@edspencer/paddock 0.0.1 → 0.56.0

package/packages/server/dist/ws.d.ts

@@ -0,0 +1,62 @@
+/**
+ * WebSocket chat transport.
+ *
+ * Protocol (the contract the frontend agent matches):
+ *
+ *   client -> server:
+ *     { type: "chat:send", payload: {
+ *         projectSlug: string,        // workspace key: a project slug, or "" for the root
+ *         sessionId: string | null,   // resume an existing chat, or null = new
+ *         message: string,
+ *         preloadContext?: boolean,   // new chat: prepend the project OVERVIEW.md
+ *         model?: string,             // per-chat model override (a known model id)
+ *     } }
+ *     { type: "chat:cancel", payload: { jobId } }   // optional: stop a running turn
+ *     { type: "ping" }
+ *
+ *   server -> client (all carry projectSlug + sessionId + jobId for routing):
+ *     { type: "chat:response",         payload: { projectSlug, sessionId, jobId, chunk } }
+ *     { type: "chat:tool_call",        payload: { projectSlug, sessionId, jobId,
+ *                                                  toolName, inputSummary, output,
+ *                                                  isError, durationMs } }
+ *     { type: "chat:message_boundary", payload: { projectSlug, sessionId, jobId } }
+ *     { type: "chat:complete",         payload: { projectSlug, sessionId, jobId, success, error?,
+ *                                                  model?, usage? } }
+ *         // model: the model the turn ran on (lastModel ?? effectiveModel).
+ *         // usage: { inputTokens, outputTokens, cacheReadTokens,
+ *         //          cacheCreationTokens, contextTokens, contextLimit } — the
+ *         //          LAST per-turn usage observed; omitted (with model) if none.
+ *         //          contextTokens = input + cacheRead + cacheCreation;
+ *         //          contextLimit  = getContextLimit(model). Stale-by-one-turn
+ *         //          by design (it reflects the just-completed turn's input).
+ *     { type: "chat:injected",         payload: { projectSlug, sessionId, jobId,
+ *                                                  sender, content, timestamp } }
+ *         // A machine-injected user turn (issue #290 Part 2): another chat
+ *         // send_message'd / a schedule fired into this session. Emitted so a
+ *         // client already viewing the recipient chat renders the injected user
+ *         // bubble LIVE (with its sender attribution) instead of only seeing the
+ *         // assistant reply and needing a refresh. `sender` is the MessageSender.
+ *     { type: "chat:error",            payload: { projectSlug, error } }
+ *     { type: "pong" }
+ *
+ * Streaming is wired for real via HerdctlService.chat()'s onMessage callback
+ * (the public trigger API supports it). The SDKMessage -> chat-event translation
+ * (assistant text deltas, message boundaries, and paired tool_use -> tool_result
+ * calls enriched with input summaries + wall-clock durations) is done by
+ * @herdctl/chat's `createSDKMessageHandler` — the shared, transport-agnostic
+ * translator every herdctl chat surface uses — so paddock no longer reimplements
+ * it (and as of @herdctl/chat@0.4.1 it pairs CLI tool results correctly, so the
+ * prior `normalizeForTranslator` shim is gone). We compose it with a tiny wrapper
+ * that also captures, from each raw SDK message, the session id and the per-turn
+ * usage + model (the translator only exposes text/boundary/tool events).
+ */
+import type { WebSocket } from "@fastify/websocket";
+export * from "./ws-protocol.js";
+import type { ChatHandlerDeps } from "./ws-context.js";
+export { forkKickoffPrompt } from "./ws-self-mcp.js";
+export { RECOVERY_NUDGE } from "./ws-turn.js";
+export declare function makeChatHandler(deps: ChatHandlerDeps): {
+    handle: (socket: WebSocket) => Promise<void>;
+    fireTrigger: (slug: string, triggerName: string) => Promise<string | null>;
+    managementOpsContext: import("./ws-context.js").ChatHandlerContext;
+};