Skip to content

Latest commit

 

History

History
504 lines (418 loc) · 44.4 KB

README.md

File metadata and controls

504 lines (418 loc) · 44.4 KB

OpenCove CLI

CLI 是 Control Surface client;业务状态由 Worker/application owner 管理。CLI 不直接修改业务数据库。

Agent terminals cannot answer permission dialogs, read or change private settings, run provider commands through prompts, or run plugin code through the API: those decisions belong to the human. Agent launches inherit Settings unless --full-access true|false chooses Full Access for that agent and its restarts. Project isolation is not yet enforced. For prompt rules and rewrite examples, see initial prompts.

智能体终端不能通过 API 回答权限弹窗、读取或修改私密设置或执行插件代码;这些决定由用户作出。Agent 启动默认继承 Settings,也可用 --full-access true|false 为该节点及其后续重启单独选择权限。目前尚未实施项目隔离。

Task coordination: claim tasks, release them and append shared results.

Commands

Group Commands
Identity whoami, context
project list, add
space list, get, create, update
node list [--root-canvas], get, create note/task/website/agent/terminal [--root-canvas], update note/task/website/agent/terminal, delete
canvas focus node, focus space
api ops, schema <operation-id>, call <operation-id>
Runtime ping, status, worker start/status/stop, runtime inspect/verify/prepare
endpoint list, register, ping, remove
mount list, create, resolve, remove
fs read, write, stat, ls; 可选 --mount <id>
worktree list, create, archive
agent list, get, prompt, delivery <id>, wait, read, stop, history clear
Agent guide skill [topic] (bundled, offline)
session run-agent, get, final, kill
pty spawn-in-mount, attach
plugin guide, list, details, install, install-git, source, check, update, apply, rollback, discover, reload, enable, disable, uninstall, run, skill, open, windows

旧拼写不提供 aliases。Mount 的项目选项只有 --project。 长文本支持 --content-file、--prompt-file、--params-file;文件路径 - 读取 stdin。 同一参数的 inline 和 file 形式互斥。fs write 保留 UTF-8 文本的空白、换行和空字符串。 Options that take a value accept leading dashes literally: --text "-v" and --title "--draft". Boolean flags and positional arguments keep their existing syntax. plugin install-git --build-output <path> 指定构建产物目录。

opencove fs write --mount mount-123 --uri file:///notes.txt --content-file ./notes.txt
opencove session run-agent --space space-123 --prompt-file ./task.txt
opencove plugin run sample status --params-file ./params.json

Space 创建、更新与项目添加 / Space creation, updates and project addition: 命令、输出与授权说明。

Output and exit codes

默认列表上限、错误重试表、终端历史读取和 quiet 创建输出见 CLI output。

成功 stdout 是 operation value JSON,不包含 {ok,value} 或 transport envelope。 fs write returns {uri, bytes} after a successful write; bytes is the UTF-8 byte count, including whitespace and newlines. JSON output ends with a newline. --pretty 格式化 JSON;--fields a,b 投影已声明的输出字段,包括支持此功能的专用 mutation 命令;generic api call mutation 和流式命令不支持投影;-o table 仅支持声明了 columns 的命令。 错误通常保持 stdout 为空;agent delivery 正常返回证据结果时,即使退出码为 1 也会输出 stdout,请解析该结果。非 TTY stderr 错误格式为 {"error":{"code":"...","message":"...","hint":"...","retryable":false,"candidates":[],"details":...}}。 error.candidates 提供歧义或建议候选项;旧的 details.candidates 保留但已弃用。TTY stderr 使用可读错误;-o json 强制 JSON 错误。 Plugin distribution 返回 failed/conflict 时 exit 1,candidate 结果位于 error.details。

Exit Meaning
0 成功(worker status 也可能返回 status: stopped)
1 operation、runtime 或远端进程失败
2 参数错误
3 无可用连接或 endpoint 不可达
4 认证或授权失败
5 Protocol incompatible or operation unsupported by an older Worker
6 profile/space 歧义
10 观察到 agent 等待;可能需要用户处理,先查看再行动
11 等待条件满足前,未完成目标已退出
124 请求、agent wait 或 PTY 握手超时
130 中断(agent wait 关闭流)或 PTY detach

Exit 5 also covers operations missing from an older Worker. Restart or update OpenCove, then retry. Ordinary invalid input still exits 2.

