@north-light/crouter 0.3.233 → 0.3.234

package/dist/core/runtime/broker/auth-reload.js

@@ -0,0 +1,149 @@
+import { AUTH_FAULT_RECOVERY_BODY, formatCard, } from '../../../shared/generated-context.js';
+import { envModelIntent } from '../../../shared/env.js';
+import { emitEvent } from '../../events/emit.js';
+import { clearFault, readFault } from '../fault.js';
+import { isUnknownModel } from '../model-selection.js';
+export function createAuthReloadGate(deps) {
+    const { nodeId, cfg, replies, rebind, session, services, broadcastModelChanged, formatModelSpec, resolveLaunchModel, driveKickoff, } = deps;
+    let reloadInFlight = null;
+    let faultRedriveInFlight = false;
+    /** True once the engine this work started against has been replaced — every
+     *  step of both flows re-checks it before touching the session again. */
+    const supersededBy = (generation, boundSession) => rebind.installedGeneration() !== generation || session() !== boundSession;
+    /** Rebuild the model snapshot against re-read credentials and reconcile the
+     *  session's model with the launch route. */
+    const runAuthReload = async (generation, authSession, authServices) => {
+        // Credentials are read fresh by PoolCredentialStore; only the
+        // ModelRuntime snapshot needs rebuilding. Authentication reloads
+        // never fetch provider catalogs over the network.
+        await authServices.modelRuntime.refresh({ allowNetwork: false });
+        if (supersededBy(generation, authSession))
+            return;
+        const modelLess = authSession.model === undefined || isUnknownModel(authSession.model);
+        const reconcilesLogicalRoute = cfg.modelExact !== true &&
+            cfg.modelProviderPinned !== true &&
+            (envModelIntent() ?? '').trim() !== '';
+        if (modelLess || reconcilesLogicalRoute) {
+            const resolved = await resolveLaunchModel(authServices, cfg);
+            if (supersededBy(generation, authSession))
+                return;
+            if (resolved !== undefined) {
+                const currentSpec = formatModelSpec(authSession.model, authSession.thinkingLevel);
+                const resolvedSpec = formatModelSpec(resolved.model, resolved.thinkingLevel);
+                if (resolvedSpec !== null && resolvedSpec !== currentSpec) {
+                    await authSession.setModel(resolved.model);
+                    if (supersededBy(generation, authSession))
+                        return;
+                    authSession.setThinkingLevel((resolved.thinkingLevel ?? 'off'));
+                }
+            }
+        }
+        if (supersededBy(generation, authSession))
+            return;
+        // Persist an algorithmic route choice without clearing the logical
+        // intent that makes future reconciliation possible.
+        await broadcastModelChanged();
+        driveKickoff();
+    };
+    /** Start (or join) this generation's reconcile. */
+    const startAuthReload = () => {
+        const generation = rebind.installedGeneration();
+        const existing = reloadInFlight;
+        if (existing !== null && existing.generation === generation)
+            return existing.promise;
+        if (generation === undefined)
+            return undefined;
+        const authSession = session();
+        const authServices = services();
+        const promise = runAuthReload(generation, authSession, authServices).catch((err) => {
+            emitEvent({
+                level: 'warn',
+                event: 'broker.auth_reload.reconcile_failed',
+                error: err,
+            });
+        });
+        const work = { generation, promise };
+        reloadInFlight = work;
+        void promise.finally(() => {
+            if (reloadInFlight === work)
+                reloadInFlight = null;
+        });
+        return promise;
+    };
+    /** Rewind to the entry the recorded auth fault killed and re-drive the turn
+     *  with the recovery prompt — once, after the reconcile it depends on. */
+    const redriveAuthFault = (reload) => {
+        const authFault = readFault(nodeId);
+        const generation = rebind.installedGeneration();
+        const faultSession = session();
+        if (authFault?.link !== 'pi→provider' ||
+            authFault.kind !== 'auth' ||
+            faultSession.isStreaming ||
+            faultRedriveInFlight)
+            return;
+        faultRedriveInFlight = true;
+        void (async () => {
+            try {
+                if (reload !== undefined)
+                    await reload;
+                if (supersededBy(generation, faultSession))
+                    return;
+                const anchorEntryId = authFault.anchorEntryId;
+                if (anchorEntryId !== undefined) {
+                    try {
+                        const leafId = faultSession.sessionManager.getLeafId?.() ?? null;
+                        if (leafId !== anchorEntryId)
+                            await faultSession.navigateTree(anchorEntryId);
+                        if (supersededBy(generation, faultSession))
+                            return;
+                    }
+                    catch (err) {
+                        emitEvent({
+                            level: 'warn',
+                            event: 'broker.auth_fault.rewind_skipped',
+                            error: err,
+                        });
+                    }
+                }
+                const fresh = readFault(nodeId);
+                if (supersededBy(generation, faultSession) ||
+                    faultSession.isStreaming ||
+                    fresh?.link !== 'pi→provider' ||
+                    fresh.kind !== 'auth' ||
+                    fresh.since !== authFault.since)
+                    return;
+                clearFault(nodeId, { link: 'pi→provider' });
+                await faultSession.prompt(formatCard('recovery', {}, AUTH_FAULT_RECOVERY_BODY));
+            }
+            catch (err) {
+                emitEvent({
+                    level: 'error',
+                    event: 'broker.auth_fault.redrive_failed',
+                    error: err,
+                });
+            }
+            finally {
+                faultRedriveInFlight = false;
+            }
+        })();
+    };
+    return {
+        inFlight: () => reloadInFlight?.promise,
+        handle(client) {
+            // Open to any client, observers included: reload_auth is an idempotent
+            // local re-read of shared credentials + the runtime's availability
+            // snapshot. It does not steer the conversation, so the daemon's
+            // canvas-wide /login fan can ride an observer connection.
+            try {
+                replies.ackTo(client, 'reload_auth');
+                redriveAuthFault(startAuthReload());
+            }
+            catch (err) {
+                replies.engineErrorTo(client)(err);
+            }
+        },
+        resetForSession() {
+            reloadInFlight = null;
+        },
+    };
+}

