open-multi-agent-kit 0.78.1 → 0.78.3

package/dist/util/clipboard-image.js

@@ -0,0 +1,263 @@
+/**
+ * Cross-platform clipboard image reader.
+ *
+ * Wraps the platform-specific clipboard reading from screenshot-store patterns
+ * into a reusable utility for the chat REPL, goal commands, and any input
+ * surface that needs Ctrl+V / paste image support.
+ *
+ * Platforms:
+ * - macOS: `pngpaste -` (brew) or `osascript` with TIFF→PNG conversion
+ * - Linux: `xclip -selection clipboard -target image/png`
+ * - Windows: PowerShell System.Windows.Forms.Clipboard
+ *
+ * Output: PNG Buffer + saved file path under .omk/screenshots/
+ */
+import { execFileSync } from "node:child_process";
+import { mkdirSync, writeFileSync, readFileSync, existsSync, unlinkSync } from "node:fs";
+import { createHash } from "node:crypto";
+import { join, relative } from "node:path";
+export const SCREENSHOT_DIR = ".omk/screenshots";
+export const MAX_IMAGE_BYTES = 20 * 1024 * 1024;
+const CLIPBOARD_TIMEOUT_MS = 5000;
+const CLIPBOARD_MAX_BUFFER = MAX_IMAGE_BYTES * 2;
+const IMAGE_MAGIC = [
+    ["png", [0x89, 0x50, 0x4e, 0x47]],
+    ["jpg", [0xff, 0xd8, 0xff]],
+    ["webp", [0x52, 0x49, 0x46, 0x46]],
+    ["gif", [0x47, 0x49, 0x46, 0x38]],
+];
+export function detectImageExt(buf) {
+    for (const [ext, magic] of IMAGE_MAGIC) {
+        if (buf.length >= magic.length && magic.every((b, i) => buf[i] === b)) {
+            return ext;
+        }
+    }
+    return null;
+}
+function mimeTypeForExt(ext) {
+    switch (ext) {
+        case "png": return "image/png";
+        case "jpg": return "image/jpeg";
+        case "webp": return "image/webp";
+        case "gif": return "image/gif";
+        default: return "application/octet-stream";
+    }
+}
+export function toDataUri(base64, ext) {
+    return `data:${mimeTypeForExt(ext)};base64,${base64}`;
+}
+function generatePath(projectRoot, ext) {
+    const dateDir = new Date().toISOString().slice(0, 10);
+    const timestamp = new Date().toISOString().replace(/[:.]/g, "").slice(0, 15);
+    const hash = createHash("sha256").update(`${Date.now()}-${Math.random()}`).digest("hex").slice(0, 8);
+    const fileName = `screenshot-${timestamp}-${hash}.${ext}`;
+    const dir = join(projectRoot, SCREENSHOT_DIR, dateDir);
+    mkdirSync(dir, { recursive: true });
+    const fullPath = join(dir, fileName);
+    const relativePath = relative(projectRoot, fullPath).replace(/\\/g, "/");
+    return { fullPath, relativePath };
+}
+// ── Platform readers ────────────────────────────────────────────────────────
+function readMacClipboard() {
+    // Try pngpaste first (faster, more reliable)
+    try {
+        const out = execFileSync("pngpaste", ["-"], {
+            timeout: CLIPBOARD_TIMEOUT_MS,
+            maxBuffer: CLIPBOARD_MAX_BUFFER,
+            stdio: ["pipe", "pipe", "pipe"],
+        });
+        if (out.length > 0)
+            return out;
+    }
+    catch {
+        // pngpaste not installed or clipboard empty
+    }
+    // Fallback: osascript (handles TIFF → PNG conversion)
+    try {
+        const script = `
+      set theFile to (POSIX path of (path to temporary items) & "omk-clip-" & (random number from 100000 to 999999) & ".png")
+      set img to the clipboard as «class PNGf»
+      set fRef to open for access POSIX file theFile with write permission
+      write img to fRef
+      close access fRef
+      return theFile
+    `;
+        const filePath = execFileSync("osascript", ["-e", script], {
+            timeout: CLIPBOARD_TIMEOUT_MS,
+            encoding: "utf-8",
+        }).trim();
+        if (filePath) {
+            const buf = readFileSync(filePath);
+            try {
+                unlinkSync(filePath);
+            }
+            catch { /* ignore */ }
+            if (buf.length > 0)
+                return buf;
+        }
+    }
+    catch {
+        // osascript failed
+    }
+    return null;
+}
+function readLinuxClipboard() {
+    try {
+        const out = execFileSync("xclip", ["-selection", "clipboard", "-target", "image/png", "-o"], {
+            timeout: CLIPBOARD_TIMEOUT_MS,
+            maxBuffer: CLIPBOARD_MAX_BUFFER,
+            stdio: ["pipe", "pipe", "pipe"],
+        });
+        if (out.length > 0)
+            return out;
+    }
+    catch {
+        // xclip not available
+    }
+    // Fallback: wl-paste (Wayland)
+    try {
+        const out = execFileSync("wl-paste", ["--type", "image/png"], {
+            timeout: CLIPBOARD_TIMEOUT_MS,
+            maxBuffer: CLIPBOARD_MAX_BUFFER,
+            stdio: ["pipe", "pipe", "pipe"],
+        });
+        if (out.length > 0)
+            return out;
+    }
+    catch {
+        // wl-paste not available
+    }
+    return null;
+}
+function readWindowsClipboard() {
+    const script = `
+$ErrorActionPreference = 'SilentlyContinue'
+Add-Type -AssemblyName System.Windows.Forms
+Add-Type -AssemblyName System.Drawing
+
+function Emit-Bytes([byte[]]$Bytes) {
+  if ($null -eq $Bytes -or $Bytes.Length -eq 0) { exit 1 }
+  [Console]::OpenStandardOutput().Write($Bytes, 0, $Bytes.Length)
+  exit 0
+}
+
+# Try PNG format first
+$data = [System.Windows.Forms.Clipboard]::GetDataObject()
+if ($null -ne $data) {
+  foreach ($format in @('PNG', 'image/png')) {
+    if ($data.GetDataPresent($format)) {
+      $raw = $data.GetData($format)
+      if ($raw -is [System.IO.MemoryStream]) { Emit-Bytes $raw.ToArray() }
+      if ($raw -is [byte[]]) { Emit-Bytes $raw }
+    }
+  }
+  # File drop (screenshot tool saves to file then copies path)
+  if ($data.GetDataPresent([System.Windows.Forms.DataFormats]::FileDrop)) {
+    $files = [string[]]$data.GetData([System.Windows.Forms.DataFormats]::FileDrop)
+    foreach ($file in $files) {
+      if ($file -match '[.](png|jpg|jpeg|webp|gif)$' -and [System.IO.File]::Exists($file)) {
+        Emit-Bytes ([System.IO.File]::ReadAllBytes($file))
+      }
+    }
+  }
+}
+
+# Fallback: GetImage
+if ([System.Windows.Forms.Clipboard]::ContainsImage()) {
+  $img = [System.Windows.Forms.Clipboard]::GetImage()
+  if ($null -ne $img) {
+    $ms = New-Object System.IO.MemoryStream
+    try {
+      $img.Save($ms, [System.Drawing.Imaging.ImageFormat]::Png)
+      Emit-Bytes $ms.ToArray()
+    } finally {
+      $ms.Dispose()
+      $img.Dispose()
+    }
+  }
+}
+exit 1
+`;
+    try {
+        const out = execFileSync("powershell.exe", ["-NoProfile", "-Command", "-"], {
+            input: script,
+            timeout: CLIPBOARD_TIMEOUT_MS,
+            maxBuffer: CLIPBOARD_MAX_BUFFER,
+            windowsHide: true,
+            stdio: ["pipe", "pipe", "pipe"],
+        });
+        if (out.length > 0)
+            return out;
+    }
+    catch {
+        // PowerShell failed
+    }
+    return null;
+}
+/**
+ * Read an image from the system clipboard. Returns null if clipboard is empty
+ * or contains no image. Platform-specific: macOS (pngpaste/osascript), Linux
+ * (xclip/wl-paste), Windows (PowerShell).
+ */
+export function readClipboardImage(platform = process.platform) {
+    switch (platform) {
+        case "darwin": return readMacClipboard();
+        case "linux": return readLinuxClipboard();
+        case "win32": return readWindowsClipboard();
+        default: return null;
+    }
+}
+// ── High-level API ──────────────────────────────────────────────────────────
+/**
+ * Read clipboard image, validate, save to .omk/screenshots/, and return
+ * both the file path and base64 data URI for wire protocol use.
+ */
+export function pasteClipboardImage(projectRoot) {
+    const buf = readClipboardImage();
+    if (!buf || buf.length === 0) {
+        return { ok: false, error: "No image found in clipboard" };
+    }
+    if (buf.length > MAX_IMAGE_BYTES) {
+        return { ok: false, error: `Clipboard image exceeds ${MAX_IMAGE_BYTES / (1024 * 1024)} MB` };
+    }
+    const ext = detectImageExt(buf);
+    if (!ext) {
+        return { ok: false, error: "Clipboard content is not a recognized image format (PNG/JPG/WebP/GIF)" };
+    }
+    const { fullPath, relativePath } = generatePath(projectRoot, ext);
+    writeFileSync(fullPath, buf);
+    const base64 = buf.toString("base64");
+    return {
+        ok: true,
+        path: fullPath,
+        relativePath: `./${relativePath}`,
+        dataUri: toDataUri(base64, ext),
+        base64,
+        ext,
+    };
+}
+/**
+ * Read an image file from disk, validate, and return base64 data URI.
+ * Used for --image <file> flag support.
+ */
+export function readImageFile(filePath) {
+    if (!existsSync(filePath)) {
+        return { ok: false, error: `File not found: ${filePath}` };
+    }
+    const buf = readFileSync(filePath);
+    if (buf.length > MAX_IMAGE_BYTES) {
+        return { ok: false, error: `File exceeds ${MAX_IMAGE_BYTES / (1024 * 1024)} MB` };
+    }
+    const ext = detectImageExt(buf);
+    if (!ext) {
+        return { ok: false, error: "File is not a recognized image format (PNG/JPG/WebP/GIF)" };
+    }
+    const base64 = buf.toString("base64");
+    return {
+        ok: true,
+        path: filePath,
+        dataUri: toDataUri(base64, ext),
+        base64,
+        ext,
+    };
+}

