open-multi-agent-kit 0.78.0

package/dist/util/runtime-profile.js

@@ -0,0 +1,149 @@
+import { join } from "path";
+import { readSimpleToml, getProjectRoot } from "./resource-profile.js";
+const ROLE_DEFAULTS = {
+    coder: { thinking: true, temperature: 0.15, topP: 0.85, variant: "coding" },
+    planner: { thinking: true, temperature: 0.25, topP: 0.9, variant: "deep" },
+    architect: { thinking: true, temperature: 0.25, topP: 0.9, variant: "deep" },
+    reviewer: { thinking: true, temperature: 0.05, topP: 0.75, variant: "standard" },
+    qa: { thinking: true, temperature: 0.05, topP: 0.75, variant: "standard" },
+    security: { thinking: true, temperature: 0.05, topP: 0.75, variant: "standard" },
+    tester: { thinking: true, temperature: 0.05, topP: 0.75, variant: "standard" },
+    explorer: { thinking: true, temperature: 0.2, topP: 0.85, variant: "balanced" },
+    researcher: { thinking: false, temperature: 0.3, topP: 0.9, variant: "fast" },
+    docs: { thinking: false, temperature: 0.3, topP: 0.9, variant: "fast" },
+    merger: { thinking: true, temperature: 0.1, topP: 0.8, variant: "conservative" },
+    release: { thinking: true, temperature: 0.1, topP: 0.8, variant: "conservative" },
+    integrator: { thinking: true, temperature: 0.1, topP: 0.8, variant: "conservative" },
+    "vision-debugger": { thinking: true, temperature: 0.15, topP: 0.85, variant: "vision" },
+};
+let profileCache;
+/**
+ * Resolve a RuntimeProfile for the given agent role.
+ * Merges: role hard-coded defaults → .omk/config.toml [router.profiles.<role>] → env overrides.
+ */
+export async function resolveRuntimeProfile(role) {
+    const defaults = ROLE_DEFAULTS[role] ?? { thinking: true, temperature: 0.2, topP: 0.85, variant: "balanced" };
+    const config = await loadProfileConfig(role);
+    const env = envProfileOverrides();
+    return {
+        ...defaults,
+        ...config,
+        ...env,
+        // Allow env to explicitly disable thinking by string "false"
+        thinking: env.thinking !== undefined ? env.thinking : config.thinking !== undefined ? config.thinking : defaults.thinking,
+    };
+}
+/**
+ * Reset cached profile config (mainly for tests).
+ */
+export function resetRuntimeProfileCache() {
+    profileCache = undefined;
+}
+async function loadProfileConfig(role) {
+    if (!profileCache) {
+        profileCache = await readProfileConfigs();
+    }
+    return profileCache[role] ?? {};
+}
+async function readProfileConfigs() {
+    const path = join(getProjectRoot(), ".omk", "config.toml");
+    const flat = await readSimpleToml(path);
+    const profiles = {};
+    for (const [key, value] of Object.entries(flat)) {
+        const m = key.match(/^router\.profiles\.([A-Za-z0-9_-]+)\.(model|thinking|variant|temperature|topP|top_p|max_output_mb|maxOutputMb)$/);
+        if (!m)
+            continue;
+        const [, role, field] = m;
+        const p = (profiles[role] ??= {});
+        switch (field) {
+            case "model":
+                p.model = value;
+                break;
+            case "thinking":
+                p.thinking = parseBoolean(value);
+                break;
+            case "variant":
+                p.variant = value;
+                break;
+            case "temperature":
+                p.temperature = parseFloatValue(value);
+                break;
+            case "topP":
+            case "top_p":
+                p.topP = parseFloatValue(value);
+                break;
+            case "max_output_mb":
+            case "maxOutputMb":
+                p.maxOutputMb = parseFloatValue(value);
+                break;
+        }
+    }
+    return profiles;
+}
+function envProfileOverrides() {
+    const env = process.env;
+    const result = {};
+    if (env.OMK_MODEL)
+        result.model = env.OMK_MODEL;
+    if (env.OMK_THINKING !== undefined) {
+        const parsed = parseBoolean(env.OMK_THINKING);
+        if (parsed !== undefined)
+            result.thinking = parsed;
+    }
+    if (env.OMK_VARIANT)
+        result.variant = env.OMK_VARIANT;
+    if (env.OMK_TEMPERATURE !== undefined) {
+        const t = parseFloatValue(env.OMK_TEMPERATURE);
+        if (t !== undefined)
+            result.temperature = t;
+    }
+    if (env.OMK_TOP_P !== undefined) {
+        const p = parseFloatValue(env.OMK_TOP_P);
+        if (p !== undefined)
+            result.topP = p;
+    }
+    if (env.OMK_MAX_OUTPUT_MB !== undefined) {
+        const m = parseFloatValue(env.OMK_MAX_OUTPUT_MB);
+        if (m !== undefined)
+            result.maxOutputMb = m;
+    }
+    return result;
+}
+function parseBoolean(value) {
+    const v = value.trim().toLowerCase();
+    if (v === "true" || v === "1" || v === "yes" || v === "on")
+        return true;
+    if (v === "false" || v === "0" || v === "no" || v === "off")
+        return false;
+    return undefined;
+}
+function parseFloatValue(value) {
+    const trimmed = value.trim();
+    if (trimmed === "")
+        return undefined;
+    const n = Number(trimmed);
+    return Number.isFinite(n) ? n : undefined;
+}
+/**
+ * Build CLI args for a profile, filtering by capability.
+ * Unsupported flags are silently omitted (soft fallback).
+ */
+export function buildProfileArgs(profile, caps) {
+    const args = [];
+    if (caps.model && profile.model) {
+        args.push("--model", profile.model);
+    }
+    if (caps.thinking && profile.thinking !== undefined) {
+        args.push(profile.thinking ? "--thinking" : "--no-thinking");
+    }
+    if (caps.temperature && profile.temperature !== undefined) {
+        args.push("--temperature", String(profile.temperature));
+    }
+    if (caps.topP && profile.topP !== undefined) {
+        args.push("--top-p", String(profile.topP));
+    }
+    if (caps.variant && profile.variant) {
+        args.push("--variant", profile.variant);
+    }
+    return args;
+}

