@edspencer/paddock 0.0.1 → 0.56.0

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

@@ -0,0 +1,86 @@
+/**
+ * The turn-execution engine, extracted from ws.ts (#403).
+ *
+ * `makeTurnEngine({ deps, hub })` relocates — intact — the mutually-recursive core
+ * that ws.ts's makeChatHandler used to hold in one closure: the trigger cluster,
+ * the self-MCP injection context, the per-turn injected-MCP builders + wake cache,
+ * the shared `startAgentTurn` execution engine, and the Layer-2/3 recovery
+ * (`injectRecoveryNudge` + `RecoveryEngine`). These pieces cross-reference each
+ * other (startAgentTurn ↔ recoveryEngine.armWatch, triggers ↔ startAgentTurn,
+ * selfMcp injection ↔ startAgentTurn), so they must share ONE scope — moving them
+ * as a group keeps that intact with no late-binding. ws.ts's socket layer consumes
+ * the returned surface.
+ */
+import type { SDKMessage, InjectedMcpServerDef } from "@herdctl/core";
+import type { Project } from "./projects.js";
+import { SessionHub } from "./session-hub.js";
+import { createWakeInjectionCache, type InjectedMcpBuildArgs } from "./wake-injection.js";
+import { RecoveryEngine } from "./recovery.js";
+import type { ChatHandlerDeps, StartAgentTurn, ChatHandlerContext } from "./ws-context.js";
+/**
+ * The recovery nudge injected by a manual Continue (issue #301, Layer 2) — and,
+ * later, by Layer 3 auto re-drive. It tells the keeper the truth (its background
+ * task was KILLED AT THE TURN BOUNDARY, not "stopped by the user" — cf #216) so it
+ * reacts sensibly: re-run the work in the FOREGROUND this turn, or report what
+ * happened. Kept terse; the killed `<task-notification>` is already in its context.
+ */
+export declare const RECOVERY_NUDGE: string;
+/**
+ * Whether an SDK message is a sub-agent (sidechain) step — `parent_tool_use_id`
+ * points at the spawning `Task` tool_use. Present on the top-level SDK message
+ * and/or its nested `message` (assistant/user shapes differ). Sidechain steps are
+ * the sub-agent's own nested work, surfaced only via the subagents endpoint on
+ * card-expand — so no live stream renders them top-level, or the sub-agent's work
+ * scatters into phantom rows of the parent transcript.
+ *
+ * EVERY live turn path must call this. There are FIVE, each with its own
+ * `createSDKMessageHandler` translator, and for a long time only the first
+ * filtered:
+ *   1. {@link makeBackgroundTurnSink}           — a backgrounded `Task`
+ *   2. this module's `startAgentTurn` onMessage — triggers / spawns / recovery
+ *   3. `ws.ts` onWakeMessage                    — a scheduled wake turn
+ *   4. `ws.ts` `chat:send` onMessage            — a human turn (where it was seen)
+ *   5. `ws.ts` slash-command onMessage          — `/foo` turns
+ *
+ * The gap survived because of a false premise recorded on {@link
+ * makeBackgroundTurnSink}: that only a BACKGROUND Task streams sidechain steps
+ * inline, a foreground one being routed to a separate session. It is not — under
+ * SDK streaming mode a foreground `Task` streams its steps inline on whichever
+ * turn stream launched it, so any unfiltered path duplicates them.
+ *
+ * Skipping is safe for session bookkeeping: a sidechain message carries the SAME
+ * `session_id` as the main chat (verified against on-disk transcripts), and the
+ * launching `tool_use` is itself main-lane, so the id always resolves first.
+ */
+export declare function isSidechainMessage(m: SDKMessage): boolean;
+/** The turn-execution surface ws.ts's socket layer consumes. */
+export interface TurnEngine {
+    startAgentTurn: StartAgentTurn;
+    buildInjection(args: InjectedMcpBuildArgs): Promise<Record<string, InjectedMcpServerDef>>;
+    wakeInjection: ReturnType<typeof createWakeInjectionCache>;
+    selfMcpCtx: ChatHandlerContext;
+    injectRecoveryNudge(project: Project, sessionId: string): Promise<void>;
+    recoveryEngine: RecoveryEngine;
+    emitAfterTurn(slug: string, sessionId: string | null): void;
+    composePreloadedPrompt(projectSlug: string, baseMessage: string): Promise<string>;
+    fireTrigger(slug: string, triggerName: string): Promise<string | null>;
+    /**
+     * Gap B: build a per-turn sink that renders autonomous background-completion
+     * re-invocation turns (delivered on the same session stream after the primary
+     * turn) as their own live hub turns. The human socket path (ws.ts) passes the
+     * returned function as `onBackgroundMessage` so a fresh/resume human turn's
+     * background work is delivered live too — parity with the spawned path.
+     */
+    makeBackgroundTurnSink(projectSlug: string): {
+        onMessage: (m: SDKMessage) => Promise<void>;
+        onDone: () => void;
+    };
+}
+/**
+ * Build the turn-execution engine bound to the handler's deps + shared hub, wiring
+ * the herdctl schedule/wake resolvers and the trigger event listeners.
+ */
+export declare function makeTurnEngine(engine: {
+    deps: ChatHandlerDeps;
+    hub: SessionHub;
+}): TurnEngine;