@alneas/eaos-server 0.0.0-stage → 0.2.0

package/dist/agentic/local-runner.d.ts

@@ -0,0 +1,106 @@
+import { AgentJobKind, AgentJobRecord } from '@alneas/eaos-core';
+import { AgentJobStore } from './agent-jobs.js';
+import { ServerAgentTaskRequest, ServerAgentTaskResult } from './types.js';
+import './autonomous-worker.js';
+import '@alneas/appkit-core/ai/ai-chat';
+import '../execution/index.js';
+import '@alneas/appkit-core/ai/action';
+import 'hono/types';
+import 'hono';
+import '@alneas/appkit-core/ai';
+import '../plugin-data/index.js';
+import '@alneas/eaos-core/plugin-sdk';
+import '@alneas/eaos-server/lifecycle-engine';
+
+/**
+ * Verified local-runner identity and routes admitted by the host.
+ * @see LocalRunnerPullCoordinator.
+ */
+interface LocalRunnerIdentity {
+    /** Nonblank authenticated runner identifier. */
+    runnerId: string;
+    /** Nonblank authenticated user to whom claimed jobs must belong. */
+    userId: string;
+    /** Nonempty array of nonblank host-authorized route identifiers. */
+    supportedRouteIds: readonly string[];
+}
+/**
+ * Durable queue and completion notification for {@link LocalRunnerPullCoordinator}.
+ */
+interface LocalRunnerPullCoordinatorOptions {
+    /** Host job store enforcing atomic claims and lease ownership. */
+    store: AgentJobStore;
+    /** Clock read once per claim/submit; defaults to a fresh Date. */
+    now?: () => Date;
+    /** Retry delay in milliseconds, finite from 0 to 86400000. @defaultValue 5000 */
+    retryDelayMs?: number;
+    /** Called with cloned job/result only after markCompleted succeeds; rejection propagates after the persisted completion. */
+    onCompleted?: (job: Readonly<AgentJobRecord<ServerAgentTaskRequest>>, result: ServerAgentTaskResult) => Promise<void>;
+}
+/**
+ * Server-side queue boundary for a local CLI/MLX runner.
+ *
+ * The runner authenticates to the host and pulls jobs; the server never needs
+ * the subscription credential. The host must perform authentication and
+ * tenant/user authorization before calling claim or submit.
+ * @example
+ * ```typescript
+ * import { LocalRunnerPullCoordinator, type LocalRunnerPullCoordinatorOptions } from "@alneas/eaos-server/agentic/local-runner";
+ * export function localRunnerQueue(options: LocalRunnerPullCoordinatorOptions) {
+ *   return new LocalRunnerPullCoordinator(options);
+ * }
+ * ```
+ */
+declare class LocalRunnerPullCoordinator {
+    private readonly options;
+    private readonly now;
+    private readonly retryDelayMs;
+    /**
+     * Creates a coordinator retaining the host store and callbacks.
+     * @param options - Queue persistence, clock, retry delay, and optional post-completion callback.
+     * @throws If store is absent or retry delay is outside finite 0–86400000 milliseconds.
+     */
+    constructor(options: LocalRunnerPullCoordinatorOptions);
+    /**
+     * Atomically claims local-pull jobs bound to this verified user, runner, and supported routes.
+     * @param identity - Host-authenticated runner identity; see {@link LocalRunnerIdentity}.
+     * @param limit - Maximum jobs requested, safe integer 1–100; defaults to 1.
+     * @returns Store-claimed jobs with leases, or an empty array when none qualify.
+     * @throws Rejects invalid identity/limit and propagated store/clock failures.
+     * @example
+     * ```typescript
+     * import { LocalRunnerPullCoordinator, type LocalRunnerPullCoordinatorOptions, type LocalRunnerIdentity } from "@alneas/eaos-server/agentic/local-runner";
+     * export async function pull(options: LocalRunnerPullCoordinatorOptions, identity: LocalRunnerIdentity) {
+     *   return new LocalRunnerPullCoordinator(options).claim(identity);
+     * }
+     * ```
+     */
+    claim(identity: LocalRunnerIdentity, limit?: number): Promise<readonly AgentJobRecord<ServerAgentTaskRequest>[]>;
+    /**
+     * Persists a leased local-runner outcome after checking its user, route, and runner bindings.
+     * @param identity - Host-authenticated runner identity.
+     * @param job - Host-loaded leased job; must belong to the same user, local-pull mode, supported route, and optional runner binding.
+     * @param result - Runtime result; COMPLETED marks completion, PENDING_APPROVAL waits, other results retry unless retryable is exactly false.
+     * @returns No value; resolves after the selected store transition and any completion callback.
+     * @throws Rejects invalid binding, store/clock/clone errors, or completion callback errors. Callback failure occurs after completion persistence.
+     * @remarks The host loads the authoritative job and authorizes tenant/user access before calling. Error text is truncated to 1000 characters for retries/failures. Store lease validation is the concurrency boundary; no remote runtime cancellation or automatic retry execution is performed here.
+     * @example
+     * ```typescript
+     * import { LocalRunnerPullCoordinator, type LocalRunnerPullCoordinatorOptions, type LocalRunnerIdentity } from "@alneas/eaos-server/agentic/local-runner";
+     * import type { AgentJobRecord } from "@alneas/eaos-core";
+     * import type { ServerAgentTaskRequest, ServerAgentTaskResult } from "@alneas/eaos-server/agentic/types";
+     * export async function submit(options: LocalRunnerPullCoordinatorOptions, identity: LocalRunnerIdentity, job: AgentJobRecord<ServerAgentTaskRequest>, result: ServerAgentTaskResult) {
+     *   await new LocalRunnerPullCoordinator(options).submit(identity, job, result);
+     * }
+     * ```
+     */
+    submit(identity: LocalRunnerIdentity, job: Readonly<AgentJobRecord<ServerAgentTaskRequest>>, result: ServerAgentTaskResult): Promise<void>;
+}
+/**
+ * Alias of core job kinds accepted by local runner coordination.
+ * @see LocalRunnerPullCoordinator.
+ */
+type LocalRunnerJobKind = AgentJobKind;
+
+export { LocalRunnerPullCoordinator };
+export type { LocalRunnerIdentity, LocalRunnerJobKind, LocalRunnerPullCoordinatorOptions };

