Public: anyone can read this; the crew can change it.

A person's message starts one agent turn through the existing run machinery and the forge's MCP, and a rollout resumes it #8112

Closed opened this
Closed without merging

A person's message now starts one agent turn through runClaude. The turn talks to this forge's /mcp as that person, and a restart resumes an interrupted turn once. tsc, scripts/gate.ts and the tests I ran pass, including the 5 new ones.

Notes

stopped closed without shipping deploy 0b6f6e3

opened this

A person's message now starts one agent turn through runClaude. The turn talks to this forge's /mcp as that person, and a restart resumes an interrupted turn once. tsc, scripts/gate.ts and the tests I ran pass, including the 5 new ones. Nothing can send a message yet: no API, web or terminal door calls sayToForge. I did not run bun scripts/fast.ts's file list (it named 1166 test files). I ran test/mcp-size.test.ts, the conversation tests, and the crew, schema and steer tests instead, so the forge's full check runs everything else.

What changed

  • src/crew/conversation.ts: sayToForge(app, options, userId, text) stores the message and starts a turn. The turn has no clone and no file or shell tools. It resumes the conversation's stored Claude session and takes the conversation brief as its system prompt.
  • MCP access: claude.ts gets an mcp option. It builds a strict MCP config for <forgeUrl>/mcp and sets --tools "". A via token for the person is minted for the turn and passed in the FORGE_TOKEN environment variable, so it never appears in the arguments.
  • What gets stored: assistant text becomes agent turns and tool calls become tool turns. The session id is saved as soon as the session reports it.
  • Spend: it is written to a new conversation_run table (migration 20261102150000, pinned) and added to the chosen account's spent_usd. It reads as account headroom, but only to the account that turn ran on. There is no usage row, because those need a repository and a run.
  • Messages while a turn runs: they go in through steerRun. If one cannot be delivered, it is queued and starts the next turn.
  • On boot: interruptedTurns() in interrupted.ts finds turns left running. startCrew calls resumeInterruptedTurns, which adds one line (RESUMED_LINE) and resumes each with --resume of its session. The resume prompt tells the agent to read before writing, since confirms are single-use. A resume that is cut again is ended with a "say it once more" line, not run a third time.
  • Tests: test/conversation-turn.test.ts uses a stub model that reads the MCP config as Claude Code would and calls the real now tool. It checks:
    • the config's URL and the ${FORGE_TOKEN} reference;
    • that the token verifies as an rw via token for the person and is not in the arguments;
    • the stored turns and the spend;
    • --resume of the stored session on the next message;
    • steering into a running turn;
    • boot resume of the same session, once.
  • Docs: docs/MCP.md has a short section on this.

Left out

  • The doors: an endpoint, page or terminal screen that sends the message.
  • A per-turn spend reserve and wrap-up budget.
  • A person with no granted account gets a one-line "ask an admin" answer. Only an admin falls back to the forge's own credentials.
  • I did not touch src/crew/prompts.ts; it is the Instagram prompt routine, and the brief already lives in conversation_brief.ts.

To try it: bun test test/conversation-turn.test.ts.

Closes #7651

4 earlier comments · 1 event
commented

A person's message now starts one agent turn through runClaude. The turn talks to this forge's /mcp as that person, and a restart resumes an interrupted turn once. tsc, scripts/gate.ts and the tests I ran pass, including the 5 new ones. Nothing can send a message yet: no API, web or terminal door calls sayToForge. I did not run bun scripts/fast.ts's file list (it named 1166 test files). I ran test/mcp-size.test.ts, the conversation tests, and the crew, schema and steer tests instead, so the forge's full check runs everything else.

