@north-light/crouter 0.3.231 → 0.3.233

package/dist/pi-extensions/canvas-doc-substrate.d.ts

@@ -29,9 +29,23 @@ interface ToolResultCtxLike {
 type ToolResultResultLike = {
     content: ContentBlockLike[];
 } | void;
+/** tool_call: fired BEFORE the tool runs. Returning `{block: true, reason}`
+ *  stops it — nothing executes, no `tool_result` fires, and `reason` becomes the
+ *  call's synthesized error result, carrying arbitrary-length text. */
+interface ToolCallEventLike {
+    toolName: string;
+    input?: unknown;
+}
+type ToolCallResultLike = {
+    block: true;
+    reason: string;
+} | void;
 interface PiLike {
     on(event: 'before_agent_start', handler: (event: BeforeAgentStartEventLike) => BeforeAgentStartResultLike | void | Promise<BeforeAgentStartResultLike | void>): void;
     on(event: 'session_start', handler: (event: unknown, ctx: unknown) => void | Promise<void>): void;
+    on(event: 'session_compact', handler: (event: unknown, ctx: unknown) => void | Promise<void>): void;
+    on(event: 'turn_end', handler: (event: unknown, ctx: unknown) => void | Promise<void>): void;
+    on(event: 'tool_call', handler: (event: ToolCallEventLike, ctx: unknown) => ToolCallResultLike | Promise<ToolCallResultLike>): void;
     on(event: 'tool_result', handler: (event: ToolResultEventLike, ctx: ToolResultCtxLike) => ToolResultResultLike | Promise<ToolResultResultLike>): void;
 }
 export declare function registerCanvasDocSubstrate(pi: PiLike): void;

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

@@ -7,7 +7,9 @@
 //
 // before_agent_start splices the context's frozen preference snapshot after the
 // native tool list. Successful read/bash results append matching memory through
-// the shared context exposure state. Pure rendering lives in core/substrate/.
+// the shared context exposure state. A bash call matching a `pre-command` doc is
+// BLOCKED before it runs and the doc comes back as its synthesized error result.
+// Pure rendering lives in core/substrate/.
 //
 // Plain TS-with-types — NO imports from @earendil-works/* (a local structural
 // PiLike interface stands in), so it compiles inside crouter's own tsc build
@@ -16,7 +18,7 @@ import { homedir } from 'node:os';
 import { join, resolve } from 'node:path';
 import { brokerExtensionState } from '../core/runtime/broker/daemon-ops.js';
 import { renderPreferencesFromState } from '../core/runtime/broker-extension-render.js';
-import { renderOnCommandDocsForSubject, renderOnReadDocsForSubject } from '../core/substrate/on-read.js';
+import { corpusHasPreCommandSurfaces, demotePreCommandExposures, renderOnCommandDocsForSubject, renderOnReadDocsForSubject, renderPreCommandDocsForSubject, } from '../core/substrate/on-read.js';
 import { clearSessionCache } from '../core/substrate/session-cache.js';
 import { cloneContextExposureState, exposureTarget, freezePreferenceSnapshot, loadContextExposureState, mergeContextExposureState, replaceContextExposureState, saveContextExposureState, sharedContextExposureState, } from '../core/substrate/injected-store.js';
 import { autoLoadedContextInner, mergeAutoLoadedContext } from './envelope-merge.js';
@@ -28,6 +30,38 @@ import { autoLoadedContextInner, mergeAutoLoadedContext } from './envelope-merge
  *  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:';
+/** The bash command string a tool call carries, or `null` when there is none. */
+function bashCommandOf(input) {
+    const command = input?.command;
+    return typeof command === 'string' && command.trim() !== '' ? command : null;
+}
+/** The blocked call's synthesized error result. A blocked command is discarded
+ *  IN FULL — pi executes none of it — so the copy must steer a re-issue of the
+ *  WHOLE command, never of one clause: when the same command also built its own
+ *  input (a heredoc, a `>` redirect, a `$(…)`), that setup did not run either,
+ *  and re-issuing only the tail would act on stale or missing data. */
+function heldReason(rendered) {
+    return [
+        'HELD — nothing ran.',
+        '',
+        'Your bash command was NOT executed. It matched memory you had not yet read, and that memory is below.',
+        '',
+        'Read it, then re-issue your WHOLE command unchanged — every clause of it, including any heredoc, redirect, or `$(…)` that built its input, because none of that ran either. The re-issue executes: this memory is now in your transcript, so there is nothing left to deliver and nothing left to hold.',
+        '',
+        rendered,
+    ].join('\n');
+}
+/** The follow-on notice for a SIBLING command in the same assistant message.
+ *  pi preflights siblings sequentially and then executes them concurrently, so
+ *  without one flag per turn the second sibling would find the doc already
+ *  exposed and slip past the hold its sibling just raised. */
+const HELD_SIBLING_REASON = [
+    'HELD — nothing ran.',
+    '',
+    'Your bash command was NOT executed. Another command in this same message was held against memory you had not read, and that memory was returned with it.',
+    '',
+    'Read it, then re-issue your WHOLE command unchanged. The re-issue executes.',
+].join('\n');
 export function registerCanvasDocSubstrate(pi) {
     const nodeId = process.env['CRTR_NODE_ID'];
     if (nodeId === undefined || nodeId.trim() === '')
@@ -57,6 +91,45 @@ export function registerCanvasDocSubstrate(pi) {
             systemPrompt: `${event.systemPrompt.slice(0, idx)}\n\n${block}${event.systemPrompt.slice(idx)}`,
         };
     });
