@north-light/crouter 0.3.311 → 0.3.313

package/dist/daemon/api/handlers/broker-recovery.d.ts

@@ -0,0 +1,4 @@
+import type { RouteTable } from '../router.js';
+export declare function requireCurrentExecution(nodeId: string, expectedExecutionId: unknown): void;
+export declare const brokerRecoveryRoutes: RouteTable;
+export declare const nodeFaultRoutes: RouteTable;

package/dist/daemon/api/handlers/broker-recovery.js

@@ -0,0 +1,251 @@
+import { ApiError } from '../../../api/errors.js';
+import { getNode } from '../../../core/canvas/canvas.js';
+import { liveExecutionForNode } from '../../../core/canvas/executions.js';
+import { admitEpisode, clearEpisode, clearFault, closeTurn, invalidateEpisode, openTurn, parseProviderError, readEpisode, readFault, recordFault, recordPendingEpisode, recordTransportPoisonVerdict, recordTurnProgress, reopenEpisode, } from '../../../core/canvas/recovery.js';
+import { notFound, usage } from '../../../core/errors.js';
+const FAULT_LINKS = new Set(['pi→provider', 'viewer↔broker', 'relay↔broker', 'viewer↔crtrd', 'daemon→node', 'crtr→pi']);
+const FAULT_KINDS = new Set(['rate-limit', 'overloaded', 'connection', 'auth', 'protocol', 'context-overflow', 'other', 'wedged', 'model-not-found']);
+const RETRY_DISPOSITIONS = new Set(['auto', 'manual', 'fatal']);
+const RETRY_OWNERS = new Set(['sdk', 'daemon', 'client']);
+function objectBody(body, operation) {
+    if (typeof body !== 'object' || body === null || Array.isArray(body))
+        throw usage(`${operation} requires a JSON object`);
+    return body;
+}
+function requireNode(nodeId) {
+    if (getNode(nodeId) === null)
+        throw notFound(`unknown node: ${nodeId}`, { received: nodeId });
+}
+export function requireCurrentExecution(nodeId, expectedExecutionId) {
+    if (typeof expectedExecutionId !== 'string' || expectedExecutionId === '')
+        throw usage('expected_execution_id must be a non-empty string');
+    const execution = liveExecutionForNode(nodeId);
+    if (execution === null || execution.executionId !== expectedExecutionId) {
+        throw new ApiError(409, 'stale_execution', 'broker execution is no longer current');
+    }
+}
+function parseRetry(value) {
+    if (typeof value !== 'object' || value === null || Array.isArray(value))
+        throw usage('retry must be an object');
+    const retry = value;
+    if (!RETRY_DISPOSITIONS.has(retry['disposition']))
+        throw usage('retry.disposition must be auto, manual, or fatal');
+    if (retry['by'] !== undefined && !RETRY_OWNERS.has(retry['by']))
+        throw usage('retry.by must be sdk, daemon, or client');
+    for (const key of ['attempt', 'max'])
+        if (retry[key] !== undefined && (!Number.isSafeInteger(retry[key]) || retry[key] < 0))
+            throw usage(`retry.${key} must be a non-negative safe integer`);
+    if (retry['nextAt'] !== undefined && typeof retry['nextAt'] !== 'string')
+        throw usage('retry.nextAt must be a string');
+    return retry;
+}
+function parseFaultInput(value) {
+    const input = objectBody(value, 'fault input');
+    if (!FAULT_LINKS.has(input['link']))
+        throw usage('fault link is invalid');
+    if (typeof input['op'] !== 'string' || input['op'] === '')
+        throw usage('fault op must be a non-empty string');
+    if (!FAULT_KINDS.has(input['kind']))
+        throw usage('fault kind is invalid');
+    if (typeof input['message'] !== 'string')
+        throw usage('fault message must be a string');
+    if (input['operation_id'] !== undefined && (typeof input['operation_id'] !== 'string' || input['operation_id'] === ''))
+        throw usage('operation_id must be a non-empty string');
+    if (input['since'] !== undefined && typeof input['since'] !== 'string')
+        throw usage('since must be a string');
+    if (input['anchor_entry_id'] !== undefined && (typeof input['anchor_entry_id'] !== 'string' || input['anchor_entry_id'] === ''))
+        throw usage('anchor_entry_id must be a non-empty string');
+    const providerError = input['provider_error'] === undefined ? undefined : parseProviderError(input['provider_error']);
+    if (input['provider_error'] !== undefined && providerError === undefined)
+        throw usage('provider_error is invalid');
+    return { ...input, ...(providerError === undefined ? {} : { provider_error: providerError }), retry: parseRetry(input['retry']) };
+}
+function faultInput(input) {
+    return {
+        link: input.link,
+        op: input.op,
+        kind: input.kind,
+        retry: input.retry,
+        message: input.message,
+        ...(input.operation_id === undefined ? {} : { operation_id: input.operation_id }),
+        ...(input.since === undefined ? {} : { since: input.since }),
+        ...(input.anchor_entry_id === undefined ? {} : { anchorEntryId: input.anchor_entry_id }),
+        ...(input.provider_error === undefined ? {} : { providerError: input.provider_error }),
+    };
+}
+function faultDto(fault) {
+    return {
+        fault_id: fault.faultId,
+        link: fault.link,
+        op: fault.op,
+        kind: fault.kind,
+        retry: fault.retry,
+        message: fault.message,
+        since: fault.since,
+        operation_id: fault.operation_id,
+        ...(fault.anchorEntryId === undefined ? {} : { anchor_entry_id: fault.anchorEntryId }),
+        ...(fault.providerError === undefined ? {} : { provider_error: fault.providerError }),
+    };
+}
+function recoveryState(nodeId) {
+    const fault = readFault(nodeId);
+    const episode = readEpisode(nodeId);
+    return {
+        fault: fault === null ? null : faultDto(fault),
+        episode: episode === null ? null : { state: episode.state, session_id: episode.sessionId, fault: faultDto(episode.fault) },
+    };
+}
+function parseTurn(body) {
+    const request = objectBody(body, 'broker turn');
+    const event = request['event'];
+    if (event !== 'started' && event !== 'progress' && event !== 'closed' && event !== 'interrupted' && event !== 'exit-diagnostic')
+        throw usage('event is invalid');
+    if (typeof request['expected_execution_id'] !== 'string' || request['expected_execution_id'] === '')
+        throw usage('expected_execution_id must be a non-empty string');
+    if (event === 'closed') {
+        if (request['end_reason'] !== 'settled' && request['end_reason'] !== 'teardown-aborted')
+            throw usage('closed turn requires end_reason settled or teardown-aborted');
+    }
+    else if (request['end_reason'] !== undefined)
+        throw usage('end_reason is valid only for closed turns');
+    if (event === 'exit-diagnostic') {
+        const diagnostic = objectBody(request['exit_diagnostic'], 'exit_diagnostic');
+        const poison = objectBody(diagnostic['transport_poison'], 'exit_diagnostic.transport_poison');
+        if (diagnostic['schema'] !== 'crtr.execution-exit-diagnostic/v1' || !Number.isSafeInteger(poison['consecutive_passes']) || poison['consecutive_passes'] < 1 || !Array.isArray(poison['routes']) || poison['routes'].length === 0 || !poison['routes'].every((route) => typeof route === 'string' && route !== ''))
+            throw usage('exit_diagnostic is invalid');
+    }
+    else if (request['exit_diagnostic'] !== undefined)
+        throw usage('exit_diagnostic is valid only for exit-diagnostic turns');
+    return request;
+}
+function handleTurn(ctx) {
+    const nodeId = ctx.params['id'];
+    requireNode(nodeId);
+    const request = parseTurn(ctx.body);
+    requireCurrentExecution(nodeId, request.expected_execution_id);
+    let applied;
+    switch (request.event) {
+        case 'started':
+            applied = openTurn(request.expected_execution_id, { reason: 'agent-start' });
+            break;
+        case 'interrupted':
+            applied = openTurn(request.expected_execution_id, { reason: 'prompt-unsettled' });
+            break;
+        case 'progress':
+            applied = recordTurnProgress(request.expected_execution_id);
+            break;
+        case 'closed':
+            applied = closeTurn(request.expected_execution_id, { endReason: request.end_reason });
+            break;
+        case 'exit-diagnostic': {
+            const poison = request.exit_diagnostic.transport_poison;
+            applied = recordTransportPoisonVerdict(request.expected_execution_id, { consecutivePasses: poison.consecutive_passes, routes: poison.routes });
+            break;
+        }
+    }
+    const body = { applied };
+    return { status: 200, body };
+}
+function parseProviderRetry(body) {
+    const request = objectBody(body, 'provider retry');
+    if (typeof request['expected_execution_id'] !== 'string' || request['expected_execution_id'] === '')
+        throw usage('expected_execution_id must be a non-empty string');
+    if (!['record-pending', 'admit', 'reopen', 'invalidate', 'clear'].includes(request['op']))
+        throw usage('provider retry op is invalid');
+    if (typeof request['session_id'] !== 'string' || request['session_id'] === '')
+        throw usage('session_id must be a non-empty string');
+    if (request['op'] === 'record-pending')
+        request['input'] = parseFaultInput(request['input']);
+    if (request['op'] === 'admit') {
+        if (typeof request['fault_id'] !== 'string' || request['fault_id'] === '')
+            throw usage('admit requires fault_id');
+        request['retry'] = parseRetry(request['retry']);
+    }
+    return request;
+}
+function handleProviderRetry(ctx) {
+    const nodeId = ctx.params['id'];
+    requireNode(nodeId);
+    const request = parseProviderRetry(ctx.body);
+    requireCurrentExecution(nodeId, request.expected_execution_id);
+    let applied;
+    switch (request.op) {
+        case 'record-pending':
+            applied = recordPendingEpisode(nodeId, { sessionId: request.session_id, input: faultInput(request.input) }) !== null;
+            break;
+        case 'admit':
+            applied = admitEpisode(nodeId, { sessionId: request.session_id, faultId: request.fault_id, retry: request.retry });
+            break;
+        case 'reopen':
+            applied = reopenEpisode(nodeId, { sessionId: request.session_id });
+            break;
+        case 'invalidate':
+            applied = invalidateEpisode(nodeId, { sessionId: request.session_id });
+            break;
+        case 'clear':
+            applied = clearEpisode(nodeId, { sessionId: request.session_id });
+            break;
+    }
+    const body = { applied, episode: recoveryState(nodeId).episode };
+    return { status: 200, body };
+}
+function parseBrokerFault(body) {
+    const request = objectBody(body, 'broker fault');
+    if (typeof request['expected_execution_id'] !== 'string' || request['expected_execution_id'] === '')
+        throw usage('expected_execution_id must be a non-empty string');
+    if (request['op'] !== 'record' && request['op'] !== 'clear')
+        throw usage('fault op must be record or clear');
+    if (request['op'] === 'record')
+        request['input'] = parseFaultInput(request['input']);
+    if (request['op'] === 'clear' && request['link'] !== undefined && !FAULT_LINKS.has(request['link']))
+        throw usage('fault link is invalid');
+    if (request['preserve_episode'] !== undefined && typeof request['preserve_episode'] !== 'boolean')
+        throw usage('preserve_episode must be boolean');
+    return request;
+}
+function handleBrokerFault(ctx) {
+    const nodeId = ctx.params['id'];
+    requireNode(nodeId);
+    const request = parseBrokerFault(ctx.body);
+    requireCurrentExecution(nodeId, request.expected_execution_id);
+    const fault = request.op === 'record'
+        ? recordFault(nodeId, faultInput(request.input))
+        : (clearFault(nodeId, { ...(request.link === undefined ? {} : { link: request.link }), ...(request.preserve_episode === undefined ? {} : { preserveEpisode: request.preserve_episode }) }), readFault(nodeId));
+    const body = { fault: fault === null ? null : faultDto(fault) };
+    return { status: 200, body };
+}
+function handleRecovery(ctx) {
+    const nodeId = ctx.params['id'];
+    requireNode(nodeId);
+    requireCurrentExecution(nodeId, ctx.query.get('expected_execution_id'));
+    return { status: 200, body: recoveryState(nodeId) };
+}
+function handleNodeFaultRecord(ctx) {
+    const nodeId = ctx.params['id'];
+    requireNode(nodeId);
+    const fault = recordFault(nodeId, faultInput(parseFaultInput(ctx.body)));
+    const body = { fault: fault === null ? null : faultDto(fault) };
+    return { status: 200, body };
+}
+function handleNodeFaultClear(ctx) {
+    const nodeId = ctx.params['id'];
+    requireNode(nodeId);
+    const link = ctx.query.get('link');
+    if (link !== null && !FAULT_LINKS.has(link))
+        throw usage('fault link is invalid');
+    const preserve = ctx.query.get('preserve_episode');
+    if (preserve !== null && preserve !== 'true' && preserve !== 'false')
+        throw usage('preserve_episode must be true or false');
+    const body = { cleared: clearFault(nodeId, { ...(link === null ? {} : { link: link }), ...(preserve === null ? {} : { preserveEpisode: preserve === 'true' }) }) };
+    return { status: 200, body };
+}
+export const brokerRecoveryRoutes = [
+    { method: 'POST', pattern: '/v1/broker/:id/turn', handler: handleTurn },
+    { method: 'POST', pattern: '/v1/broker/:id/provider-retry', handler: handleProviderRetry },
+    { method: 'POST', pattern: '/v1/broker/:id/fault', handler: handleBrokerFault },
+    { method: 'GET', pattern: '/v1/broker/:id/recovery', handler: handleRecovery },
+];
+export const nodeFaultRoutes = [
+    { method: 'POST', pattern: '/v1/nodes/:id/fault', handler: handleNodeFaultRecord },
+    { method: 'DELETE', pattern: '/v1/nodes/:id/fault', handler: handleNodeFaultClear },
+];

