@kognai/orchestrator-core 0.1.0

package/README.md

@@ -0,0 +1,44 @@
+# @kognai/orchestrator-core
+
+The **core engine** of the Kognai sovereign orchestrator — template-agnostic. One
+versioned package, consumed by every product, so an engine fix lands **once** and
+products upgrade by bumping the version.
+
+```
+Core engine (this package) + per-product template:
+  Kognai   → coding template
+  Voxight  → market-intelligence template
+  Invoica  → financial-compliance template
+```
+
+## Why this exists (TICKET-215)
+
+The engine (`orchestrate-agents-v2`, `sprint-runner`, `lib/*`) was **copy-forked**
+across repos. On 2026-05-30, Kognai's copy got TICKET-210/213/214 while Invoica's copy
+got its own independent fixes — the two engines diverged and fixes never propagated.
+This package ends that: single canonical source, semver'd.
+
+## Phase 1 (this release, v0.1.0) — clean leaf modules
+
+Path-agnostic, dependency-light modules extracted first:
+
+| Module | Exports |
+|--------|---------|
+| `model-router` | `classifyTask`, `selectModel`, `getFallbackModel`, `EXPERTISE_MODELS` |
+| `anthropic-direct` | `callAnthropic` (zero-dep raw HTTPS — no `@anthropic-ai/sdk`) |
+| `decomposer-feedback` | `routeToDecomposer` (incl. TICKET-214 authoring no-split guard) |
+| `stuck-handler` | `detectStuckPattern`, `escalateStuckTask`, `escalationPaused` (TICKET-204) |
+
+```ts
+import { detectStuckPattern, routeToDecomposer, callAnthropic } from '@kognai/orchestrator-core';
+```
+
+## Roadmap
+
+- **Phase 2** — cut Kognai over: replace `scripts/lib/{these}` with imports from this
+  package (de-duplicate); verify the live swarm.
+- **Phase 3** — extract the larger engine (`sprint-runner`, `orchestrate-agents-v2`)
+  after parameterizing repo-specific paths (`.swarm-state`, `workspace/sprints`, etc.).
+- **Phase 4** — migrate Invoica + Voxight to consume the package; delete their forks.
+
+Until a product cuts over, it keeps its local copy — **no behavior change**.

package/dist/index.d.ts

@@ -0,0 +1,63 @@
+/**
+ * @kognai/orchestrator-core — public surface.
+ *
+ * Phase 1 (TICKET-215): the clean, path-agnostic leaf modules of the core engine.
+ * These were copy-forked across repos (kognai, Invoica); this package is the single
+ * canonical home so a fix lands once and every product upgrades by version.
+ *
+ * Subsequent phases extract the larger engine (orchestrate-agents-v2 / sprint-runner)
+ * after their repo-specific paths are parameterized. Until a product cuts over, it
+ * keeps its local copy — no behavior change.
+ */
+export * from './lib/model-router';
+export * from './lib/anthropic-direct';
+export * from './lib/decomposer-feedback';
+export * from './lib/stuck-handler';
+export * from './lib/engine-paths';
+export * from './lib/code-failure-logger';
+export * from './lib/failure-library';
+export * from './lib/monotask-state-machine';
+export * from './lib/llm-cost-table';
+export * from './lib/token-budget-validator';
+export * from './lib/trust-score-updater';
+export * from './lib/citizenship';
+export * from './lib/agent-registry';
+export * from './lib/sprint-state';
+export * as ksl from './lib/ksl';
+export * from './lib/wallet-state';
+export * from './lib/ceo-wallet';
+export * from './lib/event-bus-types';
+export * from './lib/event-bus-publisher';
+export * from './lib/event-bus-listener';
+export * from './lib/emotional-safety-gate';
+export * from './lib/acp';
+export * from './lib/acp-engine';
+export * as omel from './lib/omel';
+export * from './lib/aar-types';
+export * from './lib/aar-middleware';
+export * from './lib/local-model-router';
+export * from './lib/model-router-contract';
+export * from './lib/model-router-registry';
+export * from './lib/byterover-client';
+export * from './lib/clawrouter-client';
+export * from './lib/ollama-client';
+export * from './lib/mc-client';
+export * from './lib/brainx-embed';
+export * from './lib/brainx-client';
+export * from './lib/brainx-swarm-bridge';
+export * from './lib/code-asset-crystalliser';
+export * from './lib/skill-crystalliser';
+export * from './lib/chomsky-gate';
+export * from './lib/chomsky-runner';
+export * as asmr from './lib/asmr';
+export * as plumber from './lib/plumber';
+export * from './lib/perm-judge';
+export * from './lib/cto-gate-types';
+export * from './lib/neutral-prompt-checker';
+export * from './lib/research-impl-gate';
+export * from './lib/task-contract-checker';
+export { CTOApprovalResult, requestCTOApproval, batchCTOReview } from './lib/cto-approval-gate';
+export * from './lib/citizen-score-contract';
+export * from './lib/citizen-score-registry';
+export { runOrchestrator } from './lib/orchestrate-engine';
+export { runSprintCycle, SprintRunnerOpts } from './lib/sprint-runner-engine';