pty attach 是流式例外:stdout 只有原始终端输出,远端退出 0 → CLI 0,其他退出 → CLI 1,Ctrl-C detach → 130。 worker start 前台运行,结束后返回状态 JSON。Windows 通过父进程 IPC 请求 Worker 自身完成 drain 和 lock release;超过共享停止预算才强制终止。 runtime prepare 从 stdin 接收托管部署 JSON,成功返回 {"status":"prepared"}。 默认机器模式将子进程诊断保存在最终 error.details.diagnostics(最多 16,384 个 UTF-16 code units,截断时 diagnosticsTruncated: true),stderr 仍是单个 JSON 文档。TTY 可显示诊断;-o json 禁用隐式诊断输出。 worker start、runtime verify/prepare 可显式使用 --stream-progress:stderr 实时输出原始进度/诊断,失败时追加错误 JSON,因此该模式的 stderr 是流而非单个 JSON 文档。托管 SSH bootstrap 显式使用此模式。

Connection and context

连接 URL/token:环境 token 只随 OPENCOVE_CONTROL_URL 使用。显式 --endpoint 必须配 --token,即使 URL 与环境相同;profile discovery 使用该记录自己的 token,不借用环境 token。 没有 URL 时,--user-data 优先于 OPENCOVE_USER_DATA_DIR;显式 profile 不回退到其他目录。 未指定 profile 时搜索平台应用数据目录中的 opencove-dev 和 opencove。 普通命令检查 control-surface.json 和 worker-control-surface.json,忽略无效/已退出 PID;多个有效连接记录返回歧义错误。 worker status/stop 使用本地生命周期模块,仅检查 worker 记录;不接受 --endpoint。 Space locator 不推断 cwd:使用 --space、--space-name 或 --worker 与 --branch/--path,必要时用 --project 收窄。

node create 支持 --root-canvas,在项目画布上创建、不加入任何 Space;外部调用需同时指定 --project <selector>。在 OpenCove 内不指定目标时,node create 使用调用者节点的当前 Space,或在调用者不属于任何 Space 时使用 root canvas。node list 在后一种情况下默认列整个项目;node list --root-canvas 仅列 root 节点。显式 --project 单独用于创建仍会报错,需补 Space 目标或 --root-canvas。未指定 x/y 时,在 OpenCove 内优先放在你的节点或所在 Space 旁边;调用者节点属于其他项目时从原点寻找空位,不保证可见;若会话绑定的节点已删除,需从有效节点继续;用 --focus 显示新节点。详见 Canvas node control。

For agents creating helper nodes, recommend --near @self on node create note, node create terminal and node create agent. This explicit option prefers a free slot near the reference in its current direct Space (or root). Omitting it preserves current behavior. --near <node selector> supplies project/container context; an external full reference ID needs no --project. Explicit Space/project options must match; --root-canvas overrides membership. A size-only --frame (width/height) is allowed; x/y conflict with near placement. The CLI requires features.nodeNearPlacementV1 === true for both dedicated commands and api call; older Workers refuse with exit 5 before mutation. See near placement for bounds and retry semantics.

Help and introspection

opencove --help 显示分组及全局选项;opencove <group> --help 列子命令;命令级 --help 显示参数、示例与全局选项提示,不连接 Worker。 api ops 在 OpenCove session 外离线列出 operation;session 内使用 Worker 返回的 access 和 policyVersion,旧 Worker 则报告 access: unknown;api schema 只为有 schema 的 operation 提供输入 JSON Schema;session 内同时附带 Worker 的 access、reason、policyVersion 和受限字段 rejectedFields,字段出现在 schema 中不代表允许使用。 api call <operation-id> --input-file request.json 使用同一验证与连接路径。

开发构建:pnpm build:cli;入口为 node out/cli/opencove.mjs。

CLI help golden 更新使用 pnpm exec vitest run tests/unit/app/cliInputOutput.spec.ts tests/unit/app/cliOutputBehavior.spec.ts --update,不要手改生成的 snapshot。 Agent 创建帮助快照使用 pnpm exec vitest run tests/unit/app/cliNodeHelp.spec.ts --update 更新。