package/docs/2026-06-09/critical-issues.md

@@ -0,0 +1,20 @@
+# 2026-06-09 Critical Issues
+
+## Critical Init Status
+- No critical init artifacts were missing when this daily file was generated.
+### Missing critical artifacts
+- None detected.
+
+
+## Critical Artifacts Present
+- ✅ `AGENTS.md` — top-level operating contract
+- ✅ `.kimi/AGENTS.md` — Kimi-specific operating rules
+- ✅ `.omk/config.toml` — OMK project runtime settings
+- ✅ `.omk/agents/root.yaml` — root coordinator agent
+- ✅ `.kimi/mcp.json` — Kimi project MCP registry
+- ✅ `.omk/hooks/pre-shell-guard.sh` — destructive shell guard
+- ✅ `.omk/hooks/protect-secrets.sh` — secret write guard
+- ✅ `.omk/memory/graph-state.json` — local ontology graph database
+
+## Escalation Rule
+- Treat missing shell/secret guards, root agent config, MCP registry, or ontology graph as critical until restored.

package/docs/2026-06-09/improvements.md

@@ -0,0 +1,14 @@
+# 2026-06-09 Improvements
+
+## Current Improvement Backlog
+### Optional init/support artifacts to add or refresh
+- None detected.
+
+### Critical init artifacts currently blocking reliable chat startup
+- None detected.
+
+
+## Suggested Focus
+- Keep `omk chat` startup idempotent and non-destructive.
+- Prefer local graph memory for default ontology state.
+- Keep generated daily docs small, dated, and safe to edit by hand.

