frely-cli 0.6.10 → 0.8.3

package/README.zh-CN.md

@@ -0,0 +1,230 @@
+# frely-cli
+
+[English](README.md) · [简体中文](README.zh-CN.md)
+
+`frely-cli` 把你指定的一台电脑变成 AI Agent 可以远程操作的安全设备。浏览器 Agent（ChatGPT、Codex）和命令行 Agent（Claude Code、pi）通过 Model Context Protocol（MCP）连接，访问你授权的工作区（workspace）内的文件、命令与进程——在任何地方。
+
+两个可选功能，各自有独立的配置与授权：
+
+- **Remote Agent Skill** —— 把已发布的 Frely Agent 安装为本地触发 Skill，从自动化流程中调用。
+- **本地模型共享** —— 把本机 Ollama / OpenAI 兼容运行时发布为你的 Frely 个人 Provider。
+
+本仓库包含开源的 Frely 客户端与本地 MCP 运行时；托管的 Frely Relay 控制面是独立的服务依赖。不存在独立的 `friday-local` 项目，本地 MCP 执行属于 `frely-cli`。
+
+```text
+Remote Agent Skill: 安装 -> frely login -> frely agent install -> frely agent run
+Device MCP:  在被控电脑安装 -> frely login -> frely mcp -> 客户端添加 MCP URL -> OAuth 授权
+```
+
+## 安装
+
+独立安装器（standalone installer）会选择平台可执行文件、校验 SHA-256 并安装到用户目录，不需要 Node.js、npm 或 keyring。
+
+```sh
+# macOS / Linux
+curl -fsSL https://frely.cloud/install.sh | sh
+```
+
+```powershell
+# Windows
+irm https://github.com/FrelyHQ/frely-cli/releases/latest/download/install.ps1 | iex
+```
+
+或使用 npm（需要 Node.js 22 或更新版本）：
+
+```sh
+npm install --global --ignore-scripts frely-cli@latest
+```
+
+要安装指定版本，把 `latest` 换成版本号。带 tag 的发布会在跨平台验证后同时发布 npm 包与 GitHub Release 独立安装产物。
+
+### 从源码安装
+
+用 Bun 安装当前源码：
+
+```sh
+cd /path/to/frely-cli
+bun install
+bun run build
+bun install --global "$PWD"
+```
+
+全局安装命令请使用 `$PWD` 绝对路径。如果找不到 `frely`，把 Bun 全局 bin 目录加入 `PATH`：
+
+```sh
+export PATH="$(bun pm bin -g):$PATH"
+```
+
+当前源码没有 keytar 依赖和原生 npm 构建步骤。依赖安装支持 `npm ci --ignore-scripts` 与 `bun install --ignore-scripts`。仓库以 npm 作为 CI 与发布的规范包管理器并提交 `package-lock.json`；Bun 仅用于本地开发，变更依赖时请保持 lockfile 同步。
+
+## 首次使用
+
+用消费端使用的 Frely 账号登录一次：
+
+```sh
+frely login
+```
+
+浏览器会自动打开。要换浏览器或换账号，运行 `frely login --no-browser`，并把打印的 URL 只在你想要的那个账号已登录的浏览器中打开。在已登录状态下访问设备授权 URL，可能在点击 Approve 之前就把该码绑定到那个账号——如果默认浏览器用别的账号打开了，按 Ctrl+C，重新运行 `frely login --no-browser`，使用**新的 URL**。重新登录或复用旧 URL 都不会切换账号。使用自建 Relay 时请保留 `--relay <url>`。`FRELY_NO_BROWSER=1` 仍然支持。
+
+### Device MCP：让远程客户端控制这台电脑
+
+在被控电脑上开启文件、shell 与进程访问：
+
+```sh
+frely mcp --workspace /path/to/project
+```
+
+`frely login` 通过浏览器设备授权获取受限账号会话。首次运行 `frely mcp` 会初始化独立的 MCP 安全密钥、请求浏览器批准该设备与工作区（省略 `--workspace` 时为当前目录）、安装用户级 Device Relay 服务（macOS LaunchAgent、Linux systemd 用户单元或 Windows 任务计划程序），并打印 MCP URL。默认授权 90 天，`--days 1..180` 可选时长。
+
+`frely mcp` 是幂等的：启用后再次运行只打印同一个 URL，需要地址时直接再运行即可。提示走 stderr，stdout 保持单一 URL（或 `--json` 时一个 JSON 对象）；批准或安装失败则不打印 URL。要开放更多目录，用 `frely mcp workspace add <path>`；`frely mcp workspace` 列出所有目录。
+
+把打印的完整 URL 添加到支持 OAuth 的远程 MCP 客户端，选择 OAuth 并完成授权。保持电脑在线。验证首次连接：让客户端只列出所选工作区的顶层名称，不写文件、不跑 shell 命令——返回与目录一致的结果即连通。
+
+调用端的 Claude Code：
+
+```sh
+claude mcp add --transport http frely-computer "<MCP_URL>"
+```
+
+在 Claude Code 中打开 `/mcp` 完成 OAuth 授权。每台设备使用不同的服务器名。让 Agent 用 Frely 工具做远程工作；它自带的 shell 仍跑在调用端电脑。同一设备的客户端共享其工作区与托管进程。
+
+授权生命周期：授权过期后，`frely mcp` 会请求新的批准并轮换 MCP 执行密钥；`frely mcp --days 180` 可提前续期。MCP URL 始终绑定该设备。登录刷新、OAuth 刷新与重启都不延长授权。`frely mcp stop|start` 暂停或恢复后台服务；`frely mcp remove` 撤销所有客户端的访问并卸载服务（本机有本地 Provider 时服务改为仅 Provider 模式继续运行）。在 Frely → **Device MCP**（`/user/account/connections`）管理你的设备。
+
+### 调用 Frely 托管的 Agent
+
+使用有账号或受限 API-key 访问权限的已发布 Agent。安装为本地触发 Skill（也可以用完整 manifest URL 代替 id）：
+
+```sh
+frely agent install <distribution-id> \
+  --host pi \
+  --scope global \
+  --json
+```
+
+Creator 也可以提供一个现成的模型级、限额 API key 用于赞助/演示调用。只通过 stdin 传入，避免出现在 argv 或生成的 Skill 中：
+
+```sh
+printf '%s' "$FRELY_AGENT_KEY" | \
+  frely agent install <distribution-id> \
+    --host chatgpt \
+    --scope global \
+    --api-key-stdin \
+    --json
+```
+
+CLI 会用目标模型级 MCP `tools/list` 端点验证 key，存入安全凭证库，在托管 Skill 元数据中只记录 `authMode=api-key`。分享请使用短生命周期、单模型、限额的 key；不要把 Creator 主 key 贴进去。
+
+生成的 Skill 通过 Frely 的模型级 MCP 端点调用已发布 Agent。从自动化调用已安装 Agent，完整任务走 stdin：
+
+```sh
+printf '%s' '你的完整任务' | \
+  frely agent run '<distribution-id>' --input-stdin --json
+```
+
+`frely agent status <distribution-id>` 查看已安装的 Skill，API-key 安装时同时显示该 Key 的预算。`frely agent remove <distribution-id>` 删除 Skill 及其保存的 key。
+
+## 本地模型共享
+
+把回环（loopback）OpenAI 兼容运行时发布为 Frely 个人 Provider，Ollama 是默认驱动：
+
+```sh
+frely provider share ollama
+```
+
+自定义端点与模型选择：
+
+```sh
+frely provider share openai-compatible \
+  --url http://127.0.0.1:8080/v1 \
+  --models model-a,model-b \
+  --slot <personal-provider-slot-id> \
+  --name "Local GPU"
+```
+
+要求：已登录 Frely、一个空闲的活跃个人 Provider slot、回环 HTTP、OpenAI 兼容 `/v1`（Ollama 默认端点 `http://127.0.0.1:11434/v1`）。模型名不能包含空格或 `/`。
+
+该命令创建服务端管理的 `openai-compatible` 个人 Provider，把本地端点存入仅属主可读的 CLI 状态，启动 Device Relay 服务，用设备 Ed25519 key 签署 Provider 凭证，配置 CPA 并启用声明的模型。现有 Frely Access Point 与 API-key 流程即可消费该 Provider。
+
+Provider 检查：
+
+```sh
+frely provider list
+```
+
+如果 Provider 已准备但设置中途失败，再运行一次 `frely provider share` 即可：它会续完该 Provider，而不是新建一个。
+
+## 升级与诊断
+
+```sh
+frely doctor      # 当前账号、安装路径、发行形态、最新稳定版、MCP/服务状态
+frely doctor -v   # 另加配置路径、运行时细节、授权到期、最近心跳、脱敏错误
+frely upgrade     # 原地升级当前正在运行的安装
+```
+
+`frely upgrade` 永不换安装器、不改 PATH、不降级更新版本。standalone 下载会先校验 SHA-256 并做启动测试再替换可执行文件；npm/Bun 安装保持原全局目录。匹配的、正在运行的 Device Relay 服务会被暂停维护、重启并在安装后检查；凭证、设备身份、MCP URL、工作区与授权到期均保留。Windows 上 `upgrade` 打印检测到安装方式对应的 PowerShell 命令，请在本地终端执行。
+
+`frely doctor` 是唯一诊断入口，永不重启服务。“Connected” 表示匹配的账号/设备进程在 75 秒内收到 WebSocket 心跳，且 MCP 授权与工作区与运行中的 relay 匹配。两种模式都不代替客户端完成 OAuth 授权，也不代替执行工具调用。`frely doctor --mcp` 是检查受保护凭证和服务端授权状态的推荐方式。
+
+完整行为：[self-upgrade 契约](docs/self-upgrade.md) 与[服务维护与旧版本迁移](docs/service-maintenance.md)。若安装了多个 `frely`，升级前先查看 `doctor` 显示的路径。
+
+## 本地执行边界
+
+本地 MCP 服务暴露：工作区检查、文件搜索/读/写/补丁、目录创建/删除/移动、shell 命令、常驻进程管理。
+
+文件系统工具约束在所选工作区内：拒绝 symlink 逃逸、普通文件读写上限 1 MiB、no-follow 读、原子替换写。`run_command` 与常驻进程工具以当前 OS 用户权限执行；工作区只约束它们的工作目录，**不是** shell 沙箱。
+
+只读本地操作可以并行；写与 shell 操作走本地公平调度器——避免了设备级 `busy -> 429` 行为。
+
+## 认证与密钥
+
+基础账号会话与 Network 会话使用私有明文文件，不能批准 MCP 授权，也不能在显式范围外调用账号管理操作。Provider key 与 MCP 执行 key 相互独立。
+
+MCP 密钥使用 AES-256-GCM 文件，主密钥存 macOS Keychain、Windows 凭据管理器或 Linux Secret Service。无头部署可通过 `FRELY_CREDENTIAL_KEY` 注入 32 字节 key 并设 `FRELY_CREDENTIAL_STORE=encrypted-file`。MCP 没有明文回退；安全存储失败不影响基础功能。
+
+稳定的 MCP URL 不含凭证。远程客户端持有 OAuth 凭证；CLI 持有 MCP 执行私钥。Relay 校验 OAuth 资源绑定与当前 MCP 执行租约。到期会阻塞请求与排队任务、取消托管执行，但不回滚写入，也不为任意 shell 程序提供沙箱。
+
+存储、迁移、服务注入、发布要求与威胁边界：[凭证与安装边界](docs/credential-storage.md)。
+
+## 架构
+
+- 产品定义与通用客户端接入：[docs/device-mcp.md](docs/device-mcp.md)
+- Device Relay 传输：子协议、连接 grant、重连、回退状态机：[docs/device-transport.md](docs/device-transport.md)
+- Relay OAuth 2.1 Authorization Code + PKCE、发现与 token 端点：[docs/mcp-oauth-relay-contract.md](docs/mcp-oauth-relay-contract.md)
+- Cloud 命令与授权：[docs/cloud.md](docs/cloud.md)
+- Frely Network 命令（预览，不在 `frely --help` 中列出）：[docs/frely-network.md](docs/frely-network.md)
+
+公网 MCP URL 是 Relay 返回的规范资源，例如 `https://connect.frely.cloud/mcp/<device-id>`。请使用 `frely mcp` 输出的地址，不要从控制面域名推导。URL 不含 bearer secret。
+
+## 命令
+
+```text
+frely login [--relay <https-url>] [--no-browser]
+frely logout
+frely doctor [-v] [--json]
+frely upgrade
+frely mcp [--workspace <path>] [--days 1..180] [--json]
+frely mcp workspace [add|remove <path>] [--json]
+frely mcp stop|start|remove
+frely agent install <distribution-id|manifest-url> [--host chatgpt|codex|claude-code|pi|generic] [--scope global|project] [--api-key-stdin] [--json]
+frely agent run <distribution-id> (--input <text>|--input-stdin) [--json]
+frely agent status (<distribution-id>|--api-key-stdin [--relay <url>]) [--json]
+frely agent remove <distribution-id> [--json]
+frely provider share [ollama|openai-compatible] [--url <loopback-v1-url>] [--models <a,b>] [--slot <slot-id>] [--name <name>]
+frely provider list [--json]
+frely cloud list|describe|call
+```
+
+以下命令不在 `frely --help` 中列出，但在 `frely help --agent --json` 中：`frely mcp stdio [--workspace <path>]` 通过 stdio 为本地 MCP 客户端提供工具；`frely mcp serve` 是后台服务运行的前台 Device Relay 客户端；`frely network` 是 Network 预览。
+
+`frely logout` 删除账号会话、撤销 Cloud 授权并尝试停止后台服务。
+
+## 落地页
+
+开源 CLI 落地页在 [`site/`](site/README.md)，与 CLI 同处 Apache-2.0 许可与商标政策下，为 `cli.frely.cloud` 准备，作为静态站点独立部署。网站资源不打进 npm 包。
+
+## 许可与商标
+
+`frely-cli` 采用 Apache License 2.0，见 [`LICENSE`](LICENSE)。Frely 名称、logo 与产品名不作为商标授权，见 [`TRADEMARKS.md`](TRADEMARKS.md)。
+
+开发指引见 [`CONTRIBUTING.md`](CONTRIBUTING.md)，私有漏洞报告见 [`SECURITY.md`](SECURITY.md)。

