@edspencer/paddock 0.0.1 → 0.56.0

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

@@ -0,0 +1,158 @@
+/**
+ * Shared context types for the WebSocket chat handler (extracted #403).
+ *
+ * `makeChatHandler` in ws.ts closes over one `deps` bag plus a few shared inner
+ * closures (`startAgentTurn`, `composePreloadedPrompt`, `fireTrigger`, the hub).
+ * To split the ~2000-line handler into sibling modules (ws-self-mcp.ts,
+ * ws-triggers.ts, ws-turn.ts) those pieces need NAMED types instead of relying on
+ * closure scope — this module holds them. It has NO runtime imports from ws.ts, so
+ * both ws.ts and its siblings can import from here without an import cycle.
+ */
+import type { HerdctlService } from "./herdctl.js";
+import type { ProjectStore } from "./projects.js";
+import type { SweepService } from "./sweep.js";
+import type { PaddockConfig } from "./config.js";
+import type { DriveMode } from "./models.js";
+import type { SessionHub } from "./session-hub.js";
+import type { AttachmentStore } from "./attachments.js";
+import type { QueuedMessageStore } from "./queued-message.js";
+import type { ArchiveStore } from "./archive.js";
+import type { ScheduleSessionStore } from "./schedule-session.js";
+import type { RunProvenanceStore, TurnOrigin } from "./run-provenance.js";
+import type { MessageProvenanceStore, MessageSender } from "./message-provenance.js";
+import type { PaddockEventBus } from "./event-bus.js";
+import type { TriggerService } from "./triggers.js";
+import type { TriggerSessionStore } from "./trigger-session.js";
+/**
+ * The store/service bag `makeChatHandler` is constructed with. Extracted to a
+ * named interface (#403) so the handler's extracted sibling modules can accept it
+ * by type instead of closing over it.
+ */
+export interface ChatHandlerDeps {
+    herdctl: HerdctlService;
+    projects: ProjectStore;
+    attachments: AttachmentStore;
+    /** Server config — carries the global keeper drive-mode default (Paddock#111). */
+    cfg: PaddockConfig;
+    /** Optional: post-turn overview/changelog curation engine (issues #2/#6). */
+    sweep?: SweepService;
+    /** Per-chat queued message persistence (#197). */
+    queuedMessage?: QueuedMessageStore;
+    /**
+     * Per-chat provenance sidecar (issue #261 / DD-3, DD-6): records how each chat
+     * was created (origin human/scheduled/spawned + spawn depth) so #262 can
+     * depth-gate spawning and #267 can badge provenance. A1 only carries/persists
+     * the marker — nothing gates on it yet.
+     */
+    runProvenance?: RunProvenanceStore;
+    /**
+     * Per-MESSAGE provenance sidecar (issue #290): records WHO injected each
+     * machine-added turn (send_message / schedule / spawn kickoff) keyed by the
+     * TARGET session, so the chat history can attribute injected turns. Optional so
+     * existing tests need not supply it; absent ⇒ injected turns just render as
+     * unlabelled user bubbles (today's behaviour).
+     */
+    messageProvenance?: MessageProvenanceStore;
+    /**
+     * Per-chat archived-flag sidecar (#95). Used by the self-MCP archive_chat /
+     * unarchive_chat write tools (#263) so a keeper can file a chat away — most
+     * usefully ITSELF, powering the "work → archive myself on success" convention.
+     */
+    archive: ArchiveStore;
+    /**
+     * Owned-session sidecar for accreting schedules (issue #265 / DD-2): maps a
+     * `resume_session: true` schedule to the one chat it owns, created on its first
+     * fire and reused thereafter. Absent ⇒ scheduled chats still work but every
+     * accreting schedule would start fresh each fire (degrades to `resume_session:
+     * false`); wired in production, optional so existing tests need not supply it.
+     */
+    scheduleSessions?: ScheduleSessionStore;
+    /**
+     * In-process lifecycle event bus (Epic T). When present (with {@link triggers}),
+     * this handler subscribes to lifecycle events (v1: `onArchive`) and fires each of
+     * the project's ENABLED matching EVENT triggers as its own `trigger-<slug>-<name>`
+     * agent turn via {@link startAgentTurn}. Absent ⇒ no event-trigger dispatch, so
+     * tests that don't exercise triggers need not supply it.
+     */
+    events?: PaddockEventBus;
+    /**
+     * Unified trigger registry (Epic T / T1). When present, this handler fires the
+     * project's enabled EVENT triggers (via the {@link events} bus) and its SCHEDULE
+     * triggers (via herdctl's `setScheduleTriggerHandler`) through the SAME
+     * {@link startAgentTurn} core — the single execution engine for every trigger. Absent
+     * ⇒ no trigger dispatch, so tests that don't exercise triggers need not supply it.
+     */
+    triggers?: TriggerService;
+    /**
+     * Owned-session sidecar for accreting triggers (`run.session: "resume"`, Epic T /
+     * T1) — maps a resume-type trigger to the one chat it accretes into across fires,
+     * created on its first fire and rebound off this store after a restart. Absent ⇒
+     * resume-type triggers degrade to a fresh chat each fire; wired in production,
+     * optional so existing tests need not supply it.
+     */
+    triggerSessions?: TriggerSessionStore;
+}
+/**
+ * Options for the shared per-turn execution engine `startAgentTurn` (ws-turn.ts /
+ * ws.ts). Named here so the sibling modules that RECEIVE `startAgentTurn` as a
+ * context callback (self-MCP write tools, trigger firing) can type it.
+ */
+export interface StartAgentTurnOpts {
+    projectSlug: string;
+    agentName: string;
+    workingDir: string;
+    resume: string | null;
+    prompt: string;
+    driveMode: DriveMode;
+    fallbackModel: string;
+    /**
+     * Provenance of this server-initiated turn (issue #261 / DD-3). The self-MCP
+     * write tools pass `spawned` + the child's depth. Persisted for a NEW chat
+     * only (a resume/message keeps the target chat's existing marker).
+     */
+    origin: TurnOrigin;
+    depth: number;
+    /**
+     * The chat that CREATED this one, when a chat did (issue #509). Stamped
+     * alongside `origin`/`depth` for a NEW chat, giving the nested chat list a
+     * RECORDED parent edge instead of leaving it to infer one from the kickoff
+     * message's sender.
+     *
+     * Absent when no calling chat exists — a schedule/hook fire, or the external
+     * `/mcp` transport (which binds `currentSessionId: () => null`).
+     */
+    parent?: {
+        project: string;
+        sessionId: string;
+    };
+    /**
+     * The effective `maxSpawnDepth` for the chat this turn runs in (issue #262),
+     * already resolved by the caller from the TARGET project (per-project override
+     * else instance default). Gates whether this turn receives the self-MCP.
+     */
+    maxSpawnDepth: number;
+    /**
+     * WHO caused this injected turn (issue #290). Present for a machine injection
+     * (another chat `send_message` / a schedule fire / a spawn kickoff); absent for
+     * a turn with no attributable non-human sender.
+     */
+    sender?: MessageSender;
+}
+/** The shared per-turn execution engine — resolves the chat's sessionId as soon as known. */
+export type StartAgentTurn = (opts: StartAgentTurnOpts) => Promise<string>;
+/** Resolve a preloaded (OVERVIEW+CHANGELOG) prompt for a new chat (issues #1/#188). */
+export type ComposePreloadedPrompt = (projectSlug: string, baseMessage: string) => Promise<string>;
+/** Fire a project's named trigger on demand; resolves the started chat's id or null. */
+export type FireTrigger = (slug: string, triggerName: string) => Promise<string | null>;
+/**
+ * The context the self-MCP builder + trigger-firing cluster need: the deps bag,
+ * the shared hub, and the shared inner closures. Assembled once in ws.ts and
+ * passed to the extracted sibling functions.
+ */
+export interface ChatHandlerContext {
+    deps: ChatHandlerDeps;
+    hub: SessionHub;
+    startAgentTurn: StartAgentTurn;
+    composePreloadedPrompt: ComposePreloadedPrompt;
+    fireTrigger: FireTrigger;
+}

