@xopcai/xopc 0.0.87 → 0.0.89

package/dist/src/workflows/runtime/index.d.ts

@@ -0,0 +1 @@
+export * from './script-runtime.js';

package/dist/src/workflows/runtime/index.js

@@ -0,0 +1,4 @@
+import { parseWorkflowScript } from "../../agent/workflow/parser.js";
+import { runWorkflow } from "../../agent/workflow/runtime.js";
+import "./script-runtime.js";
+export { parseWorkflowScript, runWorkflow as runWorkflowScript };

package/dist/src/workflows/runtime/script-runtime.d.ts

@@ -0,0 +1,3 @@
+export { parseWorkflowScript } from '../../agent/workflow/parser.js';
+export { runWorkflow as runWorkflowScript } from '../../agent/workflow/runtime.js';
+export type { SubagentRunner as WorkflowScriptSubagentRunner, WorkflowRunOptions as WorkflowScriptRunOptions, WorkflowRunResult as WorkflowScriptRunResult, } from '../../agent/workflow/types.js';

package/dist/src/workflows/runtime/script-runtime.js

@@ -0,0 +1,3 @@
+import { parseWorkflowScript } from "../../agent/workflow/parser.js";
+import { runWorkflow } from "../../agent/workflow/runtime.js";
+export { parseWorkflowScript, runWorkflow as runWorkflowScript };

package/dist/src/workflows/service/run-view-to-snapshot.d.ts

@@ -0,0 +1,4 @@
+import type { WorkflowSnapshot } from '../../agent/workflow/types.js';
+import type { WorkflowRunView } from '../domain/index.js';
+/** Map persisted {@link WorkflowRunView} into chat {@link WorkflowSnapshot}. */
+export declare function runViewToSnapshot(view: WorkflowRunView): WorkflowSnapshot;

package/dist/src/workflows/service/run-view-to-snapshot.js

@@ -0,0 +1,61 @@
+//#region src/workflows/service/run-view-to-snapshot.ts
+function agentNumericId(id, index) {
+	const parsed = Number.parseInt(id, 10);
+	if (Number.isFinite(parsed)) return parsed;
+	return index + 1;
+}
+function resolveResultPayload(result) {
+	if (result == null) return void 0;
+	if (typeof result === "object" && result !== null && "raw" in result) {
+		const raw = result.raw;
+		return raw !== void 0 ? raw : result;
+	}
+	return result;
+}
+/** Map persisted {@link WorkflowRunView} into chat {@link WorkflowSnapshot}. */
+function runViewToSnapshot(view) {
+	const phaseTitleById = new Map(view.phases.map((phase) => [phase.id, phase.title]));
+	const runningPhase = view.phases.find((phase) => phase.status === "running");
+	const agents = view.agents.map((agent, index) => ({
+		id: agentNumericId(agent.id, index),
+		label: agent.label,
+		phase: agent.phaseId ? phaseTitleById.get(agent.phaseId) : void 0,
+		prompt: agent.prompt ?? "",
+		status: agent.status,
+		resultPreview: agent.resultPreview,
+		error: agent.error,
+		startedAtMs: agent.startedAtMs,
+		durationMs: agent.startedAtMs != null && agent.completedAtMs != null ? agent.completedAtMs - agent.startedAtMs : void 0,
+		currentStep: agent.currentStep,
+		steps: agent.steps?.map((step) => ({
+			id: step.id,
+			kind: step.kind,
+			toolName: step.kind === "tool" ? step.label : void 0,
+			label: step.label,
+			detail: step.detail,
+			status: step.status,
+			startedAtMs: step.startedAtMs,
+			durationMs: step.startedAtMs != null && step.completedAtMs != null ? step.completedAtMs - step.startedAtMs : void 0
+		}))
+	}));
+	const { metrics } = view.run;
+	return {
+		name: view.run.definitionId,
+		description: view.run.goal || view.run.title,
+		phases: view.phases.map((phase) => phase.title),
+		currentPhase: runningPhase?.title,
+		logs: view.logs.map((entry) => entry.message),
+		agents,
+		agentCount: metrics.agentCount,
+		runningCount: Math.max(0, metrics.agentCount - metrics.doneAgentCount - metrics.errorAgentCount - metrics.skippedAgentCount),
+		doneCount: metrics.doneAgentCount,
+		errorCount: metrics.errorAgentCount,
+		skippedCount: metrics.skippedAgentCount,
+		durationMs: metrics.durationMs,
+		result: resolveResultPayload(view.run.result)
+	};
+}
+//#endregion
+export { runViewToSnapshot };
+
+//# sourceMappingURL=run-view-to-snapshot.js.map

