frely-cli 0.23.8 → 0.23.10

package/dist/controller/client.d.ts

@@ -0,0 +1,52 @@
+import { controllerLogin, type ControllerSession } from "./session.js";
+export type ToolResult = {
+    isError?: boolean;
+    content?: unknown;
+    structuredContent?: unknown;
+    [key: string]: unknown;
+};
+/**
+ * `fetch` for the FrelyMCP transport: every request carries the DPoP access token and a fresh proof for that request. A refused token is
+ * renewed once (another process may have renewed it already) and the request sent again; a request is only ever replayed when the server
+ * refused it before running anything.
+ */
+export declare function dpopFetch(initial: ControllerSession, options?: {
+    refresh?: (session: ControllerSession) => Promise<ControllerSession>;
+    now?: () => number;
+}): {
+    fetch: typeof fetch;
+    session(): ControllerSession;
+};
+export declare const NOT_AUTHORIZED = "This computer is not authorized to control your devices yet. Run frely controller login in a terminal, approve the request in your browser, then run this command again.";
+export interface Controller {
+    /** The server's own instructions (how to use the tools), printed first by `frely tools`. */
+    instructions(): string | undefined;
+    tools(): Promise<Array<{
+        name: string;
+        description?: string | undefined;
+        inputSchema?: unknown;
+        annotations?: {
+            readOnlyHint?: boolean | undefined;
+        } | undefined;
+    }>>;
+    call(name: string, args: Record<string, unknown>): Promise<ToolResult>;
+    close(): Promise<void>;
+}
+/** Opens a controller connection, signing the computer in first when there is no session and a person can approve it. */
+export declare function openController(options?: {
+    interactive: boolean;
+    login?: typeof controllerLogin;
+}): Promise<Controller>;
+/** The tool's text parts joined, as a person or model would read them. */
+export declare function resultText(result: ToolResult): string;
+/** The result as one object: its structured content, else its text when that is a JSON object. */
+export declare function resultData(result: ToolResult): Record<string, unknown> | null;
+export interface Outcome {
+    exitCode: number; /** Why the command did not simply succeed: what to do next, for the output's end. */
+    note?: string;
+}
+/**
+ * What a tool result means for the exit code. A pending approval (3) comes with where to approve and the command that waits for it; an
+ * offline device (5), a quota (6) and any other tool error (2) keep the server's own words in the output.
+ */
+export declare function outcomeOf(result: ToolResult): Outcome;

package/dist/controller/client.js

