@north-light/crouter 0.3.173 → 0.3.175

package/dist/pi-extensions/__tests__/canvas-stophook-context-nudge.test.js

@@ -13,16 +13,27 @@
 // 'toolUse' (pi-ai's StopReason), NEVER 'stop'. Gating the steer path on
 // stopReason 'stop'/'length' made runContinues unconditionally false, so the
 // nudge was ALWAYS appended as nextTurn and never steered mid-run.
-import { test, before, after, beforeEach } from 'node:test';
+import { test, before, after, beforeEach, afterEach } from 'node:test';
 import assert from 'node:assert/strict';
-import { mkdtempSync, rmSync } from 'node:fs';
+import { existsSync, mkdtempSync, mkdirSync, rmSync } from 'node:fs';
 import { tmpdir } from 'node:os';
 import { join } from 'node:path';
 import registerCanvasStophook from '../canvas-stophook.js';
 import { createNode } from '../../core/canvas/canvas.js';
 import { closeDb } from '../../core/canvas/db.js';
+import { apiSocketPath } from '../../core/canvas/paths.js';
+import { createApiServer } from '../../daemon/api/server.js';
 let home;
 let origNode;
+let server;
+async function waitForSocket(path) {
+    for (let i = 0; i < 200; i++) {
+        if (existsSync(path))
+            return;
+        await new Promise((resolve) => setTimeout(resolve, 10));
+    }
+    throw new Error(`api socket never bound at ${path}`);
+}
 function node(id) {
     return {
         node_id: id,
@@ -45,7 +56,7 @@ function makeFakePi() {
         sendMessage(m, options) {
             this.held.push({ customType: m.customType, content: m.content, deliverAs: options?.deliverAs, triggerTurn: options?.triggerTurn });
         },
-        fire(e, ev, ctx) { handlers[e]?.(ev, ctx); },
+        async fire(e, ev, ctx) { await handlers[e]?.(ev, ctx); },
     };
 }
 /** A turn_end event whose assistant message crossed a steering band. A
@@ -56,12 +67,18 @@ function turnEnd(content, stopReason = 'stop') {
 }
 const ctxAt = (tokens) => ({ getContextUsage: () => ({ tokens }) });
 before(() => { origNode = process.env['CRTR_NODE_ID']; });
-beforeEach(() => {
+beforeEach(async () => {
     closeDb();
     if (home)
         rmSync(home, { recursive: true, force: true });
     home = mkdtempSync(join(tmpdir(), 'crtr-stophook-nudge-'));
     process.env['CRTR_HOME'] = home;
+    mkdirSync(home, { recursive: true });
+    server = createApiServer();
+    await waitForSocket(apiSocketPath());
+});
+afterEach(async () => {
+    await server.close();
 });
 after(() => {
     closeDb();
@@ -73,23 +90,23 @@ after(() => {
     else
         process.env['CRTR_NODE_ID'] = origNode;
 });
-test('band crossing mid-run (tool calls present) → context nudge is a STEER', () => {
+test('band crossing mid-run (tool calls present) → context nudge is a STEER', async () => {
     createNode(node('midrun'));
     process.env['CRTR_NODE_ID'] = 'midrun';
     const pi = makeFakePi();
     registerCanvasStophook(pi);
-    pi.fire('turn_end', turnEnd([{ type: 'toolCall', id: 't1', name: 'bash', arguments: {} }], 'toolUse'), ctxAt(150_000));
+    await pi.fire('turn_end', turnEnd([{ type: 'toolCall', id: 't1', name: 'bash', arguments: {} }], 'toolUse'), ctxAt(150_000));
     assert.equal(pi.steered.length, 1, 'exactly one steer delivered');
     assert.equal(pi.steered[0].deliverAs, 'steer');
     assert.match(pi.steered[0].content, /^\[crtr\] Context ~150k/);
     assert.equal(pi.held.length, 0, 'nothing held for nextTurn');
 });
-test('band crossing on the FINAL message (no tool calls) → nudge is HELD as nextTurn, never a steer', () => {
+test('band crossing on the FINAL message (no tool calls) → nudge is HELD as nextTurn, never a steer', async () => {
     createNode(node('final'));
     process.env['CRTR_NODE_ID'] = 'final';
     const pi = makeFakePi();
     registerCanvasStophook(pi);
-    pi.fire('turn_end', turnEnd([{ type: 'text', text: 'here is my summary' }]), ctxAt(150_000));
+    await pi.fire('turn_end', turnEnd([{ type: 'text', text: 'here is my summary' }]), ctxAt(150_000));
     assert.equal(pi.steered.length, 0, 'no steer — a steer here would extend the run past the closing reply');
     assert.equal(pi.held.length, 1, 'nudge held for the next user message');
     assert.equal(pi.held[0].deliverAs, 'nextTurn');
@@ -97,24 +114,24 @@ test('band crossing on the FINAL message (no tool calls) → nudge is HELD as ne
     assert.match(pi.held[0].content, /^\[crtr\] Context ~150k/);
     assert.notEqual(pi.held[0].triggerTurn, true, 'must not trigger a turn');
 });
-test('a truncated tool-calling turn (stopReason length) still steers — the loop continues past failed calls', () => {
+test('a truncated tool-calling turn (stopReason length) still steers — the loop continues past failed calls', async () => {
     createNode(node('lengthrun'));
     process.env['CRTR_NODE_ID'] = 'lengthrun';
     const pi = makeFakePi();
     registerCanvasStophook(pi);
-    pi.fire('turn_end', turnEnd([{ type: 'toolCall', id: 't1', name: 'bash', arguments: {} }], 'length'), ctxAt(150_000));
+    await pi.fire('turn_end', turnEnd([{ type: 'toolCall', id: 't1', name: 'bash', arguments: {} }], 'length'), ctxAt(150_000));
     assert.equal(pi.steered.length, 1);
     assert.equal(pi.steered[0].deliverAs, 'steer');
     assert.equal(pi.held.length, 0);
 });
-test('an aborted final turn also holds (the loop ends unconditionally on abort)', () => {
+test('an aborted final turn also holds (the loop ends unconditionally on abort)', async () => {
     createNode(node('aborted'));
     process.env['CRTR_NODE_ID'] = 'aborted';
     const pi = makeFakePi();
     registerCanvasStophook(pi);
     // Aborted mid-tool-call: toolCall content present, but the run ends anyway —
     // a steer would sit queued and leak into the NEXT run's start instead.
-    pi.fire('turn_end', turnEnd([{ type: 'toolCall', id: 't1', name: 'bash', arguments: {} }], 'aborted'), ctxAt(150_000));
+    await pi.fire('turn_end', turnEnd([{ type: 'toolCall', id: 't1', name: 'bash', arguments: {} }], 'aborted'), ctxAt(150_000));
     assert.equal(pi.steered.length, 0);
     assert.equal(pi.held.length, 1);
     assert.equal(pi.held[0].deliverAs, 'nextTurn');

package/dist/pi-extensions/broker-local.d.ts

@@ -0,0 +1,20 @@
+import { REVIVE_KICKOFF_SENTINEL } from '../shared/generated-context.js';
+export { REVIVE_KICKOFF_SENTINEL };
+/** Persist a bare root's first real interactive message without clobbering an
+ * existing spawning mandate. This is broker-local file state, not canvas.db. */
+export declare function captureGoalIfAbsent(nodeId: string, text: string): boolean;
+/** Read the node-owned roadmap without importing the canvas state store. */
+export declare function readRoadmap(nodeId: string): string | null;
+/** Generate and commit the first name for a node. The initial operation is
+ * guarded by crtrd, so a concurrent rename or another broker cannot be
+ * overwritten after this projection becomes stale. */
+export declare function generateAndCommitInitialName(nodeId: string, prompt: string, onNamed?: (editorLabel: string) => void): void;
+/** Generate and commit a recap-driven name against the exact node projection
+ * captured before the one-shot model call. The daemon owns the compare-and-set
+ * so a human rename or another generated update wins without a fallback write. */
+export declare function generateAndCommitRecapName(nodeId: string, conversation: string, expected: {
+    name: string;
+    description: string;
+    icon: string;
+    kind: string;
+}, isStillAutomatic: () => boolean, onNamed?: (editorLabel: string) => void): void;

package/dist/pi-extensions/broker-local.js

@@ -0,0 +1,89 @@
+// Broker-local filesystem and naming helpers.
+//
+// These helpers are intentionally independent of the canvas state store. A
+// broker may read its own context files directly, but all node metadata reads
+// and generated-name writes go through crtrd's broker operation projection.
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { CRTR_DIR_NAME } from '../types.js';
+import { REVIVE_KICKOFF_SENTINEL } from '../shared/generated-context.js';
+import { brokerExtensionState, commitBrokerGeneratedName, } from '../core/runtime/broker/daemon-ops.js';
+import { headlessName, headlessNameFromConversation, sanitizeSessionName, slugFromPrompt, } from '../core/runtime/naming.js';
+export { REVIVE_KICKOFF_SENTINEL };
+function contextDir(nodeId) {
+    if (nodeId === '' || nodeId === '.' || nodeId === '..' || /[\\/\0]/u.test(nodeId)) {
+        throw new TypeError('node_id must be a non-empty path segment');
+    }
+    const canvasHome = process.env['CRTR_HOME']?.trim() || join(homedir(), CRTR_DIR_NAME, 'canvas');
+    return join(canvasHome, 'nodes', nodeId, 'context');
+}
+/** Persist a bare root's first real interactive message without clobbering an
+ * existing spawning mandate. This is broker-local file state, not canvas.db. */
+export function captureGoalIfAbsent(nodeId, text) {
+    const dir = contextDir(nodeId);
+    const path = join(dir, 'initial-prompt.md');
+    if (existsSync(path) && readFileSync(path, 'utf8').trim() !== '')
+        return false;
+    const body = text.trim();
+    if (body === '')
+        return false;
+    mkdirSync(dir, { recursive: true });
+    writeFileSync(path, `${body}\n`, 'utf8');
+    return true;
+}
+/** Read the node-owned roadmap without importing the canvas state store. */
+export function readRoadmap(nodeId) {
+    const path = join(contextDir(nodeId), 'roadmap.md');
+    return existsSync(path) ? readFileSync(path, 'utf8') : null;
+}
+function generatedDescription(source, generated) {
+    return sanitizeSessionName(generated.name) || slugFromPrompt(source);
+}
+/** Generate and commit the first name for a node. The initial operation is
+ * guarded by crtrd, so a concurrent rename or another broker cannot be
+ * overwritten after this projection becomes stale. */
+export function generateAndCommitInitialName(nodeId, prompt, onNamed) {
+    const body = prompt.trim();
+    if (body === '')
+        return;
+    void brokerExtensionState(nodeId)
+        .then((state) => {
+        if ((state.node.description ?? '').trim() !== '')
+            return undefined;
+        return headlessName(body).then((generated) => commitBrokerGeneratedName(nodeId, {
+            kind: 'initial',
+            description: generatedDescription(body, generated),
+            icon: generated.icon,
+        }));
+    })
+        .then((result) => {
+        if (result?.applied && result.editorLabel !== undefined)
+            onNamed?.(result.editorLabel);
+    })
+        .catch(() => { });
+}
+/** Generate and commit a recap-driven name against the exact node projection
+ * captured before the one-shot model call. The daemon owns the compare-and-set
+ * so a human rename or another generated update wins without a fallback write. */
+export function generateAndCommitRecapName(nodeId, conversation, expected, isStillAutomatic, onNamed) {
+    const body = conversation.trim();
+    if (body === '')
+        return;
+    void headlessNameFromConversation(body)
+        .then((generated) => {
+        if (!isStillAutomatic())
+            return undefined;
+        return commitBrokerGeneratedName(nodeId, {
+            kind: 'recap',
+            description: generatedDescription(body, generated),
+            icon: generated.icon,
+            expected,
+        });
+    })
+        .then((result) => {
+        if (result?.applied && result.editorLabel !== undefined)
+            onNamed?.(result.editorLabel);
+    })
+        .catch(() => { });
+}

package/dist/pi-extensions/canvas-context-intro.d.ts

@@ -1,4 +1,4 @@
-import { CONTEXT_INTRO_CUSTOM_TYPE } from '../core/runtime/bearings.js';
+import { CONTEXT_INTRO_CUSTOM_TYPE } from '../shared/generated-context.js';
 /** The `customType` stamped on the injected session message. Used both to write
  *  the entry and to detect it on resume (the idempotency guard). Defined beside
  *  the block builder in `core/runtime/bearings.ts` because the warm-pool claim's
@@ -68,10 +68,10 @@ interface PiLike {
 }
 /** Build the full bearings baseline for a conversation without inherited
  *  crouter context. Exported for testing. */
-export declare function buildContextIntro(nodeId: string): string;
+export declare function buildContextIntro(nodeId: string): Promise<string>;
 /** Build the compact node-scoped update for a fork whose copied branch already
  *  carries a full crouter baseline. Exported for testing. */
-export declare function buildForkContextIntro(nodeId: string): string;
+export declare function buildForkContextIntro(nodeId: string): Promise<string>;
 /**
  * Renderer for `crtr-context` messages. Collapsed (default) shows a one-line
  * stub; expanded (Ctrl+O) shows the label + full body. Returns a plain object

package/dist/pi-extensions/canvas-context-intro.js

@@ -26,8 +26,10 @@
 //
 // Plain TS-with-types — no imports from @earendil-works/* so this compiles inside
 // crouter's own tsc build without a dep on the pi packages.
-import { buildContextBearings, buildForkBearings, CONTEXT_INTRO_CUSTOM_TYPE } from '../core/runtime/bearings.js';
-import { getNode, isWarmSpare } from '../core/canvas/index.js';
+import { CONTEXT_INTRO_CUSTOM_TYPE } from '../shared/generated-context.js';
+import { brokerExtensionState } from '../core/runtime/broker/daemon-ops.js';
+import { buildContextBearingsFromState, buildForkBearingsFromState, buildProjectContextBlockForBroker } from '../core/runtime/broker-extension-render.js';
+import { situationalContextBlock } from '../core/runtime/situational-context.js';
 /** The `customType` stamped on the injected session message. Used both to write
  *  the entry and to detect it on resume (the idempotency guard). Defined beside
  *  the block builder in `core/runtime/bearings.ts` because the warm-pool claim's
@@ -38,13 +40,15 @@ export { CONTEXT_INTRO_CUSTOM_TYPE };
 // ---------------------------------------------------------------------------
 /** Build the full bearings baseline for a conversation without inherited
  *  crouter context. Exported for testing. */
-export function buildContextIntro(nodeId) {
-    return buildContextBearings(nodeId);
+export async function buildContextIntro(nodeId) {
+    const state = await brokerExtensionState(nodeId);
+    return buildContextBearingsFromState(state, buildProjectContextBlockForBroker(state.node.cwd), situationalContextBlock(nodeId));
 }
 /** Build the compact node-scoped update for a fork whose copied branch already
  *  carries a full crouter baseline. Exported for testing. */
-export function buildForkContextIntro(nodeId) {
-    return buildForkBearings(nodeId);
+export async function buildForkContextIntro(nodeId) {
+    const state = await brokerExtensionState(nodeId);
+    return buildForkBearingsFromState(state, situationalContextBlock(nodeId));
 }
 // ---------------------------------------------------------------------------
 // Collapsed-by-default rendering
@@ -141,13 +145,20 @@ export function registerCanvasContextIntro(pi) {
     // Collapse the block to a one-liner until the user expands tool output (Ctrl+O).
     // Harmless to register outside TUI mode (it's only consulted while rendering).
     pi.registerMessageRenderer(CONTEXT_INTRO_CUSTOM_TYPE, renderContextMessage);
-    pi.on('session_start', (_event, ctx) => {
+    pi.on('session_start', async (_event, ctx) => {
         const nodeId = process.env['CRTR_NODE_ID'];
         if (nodeId === undefined || nodeId.trim() === '')
             return;
         // Warm spares have no claimant yet. Their claim path delivers the full
         // baseline after assigning the real persona, profile, and working directory.
-        if (isWarmSpare(nodeId))
+        let state;
+        try {
+            state = await brokerExtensionState(nodeId);
+        }
+        catch {
+            return;
+        }
+        if (state.warm_spare)
             return;
         // The active branch, rather than the whole session file, is the context the
         // next turn sees. A new cycle therefore receives its own current baseline.
@@ -161,10 +172,10 @@ export function registerCanvasContextIntro(pi) {
         // A copied crouter branch already carries the shared baseline. Append only
         // this fork's new node-scoped facts. A non-crouter branch has no such entry.
         const inherited = contextEntries.length > 0;
-        const forked = getNode(nodeId)?.fork_from != null;
+        const forked = state.node.fork_from !== null;
         const content = inherited && forked
-            ? buildForkContextIntro(nodeId)
-            : buildContextIntro(nodeId);
+            ? buildForkBearingsFromState(state, situationalContextBlock(nodeId))
+            : buildContextBearingsFromState(state, buildProjectContextBlockForBroker(state.node.cwd), situationalContextBlock(nodeId));
         pi.sendMessage({
             customType: CONTEXT_INTRO_CUSTOM_TYPE,
             content,

package/dist/pi-extensions/canvas-doc-substrate.js

@@ -32,9 +32,12 @@
 // with no dep on the pi packages. Mirrors canvas-context-intro.ts.
 import { homedir } from 'node:os';
 import { join, resolve } from 'node:path';
-import { renderOnReadDocs, renderPreferencesSection, } from '../core/substrate/index.js';
+import { brokerExtensionState } from '../core/runtime/broker/daemon-ops.js';
+import { renderPreferencesFromState } from '../core/runtime/broker-extension-render.js';
+import { renderOnReadDocsForSubject } from '../core/substrate/on-read-pure.js';
 import { clearSessionCache } from '../core/substrate/session-cache.js';
 import { loadInjectedDocs, saveInjectedDocs } from '../core/substrate/injected-store.js';
+import { autoLoadedContextInner, mergeAutoLoadedContext } from './envelope-merge.js';
 // ---------------------------------------------------------------------------
 // Extension
 // ---------------------------------------------------------------------------
@@ -43,31 +46,6 @@ import { loadInjectedDocs, saveInjectedDocs } from '../core/substrate/injected-s
  *  to reach for while reading the tools, so memory docs/preferences must sit
  *  there, not far below. Falls back to appending if absent. */
 const TOOLS_ANCHOR = '\n\nGuidelines:';
-const AUTO_CONTEXT_RE = /<auto-loaded-context(?:\s[^>]*)?>\n([\s\S]*?)\n<\/auto-loaded-context>/;
-function mergeAutoLoadedContext(injected, content) {
-    const match = injected.match(AUTO_CONTEXT_RE);
-    const inner = match?.[1]?.trim();
-    if (!inner)
-        return content;
-    const existingText = content.map((block) => block.text ?? '').join('\n');
-    if (existingText.includes(inner))
-        return content;
-    const existingIdx = content.findIndex((block) => typeof block.text === 'string' && AUTO_CONTEXT_RE.test(block.text));
-    if (existingIdx !== -1) {
-        return content.map((block, idx) => {
-            if (idx !== existingIdx || typeof block.text !== 'string')
-                return block;
-            return {
-                ...block,
-                text: block.text.replace(AUTO_CONTEXT_RE, (_whole, current) => {
-                    const trimmed = String(current).trim();
-                    return `<auto-loaded-context>\n${inner}${trimmed === '' ? '' : `\n${trimmed}`}\n</auto-loaded-context>`;
-                }),
-            };
-        });
-    }
-    return [{ type: 'text', text: `<auto-loaded-context>\n${inner}\n</auto-loaded-context>` }, ...content];
-}
 /**
  * Register the document substrate's pi hooks on `pi`.
  *
@@ -100,9 +78,10 @@ export function registerCanvasDocSubstrate(pi) {
     //    is never empty even when no preference is eligible. (The knowledge catalog
     //    no longer enters the system prompt — it rides the bearings message via
     //    renderKnowledgeBlock.)
-    pi.on('before_agent_start', (event) => {
+    pi.on('before_agent_start', async (event) => {
         try {
-            const block = renderPreferencesSection(nodeId);
+            const state = await brokerExtensionState(nodeId);
+            const block = renderPreferencesFromState(state);
             if (block === '')
                 return; // nothing eligible — leave the prompt untouched
             const idx = event.systemPrompt.indexOf(TOOLS_ANCHOR);
@@ -118,7 +97,7 @@ export function registerCanvasDocSubstrate(pi) {
         }
     });
     // 2. ON-READ half — augment a non-error `read` result with surfacing docs.
-    pi.on('tool_result', (event, ctx) => {
+    pi.on('tool_result', async (event, ctx) => {
         try {
             if (event.toolName !== 'read' || event.isError === true)
                 return;
@@ -126,13 +105,14 @@ export function registerCanvasDocSubstrate(pi) {
             const rawPath = input?.path ?? input?.file_path;
             if (rawPath === undefined || rawPath === '')
                 return;
-            // Resolve to an absolute path (renderOnReadDocs realpaths it). pi's read
-            // tool expands a leading `~`, but event.input keeps the raw form, so
-            // expand it ourselves before resolving against the session cwd.
+            // Resolve to an absolute path (renderOnReadDocsForSubject realpaths it).
+            // pi's read tool expands a leading `~`, but event.input keeps the raw
+            // form, so expand it ourselves before resolving against the session cwd.
             const cwd = typeof ctx?.cwd === 'string' && ctx.cwd !== '' ? ctx.cwd : process.cwd();
             const expanded = rawPath.startsWith('~') ? join(homedir(), rawPath.slice(1)) : rawPath;
             const absFile = resolve(cwd, expanded);
-            const injected = renderOnReadDocs(nodeId, absFile, injectedDocs);
+            const state = await brokerExtensionState(nodeId);
+            const injected = renderOnReadDocsForSubject(state.subject, absFile, injectedDocs);
             if (injected === '')
                 return; // nothing surfaced — pass the read through unchanged
             // A doc surfaced → renderOnReadDocs grew injectedDocs; persist the set so
@@ -140,7 +120,10 @@ export function registerCanvasDocSubstrate(pi) {
             saveInjectedDocs(nodeId, injectedDocs);
             // Fold into any existing auto-loaded-context block from sibling read hooks;
             // otherwise prepend one quiet block ahead of the file contents.
-            return { content: mergeAutoLoadedContext(injected, event.content) };
+            const inner = autoLoadedContextInner(injected);
+            if (inner === null)
+                return;
+            return { content: mergeAutoLoadedContext([inner], event.content) };
         }
         catch {
             return; // inert on error — a bug must degrade a read, never break it

package/dist/pi-extensions/canvas-goal-capture.js

@@ -28,9 +28,7 @@
 //
 // Plain TS-with-types — no imports from @earendil-works/* so this compiles inside
 // crouter's own tsc build without a dep on the pi packages.
-import { captureGoalIfAbsent, REVIVE_KICKOFF_SENTINEL } from '../core/runtime/kickoff.js';
-import { generateAndPersistName } from '../core/runtime/naming-persist.js';
-import { editorLabel, getNode } from '../core/canvas/index.js';
+import { captureGoalIfAbsent, generateAndCommitInitialName, REVIVE_KICKOFF_SENTINEL, } from './broker-local.js';
 /**
  * Register the goal-capture handler on `pi`.
  *
@@ -65,15 +63,12 @@ export function registerCanvasGoalCapture(pi) {
             // canvas extensions, so it never recurses into another spawn/name. The
             // onNamed callback live-updates THIS session's label instead of waiting
             // for the next cycle. The unnamed-guard keeps it to one call per node.
-            const meta = getNode(nodeId);
-            if (meta !== null && (meta.description ?? '').trim() === '') {
-                generateAndPersistName(nodeId, text, (named) => {
-                    try {
-                        pi.setSessionName?.(editorLabel(named));
-                    }
-                    catch { /* best-effort */ }
-                });
-            }
+            generateAndCommitInitialName(nodeId, text, (label) => {
+                try {
+                    pi.setSessionName?.(label);
+                }
+                catch { /* best-effort */ }
+            });
         }
         catch {
             // Best-effort: a capture failure must never drop or alter the message.