@north-light/api 0.3.580 → 0.3.588

package/dist/core/plugin-app.js

@@ -0,0 +1,58 @@
+// plugin-app.ts -- which installed plugins hold a `crtr_app_` credential, and what that credential is.
+// Read-only; daemon code imports it (the reconcile pass, the credential routes, the read leaf). The CLI does not:
+// it asks crtrd for the credential and never reads the secrets store itself.
+import { apiSocketPath } from './canvas/paths.js';
+import { validatePluginCommands } from './command-plugins/discovery.js';
+import { declaresObjectBlocks, leafPathsBelowRoot, needsAppToken, objectBlocksReasons, streamingLeafPathsBelowRoot } from './plugin-objects-manifest.js';
+import { listInstalledPlugins } from './resolver.js';
+import { pluginAppToken } from './secrets.js';
+/** The space-joined path of every leaf below the plugin's root command, with the command-validation issues. */
+export function pluginLeafPaths(plugin) {
+    const validation = validatePluginCommands(plugin);
+    const roots = validation.manifest?.roots ?? [];
+    return { leafPaths: leafPathsBelowRoot(plugin.name, plugin.manifest, roots), streamingLeafPaths: streamingLeafPathsBelowRoot(plugin.name, plugin.manifest, roots), issues: validation.issues.map((issue) => issue.message) };
+}
+function classify() {
+    const valid = [];
+    const invalid = [];
+    for (const plugin of listInstalledPlugins('user')) {
+        // Every enabled plugin that holds a token or declares object blocks: a provider bundle holds no token but its kinds still reconcile.
+        if (!plugin.enabled || !(needsAppToken(plugin.manifest) || declaresObjectBlocks(plugin.manifest)))
+            continue;
+        const { leafPaths, streamingLeafPaths, issues } = pluginLeafPaths(plugin);
+        const reasons = [...issues, ...objectBlocksReasons(plugin.manifest, { name: plugin.name, leafPaths, streamingLeafPaths })];
+        if (reasons.length === 0)
+            valid.push(plugin);
+        else
+            invalid.push({ plugin, error: reasons.join('; ') });
+    }
+    return { valid, invalid };
+}
+/** Enabled user plugins that hold an app token: not a provider, declaring kinds or scopes or serving over HTTP, with a clean manifest. */
+export function appPlugins() {
+    return classify().valid.filter((plugin) => needsAppToken(plugin.manifest));
+}
+/** Enabled user plugins and provider bundles with a clean manifest that declare `object_kinds`, whether or not they hold a token. */
+export function kindPlugins() {
+    return classify().valid.filter((plugin) => Object.keys(plugin.manifest.object_kinds ?? {}).length > 0);
+}
+/** The enabled plugins and provider bundles that would hold a token or declare object blocks but whose manifest or commands are invalid, with why. */
+export function invalidAppPlugins() {
+    return classify().invalid;
+}
+/** The environment an exec leaf of `plugin` gets, or null when it holds no token. */
+export function pluginAppEnv(plugin) {
+    const held = pluginAppToken(plugin);
+    return held === undefined ? null : { CRTR_APP_TOKEN: held.token, CRTR_DAEMON_SOCKET: apiSocketPath() };
+}
+/** The credential of an app plugin, or null when it is not in `appPlugins()` or holds no token. */
+export function pluginAppCredential(name) {
+    const plugin = appPlugins().find((candidate) => candidate.name === name);
+    if (plugin === undefined)
+        return null;
+    const held = pluginAppToken(name);
+    if (held === undefined)
+        return null;
+    const transport = plugin.manifest.transport;
+    return { plugin, token: held.token, socket: apiSocketPath(), endpoint: transport?.kind === 'http' ? transport.endpoint : null };
+}

package/dist/core/plugin-quarantine.d.ts

