frely-cli 0.6.10 → 0.8.3

package/dist/agent/ops-stdio.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ops-stdio.js","sourceRoot":"","sources":["../../src/agent/ops-stdio.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AACH,OAAO,EAAE,OAAO,EAAe,MAAM,UAAU,CAAC;AAChD,OAAO,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AAEhD,OAAO,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AAChD,OAAO,EAAE,kBAAkB,EAAE,MAAM,iBAAiB,CAAC;AAErD,MAAM,CAAC,KAAK,UAAU,sBAAsB,CAAC,IAA0F;IACrI,MAAM,UAAU,GAAG,GAAG,aAAa,EAAE,WAAW,CAAC;IACjD,MAAM,KAAK,GAAG,MAAM,kBAAkB,CAAC,UAAU,EAAE,IAAI,CAAC,CAAC;IACzD,IAAI,CAAC,KAAK,CAAC,OAAO,EAAE,CAAC;QACnB,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,wCAAwC,UAAU,oCAAoC,CAAC,CAAC;QAC1G,OAAO,CAAC,CAAC;IACX,CAAC;IACD,MAAM,IAAI,OAAO,CAAS,CAAC,OAAO,EAAE,EAAE;QACpC,IAAI,OAAO,GAAG,KAAK,CAAC;QACpB,MAAM,MAAM,GAAG,CAAC,IAAY,EAAE,EAAE;YAC9B,IAAI,CAAC,OAAO,EAAE,CAAC;gBACb,OAAO,GAAG,IAAI,CAAC;gBACf,OAAO,CAAC,IAAI,CAAC,CAAC;YAChB,CAAC;QACH,CAAC,CAAC;QACF,MAAM,MAAM,GAAW,OAAO,CAAC,UAAU,CAAC,CAAC;QAC3C,MAAM,CAAC,EAAE,CAAC,OAAO,EAAE,CAAC,KAAK,EAAE,EAAE;YAC3B,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,4BAA4B,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;YAC1G,MAAM,CAAC,CAAC,CAAC,CAAC;QACZ,CAAC,CAAC,CAAC;QACH,MAAM,CAAC,EAAE,CAAC,OAAO,EAAE,GAAG,EAAE,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC;QACpC,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;QACzB,MAAM,KAAK,GAAG,eAAe,CAAC,EAAE,KAAK,EAAE,IAAI,CAAC,KAAK,EAAE,CAAC,CAAC;QACrD,KAAK,CAAC,EAAE,CAAC,MAAM,EAAE,CAAC,IAAI,EAAE,EAAE;YACxB,IAAI,IAAI,CAAC,IAAI,EAAE,CAAC,MAAM,GAAG,CAAC,IAAI,CAAC,MAAM,CAAC,SAAS;gBAAE,MAAM,CAAC,KAAK,CAAC,GAAG,IAAI,IAAI,CAAC,CAAC;QAC7E,CAAC,CAAC,CAAC;QACH,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC,OAAO,EAAE,GAAG,EAAE,CAAC,MAAM,CAAC,GAAG,EAAE,CAAC,CAAC;QAC3C,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC,KAAK,EAAE,GAAG,EAAE,CAAC,MAAM,CAAC,GAAG,EAAE,CAAC,CAAC;IAC3C,CAAC,CAAC,CAAC;IACH,OAAO,CAAC,CAAC;AACX,CAAC"}

