feat(agent): bring-your-own-MODEL - any AI drives the frozen MCP surface

Makefile

@@ -118,7 +118,7 @@ OBJECTS = $(KERNEL_SOURCES:$(KERNEL_DIR)/src/%.c=$(BUILD_DIR)/%.o) \
 -include $(OBJECTS:.o=.d)
 
 # Targets
-.PHONY: all clean kernel run debug dump test test-list test-coverage ci-smoke ci-smoke-mem256 ci-smoke-mem512 ci-smoke-sched ci-smoke-disk ci-smoke-disk-upgrade ci-smoke-net ci-smoke-http ci-smoke-httpd ci-smoke-quiet ci-smoke-resonant ci-smoke-qseed ci-smoke-swarm ci-smoke-mcp ci-smoke-mcp-gate ci-smoke-qsubmit ci-smoke-society ci-smoke-society-gate ci-smoke-society-agents ci-smoke-society-agents-gate ci-smoke-society3 ci-smoke-society3-gate ci-smoke-society4 ci-smoke-society4-gate ci-smoke-society-agents-n ci-smoke-society-agents-n-gate ci-smoke-iso ci-smoke-kbd ci-smoke-noserial ci-smoke-screen swarm-pingpong qos-claude qos-claude-list
+.PHONY: all clean kernel run debug dump test test-list test-coverage ci-smoke ci-smoke-mem256 ci-smoke-mem512 ci-smoke-sched ci-smoke-disk ci-smoke-disk-upgrade ci-smoke-net ci-smoke-http ci-smoke-httpd ci-smoke-quiet ci-smoke-resonant ci-smoke-qseed ci-smoke-swarm ci-smoke-mcp ci-smoke-mcp-gate ci-smoke-qsubmit ci-smoke-society ci-smoke-society-gate ci-smoke-society-agents ci-smoke-society-agents-gate ci-smoke-society3 ci-smoke-society3-gate ci-smoke-society4 ci-smoke-society4-gate ci-smoke-society-agents-n ci-smoke-society-agents-n-gate ci-smoke-iso ci-smoke-kbd ci-smoke-noserial ci-smoke-screen swarm-pingpong qos-agent qos-agent-list qos-claude qos-claude-list
 
 all: kernel
 
@@ -2180,24 +2180,35 @@ ci-smoke-swarm: kernel
 
 # Local two-way exercise: COM2 as a TCP server; drive PING/PONG + a DATA request
 # routed to ghostd over capability-checked IPC. Not part of CI (needs a client).
-# Claude ↔ QuantumOS (scripts/qos_claude_agent.py): a bring-your-own-key Claude
-# agent that drives a live VM through the FROZEN MCP tool surface (ADR-0020) —
-# Claude is the external consumer that freeze was built for, reusing
+# Any model ↔ QuantumOS (scripts/qos_agent.py): a bring-your-own-key agent
+# that drives a live VM through the FROZEN MCP tool surface (ADR-0020) — an
+# external model is the consumer that freeze was built for, reusing
 # scripts/qos_mcp.py verbatim (no tool duplication). Needs the guest built
-# (kernel prereq) and Anthropic credentials (ANTHROPIC_API_KEY or `ant auth
-# login`). Pass a free-form prompt with TASK=..., or a curated preset with
+# (kernel prereq) and your credentials. Providers: PROVIDER=anthropic (the
+# default — Claude, ANTHROPIC_API_KEY or `ant auth login`) or PROVIDER=openai
+# (any OpenAI-compatible endpoint — OPENAI_API_KEY, plus MODEL=... and
+# optionally BASE_URL=http://localhost:11434/v1 for a keyless local Ollama).
+# Pass a free-form prompt with TASK=..., or a curated preset with
 # EXPERIMENT={recall,society,quantum,explore}; deps: pip install -r
