@dobby.ai/dobby 0.1.0 → 0.1.2

package/README.md

@@ -7,6 +7,7 @@ Discord-first 本地 Agent Gateway。宿主只负责 CLI、网关主流程、扩
 - `@dobby.ai/connector-discord`
 - `@dobby.ai/connector-feishu`
 - `@dobby.ai/provider-pi`
+- `@dobby.ai/provider-codex-cli`
 - `@dobby.ai/provider-claude-cli`
 - `@dobby.ai/provider-claude`
 - `@dobby.ai/sandbox-core`
@@ -17,14 +18,14 @@ Discord-first 本地 Agent Gateway。宿主只负责 CLI、网关主流程、扩
 
 - connector source -> binding -> route -> provider / sandbox
 - Discord 频道 / 线程接入；线程消息继续按父频道命中 binding
-- Feishu 长连接消息接入（self-built app，手工安装/配置）
+- Feishu 长连接消息接入（self-built app）
 - Feishu 出站支持普通文本和 Markdown 卡片；默认群内直发，不走 reply thread
 - conversation 级 runtime 复用与串行化
 - 扩展 store 安装、启用、列举与 schema 驱动配置
 - Discord 流式回复、typing、附件下载与图片输入
 - cron 调度：一次性、固定间隔、cron expression
-- 交互式初始化：`dobby init`
-- 交互式配置：`dobby configure` / `dobby config edit`
+- 交互式初始化：`dobby init`（支持多 provider / 多 connector starter）
+- 配置检查与 schema inspect：`dobby config show|list|schema`
 - 诊断与保守修复：`dobby doctor [--fix]`
 
 ## 架构概览
@@ -59,7 +60,7 @@ Discord / Cron
 - npm
 - 对应 provider / connector 的外部运行条件
   - 例如 Discord bot token
-  - Claude CLI 或 Claude Agent SDK 所需认证
+  - Codex CLI、Claude CLI 或 Claude Agent SDK 所需认证
   - 可选的 Docker / Boxlite 运行环境
 
 ## 快速开始
@@ -76,7 +77,7 @@ npm install
 npm run build
 ```
 
-3. 初始化最小可运行配置
+3. 初始化模板配置
 
 ```bash
 npm run start -- init
@@ -84,21 +85,41 @@ npm run start -- init
 
 `init` 会做这些事情：
 
-- 交互选择 provider 和 connector
+- 交互选择 provider 和 connector（均可多选）
 - 自动安装所选扩展到运行时 extension store
-- 优先使用扩展暴露的 `configSchema` 生成配置
+- 写入一份带占位符的 `gateway.json` 模板
+- 把 `routes.default.projectRoot` 设为当前工作目录
+- 为 direct message 生成 `bindings.default`，回落到默认 route
+- 为每个所选 connector 生成一个默认 binding 到同一条 route
 - 生成 `gateway.json`
-- 选择 `provider.pi` 且缺少 `models.custom.json` 时，自动创建该文件
+- `provider.pi` 默认写入最小 inline 配置，不再依赖 `models.custom.json`
 
-说明：当前 `init` 仍只内建 Discord connector。Feishu connector 需要通过 `extension install` + `config edit/configure` 手工启用。
+说明：当前 `init` 内建这些 starter 选择：
 
-4. 运行诊断
+- provider：`provider.pi`、`provider.claude-cli`
+- connector：`connector.discord`、`connector.feishu`
+
+4. 编辑 `gateway.json`
+
+把 `REPLACE_WITH_*` / `YOUR_*` 占位值替换成你的真实配置，例如：
+
+- `connectors.items[*]` 中的 token / appId / appSecret
+- `bindings.items[*].source.id`
+- `routes.items[*].projectRoot`（如需覆盖默认 project root）
+
+5. 运行诊断
 
 ```bash
 npm run start -- doctor
 ```
 