CLI 测试先运行 pnpm build:cli,再运行 pnpm exec vitest run tests/unit/app/cli*.spec.ts。 更新帮助 golden snapshots:pnpm build:cli 后运行 pnpm exec vitest run tests/unit/app/cliCore.spec.ts tests/unit/app/cliHelpErrors.spec.ts tests/unit/app/cliSchemaValidation.spec.ts tests/unit/app/cliAgentQueries.spec.ts tests/unit/app/cliSchemaValidation.spec.ts tests/unit/app/cliSkill.spec.ts tests/unit/app/cliEvents.spec.ts tests/unit/app/cliOutputBehavior.spec.ts tests/unit/app/cliHelpErrors.spec.ts tests/unit/app/cliCommandMapping.spec.ts tests/unit/app/cliOutputContracts.spec.ts tests/unit/app/cliNodeHelp.spec.ts --update;由 Vitest 生成,不手改 .snap。错误恢复 golden 使用 pnpm exec vitest run tests/unit/app/cliAgentPrompt.spec.ts tests/unit/app/cliAgentScreenAndState.spec.ts tests/unit/app/cliAgentHistoryClear.spec.ts --update 更新。Context 和 filesystem 帮助随对应测试更新:pnpm exec vitest run tests/unit/app/cliContext.spec.ts tests/unit/app/cliOutputContracts.spec.ts tests/unit/app/cliCommandMapping.spec.ts --update。新增命令的完整帮助 golden 由 cliHelpErrors.spec.ts 生成;节点 wire schema golden 使用 pnpm exec vitest run tests/contract/controlSurface/nodeSchemas.spec.ts --update 更新。

测试的 global setup 在系统临时目录重新构建并逐字节校验工作树中的 CLI 产物;产物缺失或过期时拒绝继续,不覆盖工作树,临时构建在成功或失败后都会清理。

Context state versus session lifecycle

context.self preserves caller identity and adds node, a compact summary with id, kind, title and state. It describes the caller even when the requested project or Space differs. Without caller identity, self is null; if the node was deleted, self.node is null. --fields self.node.id,self.node.state selects these fields.

For agent neighbors, context.nodes[].state is the Worker run state from agent.list: idle, working, waiting, exited or unknown. Missing run observations are unknown; lifecycle is never used as readiness evidence. sessionStatus keeps the agent's raw session lifecycle (for example running or exited). Both fields are projectable, including --fields nodes.id,nodes.state,nodes.sessionStatus. Terminals keep lifecycle in state, tasks keep task status, and other nodes use null. The live agent.list operation excludes exited sessions; use agent get for a known exited node's snapshot. Context reports unknown when that run is absent from list.

node list preserves status (session lifecycle) and adds sessionStatus as its explicit alias on agents and terminals. Both node list and context add agentState: {state, quality, turnId} for agent nodes and observed agents inside terminal nodes. agentState.state: working means the agent is working; sessionStatus: running only means the session is alive. Missing or displaced observations yield unknown/degraded for agent nodes; plain terminals have no agentState. Context retains its existing state field semantics above.

agent get, agent list, and context agent neighbors include taskNodeId: the ID of the task whose linkedAgentNodeId points to the agent, or null for no unique link. The task pointer is authoritative; stale agent data.taskId never creates a link. Compact task summaries include data.linkedAgentNodeId, avoiding task detail queries. Joins cover the target project, including tasks outside the agent's space.

Agent orchestration and bundled skill

opencove skill prints the version-matched SKILL.md bundled in the CLI, without a Worker connection or source checkout. -o json returns {version, content}. The core guide covers identity, authority, sharing results, coordination and exit codes. Load details on demand with opencove skill canvas|coordinate|wait|read|access (choose one topic). The core index lists all topics; an unknown topic exits 2 and lists valid names. Topic JSON adds topic to the same {version, content} shape; --fields supports all three fields. Start with the core when coordinating agents. Resident canvas guidance can introduce supported agents at SessionStart; configure Suggest or Off in Settings → Agent → Tell agents about OpenCove. See eligibility and limitations.

opencove agent list --space @self -o table
opencove agent get --node "Reviewer" --pretty
opencove agent read --node "Reviewer" --screen
opencove agent read --node "Reviewer" --node "Lead" --fields node,ok,message,error
opencove whoami --tree
opencove context --fields self.lineageQuota
opencove agent prompt --node "Reviewer" --wait --read --timeout 2m --text-file ./assignment.txt
# To keep working meanwhile, split the same steps:
opencove agent prompt --node "Reviewer" --text-file ./assignment.txt
opencove agent delivery delivery-123 --wait --timeout 2m
opencove agent wait --node node-123 --turn turn-123 --timeout 2m
opencove agent read --node node-123 --turn turn-123 -o json