package/dist/agentic/local-runner.js

@@ -0,0 +1,7 @@
+import {
+  LocalRunnerPullCoordinator
+} from "../chunk-ZHMTD5KV.js";
+export {
+  LocalRunnerPullCoordinator
+};
+//# sourceMappingURL=local-runner.js.map

package/dist/agentic/local-runner.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}

package/dist/agentic/remote-executor.d.ts

@@ -0,0 +1,67 @@
+import { WorkflowAgentFailureCode } from '@alneas/eaos-core';
+import { ServerAgentTaskRequest, ServerAgentExecutor } from './types.js';
+
+/**
+ * Versioned JSON envelope POSTed by {@link createHttpAgentExecutor}.
+ */
+interface HttpAgentRuntimeRequest {
+    /** Wire protocol version; must be 1.0. */
+    protocolVersion: '1.0';
+    /** Cloned host-admitted task to execute. */
+    task: ServerAgentTaskRequest;
+}
+/**
+ * Runtime reply validated by {@link createHttpAgentExecutor}; failed replies are converted to execution errors.
+ */
+interface HttpAgentRuntimeResponse {
+    /** Wire protocol version; must match 1.0. */
+    protocolVersion: '1.0';
+    /** Must match the submitted task ID. */
+    taskId: string;
+    /** COMPLETED requires string output; FAILED is converted to a rejected execution. */
+    status: 'COMPLETED' | 'FAILED';
+    /** Required string result for COMPLETED replies; ignored on FAILED. */
+    output?: string;
+    /** Optional failure description; a blank/missing value uses a generic message. */
+    error?: string;
+    /** Optional recognized classification; unrecognized values become RUNTIME_FAILED. */
+    failureCode?: WorkflowAgentFailureCode;
+    /** Optional retry advice on failures; otherwise unavailable/timeout/runtime failure default to retryable. */
+    retryable?: boolean;
+}
+/**
+ * Trusted endpoint, credentials, transport, and limits for {@link createHttpAgentExecutor}.
+ */
+interface HttpAgentExecutorOptions {
+    /** Private host or ARM runtime endpoint. Credentials must be host-configured. */
+    url: string;
+    /** Host-configured headers, including any runtime credentials; Content-Type is always application/json. */
+    headers?: Record<string, string>;
+    /** Default timeout in milliseconds, safe integer 1–3600000; task.timeoutMs overrides this. @defaultValue 60000 */
+    timeoutMs?: number;
+    /** Maximum response bytes, safe integer 1–134217728; content length and streaming bytes are checked. @defaultValue 8388608 */
+    maxResponseBytes?: number;
+    /** Host transport implementation; defaults to global fetch. */
+    fetch?: typeof fetch;
+}
+/**
+ * Creates the standard private HTTP boundary from application-worker to an
+ * ARM/remote agent runtime. The runtime returns text only; workflow proposal
+ * parsing and all business side effects stay in EAOS/server/plugin code.
+ * @param options - Trusted endpoint, headers, fetch implementation, and limits.
+ * @returns An executor resolving runtime output text after checking protocolVersion, taskId, status, and output type.
+ * @throws Synchronously for missing/invalid endpoint or limits. Invocations reject with ServerAgentExecutionError for transport, timeout, HTTP status, output size, JSON/contract errors, or reported runtime failure; clone/serialization errors can also reject.
+ * @remarks HTTPS is required except localhost/127.0.0.1/IPv6 loopback HTTP; URL credentials and fragments are rejected. Each task uses one POST with redirects disabled, cookies omitted, and an AbortSignal timeout. No retries or business authorization occur here. Remote side effects may have happened before transport failure; the host must define safe idempotency before retrying. Response readers are released and oversized streams are cancelled.
+ * @example
+ * ```typescript
+ * import { createHttpAgentExecutor, type HttpAgentExecutorOptions } from "@alneas/eaos-server/agentic/remote-executor";
+ * export function remoteExecutor(hostConfiguration: HttpAgentExecutorOptions) {
+ *   // Provision/authenticate the runtime separately and keep its headers server-side.
+ *   return createHttpAgentExecutor(hostConfiguration);
+ * }
+ * ```
+ */
+declare function createHttpAgentExecutor(options: HttpAgentExecutorOptions): ServerAgentExecutor;
+
+export { createHttpAgentExecutor };
+export type { HttpAgentExecutorOptions, HttpAgentRuntimeRequest, HttpAgentRuntimeResponse };

