@crouton-kit/crouter 0.3.32 → 0.3.34

package/dist/core/view/stream-local.js

@@ -0,0 +1,184 @@
+import { randomUUID } from 'node:crypto';
+import { getRow } from '../canvas/index.js';
+import { BrokerUnavailableError, reconnectShouldGiveUp, ViewSocketClient } from '../runtime/view-socket-client.js';
+function makeInvalidTargetError(target) {
+    return {
+        kind: 'invalid-target',
+        display: {
+            headline: `invalid stream target: ${target}`,
+            explanation: 'Stream targets must be plain node ids.',
+            nextStep: 'Use a node id without /, \\, or .., then reconnect.',
+            level: 'error',
+            blocking: false,
+        },
+    };
+}
+function makeNoNodeError(target) {
+    return {
+        kind: 'no-node',
+        display: {
+            headline: `node ${target} does not exist`,
+            explanation: 'No node with that id was found in the canvas.',
+            nextStep: 'Check the node id and try again.',
+            level: 'error',
+            blocking: false,
+        },
+    };
+}
+function makeNoBrokerError(target) {
+    return {
+        kind: 'broker-unavailable',
+        display: {
+            headline: `node ${target} has no running broker`,
+            explanation: 'The stream transport connects only to an already-running broker.',
+            nextStep: `Run crtr node focus ${target} or crtr canvas revive ${target}, then reconnect.`,
+            level: 'error',
+            blocking: false,
+        },
+    };
+}
+function isValidTarget(target) {
+    return target.length > 0 && !target.includes('/') && !target.includes('\\') && !target.includes('..');
+}
+export function openLocalStream(req, handlers) {
+    const channelId = randomUUID();
+    const role = req.role ?? 'controller';
+    let client = null;
+    let closedByView = false;
+    let closeReported = false;
+    let reconnecting = false;
+    let everConnected = false;
+    let initialBrokerUnavailableReported = false;
+    const channel = {
+        id: channelId,
+        send(frame) {
+            client?.send(frame);
+        },
+        close() {
+            closedByView = true;
+            try {
+                client?.close();
+            }
+            catch {
+                /* best-effort */
+            }
+        },
+    };
+    const terminalClose = (reason) => {
+        if (closeReported || closedByView)
+            return;
+        closeReported = true;
+        try {
+            client?.close();
+        }
+        catch {
+            /* best-effort */
+        }
+        try {
+            handlers.onClose(reason);
+        }
+        catch {
+            /* best-effort */
+        }
+    };
+    const reportError = (err) => {
+        if (closeReported || closedByView)
+            return;
+        try {
+            handlers.onError(err);
+        }
+        catch {
+            /* best-effort */
+        }
+    };
+    const deferTerminalFailure = (reason, err) => {
+        queueMicrotask(() => {
+            reportError(err);
+            terminalClose(reason);
+        });
+    };
+    if (!isValidTarget(req.target)) {
+        deferTerminalFailure('invalid stream target', makeInvalidTargetError(req.target));
+        return channel;
+    }
+    if (getRow(req.target) === null) {
+        deferTerminalFailure('no node', makeNoNodeError(req.target));
+        return channel;
+    }
+    client = new ViewSocketClient(req.target, { emitUnmatchedDataFrames: true });
+    const sendHello = () => {
+        client?.send({ type: 'hello', role, client_id: channelId });
+    };
+    const reconnect = async () => {
+        if (closedByView || closeReported || reconnecting)
+            return;
+        reconnecting = true;
+        let delay = 200;
+        try {
+            while (!closedByView && !closeReported) {
+                const row = getRow(req.target);
+                if (row === null || reconnectShouldGiveUp(row)) {
+                    terminalClose('broker connection closed');
+                    return;
+                }
+                try {
+                    await client.redial();
+                    if (closedByView || closeReported)
+                        return;
+                    const current = getRow(req.target);
+                    if (current === null || reconnectShouldGiveUp(current)) {
+                        terminalClose('broker connection closed');
+                        return;
+                    }
+                    return;
+                }
+                catch {
+                    if (closedByView || closeReported)
+                        return;
+                    await new Promise((resolve) => setTimeout(resolve, delay));
+                    delay = Math.min(delay * 2, 1000);
+                }
+            }
+        }
+        finally {
+            reconnecting = false;
+        }
+    };
+    client.on('connect', () => {
+        if (closedByView || closeReported)
+            return;
+        everConnected = true;
+        sendHello();
+    });
+    client.on('frame', (frame) => {
+        if (closedByView || closeReported)
+            return;
+        try {
+            handlers.onFrame(frame);
+        }
+        catch {
+            /* best-effort */
+        }
+    });
+    client.on('error', (err) => {
+        if (closedByView || closeReported)
+            return;
+        if (err instanceof BrokerUnavailableError && !everConnected && !initialBrokerUnavailableReported) {
+            initialBrokerUnavailableReported = true;
+            reportError(makeNoBrokerError(req.target));
+        }
+    });
+    client.on('close', () => {
+        if (closedByView || closeReported)
+            return;
+        if (reconnecting)
+            return;
+        if (!everConnected) {
+            terminalClose('node has no running broker');
+            return;
+        }
+        void reconnect();
+    });
+    client.connect();
+    return channel;
+}

