docs: add /api/chat/workflow contract + promote Chats to top-level nav

Merged
SW
6mo ago
+157-6

Summary

Documentation-driven scoping for the upcoming Vercel-Workflow-backed chat endpoint that will live at POST /api/chat/workflow in api. Landing the contract first so the chat team can integrate against a real spec while the implementation is being ported from open-agents.

  • New OpenAPI path /api/chat/workflow with ChatWorkflowRequest schema (messages, chatId, sessionId, recoupAccessToken?) under Bearer apiKeyAuth
  • Response: text/event-stream + x-workflow-run-id response header
  • Documented status codes: 200 / 400 (incl. "Sandbox not initialized") / 401 / 404 / 409 (duplicate workflow for chat)
  • Frontmatter-only MDX page at api-reference/chat/workflow.mdx per docs CLAUDE.md convention — all prose lives in the OpenAPI description
  • Nav entry under Research → Chat, listed first

The endpoint description verbally maps the deferred sibling routes (GET /api/chat/{chatId}/stream, POST /api/chat/{chatId}/stop) so reviewers see the full planned surface without creating orphan "Coming soon" pages.

This endpoint is parallel to the existing POST /api/chat — does not replace it. The legacy endpoint continues to serve MCP- and Composio-tool chat for clients that need it.

Background

Migration plan worked through in Slack (#recoup) between Sweetman and Arpit on 2026-05-20. Decision: port the open-agents /api/chat agent loop into api as /api/chat/workflow, swap the MCP toolset for the sandbox-only tool set (bash, read, write, grep, glob, todo, task, ask_user_question, skill, fetch), and rely on the recoupable/skills:recoup-api skill (already installed in every sandbox) as the HTTP bridge back to the API.

This is PR 1 of 5. Subsequent PRs land against api:

  1. Route stub: POST /api/chat/workflow with body validation + hardcoded UIMessage stream
  2. Port 10 sandbox tool files + buildAgentTools factory (no wiring)
  3. Port route-level helpers (createChatRuntime, agentCustomInstructions, extractOrgId, compareAndSetChatActiveStreamId, touchChat, reconcileExistingActiveStream, persistLatestUserMessage)
  4. Wire it all together — runAgentWorkflow + runAgentStep + replace stub with real start()

Test plan

  • Mintlify preview renders the new page under Research → Chat → Stream Chat (Workflow + Sandbox)
  • OpenAPI playground for /api/chat/workflow loads with request body, auth, and all five status codes
  • Legacy POST /api/chat page (api-reference/chat/stream) still renders unchanged
  • No broken cross-links — page references /api-reference/sandbox/create, /api-reference/sessions/create, /api-reference/sessions/create-chat, /api-reference/chat/stream

🤖 Generated with Claude Code

Summary by cubic

Adds the contract and docs for POST /api/chat/workflow, a Vercel Workflow–backed, sandbox-only chat streaming endpoint. Also promotes Chats to a top-level tab and trims the endpoint/schema descriptions to house style.

  • New Features

    • OpenAPI path POST /api/chat/workflow secured by apiKeyAuth.
    • ChatWorkflowRequest schema: messages, chatId, sessionId; optional context.contextLimit; no recoupAccessToken (Authorization header is forwarded into the sandbox).
    • Response: text/event-stream with x-workflow-run-id header; status codes: 200, 400 (sandbox not initialized), 401, 403, 404, 409.
    • Docs page api-reference/chat/workflow.mdx; endpoint and schema descriptions tightened. Notes future GET /api/chat/{chatId}/stream and POST /api/chat/{chatId}/stop.

  • Docs Navigation

    • New top-level tab: Chats.
    • Streaming group lists api-reference/chat/workflow, api-reference/chat/stream, api-reference/chat/generate.
    • Other chat pages reorganized under Chats and Messages groups.

Summary by CodeRabbit

  • New Features
    • New streaming chat workflow API endpoint (POST /api/chat/workflow) with session management capabilities
    • Built-in support for workflow execution control via x-workflow-run-id response headers
    • Complete API reference documentation added with request schema specifications and error handling details

Review Change Stack