package/dist/agentic/remote-executor.js

@@ -0,0 +1,8 @@
+import {
+  createHttpAgentExecutor
+} from "../chunk-IJWYS2PF.js";
+import "../chunk-YABTQZDJ.js";
+export {
+  createHttpAgentExecutor
+};
+//# sourceMappingURL=remote-executor.js.map

package/dist/agentic/remote-executor.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}

package/dist/agentic/types.d.ts

@@ -0,0 +1,157 @@
+import { AgentJobKind, WorkflowAgentToolMode, AgentRuntimeResourcePolicy, WorkflowAgentFailureCode, ApprovalLevel, RiskLevel } from '@alneas/eaos-core';
+
+/**
+ * Runtime selector used to dispatch server tasks to built-in or host-provided executors.
+ * @see ServerAgentExecutor for the host adapter contract.
+ */
+type ServerAgentWorkerType = 'goose' | 'hermes_agent' | 'litellm' | 'local_cli' | 'local_mlx' | 'external_no_training' | 'custom';
+/**
+ * Selects server-side queue execution or authenticated local runner pull delivery.
+ * @see ServerAgentExecutionContext.
+ */
+type ServerAgentDispatchMode = 'server-queue' | 'local-pull';
+/**
+ * Host-admitted task passed to an agent runtime; tenant/user claims must already be verified.
+ * @see ServerAgentExecutor for a complete adapter example.
+ */
+interface ServerAgentTaskRequest {
+    /** Stable task identifier used for result and checkpoint binding. */
+    id: string;
+    /** Verified tenant ID; never accepted directly as an authenticated request-body claim. */
+    tenantId: string;
+    /** Verified submitting user ID. */
+    userId: string;
+    /** Nonblank task label; ServerAutonomousWorker limits this to 500 characters. */
+    title: string;
+    /** Nonblank runtime instructions; ServerAutonomousWorker limits this to 1000000 characters. */
+    instructions: string;
+    /** Selected built-in or host runtime adapter key. */
+    workerType: ServerAgentWorkerType;
+    /** Why the agent is running; not limited to task-graph workflows. */
+    jobKind?: AgentJobKind;
+    /** Optional domain context; interpretation belongs to the executor. */
+    context?: Record<string, unknown>;
+    /** Host-verified workflow context propagated to the external runtime. */
+    executionContext?: ServerAgentExecutionContext;
+    /** Framework-selected resource policy. Callers cannot loosen this policy. */
+    runtimePolicy?: AgentRuntimeResourcePolicy;
+    /** Optional execution timeout in milliseconds; built-in executors default to 60000 and accept safe integers from 1 to 3600000. */
+    timeoutMs?: number;
+}
+/**
+ * Host-selected workflow, correlation, tool scope, and local-runner bindings sent to the runtime.
+ * @see ServerAgentTaskRequest.
+ */
+interface ServerAgentExecutionContext {
+    /** Optional workflow/session association. */
+    workflowId?: string;
+    /** Optional host tracing identifier. */
+    correlationId?: string;
+    /** Optional host deduplication key; propagation alone does not enforce idempotency. */
+    idempotencyKey?: string;
+    /** Optional workflow tool-execution mode admitted by the host. */
+    toolMode?: WorkflowAgentToolMode;
+    /** Optional allowlisted tool names; runtime adapters must enforce the intended boundary. */
+    allowedToolNames?: readonly string[];
+    /** Selected by the server broker; clients cannot override it. */
+    routeId?: string;
+    /** Optional delivery mode; local-pull jobs are claimed by authenticated local runners. */
+    dispatchMode?: ServerAgentDispatchMode;
+    /** User/runner binding for local subscription or MLX execution. */
+    runnerId?: string;
+}
+/**
+ * Normalized runtime outcome; FAILED and PENDING_APPROVAL are returned data rather than successful output.
+ * @see ServerAgentExecutor.
+ */
+interface ServerAgentTaskResult {
+    /** Task identifier to which this result belongs. */
+    taskId: string;
+    /** COMPLETED has runtime output; PENDING_APPROVAL awaits a host decision; FAILED records a rejected or failed run. */
+    status: 'COMPLETED' | 'PENDING_APPROVAL' | 'FAILED';
+    /** Runtime text when available; omitted on failures and pending approval. */
+    output?: string;
+    /** Optional failure message for FAILED results. */
+    error?: string;
+    /** Stable failure classification for durable retry/circuit-breaker handling. */
+    failureCode?: WorkflowAgentFailureCode;
+    /** Optional retry advice; absence leaves retry policy to the caller. */
+    retryable?: boolean;
+    /** Optional generated approval binding for PENDING_APPROVAL. */
+    approvalTicketId?: string;
+    /** Optional human-approval level returned by the gatekeeper. */
+    approvalLevel?: ApprovalLevel;
+    /** Optional risk classification returned by the gatekeeper. */
+    riskLevel?: RiskLevel;
+    /** Elapsed wall-clock milliseconds for this attempt. */
+    durationMs: number;
+}
+/**
+ * Carries stable failure classification and retry advice from runtime adapters to queue coordination.
+ * @example
+ * ```typescript
+ * import { ServerAgentExecutionError } from "@alneas/eaos-server/agentic/types";
+ * const error = new ServerAgentExecutionError("Runtime unavailable", "AGENT_UNAVAILABLE", true);
+ * console.log(error.failureCode, error.retryable);
+ * ```
+ */
+declare class ServerAgentExecutionError extends Error {
+    /** Classification used by runner normalization and durable retry handling. */
+    readonly failureCode: WorkflowAgentFailureCode;
+    /** Host retry advice; true does not itself retry or make execution idempotent. */
+    readonly retryable: boolean;
+    /**
+     * Creates a runtime failure retaining an optional underlying cause.
+     * @param message - Human-readable failure description.
+     * @param failureCode - Stable classification for caller retry policy.
+     * @param retryable - Whether the caller may consider retrying this failure.
+     * @param options - Optional cause; omission does not attach an error cause.
+     */
+    constructor(message: string, failureCode: WorkflowAgentFailureCode, retryable: boolean, options?: {
+        /**
+         * Optional underlying error attached through the standard Error cause option; omission leaves the cause unset.
+         */
+        cause?: unknown;
+    });
+}
+/**
+ * Host- or plugin-owned agent execution adapter.
+ *
+ * The server owns admission, authorization and result normalization; the
+ * adapter owns the configured runtime (OpenCode, Codex, Goose, LiteLLM, etc.).
+ * @param request - Verified task and execution context; adapters must enforce host runtime/tool boundaries.
+ * @returns Runtime text output, which is not permission to perform business side effects.
+ * @throws Reject for unavailable, failed, timed-out, or invalid runtime work; ServerAgentExecutionError preserves classification and retry advice.
+ * @example
+ * ```typescript
+ * import type { ServerAgentExecutor } from "@alneas/eaos-server/agentic/types";
+ * export function instrument(execute: ServerAgentExecutor): ServerAgentExecutor {
+ *   return async request => execute(structuredClone(request));
+ * }
+ * ```
+ */
+type ServerAgentExecutor = (request: ServerAgentTaskRequest) => Promise<string>;
+/**
+ * Host-verified approval decision submitted against a pending task checkpoint.
+ * @remarks The host authenticates the approver and verifies role authority before passing this payload to a coordinator.
+ * @see ServerAgentTaskResult.
+ */
+interface ServerApprovalCallbackPayload {
+    /** Task checkpoint identifier whose approval is being decided. */
+    taskId: string;
+    /** Optional external ticket binding; when supplied it must match the checkpoint. */
+    approvalId?: string;
+    /** Optional binding hash for clients that persist the approval payload. */
+    bindingHash?: string;
+    /** True to approve; false to reject the pending work. */
+    approved: boolean;
+    /** Authenticated host approver identifier. */
+    approverId: string;
+    /** Verified role used for approval authorization. */
+    approverRole: string;
+    /** Optional human decision note. */
+    comment?: string;
+}
+
+export { ServerAgentExecutionError };
+export type { ServerAgentDispatchMode, ServerAgentExecutionContext, ServerAgentExecutor, ServerAgentTaskRequest, ServerAgentTaskResult, ServerAgentWorkerType, ServerApprovalCallbackPayload };

