@margay/ccl-core 1.5.1-alpha.6 → 1.5.1-alpha.7

package/dist/sdk/background.d.ts

@@ -13,6 +13,19 @@ export type BackgroundClientOptions = {
     env?: NodeJS.ProcessEnv;
     timeoutMs?: number;
 };
+export type DaemonEnsureResult = {
+    action: 'reused' | 'started';
+    project: string;
+    owner: {
+        ready: true;
+        pid: number;
+        configId: string;
+    };
+    recovery: {
+        status: 'available' | 'unavailable';
+        reason?: string;
+    };
+};
 export declare class BackgroundClientError extends Error {
     readonly code: string;
     constructor(code: string, message: string);
@@ -20,6 +33,7 @@ export declare class BackgroundClientError extends Error {
 /** Durable runs do not retain JS callbacks or in-process SDK MCP servers. Use
  * persistent stdio/HTTP tools configured through launch instead. */
 export declare function createBackgroundClient(options: BackgroundClientOptions): {
+    ensureDaemon: () => Promise<DaemonEnsureResult>;
     getScheduledNotificationBinding: (selector: ScheduledNotificationSelector) => Promise<ScheduledNotificationBindingLookup>;
     rebindScheduledNotifications: (request: ScheduledNotificationRebind) => Promise<{
         selector: {

package/dist/sdk/background.js

@@ -18,7 +18,7 @@ export function createBackgroundClient(options) {
         // Serialization can throw (for example for a cyclic input); do it before
         // allocating a subprocess that would otherwise wait forever for stdin.
         const input = JSON.stringify(request);
-        const retryAdvice = command.includes('notification') ? 'Read the original notification binding. Retry a binding mutation only with the same actionId and payload.' : command.includes('occurrence') ? 'Read the original occurrence and approvalDecisions. Retry approval only with the same actionId and payload.' : 'Query the original requestKey; do not submit a new key.';
+        const retryAdvice = command === 'ensure' ? 'Inspect daemon status before retrying; startup may already have completed.' : command.includes('notification') ? 'Read the original notification binding. Retry a binding mutation only with the same actionId and payload.' : command.includes('occurrence') ? 'Read the original occurrence and approvalDecisions. Retry approval only with the same actionId and payload.' : 'Query the original requestKey; do not submit a new key.';
         return new Promise((resolve, reject) => {
             const child = spawn(options.execPath ?? process.execPath, [options.cliPath, 'daemon', command, '--cwd', options.cwd, '--request-stdin'], {
                 cwd: options.cwd, env: options.env ?? process.env, stdio: ['pipe', 'pipe', 'pipe'],
@@ -73,6 +73,7 @@ export function createBackgroundClient(options) {
         });
     }
     return {
+        ensureDaemon: () => invoke('ensure', {}),
         getScheduledNotificationBinding: (selector) => invoke('get-scheduled-notification-binding', { selector }),
         rebindScheduledNotifications: (request) => invoke('rebind-scheduled-notifications', request),
         getOccurrence: (request) => invoke('get-occurrence', request),

package/dist/sdk/index.d.ts

@@ -20,7 +20,7 @@ export type { RecoveryDiagnostic } from './errorDiagnostics.js';
 export type { GatewayRequestPhase, GatewayRequestProgress } from './requestProgress.js';
 export type { AccumulatedUsage, CanUseToolContext, CanUseToolFn, CanUseToolResult, InitializationResult, LifecycleHooks, PendingApproval, PendingDecision, ProviderConfig, Query, QueryOptions, SDKEvent, SDKUserMessage, SessionStore, SessionLifecycleEvent, Transport, Usage, WireMessage, } from './types.js';
 export { getExecutionGuidance } from './executionGuidance.js';
-export { createBackgroundClient, BackgroundClientError, type BackgroundClientOptions } from './background.js';
+export { createBackgroundClient, BackgroundClientError, type BackgroundClientOptions, type DaemonEnsureResult } from './background.js';
 export type { ScheduledNotificationSelector, ScheduledNotificationRebind, ScheduledNotificationBinding, ScheduledNotificationBindingLookup, EffectiveScheduledNotificationRoute } from './scheduledNotificationTypes.js';
 export type { BackgroundRun, BackgroundRunSpec, BackgroundRunLookup, BackgroundRunSelector, BackgroundRunEvent, BackgroundRunEvents, BackgroundRunAction, BackgroundRunApproval, BackgroundPermission, BackgroundRunSource } from './backgroundRunTypes.js';
 export { runCommandProcess, type CommandProcessInput, type CommandProcessResult } from './commandProcess.js';

package/docs/background-runs.md

@@ -93,6 +93,34 @@ await background.cancelRun({ runId, expectedRevision, actionId: 'cancel-1' })
 
 `ccl daemon submit|get|events|cancel-run|approve-run --request-stdin --cwd PROJECT` 从 stdin 接收 JSON。submit 可启动缺失的兼容 daemon；读取不会启动进程。旧活 owner 配置不匹配时明确拒绝，不暗中替换。daemon stop 停调度；取消某一 run 使用 cancel-run。
 
+### 按原配置恢复 owner
+
+成功启动并就绪的 owner 会记录可复用的启动配置。退出前台不会停止它；owner 自己停止后，宿主或用户可以调用：
+
+```sh
+ccl daemon status --cwd PROJECT
+ccl daemon ensure --cwd PROJECT
+```
+
+`ensure` 复用就绪且 CLI 兼容的 owner；缺少活 owner 时，从本产品 `.ccl/daemon/recovery.json` 恢复原配置。它不使用默认模型猜测启动，也不停止已有的不同配置/版本进程。返回 `{ok:true,result:{action,project,owner:{ready,pid,configId},recovery}}`；`action=reused` 表示直接复用，`started` 表示进入启动路径，并发时返回实际获锁者身份，不代表本调用独占创建。失败返回 `{ok:false,code,error}` 并退出非零。
+
+SDK 使用同包的 `createBackgroundClient({cwd,cliPath,env}).ensureDaemon()`，返回上述 result，失败抛 `BackgroundClientError`。`options.launch` 仍用于提交任务，不覆盖 ensure 的原配方。恢复 owner 不创建新的 task/run/occurrence，也不批准等待中的权限。
+
+status 的 `recovery` 表示磁盘记录的状态，不是当前凭据可用或任务执行成功的保证；真实启动前还会核对配置。CronCreate 的 `owner.recovery` 表示该 owner 是否成功记录配方。`background_ready` 可以同时伴随 `recovery.status=unavailable`：当前任务已交接，但退出后尚不能自动恢复；不要为此另建重复任务。旧 owner 没有这个字段时可恢复性未知。
+
+| 原因 | 处理 |
+| --- | --- |
+| recovery_missing / unconfirmed | 从原宿主按原 taskId 重新 handoff，确认就绪；不手工拼造配方 |
+| inline_configuration / unsupported_configuration | 将内联 settings/MCP 或复杂权限命令模式改用持久配置文件，再重新交接；明确空 MCP 配置可保存 |
+| credentials_unavailable | 提供原来源的有效凭据后重试；不把 token 写进配方 |
+| configuration_changed / owner_incompatible | 核对 CLI/配置变化，明确选择切换时机后重新交接，不自动停止活进程 |
+| recovery_invalid / recovery_changed | 检查记录或并发启动状态，不删除重建任务库掩盖错误 |
+| storage_error / recovery_storage_error | 修复项目后台目录的写入权限；未确认配方不能用于恢复 |
+
+记录保留配置来源、受支持非凭据环境键及其缺失状态；凭据只记录来源键名，恢复时重新获取当前值。任意内联 JSON 不会被“脱敏后执行”。新启动无法保存可恢复参数时，旧配方失效。首次升级到支持此功能的版本仍需一次正常交接生成记录；更换 CLI 路径/字节或配置后也需要重新确认，不能强用旧 configId。
+
+此命令本身不安装系统自启，也不会定时主动运行；宿主可以显式调用 ensure。停机漏跑原因与自启服务属于后续交付，当前保持既有 missed/coalesce 语义。CCL 与 Margay 的目录、记录、凭据和 owner 独立，不互相接管。
+
 ### 安装升级与已有定时任务
 
 安装新包不会重启正在运行的 daemon。`ccl daemon status --cwd PROJECT`、`scheduledStatus` 和 `CronList` 的 background 结果包含：

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

@@ -89,3 +89,7 @@ configuration.
 even after a completed one-shot definition has been removed. `ccl daemon status`
 provides the same records from a fresh CLI. Process liveness (`running`) and verified
 scheduler readiness (`owner.ready`) are separate fields.
+
+## Restoring an owner with its original launch
+
+`ccl daemon ensure --cwd PROJECT` restores a confirmed reusable launch or reuses a compatible ready owner. It does not install a login service. Inspect `recovery` in daemon status; missing or unsafe records require a new handoff from the original host. Credentials are resolved again and are never stored in the recipe. See [background recovery](background-runs.md) for the JSON/SDK interface and failure handling.

package/docs/multi-gateway-auth-entry-usage.md

@@ -0,0 +1,20 @@
+# 多网关账号入口
+
+适用于 CCL 1.5.1-alpha.7 与 Margay CLI 1.8.0-alpha.1。两产品分别保存网关账号和凭据。
+
+交互会话中使用 `/login` 或 `/gateway login`，会显示已保存网关、官方网关和“连接本机或自建网关”。首次账号引导也使用同一入口。选择已保存网关会验证其账号后切换；手工 API key 配置仍标记为“未验证账号”。
+
+添加本机或自建网关时，输入网关地址，例如 `http://127.0.0.1:18090`，再选择：
+
+- 已有网关账号 token：隐藏输入；目标网关 `/auth/me` 核对账号有效后才保存到系统凭据库。
+- 此网关的授权网站：明确输入该网关支持的授权网站地址。网站必须支持现有 CLI 授权合同；任意网页登录页不会自动变成 CLI 授权服务。
+
+客户端不提供尚未接入服务端协议的 SSO 或设备授权。普通推理 API key 也不等于可用于账号和功能门的网关账号 token。
+
+终端中运行 `margay login`（CCL 使用 `ccl login`）进入同样的选择流程。自动化场景可把已有账号 token 经管道输入 `margay login --gateway URL --token-stdin`，不要把 token 写进命令参数或 shell 历史。此选项要求明确网关地址，不能与 `--website` 或 `--force` 同用。
+
+`margay account list` 列出本产品保存的网关，`margay account switch URL` 选择已有网关，`margay account status` 验证当前账号。CCL 命令把 `margay` 换成 `ccl`；两产品的默认配置和凭据服务继续分开。
+
+有效账号可复用，不必每次访问网站。授权网站来源随网关保存，过期时仍使用对应网站。旧自建网关账号缺少认证来源时，会要求选择认证方式，不能默认发送到官网。网络故障保留账号和当前选择，提示重试；明确认证失败才提示重新认证。取消同样不会清除账号。
+
+本机联调时应选择测试网关及测试账号，显式网关环境变量仍可能覆盖保存的选择，界面会提示这一点。

package/docs/releases/1.5.1-alpha.7.md

@@ -0,0 +1,16 @@
+# @margay/ccl-core 1.5.1-alpha.7
+
+本次增量更新包含多网关认证入口和后台运行恢复。
+
+- 首次引导、会话内登录与终端登录支持选择已有网关、官方网关或自建网关。
+- 自建网关可使用已有账号 token 或明确指定其授权网站；每个网关独立保存凭据，失败或取消不会覆盖原账号。
+- 新增 `daemon ensure --cwd PROJECT` 与 SDK `ensureDaemon()`，按保存的安全配置恢复后台 owner；缺少恢复记录、配置改变或存在不兼容 owner 时明确拒绝。
+- 恢复不会重新执行已完成的任务，也不提供系统开机自启。升级改变 CLI 文件后，需要正常启动并重新交接，以生成与新版匹配的恢复记录。
+
+安装：`npm install -g @margay/ccl-core@1.5.1-alpha.7`，随后运行 `ccl --version`。
+
+多网关分别登录不等于网站统一单点登录；授权网站必须与目标网关匹配。服务端最新测试环境的网页登录链路尚未完成本轮验收。
+
+CCL 与 Margay CLI 的配置、凭据和后台服务保持独立。运行中的会话或 daemon 不会自动加载新安装的代码；请在任务安排允许时正常停止并重新启动对应产品。
+
+需要回退时安装 `@margay/ccl-core@1.5.1-alpha.6` 并重新启动对应产品。程序回退不会撤销工具已经产生的文件修改或服务端数据。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@margay/ccl-core",
-  "version": "1.5.1-alpha.6",
+  "version": "1.5.1-alpha.7",
   "description": "CCL agent runtime for Margay integration",
   "license": "SEE LICENSE IN README.md",
   "type": "module",
@@ -58,7 +58,9 @@
     "docs/releases/1.5.1-alpha.4.md",
     "docs/releases/1.5.1-alpha.5.md",
     "docs/releases/1.5.1-alpha.6.md",
-    "docs/gateway-vision-capabilities.md"
+    "docs/gateway-vision-capabilities.md",
+    "docs/multi-gateway-auth-entry-usage.md",
+    "docs/releases/1.5.1-alpha.7.md"
   ],
   "engines": {
     "node": ">=22.19.0"

package/sdk/API.md

@@ -739,3 +739,7 @@ the previously published alpha.2 does not support them.
 `createBackgroundClient()` 提供 `getScheduledNotificationBinding(selector)` 与 `rebindScheduledNotifications(request)`，用于新会话接收原定时任务通知。选择器为 `{ taskId, taskCreatedAt }` 或 `{ occurrenceId }`；请求包含 `selector`、`targetSessionId`、`expectedRevision`（初始 0）和稳定 `actionId`。返回绑定含 `sessionId/revision/generation/updatedAt`。读取 occurrence 绑定还返回 `effective` 路由；显式 occurrence 优先于 task，task 优先于原 delegation。
 
 换绑不启动 owner、不改变原任务或审批状态。超时重试原 actionId 和原请求；同 ID 改内容拒绝，revision 冲突须读取当前状态后决定新动作。模型工具固定绑定到自己的宿主 session，并请求权限确认。已被消费者接受的旧通知不会撤回；新代次只通知当前待办或结果，不重放过期历史。完整 CLI、工具字段、错误和恢复说明见 [新会话接收原任务通知](../docs/background-runs.md#新会话接收原任务通知)。
+
+## 原配置恢复 daemon
+
+同包 `createBackgroundClient({ cwd, cliPath, env }).ensureDaemon()` 返回 `DaemonEnsureResult`：`action` 为 `reused` 或 `started`，包含真实 `project`、`owner.ready/pid/configId` 和 `recovery.status/reason`。失败使用 `BackgroundClientError.code`；启动超时不表示进程肯定未启动，先查询 daemon status。此方法不使用 `options.launch` 覆盖记录、不提交新任务、不安装自启。详见[后台恢复契约](../docs/background-runs.md)。