@north-light/api 0.3.580 → 0.3.587

package/dist/core/runtime/broker/model-adapter.js

@@ -0,0 +1,413 @@
+import { setTimeout as sleep } from 'node:timers/promises';
+import { createAssistantMessageEventStream, getCurrentSystemPrompt, getCurrentTools, } from '@earendil-works/pi-ai';
+import { socketFetch } from '../../../api/node-transport.js';
+import { DEFER_HEAD_REQUEST_HEADER, DEFERRED_HEAD_CONTENT_TYPE, DEFERRED_HEAD_MAGIC } from '../../../daemon/api/deferred-head.js';
+import { apiSocketPath } from '../../canvas/paths.js';
+import { northlightUnreachable } from '../../directory/reach.js';
+import { currentNodeToken } from './node-token.js';
+import { brokerApiUrl } from './daemon-ops.js';
+import { currentCausedBy } from './turn-cause.js';
+import { envModelExact, envModelIntent } from '../../../shared/env.js';
+import { MODEL_CONTEXT_BODY_MAX_BYTES } from '../../llm/body-limits.js';
+import { modelRequestFromConfig } from '../../model-routes.js';
+import { parseProviderRateLimit, providerFailureDiagnostic } from '../../provider-failure.js';
+import { UPSTREAM_MODEL_UNAVAILABLE } from '../../fault-classifier.js';
+/** Pi uses availability and auth for its model controls; only the daemon can
+ * decide whether a route has credentials. Keep the broker's metadata selectable. */
+export function configureBrokerModelRuntime(runtime, intent) {
+    runtime.checkAuth = async (provider) => runtime.getProvider(provider) ? { type: 'api_key' } : undefined;
+    runtime.getAvailable = async (provider) => runtime.getModels(provider);
+    runtime.getAvailableSnapshot = () => runtime.getModels();
+    runtime.streamSimple = (model, context, options) => streamBrokerModel(model, context, options, intent);
+}
+export const LLM_BROKER_RETRY_WINDOW_S = 300;
+export const LLM_REFUSAL_DIAGNOSTIC = 'crtr:llm-refusal';
+class LlmRefusalError extends Error {
+    retryAt;
+    rateLimit;
+    code;
+    status;
+    /** Epoch ms the daemon said the refused route frees up, when it gave one. */
+    /** `code`: the daemon's error code (`cap_exhausted` settles a run's root as such). */
+    constructor(message, retryAt, rateLimit, code, status) {
+        super(message);
+        this.retryAt = retryAt;
+        this.rateLimit = rateLimit;
+        this.code = code;
+        this.status = status;
+    }
+}
+/** A retryable `upstream_model_unavailable` refusal without a wait hint. */
+class UpstreamModelUnavailableError extends Error {
+}
+/** The request body is past what the daemon's `/v1/llm` route (or the vendor behind it) accepts.
+ *  This is a context-size problem, not a refusal: the message carries `request_too_large`, the
+ *  token pi-ai's `isContextOverflow` recognises (Anthropic's own HTTP 413 error type), so pi's
+ *  agent session compacts the conversation and retries the turn instead of the broker recording
+ *  a fatal `crtr:llm-refusal`. Compaction summarises older turns as text, which drops their
+ *  inline images. */
+function contextTooLargeError(bytes, limit) {
+    const size = bytes === undefined ? 'the request body' : `the request body (${bytes} bytes)`;
+    return new Error(`request_too_large: ${size} exceeds the ${limit}-byte model request limit; compact the conversation to shrink the context`);
+}
+/** The vendor 429 the daemon relayed on an exhausted refusal (`details.rate_limit`): its scope and rate-limit headers. */
+function refusalRateLimit(error) {
+    const raw = error.details?.rate_limit;
+    if (!raw || typeof raw !== 'object')
+        return undefined;
+    const parsed = parseProviderRateLimit(raw);
+    if (parsed === undefined)
+        return undefined;
+    const { provider, model } = raw;
+    // The daemon reports provider and model separately; the fault names the route as `provider/model`.
+    return typeof provider === 'string' && provider !== '' && typeof model === 'string' && model !== '' ? { ...parsed, model: `${provider}/${model}` } : parsed;
+}
+/** The retry deadline (epoch ms) a final daemon refusal carried on its
+ *  diagnostic, or undefined when the refusal named none. */
+export function refusalRetryAt(message) {
+    for (const diagnostic of message.diagnostics ?? []) {
+        if (diagnostic.type !== LLM_REFUSAL_DIAGNOSTIC)
+            continue;
+        const raw = diagnostic.details?.retryAt;
+        if (typeof raw === 'number' && Number.isFinite(raw) && raw > 0)
+            return raw;
+    }
+    return undefined;
+}
+/** The daemon answered `finish_reason: content_filter`: the vendor refused the
+ *  call on safety grounds. The catch records it as pi does for a direct vendor
+ *  refusal, so `isSafetyRefusal` reads it the same way on both paths. */
+class ContentFilteredError extends Error {
+}
+function wireContent(content) {
+    if (typeof content === 'string')
+        return content;
+    return content.map((part) => part.type === 'text'
+        ? { type: 'text', text: part.text }
+        : { type: 'image_url', image_url: { url: `data:${part.mimeType};base64,${part.data}` } });
+}
+/** Messages the wire request carries. An errored or aborted assistant is an
+ *  incomplete turn that pi-ai's own serializers omit; this adapter bypasses
+ *  them, so drop it here. A request must also end on a non-assistant message
+ *  (Anthropic rejects assistant prefill with a 400), so trailing assistants go
+ *  too. */
+export function wireHistory(messages) {
+    const incomplete = (message) => message.role === 'assistant' && (message.stopReason === 'error' || message.stopReason === 'aborted');
+    const kept = messages.some(incomplete) ? messages.filter((message) => !incomplete(message)) : messages;
+    let end = kept.length;
+    while (end > 0 && kept[end - 1]?.role === 'assistant')
+        end--;
+    return end === kept.length ? kept : kept.slice(0, end);
+}
+export function requestBody(model, context, options, intentOverride) {
+    const messages = [];
+    const system = getCurrentSystemPrompt(context.messages);
+    const tools = getCurrentTools(context.messages);
+    if (system)
+        messages.push({ role: 'system', content: system });
+    else if (context.systemPrompt)
+        messages.push({ role: 'system', content: context.systemPrompt });
+    for (const message of wireHistory(context.messages)) {
+        if (message.role === 'user') {
+            messages.push({ role: 'user', content: wireContent(message.content) });
+        }
+        else if (message.role === 'toolResult') {
+            messages.push({ role: 'tool', content: wireContent(message.content), tool_call_id: message.toolCallId });
+        }
+        else if (message.role === 'assistant') {
+            messages.push({ role: 'assistant', content: message.content.filter((part) => part.type === 'text').map((part) => part.text).join('') || null,
+                tool_calls: message.content.filter((part) => part.type === 'toolCall').map((part) => ({ id: part.id, type: 'function', function: { name: part.name, arguments: JSON.stringify(part.arguments) } })) });
+        }
+    }
+    const concrete = `${model.provider}/${model.id}`;
+    const intent = intentOverride ?? envModelIntent();
+    return {
+        model: modelRequestFromConfig(concrete, intent, envModelExact())?.kind === 'logical'
+            ? intent
+            : concrete,
+        model_policy: envModelExact() ? 'exact' : 'substitute',
+        stream: true,
+        messages,
+        ...(tools.length ? { tools: tools.map((tool) => ({ type: 'function', function: { name: tool.name, description: tool.description, parameters: tool.parameters } })) } : {}),
+        ...(options.reasoning ? { reasoning_effort: options.reasoning } : {}),
+        ...(options.temperature !== undefined ? { temperature: options.temperature } : {}),
+        ...(options.maxTokens !== undefined ? { max_tokens: options.maxTokens } : {}),
+    };
+}
+/** Point the message at the route the daemon actually tried. The broker's own
+ *  model is only the nominal label it launched with; when the daemon substituted
+ *  (or a refusal names the failed route) the turn belongs to that route. */
+function applyServedModel(message, served) {
+    if (typeof served !== 'string')
+        return false;
+    const slash = served.indexOf('/');
+    if (slash < 1 || slash === served.length - 1)
+        return false;
+    message.provider = served.slice(0, slash);
+    message.model = served.slice(slash + 1);
+    return true;
+}
+/** The route a refusal belongs to: the `served_model` the daemon named, else the
+ *  route of the vendor 429 an exhausted refusal relayed. */
+function refusalRoute(error) {
+    if (error.details?.served_model !== undefined)
+        return error.details.served_model;
+    const limit = error.details?.rate_limit;
+    return typeof limit?.provider === 'string' && typeof limit.model === 'string' ? `${limit.provider}/${limit.model}` : undefined;
+}
+function parseRefusal(value) {
+    if (!value || typeof value !== 'object' || !('error' in value))
+        throw new Error('llm returned an invalid response');
+    const error = value.error;
+    if (!error || typeof error.message !== 'string')
+        throw new Error('llm returned an invalid refusal');
+    return error;
+}
+/** `Crtr-Caused-By: message:<id>` for the turn running now; nothing when the turn has no input message. */
+/** `/v1/llm` at `CRTR_API_URL` (the control plane, from a sandbox) or on the local API socket. */
+function llmUrl() {
+    const base = brokerApiUrl();
+    return base === undefined ? 'http://localhost/v1/llm' : new URL('/v1/llm', base).toString();
+}
+function llmFetch() {
+    return brokerApiUrl() === undefined ? socketFetch(apiSocketPath()) : globalThis.fetch;
+}
+/** The real response under a deferred-head framing (`daemon/api/deferred-head.ts`): the magic line, keep-alive
+ *  blank lines, one JSON head line, then the body unchanged. Any other response is returned as it is. */
+export async function unwrapDeferredHead(response) {
+    if (!response.headers.get('content-type')?.startsWith(DEFERRED_HEAD_CONTENT_TYPE))
+        return response;
+    if (!response.body)
+        throw new Error('deferred head response has no body');
+    const reader = response.body.getReader();
+    let buffered = new Uint8Array(0);
+    let magic = false;
+    for (;;) {
+        const newline = buffered.indexOf(10);
+        if (newline < 0) {
+            const { value, done } = await reader.read();
+            if (done)
+                throw new Error('deferred head response ended before its head');
+            const joined = new Uint8Array(buffered.length + value.length);
+            joined.set(buffered);
+            joined.set(value, buffered.length);
+            buffered = joined;
+            continue;
+        }
+        const line = new TextDecoder().decode(buffered.subarray(0, newline)).trim();
+        buffered = buffered.subarray(newline + 1);
+        if (!magic) {
+            if (`${line}\n` !== DEFERRED_HEAD_MAGIC)
+                throw new Error('deferred head response has no magic line');
+            magic = true;
+            continue;
+        }
+        if (line === '')
+            continue;
+        const head = JSON.parse(line);
+        const headers = new Headers();
+        for (const [name, value] of Object.entries(head.headers))
+            for (const one of Array.isArray(value) ? value : [value])
+                headers.append(name, one);
+        const rest = buffered;
+        const body = new ReadableStream({
+            start(controller) { if (rest.length > 0)
+                controller.enqueue(rest); },
+            async pull(controller) {
+                const { value, done } = await reader.read();
+                if (done)
+                    controller.close();
+                else
+                    controller.enqueue(value);
+            },
+            cancel(reason) { return reader.cancel(reason); },
+        });
+        return new Response(head.status === 204 ? null : body, { status: head.status, headers });
+    }
+}
+function causedByHeader() {
+    const causedBy = currentCausedBy();
+    return causedBy === undefined ? {} : { 'crtr-caused-by': causedBy };
+}
+/** One pi stream, backed exclusively by the authenticated daemon llm route. `intent` replaces the node's own `CRTR_MODEL_INTENT` for one stream: a background one-shot of an app-paid node asks for `app/light`, not the node's rung. */
+export function streamBrokerModel(model, context, options = {}, intent) {
+    const stream = createAssistantMessageEventStream();
+    const message = {
+        role: 'assistant', content: [], api: model.api, provider: model.provider, model: model.id,
+        usage: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, totalTokens: 0, cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, total: 0 } },
+        stopReason: 'pending', timestamp: Date.now(),
+    };
+    void (async () => {
+        const token = currentNodeToken();
+        if (!token)
+            throw new Error('llm requires a node token');
+        const body = JSON.stringify(requestBody(model, context, options, intent));
+        // Measured before sending: the daemon would only answer 413, and a context that
+        // large reproduces on every retry until pi compacts it.
+        const bytes = Buffer.byteLength(body);
+        if (bytes > MODEL_CONTEXT_BODY_MAX_BYTES)
+            throw contextTooLargeError(bytes, MODEL_CONTEXT_BODY_MAX_BYTES);
+        let waited = 0;
+        while (true) {
+            options.signal?.throwIfAborted();
+            // A deferred head keeps a slow first token from reading as a dead response at an edge
+            // that cuts a response with no bytes (Cloudflare Tunnel at about 125 s).
+            const fetched = await llmFetch()(llmUrl(), {
+                method: 'POST', headers: { authorization: `Bearer ${token}`, 'content-type': 'application/json', [DEFER_HEAD_REQUEST_HEADER]: '1', ...causedByHeader() }, body, signal: options.signal,
+            }).catch((error) => {
+                // At `CRTR_API_URL` a fetch that throws means Northlight is unreachable; the connection-fault retry (RT-LLM-65) owns the retry.
+                // Only the fetch's own rejection counts: a malformed answer from a server that responded is not unreachability.
+                const url = llmUrl();
+                if (brokerApiUrl() === undefined || options.signal?.aborted)
+                    throw error;
+                throw new UpstreamModelUnavailableError(northlightUnreachable(error, url).message);
+            });
+            const response = await unwrapDeferredHead(fetched);
+            if (!response.ok) {
+                const error = parseRefusal(await response.json());
+                if (response.status === 413 || error.code === 'payload_too_large')
+                    throw contextTooLargeError(bytes, MODEL_CONTEXT_BODY_MAX_BYTES);
+                applyServedModel(message, refusalRoute(error));
+                if (error.retryable !== true)
+                    throw new LlmRefusalError(error.message, undefined, refusalRateLimit(error), error.code, response.status);
+                const seconds = error.retry_after_s;
+                // A retryable answer without a wait hint is a transient upstream failure
+                // the daemon relayed (a 503 carrying the vendor's "Connection error.").
+                // Leave it undiagnosed so the broker's fault classifier owns the retry;
+                // stamping it as a refusal would record it as fatal and park the node.
+                if (typeof seconds !== 'number' || !Number.isFinite(seconds) || seconds <= 0) {
+                    // Named by code, not prose: `upstream_model_unavailable` is a connection fault with automatic retry (RT-LLM-65).
+                    throw error.code === UPSTREAM_MODEL_UNAVAILABLE ? new UpstreamModelUnavailableError(error.message) : new Error(error.message);
+                }
+                // A wait that outlasts what is left of the retry window cannot end in a
+                // retry here, so sleeping first only delays the same failure. Fail now
+                // and keep the deadline so the recorded fault says when it frees up.
+                const remaining = LLM_BROKER_RETRY_WINDOW_S - waited;
+                if (seconds > remaining) {
+                    const retryAt = Date.now() + seconds * 1000;
+                    throw new LlmRefusalError(`${error.message} (retry after ${seconds}s, at ${new Date(retryAt).toISOString()})`, retryAt, refusalRateLimit(error));
+                }
+                await sleep(seconds * 1000, undefined, { signal: options.signal });
+                waited += seconds;
+                continue;
+            }
+            if (!response.body)
+                throw new Error('llm returned no stream');
+            stream.push({ type: 'start', partial: message });
+            const reader = response.body.getReader();
+            const decoder = new TextDecoder();
+            let pending = '';
+            let finish = 'stop';
+            let refusal;
+            let receivedUsage = false;
+            let receivedServedModel = false;
+            const apply = (line) => {
+                const chunk = JSON.parse(line);
+                if (chunk.error) {
+                    // An error after headers still names the route that was serving: the
+                    // errored turn, and the fault recorded from it, belong to that route.
+                    const error = parseRefusal(chunk);
+                    applyServedModel(message, refusalRoute(error));
+                    if (error.retryable !== true)
+                        throw new LlmRefusalError(error.message, undefined, refusalRateLimit(error), error.code);
+                    throw error.code === UPSTREAM_MODEL_UNAVAILABLE ? new UpstreamModelUnavailableError(error.message) : new Error(error.message);
+                }
+                if (chunk.served_model) {
+                    receivedServedModel = true;
+                    if (chunk.served_model.indexOf('/') < 1)
+                        throw new Error('llm returned an invalid served_model');
+                    applyServedModel(message, chunk.served_model);
+                }
+                const choice = chunk.choices?.[0];
+                const delta = choice?.delta;
+                if (delta?.reasoning_content) {
+                    const index = message.content.findIndex((part) => part.type === 'thinking');
+                    const part = index < 0 ? { type: 'thinking', thinking: '' } : message.content[index];
+                    const position = index < 0 ? message.content.push(part) - 1 : index;
+                    if (index < 0)
+                        stream.push({ type: 'thinking_start', contentIndex: position, partial: message });
+                    if (part.type !== 'thinking')
+                        throw new Error('invalid thinking block');
+                    part.thinking += delta.reasoning_content;
+                    stream.push({ type: 'thinking_delta', contentIndex: position, delta: delta.reasoning_content, partial: message });
+                }
+                if (delta?.content) {
+                    const index = message.content.findIndex((part) => part.type === 'text');
+                    const part = index < 0 ? { type: 'text', text: '' } : message.content[index];
+                    const position = index < 0 ? message.content.push(part) - 1 : index;
+                    if (index < 0)
+                        stream.push({ type: 'text_start', contentIndex: position, partial: message });
+                    if (part.type !== 'text')
+                        throw new Error('invalid text block');
+                    part.text += delta.content;
+                    stream.push({ type: 'text_delta', contentIndex: position, delta: delta.content, partial: message });
+                }
+                for (const call of delta?.tool_calls ?? []) {
+                    const toolCall = { type: 'toolCall', id: call.id, name: call.function.name, arguments: JSON.parse(call.function.arguments) };
+                    const position = message.content.push(toolCall) - 1;
+                    stream.push({ type: 'toolcall_start', contentIndex: position, partial: message });
+                    stream.push({ type: 'toolcall_end', contentIndex: position, toolCall, partial: message });
+                }
+                if (choice?.finish_reason)
+                    finish = choice.finish_reason;
+                if (choice?.message?.refusal)
+                    refusal = choice.message.refusal;
+                if (chunk.usage) {
+                    receivedUsage = true;
+                    message.usage = { input: chunk.usage.prompt_tokens, output: chunk.usage.completion_tokens, cacheRead: chunk.usage.cache_read_tokens, cacheWrite: chunk.usage.cache_write_tokens, totalTokens: chunk.usage.total_tokens, cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, total: typeof chunk.usage.usd_equivalent === 'number' && Number.isFinite(chunk.usage.usd_equivalent) ? chunk.usage.usd_equivalent : 0 } };
+                }
+            };
+            while (true) {
+                const { value, done } = await reader.read();
+                if (done)
+                    break;
+                pending += decoder.decode(value, { stream: true });
+                let end;
+                while ((end = pending.indexOf('\n')) >= 0) {
+                    const line = pending.slice(0, end).trim();
+                    pending = pending.slice(end + 1);
+                    if (line)
+                        apply(line);
+                }
+            }
+            pending += decoder.decode();
+            if (pending.trim())
+                apply(pending.trim());
+            if (!receivedUsage || !receivedServedModel)
+                throw new Error('llm stream ended without usage or served_model');
+            for (const [index, part] of message.content.entries()) {
+                if (part.type === 'text')
+                    stream.push({ type: 'text_end', contentIndex: index, content: part.text, partial: message });
+                if (part.type === 'thinking')
+                    stream.push({ type: 'thinking_end', contentIndex: index, content: part.thinking, partial: message });
+            }
+            if (finish === 'content_filter')
+                throw new ContentFilteredError(refusal ?? 'Content filtered');
+            if (!['stop', 'tool_calls', 'length'].includes(finish))
+                throw new Error(`llm returned unknown finish reason: ${finish}`);
+            message.stopReason = finish === 'tool_calls' ? 'toolUse' : finish === 'length' ? 'length' : 'stop';
+            stream.push({ type: 'done', reason: message.stopReason, message });
+            stream.end();
+            return;
+        }
+    })().catch((error) => {
+        message.stopReason = options.signal?.aborted ? 'aborted' : 'error';
+        message.errorMessage = error instanceof Error ? error.message : String(error);
+        if (error instanceof LlmRefusalError) {
+            message.diagnostics = [
+                { type: LLM_REFUSAL_DIAGNOSTIC, timestamp: Date.now(), ...(error.retryAt !== undefined ? { details: { retryAt: error.retryAt } } : {}) },
+                // The fault records which rate-limit window bound (account-wide or one model family) and its headers.
+                ...(error.rateLimit !== undefined ? [providerFailureDiagnostic({ status: 429, ratelimit: error.rateLimit })] : []),
+                // A spend-cap refusal names its code, so the root of a run settles `cap_exhausted`.
+                ...(error.rateLimit === undefined && error.code === 'cap_exhausted' ? [providerFailureDiagnostic({ status: error.status ?? 402, code: error.code })] : []),
+            ];
+        }
+        if (error instanceof UpstreamModelUnavailableError)
+            message.diagnostics = [providerFailureDiagnostic({ status: 503, code: UPSTREAM_MODEL_UNAVAILABLE })];
+        if (error instanceof ContentFilteredError && message.stopReason === 'error')
+            message.rawStopReason = 'content_filter';
+        stream.push({ type: 'error', reason: message.stopReason, error: message });
+        stream.end();
+    });
+    return stream;
+}

