| 1 | import type { DocsRuntimeApiDict } from "../types"; |
| 2 | |
| 3 | /** |
| 4 | * English reference dictionary for `app/[locale]/docs/runtime-api/page.tsx`. |
| 5 | * Copy moved verbatim from the page's `isZh` ternaries — any wording change |
| 6 | * belongs in its own commit, never mixed into a structural move. |
| 7 | */ |
| 8 | export const docsRuntimeApi: DocsRuntimeApiDict = { |
| 9 | metaTitle: "Runtime API · Codewhale Docs", |
| 10 | metaDescription: |
| 11 | "Local HTTP/SSE, JSON-RPC stdio, and ACP entrypoints for integrations, bridges, and automation.", |
| 12 | bodyClassName: "text-ink-soft leading-relaxed", |
| 13 | overviewTitle: "Runtime API", |
| 14 | overviewLead: |
| 15 | "codewhale app-server is the canonical local runtime API and control plane. Local SDKs, mobile/remote-control clients, and editor integrations talk to it instead of screen-scraping terminal output. The engine runs as a local-only process: every API binds to localhost by default — no hosted relay, no provider-token custody, no secret leakage. codewhale serve --http / --mobile remain compatibility aliases for app-server --http / --mobile and launch the identical server; new integrations should target app-server.", |
| 16 | entries: [ |
| 17 | ["http", "The full /v1/* HTTP/SSE runtime API (canonical entry), default 127.0.0.1:7878."], |
| 18 | ["mobile", "The runtime API plus the /mobile phone control page."], |
| 19 | [ |
| 20 | "stdio", |
| 21 | "Newline-delimited JSON-RPC 2.0 control transport with no listener, for local SDKs and probes.", |
| 22 | ], |
| 23 | [ |
| 24 | "web", |
| 25 | "The loopback-only browser client, embedded in the binary and opened in the default browser.", |
| 26 | ], |
| 27 | ["doctor", "Machine-readable health and capability report."], |
| 28 | ["acp", "ACP (Agent Client Protocol) stdio adapter for editors such as Zed."], |
| 29 | [ |
| 30 | "exec", |
| 31 | "The one-shot headless worker (stream-json, fleet subprocess, CI primitive) — not part of this API, but it shares the same runtime and event vocabulary.", |
| 32 | ], |
| 33 | ], |
| 34 | stdioTitle: "Probe without model tokens", |
| 35 | stdioLead: |
| 36 | "The stdio control transport can be probed without spending model tokens. capabilities returns the advertised method families (thread/*, app/*, prompt/*) and the full method list; the method set is pinned by a drift test in crates/app-server/src/lib.rs, so SDK and local integration clients can rely on it not changing silently.", |
| 37 | interruptNote: |
| 38 | "A live turn can be asked to stop with thread/interrupt (or POST /v1/threads/{id}/turns/{turn_id}/interrupt over HTTP); when no turn is streaming the reply carries interrupted: false — not an error, just nothing to stop.", |
| 39 | securityTitle: "Security boundary", |
| 40 | securityLead: |
| 41 | "The runtime API token is read from {authToken}, then {runtimeTokenEnv}, then {legacyTokenEnv}; {insecureFlag} is only accepted with a loopback bind. Cross-origin browser requests are rejected by the CORS allow-list. Before selecting a non-loopback bind — especially {mobileFlag} — read the full deployment and authentication contract in docs/RUNTIME_API.md.", |
| 42 | sourceNote: "Source document: docs/RUNTIME_API.md · Update docs-map.ts when changing.", |
| 43 | }; |
| 44 |