@melaya/runner 1.1.68 → 1.1.70

package/dist/detect.d.ts

@@ -2,4 +2,43 @@ export interface DetectedModel {
     provider: "lmstudio" | "ollama" | "claude_code" | "codex" | "github_copilot";
     name: string;
 }
-export declare function detectModels(): Promise<DetectedModel[]>;
+/** Per-probe deadlines (ms). Local servers answer in milliseconds when up. */
+export declare const PROBE_TIMEOUTS_MS: {
+    readonly lmstudio: 2500;
+    readonly ollama: 2500;
+    readonly claude_code: 9000;
+    readonly codex: 3000;
+    readonly github_copilot: 13000;
+};
+/** Test seam. */
+export declare function _clearDetectCaches(): void;
+export type ProviderId = DetectedModel["provider"];
+export interface ProviderScan {
+    /** Models in a stable provider order: lmstudio, ollama, claude_code, codex, github_copilot. */
+    models: DetectedModel[];
+    /** Local servers answering right now (a server with zero models still counts). */
+    running: {
+        lmstudio: boolean;
+        ollama: boolean;
+    };
+    /** Per-provider probe duration, and which probes hit their deadline. */
+    probeMs: Record<ProviderId, number>;
+    timedOut: ProviderId[];
+    /** Wall time of the whole scan. */
+    ms: number;
+    at: number;
+}
+export interface ScanOptions {
+    /** Bypass the per-credential network cache (a user-triggered refresh). */
+    force?: boolean;
+    /** Override per-probe deadlines (tests). */
+    timeouts?: Partial<Record<ProviderId, number>>;
+}
+/** Scan every provider in parallel. Concurrent callers share one scan. */
+export declare function scanProviders(opts?: ScanOptions): Promise<ProviderScan>;
+/** The last completed scan, when it is younger than maxAgeMs. */
+export declare function cachedScan(maxAgeMs: number): ProviderScan | null;
+/** Models only (kept for existing callers). Same parallel scan as scanProviders(). */
+export declare function detectModels(opts?: ScanOptions): Promise<DetectedModel[]>;
+/** Fingerprint of the local provider state (files + ports). No network, no subprocess. */
+export declare function providerFingerprint(): Promise<string>;

package/dist/detect.js

@@ -4,18 +4,21 @@
  */
 import { execFile } from "child_process";
 import { promisify } from "util";
-import { readFile } from "fs/promises";
+import { readFile, stat } from "fs/promises";
+import { createHash } from "crypto";
 import { homedir } from "os";
 import { join } from "path";
 const execFileAsync = promisify(execFile);
 // Fallback ONLY when the live /models fetch fails. Must be ENABLED-by-default
 // Copilot models (policy!=disabled) — Claude/Gemini default to disabled and 400.
-const COPILOT_MODELS_FALLBACK = ["gpt-4.1", "gpt-4o", "gpt-5-mini"];
+// gpt-4o / gpt-4.1 / gpt-5-mini are retired from Copilot (github.blog changelog,
+// 2026-10-19); GitHub names GPT-6 Luna as the GPT-5 mini replacement.
+const COPILOT_MODELS_FALLBACK = ["gpt-6-luna"];
 /** Fallbacks used ONLY when live discovery fails (offline runner, transient
  *  error, missing cache). The REAL lists are fetched dynamically below so a new
  *  claude/codex release is available on Melaya automatically — no code change,
  *  no redeploy. Kept minimal + in step with the registry `staticModels`. */
-const CODEX_MODELS_FALLBACK = ["gpt-5.6-sol", "gpt-5.6-terra", "gpt-5.6-luna", "gpt-5.5", "gpt-5.4", "gpt-5.4-mini"];
+const CODEX_MODELS_FALLBACK = ["gpt-6.1-sol", "gpt-6-astra", "gpt-6-sol", "gpt-6-luna", "gpt-5.6-sol", "gpt-5.6-terra", "gpt-5.6-luna"];
 const CLAUDE_ALIASES_FALLBACK = ["sonnet", "opus", "fable", "haiku"];
 /** Discover the claude model FAMILIES this subscription serves, so a new
  *  family (a future tier) appears on Melaya automatically. Hits the same
@@ -24,7 +27,10 @@ const CLAUDE_ALIASES_FALLBACK = ["sonnet", "opus", "fable", "haiku"];
  *  to their family aliases (opus/sonnet/haiku/…). Each alias resolves to the
  *  NEWEST model of its family at call time, so within-family releases are picked
  *  up for free too. Best-effort: any failure falls back to the known aliases. */
