@kognai/build 0.6.0

package/dist/lib/swarm.js

@@ -0,0 +1,89 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runSwarm = runSwarm;
+/**
+ * swarm.ts — --swarm mode (TICKET-233 Phase 2).
+ *
+ * Delegates a decomposed goal to the FULL @kognai/orchestrator-core swarm
+ * (CEO planning · CTO governance gate · dual-supervisor review · reconciliation)
+ * instead of kognai-build's lighter in-process pipeline.
+ *
+ * The engine is repo-shaped: it reads the sprint from process.argv[2] and loads
+ * coding agents from ./agents/<name>/prompt.md (cwd-relative). So we scaffold a
+ * throwaway working dir (bundled coder agent + a synthesized human-sourced sprint),
+ * chdir into it, run the orchestrator, then collect the deliverables back out.
+ *
+ * Model routing still flows through the ModelRouter registered at boot
+ * (makeBuildRouter) — so --swarm honors --sovereign ($0 local) end to end,
+ * leadership included (the engine's callLLM/callAnthropicCached route through it).
+ */
+const node_fs_1 = require("node:fs");
+const node_path_1 = require("node:path");
+const orchestrator_core_1 = require("@kognai/orchestrator-core");
+const swarm_coder_prompt_1 = require("./swarm-coder-prompt");
+/**
+ * Run a decomposed goal through the full orchestrator swarm.
+ * @param goal   the original user goal (sprint title/description)
+ * @param tasks  decomposed tasks (file + description), agent defaults to 'coder'
+ * @param outDir where to copy shipped deliverables
+ */
+async function runSwarm(goal, tasks, outDir) {
+    const sid = Math.floor(Date.now() / 1000).toString(36).slice(-5);
+    const scaffold = (0, node_path_1.join)('/tmp', `kognai-swarm-${sid}`);
+    // 1. Scaffold: bundled coder agent so the engine has someone to dispatch to.
+    (0, node_fs_1.mkdirSync)((0, node_path_1.join)(scaffold, 'agents', 'coder'), { recursive: true });
+    (0, node_fs_1.writeFileSync)((0, node_path_1.join)(scaffold, 'agents', 'coder', 'prompt.md'), swarm_coder_prompt_1.SWARM_CODER_PROMPT);
+    // 2. Synthesize a human-sourced sprint (source:'human' → CTO gate auto-approves
+    //    the builder's own goal rather than rejecting it as off-plan).
+    const sprint = {
+        sprint_id: `swarm-${sid}`,
+        title: goal,
+        description: goal,
+        source: 'human',
+        inputs: ['user goal'],
+        outputs: tasks.map((t) => t.file),
+        success_criteria: ['every task ships a complete, reviewed file'],
+        tasks: tasks.map((t, i) => ({
+            id: `swarm-${sid}-${i + 1}`,
+            title: t.file,
+            type: 'feature',
+            task_type: 'autonomous',
+            task_target: t.file,
+            agent: 'coder',
+            priority: 'medium',
+            // The engine's Phase 2 only executes tasks with status === 'pending'
+            // (orchestrate-engine: `if (task.status !== 'pending') continue`). Without
+            // this the whole leadership ceremony runs but the coder never fires.
+            status: 'pending',
+            deliverables: { code: [t.file], tests: [], docs: [] },
+            context: t.description,
+        })),
+    };
+    (0, node_fs_1.writeFileSync)((0, node_path_1.join)(scaffold, 'sprint.json'), JSON.stringify(sprint, null, 2));
+    // 3. Run the orchestrator from inside the scaffold (cwd-relative ./agents +
+    //    process.argv[2] sprint path). Restore cwd/argv afterward.
+    const prevCwd = process.cwd();
+    const prevArgv = process.argv.slice();
+    process.chdir(scaffold);
+    process.argv = [process.argv[0], process.argv[1], 'sprint.json'];
+    try {
+        await (0, orchestrator_core_1.runOrchestrator)({});
+    }
+    finally {
+        process.chdir(prevCwd);
+        process.argv = prevArgv;
+    }
+    // 4. Collect deliverables the swarm wrote (relative paths preserved).
+    const deliverables = [];
+    (0, node_fs_1.mkdirSync)(outDir, { recursive: true });
+    for (const t of tasks) {
+        const src = (0, node_path_1.join)(scaffold, t.file);
+        if ((0, node_fs_1.existsSync)(src)) {
+            const dst = (0, node_path_1.join)(outDir, t.file);
+            (0, node_fs_1.mkdirSync)((0, node_path_1.dirname)(dst), { recursive: true });
+            (0, node_fs_1.cpSync)(src, dst);
+            deliverables.push(dst);
+        }
+    }
+    return { deliverables, total: tasks.length, scaffold };
+}