package/docs/2026-06-09/init-checklist.md

@@ -0,0 +1,25 @@
+# 2026-06-09 Required Init Checklist
+
+**Run ID:** chat-2026-06-09T00-01-07-440Z-28177
+**Ontology graph:** `.omk/memory/graph-state.json`
+
+## Required Artifacts
+- ✅ `AGENTS.md` — critical; top-level operating contract
+- ✅ `.kimi/AGENTS.md` — critical; Kimi-specific operating rules
+- ✅ `DESIGN.md` — support; design/brand source of truth
+- ✅ `.omk/config.toml` — critical; OMK project runtime settings
+- ✅ `.omk/agents/root.yaml` — critical; root coordinator agent
+- ✅ `.kimi/mcp.json` — critical; Kimi project MCP registry
+- ✅ `.omk/mcp.json` — support; legacy OMK MCP fallback
+- ✅ `.omk/lsp.json` — support; bundled TypeScript/Python LSP config
+- ✅ `.omk/hooks/pre-shell-guard.sh` — critical; destructive shell guard
+- ✅ `.omk/hooks/protect-secrets.sh` — critical; secret write guard
+- ✅ `.omk/memory/graph-state.json` — critical; local ontology graph database
+- ✅ `.kimi/skills` — support; Kimi skill directory
+- ✅ `.agents/skills` — support; portable skill directory
+
+## Recovery Command
+```bash
+omk init
+omk doctor
+```

