@xopcai/xopc 0.0.87 → 0.0.89

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

@@ -0,0 +1,14 @@
+//#region src/workflows/domain/run.ts
+const TERMINAL_WORKFLOW_RUN_STATUSES = new Set([
+	"succeeded",
+	"failed",
+	"cancelled",
+	"timeout"
+]);
+function isTerminalWorkflowRunStatus(status) {
+	return TERMINAL_WORKFLOW_RUN_STATUSES.has(status);
+}
+//#endregion
+export { isTerminalWorkflowRunStatus };
+
+//# sourceMappingURL=run.js.map

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

@@ -0,0 +1 @@
+{"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/index.d.ts

@@ -0,0 +1,2 @@
+export * from './projector.js';
+export * from './workflow-engine.js';

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

@@ -0,0 +1,3 @@
+import { projectWorkflowRunView } from "./projector.js";
+import { WorkflowEngine } from "./workflow-engine.js";
+export { WorkflowEngine, projectWorkflowRunView };

package/dist/src/workflows/engine/projector.d.ts

@@ -0,0 +1,3 @@
+import type { WorkflowEventEnvelope } from '../domain/event.js';
+import type { WorkflowRunView } from '../domain/run.js';
+export declare function projectWorkflowRunView(events: WorkflowEventEnvelope[]): WorkflowRunView | null;

package/dist/src/workflows/engine/projector.js

@@ -0,0 +1,205 @@
+import { isTerminalWorkflowRunStatus } from "../domain/run.js";
+//#region src/workflows/engine/projector.ts
+function terminalRunStatus(status) {
+	return isTerminalWorkflowRunStatus(status);
+}
+function phaseStatusAfterAgentStatus(agentStatuses) {
+	if (agentStatuses.some((status) => status === "running")) return "running";
+	if (agentStatuses.some((status) => status === "error")) return "failed";
+	if (agentStatuses.length > 0 && agentStatuses.every((status) => status === "done" || status === "skipped")) return "completed";
+	return "pending";
+}
+function buildTimelineItem(event) {
+	return {
+		sequence: event.sequence,
+		type: event.type,
+		title: event.type.replaceAll("_", " "),
+		createdAtMs: event.createdAtMs
+	};
+}
+function projectWorkflowRunView(events) {
+	if (events.length === 0) return null;
+	const orderedEvents = [...events].sort((left, right) => left.sequence - right.sequence);
+	const firstEvent = orderedEvents[0];
+	if (firstEvent.type !== "run_queued") return null;
+	const firstPayload = firstEvent.payload;
+	if (!firstPayload.run) return null;
+	const run = {
+		...firstPayload.run,
+		metrics: { ...firstPayload.run.metrics }
+	};
+	const phaseIdToPhase = /* @__PURE__ */ new Map();
+	const agentIdToAgent = /* @__PURE__ */ new Map();
+	const logs = [];
+	const artifacts = [];
+	const timeline = [];
+	for (const event of orderedEvents) {
+		timeline.push(buildTimelineItem(event));
+		switch (event.type) {
+			case "run_started": {
+				const payload = event.payload;
+				run.status = "running";
+				run.startedAtMs = payload.startedAtMs;
+				break;
+			}
+			case "phase_started": {
+				const payload = event.payload;
+				phaseIdToPhase.set(payload.phaseId, {
+					id: payload.phaseId,
+					title: payload.title,
+					status: "running",
+					startedAtMs: event.createdAtMs,
+					agentIds: phaseIdToPhase.get(payload.phaseId)?.agentIds ?? []
+				});
+				break;
+			}
+			case "phase_completed": {
+				const payload = event.payload;
+				const existing = phaseIdToPhase.get(payload.phaseId);
+				if (existing) phaseIdToPhase.set(payload.phaseId, {
+					...existing,
+					status: "completed",
+					completedAtMs: event.createdAtMs
+				});
+				break;
+			}
+			case "agent_queued": {
+				const payload = event.payload;
+				agentIdToAgent.set(payload.agentId, {
+					id: payload.agentId,
+					label: payload.label,
+					phaseId: payload.phaseId,
+					status: "queued",
+					prompt: payload.prompt,
+					steps: []
+				});
+				if (payload.phaseId) {
+					const existingPhase = phaseIdToPhase.get(payload.phaseId);
+					if (existingPhase && !existingPhase.agentIds.includes(payload.agentId)) phaseIdToPhase.set(payload.phaseId, {
+						...existingPhase,
+						agentIds: [...existingPhase.agentIds, payload.agentId]
+					});
+				}
+				break;
+			}
+			case "agent_started": {
+				const payload = event.payload;
+				const existing = agentIdToAgent.get(payload.agentId);
+				if (existing) agentIdToAgent.set(payload.agentId, {
+					...existing,
+					status: "running",
+					startedAtMs: event.createdAtMs
+				});
+				break;
+			}
+			case "agent_step_started": {
+				const payload = event.payload;
+				const existing = agentIdToAgent.get(payload.agentId);
+				if (existing) agentIdToAgent.set(payload.agentId, {
+					...existing,
+					currentStep: payload.label,
+					steps: [...existing.steps, {
+						id: payload.stepId,
+						label: payload.label,
+						kind: payload.kind,
+						detail: payload.detail,
+						status: "running",
+						startedAtMs: event.createdAtMs
+					}]
+				});
+				break;
+			}
+			case "agent_step_completed": {
+				const payload = event.payload;
+				const existing = agentIdToAgent.get(payload.agentId);
+				if (existing) agentIdToAgent.set(payload.agentId, {
+					...existing,
+					steps: existing.steps.map((step) => step.id === payload.stepId ? {
+						...step,
+						status: payload.status,
+						completedAtMs: event.createdAtMs
+					} : step)
+				});
+				break;
+			}
+			case "agent_completed": {
+				const payload = event.payload;
+				const existing = agentIdToAgent.get(payload.agentId);
+				if (existing) agentIdToAgent.set(payload.agentId, {
+					...existing,
+					status: payload.status,
+					currentStep: void 0,
+					resultPreview: payload.resultPreview,
+					error: payload.error,
+					completedAtMs: event.createdAtMs
+				});
+				break;
+			}
+			case "log_appended": {
+				const payload = event.payload;
+				logs.push({
+					sequence: event.sequence,
+					message: payload.message,
+					createdAtMs: event.createdAtMs
+				});
+				break;
+			}
+			case "artifact_created": {
+				const payload = event.payload;
+				artifacts.push(payload.artifact);
+				run.metrics.artifactCount = artifacts.length;
+				break;
+			}
+			case "run_completed": {
+				const payload = event.payload;
+				run.status = "succeeded";
+				run.result = payload.result;
+				run.completedAtMs = event.createdAtMs;
+				break;
+			}
+			case "run_failed": {
+				const payload = event.payload;
+				run.status = payload.error?.code === "timeout" ? "timeout" : "failed";
+				run.error = payload.error;
+				run.completedAtMs = event.createdAtMs;
+				break;
+			}
+			case "run_cancelled":
+				run.status = "cancelled";
+				run.completedAtMs = event.createdAtMs;
+				break;
+			default: break;
+		}
+	}
+	const agents = [...agentIdToAgent.values()];
+	run.metrics.agentCount = agents.length;
+	run.metrics.doneAgentCount = agents.filter((agent) => agent.status === "done").length;
+	run.metrics.errorAgentCount = agents.filter((agent) => agent.status === "error").length;
+	run.metrics.skippedAgentCount = agents.filter((agent) => agent.status === "skipped").length;
+	run.metrics.artifactCount = artifacts.length;
+	if (run.startedAtMs && run.completedAtMs) run.metrics.durationMs = run.completedAtMs - run.startedAtMs;
+	return {
+		run,
+		phases: [...phaseIdToPhase.values()].map((phase) => {
+			if (phase.status === "completed" || phase.status === "failed") return phase;
+			const phaseAgents = phase.agentIds.map((agentId) => agentIdToAgent.get(agentId)?.status).filter((status) => Boolean(status));
+			return {
+				...phase,
+				status: phaseStatusAfterAgentStatus(phaseAgents)
+			};
+		}),
+		agents,
+		logs,
+		artifacts,
+		timeline,
+		controls: {
+			canCancel: !terminalRunStatus(run.status),
+			canRetry: terminalRunStatus(run.status),
+			canArchive: terminalRunStatus(run.status)
+		}
+	};
+}
+//#endregion
+export { projectWorkflowRunView };
+
+//# sourceMappingURL=projector.js.map

package/dist/src/workflows/engine/projector.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"projector.js","names":[],"sources":["../../../../src/workflows/engine/projector.ts"],"sourcesContent":["import type { WorkflowEventEnvelope } from '../domain/event.js';\nimport type {\n  WorkflowAgentStatus,\n  WorkflowAgentView,\n  WorkflowLogEntry,\n  WorkflowPhaseStatus,\n  WorkflowPhaseView,\n  WorkflowRun,\n  WorkflowRunView,\n  WorkflowTimelineItem,\n} from '../domain/run.js';\nimport { isTerminalWorkflowRunStatus } from '../domain/run.js';\nimport type { WorkflowArtifactRef } from '../domain/result.js';\n\nfunction terminalRunStatus(status: WorkflowRun['status']): boolean {\n  return isTerminalWorkflowRunStatus(status);\n}\n\nfunction phaseStatusAfterAgentStatus(agentStatuses: WorkflowAgentStatus[]): WorkflowPhaseStatus {\n  if (agentStatuses.some((status) => status === 'running')) {\n    return 'running';\n  }\n  if (agentStatuses.some((status) => status === 'error')) {\n    return 'failed';\n  }\n  if (agentStatuses.length > 0 && agentStatuses.every((status) => status === 'done' || status === 'skipped')) {\n    return 'completed';\n  }\n  return 'pending';\n}\n\nfunction buildTimelineItem(event: WorkflowEventEnvelope): WorkflowTimelineItem {\n  return {\n    sequence: event.sequence,\n    type: event.type,\n    title: event.type.replaceAll('_', ' '),\n    createdAtMs: event.createdAtMs,\n  };\n}\n\nexport function projectWorkflowRunView(events: WorkflowEventEnvelope[]): WorkflowRunView | null {\n  if (events.length === 0) {\n    return null;\n  }\n\n  const orderedEvents = [...events].sort((left, right) => left.sequence - right.sequence);\n  const firstEvent = orderedEvents[0];\n  if (firstEvent.type !== 'run_queued') {\n    return null;\n  }\n\n  const firstPayload = firstEvent.payload as { run?: WorkflowRun };\n  if (!firstPayload.run) {\n    return null;\n  }\n\n  const run: WorkflowRun = {\n    ...firstPayload.run,\n    metrics: { ...firstPayload.run.metrics },\n  };\n  const phaseIdToPhase = new Map<string, WorkflowPhaseView>();\n  const agentIdToAgent = new Map<string, WorkflowAgentView>();\n  const logs: WorkflowLogEntry[] = [];\n  const artifacts: WorkflowArtifactRef[] = [];\n  const timeline: WorkflowTimelineItem[] = [];\n\n  for (const event of orderedEvents) {\n    timeline.push(buildTimelineItem(event));\n\n    switch (event.type) {\n      case 'run_started': {\n        const payload = event.payload as { startedAtMs: number };\n        run.status = 'running';\n        run.startedAtMs = payload.startedAtMs;\n        break;\n      }\n      case 'phase_started': {\n        const payload = event.payload as { phaseId: string; title: string };\n        phaseIdToPhase.set(payload.phaseId, {\n          id: payload.phaseId,\n          title: payload.title,\n          status: 'running',\n          startedAtMs: event.createdAtMs,\n          agentIds: phaseIdToPhase.get(payload.phaseId)?.agentIds ?? [],\n        });\n        break;\n      }\n      case 'phase_completed': {\n        const payload = event.payload as { phaseId: string };\n        const existing = phaseIdToPhase.get(payload.phaseId);\n        if (existing) {\n          phaseIdToPhase.set(payload.phaseId, {\n            ...existing,\n            status: 'completed',\n            completedAtMs: event.createdAtMs,\n          });\n        }\n        break;\n      }\n      case 'agent_queued': {\n        const payload = event.payload as { agentId: string; label: string; phaseId?: string; prompt?: string };\n        agentIdToAgent.set(payload.agentId, {\n          id: payload.agentId,\n          label: payload.label,\n          phaseId: payload.phaseId,\n          status: 'queued',\n          prompt: payload.prompt,\n          steps: [],\n        });\n        if (payload.phaseId) {\n          const existingPhase = phaseIdToPhase.get(payload.phaseId);\n          if (existingPhase && !existingPhase.agentIds.includes(payload.agentId)) {\n            phaseIdToPhase.set(payload.phaseId, {\n              ...existingPhase,\n              agentIds: [...existingPhase.agentIds, payload.agentId],\n            });\n          }\n        }\n        break;\n      }\n      case 'agent_started': {\n        const payload = event.payload as { agentId: string };\n        const existing = agentIdToAgent.get(payload.agentId);\n        if (existing) {\n          agentIdToAgent.set(payload.agentId, {\n            ...existing,\n            status: 'running',\n            startedAtMs: event.createdAtMs,\n          });\n        }\n        break;\n      }\n      case 'agent_step_started': {\n        const payload = event.payload as {\n          agentId: string;\n          stepId: string;\n          label: string;\n          kind: 'tool' | 'llm' | 'thinking';\n          detail?: string;\n        };\n        const existing = agentIdToAgent.get(payload.agentId);\n        if (existing) {\n          agentIdToAgent.set(payload.agentId, {\n            ...existing,\n            currentStep: payload.label,\n            steps: [\n              ...existing.steps,\n              {\n                id: payload.stepId,\n                label: payload.label,\n                kind: payload.kind,\n                detail: payload.detail,\n                status: 'running',\n                startedAtMs: event.createdAtMs,\n              },\n            ],\n          });\n        }\n        break;\n      }\n      case 'agent_step_completed': {\n        const payload = event.payload as { agentId: string; stepId: string; status: 'done' | 'error' };\n        const existing = agentIdToAgent.get(payload.agentId);\n        if (existing) {\n          agentIdToAgent.set(payload.agentId, {\n            ...existing,\n            steps: existing.steps.map((step) =>\n              step.id === payload.stepId\n                ? {\n                    ...step,\n                    status: payload.status,\n                    completedAtMs: event.createdAtMs,\n                  }\n                : step,\n            ),\n          });\n        }\n        break;\n      }\n      case 'agent_completed': {\n        const payload = event.payload as {\n          agentId: string;\n          status: WorkflowAgentStatus;\n          resultPreview?: string;\n          error?: string;\n        };\n        const existing = agentIdToAgent.get(payload.agentId);\n        if (existing) {\n          agentIdToAgent.set(payload.agentId, {\n            ...existing,\n            status: payload.status,\n            currentStep: undefined,\n            resultPreview: payload.resultPreview,\n            error: payload.error,\n            completedAtMs: event.createdAtMs,\n          });\n        }\n        break;\n      }\n      case 'log_appended': {\n        const payload = event.payload as { message: string };\n        logs.push({ sequence: event.sequence, message: payload.message, createdAtMs: event.createdAtMs });\n        break;\n      }\n      case 'artifact_created': {\n        const payload = event.payload as { artifact: WorkflowArtifactRef };\n        artifacts.push(payload.artifact);\n        run.metrics.artifactCount = artifacts.length;\n        break;\n      }\n      case 'run_completed': {\n        const payload = event.payload as { result: WorkflowRun['result'] };\n        run.status = 'succeeded';\n        run.result = payload.result;\n        run.completedAtMs = event.createdAtMs;\n        break;\n      }\n      case 'run_failed': {\n        const payload = event.payload as { error: WorkflowRun['error'] };\n        run.status = payload.error?.code === 'timeout' ? 'timeout' : 'failed';\n        run.error = payload.error;\n        run.completedAtMs = event.createdAtMs;\n        break;\n      }\n      case 'run_cancelled': {\n        run.status = 'cancelled';\n        run.completedAtMs = event.createdAtMs;\n        break;\n      }\n      case 'run_queued':\n      default:\n        break;\n    }\n  }\n\n  const agents = [...agentIdToAgent.values()];\n  run.metrics.agentCount = agents.length;\n  run.metrics.doneAgentCount = agents.filter((agent) => agent.status === 'done').length;\n  run.metrics.errorAgentCount = agents.filter((agent) => agent.status === 'error').length;\n  run.metrics.skippedAgentCount = agents.filter((agent) => agent.status === 'skipped').length;\n  run.metrics.artifactCount = artifacts.length;\n  if (run.startedAtMs && run.completedAtMs) {\n    run.metrics.durationMs = run.completedAtMs - run.startedAtMs;\n  }\n\n  const phases = [...phaseIdToPhase.values()].map((phase) => {\n    if (phase.status === 'completed' || phase.status === 'failed') {\n      return phase;\n    }\n    const phaseAgents = phase.agentIds\n      .map((agentId) => agentIdToAgent.get(agentId)?.status)\n      .filter((status): status is WorkflowAgentStatus => Boolean(status));\n    return { ...phase, status: phaseStatusAfterAgentStatus(phaseAgents) };\n  });\n\n  return {\n    run,\n    phases,\n    agents,\n    logs,\n    artifacts,\n    timeline,\n    controls: {\n      canCancel: !terminalRunStatus(run.status),\n      canRetry: terminalRunStatus(run.status),\n      canArchive: terminalRunStatus(run.status),\n    },\n  };\n}\n"],"mappings":"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"}

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

