@north-light/crouter 0.3.217 → 0.3.218

package/dist/daemon/api/handlers/nodes.js

@@ -7,12 +7,13 @@
 //
 // `{id}` is the target node.
 import { readdirSync } from 'node:fs';
-import { resolve } from 'node:path';
+import { basename, resolve } from 'node:path';
 import { appendSituationalContext, closeNode, getNode, listNodes, nowIso, reviveNode, } from '../../../index.js';
 import { formatSituationalProse } from '../../../core/runtime/situational-context.js';
 import { assertLaunchModelRegistered, forkNode, resolveProfileId, spawnChild } from '../../../core/runtime/spawn.js';
 import { childrenOf, subscribersOf, subscriptionsOf, setMessageWait, updateNode } from '../../../core/canvas/canvas.js';
 import { subtreeIds } from '../../../core/canvas/nav-model.js';
+import { ticketCountsForNodes } from '../../../core/canvas/attention.js';
 import { contextDir, reportsDir } from '../../../core/canvas/paths.js';
 import { nodeArtifacts } from '../../../core/canvas/history.js';
 import { readNodeMessagesPage, readNodeSession, readNodeSnapshot, transcriptMarkdown } from '../../../core/runtime/node-read.js';
@@ -34,6 +35,7 @@ import { writeOutputSchema } from '../../../core/runtime/structured-output.js';
 import { claimWarmNode, refillWarmPool, warmPoolEnabled } from '../../../core/runtime/warm-pool.js';
 import { assertProfileActive, profileHome } from '../../../core/profiles/manifest.js';
 import { fullName } from '../../../core/canvas/labels.js';
+import { reportsForNode } from './reports.js';
 import { getCron } from '../../../core/canvas/crons.js';
 import { cronWakeOrigin } from '../../../core/runtime/bearings.js';
 import { notFound, usage } from '../../../core/errors.js';
