@alneas/eaos-server 0.0.0-stage → 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,21 @@
+# @alneas/eaos-server
+
+## 0.1.0
+
+### Added
+
+- Allow unrestricted, unmetered Public entitlement rules to skip an external paid entitlement runtime. Authentication and host lifecycle/resource admission remain mandatory.
+
+### Changed
+
+- Adopt public `@alneas/appkit-core@0.2.0`, require Node.js 24 or later, and consume `@alneas/eaos-core@^0.1.0`.
+- Use the portable storage download contract: downloads return `Uint8Array` or `null`. Decode text with `TextDecoder`; Node hosts can explicitly wrap bytes with `Buffer`.
+- Ship English guides, source-derived API references, complete installation requirements and package history.
+
+### Fixed
+
+- Read current tenant contracts inside the quota reservation's existing transaction instead of nesting a control database transaction.
+
+### Upgrade
+
+- Install the exact Appkit Core 0.2.0 peer, upgrade Node.js to 24 or later, and update adapters expecting a Buffer-only download result.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 EAOS contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.ja.md

@@ -0,0 +1,39 @@
+# eaos-server
+
+## 概要
+
+EAOSを組み込む開発者向けに、所有する公開機能と型付きの利用入口を提供します。
+
+## 目的と利点
+
+共通の実装を再利用し、業務機能とホストの接続・認可を分離します。実装の正本は公開Monorepoにあり、本番の設定や運用証拠は含めません。コードの導入、スキーマ適用、組織への有効化は別操作です。
+
+## 主な機能
+
+- 公開パッケージの型付きAPI
+- 明示的なホスト接続と現在の認可
+- パッケージ単位の検証と配布
+
+## クイックスタート
+
+registryからの導入には公開済みの版が必要です。公開前はworkspaceが作成・検証したSHA固定tarballを使用してください。パッケージのsubpath自体をbun addの引数にはしません。
+
+Node.js 24以上が必要です。Appkit Core 0.2.0の必須peerを一緒に導入します。実行ホストが認証・認可・接続を設定してください。
+
+```bash
+bun add @alneas/eaos-server @alneas/appkit-core@0.2.0
+```
+
+```typescript
+import { canonical } from '@alneas/eaos-server/lifecycle-engine'
+
+console.log(canonical({ format: 1, operation: 'inspect' }))
+```
+
+## 次の手順
+
+- [Architecture and boundaries](docs/guide.md)
+- [API reference](docs/api.md)
+- [EAOS composition](https://tech-docs.alneas.com/eaos-workspace/architecture/)
+
+- [変更履歴](https://github.com/dataarthub/eaos/blob/main/packages/server/CHANGELOG.md)

package/README.md

@@ -1,3 +1,41 @@
-# Temporary Holding Version
+# Server execution and persistence
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+## Elevator Pitch
+
+Host developers use Server to compose HTTP/MCP, lifecycle and durable data services.
+
+## Why & Value
+
+Shared implementations keep authorization, CAS, audit and Outbox consistent. The host retains provider connections, current identity and deployment policy. This MIT package owns its implementation and declarations in the public monorepo.
+
+## Key Highlights
+
+- Hono and MCP integration
+- Reviewed lifecycle plans
+- Durable CAS and audit
+- Scoped database and storage
+
+## Quickstart
+
+Registry installation requires a published release. During pre-publication development, install the checksum-pinned tarballs produced by the workspace build instead of assuming these names exist in a registry.
+
+### Public import
+
+Use Node.js 24 or later and the required Appkit Core 0.2.0 peer. The canonicalization example is pure and needs no database connection or credentials. Server execution later requires host-owned identity, authorization and persistence bindings. The subpath is an import target, not a separately installed package.
+
+```bash
+bun add @alneas/eaos-server @alneas/appkit-core@0.2.0
+```
+
+```typescript
+import { canonical } from '@alneas/eaos-server/lifecycle-engine'
+
+console.log(canonical({ format: 1, operation: 'inspect' }))
+```
+
+## Next Steps
+
+- [Change history](https://github.com/dataarthub/eaos/blob/main/packages/server/CHANGELOG.md)
+- [Architecture and boundaries](docs/guide.md)
+- [API reference](docs/api.md)
+- [EAOS composition](https://tech-docs.alneas.com/eaos-workspace/architecture/)

package/dist/agentic/agent-jobs.d.ts

@@ -0,0 +1,329 @@
+import { AgentJobRecord } from '@alneas/eaos-core';
+import { ServerAgentDispatchMode, ServerAgentTaskRequest, ServerAgentTaskResult } from './types.js';
+import { ServerAutonomousWorker } from './autonomous-worker.js';
+import { AtomicRepository, PluginPrincipal, AtomicSession } from '../plugin-data/index.js';
+import 'hono/types';
+import '@alneas/eaos-core/plugin-sdk';
+import 'hono';
+import '@alneas/eaos-server/lifecycle-engine';
+
+/**
+ * Host durable queue boundary with atomic claims and lease-checked transitions.
+ * @see createAtomicAgentJobStore for the canonical implementation.
+ */
+interface AgentJobStore {
+    /**
+     * Claims due/recoverable jobs using durable transaction/lease exclusion.
+     * @param now - Claim clock used for due and stale checks.
+     * @param limit - Maximum job count, validated by the implementation.
+     * @param filter - Optional dispatch/user/runner/route eligibility.
+     * @returns Leased jobs, or an empty array.
+     * @throws Queue persistence or admission failures propagate.
+     
+     * @example
+     * ```typescript
+     * import type { AgentJobStore } from "@alneas/eaos-server";
+     * export async function claimHostJobs(
+     *   store: AgentJobStore, eligibility: Parameters<AgentJobStore["claim"]>[2],
+     * ) {
+     *   // Supply a store already scoped to verified tenant admission.
+     *   return await store.claim(new Date(), 10, eligibility);
+     * }
+     * ```
+     */
+    claim(now: Date, limit: number, filter?: AgentJobClaimFilter): Promise<readonly AgentJobRecord<ServerAgentTaskRequest>[]>;
+    /**
+     * Transitions the leased job to succeeded and persists its result.
+     * @param jobId - Stored job ID.
+     * @param leaseToken - Current claim token; stale tokens must be rejected.
+     * @param result - Normalized task outcome to persist.
+     * @param now - Transition clock; the atomic implementation uses its configured clock instead.
+     * @returns No value; resolves after the durable transition.
+     * @throws Lease/integrity/admission or persistence failures propagate.
+     
+     * @example
+     * ```typescript
+     * import type { AgentJobStore } from "@alneas/eaos-server";
+     * export async function completeClaimedJob(
+     *   store: AgentJobStore, jobId: string, currentLeaseToken: string,
+     *   verifiedResult: Parameters<AgentJobStore["markCompleted"]>[2],
+     * ) {
+     *   await store.markCompleted(jobId, currentLeaseToken, verifiedResult, new Date());
+     *   // Completion is durable under the host store contract; stale leases reject.
+     * }
+     * ```
+     */
+    markCompleted(jobId: string, leaseToken: string, result: ServerAgentTaskResult, now: Date): Promise<void>;
+    /**
+     * Transitions the leased job to waiting_approval and persists approval result data.
+     * @param jobId - Stored job ID.
+     * @param leaseToken - Current claim token; stale tokens must be rejected.
+     * @param result - Normalized task outcome to persist.
+     * @param now - Transition clock; the atomic implementation uses its configured clock instead.
+     * @returns No value; resolves after the durable transition.
+     * @throws Lease/integrity/admission or persistence failures propagate.
+     
+     * @example
+     * ```typescript
+     * import type { AgentJobStore } from "@alneas/eaos-server";
+     * export async function deferClaimedJobForReview(
+     *   store: AgentJobStore, jobId: string, currentLeaseToken: string,
+     *   approvalResult: Parameters<AgentJobStore["markWaitingApproval"]>[2],
+     * ) {
+     *   await store.markWaitingApproval(jobId, currentLeaseToken, approvalResult, new Date());
+     *   // This records pending review; it does not approve or execute the proposed action.
+     * }
+     * ```
+     */
+    markWaitingApproval(jobId: string, leaseToken: string, result: ServerAgentTaskResult, now: Date): Promise<void>;
+    /**
+     * Releases the lease and schedules the job for a later attempt.
+     * @param jobId - Stored job ID.
+     * @param leaseToken - Current claim token; stale tokens must be rejected.
+     * @param error - Persisted failure description.
+     * @param failureCode - Optional stable runtime classification.
+     * @param retryAt - Earliest eligible next-claim timestamp.
+     * @param now - Transition clock; the atomic implementation uses its configured clock instead.
+     * @returns No value; resolves after the durable transition.
+     * @throws Lease/integrity/admission or persistence failures propagate.
+     
+     * @example
+     * ```typescript
+     * import type { AgentJobStore } from "@alneas/eaos-server";
+     * export async function rescheduleClaimedJob(
+     *   store: AgentJobStore, jobId: string, currentLeaseToken: string,
+     *   sanitizedError: string, failureCode: string | undefined, reviewedRetryAt: Date,
+     * ) {
+     *   // Reconcile any uncertain external effect before deciding a retry is safe.
+     *   await store.markRetryable(
+     *     jobId, currentLeaseToken, sanitizedError, failureCode, reviewedRetryAt, new Date(),
+     *   );
+     * }
+     * ```
+     */
+    markRetryable(jobId: string, leaseToken: string, error: string, failureCode: string | undefined, retryAt: Date, now: Date): Promise<void>;
+    /**
+     * Releases the lease and marks a terminal failed result.
+     * @param jobId - Stored job ID.
+     * @param leaseToken - Current claim token; stale tokens must be rejected.
+     * @param error - Persisted failure description.
+     * @param failureCode - Optional stable runtime classification.
+     * @param now - Transition clock; the atomic implementation uses its configured clock instead.
+     * @returns No value; resolves after the durable transition.
+     * @throws Lease/integrity/admission or persistence failures propagate.
+     
+     * @example
+     * ```typescript
+     * import type { AgentJobStore } from "@alneas/eaos-server";
+     * export async function failClaimedJob(
+     *   store: AgentJobStore, jobId: string, currentLeaseToken: string,
+     *   sanitizedError: string, failureCode: string | undefined,
+     * ) {
+     *   await store.markFailed(jobId, currentLeaseToken, sanitizedError, failureCode, new Date());
+     *   // The host persisted terminal failure; no automatic retry is requested.
+     * }
+     * ```
+     */
+    markFailed(jobId: string, leaseToken: string, error: string, failureCode: string | undefined, now: Date): Promise<void>;
+}
+/**
+ * Optional eligibility constraints for durable queue claims; omitted fields impose no restriction.
+ * @see AgentJobStore.claim.
+ */
+interface AgentJobClaimFilter {
+    /** Delivery mode; legacy jobs without a mode are treated as server-queue by the atomic implementation. */
+    dispatchMode?: ServerAgentDispatchMode;
+    /** Eligible registered route IDs; jobs without a matching route are excluded. */
+    routeIds?: readonly string[];
+    /** Verified runner ID; jobs with a different explicit runner binding are excluded, unbound jobs remain eligible. */
+    runnerId?: string;
+    /** Verified owning user ID to require. */
+    userId?: string;
+}
+/**
+ * Host queue/worker and one-pass retry policy for {@link DurableAgentJobDispatcher}.
+ */
+interface AgentJobDispatcherOptions {
+    /** Durable queue enforcing claim leases and tenant admission. */
+    store: AgentJobStore;
+    /** Worker executing each cloned claimed task. */
+    worker: ServerAutonomousWorker;
+    /** Jobs requested per pass, safe integer 1–100; defaults to 1. */
+    batchSize?: number;
+    /** Dispatcher attempt ceiling, safe integer 1–100; defaults to 5 and is combined with each job ceiling. */
+    maxAttempts?: number;
+    /** Finite nonnegative initial exponential retry delay in milliseconds; defaults to 1000. */
+    baseDelayMs?: number;
+    /** Finite retry delay ceiling at least baseDelayMs; defaults to 60000 milliseconds. */
+    maxDelayMs?: number;
+    /** Clock for claims, transitions, and retry availability; defaults to fresh Date. */
+    now?: () => Date;
+    /** Resume a LangGraph thread or publish a domain event after a successful agent result. */
+    onCompleted?: (job: Readonly<AgentJobRecord<ServerAgentTaskRequest>>, result: ServerAgentTaskResult) => Promise<void>;
+}
+/**
+ * Counts of one dispatcher pass; jobs missing lease tokens increment failed without a store transition.
+ * @see DurableAgentJobDispatcher.runOnce.
+ */
+interface AgentJobDispatchResult {
+    /** Number of rows returned by the claim. */
+    claimed: number;
+    /** Jobs whose completion callback and completed transition succeeded. */
+    succeeded: number;
+    /** Jobs transitioned to waiting_approval. */
+    waitingApproval: number;
+    /** Jobs scheduled for a later retry. */
+    retried: number;
+    /** Jobs marked terminal failure plus claimed jobs missing a lease token. */
+    failed: number;
+}
+/**
+ * Durable boundary between Micro 2 and an ARM agent runtime.
+ *
+ * The store is host-owned and must persist leases, attempts and results. This
+ * class owns only one bounded pass; a host scheduler calls runOnce again.
+ * @remarks Jobs execute sequentially within each pass, but concurrent runOnce calls are not serialized here. Leases and admission must be enforced by the host store. Completion callbacks run before markCompleted and can be repeated after retry; make external effects idempotent.
+ * @example
+ * ```typescript
+ * import { DurableAgentJobDispatcher, type AgentJobDispatcherOptions } from "@alneas/eaos-server/agentic/agent-jobs";
+ * export async function dispatch(options: AgentJobDispatcherOptions) {
+ *   return new DurableAgentJobDispatcher(options).runOnce();
+ * }
+ * ```
+ */
+declare class DurableAgentJobDispatcher {
+    private readonly options;
+    /**
+     * Validates one-pass claim and exponential retry settings.
+     * @param options - Store/worker plus bounded batch, attempt, delay, clock, and completion settings.
+     * @throws Missing store/worker, batchSize/maxAttempts outside safe integer 1–100, or nonfinite/negative/inverted retry delays.
+     */
+    constructor(options: AgentJobDispatcherOptions);
+    /**
+     * Claims one batch and executes jobs sequentially, persisting completion, approval wait, retry, or failure.
+     * @returns Per-outcome counts after all claimed jobs have been processed.
+     * @throws Rejects claim/transition/clock failures; worker errors become retryable failure results. Completion callback/markCompleted errors trigger retry-or-fail handling.
+     * @remarks Retry delay is min(maxDelayMs, baseDelayMs * 2^(attempt-1)), using job.attempt + 1 for the attempt calculation. No timer or automatic second pass is installed. Results marked PENDING_APPROVAL do not count as success.
+     * @example
+     * ```typescript
+     * import { DurableAgentJobDispatcher, type AgentJobDispatcherOptions } from "@alneas/eaos-server/agentic/agent-jobs";
+     * export async function runOnce(options: AgentJobDispatcherOptions) { return new DurableAgentJobDispatcher(options).runOnce(); }
+     * ```
+     */
+    runOnce(): Promise<AgentJobDispatchResult>;
+    private retryOrFail;
+}
+/**
+ * Creates a cloned, hashed queued job record without persisting or executing it.
+ * @param input - request supplies verified task identity; kind groups idempotency; workflowInstanceId is optional; correlationId defaults to request executionContext correlation then request.id; idempotencyKey defaults to executionContext key then request.id; maxAttempts defaults to 5; now defaults to the current Date.
+ * @returns A new queued record with generated jobId, attempt zero, request hash, and matching available/created/updated timestamps.
+ * @throws Clone/hash/invalid Date failures; this factory does not independently validate every task or attempt field.
+ * @example
+ * ```typescript
+ * import { createAgentJob } from "@alneas/eaos-server/agentic/agent-jobs";
+ * import type { ServerAgentTaskRequest } from "@alneas/eaos-server/agentic/types";
+ * export function queued(request: ServerAgentTaskRequest) { return createAgentJob({ request, kind: "workflow" }); }
+ * ```
+ */
+declare function createAgentJob(input: {
+    /**
+     * Host-verified task cloned into the durable job and hashed for idempotency integrity.
+     */
+    request: ServerAgentTaskRequest;
+    /**
+     * Queue kind used together with tenant and idempotencyKey to partition durable deduplication.
+     */
+    kind: string;
+    /**
+     * Optional companion workflow instance ID retained in the queued record.
+     */
+    workflowInstanceId?: string;
+    /**
+     * Queue trace label; defaults to request.executionContext.correlationId, then request.id.
+     */
+    correlationId?: string;
+    /**
+     * Durable deduplication identity; defaults to request.executionContext.idempotencyKey, then request.id.
+     */
+    idempotencyKey?: string;
+    /**
+     * Job attempt ceiling retained without validation here; defaults to 5 and is later combined with dispatcher policy.
+     */
+    maxAttempts?: number;
+    /**
+     * Timestamp for availableAt, createdAt, and updatedAt; defaults to a fresh Date and must support toISOString.
+     */
+    now?: Date;
+}): AgentJobRecord<ServerAgentTaskRequest>;
+/**
+ * Persists a job and tenant/kind/idempotency index in the caller's atomic transaction.
+ * @param tx - Authorized active atomic session; the caller owns commit/rollback.
+ * @param job - Created job whose tenant/kind/key define deduplication and whose requestHash binds input.
+ * @returns A clone of the saved job, or existing indexed job when its request hash matches; existing lifecycle state is preserved.
+ * @throws Reused idempotency key with a different request hash, missing indexed job, or propagated transaction/clone errors.
+ * @remarks This helper neither executes the job nor opens a transaction; host transaction isolation/CAS must prevent concurrent index creation races.
+ * @example
+ * ```typescript
+ * import { enqueueAgentJob, createAgentJob } from "@alneas/eaos-server/agentic/agent-jobs";
+ * import type { AtomicSession } from "@alneas/eaos-server/plugin-data/atomic";
+ * import type { ServerAgentTaskRequest } from "@alneas/eaos-server/agentic/types";
+ * export async function enqueue(tx: AtomicSession, request: ServerAgentTaskRequest) {
+ *   return enqueueAgentJob(tx, createAgentJob({ request, kind: "workflow" }));
+ * }
+ * ```
+ */
+declare function enqueueAgentJob(tx: AtomicSession, job: AgentJobRecord<ServerAgentTaskRequest>): Promise<AgentJobRecord<ServerAgentTaskRequest>>;
+/**
+ * Tenant-scoped CAS persistence, lease timing, admission, and transactional completion hook.
+ * @see createAtomicAgentJobStore.
+ */
+interface AtomicAgentJobStoreOptions {
+    /** Host atomic repository enforcing durable CAS and tenant isolation. */
+    repository: AtomicRepository;
+    /** Verified tenant/plugin/user repository scope, retained by reference. */
+    principal: PluginPrincipal;
+    /** Additional stale grace after lease expiry in milliseconds; finite and at least 1000, defaults to 300000. */
+    staleAfterMs?: number;
+    /** Lease duration in milliseconds; finite and at least 1000, defaults to 900000. */
+    leaseMs?: number;
+    /** Clock for state transitions; defaults to fresh Date. */
+    now?: () => Date;
+    /** Current host admission is checked before and after durable mutations. */
+    verifyCurrent?: () => Promise<void>;
+    /** Persist the domain result in the same transaction as the succeeded job state. */
+    onCompleted?: (tx: AtomicSession, job: Readonly<AgentJobRecord<ServerAgentTaskRequest>>, result: Readonly<ServerAgentTaskResult>) => Promise<void>;
+}
+/**
+ * Creates a lease-checked agent queue over an existing tenant-scoped atomic repository.
+ * @param options - Repository/principal plus clocks, leases, optional current-admission checks, and transactional result persistence.
+ * @returns Store operations validating tenant/request integrity and lease token before transitions. claim increments attempt and leases due queued/retryable jobs or sufficiently stale running jobs.
+ * @throws Synchronously for missing dependencies or lease/stale durations below 1000 ms/nonfinite. Operations reject integrity/tenant/lease/admission errors, invalid claim limits, bounded-scan exhaustion, or propagated repository/hook errors.
+ * @remarks claim scans at most 100 pages of 100 rows and permits safe-integer limits 1–100. Running jobs recover only when leaseUntil is at least staleAfterMs before the claim clock. Transition timestamps use options.now, ignoring the interface-supplied now argument. No lease renewal or worker cancellation exists; stale execution can overlap a reclaimed attempt, so side effects need host idempotency. verifyCurrent runs around durable mutations when supplied. Transactional onCompleted runs before succeeded state persistence in the same session.
+ * @example
+ * ```typescript
+ * import { createAtomicAgentJobStore, type AtomicAgentJobStoreOptions } from "@alneas/eaos-server/agentic/agent-jobs";
+ * export function jobStore(options: AtomicAgentJobStoreOptions) { return createAtomicAgentJobStore(options); }
+ * ```
+ */
+declare function createAtomicAgentJobStore(options: AtomicAgentJobStoreOptions): AgentJobStore;
+/**
+ * Marks an owned unstarted job cancelled in the caller's atomic session.
+ * @param tx - Authorized atomic session; caller commits/rolls back.
+ * @param principal - Verified tenant/user who owns the job.
+ * @param jobId - Stored queue job identifier.
+ * @param now - Cancellation timestamp; defaults to a fresh Date.
+ * @returns A cloned cancelled job, unchanged when already cancelled.
+ * @throws Missing/foreign job, request integrity mismatch, status other than queued/retryable/waiting_approval/cancelled, or transaction/clock errors.
+ * @remarks Running leases cannot be interrupted by this edit. This function performs no external runtime cancellation, approval-ticket revocation, or live admission callback.
+ * @example
+ * ```typescript
+ * import { cancelAgentJob } from "@alneas/eaos-server/agentic/agent-jobs";
+ * import type { AtomicSession } from "@alneas/eaos-server/plugin-data/atomic";
+ * import type { PluginPrincipal } from "@alneas/eaos-server/plugin-data";
+ * export async function cancel(tx: AtomicSession, principal: PluginPrincipal, jobId: string) { return cancelAgentJob(tx, principal, jobId); }
+ * ```
+ */
+declare function cancelAgentJob(tx: AtomicSession, principal: PluginPrincipal, jobId: string, now?: Date): Promise<AgentJobRecord<ServerAgentTaskRequest>>;
+
+export { DurableAgentJobDispatcher, cancelAgentJob, createAgentJob, createAtomicAgentJobStore, enqueueAgentJob };
+export type { AgentJobClaimFilter, AgentJobDispatchResult, AgentJobDispatcherOptions, AgentJobStore, AtomicAgentJobStoreOptions };

package/dist/agentic/agent-jobs.js

@@ -0,0 +1,15 @@
+import {
+  DurableAgentJobDispatcher,
+  cancelAgentJob,
+  createAgentJob,
+  createAtomicAgentJobStore,
+  enqueueAgentJob
+} from "../chunk-PBC3MZUL.js";
+export {
+  DurableAgentJobDispatcher,
+  cancelAgentJob,
+  createAgentJob,
+  createAtomicAgentJobStore,
+  enqueueAgentJob
+};
+//# sourceMappingURL=agent-jobs.js.map

package/dist/agentic/agent-jobs.js.map

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

package/dist/agentic/agent-node.d.ts

@@ -0,0 +1,40 @@
+import { WorkflowAgentRunner, WorkflowAgentRequest, WorkflowAgentProposal } from '@alneas/eaos-core';
+import { AgentGraphState, GraphNodeHandler } from './graph.js';
+import '@langchain/langgraph';
+
+/**
+ * Host runner, request construction, and output validation for {@link createWorkflowAgentNode}.
+ * @typeParam TOutput - Domain output expected from the proposal; defaults to unknown and runtime validation remains plugin-owned.
+ */
+interface WorkflowAgentNodeOptions<TOutput = unknown> {
+    /** Host-owned runner that returns proposals; this node performs no proposed action. */
+    runner: WorkflowAgentRunner;
+    /** Called per node invocation with a structured clone of state; must resolve a request matching tenantId, userId, and sessionId/workflowId. */
+    createRequest: (state: AgentGraphState) => WorkflowAgentRequest | Promise<WorkflowAgentRequest>;
+    /** Called after a completed proposal with output, full proposal, and original current state; resolves the domain-validated output stored beside the proposal. Errors reject node execution. */
+    validateOutput?: (output: TOutput, proposal: WorkflowAgentProposal<TOutput>, state: AgentGraphState) => TOutput | Promise<TOutput>;
+    /** Context property receiving cloned proposal and validated output; existing data at this key is overwritten. @defaultValue "agentProposal" */
+    contextKey?: string;
+}
+/**
+ * Creates a LangGraph node that records an agent proposal in workflow state.
+ * It deliberately does not execute proposed actions or create approvals.
+ * @typeParam TOutput - Domain-specific proposal output passed to optional plugin validation; defaults to unknown.
+ * @param options - Runner, request builder, output validator, and context key.
+ * @returns An async graph handler resolving merged context and history with an agent summary entry.
+ * @throws Synchronously if runner or request builder is missing. Node execution rejects principal/workflow mismatch, noncompleted runner results, and callback or structuredClone failures.
+ * @remarks validateOutput receives proposal output, proposal, and the current state after a completed run; its result is stored alongside the proposal. Unlike createRequest, this callback receives the original state. Host admission, durable checkpointing, and action approval remain outside this node.
+ * @example
+ * ```typescript
+ * import { createWorkflowAgentNode } from "@alneas/eaos-server/agentic/agent-node";
+ * import type { WorkflowAgentNodeOptions } from "@alneas/eaos-server/agentic/agent-node";
+ * export function proposalNode(options: WorkflowAgentNodeOptions) {
+ *   // Host callbacks build authorized requests and validate domain output.
+ *   return createWorkflowAgentNode(options);
+ * }
+ * ```
+ */
+declare function createWorkflowAgentNode<TOutput = unknown>(options: WorkflowAgentNodeOptions<TOutput>): GraphNodeHandler;
+
+export { createWorkflowAgentNode };
+export type { WorkflowAgentNodeOptions };

package/dist/agentic/agent-node.js

@@ -0,0 +1,7 @@
+import {
+  createWorkflowAgentNode
+} from "../chunk-UGNTCOVR.js";
+export {
+  createWorkflowAgentNode
+};
+//# sourceMappingURL=agent-node.js.map

package/dist/agentic/agent-node.js.map

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

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

@@ -0,0 +1,33 @@
+import { WorkflowAgentRunner } from '@alneas/eaos-core';
+import { ServerAgentExecutor } from './types.js';
+
+/**
+ * Host executor configuration for {@link createWorkflowAgentRunner}.
+ */
+interface ServerWorkflowAgentRunnerOptions {
+    /** Host-owned executor. It may be backed by Goose, Hermes or another runtime. */
+    executor: ServerAgentExecutor;
+    /** Optional host runtime label copied into every normalized run result. */
+    runtimeId?: string;
+}
+/**
+ * Bridges the host/server executor contract to the vendor-neutral workflow
+ * runner contract. The executor output is parsed as a proposal; it is never
+ * treated as an instruction to perform a side effect.
+ * @param options - Host-owned executor and optional runtime label.
+ * @returns A runner whose generic run method accepts a WorkflowAgentRequest and resolves a parsed proposal or a failure result. Executor errors become FAILED/UNAVAILABLE data; parse errors become nonretryable INVALID_PROPOSAL data.
+ * @throws Synchronously when executor is missing. run may reject before execution when request serialization fails.
+ * @remarks The runner forwards workflow/correlation/idempotency/tool context but does not independently authorize, retry, deduplicate, execute tools, or enforce timeouts. Those boundaries belong to the host executor. Runtime text must parse as a version 1.0 proposal; domain-specific output still needs plugin validation.
+ * @example
+ * ```typescript
+ * import { createWorkflowAgentRunner } from "@alneas/eaos-server/agentic/agent-runner";
+ * import type { ServerAgentExecutor } from "@alneas/eaos-server/agentic/types";
+ * export function workflowRunner(executor: ServerAgentExecutor) {
+ *   return createWorkflowAgentRunner({ executor, runtimeId: "host-runtime" });
+ * }
+ * ```
+ */
+declare function createWorkflowAgentRunner(options: ServerWorkflowAgentRunnerOptions): WorkflowAgentRunner;
+
+export { createWorkflowAgentRunner };
+export type { ServerWorkflowAgentRunnerOptions };

package/dist/agentic/agent-runner.js

@@ -0,0 +1,7 @@
+import {
+  createWorkflowAgentRunner
+} from "../chunk-6XZXYNJR.js";
+export {
+  createWorkflowAgentRunner
+};
+//# sourceMappingURL=agent-runner.js.map

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

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