frely-cli 0.23.9 → 0.23.11

package/dist/agent/local/source.d.ts

@@ -0,0 +1,28 @@
+/** Where an Agent's code comes from: a Frely Agent page (`username/name`) or a public GitHub repository. */
+export type AgentSource = {
+    kind: "frely";
+    user: string;
+    name: string;
+} | {
+    kind: "github";
+    owner: string;
+    repo: string;
+};
+export declare class SourceError extends Error {
+    constructor(message: string);
+}
+export declare function parseSource(target: string): AgentSource;
+export declare const githubUrl: (source: {
+    owner: string;
+    repo: string;
+}) => string;
+/** The public record a Frely Agent page keeps for its repository. */
+export interface RegisteredRepo {
+    repoUrl: string;
+    commit: string | undefined;
+    name: string | undefined;
+}
+/** Reads the repository the Agent's author registered on Frely. The commit is the one the author listed. */
+export declare function resolveRegisteredRepo(user: string, name: string, relayUrl: string, fetchFn?: typeof fetch): Promise<RegisteredRepo>;
+/** Downloads `repoUrl` into the empty-or-missing `dir`, at `commit` when one is given, else at the default branch. Returns the commit that is checked out. */
+export declare function download(repoUrl: string, dir: string, commit: string | undefined): Promise<string>;

package/dist/agent/local/source.js

@@ -0,0 +1,64 @@
+import { execFile } from "node:child_process";
+import { mkdir } from "node:fs/promises";
+import { dirname } from "node:path";
+import { promisify } from "node:util";
+const run = promisify(execFile);
+export class SourceError extends Error {
+    constructor(message) { super(message); this.name = "SourceError"; }
+}
+const FRELY_PART = /^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$/u;
+const GITHUB_URL = /^https:\/\/github\.com\/([A-Za-z0-9][A-Za-z0-9-]{0,38})\/([A-Za-z0-9._-]{1,100}?)(?:\.git)?\/?$/u;
+const COMMIT = /^[0-9a-f]{40}$/u;
+export function parseSource(target) {
+    const github = GITHUB_URL.exec(target);
+    if (github)
+        return { kind: "github", owner: github[1], repo: github[2] };
+    const [user, name, extra] = target.replace(/^@/u, "").split("/");
+    if (user !== undefined && name !== undefined && extra === undefined && FRELY_PART.test(user) && FRELY_PART.test(name))
+        return { kind: "frely", user, name };
+    throw new SourceError("Use a Frely Agent name such as username/name, or a public GitHub address such as https://github.com/owner/repo.");
+}
+export const githubUrl = (source) => `https://github.com/${source.owner}/${source.repo}`;
+/** Reads the repository the Agent's author registered on Frely. The commit is the one the author listed. */
+export async function resolveRegisteredRepo(user, name, relayUrl, fetchFn = fetch) {
+    const response = await fetchFn(`${relayUrl}/api/public/agent-repos/${encodeURIComponent(user)}/${encodeURIComponent(name)}`, { headers: { accept: "application/json" }, redirect: "error", signal: AbortSignal.timeout(15_000) });
+    if (response.status === 404)
+        throw new SourceError(`${user}/${name} is not a Frely Agent with a repository.`);
+    if (!response.ok)
+        throw new SourceError(`Frely could not look up ${user}/${name} (HTTP ${response.status}).`);
+    const body = await response.json().catch(() => null);
+    if (!body || typeof body.repoUrl !== "string" || !GITHUB_URL.test(body.repoUrl))
+        throw new SourceError(`Frely returned no usable repository for ${user}/${name}.`);
+    const commit = typeof body.commit === "string" && COMMIT.test(body.commit) ? body.commit : undefined;
+    return { repoUrl: body.repoUrl.replace(/\.git$/u, "").replace(/\/$/u, ""), commit, name: typeof body.name === "string" ? body.name : undefined };
+}
+/** git with no prompts, no hooks, no submodules and https only: the repository is untrusted. */
+async function git(args, cwd) {
+    const safe = ["-c", "protocol.allow=never", "-c", "protocol.https.allow=always", "-c", "core.hooksPath=/dev/null", "-c", "core.fsmonitor=false", "-c", "submodule.recurse=false"];
+    try {
+        const { stdout } = await run("git", [...safe, ...args], { cwd, env: { ...process.env, GIT_TERMINAL_PROMPT: "0", GIT_CONFIG_NOSYSTEM: "1" }, timeout: 5 * 60_000, maxBuffer: 4 * 1024 * 1024 });
+        return stdout.trim();
+    }
+    catch (error) {
+        const stderr = error.stderr?.trim().split("\n").slice(-3).join(" ");
+        throw new SourceError(`git ${args[0]} failed${stderr ? `: ${stderr}` : "."}`);
+    }
+}
+/** Downloads `repoUrl` into the empty-or-missing `dir`, at `commit` when one is given, else at the default branch. Returns the commit that is checked out. */
+export async function download(repoUrl, dir, commit) {
+    await mkdir(dirname(dir), { recursive: true });
+    if (commit) {
+        await mkdir(dir, { recursive: true });
+        await git(["init", "--quiet"], dir);
+        await git(["fetch", "--quiet", "--depth", "1", "--no-tags", "--no-recurse-submodules", repoUrl, commit], dir);
+        await git(["checkout", "--quiet", "FETCH_HEAD"], dir);
+    }
+    else {
+        await git(["clone", "--quiet", "--depth", "1", "--no-tags", "--single-branch", "--no-recurse-submodules", repoUrl, dir], undefined);
+    }
+    const head = await git(["rev-parse", "HEAD"], dir);
+    if (!COMMIT.test(head))
+        throw new SourceError("git did not report a commit.");
+    return head;
+}
+//# sourceMappingURL=source.js.map

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

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

