dsh-plugin-dev-kb 1.0.0

package/kb/site/reference/subsystems/web.md

@@ -0,0 +1,202 @@
+---
+editSource: "docs/subsystems/web.zh.md"
+outline: [2,3]
+---
+
+# Web 访问
+
+Web 访问 seam 是一个[能力 seam](https://github.com/deepseek-ai/deepseek-harness/blob/master/.agents/notes/implemented/architecture/2026-06-24-web-capability-seam.md)，在同一个 `ctx.web` 服务上横跨**两项操作**（search 与 fetch），并拆分到多个包：Service Definition（[dsh-web](https://github.com/deepseek-ai/deepseek-harness/tree/master/packages/web/web)，`ctx.web` + 提供方注册表）、Service Provider（[dsh-web-search-exa](https://github.com/deepseek-ai/deepseek-harness/tree/master/packages/web/web-search-exa)、[dsh-web-search-perplexity](https://github.com/deepseek-ai/deepseek-harness/tree/master/packages/web/web-search-perplexity)、[dsh-web-search-deepseek](https://github.com/deepseek-ai/deepseek-harness/tree/master/packages/web/web-search-deepseek)、[dsh-web-fetch-http](https://github.com/deepseek-ai/deepseek-harness/tree/master/packages/web/web-fetch-http)）与 Consumer（[dsh-tool-web](https://github.com/deepseek-ai/deepseek-harness/tree/master/packages/web/tool-web)，即 `web_search`/`web_fetch` 工具 schema）。Web 是**一项可选能力**，不属于 agent loop（智能体循环）主干，因此其词汇定义在此而非 [core.md](./core.md) 中。更换 search 提供方不会改变模型提交查询的方式，更换 fetch 提供方也不会改变模型请求 URL 的方式。
+
+源码：[`packages/web/web/src/types.ts`](https://github.com/deepseek-ai/deepseek-harness/blob/master/packages/web/web/src/types.ts)
+
+## 为什么一项能力包含两项操作
+
+搜索与抓取既不共享请求 schema，也不共享业务逻辑，但它们被有意设计为同一个 `ctx.web` 中间层：一个提供方选择策略的所有者、一套中止与错误词汇，以及一个面向产品的「此 harness 如何访问 Web」配置界面。代价是服务上并行的 `searchX`／`fetchX` 方法对；这种并行是有意为之，而不是遗漏了可抽取的共性。提供方注册的是**能力**（`WebSearchProvider` 或 `WebFetchProvider`），而非工具；面向模型的名称、schema、提示词引导与展示全部集中在唯一的消费方 `dsh-tool-web` 中。
+
+## 搜索请求与结果
+
+面向模型的工具参数仅为一个 `query`；`maxResults` 是消费方自有的上限（`dsh-tool-web` 的 `searchMaxResults` 配置，默认 `8`），通过 seam 传递并在返回时强制执行——如果提供方返回超量，seam 截断 `sources[]` 并设置 `truncated`。
+
+```ts type-equiv
+/**
+ * What one search-capable backend can return. The model-facing argument is just
+ * a query; `maxResults` is a `dsh-tool-web`-layer bound passed through unchanged
+ * and enforced on the way back by the seam (see {@link WebSearchResult}).
+ */
+interface WebSearchRequest {
+  readonly query: string
+  /**
+   * Upper bound on returned sources; the seam truncates to it. Omitted = no
+   * bound. `dsh-tool-web` always sets it. A provider whose API supports a
+   * result-count control (Exa's `numResults`) should apply it at the request
+   * layer as a cost/latency optimization; the seam enforces the bound
+   * regardless.
+   */
+  readonly maxResults?: number
+}
+```
+
+```ts type-equiv
+/**
+ * Normalized search outcome. `content` is optional provider-generated answer
+ * text or summary (Exa and DeepSeek return none; Perplexity returns a
+ * generated answer).
+ * `sources[]` is the portable citation shape. `truncated` is set by the seam
+ * when it cut `sources[]` down to `maxResults`.
+ */
+interface WebSearchResult {
+  /** Optional provider-generated answer text, search context, or summary. */
+  readonly content?: string
+  /** Citeable sources, already truncated to the request's `maxResults`. */
+  readonly sources: readonly WebSearchSource[]
+  /** True when the seam dropped sources to honor `maxResults`. */
+  readonly truncated: boolean
+}
+```
+
+```ts type-equiv
+/**
+ * One citeable source. A source always has a URL; `title`, `snippet`, and
+ * `publishedAt` are optional because not every provider returns them — forcing
+ * adapters to invent them would make the seam lie (Perplexity citations may be
+ * URL-only). `dsh-tool-web` renders `title ?? hostname(url)` for display.
+ */
+interface WebSearchSource {
+  readonly url: string
+  readonly title?: string
+  readonly snippet?: string
+  /** Publication/crawl timestamp as a provider-supplied ISO-8601 string. */
+  readonly publishedAt?: string
+}
+```
+
+## 抓取请求与结果
+
+```ts type-equiv
+/**
+ * What one fetch-capable backend is asked to retrieve. The request deliberately
+ * omits timeout, format, prompt, and extraction controls: cancellation is a
+ * direct execution argument, while presentation and higher-level LLM concerns
+ * belong outside safe retrieval.
+ */
+interface WebFetchRequest {
+  readonly url: string
+}
+```
+
+HTTP 状态码是被抓取资源状态的一部分，不自动视为失败：即使一次成功的网络抓取收到 `404` 或 `500` 响应，也仍会产出一个 `WebFetchResult`，其中包含状态码和长度受限的已解码正文。`url` 是经过允许的重定向后的最终 URL。`WebError` 仅用于无法安全获取或表示资源的情况。
+
+```ts type-equiv
+/**
+ * Normalized fetch outcome. A successful network fetch of a non-2xx response is
+ * a result, not an error: the status code is part of the fetched resource
+ * state. {@link WebError} is reserved for failures to safely retrieve or
+ * represent the resource.
+ */
+interface WebFetchResult {
+  /** The final URL after allowed redirects (the request URL is in the request). */
+  readonly url: string
+  /** HTTP status code of the fetched response. */
+  readonly statusCode: number
+  /** Decoded body, classified by content kind. */
+  readonly body: WebFetchBody
+  /** True when the provider capped the decoded body. */
+  readonly truncated: boolean
+}
+```
+
+```ts type-equiv
+/**
+ * The decoded body of a fetched resource. A CLOSED discriminated union owned by
+ * `dsh-web`: the provider decodes the kind and `dsh-tool-web` renders it, so a
+ * new kind is a coordinated change across known packages, not a plugin
+ * extension. Consumers `switch` on `kind` ending in `default: assertNever(...)`
+ * so adding a kind breaks compilation at every consumer until handled. Each arm
+ * stays its own object literal even where fields coincide, so an arm can gain
+ * fields the others lack.
+ */
+type WebFetchBody =
+  | { readonly kind: 'html'; readonly content: string }
+  | { readonly kind: 'text'; readonly content: string }
+```
+
+## 提供方可用性
+
+提供方的 `available(): boolean` 是一个廉价的本地检查（凭证是否存在、配置是否可解析），**禁止发起网络调用**。它是执行时选择提供方的输入，而不是健康检查系统：`search()`／`fetch()` 会读取它来选择可用的提供方。选择失败时，调用方会收到可据以分支处理的结构化 `WebError`；其错误代码和消息会说明缺失的 id 或存在歧义的候选集。
+
+选择从不依赖注册顺序、配置顺序或 HMR（热模块替换）顺序：一项能力要么有显式的提供方 id（配置 `searchProvider`／`fetchProvider`，或填充同一字段的对应环境变量），要么在恰好只有一个可用提供方注册时自动选择；如果存在多个可用提供方却未配置 id，则抛出 `WEB_PROVIDER_AMBIGUOUS`，而不会选用最先注册的提供方。
+
+## 错误
+
+`WebError extends HarnessError`（[core.md](./core.md) 错误分类体系），带有 `code: string`（开放式，与其他 seam 的错误一致——`LlmError`、`SubagentError`），而非封闭联合类型：提供方可以在不修改 `dsh-web` 的情况下抛出自己的错误代码，消费方必须容忍未知错误代码。错误代码按所有者划分。共享的 `WebRuntime` 约定会抛出与 seam 无关的错误代码：`WEB_PROVIDER_UNAVAILABLE`、`WEB_PROVIDER_CONFIGURED_MISSING`、`WEB_PROVIDER_CONFIGURED_UNAVAILABLE`、`WEB_PROVIDER_AMBIGUOUS`、`WEB_DUPLICATE_PROVIDER`（注册时的编程错误，类似 `LlmRuntime` 的 `DUPLICATE_ADAPTER`）、`WEB_ABORTED`，以及 `WEB_PROVIDER_ERROR`（提供方自身故障经 seam 暴露时使用的兜底代码，包括 DNS、连接被拒绝、TLS 等网络或传输故障）。抓取传输层错误代码由 `dsh-web-fetch-http` 实现拥有，不同的抓取后端无需抛出它们：`WEB_INVALID_URL`、`WEB_BLOCKED_URL`、`WEB_REDIRECT_BLOCKED`、`WEB_FETCH_TOO_LARGE`、`WEB_FETCH_TIMEOUT`、`WEB_UNSUPPORTED_CONTENT_TYPE`。
+
+## 服务
+
+`WebRuntime` 注册搜索与抓取提供方，以 `WEB_DUPLICATE_PROVIDER` 拒绝重复 id，并在执行时以结构化的选择错误解析提供方。本地抓取后端仅接受 HTTP(S)、拒绝凭证、限制重定向次数、字节数、字符数和时间、对每一次同源重定向跳转重新进行安全校验，并解码正文；展示由工具负责。本地后端不会拦截私有网络目标；在能够触及敏感内部目标的环境中，禁止启用 `web_fetch`。
+
+<!-- BEGIN GENERATED cordis-surface (gen-cordis-catalog.ts) — do not edit between markers -->
+
+<a id="cordis-surface"></a>
+
+## Cordis API
+
+Generated from source by `scripts/gen-cordis-catalog.ts` (verified fresh by `pnpm run verify-cordis-catalog` in doc-sync; regenerate with `pnpm run gen-cordis-catalog`) — this section is byte-identical in both language sides of the page. Signature blocks use a `ts cordis-catalog` fence and keep the original source JSDoc; dispatch modes are defined in the [primer](../cordis-primer.md#dispatch-modes), and the framework-inherited `ctx` API lives in [cordis-api/inherited.md](../cordis-api/inherited.md).
+
+<a id="ctxweb--webruntime"></a>
+
+### `ctx.web` — `WebRuntime`
+
+The web access service. Registered as `ctx.web` (one instance per context).
+
+Selection semantics (resolved at execution time, never order-dependent):
+
+- A configured id that is registered and `available()` → that provider.
+- A configured id not registered → `WEB_PROVIDER_CONFIGURED_MISSING`.
+- A configured id registered but unavailable → `WEB_PROVIDER_CONFIGURED_UNAVAILABLE`.
+- No id configured, exactly one registered usable provider → that provider.
+- No id configured, multiple usable providers → `WEB_PROVIDER_AMBIGUOUS`.
+- No id configured, no usable provider → `WEB_PROVIDER_UNAVAILABLE`.
+
+```ts cordis-catalog
+/**
+ * Register a search provider. Throws {@link WebError} `WEB_DUPLICATE_PROVIDER`
+ * if its id is already registered for search. Returns a disposer; disposed
+ * with the calling fiber.
+ * @param provider - the provider; its `id` is the registry key.
+ * @returns the disposer that unregisters the provider.
+ */
+registerSearchProvider(provider: WebSearchProvider): () => void
+
+/**
+ * Register a fetch provider. Throws {@link WebError} `WEB_DUPLICATE_PROVIDER`
+ * if its id is already registered for fetch. Returns a disposer; disposed
+ * with the calling fiber.
+ * @param provider - the provider; its `id` is the registry key.
+ * @returns the disposer that unregisters the provider.
+ */
+registerFetchProvider(provider: WebFetchProvider): () => void
+
+/**
+ * Run one search through the selected provider. Resolves the provider at call
+ * time with the selection rules above; throws {@link WebError} when the
+ * capability cannot run. The seam enforces `request.maxResults` on the result:
+ * if the provider over-returns, `sources[]` is truncated and `truncated` set.
+ * @param request - the query and optional result limit.
+ * @param signal - optional cancellation signal forwarded to the provider.
+ * @returns the provider's results, capped to `request.maxResults`.
+ */
+async search(request: WebSearchRequest, signal?: AbortSignal): Promise<WebSearchResult>
+
+/**
+ * Retrieve one URL through the selected provider. Resolves the provider at
+ * call time with the selection rules above; throws {@link WebError} when the
+ * capability cannot run. A non-2xx response is a result, not a throw.
+ * @param request - the URL plus retrieval options.
+ * @param signal - optional cancellation signal forwarded to the provider.
+ * @returns the retrieval outcome; non-2xx responses resolve descriptively.
+ */
+async fetch(request: WebFetchRequest, signal?: AbortSignal): Promise<WebFetchResult>
+```
+
+Source: [`packages/web/web/src/index.ts:74`](https://github.com/deepseek-ai/deepseek-harness/blob/master/packages/web/web/src/index.ts)
+<!-- END GENERATED cordis-surface -->

package/kb/site/reference/subsystems/workflow.md

@@ -0,0 +1,281 @@
+---
+editSource: "docs/subsystems/workflow.zh.md"
+outline: [2,3]
+---
+
+# 工作流
+
+工作流 seam 允许 agent（智能体）运行由模型编写、会启动 subagent 的编排脚本。与 [subagent](./subagent.md) 一样，它是**一项可选能力**，不属于 agent loop，因此其类型和操作记录在此处，而非 [core.md](./core.md)。与 bash 一样，每个上下文只允许一个引擎实现提供 `ctx.workflowEngine`；没有命名提供方注册表（第二个引擎通过插件配置替换第一个，而不与它同时运行）。
+
+Service Definition：[dsh-workflow](https://github.com/deepseek-ai/deepseek-harness/tree/master/packages/workflow/workflow)（`ctx.workflowEngine` + 下文词汇）。Service Provider 是 [dsh-workflow-worker-thread](https://github.com/deepseek-ai/deepseek-harness/tree/master/packages/workflow/workflow-worker-thread)（一个 `node:worker_threads` 引擎——每个 run 一个 worker，脚本的 vm 上下文位于其中）；面向模型的 Consumer 是 [dsh-tool-workflow](https://github.com/deepseek-ai/deepseek-harness/tree/master/packages/workflow/tool-workflow)。提案与设计理由见 [dynamic-workflows Agent Note](https://github.com/deepseek-ai/deepseek-harness/blob/master/.agents/notes/implemented/feature/2026-07-05-dynamic-workflows.md)。
+
+源码：浏览器安全词汇位于 [`packages/workflow/workflow/src/types.ts`](https://github.com/deepseek-ai/deepseek-harness/blob/master/packages/workflow/workflow/src/types.ts)，Host 请求与活跃运行句柄位于 [`runtime-types.ts`](https://github.com/deepseek-ai/deepseek-harness/blob/master/packages/workflow/workflow/src/runtime-types.ts)。
+
+## 启动请求
+
+本节定义调用方启动一次运行时提交的请求。普通工作流工具会根据模型的 `{ script, meta, args }` 调用和发起调用的 agent 构建该请求；专用消费方还可以为本次运行选择引擎级 `subagentProvider`，并将 `maxTotalAgents` 调低，但脚本无法观察或替换这两项策略。`meta` 与 `args` 是普通 JSON 数据；引擎会用 schema 校验 `meta`，并在任何工作开始前明确报错并拒绝无效数据。引擎绝不会通过对脚本文本求值来获取它们。`parent` 是必填字段——脚本启动的每个子 agent 都归属于它，cwd、谱系与深度通过 [subagent seam](./subagent.md) 传递。
+
+```ts type-equiv
+/**
+ * What a caller asks for when starting a workflow run. `meta` and `args` are
+ * plain JSON data by the seam contract. `parent` is required because every
+ * `agent()` spawned by the script is attributed to that live Agent.
+ */
+interface WorkflowStartRequest {
+  /** The plain-JS script body (top-level await allowed; ends with `return <json-value>`). */
+  script: string
+  /** The workflow's identity block, as plain JSON data (shape-validated by the engine). */
+  meta: WorkflowMeta
+  /** Optional input exposed verbatim to the script as the `args` global. */
+  args?: unknown
+  /** Optional engine-wide child-provider override for this run. */
+  subagentProvider?: string
+  /** Optional per-run total-child ceiling. */
+  maxTotalAgents?: number
+  /** The agent on whose behalf the run executes (parent of every child). */
+  parent: Agent
+  /** Cancels the run when aborted. */
+  signal?: AbortSignal
+}
+```
+
+## 工作流的身份标识：`WorkflowMeta`
+
+作为数据附在启动请求上的身份块（工具的 `meta` 参数；字段词汇与 Claude Code 动态工作流的 meta 块一致）。`phases` 仅用于进度展示：`phase()` 调用与标题匹配，供观察者使用；不暗示任何执行结构。
+
+```ts type-equiv
+/**
+ * The script's identity block, provided as plain JSON data alongside the
+ * script body (the model-facing tool carries it as its `meta` parameter) and
+ * validated by the engine before the body runs. `name`/`description` are
+ * required; the rest is optional annotation. The field vocabulary matches the
+ * Claude Code dynamic-workflows meta block.
+ */
+interface WorkflowMeta {
+  /** Short kebab-case workflow name (display + persistence key). */
+  name: string
+  /** One-line description of what the workflow does. */
+  description: string
+  /** Optional guidance on when this workflow applies (shown in listings). */
+  whenToUse?: string
+  /** Optional phase declarations matched by `phase()` calls. */
+  phases?: WorkflowPhase[]
+}
+```
+
+## 终态结果：`WorkflowResult`
+
+`WorkflowRun.result` 会兑现为一次运行的结果。`value` 是脚本的物化返回值——纯宿主域 JSON 数据（脚本无返回值时为 `null`）——仅在 `completed` 时有意义。`stopReason` 是封闭联合类型（由引擎定义；消费方可穷举）：`completed` | `cancelled` | `error`。非 `completed` 的原因在 `error` 中携带失败信息，消费方将其映射为 `isError` 工具结果，而非把部分输出当作成功上报。
+
+```ts type-equiv
+/**
+ * The outcome resolved by a live workflow run. `value` is
+ * the script's materialized return value (plain host-realm JSON data; `null`
+ * when the script returned `undefined`) — meaningful only for `completed`.
+ * A non-`completed` reason carries the failure in `error`; the consumer maps
+ * it to an `isError` tool result rather than reporting partial output.
+ */
+interface WorkflowResult {
+  /** The script's return value (host JSON data; `null` for no return). */
+  value: unknown
+  /** Why the run settled. */
+  stopReason: WorkflowStopReason
+  /** The failure message (present iff `stopReason` is not `completed`). */
+  error?: string
+  /**
+   * How many `agent()` calls the run accepted over its whole lifetime. On a
+   * graceful settlement this is the script-side count (calls still queued for
+   * a concurrency slot included); on a termination path (grace force-settle,
+   * worker death) it degrades to the host-observed count — calls queued
+   * inside a terminated script are unknowable then.
+   */
+  agentsStarted: number
+}
+```
+
+## 活跃运行：`WorkflowRun`
+
+脚本执行期间消费方持有的句柄。消费方会等待 `result`，可以在运行期间调用 `cancel`，并且必须在每条路径上调用 `dispose`（资源释放）。`result` 不会被拒绝：脚本失败会兑现为 `stopReason: 'error'`。运行被取消后，即使脚本本身永不结算，结果也会在引擎规定的有界宽限期内结算；引擎会强制将其结算为 `cancelled`，随后 worker-thread 引擎会终止脚本所在的 worker。因此，等待 `result` 的消费方不会在取消后无限期挂起。`dispose()` 会执行取消、等待有界结算并等待子 agent 完全停稳，不会因脚本卡死而挂起。
+
+```ts type-equiv
+/**
+ * Holder-owned live workflow. `result` never rejects; consumers may cancel
+ * and must call idempotent `dispose()` to await script and child quiescence.
+ */
+interface WorkflowRun {
+  readonly id: WorkflowRunId
+  /** The validated meta block available before the script body runs. */
+  readonly meta: WorkflowMeta
+  readonly result: Promise<WorkflowResult>
+  /** Cancel the run and its children. */
+  cancel(reason?: string): void
+  /** Cancel if needed and await bounded settlement and cleanup. */
+  dispose(): Promise<void>
+}
+```
+
+## 失败纪律：`WorkflowError.fatal`
+
+脚本内部的钩子误用：错误参数、未知或延迟的 `agent()` 选项、超出[结构化输出子集](https://github.com/deepseek-ai/deepseek-harness/blob/master/packages/core/tools/README.md)的 schema、超出上限、seam 启动失败、取消，都会抛出 `fatal: true` 的 `WorkflowError`。`parallel()`/`pipeline()` 组合器对 fatal 错误直接重新抛出，而非将该项映射为 `null`：一个拼写错误的选项必须明确报错并终止脚本，绝不能消融为看似普通子 agent 失败的结果。逐项的 `null` 保留给子运行失败（非 `completed` 的 stop reason）和阶段内的普通脚本错误。
+
+## 事件
+
+`workflow/*` 事件（`workflow/start`、`workflow/phase`、`workflow/log`、`workflow/agent-start`、`workflow/agent-end`、`workflow/end`，见[事件目录](#cordis-surface)）是**仅供观察**的 emit，携带数据快照：每个 payload 以 `WorkflowRunInfo`（id + meta）开头，而非活跃的 `WorkflowRun`，因此订阅者无法获得 `cancel`/`dispose`；`workflow/end` 刻意省略 result value（观察结果的监听器不得收到调用方 result 的可变别名）。每次 emit 对每个监听器隔离：订阅者抛出的异常会被记录到日志中而不会传播，也不会阻止后续注册的监听器收到事件；每个监听器收到自己的 payload 克隆，因此修改它既不会损坏引擎也不会影响其他监听器。这种隔离方式与 `subagent/start`/`subagent/end` 一致。
+
+## 持久 Chat 记录
+
+顶层 `dsh-tool-workflow` 消费方把展示事实投影到调用它的父 Session，同时不改变执行所有权。运行接受后写 `tool-workflow/run-start`，以 `runId + seq` 配对成员开始与结束，并且只在结果已取得且 dispose 完全停稳后写 `tool-workflow/run-end`。嵌套 transport 调用不写记录。第一次 append 失败会禁用本运行后续写入，因此日志保持为空或合法连续前缀，工具结果不变。
+
+`dsh-tool-workflow/invariant` 会在实时提交前和 Session 加载时校验同一协议：每个运行只有一个 start，成员序号为正且唯一，成员 end 必须配对，仍有开放成员时不能结束运行，运行结束后不能继续更新。日志尾部缺少成员 end 或 run end 是有效的中断证据，不是损坏。
+
+`dsh-client-ui-workflow-run` 通过 Conversation Node 引擎把四类事件折叠为一个 `workflow-run` Chat 节点，以 run-start 序号锚定在原工作流工具节点之后。阶段组只来自真正开始过的成员，并保留精确字符串，包括字段缺省与 `''` 的区别。Location 关闭时，缺失终点会显示为已中断。[界面包 README](https://github.com/deepseek-ai/deepseek-harness/blob/master/packages/client/ui-workflow-run/README.md)负责定义 disclosure、状态与同父本地导航行为。
+
+<!-- BEGIN GENERATED cordis-surface (gen-cordis-catalog.ts) — do not edit between markers -->
+
+<a id="cordis-surface"></a>
+
+## Cordis API
+
+Generated from source by `scripts/gen-cordis-catalog.ts` (verified fresh by `pnpm run verify-cordis-catalog` in doc-sync; regenerate with `pnpm run gen-cordis-catalog`) — this section is byte-identical in both language sides of the page. Signature blocks use a `ts cordis-catalog` fence and keep the original source JSDoc; dispatch modes are defined in the [primer](../cordis-primer.md#dispatch-modes), and the framework-inherited `ctx` API lives in [cordis-api/inherited.md](../cordis-api/inherited.md).
+
+<a id="ctxworkflowengine--workflowengine-abstract-seam"></a>
+
+### `ctx.workflowEngine` — `WorkflowEngine` (abstract seam)
+
+Workflow Service Definition contract. Invalid requests throw before publication; a live run is holder-owned, its result never rejects, cancellation and disposal are bounded, and disposal waits for child cleanup within that bound. Lifecycle listener failures are contained, and `workflow/end` fires exactly once as the result settles.
+
+```ts cordis-catalog
+/**
+ * Parse and execute a workflow script.
+ * @param request - the script, its `args`, the parent agent, and an
+ *   optional cancel signal.
+ * @returns the live run; its `result` resolves when the script settles.
+ */
+abstract start(request: WorkflowStartRequest): WorkflowRun
+```
+
+Source: [`packages/workflow/workflow/src/index.ts:157`](https://github.com/deepseek-ai/deepseek-harness/blob/master/packages/workflow/workflow/src/index.ts)
+
+<a id="workflow-events"></a>
+
+### `workflow/*` events
+
+<a id="workflowagent-end--emit"></a>
+
+#### `workflow/agent-end` — emit
+
+One `agent()` call settled (clean result, child failure, or run cancellation). Paired with Events['workflow/agent-start'] by `agent.seq`, exactly once per started call on every stop path — on an engine termination path (a worker killed past its grace) the end is engine-synthesized with outcome `'cancelled'`.
+
+```ts cordis-catalog
+/**
+ * One `agent()` call settled (clean result, child failure, or run
+ * cancellation). Paired with {@link Events['workflow/agent-start']} by
+ * `agent.seq`, exactly once per started call on every stop path — on an
+ * engine termination path (a worker killed past its grace) the end is
+ * engine-synthesized with outcome `'cancelled'`.
+ * @param info - the run's identity snapshot.
+ * @param agent - the call identity plus its outcome.
+ * @mode emit
+ */
+'workflow/agent-end'(info: WorkflowRunInfo, agent: WorkflowAgentEndInfo): void
+```
+
+Source: [`packages/workflow/workflow/src/index.ts:79`](https://github.com/deepseek-ai/deepseek-harness/blob/master/packages/workflow/workflow/src/index.ts)
+
+<a id="workflowagent-start--emit"></a>
+
+#### `workflow/agent-start` — emit
+
+One `agent()` call established a published child run. Paired with Events['workflow/agent-end'] by `agent.seq`. A call that never receives a published run from the provider emits neither event in this pair.
+
+```ts cordis-catalog
+/**
+ * One `agent()` call established a published child run. Paired with
+ * {@link Events['workflow/agent-end']} by `agent.seq`. A call that never
+ * receives a published run from the provider emits neither
+ * event in this pair.
+ * @param info - the run's identity snapshot.
+ * @param agent - the call's sequence number, label, phase, and child id.
+ * @mode emit
+ */
+'workflow/agent-start'(info: WorkflowRunInfo, agent: WorkflowAgentInfo): void
+```
+
+Source: [`packages/workflow/workflow/src/index.ts:68`](https://github.com/deepseek-ai/deepseek-harness/blob/master/packages/workflow/workflow/src/index.ts)
+
+<a id="workflowend--emit"></a>
+
+#### `workflow/end` — emit
+
+A workflow run settled (any stop reason). Fired when WorkflowRun.result resolves. Paired with Events['workflow/start'].
+
+```ts cordis-catalog
+/**
+ * A workflow run settled (any stop reason). Fired when
+ * {@link WorkflowRun.result} resolves. Paired with
+ * {@link Events['workflow/start']}.
+ * @param info - the run's identity snapshot.
+ * @param result - the outcome data (stop reason, error, agent count) —
+ *   deliberately WITHOUT the result value (see {@link WorkflowResultInfo}).
+ * @mode emit
+ */
+'workflow/end'(info: WorkflowRunInfo, result: WorkflowResultInfo): void
+```
+
+Source: [`packages/workflow/workflow/src/index.ts:89`](https://github.com/deepseek-ai/deepseek-harness/blob/master/packages/workflow/workflow/src/index.ts)
+
+<a id="workflowlog--emit"></a>
+
+#### `workflow/log` — emit
+
+The script emitted a narration line (a `log(message)` call).
+
+```ts cordis-catalog
+/**
+ * The script emitted a narration line (a `log(message)` call).
+ * @param info - the run's identity snapshot.
+ * @param message - the logged message, verbatim.
+ * @mode emit
+ */
+'workflow/log'(info: WorkflowRunInfo, message: string): void
+```
+
+Source: [`packages/workflow/workflow/src/index.ts:58`](https://github.com/deepseek-ai/deepseek-harness/blob/master/packages/workflow/workflow/src/index.ts)
+
+<a id="workflowphase--emit"></a>
+
+#### `workflow/phase` — emit
+
+The script entered a phase (a `phase(title)` call) — progress grouping for observers; no execution semantics.
+
+```ts cordis-catalog
+/**
+ * The script entered a phase (a `phase(title)` call) — progress grouping
+ * for observers; no execution semantics.
+ * @param info - the run's identity snapshot.
+ * @param title - the phase title, verbatim.
+ * @mode emit
+ */
+'workflow/phase'(info: WorkflowRunInfo, title: string): void
+```
+
+Source: [`packages/workflow/workflow/src/index.ts:51`](https://github.com/deepseek-ai/deepseek-harness/blob/master/packages/workflow/workflow/src/index.ts)
+
+<a id="workflowstart--emit"></a>
+
+#### `workflow/start` — emit
+
+A workflow run started — the script's meta block validated, the body about to execute. Paired with Events['workflow/end'].
+
+```ts cordis-catalog
+/**
+ * A workflow run started — the script's meta block validated, the body
+ * about to execute. Paired with {@link Events['workflow/end']}.
+ * @param info - the run's identity snapshot (id + meta).
+ * @mode emit
+ */
+'workflow/start'(info: WorkflowRunInfo): void
+```
+
+Source: [`packages/workflow/workflow/src/index.ts:43`](https://github.com/deepseek-ai/deepseek-harness/blob/master/packages/workflow/workflow/src/index.ts)
+<!-- END GENERATED cordis-surface -->