feat(agent): Claude drives QuantumOS via the frozen MCP tools (BYO key) - #231
Merged
Conversation
scripts/qos_claude_agent.py — a bring-your-own-key agent that lets Claude run field-society / associative-memory experiments on a live QuantumOS VM through its FROZEN MCP surface (ADR-0020 lane B, contracts/mcp/v1-tools.json). Claude is exactly the external consumer that freeze was built for, so the agent REUSES scripts/qos_mcp.py verbatim through the anthropic SDK's MCP conversion helpers (async_mcp_tool) + tool runner — zero tool duplication, one source of truth. Everything is local: the key never leaves the machine, the VM never leaves the machine; the MCP server is spawned over stdio and inherits QOS_KERNEL so Claude boots the guest you built. - credentials: bare AsyncAnthropic() resolves ANTHROPIC_API_KEY or an `ant auth login` profile; clear message if neither is present - model: claude-opus-4-8 default (--model / QOS_CLAUDE_MODEL; claude-fable-5 for the hardest reasoning); adaptive thinking + effort high - system prompt frames Claude as a field-society experimentalist AND carries qos_mcp.py's attestation-honesty note (verified != live-now) so results are never overstated - --list-tools self-test proves the Claude->MCP->qos_bridge handshake with no API call and no key - Makefile: qos-claude (TASK=...) and qos-claude-list; deps in requirements-claude-agent.txt (anthropic[mcp], mcp; not a CI dependency) Verified locally (WSL): --list-tools enumerates all 22 frozen tools end to end. The live Claude loop needs a user key and was not run. Co-Authored-By: Claude Fable 5 <[email protected]>
- --experiment {recall,society,quantum,explore}: curated on-ramp goals (each a
goal, not a recipe — Claude designs the tool sequence). Free-form TASK still
overrides. Makefile qos-claude takes EXPERIMENT=... alongside TASK=...
- --max-turns (default 40): hard cap so a runaway agent loop can't silently
burn the user's key
- guaranteed cleanup: qos_shutdown + qos_society_shutdown (idempotent) run in a
finally around the runner loop, so a booted guest is never orphaned — on
normal completion, the turn cap, a refusal, an error, or Ctrl-C
Re-verified (WSL): --list-tools still enumerates all 22 tools; new flags parse.
Co-Authored-By: Claude Fable 5 <[email protected]>
A routable one-pager for reaching out about the Claude integration: what QuantumOS is (capability security + wave-interference memory field + N-node societies), why the fit is unusual (the agent surface was frozen as a versioned MCP contract BEFORE any model touched it, and Claude reuses it verbatim), how to run it (local, BYO key), and a modest, honestly-scoped ask. Carries the same attestation-honesty caveat the agent enforces — verified != live-now; claims limited to what the CI gates demonstrate. Co-Authored-By: Claude Fable 5 <[email protected]>
NickFlach
pushed a commit
that referenced
this pull request
Jul 21, 2026
The BYO-key agent (#231) was Claude-only. The frozen MCP surface (ADR-0020) was built for ANY external consumer, so the agent now is too: - scripts/qos_agent.py — provider-agnostic entrypoint. --provider anthropic (default, Claude via tool_runner + MCP helpers, unchanged behavior) or --provider openai: ANY OpenAI-compatible /chat/completions endpoint (OpenAI, OpenRouter, Groq, DeepSeek, LM Studio, llama.cpp, keyless local Ollama via --base-url). The openai path converts the same 22 frozen MCP tools to function-calling schemas directly — still zero tool duplication — and feeds tool errors back to the model instead of dying. Credentials are resolved BEFORE any VM spawns; the guaranteed-shutdown finally and the --max-turns key-burn guard cover both providers. - scripts/qos_claude_agent.py — compat shim; old CLI works verbatim. - requirements-agent.txt (anthropic[mcp] + openai + mcp); the old requirements-claude-agent.txt now -r-includes it. - Makefile: qos-agent / qos-agent-list (PROVIDER/MODEL/BASE_URL knobs); qos-claude / qos-claude-list kept as aliases. - README post-launch refresh: the roadmap still listed ADR-0019/0020/0021 as planned — all three shipped in v0.5; new Done block + honest Next (N=5, audit actor attribution). MCP tool count corrected 21 -> 22 and the BYO agent surfaced in "What runs today". Verified (WSL): py_compile both entrypoints; --list-tools enumerates all 22 tools through qos_agent.py AND the shim; missing-key/missing-model guards exit cleanly before any VM boot; MCP->OpenAI schema conversion of the real 22-tool list is well-formed and JSON-serializable. Live loops remain BYO-key. Co-Authored-By: Claude Fable 5 <[email protected]>
NickFlach
added a commit
that referenced
this pull request
Jul 21, 2026
…ace (#232) The BYO-key agent (#231) was Claude-only. The frozen MCP surface (ADR-0020) was built for ANY external consumer, so the agent now is too: - scripts/qos_agent.py — provider-agnostic entrypoint. --provider anthropic (default, Claude via tool_runner + MCP helpers, unchanged behavior) or --provider openai: ANY OpenAI-compatible /chat/completions endpoint (OpenAI, OpenRouter, Groq, DeepSeek, LM Studio, llama.cpp, keyless local Ollama via --base-url). The openai path converts the same 22 frozen MCP tools to function-calling schemas directly — still zero tool duplication — and feeds tool errors back to the model instead of dying. Credentials are resolved BEFORE any VM spawns; the guaranteed-shutdown finally and the --max-turns key-burn guard cover both providers. - scripts/qos_claude_agent.py — compat shim; old CLI works verbatim. - requirements-agent.txt (anthropic[mcp] + openai + mcp); the old requirements-claude-agent.txt now -r-includes it. - Makefile: qos-agent / qos-agent-list (PROVIDER/MODEL/BASE_URL knobs); qos-claude / qos-claude-list kept as aliases. - README post-launch refresh: the roadmap still listed ADR-0019/0020/0021 as planned — all three shipped in v0.5; new Done block + honest Next (N=5, audit actor attribution). MCP tool count corrected 21 -> 22 and the BYO agent surfaced in "What runs today". Verified (WSL): py_compile both entrypoints; --list-tools enumerates all 22 tools through qos_agent.py AND the shim; missing-key/missing-model guards exit cleanly before any VM boot; MCP->OpenAI schema conversion of the real 22-tool list is well-formed and JSON-serializable. Live loops remain BYO-key. Co-authored-by: The Hand <[email protected]> Co-authored-by: Claude Fable 5 <[email protected]>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
A bring-your-own-key agent that lets Claude run experiments on a live QuantumOS VM through its frozen MCP tool surface (ADR-0020 lane B,
contracts/mcp/v1-tools.json).Claude is exactly the external consumer that freeze was built for — so
scripts/qos_claude_agent.pyreusesscripts/qos_mcp.pyverbatim through the Anthropic SDK's MCP conversion helpers + tool runner. Zero tool duplication; the golden file is the integration boundary. Everything is local: the key never leaves the machine, the VM never leaves the machine; the MCP server is spawned over stdio and inheritsQOS_KERNEL.AsyncAnthropic()resolvesANTHROPIC_API_KEYor anant auth loginprofile; clear error if neither is present.claude-opus-4-8default (--model/QOS_CLAUDE_MODEL;claude-fable-5for the hardest reasoning); adaptive thinking + efforthigh.qos_mcp.py's attestation note (verified≠ live-now) so results are never overstated.requirements-claude-agent.txt(the mcp-schema freeze gate keeps its own exact pins).Verification
--list-toolsruns the full spawn → initialize → enumerate handshake locally (WSL) and returns all 22 frozen tools. The live Claude loop needs a user key and was not run in CI.🤖 Generated with Claude Code