@ai-setting/roy-agent-core 1.7.52 → 1.7.55

package/dist/env/workflow/nodes/tool-node.d.ts

@@ -0,0 +1,64 @@
+/**
+ * Tool Registry interface for looking up tools
+ * Supports both the full ToolRegistration and simplified Tool interface
+ */
+export interface ToolRegistry {
+    getTool?(name: string): ToolRegistration | undefined;
+    getToolByName?(name: string): Tool | undefined;
+    hasTool?(name: string): boolean;
+}
+/**
+ * Tool Registration interface (from ToolComponent)
+ */
+export interface ToolRegistration {
+    tool: Tool;
+    enabled: boolean;
+    source?: string;
+}
+/**
+ * Tool interface for execution
+ */
+export interface Tool {
+    name: string;
+    execute(input: any, context?: any): Promise<any>;
+}
+/**
+ * ToolNode executes a registered Tool with the provided input.
+ *
+ * Input can contain template strings like {{nodeId.output.path}} that will be
+ * resolved from previousOutputs via TemplateResolver.
+ */
+export declare class ToolNode implements Node {
+    private definition;
+    private toolRegistry;
+    readonly type = "tool";
+    readonly id: string;
+    constructor(definition: NodeDefinition, toolRegistry: ToolRegistry);
+    execute(context: NodeExecutionContext): Promise<NodeExecutionResult>;
+    /**
+     * Extract the actual output value from wrapper formats.
+     * For strings, removes trailing whitespace (especially newlines from bash commands).
+     */
+    private extractFromWrapper;
+    /**
+     * Task #2900 P0-A: Extract error from wrapper format if tool reports failure.
+     *
+     * Returns the tool's `error` field (string | Error) when `success === false`
+     * is present in the wrapper, so that executor.executeWithTimeout() can
+     * propagate it as NodeExecutionResult.error. Without this, bash failures
+     * silently produced output="" + status=completed in the engine.
+     *
+     * Returns undefined when:
+     *   - value is not an object
+     *   - success === true (or success field is missing)
+     *   - wrapper has no error string
+     *
+     * Task #4392 P0-2: when the wrapper signals a non-zero `exit_code` but carries
+     * no stderr, the bare `Tool exited with code N` message is useless on its own
+     * (#4385 measured 27 such `exit 2` occurrences in the creator sessions, and
+     * 291 failed runs whose `session.metadata.error` was null). We therefore append
+     * the (redacted, single-line, truncated) command plus a stdout tail.
+     */
+    private extractErrorFromWrapper;
+}
+import type { Node, NodeDefinition, NodeExecutionContext, NodeExecutionResult } from '../types';

package/dist/env/workflow/nodes/workflow-node.d.ts