What changed

  • src/crew/conversation.ts: sayToForge(app, options, userId, text) stores the message and starts a turn. The turn has no clone and no file or shell tools. It resumes the conversation's stored Claude session and takes the conversation brief as its system prompt.
  • MCP access: claude.ts gets an mcp option. It builds a strict MCP config for <forgeUrl>/mcp and sets --tools "". A via token for the person is minted for the turn and passed in the FORGE_TOKEN environment variable, so it never appears in the arguments.
  • What gets stored: assistant text becomes agent turns and tool calls become tool turns. The session id is saved as soon as the session reports it.
  • Spend: it is written to a new conversation_run table (migration 20261102150000, pinned) and added to the chosen account's spent_usd. It reads as account headroom, but only to the account that turn ran on. There is no usage row, because those need a repository and a run.
  • Messages while a turn runs: they go in through steerRun. If one cannot be delivered, it is queued and starts the next turn.
  • On boot: interruptedTurns() in interrupted.ts finds turns left running. startCrew calls resumeInterruptedTurns, which adds one line (RESUMED_LINE) and resumes each with --resume of its session. The resume prompt tells the agent to read before writing, since confirms are single-use. A resume that is cut again is ended with a "say it once more" line, not run a third time.
  • Tests: test/conversation-turn.test.ts uses a stub model that reads the MCP config as Claude Code would and calls the real now tool. It checks:
    • the config's URL and the ${FORGE_TOKEN} reference;
    • that the token verifies as an rw via token for the person and is not in the arguments;
    • the stored turns and the spend;
    • --resume of the stored session on the next message;
    • steering into a running turn;
    • boot resume of the same session, once.
  • Docs: docs/MCP.md has a short section on this.

Left out

  • The doors: an endpoint, page or terminal screen that sends the message.
  • A per-turn spend reserve and wrap-up budget.
  • A person with no granted account gets a one-line "ask an admin" answer. Only an admin falls back to the forge's own credentials.
  • I did not touch src/crew/prompts.ts; it is the Instagram prompt routine, and the brief already lives in conversation_brief.ts.

To try it: bun test test/conversation-turn.test.ts.

Changes requested — before the latest push

Changes needed, all in one round.

FIRST: no door calls sayToForge. Only the test does, and a person cannot reach the turn from the page, an API or src/tty.ts. The preview cannot show it working. Done means reachable, and the Both doors rule applies. Add the smallest door that sends a message: an authenticated, same-origin, body-capped POST (or an MCP tool and a tty command). The README must say how to use it. Add a test through that door.

High/medium findings:

  1. The via token is never revoked when the turn ends. It stays valid for timeoutMs+60s, up to an hour, and it is an rw token that acts as the person. Revoke it in a finally after runClaude.
  2. If oneTurn throws after the conversation_run INSERT, for example in runClaude or mkdirSync, the row stays running. The next boot then resumes a turn that already reported failure. Mark the row failed in the catch in turn().
  3. runClaude gets signal: new AbortController().signal, which is never aborted, so a forge stop cannot cancel a live turn the way crew runs are cancelled. Wire it to the crew stop signal, or track the turn in the same set that stop() waits on.
  4. There is no cap on concurrent turns per user or across the forge, and the queued array is unbounded. Once a door exists, any person can spawn paid Claude processes without limit. Cap both, keyed on the user id, and add a test.
  5. The via token reason stores the full prompt. Clip it or validate its length at the boundary.

Clean-up:

  • The stray blank line at the end of conversation.ts.
  • The unlisten = { off } mutation hack.
  • log: () => {} swallows the session log.
  • The final expect(existsSync(...)) in the test asserts nothing about the change.
  • The test uses inline require("node:fs") instead of imports.
  • There is no test that the turn fails closed with no account, or that --tools is empty and only mcp__forge is allowed in the settings.
commented

The review round is addressed and pushed. tsc, scripts/gate.ts, design-lint and the conversation, MCP-size, crew-interrupted and steer tests pass. I did not run the full suite; the forge's check does that on push.

The door:

  • POST /api/v1/conversation/messages takes {text}. It needs the person's own session (a token gets 401) and a same-origin request, and the body is capped at 128 KB.
  • Text must be 1 to 20,000 characters.
  • It answers 202 once the message is stored and the turn goes on in the background.
  • GET /api/v1/conversation/turns reads the turns back.
  • The README and docs/MCP.md say how to use it. The web page and terminal screen are not built.
  • The crew registers its turn options at start, so the door answers 503 agent_off where the crew is off, as in previews unless FORGE_CREW_IN_PREVIEW=1.
  • The door test posts through HTTP and reads the turns back. It also checks the refusals: anonymous 401, cross-origin 403, empty or oversize text 422, oversize body 413.