package/dist/core/view/transport-cache.d.ts

@@ -0,0 +1,8 @@
+import type { SourceRequest } from './contract.js';
+import type { Transport } from './transport.js';
+export interface BurstCoalescingOptions {
+    ttlMs: number;
+    shouldCache(req: SourceRequest): boolean;
+    now?: () => number;
+}
+export declare function createBurstCoalescingTransport(inner: Transport, opts: BurstCoalescingOptions): Transport;

package/dist/core/view/transport-cache.js

@@ -0,0 +1,38 @@
+// transport-cache.ts — small host-side burst coalescing for expensive reads.
+//
+// The SourceRequest/Transport contract stays unchanged: callers still send the
+// same request and receive the same RawResponse. This decorator only changes the
+// host's scheduling for requests the host explicitly marks cacheable.
+export function createBurstCoalescingTransport(inner, opts) {
+    const now = opts.now ?? Date.now;
+    const inflight = new Map();
+    const cache = new Map();
+    const send = async (req) => {
+        if (!opts.shouldCache(req))
+            return inner.send(req);
+        const key = JSON.stringify(req);
+        const cached = cache.get(key);
+        if (cached !== undefined) {
+            if (cached.expiresAt > now())
+                return cached.response;
+            cache.delete(key);
+        }
+        const pending = inflight.get(key);
+        if (pending !== undefined)
+            return pending;
+        const run = inner.send(req).then((response) => {
+            cache.set(key, { expiresAt: now() + opts.ttlMs, response });
+            return response;
+        }).finally(() => {
+            inflight.delete(key);
+        });
+        inflight.set(key, run);
+        return run;
+    };
+    return {
+        send,
+        open(req, handlers) {
+            return inner.open(req, handlers);
+        },
+    };
+}

package/dist/core/view/transport-local.js

@@ -8,6 +8,7 @@
 // source's parse() job.
 import { execFile } from 'node:child_process';
 import { readFile } from 'node:fs/promises';
+import { openLocalStream } from './stream-local.js';
 const MAX_BUFFER = 10 * 1024 * 1024;
 export function createLocalTransport(opts = {}) {
     const baseCwd = opts.cwd ?? process.cwd();
@@ -19,6 +20,9 @@ export function createLocalTransport(opts = {}) {
                 case 'http': return sendHttp(req);
             }
         },