@@ -0,0 +1,16 @@
+export interface QuarantinedPlugin {
+    name: string;
+    /** which file was damaged, relative to the plugin root */
+    file: string;
+    reason: string;
+    /** where the directory was moved; absent when the move itself failed and the directory was left in place */
+    movedTo?: string;
+}
+/** Why the plugin's own files cannot be used, or null when they are intact (or the directory is not a plugin). */
+export declare function brokenPluginReason(root: string): {
+    file: string;
+    reason: string;
+} | null;
+/** Quarantine every user-scope plugin directory with a damaged manifest or command file. Never throws:
+ *  a directory that cannot be moved is reported without `movedTo` and left for the tolerant readers to skip. */
+export declare function quarantineBrokenPlugins(now?: () => number): QuarantinedPlugin[];

package/dist/core/plugin-quarantine.js

@@ -0,0 +1,70 @@
+// A plugin directory whose manifest files are damaged — 0 bytes from a write cut short, truncated,
+// not JSON — must not take the daemon down. `quarantineBrokenPlugins` moves each such directory out of
+// `plugins/` into `<scope root>/quarantine/plugins/<name>.<timestamp>` and reports it, so the next
+// install of that plugin (a provider bundle is reinstalled by the daemon's grant sync) starts clean and
+// the damaged bytes stay available for diagnosis.
+import { readFileSync, renameSync, statSync } from 'node:fs';
+import { join, resolve, sep } from 'node:path';
+import { ensureDir, listDirs, pathExists } from './fs-utils.js';
+import { readPluginManifestChecked } from './manifest.js';
+import { bundleSwapInFlightElsewhere } from './plugin-swap-lock.js';
+import { pluginsDir, userScopeRoot } from './scope.js';
+/** Why the plugin's own files cannot be used, or null when they are intact (or the directory is not a plugin). */
+export function brokenPluginReason(root) {
+    const manifest = readPluginManifestChecked(root);
+    if (manifest.status === 'broken')
+        return { file: '.crouter-plugin/plugin.json', reason: manifest.error };
+    if (manifest.status === 'absent')
+        return null;
+    const commands = manifest.manifest.commands;
+    if (typeof commands !== 'string' || commands === '')
+        return null;
+    const path = resolve(root, commands);
+    if (path !== root && !path.startsWith(root + sep))
+        return null;
+    if (!pathExists(path))
+        return null;
+    try {
+        if (statSync(path).size === 0)
+            return { file: commands, reason: 'file is empty (0 bytes)' };
+        JSON.parse(readFileSync(path, 'utf8'));
+    }
+    catch (error) {
+        return { file: commands, reason: error instanceof Error ? error.message : String(error) };
+    }
+    return null;
+}
+/** Quarantine every user-scope plugin directory with a damaged manifest or command file. Never throws:
+ *  a directory that cannot be moved is reported without `movedTo` and left for the tolerant readers to skip. */
+export function quarantineBrokenPlugins(now = Date.now) {
+    const dir = pluginsDir('user');
+    if (dir === null || !pathExists(dir))
+        return [];
+    const scopeRootPath = userScopeRoot();
+    const out = [];
+    for (const name of listDirs(dir)) {
+        const root = join(dir, name);
+        // A package swap in another process is one rename of a staged tree; never move under it.
+        if (bundleSwapInFlightElsewhere(scopeRootPath, name))
+            continue;
+        let broken;
+        try {
+            broken = brokenPluginReason(root);
+        }
+        catch (error) {
+            broken = { file: '.crouter-plugin/plugin.json', reason: String(error) };
+        }
+        if (broken === null)
+            continue;
+        const entry = { name, ...broken };
+        try {
+            const target = join(scopeRootPath, 'quarantine', 'plugins', `${name}.${now()}`);
+            ensureDir(join(scopeRootPath, 'quarantine', 'plugins'));
+            renameSync(root, target);
+            entry.movedTo = target;
+        }
+        catch { /* left in place; readPluginManifest reads it as absent */ }
+        out.push(entry);
+    }
+    return out;
+}

