@north-light/crouter 0.3.154

package/dist/core/runtime/warm-pool.d.ts

@@ -0,0 +1,51 @@
+import type { Mode } from '../canvas/index.js';
+/** Kill switch. `CRTR_WARM_POOL=0` makes every create cold again: claims stop,
+ *  refills stop, and daemon-start pre-warm no-ops. Read live (not cached at
+ *  module load) so flipping it takes effect on the next `crtr sys daemon
+ *  restart` without a rebuild. Env rather than config because the operators who
+ *  need it are guest containers — a Blaxel sandbox spec and the local-docker
+ *  compose both already carry per-home env, and neither has a config file the
+ *  host controls.
+ *
+ *  Turn it off when a spare's ~150-300 MB resident broker is the scarce
+ *  resource (a memory-capped guest), or to isolate the pool while debugging a
+ *  node that came back wearing the wrong persona. */
+export declare function warmPoolEnabled(): boolean;
+/** What a `prefer_warm` create is asking for. Only a subset of this is frozen
+ *  into the pool key (see `warmRecipeKey`); the rest is applied at claim time. */
+export interface WarmRequest {
+    kind: string;
+    mode: Mode;
+    cwd: string;
+    /** The RAW `--profile` operand: a string to pin, `null` for explicitly no
+     *  profile, `undefined` to let the daemon resolve one for the cwd. */
+    profile: string | null | undefined;
+    model: string | null;
+    situationalContext: string | null;
+    name: string | null;
+}
+/** Claim a spare for `request`, reshaped onto its persona — or null when the
+ *  pool cannot serve it. The caller falls back to a cold spawn; a claim never
+ *  fails the create. */
+export declare function claimWarmNode(request: WarmRequest): Promise<string | null>;
+/** Return every spare that is no longer worth its broker: one whose engine is
+ *  confirmed GONE (the common case — a daemon handover tears down every broker
+ *  of its epoch and nothing resumes a spare), one whose row left `active`/`idle`,
+ *  and one nobody claimed inside `SPARE_TTL_MS`.
+ *
+ *  Order matters: the marker is deleted FIRST, atomically, which is the same
+ *  move a claim makes — so a spare handed out a microsecond earlier is left
+ *  alone (`unregisterWarmSpare` returns false) and never torn down under its
+ *  new owner. Only after winning the marker is the broker killed and the row +
+ *  dir deleted. Never throws: a failed reap is retried on the next sweep. */
+export declare function reapStaleSpares(): string[];
+/** Bring the pool for `request` back to depth 1, in the background. Never
+ *  throws and never blocks a caller: a failed mint just means the next create
+ *  for this key is cold again. */
+export declare function refillWarmPool(request: WarmRequest): void;
+/** Mint a spare for the most recently used project recipes so the FIRST create
+ *  after crtrd boots is warm too, not only the second. The recipe is sourced
+ *  from real recent roots — (cwd, profile) is the whole of it, since everything
+ *  else a claim reshapes live. Fire-and-forget: returns as soon as the mints
+ *  are scheduled, never blocking the daemon's work lane. */
+export declare function prewarmRecentRecipes(): void;

package/dist/core/runtime/warm-pool.js

