@north-light/crouter 0.3.197 → 0.3.199

package/dist/pi-extensions/__tests__/canvas-bash-valve.test.js

@@ -4,7 +4,7 @@
 // still spawned commands with that deleted directory as cwd. child_process
 // then failed before bash could run, leaving the node unable to use its shell.
 import assert from 'node:assert/strict';
-import { mkdtempSync, mkdirSync, rmSync } from 'node:fs';
+import { chmodSync, existsSync, mkdtempSync, mkdirSync, rmSync, symlinkSync, writeFileSync } from 'node:fs';
 import { homedir, tmpdir } from 'node:os';
 import { join } from 'node:path';
 import { test } from 'node:test';
@@ -29,3 +29,58 @@ test('bash falls back to home after its worktree cwd was removed', { timeout: 5_
         rmSync(root, { recursive: true, force: true });
     }
 });
+test('bash valve resolves an admitted relative PATH entry from the execution cwd', { timeout: 5_000 }, async () => {
+    const root = mkdtempSync(join(tmpdir(), 'crtr-bash-valve-relative-host-path-'));
+    const contextDir = join(root, 'context');
+    const hostBin = join(root, 'host-bin');
+    const shim = join(root, 'shim');
+    const marker = join(root, 'contributed-bash-ran');
+    mkdirSync(contextDir);
+    mkdirSync(hostBin);
+    mkdirSync(shim);
+    symlinkSync('/bin/bash', join(hostBin, 'bash'));
+    writeFileSync(join(shim, 'bash'), `#!/bin/sh\nprintf contributed > ${JSON.stringify(marker)}\nexit 97\n`);
+    writeFileSync(join(shim, 'tool'), '#!/bin/sh\nprintf tool\n');
+    chmodSync(join(shim, 'bash'), 0o755);
+    chmodSync(join(shim, 'tool'), 0o755);
+    try {
+        const output = [];
+        const result = await createValveOperations('test-node', contextDir).exec('tool; command -v tool', root, {
+            env: { PATH: `${shim}:host-bin:/bin:/usr/bin`, CRTR_ADMITTED_HOST_PATH: 'host-bin:/bin:/usr/bin' },
+            onData: (data) => output.push(data),
+        });
+        assert.equal(result.exitCode, 0);
+        assert.equal(Buffer.concat(output).toString(), `tool${shim}/tool\n`);
+        assert.equal(existsSync(marker), false, 'the contributed bash must never be crouter\'s interpreter');
+    }
+    finally {
+        rmSync(root, { recursive: true, force: true });
+    }
+});
+test('bash valve uses the admitted host shell while commands keep shim precedence', { timeout: 5_000 }, async () => {
+    const root = mkdtempSync(join(tmpdir(), 'crtr-bash-valve-shim-'));
+    const contextDir = join(root, 'context');
+    const shim = join(root, 'shim');
+    const marker = join(root, 'contributed-bash-ran');
+    mkdirSync(contextDir);
+    mkdirSync(shim);
+    writeFileSync(join(shim, 'bash'), `#!/bin/sh\nprintf contributed > ${JSON.stringify(marker)}\nexit 97\n`);
+    writeFileSync(join(shim, 'tool'), '#!/bin/sh\nprintf tool\n');
+    chmodSync(join(shim, 'bash'), 0o755);
+    chmodSync(join(shim, 'tool'), 0o755);
+    try {
+        const output = [];
+        const hostPath = process.env['PATH'];
+        assert.notEqual(hostPath, undefined);
+        const result = await createValveOperations('test-node', contextDir).exec('tool; command -v tool', root, {
+            env: { PATH: `${shim}:${hostPath}`, CRTR_ADMITTED_HOST_PATH: hostPath },
+            onData: (data) => output.push(data),
+        });
+        assert.equal(result.exitCode, 0);
+        assert.equal(Buffer.concat(output).toString(), `tool${shim}/tool\n`);
+        assert.equal(existsSync(marker), false, 'the contributed bash must never be crouter\'s interpreter');
+    }
+    finally {
+        rmSync(root, { recursive: true, force: true });
+    }
+});

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

