open-multi-agent-kit 0.78.0 → 0.78.2

package/dist/runtime/tool-dispatch-contracts.js

@@ -1,10 +1,86 @@
 import { createToolExecutionBatches } from "./tool-registry-contract.js";
-export async function dispatchToolCallsByContract(calls, registry, dispatchOne) {
+import { decideToolAuthority, mapToolNameToOp, } from "../safety/tool-authority-gate.js";
+const ENFORCE_PATTERN = /^(1|true|yes|on)$/i;
+/**
+ * Resolve the global enforcement opt-in from the environment. Default OFF means
+ * the gate runs in shadow mode (record only). Set `OMK_TOOL_AUTHORITY_ENFORCE=1`
+ * to enable fail-closed enforcement at the dispatch checkpoint.
+ */
+export function resolveToolAuthorityEnforcement(env = process.env) {
+    return ENFORCE_PATTERN.test((env.OMK_TOOL_AUTHORITY_ENFORCE ?? "").trim());
+}
+/** Build a redacted reason string from non-secret authority signals only. */
+function redactedAuthorityReason(op, decision, wiring) {
+    return (`tool-authority ${decision} for ${op} op ` +
+        `(write=${wiring.writeAuthority}, shell=${wiring.shellAuthority}, ` +
+        `policy=${wiring.approvalPolicy}, sandbox=${wiring.sandboxMode}, tty=${wiring.tty})`);
+}
+/** Error used to reject a tool call rejected by the authority gate (enforce mode). */
+export class ToolAuthorityBlockedError extends Error {
+    toolName;
+    op;
+    decision;
+    constructor(record) {
+        super(record.reason);
+        this.name = "ToolAuthorityBlockedError";
+        this.toolName = record.toolName;
+        this.op = record.op;
+        this.decision = record.decision;
+    }
+}
+/** Compute the gate verdict for a single call. Pure (no IO, no env reads). */
+export function evaluateToolAuthority(toolName, wiring) {
+    const op = mapToolNameToOp(toolName);
+    const decision = decideToolAuthority({
+        op,
+        writeAuthority: wiring.writeAuthority,
+        shellAuthority: wiring.shellAuthority,
+        approvalPolicy: wiring.approvalPolicy,
+        sandboxMode: wiring.sandboxMode,
+        tty: wiring.tty,
+    });
+    const enforce = wiring.enforce === true;
+    // Fail-closed: a non-TTY "ask" is treated as a block (decideToolAuthority
+    // already returns "block" for non-TTY interactive; the second clause is a
+    // defensive guard in case the caller ever surfaces "ask" without a TTY).
+    const wouldBlock = decision === "block" || (decision === "ask" && !wiring.tty);
+    const blocked = enforce && wouldBlock;
+    return {
+        record: {
+            toolName,
+            op,
+            decision,
+            mode: enforce ? "enforce" : "shadow",
+            enforced: blocked,
+            reason: redactedAuthorityReason(op, decision, wiring),
+        },
+        blocked,
+    };
+}
+/**
+ * Wrap a dispatch function with the authority checkpoint. In shadow mode the
+ * wrapper records the verdict and always delegates to `dispatchOne`. In enforce
+ * mode a blocked verdict rejects the call with a redacted reason.
+ */
+function buildGatedDispatch(wiring, dispatchOne) {
+    return async (call) => {
+        const { record, blocked } = evaluateToolAuthority(call.toolName, wiring);
+        wiring.onDecision?.(record);
+        if (blocked) {
+            throw new ToolAuthorityBlockedError(record);
+        }
+        return dispatchOne(call);
+    };
+}
+export async function dispatchToolCallsByContract(calls, registry, dispatchOne, authority) {
+    // When no authority wiring is supplied the dispatch path is byte-identical to
+    // the pre-gate behavior (the checkpoint is a no-op).
+    const effectiveDispatch = authority ? buildGatedDispatch(authority, dispatchOne) : dispatchOne;
     const batches = createToolExecutionBatches(calls, registry);
     const appended = [];
     for (const batch of batches) {
         if (batch.kind === "parallel") {
-            const settled = await Promise.allSettled(batch.calls.map((call) => dispatchOne(call)));
+            const settled = await Promise.allSettled(batch.calls.map((call) => effectiveDispatch(call)));
             settled.forEach((result, index) => {
                 const call = batch.calls[index];
                 if (!call)
@@ -15,7 +91,7 @@ export async function dispatchToolCallsByContract(calls, registry, dispatchOne)
         }
         for (const call of batch.calls) {
             try {
-                appended.push({ call, status: "fulfilled", value: await dispatchOne(call) });
+                appended.push({ call, status: "fulfilled", value: await effectiveDispatch(call) });
             }
             catch (reason) {
                 appended.push({ call, status: "rejected", reason });

package/dist/runtime/weakness-remediation-index.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Weakness Remediation Index — Public factory that instantiates all
+ * Phase 1–6 engines with sensible defaults.
+ */
+export { type IntegrationResultKind, type WeaknessRemediationState, type AdvancedControlLoopInput, type AdvancedControlLoopResult, type AdvancedControlLoop, type AdvancedControlLoopOptions, createAdvancedControlLoop, } from "./advanced-control-loop.js";
+export { type SurfaceItem, type ScoredSurfaceItem, type MandatoryAnchor, type CompressionResult, type PublicSurfaceCompressorOptions, computeSurfaceScore, enforceFlowInvariant, PublicSurfaceCompressor, } from "./public-surface.js";
+export { type ProofBundleScores, type TrustScoreResult, type ProofBundleTrustEngine, type DeriveScoresOptions, createProofBundleTrustEngine, } from "./proof-bundle-trust.js";
+export { type MaturityResult, type ProviderMaturityGate, createProviderMaturityGate, } from "./provider-maturity-gate.js";
+export { type RuntimeScoreV2, type RuntimeRouterDecisionV2, type RouterV2Options, type RouterV2ScoringEngine, type BlastRadiusParams, type EvidenceHistoryEntry, type NodeIntent, } from "./contracts/router-v2.js";
+export { createRouterV2ScoringEngine, } from "./router-v2-scoring.js";
+export { type ReleasePromotionInputs, type ReleasePromotionResult, type ReleaseVerdict, RELEASE_GATE_WEIGHTS, TAU_EVIDENCE, TAU_EVIDENCE_HIGH, TAU_PROOF, TAU_STABLE, BETA_PRIOR_ALPHA0, BETA_PRIOR_BETA0, SURFACE_BUDGET_K, } from "./contracts/weakness-remediation.js";
+export { createReleasePromotionGate, type ReleasePromotionGate, } from "../cli/release-promotion-gate.js";
+import { PublicSurfaceCompressor } from "./public-surface.js";
+import { createProofBundleTrustEngine } from "./proof-bundle-trust.js";
+import { createProviderMaturityGate } from "./provider-maturity-gate.js";
+import { createRouterV2ScoringEngine } from "./router-v2-scoring.js";
+import { createReleasePromotionGate } from "../cli/release-promotion-gate.js";
+import { createAdvancedControlLoop } from "./advanced-control-loop.js";
+export interface WeaknessRemediationIndex {
+    readonly publicSurfaceCompressor: PublicSurfaceCompressor;
+    readonly proofBundleTrustEngine: ReturnType<typeof createProofBundleTrustEngine>;
+    readonly providerMaturityGate: ReturnType<typeof createProviderMaturityGate>;
+    readonly routerV2ScoringEngine: ReturnType<typeof createRouterV2ScoringEngine>;
+    readonly releasePromotionGate: ReturnType<typeof createReleasePromotionGate>;
+    readonly advancedControlLoop: ReturnType<typeof createAdvancedControlLoop>;
+}
+export declare function createWeaknessRemediationIndex(): WeaknessRemediationIndex;

package/dist/runtime/weakness-remediation-index.js

@@ -0,0 +1,37 @@
+/**
+ * Weakness Remediation Index — Public factory that instantiates all
+ * Phase 1–6 engines with sensible defaults.
+ */
+export { createAdvancedControlLoop, } from "./advanced-control-loop.js";
+export { computeSurfaceScore, enforceFlowInvariant, PublicSurfaceCompressor, } from "./public-surface.js";
+export { createProofBundleTrustEngine, } from "./proof-bundle-trust.js";
+export { createProviderMaturityGate, } from "./provider-maturity-gate.js";
+export { createRouterV2ScoringEngine, } from "./router-v2-scoring.js";
+export { RELEASE_GATE_WEIGHTS, TAU_EVIDENCE, TAU_EVIDENCE_HIGH, TAU_PROOF, TAU_STABLE, BETA_PRIOR_ALPHA0, BETA_PRIOR_BETA0, SURFACE_BUDGET_K, } from "./contracts/weakness-remediation.js";
+export { createReleasePromotionGate, } from "../cli/release-promotion-gate.js";
+// ─── Convenience factory ─────────────────────────────────────────────────────
+import { PublicSurfaceCompressor } from "./public-surface.js";
+import { createProofBundleTrustEngine } from "./proof-bundle-trust.js";
+import { createProviderMaturityGate } from "./provider-maturity-gate.js";
+import { createRouterV2ScoringEngine } from "./router-v2-scoring.js";
+import { createReleasePromotionGate } from "../cli/release-promotion-gate.js";
+import { createAdvancedControlLoop } from "./advanced-control-loop.js";
+export function createWeaknessRemediationIndex() {
+    const publicSurfaceCompressor = new PublicSurfaceCompressor();
+    const proofBundleTrustEngine = createProofBundleTrustEngine();
+    const providerMaturityGate = createProviderMaturityGate();
+    const routerV2ScoringEngine = createRouterV2ScoringEngine();
+    const releasePromotionGate = createReleasePromotionGate();
+    const advancedControlLoop = createAdvancedControlLoop({
+        releaseGate: releasePromotionGate,
+        releaseGateEnabled: true,
+    });
+    return {
+        publicSurfaceCompressor,
+        proofBundleTrustEngine,
+        providerMaturityGate,
+        routerV2ScoringEngine,
+        releasePromotionGate,
+        advancedControlLoop,
+    };
+}

package/dist/safety/tool-authority-gate.d.ts

@@ -0,0 +1,62 @@
+/**
+ * Pure tool-authority decision primitive.
+ *
+ * Decides allow / ask / block for a tool operation given the provider's
+ * write/shell authority, the active approval policy, the sandbox mode, and
+ * whether a TTY is attached. The function is intentionally pure: no IO, no
+ * environment reads, no secrets, no side effects.
+ *
+ * STATUS (0.78.2 stabilization): this primitive is NOT wired into any live
+ * tool-dispatch path. It exists so 0.78.3 can wire it into
+ * `dispatchToolCallsByContract` (src/runtime/tool-dispatch-contracts.ts) and
+ * the kimi runner tool loop without re-deriving the policy. Zero behavior
+ * change to current execution.
+ *
+ * Design rules (authority outranks policy; fail-closed):
+ *  1. read ops are always allowed.
+ *  2. a read-only sandbox is a hard floor: any non-read op is blocked.
+ *  3. authority must be satisfied for the op before policy is consulted:
+ *       write  -> writeAuthority === "full"
+ *       shell  -> shellAuthority === "full"
+ *       merge  -> writeAuthority === "full" AND shellAuthority === "full"
+ *  4. once authority is satisfied, the approval policy decides:
+ *       block       -> block
+ *       yolo        -> allow
+ *       auto        -> allow
+ *       interactive -> ask when a TTY is present, otherwise block
+ *                      (ask in a non-TTY context = deny-by-default).
+ */
+import type { ProviderAuthorityLevel } from "../contracts/provider-health.js";
+/** Coarse operation class used by the authority gate. */
+export type ToolOp = "read" | "write" | "shell" | "merge";
+/** Gate verdict for a single tool operation. */
+export type ToolAuthorityDecision = "allow" | "ask" | "block";
+/** Inputs to the authority decision. Fully self-contained and side-effect free. */
+export interface ToolAuthorityContext {
+    /** Operation class derived from the tool being invoked. */
+    readonly op: ToolOp;
+    /** Provider authority for write/mutation work. */
+    readonly writeAuthority: ProviderAuthorityLevel;
+    /** Provider authority for shell/CLI work. */
+    readonly shellAuthority: ProviderAuthorityLevel;
+    /** Active approval policy for the run. */
+    readonly approvalPolicy: "interactive" | "auto" | "yolo" | "block";
+    /** Active sandbox mode; "read-only" is a hard floor for non-read ops. */
+    readonly sandboxMode: "read-only" | "workspace-write";
+    /** Whether an interactive TTY is attached (gates "interactive" -> ask). */
+    readonly tty: boolean;
+}
+/**
+ * Map a raw tool name to its coarse {@link ToolOp} class.
+ *
+ * Matching is case-insensitive. Unrecognized tools fail closed to the most
+ * restrictive sensible op (`shell` = arbitrary effect execution) rather than
+ * `read`, so an unknown tool is never silently treated as harmless.
+ */
+export declare function mapToolNameToOp(toolName: string): ToolOp;
+/**
+ * Decide allow / ask / block for a tool operation. Pure and fail-closed.
+ *
+ * @see ToolAuthorityContext for the decision inputs and ordering rules.
+ */
+export declare function decideToolAuthority(ctx: ToolAuthorityContext): ToolAuthorityDecision;

package/dist/safety/tool-authority-gate.js

@@ -0,0 +1,108 @@
+/**
+ * Pure tool-authority decision primitive.
+ *
+ * Decides allow / ask / block for a tool operation given the provider's
+ * write/shell authority, the active approval policy, the sandbox mode, and
+ * whether a TTY is attached. The function is intentionally pure: no IO, no
+ * environment reads, no secrets, no side effects.
+ *
+ * STATUS (0.78.2 stabilization): this primitive is NOT wired into any live
+ * tool-dispatch path. It exists so 0.78.3 can wire it into
+ * `dispatchToolCallsByContract` (src/runtime/tool-dispatch-contracts.ts) and
+ * the kimi runner tool loop without re-deriving the policy. Zero behavior
+ * change to current execution.
+ *
+ * Design rules (authority outranks policy; fail-closed):
+ *  1. read ops are always allowed.
+ *  2. a read-only sandbox is a hard floor: any non-read op is blocked.
+ *  3. authority must be satisfied for the op before policy is consulted:
+ *       write  -> writeAuthority === "full"
+ *       shell  -> shellAuthority === "full"
+ *       merge  -> writeAuthority === "full" AND shellAuthority === "full"
+ *  4. once authority is satisfied, the approval policy decides:
+ *       block       -> block
+ *       yolo        -> allow
+ *       auto        -> allow
+ *       interactive -> ask when a TTY is present, otherwise block
+ *                      (ask in a non-TTY context = deny-by-default).
+ */
+/**
+ * Map a raw tool name to its coarse {@link ToolOp} class.
+ *
+ * Matching is case-insensitive. Unrecognized tools fail closed to the most
+ * restrictive sensible op (`shell` = arbitrary effect execution) rather than
+ * `read`, so an unknown tool is never silently treated as harmless.
+ */
+export function mapToolNameToOp(toolName) {
+    const name = toolName.trim().toLowerCase();
+    // Highest-risk git operations publish or rewrite history -> merge.
+    const mergeSignals = ["push", "merge", "cherry-pick", "cherrypick", "rebase", "tag"];
+    const looksLikeGit = name.startsWith("git") || /\bgit\b/.test(name);
+    if (looksLikeGit && mergeSignals.some((signal) => name.includes(signal))) {
+        return "merge";
+    }
+    // Bare verbs used directly as tool names (e.g. "merge", "rebase").
+    if (mergeSignals.some((signal) => name === signal)) {
+        return "merge";
+    }
+    // Shell / command execution.
+    if (name === "shell" || name === "bash" || name.includes("shell") || name.includes("bash")) {
+        return "shell";
+    }
+    // Write / mutation tools.
+    const writeSignals = ["write", "str_replace", "strreplace", "applydiff", "apply_diff", "edit"];
+    if (writeSignals.some((signal) => name.includes(signal))) {
+        return "write";
+    }
+    // Read-only tools (exact names to avoid accidental substring matches).
+    const readSignals = ["read", "grep", "glob", "ls", "cat"];
+    if (readSignals.includes(name)) {
+        return "read";
+    }
+    // Unknown / unrecognized -> most restrictive sensible op (fail-closed).
+    return "shell";
+}
+/** Returns true when provider authority is sufficient for the requested op. */
+function isAuthoritySatisfied(ctx) {
+    switch (ctx.op) {
+        case "read":
+            return true;
+        case "write":
+            return ctx.writeAuthority === "full";
+        case "shell":
+            return ctx.shellAuthority === "full";
+        case "merge":
+            return ctx.writeAuthority === "full" && ctx.shellAuthority === "full";
+    }
+}
+/**
+ * Decide allow / ask / block for a tool operation. Pure and fail-closed.
+ *
+ * @see ToolAuthorityContext for the decision inputs and ordering rules.
+ */
+export function decideToolAuthority(ctx) {
+    // Rule 1: reads are always allowed.
+    if (ctx.op === "read") {
+        return "allow";
+    }
+    // Rule 2: a read-only sandbox is a hard floor for any non-read op.
+    if (ctx.sandboxMode === "read-only") {
+        return "block";
+    }
+    // Rule 3: authority outranks policy. Insufficient authority => block.
+    if (!isAuthoritySatisfied(ctx)) {
+        return "block";
+    }
+    // Rule 4: authority satisfied -> apply approval policy.
+    if (ctx.approvalPolicy === "block") {
+        return "block";
+    }
+    if (ctx.approvalPolicy === "yolo") {
+        return "allow";
+    }
+    if (ctx.approvalPolicy === "auto") {
+        return "allow";
+    }
+    // interactive: ask only when a TTY is attached; non-TTY ask = deny-by-default.
+    return ctx.tty ? "ask" : "block";
+}

package/dist/schema/proof-bundle.schema.d.ts

@@ -16,29 +16,29 @@ export declare const ProofBundleFilesSchema: z.ZodObject<{
 }, "strip", z.ZodTypeAny, {
     commands: string;
     rawPrompt: string;
-    verifyJson: string;
+    limitations: string;
     decisionsJsonl: string;
-    runManifest: string;
     evidenceJsonl: string;
-    limitations: string;
+    verifyJson: string;
+    runManifest: string;
     stdout?: string | undefined;
     stderr?: string | undefined;
     replay?: string | undefined;
-    diffPatch?: string | undefined;
     inspectJson?: string | undefined;
+    diffPatch?: string | undefined;
 }, {
     commands: string;
     rawPrompt: string;
-    verifyJson: string;
+    limitations: string;
     decisionsJsonl: string;
-    runManifest: string;
     evidenceJsonl: string;
-    limitations: string;
+    verifyJson: string;
+    runManifest: string;
     stdout?: string | undefined;
     stderr?: string | undefined;
     replay?: string | undefined;
-    diffPatch?: string | undefined;
     inspectJson?: string | undefined;
+    diffPatch?: string | undefined;
 }>;
 export declare const ProofBundleSchema: z.ZodObject<{
     schemaVersion: z.ZodLiteral<"omk.proof-bundle.v1">;
@@ -66,29 +66,29 @@ export declare const ProofBundleSchema: z.ZodObject<{
     }, "strip", z.ZodTypeAny, {
         commands: string;
         rawPrompt: string;
-        verifyJson: string;
+        limitations: string;
         decisionsJsonl: string;
-        runManifest: string;
         evidenceJsonl: string;
-        limitations: string;
+        verifyJson: string;
+        runManifest: string;
         stdout?: string | undefined;
         stderr?: string | undefined;
         replay?: string | undefined;
-        diffPatch?: string | undefined;
         inspectJson?: string | undefined;
+        diffPatch?: string | undefined;
     }, {
         commands: string;
         rawPrompt: string;
-        verifyJson: string;
+        limitations: string;
         decisionsJsonl: string;
-        runManifest: string;
         evidenceJsonl: string;
-        limitations: string;
+        verifyJson: string;
+        runManifest: string;
         stdout?: string | undefined;
         stderr?: string | undefined;
         replay?: string | undefined;
-        diffPatch?: string | undefined;
         inspectJson?: string | undefined;
+        diffPatch?: string | undefined;
     }>;
     verdict: z.ZodEnum<["passed", "failed", "partial"]>;
     knownLimitations: z.ZodArray<z.ZodString, "many">;
@@ -101,21 +101,21 @@ export declare const ProofBundleSchema: z.ZodObject<{
     files: {
         commands: string;
         rawPrompt: string;
-        verifyJson: string;
+        limitations: string;
         decisionsJsonl: string;
-        runManifest: string;
         evidenceJsonl: string;
-        limitations: string;
+        verifyJson: string;
+        runManifest: string;
         stdout?: string | undefined;
         stderr?: string | undefined;
         replay?: string | undefined;
-        diffPatch?: string | undefined;
         inspectJson?: string | undefined;
+        diffPatch?: string | undefined;
     };
     providerPolicy: string;
     omkVersion: string;
-    runtimeVersion: "v1.2";
     proofId: string;
+    runtimeVersion: "v1.2";
     scenario: "no-kimi-smoke" | "evidence-block" | "fallback-route" | "dag-dependent-block" | "replay-inspect" | "example-generation" | "doctor-provider" | "native-safety" | "contract-version-smoke";
     verdict: "failed" | "partial" | "passed";
     knownLimitations: string[];
@@ -128,21 +128,21 @@ export declare const ProofBundleSchema: z.ZodObject<{
     files: {
         commands: string;
         rawPrompt: string;
-        verifyJson: string;
+        limitations: string;
         decisionsJsonl: string;
-        runManifest: string;
         evidenceJsonl: string;
-        limitations: string;
+        verifyJson: string;
+        runManifest: string;
         stdout?: string | undefined;
         stderr?: string | undefined;
         replay?: string | undefined;
-        diffPatch?: string | undefined;
         inspectJson?: string | undefined;
+        diffPatch?: string | undefined;
     };
     providerPolicy: string;
     omkVersion: string;
-    runtimeVersion: "v1.2";
     proofId: string;
+    runtimeVersion: "v1.2";
     scenario: "no-kimi-smoke" | "evidence-block" | "fallback-route" | "dag-dependent-block" | "replay-inspect" | "example-generation" | "doctor-provider" | "native-safety" | "contract-version-smoke";
     verdict: "failed" | "partial" | "passed";
     knownLimitations: string[];

package/dist/schema/provider.schema.d.ts

@@ -47,16 +47,16 @@ export declare const ProviderCapabilitySchema: z.ZodObject<{
         cli: boolean;
         api: boolean;
         mcp: boolean;
-        streaming: boolean;
         tools: boolean;
+        streaming: boolean;
         screenshots: boolean;
         worktreeSafe: boolean;
     }, {
         cli: boolean;
         api: boolean;
         mcp: boolean;
-        streaming: boolean;
         tools: boolean;
+        streaming: boolean;
         screenshots: boolean;
         worktreeSafe: boolean;
     }>;
@@ -102,8 +102,8 @@ export declare const ProviderCapabilitySchema: z.ZodObject<{
         cli: boolean;
         api: boolean;
         mcp: boolean;
-        streaming: boolean;
         tools: boolean;
+        streaming: boolean;
         screenshots: boolean;
         worktreeSafe: boolean;
     };
@@ -130,8 +130,8 @@ export declare const ProviderCapabilitySchema: z.ZodObject<{
         cli: boolean;
         api: boolean;
         mcp: boolean;
-        streaming: boolean;
         tools: boolean;
+        streaming: boolean;
         screenshots: boolean;
         worktreeSafe: boolean;
     };

package/dist/util/clipboard-image.d.ts

@@ -0,0 +1,49 @@
+/**
+ * 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/
+ */
+export declare const SCREENSHOT_DIR = ".omk/screenshots";
+export declare const MAX_IMAGE_BYTES: number;
+export interface ClipboardImage {
+    ok: boolean;
+    /** Absolute path to the saved PNG/JPG/WebP/GIF file. */
+    path?: string;
+    /** Project-relative path (e.g. .omk/screenshots/2026-06-08/screenshot-....png). */
+    relativePath?: string;
+    /** Base64 data URI suitable for wire protocol image_url. */
+    dataUri?: string;
+    /** Base64 raw (no prefix). */
+    base64?: string;
+    /** Detected extension: png, jpg, webp, gif. */
+    ext?: string;
+    /** Error message when ok=false. */
+    error?: string;
+}
+export declare function detectImageExt(buf: Buffer): string | null;
+export declare function toDataUri(base64: string, ext: string): string;
+/**
+ * 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 declare function readClipboardImage(platform?: NodeJS.Platform): Buffer | null;
+/**
+ * Read clipboard image, validate, save to .omk/screenshots/, and return
+ * both the file path and base64 data URI for wire protocol use.
+ */
+export declare function pasteClipboardImage(projectRoot: string): ClipboardImage;
+/**
+ * Read an image file from disk, validate, and return base64 data URI.
+ * Used for --image <file> flag support.
+ */
+export declare function readImageFile(filePath: string): ClipboardImage;