@@ -0,0 +1,32 @@
+import type { WorkflowDefinition } from '../domain/definition.js';
+import type { WorkflowEventEnvelope } from '../domain/event.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';
+import type { WorkflowScriptSubagentRunner } from '../runtime/script-runtime.js';
+export interface WorkflowEngineOptions {
+    cwd: string;
+    eventStore: WorkflowEventStore;
+    runStore: WorkflowRunStore;
+    runner: WorkflowScriptSubagentRunner;
+    onEventAppended?: (event: WorkflowEventEnvelope) => void;
+    onRunViewUpdated?: (view: WorkflowRunView) => void;
+    resolveModelId?: (modelId: string) => Model<Api>;
+}
+export interface StartWorkflowRunOptions {
+    input?: unknown;
+    source: WorkflowRunSource;
+    metadata?: WorkflowRunMetadata;
+    goal?: string;
+    runId?: string;
+    signal?: AbortSignal;
+    concurrency?: number;
+    maxSubagents?: number;
+    tokenBudget?: number | null;
+}
+export declare class WorkflowEngine {
+    private readonly options;
+    constructor(options: WorkflowEngineOptions);
+    startRun(definition: WorkflowDefinition, options: StartWorkflowRunOptions): Promise<WorkflowRunView>;
+}

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