package/dist/core/runtime/broker/read-ops.d.ts

@@ -0,0 +1,27 @@
+import { type CreateAgentSessionResult } from '@earendil-works/pi-coding-agent';
+import { type DeterministicCommandExpansion } from '../command-expansion.js';
+import { SessionListCache } from '../session-list-cache.js';
+import { type GetSettingsData, type GetTreeData, type ListMemoryRefsData, type ListModelsData, type ListScopedModelsData, type ListSessionsData, type RefMeta } from '../broker-protocol.js';
+export type BrokerSession = CreateAgentSessionResult['session'];
+export type CommandDisclosure = {
+    name: string;
+    description: string;
+    source: string;
+    template?: string;
+    expansion?: DeterministicCommandExpansion;
+    /** Whether this command can complete its outcome from a non-terminal chat
+     *  surface. Opt-in and fail-closed; builtins are never chat-capable. */
+    gatewayCapable: boolean;
+    argumentHint?: string;
+};
+export declare const modelKey: (model: {
+    provider: string;
+    id: string;
+}) => string;
+export declare function buildCommandList(session: BrokerSession): CommandDisclosure[];
+export declare function buildListMemoryRefsData(id: string, refs: RefMeta[], engineLeadingCommandNames: string[]): ListMemoryRefsData;
+export declare function buildListModelsData(id: string, session: BrokerSession): ListModelsData;
+export declare function buildScopedModelsData(id: string, session: BrokerSession): ListScopedModelsData;
+export declare function buildGetTreeData(id: string, session: BrokerSession, boundaryReviewId: string | undefined): GetTreeData;
+export declare function buildSettingsData(id: string, session: BrokerSession): GetSettingsData;
+export declare function buildSessionsData(id: string, scope: 'cwd' | 'all', session: BrokerSession, cache: SessionListCache): Promise<ListSessionsData>;