package/dist/agent/local/store.d.ts

@@ -0,0 +1,45 @@
+/**
+ * What is known about one Agent running on this computer. It lives with Frely's own files, not in the Agent's folder: the sandbox
+ * cannot read or write there, so the program it runs cannot change which sites it was approved for.
+ */
+export interface LocalAgentRecord {
+    version: 1;
+    slug: string;
+    /** What the person typed: `username/name` or a GitHub address. */
+    source: string;
+    repoUrl: string;
+    commit: string;
+    name: string;
+    workspace: string;
+    setup: string | undefined;
+    run: string;
+    /** Sites from frely.yaml, asked for when the Agent is added and started. */
+    network: string[];
+    addedAt: string;
+    setupDone: boolean;
+    /** Approved site -> when the approval ends (ISO time). */
+    approvals: Record<string, string>;
+    pid: number | undefined;
+    startedAt: string | undefined;
+}
+export declare const SLUG: RegExp;
+/** Records, logs and sockets: `~/.config/frely/agent-local`. */
+export declare const stateDir: () => string;
+/** One folder per Agent, the only place its program can write besides the system temp folder. */
+export declare const agentsRoot: () => string;
+export declare function assertSlug(slug: string): void;
+export declare const workspaceOf: (slug: string) => string;
+export declare const recordPath: (slug: string) => string;
+export declare const logPath: (slug: string) => string;
+/** Short enough for the ~100 character limit of a Unix socket path. */
+export declare const socketPath: (slug: string) => string;
+/** Whether `path` is inside the Agents folder (and not the folder itself), so a removal can never reach anything else. */
+export declare function insideAgentsRoot(path: string): boolean;
+export declare function readRecord(slug: string): Promise<LocalAgentRecord | undefined>;
+export declare function writeRecord(record: LocalAgentRecord): Promise<void>;
+export declare function listRecords(): Promise<LocalAgentRecord[]>;
+export declare function removeRecordFiles(slug: string): Promise<void>;
+/** Whether the process the record names is still running. */
+export declare function isRunning(record: Pick<LocalAgentRecord, "pid">): boolean;
+/** Approvals that have not ended yet, as a site list. */
+export declare function approvedHosts(record: Pick<LocalAgentRecord, "approvals" | "network">, now?: number): string[];

package/dist/agent/local/store.js

