@north-light/crouter 0.3.173 → 0.3.174

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

@@ -0,0 +1,383 @@
+// Broker-originated canvas operations. The broker sends Pi lifecycle facts;
+// crtrd validates and commits their durable effects while the handler stays
+// strictly canvas-write-only — no broker launch, kill, or view.sock round trip.
+import { getNode, isWarmSpare, listNodes, recordPid, setPresence, subscriptionsOf, updateNode } from '../../../core/canvas/canvas.js';
+import { isSafeNodeId } from '../../../core/canvas/paths.js';
+import { editorLabel } from '../../../core/canvas/labels.js';
+import { assembleNodeSubject } from '../../../core/substrate/subject.js';
+import { withCanvasWrite } from '../../../core/canvas/db.js';
+import { notFound, usage } from '../../../core/errors.js';
+import { readCursor, readInboxSince, writeCursor } from '../../../core/feed/inbox.js';
+import { clearYieldMessage } from '../../../core/runtime/kickoff.js';
+import { transition } from '../../../core/runtime/lifecycle.js';
+import { focusOf, tearDownNode } from '../../../core/runtime/placement.js';
+import { handleNewSession } from '../../../core/runtime/reset.js';
+import { evaluateStop } from '../../../core/runtime/stop-guard.js';
+import { clearFault } from '../../../core/runtime/fault.js';
+import { updateModelRecipe } from '../../../core/runtime/model-swap.js';
+function objectBody(body, operation) {
+    if (typeof body !== 'object' || body === null || Array.isArray(body)) {
+        throw usage(`${operation} requires a JSON body`);
+    }
+    return body;
+}
+function parseSessionBoundBody(body) {
+    const value = objectBody(body, 'broker session-bound');
+    if (typeof value['piSessionId'] !== 'string' || value['piSessionId'] === '') {
+        throw usage('piSessionId must be a non-empty string');
+    }
+    if (value['sessionFile'] !== null && typeof value['sessionFile'] !== 'string') {
+        throw usage('sessionFile must be a string or null');
+    }
+    if (!Number.isSafeInteger(value['pid']) || value['pid'] <= 0) {
+        throw usage('pid must be a positive safe integer');
+    }
+    if (value['reason'] !== null && typeof value['reason'] !== 'string') {
+        throw usage('reason must be a string or null');
+    }
+    if (!Array.isArray(value['reviewBoundaryIds'])
+        || !value['reviewBoundaryIds'].every((id) => typeof id === 'string')) {
+        throw usage('reviewBoundaryIds must be an array of strings');
+    }
+    return value;
+}
+function parseSettleBody(body) {
+    const value = objectBody(body, 'broker settle');
+    if (typeof value['stopReason'] !== 'string')
+        throw usage('stopReason must be a string');
+    for (const field of ['backgroundJobsRunning', 'pushedFinal', 'askedHuman']) {
+        if (typeof value[field] !== 'boolean')
+            throw usage(`${field} must be a boolean`);
+    }
+    return value;
+}
+function parseInboxCursorBody(body) {
+    const value = objectBody(body, 'broker inbox-cursor');
+    const throughEntryId = value['throughEntryId'];
+    if (typeof throughEntryId !== 'string' || !/^(?!0{32}$)[0-9a-f]{32}$/.test(throughEntryId)) {
+        throw usage('throughEntryId must be a non-zero 32-character lowercase hexadecimal inbox entry id');
+    }
+    const brokerPid = value['brokerPid'];
+    if (!Number.isSafeInteger(brokerPid) || brokerPid <= 0) {
+        throw usage('brokerPid must be a positive safe integer');
+    }
+    return { throughEntryId, brokerPid: brokerPid };
+}
+function parseModelCommitBody(body) {
+    const value = objectBody(body, 'broker model');
+    if (typeof value['spec'] !== 'string' || value['spec'].trim() === '')
+        throw usage('spec must be a non-empty string');
+    if (value['pinnedOverride'] !== undefined && typeof value['pinnedOverride'] !== 'boolean') {
+        throw usage('pinnedOverride must be a boolean when present');
+    }
+    if (typeof value['userSelected'] !== 'boolean')
+        throw usage('userSelected must be a boolean');
+    return value;
+}
+function requireNode(nodeId) {
+    const node = getNode(nodeId);
+    if (node === null)
+        throw notFound(`unknown node: ${nodeId}`, { received: nodeId });
+    return node;
+}
+function extensionNode(node) {
+    return {
+        node_id: node.node_id,
+        name: node.name,
+        ...(node.description === undefined ? {} : { description: node.description }),
+        ...(node.icon === undefined ? {} : { icon: node.icon }),
+        kind: node.kind,
+        mode: node.mode,
+        lifecycle: node.lifecycle,
+        status: node.status,
+        cwd: node.cwd,
+        parent: node.parent ?? null,
+        fork_from: node.fork_from ?? null,
+        profile_id: node.profile_id ?? null,
+        ...(node.managed_worktree === undefined ? {} : { managed_worktree: node.managed_worktree === null ? null : {
+                state: node.managed_worktree.state,
+                path: node.managed_worktree.path,
+                branch: node.managed_worktree.branch,
+                base_ref: node.managed_worktree.base_ref,
+                base_sha: node.managed_worktree.base_sha,
+            } }),
+        ...(node.review_binding === undefined ? {} : { review_binding: node.review_binding ?? null }),
+        intent: node.intent ?? null,
+        ...(node.persona_ack === undefined ? {} : { persona_ack: node.persona_ack }),
+        created: node.created,
+    };
+}
+function extensionState(nodeId) {
+    const node = requireNode(nodeId);
+    const ancestors = [];
+    const seen = new Set([nodeId]);
+    let parentId = node.parent ?? null;
+    while (parentId !== null && parentId !== '' && !seen.has(parentId)) {
+        seen.add(parentId);
+        const parent = getNode(parentId);
+        if (parent === null)
+            break;
+        ancestors.unshift(extensionNode(parent));
+        parentId = parent.parent ?? null;
+    }
+    const children = subscriptionsOf(nodeId)
+        .map((subscription) => getNode(subscription.node_id))
+        .filter((child) => child !== null && child.kind !== 'human')
+        .sort((a, b) => (a.status === b.status ? 0 : a.status === 'active' ? -1 : b.status === 'active' ? 1 : 0))
+        .map(extensionNode);
+    const source = node.fork_from === undefined || node.fork_from === null || node.fork_from === '' || !isSafeNodeId(node.fork_from)
+        ? null
+        : getNode(node.fork_from);
+    const subject = assembleNodeSubject(nodeId);
+    if (subject === null)
+        throw notFound(`unknown node: ${nodeId}`, { received: nodeId });
+    const report_nodes = listNodes().map((row) => ({ node_id: row.node_id, name: row.name, created: row.created }));
+    return {
+        node: extensionNode(node),
+        warm_spare: isWarmSpare(nodeId),
+        ancestors,
+        children,
+        fork_source: source === null ? null : extensionNode(source),
+        subject,
+        report_nodes,
+    };
+}
+function samePersona(a, b) {
+    return a?.mode === b.mode && a?.lifecycle === b.lifecycle;
+}
+function parseGeneratedNameBody(body) {
+    const value = objectBody(body, 'broker generated-name');
+    if (value['kind'] !== 'initial' && value['kind'] !== 'recap')
+        throw usage('kind must be initial or recap');
+    if (typeof value['description'] !== 'string' || typeof value['icon'] !== 'string') {
+        throw usage('description and icon must be strings');
+    }
+    if (value['kind'] === 'initial')
+        return { kind: 'initial', description: value['description'], icon: value['icon'] };
+    const expected = value['expected'];
+    if (typeof expected !== 'object' || expected === null || Array.isArray(expected)
+        || ['name', 'description', 'icon', 'kind'].some((key) => typeof expected[key] !== 'string')) {
+        throw usage('recap expected must contain name, description, icon, and kind strings');
+    }
+    return { kind: 'recap', description: value['description'], icon: value['icon'], expected: expected };
+}
+function parsePersonaAckBody(body) {
+    const value = objectBody(body, 'broker persona-ack');
+    const parse = (key) => {
+        const persona = value[key];
+        if (typeof persona !== 'object' || persona === null || Array.isArray(persona)
+            || (persona['mode'] !== 'base' && persona['mode'] !== 'orchestrator')
+            || (persona['lifecycle'] !== 'terminal' && persona['lifecycle'] !== 'resident')) {
+            throw usage(`${key} must be a persona state`);
+        }
+        return persona;
+    };
+    return { from: parse('from'), to: parse('to') };
+}
+function handleSessionBound(ctx) {
+    const nodeId = ctx.params['id'];
+    const request = parseSessionBoundBody(ctx.body);
+    const result = withCanvasWrite(() => {
+        const before = requireNode(nodeId);
+        // The broker reports the markers present in Pi's current branch; crtrd owns
+        // the review binding and decides whether that branch belongs to this node.
+        const reviewId = before.review_binding?.review_id;
+        if (reviewId !== undefined && !request.reviewBoundaryIds.includes(reviewId)) {
+            return { action: 'shutdown' };
+        }
+        let action = 'none';
+        if (request.reason === 'new') {
+            if (before.parent == null) {
+                // Root relaunch launches and tears down brokers. Return a directive for
+                // the calling extension rather than re-entering that broker here.
+                action = 'relaunch_root';
+            }
+            else {
+                handleNewSession(nodeId, request.piSessionId, request.sessionFile);
+            }
+        }
+        else if (before.fork_from != null && before.pi_session_id == null && request.sessionFile === null) {
+            // Pi has not exposed complete writable coordinates for this ordinary fork.
+            // Leave it unbound so recovery cannot fork provenance twice.
+            action = 'shutdown';
+        }
+        else {
+            // Confirmed boot: consume the one-shot yield note, bind the new Pi session
+            // coordinates, stamp broker liveness, and commit any pending refresh.
+            clearYieldMessage(nodeId);
+            updateNode(nodeId, {
+                pi_session_id: request.piSessionId,
+                pi_session_file: request.sessionFile,
+                cycle_pending: false,
+            });
+            recordPid(nodeId, request.pid);
+            if (before.intent === 'refresh')
+                transition(nodeId, 'revive');
+        }
+        return { action };
+    });
+    return { status: 200, body: result };
+}
+function hasUnseenNonDeferredInbox(nodeId) {
+    return readInboxSince(nodeId, readCursor(nodeId)).some((entry) => entry.tier !== 'deferred');
+}
+/** Commit the complete broker-settlement policy while holding one canvas write
+ * boundary. This handler intentionally never invokes the broker that called it:
+ * the returned directive is the only Pi-side consequence. */
+function settleBroker(nodeId, request) {
+    const node = getNode(nodeId);
+    if (node === null) {
+        // A command may have recorded its Pi-local completion marker just as an
+        // external close removes the row. There is no daemon write to perform, but
+        // preserving the marker's fail-safe consequence avoids leaving an orphaned
+        // broker alive while never fabricating a replacement canvas row.
+        if (request.pushedFinal)
+            return { action: 'shutdown' };
+        if (request.askedHuman)
+            return { action: 'stay_dormant' };
+        throw notFound(`unknown node: ${nodeId}`, { received: nodeId });
+    }
+    if (request.stopReason === 'quit') {
+        if ((node.status === 'active' || node.status === 'idle') && node.intent === null) {
+            transition(nodeId, 'finish');
+            clearFault(nodeId);
+            if (focusOf(nodeId) !== null)
+                tearDownNode(nodeId);
+            setPresence(nodeId, { pane: null, tmux_session: null, window: null });
+        }
+        return { action: 'shutdown' };
+    }
+    // Interrupted runs remain live for re-steering. A refresh intentionally
+    // aborts its own turn, so it is the one non-natural stop that exits.
+    if (request.stopReason !== 'stop' && request.stopReason !== 'length') {
+        clearFault(nodeId, { link: 'daemon→node' });
+        return node.intent === 'refresh' ? { action: 'shutdown' } : { action: 'stay_dormant' };
+    }
+    const signals = { pushedFinal: request.pushedFinal, askedHuman: request.askedHuman };
+    // These two current-state outcomes were previously duplicated around the
+    // stop guard. They are terminal broker consequences, not Pi decisions.
+    if (signals.pushedFinal || node.status === 'done') {
+        clearFault(nodeId);
+        if (focusOf(nodeId) !== null)
+            tearDownNode(nodeId);
+        setPresence(nodeId, { pane: null, tmux_session: null, window: null });
+        return { action: 'shutdown' };
+    }
+    if (signals.askedHuman) {
+        clearFault(nodeId);
+        return { action: 'stay_dormant' };
+    }
+    if (node.intent === 'refresh') {
+        clearFault(nodeId);
+        return { action: 'shutdown' };
+    }
+    const decision = evaluateStop(nodeId, signals, request.backgroundJobsRunning);
+    clearFault(nodeId);
+    if (decision.action === 'reprompt')
+        return { action: 'reprompt', prompt: decision.message };
+    if (decision.reason === 'finished') {
+        return hasUnseenNonDeferredInbox(nodeId) ? { action: 'stay_dormant' } : { action: 'shutdown' };
+    }
+    if (decision.reason !== 'awaiting' && decision.reason !== 'scheduled') {
+        return { action: 'stay_dormant' };
+    }
+    if (focusOf(nodeId) !== null || hasUnseenNonDeferredInbox(nodeId))
+        return { action: 'stay_dormant' };
+    transition(nodeId, 'release');
+    return { action: 'shutdown' };
+}
+function handleSettle(ctx) {
+    const nodeId = ctx.params['id'];
+    const request = parseSettleBody(ctx.body);
+    const directive = withCanvasWrite(() => settleBroker(nodeId, request));
+    return { status: 200, body: directive };
+}
+/** Commit a watcher cursor only while this broker generation remains current.
+ * A refresh or a replacement binding must leave the cursor untouched so the
+ * replacement replays every handoff that may have reached the discarded Pi
+ * conversation. */
+function handleInboxCursor(ctx) {
+    const nodeId = ctx.params['id'];
+    const request = parseInboxCursorBody(ctx.body);
+    const directive = withCanvasWrite(() => {
+        const node = requireNode(nodeId);
+        if (node.intent === 'refresh' || node.pi_pid !== request.brokerPid)
+            return { action: 'hold_refresh' };
+        const entries = readInboxSince(nodeId);
+        const throughIndex = entries.findIndex((entry) => entry.entry_id === request.throughEntryId);
+        if (throughIndex < 0)
+            throw usage('throughEntryId must identify an entry in this node inbox');
+        const cursor = readCursor(nodeId);
+        const cursorIndex = cursor === undefined ? -1 : entries.findIndex((entry) => entry.entry_id === cursor);
+        if (cursor !== undefined && cursorIndex < 0)
+            throw new Error(`inbox cursor entry_id not found: ${cursor}`);
+        if (throughIndex < cursorIndex)
+            throw usage('throughEntryId must not precede the durable inbox cursor');
+        if (throughIndex > cursorIndex)
+            writeCursor(nodeId, request.throughEntryId);
+        return { action: 'advanced' };
+    });
+    return { status: 200, body: directive };
+}
+function handleModelCommit(ctx) {
+    const nodeId = ctx.params['id'];
+    const request = parseModelCommitBody(ctx.body);
+    const updated = withCanvasWrite(() => updateModelRecipe(requireNode(nodeId), request.spec, request.pinnedOverride, request.userSelected));
+    return { status: 200, body: { modelOverride: updated.model_override } };
+}
+function handleExtensionState(ctx) {
+    return { status: 200, body: extensionState(ctx.params['id']) };
+}
+/** The only generated-name writer brokers may invoke. It is a compare-and-swap
+ * over the automatic label snapshot, so a human rename or newer name result
+ * wins rather than being overwritten by an older headless process. */
+function handleGeneratedName(ctx) {
+    const nodeId = ctx.params['id'];
+    const request = parseGeneratedNameBody(ctx.body);
+    const result = withCanvasWrite(() => {
+        const node = requireNode(nodeId);
+        if (request.kind === 'initial') {
+            if ((node.description ?? '').trim() !== '')
+                return { applied: false };
+            const updated = updateNode(nodeId, {
+                description: request.description,
+                ...(request.icon.trim() === '' ? {} : { icon: request.icon }),
+            });
+            return { applied: true, editorLabel: editorLabel(updated) };
+        }
+        const expected = request.expected;
+        if (node.name !== expected.name || (node.description ?? '') !== expected.description
+            || (node.icon ?? '') !== expected.icon || node.kind !== expected.kind)
+            return { applied: false };
+        const updated = updateNode(nodeId, {
+            description: request.description,
+            icon: request.icon.trim() === '' ? undefined : request.icon,
+        });
+        return { applied: true, editorLabel: editorLabel(updated) };
+    });
+    return { status: 200, body: result };
+}
+/** Ack after Pi accepted transition guidance. The expected transition prevents a
+ * stale broker from acknowledging a later persona change it did not describe. */
+function handlePersonaAck(ctx) {
+    const nodeId = ctx.params['id'];
+    const request = parsePersonaAckBody(ctx.body);
+    withCanvasWrite(() => {
+        const node = requireNode(nodeId);
+        const current = { mode: node.mode, lifecycle: node.lifecycle };
+        const acknowledged = node.persona_ack ?? current;
+        if (!samePersona(current, request.to) || !samePersona(acknowledged, request.from))
+            return;
+        updateNode(nodeId, { persona_ack: request.to });
+    });
+    return { status: 204 };
+}
+export const brokerOperationRoutes = [
+    { method: 'POST', pattern: '/v1/nodes/:id/broker/session-bound', handler: handleSessionBound },
+    { method: 'POST', pattern: '/v1/nodes/:id/broker/settle', handler: handleSettle },
+    { method: 'POST', pattern: '/v1/nodes/:id/broker/inbox-cursor', handler: handleInboxCursor },
+    { method: 'POST', pattern: '/v1/nodes/:id/broker/model', handler: handleModelCommit },
+    { method: 'GET', pattern: '/v1/nodes/:id/broker/extension-state', handler: handleExtensionState },
+    { method: 'POST', pattern: '/v1/nodes/:id/broker/generated-name', handler: handleGeneratedName },
+    { method: 'POST', pattern: '/v1/nodes/:id/broker/persona-ack', handler: handlePersonaAck },
+];

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