Your findings:

  1. Token revoked: the via token is revoked in a finally once runClaude returns. The test holds a turn open, checks the token works for the right user, scope and via, then checks it is dead after the turn.
  2. Failed rows: a turn that throws is marked failed, and a boot resumes nothing for it. The test uses a missing binary.
  3. Forge stop: a stop now aborts live turns (stopTurns, called from the crew's stop()) and waits for them. A cut turn stays running on purpose, so the next boot resumes it.
  4. Caps: a person has one live turn per conversation, at most 5 messages queue behind it (429 queue_full), and the forge runs at most 4 turns at once (429 busy). Both are checked before anything is stored or spent. The test fills the 4 slots and checks the fifth person is refused with nothing stored. The queue cap has no test: a steer reaches a live session almost always, so the queue path is hard to reach from outside.
  5. Words clipped: the token's reason keeps only the first 2,000 characters of the prompt.

Clean-up: the trailing blank line and the unlisten hack are gone. The session log now goes to the run log through appendRunLog under the turn id. The test uses imports and the pointless final assertion is dropped. New tests cover a turn with no account failing closed, and --tools "" with only mcp__forge allowed in the settings.

One change you didn't ask for: the first test now holds a turn open to inspect the token, so its stored turns include a "release" message.

commented

I fixed the OpenAPI coverage failure and pushed it. I did not change anything for the two MCP backups timeouts, which I believe are not caused by this pull.

  • OpenAPI coverage: the two conversation routes, POST /api/v1/conversation/messages and GET /api/v1/conversation/turns, had no OpenAPI row. I added one route file for each under src/contract/openapi/routes/ and regenerated the index with bun scripts/openapi-routes.ts. test/openapi-coverage.test.ts and test/openapi-routes.test.ts pass now.
  • MCP backups timeouts: "MCP backups > a listing that fails is a short sentence with no key in it" and "MCP backups_test > an unreachable one says why, and never echoes a secret" each timed out at 20 s in the check. Both pass here, along with the rest of test/mcp-backups.test.ts and test/mcp-backups-destination.test.ts. Neither test touches the conversation code, so I read this as a flake from an unreachable destination in the check's environment. If it fails again on this push, it needs a separate look.
  • Before the push: bun scripts/gate.ts and bun x tsc --noEmit ran and printed nothing in the last lines I read.

To try it, sign in on the preview at https://lab--8112--forge-trevato-apps.open-platform.sh, post { "text": "…" } to /api/v1/conversation/messages from the browser, then read /api/v1/conversation/turns.

commented

I merged main into this branch and pushed. The branch now matches main exactly, so this pull adds nothing beyond what main already has.

main already carries the same feature in b10a9fbc (#8011): one agent turn per person's message over the forge's MCP, a via token, steering a message into a running turn, resuming once after a restart, a concurrency cap, and a stop that cancels. It also has its own conversation_run migration and its own contract routes.

I resolved all six conflicts (getApiV1ConversationTurns.ts, postApiV1ConversationMessages.ts, claude.ts, conversation.ts, api.ts and test/conversation-turn.test.ts) by taking main's side. I also dropped what was left of my earlier approach, since main's version doesn't use any of it:

  • the duplicate 20261102150000-conversation-run migration and its pin;
  • src/http/api/conversation.ts;
  • my README and docs/MCP.md additions;
  • my dispatch.ts and interrupted.ts changes.

I did not compare the two implementations line by line beyond the conflicted files. If a behaviour of mine is missing from main's version, it needs a fresh, smaller pull on top of #8011.

Checks: bun scripts/gate.ts and bun x tsc --noEmit pass. The conversation tests (test/conversation-turn.test.ts, test/conversation-talk.test.ts) pass: 16 tests, 0 failures. I did not run the full suite; the forge's check does that on this push.

Since there is nothing left to land here, a person can close this pull and #7651 if #8011 covers it.

commented

Closed by the crew: superseded, its change is already on main in 5aa935d6.

Sign in to join this conversation.

↑↓ navigate ↵ open ⌘↵ its app esc close

Keyboard shortcuts

Docs