@sunshaobei/dsh-workflow 0.0.0-stage → 2.1.2

package/vendor/dynamic-workflow/engine/artifact-spec.d.ts

@@ -0,0 +1,26 @@
+/**
+ * 预置产物 spec 的形状校验。
+ *
+ * ⚠ 术语：artifact = **用户面产物**（脚本发布给用户看的看板），不是 `RunSettlement.artifact`
+ * 那个顶层返回值。
+ *
+ * 为什么校验在**引擎核心**而不是 driver：预置声明根本不过 driver（它没有可执行的效应），
+ * 而一个形状不合法的 spec 必须在落 journal 之前被拦下——journal 里的记录是投影与冷恢复的
+ * 唯一真相，一条画不出来的 spec 落了库就会在每个读面上重新炸一次。
+ *
+ * 为什么是手写而不是 zod：本包零运行时依赖（facade / 编译 / 引擎全部只靠 typescript），
+ * 而 spec 的形状小到一屏。加一个 schema 库来校验四个对象，代价是把整条纯包的依赖前提改掉。
+ *
+ * 返回**人可读的一句话**而不是 boolean：这条消息会经 `ArtifactSpecInvalid` 落进 run 的
+ * failure_json，读者（模型或作者）要据它改脚本，"invalid spec" 帮不上任何忙。
+ */
+import type { ArtifactPresetOp } from "../facade/registry.js";
+/** 一条不合法的理由；`undefined` 即通过。 */
+type ArtifactSpecProblem = string | undefined;
+/**
+ * 校验一个预置 spec。`op` 决定必填字段，公共部分（title / description 的长度）四种都查。
+ * 通过的 spec 保证：是普通对象、必填字段在场且形状正确、规范化后不超 8KB。
+ */
+export declare function validateArtifactSpec(op: ArtifactPresetOp, spec: unknown): ArtifactSpecProblem;
+export {};
+//# sourceMappingURL=artifact-spec.d.ts.map

package/vendor/dynamic-workflow/engine/artifact-spec.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"artifact-spec.d.ts","sourceRoot":"","sources":["../../src/engine/artifact-spec.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAGH,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAC;AAG9D,gCAAgC;AAChC,KAAK,mBAAmB,GAAG,MAAM,GAAG,SAAS,CAAC;AAE9C;;;GAGG;AACH,wBAAgB,oBAAoB,CAAC,EAAE,EAAE,gBAAgB,EAAE,IAAI,EAAE,OAAO,GAAG,mBAAmB,CAgB7F"}

package/vendor/dynamic-workflow/engine/artifact-spec.js