package/dist/util/runtime-scope.d.ts

@@ -0,0 +1,2 @@
+import type { OmkRuntimeScope } from "./resource-profile.js";
+export declare function parseRuntimeScopeOption(value: string | undefined, fallback: OmkRuntimeScope, optionName?: string): OmkRuntimeScope;

package/dist/util/runtime-scope.js

@@ -0,0 +1,19 @@
+import { UsageError } from "./cli-contract.js";
+export function parseRuntimeScopeOption(value, fallback, optionName = "--mcp-scope") {
+    const normalized = value?.trim().toLowerCase();
+    if (!normalized)
+        return fallback;
+    if (normalized === "none" || normalized === "off" || normalized === "disabled")
+        return "none";
+    if (normalized === "project" || normalized === "local")
+        return "project";
+    if (normalized === "all" ||
+        normalized === "global" ||
+        normalized === "local-user" ||
+        normalized === "local_user" ||
+        normalized === "personal" ||
+        normalized === "user") {
+        return "all";
+    }
+    throw new UsageError(`Invalid ${optionName}: ${value}. Use all, project, or none.`);
+}

package/dist/util/scoped-agent-file.d.ts

@@ -0,0 +1,47 @@
+import { type OmkRuntimeScope } from "./resource-profile.js";
+export interface AgentCapabilityScopes {
+    mcpScope: OmkRuntimeScope;
+    skillsScope: OmkRuntimeScope;
+    hooksScope: OmkRuntimeScope;
+    mcpNames?: string[];
+    skillNames?: string[];
+    hookNames?: string[];
+    toolNames?: string[];
+    reasoningVariant?: string;
+}
+export interface ScopedSubagentRef {
+    alias: string;
+    path: string;
+    description?: string;
+}
+export interface ScopedAgentFileOptions {
+    baseAgentFile: string;
+    outputFile: string;
+    role: string;
+    name?: string;
+    resources?: AgentCapabilityScopes;
+    systemPromptPath?: string;
+    subagents?: ScopedSubagentRef[];
+}
+export declare const OMK_AGENT_CAPABILITY_FLAGS: readonly ["OMK_MCP_ENABLED", "OMK_SKILLS_ENABLED", "OMK_HOOKS_ENABLED"];
+export declare function capabilityFlagValue(scope: OmkRuntimeScope): "true" | "false";
+export declare function resolveAgentCapabilityScopes(resources?: AgentCapabilityScopes): Promise<AgentCapabilityScopes>;
+export declare function sanitizeAgentFilePart(value: string): string;
+export declare function defaultScopedRoleAgentFile(root: string, runId: string | undefined, role: string, nodeId?: string): string;
+export declare function readBaseAgentExcludeTools(baseAgentFile: string): Promise<string[]>;
+export declare function yamlRelativePath(fromFile: string, toFile: string): string;
+export declare function renderScopedAgentYaml(options: {
+    baseAgentFile: string;
+    outputFile: string;
+    role: string;
+    name?: string;
+    resources: AgentCapabilityScopes;
+    systemPromptPath?: string;
+    subagents?: ScopedSubagentRef[];
+    excludeTools?: string[];
+}): string;
+export declare function writeScopedAgentFile(options: ScopedAgentFileOptions): Promise<string>;
+export declare function readRootAgentSubagents(baseAgentFile: string): Promise<Array<ScopedSubagentRef & {
+    baseAgentFile: string;
+    role: string;
+}>>;