package/dist/src/workflows/service/run-view-to-snapshot.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"run-view-to-snapshot.js","names":[],"sources":["../../../../src/workflows/service/run-view-to-snapshot.ts"],"sourcesContent":["import type { WorkflowSnapshot } from '../../agent/workflow/types.js';\nimport type { WorkflowRunView } from '../domain/index.js';\n\nfunction agentNumericId(id: string, index: number): number {\n  const parsed = Number.parseInt(id, 10);\n  if (Number.isFinite(parsed)) return parsed;\n  return index + 1;\n}\n\nfunction resolveResultPayload(result: WorkflowRunView['run']['result']): unknown {\n  if (result == null) return undefined;\n  if (typeof result === 'object' && result !== null && 'raw' in result) {\n    const raw = (result as { raw?: unknown }).raw;\n    return raw !== undefined ? raw : result;\n  }\n  return result;\n}\n\n/** Map persisted {@link WorkflowRunView} into chat {@link WorkflowSnapshot}. */\nexport function runViewToSnapshot(view: WorkflowRunView): WorkflowSnapshot {\n  const phaseTitleById = new Map(view.phases.map((phase) => [phase.id, phase.title]));\n  const runningPhase = view.phases.find((phase) => phase.status === 'running');\n\n  const agents = view.agents.map((agent, index) => ({\n    id: agentNumericId(agent.id, index),\n    label: agent.label,\n    phase: agent.phaseId ? phaseTitleById.get(agent.phaseId) : undefined,\n    prompt: agent.prompt ?? '',\n    status: agent.status,\n    resultPreview: agent.resultPreview,\n    error: agent.error,\n    startedAtMs: agent.startedAtMs,\n    durationMs:\n      agent.startedAtMs != null && agent.completedAtMs != null\n        ? agent.completedAtMs - agent.startedAtMs\n        : undefined,\n    currentStep: agent.currentStep,\n    steps: agent.steps?.map((step) => ({\n      id: step.id,\n      kind: step.kind,\n      toolName: step.kind === 'tool' ? step.label : undefined,\n      label: step.label,\n      detail: step.detail,\n      status: step.status,\n      startedAtMs: step.startedAtMs,\n      durationMs:\n        step.startedAtMs != null && step.completedAtMs != null\n          ? step.completedAtMs - step.startedAtMs\n          : undefined,\n    })),\n  }));\n\n  const { metrics } = view.run;\n  return {\n    name: view.run.definitionId,\n    description: view.run.goal || view.run.title,\n    phases: view.phases.map((phase) => phase.title),\n    currentPhase: runningPhase?.title,\n    logs: view.logs.map((entry) => entry.message),\n    agents,\n    agentCount: metrics.agentCount,\n    runningCount: Math.max(\n      0,\n      metrics.agentCount - metrics.doneAgentCount - metrics.errorAgentCount - metrics.skippedAgentCount,\n    ),\n    doneCount: metrics.doneAgentCount,\n    errorCount: metrics.errorAgentCount,\n    skippedCount: metrics.skippedAgentCount,\n    durationMs: metrics.durationMs,\n    result: resolveResultPayload(view.run.result),\n  };\n}\n"],"mappings":";AAGA,SAAS,eAAe,IAAY,OAAuB;CACzD,MAAM,SAAS,OAAO,SAAS,IAAI,GAAG;AACtC,KAAI,OAAO,SAAS,OAAO,CAAE,QAAO;AACpC,QAAO,QAAQ;;AAGjB,SAAS,qBAAqB,QAAmD;AAC/E,KAAI,UAAU,KAAM,QAAO,KAAA;AAC3B,KAAI,OAAO,WAAW,YAAY,WAAW,QAAQ,SAAS,QAAQ;EACpE,MAAM,MAAO,OAA6B;AAC1C,SAAO,QAAQ,KAAA,IAAY,MAAM;;AAEnC,QAAO;;;AAIT,SAAgB,kBAAkB,MAAyC;CACzE,MAAM,iBAAiB,IAAI,IAAI,KAAK,OAAO,KAAK,UAAU,CAAC,MAAM,IAAI,MAAM,MAAM,CAAC,CAAC;CACnF,MAAM,eAAe,KAAK,OAAO,MAAM,UAAU,MAAM,WAAW,UAAU;CAE5E,MAAM,SAAS,KAAK,OAAO,KAAK,OAAO,WAAW;EAChD,IAAI,eAAe,MAAM,IAAI,MAAM;EACnC,OAAO,MAAM;EACb,OAAO,MAAM,UAAU,eAAe,IAAI,MAAM,QAAQ,GAAG,KAAA;EAC3D,QAAQ,MAAM,UAAU;EACxB,QAAQ,MAAM;EACd,eAAe,MAAM;EACrB,OAAO,MAAM;EACb,aAAa,MAAM;EACnB,YACE,MAAM,eAAe,QAAQ,MAAM,iBAAiB,OAChD,MAAM,gBAAgB,MAAM,cAC5B,KAAA;EACN,aAAa,MAAM;EACnB,OAAO,MAAM,OAAO,KAAK,UAAU;GACjC,IAAI,KAAK;GACT,MAAM,KAAK;GACX,UAAU,KAAK,SAAS,SAAS,KAAK,QAAQ,KAAA;GAC9C,OAAO,KAAK;GACZ,QAAQ,KAAK;GACb,QAAQ,KAAK;GACb,aAAa,KAAK;GAClB,YACE,KAAK,eAAe,QAAQ,KAAK,iBAAiB,OAC9C,KAAK,gBAAgB,KAAK,cAC1B,KAAA;GACP,EAAE;EACJ,EAAE;CAEH,MAAM,EAAE,YAAY,KAAK;AACzB,QAAO;EACL,MAAM,KAAK,IAAI;EACf,aAAa,KAAK,IAAI,QAAQ,KAAK,IAAI;EACvC,QAAQ,KAAK,OAAO,KAAK,UAAU,MAAM,MAAM;EAC/C,cAAc,cAAc;EAC5B,MAAM,KAAK,KAAK,KAAK,UAAU,MAAM,QAAQ;EAC7C;EACA,YAAY,QAAQ;EACpB,cAAc,KAAK,IACjB,GACA,QAAQ,aAAa,QAAQ,iBAAiB,QAAQ,kBAAkB,QAAQ,kBACjF;EACD,WAAW,QAAQ;EACnB,YAAY,QAAQ;EACpB,cAAc,QAAQ;EACtB,YAAY,QAAQ;EACpB,QAAQ,qBAAqB,KAAK,IAAI,OAAO;EAC9C"}