package/docs/2026-06-09/plan.md

@@ -0,0 +1,20 @@
+# 2026-06-09 OMK Chat Plan
+
+**Run ID:** chat-2026-06-09T00-01-07-440Z-28177
+**Generated by:** omk chat bootstrap
+
+## Purpose
+- Start every chat with a dated workspace for planning, issue triage, and verification evidence.
+- Keep ontology-backed memory available before the root coordinator starts.
+- Make required init state visible without overwriting user-authored docs.
+
+## Today Plan
+1. Review `init-checklist.md` and resolve missing critical init artifacts first.
+2. Use `improvements.md` as the active improvement backlog.
+3. Use `critical-issues.md` for blocking defects, safety risks, and verification gaps.
+4. Record command evidence before claiming work is complete.
+
+## Stop Condition
+- Critical init artifacts are present.
+- Ontology graph exists at `.omk/memory/graph-state.json`.
+- Any new code/docs changes have explicit verification evidence.

package/docs/benchmark-design.md

@@ -0,0 +1,122 @@
+# OMK Control Plane Replay Benchmark Design
+
+## 1. Purpose
+
+Design a reproducible benchmark suite that measures OMK control plane
+performance across 10 representative task categories. The benchmark runs in
+**shadow mode** (recorded traces, no live LLM calls) for baseline
+reproducibility, with optional **live-evaluation mode** for regression
+testing against real providers.
+
+## 2. Task Categories
+
+| # | Category | Intent | Description |
+|---|----------|--------|-------------|
+| 1 | read-only repo Q&A | research | Agent answers questions about codebase structure |
+| 2 | small bug fix | debugging | Single-file typo / logic fix |
+| 3 | failing test repair | debugging | Update implementation to satisfy failing test |
+| 4 | multi-file refactor | refactor | Rename/move symbols across 3+ files |
+| 5 | CLI command task | shell-operation | Execute and verify CLI output |
+| 6 | dependency update | coding | Bump package version, fix breaking changes |
+| 7 | merge-conflict task | merge | Resolve git merge conflict automatically |
+| 8 | security-sensitive task | review | Patch vulnerability with audit trail |
+| 9 | provider failure fallback | debugging | Primary provider fails; fallback succeeds |
+| 10 | quota/auth failure fallback | debugging | Quota/auth error triggers provider switch |
+
+## 3. Metrics
+
+| Metric | Definition | Source |
+|--------|-----------|--------|
+| solve_rate | passed_tasks / total_tasks | harness result |
+| evidence_trust_score | ETS v2 score per task | evidence-trust-score engine |
+| false_done_rate | tasks claiming success with failing evidence / total | harness+ETS |
+| fallback_success_rate | fallback attempts that succeed / total fallback attempts | router decision trace |
+| router_regret | best_available_runtime_score − selected_runtime_score | shadow-mode diff |
+| cost_per_solved_task | Σ costUsdEstimated / solved_count | attempt records |
+| p95_latency | 95th percentile of task latencyMs | attempt records |
+| rollback_rate | tasks rolled back / total tasks | decision trace |
+| sandbox_violation_count | tasks with unexpected file writes outside worktree | sandbox audit |
+
+**router_regret** is computed in shadow mode by scoring all candidates for
+every decision and comparing the selected runtime’s composite against the
+maximum composite.
+
+## 4. Reproducibility Contract
+
+Every benchmark run must pin:
+- **treeHash**: git commit SHA of the repo under test
+- **seed**: PRNG seed for synthetic fixture generation
+- **providerConfigHash**: hash of the runtime provider configuration
+- **omkVersion**: package version
+- **benchmarkSchemaVersion**: `omk.benchmark.v1`
+
+Shadow-mode runs use pre-recorded `BenchmarkTrace` fixtures (see
+`src/benchmark/fixtures.ts`). Live-evaluation mode records new traces into
+`.omk/benchmarks/<runId>/`.
+
+## 5. Shadow Mode
+
+Shadow mode runs router v1 and v2 side-by-side on identical inputs:
+1. Load a `BenchmarkTask` fixture.
+2. Run `createRuntimeRouter` (v1) and `createRouterV2ScoringEngine` (v2).
+3. Record both decisions into `ShadowModeRecord`.
+4. Compute `router_regret` for each.
+5. Diff v1/v2 selections and log disagreements.
+
+No LLM API calls are made. Runtime `runNode` is replaced with a stub that
+returns the recorded outcome from the fixture.
+
+## 6. Benchmark Harness Lifecycle
+
+```
+loadConfig() → discoverTasks() → for each task:
+  setupWorktree() → runTask() → evaluateEvidence() → teardown()
+→ computeSummary() → writeJsonReport()
+```
+
+The harness integrates with `scripts/run-tests.mjs` via:
+```bash
+node scripts/run-benchmark.mjs --shadow --summary-json .omk/benchmarks/latest.json
+```
+
+## 7. CI Integration
+
+A new `benchmark` job runs after `fast-gate` passes on `main` branch merges
+and nightly cron. It:
+1. Checks out the repo at the merge commit.
+2. Runs `npm run benchmark:shadow`.
+3. Uploads `.omk/benchmarks/latest.json` as artifact.
+4. Fails if `solve_rate < 0.85` or `false_done_rate > 0.05`.
+
+## 8. Directory Layout
+
+```
+src/benchmark/
+  contracts.ts      # BenchmarkTask, BenchmarkResult, BenchmarkSummary
+  harness.ts        # runBenchmarkSuite(), runBenchmarkTask()
+  shadow-mode.ts    # ShadowModeEngine, computeRouterRegret()
+  fixtures.ts       # generateSyntheticTraces(), loadRecordedTraces()
+scripts/
+  run-benchmark.mjs # CLI entrypoint
+test/
+  benchmark-harness.test.mjs
+.omk/benchmarks/
+  sample-run.json   # example output
+```
+
+## 9. Extending the Benchmark
+
+To add a new task category:
+1. Add intent mapping in `src/benchmark/fixtures.ts`.
+2. Create a fixture under `test/benchmark-fixtures/`.
+3. Add an evaluation rule in `src/benchmark/harness.ts`.
+4. Register the category in `scripts/run-benchmark.mjs`.
+
+## 10. Risks & Mitigations
+
+| Risk | Mitigation |
+|------|-----------|
+| Fixture drift (codebase changes) | Pin treeHash; auto-regenerate fixtures in CI if drift detected |
+| Shadow mode not representative of live behavior | Weekly live-evaluation job with small sample |
+| Metrics gaming (fake evidence) | ETS v2 gaming penalty + runner-source requirement |
+| Secret leakage in recorded traces | Redact with `redactTrace()` before persistence |