package/dist/agent/ops.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Shared agent-op dispatch (plan §5). The same op surface serves three
+ * transports: device-relay `method: "agent"` (remote web), the MCP frely-app
+ * toolset bridge, and the local GUI ops socket (M4). Each transport passes its
+ * own task `source` and merge `approvedBy` identity; only the ops socket gets
+ * the full task record (source, worktreePath, approval) because it never
+ * leaves the device.
+ */
+import type { AgentService } from "./agent-service.js";
+import type { AgentTaskRecord, AgentTaskSource } from "./task-store.js";
+export declare const AGENT_OPS: readonly ["agent_start_task", "agent_list_tasks", "agent_get_task", "agent_get_events", "agent_send_message", "agent_get_diff", "agent_request_merge", "agent_approve_merge", "agent_discard_task", "agent_cancel_task"];
+export type AgentOp = (typeof AGENT_OPS)[number];
+export declare class AgentOpError extends Error {
+    readonly code: string;
+    constructor(code: string, message?: string);
+}
+export type AgentOpIdentity = {
+    source: AgentTaskSource;
+    approvedBy: "gui" | "web";
+};
+export declare function isAgentOp(op: string): op is AgentOp;
+export declare function dispatchAgentOp(op: AgentOp, args: Record<string, unknown>, agent: AgentService, defaults: {
+    workspace: string;
+}, identity?: AgentOpIdentity): Promise<unknown>;
+export type { AgentTaskRecord };

package/dist/agent/ops.js

@@ -0,0 +1,82 @@
+export const AGENT_OPS = [
+    "agent_start_task",
+    "agent_list_tasks",
+    "agent_get_task",
+    "agent_get_events",
+    "agent_send_message",
+    "agent_get_diff",
+    "agent_request_merge",
+    "agent_approve_merge",
+    "agent_discard_task",
+    "agent_cancel_task",
+];
+export class AgentOpError extends Error {
+    code;
+    constructor(code, message) {
+        super(message ?? code);
+        this.code = code;
+        this.name = "AgentOpError";
+    }
+}
+export function isAgentOp(op) {
+    return AGENT_OPS.includes(op);
+}
+export async function dispatchAgentOp(op, args, agent, defaults, identity = { source: { kind: "web" }, approvedBy: "web" }) {
+    switch (op) {
+        case "agent_start_task": {
+            const task = await agent.startTask({
+                workspace: optionalString(args.workspace) ?? defaults.workspace,
+                goal: requiredString(args.goal, "goal"),
+                ...(typeof args.model === "string" && args.model.length > 0 ? { model: args.model } : {}),
+                ...(typeof args.maxCostUsd === "number" && Number.isFinite(args.maxCostUsd) ? { maxCostUsd: args.maxCostUsd } : {}),
+                source: identity.source,
+            });
+            return { task };
+        }
+        case "agent_list_tasks": {
+            const workspace = optionalString(args.workspace) ?? defaults.workspace;
+            return { tasks: await agent.listTasks(workspace) };
+        }
+        case "agent_get_task":
+            return { task: await agent.getTask(requiredTaskId(args)) };
+        case "agent_get_events": {
+            const cursor = optionalNumber(args.cursor) ?? 0;
+            const page = await agent.getEvents(requiredTaskId(args), Number.isSafeInteger(cursor) && cursor >= 0 ? cursor : 0);
+            return { events: page.events, nextCursor: page.nextCursor };
+        }
+        case "agent_send_message":
+            await agent.sendMessage(requiredTaskId(args), requiredString(args.message, "message"));
+            return { sent: true };
+        case "agent_get_diff": {
+            const result = await agent.getDiff(requiredTaskId(args), optionalString(args.path));
+            return { diff: result.diff, truncated: result.truncated };
+        }
+        case "agent_request_merge": {
+            const note = optionalString(args.note);
+            return { task: await agent.requestMerge(requiredTaskId(args), note) };
+        }
+        case "agent_approve_merge":
+            return { task: await agent.approveMerge(requiredTaskId(args), identity.approvedBy) };
+        case "agent_discard_task":
+            return { task: await agent.discardTask(requiredTaskId(args)) };
+        case "agent_cancel_task":
+            return { task: await agent.cancelTask(requiredTaskId(args)) };
+        default:
+            throw new AgentOpError("unknown_op", op);
+    }
+}
+function requiredTaskId(args) {
+    return requiredString(args.taskId, "taskId");
+}
+function requiredString(value, name) {
+    if (typeof value !== "string" || value.length === 0)
+        throw new AgentOpError("invalid_args", `${name} must be a non-empty string.`);
+    return value;
+}
+function optionalString(value) {
+    return typeof value === "string" && value.length > 0 ? value : undefined;
+}
+function optionalNumber(value) {
+    return typeof value === "number" && Number.isFinite(value) ? value : undefined;
+}
+//# sourceMappingURL=ops.js.map

