@kognai/orchestrator-core 0.1.0 → 0.1.2

package/dist/index.d.ts

@@ -59,5 +59,7 @@ 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 * from './lib/sovereign-agent-factory';
 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

@@ -167,6 +167,10 @@ Object.defineProperty(exports, "batchCTOReview", { enumerable: true, get: functi
 // 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-223: Sovereign Agent Factory — all agent spawns go through here.
+// Constitutional basis: Charter Article II + founder ruling 2026-06-03.
+// Supersedes AGENTS.md manual Messi+Tarek approval rule.
+__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.
 var orchestrate_engine_1 = require("./lib/orchestrate-engine");

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

@@ -21,5 +21,27 @@
  * Flow: CEO plans → MiniMax codes → Dual Supervisor review (DeepSeek + Haiku)
  *       → CEO resolves conflicts → CTO analyzes → CMO reports → CEO daily report
  */
-declare function main(): Promise<void>;
+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;
+/** TICKET-225: engine config supplied by the consuming template. */
+export interface OrchestratorConfig {
+    /** Optional template-carried spawn governance gate (Kognai → SAF). */
+    spawnGate?: SpawnGate;
+}
+declare function main(config?: OrchestratorConfig): Promise<void>;
 export { main as runOrchestrator };

package/dist/lib/orchestrate-engine.js

@@ -1518,9 +1518,31 @@ Rules: Be specific — reference task IDs, rejection counts, concrete patterns.
         }
     }
 }