-async function fetchClaudeFamilies(token) {
+async function fetchClaudeFamilies(token, force = false) {
+    const cached = networkCacheGet(`claude:${tokenKey(token)}`, force);
+    if (cached)
+        return cached;
     try {
         const r = await fetch("https://api.anthropic.com/v1/models?limit=100", {
             headers: {
@@ -45,7 +51,7 @@ async function fetchClaudeFamilies(token) {
                     fams.add(mm[1]);
             }
             if (fams.size)
-                return [...fams];
+                return networkCacheSet(`claude:${tokenKey(token)}`, [...fams]);
         }
     }
     catch { /* offline / transient → fallback */ }
@@ -80,7 +86,7 @@ async function readCodexModels() {
  *  of truth on Windows/Linux; macOS keeps the grant in the Keychain, where
  *  `security` is a subprocess but pops NO window. Zero windows, faster, and
  *  it mirrors exactly what the runtime (model.py `_read_claude_oauth`) reads. */
-async function detectClaudeCode() {
+async function detectClaudeCode(force = false) {
     let raw = null;
     try {
         raw = await readFile(join(homedir(), ".claude", ".credentials.json"), "utf8");
@@ -102,7 +108,7 @@ async function detectClaudeCode() {
         const oauth = (JSON.parse(raw)?.claudeAiOauth ?? {});
         const expiresAt = Number(oauth.expiresAt ?? 0);
         if (oauth.accessToken && (!expiresAt || Date.now() < expiresAt)) {
-            const names = await fetchClaudeFamilies(oauth.accessToken);
+            const names = await fetchClaudeFamilies(oauth.accessToken, force);
             return names.map((name) => ({ provider: "claude_code", name }));
         }
     }
@@ -178,10 +184,21 @@ async function readGithubCopilotToken() {
  *  is present on THIS machine, exchange it for a short-lived Copilot token and
  *  list the models the subscription serves, so the picker shows TRUE local
  *  availability (copilot pipelines execute HERE, same as claude_code/codex). */
-async function detectGithubCopilot() {
+async function detectGithubCopilot(force = false) {
     const gh = await readGithubCopilotToken();
     if (!gh)
         return [];
+    const key = `copilot:${tokenKey(gh)}`;
+    const cached = networkCacheGet(key, force);
+    if (cached)
+        return cached;
+    const result = await detectGithubCopilotWith(gh);
+    if (result)
+        networkCacheSet(key, result);
+    return result ?? [];
+}
+/** The Copilot token exchange + model list. null = offline / transient (not cached). */
+async function detectGithubCopilotWith(gh) {
     try {
         const ex = await fetch("https://api.github.com/copilot_internal/v2/token", {
             headers: {
@@ -232,37 +249,178 @@ async function detectGithubCopilot() {
         return COPILOT_MODELS_FALLBACK.map((name) => ({ provider: "github_copilot", name }));
     }
     catch { /* offline / transient → not advertised */ }
-    return [];
+    return null;
+}
+// ── One parallel provider scan ─────────────────────────────────────────────
+// Every provider is probed at the same time, each under its own deadline, so
+// the whole scan costs the slowest probe (not their sum: up to ~24 s before).
+// One scan returns both the models and whether the local servers answer, so
+// callers do not probe LM Studio / Ollama a second time.
+//
+// Authenticated network calls (Claude model families, the Copilot token
+// exchange) are cached per credential for NETWORK_CACHE_MS: a periodic rescan
+// with unchanged credentials only re-reads local files and localhost servers.
+// A new or changed credential (different token) misses the cache at once.
+/** Per-probe deadlines (ms). Local servers answer in milliseconds when up. */
+export const PROBE_TIMEOUTS_MS = {
+    lmstudio: 2500,
+    ollama: 2500,
+    claude_code: 9000,
+    codex: 3000,
+    github_copilot: 13000,
+};
+const NETWORK_CACHE_MS = 6 * 60 * 60_000;
+const networkCache = new Map();
+function tokenKey(token) {
+    return createHash("sha256").update(token).digest("hex").slice(0, 16);
+}
+function networkCacheGet(key, force) {
+    if (force)
+        return null;
+    const hit = networkCache.get(key);
+    if (!hit || Date.now() - hit.at > NETWORK_CACHE_MS)
+        return null;
+    return hit.value;
+}
+function networkCacheSet(key, value) {
+    networkCache.set(key, { at: Date.now(), value });
+    return value;
+}
+/** Test seam. */
+export function _clearDetectCaches() {
+    networkCache.clear();
+    lastScan = null;
+}
+function withDeadline(p, ms, fallback) {
+    return new Promise((resolve) => {
+        let done = false;
+        const t = setTimeout(() => { if (!done) {
+            done = true;
+            resolve({ value: fallback, timedOut: true });
+        } }, ms);
+        p.then((v) => { if (!done) {
+            done = true;
+            clearTimeout(t);
+            resolve({ value: v, timedOut: false });
+        } }, () => { if (!done) {
+            done = true;
+            clearTimeout(t);
+            resolve({ value: fallback, timedOut: false });
+        } });
+    });
 }
-export async function detectModels() {
-    const models = [];
-    // LM Studio — OpenAI-compatible at :1234
+async function probeLocalServer(url, timeoutMs, pick) {
     try {
-        const r = await fetch("http://127.0.0.1:1234/v1/models", { signal: AbortSignal.timeout(3000) });
-        if (r.ok) {
-            const d = (await r.json());
-            for (const m of d.data ?? []) {
-                models.push({ provider: "lmstudio", name: m.id });
-            }
-        }
+        const r = await fetch(url, { signal: AbortSignal.timeout(timeoutMs) });
+        if (!r.ok)
+            return { up: false, names: [] };
+        const d = await r.json().catch(() => ({}));
+        return { up: true, names: pick(d) };
     }
-    catch { /* not running */ }
-    // Ollama at :11434
+    catch {
+        return { up: false, names: [] };
+    }
+}
+let lastScan = null;
+let scanInFlight = null;
+/** Scan every provider in parallel. Concurrent callers share one scan. */
+export function scanProviders(opts = {}) {
+    if (scanInFlight && !opts.force)
+        return scanInFlight;
+    const p = runScan(opts).finally(() => { if (scanInFlight === p)
+        scanInFlight = null; });
+    scanInFlight = p;
+    return p;
+}
+/** The last completed scan, when it is younger than maxAgeMs. */
+export function cachedScan(maxAgeMs) {
+    return lastScan && Date.now() - lastScan.at <= maxAgeMs ? lastScan : null;
+}
+async function runScan(opts) {
+    const t0 = Date.now();
+    const to = { ...PROBE_TIMEOUTS_MS, ...(opts.timeouts ?? {}) };
+    const force = !!opts.force;
+    const probeMs = {};
+    const timedOut = [];
+    const timed = async (id, p, fallback) => {
+        const s = Date.now();
+        const r = await withDeadline(p, to[id], fallback);
+        probeMs[id] = Date.now() - s;
+        if (r.timedOut)
+            timedOut.push(id);
+        return r.value;
+    };
+    const down = { up: false, names: [] };
+    const [lm, ol, claude, codex, copilot] = await Promise.all([
+        // LM Studio: OpenAI-compatible at :1234
+        timed("lmstudio", probeLocalServer("http://127.0.0.1:1234/v1/models", to.lmstudio, (d) => (d?.data ?? []).map((m) => m.id)), down),
+        // Ollama at :11434
+        timed("ollama", probeLocalServer("http://127.0.0.1:11434/api/tags", to.ollama, (d) => (d?.models ?? []).map((m) => m.name)), down),
+        // Claude Code CLI: subscription auth on THIS machine
+        timed("claude_code", detectClaudeCode(force), []),
+        // OpenAI Codex CLI: subscription auth on THIS machine
+        timed("codex", detectCodex(), []),
+        // GitHub Copilot: GitHub OAuth token readable on THIS machine
+        timed("github_copilot", detectGithubCopilot(force), []),
+    ]);
+    const models = [
+        ...lm.names.map((name) => ({ provider: "lmstudio", name })),
+        ...ol.names.map((name) => ({ provider: "ollama", name })),
+        ...claude,
+        ...codex,
+        ...copilot,
+    ];
+    const scan = { models, running: { lmstudio: lm.up, ollama: ol.up }, probeMs, timedOut, ms: Date.now() - t0, at: Date.now() };
+    lastScan = scan;
+    return scan;
+}
+/** Models only (kept for existing callers). Same parallel scan as scanProviders(). */
+export async function detectModels(opts = {}) {
+    return (await scanProviders(opts)).models;
+}
+// ── Change detection for periodic rescans ──────────────────────────────────
+// A cheap fingerprint of everything a scan depends on: credential / cache file
+// mtimes and whether the local server ports accept a connection. Unchanged
+// fingerprint + a recent scan = nothing to rescan.
+const FINGERPRINT_FILES = [
+    [".claude", ".credentials.json"],
+    [".codex", "auth.json"],
+    [".codex", "models_cache.json"],
+    [".config", "github-copilot", "apps.json"],
+    [".config", "github-copilot", "hosts.json"],
+    [".melaya-runner", "github_copilot.json"],
+];
+async function fileStamp(path) {
     try {
-        const r = await fetch("http://127.0.0.1:11434/api/tags", { signal: AbortSignal.timeout(3000) });
-        if (r.ok) {
-            const d = (await r.json());
-            for (const m of d.models ?? []) {
-                models.push({ provider: "ollama", name: m.name });
-            }
-        }
+        const st = await stat(path);
+        return `${st.mtimeMs}:${st.size}`;
+    }
+    catch {
+        return "-";
     }
-    catch { /* not running */ }
-    // Claude Code CLI — subscription auth on THIS machine
-    models.push(...await detectClaudeCode());
-    // OpenAI Codex CLI — subscription auth on THIS machine
-    models.push(...await detectCodex());
-    // GitHub Copilot — GitHub OAuth token readable on THIS machine
-    models.push(...await detectGithubCopilot());
-    return models;
+}
+async function portOpen(port, timeoutMs = 400) {
+    const { createConnection } = await import("net");
+    return new Promise((resolve) => {
+        const sock = createConnection({ host: "127.0.0.1", port });
+        const done = (v) => { try {
+            sock.destroy();
+        }
+        catch { /* closed */ } resolve(v); };
+        sock.setTimeout(timeoutMs, () => done(false));
+        sock.once("connect", () => done(true));
+        sock.once("error", () => done(false));
+    });
+}
+/** Fingerprint of the local provider state (files + ports). No network, no subprocess. */
+export async function providerFingerprint() {
+    const home = homedir();
+    const parts = await Promise.all([
+        ...FINGERPRINT_FILES.map((rel) => fileStamp(join(home, ...rel))),
+        portOpen(1234).then((v) => (v ? "lm:up" : "lm:down")),
+        portOpen(11434).then((v) => (v ? "ol:up" : "ol:down")),
+    ]);
+    parts.push(process.env.GH_TOKEN ? `gh:${tokenKey(process.env.GH_TOKEN)}` : "gh:-");
+    parts.push(process.env.GITHUB_TOKEN ? `ghx:${tokenKey(process.env.GITHUB_TOKEN)}` : "ghx:-");
+    return parts.join("|");
 }

package/dist/hostChannel.d.ts

@@ -0,0 +1,126 @@
+/**
+ * Host channel: the runner running inside the Melaya desktop app.
+ *
+ * The desktop app (desktop/src/main/runnerHost.ts) starts this runner in an
+ * Electron utilityProcess. There, `process.parentPort` is a message port to the
+ * app's main process; under plain Node (`npx @melaya/runner`) it is undefined
+ * and every function here is a no-op, so the CLI behaves exactly as before.
+ *
+ * The runner token arrives as the first host message ({ type: "start", token })
+ * and never through argv or env, so it does not show up in process listings.
+ *
+ * The message types below MIRROR packages/desktop-contract/src/index.ts
+ * (RunnerToHostMessage / HostToRunnerMessage) and src/computer.ts. The runner
+ * build (tsc, rootDir src) cannot import that package, so keep both in step.
+ */
+export type HostedRunnerState = "starting" | "online" | "reconnecting" | "blocked" | "error";
+/** Why a terminal "error" happened, so the app can react without parsing text. */
+export type HostedStatusCode = "token_rejected" | "server_disconnect";
+/** Mirror of the contract's RunnerToHostMessage (computer messages kept loose). */
+export type RunnerToHostMessage = {
+    type: "status";
+    state: HostedRunnerState;
+    lastError?: string;
+    code?: HostedStatusCode;
+} | {
+    type: "log";
+    level: "info" | "warn" | "error";
+    line: string;
+} | {
+    type: "version";
+    runnerVersion: string;
+}
+/** Additive (runner side first; the contract mirror is the coordinator's): startup stage offsets in ms from process start. */
+ | {
+    type: "timings";
+    stages: Partial<Record<"process_start" | "config" | "socket_connected" | "online" | "python_ready" | "discovery_done", number>>;
+}
+/** Additive: background setup progress. `waiting` = a request is waiting for this task to finish. */
+ | {
+    type: "progress";
+    task: "runtime_setup";
+    state: "running" | "done" | "failed";
+    step?: string;
+    waiting?: boolean;
+} | {
+    type: "computer.command";
+    id: string;
+    action: unknown;
+    deadlineMs: number;
+    allowedAppIds: string[];
+    allowedApps?: Array<{
+        appId: string;
+        tier: "view" | "click" | "full";
+        expiresAt?: string;
+    }>;
+} | {
+    type: "computer.stop";
+    reason: string;
+} | {
+    type: "computer.capabilities.request";
+} | {
+    type: "computer.file";
+    path: string;
+    name: string;
+    origin: "download" | "output";
+    handleHint?: string;
+} | {
+    type: "computer.approval.request";
+    approvalId: string;
+    summary: string;
+    effect: string;
+    appName?: string;
+    expiresAt: string;
+} | {
+    type: "computer.approval.closed";
+    approvalId: string;
+}
+/** Additive: something the user must fix on this computer; the app shows it natively. */
+ | {
+    type: "notice";
+    code: "browser_not_installed";
+};
+/** Mirror of the contract's HostToRunnerMessage (computer messages kept loose). */
+export type HostToRunnerMessage = {
+    type: "stop";
+} | {
+    type: "start";
+    token: string;
+}
+/** Additive: rescan model providers now and publish the list through runner:models. */
+ | {
+    type: "rescan_models";
+} | {
+    type: "computer.result";
+    id: string;
+    result: unknown;
+} | {
+    type: "computer.capabilities";
+    capabilities: unknown;
+} | {
+    type: "computer.approval.answer";
+    approvalId: string;
+    decision: "approve" | "decline";
+};
+/** True when this runner was started by the Melaya desktop app. */
+export declare function isHosted(): boolean;
+/** Send one message to the desktop app. No-op outside the app; never throws. */
+export declare function sendToHost(msg: RunnerToHostMessage): void;
+/** Subscribe to messages from the desktop app. Returns an unsubscribe function. */
+export declare function onHostMessage(cb: (msg: HostToRunnerMessage) => void): () => void;
+/** Strip anything token-shaped from a reason before it leaves the process. */
+export declare function redactReason(s: string): string;
+/** Report a state change to the desktop app. No-op outside the app. */
+export declare function hostStatus(state: HostedRunnerState, lastError?: string, code?: HostedStatusCode): void;
+/** Background setup progress for the desktop app. No-op outside the app. */
+export declare function hostProgress(state: "running" | "done" | "failed", step?: string, waiting?: boolean): void;
+/**
+ * Wait for the token from the desktop app. Resolves with the token, or rejects
+ * when nothing valid arrives within `timeoutMs`.
+ */
+export declare function waitForHostToken(timeoutMs?: number): Promise<string>;
+/**
+ * Exit after giving the last host message time to leave the process. The
+ * parentPort queue is asynchronous; exiting in the same tick can drop it.
+ */
+export declare function exitHostedSoon(code: number, delayMs?: number): void;

package/dist/hostChannel.js

@@ -0,0 +1,117 @@
+/**
+ * Host channel: the runner running inside the Melaya desktop app.
+ *
+ * The desktop app (desktop/src/main/runnerHost.ts) starts this runner in an
+ * Electron utilityProcess. There, `process.parentPort` is a message port to the
+ * app's main process; under plain Node (`npx @melaya/runner`) it is undefined
+ * and every function here is a no-op, so the CLI behaves exactly as before.
+ *
+ * The runner token arrives as the first host message ({ type: "start", token })
+ * and never through argv or env, so it does not show up in process listings.
+ *
+ * The message types below MIRROR packages/desktop-contract/src/index.ts
+ * (RunnerToHostMessage / HostToRunnerMessage) and src/computer.ts. The runner
+ * build (tsc, rootDir src) cannot import that package, so keep both in step.
+ */
+function parentPort() {
+    const p = process.parentPort;
+    return p && typeof p.postMessage === "function" ? p : null;
+}
+/** True when this runner was started by the Melaya desktop app. */
+export function isHosted() {
+    return parentPort() !== null;
+}
+/** Send one message to the desktop app. No-op outside the app; never throws. */
+export function sendToHost(msg) {
+    const p = parentPort();
+    if (!p)
+        return;
+    try {
+        p.postMessage(msg);
+    }
+    catch { /* host gone: nothing to tell */ }
+}
+/** Subscribe to messages from the desktop app. Returns an unsubscribe function. */
+export function onHostMessage(cb) {
+    const p = parentPort();
+    if (!p)
+        return () => { };
+    const listener = (e) => {
+        const data = e?.data;
+        if (!data || typeof data !== "object" || typeof data.type !== "string")
+            return;
+        try {
+            cb(data);
+        }
+        catch { /* a bad handler must not kill the runner */ }
+    };
+    p.on("message", listener);
+    return () => {
+        try {
+            if (typeof p.removeListener === "function")
+                p.removeListener("message", listener);
+            else if (typeof p.off === "function")
+                p.off("message", listener);
+        }
+        catch { /* ignore */ }
+    };
+}
+/** Strip anything token-shaped from a reason before it leaves the process. */
+export function redactReason(s) {
+    return String(s || "")
+        .replace(/mel_run_[A-Za-z0-9_\-]+/g, "mel_run_[redacted]")
+        .replace(/\b(bearer)\s+[A-Za-z0-9._~+/=\-]+/gi, "$1 [redacted]")
+        .replace(/\beyJ[A-Za-z0-9_\-]{5,}\.[A-Za-z0-9_\-]{5,}\.[A-Za-z0-9_\-]{5,}/g, "[jwt redacted]")
+        .replace(/([?&](?:token|code|state|key)=)[^&\s]+/gi, "$1[redacted]")
+        .slice(0, 300);
+}
+/** Report a state change to the desktop app. No-op outside the app. */
+export function hostStatus(state, lastError, code) {
+    if (!isHosted())
+        return;
+    sendToHost({
+        type: "status",
+        state,
+        ...(lastError ? { lastError: redactReason(lastError) } : {}),
+        ...(code ? { code } : {}),
+    });
+}
+/** Background setup progress for the desktop app. No-op outside the app. */
+export function hostProgress(state, step, waiting) {
+    if (!isHosted())
+        return;
+    sendToHost({
+        type: "progress",
+        task: "runtime_setup",
+        state,
+        ...(step ? { step: redactReason(step).slice(0, 120) } : {}),
+        ...(waiting ? { waiting: true } : {}),
+    });
+}
+/**
+ * Wait for the token from the desktop app. Resolves with the token, or rejects
+ * when nothing valid arrives within `timeoutMs`.
+ */
+export function waitForHostToken(timeoutMs = 30_000) {
+    return new Promise((resolve, reject) => {
+        let off = () => { };
+        const timer = setTimeout(() => { off(); reject(new Error("the desktop app did not send a runner token")); }, timeoutMs);
+        off = onHostMessage((msg) => {
+            if (msg.type !== "start")
+                return;
+            const token = msg.token;
+            if (typeof token !== "string" || !token.startsWith("mel_run_"))
+                return;
+            clearTimeout(timer);
+            off();
+            resolve(token);
+        });
+    });
+}
+/**
+ * Exit after giving the last host message time to leave the process. The
+ * parentPort queue is asynchronous; exiting in the same tick can drop it.
+ */
+export function exitHostedSoon(code, delayMs = 300) {
+    setTimeout(() => process.exit(code), delayMs);
+}

package/dist/hostFiles.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Files this runner produced on the computer, reported to the Melaya desktop
+ * app (contract ComputerRunnerFileMessage, { type: "computer.file" }) so
+ * computer control can open them or pick them in a file dialog by handle.
+ *
+ * Only inside the desktop app (hostChannel.isHosted()); under `npx` every
+ * function here is a no-op. The path goes to the app's main process over the
+ * parentPort and never to the server: the app turns it into an opaque handle.
+ *
+ * Sources: Assistant turn output files (after assistantFiles.ts accepted them)
+ * and pipeline outputs written to MELAYA_OUTPUT_DIR during a run. Browser
+ * downloads are denied by the browser bridge (acceptDownloads: false), so there
+ * is nothing to report from there.
+ */
+/** At most this many files per run, so a tool that writes thousands of files cannot flood the host. */
+export declare const MAX_REPORTED_PER_RUN = 25;
+/** Report one file. Returns true when a message was sent. */
+export declare function reportHostFile(path: string, origin: "download" | "output"): boolean;
+/**
+ * Files in `dir` (and one level of sub-folders) modified at or after `sinceMs`,
+ * newest first, capped. Pure apart from reading the folder.
+ */
+export declare function filesWrittenSince(dir: string, sinceMs: number, max?: number): string[];
+/** After a run: report the outputs it wrote. No-op outside the desktop app. */
+export declare function reportOutputsSince(dir: string | undefined, sinceMs: number): number;