@@ -0,0 +1,78 @@
+import { createHash } from "node:crypto";
+import { chmod, mkdir, readFile, readdir, rename, rm, writeFile } from "node:fs/promises";
+import { homedir } from "node:os";
+import { join, resolve, sep } from "node:path";
+export const SLUG = /^[a-z0-9][a-z0-9-]{0,62}$/u;
+const configRoot = () => process.env.XDG_CONFIG_HOME || join(homedir(), ".config");
+/** Records, logs and sockets: `~/.config/frely/agent-local`. */
+export const stateDir = () => join(configRoot(), "frely", "agent-local");
+/** One folder per Agent, the only place its program can write besides the system temp folder. */
+export const agentsRoot = () => resolve(process.env.FRELY_AGENTS_DIR || join(homedir(), "frely-agents"));
+export function assertSlug(slug) {
+    if (!SLUG.test(slug))
+        throw new Error("The Agent name must be lower-case letters, digits and dashes.");
+}
+export const workspaceOf = (slug) => join(agentsRoot(), slug);
+export const recordPath = (slug) => join(stateDir(), `${slug}.json`);
+export const logPath = (slug) => join(stateDir(), `${slug}.log`);
+/** Short enough for the ~100 character limit of a Unix socket path. */
+export const socketPath = (slug) => join(process.env.XDG_RUNTIME_DIR || stateDir(), `m-${createHash("sha256").update(slug).digest("hex").slice(0, 10)}.sock`);
+/** Whether `path` is inside the Agents folder (and not the folder itself), so a removal can never reach anything else. */
+export function insideAgentsRoot(path) {
+    const root = agentsRoot();
+    const target = resolve(path);
+    return target !== root && target.startsWith(root.endsWith(sep) ? root : root + sep);
+}
+export async function readRecord(slug) {
+    assertSlug(slug);
+    const raw = await readFile(recordPath(slug), "utf8").catch(() => undefined);
+    if (raw === undefined)
+        return undefined;
+    try {
+        const value = JSON.parse(raw);
+        return value.version === 1 && value.slug === slug && typeof value.run === "string" ? value : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+export async function writeRecord(record) {
+    await mkdir(stateDir(), { recursive: true, mode: 0o700 });
+    const target = recordPath(record.slug);
+    const temp = `${target}.${process.pid}.tmp`;
+    await writeFile(temp, JSON.stringify(record, null, 2) + "\n", { mode: 0o600 });
+    await rename(temp, target);
+    await chmod(target, 0o600).catch(() => undefined);
+}
+export async function listRecords() {
+    const names = await readdir(stateDir()).catch(() => []);
+    const records = [];
+    for (const name of names.filter((file) => file.endsWith(".json")).sort()) {
+        const record = await readRecord(name.slice(0, -5)).catch(() => undefined);
+        if (record)
+            records.push(record);
+    }
+    return records;
+}
+export async function removeRecordFiles(slug) {
+    await rm(recordPath(slug), { force: true });
+    await rm(logPath(slug), { force: true });
+    await rm(socketPath(slug), { force: true });
+}
+/** Whether the process the record names is still running. */
+export function isRunning(record) {
+    if (record.pid === undefined)
+        return false;
+    try {
+        process.kill(record.pid, 0);
+        return true;
+    }
+    catch (error) {
+        return error.code === "EPERM";
+    }
+}
+/** Approvals that have not ended yet, as a site list. */
+export function approvedHosts(record, now = Date.now()) {
+    return record.network.filter((host) => { const end = record.approvals[host]; return end !== undefined && Date.parse(end) > now; });
+}
+//# sourceMappingURL=store.js.map

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

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

package/dist/agent/local/supervisor.d.ts

@@ -0,0 +1,9 @@
+export declare class SupervisorError extends Error {
+    constructor(message: string);
+}
+/**
+ * Runs one Agent until it exits or this process is told to stop: the model proxy on a Unix socket, then the Agent's `local.run`
+ * inside the sandbox with only Frely's gateway, the proxy name and the approved sites reachable. Everything the program prints goes to
+ * this process's output, which `frely agent local start` points at the Agent's log file.
+ */
+export declare function superviseAgent(slug: string): Promise<number>;

package/dist/agent/local/supervisor.js

@@ -0,0 +1,62 @@
+import { requireLogin } from "../../auth.js";
+import { terminateProcessTree } from "../../runtime/process-tree.js";
+import { restrictSandboxNetwork, shutdownSandbox } from "../../runtime/sandbox.js";
+import { agentEnv, gatewayOrigin, readApiKey, spawnConfined } from "./confine.js";
+import { MODEL_HOST, startModelProxy } from "./model-proxy.js";
+import { approvedHosts, readRecord, socketPath, writeRecord } from "./store.js";
+export class SupervisorError extends Error {
+    constructor(message) { super(message); this.name = "SupervisorError"; }
+}
+/**
+ * Runs one Agent until it exits or this process is told to stop: the model proxy on a Unix socket, then the Agent's `local.run`
+ * inside the sandbox with only Frely's gateway, the proxy name and the approved sites reachable. Everything the program prints goes to
+ * this process's output, which `frely agent local start` points at the Agent's log file.
+ */
+export async function superviseAgent(slug) {
+    const record = await readRecord(slug);
+    if (!record)
+        throw new SupervisorError(`No local Agent named ${slug}. Add it with frely agent local add.`);
+    if (!record.setupDone)
+        throw new SupervisorError(`${slug} was not set up yet. Run frely agent local add again to finish.`);
+    const login = await requireLogin().catch(() => { throw new SupervisorError("Frely login is required. Run `frely login`."); });
+    const origin = gatewayOrigin(login.config.relayUrl);
+    const apiKey = await readApiKey(origin);
+    if (!apiKey)
+        throw new SupervisorError(`${slug} needs a Frely API key for its model calls. Create one at ${login.config.relayUrl}/user/keys, then run: frely agent local key --api-key-stdin`);
+    const sites = approvedHosts(record);
+    const skipped = record.network.filter((host) => !sites.includes(host));
+    if (skipped.length > 0)
+        process.stderr.write(`Not approved, so blocked: ${skipped.join(", ")}. Run frely agent local start ${slug} again to ask.\n`);
+    const socket = socketPath(slug);
+    restrictSandboxNetwork({ allowedDomains: [new URL(origin).hostname, MODEL_HOST, ...sites], mitmProxy: { socketPath: socket, domains: [MODEL_HOST] } });
+    const proxy = await startModelProxy({ socketPath: socket, upstream: origin, authorization: async () => `Bearer ${apiKey}` });
+    let confined;
+    try {
+        confined = await spawnConfined(record.run, record.workspace, agentEnv(record.workspace, { model: true }));
+    }
+    catch (error) {
+        await proxy.close();
+        await shutdownSandbox();
+        throw error;
+    }
+    const { child } = confined;
+    child.stdout?.pipe(process.stdout, { end: false });
+    child.stderr?.pipe(process.stderr, { end: false });
+    await writeRecord({ ...record, pid: process.pid, startedAt: new Date().toISOString() });
+    process.stderr.write(`[frely] ${slug} started${sites.length ? `; sites: ${sites.join(", ")}` : ""}\n`);
+    const stop = () => { void terminateProcessTree(child); };
+    process.once("SIGTERM", stop);
+    process.once("SIGINT", stop);
+    const code = await new Promise((done) => { child.once("error", () => done(1)); child.once("close", (exit) => done(exit ?? 1)); });
+    const blocked = confined.violations();
+    if (blocked.length > 0)
+        process.stderr.write(`[frely] The sandbox blocked:\n${[...new Set(blocked)].slice(0, 10).join("\n")}\n`);
+    await proxy.close();
+    await shutdownSandbox();
+    const latest = await readRecord(slug);
+    if (latest)
+        await writeRecord({ ...latest, pid: undefined, startedAt: undefined });
+    process.stderr.write(`[frely] ${slug} stopped (exit ${code}).\n`);
+    return code;
+}
+//# sourceMappingURL=supervisor.js.map

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

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

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

@@ -0,0 +1,80 @@
+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;
+    /** 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;
+    };
+}): 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,154 @@
+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 }),
+        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,41 @@
+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): 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;
+    };
+}, 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>;