@north-light/crouter 0.3.318 → 0.3.319

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

@@ -1,461 +1,7 @@
-// canvas-bash-valve.ts — the bash safety valve: auto-background hanging
-// commands, alert via inbox at tier `urgent` so completion lands as a steering
-// message mid-turn rather than queuing behind the current turn.
-//
-// Loaded into every canvas node's pi process via the node's launch.extensions
-// list. INERT when CRTR_NODE_ID is absent (plain pi session or legacy job
-// agent) — registers nothing, so the builtin bash tool stays in place.
-//
-// Rise with the tide: we do NOT reimplement or fork pi's bash tool. We call
-// pi's own `createBashToolDefinition()` (schema, description, rendering,
-// truncation, streaming throttle — ALL of it) and supply only a custom
-// `BashOperations` exec backend. Future pi improvements to the bash tool flow
-// through automatically; if pi ever changes the BashOperations interface, tsc
-// breaks loudly at upgrade instead of silently drifting.
-//
-// Why file-backed, not pipes: the builtin streams from a direct child over
-// pipes. A backgrounded orphan writing to a dead pipe after pi dies gets
-// SIGPIPE, and its exit code is observable by nobody. So every command is
-// file-backed from birth via a tiny detached supervisor (a `bash -c` process
-// group leader) that redirects the real command's stdout+stderr to a log
-// file through a bounded collector and records its exit code to a sentinel
-// file — both readable and tail-able, independent of whether this pi process
-// is even still alive.
-//
-// Deviation from upstream: this backend pins `bash` as the shell (upstream
-// consults user shell config via non-exported helpers). Acceptable — crtr's
-// agents are bash-contract anyway.
-import { envBashAutoBgDeadlineMs, envBashValveMs, envNodeId } from '../shared/env.js';
-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 { dirname } from 'node:path';
-import { performance } from 'node:perf_hooks';
-import { backgroundBashJob, bashJobPaths, cancelBashJobProcessTree, formatBashElapsed, newBashJobId, normalizeBashJobPurpose, readBashNiceness, writeJobDeadlineMs } from '../core/bash-jobs.js';
-import { bashCommandRefusal } from '../core/bash-guard.js';
-import { capturePidIdentities } from '../core/canvas/pid.js';
-import { readConfig } from '../core/config.js';
-import { PREVIEW_RESULT_PATH_ENV, previewResultPath } from '../core/preview-result-path.js';
-import { resolveAdmittedHostCommand } from '../core/runtime/spawn-env.js';
-import { Type } from 'typebox';
-import { createBashToolDefinition } from '@earendil-works/pi-coding-agent';
-// Deadline — 5 minutes by default, overridable via CRTR_BASH_VALVE_MS
-// (undocumented; test-only seam so the E2E valve check doesn't sleep 5m).
-const POLL_MS = 200;
-function resolveValveMs() {
-    return envBashValveMs();
-}
-export const MAX_BACKGROUND_BASH_LOG_BYTES = 10 * 1024 * 1024;
-export const BACKGROUND_BASH_LOG_TRUNCATION_MARKER = '\n[background bash job output truncated at 10 MiB; remaining output discarded]\n';
-// This process owns one bounded prefix of the command stream. It keeps
-// draining after the cap so the command never sees a closed pipe/SIGPIPE, and
-// uses synchronous fixed-size stdin chunks plus direct file writes so neither
-// the collector nor the log can grow without bound.
-const LOG_COLLECTOR_SCRIPT = [
-    'const fs = require("node:fs");',
-    `const cap = ${MAX_BACKGROUND_BASH_LOG_BYTES};`,
-    `const marker = Buffer.from(${JSON.stringify(BACKGROUND_BASH_LOG_TRUNCATION_MARKER)});`,
-    'const prefixCap = cap - marker.length;',
-    'const fd = fs.openSync(process.argv[1], "w");',
-    'let written = 0;',
-    'let truncated = false;',
-    'process.stdin.on("data", (chunk) => {',
-    '  if (truncated) return;',
-    '  const available = prefixCap - written;',
-    '  if (available > 0) {',
-    '    const prefix = chunk.subarray(0, available);',
-    '    fs.writeSync(fd, prefix);',
-    '    written += prefix.length;',
-    '    if (prefix.length === chunk.length) return;',
-    '  }',
-    '  fs.writeSync(fd, marker);',
-    '  truncated = true;',
-    '});',
-    'process.stdin.on("end", () => fs.closeSync(fd));',
-].join(' ');
-// The detached supervisor owns the command and its bounded stream collector.
-// 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      $9 shell path
-//   ${10} niceness ${11} node 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.
-// Only the command is niced (at ${10}, the node's own niceness); the supervisor
-// that reports its finish runs at normal priority so completion notices stay
-// prompt.
-const SUPERVISOR_SCRIPT = [
-    'SECONDS=0',
-    'n=$(command -v nice)',
-    '${n:+"$n" -n "${10}"} "${9}" "$1" 2>&1 | "${11}" -e ' + JSON.stringify(LOG_COLLECTOR_SCRIPT) + ' "$2"',
-    'ec=${PIPESTATUS[0]}',
-    '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) after $el. Log: $2  Command: $1" --to "$8" --tier urgent || true',
-    'fi',
-].join('\n');
-function makeJobPaths(contextDir) {
-    return bashJobPaths(contextDir, newBashJobId());
-}
-const liveForegroundJobs = new Set();
-let terminationHandoffInstalled = false;
-/** The broker is about to exit. Persist every foreground handoff synchronously
- * before pi's own termination listener aborts its active tool calls. */
-function backgroundLiveJobsForTermination() {
-    for (const paths of [...liveForegroundJobs]) {
-        try {
-            backgroundBashJob(paths);
-            liveForegroundJobs.delete(paths);
-        }
-        catch (err) {
-            process.stderr.write(`crtr: failed to background bash job ${paths.jobId} during broker termination: ${err.message}\n`);
-        }
-    }
-}
-function installTerminationHandoff() {
-    if (terminationHandoffInstalled)
-        return;
-    terminationHandoffInstalled = true;
-    process.prependListener('SIGTERM', backgroundLiveJobsForTermination);
-    if (process.platform !== 'win32')
-        process.prependListener('SIGHUP', backgroundLiveJobsForTermination);
-}
-const TAIL_CHUNK_BYTES = 64 * 1024;
-/** Read bytes appended to `path` since `offset`, feed them to onData, return
- * the new offset. Best-effort — a not-yet-created log file is not an error. */
-function tailOnce(path, offset, onData) {
-    let stat;
-    try {
-        stat = statSync(path);
-    }
-    catch {
-        return offset;
-    }
-    if (stat.size <= offset)
-        return offset;
-    const fd = openSync(path, 'r');
-    try {
-        while (offset < stat.size) {
-            const length = Math.min(TAIL_CHUNK_BYTES, stat.size - offset);
-            const buf = Buffer.allocUnsafe(length);
-            const bytesRead = readSync(fd, buf, 0, length, offset);
-            if (bytesRead === 0)
-                break;
-            onData(buf.subarray(0, bytesRead));
-            offset += bytesRead;
-        }
-        return offset;
-    }
-    finally {
-        closeSync(fd);
-    }
-}
-function cleanupJobDir(dir) {
-    try {
-        rmSync(dir, { recursive: true, force: true });
-    }
-    catch {
-        /* best-effort — worst case a stray dir under context/jobs/ */
-    }
-}
-function readExitCode(path) {
-    try {
-        const raw = readFileSync(path, 'utf8').trim();
-        const n = Number(raw);
-        return Number.isFinite(n) ? n : null;
-    }
-    catch {
-        return null;
-    }
-}
-/** A node can legitimately remove its own merged worktree. Never recreate that
- *  path: it would look like a valid checkout but no longer be one. Run later
- *  commands from a durable directory instead, and make the changed semantics
- *  explicit in the tool output. */
-function resolveExecutionCwd(cwd) {
-    try {
-        if (statSync(cwd).isDirectory())
-            return { cwd };
-    }
-    catch {
-        // A deleted worktree makes child_process.spawn fail with bare ENOENT.
-    }
-    const fallback = homedir();
-    return {
-        cwd: fallback,
-        warning: `[working directory no longer exists: ${cwd}; running from ${fallback}]\n`,
-    };
-}
-/** The valve's BashOperations backend. Each tool execution closes over its own
- * `takePurpose` and its own preview-result path, so concurrent calls cannot
- * exchange labels or result mirrors. The purpose is consumed even when the
- * command is invalid or refused, leaving no state to leak later. */
-export function createValveOperations(nodeId, contextDir, takePurpose = () => null, previewPath) {
-    return {
-        exec: (command, cwd, { onData, signal, timeout, env }) => {
-            return new Promise((resolve, reject) => {
-                const purpose = takePurpose();
-                if (signal?.aborted) {
-                    reject(new Error('aborted'));
-                    return;
-                }
-                const refusal = bashCommandRefusal(command, cwd);
-                if (refusal !== null) {
-                    reject(new Error(refusal));
-                    return;
-                }
-                const paths = makeJobPaths(contextDir);
-                mkdirSync(paths.dir, { recursive: true });
-                writeFileSync(paths.cmdSh, command);
-                writeFileSync(paths.jobLog, '');
-                writeFileSync(paths.jobRun, '');
-                if (purpose !== null)
-                    writeFileSync(paths.jobPurpose, purpose);
-                let offset = 0;
-                let settled = false;
-                let pgid;
-                let pgidIdentity;
-                const startedAt = performance.now();
-                const valveMs = resolveValveMs();
-                let interval;
-                const teardown = () => {
-                    if (interval)
-                        clearInterval(interval);
-                    if (signal)
-                        signal.removeEventListener('abort', onAbort);
-                    liveForegroundJobs.delete(paths);
-                };
-                const finish = (act) => {
-                    if (settled)
-                        return;
-                    settled = true;
-                    teardown();
-                    act();
-                };
-                function finishBackground(auto = false) {
-                    const elapsed = formatBashElapsed(performance.now() - startedAt);
-                    // An AUTO handoff (the agent did not choose to background this) is a
-                    // runaway risk: arm a cancel deadline the daemon enforces, and tell
-                    // the agent to claim it or lose it. A deliberate handoff runs to
-                    // completion as before — no deadline file, so the daemon skips it.
-                    let deadlineNotice = '';
-                    if (auto) {
-                        const deadlineMs = envBashAutoBgDeadlineMs();
-                        writeJobDeadlineMs(paths, Date.now() + deadlineMs);
-                        deadlineNotice =
-                            `It will be CANCELED in ${formatBashElapsed(deadlineMs)} unless you claim it: ` +
-                                `crtr node bash extend ${paths.jobId} --for <duration> (or --keep to run to completion). `;
-                    }
-                    const notice = `\n[backgrounded as job ${paths.jobId} after ${elapsed} in the foreground${auto ? ' (auto)' : ''}. ` +
-                        deadlineNotice +
-                        `It will interrupt you with a message when it exits. ` +
-                        `Watch: tail -f ${paths.jobLog} ; stop: crtr node bash kill ${paths.jobId}]`;
-                    onData(Buffer.from(notice));
-                    finish(() => resolve({ exitCode: 0 }));
-                    // Backgrounded — job dir persists (inspectable); no cleanup here.
-                }
-                function finishForeground() {
-                    offset = tailOnce(paths.jobLog, offset, onData);
-                    const exitCode = readExitCode(paths.jobExit);
-                    finish(() => resolve({ exitCode }));
-                    cleanupJobDir(paths.dir);
-                }
-                function requestBackground(auto = false) {
-                    const state = backgroundBashJob(paths);
-                    if (state === 'backgrounded' || state === 'already-backgrounded') {
-                        finishBackground(auto);
-                        return;
-                    }
-                    if (state === 'finished') {
-                        finishForeground();
-                        return;
-                    }
-                    finish(() => reject(new Error(`bash job ${paths.jobId} disappeared before it could be backgrounded`)));
-                    cleanupJobDir(paths.dir);
-                }
-                function onAbort() {
-                    offset = tailOnce(paths.jobLog, offset, onData);
-                    if (existsSync(paths.jobBg)) {
-                        finishBackground();
-                        return;
-                    }
-                    // Once the command has written its exit code, let the supervisor
-                    // finish the job.run → job.done transition before cleanup.
-                    if (existsSync(paths.jobExit))
-                        return;
-                    if (pgid !== undefined && pgidIdentity !== undefined)
-                        void cancelBashJobProcessTree(pgid, pgidIdentity);
-                    finish(() => reject(new Error('aborted')));
-                    cleanupJobDir(paths.dir);
-                }
-                if (signal)
-                    signal.addEventListener('abort', onAbort, { once: true });
-                const execution = resolveExecutionCwd(cwd);
-                if (execution.warning)
-                    onData(Buffer.from(execution.warning));
-                // The preview path reaches crtr through the environment, never through
-                // the command text: cmd.sh, job inspection, and the doc substrate's
-                // `command` surfaces all read that text as the agent's own words.
-                let childEnv = env ?? process.env;
-                if (previewPath !== undefined) {
-                    mkdirSync(dirname(previewPath), { recursive: true });
-                    // crtr APPENDS one JSONL record per invocation, so this call starts
-                    // from an empty file: a path left behind by a call whose result event
-                    // never arrived must not fold its records into this one's.
-                    rmSync(previewPath, { force: true });
-                    childEnv = { ...childEnv, [PREVIEW_RESULT_PATH_ENV]: previewPath };
-                }
-                const shellPath = resolveAdmittedHostCommand('bash', childEnv, 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, String(readBashNiceness(contextDir)), process.execPath], {
-                    cwd: execution.cwd,
-                    detached: true,
-                    stdio: 'ignore',
-                    env: childEnv,
-                });
-                child.on('error', (err) => {
-                    finish(() => reject(err));
-                    cleanupJobDir(paths.dir);
-                });
-                pgid = child.pid;
-                // The detached supervisor starts this process tree. Its launch-time
-                // identity lets cancellation reject a stale PID that now belongs to an
-                // unrelated process; it is not a containment guarantee.
-                if (pgid !== undefined) {
-                    pgidIdentity = capturePidIdentities([pgid])?.get(pgid);
-                    if (pgidIdentity === undefined) {
-                        try {
-                            process.kill(-pgid, 'SIGKILL');
-                        }
-                        catch { /* the just-started supervisor already exited */ }
-                        finish(() => reject(new Error(`bash job ${paths.jobId} started without a process identity`)));
-                        cleanupJobDir(paths.dir);
-                        return;
-                    }
-                    writeFileSync(paths.jobPgid, String(pgid));
-                    writeFileSync(paths.jobPgidIdentity, pgidIdentity);
-                    liveForegroundJobs.add(paths);
-                }
-                child.unref();
-                interval = setInterval(() => {
-                    offset = tailOnce(paths.jobLog, offset, onData);
-                    if (existsSync(paths.jobDone)) {
-                        finishForeground();
-                        return;
-                    }
-                    if (existsSync(paths.jobBg)) {
-                        finishBackground();
-                        return;
-                    }
-                    // job.exit is written before the supervisor claims job.done. Do not
-                    // time out or delete the directory during that in-progress exit.
-                    if (existsSync(paths.jobExit))
-                        return;
-                    const elapsedMs = performance.now() - startedAt;
-                    if (timeout !== undefined && timeout > 0) {
-                        if (elapsedMs >= timeout * 1000) {
-                            if (pgid !== undefined && pgidIdentity !== undefined)
-                                void cancelBashJobProcessTree(pgid, pgidIdentity);
-                            finish(() => reject(new Error(`timeout:${timeout}`)));
-                            cleanupJobDir(paths.dir);
-                        }
-                        return;
-                    }
-                    if (elapsedMs >= valveMs)
-                        requestBackground(true);
-                }, POLL_MS);
-            });
-        },
-    };
-}
-// Extension
-// `purpose` — the one line a person reads while a command runs
-//
-// 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
-// only party that knows why it is running this, so it says so, in one clause,
-// before the command streams.
-//
-// Declared FIRST so it arrives ahead of `command` in the argument stream: a host
-// parsing partial JSON can show the label while the command is still being
-// written, rather than after the call is complete and about to finish.
-//
-// The command execution path ignores it as shell input — this remains a
-// labelling channel, not an execution parameter. The valve only persists the
-// label beside a background job. Optional, so a model that omits it behaves
-// exactly as before.
-//
-// Upstream ask: pi's own bash tool should carry this (Claude Code's bash tool
-// has shipped an equivalent `description` field for years). Until it does, the
-// field is re-declared here on top of pi's schema rather than forked into it.
-const PURPOSE_DESCRIPTION = [
-    'One short clause naming what this step is FOR, in the words of the person you',
-    'are working for — "Reading the Acme thread", not "Fetching emails" and never',
-    '"Running GMAIL_FETCH_EMAILS". A person reads this while the command runs; it',
-    'is the only thing they see of this step. Under about eight words. Omit it for',
-    'steps that only touch your own scratch work.',
-].join(' ');
-/**
- * Prepend an optional `purpose` to pi's bash schema, carrying pi's own property
- * definitions through verbatim — so a future upstream change to the `command`
- * or `timeout` wording still reaches the model, and this file owns exactly one
- * field.
- */
-function withPurpose(definition) {
-    return {
-        ...definition,
-        parameters: Type.Object({
-            purpose: Type.Optional(Type.String({ description: PURPOSE_DESCRIPTION })),
-            ...definition.parameters.properties,
-        }),
-    };
-}
-/** 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 = exposePurpose ? normalizeBashJobPurpose(params['purpose']) : null;
-        const definition = createBashToolDefinition(cwd, {
-            operations: createValveOperations(nodeId, contextDir, () => purpose, previewResultPath(toolCallId)),
-        });
-        return definition.execute(toolCallId, params, signal, onUpdate, ctx);
-    };
-    return { ...schemaDefinition, execute };
-}
-export default function (pi) {
-    const nodeId = envNodeId();
-    if (nodeId === undefined || nodeId.trim() === '')
-        return; // inert — builtin bash stays
-    const contextDir = process.env['CRTR_CONTEXT_DIR'];
-    if (contextDir === undefined || contextDir.trim() === '')
-        return; // defensive; always set alongside CRTR_NODE_ID
-    installTerminationHandoff();
-    // Registered on session_start (fires for startup, new, resume, fork, and
-    // /reload) so we get ctx.cwd — the same session cwd the builtin bash tool
-    // 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(createValveToolDefinition(nodeId, contextDir, ctx.cwd, readConfig('user').bash_tool_purpose));
-    });
-}
+var ne=Object.defineProperty;var t=(n,r)=>ne(n,"name",{value:r,configurable:!0});import{envBashAutoBgDeadlineMs as re,envBashValveMs as te,envNodeId as oe}from"../shared/env.js";import{spawn as ie}from"node:child_process";import{closeSync as se,existsSync as S,mkdirSync as U,openSync as ae,readFileSync as ce,readSync as de,rmSync as F,statSync as G,writeFileSync as g}from"node:fs";import{homedir as ue}from"node:os";import{dirname as fe}from"node:path";import{performance as _}from"node:perf_hooks";import{backgroundBashJob as H,bashJobPaths as le,cancelBashJobProcessTree as V,formatBashElapsed as K,newBashJobId as pe,normalizeBashJobPurpose as be,readBashNiceness as he,writeJobDeadlineMs as me}from"../core/bash-jobs.js";import{bashCommandRefusal as ge}from"../core/bash-guard.js";import{capturePidIdentities as $e}from"../core/canvas/pid.js";import{readConfig as we}from"../core/config.js";import{PREVIEW_RESULT_PATH_ENV as Se,previewResultPath as ye}from"../core/preview-result-path.js";import{resolveAdmittedHostCommand as Ee}from"../core/runtime/spawn-env.js";import{Type as C}from"typebox";import{createBashToolDefinition as z}from"@earendil-works/pi-coding-agent";const ve=200;function Ie(){return te()}t(Ie,"resolveValveMs");const je=10*1024*1024,ke=`
+[background bash job output truncated at 10 MiB; remaining output discarded]
+`,xe=['const fs = require("node:fs");',`const cap = ${je};`,`const marker = Buffer.from(${JSON.stringify(ke)});`,"const prefixCap = cap - marker.length;",'const fd = fs.openSync(process.argv[1], "w");',"let written = 0;","let truncated = false;",'process.stdin.on("data", (chunk) => {',"  if (truncated) return;","  const available = prefixCap - written;","  if (available > 0) {","    const prefix = chunk.subarray(0, available);","    fs.writeSync(fd, prefix);","    written += prefix.length;","    if (prefix.length === chunk.length) return;","  }","  fs.writeSync(fd, marker);","  truncated = true;","});",'process.stdin.on("end", () => fs.closeSync(fd));'].join(" "),Be=["SECONDS=0","n=$(command -v nice)",'${n:+"$n" -n "${10}"} "${9}" "$1" 2>&1 | "${11}" -e '+JSON.stringify(xe)+' "$2"',"ec=${PIPESTATUS[0]}","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) after $el. Log: $2  Command: $1" --to "$8" --tier urgent || true',"fi"].join(`
+`);function Le(n){return le(n,pe())}t(Le,"makeJobPaths");const j=new Set;let q=!1;function W(){for(const n of[...j])try{H(n),j.delete(n)}catch(r){process.stderr.write(`crtr: failed to background bash job ${n.jobId} during broker termination: ${r.message}
+`)}}t(W,"backgroundLiveJobsForTermination");function Re(){q||(q=!0,process.prependListener("SIGTERM",W),process.platform!=="win32"&&process.prependListener("SIGHUP",W))}t(Re,"installTerminationHandoff");const _e=64*1024;function T(n,r,o){let i;try{i=G(n)}catch{return r}if(i.size<=r)return r;const c=ae(n,"r");try{for(;r<i.size;){const h=Math.min(_e,i.size-r),u=Buffer.allocUnsafe(h),a=de(c,u,0,h,r);if(a===0)break;o(u.subarray(0,a)),r+=a}return r}finally{se(c)}}t(T,"tailOnce");function $(n){try{F(n,{recursive:!0,force:!0})}catch{}}t($,"cleanupJobDir");function Ce(n){try{const r=ce(n,"utf8").trim(),o=Number(r);return Number.isFinite(o)?o:null}catch{return null}}t(Ce,"readExitCode");function Te(n){try{if(G(n).isDirectory())return{cwd:n}}catch{}const r=ue();return{cwd:r,warning:`[working directory no longer exists: ${n}; running from ${r}]
+`}}t(Te,"resolveExecutionCwd");function X(n,r,o=()=>null,i){return{exec:t((c,h,{onData:u,signal:a,timeout:l,env:k})=>new Promise((y,f)=>{const E=o();if(a?.aborted){f(new Error("aborted"));return}const x=ge(c,h);if(x!==null){f(new Error(x));return}const e=Le(r);U(e.dir,{recursive:!0}),g(e.cmdSh,c),g(e.jobLog,""),g(e.jobRun,""),E!==null&&g(e.jobPurpose,E);let m=0,O=!1,d,p;const P=_.now(),Y=Ie();let B;const Q=t(()=>{B&&clearInterval(B),a&&a.removeEventListener("abort",N),j.delete(e)},"teardown"),b=t(s=>{O||(O=!0,Q(),s())},"finish");function L(s=!1){const w=K(_.now()-P);let D="";if(s){const J=re();me(e,Date.now()+J),D=`It will be CANCELED in ${K(J)} unless you claim it: crtr node bash extend ${e.jobId} --for <duration> (or --keep to run to completion). `}const ee=`
+[backgrounded as job ${e.jobId} after ${w} in the foreground${s?" (auto)":""}. `+D+`It will interrupt you with a message when it exits. Watch: tail -f ${e.jobLog} ; stop: crtr node bash kill ${e.jobId}]`;u(Buffer.from(ee)),b(()=>y({exitCode:0}))}t(L,"finishBackground");function A(){m=T(e.jobLog,m,u);const s=Ce(e.jobExit);b(()=>y({exitCode:s})),$(e.dir)}t(A,"finishForeground");function Z(s=!1){const w=H(e);if(w==="backgrounded"||w==="already-backgrounded"){L(s);return}if(w==="finished"){A();return}b(()=>f(new Error(`bash job ${e.jobId} disappeared before it could be backgrounded`))),$(e.dir)}t(Z,"requestBackground");function N(){if(m=T(e.jobLog,m,u),S(e.jobBg)){L();return}S(e.jobExit)||(d!==void 0&&p!==void 0&&V(d,p),b(()=>f(new Error("aborted"))),$(e.dir))}t(N,"onAbort"),a&&a.addEventListener("abort",N,{once:!0});const v=Te(h);v.warning&&u(Buffer.from(v.warning));let I=k??process.env;i!==void 0&&(U(fe(i),{recursive:!0}),F(i,{force:!0}),I={...I,[Se]:i});const M=Ee("bash",I,v.cwd),R=ie(M,["-c",Be,"--",e.cmdSh,e.jobLog,e.jobExit,e.jobRun,e.jobDone,e.jobBg,e.jobId,n,M,String(he(r)),process.execPath],{cwd:v.cwd,detached:!0,stdio:"ignore",env:I});if(R.on("error",s=>{b(()=>f(s)),$(e.dir)}),d=R.pid,d!==void 0){if(p=$e([d])?.get(d),p===void 0){try{process.kill(-d,"SIGKILL")}catch{}b(()=>f(new Error(`bash job ${e.jobId} started without a process identity`))),$(e.dir);return}g(e.jobPgid,String(d)),g(e.jobPgidIdentity,p),j.add(e)}R.unref(),B=setInterval(()=>{if(m=T(e.jobLog,m,u),S(e.jobDone)){A();return}if(S(e.jobBg)){L();return}if(S(e.jobExit))return;const s=_.now()-P;if(l!==void 0&&l>0){s>=l*1e3&&(d!==void 0&&p!==void 0&&V(d,p),b(()=>f(new Error(`timeout:${l}`))),$(e.dir));return}s>=Y&&Z(!0)},ve)}),"exec")}}t(X,"createValveOperations");const Oe=["One short clause naming what this step is FOR, in the words of the person you",'are working for \u2014 "Reading the Acme thread", not "Fetching emails" and never','"Running GMAIL_FETCH_EMAILS". A person reads this while the command runs; it',"is the only thing they see of this step. Under about eight words. Omit it for","steps that only touch your own scratch work."].join(" ");function Pe(n){return{...n,parameters:C.Object({purpose:C.Optional(C.String({description:Oe})),...n.parameters.properties})}}t(Pe,"withPurpose");function Ae(n,r,o,i){const c=z(o,{operations:X(n,r)});return{...i?Pe(c):c,execute:t((a,l,k,y,f)=>{const E=i?be(l.purpose):null;return z(o,{operations:X(n,r,()=>E,ye(a))}).execute(a,l,k,y,f)},"execute")}}t(Ae,"createValveToolDefinition");function Ne(n){const r=oe();if(r===void 0||r.trim()==="")return;const o=process.env.CRTR_CONTEXT_DIR;o===void 0||o.trim()===""||(Re(),n.on("session_start",(i,c)=>{n.registerTool(Ae(r,o,c.cwd,we("user").bash_tool_purpose))}))}t(Ne,"default");export{ke as BACKGROUND_BASH_LOG_TRUNCATION_MARKER,je as MAX_BACKGROUND_BASH_LOG_BYTES,X as createValveOperations,Ae as createValveToolDefinition,Ne as default};

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

@@ -1,113 +1,2 @@
-// canvas-context-intro.ts — pi extension for pi-native canvas agent nodes.
-//
-// Loaded into every canvas node's pi process via the node's launch.extensions
-// list. INERT when CRTR_NODE_ID is absent (plain pi session or legacy job agent).
-//
-// At session_start, before the first response, this assembles the context-owned
-// memory state. A fresh branch receives full bearings, while a copied crouter
-// branch with known transcript provenance receives compact node bearings.
-//
-// The active branch owns the idempotency stamp. A new cycle has no current-node
-// stamp and receives a new baseline. The preference snapshot and persona
-// acknowledgment persist only after Pi materializes that baseline.
-//
-// 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 { envNodeId } from '../shared/env.js';
-import { CONTEXT_INTRO_CUSTOM_TYPE, formatCard } from '../shared/generated-context.js';
-import { brokerExtensionState } from '../core/runtime/broker/daemon-ops.js';
-import { buildContextBearingsFromState, buildForkBearingsFromState, buildProjectContextBlockForBroker, renderPreferencesFromState, } from '../core/runtime/broker-extension-render.js';
-import { acknowledgePersonaBaseline } from '../core/runtime/broker-persona-guidance.js';
-import { situationalContextEnvelope } from '../core/runtime/situational-context.js';
-import { clearContextExposureState, cloneTranscriptExposureState, emptyContextExposureState, exposureTarget, freezePreferenceSnapshot, hasTranscriptExposure, loadContextExposureState, replaceContextExposureState, saveContextExposureState, sharedContextExposureState, } from '../core/substrate/injected-store.js';
-import { clearSessionCache } from '../core/substrate/session-cache.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
- *  live delivery needs it too; re-exported here as this module's own surface. */
-export { CONTEXT_INTRO_CUSTOM_TYPE };
-// Block builder
-/** Build the full bearings baseline for a conversation without inherited
- *  crouter context. Exported for testing. */
-export async function buildContextIntro(nodeId, target) {
-    const state = await brokerExtensionState(nodeId);
-    return buildContextBearingsFromState(state, buildProjectContextBlockForBroker(state.node.cwd), situationalContextEnvelope(nodeId) ?? '', target);
-}
-/** Build the compact node-scoped update for a fork whose copied branch already
- *  carries a full crouter baseline. Exported for testing. */
-export async function buildForkContextIntro(nodeId) {
-    const state = await brokerExtensionState(nodeId);
-    return buildForkBearingsFromState(state, situationalContextEnvelope(nodeId) ?? '');
-}
-// Message extraction
-/** Plain text of a session entry's content (string or text blocks), '' when
- *  absent. Used by the idempotency guard to tell OUR own injected bearings
- *  (which name our node id) from a SOURCE's bearings copied in by `--fork-from`. */
-function entryText(e) {
-    const c = e.content;
-    if (typeof c === 'string')
-        return c;
-    if (Array.isArray(c)) {
-        return c
-            .filter((b) => typeof b?.text === 'string')
-            .map((b) => b.text)
-            .join('\n');
-    }
-    return '';
-}
-// Extension
-/** Register new-context baseline assembly; a strict resume changes nothing. */
-export function registerCanvasContextIntro(pi) {
-    pi.on('session_start', async (event, ctx) => {
-        const nodeId = envNodeId();
-        if (nodeId === undefined || nodeId.trim() === '')
-            return;
-        const reason = event?.reason;
-        // Warm spares have no claimant yet. Their claim path delivers the full
-        // baseline after assigning the real persona, profile, and working directory.
-        const state = await brokerExtensionState(nodeId);
-        if (state.warm_spare)
-            return;
-        // A root's in-process /new branch is provisional: stophook has already asked
-        // crtrd to relaunch it. The replacement broker owns the new baseline.
-        if (reason === 'new' && state.node.parent === null)
-            return;
-        if (reason === 'new') {
-            clearContextExposureState(nodeId);
-            clearSessionCache();
-        }
-        // 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.
-        const contextEntries = ctx.sessionManager.getBranch().filter((e) => e.type === 'custom_message' && e.customType === CONTEXT_INTRO_CUSTOM_TYPE);
-        const ours = contextEntries.some((e) => e.details?.nodeId === nodeId || entryText(e).includes(nodeId));
-        if (ours)
-            return;
-        const persisted = loadContextExposureState(nodeId);
-        const compact = contextEntries.length > 0 && hasTranscriptExposure(persisted);
-        const next = compact
-            ? cloneTranscriptExposureState(persisted)
-            : emptyContextExposureState();
-        const content = compact
-            ? buildForkBearingsFromState(state, situationalContextEnvelope(nodeId) ?? '')
-            : buildContextBearingsFromState(state, buildProjectContextBlockForBroker(state.node.cwd), situationalContextEnvelope(nodeId) ?? '', exposureTarget(next, 'transcript'));
-        freezePreferenceSnapshot(next, renderPreferencesFromState(state, exposureTarget(next, 'system')));
-        const messageContent = formatCard('bearings', {}, content);
-        pi.sendMessage({
-            customType: CONTEXT_INTRO_CUSTOM_TYPE,
-            content: messageContent,
-            display: true,
-            details: { nodeId },
-        });
-        const delivered = ctx.sessionManager.getBranch().some((entry) => entry.type === 'custom_message'
-            && entry.customType === CONTEXT_INTRO_CUSTOM_TYPE
-            && entry.details?.nodeId === nodeId
-            && entryText(entry) === messageContent);
-        if (!delivered)
-            throw new Error(`Pi did not materialize the context baseline for ${nodeId}`);
-        const live = sharedContextExposureState(nodeId);
-        replaceContextExposureState(live, next);
-        saveContextExposureState(nodeId, live);
-        await acknowledgePersonaBaseline(state);
-    });
-}
-export default registerCanvasContextIntro;
+var h=Object.defineProperty;var a=(t,o)=>h(t,"name",{value:o,configurable:!0});import{envNodeId as b}from"../shared/env.js";import{CONTEXT_INTRO_CUSTOM_TYPE as c,formatCard as v}from"../shared/generated-context.js";import{brokerExtensionState as u}from"../core/runtime/broker/daemon-ops.js";import{buildContextBearingsFromState as g,buildForkBearingsFromState as E,buildProjectContextBlockForBroker as S,renderPreferencesFromState as B}from"../core/runtime/broker-extension-render.js";import{acknowledgePersonaBaseline as _}from"../core/runtime/broker-persona-guidance.js";import{situationalContextEnvelope as p}from"../core/runtime/situational-context.js";import{clearContextExposureState as k,cloneTranscriptExposureState as F,emptyContextExposureState as I,exposureTarget as y,freezePreferenceSnapshot as P,hasTranscriptExposure as M,loadContextExposureState as N,replaceContextExposureState as O,saveContextExposureState as j,sharedContextExposureState as z}from"../core/substrate/injected-store.js";import{clearSessionCache as A}from"../core/substrate/session-cache.js";async function Q(t,o){const n=await u(t);return g(n,S(n.node.cwd),p(t)??"",o)}a(Q,"buildContextIntro");async function V(t){const o=await u(t);return E(o,p(t)??"")}a(V,"buildForkContextIntro");function w(t){const o=t.content;return typeof o=="string"?o:Array.isArray(o)?o.filter(n=>typeof n?.text=="string").map(n=>n.text).join(`
+`):""}a(w,"entryText");function R(t){t.on("session_start",async(o,n)=>{const e=b();if(e===void 0||e.trim()==="")return;const m=o?.reason,s=await u(e);if(s.warm_spare||m==="new"&&s.node.parent===null)return;m==="new"&&(k(e),A());const d=n.sessionManager.getBranch().filter(r=>r.type==="custom_message"&&r.customType===c);if(d.some(r=>r.details?.nodeId===e||w(r).includes(e)))return;const x=N(e),f=d.length>0&&M(x),i=f?F(x):I(),T=f?E(s,p(e)??""):g(s,S(s.node.cwd),p(e)??"",y(i,"transcript"));P(i,B(s,y(i,"system")));const l=v("bearings",{},T);if(t.sendMessage({customType:c,content:l,display:!0,details:{nodeId:e}}),!n.sessionManager.getBranch().some(r=>r.type==="custom_message"&&r.customType===c&&r.details?.nodeId===e&&w(r)===l))throw new Error(`Pi did not materialize the context baseline for ${e}`);const C=z(e);O(C,i),j(e,C),await _(s)})}a(R,"registerCanvasContextIntro");var W=R;export{c as CONTEXT_INTRO_CUSTOM_TYPE,Q as buildContextIntro,V as buildForkContextIntro,W as default,R as registerCanvasContextIntro};