@alneas/eaos-server 0.0.0-stage → 0.2.0

package/dist/chunk-BKAHUEIT.js

@@ -0,0 +1,95 @@
+// src/tenant.ts
+var TenantResolver = class {
+  defaultTenantId;
+  domainTenantMap;
+  hostTenantMap;
+  /**
+   * Copies routing mappings, normalizing their keys to lower case.
+   * @param options - Routing mappings and fallback; omitted options use empty mappings and "default".
+   */
+  constructor(options = {}) {
+    this.defaultTenantId = options.defaultTenantId ?? "default";
+    this.domainTenantMap = new Map(
+      Object.entries(options.domainTenantMap ?? {}).map(([k, v]) => [k.toLowerCase(), v])
+    );
+    this.hostTenantMap = new Map(
+      Object.entries(options.hostTenantMap ?? {}).map(([k, v]) => [k.toLowerCase(), v])
+    );
+  }
+  /**
+   * Looks up the lower-case domain following the first @ in an email routing hint.
+   * @param email - Email hint; missing, empty, or missing @ returns null. No address validation is performed.
+   * @returns The configured routing ID, or null when no domain matches.
+   * @example
+   * ```typescript
+   * import { TenantResolver } from "@alneas/eaos-server/tenant";
+   * const resolver = new TenantResolver({ domainTenantMap: { "example.com": "workspace" } });
+   * console.log(resolver.resolveFromEmail("person@example.com"));
+   * ```
+   */
+  resolveFromEmail(email) {
+    if (!email) return null;
+    const parts = email.split("@");
+    if (parts.length < 2) return null;
+    const domain = parts[1].toLowerCase();
+    return this.domainTenantMap.get(domain) ?? null;
+  }
+  /**
+   * Looks up a configured hostname after removing text following the first colon and lower-casing.
+   * @param host - Host routing hint, optionally including a port; missing or empty values return null. IPv6 host parsing is not provided.
+   * @returns The exact configured host mapping, or null.
+   * @example
+   * ```typescript
+   * import { TenantResolver } from "@alneas/eaos-server/tenant";
+   * const resolver = new TenantResolver({ hostTenantMap: { "workspace.example.com": "workspace" } });
+   * console.log(resolver.resolveFromHost("workspace.example.com:443"));
+   * ```
+   */
+  resolveFromHost(host) {
+    if (!host) return null;
+    const cleanHost = host.split(":")[0].toLowerCase();
+    if (this.hostTenantMap.has(cleanHost)) {
+      return this.hostTenantMap.get(cleanHost);
+    }
+    return null;
+  }
+  /**
+   * Selects a truthy explicit ID, then a host mapping, then the configured fallback.
+   * @param input - Routing hints: explicitTenantId takes precedence over host; email is intentionally ignored. The host must establish whether an explicit ID is trusted.
+   * @returns The selected routing ID, without validating tenant existence or membership.
+   * @see TenantResolver for a complete usage example.
+   * @example
+   * ```typescript
+   * import { TenantResolver } from "@alneas/eaos-server/tenant";
+   * const resolver = new TenantResolver();
+   * console.log(resolver.resolve({ explicitTenantId: "workspace" }));
+   * ```
+   */
+  resolve(input) {
+    if (input.explicitTenantId) return input.explicitTenantId;
+    const fromHost = this.resolveFromHost(input.host);
+    if (fromHost) return fromHost;
+    return this.defaultTenantId;
+  }
+  /**
+   * Reads the fallback ID captured at construction.
+   * @returns The configured fallback, or "default" when none was supplied.
+   * @example
+   * ```typescript
+   * import { TenantResolver } from "@alneas/eaos-server/tenant";
+   * console.log(new TenantResolver().getDefaultTenantId());
+   * ```
+   */
+  getDefaultTenantId() {
+    return this.defaultTenantId;
+  }
+};
+function createTenantResolver(options) {
+  return new TenantResolver(options);
+}
+
+export {
+  TenantResolver,
+  createTenantResolver
+};
+//# sourceMappingURL=chunk-BKAHUEIT.js.map