package/packages/server/dist/ws-context.js

@@ -0,0 +1 @@
+export {};

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

@@ -0,0 +1,423 @@
+/**
+ * WebSocket wire protocol + token/usage math (extracted from ws.ts, issue #403).
+ *
+ * Pure types + pure functions — no closure ties, no store/service dependencies.
+ * Holds:
+ *   - the client->server and server->client message interfaces + unions,
+ *   - the {@link isClientMessage} runtime guard,
+ *   - the per-turn usage extraction/fold/resolve helpers.
+ *
+ * `ws.ts` re-exports every symbol here so external importers (and tests) that
+ * `import … from "./ws.js"` continue to resolve unchanged.
+ *
+ * See ws.ts's module doc comment for the on-the-wire protocol narrative.
+ */
+import type { SDKMessage } from "@herdctl/core";
+import type { TurnNotice } from "./turn-notice.js";
+/**
+ * Per-turn token usage as observed on the SDK stream, normalized to camelCase.
+ * Read defensively from either an assistant message (`m.message.usage`) or the
+ * final result message (`m.usage`) — fields are loosely typed in core.
+ */
+export interface TurnUsage {
+    inputTokens: number;
+    outputTokens: number;
+    cacheReadTokens: number;
+    cacheCreationTokens: number;
+}
+/** A model id seen on the SDK stream paired (best-effort) with its usage. */
+interface ExtractedUsage {
+    usage: TurnUsage | null;
+    model: string | null;
+    /**
+     * True when this usage came from the terminal `type:"result"` SDK message,
+     * whose `usage` is a CUMULATIVE per-turn total aggregated across every internal
+     * API call (num_turns), not a single context-window snapshot (#398). Such a
+     * block must never feed the context-snapshot meter.
+     */
+    fromResult: boolean;
+}
+/**
+ * Defensively extract per-turn usage + model from a raw SDK message. The SDK's
+ * `message` is typed `unknown` in core, and the CLI/SDK runtimes shape usage
+ * slightly differently, so every field access is guarded.
+ *
+ * - assistant message: `m.message.usage` (Anthropic usage block) + `m.message.model`.
+ * - result message: top-level `m.usage` (same field names). Flagged `fromResult`
+ *   because that block is a cumulative per-turn total, not a snapshot (#398).
+ *
+ * Returns `{ usage: null, model: null, fromResult: false }` when neither is present.
+ */
+export declare function extractUsage(m: SDKMessage): ExtractedUsage;
+/**
+ * The rendered output of a client-local slash command (`/context`, `/usage`, …) to
+ * surface as an assistant note, or null when this SDK message isn't one (issue #158).
+ *
+ * The interactive TUI renders these locally; a non-interactive SDK session (Paddock's
+ * path) instead surfaces the output as EITHER a `type:"system"` / `local_command`
+ * entry (its `content` wraps the output in `<local-command-stdout>…`) or a
+ * `model:"<synthetic>"` assistant placeholder carrying the text. @herdctl/chat's
+ * translator drops both (synthetic messages are skipped; system entries aren't text),
+ * so the live command turn would otherwise read as a silent no-op. We recover the text
+ * and emit it as an assistant note (mirroring the `compact_boundary` special-case),
+ * consistent with the history-path recovery in `localcommand.ts`. Bare placeholders
+ * (e.g. `/compact`'s "No response requested.") yield null so they stay quiet. Paddock's
+ * own context ring + cost meter remain the primary usage view; this just stops the
+ * output vanishing.
+ */
+export declare function extractLocalCommandOutput(m: SDKMessage): string | null;
+/**
+ * Merge two context-snapshot usage blocks, keeping whichever best reflects the
+ * context window (issue #165). Only assistant / partial-assistant blocks are ever
+ * passed here — the terminal `result` block is folded separately (see
+ * {@link foldTurnUsage}), because its usage is cumulative, not a snapshot (#398).
+ *
+ * Assistant usage grows monotonically through a turn (each round re-reads the
+ * cached prefix), so "last assistant" == "max assistant". We still keep the MAX
+ * `contextTokens` (input + cacheRead + cacheCreation) defensively: an odd
+ * cache-less block can never LOWER the snapshot. `outputTokens` keeps the max
+ * seen.
+ */
+export declare function pickTurnUsage(prev: TurnUsage | null, next: TurnUsage): TurnUsage;
+/**
+ * Running per-turn usage, keeping the context snapshot and the terminal result's
+ * cumulative totals STRICTLY SEPARATE (#398).
+ *
+ * The `result` SDK message's `usage` (`SDKResultSuccess.usage`) is a cumulative
+ * sum across every internal API call in the turn (`num_turns`) — on a long
+ * tool-heavy turn it dwarfs any single assistant block. Feeding it into the
+ * snapshot (as the old MAX heuristic did) inflated the live context meter (e.g.
+ * 828k when the true window was ~292k), only to be corrected on refresh from
+ * disk. So we route it to `cumulative` and never let it touch the snapshot.
+ */
+export interface TurnUsageState {
+    /** Context-window snapshot from assistant / partial-assistant messages. */
+    snapshot: TurnUsage | null;
+    /** Terminal result's cumulative per-turn totals — for cost/output only, never contextTokens. */
+    cumulative: TurnUsage | null;
+    /** Most recent model id seen paired with usage. */
+    model: string | null;
+}
+/** A fresh, empty per-turn usage accumulator. */
+export declare function initTurnUsage(): TurnUsageState;
+/**
+ * Fold one raw SDK message into the running usage state. Mirrors exactly what the
+ * ws.ts stream loop does, so tests can drive it the same way. Assistant usage
+ * accumulates into the context snapshot; the terminal `result` block is stashed
+ * separately as the turn's cumulative total (#398).
+ */
+export declare function foldTurnUsage(state: TurnUsageState, m: SDKMessage): TurnUsageState;
+/**
+ * Resolve the final per-turn usage emitted on `chat:complete`. `contextTokens`
+ * always derives from the snapshot (the true window). The cumulative result block
+ * is used only to lift `outputTokens` to the turn's final total, and as a
+ * last-resort fallback for context if NO assistant usage was seen this turn (some
+ * runtimes emit usage only on the result — there cumulative == the single call).
+ */
+export declare function resolveTurnUsage(state: TurnUsageState): TurnUsage | null;
+export interface ChatSendMessage {
+    type: "chat:send";
+    payload: {
+        /**
+         * Workspace key: a project slug. `""` is the ROOT workspace — a present
+         * empty string, not an absent value, so test it with `=== undefined`,
+         * never for falsiness.
+         */
+        projectSlug?: string;
+        /** Session to resume; null/omitted starts a new chat. */
+        sessionId?: string | null;
+        message: string;
+        /**
+         * When true AND this is a NEW chat (sessionId null/omitted) AND the project
+         * has an OVERVIEW.md, prepend that overview to the prompt as a delimited
+         * context block (issue #1). No-op when no overview exists.
+         */
+        preloadContext?: boolean;
+        /**
+         * Optional per-chat model override (a known model id). Unknown/absent ->
+         * the workspace's persisted model, else the keeper default. The keeper agent
+         * is re-registered at this model before triggering. (§7.)
+         */
+        model?: string;
+        /**
+         * Files the user attached in the composer (issue #328). Each references an
+         * attachment already uploaded via `POST …/chats/:id/upload` (bytes in the
+         * store). The server validates them against the project's effective attachment
+         * config, then prepends a `<paddock-attachments>` hint block to the prompt
+         * pointing the keeper's `Read` tool at the absolute paths. Project chats only.
+         */
+        attachments?: Array<{
+            id: string;
+            filename: string;
+            kind?: string;
+        }>;
+    };
+}
+export interface ChatCancelMessage {
+    type: "chat:cancel";
+    payload: {
+        jobId: string;
+    };
+}
+/**
+ * Run a slash command (e.g. `/compact`) in the current chat.
+ *
+ * Unlike `chat:send`, this drives herdctl's streaming session so the CLI
+ * dispatches the command instead of treating the text as a plain prompt. The
+ * command acts on the resumed `sessionId`, so `/compact` compacts the real
+ * chat history. Output streams back over the same `chat:response` /
+ * `chat:tool_call` / `chat:complete` events as a normal turn.
+ */
+export interface ChatCommandMessage {
+    type: "chat:command";
+    payload: {
+        projectSlug?: string;
+        /** Session the command runs against. Required (a command needs a chat). */
+        sessionId?: string | null;
+        /** The full command text, including the leading slash (e.g. "/compact"). */
+        command: string;
+    };
+}
+/**
+ * Attach a socket to a session's live stream (issue #54). Sent on (re)connect so
+ * a socket that dropped mid-turn can re-attach to the still-running turn and be
+ * replayed the frames it missed.
+ *
+ * `wantReplay` MUST be false on a fresh mount (which also hydrates the transcript
+ * over REST) so buffered frames don't duplicate the transcript; it is true only
+ * for a genuine reconnect of a socket that was mid-turn, with `lastSeq` = the
+ * last per-turn `seq` the client applied (the replay is exactly the gap after it).
+ */
+export interface ChatSubscribeMessage {
+    type: "chat:subscribe";
+    payload: {
+        projectSlug?: string;
+        /** The session to attach to. Required. */
+        sessionId: string;
+        /** Replay the missed gap of a live turn (reconnect); false = future frames only. */
+        wantReplay?: boolean;
+        /** Last per-turn `seq` the client applied; the server replays everything after it. */
+        lastSeq?: number;
+    };
+}
+/**
+ * Store a queued message to be auto-sent when the current turn completes (#197).
+ * The client sends this to persist the queue server-side so it survives browser
+ * close; the server stores it, checks after turn completion, and auto-sends if
+ * present. The web client also keeps a localStorage copy for live editing UX.
+ */
+export interface ChatSetQueueMessage {
+    type: "chat:set_queue";
+    payload: {
+        projectSlug?: string;
+        sessionId?: string | null;
+        /** The queued message text, or null/empty to clear. */
+        text?: string | null;
+        /**
+         * Client-stamped identity of this queued message (#245): the ms timestamp of
+         * when it was first enqueued, stable across reloads. The server records the ts
+         * of the message it last drained per session so it can skip re-sending a stale
+         * copy a reloaded client re-asserts. Absent → the server stamps `Date.now()`.
+         */
+        ts?: number | null;
+    };
+}
+/**
+ * Manually re-drive a keeper that hung because its background task was killed at
+ * the turn boundary (issue #301, Layer 2). The keeper's session stayed ALIVE (see
+ * edspencer/herdctl#374) so it's still injectable — this action injects a recovery
+ * nudge into it via {@link startAgentTurn}, exactly the message a human sends by
+ * hand today to unstick it, but one click and correctly attributed
+ * (`sender: { kind: "recovery" }`). Gated server-side on the resolved
+ * `recovery.surfaceKilledTask` (per-project override else instance default), so a
+ * client can't re-drive when the operator turned Layer 2 off.
+ */
+export interface ChatContinueMessage {
+    type: "chat:continue";
+    payload: {
+        projectSlug?: string;
+        /** The hung keeper session to re-drive. Required (recovery needs a chat). */
+        sessionId: string;
+    };
+}
+export interface PingMessage {
+    type: "ping";
+}
+export type ClientMessage = ChatSendMessage | ChatCommandMessage | ChatCancelMessage | ChatSubscribeMessage | ChatSetQueueMessage | ChatContinueMessage | PingMessage;
+export interface Routing {
+    projectSlug: string;
+    sessionId: string | null;
+    jobId: string | null;
+    /**
+     * Per-turn, monotonic sequence number stamped by the SessionHub as the frame
+     * is emitted (issue #54). Lets a reconnecting client tell the server the last
+     * frame it applied so the exact missed gap can be replayed. Absent on frames
+     * not routed through the hub (e.g. chat:error).
+     */
+    seq?: number;
+}
+export interface ChatResponseMessage {
+    type: "chat:response";
+    payload: Routing & {
+        chunk: string;
+    };
+}
+export interface ChatToolCallMessage {
+    type: "chat:tool_call";
+    payload: Routing & {
+        toolName: string;
+        inputSummary?: string;
+        output: string;
+        isError: boolean;
+        durationMs?: number;
+        /**
+         * The originating tool_use id. Lets a client reconcile this completion with
+         * the pending row it created on the earlier `chat:tool_start` frame (#175).
+         */
+        toolUseId?: string;
+        subagentType?: string;
+        description?: string;
+        hasSubagent?: boolean;
+    };
+}
+/**
+ * An in-flight tool_use, emitted the moment the tool STARTS — before it runs or
+ * produces a result (#175). Lets a client render a pending "running…" row for
+ * slow tools (especially subagents that run for minutes), keyed by `toolUseId`,
+ * then reconcile it when the matching `chat:tool_call` completion arrives.
+ * Sourced from `@herdctl/chat`'s `onToolStart` (v0.6.0+).
+ */
+export interface ChatToolStartMessage {
+    type: "chat:tool_start";
+    payload: Routing & {
+        toolName: string;
+        inputSummary?: string;
+        toolUseId?: string;
+        /** Subagent attribution: null = main agent, else the spawning Task tool_use id. */
+        parentToolUseId: string | null;
+        subagentType?: string;
+        description?: string;
+        hasSubagent?: boolean;
+    };
+}
+export interface ChatMessageBoundaryMessage {
+    type: "chat:message_boundary";
+    payload: Routing;
+}
+/** Per-turn token usage surfaced on chat:complete (camelCase, with the meter math). */
+export interface ChatCompleteUsage {
+    inputTokens: number;
+    outputTokens: number;
+    cacheReadTokens: number;
+    cacheCreationTokens: number;
+    /** input + cacheRead + cacheCreation (what the context window holds). */
+    contextTokens: number;
+    /** getContextLimit(model). */
+    contextLimit: number;
+}
+export interface ChatCompleteMessage {
+    type: "chat:complete";
+    payload: Routing & {
+        success: boolean;
+        error?: string;
+        /** The model this turn ran on (lastModel ?? effectiveModel). Omitted if unknown. */
+        model?: string;
+        /** Last per-turn usage observed; omitted (with model) if none was seen. */
+        usage?: ChatCompleteUsage;
+    };
+}
+export interface ChatErrorMessage {
+    type: "chat:error";
+    payload: {
+        projectSlug: string;
+        error: string;
+    };
+}
+/**
+ * Tell a re-attaching client to re-hydrate from the transcript instead of a
+ * frame replay (issue #54). Emitted only when the missed gap has aged out of the
+ * turn's bounded buffer — the rare fallback that trades live-ness for correctness.
+ */
+export interface ChatResyncMessage {
+    type: "chat:resync";
+    payload: {
+        projectSlug: string;
+        sessionId: string;
+    };
+}
+/**
+ * A session's live-turn status (issues #52/#53). Broadcast to all clients on a
+ * turn's start/stop transition, sent as a snapshot to a newly-connected socket,
+ * and sent in reply to a `chat:subscribe` for a session with a running turn. It
+ * lets a client restore the Stop button + `jobId` for a returning/remounted pane
+ * (#52) and drive the in-chat + per-chat-sidebar streaming indicators (#53).
+ */
+export interface ChatActiveMessage {
+    type: "chat:active";
+    payload: {
+        projectSlug: string;
+        sessionId: string;
+        /** The running turn's cancellable job id, when known. */
+        jobId: string | null;
+        running: boolean;
+    };
+}
+/**
+ * Notify the client that the queued message was auto-sent by the server (#197).
+ * The client clears its localStorage copy of the queued message when it receives
+ * this frame, so queued messages don't duplicate if the browser closes before
+ * the turn completes.
+ */
+export interface ChatQueuedFlushedMessage {
+    type: "chat:queued_flushed";
+    payload: {
+        projectSlug: string;
+        sessionId: string;
+        /**
+         * The queued text the server is now auto-sending as a turn (#245). Present
+         * when the server actually drained+sent it — the client renders it as the
+         * user bubble in-transcript (the drained turn streams only the reply). Absent
+         * when the frame is just telling the client to clear a stale/already-sent copy.
+         */
+        text?: string;
+    };
+}
+/**
+ * A background task was killed at the turn boundary and the keeper is idle
+ * (issue #347). Broadcast LIVE by the recovery engine the moment the kill is
+ * detected — the notification is otherwise trapped in the SDK input queue until
+ * a later turn flushes it, so without this the "keeper is idle / Continue"
+ * affordance only appeared after a manual refresh. The client renders it as the
+ * amber killed-task notice inline. Gated server-side on `recovery.surfaceKilledTask`.
+ */
+export interface ChatKilledTaskMessage {
+    type: "chat:killed_task";
+    payload: {
+        projectSlug: string;
+        sessionId: string;
+        /** The killed `<task-notification>`'s `<summary>`, or a generic fallback. */
+        summary: string;
+        /** ISO timestamp of detection — used by the client to dedup replays. */
+        timestamp: string;
+    };
+}
+/**
+ * A keeper turn dead-ended without a normal reply (issue #329): a synthetic
+ * subscription/usage-limit hit, the max-turns cap, or an error (network / API
+ * 5xx-overloaded / auth / crash). Emitted INLINE during the turn (session-routed
+ * like the other turn frames), so the chat surfaces WHY it stopped instead of
+ * looking dead. The client renders it as a distinct notice turn (with the reset
+ * time for a usage limit, and a Retry/Continue affordance when `retryable`).
+ */
+export interface ChatNoticeMessage {
+    type: "chat:notice";
+    payload: Routing & {
+        notice: TurnNotice;
+    };
+}
+export interface PongMessage {
+    type: "pong";
+}
+export type ServerMessage = ChatResponseMessage | ChatToolCallMessage | ChatToolStartMessage | ChatMessageBoundaryMessage | ChatCompleteMessage | ChatErrorMessage | ChatResyncMessage | ChatActiveMessage | ChatQueuedFlushedMessage | ChatKilledTaskMessage | ChatNoticeMessage | PongMessage;
+export declare function isClientMessage(data: unknown): data is ClientMessage;
+export {};