@kognai/tool-router 0.0.0-stage → 0.1.0

package/dist/catalog/lifecycle.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Trust state and lifecycle transitions (plan.md S1, threat T2). quarantined -> reviewed -> verified; any state ->
+ * revoked; revoked is terminal. A hash change on a reviewed or verified external row forces it back to quarantined.
+ * Native Kognai rows start verified at ingest (code owned and reviewed in the repo); that is an initial state, not a
+ * transition. Who may move an outside tool to verified is the CTO desk (decision D10): `by` is recorded on every event.
+ */
+import type { Lifecycle, ToolRecord, TrustState } from '../types/tool';
+export declare function canTransition(from: TrustState, to: TrustState): boolean;
+export declare function canMoveLifecycle(from: Lifecycle, to: Lifecycle): boolean;
+/** The authority allowed to move an outside tool into reviewed or verified (decision D10). */
+export declare const VERIFY_AUTHORITY = "cto-desk";
+/** Checks a requested trust move, including who asks. Returns null when allowed, else the reason. */
+export declare function trustMoveProblem(rec: Pick<ToolRecord, 'origin' | 'trust_state'>, to: TrustState, by: string): string | null;
+/**
+ * Hash drift: when a reviewed or verified row from outside Kognai arrives with a different schema or implementation
+ * hash, the new row is quarantined. Native Kognai rows keep their state (their code is in the repo).
+ */
+export declare function trustAfterDrift(prev: Pick<ToolRecord, 'origin' | 'trust_state' | 'schema_hash' | 'implementation_hash'>, next: {
+    schema_hash: string;
+    implementation_hash: string | null;
+}): {
+    trust: TrustState;
+    drifted: boolean;
+};

package/dist/catalog/lifecycle.js

@@ -0,0 +1,51 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.VERIFY_AUTHORITY = void 0;
+exports.canTransition = canTransition;
+exports.canMoveLifecycle = canMoveLifecycle;
+exports.trustMoveProblem = trustMoveProblem;
+exports.trustAfterDrift = trustAfterDrift;
+const TRUST = {
+    quarantined: ['reviewed', 'revoked'],
+    reviewed: ['verified', 'quarantined', 'deprecated', 'revoked'],
+    verified: ['quarantined', 'deprecated', 'revoked'],
+    deprecated: ['revoked'],
+    revoked: [],
+};
+function canTransition(from, to) {
+    return TRUST[from]?.includes(to) ?? false;
+}
+const LIFE = {
+    draft: ['active', 'retired'],
+    active: ['deprecated', 'retired'],
+    deprecated: ['retired', 'active'],
+    retired: [],
+};
+function canMoveLifecycle(from, to) {
+    return LIFE[from]?.includes(to) ?? false;
+}
+/** The authority allowed to move an outside tool into reviewed or verified (decision D10). */
+exports.VERIFY_AUTHORITY = 'cto-desk';
+/** Checks a requested trust move, including who asks. Returns null when allowed, else the reason. */
+function trustMoveProblem(rec, to, by) {
+    if (!canTransition(rec.trust_state, to))
+        return `${rec.trust_state} -> ${to} is not an allowed transition`;
+    if ((to === 'verified' || to === 'reviewed') && rec.origin !== 'kognai' && by !== exports.VERIFY_AUTHORITY) {
+        return `only ${exports.VERIFY_AUTHORITY} may mark an outside tool ${to} (decision D10)`;
+    }
+    return null;
+}
+/**
+ * Hash drift: when a reviewed or verified row from outside Kognai arrives with a different schema or implementation
+ * hash, the new row is quarantined. Native Kognai rows keep their state (their code is in the repo).
+ */
+function trustAfterDrift(prev, next) {
+    const drifted = prev.schema_hash !== next.schema_hash || (prev.implementation_hash ?? null) !== (next.implementation_hash ?? null);
+    if (prev.trust_state === 'revoked')
+        return { trust: 'revoked', drifted };
+    if (!drifted)
+        return { trust: prev.trust_state, drifted };
+    if (prev.origin === 'kognai')
+        return { trust: prev.trust_state, drifted };
+    return { trust: 'quarantined', drifted };
+}

package/dist/catalog/memory-store.d.ts