@@ -0,0 +1,373 @@
+// warm-pool.ts — spare pre-booted roots, so `POST /v1/nodes` can answer in
+// milliseconds instead of waiting out a full pi engine boot (~3.6s in a guest
+// container, all of it `waitForBrokerViewSocket`).
+//
+// A spare is an ordinary canvas node: root, no kickoff prompt (so it never runs
+// a turn before anyone owns it), booted and holding a live broker, carrying a
+// `warm_pool` marker that hides it from every listing until it is claimed.
+// Claiming is the atomic DELETE of that marker (canvas.ts `claimWarmSpare`)
+// plus a `created` restamp and a RESHAPE onto the claimant's persona, after
+// which the node is indistinguishable from one that was just cold-spawned.
+//
+// What a spare must freeze is ONLY what a booted pi process genuinely cannot
+// change: its cwd, its profile, and the launch spec minus the two properties a
+// live session can still be told (tools, extensions, system prompt, env).
+// Everything else is claim-time reshape:
+//   • kind / mode / name / launch spec — rewritten on the row exactly as the
+//     `promote`/`yield --kind` polymorph rewrites them, so the next revive comes
+//     back as the claimed persona and `nodeEnv`'s CRTR_KIND/CRTR_MODE flip for
+//     anything the live process spawns.
+//   • persona_ack — stamped to the claimed {mode,lifecycle}. Without it the
+//     persona injector (runtime/persona.ts) reads drift on the first turn and
+//     tells a brand-new node its persona just changed.
+//   • model — swapped over the live broker socket (`setModelLive`, the same
+//     seam provider rotation uses). A model swap that cannot reach the broker
+//     FAILS the claim: the spare is closed and the caller cold-spawns, because
+//     a wrong-model node is worse than a slow one.
+//   • bearings — a spare mints with NONE (the context-intro extension withholds
+//     them from an unclaimed spare), because a block built at mint would assert
+//     the spare's placeholder `general`/`base` persona and snapshot the repo as
+//     it looked at mint time. Built and delivered here instead, over
+//     `deliver-live.ts`, once the row already wears the claimant's persona — and
+//     still landing first, since nobody has spoken in the session yet.
+//   • situational context — the sidecar is written and the block handed to the
+//     running session over `set_situational_context` (`situational-live.ts`),
+//     which queues it for the claimant's FIRST turn rather than starting one.
+//     Fails the claim on the same terms as the model: a node holding the wrong
+//     situation is worse than a slow one.
+//
+// The whole reshape is sound because every installed kind×mode builds an
+// IDENTICAL launch spec apart from `model` — verified across all 34 of them.
+// The key is derived from the actual built spec, so if that ever stops being
+// true the affected kinds simply key into their own pool instead of silently
+// being handed a mismatched node.
+//
+// Pool depth is 1 per key. It is populated lazily (the first `prefer_warm`
+// create for a key falls back to a cold spawn and mints the spare behind it)
+// and at daemon start for the most recent live roots, so the FIRST node after
+// sitting down is warm too.
+//
+// Nothing ever RESUMES a spare: the daemon's recovery sweep reads `listNodes`,
+// which hides the pool, so a spare whose broker dies (every daemon handover
+// tears down every broker of the epoch) is garbage, not a parked node. It is
+// also invisible to the count-based prune for the same reason. So the pool owns
+// its own garbage collection — `reapStaleSpares`, below, run at daemon start
+// and on every supervision tick.
+import { createHash } from 'node:crypto';
+import { claimWarmSpare, deleteNode, getNode, listNodes, listWarmSpares, registerWarmSpare, unregisterWarmSpare, updateNode, warmSpareCount, } from '../canvas/index.js';
+import { recordedPidLiveness } from '../canvas/pid.js';
+import { nowIso } from '../fs-utils.js';
+import { resolveProfileId, spawnChildPrepared } from './spawn.js';
+import { buildLaunchSpec } from './launch.js';
+import { setModelLive } from './model-swap.js';
+import { setSituationalContextLive } from './situational-live.js';
+import { deliverBearingsLive } from './deliver-live.js';
+import { closeNode } from './close.js';
+/** Kill switch. `CRTR_WARM_POOL=0` makes every create cold again: claims stop,
+ *  refills stop, and daemon-start pre-warm no-ops. Read live (not cached at
+ *  module load) so flipping it takes effect on the next `crtr sys daemon
+ *  restart` without a rebuild. Env rather than config because the operators who
+ *  need it are guest containers — a Blaxel sandbox spec and the local-docker
+ *  compose both already carry per-home env, and neither has a config file the
+ *  host controls.
+ *
+ *  Turn it off when a spare's ~150-300 MB resident broker is the scarce
+ *  resource (a memory-capped guest), or to isolate the pool while debugging a
+ *  node that came back wearing the wrong persona. */
+export function warmPoolEnabled() {
+    return process.env['CRTR_WARM_POOL'] !== '0';
+}
+/** Stable digest of everything a booted broker bakes in. Deliberately excludes
+ *  `model`/`modelProviderPinned`/`modelExact` AND the situational context: both
+ *  are a socket round-trip on a live session, so both are claim-time, not
+ *  mint-time. Keeping the situation out is what stops the pool fanning into a
+ *  key (and a resident broker) per distinct ambient context. */
+function warmRecipeKey(cwd, profileId, launch) {
+    const env = Object.entries(launch.env ?? {}).sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0));
+    const canonical = JSON.stringify([
+        cwd,
+        profileId,
+        launch.tools ?? [],
+        launch.extensions ?? [],
+        launch.systemPrompt ?? null,
+        env,
+    ]);
+    return createHash('sha256').update(canonical).digest('hex').slice(0, 32);
+}
+/** Resolve a request's frozen half. `resolveProfileId(explicit, null, cwd)` is
+ *  the SAME call the cold create path makes for an API-created root (no spawner
+ *  — a warm-eligible create is parentless by construction), so keying the
+ *  resolved id costs nothing extra and keys what actually matters. */
+async function resolveRecipe(request) {
+    const profileId = await resolveProfileId(request.profile, null, request.cwd);
+    const { launch } = buildLaunchSpec(request.kind, request.mode, {
+        lifecycle: 'resident',
+        hasManager: false,
+        ...(request.model !== null ? { model: request.model } : {}),
+        cwd: request.cwd,
+        profileId,
+    });
+    return {
+        key: warmRecipeKey(request.cwd, profileId, launch),
+        launch,
+        profileId,
+        request,
+    };
+}
+/** Claim a spare for `request`, reshaped onto its persona — or null when the
+ *  pool cannot serve it. The caller falls back to a cold spawn; a claim never
+ *  fails the create. */
+export async function claimWarmNode(request) {
+    const recipe = await resolveRecipe(request);
+    const created = nowIso();
+    // The row's stamp moves inside the claim transaction; meta.json (the identity
+    // source of truth `rebuildIndex` re-derives the row from) follows with the
+    // SAME value, so the two can never disagree about when this node was born.
+    const nodeId = claimWarmSpare(recipe.key, created);
+    if (nodeId === null)
+        return null;
+    const spare = getNode(nodeId);
+    const bootedModel = spare?.launch?.model;
+    updateNode(nodeId, {
+        created,
+        kind: request.kind,
+        mode: request.mode,
+        name: request.name ?? request.kind,
+        // The recipe a later revive replays — skip it and the node silently comes
+        // back as the spare's persona.
+        launch: recipe.launch,
+        // A newborn must not be told its persona just changed.
+        persona_ack: { mode: request.mode, lifecycle: 'resident' },
+        ...(request.model !== null ? { model_override: request.model } : {}),
+    });
+    // Bearings FIRST, before any other delivery: a spare mints without them (see
+    // canvas-context-intro.ts), so this is the node's orienting frame and it must
+    // land as the session's first entry. Built from the row we just reshaped, so
+    // the identity assertion, knowledge catalog, and `<project_context>` snapshot
+    // all describe the node actually being handed out rather than the spare as it
+    // looked whenever it happened to boot.
+    try {
+        await deliverBearingsLive(nodeId);
+    }
+    catch (err) {
+        return abandonSpare(nodeId, 'bearings delivery', err);
+    }
+    // Spares are always minted at the kind's DEFAULT model (never an explicit
+    // pin), so this fires only when the claimant asked for a different tier.
+    const target = recipe.launch.model;
+    if (target !== undefined && target !== bootedModel) {
+        try {
+            await setModelLive(nodeId, target, recipe.launch.modelProviderPinned === true);
+        }
+        catch (err) {
+            return abandonSpare(nodeId, 'model swap', err);
+        }
+    }
+    // Spares mint with NO situational context, so this is the claimant's, handed
+    // to a session that is already past session_start. `nextTurn` delivery means
+    // it rides the first real turn instead of waking a node nobody has spoken to.
+    if (request.situationalContext !== null) {
+        try {
+            await setSituationalContextLive(nodeId, request.situationalContext);
+        }
+        catch (err) {
+            return abandonSpare(nodeId, 'situational-context delivery', err);
+        }
+    }
+    return nodeId;
+}
+/** A claim-time reshape that could not be applied leaves a node wearing the
+ *  WRONG persona/model/situation — worse than a slow one. Close it and answer
+ *  null so the caller cold-spawns. */
+function abandonSpare(nodeId, what, err) {
+    console.error(`[warm-pool] ${what} failed on claim; closing the spare: ${err.message}`);
+    try {
+        closeNode(nodeId);
+    }
+    catch { /* best-effort */ }
+    return null;
+}
+// ---------------------------------------------------------------------------
+// Reaping
+// ---------------------------------------------------------------------------
+/** How long an UNCLAIMED spare is worth its resident broker (~150-300 MB).
+ *  A spare exists to make the NEXT create instant; one nobody has claimed in
+ *  this long is memory rented for nothing, so it is returned. Over-reaping
+ *  costs exactly one cold create (which then refills the pool), while
+ *  under-reaping accumulates hidden brokers — nothing else reaps them.
+ *
+ *  It is also what bounds the number of KEYS. Depth is 1 per key, but the key
+ *  digests the launch spec, whose extension paths carry the runtime GENERATION
+ *  hash — so every `install-runtime` re-keys the pool and strands the previous
+ *  key's spare, permanently claimable by nobody. The TTL is what collects them.
+ */
+const SPARE_TTL_MS = 60 * 60 * 1000;
+/** Return every spare that is no longer worth its broker: one whose engine is
+ *  confirmed GONE (the common case — a daemon handover tears down every broker
+ *  of its epoch and nothing resumes a spare), one whose row left `active`/`idle`,
+ *  and one nobody claimed inside `SPARE_TTL_MS`.
+ *
+ *  Order matters: the marker is deleted FIRST, atomically, which is the same
+ *  move a claim makes — so a spare handed out a microsecond earlier is left
+ *  alone (`unregisterWarmSpare` returns false) and never torn down under its
+ *  new owner. Only after winning the marker is the broker killed and the row +
+ *  dir deleted. Never throws: a failed reap is retried on the next sweep. */
+export function reapStaleSpares() {
+    const reaped = [];
+    let spares;
+    try {
+        spares = listWarmSpares();
+    }
+    catch (err) {
+        console.error(`[warm-pool] spare scan failed: ${err.message}`);
+        return reaped;
+    }
+    const cutoff = Date.now() - SPARE_TTL_MS;
+    for (const spare of spares) {
+        const mintedAt = Date.parse(spare.created);
+        const expired = Number.isNaN(mintedAt) || mintedAt < cutoff;
+        const liveness = recordedPidLiveness(spare.pi_pid, spare.pi_pid_identity);
+        const live = (spare.status === 'active' || spare.status === 'idle') && liveness === 'alive';
+        if (live && !expired)
+            continue;
+        // A failed probe is not evidence of death — leave it for the next sweep
+        // unless it is past its TTL anyway, where the verdict is the same.
+        if (liveness === 'indeterminate' && !expired)
+            continue;
+        try {
+            if (!unregisterWarmSpare(spare.node_id))
+                continue; // claimed out from under us
+            if (live) {
+                try {
+                    closeNode(spare.node_id);
+                }
+                catch { /* best-effort broker teardown */ }
+            }
+            deleteNode(spare.node_id);
+            reaped.push(spare.node_id);
+        }
+        catch (err) {
+            console.error(`[warm-pool] reap failed for ${spare.node_id}: ${err.message}`);
+        }
+    }
+    return reaped;
+}
+/** Keys with a mint in flight — crtrd is the single writer of the pool, so an
+ *  in-process guard is enough to keep depth at 1 under concurrent creates. */
+const minting = new Set();
+/** Bring the pool for `request` back to depth 1, in the background. Never
+ *  throws and never blocks a caller: a failed mint just means the next create
+ *  for this key is cold again. */
+export function refillWarmPool(request) {
+    if (!warmPoolEnabled())
+        return;
+    void (async () => {
+        try {
+            // Mint at the kind's DEFAULT model and with NO situational context: both
+            // are claim-time properties, so baking either in would only narrow who
+            // the spare can serve.
+            const recipe = await resolveRecipe({ ...request, model: null, situationalContext: null });
+            mint(recipe);
+        }
+        catch (err) {
+            console.error(`[warm-pool] recipe resolution failed: ${err.message}`);
+        }
+    })();
+}
+/** Mint one spare for an already-resolved recipe, if the pool is short. */
+function mint(recipe) {
+    const { key, request } = recipe;
+    if (minting.has(key))
+        return;
+    if (warmSpareCount(key) > 0)
+        return;
+    minting.add(key);
+    void (async () => {
+        try {
+            await spawnChildPrepared({
+                kind: request.kind,
+                mode: request.mode,
+                cwd: request.cwd,
+                // No kickoff: an empty prompt means no launch turn, so a spare burns no
+                // tokens and holds no history before somebody owns it.
+                prompt: '',
+                root: true,
+                // The spare is only useful once its broker accepts viewers — that wait
+                // is precisely the cost being moved off the create path.
+                readiness: 'await',
+                // Mint at the kind's DEFAULT model: `model_override` then stays unset on
+                // the spare, so a claim only ever SETS it (updateNode cannot clear a
+                // field) and a no-model claim gets a clean row.
+                ...(request.profile !== undefined ? { profile: request.profile } : {}),
+                // No situational context either: the claimant's is delivered live at
+                // claim time, so a spare that baked one in would serve nobody else.
+                // Mark it unclaimed the instant its row exists and BEFORE the broker
+                // launch this call then waits out — otherwise the spare would sit in
+                // every listing for the whole boot as a phantom empty conversation.
+            }, (nodeId) => registerWarmSpare(nodeId, key));
+        }
+        catch (err) {
+            console.error(`[warm-pool] mint failed for ${request.kind}: ${err.message}`);
+        }
+        finally {
+            minting.delete(key);
+        }
+    })();
+}
+// ---------------------------------------------------------------------------
+// Daemon-start pre-warm
+// ---------------------------------------------------------------------------
+/** How many distinct (cwd, profile) recipes get a spare at daemon start. Each
+ *  spare is a resident broker at ~150-300 MB, so this is deliberately tiny. */
+const PREWARM_RECIPES = 2;
+/** Mint a spare for the most recently used project recipes so the FIRST create
+ *  after crtrd boots is warm too, not only the second. The recipe is sourced
+ *  from real recent roots — (cwd, profile) is the whole of it, since everything
+ *  else a claim reshapes live. Fire-and-forget: returns as soon as the mints
+ *  are scheduled, never blocking the daemon's work lane. */
+export function prewarmRecentRecipes() {
+    if (!warmPoolEnabled())
+        return;
+    let candidates;
+    try {
+        const seen = new Set();
+        candidates = [];
+        // Newest first; `listNodes` already hides unclaimed spares.
+        for (const row of listNodes({ status: ['active', 'idle'] }).reverse()) {
+            if (row.parent !== null || row.kind === 'human')
+                continue;
+            const dedupe = `${row.cwd}\u0000${row.profile_id ?? ''}`;
+            if (seen.has(dedupe))
+                continue;
+            seen.add(dedupe);
+            candidates.push({ cwd: row.cwd, profileId: row.profile_id ?? null });
+            if (candidates.length >= PREWARM_RECIPES)
+                break;
+        }
+    }
+    catch (err) {
+        console.error(`[warm-pool] prewarm scan failed: ${err.message}`);
+        return;
+    }
+    for (const candidate of candidates) {
+        void (async () => {
+            try {
+                // `general`/`base` is only the shape the spare BOOTS as — the key it is
+                // filed under excludes everything a claim can reshape, so any kind can
+                // claim it.
+                mint(await resolveRecipe({
+                    kind: 'general',
+                    mode: 'base',
+                    cwd: candidate.cwd,
+                    profile: candidate.profileId,
+                    model: null,
+                    situationalContext: null,
+                    name: null,
+                }));
+            }
+            catch (err) {
+                console.error(`[warm-pool] prewarm failed for ${candidate.cwd}: ${err.message}`);
+            }
+        })();
+    }
+}

