frely-cli 0.23.9 → 0.23.10

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":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AACzC,OAAO,EAAE,KAAK,EAAE,KAAK,EAAE,QAAQ,EAAE,OAAO,EAAE,MAAM,EAAE,EAAE,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAC;AAC1F,OAAO,EAAE,OAAO,EAAE,MAAM,SAAS,CAAC;AAClC,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,GAAG,EAAE,MAAM,WAAW,CAAC;AA2B/C,MAAM,CAAC,MAAM,IAAI,GAAG,4BAA4B,CAAC;AAEjD,MAAM,UAAU,GAAG,GAAW,EAAE,CAAC,OAAO,CAAC,GAAG,CAAC,eAAe,IAAI,IAAI,CAAC,OAAO,EAAE,EAAE,SAAS,CAAC,CAAC;AAC3F,gEAAgE;AAChE,MAAM,CAAC,MAAM,QAAQ,GAAG,GAAW,EAAE,CAAC,IAAI,CAAC,UAAU,EAAE,EAAE,OAAO,EAAE,aAAa,CAAC,CAAC;AACjF,iGAAiG;AACjG,MAAM,CAAC,MAAM,UAAU,GAAG,GAAW,EAAE,CAAC,OAAO,CAAC,OAAO,CAAC,GAAG,CAAC,gBAAgB,IAAI,IAAI,CAAC,OAAO,EAAE,EAAE,cAAc,CAAC,CAAC,CAAC;AAEjH,MAAM,UAAU,UAAU,CAAC,IAAY;IACrC,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC;QAAE,MAAM,IAAI,KAAK,CAAC,+DAA+D,CAAC,CAAC;AACzG,CAAC;AAED,MAAM,CAAC,MAAM,WAAW,GAAG,CAAC,IAAY,EAAU,EAAE,CAAC,IAAI,CAAC,UAAU,EAAE,EAAE,IAAI,CAAC,CAAC;AAC9E,MAAM,CAAC,MAAM,UAAU,GAAG,CAAC,IAAY,EAAU,EAAE,CAAC,IAAI,CAAC,QAAQ,EAAE,EAAE,GAAG,IAAI,OAAO,CAAC,CAAC;AACrF,MAAM,CAAC,MAAM,OAAO,GAAG,CAAC,IAAY,EAAU,EAAE,CAAC,IAAI,CAAC,QAAQ,EAAE,EAAE,GAAG,IAAI,MAAM,CAAC,CAAC;AACjF,uEAAuE;AACvE,MAAM,CAAC,MAAM,UAAU,GAAG,CAAC,IAAY,EAAU,EAAE,CAAC,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,eAAe,IAAI,QAAQ,EAAE,EAAE,KAAK,UAAU,CAAC,QAAQ,CAAC,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,OAAO,CAAC,CAAC;AAE9K,0HAA0H;AAC1H,MAAM,UAAU,gBAAgB,CAAC,IAAY;IAC3C,MAAM,IAAI,GAAG,UAAU,EAAE,CAAC;IAC1B,MAAM,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC7B,OAAO,MAAM,KAAK,IAAI,IAAI,MAAM,CAAC,UAAU,CAAC,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,GAAG,GAAG,CAAC,CAAC;AACtF,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,UAAU,CAAC,IAAY;IAC3C,UAAU,CAAC,IAAI,CAAC,CAAC;IACjB,MAAM,GAAG,GAAG,MAAM,QAAQ,CAAC,UAAU,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,SAAS,CAAC,CAAC;IAC5E,IAAI,GAAG,KAAK,SAAS;QAAE,OAAO,SAAS,CAAC;IACxC,IAAI,CAAC;QACH,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAqB,CAAC;QAClD,OAAO,KAAK,CAAC,OAAO,KAAK,CAAC,IAAI,KAAK,CAAC,IAAI,KAAK,IAAI,IAAI,OAAO,KAAK,CAAC,GAAG,KAAK,QAAQ,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,SAAS,CAAC;IACzG,CAAC;IAAC,MAAM,CAAC;QAAC,OAAO,SAAS,CAAC;IAAC,CAAC;AAC/B,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,WAAW,CAAC,MAAwB;IACxD,MAAM,KAAK,CAAC,QAAQ,EAAE,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,IAAI,EAAE,KAAK,EAAE,CAAC,CAAC;IAC1D,MAAM,MAAM,GAAG,UAAU,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;IACvC,MAAM,IAAI,GAAG,GAAG,MAAM,IAAI,OAAO,CAAC,GAAG,MAAM,CAAC;IAC5C,MAAM,SAAS,CAAC,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,MAAM,EAAE,IAAI,EAAE,CAAC,CAAC,GAAG,IAAI,EAAE,EAAE,IAAI,EAAE,KAAK,EAAE,CAAC,CAAC;IAC/E,MAAM,MAAM,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;IAC3B,MAAM,KAAK,CAAC,MAAM,EAAE,KAAK,CAAC,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,SAAS,CAAC,CAAC;AACpD,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,WAAW;IAC/B,MAAM,KAAK,GAAG,MAAM,OAAO,CAAC,QAAQ,EAAE,CAAC,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,EAAc,CAAC,CAAC;IACpE,MAAM,OAAO,GAAuB,EAAE,CAAC;IACvC,KAAK,MAAM,IAAI,IAAI,KAAK,CAAC,MAAM,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC;QACzE,MAAM,MAAM,GAAG,MAAM,UAAU,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,SAAS,CAAC,CAAC;QAC1E,IAAI,MAAM;YAAE,OAAO,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;IACnC,CAAC;IACD,OAAO,OAAO,CAAC;AACjB,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,iBAAiB,CAAC,IAAY;IAClD,MAAM,EAAE,CAAC,UAAU,CAAC,IAAI,CAAC,EAAE,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC;IAC5C,MAAM,EAAE,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC;IACzC,MAAM,EAAE,CAAC,UAAU,CAAC,IAAI,CAAC,EAAE,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC;AAC9C,CAAC;AAED,6DAA6D;AAC7D,MAAM,UAAU,SAAS,CAAC,MAAqC;IAC7D,IAAI,MAAM,CAAC,GAAG,KAAK,SAAS;QAAE,OAAO,KAAK,CAAC;IAC3C,IAAI,CAAC;QAAC,OAAO,CAAC,IAAI,CAAC,MAAM,CAAC,GAAG,EAAE,CAAC,CAAC,CAAC;QAAC,OAAO,IAAI,CAAC;IAAC,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QAAC,OAAQ,KAA+B,CAAC,IAAI,KAAK,OAAO,CAAC;IAAC,CAAC;AAC/H,CAAC;AAED,yDAAyD;AACzD,MAAM,UAAU,aAAa,CAAC,MAAuD,EAAE,GAAG,GAAG,IAAI,CAAC,GAAG,EAAE;IACrG,OAAO,MAAM,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,IAAI,EAAE,EAAE,GAAG,MAAM,GAAG,GAAG,MAAM,CAAC,SAAS,CAAC,IAAI,CAAC,CAAC,CAAC,OAAO,GAAG,KAAK,SAAS,IAAI,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,GAAG,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC;AACrI,CAAC"}

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-help.d.ts