package/dist/core/pool-credential-store.d.ts

@@ -0,0 +1,31 @@
+import type { Credential, CredentialInfo, CredentialStore } from '@earendil-works/pi-ai';
+import { type ManagedProviderId, type SubscriptionCredential } from './subscription-state.js';
+/**
+ * Which pool account pi is handed for a managed provider. Deliberately dumb: pi calls `read()`
+ * mid-turn, so this must be cheap, must not touch the network, and must not make a policy
+ * decision that surprises a turn already in flight. First entry that is healthy and not cooling
+ * wins; ties break on pool order, which is stable and user-controlled (`/provider-sub select`
+ * promotes).
+ *
+ * When every account is cooling or auth-failed we still return the first one rather than
+ * nothing: deciding a turn is unservable belongs to the rotation loop, and an `undefined` here
+ * would make pi's eager launch gate FATAL a node that rotation could still have serviced.
+ */
+export declare function electPoolCredential(providerId: ManagedProviderId, now?: number): Promise<SubscriptionCredential | undefined>;
+export declare class PoolCredentialStore implements CredentialStore {
+    private readonly auth;
+    read(providerId: string): Promise<Credential | undefined>;
+    list(): Promise<readonly CredentialInfo[]>;
+    /**
+     * pi's locked read-modify-write, chiefly its OAuth refresh. The whole transaction — electing
+     * the account, running pi's `fn`, committing the result — happens under the account row locks, because a refresh token is single-use: two brokers electing the same
+     * expired account outside a lock would both spend it and the loser would get a genuine
+     * `invalid_grant`. Electing under the lock is also what guarantees the refreshed token lands
+     * back on exactly the account whose token was spent.
+     *
+     * A managed provider with no pool account is NOT created here — pi must not be able to mint a
+     * managed account behind crouter's login surfaces, which own the account-identity gate.
+     */
+    modify(providerId: string, fn: (current: Credential | undefined) => Promise<Credential | undefined>): Promise<Credential | undefined>;
+    delete(providerId: string): Promise<void>;
+}

package/dist/core/pool-credential-store.js

