@north-light/crouter 0.3.162 → 0.3.164

package/dist/pi-extensions/__tests__/canvas-tool-guide.test.js

@@ -0,0 +1,96 @@
+// Run with: node --import tsx/esm --test src/pi-extensions/__tests__/canvas-tool-guide.test.ts
+//
+// Regression: canvas brokers must load and inject the root crtr guide themselves;
+// optional pi packages are not part of the canvas runtime contract.
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { chmodSync, mkdirSync, mkdtempSync, readFileSync, realpathSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { delimiter, join } from 'node:path';
+import { CANVAS_EXTENSIONS, CANVAS_TOOL_GUIDE_PATH } from '../../core/runtime/canvas-extensions.js';
+import registerCanvasToolGuide from '../canvas-tool-guide.js';
+function fakePi() {
+    return {
+        on(event, handler) {
+            if (event === 'before_agent_start')
+                this.beforeAgentStart = handler;
+            if (event === 'session_start')
+                this.sessionStart = handler;
+        },
+    };
+}
+test('canvas nodes load the cwd-specific root guide, share its boot cache, and never capture during a turn', async () => {
+    assert.ok(CANVAS_EXTENSIONS.includes(CANVAS_TOOL_GUIDE_PATH), 'the guide is a mandatory canvas extension');
+    const root = mkdtempSync(join(tmpdir(), 'crtr-tool-guide-'));
+    const bin = join(root, 'bin');
+    const cwd = join(root, 'configured-project');
+    const countFile = join(root, 'capture-count');
+    const capturedCwdFile = join(root, 'capture-cwd');
+    const previous = {
+        cwd: process.cwd(),
+        home: process.env['HOME'],
+        nodeId: process.env['CRTR_NODE_ID'],
+        path: process.env['PATH'],
+    };
+    try {
+        mkdirSync(bin);
+        mkdirSync(cwd);
+        const command = join(bin, 'crtr');
+        writeFileSync(command, `#!/bin/sh
+count=0
+if [ -f "$CAPTURE_COUNT" ]; then count=$(cat "$CAPTURE_COUNT"); fi
+printf '%s' "$((count + 1))" > "$CAPTURE_COUNT"
+printf '%s' "$PWD" > "$CAPTURE_CWD"
+printf '%s\\n' 'configured root guide'
+`);
+        chmodSync(command, 0o755);
+        process.chdir(cwd);
+        process.env['HOME'] = root;
+        process.env['CRTR_NODE_ID'] = 'canvas-tool-guide-test';
+        process.env['PATH'] = `${bin}${delimiter}${previous.path ?? ''}`;
+        process.env['CAPTURE_COUNT'] = countFile;
+        process.env['CAPTURE_CWD'] = capturedCwdFile;
+        const first = fakePi();
+        registerCanvasToolGuide(first);
+        const firstSessionStart = first.sessionStart;
+        assert.ok(firstSessionStart, 'session-start capture is registered');
+        await firstSessionStart();
+        const second = fakePi();
+        registerCanvasToolGuide(second);
+        const secondSessionStart = second.sessionStart;
+        assert.ok(secondSessionStart, 'session-start capture is registered for every broker');
+        await secondSessionStart();
+        assert.equal(readFileSync(countFile, 'utf8'), '1', 'a sibling broker uses the 15-second disk cache');
+        assert.equal(readFileSync(capturedCwdFile, 'utf8'), realpathSync(cwd), 'root help discovers commands from the node cwd');
+        const beforeAgentStart = second.beforeAgentStart;
+        assert.ok(beforeAgentStart, 'turn-time guide injection is registered');
+        const prompt = 'Available tools\n\nGuidelines:\nUse the available tools.';
+        assert.equal(beforeAgentStart({ systemPrompt: prompt })?.systemPrompt, 'Available tools\n\n<crtr-tool-guide>\nconfigured root guide\n</crtr-tool-guide>\n\nGuidelines:\nUse the available tools.', 'the captured guide sits in the tool-selection frame');
+        rmSync(join(root, '.crouter'), { recursive: true, force: true });
+        const unbooted = fakePi();
+        registerCanvasToolGuide(unbooted);
+        const unbootedBeforeAgentStart = unbooted.beforeAgentStart;
+        assert.ok(unbootedBeforeAgentStart, 'turn-time guide injection is registered before boot capture');
+        assert.equal(unbootedBeforeAgentStart({ systemPrompt: prompt }), undefined, 'a node without a boot capture starts without a guide');
+        await new Promise((resolve) => setTimeout(resolve, 50));
+        assert.equal(readFileSync(countFile, 'utf8'), '1', 'a turn never starts a root-help subprocess');
+    }
+    finally {
+        process.chdir(previous.cwd);
+        if (previous.home === undefined)
+            delete process.env['HOME'];
+        else
+            process.env['HOME'] = previous.home;
+        if (previous.nodeId === undefined)
+            delete process.env['CRTR_NODE_ID'];
+        else
+            process.env['CRTR_NODE_ID'] = previous.nodeId;
+        if (previous.path === undefined)
+            delete process.env['PATH'];
+        else
+            process.env['PATH'] = previous.path;
+        delete process.env['CAPTURE_COUNT'];
+        delete process.env['CAPTURE_CWD'];
+        rmSync(root, { recursive: true, force: true });
+    }
+});

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

@@ -12,16 +12,15 @@
 //      into `event.systemPrompt`, right after pi's native "Available tools" list
 //      (before the `\n\nGuidelines:` anchor), so the substrate's standing
 //      directives sit in the tool-selection frame the agent reads while choosing
-//      a capability — mirroring the personal crouter-help.ts anchor logic. Falls
-//      back to appending when the anchor is absent. (The `<memory kind="knowledge">`
+//      a capability. Falls back to appending when the anchor is absent. (The `<memory kind="knowledge">`
 //      catalog rides the bearings message instead — see core/substrate/render.ts.)
 //
 //   2. tool_result (gated on `read`) — the ON-READ half. For each non-error
-//      `read`, surfaces the substrate docs that should appear alongside the file
-//      (positional `.crouter/memory/` ancestors + `applies-to` globs) at their
-//      file-read-visibility rung, prepended as a `<auto-loaded-context>` block
-//      before the file contents. A per-session realpath set dedups so the same
-//      doc is not re-injected on repeat reads.
+//      `read`, evaluates explicit `applies-to` globs (plus `read-when` metadata)
+//      across the resolved corpus and any project stores enclosing the read
+//      file. Matches render at their file-read rung in `<auto-loaded-context>`
+//      before the file contents. A transcript-scoped realpath set deduplicates
+//      repeated reads and resumed broker processes.
 //
 // Both handler bodies are wrapped in try/catch and degrade to INERT on error —
 // a substrate bug must never brick node boot or break a `read`, only quietly
@@ -42,7 +41,7 @@ import { loadInjectedDocs, saveInjectedDocs } from '../core/substrate/injected-s
 /** The stable seam that closes pi's native "Available tools" list. We splice the
  *  substrate's boot sections right before it — the agent decides which capability
  *  to reach for while reading the tools, so memory docs/preferences must sit
- *  there, not far below. Mirrors crouter-help.ts. Falls back to appending if absent. */
+ *  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) {

package/dist/pi-extensions/canvas-tool-guide.d.ts

@@ -0,0 +1,14 @@
+declare function injectToolGuide(systemPrompt: string, helpText: string): string;
+interface BeforeAgentStartEventLike {
+    systemPrompt: string;
+}
+interface PiLike {
+    on(event: 'session_start', handler: () => void | Promise<void>): void;
+    on(event: 'before_agent_start', handler: (event: BeforeAgentStartEventLike) => {
+        systemPrompt: string;
+    } | void): void;
+}
+/** Register the root crtr tool-guide injection for a canvas node. */
+export declare function registerCanvasToolGuide(pi: PiLike): void;
+export { injectToolGuide };
+export default registerCanvasToolGuide;

package/dist/pi-extensions/canvas-tool-guide.js

@@ -0,0 +1,77 @@
+// canvas-tool-guide.ts — injects the root crtr CLI guide into every canvas node.
+//
+// Capturing `crtr -h` builds the full configured command tree, including commands
+// discovered from the node's cwd. It runs only at session start; before_agent_start
+// injects the last successful capture without starting work or waiting.
+import { execFile } from 'node:child_process';
+import { createHash } from 'node:crypto';
+import { mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { dirname, join } from 'node:path';
+import { promisify } from 'node:util';
+const run = promisify(execFile);
+const TTL_MS = 15_000;
+const TOOLS_ANCHOR = '\n\nGuidelines:';
+function helpCacheFile(cwd) {
+    const hash = createHash('sha1').update(cwd).digest('hex').slice(0, 16);
+    return join(homedir(), '.crouter', 'cache', `crtr-tool-guide-${hash}.json`);
+}
+function injectToolGuide(systemPrompt, helpText) {
+    const block = `<crtr-tool-guide>\n${helpText}\n</crtr-tool-guide>`;
+    const anchor = systemPrompt.indexOf(TOOLS_ANCHOR);
+    if (anchor === -1)
+        return `${systemPrompt}\n\n${block}`;
+    return `${systemPrompt.slice(0, anchor)}\n\n${block}${systemPrompt.slice(anchor)}`;
+}
+/** Register the root crtr tool-guide injection for a canvas node. */
+export function registerCanvasToolGuide(pi) {
+    const nodeId = process.env['CRTR_NODE_ID'];
+    if (nodeId === undefined || nodeId.trim() === '')
+        return;
+    let helpText = '';
+    let capturedAt = 0;
+    async function refresh() {
+        if (helpText !== '' && Date.now() - capturedAt < TTL_MS)
+            return;
+        const file = helpCacheFile(process.cwd());
+        try {
+            const cached = JSON.parse(readFileSync(file, 'utf8'));
+            if (typeof cached.text === 'string' && cached.text !== '' && typeof cached.at === 'number' && Date.now() - cached.at < TTL_MS) {
+                helpText = cached.text;
+                capturedAt = cached.at;
+                return;
+            }
+        }
+        catch {
+            // A missing or invalid cache is refreshed below.
+        }
+        try {
+            const { stdout } = await run('crtr', ['-h'], { timeout: 10_000 });
+            helpText = stdout.trim();
+            capturedAt = Date.now();
+            try {
+                mkdirSync(dirname(file), { recursive: true });
+                writeFileSync(file, JSON.stringify({ text: helpText, at: capturedAt }), 'utf8');
+            }
+            catch {
+                // The guide remains available in this broker even when its cache cannot persist.
+            }
+        }
+        catch (err) {
+            // Keep the last successful guide and never delay a turn for a failed capture.
+            // Say so once in the broker log: a node silently missing its whole tool guide
+            // is otherwise indistinguishable from one that has it.
+            console.error('[canvas-tool-guide] crtr -h capture failed:', err);
+        }
+    }
+    // Node startup is the only point a capture may wait. Warm spares pay it before
+    // a user claims them; resumed nodes refresh before their next turn.
+    pi.on('session_start', refresh);
+    pi.on('before_agent_start', (event) => {
+        if (helpText === '')
+            return;
+        return { systemPrompt: injectToolGuide(event.systemPrompt, helpText) };
+    });
+}
+export { injectToolGuide };
+export default registerCanvasToolGuide;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@north-light/crouter",
-  "version": "0.3.162",
+  "version": "0.3.164",
   "description": "crtr — agent runtime with memory, plugins, and marketplaces",
   "type": "module",
   "main": "dist/index.js",
@@ -107,7 +107,7 @@
   },
   "license": "MIT",
   "dependencies": {
-    "@crouton-kit/humanloop": "0.4.20",
+    "@crouton-kit/humanloop": "0.4.21",
     "@earendil-works/pi-agent-core": "0.83.0",
     "@earendil-works/pi-ai": "0.83.0",
     "@earendil-works/pi-coding-agent": "0.83.0",

package/runtime.lock.json

@@ -1,16 +1,16 @@
 {
   "name": "@north-light/crouter",
-  "version": "0.3.162",
+  "version": "0.3.164",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "@north-light/crouter",
-      "version": "0.3.162",
+      "version": "0.3.164",
       "hasInstallScript": true,
       "license": "MIT",
       "dependencies": {
-        "@crouton-kit/humanloop": "0.4.20",
+        "@crouton-kit/humanloop": "0.4.21",
         "@earendil-works/pi-agent-core": "0.83.0",
         "@earendil-works/pi-ai": "0.83.0",
         "@earendil-works/pi-coding-agent": "0.83.0",
@@ -2073,9 +2073,9 @@
       }
     },
     "node_modules/@crouton-kit/humanloop": {
-      "version": "0.4.20",
-      "resolved": "https://registry.npmjs.org/@crouton-kit/humanloop/-/humanloop-0.4.20.tgz",
-      "integrity": "sha512-4MBEVzQegNQQVCUktgsCyk4civYvhpCYJfY6nPTuOjNMpz+prT0sXfjNntcZS14cG0Hj/Igzzc010VpgVnN5WQ==",
+      "version": "0.4.21",
+      "resolved": "https://registry.npmjs.org/@crouton-kit/humanloop/-/humanloop-0.4.21.tgz",
+      "integrity": "sha512-j/8dVAhl2R4dWvykSjC+yCEEb/n7P+P1FZLEFWD1pVB24tubYVmA3vJSr359nOO8esmJ+h/+S8Oef8eGZ6n6tA==",
       "hasInstallScript": true,
       "workspaces": [
         "web"

package/dist/builtin-pi-packages/pi-crtr-extensions/extensions/crouter-help.ts

@@ -1,95 +0,0 @@
-import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
-import { execFile } from "node:child_process";
-import { promisify } from "node:util";
-import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
-import { homedir } from "node:os";
-import { createHash } from "node:crypto";
-import { dirname, join } from "node:path";
-
-const run = promisify(execFile);
-
-// `crtr -h` is the auto-loaded tool guide. Capturing it costs a real subprocess:
-// bare `crtr -h` is the one invocation that must build the FULL command tree, so
-// it loads every subtree's module graph — ~250ms on a laptop, ~320ms in the
-// guest container. The guide's content is static per crouter version + installed
-// plugins, so that cost must never sit in front of a turn. The TTL only exists
-// to pick a tree change (an upgrade, a newly installed plugin) up eventually.
-const TTL_MS = 15_000;
-
-// The TTL cache is also persisted to disk, keyed by cwd (skills resolve by
-// scope, so the guide is cwd-specific). Every broker/node is a FRESH process, so
-// the in-memory cache alone is always cold at session_start — each boot would
-// re-spawn `crtr -h`. The disk layer lets a cluster of node boots within one TTL
-// window (daemon revives, child spawns, rapid relaunches) share a single capture.
-function helpCacheFile(cwd: string): string {
-  const h = createHash("sha1").update(cwd).digest("hex").slice(0, 16);
-  return join(homedir(), ".crouter", "cache", `crouter-help-${h}.json`);
-}
-
-export default function (pi: ExtensionAPI) {
-  let helpText = "";
-  let capturedAt = 0;
-
-  async function refresh(): Promise<void> {
-    if (Date.now() - capturedAt < TTL_MS && helpText) return; // in-memory fresh
-    const file = helpCacheFile(process.cwd());
-
-    // Cross-process disk cache: reuse a recent capture from a sibling boot.
-    try {
-      const c = JSON.parse(readFileSync(file, "utf8")) as { text?: string; at?: number };
-      if (typeof c.text === "string" && c.text && typeof c.at === "number" && Date.now() - c.at < TTL_MS) {
-        helpText = c.text;
-        capturedAt = c.at;
-        return; // fresh on disk — skip the spawn
-      }
-    } catch {
-      // miss / corrupt — fall through to re-probe
-    }
-
-    try {
-      const { stdout } = await run("crouter", ["-h"], { timeout: 10_000 });
-      helpText = stdout.trim();
-      capturedAt = Date.now();
-      try {
-        mkdirSync(dirname(file), { recursive: true });
-        writeFileSync(file, JSON.stringify({ text: helpText, at: capturedAt }), "utf8");
-      } catch {
-        // best-effort: a missing cache just means the next boot re-probes
-      }
-    } catch {
-      // soft-fail: keep last-known text (or empty); never block the turn
-    }
-  }
-
-  // Boot-time capture: the one place a refresh may block, because it happens at
-  // node mint/revive, never in front of a user's turn. A warm-pool spare has
-  // therefore already paid it before it is ever claimed.
-  pi.on("session_start", refresh);
-
-  pi.on("before_agent_start", (event) => {
-    // NEVER await here. A stale-by-TTL capture used to re-spawn `crtr -h`
-    // synchronously, putting its full subprocess cost between the delivered
-    // message and agent_start — measured as the single largest term in a
-    // Northlight first-message ack. Serve the last-known text and let the
-    // refresh land for the next turn instead.
-    if (Date.now() - capturedAt >= TTL_MS) void refresh();
-    if (!helpText) return;
-
-    const block = `<crtr-tool-guide>\n${helpText}\n</crtr-tool-guide>`;
-
-    // Place the guide in the tool-selection frame, right after pi's native
-    // "Available tools" list rather than at the very bottom — the agent decides
-    // which capability to reach for while reading the tools, so the crtr
-    // commands (agent/skill/job) must be present there, not 3k tokens later.
-    // `\n\nGuidelines:` is the stable seam that closes the tools area. Fall back
-    // to appending if pi ever changes that marker.
-    const anchor = "\n\nGuidelines:";
-    const idx = event.systemPrompt.indexOf(anchor);
-    if (idx === -1) {
-      return { systemPrompt: `${event.systemPrompt}\n\n${block}` };
-    }
-    return {
-      systemPrompt: `${event.systemPrompt.slice(0, idx)}\n\n${block}${event.systemPrompt.slice(idx)}`,
-    };
-  });
-}