package/dist/lib/tool-layer-stub.js

@@ -0,0 +1,214 @@
+"use strict";
+/**
+ * Tool Layer Stub
+ *
+ * Phase 1 stub returning mock tool metadata for cost estimation and
+ * capability discovery. Phase 2 (TICKET-125) replaces TOOL_LAYER with
+ * a real provider registry backed by live cost-per-call data.
+ *
+ * Function signatures are stable across phases — callers (cost-estimator.ts,
+ * build planners, capability matchers) can rely on the API surface.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TOOL_LAYER = void 0;
+exports.getToolsByIds = getToolsByIds;
+exports.listToolsByCategory = listToolsByCategory;
+exports.estimateToolCost = estimateToolCost;
+exports.TOOL_LAYER = [
+    // ── database ─────────────────────────────────────────────────────────────
+    {
+        id: 'postgres-encrypted',
+        name: 'PostgreSQL (Encrypted)',
+        provider: 'self-hosted',
+        category: 'database',
+        cost_per_call_usdc: 0,
+        description: 'Self-hosted Postgres with at-rest encryption and pgcrypto.',
+    },
+    {
+        id: 'redis-cache',
+        name: 'Redis Cache',
+        provider: 'self-hosted',
+        category: 'database',
+        cost_per_call_usdc: 0,
+        description: 'In-memory key-value store for caching and rate limiting.',
+    },
+    {
+        id: 'supabase',
+        name: 'Supabase Postgres',
+        provider: 'supabase',
+        category: 'database',
+        cost_per_call_usdc: 0.00005,
+        description: 'Managed Postgres with row-level security and realtime.',
+    },
+    // ── llm ──────────────────────────────────────────────────────────────────
+    {
+        id: 'anthropic-sonnet',
+        name: 'Anthropic Claude Sonnet',
+        provider: 'anthropic',
+        category: 'llm',
+        cost_per_call_usdc: 0.015,
+        description: 'Mid-tier reasoning LLM, ~1k token avg call.',
+    },
+    {
+        id: 'anthropic-haiku',
+        name: 'Anthropic Claude Haiku',
+        provider: 'anthropic',
+        category: 'llm',
+        cost_per_call_usdc: 0.0012,
+        description: 'Fast cheap LLM for classification and routing.',
+    },
+    {
+        id: 'qwen-plus',
+        name: 'Qwen Plus (Cloud)',
+        provider: 'alibaba',
+        category: 'llm',
+        cost_per_call_usdc: 0.0008,
+        description: 'Cloud-hosted Qwen Plus for general-purpose generation.',
+    },
+    {
+        id: 'ollama-local',
+        name: 'Ollama (Local)',
+        provider: 'self-hosted',
+        category: 'llm',
+        cost_per_call_usdc: 0,
+        description: 'Local LLM runtime (Qwen3, Llama, etc.) — zero per-call cost.',
+    },
+    // ── search ───────────────────────────────────────────────────────────────
+    {
+        id: 'tavily',
+        name: 'Tavily Search API',
+        provider: 'tavily',
+        category: 'search',
+        cost_per_call_usdc: 0.005,
+        description: 'LLM-optimized web search with snippet extraction.',
+    },
+    {
+        id: 'exa',
+        name: 'Exa Neural Search',
+        provider: 'exa',
+        category: 'search',
+        cost_per_call_usdc: 0.01,
+        description: 'Neural search over indexed web content.',
+    },
+    // ── payment ──────────────────────────────────────────────────────────────
+    {
+        id: 'x402-meter',
+        name: 'x402 Payment Meter',
+        provider: 'x402',
+        category: 'payment',
+        cost_per_call_usdc: 0.0001,
+        description: 'HTTP 402 micropayment metering for per-call billing.',
+    },
+    {
+        id: 'stripe-webhook',
+        name: 'Stripe Webhook Handler',
+        provider: 'stripe',
+        category: 'payment',
+        cost_per_call_usdc: 0,
+        description: 'Receive and verify Stripe webhook events (cost is in fees, not calls).',
+    },
+    // ── compliance ───────────────────────────────────────────────────────────
+    {
+        id: 'hipaa-bcc-checker',
+        name: 'HIPAA BAA/BCC Checker',
+        provider: 'self-hosted',
+        category: 'compliance',
+        cost_per_call_usdc: 0,
+        description: 'Verifies BAA coverage and BCC routing for PHI workflows.',
+    },
+    {
+        id: 'gdpr-data-mapper',
+        name: 'GDPR Data Mapper',
+        provider: 'self-hosted',
+        category: 'compliance',
+        cost_per_call_usdc: 0,
+        description: 'Tracks personal-data lineage for GDPR Article 30 records.',
+    },
+    // ── observability ────────────────────────────────────────────────────────
+    {
+        id: 'posthog',
+        name: 'PostHog Analytics',
+        provider: 'posthog',
+        category: 'observability',
+        cost_per_call_usdc: 0.00001,
+        description: 'Product analytics, session replay, and feature flags.',
+    },
+    {
+        id: 'datadog',
+        name: 'Datadog APM',
+        provider: 'datadog',
+        category: 'observability',
+        cost_per_call_usdc: 0.0002,
+        description: 'Application performance monitoring and log aggregation.',
+    },
+    {
+        id: 'sentry',
+        name: 'Sentry Error Tracking',
+        provider: 'sentry',
+        category: 'observability',
+        cost_per_call_usdc: 0.00005,
+        description: 'Error capture, stack traces, and release tracking.',
+    },
+    // ── identity ─────────────────────────────────────────────────────────────
+    {
+        id: 'erc-8004-resolver',
+        name: 'ERC-8004 Agent Resolver',
+        provider: 'self-hosted',
+        category: 'identity',
+        cost_per_call_usdc: 0,
+        description: 'Resolves on-chain agent identities per ERC-8004 spec.',
+    },
+    {
+        id: 'pact-mandate-verify',
+        name: 'PACT Mandate Verifier',
+        provider: 'self-hosted',
+        category: 'identity',
+        cost_per_call_usdc: 0,
+        description: 'Verifies PACT mandate signatures for delegated agent actions.',
+    },
+];
+/**
+ * Internal index keyed by tool id for O(1) lookup.
+ * Rebuilt at module load; safe because TOOL_LAYER is a const literal.
+ */
+const TOOL_INDEX = new Map(exports.TOOL_LAYER.map((tool) => [tool.id, tool]));
+/**
+ * Resolve a list of tool ids to their entries.
+ * Unknown ids are silently dropped — callers needing strict validation
+ * should compare result length to input length.
+ */
+function getToolsByIds(ids) {
+    const seen = new Set();
+    const out = [];
+    for (const id of ids) {
+        if (seen.has(id))
+            continue;
+        seen.add(id);
+        const tool = TOOL_INDEX.get(id);
+        if (tool)
+            out.push(tool);
+    }
+    return out;
+}
+/**
+ * List every tool in a given category.
+ * Returns empty array for unknown categories.
+ */
+function listToolsByCategory(category) {
+    return exports.TOOL_LAYER.filter((tool) => tool.category === category);
+}
+/**
+ * Estimate total cost in USDC for invoking the given tools `expectedCalls` times each.
+ *
+ * Formula: sum(tool.cost_per_call_usdc for tool in resolved_tools) × expectedCalls
+ *
+ * Unknown tool ids contribute 0. Negative `expectedCalls` is clamped to 0.
+ */
+function estimateToolCost(toolIds, expectedCalls) {
+    const calls = Math.max(0, expectedCalls);
+    if (calls === 0)
+        return 0;
+    const tools = getToolsByIds(toolIds);
+    const perCallSum = tools.reduce((acc, tool) => acc + tool.cost_per_call_usdc, 0);
+    return perCallSum * calls;
+}

