frely-cli 0.23.10 → 0.23.12

package/dist/agent/local/approvals.js

@@ -1,8 +1,8 @@
 import { ensureDevice } from "../../device/control.js";
 import { openController, resultData, resultText } from "../../controller/client.js";
+import { waitForApproval } from "../../controller/approval-wait.js";
 import { ControllerError, EXIT } from "../../controller/session.js";
 import { approvedHosts } from "./store.js";
-const sleepFor = (ms) => new Promise((done) => setTimeout(done, ms));
 /** When the relay does not say, an approval is taken to last as long as its default window. */
 const DEFAULT_WINDOW_MS = 12 * 3_600_000;
 /** The FrelyMCP resource name for one site. The relay shows it to the owner as "connect to <site>". */
@@ -35,7 +35,6 @@ export async function approveSites(record, io, deps = {}) {
 }
 async function approveSite(controller, device, record, host, io, deps) {
     const now = deps.now ?? Date.now;
-    const sleep = deps.sleep ?? sleepFor;
     const result = await controller.call("request_permission", {
         device, resource: siteResource(host), mode: "window",
         reason: `The local Agent ${record.slug} lists ${host} in its frely.yaml.`.slice(0, 300),
@@ -58,22 +57,19 @@ async function approveSite(controller, device, record, host, io, deps) {
         throw new ControllerError(`Approval needed for ${host}. Open the link above, approve it, then run the same command again.`, EXIT.approval);
     }
     io.err("Waiting for your decision…\n");
-    const deadline = now() + (deps.waitMs ?? 10 * 60_000);
-    for (;;) {
-        const answer = resultData(await controller.call("permission_status", { code }));
-        if (answer?.status === "approved")
-            return typeof answer.expiresAt === "string" ? answer.expiresAt : new Date(now() + DEFAULT_WINDOW_MS).toISOString();
-        if (answer?.status === "denied") {
-            io.err(`${host} was declined; ${record.slug} will run without it.\n`);
-            return undefined;
-        }
-        if (answer?.status === "expired" || answer?.status === "revoked") {
-            io.err(`The request for ${host} ended without an answer; ${record.slug} will run without it.\n`);
-            return undefined;
-        }
-        if (now() + (deps.pollMs ?? 3000) >= deadline)
-            throw new ControllerError(`Still waiting for approval of ${host}. Run the same command again to keep waiting.`, EXIT.approval);
-        await sleep(deps.pollMs ?? 3000);
+    const outcome = await waitForApproval(controller, { code }, deps.waitMs ?? 10 * 60_000, { now, ...(deps.sleep ? { sleep: deps.sleep } : {}), ...(deps.pollMs !== undefined ? { intervalMs: deps.pollMs } : {}) });
+    if (outcome.status === "approved")
+        return typeof outcome.data?.expiresAt === "string" ? outcome.data.expiresAt : new Date(now() + DEFAULT_WINDOW_MS).toISOString();
+    if (outcome.status === "denied") {
+        io.err(`${host} was declined; ${record.slug} will run without it.\n`);
+        return undefined;
+    }
+    if (outcome.status === "expired" || outcome.status === "revoked") {
+        io.err(`The request for ${host} ended without an answer; ${record.slug} will run without it.\n`);
+        return undefined;
     }
+    if (outcome.status === "error")
+        throw new ControllerError(`Could not check the approval of ${host}: ${outcome.message}`, EXIT.tool);
+    throw new ControllerError(`Still waiting for approval of ${host}. Run the same command again to keep waiting.`, EXIT.approval);
 }
 //# sourceMappingURL=approvals.js.map

package/dist/agent/local/approvals.js.map

@@ -1 +1 @@
-{"version":3,"file":"approvals.js","sourceRoot":"","sources":["../../../src/agent/local/approvals.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"approvals.js","sourceRoot":"","sources":["../../../src/agent/local/approvals.ts"],"names":[],"mappings":"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"}

package/dist/agent/run-store.d.ts

@@ -0,0 +1,85 @@
+import type { CallerItem } from "../skill/router.js";
+import type { FileRead } from "./workspace-read.js";
+/** Finished runs are kept this long on this computer, then removed the next time a run starts. */
+export declare const RUN_RETENTION_MS: number;
+export type RunStatus = "running" | "completed" | "failed" | "cancelled" | "interrupted";
+export interface RunRound {
+    readonly n: number;
+    readonly requestId?: string;
+    readonly startedAt: string;
+    readonly endedAt?: string;
+    readonly toolCalls: readonly string[];
+    readonly usage?: Readonly<{
+        input_tokens: number;
+        output_tokens: number;
+        total_tokens: number;
+    }>;
+}
+/** Local record of one `frely agent run`. Full input and output stay on this computer (file mode 0600). */
+export interface RunRecord {
+    readonly version: 1;
+    readonly runId: string;
+    readonly distributionId: string;
+    readonly modelId?: string;
+    readonly status: RunStatus;
+    readonly createdAt: string;
+    readonly updatedAt: string;
+    /** The detached worker that owns the run while it is `running`. */
+    readonly workerPid?: number;
+    readonly task: string;
+    /** Workspace root of `--read`; absent for a plain single call. */
+    readonly readRoot?: string;
+    readonly limits?: Readonly<{
+        totalBytes: number;
+        maxRounds: number;
+    }>;
+    readonly bridge?: Readonly<{
+        usedBytes: number;
+        roundsAnswered: number;
+    }>;
+    readonly items: readonly CallerItem[];
+    readonly rounds: readonly RunRound[];
+    readonly filesRead: readonly FileRead[];
+    readonly usage: Readonly<{
+        input_tokens: number;
+        output_tokens: number;
+        total_tokens: number;
+    }>;
+    readonly resumeCount: number;
+    readonly text?: string;
+    /** `--progress-summary` / `--no-progress-summary`; absent means the account's setting. */
+    readonly progressSummary?: boolean;
+    /** Newest progress line of a running plain call. */
+    readonly progress?: string;
+    /** The Agent could not take local tools, so the run was done as one plain call. */
+    readonly toolsUnsupported?: boolean;
+    readonly error?: Readonly<{
+        code: string;
+        message: string;
+    }>;
+}
+export declare function runsDirectory(): string;
+export declare function isRunId(value: string): boolean;
+export declare function createRun(input: {
+    readonly distributionId: string;
+    readonly task: string;
+    readonly readRoot?: string;
+    readonly limits?: {
+        totalBytes: number;
+        maxRounds: number;
+    };
+    readonly progressSummary?: boolean;
+}): Promise<RunRecord>;
+/** Atomic write: a reader never sees half a record. */
+export declare function writeRun(record: RunRecord): Promise<RunRecord>;
+export declare function readRun(runId: string): Promise<RunRecord | null>;
+export declare function listRuns(): Promise<RunRecord[]>;
+export declare function pruneRuns(now?: number): Promise<void>;
+export declare function processAlive(pid: number | undefined): boolean;
+/** `running` only counts while its worker is alive; otherwise the run was cut off (killed, rebooted) and is `interrupted`. */
+export declare function effectiveStatus(record: RunRecord, now?: number): RunStatus;
+/** A run can continue when a failed or interrupted run still has its Agent and (for `--read`) rounds to resume from. */
+export declare function resumable(record: RunRecord): boolean;
+/** `<id>` or `--last`. */
+export declare function resolveRun(target: string | undefined): Promise<RunRecord>;
+export declare function addUsage(total: RunRecord["usage"], usage: RunRecord["usage"] | undefined): RunRecord["usage"];

package/dist/agent/run-store.js

@@ -0,0 +1,155 @@
+import { randomUUID } from "node:crypto";
+import { chmod, mkdir, readdir, readFile, rename, rm, writeFile } from "node:fs/promises";
+import { homedir } from "node:os";
+import { join } from "node:path";
+/** Finished runs are kept this long on this computer, then removed the next time a run starts. */
+export const RUN_RETENTION_MS = 7 * 24 * 60 * 60 * 1000;
+export function runsDirectory() {
+    return join(process.env.XDG_CONFIG_HOME || join(homedir(), ".config"), "frely", "agent-runs");
+}
+const RUN_ID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/u;
+export function isRunId(value) {
+    return RUN_ID.test(value);
+}
+function runPath(runId) {
+    if (!isRunId(runId))
+        throw new Error("Invalid run id.");
+    return join(runsDirectory(), `${runId}.json`);
+}
+export async function createRun(input) {
+    await mkdir(runsDirectory(), { recursive: true, mode: 0o700 });
+    await chmod(runsDirectory(), 0o700).catch(() => undefined);
+    await pruneRuns().catch(() => undefined);
+    const now = new Date().toISOString();
+    const record = {
+        version: 1,
+        runId: randomUUID(),
+        distributionId: input.distributionId,
+        status: "running",
+        createdAt: now,
+        updatedAt: now,
+        task: input.task,
+        ...(input.readRoot === undefined ? {} : { readRoot: input.readRoot }),
+        ...(input.limits === undefined ? {} : { limits: input.limits }),
+        ...(input.progressSummary === undefined ? {} : { progressSummary: input.progressSummary }),
+        items: [],
+        rounds: [],
+        filesRead: [],
+        usage: { input_tokens: 0, output_tokens: 0, total_tokens: 0 },
+        resumeCount: 0,
+    };
+    await writeRun(record);
+    return record;
+}
+/** Atomic write: a reader never sees half a record. */
+export async function writeRun(record) {
+    const next = { ...record, updatedAt: new Date().toISOString() };
+    const path = runPath(record.runId);
+    const temp = `${path}.${process.pid}.tmp`;
+    await writeFile(temp, `${JSON.stringify(next)}\n`, { mode: 0o600 });
+    // On Windows a rename onto a file another process is reading fails briefly (EPERM/EBUSY/EACCES): retry.
+    for (let attempt = 0;; attempt += 1) {
+        try {
+            await rename(temp, path);
+            return next;
+        }
+        catch (error) {
+            const code = error.code;
+            if (attempt >= 50 || (code !== "EPERM" && code !== "EBUSY" && code !== "EACCES")) {
+                await rm(temp, { force: true });
+                throw error;
+            }
+            await new Promise((resolve) => setTimeout(resolve, 20));
+        }
+    }
+}
+export async function readRun(runId) {
+    let raw;
+    for (let attempt = 0; attempt < 5 && raw === undefined; attempt += 1) {
+        try {
+            raw = await readFile(runPath(runId), "utf8");
+        }
+        catch (error) {
+            if (error.code === "ENOENT")
+                return null;
+            await new Promise((resolve) => setTimeout(resolve, 20));
+        }
+    }
+    if (raw === undefined)
+        return null;
+    try {
+        const value = JSON.parse(raw);
+        return value.version === 1 && value.runId === runId ? value : null;
+    }
+    catch {
+        return null;
+    }
+}
+export async function listRuns() {
+    let names;
+    try {
+        names = await readdir(runsDirectory());
+    }
+    catch {
+        return [];
+    }
+    const records = await Promise.all(names.filter((name) => name.endsWith(".json")).map((name) => readRun(name.slice(0, -5))));
+    return records.filter((record) => record !== null).sort((a, b) => b.createdAt.localeCompare(a.createdAt));
+}
+export async function pruneRuns(now = Date.now()) {
+    for (const record of await listRuns()) {
+        if (record.status !== "running" && now - Date.parse(record.updatedAt) > RUN_RETENTION_MS)
+            await rm(runPath(record.runId), { force: true });
+    }
+}
+export function processAlive(pid) {
+    if (pid === undefined)
+        return false;
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (error) {
+        return error.code === "EPERM";
+    }
+}
+/** `running` only counts while its worker is alive; otherwise the run was cut off (killed, rebooted) and is `interrupted`. */
+export function effectiveStatus(record, now = Date.now()) {
+    if (record.status !== "running")
+        return record.status;
+    // The worker records its pid as its first act; until then the run is only just starting.
+    if (record.workerPid === undefined)
+        return now - Date.parse(record.updatedAt) < WORKER_START_GRACE_MS ? "running" : "interrupted";
+    return processAlive(record.workerPid) ? "running" : "interrupted";
+}
+const WORKER_START_GRACE_MS = 20_000;
+/** A run can continue when a failed or interrupted run still has its Agent and (for `--read`) rounds to resume from. */
+export function resumable(record) {
+    const status = effectiveStatus(record);
+    return (status === "interrupted" || status === "failed") && (record.error?.code ?? "") !== "input_invalid";
+}
+/** `<id>` or `--last`. */
+export async function resolveRun(target) {
+    if (target === undefined || target === "--last") {
+        const [latest] = await listRuns();
+        if (latest === undefined)
+            throw new Error("There are no agent runs on this computer.");
+        return latest;
+    }
+    if (!isRunId(target))
+        throw new Error("Use a run id from `frely agent runs`, or --last.");
+    const record = await readRun(target);
+    if (record === null)
+        throw new Error("This run is not on this computer (runs are removed after 7 days).");
+    return record;
+}
+export function addUsage(total, usage) {
+    if (usage === undefined)
+        return total;
+    return {
+        input_tokens: total.input_tokens + usage.input_tokens,
+        output_tokens: total.output_tokens + usage.output_tokens,
+        total_tokens: total.total_tokens + usage.total_tokens,
+    };
+}
+//# sourceMappingURL=run-store.js.map

package/dist/agent/run-store.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"run-store.js","sourceRoot":"","sources":["../../src/agent/run-store.ts"],"names":[],"mappings":"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"}

package/dist/agent/run.d.ts

@@ -0,0 +1,45 @@
+import { SkillAccessError, type InstalledAgentSession } from "../skill/access.js";
+import { type RunRecord } from "./run-store.js";
+import { type ReadLimits } from "./workspace-read.js";
+export interface RunDeps {
+    openSession(distributionId: string): Promise<InstalledAgentSession>;
+    invokePlain(distributionId: string, task: string, signal: AbortSignal, options?: {
+        progressSummary?: boolean;
+        onProgress?: (sentence: string) => void;
+    }): Promise<{
+        text: string;
+        modelId: string;
+        usage?: Readonly<Record<string, unknown>>;
+    }>;
+    /** Start the detached worker for a run. */
+    spawnWorker(runId: string): void;
+    stderr(text: string): void;
+    pollMs: number;
+}
+export declare const defaultRunDeps: RunDeps;
+/** Create the run record, start the detached worker and wait for the end. The same call also serves `frely agent result --wait`. */
+export declare function startRun(input: {
+    readonly distributionId: string;
+    readonly task: string;
+    readonly read?: {
+        readonly root: string;
+        readonly limits: ReadLimits;
+    };
+    readonly progressSummary?: boolean;
+}, deps?: RunDeps): Promise<RunRecord>;
+/** Poll the local record until the run is no longer running; prints each newly read file to stderr. */
+export declare function waitForRun(runId: string, deps?: Pick<RunDeps, "pollMs" | "stderr">): Promise<RunRecord>;
+/** A finished run as the foreground command reports it: the result, or the error the call would have thrown. */
+export declare function runOutcome(record: RunRecord): Record<string, unknown>;
+export declare function runFailure(record: RunRecord): SkillAccessError;
+/** The state `frely agent result` and `frely agent runs` print for a run (no task text; the result text only when finished). */
+export declare function runSummary(record: RunRecord): Record<string, unknown>;
+export declare function listRunSummaries(): Promise<Record<string, unknown>[]>;
+/** Stop a run: ask its worker to abort the call (the server stops and settles what was used), or mark an orphaned record. */
+export declare function cancelRun(target: string | undefined, deps?: Pick<RunDeps, "pollMs">): Promise<RunRecord>;
+/** Prepare an interrupted or failed run to continue with the items it already has, and start a worker for it. */
+export declare function resumeRun(target: string | undefined, deps?: RunDeps): Promise<RunRecord>;
+/** The worker side: runs the call (and the tool rounds) of one record, saving after every step. */
+export declare function executeRun(runId: string, deps?: RunDeps, signal?: AbortSignal): Promise<void>;
+/** Entry of `frely agent __worker <runId>`: cancel on SIGTERM, ignore the terminal hang-up. */
+export declare function workerMain(runId: string, deps?: RunDeps): Promise<void>;

package/dist/agent/run.js

@@ -0,0 +1,254 @@
+import { spawn } from "node:child_process";
+import { cliLaunchArguments } from "../cli-launch.js";
+import { ClientToolsUnsupportedError, invokeInstalledAgent, openInstalledAgentSession, SkillAccessError, } from "../skill/access.js";
+import { addUsage, createRun, effectiveStatus, listRuns, processAlive, readRun, resolveRun, resumable, writeRun, } from "./run-store.js";
+import { READ_TOOLS, WorkspaceReadBridge } from "./workspace-read.js";
+const MAX_TASK_BYTES = 128 * 1024;
+const OVERVIEW_HEADER = "\n\n---\nLocal workspace (read-only file tools are available: read what you need, do not guess). Readable files:\n";
+export const defaultRunDeps = {
+    openSession: (distributionId) => openInstalledAgentSession({ distributionId }),
+    invokePlain: async (distributionId, task, signal, options) => {
+        const result = await invokeInstalledAgent({
+            distributionId,
+            task,
+            signal,
+            ...(options?.progressSummary === undefined ? {} : { progressSummary: options.progressSummary }),
+            ...(options?.onProgress === undefined ? {} : { onProgress: options.onProgress }),
+        });
+        return { text: result.text, modelId: result.modelId, ...("usage" in result && result.usage ? { usage: result.usage } : {}) };
+    },
+    spawnWorker: (runId) => {
+        // Detached, so Ctrl-C, a host command timeout or a killed parent does not stop the call it is waiting for.
+        const launch = cliLaunchArguments(process.argv[1] ?? "", ["agent", "__worker", runId]);
+        spawn(launch[0], launch.slice(1), { detached: true, stdio: "ignore", windowsHide: true, env: process.env }).unref();
+    },
+    stderr: (text) => { process.stderr.write(text); },
+    pollMs: 400,
+};
+/** Create the run record, start the detached worker and wait for the end. The same call also serves `frely agent result --wait`. */
+export async function startRun(input, deps = defaultRunDeps) {
+    if (!input.task.trim() || Buffer.byteLength(input.task, "utf8") > MAX_TASK_BYTES)
+        throw new SkillAccessError("input_invalid", "Agent input must be non-empty and at most 128 KiB.");
+    const record = await createRun({
+        distributionId: input.distributionId,
+        task: input.task,
+        ...(input.read === undefined ? {} : { readRoot: input.read.root, limits: input.read.limits }),
+        ...(input.progressSummary === undefined ? {} : { progressSummary: input.progressSummary }),
+    });
+    deps.stderr(`Run ${record.runId} started. If this command is cut off the run keeps going: frely agent result ${record.runId} --wait\n`);
+    deps.spawnWorker(record.runId);
+    return waitForRun(record.runId, deps);
+}
+/** Poll the local record until the run is no longer running; prints each newly read file to stderr. */
+export async function waitForRun(runId, deps = defaultRunDeps) {
+    const seen = new Set();
+    while (true) {
+        const record = await readRun(runId);
+        if (record === null)
+            throw new SkillAccessError("remote_call_failed", "The run record is no longer on this computer.");
+        for (const file of record.filesRead) {
+            if (!seen.has(file.path)) {
+                seen.add(file.path);
+                deps.stderr(`read ${file.path}\n`);
+            }
+        }
+        if (effectiveStatus(record) !== "running")
+            return { ...record, status: effectiveStatus(record) };
+        await new Promise((resolve) => setTimeout(resolve, deps.pollMs));
+    }
+}
+/** A finished run as the foreground command reports it: the result, or the error the call would have thrown. */
+export function runOutcome(record) {
+    if (record.status === "completed") {
+        return {
+            ok: true,
+            runId: record.runId,
+            distributionId: record.distributionId,
+            ...(record.modelId === undefined ? {} : { modelId: record.modelId }),
+            text: record.text ?? "",
+            ...(record.readRoot === undefined ? {} : { filesRead: record.filesRead, rounds: record.rounds.length }),
+            ...(record.usage.total_tokens > 0 ? { usage: record.usage } : {}),
+            ...(record.toolsUnsupported === true ? { toolsUnsupported: true } : {}),
+        };
+    }
+    throw runFailure(record);
+}
+export function runFailure(record) {
+    if (record.status === "interrupted") {
+        return new SkillAccessError("remote_call_failed", `The run was interrupted before it finished. Run \`frely agent result ${record.runId} --resume --wait\` to continue it; the interrupted round is billed again.`);
+    }
+    if (record.status === "cancelled")
+        return new SkillAccessError("remote_call_failed", `The run ${record.runId} was cancelled.`);
+    const code = (record.error?.code ?? "remote_call_failed");
+    return new SkillAccessError(code, record.error?.message ?? "The remote Frely Agent call failed.");
+}
+/** The state `frely agent result` and `frely agent runs` print for a run (no task text; the result text only when finished). */
+export function runSummary(record) {
+    const status = effectiveStatus(record);
+    return {
+        ok: status === "running" || status === "completed",
+        runId: record.runId,
+        status,
+        distributionId: record.distributionId,
+        createdAt: record.createdAt,
+        updatedAt: record.updatedAt,
+        rounds: record.rounds.length,
+        filesRead: record.filesRead,
+        usage: record.usage,
+        ...(status === "completed" ? { text: record.text ?? "" } : {}),
+        ...(status === "running" && record.progress !== undefined ? { progress: record.progress } : {}),
+        ...(status === "completed" || record.error === undefined ? {} : { error: record.error }),
+        resumable: resumable(record),
+        ...(status === "running" ? { note: "Still running. Progress so far is listed; run `frely agent result <runId> --wait` to wait for the answer." } : {}),
+    };
+}
+export async function listRunSummaries() {
+    return (await listRuns()).slice(0, 20).map((record) => {
+        const { filesRead, usage, ...rest } = runSummary(record);
+        return { ...rest, filesRead: record.filesRead.length, totalTokens: usage.total_tokens };
+    });
+}
+/** Stop a run: ask its worker to abort the call (the server stops and settles what was used), or mark an orphaned record. */
+export async function cancelRun(target, deps = defaultRunDeps) {
+    const record = await resolveRun(target);
+    if (record.status !== "running")
+        return record;
+    if (processAlive(record.workerPid)) {
+        try {
+            process.kill(record.workerPid, "SIGTERM");
+        }
+        catch { /* it just ended */ }
+        for (let waited = 0; waited < 5000; waited += deps.pollMs) {
+            await new Promise((resolve) => setTimeout(resolve, deps.pollMs));
+            const current = await readRun(record.runId);
+            if (current !== null && current.status !== "running")
+                return current;
+        }
+    }
+    const latest = await readRun(record.runId) ?? record;
+    if (latest.status !== "running")
+        return latest;
+    return writeRun({ ...latest, status: "cancelled" });
+}
+/** Prepare an interrupted or failed run to continue with the items it already has, and start a worker for it. */
+export async function resumeRun(target, deps = defaultRunDeps) {
+    const record = await resolveRun(target);
+    if (!resumable(record))
+        throw new Error(effectiveStatus(record) === "running" ? "This run is still running." : "This run cannot be resumed.");
+    const { error: _error, workerPid: _pid, ...rest } = record;
+    const next = await writeRun({ ...rest, status: "running", resumeCount: record.resumeCount + 1 });
+    deps.stderr(`Resuming run ${record.runId}. The round that was interrupted is billed again.\n`);
+    deps.spawnWorker(record.runId);
+    return next;
+}
+/** The worker side: runs the call (and the tool rounds) of one record, saving after every step. */
+export async function executeRun(runId, deps = defaultRunDeps, signal = new AbortController().signal) {
+    const loaded = await readRun(runId);
+    if (loaded === null || loaded.status !== "running")
+        return;
+    let record = await writeRun({ ...loaded, workerPid: process.pid });
+    const save = async (patch) => { record = await writeRun({ ...record, ...patch }); };
+    try {
+        if (record.readRoot === undefined) {
+            let lastProgress;
+            let pending = Promise.resolve();
+            const result = await deps.invokePlain(record.distributionId, record.task, signal, {
+                ...(record.progressSummary === undefined ? {} : { progressSummary: record.progressSummary }),
+                onProgress: (sentence) => {
+                    if (sentence === lastProgress)
+                        return;
+                    lastProgress = sentence;
+                    // Saved one after another, and before the final write below, so a late line cannot undo the result.
+                    pending = pending.then(() => save({ progress: sentence })).catch(() => undefined);
+                },
+            });
+            await pending;
+            const { progress: _progress, ...withoutProgress } = record;
+            record = await writeRun({ ...withoutProgress, status: "completed", modelId: result.modelId, text: result.text });
+            return;
+        }
+        await runWithTools(record, save, () => record, deps, signal);
+    }
+    catch (error) {
+        if (signal.aborted) {
+            await save({ status: "cancelled" });
+            return;
+        }
+        const code = error instanceof SkillAccessError ? error.code : "remote_call_failed";
+        const message = error instanceof SkillAccessError ? error.message : "The remote Frely Agent call failed.";
+        await save({ status: "failed", error: { code, message } });
+    }
+}
+async function runWithTools(start, save, current, deps, signal) {
+    const limits = start.limits;
+    if (limits === undefined || start.readRoot === undefined)
+        throw new SkillAccessError("input_invalid", "The run has no workspace.");
+    const bridge = await WorkspaceReadBridge.open(start.readRoot, limits);
+    bridge.restore({ usedBytes: start.bridge?.usedBytes ?? 0, roundsAnswered: start.bridge?.roundsAnswered ?? 0, filesRead: start.filesRead });
+    const task = await withOverview(start.task, bridge);
+    const session = await deps.openSession(start.distributionId);
+    await save({ modelId: session.modelId });
+    const hardCap = limits.maxRounds + 3;
+    while (true) {
+        if (signal.aborted)
+            throw new Error("aborted");
+        const items = [...current().items];
+        const pending = unansweredCalls(items);
+        if (pending.length > 0) {
+            const outputs = await bridge.answerRound(pending);
+            for (const output of outputs)
+                items.push({ type: "function_call_output", call_id: output.callId, output: output.output });
+            await save({ items, filesRead: bridge.filesRead(), bridge: { usedBytes: bridge.state().usedBytes, roundsAnswered: bridge.state().roundsAnswered } });
+        }
+        if (current().rounds.length >= hardCap)
+            throw new SkillAccessError("remote_call_failed", "The Agent kept asking for files after the read budget was used up.");
+        const startedAt = new Date().toISOString();
+        let turn;
+        try {
+            turn = await session.turn({ task, tools: READ_TOOLS, items, signal });
+        }
+        catch (error) {
+            if (error instanceof ClientToolsUnsupportedError && current().rounds.length === 0) {
+                // The Agent takes no caller tools: do the plain single call, as if --read had not been given.
+                const result = await deps.invokePlain(start.distributionId, start.task, signal);
+                await save({ status: "completed", modelId: result.modelId, text: result.text, toolsUnsupported: true });
+                return;
+            }
+            throw error;
+        }
+        const round = {
+            n: current().rounds.length + 1,
+            ...(turn.requestId === undefined ? {} : { requestId: turn.requestId }),
+            startedAt,
+            endedAt: new Date().toISOString(),
+            toolCalls: turn.status === "tool_calls" ? turn.calls.map((call) => call.name) : [],
+            ...(turn.usage === undefined ? {} : { usage: turn.usage }),
+        };
+        const usage = addUsage(current().usage, turn.usage);
+        if (turn.status === "completed") {
+            await save({ status: "completed", text: turn.text, rounds: [...current().rounds, round], usage });
+            return;
+        }
+        await save({ rounds: [...current().rounds, round], usage, items: [...items, ...turn.items] });
+    }
+}
+function unansweredCalls(items) {
+    const answered = new Set(items.flatMap((item) => (item.type === "function_call_output" ? [item.call_id] : [])));
+    return items.flatMap((item) => (item.type === "function_call" && !answered.has(item.call_id) ? [{ callId: item.call_id, name: item.name, arguments: item.arguments }] : []));
+}
+/** Task plus the path tree of the readable files, kept inside the 128 KiB input limit. */
+async function withOverview(task, bridge) {
+    const room = MAX_TASK_BYTES - Buffer.byteLength(task, "utf8") - Buffer.byteLength(OVERVIEW_HEADER, "utf8");
+    if (room < 256)
+        return task;
+    const overview = await bridge.overview(Math.min(8 * 1024, room));
+    return overview === "" ? task : `${task}${OVERVIEW_HEADER}${overview}`;
+}
+/** Entry of `frely agent __worker <runId>`: cancel on SIGTERM, ignore the terminal hang-up. */
+export async function workerMain(runId, deps = defaultRunDeps) {
+    const controller = new AbortController();
+    process.on("SIGTERM", () => controller.abort());
+    process.on("SIGHUP", () => undefined);
+    await executeRun(runId, deps, controller.signal);
+}
+//# sourceMappingURL=run.js.map