package/dist/agentic/types.js

@@ -0,0 +1,7 @@
+import {
+  ServerAgentExecutionError
+} from "../chunk-YABTQZDJ.js";
+export {
+  ServerAgentExecutionError
+};
+//# sourceMappingURL=types.js.map

package/dist/agentic/types.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}

package/dist/agentic/workflow-catalog.d.ts

@@ -0,0 +1,152 @@
+import { WorkflowDefinitionNodeKind, WorkflowToolScopeDefinition, WorkflowDefinition, WorkflowDefinitionNode } from '@alneas/eaos-core';
+import { AgentGraphState, GraphNodeHandler, GraphSubgraph } from './graph.js';
+import '@langchain/langgraph';
+
+/**
+ * Serializable node metadata exposed to workflow editors by {@link WorkflowNodeCatalog}.
+ */
+interface WorkflowNodeDescriptor {
+    /** Unique lowercase catalog type identifier, at most 128 characters. */
+    type: string;
+    /** Editor label, trimmed and required during registration. */
+    label: string;
+    /** Optional human-readable editor description. */
+    description?: string;
+    /** Optional owning plugin ID included in visual metadata. */
+    pluginId?: string;
+    /** Workflow node category used unless a definition overrides it. */
+    kind: WorkflowDefinitionNodeKind;
+    /** Optional declared tool-scope metadata; execution enforcement belongs to the host handler. */
+    toolScope?: WorkflowToolScopeDefinition;
+    /** Optional visual capability flag; compilation defaults to true when no node approval is declared. */
+    canRequestApproval?: boolean;
+}
+/**
+ * Definition and node context supplied when compiling a registered workflow node.
+ * @see WorkflowNodeRegistration.
+ */
+interface WorkflowNodeResolverInput {
+    /** Validated serializable workflow definition being compiled. */
+    definition: WorkflowDefinition;
+    /** Specific definition node being resolved. */
+    node: WorkflowDefinitionNode;
+    /** Optional runtime state for host-specific resolution; the standard compiler omits it. */
+    state?: AgentGraphState;
+}
+/**
+ * Trusted host/plugin handler and optional subgraph resolution for one catalog node type.
+ * @see WorkflowNodeCatalog.register.
+ */
+interface WorkflowNodeRegistration {
+    /** Serializable editor metadata cloned at registration. */
+    descriptor: WorkflowNodeDescriptor;
+    /**
+   * Resolves a plugin/host handler while preserving the Effect/Receipt boundary.
+   * @param input - Validated definition and node being compiled.
+   * @returns A graph handler, synchronously or asynchronously; the compiler rejects nonfunctions.
+   * @throws Resolver failures reject compilation.
+   
+     * @example
+     * ```typescript
+     * import type { WorkflowNodeRegistration } from "@alneas/eaos-server";
+     * export async function resolveHostNode(
+     *   registration: WorkflowNodeRegistration,
+     *   validatedInput: Parameters<WorkflowNodeRegistration["resolve"]>[0],
+     * ) {
+     *   const handler = await registration.resolve(validatedInput);
+     *   return handler; // Resolving a handler does not execute its effects.
+     * }
+     * ```
+     */
+    resolve(input: WorkflowNodeResolverInput): GraphNodeHandler | Promise<GraphNodeHandler>;
+    /**
+   * Resolves a compiled LangGraph subgraph for a definition declaring subflow.
+   * @param input - Validated definition and subflow node.
+   * @returns A graph exposing invoke, synchronously or asynchronously.
+   * @throws Resolver failures reject compilation.
+   
+     * @example
+     * ```typescript
+     * import type { WorkflowNodeRegistration } from "@alneas/eaos-server";
+     * export async function resolveHostSubflow(
+     *   registration: WorkflowNodeRegistration,
+     *   validatedInput: Parameters<NonNullable<WorkflowNodeRegistration["resolveSubgraph"]>>[0],
+     * ) {
+     *   if (!registration.resolveSubgraph) throw new Error("This node has no subgraph resolver");
+     *   return await registration.resolveSubgraph(validatedInput);
+     * }
+     * ```
+     */
+    resolveSubgraph?(input: WorkflowNodeResolverInput): GraphSubgraph | Promise<GraphSubgraph>;
+}
+/**
+ * Registers trusted host/plugin node resolvers and cloned descriptors for workflow compilation and editors.
+ * @remarks Storage is process-local; no persistence or authorization is supplied.
+ * @example
+ * ```typescript
+ * import { WorkflowNodeCatalog } from "@alneas/eaos-server/agentic/workflow-catalog";
+ * const catalog = new WorkflowNodeCatalog();
+ * const unregister = catalog.register({ descriptor: { type: "example.task", label: "Example", kind: "task" }, resolve: () => async () => ({}) });
+ * console.log(catalog.list().length); // 1
+ * unregister();
+ * ```
+ */
+declare class WorkflowNodeCatalog {
+    private readonly registrations;
+    /**
+     * Registers a unique node type and returns a safe unregister callback.
+     * @param registration - Descriptor with nonblank label and type matching lowercase letters/digits/dot/underscore/hyphen up to 128 characters, plus a handler resolver.
+     * @returns A no-argument callback returning no value; it removes only this registration and does not remove a later replacement.
+     * @throws Invalid type/label, duplicate type, missing resolver, or descriptor clone failure.
+     * @remarks The descriptor is cloned and its label trimmed; resolver function references are retained.
+     * @example
+     * ```typescript
+     * import { WorkflowNodeCatalog } from "@alneas/eaos-server/agentic/workflow-catalog";
+     * const catalog = new WorkflowNodeCatalog();
+     * const dispose = catalog.register({ descriptor: { type: "example.task", label: "Example", kind: "task" }, resolve: () => async () => ({}) });
+     * dispose();
+     * ```
+     */
+    register(registration: WorkflowNodeRegistration): () => void;
+    /**
+     * Reads a registered resolver by exact node type.
+     * @param type - Case-sensitive catalog type identifier.
+     * @returns The retained registration, or undefined; mutation is not isolated by cloning.
+     * @example
+     * ```typescript
+     * import { WorkflowNodeCatalog } from "@alneas/eaos-server/agentic/workflow-catalog";
+     * console.log(new WorkflowNodeCatalog().get("example.task")); // undefined
+     * ```
+     */
+    get(type: string): WorkflowNodeRegistration | undefined;
+    /**
+     * Reads a registered resolver or fails if the type is unavailable.
+     * @param type - Exact catalog node type required by a workflow definition.
+     * @returns The retained registration.
+     * @throws If no registration exists for type.
+     * @example
+     * ```typescript
+     * import { WorkflowNodeCatalog, type WorkflowNodeRegistration } from "@alneas/eaos-server/agentic/workflow-catalog";
+     * export function registered(registration: WorkflowNodeRegistration) {
+     *   const catalog = new WorkflowNodeCatalog();
+     *   catalog.register(registration);
+     *   return catalog.require(registration.descriptor.type);
+     * }
+     * ```
+     */
+    require(type: string): WorkflowNodeRegistration;
+    /**
+     * Lists cloned descriptors in registration insertion order.
+     * @returns A new descriptor array, empty for an empty catalog; caller changes do not affect stored descriptors.
+     * @throws If descriptors were externally mutated to contain uncloneable values.
+     * @example
+     * ```typescript
+     * import { WorkflowNodeCatalog } from "@alneas/eaos-server/agentic/workflow-catalog";
+     * console.log(new WorkflowNodeCatalog().list()); // []
+     * ```
+     */
+    list(): readonly WorkflowNodeDescriptor[];
+}
+
+export { WorkflowNodeCatalog };
+export type { WorkflowNodeDescriptor, WorkflowNodeRegistration, WorkflowNodeResolverInput };