@@ -0,0 +1,189 @@
+import { runWorkflow } from "../../agent/workflow/runtime.js";
+import "../runtime/script-runtime.js";
+import { randomUUID } from "node:crypto";
+//#region src/workflows/engine/workflow-engine.ts
+var WorkflowEngine = class {
+	constructor(options) {
+		this.options = options;
+	}
+	async startRun(definition, options) {
+		const runId = options.runId ?? randomUUID();
+		const createdAtMs = Date.now();
+		const phaseTitleToId = buildPhaseTitleToId(definition);
+		let currentPhaseId;
+		let eventQueue = Promise.resolve();
+		const run = {
+			id: runId,
+			definitionId: definition.id,
+			definitionVersion: definition.version,
+			title: definition.title,
+			goal: options.goal ?? definition.description,
+			input: options.input ?? {},
+			status: "queued",
+			source: options.source,
+			metadata: options.metadata,
+			metrics: {
+				agentCount: 0,
+				doneAgentCount: 0,
+				errorAgentCount: 0,
+				skippedAgentCount: 0,
+				artifactCount: 0
+			},
+			createdAtMs
+		};
+		const appendEvent = (type, payload, createdAtMsOverride) => {
+			eventQueue = eventQueue.then(() => this.options.eventStore.append({
+				runId,
+				type,
+				payload,
+				createdAtMs: createdAtMsOverride
+			})).then(async (event) => {
+				this.options.onEventAppended?.(event);
+				const view = await this.options.runStore.rebuildRunView(runId);
+				if (view) this.options.onRunViewUpdated?.(view);
+			});
+			return eventQueue;
+		};
+		await appendEvent("run_queued", { run }, createdAtMs);
+		await appendEvent("run_started", { startedAtMs: Date.now() });
+		try {
+			const runtimeResult = await runWorkflow(definition.runtime.source, {
+				runner: this.options.runner,
+				resolveModelId: this.options.resolveModelId
+			}, {
+				cwd: this.options.cwd,
+				args: options.input,
+				signal: options.signal,
+				concurrency: options.concurrency ?? definition.defaults.concurrency,
+				maxSubagents: options.maxSubagents ?? definition.defaults.maxSubagents,
+				tokenBudget: options.tokenBudget,
+				onPhase: (title) => {
+					const nextPhaseId = phaseTitleToId.get(title) ?? normalizePhaseId(title);
+					if (currentPhaseId && currentPhaseId !== nextPhaseId) appendEvent("phase_completed", { phaseId: currentPhaseId });
+					currentPhaseId = nextPhaseId;
+					appendEvent("phase_started", {
+						phaseId: nextPhaseId,
+						title
+					});
+				},
+				onLog: (message) => {
+					appendEvent("log_appended", { message });
+				},
+				onAgentQueued: (event) => {
+					const phaseId = event.phase ? phaseTitleToId.get(event.phase) ?? normalizePhaseId(event.phase) : currentPhaseId;
+					appendEvent("agent_queued", {
+						agentId: formatRuntimeAgentId(event.id),
+						label: event.label,
+						phaseId,
+						prompt: event.prompt
+					});
+				},
+				onAgentStart: (event) => {
+					appendEvent("agent_started", { agentId: formatRuntimeAgentId(event.id) });
+				},
+				onAgentEnd: (event) => {
+					const completedStatus = normalizeCompletedAgentStatus(event.status);
+					appendEvent("agent_completed", {
+						agentId: formatRuntimeAgentId(event.id),
+						status: completedStatus,
+						resultPreview: previewWorkflowValue(event.result),
+						error: completedStatus === "error" ? "Subagent failed" : void 0
+					});
+				}
+			});
+			await eventQueue;
+			if (currentPhaseId) await appendEvent("phase_completed", { phaseId: currentPhaseId });
+			await appendEvent("run_completed", { result: toWorkflowResultEnvelope(runtimeResult.result) });
+		} catch (err) {
+			await eventQueue;
+			const error = toWorkflowRunError(err, options.signal?.aborted === true);
+			if (error.code === "cancelled") await appendEvent("run_cancelled", { reason: error.message });
+			else await appendEvent("run_failed", { error });
+		}
+		const view = await this.options.runStore.readRunView(runId);
+		if (!view) throw new Error(`workflow run view was not created for ${runId}`);
+		return view;
+	}
+};
+function buildPhaseTitleToId(definition) {
+	const phaseTitleToId = /* @__PURE__ */ new Map();
+	for (const phase of definition.phases) phaseTitleToId.set(phase.title, phase.id);
+	return phaseTitleToId;
+}
+function normalizePhaseId(title) {
+	return title.trim().toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "") || "phase";
+}
+function formatRuntimeAgentId(id) {
+	return `agent-${id}`;
+}
+function normalizeCompletedAgentStatus(status) {
+	if (status === "done" || status === "error" || status === "skipped") return status;
+	return "error";
+}
+function previewWorkflowValue(value) {
+	if (value === null || value === void 0) return;
+	if (typeof value === "string") return truncate(value, 300);
+	try {
+		return truncate(JSON.stringify(value), 300);
+	} catch {
+		return truncate(String(value), 300);
+	}
+}
+function truncate(value, maxLength) {
+	const trimmed = value.trim();
+	if (trimmed.length <= maxLength) return trimmed;
+	return `${trimmed.slice(0, maxLength - 1)}…`;
+}
+function toWorkflowResultEnvelope(value) {
+	if (isWorkflowResultEnvelope(value)) return value;
+	if (typeof value === "string") return {
+		summary: truncate(value, 800),
+		sections: [{
+			kind: "text",
+			title: "Result",
+			content: value
+		}],
+		raw: value
+	};
+	return {
+		summary: "Workflow completed.",
+		sections: [{
+			kind: "json",
+			title: "Result",
+			value
+		}],
+		raw: value
+	};
+}
+function isWorkflowResultEnvelope(value) {
+	if (!value || typeof value !== "object" || Array.isArray(value)) return false;
+	const record = value;
+	return typeof record.summary === "string" && Array.isArray(record.sections);
+}
+function toWorkflowRunError(err, wasAborted) {
+	const message = err instanceof Error ? err.message : String(err);
+	if (wasAborted || /aborted|cancelled/i.test(message)) return {
+		code: "cancelled",
+		message: message || "Workflow run cancelled",
+		recoverable: true
+	};
+	if (/timeout/i.test(message)) return {
+		code: "timeout",
+		message,
+		recoverable: true
+	};
+	if (/quota/i.test(message)) return {
+		code: "agent_quota_exceeded",
+		message,
+		recoverable: true
+	};
+	return {
+		code: "runtime_error",
+		message,
+		recoverable: false
+	};
+}
+//#endregion
+export { WorkflowEngine };
+
+//# sourceMappingURL=workflow-engine.js.map

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

@@ -0,0 +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, 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":"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"}

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

@@ -0,0 +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

@@ -0,0 +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 { 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";
+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 };