package/dist/src/workflows/service/workflow-run-service.d.ts

@@ -0,0 +1,36 @@
+import type { AgentTool } from '@earendil-works/pi-agent-core';
+import type { BuildChildToolsOptions } from '../../agent/child-agent-factory.js';
+import type { GatewayWorkflowHost } from '../../gateway/gateway-workflow-host.types.js';
+import type { WorkflowDefinition, WorkflowRunDefinitionSnapshot, WorkflowRunInputEnvelope, WorkflowRunMetadata, WorkflowRunSource } from '../domain/index.js';
+import { WorkflowRunStore } from '../store/run-store.js';
+import type { WorkflowSessionBridge } from './workflow-session-bridge.js';
+export type { CancelWorkflowRunResult, CancelWorkflowRunServiceParams, CancelWorkflowRunServiceResult, RetryWorkflowRunServiceParams, StartWorkflowRunServiceParams, StartWorkflowRunServiceResult, WorkflowRunServiceErrorCode, WorkflowRunServiceErrorResult, WorkflowRunServiceResult, } from './workflow-run-service.types.js';
+import type { CancelWorkflowRunResult, CancelWorkflowRunServiceParams, RetryWorkflowRunServiceParams, StartWorkflowRunServiceParams, WorkflowRunServiceResult } from './workflow-run-service.types.js';
+export interface WorkflowRunServiceOptions {
+    service: GatewayWorkflowHost;
+    sessionBridge: WorkflowSessionBridge;
+    buildChildTools: (childOptions: BuildChildToolsOptions) => AgentTool<any, any>[];
+}
+export declare class WorkflowRunService {
+    private readonly options;
+    private readonly activeRuns;
+    constructor(options: WorkflowRunServiceOptions);
+    startWorkflowRun(params: StartWorkflowRunServiceParams): Promise<WorkflowRunServiceResult>;
+    retryWorkflowRun(params: RetryWorkflowRunServiceParams): Promise<WorkflowRunServiceResult>;
+    cancelWorkflowRun(params: CancelWorkflowRunServiceParams): Promise<CancelWorkflowRunResult>;
+    createRunStore(agentId: string): WorkflowRunStore;
+    private loadDefinition;
+    private createWorkflowEngine;
+}
+export declare function buildWorkflowRunInputEnvelope(input: unknown, goal?: string): WorkflowRunInputEnvelope;
+export declare function buildWorkflowRunMetadata(params: {
+    definition: WorkflowDefinition;
+    agentId: string;
+    sessionKey: string;
+    source: WorkflowRunSource;
+    input: WorkflowRunInputEnvelope;
+    retryOfRunId?: string;
+    idempotencyKey?: string;
+}): WorkflowRunMetadata;
+export declare function buildWorkflowRunDefinitionSnapshot(definition: WorkflowDefinition): WorkflowRunDefinitionSnapshot;
+export declare function extractWorkflowRunSessionKey(source: WorkflowRunSource): string | null;

package/dist/src/workflows/service/workflow-run-service.js