@@ -0,0 +1,116 @@
+// pool-credential-store.ts — the CredentialStore pi reads managed providers through.
+//
+// Managed-provider OAuth credentials live in the subscription pool, which can hold multiple
+// accounts per provider. This store elects one pool account for pi; non-managed providers pass
+// through to the model_api_keys rows.
+import { CrouterCredentialStore } from './auth-file.js';
+import { MANAGED_PROVIDER_IDS, getProviderLabel, isManagedProvider, modifyElectedSubscription, readSubscriptionPool, removeManagedAccount, } from './subscription-state.js';
+import { registerGateCredentialStore } from './runtime/provider-credential-gate.js';
+/**
+ * Which pool account pi is handed for a managed provider. Deliberately dumb: pi calls `read()`
+ * mid-turn, so this must be cheap, must not touch the network, and must not make a policy
+ * decision that surprises a turn already in flight. First entry that is healthy and not cooling
+ * wins; ties break on pool order, which is stable and user-controlled (`/provider-sub select`
+ * promotes).
+ *
+ * When every account is cooling or auth-failed we still return the first one rather than
+ * nothing: deciding a turn is unservable belongs to the rotation loop, and an `undefined` here
+ * would make pi's eager launch gate FATAL a node that rotation could still have serviced.
+ */
+export async function electPoolCredential(providerId, now = Date.now()) {
+    return electFrom(await readSubscriptionPool(providerId), now);
+}
+function electFrom(pool, now = Date.now()) {
+    return pool.find((entry) => !entry.authFailure && (!entry.rateLimitedUntil || entry.rateLimitedUntil <= now)) ?? pool[0];
+}
+function toCredential(entry) {
+    return {
+        type: 'oauth',
+        refresh: entry.refresh,
+        access: entry.access,
+        expires: entry.expires,
+        ...(entry.accountId ? { accountId: entry.accountId } : {}),
+        // ChatGPT (`openai`) refresh needs the per-login issued OAuth client id.
+        ...(entry.clientId ? { clientId: entry.clientId } : {}),
+    };
+}
+export class PoolCredentialStore {
+    auth = new CrouterCredentialStore();
+    async read(providerId) {
+        if (!isManagedProvider(providerId))
+            return this.auth.read(providerId);
+        const elected = await electPoolCredential(providerId);
+        // No pool account at all: fall through to the model_api_keys rows, which is where a hand-written api_key
+        // for a managed provider still legitimately lives. An OAUTH record there is not served: the
+        // pool owns managed oauth, and nothing outside it can refresh such a record, so serving it
+        // would hand pi a credential that works until its access token expires and then fails every
+        // turn non-retryably. It reads as absent, so the provider reads logged out and `/login` fixes it.
+        if (elected !== undefined)
+            return toCredential(elected);
+        const stored = await this.auth.read(providerId);
+        return stored?.type === 'oauth' ? undefined : stored;
+    }
+    async list() {
+        // Managed providers are reported from the pool alone, on the same rule `read` serves them by:
+        // a managed oauth record in the rows is not a credential this store can honour, and letting
+        // it report configured is how a provider comes to look healthy while every turn fails.
+        const infos = (await this.auth.list()).filter((info) => !(isManagedProvider(info.providerId) && info.type === 'oauth'));
+        for (const providerId of MANAGED_PROVIDER_IDS) {
+            if (infos.some((info) => info.providerId === providerId))
+                continue;
+            // Every pool row carries an OAuth token pair (rows without one are not stored), so pool
+            // occupancy IS a stored credential for pi's purposes.
+            if ((await readSubscriptionPool(providerId)).length > 0)
+                infos.push({ providerId, type: 'oauth' });
+        }
+        return infos;
+    }
+    /**
+     * pi's locked read-modify-write, chiefly its OAuth refresh. The whole transaction — electing
+     * the account, running pi's `fn`, committing the result — happens under the account row locks, because a refresh token is single-use: two brokers electing the same
+     * expired account outside a lock would both spend it and the loser would get a genuine
+     * `invalid_grant`. Electing under the lock is also what guarantees the refreshed token lands
+     * back on exactly the account whose token was spent.
+     *
+     * A managed provider with no pool account is NOT created here — pi must not be able to mint a
+     * managed account behind crouter's login surfaces, which own the account-identity gate.
+     */
+    async modify(providerId, fn) {
+        if (!isManagedProvider(providerId))
+            return this.auth.modify(providerId, fn);
+        if ((await electPoolCredential(providerId)) === undefined) {
+            // A hand-written api_key for a managed provider legitimately lives in the model_api_keys rows (see
+            // `read`), so keep modifying it there. `read` already refuses an oauth record for a managed
+            // provider, so what it returns here is never one.
+            const existing = await this.read(providerId);
+            if (existing !== undefined)
+                return this.auth.modify(providerId, fn);
+            throw new Error(`${getProviderLabel(providerId)} has no account to update — add one with \`crtr sys settings\` or \`/provider-sub ${providerId} add\`.`);
+        }
+        const committed = await modifyElectedSubscription(providerId, (pool) => electFrom(pool), async (entry) => {
+            const next = await fn(toCredential(entry));
+            // Per the CredentialStore contract, `undefined` leaves the entry unchanged. A non-oauth
+            // result cannot be stored in the pool, which holds oauth accounts only.
+            if (next === undefined || next.type !== 'oauth')
+                return undefined;
+            const clientId = next.clientId;
+            return { refresh: next.refresh, access: next.access, expires: next.expires, ...(typeof clientId === 'string' && clientId ? { clientId } : {}) };
+        });
+        return committed === undefined ? undefined : toCredential(committed);
+    }
+    async delete(providerId) {
+        if (!isManagedProvider(providerId))
+            return this.auth.delete(providerId);
+        // pi exposes logout only at provider scope, so managed logout removes the account currently
+        // elected for that provider. `/provider-sub remove` manages a specific named account.
+        const elected = await electPoolCredential(providerId);
+        if (elected !== undefined)
+            await removeManagedAccount(providerId, elected.label);
+        // A managed provider can also be backed by a hand-written model_api_keys api_key, which `read`
+        // serves when no pool account exists. Leaving it behind would make a successful logout
+        // hand the very same credential back on the next read.
+        if ((await this.auth.read(providerId)) !== undefined)
+            await this.auth.delete(providerId);
+    }
+}
+registerGateCredentialStore(new PoolCredentialStore());