package/dist/util/scoped-agent-file.js

@@ -0,0 +1,121 @@
+import { mkdir, readFile, writeFile } from "fs/promises";
+import { basename, dirname, extname, join, relative, resolve } from "path";
+import { createHash } from "crypto";
+import YAML from "yaml";
+import { getOmkResourceSettings } from "./resource-profile.js";
+export const OMK_AGENT_CAPABILITY_FLAGS = [
+    "OMK_MCP_ENABLED",
+    "OMK_SKILLS_ENABLED",
+    "OMK_HOOKS_ENABLED",
+];
+export function capabilityFlagValue(scope) {
+    return scope === "none" ? "false" : "true";
+}
+function scopedCapabilityEnabled(scope, names) {
+    return scope !== "none" || normalizeHintValues(names ?? []).length > 0 ? "true" : "false";
+}
+export async function resolveAgentCapabilityScopes(resources) {
+    if (resources)
+        return resources;
+    const settings = await getOmkResourceSettings();
+    return {
+        mcpScope: settings.mcpScope,
+        skillsScope: settings.skillsScope,
+        hooksScope: settings.hooksScope,
+    };
+}
+export function sanitizeAgentFilePart(value) {
+    return value.trim().replace(/[^A-Za-z0-9._-]+/g, "-").replace(/^-+|-+$/g, "") || "agent";
+}
+export function defaultScopedRoleAgentFile(root, runId, role, nodeId) {
+    const suffix = nodeId ? `-${sanitizeAgentFilePart(nodeId)}` : "";
+    return join(root, ".omk", "runs", sanitizeAgentFilePart(runId ?? `runtime-${process.pid}`), "agents", "roles", `${sanitizeAgentFilePart(role)}${suffix}.yaml`);
+}
+export async function readBaseAgentExcludeTools(baseAgentFile) {
+    const raw = await readFile(baseAgentFile, "utf-8");
+    const doc = YAML.parse(raw);
+    const agent = (doc?.agent ?? {});
+    const excludeTools = (agent.exclude_tools ?? []);
+    return Array.isArray(excludeTools) ? excludeTools : [];
+}
+export function yamlRelativePath(fromFile, toFile) {
+    const rel = relative(dirname(fromFile), toFile).replace(/\\/g, "/");
+    return rel.startsWith(".") ? rel : `./${rel}`;
+}
+export function renderScopedAgentYaml(options) {
+    const lines = [
+        "version: 1",
+        "agent:",
+        `  extend: ${JSON.stringify(yamlRelativePath(options.outputFile, options.baseAgentFile))}`,
+        `  name: ${JSON.stringify(options.name ?? `omk-${options.role}`)}`,
+    ];
+    if (options.systemPromptPath) {
+        lines.push(`  system_prompt_path: ${JSON.stringify(options.systemPromptPath)}`);
+    }
+    lines.push("  system_prompt_args:", `    OMK_ROLE: ${JSON.stringify(options.role)}`, `    OMK_MCP_ENABLED: "${scopedCapabilityEnabled(options.resources.mcpScope, options.resources.mcpNames)}"`, `    OMK_SKILLS_ENABLED: "${scopedCapabilityEnabled(options.resources.skillsScope, options.resources.skillNames)}"`, `    OMK_HOOKS_ENABLED: "${scopedCapabilityEnabled(options.resources.hooksScope, options.resources.hookNames)}"`, `    OMK_MCP_HINTS: ${JSON.stringify(renderCapabilityHint(options.resources.mcpNames ?? [], options.resources.mcpScope))}`, `    OMK_SKILL_HINTS: ${JSON.stringify(renderCapabilityHint(options.resources.skillNames ?? [], options.resources.skillsScope))}`, `    OMK_TOOL_HINTS: ${JSON.stringify(renderCapabilityHint(options.resources.toolNames ?? [], "project"))}`, `    OMK_HOOK_HINTS: ${JSON.stringify(renderCapabilityHint(options.resources.hookNames ?? [], options.resources.hooksScope))}`, `    OMK_CONTEXT_BUDGET: "small"`, `    OMK_REASONING_VARIANT: ${JSON.stringify(options.resources.reasoningVariant ?? "balanced-medium")}`, `    OMK_ROUTE_READ_ONLY: "false"`);
+    if (options.excludeTools?.length) {
+        lines.push("  exclude_tools:");
+        for (const tool of options.excludeTools) {
+            lines.push(`    - ${JSON.stringify(tool)}`);
+        }
+    }
+    if (options.subagents?.length) {
+        lines.push("  subagents:");
+        for (const subagent of options.subagents) {
+            lines.push(`    ${subagent.alias}:`);
+            lines.push(`      path: ${JSON.stringify(subagent.path)}`);
+            if (subagent.description) {
+                lines.push(`      description: ${JSON.stringify(subagent.description)}`);
+            }
+        }
+    }
+    lines.push("");
+    return lines.join("\n");
+}
+function renderCapabilityHint(values, scope) {
+    const normalized = normalizeHintValues(values);
+    if (scope === "none" && normalized.length === 0)
+        return "disabled";
+    if (normalized.length === 0)
+        return "count=0;digest=000000000000";
+    return `count=${normalized.length};digest=${hintDigest(normalized)};top=${normalized.slice(0, 3).join("|")}`;
+}
+function normalizeHintValues(values) {
+    return [...new Set(values.map((value) => value.trim()).filter(Boolean).map((value) => value.slice(0, 120)))].sort();
+}
+function hintDigest(values) {
+    return createHash("sha256").update(values.join("\n")).digest("hex").slice(0, 12);
+}
+export async function writeScopedAgentFile(options) {
+    const resources = await resolveAgentCapabilityScopes(options.resources);
+    const excludeTools = await readBaseAgentExcludeTools(options.baseAgentFile);
+    await mkdir(dirname(options.outputFile), { recursive: true });
+    await writeFile(options.outputFile, renderScopedAgentYaml({ ...options, resources, excludeTools }), "utf-8");
+    return options.outputFile;
+}
+export async function readRootAgentSubagents(baseAgentFile) {
+    const raw = await readFile(baseAgentFile, "utf-8");
+    const doc = YAML.parse(raw);
+    const agent = (doc?.agent ?? {});
+    const subagents = (agent.subagents ?? {});
+    const refs = [];
+    for (const [alias, value] of Object.entries(subagents)) {
+        if (!value || typeof value !== "object")
+            continue;
+        const entry = value;
+        const rawPath = typeof entry.path === "string" ? entry.path : undefined;
+        if (!rawPath)
+            continue;
+        const absolute = resolve(dirname(baseAgentFile), rawPath);
+        const extension = extname(absolute);
+        const role = basename(absolute, extension);
+        refs.push({
+            alias,
+            path: rawPath,
+            description: typeof entry.description === "string" ? entry.description : undefined,
+            baseAgentFile: absolute,
+            role,
+        });
+    }
+    return refs;
+}