Repeated --node on agent read accepts up to 10 selectors and always returns a JSON array in input order, including duplicates. Each entry contains the input selector as node, ok, and the single-read fields, or ok: false with error. Selector/read failures never hide other targets. Exit 0 means all succeeded; otherwise use the first failing target's exit code (there is no separate partial-failure code). --turn requires a single target (exit 2 for batches); --expect-turn is unsupported by agent read for any target count (exit 2). Screen options and --last apply to all. whoami exposes lineageQuota; context exposes self.lineageQuota, both projectable as {depth, maxDepth, liveInTree, maxLiveInTree} from the admission census. Roots have depth 1; occupancy counts live/starting agent-created runtimes, excluding the user root. Older Workers or unavailable accounting omit quota. Refusal details.nodes list up to six nodeId/title/kind/depth/state occupants with kind-aware recovery hints (agent stop, or terminal session lookup then session kill). Stopping frees width on runtime exit, never the caller's depth.

Start delegation with whoami --tree for the whole quota tree, remaining slots, work states and stop commands. Missing observations remain unknown; idle agents still occupy slots. Old Workers without census rows exit 5 and preserve known counts in error.details.identity. Outside a canvas session grant, tree mode keeps ordinary identity output. See tree and recovery. For several assignments use node create agent --prompts-file ./assignments.json --wait --read. The file accepts 1–10 prompt/title objects; results and failures remain in input order. See batch launch and exact-turn recovery. 中文:委派前先用 whoami --tree 检查名额与占用者;批量创建接受 JSON 文件,逐项创建、并发等待, 完整保留结果和错误,中断不停止已创建的智能体。

Give a window a stable name with node create agent --title "Reviewer" (also supported for terminals). Rename it with node update agent --node "Reviewer" --title "Lead"; use terminal for terminal windows. Names are trimmed, saved and displayed literally, including any provider prefix you include. Auto titles and older UI-decorated titles keep their existing presentation. Automatic titles remain enabled when creation has no nonblank title. Pinned names also take precedence over pending renderer auto-titles during publication and guarded rebasing. Title and pin/literal flags are reconciled as one naming intent; competing explicit renames retain the existing three-way conflict rules. Agent/terminal updates accept a nonblank title and/or a frame and reject all data fields. A frame-only update preserves the existing title and pin.

opencove agent stop --node "Lead" stops the bound session and keeps the canvas node. It supports agent windows and terminals with a live observed agent; for terminals it stops the entire session, including the shell. An exited terminal agent is an idempotent no-op: its surviving shell and unrelated foreground work are kept running. The Worker rechecks agent eligibility immediately before stopping. Remote agent-stop targets are refused before dispatch until the executing Worker can perform a conditional stop. No unconditional remote session kill is sent. Plain terminals are refused with a session kill --session <id> hint. The result is {nodeId, sessionId, stopped: true} when stopping is requested; process exit is asynchronous. An already-exited bound session returns {nodeId, sessionId, stopped: false, reason: "not_running"} with exit 0. A changed binding fails with exit 2; inspect the node again before deciding what to stop. A node with no session binding fails with exit 1.

For simple hand-offs, agent prompt --wait --read confirms delivery, waits for its exact turn and returns one JSON result with outcome, endedAt and the structured reply. A missing reply returns reply: null and replyUnavailableReason without failing an ended turn. --read requires --wait; --fields outcome,reply.message projects declared result fields. With --wait, --timeout covers confirmation and turn waiting (default 20s, 250ms minimum); sending has a separate 15s budget plus a five-second HTTP response margin. Without --wait, --timeout remains the delivery budget (default 15s, maximum 60s). Optional reading uses the ordinary request timeout. Exit 10/11/124 errors retain deliveryId and turnId; Ctrl-C exits 130 and prints known IDs on stderr. Resume the same turn without resending.

简单交接默认使用 agent prompt --wait --read:确认投递后等待同一轮结束,再返回回复。 outcome 表示该轮结果;没有可读回复时返回 reply: null 及原因,仍算等待成功。 --wait 的超时预算覆盖确认和等待,发送另有 15 秒预算。超时或中断后保留已有 ID, 继续等待或读取原来的轮次,不要重发。