package/dist/core/predicate.d.ts

@@ -0,0 +1,65 @@
+/**
+ * Predicate matcher engine — vendored verbatim from pi's frontmatter-rules
+ * extension.
+ *
+ * Source: src/builtin-pi-packages/pi-crtr-extensions/extensions/frontmatter-rules/index.ts
+ *         (the "Condition language" block, functions `asArray` … `evalCondition`).
+ *
+ * The unified document substrate uses this to evaluate a document's `gate`
+ * predicate against a node-config subject (e.g. `orchestration.depth: { gte: 2 }`).
+ *
+ * This is intentionally a COPY, not an import: the bundled pi package is
+ * excluded from crouter's tsc compile unit (tsconfig `exclude`) — it is loaded
+ * by pi's own TS loader at runtime — so compiled core cannot import from it;
+ * cross-boundary imports go extension→core only. The functions are pure
+ * TS over `unknown` / `Record<string, unknown>` with zero external imports, so
+ * vendoring them keeps this module standalone and dependency-free. Keep it in
+ * sync with the source by hand if the matcher language ever changes.
+ *
+ * Condition language (evaluated against the subject object):
+ *   A condition is a map of <field> -> <matcher>, AND-ed across fields.
+ *   `field` may be dotted to reach nested values (e.g. `orchestration.depth`).
+ *
+ *   Matcher forms:
+ *     scalar (string/number/bool/null)
+ *         field === value, OR (if the field is an array) the array includes value
+ *     array  [a, b, c]
+ *         membership/intersection: field is one of these, OR the field array
+ *         shares any element with these
+ *     object { <op>: <arg>, ... }   (multiple ops AND together)
+ *         eq          equals (scalar or array-includes)
+ *         ne          not eq
+ *         in          [..] — field (or any of its array elements) is in the list
+ *         nin         not in
+ *         exists      true|false — field is present / absent
+ *         contains    field array includes this value
+ *         containsAll [..] — field array includes all of these
+ *         containsAny [..] — field array includes any of these
+ *         matches     regex string, case-sensitive (tests String(field); arrays: any)
+ *         imatches    regex string, case-insensitive
+ *         gt gte lt lte   numeric comparison
+ *
+ *   Combinators (reserved keys at any condition level):
+ *     all: [ {..}, {..} ]   every sub-condition true (AND)
+ *     any: [ {..}, {..} ]   at least one true (OR)
+ *     not: { .. }           sub-condition false
+ *   Sibling field matchers next to combinators are AND-ed in.
+ *
+ *   Two load-bearing edge cases preserved from the source:
+ *     - An empty condition (`{}`) is INERT: it returns false, NOT match-all.
+ *     - An unknown op never matches.
+ */
+export declare function asArray(v: unknown): unknown[];
+export declare function scalarEq(a: unknown, b: unknown): boolean;
+export declare function getField(subject: unknown, key: string): unknown;
+export declare function toRegExp(arg: unknown, flags: string): RegExp | null;
+export declare function applyOp(op: string, value: unknown, arg: unknown): boolean;
+export declare function matchField(value: unknown, matcher: unknown): boolean;
+/**
+ * Evaluate a `gate` predicate against a subject object.
+ *
+ * This is the one function consumers call. Returns true iff `condition`
+ * matches `subject`. A null/non-object condition and an empty object both
+ * return false (inert), never match-all.
+ */
+export declare function evalCondition(condition: unknown, subject: Record<string, unknown>): boolean;

