@xopcai/xopc 0.0.88 → 0.0.89

package/dist/src/workflows/domain/command.d.ts

@@ -1,9 +1,10 @@
-import type { WorkflowRunSource } from './run.js';
+import type { WorkflowRunInputEnvelope, WorkflowRunSource } from './run.js';
 export type WorkflowCommand = StartWorkflowRunCommand | CancelWorkflowRunCommand | ArchiveWorkflowRunCommand;
 export interface StartWorkflowRunCommand {
     type: 'start_run';
     definitionId: string;
     input?: unknown;
+    inputEnvelope?: WorkflowRunInputEnvelope;
     source: WorkflowRunSource;
     goal?: string;
 }

package/dist/src/workflows/domain/definition-utils.d.ts

@@ -0,0 +1,14 @@
+import type { WorkflowMeta } from '../../agent/workflow/types.js';
+import type { WorkflowDefinition } from './definition.js';
+export declare const DEFAULT_WORKFLOW_CONCURRENCY = 4;
+export declare const DEFAULT_WORKFLOW_TIMEOUT_SEC: number;
+export declare const DEFAULT_WORKFLOW_MAX_SUBAGENTS = 100;
+export interface WorkflowDefinitionBuildInput {
+    name: string;
+    source: 'builtin' | 'user';
+    script: string;
+    meta: WorkflowMeta;
+}
+export declare function buildWorkflowDefinition(input: WorkflowDefinitionBuildInput): WorkflowDefinition;
+export declare function normalizeWorkflowDefinitionId(value: string): string;
+export declare function toWorkflowDefinitionTitle(value: string): string;

package/dist/src/workflows/domain/definition-utils.js

@@ -0,0 +1,50 @@
+//#region src/workflows/domain/definition-utils.ts
+const DEFAULT_WORKFLOW_CONCURRENCY = 4;
+const DEFAULT_WORKFLOW_TIMEOUT_SEC = 1800;
+const DEFAULT_WORKFLOW_MAX_SUBAGENTS = 100;
+function buildWorkflowDefinition(input) {
+	const nowMs = Date.now();
+	const phases = input.meta.phases?.map((phase, index) => ({
+		id: normalizeWorkflowDefinitionId(phase.title) || `phase-${index + 1}`,
+		title: phase.title,
+		description: phase.detail
+	})) ?? [];
+	return {
+		id: input.name,
+		name: input.name,
+		title: toWorkflowDefinitionTitle(input.name),
+		description: input.meta.description,
+		version: "1.0.0",
+		phases,
+		runtime: {
+			kind: "script",
+			source: input.script
+		},
+		defaults: {
+			concurrency: 4,
+			timeoutSec: DEFAULT_WORKFLOW_TIMEOUT_SEC,
+			maxSubagents: input.meta.estimatedAgents?.max ?? 100
+		},
+		metadata: {
+			tags: input.meta.tags ?? [],
+			builtIn: input.source === "builtin",
+			source: input.source,
+			whenToUse: input.meta.whenToUse,
+			estimatedAgents: input.meta.estimatedAgents,
+			examplePrompts: input.meta.examplePrompts,
+			i18n: input.meta.i18n,
+			createdAtMs: nowMs,
+			updatedAtMs: nowMs
+		}
+	};
+}
+function normalizeWorkflowDefinitionId(value) {
+	return value.trim().toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "");
+}
+function toWorkflowDefinitionTitle(value) {
+	return value.split(/[_-]+/g).filter(Boolean).map((part) => `${part.slice(0, 1).toUpperCase()}${part.slice(1)}`).join(" ");
+}
+//#endregion
+export { DEFAULT_WORKFLOW_CONCURRENCY, DEFAULT_WORKFLOW_MAX_SUBAGENTS, DEFAULT_WORKFLOW_TIMEOUT_SEC, buildWorkflowDefinition, normalizeWorkflowDefinitionId, toWorkflowDefinitionTitle };
+
+//# sourceMappingURL=definition-utils.js.map

package/dist/src/workflows/domain/definition-utils.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"definition-utils.js","names":[],"sources":["../../../../src/workflows/domain/definition-utils.ts"],"sourcesContent":["import type { WorkflowMeta } from '../../agent/workflow/types.js';\n\nimport type { WorkflowDefinition } from './definition.js';\n\nexport const DEFAULT_WORKFLOW_CONCURRENCY = 4;\nexport const DEFAULT_WORKFLOW_TIMEOUT_SEC = 30 * 60;\nexport const DEFAULT_WORKFLOW_MAX_SUBAGENTS = 100;\n\nexport interface WorkflowDefinitionBuildInput {\n  name: string;\n  source: 'builtin' | 'user';\n  script: string;\n  meta: WorkflowMeta;\n}\n\nexport function buildWorkflowDefinition(input: WorkflowDefinitionBuildInput): WorkflowDefinition {\n  const nowMs = Date.now();\n  const phases = input.meta.phases?.map((phase, index) => ({\n    id: normalizeWorkflowDefinitionId(phase.title) || `phase-${index + 1}`,\n    title: phase.title,\n    description: phase.detail,\n  })) ?? [];\n\n  return {\n    id: input.name,\n    name: input.name,\n    title: toWorkflowDefinitionTitle(input.name),\n    description: input.meta.description,\n    version: '1.0.0',\n    phases,\n    runtime: {\n      kind: 'script',\n      source: input.script,\n    },\n    defaults: {\n      concurrency: DEFAULT_WORKFLOW_CONCURRENCY,\n      timeoutSec: DEFAULT_WORKFLOW_TIMEOUT_SEC,\n      maxSubagents: input.meta.estimatedAgents?.max ?? DEFAULT_WORKFLOW_MAX_SUBAGENTS,\n    },\n    metadata: {\n      tags: input.meta.tags ?? [],\n      builtIn: input.source === 'builtin',\n      source: input.source,\n      whenToUse: input.meta.whenToUse,\n      estimatedAgents: input.meta.estimatedAgents,\n      examplePrompts: input.meta.examplePrompts,\n      i18n: input.meta.i18n,\n      createdAtMs: nowMs,\n      updatedAtMs: nowMs,\n    },\n  };\n}\n\nexport function normalizeWorkflowDefinitionId(value: string): string {\n  return value\n    .trim()\n    .toLowerCase()\n    .replace(/[^a-z0-9]+/g, '-')\n    .replace(/^-+|-+$/g, '');\n}\n\nexport function toWorkflowDefinitionTitle(value: string): string {\n  return value\n    .split(/[_-]+/g)\n    .filter(Boolean)\n    .map((part) => `${part.slice(0, 1).toUpperCase()}${part.slice(1)}`)\n    .join(' ');\n}\n"],"mappings":";AAIA,MAAa,+BAA+B;AAC5C,MAAa,+BAA+B;AAC5C,MAAa,iCAAiC;AAS9C,SAAgB,wBAAwB,OAAyD;CAC/F,MAAM,QAAQ,KAAK,KAAK;CACxB,MAAM,SAAS,MAAM,KAAK,QAAQ,KAAK,OAAO,WAAW;EACvD,IAAI,8BAA8B,MAAM,MAAM,IAAI,SAAS,QAAQ;EACnE,OAAO,MAAM;EACb,aAAa,MAAM;EACpB,EAAE,IAAI,EAAE;AAET,QAAO;EACL,IAAI,MAAM;EACV,MAAM,MAAM;EACZ,OAAO,0BAA0B,MAAM,KAAK;EAC5C,aAAa,MAAM,KAAK;EACxB,SAAS;EACT;EACA,SAAS;GACP,MAAM;GACN,QAAQ,MAAM;GACf;EACD,UAAU;GACR,aAAA;GACA,YAAY;GACZ,cAAc,MAAM,KAAK,iBAAiB,OAAA;GAC3C;EACD,UAAU;GACR,MAAM,MAAM,KAAK,QAAQ,EAAE;GAC3B,SAAS,MAAM,WAAW;GAC1B,QAAQ,MAAM;GACd,WAAW,MAAM,KAAK;GACtB,iBAAiB,MAAM,KAAK;GAC5B,gBAAgB,MAAM,KAAK;GAC3B,MAAM,MAAM,KAAK;GACjB,aAAa;GACb,aAAa;GACd;EACF;;AAGH,SAAgB,8BAA8B,OAAuB;AACnE,QAAO,MACJ,MAAM,CACN,aAAa,CACb,QAAQ,eAAe,IAAI,CAC3B,QAAQ,YAAY,GAAG;;AAG5B,SAAgB,0BAA0B,OAAuB;AAC/D,QAAO,MACJ,MAAM,SAAS,CACf,OAAO,QAAQ,CACf,KAAK,SAAS,GAAG,KAAK,MAAM,GAAG,EAAE,CAAC,aAAa,GAAG,KAAK,MAAM,EAAE,GAAG,CAClE,KAAK,IAAI"}

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

