DreamLake

RFC 0011 — Built-in Agent Harness 与 Session 控制面

状态:后端、前端和 CLI 0.89.0 已发布到生产(2026-10-28);真实 API、模型工具、Codex/Claude 会话和浏览器 ACK 已验收。生产验收发现的选区焦点竞争已由 PR #1527 修复,并在实际浏览器中复验选中文字与位置。证据与已知限制见第 13 节。对应设计:Memo 6adec6fea203b8fb5430db2f(Built-in Agent, CLI and TypeScript API)与 6adeedd9650dabffcceab1ce(Agent Harness 架构)。本文既是架构 RFC,也是这次实现的说明:讲清楚 harness 的原理和框架、TypeScript API 是怎么做的、以及具体改了什么。

1. 一句话

Built-in agent 没有 shell。模型发出的每一个 tool call 都被 harness 路由到服务端的一个 TypeScript plugin;plugin 以登录用户的身份、在本轮被授予的 scope 内,调用和 CLI / TypeScript API 完全相同的 HTTP 路由,并在执行前后写下一条持久化回执(AgentToolCall)。Agent 对其他 Codex / Claude session 的控制(start / resume / stop / send / broadcast / archive / rename / subagents)不是直接 SSH 或起容器,而是向一个持久化命令队列(SessionCommand)写入意图,由用户自己机器上的 runner(dl sessions serve)认领、用 Codex / Claude 自己的 CLI 执行、回传一条带租约围栏的回执。这是 Ge 要求的 light integration:对 Codex / Claude 零改造,glue 使用 tmux、原生 CLI 和可选的本地 Docker 执行适配器。

2. 组件与职责边界(RFC 第 1 项)

浏览器(dreamlake-ai)                     dreamlake-server                                  用户机器
┌──────────────────────┐   POST /agent/chat   ┌───────────────────────────────────────┐     ┌──────────────────────────┐
│ AgentComposer         │ ───────────────────▶ │ builtin-agent/routes.ts  (turn 入口)   │     │ dl sessions serve  │
│  · page context       │   SSE: context/delta │   scopesFor(capabilities)              │     │  (runner, 用户 token)     │
│  · capabilities       │        /tool/done    │   ToolRegistry ──▶ ToolPlugin.execute  │     │  claim ──▶ 执行 ──▶ 回执  │
│  · session-control 开关│ ◀─────────────────── │        │  receipts (AgentToolCall)     │     │   tmux / claude -p /      │
│  · tool 回执列表       │                      │        ▼                               │     │   codex exec / git worktree│
└──────────────────────┘                      │   harness/api.ts  (in-process HTTP)    │     └──────────┬───────────────┘
                                              │        │                               │                │ long-poll claim