@@ -0,0 +1,173 @@
+/**
+ * 预置产物 spec 的形状校验。
+ *
+ * ⚠ 术语：artifact = **用户面产物**（脚本发布给用户看的看板），不是 `RunSettlement.artifact`
+ * 那个顶层返回值。
+ *
+ * 为什么校验在**引擎核心**而不是 driver：预置声明根本不过 driver（它没有可执行的效应），
+ * 而一个形状不合法的 spec 必须在落 journal 之前被拦下——journal 里的记录是投影与冷恢复的
+ * 唯一真相，一条画不出来的 spec 落了库就会在每个读面上重新炸一次。
+ *
+ * 为什么是手写而不是 zod：本包零运行时依赖（facade / 编译 / 引擎全部只靠 typescript），
+ * 而 spec 的形状小到一屏。加一个 schema 库来校验四个对象，代价是把整条纯包的依赖前提改掉。
+ *
+ * 返回**人可读的一句话**而不是 boolean：这条消息会经 `ArtifactSpecInvalid` 落进 run 的
+ * failure_json，读者（模型或作者）要据它改脚本，"invalid spec" 帮不上任何忙。
+ */
+import { ARTIFACT_CAPS } from "../facade/artifact-caps.js";
+import { canonicalJson } from "./hash.js";
+/**
+ * 校验一个预置 spec。`op` 决定必填字段，公共部分（title / description 的长度）四种都查。
+ * 通过的 spec 保证：是普通对象、必填字段在场且形状正确、规范化后不超 8KB。
+ */
+export function validateArtifactSpec(op, spec) {
+    if (!isPlainObject(spec))
+        return `${op} spec must be an object literal, got ${describe(spec)}`;
+    const common = checkOptions(spec);
+    if (common !== undefined)
+        return common;
+    const shape = checkShape(op, spec);
+    if (shape !== undefined)
+        return shape;
+    // 体积上限最后查：先给出形状上的具体错误，再谈大小——一个既畸形又过大的 spec，作者要先
+    // 知道它畸形在哪。
+    const bytes = utf8ByteLength(canonicalJson(spec));
+    if (bytes > ARTIFACT_CAPS.maxSpecSerializedBytes) {
+        return `${op} spec is ${bytes} bytes serialized, over the ${ARTIFACT_CAPS.maxSpecSerializedBytes}-byte limit`;
+    }
+    return undefined;
+}
+function checkShape(op, spec) {
+    if (op === "chart") {
+        const x = checkField(spec.x, "x");
+        if (x !== undefined)
+            return x;
+        const y = spec.y;
+        if (Array.isArray(y)) {
+            if (y.length === 0)
+                return "chart spec y is an empty array; give it at least one series";
+            for (const [index, entry] of y.entries()) {
+                const problem = checkField(entry, `y[${index}]`);
+                if (problem !== undefined)
+                    return problem;
+            }
+        }
+        else {
+            const problem = checkField(y, "y");
+            if (problem !== undefined)
+                return problem;
+        }
+        if (spec.type !== undefined && !["line", "bar", "scatter"].includes(String(spec.type))) {
+            return `chart spec type must be "line", "bar" or "scatter", got ${describe(spec.type)}`;
+        }
+        if (spec.scale !== undefined && !["linear", "log"].includes(String(spec.scale))) {
+            return `chart spec scale must be "linear" or "log", got ${describe(spec.scale)}`;
+        }
+        if (spec.baseline !== undefined)
+            return checkField(spec.baseline, "baseline");
+        return undefined;
+    }
+    if (op === "table") {
+        const columns = checkFieldList(spec.columns, "columns");
+        if (columns !== undefined)
+            return columns;
+        if (spec.key !== undefined && !isNonEmptyString(spec.key)) {
+            return "table spec key must be a non-empty string (the field that identifies a row)";
+        }
+        return undefined;
+    }
+    if (op === "metrics")
+        return checkFieldList(spec.metrics, "metrics");
+    // board
+    if (!isNonEmptyString(spec.key))
+        return "board spec key must be a non-empty string (the field that identifies a card)";
+    if (!isNonEmptyString(spec.status)) {
+        return "board spec status must be a non-empty string (the field that picks a card's column)";
+    }
+    if (!Array.isArray(spec.columns) || spec.columns.length === 0) {
+        return "board spec columns must be a non-empty array of strings (the column order)";
+    }
+    for (const [index, column] of spec.columns.entries()) {
+        if (!isNonEmptyString(column))
+            return `board spec columns[${index}] must be a non-empty string`;
+    }
+    // cardTitle 是**字段名**（哪个字段当卡片标题），与 ArtifactOptions.title（看板自己的标题）
+    // 是两回事——它们之前撞在同一个键上，改名正是为了让一块板能同时说出两者。
+    if (spec.cardTitle !== undefined && !isNonEmptyString(spec.cardTitle)) {
+        return "board spec cardTitle must be a non-empty string (the field used as the card title)";
+    }
+    if (spec.detail !== undefined)
+        return checkFieldList(spec.detail, "detail");
+    return undefined;
+}
+/** 公共的展示元数据（`ArtifactOptions`）：类型与长度。 */
+function checkOptions(spec) {
+    if (spec.title !== undefined) {
+        if (typeof spec.title !== "string")
+            return `spec title must be a string, got ${describe(spec.title)}`;
+        if (spec.title.length > ARTIFACT_CAPS.maxTitleLength) {
+            return `spec title is ${spec.title.length} characters, over the ${ARTIFACT_CAPS.maxTitleLength} limit`;
+        }
+    }
+    if (spec.description !== undefined) {
+        if (typeof spec.description !== "string") {
+            return `spec description must be a string, got ${describe(spec.description)}`;
+        }
+        if (spec.description.length > ARTIFACT_CAPS.maxDescriptionLength) {
+            return `spec description is ${spec.description.length} characters, over the ` +
+                `${ARTIFACT_CAPS.maxDescriptionLength} limit`;
+        }
+    }
+    if (spec.primary !== undefined && typeof spec.primary !== "boolean") {
+        return `spec primary must be a boolean, got ${describe(spec.primary)}`;
+    }
+    return undefined;
+}
+/** 一个非空的 `ArtifactField` 列表。 */
+function checkFieldList(value, where) {
+    if (!Array.isArray(value) || value.length === 0) {
+        return `spec ${where} must be a non-empty array of fields ({ field: "…" })`;
+    }
+    for (const [index, entry] of value.entries()) {
+        const problem = checkField(entry, `${where}[${index}]`);
+        if (problem !== undefined)
+            return problem;
+    }
+    return undefined;
+}
+/** 一个 `ArtifactField`：`field` 必须是非空字符串（点路径），label / unit 可选。 */
+function checkField(value, where) {
+    if (!isPlainObject(value))
+        return `spec ${where} must be { field: "…" }, got ${describe(value)}`;
+    if (!isNonEmptyString(value.field)) {
+        return `spec ${where}.field must be a non-empty string (a dot path into the item, e.g. "timing.after")`;
+    }
+    for (const key of ["label", "unit"]) {
+        if (value[key] !== undefined && typeof value[key] !== "string") {
+            return `spec ${where}.${key} must be a string, got ${describe(value[key])}`;
+        }
+    }
+    return undefined;
+}
+function isPlainObject(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function isNonEmptyString(value) {
+    return typeof value === "string" && value.trim() !== "";
+}
+/** 出错文案里的实得值描述（不打印整个对象——一个 8KB 的 spec 会把 failure_json 塞满）。 */
+function describe(value) {
+    if (value === null)
+        return "null";
+    if (Array.isArray(value))
+        return `array (${value.length} items)`;
+    if (typeof value === "object")
+        return "object";
+    if (typeof value === "string")
+        return JSON.stringify(value.slice(0, 40));
+    return String(value);
+}
+/** UTF-8 字节数（与 report 上限同一把尺）。 */
+function utf8ByteLength(value) {
+    return new TextEncoder().encode(value).length;
+}

package/vendor/dynamic-workflow/engine/ask-observation-types.d.ts

@@ -0,0 +1,54 @@
+/**
+ * driver 对一条 ask 的**观察**词汇表：用量（{@link AskStats}）与进度（{@link AskProgress}）——
+ * 同一次 turn 解析上报的两半，一半是账，一半是「还在动吗」。
+ *
+ * 从 types.ts 拆出的原因与 imported-cache-types.ts 同一条：那份契约已到 oxlint 的 max-lines
+ * 上限。公开面不变——types.ts 原地再导出这里的每一个名字，导入路径仍是 `./types.js`。
+ */
+/** driver 每完成一次 ask 上报的用量统计。 */
+export interface AskStats {
+    tokens: number;
+    toolCalls: number;
+    turns: number;
+    /**
+     * 其中**看或动了外部世界**的调用数：读文件、跑命令、访问网络。
+     * 不含只把结果或问题交回引擎的协议工具（`submit_result`、`escalate`），所以一条只作答的 typed ask
+     * 这里是 0——那样的 ask 是**纯**的，只依赖指令与转录前缀，导入缓存关闭之后仍可从缓存结算。
+     * 老 journal 行没有这个键，一律按「碰过」处理（保守）。
+     */
+    worldToolCalls?: number;
+}
+/**
+ * `node-queued` 上 `instructionsHead` 的字符上限（240）。够一两句把这次 ask 交代清楚，
+ * 又不至于让事件表长出一份指令副本——完整指令在 `dwf_node.input_json` 那一侧。
+ */
+export declare const INSTRUCTIONS_HEAD_MAX_CHARS = 240;
+/** `node-progress` 上 `lastTool.name` 的字符上限（64）：工具名，不是描述。 */
+export declare const LAST_TOOL_NAME_MAX_CHARS = 64;
+/**
+ * `node-progress` 上 `lastTool.target` 的字符上限（120）：一条给人看的线索（文件路径 /
+ * 命令头），不是入参本身——入参可以装下任何东西，而这条事件会被主代理读、被 GUI 画。
+ */
+export declare const LAST_TOOL_TARGET_MAX_CHARS = 120;
+/**
+ * 最近一次被观察到的工具调用（{@link AskProgress} 的 `lastTool`）。
+ * `target` 是给人看的**线索**，不是入参：文件类工具给路径，Bash 给命令头，认不出就缺席。
+ */
+export interface AskLastTool {
+    /** 工具名，≤ {@link LAST_TOOL_NAME_MAX_CHARS}。 */
+    name: string;
+    /** 简短目标，≤ {@link LAST_TOOL_TARGET_MAX_CHARS}；无从判断时缺席（不合成占位串）。 */
+    target?: string;
+}
+/**
+ * 一条 ask 在**turn 解析那一刻**的进度。
+ * 与 {@link AskStats} 是同一次 driver 回报的两半：stats 是账（token），progress 是「还在动吗」。
+ */
+export interface AskProgress {
+    /** 本 ask 内已解析的 turn 数，从 1 起（nudge 轮计数；repair 轮不计——它们不结束 turn）。 */
+    turn: number;
+    /** 本 ask 内累计的工具调用数，与 {@link AskStats.toolCalls} 同一个计数器。 */
+    toolCalls: number;
+    lastTool?: AskLastTool;
+}
+//# sourceMappingURL=ask-observation-types.d.ts.map

package/vendor/dynamic-workflow/engine/ask-observation-types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ask-observation-types.d.ts","sourceRoot":"","sources":["../../src/engine/ask-observation-types.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,gCAAgC;AAChC,MAAM,WAAW,QAAQ;IACvB,MAAM,EAAE,MAAM,CAAC;IACf,SAAS,EAAE,MAAM,CAAC;IAClB,KAAK,EAAE,MAAM,CAAC;IACd;;;;;OAKG;IACH,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB;AAED;;;GAGG;AACH,eAAO,MAAM,2BAA2B,MAAM,CAAC;AAE/C,4DAA4D;AAC5D,eAAO,MAAM,wBAAwB,KAAK,CAAC;AAE3C;;;GAGG;AACH,eAAO,MAAM,0BAA0B,MAAM,CAAC;AAE9C;;;GAGG;AACH,MAAM,WAAW,WAAW;IAC1B,8CAA8C;IAC9C,IAAI,EAAE,MAAM,CAAC;IACb,iEAAiE;IACjE,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED;;;GAGG;AACH,MAAM,WAAW,WAAW;IAC1B,kEAAkE;IAClE,IAAI,EAAE,MAAM,CAAC;IACb,2DAA2D;IAC3D,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,CAAC,EAAE,WAAW,CAAC;CACxB"}

package/vendor/dynamic-workflow/engine/ask-observation-types.js

@@ -0,0 +1,19 @@
+/**
+ * driver 对一条 ask 的**观察**词汇表：用量（{@link AskStats}）与进度（{@link AskProgress}）——
+ * 同一次 turn 解析上报的两半，一半是账，一半是「还在动吗」。
+ *
+ * 从 types.ts 拆出的原因与 imported-cache-types.ts 同一条：那份契约已到 oxlint 的 max-lines
+ * 上限。公开面不变——types.ts 原地再导出这里的每一个名字，导入路径仍是 `./types.js`。
+ */
+/**
+ * `node-queued` 上 `instructionsHead` 的字符上限（240）。够一两句把这次 ask 交代清楚，
+ * 又不至于让事件表长出一份指令副本——完整指令在 `dwf_node.input_json` 那一侧。
+ */
+export const INSTRUCTIONS_HEAD_MAX_CHARS = 240;
+/** `node-progress` 上 `lastTool.name` 的字符上限（64）：工具名，不是描述。 */
+export const LAST_TOOL_NAME_MAX_CHARS = 64;
+/**
+ * `node-progress` 上 `lastTool.target` 的字符上限（120）：一条给人看的线索（文件路径 /
+ * 命令头），不是入参本身——入参可以装下任何东西，而这条事件会被主代理读、被 GUI 画。
+ */
+export const LAST_TOOL_TARGET_MAX_CHARS = 120;

package/vendor/dynamic-workflow/engine/cached-ask-facts.d.ts

@@ -0,0 +1,28 @@
+/**
+ * ask 的**出生事实**：`node-queued` 带的那几样，以及缓存命中的 `node-settled` 重发的同一份
+ * （types.ts 的 `node-settled`；docs/execution-engine.md「Events」）。
+ *
+ * 从 scheduler.ts 拆出（oxlint max-lines 上限 400 行）。任务摘要的规则也搬到这里：两条出生事件
+ * 带的必须是逐字同一个串，同一个函数算就不会漂。
+ */
+import type { ImportedActorState } from "./imported-cache.js";
+import { type ActorRef } from "./types.js";
+/** 缓存命中的 ask 结算在 `{type, instance, outcome, cached, error?}` 之外多带的键。 */
+export interface CachedAskFacts {
+    kind: "ask";
+    actor: ActorRef;
+    actorSeq: number;
+    instructionsHead?: string;
+    sourceSessionId?: string;
+}
+/**
+ * 一次缓存命中的出生事实。**在命中判定的那一刻取**：`sourceSessionId` 读的是那一刻的导入消费态
+ * （{@link ImportedActorState.sourceSessionAt}），而事件本身可能被结算次序闸推迟。
+ */
+export declare function cachedAskFacts(actor: ActorRef, seq: number, instructions: string, imported: ImportedActorState | undefined): CachedAskFacts;
+/**
+ * 作者指令的开头（{@link INSTRUCTIONS_HEAD_MAX_CHARS} 个字符，去两端空白，**不加省略号**）。
+ * 空指令返回 undefined：缺席的键比一个空串诚实——读面据此退回「不知道它被交代了什么」。
+ */
+export declare function headOfInstructions(instructions: string): string | undefined;
+//# sourceMappingURL=cached-ask-facts.d.ts.map

package/vendor/dynamic-workflow/engine/cached-ask-facts.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cached-ask-facts.d.ts","sourceRoot":"","sources":["../../src/engine/cached-ask-facts.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,qBAAqB,CAAC;AAC9D,OAAO,EAA+B,KAAK,QAAQ,EAAE,MAAM,YAAY,CAAC;AAExE,wEAAwE;AACxE,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,KAAK,CAAC;IACZ,KAAK,EAAE,QAAQ,CAAC;IAChB,QAAQ,EAAE,MAAM,CAAC;IACjB,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,eAAe,CAAC,EAAE,MAAM,CAAC;CAC1B;AAED;;;GAGG;AACH,wBAAgB,cAAc,CAC5B,KAAK,EAAE,QAAQ,EACf,GAAG,EAAE,MAAM,EACX,YAAY,EAAE,MAAM,EACpB,QAAQ,EAAE,kBAAkB,GAAG,SAAS,GACvC,cAAc,CAUhB;AAED;;;GAGG;AACH,wBAAgB,kBAAkB,CAAC,YAAY,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAM3E"}

package/vendor/dynamic-workflow/engine/cached-ask-facts.js

@@ -0,0 +1,35 @@
+/**
+ * ask 的**出生事实**：`node-queued` 带的那几样，以及缓存命中的 `node-settled` 重发的同一份
+ * （types.ts 的 `node-settled`；docs/execution-engine.md「Events」）。
+ *
+ * 从 scheduler.ts 拆出（oxlint max-lines 上限 400 行）。任务摘要的规则也搬到这里：两条出生事件
+ * 带的必须是逐字同一个串，同一个函数算就不会漂。
+ */
+import { INSTRUCTIONS_HEAD_MAX_CHARS } from "./types.js";
+/**
+ * 一次缓存命中的出生事实。**在命中判定的那一刻取**：`sourceSessionId` 读的是那一刻的导入消费态
+ * （{@link ImportedActorState.sourceSessionAt}），而事件本身可能被结算次序闸推迟。
+ */
+export function cachedAskFacts(actor, seq, instructions, imported) {
+    const instructionsHead = headOfInstructions(instructions);
+    const sourceSessionId = imported?.sourceSessionAt(seq);
+    return {
+        kind: "ask",
+        actor,
+        actorSeq: seq,
+        ...(instructionsHead === undefined ? {} : { instructionsHead }),
+        ...(sourceSessionId === undefined ? {} : { sourceSessionId }),
+    };
+}
+/**
+ * 作者指令的开头（{@link INSTRUCTIONS_HEAD_MAX_CHARS} 个字符，去两端空白，**不加省略号**）。
+ * 空指令返回 undefined：缺席的键比一个空串诚实——读面据此退回「不知道它被交代了什么」。
+ */
+export function headOfInstructions(instructions) {
+    const trimmed = instructions.trim();
+    if (trimmed.length === 0)
+        return undefined;
+    return trimmed.length <= INSTRUCTIONS_HEAD_MAX_CHARS
+        ? trimmed
+        : trimmed.slice(0, INSTRUCTIONS_HEAD_MAX_CHARS);
+}

package/vendor/dynamic-workflow/engine/concurrency.d.ts

@@ -0,0 +1,151 @@
+/**
+ * 自适应并发控制器：一个 provider key 上的纯 AIMD 状态机。
+ *
+ * 纯包纪律：不读时钟、不做 I/O——`now`（ms since epoch）一律由调用方传入；本类只回答
+ * 「cap 现在是多少、能不能准入、这次信号让 cap 变了没有」。谁喂信号、谁排队（bootstrap 的进程级
+ * 治理器）都在包外。
+ *
+ * 度量单位是**模型请求**（每一次尝试）：`inFlight` = 已准入、尚未 release 的请求数。
+ * 没有 ask 级计数——一个子代理同时只有一个请求在飞，「≤ N 个请求」与「≤ N 个子代理在跑」等价。
+ *
+ * 批次阻尼靠 **epoch**：每次准入记下当时的 epoch，每次限流裁决 epoch += 1。一个 429 只在
+ * 它的请求是在**当前** cap 下发出（epoch 相同）时才评价当前 cap；旧 epoch 的 429 评价的是一个已被
+ * 砍掉的 cap，只清 streak、刷新 cooldown。成功同理：只有当前 epoch 的成功计入 streak。
+ *
+ * 信号方法都返回本次信号引起的 cap 变化列表（通常 0 或 1 条；空闲重置紧接着一次限流时会是 2 条），
+ * 调用方原样扇出成 `concurrency-changed` 事件。
+ */
+import type { ConcurrencyChange, ConcurrencyChangeReason } from "./types.js";
+/**
+ * 限流即 `cap = max(FLOOR, floor(cap × 0.75))`（系数从 0.5 改为 0.75）：
+ * 减半对「只多了一两个」的越界反应过猛——闸门是请求级的，一次 429 说明 cap 高了，很少说明高了一倍。
+ */
+export declare const CONCURRENCY_DECREASE_FACTOR = 0.75;
+/** 加性递增步长。 */
+export declare const CONCURRENCY_INCREASE_STEP = 1;
+/**
+ * 每 +1 需要的连续成功模型请求数 K。只有一档。该值从 40 降到 4：
+ * 探测失败的代价只是一个请求撞一次 429 然后退回 `lastGood`（已证明可用的水位），不值得用 40 次
+ * 成功去换一次试探。
+ */
+export declare const CONCURRENCY_INCREASE_AFTER_SUCCESSES = 4;
+/** 永远至少有一个探针在跑。 */
+export declare const CONCURRENCY_FLOOR = 1;
+/** 某 key 空闲这么久（且无在飞）后遗忘学到的 cap，回起点 `initial`（决策 20）。 */
+export declare const CONCURRENCY_IDLE_RESET_MS = 300000;
+/** 会令 cap 减少的限流类原因。 */
+export type ConcurrencyThrottleReason = Extract<ConcurrencyChangeReason, "rate_limited" | "provider_overloaded" | "offpeak_queued">;
+/** 控制器的只读快照（供测试断言与治理器投影 run 头的 `concurrency`）。 */
+export interface ConcurrencyControllerSnapshot {
+    readonly key: string;
+    /** 起点与空闲重置的落点：默认并发 D。 */
+    readonly initial: number;
+    /** 自动增长的上界（治理器定，可随时挪动；恒 ≥ initial）。 */
+    readonly growthLimit: number;
+    readonly cap: number;
+    /** 限流裁决计数；准入时发给请求，请求结束时带回来比对。 */
+    readonly epoch: number;
+    readonly inFlight: number;
+    readonly waiters: number;
+    readonly successStreak: number;
+    readonly cooldownUntil?: number;
+    readonly lastRequestAt?: number;
+    readonly lastGood?: number;
+    readonly lastBad?: number;
+    /** 最近一次被拒（不论 epoch）的时刻；五分钟内有它就不起跳（{@link ConcurrencyController.seed}）。 */
+    readonly lastThrottledAt?: number;
+}
+export declare class ConcurrencyController {
+    readonly key: string;
+    readonly initial: number;
+    private cap;
+    private growthLimit_;
+    private epoch;
+    private inFlight;
+    private waiters_;
+    private successStreak;
+    private cooldownUntil?;
+    private lastRequestAt?;
+    private lastGood?;
+    private lastBad?;
+    private lastThrottledAt?;
+    /**
+     * @param key provider key（`${providerId}/${modelId}`），只用于填进 change 事件——控制器自己
+     *   对它无感。放在构造参数而不是每次信号传入：一个控制器只服务一个 key，这是身份不是参数。
+     * @param initial 默认并发 D（docs/dynamic-workflow/concurrency.md「Two bounds on a run」）：cap 的
+     *   起点，也是空闲重置的落点。它**不是**上界。
+     * @param growthLimit 自动增长的上界；缺省即 `initial`（只回落、不越过起点的旧行为）。治理器按
+     *   `max(2D, 用过这个 key 的在飞 run 的最大上界)` 给出并随时经 {@link setGrowthLimit} 挪动。
+     */
+    constructor(key: string, initial: number, growthLimit?: number);
+    snapshot(): ConcurrencyControllerSnapshot;
+    /**
+     * 闸门（准入条件）：在飞请求数低于 cap 且不在 Retry-After 冷却中。纯查询，不做空闲重置——
+     * 调用方（治理器）在准入路径上先调 {@link observe}（准入也是一次「信号」，空闲一小时后的第一个
+     * run 要立刻从起点 `initial` 起步，决策 20）。
+     */
+    canAdmit(now: number): boolean;
+    /** 只做空闲重置检查的「空信号」（准入前、observer 放行前用）。 */
+    observe(now: number): ConcurrencyChange[];
+    /**
+     * 一个请求被准入：`inFlight++`、刷新 `lastRequestAt`，返回它所属的 epoch（请求结束时带回来）。
+     * 不做空闲重置——调用方已在 {@link observe} 里做过；这里若再做，一个刚被 observe 判定「不空闲」
+     * 的准入不可能变成空闲。
+     */
+    admitted(now: number): number;
+    /**
+     * 一个请求成功结束：`inFlight--`；只有**当前 epoch** 的成功使
+     * `successStreak++`——旧 epoch 的成功证明的是旧 cap 下退避压低后的负载，不是新 cap 可以更高。
+     * `successStreak ≥ K` 即**证明**当前 cap 可用：`lastGood = max(lastGood, cap)`（决策 40：只有
+     * 完成的 streak 能设 lastGood，减少 cap 不能）。再满足有等待者 **且** `cap < growthLimit` → +1。
+     * 无等待者时 streak 照累积但不兑现（决策 15）。
+     */
+    succeeded(now: number, epoch: number): ConcurrencyChange[];
+    /**
+     * 被限流/过载。一律 `inFlight--`、清 streak、带 Retry-After 则把 cooldown
+     * 推到更晚者。
+     *
+     * 只有 `epoch === 当前 epoch` 的 429 才动 cap：它是在当前 cap 下发出的请求，是对当前 cap 的评价；
+     * 旧 epoch 的 429 忽略（不发事件）。当前 epoch 的分两档：在 `lastGood` **之上**探测被限流 → 退回
+     * `lastGood`（记 `lastBad`，不按系数减）；否则（`lastGood` 缺席或 `cap ≤ lastGood`：墙下移了）→
+     * `cap = max(FLOOR, floor(cap × 0.75))`，记 `lastBad = 旧 cap`，并**清掉** `lastGood`——它刚被
+     * 证伪，而新 cap 还没被任何 streak 证明（减 cap 不设 lastGood）。两档之后 `epoch += 1`——
+     * 即便 cap 已在地板、数值没变，也翻一页：同一批请求只能触发一次裁决。
+     */
+    throttled(now: number, epoch: number, reason: ConcurrencyThrottleReason, retryAfterMs?: number): ConcurrencyChange[];
+    /** 瞬态但非限流的失败（timeout / 5xx / 网络）：`inFlight--`、清 streak，cap 不动。 */
+    failedTransient(now: number): ConcurrencyChange[];
+    /** 一个请求以永久失败 / 取消终结，或 ticket 只见 release 没见终结事件：只做 `inFlight--`。 */
+    ended(now: number): ConcurrencyChange[];
+    /** 治理器在队列变化时喂入的等待者数（有需求才加 cap）。 */
+    waiters(now: number, count: number): ConcurrencyChange[];
+    /**
+     * 挪动自动增长的上界（docs/dynamic-workflow/concurrency.md「Increase」）。这是控制器里唯一一个
+     * 不归它自己管的数：治理器按「2D 与用过这个 key 的在飞 run 的最大上界取大」算出来，run 来去、
+     * retune 都会让它变。恒夹到 ≥ initial。
+     *
+     * 抬高什么都不立刻改：cap 照旧一级一级爬。压低到 cap 之下则当场把 cap 拉到新上界并发一条
+     * `limit_lowered`——否则一个为大 run 学到的高 cap 会留给之后的默认 run 共用，直到空闲重置。
+     * 同时夹 `lastGood`、清 streak、翻 epoch：旧 cap 下发出的请求撞的 429 不是对新 cap 的裁决。
+     */
+    setGrowthLimit(now: number, limit: number): ConcurrencyChange[];
+    /**
+     * 起跳（docs/dynamic-workflow/concurrency.md「Seeding」）：用户把一个 run 的上界调高时，治理器请
+     * cap 直接跳到 `min(target, growthLimit)`，而不是每 K 次成功爬一级——从 8 爬到 32 要约 96 次
+     * 成功，用户看到的是「设置没生效」。
+     *
+     * 清 `lastGood`：起跳点是新的起点，不是在已证明水位之上的探测；否则第一次 429 会一路退回旧的
+     * 已证明水位，而不是按系数减（32 → 24 → 18 …）。同时清 `lastBad`、清 streak、翻 epoch。
+     *
+     * 两种情况不跳：目标不高于 cap；五分钟内（空闲重置同一窗口）有过任何一次拒绝——那时起跳就是
+     * 明知故犯地对着刚撞过的墙再冲一波，cap 改为照常一级一级爬。
+     */
+    seed(now: number, target: number): ConcurrencyChange[];
+    /**
+     * 空闲重置（决策 20）：`now − lastRequestAt ≥ IDLE_RESET_MS` 且无在飞 → cap 回起点 `initial`，
+     * 清 streak / cooldown / lastGood / lastBad，epoch += 1。惰性发生在任一信号到达时（无定时器）。
+     */
+    private idleReset;
+    private change;
+}
+//# sourceMappingURL=concurrency.d.ts.map

package/vendor/dynamic-workflow/engine/concurrency.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"concurrency.d.ts","sourceRoot":"","sources":["../../src/engine/concurrency.ts"],"names":[],"mappings":"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"}