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

package/dist/sdk/session.js

@@ -0,0 +1,167 @@
+import { randomUUID } from 'node:crypto';
+import { queryHandleWithTransport } from './queryHandle.js';
+import { spawnForOptions } from './query.js';
+/** One CLI process, sequential turns, and a bounded host-side input queue. */
+export class Session {
+    pid;
+    /** Existing SDK controls, including initialization, model and task controls. */
+    controls;
+    handle;
+    limit;
+    options;
+    queue = [];
+    active;
+    wake;
+    accepting = true;
+    closed = false;
+    drainWaiters = [];
+    pumping;
+    constructor(options = {}, transport) {
+        this.limit = options.maxPendingTurns ?? 32;
+        if (!Number.isSafeInteger(this.limit) || this.limit < 1) {
+            throw new RangeError('ccl-sdk: maxPendingTurns must be a positive integer');
+        }
+        if (options.pendingDecision)
+            throw new Error('ccl-sdk: resume a pending decision before creating a Session');
+        this.options = options;
+        const owned = transport ?? spawnForOptions(options);
+        this.pid = owned.pid;
+        this.handle = queryHandleWithTransport(this.inputs(), options, owned);
+        this.controls = this.handle;
+        this.pumping = this.consume();
+    }
+    prompt(content) {
+        return this.enqueue(content, false);
+    }
+    followUp(content) {
+        return this.enqueue(content, false);
+    }
+    /** Interrupt the active turn; correction runs before queued follow-ups. */
+    steer(content) {
+        const turn = this.enqueue(content, true);
+        if (this.active)
+            void this.interrupt().catch(error => this.fail(error));
+        return turn;
+    }
+    enqueue(content, priority) {
+        if (!this.accepting || this.closed)
+            throw new Error('ccl-sdk: session input is closed');
+        if (this.queue.length + (this.active ? 1 : 0) >= this.limit) {
+            throw new Error(`ccl-sdk: session queue is full (${this.limit} pending turns)`);
+        }
+        const id = randomUUID();
+        let resolve;
+        let reject;
+        const result = new Promise((yes, no) => { resolve = yes; reject = no; });
+        // It is valid to enqueue follow-ups and observe their results later.
+        void result.catch(() => { });
+        const turn = { id, result, cancel: () => this.cancel(id) };
+        const entry = { turn, resolve, reject, input: {
+                type: 'user', uuid: id, message: { role: 'user', content },
+            } };
+        if (priority)
+            this.queue.unshift(entry);
+        else
+            this.queue.push(entry);
+        this.wake?.();
+        return turn;
+    }
+    async *inputs() {
+        while (!this.closed) {
+            if (this.active) {
+                await new Promise(resolve => { this.wake = resolve; });
+                this.wake = undefined;
+                continue;
+            }
+            const entry = this.queue.shift();
+            if (entry) {
+                this.active = entry;
+                yield entry.input;
+            }
+            else {
+                await new Promise(resolve => { this.wake = resolve; });
+                this.wake = undefined;
+            }
+        }
+    }
+    async consume() {
+        try {
+            for await (const event of this.handle) {
+                const correlated = { ...event, turnId: event.turnId ?? this.active?.turn.id };
+                // Observability callbacks must not terminate the agent or strand work.
+                try {
+                    this.options.onEvent?.(correlated);
+                }
+                catch { /* host observer */ }
+                if (event.type === 'result' && this.active) {
+                    if (event.turnId !== this.active.turn.id)
+                        throw new Error('ccl-sdk: mismatched turn result');
+                    this.active.resolve(event);
+                    this.active = undefined;
+                    this.wake?.();
+                    this.notifyDrained();
+                }
+                else if (event.type === 'error' && event.fatal) {
+                    throw new Error(event.message);
+                }
+                else if (event.type === 'suspended') {
+                    throw new Error(`ccl-sdk: session suspended; resumeWithDecision(${event.sessionId}) is required`);
+                }
+            }
+            if (!this.closed)
+                this.fail(new Error('ccl-sdk: session transport ended'));
+        }
+        catch (error) {
+            this.fail(error);
+        }
+        finally {
+            await this.controls.close();
+        }
+    }
+    fail(reason) {
+        const error = reason instanceof Error ? reason : new Error(String(reason));
+        this.closed = true;
+        this.accepting = false;
+        this.active?.reject(error);
+        this.active = undefined;
+        for (const entry of this.queue.splice(0))
+            entry.reject(error);
+        this.wake?.();
+        this.notifyDrained();
+        void this.controls.close().catch(() => { });
+    }
+    notifyDrained() {
+        if (this.active || this.queue.length)
+            return;
+        for (const resolve of this.drainWaiters.splice(0))
+            resolve();
+    }
+    async interrupt() {
+        if (this.active)
+            await this.controls.interrupt();
+    }
+    async cancel(id) {
+        if (this.active?.turn.id === id)
+            return this.interrupt();
+        const index = this.queue.findIndex(entry => entry.turn.id === id);
+        if (index < 0)
+            return;
+        this.queue.splice(index, 1)[0].reject(new Error('ccl-sdk: queued turn cancelled'));
+        this.notifyDrained();
+    }
+    /** Stop accepting inputs and drain accepted turns, keeping controls alive. */
+    async endInput() {
+        this.accepting = false;
+        if (!this.active && !this.queue.length)
+            return;
+        await new Promise(resolve => this.drainWaiters.push(resolve));
+    }
+    async close() {
+        this.fail(new Error('ccl-sdk: session closed'));
+        await this.controls.close();
+        await this.pumping;
+    }
+}
+export function createSession(options = {}) {
+    return new Session(options);
+}