package/dist/core/scope.d.ts

@@ -0,0 +1,47 @@
+import type { InstalledPlugin, Scope } from '../types.js';
+export declare function builtinViewsRoot(): string;
+export declare function builtinMemoryRoot(): string;
+export declare function builtinPiPackagesDir(): string;
+export declare function builtinPiPackageDir(name: string): string;
+export declare function userScopeRoot(): string;
+export declare function findProjectScopeRoot(startDir?: string): string | null;
+/** Every project scope root visible from `startDir`, nearest first — now a
+ *  PROFILE-AWARE pointer walk, not a single-pointer ancestor walk. Pointers are
+ *  `[startDir]` plus, when `profileId` resolves to a manifest, each of its
+ *  `projects` in manifest order; each pointer independently walks upward
+ *  collecting every ancestor `.crouter/` dir, the pointers' contributions
+ *  concatenate in pointer order, and the combined list dedupes to first
+ *  occurrence — so a `.crouter/` shared by two pointers contributes once, at
+ *  whichever pointer reached it first. `profileId` defaults to the process's
+ *  selected profile (`CRTR_PROFILE_ID`); a null/unresolvable profile collapses
+ *  to the single `[startDir]` pointer, reproducing today's behavior exactly.
+ *  Results are cached per (resolved startDir, profileId) — `resetScopeCache()`
+ *  invalidates on any profile mutation that can change project dirs or names. */
+export declare function findProjectScopeRoots(startDir?: string, profileId?: string | null): string[];
+export declare function projectScopeRoot(startDir?: string): string | null;
+export declare function projectScopeRoots(startDir?: string, profileId?: string | null): string[];
+export declare function scopeRoot(scope: Scope): string | null;
+export declare function requireScopeRoot(scope: Scope): string;
+export declare function ensureProjectScopeRoot(startDir?: string): string;
+export declare function pluginsDir(scope: Scope): string | null;
+export declare function marketplacesDir(scope: Scope): string | null;
+export declare function configuredClisDir(scope: Scope): string | null;
+/** The configured-CLIs cache parent dir under an EXACT scope-root dir. Used to
+ *  address per-root caches when multiple project roots are visible; the single
+ *  source of the `configured-clis` path segment. */
+export declare function configuredClisDirForRoot(scopeRootDir: string): string;
+/** Where substrate memory documents live per scope. Builtin memory is the
+ *  special case — its own package dir (builtinMemoryRoot), since the builtin
+ *  scope has no scopeRoot — mirroring viewsDir's builtin handling. User and
+ *  project memory live at scopeRoot(scope)/memory. */
+export declare function scopeMemoryDir(scope: Scope): string | null;
+/** Where a plugin's substrate memory documents live: `<plugin.root>/memory`.
+ *  The resolver mounts these under the virtual `<pluginName>/` namespace. */
+export declare function pluginMemoryDir(plugin: InstalledPlugin): string;
+/** Where view definition dirs live per scope. Builtin views sit directly under
+ *  builtinViewsRoot() (no `views/` segment — they ARE the builtin views dir),
+ *  matching the loader's `<root>/<name>/core.mjs` resolution. */
+export declare function viewsDir(scope: Scope): string | null;
+export declare function resolveScopeArg(scopeArg: string | undefined): Scope | 'all';
+export declare function listScopes(scopeArg: string | undefined): Scope[];
+export declare function resetScopeCache(): void;