@@ -1,5 +1,7 @@
 export * from './definition.js';
+export * from './definition-utils.js';
 export * from './event.js';
 export * from './result.js';
 export * from './run.js';
 export * from './command.js';
+export * from './validation.js';

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

@@ -1,2 +1,4 @@
+import { DEFAULT_WORKFLOW_CONCURRENCY, DEFAULT_WORKFLOW_MAX_SUBAGENTS, DEFAULT_WORKFLOW_TIMEOUT_SEC, buildWorkflowDefinition, normalizeWorkflowDefinitionId, toWorkflowDefinitionTitle } from "./definition-utils.js";
 import { isTerminalWorkflowRunStatus } from "./run.js";
-export { isTerminalWorkflowRunStatus };
+import { validateWorkflowDefinitionInput } from "./validation.js";
+export { DEFAULT_WORKFLOW_CONCURRENCY, DEFAULT_WORKFLOW_MAX_SUBAGENTS, DEFAULT_WORKFLOW_TIMEOUT_SEC, buildWorkflowDefinition, isTerminalWorkflowRunStatus, normalizeWorkflowDefinitionId, toWorkflowDefinitionTitle, validateWorkflowDefinitionInput };

package/dist/src/workflows/domain/run.d.ts

@@ -1,3 +1,4 @@
+import type { WorkflowDefinitionEstimatedAgents } from './definition.js';
 import type { WorkflowArtifactRef, WorkflowResultEnvelope } from './result.js';
 export type WorkflowRunStatus = 'queued' | 'running' | 'succeeded' | 'failed' | 'cancelled' | 'timeout';
 export declare function isTerminalWorkflowRunStatus(status: WorkflowRunStatus): boolean;
