@kognai/orchestrator-core 0.1.0

package/dist/lib/plumber/types.d.ts

@@ -0,0 +1,78 @@
+/**
+ * Plumber — data contracts (TICKET-216, observer half).
+ *
+ * The Plumber is the engine's self-healing OBSERVABILITY layer (Layer 4 Health /
+ * Layer 7 Plumber). This module defines the contracts for the READ-MOSTLY observer:
+ * it consumes KSL records, judges them against SOP/position conformance, and routes
+ * observations to sinks (failure substrate, skill-candidate queue, plumber.alert).
+ *
+ * IMPORTANT — the observer NEVER writes code. It only produces observations and
+ * writes to logs/queues/events. The autonomous fixer is a separate, gated ticket.
+ *
+ * Position-Map context (TICKET-153) is a first-class input: conformance is judged
+ * RELATIVE to the agent's Kognai-architectural position, and failures are weighted
+ * by the impacted wedge dimension (sovereignty / security / intelligence / memory).
+ *
+ * Zero-dep: stdlib + in-core KSL types only.
+ */
+import type { KSLRecord } from '../ksl/record-writer';
+export type SovereigntyTier = 1 | 2 | 3 | 4;
+export type OptimizationProfile = 'security-first' | 'compliance-first' | 'performance-first' | 'sovereignty-first' | 'default' | (string & {});
+/**
+ * What an agent knows about its place in Kognai when it does work. All fields are
+ * optional so the observer degrades gracefully when the map is absent (pre-AIAX-v0.2);
+ * cut over to the canonical AIAX v0.2 map schema when it lands.
+ */
+export interface PositionMapContext {
+    layer?: string;
+    sovereigntyTier?: SovereigntyTier;
+    securityBlastRadius?: 'leaf' | 'moderate' | 'high';
+    intelligenceSink?: 'evidence' | 'simulation' | 'none';
+    memoryImpact?: 'low' | 'medium' | 'high';
+    role?: 'executor' | 'supervisor' | 'decomposer' | 'ceo' | 'cto' | 'reviewer' | (string & {});
+    optimizationProfile?: OptimizationProfile;
+    mandate?: {
+        costEnvelopeUsd?: number;
+    };
+    namespace?: 'production' | 'simulation';
+}
+export type ConformanceSeverity = 'info' | 'warn' | 'high';
+/** The four wedge dimensions a failure can touch (for TICKET-152 weighting). */
+export type PositionDimension = 'sovereignty' | 'security' | 'intelligence' | 'memory' | 'none';
+export interface ConformanceResult {
+    checkId: string;
+    ok: boolean;
+    severity: ConformanceSeverity;
+    message: string;
+    dimension?: PositionDimension;
+    positionRelative?: boolean;
+}
+export type ObservationVerdict = 'conformant' | 'success_pattern' | 'failure' | 'anomaly';
+export type PlumberFailureType = 'sop_nonconformance' | 'position_map_violation' | 'execution_error' | 'signal_mismatch';
+export interface ObservationRef {
+    run_id: string;
+    sprint_id: string;
+    task_id: string;
+    attempt: number;
+    agent: string;
+}
+export interface PlumberObservation {
+    ref: ObservationRef;
+    verdict: ObservationVerdict;
+    conformance: ConformanceResult[];
+    failureType?: PlumberFailureType;
+    dimension?: PositionDimension;
+    severity: ConformanceSeverity;
+    signal_strength: 'low' | 'medium' | 'high';
+    summary: string;
+    observed_at: string;
+}
+export interface PlumberSinks {
+    /** A real failure (high-severity non-conformance, position-map violation, or execution error). */
+    onFailure(obs: PlumberObservation, record: KSLRecord, ctx?: PositionMapContext): void | Promise<void>;
+    /** A high-signal clean attempt worth crystallising into a skill. */
+    onSkillCandidate(obs: PlumberObservation, record: KSLRecord, ctx?: PositionMapContext): void | Promise<void>;
+    /** A warning-level anomaly worth a plumber.alert but not a failure. */
+    onAlert(obs: PlumberObservation, record: KSLRecord, ctx?: PositionMapContext): void | Promise<void>;
+}
+export declare function refOf(record: KSLRecord): ObservationRef;

package/dist/lib/plumber/types.js

