@margay/ccl-core 1.4.5-rc.8 → 1.4.6-beta.0

package/sdk/API.md

@@ -17,7 +17,7 @@ import {
 } from '@margay/ccl-core/sdk'
 ```
 
-- **运行时**:Node ≥ 20(ESM)。SDK 本体零第三方依赖,只用 Node 内置模块。
+- **运行时**:Node ≥ 22.19.0（ESM），依赖随 `@margay/ccl-core` 安装。
 - **CLI 定位**:SDK 以受管子进程方式运行 CCL CLI(全管道 stdio,无 TTY)。CLI 路径解析顺序:
   1. `options.cliPath`
   2. 环境变量 `CCL_SDK_CLI_PATH`
@@ -29,10 +29,16 @@ import {
 
 ## 2. 核心入口
 
-### 2.1 `query(prompt, options?) → AsyncGenerator<SDKEvent>`
+### 2.1 `query({ prompt, options? }) → Query`
 
 发起一轮对话(一次 agentic 任务),异步迭代产出事件,直到终态事件(`result` / `suspended` / fatal `error`)后结束。
 
+上面的单轮语义适用于字符串输入；旧的双参数形式仍兼容。`prompt` 也可传
+`AsyncIterable<SDKUserMessage>`：每条输入完成后再消费下一条，`result.turnId`
+关联输入的 `uuid`（未提供时自动生成）。输入结束、生成器错误、abort 或 close
+都会回收流式 query 的 CLI 进程。必须持续消费事件；流式输出积压超过 1024 项
+会明确报错并关闭，避免无限占用内存。
+
 ```ts
 for await (const event of query('检查收件箱并起草回复', {
   cwd: '/srv/cos-workspace',
@@ -73,6 +79,20 @@ for await (const event of resumeWithDecision(sessionId, { behavior: 'allow' }))
 
 `query(newPrompt, { resume: sessionId })` —— 在已有会话上继续新一轮对话(非审批场景的普通 resume)。
 
+### 2.5 `createSession(options?) → Session`
+
+在同一个 CLI 进程中连续交互。`prompt(content)`、`followUp(content)` 返回
+`Turn { id, result, cancel() }`，按顺序执行；`steer(content)` 中断当前轮，将纠偏
+放到等待队列前面。已产生的工具副作用不会回滚。
+
+`maxPendingTurns` 默认 32，包含正在执行的轮次，队满时同步拒绝新输入。
+`onEvent(event)` 接收即时事件，Session 不保存事件历史。`controls` 提供原有
+Query 控制方法，`pid` 用于宿主监控。
+
+`endInput()` 停止接受新输入并等待已接受轮次，但保留进程和控制通道；`close()`
+终止进程并拒绝未完成轮次。权限回调可等待宿主决定，interrupt/close 会取消
+等待；返回 `pending` 仍表示持久挂起，后续用 `resumeWithDecision` 恢复。
+
 ---
 
 ## 3. 事件参考(SDKEvent)
@@ -92,7 +112,9 @@ for await (const event of resumeWithDecision(sessionId, { behavior: 'allow' }))
 | `error_diagnostic` | `diagnostic: RecoveryDiagnostic`, `sessionId?` | 可选过程事件，仅 `includeErrorDiagnostics:true` 时输出；不是终态 |
 | `raw` | `message` | 透传子进程原始消息(仅 `includeRaw:true` 时产出,调试用) |
 
-**终态约定**:每次迭代**恰好一个**终态——`result`、`suspended`、或 fatal `error`。宿主状态机据此收敛。
+**终态约定**：字符串 query 的 `result` 结束该次输入。流式 query / Session 的
+`result` 只结束对应 `turnId`，后续仍可能有输入。`suspended`、fatal `error`、
+关闭或输入 EOF 结束流式 query；不要把首个 result 当作常驻 Session 已关闭。
 
 ### 恢复结果与用户介入
 
@@ -390,3 +412,13 @@ query('用 filesystem server 列目录', {
 
 新增事件:`{ type:'stream_event', event, sessionId? }`;result 事件新增 `structuredOutput?`。
 新增 hooks:`onSessionStart` / `onUserPromptSubmit`;`onTurnEnd` 事件新增 `usage?`。
+
+
+### Optional gateway request progress (source candidate)
+
+`QueryOptions.includeRequestProgress?: boolean` defaults to false. When enabled,
+`SDKEvent` additionally includes `{ type: 'request_progress', progress }`, where
+`progress` is the exported `GatewayRequestProgress` type. See the
+[request status guide](./README.md#gateway-request-status-source-candidate) for
+phases, bounded delivery and host lifecycle rules. This nonterminal event must
+not be used as an assistant message, a successful result, or a retry instruction.

package/sdk/README.md

@@ -66,6 +66,43 @@ process events. Those events do not replace or add a terminal result.
 See the [API contract](./API.md) and [recovery guide](../docs/error-recovery-usage.md)
 for consent, external blockers, and continuation rules.
 
+## Gateway request status (source candidate)
+
+Set `includeRequestProgress: true` to receive nonterminal `request_progress`
+events. This is off by default, independent of raw/partial/error diagnostic
+options. It does not change `result`, cancellation, or `onSessionEnd`.
+
+```ts
+for await (const event of query('Summarize this project.', {
+  includeRequestProgress: true,
+})) {
+  if (event.type === 'request_progress') {
+    const { requestId, phase, attempt, elapsedMs, idleMs, slow } = event.progress
+    // Update a transient status indicator, keyed by requestId.
+  }
+  if (event.type === 'result') {
+    // End the turn using the existing success/error contract.
+  }
+}
+```
+
+Phases are `preparing`, `connecting`, `sending`, `waiting_response`,
+`response_headers`, `retry_wait`, `streaming`, and `finished`. `connecting`
+includes pool waiting, DNS, TCP, TLS and proxy negotiation; it does not identify
+which of those substeps is slow. `idleMs` measures time without effective model
+progress. Events contain no prompt, headers, credentials or endpoint URL.
+
+Events are finite (at most 32 per model request), not periodic heartbeats.
+A slow notice never counts as model progress or grants permission to retry.
+`finished` ends a request, not necessarily the turn; clear status on the existing
+result/abort/disconnect path as well. Hosts should keep their own deadlines
+and avoid replaying tools when the remote completion state is unknown.
+
+CLI users can opt in with `--print --output-format stream-json
+--include-request-progress`; each wire event is `system/request_progress`.
+The flag is invalid with text or JSON output. See
+[request deadlines](../docs/gateway-quickstart.md#request-deadlines-and-slow-waits).
+
 ## Architecture
 
 The SDK is the **host side** of the stream-json control protocol that
@@ -146,3 +183,60 @@ provider mapping, skills-dir wrapping, hooks, usage accumulation, file-store
 round-trip. The issue's live end-to-end DoD slice (real model + mock outbound
 endpoint + real process exit) is CoS-side per the issue's division of labor —
 the SDK-side seams it needs are all covered above.
+# Minimal mode and explicit tools
+
+When passing `--bare` through `extraArgs`, the built-in tool set is Bash, Read,
+and Edit (REPL/coordinator modes have their own subset). `--tools default` uses
+that mode's available set; an explicit incompatible selection such as
+`--bare --tools Write` fails with a diagnostic before a model request. Remove
+`--bare` and unset `CLAUDE_CODE_SIMPLE` to request Write. Allow/deny permissions
+still apply; `--allowedTools` does not add tools to the available set.
+
+Use `extraArgs: ['--thinking', 'disabled']` to explicitly disable thinking on
+Anthropic Messages compatible routes. Omitting the option retains the route's
+default. The selection persists across requests; a query handle's
+`setMaxThinkingTokens(0)` explicitly disables it, and `null` restores the default.
+# Persistent sessions and streamed input
+
+`query({ prompt: asyncIterable, options })` accepts `SDKUserMessage` values. It
+submits one message at a time, waits for its result before pulling the next,
+and adds the input UUID as `result.turnId` (generating a UUID if omitted).
+Input EOF closes a streamed query. Invalid messages or producer failures reject
+the event iterator. Consume events as they arrive: an unread streamed query fails
+explicitly at 1024 buffered events instead of retaining unlimited output.
+
+Use `createSession` when the host owns a longer conversation:
+
+```ts
+import { createSession } from '@margay/ccl-core/sdk'
+
+const session = createSession({ cwd: projectDir, maxPendingTurns: 32 })
+try {
+  const first = session.prompt('Inspect the project and describe the failing test.')
+  console.log(await first.result)
+  const next = session.followUp('Fix that failure and run the relevant test.')
+  console.log(await next.result)
+  await session.endInput()
+  // The same child and controls remain alive until close().
+  console.log(session.pid, await session.controls.initializationResult())
+} finally {
+  await session.close()
+}
+```
+
+`prompt` and `followUp` enqueue FIFO; exceeding `maxPendingTurns` throws before
+acceptance. Each `Turn` has a stable `id`, a `result` promise and `cancel()`.
+Cancelling a queued turn rejects its promise. Cancelling an active turn interrupts
+the CLI and returns its interrupted result; already executed tool effects remain.
+`steer(text)` interrupts the active turn and puts the correction ahead of waiting
+follow-ups. It does not undo earlier effects. `endInput()` rejects new inputs and
+waits for accepted turns while preserving controls; `close()` terminates the child
+and rejects unfinished turns. `onEvent` observes events without retaining history.
+
+Permission callbacks can wait for a host decision while the process stays alive.
+Interrupt and close cancel that wait. Returning `{ behavior: 'pending' }` retains
+the existing durable suspend contract: it ends this process and requires
+`resumeWithDecision(sessionId, decision)`; it does not imply automatic approval.
+Uncooperative application iterators/callbacks cannot be forcibly stopped, but do
+not prevent CLI cleanup. One-shot string queries and post-result `rewindFiles`
+retain their existing behavior.