@@ -0,0 +1,118 @@
+import type { Node, NodeDefinition, NodeExecutionContext, NodeExecutionResult } from '../types';
+/**
+ * WorkflowRunner interface for running sub-workflows
+ */
+export interface WorkflowRunner {
+    /**
+     * Run a workflow by name
+     * @param workflowName - Name of the workflow to run
+     * @param input - Optional input to pass to the workflow
+     * @returns Promise resolving to the workflow run result
+     */
+    run(workflowName: string, input?: any): Promise<WorkflowRunResult>;
+    /**
+     * Get the status of a workflow run
+     * @param runId - The run ID to check
+     * @returns Promise resolving to the run result or null if not found
+     */
+    getRun(runId: string): Promise<WorkflowRunResult | null>;
+}
+/**
+ * Result from a workflow run
+ */
+export interface WorkflowRunResult {
+    /** Unique run ID */
+    runId: string;
+    /** Final status of the run */
+    status: 'completed' | 'failed' | 'stopped';
+    /** Output from the workflow (if completed) */
+    output?: any;
+    /** Error message (if failed or stopped) */
+    error?: string;
+}
+/**
+ * WorkflowNode configuration
+ */
+export interface WorkflowNodeConfig {
+    /** Name of the workflow to invoke */
+    workflow_name: string;
+    /** Input to pass to the sub-workflow (supports template strings) */
+    input?: Record<string, unknown>;
+    /** Whether to wait for completion (default: true) */
+    wait_complete?: boolean;
+}
+/**
+ * WorkflowNode executes a nested workflow as a node.
+ *
+ * This allows one workflow to invoke another workflow as a single node,
+ * enabling workflow composition and reusability.
+ *
+ * Features:
+ * - Pass input to sub-workflow (with template resolution)
+ * - Wait for completion or fire-and-forget
+ * - Handle sub-workflow errors
+ * - Track execution duration
+ */
+export declare class WorkflowNode implements Node {
+    private definition;
+    private workflowRunner;
+    readonly type = "workflow";
+    readonly id: string;
+    constructor(definition: NodeDefinition, workflowRunner: WorkflowRunner);
+    execute(context: NodeExecutionContext): Promise<NodeExecutionResult>;
+    /**
+     * Convert Record<string, NodeExecutionResult> to Map<string, any>
+     * for compatibility with resolvePath that expects Map format.
+     *
+     * In the Record format, the value is NodeExecutionResult (with output field).
+     * In the Map format, the value is the raw output directly.
+     */
+    private convertToMap;
+    /**
+     * Resolve input template references.
+     * Templates are in the format {{nodeId.output.path}}
+     *
+     * @param input - The input object that may contain template strings
+     * @param previousOutputs - Map of previous node outputs (value is raw output)
+     * @returns The input with template references resolved
+     */
+    private resolveInput;
+    /**
+     * Resolve a value that may contain template references.
+     */
+    private resolveValue;
+    /**
+     * Resolve template references in a single string.
+     * Supports format: {{nodeId.output.path}}
+     */
+    private resolveStringTemplate;
+    /**
+     * Resolve a dot-notation path from previous outputs.
+     * First segment is the node ID, rest is the path within that node's output.
+     */
+    private resolvePath;
+    /**
+     * Extract the actual output value from wrapper formats.
+     *
+     * Handles:
+     * - AgentNode format: { result, metadata } -> returns result
+     * - DecoratorNode format: { success, output, ... } -> returns output
+     * - Other formats: returns value as-is
+     *
+     * @param value - The value to extract from
+     * @returns The extracted value
+     */
+    private extractFromWrapper;
+    /**
+     * Convert a value to string for template replacement.
+     * - If value is undefined, return the original template
+     * - If value is a string, return it directly
+     * - If value is null, return 'null'
+     * - If value is an object or array, serialize to JSON
+     *
+     * @param value - The value to stringify
+     * @param originalTemplate - The original template string (returned if value is undefined)
+     * @returns String representation of the value
+     */
+    private stringifyValue;
+}

package/dist/env/workflow/plugins/index.d.ts

@@ -0,0 +1,6 @@
+/**
+ * @fileoverview Workflow Plugins Module — barrel export
+ *
+ * 参考 `env/task/plugins/index.ts` 的导出方式。
+ */
+export { LarkCliWorkflowNotifyHook, createLarkCliWorkflowNotifyHook, type WorkflowNotifyConfig, } from "./lark-cli-workflow-notify-plugin";

package/dist/env/workflow/plugins/index.js

@@ -1,8 +1,8 @@
 import {
   LarkCliWorkflowNotifyHook,
   createLarkCliWorkflowNotifyHook
-} from "../../../shared/@ai-setting/roy-agent-core-brwzs8wf.js";
-import"../../../shared/@ai-setting/roy-agent-core-j8e92gj8.js";
+} from "../../../shared/@ai-setting/roy-agent-core-9h72sk1n.js";
+import"../../../shared/@ai-setting/roy-agent-core-b5ew8t0k.js";
 import"../../../shared/@ai-setting/roy-agent-core-9csa89jx.js";
 import"../../../shared/@ai-setting/roy-agent-core-qcspfszy.js";
 import"../../../shared/@ai-setting/roy-agent-core-4z3rq5gw.js";

package/dist/env/workflow/plugins/lark-cli-workflow-notify-plugin.d.ts