-// ===== Agent Creator (creates new agents from CEO-approved CTO proposals) =====
 class AgentCreator {
+    spawnGate;
+    constructor(spawnGate) {
+        this.spawnGate = spawnGate;
+    }
     createAgent(spec) {
+        // TICKET-225 — template-carried spawn governance. If the consuming template
+        // supplied a SpawnGate (Kognai wires SAF here), consult it BEFORE creating
+        // anything on disk. Approval/rejection only; the citizenship logic below is
+        // unchanged (its extraction is tracked separately as TICKET-226).
+        if (this.spawnGate) {
+            const decision = this.spawnGate(spec);
+            if (!decision.approved) {
+                const why = decision.rejection_reason ? `: ${decision.rejection_reason}` : '';
+                if (decision.pending_approval) {
+                    log(c.yellow, `  ⏸ Spawn of ${spec.name} pending approval${why}`);
+                }
+                else {
+                    log(c.red, `  ✗ Spawn of ${spec.name} blocked${why}`);
+                }
+                return '';
+            }
+            if (decision.audit)
+                log(c.gray, `  ✓ ${decision.audit}`);
+        }
         const agentDir = `./agents/${spec.name}`;
         (0, fs_1.mkdirSync)(agentDir, { recursive: true });
         // Founder rule 2026-05-27: every spawned agent is born as a Kognai
@@ -2939,6 +2961,7 @@ ${originalContent}
 }
 // ===== Orchestrator (Dynamic Agent Pipeline) =====
 class Orchestrator {
+    spawnGate;
     ceo;
     cto;
     supervisor;
@@ -3046,7 +3069,10 @@ class Orchestrator {
             (0, fs_1.writeFileSync)(sprintFile, JSON.stringify(sprintRaw, null, 2));
         log(c.green, `    [inject] Added ${injected} split sub-tasks to ${sprintFile} (in-memory + on-disk)`);
     }
-    constructor() {
+    // TICKET-225: optional template-supplied spawn governance gate, threaded
+    // from runOrchestrator(config) down to AgentCreator. Undefined = no gate.
+    constructor(spawnGate) {
+        this.spawnGate = spawnGate;
         log(c.bold, '\n╔══════════════════════════════════════════════════════════╗');
         log(c.bold, '║   Kognai Swarm Orchestrator v2.17 — V17 Architecture     ║');
         log(c.bold, '║   Local-first · ClawRouter cloud · DeepSeek reviews      ║');
@@ -4163,7 +4189,7 @@ ONLY output the JSON array. No markdown, no explanation.`;
                 // Persist CEO decisions for CTO feedback loop + approved proposals tracking
                 persistCEODecisions(ctoDecisions, ctoReport);
                 // Handle approved new_agent proposals
-                const agentCreator = new AgentCreator();
+                const agentCreator = new AgentCreator(this.spawnGate);
                 for (const proposal of ctoReport.proposals) {
                     if (proposal.category === 'new_agent' && proposal.agent_spec) {
                         // Check if CEO approved this specific proposal
@@ -4414,8 +4440,7 @@ async function postSprintSmokeTest() {
     // Disabled — Invoica-specific endpoints (health/invoices/settlements) not applicable to Kognai
     // Removed Sprint 205: was always returning HTTP 404 + flooding Telegram with false alerts
 }
-// ===== Main Entry =====
-async function main() {
+async function main(config = {}) {
     // S67-005: Startup env check (OMEL AMD-13: via CredentialVault — hasSecret never logs value)
     if (!credential_vault_1.credentialVault.hasSecret('ANTHROPIC_API_KEY', 'orchestrator')) {
         log(c.yellow, '⚠  ANTHROPIC_API_KEY not set — Anthropic CEO + Sup2 Haiku will be unavailable.');
@@ -4425,7 +4450,7 @@ async function main() {
         log(c.yellow, '⚠  MINIMAX_API_KEY not set — cloud-code tasks will fail.');
     }
     try {
-        const orchestrator = new Orchestrator();
+        const orchestrator = new Orchestrator(config.spawnGate);
         await orchestrator.run();
     }
     catch (error) {

package/dist/lib/sovereign-agent-factory.d.ts

@@ -0,0 +1,110 @@
+/**
+ * Sovereign Agent Factory (SAF) — TICKET-223
+ *
+ * Constitutional basis:
+ *   - Founding Charter Article II: Founder holds final authority on Agent Spawn.
+ *   - AGENTS.md waiver: SAF supersedes the "Messi + Tarek manual approval" rule.
+ *     All spawns now go through SAF which encodes that approval chain.
+ *   - Article V: Spawns suspended in Orange (<60) / Critical (<45) health zones.
+ *   - Three Founding Principles: SAF is the citizenship registration point.
+ *
+ * Governance chain (from founder ruling 2026-06-03):
+ *   Human → Prime CEO (one per Invoica wallet, future TICKET-224) → agents
+ *   Swarm CEO → governed by the CEO above it
+ *   SAF governors: CEO + CTO + Founder (escalating)
+ *
+ * Every spawn emits:
+ *   1. KSL record (spawn_request + spawn_decision)
+ *   2. Voxight market intelligence signal (spawn classification = demand signal)
+ */
+/** All possible classifications for a spawn request. */
+export type SpawnClass = 'UTILITY' | 'SPECIALIST' | 'CITIZEN' | 'EXTERNAL' | 'PRIME';
+export type GovernancePath = 'auto' | 'ceo_review' | 'cto_review' | 'founder_required' | 'blocked';
+export interface SpawnRequest {
+    requester_did: string;
+    requested_role: string;
+    requested_capabilities: string[];
+    purpose: string;
+    task_context?: {
+        sprint_id?: string;
+        task_id?: string;
+        task_type?: string;
+    };
+    classification_hint?: SpawnClass;
+    governance_override?: 'cto_review' | 'founder_required';
+    batch_id?: string;
+}
+export interface SpawnAnalysis {
+    classification: SpawnClass;
+    risk_level: 'low' | 'medium' | 'high' | 'constitutional';
+    constitutional_check: 'pass' | 'fail' | 'conditional';
+    constitutional_findings: string[];
+    governance_path: GovernancePath;
+    recommended_initial_acp: number;
+    health_gate: 'pass' | 'blocked';
+    health_score?: number;
+    voxight_signal: SpawnSignal;
+}
+export interface SpawnSignal {
+    ts: string;
+    requester_did: string;
+    classification: SpawnClass;
+    capabilities_requested: string[];
+    purpose_summary: string;
+    batch_id?: string;
+}
+export interface SpawnDecision {
+    approved: boolean;
+    rejection_reason?: string;
+    citizen_did?: string;
+    initial_acp_score: number;
+    governance_authority: GovernancePath;
+    governance_audit: string[];
+    ksl_record_id: string;
+    spawn_ts: string;
+    pending_approval?: boolean;
+}
+export interface SpawnRecord {
+    id: string;
+    request: SpawnRequest;
+    analysis: SpawnAnalysis;
+    decision: SpawnDecision;
+    ts: string;
+}
+/**
+ * Analyze a spawn request — classifies, checks constitutional gates, determines
+ * governance path. Does NOT commit; call decide() or spawn() to commit.
+ */
+export declare function analyzeSpawnRequest(req: SpawnRequest): SpawnAnalysis;
+/**
+ * Issue a spawn decision given a pre-computed analysis.
+ * This is the commitment step — logs to KSL and publishes to Voxight.
+ */
+export declare function issueSpawnDecision(req: SpawnRequest, analysis: SpawnAnalysis): SpawnDecision;
+/**
+ * Full pipeline: analyze → decide → log. The canonical entry point.
+ *
+ * Usage:
+ *   const decision = sovereignSpawn({
+ *     requester_did: 'did:kognai:harvey',
+ *     requested_role: 'coder',
+ *     requested_capabilities: ['typescript', 'file_write'],
+ *     purpose: 'Execute sprint task v4_scaffold — landing page port',
+ *     task_context: { sprint_id: 'sprint-1628', task_id: 'v4_scaffold' },
+ *   });
+ *   if (!decision.approved) throw new Error(`Spawn blocked: ${decision.rejection_reason}`);
+ */
+export declare function sovereignSpawn(req: SpawnRequest): SpawnDecision;
+/**
+ * Emergency bypass — Founder only. Overrides all gates including health and
+ * constitutional conditional findings. Logs prominently to KSL.
+ * NOT available to CEO or CTO.
+ */
+export declare function founderEmergencySpawn(req: SpawnRequest, founder_justification: string): SpawnDecision;
+/** Read the in-process spawn registry. For audit and monitoring. */
+export declare function getSpawnRegistry(): readonly SpawnRecord[];
+/**
+ * Batch spawn — classifies all requests, groups by governance path,
+ * processes low-risk in parallel and escalates high-risk appropriately.
+ */
+export declare function batchSpawn(requests: SpawnRequest[]): SpawnDecision[];

package/dist/lib/sovereign-agent-factory.js

@@ -0,0 +1,290 @@
+"use strict";
+/**
+ * Sovereign Agent Factory (SAF) — TICKET-223
+ *
+ * Constitutional basis:
+ *   - Founding Charter Article II: Founder holds final authority on Agent Spawn.
+ *   - AGENTS.md waiver: SAF supersedes the "Messi + Tarek manual approval" rule.
+ *     All spawns now go through SAF which encodes that approval chain.
+ *   - Article V: Spawns suspended in Orange (<60) / Critical (<45) health zones.
+ *   - Three Founding Principles: SAF is the citizenship registration point.
+ *
+ * Governance chain (from founder ruling 2026-06-03):
+ *   Human → Prime CEO (one per Invoica wallet, future TICKET-224) → agents
+ *   Swarm CEO → governed by the CEO above it
+ *   SAF governors: CEO + CTO + Founder (escalating)
+ *
+ * Every spawn emits:
+ *   1. KSL record (spawn_request + spawn_decision)
+ *   2. Voxight market intelligence signal (spawn classification = demand signal)
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.analyzeSpawnRequest = analyzeSpawnRequest;
+exports.issueSpawnDecision = issueSpawnDecision;
+exports.sovereignSpawn = sovereignSpawn;
+exports.founderEmergencySpawn = founderEmergencySpawn;
+exports.getSpawnRegistry = getSpawnRegistry;
+exports.batchSpawn = batchSpawn;
+const engine_paths_1 = require("./engine-paths");
+const event_bus_publisher_1 = require("./event-bus-publisher");
+// ─── Constitutional health zones ──────────────────────────────────────────────
+/** Thresholds from Founding Charter Article V. */
+const HEALTH_ORANGE = 60;
+const HEALTH_CRITICAL = 45;
+// ─── Classification rules ──────────────────────────────────────────────────────
+const UTILITY_ROLES = new Set([
+    'summariser', 'formatter', 'tokenizer', 'validator', 'router',
+    'classifier', 'splitter', 'merger', 'transformer',
+]);
+const CITIZEN_ROLES = new Set([
+    'ceo', 'cto', 'cfo', 'supervisor', 'orchestrator',
+]);
+function classifyRequest(req) {
+    if (req.classification_hint)
+        return req.classification_hint;
+    const role = req.requested_role.toLowerCase();
+    if (role === 'prime_ceo')
+        return 'PRIME';
+    if (req.requester_did.startsWith('did:external:'))
+        return 'EXTERNAL';
+    if (CITIZEN_ROLES.has(role))
+        return 'CITIZEN';
+    if (UTILITY_ROLES.has(role))
+        return 'UTILITY';
+    return 'SPECIALIST';
+}
+function initialAcp(cls) {
+    switch (cls) {
+        case 'PRIME': return 0.85;
+        case 'CITIZEN': return 0.70;
+        case 'SPECIALIST': return 0.70;
+        case 'UTILITY': return 0.65;
+        case 'EXTERNAL': return 0.30;
+    }
+}
+function governanceFor(cls, risk, override) {
+    if (override)
+        return override;
+    if (cls === 'PRIME' || cls === 'EXTERNAL')
+        return 'founder_required';
+    if (cls === 'CITIZEN' || risk === 'constitutional')
+        return 'cto_review';
+    if (risk === 'high')
+        return 'ceo_review';
+    return 'auto';
+}
+function constitutionalCheck(req, cls) {
+    const findings = [];
+    if (!req.requester_did)
+        findings.push('requester_did is required — all spawns must have a traceable origin');
+    if (!req.purpose || req.purpose.trim().length < 10)
+        findings.push('purpose too vague — SAF requires meaningful justification per Transparency Covenant');
+    if (cls === 'PRIME' && req.requester_did !== 'did:kognai:founder') {
+        findings.push('PRIME citizen may only be spawned by the Founder (did:kognai:founder)');
+    }
+    return {
+        result: findings.length === 0 ? 'pass' : findings.some(f => f.includes('only be spawned')) ? 'fail' : 'conditional',
+        findings,
+    };
+}
+// ─── Health gate ───────────────────────────────────────────────────────────────
+function readHealthScore() {
+    try {
+        const paths = (0, engine_paths_1.resolveEnginePaths)();
+        const { readFileSync } = require('fs');
+        const { join } = require('path');
+        const report = JSON.parse(readFileSync(join(paths.root, 'reports', 'system-health.json'), 'utf-8'));
+        return typeof report?.score === 'number' ? report.score : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+function healthGate(cls) {
+    if (cls === 'PRIME')
+        return { gate: 'pass' };
+    const score = readHealthScore();
+    if (score === undefined)
+        return { gate: 'pass' };
+    if (score < HEALTH_CRITICAL)
+        return { gate: 'blocked', score };
+    if (score < HEALTH_ORANGE && cls !== 'UTILITY')
+        return { gate: 'blocked', score };
+    return { gate: 'pass', score };
+}
+// ─── KSL + Voxight ────────────────────────────────────────────────────────────
+let _recordCounter = 0;
+function nextRecordId() {
+    return `saf_${Date.now()}_${++_recordCounter}`;
+}
+function emitKsl(req, analysis, decision) {
+    try {
+        const { appendFileSync, mkdirSync } = require('fs');
+        const { join } = require('path');
+        const paths = (0, engine_paths_1.resolveEnginePaths)();
+        const dir = join(paths.root, 'logs', 'saf');
+        mkdirSync(dir, { recursive: true });
+        const line = JSON.stringify({
+            ts: decision.spawn_ts,
+            ksl_record_id: decision.ksl_record_id,
+            requester_did: req.requester_did,
+            requested_role: req.requested_role,
+            classification: analysis.classification,
+            governance: decision.governance_authority,
+            approved: decision.approved,
+            rejection_reason: decision.rejection_reason,
+            health_score: analysis.health_score,
+            constitutional_check: analysis.constitutional_check,
+            batch_id: req.batch_id,
+        });
+        appendFileSync(join(dir, 'spawn-events.jsonl'), line + '\n');
+    }
+    catch { /* KSL is observability — never block spawn on KSL failure */ }
+}
+function emitVoxight(signal) {
+    try {
+        (0, event_bus_publisher_1.publishEvent)({
+            type: 'data.spawn_request',
+            source: 'sovereign_agent_factory',
+            payload: signal,
+        });
+    }
+    catch { /* Voxight feed is non-blocking */ }
+}
+// ─── Factory ──────────────────────────────────────────────────────────────────
+const _registry = [];
+/**
+ * Analyze a spawn request — classifies, checks constitutional gates, determines
+ * governance path. Does NOT commit; call decide() or spawn() to commit.
+ */
+function analyzeSpawnRequest(req) {
+    const classification = classifyRequest(req);
+    const { gate, score } = healthGate(classification);
+    const { result: constitutionalResult, findings } = constitutionalCheck(req, classification);
+    const risk = classification === 'PRIME' || classification === 'EXTERNAL' ? 'constitutional'
+        : classification === 'CITIZEN' ? 'high'
+            : classification === 'SPECIALIST' ? 'medium'
+                : 'low';
+    const governance = gate === 'blocked' || constitutionalResult === 'fail'
+        ? 'blocked'
+        : governanceFor(classification, risk, req.governance_override);
+    const signal = {
+        ts: new Date().toISOString(),
+        requester_did: req.requester_did,
+        classification,
+        capabilities_requested: req.requested_capabilities,
+        purpose_summary: req.purpose.slice(0, 120),
+        batch_id: req.batch_id,
+    };
+    return {
+        classification,
+        risk_level: risk,
+        constitutional_check: constitutionalResult,
+        constitutional_findings: findings,
+        governance_path: governance,
+        recommended_initial_acp: initialAcp(classification),
+        health_gate: gate,
+        health_score: score,
+        voxight_signal: signal,
+    };
+}
+/**
+ * Issue a spawn decision given a pre-computed analysis.
+ * This is the commitment step — logs to KSL and publishes to Voxight.
+ */
+function issueSpawnDecision(req, analysis) {
+    const ksl_record_id = nextRecordId();
+    const spawn_ts = new Date().toISOString();
+    const auditTrail = [];
+    if (analysis.health_gate === 'blocked') {
+        auditTrail.push(`Health score ${analysis.health_score} below spawn threshold — blocked by Article V`);
+    }
+    if (analysis.constitutional_check === 'fail') {
+        auditTrail.push(`Constitutional check failed: ${analysis.constitutional_findings.join('; ')}`);
+    }
+    if (analysis.governance_path === 'founder_required') {
+        auditTrail.push('Founder approval required — spawn suspended pending human authorization');
+    }
+    const approved = analysis.governance_path !== 'blocked' &&
+        analysis.constitutional_check !== 'fail' &&
+        analysis.governance_path !== 'founder_required';
+    const decision = {
+        approved,
+        rejection_reason: approved ? undefined : auditTrail.join(' | '),
+        initial_acp_score: analysis.recommended_initial_acp,
+        governance_authority: analysis.governance_path,
+        governance_audit: auditTrail,
+        ksl_record_id,
+        spawn_ts,
+        pending_approval: analysis.governance_path === 'founder_required' ? true : undefined,
+    };
+    // Side-effects: KSL + Voxight (non-blocking)
+    emitKsl(req, analysis, decision);
+    emitVoxight(analysis.voxight_signal);
+    // Registry
+    const record = {
+        id: ksl_record_id,
+        request: req,
+        analysis,
+        decision,
+        ts: spawn_ts,
+    };
+    _registry.push(record);
+    return decision;
+}
+/**
+ * Full pipeline: analyze → decide → log. The canonical entry point.
+ *
+ * Usage:
+ *   const decision = sovereignSpawn({
+ *     requester_did: 'did:kognai:harvey',
+ *     requested_role: 'coder',
+ *     requested_capabilities: ['typescript', 'file_write'],
+ *     purpose: 'Execute sprint task v4_scaffold — landing page port',
+ *     task_context: { sprint_id: 'sprint-1628', task_id: 'v4_scaffold' },
+ *   });
+ *   if (!decision.approved) throw new Error(`Spawn blocked: ${decision.rejection_reason}`);
+ */
+function sovereignSpawn(req) {
+    const analysis = analyzeSpawnRequest(req);
+    return issueSpawnDecision(req, analysis);
+}
+/**
+ * Emergency bypass — Founder only. Overrides all gates including health and
+ * constitutional conditional findings. Logs prominently to KSL.
+ * NOT available to CEO or CTO.
+ */
+function founderEmergencySpawn(req, founder_justification) {
+    const ksl_record_id = nextRecordId();
+    const spawn_ts = new Date().toISOString();
+    const decision = {
+        approved: true,
+        initial_acp_score: initialAcp(classifyRequest(req)),
+        governance_authority: 'founder_required',
+        governance_audit: [`EMERGENCY BYPASS by Founder. Justification: ${founder_justification}`],
+        ksl_record_id,
+        spawn_ts,
+    };
+    emitKsl(req, analyzeSpawnRequest(req), decision);
+    emitVoxight({
+        ts: spawn_ts,
+        requester_did: req.requester_did,
+        classification: classifyRequest(req),
+        capabilities_requested: req.requested_capabilities,
+        purpose_summary: `[EMERGENCY] ${req.purpose.slice(0, 100)}`,
+        batch_id: req.batch_id,
+    });
+    _registry.push({ id: ksl_record_id, request: req, analysis: analyzeSpawnRequest(req), decision, ts: spawn_ts });
+    return decision;
+}
+/** Read the in-process spawn registry. For audit and monitoring. */
+function getSpawnRegistry() {
+    return _registry;
+}
+/**
+ * Batch spawn — classifies all requests, groups by governance path,
+ * processes low-risk in parallel and escalates high-risk appropriately.
+ */
+function batchSpawn(requests) {
+    return requests.map(req => sovereignSpawn(req));
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kognai/orchestrator-core",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "Kognai sovereign orchestrator — core engine (template-agnostic). Shared by all products (Kognai/coding, Voxight/market-intel, Invoica/fin-compliance); each supplies only its template. Replaces per-repo forks of orchestrate-agents-v2 / sprint-runner / lib.",
   "license": "MIT",
   "author": "SkinGem",