package/dist/daemon/api/handlers/canvas.js

@@ -1,17 +1,4 @@
-// Canvas-wide read + maintenance handlers (spec §6.3). Attention/history/snapshot
-// are cross-canvas reads; prune/rebuild-index are the maintenance verbs backing
-// `crtr canvas prune` / `crtr canvas rebuild-index`.
-//
-// The CLI leaves (Stage B-6) are pure clients: every canvas.db touch these verbs
-// had — pruneNodes/pruneToLimit/reapEmptyNodes, the rebuild + fail-loud check,
-// the enriched snapshot roster, and the whole
-// buildCorpus/resolveRef search corpus — runs HERE, server-side. map.ts carries
-// no projector for these readers (frozen under concurrency with the sibling
-// handler author), so the field-mapping is inlined \u2014 a server-side projection,
-// the sanctioned place for it.
-import { existsSync, readdirSync } from 'node:fs';
-import { join } from 'node:path';
-import { listNodes, pruneNodes, pruneToLimit, rebuildIndex, rosterEdges, rosterNodes } from '../../../core/canvas/canvas.js';
+import { pruneNodes, pruneToLimit, rosterEdges, rosterNodes } from '../../../core/canvas/canvas.js';
 import { activeBackgroundBashJobs } from '../../../core/bash-jobs.js';
 import { contextDir } from '../../../core/canvas/paths.js';
 import { nowIso } from '../../../core/fs-utils.js';