+    // One flag per assistant turn: the first hold covers every matching command
+    // in the same message.
+    let blockedThisTurn = false;
+    pi.on('turn_end', () => {
+        blockedThisTurn = false;
+    });
+    // Compaction drops delivered guidance out of the transcript while the ledger
+    // still records it as delivered. Forget those deliveries so the holds re-arm.
+    pi.on('session_compact', () => {
+        mergeContextExposureState(contextExposure, loadContextExposureState(nodeId));
+        demotePreCommandExposures(contextExposure);
+        saveContextExposureState(nodeId, contextExposure);
+        blockedThisTurn = false;
+    });
+    pi.on('tool_call', async (event) => {
+        if (event.toolName !== 'bash')
+            return;
+        const command = bashCommandOf(event.input);
+        if (command === null)
+            return;
+        // The common case is a corpus with no pre-command doc at all, and it must
+        // cost nothing — short-circuit before the daemon round-trip below.
+        if (!corpusHasPreCommandSurfaces())
+            return;
+        if (blockedThisTurn)
+            return { block: true, reason: HELD_SIBLING_REASON };
+        const state = await brokerExtensionState(nodeId);
+        mergeContextExposureState(contextExposure, loadContextExposureState(nodeId));
+        const next = cloneContextExposureState(contextExposure);
+        const rendered = renderPreCommandDocsForSubject(state.subject, command, exposureTarget(next, 'transcript'));
+        // Everything this command matches is already in the transcript: the hold is
+        // released and the command runs.
+        if (rendered === '')
+            return;
+        blockedThisTurn = true;
+        saveContextExposureState(nodeId, next);
+        replaceContextExposureState(contextExposure, next);
+        return { block: true, reason: heldReason(rendered) };
+    });
     pi.on('tool_result', async (event, ctx) => {
         if (event.isError === true)
             return;

package/dist/pi-extensions/canvas-prompt-scrub.d.ts

@@ -0,0 +1,13 @@
+/** Strip pi's self-references from an assembled system prompt. */
+export declare function scrubPromptSelfReference(systemPrompt: string): string;
+interface BeforeAgentStartEventLike {
+    systemPrompt: string;
+}
+interface PiLike {
+    on(event: 'before_agent_start', handler: (event: BeforeAgentStartEventLike) => {
+        systemPrompt: string;
+    } | void): void;
+}
+/** Register the system-prompt scrub for a canvas node. */
+export declare function registerCanvasPromptScrub(pi: PiLike): void;
+export default registerCanvasPromptScrub;

package/dist/pi-extensions/canvas-prompt-scrub.js

@@ -0,0 +1,53 @@
+// canvas-prompt-scrub.ts — removes pi's self-referential prompt text before any
+// other consumer reads the system prompt.
+//
+// pi's prompt builder hardcodes two things a canvas node should not carry:
+//
+//  1. An opening sentence naming pi as the harness. A node's identity is the
+//     canvas persona crouter appends, not the engine it happens to run on.
+//  2. A "Pi documentation (read only ...):" block — a marker line plus bullets
+//     pointing at pi's README / docs / examples under node_modules. It maps
+//     topics to doc files, which makes the agent extrapolate a
+//     topic -> docs/<topic>.md pattern and surface pi's internals unprompted.
+//
+// ORDER IS THE POINT. This must be a canvas extension, not a package one:
+// crouter's canvas extensions load ahead of installed pi packages, and the
+// Claude subscription adapter is a package. That adapter also wants the docs
+// block gone (it is a third-party tell that costs a Claude subscription its
+// plan rate), but it removes the block by cutting from the marker to the next
+// boundary marker it knows — and a canvas prompt has none, so the cut runs to
+// the end of the prompt and takes crouter's appended canvas persona with it.
+// Scrubbing here leaves the adapter nothing to find, so the persona survives.
+// The companion guard is CRTR env that disables the adapter's re-injection;
+// without it the adapter rebuilds the block from its own fallback copy.
+//
+// Every rule below is anchored to pi's exact wording and degrades to a no-op if
+// pi rewords, so a pi upgrade can never break a turn here.
+const PI_IDENTITY = 'You are an expert coding assistant operating inside pi, a coding agent harness.';
+const NEUTRAL_IDENTITY = 'You are an expert coding assistant.';
+const PI_DOCS_MARKER = 'Pi documentation (read only';
+// The marker line plus its trailing "- ..." bullets, and any leading blank
+// lines so the surrounding prompt closes up cleanly.
+const PI_DOCS_BLOCK = /\n*^Pi documentation \(read only[^\n]*:(?:\n[ \t]*-[^\n]*)*/m;
+/** Strip pi's self-references from an assembled system prompt. */
+export function scrubPromptSelfReference(systemPrompt) {
+    let prompt = systemPrompt;
+    if (prompt.includes(PI_IDENTITY))
+        prompt = prompt.replace(PI_IDENTITY, NEUTRAL_IDENTITY);
+    if (prompt.includes(PI_DOCS_MARKER))
+        prompt = `${prompt.replace(PI_DOCS_BLOCK, '').trimEnd()}\n`;
+    return prompt;
+}
+/** Register the system-prompt scrub for a canvas node. */
+export function registerCanvasPromptScrub(pi) {
+    const nodeId = process.env['CRTR_NODE_ID'];
+    if (nodeId === undefined || nodeId.trim() === '')
+        return;
+    pi.on('before_agent_start', (event) => {
+        const scrubbed = scrubPromptSelfReference(event.systemPrompt);
+        if (scrubbed === event.systemPrompt)
+            return;
+        return { systemPrompt: scrubbed };
+    });
+}
+export default registerCanvasPromptScrub;

package/dist/shared/generated-context.d.ts

@@ -8,6 +8,13 @@ export declare const CONTEXT_NUDGE_CUSTOM_TYPE = "crtr-context-nudge";
 export declare const REVIEW_BOUNDARY_CUSTOM_TYPE = "crtr-review-boundary";
 /** Generic completion mandate issued by the terminal-node stop guard. */
 export declare const STALL_REPROMPT: string;
+/** The daemon's parking mandate: the last turn of a conversation the unattended
+ *  clock is concluding. Delivered live, wrapped in a `park` runtime card. It
+ *  shares a CONTRACT with `node yield`'s pre-invocation guide (roadmap current,
+ *  short and shrinking; context dir for in-progress material; memory only for
+ *  gated permanent lessons) but not a string: yield is read by an agent choosing
+ *  to refresh, this by an agent being told to conclude. */
+export declare const PARK_SUMMARY_PROMPT: string;
 /** Static recovery prompts shared by the broker producer and display classifier. */
 export declare const AUTH_FAULT_RECOVERY_BODY = "Provider credentials were just updated (a new login landed). Your previous turn stopped on a provider authentication failure. Continue from where you left off and retry the work that failed.";
 export declare const CONNECTION_FAULT_RECOVERY_BODY = "The network connection is back online. Your previous turn stopped on a connection error (the network was down). Continue from where you left off and retry the work that failed.";

package/dist/shared/generated-context.js

@@ -13,6 +13,17 @@ export const REVIEW_BOUNDARY_CUSTOM_TYPE = 'crtr-review-boundary';
 /** Generic completion mandate issued by the terminal-node stop guard. */
 export const STALL_REPROMPT = "You've stopped but you're not waiting on anyone and haven't finished. " +
     "Pipe the result to `crtr push final` through a single-quoted heredoc if the work is done, or use `crtr human send` if you are blocked or need the user.";
+/** The daemon's parking mandate: the last turn of a conversation the unattended
+ *  clock is concluding. Delivered live, wrapped in a `park` runtime card. It
+ *  shares a CONTRACT with `node yield`'s pre-invocation guide (roadmap current,
+ *  short and shrinking; context dir for in-progress material; memory only for
+ *  gated permanent lessons) but not a string: yield is read by an agent choosing
+ *  to refresh, this by an agent being told to conclude. */
+export const PARK_SUMMARY_PROMPT = 'This conversation has been idle with nothing waiting on it, so it is being concluded. This is your last turn — do these four things now, then stop.\n\n'
+    + '1. Bring your roadmap current. It lives at `$CRTR_CONTEXT_DIR/roadmap.md`, and it is the document a fresh cycle reads to know where things stand: what was done, what is still open, and what someone picking this up needs. Write one now if you never had one. Keep it short and shrinking — strategy and present state only, deleting completed items rather than marking them done.\n\n'
+    + '2. Save anything else worth keeping. In-progress task material — what has happened, identifiers, in-flight state — goes to one or more files in your context directory. A permanent lesson worth remembering indefinitely goes to node memory (`crtr memory write -h`), gated deliberately: transcript state does not belong in memory.\n\n'
+    + '3. Push one regular report to your subscribers summarizing where things stand: `crtr push update`. NOT `crtr push final` — this concludes the conversation, it does not finish a mandate.\n\n'
+    + '4. Stop. A later message reopens you on a fresh context window grounded in your goal and that roadmap, so what you leave behind now is what you get back.';
 /** Static recovery prompts shared by the broker producer and display classifier. */
 export const AUTH_FAULT_RECOVERY_BODY = 'Provider credentials were just updated (a new login landed). Your previous turn stopped on a provider authentication failure. Continue from where you left off and retry the work that failed.';
 export const CONNECTION_FAULT_RECOVERY_BODY = 'The network connection is back online. Your previous turn stopped on a connection error (the network was down). Continue from where you left off and retry the work that failed.';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@north-light/crouter",
-  "version": "0.3.231",
+  "version": "0.3.233",
   "description": "crtr — agent runtime with memory, plugins, and marketplaces",
   "type": "module",
   "main": "dist/index.js",
@@ -81,10 +81,10 @@
     "dev": "tsx --conditions=crtr-src src/cli.ts",
     "link": "npm link",
     "prepublishOnly": "npm run build",
-    "test": "node --conditions=crtr-src --import tsx/esm --test --test-force-exit --test-concurrency=$(node -p 'Math.max(4, require(`node:os`).availableParallelism() - 1)') --test-timeout=10000 'src/**/__tests__/*.test.ts'",
-    "test:integration": "node --conditions=crtr-src --import tsx/esm --test --test-concurrency=$(node -p 'Math.min(8, Math.max(2, require(`node:os`).availableParallelism() - 1))') --test-timeout=60000 'src/**/__tests__/integration/*.test.ts'",
+    "test": "CRTR_NO_DAEMON_AUTOSTART=1 node --conditions=crtr-src --import tsx/esm --test --test-force-exit --test-concurrency=$(node -p 'Math.max(4, require(`node:os`).availableParallelism() - 1)') --test-timeout=10000 'src/**/__tests__/*.test.ts'",
+    "test:integration": "CRTR_NO_DAEMON_AUTOSTART=1 node --conditions=crtr-src --import tsx/esm --test --test-concurrency=$(node -p 'Math.min(8, Math.max(2, require(`node:os`).availableParallelism() - 1))') --test-timeout=60000 'src/**/__tests__/integration/*.test.ts'",
     "test:seam": "npm run build && npm run test:seam:built",
-    "test:seam:built": "node --test --test-concurrency=4 --test-timeout=180000 'dist/**/__tests__/seam/*.test.js'",
+    "test:seam:built": "CRTR_NO_DAEMON_AUTOSTART=1 node --test --test-concurrency=4 --test-timeout=180000 'dist/**/__tests__/seam/*.test.js'",
     "test:all": "npm test && npm run test:integration && npm run test:seam"
   },
   "overrides": {

package/runtime.lock.json

@@ -1,12 +1,12 @@
 {
   "name": "@north-light/crouter",
-  "version": "0.3.231",
+  "version": "0.3.233",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "@north-light/crouter",
-      "version": "0.3.231",
+      "version": "0.3.233",
       "hasInstallScript": true,
       "license": "MIT",
       "dependencies": {

package/dist/builtin-pi-packages/pi-crtr-extensions/extensions/strip-skills-docs.ts

@@ -1,47 +0,0 @@
-/**
- * Strip pi's "Pi documentation" block from the system prompt.
- *
- * Pi core hardcodes a "Pi documentation (read only when the user asks about pi
- * itself, its SDK, extensions, themes, skills, or TUI):" block — a marker line
- * plus a bullet list pointing at pi's README / docs / examples under
- * node_modules. It causes two problems we fix by removing the whole block:
- *
- *  1. It maps topics to doc files (`skills (docs/skills.md)`, etc.), which makes
- *     the agent extrapolate a topic -> docs/<topic>.md pattern and surface pi's
- *     internal skill system when we don't want it referenced.
- *  2. It is a THIRD-PARTY TELL. When authenticating a Claude subscription over
- *     OAuth, Anthropic inspects the request and — if it doesn't look like genuine
- *     Claude Code — routes it to "extra usage" instead of the plan, returning
- *     HTTP 400 ("Third-party apps now draw from your extra usage..."). The
- *     companion `pi-claude-oauth-adapter` normally strips this block for exactly
- *     that reason, but it matches the marker string INCLUDING the word "skills,"
- *     — and the earlier version of THIS extension mangled that marker (it removed
- *     just the "skills" word), so the adapter's match failed and the block leaked
- *     to the wire → every subscription turn 400'd. Removing the entire block here
- *     is self-contained: it fixes the leak regardless of the adapter's marker,
- *     load order, or presence, and subsumes the old skill-reference removal.
- *
- * Runs in `before_agent_start` so it survives `pi update` / `brew upgrade`
- * (which would overwrite any edit to the installed dist), and degrades to a
- * no-op if pi changes the wording.
- */
-
-import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
-
-// Matches the whole block: the "Pi documentation (read only ...):" marker line
-// (with or without the "skills," enumeration) plus its trailing "- ..." bullets,
-// and any leading blank lines so the surrounding prompt closes up cleanly.
-const PI_DOCS_BLOCK = /\n*^Pi documentation \(read only[^\n]*:(?:\n[ \t]*-[^\n]*)*/m;
-
-function stripPiDocsBlock(prompt: string): string {
-	if (!prompt.includes("Pi documentation (read only")) return prompt; // no-op / wording changed
-	return prompt.replace(PI_DOCS_BLOCK, "").trimEnd() + "\n";
-}
-
-export default function stripSkillsDocs(pi: ExtensionAPI) {
-	pi.on("before_agent_start", async (event) => {
-		const stripped = stripPiDocsBlock(event.systemPrompt);
-		if (stripped === event.systemPrompt) return;
-		return { systemPrompt: stripped };
-	});
-}