@@ -13,8 +13,8 @@
 // this handler validates the full arm surface (timing SHAPE and
 // advanceability, enums, env, sink shape + arm-time target existence, anchor
 // coupling), applies spec defaults for the rest, and inserts through the DAO.
-// crtrd is the sole state owner and the CLI is only one of its clients (the
-// web UI and Northlight Core call the same routes), so nothing here trusts a
+// crtrd is the sole state owner and the CLI is only one of its clients
+// (Northlight Core calls the same routes), so nothing here trusts a
 // client-resolved value it can check itself. Every per-cron route resolves
 // through `requireCron`, which enforces the caller's profile scope. The sink is stored as JSON (`{"node":…}` /
 // `{"spawn":…}` / `{"human":true}` / `{}`); the DTO renders it back to the
@@ -25,7 +25,7 @@ import { armCron, cancelCron, getCron, listCrons, listCronRuns, setCronState, }
 import { getNode } from '../../../core/canvas/canvas.js';
 import { InputError } from '../../../core/io.js';
 import { nextSlotAfter } from '../../../core/wake.js';
-import { executeCron } from '../../cron-run.js';
+import { executeCron, markSelfCanceledCronRun } from '../../cron-run.js';
 import { toCronDTO, toCronRunDTO } from '../map.js';
 function requireString(req, field) {
     const v = req[field];
@@ -340,7 +340,12 @@ function handleCancel(ctx) {
     if (c !== null && !inScope(c, callerProfile(ctx))) {
         throw new ApiError(404, 'cron_not_found', `no cron ${cronId} in this profile — it is scoped to another profile`);
     }
-    cancelCron(cronId);
+    const runId = ctx.query.get('run_id');
+    // Only the currently running process can preserve itself. An arbitrary or
+    // stale run id falls through to the normal cancellation that kills the
+    // process group before removing the row.
+    const preserveRunningProcess = runId !== null && markSelfCanceledCronRun(cronId, runId);
+    cancelCron(cronId, { preserveRunningProcess });
     return { status: 204 };
 }
 export const cronRoutes = [

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

@@ -1,12 +1,11 @@
 // Host file-read handler — `GET /v1/files/peek?path=<abs>` (spec §6). Reads an
-// absolute host path as UTF-8 for the browser file-peek panel (the transcript's
-// "any file path opens here" surface). The read is byte-capped → `truncated`,
-// so an accidental peek of a huge log/binary never streams unbounded memory.
+// absolute host path as UTF-8 for API clients that present transcript-linked
+// files. The read is byte-capped → `truncated`, so an accidental peek of a huge
+// log/binary never streams unbounded memory.
 //
-// Trust model: crtrd runs as the single local user behind a unix socket; the
-// browser reaches this only through the web shell's auth-gated `/v1` proxy —
-// the same boundary as every other route. No node scoping: a peeked path is an
-// arbitrary host path shown in the transcript, not a node-owned artifact.
+// Trust model: crtrd runs as the single local user behind a unix socket. No
+// node scoping: a peeked path is an arbitrary host path presented to the client,
+// not a node-owned artifact.
 import { closeSync, fstatSync, openSync, readSync } from 'node:fs';
 import { isAbsolute } from 'node:path';
 import { notFound, usage } from '../../../core/errors.js';