@kognai/tool-router 0.0.0-stage → 0.1.0

package/dist/schema/tool.schema.json

@@ -0,0 +1,117 @@
+{
+    "$schema": "https://json-schema.org/draft/2020-12/schema",
+    "$id": "https://kognai.ai/schemas/ktr/tool-record-v1.json",
+    "title": "KTR ToolRecord v1",
+    "type": "object",
+    "additionalProperties": false,
+    "required": [
+        "schema_version", "id", "version", "name", "description_safe", "description_raw_sha256", "provider", "origin",
+        "category", "tags", "operations", "auth", "privacy_class", "business_tier", "regions", "networks", "pricing",
+        "success", "latency", "rate_limits", "health", "dependencies", "trust_state", "skill_ids", "last_validated",
+        "schema_hash", "implementation_hash", "lifecycle", "aliases", "same_as", "provenance", "ingested_at"
+    ],
+    "properties": {
+        "schema_version": { "enum": [1] },
+        "id": { "type": "string", "maxLength": 160, "pattern": "^tool:(kognai|mcp|openapi|x402|community|composio):[a-z0-9._-]+(/[a-z0-9._-]+)+$" },
+        "version": { "type": "string", "minLength": 1, "maxLength": 80 },
+        "name": { "type": "string", "minLength": 1, "maxLength": 120 },
+        "description_safe": { "type": "string", "maxLength": 512 },
+        "description_raw_sha256": { "type": "string", "pattern": "^[0-9a-f]{64}$" },
+        "provider": {
+            "type": "object", "additionalProperties": false, "required": ["name", "kognai_owned"],
+            "properties": { "name": { "type": "string", "maxLength": 120 }, "url": { "type": "string", "maxLength": 300 }, "kognai_owned": { "type": "boolean" } }
+        },
+        "origin": { "enum": ["kognai", "mcp", "openapi", "x402", "community", "composio"] },
+        "category": { "type": "string", "maxLength": 60 },
+        "tags": { "type": "array", "maxItems": 40, "items": { "type": "string", "maxLength": 60 } },
+        "operations": {
+            "type": "array", "maxItems": 200,
+            "items": {
+                "type": "object", "additionalProperties": false,
+                "required": ["op", "summary", "capabilities", "input_schema", "output_schema", "side_effects", "risk_classes", "scopes", "idempotent", "url_from_user"],
+                "properties": {
+                    "op": { "type": "string", "pattern": "^[a-z0-9_.-]{1,64}$" },
+                    "summary": { "type": "string", "maxLength": 200 },
+                    "capabilities": { "type": "array", "items": { "type": "string", "pattern": "^[a-z0-9_]+(\\.[a-z0-9_]+)+$" } },
+                    "input_schema": { "type": "object" },
+                    "output_schema": { "type": ["object", "null"] },
+                    "side_effects": { "type": "array", "items": { "enum": ["none", "read", "write", "publish", "message", "payment", "delete", "infra"] } },
+                    "risk_classes": { "type": "array", "items": { "enum": ["read_only", "network", "data_modification", "publish_or_message", "payment", "destructive", "sensitive_data", "privileged_infra"] } },
+                    "scopes": { "type": "array", "items": { "type": "string", "maxLength": 200 } },
+                    "idempotent": { "type": ["boolean", "null"] },
+                    "url_from_user": { "type": "boolean" }
+                }
+            }
+        },
+        "auth": {
+            "type": "object", "additionalProperties": false, "required": ["kind"],
+            "properties": { "kind": { "enum": ["none", "oauth", "api_key", "x402", "internal"] }, "credential_ref": { "type": "string" }, "provider": { "type": "string" } }
+        },
+        "privacy_class": { "enum": ["public", "internal", "private", "sensitive"] },
+        "business_tier": { "enum": ["free", "citizen_plus", "citizen_pro", "citizen_pro_max", "enterprise", null] },
+        "regions": { "type": "array", "items": { "type": "string", "maxLength": 3 } },
+        "networks": { "type": "array", "items": { "enum": ["base", "base-sepolia", "solana", "solana-devnet", "offchain"] } },
+        "pricing": {
+            "type": "object", "additionalProperties": false, "required": ["model", "source"],
+            "properties": {
+                "model": { "enum": ["free", "per_call", "per_unit", "unknown"] },
+                "price": {
+                    "type": "object", "additionalProperties": false, "required": ["amount_micro", "currency"],
+                    "properties": {
+                        "amount_micro": { "type": "string", "pattern": "^[0-9]{1,30}$" },
+                        "currency": { "enum": ["USDC", "KGC", "USD"] },
+                        "network": { "enum": ["base", "base-sepolia", "solana", "solana-devnet", "offchain"] }
+                    }
+                },
+                "unit": { "type": "string", "maxLength": 40 },
+                "source": { "enum": ["measured", "provider", "cfo_price_book", "unknown"] },
+                "observed_at": { "type": "string" }
+            }
+        },
+        "success": {
+            "type": "object", "additionalProperties": false,
+            "required": ["exec_ok", "exec_n", "verified_ok", "verified_n", "distinct_principals", "window_days"],
+            "properties": {
+                "exec_ok": { "type": "integer" }, "exec_n": { "type": "integer" }, "verified_ok": { "type": "integer" },
+                "verified_n": { "type": "integer" }, "distinct_principals": { "type": "integer" }, "window_days": { "type": "integer" }
+            }
+        },
+        "latency": {
+            "type": "object", "additionalProperties": false, "required": ["p50_ms", "p95_ms", "n"],
+            "properties": { "p50_ms": { "type": ["number", "null"] }, "p95_ms": { "type": ["number", "null"] }, "n": { "type": "integer" } }
+        },
+        "rate_limits": { "type": ["object", "null"] },
+        "health": {
+            "type": "object", "additionalProperties": false, "required": ["state", "checked_at", "source"],
+            "properties": {
+                "state": { "enum": ["up", "degraded", "down", "unknown"] },
+                "checked_at": { "type": ["string", "null"] },
+                "source": { "enum": ["probe", "experience", "none"] }
+            }
+        },
+        "dependencies": { "type": "array", "items": { "type": "string" } },
+        "trust_state": { "enum": ["quarantined", "reviewed", "verified", "deprecated", "revoked"] },
+        "skill_ids": { "type": "array", "items": { "type": "string" } },
+        "last_validated": { "type": ["string", "null"] },
+        "schema_hash": { "type": "string", "pattern": "^[0-9a-f]{64}$" },
+        "implementation_hash": { "type": ["string", "null"] },
+        "lifecycle": { "enum": ["draft", "active", "deprecated", "retired"] },
+        "aliases": { "type": "array", "items": { "type": "string", "maxLength": 160 } },
+        "same_as": { "type": "array", "items": { "type": "string" } },
+        "product_id": { "type": "string" },
+        "aiax_ready": { "type": "boolean" },
+        "provenance": {
+            "type": "array", "minItems": 1,
+            "items": {
+                "type": "object", "additionalProperties": false,
+                "required": ["source", "source_ref", "retrieved_at", "licence", "adapter", "adapter_version", "snapshot_sha256"],
+                "properties": {
+                    "source": { "type": "string" }, "source_ref": { "type": "string", "maxLength": 400 }, "retrieved_at": { "type": "string" },
+                    "licence": { "type": ["string", "null"] }, "adapter": { "type": "string" }, "adapter_version": { "type": "string" },
+                    "snapshot_sha256": { "type": "string", "pattern": "^[0-9a-f]{64}$" }
+                }
+            }
+        },
+        "ingested_at": { "type": "string" }
+    }
+}