@@ -266,26 +268,106 @@ export async function handleCreate(ctx, deps = {}) {
 // ---------------------------------------------------------------------------
 // GET /v1/nodes — list (filters) ; GET /v1/nodes/{id} — detail
 // ---------------------------------------------------------------------------
-function handleList(ctx) {
-    const status = ctx.query.get('status');
-    const kind = ctx.query.get('kind');
-    const mode = ctx.query.get('mode');
-    const under = ctx.query.get('under');
-    const hanging = ctx.query.get('hanging');
-    let rows = status !== null ? listNodes({ status }) : listNodes();
-    if (kind !== null)
-        rows = rows.filter((r) => r.kind === kind);
-    if (mode !== null)
-        rows = rows.filter((r) => r.mode === mode);
-    if (under !== null) {
-        const scope = new Set(subtreeIds(under));
-        rows = rows.filter((r) => scope.has(r.node_id));
+function singleQueryValue(ctx, name) {
+    const values = ctx.query.getAll(name);
+    if (values.length > 1)
+        throw usage(`${name} must appear at most once`);
+    return values[0];
+}
+function optionalBoolean(value, name) {
+    if (value === undefined)
+        return undefined;
+    if (value === '1' || value === 'true')
+        return true;
+    if (value === '0' || value === 'false')
+        return false;
+    throw usage(`${name} must be true or false`);
+}
+function oneOf(value, name, allowed) {
+    if (value === undefined)
+        return undefined;
+    if (allowed.includes(value))
+        return value;
+    throw usage(`${name} must be one of: ${allowed.join(', ')}`);
+}
+function parseListQuery(ctx) {
+    const allowed = new Set([
+        'status', 'lifecycle', 'kind', 'mode', 'profile_id', 'profile_prefix',
+        'parent', 'top_level', 'under', 'hanging', 'include',
+    ]);
+    for (const [name] of ctx.query) {
+        if (!allowed.has(name))
+            throw usage(`unknown nodes query parameter: ${name}`);
     }
-    if (hanging === '1' || hanging === 'true') {
-        // A dangling manager edge: a non-root whose recorded parent is gone.
-        rows = rows.filter((r) => r.parent !== null && getNode(r.parent) === null);
+    const status = oneOf(singleQueryValue(ctx, 'status'), 'status', ['active', 'idle', 'done', 'dead', 'canceled']);
+    const lifecycle = oneOf(singleQueryValue(ctx, 'lifecycle'), 'lifecycle', ['terminal', 'resident']);
+    const kind = singleQueryValue(ctx, 'kind');
+    const mode = oneOf(singleQueryValue(ctx, 'mode'), 'mode', ['base', 'orchestrator']);
+    const profileId = singleQueryValue(ctx, 'profile_id');
+    const profilePrefix = singleQueryValue(ctx, 'profile_prefix');
+    const parent = singleQueryValue(ctx, 'parent');
+    const topLevel = optionalBoolean(singleQueryValue(ctx, 'top_level'), 'top_level');
+    const under = singleQueryValue(ctx, 'under');
+    const hanging = optionalBoolean(singleQueryValue(ctx, 'hanging'), 'hanging');
+    const include = oneOf(singleQueryValue(ctx, 'include'), 'include', ['activity']);
+    if (parent !== undefined && topLevel === true) {
+        throw usage('parent and top_level=true cannot be combined');
     }
-    const body = rows.map(toNodeSummaryDTO);
+    return {
+        ...(status !== undefined ? { status } : {}),
+        ...(lifecycle !== undefined ? { lifecycle } : {}),
+        ...(kind !== undefined ? { kind } : {}),
+        ...(mode !== undefined ? { mode } : {}),
+        ...(profileId !== undefined ? { profile_id: profileId } : {}),
+        ...(profilePrefix !== undefined ? { profile_prefix: profilePrefix } : {}),
+        ...(parent !== undefined ? { parent } : {}),
+        ...(topLevel !== undefined ? { top_level: topLevel } : {}),
+        ...(under !== undefined ? { under } : {}),
+        ...(hanging !== undefined ? { hanging } : {}),
+        ...(include !== undefined ? { include: include } : {}),
+    };
+}
+export function handleList(ctx) {
+    const query = parseListQuery(ctx);
+    let rows = query.status !== undefined ? listNodes({ status: query.status }) : listNodes();
+    if (query.lifecycle !== undefined)
+        rows = rows.filter((row) => row.lifecycle === query.lifecycle);
+    if (query.kind !== undefined)
+        rows = rows.filter((row) => row.kind === query.kind);
+    if (query.mode !== undefined)
+        rows = rows.filter((row) => row.mode === query.mode);
+    if (query.profile_id !== undefined)
+        rows = rows.filter((row) => row.profile_id === query.profile_id);
+    if (query.profile_prefix !== undefined)
+        rows = rows.filter((row) => row.profile_id?.startsWith(query.profile_prefix));
+    if (query.parent !== undefined)
+        rows = rows.filter((row) => row.parent === query.parent);
+    if (query.top_level === true)
+        rows = rows.filter((row) => row.parent === null);
+    if (query.under !== undefined) {
+        const scope = new Set(subtreeIds(query.under));
+        rows = rows.filter((row) => scope.has(row.node_id));
+    }
+    if (query.hanging === true) {
+        rows = rows.filter((row) => row.parent !== null && getNode(row.parent) === null);
+    }
+    const counts = query.include === 'activity'
+        ? ticketCountsForNodes(rows.map((row) => row.node_id))
+        : null;
+    const body = rows.map((row) => {
+        const node = toNodeSummaryDTO(row);
+        if (counts !== null) {
+            const reports = reportsForNode(row.node_id);
+            node.activity = {
+                latest_report: reports[0] ?? null,
+                final_report: row.final_report === null
+                    ? null
+                    : reports.find((report) => basename(report.path) === row.final_report) ?? null,
+                pending_human_count: counts[row.node_id] ?? 0,
+            };
+        }
+        return node;
+    });
     return { status: 200, body };
 }
 function handleDetail(ctx) {

package/dist/daemon/api/handlers/reports.d.ts

@@ -1,2 +1,6 @@
+import type { ReportDTO } from '../../../api/index.js';
 import type { RouteTable } from '../router.js';
+/** Read one node's pushed reports, newest first. This stays in the daemon so
+ * collection projections can include report activity without client-side N+1s. */
+export declare function reportsForNode(id: string): ReportDTO[];
 export declare const reportRoutes: RouteTable;

package/dist/daemon/api/handlers/reports.js

@@ -110,12 +110,9 @@ function compactToIso(stamp) {
     const m = stamp.match(/^(\d{4})(\d{2})(\d{2})T(\d{2})(\d{2})(\d{2})$/);
     return m === null ? stamp : `${m[1]}-${m[2]}-${m[3]}T${m[4]}:${m[5]}:${m[6]}`;
 }
-function handleList(ctx) {
-    const id = ctx.params['id'];
-    requireNode(id);
-    const tierFilter = ctx.query.get('tier');
-    const limitRaw = ctx.query.get('limit');
-    const limit = limitRaw !== null ? Number(limitRaw) : undefined;
+/** Read one node's pushed reports, newest first. This stays in the daemon so
+ * collection projections can include report activity without client-side N+1s. */
+export function reportsForNode(id) {
     const dir = reportsDir(id);
     let files;
     try {
@@ -136,9 +133,18 @@ function handleList(ctx) {
             (m ? compactToIso(m[1]) : new Date(statSync(abs).mtimeMs).toISOString());
         reports.push({ path: abs, tier, body: body.trim(), created });
     }
-    // Newest first, then apply the optional tier + limit filters.
     reports.sort((a, b) => (a.created < b.created ? 1 : a.created > b.created ? -1 : 0));
-    let out = tierFilter !== null ? reports.filter((r) => r.tier === tierFilter) : reports;
+    return reports;
+}
+function handleList(ctx) {
+    const id = ctx.params['id'];
+    requireNode(id);
+    const tierFilter = ctx.query.get('tier');
+    const limitRaw = ctx.query.get('limit');
+    const limit = limitRaw !== null ? Number(limitRaw) : undefined;
+    let out = reportsForNode(id);
+    if (tierFilter !== null)
+        out = out.filter((report) => report.tier === tierFilter);
     if (limit !== undefined && Number.isFinite(limit) && limit >= 0)
         out = out.slice(0, limit);
     return { status: 200, body: out };

package/dist/daemon/crtrd.js

@@ -62,7 +62,7 @@ import { StorageMaintenanceReconciler } from './reconcilers/storage-maintenance.
 import { captureLivenessSnapshot, capturePidCommand, captureTeardownSnapshot, isPidAlive, killProcessTreePids, } from '../core/canvas/pid.js';
 import { bindFleet, boundFleet } from '../core/runtime/fleet.js';
 import { bindDaemonControl, clearDaemonControl } from './control.js';
-import { spawnDaemon } from './manage.js';
+import { execDaemon, spawnDaemon } from './manage.js';
 import { reconcileAndMigrateBoot } from '../core/canvas/boot.js';
 import { resolveInstallId } from '../core/canvas/install-id.js';
 import { setInstallId } from '../core/runtime/nodes.js';
@@ -480,11 +480,10 @@ export async function runDaemon(opts = {}) {
         }, HANDOVER_ACK_GRACE_MS);
         return { graceMs: HANDOVER_ACK_GRACE_MS };
     }
-    /** Quiesce exactly as a SIGTERM would, then spawn the successor and exit.
+    /** Quiesce exactly as a SIGTERM would, then start the successor.
      *  Ordering is forced: the successor's claim can only be won after this
-     *  daemon has released its own, so teardown strictly precedes the spawn. The
-     *  successor resolves its entry through `runtime/selected`, which is how it
-     *  picks up a generation this process never loaded. */
+     *  daemon has released its own. PID 1 is replaced in place so a container
+     *  does not stop between daemon generations; ordinary hosts spawn and exit. */
     async function performHandover() {
         try {
             await requestCleanup();
@@ -495,6 +494,9 @@ export async function runDaemon(opts = {}) {
             process.exit(1);
         }
         try {
+            if (process.pid === 1) {
+                await execDaemon();
+            }
             const spawned = await spawnDaemon();
             operationIdContext.fresh(() => {
                 emitEvent({

package/dist/daemon/manage.d.ts

@@ -36,6 +36,9 @@ export declare function findDaemonPids(): number[];
  *  reaped. Best-effort throughout: a pid that dies between enumeration and signal
  *  just no-ops. */
 export declare function sweepStrayDaemons(keepPid: number | null): number[];
+/** Replace PID 1 with the selected daemon generation. Docker keeps a container
+ *  alive only while PID 1 lives, so a handover there must preserve its pid. */
+export declare function execDaemon(): Promise<never>;
 export interface SpawnDaemonResult {
     /** True when a new daemon process was spawned. */
     started: boolean;

package/dist/daemon/manage.js

@@ -190,6 +190,20 @@ export function sweepStrayDaemons(keepPid) {
     }
     return strays;
 }
+// ---------------------------------------------------------------------------
+// daemon launch — low-level spawn/exec
+// ---------------------------------------------------------------------------
+/** Replace PID 1 with the selected daemon generation. Docker keeps a container
+ *  alive only while PID 1 lives, so a handover there must preserve its pid. */
+export async function execDaemon() {
+    const execve = process.execve;
+    if (execve === undefined) {
+        throw new Error(`this Node.js ${process.version} runtime cannot replace PID 1 with the successor daemon`);
+    }
+    const executable = hostExecPath();
+    const launchArgs = await resolveDaemonLaunch();
+    return execve(executable, [executable, ...launchArgs, '--canvas-home', crtrHome()], sanitizedDaemonEnv());
+}
 // Daemon lifecycle transitions are bounded so callers never claim a state
 // change before the pidfile and process liveness agree.
 //

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

@@ -4,9 +4,10 @@ import type { ExtensionAPI } from '@earendil-works/pi-coding-agent';
  *  not open with a sleep (or its duration isn't statically knowable). */
 export declare function leadingSleepSeconds(command: string): number | null;
 /** The valve's BashOperations backend. Each tool execution closes over its own
- * `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;
+ * `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 declare function createValveOperations(nodeId: string, contextDir: string, takePurpose?: () => string | null, previewPath?: string): 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

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

@@ -27,8 +27,10 @@
 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 { backgroundBashJob, bashJobPaths, formatBashElapsed, newBashJobId, normalizeBashJobPurpose } from '../core/bash-jobs.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';
@@ -218,9 +220,10 @@ function resolveExecutionCwd(cwd) {
     };
 }
 /** The valve's BashOperations backend. Each tool execution closes over its own
- * `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 function createValveOperations(nodeId, contextDir, takePurpose = () => null) {
+ * `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) => {
@@ -309,12 +312,20 @@ export function createValveOperations(nodeId, contextDir, takePurpose = () => nu
                 const execution = resolveExecutionCwd(cwd);
                 if (execution.warning)
                     onData(Buffer.from(execution.warning));
-                const shellPath = resolveAdmittedHostCommand('bash', env ?? process.env, execution.cwd);
+                // 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 });
+                    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], {
                     cwd: execution.cwd,
                     detached: true,
                     stdio: 'ignore',
-                    env: env ?? process.env,
+                    env: childEnv,
                 });
                 child.on('error', (err) => {
                     finish(() => reject(err));
@@ -418,7 +429,9 @@ export function createValveToolDefinition(nodeId, contextDir, cwd, exposePurpose
     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) });
+        const definition = createBashToolDefinition(cwd, {
+            operations: createValveOperations(nodeId, contextDir, () => purpose, previewResultPath(toolCallId)),
+        });
         return definition.execute(toolCallId, params, signal, onUpdate, ctx);
     };
     return { ...schemaDefinition, execute };

package/dist/pi-extensions/canvas-preview-result.d.ts

@@ -1,17 +1,9 @@
-interface ToolCallEvent {
-    toolName: string;
-    toolCallId: string;
-    input: {
-        command?: string;
-    };
-}
 interface ToolResultEvent {
     toolName: string;
     toolCallId: string;
     details?: Record<string, unknown>;
 }
 interface PiLike {
-    on(event: 'tool_call', handler: (event: ToolCallEvent) => void): void;
     on(event: 'tool_result', handler: (event: ToolResultEvent) => {
         details: Record<string, unknown>;
     } | void): void;

package/dist/pi-extensions/canvas-preview-result.js

@@ -1,13 +1,13 @@
 // canvas-preview-result.ts — private structured result transport for crtr bash calls.
 //
 // A crtr leaf returns a record, but the CLI normally renders that record to
-// stdout for the agent. stdout is model context, so this hook assigns every
-// bash call a private file, lets crtr atomically mirror its record there, then
-// attaches the record to Pi's ToolResult.details. The attach viewer can render
-// a structured preview without parsing the agent-facing text.
-import { existsSync, mkdirSync, readFileSync, rmSync } from 'node:fs';
-import { tmpdir } from 'node:os';
-import { join } from 'node:path';
+// stdout for the agent. stdout is model context, so the bash valve hands every
+// bash call a private file path in the child environment, crtr atomically
+// mirrors its record there, and this hook attaches the record to Pi's
+// ToolResult.details. The attach viewer can render a structured preview
+// without parsing the agent-facing text.
+import { existsSync, readFileSync, rmSync } from 'node:fs';
+import { previewResultPath } from '../core/preview-result-path.js';
 function isPreviewRecord(value) {
     if (value === null || typeof value !== 'object' || typeof value['path'] !== 'string')
         return false;
@@ -21,24 +21,10 @@ function isPreviewRecord(value) {
 export function registerCanvasPreviewResult(pi) {
     if (process.env['CRTR_NODE_ID'] === undefined || process.env['CRTR_NODE_ID'] === '')
         return;
-    const directory = join(tmpdir(), 'crouter-preview-results');
-    const paths = new Map();
-    pi.on('tool_call', (event) => {
-        if (event.toolName !== 'bash' || typeof event.input.command !== 'string')
-            return;
-        mkdirSync(directory, { recursive: true });
-        const path = join(directory, `${encodeURIComponent(event.toolCallId)}.json`);
-        paths.set(event.toolCallId, path);
-        // Export before the complete script rather than prefixing its first simple
-        // command: agent bash calls routinely start with `cd … &&`, a compound
-        // statement, or setup commands before crtr itself.
-        event.input.command = `export CRTR_PREVIEW_RESULT_PATH=${JSON.stringify(path)}\n${event.input.command}`;
-    });
     pi.on('tool_result', (event) => {
-        const path = paths.get(event.toolCallId);
-        if (path === undefined)
+        if (event.toolName !== 'bash')
             return;
-        paths.delete(event.toolCallId);
+        const path = previewResultPath(event.toolCallId);
         if (!existsSync(path))
             return;
         try {

package/dist/types.d.ts

@@ -27,6 +27,33 @@ export interface PluginBundle {
     endpoint: string;
     authEnv?: string;
 }
+export type MemoryExtensionScalar = string | boolean | number;
+export type MemoryExtensionFieldType = 'boolean' | 'string' | 'number' | 'enum';
+interface MemoryExtensionDeclarationBase {
+    write_help: string;
+    edit_help: string;
+}
+export interface BooleanMemoryExtensionDeclaration extends MemoryExtensionDeclarationBase {
+    type: 'boolean';
+    default?: boolean;
+}
+export interface StringMemoryExtensionDeclaration extends MemoryExtensionDeclarationBase {
+    type: 'string';
+    default?: string;
+}
+export interface NumberMemoryExtensionDeclaration extends MemoryExtensionDeclarationBase {
+    type: 'number';
+    default?: number;
+}
+export interface EnumMemoryExtensionDeclaration extends MemoryExtensionDeclarationBase {
+    type: 'enum';
+    values: string[];
+    default?: string;
+}
+export type MemoryExtensionDeclaration = BooleanMemoryExtensionDeclaration | StringMemoryExtensionDeclaration | NumberMemoryExtensionDeclaration | EnumMemoryExtensionDeclaration;
+/** Field declarations owned by one plugin manifest. The plugin's `name` is
+ * the namespace; keys here are its lowercase kebab-case local field names. */
+export type MemoryExtensionDeclarations = Record<string, MemoryExtensionDeclaration>;
 export interface PluginManifest {
     name: string;
     version?: string;
@@ -47,6 +74,9 @@ 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>>;
+    /** Plugin-owned typed metadata declarations for memory document frontmatter.
+     * Values live at `extensions.<this manifest name>.<field>`. */
+    memory_extensions?: MemoryExtensionDeclarations;
     /** 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`
@@ -446,3 +476,4 @@ export declare function defaultRemoteCanvasConfig(): RemoteCanvasConfig;
 export declare function defaultKindsConfig(): Record<string, KindConfig>;
 export declare function defaultModelLaddersConfig(): ModelLaddersConfig;
 export declare function defaultScopeState(): ScopeState;
+export {};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@north-light/crouter",
-  "version": "0.3.217",
+  "version": "0.3.218",
   "description": "crtr — agent runtime with memory, plugins, and marketplaces",
   "type": "module",
   "main": "dist/index.js",

package/runtime.lock.json

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