package/dist/core/runtime/broker/read-ops.js

@@ -0,0 +1,172 @@
+import { ModelRegistry } from '@earendil-works/pi-coding-agent';
+import { boundaryRootedTree } from '../session-visibility.js';
+import { isUnknownModel } from '../model-selection.js';
+import { BUILTIN_SLASH_COMMANDS } from '../pi-vendored.js';
+import { isDeterministicCommandExpansion } from '../command-expansion.js';
+import { registrationChatSurface, templateChatSurface } from '../command-surface.js';
+function registryOf(session) {
+    return new ModelRegistry(session.modelRuntime);
+}
+const toModelRef = (model) => model === undefined || isUnknownModel(model) ? null : { provider: model.provider, id: model.id };
+export const modelKey = (model) => `${model.provider}/${model.id}`;
+export function buildCommandList(session) {
+    const out = [];
+    // Builtins are pi's own terminal controls. They stay in the terminal
+    // disclosure and are never offered to a chat surface.
+    for (const builtin of BUILTIN_SLASH_COMMANDS)
+        out.push({ name: builtin.name, description: builtin.description, source: 'builtin', gatewayCapable: false });
+    try {
+        for (const command of session.extensionRunner.getRegisteredCommands()) {
+            const expansion = command.expansion;
+            out.push({
+                name: command.invocationName,
+                description: command.description ?? '',
+                source: 'command',
+                ...(isDeterministicCommandExpansion(expansion) ? { expansion } : {}),
+                ...registrationChatSurface(command),
+            });
+        }
+    }
+    catch {
+        /* engine without a live extensionRunner — builtins only */
+    }
+    try {
+        for (const template of session.promptTemplates)
+            out.push({ name: template.name, description: template.description, source: 'template', template: template.content, ...templateChatSurface(template) });
+    }
+    catch {
+        /* ignore */
+    }
+    return out;
+}
+export function buildListMemoryRefsData(id, refs, engineLeadingCommandNames) {
+    return { type: 'data', id, kind: 'list_memory_refs', refs, engineLeadingCommandNames };
+}
+export function buildListModelsData(id, session) {
+    const registry = registryOf(session);
+    let availableIds = [];
+    try {
+        availableIds = registry.getAvailable().map(modelKey);
+    }
+    catch {
+        /* getAvailable touches auth config; degrade to none known available */
+    }
+    return {
+        type: 'data',
+        id,
+        kind: 'list_models',
+        models: registry.getAll(),
+        current: toModelRef(session.model),
+        availableIds,
+        scopedModels: session.scopedModels.map((scoped) => ({ model: scoped.model, thinkingLevel: scoped.thinkingLevel })),
+        enabledModelIds: session.settingsManager.getEnabledModels() ?? null,
+    };
+}
+export function buildScopedModelsData(id, session) {
+    return {
+        type: 'data',
+        id,
+        kind: 'list_scoped_models',
+        allModels: registryOf(session).getAll(),
+        enabledModelIds: session.settingsManager.getEnabledModels() ?? null,
+    };
+}
+export function buildGetTreeData(id, session, boundaryReviewId) {
+    const manager = session.sessionManager;
+    const tree = boundaryReviewId !== undefined ? boundaryRootedTree(manager.getTree(), boundaryReviewId) : manager.getTree();
+    const visibleEntryIds = new Set();
+    const collectEntryIds = (nodes) => {
+        for (const node of nodes) {
+            visibleEntryIds.add(node.entry.id);
+            collectEntryIds(node.children);
+        }
+    };
+    collectEntryIds(tree);
+    const forkPoints = session.getUserMessagesForForking()
+        .filter((user) => visibleEntryIds.has(user.entryId))
+        .map((user) => ({ id: user.entryId, text: user.text, timestamp: manager.getEntry(user.entryId)?.timestamp }));
+    const currentLeafId = manager.getLeafId();
+    return {
+        type: 'data',
+        id,
+        kind: 'get_tree',
+        tree,
+        currentLeafId: currentLeafId !== null && visibleEntryIds.has(currentLeafId) ? currentLeafId : null,
+        forkPoints,
+    };
+}
+export function buildSettingsData(id, session) {
+    const manager = session.settingsManager;
+    let availableThemes = [];
+    try {
+        availableThemes = session.resourceLoader.getThemes().themes.map((theme) => theme.name ?? '').filter((name) => name !== '');
+    }
+    catch {
+        /* loader without themes — viewer falls back to its local theme registry */
+    }
+    const defaultProvider = manager.getDefaultProvider();
+    const defaultModelId = manager.getDefaultModel();
+    let availableDefaultModels = [];
+    try {
+        availableDefaultModels = session.modelRuntime.getAvailableSnapshot();
+    }
+    catch {
+        /* the snapshot touches auth config; degrade to none known available */
+    }
+    const settings = {
+        autoCompact: session.autoCompactionEnabled,
+        defaultModel: defaultProvider && defaultModelId ? `${defaultProvider}/${defaultModelId}` : 'not set',
+        availableDefaultModels,
+        showImages: manager.getShowImages(),
+        imageWidthCells: manager.getImageWidthCells(),
+        autoResizeImages: manager.getImageAutoResize(),
+        blockImages: manager.getBlockImages(),
+        enableSkillCommands: manager.getEnableSkillCommands(),
+        steeringMode: session.steeringMode,
+        followUpMode: session.followUpMode,
+        transport: manager.getTransport(),
+        httpIdleTimeoutMs: manager.getHttpIdleTimeoutMs(),
+        thinkingLevel: session.thinkingLevel,
+        availableThinkingLevels: session.getAvailableThinkingLevels(),
+        modelThinkingLevels: manager.getAllModelThinkingLevels(),
+        currentTheme: manager.getTheme() ?? '',
+        terminalTheme: 'dark',
+        availableThemes,
+        hideThinkingBlock: manager.getHideThinkingBlock(),
+        mermaidRenderingMode: manager.getMermaidRenderingMode(),
+        collapseChangelog: manager.getCollapseChangelog(),
+        enableInstallTelemetry: manager.getEnableInstallTelemetry(),
+        doubleEscapeAction: manager.getDoubleEscapeAction(),
+        treeFilterMode: manager.getTreeFilterMode(),
+        showHardwareCursor: manager.getShowHardwareCursor(),
+        editorPaddingX: manager.getEditorPaddingX(),
+        autocompleteMaxVisible: manager.getAutocompleteMaxVisible(),
+        quietStartup: manager.getQuietStartup(),
+        clearOnShrink: manager.getClearOnShrink(),
+        showTerminalProgress: manager.getShowTerminalProgress(),
+        tuiMode: manager.getTuiMode(),
+        fullscreenExitOutput: manager.getFullscreenExitOutput(),
+        fullscreenScrollbar: manager.getFullscreenScrollbar(),
+        fullscreenCopyOnSelect: manager.getFullscreenCopyOnSelect(),
+        fullscreenWheelScrollLines: manager.getFullscreenWheelScrollLines(),
+        warnings: manager.getWarnings(),
+        defaultProjectTrust: manager.getDefaultProjectTrust(),
+        showCacheMissNotices: manager.getShowCacheMissNotices(),
+        cacheWarmingMode: manager.getCacheWarmingMode(),
+        outputPad: manager.getOutputPad(),
+        autoRetry: session.autoRetryEnabled,
+        model: toModelRef(session.model),
+    };
+    return { type: 'data', id, kind: 'get_settings', settings };
+}
+export function buildSessionsData(id, scope, session, cache) {
+    const manager = session.sessionManager;
+    return (scope === 'all' ? cache.listAll() : cache.listDir(manager.getCwd())).then((sessions) => ({
+        type: 'data',
+        id,
+        kind: 'list_sessions',
+        scope,
+        sessions,
+        currentSessionFile: session.sessionFile,
+    }));
+}