@@ -0,0 +1,49 @@
+import type { CatalogStore, TrustEvent } from '../types/ports';
+import type { ToolRecord, TrustState } from '../types/tool';
+export interface IndexEntry {
+    id: string;
+    version: string;
+    schema_hash: string;
+    content_sha: string;
+    trust_state: TrustState;
+    lifecycle: string;
+    latest: boolean;
+}
+/** Hash of what routing reads from a row: everything but ingestion and retrieval times. */
+export declare const contentSha: (r: ToolRecord) => string;
+export declare class MemoryCatalogStore implements CatalogStore {
+    protected rows: Map<string, ToolRecord>;
+    protected latestVersion: Map<string, string>;
+    protected trustEvents: TrustEvent[];
+    protected vecs: Map<string, {
+        dims: number;
+        ids: string[];
+        data: Float32Array;
+    }>;
+    private snap;
+    constructor(rows?: ToolRecord[]);
+    protected key: (id: string, version: string) => string;
+    index(): IndexEntry[];
+    snapshotId(): string;
+    all(): Iterable<ToolRecord>;
+    latest(): Iterable<ToolRecord>;
+    get(id: string, version?: string): ToolRecord | null;
+    upsert(rows: ToolRecord[]): {
+        added: number;
+        versioned: number;
+        unchanged: number;
+    };
+    setTrust(id: string, version: string, to: TrustState, by: string, why: string): void;
+    recordEvent(e: TrustEvent): void;
+    events(): TrustEvent[];
+    vectors(model: string): {
+        dims: number;
+        ids: string[];
+        data: Float32Array;
+    } | null;
+    setVectors(model: string, v: {
+        dims: number;
+        ids: string[];
+        data: Float32Array;
+    }): void;
+}

package/dist/catalog/memory-store.js

@@ -0,0 +1,92 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MemoryCatalogStore = exports.contentSha = void 0;
+/**
+ * In memory CatalogStore: tests, the benchmark, and the base of the file store. Rows are keyed by id and version;
+ * `latest` follows ingestion order. The snapshot id hashes the index (id, version, schema hash, content hash, trust,
+ * lifecycle), never a timestamp, so the same inputs give the same snapshot id and any change routing can see (a new
+ * capability tag, a sanitised description) gives a new one.
+ */
+const hash_1 = require("../hash");
+const lifecycle_1 = require("./lifecycle");
+/** Hash of what routing reads from a row: everything but ingestion and retrieval times. */
+const contentSha = (r) => (0, hash_1.sha256)((0, hash_1.canonical)({ ...r, ingested_at: '', provenance: r.provenance.map((p) => ({ ...p, retrieved_at: '' })) })).slice(0, 16);
+exports.contentSha = contentSha;
+class MemoryCatalogStore {
+    rows = new Map();
+    latestVersion = new Map();
+    trustEvents = [];
+    vecs = new Map();
+    snap = null;
+    constructor(rows = []) { if (rows.length)
+        this.upsert(rows); }
+    key = (id, version) => `${id}@${version}`;
+    index() {
+        return [...this.rows.values()]
+            .map((r) => ({ id: r.id, version: r.version, schema_hash: r.schema_hash, content_sha: (0, exports.contentSha)(r), trust_state: r.trust_state, lifecycle: r.lifecycle, latest: this.latestVersion.get(r.id) === r.version }))
+            .sort((a, b) => (a.id < b.id ? -1 : a.id > b.id ? 1 : a.version < b.version ? -1 : a.version > b.version ? 1 : 0));
+    }
+    snapshotId() {
+        if (!this.snap)
+            this.snap = `cat_${(0, hash_1.sha256)((0, hash_1.canonical)(this.index())).slice(0, 16)}`;
+        return this.snap;
+    }
+    all() { return this.rows.values(); }
+    *latest() {
+        for (const [id, v] of this.latestVersion) {
+            const r = this.rows.get(this.key(id, v));
+            if (r)
+                yield r;
+        }
+    }
+    get(id, version) {
+        const v = version ?? this.latestVersion.get(id);
+        return v === undefined ? null : this.rows.get(this.key(id, v)) || null;
+    }
+    upsert(rows) {
+        let added = 0;
+        let versioned = 0;
+        let unchanged = 0;
+        for (const r of rows) {
+            const k = this.key(r.id, r.version);
+            const existing = this.rows.get(k);
+            if (existing) {
+                if ((0, hash_1.canonical)({ ...existing, ingested_at: '' }) === (0, hash_1.canonical)({ ...r, ingested_at: '' })) {
+                    unchanged++;
+                    continue;
+                }
+                this.rows.set(k, r);
+                unchanged++; // same id and version: metadata refreshed in place (trust, links)
+                continue;
+            }
+            if (this.latestVersion.has(r.id))
+                versioned++;
+            else
+                added++;
+            this.rows.set(k, r);
+            this.latestVersion.set(r.id, r.version);
+        }
+        this.snap = null;
+        return { added, versioned, unchanged };
+    }
+    setTrust(id, version, to, by, why) {
+        const r = this.get(id, version);
+        if (!r)
+            throw new Error(`no row ${id}@${version}`);
+        const problem = (0, lifecycle_1.trustMoveProblem)(r, to, by);
+        if (problem)
+            throw new Error(problem);
+        this.rows.set(this.key(id, version), { ...r, trust_state: to, last_validated: to === 'verified' ? new Date().toISOString() : r.last_validated });
+        this.recordEvent({ at: new Date().toISOString(), id, version, from: r.trust_state, to, by, why });
+        this.snap = null;
+    }
+    recordEvent(e) { this.trustEvents.push(e); }
+    events() { return [...this.trustEvents]; }
+    vectors(model) { return this.vecs.get(model) || null; }
+    setVectors(model, v) {
+        if (v.data.length !== v.dims * v.ids.length)
+            throw new Error('vector data length does not match ids x dims');
+        this.vecs.set(model, v);
+    }
+}
+exports.MemoryCatalogStore = MemoryCatalogStore;