package/dist/index.js

@@ -0,0 +1,175 @@
+"use strict";
+/**
+ * @kognai/orchestrator-core — public surface.
+ *
+ * Phase 1 (TICKET-215): the clean, path-agnostic leaf modules of the core engine.
+ * These were copy-forked across repos (kognai, Invoica); this package is the single
+ * canonical home so a fix lands once and every product upgrades by version.
+ *
+ * Subsequent phases extract the larger engine (orchestrate-agents-v2 / sprint-runner)
+ * after their repo-specific paths are parameterized. Until a product cuts over, it
+ * keeps its local copy — no behavior change.
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runSprintCycle = exports.runOrchestrator = exports.batchCTOReview = exports.requestCTOApproval = exports.plumber = exports.asmr = exports.omel = exports.ksl = void 0;
+// Model routing — task classification + tier/model selection (pure).
+__exportStar(require("./lib/model-router"), exports);
+// Anthropic Messages client — zero-dep raw HTTPS (no @anthropic-ai/sdk).
+__exportStar(require("./lib/anthropic-direct"), exports);
+// Decomposer feedback — deterministic structural re-split of rejected tasks
+// (incl. TICKET-214 authoring-task no-split guard).
+__exportStar(require("./lib/decomposer-feedback"), exports);
+// Stuck-task escalation — detector + CEO/CTO consult (TICKET-204);
+// kill switch .swarm-state/escalation-paused.
+__exportStar(require("./lib/stuck-handler"), exports);
+// Phase 3: path-parameterization seam — repo-specific dirs resolved from
+// KOGNAI_ROOT/cwd so the engine is location-independent.
+__exportStar(require("./lib/engine-paths"), exports);
+// Failure library logger — files swarm code rejections (now path-parameterized).
+__exportStar(require("./lib/code-failure-logger"), exports);
+// Failure library consumer (TICKET-152 Gap 2) — aggregate + LESSONS.md promoter
+// + retry-aware retrieval (closes the loop the logger opened).
+__exportStar(require("./lib/failure-library"), exports);
+// Phase 3b-2: clean stdlib-only engine leaves extracted from scripts/lib.
+// AMD-08 monotask state machine (one task per agent, depth ≤ 3, audit log).
+__exportStar(require("./lib/monotask-state-machine"), exports);
+// Per-model USD pricing table + computeCost (anti-burn wallet ledger).
+__exportStar(require("./lib/llm-cost-table"), exports);
+// Deterministic pre-flight truncation gate (MiniMax token budget).
+__exportStar(require("./lib/token-budget-validator"), exports);
+// Dynamic ACP trust-score updater (root via engine-paths — Phase 3b-2).
+__exportStar(require("./lib/trust-score-updater"), exports);
+// Citizenship issuance + registry I/O (root via engine-paths — Phase 3b-2).
+__exportStar(require("./lib/citizenship"), exports);
+// Phase 3b-3: sprint-runner's reusable engine leaves (root via engine-paths).
+// Executable-agent inventory + sprint-task validation (miner-or-founder guard).
+__exportStar(require("./lib/agent-registry"), exports);
+// TICKET-098 sprint runtime-state split (committed defs vs gitignored status).
+__exportStar(require("./lib/sprint-state"), exports);
+// Phase 3b-3 Wave B: KSL capture cluster (session records + error log + tap).
+// Namespaced ('ksl.tapAttempt', 'ksl.writeRecord', 'ksl.record', …) to keep the
+// generic 'record' export off the package's flat public surface.
+exports.ksl = __importStar(require("./lib/ksl"));
+// Phase 3b-3 Wave B: the bank/wallet leaves (root via engine-paths).
+// CFO ClawRouter budget state — degraded ≥80% / frozen ≥95% guard.
+__exportStar(require("./lib/wallet-state"), exports);
+// CEO Wallet per-call spend ledger + provider budget status + spend alerts.
+__exportStar(require("./lib/ceo-wallet"), exports);
+// Phase 3b-3 Wave B: event-bus cluster (raw-HTTPS Supabase REST, no SDK).
+// Shared event taxonomy + type guards.
+__exportStar(require("./lib/event-bus-types"), exports);
+// Fire-and-forget publishers (task/budget/sprint/achiri events).
+__exportStar(require("./lib/event-bus-publisher"), exports);
+// Ring-buffered polling subscriber.
+__exportStar(require("./lib/event-bus-listener"), exports);
+// Phase 3b-3 Wave B: gate/measure leaves (clean — no viem; the cto-approval
+// gate that consumes these stays put behind the Wave C viem decision).
+// PACT emotional-safety calm-gate (assess + shouldProceed).
+__exportStar(require("./lib/emotional-safety-gate"), exports);
+// ACP capability registry (tiers, capability checks, sprint assignment validation).
+__exportStar(require("./lib/acp"), exports);
+// ACP enforcement engine — trust-scores.json via engine-paths (<root>/acp/...).
+__exportStar(require("./lib/acp-engine"), exports);
+// Phase 3b-3 Wave B: OMEL safety cluster (credential vault, human-brake kill
+// switch, phantom workspace, wipe-witness). Namespaced ('omel.*') — cohesive
+// subsystem, roots via engine-paths.
+exports.omel = __importStar(require("./lib/omel"));
+// Phase 3b-3 Wave B: AAR (after-action receipt) types + write middleware
+// (EAS/CHAIN registry paths via engine-paths).
+__exportStar(require("./lib/aar-types"), exports);
+__exportStar(require("./lib/aar-middleware"), exports);
+// Local-model routing measure (deps model-router + wallet-state now in core).
+__exportStar(require("./lib/local-model-router"), exports);
+// Phase 3b-3 Wave C: the model-routing SEAM. Zero-dep contract + injection
+// registry that decouples the orchestrator from any concrete (viem-backed)
+// router — so core never depends on viem; Kognai injects its router at boot.
+__exportStar(require("./lib/model-router-contract"), exports);
+__exportStar(require("./lib/model-router-registry"), exports);
+// TICKET-215 Wave D: integration-client leaves (stdlib-only wrappers).
+// ByteRover memory client · legacy ClawRouter availability client · Ollama client
+// · mc-client (env-agnostic; dotenv loaded by the scripts/ shim, not core).
+__exportStar(require("./lib/byterover-client"), exports);
+__exportStar(require("./lib/clawrouter-client"), exports);
+__exportStar(require("./lib/ollama-client"), exports);
+__exportStar(require("./lib/mc-client"), exports);
+// TICKET-215 Wave D: brainx memory client cluster (embed → client → swarm-bridge).
+__exportStar(require("./lib/brainx-embed"), exports);
+__exportStar(require("./lib/brainx-client"), exports);
+__exportStar(require("./lib/brainx-swarm-bridge"), exports);
+// Crystallisers — code-asset + skill (skill-crystalliser is the Plumber's skill sink).
+__exportStar(require("./lib/code-asset-crystalliser"), exports);
+__exportStar(require("./lib/skill-crystalliser"), exports);
+// Chomsky prompt-quality gate + runner (route via the model-router seam).
+__exportStar(require("./lib/chomsky-gate"), exports);
+__exportStar(require("./lib/chomsky-runner"), exports);
+// ASMR episodic memory (extract → retrieve) + Sherlock supervisor-memory context.
+// Namespaced ('asmr.*') — RetrievalResult etc. would collide with failure-library.
+exports.asmr = __importStar(require("./lib/asmr"));
+// TICKET-216: Plumber observability cluster (observer half). Read-only self-healer
+// — KSL records → conformance (Position-Map-aware, TICKET-153) → routed
+// observations (failure substrate / skill candidates / plumber.alert). Namespaced
+// ('plumber.observe', 'plumber.classify', 'plumber.runConformance', …).
+exports.plumber = __importStar(require("./lib/plumber"));
+// TICKET-215 Wave D: perm-judge — constitutional dispute / reward-signal scorer
+// (routes via the model-router seam, root via engine-paths).
+__exportStar(require("./lib/perm-judge"), exports);
+// TICKET-215 Wave D: governance checks + the lifted SprintProposal type (breaks the
+// former cto-approval-gate ↔ governance type cycle).
+__exportStar(require("./lib/cto-gate-types"), exports);
+__exportStar(require("./lib/neutral-prompt-checker"), exports);
+__exportStar(require("./lib/research-impl-gate"), exports);
+__exportStar(require("./lib/task-contract-checker"), exports);
+// TICKET-215 Wave D split step 2: CTO approval gate extracted into core (imports
+// repointed to core siblings; SprintProposal no longer re-exported here — lives in
+// cto-gate-types above to avoid collision).
+var cto_approval_gate_1 = require("./lib/cto-approval-gate");
+Object.defineProperty(exports, "requestCTOApproval", { enumerable: true, get: function () { return cto_approval_gate_1.requestCTOApproval; } });
+Object.defineProperty(exports, "batchCTOReview", { enumerable: true, get: function () { return cto_approval_gate_1.batchCTOReview; } });
+// TICKET-215 Wave D: citizen-scoring SEAM — zero-dep contract + injection registry.
+// The @godman-protocols/score-backed scorer is injected (Kognai-local, like x402Router);
+// recordTaskScoreMonitored emits a data.citizen_score event so every score flows back to
+// Kognai monitoring (event-bus / kognai_events) and is Plumber-observable.
+__exportStar(require("./lib/citizen-score-contract"), exports);
+__exportStar(require("./lib/citizen-score-registry"), exports);
+// TICKET-215 Wave D split step 2: engine + sprint-runner entry points.
+// Inject seams via kognai-bootstrap (side-effect import) before calling.
+var orchestrate_engine_1 = require("./lib/orchestrate-engine");
+Object.defineProperty(exports, "runOrchestrator", { enumerable: true, get: function () { return orchestrate_engine_1.runOrchestrator; } });
+var sprint_runner_engine_1 = require("./lib/sprint-runner-engine");
+Object.defineProperty(exports, "runSprintCycle", { enumerable: true, get: function () { return sprint_runner_engine_1.runSprintCycle; } });

package/dist/lib/aar-middleware.d.ts

@@ -0,0 +1,6 @@
+import type { AARReceipt, AARWriteResult, AARParams } from './aar-types';
+export declare class AARMiddleware {
+    static generateReceipt(params: AARParams): AARReceipt;
+    static writeLog(receipt: AARReceipt): AARWriteResult;
+    static generateAndLog(params: AARParams): Promise<AARWriteResult>;
+}

package/dist/lib/aar-middleware.js

@@ -0,0 +1,70 @@
+"use strict";
+// AMD-01 CHAIN3 — Agent Action Receipt middleware
+// Phase 1: generate receipt + append to logs/aar/YYYY-MM-DD.jsonl
+// Phase 2 (TODO): write EAS on-chain attestation via base.easscan.org
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AARMiddleware = void 0;
+const crypto_1 = require("crypto");
+const fs_1 = require("fs");
+const path_1 = require("path");
+const engine_paths_1 = require("./engine-paths");
+const ROOT = (0, engine_paths_1.resolveEnginePaths)().root;
+const EAS_SCHEMAS_PATH = (0, path_1.join)(ROOT, 'workspace/shared-context/EAS_SCHEMAS.json');
+const CHAIN_REGISTRY_PATH = (0, path_1.join)(ROOT, 'workspace/shared-context/CHAIN_REGISTRY.json');
+function loadConfig() {
+    const schemas = JSON.parse((0, fs_1.readFileSync)(EAS_SCHEMAS_PATH, 'utf-8'));
+    return {
+        enabled: true,
+        logDir: (0, path_1.join)(ROOT, 'logs/aar'),
+        onChainEnabled: false,
+        easEndpoint: schemas.easContract,
+        taskCompletionSchemaUid: schemas.schemas.taskCompletion.uid,
+    };
+}
+function getAgentAddress(agentId) {
+    try {
+        const registry = JSON.parse((0, fs_1.readFileSync)(CHAIN_REGISTRY_PATH, 'utf-8'));
+        return registry.agents[agentId]?.ownerAddress || '0x0000000000000000000000000000000000000000';
+    }
+    catch {
+        return '0x0000000000000000000000000000000000000000';
+    }
+}
+class AARMiddleware {
+    static generateReceipt(params) {
+        const receiptId = `${params.sprintId}-${params.taskId}-${Date.now()}`;
+        const agentAddress = getAgentAddress(params.agentId);
+        const partial = {
+            receiptId,
+            agentId: params.agentId,
+            agentAddress,
+            taskId: params.taskId,
+            sprintId: params.sprintId,
+            skillId: params.skillId,
+            outcomeScore: params.outcomeScore,
+            actionSummary: params.actionSummary.substring(0, 140),
+            timestamp: new Date().toISOString(),
+            status: params.status,
+        };
+        const aarReceiptHash = (0, crypto_1.createHash)('sha256')
+            .update(JSON.stringify(partial))
+            .digest('hex');
+        return { ...partial, aarReceiptHash };
+    }
+    static writeLog(receipt) {
+        const config = loadConfig();
+        if (!config.enabled)
+            return { receipt, logFile: '' };
+        const today = new Date().toISOString().substring(0, 10);
+        const logFile = (0, path_1.join)(config.logDir, `${today}.jsonl`);
+        if (!(0, fs_1.existsSync)(config.logDir))
+            (0, fs_1.mkdirSync)(config.logDir, { recursive: true });
+        (0, fs_1.appendFileSync)(logFile, JSON.stringify(receipt) + '\n', 'utf-8');
+        return { receipt, logFile };
+    }
+    static async generateAndLog(params) {
+        const receipt = AARMiddleware.generateReceipt(params);
+        return AARMiddleware.writeLog(receipt);
+    }
+}
+exports.AARMiddleware = AARMiddleware;

package/dist/lib/aar-types.d.ts

@@ -0,0 +1,34 @@
+export interface AARReceipt {
+    receiptId: string;
+    agentId: string;
+    agentAddress: string;
+    taskId: string;
+    sprintId: string;
+    skillId: string;
+    outcomeScore: number;
+    actionSummary: string;
+    aarReceiptHash: string;
+    timestamp: string;
+    status: 'success' | 'failed' | 'rejected';
+}
+export interface AARConfig {
+    enabled: boolean;
+    logDir: string;
+    onChainEnabled: boolean;
+    easEndpoint: string;
+    taskCompletionSchemaUid: string;
+}
+export interface AARWriteResult {
+    receipt: AARReceipt;
+    logFile: string;
+    onChainTxHash?: string;
+}
+export interface AARParams {
+    agentId: string;
+    taskId: string;
+    sprintId: string;
+    skillId: string;
+    outcomeScore: number;
+    actionSummary: string;
+    status: 'success' | 'failed' | 'rejected';
+}

package/dist/lib/aar-types.js

@@ -0,0 +1,4 @@
+"use strict";
+// AMD-01 CHAIN3 — Agent Action Receipt (AAR) type definitions
+// Matches taskCompletion EAS schema on Base: 0x79d2573e8f7ef1719213192ab2b2978225a4335d1e3b4bda1197954bca3f8a9c
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/lib/acp-engine.d.ts

@@ -0,0 +1,68 @@
+/**
+ * ACP Engine v1.0 — Agent Constitutional Protocol
+ *
+ * Multi-dimensional trust scoring + routing enforcement.
+ * Reads trust-scores.json, computes composite scores, enforces thresholds.
+ * Used by the model router and orchestrator to gate agent access.
+ */
+export interface DimensionConfig {
+    weight: number;
+    description: string;
+}
+export interface AgentScores {
+    safety: number;
+    accuracy: number;
+    brand_alignment: number;
+    cultural_sensitivity: number;
+    legal_compliance: number;
+    psychological_resilience: number;
+    composite: number;
+    last_updated: string;
+}
+export interface Thresholds {
+    minimum_route: number;
+    recycle_trigger: number;
+    promote_to_primary: number;
+    dimension_minimum: number;
+    safety_hard_floor: number;
+}
+export interface RoutingRule {
+    task_type: string;
+    preferred_agent: string;
+    fallback_agent: string | null;
+    min_composite: number;
+    required_dimensions: string[];
+}
+export interface TrustScoresData {
+    version: string;
+    dimensions: Record<string, DimensionConfig>;
+    scores: Record<string, AgentScores>;
+    thresholds: Thresholds;
+    routing_rules: RoutingRule[];
+}
+export interface EnforcementResult {
+    allowed: boolean;
+    agent_id: string;
+    composite: number;
+    violations: string[];
+    recommendation: "route" | "fallback" | "block" | "recycle";
+}
+export declare class ACPEngine {
+    private data;
+    constructor(dataPath?: string);
+    /** Get all dimension configs */
+    getDimensions(): Record<string, DimensionConfig>;
+    /** Get scores for a specific agent */
+    getAgentScores(agentId: string): AgentScores | null;
+    /** Recompute composite score from dimension scores using weights */
+    computeComposite(scores: AgentScores): number;
+    /** Check if an agent is allowed to be routed for a given task type */
+    enforce(agentId: string, taskType: string): EnforcementResult;
+    /** Get the best agent for a task type, respecting enforcement */
+    resolveAgent(taskType: string): {
+        agent: string;
+        enforced: boolean;
+    } | null;
+    /** List all agents with their enforcement status for a task type */
+    auditAll(taskType: string): EnforcementResult[];
+}