+        open(req, handlers) {
+            return openLocalStream(req, handlers);
+        },
     };
 }
 function sendExec(req, baseCwd) {

package/dist/core/view/transport.d.ts

@@ -1,4 +1,10 @@
-import type { SourceRequest, RawResponse } from './contract.js';
+import type { SourceRequest, RawResponse, StreamRequest, StreamChannel, SourceError } from './contract.js';
+export interface StreamHandlers {
+    onFrame(frame: unknown): void;
+    onClose(reason: string): void;
+    onError(err: SourceError): void;
+}
 export interface Transport {
     send(req: SourceRequest): Promise<RawResponse>;
+    open(req: StreamRequest, handlers: StreamHandlers): StreamChannel;
 }

package/dist/core/wake.d.ts

@@ -67,9 +67,9 @@ export declare function parseCadence(every: string, opts: ParseOpts): CadenceRes
  *   - {"cron":"0 9 * * *","tz":"America/…"}  -> ``cron `0 9 * * *` (America/…)``
  *   - null / undefined / unparseable         -> `none`
  *
- * The ONE cadence-display helper, shared by the `node wake` CLI surface
+ * The ONE cadence-display helper, shared by the `node triggers` CLI surface
  * (list/guidance) and the <crtr-wake> wake-provenance block (bearings.ts), so
- * the cadence an agent reads in its wake block matches `crtr node wake list`
+ * the cadence an agent reads in its wake block matches `crtr node triggers`
  * exactly. Cadence only — never an instance count.
  */
 export declare function cadenceDisplay(recur: string | null | undefined): string;

package/dist/core/wake.js

@@ -1,9 +1,9 @@
-// Time grammar + recurrence evaluation for scheduled wakeups.
+// Time grammar + recurrence evaluation for scheduled triggers.
 //
-// This is the ONE place that owns wakeup time logic. Both the CLI surface
-// (`node wake at|until|spawn`) and the daemon's firing pass import
-// from here, so there is no duplicated cron usage and no surface<->daemon
-// inverted dependency:
+// This is the ONE place that owns trigger time logic. Both the CLI surface
+// (`node new --at/--every/--when`, `node msg --at/--every/--when`) and the
+// daemon's firing pass import from here, so there is no duplicated cron usage
+// and no surface<->daemon inverted dependency:
 //   - parseWhen / parseCadence  — arm-time grammar (surface, T7)
 //   - nextSlotAfter             — per-tick advance / coalescing (daemon, T4)
 //
@@ -250,9 +250,9 @@ export function parseCadence(every, opts) {
  *   - {"cron":"0 9 * * *","tz":"America/…"}  -> ``cron `0 9 * * *` (America/…)``
  *   - null / undefined / unparseable         -> `none`
  *
- * The ONE cadence-display helper, shared by the `node wake` CLI surface
+ * The ONE cadence-display helper, shared by the `node triggers` CLI surface
  * (list/guidance) and the <crtr-wake> wake-provenance block (bearings.ts), so
- * the cadence an agent reads in its wake block matches `crtr node wake list`
+ * the cadence an agent reads in its wake block matches `crtr node triggers`
  * exactly. Cadence only — never an instance count.
  */
 export function cadenceDisplay(recur) {

package/dist/daemon/__tests__/predicate-eval.test.js

@@ -0,0 +1,109 @@
+// Regression for final-integrated-verdict Major #1: a predicate whose script
+// writes more than STDOUT_CAP_BYTES to stdout AND exits non-zero must be
+// RESCHEDULED (stay armed), never fired and never stuck running. Before the
+// fix, `finish()` in `src/daemon/predicate-eval.ts` checked `overflowed`
+// BEFORE the exit-code branch, so any verbose non-zero predicate got consumed
+// on its first poll. The fix gates the overflow check on `code === 0 &&
+// stdoutIsBody`. Drives the REAL `evaluateDuePredicates` — no child_process
+// mocking, a real subprocess is spawned.
+import { test, before, beforeEach, after } from 'node:test';
+import assert from 'node:assert/strict';
+import { mkdtempSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { createNode, closeDb, armTrigger, listTriggers } from '../../core/canvas/index.js';
+import { evaluateDuePredicates } from '../predicate-eval.js';
+let home;
+function node(id, cwd) {
+    return {
+        node_id: id,
+        name: id,
+        created: new Date().toISOString(),
+        cwd,
+        kind: 'general',
+        mode: 'base',
+        lifecycle: 'terminal',
+        status: 'active',
+    };
+}
+before(() => {
+    home = mkdtempSync(join(tmpdir(), 'crtr-predicate-eval-'));
+    process.env['CRTR_HOME'] = home;
+});
+beforeEach(() => {
+    closeDb();
+    rmSync(home, { recursive: true, force: true });
+});
+after(() => {
+    closeDb();
+    rmSync(home, { recursive: true, force: true });
+    delete process.env['CRTR_HOME'];
+});
+/** Poll a trigger's row (via listTriggers) until an evaluation has completed
+ *  (`last_exit` set) or the timeout elapses. Fire-and-forget evaluation
+ *  settles asynchronously off a real child process. */
+async function waitForEvalSettled(nodeId, timeoutMs = 5000) {
+    const start = Date.now();
+    for (;;) {
+        const rows = listTriggers({ node: nodeId });
+        if (rows.length > 0 && rows[0].last_exit !== null)
+            return;
+        if (Date.now() - start > timeoutMs)
+            throw new Error('timed out waiting for predicate evaluation to settle');
+        await new Promise((r) => setTimeout(r, 50));
+    }
+}
+test('a >16KiB-stdout, non-zero-exit predicate stays armed (rescheduled, not fired/stuck)', async () => {
+    const meta = createNode(node('target-1', home));
+    const trigger_id = 'trig-overflow-nonzero';
+    armTrigger({
+        trigger_id,
+        node_id: meta.node_id,
+        owner_id: meta.node_id,
+        action: 'msg',
+        action_mode: 'inbox_message',
+        trigger_type: 'when',
+        when_script: `node -e "process.stdout.write('x'.repeat(20000)); process.exit(1)"`,
+        eval_every: JSON.stringify({ every: '1m' }),
+        next_eval_at: new Date(Date.now() - 1000).toISOString(),
+        payload: { label: 'test' },
+    });
+    const outcomes = [];
+    evaluateDuePredicates(Date.now(), (o) => outcomes.push(o));
+    await waitForEvalSettled(meta.node_id);
+    // Nothing fired/canceled: onDone was never invoked for this trigger.
+    assert.equal(outcomes.length, 0);
+    // The trigger row still exists (still armed), rescheduled to idle with the
+    // non-zero exit recorded — not stuck 'running'.
+    const rows = listTriggers({ node: meta.node_id });
+    assert.equal(rows.length, 1);
+    assert.equal(rows[0].trigger_id, trigger_id);
+    assert.equal(rows[0].eval_state, 'idle');
+    assert.notEqual(rows[0].last_exit, 0);
+});
+test('sanity: a small-output exit-0 predicate fires and is consumed', async () => {
+    const meta = createNode(node('target-2', home));
+    const trigger_id = 'trig-fires-clean';
+    armTrigger({
+        trigger_id,
+        node_id: meta.node_id,
+        owner_id: meta.node_id,
+        action: 'msg',
+        action_mode: 'inbox_message',
+        trigger_type: 'when',
+        when_script: `echo ok`,
+        eval_every: JSON.stringify({ every: '1m' }),
+        next_eval_at: new Date(Date.now() - 1000).toISOString(),
+        payload: { label: 'test' },
+    });
+    const outcomes = [];
+    evaluateDuePredicates(Date.now(), (o) => outcomes.push(o));
+    const start = Date.now();
+    while (outcomes.length === 0 && Date.now() - start < 5000) {
+        await new Promise((r) => setTimeout(r, 50));
+    }
+    assert.equal(outcomes.length, 1);
+    assert.equal(outcomes[0].kind, 'fired');
+    // Consumed: the trigger row is gone.
+    assert.equal(listTriggers({ node: meta.node_id }).length, 0);
+});

package/dist/daemon/crtrd.d.ts

@@ -1,4 +1,6 @@
 import { type NodeRow } from '../core/canvas/index.js';
+import { FAULT_QUIET_MS } from '../core/runtime/fault.js';
+export { FAULT_QUIET_MS };
 import { isPidAlive } from '../core/canvas/pid.js';
 export declare const YIELD_STALL_GRACE_MS: number;
 /** Refresh-stall decision (§H refresh-authority; audit 2026-06-09, Bug 1 — node
@@ -17,25 +19,6 @@ export declare const YIELD_STALL_GRACE_MS: number;
  *  after running `node yield` mid-turn, and a working engine must never be
  *  killed), and the state has persisted past YIELD_STALL_GRACE_MS. */
 export declare function yieldStallVerdict(piPidAlive: boolean | null, intent: NodeRow['intent'], busy: boolean, stalledFor: number | null): 'leave' | 'pending' | 'kill';
-export declare const ERROR_STALL_QUIET_MS: number;
-/** The §I wedge signature, from a session-jsonl tail: the LAST assistant
- *  message stopped with 'error' (retry budget exhausted — pi appends the error
- *  turn and parks). Returns its errorMessage for the daemon log (the "why it
- *  wedged" trace), or null when the last assistant turn ended any other way —
- *  'stop'/'length' is a healthy park, 'aborted' is a human Esc, and trailing
- *  non-assistant lines (toolResults, an injected user message) are walked past.
- *  The first line of a mid-file tail cut fails JSON.parse and is skipped. */
-export declare function trailingEngineError(tail: string | null): string | null;
-/** Error-stall decision (§I; gh issue #4 — node mqaeqzdu-0746b3b7, a 9h zombie
- *  after an Anthropic outage). Pure, mirroring yieldStallVerdict; the kill side
- *  effects live in handleErrorStall.
- *
- *  'kill' ONLY when ALL of: engine alive, NO pending intent (refresh is §H's
- *  domain; idle-release chose dormancy), the turn is over (busy absent — a node
- *  wedged mid-bash must be recovered by killing the subprocess, never the node),
- *  the session file has been quiet past ERROR_STALL_QUIET_MS, and its last
- *  assistant message stopped with 'error'. */
-export declare function errorStallVerdict(piPidAlive: boolean | null, intent: NodeRow['intent'], busy: boolean, quietForMs: number | null, trailingError: boolean): 'leave' | 'kill';
 export type LivenessVerdict = 'leave' | 'pending' | 'revive';
 /** Decide what to do with a node whose engine pid is DEAD, from how long it's
  *  been dead. Pure — the time/revive side effects live in handleNodeLiveness;
@@ -50,6 +33,7 @@ export declare function readPidfile(): number | null;
 export { isPidAlive };
 /** True when a crtrd process is already running (pidfile exists + pid alive). */
 export declare function isDaemonRunning(): boolean;
+/** Supervision tick over the daemon's current live set. */
 export declare function superviseTick(now?: number): Promise<void>;
 export interface DaemonOpts {
     /** Milliseconds between supervision polls. Default 2000. */