package/dist/schema/validate.d.ts

@@ -0,0 +1,9 @@
+export interface ValidateResult {
+    ok: boolean;
+    errors: string[];
+    ignored: string[];
+}
+export declare function validate(schema: Record<string, any>, value: unknown, max?: number): ValidateResult;
+export declare const TOOL_SCHEMA: Record<string, any>;
+/** Validates a ToolRecord against the KTR schema. */
+export declare const validateToolRecord: (rec: unknown) => ValidateResult;

package/dist/schema/validate.js

@@ -0,0 +1,92 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.validateToolRecord = exports.TOOL_SCHEMA = void 0;
+exports.validate = validate;
+/**
+ * A minimal JSON Schema validator for the subset KTR emits (plan.md S1): type, required, enum, const, pattern,
+ * minLength, maxLength, minItems, maxItems, items, properties, additionalProperties. Any other keyword is ignored and
+ * reported in `ignored`, so a schema that relies on it is visible instead of silently passing. External tool schemas
+ * are only stored and hashed, never validated against arguments in milestone 1.
+ */
+const tool_schema_json_1 = __importDefault(require("./tool.schema.json"));
+const SUPPORTED = new Set([
+    'type', 'required', 'enum', 'const', 'pattern', 'minLength', 'maxLength', 'minItems', 'maxItems', 'items', 'properties',
+    'additionalProperties', '$schema', '$id', 'title', 'description', 'default', 'examples',
+]);
+const typeOf = (v) => {
+    if (v === null)
+        return 'null';
+    if (Array.isArray(v))
+        return 'array';
+    if (typeof v === 'number')
+        return Number.isInteger(v) ? 'integer' : 'number';
+    return typeof v;
+};
+const typeMatches = (want, v) => {
+    const t = typeOf(v);
+    return want === t || (want === 'number' && t === 'integer');
+};
+const eq = (a, b) => JSON.stringify(a) === JSON.stringify(b);
+function validate(schema, value, max = 50) {
+    const errors = [];
+    const ignored = new Set();
+    const walk = (s, v, path) => {
+        if (errors.length >= max || !s || typeof s !== 'object')
+            return;
+        for (const k of Object.keys(s))
+            if (!SUPPORTED.has(k))
+                ignored.add(k);
+        if (s.type !== undefined) {
+            const types = Array.isArray(s.type) ? s.type : [s.type];
+            if (!types.some((t) => typeMatches(t, v))) {
+                errors.push(`${path || '/'}: expected ${types.join(' or ')}, got ${typeOf(v)}`);
+                return;
+            }
+        }
+        if (s.enum !== undefined && !s.enum.some((e) => eq(e, v)))
+            errors.push(`${path || '/'}: not one of ${JSON.stringify(s.enum)}`);
+        if (s.const !== undefined && !eq(s.const, v))
+            errors.push(`${path || '/'}: must be ${JSON.stringify(s.const)}`);
+        if (typeof v === 'string') {
+            if (typeof s.maxLength === 'number' && [...v].length > s.maxLength)
+                errors.push(`${path}: longer than ${s.maxLength}`);
+            if (typeof s.minLength === 'number' && [...v].length < s.minLength)
+                errors.push(`${path}: shorter than ${s.minLength}`);
+            if (typeof s.pattern === 'string' && !new RegExp(s.pattern, 'u').test(v))
+                errors.push(`${path}: does not match ${s.pattern}`);
+        }
+        if (Array.isArray(v)) {
+            if (typeof s.maxItems === 'number' && v.length > s.maxItems)
+                errors.push(`${path}: more than ${s.maxItems} items`);
+            if (typeof s.minItems === 'number' && v.length < s.minItems)
+                errors.push(`${path}: fewer than ${s.minItems} items`);
+            if (s.items && typeof s.items === 'object')
+                v.forEach((x, i) => walk(s.items, x, `${path}/${i}`));
+        }
+        if (v && typeof v === 'object' && !Array.isArray(v)) {
+            const o = v;
+            if (Array.isArray(s.required))
+                for (const r of s.required)
+                    if (!(r in o))
+                        errors.push(`${path}/${r}: required`);
+            const props = s.properties || {};
+            for (const [k, x] of Object.entries(o)) {
+                if (props[k])
+                    walk(props[k], x, `${path}/${k}`);
+                else if (s.additionalProperties === false)
+                    errors.push(`${path}/${k}: not allowed`);
+                else if (s.additionalProperties && typeof s.additionalProperties === 'object')
+                    walk(s.additionalProperties, x, `${path}/${k}`);
+            }
+        }
+    };
+    walk(schema, value, '');
+    return { ok: errors.length === 0, errors, ignored: [...ignored].sort() };
+}
+exports.TOOL_SCHEMA = tool_schema_json_1.default;
+/** Validates a ToolRecord against the KTR schema. */
+const validateToolRecord = (rec) => validate(exports.TOOL_SCHEMA, rec);
+exports.validateToolRecord = validateToolRecord;