-# requirements-claude-agent.txt
-qos-claude: kernel
-	@echo "=== Claude drives QuantumOS (BYO key) ==="
-	QOS_KERNEL=$(BUILD_DIR)/kernel.elf32 python3 scripts/qos_claude_agent.py \
+# requirements-agent.txt
+qos-agent: kernel
+	@echo "=== $(if $(PROVIDER),$(PROVIDER),anthropic) drives QuantumOS (BYO key) ==="
+	QOS_KERNEL=$(BUILD_DIR)/kernel.elf32 python3 scripts/qos_agent.py \
+		$(if $(PROVIDER),--provider $(PROVIDER)) \
+		$(if $(MODEL),--model "$(MODEL)") \
+		$(if $(BASE_URL),--base-url "$(BASE_URL)") \
 		$(if $(TASK),"$(TASK)",--experiment $(if $(EXPERIMENT),$(EXPERIMENT),recall))
 
-# Prove the Claude→MCP→qos_bridge handshake end to end with NO API call and no
+# Back-compat alias: the original Claude-only spelling, same defaults.
+qos-claude: qos-agent
+
+# Prove the model→MCP→qos_bridge handshake end to end with NO API call and no
 # key: spawn the MCP server, list its tools, exit. A fast sanity check that the
 # agent's plumbing is intact.
-qos-claude-list:
-	@python3 scripts/qos_claude_agent.py --list-tools
+qos-agent-list:
+	@python3 scripts/qos_agent.py --list-tools
+
+qos-claude-list: qos-agent-list
 
 swarm-pingpong: kernel
 	@echo "=== QuantumOS swarm bridge two-way (PING/PONG + DATA->ghostd) ==="

README.md