@@ -144,19 +144,19 @@ export declare const COMMANDS: readonly [{
     readonly purpose: "Install a download-install Prompt or Skill from the marketplace through Frely Cloud. The paid part is installed only with a valid pass; otherwise the command prints how to buy one. Skills go to the host Skill folder, Prompts to --dir (default: current directory). Scripts are saved without execute permission.";
 }, {
     readonly id: "remote.tools";
-    readonly usage: "frely remote tools <username/name> [--json]";
+    readonly usage: "frely remote tools <username/name> [--json] [--replace]";
     readonly auth: "cloud-oauth";
     readonly effect: "remote-read";
-    readonly purpose: "List the tools of a remote MCP product from the marketplace, with their input schemas, without configuring it in an MCP client. The first use asks Frely for a key that works only for this MCP.";
+    readonly purpose: "List the tools of a remote MCP product from the marketplace, with their input schemas, without configuring it in an MCP client. The first use asks Frely for a key that works only for this MCP. If the name now belongs to a different MCP than the one connected before, it stops; --replace switches to the new one.";
 }, {
     readonly id: "remote.call";
-    readonly usage: "frely remote call <username/name> <tool> [--json '<object>' | --input <file>]";
+    readonly usage: "frely remote call <username/name> <tool> [--json '<object>' | --input <file>] [--replace]";
     readonly auth: "cloud-oauth";
     readonly effect: "remote-call";
     readonly purpose: "Call one tool of a remote MCP product and print the result as JSON (exit code 1 when the tool reports an error). Each call is billed or needs a pass exactly as in an MCP client; ask the user before a call that writes data they did not ask for.";
 }, {
     readonly id: "remote.config";
-    readonly usage: "frely remote config <username/name> [--write <file>]";
+    readonly usage: "frely remote config <username/name> [--write <file>] [--replace]";
     readonly auth: "cloud-oauth";
     readonly effect: "remote-write";
     readonly purpose: "Get a new key for one remote MCP product (it replaces the previous one) and print the mcpServers JSON that MCP clients take for it; with --write the entry is merged into that JSON file (created 0600) instead of printed. The key works only for this MCP.";
@@ -184,12 +184,54 @@ export declare const COMMANDS: readonly [{
     readonly auth: "none";
     readonly effect: "local-write";
     readonly purpose: "Remove an installed Agent Skill and its saved API key.";
+}, {
+    readonly id: "agent.local.add";
+    readonly usage: "frely agent local add <username/name | https://github.com/owner/repo> [--name <folder-name>]";
+    readonly auth: "optional-account";
+    readonly effect: "local-write";
+    readonly purpose: "Download an Agent's repository into its own folder under ~/frely-agents and run its setup inside the sandbox. The sandbox can write only that folder, cannot read credential folders and can reach only Frely's API plus the sites the repository lists in frely.yaml, each of which the owner approves once through a link (exit code 3 with the link when nobody can wait; approve, then run the same command again). Needs a frely.yaml with a local.run command.";
+}, {
+    readonly id: "agent.local.start";
+    readonly usage: "frely agent local start <name> [--foreground]";
+    readonly auth: "account-and-api-key";
+    readonly effect: "local-process";
+    readonly purpose: "Run a local Agent in the background inside the sandbox. Its model calls go through a local proxy that adds the Frely API key (saved with `frely agent local key`), so the repository's code never sees it. Billed to the key like any other API call.";
+}, {
+    readonly id: "agent.local.stop";
+    readonly usage: "frely agent local stop <name>";
+    readonly auth: "none";
+    readonly effect: "local-process";
+    readonly purpose: "Stop a running local Agent. Run start again afterwards to apply newly approved sites.";
+}, {
+    readonly id: "agent.local.logs";
+    readonly usage: "frely agent local logs <name> [--lines <n>] [--follow]";
+    readonly auth: "none";
+    readonly effect: "read";
+    readonly purpose: "Show what a local Agent printed, including what the sandbox blocked.";
+}, {
+    readonly id: "agent.local.list";
+    readonly usage: "frely agent local list [--json]";
+    readonly auth: "none";
+    readonly effect: "read";
+    readonly purpose: "List the Agents on this computer, whether each is running, and the sites each has been approved for.";
+}, {
+    readonly id: "agent.local.remove";
+    readonly usage: "frely agent local remove <name>";
+    readonly auth: "none";
+    readonly effect: "local-write";
+    readonly purpose: "Stop a local Agent and delete its folder and records. Only the Agent's own folder is removed.";
+}, {
+    readonly id: "agent.local.key";
+    readonly usage: "frely agent local key --api-key-stdin | --clear";
+    readonly auth: "account";
+    readonly effect: "local-write";
+    readonly purpose: "Save the Frely API key that local Agents use for model calls; it goes only through stdin to secure storage. FRELY_API_KEY overrides it.";
 }, {
     readonly id: "provider.share";
     readonly usage: "frely provider share [ollama|openai-compatible] [--url <loopback-v1-url>] [--models <a,b>] [--slot <slot-id>] [--name <name>]";
     readonly auth: "account";
     readonly effect: "remote-write";
-    readonly purpose: "Publish a local model Provider. If a prepared Provider on this device is not finished, resume it instead.";
+    readonly purpose: "Publish a local model Provider. If a prepared Provider on this device is not finished, resume it instead. Prints this week's remaining relay allowance; relayed traffic counts against the weekly relay allowance.";
 }, {
     readonly id: "provider.list";
     readonly usage: "frely provider list [--json]";
@@ -202,6 +244,18 @@ export declare const COMMANDS: readonly [{
     readonly auth: "account";
     readonly effect: "remote-write";
     readonly purpose: "Make a web service on this computer (http://127.0.0.1:<port>) reachable from the Internet by a private link through Frely's relay, until Ctrl+C or expiry (at most 24 hours). Asks first. The relay allowance is a plan limit per UTC week; --rewrite-host sends Host: localhost to dev servers that refuse other names. Not the same as `frely provider share` (local models) or `frely tunnel` (command sandbox).";
+}, {
+    readonly id: "service.share";
+    readonly usage: "frely service share --type mcp|a2a --port <n> [--label <text>] [--background] [--json]";
+    readonly auth: "account";
+    readonly effect: "remote-write";
+    readonly purpose: "Connect an MCP server or A2A Agent that runs on this computer (127.0.0.1:<port>) to Frely so you can sell it, without a public address: only Frely's own cloud can reach it, the port never leaves this computer, and Frely never supplies a target. Runs until Ctrl+C, or with --background the device background service keeps it connected. Prints this week's remaining relay allowance; relayed traffic counts against the weekly relay allowance.";
+}, {
+    readonly id: "service.manage";
+    readonly usage: "frely service list [--json] | stop <id|label> | remove <id|label>";
+    readonly auth: "account";
+    readonly effect: "remote-write";
+    readonly purpose: "List registered services, stop one on this computer (it stays registered), or remove it from Frely (products that pointed at it become unreachable).";
 }, {
     readonly id: "tunnel";
     readonly usage: "frely tunnel <host>:<port> [--local-port N]";
@@ -517,19 +571,19 @@ export declare function agentHelp(): {
         readonly purpose: "Install a download-install Prompt or Skill from the marketplace through Frely Cloud. The paid part is installed only with a valid pass; otherwise the command prints how to buy one. Skills go to the host Skill folder, Prompts to --dir (default: current directory). Scripts are saved without execute permission.";
     }, {
         readonly id: "remote.tools";
-        readonly usage: "frely remote tools <username/name> [--json]";
+        readonly usage: "frely remote tools <username/name> [--json] [--replace]";
         readonly auth: "cloud-oauth";
         readonly effect: "remote-read";
-        readonly purpose: "List the tools of a remote MCP product from the marketplace, with their input schemas, without configuring it in an MCP client. The first use asks Frely for a key that works only for this MCP.";
+        readonly purpose: "List the tools of a remote MCP product from the marketplace, with their input schemas, without configuring it in an MCP client. The first use asks Frely for a key that works only for this MCP. If the name now belongs to a different MCP than the one connected before, it stops; --replace switches to the new one.";
     }, {
         readonly id: "remote.call";
-        readonly usage: "frely remote call <username/name> <tool> [--json '<object>' | --input <file>]";
+        readonly usage: "frely remote call <username/name> <tool> [--json '<object>' | --input <file>] [--replace]";
         readonly auth: "cloud-oauth";
         readonly effect: "remote-call";
         readonly purpose: "Call one tool of a remote MCP product and print the result as JSON (exit code 1 when the tool reports an error). Each call is billed or needs a pass exactly as in an MCP client; ask the user before a call that writes data they did not ask for.";
     }, {
         readonly id: "remote.config";
-        readonly usage: "frely remote config <username/name> [--write <file>]";
+        readonly usage: "frely remote config <username/name> [--write <file>] [--replace]";
         readonly auth: "cloud-oauth";
         readonly effect: "remote-write";
         readonly purpose: "Get a new key for one remote MCP product (it replaces the previous one) and print the mcpServers JSON that MCP clients take for it; with --write the entry is merged into that JSON file (created 0600) instead of printed. The key works only for this MCP.";
@@ -557,12 +611,54 @@ export declare function agentHelp(): {
         readonly auth: "none";
         readonly effect: "local-write";
         readonly purpose: "Remove an installed Agent Skill and its saved API key.";
+    }, {
+        readonly id: "agent.local.add";
+        readonly usage: "frely agent local add <username/name | https://github.com/owner/repo> [--name <folder-name>]";
+        readonly auth: "optional-account";
+        readonly effect: "local-write";
+        readonly purpose: "Download an Agent's repository into its own folder under ~/frely-agents and run its setup inside the sandbox. The sandbox can write only that folder, cannot read credential folders and can reach only Frely's API plus the sites the repository lists in frely.yaml, each of which the owner approves once through a link (exit code 3 with the link when nobody can wait; approve, then run the same command again). Needs a frely.yaml with a local.run command.";
+    }, {
+        readonly id: "agent.local.start";
+        readonly usage: "frely agent local start <name> [--foreground]";
+        readonly auth: "account-and-api-key";
+        readonly effect: "local-process";
+        readonly purpose: "Run a local Agent in the background inside the sandbox. Its model calls go through a local proxy that adds the Frely API key (saved with `frely agent local key`), so the repository's code never sees it. Billed to the key like any other API call.";
+    }, {
+        readonly id: "agent.local.stop";
+        readonly usage: "frely agent local stop <name>";
+        readonly auth: "none";
+        readonly effect: "local-process";
+        readonly purpose: "Stop a running local Agent. Run start again afterwards to apply newly approved sites.";
+    }, {
+        readonly id: "agent.local.logs";
+        readonly usage: "frely agent local logs <name> [--lines <n>] [--follow]";
+        readonly auth: "none";
+        readonly effect: "read";
+        readonly purpose: "Show what a local Agent printed, including what the sandbox blocked.";
+    }, {
+        readonly id: "agent.local.list";
+        readonly usage: "frely agent local list [--json]";
+        readonly auth: "none";
+        readonly effect: "read";
+        readonly purpose: "List the Agents on this computer, whether each is running, and the sites each has been approved for.";
+    }, {
+        readonly id: "agent.local.remove";
+        readonly usage: "frely agent local remove <name>";
+        readonly auth: "none";
+        readonly effect: "local-write";
+        readonly purpose: "Stop a local Agent and delete its folder and records. Only the Agent's own folder is removed.";
+    }, {
+        readonly id: "agent.local.key";
+        readonly usage: "frely agent local key --api-key-stdin | --clear";
+        readonly auth: "account";
+        readonly effect: "local-write";
+        readonly purpose: "Save the Frely API key that local Agents use for model calls; it goes only through stdin to secure storage. FRELY_API_KEY overrides it.";
     }, {
         readonly id: "provider.share";
         readonly usage: "frely provider share [ollama|openai-compatible] [--url <loopback-v1-url>] [--models <a,b>] [--slot <slot-id>] [--name <name>]";
         readonly auth: "account";
         readonly effect: "remote-write";
-        readonly purpose: "Publish a local model Provider. If a prepared Provider on this device is not finished, resume it instead.";
+        readonly purpose: "Publish a local model Provider. If a prepared Provider on this device is not finished, resume it instead. Prints this week's remaining relay allowance; relayed traffic counts against the weekly relay allowance.";
     }, {
         readonly id: "provider.list";
         readonly usage: "frely provider list [--json]";
@@ -575,6 +671,18 @@ export declare function agentHelp(): {
         readonly auth: "account";
         readonly effect: "remote-write";
         readonly purpose: "Make a web service on this computer (http://127.0.0.1:<port>) reachable from the Internet by a private link through Frely's relay, until Ctrl+C or expiry (at most 24 hours). Asks first. The relay allowance is a plan limit per UTC week; --rewrite-host sends Host: localhost to dev servers that refuse other names. Not the same as `frely provider share` (local models) or `frely tunnel` (command sandbox).";
+    }, {
+        readonly id: "service.share";
+        readonly usage: "frely service share --type mcp|a2a --port <n> [--label <text>] [--background] [--json]";
+        readonly auth: "account";
+        readonly effect: "remote-write";
+        readonly purpose: "Connect an MCP server or A2A Agent that runs on this computer (127.0.0.1:<port>) to Frely so you can sell it, without a public address: only Frely's own cloud can reach it, the port never leaves this computer, and Frely never supplies a target. Runs until Ctrl+C, or with --background the device background service keeps it connected. Prints this week's remaining relay allowance; relayed traffic counts against the weekly relay allowance.";
+    }, {
+        readonly id: "service.manage";
+        readonly usage: "frely service list [--json] | stop <id|label> | remove <id|label>";
+        readonly auth: "account";
+        readonly effect: "remote-write";
+        readonly purpose: "List registered services, stop one on this computer (it stays registered), or remove it from Frely (products that pointed at it become unreachable).";
     }, {
         readonly id: "tunnel";
         readonly usage: "frely tunnel <host>:<port> [--local-port N]";

package/dist/agent-help.js

@@ -24,16 +24,25 @@ export const COMMANDS = [
     { id: "item.run", usage: "frely item run <script> [args...]", auth: "cloud-oauth", effect: "local-execution", purpose: "Run an encrypted paid script of an installed item inside the Frely command sandbox. The placeholder file at the script's path calls this for you. The access lease is renewed when it is near its end; without a valid pass the script does not run." },
     { id: "item.update", usage: "frely item update [<folder>] [--json]", auth: "cloud-oauth", effect: "local-write", purpose: "Without a folder, list the installed marketplace items and say which have a newer version; nothing is changed. With a folder, install the newer version into that folder, after you decide to. Frely never updates an item by itself. A folder you edited is refused, and a new version needs a new review (frely item trust) unless Frely's scan passed for it." },
     { id: "item.install", usage: "frely item install <username/name[@version]> [--host chatgpt|codex|claude-code|pi|generic] [--scope global|project] [--dir <path>] [--json]", auth: "cloud-oauth", effect: "local-write", purpose: "Install a download-install Prompt or Skill from the marketplace through Frely Cloud. The paid part is installed only with a valid pass; otherwise the command prints how to buy one. Skills go to the host Skill folder, Prompts to --dir (default: current directory). Scripts are saved without execute permission." },
-    { id: "remote.tools", usage: "frely remote tools <username/name> [--json]", auth: "cloud-oauth", effect: "remote-read", purpose: "List the tools of a remote MCP product from the marketplace, with their input schemas, without configuring it in an MCP client. The first use asks Frely for a key that works only for this MCP." },
-    { id: "remote.call", usage: "frely remote call <username/name> <tool> [--json '<object>' | --input <file>]", auth: "cloud-oauth", effect: "remote-call", purpose: "Call one tool of a remote MCP product and print the result as JSON (exit code 1 when the tool reports an error). Each call is billed or needs a pass exactly as in an MCP client; ask the user before a call that writes data they did not ask for." },
-    { id: "remote.config", usage: "frely remote config <username/name> [--write <file>]", auth: "cloud-oauth", effect: "remote-write", purpose: "Get a new key for one remote MCP product (it replaces the previous one) and print the mcpServers JSON that MCP clients take for it; with --write the entry is merged into that JSON file (created 0600) instead of printed. The key works only for this MCP." },
+    { id: "remote.tools", usage: "frely remote tools <username/name> [--json] [--replace]", auth: "cloud-oauth", effect: "remote-read", purpose: "List the tools of a remote MCP product from the marketplace, with their input schemas, without configuring it in an MCP client. The first use asks Frely for a key that works only for this MCP. If the name now belongs to a different MCP than the one connected before, it stops; --replace switches to the new one." },
+    { id: "remote.call", usage: "frely remote call <username/name> <tool> [--json '<object>' | --input <file>] [--replace]", auth: "cloud-oauth", effect: "remote-call", purpose: "Call one tool of a remote MCP product and print the result as JSON (exit code 1 when the tool reports an error). Each call is billed or needs a pass exactly as in an MCP client; ask the user before a call that writes data they did not ask for." },
+    { id: "remote.config", usage: "frely remote config <username/name> [--write <file>] [--replace]", auth: "cloud-oauth", effect: "remote-write", purpose: "Get a new key for one remote MCP product (it replaces the previous one) and print the mcpServers JSON that MCP clients take for it; with --write the entry is merged into that JSON file (created 0600) instead of printed. The key works only for this MCP." },
     { id: "agent.install", usage: "frely agent install <username/name[@version]> [--host chatgpt|codex|claude-code|pi|generic] [--scope global|project] [--dir <project>] [--api-key-stdin] [--json]", auth: "optional-api-key", effect: "local-write", purpose: "Install the public Agent's trigger Skill; an API key goes only through stdin to secure storage." },
     { id: "agent.run", usage: "frely agent run <username/name> (--input <text>|--input-stdin) [--json]", auth: "installed-api-key-or-account", effect: "remote-call", purpose: "Send the complete relevant user request to the installed Agent through model-scoped MCP. Usage may be billed." },
     { id: "agent.status", usage: "frely agent status (<username/name>|--api-key-stdin [--relay <url>]) [--json]", auth: "none-or-api-key", effect: "read", purpose: "Inspect an installed Agent Skill and, for API-key installs, its Key budget. With --api-key-stdin, read that Key's budget without installing or logging in." },
     { id: "agent.remove", usage: "frely agent remove <username/name> [--json]", auth: "none", effect: "local-write", purpose: "Remove an installed Agent Skill and its saved API key." },
-    { id: "provider.share", usage: "frely provider share [ollama|openai-compatible] [--url <loopback-v1-url>] [--models <a,b>] [--slot <slot-id>] [--name <name>]", auth: "account", effect: "remote-write", purpose: "Publish a local model Provider. If a prepared Provider on this device is not finished, resume it instead." },
+    { id: "agent.local.add", usage: "frely agent local add <username/name | https://github.com/owner/repo> [--name <folder-name>]", auth: "optional-account", effect: "local-write", purpose: "Download an Agent's repository into its own folder under ~/frely-agents and run its setup inside the sandbox. The sandbox can write only that folder, cannot read credential folders and can reach only Frely's API plus the sites the repository lists in frely.yaml, each of which the owner approves once through a link (exit code 3 with the link when nobody can wait; approve, then run the same command again). Needs a frely.yaml with a local.run command." },
+    { id: "agent.local.start", usage: "frely agent local start <name> [--foreground]", auth: "account-and-api-key", effect: "local-process", purpose: "Run a local Agent in the background inside the sandbox. Its model calls go through a local proxy that adds the Frely API key (saved with `frely agent local key`), so the repository's code never sees it. Billed to the key like any other API call." },
+    { id: "agent.local.stop", usage: "frely agent local stop <name>", auth: "none", effect: "local-process", purpose: "Stop a running local Agent. Run start again afterwards to apply newly approved sites." },
+    { id: "agent.local.logs", usage: "frely agent local logs <name> [--lines <n>] [--follow]", auth: "none", effect: "read", purpose: "Show what a local Agent printed, including what the sandbox blocked." },
+    { id: "agent.local.list", usage: "frely agent local list [--json]", auth: "none", effect: "read", purpose: "List the Agents on this computer, whether each is running, and the sites each has been approved for." },
+    { id: "agent.local.remove", usage: "frely agent local remove <name>", auth: "none", effect: "local-write", purpose: "Stop a local Agent and delete its folder and records. Only the Agent's own folder is removed." },
+    { id: "agent.local.key", usage: "frely agent local key --api-key-stdin | --clear", auth: "account", effect: "local-write", purpose: "Save the Frely API key that local Agents use for model calls; it goes only through stdin to secure storage. FRELY_API_KEY overrides it." },
+    { id: "provider.share", usage: "frely provider share [ollama|openai-compatible] [--url <loopback-v1-url>] [--models <a,b>] [--slot <slot-id>] [--name <name>]", auth: "account", effect: "remote-write", purpose: "Publish a local model Provider. If a prepared Provider on this device is not finished, resume it instead. Prints this week's remaining relay allowance; relayed traffic counts against the weekly relay allowance." },
     { id: "provider.list", usage: "frely provider list [--json]", auth: "account", effect: "read", purpose: "List configured local Providers." },
     { id: "share", usage: "frely share <port> [--ttl <hours>] [--rewrite-host] [--yes] [--json]", auth: "account", effect: "remote-write", purpose: "Make a web service on this computer (http://127.0.0.1:<port>) reachable from the Internet by a private link through Frely's relay, until Ctrl+C or expiry (at most 24 hours). Asks first. The relay allowance is a plan limit per UTC week; --rewrite-host sends Host: localhost to dev servers that refuse other names. Not the same as `frely provider share` (local models) or `frely tunnel` (command sandbox)." },
+    { id: "service.share", usage: "frely service share --type mcp|a2a --port <n> [--label <text>] [--background] [--json]", auth: "account", effect: "remote-write", purpose: "Connect an MCP server or A2A Agent that runs on this computer (127.0.0.1:<port>) to Frely so you can sell it, without a public address: only Frely's own cloud can reach it, the port never leaves this computer, and Frely never supplies a target. Runs until Ctrl+C, or with --background the device background service keeps it connected. Prints this week's remaining relay allowance; relayed traffic counts against the weekly relay allowance." },
+    { id: "service.manage", usage: "frely service list [--json] | stop <id|label> | remove <id|label>", auth: "account", effect: "remote-write", purpose: "List registered services, stop one on this computer (it stays registered), or remove it from Frely (products that pointed at it become unreachable)." },
     { id: "tunnel", usage: "frely tunnel <host>:<port> [--local-port N]", auth: "none", effect: "local-execution", purpose: "Run inside a sandboxed command (run_command): listen on 127.0.0.1:<local-port> (default: the same port) and forward each TCP connection to host:port through the command sandbox's proxy, so database and redis clients connect to 127.0.0.1 without turning the sandbox off. Start it in the same command as the client, for example `frely tunnel db.example.com:5432 & sleep 1; psql -h 127.0.0.1 ...`. Prints the local address and runs until killed." },
     { id: "sandbox.proxy", usage: "frely sandbox proxy [<http://host:port> [--no-proxy <list>] | --clear]", auth: "none", effect: "local-write", purpose: "Show, save or remove the HTTP(S) proxy that the command sandbox forwards its network traffic to (your own proxy, for example Clash). Without one saved it uses the HTTPS_PROXY / HTTP_PROXY / ALL_PROXY of the CLI process and, on macOS, the system proxy. Your proxy settings are never changed. Takes effect when the MCP service restarts." },
     { id: "devices", usage: "frely devices [--add] [--json]", auth: "controller", effect: "read", purpose: "List your Frely devices with online state and workspaces (list_devices). --add prints a one-time install command for a new computer." },
@@ -89,11 +98,11 @@ const GROUPS = [
     { title: "Control your devices", ids: ["devices", "run", "ps", "logs", "kill", "read", "ls", "grep", "edit", "permission", "tools", "call", "controller"] },
     { title: "Account", ids: ["login", "logout", "uninstall", "doctor", "update"] },
     { title: "Device MCP", ids: ["mcp.start", "mcp.workspace", "mcp.local", "mcp.lifecycle"] },
-    { title: "Agents", ids: ["agent.install", "agent.run", "agent.status", "agent.remove"] },
+    { title: "Agents", ids: ["agent.install", "agent.run", "agent.status", "agent.remove", "agent.local"] },
     { title: "Skills", ids: ["skill.install"] },
     { title: "Marketplace items", ids: ["item.install", "item.update", "item.run", "item.trust"] },
     { title: "Providers", ids: ["provider.share", "provider.list"] },
-    { title: "Share", ids: ["share"] },
+    { title: "Share", ids: ["share", "service.share", "service.manage"] },
     { title: "Command sandbox", ids: ["tunnel", "sandbox.proxy"] },
     { title: "API", ids: ["api", "remote.tools", "remote.call", "remote.config"] },
 ];
@@ -133,9 +142,19 @@ const SHORT_USAGE = {
     "agent.run": "frely agent run <username/name> (--input <text>|--input-stdin)",
     "agent.status": "frely agent status <username/name>",
     "agent.remove": "frely agent remove <username/name>",
+    "agent.local": "frely agent local add|start|stop|logs|list|remove|key",
+    "agent.local.add": "frely agent local add <username/name | github-url>",
+    "agent.local.start": "frely agent local start <name>",
+    "agent.local.stop": "frely agent local stop <name>",
+    "agent.local.logs": "frely agent local logs <name> [--follow]",
+    "agent.local.list": "frely agent local list",
+    "agent.local.remove": "frely agent local remove <name>",
+    "agent.local.key": "frely agent local key --api-key-stdin",
     "provider.share": "frely provider share [ollama|openai-compatible] [--models <a,b>]",
     "provider.list": "frely provider list",
     share: "frely share <port> [--ttl <hours>]",
+    "service.share": "frely service share --type mcp|a2a --port <n>",
+    "service.manage": "frely service list|stop|remove",
     tunnel: "frely tunnel <host>:<port> [--local-port N]",
     "sandbox.proxy": "frely sandbox proxy [<url> [--no-proxy <list>] | --clear]",
     api: "frely api list|describe|call",