@alneas/eaos-server 0.0.0-stage → 0.2.0

package/CHANGELOG.md

@@ -0,0 +1,41 @@
+# @alneas/eaos-server
+
+## 0.2.0
+
+### Added
+
+- Expose canonical `createChatClient` and `createToolAgent` execution APIs backed by existing Appkit chat, Action and execution-session primitives. Connect live authorization, model routes, limits, cancellation, guards, budgets, usage and observations.
+- Route built-in LiteLLM tasks through the same chat client. Support Host-owned authentication headers and optional shared chat configuration without changing injected-executor priority or Goose/Hermes process execution.
+
+### Changed
+
+- Align English/Japanese setup and support guidance with actual package requirements; link the existing GitHub private reporting channel without adding a support guarantee.
+
+- Consume EAOS Core ^0.2.0 and reauthorize after asynchronous guards/accounting/telemetry, before returning output. Recheck retained tool history before each subsequent model request.
+- Require explicit model-to-adapter bindings when a model registry is configured. Reject protocol-reserved provider parameters rather than allowing them to override the selected model or messages.
+
+### Upgrade
+
+- Built-in LiteLLM now requests OpenAI-compatible SSE streams. JSON-only custom endpoints must provide a compatible Host adapter or injected executor. Existing task result envelopes, endpoint/model/fetch options, HTTP status errors, output ceilings and process dispatch remain supported; common stream, cancellation and validation failures use shared chat diagnostics.
+- Provider usage may be unavailable in Appkit events. Host accounting receives unknown usage explicitly and must reconcile it instead of treating it as zero; accounting failures propagate. Keep external side-effect idempotency and durable accounting in the Host.
+- Install Core 0.2.0 before Server 0.2.0. This update performs no migrations or tenant activation.
+
+## 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,49 @@
+# Server の実行と永続化
+
+[English](https://github.com/dataarthub/eaos/blob/main/packages/server/README.md) | [日本語](https://github.com/dataarthub/eaos/blob/main/packages/server/README.ja.md)
+
+[ドキュメントサイトの日本語ページ](https://tech-docs.alneas.com/ja/eaos-workspace/server/)でプロジェクト全体の日本語ドキュメントを案内しています。未翻訳・レビュー待ちのページは英語にフォールバックする場合があります。公開サイトは公開済みバージョンの案内であり、この README の 0.2.0 候補と一致しない場合は、対応する英語ガイドと変更履歴を確認してください。
+
+[![TypeScript](https://img.shields.io/badge/TypeScript-3178C6?style=flat&logo=typescript&logoColor=white)](https://www.typescriptlang.org/docs/) [![Node.js minimum 24](https://img.shields.io/badge/Node.js-%3E%3D24-339933?style=flat&logo=nodedotjs&logoColor=white)](https://nodejs.org/en/about/previous-releases) [![Hono](https://img.shields.io/badge/Hono-E36002?style=flat&logo=hono&logoColor=white)](https://hono.dev/docs/)
+
+## Elevator Pitch
+
+ホスト開発者は Server を使い、HTTP/MCP、ライフサイクル、永続データサービスを構成できます。
+
+## Why & Value
+
+共通実装により、認可、CAS、監査、Outbox の振る舞いを揃えます。プロバイダーへの接続、現在の識別情報、デプロイ方針はホストが管理します。この MIT パッケージの実装と型宣言は公開モノレポで管理します。
+
+## Key Highlights
+
+- Hono と MCP の連携
+- レビューを経たライフサイクル計画
+- 永続的な CAS と監査
+- スコープを限定したデータベースとストレージ
+
+## Quickstart
+
+この checkout は 0.2.0 のリリース準備用です。0.1.0 は公開済みです。0.2.0 の公開まではチェックサムを固定した候補 tarball を導入し、以下のコマンドは公開後に使用してください。
+
+### 公開 API の import
+
+Node.js 24 以上と、必須 peer の Appkit Core 0.2.0 を使用してください。以下の正規化の例は純粋な処理で、データベース接続や認証情報は不要です。Server の実行には、別途ホストが管理する識別情報、認可、永続化の接続が必要です。subpath は import の対象であり、個別にインストールするパッケージではありません。
+
+```bash
+bun add @alneas/eaos-server@0.2.0 @alneas/appkit-core@0.2.0
+```
+
+```typescript
+import { canonical } from '@alneas/eaos-server/lifecycle-engine'
+
+console.log(canonical({ format: 1, operation: 'inspect' }))
+```
+
+## Next Steps
+
+- [変更履歴](https://github.com/dataarthub/eaos/blob/main/packages/server/CHANGELOG.md)
+- [アーキテクチャと境界](docs/guide.md)
+- [API リファレンス](docs/api.md)
+- [EAOS の構成](https://tech-docs.alneas.com/eaos-workspace/architecture/)
+
+英語での質問・不具合報告を [GitHub Issues](https://github.com/dataarthub/eaos/issues) で受け付けています。非公開の脆弱性報告には [GitHubの非公開報告機能](https://github.com/dataarthub/eaos/security/advisories/new)を利用できます。

package/README.md

@@ -1,3 +1,47 @@
-# 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.
+[English](https://github.com/dataarthub/eaos/blob/main/packages/server/README.md) | [日本語](https://github.com/dataarthub/eaos/blob/main/packages/server/README.ja.md)
+
+[![TypeScript](https://img.shields.io/badge/TypeScript-3178C6?style=flat&logo=typescript&logoColor=white)](https://www.typescriptlang.org/docs/) [![Node.js minimum 24](https://img.shields.io/badge/Node.js-%3E%3D24-339933?style=flat&logo=nodedotjs&logoColor=white)](https://nodejs.org/en/about/previous-releases) [![Hono](https://img.shields.io/badge/Hono-E36002?style=flat&logo=hono&logoColor=white)](https://hono.dev/docs/)
+
+## 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
+
+This checkout prepares version 0.2.0; version 0.1.0 is already published. Until 0.2.0 is published, install the checksum-pinned candidate tarball. The command below applies after that release.
+
+### 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@0.2.0 @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/)
+
+Questions and issue reports in English are welcome in [GitHub Issues](https://github.com/dataarthub/eaos/issues). Private vulnerability reports can use [GitHub private reporting](https://github.com/dataarthub/eaos/security/advisories/new).

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

@@ -0,0 +1,333 @@
+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 '@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 '@alneas/eaos-core/plugin-sdk';
+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":[]}