package/dist/agent/ops.js.map

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

package/dist/agent/protocol.d.ts

@@ -0,0 +1,72 @@
+export declare const AGENT_HOST_PROTOCOL = "frely.agent-host.v1";
+export declare const AGENT_HOST_PROTOCOL_VERSION = 1;
+export declare const AGENT_HOST_MAX_FRAME_BYTES: number;
+export declare const AGENT_HOST_CONNECTION_KEY_ENV = "FRELY_AGENT_HOST_KEY";
+export type AgentHostTaskStatus = "running" | "waiting_input" | "completed" | "failed" | "cancelled";
+export type AgentHostTaskEvent = {
+    type: "status";
+    status: AgentHostTaskStatus;
+    detail?: string;
+} | {
+    type: "message";
+    role: "assistant" | "user" | "system";
+    text: string;
+    partial?: boolean;
+} | {
+    type: "tool_call";
+    tool: string;
+    summary: string;
+    state: "started" | "finished" | "failed";
+} | {
+    type: "usage";
+    inputTokens: number;
+    outputTokens: number;
+    costUsd: number;
+} | {
+    type: "log";
+    text: string;
+};
+export type JsonRpcId = number | string;
+export type JsonRpcRequest = {
+    jsonrpc: "2.0";
+    id?: JsonRpcId;
+    method: string;
+    params?: Record<string, unknown>;
+};
+export type JsonRpcResponse = {
+    jsonrpc: "2.0";
+    id: JsonRpcId;
+    result?: unknown;
+    error?: {
+        code: number;
+        message: string;
+        data?: unknown;
+    };
+};
+export type JsonRpcMessage = JsonRpcRequest | JsonRpcResponse | {
+    jsonrpc: "2.0";
+    method: string;
+    params?: Record<string, unknown>;
+};
+export declare class AgentHostProtocolError extends Error {
+    readonly code: "frame_invalid" | "frame_too_large" | "handshake_rejected" | "unexpected_frame";
+    constructor(code: "frame_invalid" | "frame_too_large" | "handshake_rejected" | "unexpected_frame");
+}
+export declare function newConnectionKey(): string;
+export declare function isValidTaskId(id: string): boolean;
+export declare function newTaskId(): string;
+/** Encode one NDJSON frame. */
+export declare function encodeAgentHostFrame(message: JsonRpcMessage): string;
+/** Decode one NDJSON frame (without the trailing newline). */
+export declare function decodeAgentHostFrame(line: Buffer | string): JsonRpcMessage;
+/** Validate and normalize a `task.event` notification params object. */
+export declare function decodeTaskEvent(params: unknown): {
+    taskId: string;
+    event: AgentHostTaskEvent;
+};
+export declare function isToolMethod(method: string): boolean;
+/** Validate params of a `tool.*` request from the host. Returns normalized args. */
+export declare function decodeToolParams(method: string, params: unknown): {
+    taskId: string;
+    args: Record<string, unknown>;
+};

package/dist/agent/protocol.js

