feat(workflow): show durable run records in Chat

2026-08-10 18:37:30 +08:00
parent d2321d210a
commit 8de6df19d9
73 changed files with 3013 additions and 227 deletions
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/workflow/workflow/README.md
-README.md: 0de661423206cc71eb4669bc8ddb2419202bcb4a
-README.zh.md: 62abd00c013d054f4111a2db2ce72c58d3514087
+README.md: f1b101159e656d7d76812c95c020fe6b3f48115e
+README.zh.md: 6d85c3b7e847b8c6176d4c1938805c22c543678b
@@ -6,6 +6,8 @@ The workflow seam (`ctx.workflows`) executes a model-written orchestration scrip

 `@deepseek-ai/dsh-workflow-workerthread` is the current engine and `@deepseek-ai/dsh-tool-workflow` is the model-facing consumer. A future process or sandbox engine can replace the implementation without changing the tool.

+The package root is the Host face. The browser-safe `@deepseek-ai/dsh-workflow/types` subpath contains run identities, metadata, results, and observe-only lifecycle payloads without importing `Agent`, Cordis services, or Host context declarations; Host-only `WorkflowStartRequest` and `WorkflowRun` live behind the package root.
+
 ## Service and run contract

 `WorkflowService.start(request): WorkflowRun` validates enough synchronously to reject a malformed meta block, unparseable script, unavailable provider route, or unsupported per-run limit before a run exists. Once returned, `WorkflowRun.result` never rejects: execution failures resolve with `stopReason: 'error'`, and cancellation resolves with `cancelled` within the engine's bounded grace.
@@ -6,6 +6,8 @@

 `@deepseek-ai/dsh-workflow-workerthread` 是当前引擎，`@deepseek-ai/dsh-tool-workflow` 是面向模型的消费方。未来的进程或沙箱引擎可以替换实现，而无需更改工具。

+包根是 Host face。浏览器安全的 `@deepseek-ai/dsh-workflow/types` 子路径包含运行身份、元数据、结果和仅供观察的生命周期 payload，不导入 `Agent`、Cordis service 或 Host Context 声明；Host 专用的 `WorkflowStartRequest` 与 `WorkflowRun` 只从包根提供。
+
 ## 服务与运行约定

 `WorkflowService.start(request): WorkflowRun` 会同步完成足够多的校验，在运行创建前拒绝格式错误的 meta 块、无法解析的脚本、不可用的提供方路由或不受支持的单次运行限制。返回后，`WorkflowRun.result` 绝不拒绝：执行失败以 `stopReason: 'error'` 兑现，取消则在引擎有限的宽限时间内以 `cancelled` 兑现。
@@ -15,12 +15,17 @@
      "types": "./lib/types/invariant.d.ts",
      "default": "./lib/invariant.js"
    },
+    "./types": {
+      "types": "./lib/types/types.d.ts",
+      "default": "./lib/types/types.js"
+    },
    "./src/*": "./src/*",
    "./package.json": "./package.json"
  },
  "files": [
    "lib/index.js",
    "lib/invariant.js",
+    "lib/types/**/*.js",
    "lib/types/**/*.d.ts"
  ],
  "license": "BSD-3-Clause",
@@ -10,10 +10,9 @@ import type {
  WorkflowAgentEndInfo,
  WorkflowAgentInfo,
  WorkflowResultInfo,
-  WorkflowRun,
  WorkflowRunInfo,
-  WorkflowStartRequest,
 } from './types.ts'