@@ -0,0 +1,107 @@
+/**
+ * @fileoverview LarkCliWorkflowNotifyHook - 把 workflow run 进展同步到飞书群
+ *
+ * Part 2：在 workflow 生命周期 Hook 上，把「run 进展」渲染成**一张可更新 + 置顶的
+ * 飞书卡片** —— 完全复用 task 通知的卡片引擎 `LarkCardPatchNotifier`（同一套
+ * 卡片骨架 / lark-cli 参数契约 / pin-unpin 逻辑），不新写 lark-cli 封装。
+ *
+ * 生命周期映射：
+ *   - `workflow:before.run`  → notifier.startWorkflow（发卡 + pin）
+ *   - `workflow:before.node` → notifier.updateWorkflow（patch 同一卡片；节流）
+ *   - `workflow:after.node`  → notifier.updateWorkflow（patch 同一卡片；节点里程碑/进度）
+ *   - `workflow:after.run`   → notifier.finishWorkflow（终态 patch + unpin + 清理跟踪）
+ *
+ * ── 触发群 / 身份（与 task 插件一致）──────────────────────────────────
+ * workflow Hook 由 engine 触发，其 ALS 上下文继承自触发它的 agent query
+ * （`workflow_run` 工具）—— 因此 `getEnvContextOrEmpty().replyChannel`
+ * （chatId / profile / messageId）应该可达。若取不到 chatId → **安全跳过**
+ * （不抛错、不发到错误的群）。
+ *
+ * ── 单卡片语义 ────────────────────────────────────────────────────────
+ * 同一 runId 全程只建一张卡（`cardMessageIds` 按 runId 跟踪 messageId），
+ * 节点事件只 patch 这张卡（不刷屏）；终态后清理跟踪项。
+ *
+ * ⚠️ 关键契约：`globalHookManager.execute(point, data, metadata)` 会把 data 包进
+ *   `HookContext` —— hook 收到的第 1 个参数是 **ctx**，载荷在 **ctx.data**。
+ */
+import type { Hook, HookContext } from "../../hook/types";
+import { LarkCardPatchNotifier } from "../../task/plugins/lark-card-patch-notifier";
+export interface WorkflowNotifyConfig {
+    /** 是否启用（默认 true） */
+    enabled?: boolean;
+    /** 优先级（默认 5） */
+    priority?: number;
+    /** 插件名称（用于 pluginEnabled 检查） */
+    pluginName?: string;
+    /** 事件源 ID（用于 pluginEnabled 检查） */
+    sourceId?: string;
+    /**
+     * 节点「开始」事件的节流间隔（毫秒）
+     *
+     * `workflow:before.node` 在大 DAG 上高频触发，不加节流会频繁 patch 卡片。
+     * 默认 3000ms；设为 0 表示不节流。
+     *
+     * ★ 只节流 `before.node`（"开始"），`after.node` / `after.run` 永远 patch ——
+     *   节点完成/终态是进度分子与终态卡片的来源，丢了会让卡片停在旧状态。
+     */
+    nodeThrottleMs?: number;
+    /**
+     * LarkCardPatchNotifier 实例
+     *
+     * 不传 → plugin 自己 new 一个（messageId 由 plugin 的 Map 跟踪）。
+     */
+    cardNotifier?: LarkCardPatchNotifier;
+}
+export declare class LarkCliWorkflowNotifyHook implements Hook {
+    readonly name: string;
+    readonly priority: number;
+    readonly description?: string;
+    readonly pluginName?: string;
+    readonly sourceId?: string;
+    /**
+     * 本插件监听的 hook 点（显式声明）
+     *
+     * ★ `event-source-handlers.getPluginHookPoints()` 会优先读这个字段 —— 让
+     *   "flat execute" 插件能声明自己的 hook 点，而不是被硬编码成 task 的 4 个点。
+     */
+    readonly hookPoints: string[];
+    private readonly config;
+    /** 卡片引擎（复用 task 卡片实现） */
+    private cardNotifier?;
+    /** 卡片 messageId 跟踪（key: runId）—— 同一 run 全程复用同一张卡 */
+    private cardMessageIds;
+    /** 节点「开始」节流状态（key: `node:${runId}` → 上次 patch 时间戳） */
+    private lastNodeNotifyTimestamps;
+    /** 建卡失败哨兵：后续 update 直接 skip，避免"失败→重试→再失败"风暴 */
+    private static readonly CARD_START_FAILED_SENTINEL;
+    /** 建卡进行中哨兵：挡住同链路上的重入 update（避免重复建卡） */
+    private static readonly CARD_START_INFLIGHT_SENTINEL;
+    constructor(config?: WorkflowNotifyConfig);
+    execute(ctx: HookContext<unknown>): Promise<void>;
+    /** run 开始：建卡（标题含 workflow 名）+ pin */
+    private onBeforeRun;
+    /** 节点即将执行：patch 同一卡片（节流） */
+    private onBeforeNode;
+    /** 节点结束：patch 同一卡片（进度 + 过程记录；失败时加里程碑） */
+    private onAfterNode;
+    /** run 终态：patch 终态（completed 绿 / failed 红 / stopped 灰）+ unpin + 清理 */
+    private onAfterRun;
+    /** 建卡（+ pin）并缓存 messageId */
+    private sendCardStart;
+    /** patch 同一张卡（无卡片 / 建卡失败 / 无 chatId 时安全跳过） */
+    private patchCard;
+    /**
+     * 解析卡片目标（chatId / profile）—— 与 task 插件一致，优先 ALS replyChannel
+     *
+     * workflow 的 hook 由 engine 触发，ALS 上下文继承自触发它的 agent query
+     * （`workflow_run` 工具），因此 replyChannel 通常可达。取不到 → 调用方安全跳过。
+     */
+    private resolveTarget;
+    /** hook 载荷 → 卡片"运行栏位"元信息 */
+    private buildWorkflowMeta;
+    /** RunStatus → 卡片终态 */
+    private mapRunStatus;
+    /** 节点「开始」节流（只节流 before.node） */
+    private shouldThrottleNodeStart;
+}
+export declare function createLarkCliWorkflowNotifyHook(config?: WorkflowNotifyConfig): LarkCliWorkflowNotifyHook;

