@kognai/orchestrator-core 0.1.0 → 0.1.1

package/dist/index.d.ts

@@ -59,5 +59,6 @@ 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 { 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/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.1",
   "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",