@north-light/crouter 0.3.233 → 0.3.235

package/dist/core/runtime/broker/engine-routing.js

@@ -0,0 +1,211 @@
+import { randomUUID } from 'node:crypto';
+import { emitEvent } from '../../events/emit.js';
+/**
+ * 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 function resolveEngineRoute(frame, isStreaming) {
+    if (frame.type === 'follow_up' && isStreaming)
+        return { call: 'followUp' };
+    const options = {};
+    if (frame.images !== undefined)
+        options.images = frame.images;
+    if (isStreaming)
+        options.streamingBehavior = 'steer';
+    return { call: 'prompt', options };
+}
+/**
+ * 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 function isLeadingEngineCommand(text, session) {
+    if (text.startsWith('/')) {
+        const spaceIndex = text.indexOf(' ');
+        const commandName = spaceIndex === -1 ? text.slice(1) : text.slice(1, spaceIndex);
+        try {
+            if (session.extensionRunner?.getCommand(commandName))
+                return true;
+        }
+        catch {
+            /* engine without a live extensionRunner (e.g. the fake) — not a match */
+        }
+    }
+    if (text.startsWith('/skill:')) {
+        const spaceIndex = text.indexOf(' ');
+        const skillName = spaceIndex === -1 ? text.slice(7) : text.slice(7, spaceIndex);
+        try {
+            if (session.resourceLoader?.getSkills().skills.some((s) => s.name === skillName))
+                return true;
+        }
+        catch {
+            /* engine without a live resourceLoader — not a match */
+        }
+    }
+    if (text.startsWith('/')) {
+        const match = text.match(/^\/([^\s]+)(?:\s+([\s\S]*))?$/);
+        const templateName = match?.[1];
+        if (templateName !== undefined) {
+            try {
+                if (session.promptTemplates?.some((t) => t.name === templateName))
+                    return true;
+            }
+            catch {
+                /* engine without a live promptTemplates getter — not a match */
+            }
+        }
+    }
+    return false;
+}
+/** 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 function resolveSteerCall(text, session) {
+    return isLeadingEngineCommand(text, session) ? '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 function engineLeadingCommandTokens(session) {
+    const out = [];
+    try {
+        for (const c of session.extensionRunner?.getRegisteredCommands() ?? [])
+            out.push(c.invocationName);
+    }
+    catch {
+        /* engine without a live extensionRunner (e.g. the fake) — none */
+    }
+    try {
+        for (const s of session.resourceLoader?.getSkills().skills ?? [])
+            out.push(`skill:${s.name}`);
+    }
+    catch {
+        /* engine without a live resourceLoader — none */
+    }
+    try {
+        for (const t of session.promptTemplates ?? [])
+            out.push(t.name);
+    }
+    catch {
+        /* engine without a live promptTemplates getter — none */
+    }
+    return out;
+}
+/**
+ * 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 function chooseGuidanceDeliveryMode(frameType, routeCall, isStreaming) {
+    if (frameType === 'steer')
+        return 'steer';
+    if (routeCall === 'followUp')
+        return 'followUp';
+    return isStreaming ? 'steer' : '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 async function promptWithNextTurnGuidance(session, guidance, runPrompt) {
+    // Must survive Pi's structured-clone step when the queued custom message is
+    // folded into the turn. A Symbol reaches that step in `details` and aborts
+    // the real prompt with "could not be cloned" before the provider runs.
+    const marker = `crtr-memory-refs-pending:${randomUUID()}`;
+    let queued = false;
+    try {
+        await session.sendCustomMessage({ customType: 'crtr-memory-refs', content: guidance, display: false, details: marker }, { deliverAs: 'nextTurn' });
+        queued = true;
+    }
+    catch (err) {
+        emitEvent({
+            level: 'warn',
+            event: 'broker.memory_refs.guidance_send_failed',
+            error: err,
+        });
+    }
+    try {
+        await runPrompt();
+    }
+    finally {
+        if (queued)
+            clearOwnPendingNextTurnGuidance(session, marker);
+    }
+}
+/** Splice out exactly the pending-nextTurn entry `marker` identifies (object-
+ *  identity match on `details`), if it is still present — a no-op (and safe)
+ *  if `session.prompt()` already drained it normally, or if the session/field
+ *  shape doesn't match (defensive against an engine without the field, e.g. a
+ *  future SDK bump or a structurally-different test double). */
+function clearOwnPendingNextTurnGuidance(session, marker) {
+    const pending = session._pendingNextTurnMessages;
+    if (!Array.isArray(pending))
+        return;
+    const idx = pending.findIndex((m) => m?.details === marker);
+    if (idx !== -1)
+        pending.splice(idx, 1);
+}