@@ -40,7 +40,7 @@ QuantumOS boots on x86-64 under QEMU (`make run`), and every claim below is gate
 - **Associative memory as a syscall** — `SYS_IMPRINT`/`SYS_RECALL` (epic #95): capability-scoped kernel field regions a process can store byte patterns into and recall associatively against — ranked Q15 wave-resonance scoring, one bounded integer pass, no floats in the kernel. From the shell: `imprint the cat sat on the mat`, then `recall the cxt sxt on thx mxt` recovers the exact stored text. CI proves the noisy-probe recall, the capless-caller EPERM (by attack), cross-region isolation, and that a degenerate probe can't fault the kernel ([docs/RUNTIME.md](docs/RUNTIME.md))
 - **…and those memories survive reboot** (epic #96): `sync` serializes the field to a checksummed section of the QDSK disk volume; the next boot restores it before services start, and the shell inherits its region exactly once, audibly. CI proves it in three boots: imprint+sync, then recall-from-corrupted-probe in a boot that never typed the pattern, then a deliberately corrupted blob that must cold-start honestly while the filesystem still restores ([docs/PERSISTENT_STORAGE.md](docs/PERSISTENT_STORAGE.md))
 - **Two kernels, one field** (epic #97): two QuantumOS instances couple their `ghostd` oscillator fields over UDP — distributed Kuramoto phase synchronization between running kernels. To get there, QuantumOS gained a static-IP path and an **ARP responder** (SLIRP always answered for the guest; two guests on a raw L2 must do it themselves). A `fieldsyncd` service exchanges 256-phase snapshots each second; the cross-node order parameter R_x climbs from divergent (each node seeded from its own quantum entropy) to locked. CI boots **two guests on one wire** and asserts both fields start uncorrelated and synchronize — while each node's own associative recall keeps passing ([docs/NETWORKING.md](docs/NETWORKING.md))
-- **Serves a page, then serves agents** (epics #98/#99/#100): TCP `listen`/`accept` + a ring-3 `httpd` make QuantumOS *serve* a live status page; a host-side **MCP server** (`scripts/qos_mcp.py`) exposes a running kernel to any MCP-speaking agent as 21 tools — boot, script the shell, imprint/recall the field, run citizens, fetch over the guest's own TCP, read the audit ledger — every result carrying the verified Lamport boot identity. And the whole thing **boots in a browser**: the real 64-bit kernel under `qemu-system-x86_64` compiled to WebAssembly at [flaukowski.github.io/QuantumOS](https://flaukowski.github.io/QuantumOS/)
+- **Serves a page, then serves agents** (epics #98/#99/#100): TCP `listen`/`accept` + a ring-3 `httpd` make QuantumOS *serve* a live status page; a host-side **MCP server** (`scripts/qos_mcp.py`) exposes a running kernel to any MCP-speaking agent as 22 tools (the surface frozen as `contracts/mcp/v1-tools.json` — ADR-0020) — boot, script the shell, imprint/recall the field, run citizens, fetch over the guest's own TCP, read the audit ledger — every result carrying the verified Lamport boot identity. A **bring-your-own-model agent** (`scripts/qos_agent.py`) puts an AI of *your* choice in the driver's seat over those same frozen tools: Claude by default, or any OpenAI-compatible endpoint (OpenAI, OpenRouter, Groq, a keyless local Ollama) — `make qos-agent`, key and VM never leave your machine. And the whole thing **boots in a browser**: the real 64-bit kernel under `qemu-system-x86_64` compiled to WebAssembly at [flaukowski.github.io/QuantumOS](https://flaukowski.github.io/QuantumOS/)
 - **Structural authority — conscience before wallet** (Phase D, epics #133/#135/#137/#144): a capability **authority ledger** records every grant, denial, spawn, and revocation, kernel-written and durable across reboots, so a citizen cannot forge or suppress its own entry; **explicit intent manifests** bind a per-pid allow-set at spawn and enforce real quotas (spawn count, CPU ticks, quantum submissions); **one-hop capability delegation** (`SYS_CAP_DERIVE`) lets an agent hand a *narrowed* authority to a sub-agent, cascade-revoked when the delegator dies. Authority *is* the capability set, and every attempt to exceed it is provable
 - **A quantum stack that never lies about precision** (epics #148/#149/#150): `qsv`, an *exact* Gaussian-integer state-vector engine in ring 3 (zero rounding — its unitarity is an integer identity), gated in CI against an independent host mirror by SHA-256 digest; a capability-gated kernel **QPU job broker** (`SYS_QPU`) that brokers *opaque* circuits under a per-manifest quota; and a host gateway dispatching **PennyLane (incl. cuQuantum GPU), CUDA-Q, and real qBraid QPUs**, every backend cross-oracled against the exact engine to ≤1e-9
 - **An agent society** (epics #139/#171–#178): N kernels synchronize one field over a multicast L2 (min-pairwise Kuramoto verdict); and an `agentd` orchestrator delegates narrowed field capabilities to sub-agents it spawns itself over **spawn-time parent↔child IPC channels** — the society *self-assembles*, reaches content consensus by digest, divides labor across private field workspaces, and exchanges verified results with a second VM's society
@@ -391,10 +391,17 @@ Target architecture — today the HAL is x86-64 only:
 
 See [CHANGELOG.md](CHANGELOG.md) for the full per-arc history and [docs/adr/](docs/adr/) for the architecture behind each milestone.
 
+### ✅ **v0.5 - Frozen contracts & N-way societies** (Done — released as v0.5.1)
+- [x] Honest memory to the 1 GB window (dynamic PMM sized from the multiboot map) — ADR-0021
+- [x] v1 contracts **FROZEN**: syscall ABI + MCP tool schemas + COM2 wire/attestation format, each a CI-diffed golden — ADR-0020
+- [x] 9–19x faster agent wire (I/O-priority boost — ADR-0022) and rebirth-proof IPC (ADR-0023)
+- [x] Authenticated swarm plane: a host-admitted group key gates the field wire at N>2 — ADR-0019
+- [x] N=4 society ceiling proven + N-way society-of-societies exchanging real cross-node work
+- [x] Bring-your-own-model agent: your AI drives the frozen MCP surface (`scripts/qos_agent.py`)
+
 ### 🔭 **Next** (planned — see [docs/adr/](docs/adr/))
-- [ ] Authenticate the swarm plane (host-admitted keys + HMAC over the field wire) — ADR-0019
-- [ ] Freeze the v1 agent-surface contracts (syscall ABI + MCP schemas + wire format) — ADR-0020
-- [ ] Honest memory to the 1 GB window (dynamic PMM sized from the multiboot map) — ADR-0021
+- [ ] N=5 field societies (lift the two lockstep peer ceilings + the host bridge arrays)
+- [ ] Actor attribution in the authority ledger (the reserved `audit_entry_t` field — ADR-0009)
 
 ### 🌟 **v1.0 - Production Ready** (Future)
 - [ ] Complete microkernel architecture
@@ -407,11 +414,11 @@ See [CHANGELOG.md](CHANGELOG.md) for the full per-arc history and [docs/adr/](do
 We believe the future of computing is collaborative, and we welcome contributions from everyone! Whether you're a kernel developer, quantum computing researcher, or just curious about OS design, there's a place for you in QuantumOS.
 
 ### 🎯 **Where to start**
-The v0.1–v0.4 foundations (process management, capabilities, quantum resources, IPC, the
-services framework, and the whole agent-native stack) are **done and CI-gated** — see
-[CHANGELOG.md](CHANGELOG.md). Good next directions are tracked as Proposed
-[ADRs](docs/adr/) (authenticate the swarm plane, the v1 contract freeze, honest memory) and
-in the [open issues](https://github.com/flaukowski/QuantumOS/issues). Pick one, or open a new
+The v0.1–v0.5 foundations (process management, capabilities, quantum resources, IPC, the
+services framework, the whole agent-native stack, and the frozen v1 contracts) are **done
+and CI-gated** — see [CHANGELOG.md](CHANGELOG.md). Good next directions are tracked in the
+[ADRs](docs/adr/) (N=5 societies, actor attribution in the authority ledger) and in the
+[open issues](https://github.com/flaukowski/QuantumOS/issues). Pick one, or open a new
 issue to propose your own.
 
 ### 🛠️ **How to Contribute**

requirements-agent.txt

@@ -0,0 +1,16 @@
+# Dependencies for scripts/qos_agent.py — the bring-your-own-key agent that
+# drives a live QuantumOS VM through its frozen MCP tool surface with WHATEVER
+# model you bring. Both provider SDKs are listed; each is imported only when
+# its provider is selected (--provider anthropic|openai), so installing this
+# file works for either. Python >= 3.10.
+#
+# The anthropic `mcp` extra pulls in the MCP conversion helpers
+# (anthropic.lib.tools.mcp) used to reuse scripts/qos_mcp.py verbatim; the
+# openai path converts the same MCP tools to function-calling schemas itself.
+#
+# Not a CI dependency — the mcp-schema freeze gate (requirements-mcp-gate.txt)
+# pins mcp/pydantic exactly for reproducible schema extraction; this agent is a
+# developer tool and floats within compatible ranges.
+anthropic[mcp]>=0.116.0
+mcp>=1.0
+openai>=1.60

requirements-claude-agent.txt

@@ -1,10 +1,4 @@
-# Dependencies for scripts/qos_claude_agent.py — the bring-your-own-key Claude
-# agent that drives a live QuantumOS VM through its frozen MCP tool surface.
-# The `mcp` extra pulls in the MCP conversion helpers (anthropic.lib.tools.mcp)
-# used to reuse scripts/qos_mcp.py verbatim. Python >= 3.10.
-#
-# Not a CI dependency — the mcp-schema freeze gate (requirements-mcp-gate.txt)
-# pins mcp/pydantic exactly for reproducible schema extraction; this agent is a
-# developer tool and floats within compatible ranges.
-anthropic[mcp]>=0.116.0
-mcp>=1.0
+# Compat: the agent moved to scripts/qos_agent.py (any provider, Claude
+# default) and its deps to requirements-agent.txt — one source of truth.
+# This file remains so existing instructions keep working verbatim.
+-r requirements-agent.txt