open-multi-agent-kit 0.78.1 → 0.78.2

package/dist/commands/goal-interview.js

@@ -0,0 +1,396 @@
+import { mkdir, writeFile, readFile, readdir } from "fs/promises";
+import { basename, join } from "path";
+import { getProjectRoot } from "../util/fs.js";
+import { style, header, status, label } from "../util/theme.js";
+import { NotFoundError, UsageError, emitError } from "../util/cli-contract.js";
+import { createGoalPersister } from "../goal/persistence.js";
+import { createGoalSpec, updateGoalStatus } from "../goal/intake.js";
+import { buildInterviewSession, ingestAnswers } from "../goal/interview-session.js";
+import { applyInterviewDelta } from "../goal/interview-assimilation.js";
+import { redactSecretText } from "../goal/intent-frame.js";
+import { readImageFile } from "../util/clipboard-image.js";
+const IMAGE_ATTACHMENT_QUESTION_ID = "q-image-attachment";
+function getGoalBasePath() {
+    return join(getProjectRoot(), ".omk", "goals");
+}
+function printAlphaWarning(json) {
+    if (json)
+        return;
+    if (!process.env.OMK_GOAL_ALPHA) {
+        console.log(style.orange("⚠️  Goal interview is alpha. Set OMK_GOAL_ALPHA=1 to suppress this warning."));
+    }
+}
+function parseDepth(value) {
+    if (!value)
+        return undefined;
+    if (value === "light" || value === "standard" || value === "deep")
+        return value;
+    throw new UsageError(`Invalid depth: ${value} (expected light | standard | deep)`);
+}
+function parseMode(value) {
+    if (!value || value === "create")
+        return "create";
+    if (value === "refine")
+        return "refine";
+    throw new UsageError(`Invalid mode: ${value} (expected create | refine)`);
+}
+async function loadAnswersFile(root, filePath) {
+    const abs = join(root, filePath);
+    let content;
+    try {
+        content = await readFile(abs, "utf-8");
+    }
+    catch {
+        throw new NotFoundError(`Answers file not found: ${filePath}`);
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(content);
+    }
+    catch {
+        throw new UsageError(`Answers file is not valid JSON: ${filePath}`);
+    }
+    const rows = Array.isArray(parsed)
+        ? parsed
+        : (parsed && typeof parsed === "object" && Array.isArray(parsed.answers)
+            ? parsed.answers
+            : null);
+    if (!rows) {
+        throw new UsageError(`Answers file must be an array or { "answers": [...] }: ${filePath}`);
+    }
+    const now = new Date().toISOString();
+    const answers = [];
+    for (const row of rows) {
+        if (!row || typeof row !== "object")
+            continue;
+        const r = row;
+        if (typeof r.questionId !== "string")
+            continue;
+        answers.push({
+            questionId: r.questionId,
+            answer: typeof r.answer === "string" ? r.answer : "",
+            answeredAt: typeof r.answeredAt === "string" ? r.answeredAt : now,
+            skipped: r.skipped === true ? true : undefined,
+        });
+    }
+    return answers;
+}
+function buildImageAttachment(imagePath) {
+    const img = readImageFile(imagePath);
+    if (!img.ok) {
+        throw new UsageError(img.error ?? `Unable to read image file: ${imagePath}`);
+    }
+    if (typeof img.dataUri !== "string" || typeof img.ext !== "string") {
+        throw new UsageError(`Image file could not be converted to a data URI: ${imagePath}`);
+    }
+    return {
+        name: basename(imagePath),
+        path: imagePath,
+        mimeType: `image/${img.ext}`,
+        dataUri: img.dataUri,
+        ext: img.ext,
+        source: "file",
+    };
+}
+function attachImageToSession(session, imagePath) {
+    const attachment = buildImageAttachment(imagePath);
+    const answeredAt = new Date().toISOString();
+    return {
+        ...session,
+        updatedAt: answeredAt,
+        answers: [
+            ...session.answers.filter((answer) => answer.questionId !== IMAGE_ATTACHMENT_QUESTION_ID),
+            {
+                questionId: IMAGE_ATTACHMENT_QUESTION_ID,
+                answer: `Image file: ${imagePath}`,
+                answeredAt,
+                skipped: false,
+            },
+        ],
+        findings: [
+            ...session.findings.filter((finding) => finding.sourceQuestionId !== IMAGE_ATTACHMENT_QUESTION_ID),
+            {
+                field: "attachments",
+                value: attachment,
+                sourceQuestionId: IMAGE_ATTACHMENT_QUESTION_ID,
+                confidence: 1,
+            },
+        ],
+    };
+}
+function renderQuestionsMarkdown(session) {
+    const lines = [
+        `# Interview Questions — ${session.sessionId}`,
+        "",
+        `**Mode:** ${session.mode}  |  **Depth:** ${session.depth}  |  **Ambiguity:** ${session.ambiguity}`,
+        "",
+        "| # | Score | Req | Target | Kind | Prompt |",
+        "|---|-------|-----|--------|------|--------|",
+    ];
+    session.questions.forEach((q, i) => {
+        const req = q.required ? "✓" : "";
+        lines.push(`| ${i + 1} | ${q.score} | ${req} | ${q.targetField} | ${q.kind} | ${q.prompt.replace(/\|/g, "\\|")} |`);
+    });
+    lines.push("");
+    return lines.join("\n");
+}
+function renderReportMarkdown(session) {
+    const c = session.completeness;
+    const lines = [
+        `# Interview Report — ${session.sessionId}`,
+        "",
+        `**Status:** ${session.status}  |  **Mode:** ${session.mode}  |  **Depth:** ${session.depth}`,
+        `**Ambiguity:** ${session.ambiguity}  |  **Completeness:** ${c.overall}`,
+        "",
+        "## Completeness by axis",
+        "",
+        `- objective: ${c.objective}`,
+        `- successCriteria: ${c.successCriteria}`,
+        `- evidence: ${c.evidence}`,
+        `- artifacts: ${c.artifacts}`,
+        `- constraints: ${c.constraints}`,
+        `- risks: ${c.risks}`,
+        `- authority: ${c.authority}`,
+        "",
+    ];
+    if (c.criticalMissing.length > 0) {
+        lines.push("## Critical missing fields", "", ...c.criticalMissing.map((m) => `- ${m}`), "");
+    }
+    if (c.contradictions.length > 0) {
+        lines.push("## Unresolved contradictions", "", ...c.contradictions.map((m) => `- ${m}`), "");
+    }
+    lines.push("## Answers", "");
+    if (session.answers.length === 0) {
+        lines.push("_No answers recorded yet._", "");
+    }
+    else {
+        for (const a of session.answers) {
+            if (a.skipped) {
+                lines.push(`- **${a.questionId}**: _(skipped)_`);
+            }
+            else {
+                lines.push(`- **${a.questionId}**: ${a.answer}`);
+            }
+        }
+        lines.push("");
+    }
+    lines.push("## Spec delta", "");
+    if (session.specDelta.changes.length === 0) {
+        lines.push("_No structured changes derived._", "");
+    }
+    else {
+        for (const ch of session.specDelta.changes) {
+            lines.push(`- \`${ch.op}\` **${String(ch.field)}** (conf ${ch.confidence}): ${JSON.stringify(ch.value)}`);
+        }
+        lines.push("");
+    }
+    return lines.join("\n");
+}
+async function writeSessionArtifacts(dir, session) {
+    await mkdir(dir, { recursive: true });
+    await writeFile(join(dir, "interview.json"), `${JSON.stringify(session, null, 2)}\n`);
+    await writeFile(join(dir, "spec-delta.json"), `${JSON.stringify(session.specDelta, null, 2)}\n`);
+    await writeFile(join(dir, "questions.md"), renderQuestionsMarkdown(session));
+    await writeFile(join(dir, "interview-report.md"), renderReportMarkdown(session));
+    const answersJsonl = session.answers.map((a) => JSON.stringify(a)).join("\n");
+    await writeFile(join(dir, "answers.jsonl"), answersJsonl.length > 0 ? `${answersJsonl}\n` : "");
+}
+function printSessionSummary(session, sessionDir) {
+    console.log(header("Goal Interview"));
+    console.log(label("Session", session.sessionId));
+    console.log(label("Mode", session.mode));
+    console.log(label("Depth", session.depth));
+    console.log(label("Ambiguity", String(session.ambiguity)));
+    console.log(label("Completeness", String(session.completeness.overall)));
+    console.log(label("Status", session.status));
+    console.log(label("Questions", String(session.questions.length)));
+    console.log(label("Answers", String(session.answers.length)));
+    if (session.completeness.criticalMissing.length > 0) {
+        console.log(label("Missing", session.completeness.criticalMissing.join(", ")));
+    }
+    if (session.completeness.contradictions.length > 0) {
+        console.log(style.pink(`Contradictions: ${session.completeness.contradictions.join("; ")}`));
+    }
+    console.log("");
+    if (session.answers.length === 0) {
+        console.log(style.purpleBold("Top questions"));
+        for (const q of session.questions.slice(0, 6)) {
+            const req = q.required ? style.pink("[required]") : style.gray("[optional]");
+            console.log(`  ${req} (${q.score}) ${q.prompt}`);
+        }
+        console.log("");
+        console.log(style.gray("Answer via: omk goal interview \"<prompt>\" --answers answers.json --write-spec"));
+    }
+    console.log(status.success(`interview.json → ${join(sessionDir, "interview.json")}`));
+}
+export async function goalInterviewCommand(input, options) {
+    printAlphaWarning(options.json);
+    const root = getProjectRoot();
+    const persister = createGoalPersister(getGoalBasePath());
+    const mode = parseMode(options.mode);
+    const depth = parseDepth(options.depth);
+    const maxQuestions = options.maxQuestions ? Number.parseInt(options.maxQuestions, 10) : undefined;
+    if (maxQuestions !== undefined && (!Number.isFinite(maxQuestions) || maxQuestions <= 0)) {
+        throw new UsageError(`Invalid --max-questions: ${options.maxQuestions}`);
+    }
+    // Resolve existing goal for refine mode or when --goal-id / id positional is given.
+    const goalIdHint = options.goalId ?? (mode === "refine" ? input : undefined);
+    let existingGoal = null;
+    if (goalIdHint) {
+        existingGoal = await persister.load(goalIdHint);
+        if (!existingGoal) {
+            const msg = `Goal not found: ${goalIdHint}`;
+            emitError(msg, Boolean(options.json));
+            throw new NotFoundError(msg);
+        }
+    }
+    const rawPrompt = existingGoal
+        ? (existingGoal.rawPrompt || existingGoal.objective || existingGoal.title)
+        : (input ?? "");
+    if (!rawPrompt.trim()) {
+        throw new UsageError("A raw goal prompt or an existing --goal-id is required.");
+    }
+    // Redact secrets from the prompt before it reaches the session, the GoalSpec,
+    // persisted artifacts, or --json output.
+    const safePrompt = redactSecretText(rawPrompt);
+    const seed = {
+        rawPrompt: safePrompt,
+        riskLevel: existingGoal?.riskLevel,
+        goal: existingGoal ?? undefined,
+    };
+    let session = buildInterviewSession({
+        seed,
+        mode: existingGoal ? "refine" : mode,
+        depth,
+        maxQuestions,
+        goalId: existingGoal?.goalId,
+    });
+    if (options.answers) {
+        const answers = await loadAnswersFile(root, options.answers);
+        session = ingestAnswers(session, seed, answers);
+    }
+    if (options.image) {
+        session = attachImageToSession(session, options.image);
+    }
+    // Optionally apply the delta to a GoalSpec.
+    let savedGoalId = existingGoal?.goalId;
+    if (options.writeSpec) {
+        let goal;
+        if (existingGoal) {
+            const result = applyInterviewDelta(existingGoal, session.specDelta);
+            goal = updateGoalStatus(result.goal, result.goal.status, { planRevision: result.goal.planRevision + 1 });
+        }
+        else {
+            const base = createGoalSpec(safePrompt);
+            goal = applyInterviewDelta(base, session.specDelta).goal;
+        }
+        await persister.save(goal);
+        await persister.appendHistory(goal.goalId, {
+            at: new Date().toISOString(),
+            action: existingGoal ? "interview-refine" : "interview-create",
+            detail: {
+                sessionId: session.sessionId,
+                ambiguity: session.ambiguity,
+                completeness: session.completeness.overall,
+                changes: session.specDelta.changes.length,
+            },
+        });
+        savedGoalId = goal.goalId;
+        session.goalId = goal.goalId;
+        session.specDelta.goalId = goal.goalId;
+    }
+    // Persist interview artifacts. With a goal id, store under the goal dir.
+    const sessionDir = savedGoalId
+        ? join(getGoalBasePath(), savedGoalId, "interviews", session.sessionId)
+        : join(root, ".omk", "interviews", session.sessionId);
+    await writeSessionArtifacts(sessionDir, session);
+    if (options.json) {
+        console.log(JSON.stringify(session, null, 2));
+        return;
+    }
+    printSessionSummary(session, sessionDir);
+    if (savedGoalId) {
+        console.log(status.success(`goal spec written → ${savedGoalId}`));
+        console.log(style.gray(`Next: omk goal plan ${savedGoalId}`));
+    }
+}
+async function findLatestInterviewSessionId(goalDir) {
+    const interviewsDir = join(goalDir, "interviews");
+    try {
+        const entries = await readdir(interviewsDir, { withFileTypes: true });
+        const dirs = entries.filter((e) => e.isDirectory()).map((e) => e.name).sort();
+        return dirs.length > 0 ? dirs[dirs.length - 1] : null;
+    }
+    catch {
+        return null;
+    }
+}
+export async function goalRefineCommand(goalId, options) {
+    printAlphaWarning(options.json);
+    const persister = createGoalPersister(getGoalBasePath());
+    const goal = await persister.load(goalId);
+    if (!goal) {
+        const msg = `Goal not found: ${goalId}`;
+        emitError(msg, Boolean(options.json));
+        throw new NotFoundError(msg);
+    }
+    const goalDir = join(getGoalBasePath(), goalId);
+    const from = options.fromInterview ?? "latest";
+    const sessionId = from === "latest" ? await findLatestInterviewSessionId(goalDir) : from;
+    if (!sessionId) {
+        const msg = `No interview session found for goal: ${goalId}. Run: omk goal interview ${goalId} --mode refine --answers answers.json`;
+        emitError(msg, Boolean(options.json));
+        throw new NotFoundError(msg);
+    }
+    const deltaPath = join(goalDir, "interviews", sessionId, "spec-delta.json");
+    let delta;
+    try {
+        delta = JSON.parse(await readFile(deltaPath, "utf-8"));
+    }
+    catch {
+        const msg = `Interview spec-delta not found: ${deltaPath}`;
+        emitError(msg, Boolean(options.json));
+        throw new NotFoundError(msg);
+    }
+    const result = applyInterviewDelta(goal, delta);
+    const refined = updateGoalStatus(result.goal, result.goal.status, { planRevision: result.goal.planRevision + 1 });
+    await persister.save(refined);
+    await persister.appendHistory(goalId, {
+        at: new Date().toISOString(),
+        action: "refine",
+        detail: {
+            sessionId,
+            applied: result.appliedChanges.length,
+            skipped: result.skippedChanges.length,
+            contradictions: result.contradictions.length,
+            planRevision: refined.planRevision,
+        },
+    });
+    if (options.plan) {
+        const { goalPlanCommand } = await import("./goal.js");
+        await goalPlanCommand(goalId, { json: options.json });
+        return;
+    }
+    if (options.json) {
+        console.log(JSON.stringify({
+            goalId,
+            sessionId,
+            applied: result.appliedChanges.length,
+            skipped: result.skippedChanges.length,
+            contradictions: result.contradictions,
+            planRevision: refined.planRevision,
+            status: refined.status,
+        }, null, 2));
+        return;
+    }
+    console.log(header("Goal Refined"));
+    console.log(label("ID", goalId));
+    console.log(label("From interview", sessionId));
+    console.log(label("Applied changes", String(result.appliedChanges.length)));
+    console.log(label("Skipped changes", String(result.skippedChanges.length)));
+    console.log(label("Plan revision", String(refined.planRevision)));
+    if (result.contradictions.length > 0) {
+        console.log(style.pink(`Contradictions: ${result.contradictions.join("; ")}`));
+    }
+    console.log(style.gray(`Next: omk goal plan ${goalId}`));
+}