package/dist/agent/agent-service.d.ts

@@ -0,0 +1,77 @@
+import { type DiagnosticLog } from "../runtime/diagnostics.js";
+import { AgentHostSupervisor, type HostRequest } from "./supervisor.js";
+import { AgentStoreError, type AgentTaskRecord, type AgentTaskSource, TaskStore, type StoredAgentEvent } from "./task-store.js";
+import { type AgentHostTaskEvent } from "./protocol.js";
+import { branchNameForTask } from "./worktrees.js";
+export declare class AgentServiceError extends Error {
+    readonly code: AgentServiceErrorCode;
+    constructor(code: AgentServiceErrorCode, message?: string);
+}
+export type AgentServiceErrorCode = "invalid_args" | "task_not_found" | "workspace_not_git_repo" | "workspace_dirty" | "too_many_tasks" | "rate_limited" | "invalid_state" | "budget_exceeded" | "remote_control_disabled" | "app_not_installed" | "host_unavailable" | "internal";
+export type AgentRuntimeConfig = {
+    schemaVersion: 1;
+    remoteControlEnabled: boolean;
+    defaultMaxCostUsd: number;
+    maxCostUsdLimit: number;
+    maxConcurrentTasks: number;
+};
+export declare const DEFAULT_AGENT_CONFIG: AgentRuntimeConfig;
+export declare function loadAgentConfig(env?: NodeJS.ProcessEnv): Promise<AgentRuntimeConfig>;
+export declare function saveAgentConfig(config: AgentRuntimeConfig, env?: NodeJS.ProcessEnv): Promise<void>;
+export type StartTaskInput = {
+    workspace: string;
+    goal: string;
+    model?: string;
+    maxCostUsd?: number;
+    source: AgentTaskSource;
+};
+export declare class AgentService {
+    private readonly deps;
+    private readonly executors;
+    private readonly scheduler;
+    private credentialsSent;
+    private budgetCancels;
+    private _supervisor;
+    constructor(deps: {
+        store: TaskStore;
+        resolveSupervisor: () => AgentHostSupervisor;
+        modelCredentials?: () => {
+            apiKey: string;
+            baseUrl: string;
+            model: string;
+        } | null;
+        config?: () => Promise<AgentRuntimeConfig>;
+        log?: DiagnosticLog;
+    });
+    supervisor(): AgentHostSupervisor;
+    startTask(input: StartTaskInput): Promise<AgentTaskRecord>;
+    listTasks(workspace?: string): Promise<AgentTaskRecord[]>;
+    getTask(id: string): Promise<AgentTaskRecord>;
+    getEvents(id: string, cursor?: number): Promise<{
+        events: StoredAgentEvent[];
+        nextCursor: number | null;
+    }>;
+    sendMessage(id: string, message: string): Promise<void>;
+    cancelTask(id: string): Promise<AgentTaskRecord>;
+    private settleCancelled;
+    getDiff(id: string, path?: string): Promise<{
+        diff: string;
+        truncated: boolean;
+    }>;
+    requestMerge(id: string, note?: string): Promise<AgentTaskRecord>;
+    approveMerge(id: string, approvedBy: "gui" | "web"): Promise<AgentTaskRecord>;
+    discardTask(id: string): Promise<AgentTaskRecord>;
+    stopHost(): Promise<void>;
+    status(): {
+        host: ReturnType<AgentHostSupervisor["status"]>;
+    };
+    private ensureHostWithCredentials;
+    private debug;
+    private eventsQueue;
+    readonly onTaskEvent: (taskId: string, event: AgentHostTaskEvent) => void;
+    private handleTaskEvent;
+    readonly onHostLost: (error?: Error) => void;
+    private failRunningTasks;
+    readonly onToolRequest: (request: HostRequest, args: Record<string, unknown>, taskId: string) => Promise<unknown>;
+}
+export { TaskStore, AgentStoreError, branchNameForTask };