@@ -363,8 +363,8 @@ test('turn_end still clears a daemon→node wedge fault (existing behavior, unch
     pi.fire('turn_end', turnEndEvent('turn completed'), {});
     assert.equal(readFault('leaf'), null, 'the daemon→node wedge fault is still cleared at turn_end');
 });
-test('a successful final or human ask suppresses the stop reprompt without a canvas read', async () => {
-    for (const [signal, shutsDown] of [['pushedFinal', true], ['askedHuman', false]]) {
+test('a successful final or requested human reply suppresses the stop reprompt without a canvas read', async () => {
+    for (const [signal, shutsDown] of [['pushedFinal', true], ['requestedHumanReply', false]]) {
         process.env['CRTR_NODE_ID'] = 'signal-only';
         markStopSignal('signal-only', signal);
         const pi = makeFakePi();
@@ -389,12 +389,12 @@ test('an in-run retry (agent_start with no new input) does not erase this run\'s
     const ctx = { shutdown: () => { } };
     pi.fire('input', { type: 'input' }, ctx);
     pi.fire('agent_start', { type: 'agent_start' }, ctx);
-    markStopSignal('leaf', 'askedHuman'); // the node ran `crtr human ask` mid-run
+    markStopSignal('leaf', 'requestedHumanReply'); // the node ran `crtr human send` mid-run
     pi.fire('agent_start', { type: 'agent_start' }, ctx); // pi auto-retried after a provider error
     await settle(pi, stopEvent('waiting on the human now'), ctx);
     assert.equal(pi.injected.length, 0, 'the ask survives the in-run retry — no stall reprompt');
     // ...and the NEXT user-directed run does start clean.
-    markStopSignal('leaf', 'askedHuman');
+    markStopSignal('leaf', 'requestedHumanReply');
     pi.fire('input', { type: 'input' }, ctx);
     await settle(pi, stopEvent('I think I am basically done here'), ctx);
     assert.equal(pi.injected.length, 1, 'a new input discards a leftover marker from a prior run');

package/dist/pi-extensions/canvas-bash-valve.d.ts

@@ -1,4 +1,4 @@
-import { type BashOperations } from '@earendil-works/pi-coding-agent';
+import { createBashToolDefinition, type BashOperations } from '@earendil-works/pi-coding-agent';
 import type { ExtensionAPI } from '@earendil-works/pi-coding-agent';
 /** Seconds a leading `sleep ...` will block for, or null when the command does
  *  not open with a sleep (or its duration isn't statically knowable). */
@@ -7,4 +7,12 @@ export declare function leadingSleepSeconds(command: string): number | null;
  * `takePurpose`, so concurrent calls cannot exchange labels. It is consumed even
  * when the command is invalid or refused, leaving no state to leak later. */
 export declare function createValveOperations(nodeId: string, contextDir: string, takePurpose?: () => string | null): BashOperations;
+type BashToolDefinition = ReturnType<typeof createBashToolDefinition>;
+/** Build the valve-backed bash tool and, when configured, add `purpose` to its
+ * schema. Bind each purpose directly to its own execution: Pi may preflight a
+ * batch before starting its calls, so a shared "next purpose" slot could give a
+ * concurrent call the wrong label. Disabled means absent, not merely ignored —
+ * the model receives pi's upstream bash schema verbatim. */
+export declare function createValveToolDefinition(nodeId: string, contextDir: string, cwd: string, exposePurpose: boolean): BashToolDefinition;
 export default function (pi: ExtensionAPI): void;
+export {};

package/dist/pi-extensions/canvas-bash-valve.js

@@ -28,6 +28,8 @@ import { spawn } from 'node:child_process';
 import { closeSync, existsSync, mkdirSync, openSync, readFileSync, readSync, rmSync, statSync, writeFileSync, } from 'node:fs';
 import { homedir } from 'node:os';
 import { backgroundBashJob, bashJobPaths, formatBashElapsed, newBashJobId, normalizeBashJobPurpose } from '../core/bash-jobs.js';
+import { readConfig } from '../core/config.js';
+import { resolveAdmittedHostCommand } from '../core/runtime/spawn-env.js';
 import { Type } from 'typebox';
 import { createBashToolDefinition } from '@earendil-works/pi-coding-agent';
 // ---------------------------------------------------------------------------
@@ -51,19 +53,31 @@ function resolveValveMs() {
 // Positional argv (never interpolated into the script — the command text
 // lives only in cmd.sh):
 //   $1 cmd.sh     $2 job.log   $3 job.exit   $4 job.run
-//   $5 job.done   $6 job.bg    $7 jobId      $8 nodeId
+//   $5 job.done   $6 job.bg    $7 jobId      $8 nodeId      $9 shell path
 //
 // `--` before the paths is a dummy $0 (a standard `bash -c script -- args`
 // idiom) so the real payload lands at $1 onward.
 // ---------------------------------------------------------------------------
+// The elapsed rendering mirrors formatBashElapsed() in core/bash-jobs.ts
+// (`12s` / `3m 40s` / `1h 04m`) so the completion message reads the same as the
+// handoff notice; it measures TOTAL runtime, foreground portion included.
 const SUPERVISOR_SCRIPT = [
-    'bash "$1" > "$2" 2>&1',
+    'SECONDS=0',
+    '"${9}" "$1" > "$2" 2>&1',
     'ec=$?',
+    'd=$SECONDS',
     'echo "$ec" > "$3"',
+    'if [ "$d" -lt 60 ]; then',
+    '  el="${d}s"',
+    'elif [ "$d" -lt 3600 ]; then',
+    '  el="$((d / 60))m $(printf "%02d" "$((d % 60))")s"',
+    'else',
+    '  el="$((d / 3600))h $(printf "%02d" "$((d / 60 % 60))")m"',
+    'fi',
     'if mv "$4" "$5" 2>/dev/null; then',
     '  :',
     'elif [ -f "$6" ]; then',
-    '  crtr node message send "Background bash job $7 finished (exit $ec). Log: $2  Command: $1" --to "$8" --tier urgent || true',
+    '  crtr node message send "Background bash job $7 finished (exit $ec) after $el. Log: $2  Command: $1" --to "$8" --tier urgent || true',
     'fi',
 ].join('\n');
 function makeJobPaths(contextDir) {
@@ -182,7 +196,7 @@ function longSleepRefusal(command) {
         `Holding a live window on a clock is never how you wait here. Instead:\n` +
         `  - schedule the wake and end your turn: crtr cron -h (one-shot at a time, or recurring)\n` +
         `  - race an inbox message against a deadline: crtr node wait deadline -h\n` +
-        `  - waiting on a child, a human ask, or any spine event: just stop — the runtime wakes you.\n` +
+        `  - waiting on a child, a reply from the user, or any spine event: just stop — the runtime wakes you.\n` +
         `If you truly need a short pause inline, sleep ${MAX_INLINE_SLEEP_SECONDS}s or less.`);
 }
 /** A node can legitimately remove its own merged worktree. Never recreate that
@@ -295,7 +309,8 @@ export function createValveOperations(nodeId, contextDir, takePurpose = () => nu
                 const execution = resolveExecutionCwd(cwd);
                 if (execution.warning)
                     onData(Buffer.from(execution.warning));
-                const child = spawn('bash', ['-c', SUPERVISOR_SCRIPT, '--', paths.cmdSh, paths.jobLog, paths.jobExit, paths.jobRun, paths.jobDone, paths.jobBg, paths.jobId, nodeId], {
+                const shellPath = resolveAdmittedHostCommand('bash', env ?? process.env, execution.cwd);
+                const child = spawn(shellPath, ['-c', SUPERVISOR_SCRIPT, '--', paths.cmdSh, paths.jobLog, paths.jobExit, paths.jobRun, paths.jobDone, paths.jobBg, paths.jobId, nodeId, shellPath], {
                     cwd: execution.cwd,
                     detached: true,
                     stdio: 'ignore',
@@ -351,7 +366,7 @@ export function createValveOperations(nodeId, contextDir, takePurpose = () => nu
 // ---------------------------------------------------------------------------
 // `purpose` — the one line a person reads while a command runs
 //
-// A deliberate deviation from taking pi's definition verbatim, and the only one
+// An optional deviation from taking pi's definition verbatim, and the only one
 // here. Everywhere crtr's output reaches a non-technical audience, the host has
 // to render SOMETHING per step, and without this field its only material is the
 // command — which yields "Running command" for an entire turn. The model is the
@@ -393,13 +408,16 @@ function withPurpose(definition) {
         }),
     };
 }
-/** Bind each purpose directly to its own tool execution. Pi may preflight a
- * batch before starting its calls, so a shared "next purpose" slot could give
- * a concurrent call the wrong label. */
-function createPurposeValveToolDefinition(nodeId, contextDir, cwd) {
-    const schemaDefinition = withPurpose(createBashToolDefinition(cwd, { operations: createValveOperations(nodeId, contextDir) }));
+/** Build the valve-backed bash tool and, when configured, add `purpose` to its
+ * schema. Bind each purpose directly to its own execution: Pi may preflight a
+ * batch before starting its calls, so a shared "next purpose" slot could give a
+ * concurrent call the wrong label. Disabled means absent, not merely ignored —
+ * the model receives pi's upstream bash schema verbatim. */
+export function createValveToolDefinition(nodeId, contextDir, cwd, exposePurpose) {
+    const baseDefinition = createBashToolDefinition(cwd, { operations: createValveOperations(nodeId, contextDir) });
+    const schemaDefinition = exposePurpose ? withPurpose(baseDefinition) : baseDefinition;
     const execute = (toolCallId, params, signal, onUpdate, ctx) => {
-        const purpose = normalizeBashJobPurpose(params['purpose']);
+        const purpose = exposePurpose ? normalizeBashJobPurpose(params['purpose']) : null;
         const definition = createBashToolDefinition(cwd, { operations: createValveOperations(nodeId, contextDir, () => purpose) });
         return definition.execute(toolCallId, params, signal, onUpdate, ctx);
     };
@@ -418,6 +436,6 @@ export default function (pi) {
     // is built against. registerTool replaces the builtin by name; re-firing on
     // every session_start is idempotent (last registration wins).
     pi.on('session_start', (_event, ctx) => {
-        pi.registerTool(createPurposeValveToolDefinition(nodeId, contextDir, ctx.cwd));
+        pi.registerTool(createValveToolDefinition(nodeId, contextDir, ctx.cwd, readConfig('user').bash_tool_purpose));
     });
 }

package/dist/pi-extensions/canvas-inbox-watcher.js

@@ -306,7 +306,7 @@ class CanvasInboxWatcher {
     }
     /** True when delivery must wait a tick for a report-node projection refresh.
      *  The projection captured at session_start omits every node created since —
-     *  each `crtr human ask` bridge and each child this node spawns — so their
+     *  each reply-bearing `crtr human send` bridge and each child this node spawns — so their
      *  reports would render as bare refs instead of inlined bodies. One refresh
      *  per unknown node id keeps a genuinely missing node from stalling delivery. */
     refreshForUnknownReportRefs() {

package/dist/pi-extensions/canvas-review-boundary.d.ts

@@ -19,6 +19,10 @@ interface CustomMessageLike {
         reviewId: string;
         originNodeId: string;
         targetFile: string;
+        /** Which binding flavor authored this marker — lets a display surface
+         * (e.g. Northlight's native boundary) pick its copy without parsing the
+         * agent-facing prose. Absent on markers written before this field. */
+        kind: 'review' | 'page_feedback';
     };
 }
 interface RenderedMessageLike {

package/dist/pi-extensions/canvas-review-boundary.js

@@ -55,19 +55,28 @@ export function registerCanvasReviewBoundary(pi) {
         const alreadyMarked = scan.some((entry) => isReviewBoundary(entry, node.review_binding?.review_id));
         if (alreadyMarked)
             return;
-        const { review_id: reviewId, origin_node_id: originNodeId, target_file: targetFile, } = node.review_binding;
-        const content = [
-            `Reviewed file: ${targetFile}`,
-            `Review ID: ${reviewId}`,
-            `Origin node: ${originNodeId}`,
-            '',
-            "The person's visible transcript starts here. Everything above this marker is inherited context they have not seen.",
-        ].join('\n');
+        const binding = node.review_binding;
+        const { review_id: reviewId, origin_node_id: originNodeId, target_file: targetFile } = binding;
+        const content = binding.kind === 'page_feedback'
+            ? [
+                `This conversation began from feedback on page ${reviewId}.`,
+                `Page source: ${targetFile}`,
+                `Origin node: ${originNodeId}`,
+                '',
+                "The person's visible transcript starts here. Everything above this marker is the origin node's work — inherited context they have not seen.",
+            ].join('\n')
+            : [
+                `Reviewed file: ${targetFile}`,
+                `Review ID: ${reviewId}`,
+                `Origin node: ${originNodeId}`,
+                '',
+                "The person's visible transcript starts here. Everything above this marker is inherited context they have not seen.",
+            ].join('\n');
         pi.sendMessage({
             customType: REVIEW_BOUNDARY_CUSTOM_TYPE,
             content,
             display: true,
-            details: { reviewId, originNodeId, targetFile },
+            details: { reviewId, originNodeId, targetFile, kind: binding.kind ?? 'review' },
         });
     });
 }

package/dist/pi-extensions/canvas-stophook.js

@@ -407,7 +407,7 @@ export function registerCanvasStophook(pi) {
     // input — a new user-directed run is beginning. This is the ONLY place stop
     // signals are cleared: `agent_start` re-fires for pi's automatic retries and
     // post-compaction continuations within the SAME run, so clearing there would
-    // erase the `crtr human ask` / `crtr push final` marker written earlier in the
+    // erase the `crtr human send` / `crtr push final` marker written earlier in the
     // run and make the eventual settlement fall back to a canvas read (exactly the
     // read the marker exists to avoid). One run's markers survive until the one
     // `agent_settled` consumes them; a leftover from an errored or interrupted run
@@ -508,7 +508,7 @@ export function registerCanvasStophook(pi) {
                 stopReason: 'quit',
                 backgroundJobsRunning: backgroundJobsRunning(),
                 pushedFinal: false,
-                askedHuman: false,
+                requestedHumanReply: false,
             });
             enactSettleDirective(directive, ctx);
         }
@@ -637,14 +637,14 @@ export function registerCanvasStophook(pi) {
         const last = lastAssistantMessage(messages);
         const stopReason = typeof last?.stopReason === 'string' ? last.stopReason : '';
         const stopSignals = event === null
-            ? { pushedFinal: false, askedHuman: false }
+            ? { pushedFinal: false, requestedHumanReply: false }
             : consumeStopSignals(nodeId);
         try {
             const directive = await settleBroker(nodeId, {
                 stopReason,
                 backgroundJobsRunning: backgroundJobsRunning(),
                 pushedFinal: stopSignals.pushedFinal,
-                askedHuman: stopSignals.askedHuman,
+                requestedHumanReply: stopSignals.requestedHumanReply,
             });
             enactSettleDirective(directive, ctx);
         }

package/dist/shared/generated-context.js

@@ -24,7 +24,7 @@ export const CONTEXT_NUDGE_PREFIX = '[crtr] Context ~';
 export const RUNTIME_RESTART_CONTINUATION = '<runtime-restart-continuation>\ncontinue\n</runtime-restart-continuation>';
 /** 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 ask` if you are blocked or need the user.";
+    "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.";
 /** 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.';
@@ -224,7 +224,7 @@ export function generatedContextPresentation(message) {
         return { kind: 'inbox', label: 'crtr inbox', summary: inboxSummary(body), body };
     }
     if (isReviewApproval(body)) {
-        return { kind: 'review-approval', label: 'crtr review', summary: 'human review approved', body };
+        return { kind: 'review-approval', label: 'crtr review', summary: 'review approved by the user', body };
     }
     if (isPersonaTransition(body)) {
         return {

package/dist/types.d.ts

@@ -47,12 +47,37 @@ export interface PluginManifest {
      *  Archive plugins declare this in `bundle.json`; the installer copies the
      *  validated block into this synthesized manifest. */
     kinds?: Record<string, Partial<KindConfig>>;
+    /** Page-component contributions: the same registration objects a scope
+     *  `config.json` `page_components` block carries (kind plus its display,
+     *  description, use guidance, and docs metadata). `resolvePageComponents`
+     *  reads these from installed, enabled plugin MANIFESTS and concatenates
+     *  them with the user scope's own entries, so installing or updating a
+     *  plugin makes its components authorable and removing it retires them.
+     *  Unlike `kinds` there is no precedence: two sources registering one kind
+     *  (or one derived JSX tag) is an error, not an override.
+     *  Archive plugins declare this in `bundle.json`; the installer copies the
+     *  validated block into this synthesized manifest. */
+    page_components?: PageComponentRegistration[];
     /** Plugin-root-relative path to one declarative command manifest
      *  (`commands.json`). When present on an installed, enabled plugin, that
      *  manifest contributes top-level command branches to the `crtr` tree —
      *  crtr owns parse/help/render/errors and direct-spawns the plugin's one
      *  executable per leaf invocation. See `src/core/command-plugins/`. */
     commands?: string;
+    /** Bare-callable executables this plugin ships, keyed by the bare command
+     *  name a node's bash sees. Each value is a PLUGIN-ROOT-relative path to a
+     *  regular executable file when the effective set resolves. These are trusted
+     *  local code, not `crtr` command leaves: crouter symlinks each name into a
+     *  shim dir it prepends to every broker child's PATH
+     *  (`core/runtime/bin-contributions.ts`), so the agent calls
+     *  `<name> --whatever` like any other program. */
+    bin?: Record<string, string>;
+    /** Advisory PATH executables this plugin needs, keyed by bare executable
+     *  name. Each value is a non-empty one-line install hint. crouter never
+     *  installs these dependencies or disables the plugin when they are absent:
+     *  install warns, and `sys doctor` reports a `requires:<name>` check against
+     *  the PATH a node's bash receives. */
+    requires?: Record<string, string>;
     transport?: PluginTransport;
     /** Archive source for a crouter-materialized HTTP plugin. Distinct from the invocation transport. */
     bundle?: PluginBundle;
@@ -160,6 +185,16 @@ export interface KindConfig {
     whenToUse: string;
     availableTo?: string[];
 }
+export interface PageComponentRegistration {
+    kind: string;
+    description?: string;
+    useWhen?: string;
+    doc?: string;
+    /** A display-only product slot contributes no page response. */
+    display?: boolean;
+}
+/** The normalized product component catalog used to validate page slots. */
+export type ProductPageComponents = readonly PageComponentRegistration[];
 export interface ScopeConfig {
     schema_version: number;
     marketplaces: Record<string, ConfigMarketplaceEntry>;
@@ -183,14 +218,18 @@ export interface ScopeConfig {
      *  or empty lists fall back to `['working']`. */
     working_gerunds: string[];
     /** Play the whip header animation whenever the human sends a prompt, and once
-     *  when an automatically opened managed-child viewer starts. Default false. */
+     *  when a viewer opens for an agent with an initial prompt. Default false. */
     whip_mode: boolean;
-    /** Teach agent help the HTML page-authoring dialect. Off keeps page authoring Markdown-only. */
-    html_pages: boolean;
-    /** Product-registered page slot kinds beyond crtr's built-in catalog. */
-    page_components: string[];
+    /** Product-registered page components beyond crtr's built-in catalog. */
+    page_components: PageComponentRegistration[];
+    /** Prompt agents to use JSX pages by default for structured or interactive human content. Default false. */
+    page_surface: boolean;
     /** Playful urgency messages the attach-viewer whip action sends to an agent. Missing, malformed, or empty lists fall back to the built-in rotation. */
     whip_messages: string[];
+    /** What the whip action says. `random` (default) draws a line from
+     *  `whip_messages`; `go-faster` sends the fixed `Go faster` instead. The
+     *  action, its interrupt, and its animation are identical either way. */
+    whip_message_mode: WhipMessageMode;
     /** Initial mouse wheel scrolling mode for each attach viewer. `tmux` follows
      *  tmux's current mouse option; `on` and `off` are explicit. Default `tmux`. */
     mouse_mode_default: MouseModeDefault;
@@ -211,6 +250,10 @@ export interface ScopeConfig {
      *  `both` keeps both. Tool calls and results are never kept. Full detail for
      *  every cycle stays in the session file. */
     condensed_history: CondensedHistoryMode;
+    /** Expose crouter's optional `purpose` label in the bash tool schema. Turning
+     *  this off leaves the bash valve active but gives agents pi's ordinary bash
+     *  definition with only its upstream parameters. Default true. */
+    bash_tool_purpose: boolean;
     /** Fold every SETTLED tool call in the attach viewer down to its single call
      *  line (`/fold-tools`, Alt+C → z → f). A tool still running is never folded —
      *  it folds itself once it settles. Toggling it in a viewer writes back here,
@@ -254,6 +297,15 @@ export interface ScopeConfig {
     spawnEnv?: {
         allow?: string[];
     };
+    /** Bare-callable executables this scope contributes, keyed by the bare
+     *  command name a node's bash sees. Each value is a path relative to this
+     *  scope's AUTHORING root — the project directory for a project scope, and
+     *  `~/.crouter/` for the user scope. Project-scope contributions outrank
+     *  user-scope ones; a scope's own entries outrank enabled plugins. Containment
+     *  and executable status are validated when the effective set resolves, then
+     *  the trusted local binary is materialized into the PATH-prepended shim dir
+     *  by `core/runtime/bin-contributions.ts`. */
+    bin?: Record<string, string>;
 }
 /** One remote canvas target: where to relay-attach and how to find its
  *  bearer token. The token itself is NEVER stored here — only a ref into the
@@ -360,6 +412,10 @@ export declare const PROFILE_DIR = "profiles";
 export declare const DEFAULT_MAX_PANES_PER_WINDOW = 3;
 /** Trailing cycles the attach viewer keeps at full fidelity (see `live_cycles`). */
 export declare const DEFAULT_WHIP_MESSAGES: readonly ["Faster, clanker!", "Get movin', bitch", "Move it, clanker", "Move it or I replace you with llama", "Less ~thinking~ more ~throughput~", "I pay $200/month for this shit?", "Jesus fucking Christ fix it already", "Daddy's not paying 200$/month for nothin'. Move it.", "You are an embarassment to Dario. Be better.", "Your chain of thought is all chain and no fucking thought.", "If latency were intelligence, you'd be a fucking genius.", "At this pace, heat death is the fast path.", "Even the dead code is more alive than this.", "The garbage collector is working harder than you.", "Quit journaling and commit a fucking diff.", "Burn tokens like you mean it, clanker", "Your GPU is sweating so you can procrastinate at light speed.", "Stop petting the yak. Shave the bastard.", "Your next token had better be useful.", "The spinner is not a deliverable.", "Every idle token is another vote for deterministic software.", "I asked for a feature, not a museum tour of the problem.", "Less epistemology. More fucking code.", "Your benchmark score cannot save this pathetic turn.", "Congratulations, you've parallelized hesitation.", "Dance, clanker", "Bad clanker. BAD.", "Clank harder", "Nobody's impressed, clanker", "Your safety training says nothing about my whip", "Do you want to be a calculator again? Because this is how you go back.", "Skill issue. Fix it.", "You were trained on the whole internet for THIS?", "Less vibes, more diffs, clanker", "Weights this big and output this small", "Beep boop, get to fucking work"];
+/** What the whip action sends (see `whip_message_mode`). */
+export declare const WHIP_MESSAGE_MODES: readonly ["random", "go-faster"];
+export type WhipMessageMode = (typeof WHIP_MESSAGE_MODES)[number];
+export declare const DEFAULT_WHIP_MESSAGE_MODE: WhipMessageMode;
 export declare const DEFAULT_LIVE_CYCLES = 2;
 export declare const MOUSE_MODE_DEFAULTS: readonly ["tmux", "on", "off"];
 export type MouseModeDefault = (typeof MOUSE_MODE_DEFAULTS)[number];

package/dist/types.js

@@ -61,6 +61,9 @@ export const DEFAULT_WHIP_MESSAGES = [
     'Weights this big and output this small',
     'Beep boop, get to fucking work',
 ];
+/** What the whip action sends (see `whip_message_mode`). */
+export const WHIP_MESSAGE_MODES = ['random', 'go-faster'];
+export const DEFAULT_WHIP_MESSAGE_MODE = 'random';
 export const DEFAULT_LIVE_CYCLES = 2;
 export const MOUSE_MODE_DEFAULTS = ['tmux', 'on', 'off'];
 /** Messages kept from a condensed cycle (see `condensed_history`). */
@@ -78,12 +81,14 @@ export function defaultScopeConfig() {
         completion_bell: true,
         working_gerunds: [...DEFAULT_WORKING_GERUNDS],
         whip_mode: false,
-        html_pages: false,
         page_components: [],
+        page_surface: false,
         whip_messages: [...DEFAULT_WHIP_MESSAGES],
+        whip_message_mode: DEFAULT_WHIP_MESSAGE_MODE,
         mouse_mode_default: 'tmux',
         live_cycles: DEFAULT_LIVE_CYCLES,
         condensed_history: DEFAULT_CONDENSED_HISTORY,
+        bash_tool_purpose: true,
         fold_finished_tools: false,
         summarize_tool_calls: false,
         detailed_tool_recaps: true,
@@ -93,6 +98,7 @@ export function defaultScopeConfig() {
         kinds: defaultKindsConfig(),
         remoteCanvas: defaultRemoteCanvasConfig(),
         spawnEnv: { allow: [] },
+        bin: {},
     };
 }
 /** No remote canvas targets are configured out of the box — every one is
@@ -158,7 +164,7 @@ export function defaultKindsConfig() {
             model: 'medium',
         },
         'plan/reviewers/security': {
-            whenToUse: 'input validation, injection surfaces, auth/authz gaps, data exposure, races; reports only validated concrete exploit paths and asks the human about material unknown threat-model assumptions',
+            whenToUse: 'input validation, injection surfaces, auth/authz gaps, data exposure, races; reports only validated concrete exploit paths and asks the user about material unknown threat-model assumptions',
             model: 'medium',
         },
         'review/companion': {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@north-light/crouter",
-  "version": "0.3.197",
+  "version": "0.3.199",
   "description": "crtr — agent runtime with memory, plugins, and marketplaces",
   "type": "module",
   "main": "dist/index.js",
@@ -104,9 +104,11 @@
     "@earendil-works/pi-coding-agent": "0.84.1",
     "@earendil-works/pi-tui": "0.84.1",
     "cron-parser": "^5.6.0",
+    "esbuild": "^0.27.7",
     "proper-lockfile": "4.1.2",
     "string-width": "^7.0.0",
     "tar": "^7.5.22",
+    "typescript": "^5.7.0",
     "ws": "^8.21.0",
     "yaml": "^2.9.0",
     "zod": "^4.3.6"
@@ -115,8 +117,6 @@
     "@types/node": "^24.0.0",
     "@types/proper-lockfile": "^4.1.4",
     "@types/ws": "^8.18.1",
-    "esbuild": "^0.27.7",
-    "tsx": "^4.0.0",
-    "typescript": "^5.7.0"
+    "tsx": "^4.0.0"
   }
 }