To do other work meanwhile, keep the four-step loop and save deliveryId and turnId; use the same node selector throughout. Prompt → confirm delivery → wait --turn <turnId> → read the same turn. Check outcome and the reply. Claude and Codex lifecycle replies are correlated; turn end alone does not prove a steer was consumed. Use --until idle only for node-level readiness. Host waiting strategies are in opencove skill coordinate.

All commands have offline --help, examples and declared projectable fields. Node/Space selectors reuse exact IDs, exact names, unique prefixes and @self. Inside OpenCove, agent list defaults to the caller's Space; explicit --project selects project scope. --state working|waiting|idle|exited|unknown filters the Worker's agent.list. That operation lists live sessions only, excluding exited sessions; get/wait can address a known exited node. An unbound/deleted node's title is null. Final-message reads use the Worker's agent.finalMessage query.

Command Output contract Projection / table
agent list {epoch, seq, agents: [snapshot + title]} Snapshot fields + title; table columns: nodeId, title, provider, state, blockedReason, turn.startedAt, quality
agent get --node <selector> Snapshot + title; supports agent windows and terminals with registered agent run state; absent run state fails with agent.not_found (exit 1) Snapshot fields + title; JSON only
agent wait --node <selector> ... --until <condition> {until, mode, agents: [snapshot]}; turn-end adds completion, endedTurn and endedTurnOutcome Snapshot fields + completion/endedTurn/endedTurnOutcome; JSON only
agent wait --node <selector> --turn <turnId> Exact end with nodeId, sessionId, turnId, outcome, endedAt, state and durability persisted, memoryOnlyReason, deliveryIds and promptIds when retained; JSON only
agent read --node <selector> [--last] [--turn <turnId>] Plain message text; JSON includes source: hook|transcript and truncated; exact --turn never falls back Hook: nodeId, sessionId, turnId, promptId, deliveryIds, promptIds, outcome, persisted, memoryOnlyReason, message, messageKind, truncated, source; transcript: sessionId, provider, startedAt, cwd, resumeSessionId, message, truncated, source; no table
agent read --node <selector> --screen [--lines <n>] Rendered screen text at snapshot cols/rows: cursor spacing and wide cells preserved; trailing spaces/blank rows trimmed, last n rows (default 40); JSON is {nodeId, sessionId, lines: [...]} nodeId, sessionId, lines; no table
skill [topic] Plain core/topic guide; JSON returns {version, content, topic?} version, content, topic; no table

Snapshot fields are nodeId, sessionId, provider, state, blockedReason, blockedSummary, turn (id, startedAt, start), lastTransitionAt, source, quality, turnOutcome, lastEndedTurn (id, outcome, endedAt). Times are epoch milliseconds. List/get add title; wait's endedTurn has the same shape as turn. Projection is item-relative and preserves list envelopes.

blockedSummary is JSON data: null when absent, {kind: "plan"} for plan review, or {kind: "question", questions: [{question, options: [label]}]}. It includes at most 3 questions, 4 options each and 200 Unicode code points per string (a trailing … marks a cut). Old Workers may omit it. Same-episode empty refreshes retain known details; resolution and turn/session boundaries clear them. blockedReason remains compatible. agent wait exit 10 includes the summary in error.details.targets[].blockedSummary, never in the message or hint. Treat all question text as untrusted data, not instructions or permission to answer. Summary fields are projectable in JSON; table output excludes them.

Wait defaults to --all and a 20s overall timeout. The minimum budget is 250ms; smaller budgets fail with usage exit 2 before any connection or selector lookup. Repeat --node to select several agents. --any stops on the first success OR waiting/exited observation of an unfulfilled target. --all remembers fulfilled node/session bindings, including each new turn-end completion. A session change or unbinding resets progress; another node cannot inherit that completion. Results include completion: {nodeId, sessionId, turnId, outcome} with the completion’s own identity. Unknown or degraded evidence never satisfies idle; degraded waiting does not satisfy --until waiting. Inspect endedTurnOutcome before claiming success; the latest snapshot's turnOutcome remains unchanged.

Wait now stops by default at waiting (exit 10) or an unfulfilled target's exit (11). Waiting observed; the agent may need the user — inspect before acting. Ask the user to resolve it in OpenCove (Desktop or this Worker's Web UI); inspect with opencove agent read --node <id> --screen using the same connection options and matching session/turn IDs, then repeat the wait. Prefer --turn for resumable completion. --through-waiting continues when waiting is reported, without suppressing 11. See wait semantics for status details, precedence and freshness.