package/dist/util/screenshot-store.d.ts

@@ -0,0 +1,35 @@
+export declare const SCREENSHOT_DIR = ".omk/screenshots";
+export declare const MAX_SIZE_BYTES: number;
+export interface ScreenshotResult {
+    ok: boolean;
+    path?: string;
+    relativePath?: string;
+    error?: string;
+}
+export interface PasteScreenshotOptions {
+    platform?: NodeJS.Platform | string;
+    env?: NodeJS.ProcessEnv;
+    timeoutMs?: number;
+    procVersion?: string;
+}
+export declare function validateMagicBytes(buf: Buffer): {
+    ok: boolean;
+    ext: string;
+};
+export declare function buildWindowsClipboardImageScript(): string;
+export declare function getWindowsClipboardImageCommands(env?: NodeJS.ProcessEnv): string[];
+export declare function isWslEnvironment(env?: NodeJS.ProcessEnv, procVersion?: string): boolean;
+export declare function pasteScreenshot(projectRoot?: string, options?: PasteScreenshotOptions): ScreenshotResult;
+export declare function getScreenshotDir(projectRoot?: string): string;
+export interface ScreenshotEntry {
+    relativePath: string;
+    fullPath: string;
+    size: number;
+    mtimeMs: number;
+}
+export declare function listScreenshots(projectRoot?: string): ScreenshotEntry[];
+export interface CleanResult {
+    deleted: string[];
+    skipped: string[];
+}
+export declare function cleanScreenshots(days: number, dryRun: boolean, projectRoot?: string): CleanResult;