@@ -0,0 +1,29 @@
+"use strict";
+/**
+ * Plumber — data contracts (TICKET-216, observer half).
+ *
+ * The Plumber is the engine's self-healing OBSERVABILITY layer (Layer 4 Health /
+ * Layer 7 Plumber). This module defines the contracts for the READ-MOSTLY observer:
+ * it consumes KSL records, judges them against SOP/position conformance, and routes
+ * observations to sinks (failure substrate, skill-candidate queue, plumber.alert).
+ *
+ * IMPORTANT — the observer NEVER writes code. It only produces observations and
+ * writes to logs/queues/events. The autonomous fixer is a separate, gated ticket.
+ *
+ * Position-Map context (TICKET-153) is a first-class input: conformance is judged
+ * RELATIVE to the agent's Kognai-architectural position, and failures are weighted
+ * by the impacted wedge dimension (sovereignty / security / intelligence / memory).
+ *
+ * Zero-dep: stdlib + in-core KSL types only.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.refOf = refOf;
+function refOf(record) {
+    return {
+        run_id: record.run_id,
+        sprint_id: record.sprint_id,
+        task_id: record.task_id,
+        attempt: record.attempt,
+        agent: record.agent,
+    };
+}

package/dist/lib/research-impl-gate.d.ts

@@ -0,0 +1,16 @@
+/**
+ * research-impl-gate.ts — Sprint TICKET-005-RULE2
+ * Rule 2 (Research/Implementation Separation): blocks implementation sprints
+ * from executing until their paired research sprint is marked done.
+ */
+import type { SprintProposal } from './cto-gate-types';
+export interface ResearchGateResult {
+    allowed: boolean;
+    reason: string;
+}
+/**
+ * Check whether an implementation sprint's research prerequisite is done.
+ * Returns allowed:true for non-implementation sprints or sprints without
+ * a research_sprint_id.
+ */
+export declare function checkResearchGate(sprint: SprintProposal, projectRoot: string): ResearchGateResult;

package/dist/lib/research-impl-gate.js

@@ -0,0 +1,105 @@
+"use strict";
+/**
+ * research-impl-gate.ts — Sprint TICKET-005-RULE2
+ * Rule 2 (Research/Implementation Separation): blocks implementation sprints
+ * from executing until their paired research sprint is marked done.
+ */
+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 __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.checkResearchGate = checkResearchGate;
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+/**
+ * Check whether an implementation sprint's research prerequisite is done.
+ * Returns allowed:true for non-implementation sprints or sprints without
+ * a research_sprint_id.
+ */
+function checkResearchGate(sprint, projectRoot) {
+    if (sprint.phase !== 'implementation') {
+        return { allowed: true, reason: 'Not an implementation sprint — no gate required.' };
+    }
+    if (!sprint.research_sprint_id) {
+        return { allowed: true, reason: 'Implementation sprint has no research_sprint_id — gate skipped.' };
+    }
+    const researchId = sprint.research_sprint_id;
+    // Check sprint-queue.json first (authoritative status)
+    // Try both the raw ID and without the 'sprint-' prefix
+    const queueIds = [researchId, researchId.replace(/^sprint-/, '')];
+    const queueFile = path.join(projectRoot, 'workspace', 'sprint-queue.json');
+    if (fs.existsSync(queueFile)) {
+        try {
+            const q = JSON.parse(fs.readFileSync(queueFile, 'utf-8'));
+            const items = q.queue || q;
+            const match = items.find((i) => queueIds.includes(i.sprint_id || i.sprint || i.id || ''));
+            if (match) {
+                if (match.status === 'done') {
+                    return { allowed: true, reason: `Research sprint ${researchId} is done (queue).` };
+                }
+                return {
+                    allowed: false,
+                    reason: `Research sprint ${researchId} not done in queue (status: ${match.status || 'unknown'}).`,
+                };
+            }
+        }
+        catch { /* fall through */ }
+    }
+    // Fall back to workspace/sprints/{id}.json
+    const sprintFile = path.join(projectRoot, 'workspace', 'sprints', `${researchId}.json`);
+    if (fs.existsSync(sprintFile)) {
+        try {
+            const data = JSON.parse(fs.readFileSync(sprintFile, 'utf-8'));
+            if (data.status === 'done') {
+                return { allowed: true, reason: `Research sprint ${researchId} is done.` };
+            }
+            if (data.status) {
+                return {
+                    allowed: false,
+                    reason: `Research sprint ${researchId} not done (status: ${data.status}).`,
+                };
+            }
+            // File exists but has no status — treat as not done
+            return {
+                allowed: false,
+                reason: `Research sprint ${researchId} has no status field — treating as not done.`,
+            };
+        }
+        catch { /* fall through */ }
+    }
+    // Research sprint not found anywhere — block by default
+    return {
+        allowed: false,
+        reason: `Research sprint ${researchId} not found in sprints/ or sprint-queue.json.`,
+    };
+}