package/dist/lib/tool-layer.js

@@ -0,0 +1,249 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TOOL_LAYER = void 0;
+exports.getToolsByIds = getToolsByIds;
+exports.listToolsByCategory = listToolsByCategory;
+exports.estimateToolCost = estimateToolCost;
+exports.unknownToolIds = unknownToolIds;
+/**
+ * Tool Layer (TICKET-125) — the registry of external capabilities agents call,
+ * with per-call cost metadata used for cost estimation + capability discovery.
+ *
+ * The curated catalog below is the base registry; a workspace extends or
+ * overrides it via `.kognai/tools.json` (merged at module load). Consumers:
+ * cost-estimator, build planners, capability matchers, and the mandate preview.
+ */
+const registry_overrides_1 = require("./registry-overrides");
+exports.TOOL_LAYER = [
+    // ── database ─────────────────────────────────────────────────────────────
+    {
+        id: 'postgres-encrypted',
+        name: 'PostgreSQL (Encrypted)',
+        provider: 'self-hosted',
+        category: 'database',
+        cost_per_call_usdc: 0,
+        description: 'Self-hosted Postgres with at-rest encryption and pgcrypto.',
+    },
+    {
+        id: 'redis-cache',
+        name: 'Redis Cache',
+        provider: 'self-hosted',
+        category: 'database',
+        cost_per_call_usdc: 0,
+        description: 'In-memory key-value store for caching and rate limiting.',
+    },
+    {
+        id: 'supabase',
+        name: 'Supabase Postgres',
+        provider: 'supabase',
+        category: 'database',
+        cost_per_call_usdc: 0.00005,
+        description: 'Managed Postgres with row-level security and realtime.',
+    },
+    // ── llm ──────────────────────────────────────────────────────────────────
+    {
+        id: 'anthropic-sonnet',
+        name: 'Anthropic Claude Sonnet',
+        provider: 'anthropic',
+        category: 'llm',
+        cost_per_call_usdc: 0.015,
+        description: 'Mid-tier reasoning LLM, ~1k token avg call.',
+    },
+    {
+        id: 'anthropic-haiku',
+        name: 'Anthropic Claude Haiku',
+        provider: 'anthropic',
+        category: 'llm',
+        cost_per_call_usdc: 0.0012,
+        description: 'Fast cheap LLM for classification and routing.',
+    },
+    {
+        id: 'qwen-plus',
+        name: 'Qwen Plus (Cloud)',
+        provider: 'alibaba',
+        category: 'llm',
+        cost_per_call_usdc: 0.0008,
+        description: 'Cloud-hosted Qwen Plus for general-purpose generation.',
+    },
+    {
+        id: 'ollama-local',
+        name: 'Ollama (Local)',
+        provider: 'self-hosted',
+        category: 'llm',
+        cost_per_call_usdc: 0,
+        description: 'Local LLM runtime (Qwen3, Llama, etc.) — zero per-call cost.',
+    },
+    // ── search ───────────────────────────────────────────────────────────────
+    {
+        id: 'tavily',
+        name: 'Tavily Search API',
+        provider: 'tavily',
+        category: 'search',
+        cost_per_call_usdc: 0.005,
+        description: 'LLM-optimized web search with snippet extraction.',
+    },
+    {
+        id: 'exa',
+        name: 'Exa Neural Search',
+        provider: 'exa',
+        category: 'search',
+        cost_per_call_usdc: 0.01,
+        description: 'Neural search over indexed web content.',
+    },
+    // ── payment ──────────────────────────────────────────────────────────────
+    {
+        id: 'x402-meter',
+        name: 'x402 Payment Meter',
+        provider: 'x402',
+        category: 'payment',
+        cost_per_call_usdc: 0.0001,
+        description: 'HTTP 402 micropayment metering for per-call billing.',
+    },
+    {
+        id: 'stripe-webhook',
+        name: 'Stripe Webhook Handler',
+        provider: 'stripe',
+        category: 'payment',
+        cost_per_call_usdc: 0,
+        description: 'Receive and verify Stripe webhook events (cost is in fees, not calls).',
+    },
+    // ── compliance ───────────────────────────────────────────────────────────
+    {
+        id: 'hipaa-bcc-checker',
+        name: 'HIPAA BAA/BCC Checker',
+        provider: 'self-hosted',
+        category: 'compliance',
+        cost_per_call_usdc: 0,
+        description: 'Verifies BAA coverage and BCC routing for PHI workflows.',
+    },
+    {
+        id: 'gdpr-data-mapper',
+        name: 'GDPR Data Mapper',
+        provider: 'self-hosted',
+        category: 'compliance',
+        cost_per_call_usdc: 0,
+        description: 'Tracks personal-data lineage for GDPR Article 30 records.',
+    },
+    // ── observability ────────────────────────────────────────────────────────
+    {
+        id: 'posthog',
+        name: 'PostHog Analytics',
+        provider: 'posthog',
+        category: 'observability',
+        cost_per_call_usdc: 0.00001,
+        description: 'Product analytics, session replay, and feature flags.',
+    },
+    {
+        id: 'datadog',
+        name: 'Datadog APM',
+        provider: 'datadog',
+        category: 'observability',
+        cost_per_call_usdc: 0.0002,
+        description: 'Application performance monitoring and log aggregation.',
+    },
+    {
+        id: 'sentry',
+        name: 'Sentry Error Tracking',
+        provider: 'sentry',
+        category: 'observability',
+        cost_per_call_usdc: 0.00005,
+        description: 'Error capture, stack traces, and release tracking.',
+    },
+    // ── identity ─────────────────────────────────────────────────────────────
+    {
+        id: 'erc-8004-resolver',
+        name: 'ERC-8004 Agent Resolver',
+        provider: 'self-hosted',
+        category: 'identity',
+        cost_per_call_usdc: 0,
+        description: 'Resolves on-chain agent identities per ERC-8004 spec.',
+    },
+    {
+        id: 'pact-mandate-verify',
+        name: 'PACT Mandate Verifier',
+        provider: 'self-hosted',
+        category: 'identity',
+        cost_per_call_usdc: 0,
+        description: 'Verifies PACT mandate signatures for delegated agent actions.',
+    },
+    // --- template-aligned capabilities (TICKET-233) ---
+    { id: "web-search", name: "Web Search", provider: "external", category: "research", cost_per_call_usdc: 0.002, description: "Web Search — capability used by kognai-build templates." },
+    { id: "pdf-reader", name: "Pdf Reader", provider: "external", category: "research", cost_per_call_usdc: 0.002, description: "Pdf Reader — capability used by kognai-build templates." },
+    { id: "citation-manager", name: "Citation Manager", provider: "external", category: "research", cost_per_call_usdc: 0.002, description: "Citation Manager — capability used by kognai-build templates." },
+    { id: "markdown-editor", name: "Markdown Editor", provider: "self-hosted", category: "content", cost_per_call_usdc: 0, description: "Markdown Editor — capability used by kognai-build templates." },
+    { id: "grammar-checker", name: "Grammar Checker", provider: "self-hosted", category: "content", cost_per_call_usdc: 0, description: "Grammar Checker — capability used by kognai-build templates." },
+    { id: "readability-scorer", name: "Readability Scorer", provider: "self-hosted", category: "content", cost_per_call_usdc: 0, description: "Readability Scorer — capability used by kognai-build templates." },
+    { id: "vite", name: "Vite", provider: "self-hosted", category: "build", cost_per_call_usdc: 0, description: "Vite — capability used by kognai-build templates." },
+    { id: "typescript-checker", name: "Typescript Checker", provider: "self-hosted", category: "build", cost_per_call_usdc: 0, description: "Typescript Checker — capability used by kognai-build templates." },
+    { id: "eslint", name: "Eslint", provider: "self-hosted", category: "build", cost_per_call_usdc: 0, description: "Eslint — capability used by kognai-build templates." },
+    { id: "slither", name: "Slither", provider: "self-hosted", category: "security", cost_per_call_usdc: 0, description: "Slither — capability used by kognai-build templates." },
+    { id: "foundry", name: "Foundry", provider: "self-hosted", category: "security", cost_per_call_usdc: 0, description: "Foundry — capability used by kognai-build templates." },
+    { id: "echidna-fuzzer", name: "Echidna Fuzzer", provider: "self-hosted", category: "security", cost_per_call_usdc: 0, description: "Echidna Fuzzer — capability used by kognai-build templates." },
+    { id: "audit-trail-emitter", name: "Audit Trail Emitter", provider: "self-hosted", category: "security", cost_per_call_usdc: 0, description: "Audit Trail Emitter — capability used by kognai-build templates." },
+    { id: "commander", name: "Commander", provider: "self-hosted", category: "build", cost_per_call_usdc: 0, description: "Commander — capability used by kognai-build templates." },
+    { id: "bash", name: "Bash", provider: "self-hosted", category: "build", cost_per_call_usdc: 0, description: "Bash — capability used by kognai-build templates." },
+    { id: "node-runtime", name: "Node Runtime", provider: "self-hosted", category: "build", cost_per_call_usdc: 0, description: "Node Runtime — capability used by kognai-build templates." },
+    { id: "airflow", name: "Airflow", provider: "self-hosted", category: "data", cost_per_call_usdc: 0, description: "Airflow — capability used by kognai-build templates." },
+    { id: "dbt", name: "Dbt", provider: "self-hosted", category: "data", cost_per_call_usdc: 0, description: "Dbt — capability used by kognai-build templates." },
+    { id: "great-expectations", name: "Great Expectations", provider: "self-hosted", category: "data", cost_per_call_usdc: 0, description: "Great Expectations — capability used by kognai-build templates." },
+    { id: "k6", name: "K6", provider: "self-hosted", category: "performance", cost_per_call_usdc: 0, description: "K6 — capability used by kognai-build templates." },
+    { id: "clinic-js", name: "Clinic Js", provider: "self-hosted", category: "performance", cost_per_call_usdc: 0, description: "Clinic Js — capability used by kognai-build templates." },
+    { id: "websocket-bench", name: "Websocket Bench", provider: "self-hosted", category: "performance", cost_per_call_usdc: 0, description: "Websocket Bench — capability used by kognai-build templates." },
+    { id: "hyperframes", name: "Hyperframes", provider: "self-hosted", category: "media", cost_per_call_usdc: 0, description: "Hyperframes — capability used by kognai-build templates." },
+    { id: "ffmpeg", name: "Ffmpeg", provider: "self-hosted", category: "media", cost_per_call_usdc: 0, description: "Ffmpeg — capability used by kognai-build templates." },
+    { id: "scorsese-renderer", name: "Scorsese Renderer", provider: "self-hosted", category: "media", cost_per_call_usdc: 0, description: "Scorsese Renderer — capability used by kognai-build templates." },
+];
+// Merge optional workspace overrides (.kognai/tools.json) before the index is
+// built — makes the registry real & extensible, not a frozen catalog.
+(0, registry_overrides_1.applyRegistryOverrides)(exports.TOOL_LAYER, 'tools.json');
+/**
+ * Internal index keyed by tool id for O(1) lookup.
+ * Rebuilt at module load over the merged registry.
+ */
+const TOOL_INDEX = new Map(exports.TOOL_LAYER.map((tool) => [tool.id, tool]));
+/**
+ * Resolve a list of tool ids to their entries.
+ * Unknown ids are silently dropped — callers needing strict validation
+ * should compare result length to input length.
+ */
+function getToolsByIds(ids) {
+    const seen = new Set();
+    const out = [];
+    for (const id of ids) {
+        if (seen.has(id))
+            continue;
+        seen.add(id);
+        const tool = TOOL_INDEX.get(id);
+        if (tool)
+            out.push(tool);
+    }
+    return out;
+}
+/**
+ * List every tool in a given category.
+ * Returns empty array for unknown categories.
+ */
+function listToolsByCategory(category) {
+    return exports.TOOL_LAYER.filter((tool) => tool.category === category);
+}
+/**
+ * Estimate total cost in USDC for invoking the given tools `expectedCalls` times each.
+ *
+ * Formula: sum(tool.cost_per_call_usdc for tool in resolved_tools) × expectedCalls
+ *
+ * Unknown tool ids contribute 0. Negative `expectedCalls` is clamped to 0.
+ */
+function estimateToolCost(toolIds, expectedCalls) {
+    const calls = Math.max(0, expectedCalls);
+    if (calls === 0)
+        return 0;
+    const tools = getToolsByIds(toolIds);
+    const perCallSum = tools.reduce((acc, tool) => acc + tool.cost_per_call_usdc, 0);
+    return perCallSum * calls;
+}
+/** Return any tool ids not present in the registry (for template validation). */
+function unknownToolIds(ids) {
+    if (!Array.isArray(ids))
+        return [];
+    return ids.filter((id) => !TOOL_INDEX.has(id));
+}