@kognai/orchestrator-core 0.1.2 → 0.1.4

package/dist/index.d.ts

@@ -23,6 +23,7 @@ export * from './lib/trust-score-updater';
 export * from './lib/citizenship';
 export * from './lib/agent-registry';
 export * from './lib/sprint-state';
+export * from './lib/build-triage';
 export * as ksl from './lib/ksl';
 export * from './lib/wallet-state';
 export * from './lib/ceo-wallet';
@@ -60,6 +61,8 @@ export { CTOApprovalResult, requestCTOApproval, batchCTOReview } from './lib/cto
 export * from './lib/citizen-score-contract';
 export * from './lib/citizen-score-registry';
 export * from './lib/sovereign-agent-factory';
+export * from './lib/did-resolver-registry';
+export * from './lib/preamble-provider-registry';
 export { runOrchestrator } from './lib/orchestrate-engine';
 export type { OrchestratorConfig, SpawnGate, SpawnGateResult, AgentSpawnSpec, } from './lib/orchestrate-engine';
 export { runSprintCycle, SprintRunnerOpts } from './lib/sprint-runner-engine';

package/dist/index.js

@@ -82,6 +82,9 @@ __exportStar(require("./lib/citizenship"), exports);
 __exportStar(require("./lib/agent-registry"), exports);
 // TICKET-098 sprint runtime-state split (committed defs vs gitignored status).
 __exportStar(require("./lib/sprint-state"), exports);