package/dist/lib/sherlock-memory.d.ts

@@ -0,0 +1,29 @@
+/**
+ * sherlock-memory.ts — Sherlock v2 ASMR Memory Context (AMD-21-03)
+ *
+ * Wraps retrieveRelevantMemories() from asmr-retrieval.ts and formats
+ * the top-N relevant episodic entries into a markdown context block
+ * for injection into the Sherlock (supervisor) agent's review prompt.
+ *
+ * Replaces full MEMORY.md polling with query-driven six-vector retrieval.
+ * Routing: nomic-embed-text LOCAL — zero cloud cost (asmr-retrieval.ts).
+ * Fail-open: any error returns '' — never blocks the supervisor pipeline.
+ *
+ * FP-007: < 200 lines
+ */
+/**
+ * Retrieve and format relevant episodic memory context for a Sherlock review.
+ *
+ * Uses the ASMR six-vector retrieval engine (nomic-embed-text local embeddings,
+ * cosine similarity ranking) to find the most semantically relevant prior sprint
+ * outcomes for the given task query.
+ *
+ * Returns a formatted markdown block ready for injection into the supervisor
+ * review prompt, or an empty string if retrieval yields nothing or fails.
+ *
+ * Fail-open: errors are silently absorbed — never blocks a review pipeline.
+ *
+ * @param query  Task context string or task ID to drive retrieval
+ * @returns      Formatted markdown memory block, or '' if unavailable
+ */
+export declare function getSherlockMemoryContext(query: string): Promise<string>;

package/dist/lib/sherlock-memory.js