package/dist/core/runtime/broker/engine-drive.d.ts

@@ -0,0 +1,26 @@
+import type { ClientToBroker } from '../broker-protocol.js';
+import type { BrokerClient, BrokerClientRegistry } from './client-registry.js';
+import type { EventProjection } from './event-projection.js';
+import type { MemoryRefGuidance } from './frame-memory-refs.js';
+import type { FrameReplies } from './frame-replies.js';
+import type { AuthReloadGate } from './auth-reload.js';
+import type { BrokerSession } from './read-ops.js';
+import type { RebindDriver } from './rebind.js';
+import type { ToolGroupTracker } from './tool-groups.js';
+import type { PromptDispatchTracker } from './turn-ignition.js';
+/** The frames that drive the live engine — the viewer's input vocabulary. */
+export type DriveFrame = Extract<ClientToBroker, {
+    type: 'prompt' | 'steer' | 'follow_up' | 'abort' | 'bash';
+}>;
+export type EngineDriver = (client: BrokerClient, frame: DriveFrame) => Promise<unknown> | undefined;
+export declare function createEngineDriver(deps: {
+    registry: BrokerClientRegistry;
+    replies: FrameReplies;
+    session: () => BrokerSession;
+    dispatches: PromptDispatchTracker;
+    memoryRefs: MemoryRefGuidance;
+    authReloadGate: AuthReloadGate;
+    rebind: RebindDriver;
+    projection: EventProjection;
+    toolGroups: ToolGroupTracker;
+}): EngineDriver;

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