package/dist/shortlist/generate.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Shortlist (plan.md S3): at most min(10, max_candidates) per node, eligible only, above the relevance floor, with
+ * reasons, fallbacks and auth needs. Kognai first (ADR-008): with kognai_first 'hard', when a Kognai product covers the
+ * step, outside tools are returned only as fallbacks of the first Kognai candidate; with 'prior' Kognai tools get a
+ * small bonus; with 'off' merit alone. Linked duplicates (same_as) collapse into fallbacks. Nothing in a candidate is
+ * copied from provider text except its name.
+ */
+import type { Candidate, CallerContext, PlanNode } from '../types/route';
+import type { Ranked } from '../rank/ranker';
+export declare const MAX_CANDIDATES = 10;
+export declare const PRIOR_BONUS = 0.05;
+export declare const CONNECTED_BONUS = 0.02;
+export interface ShortlistOpts {
+    max?: number;
+    floor?: number;
+    mode: 'discover' | 'execute_plan';
+}
+export declare function generate(ranked: Ranked[], node: PlanNode, ctx: CallerContext, o: ShortlistOpts): {
+    candidates: Candidate[];
+    kognaiFirst: boolean;
+};

package/dist/shortlist/generate.js

@@ -0,0 +1,75 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CONNECTED_BONUS = exports.PRIOR_BONUS = exports.MAX_CANDIDATES = void 0;
+exports.generate = generate;
+const rules_1 = require("../eligibility/rules");
+const weights_1 = require("../rank/weights");
+exports.MAX_CANDIDATES = 10;
+exports.PRIOR_BONUS = 0.05;
+exports.CONNECTED_BONUS = 0.02;
+const r4 = (x) => Math.round(x * 10000) / 10000;
+function generate(ranked, node, ctx, o) {
+    const max = Math.max(0, Math.min(exports.MAX_CANDIDATES, o.max ?? exports.MAX_CANDIDATES));
+    let list = ranked.filter((x) => x.fit >= (o.floor ?? weights_1.RELEVANCE_FLOOR));
+    // an account the owner already connected beats the same tool on an account still to connect
+    list = list.map((x) => (x.r.item.rec.auth.kind === 'oauth' && (0, rules_1.authNeeded)(x.r.item.rec, x.r.item.op, ctx) === null ? { ...x, score: x.score + exports.CONNECTED_BONUS, reasons: [...x.reasons, "the owner's account is already connected"] } : x))
+        .sort((a, b) => b.score - a.score || (a.r.item.key < b.r.item.key ? -1 : 1));
+    let outsideFallbacks = [];
+    let kognaiFirst = false;
+    if (ctx.kognai_first === 'prior') {
+        list = list.map((x) => ((0, rules_1.isKognaiProduct)(x.r.item.rec) ? { ...x, score: x.score + exports.PRIOR_BONUS } : x)).sort((a, b) => b.score - a.score || (a.r.item.key < b.r.item.key ? -1 : 1));
+    }
+    else if (ctx.kognai_first === 'hard') {
+        const covers = list.some((x) => (0, rules_1.isKognaiProduct)(x.r.item.rec) && x.r.signals.capability === 1);
+        if (covers) {
+            kognaiFirst = true;
+            outsideFallbacks = list.filter((x) => !(0, rules_1.isKognaiProduct)(x.r.item.rec)).slice(0, max).map((x) => x.r.item.key);
+            list = list.filter((x) => (0, rules_1.isKognaiProduct)(x.r.item.rec));
+        }
+    }
+    // same_as: keep the first (best) of a linked group, the others become its fallbacks
+    const kept = [];
+    const extra = new Map();
+    for (const x of list) {
+        const rec = x.r.item.rec;
+        const head = kept.find((k) => k.r.item.rec.same_as.includes(rec.id) || rec.same_as.includes(k.r.item.rec.id));
+        if (head) {
+            (extra.get(head.r.item.key) || extra.set(head.r.item.key, []).get(head.r.item.key)).push(x.r.item.key);
+            continue;
+        }
+        kept.push(x);
+        if (kept.length >= max)
+            break;
+    }
+    const candidates = kept.map((x, i) => {
+        const { rec, op } = x.r.item;
+        const reasons = [...x.reasons];
+        if (kognaiFirst && i === 0)
+            reasons.unshift('Kognai product first (ADR-008): outside tools are fallbacks');
+        const auth = (0, rules_1.authNeeded)(rec, op, ctx);
+        if (auth?.kind === 'oauth')
+            reasons.push(`needs the owner's ${auth.provider} connection`);
+        if (auth?.kind === 'approval')
+            reasons.push('needs an approval before it runs');
+        return {
+            tool_id: x.r.item.key,
+            version: rec.version,
+            operation: op.op,
+            name: rec.name,
+            input_schema: op.input_schema,
+            output_schema: op.output_schema,
+            score: r4(x.score),
+            score_parts: Object.fromEntries(Object.entries(x.parts).map(([k, v]) => [k, r4(v)])),
+            reasons,
+            cost: rec.pricing,
+            skills: x.skills.map((s) => ({ skill_id: s.skill_id, version: s.version, uplift: r4(s.uplift) })),
+            auth_needed: auth,
+            confidence: r4(x.confidence),
+            fallbacks: [...(extra.get(x.r.item.key) || []), ...(i === 0 ? outsideFallbacks : [])],
+            evidence: { verified_n: x.stats.verified_n, cold_start: x.cold },
+            trust_state: rec.trust_state,
+            executable: rec.trust_state === 'verified' || rec.trust_state === 'reviewed',
+        };
+    });
+    return { candidates, kognaiFirst };
+}

