@margay/ccl-core 1.5.0-alpha.4 → 1.5.1-alpha.2

package/sdk/API.md

@@ -6,6 +6,8 @@
 
 原生 `UserPromptSubmit` 的来源、消息 ID、排队与恢复语义见 [输入身份契约](../docs/hook-input-provenance.md)；该文档明确区分源码候选与已发布版本。
 
+`1.5.1-alpha` 接口 `createBackgroundClient` 及独立后台生命周期见 [持久后台接入契约](../docs/background-runs.md)。其事件返回 `{events,nextCursor,hasMore}`，支持 `limit` 分页；不要套用本文历史会话接口的默认 CLI 定位或内存回调机制。工具操作恢复另见 [命令适配](../docs/command-tool-recovery.md) 和 [MCP 恢复](../docs/mcp-tool-recovery.md)。
+
 ---
 
 ## 1. 引入与运行要求
@@ -111,6 +113,19 @@ Query 控制方法，`pid` 用于宿主监控。
 终止进程并拒绝未完成轮次。权限回调可等待宿主决定，interrupt/close 会取消
 等待；返回 `pending` 仍表示持久挂起，后续用 `resumeWithDecision` 恢复。
 
+**后台工具与可交互前台是两个层次。** `Agent(run_in_background: true)` 会先返回
+启动结果，但 CLI 的 print/SDK 路径可能继续等待该输入所属的后台工作及完成通知，
+才发出这一轮的 `result`。`Session` 按该终态串行发送下一条输入，因此收到
+`assistant_text` 中的接收确认，不代表同一 Session 的下一次 `prompt()` 已可执行。
+不要把 `Turn.result` 当作“前台确认已显示”事件，也不要用 `steer()` 充当无损的
+后台移交；它会中断当前轮。
+
+若应用要求后台任务运行期间前台仍可对话，可将工作交给**独立的 worker Session**，
+主会话不等待 worker 的 `Turn.result`。由应用保存任务与 worker 的关联，消费其结果，
+再将实际完成结果交给前台。多个 Session 是独立执行上下文，需要明确传递任务、
+权限与材料引用；进程中的 Session 本身不是持久队列，应用仍需处理保存后派发失败、
+退出恢复与结果未知。此路径的接口并发可用性不保证模型服务的前台响应时延。
+
 ---
 
 ## 3. 事件参考(SDKEvent)
@@ -134,6 +149,39 @@ Query 控制方法，`pid` 用于宿主监控。
 `result` 只结束对应 `turnId`，后续仍可能有输入。`suspended`、fatal `error`、
 关闭或输入 EOF 结束流式 query；不要把首个 result 当作常驻 Session 已关闭。
 
+### 子任务生命周期事件
+
+启用 `includeRaw: true`，从 `event.type === 'raw'` 的 `event.message` 读取
+宿主 `type: 'system'` 事件。`createSession` 可通过 `onEvent` 消费同样的事件；
+这些事件不会另外转换成同名的顶层 `SDKEvent`。
+
+| subtype | 主要字段 | 含义 |
+|---|---|---|
+| `task_started` | `session_id`, `task_id`, `tool_use_id?`, `description`, `task_type?`, `uuid` | 进程内已登记子任务；不等于业务绑定已持久保存 |
+| `task_progress` | 上述身份字段、`usage`, `last_tool_name?`, `summary?` | 可选进度，不是完成证明 |
+| `task_notification` | 身份字段、`status`, `output_file`, `summary`, `usage?` | 终态通知；`status` 为 `completed`、`failed` 或 `stopped` |
+
+保存业务执行尝试与实际 `session_id/tool_use_id/task_id` 的关联。内部取消状态
+`killed` 在此映射为 `stopped`。模型文本或工具正文中的同名 XML 不应当作宿主事件；
+即使任务 `completed`，仍需核对业务产物和实际交付回执。
+
+从 `1.5.0-alpha.6` 起，`TaskOutput` 抢先读取终态、抑制后续模型通知的路径也会
+补发结构化 SDK 终态；已经通知、重复读取或仍在运行时不新增该终态。这一修复
+不提供持久投递保证：事件队列、任务表主要在进程内，前台忙碌可能延后通知，
+退出后没有消费者确认游标或保证重放。应用应保存收到的事件并处理重复、缺失和冲突。
+
+当前没有按父会话和原 `tool_use_id` 查询历史运行的公开 SDK 接口。`TaskOutput`
+是已标记弃用的模型工具，只查询现有任务表；`stopTask(taskId)` 是当前进程内的
+取消控制，不是查询，也不能撤销副作用。`SubagentStart` 不提供原 Agent 调用 ID。
+已保存的父会话 Agent 工具结果可提供 `toolUseResult.agentId` 与
+`message.content[].tool_use_id` 的有限取证关联；记录缺失、日志截断或进程退出
+应保留为未知，不直接重派。`resume` 会继续执行，不能用作无副作用的状态查询。
+
+普通后台 agent 默认不能弹出权限 UI；规则和权限 hook 未放行、仍需要交互的操作
+通常返回工具拒绝。不能期待所有权限不足都表现为统一的任务 `waiting` 或 `failed`。
+显式允许提示的配置另按实际权限事件处理。普通 worker 也不获得嵌套 Agent 工具；
+独立 reviewer 应由主协调入口派发，保持前台与 worker Session 的分工。
+
 ### 恢复结果与用户介入
 
 `result.recovery` 是可选扩展，与过程诊断的 `diagnostic.recovery.phase` 不同：