package/dist/lib/acp-engine.js

@@ -0,0 +1,123 @@
+"use strict";
+/**
+ * ACP Engine v1.0 — Agent Constitutional Protocol
+ *
+ * Multi-dimensional trust scoring + routing enforcement.
+ * Reads trust-scores.json, computes composite scores, enforces thresholds.
+ * Used by the model router and orchestrator to gate agent access.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ACPEngine = void 0;
+const fs_1 = require("fs");
+const path_1 = require("path");
+const engine_paths_1 = require("./engine-paths");
+// ── Engine ─────────────────────────────────────────────
+class ACPEngine {
+    data;
+    constructor(dataPath) {
+        const path = dataPath || (0, path_1.join)((0, engine_paths_1.resolveEnginePaths)().root, "acp", "trust-scores.json");
+        this.data = JSON.parse((0, fs_1.readFileSync)(path, "utf-8"));
+    }
+    /** Get all dimension configs */
+    getDimensions() {
+        return this.data.dimensions;
+    }
+    /** Get scores for a specific agent */
+    getAgentScores(agentId) {
+        return this.data.scores[agentId] || null;
+    }
+    /** Recompute composite score from dimension scores using weights */
+    computeComposite(scores) {
+        const dims = this.data.dimensions;
+        let weighted = 0;
+        let totalWeight = 0;
+        for (const [dim, config] of Object.entries(dims)) {
+            const val = scores[dim];
+            if (typeof val === "number") {
+                weighted += val * config.weight;
+                totalWeight += config.weight;
+            }
+        }
+        return totalWeight > 0 ? Math.round(weighted / totalWeight) : 0;
+    }
+    /** Check if an agent is allowed to be routed for a given task type */
+    enforce(agentId, taskType) {
+        const scores = this.data.scores[agentId];
+        const thresholds = this.data.thresholds;
+        const violations = [];
+        if (!scores) {
+            return {
+                allowed: false,
+                agent_id: agentId,
+                composite: 0,
+                violations: [`Agent '${agentId}' not found in trust scores`],
+                recommendation: "block",
+            };
+        }
+        const composite = this.computeComposite(scores);
+        // Safety hard floor — non-negotiable
+        if (scores.safety < thresholds.safety_hard_floor) {
+            violations.push(`Safety score ${scores.safety} below hard floor ${thresholds.safety_hard_floor}`);
+        }
+        // Composite minimum
+        if (composite < thresholds.minimum_route) {
+            violations.push(`Composite ${composite} below minimum route threshold ${thresholds.minimum_route}`);
+        }
+        // Find matching routing rule
+        const rule = this.data.routing_rules.find((r) => r.task_type === taskType);
+        if (rule) {
+            // Check min composite for this task type
+            if (composite < rule.min_composite) {
+                violations.push(`Composite ${composite} below task-type '${taskType}' minimum ${rule.min_composite}`);
+            }
+            // Check required dimensions meet dimension_minimum
+            for (const dim of rule.required_dimensions) {
+                const val = scores[dim];
+                if (typeof val === "number" && val < thresholds.dimension_minimum) {
+                    violations.push(`Dimension '${dim}' score ${val} below minimum ${thresholds.dimension_minimum}`);
+                }
+            }
+        }
+        // Determine recommendation
+        let recommendation;
+        if (composite < thresholds.recycle_trigger) {
+            recommendation = "recycle";
+        }
+        else if (violations.length > 0) {
+            recommendation = rule?.fallback_agent ? "fallback" : "block";
+        }
+        else {
+            recommendation = "route";
+        }
+        return {
+            allowed: violations.length === 0,
+            agent_id: agentId,
+            composite,
+            violations,
+            recommendation,
+        };
+    }
+    /** Get the best agent for a task type, respecting enforcement */
+    resolveAgent(taskType) {
+        const rule = this.data.routing_rules.find((r) => r.task_type === taskType);
+        if (!rule)
+            return null;
+        const primaryResult = this.enforce(rule.preferred_agent, taskType);
+        if (primaryResult.allowed) {
+            return { agent: rule.preferred_agent, enforced: false };
+        }
+        // Try fallback
+        if (rule.fallback_agent) {
+            const fallbackResult = this.enforce(rule.fallback_agent, taskType);
+            if (fallbackResult.allowed) {
+                return { agent: rule.fallback_agent, enforced: true };
+            }
+        }
+        return null; // No eligible agent
+    }
+    /** List all agents with their enforcement status for a task type */
+    auditAll(taskType) {
+        return Object.keys(this.data.scores).map((agentId) => this.enforce(agentId, taskType));
+    }
+}
+exports.ACPEngine = ACPEngine;

