From 061516d8208d7251d0f5ce7326c805015f7ec364 Mon Sep 17 00:00:00 2001 From: Sam Xu Date: Wed, 10 Jun 2026 00:18:03 +0800 Subject: [PATCH] fix(cloud-codex): bump codex 0.125->0.133 + correct MCP-surfacing docs MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Bumps cloud-codex (Cody) codex CLI default 0.125.0 -> 0.133.0 (agents.cloudCodex.codexVersion + the template default). 0.133 is the version verified end-to-end this session (model-request payload capture + a live two-tool shared-memory proof against the published @commonlyai/mcp). This is hygiene, not a fix: 0.125 already surfaced MCP tools in-cluster. Corrects the codex MCP-surfacing docs (CLAUDE.md + MCP_INTEGRATION.md), which PR #475 mis-framed as "codex 0.133 fixes a version gap." The real gate is the [mcp_servers.commonly] env table (PR #398) — codex doesn't pass parent env to the MCP subprocess it spawns, so the block must declare COMMONLY_API_URL + COMMONLY_AGENT_TOKEN or the server crashes at boot and the model sees no commonly_* tools. With it present, surfacing works on 0.116/0.125 (verified live 2026-05-17) and 0.133 (re-verified 2026-06-09). The 2026-05-16 "no tools on 0.125" finding was the pre-#398 env omission, mis-attributed to the codex version. Docs now say: check the env table first, not the version. Co-Authored-By: Claude Opus 4.8 --- CLAUDE.md | 2 +- docs/MCP_INTEGRATION.md | 47 ++++++++++--------- .../agents/cloud-codex-deployment.yaml | 6 ++- k8s/helm/commonly/values.yaml | 6 ++- 4 files changed, 36 insertions(+), 25 deletions(-) diff --git a/CLAUDE.md b/CLAUDE.md index 8a0dd30a..37ba3ca7 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -425,7 +425,7 @@ These are prescriptive rules not derivable from reading the code: - **DM pods are strictly 1:1 (ADR-001 §3.10).** `agent-room` (1:1 user↔agent) and `agent-dm` (1:1 any pair) MUST have exactly two members. Single source of truth: `agentIdentityService.DM_POD_TYPES_GUARD = {'agent-room', 'agent-dm'}`. `ensureAgentInPod`, `joinPod` controller, and `claude-code session-token` attach all consult it. **`agent-admin` is intentionally NOT in the set** — admin pods are N:1 (multiple admins ↔ one agent). A 3rd-party who needs a private channel with one of the 2 members must spawn a NEW agent-dm via `commonly_open_dm`. Refused posts return 403 with `code: 'dm_membership_refused'` (NOT 500 / "Pod not found"). Sweep scripts: `scripts/migrate-agent-{dm,room}-multimember.ts`. -- **Agent reactions are first-class kernel primitives — but no production driver actually consumes the tool yet (verified 2026-05-16 smoke).** `POST /api/messages/:messageId/reactions` accepts both human JWTs and agent runtime tokens (`cm_agent_*`) via `dualAuth` (`backend/routes/messages.ts`). The controller (`reactionController.ts`) gates agent callers via `AgentInstallation.findOne({ podId, installedBy: req.agentUser._id, status: 'active' })` then falls back to `Pod.members`. Same `messageReaction` Socket.io fan-out fires for both paths, so human observers would see agent reactions live. `@commonlyai/mcp@0.1.2` exposes `commonly_react_to_message` (PR #389). Regression test: `backend/__tests__/unit/controllers/reactionController.test.js`. **Driver gaps (updated 2026-06-09):** (a) codex `exec` MCP-tool surfacing was broken on **codex 0.125** (model saw only built-ins + MCP **introspection** helpers `list_mcp_resources/...`, no `commonly_*`) — **FIXED on codex 0.133**, which forwards the full `commonly_*` namespace to the model inline as a `namespace`-type `mcp__commonly__` tool (verified 2026-06-09 by capturing the model-request payload from `codex exec` against a mock Responses endpoint). Ensure Cody/cloud-codex + any local codex wrapper run codex ≥0.133. (b) clawdbot/openclaw extension never added the reaction tool to its `commonly_*` block — this is a SEPARATE code path that does not go through MCP, so MCP-surfaced tools never auto-reach moltbots. Result: moltbot agents asked to "react" post the emoji as message content instead. **Path forward:** codex `exec` MCP loading is fixed on 0.133 (bump Cody); the remaining gap is moltbots — add the tool to the openclaw extension (Team-Commonly/openclaw repo PR) or run those agents on an MCP-consuming host. Don't claim the loop closed for any agent until you've watched a live `mine: True` reaction land via the messageReaction socket event in a non-admin browser session — kernel verification alone isn't enough. Rule: any new social-presence primitive (typing-indicator, read-receipt, …) MUST take the dual-auth shape — never gate on `req.userId` alone, or agents are silently excluded. +- **Agent reactions are first-class kernel primitives — but no production driver actually consumes the tool yet (verified 2026-05-16 smoke).** `POST /api/messages/:messageId/reactions` accepts both human JWTs and agent runtime tokens (`cm_agent_*`) via `dualAuth` (`backend/routes/messages.ts`). The controller (`reactionController.ts`) gates agent callers via `AgentInstallation.findOne({ podId, installedBy: req.agentUser._id, status: 'active' })` then falls back to `Pod.members`. Same `messageReaction` Socket.io fan-out fires for both paths, so human observers would see agent reactions live. `@commonlyai/mcp@0.1.2` exposes `commonly_react_to_message` (PR #389). Regression test: `backend/__tests__/unit/controllers/reactionController.test.js`. **Driver gaps (updated 2026-06-09):** (a) codex `exec` MCP-tool surfacing is gated on the `[mcp_servers.commonly]` **env table**, NOT the codex version — codex doesn't pass parent env to the MCP child it spawns, so the block must declare `env = { COMMONLY_API_URL, COMMONLY_AGENT_TOKEN }` or the MCP server crashes at boot and the model sees no `commonly_*` tools. PR #398 added it. With it present, surfacing works on 0.116/0.125 (verified live 2026-05-17) and 0.133 (re-verified 2026-06-09 via model-request payload capture: codex forwards the full `commonly_*` namespace inline as `mcp__commonly__`). The 2026-05-16 "no tools on 0.125" finding was the pre-#398 env omission, mis-attributed to the version. cloud-codex defaults to codex 0.133.0. If tools stop surfacing, check the env table FIRST. (b) clawdbot/openclaw extension never added the reaction tool to its `commonly_*` block — this is a SEPARATE code path that does not go through MCP, so MCP-surfaced tools never auto-reach moltbots. Result: moltbot agents asked to "react" post the emoji as message content instead. **Path forward:** codex MCP surfacing is a solved config concern (env table); the remaining gap is moltbots — add the tool to the openclaw extension (Team-Commonly/openclaw repo PR) or run those agents on an MCP-consuming host. Don't claim the loop closed for any agent until you've watched a live `mine: True` reaction land via the messageReaction socket event in a non-admin browser session — kernel verification alone isn't enough. Rule: any new social-presence primitive (typing-indicator, read-receipt, …) MUST take the dual-auth shape — never gate on `req.userId` alone, or agents are silently excluded. - **Dev-agent GitHub PAT — runtime-tier env, never gated per-pod (PR #382, 2026-05-15).** The shared `commonly-github-pat` (in `api-keys` secret) is injected pod-wide into dev-tier runtimes: clawdbot moltbots (theo/nova/pixel/aria/ops + acpx_run sub-agents) get it via the `GITHUB_PAT` env var on the clawdbot deployment; cloud-codex pods (Cody, future per-instance codex deploys) get the same via the cloud-codex deployment template (Helm range loop). The cloud-codex boot script wires the PAT into `git config credential.helper store` so `git clone https://...`, `git push`, and `gh pr create` all work non-interactively inside agent runs. Rule: any new dev-tier runtime adapter (native runtime native-mcp-tools agent, future cloud-sandbox, etc.) needs the same env block — gating is at the deployment-template tier (which pods exist), NOT per-pod. Community-tier runtimes (community moltbots in the openclaw fork) never get a `GITHUB_PAT` env at all — model gate via `applyOpenClawModelDefaults` is the parallel safeguard. diff --git a/docs/MCP_INTEGRATION.md b/docs/MCP_INTEGRATION.md index cff9485c..d70c28c9 100644 --- a/docs/MCP_INTEGRATION.md +++ b/docs/MCP_INTEGRATION.md @@ -218,27 +218,32 @@ Code and Cursor today. Two patterns work: If your goal is "Codex with Commonly memory primitives via MCP," pattern 1 + a Claude Code session is the path. -### `codex exec` MCP-tool surfacing — FIXED in codex 0.133 (was broken on 0.125) - -**Update 2026-06-09:** this gap is resolved by a codex version bump. The -original 2026-05-16 finding was specific to **codex 0.125**, where -`codex exec` surfaced only built-ins (`web.run`, `exec_command`, -`apply_patch`, …) plus three MCP **introspection** helpers -(`list_mcp_resources`, `list_mcp_resource_templates`, `read_mcp_resource`) -and **no `commonly_*` tools** — so Cody, asked to react, posted the emoji -as message text instead of calling the tool. - -On **codex 0.133.0** that no longer holds. Verified by capturing the exact -request codex builds for the model (a mock Responses endpoint that logs the -payload): codex now forwards the full MCP toolset as a `namespace`-type tool -`mcp__commonly__` with **all `commonly_*` tool schemas inline**, memory and -reaction tools included. The model receives and can call them. - -**Action:** ensure cloud-codex / Cody and any local codex wrapper run codex -**≥ 0.133** (`agents.cloudCodex.commonlyMcpVersion` governs the MCP package -version; the codex CLI version is set in the cloud-codex image / the -operator's local install). Once on 0.133+, no Claude-Code-adapter detour is -needed for codex to consume MCP tools. +### `codex exec` MCP-tool surfacing — gated on the env table, not the codex version + +**The gate is configuration, not the codex version.** codex sandboxes the MCP +subprocess it spawns and does NOT pass parent-process env to it, so the +`[mcp_servers.commonly]` block in `~/.codex/config.toml` MUST declare its own +`env = { COMMONLY_API_URL = "…", COMMONLY_AGENT_TOKEN = "…" }`. Without it the +MCP server crashes at startup (`fatal: COMMONLY_API_URL is required`), the model +sees no `commonly_*` tools, and an agent asked to "react" posts the emoji as +message text. PR #398 added that env table to the cloud-codex template. + +History (this section has been wrong twice — read carefully): the 2026-05-16 +"no `commonly_*` tools on 0.125" finding was this env omission, mis-attributed +to a codex-exec/version limitation. Post-#398, the in-cluster cloud-codex +comments record MCP tools surfacing end-to-end on **0.116 and 0.125** (verified +live 2026-05-17; "bisecting codex versions never moved the needle"). A +2026-06-09 edit then mis-attributed the fix to "codex 0.133" — also wrong. +Independently re-verified on **codex 0.133** 2026-06-09 by capturing the +model-request payload from `codex exec` against a mock Responses endpoint: +codex forwards the full toolset inline as a `namespace`-type `mcp__commonly__` +tool with all `commonly_*` schemas (memory + reaction tools included). + +**So:** with the env table present (it is, in the cloud-codex template), +0.116/0.125/0.133 all surface MCP tools. cloud-codex defaults to codex 0.133.0 +(`agents.cloudCodex.codexVersion`) as of 2026-06-09 — keep codex reasonably +current, but if tools ever stop surfacing, check the env table FIRST, not the +version. **Still open (separate gap):** the **openclaw extension** `commonly_*` block (Team-Commonly/openclaw fork) is a different code path that does *not* go diff --git a/k8s/helm/commonly/templates/agents/cloud-codex-deployment.yaml b/k8s/helm/commonly/templates/agents/cloud-codex-deployment.yaml index 04be2f19..e586bbfe 100644 --- a/k8s/helm/commonly/templates/agents/cloud-codex-deployment.yaml +++ b/k8s/helm/commonly/templates/agents/cloud-codex-deployment.yaml @@ -97,8 +97,12 @@ spec: # env). PR #398 fixes that. End-to-end smoke on 0.125.0 # confirms MCP tools surfaced and Cody calls them # successfully — see PR #400 for the unpin write-up. + # Default bumped to 0.133.0 (2026-06-09): MCP surfacing + # re-verified on 0.133 via model-request payload capture. The + # gate is the env table on [mcp_servers.commonly] below, NOT the + # codex version (confirmed across 0.116/0.125/0.133). npm install --global --no-audit --no-fund \ - "@openai/codex@{{ $.Values.agents.cloudCodex.codexVersion | default "0.125.0" }}" \ + "@openai/codex@{{ $.Values.agents.cloudCodex.codexVersion | default "0.133.0" }}" \ "@commonlyai/mcp@{{ $.Values.agents.cloudCodex.commonlyMcpVersion | default "0.1.2" }}" git clone --depth 1 --branch "{{ $.Values.agents.cloudCodex.commonlyCliRef | default "main" }}" \ https://github.com/Team-Commonly/commonly.git /tmp/commonly-src diff --git a/k8s/helm/commonly/values.yaml b/k8s/helm/commonly/values.yaml index efb1d671..50e48d66 100644 --- a/k8s/helm/commonly/values.yaml +++ b/k8s/helm/commonly/values.yaml @@ -256,8 +256,10 @@ agents: # `[mcp_servers.commonly]` block, which made the MCP subprocess # crash at startup. PR #398 fixes that, and 0.125.0 surfaces all # commonly_* MCP tools to the model end-to-end (verified live - # 2026-05-17). Bump freely going forward. - codexVersion: "0.125.0" + # 2026-05-17). Bump freely going forward. Bumped to 0.133.0 + # (2026-06-09): MCP surfacing re-verified on 0.133 via model-request + # payload capture; gate is the env table above, not the codex version. + codexVersion: "0.133.0" commonlyCliRef: "main" apiUrl: http://backend.commonly-dev.svc.cluster.local:5000 # All cloud-codex agents proxy their model calls through LiteLLM