@north-light/crouter 0.3.262 → 0.3.269

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

@@ -0,0 +1,77 @@
+// canvas-stamp.ts — the sole writer of `crtr-stamp` entries.
+//
+// Two records land in the session jsonl. A SESSION stamp names the node and the
+// crtr release that own the file, appended at session start only when the
+// latest one on disk disagrees — which covers a fresh session, a fork (whose
+// copied history still carries the source node's stamp), a new cycle, and a
+// runtime upgrade mid-node, without a rule per case. A MESSAGE stamp records
+// where one user message came from, joined to it by the message's own
+// timestamp.
+//
+// Every user message is stamped; an origin appears only when a delivery seam
+// announced one (absence means unknown, never a guess). An assistant message is
+// stamped only when an `ext` contribution is pending, so an ordinary turn costs
+// no line.
+//
+// Ordering note: pi runs message_end handlers BEFORE it persists the finalized
+// message, so the stamp is written as that message's structural parent. The
+// join is by `msgTs`, so tree position carries no meaning here.
+import { envNodeId } from '../shared/env.js';
+import { crtrVersion } from '../shared/crtr-version.js';
+import { claimMessageOrigin, drainStampExt, hasPendingStampExt, } from '../core/runtime/stamp/channel.js';
+import { CRTR_STAMP_CUSTOM_TYPE, latestSessionStamp, STAMP_SCHEMA_VERSION, } from '../core/runtime/stamp/protocol.js';
+/** Plain text of a message's content (string or content blocks). */
+function messageText(content) {
+    if (typeof content === 'string')
+        return content;
+    if (Array.isArray(content)) {
+        return content
+            .filter((block) => typeof block === 'object' && block !== null && typeof block.text === 'string')
+            .map((block) => block.text)
+            .join('\n');
+    }
+    return '';
+}
+function envelope(kind, payload) {
+    const ext = drainStampExt();
+    return {
+        v: STAMP_SCHEMA_VERSION,
+        kind,
+        payload,
+        ...(ext === undefined ? {} : { ext }),
+    };
+}
+/** Register the stamp writer. */
+export function registerCanvasStamp(pi) {
+    pi.on('session_start', (_event, ctx) => {
+        const node = envNodeId();
+        if (node === undefined || node.trim() === '')
+            return;
+        const crtr = crtrVersion();
+        const latest = latestSessionStamp(ctx.sessionManager.getEntries());
+        if (latest !== null && latest.payload.node === node && latest.payload.crtr === crtr)
+            return;
+        pi.appendEntry(CRTR_STAMP_CUSTOM_TYPE, envelope('session', { node, crtr }));
+    });
+    pi.on('message_end', (event) => {
+        const message = event?.message;
+        if (message === undefined || message === null)
+            return;
+        if (typeof message.timestamp !== 'number')
+            return;
+        const msgTs = message.timestamp;
+        if (message.role === 'user') {
+            const origin = claimMessageOrigin(messageText(message.content));
+            pi.appendEntry(CRTR_STAMP_CUSTOM_TYPE, envelope('message', {
+                msgTs,
+                ...(origin === null ? {} : { origin }),
+            }));
+            return;
+        }
+        // Any other message earns a line only for a pending contribution.
+        if (!hasPendingStampExt())
+            return;
+        pi.appendEntry(CRTR_STAMP_CUSTOM_TYPE, envelope('message', { msgTs }));
+    });
+}
+export default registerCanvasStamp;

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

@@ -33,6 +33,7 @@ import { activeBackgroundBashJobs } from '../core/bash-jobs.js';
 import { CONTEXT_NUDGE_CUSTOM_TYPE, formatCard } from '../shared/generated-context.js';
 import { isReviewBoundary } from '../core/runtime/session-visibility.js';
 import { runRefreshAbort } from '../core/runtime/broker/extension-abort.js';
+import { announceMessageOrigin } from '../core/runtime/stamp/channel.js';
 /** Condense a tool call into one short line for the activity cue. Picks the most
  *  identifying arg (command / path / pattern / description), collapses whitespace,
  *  and hard-caps the length so a giant bash command can't bloat telemetry.json. */