package/dist/contracts/interview.d.ts

@@ -0,0 +1,106 @@
+import type { GoalSpec, RiskLevel } from "./goal.js";
+export declare const INTERVIEW_SCHEMA_VERSION: "omk.interview.v1";
+export declare const INTERVIEW_DELTA_SCHEMA_VERSION: "omk.interview-delta.v1";
+export type InterviewDepth = "light" | "standard" | "deep";
+export type InterviewMode = "create" | "refine";
+export type InterviewQuestionKind = "objective" | "success-criteria" | "artifact" | "constraint" | "non-goal" | "risk" | "authority" | "evidence" | "dependency" | "rollback";
+/**
+ * Field on GoalSpec (or a derived structure) that an answer is meant to fill.
+ * A question without a targetField is low quality and must be dropped.
+ */
+export type InterviewTargetField = "objective" | "successCriteria" | "expectedArtifacts" | "constraints" | "nonGoals" | "risks" | "riskLevel" | "intentFrame" | "actionAtoms";
+export interface InterviewQuestion {
+    id: string;
+    kind: InterviewQuestionKind;
+    prompt: string;
+    required: boolean;
+    targetField: InterviewTargetField;
+    /** 0..1 — how much answering reduces uncertainty about the goal. */
+    informationGain: number;
+    /** 0..1 — how much answering reduces execution risk. */
+    riskReduction: number;
+    /** 0..1 — how strongly the answer reshapes the execution DAG. */
+    dagImpact: number;
+    /** 0..1 — how strongly the answer strengthens evidence gates. */
+    evidenceImpact: number;
+    /** 0..1 — burden on the user (penalty). */
+    userCost: number;
+    /** Derived ranking score, 0..1, rounded to 2 decimals. */
+    score: number;
+}
+export interface InterviewAnswer {
+    questionId: string;
+    answer: string;
+    answeredAt: string;
+    skipped?: boolean;
+}
+export interface InterviewFinding {
+    field: InterviewTargetField | string;
+    value: unknown;
+    sourceQuestionId: string;
+    /** 0..1 confidence that this finding is correct and explicit. */
+    confidence: number;
+    /** True when this finding contradicts an existing explicit value. */
+    conflict?: boolean;
+}
+export interface InterviewCompleteness {
+    /** Weighted overall completeness, 0..1. */
+    overall: number;
+    objective: number;
+    successCriteria: number;
+    evidence: number;
+    artifacts: number;
+    constraints: number;
+    risks: number;
+    authority: number;
+    /** Required fields with no usable value yet. */
+    criticalMissing: string[];
+    /** Unresolved contradictions between answers and existing values. */
+    contradictions: string[];
+}
+export type InterviewDeltaField = keyof GoalSpec | "successCriteria" | "expectedArtifacts" | "riskLevel";
+export interface InterviewSpecChange {
+    field: InterviewDeltaField;
+    op: "add" | "replace" | "remove";
+    value: unknown;
+    sourceQuestionId: string;
+    /** 0..1 confidence used by the conflict resolver. */
+    confidence: number;
+}
+export interface InterviewSpecDelta {
+    schemaVersion: typeof INTERVIEW_DELTA_SCHEMA_VERSION;
+    goalId?: string;
+    changes: InterviewSpecChange[];
+}
+export type InterviewStatus = "open" | "complete" | "blocked";
+export interface InterviewSession {
+    schemaVersion: typeof INTERVIEW_SCHEMA_VERSION;
+    sessionId: string;
+    goalId?: string;
+    mode: InterviewMode;
+    depth: InterviewDepth;
+    createdAt: string;
+    updatedAt: string;
+    rawPrompt?: string;
+    /** Ambiguity score 0..1; higher means more interview is needed. */
+    ambiguity: number;
+    questions: InterviewQuestion[];
+    answers: InterviewAnswer[];
+    findings: InterviewFinding[];
+    completeness: InterviewCompleteness;
+    specDelta: InterviewSpecDelta;
+    status: InterviewStatus;
+}
+/** Inputs the question bank needs to derive candidate questions. */
+export interface InterviewSeed {
+    rawPrompt: string;
+    riskLevel?: RiskLevel;
+    goal?: GoalSpec;
+}
+/** Result of applying a spec delta to a GoalSpec. */
+export interface InterviewApplyResult {
+    goal: GoalSpec;
+    appliedChanges: InterviewSpecChange[];
+    skippedChanges: InterviewSpecChange[];
+    contradictions: string[];
+}