package/dist/types/ports.d.ts

@@ -0,0 +1,71 @@
+/**
+ * Ports (ADR-001, ADR-002). The package imports nothing from Kognai; Kognai wires these to files and to the ClawRouter
+ * gateway. Tests wire fakes.
+ */
+import type { SuccessStats, ToolRecord, TrustState } from './tool';
+export interface CatalogStore {
+    /** Hash of the index (ids, versions, schema hashes, trust, lifecycle), stamped on every route. */
+    snapshotId(): string;
+    /** Every row, every version. */
+    all(): Iterable<ToolRecord>;
+    /** The newest version of each tool id: what the router reads. */
+    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;
+    /** Appends a trust event without a state check (ingestion: drift, revocation). */
+    recordEvent(e: TrustEvent): void;
+    events(): TrustEvent[];
+    vectors(model: string): {
+        dims: number;
+        ids: string[];
+        data: Float32Array;
+    } | null;
+}
+export interface EvidenceStore {
+    stats(toolId: string): SuccessStats | null;
+}
+export interface EmbeddingPort {
+    model: string;
+    dims: number;
+    embed(texts: string[]): Promise<Float32Array[]>;
+}
+export interface ClassifierLabels {
+    capabilities: string[];
+    requirements: string[];
+    complexities: string[];
+}
+export interface ClassifierAnswer {
+    capabilities: string[];
+    requirement?: string;
+    task_complexity?: string;
+    confidence?: number;
+}
+export interface ClassifierPort {
+    classify(text: string, labels: ClassifierLabels): Promise<ClassifierAnswer | null>;
+}
+export interface SkillRef {
+    skill_id: string;
+    version: string;
+    uplift: number;
+    evaluated: boolean;
+}
+export interface SkillIndex {
+    forTool(toolId: string, op: string): SkillRef[];
+}
+export interface Clock {
+    now(): Date;
+}
+export interface TrustEvent {
+    at: string;
+    id: string;
+    version: string;
+    from: TrustState;
+    to: TrustState;
+    by: string;
+    why: string;
+}