@@ -271,6 +272,7 @@ export function registerCanvasStophook(pi) {
     };
     const enactSettleDirective = (directive, ctx) => {
         if (directive.action === 'reprompt') {
+            announceMessageOrigin(directive.prompt, { type: 'runtime', kind: 'stop-guard' });
             pi.sendUserMessage(directive.prompt, { deliverAs: 'followUp' });
             return;
         }
@@ -566,6 +568,7 @@ export function registerCanvasStophook(pi) {
                 firedBands.add(at);
                 const note = formatCard('context-nudge', {}, steerNote(at, node.lifecycle, node.mode));
                 if (runContinues) {
+                    announceMessageOrigin(note, { type: 'runtime', kind: 'context-nudge' });
                     pi.sendUserMessage(note, { deliverAs: 'steer' });
                 }
                 else {

package/dist/shared/__tests__/env-boundary.test.js

@@ -17,6 +17,7 @@ const MIGRATED_VARS = [
     'CRTR_PROFILE_ID',
     'CRTR_NODE_CWD',
     'CRTR_MODEL_INTENT',
+    'CRTR_MODEL_EXACT',
     'CRTR_HOME',
     'CRTR_STREAM_WATCHDOG_MS',
     'CRTR_WATCHER_TICK_MS',
@@ -35,6 +36,7 @@ const MIGRATED_VARS = [
     'CRTR_WARN_LIVE_BROKERS',
     'CRTR_TEST_UNATTENDED_PARK_MS',
     'CRTR_TEST_PARK_SUMMARY_GRACE_MS',
+    'CRTR_UNATTENDED_PARK_MS',
 ];
 // Matches `process.env['VAR']`, `process.env.VAR`, or `process.env[\`VAR\`]`
 // for exactly one of MIGRATED_VARS — not a longer name that merely starts
@@ -53,8 +55,8 @@ const EXEMPTIONS = new Map([
     ],
     [
         'core/runtime/broker.ts',
-        "clears CRTR_MODEL_INTENT via `delete process.env[...]` — a mutation, " +
-            'not a read, so it stays here per shared/env.ts\'s header comment.',
+        "clears CRTR_MODEL_INTENT and sets CRTR_MODEL_EXACT via process.env — mutations, " +
+            'not reads, so they stay here per shared/env.ts\'s header comment.',
     ],
 ]);
 function tsFilesUnder(dir) {

package/dist/shared/crtr-version.d.ts

@@ -0,0 +1,2 @@
+/** The running crouter package version (`package.json` `version`). */
+export declare function crtrVersion(): string;

package/dist/shared/crtr-version.js

@@ -0,0 +1,18 @@
+// The installed crtr release string, read once per process from the package
+// manifest. Callers that record a version into durable state (the session
+// stamp) and callers that compare against npm (self-update) read this one
+// implementation.
+import { readFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+let cached = null;
+/** The running crouter package version (`package.json` `version`). */
+export function crtrVersion() {
+    if (cached !== null)
+        return cached;
+    // src|dist/shared/crtr-version.ts → up to src|dist/ → up to pkg root
+    const root = join(dirname(fileURLToPath(import.meta.url)), '..', '..');
+    const parsed = JSON.parse(readFileSync(join(root, 'package.json'), 'utf8'));
+    cached = parsed.version;
+    return cached;
+}

package/dist/shared/env.d.ts

@@ -8,6 +8,8 @@ export declare function envNodeCwd(): string | undefined;
  *  undefined. Cleared (not read) via `delete process.env['CRTR_MODEL_INTENT']`
  *  in `runtime/broker.ts` — a mutation, not a read, so it stays there. */
 export declare function envModelIntent(): string | undefined;
+/** Whether the launch recipe requires this broker to keep its exact provider/model. */
+export declare function envModelExact(): boolean;
 /** The raw `CRTR_HOME` override, unresolved. Use `crtrHome()`
  *  (`core/canvas/paths.ts`) to get the resolved canvas-home path; use this
  *  only when a caller needs the override itself — to check whether one is
@@ -67,6 +69,14 @@ export declare function envWarnLiveBrokers(): number | undefined;
 /** Test-only unattended-park interval override (`CRTR_TEST_UNATTENDED_PARK_MS`),
  *  gated by `envNoDaemonAutostart()` at the call site; no production default. */
 export declare function envTestUnattendedParkMs(): number | undefined;
+/** Production unattended-park interval override (`CRTR_UNATTENDED_PARK_MS`), in
+ *  milliseconds; wins over the user-scope config value
+ *  (`readConfig('user').lifecycle.unattendedParkMs`, itself defaulting to 15
+ *  min) whenever set, autostart or not. Unlike `CRTR_TEST_UNATTENDED_PARK_MS`
+ *  this is not gated on `envNoDaemonAutostart()`: it is the env escape hatch
+ *  above the configured knob a deployment sets to tune how long an eligible
+ *  resident idles before its parking turn. */
+export declare function envUnattendedParkMs(): number | undefined;
 /** Test-only park-summary grace-period override
  *  (`CRTR_TEST_PARK_SUMMARY_GRACE_MS`); no production default. */
 export declare function envTestParkSummaryGraceMs(): number | undefined;

package/dist/shared/env.js

@@ -40,6 +40,10 @@ export function envNodeCwd() {
 export function envModelIntent() {
     return process.env['CRTR_MODEL_INTENT'];
 }
+/** Whether the launch recipe requires this broker to keep its exact provider/model. */
+export function envModelExact() {
+    return process.env['CRTR_MODEL_EXACT'] === '1';
+}
 /** The raw `CRTR_HOME` override, unresolved. Use `crtrHome()`
  *  (`core/canvas/paths.ts`) to get the resolved canvas-home path; use this
  *  only when a caller needs the override itself — to check whether one is
@@ -140,10 +144,11 @@ export function envDebug() {
     return process.env['CRTR_DEBUG'] === '1';
 }
 // Precedence — broker-supervision.ts's threshold/interval overrides. Each
-// returns the raw parsed value with NO default: the caller (config for the
-// thresholds, a hardcoded production constant for the intervals) supplies
-// the default, and env wins over it when set. Undefined, unparseable, or
-// non-positive all mean "no override" — the caller's own default applies.
+// returns the raw parsed value with NO default: the caller supplies the
+// default (user config for the broker thresholds and the unattended-park
+// interval, a hardcoded constant for the test-only park-summary grace), and
+// env wins over it when set. Undefined, unparseable, or non-positive all mean
+// "no override" — the caller's own default applies.
 function parsePositiveInteger(raw) {
     if (raw === undefined || raw === '')
         return undefined;
@@ -171,6 +176,16 @@ function parsePositiveMsNoDefault(raw) {
 export function envTestUnattendedParkMs() {
     return parsePositiveMsNoDefault(process.env['CRTR_TEST_UNATTENDED_PARK_MS']);
 }
+/** Production unattended-park interval override (`CRTR_UNATTENDED_PARK_MS`), in
+ *  milliseconds; wins over the user-scope config value
+ *  (`readConfig('user').lifecycle.unattendedParkMs`, itself defaulting to 15
+ *  min) whenever set, autostart or not. Unlike `CRTR_TEST_UNATTENDED_PARK_MS`
+ *  this is not gated on `envNoDaemonAutostart()`: it is the env escape hatch
+ *  above the configured knob a deployment sets to tune how long an eligible
+ *  resident idles before its parking turn. */
+export function envUnattendedParkMs() {
+    return parsePositiveMsNoDefault(process.env['CRTR_UNATTENDED_PARK_MS']);
+}
 /** Test-only park-summary grace-period override
  *  (`CRTR_TEST_PARK_SUMMARY_GRACE_MS`); no production default. */
 export function envTestParkSummaryGraceMs() {

package/dist/types.d.ts

@@ -157,6 +157,14 @@ export interface BrokerThresholdsConfig {
     /** Defer daemon-initiated revives once the live broker census reaches this count. */
     automaticReviveCap: number;
 }
+/** Host-wide node-lifecycle timing. Read only from user scope by crtrd, like
+ *  `brokerThresholds`: project configuration must not change another user's
+ *  daemon. */
+export interface LifecycleConfig {
+    /** How long an eligible resident idles before its unattended-parking turn
+     *  begins, in milliseconds. `CRTR_UNATTENDED_PARK_MS` overrides this. */
+    unattendedParkMs: number;
+}
 export type KeybindingOverrides = Record<string, string[]>;
 /** Compile-time seam for runtime consumers migrating to semantic binding IDs. */
 export type CanvasAction = {
@@ -189,12 +197,14 @@ export interface ModelLaddersConfig {
     openai: Record<ModelStrength, string>;
 }
 /** A declared provider/model route. Route ids are the keys of `modelRoutes` so
- * scopes can override one route without restating the registry. */
+ * scopes can override one route without restating the registry. `credentialSource`
+ * orders otherwise-equivalent routes; credentials are selected by `providerId`.
+ * Effective routes always name every strength. */
 export interface ModelRouteConfig {
     family: string;
     credentialSource: string;
     providerId: string;
-    models: Partial<Record<ModelStrength, string>>;
+    models: Record<ModelStrength, string>;
 }
 export interface ModelRoutingConfig {
     credentialSourceOrder?: string[];
@@ -249,6 +259,8 @@ export interface ScopeConfig {
      *  Independent attended roots keep their normal viewer behavior. */
     auto_open_child_viewers: boolean;
     brokerThresholds: BrokerThresholdsConfig;
+    /** Host-wide node-lifecycle timing (user scope only). */
+    lifecycle: LifecycleConfig;
     /** Ring a short completion sound in the attach viewer when the node you are
      *  watching finishes a turn and hands control back (the Claude-Code Stop-hook
      *  ding). Only ever fires inside a live viewer pane — a headless/background

package/dist/types.js

@@ -82,6 +82,10 @@ export function defaultScopeConfig() {
         // sized as a backstop that actually engages before the machine does.
         // Override per host with CRTR_MAX_LIVE_BROKERS / CRTR_WARN_LIVE_BROKERS.
         brokerThresholds: { warning: 16, automaticReviveCap: 32 },
+        // The unattended-park idle-eligibility delay: how long an eligible resident
+        // idles before its parking turn begins. Override per host with
+        // CRTR_UNATTENDED_PARK_MS.
+        lifecycle: { unattendedParkMs: 15 * 60_000 },
         completion_bell: true,
         working_gerunds: [...DEFAULT_WORKING_GERUNDS],
         whip_mode: false,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@north-light/crouter",
-  "version": "0.3.262",
+  "version": "0.3.269",
   "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.262",
+  "version": "0.3.269",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "@north-light/crouter",
-      "version": "0.3.262",
+      "version": "0.3.269",
       "hasInstallScript": true,
       "license": "MIT",
       "dependencies": {