package/dist/contracts/interview.js

@@ -0,0 +1,9 @@
+// Contract: src/contracts/interview.ts
+// Owner: Contract Worker (Deep Interview phase 0)
+// OMK Deep Interview — uncertainty reducer for goal-driven agent runs.
+//
+// Read-only for downstream interview modules. These types are the shared
+// language for question banking, scoring, assimilation, session building,
+// and the `omk goal interview` / `omk goal refine` CLI commands.
+export const INTERVIEW_SCHEMA_VERSION = "omk.interview.v1";
+export const INTERVIEW_DELTA_SCHEMA_VERSION = "omk.interview-delta.v1";

package/dist/evidence/index.d.ts

@@ -13,3 +13,7 @@ export { decideRepair } from "../orchestration/repair-policy.js";
 export type { RepairContext } from "../orchestration/repair-policy.js";
 export type { DecisionTraceStore } from "./decision-trace.js";
 export { createDecisionTraceStore } from "./decision-trace.js";
+export type { ProofTrustMvpEngine, ProofTrustResult } from "./proof-trust.js";
+export { createProofTrustMvpEngine } from "./proof-trust.js";
+export type { AlgorithmSpec, ReleaseCandidate, RegressionProofMatrixResult, RegressionProofMatrixEngine, RegressionProofMatrixOptions, } from "./regression-proof-matrix.js";
+export { createRegressionProofMatrixEngine } from "./regression-proof-matrix.js";