@@ -21,9 +8,8 @@ import { localCanvasSource } from '../../../core/canvas/source.js';
 import { listFocuses } from '../../../core/canvas/focuses.js';
 import { ticketCountsForNodes, ticketsAcrossCanvas } from '../../../core/canvas/attention.js';
 import { buildCorpus, groupCorpus, resolveRef, } from '../../../core/canvas/history.js';
-import { nodeDir, nodesRoot } from '../../../core/canvas/paths.js';
 import { reapEmptyNodes } from '../../../core/runtime/placement.js';
-import { general, notFound, usage } from '../../../core/errors.js';
+import { notFound, usage } from '../../../core/errors.js';
 function handleAttention() {
     const body = {
         items: ticketsAcrossCanvas().map((t) => ({
@@ -319,8 +305,6 @@ async function handleSnapshot(ctx) {
     const asks = ticketCountsForNodes(rows.map((r) => r.node_id));
     await enrichRowsFromSource(localCanvasSource, rows, asks);
     const nodes = rows.map((row) => {
-        // Every field here comes from the NodeRow listNodes already fetched (stashed
-        // on the row as srcRow) — this handler opens no meta.json at all.
         const src = row.srcRow;
         const hostKind = src?.host_kind ?? 'tmux';
         return {
@@ -493,31 +477,6 @@ function handlePrune(ctx) {
     const body = { pruned, dry_run: dryRun, ttl_days: ttlDays };
     return { status: 200, body };
 }
-// rebuild-index \u2014 re-derive rows from on-disk metas + the fail-loud guard.
-// Lifted from `commands/canvas-rebuild-index.ts` (countOnDiskMetas + throw).
-function countOnDiskMetas() {
-    const root = nodesRoot();
-    if (!existsSync(root))
-        return 0;
-    let n = 0;
-    for (const id of readdirSync(root)) {
-        if (existsSync(join(nodeDir(id), 'meta.json')))
-            n++;
-    }
-    return n;
-}
-function handleRebuildIndex() {
-    const metas = countOnDiskMetas();
-    rebuildIndex();
-    const rows = listNodes().length;
-    if (metas > 0 && rows === 0) {
-        // A non-500 CrtrError so the specific diagnostic survives the error body
-        // (toErrorBody scrubs 500 messages for hygiene).
-        throw general(`rebuild-index found ${metas} on-disk meta.json file(s) under ${nodesRoot()} but produced 0 node rows in canvas.db \u2014 rebuild failed; refusing to leave an empty index`);
-    }
-    const body = { metas, rows };
-    return { status: 200, body };
-}
 export const canvasRoutes = [
     { method: 'GET', pattern: '/v1/canvas/attention', handler: handleAttention },
     { method: 'POST', pattern: '/v1/canvas/attention/counts', handler: handleAttentionCounts },
@@ -528,5 +487,4 @@ export const canvasRoutes = [
     { method: 'GET', pattern: '/v1/canvas/snapshot', handler: handleSnapshot },
     { method: 'GET', pattern: '/v1/canvas/roster', handler: handleRoster },
     { method: 'POST', pattern: '/v1/canvas/prune', handler: handlePrune },
-    { method: 'POST', pattern: '/v1/canvas/rebuild-index', handler: handleRebuildIndex },
 ];

package/dist/daemon/api/handlers/daemon.js

@@ -8,6 +8,7 @@
 // success, and the resumed agent sees an aborted tool call and re-runs it. Here
 // the daemon answers FIRST and hands over afterwards, so the ack is a settled
 // tool result in the caller's transcript before the SIGTERM lands.
+import { toMigrateStateDTO } from '../map.js';
 import { boundDaemonControl } from '../../control.js';
 function handleRestart() {
     const control = boundDaemonControl();
@@ -30,6 +31,46 @@ function handleRestart() {
     // 202: accepted, not yet performed — the handover happens after this response.
     return { status: 202, body };
 }
+async function handleAdmit(ctx) {
+    if (ctx.body !== undefined) {
+        throw { status: 400, code: 'invalid_request', message: 'admission request must not include a body' };
+    }
+    const control = boundDaemonControl();
+    if (control === null) {
+        throw {
+            status: 503,
+            code: 'daemon_control_unavailable',
+            message: 'this API server is not hosted by a live daemon and cannot admit normal work',
+        };
+    }
+    const body = await control.admitStartup();
+    return { status: 200, body };
+}
+async function handleMigrate(ctx) {
+    const control = boundDaemonControl();
+    if (control === null) {
+        throw {
+            status: 503,
+            code: 'daemon_control_unavailable',
+            message: 'this API server is not hosted by a live daemon and cannot migrate its corpus',
+        };
+    }
+    const body = ctx.body;
+    if (body !== undefined && (typeof body !== 'object' || body === null || Array.isArray(body))) {
+        throw { status: 400, code: 'invalid_request', message: 'migration request body must be an object' };
+    }
+    const raw = (body ?? {});
+    if (raw.dry_run !== undefined && typeof raw.dry_run !== 'boolean') {
+        throw { status: 400, code: 'invalid_request', message: 'dry_run must be a boolean' };
+    }
+    if (raw.dirs !== undefined && (!Array.isArray(raw.dirs) || raw.dirs.some((dir) => typeof dir !== 'string'))) {
+        throw { status: 400, code: 'invalid_request', message: 'dirs must be an array of strings' };
+    }
+    const result = await control.repairMigrations({ dryRun: raw.dry_run === true, dirs: (raw.dirs ?? []) });
+    return { status: 200, body: toMigrateStateDTO(result.result, { resumed: result.resumed, resumeError: result.resumeError }) };
+}
 export const daemonRoutes = [
     { method: 'POST', pattern: '/v1/daemon/restart', handler: (_ctx) => handleRestart() },
+    { method: 'POST', pattern: '/v1/daemon/migrate', handler: handleMigrate },
+    { method: 'POST', pattern: '/v1/daemon/admit', handler: handleAdmit },
 ];

package/dist/daemon/api/handlers/feedback-comments.js

@@ -12,7 +12,7 @@ import { ApiError } from '../../../api/index.js';
 import { createPageFeedbackComment, readPageFeedback, resolvePageFeedbackComment, PageFeedbackCommentAlreadyResolvedError, PageTicketTerminalError, UnknownPageFeedbackCommentError, } from '../../../core/human/feedback.js';
 import { discardFeedbackCompanion, pageDocumentSha256, realizeFeedbackCompanion } from '../../../core/human/feedback-companion.js';
 import { parsePage } from '../../../core/human/page.js';
-import { pageTicketState } from '../../../core/human/tickets.js';
+import { pageTicketState, selectedPageDir } from '../../../core/human/tickets.js';
 import { deliverNodeMessage } from '../../messaging/node-message.js';
 import { requireTicketId, resolveTicket } from './inbox.js';
 import { invalidRequest, objectBody, optionalString, requiredString } from './validate.js';
@@ -90,7 +90,7 @@ function parseCreate(ctx) {
 async function handleCreate(ctx) {
     const request = parseCreate(ctx);
     const resolved = requireMutablePageTicket(ctx);
-    const manifest = parsePage(resolved.dir);
+    const manifest = parsePage(selectedPageDir(resolved.dir));
     if (manifest.dialect !== 'jsx') {
         throw new ApiError(409, 'page_dialect_unsupported', 'feedback comments exist only on TSX pages');
     }

package/dist/daemon/api/handlers/health.js

@@ -13,7 +13,8 @@ import { API_VERSION } from '../../../api/index.js';
 import { DEFAULT_INTERVAL_MS } from '../../supervise-cadence.js';
 import { envCrtrdTcp } from '../../../shared/env.js';
 import { isPidAlive } from '../../../core/canvas/pid.js';
-import { isBusy } from '../../../core/runtime/busy.js';
+import { readLiveTurn } from '../../../core/canvas/recovery.js';
+import { boundDaemonControl } from '../../control.js';
 // The daemon's supervise-loop cadence, echoed as an informational field; the
 // loop itself is unchanged (hard constraint). Derived from the single shared
 // constant so it can never drift from crtrd's actual interval.
@@ -35,13 +36,16 @@ function nodeCounts(rows) {
 }
 function handleHealthz() {
     const storeAccessible = canvasRows() !== null;
+    const startup = boundDaemonControl()?.startupBlock() ?? null;
     const body = {
-        ok: storeAccessible,
+        ok: storeAccessible && startup === null,
         daemon_up: true,
         store_accessible: storeAccessible,
-        brokers_reconciled: true,
+        brokers_reconciled: startup === null,
+        startup_phase: startup?.phase ?? 'ready',
+        ...(startup === null ? {} : { startup_blocked: startup.message }),
     };
-    return { status: storeAccessible ? 200 : 503, body };
+    return { status: body.ok ? 200 : 503, body };
 }
 function handleStatus() {
     const rows = canvasRows();
@@ -49,7 +53,7 @@ function handleStatus() {
         // The store is unreachable — spec §8 store_unavailable.
         throw { status: 503, code: 'store_unavailable', message: 'canvas store is inaccessible' };
     }
-    const busyNodeCount = rows.filter((row) => row.kind !== 'human' && isBusy(row.node_id) && isPidAlive(row.pi_pid)).length;
+    const busyNodeCount = rows.filter((row) => row.kind !== 'human' && readLiveTurn(row.node_id)?.busy === true && isPidAlive(row.pi_pid)).length;
     const tcp = envCrtrdTcp();
     const body = {
         daemon_pid: process.pid,
@@ -62,6 +66,7 @@ function handleStatus() {
         },
         runtime_version: currentVersion(),
         api_version: API_VERSION,
+        startup_phase: boundDaemonControl()?.startupBlock()?.phase ?? 'ready',
     };
     return { status: 200, body };
 }