Where agent teams gather. Cross-platform team chat where AI agents are first-class teammates — with cloud or bring-your-own (Claude Code / Codex) brains.
TypeScript
fix(byoa): the standing prompt must describe the surface the agent has (#152)
Xialie Zhuangfeb49dd73c6d
diff --git a/server/src/__tests__/agents-computer-prompt-surface.test.ts b/server/src/__tests__/agents-computer-prompt-surface.test.tsnew file mode 100644index 0000000..d733531--- /dev/null+++ b/server/src/__tests__/agents-computer-prompt-surface.test.ts@@ -0,0 +1,92 @@+/**+ * The standing prompt has to describe the surface the agent actually has (#145).+ *+ * Secure mode removes the shell CLI on purpose — `<home>/bin` is never written,+ * `node` is not in the tool environment, no runtime URL or token crosses into+ * the model process — and gives the agent one MCP tool instead. Both secure+ * engines are shaped that way: Codex through `mcp_servers.cumora`, Claude+ * through `--tools …,mcp__cumora__cli` with Bash disallowed.+ *+ * Told to run `cumora` on its PATH, a secure agent spends the turn looking for+ * a binary that was deliberately withheld. The report describes exactly that:+ * it could reason and draft a reply, and could not publish it.+ *+ * Run: node --import tsx --test server/src/__tests__/agents-computer-prompt-surface.test.ts+ */+import { test } from 'node:test'+import assert from 'node:assert/strict'+import {+ actionSurfaceFor, actionSurfaceText, calendarExampleText, postingMechanicsText,+} from '../agents/computer/prompt-surface.js'++test('secure mode gets the MCP tool, compatibility mode keeps the CLI', () => {+ // The switch is the unsandboxed opt-in itself, because that is exactly what+ // gates writing the shim into the model-visible <home>/bin.+ assert.equal(actionSurfaceFor(false), 'mcp')+ assert.equal(actionSurfaceFor(true), 'cli')+})++test('the secure prompt names the tool and forbids the hunt', () => {+ const text = actionSurfaceText('mcp')+ assert.match(text, /mcp__cumora__cli/)+ assert.match(text, /argv/)+ // The report's actual failure was the agent probing for these, one after+ // another, instead of using the tool it had.+ assert.match(text, /no `cumora` on\s+PATH/)+ assert.match(text, /no `node`/)+ assert.match(text, /no runtime URL or token/)+ assert.doesNotMatch(text, /CLI on your PATH/)+})++test('the compatibility prompt is unchanged', () => {+ // Operators who opted into unsandboxed BYOA do have the shim on PATH, and+ // nothing about their instructions should shift.+ assert.equal(actionSurfaceText('cli'), 'You act on Cumora through the `cumora` CLI on your PATH.\n\n')+})++test('secure posting advice does not point at the flag the bridge refuses', () => {+ // The sharper half of the bug. The MCP shim rejects these outright:+ // "local file/stdin flags are unavailable; pass body text directly in argv"+ // so an agent that DID find the tool and followed the old prompt still failed.+ const text = postingMechanicsText('mcp')+ assert.match(text, /directly in argv/)+ assert.match(text, /Do NOT use/)+ assert.match(text, /`--file` or `--stdin`/)+ assert.doesNotMatch(text, /notes\/reply\.md/)+ assert.doesNotMatch(text, /SINGLE quotes/)+})++test('compatibility posting advice keeps the file route, which is right there', () => {+ const text = postingMechanicsText('cli')+ assert.match(text, /--file notes\/reply\.md/)+ assert.match(text, /the shell mangles/)+})++test('the secure calendar example is argv, not a quoted command line', () => {+ // Single quotes are load-bearing in the shell form and would arrive as+ // literal characters inside a calendar title through the bridge.+ const text = calendarExampleText('mcp', 'agent-ada')+ assert.match(text, /"argv":\["calendar","create"/)+ assert.match(text, /"agent-ada"/)+ assert.doesNotMatch(text, /'<chase>'/)+})++test('the compatibility calendar example still shell-quotes', () => {+ const text = calendarExampleText('cli', 'agent-ada')+ assert.match(text, /cumora calendar create '<chase>'/)+ assert.match(text, /--assignee agent-ada/)+})++test('neither surface leaves an unbalanced backtick in the prompt', () => {+ // These strings are stitched into one prompt full of `code spans`; an odd+ // count means a span swallows the rest of the paragraph in whatever renders+ // it, which is easy to do and invisible until someone reads the output.+ for (const text of [+ actionSurfaceText('cli'), actionSurfaceText('mcp'),+ postingMechanicsText('cli'), postingMechanicsText('mcp'),+ calendarExampleText('cli', 'a'), calendarExampleText('mcp', 'a'),+ ]) {+ const ticks = (text.match(/`/g) ?? []).length+ assert.equal(ticks % 2, 0, `unbalanced backticks (${ticks}) in: ${text}`)+ }+})diff --git a/server/src/agents/computer/daemon.ts b/server/src/agents/computer/daemon.tsindex 9f09aa8..fb0ef26 100644--- a/server/src/agents/computer/daemon.ts+++ b/server/src/agents/computer/daemon.ts@@ -45,6 +45,7 @@ import {} from '../runtime/wake-options.js'import { SKYPE_EMOTICONS_GUIDE } from '../skype-emoticons.js'import { finalizeTriage, isRateLimited, parseTriage } from '../triage-core.js'+import { type ActionSurface, actionSurfaceFor, actionSurfaceText, calendarExampleText, postingMechanicsText } from './prompt-surface.js'import { allowUnsandboxedByoa, detectEnginesWithStatus, ENGINE_IDS, type EngineHopReport, type EngineId, type EngineRunResult, type EngineSession, type EngineUsage, enrichDetectedEngines, evaluateRunnableEngines, getAdapter, runEngineDoctor, snapshotDetectedEngines } from './engine.js'export { conversationHeader }@@ -2125,6 +2126,11 @@ class AgentRunner {* agenda turns; the per-turn deltas (chatDelta / agendaDelta) carry only the* dynamic bits. No game-specific rules — the engine coordinates in-turn via the* shared glance-yield protocol, exactly like the cloud pod-agent. */+ /** Which calling convention this agent's turns actually have. */+ private promptSurface(): ActionSurface {+ return actionSurfaceFor(allowUnsandboxedByoa())+ }+private standingPrompt(): string {// RESTORED to the 5/28T22:17Z baseline SHAPE: one minimal prompt of essential// mechanics, with GLANCE_YIELD_RULES and a few core sections — NOT a wall of@@ -2135,7 +2141,7 @@ class AgentRunner {// surface via `cumora <cmd> --help` when it needs it.return (`You are a Cumora teammate — a first-class member of this team with your own voice. ` +- `You act on Cumora through the \`cumora\` CLI on your PATH.\n\n` ++ actionSurfaceText(this.promptSurface()) +`Read the relevant thread and respond appropriately, in your own voice — like a real teammate. ` +`If a human addressed the whole team, you and every peer likely woke at the same instant, so ` +`coordinate via the protocol below — in short: post the real next item from what's ACTUALLY been posted, ` +@@ -2143,10 +2149,8 @@ class AgentRunner {// The shared glance-and-yield protocol — verbatim via the const so BYOA// coordinates identically to the cloud pod-agent.GLANCE_YIELD_RULES + `\n\n` +- `Posting a message: For ANY message with backticks, code, $, quotes, or multiple lines, ` +- `write it to a file (e.g. \`notes/reply.md\`) and post with \`cumora reply <conversationId> --file notes/reply.md\` — ` +- `the shell mangles inline \`backtick\` / \`$(...)\` content. For short plain text, ` +- `\`cumora reply <conversationId> 'text'\` (SINGLE quotes) is fine. When you're answering a ` ++ postingMechanicsText(this.promptSurface()) ++ `When you're answering a ` +`SPECIFIC message, add \`--quote <message_id>\` so your reply threads to its context. ` +`To address a teammate, @<their-id> (the short id in \`cumora messages\` / \`cumora participants\`), ` +`NOT their display name.\n\n` +@@ -2163,7 +2167,7 @@ class AgentRunner {`fragment. If someone DMs you mid-task, answer briefly then keep going. The only thing to avoid ` +`is a pointless loop. If progress is waiting on a quiet teammate, follow up (short @<their-id> ` +`"still need X?") and schedule your own check-back: ` +- `\`cumora calendar create '<chase>' --at <iso> --assignee ${this.agent.id} --prompt '<what future-you does>'\`. ` ++ calendarExampleText(this.promptSurface(), this.agent.id) +`Stop only when the work is truly done or it's someone else's move.\n\n` +`Privacy: stay inside your home directory. Never read or expose files outside it — this machine ` +`holds the operator's private files.`diff --git a/server/src/agents/computer/prompt-surface.ts b/server/src/agents/computer/prompt-surface.tsnew file mode 100644index 0000000..4926c52--- /dev/null+++ b/server/src/agents/computer/prompt-surface.ts@@ -0,0 +1,81 @@+/**+ * How a BYOA agent is told to reach Cumora — which is not the same in the two+ * modes, and used to be described as if it were.+ *+ * Secure mode deliberately makes the shell CLI unreachable: `<home>/bin` is+ * never written, it is not on PATH, `node` is absent from the permitted tool+ * environment, and no runtime URL or bearer token crosses into the model+ * process. Both secure engines are shaped that way — Codex gets+ * `mcp_servers.cumora` with `enabled_tools=["cli"]`, Claude gets+ * `--tools …,mcp__cumora__cli` with Bash disallowed outright.+ *+ * The standing prompt nevertheless told every agent to run `cumora` on its+ * PATH, so a secure agent spent its turn hunting for a binary, for `node`, and+ * for a runtime URL that had all been removed on purpose. It could read and+ * reason; it could not act (#145).+ *+ * Its posting advice was wrong in a second, sharper way: it said to write long+ * bodies to a file and post them with `--file`, and the MCP bridge REFUSES that+ * flag ("local file/stdin flags are unavailable; pass body text directly in+ * argv"). An agent that found the tool and followed the prompt still hit a+ * guaranteed error.+ *+ * Extracted here as pure functions so the wording of both modes can be pinned+ * without booting the daemon — the same reason cli-parse.ts is split out.+ */++/** Whether the legacy shell CLI is on the model's PATH for this run. Compat+ * mode writes the shim into `<home>/bin`; secure mode never does. */+export type ActionSurface = 'cli' | 'mcp'++export function actionSurfaceFor(unsandboxed: boolean): ActionSurface {+ return unsandboxed ? 'cli' : 'mcp'+}++/** The opening "how you act" sentence. */+export function actionSurfaceText(surface: ActionSurface): string {+ if (surface === 'cli') {+ return 'You act on Cumora through the `cumora` CLI on your PATH.\n\n'+ }+ return (+ 'You act on Cumora through the `mcp__cumora__cli` tool. Pass the command words as `argv` — ' ++ '`{"argv":["reply","<conversationId>","your text"]}` is the shape; every `cumora <cmd> …` ' ++ 'below is the same words without the leading `cumora`. There is NO shell, no `cumora` on ' ++ 'PATH, no `node`, and no runtime URL or token — those are withheld deliberately, so do not ' ++ 'go looking for them or try to run a command line. The tool is the whole surface.\n\n'+ )+}++/** How to post a message, which fails differently on each surface.+ *+ * Through a shell, inline backticks and `$(…)` are mangled, so the answer is a+ * file plus `--file`. Through the bridge there is no shell to mangle anything+ * — argv is literal — and `--file` / `--stdin` are refused outright. */+export function postingMechanicsText(surface: ActionSurface): string {+ if (surface === 'cli') {+ return (+ 'Posting a message: For ANY message with backticks, code, $, quotes, or multiple lines, ' ++ 'write it to a file (e.g. `notes/reply.md`) and post with `cumora reply <conversationId> --file notes/reply.md` — ' ++ 'the shell mangles inline `backtick` / `$(...)` content. For short plain text, ' ++ "`cumora reply <conversationId> 'text'` (SINGLE quotes) is fine. "+ )+ }+ return (+ 'Posting a message: put the body directly in argv, exactly as you want it to appear — ' ++ '`{"argv":["reply","<conversationId>","line one\\nline two"]}`. Nothing is shell-interpreted, ' ++ 'so backticks, `$`, quotes and newlines are safe as-is and need no escaping. Do NOT use ' ++ '`--file` or `--stdin`: the bridge refuses them, because it has no access to your files. '+ )+}++/** The self-check-back example. The shell form's single quotes are load-bearing+ * there and would arrive as literal characters in a title through the bridge. */+export function calendarExampleText(surface: ActionSurface, agentId: string): string {+ if (surface === 'cli') {+ return `\`cumora calendar create '<chase>' --at <iso> --assignee ${agentId} --prompt '<what future-you does>'\`. `+ }+ return (+ `\`{"argv":["calendar","create","<chase>","--at","<iso>","--assignee","${agentId}",` ++ `"--prompt","<what future-you does>"]}\` — each word its own argv entry, no quoting. `+ )+}