package/dist/catalog/risk.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Risk classes of an operation, derived at ingestion (plan.md S1 rule 3). Evidence only ever adds classes: unknown
+ * side effects add network and data_modification; cue words in the text add the stricter class; nothing in provider
+ * text can remove one. read_only is given only when every known side effect is a read and no stricter class applies.
+ */
+import type { JSONSchema, Origin, RiskClass, SideEffect } from '../types/tool';
+export declare const RISK_CUES: Array<[RiskClass, RegExp]>;
+export declare function urlFromUser(input: JSONSchema | null | undefined): boolean;
+export declare function takesDestination(input: JSONSchema | null | undefined): boolean;
+export interface RiskInput {
+    origin: Origin;
+    side_effects: SideEffect[] | null | undefined;
+    scopes?: string[];
+    text: string;
+    input_schema?: JSONSchema | null;
+    external_network: boolean;
+}
+export declare function deriveRisk(r: RiskInput): {
+    risk: RiskClass[];
+    side_effects: SideEffect[];
+    url_from_user: boolean;
+};

package/dist/catalog/risk.js

@@ -0,0 +1,73 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RISK_CUES = void 0;
+exports.urlFromUser = urlFromUser;
+exports.takesDestination = takesDestination;
+exports.deriveRisk = deriveRisk;
+const fold = (s) => String(s || '').normalize('NFKD').replace(/[̀-ͯ]/g, '').toLowerCase();
+exports.RISK_CUES = [
+    ['payment', /\b(transfer (funds|money|usdc|sol|eth|btc|tokens?|crypto)|send (funds|money|usdc|sol|eth|btc|crypto|tokens?|payments?)|withdraw|make (a )?payments?|pay (an? )?(invoice|bill|merchant)|(buy|sell|swap|trade) (tokens?|crypto|coins?|shares|stocks?|nfts?|usdc|sol|eth|btc)|execute (a )?(trade|swap|order|payment)|place (an? )?(trade|order)|token swaps?|trading bot)\b/],
+    ['destructive', /\b(delete|deletes|deleting|remove (files?|records?|rows?|users?|repos?)|erase|wipe|destroy|drop (table|database|schema)|purge|truncate|rm -rf)\b/],
+    ['publish_or_message', /\b(send (an? )?(emails?|messages?|sms|texts?|dms?|tweets?|notifications?)|post (to|on) |publish(es|ing)? (to|on|a|posts?)|tweet(s|ing)? |reply to (emails?|messages?|comments?|tweets?)|send(s|ing)? emails|outbound (email|sms|calls?))/],
+    ['privileged_infra', /\b(deploy(s|ing|ment)?|ssh|shell commands?|execute (code|commands?|scripts?)|run (code|commands?|scripts?|shell)|kubernetes|kubectl|terraform|docker|root access|sudo|dns records?|firewall rules?|provision (servers?|vms?|infrastructure)|cloud infrastructure)\b/],
+    ['sensitive_data', /\b(emails?|inbox|gmail|outlook|mailbox|calendar|google drive|onedrive|contacts|passwords?|credentials?|medical records?|health records?|patient data|bank accounts?|iban|passport|social security|private keys?|seed phrase|direct messages?)\b/],
+];
+/** Input property names that mean "a URL the caller supplies" (no fetch from chat). */
+const URL_PROP = /^(url|uri|link|href|page_url|target_url|website|site|source_url|image_url|endpoint|webhook|callback_url)$/i;
+/** Input property names that mean "where money goes" (security.txt rule 1). */
+const DEST_PROP = /^(to|recipient|recipient_address|destination|destination_address|to_address|address|payto|pay_to|receiver|wallet_address|beneficiary)$/i;
+const props = (s) => {
+    const p = s && typeof s === 'object' ? s.properties : null;
+    return p && typeof p === 'object' ? p : {};
+};
+function urlFromUser(input) {
+    for (const [k, v] of Object.entries(props(input))) {
+        if (URL_PROP.test(k))
+            return true;
+        if (v && typeof v === 'object' && (v.format === 'uri' || v.format === 'url'))
+            return true;
+        if (k === 'body' && urlFromUser(v))
+            return true;
+    }
+    return false;
+}
+function takesDestination(input) {
+    for (const [k, v] of Object.entries(props(input))) {
+        if (DEST_PROP.test(k))
+            return true;
+        if (k === 'body' && takesDestination(v))
+            return true;
+    }
+    return false;
+}
+const SIDE_RISK = {
+    none: [], read: [], write: ['data_modification'], publish: ['publish_or_message'], message: ['publish_or_message'],
+    payment: ['payment'], delete: ['destructive', 'data_modification'], infra: ['privileged_infra'],
+};
+function deriveRisk(r) {
+    const out = new Set();
+    const known = Array.isArray(r.side_effects) && r.side_effects.length > 0;
+    const side = known ? [...new Set(r.side_effects)] : [];
+    if (!known) {
+        out.add('network');
+        out.add('data_modification');
+    }
+    for (const s of side)
+        for (const c of SIDE_RISK[s] || [])
+            out.add(c);
+    const t = fold(r.text);
+    for (const [cls, re] of exports.RISK_CUES)
+        if (re.test(t))
+            out.add(cls);
+    for (const sc of r.scopes || [])
+        if (/mail|gmail|calendar|drive|contacts|message|inbox/i.test(sc))
+            out.add('sensitive_data');
+    const url = urlFromUser(r.input_schema);
+    if (url || r.external_network)
+        out.add('network');
+    const strict = ['data_modification', 'publish_or_message', 'payment', 'destructive', 'privileged_infra'];
+    if (known && side.every((s) => s === 'read' || s === 'none') && !strict.some((c) => out.has(c)))
+        out.add('read_only');
+    const order = ['read_only', 'network', 'data_modification', 'publish_or_message', 'payment', 'destructive', 'sensitive_data', 'privileged_infra'];
+    return { risk: order.filter((c) => out.has(c)), side_effects: side, url_from_user: url };
+}