package/dist/core/runtime/broker/event-projection.js

@@ -1,6 +1,7 @@
 import { readConfig } from '../../config.js';
+import { envStreamWatchdogMs } from '../../../shared/env.js';
 import { emitEvent } from '../../events/emit.js';
-import { releaseKnownStreamWait, resolveStreamWatchdogMs, StreamWatchdog } from '../stream-watchdog.js';
+import { releaseKnownStreamWait, StreamWatchdog } from '../stream-watchdog.js';
 import { withoutYieldAbort } from '../session-cycles.js';
 import { DEFAULT_WORKING_ACTIVITY, randomWorkingActivity } from '../../../shared/working-activity.js';
 import { hydrateLiveAdvertisedCommandMessage, prepareAdvertisedCommandPersistence, } from '../advertised-command-invocation.js';
@@ -12,7 +13,7 @@ export class EventProjection {
     pendingUpdateTimer = null;
     workingActivity = DEFAULT_WORKING_ACTIVITY;
     streamWatchdog;
-    streamWatchdogMs = resolveStreamWatchdogMs();
+    streamWatchdogMs = envStreamWatchdogMs();
     pendingBroadcast = null;
     broadcastGeneration = 0;
     constructor(deps) {

package/dist/core/runtime/broker/fault-retry.js

@@ -1,3 +1,4 @@
+import { envModelIntent, envNodeCwd, envProfileId } from '../../../shared/env.js';
 import { isContextOverflow } from '@earendil-works/pi-ai';
 import { classify } from '../../fault-classifier.js';
 import { clearFault, isModelNotFoundError, isProviderUnconfiguredError, readFault, recordFault } from '../fault.js';
@@ -8,6 +9,7 @@ import { emitEvent } from '../../events/emit.js';
 import { CONNECTION_FAULT_RECOVERY_BODY, PROVIDER_FAULT_RECOVERY_BODY, formatCard, formatModelFallbackRecovery } from '../../../shared/generated-context.js';
 import { markFatalOnExhaust, nextFaultRetry, policyFor } from '../fault-recovery.js';
 import { parseModelSpec } from '../model-selection.js';
+import { endedByAbort } from '../session-cycles.js';
 import { resolveProviderCandidates } from '../../subscription-state.js';
 const MAX_TIMEOUT_MS = 2_147_483_647;
 /** Owns provider fallback and daemon-driven fault retry state for one broker session. */
@@ -89,6 +91,11 @@ export class FaultRetry {
         if (refreshAbort)
             return;
         const raw = typeof last.errorMessage === 'string' ? last.errorMessage : 'engine error (no errorMessage recorded)';
+        // An abort landing between requests reaches pi's catch as a bare AbortError
+        // and settles as an error rather than `aborted`. Something asked that turn
+        // to stop, so there is no provider fault to record.
+        if (endedByAbort({ stopReason: 'error', errorMessage: raw }))
+            return;
         const uncompactedOverflow = isContextOverflow(last, settledSession.model?.contextWindow);
         const classified = classify('pi→provider', last);
         const coolingDeadline = extractCoolingDeadline(last);
@@ -140,10 +147,10 @@ export class FaultRetry {
         const currentSpec = this.deps.formatModelSpec(candidateSession.model, candidateSession.thinkingLevel);
         if (currentSpec === null)
             return;
-        const routeRequest = modelRequestFromConfig(this.deps.cfg.model, process.env['CRTR_MODEL_INTENT'], false);
+        const routeRequest = modelRequestFromConfig(this.deps.cfg.model, envModelIntent(), false);
         if (routeRequest === undefined)
             return;
-        const routes = expandModelCandidates(routeRequest, process.env['CRTR_NODE_CWD'] ?? this.deps.cfg.cwd, process.env['CRTR_PROFILE_ID']);
+        const routes = expandModelCandidates(routeRequest, envNodeCwd() ?? this.deps.cfg.cwd, envProfileId());
         const current = parseModelSpec(currentSpec);
         const liveRank = routes.find((candidate) => `${candidate.providerId}/${candidate.modelId}` === current.modelSpec && candidate.thinkingLevel === current.thinkingLevel)?.rank;
         const nextRoute = liveRank === undefined ? undefined : routes.slice(liveRank + 1).find((candidate) => !this.failedRetryRoutes.has(candidate.routeId) && resolveProviderCandidates([{ ...candidate, ...probeRouteAvailability(candidate, this.deps.registryOf(candidateServices)), automaticFallback: true }]).candidates.length > 0);
@@ -183,8 +190,8 @@ export class FaultRetry {
             return;
         const current = parseModelSpec(currentSpec);
         this.notFoundModels.add(current.modelSpec);
-        const routeRequest = modelRequestFromConfig(this.deps.cfg.model, process.env['CRTR_MODEL_INTENT'], false);
-        const routes = routeRequest ? expandModelCandidates(routeRequest, process.env['CRTR_NODE_CWD'] ?? this.deps.cfg.cwd, process.env['CRTR_PROFILE_ID']) : [];
+        const routeRequest = modelRequestFromConfig(this.deps.cfg.model, envModelIntent(), false);
+        const routes = routeRequest ? expandModelCandidates(routeRequest, envNodeCwd() ?? this.deps.cfg.cwd, envProfileId()) : [];
         const liveRank = routes.find((candidate) => `${candidate.providerId}/${candidate.modelId}` === current.modelSpec && candidate.thinkingLevel === current.thinkingLevel)?.rank;
         const nextRoute = liveRank === undefined ? undefined : routes.slice(liveRank + 1).find((candidate) => !this.notFoundModels.has(`${candidate.providerId}/${candidate.modelId}`) && resolveProviderCandidates([{ ...candidate, ...probeRouteAvailability(candidate, this.deps.registryOf(candidateServices)), automaticFallback: true }]).candidates.length > 0);
         if (!nextRoute)

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

@@ -0,0 +1,38 @@
+import { type ClientToBroker } from '../broker-protocol.js';
+import type { BrokerClient, BrokerClientRegistry } from './client-registry.js';
+import type { EngineDriver } from './engine-drive.js';
+import type { FrameReplies } from './frame-replies.js';
+import type { BrokerSession } from './read-ops.js';
+import type { TurnAcceptanceGate } from './turn-ignition.js';
+/** An extension dialog fanned out to writable clients, awaiting the first answer. */
+export type PendingDialog = {
+    resolve: (response: Extract<ClientToBroker, {
+        type: 'extension_ui_response';
+    }>) => void;
+};
+/** The frames about a client's own connection — admission, one-shot delivery,
+ *  dialog answers, and the two ways a socket or the broker ends. */
+export type ClientFrameHandlers = {
+    hello(client: BrokerClient, frame: Extract<ClientToBroker, {
+        type: 'hello';
+    }>): void;
+    deliver(client: BrokerClient, frame: Extract<ClientToBroker, {
+        type: 'deliver';
+    }>): void;
+    dialog(client: BrokerClient, frame: Extract<ClientToBroker, {
+        type: 'extension_ui_response';
+    }>): void;
+    bye(client: BrokerClient): void;
+    shutdown(): void;
+};
+export declare function createClientHandlers(deps: {
+    registry: BrokerClientRegistry;
+    replies: FrameReplies;
+    session: () => BrokerSession;
+    driveEngine: EngineDriver;
+    turnAcceptance: TurnAcceptanceGate;
+    pendingDialogs: Map<string, PendingDialog>;
+    sendWelcome: (client: BrokerClient) => void;
+    replayExtraPendingDialogsTo: (client: BrokerClient) => void;
+    disposeAndExit: (reason: string, status?: number) => void;
+}): ClientFrameHandlers;

package/dist/core/runtime/broker/frame-client.js

@@ -0,0 +1,129 @@
+import { SITUATIONAL_CONTEXT_CUSTOM_TYPE } from '../../../shared/generated-context.js';
+import { emitEvent } from '../../events/emit.js';
+import { normalizeSnapshotTail } from '../broker-protocol.js';
+export function createClientHandlers(deps) {
+    const { registry, replies, session, driveEngine, turnAcceptance, pendingDialogs, sendWelcome, replayExtraPendingDialogsTo, disposeAndExit, } = deps;
+    const { notWritable, ackTo } = replies;
+    return {
+        hello(client, frame) {
+            // Admit at the REQUESTED role — unconditionally. `controller` is a
+            // per-client write capability, not a singleton slot, so an arriving
+            // writable client never demotes (or is demoted by) an already-attached
+            // one: attached terminal panes are all writable at once.
+            //
+            // A repeated hello on an already-helloed socket must not RE-role it: the
+            // role is fixed for the socket's lifetime, so every downstream gate and
+            // every already-fanned-out dialog keep the authority the first welcome
+            // stated. A duplicate hello still re-sends the catch-up snapshot.
+            const firstHello = !client.helloed;
+            client.id = frame.client_id;
+            client.snapshotTail = normalizeSnapshotTail(frame.snapshot_tail);
+            if (firstHello) {
+                client.helloed = true;
+                client.role = frame.role === 'controller' ? 'controller' : 'observer';
+                client.attends = frame.attends !== false;
+            }
+            sendWelcome(client);
+            if (firstHello)
+                registry.persistAttachState(); // a helloed viewer arrived
+            // welcome carried the FIRST pending dialog; replay any extras so a writable
+            // client attaching mid-dialog can answer every in-flight dialog.
+            if (client.role === 'controller')
+                replayExtraPendingDialogsTo(client);
+        },
+        deliver(client, frame) {
+            // Interactive delivery from a one-shot server client (crtrd's
+            // `POST /messages` `delivery:'interactive'` path). Routed HERE,
+            // broker-side, because only the broker authoritatively knows streaming
+            // state: the synthesized `prompt` frame reuses resolveEngineRoute's m-B
+            // routing (idle → prompt(); mid-stream → prompt({streamingBehavior:
+            // 'steer'}), pi's own Enter-while-streaming submit) plus the memory-refs
+            // guidance path — byte-identical behavior to a viewer's Enter. Acked
+            // once ACCEPTED (correlated by the frame's id) so the daemon returns
+            // deterministically; `detail` reports which route was taken.
+            //
+            // The ack reports the engine call's OUTCOME, never merely the fact that
+            // a call was made: the session's prompt() rejects outright when the
+            // model's provider has no credential, and acking unconditionally reported
+            // `delivered:true` for a message the engine had refused — the caller's
+            // one-shot client then closed before the error frame arrived and the
+            // message vanished with no trace. A prompt route therefore acks on the
+            // race between acceptance (agent_start) and rejection; a steer route
+            // joins a turn already running, so no new agent_start is coming and its
+            // ack stays at routing time.
+            if (notWritable(client, 'drive the engine', frame.id))
+                return;
+            const via = session().isStreaming ? 'steer' : 'prompt';
+            // Ordered context cards ahead of the body, inside this ONE frame handling,
+            // so no other client's send can interleave between a card and its body.
+            // Nothing is awaited: `sendCustomMessage` completes synchronously on both
+            // branches that apply here — idle appends to the session and starts NO turn
+            // (the body is the sole trigger), streaming queues on the same steer queue
+            // the body's `prompt({streamingBehavior:'steer'})` uses, preserving order.
+            for (const card of frame.cards ?? []) {
+                void session()
+                    .sendCustomMessage({
+                    customType: SITUATIONAL_CONTEXT_CUSTOM_TYPE,
+                    content: card,
+                    display: true,
+                }, via === 'steer' ? { deliverAs: 'steer' } : undefined)
+                    .catch((error) => emitEvent({
+                    level: 'error',
+                    event: 'broker.deliver.card_failed',
+                    error,
+                }));
+            }
+            let delivered = false;
+            const ackAccepted = () => {
+                if (delivered)
+                    return;
+                delivered = true;
+                ackTo(client, 'deliver', true, via, frame.id);
+            };
+            if (via === 'prompt')
+                turnAcceptance.waitFor(ackAccepted);
+            const outcome = driveEngine(client, {
+                type: 'prompt',
+                text: frame.text,
+                ...(frame.images !== undefined ? { images: frame.images } : {}),
+            });
+            if (via === 'steer' || outcome === undefined) {
+                turnAcceptance.cancel(ackAccepted);
+                ackAccepted();
+                return;
+            }
+            void outcome.then((failure) => {
+                turnAcceptance.cancel(ackAccepted);
+                if (failure === undefined) {
+                    ackAccepted();
+                    return;
+                }
+                // The error frame already went to the client, but a one-shot deliver
+                // client is gone by then — record it where it survives.
+                emitEvent({
+                    level: 'error',
+                    event: 'broker.prompt.deliver_failed',
+                    error: failure,
+                });
+                if (delivered)
+                    return;
+                delivered = true;
+                ackTo(client, 'deliver', false, String(failure), frame.id);
+            });
+        },
+        dialog(client, frame) {
+            if (notWritable(client, 'answer dialogs'))
+                return;
+            // First response for this id wins: `resolve` settles the entry and deletes
+            // it, so every later response from a peer that was also fanned this dialog
+            // finds nothing here and is a silent no-op.
+            pendingDialogs.get(frame.id)?.resolve(frame);
+        },
+        bye(client) {
+            client.socket.end();
+        },
+        shutdown() {
+            disposeAndExit('shutdown-frame');
+        },
+    };
+}