@@ -0,0 +1,105 @@
+"use strict";
+/**
+ * sherlock-memory.ts — Sherlock v2 ASMR Memory Context (AMD-21-03)
+ *
+ * Wraps retrieveRelevantMemories() from asmr-retrieval.ts and formats
+ * the top-N relevant episodic entries into a markdown context block
+ * for injection into the Sherlock (supervisor) agent's review prompt.
+ *
+ * Replaces full MEMORY.md polling with query-driven six-vector retrieval.
+ * Routing: nomic-embed-text LOCAL — zero cloud cost (asmr-retrieval.ts).
+ * Fail-open: any error returns '' — never blocks the supervisor pipeline.
+ *
+ * FP-007: < 200 lines
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getSherlockMemoryContext = getSherlockMemoryContext;
+const asmr_retrieval_1 = require("./asmr-retrieval");
+// AMD-21 P3 (Sprint 1537): three-tier retrieval pipeline. Default ON; set to
+// '0' to fall back to the legacy single-tier nomic-embed retrieval.
+const USE_THREE_TIER = process.env['SHERLOCK_USE_THREE_TIER'] !== '0';
+const SHERLOCK_AGENT_ID = 'sherlock';
+// ── Config ────────────────────────────────────────────────────────────────────
+/** Number of top-ranked ASMR entries to inject into the supervisor context */
+const MEMORY_LIMIT = 5;
+/** Minimum character length for a query to be worth retrieving against */
+const MIN_QUERY_LEN = 10;
+/** Maximum characters of actionSummary to show per entry */
+const SUMMARY_MAX_CHARS = 120;
+// ── Formatters ────────────────────────────────────────────────────────────────
+/**
+ * Format a single ASMR entry as a compact markdown row.
+ * Shows: rank, sprint/agent attribution, topic, intent, stance, summary.
+ */
+function formatEntry(entry, rank) {
+    const { topic, intent, stance, emotion } = entry.vectors;
+    const agent = entry.agentId || 'unknown';
+    const sprint = entry.sprintId || '?';
+    const summary = (entry.actionSummary || '').substring(0, SUMMARY_MAX_CHARS);
+    const emotionTag = emotion ? ` [${emotion}]` : '';
+    return (`${rank}. **[${sprint} / ${agent}]**${emotionTag}\n` +
+        `   Topic: ${topic} — Intent: ${intent} (${stance})\n` +
+        `   ${summary}`);
+}
+/**
+ * Wrap the ranked entries in a labelled markdown context block.
+ * Returns empty string if no entries are available.
+ */
+function formatMemoryBlock(entries) {
+    if (entries.length === 0)
+        return '';
+    const rows = entries.map((e, i) => formatEntry(e, i + 1));
+    return ('\n\n## Relevant Episodic Memory (Sherlock v2 / ASMR)\n' +
+        '_Top prior outcomes ranked by semantic similarity — use as pattern context only._\n\n' +
+        rows.join('\n\n'));
+}
+// ── Public API ────────────────────────────────────────────────────────────────
+/**
+ * Retrieve and format relevant episodic memory context for a Sherlock review.
+ *
+ * Uses the ASMR six-vector retrieval engine (nomic-embed-text local embeddings,
+ * cosine similarity ranking) to find the most semantically relevant prior sprint
+ * outcomes for the given task query.
+ *
+ * Returns a formatted markdown block ready for injection into the supervisor
+ * review prompt, or an empty string if retrieval yields nothing or fails.
+ *
+ * Fail-open: errors are silently absorbed — never blocks a review pipeline.
+ *
+ * @param query  Task context string or task ID to drive retrieval
+ * @returns      Formatted markdown memory block, or '' if unavailable
+ */
+async function getSherlockMemoryContext(query) {
+    if (!query || query.trim().length < MIN_QUERY_LEN)
+        return '';
+    try {
+        if (USE_THREE_TIER) {
+            const r = await (0, asmr_retrieval_1.retrieveThreeTier)(query, SHERLOCK_AGENT_ID, { maxResults: MEMORY_LIMIT });
+            // Log the per-tier breakdown so we can observe behaviour after rollout.
+            // stderr to stay out of stdout-piped consumers.
+            process.stderr.write(`[sherlock-memory] three-tier hits — hot=${r.hot.length} warm=${r.warm.length} ` +
+                `cold=${r.cold.length} merged=${r.merged.length} ` +
+                `lat(ms)=${r.latency_ms.total} (h=${r.latency_ms.hot} w=${r.latency_ms.warm} c=${r.latency_ms.cold})\n`);
+            return formatThreeTierBlock(r.merged);
+        }
+        const entries = await (0, asmr_retrieval_1.retrieveRelevantMemories)(query, MEMORY_LIMIT);
+        return formatMemoryBlock(entries);
+    }
+    catch {
+        // Non-blocking — ASMR retrieval failure must never stop a supervisor review
+        return '';
+    }
+}
+/** Render three-tier MemoryHit list using the existing markdown shape. */
+function formatThreeTierBlock(merged) {
+    if (merged.length === 0)
+        return '';
+    const rows = merged.map((h, i) => {
+        const summary = h.content.substring(0, SUMMARY_MAX_CHARS);
+        const tier = h.source.toUpperCase();
+        return `${i + 1}. **[${tier}]** _(score ${h.score.toFixed(2)})_\n   ${summary}`;
+    });
+    return ('\n\n## Relevant Episodic Memory (Sherlock v2 / ASMR three-tier)\n' +
+        '_Hot in-memory turns + warm BrainX vectors + cold archive scan, ranked by score._\n\n' +
+        rows.join('\n\n'));
+}

package/dist/lib/skill-crystalliser.d.ts

@@ -0,0 +1,44 @@
+export interface SkillScoreEntry {
+    sprint_id: string;
+    task_id: string;
+    score: number;
+    reviewed_at: string;
+}
+export interface SkillRecord {
+    skill_id: string;
+    type: 'kognai-owned' | 'user-uploaded';
+    name: string;
+    description: string;
+    definition: {
+        approach: string;
+        key_patterns: string[];
+        anti_patterns: string[];
+    };
+    optimal_settings: {
+        model: string;
+        task_target: 'local' | 'cloud-code';
+        max_attempts: number;
+    };
+    score_history: SkillScoreEntry[];
+    execution_count: number;
+    access_tier: 'internal' | 'free' | 'rental' | 'sale';
+    source_sprint: string;
+    source_task: string;
+    agent_id: string;
+    created_at: string;
+    updated_at: string;
+}
+export interface CrystalliseParams {
+    agentId: string;
+    taskId: string;
+    sprintId: string;
+    taskTitle: string;
+    taskType: string;
+    model: string;
+    taskTarget: 'local' | 'cloud-code';
+    score: number;
+    approachSummary: string;
+    keyPatterns: string[];
+    antiPatterns: string[];
+}
+export declare function crystalliseSkill(params: CrystalliseParams): SkillRecord | null;