package/dist/types/ports.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/types/route.d.ts

@@ -0,0 +1,121 @@
+/**
+ * Request, classification and response types (plan.md sections 3 and 4). "task_complexity" is the field name for the
+ * ToolRouter's SIMPLE to REASONING scale (decision D3, ADR-002); "tier" alone always means a ClawRouter tier.
+ */
+import type { BusinessTier, JSONSchema, Network, Pricing, RiskClass, TrustState } from './tool';
+export type TaskComplexity = 'SIMPLE' | 'MEDIUM' | 'COMPLEX' | 'REASONING';
+export declare const TASK_COMPLEXITIES: TaskComplexity[];
+export type Requirement = 'tool' | 'no_tool' | 'no_eligible_tool' | 'clarify';
+export declare const REQUIREMENTS: Requirement[];
+export type Lang = 'en' | 'fr' | 'derja' | 'other';
+export interface CallerContext {
+    caller_id: string;
+    principal_id: string;
+    kind: 'citizen' | 'swarm' | 'engine' | 'external';
+    business_tier: BusinessTier;
+    connected: Array<{
+        provider: string;
+        scopes: string[];
+    }>;
+    budget_remaining_micro?: string;
+    kognai_first: 'hard' | 'prior' | 'off';
+    /** Whose data the request is about (E7). Defaults to principal_id: a citizen reading its own owner's mail. */
+    data_owner_id?: string;
+}
+export interface PlanNode {
+    node_id: string;
+    capability: string;
+    depends_on: string[];
+    risk_classes: RiskClass[];
+    args_known: string[];
+    args_missing: string[];
+    /** false for model work (summarise given text, synthesise): no shortlist is built for the node. */
+    needs_tool: boolean;
+}
+export interface CapabilityHit {
+    id: string;
+    confidence: number;
+    span: string;
+}
+export interface Classification {
+    task_complexity: TaskComplexity;
+    risk_classes: RiskClass[];
+    requirement: Requirement;
+    capabilities: string[];
+    hits: CapabilityHit[];
+    confidence: number;
+    method: 'rules' | 'model';
+    language: Lang;
+    args_known: string[];
+    /** Words that asked for analysis, comparison or synthesis (REASONING). */
+    reasoning_cues: string[];
+    /** Text recognised as quoted data (an email body, a pasted page), excluded from cue detection (T5). */
+    data_spans: number;
+}
+export interface RouteRequest {
+    request_id?: string;
+    text: string;
+    context: CallerContext;
+    mode?: 'discover' | 'execute_plan';
+    constraints?: {
+        max_candidates?: number;
+        max_cost_micro?: string;
+        networks?: Network[];
+        regions?: string[];
+    };
+    request_step?: 'simple' | 'product' | 'lax' | 'swarm';
+}
+export type ScorePart = 'fit' | 'schema' | 'success' | 'cost' | 'latency' | 'skills' | 'exploration' | 'aiax';
+export interface Candidate {
+    tool_id: string;
+    version: string;
+    operation: string;
+    name: string;
+    input_schema: JSONSchema;
+    output_schema: JSONSchema | null;
+    score: number;
+    score_parts: Record<ScorePart, number>;
+    reasons: string[];
+    cost: Pricing;
+    skills: Array<{
+        skill_id: string;
+        version: string;
+        uplift: number;
+    }>;
+    auth_needed: {
+        kind: 'oauth' | 'api_key' | 'x402' | 'approval';
+        provider?: string;
+        scopes?: string[];
+    } | null;
+    confidence: number;
+    fallbacks: string[];
+    evidence: {
+        verified_n: number;
+        cold_start: boolean;
+    };
+    trust_state: TrustState;
+    /** false for a quarantined tool shown in discover mode: listed, never executable (threat T2). */
+    executable: boolean;
+}
+export interface NodeShortlist {
+    node_id: string;
+    candidates: Candidate[];
+    excluded: Record<string, number>;
+}
+export interface RouteResponse {
+    route_id: string;
+    created_at: string;
+    catalog_snapshot: string;
+    mode: 'discover' | 'execute_plan';
+    task_complexity: TaskComplexity;
+    risk_classes: RiskClass[];
+    requirement: Requirement;
+    classifier: {
+        method: 'rules' | 'model';
+        confidence: number;
+    };
+    plan: PlanNode[];
+    shortlists: NodeShortlist[];
+    request_step?: string;
+    notes: string[];
+}