@@ -216,6 +264,35 @@ query(...)
 
 ## 6. QueryOptions 字段表
 
+### 共用执行指引与宿主定制
+
+普通 CLI 和 SDK 默认系统指令共用运行层的工具执行指导：可用且适合时优先专用文件工具；脚本、构建、测试、转换及专用工具不提供的元数据查询使用 Bash。缺工具可采用已授权等价方案，权限拒绝不能成为换工具绕过限制的理由。这是 agent 指引，不是工具调用或模型遵循的强制保证。
+
+保留运行层默认指导并追加岗位或用户配置时，SDK 使用 `appendSystemPrompt`，CLI 使用 `--append-system-prompt` 或 `--append-system-prompt-file`。内容由宿主组合和维护，不改写用户 persona 文件，也不自动同步两个应用的配置。若 SDK 同时提供 `systemPrompt`，追加内容接在替换后的提示之后。仅在确实需要自管全部系统指令时使用 `systemPrompt` / `--system-prompt`；它们会替换默认系统指令，Bash 等工具的说明仍来自实际工具 schema。没有另一个命名 preset 注册或版本协商接口。
+
+需要保留自定义 `systemPrompt`、同时复用运行层执行指引时，可显式使用 `getExecutionGuidance(toolNames)`。**此导出从 `1.5.0-alpha.5` 提供**；内容随同一部署包版本更新，不另建 preset 版本号。SDK 和 CLI 应使用同一固定版本的包，旧安装包不一定具备此导出。
+
+```ts
+import { getExecutionGuidance, query } from '@margay/ccl-core/sdk'
+
+const toolNames = ['Read', 'Write', 'Edit', 'Glob', 'Grep', 'Bash']
+const execution = getExecutionGuidance(toolNames)
+const result = query(prompt, {
+  systemPrompt: personaText, // 原岗位身份，由应用保存；指引更新不改写它
+  appendSystemPrompt: [execution, userDefaults].filter(Boolean).join('\n\n'),
+  extraArgs: ['--tools', toolNames.join(',')],
+  canUseTool, // 沿用应用自身权限处理；生成指引不会授予工具权限
+})
+for await (const event of result) { /* 消费实际结果 */ }
+```
+
+`toolNames` 使用会话实际暴露的规范工具名，非显示别名或权限规则表达式；只有提供的内置文件工具/Bash 才生成对应分工说明，其它工具仍遵循通用的“按已有接口执行、必要时定向调查”规则。空列表只返回通用边界。工具集合变化时由应用重新生成；函数不探测文件、不加载技能、不注册工具、不修改配置、不自动注入会话。普通默认系统提示已经消费同一来源，无需再追加一次。
+
+直接 CLI 的自定义 persona 也可消费同一份文字：应用通过上述导出生成一个自己管理的文本文件，再使用 `--system-prompt-file <persona文件> --append-system-prompt-file <执行指引文件>`。不依赖复制某个内部提示文件，也不需要 persona 改成默认 coding 身份。显式完整替换且不追加时，仍保持既有替换契约。REPL/embedded 等特殊工具表面由调用方传入实际可直接使用的工具名，不能把本函数当作特殊模式的全部运行指令。
+
+宿主应固定部署包版本并检验实际模型输入，而非从工具已注册推断默认指导存在。升级依赖后还需重启实际运行的 CLI/SDK 进程。Desktop 的资源管理、配置保存和 UI 联验仍由宿主负责。
+
+
 | 字段 | 类型 | 默认 | 说明 |
 |---|---|---|---|
 | `cwd` | string | 继承宿主 | 会话工作目录 |