@@ -0,0 +1,279 @@
+import { extractProfileAgentId } from "../../config/agent-profile.js";
+import { init_providers, resolveModel } from "../../providers/index.js";
+import { createWorkflowCatalog } from "../../agent/workflow/catalog.js";
+import { DelegateSubagentRunner } from "../../agent/workflow/subagent-runner.js";
+import { resolveModelRef } from "../../config/agent-typed-models.js";
+import { buildWorkflowDefinition } from "../domain/definition-utils.js";
+import { isTerminalWorkflowRunStatus } from "../domain/run.js";
+import "../domain/index.js";
+import { WorkflowEngine } from "../engine/workflow-engine.js";
+import "../engine/index.js";
+import { WorkflowEventStore } from "../store/event-store.js";
+import { WorkflowRunStore } from "../store/run-store.js";
+import { randomUUID } from "node:crypto";
+//#region src/workflows/service/workflow-run-service.ts
+init_providers();
+var WorkflowRunService = class {
+	activeRuns = /* @__PURE__ */ new Map();
+	constructor(options) {
+		this.options = options;
+	}
+	async startWorkflowRun(params) {
+		const definition = this.loadDefinition(params.definitionId);
+		if (!definition) return {
+			ok: false,
+			code: "definition_not_found",
+			message: "Workflow definition not found",
+			httpStatus: 404
+		};
+		const runId = randomUUID();
+		const goal = params.goal ?? "";
+		const { sessionKey } = await this.options.sessionBridge.prepareRunSession({
+			runId,
+			agentId: params.agentId,
+			definitionId: params.definitionId,
+			definitionTitle: definition.title,
+			goal,
+			parentSessionKey: params.parentSessionKey
+		});
+		const source = normalizeWorkflowRunSourceForSession(params.source, sessionKey, params.parentSessionKey);
+		const abortController = new AbortController();
+		const eventStore = new WorkflowEventStore(this.options.service.currentConfig, params.agentId);
+		const runStore = new WorkflowRunStore(this.options.service.currentConfig, params.agentId, eventStore);
+		const engine = this.createWorkflowEngine({
+			eventStore,
+			runStore,
+			sessionKey
+		});
+		const inputEnvelope = params.inputEnvelope ?? buildWorkflowRunInputEnvelope(params.input, params.goal);
+		this.activeRuns.set(runId, abortController);
+		engine.startRun(definition, {
+			runId,
+			input: inputEnvelope.payload,
+			goal: inputEnvelope.goal ?? params.goal,
+			source,
+			metadata: buildWorkflowRunMetadata({
+				definition,
+				agentId: params.agentId,
+				sessionKey,
+				source,
+				input: inputEnvelope,
+				retryOfRunId: params.retryOfRunId,
+				idempotencyKey: params.idempotencyKey
+			}),
+			signal: abortController.signal,
+			concurrency: params.concurrency,
+			maxSubagents: params.maxSubagents,
+			tokenBudget: params.tokenBudget
+		}).catch((err) => {
+			this.options.service.emit("workflow.run.error", {
+				runId,
+				error: err instanceof Error ? err.message : String(err)
+			});
+		}).finally(() => {
+			this.activeRuns.delete(runId);
+		});
+		return {
+			ok: true,
+			runId,
+			sessionKey
+		};
+	}
+	async retryWorkflowRun(params) {
+		const existing = await this.createRunStore(params.agentId).readRunView(params.runId);
+		if (!existing) return {
+			ok: false,
+			code: "run_not_found",
+			message: "Workflow run not found",
+			httpStatus: 404
+		};
+		const parentSessionKey = existing.run.source.kind === "chat" ? existing.run.source.sessionKey : void 0;
+		return this.startWorkflowRun({
+			agentId: params.agentId,
+			definitionId: existing.run.definitionId,
+			input: existing.run.input,
+			goal: existing.run.goal,
+			source: existing.run.source,
+			parentSessionKey,
+			retryOfRunId: existing.run.id
+		});
+	}
+	async cancelWorkflowRun(params) {
+		const controller = this.activeRuns.get(params.runId);
+		if (controller) {
+			controller.abort();
+			this.activeRuns.delete(params.runId);
+			return {
+				ok: true,
+				cancelled: true
+			};
+		}
+		const runStore = this.createRunStore(params.agentId);
+		const view = await runStore.readRunView(params.runId);
+		if (!view) return {
+			ok: false,
+			code: "run_not_found",
+			message: "Workflow run not found",
+			httpStatus: 404
+		};
+		if (isTerminalWorkflowRunStatus(view.run.status)) return {
+			ok: true,
+			cancelled: true,
+			alreadyFinished: true
+		};
+		await new WorkflowEventStore(this.options.service.currentConfig, params.agentId).append({
+			runId: params.runId,
+			type: "run_cancelled",
+			payload: { reason: params.reason ?? "Cancelled by user" }
+		});
+		const updated = await runStore.rebuildRunView(params.runId);
+		if (updated) {
+			this.options.service.emit("workflow.run.updated", {
+				runId: params.runId,
+				view: updated
+			});
+			this.options.sessionBridge.handleRunViewUpdated(updated);
+		}
+		return {
+			ok: true,
+			cancelled: true
+		};
+	}
+	createRunStore(agentId) {
+		const eventStore = new WorkflowEventStore(this.options.service.currentConfig, agentId);
+		return new WorkflowRunStore(this.options.service.currentConfig, agentId, eventStore);
+	}
+	loadDefinition(definitionId) {
+		const catalog = createWorkflowCatalog();
+		try {
+			const loaded = catalog.load(definitionId);
+			return buildWorkflowDefinition({
+				name: loaded.name,
+				source: loaded.source,
+				script: loaded.script,
+				meta: loaded.meta
+			});
+		} catch {
+			return null;
+		}
+	}
+	createWorkflowEngine(params) {
+		const gatewayService = this.options.service;
+		const runner = new DelegateSubagentRunner({
+			workspace: gatewayService.currentWorkspacePath,
+			bus: gatewayService.messageBusInstance,
+			getDefaultModel: () => resolveModel(gatewayService.agentService.getModelForSession(params.sessionKey)),
+			getConfig: () => gatewayService.currentConfig,
+			buildChildTools: (childOptions) => this.options.buildChildTools(childOptions)
+		});
+		return new WorkflowEngine({
+			cwd: gatewayService.currentWorkspacePath,
+			eventStore: params.eventStore,
+			runStore: params.runStore,
+			runner,
+			resolveModelId: (modelId) => {
+				const agentId = extractProfileAgentId(params.sessionKey, gatewayService.currentConfig);
+				return resolveModel(resolveModelRef(gatewayService.currentConfig, agentId, modelId));
+			},
+			onEventAppended: (event) => {
+				gatewayService.emit("workflow.event.appended", {
+					runId: event.runId,
+					event
+				});
+			},
+			onRunViewUpdated: (view) => {
+				gatewayService.emit("workflow.run.updated", {
+					runId: view.run.id,
+					view
+				});
+				this.options.sessionBridge.handleRunViewUpdated(view);
+			}
+		});
+	}
+};
+function normalizeWorkflowRunSourceForSession(source, workflowSessionKey, parentSessionKey) {
+	if (parentSessionKey?.trim()) return {
+		kind: "chat",
+		sessionKey: parentSessionKey.trim()
+	};
+	if (source.kind === "webui") return {
+		...source,
+		sessionKey: workflowSessionKey
+	};
+	if (source.kind === "chat") return source;
+	return source;
+}
+function buildWorkflowRunInputEnvelope(input, goal) {
+	if (isWorkflowRunInputEnvelope(input)) return input;
+	return {
+		payload: input ?? {},
+		goal
+	};
+}
+function buildWorkflowRunMetadata(params) {
+	return {
+		sessionKey: params.sessionKey,
+		triggerSource: params.source.kind,
+		agentId: params.agentId,
+		retryOfRunId: params.retryOfRunId,
+		definition: buildWorkflowRunDefinitionSnapshot(params.definition),
+		input: params.input,
+		correlation: { idempotencyKey: params.idempotencyKey },
+		origin: buildWorkflowRunOrigin(params.source),
+		schedule: params.source.kind === "cron" ? {
+			scheduleId: params.source.scheduleId,
+			fireId: params.source.fireId
+		} : void 0
+	};
+}
+function buildWorkflowRunDefinitionSnapshot(definition) {
+	return {
+		id: definition.id,
+		name: definition.name,
+		title: definition.title,
+		version: definition.version,
+		source: definition.metadata.source,
+		tags: [...definition.metadata.tags],
+		phaseCount: definition.phases.length,
+		estimatedAgents: definition.metadata.estimatedAgents
+	};
+}
+function extractWorkflowRunSessionKey(source) {
+	if ("sessionKey" in source && typeof source.sessionKey === "string" && source.sessionKey.trim()) return source.sessionKey.trim();
+	return null;
+}
+function buildWorkflowRunOrigin(source) {
+	switch (source.kind) {
+		case "chat": return {
+			channel: "chat",
+			sessionKey: source.sessionKey,
+			messageId: source.messageId
+		};
+		case "webui": return {
+			channel: "webui",
+			sessionKey: source.sessionKey
+		};
+		case "cron": return {
+			channel: "cron",
+			scheduleId: source.scheduleId,
+			fireId: source.fireId
+		};
+		case "api": return {
+			channel: "api",
+			requestId: source.requestId
+		};
+		case "im": return {
+			channel: source.channel,
+			chatId: source.chatId,
+			messageId: source.messageId
+		};
+	}
+}
+function isWorkflowRunInputEnvelope(input) {
+	if (!input || typeof input !== "object" || Array.isArray(input)) return false;
+	return "payload" in input || "variables" in input || "context" in input;
+}
+//#endregion
+export { WorkflowRunService, buildWorkflowRunDefinitionSnapshot, buildWorkflowRunInputEnvelope, buildWorkflowRunMetadata, extractWorkflowRunSessionKey };
+
+//# sourceMappingURL=workflow-run-service.js.map