package/dist/lib/skill-crystalliser.js

@@ -0,0 +1,60 @@
+"use strict";
+// AMD-02 SKILL BANK — P0-SKILL2 — Skill crystallisation pipeline
+// Called after each APPROVED task to distil execution into a reusable skill record
+// Phase 1: write to skill-bank/kognai-owned/. Phase 3: expose via marketplace.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.crystalliseSkill = crystalliseSkill;
+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 SKILL_BANK_DIR = (0, path_1.join)(ROOT, 'skill-bank/kognai-owned');
+function crystalliseSkill(params) {
+    if (params.score < 75)
+        return null; // Only crystallise high-quality executions
+    const slug = params.taskTitle
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, '-')
+        .replace(/^-|-$/g, '')
+        .substring(0, 40);
+    const skill_id = `${params.agentId}-${params.sprintId}-${slug}`;
+    const now = new Date().toISOString();
+    const skillPath = (0, path_1.join)(SKILL_BANK_DIR, `${skill_id}.json`);
+    // If skill already exists, append score to history and update
+    if ((0, fs_1.existsSync)(skillPath)) {
+        const existing = JSON.parse((0, fs_1.readFileSync)(skillPath, 'utf-8'));
+        existing.score_history.push({ sprint_id: params.sprintId, task_id: params.taskId, score: params.score, reviewed_at: now });
+        existing.execution_count += 1;
+        existing.updated_at = now;
+        (0, fs_1.writeFileSync)(skillPath, JSON.stringify(existing, null, 2), 'utf-8');
+        return existing;
+    }
+    const record = {
+        skill_id,
+        type: 'kognai-owned',
+        name: params.taskTitle.substring(0, 60),
+        description: params.approachSummary.substring(0, 200),
+        definition: {
+            approach: params.approachSummary,
+            key_patterns: params.keyPatterns.slice(0, 5),
+            anti_patterns: params.antiPatterns.slice(0, 3),
+        },
+        optimal_settings: {
+            model: params.model,
+            task_target: params.taskTarget,
+            max_attempts: 3,
+        },
+        score_history: [{ sprint_id: params.sprintId, task_id: params.taskId, score: params.score, reviewed_at: now }],
+        execution_count: 1,
+        access_tier: 'internal',
+        source_sprint: params.sprintId,
+        source_task: params.taskId,
+        agent_id: params.agentId,
+        created_at: now,
+        updated_at: now,
+    };
+    if (!(0, fs_1.existsSync)(SKILL_BANK_DIR))
+        (0, fs_1.mkdirSync)(SKILL_BANK_DIR, { recursive: true });
+    (0, fs_1.writeFileSync)(skillPath, JSON.stringify(record, null, 2), 'utf-8');
+    return record;
+}

package/dist/lib/sprint-runner-engine.d.ts

@@ -0,0 +1,27 @@
+/**
+ * sprint-runner.ts — Auto-executes pending sprint tasks via dual-supervisor orchestrator
+ *
+ * PM2 cron: every 30 minutes — checks for pending work and runs it
+ *
+ * Flow:
+ *   1. Check lock file (prevents parallel sprints)
+ *   2. Scan sprints/ for JSON files with pending tasks
+ *      Priority: week-N.json descending (newest sprint first)
+ *   3. Read sprint JSON, inject sprint_id into each task
+ *   4. Write modified sprint to logs/sprint-runner-active.json
+ *   5. Spawn orchestrate-agents-v2.ts on the temp ACTIVE file
+ *      (Dual supervisor: Claude Sonnet + OpenAI Codex, CEO conflict resolution)
+ *   6. Telegram alert on start + finish
+ *   7. Release lock when done
+ *
+ * GitHub Issues → Sprint Tasks:
+ *   CEO creates GitHub issues as directives. To execute them, they must be
+ *   converted into a sprint JSON file (sprints/week-N.json) first.
+ *   The CEO bot or a human writes the sprint JSON; this runner executes it.
+ */
+export interface SprintRunnerOpts {
+    orchestratorScript: string;
+    postSprintHook?: () => void;
+}
+declare function runSprintCycle(opts: SprintRunnerOpts): Promise<void>;
+export { runSprintCycle };