@@ -0,0 +1,257 @@
+import { emitEvent } from '../../events/emit.js';
+import { operationIdContext } from '../../events/operation-id.js';
+import { promptWithAdvertisedCommandInvocation } from '../advertised-command-invocation.js';
+import { chooseGuidanceDeliveryMode, promptWithNextTurnGuidance, resolveEngineRoute, resolveSteerCall, } from './engine-routing.js';
+export function createEngineDriver(deps) {
+    const { registry, replies, session, dispatches, memoryRefs, authReloadGate, rebind, projection, toolGroups, } = deps;
+    const { ackTo, engineErrorTo } = replies;
+    const errorRelay = (client) => {
+        let failure;
+        return {
+            relay: (err) => {
+                failure = err;
+                registry.sendFrame(client, {
+                    type: 'error',
+                    code: 'engine_error',
+                    message: String(err),
+                });
+            },
+            failure: () => failure,
+        };
+    };
+    // Hidden `crtr-memory-refs` guidance rides ALONGSIDE the human frame's own
+    // engine call, never rewriting `frame.text` — see MemoryRefGuidance /
+    // chooseGuidanceDeliveryMode. A failed SEND (as opposed to a failed
+    // resolve, handled above) is likewise logged-and-swallowed: it must never
+    // reach the error relay, which is reserved for the human call's own outcome.
+    const sendGuidance = (guidance, deliverAs) => session()
+        .sendCustomMessage({ customType: 'crtr-memory-refs', content: guidance, display: false }, { deliverAs })
+        .catch((err) => {
+        emitEvent({
+            level: 'warn',
+            event: 'broker.memory_refs.guidance_send_failed',
+            error: err,
+        });
+    });
+    const drivePromptOrFollowUp = (client, frame, errors) => {
+        const relayError = errors.relay;
+        // Settle on the engine call's outcome: the failure is set by relayError
+        // before the caught promise resolves, so reading it after the chain is
+        // the call's verdict.
+        const settle = (p) => p.then(() => errors.failure());
+        const dispatch = () => {
+            const route = resolveEngineRoute(frame, session().isStreaming);
+            const guidance = memoryRefs.guidanceFor(frame.text);
+            if (guidance === null) {
+                if (route.call === 'prompt') {
+                    // A routed prompt STARTS a turn — including an idle follow_up
+                    // escalated by m-C — so it gets a fresh operation id. A true
+                    // (mid-stream) followUp rides the current turn's operation, like
+                    // steer.
+                    return settle(dispatches.track(operationIdContext.fresh(() => promptWithAdvertisedCommandInvocation(session(), frame.text, () => session().prompt(frame.text, route.options)).catch(relayError))));
+                }
+                // C1: pi's followUp() takes images as a POSITIONAL 2nd arg (`followUp(text, images?)`).
+                return settle(session().followUp(frame.text, frame.images).catch(relayError));
+            }
+            const deliverAs = chooseGuidanceDeliveryMode(frame.type, route.call, session().isStreaming);
+            if (route.call === 'prompt') {
+                if (deliverAs === 'nextTurn') {
+                    // The ONLY ordering where guidance precedes the human call — pi's
+                    // prompt() reads+clears its pending-nextTurn queue synchronously
+                    // at call time, injecting it into the SAME turn as the new user
+                    // message. promptWithNextTurnGuidance queues the guidance and then
+                    // ATOMICALLY clears its own pending entry if prompt() settles
+                    // without ever reaching that drain (an early throw/return leaves
+                    // nothing stranded to leak into a later, unrelated turn).
+                    return settle(dispatches.track(promptWithNextTurnGuidance(session(), guidance, () => operationIdContext.fresh(() => promptWithAdvertisedCommandInvocation(session(), frame.text, () => session().prompt(frame.text, route.options)))).catch(relayError)));
+                }
+                return settle(dispatches.track(operationIdContext.fresh(() => promptWithAdvertisedCommandInvocation(session(), frame.text, () => session().prompt(frame.text, route.options))
+                    .catch(relayError)
+                    .then(() => sendGuidance(guidance, deliverAs)))));
+            }
+            // deliverAs is always 'followUp' here per chooseGuidanceDeliveryMode's
+            // contract (a followUp routeCall never yields 'nextTurn').
+            return settle(session()
+                .followUp(frame.text, frame.images)
+                .catch(relayError)
+                .then(() => sendGuidance(guidance, deliverAs)));
+        };
+        // /login acknowledges before its asynchronous local refresh completes.
+        // An idle turn must not overtake that refresh and launch on the stale
+        // route; true mid-stream follow-ups keep their immediate queue behavior.
+        const authReload = session().isStreaming
+            ? undefined
+            : authReloadGate.inFlight();
+        if (authReload === undefined)
+            return dispatch();
+        const waitingGeneration = rebind.installedGeneration();
+        const waitingSession = session();
+        return authReload.then(() => {
+            if (rebind.installedGeneration() !== waitingGeneration ||
+                session() !== waitingSession) {
+                relayError(new Error('session changed while prompt waited for authentication reload'));
+                return errors.failure();
+            }
+            return dispatch();
+        });
+    };
+    /**
+     * `prompt { interrupt: true }` is one atomic viewer intention: end whatever
+     * is producing now, then start this as a new turn. A normal mid-stream
+     * prompt deliberately steers into pi's queue; the whip must not.
+     */
+    const driveInterruptPrompt = (client, frame, errors) => (async () => {
+        if (session().isBashRunning) {
+            session().abortBash();
+        }
+        else {
+            // A prompt can be in pi's async setup before isStreaming flips. Match
+            // the correlated interrupt's guard so a whip cannot silently miss it.
+            await dispatches.waitUntilAbortable();
+            if (session().isStreaming)
+                await session().abort();
+        }
+        return drivePromptOrFollowUp(client, {
+            type: 'prompt',
+            text: frame.text,
+            ...(frame.images !== undefined ? { images: frame.images } : {}),
+        }, errorRelay(client));
+    })().catch((err) => {
+        errors.relay(err);
+        return errors.failure();
+    });
+    /**
+     * A viewer submits ordinary text as `steer` while the agent is running,
+     * including a slash command injected by the tmux prefix menu. pi's steer()
+     * deliberately rejects registered extension commands because they cannot be
+     * queued; prompt() performs the command preflight first and executes it
+     * immediately even while streaming. It also expands a matching
+     * skill/template before applying the same steer behavior.
+     */
+    const driveSteer = (frame, errors) => {
+        const relayError = errors.relay;
+        if (resolveSteerCall(frame.text, session()) === 'prompt') {
+            void promptWithAdvertisedCommandInvocation(session(), frame.text, () => session().prompt(frame.text, {
+                images: frame.images,
+                streamingBehavior: 'steer',
+            })).catch(relayError);
+            return;
+        }
+        const guidance = memoryRefs.guidanceFor(frame.text);
+        // C1: pi's steer() takes images as a POSITIONAL 2nd arg (`steer(text, images?)`).
+        if (guidance === null) {
+            void session().steer(frame.text, frame.images).catch(relayError);
+            return;
+        }
+        void session()
+            .steer(frame.text, frame.images)
+            .catch(relayError)
+            .then(() => sendGuidance(guidance, 'steer'));
+    };
+    /**
+     * esc/abort cancels whatever is live: a running `!` command (abortBash)
+     * takes precedence over the agent turn, mirroring pi interactive mode.
+     */
+    const driveAbort = (client, frame, errors) => {
+        if (session().isBashRunning) {
+            session().abortBash();
+            if (frame.id !== undefined)
+                ackTo(client, 'abort', true, 'bash', frame.id);
+            return;
+        }
+        if (frame.id === undefined) {
+            // A viewer's Esc — unchanged instant semantics, no ack.
+            void session().abort().catch(errors.relay);
+            return;
+        }
+        // An id-bearing abort (a one-shot daemon interrupt) must close the
+        // pre-turn window: a routed deliver whose prompt() is still in async
+        // setup reads as idle and abort() would silently miss it. If a prompt
+        // dispatch is pending, wait (bounded) for the run to become abortable
+        // — or for every dispatch to settle without one (an early return) —
+        // then abort and ack with what was actually interrupted.
+        void (async () => {
+            try {
+                await dispatches.waitUntilAbortable();
+                const detail = session().isStreaming ? 'turn' : 'idle';
+                await session().abort();
+                ackTo(client, 'abort', true, detail, frame.id);
+            }
+            catch (err) {
+                engineErrorTo(client, frame.id)(err);
+            }
+        })();
+    };
+    /**
+     * `!`/`!!` bash: run via session.executeBash (records a bashExecution context
+     * message, starts NO agent turn) and relay its lifecycle to ALL viewers as
+     * bash_start/bash_output/bash_end so each renders the live component.
+     * Serialized like pi's interactive mode — reject a second `!` while one is
+     * already running rather than racing _bashAbortController.
+     */
+    const driveBash = (client, frame, errors) => {
+        const command = frame.command;
+        if (command.trim() === '')
+            return;
+        if (session().isBashRunning) {
+            registry.sendFrame(client, {
+                type: 'error',
+                code: 'bash_busy',
+                message: 'A bash command is already running',
+            });
+            return;
+        }
+        const exclude = frame.excludeFromContext === true;
+        // Order before any held assistant message_update, so a `!` run mid-stream
+        // never renders ahead of the update it follows.
+        projection.flush();
+        // The live bash component is a visible transcript boundary, even though
+        // its persisted bashExecution message arrives later via the session.
+        toolGroups.finishOpenToolGroup();
+        registry.broadcast({
+            type: 'bash_start',
+            command,
+            excludeFromContext: exclude,
+        });
+        void session()
+            .executeBash(command, (chunk) => registry.broadcast({ type: 'bash_output', chunk }), { excludeFromContext: exclude })
+            .then((result) => {
+            registry.broadcast({
+                type: 'bash_end',
+                exitCode: result.exitCode,
+                cancelled: result.cancelled,
+                truncated: result.truncated,
+                fullOutputPath: result.fullOutputPath,
+            });
+        })
+            .catch(errors.relay);
+    };
+    /**
+     * Drive the engine for one client frame. For a prompt/follow_up frame this
+     * returns a promise that settles with the engine call's OUTCOME — `undefined`
+     * when the call succeeded, the rejection value when it did not — so a caller
+     * that must report success (the `deliver` ack) can read it instead of assuming
+     * the dispatch worked. Every other frame type keeps the fire-and-forget shape
+     * and returns `undefined`.
+     */
+    return (client, frame) => {
+        const errors = errorRelay(client);
+        switch (frame.type) {
+            case 'prompt':
+                return frame.interrupt === true
+                    ? driveInterruptPrompt(client, frame, errors)
+                    : drivePromptOrFollowUp(client, frame, errors);
+            case 'follow_up':
+                return drivePromptOrFollowUp(client, frame, errors);
+            case 'steer':
+                driveSteer(frame, errors);
+                return undefined;
+            case 'abort':
+                driveAbort(client, frame, errors);
+                return undefined;
+            case 'bash':
+                driveBash(client, frame, errors);
+                return undefined;
+        }
+    };
+}

package/dist/core/runtime/broker/engine-routing.d.ts

@@ -0,0 +1,143 @@
+import type { PromptOptions } from '@earendil-works/pi-coding-agent';
+import type { ImageContent } from '@earendil-works/pi-ai';
+/**
+ * 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>;