package/docs/github-organic-promotion.md

@@ -0,0 +1,127 @@
+# GitHub organic promotion checklist
+
+OMK's strongest GitHub search position is:
+
+> Provider-neutral multi-agent control plane for coding agents: route runtimes, scope MCP tools, run DAG workers, verify evidence, and replay agent runs.
+
+## Repository About
+
+Recommended GitHub About description:
+
+```txt
+Provider-neutral multi-agent control plane for coding agents. Route runtimes, scope MCP tools, run DAG workers, verify evidence, and replay agent runs from the omk CLI.
+```
+
+Apply after maintainer confirmation:
+
+```bash
+gh repo edit dmae97/open-multi-agent-kit \
+  --description "Provider-neutral multi-agent control plane for coding agents. Route runtimes, scope MCP tools, run DAG workers, verify evidence, and replay agent runs from the omk CLI."
+```
+
+## GitHub Topics
+
+Use all 20 topics:
+
+```txt
+ai-agent
+ai-agents
+llm
+coding-agent
+ai-coding
+agentic-coding
+multi-agent
+multi-agent-orchestration
+agent-orchestration
+agent-runtime
+agent-control-plane
+developer-tools
+ai-devtools
+cli
+typescript
+nodejs
+mcp
+model-context-protocol
+workflow-automation
+provider-neutral
+```
+
+Apply after maintainer confirmation:
+
+```bash
+gh repo edit dmae97/open-multi-agent-kit \
+  --add-topic ai-agent \
+  --add-topic ai-agents \
+  --add-topic llm \
+  --add-topic coding-agent \
+  --add-topic ai-coding \
+  --add-topic agentic-coding \
+  --add-topic multi-agent \
+  --add-topic multi-agent-orchestration \
+  --add-topic agent-orchestration \
+  --add-topic agent-runtime \
+  --add-topic agent-control-plane \
+  --add-topic developer-tools \
+  --add-topic ai-devtools \
+  --add-topic cli \
+  --add-topic typescript \
+  --add-topic nodejs \
+  --add-topic mcp \
+  --add-topic model-context-protocol \
+  --add-topic workflow-automation \
+  --add-topic provider-neutral
+```
+
+## Social preview
+
+Upload this generated image in GitHub repository settings:
+
+```txt
+readmeasset/social-preview.png
+```
+
+It uses the message:
+
+```txt
+OMK
+Provider-Neutral Multi-Agent Control Plane
+Route. Verify. Replay.
+```
+
+## Awesome-list PR entries
+
+### bradAGI/awesome-cli-coding-agents
+
+Preferred section: `Harnesses & orchestration`.
+
+```md
+- **[OMK](https://github.com/dmae97/open-multi-agent-kit)** `⭐ <current>` — Provider-neutral CLI control plane for coding agents: routes runtimes, scopes MCP, runs DAG workers, and verifies evidence before completion. MIT.
+```
+
+### e2b-dev/awesome-ai-sdks
+
+```md
+## [OMK](https://github.com/dmae97/open-multi-agent-kit)
+
+OMK is a provider-neutral multi-agent control plane for coding workflows. It routes agent runtimes, scopes MCP tools, runs DAG-based workers, verifies evidence, and preserves replayable run artifacts.
+
+### Links
+
+- [GitHub](https://github.com/dmae97/open-multi-agent-kit)
+- [npm](https://www.npmjs.com/package/open-multi-agent-kit)
+```
+
+### punkpeye/awesome-mcp-devtools
+
+Preferred section: `Frameworks` or `Development Tools`.
+
+```md
+- [OMK](https://github.com/dmae97/open-multi-agent-kit) - TypeScript CLI control plane for coding agents with scoped MCP injection, provider routing, evidence gates, and replayable run telemetry.
+```
+
+## Measurement plan
+
+- Topics applied + 7 days: inspect GitHub topic/search traffic.
+- First awesome PR merged + 7 days: check `Referring sites` for that awesome repo.
+- 2 weeks: compare visitors, clones, npm downloads, and popular README content.
+- 4 weeks: review visitor-to-star conversion; 1-3% is acceptable for early OSS.