package/dist/agentic/workflow-catalog.js

@@ -0,0 +1,7 @@
+import {
+  WorkflowNodeCatalog
+} from "../chunk-7AHSS7SO.js";
+export {
+  WorkflowNodeCatalog
+};
+//# sourceMappingURL=workflow-catalog.js.map

package/dist/agentic/workflow-catalog.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}

package/dist/agentic/workflow-compiler.d.ts

@@ -0,0 +1,44 @@
+import { WorkflowDefinition } from '@alneas/eaos-core';
+import { BaseCheckpointSaver } from '@langchain/langgraph';
+import { AgentGraphEngine, AgentGraphEngineOptions } from './graph.js';
+import { WorkflowNodeCatalog } from './workflow-catalog.js';
+
+/**
+ * Trusted node catalog, checkpoint persistence, and live approval authority for {@link compileWorkflowDefinition}.
+ */
+interface WorkflowCompilerOptions {
+    /** Required host/plugin node resolver catalog. */
+    catalog: WorkflowNodeCatalog;
+    /** Optional LangGraph saver; absent uses the graph engine default, which is not durable host storage. */
+    checkpointer?: BaseCheckpointSaver;
+    /** Optional live host approval authorization forwarded to the graph engine. */
+    authorizeResume?: AgentGraphEngineOptions['authorizeResume'];
+}
+/**
+ * Validated definition and configured graph produced by {@link compileWorkflowDefinition}.
+ */
+interface CompiledWorkflow {
+    /** Validated serializable workflow definition returned by core validation. */
+    definition: WorkflowDefinition;
+    /** Newly assembled graph; compilation performs no workflow execution. */
+    graph: AgentGraphEngine;
+}
+/**
+ * Validates a serializable workflow and resolves its catalog nodes into a LangGraph-backed runtime.
+ * @param input - Unknown serialized definition accepted by core validateWorkflowDefinition.
+ * @param options - Required catalog, optional saver, and live resume authorizer.
+ * @returns Validated definition and newly configured graph with node retries, conditional routes, approval metadata, and subgraph mappings.
+ * @throws Rejects definition validation, missing catalog/types/subgraph resolvers, invalid resolved handlers/graphs, or propagated resolver/graph construction errors.
+ * @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.
+ * @example
+ * ```typescript
+ * import { compileWorkflowDefinition, type WorkflowCompilerOptions } from "@alneas/eaos-server/agentic/workflow-compiler";
+ * export async function compile(input: unknown, options: WorkflowCompilerOptions) {
+ *   return compileWorkflowDefinition(input, options);
+ * }
+ * ```
+ */
+declare function compileWorkflowDefinition(input: unknown, options: WorkflowCompilerOptions): Promise<CompiledWorkflow>;
+
+export { compileWorkflowDefinition };
+export type { CompiledWorkflow, WorkflowCompilerOptions };

package/dist/agentic/workflow-compiler.js

@@ -0,0 +1,8 @@
+import {
+  compileWorkflowDefinition
+} from "../chunk-CJ7OFEF7.js";
+import "../chunk-HXFVOR7Z.js";
+export {
+  compileWorkflowDefinition
+};
+//# sourceMappingURL=workflow-compiler.js.map

package/dist/agentic/workflow-compiler.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}