@@ -0,0 +1,195 @@
+/**
+ * frely.agent-host.v1 — wire contract between the CLI (supervisor) and the
+ * Pi Node agent host. See docs/agent-host.md for the public description.
+ */
+import { randomBytes } from "node:crypto";
+export const AGENT_HOST_PROTOCOL = "frely.agent-host.v1";
+export const AGENT_HOST_PROTOCOL_VERSION = 1;
+export const AGENT_HOST_MAX_FRAME_BYTES = 1024 * 1024;
+export const AGENT_HOST_CONNECTION_KEY_ENV = "FRELY_AGENT_HOST_KEY";
+export class AgentHostProtocolError extends Error {
+    code;
+    constructor(code) {
+        super(code);
+        this.code = code;
+        this.name = "AgentHostProtocolError";
+    }
+}
+export function newConnectionKey() {
+    return randomBytes(32).toString("base64url");
+}
+export function isValidTaskId(id) {
+    return /^at_[a-z0-9]{24}$/u.test(id);
+}
+export function newTaskId() {
+    return `at_${randomBytes(12).toString("hex")}`;
+}
+/** Encode one NDJSON frame. */
+export function encodeAgentHostFrame(message) {
+    const line = JSON.stringify(message);
+    if (Buffer.byteLength(line) > AGENT_HOST_MAX_FRAME_BYTES)
+        throw new AgentHostProtocolError("frame_too_large");
+    return `${line}\n`;
+}
+/** Decode one NDJSON frame (without the trailing newline). */
+export function decodeAgentHostFrame(line) {
+    if (Buffer.byteLength(line) > AGENT_HOST_MAX_FRAME_BYTES)
+        throw new AgentHostProtocolError("frame_too_large");
+    let value;
+    try {
+        value = JSON.parse(Buffer.isBuffer(line) ? line.toString("utf8") : line);
+    }
+    catch {
+        throw new AgentHostProtocolError("frame_invalid");
+    }
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        throw new AgentHostProtocolError("frame_invalid");
+    const record = value;
+    if (record.jsonrpc !== "2.0")
+        throw new AgentHostProtocolError("frame_invalid");
+    if ("method" in record) {
+        if (typeof record.method !== "string" || record.method.length === 0)
+            throw new AgentHostProtocolError("frame_invalid");
+        if ("id" in record && record.id !== null && typeof record.id !== "number" && typeof record.id !== "string") {
+            throw new AgentHostProtocolError("frame_invalid");
+        }
+        if ("params" in record && record.params !== undefined && (typeof record.params !== "object" || record.params === null)) {
+            throw new AgentHostProtocolError("frame_invalid");
+        }
+        return value;
+    }
+    if (typeof record.id !== "number" && typeof record.id !== "string")
+        throw new AgentHostProtocolError("frame_invalid");
+    if (!("result" in record) && !("error" in record))
+        throw new AgentHostProtocolError("frame_invalid");
+    if ("error" in record && record.error !== undefined) {
+        const error = record.error;
+        if (!error || typeof error !== "object" || typeof error.code !== "number" || typeof error.message !== "string") {
+            throw new AgentHostProtocolError("frame_invalid");
+        }
+    }
+    return value;
+}
+/** Validate and normalize a `task.event` notification params object. */
+export function decodeTaskEvent(params) {
+    if (!params || typeof params !== "object")
+        throw new AgentHostProtocolError("frame_invalid");
+    const record = params;
+    if (typeof record.taskId !== "string" || !isValidTaskId(record.taskId))
+        throw new AgentHostProtocolError("frame_invalid");
+    const event = record.event;
+    if (!event || typeof event !== "object")
+        throw new AgentHostProtocolError("frame_invalid");
+    const item = event;
+    switch (item.type) {
+        case "status":
+            if (item.status !== "running" && item.status !== "waiting_input" && item.status !== "completed" && item.status !== "failed" && item.status !== "cancelled") {
+                throw new AgentHostProtocolError("frame_invalid");
+            }
+            if (item.detail !== undefined && typeof item.detail !== "string")
+                throw new AgentHostProtocolError("frame_invalid");
+            return { taskId: record.taskId, event: item };
+        case "message":
+            if (item.role !== "assistant" && item.role !== "user" && item.role !== "system")
+                throw new AgentHostProtocolError("frame_invalid");
+            if (typeof item.text !== "string" || item.text.length > 64 * 1024)
+                throw new AgentHostProtocolError("frame_invalid");
+            if (item.partial !== undefined && typeof item.partial !== "boolean")
+                throw new AgentHostProtocolError("frame_invalid");
+            return { taskId: record.taskId, event: item };
+        case "tool_call":
+            if (typeof item.tool !== "string" || typeof item.summary !== "string" || item.summary.length > 2048)
+                throw new AgentHostProtocolError("frame_invalid");
+            if (item.state !== "started" && item.state !== "finished" && item.state !== "failed")
+                throw new AgentHostProtocolError("frame_invalid");
+            return { taskId: record.taskId, event: item };
+        case "usage": {
+            for (const key of ["inputTokens", "outputTokens", "costUsd"]) {
+                const value = item[key];
+                if (typeof value !== "number" || !Number.isFinite(value) || value < 0)
+                    throw new AgentHostProtocolError("frame_invalid");
+            }
+            return { taskId: record.taskId, event: item };
+        }
+        case "log":
+            if (typeof item.text !== "string" || item.text.length > 4096)
+                throw new AgentHostProtocolError("frame_invalid");
+            return { taskId: record.taskId, event: item };
+        default:
+            throw new AgentHostProtocolError("frame_invalid");
+    }
+}
+const TOOL_METHODS = new Set(["tool.read", "tool.write", "tool.edit", "tool.bash", "tool.grep", "tool.find", "tool.ls"]);
+export function isToolMethod(method) {
+    return TOOL_METHODS.has(method);
+}
+/** Validate params of a `tool.*` request from the host. Returns normalized args. */
+export function decodeToolParams(method, params) {
+    if (!params || typeof params !== "object")
+        throw new AgentHostProtocolError("frame_invalid");
+    const record = params;
+    if (typeof record.taskId !== "string" || !isValidTaskId(record.taskId))
+        throw new AgentHostProtocolError("frame_invalid");
+    const { taskId, ...args } = record;
+    switch (method) {
+        case "tool.read":
+            requireString(args, "path");
+            break;
+        case "tool.write":
+            requireString(args, "path");
+            if (typeof args.content !== "string")
+                throw new AgentHostProtocolError("frame_invalid");
+            optionalBoolean(args, "overwrite");
+            break;
+        case "tool.edit":
+            requireString(args, "path");
+            if (!Array.isArray(args.edits) || args.edits.length === 0)
+                throw new AgentHostProtocolError("frame_invalid");
+            break;
+        case "tool.bash":
+            requireString(args, "command");
+            optionalString(args, "cwd");
+            if (args.timeoutMs !== undefined && (typeof args.timeoutMs !== "number" || !Number.isSafeInteger(args.timeoutMs) || args.timeoutMs < 100 || args.timeoutMs > 120_000)) {
+                throw new AgentHostProtocolError("frame_invalid");
+            }
+            break;
+        case "tool.grep":
+            requireString(args, "query");
+            optionalString(args, "path");
+            optionalBoolean(args, "regex");
+            optionalBoolean(args, "caseSensitive");
+            optionalInteger(args, "maxResults", 1, 200);
+            optionalInteger(args, "contextLines", 0, 5);
+            break;
+        case "tool.find":
+            requireString(args, "pattern");
+            optionalString(args, "path");
+            optionalInteger(args, "maxResults", 1, 500);
+            break;
+        case "tool.ls":
+            optionalString(args, "path");
+            break;
+        default:
+            throw new AgentHostProtocolError("frame_invalid");
+    }
+    return { taskId, args };
+}
+function requireString(args, key) {
+    if (typeof args[key] !== "string" || args[key].length === 0)
+        throw new AgentHostProtocolError("frame_invalid");
+}
+function optionalString(args, key) {
+    if (args[key] !== undefined && typeof args[key] !== "string")
+        throw new AgentHostProtocolError("frame_invalid");
+}
+function optionalBoolean(args, key) {
+    if (args[key] !== undefined && typeof args[key] !== "boolean")
+        throw new AgentHostProtocolError("frame_invalid");
+}
+function optionalInteger(args, key, min, max) {
+    const value = args[key];
+    if (value !== undefined && (typeof value !== "number" || !Number.isSafeInteger(value) || value < min || value > max)) {
+        throw new AgentHostProtocolError("frame_invalid");
+    }
+}
+//# sourceMappingURL=protocol.js.map

