@crouton-kit/crouter 0.3.32 → 0.3.34

package/dist/core/config.js

@@ -1,5 +1,5 @@
 import { join } from 'node:path';
-import { CONFIG_FILE, STATE_FILE, defaultScopeConfig, defaultScopeState, defaultCanvasNavConfig } from '../types.js';
+import { CONFIG_FILE, STATE_FILE, defaultScopeConfig, defaultScopeState, defaultCanvasNavConfig, defaultModelLaddersConfig } from '../types.js';
 import { readJsonIfExists, writeJson, ensureDir } from './fs-utils.js';
 import { scopeRoot, requireScopeRoot } from './scope.js';
 function configPathFor(root) {
@@ -56,21 +56,82 @@ export function ensureScopeInitialized(scope, root) {
         writeJson(cfgPath, defaultScopeConfig());
     }
 }
+function prefixBindDesc(desc) {
+    return typeof desc === 'string' && desc !== '' ? { desc } : {};
+}
+function normalizePrefixMenuItem(raw) {
+    if (raw === null || typeof raw !== 'object')
+        return null;
+    const r = raw;
+    const key = typeof r.key === 'string' && r.key !== '' ? r.key : null;
+    const desc = typeof r.desc === 'string' && r.desc !== '' ? r.desc : null;
+    const action = normalizePrefixBind(r.action);
+    if (key === null || desc === null || action === null)
+        return null;
+    const out = { key, desc, action };
+    if (r.confirm === true)
+        out.confirm = true;
+    return out;
+}
+function normalizePrefixBind(raw) {
+    if (raw === null || typeof raw !== 'object')
+        return null;
+    const r = raw;
+    const desc = prefixBindDesc(r.desc);
+    const confirm = r.confirm === true ? { confirm: true } : {};
+    if (typeof r.run === 'string') {
+        if (r.run === '__graph__')
+            return { kind: 'keys', keys: '/graph', ...desc };
+        if (r.run === '__issue__') {
+            return {
+                kind: 'menu',
+                items: [
+                    { key: 'i', desc: 'idea', action: { kind: 'popup', run: 'canvas issue new --type idea' } },
+                    { key: 'b', desc: 'bug', action: { kind: 'popup', run: 'canvas issue new --type bug' } },
+                ],
+                ...desc,
+            };
+        }
+    }
+    if (r.kind === 'keys' && typeof r.keys === 'string')
+        return { kind: 'keys', keys: r.keys, ...desc };
+    if (r.kind === 'popup' && typeof r.run === 'string')
+        return { kind: 'popup', run: r.run, ...desc };
+    if (r.kind === 'menu' && Array.isArray(r.items)) {
+        const items = r.items.map(normalizePrefixMenuItem).filter((item) => item !== null);
+        if (items.length !== r.items.length)
+            return null;
+        return { kind: 'menu', items, ...desc };
+    }
+    if ((r.kind === undefined || r.kind === 'crtr') && typeof r.run === 'string') {
+        return { kind: 'crtr', run: r.run, ...confirm, ...desc };
+    }
+    if (r.kind === undefined && typeof r.keys === 'string')
+        return { kind: 'keys', keys: r.keys, ...desc };
+    return null;
+}
+function normalizeGraphBind(raw) {
+    if (raw === null || typeof raw !== 'object')
+        return null;
+    const r = raw;
+    if (typeof r.run !== 'string')
+        return null;
+    return {
+        run: r.run,
+        ...(r.confirm === true ? { confirm: true } : {}),
+        ...(typeof r.desc === 'string' && r.desc !== '' ? { desc: r.desc } : {}),
+    };
+}
 /** Deep-merge one bind table over its built-in defaults: a user adding a single
- *  bind must not wipe the rest. Each user entry is validated (a `run` string is
- *  required) before it replaces/extends a key. */
-function mergeBinds(base, over) {
+ *  bind must not wipe the rest. Each user entry is normalized before it
+ *  replaces/extends a key. */
+function mergeBinds(base, over, normalize) {
     const out = { ...base };
     if (over !== null && typeof over === 'object') {
         for (const [k, v] of Object.entries(over)) {
-            if (v !== null && typeof v === 'object' && typeof v.run === 'string') {
-                const b = v;
-                out[k] = {
-                    run: b.run,
-                    ...(b.confirm === true ? { confirm: true } : {}),
-                    ...(typeof b.desc === 'string' ? { desc: b.desc } : {}),
-                };
-            }
+            const normalized = normalize(v);
+            if (normalized !== null)
+                out[k] = normalized;
         }
     }
     return out;
@@ -85,9 +146,44 @@ function mergeCanvasNav(raw) {
     const prefixKey = typeof r.prefixKey === 'string' && r.prefixKey.trim() !== '' ? r.prefixKey : defaults.prefixKey;
     return {
         prefixKey,
-        prefixBinds: mergeBinds(defaults.prefixBinds, r.prefixBinds),
-        graphBinds: mergeBinds(defaults.graphBinds, r.graphBinds),
+        prefixBinds: mergeBinds(defaults.prefixBinds, r.prefixBinds, normalizePrefixBind),
+        graphBinds: mergeBinds(defaults.graphBinds, r.graphBinds, normalizeGraphBind),
+    };
+}
+function mergeModelLadders(raw) {
+    const defaults = defaultModelLaddersConfig();
+    if (raw === null || typeof raw !== 'object')
+        return defaults;
+    const r = raw;
+    const out = {
+        anthropic: { ...defaults.anthropic },
+        openai: { ...defaults.openai },
     };
+    if (r.defaultProvider === 'anthropic' || r.defaultProvider === 'openai') {
+        out.defaultProvider = r.defaultProvider;
+    }
+    for (const provider of ['anthropic', 'openai']) {
+        const over = r[provider];
+        if (over === null || typeof over !== 'object')
+            continue;
+        for (const [strength, value] of Object.entries(over)) {
+            if ((strength === 'ultra' || strength === 'strong' || strength === 'medium' || strength === 'light') && typeof value === 'string') {
+                out[provider][strength] = value;
+            }
+        }
+    }
+    return out;
+}
+function mergePersonaStrengths(raw) {
+    const out = {};
+    if (raw === null || typeof raw !== 'object')
+        return out;
+    for (const [persona, value] of Object.entries(raw)) {
+        if (value === 'ultra' || value === 'strong' || value === 'medium' || value === 'light') {
+            out[persona] = value;
+        }
+    }
+    return out;
 }
 function normalizeMode(value, fallback) {
     if (value === true)
@@ -100,7 +196,7 @@ function normalizeMode(value, fallback) {
 }
 function mergeConfig(partial) {
     const defaults = defaultScopeConfig();
-    const schema_version = partial.schema_version === undefined ? defaults.schema_version : partial.schema_version;
+    const schema_version = defaults.schema_version;
     const marketplaces = partial.marketplaces === undefined ? {} : partial.marketplaces;
     const plugins = partial.plugins === undefined ? {} : partial.plugins;
     const au = partial.auto_update;
@@ -118,7 +214,9 @@ function mergeConfig(partial) {
         ? Math.floor(rawMaxPanes)
         : defaults.max_panes_per_window;
     const canvasNav = mergeCanvasNav(partial.canvasNav);
-    return { schema_version, marketplaces, plugins, auto_update, max_panes_per_window, canvasNav };
+    const modelLadders = mergeModelLadders(partial.modelLadders);
+    const personaStrengths = mergePersonaStrengths(partial.personaStrengths);
+    return { schema_version, marketplaces, plugins, auto_update, max_panes_per_window, canvasNav, modelLadders, personaStrengths };
 }
 export function updateConfig(scope, mutate) {
     const cfg = readConfig(scope);

package/dist/core/fault-classifier.d.ts

@@ -0,0 +1,41 @@
+export type FaultLink = 'pi→provider' | 'viewer↔broker' | 'relay↔broker' | 'browser↔relay' | 'cli→exa';
+export type FaultKind = 'rate-limit' | 'overloaded' | 'connection' | 'auth' | 'protocol' | 'other';
+export type FaultRetryDisposition = 'auto' | 'manual' | 'fatal';
+export type FaultRetryOwner = 'sdk' | 'daemon' | 'client';
+export interface FaultRetry {
+    disposition: FaultRetryDisposition;
+    by?: FaultRetryOwner;
+    attempt?: number;
+    max?: number;
+    nextAt?: string;
+}
+export interface Fault {
+    link: FaultLink;
+    op: string;
+    kind: FaultKind;
+    retry: FaultRetry;
+    message: string;
+    since: string;
+    logPath: string;
+    anchorEntryId?: string;
+}
+export interface FaultClassification {
+    kind: FaultKind;
+    disposition: FaultRetryDisposition;
+}
+export interface FaultErrnoLike {
+    code?: unknown;
+    errno?: unknown;
+    message?: unknown;
+}
+export interface FaultHttpLike {
+    status?: unknown;
+    statusText?: unknown;
+    ok?: unknown;
+    message?: unknown;
+}
+export interface FaultWsCloseLike {
+    code?: unknown;
+    reason?: unknown;
+}
+export declare function classify(link: FaultLink, raw: unknown): FaultClassification;

package/dist/core/fault-classifier.js

@@ -0,0 +1,110 @@
+function isRecord(value) {
+    return typeof value === 'object' && value !== null;
+}
+function text(value) {
+    return typeof value === 'string' ? value : '';
+}
+function classifyProviderText(message) {
+    const m = message ?? '';
+    // ORDER MATTERS: rate-limit → overloaded → connection → other.
+    if (/rate.?limit|\b429\b|too many requests|quota/i.test(m))
+        return 'rate-limit';
+    if (/overloaded|\b529\b|\b503\b|capacity|server.{0,3}busy|temporarily unavailable/i.test(m))
+        return 'overloaded';
+    if (/connection|econnreset|etimedout|enotfound|econnrefused|network|fetch failed|socket hang|timed? out|timeout/i.test(m))
+        return 'connection';
+    return 'other';
+}
+function classifyErrno(raw) {
+    const code = text(raw.code) || text(raw.errno);
+    if (code === '')
+        return null;
+    if (/^(ECONNREFUSED|ECONNRESET|ETIMEDOUT|ENOENT|ENOTFOUND|EAI_AGAIN|EPIPE|EHOSTUNREACH|ENETUNREACH)$/i.test(code)) {
+        return 'connection';
+    }
+    return null;
+}
+function classifyHttp(raw) {
+    const status = typeof raw.status === 'number' ? raw.status : null;
+    if (status === null)
+        return null;
+    if (status === 401 || status === 403)
+        return 'auth';
+    if (status === 429)
+        return 'rate-limit';
+    if (status === 503 || status === 529)
+        return 'overloaded';
+    if (status >= 500 && status <= 599)
+        return 'overloaded';
+    if (status >= 400 && status <= 499)
+        return 'protocol';
+    return null;
+}
+function classifyWsClose(raw) {
+    const code = typeof raw.code === 'number' ? raw.code : null;
+    if (code === null)
+        return null;
+    if (code === 1008)
+        return 'protocol';
+    if (code === 1006)
+        return 'connection';
+    if (code === 1011) {
+        const reason = text(raw.reason);
+        if (/no running broker/i.test(reason))
+            return 'connection';
+        return classifyProviderText(reason) === 'connection' ? 'connection' : 'other';
+    }
+    return null;
+}
+function classifyDisposition(link, kind) {
+    if (kind === 'auth' || kind === 'protocol')
+        return 'fatal';
+    if (link === 'pi→provider') {
+        if (kind === 'connection' || kind === 'rate-limit' || kind === 'overloaded')
+            return 'auto';
+        return 'fatal';
+    }
+    return 'manual';
+}
+function rawText(raw) {
+    if (typeof raw === 'string')
+        return raw;
+    if (!isRecord(raw))
+        return '';
+    const candidates = [
+        raw['message'],
+        raw['errorMessage'],
+        raw['reason'],
+        raw['body'],
+        raw['statusText'],
+    ];
+    for (const candidate of candidates) {
+        if (typeof candidate === 'string' && candidate !== '')
+            return candidate;
+    }
+    const nested = raw['error'];
+    if (isRecord(nested)) {
+        const nestedMessage = nested['message'];
+        if (typeof nestedMessage === 'string' && nestedMessage !== '')
+            return nestedMessage;
+        const nestedReason = nested['reason'];
+        if (typeof nestedReason === 'string' && nestedReason !== '')
+            return nestedReason;
+    }
+    return '';
+}
+export function classify(link, raw) {
+    if (isRecord(raw)) {
+        const errno = classifyErrno(raw);
+        if (errno !== null)
+            return { kind: errno, disposition: classifyDisposition(link, errno) };
+        const http = classifyHttp(raw);
+        if (http !== null)
+            return { kind: http, disposition: classifyDisposition(link, http) };
+        const ws = classifyWsClose(raw);
+        if (ws !== null)
+            return { kind: ws, disposition: classifyDisposition(link, ws) };
+    }
+    const kind = classifyProviderText(rawText(raw));
+    return { kind, disposition: classifyDisposition(link, kind) };
+}

package/dist/core/feed/inbox.d.ts

@@ -2,6 +2,10 @@ export type InboxTier = 'critical' | 'urgent' | 'normal' | 'deferred';
 export type InboxKind = 'update' | 'urgent' | 'final' | 'message' | 'completed';
 /** A single inbox entry — a pointer, not a copy of the content. */
 export interface InboxEntry {
+    /** Short stable handle for addressing this entry from the CLI (`feed message
+     *  <id>`). Set when the entry carries an inline body too long to fully inline
+     *  in the digest, so the receiver can read the full text back by id. */
+    id?: string;
     /** ISO 8601 timestamp of delivery. */
     ts: string;
     /** Node id of the sender, or null for system-generated entries. */
@@ -22,6 +26,8 @@ export interface InboxEntry {
  * Fills `ts` (current ISO time). Returns the completed entry.
  */
 export declare function appendInbox(nodeId: string, entry: Omit<InboxEntry, 'ts'>): InboxEntry;
+/** Find one inbox entry by its short `id` handle (see `feed message <id>`). */
+export declare function readInboxEntryById(nodeId: string, id: string): InboxEntry | undefined;
 /**
  * Return all inbox entries strictly after `cursorIso`.
  * When `cursorIso` is undefined, returns every entry in the file.
@@ -36,6 +42,15 @@ export declare function readCursor(nodeId: string): string | undefined;
  * Persist a new cursor ISO for a node's inbox (atomic tmp+rename).
  */
 export declare function writeCursor(nodeId: string, iso: string): void;
+/** True when an entry's inline body is long enough that the digest will clip it
+ *  — the trigger for minting an addressable `id` so the full text stays
+ *  recoverable via `feed message <id>`. */
+export declare function bodyExceedsPreview(e: Pick<InboxEntry, 'data' | 'label'>): boolean;
+/** Clip a body to a bounded preview, reporting whether anything was dropped. */
+export declare function clipBody(body: string): {
+    text: string;
+    clipped: boolean;
+};
 /**
  * Render many unread inbox pointers into one compact digest string.
  *

package/dist/core/feed/inbox.js

@@ -9,6 +9,7 @@
 //   nodes/<id>/inbox.jsonl.cursor   — ISO 8601 of last-read entry (sidecar)
 import { appendFileSync, existsSync, readFileSync, writeFileSync, renameSync, mkdirSync, } from 'node:fs';
 import { dirname } from 'node:path';
+import { randomUUID } from 'node:crypto';
 import { inboxPath } from '../canvas/index.js';
 // ---------------------------------------------------------------------------
 // Cursor sidecar path
@@ -25,6 +26,10 @@ function cursorPath(nodeId) {
  */
 export function appendInbox(nodeId, entry) {
     const full = { ts: new Date().toISOString(), ...entry };
+    // A message that carries an inline body the digest will clip needs a stable
+    // handle so the receiver can read the full text back (`feed message <id>`).
+    if (full.id === undefined && bodyExceedsPreview(full))
+        full.id = randomUUID().slice(0, 8);
     const line = JSON.stringify(full) + '\n';
     // Ensure the parent directory exists (inbox.jsonl lives directly under the
     // node dir, which ensureNodeDirs creates — but guard anyway for callers that
@@ -41,6 +46,10 @@ export function appendInbox(nodeId, entry) {
 // ---------------------------------------------------------------------------
 // Read
 // ---------------------------------------------------------------------------
+/** Find one inbox entry by its short `id` handle (see `feed message <id>`). */
+export function readInboxEntryById(nodeId, id) {
+    return readInboxSince(nodeId, undefined).find((e) => e.id === id);
+}
 /**
  * Return all inbox entries strictly after `cursorIso`.
  * When `cursorIso` is undefined, returns every entry in the file.
@@ -89,11 +98,25 @@ export function writeCursor(nodeId, iso) {
 // ---------------------------------------------------------------------------
 // Coalesce
 // ---------------------------------------------------------------------------
-/** Bounds for inlining a ref-less entry's body in the digest. */
+/** Bounds for inlining a message body's preview in the digest. */
 const BODY_MAX_LINES = 12;
 const BODY_MAX_CHARS = 1000;
+/** The inline body an entry carries (a direct msg / system alert), trimmed.
+ *  Empty for a push pointer (whose body lives at `ref`) or a one-line entry
+ *  whose `label` already IS the whole message. */
+function inlineBody(e) {
+    const body = typeof e.data?.['body'] === 'string' ? e.data['body'].trim() : '';
+    return body === '' || body === e.label ? '' : body;
+}
+/** True when an entry's inline body is long enough that the digest will clip it
+ *  — the trigger for minting an addressable `id` so the full text stays
+ *  recoverable via `feed message <id>`. */
+export function bodyExceedsPreview(e) {
+    const body = inlineBody(e);
+    return body !== '' && clipBody(body).clipped;
+}
 /** Clip a body to a bounded preview, reporting whether anything was dropped. */
-function clipBody(body) {
+export function clipBody(body) {
     let text = body;
     let clipped = false;
     const lines = text.split('\n');
@@ -111,23 +134,26 @@ function clipBody(body) {
  * Render one entry's digest line(s).
  *
  * A push pointer (has a `ref`) stays a pointer — the body lives in the report
- * file, dereferenced on demand by reading that path. A ref-less entry (a direct
- * `node msg` or a system alert) has NO report to dereference; its full body
- * lives only in `data.body`, and `label` is just the first line truncated. So
- * for those we inline the body (bounded) — rendering only the truncated label
- * would strand the rest with nowhere to recover it.
+ * file, dereferenced on demand by reading that path. A direct `node msg` or
+ * system alert has NO report to dereference; its full body lives in the
+ * inbox.jsonl entry itself (`data.body`), so we inline a bounded preview. When
+ * that preview clips, the entry carries a short `id` and we point at the CLI
+ * command that reads the full body back from the jsonl (`feed message <id>`).
  */
 function renderEntry(e) {
-    if (e.ref !== undefined) {
-        return `  [${e.kind}] ${e.label}  (ref: ${e.ref})`;
-    }
-    const body = typeof e.data?.['body'] === 'string' ? e.data['body'].trim() : '';
-    if (body === '' || body === e.label) {
-        return `  [${e.kind}] ${e.label}`;
+    const body = inlineBody(e);
+    if (body === '') {
+        return e.ref !== undefined
+            ? `  [${e.kind}] ${e.label}  (ref: ${e.ref})`
+            : `  [${e.kind}] ${e.label}`;
     }
     const { text, clipped } = clipBody(body);
     const indented = text.split('\n').map((l) => `    ${l}`).join('\n');
-    const more = clipped ? '\n    … (body clipped)' : '';
+    const more = clipped
+        ? (e.id !== undefined
+            ? `\n    … (clipped — full message: \`crtr feed message ${e.id}\`)`
+            : '\n    … (body clipped)')
+        : '';
     return `  [${e.kind}]\n${indented}${more}`;
 }
 /**

package/dist/core/frontmatter.d.ts

@@ -1,18 +1,8 @@
-import { type SkillFrontmatter } from '../types.js';
-export interface ParsedFrontmatter {
-    data: SkillFrontmatter | null;
-    body: string;
-    raw: string;
-}
-export declare function parseFrontmatter(source: string): ParsedFrontmatter;
 export interface ParsedFrontmatterGeneric {
     /** Raw, uncoerced key/value record from the YAML block (null when absent). */
     data: Record<string, unknown> | null;
     body: string;
     raw: string;
 }
-/** Like parseFrontmatter but returns the raw key/value record instead of
- *  coercing to SkillFrontmatter. Used by consumers (e.g. subagents) that read
- *  fields skills don't declare, such as `tools` and `model`. */
+/** Parse a frontmatter block as a raw key/value record. */
 export declare function parseFrontmatterGeneric(source: string): ParsedFrontmatterGeneric;
-export declare function serializeFrontmatter(data: SkillFrontmatter): string;

package/dist/core/frontmatter.js

@@ -1,18 +1,6 @@
 import { parse as parseYaml } from 'yaml';
-import { isSkillType } from '../types.js';
 const FRONTMATTER_RE = /^---\s*\r?\n([\s\S]*?)\r?\n---\s*\r?\n?/;
-export function parseFrontmatter(source) {
-    const match = source.match(FRONTMATTER_RE);
-    if (!match) {
-        return { data: null, body: source, raw: '' };
-    }
-    const raw = match[1];
-    const body = source.slice(match[0].length);
-    return { data: toSkillFrontmatter(parseYamlBlock(raw)), body, raw };
-}
-/** Like parseFrontmatter but returns the raw key/value record instead of
- *  coercing to SkillFrontmatter. Used by consumers (e.g. subagents) that read
- *  fields skills don't declare, such as `tools` and `model`. */
+/** Parse a frontmatter block as a raw key/value record. */
 export function parseFrontmatterGeneric(source) {
     const match = source.match(FRONTMATTER_RE);
     if (!match) {
@@ -22,26 +10,6 @@ export function parseFrontmatterGeneric(source) {
     const body = source.slice(match[0].length);
     return { data: parseYamlBlock(raw), body, raw };
 }
-function toSkillFrontmatter(out) {
-    const fm = {
-        name: scalarToString(out.name) ?? '',
-        description: scalarToString(out.description),
-        keywords: Array.isArray(out.keywords) ? out.keywords.map((k) => String(k)) : undefined,
-        type: isSkillType(out.type) ? out.type : undefined,
-    };
-    return fm;
-}
-/** Coerce a YAML scalar (string/number/boolean) to its string form. A skill's
- *  `name`/`description` are always strings to consumers; native non-string
- *  scalars (a numeric/boolean value) render as their string form, and
- *  non-scalars (null/undefined/array/object) yield undefined. */
-function scalarToString(v) {
-    if (typeof v === 'string')
-        return v;
-    if (typeof v === 'number' || typeof v === 'boolean')
-        return String(v);
-    return undefined;
-}
 /** Parse the inner YAML of a frontmatter block into a key/value record.
  *
  *  ONE strict parser, no fallback. The frontmatter contract IS "valid YAML":
@@ -65,25 +33,3 @@ function normalizeToRecord(parsed) {
     }
     return {};
 }
-export function serializeFrontmatter(data) {
-    const lines = ['---'];
-    lines.push(`name: ${quoteIfNeeded(data.name)}`);
-    if (data.description !== undefined) {
-        lines.push(`description: ${quoteIfNeeded(data.description)}`);
-    }
-    if (data.type !== undefined) {
-        lines.push(`type: ${data.type}`);
-    }
-    if (data.keywords && data.keywords.length) {
-        const inline = `[${data.keywords.map(quoteIfNeeded).join(', ')}]`;
-        lines.push(`keywords: ${inline}`);
-    }
-    lines.push('---');
-    return lines.join('\n') + '\n';
-}
-function quoteIfNeeded(s) {
-    if (/[:#\-\[\]{},&*?|<>=!%@`]/.test(s) || /^\s/.test(s) || /\s$/.test(s)) {
-        return `"${s.replace(/"/g, '\\"')}"`;
-    }
-    return s;
-}