@@ -0,0 +1,124 @@
+import { Client } from "@modelcontextprotocol/sdk/client/index.js";
+import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";
+import { VERSION } from "../version.js";
+import { createDpopProof, dpopKeyFromPem } from "./dpop.js";
+import { controllerLogin, ControllerError, EXIT, readSession, refreshSession } from "./session.js";
+/**
+ * `fetch` for the FrelyMCP transport: every request carries the DPoP access token and a fresh proof for that request. A refused token is
+ * renewed once (another process may have renewed it already) and the request sent again; a request is only ever replayed when the server
+ * refused it before running anything.
+ */
+export function dpopFetch(initial, options = {}) {
+    let session = initial;
+    const refresh = options.refresh ?? refreshSession;
+    const now = options.now ?? Date.now;
+    const send = (input, init) => {
+        const url = input instanceof Request ? input.url : String(input);
+        const method = init?.method ?? (input instanceof Request ? input.method : "GET");
+        const headers = new Headers(init?.headers);
+        headers.set("authorization", `DPoP ${session.accessToken}`);
+        headers.set("dpop", createDpopProof(dpopKeyFromPem(session.privateKeyPem), { method, url, accessToken: session.accessToken }));
+        return fetch(url, { ...init, headers, redirect: "error" });
+    };
+    return {
+        session: () => session,
+        fetch: async (input, init) => {
+            if (session.expiresAt - 30_000 <= now())
+                session = await refresh(session);
+            let response = await send(input, init);
+            if (response.status === 401) {
+                await response.body?.cancel().catch(() => undefined);
+                session = await refresh(session);
+                response = await send(input, init);
+                if (response.status === 401)
+                    throw new ControllerError("The server did not accept this computer's controller authorization. Run the command again to approve it in your browser.", EXIT.auth);
+            }
+            return response;
+        },
+    };
+}
+export const NOT_AUTHORIZED = "This computer is not authorized to control your devices yet. Run frely controller login in a terminal, approve the request in your browser, then run this command again.";
+/** Opens a controller connection, signing the computer in first when there is no session and a person can approve it. */
+export async function openController(options = { interactive: false }) {
+    let session = await readSession();
+    if (!session) {
+        if (!options.interactive)
+            throw new ControllerError(NOT_AUTHORIZED, EXIT.auth);
+        session = await (options.login ?? controllerLogin)();
+    }
+    const signed = dpopFetch(session);
+    const transport = new StreamableHTTPClientTransport(new URL(session.mcpUrl), {
+        fetch: signed.fetch, reconnectionOptions: { maxRetries: 0, initialReconnectionDelay: 1000, maxReconnectionDelay: 1000, reconnectionDelayGrowFactor: 1 },
+    });
+    const client = new Client({ name: "frely-cli-controller", version: VERSION });
+    try {
+        await client.connect(transport);
+    }
+    catch (error) {
+        await client.close().catch(() => undefined);
+        if (error instanceof ControllerError)
+            throw error;
+        throw new ControllerError(`Could not reach FrelyMCP: ${error instanceof Error ? error.message : String(error)}`, EXIT.offline);
+    }
+    return {
+        instructions: () => client.getInstructions(),
+        async tools() {
+            const all = [];
+            let cursor;
+            do {
+                const page = await client.listTools(cursor === undefined ? {} : { cursor });
+                all.push(...page.tools);
+                cursor = page.nextCursor;
+            } while (cursor && all.length < 1000);
+            return all;
+        },
+        call: (name, args) => client.callTool({ name, arguments: args }, undefined, { timeout: 180_000 }),
+        close: () => client.close(),
+    };
+}
+/** The tool's text parts joined, as a person or model would read them. */
+export function resultText(result) {
+    const parts = Array.isArray(result.content) ? result.content : [];
+    return parts.filter((part) => part.type === "text" && typeof part.text === "string").map((part) => part.text).join("\n");
+}
+/** The result as one object: its structured content, else its text when that is a JSON object. */
+export function resultData(result) {
+    if (result.structuredContent && typeof result.structuredContent === "object" && !Array.isArray(result.structuredContent))
+        return result.structuredContent;
+    try {
+        const parsed = JSON.parse(resultText(result));
+        return parsed && typeof parsed === "object" && !Array.isArray(parsed) ? parsed : null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * What a tool result means for the exit code. A pending approval (3) comes with where to approve and the command that waits for it; an
+ * offline device (5), a quota (6) and any other tool error (2) keep the server's own words in the output.
+ */
+export function outcomeOf(result) {
+    const data = resultData(result);
+    if (data?.status === "pending" && (typeof data.approveUrl === "string" || typeof data.shortCode === "string")) {
+        const code = typeof data.shortCode === "string" ? data.shortCode : null;
+        const lines = [`Approval needed${typeof data.device === "string" ? ` on ${data.device}` : ""}.`];
+        if (typeof data.approveUrl === "string")
+            lines.push(`Approve here: ${data.approveUrl}`);
+        if (code)
+            lines.push(`After the owner approves, or to wait for it in the background: frely permission wait ${code}`);
+        return { exitCode: EXIT.approval, note: lines.join("\n") };
+    }
+    if (result.isError !== true)
+        return { exitCode: EXIT.ok };
+    const error = (data?.error && typeof data.error === "object" ? data.error : null);
+    if (error && (error.code === "permission_required" || error.code === "confirmation_required") && typeof error.url === "string") {
+        return { exitCode: EXIT.approval, note: `Approval needed. Approve here: ${error.url}` };
+    }
+    const text = resultText(result);
+    if (/frely mcp start|device is offline|Offline:/u.test(text))
+        return { exitCode: EXIT.offline };
+    if (error && typeof error.code === "string" && /limit|quota|insufficient/u.test(error.code))
+        return { exitCode: EXIT.limit };
+    return { exitCode: EXIT.tool };
+}
+//# sourceMappingURL=client.js.map

package/dist/controller/client.js.map

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

package/dist/controller/commands.d.ts

@@ -0,0 +1,16 @@
+import { openController, type Controller } from "./client.js";
+export declare const CONTROLLER_COMMANDS: ReadonlySet<string>;
+export interface Output {
+    out(text: string): void;
+    err(text: string): void;
+}
+export declare const CONTROLLER_USAGE = "Control your Frely devices from this computer.\n  frely devices [--add]                          List devices, whether they are online, and their workspaces\n  frely run <device> [--cwd <dir>] [--timeout <s>] [--background] -- <command>\n  frely ps <device>                              Background commands on the device\n  frely logs <device> <id> [--follow]            Output of a background command\n  frely kill <device> <id>                       Stop a background command\n  frely read <device>:<path> [--lines a:b]       Print a file\n  frely ls [<device>:<path>]                     List a folder (no argument: the workspace roots)\n  frely grep <device>:<path> <text> [--regex] [--case] [--max <n>]\n  frely edit <device>:<path> (--from <local file> | --patch <json file>) [--overwrite]\n  frely permission request <device> --resource <name> --reason <text> --command <text> [--cwd <dir>] [--mode once|window|authorization]\n  frely permission confirm <code> [A|B|C]        Finish an approval by authenticator or emailed code\n  frely permission wait <short code> [--then '<command>'] [--timeout <s>]\n  frely tools [--json]                           What the server offers, with its own instructions\n  frely call <tool> [--json '<object>' | --input <file>]   Any tool by name\n  frely controller login|logout|status           This computer's authorization to control your devices\n\nEvery command takes --json (the full result) and --out <file> (write the output there).\nA device is its name or id from \"frely devices\". A path on this computer is not accepted where <device>:<path> is expected.\nExit codes: 0 done, 1 this CLI (usage, local file), 2 the tool or the remote command failed, 3 approval needed (the output has the link\nand the \"frely permission wait\" command), 4 not authorized (run frely controller login), 5 device offline, 6 limit reached.\n";
+/** Tests replace the connection with a fake; returns the function that puts the real one back. */
+export declare function useControllerOpener(replacement: typeof openController): () => void;
+export declare function runControllerCommand(args: readonly string[], io: Output): Promise<number>;
+/** Polls the request until the owner decides: approved is 0, denied 2, and a request that ran out (or was revoked) or the time limit is 3, because approval is still needed. */
+export declare function waitForPermission(controller: Pick<Controller, "call">, code: string, timeoutMs: number, io: Output, options?: {
+    intervalMs?: number;
+    now?: () => number;
+    sleep?: (ms: number) => Promise<void>;
+}): Promise<number>;

package/dist/controller/commands.js

@@ -0,0 +1,411 @@
+import { spawn } from "node:child_process";
+import { readFile, stat, writeFile } from "node:fs/promises";
+import { intOption, parseArgs, requireRemote } from "./args.js";
+import { openController, outcomeOf, resultData, resultText } from "./client.js";
+import { controllerLogin, controllerLogout, ControllerError, EXIT, readSession } from "./session.js";
+export const CONTROLLER_COMMANDS = new Set(["devices", "run", "ps", "logs", "kill", "read", "ls", "grep", "edit", "tools", "call", "permission", "controller"]);
+export const CONTROLLER_USAGE = `Control your Frely devices from this computer.
+  frely devices [--add]                          List devices, whether they are online, and their workspaces
+  frely run <device> [--cwd <dir>] [--timeout <s>] [--background] -- <command>
+  frely ps <device>                              Background commands on the device
+  frely logs <device> <id> [--follow]            Output of a background command
+  frely kill <device> <id>                       Stop a background command
+  frely read <device>:<path> [--lines a:b]       Print a file
+  frely ls [<device>:<path>]                     List a folder (no argument: the workspace roots)
+  frely grep <device>:<path> <text> [--regex] [--case] [--max <n>]
+  frely edit <device>:<path> (--from <local file> | --patch <json file>) [--overwrite]
+  frely permission request <device> --resource <name> --reason <text> --command <text> [--cwd <dir>] [--mode once|window|authorization]
+  frely permission confirm <code> [A|B|C]        Finish an approval by authenticator or emailed code
+  frely permission wait <short code> [--then '<command>'] [--timeout <s>]
+  frely tools [--json]                           What the server offers, with its own instructions
+  frely call <tool> [--json '<object>' | --input <file>]   Any tool by name
+  frely controller login|logout|status           This computer's authorization to control your devices
+
+Every command takes --json (the full result) and --out <file> (write the output there).
+A device is its name or id from "frely devices". A path on this computer is not accepted where <device>:<path> is expected.
+Exit codes: 0 done, 1 this CLI (usage, local file), 2 the tool or the remote command failed, 3 approval needed (the output has the link
+and the "frely permission wait" command), 4 not authorized (run frely controller login), 5 device offline, 6 limit reached.
+`;
+const MAX_LOCAL_FILE = 1024 * 1024;
+const isInteractive = () => process.stdin.isTTY === true && process.stderr.isTTY === true;
+const sleep = (ms) => new Promise((done) => setTimeout(done, ms));
+async function emit(shown, outcome, parsed, io) {
+    const body = parsed.flags.has("--json") ? JSON.stringify(shown.result, null, 2) : shown.text;
+    const file = parsed.values.get("--out");
+    if (file !== undefined) {
+        await writeFile(file, body.endsWith("\n") ? body : body + "\n");
+        io.out(`Wrote ${Buffer.byteLength(body)} bytes to ${file}\n`);
+    }
+    else
+        io.out(body === "" || body.endsWith("\n") ? body : body + "\n");
+    if (outcome.note)
+        io.err(outcome.note + "\n");
+    if (outcome.exitCode !== EXIT.ok)
+        return outcome.exitCode;
+    if (shown.remoteExit !== undefined && shown.remoteExit !== 0) {
+        io.err(`The command ended with exit code ${shown.remoteExit}.\n`);
+        return EXIT.tool;
+    }
+    return EXIT.ok;
+}
+const asText = (value) => typeof value === "string" ? value : "";
+/** The output of a `process` or `read` result as the command itself would have printed it. */
+function shownOf(result) {
+    const data = resultData(result);
+    if (data && (typeof data.stdout === "string" || typeof data.stderr === "string")) {
+        const text = asText(data.stdout) + (asText(data.stderr) ? (asText(data.stdout) && !asText(data.stdout).endsWith("\n") ? "\n" : "") + asText(data.stderr) : "");
+        const exitCode = typeof data.exitCode === "number" ? data.exitCode : undefined;
+        return { text, result, ...(exitCode !== undefined ? { remoteExit: exitCode } : {}) };
+    }
+    if (data && typeof data.content === "string" && data.encoding === undefined)
+        return { text: data.content, result };
+    return { text: resultText(result) || (data ? JSON.stringify(data, null, 2) : ""), result };
+}
+let openIt = openController;
+/** Tests replace the connection with a fake; returns the function that puts the real one back. */
+export function useControllerOpener(replacement) {
+    const previous = openIt;
+    openIt = replacement;
+    return () => { openIt = previous; };
+}
+async function withController(io, work) {
+    const controller = await openIt({ interactive: isInteractive() });
+    try {
+        return await work(controller);
+    }
+    finally {
+        await controller.close().catch(() => undefined);
+    }
+}
+const COMMON_FLAGS = ["--json"];
+const COMMON_VALUES = ["--out"];
+async function readLocal(path, what) {
+    const info = await stat(path).catch(() => { throw new ControllerError(`${what} ${path} was not found.`, EXIT.cli); });
+    if (!info.isFile())
+        throw new ControllerError(`${what} ${path} is not a file.`, EXIT.cli);
+    if (info.size > MAX_LOCAL_FILE)
+        throw new ControllerError(`${what} ${path} is larger than 1 MiB.`, EXIT.cli);
+    return readFile(path);
+}
+export async function runControllerCommand(args, io) {
+    const [command, ...rest] = args;
+    try {
+        if (command === undefined || rest.includes("--help") || rest.includes("-h")) {
+            io.out(CONTROLLER_USAGE);
+            return EXIT.ok;
+        }
+        switch (command) {
+            case "controller": return await controllerCommand(rest, io);
+            case "permission": return await permissionCommand(rest, io);
+            case "devices": return await devices(rest, io);
+            case "run": return await run(rest, io);
+            case "ps": return await ps(rest, io);
+            case "logs": return await logs(rest, io);
+            case "kill": return await kill(rest, io);
+            case "read": return await readCommand(rest, io);
+            case "ls": return await ls(rest, io);
+            case "grep": return await grep(rest, io);
+            case "edit": return await edit(rest, io);
+            case "tools": return await toolsCommand(rest, io);
+            case "call": return await callCommand(rest, io);
+            default: throw new ControllerError(`Unknown command ${command}.\n${CONTROLLER_USAGE}`, EXIT.cli);
+        }
+    }
+    catch (error) {
+        if (error instanceof ControllerError) {
+            io.err(error.message + "\n");
+            return error.exitCode;
+        }
+        throw error;
+    }
+}
+async function controllerCommand(args, io) {
+    const action = args[0];
+    if (action === "login") {
+        const session = await controllerLogin({ notify: (text) => io.err(text) });
+        io.out(`This computer can now control your Frely devices (FrelyMCP ${session.mcpUrl}).\n`);
+        return EXIT.ok;
+    }
+    if (action === "logout") {
+        io.out(await controllerLogout() ? "This computer no longer controls your Frely devices.\n" : "This computer was not authorized as a controller.\n");
+        return EXIT.ok;
+    }
+    if (action === "status") {
+        const session = await readSession();
+        io.out(session ? `Authorized to control your devices: yes\nFrelyMCP: ${session.mcpUrl}\n` : "Authorized to control your devices: no. Run frely controller login.\n");
+        return EXIT.ok;
+    }
+    throw new ControllerError("Usage: frely controller login|logout|status", EXIT.cli);
+}
+async function devices(args, io) {
+    const parsed = parseArgs(args, { flags: [...COMMON_FLAGS, "--add"], values: COMMON_VALUES });
+    return withController(io, async (controller) => {
+        const result = await controller.call("list_devices", parsed.flags.has("--add") ? { addDevice: true } : {});
+        const outcome = outcomeOf(result);
+        const data = resultData(result);
+        const list = Array.isArray(data?.devices) ? data.devices : null;
+        let text = resultText(result);
+        if (list) {
+            const rows = list.map((device) => `${asText(device.name) || asText(device.id)}\t${device.online === true ? "online" : "offline"}\t${asText(device.mcp)}\t${Array.isArray(device.workspaces) ? device.workspaces.join(", ") : "-"}`);
+            text = ["NAME\tSTATE\tMCP\tWORKSPACES", ...rows].join("\n") + (typeof data?.setup === "string" ? `\n\n${data.setup}` : "");
+        }
+        return emit({ text, result }, outcome, parsed, io);
+    });
+}
+async function toolCall(io, parsed, name, input) {
+    return withController(io, async (controller) => {
+        const result = await controller.call(name, input);
+        return emit(shownOf(result), outcomeOf(result), parsed, io);
+    });
+}
+async function run(args, io) {
+    const parsed = parseArgs(args, { flags: [...COMMON_FLAGS, "--background"], values: [...COMMON_VALUES, "--cwd", "--timeout"] });
+    const [device] = parsed.positionals;
+    if (!device || parsed.positionals.length !== 1 || parsed.rest.length === 0)
+        throw new ControllerError("Usage: frely run <device> [--cwd <dir>] [--timeout <s>] [--background] -- <command>", EXIT.cli);
+    const timeout = intOption(parsed, "--timeout", 1, 120);
+    const background = parsed.flags.has("--background");
+    return toolCall(io, parsed, "process", {
+        device, action: background ? "start" : "run", command: parsed.rest.join(" "), ...(parsed.values.has("--cwd") ? { cwd: parsed.values.get("--cwd") } : {}),
+        ...(timeout !== undefined && !background ? { timeoutMs: timeout * 1000 } : {}),
+    });
+}
+async function ps(args, io) {
+    const parsed = parseArgs(args, { flags: COMMON_FLAGS, values: COMMON_VALUES });
+    if (parsed.positionals.length !== 1)
+        throw new ControllerError("Usage: frely ps <device>", EXIT.cli);
+    return toolCall(io, parsed, "process", { device: parsed.positionals[0], action: "list" });
+}
+async function kill(args, io) {
+    const parsed = parseArgs(args, { flags: COMMON_FLAGS, values: COMMON_VALUES });
+    if (parsed.positionals.length !== 2)
+        throw new ControllerError("Usage: frely kill <device> <id>", EXIT.cli);
+    return toolCall(io, parsed, "process", { device: parsed.positionals[0], action: "stop", processId: parsed.positionals[1] });
+}
+async function logs(args, io) {
+    const parsed = parseArgs(args, { flags: [...COMMON_FLAGS, "--follow"], values: COMMON_VALUES });
+    if (parsed.positionals.length !== 2)
+        throw new ControllerError("Usage: frely logs <device> <id> [--follow]", EXIT.cli);
+    const [device, processId] = parsed.positionals;
+    const follow = parsed.flags.has("--follow");
+    return withController(io, async (controller) => {
+        let stdoutCursor = 0, stderrCursor = 0;
+        for (;;) {
+            const result = await controller.call("process", { device, action: "read", processId, stdoutCursor, stderrCursor });
+            const outcome = outcomeOf(result);
+            const data = resultData(result);
+            if (!follow || outcome.exitCode !== EXIT.ok || !data)
+                return emit(shownOf(result), outcome, parsed, io);
+            const out = asText(data.stdout), err = asText(data.stderr);
+            if (out)
+                io.out(out);
+            if (err)
+                io.err(err);
+            stdoutCursor = typeof data.stdoutCursor === "number" ? data.stdoutCursor : stdoutCursor;
+            stderrCursor = typeof data.stderrCursor === "number" ? data.stderrCursor : stderrCursor;
+            if (data.running === false)
+                return typeof data.exitCode === "number" && data.exitCode !== 0 ? EXIT.tool : EXIT.ok;
+            await sleep(1000);
+        }
+    });
+}
+async function readCommand(args, io) {
+    const parsed = parseArgs(args, { flags: COMMON_FLAGS, values: [...COMMON_VALUES, "--lines"] });
+    if (parsed.positionals.length !== 1)
+        throw new ControllerError("Usage: frely read <device>:<path> [--lines a:b]", EXIT.cli);
+    const { device, path } = requireRemote(parsed.positionals[0]);
+    let range = {};
+    const lines = parsed.values.get("--lines");
+    if (lines !== undefined) {
+        const match = /^(\d+):(\d*)$/u.exec(lines);
+        if (!match || Number(match[1]) < 1)
+            throw new ControllerError("--lines must look like 10:40 (or 10: for the rest of the file).", EXIT.cli);
+        range = { startLine: Number(match[1]), ...(match[2] ? { endLine: Number(match[2]) } : {}) };
+    }
+    return toolCall(io, parsed, "read", { device, action: "read", path, ...range });
+}
+async function ls(args, io) {
+    const parsed = parseArgs(args, { flags: COMMON_FLAGS, values: COMMON_VALUES });
+    if (parsed.positionals.length > 1)
+        throw new ControllerError("Usage: frely ls [<device>:<path>]", EXIT.cli);
+    const [target] = parsed.positionals;
+    if (target !== undefined && !target.includes(":"))
+        return toolCall(io, parsed, "read", { device: target, action: "roots" });
+    const { device, path } = requireRemote(target);
+    return toolCall(io, parsed, "read", { device, action: "list", path });
+}
+async function grep(args, io) {
+    const parsed = parseArgs(args, { flags: [...COMMON_FLAGS, "--regex", "--case"], values: [...COMMON_VALUES, "--max", "--context"] });
+    if (parsed.positionals.length !== 2)
+        throw new ControllerError("Usage: frely grep <device>:<path> <text> [--regex] [--case] [--max <n>] [--context <n>]", EXIT.cli);
+    const { device, path } = requireRemote(parsed.positionals[0]);
+    const max = intOption(parsed, "--max", 1, 1000), context = intOption(parsed, "--context", 0, 10);
+    return toolCall(io, parsed, "read", {
+        device, action: "search", path, query: parsed.positionals[1], regex: parsed.flags.has("--regex"), caseSensitive: parsed.flags.has("--case"),
+        ...(max !== undefined ? { maxResults: max } : {}), ...(context !== undefined ? { contextLines: context } : {}),
+    });
+}
+async function edit(args, io) {
+    const parsed = parseArgs(args, { flags: [...COMMON_FLAGS, "--overwrite"], values: [...COMMON_VALUES, "--from", "--patch"] });
+    if (parsed.positionals.length !== 1)
+        throw new ControllerError("Usage: frely edit <device>:<path> (--from <local file> | --patch <json file>) [--overwrite]", EXIT.cli);
+    const { device, path } = requireRemote(parsed.positionals[0]);
+    const from = parsed.values.get("--from"), patch = parsed.values.get("--patch");
+    if ((from === undefined) === (patch === undefined))
+        throw new ControllerError("Give exactly one of --from <local file> or --patch <json file>.", EXIT.cli);
+    let input;
+    if (from !== undefined) {
+        const data = await readLocal(from, "The file");
+        let text = null;
+        try {
+            text = new TextDecoder("utf-8", { fatal: true }).decode(data);
+        }
+        catch { /* Sent as binary below. */ }
+        input = { device, path, ...(text !== null ? { content: text } : { contentBase64: data.toString("base64") }), overwrite: parsed.flags.has("--overwrite") };
+    }
+    else {
+        let edits;
+        try {
+            edits = JSON.parse((await readLocal(patch, "The patch")).toString("utf8"));
+        }
+        catch (error) {
+            if (error instanceof ControllerError)
+                throw error;
+            throw new ControllerError(`The patch ${patch} is not valid JSON.`, EXIT.cli);
+        }
+        if (!Array.isArray(edits) || edits.length === 0)
+            throw new ControllerError("The patch must be a JSON array of { startLine, endLine, replacement }.", EXIT.cli);
+        input = { device, path, edits };
+    }
+    return toolCall(io, parsed, "edit_file", input);
+}
+async function toolsCommand(args, io) {
+    const parsed = parseArgs(args, { flags: COMMON_FLAGS, values: COMMON_VALUES });
+    return withController(io, async (controller) => {
+        const tools = await controller.tools();
+        const instructions = controller.instructions() ?? "";
+        const result = { content: [], structuredContent: { instructions, tools } };
+        const text = [instructions, ...tools.map((tool) => `${tool.name}${tool.annotations?.readOnlyHint ? " [read]" : ""}  ${(tool.description ?? "").replace(/\s+/gu, " ").slice(0, 160)}`)].filter(Boolean).join("\n\n");
+        return emit({ text, result: { ...result } }, { exitCode: EXIT.ok }, parsed, io);
+    });
+}
+/** `--json` takes a JSON object here (as in frely api call); a bare --json still asks for the full result. */
+function callArgs(args) {
+    const rest = [];
+    let json;
+    for (let i = 0; i < args.length; i++) {
+        const next = args[i + 1];
+        if (args[i] === "--json" && next !== undefined && /^\s*[{[]/u.test(next)) {
+            json = next;
+            i++;
+        }
+        else
+            rest.push(args[i]);
+    }
+    const parsed = parseArgs(rest, { flags: COMMON_FLAGS, values: [...COMMON_VALUES, "--input"] });
+    if (json !== undefined && parsed.values.has("--input"))
+        throw new ControllerError("Use --json '<object>' or --input <file>, not both.", EXIT.cli);
+    return { parsed, input: json !== undefined ? parseObject(json) : null };
+}
+function parseObject(text) {
+    let value;
+    try {
+        value = JSON.parse(text);
+    }
+    catch {
+        throw new ControllerError("The input is not valid JSON.", EXIT.cli);
+    }
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        throw new ControllerError("The input must be a JSON object.", EXIT.cli);
+    return value;
+}
+async function callCommand(args, io) {
+    const { parsed, input } = callArgs(args);
+    const [name] = parsed.positionals;
+    if (!name || parsed.positionals.length !== 1 || !/^[a-zA-Z0-9_.:-]{1,128}$/u.test(name))
+        throw new ControllerError("Usage: frely call <tool> [--json '<object>' | --input <file>]", EXIT.cli);
+    const file = parsed.values.get("--input");
+    const arguments_ = input ?? (file !== undefined ? parseObject((await readLocal(file, "The input")).toString("utf8")) : {});
+    return toolCall(io, parsed, name, arguments_);
+}
+async function permissionCommand(args, io) {
+    const [action, ...rest] = args;
+    if (action === "request") {
+        const parsed = parseArgs(rest, { flags: [...COMMON_FLAGS, "--no-wait"], values: [...COMMON_VALUES, "--resource", "--reason", "--command", "--cwd", "--mode"] });
+        const [device] = parsed.positionals;
+        const resource = parsed.values.get("--resource"), reason = parsed.values.get("--reason"), command = parsed.values.get("--command");
+        if (!device || parsed.positionals.length !== 1 || !resource || !reason || !command)
+            throw new ControllerError("Usage: frely permission request <device> --resource <name> --reason <text> --command <text> [--cwd <dir>] [--mode once|window|authorization]", EXIT.cli);
+        const mode = parsed.values.get("--mode");
+        if (mode !== undefined && !["once", "window", "authorization"].includes(mode))
+            throw new ControllerError("--mode must be once, window or authorization.", EXIT.cli);
+        return withController(io, async (controller) => {
+            const result = await controller.call("request_permission", { device, resource, reason, command, ...(parsed.values.has("--cwd") ? { cwd: parsed.values.get("--cwd") } : {}), ...(mode ? { mode } : {}) });
+            const outcome = outcomeOf(result);
+            // A person at a terminal waits here for the approval; a script or an AI gets the link and the wait command, and the exit code 3.
+            const code = resultData(result)?.shortCode;
+            if (outcome.exitCode !== EXIT.approval || typeof code !== "string" || !isInteractive() || parsed.flags.has("--no-wait") || parsed.flags.has("--json"))
+                return emit(shownOf(result), outcome, parsed, io);
+            io.out(resultText(result) + "\n");
+            io.err("Waiting for the owner to decide…\n");
+            return waitForPermission(controller, code, 10 * 60_000, io);
+        });
+    }
+    if (action === "confirm") {
+        const parsed = parseArgs(rest, { flags: COMMON_FLAGS, values: COMMON_VALUES });
+        const [code, choice] = parsed.positionals;
+        if (!code || parsed.positionals.length > 2 || (choice !== undefined && !/^[ABC]$/u.test(choice)))
+            throw new ControllerError("Usage: frely permission confirm <code> [A|B|C]", EXIT.cli);
+        return toolCall(io, parsed, "confirm_permission", { code, ...(choice ? { choice } : {}) });
+    }
+    if (action === "wait") {
+        const parsed = parseArgs(rest, { values: ["--then", "--timeout"] });
+        const [code] = parsed.positionals;
+        if (!code || parsed.positionals.length !== 1 || !/^[A-Za-z]{6}$/u.test(code))
+            throw new ControllerError("Usage: frely permission wait <six-letter short code> [--then '<command>'] [--timeout <s>]", EXIT.cli);
+        const timeout = intOption(parsed, "--timeout", 1, 3600) ?? 600;
+        const status = await withController(io, (controller) => waitForPermission(controller, code.toUpperCase(), timeout * 1000, io));
+        const then = parsed.values.get("--then");
+        if (status !== EXIT.ok || then === undefined)
+            return status;
+        // The approval of one command is bound to its exact text, so the command is run as given.
+        return new Promise((done, fail) => {
+            const child = spawn(then, { shell: true, stdio: "inherit" });
+            child.once("error", fail);
+            child.once("exit", (exit) => done(exit ?? EXIT.tool));
+        });
+    }
+    throw new ControllerError("Usage: frely permission request|confirm|wait. See frely permission --help.", EXIT.cli);
+}
+/** Polls the request until the owner decides: approved is 0, denied 2, and a request that ran out (or was revoked) or the time limit is 3, because approval is still needed. */
+export async function waitForPermission(controller, code, timeoutMs, io, options = {}) {
+    const { intervalMs = 3000, now = Date.now, sleep: wait = sleep } = options;
+    const deadline = now() + timeoutMs;
+    for (;;) {
+        const result = await controller.call("permission_status", { code });
+        const data = resultData(result);
+        if (result.isError === true || !data) {
+            io.err((resultText(result) || "The approval could not be checked.") + "\n");
+            return EXIT.tool;
+        }
+        switch (data.status) {
+            case "approved":
+                io.out(`Approved${typeof data.mode === "string" ? ` (${data.mode})` : ""}${typeof data.expiresAt === "string" ? ` until ${data.expiresAt}` : ""}. Run the command again unchanged.\n`);
+                return EXIT.ok;
+            case "denied":
+                io.err("The owner denied this request.\n");
+                return EXIT.tool;
+            case "expired":
+            case "revoked":
+                io.err(`The request is ${String(data.status)}. Ask for it again.\n`);
+                return EXIT.approval;
+            default: break;
+        }
+        if (now() + intervalMs >= deadline) {
+            io.err("Still waiting for the owner. Run frely permission wait again to keep waiting.\n");
+            return EXIT.approval;
+        }
+        await wait(intervalMs);
+    }
+}
+//# sourceMappingURL=commands.js.map