package/dist/agent/protocol.js.map

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

package/dist/agent/supervisor.d.ts

@@ -0,0 +1,80 @@
+/**
+ * Agent host supervisor: spawns the capsule agent host with a duplex fd3
+ * protocol pipe, performs the frely.agent-host.v1 handshake, forwards tool
+ * requests, and owns idle shutdown / crash handling.
+ */
+import { type ChildProcess } from "node:child_process";
+import { type DiagnosticLog } from "../runtime/diagnostics.js";
+import { type AgentHostTaskEvent, type JsonRpcId } from "./protocol.js";
+import { type CapsuleFacts, type AppInstall } from "./app-install.js";
+export declare const AGENT_HOST_IDLE_TIMEOUT_MS: number;
+export declare const AGENT_HOST_HANDSHAKE_TIMEOUT_MS = 15000;
+export type AgentHostStatus = "stopped" | "starting" | "running" | "failed";
+export type HostRequest = {
+    id: JsonRpcId;
+    method: string;
+    params: unknown;
+};
+/** JSON-RPC peer over the fd3 pipe of a spawned agent host. */
+export declare class AgentHostConnection {
+    readonly process: ChildProcess;
+    private readonly duplex;
+    private readonly log?;
+    private nextId;
+    private readonly pending;
+    private writeClosed;
+    private closeListeners;
+    private constructor();
+    static start(facts: CapsuleFacts, options: {
+        log?: DiagnosticLog | undefined;
+        onEvent?: (taskId: string, event: AgentHostTaskEvent) => void;
+        onToolRequest?: (request: HostRequest, args: Record<string, unknown>, taskId: string) => Promise<unknown>;
+    }): Promise<AgentHostConnection>;
+    private onEvent?;
+    private onToolRequest?;
+    private handshake;
+    request(method: string, params: Record<string, unknown>, timeoutMs?: number): Promise<unknown>;
+    notify(method: string, params: Record<string, unknown>): void;
+    respond(id: JsonRpcId, result: unknown): void;
+    respondError(id: JsonRpcId, code: number, message: string): void;
+    shutdown(graceMs?: number): Promise<void>;
+    kill(): void;
+    onClose(listener: (error?: Error) => void): void;
+    private write;
+    private handleLine;
+    private handleNotification;
+    private handleHostRequest;
+    private closed;
+    private close;
+}
+export declare function cliVersion(): string;
+/** Owns the single agent host process across tasks. */
+export declare class AgentHostSupervisor {
+    private readonly deps;
+    private connection;
+    private starting;
+    private idleTimer;
+    private state;
+    private lastError;
+    private integrityVerified;
+    private lastActivityAt;
+    constructor(deps: {
+        resolveFacts: () => Promise<CapsuleFacts>;
+        onEvent: (taskId: string, event: AgentHostTaskEvent) => void;
+        onToolRequest: (request: HostRequest, args: Record<string, unknown>, taskId: string) => Promise<unknown>;
+        onHostLost: (error?: Error) => void;
+        isIdle: () => boolean | Promise<boolean>;
+        log?: DiagnosticLog | undefined;
+        fullIntegrityVerification?: boolean;
+        appInstall?: (() => Promise<AppInstall>) | undefined;
+    });
+    status(): {
+        state: AgentHostStatus;
+        hostVersion: string | null;
+        lastError: string | null;
+    };
+    ensureHost(): Promise<AgentHostConnection>;
+    stop(): Promise<void>;
+    private armIdleTimer;
+    private disarmIdleTimer;
+}