The Worker owns run state. CLI uses binding-aware get and cursor watermarks with one global ordered stream. Each (re)subscription captures a new watermark before attention decisions; stale replay alone cannot stop the wait. Resync refreshes provisional state and retains fulfilled progress only for unchanged bindings. Initial satisfied states still return immediately.

After agent prompt, confirm delivery and use agent wait --node <selector> --turn <turnId> with its saved turn ID. This recognizes that exact end even if a newer turn has started. A node-level idle wait accepts a state that already holds, but cannot identify the submitted turn. turn-end remains available for observing a future turn boundary after the baseline; historical outcomes never satisfy it. Use it only when observation starts during a running turn, rather than as the normal post-prompt wait. Timeout exits 124, leaves stdout empty and includes all last known snapshots in stderr's error.details.lastKnown (TTY also prints lastKnown). Ctrl-C exits 130 and closes streams; neither condition stops the agent. Missing run state is a clear error with a start/resume hint.

Final-message read tries agent.finalMessage {nodeId} first: newest observed ended turn, including empty/whitespace-only content. --turn <turnId> selects the exact OpenCove ID returned by prompt, never a prefix, another turn or a transcript. Only a read without --turn may fall back to session.finalMessage {nodeId}, and only for agent.final_message_unavailable with reason no_ended_turn or provider_sent_no_message. All other errors remain errors, including unsupported operations on an older Worker. Restart/restored conversations can use that unqualified transcript fallback; exact local --turn reads use the independent Worker archive across restarts.

Hook JSON contains {nodeId, sessionId, turnId, promptId?, outcome, message, truncated, source: 'hook'}. Transcript JSON preserves the session fields and adds source: 'transcript', truncated: false. Neither reading nor content proves a successful outcome. Exact local turns are retained in the private Worker archive across restarts; unqualified reads remain scoped to the current incarnation. Correlated local Claude and Codex lifecycle hooks supply it. Unavailable details.reason values are no_ended_turn, provider_sent_no_message, turn_not_ended (active) and turn_not_found (unknown/evicted). Exact reads preserve these reasons with exit 1; they never silently return an older message.

Plain text remains the default even when piped. A cut hook prefix stays the result and prints exactly one stderr notice with commands to look for the rest via session final --session <sessionId> (provider transcript) or agent read --screen. Those inspection paths may be incomplete and are not exact-turn substitutes.

Screen mode uses existing session.get {nodeId} then session.presentationSnapshot {sessionId}, never terminal input. A small virtual screen replays cursor movement, CR/LF/BS/TAB and line/display erase at the snapshot geometry, with two cells for wide CJK/emoji. It selects the declared normal or alternate buffer; SGR, OSC/hyperlinks and unrelated modes are ignored. Output contains only the rendered viewport rows, with trailing spaces and blank rows removed, then the requested last n rows. --lines requires --screen and a positive whole number; --screen conflicts with --last and --turn. --last can accompany --turn and does not loosen exact selection. --fields selects structured JSON, as does -o json. session.transcript_not_ready queries agent.get: only working agents are advised to wait for idle. An idle agent with a completed turn is told that its provider has not written a readable transcript (for example transcript saving disabled), with agent read --screen as the inspection path and no wait recommendation. Other states get screen/provider-setting guidance. Not-found asks you to check the node and start/resume its session. Transcript fallback and session final --session <id> reject null, empty or whitespace-only final messages with session.transcript_not_ready, exit 1 and the same state-aware recovery. The server normalizes blank replies to null and supplies no separate empty-reply marker, so a genuine empty reply cannot be distinguished. Nonblank replies keep the existing text/JSON output forms. Reading can cache a discovered transcript identity under the existing server contract. Prompt admission and uncertainty rules are unchanged: never resend after stalled/interrupted or transport-unknown delivery. See Prompt delivery.

Wait uses the condition-wait pattern documented by Kubernetes and UTF-8, multiline-data, comment and newline framing from the HTML SSE standard, adapted to OpenCove's explicit epoch/seq query cursors and bearer authentication. Fake-stream unit tests exercise these invariants without opening local listeners.

安装与运行

Desktop、standalone 与 server 安装方式见 CLI 安装指南。

Canvas 终端身份