package/dist/core/predicate.js

@@ -0,0 +1,191 @@
+/**
+ * Predicate matcher engine — vendored verbatim from pi's frontmatter-rules
+ * extension.
+ *
+ * Source: src/builtin-pi-packages/pi-crtr-extensions/extensions/frontmatter-rules/index.ts
+ *         (the "Condition language" block, functions `asArray` … `evalCondition`).
+ *
+ * The unified document substrate uses this to evaluate a document's `gate`
+ * predicate against a node-config subject (e.g. `orchestration.depth: { gte: 2 }`).
+ *
+ * This is intentionally a COPY, not an import: the bundled pi package is
+ * excluded from crouter's tsc compile unit (tsconfig `exclude`) — it is loaded
+ * by pi's own TS loader at runtime — so compiled core cannot import from it;
+ * cross-boundary imports go extension→core only. The functions are pure
+ * TS over `unknown` / `Record<string, unknown>` with zero external imports, so
+ * vendoring them keeps this module standalone and dependency-free. Keep it in
+ * sync with the source by hand if the matcher language ever changes.
+ *
+ * Condition language (evaluated against the subject object):
+ *   A condition is a map of <field> -> <matcher>, AND-ed across fields.
+ *   `field` may be dotted to reach nested values (e.g. `orchestration.depth`).
+ *
+ *   Matcher forms:
+ *     scalar (string/number/bool/null)
+ *         field === value, OR (if the field is an array) the array includes value
+ *     array  [a, b, c]
+ *         membership/intersection: field is one of these, OR the field array
+ *         shares any element with these
+ *     object { <op>: <arg>, ... }   (multiple ops AND together)
+ *         eq          equals (scalar or array-includes)
+ *         ne          not eq
+ *         in          [..] — field (or any of its array elements) is in the list
+ *         nin         not in
+ *         exists      true|false — field is present / absent
+ *         contains    field array includes this value
+ *         containsAll [..] — field array includes all of these
+ *         containsAny [..] — field array includes any of these
+ *         matches     regex string, case-sensitive (tests String(field); arrays: any)
+ *         imatches    regex string, case-insensitive
+ *         gt gte lt lte   numeric comparison
+ *
+ *   Combinators (reserved keys at any condition level):
+ *     all: [ {..}, {..} ]   every sub-condition true (AND)
+ *     any: [ {..}, {..} ]   at least one true (OR)
+ *     not: { .. }           sub-condition false
+ *   Sibling field matchers next to combinators are AND-ed in.
+ *
+ *   Two load-bearing edge cases preserved from the source:
+ *     - An empty condition (`{}`) is INERT: it returns false, NOT match-all.
+ *     - An unknown op never matches.
+ */
+export function asArray(v) {
+    if (Array.isArray(v))
+        return v;
+    if (v === undefined)
+        return [];
+    return [v];
+}
+// Scalar equality with light, predictable coercion: exact match, or
+// string/number cross-compare so `version: 2` matches a subject "2".
+export function scalarEq(a, b) {
+    if (a === b)
+        return true;
+    if ((typeof a === 'number' || typeof a === 'string') &&
+        (typeof b === 'number' || typeof b === 'string')) {
+        return String(a) === String(b);
+    }
+    return false;
+}
+// Resolve a (possibly dotted) field path against the subject object.
+export function getField(subject, key) {
+    if (subject && typeof subject === 'object' && key in subject) {
+        return subject[key];
+    }
+    if (!key.includes('.'))
+        return undefined;
+    let cur = subject;
+    for (const part of key.split('.')) {
+        if (cur == null || typeof cur !== 'object')
+            return undefined;
+        cur = cur[part];
+    }
+    return cur;
+}
+export function toRegExp(arg, flags) {
+    if (typeof arg !== 'string')
+        return null;
+    try {
+        return new RegExp(arg, flags);
+    }
+    catch {
+        return null;
+    }
+}
+export function applyOp(op, value, arg) {
+    const vals = asArray(value);
+    switch (op) {
+        case 'eq':
+            return Array.isArray(value) ? value.some((v) => scalarEq(v, arg)) : scalarEq(value, arg);
+        case 'ne':
+            return !applyOp('eq', value, arg);
+        case 'in':
+            return asArray(arg).some((a) => vals.some((v) => scalarEq(v, a)));
+        case 'nin':
+            return !applyOp('in', value, arg);
+        case 'exists':
+            return (value !== undefined) === (arg !== false);
+        case 'contains':
+            return vals.some((v) => scalarEq(v, arg));
+        case 'containsAll':
+            return asArray(arg).every((a) => vals.some((v) => scalarEq(v, a)));
+        case 'containsAny':
+            return asArray(arg).some((a) => vals.some((v) => scalarEq(v, a)));
+        case 'matches':
+        case 'imatches': {
+            const re = toRegExp(arg, op === 'imatches' ? 'i' : '');
+            if (!re)
+                return false;
+            return vals.some((v) => (typeof v === 'string' || typeof v === 'number' ? re.test(String(v)) : false));
+        }
+        case 'gt':
+        case 'gte':
+        case 'lt':
+        case 'lte': {
+            const n = Number(value);
+            const t = Number(arg);
+            if (Number.isNaN(n) || Number.isNaN(t))
+                return false;
+            if (op === 'gt')
+                return n > t;
+            if (op === 'gte')
+                return n >= t;
+            if (op === 'lt')
+                return n < t;
+            return n <= t;
+        }
+        default:
+            return false; // unknown op never matches
+    }
+}
+export function matchField(value, matcher) {
+    if (matcher === null || ['string', 'number', 'boolean'].includes(typeof matcher)) {
+        if (Array.isArray(value))
+            return value.some((v) => scalarEq(v, matcher));
+        return scalarEq(value, matcher);
+    }
+    if (Array.isArray(matcher)) {
+        const vals = asArray(value);
+        return matcher.some((m) => vals.some((v) => scalarEq(v, m)));
+    }
+    if (matcher && typeof matcher === 'object') {
+        return Object.entries(matcher).every(([op, arg]) => applyOp(op, value, arg));
+    }
+    return false;
+}
+/**
+ * Evaluate a `gate` predicate against a subject object.
+ *
+ * This is the one function consumers call. Returns true iff `condition`
+ * matches `subject`. A null/non-object condition and an empty object both
+ * return false (inert), never match-all.
+ */
+export function evalCondition(condition, subject) {
+    if (condition == null)
+        return false;
+    if (Array.isArray(condition))
+        return condition.every((sub) => evalCondition(sub, subject));
+    if (typeof condition !== 'object')
+        return false;
+    const c = condition;
+    const hasCombinator = 'all' in c || 'any' in c || 'not' in c;
+    if (hasCombinator) {
+        let ok = true;
+        if ('all' in c)
+            ok = ok && asArray(c.all).every((s) => evalCondition(s, subject));
+        if ('any' in c)
+            ok = ok && asArray(c.any).some((s) => evalCondition(s, subject));
+        if ('not' in c)
+            ok = ok && !evalCondition(c.not, subject);
+        for (const k of Object.keys(c)) {
+            if (k === 'all' || k === 'any' || k === 'not')
+                continue;
+            ok = ok && matchField(getField(subject, k), c[k]);
+        }
+        return ok;
+    }
+    const keys = Object.keys(c);
+    if (keys.length === 0)
+        return false; // empty condition is inert, not match-all
+    return keys.every((k) => matchField(getField(subject, k), c[k]));
+}

