open-multi-agent-kit 0.78.1 → 0.78.2

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # Changelog
 
+## Unreleased — Deep Interview + Clipboard Image Paste
+
+### Added
+
+- `omk goal interview [input]` and `omk goal refine <goal-id>` commands under the existing `goal` group, adding an evidence-driven clarification step before planning.
+- Deterministic deep interview that scores goal ambiguity (`0..1`), ranks targeted questions (`informationGain*0.35 + riskReduction*0.25 + dagImpact*0.20 + evidenceImpact*0.15 - userCost*0.05`), and computes a completeness score from assimilated answers.
+- Spec-delta assimilation that folds interview answers into a structured `GoalSpec` with conflict resolution, selectable depth (`light|standard|deep`, auto-selected by ambiguity when omitted), and `--write-spec` persistence.
+- `omk.interview.v1` JSON contract (`schemas/omk.interview.v1.schema.json`) plus the `omk.interview-delta.v1` spec-delta envelope.
+- Per-session interview artifacts (`interview.json`, `spec-delta.json`, `questions.md`, `answers.jsonl`, `interview-report.md`) under `.omk/goals/<goalId>/interviews/<sessionId>/` (or `.omk/interviews/<sessionId>/` before `--write-spec`).
+- GitHub organic growth kit: README first-screen positioning, runnable awesome-list examples, a 1280x640 social preview upload candidate, and reusable Topics/About/awesome-list PR copy in `docs/github-organic-promotion.md`.
+- Clipboard image paste support: `/paste` slash command in chat REPL, `--image` flag on `omk goal interview`, cross-platform clipboard reader (macOS/Linux/Windows), `InputAttachment` type for multimodal image handling.
+
 ## v0.78.1 — package alignment, JSON contract envelopes, and adaptive runtime algorithms (2026-06-07)
 
 ### Overview

package/MATURITY.md

@@ -63,6 +63,10 @@ Current source version: v0.78.1 (`v1.2` runtime contract family)
 | `omk research` | Core runtime web research wrapper; depends on Kimi tool availability. |
 | `omk open-design-agent` | Local Open Design CLI bridge. |
 
+## Regression Proof Matrix Claim Boundary
+
+Regression Proof Matrix is a release-defense gate, not a stable-release claim. Stable promotion still requires full `npm test`, live provider maturity data, and a minimal verified demo pass.
+
 ## Automation Contract Status
 
 | Area | Current state | Next hardening |

package/README.md

@@ -23,6 +23,7 @@
 <p align="center">
   <a href="#install">Install</a> ·
   <a href="#quick-start">Quick start</a> ·
+  <a href="#who-is-this-for">Who is this for?</a> ·
   <a href="#current-runtime-algorithm">Runtime algorithm</a> ·
   <a href="docs/getting-started.md">Docs</a> ·
   <a href="readmeasset/ASSET_INDEX.md">Visual assets</a>
@@ -30,6 +31,14 @@
 
 `OMK` (`omk`) turns a coding goal into a bounded, evidence-gated agent run.
 
+Use OMK when one coding agent is not enough: route Codex, OpenCode, Kimi, DeepSeek, Qwen, OpenRouter, and local runtimes through one evidence-gated control loop.
+
+## Who is this for?
+
+- Developers running multiple coding agents from the terminal.
+- Teams that need MCP-scoped agent execution instead of unrestricted tool access.
+- Agent builders who want routing, fallback, evidence gates, telemetry, and replay.
+
 > Current package source target: `open-multi-agent-kit@0.78.1`.
 > Public package name: `open-multi-agent-kit` (`@omk/cli` is not the active npm package).
 > Runtime contract family: `v1.2` (contract family, not a stable npm `1.x` release).
@@ -38,7 +47,7 @@
 
 ## Quickstart (3 minutes)
 
-A beginner reads this, runs four commands, and succeeds.
+A beginner reads this, runs four commands, and reaches an initialized OMK chat/doctor flow.
 
 ```bash
 npm i -g open-multi-agent-kit
@@ -47,6 +56,11 @@ omk doctor
 omk chat
 ```
 