package/dist/chunk-BKAHUEIT.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/tenant.ts"],"sourcesContent":["/**\n * Routing hints used by {@link TenantResolver}; they do not authenticate a tenant.\n * @see TenantResolver for a complete usage example.\n */\nexport interface TenantResolverOptions {\n  /** Fallback when no explicit ID or host mapping matches. @defaultValue \"default\" */\n  defaultTenantId?: string\n  /** Routing-only email domain mappings. Never use email-derived results as an authenticated tenant claim. */\n  domainTenantMap?: Record<string, string>\n  /** Trusted, exact hostname mappings (e.g. { \"demo.example.com\": \"tenant-demo\" }). */\n  hostTenantMap?: Record<string, string>\n}\n\n/**\n * Selects a tenant routing ID from an explicit trusted ID, configured host, or fallback.\n * @remarks This resolver performs no authentication or membership check. Host headers and explicit IDs must be validated by the host before being used for authorization. Email mappings are exposed only by resolveFromEmail.\n * @example\n * ```typescript\n * import { TenantResolver } from \"@alneas/eaos-server/tenant\";\n * const resolver = new TenantResolver({ hostTenantMap: { \"workspace.example.com\": \"workspace\" } });\n * const tenantId = resolver.resolve({ host: \"workspace.example.com:443\" });\n * console.log(tenantId); // \"workspace\"\n * ```\n */\nexport class TenantResolver {\n  private defaultTenantId: string\n  private domainTenantMap: Map<string, string>\n  private hostTenantMap: Map<string, string>\n\n  /**\n   * Copies routing mappings, normalizing their keys to lower case.\n   * @param options - Routing mappings and fallback; omitted options use empty mappings and \"default\".\n   */\n  constructor(options: TenantResolverOptions = {}) {\n    this.defaultTenantId = options.defaultTenantId ?? 'default'\n    this.domainTenantMap = new Map(\n      Object.entries(options.domainTenantMap ?? {}).map(([k, v]) => [k.toLowerCase(), v])\n    )\n    this.hostTenantMap = new Map(\n      Object.entries(options.hostTenantMap ?? {}).map(([k, v]) => [k.toLowerCase(), v])\n    )\n  }\n\n  /**\n   * Looks up the lower-case domain following the first @ in an email routing hint.\n   * @param email - Email hint; missing, empty, or missing @ returns null. No address validation is performed.\n   * @returns The configured routing ID, or null when no domain matches.\n   * @example\n   * ```typescript\n   * import { TenantResolver } from \"@alneas/eaos-server/tenant\";\n   * const resolver = new TenantResolver({ domainTenantMap: { \"example.com\": \"workspace\" } });\n   * console.log(resolver.resolveFromEmail(\"person@example.com\"));\n   * ```\n   */\n  resolveFromEmail(email: string | null | undefined): string | null {\n    if (!email) return null\n    const parts = email.split('@')\n    if (parts.length < 2) return null\n    const domain = parts[1].toLowerCase()\n    return this.domainTenantMap.get(domain) ?? null\n  }\n\n  /**\n   * Looks up a configured hostname after removing text following the first colon and lower-casing.\n   * @param host - Host routing hint, optionally including a port; missing or empty values return null. IPv6 host parsing is not provided.\n   * @returns The exact configured host mapping, or null.\n   * @example\n   * ```typescript\n   * import { TenantResolver } from \"@alneas/eaos-server/tenant\";\n   * const resolver = new TenantResolver({ hostTenantMap: { \"workspace.example.com\": \"workspace\" } });\n   * console.log(resolver.resolveFromHost(\"workspace.example.com:443\"));\n   * ```\n   */\n  resolveFromHost(host: string | null | undefined): string | null {\n    if (!host) return null\n    const cleanHost = host.split(':')[0].toLowerCase()\n    if (this.hostTenantMap.has(cleanHost)) {\n      return this.hostTenantMap.get(cleanHost)!\n    }\n    return null\n  }\n\n  /**\n   * Selects a truthy explicit ID, then a host mapping, then the configured fallback.\n   * @param input - Routing hints: explicitTenantId takes precedence over host; email is intentionally ignored. The host must establish whether an explicit ID is trusted.\n   * @returns The selected routing ID, without validating tenant existence or membership.\n   * @see TenantResolver for a complete usage example.\n   * @example\n   * ```typescript\n   * import { TenantResolver } from \"@alneas/eaos-server/tenant\";\n   * const resolver = new TenantResolver();\n   * console.log(resolver.resolve({ explicitTenantId: \"workspace\" }));\n   * ```\n   */\n  resolve(input: { \n  /**\n   * Optional host routing hint, including a possible port; checked only after a falsy/absent explicitTenantId against configured exact host mappings.\n   */\n  host?: string | null; \n  /**\n   * Optional compatibility routing hint intentionally ignored by resolve; an email domain is not an authenticated tenant claim.\n   */\n  email?: string | null; \n  /**\n   * Optional trusted tenant routing selection; any truthy value takes precedence without tenant-existence or membership validation.\n   */\n  explicitTenantId?: string | null }): string {\n    if (input.explicitTenantId) return input.explicitTenantId\n    // Email domains are routing hints only; they are deliberately not accepted\n    // as an authenticated tenant selector.\n    const fromHost = this.resolveFromHost(input.host)\n    if (fromHost) return fromHost\n    return this.defaultTenantId\n  }\n\n  /**\n   * Reads the fallback ID captured at construction.\n   * @returns The configured fallback, or \"default\" when none was supplied.\n   * @example\n   * ```typescript\n   * import { TenantResolver } from \"@alneas/eaos-server/tenant\";\n   * console.log(new TenantResolver().getDefaultTenantId());\n   * ```\n   */\n  getDefaultTenantId(): string {\n    return this.defaultTenantId\n  }\n}\n\n/**\n * Creates a resolver for host-owned tenant routing hints.\n * @param options - Routing mappings and fallback; see {@link TenantResolverOptions}.\n * @returns A new independent resolver with copied mappings.\n * @example\n * ```typescript\n * import { createTenantResolver } from \"@alneas/eaos-server/tenant\";\n * const resolver = createTenantResolver({ defaultTenantId: \"workspace\" });\n * console.log(resolver.resolve({}));\n * ```\n */\nexport function createTenantResolver(options?: TenantResolverOptions): TenantResolver {\n  return new TenantResolver(options)\n}\n"],"mappings":";AAwBO,IAAM,iBAAN,MAAqB;AAAA,EAClB;AAAA,EACA;AAAA,EACA;AAAA;AAAA;AAAA;AAAA;AAAA,EAMR,YAAY,UAAiC,CAAC,GAAG;AAC/C,SAAK,kBAAkB,QAAQ,mBAAmB;AAClD,SAAK,kBAAkB,IAAI;AAAA,MACzB,OAAO,QAAQ,QAAQ,mBAAmB,CAAC,CAAC,EAAE,IAAI,CAAC,CAAC,GAAG,CAAC,MAAM,CAAC,EAAE,YAAY,GAAG,CAAC,CAAC;AAAA,IACpF;AACA,SAAK,gBAAgB,IAAI;AAAA,MACvB,OAAO,QAAQ,QAAQ,iBAAiB,CAAC,CAAC,EAAE,IAAI,CAAC,CAAC,GAAG,CAAC,MAAM,CAAC,EAAE,YAAY,GAAG,CAAC,CAAC;AAAA,IAClF;AAAA,EACF;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAaA,iBAAiB,OAAiD;AAChE,QAAI,CAAC,MAAO,QAAO;AACnB,UAAM,QAAQ,MAAM,MAAM,GAAG;AAC7B,QAAI,MAAM,SAAS,EAAG,QAAO;AAC7B,UAAM,SAAS,MAAM,CAAC,EAAE,YAAY;AACpC,WAAO,KAAK,gBAAgB,IAAI,MAAM,KAAK;AAAA,EAC7C;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAaA,gBAAgB,MAAgD;AAC9D,QAAI,CAAC,KAAM,QAAO;AAClB,UAAM,YAAY,KAAK,MAAM,GAAG,EAAE,CAAC,EAAE,YAAY;AACjD,QAAI,KAAK,cAAc,IAAI,SAAS,GAAG;AACrC,aAAO,KAAK,cAAc,IAAI,SAAS;AAAA,IACzC;AACA,WAAO;AAAA,EACT;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAcA,QAAQ,OAYoC;AAC1C,QAAI,MAAM,iBAAkB,QAAO,MAAM;AAGzC,UAAM,WAAW,KAAK,gBAAgB,MAAM,IAAI;AAChD,QAAI,SAAU,QAAO;AACrB,WAAO,KAAK;AAAA,EACd;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAWA,qBAA6B;AAC3B,WAAO,KAAK;AAAA,EACd;AACF;AAaO,SAAS,qBAAqB,SAAiD;AACpF,SAAO,IAAI,eAAe,OAAO;AACnC;","names":[]}

package/dist/chunk-CJ7OFEF7.js

@@ -0,0 +1,134 @@
+import {
+  AgentGraphEngine
+} from "./chunk-HXFVOR7Z.js";
+
+// src/agentic/workflow-compiler.ts
+import { evaluateWorkflowCondition, validateWorkflowDefinition } from "@alneas/eaos-core";
+async function compileWorkflowDefinition(input, options) {
+  const definition = validateWorkflowDefinition(input);
+  if (!options?.catalog) throw new Error("Workflow node catalog is required");
+  const graph = new AgentGraphEngine({
+    checkpointer: options.checkpointer,
+    authorizeResume: options.authorizeResume,
+    workflowId: definition.workflowId,
+    workflowVersion: definition.version
+  });
+  for (const node of definition.nodes) {
+    const registration = options.catalog.require(node.type);
+    const visual = visualNode(node, registration.descriptor);
+    if (node.subflow) {
+      if (!registration.resolveSubgraph) throw new Error(`Workflow node '${node.id}' declares a subflow but '${node.type}' has no subgraph resolver`);
+      const subgraph = await registration.resolveSubgraph({ definition, node });
+      if (!subgraph || typeof subgraph.invoke !== "function") throw new Error(`Workflow subflow '${node.id}' did not resolve to a compiled graph`);
+      graph.addSubgraph(node.id, subgraph, {
+        visual,
+        mapInput: (state) => node.subflow?.inputPath ? valueAtPath(state, node.subflow.inputPath).value : state,
+        mapOutput: (output, state) => ({ context: { ...state.context ?? {}, [node.subflow?.outputKey ?? `${node.id}.output`]: structuredClone(output) } })
+      });
+      continue;
+    }
+    const handler = await registration.resolve({ definition, node });
+    if (typeof handler !== "function") throw new Error(`Workflow node '${node.id}' did not resolve to a handler`);
+    graph.addNode(node.id, wrapNode(node, handler), { retryPolicy: retryPolicy(node), visual });
+  }
+  graph.setEntryPoint(definition.entryNode);
+  for (const node of definition.nodes) {
+    const outgoing = definition.edges.filter((edge) => edge.from === node.id);
+    if (!outgoing.length) continue;
+    for (const edge of outgoing) graph.addEdge(edge.from, edge.to, { visual: edgeVisual(edge) });
+    if (outgoing.some((edge) => edge.condition !== void 0)) {
+      const destinations = [...new Set(outgoing.map((edge) => edge.to))];
+      graph.addConditionalEdges(node.id, (state) => routeDefinitionEdges(outgoing, state), destinations, {
+        labels: Object.fromEntries(outgoing.map((edge) => [edge.to, edge.label ?? (edge.condition ? "\u6761\u4EF6\u5206\u5C90" : "\u65E2\u5B9A")])),
+        visual: { kind: "conditional" }
+      });
+    }
+  }
+  return { definition, graph };
+}
+function wrapNode(node, handler) {
+  return async (state) => {
+    const handlerState = node.toolScope ? { ...structuredClone(state), context: { ...state.context ?? {}, __eaosWorkflowToolScope: structuredClone(node.toolScope) } } : structuredClone(state);
+    const update = await withTimeout(handler(handlerState), node.timeoutMs, node.id);
+    if (!node.approval) return update;
+    const existing = update.pendingApproval;
+    const args = existing?.args ?? (node.approval.argsPath ? valueAtPath({ ...state, ...update }, node.approval.argsPath).value : {});
+    if (!isRecord(args)) throw new Error(`Workflow approval node '${node.id}' args must be an object`);
+    return {
+      ...update,
+      pendingApproval: {
+        ...existing ?? {},
+        toolName: existing?.toolName ?? node.approval.toolName,
+        approvalLevel: existing?.approvalLevel ?? node.approval.approvalLevel,
+        riskLevel: existing?.riskLevel ?? node.approval.riskLevel,
+        reason: existing?.reason ?? node.approval.reason,
+        args: structuredClone(args),
+        ...node.approval.permission === void 0 ? {} : { permission: existing?.permission ?? node.approval.permission },
+        ...node.approval.contractVersion === void 0 ? {} : { contractVersion: existing?.contractVersion ?? node.approval.contractVersion }
+      }
+    };
+  };
+}
+function retryPolicy(node) {
+  if (!node.retry) return void 0;
+  return { maxAttempts: node.retry.maxAttempts, initialInterval: node.retry.backoffMs, maxInterval: node.retry.maxBackoffMs, jitter: node.retry.jitter };
+}
+function visualNode(node, descriptor) {
+  return {
+    kind: node.kind ?? descriptor.kind ?? "task",
+    label: node.label ?? descriptor.label,
+    ...node.description ?? descriptor.description ? { description: node.description ?? descriptor.description } : {},
+    ...node.pluginId ?? descriptor.pluginId ? { pluginId: node.pluginId ?? descriptor.pluginId } : {},
+    ...node.approval ? { approvalLevel: node.approval.approvalLevel, riskLevel: node.approval.riskLevel, toolName: node.approval.toolName, canRequestApproval: true } : { canRequestApproval: descriptor.canRequestApproval ?? true },
+    ...node.retry ? { retryable: node.retry.maxAttempts > 1 } : {},
+    ...node.subflow ? { subgraphId: node.subflow.workflowId, subgraphVersion: node.subflow.version } : {}
+  };
+}
+function edgeVisual(edge) {
+  return {
+    kind: edge.condition ? "conditional" : edge.default ? "system" : "normal",
+    ...edge.label === void 0 ? {} : { label: edge.label },
+    ...edge.condition === void 0 ? {} : { condition: conditionLabel(edge.condition) }
+  };
+}
+function conditionLabel(condition) {
+  if ("all" in condition) return condition.all.map(conditionLabel).join(" AND ");
+  if ("any" in condition) return condition.any.map(conditionLabel).join(" OR ");
+  if ("not" in condition) return `NOT (${conditionLabel(condition.not)})`;
+  return `${condition.path} ${condition.operator}${"value" in condition ? ` ${JSON.stringify(condition.value)}` : ""}`;
+}
+function routeDefinitionEdges(edges, state) {
+  const fallback = edges.find((edge) => edge.default === true || edge.condition === void 0);
+  const match = edges.find((edge) => edge.condition !== void 0 && evaluateWorkflowCondition(edge.condition, state));
+  return (match ?? fallback)?.to ?? (() => {
+    throw new Error(`No workflow edge condition matched from '${state.currentStep}'`);
+  })();
+}
+function valueAtPath(input, path) {
+  let current = input;
+  for (const part of path.split(".")) {
+    if (!isRecord(current) || !Object.prototype.hasOwnProperty.call(current, part)) return { exists: false, value: void 0 };
+    current = current[part];
+  }
+  return { exists: true, value: current };
+}
+function isRecord(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+async function withTimeout(promise, timeoutMs, nodeId) {
+  if (timeoutMs === void 0) return promise;
+  let timer;
+  const timeout = new Promise((_, reject) => {
+    timer = setTimeout(() => reject(new Error(`Workflow node '${nodeId}' timed out after ${timeoutMs}ms`)), timeoutMs);
+  });
+  try {
+    return await Promise.race([promise, timeout]);
+  } finally {
+    if (timer !== void 0) clearTimeout(timer);
+  }
+}
+
+export {
+  compileWorkflowDefinition
+};
+//# sourceMappingURL=chunk-CJ7OFEF7.js.map

package/dist/chunk-CJ7OFEF7.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/agentic/workflow-compiler.ts"],"sourcesContent":["import type { WorkflowCondition, WorkflowDefinition, WorkflowDefinitionEdge, WorkflowDefinitionNode, WorkflowGraphNodeInput } from '@alneas/eaos-core'\nimport { evaluateWorkflowCondition, validateWorkflowDefinition } from '@alneas/eaos-core'\nimport type { BaseCheckpointSaver, RetryPolicy } from '@langchain/langgraph'\nimport { AgentGraphEngine, type AgentGraphEngineOptions, type AgentGraphState, type GraphNodeHandler } from './graph'\nimport { WorkflowNodeCatalog } from './workflow-catalog'\n\n/**\n * Trusted node catalog, checkpoint persistence, and live approval authority for {@link compileWorkflowDefinition}.\n */\nexport interface WorkflowCompilerOptions {\n  /** Required host/plugin node resolver catalog. */\n  catalog: WorkflowNodeCatalog\n  /** Optional LangGraph saver; absent uses the graph engine default, which is not durable host storage. */\n  checkpointer?: BaseCheckpointSaver\n  /** Optional live host approval authorization forwarded to the graph engine. */\n  authorizeResume?: AgentGraphEngineOptions['authorizeResume']\n}\n\n/**\n * Validated definition and configured graph produced by {@link compileWorkflowDefinition}.\n */\nexport interface CompiledWorkflow {\n  /** Validated serializable workflow definition returned by core validation. */\n  definition: WorkflowDefinition\n  /** Newly assembled graph; compilation performs no workflow execution. */\n  graph: AgentGraphEngine\n}\n\n/**\n * Validates a serializable workflow and resolves its catalog nodes into a LangGraph-backed runtime.\n * @param input - Unknown serialized definition accepted by core validateWorkflowDefinition.\n * @param options - Required catalog, optional saver, and live resume authorizer.\n * @returns Validated definition and newly configured graph with node retries, conditional routes, approval metadata, and subgraph mappings.\n * @throws Rejects definition validation, missing catalog/types/subgraph resolvers, invalid resolved handlers/graphs, or propagated resolver/graph construction errors.\n * @remarks Host resolvers may have setup side effects before a later node fails; no rollback/disposal protocol is provided. Node timeouts race the handler but do not cancel underlying work. Tool scopes are passed in workflow context; handlers must enforce them. Runtime conditional routing picks the first matching condition or first default/unconditional edge and throws if none match. Durable persistence, live authorization, and safe side-effect retry contracts remain host-owned.\n * @example\n * ```typescript\n * import { compileWorkflowDefinition, type WorkflowCompilerOptions } from \"@alneas/eaos-server/agentic/workflow-compiler\";\n * export async function compile(input: unknown, options: WorkflowCompilerOptions) {\n *   return compileWorkflowDefinition(input, options);\n * }\n * ```\n */\nexport async function compileWorkflowDefinition(input: unknown, options: WorkflowCompilerOptions): Promise<CompiledWorkflow> {\n  const definition = validateWorkflowDefinition(input)\n  if (!options?.catalog) throw new Error('Workflow node catalog is required')\n  const graph = new AgentGraphEngine({\n    checkpointer: options.checkpointer,\n    authorizeResume: options.authorizeResume,\n    workflowId: definition.workflowId,\n    workflowVersion: definition.version,\n  })\n\n  for (const node of definition.nodes) {\n    const registration = options.catalog.require(node.type)\n    const visual = visualNode(node, registration.descriptor)\n    if (node.subflow) {\n      if (!registration.resolveSubgraph) throw new Error(`Workflow node '${node.id}' declares a subflow but '${node.type}' has no subgraph resolver`)\n      const subgraph = await registration.resolveSubgraph({ definition, node })\n      if (!subgraph || typeof subgraph.invoke !== 'function') throw new Error(`Workflow subflow '${node.id}' did not resolve to a compiled graph`)\n      graph.addSubgraph(node.id, subgraph, {\n        visual,\n        mapInput: state => node.subflow?.inputPath ? valueAtPath(state, node.subflow.inputPath).value : state,\n        mapOutput: (output, state) => ({ context: { ...(state.context ?? {}), [node.subflow?.outputKey ?? `${node.id}.output`]: structuredClone(output) } }),\n      })\n      continue\n    }\n    const handler = await registration.resolve({ definition, node })\n    if (typeof handler !== 'function') throw new Error(`Workflow node '${node.id}' did not resolve to a handler`)\n    graph.addNode(node.id, wrapNode(node, handler), { retryPolicy: retryPolicy(node), visual })\n  }\n\n  graph.setEntryPoint(definition.entryNode)\n  for (const node of definition.nodes) {\n    const outgoing = definition.edges.filter(edge => edge.from === node.id)\n    if (!outgoing.length) continue\n    for (const edge of outgoing) graph.addEdge(edge.from, edge.to, { visual: edgeVisual(edge) })\n    if (outgoing.some(edge => edge.condition !== undefined)) {\n      const destinations = [...new Set(outgoing.map(edge => edge.to))]\n      graph.addConditionalEdges(node.id, state => routeDefinitionEdges(outgoing, state), destinations, {\n        labels: Object.fromEntries(outgoing.map(edge => [edge.to, edge.label ?? (edge.condition ? '条件分岐' : '既定')])),\n        visual: { kind: 'conditional' },\n      })\n    }\n  }\n  return { definition, graph }\n}\n\nfunction wrapNode(node: WorkflowDefinitionNode, handler: GraphNodeHandler): GraphNodeHandler {\n  return async state => {\n    const handlerState = node.toolScope\n      ? { ...structuredClone(state), context: { ...(state.context ?? {}), __eaosWorkflowToolScope: structuredClone(node.toolScope) } }\n      : structuredClone(state)\n    const update = await withTimeout(handler(handlerState), node.timeoutMs, node.id)\n    if (!node.approval) return update\n    const existing = update.pendingApproval\n    const args = existing?.args ?? (node.approval.argsPath ? valueAtPath({ ...state, ...update }, node.approval.argsPath).value : {})\n    if (!isRecord(args)) throw new Error(`Workflow approval node '${node.id}' args must be an object`)\n    return {\n      ...update,\n      pendingApproval: {\n        ...(existing ?? {}),\n        toolName: existing?.toolName ?? node.approval.toolName,\n        approvalLevel: existing?.approvalLevel ?? node.approval.approvalLevel,\n        riskLevel: existing?.riskLevel ?? node.approval.riskLevel,\n        reason: existing?.reason ?? node.approval.reason,\n        args: structuredClone(args),\n        ...(node.approval.permission === undefined ? {} : { permission: existing?.permission ?? node.approval.permission }),\n        ...(node.approval.contractVersion === undefined ? {} : { contractVersion: existing?.contractVersion ?? node.approval.contractVersion }),\n      },\n    }\n  }\n}\n\nfunction retryPolicy(node: WorkflowDefinitionNode): RetryPolicy | undefined {\n  if (!node.retry) return undefined\n  return { maxAttempts: node.retry.maxAttempts, initialInterval: node.retry.backoffMs, maxInterval: node.retry.maxBackoffMs, jitter: node.retry.jitter }\n}\n\nfunction visualNode(node: WorkflowDefinitionNode, descriptor: { label: string; description?: string; pluginId?: string; kind: WorkflowDefinitionNode['kind']; canRequestApproval?: boolean }): WorkflowGraphNodeInput {\n  return {\n    kind: node.kind ?? descriptor.kind ?? 'task',\n    label: node.label ?? descriptor.label,\n    ...(node.description ?? descriptor.description ? { description: node.description ?? descriptor.description } : {}),\n    ...(node.pluginId ?? descriptor.pluginId ? { pluginId: node.pluginId ?? descriptor.pluginId } : {}),\n    ...(node.approval ? { approvalLevel: node.approval.approvalLevel, riskLevel: node.approval.riskLevel, toolName: node.approval.toolName, canRequestApproval: true } : { canRequestApproval: descriptor.canRequestApproval ?? true }),\n    ...(node.retry ? { retryable: node.retry.maxAttempts > 1 } : {}),\n    ...(node.subflow ? { subgraphId: node.subflow.workflowId, subgraphVersion: node.subflow.version } : {}),\n  }\n}\n\nfunction edgeVisual(edge: WorkflowDefinitionEdge) {\n  return {\n    kind: edge.condition ? 'conditional' as const : edge.default ? 'system' as const : 'normal' as const,\n    ...(edge.label === undefined ? {} : { label: edge.label }),\n    ...(edge.condition === undefined ? {} : { condition: conditionLabel(edge.condition) }),\n  }\n}\n\nfunction conditionLabel(condition: WorkflowCondition): string {\n  if ('all' in condition) return condition.all.map(conditionLabel).join(' AND ')\n  if ('any' in condition) return condition.any.map(conditionLabel).join(' OR ')\n  if ('not' in condition) return `NOT (${conditionLabel(condition.not)})`\n  return `${condition.path} ${condition.operator}${'value' in condition ? ` ${JSON.stringify(condition.value)}` : ''}`\n}\n\nfunction routeDefinitionEdges(edges: readonly WorkflowDefinitionEdge[], state: AgentGraphState): string {\n  const fallback = edges.find(edge => edge.default === true || edge.condition === undefined)\n  const match = edges.find(edge => edge.condition !== undefined && evaluateWorkflowCondition(edge.condition, state))\n  return (match ?? fallback)?.to ?? (() => { throw new Error(`No workflow edge condition matched from '${state.currentStep}'`) })()\n}\n\nfunction valueAtPath(input: unknown, path: string): { exists: boolean; value: unknown } {\n  let current: unknown = input\n  for (const part of path.split('.')) {\n    if (!isRecord(current) || !Object.prototype.hasOwnProperty.call(current, part)) return { exists: false, value: undefined }\n    current = current[part]\n  }\n  return { exists: true, value: current }\n}\n\nfunction isRecord(value: unknown): value is Record<string, unknown> {\n  return typeof value === 'object' && value !== null && !Array.isArray(value)\n}\n\nasync function withTimeout<T>(promise: Promise<T>, timeoutMs: number | undefined, nodeId: string): Promise<T> {\n  if (timeoutMs === undefined) return promise\n  let timer: ReturnType<typeof setTimeout> | undefined\n  const timeout = new Promise<never>((_, reject) => { timer = setTimeout(() => reject(new Error(`Workflow node '${nodeId}' timed out after ${timeoutMs}ms`)), timeoutMs) })\n  try { return await Promise.race([promise, timeout]) } finally { if (timer !== undefined) clearTimeout(timer) }\n}\n"],"mappings":"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","names":[]}

package/dist/chunk-EJKWDZIU.js

@@ -0,0 +1,111 @@
+import {
+  ServerWorkflowManager
+} from "./chunk-FD6VC2NA.js";
+
+// src/agentic/workflow-coordinator.ts
+var DurableWorkflowCoordinator = class extends ServerWorkflowManager {
+  store;
+  /**
+   * Captures workflow callbacks and required durable instance store.
+   * @param options - Host store, approval notification, and live resume authorization.
+   * @throws If store is missing.
+   */
+  constructor(options) {
+    super(options);
+    if (!options?.store) throw new Error("Workflow instance store is required");
+    this.store = options.store;
+  }
+  /**
+   * Creates a queued companion instance then runs and persists its graph outcome.
+   * @param graph - Configured graph with appropriate checkpoint persistence.
+   * @param record - Host-admitted instance metadata; instanceId and tenantId must match initialState.
+   * @param initialState - Verified workflow identity and starting state.
+   * @returns Graph state after execution and companion CAS persistence.
+   * @throws Rejects alignment mismatch, existing instance, graph/callback/clone/store failures, or companion revision conflict.
+   * @remarks The queued record can exist even if graph execution later fails; no cross-store rollback occurs. Atomic duplicate prevention belongs to store.create.
+   * @example
+   * ```typescript
+   * import { DurableWorkflowCoordinator } from "@alneas/eaos-server/agentic/workflow-coordinator";
+   * import type { AgentGraphEngine, AgentGraphState } from "@alneas/eaos-server/agentic/graph";
+   * import type { WorkflowInstanceRecord } from "@alneas/eaos-core";
+   * export async function start(coordinator: DurableWorkflowCoordinator, graph: AgentGraphEngine, record: WorkflowInstanceRecord, state: AgentGraphState) { return coordinator.start(graph, record, state); }
+   * ```
+   */
+  async start(graph, record, initialState) {
+    if (record.instanceId !== initialState.sessionId || record.tenantId !== initialState.tenantId) throw new Error("Workflow instance and graph state are not aligned");
+    const existing = await this.store.read(record.tenantId, record.instanceId);
+    if (existing) throw new Error("Workflow instance already exists");
+    await this.store.create(record.tenantId, { id: record.instanceId, revision: 1, value: { ...structuredClone(record), status: "queued" } });
+    return this.runAndPersist(graph, initialState);
+  }
+  /**
+   * Runs an existing graph instance and CAS-updates its companion status.
+   * @param graph - Graph whose session already has a companion record.
+   * @param initialState - Verified state aligned with that record.
+   * @returns Graph result after companion persistence; status prioritizes pending approval, error, completion, then running.
+   * @throws Graph/store/clock failures, missing companion, or changed revision; graph checkpoints may already have advanced.
+   * @example
+   * ```typescript
+   * import { DurableWorkflowCoordinator } from "@alneas/eaos-server/agentic/workflow-coordinator";
+   * import type { AgentGraphEngine, AgentGraphState } from "@alneas/eaos-server/agentic/graph";
+   * export async function run(coordinator: DurableWorkflowCoordinator, graph: AgentGraphEngine, state: AgentGraphState) { return coordinator.runWorkflow(graph, state); }
+   * ```
+   */
+  async runWorkflow(graph, initialState) {
+    return this.runAndPersist(graph, initialState);
+  }
+  /**
+   * Resumes a verified graph approval then persists its resulting companion state.
+   * @param graph - Graph owning the pending checkpoint.
+   * @param payload - Host-authenticated approver decision and optional binding checks.
+   * @returns Resume outcome; companion persistence failure becomes resumed:false error data even when graph resume already succeeded.
+   * @throws Underlying graph/store failures outside normalized resume/persistence handling may reject.
+   * @remarks A false result does not prove no side effects occurred; reconcile graph and companion state before retrying.
+   * @example
+   * ```typescript
+   * import { DurableWorkflowCoordinator } from "@alneas/eaos-server/agentic/workflow-coordinator";
+   * import type { AgentGraphEngine } from "@alneas/eaos-server/agentic/graph";
+   * import type { ServerApprovalCallbackPayload } from "@alneas/eaos-server/agentic/types";
+   * export async function approve(coordinator: DurableWorkflowCoordinator, graph: AgentGraphEngine, payload: ServerApprovalCallbackPayload) { return coordinator.handleApproval(graph, payload); }
+   * ```
+   */
+  async handleApproval(graph, payload) {
+    const result = await super.handleApproval(graph, payload);
+    if (result.resumed && result.state) {
+      try {
+        await this.persist(result.state);
+      } catch (error) {
+        return { resumed: false, error: error instanceof Error ? error.message : "Workflow instance persistence failed" };
+      }
+    }
+    return result;
+  }
+  async runAndPersist(graph, state) {
+    const result = await super.runWorkflow(graph, state);
+    await this.persist(result);
+    return result;
+  }
+  async persist(state) {
+    const current = await this.store.read(state.tenantId, state.sessionId);
+    if (!current) throw new Error(`Workflow instance '${state.sessionId}' not found`);
+    const value = {
+      ...current.value,
+      status: statusForState(state),
+      checkpointRevision: state.checkpointRevision,
+      updatedAt: (/* @__PURE__ */ new Date()).toISOString(),
+      ...state.error ? { error: state.error } : { error: void 0 }
+    };
+    if (!await this.store.replace(state.tenantId, { ...current, revision: current.revision + 1, value }, current.revision)) throw new Error("Workflow instance revision changed");
+  }
+};
+function statusForState(state) {
+  if (state.pendingApproval) return "waiting_approval";
+  if (state.error) return "failed";
+  if (state.isComplete) return "completed";
+  return "running";
+}
+
+export {
+  DurableWorkflowCoordinator
+};
+//# sourceMappingURL=chunk-EJKWDZIU.js.map

package/dist/chunk-EJKWDZIU.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/agentic/workflow-coordinator.ts"],"sourcesContent":["import type { WorkflowInstanceRecord, WorkflowInstanceStatus } from '@alneas/eaos-core'\nimport type { AgentGraphState, AgentGraphEngine } from './graph'\nimport { ServerWorkflowManager, type ServerWorkflowOptions } from './workflow-manager'\nimport type { ServerApprovalCallbackPayload } from './types'\n\n/**\n * Durable business-instance record with host compare-and-swap revision.\n * @see DurableWorkflowCoordinator.\n */\nexport interface StoredWorkflowInstance {\n  /** Workflow instance ID, aligned with graph sessionId. */\n  id: string\n  /** Host CAS revision, starting at one for coordinator-created records. */\n  revision: number\n  /** Domain workflow instance metadata; graph payload remains in its checkpointer. */\n  value: WorkflowInstanceRecord\n}\n\n/** Host-owned durable store for the companion workflow instance record.\n * @see DurableWorkflowCoordinator for usage.\n */\nexport interface WorkflowInstanceStore {\n  /**\n   * Reads an authorized tenant's companion instance.\n   * @param tenantId - Verified owning tenant.\n   * @param instanceId - Workflow session/instance ID.\n   * @returns Stored record, or null if absent.\n   * @throws Persistence failures propagate.\n   \n   * @example\n   * ```typescript\n   * import type { WorkflowInstanceStore } from \"@alneas/eaos-server\";\n   * export async function readTenantInstance(\n   *   store: WorkflowInstanceStore, verifiedTenantId: string, instanceId: string,\n   * ) {\n   *   const record = await store.read(verifiedTenantId, instanceId);\n   *   return record?.value.status; // A missing instance yields undefined here.\n   * }\n   * ```\n   */\n  read(tenantId: string, instanceId: string): Promise<StoredWorkflowInstance | null>\n  /**\n   * Atomically inserts a new companion instance, rejecting duplicates.\n   * @param tenantId - Verified owning tenant.\n   * @param record - Initial revision-one queued record.\n   * @returns No value; resolves when durable creation completes.\n   * @throws Duplicate/conflicting identity or persistence failure must reject.\n   \n   * @example\n   * ```typescript\n   * import type { WorkflowInstanceStore } from \"@alneas/eaos-server\";\n   * export async function createQueuedInstance(\n   *   store: WorkflowInstanceStore, verifiedTenantId: string,\n   *   initialRecord: Parameters<WorkflowInstanceStore[\"create\"]>[1],\n   * ) {\n   *   // Supply an aligned, admitted revision-one queued record.\n   *   await store.create(verifiedTenantId, initialRecord);\n   * }\n   * ```\n   */\n  create(tenantId: string, record: StoredWorkflowInstance): Promise<void>\n  /**\n   * Atomically replaces a companion record only if its revision matches.\n   * @param tenantId - Verified owning tenant.\n   * @param record - Replacement with incremented revision.\n   * @param expectedRevision - Previously read revision required for CAS.\n   * @returns True on replacement, false on stale revision.\n   * @throws Persistence failures propagate.\n   \n   * @example\n   * ```typescript\n   * import type { WorkflowInstanceStore } from \"@alneas/eaos-server\";\n   * export async function replaceTenantInstance(\n   *   store: WorkflowInstanceStore, verifiedTenantId: string,\n   *   nextRecord: Parameters<WorkflowInstanceStore[\"replace\"]>[1], previouslyReadRevision: number,\n   * ) {\n   *   // nextRecord has the incremented revision; false means another writer won.\n   *   return await store.replace(verifiedTenantId, nextRecord, previouslyReadRevision);\n   * }\n   * ```\n   */\n  replace(tenantId: string, record: StoredWorkflowInstance, expectedRevision: number): Promise<boolean>\n}\n\n/**\n * Workflow notification/approval callbacks plus durable companion-instance storage.\n * @see DurableWorkflowCoordinator.\n */\nexport interface DurableWorkflowCoordinatorOptions extends ServerWorkflowOptions {\n  /** Host-authorized tenant-scoped store with atomic create and revision checks. */\n  store: WorkflowInstanceStore\n}\n\n/**\n * Keeps the business workflow instance synchronized with the LangGraph\n * checkpoint without making either one the other's database implementation.\n * @remarks Checkpoint and companion record updates are separate operations; failures can leave them temporarily divergent. The host owns writer serialization, tenant authorization, durable stores, and reconciliation rather than blind retry after partial outcomes.\n * @example\n * ```typescript\n * import { DurableWorkflowCoordinator } from \"@alneas/eaos-server/agentic/workflow-coordinator\";\n * import type { DurableWorkflowCoordinatorOptions } from \"@alneas/eaos-server/agentic/workflow-coordinator\";\n * export function coordinator(options: DurableWorkflowCoordinatorOptions) { return new DurableWorkflowCoordinator(options); }\n * ```\n */\nexport class DurableWorkflowCoordinator extends ServerWorkflowManager {\n  private readonly store: WorkflowInstanceStore\n\n  /**\n   * Captures workflow callbacks and required durable instance store.\n   * @param options - Host store, approval notification, and live resume authorization.\n   * @throws If store is missing.\n   */\n  constructor(options: DurableWorkflowCoordinatorOptions) {\n    super(options)\n    if (!options?.store) throw new Error('Workflow instance store is required')\n    this.store = options.store\n  }\n\n  /**\n   * Creates a queued companion instance then runs and persists its graph outcome.\n   * @param graph - Configured graph with appropriate checkpoint persistence.\n   * @param record - Host-admitted instance metadata; instanceId and tenantId must match initialState.\n   * @param initialState - Verified workflow identity and starting state.\n   * @returns Graph state after execution and companion CAS persistence.\n   * @throws Rejects alignment mismatch, existing instance, graph/callback/clone/store failures, or companion revision conflict.\n   * @remarks The queued record can exist even if graph execution later fails; no cross-store rollback occurs. Atomic duplicate prevention belongs to store.create.\n   * @example\n   * ```typescript\n   * import { DurableWorkflowCoordinator } from \"@alneas/eaos-server/agentic/workflow-coordinator\";\n   * import type { AgentGraphEngine, AgentGraphState } from \"@alneas/eaos-server/agentic/graph\";\n   * import type { WorkflowInstanceRecord } from \"@alneas/eaos-core\";\n   * export async function start(coordinator: DurableWorkflowCoordinator, graph: AgentGraphEngine, record: WorkflowInstanceRecord, state: AgentGraphState) { return coordinator.start(graph, record, state); }\n   * ```\n   */\n  async start(graph: AgentGraphEngine, record: WorkflowInstanceRecord, initialState: AgentGraphState): Promise<AgentGraphState> {\n    if (record.instanceId !== initialState.sessionId || record.tenantId !== initialState.tenantId) throw new Error('Workflow instance and graph state are not aligned')\n    const existing = await this.store.read(record.tenantId, record.instanceId)\n    if (existing) throw new Error('Workflow instance already exists')\n    await this.store.create(record.tenantId, { id: record.instanceId, revision: 1, value: { ...structuredClone(record), status: 'queued' } })\n    return this.runAndPersist(graph, initialState)\n  }\n\n  /**\n   * Runs an existing graph instance and CAS-updates its companion status.\n   * @param graph - Graph whose session already has a companion record.\n   * @param initialState - Verified state aligned with that record.\n   * @returns Graph result after companion persistence; status prioritizes pending approval, error, completion, then running.\n   * @throws Graph/store/clock failures, missing companion, or changed revision; graph checkpoints may already have advanced.\n   * @example\n   * ```typescript\n   * import { DurableWorkflowCoordinator } from \"@alneas/eaos-server/agentic/workflow-coordinator\";\n   * import type { AgentGraphEngine, AgentGraphState } from \"@alneas/eaos-server/agentic/graph\";\n   * export async function run(coordinator: DurableWorkflowCoordinator, graph: AgentGraphEngine, state: AgentGraphState) { return coordinator.runWorkflow(graph, state); }\n   * ```\n   */\n  override async runWorkflow(graph: AgentGraphEngine, initialState: AgentGraphState): Promise<AgentGraphState> {\n    return this.runAndPersist(graph, initialState)\n  }\n\n  /**\n   * Resumes a verified graph approval then persists its resulting companion state.\n   * @param graph - Graph owning the pending checkpoint.\n   * @param payload - Host-authenticated approver decision and optional binding checks.\n   * @returns Resume outcome; companion persistence failure becomes resumed:false error data even when graph resume already succeeded.\n   * @throws Underlying graph/store failures outside normalized resume/persistence handling may reject.\n   * @remarks A false result does not prove no side effects occurred; reconcile graph and companion state before retrying.\n   * @example\n   * ```typescript\n   * import { DurableWorkflowCoordinator } from \"@alneas/eaos-server/agentic/workflow-coordinator\";\n   * import type { AgentGraphEngine } from \"@alneas/eaos-server/agentic/graph\";\n   * import type { ServerApprovalCallbackPayload } from \"@alneas/eaos-server/agentic/types\";\n   * export async function approve(coordinator: DurableWorkflowCoordinator, graph: AgentGraphEngine, payload: ServerApprovalCallbackPayload) { return coordinator.handleApproval(graph, payload); }\n   * ```\n   */\n  override async handleApproval(graph: AgentGraphEngine, payload: ServerApprovalCallbackPayload): Promise<{ \n  /** True only when graph resumption and companion-instance persistence complete; false may also mean companion persistence failed after the graph advanced. */\n  resumed: boolean; \n  /** Optional resumed graph state returned when companion persistence succeeds; omitted when companion persistence is normalized into failure data. */\n  state?: AgentGraphState; \n  /** Optional graph resume or companion persistence failure detail; reconcile both stores before retrying because graph effects may already have completed. */\n  error?: string }> {\n    const result = await super.handleApproval(graph, payload)\n    if (result.resumed && result.state) {\n      try { await this.persist(result.state) } catch (error) { return { resumed: false, error: error instanceof Error ? error.message : 'Workflow instance persistence failed' } }\n    }\n    return result\n  }\n\n  private async runAndPersist(graph: AgentGraphEngine, state: AgentGraphState): Promise<AgentGraphState> {\n    const result = await super.runWorkflow(graph, state)\n    await this.persist(result)\n    return result\n  }\n\n  private async persist(state: AgentGraphState): Promise<void> {\n    const current = await this.store.read(state.tenantId, state.sessionId)\n    if (!current) throw new Error(`Workflow instance '${state.sessionId}' not found`)\n    const value: WorkflowInstanceRecord = {\n      ...current.value,\n      status: statusForState(state),\n      checkpointRevision: state.checkpointRevision,\n      updatedAt: new Date().toISOString(),\n      ...(state.error ? { error: state.error } : { error: undefined }),\n    }\n    if (!await this.store.replace(state.tenantId, { ...current, revision: current.revision + 1, value }, current.revision)) throw new Error('Workflow instance revision changed')\n  }\n}\n\nfunction statusForState(state: AgentGraphState): WorkflowInstanceStatus {\n  if (state.pendingApproval) return 'waiting_approval'\n  if (state.error) return 'failed'\n  if (state.isComplete) return 'completed'\n  return 'running'\n}\n"],"mappings":";;;;;AAwGO,IAAM,6BAAN,cAAyC,sBAAsB;AAAA,EACnD;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAOjB,YAAY,SAA4C;AACtD,UAAM,OAAO;AACb,QAAI,CAAC,SAAS,MAAO,OAAM,IAAI,MAAM,qCAAqC;AAC1E,SAAK,QAAQ,QAAQ;AAAA,EACvB;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAkBA,MAAM,MAAM,OAAyB,QAAgC,cAAyD;AAC5H,QAAI,OAAO,eAAe,aAAa,aAAa,OAAO,aAAa,aAAa,SAAU,OAAM,IAAI,MAAM,mDAAmD;AAClK,UAAM,WAAW,MAAM,KAAK,MAAM,KAAK,OAAO,UAAU,OAAO,UAAU;AACzE,QAAI,SAAU,OAAM,IAAI,MAAM,kCAAkC;AAChE,UAAM,KAAK,MAAM,OAAO,OAAO,UAAU,EAAE,IAAI,OAAO,YAAY,UAAU,GAAG,OAAO,EAAE,GAAG,gBAAgB,MAAM,GAAG,QAAQ,SAAS,EAAE,CAAC;AACxI,WAAO,KAAK,cAAc,OAAO,YAAY;AAAA,EAC/C;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAeA,MAAe,YAAY,OAAyB,cAAyD;AAC3G,WAAO,KAAK,cAAc,OAAO,YAAY;AAAA,EAC/C;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAiBA,MAAe,eAAe,OAAyB,SAMrC;AAChB,UAAM,SAAS,MAAM,MAAM,eAAe,OAAO,OAAO;AACxD,QAAI,OAAO,WAAW,OAAO,OAAO;AAClC,UAAI;AAAE,cAAM,KAAK,QAAQ,OAAO,KAAK;AAAA,MAAE,SAAS,OAAO;AAAE,eAAO,EAAE,SAAS,OAAO,OAAO,iBAAiB,QAAQ,MAAM,UAAU,uCAAuC;AAAA,MAAE;AAAA,IAC7K;AACA,WAAO;AAAA,EACT;AAAA,EAEA,MAAc,cAAc,OAAyB,OAAkD;AACrG,UAAM,SAAS,MAAM,MAAM,YAAY,OAAO,KAAK;AACnD,UAAM,KAAK,QAAQ,MAAM;AACzB,WAAO;AAAA,EACT;AAAA,EAEA,MAAc,QAAQ,OAAuC;AAC3D,UAAM,UAAU,MAAM,KAAK,MAAM,KAAK,MAAM,UAAU,MAAM,SAAS;AACrE,QAAI,CAAC,QAAS,OAAM,IAAI,MAAM,sBAAsB,MAAM,SAAS,aAAa;AAChF,UAAM,QAAgC;AAAA,MACpC,GAAG,QAAQ;AAAA,MACX,QAAQ,eAAe,KAAK;AAAA,MAC5B,oBAAoB,MAAM;AAAA,MAC1B,YAAW,oBAAI,KAAK,GAAE,YAAY;AAAA,MAClC,GAAI,MAAM,QAAQ,EAAE,OAAO,MAAM,MAAM,IAAI,EAAE,OAAO,OAAU;AAAA,IAChE;AACA,QAAI,CAAC,MAAM,KAAK,MAAM,QAAQ,MAAM,UAAU,EAAE,GAAG,SAAS,UAAU,QAAQ,WAAW,GAAG,MAAM,GAAG,QAAQ,QAAQ,EAAG,OAAM,IAAI,MAAM,oCAAoC;AAAA,EAC9K;AACF;AAEA,SAAS,eAAe,OAAgD;AACtE,MAAI,MAAM,gBAAiB,QAAO;AAClC,MAAI,MAAM,MAAO,QAAO;AACxB,MAAI,MAAM,WAAY,QAAO;AAC7B,SAAO;AACT;","names":[]}