@north-light/crouter 0.3.197 → 0.3.198

package/dist/pages/host.d.ts

@@ -34,11 +34,6 @@ export interface CrtrThemeBridge {
     /** Registers `listener` for later theme changes; returns its unsubscribe. */
     subscribe(listener: (tokens: Record<string, string>) => void): () => void;
 }
-/** Data behind a `source`-bearing config (table, cards, chart). */
-export interface CrtrArtifactBridge {
-    /** Resolves the already-parsed data for `source`, or rejects when it is unreachable. */
-    data(source: string): Promise<unknown>;
-}
 /** What `mountWorkspaceComponent` can answer: the host rendered it, or it has no renderer. */
 export type WorkspaceMountOutcome = 'mounted' | 'unavailable';
 /** The bridge a host installs at `window.crtr`. */
@@ -59,7 +54,6 @@ export interface CrtrHost {
     /** Flushes the pending autosave of the partial map. */
     progress(): Promise<void>;
     readonly theme: CrtrThemeBridge;
-    readonly artifact: CrtrArtifactBridge;
     /**
      * Asks the host to render a product-registered (`unvalidated`) slot into `element`.
      * A host with no renderer for `kind` answers `'unavailable'`.
@@ -90,17 +84,6 @@ export type HostCall = {
     status: 'failed';
     reason: string;
 };
-/** The outcome of an artifact read, with the same three-way split as `HostCall`. */
-export type ArtifactData = {
-    status: 'ok';
-    data: unknown;
-} | {
-    status: 'unavailable';
-    reason: string;
-} | {
-    status: 'failed';
-    reason: string;
-};
 /** The installed bridge, or `undefined` on a bare page. */
 export declare function host(): CrtrHost | undefined;
 /**
@@ -143,13 +126,6 @@ export declare function themeTokens(): Record<string, string>;
  * to `disconnectedCallback` without checking whether a host was there.
  */
 export declare function subscribeTheme(listener: (tokens: Record<string, string>) => void): () => void;
-/**
- * Reads the data behind a `source`-bearing config. The host resolves the reference and hands
- * back parsed data; an element never resolves a reference itself and never fetches a URL.
- * Anything other than `'ok'` is a named unavailable state to render, not a reason to retry
- * some other way.
- */
-export declare function artifactData(source: string): Promise<ArtifactData>;
 /**
  * Asks the host to render a product-registered slot into `element`. A bare page, a host with
  * no registry, and a host whose mount threw all answer `'unavailable'` — the escape element's

package/dist/pages/host.js

@@ -147,23 +147,6 @@ export function subscribeTheme(listener) {
         return () => { };
     }
 }
-/**
- * Reads the data behind a `source`-bearing config. The host resolves the reference and hands
- * back parsed data; an element never resolves a reference itself and never fetches a URL.
- * Anything other than `'ok'` is a named unavailable state to render, not a reason to retry
- * some other way.
- */
-export async function artifactData(source) {
-    const bridge = host();
-    if (typeof bridge?.artifact?.data !== 'function')
-        return missing('artifact.data');
-    try {
-        return { status: 'ok', data: await bridge.artifact.data(source) };
-    }
-    catch (error) {
-        return { status: 'failed', reason: reasonOf(error) };
-    }
-}
 /**
  * Asks the host to render a product-registered slot into `element`. A bare page, a host with
  * no registry, and a host whose mount threw all answer `'unavailable'` — the escape element's

package/dist/pages/readonly.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Read-only presentation for a page that can no longer take an answer.
+ *
+ * A resolved or canceled page is still opened, read, and saved — the host renders it exactly
+ * as before and marks it out of reach: `inert` on each response-bearing element (Northlight's
+ * srcdoc host does this on every `[slot-id]`), and `disabled` on the pager so submit is gone.
+ * `inert` blocks pointer and keyboard interaction, but it is only a hit-testing rule: the
+ * controls underneath still LOOK live, and a scripted click still flips a checkbox. So the
+ * elements take the same signal and put it where a person can see it — every input renders
+ * disabled and every writing box read-only, which is also what makes the state unreachable
+ * rather than merely unclickable.
+ *
+ * The signal is read from the DOM rather than from a new attribute, because both halves of it
+ * already exist: `inert` is a standard reflected attribute the host sets, and `disabled` on
+ * `<crtr-pages>` is the attribute the pager itself observes.
+ */
+/** Whether this element sits on a page that can no longer take an answer. */
+export declare function isReadOnly(element: HTMLElement): boolean;
+/**
+ * Paints `root`'s controls read-only (or live again). Inputs go `disabled` — greyed, skipped
+ * by the tab order, and deaf even to a scripted `click()` — and writing boxes go `readOnly`,
+ * which keeps their text selectable and copyable while refusing every edit.
+ */
+export declare function applyReadOnly(root: ParentNode, readOnly: boolean): void;

package/dist/pages/readonly.js

@@ -0,0 +1,31 @@
+/**
+ * Read-only presentation for a page that can no longer take an answer.
+ *
+ * A resolved or canceled page is still opened, read, and saved — the host renders it exactly
+ * as before and marks it out of reach: `inert` on each response-bearing element (Northlight's
+ * srcdoc host does this on every `[slot-id]`), and `disabled` on the pager so submit is gone.
+ * `inert` blocks pointer and keyboard interaction, but it is only a hit-testing rule: the
+ * controls underneath still LOOK live, and a scripted click still flips a checkbox. So the
+ * elements take the same signal and put it where a person can see it — every input renders
+ * disabled and every writing box read-only, which is also what makes the state unreachable
+ * rather than merely unclickable.
+ *
+ * The signal is read from the DOM rather than from a new attribute, because both halves of it
+ * already exist: `inert` is a standard reflected attribute the host sets, and `disabled` on
+ * `<crtr-pages>` is the attribute the pager itself observes.
+ */
+/** Whether this element sits on a page that can no longer take an answer. */
+export function isReadOnly(element) {
+    return element.closest('[inert], crtr-pages[disabled]') !== null;
+}
+/**
+ * Paints `root`'s controls read-only (or live again). Inputs go `disabled` — greyed, skipped
+ * by the tab order, and deaf even to a scripted `click()` — and writing boxes go `readOnly`,
+ * which keeps their text selectable and copyable while refusing every edit.
+ */
+export function applyReadOnly(root, readOnly) {
+    for (const input of root.querySelectorAll('input'))
+        input.disabled = readOnly;
+    for (const area of root.querySelectorAll('textarea'))
+        area.readOnly = readOnly;
+}

package/dist/pages/responses.d.ts

@@ -0,0 +1,37 @@
+/**
+ * What the page would submit — every response-bearing slot, not only the touched ones.
+ *
+ * `respond()` is a user-change channel: an element calls it when the person changes
+ * something, so a slot nobody touched has never crossed the bridge and the host's map does
+ * not name it. A final submit must name every response-bearing slot, and crtrd rejects a
+ * map that does not — correctly, because "this slot has no answer" and "the page forgot to
+ * mention it" would otherwise be the same thing on the wire.
+ *
+ * The answer for an untouched slot is not a guess and it is not a per-kind default anyone
+ * has to re-derive: it is exactly what that slot is showing right now — a text slot's
+ * authored text, unedited; a selection nobody made. Each element already builds that object
+ * for `respond()`. So each one registers its reader here at mount, and the pager reports all
+ * of them through `respond()` immediately before it submits.
+ *
+ * Registration itself writes nothing and asks for no autosave: opening a page and closing it
+ * again saves exactly what it saved before. The reporting happens at submit, where the
+ * autosave the reports schedule is flushed by the submit itself.
+ */
+import type { SlotResponse } from './types.js';
+/**
+ * Registers this element as the answer for `slotId`. Call it once at mount, after the slot's
+ * config has been read and its state hydrated, and only from an element whose slot actually
+ * bears a response — reporting a response for a display-only slot is a submit the host will
+ * reject by name. `read` is called at submit time, so it must return the slot's complete
+ * current response, exactly what `respond()` is handed on a user change.
+ */
+export declare function registerSlotResponse(element: HTMLElement, slotId: string, read: () => SlotResponse): void;
+/**
+ * Hands the host every registered slot's current response, so the map it holds is the whole
+ * page. Only the pager calls this, and only immediately before `submit()`.
+ *
+ * A reader whose element has left the document names a slot that is no longer on screen, and
+ * a reader that throws has no answer to give; both are dropped rather than reported, which
+ * leaves the host's map exactly as complete as the page really is.
+ */
+export declare function reportSlotResponses(): void;

package/dist/pages/responses.js

@@ -0,0 +1,56 @@
+/**
+ * What the page would submit — every response-bearing slot, not only the touched ones.
+ *
+ * `respond()` is a user-change channel: an element calls it when the person changes
+ * something, so a slot nobody touched has never crossed the bridge and the host's map does
+ * not name it. A final submit must name every response-bearing slot, and crtrd rejects a
+ * map that does not — correctly, because "this slot has no answer" and "the page forgot to
+ * mention it" would otherwise be the same thing on the wire.
+ *
+ * The answer for an untouched slot is not a guess and it is not a per-kind default anyone
+ * has to re-derive: it is exactly what that slot is showing right now — a text slot's
+ * authored text, unedited; a selection nobody made. Each element already builds that object
+ * for `respond()`. So each one registers its reader here at mount, and the pager reports all
+ * of them through `respond()` immediately before it submits.
+ *
+ * Registration itself writes nothing and asks for no autosave: opening a page and closing it
+ * again saves exactly what it saved before. The reporting happens at submit, where the
+ * autosave the reports schedule is flushed by the submit itself.
+ */
+import { respond } from './host.js';
+/** One entry per slot id; a second registration for an id replaces the first. */
+const readers = new Map();
+/**
+ * Registers this element as the answer for `slotId`. Call it once at mount, after the slot's
+ * config has been read and its state hydrated, and only from an element whose slot actually
+ * bears a response — reporting a response for a display-only slot is a submit the host will
+ * reject by name. `read` is called at submit time, so it must return the slot's complete
+ * current response, exactly what `respond()` is handed on a user change.
+ */
+export function registerSlotResponse(element, slotId, read) {
+    readers.set(slotId, { element, read });
+}
+/**
+ * Hands the host every registered slot's current response, so the map it holds is the whole
+ * page. Only the pager calls this, and only immediately before `submit()`.
+ *
+ * A reader whose element has left the document names a slot that is no longer on screen, and
+ * a reader that throws has no answer to give; both are dropped rather than reported, which
+ * leaves the host's map exactly as complete as the page really is.
+ */
+export function reportSlotResponses() {
+    for (const [slotId, reader] of [...readers]) {
+        if (!reader.element.isConnected) {
+            readers.delete(slotId);
+            continue;
+        }
+        let response;
+        try {
+            response = reader.read();
+        }
+        catch {
+            continue;
+        }
+        respond(slotId, response);
+    }
+}

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

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

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

@@ -28,6 +28,7 @@ import { spawn } from 'node:child_process';
 import { closeSync, existsSync, mkdirSync, openSync, readFileSync, readSync, rmSync, statSync, writeFileSync, } from 'node:fs';
 import { homedir } from 'node:os';
 import { backgroundBashJob, bashJobPaths, formatBashElapsed, newBashJobId, normalizeBashJobPurpose } from '../core/bash-jobs.js';
+import { readConfig } from '../core/config.js';
 import { Type } from 'typebox';
 import { createBashToolDefinition } from '@earendil-works/pi-coding-agent';
 // ---------------------------------------------------------------------------
@@ -351,7 +352,7 @@ export function createValveOperations(nodeId, contextDir, takePurpose = () => nu
 // ---------------------------------------------------------------------------
 // `purpose` — the one line a person reads while a command runs
 //
-// A deliberate deviation from taking pi's definition verbatim, and the only one
+// An optional deviation from taking pi's definition verbatim, and the only one
 // here. Everywhere crtr's output reaches a non-technical audience, the host has
 // to render SOMETHING per step, and without this field its only material is the
 // command — which yields "Running command" for an entire turn. The model is the
@@ -393,13 +394,16 @@ function withPurpose(definition) {
         }),
     };
 }