+## Examples for agent tooling lists
+
+- [Codex MCP evidence run](https://github.com/dmae97/open-multi-agent-kit/tree/main/examples/codex-mcp-evidence-run): project-scoped MCP setup plus evidence-gated DAG dry run.
+- [Provider fallback](https://github.com/dmae97/open-multi-agent-kit/tree/main/examples/provider-fallback): `--provider auto` routing with parallel worker planning.
+
 ## Current release reality
 
 - The public npm line is `open-multi-agent-kit@0.78.x`. Published npm `latest` is `0.78.0`;
@@ -58,6 +72,8 @@ omk chat
   lanes are scoped by the provider-maturity contract.
 - Safety and evidence claims apply to the exact adapter, command, and verification gate that
   produced them.
+- Regression Proof Matrix is a release-defense coverage gate, not a stable-release claim.
+  Stable promotion still requires full tests, live provider maturity data, and a minimal verified demo pass.
 
 ## Why OMK
 
@@ -192,6 +208,59 @@ Kimi worker prompts use stdin with `--input-format text` where that adapter path
 Goal → DAG plan → parallel lanes → evidence bundle → verify gate → merge / replay / inspect
 ```
 
+## Goal lifecycle
+
+`omk goal` turns a raw goal into a planned, evidence-gated run. The **OMK Deep Interview** is an uncertainty reducer that clarifies the goal before planning, so the DAG is compiled from a structured spec instead of a vague prompt.
+
+Recommended flow:
+
+```bash
+omk goal interview "<raw goal>" --depth deep --write-spec
+omk goal plan <goal-id>
+omk goal run <goal-id> --provider auto --approval-policy interactive
+omk goal verify <goal-id>
+```
+
+### `omk goal interview [input]`
+
+Runs a deterministic deep interview that scores goal ambiguity (`0..1`), ranks targeted questions, assimilates answers into a structured spec delta, computes a completeness score, and (with `--write-spec`) creates or updates a `GoalSpec`. Question ranking is deterministic:
+
+```text
+score = informationGain*0.35 + riskReduction*0.25 + dagImpact*0.20 + evidenceImpact*0.15 - userCost*0.05
+```
+
+| Option                     | Purpose                                                         |
+| -------------------------- | -------------------------------------------------------------- |
+| `--goal-id <id>`           | Target an existing goal.                                       |
+| `--mode <create\|refine>`  | Create a new spec or refine an existing one.                   |
+| `--depth <light\|standard\|deep>` | Interview depth; omit to auto-select by ambiguity.      |
+| `--max-questions <n>`      | Cap the number of ranked questions.                           |
+| `--answers <file>`         | Supply answers non-interactively.                             |
+| `--write-spec`             | Persist the spec delta into a `GoalSpec`.                     |
+| `--json`                   | Emit the `omk.interview.v1` JSON contract.                    |
+
+### `omk goal refine <goal-id>`
+
+Applies the latest interview spec delta to a goal and optionally replans.
+
+| Option                  | Purpose                                          |
+| ----------------------- | ------------------------------------------------ |
+| `--from-interview <id>` | Source interview session (default: latest).      |
+| `--plan`                | Replan the goal after applying the delta.         |
+| `--json`                | Emit machine-readable output.                     |
+
+Answers file format (`--answers answers.json`):
+
+```json
+{
+  "answers": [
+    { "questionId": "q-success-criteria", "answer": "..." }
+  ]
+}
+```
+
+Session artifacts (`interview.json`, `spec-delta.json`, `questions.md`, `answers.jsonl`, `interview-report.md`) are written under `.omk/goals/<goalId>/interviews/<sessionId>/`, or `.omk/interviews/<sessionId>/` before `--write-spec`.
+
 ## What OMK controls
 
 | Surface            | What OMK does                                                                                           |

package/dist/cli/register-spec-agent-goal-commands.js

@@ -159,6 +159,51 @@ export function registerSpecAgentGoalCommands(program) {
             throw err;
         }
     });
+    goal
+        .command("interview [input]")
+        .description("[Alpha] Run a deep interview to reduce goal uncertainty before planning")
+        .option("--goal-id <id>", "Existing goal id to refine")
+        .option("--mode <create|refine>", "Interview mode (create | refine)", "create")
+        .option("--depth <light|standard|deep>", "Interview depth (omit to auto-select by ambiguity)")
+        .option("--max-questions <n>", "Maximum number of questions")
+        .option("--answers <file>", "Answers JSON file: { \"answers\": [{ \"questionId\", \"answer\" }] }")
+        .option("--image <file>", "Attach an image file (screenshot/diagram) to the interview")
+        .option("--write-spec", "Create or update the goal spec from interview answers")
+        .option("--json", t("cmd.goalJsonOption"))
+        .action(async (input, options) => {
+        const { goalInterviewCommand } = await import("../commands/goal-interview.js");
+        try {
+            await goalInterviewCommand(input, options);
+        }
+        catch (err) {
+            if (err instanceof CliError) {
+                if (process.exitCode === undefined)
+                    process.exitCode = err.exitCode;
+                return;
+            }
+            throw err;
+        }
+    });
+    goal
+        .command("refine <goal-id>")
+        .description("[Alpha] Apply the latest interview spec delta to a goal and optionally replan")
+        .option("--from-interview <id>", "Interview session id (default: latest)", "latest")
+        .option("--plan", "Rebuild the plan after applying the interview delta")
+        .option("--json", t("cmd.goalJsonOption"))
+        .action(async (goalId, options) => {
+        const { goalRefineCommand } = await import("../commands/goal-interview.js");
+        try {
+            await goalRefineCommand(goalId, options);
+        }
+        catch (err) {
+            if (err instanceof CliError) {
+                if (process.exitCode === undefined)
+                    process.exitCode = err.exitCode;
+                return;
+            }
+            throw err;
+        }
+    });
     goal
         .command("list")
         .description(t("cmd.goalListDesc"))

package/dist/cli/release-promotion-gate.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Phase 5 — Release Promotion Gate (Algorithm 8)
+ *
+ * Computes a release viability score R_v from ten normalized input
+ * dimensions and derives a verdict: block, pre-release, or stable.
+ */
+import { type ReleasePromotionInputs, type ReleasePromotionResult } from "../runtime/contracts/weakness-remediation.js";
+/** Gate engine contract. */
+export interface ReleasePromotionGate {
+    /** Evaluate inputs and return scored result with verdict. */
+    evaluate(inputs: ReleasePromotionInputs): ReleasePromotionResult;
+}
+/** Factory that creates the default release promotion gate. */
+export declare function createReleasePromotionGate(): ReleasePromotionGate;

package/dist/cli/release-promotion-gate.js

@@ -0,0 +1,71 @@
+/**
+ * Phase 5 — Release Promotion Gate (Algorithm 8)
+ *
+ * Computes a release viability score R_v from ten normalized input
+ * dimensions and derives a verdict: block, pre-release, or stable.
+ */
+import { RELEASE_GATE_WEIGHTS, } from "../runtime/contracts/weakness-remediation.js";
+/** Factory that creates the default release promotion gate. */
+export function createReleasePromotionGate() {
+    return {
+        evaluate(inputs) {
+            const w = RELEASE_GATE_WEIGHTS;
+            const demoRun = inputs.demoRun ?? false;
+            const maturity = inputs.maturity ?? inputs.providerMinimum ?? 0;
+            const rawScore = w.ci * inputs.ci +
+                w.build * (inputs.build ?? 0) +
+                w.types * (inputs.types ?? 0) +
+                w.tests * (inputs.tests ?? 0) +
+                w.install * inputs.freshInstallSmoke +
+                w.demo * (demoRun ? 1 : 0) +
+                w.proof * inputs.proofMedian +
+                w.maturity * maturity +
+                w.docs * inputs.docs -
+                w.regression * inputs.regressionSeverity;
+            const score = clamp01(rawScore);
+            const reasons = [];
+            const blocked = inputs.ci === 0 || inputs.freshInstallSmoke === 0 || !demoRun;
+            if (blocked) {
+                if (inputs.ci === 0) {
+                    reasons.push("CI score is 0 (blocking)");
+                }
+                if (inputs.freshInstallSmoke === 0) {
+                    reasons.push("Fresh install smoke is 0 (blocking)");
+                }
+                if (!demoRun) {
+                    reasons.push("Minimal verified demo run failed or missing (blocking)");
+                }
+            }
+            let verdict;
+            if (blocked) {
+                verdict = "block";
+            }
+            else if (score >= 0.90 && inputs.proofMedian >= 0.85 && maturity >= 0.80) {
+                verdict = "stable";
+                reasons.push(`Score ${formatScore(score)} meets stable threshold (≥0.90) with proof≥0.85 and maturity≥0.80`);
+            }
+            else if (score >= 0.75 && inputs.proofMedian >= 0.75) {
+                verdict = "pre-release";
+                reasons.push(`Score ${formatScore(score)} meets pre-release threshold (≥0.75) with proof≥0.75`);
+            }
+            else {
+                verdict = "block";
+                reasons.push(`Score ${formatScore(score)} below pre-release threshold (≥0.75) or proof below 0.75`);
+            }
+            return {
+                score,
+                verdict,
+                blocked,
+                reasons,
+            };
+        },
+    };
+}
+function clamp01(n) {
+    if (Number.isNaN(n))
+        return 0;
+    return Math.max(0, Math.min(1, n));
+}
+function formatScore(n) {
+    return n.toFixed(4);
+}

package/dist/cli/v2/release-commands.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Section 21 — CLI v2 Release Commands (Clipanion)
+ *
+ * `omk release check`  — Evaluate release promotion gate
+ * `omk release promote` — Promote release if gate passes (stub)
+ */
+import { Command, type Cli } from "clipanion";
+type ClipanionRegistrar = Pick<Cli, "register">;
+export declare class ReleaseCheckCommand extends Command {
+    static paths: string[][];
+    static usage: import("clipanion").Usage;
+    ci: string;
+    schema: string;
+    docs: string;
+    proof: string;
+    provider: string;
+    regression: string;
+    install: string;
+    semver: string;
+    json: boolean;
+    execute(): Promise<number>;
+}
+export declare class ReleasePromoteCommand extends Command {
+    static paths: string[][];
+    static usage: import("clipanion").Usage;
+    execute(): Promise<number>;
+}
+export declare function registerReleaseCommandsV2(cli: ClipanionRegistrar): void;
+export {};

package/dist/cli/v2/release-commands.js

@@ -0,0 +1,95 @@
+/**
+ * Section 21 — CLI v2 Release Commands (Clipanion)
+ *
+ * `omk release check`  — Evaluate release promotion gate
+ * `omk release promote` — Promote release if gate passes (stub)
+ */
+import { Command, Option } from "clipanion";
+import { createReleasePromotionGate } from "../release-promotion-gate.js";
+// ──────────────────────────────────────────────
+// Release Check
+// ──────────────────────────────────────────────
+export class ReleaseCheckCommand extends Command {
+    static paths = [["release", "check"]];
+    static usage = Command.Usage({
+        description: "Evaluate release promotion gate",
+        examples: [["Check release readiness", "omk release check"]],
+    });
+    ci = Option.String("--ci", "1", { description: "CI score (0–1)" });
+    schema = Option.String("--schema", "1", { description: "Schema score (0–1)" });
+    docs = Option.String("--docs", "1", { description: "Docs score (0–1)" });
+    proof = Option.String("--proof", "1", { description: "Proof median (0–1)" });
+    provider = Option.String("--provider", "1", { description: "Provider minimum (0–1)" });
+    regression = Option.String("--regression", "0", { description: "Regression severity (0–1)" });
+    install = Option.String("--install", "1", { description: "Fresh install smoke (0–1)" });
+    semver = Option.String("--semver", "1", { description: "Semver score (0–1)" });
+    json = Option.Boolean("--json", false, { description: "JSON output" });
+    async execute() {
+        const gate = createReleasePromotionGate();
+        const inputs = {
+            ci: Number.parseFloat(this.ci),
+            schema: Number.parseFloat(this.schema),
+            docs: Number.parseFloat(this.docs),
+            proofMedian: Number.parseFloat(this.proof),
+            providerMinimum: Number.parseFloat(this.provider),
+            regressionSeverity: Number.parseFloat(this.regression),
+            freshInstallSmoke: Number.parseFloat(this.install),
+            semver: Number.parseFloat(this.semver),
+        };
+        const result = gate.evaluate(inputs);
+        if (this.json) {
+            this.context.stdout.write(JSON.stringify(result, null, 2) + "\n");
+        }
+        else {
+            this.context.stdout.write("Release Promotion Gate\n");
+            this.context.stdout.write(`Score:   ${result.score.toFixed(4)}\n`);
+            this.context.stdout.write(`Verdict: ${result.verdict}\n`);
+            this.context.stdout.write(`Blocked: ${result.blocked}\n`);
+            if (result.reasons.length > 0) {
+                this.context.stdout.write("Reasons:\n");
+                for (const reason of result.reasons) {
+                    this.context.stdout.write(`  - ${reason}\n`);
+                }
+            }
+        }
+        return result.verdict === "block" ? 1 : 0;
+    }
+}
+// ──────────────────────────────────────────────
+// Release Promote
+// ──────────────────────────────────────────────
+export class ReleasePromoteCommand extends Command {
+    static paths = [["release", "promote"]];
+    static usage = Command.Usage({
+        description: "Promote release if gate passes",
+        examples: [["Promote release", "omk release promote"]],
+    });
+    async execute() {
+        const gate = createReleasePromotionGate();
+        const inputs = {
+            ci: Number.parseFloat(process.env.OMK_RELEASE_CI ?? "1"),
+            schema: Number.parseFloat(process.env.OMK_RELEASE_SCHEMA ?? "1"),
+            docs: Number.parseFloat(process.env.OMK_RELEASE_DOCS ?? "1"),
+            proofMedian: Number.parseFloat(process.env.OMK_RELEASE_PROOF ?? "1"),
+            providerMinimum: Number.parseFloat(process.env.OMK_RELEASE_PROVIDER ?? "1"),
+            regressionSeverity: Number.parseFloat(process.env.OMK_RELEASE_REGRESSION ?? "0"),
+            freshInstallSmoke: Number.parseFloat(process.env.OMK_RELEASE_INSTALL ?? "1"),
+            semver: Number.parseFloat(process.env.OMK_RELEASE_SEMVER ?? "1"),
+        };
+        const result = gate.evaluate(inputs);
+        this.context.stdout.write(JSON.stringify(result, null, 2) + "\n");
+        if (result.verdict === "block") {
+            this.context.stderr.write("Release promotion blocked.\n");
+            return 1;
+        }
+        this.context.stdout.write("Release promotion approved.\n");
+        return 0;
+    }
+}
+// ──────────────────────────────────────────────
+// Registration
+// ──────────────────────────────────────────────
+export function registerReleaseCommandsV2(cli) {
+    cli.register(ReleaseCheckCommand);
+    cli.register(ReleasePromoteCommand);
+}

package/dist/commands/chat/native-root-loop.js

@@ -791,6 +791,7 @@ export async function runNativeOmkRootLoop(input) {
     let running = true;
     let readlineClosed = false;
     let activeTurnAbort;
+    let pendingPastedImageLine;
     const queuedLines = [];
     let pendingLineResolve;
     const resolveNextLine = (value) => {
@@ -846,7 +847,7 @@ export async function runNativeOmkRootLoop(input) {
         const userInput = await readPromptLine();
         if (userInput === undefined)
             break;
-        const line = userInput.trim();
+        let line = userInput.trim();
         if (!line)
             continue;
         renderer?.emit({ type: "input:submitted", text: line });
@@ -855,6 +856,10 @@ export async function runNativeOmkRootLoop(input) {
             break;
         }
         const parsedSlash = parseSlashInput(line);
+        if (!parsedSlash && pendingPastedImageLine) {
+            line = `${pendingPastedImageLine}\n${line}`;
+            pendingPastedImageLine = undefined;
+        }
         const inputEnvelope = buildNativeInputEnvelope({
             loopInput: input,
             state,
@@ -896,6 +901,14 @@ export async function runNativeOmkRootLoop(input) {
                 try {
                     await terminalOwner.withChildProcess(rl, async () => {
                         const result = await runSlashHandler(handler, parsedSlash, slashContext);
+                        if (parsedSlash.command === "/paste" && result.ok) {
+                            const pasteLine = result.text?.trim();
+                            if (pasteLine) {
+                                pendingPastedImageLine = pendingPastedImageLine
+                                    ? `${pendingPastedImageLine}\n${pasteLine}`
+                                    : pasteLine;
+                            }
+                        }
                         if (result.exit)
                             running = false;
                     });

package/dist/commands/chat/slash/commands/session.js

@@ -1,7 +1,7 @@
 import { style } from "../../../../util/theme.js";
 import { readTodos } from "../../../../util/todo-sync.js";
 import { commandLine, formatScopedNames, section } from "../format.js";
-import { okSlashResult } from "../result.js";
+import { errorSlashResult, okSlashResult } from "../result.js";
 export function buildSessionSlashCommands() {
     return [
         {
@@ -22,6 +22,23 @@ export function buildSessionSlashCommands() {
             examples: ["/help"],
             handler: () => okSlashResult({ text: renderSlashHelp() }),
         },
+        {
+            name: "/paste",
+            aliases: [],
+            group: "session",
+            summary: "Paste image from clipboard",
+            usage: "/paste",
+            examples: ["/paste"],
+            handler: async (ctx) => {
+                const { pasteClipboardImage } = await import("../../../../util/clipboard-image.js");
+                const result = pasteClipboardImage(ctx.input.root);
+                if (!result.ok)
+                    return errorSlashResult(result.error ?? "No image in clipboard");
+                if (!result.relativePath)
+                    return errorSlashResult("Clipboard image saved without a relative path");
+                return okSlashResult({ text: `Image file: ${result.relativePath}` });
+            },
+        },
         {
             name: "/status",
             aliases: ["/s"],
@@ -76,6 +93,7 @@ function renderSlashHelp() {
         commandLine("/theme", "<system24|green-rain|neon-grid|rust-forge|plain|high-contrast>", "Set session theme"),
         commandLine("/view", "<summary|graph|evidence|tool-plane|events>", "Set control-plane view"),
         commandLine("/animation", "<off|low|auto|full>", "Set animation policy"),
+        commandLine("/paste", "", "Paste image from clipboard"),
         commandLine("/status", "", "Session status"),
         commandLine("/clear", "/cls", "Clear screen"),
         commandLine("/runs", "", "Recent run history"),

package/dist/commands/goal-interview.d.ts

@@ -0,0 +1,18 @@
+interface GoalInterviewOptions {
+    goalId?: string;
+    mode?: string;
+    depth?: string;
+    maxQuestions?: string;
+    answers?: string;
+    image?: string;
+    writeSpec?: boolean;
+    json?: boolean;
+}
+interface GoalRefineOptions {
+    fromInterview?: string;
+    plan?: boolean;
+    json?: boolean;
+}
+export declare function goalInterviewCommand(input: string | undefined, options: GoalInterviewOptions): Promise<void>;
+export declare function goalRefineCommand(goalId: string, options: GoalRefineOptions): Promise<void>;
+export {};