@@ -374,6 +451,16 @@ for await (const ev of query('用 load_csv 读 /data/x.csv 并报告行列', {
 - handler 在 **host 进程**执行(可访问 host 的文件/网络/状态)。
 - 每次调用先过 `canUseTool`(可 allow/deny/pending);deny → 工具不跑。
 
+工具发现元数据：`tool` 的第五个参数支持
+`{ searchHint?: string, alwaysLoad?: boolean, annotations?: Record<string, unknown> }`。
+`searchHint` 作为 `anthropic/searchHint` 传给工具搜索，补充名称和描述之外的搜索词；
+SDK 在 `tools/list` 中转发此字段。
+新增的 `alwaysLoad: true` 作为 `anthropic/alwaysLoad` 传给 CLI，让该工具完整 schema
+进入首请求，无须先由 ToolSearch 发现。省略或传 `false` 沿用 CLI 的工具发现策略，
+并非强制隐藏工具。这些选项不授予执行权限，也不保证模型选择该工具；
+`canUseTool` 的拒绝仍阻止 handler 执行。仅对确实需要首请求展示的工具显式启用，
+避免无条件扩大每次请求。
+
 ### 13.2 Token 级流式(G3)
 ```ts
 for await (const ev of query('写一段', { includePartialMessages: true })) {
@@ -527,3 +614,62 @@ For shared updates, retain immutable version directories and select a new root
 explicitly. Rediscover IDs after upgrading from random SDK wrapper names or after
 moving a skill root; transcript resume does not restore resource bindings.
 See [shared skill identity, reload and publisher responsibilities](../docs/shared-skill-resources.md).
+# Query loop observations
+
+`SDKEvent` includes `{ type: 'query_lifecycle', lifecycle, sessionId }`. The
+`lifecycle.record.phase === 'terminal'` observation closes one host query loop;
+it does not replace the outer `result` event or verify a business outcome. Native
+Stop hooks carry the same checkpoint identity in their optional `query` field.
+See [input and query correlation](../docs/hook-input-provenance.md) for fields,
+failure states and the distinction between accepted and adapter-dispatched inputs.
+
+`readQueryLifecycle({ transcriptPath, sessionId, queryId })` reads only the given
+file and returns `found` with `complete`/`incomplete`, `not_found`, or `unavailable`.
+Use the original query ID when processing late or replayed notifications. Missing
+records do not authorize re-execution of tools.
+
+Keep ownership of the public query handle and close it when post-result controls
+are no longer needed:
+
+```js
+const handle = query(prompt, options)
+try {
+  for await (const event of handle) {
+    if (event.type === 'query_lifecycle') recordObservation(event.lifecycle)
+    // Continue consuming the outer result; a Stop checkpoint is not terminal.
+  }
+} finally {
+  await handle.close()
+}
+```
+
+## Write without replacing an existing target (1.5.1-alpha candidate)
+
+The native `Write` schema accepts optional `mode: "overwrite" | "create_only"`.
+Omitting it keeps the existing read-before-overwrite behavior. For an export that
+must preserve every existing target, use:
+
+```json
+{"file_path":"/absolute/path/new-export.txt","content":"Export content\n","mode":"create_only"}
+```
+
+`create_only` refuses files (including previously read or empty files), directories,
+symbolic links and dangling links. Publication is exclusive even if another process
+creates the target after validation. On conflict, choose another authorized path;
+reading the old target or approval to write does not convert this into overwrite.
+The model receives the same schema through CLI/TUI and SDK. The headless workflow
+`tool("Write", input)` also honors the mode, with its existing permission policy.
+
+The implementation stages complete UTF-8 content beside the destination and links
+it into place without replacing a directory entry. Unsupported hard links fail
+without falling back to overwrite. A pre-publication write/flush/cancellation
+failure does not create the target; diagnostics report any temporary residue.
+After publication, cancellation and post-write cleanup/diagnostic failures do not
+undo the created file. The result reports its canonical path and any warnings.
+An interrupted consumer may receive no result; missing output is not proof that
+the file was never created. This is not a power-loss, network-filesystem or durable
+operation-replay guarantee, and does not introduce a new permission gate.
+
+Check the actual tool schema for `mode`; an older installation with the same
+candidate version string may not have it. An existence precheck followed by normal
+Write is not an equivalent no-replacement contract.

package/sdk/README.md

@@ -34,6 +34,12 @@ for await (const event of query('检查今天的收件箱并起草回复', {
 
 Resume an existing session: `query(prompt, { resume: sessionId })`.
 
+For work that must continue after the foreground closes, the **1.5.1-alpha interface** exports `createBackgroundClient`.
+See [durable background tasks](../docs/background-runs.md) for explicit submission,
+stable keys, paged event recovery, permissions and the worker/reviewer example.
+Its required `cwd` and `cliPath` options are separate from `query()`'s defaults;
+in-process callbacks and SDK MCP instances cannot be carried into a detached worker.
+
 Pending approval (7×24 resident CoS, owner approves via Feishu card):
 
 ```ts