+// TICKET-234 build triage seam — classifyBuildPath (ceremony-depth axis) +
+// logBuildTriage. Consumed by the orchestrator run loop AND by kognai-build.
+__exportStar(require("./lib/build-triage"), 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.
@@ -173,6 +176,9 @@ __exportStar(require("./lib/citizen-score-registry"), exports);
 __exportStar(require("./lib/sovereign-agent-factory"), exports);
 // TICKET-215 Wave D split step 2: engine + sprint-runner entry points.
 // Inject seams via kognai-bootstrap (side-effect import) before calling.
+// TICKET-226 A1: template-carried polity seams (DID resolution + constitutional preamble).
+__exportStar(require("./lib/did-resolver-registry"), exports);
+__exportStar(require("./lib/preamble-provider-registry"), exports);
 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");

package/dist/lib/build-triage.d.ts

@@ -0,0 +1,27 @@
+export type BuildPath = 'regulated' | 'fast';
+export interface BuildTriageResult {
+    path: BuildPath;
+    reason: string;
+    triggers: string[];
+    sensitive: boolean;
+    sovereign: boolean;
+    complexity: 'low' | 'medium' | 'high';
+    taskCount: number;
+    codeFileCount: number;
+}
+/**
+ * Classify a build into a ceremony-depth path. Pure + synchronous: it only reads
+ * the sprint JSON + task list, so it adds negligible cost relative to the
+ * ceremony it gates. Default-to-regulated on uncertainty.
+ *
+ * @param sprint  the raw sprint object (may carry regulated/strict/fast_track/sovereign flags)
+ * @param tasks   the loaded task list (each with deliverables/context/type)
+ */
+export declare function classifyBuildPath(sprint: any, tasks: any[]): BuildTriageResult;
+/**
+ * Append the triage decision to logs/routing/triage.jsonl (location-independent
+ * via engine-paths). Best-effort: never throws into the run loop. This is the
+ * audit trail required by the ticket — evidence that triage routes correctly and
+ * the means to audit any fast-tracked build later.
+ */
+export declare function logBuildTriage(sprintId: string, result: BuildTriageResult): void;

package/dist/lib/build-triage.js

@@ -0,0 +1,202 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.classifyBuildPath = classifyBuildPath;
+exports.logBuildTriage = logBuildTriage;
+/**
+ * build-triage.ts — TICKET-234: pre-orchestrator build triage (ceremony-depth axis).
+ *
+ * The orchestrator historically ran the SAME full ceremony for every build
+ * regardless of complexity or sensitivity (CEO assessment → execution →
+ * dual-supervisor review → CTO data analysis → CEO proposal cycle → post-sprint
+ * + agent minting). A 3-line `addTwo` cost 171s + the entire ceremony.
+ *
+ * This module adds a cheap classifier that runs BEFORE the orchestrator hands
+ * off to the swarm and routes the build to one of two execution paths:
+ *
+ *   - REGULATED (full ceremony) — CEO · CTO governance gate · dual-supervisor
+ *     review · reconciliation · the full CTO/CEO proposal cycle. Templates apply
+ *     on this path only. For sensitive / sovereign / complex builds.
+ *
+ *   - FAST  — coder → single-supervisor review → the minimum safety/security/
+ *     quality gate (QA gate: typecheck/compile/no-secrets, always on). No
+ *     dual-supervisor, no CTO/CEO post-sprint ceremony, no templates. For
+ *     simple, low-stakes, single-file, non-sensitive builds.
+ *
+ * It is the CEREMONY-DEPTH axis. It composes WITH `assessTaskComplexity`
+ * (engine-helpers), which scores the MODEL-ROUTING axis — they are orthogonal:
+ * a fast-tracked build can still route to a cloud model, and a regulated build
+ * can still run local. This stays a PURE HEURISTIC (no LLM call) so the triage
+ * never reintroduces the overhead it removes.
+ *
+ * Safety invariant: DEFAULT TO REGULATED on any uncertainty. `fast` is returned
+ * only when the build is provably simple AND non-sensitive AND non-sovereign.
+ * A `fast_track` opt-in never lowers the safety floor — sensitivity/complexity
+ * still force REGULATED.
+ */
+const fs_1 = require("fs");
+const path_1 = require("path");
+const engine_paths_1 = require("./engine-paths");
+// Sensitivity keywords — PHI/PII, payments/financial, auth/secrets/credentials,
+// crypto/on-chain/contracts, destructive or privileged operations. A match in a
+// deliverable path, task context, or sprint goal forces REGULATED.
+const SENSITIVE_KEYWORDS = [
+    // auth / secrets / credentials
+    'auth', 'secret', 'credential', 'password', 'passwd', 'api[_-]?key', 'apikey',
+    'access[_-]?token', 'private[_-]?key', 'privatekey', 'seed[_-]?phrase', 'mnemonic',
+    'oauth', 'jwt', 'session[_-]?token', 'vault',
+    // payments / financial
+    'payment', 'billing', 'invoice', 'payout', 'stripe', 'paypal', 'charge', 'refund',
+    'kyc', 'ledger', 'wallet', 'pricing',
+    // crypto / on-chain / contracts
+    'x402', 'crypto', 'on[_-]?chain', 'onchain', 'blockchain', 'smart[_-]?contract',
+    'erc20', 'erc-20', 'usdc', '\\$kog', 'viem', 'web3',
+    // PHI / PII / regulated data
+    '\\bphi\\b', '\\bpii\\b', 'gdpr', 'hipaa', 'personal[_-]?data', 'health[_-]?record',
+    // schema / data migrations (high-blast-radius, hard to roll back)
+    'migration', 'prisma/migrations', 'drop[_-]?table', 'alter[_-]?table',
+];
+// Destructive / privileged operations — context-level matches force REGULATED.
+const DESTRUCTIVE_KEYWORDS = [
+    'rm\\s+-rf', 'drop\\s+table', 'delete\\s+from', 'truncate\\s+table',
+    'force[_-]?push', '--force', 'chmod\\s+777', 'sudo\\b', 'kill\\s+-9',
+];
+// Sensitive directories — a deliverable under one of these forces REGULATED.
+const SENSITIVE_DIRS = [
+    'banks/', 'wallet', 'ceo-wallet', 'gates/', 'policy/', 'contracts/', 'omel/',
+    'x402-base/', 'prisma/', 'credential', '.env', 'auth/', 'secrets/',
+];
+// Architectural / cross-cutting keywords — a match means the change is not a
+// simple single-concern build → REGULATED.
+const ARCHITECTURAL_KEYWORDS = [
+    'architect', 'refactor', 'migrate', 'cross[_-]?cutting', 'system[_-]?wide',
+    'redesign', 'database', 'schema', 'infrastructure', 'orchestrat', 'pipeline',
+    'framework', 'breaking[_-]?change', 'rewrite',
+];
+function compile(words) {
+    return new RegExp(`(${words.join('|')})`, 'i');
+}
+const SENSITIVE_RE = compile(SENSITIVE_KEYWORDS);
+const DESTRUCTIVE_RE = compile(DESTRUCTIVE_KEYWORDS);
+const ARCH_RE = compile(ARCHITECTURAL_KEYWORDS);
+function asBool(v) {
+    return v === true || v === 'true' || v === 1 || v === '1';
+}
+/**
+ * Classify a build into a ceremony-depth path. Pure + synchronous: it only reads
+ * the sprint JSON + task list, so it adds negligible cost relative to the
+ * ceremony it gates. Default-to-regulated on uncertainty.
+ *
+ * @param sprint  the raw sprint object (may carry regulated/strict/fast_track/sovereign flags)
+ * @param tasks   the loaded task list (each with deliverables/context/type)
+ */
+function classifyBuildPath(sprint, tasks) {
+    const triggers = [];
+    const taskList = Array.isArray(tasks) ? tasks : [];
+    const taskCount = taskList.length;
+    // Gather all the text we scan for sensitivity/architecture signals.
+    const deliverablePaths = [];
+    const codeFiles = [];
+    for (const t of taskList) {
+        const d = (t && t.deliverables) || {};
+        const code = Array.isArray(d.code) ? d.code : [];
+        const tests = Array.isArray(d.tests) ? d.tests : [];
+        const docs = Array.isArray(d.docs) ? d.docs : [];
+        codeFiles.push(...code);
+        deliverablePaths.push(...code, ...tests, ...docs);
+    }
+    const codeFileCount = new Set(codeFiles).size;
+    const contextText = taskList
+        .map((t) => `${(t && (t.context || t.title || t.id)) || ''} ${(t && (t.type || t.task_type)) || ''}`)
+        .join(' ');
+    const goalText = `${sprint?.name || sprint?.title || ''} ${sprint?.goal || sprint?.description || ''}`;
+    const pathText = deliverablePaths.join(' ');
+    const haystack = `${goalText} ${contextText} ${pathText}`;
+    // ── Explicit flags ────────────────────────────────────────────────────────
+    const forcedRegulated = asBool(sprint?.regulated) || asBool(sprint?.strict) || asBool(process.env.KOGNAI_FORCE_REGULATED);
+    const requestedFast = asBool(sprint?.fast_track) || asBool(sprint?.fast);
+    if (forcedRegulated)
+        triggers.push('explicit:regulated');
+    // ── Sensitivity ───────────────────────────────────────────────────────────
+    let sensitive = false;
+    if (SENSITIVE_RE.test(haystack)) {
+        sensitive = true;
+        triggers.push(`sensitive:keyword(${(haystack.match(SENSITIVE_RE) || [])[1]})`);
+    }
+    if (DESTRUCTIVE_RE.test(haystack)) {
+        sensitive = true;
+        triggers.push(`sensitive:destructive(${(haystack.match(DESTRUCTIVE_RE) || [])[1]})`);
+    }
+    const dirHit = SENSITIVE_DIRS.find((dir) => pathText.toLowerCase().includes(dir.toLowerCase()));
+    if (dirHit) {
+        sensitive = true;
+        triggers.push(`sensitive:path(${dirHit})`);
+    }
+    // ── Sovereign / regulated domain ──────────────────────────────────────────
+    const sovereign = asBool(sprint?.sovereign) || asBool(sprint?.regulated_domain);
+    if (sovereign)
+        triggers.push('sovereign');
+    // ── Complexity (ceremony-depth, NOT model routing) ────────────────────────
+    const estimated = String(sprint?.estimated_complexity || '').toLowerCase();
+    const archHit = ARCH_RE.test(haystack);
+    if (archHit)
+        triggers.push(`complex:architectural(${(haystack.match(ARCH_RE) || [])[1]})`);
+    if (taskCount > 1)
+        triggers.push(`complex:multi-task(${taskCount})`);
+    if (codeFileCount > 1)
+        triggers.push(`complex:multi-file(${codeFileCount})`);
+    if (estimated === 'high')
+        triggers.push('complex:estimated-high');
+    let complexity = 'low';
+    if (archHit || taskCount > 2 || codeFileCount > 2 || estimated === 'high')
+        complexity = 'high';
+    else if (taskCount > 1 || codeFileCount > 1 || estimated === 'medium')
+        complexity = 'medium';
+    // ── Decision (default-to-regulated) ───────────────────────────────────────
+    // A build is FAST-eligible only if it is provably simple AND nothing sensitive
+    // / sovereign / forced fired. Anything ambiguous → REGULATED.
+    const isSimple = taskCount === 1 && codeFileCount <= 1 && !archHit && estimated !== 'high';
+    const blockFast = forcedRegulated || sensitive || sovereign || !isSimple;
+    let path;
+    let reason;
+    if (blockFast) {
+        path = 'regulated';
+        reason =
+            forcedRegulated ? 'explicit --regulated/--strict flag'
+                : sensitive ? `sensitive build (${triggers.filter((t) => t.startsWith('sensitive')).join(', ')})`
+                    : sovereign ? 'sovereign / regulated-domain build'
+                        : `complexity above fast-track threshold (${triggers.filter((t) => t.startsWith('complex')).join(', ') || 'multi-concern'})`;
+    }
+    else {
+        path = 'fast';
+        reason = requestedFast
+            ? 'fast-track opt-in; simple non-sensitive single-file build'
+            : 'simple non-sensitive single-file build → fast track';
+    }
+    return { path, reason, triggers, sensitive, sovereign, complexity, taskCount, codeFileCount };
+}
+/**
+ * Append the triage decision to logs/routing/triage.jsonl (location-independent
+ * via engine-paths). Best-effort: never throws into the run loop. This is the
+ * audit trail required by the ticket — evidence that triage routes correctly and
+ * the means to audit any fast-tracked build later.
+ */
+function logBuildTriage(sprintId, result) {
+    try {
+        const file = (0, path_1.join)((0, engine_paths_1.resolveEnginePaths)().logs, 'routing', 'triage.jsonl');
+        (0, fs_1.mkdirSync)((0, path_1.dirname)(file), { recursive: true });
+        const row = {
+            sprint_id: sprintId,
+            path: result.path,
+            reason: result.reason,
+            triggers: result.triggers,
+            sensitive: result.sensitive,
+            sovereign: result.sovereign,
+            complexity: result.complexity,
+            task_count: result.taskCount,
+            code_file_count: result.codeFileCount,
+            logged_at: new Date().toISOString(),
+        };
+        (0, fs_1.appendFileSync)(file, JSON.stringify(row) + '\n');
+    }
+    catch { /* non-fatal — audit log must never break a run */ }
+}

package/dist/lib/did-resolver-registry.d.ts

@@ -0,0 +1,15 @@
+/**
+ * DID resolver seam — TICKET-226 Phase A1 (template-carried polity extraction).
+ *
+ * How an agent ROLE maps to a DID is a product concern, not an engine concern
+ * (the core is template-agnostic — TICKET-215). This seam lets a consuming
+ * template override DID resolution. OPTIONAL override: if no resolver is set the
+ * engine keeps its existing inline behavior, so adding this is NON-BREAKING.
+ * Phase A2 injects Kognai's citizenship-backed resolver; Phase A3 removes the
+ * engine's inline default.
+ */
+export type DidResolver = (role: string) => string;
+/** Inject a product-specific DID resolver (e.g. Kognai citizenship → did:kognai). */
+export declare function setDidResolver(fn: DidResolver): void;
+/** The injected resolver, or null if the engine should use its inline default. */
+export declare function getDidResolver(): DidResolver | null;

package/dist/lib/did-resolver-registry.js

@@ -0,0 +1,9 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.setDidResolver = setDidResolver;
+exports.getDidResolver = getDidResolver;
+let _resolver = null;
+/** Inject a product-specific DID resolver (e.g. Kognai citizenship → did:kognai). */
+function setDidResolver(fn) { _resolver = fn; }
+/** The injected resolver, or null if the engine should use its inline default. */
+function getDidResolver() { return _resolver; }

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

@@ -0,0 +1,71 @@
+import type { AgentTask, ReviewResult, CTOProposal, CTOReport } from './orchestrate-engine';
+export declare class SupervisorAgent {
+    private systemPrompt;
+    constructor();
+    reviewTask(task: AgentTask, files: string[]): Promise<ReviewResult>;
+}
+export declare class Supervisor2Agent {
+    private systemPrompt;
+    constructor();
+    reviewTask(task: AgentTask, files: string[]): Promise<ReviewResult>;
+}
+export interface DualReviewResult {
+    finalReview: ReviewResult;
+    review1: ReviewResult;
+    review2: ReviewResult;
+    consensus: boolean;
+    escalatedToCEO: boolean;
+    ceoDecision?: string;
+}
+export declare function reconcileSupervisorReviews(review1: ReviewResult, review2: ReviewResult, task: AgentTask, ceo: CEOAgent): Promise<DualReviewResult>;
+export declare class CEOAgent {
+    private systemPrompt;
+    constructor();
+    reviewSprintProgress(tasks: AgentTask[]): Promise<string>;
+    resolveReviewConflict(task: AgentTask, approvalReview: ReviewResult, rejectionReview: ReviewResult, approver: string, rejecter: string): Promise<string>;
+    reviewCTOProposals(ctoReport: CTOReport): Promise<string>;
+    generateDailyReport(tasks: AgentTask[], stats: {
+        tasksExecuted: number;
+        approved: number;
+        rejected: number;
+        conflicts?: number;
+        escalations?: number;
+    }, ctoReport: string, ctoDecisions: string): Promise<void>;
+}
+export declare class CTODataCollector {
+    collect(): string;
+}
+export declare class CTOAgent {
+    private systemPrompt;
+    private dataCollector;
+    constructor();
+    analyze(): Promise<CTOReport>;
+    /**
+     * Post-sprint analysis: autonomous retrospective that runs after every sprint.
+     * Analyzes sprint results, detects failure patterns, and saves a report.
+     * This runs the CTO techwatch `post-sprint-analysis` watch type.
+     */
+    postSprintAnalysis(tasks: any[], stats: any): Promise<string>;
+}
+export interface AgentSpawnSpec {
+    name: string;
+    role: string;
+    llm: 'minimax' | 'anthropic';
+    trigger: string;
+    prompt_summary: string;
+}
+export interface SpawnGateResult {
+    approved: boolean;
+    /** Human-readable reason when not approved (rejected or pending). */
+    rejection_reason?: string;
+    /** True when the spawn is suspended awaiting an out-of-band (e.g. human) approval. */
+    pending_approval?: boolean;
+    /** Optional one-line audit string logged on an approved decision. */
+    audit?: string;
+}
+export type SpawnGate = (spec: AgentSpawnSpec) => SpawnGateResult;
+export declare class AgentCreator {
+    private readonly spawnGate?;
+    constructor(spawnGate?: SpawnGate | undefined);
+    createAgent(spec: NonNullable<CTOProposal['agent_spec']>): string;
+}