package/dist/core/preview-registry.d.ts

@@ -0,0 +1,59 @@
+export declare const SUPPRESS_OUTPUT_LEAVES: ReadonlySet<string>;
+/** True when the leaf at this full help-name path (e.g. "canvas snapshot")
+ *  declares `preview.suppressOutput: true`. */
+export declare function suppressOutputForLeaf(helpName: string): boolean;
+/** Same lookup from argv tokens (e.g. ['node', 'inspect', 'snapshot', 'abc'])
+ *  instead of a pre-joined help name. Matches a registered leaf name against
+ *  a *prefix* of the tokens, not the whole joined tail, so a leaf's own
+ *  positional arguments (e.g. the snapshot id in `node inspect snapshot
+ *  abc`) don't prevent the match. */
+export declare function suppressOutputForPath(tokens: readonly string[]): boolean;
+export declare const HELP_ICON: string;
+/** Glyphs for the plain agent tools the attach viewer re-skins (render/tool-calls.ts).
+ *  Same registry as the crtr command icons so every Nerd Font codepoint the viewer
+ *  paints lives in one file: terminal for `bash`, file-text for `read`, floppy for
+ *  `write` (content committed to disk), pencil-square for `edit`. */
+export declare const TOOL_ICON: Readonly<Record<'bash' | 'read' | 'write' | 'edit', string>>;
+/** Per-leaf overrides, keyed by full leaf help-name path (e.g. "doc
+ *  lint"), same shape as SUPPRESS_OUTPUT_LEAVES. */
+export declare const LEAF_ICON_CP: Record<string, number>;
+/** Resolve the Nerd Font glyph for a command's argv tokens: the longest
+ *  matching LEAF_ICON_CP prefix, else the tokens[0] family glyph, else the
+ *  generic ◆ fallback for an unmapped family. */
+export declare function iconForPath(tokens: readonly string[]): string;
+export type SummaryTone = 'plain' | 'success' | 'error' | 'warning' | 'muted' | 'accent';
+export interface SummaryLine {
+    text: string;
+    tone?: SummaryTone;
+}
+export interface CrtrPreview {
+    path: string;
+    result?: Record<string, unknown>;
+    jsonl?: Record<string, unknown>[];
+    error?: Record<string, unknown>;
+}
+/** Every crtr invocation's own structured result in one bash tool result, in
+ *  invocation order — mirrored onto `details` by the canvas preview extension
+ *  (pi-extensions/canvas-preview-result.ts), and present on live tool events and
+ *  on rebuilt snapshot messages alike.
+ *
+ *  `crtrPreviews` carries every invocation in the call; `crtrPreview` (the last
+ *  record alone) is all a transcript persisted before the channel became a list
+ *  can offer, so both are read. This validates only the transport envelope —
+ *  command-owned summaries validate the fields they use. */
+export declare function crtrPreviewRecords(result: unknown): CrtrPreview[];
+type SummaryInput = {
+    result?: Record<string, unknown>;
+    jsonl?: Record<string, unknown>[];
+    error?: Record<string, unknown>;
+};
+type Summarizer = (input: SummaryInput, tokens: readonly string[]) => SummaryLine[] | null;
+export declare const SUMMARIZERS: ReadonlyArray<{
+    path: string;
+    run: Summarizer;
+}>;
+/** Summarize an exact CLI result record. The recorded path is authoritative:
+ * shell tokenization is used only for an invocation's static icon/help chrome,
+ * never to identify or decode the returned leaf data. */
+export declare function summarizePath(preview: CrtrPreview, tokens?: readonly string[]): SummaryLine[] | null;
+export {};