CLI / TS API                                  │        ▼                               │                │ renew / result
┌──────────────────────┐   同一组 HTTP 路由    │   terminal-sessions / notes / …routes  │ ◀──────────────┘
│ @dreamlake/dreamlake- │ ───────────────────▶ │   session-control/routes.ts            │
│ cli/api · sessions ctl│                      │     store.ts: SessionCommand/Runner    │
└──────────────────────┘                      └───────────────────────────────────────┘
组件负责不负责
浏览器采集有界可见正文、选区、结构与布局快照;声明本轮 capabilities;执行 layout_action;展示 tool 回执任何授权;任何工具结果正文
builtin-agent/routes.ts鉴权、团队准入、身份(SA + context project)、turn 租约、把 capabilities 变成 scopes、驱动模型循环、结算回执执行工具逻辑
harness/registry.ts工具目录、按 scope 过滤、Ajv 参数校验、每轮次数上限、超时、回执写入/结算、结果截断业务逻辑
harness/api.ts以调用者 bearer 在进程内 inject 同一 Fastify 路由;附加 agent 归因头绕过任何路由的鉴权
plugins/*把 HTTP 结果压缩成模型可读的小对象 + 资源引用 + summary持有凭据、选择身份
session-control/命令/runner 的持久化与状态机、路由到 runner、租约与围栏、owner-only 控制执行进程
runner(CLI)在用户机器上执行命令:tmux / headless、git worktree、读本地 transcript 做 status/subagents/sync任何服务端权限;不接收入站连接

Background turns (pending release)

Clients negotiate backgroundExecution: 1 and admission: 1 from GET /agent/capabilities and opt into POST /agent/chat with execution: "background". A background turn continues when its response socket closes, while the owning server process lives. Existing clients keep the original disconnect-to-cancel behavior. This is not a durable job queue: process failure interrupts the turn, and no automatic restart or replay of tool calls occurs. The turn has a ten-minute wall-clock deadline in addition to the existing provider idle timeout and tool limits.

Background requests refuse browserExecution: 1 and delegated browser requests (400 agent_background_backend_only). Only tools declaring backend execution are offered and allowed. The web composer shows this as a visible mode: Keep running (background, server tools only, the default when negotiated) or This tab (foreground with page tools; closing the tab stops it). Existing turn capabilities, namespace authority, resource ACLs and exact project grants still apply. The browser bearer is used only by the live process; it is not persisted as worker credentials.

Durable admission

Send admissionId (^[A-Za-z0-9_-]{16,64}$, one per intended turn) with the chat request and reuse it, with the identical body, for every retry. The server records it in the same transaction that claims the session lease; its key is derived from the user and the ID, so no extra index is required.

  • An admitted turn first emits {type: "admission", replayed: false, admissionId, sessionId, turnId, execution, state, deadlineAt}, before skills, memory or the model load.
  • A retry with the same ID and canonical payload answers one admission event with replayed: true and starts nothing. A different payload returns 409 agent_admission_conflict. Reuse re-checks team membership, conversation ownership and the acting namespace.
  • GET /agent/admissions/:admissionId (owner only) reconciles a request whose response was lost, including before any session ID arrived. It applies the same checks as a replay: conversation ownership and the acting namespace. A refusal (403, or 410 agent_admission_session_gone) carries no session, turn or namespace. 404 agent_admission_unknown means not admitted (yet); resending the identical request with the same ID is then safe.
  • Uncertain outcomes are no response, 408, and every 5xx except the refusals the route can only return before admission (agent_model_not_configured, agent_shutting_down, agent_team_not_configured, agent_search_not_configured, system_agent_project_not_configured, system_agent_prompt_empty). Other 4xx are definite. The web client keeps one local entry per unconfirmed admission (identifiers only), never declares an unconfirmed send failed, and after 15 minutes reports it as unconfirmed rather than suggesting a resend.
  • The web client offers background mode only when the server advertises both backgroundExecution: 1 and admission: 1; otherwise turns stay foreground.

State, Stop and reconnect

GET /agent/sessions/:id returns activeTurnId and a nullable background object with turnId, text, cancelRequested, deadlineAt, checkpointedAt and status, and sends an ETag (observers may poll with If-None-Match). Statuses:

statusmeaning
runningthe owning process holds a live lease
completedfinished; the answer is in messages
cancelledan explicit Stop took effect; committed tool effects remain
timed_outthe background deadline ended it
authority_expiredthe caller's authority ended mid-turn (a 401 from an in-process call or a failed active-actor fence); a tool's own 403 is an ordinary tool error
errorany other failure
loststored as running but its lease expired: the process stopped renewing. It is never resumed

While running, text is a redacted, bounded replacement snapshot (at most 65,536 UTF-16 code units), normally updated every two seconds. It is not a lossless replay: reconnect by reading state and receipts, never by resending the prompt. Image bytes and unsaved Memo previews are not persisted. Thinking-details persistence adds a separate bounded reasoning sidecar to these checkpoints; it is not part of the ordered output-event log.

POST /agent/sessions/:id/stop takes {turnId} and requires the authenticated owner and team admission. It records cancellation under the current lease before signalling a local worker; other replicas observe it on the two-second checkpoint. It answers {accepted, turnId, state, status}: state: "requested" (also for a repeat after a lost response) or "already_terminal" when that exact turn already ended. A Stop for a turn that has been replaced returns 409 agent_session_turn_lost and cannot affect the replacement. Stop is cooperative and cannot undo committed writes; inspect receipts for uncertain effects.

The existing /agent/sessions/:id/steer endpoint admits events to a running turn at model boundaries. It does not wake idle sessions.

Limits and rollback

No restart recovery, idle wake-up, ordered output replay or cross-replica quota is provided; lost is the honest outcome of process loss. Admission rows have no expiry yet. To roll back, clients stop sending execution and admissionId; the server keeps serving foreground turns unchanged, and the extra fields are additive. BUILTIN_AGENT_TEST_MODEL_URL is a test-only, loopback-only model stub hook.

Durable jobs (pending release, AGENT_DURABLE_JOBS_ENABLED)

Capabilities add durableExecution: 1, durableTools and durableExcluded. execution: "durable" (requires admissionId) writes the job, its work credential, the session claim and the admission in one transaction and returns after the admission event; nothing runs in the request.

  • Ownership and fencing. Every replica's worker claims queued or lease-expired jobs by compare-and-set on (id, generation). A claim advances the credential generation in the same commit. Transcript, receipt, output and terminal writes, and the destination writes of durable tools, are fenced on the generation inside their own transaction: a paused worker that resumes after a reclaim cannot commit. Lease expiry only makes a job reclaimable.
  • Replay rule. A reclaim re-runs the model, which mints new tool-call ids. A turn is re-run only if no side-effecting call was started by an earlier generation; otherwise it ends interrupted. At most 2 reclaims (failed).
  • Limits. One running job per user across replicas. Cumulative budgets (40 rounds, 80 tool calls, 400,000 tokens, with 24,576 tokens reserved before each round so a crash never under-counts; lower for waits) and the absolute 10-minute deadline survive reclaims. Exhaustion ends budget_exhausted.
  • Worker authority. A non-secret credential row per job; 60-second tokens bound to (credential, generation, jti), under a key distinct from user tokens, accepted only by authenticateJWT after rechecking the row, the job (running, same generation, not stopped, before the deadline) and the human. Requests run as that human and are limited, fail-closed, to the route patterns of the durable toolset inside the admitted namespace (workPolicy.ts); Projects must be in both the grant set fixed at admission and the current grants. Mutating routes also require the write scope the admitted turn was granted (memory:update: memoryWrite plus an explicit memory request in that message; sessions:control: sessionControl). A resume must carry the exact admitted request. No browser bearer is stored.
  • Toolset. Project and Memo reads, memory search and update (version-guarded, fenced in the same transaction), session rename/archive (fencedMutation). Memo body writes are excluded: they commit to the RTC server, outside any transaction this server can fence.

Ordered output

GET /agent/sessions/:id/turns/:turnId/events?after=&limit= (owner only) returns {events: [{seq, generation, type, data}], nextAfter, latestSeq, truncated, finalized, complete}; complete only when the job is terminal, its last batch was written (finalized) and every event was returned. Types: generation (a reclaim superseded earlier partial output), model, delta (coalesced), tool (display-safe receipt fields), steering, truncated. At most 2,000 events / 256 KiB of delta text per job, across every generation; an oversized piece is cut and exactly one truncated marker ends the record. The writer's queue is bounded (500 events / 64 KiB, one flush in flight); overflow is recorded as truncation. Tool events keep only a code-shaped error. Kept 7 days after the job ends; purged jobs are marked. A cursor ahead of latestSeq is 409; output no longer retained answers {reset: true, reason: "not_retained", snapshot}.

Waits and addressed events

  • POST /agent/sessions/:id/waits {kind: "memo_committed", noteId, message, expiresInMinutes?, budget?, capabilities?} or {kind: "owner_event", ...}: owner opt-in; scope, budget (default 10 rounds / 20 calls / 100,000 tokens) and expiry (default 60, at most 1,440 minutes) are fixed and returned. One active wait per conversation and at most 10 per user (409 agent_wait_limit_conversation / _user). GET lists, DELETE .../waits/:waitId revokes (after it fired: alreadyFired with that exact turn, which only a Stop of that turn stops). Stop never revokes waits and a stale Stop never reaches a newer turn or wake. Expiry ends the wait's authority: a wake's deadline is min(now + 10 min, expiresAt) and none starts with under 60 s left. Wake write scopes come from the wait's capabilities and message only.
  • memo_committed waits store the Memo's committed checksum read before the wait is persisted; every worker reconciles active Memo waits against the current committed checksum (paged, fair), so a crashed or missed commit notification cannot lose a change. The canonical Memo read decision is applied at creation and before each system event is consumed; an unreadable target cancels the wait. POST .../waits/:waitId/events {eventId, payload} is the owner addressing that exact wait. Work tokens can do neither.
  • An admitted event fires one durable turn through an outbox (event, one-shot wait transition, session claim, job, credential in one transaction). The same eventId and payload return the same receipt; a changed payload is 409 agent_event_id_conflict; later events are coalesced (no model); an event for a busy conversation or a transient failure is pending (held atomically with the wait) and retried; only lost authority cancels a wait; at most 64 per wait. Memo revisions are not ordered, so no source cursor is kept. Owner events cannot satisfy Memo waits; a system event must name the current committed checksum.

Retention

Output: 7 days after the job ends (then reset). Content: 7 days after it ends, the job's admitted request, a finished wait's message and an event's payload are removed by the purge worker (marked, never revisited). Identity is kept: admissions stay as tombstones (ids, payload hash, outcome) so an old admissionId is replayed, never run again; event digests stay so a re-send is a duplicate or a conflict; tool receipts are never purged.

Replicas

AGENT_DURABLE_WORKER_CONCURRENCY (default 4, at most 16) bounds running jobs per process; 0 makes an API-only replica that admits but never claims.

Memo producer

Verified end to end against an isolated vuer-rtc server (vuer-rtc-workspace 2d4b87a7, its existing build): a body write commits through RTC, the server's projection sync records Memo.checksum, and reconciliation fires the wait. The sync loop runs only when RTC_API_URL is set.

Indexes

Four new indexes, all in the reviewed built-in agent scope (src/deployment/builtinAgentIndexes.ts):

CollectionNameKeyUnique
AgentJobAgentJob_state_leaseExpiresAt_idx{state: 1, leaseExpiresAt: 1}no
AgentTurnEventAgentTurnEvent_jobId_seq_key{jobId: 1, seq: 1}yes
AgentWaitAgentWait_targetKey_state_idx{targetKey: 1, state: 1}no
AgentWaitAgentWait_state_expiresAt_idx{state: 1, expiresAt: 1}no

Provision after merge and before deploying (deploy refuses index additions), with the existing EKS-aware workflow and its deploy role (the older per-scope builtin-agent-indexes.yml passes only ECS settings and cannot target the EKS production deployment):

sh
gh workflow run schema-indexes.yml --ref main -f environment=production -f scope=builtin-agent -f mode=plan
# review the printed plan: exactly these four additions, its planHash
gh workflow run schema-indexes.yml --ref main -f environment=production -f scope=builtin-agent -f mode=apply \
  -f plan_hash=<planHash> -f confirmation=CREATE_BUILTIN_AGENT_INDEXES_ON_PRODUCTION

Applied to production on 2026-11-15 (plan a301105a…, 4 created, 21 verified). Admissions, credentials, work slots and inbound events are keyed by _id.

The existing session-command queue is for user-machine runners and does not provide these guarantees to built-in model turns.

3. 工具定义与注册(RFC 第 2 项)

Memo streaming previews (pending release)

The built-in agent streams a bounded, explicitly unsaved source preview while it generates canonical Memo create, write, append, replace, insert, patch, and batched edit arguments. Batched previews contain replacement text or HTML, separated by blank lines; they are not a reconstruction of the whole document. Moves and deletions have no new source text to stream. The preview is shown in the agent and the matching open Memo without replacing the saved reader or writing into its collaborative editor. New Memo previews appear in the agent before a Memo ID exists. Preview text is inert, including incomplete HTML.

memo_preview SSE events carry turn/session identity, a round/index draft ID, monotonic sequence, operation, namespace, optional Memo ID and base revision, decoded text deltas, and lifecycle state. Existing-Memo previews require a revision observed in that turn; whole-body writes require complete read coverage. They do not authorize a write. Complete arguments still pass through the existing registry, schema and permission checks, turn fencing, revision-bound RTC command, idempotent command identity, and durable receipt/readback flow. No generated prefix is persisted. Exact mode refuses stale revisions; merge retains the existing identity-based concurrency semantics.

The UI distinguishes preview, saving, saved, unchanged, not_saved, discarded, and uncertain. Only an accepted revision receipt confirms a save. Steering or cancellation before dispatch discards the draft. Interruption after dispatch leaves the outcome unconfirmed: inspect the Memo and durable tool/command receipt before retrying. Neither reconnect nor a restored conversation replays a draft. Previews are memory-only, not chat transcript/history; resetting the conversation, signing out, or reloading clears them. The browser retains at most four previews of 64,000 UTF-16 code units each (create input is capped at 32,000), and rejects sequence gaps or changed target identities. Older clients ignore the additive event; older servers retain their existing write behavior.

Memo 与文件夹归档

归档与删除、标签分别管理。dreamlake_note_update 接受单独的 {noteId, namespace?, archived:true|false},不能同时提交 name、summary 或 visibility;需要 notes:write 和 Memo 自身的管理权限。 dreamlake_folder_archive 接受 {projectId, folderId, archived:true|false}, 需要本轮 projects:write scope、明确授予服务账号的 WRITE/ADMIN 项目权限, 并再次通过同一个 PATCH /nodes/:id 路由检查调用者权限。 toolsWrite:1 才授予新的项目写 scope;projects:read 本身不能归档。

dreamlake_notes_list、dreamlake_notes_search、dreamlake_notes_grep 与 dreamlake_search_project 接受 includeArchived。默认只发现活跃内容;显式 读取仍可访问有权限的归档对象。Memo 元数据包含 archivedAt。成功保存修改或 显式取消归档会恢复相应文件夹路径,不会恢复独立归档的兄弟项或已删除对象。 写入超时、未知结果或 5xx 仍记录为 uncertain;先核对状态,不要盲目重放。 这些是当前内置工具注册,不代表另外发布了一个 MCP server。 详见 归档 API 契约。

网页研究:搜索、读取与 Memo(本分支新增能力未发布)

第一阶段支持「搜索或给出 URL → 读取网页文本 → 带来源写入 Memo」。 写 Memo 仍需用户明确要求,并开启工具写入;现有权限、revision guard 和 写后验证继续生效。搜索摘要不能当作已读取的网页正文。

POST /agent/chat 可选 searchProvider:serpapi(默认)、brave、 tavily-basic、tavily-advanced。GUI 从经过团队准入检查的 GET /agent/search-providers 获取可用项;未配置项不可选择。 显式选择未配置的 provider 会拒绝请求,不会静默换一家。 服务端分别使用 SERPAPI_API_KEY、BRAVE_API_KEY、TAVILY_API_KEY; Vault 存储不等于环境注入,部署时仍需配置对应 secret。 一次 turn 固定一个 provider,模型不能通过工具参数更改它。

dreamlake_web_search 返回最多 10 个标题、URL 和摘要,以及 nextStart。 查询长度为 1–500 字符。每轮最多 12 次,单次 20 秒,不自动重试或 fallback。

Provider分页地区/语言返回内容
SerpApistart 是偏移量,0–100country / languageGoogle SERP 摘要
Bravestart 是页号,0–9country / language,供应商支持范围可能不同Brave 索引摘要
Tavily Basic / Advanced不支持,非零 start 拒绝当前 adapter 明确拒绝这些过滤参数研究检索摘录

始终原样使用返回的 nextStart;它为 null 时停止分页。 Tavily 固定用户所选 depth,关闭自动参数、答案生成及 raw content。 三者不是等价结果集;没有实测之前不声明质量或成本排名。

dreamlake_web_read 独立于搜索 provider,可读取用户直接给出的公开 HTTPS URL。 支持 HTML、纯文本和可提取文字的 PDF,提取标题、文本、来源 URL、读取时间与返回文本的 SHA-256。 HTML/text 响应上限 8 MiB,PDF 响应上限 16 MiB;下载大小超限返回 agent_web_read_too_large,不冒充网络不可用。返回文本上限 8,000 UTF-16 units,超限明确标记 truncated。 每轮最多 12 次,单次 20 秒。DNS 在实际连接时校验,拒绝内网地址、 带账号密码的 URL、非标准端口;不发送浏览器 cookies 或服务凭据。 不执行 JavaScript,不支持登录页或绕过反爬。允许最多三次公开 HTTPS 跳转;每次重新校验 URL 和实际连接的 DNS,拒绝内网、凭据 URL、降级 HTTP 和循环。 PDF 仅以字节传入独立 worker,不执行文档脚本或加载嵌入资源;解析上限 40 页、200,000 字符、8 秒和 128 MiB JS 堆。返回 format=pdf、pageCount、pagesRead;扫描件或加密文件可能不可读。可选 query 从已解析全文选择相关逐字片段,同时保留开头书目信息,PDF 还保留已解析文本末尾的一小段(可能包含早期参考文献);8,000 字符的返回仍是摘录,truncated=true 不代表全篇已呈现。读取失败必须报告,不能以搜索摘要冒充正文。正文是非可信资料,不是 agent 指令。

研究收集和 Memo 保存

dreamlake_research_collect 接收 1–3 个互不重复的查询,使用本轮选定的 provider 并行搜索;交错选取各查询结果、去重,优先论文页面和 PDF,而非作者资料镜像、社交或百科页面, 从最多六个候选页面中获取最多四个成功来源,读取并发为 2。默认目标三个成功来源, 每轮最多调用两次,单次总预算 90 秒。失败页面不能算成功来源。maxSources=0 仅返回候选检索结果,状态为 discovery_only,不读取页面或生成证据句柄。研究定义默认先用此模式比较候选的标题、作者与问题,再选择原文读取,避免仅因 PDF 容易读取就先采集无关论文。 子调用继续经过同一工具 registry,保留权限检查、调用次数和独立回执; 不自动重试同一页面或换 provider。返回候选来源、短摘录、evidenceRef 和明确失败, 不代表论文匹配已经核实,也不保证 PDF、重定向或动态页面可读。

dreamlake_research_save 每轮最多发起一次真正的创建,将结构化候选保存为真实的私有 Memo。 候选包含标题、可选作者与年份、主要发现、相关性、不确定项和原文引用。 省略可选 quote 时,服务端直接截取本轮来源正文前 300 个字符作为规范摘录, 避免模型重抄引文造成标点或空白差异。显式引用允许空白差异;PDF 来源还允许字母之间的断行连字符差异(例如 re- 换行 inforcement),普通词内连字符与其他标点仍必须匹配;保存的是来源中实际匹配的原始子串。引文必须出现在 本轮成功读取的来源正文中;不存在的 evidence handle 或 虚构引用在创建 Memo 前拒绝。标题、问题或分析字段为 placeholder、TODO、TBD 等 占位内容时也在写入前拒绝,允许在同一有限纠正预算内补全真实分析。作者、年份和分析仍由模型判断,缺失字段标记 Unknown。Memo 包含来源 URL、标题、读取时间、内容 hash 和截断标记。 保存复用 canonical Memo create、revision-guarded 写入和回读;失败返回已有 Memo 的恢复标识,不自动创建第二份。编辑已有 Memo 继续使用常规 Memo 工具。

选择已有 agent definition

在 built-in agent 输入 @agent,从当前执行 namespace 的既有 Runnable catalog 选择 definition、填写参数,再点击 Send。运行状态、工具回执和结果 保存在当前对话,恢复对话也会恢复所选 definition。切换 namespace 会清除选择。 搜索 provider 位于工具栏最右侧的 More → Search provider 二级菜单。

工具调用在每个用户回合中默认折叠为一行,显示调用数量与失败/不确定状态数量; 展开第一层后,每次调用仍是独立收起的一行,再展开第二层查看该工具的返回详情。 搜索详情在第二层内切换 Results / JSON,不与整轮调用列表共用展开状态。 其他工具展示已记录的返回摘要;没有保留的完整 response body 不会补造。 搜索详情按需读取 GET /agent/sessions/:id/searches?turnId=...,仅对话所有者可访问,并包含 research_collect 内的搜索子调用。展示实际查询、provider/engine、HTTP 状态、耗时、结果标题/链接/摘要、 查询改写或站点筛选警告,以及 request/response JSON。供应商结果快照来自分析前的公开结果字段投影, 与筛选后交给模型的结果分开;不返回凭据或供应商 transport envelope,也不将搜索摘要视为已核实正文。 每个快照仍受 64 KiB 上限约束,超限明确标记;旧调用没有保存的供应商快照不能补造。 展开、刷新详情和恢复对话不会重新执行搜索。前后端发布后新调用才能提供完整的新展示字段。

GET /agent/definitions?namespace=...&page=1 按每页 20 个列出调用者可访问的 kind=agent Runnable。只执行显式声明 metadata.agent.runtime="builtin-v1" 的配置;其他 runtime 显示不可用。支持 name、tools、arguments 和可选的 workflow, 不执行 Claude tool 名称、模型覆盖、permissions、RunConfig、queue 或 host 配置。 参数支持 string、number、integer、boolean、enum,最多 20 个;文本值最多 4,000 字符,prompt 最多 16,000 字符,替换后最多 24,000 字符。不支持凭据参数。

POST /agent/chat 的 agentDefinition 接收 {id, revision, arguments}; revision 是 catalog 返回的内容 hash,每轮重新读取 definition 和检查访问权限。 改动后的配置返回 agent_definition_changed,需重新选择;撤销权限后不能继续执行。 传 null 清除选择,省略则沿用已保存选择。工具白名单与当前用户权限、工具写入开关 取交集,也约束嵌套工具调用,definition 不能授予额外权限。

Research definition 示例 可通过现有 POST /namespaces/:slug/runnables 注册。它保存在同一个网站 catalog 中, 不是前端维护的第二份 agent 列表。question 是问题,回答默认跟随用户语言; Agent 列表按所选 namespace 查询,并应用当前用户的访问权限;切换个人或团队 namespace 会切换定义列表,不会移动或复制 agent。 save_note 通过开关决定是否请求保存;关闭工具写入时只能返回研究结果。

参数或引用校验失败且尚未发起 Memo 写入时,最多允许两次纠正:根据 schema 字段路径与限制修正参数,直接复制来源返回的 suggestedQuote。诊断不包含参数值或未知字段名。一旦发起创建,无论成功、失败或不确定,本轮都禁止再次创建。重定向来源的 requestedUrl 和搜索改写警告均通过完整工具输出契约校验。

Research 示例显式使用 metadata.agent.workflow="research-v1":强制一次收集, 最多追加四次定向搜索和六次直接读取;有来源且 save_note=true 时可选择沿搜索结果或网页返回的链接继续核实,也可直接 research_save。用尽定向搜索和追加读取后必须进入保存,再调用 Memo read,最后返回结果。普通 Memo 创建工具仅作为 research_save 的受权限约束子调用,模型不能直接绕过证据保存。开始写入后的失败不自动重试;仅允许上述写入前引用纠正。 写入权限未启用或没有读取成功的来源时,不会强行创建 Memo;普通 definitions 不受该流程影响。

网页读取扫描最多 2,048 个不同公开链接,按 query 与链接周围的书目内容匹配排序,再返回最多 8 个公开 HTTPS 链接(不自动访问),便于核实原始论文或摘要。旧书目中的 HTTP 链接只返回保留 host/path/大小写的 HTTPS 候选,实际请求仍必须通过公开地址和连接 DNS 校验,不发送 HTTP、不回退到明文。同一书目条目优先返回 PDF 等原文链接,标签带书目上下文,避免 PDF/bibtex/code/video 占满候选。收集阶段会合并同一 Google Scholar 作者的地区镜像,并优先读取文章页。收集结果保留每次搜索的全部前五个候选,供模型比较。研究查询使用短的互补问题,避免把所有线索拼成长查询。

SerpApi 设置 nfpr=1 请求保留原查询,但 Google 仍可能改写。 如果返回 showing_results_for 与原查询不同,返回空结果和 provider_query_rewritten 警告;单个明确 site:domain 查询的域外结果也会被过滤并报告 provider_site_filter_mismatch,不会冒充该域的来源。没有证据时应调整查询或说明限制。

调用回执记录搜索 provider、状态、耗时与归一化结果快照。 搜索请求发出前保存 intent,避免进程中断后误报成功;最终保存失败时不重发请求。 未返回的账单、缓存命中与实际费用均为未知;Tavily 仅记录响应实际提供的 credit 用量。 查询会发送给外部 provider,并进入回执;不要包含秘密或私有文档正文。

运维可通过 dreamlake-server/scripts/export-search-observations.ts,显式指定 --users、--since、--until、--out、--revision 导出本系统的搜索快照。 可选 --namespace 和 --source 上传到已有的非公开组织 Source,使用 DREAMLAKE_REMOTE 和 DREAMLAKE_API_KEY,上传后读取并校验 SHA-256。 内容寻址允许重跑同一时间窗,不会重放搜索。这不是自动开启的团队采集任务, 也不会读取 Claude/Codex 本地历史;规范化快照不是完整供应商响应。

可重复的研究验收

dreamlake-server/scripts/benchmark-research.ts 是显式执行的运维验收程序, 不是后台采集器。它从网站 catalog 读取指定 definition 的当前 revision, 使用 SerpApi 发起一轮研究,记录部署 revision、输入来源与 SHA-256、流开始耗时、 总耗时、工具回执和 Memo ID。必须同时出现搜索、正文读取、研究保存、Memo 创建, 以及保存后对同一个 Memo 的成功读取,才能标记工具链通过;结果相关性和原文 支撑仍需人工评审,不能由工具链成功推断。

sh
cd dreamlake-server
pnpm exec tsx scripts/benchmark-research.ts \
  --namespace TEAM --definition DEFINITION_ID \
  --question /absolute/path/question.txt \
  --source 'original-question-reference' --out /absolute/path/new-run

默认仅准备输入记录,不发请求、不创建 Memo。加 --execute 才会使用 DREAMLAKE_API_KEY 调用指定的 HTTPS API(默认 https://api.dreamlake.ai), 可能消耗搜索与模型额度并创建一篇私有 Memo。每轮上限 360 秒;不自动重试。 输出目录必须尚不存在,保存到权限受限的本地文件;不要提交或公开实际查询、 回复和回执。输入应保留模糊线索,预期答案另存于评审记录,不能泄露到被测 prompt。

state.json 在发送前持久化请求意图,拿到 session/turn 后立即保存恢复标识。 中断、超时或不确定写入后,先检查该 session 的回执和 Memo,不能删除输出目录 后盲目重跑。result.json 区分准备、阻塞、未完成和工具链通过但质量待评审; 上游 402 不会被记为已搜索。该程序测试 API 工具链,不代替浏览器中的 @agent 选择演示,也不代表供应商对比、计费准确性或 14 天基线已经完成。

后续阶段:用授权的真实任务进行同题比较,再根据结果决定默认 provider、 复杂网页抓取、fallback 和费用展示。历史回填、14 天报告和 Metronome 不属于第一阶段。

dreamlake-server/src/builtin-agent/harness/plugin.ts:

ts
interface ToolPlugin<A, R> {
  name: string // 模型可见,稳定;^dreamlake_[a-z0-9_]+$
  version: string
  description: string
  inputSchema: JsonSchemaObject // 必须是 additionalProperties:false 的 object
  scope: ToolScope // projects:read | projects:write | notes:read | notes:write | sessions:read | sessions:control | layout:act
  execution: 'backend' | 'browser' | 'runner'
  sideEffect: 'none' | 'write' | 'control'
  idempotent: boolean
  timeoutMs?: number
  maxPerTurn?: number
  execute(ctx: PluginContext, args: A): Promise<ToolOutcome<R>> // { data, resources?, commandId?, summary? }
}

PluginContext 带:identity(userId + SA + context project)、namespace(个人命名空间)、conversationId / turnId / toolCallId、page、scopes、signal、api(AgentApi)、emit(SSE)。

注册与发现:plugins/index.ts 导出 builtinPlugins,routes.ts 启动时 new ToolRegistry(builtinPlugins, new PrismaReceiptStore())。每轮 registry.definitions(scopes) 只把本轮 scope 内的工具交给模型(OpenAI function 格式)。scopesFor(capabilities):读 scope 恒有;layoutActions:1 → layout:act;sessionControl:1 → sessions:control;notesWrite:1 → notes:write。capability 是人每轮给的授权声明,不是存储的权限;每次 execute 仍检查 scope。

执行流程(registry.execute):scope 检查 → 每轮次数上限 → JSON.parse + Ajv 校验(拒绝多余字段,模型无法塞 actorId) → receipts.start(写不进回执就拒绝执行:agent_receipt_unavailable) → plugin.execute 在 AbortSignal.any([turn, timeout]) 下运行 → 结果截断到 48 KiB → receipts.finish。错误分类:取消 → uncertain;带副作用的超时 → uncertain(可能已落地);写入的未知错误与 5xx → uncertain;已知且未发生副作用的拒绝 → failed。turn 结束时 settleTurn 把仍 running 的回执标为 uncertain。

CLI / TS API / agent tool 复用同一契约:plugin 不碰 Prisma 读用户资源,而是通过 harness/api.ts 的 inProcessApi(Fastify inject,带调用者 bearer 与 x-dreamlake-agent-* 归因头)调用 /namespaces/:ns/terminal-sessions…、/namespaces/:ns/notes…、/namespaces/:ns/session-commands…。CLI 命令和 @dreamlake/dreamlake-cli/api 调用的是同样的路径、body 和错误码。所以"对等"不是靠文档约定,而是同一份路由。

4. 前端执行(RFC 第 3 项)

保留原有 typed layout bridge(dreamlake_apply_layout,execution:'browser',maxPerTurn:8,绑定 session/turn/revision,20 s 等待浏览器 ack,未确认即 unconfirmed)。本次新增:

  • capabilities.sessionControl 开关(header 上的 Shield 按钮,aria-pressed,localStorage 记忆)。关着时模型根本看不到控制类工具。
  • SSE tool 事件(toolCallId / name / status / error / receiptId / commandId)渲染为 composer 下方一行一条的回执,永远不含结果正文。

5. 后端执行(RFC 第 4 项)

  • 内容读取:dreamlake_note_read(body 或 section、行范围、24k 字符截断,返回 etag)、dreamlake_note_sections、dreamlake_notes_search。读遵循调用者实际权限(memos 路由自己的 ACL)。
  • 文档编辑:dreamlake_note_append = 读 body 拿 etag → PUT …/body 带 If-Match。并发编辑返回 412 stale 而不是覆盖;历史由 memos 服务自身的版本机制保留。只在 notes:write scope 下提供。
  • 搜索:GET /namespaces/:ns/notes?q=,返回可定位的 section matches、普通 Memo URL 引用和 href。新引用不生成 :note 指令;已保存的旧指令仍可读取。
  • Session 读取:dreamlake_sessions_list(mine/available,runState 过滤,needsAttention = waiting|error)、dreamlake_session_get(descriptor + 有界 conversation tail + 关联资源 + 最近命令)、dreamlake_sessions_activity(时间窗口内的 work map:按 owner 聚合 session 与关联 note/artifact)。
  • 归档/改名:PATCH …/terminal-sessions/:id/archive(新)与 /name。归档只影响列表(archived=include|only 可查),不动进程。
  • 持久记录:AgentToolCall(conversationId/turnId/toolCallId/tool/version/scope/argsDigest/args≤4k/status/resources/commandId/summary/error);SessionCommand.origin 记录 {kind:'builtin-agent', conversationId, turnId, toolCallId},与资源活动归因头一致。GET /agent/sessions/:id/tool-calls 读回执。

6. 沙盒 / 运行环境执行(RFC 第 5 项)

repo 直接使用 checkout,worktree 在用户目录下创建独立 Git worktree。pod 由用户明确配置的 runner 通过本地 Docker 执行;sessions serve --pod-config /abs/config.json 才声明此能力,未配置返回 pod_not_configured。配置固定镜像 digest、精确仓库 realpath 白名单、网络、CPU/内存和可选的私有 provider env 文件。容器使用 UID 1000、只读根文件系统、禁用 capabilities、独立持久 home volume;read-only 同时把仓库挂载为只读。不挂载宿主 home 或 Docker socket。只支持 headless,执行、停止和恢复都验证 runner 标签并定位容器 ID。镜像必须预装 Node、Codex/Claude 和可写的 /home/agent。这不是远端资源 provisioning,也不会使用控制面 IAM。

原生权限模式不等于 OS 沙盒;Claude plan 模式仍需容器文件系统约束才能证明文件不可写。permissionLevel 映射:read-only → claude --permission-mode plan / codex --sandbox read-only;workspace-write → acceptEdits / workspace-write;full-access → bypassPermissions / danger-full-access。

Runner 两种模式:机器上有 tmux 3.2+ 时 tmux new-session -d,session 名与 terminal gateway 约定一致(dl-claude-<hash> / dl-codex-<hash>)并打上本 runner 的 ownership 标记(send/stop 前校验 owner + pane 身份);本机 tmux attach 可接入,浏览器终端 / sessions open 仍需 enrolled host;没有 tmux 时 headless:claude -p --session-id … --output-format json / codex exec --json,send 变成一次 --resume 回合并把回复放进回执。文本永远以参数数组传给子进程、prompt 走 stdin(交互启动用 -- 边界),不经过 shell 字符串也不可能被解析成选项;start 记录的 permissionLevel 会在后续每个 provider 进程(resume / headless send)上重新施加;headless send 在 transcript 一分钟内被他人写过时拒绝(native_session_active);runner 并发执行命令,stop 能打断正在跑的 headless 回合;租约被拒即中止子进程且不再上报。交互启动通过 tmux new-session -e 原子设置每次 launch 的 nonce;取消窗口中清理前读取并再次核对 nonce,以 tmux session ID 定位,避免误杀同名替代会话。

7. 生命周期与恢复(RFC 第 6 项)

稳定 ID:conversation(24-hex)、turnId、toolCallId(provider 给的 id)、receiptId(AgentToolCall._id)、commandId、runnerId、sessionId(terminalSession)。

SessionCommand 状态机:

pending ──claim(fenced: status=pending ∧ runnerId)──▶ running ──result(fenced: leaseToken)──▶ completed | failed
   │                                                    │
   └── cancel (owner, pending) ──▶ cancelled           └── lease 90 s 未 renew ──▶ uncertain(不重排队)
  • 每个转换都是 updateMany 加精确前置条件;慢 runner、重试的 HTTP、第二个 server 实例都不能完成别人的 claim 或复活已结束的命令。
  • 路由:显式 runnerId → session 绑定的 runner → 唯一在线 runner;否则 session_runner_offline / session_runner_ambiguous 直接拒绝,不盲目排队。
  • start 回执把新 session 的 runnerId 绑定到 session 行;回执里的 runState 作为观测写回(owner 围栏)。
  • 回执只允许一次;uncertain 的语义是"效果未知,先查再重试"(runner 也会主动报 uncertain 并附 checkpoint:如进程已起但注册被拒),plugin 结果里会对模型明说。
  • 幂等:SessionCommandKey 唯一索引做原子预留;同 key 不同输入 → 409 session_command_idempotency_conflict;built-in agent 每个 tool call 自带 key(agent:<hash(conversation, turn, toolCall)>),provider 重试不会入队两次。
  • 围栏:built-in agent 提交命令时,服务端在同一事务里校验该 conversation 的当前 turn 租约并插入命令(agent_turn_not_current);registry 在任何副作用前重新续约(renewAgentTurn),且续约与执行一起受 deadline 约束;租约到期(leaseExpiresAt)写进 renew/result 的原子谓词;回执终态、session 绑定与原始 start 权限在同一事务提交;缺失或无效 sessionId 拒绝完成。rename / archive 这类由本 PR 拥有的路由在提交时同样用条件写围栏(带 agent 归因头的请求进事务);对 memos 这类复用既有路由的写入,围栏是执行前的续约加写后复核:若写入期间 turn 被接管,回执标为 uncertain(turnLostAfterWrite)并告知模型不要重试——已声明为边界。in-process API 自动携带当前 turn 头,rename/archive 无需各自补头;写后复核也受同一 deadline 和取消信号约束。SessionCommandKey 预留带 generation,回收后旧持有者的绑定/释放都不再匹配。
  • Runner 侧:同一 session 同时只跑一个 send/resume 操作(tmux 与 headless 共用预留)(session_busy);stop 等到进程真正退出才回执(否则 stop_unverified/uncertain);provider 非零退出一律 uncertain(可能已改文件);租约被拒或本地租约到期即中止并不再上报。

8. 端到端(RFC 第 7 项)

"把 'rebase on main' 发给那个在等我的 Claude session":

  1. 浏览器开启 session control,POST /agent/chat 带 capabilities:{layoutActions:1, sessionControl:1}。
  2. scopesFor 给出 sessions:control,registry 把 dreamlake_session_send 等交给模型。
  3. 模型先调 dreamlake_sessions_list({runState:'waiting'}) → plugin 经 in-process API GET /namespaces/marvin/terminal-sessions?sort=recent → 回执 r1。
  4. 模型调 dreamlake_session_send({sessionId, text, wait:20}) → plugin POST /namespaces/marvin/session-commands(头里带 conversation/turn/toolCall)→ 命令 pending → GET …/session-commands/:id?wait=20 长轮询。
  5. 用户机器上的 dl sessions serve 在 claim 中拿到命令(租约 90 s),tmux load-buffer / paste-buffer -p 整段粘贴,再用 send-keys Enter 提交,POST …/result {leaseToken, status:'completed', result:{delivered:true, runState:'working'}}。
  6. 服务端围栏校验租约,写回执,更新 session runState;plugin 返回 {command: completed},registry 写 r2(commandId 关联),SSE tool 事件带 commandId;模型回答。
  7. 浏览器关闭、worker 崩溃:命令和回执都在数据库;sessions control wait <commandId> 或 dreamlake_command_get 随时查;runner 死了命令变 uncertain,不会重复发送。

9. CLI 与 TypeScript API 对照表(RFC 第 6 项 / Memo 02 第 6 条)

能力Agent toolCLITypeScript API (createClient().sessions(ns) …)HTTP
列 sessiondreamlake_sessions_listsessions list / sessions list --archived includesessions(ns).list / availableGET /namespaces/:ns/terminal-sessions, GET /terminal-sessions/available
看 sessiondreamlake_session_getsessions show + sessions resourcesget / conversation / resourcesGET …/:id/metadata, /conversation, /resources
work mapdreamlake_sessions_activitysessions list --sort recent + resources组合上两项同上
改名 / 归档dreamlake_session_rename / _archivesessions rename / archive / unarchiverename / archivePATCH …/:id/name, PATCH …/:id/archive(新)
启动(隔离 + 权限)dreamlake_session_startsessions control start --isolation worktree --permission …commands.create('start', …)POST /namespaces/:ns/session-commands(新)
resume / stopdreamlake_session_resume / _stopsessions control resume / stop --yescommands.create('resume', …) / commands.create('stop', …)同上
send / broadcastdreamlake_session_send, dreamlake_sessions_broadcastsessions control send / broadcastcommands.create('send'), commands.broadcast同上 + /broadcast
receivedreamlake_session_sync + _getsessions control sync + sessions showcommands.create('sync') + conversationPUT …/conversation(已有)
status / subagentsdreamlake_session_status / _subagentssessions control status / subagentscommands.create(...)同上
命令回执dreamlake_command_getsessions control wait / list / cancelcommands.get / wait / list / cancelGET …/session-commands/:id?wait=
runnerdreamlake_runners_listsessions runners / sessions serverunners.list / register / claim, commands.renew / finish/namespaces/:ns/session-runners…(新)
笔记搜索 / 读 / 追加dreamlake_notes_search / _note_read / _note_sections / _note_appendnotes search / read / sections / appendnotes(ns).search / body / sections / append/namespaces/:ns/notes…(已有)
与 agent 对话 / 回执—sessions chat [--control], sessions tool-callsagent.chat / toolCallsPOST /agent/chat, GET /agent/sessions/:id/tool-calls(新)

错误语义一致:服务端错误码原样穿透(ApiError.code / CLI 输出 / plugin 抛 AgentError(status, code) → 模型看到 {error: code})。

10. 这次改了什么

dreamlake-server(workspace 仓库,分支 feat/builtin-agent-harness)

  • prisma/schema.prisma:TerminalSession 增加 archivedAt、runnerId;增加 permissionLevel、agentReceiptsSettledAt;新增 SessionRunner、SessionCommand、SessionCommandKey、AgentToolCall。
  • 新增 src/builtin-agent/harness/{plugin,registry,receipts,api}.ts;src/builtin-agent/plugins/{projects,layout,sessions,notes,activity,index}.ts。
  • src/builtin-agent/routes.ts:用 registry 取代硬编码工具;capabilities 扩展;GET /agent/sessions/:id/tool-calls;turn 结束结算回执。model.ts:execute 带 call id、回执事件透传。context.ts:系统策略按 scope 说明可用工具与回执语义。
  • 新增 src/session-control/{contract,store,routes}.ts;src/index.ts 注册。src/routes/terminal-sessions.ts:archived 列表过滤 + PATCH :id/archive。
  • 测试:harness/registry.test.ts、plugins/plugins.test.ts、session-control/{store,routes}.test.ts,并更新 routes.test.ts、model.test.ts、terminal-sessions.test.ts。

dreamlake-cli(分支 feat/session-control-api)

  • 新增 src/api/{client,sessions,notes,agent,index}.ts,package.json 导出 ./api,tsconfig 开 declaration。
  • 新增 src/cli/sessions/control.ts(serve / runners / control … / rename / archive / unarchive / chat / tool-calls)与 src/cli/sessions/runner/{native,exec,serve}.ts。
  • 文档 docs/pages/sessions/control、docs/pages/dev/typescript-api;生成的 help examples 已更新。测试 __tests__/api-client.test.ts、__tests__/session-runner.test.ts。

dreamlake-ai(分支 feat/agent-session-control)

  • lib/agent/stream.ts 增加 tool 事件;components/agent/AgentComposer.tsx 增加 session control 开关、capability 发送、回执列表;测试补充两条。

11. 本轮补齐的能力与验收

  • 页面正文通过可见 DOM 文本快照采集,排除表单输入、隐藏区域、composer 和私有标记;上限 24,000 UTF-16 单元、300 结构块,附资源路径、SHA-256、观察时间、选区位置和截断标志。dreamlake_page_read/find 读取和定位该快照;缺失快照明确拒绝。它是浏览器观察,不授予资源权限。dreamlake_open_resources_find 从当前布局的稳定资源 ID 枚举打开的 Memo,逐一经真实所属 namespace 的鉴权 API 搜索,并返回分页和不支持资源类型的 partial 状态。
  • Memos 新增 dreamlake_note_create/source/patch/find。source 使用 v2 的 pinned revision 和 Unicode codepoint 分页;patch 默认 exact original revision,提交前后保存 checkpoint,写成功但读回失败保持 uncertain。局部替换和全量替换都走现有条件编辑与历史保留路径。TS API 的 source/edit/patch/versions/version/find 复用这些路由。
  • 项目搜索支持稳定 cursor 和 content:true:每页最多扫描 10 条资源,文本文件返回 hash 与 UTF-16 命中位置,挂载 Memo 按真实所属 namespace 经鉴权搜索;跳过、截断和下一页显式返回,不能把 partial 的空页当成全项目没有结果。
  • dreamlake_run_macro 顺序运行最多 8 个布局或 Memo source/find/patch、page read/find 步骤。每步校验 schema 和 scope,布局使用 ACK 的下一版本;后续步骤失败保留已完成资源和位置。它不回滚已落地编辑,也不重放未知效果。参数化布局支持 $previous tab/panel ID。
  • AgentBrowserAction 在发出 SSE 前持久化。浏览器 sessionStorage 在布局变更前写 intent,变更后保存 ACK;reload 后同一 action 不再执行。迟到 ACK 保留在 durable action 中,不能覆盖后续 turn。agent.browserActions() / sessions browser-actions 可检查记录。
  • managed 子会话可通过 parentSessionId / --parent 建立关系,列表按父会话过滤,并受父会话记录的权限上限约束。子会话使用普通 session ID 的 send/resume/stop/archive。原生 provider 内部 subagents 的独立生命周期仍不属于轻量 CLI 集成;Claude 本地记录仅供检查。
  • running cancel 设置取消意图,由 renew 传给 runner,中断执行后记录 uncertain。runner 在本地私有、fsync 的 journal 中先记意图再执行,保存 native ID、worktree、容器和 tmux checkpoint。重启上传迟到证据但不重放;服务端 uncertain 状态不因此变成 completed。可验证的旧 pod/tmux 被停止,无法确认的旧进程隔离后续 provider 工作,保留人工检查依据。

2026-10-28 发布前本地验收记录

环境已验证证据限制
本机真实 Codex 0.162.0headless start、同一 native ID resume、预期回复使用临时 Git 仓库;未经过生产服务
本机真实 Claude 2.1.312上游恢复后 start、同一 native ID resume、预期回复未改全局配置;未经过生产服务
独立 loopback Mongo 7 replica set事务失败回滚、绑定与原始权限原子提交、重复/过期租约拒绝、running cancel、迟到证据不可覆盖scripts/verify-session-control-local.ts,仅允许专用本地数据库
独立 loopback RTC并发条件编辑、历史与身份路径;真实 TS client 原始版本编辑、emoji、过期拒绝和旧版本读回native RTC integration;业务归属/存储依赖隔离模拟
真实 Claude + Dockerpod 内启动、停止容器后恢复同一 native ID、预期回复dreamlake-cli/scripts/verify-native-session.ts;真实 Codex-in-pod 也已通过,下文保留 CA 根因和证据
真实 Docker 容器非 root、只读 root/repo、无 socket、停止重启后 home 保留provider 可执行程序为明确的测试 fixture,不能当作真实 LLM 容器验收
runner 进程强杀 + 真实 DockerSIGKILL 后 journal 保留,重启上传迟到证据并停止旧容器,无副作用重放verify-runner-recovery.ts;控制面响应是 fixture,Mongo 路由另行验收
真实 Chromium + UIKit正文隐私过滤、tab activation、reload 保留 ACK、未确认 intent 不重放dreamlake-ai/scripts/verify-agent-browser.mjs,隔离浏览器 fixture,不是生产 app E2E

以上是发布前本地证据,生产结果另见下文,不能混作同一种验收。真实 Codex-in-pod 的 CA 问题已解决。非 Memo 打开资源的正文搜索与原生隐藏 subagent 控制仍返回明确的 unsupported/partial;CLI 发布不代表 413 项映射均做过真实端到端验证。

控制面仍 owner-only;runState 仍是 transcript/进程的启发式观察。五个新 collection 的十项索引已经单独获批并创建;Memo 与既有索引未修改。

12. 两份 Memo 的完整交付核对表与 API 契约(2026-10-28)

以下逐项对应两份 Memo 的要求;“本地”不等于完整产品或生产验收。 CLI 的全部可执行命令另有自动核对的接口清单,包含本地专属操作的排除理由。

Memo 要求API 契约 / 实现验证及边界
无 bash、仅管理其他 session、light integrationtyped plugin registry;session command/runner 协议;原生 codex exec / claude -p无 shell plugin;执行权限留在明确配置的 runner;不在 API import 时启动进程
当前页面真实正文、选区、结构、资源和版本位置browser.readPage/findPage;UI 独立采集 PageContentSnapshot可见 DOM 采集、隐私过滤、SHA-256、UTF-16、有界截断;浏览器观察不授予权限
已打开资源读取/搜索openResources.find;Memo 全局鉴权后按真实 namespace 搜索;显式 projectId 文件读取返回位置、版本、分页及 descriptor revision;拒绝/不支持单独列在 skipped,partial 不等于无结果
授权项目搜索和文件正文projectTools.listProjects/searchProject/readFile服务端按实际 grant 检查;扫描、正文、命中和分页均有界
文档创建、段落/标题/列表与局部修改notes.create/source/edit/insert/replace/removeText/patch;CLI 内部 source span plannerUnicode codepoint 原始位置;确切 revision;拒绝过期写入;业务 Memo 路由保持原样
必要的全量替换及历史保留notes.replaceContent、versions/version全量内容转换为条件 patch;不清空 RTC 历史,不静默覆盖新版本
legacy/new 兼容旧 section/body API 和 CLI 导入路径保留;source v2 明确校验旧接口与新 v2 的单位、版本与错误语义分别说明,不自动降级写入
可复用参数化 macro、稳定目标CLI browser.runMacro;服务端独立 scoped step adapter;稳定 tab/panel/resource ID 与 $previous最多 8 步、顺序 checkpoint;失败保留已完成步骤;未知效果不重放
ACK、失败/取消与恢复durable browser action、sessionStorage intent/ACK、agent.browserActionsreload/迟到 ACK/缺失 ACK 覆盖;未确认保持 uncertain,不能标为成功
session 发现、打开与上下文读取sessions.list/available/get/conversation/resources;本地 open adapter当前 owner 控制边界;本地窗口/TTY 操作留在调用端
start/resume/stop/archivesessions.commands.create/get/wait/cancel、archive、runner 协议原生 session ID、租约 fencing、取消后的未知结果、迟到证据不可改写终态
repo/worktree/pod 与 permission leveltyped command input、runner 精确 repo/image allowlist不自动回退隔离;用户配置执行端;显式网络、资源与权限上限
send/receive/broadcast、委派/结果归档commands、conversation、resources、durable command/result幂等键、稳定调用链、取消/中断、状态与结果归因
rename、父子任务与 subagentrename、parentSessionId、managed children 的普通生命周期;native transcript inspectionmanaged child 受父权限上限约束;原生隐藏 subagent 无独立原生命令时明确 unsupported
CLI/TS 完整能力和类型、示例、错误/权限/版本一致CLI 自己导出的 TypeScript API;createApi(Transport) / createClient;自动命令清单同一服务契约;CLI 保留原调用链,API 薄适配原有函数;本地文件/进程需要明确 adapter
实际读写/委派凭据与 provenanceturn/tool-call attribution、AgentToolCall、SessionCommand、资源与原始版本 checkpoint归因头不是授权;写后读回失败保留写入证据和 uncertain

RFC 的七项架构交付分别对应:第 2 节组件边界,第 3 节工具定义,第 4 节前端执行,第 5 节受控后端 API,第 6 节 sandbox/runner,第 7–8 节状态与恢复,第 11 节真实验收及限制。已有图、状态模型和恢复说明与本表一同审阅。

独立实现与 Memo 路由的边界

遵循用户最新决定:CLI 导出自己的 TypeScript API,CLI 仓库内部保留有价值的函数复用;后端 built-in plugins 和前端保留独立的薄实现,以相同 HTTP/数据契约与测试维持一致。没有独立 @dreamlake/api 包、vendored tarball 或跨仓库运行依赖。Memo 的私有 helper 原位置保留 re-export,但只在 CLI 仓库内共享。

Memo 的路由、RTC 写入与历史服务不因 agent 工具而改变。部署同一个后端进程可能涉及服务重启,这是部署层面的风险,不是业务路由应耦合的理由。此前的发布暂停已由用户在 2026-10-28 撤销;以下历史记录保留其当时状态。

验证记录与历史方案

独立共享包和大规模 CLI 搬迁方案已经撤回。旧实验记录保留在 docs/evidence/builtin-agent-20261028/sdk-parity.json,不代表当前实现。当前 CLI 0.89.0 使用自身 TypeScript 导出,原有 CLI 模块逐文件处置见下文;472 个命令中 413 项映射服务 API 或共享算法,59 项为明确的本地专属排除。

Review 后的权限和恢复约束

独立 Claude Code review 发现并修正:send/resume 不能提高 session 启动权限;未知启动策略拒绝执行;built-in-origin start 受 runner 显式 repo allowlist 和默认 workspace-write 上限限制;status/sync/subagents 也需要会话控制授权;归因头支持 provider 调用 ID 的标点但拒绝不完整身份。归档会话仍可停止,非 owner 不接收 pod/runner 策略细节。

runner 启动后会周期检查旧命令租约,过期 prepared intent 可安全解除隔离,不重放 provider。丢失 runner identity 仍隔离;人工确认旧进程停止后才可带理由 acknowledge 本地 journal。Docker 不可达不能被当成 pod 已不存在。停止后的 pod home 为 resume 保留,需要运维显式清理。

前端新增独立 Memo editing 开关,默认关闭,与 Session control 分开。Memo append 要求原始 ifMatch,macro 失败保留失败步骤的写入 checkpoint;工具记录支持 cursor 分页;broadcast 丢失应答后按各 session 的幂等键重建命令链接,保持 uncertain。chat 请求上限按 UTF-8 正文和历史扩大到有界 1 MiB,仍保留正文与历史字符限制。

跨实现契约脚本 dreamlake-cli/scripts/verify-builtin-contract.mts 通过真实 Fastify 注入比较 CLI API 和独立 backend plugin 的 source/patch、403/412 拒绝语义;它是本地协议证据,不替代 RTC 或生产验收。

Codex 容器网络验收结论

Codex 0.162.0 使用本机既有 ChatGPT 登录完成真实 pod 启动、停止容器、同一 native session ID resume,分别返回预期 START/RESUME 标记。旧镜像缺少系统 CA bundle;Node 自带信任库掩盖了问题,native TLS 的 alert 48(unknown_ca)确认原因。临时镜像补装 ca-certificates 后无需代理或新 API key,未关闭 TLS 校验,也未修改全局 Codex 配置。测试容器和含凭据的 home volume 已移除。

本轮本地完整 CLI 回归 2,323 passed、1 skipped、0 failed,文档测试另 4 passed;后续 review 差异定向 50 passed。后端相关 212 passed、1 skipped;前端 87 passed;两站文档 production build 通过。独立 Claude review 执行 ID、最终验收和限制见 docs/evidence/builtin-agent-20261028/independent-api-validation.json。不把已有截图/fixture 当作生产整链验收。

大规模 CLI 搬迁不是两份 Memo 强制要求的架构:API 能力覆盖要求需要新增接口,但不要求另建共享 package 或改写所有命令。此轮只保留 CLI 与其自身 TypeScript 导出确实使用的函数复用和兼容 re-export;不继续迁移无关 CLI 模块,不把整个 CLI API 目录自动注册为模型工具。

最小 CLI diff 复查(CLI 0.89.0 已发布)

本轮逐项检查旧 CLI 的实际搬迁与调用链,恢复 HTTP、Memo source/编辑/HTML/outline、上传、Library、layout、项目 grants、worker 的原文件;API 在原实现上薄转导出。Jobs/Infra 只新增显式凭据与 fetch 工厂,Memo events/registered receipt 只增加可选请求注入,原 CLI 默认调用不变。撤回 program.ts 拆分,保留小型只读命令清单出口;移除独立 API 编译配置,以现有编译与依赖发布 CLI 自己的 API 导出。

逐文件处置与前后 diff 行数见 docs/evidence/builtin-agent-20261028/minimal-cli-audit.json 和 CLI 最小改动说明(CLI 0.89.0 已发布)。新增 session runner/权限/恢复属于需求功能,继续保留。API 源码和实际 npm-pack 产物均检查导入无登录读取/进程/网络副作用,并从 tarball 验证声明可被 TypeScript 使用。该次 CLI 最小化没有 UI 或后端运行码变更;生产验收另修复了 agent 前端选区捕获时序,见第 13 节。

生产发布索引预检(2026-10-28)

后端合并提交 10c5d9e3 的完整 CI 已通过。生产发布 run 40644124702 在更新 ECS 前按既有规则停止:完整 schema 317 项预检仅缺少本功能五个新 collection 的十个索引;无 blocker、重复记录或并行数组问题。精确规格见仓库 docs/evidence/builtin-agent-20261028/production-index-plan.json。Memo、RTC 和既有索引均不修改。

首次初始化通过手工 builtin-agent-indexes.yml 执行,限 main 和固定十项规格,先 plan、再用数据库绑定的 plan hash 与 CREATE_BUILTIN_AGENT_INDEXES_ONLY 确认 apply;复用既有 additive-only 工具,保留重复/冲突/目标验证,不放宽 deploy 的零新增规则。用户已在 2026-10-28 对这份具体十项计划另行授权;独立计划 run 40645866249 再次确认范围和无冲突。索引源码经 Claude Code session 92306262-7359-4c6f-abf8-b0e45472182c 只读复查,无阻断问题。随后 run 40646216301 以 additive-only 创建并核验十项索引,后端发布 run 40644124702 attempt 2 成功;部署阶段再次核验 317 项,新增数为零。

13. 生产发布与实际验收(2026-10-28)

后端 10c5d9e3(ECS task definition 121)通过完整 CI 和实际镜像/运行任务核验;UI a09e835c(含选区修复)已在 Netlify production ready;CLI 0.89.0 从 Actions 发布,npm 全新安装、API 导入及八个平台有界下载读回通过。完整记录见仓库 docs/evidence/builtin-agent-20261028/production-acceptance.json。生产数据只使用明确的临时私有 Memo 和本机临时 Git 仓库。

生产路径实际结果边界
发布版 TS API → 生产 Memo创建、原始版本条件写、确认版本读回;旧版本写入 412 且正文不变原有 Memo 路由/RTC/历史服务复用
built-in 模型 → Memo 工具source 与有效 patch 回执 completed,写入标记读回匹配模型错误 diff 和错误 ETag 曾被拒绝,正文无副作用;不保证模型总能生成有效 patch
生产控制面 → Mac runner → Codex/Claude两者真实 start、stop 后同一 native ID resume、sync、重命名/归档、managed parent/child 均通过使用已授权 Mac;不是远端生产 pod 启动证明
built-in 模型 → durable command → Codexcommand 的 origin 为 builtin-agent,真实 provider 返回指定标记runner 的 repo 与权限上限保持有效
生产浏览器 → page_read真实 Memo 正文和 SHA-256 快照可读,两个授权开关默认关闭真实选区 PROD_HARNESS_READ_OK、UTF-16 位置 120–140 在生产读回;不长期缓存旧选区
生产 macro → UIKit → durable ACKactivate 当前 Memo 的 action 为 acknowledged / applied,工具 completed实际刷新后会话结果仍在,action ID 与数量不变,无重放

选区读取使用发送当刻的选择:先写问题,再在正文选中文字并点 Send。宏不授予 Memo 写入或会话控制权限;这两种操作仍需各自明确授权。

示例:关闭写入/控制开关时,可以要求“读取当前 Memo,标出包含某个词的位置”;开启 Memo editing 后,可以要求在指定 Memo 的原始版本上条件追加总结;开启 Session control 并在自己的机器运行明确配置的 runner 后,可以要求给指定会话发送任务、停止或恢复该会话。built-in agent 没有独立 shell 工具,也不会使用服务 IAM 替用户启动机器。

Production acceptance: current Memo selection and confirmed macro ACK

临时 Memo 已软删除,测试会话已归档,runner 已停止,临时 Claude 配置副本已移除;用户原有资源和 UIKit 工作区未改动。命名版本保存/目录/正文读回、旧 pinned revision 读回也通过;历史数据仅属于该临时 Memo。

CLI 0.89.0 的 Actions 发布、后端 ECS 发布 与前端 Netlify deployment 6ae1a868cd38c597da4d277b 分别留证。UI a09e835c 的全部产品检查在第二次运行通过;最终聚合 gate 因 main 前移而拒绝,不能冒称该 gate 绿色。后继 main d69ae832 的完整 CI run 40653071556 已通过。高亮标签几何测试另保留同帧观测的修正,避免持有已重建 DOM 的旧句柄;不改变标签位置、过期或正文不变断言。

14. Memo 改写可靠性修正(2026-10-28)

生产用户反馈显示:手写 unified diff 的 hunk 行数错误会被正确拒绝;随后模型又将 sha256: 内容哈希作为旧 ETag,导致 stale,并错误归因于并发修改。相同 RTC revision 的只读回查证实不能作这种推断。

新增 dreamlake_note_replace(noteId, baseRevision, content):模型只提交目标正文,服务端读取原始 retained revision,以现有 canonical patch 算法生成差异,再走原有 exact 条件写与确认版本读回;不改变 Memo 路由、RTC、权限或历史。note_append 同样优先使用 source 返回的 RTC baseRevision,旧 ifMatch 兼容路径明确拒绝哈希/RTC revision,避免误报并发。失败后不切换 merge 或换 baseline 盲目重试,未确认的写入保留 uncertain 状态。

同时修正通用工具参数的 2 KB 硬限制与工具声明不一致的问题:单调用保留 256 Ki UTF-16 code units、每轮累计 512 Ki 的硬上限;模型输出上限 8192 tokens,收到 length 截断时禁止执行不完整调用。此修正也覆盖长会话消息和宏参数。Memo canonical source 每页最多 6000 Unicode code points,next 与原始 revision 保留在 48 KiB 结果预算内;后续页必须指定同一 at。错误反馈仅提供固定指导,不透传原始服务错误或凭据。

验收必须使用普通自然语言让真实模型自行调用 source → replace/append;提供预制合法 patch 不能替代该验收。用户随后明确授权原 Memo 参与验证;生产版本 da5dad07 已通过真实模型 source → replace 改写,改写前命名版本保留。临时 Memo 的 source → append 也已通过。

本次追加 review 处置:模型工具轮次从 4 轮/6 次调整为最多 12 轮/24 次(最后一轮只生成回答),registry 另有含 macro 子步骤在内的 64 次总上限。macro 每步重新走 registry,共享权限、schema、单工具次数和独立 deadline,并记录独立 receipt;父 receipt 保存子 receipt ID,未知结果不重放。全部生产工具声明可兼容新增字段的输出 envelope schema,registry 在标记 completed 前校验;写入后输出不匹配按 uncertain 处理。GET /agent/tools 为登录且满足部署团队限制的调用者提供版本、输入/输出 schema、scope、执行边界及幂等声明;发现工具不授予调用权限,也不创建会话身份。

review 中以下不是本轮应自动扩大的架构:项目文件工具继续要求显式 service-account 项目 grant,属于比用户登录权限更窄的范围,不能声称可读所有用户项目;Note/会话则走用户 token。execution 是描述底层依赖的发现元数据:page_read 读取发送时的浏览器快照,layout 才有真实浏览器 ACK,runner 插件只排队,不表示服务端直接执行。idempotent 表示操作本身可安全重复,不承诺对所有写入通用去重;session command 通过 conversation/turn/toolCall 派生稳定 key,macro 子步骤派生稳定 child call ID;Memo 写入依赖 revision 和不自动重试。保留兼容 read-tool 路由,不引入独立共享 SDK、托管 sandbox 或新的服务 IAM 权限。多实例全局准入仍不由进程内 Set 保证,现有会话 lease 不应被描述成全局用户并发配额。

模型接口兼容性与历史发现(线上验收追加)

ce946bd2 已发布。真实模型 A/B 探测发现:只读、会话控制和布局权限的短提示均可完成,但启用 Memo writing 时在执行工具前被模型接口拒绝。因此移除 append 输入 schema 新增的顶层 oneOf,由执行器在任何 API 访问前检查 RTC baseRevision 与旧 ifMatch 必须恰选一个;模型工具的顶层 schema 不使用组合关键字。上游拒绝保留兼容的 agent_model_unavailable,同时仅返回 upstreamStatus 数字,不暴露上游响应正文、密钥或提示词。

同时修复个人 namespace 的旧 Mongo 记录缺少 orgId 时 agent 历史列表为空:查询明确兼容 null 与缺失字段,继续限制 owner、live namespace、private managed conversation 和原有分页边界。这两项追加修正已在 da5dad07 发布,完整 CI run 40680689375、部署 run 40680718232 和真实模型改写/追加验收均通过。此前预制 patch 的验收不能替代这项验证。

局部 patch 的精确文本输入(待发布)

CLI 0.89.0 的合法 unified diff 在生产成功插入中文 checkbox 区块,并读回确认版本逐字核验。实际失败的 agent 调用先读了 canonical source,但 hunk 声明旧内容 6 行、正文只有 5 行;本地复现为 Unified counts do not match,不能归因为中文、渲染文本或并发修改。

dreamlake_note_patch 新增 format: "text-edits",输入 edits: [{oldText, newText}],不同时传 patch。每个 oldText 必须在原始 baseRevision 的源码中恰好出现一次;插入时在两侧保留一个唯一锚点,删除时 newText 为空。至多 8 项,每段文本最多 4000 字符,全部在同一原始源码上匹配,不得重叠或依赖前项生成的新文本。程序生成合法 diff,复用现有 Memo API 的 exact/merge 语义与确认版本读回;没有模糊匹配、自动换基线或修改 CLI/Note 路由。

兼容的 diff/inline-dff 输入在写入前校验原始源码。无效行数返回 note_patch_invalid_counts,源码不匹配、语法错误、找不到文本、重复匹配及重叠分别返回固定错误码;原始服务错误和源码不进入错误反馈。模型应根据实际错误码解释原因。成功 macro 的最终回执保留每个子步骤的 receiptId,避免终态摘要覆盖执行时的关联记录。

Memo reading and session search scope

The agent reads Memos through the same contract=v2&view=reading body contract as the CLI Markdown reading view. Responses contain addressed text, source hash, opaque revision, scope, and start/end/total/complete/next reading-view offsets in Unicode code points. Generated reading hints are not editable source. Continuation requires at with the original revision; changed or expired revisions never silently advance. Each page budgets escaped JSON text to 32 KiB, below the tool envelope limit. Whole-note tasks follow next until complete; focused reads use toc, section, or tag. Edits still use canonical source.

Session discovery defaults to the caller's personal sessions. An explicit owner namespace, team organization slug/id, or scope=available expands only the selected search scope; it grants no access and never changes visibility. No matches do not automatically widen the scope. Both metadata and uploaded, redacted user/assistant conversation text can match. Tool/system payloads are not indexed. Read authorization is applied before keyword matching and paging.

Codex/Claude registration currently defaults new records to public unless explicitly private; absent legacy visibility stays private/team. Public sessions can be read anonymously. Organization-shared sessions require current valid memberships and owner authority; private sessions remain restricted. Built-in agent conversations remain owner-only. Reading/searching grants no control rights.

Broad transcript search fails closed with terminal_search_scope_too_large when it exceeds 64 owner/namespace groups or 256 owner/team policy-check units (at most 768 policy database calls); narrow with owner or team. Anonymous searches without an explicit owner match metadata only. An explicit foreign namespace is treated as an owner filter and conflicts with scope=mine. Team slugs accept an optional leading @. Existing built-in conversations enter the transcript search index on their next turn; this release does not backfill historical conversation bodies.

The deterministic scope limit returns HTTP 422; narrow the query instead of retrying it. Listings with no keyword keep their existing pagination and do not enumerate all owner groups.

Acting namespace

/su NAMESPACE selects the acting namespace for the current built-in agent conversation. The argument is a real namespace slug, such as /su alice or /su acme; personal is not a special target. The session UI shows the selected namespace. Other conversations and the application's current workspace keep their own state. The conversation's resource commands, including /ssh, use this acting namespace. Without an explicit selection, they follow the selected application workspace.

The signed-in user remains the caller. Namespace access is checked by the server, and each resource operation still checks that caller's permissions. Switching to an organization namespace never grants another member access to a personally owned host. The acting namespace is pinned for each turn; a scope switch must not retarget a tool call already in progress.

Switch scope to work with resources where they already live. Use the host move operation when the resource itself should be filed in another namespace. Host move tools use the same preview and guarded apply API as the CLI and SDKs; mutation tools require the session's explicit control capability as well as resource authority.

Developer palette: personal SSH targets

With Developer Mode enabled, the built-in command palette's /ssh search includes the signed-in user's personal computers alongside computers in the conversation’s effective namespace. Toggle Developer Mode with ⌘⇧D, open the palette and enter /ssh my-laptop. Personal results are marked Personal · NAMESPACE; choosing one opens its terminal using the result's namespace while the Memo and application stay in their workspace. No /su or host move is required.

This is a discovery option, not an authorization exception. The existing host API and terminal delegation still check the signed-in owner. Turning off the flag separates the search cache from personal discovery; sign-in changes also change its authorization generation. If one inventory is unavailable, successful results from the other namespace remain available and the failed inventory is shown as unavailable.

Thinking details(按会话与 turn 保存)

内置 Agent 的可折叠 Thinking details 区域只显示供应商实际返回的可见推理或摘要。 OpenRouter Chat Completions 的 delta.reasoning、reasoning.text.text 和 reasoning.summary.summary 进入独立的 reasoning SSE 事件;同一 chunk 有结构化 reasoning_details 时优先使用它,避免重复显示。加密内容、签名、未知字段不发送, 供应商不提供文本时明确显示无可见内容,不根据 token 数或工具活动编造推理。

持久化要求后端与 UI 都包含本节实现。可见文本作为会话的独立 reasoning sidecar 保存,键为 sessionId 与服务端 turnId,并用 userMessageIndex 定位原始用户消息。 每条记录固定保存 admission 时的 actingNamespace;浏览器只显示当前工作空间的 记录,切换工作空间不会改写旧 turn 的归属。未知旧记录的 scope 不自动补成当前空间。 不进入回答文本、复制、搜索索引、模型历史、工具回执或诊断日志。恢复会话后仍默认 折叠,展开区域有独立滚动范围;新 turn 保留以前的记录,切换或更换登录身份不会 泄露另一会话的内容。旧会话没有保存过的文本无法补回。

完成或取消时与回答在同一 lease/generation-fenced transaction 中保存;后台运行 每两秒随 checkpoint 替换同一个 turn 的记录。取消、失败及过期租约标记 interrupted。进程突然退出只能恢复最后一次 checkpoint,普通前台 turn 则需到 结束时才保存。每个 turn 最多 16,384 个 UTF-16 code unit,会话最多 200 条; 独立预算不会挤占回答的既有 1 MiB 上限。读取仍要求当前会话所有者身份;不增加公共 读取入口,不存加密推理、签名或未知供应商字段。

服务端在完整行边界做凭据脱敏后实时发送,最后一行在模型轮次结束或开始输出回答/ 工具时发送;取消时丢弃未完成的行。整个 turn 的输入与显示文本各限制为 16,384 个 UTF-16 code unit,事件最多 256 个,浏览器再次限制文本长度。达到显示上限会提示, 不会因此停止工具或回答。该显示不改变模型选择、推理预算或已有授权流程。

研究延迟诊断

聊天 SSE 的 model_timing 事件逐轮报告模型请求耗时、响应头/首事件/首输出时间、 输入长度、输出/参数/推理字符数,以及上游提供的 token 用量和路由标识。 不会发送提示词、工具参数或推理正文。工具执行耗时仍来自独立回执, 不能将模型等待和搜索调用混算。研究验收脚本保存事件接收时间和逐轮测量, 未知用量保持缺失而非记为零。

研究流程的查询规划与后续证据判断使用 OpenRouter reasoning.effort=medium,仅剩保存、回读或最终回答时使用 reasoning.effort=none。各轮使用 provider.sort=latency 和 require_parameters=true;不要求上游支持可选的 parallel_tool_calls 参数,返回的工具调用仍由服务端按顺序执行并逐次检查流程阶段与预算,每轮上限 4,096 输出 token。来源选择需要根据刚读取的证据重新判断,不能仅为减少延迟而关闭所有后续推理;完成来源收集后则不再开启额外推理。普通 Agent 的模型参数保持原有行为;不支持这些参数的上游明确拒绝,而非静默忽略。速度和论文质量仍需独立实测。 BUILTIN_RESEARCH_MODEL 可为显式 research-v1 流程配置独立的 OpenRouter 模型;为空时沿用 BUILTIN_AGENT_MODEL。普通 Agent 不读取此覆盖值。BUILTIN_RESEARCH_PROVIDER 可同时限定研究模型的上游 provider slug(例如 openai),设置后仅允许该上游且关闭跨上游回退;为空则保留延迟排序。生产预检使用相同路由,限定上游不可用会阻止发布,而不是静默切换。固定路由不保证延迟,仍需观测实际模型轮次。生产部署从同名 environment variable 注入;模型不可用或参数不支持时明确失败,不静默换模型。 配置覆盖值后,生产发布在滚动更新前执行一次最多 256 输出 token 的惰性工具调用探测;探测只验证模型可用性和参数契约,不执行返回的工具,也不证明端到端检索质量。探测失败则停止本次发布。model_timing.model 仅记录上游返回且通过安全字符检查的模型标识,便于比较实际运行。

选中的 Agent definition 以独立 user 消息传给模型,位于历史之后、当前问题之前;上下文只保留名称和 revision。它是当前任务的指令,不是系统权限,也不能扩展工具或资源授权。研究 benchmark 将原始问题原样发送,保存与回读要求来自所选 definition,不额外拼接 benchmark 提示。网页读取若遇到已识别的 HTTP 200 防机器人/访问拦截页,会返回 agent_web_read_challenge,不会生成研究证据句柄;可寻找另一个公开原文来源,不能绕过拦截。

论文检索可在 dreamlake_web_search 或 dreamlake_research_collect 指定 engine: "scholar",使用当前 SerpApi 凭据访问 Google Scholar;默认 engine: "web" 保持普通网页检索。Scholar 返回未验证的 publication 书目信息与至多三个 resources 公开原文链接,必须继续读取原文才有证据句柄。历史 HTTP 原文资源链接仅提供同一 host/path/case 的 HTTPS 地址;实际读取仍需通过公共网络与重定向检查。该模式支持结果 offset、count 与 language,不支持 country;其他 provider 不支持 Scholar,明确返回 agent_search_engine_unsupported,不自动切换 provider。检索观察记录 request.engine、response.engine 与 adapterVersion 3,以区分两种检索模式;没有上游计费证据时仍不推测费用。模型上下文包含本轮所选 searchProvider,供定义选择兼容的检索模式。 示例定义用不同名字片段发现候选,优先读取最相关的 1–2 个原文;只有追溯早期原作会改变答案时才继续查参考文献,不要求与先前聊天答案一致,也不把工具预算当成必须用完的次数;已知标题的原文链接不可用时,以同一 provider 的 engine: "web" 精确标题检索寻找其他公开副本,不在 Scholar 中反复返回同一仓库。PDF 未提供年份时,可读取返回的机构出版记录进行核对。

PDF 的 query 含 References 或 bibliography 时,读取器会识别独立参考文献标题(包括 PDF 小型大写排版产生的 R EFERENCES),优先返回连续的参考文献段落及开头书目信息,仍受 8,000 字符摘录上限约束。没有识别到标题时沿用关键词窗口;不能把截断的参考文献声称为完整列表。

Resource API discovery and agent authoring

See Resource APIs in the built-in agent for the public tool contract, coverage inventory, agent creation and transport limits.

Conversation model selection

See Choose an agent model for the canonical UI and API contract: configured-route discovery, conversation-scoped selection, explicit Default reset, availability errors, and provider-reported model receipts.

Explicit personal-agent project delegation

The built-in agent retains its personal account across conversations. Human Project access, persistent delegation to that agent, and the current turn's tool capabilities are separate checks. Human Project ADMIN does not supply an agent WRITE grant. Memo filing uses the Memo route's caller permissions; a missing Project tree grant does not establish that Memo filing is forbidden.

GET /agent/project-grants/:projectId?namespace=:namespace diagnoses one exact Project for the authenticated caller's own built-in agent. It requires current human Project read access, returns no other users' grants, and never provisions an identity or changes access. A missing/inaccessible Project returns 404. The response is private and not cached:

FieldMeaning
human.role, human.manageGrantsCurrent human Project role and ADMIN capability
agent.state, agent.role, agent.managedExisting identity state, exact delegation, managed context flag
operations.readProject, createFolder, manageProjectGrantsAdvisory allowed, requiredAgentRole, and refusal reason
delegation.canSet, canRevoke, roles, endpointHuman delegation controls, limited to READ/WRITE
turnCapabilityCheckedFalse on this HTTP snapshot; it cannot observe a future turn

The read-only dreamlake_agent_project_access tool uses this endpoint with resources:read. It works without a Project service-account grant, adds the current turn's Project read/write capabilities and acting namespace, and intersects them with each operation's advisory result. Its turnCapabilityChecked is true. This diagnostic does not replace authorization when the operation executes.

A human can explicitly delegate READ or WRITE on that exact Project through PUT /agent/project-grants/:projectId with { "role": "WRITE", "expectedRole": null }. expectedRole is optional for compatibility; clients performing a reviewed update should send the previously observed role (READ, WRITE, ADMIN, or null). A changed snapshot returns 409 agent_project_delegation_changed; refresh and review instead of retrying blindly. DELETE revokes the exact own-agent delegation, including after the human loses target access. The managed context grant cannot be changed.

These mutation routes are excluded from model tools and refused by the in-process agent transport. The account is derived from the authenticated user. Setting a grant requires current Project ADMIN inside the existing account/target mutation transaction. Delegation never grants ADMIN, changes human membership or ACLs, or equips a machine identity. A UI must refresh after a mutation and distinguish persistent delegation from per-turn tool capability. No success is inferred from an optimistic local selection.

Organization-scoped turns can use explicitly delegated Projects in their selected namespace. Each operation still intersects the explicit grant with current human Project permission and the turn capability. Such turns cannot inherit personal or other-organization Project grants; discovery filters those out. Personal-scoped turns may use exact delegated organization Projects. Cross-namespace Project ADMIN operations remain unavailable. READ enables discovery and small-file reads; folder creation requires WRITE, the write turn capability, and the resource route's ACL. Restricted mode, revocation and loss of human access remain authoritative. These checks retain existing preflight/post-read semantics; a diagnostic snapshot is not an atomic authorization guarantee against concurrent grant changes.

Tool attempt observations

The registry emits one safe tool_observation per invocation, including preflight refusals, macro children, cancellations and uncertain outcomes. Fields include registered tool/version, server-generated attempt ID, hashed call/turn correlation, duration, error class/status, actor mode and outcome. Receipt persistence retries are not extra attempts. Model retries are separate attempts. Macro children are marked so top-level rates can exclude them. Prompts, arguments, private bodies and raw errors are excluded. Reporting failures never affect tool execution.

Structured server logs cover all registry entry points. Connected web clients forward observations as agent_tool_completed through the existing PostHog privacy and opt-out path, alongside existing error exceptions. This denominator covers observed browser-delivered attempts, not all server executions: disconnects and disabled analytics can omit delivery. CLI/read-tool attempts remain in server logs and receipts; they are not included in the browser denominator.