package/dist/core/runtime/broker/turn-cause.d.ts

@@ -0,0 +1,7 @@
+import type { BrokerSession } from './read-ops.js';
+export declare function setTurnCauseSource(source: () => BrokerSession): void;
+type Branch = ReturnType<BrokerSession['sessionManager']['getBranch']>;
+export declare function turnCauseOf(branch: Branch): string | undefined;
+/** `message:<id>` of the turn running now, or undefined. */
+export declare function currentCausedBy(): string | undefined;
+export {};

package/dist/core/runtime/broker/turn-cause.js

@@ -0,0 +1,30 @@
+/** The reference a broker's model and CLI calls carry as `Crtr-Caused-By`: `message:<id>` for the first message id in the current
+ *  turn's `crtr-turn-input` entry (design-ledger, "Turn id"). Read from the session at call time, so there is one source of truth:
+ *  an entry becomes the turn's input once the user or custom message that starts the turn follows it, and a turn that started with no entry (a person's own
+ *  prompt) has none. The broker registers its live session once; before that, and in a process with no session, there is none. */
+let liveSession;
+export function setTurnCauseSource(source) { liveSession = source; }
+export function turnCauseOf(branch) {
+    let pending = [];
+    let cause;
+    for (const entry of branch) {
+        if (entry.type === 'custom' && entry.customType === 'crtr-turn-input') {
+            const ids = entry.data?.message_ids;
+            if (Array.isArray(ids))
+                pending.push(...ids.filter((id) => typeof id === 'string'));
+        }
+        else if ((entry.type === 'message' && entry.message.role === 'user') || entry.type === 'custom_message') {
+            if (pending.length > 0) {
+                cause = pending[0];
+                pending = [];
+            }
+            else
+                cause = undefined;
+        }
+    }
+    return cause === undefined ? undefined : `message:${cause}`;
+}
+/** `message:<id>` of the turn running now, or undefined. */
+export function currentCausedBy() {
+    return liveSession === undefined ? undefined : turnCauseOf(liveSession().sessionManager.getBranch());
+}