package/dist/src/workflows/service/workflow-run-service.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"workflow-run-service.js","names":["resolveModelById"],"sources":["../../../../src/workflows/service/workflow-run-service.ts"],"sourcesContent":["import { randomUUID } from 'node:crypto';\n\nimport type { AgentTool } from '@earendil-works/pi-agent-core';\n\nimport type { BuildChildToolsOptions } from '../../agent/child-agent-factory.js';\nimport { extractProfileAgentId } from '../../config/agent-profile.js';\nimport { resolveModelRef } from '../../config/agent-typed-models.js';\nimport type { GatewayWorkflowHost } from '../../gateway/gateway-workflow-host.types.js';\nimport { resolveModel as resolveModelById } from '../../providers/index.js';\nimport { createWorkflowCatalog } from '../../agent/workflow/catalog.js';\nimport { DelegateSubagentRunner } from '../../agent/workflow/subagent-runner.js';\nimport type {\n  WorkflowDefinition,\n  WorkflowRunDefinitionSnapshot,\n  WorkflowRunInputEnvelope,\n  WorkflowRunMetadata,\n  WorkflowRunSource,\n} from '../domain/index.js';\nimport { buildWorkflowDefinition, isTerminalWorkflowRunStatus } from '../domain/index.js';\nimport { WorkflowEngine } from '../engine/index.js';\nimport { WorkflowEventStore } from '../store/event-store.js';\nimport { WorkflowRunStore } from '../store/run-store.js';\nimport type { WorkflowSessionBridge } from './workflow-session-bridge.js';\nexport type {\n  CancelWorkflowRunResult,\n  CancelWorkflowRunServiceParams,\n  CancelWorkflowRunServiceResult,\n  RetryWorkflowRunServiceParams,\n  StartWorkflowRunServiceParams,\n  StartWorkflowRunServiceResult,\n  WorkflowRunServiceErrorCode,\n  WorkflowRunServiceErrorResult,\n  WorkflowRunServiceResult,\n} from './workflow-run-service.types.js';\n\nimport type {\n  CancelWorkflowRunResult,\n  CancelWorkflowRunServiceParams,\n  RetryWorkflowRunServiceParams,\n  StartWorkflowRunServiceParams,\n  WorkflowRunServiceResult,\n} from './workflow-run-service.types.js';\n\nexport interface WorkflowRunServiceOptions {\n  service: GatewayWorkflowHost;\n  sessionBridge: WorkflowSessionBridge;\n  buildChildTools: (childOptions: BuildChildToolsOptions) => AgentTool<any, any>[];\n}\n\nexport class WorkflowRunService {\n  private readonly activeRuns = new Map<string, AbortController>();\n\n  constructor(private readonly options: WorkflowRunServiceOptions) {}\n\n  async startWorkflowRun(params: StartWorkflowRunServiceParams): Promise<WorkflowRunServiceResult> {\n    const definition = this.loadDefinition(params.definitionId);\n    if (!definition) {\n      return {\n        ok: false,\n        code: 'definition_not_found',\n        message: 'Workflow definition not found',\n        httpStatus: 404,\n      };\n    }\n\n    const runId = randomUUID();\n    const goal = params.goal ?? '';\n    const { sessionKey } = await this.options.sessionBridge.prepareRunSession({\n      runId,\n      agentId: params.agentId,\n      definitionId: params.definitionId,\n      definitionTitle: definition.title,\n      goal,\n      parentSessionKey: params.parentSessionKey,\n    });\n    const source = normalizeWorkflowRunSourceForSession(params.source, sessionKey, params.parentSessionKey);\n    const abortController = new AbortController();\n    const eventStore = new WorkflowEventStore(this.options.service.currentConfig, params.agentId);\n    const runStore = new WorkflowRunStore(this.options.service.currentConfig, params.agentId, eventStore);\n    const engine = this.createWorkflowEngine({\n      eventStore,\n      runStore,\n      sessionKey,\n    });\n    const inputEnvelope = params.inputEnvelope ?? buildWorkflowRunInputEnvelope(params.input, params.goal);\n\n    this.activeRuns.set(runId, abortController);\n    void engine.startRun(definition, {\n      runId,\n      input: inputEnvelope.payload,\n      goal: inputEnvelope.goal ?? params.goal,\n      source,\n      metadata: buildWorkflowRunMetadata({\n        definition,\n        agentId: params.agentId,\n        sessionKey,\n        source,\n        input: inputEnvelope,\n        retryOfRunId: params.retryOfRunId,\n        idempotencyKey: params.idempotencyKey,\n      }),\n      signal: abortController.signal,\n      concurrency: params.concurrency,\n      maxSubagents: params.maxSubagents,\n      tokenBudget: params.tokenBudget,\n    }).catch((err) => {\n      this.options.service.emit('workflow.run.error', {\n        runId,\n        error: err instanceof Error ? err.message : String(err),\n      });\n    }).finally(() => {\n      this.activeRuns.delete(runId);\n    });\n\n    return { ok: true, runId, sessionKey };\n  }\n\n  async retryWorkflowRun(params: RetryWorkflowRunServiceParams): Promise<WorkflowRunServiceResult> {\n    const runStore = this.createRunStore(params.agentId);\n    const existing = await runStore.readRunView(params.runId);\n    if (!existing) {\n      return {\n        ok: false,\n        code: 'run_not_found',\n        message: 'Workflow run not found',\n        httpStatus: 404,\n      };\n    }\n\n    const parentSessionKey =\n      existing.run.source.kind === 'chat' ? existing.run.source.sessionKey : undefined;\n\n    return this.startWorkflowRun({\n      agentId: params.agentId,\n      definitionId: existing.run.definitionId,\n      input: existing.run.input,\n      goal: existing.run.goal,\n      source: existing.run.source,\n      parentSessionKey,\n      retryOfRunId: existing.run.id,\n    });\n  }\n\n  async cancelWorkflowRun(params: CancelWorkflowRunServiceParams): Promise<CancelWorkflowRunResult> {\n    const controller = this.activeRuns.get(params.runId);\n    if (controller) {\n      controller.abort();\n      this.activeRuns.delete(params.runId);\n      return { ok: true, cancelled: true };\n    }\n\n    const runStore = this.createRunStore(params.agentId);\n    const view = await runStore.readRunView(params.runId);\n    if (!view) {\n      return {\n        ok: false,\n        code: 'run_not_found',\n        message: 'Workflow run not found',\n        httpStatus: 404,\n      };\n    }\n\n    if (isTerminalWorkflowRunStatus(view.run.status)) {\n      return { ok: true, cancelled: true, alreadyFinished: true };\n    }\n\n    const eventStore = new WorkflowEventStore(this.options.service.currentConfig, params.agentId);\n    await eventStore.append({\n      runId: params.runId,\n      type: 'run_cancelled',\n      payload: { reason: params.reason ?? 'Cancelled by user' },\n    });\n    const updated = await runStore.rebuildRunView(params.runId);\n    if (updated) {\n      this.options.service.emit('workflow.run.updated', { runId: params.runId, view: updated });\n      void this.options.sessionBridge.handleRunViewUpdated(updated);\n    }\n    return { ok: true, cancelled: true };\n  }\n\n  createRunStore(agentId: string): WorkflowRunStore {\n    const eventStore = new WorkflowEventStore(this.options.service.currentConfig, agentId);\n    return new WorkflowRunStore(this.options.service.currentConfig, agentId, eventStore);\n  }\n\n  private loadDefinition(definitionId: string): WorkflowDefinition | null {\n    const catalog = createWorkflowCatalog();\n    try {\n      const loaded = catalog.load(definitionId);\n      return buildWorkflowDefinition({\n        name: loaded.name,\n        source: loaded.source,\n        script: loaded.script,\n        meta: loaded.meta,\n      });\n    } catch {\n      return null;\n    }\n  }\n\n  private createWorkflowEngine(params: {\n    eventStore: WorkflowEventStore;\n    runStore: WorkflowRunStore;\n    sessionKey: string;\n  }): WorkflowEngine {\n    const gatewayService = this.options.service;\n    const runner = new DelegateSubagentRunner({\n      workspace: gatewayService.currentWorkspacePath,\n      bus: gatewayService.messageBusInstance,\n      getDefaultModel: () => resolveModelById(gatewayService.agentService.getModelForSession(params.sessionKey)),\n      getConfig: () => gatewayService.currentConfig,\n      buildChildTools: (childOptions) => this.options.buildChildTools(childOptions),\n    });\n\n    return new WorkflowEngine({\n      cwd: gatewayService.currentWorkspacePath,\n      eventStore: params.eventStore,\n      runStore: params.runStore,\n      runner,\n      resolveModelId: (modelId) => {\n        const agentId = extractProfileAgentId(params.sessionKey, gatewayService.currentConfig);\n        return resolveModelById(resolveModelRef(gatewayService.currentConfig, agentId, modelId));\n      },\n      onEventAppended: (event) => {\n        gatewayService.emit('workflow.event.appended', { runId: event.runId, event });\n      },\n      onRunViewUpdated: (view) => {\n        gatewayService.emit('workflow.run.updated', { runId: view.run.id, view });\n        void this.options.sessionBridge.handleRunViewUpdated(view);\n      },\n    });\n  }\n}\n\nfunction normalizeWorkflowRunSourceForSession(\n  source: WorkflowRunSource,\n  workflowSessionKey: string,\n  parentSessionKey?: string,\n): WorkflowRunSource {\n  if (parentSessionKey?.trim()) {\n    return { kind: 'chat', sessionKey: parentSessionKey.trim() };\n  }\n  if (source.kind === 'webui') {\n    return { ...source, sessionKey: workflowSessionKey };\n  }\n  if (source.kind === 'chat') {\n    return source;\n  }\n  return source;\n}\n\nexport function buildWorkflowRunInputEnvelope(input: unknown, goal?: string): WorkflowRunInputEnvelope {\n  if (isWorkflowRunInputEnvelope(input)) {\n    return input;\n  }\n  return {\n    payload: input ?? {},\n    goal,\n  };\n}\n\nexport function buildWorkflowRunMetadata(params: {\n  definition: WorkflowDefinition;\n  agentId: string;\n  sessionKey: string;\n  source: WorkflowRunSource;\n  input: WorkflowRunInputEnvelope;\n  retryOfRunId?: string;\n  idempotencyKey?: string;\n}): WorkflowRunMetadata {\n  return {\n    sessionKey: params.sessionKey,\n    triggerSource: params.source.kind,\n    agentId: params.agentId,\n    retryOfRunId: params.retryOfRunId,\n    definition: buildWorkflowRunDefinitionSnapshot(params.definition),\n    input: params.input,\n    correlation: {\n      idempotencyKey: params.idempotencyKey,\n    },\n    origin: buildWorkflowRunOrigin(params.source),\n    schedule: params.source.kind === 'cron'\n      ? { scheduleId: params.source.scheduleId, fireId: params.source.fireId }\n      : undefined,\n  };\n}\n\nexport function buildWorkflowRunDefinitionSnapshot(definition: WorkflowDefinition): WorkflowRunDefinitionSnapshot {\n  return {\n    id: definition.id,\n    name: definition.name,\n    title: definition.title,\n    version: definition.version,\n    source: definition.metadata.source,\n    tags: [...definition.metadata.tags],\n    phaseCount: definition.phases.length,\n    estimatedAgents: definition.metadata.estimatedAgents,\n  };\n}\n\nexport function extractWorkflowRunSessionKey(source: WorkflowRunSource): string | null {\n  if ('sessionKey' in source && typeof source.sessionKey === 'string' && source.sessionKey.trim()) {\n    return source.sessionKey.trim();\n  }\n  return null;\n}\n\nfunction buildWorkflowRunOrigin(source: WorkflowRunSource): WorkflowRunMetadata['origin'] {\n  switch (source.kind) {\n    case 'chat':\n      return { channel: 'chat', sessionKey: source.sessionKey, messageId: source.messageId };\n    case 'webui':\n      return { channel: 'webui', sessionKey: source.sessionKey };\n    case 'cron':\n      return { channel: 'cron', scheduleId: source.scheduleId, fireId: source.fireId };\n    case 'api':\n      return { channel: 'api', requestId: source.requestId };\n    case 'im':\n      return { channel: source.channel, chatId: source.chatId, messageId: source.messageId };\n  }\n}\n\nfunction isWorkflowRunInputEnvelope(input: unknown): input is WorkflowRunInputEnvelope {\n  if (!input || typeof input !== 'object' || Array.isArray(input)) {\n    return false;\n  }\n  return 'payload' in input || 'variables' in input || 'context' in input;\n}\n"],"mappings":"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"}