package/dist/agent/agent-service.js

@@ -0,0 +1,348 @@
+/**
+ * AgentService: orchestrates agent tasks end-to-end — validation, worktrees,
+ * the agent host process, events, budget, and the merge workflow. This is the
+ * single implementation behind the GUI, the device relay (`method: "agent"`),
+ * and the `frely app` CLI.
+ */
+import { randomBytes } from "node:crypto";
+import { mkdir, readFile, rename, writeFile } from "node:fs/promises";
+import { dirname } from "node:path";
+import { FairRwScheduler } from "../runtime/scheduler.js";
+import { AgentToolExecutor, toolKindFromMethod } from "./tool-executor.js";
+import { AGENT_DEFAULT_MAX_COST_USD, AGENT_MAX_COST_USD_LIMIT, AGENT_DEFAULT_MAX_CONCURRENT_TASKS, AGENT_START_RATE_LIMIT_PER_MINUTE, AGENT_TASK_MAX_GOAL_BYTES, AgentStoreError, agentConfigPath, isTerminalStatus, nextRuntimeStatus, TaskStore, } from "./task-store.js";
+import { newTaskId } from "./protocol.js";
+import { branchNameForTask, createTaskWorktree, mergeTaskBranch, removeTaskWorktree, taskDiff, WorktreeError } from "./worktrees.js";
+export class AgentServiceError extends Error {
+    code;
+    constructor(code, message) {
+        super(message ?? code);
+        this.code = code;
+        this.name = "AgentServiceError";
+    }
+}
+export const DEFAULT_AGENT_CONFIG = {
+    schemaVersion: 1,
+    remoteControlEnabled: false,
+    defaultMaxCostUsd: AGENT_DEFAULT_MAX_COST_USD,
+    maxCostUsdLimit: AGENT_MAX_COST_USD_LIMIT,
+    maxConcurrentTasks: AGENT_DEFAULT_MAX_CONCURRENT_TASKS,
+};
+export async function loadAgentConfig(env = process.env) {
+    try {
+        const raw = JSON.parse(await readFile(agentConfigPath(env), "utf8"));
+        return {
+            schemaVersion: 1,
+            remoteControlEnabled: raw.remoteControlEnabled === true,
+            defaultMaxCostUsd: boundedCost(raw.defaultMaxCostUsd, AGENT_DEFAULT_MAX_COST_USD),
+            maxCostUsdLimit: boundedCost(raw.maxCostUsdLimit, AGENT_MAX_COST_USD_LIMIT),
+            maxConcurrentTasks: boundedConcurrency(raw.maxConcurrentTasks),
+        };
+    }
+    catch {
+        return { ...DEFAULT_AGENT_CONFIG };
+    }
+}
+export async function saveAgentConfig(config, env = process.env) {
+    const path = agentConfigPath(env);
+    await mkdir(dirname(path), { recursive: true, mode: 0o700 });
+    const tmp = `${path}.${randomBytes(8).toString("hex")}.tmp`;
+    await writeFile(tmp, `${JSON.stringify(config, null, 2)}\n`, { encoding: "utf8", mode: 0o600 });
+    await rename(tmp, path);
+}
+function boundedCost(value, fallback) {
+    return typeof value === "number" && Number.isFinite(value) && value > 0 && value <= AGENT_MAX_COST_USD_LIMIT ? value : fallback;
+}
+function boundedConcurrency(value) {
+    return typeof value === "number" && Number.isSafeInteger(value) && value >= 1 && value <= 4 ? value : AGENT_DEFAULT_MAX_CONCURRENT_TASKS;
+}
+export class AgentService {
+    deps;
+    executors = new Map();
+    scheduler = new FairRwScheduler(4);
+    credentialsSent = false;
+    budgetCancels = new Set();
+    _supervisor = null;
+    constructor(deps) {
+        this.deps = deps;
+    }
+    supervisor() {
+        this._supervisor ??= this.deps.resolveSupervisor();
+        return this._supervisor;
+    }
+    async startTask(input) {
+        const goal = typeof input.goal === "string" ? input.goal.trim() : "";
+        if (goal.length === 0 || Buffer.byteLength(goal) > AGENT_TASK_MAX_GOAL_BYTES)
+            throw new AgentServiceError("invalid_args", "goal must be 1..65536 bytes.");
+        if (typeof input.workspace !== "string" || input.workspace.length === 0)
+            throw new AgentServiceError("invalid_args", "workspace is required.");
+        const config = (await this.deps.config?.()) ?? DEFAULT_AGENT_CONFIG;
+        if (input.source.kind !== "gui" && !config.remoteControlEnabled)
+            throw new AgentServiceError("remote_control_disabled", "Run `frely app remote enable` first.");
+        const maxCostUsd = boundedCost(input.maxCostUsd ?? config.defaultMaxCostUsd, config.defaultMaxCostUsd);
+        const tasks = await this.deps.store.list();
+        const now = Date.now();
+        const active = tasks.filter((task) => !isTerminalStatus(task.status));
+        if (active.length >= config.maxConcurrentTasks)
+            throw new AgentServiceError("too_many_tasks");
+        const recentStarts = tasks.filter((task) => now - Date.parse(task.createdAt) < 60_000).length;
+        if (recentStarts >= AGENT_START_RATE_LIMIT_PER_MINUTE)
+            throw new AgentServiceError("rate_limited");
+        let worktree;
+        const taskId = newTaskId();
+        try {
+            worktree = await createTaskWorktree(taskId, input.workspace);
+        }
+        catch (error) {
+            if (error instanceof WorktreeError) {
+                if (error.code === "not_a_git_repo")
+                    throw new AgentServiceError("workspace_not_git_repo");
+                if (error.code === "dirty_workspace")
+                    throw new AgentServiceError("workspace_dirty");
+            }
+            throw error;
+        }
+        const id = taskId;
+        const record = {
+            id,
+            source: input.source,
+            workspace: input.workspace,
+            worktreePath: worktree.path,
+            branch: worktree.branch,
+            baseBranch: worktree.baseBranch,
+            baseCommit: worktree.baseCommit,
+            goal,
+            model: input.model ?? null,
+            maxCostUsd,
+            status: "queued",
+            mergeStatus: "none",
+            usage: { inputTokens: 0, outputTokens: 0, costUsd: 0 },
+            error: null,
+            mergeRequest: null,
+            approval: null,
+            createdAt: new Date().toISOString(),
+            updatedAt: new Date().toISOString(),
+            settledAt: null,
+        };
+        await this.deps.store.create(record);
+        try {
+            const connection = await this.ensureHostWithCredentials();
+            this.executors.set(id, new AgentToolExecutor(worktree.path, this.scheduler));
+            await connection.request("task.start", {
+                taskId: id,
+                worktreePath: worktree.path,
+                goal,
+                model: input.model ?? null,
+                budgetUsd: maxCostUsd,
+                baseBranch: worktree.baseBranch,
+                baseCommit: worktree.baseCommit,
+            });
+        }
+        catch (error) {
+            this.executors.delete(id);
+            await this.deps.store.update(id, (task) => ({ ...task, status: "failed", error: error instanceof Error ? error.message : "task start failed", settledAt: new Date().toISOString() }));
+            await this.deps.store.appendEvent(id, { type: "status", status: "failed", detail: "Agent host unavailable." });
+            if (error instanceof AgentServiceError)
+                throw error;
+            throw new AgentServiceError("host_unavailable", error instanceof Error ? error.message : "agent host unavailable");
+        }
+        return (await this.deps.store.read(id));
+    }
+    async listTasks(workspace) {
+        const tasks = await this.deps.store.list();
+        return workspace ? tasks.filter((task) => task.workspace === workspace) : tasks;
+    }
+    async getTask(id) {
+        return this.deps.store.read(id);
+    }
+    async getEvents(id, cursor = 0) {
+        return this.deps.store.readEvents(id, cursor);
+    }
+    async sendMessage(id, message) {
+        if (typeof message !== "string" || message.length === 0 || message.length > 64 * 1024)
+            throw new AgentServiceError("invalid_args");
+        const task = await this.deps.store.read(id);
+        if (task.status !== "running" && task.status !== "waiting_input")
+            throw new AgentServiceError("invalid_state", `Cannot send a message to a ${task.status} task.`);
+        const connection = await this.supervisor().ensureHost();
+        await connection.request("task.message", { taskId: id, message });
+    }
+    async cancelTask(id) {
+        const task = await this.deps.store.read(id);
+        if (isTerminalStatus(task.status))
+            return task;
+        if (task.status === "queued" && !this.executors.has(id)) {
+            return this.settleCancelled(id, "Cancelled before start.");
+        }
+        try {
+            const connection = await this.supervisor().ensureHost();
+            await connection.request("task.cancel", { taskId: id, reason: "User requested cancellation." }, 10_000);
+        }
+        catch (error) {
+            this.debug("agent.task.cancel_failed", id, error);
+            return this.settleCancelled(id, "Cancelled (host unreachable).");
+        }
+        return this.deps.store.read(id);
+    }
+    async settleCancelled(id, detail) {
+        this.executors.delete(id);
+        const record = await this.deps.store.update(id, (task) => ({ ...task, status: "cancelled", settledAt: new Date().toISOString() }));
+        await this.deps.store.appendEvent(id, { type: "status", status: "cancelled", detail });
+        return record;
+    }
+    async getDiff(id, path) {
+        const task = await this.deps.store.read(id);
+        try {
+            return await taskDiff(id, task.workspace, path);
+        }
+        catch (error) {
+            if (error instanceof WorktreeError && error.code === "not_a_git_repo")
+                throw new AgentServiceError("workspace_not_git_repo");
+            throw new AgentServiceError("internal", error instanceof Error ? error.message : "diff failed");
+        }
+    }
+    async requestMerge(id, note) {
+        const task = await this.deps.store.read(id);
+        if (task.status !== "completed")
+            throw new AgentServiceError("invalid_state", "Only completed tasks can request a merge.");
+        if (task.mergeStatus !== "none")
+            throw new AgentServiceError("invalid_state", `Merge already ${task.mergeStatus}.`);
+        return this.deps.store.update(id, (record) => ({
+            ...record,
+            mergeStatus: "merge_requested",
+            mergeRequest: { requestedAt: new Date().toISOString(), ...(note !== undefined && note.length > 0 ? { note: note.slice(0, 2048) } : {}) },
+        }));
+    }
+    async approveMerge(id, approvedBy) {
+        const task = await this.deps.store.read(id);
+        if (task.mergeStatus !== "merge_requested")
+            throw new AgentServiceError("invalid_state", `Merge state is ${task.mergeStatus}.`);
+        const approved = await this.deps.store.update(id, (record) => ({
+            ...record,
+            mergeStatus: "approved",
+            approval: { approvedAt: new Date().toISOString(), approvedBy },
+        }));
+        const outcome = await mergeTaskBranch(id, task.workspace);
+        if (outcome.status === "merged") {
+            await removeTaskWorktree(id, task.workspace).catch(() => undefined);
+            return this.deps.store.update(id, (record) => ({ ...record, mergeStatus: "merged" }));
+        }
+        return this.deps.store.update(id, (record) => ({ ...record, mergeStatus: "merge_conflict", error: outcome.detail }));
+    }
+    async discardTask(id) {
+        const task = await this.deps.store.read(id);
+        if (task.mergeStatus === "merged" || task.mergeStatus === "discarded")
+            throw new AgentServiceError("invalid_state", `Task already ${task.mergeStatus}.`);
+        await removeTaskWorktree(id, task.workspace).catch(() => undefined);
+        this.executors.delete(id);
+        return this.deps.store.update(id, (record) => ({ ...record, mergeStatus: "discarded" }));
+    }
+    async stopHost() {
+        for (const executor of this.executors.values())
+            executor.dispose();
+        this.executors.clear();
+        await this.supervisor().stop();
+    }
+    status() {
+        return { host: this.supervisor().status() };
+    }
+    // --- host wiring ---------------------------------------------------------
+    async ensureHostWithCredentials() {
+        const connection = await this.supervisor().ensureHost();
+        if (!this.credentialsSent) {
+            const credentials = this.deps.modelCredentials?.();
+            if (credentials)
+                connection.notify("model.credentials", credentials);
+            this.credentialsSent = true;
+        }
+        return connection;
+    }
+    debug(event, taskId, error) {
+        this.deps.log?.(JSON.stringify({ timestamp: new Date().toISOString(), pid: process.pid, event, taskId, ...(error ? { error: error instanceof Error ? error.message : String(error) } : {}) }));
+    }
+    eventsQueue = Promise.resolve();
+    onTaskEvent = (taskId, event) => {
+        // Hosts may burst events in a single tick (e.g. running+completed); apply them
+        // strictly in arrival order so a late non-terminal write cannot overwrite a terminal one.
+        this.eventsQueue = this.eventsQueue
+            .then(() => this.handleTaskEvent(taskId, event))
+            .catch((error) => this.debug("agent.event_apply_failed", taskId, error));
+    };
+    async handleTaskEvent(taskId, event) {
+        if (event.type === "status") {
+            const current = await this.deps.store.read(taskId).catch(() => null);
+            if (!current)
+                return;
+            const next = nextRuntimeStatus(current.status, event);
+            if (next === null) {
+                this.debug("agent.task.status_rejected", taskId);
+                return;
+            }
+            await this.deps.store.update(taskId, (task) => ({
+                ...task,
+                status: next,
+                error: next === "failed" ? event.detail ?? "Task failed." : task.error,
+                settledAt: isTerminalStatus(next) ? new Date().toISOString() : task.settledAt,
+            }));
+            if (isTerminalStatus(next)) {
+                this.executors.get(taskId)?.dispose();
+                this.executors.delete(taskId);
+                void this.supervisor().ensureHost().then((connection) => connection.request("session.dispose", { taskId }, 5_000)).catch(() => undefined);
+            }
+        }
+        if (event.type === "usage") {
+            const task = await this.deps.store.read(taskId).catch(() => null);
+            if (!task)
+                return;
+            await this.deps.store.update(taskId, (record) => ({
+                ...record,
+                usage: {
+                    inputTokens: record.usage.inputTokens + event.inputTokens,
+                    outputTokens: record.usage.outputTokens + event.outputTokens,
+                    costUsd: Math.max(record.usage.costUsd, event.costUsd),
+                },
+            }));
+            const latest = await this.deps.store.read(taskId);
+            if (latest.usage.costUsd >= latest.maxCostUsd && !isTerminalStatus(latest.status) && !this.budgetCancels.has(taskId)) {
+                this.budgetCancels.add(taskId);
+                void this.supervisor()
+                    .ensureHost()
+                    .then((connection) => connection.request("task.cancel", { taskId, reason: "Budget limit reached." }, 10_000))
+                    .catch(() => this.settleCancelled(taskId, "Budget limit reached (host unreachable)."));
+            }
+        }
+        await this.deps.store.appendEvent(taskId, event);
+    }
+    onHostLost = (error) => {
+        this.credentialsSent = false;
+        this.budgetCancels.clear();
+        void this.failRunningTasks(error).catch(() => undefined);
+    };
+    async failRunningTasks(error) {
+        const detail = error ? `Agent host exited unexpectedly: ${error.message}` : "Agent host exited unexpectedly.";
+        for (const task of await this.deps.store.list()) {
+            if (isTerminalStatus(task.status))
+                continue;
+            this.executors.delete(task.id);
+            await this.deps.store.update(task.id, (record) => ({ ...record, status: "failed", error: detail, settledAt: new Date().toISOString() }));
+            await this.deps.store.appendEvent(task.id, { type: "status", status: "failed", detail });
+        }
+    }
+    onToolRequest = async (request, args, taskId) => {
+        const kind = toolKindFromMethod(request.method);
+        if (!kind)
+            throw new Error(`Unsupported tool method: ${request.method}`);
+        const executor = this.executors.get(taskId);
+        if (!executor) {
+            const task = await this.deps.store.read(taskId).catch(() => null);
+            if (!task)
+                throw new Error("Unknown task.");
+            throw new Error(`Task ${taskId} is ${task.status}; tools are unavailable.`);
+        }
+        const result = await executor.execute(kind, args);
+        if (!result.ok)
+            throw new Error(result.error.message);
+        return result.result;
+    };
+}
+export { TaskStore, AgentStoreError, branchNameForTask };
+//# sourceMappingURL=agent-service.js.map