package/dist/env/workflow/plugins/workflow-json-output-plugin.d.ts

@@ -0,0 +1,166 @@
+/**
+ * Workflow JSON output extraction via agent:after.react + json-extract sub-agent.
+ *
+ * Architecture (decoupled, sub-agent based + tool self-recording):
+ * 1. Main agent runs its normal ReAct loop (plan/execute/verify) — it does NOT
+ *    know about JSON output. The main agent's tool list is clean.
+ * 2. After ReAct finishes, this plugin is invoked on `agent:after.react`.
+ * 3. The plugin creates a dynamic `workflow_submit_output` tool bound to
+ *    `hookCtx` and calls the `json-extract` sub-agent via
+ *    `agentComponent.run('json-extract', '', { sessionId, extraTools, ... })`.
+ * 4. The `json-extract` sub-agent (built-in) has one allowed tool:
+ *    `workflow_submit_output`. It reads session history and calls the tool
+ *    with the structured JSON answer.
+ * 5. The tool itself (not this plugin) writes the validated JSON to
+ *    `hookCtx.structuredOutputExtracted`. The plugin just reads it back
+ *    afterwards — no result.toolCalls inspection, no re-validation.
+ *
+ * No fallback: if the sub-agent fails to call the tool, we log a warning and
+ * return undefined. We do NOT substitute a hardcoded model.
+ */
+import type { AgentComponent } from '../../agent/agent-component';
+import type { HookContext as AgentHookContext } from '../../agent/types';
+export declare const WORKFLOW_JSON_OUTPUT_SOURCE_ID = "workflow";
+export declare const WORKFLOW_JSON_OUTPUT_PLUGIN_NAME = "json-output";
+export declare const WORKFLOW_JSON_OUTPUT_PLUGIN_KEY = "workflow:json-output";
+export declare function isWorkflowJsonOutputEnabled(pluginEnabled?: Record<string, boolean>): boolean;
+/**
+ * 注册 workflow JSON output plugin
+ *
+ * @param options.agentComponent — AgentComponent 实例，用于在 hook 中调用
+ *                                  json-extract sub-agent
+ */
+export declare function registerWorkflowJsonOutputPlugin(options?: {
+    agentComponent: AgentComponent;
+} | void): void;
+export declare function unregisterWorkflowJsonOutputPlugin(): void;
+/**
+ * For tests: set the agentComponent reference directly.
+ */
+export declare function __setPluginAgentComponentForTest(agentComponent: AgentComponent | null): void;
+/**
+ * Narrow source interface for `resolveProviderToolChoice`.
+ *
+ * Replaces the unsafe `agentComponent: any` parameter (Task #2177 review
+ * finding C-1 + A-1). Any object that exposes a `configComponent.get(key)`
+ * satisfies this contract — AgentComponent, mock test doubles, and future
+ * first-party wrappers all work.
+ *
+ * Exported so callers can type-narrow their inputs without `any`-cast.
+ */
+export interface ProviderConfigSource {
+    configComponent?: {
+        get(key: string): unknown;
+    };
+}
+/**
+ * Resolve effective toolChoice for the json-extract sub-agent.
+ *
+ * Rules (Task #2175):
+ *   1. First-party providers (openai/anthropic/google) → "required"
+ *   2. OpenAI-compatible providers with `capabilities.reasoning === true`
+ *      (deepseek / volcengine / qwen-thinking / ...) → "auto" + rely on
+ *      `maxIterations=5` retry (agent-registry.ts:432).
+ *   3. Everything else (unknown / no config) → "required" (back-compat).
+ *
+ * Anthropic + reasoning rationale (Task #2181, finding A-3 partial — Task #2177
+ * review op #16537):
+ *   Anthropic Claude with extended thinking (`thinking.type=enabled`) is
+ *   treated as first-party and unconditionally returns `'required'`.
+ *   This is supported by AI SDK v4+: Claude Sonnet 4.5 / Opus 4 with
+ *   extended thinking accepts `tool_choice: "required"` (per Anthropic
+ *   docs: https://docs.anthropic.com/en/docs/build-with-claude/extended-thinking).
+ *   The provider returns a 400 error if the model rejects
+ *   `tool_choice: "required"` — it does NOT silently drop the argument.
+ *   The OpenAI-compatible branch (`'auto'`) is reserved for providers
+ *   where reasoning silently DROPS `tool_choice` instead of erroring
+ *   (deepseek / volcengine / qwen-thinking observed behavior in Task #2175).
+ *   TODO(validation): confirm against real Anthropic SDK behavior in a
+ *   future R&D Task.
+ *
+ * Known limitation (Task #2177 review B-3): this function does NOT consult
+ * session-level provider overrides (e.g. `hookCtx.context.metadata.llmProvider`).
+ * Only the global `llm.defaultProvider` is read. If a future Task needs
+ * per-session override, update the EDGE-3 test in
+ * `workflow-json-output-plugin-provider-compat.test.ts` and document the
+ * override precedence rules.
+ *
+ * Exported for unit testing.
+ */
+export declare function resolveProviderToolChoice(source: ProviderConfigSource | null | undefined): "required" | "auto";
+/**
+ * Workflow JSON output extraction via agent:after.react + json-extract sub-agent.
+ *
+ * Architecture (v3 — clean extraction, Issue #1694 root-cause fix):
+ *
+ *   1. Main agent runs its normal ReAct loop. It may produce JSON in any of:
+ *      - Plain text: {"x": 1, ...}
+ *      - Markdown code block: ```json\n{"x": 1, ...}\n```
+ *      - Tool-call input (e.g., echo's message field): {"x": 1, ...}
+ *      The main agent does NOT know about workflow_submit_output. Its only
+ *      contract is "produce a JSON object somewhere in its final output".
+ *
+ *   2. After ReAct finishes, this plugin is invoked on `agent:after.react`.
+ *
+ *   3. The plugin extracts JSON from the main agent's final output via
+ *      `extractJsonFromAgentOutput()` (tries multiple patterns + validates
+ *      against the JSON schema).
+ *
+ *   4. The plugin constructs a SINGLE user query message containing the
+ *      pre-extracted JSON and calls the `json-extract` sub-agent with:
+ *        - `messages: [{ role: "user", content: "Submit this JSON: ..." }]`
+ *          (Layer 1+2 messages override — bypasses main session history,
+ *           eliminating pollution risk)
+ *        - `toolChoice: "required"` (forces LLM to call workflow_submit_output,
+ *           eliminating the non-deterministic "markdown makes me stop" bug)
+ *        - `extraTools: [workflow_submit_output]`
+ *        - `persistSession: false`
+ *
+ *   5. The submit tool (not this plugin) writes the validated JSON to
+ *      `hookCtx.structuredOutputExtracted`. The plugin just reads it back.
+ *
+ * Why this works where the previous design failed:
+ *   - Previous: sub-agent reuses main session history. The history contains
+ *     echo tool-calls + markdown code blocks + thinking blocks, all of which
+ *     pollute the sub-agent's reasoning and cause non-deterministic
+ *     finishReason=stop (no tool call).
+ *   - Now: sub-agent sees ONLY one user message with the pre-extracted JSON
+ *     and the schema prompt. The LLM cannot be confused by polluted history
+ *     because there is no polluted history.
+ */
+export declare function runWorkflowJsonOutputExtraction(hookCtx: AgentHookContext & {
+    structuredOutputExtracted?: Record<string, unknown>;
+}): Promise<void>;
+/**
+ * Extract a JSON object from the main agent's final output.
+ *
+ * Tries multiple patterns (in order):
+ *   1. `hookCtx.llmOutput.content` (if non-empty)
+ *   2. Last assistant message text part
+ *   3. Last assistant message tool-call input (string or { message: ... })
+ *
+ * Within each pattern, tries (in order):
+ *   1. Direct JSON.parse
+ *   2. Markdown ```json ... ``` code block
+ *   3. First {...} substring
+ *
+ * Returns null if all attempts fail.
+ *
+ * Exported for testing.
+ */
+export declare function extractJsonFromAgentOutput(hookCtx: AgentHookContext): Record<string, unknown> | null;
+/**
+ * Try to parse a JSON object from arbitrary text using 3 strategies:
+ *   1. Whole text is JSON
+ *   2. Markdown ```json ... ``` code block
+ *   3. First {...} substring
+ *
+ * Returns null if no valid JSON object is found.
+ *
+ * 2026-10-16：实现已抽到 `src/utils/loose-json`（session 压缩的 checkpoint
+ * 降级路径也要用同一个解析器，避免 session → workflow/plugins 反向耦合）。
+ * 此处 re-export，历史 import 路径（含测试）不变。
+ */
+import { tryParseJsonFromText } from '../../../utils/loose-json';
+export { tryParseJsonFromText };
+export declare const tracedRunWorkflowJsonOutputExtraction: typeof runWorkflowJsonOutputExtraction;

