@north-light/crouter 0.3.173 → 0.3.175

package/dist/core/runtime/broker/frame-dispatch.d.ts

@@ -0,0 +1,238 @@
+import type { AgentSessionServices, ModelRegistry, PromptOptions } from '@earendil-works/pi-coding-agent';
+import type { ImageContent } from '@earendil-works/pi-ai';
+import { type BrokerSdkConfig } from '../launch.js';
+import type { ClientToBroker } from '../broker-protocol.js';
+import type { BrokerClient, BrokerClientRegistry } from './client-registry.js';
+import { type BrokerSession } from './read-ops.js';
+import type { ToolGroupTracker } from './tool-groups.js';
+import type { EventProjection } from './event-projection.js';
+import type { RebindDriver } from './rebind.js';
+export declare const REVIEW_BOUNDARY_NAVIGATION_CODE = "review_boundary_navigation";
+export declare class ReviewBoundaryNavigationError extends Error {
+    readonly targetId: string;
+    readonly code = "review_boundary_navigation";
+    constructor(targetId: string);
+}
+/**
+ * Route a writable client's `prompt`/`follow_up` frame against the LIVE session
+ * state. The client picks its frame type off a possibly-STALE `isStreaming`
+ * snapshot, so the broker is authoritative and the client's choice is a HINT:
+ *
+ *  - m-B (streaming-safe prompt): a `prompt` arriving mid-stream needs
+ *    PromptOptions.streamingBehavior ("Required if streaming"; prompt() throws
+ *    without it). "steer" mirrors pi interactive-mode's own
+ *    Enter-while-streaming submit (`prompt(text, { streamingBehavior: "steer" })`).
+ *  - m-C (idle-safe follow_up): pi's followUp() only enqueues into a RUNNING
+ *    agent loop — on an idle session nothing ever drains the queue and the text
+ *    is silently lost. An idle `follow_up` therefore runs as a prompt now.
+ *
+ * driveEngine calls this synchronously with `session.isStreaming`, so the
+ * routed state cannot go stale between the check and the engine call.
+ * C1: images ride as a field on PromptOptions (pi: `prompt(text, { images })`).
+ */
+export declare function resolveEngineRoute(frame: {
+    type: 'prompt' | 'follow_up';
+    images?: ImageContent[];
+}, isStreaming: boolean): {
+    call: 'prompt';
+    options: PromptOptions;
+} | {
+    call: 'followUp';
+};
+/**
+ * True iff `text` would be consumed by pi's OWN leading-name preflight before
+ * `session.prompt/steer/followUp` ever sees it as prose — an extension command
+ * (`session.extensionRunner.getCommand`), a `/skill:name` skill, or a `/name`
+ * prompt template (mirrors `_tryExecuteExtensionCommand` / `_expandSkillCommand`
+ * / `expandPromptTemplate` in the pinned SDK verbatim, including the exact
+ * name-parsing substrings). Inline memory-reference guidance must NEVER fire
+ * for these — the leading token routes to the engine's own command surface,
+ * not prose referencing a memory doc. Each lookup is independently wrapped so
+ * an engine missing one accessor (the fake, or a degraded session) degrades
+ * that check to "not a match" rather than aborting the whole classification —
+ * matching `buildCommandList`'s existing "no live extensionRunner" tolerance.
+ */
+export declare function isLeadingEngineCommand(text: string, session: {
+    extensionRunner?: {
+        getCommand(name: string): unknown;
+    };
+    resourceLoader?: {
+        getSkills(): {
+            skills: Array<{
+                name: string;
+            }>;
+        };
+    };
+    promptTemplates?: ReadonlyArray<{
+        name: string;
+    }>;
+}): boolean;
+/** A `steer` frame normally maps directly to pi's steer queue. Engine commands,
+ * skills, and templates must instead pass through prompt()'s leading-command
+ * preflight; with streamingBehavior:'steer', ordinary expanded text still lands
+ * in the same queue. */
+export declare function resolveSteerCall(text: string, session: Parameters<typeof isLeadingEngineCommand>[1]): 'prompt' | 'steer';
+/**
+ * Enumerate every leading-token STRING this session's engine would
+ * independently consume as a leading command/skill/template dispatch BEFORE
+ * inline memory-reference guidance ever applies — the read-op sibling of
+ * `isLeadingEngineCommand`'s point-lookup, gathered as a full enumeration for
+ * viewer-side suppression instead of a per-submission membership check. Same
+ * three sources, same shape of the leading match `isLeadingEngineCommand`
+ * checks (bare extension-command invocation names and prompt-template names,
+ * `skill:<name>` for skills), so `/${token}` round-trips through
+ * `isLeadingEngineCommand(text, session)` for every emitted token (locked by
+ * a test). Kept STRICTLY separate from `buildCommandList` (command
+ * completion) and the ref inventory (`RefMeta` rows) — this is neither.
+ */
+export declare function engineLeadingCommandTokens(session: {
+    extensionRunner?: {
+        getRegisteredCommands(): Array<{
+            invocationName: string;
+        }>;
+    };
+    resourceLoader?: {
+        getSkills(): {
+            skills: Array<{
+                name: string;
+            }>;
+        };
+    };
+    promptTemplates?: ReadonlyArray<{
+        name: string;
+    }>;
+}): string[];
+/**
+ * Choose how the hidden `crtr-memory-refs` guidance custom message rides
+ * alongside a human frame's own engine call (design Flow B). Pure over the
+ * frame's routing outcome — never reads live session state itself, so a
+ * caller can decide the delivery mode from the exact same `route`
+ * `resolveEngineRoute` already computed for the human call.
+ *
+ *  - `steer` frame              -> 'steer' (always; no route call exists).
+ *  - a TRUE mid-stream follow_up (`routeCall === 'followUp'`) -> 'followUp'.
+ *  - every other `prompt`/`follow_up` routed as `routeCall === 'prompt'`:
+ *    idle -> 'nextTurn' (the ONLY case guidance precedes the human call —
+ *    pi's `prompt()` reads+clears its pending-nextTurn queue synchronously
+ *    into the SAME turn as the new user message); streaming (m-B
+ *    steer-while-streaming) -> 'steer', never 'nextTurn' (that would attach
+ *    to a later, unrelated turn).
+ */
+export declare function chooseGuidanceDeliveryMode(frameType: 'prompt' | 'follow_up' | 'steer', routeCall: 'prompt' | 'followUp' | undefined, isStreaming: boolean): 'steer' | 'followUp' | 'nextTurn';
+/**
+ * Deliver a `nextTurn` guidance custom message ATOMICALLY around the idle-
+ * prompt call it's meant to ride alongside. Pi's `_pendingNextTurnMessages`
+ * queue (the only public seam for `deliverAs:'nextTurn'`) is drained ONLY deep
+ * inside `session.prompt()`, well after several await points — extension-
+ * command interception, the `input` extension transform, a streaming reroute,
+ * model/auth validation, pre-turn compaction — that can return or throw BEFORE
+ * the drain ever runs. `sendCustomMessage`'s nextTurn branch pushes
+ * synchronously and unconditionally, so any of those early exits strands the
+ * pushed guidance in the queue to attach itself to whichever LATER, unrelated
+ * prompt happens to reach the drain first.
+ *
+ * There is no public SDK seam to observe or cancel a pending nextTurn message
+ * (`_pendingNextTurnMessages` is TS-`private` only — a plain runtime field, not
+ * `#private`), so this reaches into that one field and removes EXACTLY the
+ * entry this call pushed, identified by object identity via a locally-
+ * generated marker riding the message's own `details` field (never surfaced to
+ * the model, and irrelevant if the message WAS consumed normally — `details`
+ * is just carried through like any other field once folded into a real turn).
+ * Runs UNCONDITIONALLY after the human call settles, success or failure/early-
+ * return alike — a "successful" `prompt()` promise can just as easily be an
+ * early return that skipped the drain (an intercepted extension command, an
+ * `input` transform, a streaming reroute) as a genuine consumed turn, so only
+ * checking `.catch` is not enough.
+ */
+export declare function promptWithNextTurnGuidance(session: {
+    sendCustomMessage(message: {
+        customType: string;
+        content: unknown;
+        display?: boolean;
+        details?: unknown;
+    }, options?: {
+        deliverAs?: 'steer' | 'followUp' | 'nextTurn';
+    }): Promise<void>;
+}, guidance: string, runPrompt: () => Promise<void>): Promise<void>;
+/** True iff a parsed JSONL branch-entry line is a hidden (`display:false`)
+ *  custom message — the general display boundary crossed if left in an
+ *  exported branch (not just `crtr-memory-refs` guidance; any hidden custom
+ *  content). Covers both persisted shapes a branch entry can take: a
+ *  `type:'custom_message'` entry (display at the entry's own top level) and a
+ *  `type:'message'` entry wrapping a `role:'custom'` message (display nested
+ *  under `.message`). */
+export declare function isHiddenJsonlBranchEntry(entry: unknown): boolean;
+/** Rewrite an already-exported JSONL file in place, dropping every hidden
+ *  (`display:false`) branch entry while re-chaining `parentId` so the
+ *  remaining entries stay a single valid linear branch — applying the general
+ *  display:false boundary to `session.exportToJsonl`'s own output, which
+ *  serializes every entry verbatim regardless of display. The header line
+ *  (line 1) is copied through untouched. */
+export declare function stripHiddenEntriesFromJsonlExport(filePath: string): void;
+type PendingDialog = {
+    resolve: (response: Extract<ClientToBroker, {
+        type: 'extension_ui_response';
+    }>) => void;
+};
+export type FrameDispatchDeps = {
+    nodeId: string;
+    cfg: BrokerSdkConfig;
+    registry: BrokerClientRegistry;
+    toolGroups: ToolGroupTracker;
+    projection: EventProjection;
+    rebind: RebindDriver;
+    reviewCompanion: boolean;
+    pendingDialogs: Map<string, PendingDialog>;
+    sendWelcome: (client: BrokerClient) => void;
+    replayExtraPendingDialogsTo: (client: BrokerClient) => void;
+    reWelcomeAll: () => void;
+    disposeAndExit: (reason: string, status?: number) => void;
+    persistModelChoice: (pinnedOverride?: boolean, userSelected?: boolean) => Promise<string | null>;
+    broadcastModelChanged: (persist?: boolean, pinnedOverride?: boolean, userSelected?: boolean) => Promise<void>;
+    registryOf: (services: AgentSessionServices) => ModelRegistry;
+    formatModelSpec: (model: BrokerSession['model'], thinkingLevel?: string) => string | null;
+    formatExactModelSpec: (model: BrokerSession['model'], thinkingLevel?: string) => string | null;
+    resolveLaunchModel: (services: AgentSessionServices, cfg: BrokerSdkConfig) => Promise<{
+        model: NonNullable<ReturnType<ModelRegistry['find']>>;
+        thinkingLevel: string | undefined;
+    } | undefined>;
+};
+export type FrameDispatchContext = ReturnType<typeof createFrameDispatchContext>;
+/** Owns frame-local input state while dispatching through explicit broker collaborators. */
+export declare function createFrameDispatchContext(deps: FrameDispatchDeps): {
+    handlers: {
+        hello: (client: BrokerClient, frame: Extract<ClientToBroker, {
+            type: "hello";
+        }>) => void;
+        drive: (client: BrokerClient, frame: Extract<ClientToBroker, {
+            type: "prompt" | "steer" | "follow_up" | "abort" | "bash";
+        }>) => void;
+        deliver: (client: BrokerClient, frame: Extract<ClientToBroker, {
+            type: "deliver";
+        }>) => void;
+        dialog: (client: BrokerClient, frame: Extract<ClientToBroker, {
+            type: "extension_ui_response";
+        }>) => void;
+        engineControl: (client: BrokerClient, frame: Extract<ClientToBroker, {
+            type: "set_model" | "deliver_custom_message" | "cycle_model" | "cycle_ladder" | "cycle_thinking" | "dequeue" | "set_thinking_level" | "set_auto_retry" | "set_auto_compaction" | "compact" | "set_session_name";
+        }>) => void;
+        read: (client: BrokerClient, frame: Extract<ClientToBroker, {
+            type: "get_commands" | "list_models" | "list_scoped_models" | "list_memory_refs" | "get_tree" | "get_settings" | "list_sessions" | "get_human_fork_coordinates";
+        }>) => void;
+        session: (client: BrokerClient, frame: Extract<ClientToBroker, {
+            type: "navigate_tree" | "reload" | "export" | "new_session" | "switch_session" | "fork" | "clone" | "share";
+        }>) => void;
+        authentication: (client: BrokerClient, frame: Extract<ClientToBroker, {
+            type: "reload_auth";
+        }>) => void;
+        bye: (client: BrokerClient) => void;
+        shutdown: () => void;
+    };
+    kickoff(prompt: string): void;
+    notifyTurnAccepted: () => void;
+    pendingPromptDispatches: () => number;
+    resetForSession: () => void;
+};
+/** The socket listener calls this explicit dispatcher for every decoded client frame. */
+export declare function handleFrame(ctx: FrameDispatchContext, client: BrokerClient, frame: ClientToBroker): void;
+export {};