package/dist/util/screenshot-store.js

@@ -0,0 +1,310 @@
+/**
+ * Screenshot store — cross-platform clipboard image reader with safe project-relative paths.
+ *
+ * All images are saved under .omk/screenshots/YYYY-MM-DD/ so they stay
+ * gitignored and organized by date.
+ */
+import { execFileSync } from "node:child_process";
+import { writeFileSync, mkdirSync, readFileSync, readdirSync, statSync, existsSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join, relative } from "node:path";
+import { createHash } from "node:crypto";
+import { getProjectRoot } from "./fs.js";
+export const SCREENSHOT_DIR = ".omk/screenshots";
+export const MAX_SIZE_BYTES = 20 * 1024 * 1024;
+const CLIPBOARD_TIMEOUT_MS = 5000;
+const CLIPBOARD_MAX_BUFFER_BYTES = MAX_SIZE_BYTES * 2;
+const IMAGE_MAGIC = new Map([
+    ["png", [0x89, 0x50, 0x4e, 0x47]],
+    ["jpg", [0xff, 0xd8, 0xff]],
+    ["webp", [0x52, 0x49, 0x46, 0x46]], // RIFF
+    ["gif", [0x47, 0x49, 0x46, 0x38]], // GIF8
+]);
+export function validateMagicBytes(buf) {
+    for (const [ext, magic] of IMAGE_MAGIC) {
+        if (buf.length >= magic.length && magic.every((b, i) => buf[i] === b)) {
+            return { ok: true, ext };
+        }
+    }
+    return { ok: false, ext: "" };
+}
+function generateScreenshotPath(projectRoot, ext) {
+    const now = new Date();
+    const dateDir = now.toISOString().slice(0, 10);
+    const timestamp = now.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 };
+}
+function saveScreenshot(data, ext, projectRoot) {
+    if (data.length > MAX_SIZE_BYTES) {
+        return { ok: false, error: `Image exceeds ${MAX_SIZE_BYTES / (1024 * 1024)} MB limit` };
+    }
+    const magic = validateMagicBytes(data);
+    if (!magic.ok) {
+        return { ok: false, error: "Clipboard does not contain a valid image (PNG/JPG/WebP/GIF)" };
+    }
+    const { fullPath, relativePath } = generateScreenshotPath(projectRoot, magic.ext);
+    writeFileSync(fullPath, data);
+    return { ok: true, path: fullPath, relativePath: `./${relativePath}` };
+}
+// ---------------------------------------------------------------------------
+// Windows provider
+// ---------------------------------------------------------------------------
+export function buildWindowsClipboardImageScript() {
+    return `
+$ErrorActionPreference = 'Stop'
+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]::Out.Write([Convert]::ToBase64String($Bytes))
+  exit 0
+}
+
+$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 }
+    }
+  }
+
+  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))
+      }
+    }
+  }
+}
+
+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
+`;
+}
+export function getWindowsClipboardImageCommands(env = process.env) {
+    const explicit = env.OMK_WINDOWS_POWERSHELL_PATH?.trim();
+    const candidates = explicit
+        ? [explicit]
+        : [
+            "powershell.exe",
+            "pwsh.exe",
+            "/mnt/c/Windows/System32/WindowsPowerShell/v1.0/powershell.exe",
+        ];
+    return [...new Set(candidates.filter((cmd) => cmd.length > 0))];
+}
+function execWindowsClipboardScript(command, options = {}) {
+    const encoded = Buffer.from(buildWindowsClipboardImageScript(), "utf16le").toString("base64");
+    return execFileSync(command, ["-NoProfile", "-STA", "-EncodedCommand", encoded], {
+        encoding: "utf-8",
+        timeout: options.timeoutMs ?? CLIPBOARD_TIMEOUT_MS,
+        maxBuffer: CLIPBOARD_MAX_BUFFER_BYTES,
+        windowsHide: true,
+        env: options.env ? { ...process.env, ...options.env } : process.env,
+    }).trim();
+}
+function readWindowsClipboard(projectRoot, options = {}) {
+    let lastError = "No image in clipboard";
+    for (const command of getWindowsClipboardImageCommands(options.env)) {
+        try {
+            const b64 = execWindowsClipboardScript(command, options);
+            const buf = Buffer.from(b64, "base64");
+            if (buf.length === 0) {
+                lastError = "No image in clipboard";
+                continue;
+            }
+            return saveScreenshot(buf, "png", projectRoot);
+        }
+        catch (e) {
+            lastError = e instanceof Error ? e.message : String(e);
+        }
+    }
+    return { ok: false, error: lastError };
+}
+// ---------------------------------------------------------------------------
+// macOS provider
+// ---------------------------------------------------------------------------
+function readMacOSClipboard(projectRoot, options = {}) {
+    // Try pngpaste first (more reliable)
+    try {
+        const tmpPath = join(tmpdir(), `omk-screenshot-${Date.now()}.png`);
+        execFileSync("pngpaste", [tmpPath], { timeout: options.timeoutMs ?? CLIPBOARD_TIMEOUT_MS });
+        const buf = readFileSync(tmpPath);
+        if (buf.length === 0) {
+            return { ok: false, error: "No image in clipboard" };
+        }
+        return saveScreenshot(buf, "png", projectRoot);
+    }
+    catch {
+        // Fallback to osascript
+        try {
+            const tmpPath = join(tmpdir(), `omk-screenshot-${Date.now()}.png`);
+            const script = `
+        set pngData to the clipboard as «class PNGf»
+        set f to open for access POSIX file "${tmpPath}" with write permission
+        write pngData to f
+        close access f
+      `;
+            execFileSync("osascript", ["-e", script], { encoding: "utf-8", timeout: options.timeoutMs ?? CLIPBOARD_TIMEOUT_MS });
+            const buf = readFileSync(tmpPath);
+            if (buf.length === 0) {
+                return { ok: false, error: "No image in clipboard" };
+            }
+            return saveScreenshot(buf, "png", projectRoot);
+        }
+        catch (e) {
+            return { ok: false, error: e.message };
+        }
+    }
+}
+// ---------------------------------------------------------------------------
+// Linux / WSL provider
+// ---------------------------------------------------------------------------
+export function isWslEnvironment(env = process.env, procVersion) {
+    if (env.WSL_DISTRO_NAME || env.WSLENV || env.WSL_INTEROP)
+        return true;
+    const version = procVersion ?? (() => {
+        try {
+            return readFileSync("/proc/version", "utf-8");
+        }
+        catch {
+            return "";
+        }
+    })();
+    return /microsoft|wsl/i.test(version);
+}
+function readLinuxClipboard(projectRoot, options = {}) {
+    let wslError;
+    if (isWslEnvironment(options.env, options.procVersion)) {
+        const windowsResult = readWindowsClipboard(projectRoot, options);
+        if (windowsResult.ok)
+            return windowsResult;
+        wslError = windowsResult.error;
+    }
+    try {
+        let buf;
+        try {
+            buf = execFileSync("wl-paste", ["--type", "image/png"], {
+                timeout: options.timeoutMs ?? CLIPBOARD_TIMEOUT_MS,
+                encoding: "buffer",
+                maxBuffer: CLIPBOARD_MAX_BUFFER_BYTES,
+            });
+        }
+        catch {
+            buf = execFileSync("xclip", ["-selection", "clipboard", "-t", "image/png", "-o"], {
+                timeout: options.timeoutMs ?? CLIPBOARD_TIMEOUT_MS,
+                encoding: "buffer",
+                maxBuffer: CLIPBOARD_MAX_BUFFER_BYTES,
+            });
+        }
+        if (buf.length === 0) {
+            return { ok: false, error: "No image in clipboard" };
+        }
+        return saveScreenshot(buf, "png", projectRoot);
+    }
+    catch (e) {
+        const linuxError = e instanceof Error ? e.message : String(e);
+        const error = wslError ? `Windows clipboard unavailable (${wslError}); Linux clipboard unavailable (${linuxError})` : linuxError;
+        return { ok: false, error };
+    }
+}
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+export function pasteScreenshot(projectRoot, options = {}) {
+    const root = projectRoot ?? getProjectRoot();
+    const platform = options.platform ?? process.platform;
+    if (platform === "win32") {
+        return readWindowsClipboard(root, options);
+    }
+    if (platform === "darwin") {
+        return readMacOSClipboard(root, options);
+    }
+    return readLinuxClipboard(root, options);
+}
+export function getScreenshotDir(projectRoot) {
+    const root = projectRoot ?? getProjectRoot();
+    return join(root, SCREENSHOT_DIR);
+}
+export function listScreenshots(projectRoot) {
+    const root = projectRoot ?? getProjectRoot();
+    const base = join(root, SCREENSHOT_DIR);
+    if (!existsSync(base))
+        return [];
+    const entries = [];
+    for (const dateDir of readdirSync(base)) {
+        const datePath = join(base, dateDir);
+        const stat = statSync(datePath, { throwIfNoEntry: false });
+        if (!stat || !stat.isDirectory())
+            continue;
+        for (const file of readdirSync(datePath)) {
+            const fullPath = join(datePath, file);
+            const s = statSync(fullPath, { throwIfNoEntry: false });
+            if (!s || !s.isFile())
+                continue;
+            entries.push({
+                relativePath: relative(root, fullPath).replace(/\\/g, "/"),
+                fullPath,
+                size: s.size,
+                mtimeMs: s.mtimeMs,
+            });
+        }
+    }
+    return entries.sort((a, b) => b.mtimeMs - a.mtimeMs);
+}
+export function cleanScreenshots(days, dryRun, projectRoot) {
+    const root = projectRoot ?? getProjectRoot();
+    const base = join(root, SCREENSHOT_DIR);
+    if (!existsSync(base))
+        return { deleted: [], skipped: [] };
+    const cutoff = Date.now() - days * 24 * 60 * 60 * 1000;
+    const result = { deleted: [], skipped: [] };
+    for (const dateDir of readdirSync(base)) {
+        const datePath = join(base, dateDir);
+        const stat = statSync(datePath, { throwIfNoEntry: false });
+        if (!stat || !stat.isDirectory())
+            continue;
+        for (const file of readdirSync(datePath)) {
+            const fullPath = join(datePath, file);
+            const s = statSync(fullPath, { throwIfNoEntry: false });
+            if (!s || !s.isFile())
+                continue;
+            if (s.mtimeMs < cutoff) {
+                if (!dryRun) {
+                    rmSync(fullPath);
+                }
+                result.deleted.push(relative(root, fullPath).replace(/\\/g, "/"));
+            }
+            else {
+                result.skipped.push(relative(root, fullPath).replace(/\\/g, "/"));
+            }
+        }
+        // Remove empty date directories
+        if (!dryRun && readdirSync(datePath).length === 0) {
+            rmSync(datePath, { recursive: true });
+        }
+    }
+    return result;
+}