-5. 启动网关
+`doctor` 会同时检查：
+
+- 配置结构 / 引用关系
+- 缺失的扩展安装
+- `REPLACE_WITH_*` / `YOUR_*` 这类 init 占位值是否还未替换
+
+6. 启动网关
 
 ```bash
 npm run start --
@@ -107,7 +128,9 @@ npm run start --
 说明：
 
 - `dobby` 无子命令时，默认等价于 `dobby start`
+- `dobby --version` 可直接查看当前 CLI 版本
 - 在仓库内直接运行时，CLI 会自动使用 `./config/gateway.json`
+- 在仓库内执行 `init` / `extension install` 时，会优先安装 `plugins/*` 的本地构建产物
 - 也可以通过环境变量覆盖配置路径：
 
 ```bash
@@ -152,33 +175,23 @@ cron 配置路径优先级：
 顶层命令：
 
 ```bash
+dobby --version
 dobby start
 dobby init
-dobby configure
 dobby doctor [--fix]
 ```
 
-配置与拓扑：
+配置检查：
 
 ```bash
 dobby config show [section] [--json]
 dobby config list [section] [--json]
-dobby config edit [--section provider|connector|route|binding]
 dobby config schema list [--json]
 dobby config schema show <contributionId> [--json]
-
-dobby bot list [--json]
-dobby bot set <connectorId> [--name <name>] [--token <token>]
-
-dobby binding list [--connector <id>] [--json]
-dobby binding set <bindingId> --connector <id> --source-type channel|chat --source-id <id> --route <id>
-dobby binding remove <bindingId>
-
-dobby route list [--json]
-dobby route set <routeId> [--project-root <path>] [--tools full|readonly] [--provider <id>] [--sandbox <id>] [--mentions required|optional]
-dobby route remove <routeId> [--cascade-bindings]
 ```
 
+配置变更建议直接编辑 `gateway.json`，再通过 `dobby doctor` 或 `dobby start` 做校验。
+
 扩展管理：
 
 ```bash
@@ -221,25 +234,40 @@ dobby cron remove <jobId>
   - 默认 provider instance ID
 - `providers.items[*].type` / `connectors.items[*].type` / `sandboxes.items[*].type`
   - 指向某个 contribution，实例配置直接内联在对象里
-- `routes.defaults`
-  - 统一提供 route 默认的 `provider`、`sandbox`、`tools`、`mentions`
+- `routes.default`
+  - 统一提供 route 默认的 `projectRoot`、`provider`、`sandbox`、`tools`、`mentions`
 - `routes.items[*]`
-  - route 是可复用的执行 profile，定义 `projectRoot`，并按需覆盖 `provider`、`sandbox`、`tools`、`mentions`、`systemPromptFile`
+  - route 是可复用的执行 profile，可继承默认 `projectRoot`，并按需覆盖 `provider`、`sandbox`、`tools`、`mentions`、`systemPromptFile`
+- `bindings.default`
+  - direct message 未命中显式 binding 时使用的默认 route fallback
 - `bindings.items[*]`
   - `(connector, source.type, source.id) -> route` 的入口绑定
 - `sandboxes.default`
   - 未指定时默认使用 `host.builtin`
-- 未匹配 binding 的入站消息会被直接忽略，不存在 default route fallback
-
-当前代码还保留但未真正生效的字段：
-
-- cron job 的 `sessionPolicy`
+- 未匹配 binding 的入站消息会被直接忽略；仅 direct message 可回落到 `bindings.default`
 
 示例配置：
 
 - gateway：[`config/gateway.example.json`](config/gateway.example.json)
 - cron：[`config/cron.example.json`](config/cron.example.json)
-- provider.pi 自定义模型：[`config/models.custom.example.json`](config/models.custom.example.json)
+
+`provider.pi` 现在使用 inline custom provider 配置。最小常用字段是：
+
+- `model`
+- `baseUrl`
+- `apiKey`
+
+这些字段默认自动补齐：
+
+- `provider = "custom-openai"`
+- `api = "openai-completions"`
+- `authHeader = false`
+- `thinkingLevel = "off"`
+- `models = [{ id: model }]`
+
+只有在你需要多模型元数据或覆盖能力参数时，才需要手工展开 `models`。
+
+`apiKey` 支持直接写 literal，也支持写环境变量名，由 `pi` 的 `AuthStorage` / `ModelRegistry` 按上游规则解析。
 
 ## 扩展包与 contribution
 
@@ -247,6 +275,7 @@ dobby cron remove <jobId>
 
 - `connector.discord`
 - `provider.pi`
+- `provider.codex-cli`
 - `provider.claude-cli`
 - `provider.claude`
 - `sandbox.boxlite`
@@ -255,15 +284,30 @@ dobby cron remove <jobId>
 `dobby init` 当前只内建这些 starter 选择：
 
 - provider：`provider.pi`、`provider.claude-cli`
-- connector：`connector.discord`
+- connector：`connector.discord`、`connector.feishu`
 
-`provider.claude` 与 sandbox 相关扩展需要手工安装和配置，例如：
+`provider.codex-cli`、`provider.claude` 与 sandbox 相关扩展需要手工安装和配置，例如：
 
 ```bash
+npm run start -- extension install @dobby.ai/provider-codex-cli --enable
 npm run start -- extension install @dobby.ai/provider-claude --enable
 npm run start -- extension install @dobby.ai/sandbox-core --enable
 ```
 
+若使用 `provider.codex-cli`，启动前建议检查：
+
+```bash
+codex --version
+codex login status
+```
+
+最小配置字段：
+
+- `command`（默认 `codex`）
+- `commandArgs`（默认 `[]`）
+- `model`（可选；未设置时使用 Codex CLI / 本地配置默认模型）
+- `skipGitRepoCheck`（默认 `false`）
+
 `--enable` 的行为：
 
 - 把包写入 `extensions.allowList`
@@ -292,13 +336,14 @@ npm run start -- cron add daily-report \
 
 说明：
 
-- `cron run <jobId>` 只是把 job 标记为“下一次 scheduler tick 执行”
+- `cron run <jobId>` 会额外排队一次立即执行，不会恢复 paused 状态，也不会改写原有 `nextRunAtMs`
 - 需要已有一个正在运行的 `dobby start`
 - 当前 scheduled run 一律按 stateless / ephemeral 执行
 
 ## Discord 连接器的当前行为
 
-- 只处理已绑定的 guild channel，DM 目前禁用
+- guild channel 仍按显式 binding 匹配
+- DM 可通过 `bindings.default` 回落到默认 route
 - 线程消息使用父频道 ID 做 binding 查找
 - 会自动下载附件到本地
 - 图片会作为 image input 传给 provider
@@ -372,7 +417,7 @@ npm run plugins:build
 
 - `npm run dev:local` 与 `npm run start:local` 会尝试读取 `.env`
 - 普通 `npm run start -- ...` 不会自动载入 `.env`
-- 配置编辑流优先使用扩展 `configSchema`，无 schema 时退回 JSON 输入
+- `dobby init` 生成的是模板配置；运行前先替换 `gateway.json` 中的 placeholder
 
 ## 相关文档
 

package/dist/src/agent/event-forwarder.js

@@ -1,3 +1,11 @@
+import { OUTBOUND_MESSAGE_KIND_METADATA_KEY, OUTBOUND_MESSAGE_KIND_PROGRESS, } from "../core/types.js";
+const DEFAULT_PROGRESS_DEBOUNCE_MS = 150;
+const DEFAULT_LONG_PROGRESS_MS = 10_000;
+const WORKING_LOCALLY_TEXT = "Working locally...";
+const STILL_WORKING_LOCALLY_TEXT = "Still working locally...";
+const WORKING_WITH_TOOLS_TEXT = "Working with tools...";
+const STILL_WORKING_WITH_TOOLS_TEXT = "Still working with tools...";
+const RECOVERING_FROM_TOOL_ISSUE_TEXT = "Recovering from a tool issue...";
 function truncate(text, max) {
     if (max === undefined)
         return text;
@@ -57,22 +65,37 @@ export class EventForwarder {
     appendEmittedText = "";
     pendingFlush = null;
     flushSerial = Promise.resolve();
+    progressSerial = Promise.resolve();
     pendingOps = [];
     updateIntervalMs;
+    progressDebounceMs;
+    longProgressMs;
     toolMessageMode;
     maxTextLength;
     onOutboundActivity;
     updateStrategy;
+    progressUpdateStrategy;
     lastEditPrimaryText = null;
+    progressMessageId = null;
+    lastProgressMessageText = null;
+    pendingProgressText = null;
+    pendingProgressFlush = null;
+    hasQueuedProgressMessage = false;
+    longProgressTimer = null;
+    activeWorkPhase = null;
     constructor(connector, inbound, rootMessageId, logger, options = {}) {
         this.connector = connector;
         this.inbound = inbound;
         this.logger = logger;
         this.rootMessageId = rootMessageId;
         this.updateIntervalMs = options.updateIntervalMs ?? 400;
+        this.progressDebounceMs = options.progressDebounceMs ?? DEFAULT_PROGRESS_DEBOUNCE_MS;
+        this.longProgressMs = options.longProgressMs ?? DEFAULT_LONG_PROGRESS_MS;
         this.toolMessageMode = options.toolMessageMode ?? "none";
         this.onOutboundActivity = options.onOutboundActivity;
         this.updateStrategy = this.connector.capabilities.updateStrategy;
+        this.progressUpdateStrategy = this.connector.capabilities.progressUpdateStrategy
+            ?? (this.updateStrategy === "edit" ? "edit" : "create");
         const capabilityMaxTextLength = this.connector.capabilities.maxTextLength;
         this.maxTextLength = typeof capabilityMaxTextLength === "number" && capabilityMaxTextLength > 0
             ? capabilityMaxTextLength
@@ -98,13 +121,20 @@ export class EventForwarder {
             }
             return;
         }
+        if (event.type === "command_start") {
+            this.enterWorkPhase("local");
+            return;
+        }
         if (event.type === "tool_start") {
             this.logger.info({
                 toolName: event.toolName,
                 conversation: `${this.inbound.platform}:${this.inbound.accountId}:${this.inbound.chatId}:${this.inbound.threadId ?? "root"}`,
             }, "Tool execution started");
-            if (this.updateStrategy !== "final_only" && this.toolMessageMode === "all") {
-                this.enqueueSend(`_-> Running tool: ${event.toolName}_`);
+            if (this.toolMessageMode === "all") {
+                this.enqueueSideMessage(this.renderToolStartMessage(event.toolName));
+            }
+            else {
+                this.enterWorkPhase("tool");
             }
             return;
         }
@@ -115,26 +145,21 @@ export class EventForwarder {
                 isError: event.isError,
                 conversation: `${this.inbound.platform}:${this.inbound.accountId}:${this.inbound.chatId}:${this.inbound.threadId ?? "root"}`,
             }, event.isError ? "Tool execution finished with error" : "Tool execution finished");
-            if (this.updateStrategy !== "final_only" &&
-                (this.toolMessageMode === "all" || (this.toolMessageMode === "errors" && event.isError))) {
-                const prefix = event.isError ? "ERR" : "OK";
-                const header = `*${prefix} ${event.toolName}*\n\`\`\`\n`;
-                const footer = "\n```";
-                const availableSummaryLength = this.maxTextLength === undefined
-                    ? undefined
-                    : Math.max(0, this.maxTextLength - header.length - footer.length);
-                this.enqueueSend(`${header}${truncate(summary, availableSummaryLength)}${footer}`);
+            if ((this.toolMessageMode === "all" || (this.toolMessageMode === "errors" && event.isError))) {
+                this.enqueueSideMessage(this.renderToolEndMessage(event.toolName, event.isError, summary));
+            }
+            else if (event.isError) {
+                this.setProgressMessage(RECOVERING_FROM_TOOL_ISSUE_TEXT);
             }
             return;
         }
         if (event.type === "status") {
-            if (this.updateStrategy === "final_only") {
-                return;
-            }
-            this.enqueueSend(`_${event.message}_`);
+            this.setProgressMessage(event.message);
         }
     };
     async finalize() {
+        this.clearLongProgressTimer();
+        await this.flushProgressUpdates();
         if (this.updateStrategy === "final_only") {
             await this.finalizeFinalOnly();
             await Promise.allSettled(this.pendingOps);
@@ -173,6 +198,7 @@ export class EventForwarder {
                 return;
             }
             try {
+                await this.flushProgressUpdates();
                 if (this.updateStrategy === "append") {
                     await this.flushAppendProgress();
                     return;
@@ -198,13 +224,113 @@ export class EventForwarder {
         });
         await run;
     }
-    enqueueSend(text) {
+    enqueueSideMessage(text) {
+        this.enqueueSendWithMetadata(text, this.progressMessageMetadata());
+    }
+    setProgressMessage(message) {
+        this.activeWorkPhase = null;
+        this.clearLongProgressTimer();
+        this.scheduleProgressUpdate(this.renderStatusMessage(message));
+    }
+    enterWorkPhase(phase) {
+        if (this.activeWorkPhase === "local" && phase === "tool") {
+            return;
+        }
+        if (this.activeWorkPhase === phase) {
+            return;
+        }
+        this.activeWorkPhase = phase;
+        this.scheduleProgressUpdate(this.renderWorkPhaseMessage(phase, false));
+        this.scheduleLongProgressUpdate(phase);
+    }
+    scheduleProgressUpdate(text) {
+        const shouldCreateImmediately = !this.hasQueuedProgressMessage;
+        this.hasQueuedProgressMessage = true;
+        this.pendingProgressText = text;
+        if (shouldCreateImmediately) {
+            void this.flushProgressNow();
+            return;
+        }
+        if (this.pendingProgressFlush) {
+            clearTimeout(this.pendingProgressFlush);
+        }
+        this.pendingProgressFlush = setTimeout(() => {
+            void this.flushProgressNow();
+        }, this.progressDebounceMs);
+    }
+    async flushProgressNow() {
+        if (this.pendingProgressFlush) {
+            clearTimeout(this.pendingProgressFlush);
+            this.pendingProgressFlush = null;
+        }
+        const text = this.pendingProgressText;
+        if (text === null) {
+            return;
+        }
+        this.pendingProgressText = null;
+        const metadata = this.progressMessageMetadata();
+        const run = this.progressSerial.then(async () => {
+            if (this.lastProgressMessageText === text) {
+                return;
+            }
+            try {
+                if (this.canEditProgressMessage() && this.progressMessageId) {
+                    await this.connector.send({
+                        ...this.baseEnvelope(),
+                        mode: "update",
+                        targetMessageId: this.progressMessageId,
+                        text,
+                        metadata,
+                    });
+                    this.lastProgressMessageText = text;
+                    this.noteOutboundActivity();
+                    return;
+                }
+                const created = await this.connector.send({
+                    ...this.baseEnvelope(),
+                    mode: "create",
+                    text,
+                    metadata,
+                });
+                this.progressMessageId = this.canEditProgressMessage() ? (created.messageId ?? this.progressMessageId) : null;
+                this.lastProgressMessageText = text;
+                this.noteOutboundActivity();
+            }
+            catch (error) {
+                this.logger.warn({
+                    err: error,
+                    connectorId: this.inbound.connectorId,
+                    chatId: this.inbound.chatId,
+                    progressMessageId: this.progressMessageId,
+                }, "Failed to send or update progress message");
+            }
+        });
+        this.progressSerial = run.catch(() => {
+            // keep chain alive for future progress updates
+        });
+        this.pendingOps.push(run);
+        await run;
+    }
+    scheduleLongProgressUpdate(phase) {
+        this.clearLongProgressTimer();
+        if (this.longProgressMs <= 0) {
+            return;
+        }
+        this.longProgressTimer = setTimeout(() => {
+            if (this.activeWorkPhase !== phase) {
+                return;
+            }
+            this.scheduleProgressUpdate(this.renderWorkPhaseMessage(phase, true));
+        }, this.longProgressMs);
+    }
+    enqueueSendWithMetadata(text, metadata) {
         const promise = this.connector
             .send({
             ...this.baseEnvelope(),
             mode: "create",
             ...(this.rootMessageId ? { replyToMessageId: this.rootMessageId } : {}),
             text,
+            ...(metadata ? { metadata } : {}),
         })
             .then(() => {
             this.noteOutboundActivity();
@@ -219,6 +345,49 @@ export class EventForwarder {
         });
         this.pendingOps.push(promise);
     }
+    canEditProgressMessage() {
+        return this.progressUpdateStrategy === "edit";
+    }
+    progressMessageMetadata() {
+        return {
+            [OUTBOUND_MESSAGE_KIND_METADATA_KEY]: OUTBOUND_MESSAGE_KIND_PROGRESS,
+        };
+    }
+    renderStatusMessage(message) {
+        return truncate(message, this.maxTextLength);
+    }
+    renderWorkPhaseMessage(phase, isLongRunning) {
+        if (phase === "local") {
+            return truncate(isLongRunning ? STILL_WORKING_LOCALLY_TEXT : WORKING_LOCALLY_TEXT, this.maxTextLength);
+        }
+        return truncate(isLongRunning ? STILL_WORKING_WITH_TOOLS_TEXT : WORKING_WITH_TOOLS_TEXT, this.maxTextLength);
+    }
+    renderToolStartMessage(toolName) {
+        return truncate(`Running tool: ${toolName}`, this.maxTextLength);
+    }
+    renderToolEndMessage(toolName, isError, summary) {
+        const prefix = isError ? "ERR" : "OK";
+        const body = summary.trim().length > 0 ? `${prefix} ${toolName}\n${summary}` : `${prefix} ${toolName}`;
+        return truncate(body, this.maxTextLength);
+    }
+    async flushProgressUpdates() {
+        if (this.pendingProgressText !== null) {
+            await this.flushProgressNow();
+            return;
+        }
+        try {
+            await this.progressSerial;
+        }
+        catch {
+            // progress message failures are already logged when they happen
+        }
+    }
+    clearLongProgressTimer() {
+        if (this.longProgressTimer) {
+            clearTimeout(this.longProgressTimer);
+            this.longProgressTimer = null;
+        }
+    }
     async sendEditPrimary(text) {
         if (this.rootMessageId && this.lastEditPrimaryText === text) {
             return;

package/dist/src/cli/commands/cron.js

@@ -36,15 +36,6 @@ function parseSchedule(input) {
         ...(input.tz ? { tz: input.tz } : {}),
     };
 }
-function parseSessionPolicy(value) {
-    if (value === undefined) {
-        return undefined;
-    }
-    if (value === "stateless" || value === "shared-session") {
-        return value;
-    }
-    throw new Error(`Invalid session policy '${value}'. Expected 'stateless' or 'shared-session'.`);
-}
 function assertDeliveryReferences(config, input) {
     if (!config.connectors.items[input.connectorId]) {
         throw new Error(`Unknown connectorId '${input.connectorId}'`);
@@ -86,13 +77,11 @@ export async function runCronAddCommand(options) {
     const now = Date.now();
     const nextRunAtMs = computeInitialNextRunAtMs(schedule, now);
     const id = `${slugify(options.name)}-${Math.random().toString(36).slice(2, 8)}`;
-    const sessionPolicy = parseSessionPolicy(options.sessionPolicy) ?? "stateless";
     const job = {
         id,
         name: options.name,
         enabled: true,
         schedule,
-        sessionPolicy,
         prompt: options.prompt,
         delivery: {
             connectorId: options.connectorId,
@@ -132,6 +121,9 @@ export async function runCronListCommand(options) {
         console.log(`- ${job.id} [${job.enabled ? "enabled" : "paused"}] ${job.name}`);
         console.log(`  schedule=${schedule}`);
         console.log(`  next=${next} last=${last} status=${job.state.lastStatus ?? "-"}`);
+        if (job.state.manualRunRequestedAtMs !== undefined) {
+            console.log(`  manualRun=${new Date(job.state.manualRunRequestedAtMs).toISOString()}`);
+        }
         console.log(`  delivery=${job.delivery.connectorId}/${job.delivery.routeId}/${job.delivery.channelId}`);
     }
 }
@@ -154,10 +146,12 @@ export async function runCronStatusCommand(options) {
         console.log(`- name: ${target.name}`);
         console.log(`- enabled: ${target.enabled}`);
         console.log(`- schedule: ${describeSchedule(target.schedule)}`);
-        console.log(`- sessionPolicy: ${target.sessionPolicy ?? "stateless"}`);
         console.log(`- nextRun: ${target.state.nextRunAtMs ? new Date(target.state.nextRunAtMs).toISOString() : "-"}`);
         console.log(`- lastRun: ${target.state.lastRunAtMs ? new Date(target.state.lastRunAtMs).toISOString() : "-"}`);
         console.log(`- lastStatus: ${target.state.lastStatus ?? "-"}`);
+        if (target.state.manualRunRequestedAtMs !== undefined) {
+            console.log(`- manualRunQueuedAt: ${new Date(target.state.manualRunRequestedAtMs).toISOString()}`);
+        }
         if (target.state.lastError) {
             console.log(`- lastError: ${target.state.lastError}`);
         }
@@ -173,28 +167,23 @@ export async function runCronRunCommand(options) {
     const now = Date.now();
     await context.store.updateJob(options.jobId, (current) => ({
         ...current,
-        enabled: true,
         updatedAtMs: now,
         state: {
             ...current.state,
-            nextRunAtMs: now,
+            manualRunRequestedAtMs: current.state.manualRunRequestedAtMs ?? now,
         },
     }));
-    console.log(`Scheduled cron job ${options.jobId} to run on next scheduler tick.`);
+    console.log(`Queued one manual run for cron job ${options.jobId}.`);
+    console.log("It will execute once without changing the job's enabled state or next scheduled run.");
     console.log("Ensure the gateway process is running for execution.");
 }
 export async function runCronUpdateCommand(options) {
     const context = await loadCronContext(options.cronConfigPath ? { cronConfigPath: options.cronConfigPath } : undefined);
     const now = Date.now();
-    const hasScheduleUpdate = options.at !== undefined || options.everyMs !== undefined || options.cronExpr !== undefined;
-    const nextSchedule = hasScheduleUpdate
-        ? parseSchedule({
-            ...(options.at ? { at: options.at } : {}),
-            ...(options.everyMs !== undefined ? { everyMs: options.everyMs } : {}),
-            ...(options.cronExpr ? { cronExpr: options.cronExpr } : {}),
-            ...(options.tz ? { tz: options.tz } : {}),
-        })
-        : null;
+    const hasScheduleUpdate = options.at !== undefined
+        || options.everyMs !== undefined
+        || options.cronExpr !== undefined
+        || options.tz !== undefined;
     await context.store.updateJob(options.jobId, (current) => {
         const updatedDelivery = {
             connectorId: options.connectorId ?? current.delivery.connectorId,
@@ -209,14 +198,37 @@ export async function runCronUpdateCommand(options) {
             connectorId: updatedDelivery.connectorId,
             routeId: updatedDelivery.routeId,
         });
-        const schedule = nextSchedule ?? current.schedule;
-        const nextRunAtMs = nextSchedule
+        let schedule = current.schedule;
+        if (hasScheduleUpdate) {
+            const hasExplicitScheduleVariant = options.at !== undefined
+                || options.everyMs !== undefined
+                || options.cronExpr !== undefined;
+            if (hasExplicitScheduleVariant) {
+                schedule = parseSchedule({
+                    ...(options.at ? { at: options.at } : {}),
+                    ...(options.everyMs !== undefined ? { everyMs: options.everyMs } : {}),
+                    ...(options.cronExpr ? { cronExpr: options.cronExpr } : {}),
+                    ...(options.tz ? { tz: options.tz } : {}),
+                });
+            }
+            else if (options.tz !== undefined) {
+                if (current.schedule.kind !== "cron") {
+                    throw new Error("--tz can only be updated for cron schedules or together with --cron");
+                }
+                schedule = {
+                    kind: "cron",
+                    expr: current.schedule.expr,
+                    ...(options.tz ? { tz: options.tz } : {}),
+                };
+            }
+        }
+        const nextRunAtMs = hasScheduleUpdate
             ? computeInitialNextRunAtMs(schedule, now)
             : current.state.nextRunAtMs;
         const nextState = {
             ...current.state,
         };
-        if (nextSchedule) {
+        if (hasScheduleUpdate) {
             if (nextRunAtMs === undefined) {
                 delete nextState.nextRunAtMs;
             }
@@ -224,7 +236,6 @@ export async function runCronUpdateCommand(options) {
                 nextState.nextRunAtMs = nextRunAtMs;
             }
         }
-        const parsedSessionPolicy = parseSessionPolicy(options.sessionPolicy);
         const nextJob = {
             ...current,
             name: options.name ?? current.name,
@@ -234,13 +245,6 @@ export async function runCronUpdateCommand(options) {
             updatedAtMs: now,
             state: nextState,
         };
-        const nextSessionPolicy = parsedSessionPolicy ?? current.sessionPolicy;
-        if (nextSessionPolicy !== undefined) {
-            nextJob.sessionPolicy = nextSessionPolicy;
-        }
-        else {
-            delete nextJob.sessionPolicy;
-        }
         return nextJob;
     });
     console.log(`Updated cron job ${options.jobId}`);