package/dist/src/workflows/service/workflow-run-service.types.d.ts

@@ -0,0 +1,47 @@
+import type { WorkflowRunInputEnvelope, WorkflowRunSource } from '../domain/index.js';
+export interface StartWorkflowRunServiceParams {
+    agentId: string;
+    definitionId: string;
+    parentSessionKey?: string;
+    input?: unknown;
+    inputEnvelope?: WorkflowRunInputEnvelope;
+    goal?: string;
+    source: WorkflowRunSource;
+    concurrency?: number;
+    maxSubagents?: number;
+    tokenBudget?: number | null;
+    retryOfRunId?: string;
+    idempotencyKey?: string;
+}
+export interface StartWorkflowRunServiceResult {
+    ok: true;
+    runId: string;
+    sessionKey: string;
+}
+export type WorkflowRunServiceErrorCode = 'definition_not_found' | 'run_not_found' | 'invalid_state';
+export interface WorkflowRunServiceErrorResult {
+    ok: false;
+    code: WorkflowRunServiceErrorCode;
+    message: string;
+    httpStatus: 400 | 404 | 409;
+}
+export type WorkflowRunServiceResult = StartWorkflowRunServiceResult | WorkflowRunServiceErrorResult;
+export interface RetryWorkflowRunServiceParams {
+    agentId: string;
+    runId: string;
+}
+export interface CancelWorkflowRunServiceParams {
+    agentId: string;
+    runId: string;
+    reason?: string;
+}
+export interface CancelWorkflowRunServiceResult {
+    ok: true;
+    cancelled: boolean;
+    alreadyFinished?: boolean;
+}
+export type CancelWorkflowRunResult = CancelWorkflowRunServiceResult | WorkflowRunServiceErrorResult;
+/** Minimal surface for agent/cron callers (avoids importing the service class). */
+export interface WorkflowRunServiceLike {
+    startWorkflowRun(params: StartWorkflowRunServiceParams): Promise<WorkflowRunServiceResult>;
+}