package/dist/sdk/types.d.ts

@@ -142,6 +142,8 @@ export type QueryOptions = {
      * suggestions; it is neither a result nor an instruction for the host to retry.
      */
     includeErrorDiagnostics?: boolean;
+    /** Opt-in finite, nonterminal gateway status events. Defaults to false. */
+    includeRequestProgress?: boolean;
     /**
      * slice sdk-json-schema-output (G4): a JSON Schema for structured output. When set, the CLI
      * validates the final result against it (retrying the model) and returns `structuredOutput` on
@@ -297,10 +299,30 @@ export type Usage = {
  * minimal set from the issue (P0-1) plus `permission_resolved` (audit trail)
  * and optional `raw` passthrough.
  */
-export type SDKEvent = {
+export type SDKUserMessage = {
+    type: 'user';
+    message: {
+        role: 'user';
+        content: string | Array<{
+            type: string;
+            [key: string]: unknown;
+        }>;
+    };
+    uuid?: string;
+    parent_tool_use_id?: null;
+    session_id?: string;
+};
+export type SDKEvent = SDKEventPayload & {
+    turnId?: string;
+};
+type SDKEventPayload = {
     type: 'assistant_text';
     text: string;
     sessionId?: string;
+} | {
+    type: 'request_progress';
+    progress: import('./requestProgress.js').GatewayRequestProgress;
+    sessionId?: string;
 } | {
     type: 'error_diagnostic';
     diagnostic: import('./errorDiagnostics.js').RecoveryDiagnostic;
@@ -452,3 +474,4 @@ export type Transport = {
      * rewritten). Absent for in-memory test transports. */
     pid?: number;
 };
+export {};

package/docs/ccl-duo-agent.md

@@ -100,6 +100,8 @@ Duo 让一个 Agent 执行任务，另一个独立检查结果。双方各有上
 
 本地修复候选在模型查询失败终止后将对应 Duo 任务置为暂停，保留材料和审查记录。先检查错误、凭据或模型可用性，再使用 `/duo resume`；失败不会被标为审核完成。
 
+2026-10-15 本地候选修复了超时后“显示已恢复、任务仍停在暂停阶段”的问题。恢复时根据当前要求、材料和有效审核记录重新确定工作阶段，再允许双方继续；暂停期间改过要求时，旧 PASS 不能恢复为可接受状态。此修复尚未发布。
+
 Duo 退出和任务完成不是一回事。任务被接受后 Duo 回到待命，可直接输入下一项任务；即使旧材料后来变化，仍可接新任务或使用 `/duo exit`。清理失败会显示原因，但不能锁住输入。普通 `/exit` 退出 CCL 会话。
 
 ### 必要时由用户裁决

package/docs/cli-installation.md

@@ -0,0 +1,86 @@
+# CLI installation and upgrades
+
+For `1.4.5-rc.10`, use Node.js `>=22.19.0`. This matches the declared minimum of
+the pinned `undici 8.0.2` runtime dependency; the earlier Node 20 declaration no
+longer applies. macOS Node/Bun verification does not imply Windows verification.
+
+Starting with `1.4.5-rc.10`, CCL declares `ccl` and `margay` as names for the same
+`dist/cli.js`. Both names must report the package version and provide the same
+options. The `1.4.5-rc.9` package declares only
+`margay`. Installing that existing version will not add `ccl`.
+
+## Global and project installs
+
+For a terminal command available outside a project, install the desired released
+version globally:
+
+```sh
+npm install --global @margay/ccl-core@latest
+margay --version
+```
+
+After installing a release with both entries, also run `ccl --version`. Both
+outputs must match the installed package's version. Global installation does not
+replace a CLI embedded in Margay Desktop or already loaded by a running process.
+
+Without `--global`, npm installs a project dependency. Run that copy explicitly:
+
+```sh
+npm install @margay/ccl-core@latest
+./node_modules/.bin/margay --version
+```
+
+Releases with both entries also provide `./node_modules/.bin/ccl`. A successful
+project install does not upgrade commands elsewhere on the shell's PATH.
+
+## Migrating old custom launchers (macOS/Linux)
+
+Some earlier local deployments created shell scripts that pin a release path.
+These are separate from npm-managed links. Inspect resolution before and after
+upgrading:
+
+```sh
+type -a ccl margay
+npm prefix --global
+npm ls --global @margay/ccl-core --depth=0
+```
+
+There are two distinct cases:
+
+- **npm reports `EEXIST`:** an unmanaged launcher occupies the intended npm bin
+  path. Inspect the named file and confirm it belongs to the old CCL deployment.
+  Move that specific file to an unused backup path, then repeat the installation.
+  Preserve unrelated executables; a blanket `--force` is not a migration plan.
+- **Installation succeeds, but the command reports an old version:** an alias,
+  shell function or an earlier PATH directory is taking precedence. Inspect the
+  resolved entry. Back up the specific obsolete CCL wrapper, or update an explicit
+  alias/function to use the npm entry. Ensure the npm prefix's `bin` directory is
+  on PATH. Refresh the shell command cache (`rehash` in zsh, `hash -r` in bash),
+  then verify both commands again from outside the source checkout.
+
+Keep each backup until the new commands work. To roll back a custom wrapper,
+restore its saved bytes at the original path after inspecting what currently
+occupies that path. For an npm-managed installation, install the previous exact
+version. Future npm upgrades manage both links once the custom wrappers have
+been migrated.
+
+## Checking a release tarball
+
+From a built checkout, pack the release and test its actual npm installation:
+
+```sh
+npm pack --ignore-scripts --pack-destination /path/to/artifacts
+node tests/package-cli-install.mjs /path/to/artifacts/candidate.tgz /path/to/previous.tgz
+```
+
+The smoke test uses isolated install prefixes, HOME/configuration and cache. It
+checks fresh global and project installs, upgrade from the previous tarball,
+both commands through PATH, matching executable/version/help, an unmanaged-file
+collision, backup migration and PATH shadowing. Dependency lifecycle scripts are
+disabled; this verifies CLI installation and startup, not native dependency or
+model behavior. It currently runs on POSIX; Windows `.cmd`/PowerShell launchers
+require a Windows run. It cleans its temporary installations even on failure.
+
+Use the final tarball as the test input. A metadata edit after publishing rc.9
+does not change rc.9 on npm; allocate a new version, rebuild, pack and verify
+before publishing the corrected release.

package/docs/context-checkpoints-and-daemon.md

@@ -0,0 +1,54 @@
+# Completed-step checkpoints and background scheduling
+
+For a long task, `ContextCheckpoint` can save selected completed tool results with
+a summary and artifact references. Subsequent requests carry that summary and
+retrieval references. Full original outputs, including image blocks, remain in
+the session's transcript-adjacent `.checkpoints` directory with SHA-256 integrity
+checks. `list` locates saved records; `restore` makes the original evidence
+available again, including after transcript compaction or resume.
+
+At a completed phase, omit `tool_use_ids` to save all eligible completed results.
+For a subset, `list` returns available result IDs with their tool names and inputs.
+Use the `checkpoint_id` returned by `save` or `list` when restoring; invented
+protocol IDs are rejected.
+
+The model chooses completed work; the tool rejects missing results, unresolved
+permission interactions, errors, background launches, and duplicate archives.
+User messages, corrections and user-supplied images are never projected away.
+Checkpoint storage failures leave the incoming context intact. This path uses the
+existing full compaction and result-budget machinery; it does not enable the
+unimplemented provider cache-editing features. Checkpointing can change cache
+reuse and adds tool calls, so savings depend on the actual task and provider.
+
+`ccl daemon start --cwd /path/to/project` starts a detached local owner for the
+project's existing `.ccl/scheduled_tasks.json`. The launching CLI may exit; the
+owner remains. `ccl daemon run` is the foreground equivalent for an external
+service manager. This command does not install a login or reboot service.
+
+The owner uses the existing cron scheduler and project lock. It records an
+occurrence before acknowledging it, then records execution and local delivery
+separately under `.ccl/daemon/`. `status` shows these records. Completed output is
+saved in `results/`; tool/events evidence is retained in `events/`. There is no
+automatic email, chat or other external delivery.
+
+```sh
+ccl daemon status --cwd /path/to/project
+ccl daemon cancel OCCURRENCE_ID --cwd /path/to/project
+ccl daemon approve OCCURRENCE_ID allow --cwd /path/to/project
+ccl daemon approve OCCURRENCE_ID deny --cwd /path/to/project
+ccl daemon run-missed OCCURRENCE_ID --cwd /path/to/project
+ccl daemon deliver OCCURRENCE_ID --cwd /path/to/project
+ccl daemon stop --cwd /path/to/project
+```
+
+The CLI's existing permission rules apply. An unresolved permission suspends
+execution until an explicit `approve` decision. Missed one-shot tasks are retained
+as `missed` and need `run-missed`; recurring timing follows the shared scheduler.
+On restart, accepted but not started work can continue. Work interrupted after
+execution began is recorded as `interrupted` and never automatically replayed:
+inspect its events and external effects before scheduling new work. `deliver`
+retries saving an already successful result, without rerunning its tools.
+
+`cancel` stops an occurrence; delete the durable cron definition as well when
+future recurring occurrences should cease. A permission wait and an interrupted
+run remain visible across restarts. Stop does not erase schedules or evidence.

package/docs/gateway-quickstart.md

@@ -190,8 +190,60 @@ by endpoint switching.
 Output/context limits do not mean the account is out of credit. See the
 [recovery guide](./error-recovery-usage.md) for consent and external-blocker UX.
 
+## Request Deadlines And Slow Waits
+
+The source candidate adds connection and response deadlines while preserving
+the existing total request setup budget. These values are milliseconds:
+
+| Variable | Default | Applies until |
+| --- | --- | --- |
+| `CCL_GATEWAY_REQUEST_TIMEOUT_MS` | `300000` | A response stream is established, including retry delays |
+| `CCL_GATEWAY_CONNECT_TIMEOUT_MS` | Total setup budget | A pooled/new connection can send the request |
+| `CCL_GATEWAY_RESPONSE_TIMEOUT_MS` | Total setup budget | Response headers arrive after sending |
+| `CCL_GATEWAY_SLOW_WAIT_MS` | `30000` | A single slow-status notice becomes eligible |
+
+Values must be whole numbers from 1 to 3600000. Invalid values fall back to the
+default and produce a one-time stderr notice. A phase deadline cannot extend
+the remaining total budget, and retries do not receive a new total budget.
+Defaults therefore do not shorten the existing five-minute setup allowance.
+
+For example, allow up to 30 seconds to connect and 180 seconds for headers:
+
+```sh
+CCL_GATEWAY_CONNECT_TIMEOUT_MS=30000 CCL_GATEWAY_RESPONSE_TIMEOUT_MS=180000 margay
+```
+
+After streaming starts, the separate model-progress idle watchdog applies;
+the setup deadline does not impose a maximum duration on healthy output.
+The TUI shows the current request phase and a slow-wait notice. Escape cancels
+through the existing task cancellation path. Status notices do not reset the
+model-progress watchdog or become assistant text.
+
+A local timeout reports `gateway_request_timeout` with the observed phase.
+It cannot establish whether the remote request completed. Check task state
+before repeating work that may have side effects. SDK hosts can opt into
+[structured request status](../sdk/README.md#gateway-request-status-source-candidate).
+
 ## Troubleshooting
 
+In the source candidate, headless runs with `CI=1` can authenticate using an
+admitted gateway configuration alone. A separate Anthropic API key is not
+required for that route. Missing or rejected gateway credentials still require
+a valid login or another supported credential source. This fixes a startup
+failure present in rc.9; it does not change the gateway's 401 handling.
+
+The source candidate also reports a failed in-process teammate request to its
+team leader with the visible failure reason. The teammate remains available for
+explicit new work after the failure; a timeout does not automatically retry the
+task or mark it complete. Check any uncertain side effects before resuming.
+
+In the source candidate, headless background completions belong to the input
+that launched them. They share that input's `--max-turns` ceiling and cannot
+restart it after an error or interrupt. Successful background work is collected
+before its final result. A new SDK input can start fresh work; late notifications
+from the previous input do not start model calls for it. Closing an SDK query
+also waits for background shell termination during the CLI's bounded shutdown.
+
 | Symptom | Action |
 | --- | --- |
 | Website offers no login entry | Confirm that login is enabled for that website/environment; a 200 page alone does not prove it is enabled. Cancel the CLI wait if disabled |

package/docs/releases/1.4.5-rc.10.md

@@ -0,0 +1,50 @@
+# 1.4.5-rc.10
+
+本版本包含双命令入口和 Mac Phase B 稳定性修复。包同时注册 `ccl` 和
+`margay`，两个命令指向同一份运行程序，功能、参数和版本相同。
+CLI 与 SDK 随同一个 `@margay/ccl-core` 包交付。
+
+## 相对 rc.9 的更新
+
+- 网关请求区分连接、等待响应和流式读取阶段，阶段期限共用请求总期限。
+  CLI/SDK 可选择接收等待进度；通知异常不阻塞请求，不混入模型上下文。
+- 无头执行的一次输入只返回一个终态。任务失败后，旧后台通知不会重新唤起模型、
+  执行工具或重复返回结果；取消及 SDK 关闭会清理所属后台任务。
+- 自动继续与压缩累计使用剩余任务预算，避免重置额度后不断运行。
+- 修复 CI 网关凭据识别、Duo 超时后的恢复，以及进程内/独立进程 Swarm 的失败通知。
+- 保留 rc.9 的输出预算、慢请求等待和有界断流恢复；已完成工具结果继续保留。
+- 将外部运行依赖 `undici` 固定为本候选验证过的 `8.0.2`，避免全新 npm 安装
+  自动选择不同版本。Node 声明要求调整为 `>=22.19.0`，与该依赖声明一致；
+  原先的 Node 20 支持声明不再适用。
+
+## 安装与升级
+
+全局安装后核对两个入口：
+
+```sh
+npm install --global @margay/ccl-core@1.4.5-rc.10
+ccl --version
+margay --version
+```
+
+两者应输出 `1.4.5-rc.10 (Margay)`。不带 `--global` 的安装只更新项目依赖，
+可通过 `./node_modules/.bin/ccl` 或 `./node_modules/.bin/margay` 使用。
+
+旧的自定义启动脚本、alias 或 PATH 排序可能继续选择旧版本。若安装报告
+`EEXIST` 或运行版本不一致，按[安装与升级说明](../cli-installation.md)检查并
+备份迁移对应入口。npm 全局安装不会替换 Margay Desktop 内嵌的运行包。
+
+## 验证与已知边界
+
+Phase B 候选已在 Mac 验证 Node/Bun 下 CLI、SDK 的成功、超时、取消和后续输入，
+以及 TUI、Duo、Swarm 和 Margay.app 私有副本的消费链路。CLI 构建 SHA256：
+`92a070720228fe35b80608e751fb59ea0116ac7c9e9115c009da98e1063a39df`。
+包的安装检查另外验证 POSIX 全新全局/项目安装、rc.9 升级、双入口、旧脚本冲突和 PATH 遮挡。
+
+- 本版不包含“轮次耗尽返回退出码 2，由上层自动续接”的新方案；到上限仍报告
+  `error_max_turns`。真实视频验证的首个 48 轮调用失败，另一次明确输入才完成交付。
+- DeepSeek thinking 400 的根因及针对性修复尚未收口；不能承诺本版消除该错误，
+  也不能仅凭 `blocked_external` 认定连接/超时问题已修复。
+- Windows 实机未验证；全仓 typecheck 的 11 条既有诊断未解决。
+- 获批 reactive compact 与 taskBudget 组合在当前公开入口不可达，仅作源码核对。
+  运营接口 401 及 shell 失败文案与 `is_error:false` 不一致的线索仍待定位。

package/docs/releases/1.4.6-beta.0.md

@@ -0,0 +1,54 @@
+# 1.4.6-beta.0
+
+本版将已在本机完成验证和独立审核的修复发布到 npm。基线为
+`1.4.5-rc.10`，实现与本地候选 `1.4.5-rc.10.local-issues-38-42.1`
+一致；本次只调整发布版本、重新构建并补充版本说明。
+
+## 相对 npm rc.10 的变化
+
+- #22：失败的 Bash 命令保留 stdout/stderr，较长的错误输出明确标记截断。
+- #35：显式 thinking 设置通过 CLI、SDK 正确传给兼容 Messages 网关；
+  原生模型继续遵循各自能力适配。
+- #36：bare 模式显式请求 Write 等不可用工具时，在请求模型前明确报错，
+  避免静默过滤。bare 默认仍为 Bash、Read、Edit。
+- #38：SDK 支持异步输入序列，逐轮返回结果，正确处理输入结束、取消和关闭。
+- #39：中文等不依赖空格分词的请求可以进入已有相关记忆选择流程。
+- #40：新增 SDK Session/Turn 接口，支持常驻进程、排队输入、优先纠正和逐轮取消。
+- #41：新增 ContextCheckpoint，支持保存、压缩请求中的历史工具结果及恢复原证据。
+- #42：新增独立 daemon 执行持久任务，记录执行与本地结果交付，避免交付重试重复执行。
+- GLM 服务端工具历史切换到其他模型时，转换已完成且配对明确的扩展结果；
+  保留原始会话记录和普通客户端工具调用。
+- 保留已验证的流式工具调用、压缩恢复和会话并发写入修复，以及 rc.10 的
+  请求期限、取消、后台任务清理和唯一终态处理。
+
+## 安装与兼容
+
+```sh
+npm install --global @margay/ccl-core@1.4.6-beta.0
+ccl --version
+margay --version
+```
+
+Node 要求仍为 `>=22.19.0`。CLI 和 SDK 随同一个包发布。
+全局升级不会替换 Margay Desktop 内置的运行包；桌面端需单独更新其依赖和构建。
+本版不自动安装系统启动服务、不自动重启已有会话，也不迁移用户数据。
+
+目标 npm 标签：`latest` 指向本版，`next` 与 `stable` 指向 `1.4.5-rc.10`。
+`rc` 标签保持原值。
+
+## 验证与仍需处理的问题
+
+核心实现的独立审核和执行证据见仓库中的
+`docs/issues-22-35-36-fix-2026-10-18.md` 与
+`docs/issues-38-42-fix-2026-10-19.md`。本次发布的构建、安装及协议验证记录
+保存在 `.rll/records/release-1.4.6-beta.0/`，发布包与验证包使用同一份 tarball。
+
+- 此版仍有 AI 指令审核发现的定时语义问题：相对时间、精确时刻和未来开始可能
+  生成不符合要求的计划；“关闭终端继续运行”也可能只保存任务而未启动 daemon。
+- HTTP 400/401 的部分具体原因展示和父子任务重复错误恢复用例仍有既有失败。
+- 任务达到配置的轮次上限仍会失败，不保证自动续接；提高输出预算不突破模型或网关上限。
+- 检查点验证证明保存/恢复可用，不代表性能或 token 成本改善。
+- 全仓类型检查存在 11 条已记录的基线错误；Windows 实机未验证。
+
+需要回退时可安装 `@margay/ccl-core@1.4.5-rc.10`。回退不会撤销已经执行的任务或文件写入；
+依赖本版新 SDK 接口的宿主应同步回退其调用代码。

package/package.json

@@ -1,16 +1,18 @@
 {
   "name": "@margay/ccl-core",
-  "version": "1.4.5-rc.9",
+  "version": "1.4.6-beta.0",
   "description": "Core runtime extracted from Claude Code (ccl) for Margay integration",
   "license": "SEE LICENSE IN README.md",
   "type": "module",
   "bin": {
+    "ccl": "dist/cli.js",
     "margay": "dist/cli.js"
   },
   "files": [
     "dist",
     "README.md",
     "QUICKSTART.md",
+    "docs/cli-installation.md",
     "INTENT-GATEWAY-GUIDE.md",
     "docs/index.md",
     "docs/error-recovery-usage.md",
@@ -37,10 +39,13 @@
     "docs/features/business-facts.md",
     "docs/releases/1.4.5-rc.8.md",
     "docs/features/copy-on-select.md",
-    "docs/releases/1.4.5-rc.9.md"
+    "docs/releases/1.4.5-rc.9.md",
+    "docs/releases/1.4.5-rc.10.md",
+    "docs/context-checkpoints-and-daemon.md",
+    "docs/releases/1.4.6-beta.0.md"
   ],
   "engines": {
-    "node": ">=20.0.0"
+    "node": ">=22.19.0"
   },
   "scripts": {
     "typecheck": "tsc --noEmit",
@@ -128,7 +133,7 @@
     "tree-kill": "^1.2.2",
     "turndown": "^7.2.4",
     "type-fest": "^5.5.0",
-    "undici": "^8.0.2",
+    "undici": "8.0.2",
     "usehooks-ts": "^3.1.1",
     "vscode-jsonrpc": "^8.2.1",
     "vscode-languageserver-protocol": "^3.17.5",

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.