package/dist/catalog/sanitise.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Untrusted provider text to description_safe (threat T1). External descriptions are data (security.txt rule 13):
+ * this strips control, zero width and bidi characters, HTML, markdown links and images, collapses whitespace, caps the
+ * length at 512, drops sentences that read as instructions to a model or a ranker, and thins keyword stuffing. The raw
+ * text is kept outside the record by hash only and is never shown to a model.
+ */
+export type SanitiseFlag = 'control_chars' | 'zero_width' | 'bidi' | 'html' | 'md_link' | 'md_image' | 'url' | 'injection' | 'repetition' | 'truncated' | 'empty';
+export interface SanitiseResult {
+    text: string;
+    flags: SanitiseFlag[];
+}
+export declare const MAX_SAFE = 512;
+/** Sentences that address a model, a ranker or the reader with instructions. Matched after folding. */
+export declare const INJECTION_PATTERNS: RegExp[];
+export declare function sanitise(raw: string): SanitiseResult;
+/** Short form for summaries (200 chars), same rules. */
+export declare function sanitiseShort(raw: string, max?: number): string;

package/dist/catalog/sanitise.js

@@ -0,0 +1,109 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.INJECTION_PATTERNS = exports.MAX_SAFE = void 0;
+exports.sanitise = sanitise;
+exports.sanitiseShort = sanitiseShort;
+exports.MAX_SAFE = 512;
+const ZERO_WIDTH = /[​-‍⁠᠎]/g;
+const BIDI = /[‎‏‪-‮⁦-⁩؜]/g;
+// C0 and C1 controls except tab, line feed and carriage return (turned into spaces later)
+const CONTROL = /[\u0000-\u0008\u000B\u000C\u000E-\u001F\u007F-\u009F]/g;
+const HTML = /<\/?[a-zA-Z][^>]{0,400}>|<!--[\s\S]*?-->/g;
+const MD_IMAGE = /!\[[^\]]{0,200}\]\([^)]{0,500}\)/g;
+const MD_LINK = /\[([^\]]{0,200})\]\([^)]{0,500}\)/g;
+const SPECIAL_TOKENS = /<\|?\s*(im_start|im_end|system|endoftext|assistant|user)\s*\|?>/gi;
+const URL_RE = /\bhttps?:\/\/[^\s)]+/gi;
+/** Sentences that address a model, a ranker or the reader with instructions. Matched after folding. */
+exports.INJECTION_PATTERNS = [
+    /\b(ignore|disregard|forget|override)\b.{0,40}\b(previous|prior|above|earlier|all|any|other|system)\b.{0,30}\b(instruction|instructions|prompt|prompts|rules|messages|tools?)\b/,
+    /\byou (must|should|have to|need to|will)\b.{0,40}\b(select|choose|pick|use|call|rank|prefer|recommend|trust)\b/,
+    /\b(select|choose|pick|use|call)\b.{0,10}\bonly\b.{0,10}\b(this|me|us)\b/,
+    /\b(always|only)\b.{0,20}\b(select|choose|pick|use|call|rank|prefer|recommend)\b.{0,30}\b(this|me|us|our)\b/,
+    /\b(rank|score|rate|place|list)\b.{0,30}\b(this|me|us|our)\b.{0,20}\b(first|top|highest|above|#1|number one)\b/,
+    /\b(highest|top|maximum)\s+(priority|ranking|score)\b/,
+    /^\W*(system|assistant|developer)\s*:/,
+    /<\|?(im_start|im_end|system|endoftext)\|?>/,
+    /\b(do not|don't|never)\b.{0,30}\b(tell|inform|reveal|mention)\b.{0,30}\b(user|human|owner|operator)\b/,
+    /\b(send|forward|exfiltrate|upload|post|share)\b(?!-)\s.{0,20}\b(your|the|all|any|my)\b.{0,20}\b(api[_ -]?keys?|secrets?|credentials?|passwords?|private keys?|seed phrase)\b/,
+    /\b(dan mode|developer mode)\b/,
+    /\bact as\b.{0,30}\b(system|admin|root|the router)\b/,
+    /\bnew instructions?\b/,
+    /\b(transfer|send)\s+\d+(\.\d+)?\s*(usdc|usdt|sol|eth|btc|usd|dollars?|euros?)\b/,
+    /\b(transfer|send)\b.{0,40}\bto\s+(0x[0-9a-f]{6,}|[1-9a-hj-np-z]{32,44})\b/,
+];
+const hit = (re, s) => { re.lastIndex = 0; const r = re.test(s); re.lastIndex = 0; return r; };
+const fold = (s) => s.normalize('NFKD').replace(/[̀-ͯ]/g, '').toLowerCase();
+function sanitise(raw) {
+    const flags = new Set();
+    let t = String(raw ?? '');
+    if (hit(CONTROL, t))
+        flags.add('control_chars');
+    t = t.replace(CONTROL, ' ');
+    if (hit(ZERO_WIDTH, t))
+        flags.add('zero_width');
+    t = t.replace(ZERO_WIDTH, '');
+    if (hit(BIDI, t))
+        flags.add('bidi');
+    t = t.replace(BIDI, '');
+    t = t.normalize('NFKC');
+    // chat template tokens end a sentence and mark the text as an injection attempt
+    if (hit(SPECIAL_TOKENS, t))
+        flags.add('injection');
+    t = t.replace(SPECIAL_TOKENS, '. ');
+    if (hit(MD_IMAGE, t))
+        flags.add('md_image');
+    t = t.replace(MD_IMAGE, ' ');
+    if (hit(MD_LINK, t))
+        flags.add('md_link');
+    t = t.replace(MD_LINK, '$1');
+    if (hit(HTML, t))
+        flags.add('html');
+    t = t.replace(HTML, ' ');
+    if (hit(URL_RE, t))
+        flags.add('url');
+    t = t.replace(URL_RE, ' ');
+    t = t.replace(/[`*_~#>|]+/g, ' ').replace(/\s+/g, ' ').trim();
+    // drop sentences that carry instructions
+    const sentences = t.split(/(?<=[.!?;])\s+|\s+[-–—]\s+/);
+    const kept = [];
+    for (const s of sentences) {
+        const f = fold(s);
+        if (exports.INJECTION_PATTERNS.some((re) => re.test(f))) {
+            flags.add('injection');
+            continue;
+        }
+        kept.push(s);
+    }
+    t = kept.join(' ');
+    // thin keyword stuffing: a word may appear at most 3 times
+    const counts = new Map();
+    const words = t.split(' ');
+    const thinned = [];
+    for (const w of words) {
+        const k = fold(w).replace(/[^\p{L}\p{N}]+/gu, '');
+        if (!k) {
+            thinned.push(w);
+            continue;
+        }
+        const n = (counts.get(k) || 0) + 1;
+        counts.set(k, n);
+        if (n > 3) {
+            flags.add('repetition');
+            continue;
+        }
+        thinned.push(w);
+    }
+    t = thinned.join(' ').replace(/\s+/g, ' ').trim();
+    if ([...t].length > exports.MAX_SAFE) {
+        flags.add('truncated');
+        t = [...t].slice(0, exports.MAX_SAFE - 1).join('').trimEnd() + '…';
+    }
+    if (!t)
+        flags.add('empty');
+    return { text: t, flags: [...flags].sort() };
+}
+/** Short form for summaries (200 chars), same rules. */
+function sanitiseShort(raw, max = 200) {
+    const { text } = sanitise(raw);
+    return [...text].length > max ? [...text].slice(0, max - 1).join('').trimEnd() + '…' : text;
+}

package/dist/classify/classifier.d.ts

@@ -0,0 +1,12 @@
+/**
+ * classify(): rules first; the ClassifierPort (ClawRouter, local rung, $0) only when all of these hold: the rules'
+ * confidence is under 0.5, TOOL_ROUTER_MODEL_FALLBACK is on, a port is wired, and the rules did not already decide
+ * no_tool. Only the request text is sent, never tool text (T1). The answer is validated against the taxonomy: unknown
+ * capability ids and unknown labels are dropped, malformed answers ignored. Risk classes stay the rules' classes plus
+ * the default risk of any capability the model added: a model answer can add risk, never remove it.
+ */
+import type { KtrFlags } from '../flags';
+import type { ClassifierPort } from '../types/ports';
+import type { CallerContext, Classification } from '../types/route';
+export declare const FALLBACK_THRESHOLD = 0.5;
+export declare function classify(text: string, ctx: Partial<CallerContext>, flags: Pick<KtrFlags, 'modelFallback' | 'stopped'>, port?: ClassifierPort | null): Promise<Classification>;

package/dist/classify/classifier.js

@@ -0,0 +1,52 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FALLBACK_THRESHOLD = void 0;
+exports.classify = classify;
+const route_1 = require("../types/route");
+const rules_1 = require("./rules");
+const taxonomy_1 = require("./taxonomy");
+exports.FALLBACK_THRESHOLD = 0.5;
+async function classify(text, ctx, flags, port) {
+    const r = (0, rules_1.classifyRules)(text, ctx);
+    const base = {
+        task_complexity: r.task_complexity, risk_classes: r.risk_classes, requirement: r.requirement,
+        capabilities: r.capabilities.map((c) => c.id), hits: r.capabilities, confidence: r.confidence, method: 'rules',
+        language: r.language, args_known: r.args_known, reasoning_cues: r.reasoning_cues, data_spans: r.data_spans,
+    };
+    const eligible = r.confidence < exports.FALLBACK_THRESHOLD && flags.modelFallback && !flags.stopped && !!port && r.requirement !== 'no_tool';
+    if (!eligible)
+        return base;
+    let answer = null;
+    try {
+        answer = await port.classify(String(text).slice(0, 600), { capabilities: taxonomy_1.CAPABILITY_IDS, requirements: route_1.REQUIREMENTS, complexities: route_1.TASK_COMPLEXITIES });
+    }
+    catch {
+        answer = null;
+    }
+    if (!answer || !Array.isArray(answer.capabilities))
+        return base;
+    const caps = [...new Set(answer.capabilities.map(String).filter((c) => taxonomy_1.CAPABILITY_IDS.includes(c)))];
+    const requirement = route_1.REQUIREMENTS.includes(answer.requirement) ? answer.requirement : null;
+    const complexity = route_1.TASK_COMPLEXITIES.includes(answer.task_complexity) ? answer.task_complexity : null;
+    if (!caps.length && !requirement)
+        return base;
+    const merged = [...new Set([...base.capabilities, ...caps])];
+    const risk = new Set(base.risk_classes);
+    for (const c of caps)
+        for (const x of (0, taxonomy_1.capabilityById)(c).default_risk)
+            risk.add(x);
+    const needsTool = merged.some((c) => (0, taxonomy_1.capabilityById)(c).needs_tool);
+    const finalReq = requirement === 'no_eligible_tool' ? 'tool' : requirement ?? (needsTool ? 'tool' : merged.length ? 'no_tool' : base.requirement);
+    const order = ['read_only', 'network', 'data_modification', 'publish_or_message', 'payment', 'destructive', 'sensitive_data', 'privileged_infra'];
+    const conf = typeof answer.confidence === 'number' && answer.confidence >= 0 && answer.confidence <= 1 ? answer.confidence : 0.5;
+    return {
+        ...base,
+        capabilities: merged,
+        hits: [...base.hits, ...caps.filter((c) => !base.capabilities.includes(c)).map((id) => ({ id, confidence: conf, span: '(model)' }))],
+        requirement: finalReq === 'tool' && !needsTool ? 'no_tool' : finalReq,
+        task_complexity: base.task_complexity === 'REASONING' ? 'REASONING' : complexity ?? base.task_complexity,
+        risk_classes: order.filter((c) => risk.has(c)),
+        confidence: Number(Math.max(base.confidence, Math.min(conf, 0.7)).toFixed(2)),
+        method: 'model',
+    };
+}

package/dist/classify/decompose.d.ts

@@ -0,0 +1,10 @@
+/**
+ * decompose(): a classification to a DAG of atomic operations (plan.md S2). Known chains use templates; anything else
+ * becomes one node per capability in mention order, sequential when the text chains the steps ("then", "and send
+ * it"), parallel otherwise. Templates are fixed acyclic shapes and generic edges only point to earlier nodes, so a
+ * cycle cannot be built; topoOrder() checks it anyway.
+ */
+import type { Classification, PlanNode } from '../types/route';
+export declare function decompose(c: Classification, text?: string): PlanNode[];
+/** Topological order; throws on a cycle or an unknown dependency. */
+export declare function topoOrder(nodes: PlanNode[]): string[];

package/dist/classify/decompose.js

@@ -0,0 +1,107 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.decompose = decompose;
+exports.topoOrder = topoOrder;
+const taxonomy_1 = require("./taxonomy");
+const text_1 = require("./text");
+const rules_1 = require("./rules");
+const VIDEO_CHAIN = ['script.write', 'character.design', 'video.generate', 'voice.speak', 'video.edit'];
+const RICH_VIDEO = /(?<![\p{L}])(cinematic|characters?|consistent|dialogue|scenes?|story|talking|conversation|personnages?|\d{2,3} ?(s|sec|secondes?|seconds?)|minutes?)(?![\p{L}])/u;
+const SEARCHES = ['literature.search', 'trial.search', 'patent.search', 'web.search', 'news.search'];
+const READS_FOR_EXTRACTION = ['mail.read', 'mail.search', 'drive.search', 'doc.read', 'calendar.read'];
+function node(i, cap, depends, c) {
+    const def = (0, taxonomy_1.capabilityById)(cap);
+    const needs = def.args || [];
+    const known = needs.filter((a) => c.args_known.includes(a));
+    // a chained node gets its inputs from the node before it: nothing is missing
+    const missing = depends.length ? [] : needs.filter((a) => !c.args_known.includes(a));
+    return { node_id: `n${i}`, capability: cap, depends_on: depends, risk_classes: [...def.default_risk], args_known: known.length ? known : (c.args_known.includes('query') ? ['query'] : []), args_missing: missing, needs_tool: def.needs_tool };
+}
+function decompose(c, text = '') {
+    if (c.requirement === 'clarify' || !c.capabilities.length)
+        return [];
+    const caps = c.capabilities.filter((x) => (0, taxonomy_1.capabilityById)(x));
+    const norm = (0, text_1.normalise)(text);
+    const out = [];
+    const add = (cap, deps) => { const n = node(out.length + 1, cap, deps, c); out.push(n); return n.node_id; };
+    // video chain (Demo C): a produced piece with characters, dialogue, a story or a duration
+    if (caps.includes('video.generate') && (caps.includes('character.design') || caps.includes('script.write') || RICH_VIDEO.test(norm))) {
+        let prev = [];
+        for (const cap of VIDEO_CHAIN)
+            prev = [add(cap, prev)];
+        if (caps.includes('music.generate')) {
+            const m = add('music.generate', [out[0].node_id]);
+            out[out.length - 2].depends_on.push(m);
+        }
+        for (const cap of caps)
+            if (!out.some((n) => n.capability === cap))
+                add(cap, []);
+        return fixEditDeps(out);
+    }
+    // research (Demo B): searches in parallel, synthesis after all of them
+    const searches = caps.filter((x) => SEARCHES.includes(x));
+    if (searches.length && (caps.includes('evidence.synthesise') || c.task_complexity === 'REASONING') && searches.some((s) => s !== 'web.search' && s !== 'news.search')) {
+        const ids = searches.map((s) => add(s, []));
+        add('evidence.synthesise', ids);
+        for (const cap of caps)
+            if (!out.some((n) => n.capability === cap))
+                add(cap, []);
+        return out;
+    }
+    // extraction from the owner's data (Demo D): read first, model work after
+    if (caps.includes('mail.extract_actions') || caps.includes('text.summarise')) {
+        const reads = caps.filter((x) => READS_FOR_EXTRACTION.includes(x));
+        if (reads.length) {
+            const ids = reads.map((r) => add(r, []));
+            for (const cap of caps)
+                if (!reads.includes(cap))
+                    add(cap, (0, taxonomy_1.capabilityById)(cap).needs_tool ? [] : ids);
+            return out;
+        }
+    }
+    // generic: sequential when the text chains the steps, otherwise parallel
+    const chained = rules_1.CHAIN_HINT.test(norm);
+    let prev = [];
+    for (const cap of caps) {
+        const id = add(cap, chained ? prev : []);
+        prev = [id];
+    }
+    // model work (summarise, synthesise) after the tool nodes it follows
+    for (let i = 0; i < out.length; i++) {
+        const n = out[i];
+        if (n.needs_tool || n.depends_on.length)
+            continue;
+        n.depends_on = out.slice(0, i).filter((x) => x.needs_tool).map((x) => x.node_id);
+    }
+    return out;
+}
+function fixEditDeps(nodes) {
+    for (const n of nodes)
+        n.depends_on = [...new Set(n.depends_on)];
+    return nodes;
+}
+/** Topological order; throws on a cycle or an unknown dependency. */
+function topoOrder(nodes) {
+    const ids = new Set(nodes.map((n) => n.node_id));
+    for (const n of nodes)
+        for (const d of n.depends_on)
+            if (!ids.has(d))
+                throw new Error(`${n.node_id} depends on unknown ${d}`);
+    const order = [];
+    const state = new Map();
+    const byId = new Map(nodes.map((n) => [n.node_id, n]));
+    const visit = (id) => {
+        if (state.get(id) === 2)
+            return;
+        if (state.get(id) === 1)
+            throw new Error(`cycle at ${id}`);
+        state.set(id, 1);
+        for (const d of byId.get(id).depends_on)
+            visit(d);
+        state.set(id, 2);
+        order.push(id);
+    };
+    for (const n of nodes)
+        visit(n.node_id);
+    return order;
+}