package/dist/src/workflows/service/workflow-run-service.types.js

@@ -0,0 +1 @@
+export {};

package/dist/src/workflows/service/workflow-session-bridge.d.ts

@@ -0,0 +1,29 @@
+import type { GatewayWorkflowHost } from '../../gateway/gateway-workflow-host.types.js';
+import type { WorkflowRunView } from '../domain/index.js';
+export declare const WORKFLOW_SESSION_TYPE = "workflow";
+export declare const WORKFLOW_RUN_LINK_CONTEXT_KIND = "workflow-run-link";
+export interface PrepareWorkflowRunSessionParams {
+    runId: string;
+    agentId: string;
+    definitionId: string;
+    definitionTitle: string;
+    goal: string;
+    parentSessionKey?: string;
+}
+export interface PrepareWorkflowRunSessionResult {
+    sessionKey: string;
+}
+export declare class WorkflowSessionBridge {
+    private readonly gateway;
+    private readonly terminalPersistedRunIds;
+    constructor(gateway: GatewayWorkflowHost);
+    prepareRunSession(params: PrepareWorkflowRunSessionParams): Promise<PrepareWorkflowRunSessionResult>;
+    handleRunViewUpdated(view: WorkflowRunView): Promise<void>;
+    private persistTerminalTranscript;
+    private writeParentRunLink;
+}
+export declare function formatParentRunLinkText(params: {
+    definitionId: string;
+    goal: string;
+    status: WorkflowRunView['run']['status'];
+}): string;