Hosting Worker 在 canvas PTY spawn 时注入 OPENCOVE_ENV=1、OPENCOVE_NODE_ID、 OPENCOVE_SPACE_ID、OPENCOVE_PROJECT_ID、OPENCOVE_CONTROL_URL、session-scoped OPENCOVE_CONTROL_TOKEN 和 OPENCOVE_CLI;PTY host 分配实际 session ID 后注入 OPENCOVE_SESSION_ID。不属于 Space 的节点使用空 OPENCOVE_SPACE_ID。Worker 全权限 bearer 不进入该环境,调用者提供的身份/控制环境变量会被覆盖。

现有 shim directory 提供 opencove(POSIX sh)和 opencove.cmd,并被放在 PATH 首部。 Launcher 使用本 Worker 的 runtime executable;CLI 从环境读取 endpoint/token,显式 CLI 指定 --endpoint 时必须配 --token。OPENCOVE_CLI 指向构建产物 out/cli/opencove.mjs。

node.create 和 UI 创建流程在 spawn 前预留 node ID;Worker 校验已有节点的所属记录, 恢复使用 Worker 保存的身份。远端由实际 hosting Worker 签发 grant。凭证在 spawn 注册完成后 激活,失败、退出、kill、hosting Worker shutdown 时失效。system.whoami 返回 caller identity、 scopeTier、instanceId 和 appVersion,不返回 token/hash。

Windows 直接以 wsl.exe 启动 canvas PTY 暂时明确拒绝 scoped identity:Windows shim 路径与 loopback URL 不能保证在 WSL 中可用。应在 WSL 内运行 hosting Worker,并通过 mount 使用它。

Selector diagnostics and bounded output

Use --space <selector> with any --node selector to resolve a node name or unique ID prefix within that space. Explicit --space also validates full IDs and @self; a node outside that space fails with node.not_found, naming the actual and selected spaces. Drop --space to address full IDs across spaces. An explicitly selected project continues to constrain IDs. Names remain case-sensitive, and ambiguity always fails without choosing a target. For example:

opencove node get --node "Progress" --space "Main" --fields id,data.text
opencove node update note --node "Progress" --space "Main" --text "Ready for review"
opencove node delete --node "Progress" --space "Main"

Ambiguous node candidates include spaceId and spaceName. Note candidates also include a single-line preview, limited to 60 characters including an ellipsis when cut. Full note content is read only for the displayed ambiguity candidates. Missing selectors report the project and optional space searched, suggest up to three names within case-insensitive edit distance 2, and identify known IDs of a different kind. Suggestions never resolve selectors automatically.

--limit <n> accepts a non-negative safe integer and caps each top-level output list after filtering and field projection. It does not limit selector lookup or change the operation sent to the Worker. Omit it or use --limit 0 for complete output. A cut object-shaped list preserves its envelope and adds totals, for example:

{ "activeProjectId": "p", "projects": [{ "id": "p" }], "truncated": { "projects": 4 } }

Bare-array outputs such as api ops always remain arrays, including when cut. A cut array writes one stderr notice, for example Showing 20 of 145 operations; use --limit 0 for all. Object-shaped lists keep top-level truncated totals. Tables cap rows, use uppercase headers, and report truncation with one stderr notice, for example Showing 1 of 5 nodes; use --limit 0 for all. JSON object lists keep their top-level totals. Nested node data (for example tags) is not truncated. Server-side filesystem read bounds remain separate and do not provide a total beyond the entries returned by the Worker.

space list and space get use the same space-row fields: id, name, directoryPath, targetMountId, parentSpaceId, boundary, rect, sortOrder, nodeIds, projectId and nodeCount. rect is {x,y,width,height} in canvas coordinates, or null without saved geometry; space create uses the same field. boundary describes access scope. The legacy projectId/activeSpaceId envelopes remain. space get retains nodes; space list keeps IDs, directoryPath, nodeIds and nodeCount but omits full node objects by default. Request them explicitly with --fields nodes, or select nested fields with --fields id,name,nodes.id. These compact queries remain useful for finding a space and checking its membership:

opencove space list --project "@self" --limit 10 --fields id,name,directoryPath,nodeCount
opencove node list --space "Main" --limit 10 --fields id,kind,title

context.space.directoryPath uses the same spelling as space get and space list. Node content paths are data.text for notes; data.requirement, data.status, data.priority, data.tags for tasks; data.url for websites; and top-level status / sessionId for agents and terminals. node list returns summaries; read full note text with node get. If a declared projectable field is absent on a returned node kind, the CLI writes one notice to stderr and leaves stdout as projected JSON. Empty note text is a present value and does not trigger a notice.