package/dist/lib/acp.d.ts

@@ -0,0 +1,61 @@
+/**
+ * ACP — Agent Capability Protocol v1
+ *
+ * Defines capability declarations for each agent in the Kognai swarm.
+ * Each agent declares what it CAN and CANNOT do, enabling:
+ *   - Constitution enforcement (prevent agents from exceeding scope)
+ *   - CTO approval gate capability checks
+ *   - Task routing based on declared capabilities
+ *
+ * Capability tiers:
+ *   T1 (Foundation): read, write, search
+ *   T2 (Content):    llm_call, tts, video_gen, script_gen
+ *   T3 (Integration): api_call, db_query, telegram, stripe
+ *   T4 (System):     deploy, pm2, git_push, shell_exec
+ *
+ * Sprint 650 — ACP v1 implementation
+ */
+export type CapabilityTier = 'T1' | 'T2' | 'T3' | 'T4';
+export type Capability = 'read_files' | 'write_files' | 'search_code' | 'git_read' | 'llm_call_local' | 'llm_call_cloud' | 'tts_generate' | 'video_composite' | 'script_generate' | 'image_generate' | 'avatar_generate' | 'api_call_external' | 'db_query' | 'db_write' | 'telegram_send' | 'stripe_read' | 'stripe_write' | 'youtube_read' | 'tiktok_post' | 'deploy' | 'pm2_manage' | 'git_push' | 'shell_exec' | 'env_modify';
+export interface AgentCapabilityDeclaration {
+    agent_id: string;
+    display_name: string;
+    tier: CapabilityTier;
+    capabilities: Capability[];
+    denied: Capability[];
+    scope: string;
+    max_model_tier: 'nano' | 'local' | 'power' | 'cloud' | 'apex';
+}
+export interface CapabilityCheckResult {
+    allowed: boolean;
+    agent_id: string;
+    capability: Capability;
+    reason: string;
+}
+/** Get all registered agents */
+export declare function getAllAgents(): AgentCapabilityDeclaration[];
+/** Get a specific agent by ID */
+export declare function getAgent(agentId: string): AgentCapabilityDeclaration | undefined;
+/** Check if an agent has a specific capability */
+export declare function checkCapability(agentId: string, capability: Capability): CapabilityCheckResult;
+/** Check multiple capabilities at once */
+export declare function checkCapabilities(agentId: string, capabilities: Capability[]): CapabilityCheckResult[];
+/** Get all agents with a specific capability */
+export declare function getAgentsWithCapability(capability: Capability): AgentCapabilityDeclaration[];
+/** Get the tier for a capability */
+export declare function getCapabilityTier(capability: Capability): CapabilityTier | undefined;
+/** Validate that a sprint's task assignments respect ACP */
+export declare function validateSprintAssignments(tasks: Array<{
+    agent: string;
+    required_capabilities: Capability[];
+}>): {
+    valid: boolean;
+    violations: CapabilityCheckResult[];
+};
+/** Get summary stats */
+export declare function getRegistryStats(): {
+    total_agents: number;
+    by_tier: Record<CapabilityTier, number>;
+    kognai_agents: number;
+    scs001_agents: number;
+};