package/dist/evidence/index.js

@@ -5,3 +5,5 @@ export { createDiagnosisEngine } from "./diagnosis.js";
 export { createRunTraceStore } from "./run-trace.js";
 export { decideRepair } from "../orchestration/repair-policy.js";
 export { createDecisionTraceStore } from "./decision-trace.js";
+export { createProofTrustMvpEngine } from "./proof-trust.js";
+export { createRegressionProofMatrixEngine } from "./regression-proof-matrix.js";

package/dist/evidence/proof-trust-cli.d.ts

@@ -0,0 +1,8 @@
+#!/usr/bin/env node
+/**
+ * Proof Trust CLI — thin wrapper around ProofTrustMvpEngine.
+ *
+ * Usage:
+ *   node dist/evidence/proof-trust-cli.js <runDir> <bundlePath>
+ */
+export {};

package/dist/evidence/proof-trust-cli.js

@@ -0,0 +1,27 @@
+#!/usr/bin/env node
+/**
+ * Proof Trust CLI — thin wrapper around ProofTrustMvpEngine.
+ *
+ * Usage:
+ *   node dist/evidence/proof-trust-cli.js <runDir> <bundlePath>
+ */
+import { readFile } from "node:fs/promises";
+import { createProofTrustMvpEngine } from "./proof-trust.js";
+async function main() {
+    const args = process.argv.slice(2);
+    const runDir = args[0] ?? ".omk/runs";
+    const bundlePath = args[1];
+    if (!bundlePath) {
+        console.error("Usage: proof-trust-cli <runDir> <bundlePath>");
+        process.exit(1);
+    }
+    const bundle = JSON.parse(await readFile(bundlePath, "utf8"));
+    const engine = createProofTrustMvpEngine();
+    const result = await engine.evaluate(runDir, bundle);
+    console.log(JSON.stringify(result, null, 2));
+    process.exit(result.missingFields.length > 0 ? 1 : 0);
+}
+main().catch((err) => {
+    console.error(err);
+    process.exit(1);
+});

package/dist/evidence/proof-trust.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Proof Trust MVP — Algorithm 3
+ *
+ * Evaluates a proof bundle against a run directory, computing a trust score
+ * based on weighted field presence and validity.
+ */
+export interface ProofTrustMvpEngine {
+    evaluate(runDir: string, bundle: unknown): Promise<ProofTrustResult>;
+}
+export interface ProofTrustResult {
+    readonly trustScore: number;
+    readonly missingFields: readonly string[];
+}
+export declare function createProofTrustMvpEngine(schemas?: Readonly<Record<string, unknown>>): ProofTrustMvpEngine;