package/dist/env/workflow/runtime/runtime-cancellation-scope.d.ts

@@ -0,0 +1,121 @@
+/**
+ * @fileoverview RuntimeCancellationScope — structured cancellation contract
+ * owned by each workflow session (Task #2275).
+ *
+ * Why this exists:
+ *   Before Task #2275, the engine's stop path was a loose combination of
+ *   metadata update + executor.cancelAll() + cache eviction. The underlying
+ *   `runWorkflow()` Promise could remain pending, cooperative runners could
+ *   ignore a graceful signal, retry-backoff timers could survive a stop, and
+ *   a second ESC had nothing to escalate.
+ *
+ *   `RuntimeCancellationScope` is the single, observable, runtime-owned
+ *   cancellation surface. The engine creates one scope per active session,
+ *   every node executor and AgentComponent receives the same scope (via
+ *   `context.cancellationScope` + `context.abortSignal`), and the engine
+ *   `stop()` path drives the scope through a deterministic state machine:
+ *
+ *       running ──cancel()──► graceful ──cancel({force:true})──► force
+ *
+ *   Each transition records the reason on its AbortSignal and fires
+ *   registered cleanup handlers. The engine `waitForCleanup()` resolves
+ *   once every tracked Promise has settled (or a bounded timeout elapses).
+ *
+ * Contract:
+ *   - `signal`: combined "graceful+force" AbortSignal that listeners may
+ *     use as a single source. Equivalent to `AbortSignal.any([...])`.
+ *   - `forceSignal`: fires ONLY on `cancel({force:true})`. Useful for
+ *     real-process kill paths that must not be triggered by a polite stop.
+ *   - `level`: "running" | "graceful" | "force" — reflects current state.
+ *   - `track(label, work)`: returns `work`'s settled Promise. Work identity
+ *     (the Promise instance) is removed from tracking once it settles. Work
+ *     errors propagate (NOT swallowed).
+ *   - `onForce(label, handler)`: registers a handler invoked when the scope
+ *     enters `force`. Returns an unsubscribe function.
+ *   - `cancel(reason, options?)`: transitions to graceful OR force. Idempotent.
+ *     Returns a CleanupReport aggregating handler errors.
+ *   - `waitForCleanup(timeoutMs)`: returns once all tracked work settles or
+ *     the timeout elapses.
+ */
+/**
+ * Cancellation level reflects the current escalation stage of a scope.
+ *   - "running": no cancellation requested yet.
+ *   - "graceful": `cancel()` was called but no force yet.
+ *   - "force": `cancel({force:true})` was called.
+ */
+export type CancellationLevel = "running" | "graceful" | "force";
+/**
+ * CleanupReport aggregates the outcome of `cancel()` and `waitForCleanup()`.
+ *   - `completed`: true when every tracked Promise has settled.
+ *   - `pendingLabels`: labels of work still pending at report time.
+ *   - `errors`: cleanup-handler errors (NOT tracked-work errors).
+ */
+export interface CleanupReport {
+    completed: boolean;
+    pendingLabels: string[];
+    errors: Array<{
+        label: string;
+        error: string;
+    }>;
+}
+/**
+ * RuntimeCancellationScope — runtime-owned cancellation/cleanup contract.
+ *
+ * Thread-safety: single-threaded JavaScript; no concurrent access concerns.
+ *
+ * Idempotency:
+ *   - `cancel()` after a graceful cancel is a no-op (no re-fire, no state change).
+ *   - `cancel({force:true})` after a graceful cancel escalates to force and
+ *     fires force handlers exactly once.
+ *   - `cancel({force:true})` after a force cancel is a no-op.
+ */
+export declare class RuntimeCancellationScope {
+    /** Graceful AbortController — fires on `cancel()` (any reason). */
+    private readonly gracefulController;
+    /** Force AbortController — fires only on `cancel({force:true})`. */
+    private readonly forceController;
+    /** Combined signal — fires on graceful OR force. */
+    readonly signal: AbortSignal;
+    /** Force-only signal — fires only on `cancel({force:true})`. */
+    readonly forceSignal: AbortSignal;
+    /** Current cancellation level. */
+    private _level;
+    /** Tracked cleanup work, keyed by Promise identity. */
+    private trackedWork;
+    /** Registered force handlers, in registration order. */
+    private forceHandlers;
+    /** Captured handler errors from the most recent force fire. */
+    private forceHandlerErrors;
+    constructor();
+    get level(): CancellationLevel;
+    /**
+     * Track a Promise as cleanup work. Returns the work's settled Promise.
+     * Work errors propagate (NOT swallowed) — the engine propagates them to
+     * its own completedPromise via the existing error path.
+     */
+    track<T>(label: string, work: Promise<T>): Promise<T>;
+    /**
+     * Register a force handler. Handler is invoked when the scope enters
+     * `force`. Returns an unsubscribe function that detaches the handler.
+     *
+     * Handlers run in registration order. If a handler throws, the error is
+     * captured into `CleanupReport.errors`; subsequent handlers still run.
+     */
+    onForce(label: string, handler: () => void | Promise<void>): () => void;
+    /**
+     * Cancel the scope. Transitions:
+     *   running → graceful: on any cancel() call.
+     *   graceful → force:   on cancel({force:true}).
+     *   force → force:      no-op (handlers do not re-fire).
+     *
+     * Returns a CleanupReport describing handler errors and pending work.
+     */
+    cancel(reason: string, options?: {
+        force?: boolean;
+    }): Promise<CleanupReport>;
+    /**
+     * Wait until every tracked Promise settles, or the timeout elapses.
+     * Returns a CleanupReport.
+     */
+    waitForCleanup(timeoutMs: number): Promise<CleanupReport>;
+}

