@north-light/crouter 0.3.172 → 0.3.174

package/dist/core/runtime/broker/rebind.js

@@ -0,0 +1,211 @@
+import { mkdirSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { jobDir } from '../../canvas/paths.js';
+import { emitEvent } from '../../events/emit.js';
+import { operationIdContext } from '../../events/operation-id.js';
+const MAX_ADMITTED_REPLACEMENTS = 2;
+const REPLACEMENT_DEADLINE_MS = 30_000;
+const REPLACEMENT_DEADLINE_EXCEEDED = Symbol('replacement-deadline-exceeded');
+/** Owns session subscription replacement, its serialization lane, and replacement admission policy. */
+export class RebindDriver {
+    deps;
+    sessionValue;
+    servicesValue;
+    unsubscribe;
+    installed;
+    nextSubscriptionGeneration = 0;
+    rebindTail = Promise.resolve();
+    latestRebindRequest = 0;
+    replacementTail = Promise.resolve();
+    admittedReplacements = 0;
+    agentRunActiveValue = false;
+    shutdownRequested = false;
+    constructor(deps) {
+        this.deps = deps;
+        this.sessionValue = deps.session;
+        this.servicesValue = deps.services;
+    }
+    session() { return this.sessionValue; }
+    services() { return this.servicesValue; }
+    installedGeneration() { return this.installed; }
+    isAgentRunActive() { return this.agentRunActiveValue; }
+    requestShutdown() {
+        if (!this.agentRunActiveValue) {
+            this.deps.disposeAndExit('shutdown-hook');
+            return;
+        }
+        this.shutdownRequested = true;
+    }
+    setRebindSession() {
+        this.deps.runtime?.setRebindSession((candidateSession) => this.enqueueRebind(candidateSession, this.deps.runtime.services));
+    }
+    enqueueRebind(candidateSession, candidateServices) {
+        const ticket = ++this.latestRebindRequest;
+        const task = this.rebindTail.then(async () => {
+            if (ticket !== this.latestRebindRequest)
+                return;
+            this.installed?.executingTools.clear();
+            this.removeInstalledSubscription();
+            this.deps.setActiveSession(candidateSession);
+            this.deps.projection().reset();
+            this.deps.faultRetry().reset();
+            this.agentRunActiveValue = false;
+            this.deps.onSessionRebind();
+            this.deps.toolGroups.resetForSession();
+            await candidateSession.bindExtensions({ uiContext: this.deps.uiContext(), mode: 'rpc', shutdownHandler: () => this.requestShutdown() });
+            if (ticket !== this.latestRebindRequest)
+                return;
+            this.removeInstalledSubscription();
+            this.sessionValue = candidateSession;
+            this.servicesValue = candidateServices;
+            if (this.deps.cfg.editorName !== undefined && this.deps.cfg.editorName !== '') {
+                try {
+                    candidateSession.setSessionName(this.deps.cfg.editorName);
+                }
+                catch {
+                    /* non-fatal: naming is cosmetic */
+                }
+            }
+            const generation = {
+                id: ++this.nextSubscriptionGeneration,
+                session: candidateSession,
+                fallback: { blocked: false },
+                stagedProviderAgentEnd: null,
+                stagedWatchdogAbort: false,
+                stagedOverflowFailure: null,
+                executingTools: new Set(),
+            };
+            this.unsubscribe = this.sessionValue.subscribe((event) => {
+                if (!this.deps.projection().isCurrent(generation))
+                    return;
+                const ambientId = operationIdContext.current();
+                if (ambientId !== undefined) {
+                    this.executeSubscriptionCallback(generation, event);
+                    return;
+                }
+                const fallback = generation.fallback;
+                if (event.type === 'turn_start' && fallback.storedId !== undefined) {
+                    fallback.storedId = undefined;
+                    fallback.blocked = true;
+                    operationIdContext.fresh(() => {
+                        emitEvent({ level: 'warn', event: 'broker.turn.fallback_overlap', fields: { generation: generation.id, engine_event: event.type } });
+                        this.executeSubscriptionCallback(generation, event);
+                    });
+                    return;
+                }
+                if (event.type === 'turn_start' && !fallback.blocked) {
+                    operationIdContext.fresh((operationId) => {
+                        fallback.storedId = operationId;
+                        this.executeSubscriptionCallback(generation, event);
+                    });
+                    return;
+                }
+                const storedId = fallback.storedId;
+                if (storedId !== undefined && !fallback.blocked) {
+                    operationIdContext.run(storedId, () => {
+                        this.executeSubscriptionCallback(generation, event);
+                        if (event.type === 'agent_settled' && fallback.storedId === storedId)
+                            fallback.storedId = undefined;
+                    });
+                    return;
+                }
+                this.executeSubscriptionCallback(generation, event);
+            });
+            this.installed = generation;
+            this.captureSystemPrompt(candidateSession);
+        });
+        this.rebindTail = task.catch(() => undefined);
+        return task;
+    }
+    runReplacement(client, op, run) {
+        const runtime = this.deps.runtime;
+        if (runtime === undefined) {
+            this.deps.registry.sendFrame(client, { type: 'error', code: 'engine_error', message: 'session replacement unsupported at this engine pin' });
+            return;
+        }
+        if (this.admittedReplacements >= MAX_ADMITTED_REPLACEMENTS) {
+            operationIdContext.fresh(() => emitEvent({ level: 'warn', event: 'broker.session_replacement.rejected', outcome: 'skipped', fields: { op, reason: 'capacity', admitted: MAX_ADMITTED_REPLACEMENTS, cap: MAX_ADMITTED_REPLACEMENTS } }));
+            this.ackTo(client, op, false, `session replacement busy (${MAX_ADMITTED_REPLACEMENTS} active or queued)`);
+            return;
+        }
+        this.admittedReplacements++;
+        const task = this.replacementTail.then(async () => {
+            try {
+                await operationIdContext.fresh(async () => {
+                    const startedAt = process.hrtime.bigint();
+                    let timer;
+                    try {
+                        const deadline = new Promise((resolve) => { timer = setTimeout(() => resolve(REPLACEMENT_DEADLINE_EXCEEDED), REPLACEMENT_DEADLINE_MS); });
+                        const outcome = await Promise.race([run(runtime), deadline]);
+                        if (outcome === REPLACEMENT_DEADLINE_EXCEEDED) {
+                            emitEvent({ level: 'error', event: 'broker.session_replacement.timed_out', outcome: 'failed', duration_ms: Number(process.hrtime.bigint() - startedAt) / 1_000_000, fields: { op, deadline_ms: REPLACEMENT_DEADLINE_MS, mutation_outcome: 'indeterminate' } });
+                            this.ackTo(client, op, false, 'session replacement timed out; broker restarting because session state is indeterminate');
+                            this.deps.disposeAndExit('session-replacement-timeout', 1);
+                            return;
+                        }
+                        if (!outcome.cancelled)
+                            this.deps.reWelcomeAll();
+                        this.ackTo(client, op, !outcome.cancelled, outcome.cancelled ? outcome.detail ?? 'cancelled by extension' : undefined);
+                    }
+                    catch (err) {
+                        emitEvent({ level: 'error', event: 'broker.session_replacement.failed', outcome: 'failed', error: err, fields: { op, mutation_outcome: 'indeterminate' } });
+                        this.ackTo(client, op, false, 'session replacement failed; broker restarting because session state is indeterminate');
+                        this.deps.disposeAndExit('session-replacement-failed', 1);
+                    }
+                    finally {
+                        clearTimeout(timer);
+                    }
+                });
+            }
+            finally {
+                this.admittedReplacements--;
+            }
+        });
+        this.replacementTail = task.catch(() => undefined);
+    }
+    removeInstalledSubscription() {
+        this.unsubscribe?.();
+        this.unsubscribe = undefined;
+        this.installed = undefined;
+    }
+    captureSystemPrompt(candidateSession) {
+        try {
+            const dir = jobDir(this.deps.nodeId);
+            mkdirSync(dir, { recursive: true });
+            writeFileSync(join(dir, 'system-prompt.md'), candidateSession.systemPrompt, 'utf8');
+        }
+        catch {
+            /* non-fatal: diagnostic only */
+        }
+    }
+    executeSubscriptionCallback(generation, event) {
+        try {
+            if (event.type === 'agent_start')
+                this.agentRunActiveValue = true;
+            if (event.type === 'agent_end') {
+                generation.stagedProviderAgentEnd = event;
+                generation.stagedOverflowFailure = null;
+            }
+            if (event.type === 'compaction_end' && event.reason === 'overflow' && event.willRetry === false && typeof event.errorMessage === 'string')
+                generation.stagedOverflowFailure = { errorMessage: event.errorMessage };
+            if (event.type === 'agent_settled') {
+                this.agentRunActiveValue = false;
+                this.deps.faultRetry().publishSettledProviderFault(generation);
+                if (this.shutdownRequested) {
+                    this.deps.disposeAndExit('shutdown-after-settle');
+                    return;
+                }
+            }
+            this.deps.toolGroups.observeToolGroupEvent(event);
+            this.deps.projection().relayEvent(event, generation);
+            if (event.type === 'agent_settled')
+                this.deps.faultRetry().schedule();
+        }
+        catch (err) {
+            emitEvent({ level: 'debug', event: 'broker.runtime.diagnostic', fields: { message: `event relay threw: ${String(err)}` } });
+        }
+    }
+    ackTo(client, op, ok = true, detail, id) {
+        this.deps.registry.sendFrame(client, { type: 'ack', for: op, ok, ...(detail !== undefined ? { detail } : {}), ...(id !== undefined ? { id } : {}) });
+    }
+}

package/dist/core/runtime/broker/tool-groups.d.ts

@@ -0,0 +1,39 @@
+import { type ToolGroupSummary } from '../../../shared/tool-groups.js';
+import type { BrokerToClient } from '../broker-protocol.js';
+/** Owns transcript tool-group state and its durable summary sidecars. */
+export declare class ToolGroupTracker {
+    private readonly broadcast;
+    private readonly toolSummariesPath;
+    private readonly pendingToolSummaryPath;
+    private readonly toolGroupSummaries;
+    private readonly summaryAttempted;
+    private readonly generatingToolGroups;
+    private readonly toolGroupsByCallId;
+    private readonly summaryTasks;
+    private openToolGroup;
+    private lastToolGroupBoundaryProse;
+    private sawAssistantProse;
+    constructor(nodeId: string, broadcast: (frame: BrokerToClient) => void);
+    summaries(): Record<string, ToolGroupSummary>;
+    resetForSession(): void;
+    finishOpenToolGroup(settleInterruptedTools?: boolean): void;
+    observeToolGroupEvent(event: {
+        type?: string;
+        message?: unknown;
+        toolCallId?: unknown;
+        toolName?: unknown;
+        args?: unknown;
+        result?: unknown;
+        isError?: unknown;
+        success?: unknown;
+    }): void;
+    persistPendingSummary(): void;
+    hasSummaryTasks(): boolean;
+    waitForSummaryTasks(): Promise<PromiseSettledResult<void>[]>;
+    private ensureOpenToolGroup;
+    private visibleBoundary;
+    private clearPendingToolGroupSummary;
+    private generateToolGroupSummary;
+    private generateSettledToolGroup;
+    private resumePendingSummary;
+}

package/dist/core/runtime/broker/tool-groups.js

@@ -0,0 +1,244 @@
+import { existsSync, unlinkSync } from 'node:fs';
+import { join } from 'node:path';
+import { jobDir } from '../../canvas/paths.js';
+import { readConfig } from '../../config.js';
+import { emitEvent } from '../../events/emit.js';
+import { atomicWriteJson, readJsonIfExists } from '../../fs-utils.js';
+import { assistantVisibleText, isTrueUserMessage, normalizeToolGroupSummaryRecord, } from '../../../shared/tool-groups.js';
+import { generatedContextText } from '../../../shared/generated-context.js';
+import { headlessToolGroupSummary, serializeToolGroup } from '../tool-group-summary.js';
+const PENDING_TOOL_SUMMARY_KEY_MAX_CHARS = 1_000;
+const PENDING_TOOL_SUMMARY_SEGMENT_MAX_CHARS = 10_000;
+function normalizePendingToolGroupSummary(value) {
+    if (value === null || typeof value !== 'object' || Array.isArray(value))
+        return null;
+    const record = value;
+    if (Object.keys(record).sort().join(',') !== 'key,segment,version')
+        return null;
+    if (record.version !== 1 || typeof record.key !== 'string' || typeof record.segment !== 'string')
+        return null;
+    if (record.key.length === 0 || record.key.length > PENDING_TOOL_SUMMARY_KEY_MAX_CHARS || record.segment.length === 0 || record.segment.length > PENDING_TOOL_SUMMARY_SEGMENT_MAX_CHARS)
+        return null;
+    return { version: 1, key: record.key, segment: record.segment };
+}
+/** Owns transcript tool-group state and its durable summary sidecars. */
+export class ToolGroupTracker {
+    broadcast;
+    toolSummariesPath;
+    pendingToolSummaryPath;
+    toolGroupSummaries = new Map();
+    summaryAttempted;
+    generatingToolGroups = new Map();
+    toolGroupsByCallId = new Map();
+    summaryTasks = new Set();
+    openToolGroup;
+    lastToolGroupBoundaryProse = '';
+    sawAssistantProse = false;
+    constructor(nodeId, broadcast) {
+        this.broadcast = broadcast;
+        this.toolSummariesPath = join(jobDir(nodeId), 'tool-summaries.json');
+        this.pendingToolSummaryPath = join(jobDir(nodeId), 'pending-tool-summary.json');
+        try {
+            const persisted = readJsonIfExists(this.toolSummariesPath);
+            for (const [key, summary] of Object.entries(normalizeToolGroupSummaryRecord(persisted)))
+                this.toolGroupSummaries.set(key, summary);
+        }
+        catch {
+            /* malformed sidecar merely withholds summaries */
+        }
+        this.summaryAttempted = new Set(this.toolGroupSummaries.keys());
+        this.resumePendingSummary();
+    }
+    summaries() {
+        return Object.fromEntries(this.toolGroupSummaries);
+    }
+    resetForSession() {
+        this.openToolGroup = undefined;
+        this.toolGroupsByCallId.clear();
+        this.sawAssistantProse = false;
+    }
+    finishOpenToolGroup(settleInterruptedTools = false) {
+        const group = this.openToolGroup;
+        this.openToolGroup = undefined;
+        if (group === undefined)
+            return;
+        group.closed = true;
+        if (settleInterruptedTools) {
+            for (const id of group.pendingToolIds)
+                this.toolGroupsByCallId.delete(id);
+            group.pendingToolIds.clear();
+        }
+        group.summarizeWhenSettled = readConfig('user').summarize_tool_calls;
+        this.generateSettledToolGroup(group);
+    }
+    observeToolGroupEvent(event) {
+        if (event.type === 'compaction_end' || (event.type === 'auto_retry_end' && event.success !== true)) {
+            this.finishOpenToolGroup();
+            return;
+        }
+        if (event.type === 'message_end') {
+            const message = event.message;
+            if (message !== null && typeof message === 'object') {
+                const item = message;
+                if (item.role === 'assistant' && (item.stopReason === 'aborted' || item.stopReason === 'error'))
+                    this.finishOpenToolGroup(true);
+            }
+            return;
+        }
+        if (event.type === 'tool_execution_start') {
+            const group = this.ensureOpenToolGroup();
+            const id = typeof event.toolCallId === 'string' ? event.toolCallId : '';
+            if (group.key === undefined && id !== '')
+                group.key = id;
+            if (id !== '') {
+                group.pendingToolIds.add(id);
+                this.toolGroupsByCallId.set(id, group);
+            }
+            group.toolCount += 1;
+            group.pieces.push({ type: 'tool', name: typeof event.toolName === 'string' ? event.toolName : 'tool', args: event.args });
+            return;
+        }
+        if (event.type === 'tool_execution_end') {
+            const id = typeof event.toolCallId === 'string' ? event.toolCallId : '';
+            const group = id === '' ? this.openToolGroup : this.toolGroupsByCallId.get(id);
+            if (group !== undefined) {
+                group.pieces.push({ type: 'result', name: typeof event.toolName === 'string' ? event.toolName : 'tool', result: event.result, isError: event.isError === true });
+                if (id !== '') {
+                    group.pendingToolIds.delete(id);
+                    this.toolGroupsByCallId.delete(id);
+                }
+                this.generateSettledToolGroup(group);
+            }
+            return;
+        }
+        if (event.type !== 'message_start' && event.type !== 'message_update')
+            return;
+        const message = event.message;
+        if (message === null || typeof message !== 'object')
+            return;
+        const item = message;
+        if (item.role === 'assistant') {
+            if (event.type === 'message_start')
+                this.sawAssistantProse = false;
+            const prose = assistantVisibleText(item);
+            if (!this.sawAssistantProse && prose.trim() !== '') {
+                this.sawAssistantProse = true;
+                this.visibleBoundary(prose);
+            }
+            return;
+        }
+        if (event.type !== 'message_start')
+            return;
+        if (item.role === 'compactionSummary' || item.role === 'branchSummary' || item.role === 'bashExecution' || item.role === 'status' || item.role === 'error' || item.customType === 'crtr-cycle-divider') {
+            this.finishOpenToolGroup();
+            return;
+        }
+        if (isTrueUserMessage(item)) {
+            this.visibleBoundary(generatedContextText(item));
+            return;
+        }
+        if (item.display === false)
+            return;
+        const text = generatedContextText(item);
+        const isBearingsOrRevive = item.customType === 'crtr-context' || (item.role === 'user' && text.startsWith('You have been revived fresh after a context refresh'));
+        if (isBearingsOrRevive) {
+            if (this.openToolGroup !== undefined && text !== '')
+                this.openToolGroup.pieces.push({ type: 'text', text });
+            return;
+        }
+        const group = this.ensureOpenToolGroup();
+        if (text !== '')
+            group.pieces.push({ type: 'text', text });
+    }
+    persistPendingSummary() {
+        const pending = [...this.generatingToolGroups.values()].at(-1);
+        if (pending === undefined)
+            return;
+        try {
+            atomicWriteJson(this.pendingToolSummaryPath, pending);
+        }
+        catch (error) {
+            emitEvent({ level: 'warn', event: 'broker.runtime.diagnostic', fields: { message: `failed to persist pending tool summary: ${error instanceof Error ? error.message : String(error)}` } });
+        }
+    }
+    hasSummaryTasks() {
+        return this.summaryTasks.size > 0;
+    }
+    waitForSummaryTasks() {
+        return Promise.allSettled([...this.summaryTasks]);
+    }
+    ensureOpenToolGroup() {
+        if (this.openToolGroup === undefined) {
+            this.openToolGroup = { toolCount: 0, pieces: [], boundaryProse: this.lastToolGroupBoundaryProse, pendingToolIds: new Set(), closed: false, summarizeWhenSettled: false };
+        }
+        return this.openToolGroup;
+    }
+    visibleBoundary(prose) {
+        this.finishOpenToolGroup();
+        this.lastToolGroupBoundaryProse = prose;
+    }
+    clearPendingToolGroupSummary(input) {
+        try {
+            const persisted = normalizePendingToolGroupSummary(readJsonIfExists(this.pendingToolSummaryPath));
+            if (persisted?.key === input.key && persisted.segment === input.segment)
+                unlinkSync(this.pendingToolSummaryPath);
+        }
+        catch {
+            /* a stale handoff must not revoke the recap */
+        }
+    }
+    generateToolGroupSummary(input) {
+        const { key, segment } = input;
+        if (this.summaryAttempted.has(key) || this.generatingToolGroups.has(key))
+            return;
+        this.summaryAttempted.add(key);
+        this.generatingToolGroups.set(key, input);
+        let task;
+        task = headlessToolGroupSummary(segment)
+            .then((summary) => {
+            if (summary === null)
+                return;
+            this.toolGroupSummaries.set(key, summary);
+            try {
+                atomicWriteJson(this.toolSummariesPath, Object.fromEntries(this.toolGroupSummaries));
+            }
+            catch {
+                this.toolGroupSummaries.delete(key);
+                return;
+            }
+            this.clearPendingToolGroupSummary(input);
+            this.broadcast({ type: 'tool_group_summary', key, summary });
+        })
+            .catch(() => undefined)
+            .finally(() => {
+            this.generatingToolGroups.delete(key);
+            this.summaryTasks.delete(task);
+        });
+        this.summaryTasks.add(task);
+    }
+    generateSettledToolGroup(group) {
+        if (!group.closed || group.pendingToolIds.size > 0 || group.key === undefined || !group.summarizeWhenSettled)
+            return;
+        this.generateToolGroupSummary({ version: 1, key: group.key, segment: serializeToolGroup(group.boundaryProse, group.pieces) });
+    }
+    resumePendingSummary() {
+        try {
+            const pending = normalizePendingToolGroupSummary(readJsonIfExists(this.pendingToolSummaryPath));
+            if (pending === null) {
+                if (existsSync(this.pendingToolSummaryPath)) {
+                    unlinkSync(this.pendingToolSummaryPath);
+                    emitEvent({ level: 'warn', event: 'broker.startup.warning', fields: { stage: 'pending_tool_summary', message: 'removed an invalid pending tool summary' } });
+                }
+            }
+            else if (this.toolGroupSummaries.has(pending.key)) {
+                unlinkSync(this.pendingToolSummaryPath);
+            }
+            else {
+                this.generateToolGroupSummary(pending);
+            }
+        }
+        catch (error) {
+            emitEvent({ level: 'warn', event: 'broker.startup.warning', fields: { stage: 'pending_tool_summary', message: error instanceof Error ? error.message : String(error) } });
+        }
+    }
+}

package/dist/core/runtime/broker-extension-render.d.ts

@@ -0,0 +1,11 @@
+import type { BrokerExtensionNodeDTO, BrokerExtensionStateDTO } from '../../api/dto/broker-ops.js';
+export declare function editorLabelForBrokerNode(node: BrokerExtensionNodeDTO): string;
+/** Same environment-only project context rendered at normal boot, without a
+ * canvas import. */
+export declare function buildProjectContextBlockForBroker(cwd: string): string;
+export declare function buildContextBearingsFromState(state: BrokerExtensionStateDTO, projectContext: string, situational?: string): string;
+export declare function buildForkBearingsFromState(state: BrokerExtensionStateDTO, situational?: string): string;
+export declare function renderPreferencesFromState(state: BrokerExtensionStateDTO): string;
+/** A canonical report ref has already been validated by crtrd in state. The
+ * broker reads only its local filesystem content; no canvas accessor is needed. */
+export declare function reportPathFromRef(ref: string, reportNodes: ReadonlyMap<string, unknown>): string | null;