-/** Bind each purpose directly to its own tool execution. Pi may preflight a
- * batch before starting its calls, so a shared "next purpose" slot could give
- * a concurrent call the wrong label. */
-function createPurposeValveToolDefinition(nodeId, contextDir, cwd) {
-    const schemaDefinition = withPurpose(createBashToolDefinition(cwd, { operations: createValveOperations(nodeId, contextDir) }));
+/** Build the valve-backed bash tool and, when configured, add `purpose` to its
+ * schema. Bind each purpose directly to its own execution: Pi may preflight a
+ * batch before starting its calls, so a shared "next purpose" slot could give a
+ * concurrent call the wrong label. Disabled means absent, not merely ignored —
+ * the model receives pi's upstream bash schema verbatim. */
+export function createValveToolDefinition(nodeId, contextDir, cwd, exposePurpose) {
+    const baseDefinition = createBashToolDefinition(cwd, { operations: createValveOperations(nodeId, contextDir) });
+    const schemaDefinition = exposePurpose ? withPurpose(baseDefinition) : baseDefinition;
     const execute = (toolCallId, params, signal, onUpdate, ctx) => {
-        const purpose = normalizeBashJobPurpose(params['purpose']);
+        const purpose = exposePurpose ? normalizeBashJobPurpose(params['purpose']) : null;
         const definition = createBashToolDefinition(cwd, { operations: createValveOperations(nodeId, contextDir, () => purpose) });
         return definition.execute(toolCallId, params, signal, onUpdate, ctx);
     };
@@ -418,6 +422,6 @@ export default function (pi) {
     // is built against. registerTool replaces the builtin by name; re-firing on
     // every session_start is idempotent (last registration wins).
     pi.on('session_start', (_event, ctx) => {
-        pi.registerTool(createPurposeValveToolDefinition(nodeId, contextDir, ctx.cwd));
+        pi.registerTool(createValveToolDefinition(nodeId, contextDir, ctx.cwd, readConfig('user').bash_tool_purpose));
     });
 }

package/dist/types.d.ts

@@ -160,6 +160,16 @@ export interface KindConfig {
     whenToUse: string;
     availableTo?: string[];
 }
+export interface PageComponentRegistration {
+    kind: string;
+    description?: string;
+    useWhen?: string;
+    doc?: string;
+    /** A display-only product slot contributes no page response. */
+    display?: boolean;
+}
+/** The normalized product component catalog used to validate page slots. */
+export type ProductPageComponents = readonly PageComponentRegistration[];
 export interface ScopeConfig {
     schema_version: number;
     marketplaces: Record<string, ConfigMarketplaceEntry>;
@@ -183,12 +193,12 @@ export interface ScopeConfig {
      *  or empty lists fall back to `['working']`. */
     working_gerunds: string[];
     /** Play the whip header animation whenever the human sends a prompt, and once
-     *  when an automatically opened managed-child viewer starts. Default false. */
+     *  when a viewer opens for an agent with an initial prompt. Default false. */
     whip_mode: boolean;
-    /** Teach agent help the HTML page-authoring dialect. Off keeps page authoring Markdown-only. */
-    html_pages: boolean;
-    /** Product-registered page slot kinds beyond crtr's built-in catalog. */
-    page_components: string[];
+    /** Product-registered page components beyond crtr's built-in catalog. */
+    page_components: PageComponentRegistration[];
+    /** Prompt agents to use HTML pages by default for structured or interactive human content. Default false. */
+    html_surface: boolean;
     /** Playful urgency messages the attach-viewer whip action sends to an agent. Missing, malformed, or empty lists fall back to the built-in rotation. */
     whip_messages: string[];
     /** Initial mouse wheel scrolling mode for each attach viewer. `tmux` follows
@@ -211,6 +221,10 @@ export interface ScopeConfig {
      *  `both` keeps both. Tool calls and results are never kept. Full detail for
      *  every cycle stays in the session file. */
     condensed_history: CondensedHistoryMode;
+    /** Expose crouter's optional `purpose` label in the bash tool schema. Turning
+     *  this off leaves the bash valve active but gives agents pi's ordinary bash
+     *  definition with only its upstream parameters. Default true. */
+    bash_tool_purpose: boolean;
     /** Fold every SETTLED tool call in the attach viewer down to its single call
      *  line (`/fold-tools`, Alt+C → z → f). A tool still running is never folded —
      *  it folds itself once it settles. Toggling it in a viewer writes back here,

package/dist/types.js

@@ -78,12 +78,13 @@ export function defaultScopeConfig() {
         completion_bell: true,
         working_gerunds: [...DEFAULT_WORKING_GERUNDS],
         whip_mode: false,
-        html_pages: false,
         page_components: [],
+        html_surface: false,
         whip_messages: [...DEFAULT_WHIP_MESSAGES],
         mouse_mode_default: 'tmux',
         live_cycles: DEFAULT_LIVE_CYCLES,
         condensed_history: DEFAULT_CONDENSED_HISTORY,
+        bash_tool_purpose: true,
         fold_finished_tools: false,
         summarize_tool_calls: false,
         detailed_tool_recaps: true,

package/package.json

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

package/scripts/install-runtime.mjs

@@ -14,7 +14,10 @@ const GENERATIONS = join(RUNTIME_HOME, 'generations');
 const LOCK = join(RUNTIME_HOME, 'install.lock');
 const LOCK_OWNER_FILE = 'owner.json';
 const RUNTIME_LOCK = 'runtime.lock.json';
-const KEEP_RECENT_GENERATIONS = 3;
+// The selected generation plus one prior, so a bad selection can be rolled
+// back by hand. Anything older is reinstallable from npm and is not worth the
+// ~500MB/generation it costs on disk.
+const KEEP_RECENT_GENERATIONS = 2;
 const FS_CONCURRENCY = 64;
 // How long an install.lock with no readable owner record is given the
 // benefit of the doubt (the owner is mid-write, or on an ancient version of
@@ -174,40 +177,36 @@ function generationIdsIn(text) {
   return [...text.matchAll(/generations\/([a-f0-9]{64})(?:[/\s]|$)/g)].map((match) => match[1]);
 }
 
-/** Return every generation used by a running process and whether every stable
- *  selector process exposed its generation lease. */
+/** Every generation a running process is using — named in its argv, or held as
+ *  an open entry-file lease (how a stable `crtr`/`crtrd` shim, whose argv names
+ *  no generation, keeps the one it resolved; see `holdGenerationEntryFd` in
+ *  bin/runtime-selector.mjs and the matching open in src/cli.ts).
+ *
+ *  Detection is positive-only and that is deliberate: a generation nothing here
+ *  names is prunable. An earlier revision also tracked whether every stable shim
+ *  had exposed a lease and skipped the whole GC when one had not. That made one
+ *  unidentifiable process veto all pruning permanently — a single pre-upgrade
+ *  viewer, which could never hold a lease the mechanism predated, silently
+ *  stopped GC forever and grew this directory by ~500MB per install. */
 async function liveGenerationIds() {
   const output = await run('ps', ['-axww', '-o', 'pid=,command='], RUNTIME_HOME, true);
   const live = new Set(generationIdsIn(output));
   const nodePids = [];
-  const opaqueStablePids = new Set();
   for (const line of output.split('\n')) {
     const match = /^\s*(\d+)\s+(.*)$/.exec(line);
     if (!match) continue;
     const [, pid, command] = match;
-    const stableSelector = /^(?:\S*node\s+)?\S*\/bin\/(?:crtr|crtrd|crouter)(?:\s|$)/.test(command);
-    if (stableSelector && generationIdsIn(command).length === 0) opaqueStablePids.add(pid);
     if (/(?:^|[\s/])(?:node|crtrd?|crouter)(?:[\s]|$)/.test(command)) nodePids.push(pid);
   }
-  if (nodePids.length === 0) return { live, uncertain: opaqueStablePids.size > 0 };
+  if (nodePids.length === 0) return live;
 
   // One lsof invocation resolves cwd references and the runtime entry-file
   // lease held by each stable CLI process without a per-process startup penalty.
   const open = await probe('lsof', ['-n', '-P', '-a', '-p', nodePids.join(','), '-Fn'], RUNTIME_HOME);
-  let pid;
-  const exposedStablePids = new Set();
   for (const line of open.split('\n')) {
-    const processMatch = /^p(\d+)$/.exec(line);
-    if (processMatch) {
-      pid = processMatch[1];
-      continue;
-    }
-    const ids = generationIdsIn(line);
-    for (const id of ids) live.add(id);
-    if (pid !== undefined && ids.length > 0 && opaqueStablePids.has(pid)) exposedStablePids.add(pid);
+    for (const id of generationIdsIn(line)) live.add(id);
   }
-  const uncertain = [...opaqueStablePids].some((stablePid) => !exposedStablePids.has(stablePid));
-  return { live, uncertain };
+  return live;
 }
 
 async function selectedGenerationId() {
@@ -219,11 +218,7 @@ async function selectedGenerationId() {
 
 async function pruneGenerations() {
   const selected = await selectedGenerationId();
-  const { live, uncertain } = await liveGenerationIds();
-  if (uncertain) {
-    process.stderr.write('runtime generation GC skipped: a live stable crouter shim does not expose its generation lease\n');
-    return;
-  }
+  const live = await liveGenerationIds();
   const entries = await readdir(GENERATIONS, { withFileTypes: true });
   const candidates = [];
   for (const entry of entries) {

package/dist/clients/attach/render/html-markdown.d.ts

@@ -1,13 +0,0 @@
-export interface HtmlMarkdownStyles {
-    kbd: (text: string) => string;
-    mark: (text: string) => string;
-    hint: (text: string) => string;
-}
-export interface HtmlMarkdownOptions {
-    /** Undefined honors each block's `open` attribute. A boolean is the viewer's
-     * global Ctrl+O override. */
-    detailsExpanded: boolean | undefined;
-    styles: HtmlMarkdownStyles;
-}
-/** Transform the strict supported HTML subset in one Markdown string. */
-export declare function transformHtmlMarkdown(source: string, options: HtmlMarkdownOptions): string;