package/dist/env/workflow/service/index.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Service Index - Session-based Workflow Service
+ *
+ * After refactoring, RunRepository is removed. Workflow runs are managed via SessionComponent.
+ */
+export { WorkflowService } from './workflow-service';
+export type { WorkflowRepository, WorkflowEngine, CreateOptions, ListOptions, WorkflowUpdates, WorkflowEngineFactory, SessionInfo, WorkflowSessionMetadata, AgentSessionRef, } from './workflow-service';
+export { WorkflowServiceRegistry, getWorkflowService, registerWorkflowService, } from './registry';
+export type { WorkflowDefinition } from '../types/workflow';

package/dist/env/workflow/service/registry.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Registry - Singleton registry for accessing WorkflowService
+ */
+import { WorkflowService } from './workflow-service';
+/**
+ * Singleton registry for WorkflowService
+ * Provides centralized access to the workflow service instance
+ */
+export declare class WorkflowServiceRegistry {
+    private static instance;
+    private service;
+    private constructor();
+    /**
+     * Get the singleton registry instance
+     */
+    static getInstance(): WorkflowServiceRegistry;
+    /**
+     * Register a WorkflowService instance
+     */
+    register(service: WorkflowService): void;
+    /**
+     * Get the registered WorkflowService instance
+     * @throws Error if no service is registered
+     */
+    get(): WorkflowService;
+    /**
+     * Check if a service is registered
+     */
+    isRegistered(): boolean;
+    /**
+     * Reset the registry (primarily for testing)
+     */
+    reset(): void;
+}
+export declare function getWorkflowService(): WorkflowService;
+export declare function registerWorkflowService(service: WorkflowService): void;
+export type { WorkflowService };