@dipoleml/dcode-cli 1.0.0 → 1.2.0

package/node_modules/@dcode/contracts/dist/hooks/workspace-hook-trust.d.ts

@@ -285,12 +285,12 @@ export declare const workspaceHookBundleSnapshotSchema: z.ZodObject<{
             timeoutMs: z.ZodOptional<z.ZodNumber>;
             maxOutputBytes: z.ZodOptional<z.ZodNumber>;
         }, "strict", z.ZodTypeAny, {
-            timeoutMs?: number | undefined;
             enabled?: boolean | undefined;
+            timeoutMs?: number | undefined;
             maxOutputBytes?: number | undefined;
         }, {
-            timeoutMs?: number | undefined;
             enabled?: boolean | undefined;
+            timeoutMs?: number | undefined;
             maxOutputBytes?: number | undefined;
         }>;
     }, "strict", z.ZodTypeAny, {
@@ -301,8 +301,8 @@ export declare const workspaceHookBundleSnapshotSchema: z.ZodObject<{
         configFileKind: "dcode.json" | ".dcode/config.json" | "explicit";
         explicitProjectConfig: boolean;
         hooksRoot: {
-            timeoutMs?: number | undefined;
             enabled?: boolean | undefined;
+            timeoutMs?: number | undefined;
             maxOutputBytes?: number | undefined;
         };
     }, {
@@ -313,8 +313,8 @@ export declare const workspaceHookBundleSnapshotSchema: z.ZodObject<{
         configFileKind: "dcode.json" | ".dcode/config.json" | "explicit";
         explicitProjectConfig: boolean;
         hooksRoot: {
-            timeoutMs?: number | undefined;
             enabled?: boolean | undefined;
+            timeoutMs?: number | undefined;
             maxOutputBytes?: number | undefined;
         };
     }>, "many">;
@@ -462,8 +462,8 @@ export declare const workspaceHookBundleSnapshotSchema: z.ZodObject<{
         configFileKind: "dcode.json" | ".dcode/config.json" | "explicit";
         explicitProjectConfig: boolean;
         hooksRoot: {
-            timeoutMs?: number | undefined;
             enabled?: boolean | undefined;
+            timeoutMs?: number | undefined;
             maxOutputBytes?: number | undefined;
         };
     }[];
@@ -525,8 +525,8 @@ export declare const workspaceHookBundleSnapshotSchema: z.ZodObject<{
         configFileKind: "dcode.json" | ".dcode/config.json" | "explicit";
         explicitProjectConfig: boolean;
         hooksRoot: {
-            timeoutMs?: number | undefined;
             enabled?: boolean | undefined;
+            timeoutMs?: number | undefined;
             maxOutputBytes?: number | undefined;
         };
     }[];
@@ -593,44 +593,44 @@ export declare const workspaceHookReviewFlowStateSchema: z.ZodEffects<z.ZodObjec
 }, "strict", z.ZodTypeAny, {
     state: "pending" | "cancelled" | "timed_out" | "superseded" | "resolved";
     sessionId: string;
-    createdAt: number;
+    generation: number;
     workspaceIdentity: string;
+    createdAt: number;
     bundleDigest: string;
     reviewFlowId: string;
-    generation: number;
     interactionId: string;
     deadlineAt: number;
     supersededByInteractionId?: string | undefined;
 }, {
     state: "pending" | "cancelled" | "timed_out" | "superseded" | "resolved";
     sessionId: string;
-    createdAt: number;
+    generation: number;
     workspaceIdentity: string;
+    createdAt: number;
     bundleDigest: string;
     reviewFlowId: string;
-    generation: number;
     interactionId: string;
     deadlineAt: number;
     supersededByInteractionId?: string | undefined;
 }>, {
     state: "pending" | "cancelled" | "timed_out" | "superseded" | "resolved";
     sessionId: string;
-    createdAt: number;
+    generation: number;
     workspaceIdentity: string;
+    createdAt: number;
     bundleDigest: string;
     reviewFlowId: string;
-    generation: number;
     interactionId: string;
     deadlineAt: number;
     supersededByInteractionId?: string | undefined;
 }, {
     state: "pending" | "cancelled" | "timed_out" | "superseded" | "resolved";
     sessionId: string;
-    createdAt: number;
+    generation: number;
     workspaceIdentity: string;
+    createdAt: number;
     bundleDigest: string;
     reviewFlowId: string;
-    generation: number;
     interactionId: string;
     deadlineAt: number;
     supersededByInteractionId?: string | undefined;

package/node_modules/@dcode/contracts/dist/index.d.ts

@@ -3,6 +3,7 @@ export * from "./interfaces/execution.port.js";
 export * from "./interfaces/browser-control.port.js";
 export * from "./interfaces/file-system.port.js";
 export * from "./interfaces/context-source.port.js";
+export * from "./interfaces/provider-endpoint-routing.port.js";
 export * from "./interfaces/http-client.port.js";
 export * from "./interfaces/image-processor.port.js";
 export * from "./interfaces/pdf-document.port.js";
@@ -22,6 +23,7 @@ export * from "./interfaces/dynamic-workflow-snippet.port.js";
 export * from "./interfaces/model-catalog.port.js";
 export * from "./interfaces/automation.port.js";
 export * from "./interfaces/off-peak.port.js";
+export * from "./interfaces/topic-resource.port.js";
 export * from "./interfaces/mcp.port.js";
 export * from "./interfaces/runtime-input-presentation.js";
 export * from "./events/session.events.js";

package/node_modules/@dcode/contracts/dist/index.js

@@ -7,6 +7,7 @@ export * from "./interfaces/execution.port.js";
 export * from "./interfaces/browser-control.port.js";
 export * from "./interfaces/file-system.port.js";
 export * from "./interfaces/context-source.port.js";
+export * from "./interfaces/provider-endpoint-routing.port.js";
 export * from "./interfaces/http-client.port.js";
 export * from "./interfaces/image-processor.port.js";
 export * from "./interfaces/pdf-document.port.js";
@@ -26,6 +27,7 @@ export * from "./interfaces/dynamic-workflow-snippet.port.js";
 export * from "./interfaces/model-catalog.port.js";
 export * from "./interfaces/automation.port.js";
 export * from "./interfaces/off-peak.port.js";
+export * from "./interfaces/topic-resource.port.js";
 export * from "./interfaces/mcp.port.js";
 export * from "./interfaces/runtime-input-presentation.js";
 // Events

package/node_modules/@dcode/contracts/dist/interfaces/browser-control.port.d.ts

@@ -412,6 +412,7 @@ export type BrowserCommand = {
     turnId?: string;
 } | {
     method: "closeSession";
+    closeTabs?: boolean;
 } | {
     method: "cancelRequest";
     requestId: string;
@@ -568,6 +569,8 @@ export interface BrowserControlListInput {
     traceContext?: TraceContext;
     signal?: AbortSignal;
 }
+/** 子会话 Browser 请求的 tab 归属：子会话自己（dwf 子代理）或父会话（core Agent 子代理）。 */
+export type BrowserChildSessionTabOwner = "child" | "parent";
 export interface BrowserControlPort {
     /** 只返回完成握手且当前 context 可达的 backend，不允许伪造 stub。 */
     list(input: BrowserControlListInput): Promise<BrowserBackendDescriptor[]>;
@@ -576,5 +579,24 @@ export interface BrowserControlPort {
     turnEnded?(input: BrowserControlListInput): Promise<void>;
     /** session 关闭时释放 browser guest、pending request 与 lease。 */
     closeSession?(input: BrowserControlListInput): Promise<void>;
+    /**
+     * 为一个客户端不认识的子会话派生端口：workspace / clientMode 按 parentSessionId 的会话解析。
+     *
+     * - `tabOwner: "child"`（默认，dwf 子代理）：tab 归属是子会话自己的 sessionId；派生端口的
+     *   closeSession 连 tab 一起关，并结束这份登记。
+     * - `tabOwner: "parent"`（core Agent 子代理）：下发的 sessionId 换成父会话，子代理与当前对话共用同一组
+     *   tab（桌面据此展开面板、tabs.list 列出对话全部 tab）；派生端口的 turnEnded / closeSession 不向
+     *   桌面发生命周期，tab 交给父会话自己的生命周期管理，closeSession 只结束登记。
+     *
+     * 登记结束后该子会话的请求与从未登记的一样被拒。
+     *
+     * 缺席表示实现不按客户端会话校验 sessionId（如 CLI headless CDP），子会话直接用本端口。
+     * 见 apps/dcode-cli/packages/dynamic-workflow/docs/execution-engine.md「Subagent sessions」。
+     */
+    forChildSession?(input: {
+        childSessionId: string;
+        parentSessionId: string;
+        tabOwner?: BrowserChildSessionTabOwner;
+    }): BrowserControlPort;
 }
 //# sourceMappingURL=browser-control.port.d.ts.map

package/node_modules/@dcode/contracts/dist/interfaces/dynamic-workflow-run-hole.port.d.ts

@@ -0,0 +1,92 @@
+import type { SessionId, ToolCallId } from "./shared.js";
+import type { TraceContext } from "../tracing/tracer.js";
+/**
+ * 一处留白在快照上的投影（apps/dcode-cli/packages/dynamic-workflow/docs/execution-engine.md「The run snapshot」）：
+ * 由 `hole-reached` / `hole-filled` 事件加引擎内存里的停驻表投影——**`waiting` 只在引擎说它在等时**
+ * 成立（进程亡故后没有 promise 在等，单靠事件会把一个没人问的留白报成在等），`filled` 来自事件。
+ * 零条时整字段缺席，≤32。
+ *
+ * `line` / `before` / `after` 是留白通知（core 的进度发射器）要念的三样：留白调用在草稿里的行、
+ * 它前后的阶段名，都来自编译产物；读不到时缺席，通知随之省略那一句。草稿路径不在这里——它就是
+ * 快照的 `scriptPath`。
+ */
+export interface DynamicWorkflowRunHole {
+    /** 留白的站点 id（`hole#21b40fca`，名字键）；`fillHole` 只认它。 */
+    siteId: string;
+    /** 这一处的序号（同一站点在循环里可以到达多次）。 */
+    ordinal: number;
+    /** 留白的字面名。 */
+    name: string;
+    /** 类型实参原文（`Verdict`），照脚本写法。 */
+    type: string;
+    state: "waiting" | "filled";
+    /** 到达时刻（epoch ms）；`waiting` 时在场。 */
+    since?: number;
+    /** 补全时刻（epoch ms）；`filled` 时在场。 */
+    filledAt?: number;
+    /** 补全它的会话（`fillHole` 请求的 `parentSessionId`）。 */
+    filledBy?: string;
+    /** 留白调用在 run 草稿里的行号（1 起）。 */
+    line?: number;
+    /** 留白之前的阶段名。 */
+    before?: string;
+    /** 留白之后的阶段名。 */
+    after?: string;
+}
+/**
+ * {@link DynamicWorkflowRunPort.fillHole} 的请求（docs/dynamic-workflow/launch.md「The `FillWorkflowHole`
+ * tool」；引擎文档「The fill service's checks」）。`body` 是留白函数体的**语句**，逐字节；拼接、编译、
+ * 站点稳定性检查与草稿改写都在端口实现侧。
+ */
+export interface DynamicWorkflowRunFillHoleRequest {
+    runId: string;
+    /** 留白的站点 id（`hole#21b40fca`，名字键）。 */
+    holeId: string;
+    body: string;
+    /** 补全的会话，落进 `hole-filled.filledBy`。 */
+    parentSessionId?: SessionId | string;
+    /** 发起这次补全的 FillWorkflowHole 工具调用。 */
+    toolCallId?: ToolCallId | string;
+    trace: TraceContext;
+}
+/**
+ * 补全被拒的结构化理由。四者对模型是四个不同的下一步：换 run id / 看 run 的状态（停了就先
+ * ResumeWorkflowRun）/ 改 fill 文件再交 `path` / 什么都别改，这是宿主的故障。
+ */
+export type DynamicWorkflowRunFillHoleRefusalReason = 
+/** journal 里没有这个 run。 */
+"run_not_found"
+/** run 不在飞，或这个留白不是它正在等的（已补过、还没到、未知 id）；message 说明是哪一种。 */
+ | "hole_not_waiting"
+/** 有效脚本编不过；`diagnostics` 在场。什么都没拼、没记、留白照旧在等。 */
+ | "compile_failed"
+/** 编好的有效脚本给某个既有站点换了号：分析器的编号规则被打破，是宿主故障而非模型的错；留白照旧在等。 */
+ | "fill_ids_unstable";
+/**
+ * 一条补全诊断。`inFill` 为真时 `line` / `column` 是**函数体内**的坐标（拼进去的那一段），否则是
+ * 脚本坐标——工具层据此把它锚到 fill 文件或 run 的草稿。
+ */
+export interface DynamicWorkflowRunFillHoleDiagnostic {
+    line: number;
+    column: number;
+    message: string;
+    code: number;
+    inFill: boolean;
+}
+/**
+ * `fillHole` 的结构化结果。成功时 `scriptText` 是**有效脚本**（已拼入函数体、已落库的那一份），
+ * 工具层据它铸 display；`scriptPath` 是 run 的草稿（已被就地改写成有效脚本；run 原本没有草稿时
+ * 由实现侧铸一份）；`phasesAdded` 是函数体带来的阶段名。
+ */
+export type FillWorkflowHoleResult = {
+    ok: true;
+    phasesAdded: string[];
+    scriptPath?: string;
+    scriptText: string;
+} | {
+    ok: false;
+    reason: DynamicWorkflowRunFillHoleRefusalReason;
+    message: string;
+    diagnostics?: DynamicWorkflowRunFillHoleDiagnostic[];
+};
+//# sourceMappingURL=dynamic-workflow-run-hole.port.d.ts.map

package/node_modules/@dcode/contracts/dist/interfaces/dynamic-workflow-run-hole.port.js

@@ -0,0 +1,9 @@
+// ============================================================
+// Dynamic Workflow Run Port - 留白（hole）的读面与补全面
+// ============================================================
+// 从 dynamic-workflow-run.port.ts 拆出（oxlint max-lines 400 行门），照 retune 的先例
+// （dynamic-workflow-run-retune.port.ts）：快照上的留白条目、`fillHole` 的请求与结果住在这里，端口
+// 方法本身仍在 DynamicWorkflowRunPort 上；公开名一个不改，主端口文件 `export type *` 再导出。
+// spec：docs/dynamic-workflow/launch.md「The `FillWorkflowHole` tool」；
+// apps/dcode-cli/packages/dynamic-workflow/docs/execution-engine.md「Holes」。
+export {};

package/node_modules/@dcode/contracts/dist/interfaces/dynamic-workflow-run-retune.port.d.ts

@@ -25,15 +25,15 @@ export type DynamicWorkflowRunRetuneRefusalReason = "not_live" | "unchanged";
  * {@link import("./dynamic-workflow-run.port.js").DynamicWorkflowRunAmendResult} 同一条论证：
  * 两种理由都是调用方可预期的业务分支。
  *
- * `ceiling` 与 `previous` 不是锦上添花：模型面的回话要说「至多 n 个子代理同时运行」，而 n 等于
- * 天花板时该说的是「限制已解除」（与 `CreateWorkflow` 的回话同一条判据）；事件日志要说「8 → 2」，
- * 从单个新值推不出前一个。两者都只有端口这一侧知道，留给调用方重算就是第二份天花板实现。
+ * `defaultConcurrency` 与 `previous` 不是锦上添花：模型面的回话要说「至多 n 个子代理同时运行」，而
+ * n 等于默认并发时要注明「（默认）」（与 `CreateWorkflow` 的回话同一条判据）；事件日志要说「8 → 2」，
+ * 从单个新值推不出前一个。两者都只有端口这一侧知道，留给调用方重算就是第二份默认并发实现。
  */
 export type DynamicWorkflowRunRetuneResult = {
     ok: true;
     maxConcurrency: number;
     previous: number;
-    ceiling: number;
+    defaultConcurrency: number;
 } | {
     ok: false;
     reason: DynamicWorkflowRunRetuneRefusalReason;

package/node_modules/@dcode/contracts/dist/interfaces/dynamic-workflow-run-retune.port.js

@@ -1,4 +1,8 @@
-// Dynamic Workflow Run Port：调整运行中的并发上限。
-// 定义请求、结果与能力边界，由 dynamic-workflow-run.port.ts 统一再导出，
-// 调用方通过 `@dcode/contracts` 使用。
+// ============================================================
+// Dynamic Workflow Run Port：就地改一个在飞 run 的并发上界
+// ============================================================
+// docs/dynamic-workflow/concurrency.md「Retuning a live run」。与情势截面
+// （dynamic-workflow-run-roster.port.ts）同一条拆分理由：dynamic-workflow-run.port.ts 顶到
+// oxlint max-lines 上限（400 行），而这三个类型自成一组。公开面不变——那边原样再导出，
+// `@dcode/contracts` 的导入路径一字不改。
 export {};

package/node_modules/@dcode/contracts/dist/interfaces/dynamic-workflow-run-workspace.port.js

@@ -1,4 +1,9 @@
-// Dynamic Workflow Run Port：工作区操作记录的读取类型。
-// 包含 `files.*`、`git.*` 和 `world.run` 调用的清单行与正文，
-// 由 dynamic-workflow-run.port.ts 统一再导出，调用方通过 `@dcode/contracts` 使用。
+// ============================================================
+// Dynamic Workflow Run Port：工作区 transcript 的读面类型
+// ============================================================
+// docs/dynamic-workflow/transcript-and-notifications.md。与情势截面
+// （dynamic-workflow-run-roster.port.ts）、retune（dynamic-workflow-run-retune.port.ts）同一条
+// 拆分理由：dynamic-workflow-run.port.ts 顶到 oxlint max-lines 上限（400 行），而这六个类型
+// 自成一组（一次 `files.*` / `git.*` / `world.run` 调用的清单行与正文）。公开面不变——那边
+// 原样再导出，`@dcode/contracts` 的导入路径一字不改。
 export {};

package/node_modules/@dcode/contracts/dist/interfaces/dynamic-workflow-run.port.d.ts

@@ -1,5 +1,6 @@
 import type { DynamicWorkflowRunHealth, DynamicWorkflowRunPhaseView, DynamicWorkflowRunSubagentView } from "./dynamic-workflow-run-roster.port.js";
 import type { DynamicWorkflowRunRetuneRequest, DynamicWorkflowRunRetuneResult } from "./dynamic-workflow-run-retune.port.js";
+import type { DynamicWorkflowRunFillHoleRequest, DynamicWorkflowRunHole, FillWorkflowHoleResult } from "./dynamic-workflow-run-hole.port.js";
 import type { DynamicWorkflowRunWorkspaceNode, DynamicWorkflowRunWorkspaceNodeResult, DynamicWorkflowRunWorkspaceNodeResultQuery } from "./dynamic-workflow-run-workspace.port.js";
 import type { DynamicWorkflowRunProgressPayload } from "../events/session.events.js";
 import type { ModelSelection } from "../model/model.js";
@@ -46,10 +47,10 @@ export interface DynamicWorkflowRunSubmitRequest {
      */
     phaseNames?: string[];
     /**
-     * 本 run 自己的并发上界：同时在飞的
-     * ask 数，落 `dwf_run.caps_max_concurrency`、resume 照用。**缺席即天花板**（机器推导值，
-     * `resolveWorkflowConcurrencyCeiling`）；给了就钳到 `[1, 天花板]`——它只能压低并发，永不抬高。
-     * 工具层在 `resolveInput` 里已经钳过一次（确认窗要显示实际生效的值），这里再钳是端口自己的契约。
+     * 本 run 自己的并发上界（docs/dynamic-workflow/concurrency.md「Two bounds on a run」）：同时在飞的
+     * ask 数，落 `dwf_run.caps_max_concurrency`、resume 照用。**缺席即默认并发**（机器推导值，
+     * `resolveWorkflowDefaultConcurrency`）；给了就向下取整、至少 1，**没有上限**——高于或低于默认都行。
+     * 工具层在 `resolveInput` 里已经取整过一次（确认窗要显示实际生效的值），这里再取整是端口自己的契约。
      */
     maxConcurrency?: number;
     /**
@@ -61,6 +62,13 @@ export interface DynamicWorkflowRunSubmitRequest {
      * 发生」有两个答案。主代理自己不受影响：它恒留在会话模型上。
      */
     subagentModel?: ModelSelection;
+    /**
+     * 脚本里点名的模型（docs/dynamic-workflow/launch.md「Models the script names」）：键是脚本逐字
+     * 写下的名字（运行期 persona 里带的就是它），值是工具层已经对着模型目录解析好的选择。与
+     * {@link subagentModel} 同一条路、同一个理由收结构化选择：随 `run-launched` 记一次（规范串）、
+     * 引擎从不读，宿主建子代理会话时按 persona 的名字查它。脚本没点名任何模型时缺席。
+     */
+    modelBindings?: Record<string, ModelSelection>;
     /**
      * 本 run 的脚本**来自哪个文件**的绝对路径。与 {@link subagentModel} 走同一条路：随 `run-launched` 记一次、引擎从不读、
      * 零 SQL（`dwf_run` 上没有这一列），两条读面再从事件读回。
@@ -127,6 +135,12 @@ export interface DynamicWorkflowRunAmendRequest {
      * `resolveInput` 里连同一次重新解析归一成这里的一个选择或缺席。
      */
     subagentModel?: ModelSelection;
+    /**
+     * **新脚本**点名的模型；语义同 {@link DynamicWorkflowRunSubmitRequest.modelBindings}。「同名沿用
+     * 前驱的绑定」是**工具面**的规则，在 `AmendWorkflow` 的 `resolveInput` 里连同重新解析归一成这里
+     * 的一张表；端口不从前驱继承任何绑定。
+     */
+    modelBindings?: Record<string, ModelSelection>;
     /**
      * **新脚本**来自哪个文件的绝对路径；语义同 {@link DynamicWorkflowRunSubmitRequest.scriptPath}。
      *
@@ -179,6 +193,19 @@ export type DynamicWorkflowRunAmendResult = {
 export type DynamicWorkflowRunCancelInitiator = "user" | "model" | {
     superseded: string;
 };
+/**
+ * 终态快照带的 report item 上限（`reports` 的长度上界）。取 256——report 条数上限从 256 提到
+ * 65,536 之前的值：报告条数不超过它的 run，快照与通知逐字节不变；更大的 run 由 `reportCount`
+ * 说出真实总数。完成通知那一节的字符预算（8000）本来也容不下更多条。
+ */
+export declare const DYNAMIC_WORKFLOW_SNAPSHOT_MAX_REPORTS = 256;
+/**
+ * 终态快照带的 report item 的字节上界（按 journal 里 `result_json` 的字节计）。取 8 MiB——
+ * 单条上限 32 KiB 时 256 条的最坏情形，所以单条上限提到 1 MiB 之后快照的内存不涨。快照只喂
+ * 完成通知，而通知每条最多展示 2,000 字符、整节 8,000 字符，8 MiB 远超它能用上的部分。
+ * 第一条总是带上，所以一条 1 MiB 的报告不会让快照一条都不带。
+ */
+export declare const DYNAMIC_WORKFLOW_SNAPSHOT_MAX_REPORT_BYTES: number;
 /**
  * run 快照：沿用 {@link WorkflowTaskSnapshot} 的形状（后台任务追踪器与通知管线按它读），
  * 只把 `output` 放宽——workflow run 的产物是脚本的顶层返回值，形状由脚本决定，不是 legacy
@@ -188,6 +215,9 @@ export type DynamicWorkflowRunCancelInitiator = "user" | "model" | {
  * `kind = "report"` 节点行——那是这些条目的持久家（`workflowRuns.reports` 只是有界的
  * memory-only 展示面）。完成通知据此在 completed / failed / cancelled 三态下一律回投：
  * 一个死在第 12 个 ask 上的 run 仍然做完了 11 个 ask 的活，捞回它正是 `report` 存在的理由。
+ * 它只带**前** {@link DYNAMIC_WORKFLOW_SNAPSHOT_MAX_REPORTS} 条、且至多
+ * {@link DYNAMIC_WORKFLOW_SNAPSHOT_MAX_REPORT_BYTES} 字节；真实总数在 `reportCount`
+ * （docs/execution-engine.md「Reading the journal」）。
  */
 export type DynamicWorkflowRunSnapshot = Omit<WorkflowTaskSnapshot, "output"> & {
     output?: unknown;
@@ -217,6 +247,12 @@ export type DynamicWorkflowRunSnapshot = Omit<WorkflowTaskSnapshot, "output"> &
      * 这里是字符串而不是 {@link ModelSelection}：读面只用来显示与原样回填，没有人按字段取值。
      */
     subagentModel?: string;
+    /**
+     * 本 run 的脚本点名的模型（journal 事件 `run-launched` 上的那张表）：脚本逐字写下的名字 →
+     * 规范串。**只在脚本点名过模型时在场**。`AmendWorkflow` 的 `resolveInput` 与 GUI「配置」据它让
+     * 同名的绑定沿用下去（docs/dynamic-workflow/launch.md「Models the script names」）。
+     */
+    modelBindings?: Record<string, string>;
     /**
      * 本 run 的脚本文件（绝对路径，journal 事件 `run-launched` 上的那一个）。**只在这个 run 记下过文件时在场**。
      *
@@ -228,14 +264,21 @@ export type DynamicWorkflowRunSnapshot = Omit<WorkflowTaskSnapshot, "output"> &
     failure?: DynamicWorkflowRunError;
     /**
      * 本 run 及其 lineage 的**活动**时长（毫秒）：本 run 的每一世加上每个前驱的每一世，世与世
-     * 之间的空档不计。完成卡的「时间」格报的就是它。
+     * 之间的空档不计（口径与理由见 docs/dynamic-workflow/transcript-and-notifications.md
+     * 「How long it took」）。完成卡的「时间」格报的就是它。
      *
      * 与 `reports` / `artifacts` 同规**只在终态在场**（`getTask` 被反复轮询，而消费者只有终态
      * 通知），且 journal 说不出话时整字段缺席——不是 0。缺席即读侧退回 `completedAt − startedAt`：
      * 那是结算它的那个进程自己看到的一世，一个更保守但永不虚报的答案。
      */
     activeDurationMs?: number;
+    /** 前 {@link DYNAMIC_WORKFLOW_SNAPSHOT_MAX_REPORTS} 条 report item，按报告顺序；零条时缺席。 */
     reports?: readonly unknown[];
+    /**
+     * 本 run 的 report 真实总条数（`count(*)`），与 `reports` 同在同缺。通知与 manifest 的
+     * `count` 读它：`reports` 被截在上限处时，`count ≠ shown` 就是「还有更多」的信号。
+     */
+    reportCount?: number;
     /**
      * 此刻停驻在这个 run 上、等主代理作答的升级问题。
      *
@@ -248,6 +291,12 @@ export type DynamicWorkflowRunSnapshot = Omit<WorkflowTaskSnapshot, "output"> &
      * 时候都能经既有观察面重新发现待答问题。零条时整字段缺席（不发空数组）。
      */
     pendingQuestions?: readonly DynamicWorkflowRunPendingQuestion[];
+    /**
+     * 本 run 的留白（{@link DynamicWorkflowRunHole}）：到达过的每一处，等着的与补过的。与
+     * `pendingQuestions` 同规——零条整字段缺席、`waiting` 从引擎的停驻表投影而不是单靠事件重放；
+     * 留白通知的发射器与 `FillWorkflowHole` 的 resolveInput 都读它。
+     */
+    holes?: readonly DynamicWorkflowRunHole[];
     /**
      * 本 run 发布的**用户面产物**，按首次出现顺序，来自
      * journal 的 `kind = "artifact"` 行——那是版本历史的持久家（`workflowRuns.artifacts` 只带
@@ -310,13 +359,30 @@ export interface DynamicWorkflowRunArtifactItem {
     sequence: number;
     siteId: string;
     ordinal: number;
-    item: unknown;
+    /** 整条 item；请求点名了 `fields` 时缺席。 */
+    item?: unknown;
+    /** 请求点名了 `fields` 时：路径 → 值，走不通的路径不在表里。 */
+    fields?: Record<string, unknown>;
 }
-/** {@link DynamicWorkflowRunPort.listArtifactItems} 的分页袋（cursor = journal sequence，严格大于）。 */
+/**
+ * {@link DynamicWorkflowRunPort.listArtifactItems} 的分页袋（cursor = journal sequence，严格大于）。
+ * 两道界的语义同 {@link DynamicWorkflowRunEventPage}：条数到 `limit`、或再加一条就超过
+ * `maxBytes` 时收尾，第一条总是带上。两者都由调用方（网关）给定，实现方精确兑现、不再钳。
+ */
 export interface DynamicWorkflowRunArtifactItemPage {
     afterSequence?: number;
-    /** 必填；调用方可传「上限 + 1」探测 hasMore，实现方不得再钳。 */
     limit: number;
+    maxBytes: number;
+    /**
+     * 只取这些字段路径（`readWorkflowArtifactField` 的规则，由 SQLite 取出），结果每条带 `fields`
+     * 而不带 `item`，`maxBytes` 按取出的字段值计。缺省 = 整条 item。
+     */
+    fields?: readonly string[];
+}
+/** 看板条目的一页。`hasMore` 由存储层判定：页之后是否还有条目。 */
+export interface DynamicWorkflowRunArtifactItemsResult {
+    items: readonly DynamicWorkflowRunArtifactItem[];
+    hasMore: boolean;
 }
 /** {@link DynamicWorkflowRunPort.readArtifact} 的返回：某个版本的全部字节。 */
 export interface DynamicWorkflowRunArtifactBytes {
@@ -372,11 +438,23 @@ export type DynamicWorkflowResolveQuestionResult = {
 export interface DynamicWorkflowRunWaitOptions {
     signal?: AbortSignal;
 }
-/** 事件日志的分页参数；cursor = journal sequence（appendEvent 单调分配）。 */
+/**
+ * 事件日志的分页参数；cursor = journal sequence（appendEvent 单调分配）。
+ *
+ * 两道界同时生效（docs/execution-engine.md「Reading the journal」）：页在条数到 `limit`、或
+ * 再加一条就会让存储里的序列化字节超过 `maxBytes` 时收尾；第一条总是带上，所以一条超过
+ * `maxBytes` 的事件自成一页。实现方缺省两者时各取一个有界的默认值——事件日志一页永远有界。
+ */
 export interface DynamicWorkflowRunEventPage {
     /** 只取 sequence 严格大于该值的事件；缺省从头取。 */
     afterSequence?: number;
     limit?: number;
+    maxBytes?: number;
+}
+/** 事件日志的一页。`hasMore` 由存储层判定：页之后是否还有事件。 */
+export interface DynamicWorkflowRunEventsResult {
+    events: DynamicWorkflowRunEvent[];
+    hasMore: boolean;
 }
 /**
  * 一条 run 事件的**协议形态**：sequence + 事件种类 + JSON 载荷。
@@ -449,16 +527,18 @@ export interface DynamicWorkflowRunPort {
      */
     amend?(request: DynamicWorkflowRunAmendRequest, options?: DynamicWorkflowRunSubmitOptions): Promise<DynamicWorkflowRunAmendResult>;
     /**
-     * run 自己并发上界的天花板（`max(1, min(16, availableParallelism() − 2))`，每进程一个值）。同步、无副作用。
+     * 默认并发 D（docs/dynamic-workflow/concurrency.md「Two bounds on a run」：
+     * `max(4, min(16, availableParallelism() − 2))`，每进程一个值）。同步、无副作用。它是**起点**
+     * 不是上限：没设 `max_concurrency` 的 run 跑在它上面，设了的高于低于都行。
      *
-     * 工具层的两个读者：`CreateWorkflow` / `AmendWorkflow` 的 `resolveInput` 把模型给的
-     * `max_concurrency` 钳到它之下（确认窗显示的必须是将要生效的值），`GetWorkflowRun` 据它决定
-     * 一个 run 的上界是否值得一提。**可选成员**（消费方 `typeof` 探测）：端口 stub 不必为它陪跑，
-     * 缺席时工具层不钳、原样下传（端口实现自己还会钳一次）。
+     * 工具层的读者：确认窗与回话（「（默认）」「默认 N」）、`AmendWorkflow` 的同值判定（`null` 要
+     * 折算成数才比得了），以及 `GetWorkflowRun` 据它决定一个 run 的上界是否值得一提（≠ 默认才提）。
+     * **可选成员**（消费方 `typeof` 探测）：端口 stub 不必为它陪跑，缺席时工具层只是不知道默认是几。
      */
-    concurrencyCeiling?(): number;
+    defaultConcurrency?(): number;
     /**
-     * 就地改一个**在飞** run 自己的并发上界：同一个 runId、不铸后继、不 supersede、不导入缓存、在飞 ask 一个不丢。
+     * 就地改一个**在飞** run 自己的并发上界（docs/dynamic-workflow/concurrency.md「Retuning a live
+     * run」）：同一个 runId、不铸后继、不 supersede、不导入缓存、在飞 ask 一个不丢。
      *
      * 与 {@link amend} 并列而非合并：修订换的是**脚本**，代价是停下前驱、铸新 run、从缓存重放；
      * 而「只把这个 run 调慢一点」不该付那笔账。两个调用方（`AmendWorkflow` 的 handler 与 GUI 的
@@ -481,7 +561,7 @@ export interface DynamicWorkflowRunPort {
      */
     cancel(runId: string, initiator?: DynamicWorkflowRunCancelInitiator): Promise<boolean>;
     /** 按 cursor 翻取事件日志；越界 cursor 返回空页而非报错。 */
-    listEvents(runId: string, options: DynamicWorkflowRunEventPage): Promise<DynamicWorkflowRunEvent[]>;
+    listEvents(runId: string, options: DynamicWorkflowRunEventPage): Promise<DynamicWorkflowRunEventsResult>;
     /**
      * 按项目（cwd）枚举 run，最近更新的在前。服务 `ListWorkflowRuns` 工具。
      *
@@ -554,6 +634,19 @@ export interface DynamicWorkflowRunPort {
      * 应答面全员陪跑；对消费方「端口缺席」与「方法缺席」是同一个业务失败。
      */
     resolveQuestion?(qid: string, answer: string): Promise<DynamicWorkflowResolveQuestionResult>;
+    /**
+     * 给一个正在等的留白补上函数体（docs/dynamic-workflow/launch.md「The `FillWorkflowHole` tool」；
+     * 引擎文档「The fill service's checks」）。服务 `FillWorkflowHole` 工具。
+     *
+     * 实现侧一条龙：读 run 存档的脚本 → 按站点 id 找到留白调用、把函数体拼成它的最后一个实参 →
+     * 整体编译（诊断 → `compile_failed`，坐标按 `inFill` 分到函数体内 / 脚本）→ 站点稳定性检查
+     * （→ `fill_ids_unstable`）→ 引擎 `fillHole`（→ `hole_not_waiting`）→ 把 run 的草稿就地改写成
+     * 有效脚本。**拒绝即零副作用**：留白照旧在等。
+     *
+     * **可选成员**（消费方 `typeof` 探测），理由同 {@link resolveQuestion}：端口 stub 不必为它陪跑；
+     * 对消费方「端口缺席」与「方法缺席」是同一个业务失败（本会话不能补全留白）。
+     */
+    fillHole?(request: DynamicWorkflowRunFillHoleRequest): Promise<FillWorkflowHoleResult>;
     /**
      * 本 run 的用户面产物清单（journal `kind = "artifact"` 行按 id 分组、版本升序）。UI 冷恢复与中枢详情的 durable 读法。
      * 未知 runId 返回 `undefined`。**可选成员**，理由同 {@link listRuns}（journal 带产物
@@ -564,7 +657,7 @@ export interface DynamicWorkflowRunPort {
      * 喂给某个预置产物的 `report` 条目，按 journal sequence 升序分页（看板的取数面）。
      * 越界 cursor 返回空页而非报错。可选成员，理由同 {@link listArtifacts}。
      */
-    listArtifactItems?(runId: string, artifactId: string, page: DynamicWorkflowRunArtifactItemPage): Promise<readonly DynamicWorkflowRunArtifactItem[]>;
+    listArtifactItems?(runId: string, artifactId: string, page: DynamicWorkflowRunArtifactItemPage): Promise<DynamicWorkflowRunArtifactItemsResult>;
     /**
      * 读某个产物版本的字节：**先**在 journal 里确认 `(runId, artifactId, version)` 有一行
      * `completed` 记录，再按行上的 `uri` 经 tool-artifact store 取——调用方传来的任何 id 都
@@ -726,6 +819,7 @@ export interface DynamicWorkflowRunProviderStop {
 }
 export type * from "./dynamic-workflow-run-roster.port.js";
 export type * from "./dynamic-workflow-run-retune.port.js";
+export type * from "./dynamic-workflow-run-hole.port.js";
 export type * from "./dynamic-workflow-run-workspace.port.js";
 /** 单 run 详情：共同截面 + 进度 + 情势截面 + 按终态分叉的产物 / 失败。 */
 export interface DynamicWorkflowRunDetail extends DynamicWorkflowRunSummary {
@@ -741,6 +835,8 @@ export interface DynamicWorkflowRunDetail extends DynamicWorkflowRunSummary {
      * 很少设置的字段加宽。
      */
     subagentModel?: string;
+    /** 本 run 的脚本点名的模型，语义同 {@link DynamicWorkflowRunSnapshot.modelBindings}。 */
+    modelBindings?: Record<string, string>;
     /**
      * 本 run 的脚本文件，语义同 {@link DynamicWorkflowRunSnapshot.scriptPath}：只在记下过文件时
      * 在场。`GetWorkflowRun` 据它在 `<amendable>` 里把下一步说成「就地编辑这个文件」。
@@ -788,6 +884,11 @@ export interface DynamicWorkflowRunDetail extends DynamicWorkflowRunSummary {
      * 缺了它，那两处承诺都会指向一个什么都不返回的工具。
      */
     pendingQuestions?: readonly DynamicWorkflowRunPendingQuestion[];
+    /**
+     * 本 run 的留白，与 {@link DynamicWorkflowRunSnapshot.holes} **同源同投影**（零条整字段缺席），
+     * 只是换了一条读面：本字段服务 `GetWorkflowRun`——留白通知丢失后模型侧唯一的发现面。
+     */
+    holes?: readonly DynamicWorkflowRunHole[];
     /**
      * 本 run 的用户面产物（任意状态都附；journal-backed，与 {@link DynamicWorkflowRunSnapshot.artifacts}
      * 同源）。`GetWorkflowRun` 据此告诉模型「这些已经以卡片呈现给用户了，按标题引用即可」。

package/node_modules/@dcode/contracts/dist/interfaces/dynamic-workflow-run.port.js

@@ -1,6 +1,19 @@
 // ============================================================
 // Dynamic Workflow Run Port - dwf 引擎 run 的提交 / 观察 / 取消边界
 // ============================================================
+/**
+ * 终态快照带的 report item 上限（`reports` 的长度上界）。取 256——report 条数上限从 256 提到
+ * 65,536 之前的值：报告条数不超过它的 run，快照与通知逐字节不变；更大的 run 由 `reportCount`
+ * 说出真实总数。完成通知那一节的字符预算（8000）本来也容不下更多条。
+ */
+export const DYNAMIC_WORKFLOW_SNAPSHOT_MAX_REPORTS = 256;
+/**
+ * 终态快照带的 report item 的字节上界（按 journal 里 `result_json` 的字节计）。取 8 MiB——
+ * 单条上限 32 KiB 时 256 条的最坏情形，所以单条上限提到 1 MiB 之后快照的内存不涨。快照只喂
+ * 完成通知，而通知每条最多展示 2,000 字符、整节 8,000 字符，8 MiB 远超它能用上的部分。
+ * 第一条总是带上，所以一条 1 MiB 的报告不会让快照一条都不带。
+ */
+export const DYNAMIC_WORKFLOW_SNAPSHOT_MAX_REPORT_BYTES = 8 * 1024 * 1024;
 /**
  * run 事件载荷的界。**协议边界上的所有载荷有界**，而引擎的事件
  * 里有两个天然无界的字段：`actor-created` 的 `persona.system`（整段 system prompt）与

package/node_modules/@dcode/contracts/dist/interfaces/index.d.ts

@@ -1,3 +1,4 @@
+export * from "./provider-endpoint-routing.port.js";
 export * from "./execution.port.js";
 export * from "./file-system.port.js";
 export * from "./context-source.port.js";

package/node_modules/@dcode/contracts/dist/interfaces/index.js

@@ -1,4 +1,5 @@
 // Ports - interface definitions for adapters
+export * from "./provider-endpoint-routing.port.js";
 export * from "./execution.port.js";
 export * from "./file-system.port.js";
 export * from "./context-source.port.js";