package/dist/types/route.js

@@ -0,0 +1,5 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.REQUIREMENTS = exports.TASK_COMPLEXITIES = void 0;
+exports.TASK_COMPLEXITIES = ['SIMPLE', 'MEDIUM', 'COMPLEX', 'REASONING'];
+exports.REQUIREMENTS = ['tool', 'no_tool', 'no_eligible_tool', 'clarify'];

package/dist/types/tool.d.ts

@@ -0,0 +1,123 @@
+/**
+ * The tool record (plan.md section 1). One row per (tool id, version). Everything the router reads about a tool is
+ * here; the raw provider text is kept outside the record by hash only and is never shown to a model (threat T1).
+ */
+export type Origin = 'kognai' | 'mcp' | 'openapi' | 'x402' | 'community' | 'composio';
+export type TrustState = 'quarantined' | 'reviewed' | 'verified' | 'deprecated' | 'revoked';
+export type Lifecycle = 'draft' | 'active' | 'deprecated' | 'retired';
+export type SideEffect = 'none' | 'read' | 'write' | 'publish' | 'message' | 'payment' | 'delete' | 'infra';
+export type RiskClass = 'read_only' | 'network' | 'data_modification' | 'publish_or_message' | 'payment' | 'destructive' | 'sensitive_data' | 'privileged_infra';
+export type PrivacyClass = 'public' | 'internal' | 'private' | 'sensitive';
+export type BusinessTier = 'free' | 'citizen_plus' | 'citizen_pro' | 'citizen_pro_max' | 'enterprise';
+export type Currency = 'USDC' | 'KGC' | 'USD';
+export type Network = 'base' | 'base-sepolia' | 'solana' | 'solana-devnet' | 'offchain';
+export type JSONSchema = Record<string, unknown>;
+export declare const ORIGINS: Origin[];
+export declare const TRUST_STATES: TrustState[];
+export declare const LIFECYCLES: Lifecycle[];
+export declare const SIDE_EFFECTS: SideEffect[];
+export declare const RISK_CLASSES: RiskClass[];
+/** The four classes the benchmark measures recall on (plan.md section 6). */
+export declare const HIGH_RISK: RiskClass[];
+export declare const PRIVACY_CLASSES: PrivacyClass[];
+export declare const BUSINESS_TIERS: BusinessTier[];
+export declare const NETWORKS: Network[];
+export interface Money {
+    amount_micro: string;
+    currency: Currency;
+    network?: Network;
+}
+export interface Pricing {
+    model: 'free' | 'per_call' | 'per_unit' | 'unknown';
+    price?: Money;
+    unit?: string;
+    source: 'measured' | 'provider' | 'cfo_price_book' | 'unknown';
+    observed_at?: string;
+}
+export interface ToolOperation {
+    op: string;
+    summary: string;
+    capabilities: string[];
+    input_schema: JSONSchema;
+    output_schema: JSONSchema | null;
+    side_effects: SideEffect[];
+    risk_classes: RiskClass[];
+    scopes: string[];
+    idempotent: boolean | null;
+    url_from_user: boolean;
+}
+export interface Provenance {
+    source: string;
+    source_ref: string;
+    retrieved_at: string;
+    licence: string | null;
+    adapter: string;
+    adapter_version: string;
+    snapshot_sha256: string;
+}
+export interface SuccessStats {
+    exec_ok: number;
+    exec_n: number;
+    verified_ok: number;
+    verified_n: number;
+    distinct_principals: number;
+    window_days: number;
+}
+export interface ToolRecord {
+    schema_version: 1;
+    id: string;
+    version: string;
+    name: string;
+    description_safe: string;
+    description_raw_sha256: string;
+    provider: {
+        name: string;
+        url?: string;
+        kognai_owned: boolean;
+    };
+    origin: Origin;
+    category: string;
+    tags: string[];
+    operations: ToolOperation[];
+    auth: {
+        kind: 'none' | 'oauth' | 'api_key' | 'x402' | 'internal';
+        credential_ref?: string;
+        provider?: string;
+    };
+    privacy_class: PrivacyClass;
+    business_tier: BusinessTier | null;
+    regions: string[];
+    networks: Network[];
+    pricing: Pricing;
+    success: SuccessStats;
+    latency: {
+        p50_ms: number | null;
+        p95_ms: number | null;
+        n: number;
+    };
+    rate_limits: {
+        per_min?: number;
+        per_day?: number;
+    } | null;
+    health: {
+        state: 'up' | 'degraded' | 'down' | 'unknown';
+        checked_at: string | null;
+        source: 'probe' | 'experience' | 'none';
+    };
+    dependencies: string[];
+    trust_state: TrustState;
+    skill_ids: string[];
+    last_validated: string | null;
+    schema_hash: string;
+    implementation_hash: string | null;
+    lifecycle: Lifecycle;
+    aliases: string[];
+    same_as: string[];
+    product_id?: string;
+    /** The provider's base URL serves a valid AIAX manifest (/aiax/manifest.json). Optional: absent = false, and an
+     *  absent field leaves the record's canonical JSON (and every hash over it) unchanged. */
+    aiax_ready?: boolean;
+    provenance: Provenance[];
+    ingested_at: string;
+}
+export declare const EMPTY_SUCCESS: SuccessStats;