@@ -10,6 +11,7 @@ export interface WorkflowRun {
     input: unknown;
     status: WorkflowRunStatus;
     source: WorkflowRunSource;
+    metadata?: WorkflowRunMetadata;
     result?: WorkflowResultEnvelope;
     error?: WorkflowRunError;
     metrics: WorkflowRunMetrics;
@@ -17,22 +19,76 @@ export interface WorkflowRun {
     startedAtMs?: number;
     completedAtMs?: number;
 }
+export interface WorkflowRunMetadata {
+    sessionKey: string;
+    triggerSource: WorkflowRunSource['kind'];
+    agentId?: string;
+    retryOfRunId?: string;
+    definition: WorkflowRunDefinitionSnapshot;
+    input?: WorkflowRunInputEnvelope;
+    correlation?: WorkflowRunCorrelation;
+    origin?: WorkflowRunOrigin;
+    schedule?: WorkflowRunScheduleMetadata;
+}
+export interface WorkflowRunInputEnvelope {
+    payload: unknown;
+    goal?: string;
+    variables?: Record<string, unknown>;
+    context?: Record<string, unknown>;
+}
+export interface WorkflowRunCorrelation {
+    idempotencyKey?: string;
+    requestId?: string;
+    traceId?: string;
+    parentRunId?: string;
+}
+export interface WorkflowRunOrigin {
+    channel: string;
+    sessionKey?: string;
+    chatId?: string;
+    messageId?: string;
+    scheduleId?: string;
+    fireId?: string;
+    requestId?: string;
+}
+export interface WorkflowRunScheduleMetadata {
+    scheduleId: string;
+    fireId?: string;
+    scheduledAtMs?: number;
+}
+export interface WorkflowRunDefinitionSnapshot {
+    id: string;
+    name: string;
+    title: string;
+    version: string;
+    source: 'builtin' | 'user';
+    tags: string[];
+    phaseCount: number;
+    estimatedAgents?: WorkflowDefinitionEstimatedAgents;
+}
 export type WorkflowRunSource = {
     kind: 'chat';
     sessionKey: string;
     messageId?: string;
 } | {
     kind: 'webui';
+    sessionKey?: string;
+    requestId?: string;
 } | {
     kind: 'cron';
     scheduleId: string;
+    fireId?: string;
+    scheduledAtMs?: number;
 } | {
     kind: 'api';
     requestId?: string;
+    idempotencyKey?: string;
 } | {
     kind: 'im';
     channel: string;
     chatId: string;
+    messageId?: string;
+    userId?: string;
 };
 export interface WorkflowRunMetrics {
     agentCount: number;
@@ -60,6 +116,7 @@ export interface WorkflowRunSummary {
     title: string;
     status: WorkflowRunStatus;
     source: WorkflowRunSource;
+    metadata?: WorkflowRunMetadata;
     createdAtMs: number;
     startedAtMs?: number;
     completedAtMs?: number;

package/dist/src/workflows/domain/run.js.map

@@ -1 +1 @@
-{"version":3,"file":"run.js","names":[],"sources":["../../../../src/workflows/domain/run.ts"],"sourcesContent":["import type { WorkflowArtifactRef, WorkflowResultEnvelope } from './result.js';\n\nexport type WorkflowRunStatus =\n  | 'queued'\n  | 'running'\n  | 'succeeded'\n  | 'failed'\n  | 'cancelled'\n  | 'timeout';\n\nconst TERMINAL_WORKFLOW_RUN_STATUSES = new Set<WorkflowRunStatus>([\n  'succeeded',\n  'failed',\n  'cancelled',\n  'timeout',\n]);\n\nexport function isTerminalWorkflowRunStatus(status: WorkflowRunStatus): boolean {\n  return TERMINAL_WORKFLOW_RUN_STATUSES.has(status);\n}\n\nexport interface WorkflowRun {\n  id: string;\n  definitionId: string;\n  definitionVersion: string;\n  title: string;\n  goal: string;\n  input: unknown;\n  status: WorkflowRunStatus;\n  source: WorkflowRunSource;\n  result?: WorkflowResultEnvelope;\n  error?: WorkflowRunError;\n  metrics: WorkflowRunMetrics;\n  createdAtMs: number;\n  startedAtMs?: number;\n  completedAtMs?: number;\n}\n\nexport type WorkflowRunSource =\n  | { kind: 'chat'; sessionKey: string; messageId?: string }\n  | { kind: 'webui' }\n  | { kind: 'cron'; scheduleId: string }\n  | { kind: 'api'; requestId?: string }\n  | { kind: 'im'; channel: string; chatId: string };\n\nexport interface WorkflowRunMetrics {\n  agentCount: number;\n  doneAgentCount: number;\n  errorAgentCount: number;\n  skippedAgentCount: number;\n  artifactCount: number;\n  durationMs?: number;\n}\n\nexport interface WorkflowRunError {\n  code: WorkflowRunErrorCode;\n  message: string;\n  detail?: string;\n  recoverable: boolean;\n}\n\nexport type WorkflowRunErrorCode =\n  | 'definition_not_found'\n  | 'invalid_input'\n  | 'runtime_error'\n  | 'timeout'\n  | 'cancelled'\n  | 'result_validation_failed'\n  | 'agent_quota_exceeded';\n\nexport interface WorkflowRunControls {\n  canCancel: boolean;\n  canRetry: boolean;\n  canArchive: boolean;\n}\n\nexport interface WorkflowRunSummary {\n  id: string;\n  definitionId: string;\n  title: string;\n  status: WorkflowRunStatus;\n  source: WorkflowRunSource;\n  createdAtMs: number;\n  startedAtMs?: number;\n  completedAtMs?: number;\n  metrics: WorkflowRunMetrics;\n}\n\nexport interface WorkflowRunView {\n  run: WorkflowRun;\n  phases: WorkflowPhaseView[];\n  agents: WorkflowAgentView[];\n  logs: WorkflowLogEntry[];\n  artifacts: WorkflowArtifactRef[];\n  timeline: WorkflowTimelineItem[];\n  controls: WorkflowRunControls;\n}\n\nexport type WorkflowPhaseStatus = 'pending' | 'running' | 'completed' | 'failed';\n\nexport interface WorkflowPhaseView {\n  id: string;\n  title: string;\n  status: WorkflowPhaseStatus;\n  startedAtMs?: number;\n  completedAtMs?: number;\n  agentIds: string[];\n}\n\nexport type WorkflowAgentStatus = 'queued' | 'running' | 'done' | 'error' | 'skipped';\n\nexport interface WorkflowAgentView {\n  id: string;\n  label: string;\n  phaseId?: string;\n  status: WorkflowAgentStatus;\n  prompt?: string;\n  currentStep?: string;\n  resultPreview?: string;\n  error?: string;\n  startedAtMs?: number;\n  completedAtMs?: number;\n  steps: WorkflowAgentStepView[];\n}\n\nexport type WorkflowAgentStepStatus = 'running' | 'done' | 'error';\n\nexport interface WorkflowAgentStepView {\n  id: string;\n  label: string;\n  kind: 'tool' | 'llm' | 'thinking';\n  detail?: string;\n  status: WorkflowAgentStepStatus;\n  startedAtMs?: number;\n  completedAtMs?: number;\n}\n\nexport interface WorkflowLogEntry {\n  sequence: number;\n  message: string;\n  createdAtMs: number;\n}\n\nexport interface WorkflowTimelineItem {\n  sequence: number;\n  type: string;\n  title: string;\n  createdAtMs: number;\n}\n"],"mappings":";AAUA,MAAM,iCAAiC,IAAI,IAAuB;CAChE;CACA;CACA;CACA;CACD,CAAC;AAEF,SAAgB,4BAA4B,QAAoC;AAC9E,QAAO,+BAA+B,IAAI,OAAO"}
+{"version":3,"file":"run.js","names":[],"sources":["../../../../src/workflows/domain/run.ts"],"sourcesContent":["import type { WorkflowDefinitionEstimatedAgents } from './definition.js';\nimport type { WorkflowArtifactRef, WorkflowResultEnvelope } from './result.js';\n\nexport type WorkflowRunStatus =\n  | 'queued'\n  | 'running'\n  | 'succeeded'\n  | 'failed'\n  | 'cancelled'\n  | 'timeout';\n\nconst TERMINAL_WORKFLOW_RUN_STATUSES = new Set<WorkflowRunStatus>([\n  'succeeded',\n  'failed',\n  'cancelled',\n  'timeout',\n]);\n\nexport function isTerminalWorkflowRunStatus(status: WorkflowRunStatus): boolean {\n  return TERMINAL_WORKFLOW_RUN_STATUSES.has(status);\n}\n\nexport interface WorkflowRun {\n  id: string;\n  definitionId: string;\n  definitionVersion: string;\n  title: string;\n  goal: string;\n  input: unknown;\n  status: WorkflowRunStatus;\n  source: WorkflowRunSource;\n  metadata?: WorkflowRunMetadata;\n  result?: WorkflowResultEnvelope;\n  error?: WorkflowRunError;\n  metrics: WorkflowRunMetrics;\n  createdAtMs: number;\n  startedAtMs?: number;\n  completedAtMs?: number;\n}\n\nexport interface WorkflowRunMetadata {\n  sessionKey: string;\n  triggerSource: WorkflowRunSource['kind'];\n  agentId?: string;\n  retryOfRunId?: string;\n  definition: WorkflowRunDefinitionSnapshot;\n  input?: WorkflowRunInputEnvelope;\n  correlation?: WorkflowRunCorrelation;\n  origin?: WorkflowRunOrigin;\n  schedule?: WorkflowRunScheduleMetadata;\n}\n\nexport interface WorkflowRunInputEnvelope {\n  payload: unknown;\n  goal?: string;\n  variables?: Record<string, unknown>;\n  context?: Record<string, unknown>;\n}\n\nexport interface WorkflowRunCorrelation {\n  idempotencyKey?: string;\n  requestId?: string;\n  traceId?: string;\n  parentRunId?: string;\n}\n\nexport interface WorkflowRunOrigin {\n  channel: string;\n  sessionKey?: string;\n  chatId?: string;\n  messageId?: string;\n  scheduleId?: string;\n  fireId?: string;\n  requestId?: string;\n}\n\nexport interface WorkflowRunScheduleMetadata {\n  scheduleId: string;\n  fireId?: string;\n  scheduledAtMs?: number;\n}\n\nexport interface WorkflowRunDefinitionSnapshot {\n  id: string;\n  name: string;\n  title: string;\n  version: string;\n  source: 'builtin' | 'user';\n  tags: string[];\n  phaseCount: number;\n  estimatedAgents?: WorkflowDefinitionEstimatedAgents;\n}\n\nexport type WorkflowRunSource =\n  | { kind: 'chat'; sessionKey: string; messageId?: string }\n  | { kind: 'webui'; sessionKey?: string; requestId?: string }\n  | { kind: 'cron'; scheduleId: string; fireId?: string; scheduledAtMs?: number }\n  | { kind: 'api'; requestId?: string; idempotencyKey?: string }\n  | { kind: 'im'; channel: string; chatId: string; messageId?: string; userId?: string };\n\nexport interface WorkflowRunMetrics {\n  agentCount: number;\n  doneAgentCount: number;\n  errorAgentCount: number;\n  skippedAgentCount: number;\n  artifactCount: number;\n  durationMs?: number;\n}\n\nexport interface WorkflowRunError {\n  code: WorkflowRunErrorCode;\n  message: string;\n  detail?: string;\n  recoverable: boolean;\n}\n\nexport type WorkflowRunErrorCode =\n  | 'definition_not_found'\n  | 'invalid_input'\n  | 'runtime_error'\n  | 'timeout'\n  | 'cancelled'\n  | 'result_validation_failed'\n  | 'agent_quota_exceeded';\n\nexport interface WorkflowRunControls {\n  canCancel: boolean;\n  canRetry: boolean;\n  canArchive: boolean;\n}\n\nexport interface WorkflowRunSummary {\n  id: string;\n  definitionId: string;\n  title: string;\n  status: WorkflowRunStatus;\n  source: WorkflowRunSource;\n  metadata?: WorkflowRunMetadata;\n  createdAtMs: number;\n  startedAtMs?: number;\n  completedAtMs?: number;\n  metrics: WorkflowRunMetrics;\n}\n\nexport interface WorkflowRunView {\n  run: WorkflowRun;\n  phases: WorkflowPhaseView[];\n  agents: WorkflowAgentView[];\n  logs: WorkflowLogEntry[];\n  artifacts: WorkflowArtifactRef[];\n  timeline: WorkflowTimelineItem[];\n  controls: WorkflowRunControls;\n}\n\nexport type WorkflowPhaseStatus = 'pending' | 'running' | 'completed' | 'failed';\n\nexport interface WorkflowPhaseView {\n  id: string;\n  title: string;\n  status: WorkflowPhaseStatus;\n  startedAtMs?: number;\n  completedAtMs?: number;\n  agentIds: string[];\n}\n\nexport type WorkflowAgentStatus = 'queued' | 'running' | 'done' | 'error' | 'skipped';\n\nexport interface WorkflowAgentView {\n  id: string;\n  label: string;\n  phaseId?: string;\n  status: WorkflowAgentStatus;\n  prompt?: string;\n  currentStep?: string;\n  resultPreview?: string;\n  error?: string;\n  startedAtMs?: number;\n  completedAtMs?: number;\n  steps: WorkflowAgentStepView[];\n}\n\nexport type WorkflowAgentStepStatus = 'running' | 'done' | 'error';\n\nexport interface WorkflowAgentStepView {\n  id: string;\n  label: string;\n  kind: 'tool' | 'llm' | 'thinking';\n  detail?: string;\n  status: WorkflowAgentStepStatus;\n  startedAtMs?: number;\n  completedAtMs?: number;\n}\n\nexport interface WorkflowLogEntry {\n  sequence: number;\n  message: string;\n  createdAtMs: number;\n}\n\nexport interface WorkflowTimelineItem {\n  sequence: number;\n  type: string;\n  title: string;\n  createdAtMs: number;\n}\n"],"mappings":";AAWA,MAAM,iCAAiC,IAAI,IAAuB;CAChE;CACA;CACA;CACA;CACD,CAAC;AAEF,SAAgB,4BAA4B,QAAoC;AAC9E,QAAO,+BAA+B,IAAI,OAAO"}

package/dist/src/workflows/domain/validation.d.ts

@@ -0,0 +1,19 @@
+import type { WorkflowDefinition } from './definition.js';
+export type WorkflowDefinitionValidationIssueCode = 'name_required' | 'script_required' | 'parse_failed' | 'meta_name_mismatch' | 'unknown_error';
+export interface WorkflowDefinitionValidationIssue {
+    code: WorkflowDefinitionValidationIssueCode;
+    message: string;
+    line?: number;
+    column?: number;
+}
+export interface WorkflowDefinitionValidationResult {
+    valid: boolean;
+    errors: WorkflowDefinitionValidationIssue[];
+    warnings: WorkflowDefinitionValidationIssue[];
+    definition?: WorkflowDefinition;
+}
+export interface ValidateWorkflowDefinitionInput {
+    name?: string;
+    script?: string;
+}
+export declare function validateWorkflowDefinitionInput(input: ValidateWorkflowDefinitionInput): WorkflowDefinitionValidationResult;

package/dist/src/workflows/domain/validation.js

@@ -0,0 +1,66 @@
+import { parseWorkflowScript } from "../../agent/workflow/parser.js";
+import { buildWorkflowDefinition } from "./definition-utils.js";
+//#region src/workflows/domain/validation.ts
+const NAME_RE = /^[a-z][a-z0-9_-]*$/;
+function validateWorkflowDefinitionInput(input) {
+	const name = input.name?.trim() ?? "";
+	const script = input.script ?? "";
+	const errors = [];
+	const warnings = [];
+	if (!name) errors.push({
+		code: "name_required",
+		message: "Workflow name is required."
+	});
+	else if (!NAME_RE.test(name)) errors.push({
+		code: "parse_failed",
+		message: `Invalid workflow name "${name}". Use lowercase snake_case, e.g. "audit_repo".`
+	});
+	if (!script.trim()) errors.push({
+		code: "script_required",
+		message: "Workflow script is required."
+	});
+	if (errors.length > 0) return {
+		valid: false,
+		errors,
+		warnings
+	};
+	try {
+		const { meta } = parseWorkflowScript(script);
+		if (meta.name !== name) {
+			errors.push({
+				code: "meta_name_mismatch",
+				message: `meta.name "${meta.name}" does not match workflow name "${name}".`
+			});
+			return {
+				valid: false,
+				errors,
+				warnings
+			};
+		}
+		return {
+			valid: true,
+			errors,
+			warnings,
+			definition: buildWorkflowDefinition({
+				name,
+				source: "user",
+				script,
+				meta
+			})
+		};
+	} catch (err) {
+		errors.push({
+			code: "parse_failed",
+			message: err instanceof Error ? err.message : String(err)
+		});
+		return {
+			valid: false,
+			errors,
+			warnings
+		};
+	}
+}
+//#endregion
+export { validateWorkflowDefinitionInput };
+
+//# sourceMappingURL=validation.js.map

package/dist/src/workflows/domain/validation.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"validation.js","names":[],"sources":["../../../../src/workflows/domain/validation.ts"],"sourcesContent":["import { parseWorkflowScript } from '../../agent/workflow/parser.js';\n\nimport type { WorkflowDefinition } from './definition.js';\nimport { buildWorkflowDefinition } from './definition-utils.js';\n\nexport type WorkflowDefinitionValidationIssueCode =\n  | 'name_required'\n  | 'script_required'\n  | 'parse_failed'\n  | 'meta_name_mismatch'\n  | 'unknown_error';\n\nexport interface WorkflowDefinitionValidationIssue {\n  code: WorkflowDefinitionValidationIssueCode;\n  message: string;\n  line?: number;\n  column?: number;\n}\n\nexport interface WorkflowDefinitionValidationResult {\n  valid: boolean;\n  errors: WorkflowDefinitionValidationIssue[];\n  warnings: WorkflowDefinitionValidationIssue[];\n  definition?: WorkflowDefinition;\n}\n\nexport interface ValidateWorkflowDefinitionInput {\n  name?: string;\n  script?: string;\n}\n\nconst NAME_RE = /^[a-z][a-z0-9_-]*$/;\n\nexport function validateWorkflowDefinitionInput(\n  input: ValidateWorkflowDefinitionInput,\n): WorkflowDefinitionValidationResult {\n  const name = input.name?.trim() ?? '';\n  const script = input.script ?? '';\n  const errors: WorkflowDefinitionValidationIssue[] = [];\n  const warnings: WorkflowDefinitionValidationIssue[] = [];\n\n  if (!name) {\n    errors.push({ code: 'name_required', message: 'Workflow name is required.' });\n  } else if (!NAME_RE.test(name)) {\n    errors.push({\n      code: 'parse_failed',\n      message: `Invalid workflow name \"${name}\". Use lowercase snake_case, e.g. \"audit_repo\".`,\n    });\n  }\n\n  if (!script.trim()) {\n    errors.push({ code: 'script_required', message: 'Workflow script is required.' });\n  }\n\n  if (errors.length > 0) {\n    return { valid: false, errors, warnings };\n  }\n\n  try {\n    const { meta } = parseWorkflowScript(script);\n    if (meta.name !== name) {\n      errors.push({\n        code: 'meta_name_mismatch',\n        message: `meta.name \"${meta.name}\" does not match workflow name \"${name}\".`,\n      });\n      return { valid: false, errors, warnings };\n    }\n\n    return {\n      valid: true,\n      errors,\n      warnings,\n      definition: buildWorkflowDefinition({\n        name,\n        source: 'user',\n        script,\n        meta,\n      }),\n    };\n  } catch (err) {\n    errors.push({\n      code: 'parse_failed',\n      message: err instanceof Error ? err.message : String(err),\n    });\n    return { valid: false, errors, warnings };\n  }\n}\n"],"mappings":";;;AA+BA,MAAM,UAAU;AAEhB,SAAgB,gCACd,OACoC;CACpC,MAAM,OAAO,MAAM,MAAM,MAAM,IAAI;CACnC,MAAM,SAAS,MAAM,UAAU;CAC/B,MAAM,SAA8C,EAAE;CACtD,MAAM,WAAgD,EAAE;AAExD,KAAI,CAAC,KACH,QAAO,KAAK;EAAE,MAAM;EAAiB,SAAS;EAA8B,CAAC;UACpE,CAAC,QAAQ,KAAK,KAAK,CAC5B,QAAO,KAAK;EACV,MAAM;EACN,SAAS,0BAA0B,KAAK;EACzC,CAAC;AAGJ,KAAI,CAAC,OAAO,MAAM,CAChB,QAAO,KAAK;EAAE,MAAM;EAAmB,SAAS;EAAgC,CAAC;AAGnF,KAAI,OAAO,SAAS,EAClB,QAAO;EAAE,OAAO;EAAO;EAAQ;EAAU;AAG3C,KAAI;EACF,MAAM,EAAE,SAAS,oBAAoB,OAAO;AAC5C,MAAI,KAAK,SAAS,MAAM;AACtB,UAAO,KAAK;IACV,MAAM;IACN,SAAS,cAAc,KAAK,KAAK,kCAAkC,KAAK;IACzE,CAAC;AACF,UAAO;IAAE,OAAO;IAAO;IAAQ;IAAU;;AAG3C,SAAO;GACL,OAAO;GACP;GACA;GACA,YAAY,wBAAwB;IAClC;IACA,QAAQ;IACR;IACA;IACD,CAAC;GACH;UACM,KAAK;AACZ,SAAO,KAAK;GACV,MAAM;GACN,SAAS,eAAe,QAAQ,IAAI,UAAU,OAAO,IAAI;GAC1D,CAAC;AACF,SAAO;GAAE,OAAO;GAAO;GAAQ;GAAU"}

package/dist/src/workflows/engine/workflow-engine.d.ts

@@ -1,6 +1,6 @@
 import type { WorkflowDefinition } from '../domain/definition.js';
 import type { WorkflowEventEnvelope } from '../domain/event.js';
-import type { WorkflowRunSource, WorkflowRunView } from '../domain/run.js';
+import type { WorkflowRunMetadata, WorkflowRunSource, WorkflowRunView } from '../domain/run.js';
 import { WorkflowEventStore } from '../store/event-store.js';
 import { WorkflowRunStore } from '../store/run-store.js';
 import type { Api, Model } from '@earendil-works/pi-ai';
@@ -17,6 +17,7 @@ export interface WorkflowEngineOptions {
 export interface StartWorkflowRunOptions {
     input?: unknown;
     source: WorkflowRunSource;
+    metadata?: WorkflowRunMetadata;
     goal?: string;
     runId?: string;
     signal?: AbortSignal;

package/dist/src/workflows/engine/workflow-engine.js

@@ -21,6 +21,7 @@ var WorkflowEngine = class {
 			input: options.input ?? {},
 			status: "queued",
 			source: options.source,
+			metadata: options.metadata,
 			metrics: {
 				agentCount: 0,
 				doneAgentCount: 0,

package/dist/src/workflows/engine/workflow-engine.js.map

@@ -1 +1 @@
-{"version":3,"file":"workflow-engine.js","names":["runWorkflowScript"],"sources":["../../../../src/workflows/engine/workflow-engine.ts"],"sourcesContent":["import { randomUUID } from 'node:crypto';\n\nimport type { WorkflowDefinition } from '../domain/definition.js';\nimport type { WorkflowEventEnvelope, WorkflowEventPayload, WorkflowEventType } from '../domain/event.js';\nimport type { WorkflowRun, WorkflowRunError, WorkflowRunSource, WorkflowRunView } from '../domain/run.js';\nimport type { WorkflowResultEnvelope } from '../domain/result.js';\nimport { WorkflowEventStore } from '../store/event-store.js';\nimport { WorkflowRunStore } from '../store/run-store.js';\nimport { runWorkflowScript } from '../runtime/script-runtime.js';\nimport type { Api, Model } from '@earendil-works/pi-ai';\n\nimport type { WorkflowScriptSubagentRunner } from '../runtime/script-runtime.js';\n\nexport interface WorkflowEngineOptions {\n  cwd: string;\n  eventStore: WorkflowEventStore;\n  runStore: WorkflowRunStore;\n  runner: WorkflowScriptSubagentRunner;\n  onEventAppended?: (event: WorkflowEventEnvelope) => void;\n  onRunViewUpdated?: (view: WorkflowRunView) => void;\n  resolveModelId?: (modelId: string) => Model<Api>;\n}\n\nexport interface StartWorkflowRunOptions {\n  input?: unknown;\n  source: WorkflowRunSource;\n  goal?: string;\n  runId?: string;\n  signal?: AbortSignal;\n  concurrency?: number;\n  maxSubagents?: number;\n  tokenBudget?: number | null;\n}\n\nexport class WorkflowEngine {\n  constructor(private readonly options: WorkflowEngineOptions) {}\n\n  async startRun(definition: WorkflowDefinition, options: StartWorkflowRunOptions): Promise<WorkflowRunView> {\n    const runId = options.runId ?? randomUUID();\n    const createdAtMs = Date.now();\n    const phaseTitleToId = buildPhaseTitleToId(definition);\n    let currentPhaseId: string | undefined;\n    let eventQueue = Promise.resolve();\n\n    const run: WorkflowRun = {\n      id: runId,\n      definitionId: definition.id,\n      definitionVersion: definition.version,\n      title: definition.title,\n      goal: options.goal ?? definition.description,\n      input: options.input ?? {},\n      status: 'queued',\n      source: options.source,\n      metrics: {\n        agentCount: 0,\n        doneAgentCount: 0,\n        errorAgentCount: 0,\n        skippedAgentCount: 0,\n        artifactCount: 0,\n      },\n      createdAtMs,\n    };\n\n    const appendEvent = (type: WorkflowEventType, payload: WorkflowEventPayload, createdAtMsOverride?: number) => {\n      eventQueue = eventQueue\n        .then(() =>\n          this.options.eventStore.append({\n            runId,\n            type,\n            payload,\n            createdAtMs: createdAtMsOverride,\n          }),\n        )\n        .then(async (event) => {\n          this.options.onEventAppended?.(event);\n          const view = await this.options.runStore.rebuildRunView(runId);\n          if (view) {\n            this.options.onRunViewUpdated?.(view);\n          }\n        });\n      return eventQueue;\n    };\n\n    await appendEvent('run_queued', { run }, createdAtMs);\n    await appendEvent('run_started', { startedAtMs: Date.now() });\n\n    try {\n      const runtimeResult = await runWorkflowScript<unknown>(\n        definition.runtime.source,\n        {\n          runner: this.options.runner,\n          resolveModelId: this.options.resolveModelId,\n        },\n        {\n          cwd: this.options.cwd,\n          args: options.input,\n          signal: options.signal,\n          concurrency: options.concurrency ?? definition.defaults.concurrency,\n          maxSubagents: options.maxSubagents ?? definition.defaults.maxSubagents,\n          tokenBudget: options.tokenBudget,\n          onPhase: (title) => {\n            const nextPhaseId = phaseTitleToId.get(title) ?? normalizePhaseId(title);\n            if (currentPhaseId && currentPhaseId !== nextPhaseId) {\n              void appendEvent('phase_completed', { phaseId: currentPhaseId });\n            }\n            currentPhaseId = nextPhaseId;\n            void appendEvent('phase_started', { phaseId: nextPhaseId, title });\n          },\n          onLog: (message) => {\n            void appendEvent('log_appended', { message });\n          },\n          onAgentQueued: (event) => {\n            const phaseId = event.phase ? (phaseTitleToId.get(event.phase) ?? normalizePhaseId(event.phase)) : currentPhaseId;\n            void appendEvent('agent_queued', {\n              agentId: formatRuntimeAgentId(event.id),\n              label: event.label,\n              phaseId,\n              prompt: event.prompt,\n            });\n          },\n          onAgentStart: (event) => {\n            void appendEvent('agent_started', { agentId: formatRuntimeAgentId(event.id) });\n          },\n          onAgentEnd: (event) => {\n            const completedStatus = normalizeCompletedAgentStatus(event.status);\n            void appendEvent('agent_completed', {\n              agentId: formatRuntimeAgentId(event.id),\n              status: completedStatus,\n              resultPreview: previewWorkflowValue(event.result),\n              error: completedStatus === 'error' ? 'Subagent failed' : undefined,\n            });\n          },\n        },\n      );\n\n      await eventQueue;\n      if (currentPhaseId) {\n        await appendEvent('phase_completed', { phaseId: currentPhaseId });\n      }\n      await appendEvent('run_completed', { result: toWorkflowResultEnvelope(runtimeResult.result) });\n    } catch (err) {\n      await eventQueue;\n      const error = toWorkflowRunError(err, options.signal?.aborted === true);\n      if (error.code === 'cancelled') {\n        await appendEvent('run_cancelled', { reason: error.message });\n      } else {\n        await appendEvent('run_failed', { error });\n      }\n    }\n\n    const view = await this.options.runStore.readRunView(runId);\n    if (!view) {\n      throw new Error(`workflow run view was not created for ${runId}`);\n    }\n    return view;\n  }\n}\n\nfunction buildPhaseTitleToId(definition: WorkflowDefinition): Map<string, string> {\n  const phaseTitleToId = new Map<string, string>();\n  for (const phase of definition.phases) {\n    phaseTitleToId.set(phase.title, phase.id);\n  }\n  return phaseTitleToId;\n}\n\nfunction normalizePhaseId(title: string): string {\n  const normalized = title\n    .trim()\n    .toLowerCase()\n    .replace(/[^a-z0-9]+/g, '-')\n    .replace(/^-+|-+$/g, '');\n  return normalized || 'phase';\n}\n\nfunction formatRuntimeAgentId(id: number): string {\n  return `agent-${id}`;\n}\n\nfunction normalizeCompletedAgentStatus(status: string): 'done' | 'error' | 'skipped' {\n  if (status === 'done' || status === 'error' || status === 'skipped') {\n    return status;\n  }\n  return 'error';\n}\n\nfunction previewWorkflowValue(value: unknown): string | undefined {\n  if (value === null || value === undefined) {\n    return undefined;\n  }\n  if (typeof value === 'string') {\n    return truncate(value, 300);\n  }\n  try {\n    return truncate(JSON.stringify(value), 300);\n  } catch {\n    return truncate(String(value), 300);\n  }\n}\n\nfunction truncate(value: string, maxLength: number): string {\n  const trimmed = value.trim();\n  if (trimmed.length <= maxLength) {\n    return trimmed;\n  }\n  return `${trimmed.slice(0, maxLength - 1)}…`;\n}\n\nfunction toWorkflowResultEnvelope(value: unknown): WorkflowResultEnvelope {\n  if (isWorkflowResultEnvelope(value)) {\n    return value;\n  }\n  if (typeof value === 'string') {\n    return {\n      summary: truncate(value, 800),\n      sections: [{ kind: 'text', title: 'Result', content: value }],\n      raw: value,\n    };\n  }\n  return {\n    summary: 'Workflow completed.',\n    sections: [{ kind: 'json', title: 'Result', value }],\n    raw: value,\n  };\n}\n\nfunction isWorkflowResultEnvelope(value: unknown): value is WorkflowResultEnvelope {\n  if (!value || typeof value !== 'object' || Array.isArray(value)) {\n    return false;\n  }\n  const record = value as Partial<WorkflowResultEnvelope>;\n  return typeof record.summary === 'string' && Array.isArray(record.sections);\n}\n\nfunction toWorkflowRunError(err: unknown, wasAborted: boolean): WorkflowRunError {\n  const message = err instanceof Error ? err.message : String(err);\n  if (wasAborted || /aborted|cancelled/i.test(message)) {\n    return {\n      code: 'cancelled',\n      message: message || 'Workflow run cancelled',\n      recoverable: true,\n    };\n  }\n  if (/timeout/i.test(message)) {\n    return {\n      code: 'timeout',\n      message,\n      recoverable: true,\n    };\n  }\n  if (/quota/i.test(message)) {\n    return {\n      code: 'agent_quota_exceeded',\n      message,\n      recoverable: true,\n    };\n  }\n  return {\n    code: 'runtime_error',\n    message,\n    recoverable: false,\n  };\n}\n"],"mappings":"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"}
+{"version":3,"file":"workflow-engine.js","names":["runWorkflowScript"],"sources":["../../../../src/workflows/engine/workflow-engine.ts"],"sourcesContent":["import { randomUUID } from 'node:crypto';\n\nimport type { WorkflowDefinition } from '../domain/definition.js';\nimport type { WorkflowEventEnvelope, WorkflowEventPayload, WorkflowEventType } from '../domain/event.js';\nimport type { WorkflowRun, WorkflowRunError, WorkflowRunMetadata, WorkflowRunSource, WorkflowRunView } from '../domain/run.js';\nimport type { WorkflowResultEnvelope } from '../domain/result.js';\nimport { WorkflowEventStore } from '../store/event-store.js';\nimport { WorkflowRunStore } from '../store/run-store.js';\nimport { runWorkflowScript } from '../runtime/script-runtime.js';\nimport type { Api, Model } from '@earendil-works/pi-ai';\n\nimport type { WorkflowScriptSubagentRunner } from '../runtime/script-runtime.js';\n\nexport interface WorkflowEngineOptions {\n  cwd: string;\n  eventStore: WorkflowEventStore;\n  runStore: WorkflowRunStore;\n  runner: WorkflowScriptSubagentRunner;\n  onEventAppended?: (event: WorkflowEventEnvelope) => void;\n  onRunViewUpdated?: (view: WorkflowRunView) => void;\n  resolveModelId?: (modelId: string) => Model<Api>;\n}\n\nexport interface StartWorkflowRunOptions {\n  input?: unknown;\n  source: WorkflowRunSource;\n  metadata?: WorkflowRunMetadata;\n  goal?: string;\n  runId?: string;\n  signal?: AbortSignal;\n  concurrency?: number;\n  maxSubagents?: number;\n  tokenBudget?: number | null;\n}\n\nexport class WorkflowEngine {\n  constructor(private readonly options: WorkflowEngineOptions) {}\n\n  async startRun(definition: WorkflowDefinition, options: StartWorkflowRunOptions): Promise<WorkflowRunView> {\n    const runId = options.runId ?? randomUUID();\n    const createdAtMs = Date.now();\n    const phaseTitleToId = buildPhaseTitleToId(definition);\n    let currentPhaseId: string | undefined;\n    let eventQueue = Promise.resolve();\n\n    const run: WorkflowRun = {\n      id: runId,\n      definitionId: definition.id,\n      definitionVersion: definition.version,\n      title: definition.title,\n      goal: options.goal ?? definition.description,\n      input: options.input ?? {},\n      status: 'queued',\n      source: options.source,\n      metadata: options.metadata,\n      metrics: {\n        agentCount: 0,\n        doneAgentCount: 0,\n        errorAgentCount: 0,\n        skippedAgentCount: 0,\n        artifactCount: 0,\n      },\n      createdAtMs,\n    };\n\n    const appendEvent = (type: WorkflowEventType, payload: WorkflowEventPayload, createdAtMsOverride?: number) => {\n      eventQueue = eventQueue\n        .then(() =>\n          this.options.eventStore.append({\n            runId,\n            type,\n            payload,\n            createdAtMs: createdAtMsOverride,\n          }),\n        )\n        .then(async (event) => {\n          this.options.onEventAppended?.(event);\n          const view = await this.options.runStore.rebuildRunView(runId);\n          if (view) {\n            this.options.onRunViewUpdated?.(view);\n          }\n        });\n      return eventQueue;\n    };\n\n    await appendEvent('run_queued', { run }, createdAtMs);\n    await appendEvent('run_started', { startedAtMs: Date.now() });\n\n    try {\n      const runtimeResult = await runWorkflowScript<unknown>(\n        definition.runtime.source,\n        {\n          runner: this.options.runner,\n          resolveModelId: this.options.resolveModelId,\n        },\n        {\n          cwd: this.options.cwd,\n          args: options.input,\n          signal: options.signal,\n          concurrency: options.concurrency ?? definition.defaults.concurrency,\n          maxSubagents: options.maxSubagents ?? definition.defaults.maxSubagents,\n          tokenBudget: options.tokenBudget,\n          onPhase: (title) => {\n            const nextPhaseId = phaseTitleToId.get(title) ?? normalizePhaseId(title);\n            if (currentPhaseId && currentPhaseId !== nextPhaseId) {\n              void appendEvent('phase_completed', { phaseId: currentPhaseId });\n            }\n            currentPhaseId = nextPhaseId;\n            void appendEvent('phase_started', { phaseId: nextPhaseId, title });\n          },\n          onLog: (message) => {\n            void appendEvent('log_appended', { message });\n          },\n          onAgentQueued: (event) => {\n            const phaseId = event.phase ? (phaseTitleToId.get(event.phase) ?? normalizePhaseId(event.phase)) : currentPhaseId;\n            void appendEvent('agent_queued', {\n              agentId: formatRuntimeAgentId(event.id),\n              label: event.label,\n              phaseId,\n              prompt: event.prompt,\n            });\n          },\n          onAgentStart: (event) => {\n            void appendEvent('agent_started', { agentId: formatRuntimeAgentId(event.id) });\n          },\n          onAgentEnd: (event) => {\n            const completedStatus = normalizeCompletedAgentStatus(event.status);\n            void appendEvent('agent_completed', {\n              agentId: formatRuntimeAgentId(event.id),\n              status: completedStatus,\n              resultPreview: previewWorkflowValue(event.result),\n              error: completedStatus === 'error' ? 'Subagent failed' : undefined,\n            });\n          },\n        },\n      );\n\n      await eventQueue;\n      if (currentPhaseId) {\n        await appendEvent('phase_completed', { phaseId: currentPhaseId });\n      }\n      await appendEvent('run_completed', { result: toWorkflowResultEnvelope(runtimeResult.result) });\n    } catch (err) {\n      await eventQueue;\n      const error = toWorkflowRunError(err, options.signal?.aborted === true);\n      if (error.code === 'cancelled') {\n        await appendEvent('run_cancelled', { reason: error.message });\n      } else {\n        await appendEvent('run_failed', { error });\n      }\n    }\n\n    const view = await this.options.runStore.readRunView(runId);\n    if (!view) {\n      throw new Error(`workflow run view was not created for ${runId}`);\n    }\n    return view;\n  }\n}\n\nfunction buildPhaseTitleToId(definition: WorkflowDefinition): Map<string, string> {\n  const phaseTitleToId = new Map<string, string>();\n  for (const phase of definition.phases) {\n    phaseTitleToId.set(phase.title, phase.id);\n  }\n  return phaseTitleToId;\n}\n\nfunction normalizePhaseId(title: string): string {\n  const normalized = title\n    .trim()\n    .toLowerCase()\n    .replace(/[^a-z0-9]+/g, '-')\n    .replace(/^-+|-+$/g, '');\n  return normalized || 'phase';\n}\n\nfunction formatRuntimeAgentId(id: number): string {\n  return `agent-${id}`;\n}\n\nfunction normalizeCompletedAgentStatus(status: string): 'done' | 'error' | 'skipped' {\n  if (status === 'done' || status === 'error' || status === 'skipped') {\n    return status;\n  }\n  return 'error';\n}\n\nfunction previewWorkflowValue(value: unknown): string | undefined {\n  if (value === null || value === undefined) {\n    return undefined;\n  }\n  if (typeof value === 'string') {\n    return truncate(value, 300);\n  }\n  try {\n    return truncate(JSON.stringify(value), 300);\n  } catch {\n    return truncate(String(value), 300);\n  }\n}\n\nfunction truncate(value: string, maxLength: number): string {\n  const trimmed = value.trim();\n  if (trimmed.length <= maxLength) {\n    return trimmed;\n  }\n  return `${trimmed.slice(0, maxLength - 1)}…`;\n}\n\nfunction toWorkflowResultEnvelope(value: unknown): WorkflowResultEnvelope {\n  if (isWorkflowResultEnvelope(value)) {\n    return value;\n  }\n  if (typeof value === 'string') {\n    return {\n      summary: truncate(value, 800),\n      sections: [{ kind: 'text', title: 'Result', content: value }],\n      raw: value,\n    };\n  }\n  return {\n    summary: 'Workflow completed.',\n    sections: [{ kind: 'json', title: 'Result', value }],\n    raw: value,\n  };\n}\n\nfunction isWorkflowResultEnvelope(value: unknown): value is WorkflowResultEnvelope {\n  if (!value || typeof value !== 'object' || Array.isArray(value)) {\n    return false;\n  }\n  const record = value as Partial<WorkflowResultEnvelope>;\n  return typeof record.summary === 'string' && Array.isArray(record.sections);\n}\n\nfunction toWorkflowRunError(err: unknown, wasAborted: boolean): WorkflowRunError {\n  const message = err instanceof Error ? err.message : String(err);\n  if (wasAborted || /aborted|cancelled/i.test(message)) {\n    return {\n      code: 'cancelled',\n      message: message || 'Workflow run cancelled',\n      recoverable: true,\n    };\n  }\n  if (/timeout/i.test(message)) {\n    return {\n      code: 'timeout',\n      message,\n      recoverable: true,\n    };\n  }\n  if (/quota/i.test(message)) {\n    return {\n      code: 'agent_quota_exceeded',\n      message,\n      recoverable: true,\n    };\n  }\n  return {\n    code: 'runtime_error',\n    message,\n    recoverable: false,\n  };\n}\n"],"mappings":";;;;AAmCA,IAAa,iBAAb,MAA4B;CAC1B,YAAY,SAAiD;AAAhC,OAAA,UAAA;;CAE7B,MAAM,SAAS,YAAgC,SAA4D;EACzG,MAAM,QAAQ,QAAQ,SAAS,YAAY;EAC3C,MAAM,cAAc,KAAK,KAAK;EAC9B,MAAM,iBAAiB,oBAAoB,WAAW;EACtD,IAAI;EACJ,IAAI,aAAa,QAAQ,SAAS;EAElC,MAAM,MAAmB;GACvB,IAAI;GACJ,cAAc,WAAW;GACzB,mBAAmB,WAAW;GAC9B,OAAO,WAAW;GAClB,MAAM,QAAQ,QAAQ,WAAW;GACjC,OAAO,QAAQ,SAAS,EAAE;GAC1B,QAAQ;GACR,QAAQ,QAAQ;GAChB,UAAU,QAAQ;GAClB,SAAS;IACP,YAAY;IACZ,gBAAgB;IAChB,iBAAiB;IACjB,mBAAmB;IACnB,eAAe;IAChB;GACD;GACD;EAED,MAAM,eAAe,MAAyB,SAA+B,wBAAiC;AAC5G,gBAAa,WACV,WACC,KAAK,QAAQ,WAAW,OAAO;IAC7B;IACA;IACA;IACA,aAAa;IACd,CAAC,CACH,CACA,KAAK,OAAO,UAAU;AACrB,SAAK,QAAQ,kBAAkB,MAAM;IACrC,MAAM,OAAO,MAAM,KAAK,QAAQ,SAAS,eAAe,MAAM;AAC9D,QAAI,KACF,MAAK,QAAQ,mBAAmB,KAAK;KAEvC;AACJ,UAAO;;AAGT,QAAM,YAAY,cAAc,EAAE,KAAK,EAAE,YAAY;AACrD,QAAM,YAAY,eAAe,EAAE,aAAa,KAAK,KAAK,EAAE,CAAC;AAE7D,MAAI;GACF,MAAM,gBAAgB,MAAMA,YAC1B,WAAW,QAAQ,QACnB;IACE,QAAQ,KAAK,QAAQ;IACrB,gBAAgB,KAAK,QAAQ;IAC9B,EACD;IACE,KAAK,KAAK,QAAQ;IAClB,MAAM,QAAQ;IACd,QAAQ,QAAQ;IAChB,aAAa,QAAQ,eAAe,WAAW,SAAS;IACxD,cAAc,QAAQ,gBAAgB,WAAW,SAAS;IAC1D,aAAa,QAAQ;IACrB,UAAU,UAAU;KAClB,MAAM,cAAc,eAAe,IAAI,MAAM,IAAI,iBAAiB,MAAM;AACxE,SAAI,kBAAkB,mBAAmB,YAClC,aAAY,mBAAmB,EAAE,SAAS,gBAAgB,CAAC;AAElE,sBAAiB;AACZ,iBAAY,iBAAiB;MAAE,SAAS;MAAa;MAAO,CAAC;;IAEpE,QAAQ,YAAY;AACb,iBAAY,gBAAgB,EAAE,SAAS,CAAC;;IAE/C,gBAAgB,UAAU;KACxB,MAAM,UAAU,MAAM,QAAS,eAAe,IAAI,MAAM,MAAM,IAAI,iBAAiB,MAAM,MAAM,GAAI;AAC9F,iBAAY,gBAAgB;MAC/B,SAAS,qBAAqB,MAAM,GAAG;MACvC,OAAO,MAAM;MACb;MACA,QAAQ,MAAM;MACf,CAAC;;IAEJ,eAAe,UAAU;AAClB,iBAAY,iBAAiB,EAAE,SAAS,qBAAqB,MAAM,GAAG,EAAE,CAAC;;IAEhF,aAAa,UAAU;KACrB,MAAM,kBAAkB,8BAA8B,MAAM,OAAO;AAC9D,iBAAY,mBAAmB;MAClC,SAAS,qBAAqB,MAAM,GAAG;MACvC,QAAQ;MACR,eAAe,qBAAqB,MAAM,OAAO;MACjD,OAAO,oBAAoB,UAAU,oBAAoB,KAAA;MAC1D,CAAC;;IAEL,CACF;AAED,SAAM;AACN,OAAI,eACF,OAAM,YAAY,mBAAmB,EAAE,SAAS,gBAAgB,CAAC;AAEnE,SAAM,YAAY,iBAAiB,EAAE,QAAQ,yBAAyB,cAAc,OAAO,EAAE,CAAC;WACvF,KAAK;AACZ,SAAM;GACN,MAAM,QAAQ,mBAAmB,KAAK,QAAQ,QAAQ,YAAY,KAAK;AACvE,OAAI,MAAM,SAAS,YACjB,OAAM,YAAY,iBAAiB,EAAE,QAAQ,MAAM,SAAS,CAAC;OAE7D,OAAM,YAAY,cAAc,EAAE,OAAO,CAAC;;EAI9C,MAAM,OAAO,MAAM,KAAK,QAAQ,SAAS,YAAY,MAAM;AAC3D,MAAI,CAAC,KACH,OAAM,IAAI,MAAM,yCAAyC,QAAQ;AAEnE,SAAO;;;AAIX,SAAS,oBAAoB,YAAqD;CAChF,MAAM,iCAAiB,IAAI,KAAqB;AAChD,MAAK,MAAM,SAAS,WAAW,OAC7B,gBAAe,IAAI,MAAM,OAAO,MAAM,GAAG;AAE3C,QAAO;;AAGT,SAAS,iBAAiB,OAAuB;AAM/C,QALmB,MAChB,MAAM,CACN,aAAa,CACb,QAAQ,eAAe,IAAI,CAC3B,QAAQ,YAAY,GACN,IAAI;;AAGvB,SAAS,qBAAqB,IAAoB;AAChD,QAAO,SAAS;;AAGlB,SAAS,8BAA8B,QAA8C;AACnF,KAAI,WAAW,UAAU,WAAW,WAAW,WAAW,UACxD,QAAO;AAET,QAAO;;AAGT,SAAS,qBAAqB,OAAoC;AAChE,KAAI,UAAU,QAAQ,UAAU,KAAA,EAC9B;AAEF,KAAI,OAAO,UAAU,SACnB,QAAO,SAAS,OAAO,IAAI;AAE7B,KAAI;AACF,SAAO,SAAS,KAAK,UAAU,MAAM,EAAE,IAAI;SACrC;AACN,SAAO,SAAS,OAAO,MAAM,EAAE,IAAI;;;AAIvC,SAAS,SAAS,OAAe,WAA2B;CAC1D,MAAM,UAAU,MAAM,MAAM;AAC5B,KAAI,QAAQ,UAAU,UACpB,QAAO;AAET,QAAO,GAAG,QAAQ,MAAM,GAAG,YAAY,EAAE,CAAC;;AAG5C,SAAS,yBAAyB,OAAwC;AACxE,KAAI,yBAAyB,MAAM,CACjC,QAAO;AAET,KAAI,OAAO,UAAU,SACnB,QAAO;EACL,SAAS,SAAS,OAAO,IAAI;EAC7B,UAAU,CAAC;GAAE,MAAM;GAAQ,OAAO;GAAU,SAAS;GAAO,CAAC;EAC7D,KAAK;EACN;AAEH,QAAO;EACL,SAAS;EACT,UAAU,CAAC;GAAE,MAAM;GAAQ,OAAO;GAAU;GAAO,CAAC;EACpD,KAAK;EACN;;AAGH,SAAS,yBAAyB,OAAiD;AACjF,KAAI,CAAC,SAAS,OAAO,UAAU,YAAY,MAAM,QAAQ,MAAM,CAC7D,QAAO;CAET,MAAM,SAAS;AACf,QAAO,OAAO,OAAO,YAAY,YAAY,MAAM,QAAQ,OAAO,SAAS;;AAG7E,SAAS,mBAAmB,KAAc,YAAuC;CAC/E,MAAM,UAAU,eAAe,QAAQ,IAAI,UAAU,OAAO,IAAI;AAChE,KAAI,cAAc,qBAAqB,KAAK,QAAQ,CAClD,QAAO;EACL,MAAM;EACN,SAAS,WAAW;EACpB,aAAa;EACd;AAEH,KAAI,WAAW,KAAK,QAAQ,CAC1B,QAAO;EACL,MAAM;EACN;EACA,aAAa;EACd;AAEH,KAAI,SAAS,KAAK,QAAQ,CACxB,QAAO;EACL,MAAM;EACN;EACA,aAAa;EACd;AAEH,QAAO;EACL,MAAM;EACN;EACA,aAAa;EACd"}

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

@@ -1,6 +1,10 @@
 export * from './domain/index.js';
 export * from './engine/index.js';
 export * from './runtime/index.js';
+export * from './service/workflow-run-service.js';
+export * from './service/workflow-session-bridge.js';
+export * from './service/workflow-session-key.js';
+export * from './service/run-view-to-snapshot.js';
 export * from './store/event-store.js';
 export * from './store/paths.js';
 export * from './store/run-store.js';

package/dist/src/workflows/index.js

@@ -1,11 +1,18 @@
 import { parseWorkflowScript } from "../agent/workflow/parser.js";
 import { runWorkflow } from "../agent/workflow/runtime.js";
+import { DEFAULT_WORKFLOW_CONCURRENCY, DEFAULT_WORKFLOW_MAX_SUBAGENTS, DEFAULT_WORKFLOW_TIMEOUT_SEC, buildWorkflowDefinition, normalizeWorkflowDefinitionId, toWorkflowDefinitionTitle } from "./domain/definition-utils.js";
 import { isTerminalWorkflowRunStatus } from "./domain/run.js";
+import { validateWorkflowDefinitionInput } from "./domain/validation.js";
+import "./domain/index.js";
 import { projectWorkflowRunView } from "./engine/projector.js";
 import { WorkflowEngine } from "./engine/workflow-engine.js";
 import "./engine/index.js";
-import "./runtime/index.js";
 import { resolveWorkflowRootDir, resolveWorkflowRunArtifactsDir, resolveWorkflowRunDir, resolveWorkflowRunEventsPath, resolveWorkflowRunViewPath, resolveWorkflowRunsDir } from "./store/paths.js";
 import { WorkflowEventStore, createWorkflowEventStore } from "./store/event-store.js";
 import { WorkflowRunStore, createWorkflowRunStore } from "./store/run-store.js";
-export { WorkflowEngine, WorkflowEventStore, WorkflowRunStore, createWorkflowEventStore, createWorkflowRunStore, isTerminalWorkflowRunStatus, parseWorkflowScript, projectWorkflowRunView, resolveWorkflowRootDir, resolveWorkflowRunArtifactsDir, resolveWorkflowRunDir, resolveWorkflowRunEventsPath, resolveWorkflowRunViewPath, resolveWorkflowRunsDir, runWorkflow as runWorkflowScript };
+import { WorkflowRunService, buildWorkflowRunDefinitionSnapshot, buildWorkflowRunInputEnvelope, buildWorkflowRunMetadata, extractWorkflowRunSessionKey } from "./service/workflow-run-service.js";
+import { runViewToSnapshot } from "./service/run-view-to-snapshot.js";
+import { buildWorkflowRunSessionKey, readWorkflowRunIdFromSessionCustomData } from "./service/workflow-session-key.js";
+import { WORKFLOW_RUN_LINK_CONTEXT_KIND, WORKFLOW_SESSION_TYPE, WorkflowSessionBridge, formatParentRunLinkText } from "./service/workflow-session-bridge.js";
+import "./runtime/index.js";
+export { DEFAULT_WORKFLOW_CONCURRENCY, DEFAULT_WORKFLOW_MAX_SUBAGENTS, DEFAULT_WORKFLOW_TIMEOUT_SEC, WORKFLOW_RUN_LINK_CONTEXT_KIND, WORKFLOW_SESSION_TYPE, WorkflowEngine, WorkflowEventStore, WorkflowRunService, WorkflowRunStore, WorkflowSessionBridge, buildWorkflowDefinition, buildWorkflowRunDefinitionSnapshot, buildWorkflowRunInputEnvelope, buildWorkflowRunMetadata, buildWorkflowRunSessionKey, createWorkflowEventStore, createWorkflowRunStore, extractWorkflowRunSessionKey, formatParentRunLinkText, isTerminalWorkflowRunStatus, normalizeWorkflowDefinitionId, parseWorkflowScript, projectWorkflowRunView, readWorkflowRunIdFromSessionCustomData, resolveWorkflowRootDir, resolveWorkflowRunArtifactsDir, resolveWorkflowRunDir, resolveWorkflowRunEventsPath, resolveWorkflowRunViewPath, resolveWorkflowRunsDir, runViewToSnapshot, runWorkflow as runWorkflowScript, toWorkflowDefinitionTitle, validateWorkflowDefinitionInput };

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;