Skip to content

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.ts
new file mode 100644
index 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.ts
index 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.ts
new file mode 100644
index 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. `
+ )
+}