+import type { WorkflowRun, WorkflowStartRequest } from './runtime-types.ts'

 export { WorkflowRunId } from './types.ts'
 export type {
@@ -24,11 +23,10 @@ export type {
  WorkflowPhase,
  WorkflowResult,
  WorkflowResultInfo,
-  WorkflowRun,
  WorkflowRunInfo,
-  WorkflowStartRequest,
  WorkflowStopReason,
 } from './types.ts'
+export type { WorkflowRun, WorkflowStartRequest } from './runtime-types.ts'

 declare module 'cordis' {
  interface Context {
@@ -0,0 +1,49 @@
+/**
+ * Host-only workflow request and live-run handles. The browser-safe durable
+ * vocabulary remains in `./types` so Client programs never import Agent or
+ * host Cordis context declarations.
+ *
+ * @module @deepseek-ai/dsh-workflow
+ */
+
+import type { Agent } from '@deepseek-ai/dsh-agent'
+import type {
+  WorkflowMeta, WorkflowResult, WorkflowRunId,
+} from './types.ts'
+
+/**
+ * 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.
+ */
+export 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
+}
+
+/**
+ * Holder-owned live workflow. `result` never rejects; consumers may cancel
+ * and must call idempotent `dispose()` to await script and child quiescence.
+ */
+export 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>
+}
@@ -7,8 +7,7 @@
 */

 import type { Branded } from '@deepseek-ai/dsh-brand'
-import type { Agent } from '@deepseek-ai/dsh-agent'
-import type { SessionId } from '@deepseek-ai/dsh-session'
+import type { SessionId } from '@deepseek-ai/dsh-session/types'

 /** Identifies one workflow run. */
 export type WorkflowRunId = Branded<'WorkflowRunId'>
@@ -55,38 +54,6 @@ export interface WorkflowMeta {
  phases?: WorkflowPhase[]
 }

-/**
- * What a caller asks for when starting a workflow run. `meta` and `args` are
- * plain JSON DATA by the seam contract (the tool builds both from the model's schema-validated call;
- * the engine validates `meta` against its schema and rejects loud
- * before anything runs) — an engine never evaluates script text to obtain
- * them. `parent` is REQUIRED — every `agent()` the script spawns is
- * attributed to it (cwd, lineage, depth flow through the subagent seam).
- */
-export interface WorkflowStartRequest {
-  /** The plain-JS script body (top-level await allowed; ends with `return <json-value>`). */
-  script: string
-  /** The workflow's identity fields as plain JSON data, 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. The workflow
-   * script cannot observe or replace it; omission uses the engine's configured
-   * provider.
-   */
-  subagentProvider?: string
-  /**
-   * Optional per-run total-child ceiling. Implementations reject values above
-   * their deployment ceiling before publishing the run.
-   */
-  maxTotalAgents?: number
-  /** The agent on whose behalf the run executes (parent of every child). */
-  parent: Agent
-  /** Cancels the run when aborted (the tool's `exec.signal`). */
-  signal?: AbortSignal
-}
-
 /**
 * Why a run settled. CLOSED union (engine-owned, consumers may exhaust):
 * `completed` = the script ran to its final `return`; `cancelled` = the run
@@ -96,7 +63,7 @@ export interface WorkflowStartRequest {
 export type WorkflowStopReason = 'completed' | 'cancelled' | 'error'

 /**
- * The outcome of one run, resolved by {@link WorkflowRun.result}. `value` is
+ * 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
@@ -119,23 +86,6 @@ export interface WorkflowResult {
  agentsStarted: number
 }

-/**
- * Holder-owned live workflow. `result` never rejects and settles within the
- * engine's cancellation grace; failures resolve through `stopReason`. Consumers
- * may cancel and must call idempotent `dispose()` on every path to await bounded
- * script settlement and child quiescence.
- */
-export interface WorkflowRun {
-  readonly id: WorkflowRunId
-  /** The validated meta block (available before the body runs). */
-  readonly meta: WorkflowMeta
-  readonly result: Promise<WorkflowResult>
-  /** Cancel the run: children abort, pending hooks reject, the script dies at its next await (or is force-settled at the grace). */
-  cancel(reason?: string): void
-  /** Cancel + bounded-grace settle; safe to call on every path (idempotent). */
-  dispose(): Promise<void>
-}
-
 /** Identifying detail for a run, carried by every `workflow/*` event as borrowed immutable data, never the live run. */
 export interface WorkflowRunInfo {
  /** The run's id. */
@@ -17,6 +17,9 @@
    {
      "path": "../../core/agent"
    },
+    {
+      "path": "../../core/session"
+    },
    {
      "path": "../../util/brand"
    },