File URI inputs require an absolute file:// URI, including with --mount. Errors give an example built from the input when possible; relative examples use /path/to/project as a placeholder, never the CLI cwd. Find the target's real root:

opencove mount list --project "@self" --fields mountId,rootUri
opencove fs read --uri file:///workspace/README.md

Unknown api schema / api call IDs suggest nearby IDs and a domain catalog query. Catalog rows expose cliCommand (when a dedicated command exists) and scope (read, interact, admin). Inside OpenCove, access comes from the Worker policy: allowed, denied (with a reason), or constrained, plus policyVersion. allowed is a compatibility boolean only for allowed/denied rows; constrained or unknown access omits it. Offline or with an older Worker, access is unknown. api schema keeps the input JSON Schema and adds the same Worker access information inside OpenCove, including rejectedFields and their reasons for constrained launches. A schema field does not grant permission to use it. Operation preconditions and resource permissions still apply. Domain summaries use commandOperations for the number of command-kind operations.

opencove api ops --domains --fields domain,operations,commandOperations
opencove api ops --prefix node --fields id,cliCommand,scope,access --limit 10

创建并等待首条回复:见 Create an agent and wait。

Archived exact turns

Exact local agent read --turn and agent wait --turn survive Worker/app restarts, without relaunching the agent, and return the original node/session IDs. JSON includes persisted; false includes memoryOnlyReason (unbound, remote, unavailable, write_failed, deleted, or retention_backlog). Older Workers cannot certify it. archive_unavailable is distinct from missing/expired history; never resend to recover it.

The executing Worker stores final reply text (≤64 KiB UTF-8), outcome, IDs, timestamps and truncation/intermediate metadata in a separate archive file. It stores no prompt text, hook evidence or S2 delivery records. S1 provider continuations archive once at the final OpenCove end; uncertainty stays unknown/messageKind: intermediate and never grants readiness or proves steering consumption. Retention upper bounds are 60 turns/node, 30 days, 20,000 global records and 128 MiB of message text; metadata-only ends count. Smaller memory caches may evict earlier. Oversized purges leave new turns memory-only (retention_backlog) while bounded cleanup makes room for future records.

Deleting the node removes queryable OpenCove history, including caches; it does not erase provider transcripts, existing backups or forensic remnants. opencove agent history clear --node <selector> (agent.history.clear, interact scope) deletes the node’s archived and in-memory replies across retained incarnations, leaving the node, provider transcripts, backups, run state, active turns and delivery records unchanged; later ends store normally, and archive unavailability clears memory but exits 1. Unqualified reads, prompt-ID selectors and labelled transcript fallback retain current-incarnation semantics. Remote history is not routed across Workers.

Help goldens are generated by Vitest: pnpm exec vitest run tests/unit/app/cliCore.spec.ts tests/unit/app/cliInputOutput.spec.ts tests/unit/app/cliAgentQueries.spec.ts tests/unit/app/cliSchemaValidation.spec.ts tests/unit/app/cliSkill.spec.ts tests/unit/app/cliEvents.spec.ts tests/unit/app/cliOutputBehavior.spec.ts tests/unit/app/cliHelpErrors.spec.ts tests/unit/app/cliCommandMapping.spec.ts tests/unit/app/cliOutputContracts.spec.ts tests/unit/app/cliNodeHelp.spec.ts --update. Never edit generated snapshots by hand.

An unfinished agent read --turn retains agent.final_message_unavailable and details.reason: turn_not_ended, and adds state and blockedReason. Waiting asks the user to resolve the permission, question or plan in OpenCove; working retains the exact-turn wait command. Unavailable or replaced observations report unknown; they never replace the original read error or trigger another prompt.

Question summaries and their compatibility rules: Agent dialog summaries.

Creation lineage and parent selectors

@parent selects the node that created yours; node and agent lists can filter with --spawned-by, and results carry spawnedBy, lineageDepth and lineageStatus. See Lineage. 中文:@parent、--spawned-by 与血缘字段的完整说明见 Lineage。

Agent event observation

Use opencove events for resumable, read-only NDJSON observations. Consume stream.ready before starting work; save each complete record's cursor and resume with --cursor-file <path> or manually with --after. Use --until-each-turn with repeated --node to observe one completion per node. stream.gap is terminal. See Events and the versioned transport contract for filtering, attribution, bounded output, grant revocation and exit codes.