@alneas/eaos-core API

Public entrypoints

Import	Contract
`@alneas/eaos-core/adapters`	Typed public export
`@alneas/eaos-core/adapters/platform-context`	Typed public export
`@alneas/eaos-core/adapters/tenant-adapter`	Typed public export
`@alneas/eaos-core/adapters/types`	Typed public export
`@alneas/eaos-core/agent/approved-execution`	Typed public export
`@alneas/eaos-core/agent/cache-manager`	Typed public export
`@alneas/eaos-core/agent/circuit-breaker`	Typed public export
`@alneas/eaos-core/agent/workflow-effects`	Typed public export
`@alneas/eaos-core/agentic/execution-sandbox`	Typed public export
`@alneas/eaos-core/agentic`	Typed public export
`@alneas/eaos-core/agentic/instinct-engine`	Typed public export
`@alneas/eaos-core/agentic/model-routing-gateway`	Typed public export
`@alneas/eaos-core/agentic/runtime-policy`	Typed public export
`@alneas/eaos-core/agentic/runtime`	Typed public export
`@alneas/eaos-core/agentic/skill-gate-bridge`	Typed public export
`@alneas/eaos-core/agentic/structured-tool-call-adapter`	Typed public export
`@alneas/eaos-core/agentic/types`	Typed public export
`@alneas/eaos-core/ai/anomaly`	Typed public export
`@alneas/eaos-core/ai/execution-broker`	Typed public export
`@alneas/eaos-core/ai/governance`	Typed public export
`@alneas/eaos-core/ai/host-adapters`	Typed public export
`@alneas/eaos-core/ai`	Typed public export
`@alneas/eaos-core/ai/model-registry`	Typed public export
`@alneas/eaos-core/ai/proposal-ui`	Typed public export
`@alneas/eaos-core/ai/resilience`	Typed public export
`@alneas/eaos-core/ai/skills`	Typed public export
`@alneas/eaos-core/db/adapter`	Typed public export
`@alneas/eaos-core/events/outbox`	Typed public export
`@alneas/eaos-core/health`	Typed public export
`@alneas/eaos-core`	Typed public export
`@alneas/eaos-core/platform/config`	Typed public export
`@alneas/eaos-core/plugin-bundles`	Typed public export
`@alneas/eaos-core/plugin-sdk/contract-compatibility`	Typed public export
`@alneas/eaos-core/plugin-sdk/data-standards`	Typed public export
`@alneas/eaos-core/plugin-sdk/decimal-values`	Typed public export
`@alneas/eaos-core/plugin-sdk/eligibility`	Typed public export
`@alneas/eaos-core/plugin-sdk/event-bus`	Typed public export
`@alneas/eaos-core/plugin-sdk`	Typed public export
`@alneas/eaos-core/plugin-sdk/procedure`	Typed public export
`@alneas/eaos-core/plugin-sdk/registry`	Typed public export
`@alneas/eaos-core/plugin-sdk/storage-policy`	Typed public export
`@alneas/eaos-core/plugin-sdk/tenant-strategy-registry`	Typed public export
`@alneas/eaos-core/plugin-sdk/types`	Typed public export
`@alneas/eaos-core/secrets/secret-resolver`	Typed public export
`@alneas/eaos-core/security/audit-sink`	Typed public export
`@alneas/eaos-core/security/gatekeeper`	Typed public export
`@alneas/eaos-core/security/platform-security`	Typed public export
`@alneas/eaos-core/serialization`	Typed public export
`@alneas/eaos-core/serialization/json`	Typed public export
`@alneas/eaos-core/storage`	Typed public export
`@alneas/eaos-core/types/env`	Typed public export
`@alneas/eaos-core/vector`	Typed public export
`@alneas/eaos-core/webhook/delivery`	Typed public export
`@alneas/eaos-core/webhook`	Typed public export
`@alneas/eaos-core/workflow-contracts`	Typed public export
`@alneas/eaos-core/workflow-definition`	Typed public export
`@alneas/eaos-core/workflow-runtime`	Typed public export
`@alneas/eaos-core/workflow-visualization`	Typed public export
`@alneas/eaos-core/db`	Typed public export
`@alneas/eaos-core/entitlements`	Typed public export
`@alneas/eaos-core/plugin-sdk/define-plugin`	Typed public export
`@alneas/eaos-core/testing`	Typed public export
`@alneas/eaos-core/contracts/data-contracts`	Typed public export
`@alneas/eaos-core/contracts/json-documents`	Typed public export
`@alneas/eaos-core/migration-types`	Typed public export
`@alneas/eaos-core/data-contracts`	Typed public export
`@alneas/eaos-core/contracts/platform-records`	Typed public export
`@alneas/eaos-core/contracts/platform-records.json`	Packaged JSON contract/data asset; resolve this exported path with the host loader

[FUNCTION] `addDecimalValues`

Add two exact decimal strings using bigint coefficients.

Imports: @alneas/eaos-core/plugin-sdk, @alneas/eaos-core/plugin-sdk/decimal-values.

Signature

declare function addDecimalValues(left: string, right: string): string;

Parameters

Name	Type	Required	Description
`left`	`string`	Yes	First valid decimal string.
`right`	`string`	Yes	Second valid decimal string.

Returns

string

Their exact sum, using the larger input scale.

Errors and rejections

Error for invalid input or a sum exceeding decimalValueSchema.

Example

import { addDecimalValues } from "@alneas/eaos-core/plugin-sdk/decimal-values";
console.log(addDecimalValues("0.10", "0.20")); // 0.30

[CONSTANT] `AGENT_RUNTIME_POLICY_VERSION`

Host-neutral resource and placement policy for the three-host runtime.

This is a reviewable default contract, not a Docker/systemd executor. Hosts translate it to cgroups, container options or service units and may tighten it after measuring the target machine.

Imports: @alneas/eaos-core, @alneas/eaos-core/agentic, @alneas/eaos-core/agentic/runtime-policy.

Signature

declare const AGENT_RUNTIME_POLICY_VERSION: 1;

Parameters

Name	Type	Required	Description
—	—	—	No call parameters.

Returns

Declared constant value.

Example

See the owning declaration and linked feature guide for usage; no standalone example is documented in source.

[INTERFACE] `AgentCapabilitiesConfig`

Agent/skill/tool discovery metadata and per-tool policy declarations.

Imports: @alneas/eaos-core, @alneas/eaos-core/plugin-sdk, @alneas/eaos-core/plugin-sdk/types.

Signature

interface AgentCapabilitiesConfig {
    providedAgents?: ProvidedAgentConfig[];
    skills?: SkillCatalogEntry[];
    webMcpTools?: WebMcpToolDefinition[];
    gatekeeperPolicies?: Record<string, GatekeeperPolicy>;
}

Parameters

Name	Type	Required	Description
`providedAgents`	`ProvidedAgentConfig[]`	No	Optional agent metadata advertised by the plugin.
`skills`	`SkillCatalogEntry[]`	No	Runtime-discoverable skill metadata; execution remains bound to MCP/actions.
`webMcpTools`	`WebMcpToolDefinition[]`	No	Optional browser-side tools advertised by the plugin.
`gatekeeperPolicies`	`Record<string, GatekeeperPolicy>`	No	Tool-name keyed security policies registered by the host.

Returns

Type declaration; no runtime value.

Public members

`providedAgents`

Optional agent metadata advertised by the plugin.

`skills`

Runtime-discoverable skill metadata; execution remains bound to MCP/actions.

`webMcpTools`

Optional browser-side tools advertised by the plugin.

`gatekeeperPolicies`

Tool-name keyed security policies registered by the host.

Example

See the owning declaration and linked feature guide for usage; no standalone example is documented in source.

[INTERFACE] `AgentExecutionContext`

Host-provided tenant/user/session scope for tool hook execution.

Imports: @alneas/eaos-core, @alneas/eaos-core/agentic, @alneas/eaos-core/agentic/runtime.

Signature

interface AgentExecutionContext {
    tenantId: string;
    userId: string;
    sessionId: string;
    traceId: string;
    userRoles: string[];
    metadata?: Record<string, unknown>;
}

Parameters

Name	Type	Required	Description
`tenantId`	`string`	Yes	Verified tenant boundary for the record or operation; host authorization must establish this scope.
`userId`	`string`	Yes	User identity within the tenant supplied by the trusted host.
`sessionId`	`string`	Yes	Host session identity used to correlate lifecycle callbacks and operations.
`traceId`	`string`	Yes	Trace correlation identity propagated through host execution and audit paths.
`userRoles`	`string[]`	Yes	Verified host role claims passed to gatekeeper/runtime evaluation.
`metadata`	`Record<string, unknown>`	No	Optional host/provider metadata; callers remain responsible for sensitive content and validation.

Returns

Type declaration; no runtime value.

Public members

`tenantId`

Verified tenant boundary for the record or operation; host authorization must establish this scope.

`userId`

User identity within the tenant supplied by the trusted host.

`sessionId`

Host session identity used to correlate lifecycle callbacks and operations.

`traceId`

Trace correlation identity propagated through host execution and audit paths.

`userRoles`

Verified host role claims passed to gatekeeper/runtime evaluation.

`metadata`

Optional host/provider metadata; callers remain responsible for sensitive content and validation.

Example

See the owning declaration and linked feature guide for usage; no standalone example is documented in source.

[INTERFACE] `AgentInstinct`

Tenant/domain heuristic learned from a session with confidence and outcome counts.

Imports: @alneas/eaos-core, @alneas/eaos-core/agentic, @alneas/eaos-core/agentic/instinct-engine.

Signature

interface AgentInstinct {
    id: string;
    tenantId: string;
    domain: string;
    pattern: string;
    heuristic: string;
    confidence: number;
    successCount: number;
    failureCount: number;
    embedding?: number[];
    createdAt: string;
    updatedAt: string;
}

Parameters

Name	Type	Required	Description
`id`	`string`	Yes	Generated process-local heuristic identity; extraction does not persist it.
`tenantId`	`string`	Yes	Verified tenant boundary for the record or operation; host authorization must establish this scope.
`domain`	`string`	Yes	Exact host classification key used by local heuristic filtering.
`pattern`	`string`	Yes	Observed session pattern that motivates the reusable heuristic.
`heuristic`	`string`	Yes	Reusable suggested handling text extracted or synthesized from a session.
`confidence`	`number`	Yes	Reported confidence ratio, conventionally from zero to one; validate at the consuming boundary.
`successCount`	`number`	Yes	Number of successful uses reported for the heuristic.
`failureCount`	`number`	Yes	Number of failed uses reported for the heuristic.
`embedding`	`number[]`	No	Optional numeric embedding metadata; extraction does not generate or persist embeddings.
`createdAt`	`string`	Yes	Creation timestamp supplied or generated by the owning API.
`updatedAt`	`string`	Yes	Timestamp of the latest host-recorded update; this contract does not persist changes.

Returns

Type declaration; no runtime value.

Public members

`id`

Generated process-local heuristic identity; extraction does not persist it.

`tenantId`

Verified tenant boundary for the record or operation; host authorization must establish this scope.

`domain`

Exact host classification key used by local heuristic filtering.

`pattern`

Observed session pattern that motivates the reusable heuristic.

`heuristic`

Reusable suggested handling text extracted or synthesized from a session.

`confidence`

Reported confidence ratio, conventionally from zero to one; validate at the consuming boundary.

`successCount`

Number of successful uses reported for the heuristic.

`failureCount`

Number of failed uses reported for the heuristic.

`embedding`

Optional numeric embedding metadata; extraction does not generate or persist embeddings.

`createdAt`

Creation timestamp supplied or generated by the owning API.

`updatedAt`

Timestamp of the latest host-recorded update; this contract does not persist changes.

Example

See the owning declaration and linked feature guide for usage; no standalone example is documented in source.

[TYPE] `AgentJobKind`

Host agent-job category, including named built-ins and extensible strings.

Imports: @alneas/eaos-core, @alneas/eaos-core/workflow-runtime.

Signature

type AgentJobKind = 'workflow-proposal' | 'reconciliation' | 'anomaly-investigation' | 'document-analysis' | 'report-draft' | 'incident-triage' | 'retrieval-synthesis' | (string & {});

Parameters

Name	Type	Required	Description
—	—	—	No call parameters.

Returns

Type declaration; no runtime value.

Example

See the owning declaration and linked feature guide for usage; no standalone example is documented in source.

[INTERFACE] `AgentJobRecord`

Host-persisted agent request, retry/lease state and optional result or failure.

Imports: @alneas/eaos-core, @alneas/eaos-core/workflow-runtime.

Signature

interface AgentJobRecord<TRequest = unknown, TResult = unknown> {
    jobId: string;
    tenantId: string;
    kind: AgentJobKind;
    status: AgentJobStatus;
    request: TRequest;
    requestHash: string;
    workflowInstanceId?: string;
    correlationId: string;
    idempotencyKey: string;
    attempt: number;
    maxAttempts: number;
    availableAt: string;
    leaseUntil?: string;
    leaseToken?: string;
    result?: TResult;
    error?: string;
    failureCode?: string;
    createdAt: string;
    updatedAt: string;
}

Parameters

Name	Type	Required	Description
`jobId`	`string`	Yes	Durable host job identity, separate from workflow and replay identities.
`tenantId`	`string`	Yes	Verified tenant boundary for the record or operation; host authorization must establish this scope.
`kind`	`AgentJobKind`	Yes	Host job category; built-in names and custom strings are supported.
`status`	`AgentJobStatus`	Yes	Host-persisted durable job lifecycle, including retries, cancellation and review.
`request`	`TRequest`	Yes	Admitted domain request stored or passed to a host execution boundary.
`requestHash`	`string`	Yes	SHA-256 identity of the canonical agent-job request.
`workflowInstanceId`	`string`	No	Optional durable instance identity correlating this event/job with a workflow.
`correlationId`	`string`	Yes	Identity grouping causally related workflow requests and events.
`idempotencyKey`	`string`	Yes	Replay identity for the same admitted operation; the host must persist/deduplicate it before unsafe retries.
`attempt`	`number`	Yes	Host-recorded one-based execution attempt; helpers consuming it require a positive integer.
`maxAttempts`	`number`	Yes	Maximum intended attempt count; delay calculators validate it but do not themselves stop retries.
`availableAt`	`string`	Yes	Earliest timestamp at which the host scheduler may claim or execute this work.
`leaseUntil`	`string`	No	Optional deadline until which the current worker claim remains live.
`leaseToken`	`string`	No	Optional host claim ownership token used for optimistic settlement.
`result`	`TResult`	No	Optional durable domain output written by host job settlement.
`error`	`string`	No	Optional human-readable failure detail; absence does not independently establish success.
`failureCode`	`string`	No	Optional host/runtime classification used to choose durable retry behavior.
`createdAt`	`string`	Yes	Creation timestamp supplied or generated by the owning API.
`updatedAt`	`string`	Yes	Timestamp of the latest host-recorded update; this contract does not persist changes.

Returns

Type declaration; no runtime value.

Type parameters

TRequest: Persisted agent request shape; defaults to unknown.
TResult: Optional persisted job output shape; defaults to unknown.

Public members

`jobId`

Durable host job identity, separate from workflow and replay identities.

`tenantId`

Verified tenant boundary for the record or operation; host authorization must establish this scope.

`kind`

Host job category; built-in names and custom strings are supported.

`status`

Host-persisted durable job lifecycle, including retries, cancellation and review.

`request`

Admitted domain request stored or passed to a host execution boundary.

`requestHash`

SHA-256 identity of the canonical agent-job request.

`workflowInstanceId`

Optional durable instance identity correlating this event/job with a workflow.

`correlationId`

Identity grouping causally related workflow requests and events.

`idempotencyKey`

Replay identity for the same admitted operation; the host must persist/deduplicate it before unsafe retries.

`attempt`

Host-recorded one-based execution attempt; helpers consuming it require a positive integer.

`maxAttempts`

Maximum intended attempt count; delay calculators validate it but do not themselves stop retries.

`availableAt`

Earliest timestamp at which the host scheduler may claim or execute this work.

`leaseUntil`

Optional deadline until which the current worker claim remains live.

`leaseToken`

Optional host claim ownership token used for optimistic settlement.

`result`

Optional durable domain output written by host job settlement.

`error`

Optional human-readable failure detail; absence does not independently establish success.

`failureCode`

Optional host/runtime classification used to choose durable retry behavior.

`createdAt`

Creation timestamp supplied or generated by the owning API.

`updatedAt`

Timestamp of the latest host-recorded update; this contract does not persist changes.

Example

See the owning declaration and linked feature guide for usage; no standalone example is documented in source.

[TYPE] `AgentJobStatus`

Durable job lifecycle including approval, retry and cancellation states.

Imports: @alneas/eaos-core, @alneas/eaos-core/workflow-runtime.

Signature

type AgentJobStatus = 'queued' | 'running' | 'waiting_approval' | 'succeeded' | 'retryable' | 'failed' | 'cancelled';

Parameters

Name	Type	Required	Description
—	—	—	No call parameters.

Returns

Type declaration; no runtime value.

Example

See the owning declaration and linked feature guide for usage; no standalone example is documented in source.

[INTERFACE] `AgentNode`

Organizational agent identity, reporting relationship, budget and lifecycle metadata.

Imports: @alneas/eaos-core, @alneas/eaos-core/agentic, @alneas/eaos-core/agentic/types.

Signature

interface AgentNode {
    id: string;
    orgId: string;
    parentId?: string;
    name: string;
    role: 'ceo' | 'executive' | 'manager' | 'worker' | 'red_team';
    tierLevel: ModelTier;
    allowedSensitivityLevel: DataSensitivityLevel;
    dailyBudgetCapUsd: number;
    currentDailySpendUsd: number;
    capabilities: string[];
    status: 'active' | 'busy' | 'paused' | 'error';
    createdAt: string;
    updatedAt: string;
}

Parameters

Name	Type	Required	Description
`id`	`string`	Yes	Organizational agent identity used for assignment and hierarchy.
`orgId`	`string`	Yes	Organization identity grouping agents/tasks within host data.
`parentId`	`string`	No	Optional parent agent identity in the organizational reporting tree.
`name`	`string`	Yes	Human-readable display name supplied by the plugin/provider catalog; distinct from the stable ID.
`role`	`'ceo' \| 'executive' \| 'manager' \| 'worker' \| 'red_team'`	Yes	Organizational role used by host coordination: ceo, executive, manager, worker or red_team.
`tierLevel`	`ModelTier`	Yes	Advertised agent model capability/cost tier; host routing applies actual policy.
`allowedSensitivityLevel`	`DataSensitivityLevel`	Yes	Highest/declared sensitivity classification accepted by this agent according to host policy.
`dailyBudgetCapUsd`	`number`	Yes	Maximum advertised daily spending allowance in US dollars; accounting/enforcement belongs to the host.
`currentDailySpendUsd`	`number`	Yes	Host-reported spending already accrued today in US dollars.
`capabilities`	`string[]`	Yes	Advertised operation/capability names; presence alone does not authorize execution.
`status`	`'active' \| 'busy' \| 'paused' \| 'error'`	Yes	Host agent availability state; Core does not schedule work from this field.
`createdAt`	`string`	Yes	Creation timestamp supplied or generated by the owning API.
`updatedAt`	`string`	Yes	Timestamp of the latest host-recorded update; this contract does not persist changes.

Returns

Type declaration; no runtime value.

Public members

`id`

Organizational agent identity used for assignment and hierarchy.

`orgId`

Organization identity grouping agents/tasks within host data.

`parentId`

Optional parent agent identity in the organizational reporting tree.

`name`

Human-readable display name supplied by the plugin/provider catalog; distinct from the stable ID.

`role`

Organizational role used by host coordination: ceo, executive, manager, worker or red_team.

`tierLevel`

Advertised agent model capability/cost tier; host routing applies actual policy.

`allowedSensitivityLevel`

Highest/declared sensitivity classification accepted by this agent according to host policy.

`dailyBudgetCapUsd`

Maximum advertised daily spending allowance in US dollars; accounting/enforcement belongs to the host.

`currentDailySpendUsd`

Host-reported spending already accrued today in US dollars.

`capabilities`

Advertised operation/capability names; presence alone does not authorize execution.

`status`

Host agent availability state; Core does not schedule work from this field.

`createdAt`

Creation timestamp supplied or generated by the owning API.

`updatedAt`

Timestamp of the latest host-recorded update; this contract does not persist changes.

Example

See the owning declaration and linked feature guide for usage; no standalone example is documented in source.

[CLASS] `AgentRuntime`

Sequence admission hooks around a tool executor and dispatch lifecycle observers.

Imports: @alneas/eaos-core, @alneas/eaos-core/agentic, @alneas/eaos-core/agentic/runtime.

Signature

declare class AgentRuntime {
    constructor(dbAdapter?: DatabaseAdapter | undefined);
    registerPreToolHook(handler: PreToolHookHandler): void;
    registerPostToolHook(handler: PostToolHookHandler): void;
    registerSessionStartHook(handler: SessionStartHookHandler): void;
    registerStopHook(handler: StopHookHandler): void;
    onSessionStart(payload: SessionHookPayload): Promise<void>;
    executeTool<T = unknown>(toolName: string, rawArgs: Record<string, unknown>, context: AgentExecutionContext, executor: (args: Record<string, unknown>) => Promise<T>): Promise<{
        success: boolean;
        result?: T;
        error?: string;
        status: 'COMPLETED' | 'BLOCKED' | 'PENDING_APPROVAL';
        riskLevel?: RiskLevel;
    }>;
    onStop(payload: StopHookPayload): Promise<void>;
}

Parameters

Name	Type	Required	Description
`dbAdapter`	`DatabaseAdapter \| undefined`	No	Optional database adapter retained by the instance; not used by current execution methods.

Returns

AgentRuntime

Remarks

Registers a heuristic secret scanner first. This is not comprehensive secret detection or host authorization. State is process-local; no unregister API, persistence, cancellation or retry is supplied. Session/stop failures are logged; post-tool Promises are not awaited. The optional database adapter is currently unused.

Constructor contract

Public members

`registerPreToolHook`

Append a blocking admission hook.

Parameters:

handler: Called sequentially with current arguments and verified context before execution. Return proceed false to stop; modifiedArgs replaces arguments for subsequent hooks. Throws/rejections propagate.

Returns: No value; callback is retained until this runtime is discarded.

Example:

import { AgentRuntime } from "@alneas/eaos-core/agentic/runtime";
const runtime = new AgentRuntime();
runtime.registerPreToolHook(() => ({ proceed: true }));

`registerPostToolHook`

Append a completion observer.

Parameters:

handler: Called after executor resolves with output and elapsed milliseconds. Returned Promises are not awaited and rejections are logged; a synchronous throw is caught by executeTool and converts its result to BLOCKED even if the effect already ran.

Returns: No value; callback is retained until this runtime is discarded.

Example:

import { AgentRuntime } from "@alneas/eaos-core/agentic/runtime";
const runtime = new AgentRuntime();
runtime.registerPostToolHook(payload => { console.log(payload.durationMs); });

`registerSessionStartHook`

Append a session startup hook.

Parameters:

handler: Called sequentially by onSessionStart with session identity/metadata; returns no value and failures are logged.

Returns: No value; callback is retained until this runtime is discarded.

Example:

import { AgentRuntime } from "@alneas/eaos-core/agentic/runtime";
const runtime = new AgentRuntime();
runtime.registerSessionStartHook(payload => { console.log(payload.sessionId); });

`registerStopHook`

Append a session stop hook.

Parameters:

handler: Called sequentially by onStop with session history and reported success; returns no value and failures are logged.

Returns: No value; callback is retained until this runtime is discarded.

Example:

import { AgentRuntime } from "@alneas/eaos-core/agentic/runtime";
const runtime = new AgentRuntime();
runtime.registerStopHook(payload => { console.log(payload.success); });

`onSessionStart`

Await startup hooks in registration order and log their failures.

Parameters:

payload: Session scope and lifecycle data passed by reference to each hook.

Returns: No value; all registered hooks have been awaited, including those that failed.

Remarks

No retry or cancellation is supplied; hook errors are logged and do not stop later hooks.

Example:

import { AgentRuntime } from "@alneas/eaos-core/agentic/runtime";
const runtime = new AgentRuntime();
await runtime.onSessionStart({ sessionId: "session-1", tenantId: "tenant-demo", userId: "user-demo" });

`executeTool`

Run ordered admission hooks, then the executor and completion observers.

Parameters:

toolName: Tool identifier supplied to hooks.
rawArgs: Arguments shallow-copied before hooks; nested values remain shared.
context: Verified host scope passed unchanged to hooks.
executor: Called once only if hooks proceed, with final arguments; resolves the domain result. Executor throws/rejections become BLOCKED data.

Returns: COMPLETED with result, or BLOCKED/PENDING_APPROVAL with error and optional risk. Does not wait for asynchronous post hooks.

Type parameters

T: Resolved executor output type retained in successful result data; defaults to unknown.

Remarks

No authorization/approval is granted by COMPLETED. A synchronous post hook can report BLOCKED after the executor has already produced side effects; reconcile before retrying. No cancellation, timeout, persistence or retry is implemented.

Errors and rejections

Pre-tool hook throws/rejections propagate, including JSON serialization errors from the built-in scanner.

Example:

import { AgentRuntime } from "@alneas/eaos-core/agentic/runtime";
const runtime = new AgentRuntime();
const context = { tenantId: "tenant-demo", userId: "user-demo", sessionId: "session-1", traceId: "trace-1", userRoles: ["member"] };
console.log(await runtime.executeTool("notes.preview", {}, context, async () => ({ count: 0 })));

`executeTool.success`

Reported completion flag; inspect status/receipt and reconcile any uncertain side effects before retrying.

`executeTool.result`

Optional executor result present when the returned status is COMPLETED.

`executeTool.error`

Optional human-readable failure detail; absence does not independently establish success.

`executeTool.status`

COMPLETED after executor/initial post dispatch, BLOCKED for denied/executor failure, or PENDING_APPROVAL when a hook requests review.

`executeTool.riskLevel`

Declared operation risk used to determine review requirements; it does not itself grant authorization.

`onStop`

Await stop hooks in registration order and log their failures.

Parameters:

payload: Session scope and lifecycle data passed by reference to each hook.

Returns: No value; all registered hooks have been awaited, including those that failed.

Remarks

No retry or cancellation is supplied; hook errors are logged and do not stop later hooks.

Example:

import { AgentRuntime } from "@alneas/eaos-core/agentic/runtime";
const runtime = new AgentRuntime();
await runtime.onStop({ sessionId: "session-1", tenantId: "tenant-demo", userId: "user-demo", history: [], success: true });

Example

import { AgentRuntime } from "@alneas/eaos-core/agentic/runtime";
const runtime = new AgentRuntime();
const context = { tenantId: "tenant-demo", userId: "user-demo", sessionId: "session-1", traceId: "trace-1", userRoles: ["member"] };
console.log(await runtime.executeTool("notes.preview", {}, context, async () => ({ count: 0 })));

[INTERFACE] `AgentRuntimeResourcePolicy`

AI-host runtime concurrency, duration, resource and isolation requirements.

Imports: @alneas/eaos-core, @alneas/eaos-core/agentic, @alneas/eaos-core/agentic/runtime-policy.

Signature

interface AgentRuntimeResourcePolicy {
    placement: 'ai';
    maxConcurrent: number;
    maxRuntimeMs: number;
    memoryLimitMb: number;
    pidsLimit: number;
    rootFilesystem: 'read-only';
    network: 'private-only';
    tmpfs: AgentTmpfsPolicy;
    workspace: AgentWorkspacePolicy;
}

Parameters

Name	Type	Required	Description
`placement`	`'ai'`	Yes	Host role on which the runtime must be enforced; the default places it on ai.
`maxConcurrent`	`number`	Yes	Maximum concurrent agent runtimes; the default policy uses one.
`maxRuntimeMs`	`number`	Yes	Maximum runtime duration in milliseconds; the default policy uses 900000.
`memoryLimitMb`	`number`	Yes	Host-enforced memory ceiling in megabytes; the default policy uses 2048.
`pidsLimit`	`number`	Yes	Host-enforced process count limit; the default policy uses 100.
`rootFilesystem`	`'read-only'`	Yes	Read-only root-filesystem requirement to translate into host/container policy.
`network`	`'private-only'`	Yes	Private-network-only runtime policy; the host must enforce network isolation.
`tmpfs`	`AgentTmpfsPolicy`	Yes	Temporary-filesystem size and mount restrictions supplied to the host.
`workspace`	`AgentWorkspacePolicy`	Yes	Ephemeral workspace capacity/mount policy the host must enforce and clean up after execution.

Returns

Type declaration; no runtime value.

Public members

`placement`

Host role on which the runtime must be enforced; the default places it on ai.

`maxConcurrent`

Maximum concurrent agent runtimes; the default policy uses one.

`maxRuntimeMs`

Maximum runtime duration in milliseconds; the default policy uses 900000.

`memoryLimitMb`

Host-enforced memory ceiling in megabytes; the default policy uses 2048.

`pidsLimit`

Host-enforced process count limit; the default policy uses 100.

`rootFilesystem`

Read-only root-filesystem requirement to translate into host/container policy.

`network`

Private-network-only runtime policy; the host must enforce network isolation.

`tmpfs`

Temporary-filesystem size and mount restrictions supplied to the host.

`workspace`

Ephemeral workspace capacity/mount policy the host must enforce and clean up after execution.

Example

See the owning declaration and linked feature guide for usage; no standalone example is documented in source.

[INTERFACE] `AgentTmpfsPolicy`

Host-enforced temporary mount size and execution/privilege restrictions.

Imports: @alneas/eaos-core, @alneas/eaos-core/agentic, @alneas/eaos-core/agentic/runtime-policy.

Signature

interface AgentTmpfsPolicy {
    path: '/tmp';
    maxBytes: number;
    noexec: true;
    nosuid: true;
    nodev: true;
}

Parameters

Name	Type	Required	Description
`path`	`'/tmp'`	Yes	Temporary mount path fixed to /tmp.
`maxBytes`	`number`	Yes	Host-enforced temporary filesystem byte ceiling; default policy sets 67108864 (64 MiB).
`noexec`	`true`	Yes	Host mount restriction forbidding execution from the temporary filesystem.
`nosuid`	`true`	Yes	Host mount restriction disabling set-user-ID/set-group-ID privilege elevation.
`nodev`	`true`	Yes	Host mount restriction disabling device-file interpretation.

Returns

Type declaration; no runtime value.

Public members

`path`

Temporary mount path fixed to /tmp.

`maxBytes`

Host-enforced temporary filesystem byte ceiling; default policy sets 67108864 (64 MiB).

`noexec`

Host mount restriction forbidding execution from the temporary filesystem.

`nosuid`

Host mount restriction disabling set-user-ID/set-group-ID privilege elevation.

`nodev`

Host mount restriction disabling device-file interpretation.

Example

See the owning declaration and linked feature guide for usage; no standalone example is documented in source.

[INTERFACE] `AgentWorkspacePolicy`

Ephemeral workspace placement and capacity configuration.

Imports: @alneas/eaos-core, @alneas/eaos-core/agentic, @alneas/eaos-core/agentic/runtime-policy.

Signature

interface AgentWorkspacePolicy {
    mode: 'quota-volume' | 'tmpfs';
    path: '/workspace';
    maxBytes: number;
    persistent: false;
}

Parameters

Name	Type	Required	Description
`mode`	`'quota-volume' \| 'tmpfs'`	Yes	quota-volume is the safer default when Ruri shares the AI host’s RAM.
`path`	`'/workspace'`	Yes	Ephemeral working mount path fixed to /workspace.
`maxBytes`	`number`	Yes	Host-enforced ephemeral workspace byte ceiling; default policy sets 1073741824 (1 GiB).
`persistent`	`false`	Yes	Whether auth cookies persist, or whether a workspace survives execution; cookie default is true and runtime workspace is always false.

Returns

Type declaration; no runtime value.

Public members

`mode`

quota-volume is the safer default when Ruri shares the AI host’s RAM.

`path`

Ephemeral working mount path fixed to /workspace.

`maxBytes`

Host-enforced ephemeral workspace byte ceiling; default policy sets 1073741824 (1 GiB).

`persistent`

Whether auth cookies persist, or whether a workspace survives execution; cookie default is true and runtime workspace is always false.

Example

See the owning declaration and linked feature guide for usage; no standalone example is documented in source.

[TYPE] `AIAnomalyAlgorithm`

Declared detector families; the current configuration validator accepts only zscore and iqr.

Imports: @alneas/eaos-core, @alneas/eaos-core/ai, @alneas/eaos-core/ai/anomaly.

Signature

type AIAnomalyAlgorithm = 'zscore' | 'iqr' | 'ewma';

Parameters

Name	Type	Required	Description
—	—	—	No call parameters.

Returns

Type declaration; no runtime value.

Example

See the owning declaration and linked feature guide for usage; no standalone example is documented in source.

[INTERFACE] `AIAnomalyConfig`

History threshold and detector tuning for latest-point analysis.

Imports: @alneas/eaos-core, @alneas/eaos-core/ai, @alneas/eaos-core/ai/anomaly.

Signature

interface AIAnomalyConfig {
    minSamples?: number;
    sensitivity?: number;
    algorithms?: readonly AIAnomalyAlgorithm[];
    ewmaAlpha?: number;
}

Parameters

Name	Type	Required	Description
`minSamples`	`number`	No	Minimum historical points, from 2 to 10000; defaults to 30 and excludes the latest point.
`sensitivity`	`number`	No	Detector sensitivity strictly between zero and one; defaults to 0.95 for z-score thresholds.
`algorithms`	`readonly AIAnomalyAlgorithm[]`	No	Detector order; defaults to zscore and iqr. Current validation rejects ewma despite its declared type.
`ewmaAlpha`	`number`	No	EWMA smoothing factor greater than zero and at most one; defaults to 0.3, though ewma selection is currently rejected.

Returns

Type declaration; no runtime value.

Public members

`minSamples`

Minimum historical points, from 2 to 10000; defaults to 30 and excludes the latest point.

`sensitivity`

Detector sensitivity strictly between zero and one; defaults to 0.95 for z-score thresholds.

`algorithms`

Detector order; defaults to zscore and iqr. Current validation rejects ewma despite its declared type.

`ewmaAlpha`

EWMA smoothing factor greater than zero and at most one; defaults to 0.3, though ewma selection is currently rejected.

Example

See the owning declaration and linked feature guide for usage; no standalone example is documented in source.

[INTERFACE] `AIAnomalyExpectedRange`

Estimated history envelope and population mean/standard deviation.

Imports: @alneas/eaos-core, @alneas/eaos-core/ai, @alneas/eaos-core/ai/anomaly.

Signature

interface AIAnomalyExpectedRange {
    min: number;
    max: number;
    mean: number;
    stdDev: number;
}

Parameters

Name	Type	Required	Description
`min`	`number`	Yes	Estimated lower history bound for the detector output.
`max`	`number`	Yes	Estimated upper history bound for the detector output.
`mean`	`number`	Yes	Arithmetic mean of the history used for the detector result.
`stdDev`	`number`	Yes	Population standard deviation of the history used for the detector result.

Returns

Type declaration; no runtime value.

Public members

`min`

Estimated lower history bound for the detector output.

`max`

Estimated upper history bound for the detector output.

`mean`

Arithmetic mean of the history used for the detector result.

`stdDev`

Population standard deviation of the history used for the detector result.

Example

See the owning declaration and linked feature guide for usage; no standalone example is documented in source.

[INTERFACE] `AIAnomalyResult`

One detector outcome for the latest point with bounded score and optional diagnostics.

Imports: @alneas/eaos-core, @alneas/eaos-core/ai, @alneas/eaos-core/ai/anomaly.

Signature

interface AIAnomalyResult {
    detected: boolean;
    algorithm: AIAnomalyAlgorithm;
    metric: string;
    timestamp: number;
    value: number;
    score: number;
    severity: AIAnomalySeverity;
    expectedRange?: AIAnomalyExpectedRange;
    details?: Readonly<Record<string, number>>;
}

Parameters

Name	Type	Required	Description
`detected`	`boolean`	Yes	Whether the latest value crosses the selected detector threshold.
`algorithm`	`AIAnomalyAlgorithm`	Yes	Detector that produced this result.
`metric`	`string`	Yes	Nonempty metric label used to correlate the detector result.
`timestamp`	`number`	Yes	Timestamp coordinate copied from the latest metric point, in the input metric units.
`value`	`number`	Yes	Latest observation value copied into this detector result.
`score`	`number`	Yes	Provider/detector relevance or anomaly score; interpret using the owning result contract.
`severity`	`AIAnomalySeverity`	Yes	Handling/alert severity attached to the classified error or detector result.
`expectedRange`	`AIAnomalyExpectedRange`	No	Optional estimated history envelope; absent for insufficient samples.
`details`	`Readonly<Record<string, number>>`	No	Optional numeric diagnostics, including sample counts or detector threshold components.

Returns

Type declaration; no runtime value.

Public members

`detected`

Whether the latest value crosses the selected detector threshold.

`algorithm`

Detector that produced this result.

`metric`

Nonempty metric label used to correlate the detector result.

`timestamp`

Timestamp coordinate copied from the latest metric point, in the input metric units.

`value`

Latest observation value copied into this detector result.

`score`

Provider/detector relevance or anomaly score; interpret using the owning result contract.

`severity`

Handling/alert severity attached to the classified error or detector result.

`expectedRange`

Optional estimated history envelope; absent for insufficient samples.

`details`

Optional numeric diagnostics, including sample counts or detector threshold components.

Example

See the owning declaration and linked feature guide for usage; no standalone example is documented in source.

[TYPE] `AIAnomalySeverity`

Severity derived from the detector threshold ratio.

Imports: @alneas/eaos-core, @alneas/eaos-core/ai, @alneas/eaos-core/ai/anomaly.

Signature

type AIAnomalySeverity = 'info' | 'warning' | 'critical';

Parameters

Name	Type	Required	Description
—	—	—	No call parameters.

Returns

Type declaration; no runtime value.

Example

See the owning declaration and linked feature guide for usage; no standalone example is documented in source.

[TYPE] `AIBrowserAction`

Navigate, interact, wait or capture actions interpreted by a browser host.

Imports: @alneas/eaos-core, @alneas/eaos-core/ai, @alneas/eaos-core/ai/host-adapters.

Signature

type AIBrowserAction = {
    type: 'navigate';
    url: string;
} | {
    type: 'click';
    selector: string;
} | {
    type: 'fill';
    selector: string;
    value: string;
} | {
    type: 'select';
    selector: string;
    value: string;
} | {
    type: 'waitFor';
    selector: string;
    timeoutMs?: number;
} | {
    type: 'screenshot';
    fullPage?: boolean;
} | {
    type: 'pdf';
};

Parameters

Name	Type	Required	Description
—	—	—	No call parameters.

Returns

Type declaration; no runtime value.

Public members

`type`

Browser action discriminator selecting navigation, interaction, waiting or capture fields.

`url`

Target/observed HTTP(S) location; adapter/host authorization must restrict navigation and delivery.

`type`

Browser action discriminator selecting navigation, interaction, waiting or capture fields.

`selector`

Element selector interpreted within the authorized browser session.

`type`

Browser action discriminator selecting navigation, interaction, waiting or capture fields.

`selector`

Element selector interpreted within the authorized browser session.

`value`

Text value to fill or option value to select in the authorized browser page.

`type`

Browser action discriminator selecting navigation, interaction, waiting or capture fields.

`selector`

Element selector interpreted within the authorized browser session.

`value`

Text value to fill or option value to select in the authorized browser page.

`type`

Browser action discriminator selecting navigation, interaction, waiting or capture fields.

`selector`

Element selector interpreted within the authorized browser session.

`timeoutMs`

Optional execution deadline in milliseconds; enforcement belongs to the API/runtime consuming this metadata.

`type`

Browser action discriminator selecting navigation, interaction, waiting or capture fields.

`fullPage`

Optional request for full-page capture; omission uses the host browser default.

`type`

Browser action discriminator selecting navigation, interaction, waiting or capture fields.

Example

See the owning declaration and linked feature guide for usage; no standalone example is documented in source.

[INTERFACE] `AIBrowserAdapter`

Host-owned scoped browser session lifecycle and admitted interactions.

Imports: @alneas/eaos-core, @alneas/eaos-core/ai, @alneas/eaos-core/ai/host-adapters.

Signature

interface AIBrowserAdapter extends AIHostAdapter {
    openSession(input: {
        origin: string;
    }, context: AIHostActionContext): Promise<AIHostResult<AIBrowserSession>>;
    snapshot(input: {
        sessionId: string;
    }, context: AIExecutionContext): Promise<AIBrowserSnapshot>;
    execute(input: {
        sessionId: string;
        actions: readonly AIBrowserAction[];
    }, context: AIHostActionContext): Promise<AIHostResult<AIBrowserSnapshot>>;
    closeSession(input: {
        sessionId: string;
    }, context: AIHostActionContext): Promise<AIHostResult<unknown>>;
}

Parameters

Name	Type	Required	Description
`openSession`	`Promise<AIHostResult<AIBrowserSession>>`	Yes	Request a host browser session restricted to an approved origin.
`snapshot`	`Promise<AIBrowserSnapshot>`	Yes	Read current page metadata from an authorized host browser session.
`execute`	`Promise<AIHostResult<AIBrowserSnapshot>>`	Yes	Request an admitted ordered browser action sequence.
`closeSession`	`Promise<AIHostResult<unknown>>`	Yes	Request cleanup of a host browser session.

Returns

Type declaration; no runtime value.

Public members

`openSession`

Request a host browser session restricted to an approved origin.

Parameters:

input: Initial origin; host validates its origin allowlist and browser authorization.
context: Verified host scope plus replay key and optional review/deadline/dry-run metadata.

Returns: Optional session identity/allowed origins and host receipt; caller later closes accepted sessions.

Remarks

Requires a real host implementation and trusted execution context; Core supplies no provider credentials, default count limits or cancellation policy. The host enforces approval/deadline/dryRun/idempotency and owns durable receipts; reconcile uncertain outcomes before replaying an effect.

Errors and rejections

Host implementation errors/rejections propagate; successful Promise resolution must still be interpreted through the returned result/receipt.

Example:

import type { AIBrowserAdapter, AIHostActionContext } from "@alneas/eaos-core/ai/host-adapters";
async function useHost(adapter: AIBrowserAdapter, context: AIHostActionContext) {
 const opened = await adapter.openSession({ origin: "https://example.com" }, context);
 if (opened.receipt.status !== "completed" || !opened.value) return opened;
 const sessionId = opened.value.sessionId;
 try {
  return await adapter.snapshot({ sessionId }, context.context);
 } finally {
  await adapter.closeSession({ sessionId }, { ...context, idempotencyKey: context.idempotencyKey + ":close" });
 }
}

`openSession.input.origin`

Initial HTTP(S) origin that the host must admit into the browser session allowlist.

`snapshot`

Read current page metadata from an authorized host browser session.

Parameters:

input: Existing browser session identity.
context: Verified host scope used for tenant/user access checks.

Returns: Current URL and optional title/text/screenshot reference.

Remarks

Requires a real host implementation and trusted execution context; Core supplies no provider credentials, default count limits or cancellation policy.

Errors and rejections

Host implementation errors/rejections propagate; successful Promise resolution must still be interpreted through the returned result/receipt.

Example:

import type { AIBrowserAdapter } from "@alneas/eaos-core/ai/host-adapters";
import type { AIExecutionContext } from "@alneas/eaos-core/ai/governance";
async function useHost(adapter: AIBrowserAdapter, context: AIExecutionContext) {
 return adapter.snapshot({ sessionId: "session-1" }, context);
}

`snapshot.input.sessionId`

Host session identity used to correlate lifecycle callbacks and operations.

`execute`

Request an admitted ordered browser action sequence.

Parameters:

input: Existing session and navigation/interaction/capture actions; wait timeout is milliseconds.
context: Verified host scope plus replay key and optional review/deadline/dry-run metadata.

Returns: Optional resulting snapshot and host receipt; partial action completion is provider-defined.

Remarks

Errors and rejections

Host implementation errors/rejections propagate; successful Promise resolution must still be interpreted through the returned result/receipt.

Example:

import type { AIBrowserAdapter, AIHostActionContext } from "@alneas/eaos-core/ai/host-adapters";
async function useHost(adapter: AIBrowserAdapter, context: AIHostActionContext) {
 return adapter.execute({ sessionId: "session-1", actions: [{ type: "screenshot", fullPage: false }] }, context);
}

`execute.input.sessionId`

Host session identity used to correlate lifecycle callbacks and operations.

`execute.input.actions`

Ordered proposed actions; the host must validate and authorize them before any side effect.

`closeSession`

Request cleanup of a host browser session.

Parameters:

input: Existing session identity to release.
context: Verified host scope plus replay key and optional review/deadline/dry-run metadata.

Returns: Host receipt plus optional provider cleanup data.

Remarks

Errors and rejections

Host implementation errors/rejections propagate; successful Promise resolution must still be interpreted through the returned result/receipt.

Example:

import type { AIBrowserAdapter, AIHostActionContext } from "@alneas/eaos-core/ai/host-adapters";
async function useHost(adapter: AIBrowserAdapter, context: AIHostActionContext) {
 return adapter.closeSession({ sessionId: "session-1" }, context);
}

`closeSession.input.sessionId`

Host session identity used to correlate lifecycle callbacks and operations.

Example

See the owning declaration and linked feature guide for usage; no standalone example is documented in source.

[INTERFACE] `AIBrowserSession`

Browser session identity and the origins permitted by its host.

Imports: @alneas/eaos-core, @alneas/eaos-core/ai, @alneas/eaos-core/ai/host-adapters.

Signature

interface AIBrowserSession {
    sessionId: string;
    allowedOrigins: readonly string[];
}

Parameters

Name	Type	Required	Description
`sessionId`	`string`	Yes	Host session identity used to correlate lifecycle callbacks and operations.
`allowedOrigins`	`readonly string[]`	Yes	Origins permitted by the browser host for this session.

Returns

Type declaration; no runtime value.

Public members

`sessionId`

Host session identity used to correlate lifecycle callbacks and operations.

`allowedOrigins`

Origins permitted by the browser host for this session.

Example

See the owning declaration and linked feature guide for usage; no standalone example is documented in source.

[INTERFACE] `AIBrowserSnapshot`

Current browser URL and optional title, text and screenshot reference.

Imports: @alneas/eaos-core, @alneas/eaos-core/ai, @alneas/eaos-core/ai/host-adapters.

Signature

interface AIBrowserSnapshot {
    url: string;
    title?: string;
    text?: string;
    screenshotRef?: string;
}

Parameters

Name	Type	Required	Description
`url`	`string`	Yes	Target/observed HTTP(S) location; adapter/host authorization must restrict navigation and delivery.
`title`	`string`	No	Human-readable draft, task, file or event title displayed by the host.
`text`	`string`	No	Plain-text message/browser content; treat provider text as untrusted data.
`screenshotRef`	`string`	No	Optional host-managed reference to captured image data.

Returns

Type declaration; no runtime value.

Public members

`url`

Target/observed HTTP(S) location; adapter/host authorization must restrict navigation and delivery.

`title`

Human-readable draft, task, file or event title displayed by the host.

`text`

Plain-text message/browser content; treat provider text as untrusted data.

`screenshotRef`

Optional host-managed reference to captured image data.

Example

See the owning declaration and linked feature guide for usage; no standalone example is documented in source.

[INTERFACE] `AIBudgetDecision`

Host budget admission decision with optional throttle/retry guidance.

Imports: @alneas/eaos-core, @alneas/eaos-core/ai, @alneas/eaos-core/ai/governance.

Signature

interface AIBudgetDecision {
    allowed: boolean;
    reason?: string;
    throttled?: boolean;
    retryAfterMs?: number;
}

Parameters

Name	Type	Required	Description
`allowed`	`boolean`	Yes	Admission/check decision; consumers must inspect it before using the associated result or performing an effect.
`reason`	`string`	No	Human-readable explanation of the decision or requested action.
`throttled`	`boolean`	No	Optional indication that budget/capacity policy temporarily deferred execution.
`retryAfterMs`	`number`	No	Optional host guidance for when capacity/budget may be retried, in milliseconds.

Returns

Type declaration; no runtime value.

Public members

`allowed`

Admission/check decision; consumers must inspect it before using the associated result or performing an effect.

`reason`

Human-readable explanation of the decision or requested action.

`throttled`

Optional indication that budget/capacity policy temporarily deferred execution.

`retryAfterMs`

Optional host guidance for when capacity/budget may be retried, in milliseconds.

Example

See the owning declaration and linked feature guide for usage; no standalone example is documented in source.

[INTERFACE] `AIBudgetGate`

Budget enforcement is a policy port; Redis/SQL/accounting remain host-owned.

Imports: @alneas/eaos-core, @alneas/eaos-core/ai, @alneas/eaos-core/ai/governance.

Signature

interface AIBudgetGate {
    authorize(input: {
        context: AIExecutionContext;
        usage?: AIUsage;
    }): Promise<AIBudgetDecision> | AIBudgetDecision;
    recordUsage?(input: {
        context: AIExecutionContext;
        usage: AIUsage;
    }): Promise<void> | void;
}

Parameters

Name	Type	Required	Description
`authorize`	`Promise<AIBudgetDecision> \| AIBudgetDecision`	Yes	Ask host budget policy whether model work may proceed.
`recordUsage`	`Promise<void> \| void`	No	Report usage to optional host accounting after execution.

Returns

Type declaration; no runtime value.

Public members

`authorize`

Ask host budget policy whether model work may proceed.

Parameters:

input: Verified scope and optional estimated/reported usage.

Returns: Admission/throttle/retry guidance, directly or asynchronously.

Remarks

Host owns reservation/accounting, concurrency and enforcement; an allowed decision alone is not a framework reservation.

Errors and rejections

Host policy errors/rejections propagate.

Example:

import type { AIBudgetGate } from "@alneas/eaos-core/ai/governance";
async function checkHostBudget(gate: AIBudgetGate, input: Parameters<AIBudgetGate["authorize"]>[0]) { return gate.authorize(input); }

`authorize.input.context`

Verified host execution scope propagated to adapters/guards/hooks; callers must establish identity and authorization before use.

`authorize.input.usage`

Optional token/cost telemetry reported by a host/runtime; absence does not mean zero use.

`recordUsage`

Report usage to optional host accounting after execution.

Parameters:

input: Verified scope and measured/reported usage to record.

Returns: No value; returned Promise completion means the host accounting callback completed.

Remarks

Optional host accounting port; retry/deduplication semantics must be defined by the implementation.

Errors and rejections

Host accounting errors/rejections propagate.

Example:

import type { AIBudgetGate } from "@alneas/eaos-core/ai/governance";
async function recordHostUsage(gate: AIBudgetGate, input: Parameters<NonNullable<AIBudgetGate["recordUsage"]>>[0]) {
 if (!gate.recordUsage) throw new Error("Host usage accounting is unavailable");
 await gate.recordUsage(input);
}

`recordUsage.input.context`

Verified host execution scope propagated to adapters/guards/hooks; callers must establish identity and authorization before use.

`recordUsage.input.usage`

Optional token/cost telemetry reported by a host/runtime; absence does not mean zero use.

Example

See the owning declaration and linked feature guide for usage; no standalone example is documented in source.

[INTERFACE] `AICalendarAdapter`

Host-owned calendar reads and replay-safe event mutations.

Imports: @alneas/eaos-core, @alneas/eaos-core/ai, @alneas/eaos-core/ai/host-adapters.

Signature

interface AICalendarAdapter extends AIHostAdapter {
    listEvents(input: {
        from: string;
        to: string;
        calendarIds?: readonly string[];
    }, context: AIExecutionContext): Promise<readonly AICalendarEvent[]>;
    findAvailability(input: {
        from: string;
        to: string;
        durationMinutes: number;
        calendarIds?: readonly string[];
    }, context: AIExecutionContext): Promise<readonly AICalendarAvailability[]>;
    createEvent(input: AICalendarEvent, context: AIHostActionContext): Promise<AIHostResult<AICalendarEvent>>;
    updateEvent(input: AICalendarEvent & {
        id: string;
    }, context: AIHostActionContext): Promise<AIHostResult<AICalendarEvent>>;
    cancelEvent(input: {
        id: string;
        reason?: string;
    }, context: AIHostActionContext): Promise<AIHostResult<unknown>>;
}

Parameters

Name	Type	Required	Description
`listEvents`	`Promise<readonly AICalendarEvent[]>`	Yes	List authorized calendar events in a requested time window.
`findAvailability`	`Promise<readonly AICalendarAvailability[]>`	Yes	Read busy intervals for an availability search.
`createEvent`	`Promise<AIHostResult<AICalendarEvent>>`	Yes	Request creation of an event through the admitted calendar host.
`updateEvent`	`Promise<AIHostResult<AICalendarEvent>>`	Yes	Request an admitted update to an existing calendar event.
`cancelEvent`	`Promise<AIHostResult<unknown>>`	Yes	Request cancellation of an authorized calendar event.

Returns

Type declaration; no runtime value.

Public members

`listEvents`

List authorized calendar events in a requested time window.

Parameters:

input: Window start/end and optional calendar IDs; provider defines interval boundaries and default calendars.
context: Verified host scope used for tenant/user access checks.

Returns: The matching event array, possibly empty.

Remarks

Requires a real host implementation and trusted execution context; Core supplies no provider credentials, default count limits or cancellation policy.

Errors and rejections

Host implementation errors/rejections propagate; successful Promise resolution must still be interpreted through the returned result/receipt.

Example:

import type { AICalendarAdapter } from "@alneas/eaos-core/ai/host-adapters";
import type { AIExecutionContext } from "@alneas/eaos-core/ai/governance";
async function useHost(adapter: AICalendarAdapter, context: AIExecutionContext) {
 return adapter.listEvents({ from: "2026-10-19T00:00:00Z", to: "2026-10-20T00:00:00Z" }, context);
}

`listEvents.input.from`

Start timestamp of the calendar query window; host provider defines inclusivity and timezone handling.

`listEvents.input.to`

End timestamp of the calendar query window; host provider defines inclusivity and timezone handling.

`listEvents.input.calendarIds`

Optional calendars within the authorized host account; omission uses adapter-defined selection.

`findAvailability`

Read busy intervals for an availability search.

Parameters:

input: Window, requested duration in minutes and optional calendar IDs; host validates bounds.
context: Verified host scope used for tenant/user access checks.

Returns: Calendar busy-interval arrays; empty when none are returned.

Remarks

Requires a real host implementation and trusted execution context; Core supplies no provider credentials, default count limits or cancellation policy.

Errors and rejections

Host implementation errors/rejections propagate; successful Promise resolution must still be interpreted through the returned result/receipt.

Example:

import type { AICalendarAdapter } from "@alneas/eaos-core/ai/host-adapters";
import type { AIExecutionContext } from "@alneas/eaos-core/ai/governance";
async function useHost(adapter: AICalendarAdapter, context: AIExecutionContext) {
 return adapter.findAvailability({ from: "2026-10-19T00:00:00Z", to: "2026-10-20T00:00:00Z", durationMinutes: 30 }, context);
}

`findAvailability.input.from`

Start timestamp of the calendar query window; host provider defines inclusivity and timezone handling.

`findAvailability.input.to`

End timestamp of the calendar query window; host provider defines inclusivity and timezone handling.

`findAvailability.input.durationMinutes`

Requested availability duration in minutes; adapter validates its supported bounds.

`findAvailability.input.calendarIds`

Optional calendars within the authorized host account; omission uses adapter-defined selection.

`createEvent`

Request creation of an event through the admitted calendar host.

Parameters:

input: Event title/time range and optional attendee/location/reminder metadata.
context: Verified host scope plus replay key and optional review/deadline/dry-run metadata.

Returns: Optional created event plus an authoritative receipt; acceptance may remain pending.

Remarks

Errors and rejections

Host implementation errors/rejections propagate; successful Promise resolution must still be interpreted through the returned result/receipt.

Example:

import type { AICalendarAdapter, AIHostActionContext } from "@alneas/eaos-core/ai/host-adapters";
async function useHost(adapter: AICalendarAdapter, context: AIHostActionContext) {
 return adapter.createEvent({ title: "Review", start: "2026-10-19T10:00:00Z", end: "2026-10-19T10:30:00Z" }, context);
}

`updateEvent`

Request an admitted update to an existing calendar event.

Parameters:

input: Existing event ID and replacement/update fields interpreted by the provider.
context: Verified host scope plus replay key and optional review/deadline/dry-run metadata.

Returns: Optional updated event and host receipt; inspect receipt status before assuming completion.

Remarks

Errors and rejections

Host implementation errors/rejections propagate; successful Promise resolution must still be interpreted through the returned result/receipt.

Example:

import type { AICalendarAdapter, AIHostActionContext } from "@alneas/eaos-core/ai/host-adapters";
async function useHost(adapter: AICalendarAdapter, context: AIHostActionContext) {
 return adapter.updateEvent({ id: "event-1", title: "Review", start: "2026-10-19T10:00:00Z", end: "2026-10-19T10:30:00Z" }, context);
}

`updateEvent.input.id`

Existing provider event identity to update within authorized calendars.

`cancelEvent`

Request cancellation of an authorized calendar event.

Parameters:

input: Existing event ID and optional human-readable cancellation reason.
context: Verified host scope plus replay key and optional review/deadline/dry-run metadata.

Returns: Host receipt and optional provider result; completion is receipt-driven.

Remarks

Errors and rejections

Host implementation errors/rejections propagate; successful Promise resolution must still be interpreted through the returned result/receipt.

Example:

import type { AICalendarAdapter, AIHostActionContext } from "@alneas/eaos-core/ai/host-adapters";
async function useHost(adapter: AICalendarAdapter, context: AIHostActionContext) {
 return adapter.cancelEvent({ id: "event-1", reason: "Rescheduled" }, context);
}

`cancelEvent.input.id`

Existing provider event identity to cancel within authorized calendars.

`cancelEvent.input.reason`

Human-readable explanation of the decision or requested action.

Example

See the owning declaration and linked feature guide for usage; no standalone example is documented in source.

[INTERFACE] `AICalendarAvailability`

Busy intervals for a calendar over a host-selected window.

Imports: @alneas/eaos-core, @alneas/eaos-core/ai, @alneas/eaos-core/ai/host-adapters.

Signature

interface AICalendarAvailability {
    calendarId: string;
    busy: readonly {
        start: string;
        end: string;
    }[];
}

Parameters

Name	Type	Required	Description
`calendarId`	`string`	Yes	Calendar identity within the authorized host account.
`busy`	`readonly { start: string; end: string; }[]`	Yes	Provider-reported busy intervals with start/end timestamps.

Returns

Type declaration; no runtime value.

Public members

`calendarId`

Calendar identity within the authorized host account.

`busy`

Provider-reported busy intervals with start/end timestamps.

`busy[].start`

Start timestamp of a provider-reported busy interval.

`busy[].end`

End timestamp of a provider-reported busy interval.

Example

See the owning declaration and linked feature guide for usage; no standalone example is documented in source.

[INTERFACE] `AICalendarEvent`

Provider-neutral calendar event fields for reads and mutations.

Imports: @alneas/eaos-core, @alneas/eaos-core/ai, @alneas/eaos-core/ai/host-adapters.

Signature

interface AICalendarEvent {
    id?: string;
    title: string;
    start: string;
    end: string;
    timeZone?: string;
    attendees?: readonly string[];
    location?: string;
    description?: string;
    remindersMinutes?: readonly number[];
}

Parameters

Name	Type	Required	Description
`id`	`string`	No	Existing provider event identity; optional when proposing creation.
`title`	`string`	Yes	Human-readable draft, task, file or event title displayed by the host.
`start`	`string`	Yes	Event start timestamp interpreted with the optional event timezone by the host calendar provider.
`end`	`string`	Yes	Event end timestamp; the host calendar provider validates ordering and timezone semantics.
`timeZone`	`string`	No	Optional timezone identifier used by the calendar provider.
`attendees`	`readonly string[]`	No	Optional attendee addresses/identities accepted by the host calendar provider.
`location`	`string`	No	Optional event location text.
`description`	`string`	No	Human-readable metadata describing the capability, workflow node or requirement to host users.
`remindersMinutes`	`readonly number[]`	No	Optional reminder offsets in minutes as interpreted by the calendar provider.

Returns

Type declaration; no runtime value.

Public members

`id`

Existing provider event identity; optional when proposing creation.

`title`

Human-readable draft, task, file or event title displayed by the host.

`start`

Event start timestamp interpreted with the optional event timezone by the host calendar provider.

`end`

Event end timestamp; the host calendar provider validates ordering and timezone semantics.

`timeZone`

Optional timezone identifier used by the calendar provider.

`attendees`

Optional attendee addresses/identities accepted by the host calendar provider.

`location`

Optional event location text.

`description`

Human-readable metadata describing the capability, workflow node or requirement to host users.

`remindersMinutes`

Optional reminder offsets in minutes as interpreted by the calendar provider.

Example

See the owning declaration and linked feature guide for usage; no standalone example is documented in source.

[CLASS] `AiCircuitBreaker`

Track local provider failures and select a preferred available provider.

Imports: @alneas/eaos-core/agent/circuit-breaker.

Signature

declare class AiCircuitBreaker {
    constructor(fallbackPriority?: AiProvider[]);
    recordSuccess(provider: AiProvider): void;
    recordFailure(provider: AiProvider): void;
    getHealthyProvider(): AiProvider;
    getHealthStatus(): ProviderHealth[];
}

Parameters

Name	Type	Required	Description
`fallbackPriority`	`AiProvider[]`	No	Priority list stored by reference; defaults to gemini, openai, claude, workers-ai, ollama. Supply a nonempty list.

Returns

AiCircuitBreaker

Remarks

Three recorded failures open a provider; a selection more than 30000 ms after its latest failure marks it HALF_OPEN. It does not schedule probes, execute requests, constrain concurrent half-open requests or coordinate across processes. When all providers remain open it still returns the first priority provider; an empty priority list yields undefined at runtime despite the declared return type.

Constructor contract

Public members

`recordSuccess`

Reset a registered provider failure count and close its circuit.

Parameters:

provider: Provider identifier registered by the constructor.

Returns: No value; unregistered providers are ignored.

Example:

import { AiCircuitBreaker } from "@alneas/eaos-core/agent/circuit-breaker";
const breaker = new AiCircuitBreaker(["openai"]);
breaker.recordSuccess("openai");

`recordFailure`

Increment failures and record the time, opening the circuit at three failures.

Parameters:

provider: Provider identifier registered by the constructor.

Returns: No value; unregistered providers are ignored.

Example:

import { AiCircuitBreaker } from "@alneas/eaos-core/agent/circuit-breaker";
const breaker = new AiCircuitBreaker(["openai"]);
breaker.recordFailure("openai");

`getHealthyProvider`

Select the first closed/half-open provider, or one whose open cooldown elapsed.

Returns: Preferred provider; first priority is used even when all are degraded.

Remarks

Selection may transition one open circuit to HALF_OPEN; caller records subsequent success/failure.

Example:

import { AiCircuitBreaker } from "@alneas/eaos-core/agent/circuit-breaker";
const breaker = new AiCircuitBreaker(["openai"]);
console.log(breaker.getHealthyProvider());

`getHealthStatus`

Expose current tracked provider health records.

Returns: A new array containing the original mutable health objects.

Remarks

Mutating a returned health object changes breaker state.

Example:

import { AiCircuitBreaker } from "@alneas/eaos-core/agent/circuit-breaker";
const breaker = new AiCircuitBreaker(["openai"]);
console.log(breaker.getHealthStatus());

Example

import { AiCircuitBreaker } from "@alneas/eaos-core/agent/circuit-breaker";
const breaker = new AiCircuitBreaker(["openai", "gemini"]);
breaker.recordFailure("openai");
console.log(breaker.getHealthyProvider());

[TYPE] `AIDataSensitivityLevel`

Data classification used to select an approved model route.

Imports: @alneas/eaos-core, @alneas/eaos-core/ai, @alneas/eaos-core/ai/governance.

Signature

type AIDataSensitivityLevel = 'level1_public' | 'level2_internal' | 'level3_strict';

Parameters

Name	Type	Required	Description
—	—	—	No call parameters.

Returns

Type declaration; no runtime value.

Example

See the owning declaration and linked feature guide for usage; no standalone example is documented in source.

[INTERFACE] `AIEmailAdapter`

Host-owned message reads, label changes, draft creation and sending.

Imports: @alneas/eaos-core, @alneas/eaos-core/ai, @alneas/eaos-core/ai/host-adapters.

Signature

interface AIEmailAdapter extends AIHostAdapter {
    searchMessages(input: {
        query: string;
        limit?: number;
    }, context: AIExecutionContext): Promise<readonly AIEmailMessage[]>;
    getMessage(input: {
        id: string;
    }, context: AIExecutionContext): Promise<AIEmailMessage | null>;
    applyLabels(input: {
        messageId: string;
        add?: readonly string[];
        remove?: readonly string[];
    }, context: AIHostActionContext): Promise<AIHostResult<unknown>>;
    createDraft(input: AIEmailDraft, context: AIHostActionContext): Promise<AIHostResult<AIEmailDraft>>;
    sendDraft(input: {
        draftId: string;
    }, context: AIHostActionContext): Promise<AIHostResult<AIEmailMessage>>;
}

Parameters

Name	Type	Required	Description
`searchMessages`	`Promise<readonly AIEmailMessage[]>`	Yes	Search messages in the authorized mail scope.
`getMessage`	`Promise<AIEmailMessage \| null>`	Yes	Read one authorized email message by provider identity.
`applyLabels`	`Promise<AIHostResult<unknown>>`	Yes	Request admitted label changes on an email message.
`createDraft`	`Promise<AIHostResult<AIEmailDraft>>`	Yes	Request a draft without implicitly sending it.
`sendDraft`	`Promise<AIHostResult<AIEmailMessage>>`	Yes	Request delivery of an existing host-owned mail draft.

Returns

Type declaration; no runtime value.

Public members

`searchMessages`

Search messages in the authorized mail scope.

Parameters:

input: Provider query and optional count limit; syntax/defaults remain adapter-owned.
context: Verified host scope used for tenant/user access checks.

Returns: Matching message metadata/content, possibly empty.

Remarks

Requires a real host implementation and trusted execution context; Core supplies no provider credentials, default count limits or cancellation policy.

Errors and rejections

Host implementation errors/rejections propagate; successful Promise resolution must still be interpreted through the returned result/receipt.

Example:

import type { AIEmailAdapter } from "@alneas/eaos-core/ai/host-adapters";
import type { AIExecutionContext } from "@alneas/eaos-core/ai/governance";
async function useHost(adapter: AIEmailAdapter, context: AIExecutionContext) {
 return adapter.searchMessages({ query: "subject:review", limit: 10 }, context);
}

`searchMessages.input.query`

Provider/host query text; syntax, authorization and limits are adapter-owned.

`searchMessages.input.limit`

Optional result-count bound; default and maximum are owned by the connected adapter.

`getMessage`

Read one authorized email message by provider identity.

Parameters:

input: Existing provider message ID.
context: Verified host scope used for tenant/user access checks.

Returns: Message when available, otherwise null.

Remarks

Requires a real host implementation and trusted execution context; Core supplies no provider credentials, default count limits or cancellation policy.

Errors and rejections

Host implementation errors/rejections propagate; successful Promise resolution must still be interpreted through the returned result/receipt.

Example:

import type { AIEmailAdapter } from "@alneas/eaos-core/ai/host-adapters";
import type { AIExecutionContext } from "@alneas/eaos-core/ai/governance";
async function useHost(adapter: AIEmailAdapter, context: AIExecutionContext) {
 return adapter.getMessage({ id: "message-1" }, context);
}

`getMessage.input.id`

Provider message identity within the authorized mail account.

`applyLabels`

Request admitted label changes on an email message.

Parameters:

input: Message ID and optional labels to add/remove; provider owns conflict semantics.
context: Verified host scope plus replay key and optional review/deadline/dry-run metadata.

Returns: Host receipt and optional provider result.

Remarks

Errors and rejections

Host implementation errors/rejections propagate; successful Promise resolution must still be interpreted through the returned result/receipt.

Example:

import type { AIEmailAdapter, AIHostActionContext } from "@alneas/eaos-core/ai/host-adapters";
async function useHost(adapter: AIEmailAdapter, context: AIHostActionContext) {
 return adapter.applyLabels({ messageId: "message-1", add: ["reviewed"] }, context);
}

`applyLabels.input.messageId`

Existing message identity within the authorized mail account.

`applyLabels.input.add`

Optional labels to add to the selected message.

`applyLabels.input.remove`

Optional labels to remove from the selected message.

`createDraft`

Request a draft without implicitly sending it.

Parameters:

input: Recipients, subject/body and optional reply metadata.
context: Verified host scope plus replay key and optional review/deadline/dry-run metadata.

Returns: Optional created draft and host receipt; sending requires a separate admitted action.

Remarks

Errors and rejections

Host implementation errors/rejections propagate; successful Promise resolution must still be interpreted through the returned result/receipt.

Example:

import type { AIEmailAdapter, AIHostActionContext } from "@alneas/eaos-core/ai/host-adapters";
async function useHost(adapter: AIEmailAdapter, context: AIHostActionContext) {
 return adapter.createDraft({ to: ["[email protected]"], subject: "Review", bodyText: "Please review the draft." }, context);
}

`sendDraft`

Request delivery of an existing host-owned mail draft.

Parameters:

input: Previously created draft identity; the host must verify send authorization.
context: Verified host scope plus replay key and optional review/deadline/dry-run metadata.

Returns: Optional sent message plus receipt; accepted/pending are not proof of delivery.

Remarks

Errors and rejections

Host implementation errors/rejections propagate; successful Promise resolution must still be interpreted through the returned result/receipt.

Example:

import type { AIEmailAdapter, AIHostActionContext } from "@alneas/eaos-core/ai/host-adapters";
async function useHost(adapter: AIEmailAdapter, context: AIHostActionContext) {
 return adapter.sendDraft({ draftId: "draft-1" }, context);
}

`sendDraft.input.draftId`

Previously created mail draft identity to send through the admitted host action.

Example

See the owning declaration and linked feature guide for usage; no standalone example is documented in source.

[INTERFACE] `AIEmailDraft`

Draft recipients, subject and plain-text body, optionally tied to a reply.

Imports: @alneas/eaos-core, @alneas/eaos-core/ai, @alneas/eaos-core/ai/host-adapters.

Signature

interface AIEmailDraft {
    id?: string;
    replyToMessageId?: string;
    to: readonly string[];
    cc?: readonly string[];
    subject: string;
    bodyText: string;
}

Parameters

Name	Type	Required	Description
`id`	`string`	No	Optional provider draft identity, normally populated after host draft creation.
`replyToMessageId`	`string`	No	Optional existing message identity used when constructing a reply draft.
`to`	`readonly string[]`	Yes	Intended recipient addresses; the host must authorize any later send.
`cc`	`readonly string[]`	No	Optional copy-recipient addresses; host applies delivery authorization.
`subject`	`string`	Yes	Email subject text passed to or returned by the host provider.
`bodyText`	`string`	Yes	Plain-text email content; provider rendering and delivery policy remain host-owned.

Returns

Type declaration; no runtime value.

Public members

`id`

Optional provider draft identity, normally populated after host draft creation.

`replyToMessageId`

Optional existing message identity used when constructing a reply draft.

`to`

Intended recipient addresses; the host must authorize any later send.

`cc`

Optional copy-recipient addresses; host applies delivery authorization.

`subject`

Email subject text passed to or returned by the host provider.

`bodyText`

Plain-text email content; provider rendering and delivery policy remain host-owned.

Example

See the owning declaration and linked feature guide for usage; no standalone example is documented in source.

[INTERFACE] `AIEmailMessage`

Provider-neutral email message metadata and optional plain-text content.

Imports: @alneas/eaos-core, @alneas/eaos-core/ai, @alneas/eaos-core/ai/host-adapters.

Signature

interface AIEmailMessage {
    id: string;
    threadId?: string;
    from: string;
    to: readonly string[];
    subject: string;
    receivedAt: string;
    bodyText?: string;
    labels?: readonly string[];
}

Parameters

Name	Type	Required	Description
`id`	`string`	Yes	Provider message identity used for reads, replies and label actions.
`threadId`	`string`	No	Host conversation/thread identity for correlation.
`from`	`string`	Yes	Sender address/identity reported by the mail provider.
`to`	`readonly string[]`	Yes	Recipient addresses/identities reported by the mail provider.
`subject`	`string`	Yes	Email subject text passed to or returned by the host provider.
`receivedAt`	`string`	Yes	Provider-reported email receive timestamp.
`bodyText`	`string`	No	Plain-text email content; provider rendering and delivery policy remain host-owned.
`labels`	`readonly string[]`	No	Optional provider labels or metric dimensions carried without framework interpretation.

Returns

Type declaration; no runtime value.

Public members

`id`

Provider message identity used for reads, replies and label actions.

`threadId`

Host conversation/thread identity for correlation.

`from`

Sender address/identity reported by the mail provider.

`to`

Recipient addresses/identities reported by the mail provider.

`subject`

Email subject text passed to or returned by the host provider.

`receivedAt`

Provider-reported email receive timestamp.

`bodyText`

Plain-text email content; provider rendering and delivery policy remain host-owned.

`labels`

Optional provider labels or metric dimensions carried without framework interpretation.

Example

See the owning declaration and linked feature guide for usage; no standalone example is documented in source.

[TYPE] `AIErrorCategory`

Operational categories attached to classified errors.

Imports: @alneas/eaos-core, @alneas/eaos-core/ai, @alneas/eaos-core/ai/resilience.

Signature

type AIErrorCategory = 'validation' | 'infrastructure' | 'external_api' | 'llm' | 'policy' | 'business';

Parameters

Name	Type	Required	Description
—	—	—	No call parameters.

Returns

Type declaration; no runtime value.

Example

See the owning declaration and linked feature guide for usage; no standalone example is documented in source.

[INTERFACE] `AIErrorClassification`

Normalized error message and handling metadata returned without side effects.

Imports: @alneas/eaos-core, @alneas/eaos-core/ai, @alneas/eaos-core/ai/resilience.

Signature

interface AIErrorClassification {
    message: string;
    code: string;
    category: AIErrorCategory;
    severity: AIErrorSeverity;
    retryable: boolean;
    hint: string;
    context?: Readonly<Record<string, unknown>>;
}

Parameters

Name	Type	Required	Description
`message`	`string`	Yes	Human-readable provider/failure explanation; do not include secrets in surfaced diagnostics.
`code`	`string`	Yes	Matched host error code, or ERR_UNKNOWN when no rule matches.
`category`	`AIErrorCategory`	Yes	Matched operational category, business for the unknown-error fallback.
`severity`	`AIErrorSeverity`	Yes	Handling/alert severity attached to the classified error or detector result.
`retryable`	`boolean`	Yes	Whether the recorded failure permits a host retry; callers must still account for possible completed effects.
`hint`	`string`	Yes	Human-readable remediation guidance associated with an error classification rule/result.
`context`	`Readonly<Record<string, unknown>>`	No	Verified host execution scope propagated to adapters/guards/hooks; callers must establish identity and authorization before use.

Returns

Type declaration; no runtime value.

Public members

`message`

Human-readable provider/failure explanation; do not include secrets in surfaced diagnostics.

`code`

Matched host error code, or ERR_UNKNOWN when no rule matches.

`category`

Matched operational category, business for the unknown-error fallback.

`severity`

Handling/alert severity attached to the classified error or detector result.

`retryable`

Whether the recorded failure permits a host retry; callers must still account for possible completed effects.

`hint`

Human-readable remediation guidance associated with an error classification rule/result.

`context`

Verified host execution scope propagated to adapters/guards/hooks; callers must establish identity and authorization before use.

Example

See the owning declaration and linked feature guide for usage; no standalone example is documented in source.

[INTERFACE] `AIErrorClassificationRule`

Ordered regex rule defining category, retryability and user guidance.

Imports: @alneas/eaos-core, @alneas/eaos-core/ai, @alneas/eaos-core/ai/resilience.

Signature

interface AIErrorClassificationRule {
    pattern: string;
    code: string;
    category: AIErrorCategory;
    severity: AIErrorSeverity;
    retryable: boolean;
    hint: string;
}

Parameters

Name	Type	Required	Description
`pattern`	`string`	Yes	Case-insensitive regular expression matched against error message and stack; invalid syntax throws during classification.
`code`	`string`	Yes	Machine-readable classification code copied to results when this rule first matches.
`category`	`AIErrorCategory`	Yes	Operational error category assigned when this regex rule matches.
`severity`	`AIErrorSeverity`	Yes	Handling/alert severity attached to the classified error or detector result.
`retryable`	`boolean`	Yes	Whether the recorded failure permits a host retry; callers must still account for possible completed effects.
`hint`	`string`	Yes	Human-readable remediation guidance associated with an error classification rule/result.

Returns

Type declaration; no runtime value.

Public members

`pattern`

Case-insensitive regular expression matched against error message and stack; invalid syntax throws during classification.

`code`

Machine-readable classification code copied to results when this rule first matches.

`category`

Operational error category assigned when this regex rule matches.

`severity`

Handling/alert severity attached to the classified error or detector result.

`retryable`

Whether the recorded failure permits a host retry; callers must still account for possible completed effects.

`hint`

Human-readable remediation guidance associated with an error classification rule/result.

Example

See the owning declaration and linked feature guide for usage; no standalone example is documented in source.

[TYPE] `AIErrorSeverity`

Severity labels used by host error handling and observability.

Imports: @alneas/eaos-core, @alneas/eaos-core/ai, @alneas/eaos-core/ai/resilience.

Signature

type AIErrorSeverity = 'fatal' | 'error' | 'warning' | 'info';

Parameters

Name	Type	Required	Description
—	—	—	No call parameters.

Returns

Type declaration; no runtime value.

Example

See the owning declaration and linked feature guide for usage; no standalone example is documented in source.

[TYPE] `AIExecutionAvailability`

Host-reported route availability; offline candidates are excluded.

Imports: @alneas/eaos-core, @alneas/eaos-core/ai, @alneas/eaos-core/ai/execution-broker.

Signature

type AIExecutionAvailability = 'available' | 'degraded' | 'offline';

Parameters

Name	Type	Required	Description
—	—	—	No call parameters.

Returns

Type declaration; no runtime value.

Example

See the owning declaration and linked feature guide for usage; no standalone example is documented in source.

[INTERFACE] `AIExecutionCandidate`

A host-advertised execution route. It contains no endpoint, credential or provider SDK. A route can represent a user’s local subscription CLI, a local MLX process, the ARM worker pool, or an approved external model.

Imports: @alneas/eaos-core, @alneas/eaos-core/ai, @alneas/eaos-core/ai/execution-broker.

Signature

interface AIExecutionCandidate {
    routeId: string;
    target: AIExecutionTarget;
    adapterId: string;
    capabilities: readonly AIModelCapability[];
    allowedSensitivity: readonly AIDataSensitivityLevel[];
    requiresNoTraining: boolean;
    quality: AIExecutionQuality;
    supportedModes: readonly AIExecutionMode[];
    capacity?: AIExecutionCapacity;
    userBound?: boolean;
    priority?: number;
}

Parameters

Name	Type	Required	Description
`routeId`	`string`	Yes	Unique host route identity used as the deterministic final tie-breaker.
`target`	`AIExecutionTarget`	Yes	Approved resource identity or execution placement; this metadata does not independently enforce access.
`adapterId`	`string`	Yes	Host adapter identity that binds routing/receipts to the implementation actually used.
`capabilities`	`readonly AIModelCapability[]`	Yes	Advertised operation/capability names; presence alone does not authorize execution.
`allowedSensitivity`	`readonly AIDataSensitivityLevel[]`	Yes	Data classifications the host advertises as permitted on this model/route.
`requiresNoTraining`	`boolean`	Yes	Declared no-training policy requirement; the host must verify and enforce the provider agreement.
`quality`	`AIExecutionQuality`	Yes	Relative route quality used for scoring; request quality is a preference rather than a hard minimum.
`supportedModes`	`readonly AIExecutionMode[]`	Yes	Execution modes the host advertises as supported by this route.
`capacity`	`AIExecutionCapacity`	No	Optional host availability/queue snapshot; omitted capacity is treated as available in filtering.
`userBound`	`boolean`	No	A subscription CLI is user-bound and must be explicitly allowed.
`priority`	`number`	No	Host policy tie-breaker; larger values win after hard constraints.

Returns

Type declaration; no runtime value.

Public members

`routeId`

Unique host route identity used as the deterministic final tie-breaker.

`target`

Approved resource identity or execution placement; this metadata does not independently enforce access.

`adapterId`

Host adapter identity that binds routing/receipts to the implementation actually used.

`capabilities`

Advertised operation/capability names; presence alone does not authorize execution.

`allowedSensitivity`

Data classifications the host advertises as permitted on this model/route.

`requiresNoTraining`

Declared no-training policy requirement; the host must verify and enforce the provider agreement.

`quality`

Relative route quality used for scoring; request quality is a preference rather than a hard minimum.

`supportedModes`

Execution modes the host advertises as supported by this route.

`capacity`

Optional host availability/queue snapshot; omitted capacity is treated as available in filtering.

`userBound`

A subscription CLI is user-bound and must be explicitly allowed.

`priority`

Host policy tie-breaker; larger values win after hard constraints.

Example

See the owning declaration and linked feature guide for usage; no standalone example is documented in source.

[INTERFACE] `AIExecutionCapacity`

Host capacity snapshot used as a scoring/filtering input.

Imports: @alneas/eaos-core, @alneas/eaos-core/ai, @alneas/eaos-core/ai/execution-broker.

Signature

interface AIExecutionCapacity {
    state: AIExecutionAvailability;
    queueDepth?: number;
    retryAfterMs?: number;
    checkedAt?: string;
}

Parameters

Name	Type	Required	Description
`state`	`AIExecutionAvailability`	Yes	Host availability snapshot; offline routes are excluded and degraded routes receive a score penalty.
`queueDepth`	`number`	No	Optional nonnegative safe-integer number of queued requests in the capacity snapshot.
`retryAfterMs`	`number`	No	Optional host guidance for when capacity/budget may be retried, in milliseconds.
`checkedAt`	`string`	No	Timestamp associated with the reported evaluation or measurement.

Returns

Type declaration; no runtime value.

Public members

`state`

Host availability snapshot; offline routes are excluded and degraded routes receive a score penalty.

`queueDepth`

Optional nonnegative safe-integer number of queued requests in the capacity snapshot.

`retryAfterMs`

Optional host guidance for when capacity/budget may be retried, in milliseconds.

`checkedAt`

Timestamp associated with the reported evaluation or measurement.

Example

See the owning declaration and linked feature guide for usage; no standalone example is documented in source.

[INTERFACE] `AIExecutionContext`

Verified tenant/user operation scope and optional session/model classification.

Imports: @alneas/eaos-core, @alneas/eaos-core/ai, @alneas/eaos-core/ai/governance.

Signature

interface AIExecutionContext {
    tenantId: string;
    userId: string;
    operation: string;
    traceId: string;
    sessionId?: string;
    model?: string;
    sensitivityLevel?: AIDataSensitivityLevel;
}

Parameters

Name	Type	Required	Description
`tenantId`	`string`	Yes	Verified tenant boundary for the record or operation; host authorization must establish this scope.
`userId`	`string`	Yes	User identity within the tenant supplied by the trusted host.
`operation`	`string`	Yes	Operation identity whose meaning and permission are controlled by the host.
`traceId`	`string`	Yes	Trace correlation identity propagated through host execution and audit paths.
`sessionId`	`string`	No	Host session identity used to correlate lifecycle callbacks and operations.
`model`	`string`	No	Optional model selection metadata associated with this execution scope.
`sensitivityLevel`	`AIDataSensitivityLevel`	No	Classification used by the host to constrain eligible execution routes.

Returns

Type declaration; no runtime value.

Public members

`tenantId`

Verified tenant boundary for the record or operation; host authorization must establish this scope.

`userId`

User identity within the tenant supplied by the trusted host.

`operation`

Operation identity whose meaning and permission are controlled by the host.

`traceId`

Trace correlation identity propagated through host execution and audit paths.

`sessionId`

Host session identity used to correlate lifecycle callbacks and operations.

`model`

Optional model selection metadata associated with this execution scope.

`sensitivityLevel`

Classification used by the host to constrain eligible execution routes.

Example

See the owning declaration and linked feature guide for usage; no standalone example is documented in source.

[INTERFACE] `AIExecutionDecision`

Selected route, ranked compatible fallbacks and the policy version/reason.

Imports: @alneas/eaos-core, @alneas/eaos-core/ai, @alneas/eaos-core/ai/execution-broker.

Signature

interface AIExecutionDecision {
    route: AIExecutionCandidate;
    fallbacks: readonly AIExecutionCandidate[];
    policyVersion: string;
    reason: string;
}

Parameters

Name	Type	Required	Description
`route`	`AIExecutionCandidate`	Yes	Highest-ranked compatible execution candidate.
`fallbacks`	`readonly AIExecutionCandidate[]`	Yes	Remaining compatible candidates in deterministic ranking order; no fallback execution happens automatically.
`policyVersion`	`string`	Yes	Host-supplied policy identity included with decisions; default ai-execution-policy-v1.
`reason`	`string`	Yes	Human-readable explanation of the decision or requested action.

Returns

Type declaration; no runtime value.

Public members

`route`

Highest-ranked compatible execution candidate.

`fallbacks`

Remaining compatible candidates in deterministic ranking order; no fallback execution happens automatically.

`policyVersion`

Host-supplied policy identity included with decisions; default ai-execution-policy-v1.

`reason`

Human-readable explanation of the decision or requested action.

Example

See the owning declaration and linked feature guide for usage; no standalone example is documented in source.

[TYPE] `AIExecutionLatency`

Latency preference used when ranking compatible candidates.

Imports: @alneas/eaos-core, @alneas/eaos-core/ai, @alneas/eaos-core/ai/execution-broker.

Signature

type AIExecutionLatency = 'interactive' | 'normal' | 'batch';

Parameters

Name	Type	Required	Description
—	—	—	No call parameters.

Returns

Type declaration; no runtime value.

Example

See the owning declaration and linked feature guide for usage; no standalone example is documented in source.

[TYPE] `AIExecutionMode`

Interactive request or durable-workflow placement mode.

Imports: @alneas/eaos-core, @alneas/eaos-core/ai, @alneas/eaos-core/ai/execution-broker.

Signature

type AIExecutionMode = 'durable-workflow' | 'interactive';

Parameters

Name	Type	Required	Description
—	—	—	No call parameters.

Returns

Type declaration; no runtime value.

Example

See the owning declaration and linked feature guide for usage; no standalone example is documented in source.

[TYPE] `AIExecutionQuality`

Relative quality preference used in broker scoring.

Imports: @alneas/eaos-core, @alneas/eaos-core/ai, @alneas/eaos-core/ai/execution-broker.

Signature

type AIExecutionQuality = 'economy' | 'standard' | 'premium';

Parameters

Name	Type	Required	Description
—	—	—	No call parameters.

Returns

Type declaration; no runtime value.

Example

See the owning declaration and linked feature guide for usage; no standalone example is documented in source.

[INTERFACE] `AIExecutionRequest`

Verified operation context and hard/soft placement constraints.

Imports: @alneas/eaos-core, @alneas/eaos-core/ai, @alneas/eaos-core/ai/execution-broker.

Signature

interface AIExecutionRequest {
    context: Pick<AIExecutionContext, 'tenantId' | 'userId' | 'operation'>;
    capability: AIModelCapability;
    sensitivityLevel: AIDataSensitivityLevel;
    mode: AIExecutionMode;
    quality: AIExecutionQuality;
    latency: AIExecutionLatency;
    requiresNoTraining: boolean;
    preferredTargets?: readonly AIExecutionTarget[];
    allowedTargets?: readonly AIExecutionTarget[];
    allowUserBoundRunner?: boolean;
}

Parameters

Name	Type	Required	Description
`context`	`Pick<AIExecutionContext, 'tenantId' \| 'userId' \| 'operation'>`	Yes	Verified host execution scope propagated to adapters/guards/hooks; callers must establish identity and authorization before use.
`capability`	`AIModelCapability`	Yes	Required model capability used as a hard route filter.
`sensitivityLevel`	`AIDataSensitivityLevel`	Yes	Classification used by the host to constrain eligible execution routes.
`mode`	`AIExecutionMode`	Yes	Selected operation/storage/execution variant; the owning discriminated union determines applicable fields.
`quality`	`AIExecutionQuality`	Yes	Relative route quality used for scoring; request quality is a preference rather than a hard minimum.
`latency`	`AIExecutionLatency`	Yes	Requested latency preference used for scoring, rather than a hard deadline.
`requiresNoTraining`	`boolean`	Yes	Declared no-training policy requirement; the host must verify and enforce the provider agreement.
`preferredTargets`	`readonly AIExecutionTarget[]`	No	Optional target ranking order; unlisted targets remain eligible unless allowedTargets excludes them.
`allowedTargets`	`readonly AIExecutionTarget[]`	No	Optional hard target allowlist; an empty list permits no targets.
`allowUserBoundRunner`	`boolean`	No	Required for unattended workflows that intentionally use a user runner.

Returns

Type declaration; no runtime value.

Public members

`context`

Verified host execution scope propagated to adapters/guards/hooks; callers must establish identity and authorization before use.

`capability`

Required model capability used as a hard route filter.

`sensitivityLevel`

Classification used by the host to constrain eligible execution routes.

`mode`

Selected operation/storage/execution variant; the owning discriminated union determines applicable fields.

`quality`

Relative route quality used for scoring; request quality is a preference rather than a hard minimum.

`latency`

Requested latency preference used for scoring, rather than a hard deadline.

`requiresNoTraining`

Declared no-training policy requirement; the host must verify and enforce the provider agreement.

`preferredTargets`

Optional target ranking order; unlisted targets remain eligible unless allowedTargets excludes them.

`allowedTargets`

Optional hard target allowlist; an empty list permits no targets.

`allowUserBoundRunner`

Required for unattended workflows that intentionally use a user runner.

Example

See the owning declaration and linked feature guide for usage; no standalone example is documented in source.

[CLASS] `AIExecutionRouteUnavailableError`

Signal that no advertised execution route satisfies broker constraints.

Imports: @alneas/eaos-core, @alneas/eaos-core/ai, @alneas/eaos-core/ai/execution-broker.

Signature

declare class AIExecutionRouteUnavailableError extends Error {
    readonly code: "AI_ROUTE_UNAVAILABLE";
    constructor(message?: string);
}

Parameters

Name	Type	Required	Description
`message`	`string`	No	Human-readable reason; defaults to No AI execution route satisfies the request.

Returns

AIExecutionRouteUnavailableError

Constructor contract

Public members

`code`

Stable machine-readable code AI_ROUTE_UNAVAILABLE.

Example

import { AIExecutionRouteUnavailableError } from "@alneas/eaos-core/ai/execution-broker";
const error = new AIExecutionRouteUnavailableError();
console.log(error.code); // AI_ROUTE_UNAVAILABLE

[TYPE] `AIExecutionTarget`

Execution locations considered by the host-controlled route broker.

Imports: @alneas/eaos-core, @alneas/eaos-core/ai, @alneas/eaos-core/ai/execution-broker.

Signature

type AIExecutionTarget = 'local-subscription-cli' | 'local-mlx' | 'arm-agent' | 'external-no-training';

Parameters

Name	Type	Required	Description
—	—	—	No call parameters.

Returns

Type declaration; no runtime value.

Example

See the owning declaration and linked feature guide for usage; no standalone example is documented in source.

[INTERFACE] `AIGuard`

Optional input/output guard. Implementations belong to the host or an optional package.

Imports: @alneas/eaos-core, @alneas/eaos-core/ai, @alneas/eaos-core/ai/governance.

Signature

interface AIGuard {
    before?(input: AIGuardInput): Promise<AIGuardResult> | AIGuardResult;
    after?(input: {
        context: AIExecutionContext;
        message: AIChatMessage;
    }): Promise<AIGuardResult> | AIGuardResult;
}

Parameters

Name	Type	Required	Description
`before`	`Promise<AIGuardResult> \| AIGuardResult`	No	Evaluate model input before provider execution.
`after`	`Promise<AIGuardResult> \| AIGuardResult`	No	Evaluate a provider message before exposing it to the caller.

Returns

Type declaration; no runtime value.

Public members

`before`

Evaluate model input before provider execution.

Parameters:

input: Verified scope, original messages and tool identities to review.

Returns: Admission data and optional replacement messages/classification/redactions, directly or through a Promise.

Remarks

Optional host policy port; the caller must honor allowed and decide how failures affect execution.

Errors and rejections

Guard errors/rejections propagate to its caller.

Example:

import type { AIGuard } from "@alneas/eaos-core/ai/governance";
async function reviewInput(guard: AIGuard, input: Parameters<NonNullable<AIGuard["before"]>>[0]) {
 if (!guard.before) throw new Error("Host input guard is unavailable");
 return guard.before(input);
}

`after`

Evaluate a provider message before exposing it to the caller.

Parameters:

input: Verified execution scope and generated chat message.

Returns: Admission data and optional host replacements/classification/redactions.

Remarks

Optional host policy port; it does not undo provider calls or already-performed effects.

Errors and rejections

Guard errors/rejections propagate to its caller.

Example:

import type { AIGuard } from "@alneas/eaos-core/ai/governance";
async function reviewOutput(guard: AIGuard, input: Parameters<NonNullable<AIGuard["after"]>>[0]) {
 if (!guard.after) throw new Error("Host output guard is unavailable");
 return guard.after(input);
}

`after.input.context`

Verified host execution scope propagated to adapters/guards/hooks; callers must establish identity and authorization before use.

`after.input.message`

Human-readable provider/failure explanation; do not include secrets in surfaced diagnostics.

Example

See the owning declaration and linked feature guide for usage; no standalone example is documented in source.

[INTERFACE] `AIGuardInput`

Execution context, chat messages and tool names evaluated before model execution.

Imports: @alneas/eaos-core, @alneas/eaos-core/ai, @alneas/eaos-core/ai/governance.

Signature

interface AIGuardInput {
    context: AIExecutionContext;
    messages: readonly AIChatMessage[];
    toolNames: readonly string[];
}

Parameters

Name	Type	Required	Description
`context`	`AIExecutionContext`	Yes	Verified host execution scope propagated to adapters/guards/hooks; callers must establish identity and authorization before use.
`messages`	`readonly AIChatMessage[]`	Yes	Chat messages evaluated by a host guard, or optional rewritten messages returned by it.
`toolNames`	`readonly string[]`	Yes	Tool identities presented to a guard for policy evaluation.

Returns

Type declaration; no runtime value.

Public members

`context`

Verified host execution scope propagated to adapters/guards/hooks; callers must establish identity and authorization before use.

`messages`

Chat messages evaluated by a host guard, or optional rewritten messages returned by it.

`toolNames`

Tool identities presented to a guard for policy evaluation.

Example

See the owning declaration and linked feature guide for usage; no standalone example is documented in source.

[INTERFACE] `AIGuardResult`

Guard admission decision with optional rewritten messages and classification/redaction data.

Imports: @alneas/eaos-core, @alneas/eaos-core/ai, @alneas/eaos-core/ai/governance.

Signature

interface AIGuardResult {
    allowed: boolean;
    reason?: string;
    messages?: readonly AIChatMessage[];
    sensitivityLevel?: AIDataSensitivityLevel;
    redactions?: Readonly<Record<string, string>>;
}

Parameters

Name	Type	Required	Description
`allowed`	`boolean`	Yes	Admission/check decision; consumers must inspect it before using the associated result or performing an effect.
`reason`	`string`	No	Human-readable explanation of the decision or requested action.
`messages`	`readonly AIChatMessage[]`	No	Chat messages evaluated by a host guard, or optional rewritten messages returned by it.
`sensitivityLevel`	`AIDataSensitivityLevel`	No	Classification used by the host to constrain eligible execution routes.
`redactions`	`Readonly<Record<string, string>>`	No	Optional host-produced redaction mapping; may itself contain sensitive source values.

Returns

Type declaration; no runtime value.

Public members

`allowed`

Admission/check decision; consumers must inspect it before using the associated result or performing an effect.

`reason`

Human-readable explanation of the decision or requested action.

`messages`

Chat messages evaluated by a host guard, or optional rewritten messages returned by it.

`sensitivityLevel`

Classification used by the host to constrain eligible execution routes.

`redactions`

Optional host-produced redaction mapping; may itself contain sensitive source values.

Example

See the owning declaration and linked feature guide for usage; no standalone example is documented in source.

[INTERFACE] `AIHostActionContext`

A side-effect request must be replay-safe and tied to the verified execution context.

Imports: @alneas/eaos-core, @alneas/eaos-core/ai, @alneas/eaos-core/ai/host-adapters.

Signature

interface AIHostActionContext {
    context: AIExecutionContext;
    idempotencyKey: string;
    dryRun?: boolean;
    approval?: {
        approvalId: string;
        status: 'pending' | 'approved' | 'rejected';
    };
    deadline?: string;
}

Parameters

Name	Type	Required	Description
`context`	`AIExecutionContext`	Yes	Verified host execution scope propagated to adapters/guards/hooks; callers must establish identity and authorization before use.
`idempotencyKey`	`string`	Yes	Replay identity for the same admitted operation; the host must persist/deduplicate it before unsafe retries.
`dryRun`	`boolean`	No	Optional request to preview rather than commit an effect; actual support/enforcement is adapter-owned.
`approval`	`{ approvalId: string; status: 'pending' \| 'approved' \| 'rejected'; }`	No	Optional host review metadata; an approved value must be established by a trusted host, never by model output.
`deadline`	`string`	No	Optional absolute deadline supplied to the host; Core does not schedule cancellation.

Returns

Type declaration; no runtime value.

Public members

`context`

Verified host execution scope propagated to adapters/guards/hooks; callers must establish identity and authorization before use.

`idempotencyKey`

Replay identity for the same admitted operation; the host must persist/deduplicate it before unsafe retries.

`dryRun`

Optional request to preview rather than commit an effect; actual support/enforcement is adapter-owned.

`approval`

Optional host review metadata; an approved value must be established by a trusted host, never by model output.

`approval.approvalId`

Host identity for the review request/decision associated with this operation.

`approval.status`

Host-established review state; pending/rejected do not authorize a side effect.

`deadline`

Optional absolute deadline supplied to the host; Core does not schedule cancellation.

Example

See the owning declaration and linked feature guide for usage; no standalone example is documented in source.

[INTERFACE] `AIHostAdapter`

Host adapter identity and advertised operation capabilities.

Imports: @alneas/eaos-core, @alneas/eaos-core/ai, @alneas/eaos-core/ai/host-adapters.

Signature

interface AIHostAdapter {
    readonly id: string;
    readonly capabilities: readonly string[];
}

Parameters

Name	Type	Required	Description
`id`	`string`	Yes	Host adapter identity used to bind execution and receipts to a provider implementation.
`capabilities`	`readonly string[]`	Yes	Advertised operation/capability names; presence alone does not authorize execution.

Returns

Type declaration; no runtime value.

Public members

`id`

Host adapter identity used to bind execution and receipts to a provider implementation.

`capabilities`

Advertised operation/capability names; presence alone does not authorize execution.

Example

See the owning declaration and linked feature guide for usage; no standalone example is documented in source.

[TYPE] `AIHostAdapterName`

Provider-neutral adapter names that a Host may expose to a Skill.

Imports: @alneas/eaos-core, @alneas/eaos-core/ai, @alneas/eaos-core/ai/governance, @alneas/eaos-core/ai/host-adapters.

Signature

type AIHostAdapterName = 'calendar' | 'email' | 'workspace' | 'travel' | 'browser' | 'messaging' | 'workflow' | 'retrieval';

Parameters

Name	Type	Required	Description
—	—	—	No call parameters.

Returns

Type declaration; no runtime value.

Example

See the owning declaration and linked feature guide for usage; no standalone example is documented in source.

[INTERFACE] `AIHostAdapters`

Host-owned capabilities made available to a runtime without importing providers into core.

Imports: @alneas/eaos-core, @alneas/eaos-core/ai, @alneas/eaos-core/ai/host-adapters.

Signature

interface AIHostAdapters {
    calendar?: AICalendarAdapter;
    email?: AIEmailAdapter;
    workspace?: AIWorkspaceAdapter;
    travel?: AITravelAdapter;
    browser?: AIBrowserAdapter;
    messaging?: AIMessagingAdapter;
    workflow?: AIWorkflowAdapter;
    retrieval?: AIRetrievalAdapter;
}

Parameters

Name	Type	Required	Description
`calendar`	`AICalendarAdapter`	No	Optional host calendar capability; absence means the host has not configured it.
`email`	`AIEmailAdapter`	No	Optional host email capability; absence means email operations are unavailable.
`workspace`	`AIWorkspaceAdapter`	No	Optional host workspace read/proposal/mutation capability; absence means it is unavailable.
`travel`	`AITravelAdapter`	No	Optional host travel capability; absence means the host has not configured it.
`browser`	`AIBrowserAdapter`	No	Optional host browser capability; absence means the host has not configured it.
`messaging`	`AIMessagingAdapter`	No	Optional host messaging capability; absence means the host has not configured it.
`workflow`	`AIWorkflowAdapter`	No	Optional host workflow capability; absence means the host has not configured it.
`retrieval`	`AIRetrievalAdapter`	No	Host retrieval capability or placement binding; indexing remains host-owned.

Returns

Type declaration; no runtime value.

Public members

`calendar`

Optional host calendar capability; absence means the host has not configured it.

`email`

Optional host email capability; absence means email operations are unavailable.

`workspace`

Optional host workspace read/proposal/mutation capability; absence means it is unavailable.

`travel`

Optional host travel capability; absence means the host has not configured it.

`browser`

Optional host browser capability; absence means the host has not configured it.

`messaging`

Optional host messaging capability; absence means the host has not configured it.

`workflow`

Optional host workflow capability; absence means the host has not configured it.

`retrieval`

Host retrieval capability or placement binding; indexing remains host-owned.

Example

See the owning declaration and linked feature guide for usage; no standalone example is documented in source.

[TYPE] `AIHostOperationStatus`

Host side-effect status; accepted/pending do not mean completed.

Imports: @alneas/eaos-core, @alneas/eaos-core/ai, @alneas/eaos-core/ai/host-adapters.

Signature

type AIHostOperationStatus = 'accepted' | 'completed' | 'pending' | 'failed' | 'unavailable';

Parameters

Name	Type	Required	Description
—	—	—	No call parameters.

Returns

Type declaration; no runtime value.

Example

See the owning declaration and linked feature guide for usage; no standalone example is documented in source.

[INTERFACE] `AIHostReceipt`

The only source of truth for an external side effect.

Imports: @alneas/eaos-core, @alneas/eaos-core/ai, @alneas/eaos-core/ai/host-adapters.

Signature

interface AIHostReceipt {
    adapterId: string;
    operation: string;
    receiptId: string;
    idempotencyKey: string;
    status: AIHostOperationStatus;
    acceptedAt: string;
    completedAt?: string;
    externalId?: string;
    message?: string;
    metadata?: Readonly<Record<string, unknown>>;
}

Parameters

Name	Type	Required	Description
`adapterId`	`string`	Yes	Host adapter identity that binds routing/receipts to the implementation actually used.
`operation`	`string`	Yes	Operation identity whose meaning and permission are controlled by the host.
`receiptId`	`string`	Yes	Provider/host identity of the effect receipt.
`idempotencyKey`	`string`	Yes	Replay identity for the same admitted operation; the host must persist/deduplicate it before unsafe retries.
`status`	`AIHostOperationStatus`	Yes	Host-reported operation lifecycle; only completed is considered successful by isAIHostReceiptSuccessful.
`acceptedAt`	`string`	Yes	Host timestamp at which the side-effect request was accepted.
`completedAt`	`string`	No	Optional host completion timestamp; absent while the effect remains unsettled.
`externalId`	`string`	No	Optional external resource identity reported by the provider.
`message`	`string`	No	Human-readable provider/failure explanation; do not include secrets in surfaced diagnostics.
`metadata`	`Readonly<Record<string, unknown>>`	No	Optional host/provider metadata; callers remain responsible for sensitive content and validation.

Returns

Type declaration; no runtime value.

Public members

`adapterId`

Host adapter identity that binds routing/receipts to the implementation actually used.

`operation`

Operation identity whose meaning and permission are controlled by the host.

`receiptId`

Provider/host identity of the effect receipt.

`idempotencyKey`

Replay identity for the same admitted operation; the host must persist/deduplicate it before unsafe retries.

`status`

Host-reported operation lifecycle; only completed is considered successful by isAIHostReceiptSuccessful.

`acceptedAt`

Host timestamp at which the side-effect request was accepted.

`completedAt`

Optional host completion timestamp; absent while the effect remains unsettled.

`externalId`

Optional external resource identity reported by the provider.

`message`

Human-readable provider/failure explanation; do not include secrets in surfaced diagnostics.

`metadata`

Optional host/provider metadata; callers remain responsible for sensitive content and validation.

Example

See the owning declaration and linked feature guide for usage; no standalone example is documented in source.

[INTERFACE] `AIHostResult`

Optional domain value paired with an authoritative host receipt.

Imports: @alneas/eaos-core, @alneas/eaos-core/ai, @alneas/eaos-core/ai/host-adapters.

Signature

interface AIHostResult<T> {
    value?: T;
    receipt: AIHostReceipt;
}

Parameters

Name	Type	Required	Description
`value`	`T`	No	Optional provider domain value; inspect receipt status before treating it as completed output.
`receipt`	`AIHostReceipt`	Yes	Authoritative host operation receipt; inspect its status/outcome before treating optional output as successful.

Returns

Type declaration; no runtime value.

Type parameters

T: Optional provider domain output; the receipt remains authoritative for completion.

Public members

`value`

Optional provider domain value; inspect receipt status before treating it as completed output.

`receipt`

Authoritative host operation receipt; inspect its status/outcome before treating optional output as successful.

Example

See the owning declaration and linked feature guide for usage; no standalone example is documented in source.

[INTERFACE] `AILineMessage`

Recipient and optional text/template for a host messaging operation.

Imports: @alneas/eaos-core, @alneas/eaos-core/ai, @alneas/eaos-core/ai/host-adapters.

Signature

interface AILineMessage {
    id?: string;
    recipientId: string;
    text?: string;
    template?: unknown;
}

Parameters

Name	Type	Required	Description
`id`	`string`	No	Optional provider message identity returned after delivery.
`recipientId`	`string`	Yes	Messaging recipient identity resolved and authorized by the host.
`text`	`string`	No	Plain-text message/browser content; treat provider text as untrusted data.
`template`	`unknown`	No	Optional provider-specific message template; validation belongs to the messaging host.

Returns

Type declaration; no runtime value.

Public members

`id`

Optional provider message identity returned after delivery.

`recipientId`

Messaging recipient identity resolved and authorized by the host.

`text`

Plain-text message/browser content; treat provider text as untrusted data.

`template`

Optional provider-specific message template; validation belongs to the messaging host.

Example

See the owning declaration and linked feature guide for usage; no standalone example is documented in source.

[INTERFACE] `AIMessagingAdapter`

Host messaging delivery and inbound-signature verification ports.

Imports: @alneas/eaos-core, @alneas/eaos-core/ai, @alneas/eaos-core/ai/host-adapters.

Signature

interface AIMessagingAdapter extends AIHostAdapter {
    sendMessage(input: AILineMessage, context: AIHostActionContext): Promise<AIHostResult<AILineMessage>>;
    verifyInbound(input: {
        body: string;
        signature: string;
    }, context: AIExecutionContext): Promise<{
        valid: boolean;
        event?: unknown;
    }>;
}

Parameters

Name	Type	Required	Description
`sendMessage`	`Promise<AIHostResult<AILineMessage>>`	Yes	Request admitted provider message delivery.
`verifyInbound`	`Promise<{ valid: boolean; event?: unknown; }>`	Yes	Validate a provider inbound signature against an exact message body.

Returns

Type declaration; no runtime value.

Public members

`sendMessage`

Request admitted provider message delivery.

Parameters:

input: Authorized recipient and text/template; host validates provider-specific payload and permissions.
context: Verified host scope plus replay key and optional review/deadline/dry-run metadata.

Returns: Optional provider message plus receipt; accepted status does not establish delivery.

Remarks

Errors and rejections

Host implementation errors/rejections propagate; successful Promise resolution must still be interpreted through the returned result/receipt.

Example:

import type { AIMessagingAdapter, AIHostActionContext } from "@alneas/eaos-core/ai/host-adapters";
async function useHost(adapter: AIMessagingAdapter, context: AIHostActionContext) {
 return adapter.sendMessage({ recipientId: "recipient-1", text: "Review ready" }, context);
}

`verifyInbound`

Validate a provider inbound signature against an exact message body.

Parameters:

input: Raw body and signature; host owns provider verification/freshness policy.
context: Verified host scope used for tenant/user access checks.

Returns: Validation data with optional decoded event; invalid is returned as valid false.

Remarks

Requires a real host implementation and trusted execution context; Core supplies no provider credentials, default count limits or cancellation policy.

Errors and rejections

Host implementation errors/rejections propagate; successful Promise resolution must still be interpreted through the returned result/receipt.

Example:

import type { AIMessagingAdapter } from "@alneas/eaos-core/ai/host-adapters";
import type { AIExecutionContext } from "@alneas/eaos-core/ai/governance";
async function useHost(adapter: AIMessagingAdapter, context: AIExecutionContext) {
 return adapter.verifyInbound({ body: "{}", signature: "signature-from-provider" }, context);
}

`verifyInbound.valid`

Whether signature verification succeeded; does not prove timestamp freshness or replay safety.

`verifyInbound.event`

Inbound provider event or webhook event name interpreted by the connected host.

`verifyInbound.input.body`

Exact inbound body or configured hook body mapping; callback mapping defaults preserve native Kratos behavior.

`verifyInbound.input.signature`

Hexadecimal HMAC or inbound provider signature paired with the exact body; freshness/replay protection remains host-owned.

Example

See the owning declaration and linked feature guide for usage; no standalone example is documented in source.

[TYPE] `AIModelCapability`

Capability exposed by a host-controlled model route.

Imports: @alneas/eaos-core, @alneas/eaos-core/ai, @alneas/eaos-core/ai/model-registry.

Signature

type AIModelCapability = 'chat' | 'tools' | 'structured-output' | 'embedding' | 'rerank';

Parameters

Name	Type	Required	Description
—	—	—	No call parameters.

Returns

Type declaration; no runtime value.

Example

See the owning declaration and linked feature guide for usage; no standalone example is documented in source.

[INTERFACE] `AIModelRegistry`

List and resolve approved model routes without executing providers.

Imports: @alneas/eaos-core, @alneas/eaos-core/ai, @alneas/eaos-core/ai/model-registry.

Signature

interface AIModelRegistry {
    list(): readonly AIModelRoute[];
    resolve(input: AIModelResolveInput): AIModelRoute;
}

Parameters

Name	Type	Required	Description
`list`	`readonly AIModelRoute[]`	Yes	Return detached copies of every registered model route.
`resolve`	`AIModelRoute`	Yes	Resolve an approved route for verified context, capability and optional sensitivity.

Returns

Type declaration; no runtime value.

Public members

`list`

Return detached copies of every registered model route.

Returns: A new array with copied routes/capability/sensitivity lists.

Remarks

The built-in registry does not query provider availability.

Example:

import type { AIModelRegistry } from "@alneas/eaos-core/ai/model-registry";
function listRoutes(registry: AIModelRegistry) { return registry.list(); }

`resolve`

Resolve an approved route for verified context, capability and optional sensitivity.

Parameters:

input: Scope and required capability plus optional model ID/sensitivity; omitted model uses the configured default.

Returns: A detached matching route, never a provider connection.

Remarks

The built-in registry checks shape/compatibility; host tenant/user authorization remains separate.

Errors and rejections

The built-in registry throws Error for invalid context, missing/unknown model or incompatible capability/sensitivity.

Example:

import type { AIModelRegistry } from "@alneas/eaos-core/ai/model-registry";
function resolveRoute(registry: AIModelRegistry) { return registry.resolve({ context: { tenantId: "tenant-demo", userId: "user-demo", operation: "preview" }, capability: "chat", sensitivityLevel: "level1_public" }); }

Example

See the owning declaration and linked feature guide for usage; no standalone example is documented in source.

[INTERFACE] `AIModelRegistryOptions`

Approved routes and optional host-selected default route identity.

Imports: @alneas/eaos-core, @alneas/eaos-core/ai, @alneas/eaos-core/ai/model-registry.

Signature

interface AIModelRegistryOptions {
    routes: readonly AIModelRoute[];
    defaultModelId?: string;
}

Parameters

Name	Type	Required	Description
`routes`	`readonly AIModelRoute[]`	Yes	Approved model/route declarations or synchronous plugin-registration callback; plugin callbacks run once during definePlugin.
`defaultModelId`	`string`	No	Optional host-selected default. Requests cannot select an unregistered route.

Returns

Type declaration; no runtime value.

Public members

`routes`

Approved model/route declarations or synchronous plugin-registration callback; plugin callbacks run once during definePlugin.

`defaultModelId`

Optional host-selected default. Requests cannot select an unregistered route.

Example

See the owning declaration and linked feature guide for usage; no standalone example is documented in source.

[INTERFACE] `AIModelResolveInput`

Execution scope and capability with optional explicit model and sensitivity requirement.

Imports: @alneas/eaos-core, @alneas/eaos-core/ai, @alneas/eaos-core/ai/model-registry.

Signature

interface AIModelResolveInput {
    context: Pick<AIExecutionContext, 'tenantId' | 'userId' | 'operation'>;
    capability: AIModelCapability;
    modelId?: string;
    sensitivityLevel?: AIDataSensitivityLevel;
}

Parameters

Name	Type	Required	Description
`context`	`Pick<AIExecutionContext, 'tenantId' \| 'userId' \| 'operation'>`	Yes	Verified host execution scope propagated to adapters/guards/hooks; callers must establish identity and authorization before use.
`capability`	`AIModelCapability`	Yes	Required model capability used as a hard route filter.
`modelId`	`string`	No	Registered model route identity; unknown selections fail closed in the model registry.
`sensitivityLevel`	`AIDataSensitivityLevel`	No	Classification used by the host to constrain eligible execution routes.

Returns

Type declaration; no runtime value.

Public members

`context`

Verified host execution scope propagated to adapters/guards/hooks; callers must establish identity and authorization before use.

`capability`

Required model capability used as a hard route filter.

`modelId`

Registered model route identity; unknown selections fail closed in the model registry.

`sensitivityLevel`

Classification used by the host to constrain eligible execution routes.

Example

See the owning declaration and linked feature guide for usage; no standalone example is documented in source.

[INTERFACE] `AIModelRoute`

Public, provider-neutral model metadata.

A route contains no endpoint, SDK, credential or provider secret. Those remain host-owned. adapterId binds the selected route to the host adapter that will actually execute it, preventing a request from silently switching providers.

Imports: @alneas/eaos-core, @alneas/eaos-core/ai, @alneas/eaos-core/ai/model-registry.

Signature

interface AIModelRoute {
    modelId: string;
    adapterId: string;
    capabilities: readonly AIModelCapability[];
    allowedSensitivity: readonly AIDataSensitivityLevel[];
    requiresNoTraining?: boolean;
    maxInputChars?: number;
    maxOutputChars?: number;
}

Parameters

Name	Type	Required	Description
`modelId`	`string`	Yes	Registered model route identity; unknown selections fail closed in the model registry.
`adapterId`	`string`	Yes	Host adapter identity that binds routing/receipts to the implementation actually used.
`capabilities`	`readonly AIModelCapability[]`	Yes	Advertised operation/capability names; presence alone does not authorize execution.
`allowedSensitivity`	`readonly AIDataSensitivityLevel[]`	Yes	Data classifications the host advertises as permitted on this model/route.
`requiresNoTraining`	`boolean`	No	Declared no-training policy requirement; the host must verify and enforce the provider agreement.
`maxInputChars`	`number`	No	Optional positive input character ceiling, at most 1000000 when registry-validated.
`maxOutputChars`	`number`	No	Optional positive output character ceiling, at most 1000000 when registry-validated.

Returns

Type declaration; no runtime value.

Public members

`modelId`

Registered model route identity; unknown selections fail closed in the model registry.

`adapterId`

Host adapter identity that binds routing/receipts to the implementation actually used.

`capabilities`

Advertised operation/capability names; presence alone does not authorize execution.

`allowedSensitivity`

Data classifications the host advertises as permitted on this model/route.

`requiresNoTraining`

Declared no-training policy requirement; the host must verify and enforce the provider agreement.

`maxInputChars`

Optional positive input character ceiling, at most 1000000 when registry-validated.

`maxOutputChars`

Optional positive output character ceiling, at most 1000000 when registry-validated.

Example

See the owning declaration and linked feature guide for usage; no standalone example is documented in source.

[INTERFACE] `AINumericMetricPoint`

Finite numeric observation with caller-defined timestamp units and optional labels.

Imports: @alneas/eaos-core, @alneas/eaos-core/ai, @alneas/eaos-core/ai/anomaly.

Signature

interface AINumericMetricPoint {
    timestamp: number;
    value: number;
    labels?: Readonly<Record<string, string>>;
}

Parameters

Name	Type	Required	Description
`timestamp`	`number`	Yes	Finite caller-defined numeric time coordinate; points must be in nondecreasing order and use consistent units.
`value`	`number`	Yes	Finite numeric observation compared with preceding history; all points for a metric must use consistent units.
`labels`	`Readonly<Record<string, string>>`	No	Optional provider labels or metric dimensions carried without framework interpretation.

Returns

Type declaration; no runtime value.

Public members

`timestamp`

Finite caller-defined numeric time coordinate; points must be in nondecreasing order and use consistent units.

`value`

Finite numeric observation compared with preceding history; all points for a metric must use consistent units.

`labels`

Optional provider labels or metric dimensions carried without framework interpretation.

Example

See the owning declaration and linked feature guide for usage; no standalone example is documented in source.

[INTERFACE] `AIObservabilitySink`

Observability is deliberately best-effort and must never become a second execution engine.

Imports: @alneas/eaos-core, @alneas/eaos-core/ai, @alneas/eaos-core/ai/governance.

Signature

interface AIObservabilitySink {
    record(observation: AIObservation): Promise<void> | void;
}

Parameters

Name	Type	Required	Description
`record`	`Promise<void> \| void`	Yes	Deliver one execution observation to host telemetry.

Returns

Type declaration; no runtime value.

Public members

`record`

Deliver one execution observation to host telemetry.

Parameters:

observation: Execution phase, verified scope and optional result/error/usage metadata; redact sensitive content before delivery.

Returns: No value; any returned Promise completes when the host telemetry callback completes.

Remarks

Intended as best-effort telemetry; callers decide how to isolate telemetry failures from execution.

Errors and rejections

Host telemetry errors/rejections are exposed to the direct caller.

Example:

import type { AIObservabilitySink } from "@alneas/eaos-core/ai/governance";
async function observeHost(sink: AIObservabilitySink, observation: Parameters<AIObservabilitySink["record"]>[0]) { await sink.record(observation); }

Example

See the owning declaration and linked feature guide for usage; no standalone example is documented in source.

[INTERFACE] `AIObservation`

Contextual execution observation with optional inputs, outputs, usage and errors.

Imports: @alneas/eaos-core, @alneas/eaos-core/ai, @alneas/eaos-core/ai/governance.

Signature

interface AIObservation {
    phase: AIObservationPhase;
    context: AIExecutionContext;
    eventType?: string;
    input?: unknown;
    output?: unknown;
    usage?: AIUsage;
    error?: string;
    metadata?: Readonly<Record<string, unknown>>;
}

Parameters

Name	Type	Required	Description
`phase`	`AIObservationPhase`	Yes	Lifecycle observation stage: started, event, completed, blocked or failed.
`context`	`AIExecutionContext`	Yes	Verified host execution scope propagated to adapters/guards/hooks; callers must establish identity and authorization before use.
`eventType`	`string`	No	Optional provider/runtime event name associated with this observation.
`input`	`unknown`	No	Domain request value passed to the admitted operation; no domain-schema proof is implied solely by this type.
`output`	`unknown`	No	Optional domain output; validate it separately and inspect the accompanying status/receipt.
`usage`	`AIUsage`	No	Optional token/cost telemetry reported by a host/runtime; absence does not mean zero use.
`error`	`string`	No	Optional human-readable failure detail; absence does not independently establish success.
`metadata`	`Readonly<Record<string, unknown>>`	No	Optional host/provider metadata; callers remain responsible for sensitive content and validation.

Returns

Type declaration; no runtime value.

Public members

`phase`

Lifecycle observation stage: started, event, completed, blocked or failed.

`context`

Verified host execution scope propagated to adapters/guards/hooks; callers must establish identity and authorization before use.

`eventType`

Optional provider/runtime event name associated with this observation.

`input`

Domain request value passed to the admitted operation; no domain-schema proof is implied solely by this type.

`output`

Optional domain output; validate it separately and inspect the accompanying status/receipt.

`usage`

Optional token/cost telemetry reported by a host/runtime; absence does not mean zero use.

`error`

Optional human-readable failure detail; absence does not independently establish success.

`metadata`

Optional host/provider metadata; callers remain responsible for sensitive content and validation.

Example

See the owning declaration and linked feature guide for usage; no standalone example is documented in source.

[TYPE] `AIObservationPhase`

Execution lifecycle markers delivered to observability sinks.

Imports: @alneas/eaos-core, @alneas/eaos-core/ai, @alneas/eaos-core/ai/governance.

Signature

type AIObservationPhase = 'started' | 'event' | 'completed' | 'blocked' | 'failed';

Parameters

Name	Type	Required	Description
—	—	—	No call parameters.

Returns

Type declaration; no runtime value.

Example

See the owning declaration and linked feature guide for usage; no standalone example is documented in source.

[TYPE] `AiProvider`

Provider keys tracked by the local AI circuit breaker.

Imports: @alneas/eaos-core/agent/circuit-breaker.

Signature

type AiProvider = 'openai' | 'gemini' | 'claude' | 'workers-ai' | 'ollama';

Parameters

Name	Type	Required	Description
—	—	—	No call parameters.

Returns

Type declaration; no runtime value.

Example

See the owning declaration and linked feature guide for usage; no standalone example is documented in source.

[INTERFACE] `AIRetrievalAdapter`

Tenant-scoped, read-only retrieval. Indexing and deletion remain Host/Action operations.

Imports: @alneas/eaos-core, @alneas/eaos-core/ai, @alneas/eaos-core/ai/host-adapters.

Signature

interface AIRetrievalAdapter extends AIHostAdapter {
    search(input: {
        query: string;
        topK?: number;
        filters?: Readonly<Record<string, string | number | boolean | readonly string[]>>;
    }, context: AIExecutionContext): Promise<readonly AIRetrievalDocument[]>;
}

Parameters

Name	Type	Required	Description
`search`	`Promise<readonly AIRetrievalDocument[]>`	Yes	Retrieve tenant-scoped source excerpts from a host-owned index.

Returns

Type declaration; no runtime value.

Public members

`search`

Retrieve tenant-scoped source excerpts from a host-owned index.

Parameters:

input: Query and optional topK/metadata filters; adapter owns defaults, limits and index authorization.
context: Verified host scope used for tenant/user access checks.

Returns: Retrieved excerpts with source IDs and provider scores, possibly empty.

Remarks

Requires a real host implementation and trusted execution context; Core supplies no provider credentials, default count limits or cancellation policy.

Errors and rejections

Host implementation errors/rejections propagate; successful Promise resolution must still be interpreted through the returned result/receipt.

Example:

import type { AIRetrievalAdapter } from "@alneas/eaos-core/ai/host-adapters";
import type { AIExecutionContext } from "@alneas/eaos-core/ai/governance";
async function useHost(adapter: AIRetrievalAdapter, context: AIExecutionContext) {
 return adapter.search({ query: "review policy", topK: 5 }, context);
}

`search.input.query`

Provider/host query text; syntax, authorization and limits are adapter-owned.

`search.input.topK`

Requested maximum result count; vector request validation permits integers from 1 to 10000.

`search.input.filters`

Optional host-approved metadata filters; physical field permissions and semantics remain adapter-owned.

Example

See the owning declaration and linked feature guide for usage; no standalone example is documented in source.

[INTERFACE] `AIRetrievalDocument`

Retrieved source excerpt with provider-defined relevance score and optional provenance.

Imports: @alneas/eaos-core, @alneas/eaos-core/ai, @alneas/eaos-core/ai/host-adapters.

Signature

interface AIRetrievalDocument {
    sourceId: string;
    title?: string;
    excerpt: string;
    score: number;
    revision?: string;
    metadata?: Readonly<Record<string, unknown>>;
}

Parameters

Name	Type	Required	Description
`sourceId`	`string`	Yes	Stable retrieval source identity used to trace returned evidence.
`title`	`string`	No	Human-readable draft, task, file or event title displayed by the host.
`excerpt`	`string`	Yes	Source text excerpt; callers should preserve provenance when presenting it.
`score`	`number`	Yes	Provider/detector relevance or anomaly score; interpret using the owning result contract.
`revision`	`string`	No	Optional source/target revision interpreted by the owning host; approval/effect target revisions must be positive integers.
`metadata`	`Readonly<Record<string, unknown>>`	No	Optional host/provider metadata; callers remain responsible for sensitive content and validation.

Returns

Type declaration; no runtime value.

Public members

`sourceId`

Stable retrieval source identity used to trace returned evidence.

`title`

Human-readable draft, task, file or event title displayed by the host.

`excerpt`

Source text excerpt; callers should preserve provenance when presenting it.

`score`

Provider/detector relevance or anomaly score; interpret using the owning result contract.

`revision`

Optional source/target revision interpreted by the owning host; approval/effect target revisions must be positive integers.

`metadata`

Optional host/provider metadata; callers remain responsible for sensitive content and validation.

Example

See the owning declaration and linked feature guide for usage; no standalone example is documented in source.

[INTERFACE] `AIRetryPolicy`

Host retry limit and exponential delay/jitter parameters.

Imports: @alneas/eaos-core, @alneas/eaos-core/ai, @alneas/eaos-core/ai/resilience.

Signature

interface AIRetryPolicy {
    maxAttempts: number;
    baseDelayMs: number;
    maxDelayMs: number;
    backoffMultiplier: number;
    jitterFactor: number;
}

Parameters

Name	Type	Required	Description
`maxAttempts`	`number`	Yes	Maximum intended attempt count; delay calculators validate it but do not themselves stop retries.
`baseDelayMs`	`number`	Yes	Initial retry delay in milliseconds before exponential scaling.
`maxDelayMs`	`number`	Yes	Upper bound for a calculated retry delay in milliseconds.
`backoffMultiplier`	`number`	Yes	Exponential growth factor for successive retry delays, at least one for validated policies.
`jitterFactor`	`number`	Yes	Fraction from zero to one scaling the injected random retry jitter.

Returns

Type declaration; no runtime value.

Public members

`maxAttempts`

Maximum intended attempt count; delay calculators validate it but do not themselves stop retries.

`baseDelayMs`

Initial retry delay in milliseconds before exponential scaling.

`maxDelayMs`

Upper bound for a calculated retry delay in milliseconds.

`backoffMultiplier`

Exponential growth factor for successive retry delays, at least one for validated policies.

`jitterFactor`

Fraction from zero to one scaling the injected random retry jitter.

Example

See the owning declaration and linked feature guide for usage; no standalone example is documented in source.

[TYPE] `AITextOrToolPart`

Keep the import visible in generated declarations for consumers that work with chat parts.

Imports: @alneas/eaos-core, @alneas/eaos-core/ai, @alneas/eaos-core/ai/governance.

Signature

type AITextOrToolPart = Extract<AIChatPart, {
    type: 'text' | 'tool-call' | 'tool-result';
}>;

Parameters

Name	Type	Required	Description
—	—	—	No call parameters.

Returns

Type declaration; no runtime value.

Public members

`type`

Chat-part discriminator selecting text, tool-call or tool-result payload fields.

Example

See the owning declaration and linked feature guide for usage; no standalone example is documented in source.

[INTERFACE] `AITravelAdapter`

Host-owned travel discovery and replay-safe holds, bookings and cancellations.

Imports: @alneas/eaos-core, @alneas/eaos-core/ai, @alneas/eaos-core/ai/host-adapters.

Signature

interface AITravelAdapter extends AIHostAdapter {
    searchOffers(input: {
        destination: string;
        departureDate: string;
        returnDate?: string;
        travelers: number;
        kind?: AITravelOffer['kind'];
    }, context: AIExecutionContext): Promise<readonly AITravelOffer[]>;
    holdOffer(input: {
        offerId: string;
        expiresAt?: string;
    }, context: AIHostActionContext): Promise<AIHostResult<AITravelOffer>>;
    bookOffer(input: {
        offerId: string;
        travelerIds: readonly string[];
    }, context: AIHostActionContext): Promise<AIHostResult<AITravelOffer>>;
    cancelBooking(input: {
        bookingId: string;
        reason?: string;
    }, context: AIHostActionContext): Promise<AIHostResult<unknown>>;
}

Parameters

Name	Type	Required	Description
`searchOffers`	`Promise<readonly AITravelOffer[]>`	Yes	Discover travel offers without creating holds or bookings.
`holdOffer`	`Promise<AIHostResult<AITravelOffer>>`	Yes	Request an admitted temporary hold on a discovered offer.
`bookOffer`	`Promise<AIHostResult<AITravelOffer>>`	Yes	Request an admitted booking for verified traveler identities.
`cancelBooking`	`Promise<AIHostResult<unknown>>`	Yes	Request cancellation of an authorized existing booking.

Returns

Type declaration; no runtime value.

Public members

`searchOffers`

Discover travel offers without creating holds or bookings.

Parameters:

input: Destination, outbound date, optional return date, traveler count and optional category.
context: Verified host scope used for tenant/user access checks.

Returns: Current provider offers, possibly empty; terms/prices may change before booking.

Remarks

Requires a real host implementation and trusted execution context; Core supplies no provider credentials, default count limits or cancellation policy.

Errors and rejections

Host implementation errors/rejections propagate; successful Promise resolution must still be interpreted through the returned result/receipt.

Example:

import type { AITravelAdapter } from "@alneas/eaos-core/ai/host-adapters";
import type { AIExecutionContext } from "@alneas/eaos-core/ai/governance";
async function useHost(adapter: AITravelAdapter, context: AIExecutionContext) {
 return adapter.searchOffers({ destination: "Tokyo", departureDate: "2026-11-01", travelers: 1 }, context);
}

`searchOffers.input.destination`

Destination query text interpreted by the travel provider.

`searchOffers.input.departureDate`

Outbound business date accepted by the travel provider.

`searchOffers.input.returnDate`

Optional return business date accepted by the travel provider.

`searchOffers.input.travelers`

Number of travelers; provider validates supported bounds.

`searchOffers.input.kind`

Travel offer category used to select transport, lodging or another provider offer.

`holdOffer`

Request an admitted temporary hold on a discovered offer.

Parameters:

input: Offer ID and optional requested expiry; provider determines supported hold semantics.
context: Verified host scope plus replay key and optional review/deadline/dry-run metadata.

Returns: Optional held offer plus host receipt.

Remarks

Errors and rejections

Host implementation errors/rejections propagate; successful Promise resolution must still be interpreted through the returned result/receipt.

Example:

import type { AITravelAdapter, AIHostActionContext } from "@alneas/eaos-core/ai/host-adapters";
async function useHost(adapter: AITravelAdapter, context: AIHostActionContext) {
 return adapter.holdOffer({ offerId: "offer-1" }, context);
}

`holdOffer.input.offerId`

Travel provider offer identity selected from trusted discovery results.

`holdOffer.input.expiresAt`

Optional absolute expiry; the owning validation/evaluation API determines whether it remains live.

`bookOffer`

Request an admitted booking for verified traveler identities.

Parameters:

input: Offer ID and host-verified traveler IDs; host must check authorization and current terms.
context: Verified host scope plus replay key and optional review/deadline/dry-run metadata.

Returns: Optional booked offer and host receipt; pending status needs reconciliation.

Remarks

Errors and rejections

Host implementation errors/rejections propagate; successful Promise resolution must still be interpreted through the returned result/receipt.

Example:

import type { AITravelAdapter, AIHostActionContext } from "@alneas/eaos-core/ai/host-adapters";
async function useHost(adapter: AITravelAdapter, context: AIHostActionContext) {
 return adapter.bookOffer({ offerId: "offer-1", travelerIds: ["traveler-1"] }, context);
}

`bookOffer.input.offerId`

Travel provider offer identity selected from trusted discovery results.

`bookOffer.input.travelerIds`

Host-verified traveler identities used to complete a booking.

`cancelBooking`

Request cancellation of an authorized existing booking.

Parameters:

input: Booking identity and optional cancellation reason.
context: Verified host scope plus replay key and optional review/deadline/dry-run metadata.

Returns: Host receipt with optional provider cancellation data.

Remarks

Errors and rejections

Host implementation errors/rejections propagate; successful Promise resolution must still be interpreted through the returned result/receipt.

Example:

import type { AITravelAdapter, AIHostActionContext } from "@alneas/eaos-core/ai/host-adapters";
async function useHost(adapter: AITravelAdapter, context: AIHostActionContext) {
 return adapter.cancelBooking({ bookingId: "booking-1", reason: "Plans changed" }, context);
}

`cancelBooking.input.bookingId`

Existing booking identity authorized for cancellation.

`cancelBooking.input.reason`

Human-readable explanation of the decision or requested action.

Example

See the owning declaration and linked feature guide for usage; no standalone example is documented in source.

[INTERFACE] `AITravelOffer`

Travel provider offer with optional dates, price, currency and terms.

Imports: @alneas/eaos-core, @alneas/eaos-core/ai, @alneas/eaos-core/ai/host-adapters.

Signature

interface AITravelOffer {
    id: string;
    kind: 'transport' | 'lodging' | 'other';
    provider: string;
    title: string;
    start?: string;
    end?: string;
    totalAmount?: number;
    currency?: string;
    terms?: string;
}

Parameters

Name	Type	Required	Description
`id`	`string`	Yes	Provider offer identity to bind a later hold/booking request.
`kind`	`'transport' \| 'lodging' \| 'other'`	Yes	Travel offer category used to select transport, lodging or another provider offer.
`provider`	`string`	Yes	Provider identity from model metadata, travel discovery or connection/circuit health.
`title`	`string`	Yes	Human-readable draft, task, file or event title displayed by the host.
`start`	`string`	No	Optional provider offer start/departure timestamp.
`end`	`string`	No	Optional provider offer end/arrival timestamp.
`totalAmount`	`number`	No	Optional provider quoted price; its monetary units and rounding are provider-defined.
`currency`	`string`	No	Currency identifier for reported cost/price; its units are defined by the provider/host contract.
`terms`	`string`	No	Optional provider terms that the caller must review before booking.

Returns

Type declaration; no runtime value.

Public members

`id`

Provider offer identity to bind a later hold/booking request.

`kind`

Travel offer category used to select transport, lodging or another provider offer.

`provider`

Provider identity from model metadata, travel discovery or connection/circuit health.

`title`

Human-readable draft, task, file or event title displayed by the host.

`start`

Optional provider offer start/departure timestamp.

`end`

Optional provider offer end/arrival timestamp.

`totalAmount`

Optional provider quoted price; its monetary units and rounding are provider-defined.

`currency`

Currency identifier for reported cost/price; its units are defined by the provider/host contract.

`terms`

Optional provider terms that the caller must review before booking.

Example

See the owning declaration and linked feature guide for usage; no standalone example is documented in source.

[INTERFACE] `AIUsage`

Provider-reported token counts and optional cost/currency metadata.

Imports: @alneas/eaos-core, @alneas/eaos-core/ai, @alneas/eaos-core/ai/governance.

Signature

interface AIUsage {
    inputTokens?: number;
    outputTokens?: number;
    totalTokens?: number;
    cost?: number;
    currency?: string;
}

Parameters

Name	Type	Required	Description
`inputTokens`	`number`	No	Optional count of tokens consumed as model/runtime input.
`outputTokens`	`number`	No	Optional count of generated model/runtime tokens.
`totalTokens`	`number`	No	Optional total token count reported by the provider/runtime.
`cost`	`number`	No	Optional provider-reported cost in the supplied currency; accounting remains host-owned.
`currency`	`string`	No	Currency identifier for reported cost/price; its units are defined by the provider/host contract.

Returns

Type declaration; no runtime value.

Public members

`inputTokens`

Optional count of tokens consumed as model/runtime input.

`outputTokens`

Optional count of generated model/runtime tokens.

`totalTokens`

Optional total token count reported by the provider/runtime.

`cost`

Optional provider-reported cost in the supplied currency; accounting remains host-owned.

`currency`

Currency identifier for reported cost/price; its units are defined by the provider/host contract.

Example

See the owning declaration and linked feature guide for usage; no standalone example is documented in source.

[INTERFACE] `AIWorkflowAdapter`

Host workflow discovery, admitted execution/cancellation and status reads.

Imports: @alneas/eaos-core, @alneas/eaos-core/ai, @alneas/eaos-core/ai/host-adapters.

Signature

interface AIWorkflowAdapter extends AIHostAdapter {
    listWorkflows(input: {
        tag?: string;
        limit?: number;
    }, context: AIExecutionContext): Promise<readonly {
        id: string;
        name: string;
        version?: string;
    }[]>;
    executeWorkflow(input: {
        workflowId: string;
        payload: unknown;
    }, context: AIHostActionContext): Promise<AIHostResult<AIWorkflowExecution>>;
    getExecution(input: {
        executionId: string;
    }, context: AIExecutionContext): Promise<AIWorkflowExecution | null>;
    cancelExecution(input: {
        executionId: string;
        reason?: string;
    }, context: AIHostActionContext): Promise<AIHostResult<AIWorkflowExecution>>;
}

Parameters

Name	Type	Required	Description
`listWorkflows`	`Promise<readonly { id: string; name: string; version?: string; }[]>`	Yes	Discover workflows available to the verified execution scope.
`executeWorkflow`	`Promise<AIHostResult<AIWorkflowExecution>>`	Yes	Request an admitted host workflow execution.
`getExecution`	`Promise<AIWorkflowExecution \| null>`	Yes	Read one authorized host workflow execution.
`cancelExecution`	`Promise<AIHostResult<AIWorkflowExecution>>`	Yes	Request cancellation of an authorized host workflow execution.

Returns

Type declaration; no runtime value.

Public members

`listWorkflows`

Discover workflows available to the verified execution scope.

Parameters:

input: Optional tag and count limit; defaults belong to the host adapter.
context: Verified host scope used for tenant/user access checks.

Returns: Workflow IDs/display names and optional versions, possibly empty.

Remarks

Requires a real host implementation and trusted execution context; Core supplies no provider credentials, default count limits or cancellation policy.

Errors and rejections

Host implementation errors/rejections propagate; successful Promise resolution must still be interpreted through the returned result/receipt.

Example:

import type { AIWorkflowAdapter } from "@alneas/eaos-core/ai/host-adapters";
import type { AIExecutionContext } from "@alneas/eaos-core/ai/governance";
async function useHost(adapter: AIWorkflowAdapter, context: AIExecutionContext) {
 return adapter.listWorkflows({ tag: "review", limit: 10 }, context);
}

`listWorkflows[].id`

Host workflow definition identity used for a later execute request.

`listWorkflows[].name`

Human-readable display name supplied by the plugin/provider catalog; distinct from the stable ID.

`listWorkflows[].version`

Optional host workflow release version advertised for execution selection.

`listWorkflows.input.tag`

Optional host workflow discovery tag filter.

`listWorkflows.input.limit`

Optional result-count bound; default and maximum are owned by the connected adapter.

`executeWorkflow`

Request an admitted host workflow execution.

Parameters:

input: Discovered workflow identity and domain payload validated by the host.
context: Verified host scope plus replay key and optional review/deadline/dry-run metadata.

Returns: Optional execution record and receipt; queued/running states are not workflow completion.

Remarks

Errors and rejections

Host implementation errors/rejections propagate; successful Promise resolution must still be interpreted through the returned result/receipt.

Example:

import type { AIWorkflowAdapter, AIHostActionContext } from "@alneas/eaos-core/ai/host-adapters";
async function useHost(adapter: AIWorkflowAdapter, context: AIHostActionContext) {
 return adapter.executeWorkflow({ workflowId: "review", payload: { documentId: "document-1" } }, context);
}

`executeWorkflow.input.workflowId`

Workflow definition identity used to correlate execution and effects.

`executeWorkflow.input.payload`

Typed event/request body; constructors clone and strictly hash JSON where documented.

`getExecution`

Read one authorized host workflow execution.

Parameters:

input: Existing execution identity.
context: Verified host scope used for tenant/user access checks.

Returns: Execution record when available, otherwise null.

Remarks

Requires a real host implementation and trusted execution context; Core supplies no provider credentials, default count limits or cancellation policy.

Errors and rejections

Host implementation errors/rejections propagate; successful Promise resolution must still be interpreted through the returned result/receipt.

Example:

import type { AIWorkflowAdapter } from "@alneas/eaos-core/ai/host-adapters";
import type { AIExecutionContext } from "@alneas/eaos-core/ai/governance";
async function useHost(adapter: AIWorkflowAdapter, context: AIExecutionContext) {
 return adapter.getExecution({ executionId: "execution-1" }, context);
}

`getExecution.input.executionId`

Host/provider execution identity; the legacy sandbox may generate this for a simulated result.

`cancelExecution`

Request cancellation of an authorized host workflow execution.

Parameters:

input: Execution identity and optional reason.
context: Verified host scope plus replay key and optional review/deadline/dry-run metadata.

Returns: Optional execution record and host receipt; cancellation completion is host-defined.

Remarks

Errors and rejections

Host implementation errors/rejections propagate; successful Promise resolution must still be interpreted through the returned result/receipt.

Example:

import type { AIWorkflowAdapter, AIHostActionContext } from "@alneas/eaos-core/ai/host-adapters";
async function useHost(adapter: AIWorkflowAdapter, context: AIHostActionContext) {
 return adapter.cancelExecution({ executionId: "execution-1", reason: "Superseded" }, context);
}

`cancelExecution.input.executionId`

Host/provider execution identity; the legacy sandbox may generate this for a simulated result.

`cancelExecution.input.reason`

Human-readable explanation of the decision or requested action.

Example

See the owning declaration and linked feature guide for usage; no standalone example is documented in source.

[INTERFACE] `AIWorkflowExecution`

Host workflow identity, lifecycle timestamps and optional output.

Imports: @alneas/eaos-core, @alneas/eaos-core/ai, @alneas/eaos-core/ai/host-adapters.

Signature

interface AIWorkflowExecution {
    executionId: string;
    workflowId: string;
    status: 'queued' | 'running' | 'succeeded' | 'failed' | 'cancelled';
    startedAt?: string;
    finishedAt?: string;
    output?: unknown;
}

Parameters

Name	Type	Required	Description
`executionId`	`string`	Yes	Host/provider execution identity; the legacy sandbox may generate this for a simulated result.
`workflowId`	`string`	Yes	Workflow definition identity used to correlate execution and effects.
`status`	`'queued' \| 'running' \| 'succeeded' \| 'failed' \| 'cancelled'`	Yes	Host workflow lifecycle independent of action receipt acceptance.
`startedAt`	`string`	No	Optional host-reported execution start timestamp.
`finishedAt`	`string`	No	Optional host-reported execution completion timestamp.
`output`	`unknown`	No	Optional domain output; validate it separately and inspect the accompanying status/receipt.

Returns

Type declaration; no runtime value.

Public members

`executionId`

Host/provider execution identity; the legacy sandbox may generate this for a simulated result.

`workflowId`

Workflow definition identity used to correlate execution and effects.

`status`

Host workflow lifecycle independent of action receipt acceptance.

`startedAt`

Optional host-reported execution start timestamp.

`finishedAt`

Optional host-reported execution completion timestamp.

`output`

Optional domain output; validate it separately and inspect the accompanying status/receipt.

Example

See the owning declaration and linked feature guide for usage; no standalone example is documented in source.

[INTERFACE] `AIWorkspaceAdapter`

Provider-neutral Docs/Sheets/Drive surface. OAuth and provider SDKs remain host-owned.

Imports: @alneas/eaos-core, @alneas/eaos-core/ai, @alneas/eaos-core/ai/host-adapters.

Signature

interface AIWorkspaceAdapter extends AIHostAdapter {
    searchFiles(input: {
        query: string;
        mimeTypes?: readonly string[];
        limit?: number;
    }, context: AIExecutionContext): Promise<readonly AIWorkspaceFile[]>;
    readFile(input: {
        fileId: string;
        version?: string;
    }, context: AIExecutionContext): Promise<{
        file: AIWorkspaceFile;
        content: string;
    } | null>;
    proposeChange(input: AIWorkspaceChange, context: AIExecutionContext): Promise<{
        change: AIWorkspaceChange;
        summary: string;
    }>;
    applyChange(input: AIWorkspaceChange, context: AIHostActionContext): Promise<AIHostResult<AIWorkspaceFile>>;
}

Parameters

Name	Type	Required	Description
`searchFiles`	`Promise<readonly AIWorkspaceFile[]>`	Yes	Discover files within the authorized workspace scope.
`readFile`	`Promise<{ file: AIWorkspaceFile; content: string; } \| null>`	Yes	Read authorized file content and provider version metadata.
`proposeChange`	`Promise<{ change: AIWorkspaceChange; summary: string; }>`	Yes	Prepare a reviewable file change without invoking applyChange.
`applyChange`	`Promise<AIHostResult<AIWorkspaceFile>>`	Yes	Request an admitted workspace mutation with optional version precondition.

Returns

Type declaration; no runtime value.

Public members

`searchFiles`

Discover files within the authorized workspace scope.

Parameters:

input: Provider query, optional media types and count limit; defaults are adapter-owned.
context: Verified host scope used for tenant/user access checks.

Returns: Matching file descriptors, possibly empty.

Remarks

Requires a real host implementation and trusted execution context; Core supplies no provider credentials, default count limits or cancellation policy.

Errors and rejections

Host implementation errors/rejections propagate; successful Promise resolution must still be interpreted through the returned result/receipt.

Example:

import type { AIWorkspaceAdapter } from "@alneas/eaos-core/ai/host-adapters";
import type { AIExecutionContext } from "@alneas/eaos-core/ai/governance";
async function useHost(adapter: AIWorkspaceAdapter, context: AIExecutionContext) {
 return adapter.searchFiles({ query: "review", limit: 10 }, context);
}

`searchFiles.input.query`

Provider/host query text; syntax, authorization and limits are adapter-owned.

`searchFiles.input.mimeTypes`

Optional media-type filter for host workspace search.

`searchFiles.input.limit`

Optional result-count bound; default and maximum are owned by the connected adapter.

`readFile`

Read authorized file content and provider version metadata.

Parameters:

input: File identity and optional exact provider revision.
context: Verified host scope used for tenant/user access checks.

Returns: File/content pair when available, otherwise null.

Remarks

Requires a real host implementation and trusted execution context; Core supplies no provider credentials, default count limits or cancellation policy.

Errors and rejections

Host implementation errors/rejections propagate; successful Promise resolution must still be interpreted through the returned result/receipt.

Example:

import type { AIWorkspaceAdapter } from "@alneas/eaos-core/ai/host-adapters";
import type { AIExecutionContext } from "@alneas/eaos-core/ai/governance";
async function useHost(adapter: AIWorkspaceAdapter, context: AIExecutionContext) {
 return adapter.readFile({ fileId: "file-1" }, context);
}

`readFile.file`

Workspace file metadata accompanying returned file content.

`readFile.content`

Loaded skill instructions, model response text or proposed file content; treat external text as untrusted input.

`readFile.input.fileId`

Workspace file identity within the verified host account.

`readFile.input.version`

Optional provider revision to read; omission uses adapter-defined current-version behavior.

`proposeChange`

Prepare a reviewable file change without invoking applyChange.

Parameters:

input: File identity, mutation kind, optional expected version and content/rows.
context: Verified host scope used for tenant/user access checks.

Returns: The proposed structured change and human-readable summary.

Remarks

Requires a real host implementation and trusted execution context; Core supplies no provider credentials, default count limits or cancellation policy.

Errors and rejections

Host implementation errors/rejections propagate; successful Promise resolution must still be interpreted through the returned result/receipt.

Example:

import type { AIWorkspaceAdapter } from "@alneas/eaos-core/ai/host-adapters";
import type { AIExecutionContext } from "@alneas/eaos-core/ai/governance";
async function useHost(adapter: AIWorkspaceAdapter, context: AIExecutionContext) {
 return adapter.proposeChange({ fileId: "file-1", operation: "append", content: "Review notes" }, context);
}

`proposeChange.change`

Structured file change to review before an admitted apply operation.

`proposeChange.summary`

Human-readable review/result description suitable for host presentation.

`applyChange`

Request an admitted workspace mutation with optional version precondition.

Parameters:

input: Reviewed file change and optional optimistic provider version.
context: Verified host scope plus replay key and optional review/deadline/dry-run metadata.

Returns: Optional updated file descriptor and host receipt.

Remarks

Errors and rejections

Host implementation errors/rejections propagate; successful Promise resolution must still be interpreted through the returned result/receipt.

Example:

import type { AIWorkspaceAdapter, AIHostActionContext } from "@alneas/eaos-core/ai/host-adapters";
async function useHost(adapter: AIWorkspaceAdapter, context: AIHostActionContext) {
 return adapter.applyChange({ fileId: "file-1", operation: "append", content: "Review notes" }, context);
}

Example

See the owning declaration and linked feature guide for usage; no standalone example is documented in source.

[INTERFACE] `AIWorkspaceChange`

Proposed file content or row change with an optional optimistic version.

Imports: @alneas/eaos-core, @alneas/eaos-core/ai, @alneas/eaos-core/ai/host-adapters.

Signature

interface AIWorkspaceChange {
    fileId: string;
    operation: 'create' | 'replace' | 'append' | 'update';
    expectedVersion?: string;
    content?: string;
    rows?: readonly (readonly unknown[])[];
}

Parameters

Name	Type	Required	Description
`fileId`	`string`	Yes	Workspace file identity within the verified host account.
`operation`	`'create' \| 'replace' \| 'append' \| 'update'`	Yes	Operation identity whose meaning and permission are controlled by the host.
`expectedVersion`	`string`	No	Optional optimistic provider version that the host should check before mutation.
`content`	`string`	No	Loaded skill instructions, model response text or proposed file content; treat external text as untrusted input.
`rows`	`readonly (readonly unknown[])[]`	No	Optional row data for provider-supported spreadsheet changes.

Returns

Type declaration; no runtime value.

Public members

`fileId`

Workspace file identity within the verified host account.

`operation`

Operation identity whose meaning and permission are controlled by the host.

`expectedVersion`

Optional optimistic provider version that the host should check before mutation.

`content`

Loaded skill instructions, model response text or proposed file content; treat external text as untrusted input.

`rows`

Optional row data for provider-supported spreadsheet changes.

Example

See the owning declaration and linked feature guide for usage; no standalone example is documented in source.

[INTERFACE] `AIWorkspaceFile`

Workspace file identity, media type and optional version/location metadata.

Imports: @alneas/eaos-core, @alneas/eaos-core/ai, @alneas/eaos-core/ai/host-adapters.

Signature

interface AIWorkspaceFile {
    id: string;
    name: string;
    mimeType: string;
    version?: string;
    modifiedAt?: string;
    uri?: string;
}

Parameters

Name	Type	Required	Description
`id`	`string`	Yes	Provider workspace file identity within the authorized host account.
`name`	`string`	Yes	Human-readable display name supplied by the plugin/provider catalog; distinct from the stable ID.
`mimeType`	`string`	Yes	Provider media-type metadata for the workspace file.
`version`	`string`	No	Optional provider file revision for optimistic host changes.
`modifiedAt`	`string`	No	Optional provider-reported file modification timestamp.
`uri`	`string`	No	Optional provider location reference; it is not an authorization capability.

Returns

Type declaration; no runtime value.

Public members

`id`

Provider workspace file identity within the authorized host account.

`name`

Human-readable display name supplied by the plugin/provider catalog; distinct from the stable ID.

`mimeType`

Provider media-type metadata for the workspace file.

`version`

Optional provider file revision for optimistic host changes.

`modifiedAt`

Optional provider-reported file modification timestamp.

`uri`

Optional provider location reference; it is not an authorization capability.

Example

See the owning declaration and linked feature guide for usage; no standalone example is documented in source.

[FUNCTION] `analyzeLatestMetric`

Analyze the last metric point against prior points without persistence or side effects. Hosts/plugins own buffering, cooldowns, alert routing and durable audit records.

Imports: @alneas/eaos-core, @alneas/eaos-core/ai, @alneas/eaos-core/ai/anomaly.

Signature

declare function analyzeLatestMetric(input: {
    metric: string;
    points: readonly AINumericMetricPoint[];
    config?: AIAnomalyConfig;
}): readonly AIAnomalyResult[];

Parameters

Name	Type	Required	Description
`input`	`{ metric: string; points: readonly AINumericMetricPoint[]; config?: AIAnomalyConfig; }`	Yes	Nonempty metric name, nonempty finite observations ordered by timestamp, and optional detection configuration. Timestamp units are caller-defined and must be consistent.

Returns

readonly AIAnomalyResult[]

One result per configured algorithm, in configuration order; insufficient history yields detected false with sample counts.

Remarks

Defaults: 30 historical samples, sensitivity 0.95, zscore/iqr and ewmaAlpha 0.3. No buffering, alerts or durable audit records are created.

Errors and rejections

Error for invalid metric, observations or configuration. The current validator accepts zscore/iqr and rejects ewma even though the algorithm type includes it.

Public members

`input.metric`

Nonblank metric label included in each detector result.

`input.points`

Nonempty finite observations ordered by nondecreasing timestamp; the last point is tested against preceding history without changing the input array.

`input.config`

Optional detector settings; defaults are 30 prior samples, sensitivity 0.95, zscore/iqr and alpha 0.3. Current validation rejects ewma selection.

Example

import { analyzeLatestMetric } from "@alneas/eaos-core/ai/anomaly";
const results = analyzeLatestMetric({ metric: "latency", points: [{ timestamp: 1, value: 10 }, { timestamp: 2, value: 10 }, { timestamp: 3, value: 100 }], config: { minSamples: 2 } });
console.log(results.map(result => result.detected));

[INTERFACE] `ApiConfig`

URL prefix used by the host when mounting plugin APIs.

Imports: @alneas/eaos-core, @alneas/eaos-core/plugin-sdk, @alneas/eaos-core/plugin-sdk/types.

Signature

interface ApiConfig {
    prefix: string;
}

Parameters

Name	Type	Required	Description
`prefix`	`string`	Yes	API mount path or public API-key lookup prefix; neither value grants authorization.

Returns

Type declaration; no runtime value.

Public members

`prefix`

API mount path or public API-key lookup prefix; neither value grants authorization.

Example

See the owning declaration and linked feature guide for usage; no standalone example is documented in source.

[INTERFACE] `ApiKeyRecord`

Hash-only API key metadata suitable for host persistence and revocation checks.

Imports: @alneas/eaos-core, @alneas/eaos-core/security/platform-security.

Signature

interface ApiKeyRecord {
    id: string;
    prefix: string;
    hash: string;
    tenantId: string;
    userId: string;
    scopes: readonly string[];
    createdAt: string;
    expiresAt?: string | null;
    revokedAt?: string | null;
}

Parameters

Name	Type	Required	Description
`id`	`string`	Yes	Key-record identity used by host persistence; defaults to a random UUID at issuance.
`prefix`	`string`	Yes	API mount path or public API-key lookup prefix; neither value grants authorization.
`hash`	`string`	Yes	Content integrity digest; hashes are unkeyed and do not establish authorization or writer authenticity.
`tenantId`	`string`	Yes	Verified tenant boundary for the record or operation; host authorization must establish this scope.
`userId`	`string`	Yes	User identity within the tenant supplied by the trusted host.
`scopes`	`readonly string[]`	Yes	Exact API permission scope names associated with the verified identity/key.
`createdAt`	`string`	Yes	Creation timestamp supplied or generated by the owning API.
`expiresAt`	`string \| null`	No	Optional absolute expiry; the owning validation/evaluation API determines whether it remains live.
`revokedAt`	`string \| null`	No	Revocation timestamp when present; an active value disables use.

Returns

Type declaration; no runtime value.

Public members

`id`

Key-record identity used by host persistence; defaults to a random UUID at issuance.

`prefix`

API mount path or public API-key lookup prefix; neither value grants authorization.

`hash`

Content integrity digest; hashes are unkeyed and do not establish authorization or writer authenticity.

`tenantId`

Verified tenant boundary for the record or operation; host authorization must establish this scope.

`userId`

User identity within the tenant supplied by the trusted host.

`scopes`

Exact API permission scope names associated with the verified identity/key.

`createdAt`

Creation timestamp supplied or generated by the owning API.

`expiresAt`

Optional absolute expiry; the owning validation/evaluation API determines whether it remains live.

`revokedAt`

Revocation timestamp when present; an active value disables use.

Example

See the owning declaration and linked feature guide for usage; no standalone example is documented in source.

[INTERFACE] `ApprovalBinding`

A compact, non-secret identity for an approved operation. The input itself is deliberately not stored here; the host may retain it in its scoped proposal/job store and use inputHash to prove that it is unchanged.

Imports: @alneas/eaos-core, @alneas/eaos-core/agent/approved-execution.

Signature

interface ApprovalBinding {
    tenantId: string;
    requestedBy: string;
    operation: string;
    target?: ExecutionTarget;
    inputHash: string;
    contractHash: string;
    expiresAt?: string;
    bindingHash: string;
}

Parameters

Name	Type	Required	Description
`tenantId`	`string`	Yes	Verified tenant boundary for the record or operation; host authorization must establish this scope.
`requestedBy`	`string`	Yes	Verified identity of the requester whose approval binding is being constructed.
`operation`	`string`	Yes	Operation identity whose meaning and permission are controlled by the host.
`target`	`ExecutionTarget`	No	Approved resource identity or execution placement; this metadata does not independently enforce access.
`inputHash`	`string`	Yes	SHA-256 identity of the canonical JSON request input.
`contractHash`	`string`	Yes	SHA-256 identity of the captured versioned execution contract.
`expiresAt`	`string`	No	Optional absolute expiry; the owning validation/evaluation API determines whether it remains live.
`bindingHash`	`string`	Yes	SHA-256 integrity identity of the normalized approval binding.

Returns

Type declaration; no runtime value.

Public members

`tenantId`

Verified tenant boundary for the record or operation; host authorization must establish this scope.

`requestedBy`

Verified identity of the requester whose approval binding is being constructed.

`operation`

Operation identity whose meaning and permission are controlled by the host.

`target`

Approved resource identity or execution placement; this metadata does not independently enforce access.

`inputHash`

SHA-256 identity of the canonical JSON request input.

`contractHash`

SHA-256 identity of the captured versioned execution contract.

`expiresAt`

Optional absolute expiry; the owning validation/evaluation API determines whether it remains live.

`bindingHash`

SHA-256 integrity identity of the normalized approval binding.

Example

See the owning declaration and linked feature guide for usage; no standalone example is documented in source.

[INTERFACE] `ApprovalBindingInput`

Scope, request and contract whose exact identities an approval must bind.

Imports: @alneas/eaos-core, @alneas/eaos-core/agent/approved-execution.

Signature

interface ApprovalBindingInput {
    tenantId: string;
    requestedBy: string;
    operation: string;
    target?: ExecutionTarget;
    input: unknown;
    contract: ExecutionContract;
    expiresAt?: Date | string;
}

Parameters

Name	Type	Required	Description
`tenantId`	`string`	Yes	Verified tenant boundary for the record or operation; host authorization must establish this scope.
`requestedBy`	`string`	Yes	Verified identity of the requester whose approval binding is being constructed.
`operation`	`string`	Yes	Operation identity whose meaning and permission are controlled by the host.
`target`	`ExecutionTarget`	No	Approved resource identity or execution placement; this metadata does not independently enforce access.
`input`	`unknown`	Yes	Domain request value passed to the admitted operation; no domain-schema proof is implied solely by this type.
`contract`	`ExecutionContract`	Yes	Versioned operation metadata captured for input/policy compatibility and approval binding.
`expiresAt`	`Date \| string`	No	Optional absolute expiry for approvals that must be decided within a bounded window.

Returns

Type declaration; no runtime value.

Public members

`tenantId`

Verified tenant boundary for the record or operation; host authorization must establish this scope.

`requestedBy`

Verified identity of the requester whose approval binding is being constructed.

`operation`

Operation identity whose meaning and permission are controlled by the host.

`target`

Approved resource identity or execution placement; this metadata does not independently enforce access.

`input`

Domain request value passed to the admitted operation; no domain-schema proof is implied solely by this type.

`contract`

Versioned operation metadata captured for input/policy compatibility and approval binding.

`expiresAt`

Optional absolute expiry for approvals that must be decided within a bounded window.

Example

See the owning declaration and linked feature guide for usage; no standalone example is documented in source.

[FUNCTION] `approvalBindingMatches`

Compare a stored approval identity with the operation that is about to run.

Imports: @alneas/eaos-core, @alneas/eaos-core/agent/approved-execution.

Signature

declare function approvalBindingMatches(stored: ApprovalBinding, expected: ApprovalBindingInput | ApprovalBinding, options?: {
    now?: Date;
}): boolean;

Parameters

Name	Type	Required	Description
`stored`	`ApprovalBinding`	Yes	Stored identity to validate.
`expected`	`ApprovalBindingInput \| ApprovalBinding`	Yes	Expected binding or source input from which a binding is constructed.
`options`	`{ now?: Date; }`	No	Optional evaluation clock shared by both validations; defaults to current Date.

Returns

boolean

True when validated identities and request/contract hashes match; false on any validation or hashing error.

Remarks

No authorization, persistence or execution occurs.

Public members

`options.now`

Optional reference time shared by both binding validations; omission evaluates expiry against current Date values.

Example

import { approvalBindingMatches } from "@alneas/eaos-core/agent/approved-execution";
import { createApprovalBinding } from "@alneas/eaos-core/agent/approved-execution";
const input = { tenantId: "tenant-demo", requestedBy: "user-demo", operation: "note.read", input: { id: "note-1" }, contract: { operation: "note.read", version: "1.0.0", permission: "notes:read", sideEffect: "read", riskLevel: "low", approvalLevel: "L1_AUTO", inputSchema: { type: "object" } } } as const;
console.log(approvalBindingMatches(createApprovalBinding(input), input)); // true

[TYPE] `ApprovalLevel`

Ordered organizational approval categories from automatic to executive review.

Imports: @alneas/eaos-core, @alneas/eaos-core/security/gatekeeper.

Signature

type ApprovalLevel = 'L1_AUTO' | 'L2_LEAD' | 'L3_MANAGER' | 'L4_EXECUTIVE';

Parameters

Name	Type	Required	Description
—	—	—	No call parameters.

Returns

Type declaration; no runtime value.

Example

See the owning declaration and linked feature guide for usage; no standalone example is documented in source.

[INTERFACE] `ApprovedExecutionEvent`

Validated binding paired with the execution input carried by an outbox event.

Imports: @alneas/eaos-core, @alneas/eaos-core/agent/approved-execution.

Signature

interface ApprovedExecutionEvent<T = unknown> {
    binding: ApprovalBinding;
    input: T;
}

Parameters

Name	Type	Required	Description
`binding`	`ApprovalBinding`	Yes	Validated request/contract identity whose bindingHash is the outbox idempotency key.
`input`	`T`	Yes	Domain request value passed to the admitted operation; no domain-schema proof is implied solely by this type.

Returns

Type declaration; no runtime value.

Type parameters

T: Execution input type carried alongside the binding; defaults to unknown.

Public members

`binding`

Validated request/contract identity whose bindingHash is the outbox idempotency key.

`input`

Domain request value passed to the admitted operation; no domain-schema proof is implied solely by this type.

Example

See the owning declaration and linked feature guide for usage; no standalone example is documented in source.

[TYPE] `ArchiveMode`

Declared archival destination or retention deletion strategy; execution belongs to the host.

Imports: @alneas/eaos-core/plugin-sdk, @alneas/eaos-core/plugin-sdk/storage-policy.

Signature

type ArchiveMode = 'none' | 'object-storage' | 'cold-storage' | 'delete-after-retention';

Parameters

Name	Type	Required	Description
—	—	—	No call parameters.

Returns

Type declaration; no runtime value.

Example

See the owning declaration and linked feature guide for usage; no standalone example is documented in source.

[FUNCTION] `assertActiveConsent`

Require an active consent matching a tenant, user and purpose.

Imports: @alneas/eaos-core, @alneas/eaos-core/security/platform-security.

Signature

declare function assertActiveConsent(records: readonly ConsentRecord[], requirement: {
    tenantId: string;
    userId: string;
    purpose: string;
    version?: string;
    now?: Date;
}): void;

Parameters

Name	Type	Required	Description
`records`	`readonly ConsentRecord[]`	Yes	Trusted consent records passed to hasActiveConsent.
`requirement`	`{ tenantId: string; userId: string; purpose: string; version?: string; now?: Date; }`	Yes	Required scope/version and optional evaluation clock; omitted now uses current Date.

Returns

void

No value; successful completion means a matching consent exists.

Errors and rejections

Error when no active consent satisfies the requirement.

Public members

`requirement.tenantId`

Exact trusted tenant identity to match against consent records.

`requirement.userId`

Exact authenticated user identity whose grant must match within the tenant.

`requirement.purpose`

Exact consent purpose identifier; a grant for another purpose does not satisfy this requirement.

`requirement.version`

Optional exact consent revision; omission or an empty string accepts any recorded version.

`requirement.now`

Optional evaluation clock for grant-start/expiry checks; omission uses current Date. A matching record must be granted at or before this instant and unrevoked/unexpired.

Example

import { assertActiveConsent } from "@alneas/eaos-core/security/platform-security";
const records = [{ tenantId: "tenant-demo", userId: "user-demo", purpose: "summarization", version: "1", grantedAt: "2026-01-01T00:00:00Z" }];
const requirement = { tenantId: "tenant-demo", userId: "user-demo", purpose: "summarization", version: "1", now: new Date("2026-10-19T00:00:00Z") };
assertActiveConsent(records, requirement);

[FUNCTION] `assertBusinessDate`

Validate a real Gregorian calendar date in YYYY-MM-DD form.

Imports: @alneas/eaos-core/plugin-sdk, @alneas/eaos-core/plugin-sdk/data-standards.

Signature

declare function assertBusinessDate(value: unknown): asserts value is string;

Parameters

Name	Type	Required	Description
`value`	`unknown`	Yes	Date-only text, without time or timezone.

Returns

asserts value is string

No value; successful completion narrows value to string.

Errors and rejections

Error for invalid syntax or a date that does not round-trip through UTC.

Example

import { assertBusinessDate } from "@alneas/eaos-core/plugin-sdk/data-standards";
assertBusinessDate("2026-10-19");

[FUNCTION] `assertBusinessId`

Validate an opaque business identifier.

Imports: @alneas/eaos-core/plugin-sdk, @alneas/eaos-core/plugin-sdk/data-standards.

Signature

declare function assertBusinessId(value: unknown): asserts value is string;

Parameters

Name	Type	Required	Description
`value`	`unknown`	Yes	Nonempty text up to 256 UTF-16 code units, without surrounding whitespace or ASCII control characters.

Returns

asserts value is string

No value; successful completion narrows value to string.

Errors and rejections

Error when the business identity is invalid.

Example

import { assertBusinessId } from "@alneas/eaos-core/plugin-sdk/data-standards";
assertBusinessId("order-001");

[FUNCTION] `assertDataContractBinding`

Require a binding to resolve to the named contract and one of its owned tables.

Imports: @alneas/eaos-core, @alneas/eaos-core/data-contracts, @alneas/eaos-core/contracts/data-contracts.

Signature

declare function assertDataContractBinding(catalog: DataContractCatalog, binding: DataContractBinding): void;

Parameters

Name	Type	Required	Description
`catalog`	`DataContractCatalog`	Yes	Previously resolved contract/table ownership catalog.
`binding`	`DataContractBinding`	Yes	Contract ID, semver range, owned table and optional lowercase namespace.

Returns

void

No value; completion confirms version/table ownership compatibility.

Remarks

Does not grant data access or apply migrations.

Errors and rejections

Error for unknown contract, incompatible/invalid range, foreign table or invalid namespace.

Example

import { assertDataContractBinding } from "@alneas/eaos-core/contracts/data-contracts";
import { resolveDataContracts } from "@alneas/eaos-core/contracts/data-contracts";
const contract = { id: "notes", version: "1.0.0", description: "Tenant notes", schema: { type: "object", properties: { tenant_id: { type: "string" } }, required: ["tenant_id"], "x-db": { tableName: "notes" } }, migrations: [] };
const catalog = resolveDataContracts([contract], { notes: "^1.0.0" });
assertDataContractBinding(catalog, { contractId: "notes", version: "^1.0.0", table: "notes" });

[FUNCTION] `assertDecimalValue`

Validate a bounded exact decimal string.

Imports: @alneas/eaos-core/plugin-sdk, @alneas/eaos-core/plugin-sdk/decimal-values.

Signature

declare function assertDecimalValue(value: unknown): asserts value is string;

Parameters

Name	Type	Required	Description
`value`	`unknown`	Yes	Decimal text without exponent notation, leading plus or leading zeroes; at most 38 digits, scale 18, length 40.

Returns

asserts value is string

No value; successful completion narrows value to string.

Errors and rejections

Error when the value violates decimalValueSchema.

Example

import { assertDecimalValue } from "@alneas/eaos-core/plugin-sdk/decimal-values";
assertDecimalValue("12.50");

[FUNCTION] `assertGraphProjectionResult`

Fail closed when a graph provider returns a foreign tenant or malformed projection.

Imports: @alneas/eaos-core, @alneas/eaos-core/workflow-runtime.

Signature

declare function assertGraphProjectionResult(result: GraphProjectionQueryResult, tenantId: string): GraphProjectionQueryResult;

Parameters

Name	Type	Required	Description
`result`	`GraphProjectionQueryResult`	Yes	Provider result with a parseable projection timestamp, unique nodes, tenant-matching edges and endpoints present in nodes.
`tenantId`	`string`	Yes	Expected nonempty tenant ID, up to 256 characters.

Returns

GraphProjectionQueryResult

The same result object, without a defensive clone.

Errors and rejections

Error for malformed scope/timestamp/nodes/edges, foreign tenants, duplicate nodes or invalid optional source revision.

Example

import { assertGraphProjectionResult } from "@alneas/eaos-core/workflow-runtime";
console.log(assertGraphProjectionResult({ tenantId: "tenant-demo", nodes: [], edges: [], projectedAt: "2026-10-19T00:00:00Z", stale: false }, "tenant-demo"));

[FUNCTION] `assertInstant`

Validate an ISO-style timestamp with an explicit timezone.

Imports: @alneas/eaos-core/plugin-sdk, @alneas/eaos-core/plugin-sdk/data-standards.

Signature

declare function assertInstant(value: unknown): asserts value is string;

Parameters

Name	Type	Required	Description
`value`	`unknown`	Yes	Timestamp with seconds and Z or numeric timezone offset; optional 1–9 fractional digits.

Returns

asserts value is string

No value; successful completion narrows value to string.

Errors and rejections

Error for invalid timestamp syntax, date, hour/minute/second or an unparseable instant.

Example

import { assertInstant } from "@alneas/eaos-core/plugin-sdk/data-standards";
assertInstant("2026-10-19T10:00:00+09:00");

[FUNCTION] `assertJsonDocumentContracts`

Validate logical JSON document identities, ownership routes and physical column bindings.

Imports: @alneas/eaos-core, @alneas/eaos-core/data-contracts, @alneas/eaos-core/contracts/data-contracts, @alneas/eaos-core/contracts/json-documents.

Signature

declare function assertJsonDocumentContracts(documents: readonly JsonDocumentContract[], tables: ReadonlyMap<string, Record<string, unknown>>): void;

Parameters

Name	Type	Required	Description
`documents`	`readonly JsonDocumentContract[]`	Yes	Unique document IDs and route tuples, closed object schemas, semver versions and optional ownership/size policies.
`tables`	`ReadonlyMap<string, Record<string, unknown>>`	Yes	Physical schema map whose properties contain every referenced document column.

Returns

void

No value; completion confirms declaration compatibility, without compiling schemas or applying changes.

Errors and rejections

Error for invalid/duplicate identity/routes, missing columns, invalid namespace/prefix/path, nonclosed schema or invalid byte/immutability policy.

Example

import { assertJsonDocumentContracts } from "@alneas/eaos-core/contracts/json-documents";
const document = { id: "notes.body", version: "1.0.0", table: "notes", column: "payload", schema: { type: "object", properties: { title: { type: "string" } }, required: ["title"], additionalProperties: false } };
assertJsonDocumentContracts([document], new Map([["notes", { properties: { payload: { type: "string" } } }]]));

[FUNCTION] `assertMoneyMinor`

Validate a monetary amount already expressed in minor units.

Imports: @alneas/eaos-core/plugin-sdk, @alneas/eaos-core/plugin-sdk/data-standards.

Signature

declare function assertMoneyMinor(value: unknown, nonnegative?: boolean): asserts value is number;

Parameters

Name	Type	Required	Description
`value`	`unknown`	Yes	Safe integer amount; no currency conversion is performed.
`nonnegative`	`boolean`	No	Reject negative amounts when true; defaults to false.

Returns

asserts value is number

No value; successful completion narrows value to number.

Errors and rejections

Error for a nonsafe integer or a prohibited negative amount.

Example

import { assertMoneyMinor } from "@alneas/eaos-core/plugin-sdk/data-standards";
assertMoneyMinor(1250, true);

[FUNCTION] `assertPayloadWithinPolicy`

Serialize a payload and enforce its UTF-8 storage size limit.

Imports: @alneas/eaos-core/plugin-sdk, @alneas/eaos-core/plugin-sdk/storage-policy.

Signature

declare function assertPayloadWithinPolicy(policy: PluginStoragePolicy, value: unknown): string;

Parameters

Name	Type	Required	Description
`policy`	`PluginStoragePolicy`	Yes	Storage constraints validated before serialization.
`value`	`unknown`	Yes	Value passed to JSON.stringify; top-level undefined is rejected.

Returns

string

Serialized JSON when it fits the byte limit.

Remarks

Uses TextEncoder; native JSON serialization semantics, including toJSON, apply.

Errors and rejections

Error for invalid policy, missing JSON output or oversized output; JSON.stringify errors, including cycles and bigint, propagate.

Example

import { assertPayloadWithinPolicy } from "@alneas/eaos-core/plugin-sdk/storage-policy";
const policy = { maxPayloadBytes: 1024, objectStorage: "optional", historyRetentionDays: null, archive: { mode: "none" } } as const;
console.log(assertPayloadWithinPolicy(policy, { message: "hello" }));

[FUNCTION] `assertPlatformPrincipal`

Validate the required shape of a host-verified principal.

Imports: @alneas/eaos-core, @alneas/eaos-core/security/platform-security.

Signature

declare function assertPlatformPrincipal(value: PlatformPrincipal): void;

Parameters

Name	Type	Required	Description
`value`	`PlatformPrincipal`	Yes	Nonblank user/tenant IDs and nonblank role/scope entries; roles may be empty.

Returns

void

No value; completion confirms shape only.

Remarks

Does not authenticate a user or authorize operations; the host must establish principal trust.

Errors and rejections

Error when the principal shape is invalid.

Example

import { assertPlatformPrincipal } from "@alneas/eaos-core/security/platform-security";
assertPlatformPrincipal({ userId: "user-demo", tenantId: "tenant-demo", roles: ["member"] });

[FUNCTION] `assertPluginEntitlement`

Validate plugin admission and optional metering requirements.

Imports: @alneas/eaos-core, @alneas/eaos-core/plugin-sdk, @alneas/eaos-core/entitlements.

Signature

declare function assertPluginEntitlement(value: PluginEntitlement): void;

Parameters

Name	Type	Required	Description
`value`	`PluginEntitlement`	Yes	Policy; pro requires an addon ID, corporate requires a nonempty tenant allowlist, and quotas must be nonnegative safe integers.

Returns

void

No value; completion confirms structural policy validity.

Errors and rejections

Error for invalid tier, identifiers, allowlist or metering settings.

Example

import { assertPluginEntitlement } from "@alneas/eaos-core/entitlements";
assertPluginEntitlement({ tier: "public" });

[FUNCTION] `assertPluginStoragePolicy`

Validate and normalize record retention and storage constraints.

Imports: @alneas/eaos-core/plugin-sdk, @alneas/eaos-core/plugin-sdk/storage-policy.

Signature

declare function assertPluginStoragePolicy(policy: PluginStoragePolicy): PluginStoragePolicy;

Parameters

Name	Type	Required	Description
`policy`	`PluginStoragePolicy`	Yes	Policy with a positive safe-integer payload limit up to 64 MiB, positive retention days or null, and a compatible archive policy.

Returns

PluginStoragePolicy

A new policy object with a new archive object.

Remarks

Validation does not schedule archives, delete records or provision object storage.

Errors and rejections

Error for invalid values, missing archive delay, archive delay with none, indefinite delete retention, or external archives when object storage is forbidden.

Example

import { assertPluginStoragePolicy } from "@alneas/eaos-core/plugin-sdk/storage-policy";
const policy = assertPluginStoragePolicy({ maxPayloadBytes: 1024, objectStorage: "optional", historyRetentionDays: null, archive: { mode: "none" } });
console.log(policy.maxPayloadBytes);

[FUNCTION] `assertStorageBudget`

Validate host-defined per-plane byte limits and a warning threshold.

Imports: @alneas/eaos-core, @alneas/eaos-core/storage.

Signature

declare function assertStorageBudget(value: StorageBudget): StorageBudget;

Parameters

Name	Type	Required	Description
`value`	`StorageBudget`	Yes	Tenant budget with nonnegative safe-integer limits; optional warnAtRatio must be greater than zero and at most one.

Returns

StorageBudget

The original budget object.

Remarks

Missing planes have no framework limit; validation does not enforce capacity.

Errors and rejections

Error for an invalid tenant, plane, byte limit or warning ratio.

Example

import { assertStorageBudget } from "@alneas/eaos-core/storage";
console.log(assertStorageBudget({ tenantId: "tenant-demo", limits: { object: 1048576 }, warnAtRatio: 0.8 }));

[FUNCTION] `assertStorageUsage`

Validate host-reported usage before it is used for quota or cost decisions.

Imports: @alneas/eaos-core, @alneas/eaos-core/storage.

Signature

declare function assertStorageUsage(value: StorageUsage): StorageUsage;

Parameters

Name	Type	Required	Description
`value`	`StorageUsage`	Yes	Tenant-scoped usage with a parseable measuredAt and nonnegative safe-integer byte/item counts for known planes.

Returns

StorageUsage

The original object, without copying or freezing it.

Remarks

Does not measure storage or authorize the tenant scope.

Errors and rejections

Error for an invalid tenant, timestamp, plane or count.

Example

import { assertStorageUsage } from "@alneas/eaos-core/storage";
const usage = assertStorageUsage({ tenantId: "tenant-demo", measuredAt: "2026-10-19T00:00:00Z", bytes: { database: 1024 } });
console.log(usage.bytes.database);

[FUNCTION] `assertTenantEntitlements`

Validate a host-provided tenant subscription snapshot.

Imports: @alneas/eaos-core, @alneas/eaos-core/plugin-sdk, @alneas/eaos-core/entitlements.

Signature

declare function assertTenantEntitlements(value: TenantEntitlements): void;

Parameters

Name	Type	Required	Description
`value`	`TenantEntitlements`	Yes	Tenant ID, plan/status, addon IDs, optional parseable expiry and nonnegative safe-integer quota overrides.

Returns

void

No value; completion confirms snapshot shape, without checking freshness.

Errors and rejections

Error for invalid identity, plan/status, expiry, addon IDs or quota overrides.

Example

import { assertTenantEntitlements } from "@alneas/eaos-core/entitlements";
assertTenantEntitlements({ tenantId: "tenant-demo", plan: "free", status: "active", addons: [] });

[FUNCTION] `assertVectorSearchHits`

Reject provider results that cross a tenant boundary or contain unusable scores.

Imports: @alneas/eaos-core, @alneas/eaos-core/vector.

Signature

declare function assertVectorSearchHits(hits: readonly VectorSearchHit[], tenantId: string): readonly VectorSearchHit[];

Parameters

Name	Type	Required	Description
`hits`	`readonly VectorSearchHit[]`	Yes	Provider results; IDs must be unique and scores finite.
`tenantId`	`string`	Yes	Expected nonempty tenant ID, at most 256 characters.

Returns

readonly VectorSearchHit[]

The original hit array, including an empty array when no results exist.

Remarks

Score range and ordering remain provider-defined.

Errors and rejections

Error for invalid scope, foreign-tenant results, invalid/duplicate IDs or nonfinite scores.

Example

import { assertVectorSearchHits } from "@alneas/eaos-core/vector";
console.log(assertVectorSearchHits([], "tenant-demo")); // []

[FUNCTION] `assertVectorSearchRequest`

Validate tenant scope, query vector and bounded result count.

Imports: @alneas/eaos-core, @alneas/eaos-core/vector.

Signature

declare function assertVectorSearchRequest(input: VectorSearchRequest): VectorSearchRequest;

Parameters

Name	Type	Required	Description
`input`	`VectorSearchRequest`	Yes	Nonempty tenant/index IDs up to 256 characters, nonempty finite vector and integer topK from 1 to 10000.

Returns

VectorSearchRequest

The original request object; filters are not validated by this helper.

Remarks

The host validates index authorization, vector dimension and filter semantics.

Errors and rejections

Error for an invalid identity, vector or result count.

Example

import { assertVectorSearchRequest } from "@alneas/eaos-core/vector";
console.log(assertVectorSearchRequest({ tenantId: "tenant-demo", indexId: "documents", queryVector: [0.1, 0.2], topK: 10 }));

[INTERFACE] `AuditSink`

Host-owned durable append port; successful completion must mean the event was accepted according to host persistence policy.

Imports: @alneas/eaos-core/security/audit-sink.

Signature

interface AuditSink<T> {
    append(event: Readonly<T>): Promise<void>;
}

Parameters

Name	Type	Required	Description
`append`	`Promise<void>`	Yes	Append an audit event to host durable storage.

Returns

Type declaration; no runtime value.

Type parameters

T: Event shape accepted by the host append implementation; caller controls its persistence schema.

Public members

`append`

Append an audit event to host durable storage.

Parameters:

event: Readonly event delivered by the caller; protect sensitive metadata and enforce tenant scope.

Returns: No value; completion must mean accepted according to the host durability policy.

Remarks

Host defines transactions, ordering, replay/idempotency and partial-write reconciliation; a rejection can follow a committed effect.

Errors and rejections

Host persistence failures reject the Promise.

Example:

import type { AuditSink } from "@alneas/eaos-core/security/audit-sink";
async function appendHostAudit(sink: AuditSink<{ action: string }>, event: { action: string }) { await sink.append(event); }

Example

See the owning declaration and linked feature guide for usage; no standalone example is documented in source.

[TYPE] `AuthUiFlow`

Authentication UI flows whose routes may be overridden.

Imports: @alneas/eaos-core/platform/config.

Signature

type AuthUiFlow = 'login' | 'registration' | 'error' | 'settings' | 'recovery' | 'verification' | 'logout';

Parameters

Name	Type	Required	Description
—	—	—	No call parameters.

Returns

Type declaration; no runtime value.

Example

See the owning declaration and linked feature guide for usage; no standalone example is documented in source.

[INTERFACE] `BundlePlugin`

A plugin-shaped value that can be included in an operator bundle.

Imports: @alneas/eaos-core, @alneas/eaos-core/plugin-bundles.

Signature

interface BundlePlugin {
    id: string;
}

Parameters

Name	Type	Required	Description
`id`	`string`	Yes	Plugin identity used for bundle ID projection and deduplication.

Returns

Type declaration; no runtime value.

Public members

`id`

Plugin identity used for bundle ID projection and deduplication.

Example

See the owning declaration and linked feature guide for usage; no standalone example is documented in source.

[FUNCTION] `bundlePluginIds`

Convert a manifest catalog into the ID map accepted by LifecycleProject.bundles.

Imports: @alneas/eaos-core, @alneas/eaos-core/plugin-bundles.

Signature

declare function bundlePluginIds<T extends BundlePlugin, C extends PluginBundleCatalog<T>>(catalog: C): {
    [K in keyof C]: readonly string[];
};

Parameters

Name	Type	Required	Description
`catalog`	`C`	Yes	Named ordered plugin lists; IDs are copied without validation or deduplication.

Returns

{ [K in keyof C]: readonly string[]; }

A new object with the same enumerable bundle keys and fresh arrays of plugin IDs.

Type parameters

T: Plugin-shaped values with an ID.
C: Catalog whose keys are preserved in the result type.

Example

import { bundlePluginIds } from "@alneas/eaos-core/plugin-bundles";
console.log(bundlePluginIds({ basic: [{ id: "notes" }] })); // { basic: ["notes"] }

[INTERFACE] `CacheEntry`

Cached result reference and absolute expiry in Unix epoch milliseconds.

Imports: @alneas/eaos-core/agent/cache-manager.

Signature

interface CacheEntry {
    data: unknown;
    expiresAt: number;
}

Parameters

Name	Type	Required	Description
`data`	`unknown`	Yes	Structured draft/event data or cached result; serialization and validation occur at the owning API boundary.
`expiresAt`	`number`	Yes	Optional absolute expiry; the owning validation/evaluation API determines whether it remains live.

Returns

Type declaration; no runtime value.

Public members

`data`

Structured draft/event data or cached result; serialization and validation occur at the owning API boundary.

`expiresAt`

Optional absolute expiry; the owning validation/evaluation API determines whether it remains live.

Example

See the owning declaration and linked feature guide for usage; no standalone example is documented in source.

[FUNCTION] `calculateRetryDelay`

Calculate one retry delay. Randomness is injected by the host so this helper stays pure and testable.

Imports: @alneas/eaos-core, @alneas/eaos-core/ai, @alneas/eaos-core/ai/resilience.

Signature

declare function calculateRetryDelay(input: {
    attempt: number;
    policy: AIRetryPolicy;
    random?: number;
}): number;

Parameters

Name	Type	Required	Description
`input`	`{ attempt: number; policy: AIRetryPolicy; random?: number; }`	Yes	One-based attempt, retry policy and random factor in [0, 1] (defaults to 0). Delay fields use milliseconds; multiplier must be at least 1 and jitter factor in [0, 1].

Returns

number

Delay in milliseconds, capped at maxDelayMs. maxAttempts is validated but does not stop an attempt exceeding it.

Remarks

Does not sleep or execute retries; the caller owns retry count, cancellation and idempotency.

Errors and rejections

Error for invalid attempt, policy or random factor.

Public members

`input.attempt`

Positive safe-integer one-based attempt used for exponentiation; the helper does not reject attempts exceeding policy.maxAttempts.

`input.policy`

Validated retry parameters; millisecond delays must be finite/nonnegative, multiplier at least one, jitter in [0,1] and maxAttempts a positive safe integer.

`input.random`

Optional finite injected random factor from zero to one; defaults to zero, producing no added jitter. The helper does not draw randomness.

Example

import { calculateRetryDelay } from "@alneas/eaos-core/ai/resilience";
const delay = calculateRetryDelay({ attempt: 2, policy: { maxAttempts: 3, baseDelayMs: 100, maxDelayMs: 1000, backoffMultiplier: 2, jitterFactor: 0 } });
console.log(delay); // 200

[FUNCTION] `canonicalJson`

Deterministic JSON for hashes, cursors and identity keys.

Imports: @alneas/eaos-core, @alneas/eaos-core/serialization, @alneas/eaos-core/serialization/json.

Signature

declare function canonicalJson(value: unknown, options?: CanonicalJsonOptions): string;

Parameters

Name	Type	Required	Description
`value`	`unknown`	Yes	Acyclic JSON data; strict mode permits only plain objects, dense arrays, finite numbers, strings, booleans and null.
`options`	`CanonicalJsonOptions`	No	Serialization mode; strict defaults to true. With strict false, JSON.stringify/parse normalization runs before sorting.

Returns

string

The deterministic JSON text; array order is preserved.

Errors and rejections

Error for unsupported strict values, cycles, sparse or decorated arrays; native JSON serialization errors propagate in non-strict mode.

Example

import { canonicalJson } from "@alneas/eaos-core/serialization/json";
console.log(canonicalJson({ b: 2, a: 1 })); // {"a":1,"b":2}

[FUNCTION] `canonicalJsonHash`

Hash strict canonical JSON with SHA-256.

Imports: @alneas/eaos-core, @alneas/eaos-core/serialization.

Signature

declare function canonicalJsonHash(value: unknown): string;

Parameters

Name	Type	Required	Description
`value`	`unknown`	Yes	Data accepted by canonicalJson in strict mode.

Returns

string

The lowercase hexadecimal digest of the canonical JSON text.

Remarks

Requires node:crypto; does not persist or sign the data.

Errors and rejections

Error when canonicalJson rejects non-JSON data or cycles.

Example

import { canonicalJsonHash } from "@alneas/eaos-core/serialization";
console.log(canonicalJsonHash({ a: 1 }));

[INTERFACE] `CanonicalJsonOptions`

Control normalization before deterministic serialization.

Imports: @alneas/eaos-core, @alneas/eaos-core/serialization, @alneas/eaos-core/serialization/json.

Signature

interface CanonicalJsonOptions {
    strict?: boolean;
}

Parameters

Name	Type	Required	Description
`strict`	`boolean`	No	Reject non-JSON values instead of normalizing with JSON.stringify/parse.

Returns

Type declaration; no runtime value.

Public members

`strict`

Reject non-JSON values instead of normalizing with JSON.stringify/parse.

Default: true.

Example

See the owning declaration and linked feature guide for usage; no standalone example is documented in source.

[FUNCTION] `classifyAIError`

Classify an error using host/plugin-provided rules without logging or side effects. The first matching rule wins, so callers should order rules from specific to broad.

Imports: @alneas/eaos-core, @alneas/eaos-core/ai, @alneas/eaos-core/ai/resilience.

Signature

declare function classifyAIError(input: {
    error: unknown;
    rules: readonly AIErrorClassificationRule[];
    context?: Readonly<Record<string, unknown>>;
}): AIErrorClassification;

Parameters

Name	Type	Required	Description
`input`	`{ error: unknown; rules: readonly AIErrorClassificationRule[]; context?: Readonly<Record<string, unknown>>; }`	Yes	Error, ordered regular-expression rules and optional context. First matching message or stack wins; context is retained by reference.

Returns

AIErrorClassification

Classification, falling back to ERR_UNKNOWN/business/error/nonretryable when no rule matches.

Remarks

Does not log, retry or mutate host state.

Errors and rejections

SyntaxError when an evaluated rule contains an invalid regular expression.

Public members

`input.error`

Error, text or message-bearing object to classify; unsupported shapes use the message Unknown error. Error stack text also participates in matching.

`input.rules`

Ordered case-insensitive regular-expression rules; first matching message/stack wins and invalid evaluated regex syntax throws.

`input.context`

Optional readonly host metadata retained by reference in the classification; this helper neither logs nor redacts its contents.

Example

import { classifyAIError } from "@alneas/eaos-core/ai/resilience";
const result = classifyAIError({ error: new Error("timeout"), rules: [] });
console.log(result.code); // ERR_UNKNOWN

[TYPE] `ClientTarget`

Client channels a plugin advertises to hosts.

Imports: @alneas/eaos-core, @alneas/eaos-core/plugin-sdk, @alneas/eaos-core/plugin-sdk/types.

Signature

type ClientTarget = 'web' | 'line' | 'ios';

Parameters

Name	Type	Required	Description
—	—	—	No call parameters.

Returns

Type declaration; no runtime value.

Example

See the owning declaration and linked feature guide for usage; no standalone example is documented in source.

[FUNCTION] `collectSchemaMigrations`

Read-only migration inventory for offline tooling and isolated test bootstrap; never applies SQL.

Imports: @alneas/eaos-core, @alneas/eaos-core/data-contracts, @alneas/eaos-core/contracts/data-contracts.

Signature

declare function collectSchemaMigrations(releases: readonly SchemaMigrationSource[], available?: readonly DataContract[]): PluginMigration[];

Parameters

Name	Type	Required	Description
`releases`	`readonly SchemaMigrationSource[]`	Yes	Plugin/release sources in desired order; each dependency set is checked.
`available`	`readonly DataContract[]`	No	Additional shared contract releases; defaults to empty. Conflicting definitions with the same ID are rejected.

Returns

PluginMigration[]

A new migration list with dependency-ordered shared migrations followed by source migrations; entries retain source references.

Remarks

Read-only inventory for offline tooling/test bootstrap; it does not prove that SQL has been applied.

Errors and rejections

Error for conflicting contracts or any resolveDataContracts validation/resolution failure.

Example

import { collectSchemaMigrations } from "@alneas/eaos-core/contracts/data-contracts";
console.log(collectSchemaMigrations([{ migrations: [] }])); // []

[FUNCTION] `compareInputSchemaCompatibility`

Returns only input changes that can break an existing caller. Optional additions are compatible.

Imports: @alneas/eaos-core, @alneas/eaos-core/plugin-sdk, @alneas/eaos-core/plugin-sdk/contract-compatibility.

Signature

declare function compareInputSchemaCompatibility(previous: Record<string, unknown>, current: Record<string, unknown>): string[];

Parameters

Name	Type	Required	Description
`previous`	`Record<string, unknown>`	Yes	Previously captured object schema.
`current`	`Record<string, unknown>`	Yes	Replacement object schema.

Returns

string[]

Human-readable issues for removed properties, new required properties, changed explicit types or narrowed enums; empty means no checked break was found.

Remarks

Checks direct properties/required/type/enum only, not general JSON Schema compatibility. Optional additions are accepted.

Example

import { compareInputSchemaCompatibility } from "@alneas/eaos-core/plugin-sdk/contract-compatibility";
console.log(compareInputSchemaCompatibility({ properties: { title: { type: "string" } } }, { properties: { title: { type: "number" } } }));

[FUNCTION] `compareOutputSchemaCompatibility`

Returns only output changes that can break an existing consumer. Optional additions are compatible.

Imports: @alneas/eaos-core, @alneas/eaos-core/plugin-sdk, @alneas/eaos-core/plugin-sdk/contract-compatibility.

Signature

declare function compareOutputSchemaCompatibility(previous: Record<string, unknown> | undefined, current: Record<string, unknown> | undefined): string[];

Parameters

Name	Type	Required	Description
`previous`	`Record<string, unknown> \| undefined`	Yes	Previous output schema; undefined disables comparison.
`current`	`Record<string, unknown> \| undefined`	Yes	Replacement output schema; undefined disables comparison.

Returns

string[]

Human-readable issues; empty when either schema is absent or no checked break exists.

Remarks

Checks removed required properties and explicit type changes only; not a full JSON Schema substitutability check.

Example

import { compareOutputSchemaCompatibility } from "@alneas/eaos-core/plugin-sdk/contract-compatibility";
console.log(compareOutputSchemaCompatibility(undefined, { type: "object" })); // []

[FUNCTION] `comparePluginContractSnapshots`

Report removed tools, checked schema breaks and policy changes between snapshots.

Imports: @alneas/eaos-core, @alneas/eaos-core/plugin-sdk, @alneas/eaos-core/plugin-sdk/contract-compatibility.

Signature

declare function comparePluginContractSnapshots(previous: PluginContractSnapshot, current: PluginContractSnapshot): ContractCompatibilityReport;

Parameters

Name	Type	Required	Description
`previous`	`PluginContractSnapshot`	Yes	Previously admitted snapshot.
`current`	`PluginContractSnapshot`	Yes	Candidate replacement snapshot; tool matching uses exact names.

Returns

ContractCompatibilityReport

Compatibility plus detailed issues; newly added tools and unexamined schema changes produce no issue.

Remarks

Does not verify hashes, compare plugin identities or enforce migration. Policy changes invalidate reuse of approvals at the host boundary.

Example

import { comparePluginContractSnapshots } from "@alneas/eaos-core/plugin-sdk/contract-compatibility";
const previous = { pluginId: "notes", pluginVersion: "1.0.0", tools: [], hash: "unused-for-comparison" };
console.log(comparePluginContractSnapshots(previous, { ...previous, pluginVersion: "1.1.0" }).compatible); // true

[FUNCTION] `computePayloadHash`

Compute a SHA-256 digest of exact payload text.

Imports: @alneas/eaos-core, @alneas/eaos-core/webhook, @alneas/eaos-core/webhook/delivery.

Signature

declare function computePayloadHash(payload: string): string;

Parameters

Name	Type	Required	Description
`payload`	`string`	Yes	UTF-8 text to hash; no JSON normalization occurs.

Returns

string

Lowercase hexadecimal digest.

Remarks

Requires node:crypto; a hash is not an authenticated signature.

Example

import { computePayloadHash } from "@alneas/eaos-core/webhook/delivery";
console.log(computePayloadHash("{}"));

[TYPE] `ConfigSource`

Provenance labels recorded for normalized inputs and derived outputs.

Imports: @alneas/eaos-core/platform/config.

Signature

type ConfigSource = 'default' | 'app' | 'environment' | 'derived';

Parameters

Name	Type	Required	Description
—	—	—	No call parameters.

Returns

Type declaration; no runtime value.

Example

See the owning declaration and linked feature guide for usage; no standalone example is documented in source.

[INTERFACE] `ConnectionStats`

Current connection count, configured pool size and driver family.

Imports: @alneas/eaos-core, @alneas/eaos-core/db, @alneas/eaos-core/db/adapter.

Signature

interface ConnectionStats {
    activeConnections: number;
    poolSize: number;
    driver: DbDriverType;
}

Parameters

Name	Type	Required	Description
`activeConnections`	`number`	Yes	Host-reported number of connections currently active.
`poolSize`	`number`	Yes	Host-reported configured connection-pool capacity.
`driver`	`DbDriverType`	Yes	Database driver family reporting these statistics.

Returns

Type declaration; no runtime value.

Public members

`activeConnections`

Host-reported number of connections currently active.

`poolSize`

Host-reported configured connection-pool capacity.

`driver`

Database driver family reporting these statistics.

Example

See the owning declaration and linked feature guide for usage; no standalone example is documented in source.

[INTERFACE] `ConsentRecord`

Tenant/user consent grant for a versioned purpose with optional expiry or revocation.

Imports: @alneas/eaos-core, @alneas/eaos-core/security/platform-security.

Signature

interface ConsentRecord {
    tenantId: string;
    userId: string;
    purpose: string;
    version: string;
    grantedAt: string;
    expiresAt?: string | null;
    revokedAt?: string | null;
}

Parameters

Name	Type	Required	Description
`tenantId`	`string`	Yes	Verified tenant boundary for the record or operation; host authorization must establish this scope.
`userId`	`string`	Yes	User identity within the tenant supplied by the trusted host.
`purpose`	`string`	Yes	Named consent or agent-task purpose used by host policy evaluation.
`version`	`string`	Yes	Consent text/purpose revision accepted by the user.
`grantedAt`	`string`	Yes	Parseable timestamp when consent begins; future grants do not count as active.
`expiresAt`	`string \| null`	No	Optional absolute expiry; the owning validation/evaluation API determines whether it remains live.
`revokedAt`	`string \| null`	No	Revocation timestamp when present; an active value disables use.

Returns

Type declaration; no runtime value.

Public members

`tenantId`

Verified tenant boundary for the record or operation; host authorization must establish this scope.

`userId`

User identity within the tenant supplied by the trusted host.

`purpose`

Named consent or agent-task purpose used by host policy evaluation.

`version`

Consent text/purpose revision accepted by the user.

`grantedAt`

Parseable timestamp when consent begins; future grants do not count as active.

`expiresAt`

Optional absolute expiry; the owning validation/evaluation API determines whether it remains live.

`revokedAt`

Revocation timestamp when present; an active value disables use.

Example

See the owning declaration and linked feature guide for usage; no standalone example is documented in source.

[INTERFACE] `ContentAdapter`

Compatibility re-export; its implementation and documentation are owned by the owning package @dataarthub/app-core.

Imports: @alneas/eaos-core, @alneas/eaos-core/adapters, @alneas/eaos-core/adapters/types.

Signature

export interface ContentAdapter {
    get(slug: string): Promise<ContentItem | null>;
    list(filter?: ContentFilter): Promise<ContentItem[]>;
    save(item: ContentItem): Promise<void>;
    delete(slug: string): Promise<void>;
    sync(items: ContentItem[], options?: {
        deleteMissing?: boolean;
    }): Promise<ContentSyncResult>;
    build?(command?: string): Promise<BuildResult>;
    deploy?(outputDir: string, target: {
        upload: (key: string, data: Buffer, options?: any) => Promise<any>;
    }): Promise<DeployResult>;
}

Parameters

Name	Type	Required	Description
`get`	`Promise<ContentItem \| null>`	Yes	See the upstream owning declaration.
`list`	`Promise<ContentItem[]>`	Yes	See the upstream owning declaration.
`save`	`Promise<void>`	Yes	See the upstream owning declaration.
`delete`	`Promise<void>`	Yes	See the upstream owning declaration.
`sync`	`Promise<ContentSyncResult>`	Yes	See the upstream owning declaration.
`build`	`Promise<BuildResult>`	No	See the upstream owning declaration.
`deploy`	`Promise<DeployResult>`	No	See the upstream owning declaration.

Returns

Type declaration; no runtime value.

Example

See the owning declaration and linked feature guide for usage; no standalone example is documented in source.

[INTERFACE] `ContentFilter`

Compatibility re-export; its implementation and documentation are owned by the owning package @dataarthub/app-core.

Imports: @alneas/eaos-core, @alneas/eaos-core/adapters, @alneas/eaos-core/adapters/types.

Signature

export interface ContentFilter {
    contentType?: string;
    status?: ContentItem['status'];
    tags?: string[];
    author?: string;
    search?: string;
    publishedAfter?: string;
    publishedBefore?: string;
    erpManagedOnly?: boolean;
    limit?: number;
    offset?: number;
    sort?: Record<string, 1 | -1>;
}

Parameters

Name	Type	Required	Description
`contentType`	`string`	No	See the upstream owning declaration.
`status`	`ContentItem['status']`	No	See the upstream owning declaration.
`tags`	`string[]`	No	See the upstream owning declaration.
`author`	`string`	No	See the upstream owning declaration.
`search`	`string`	No	See the upstream owning declaration.
`publishedAfter`	`string`	No	See the upstream owning declaration.
`publishedBefore`	`string`	No	See the upstream owning declaration.
`erpManagedOnly`	`boolean`	No	See the upstream owning declaration.
`limit`	`number`	No	See the upstream owning declaration.
`offset`	`number`	No	See the upstream owning declaration.
`sort`	`Record<string, 1 \| -1>`	No	See the upstream owning declaration.

Returns

Type declaration; no runtime value.

Example

See the owning declaration and linked feature guide for usage; no standalone example is documented in source.

[INTERFACE] `ContentItem`

Compatibility re-export; its implementation and documentation are owned by the owning package @dataarthub/app-core.

Imports: @alneas/eaos-core, @alneas/eaos-core/adapters, @alneas/eaos-core/adapters/types.

Signature

export interface ContentItem {
    slug: string;
    contentType: string;
    title: string;
    description?: string;
    image?: string;
    author?: string;
    tags?: string[];
    status: 'draft' | 'published' | 'archived';
    publishedAt?: string;
    updatedAt?: string;
    scheduledAt?: string;
    seoTitle?: string;
    seoDescription?: string;
    seoKeywords?: string[];
    canonicalUrl?: string;
    ogImage?: string;
    jsonLd?: Record<string, unknown>;
    body: string;
    sourceId?: string;
    sourceTable?: string;
    tenantId?: string;
    lastSyncedAt?: string;
    metadata?: Record<string, unknown>;
}

Parameters

Name	Type	Required	Description
`slug`	`string`	Yes	See the upstream owning declaration.
`contentType`	`string`	Yes	See the upstream owning declaration.
`title`	`string`	Yes	See the upstream owning declaration.
`description`	`string`	No	See the upstream owning declaration.
`image`	`string`	No	See the upstream owning declaration.
`author`	`string`	No	See the upstream owning declaration.
`tags`	`string[]`	No	See the upstream owning declaration.
`status`	`'draft' \| 'published' \| 'archived'`	Yes	See the upstream owning declaration.
`publishedAt`	`string`	No	See the upstream owning declaration.
`updatedAt`	`string`	No	See the upstream owning declaration.
`scheduledAt`	`string`	No	See the upstream owning declaration.
`seoTitle`	`string`	No	See the upstream owning declaration.
`seoDescription`	`string`	No	See the upstream owning declaration.
`seoKeywords`	`string[]`	No	See the upstream owning declaration.
`canonicalUrl`	`string`	No	See the upstream owning declaration.
`ogImage`	`string`	No	See the upstream owning declaration.
`jsonLd`	`Record<string, unknown>`	No	See the upstream owning declaration.
`body`	`string`	Yes	See the upstream owning declaration.
`sourceId`	`string`	No	See the upstream owning declaration.
`sourceTable`	`string`	No	See the upstream owning declaration.
`tenantId`	`string`	No	See the upstream owning declaration.
`lastSyncedAt`	`string`	No	See the upstream owning declaration.
`metadata`	`Record<string, unknown>`	No	See the upstream owning declaration.

Returns

Type declaration; no runtime value.

Example

See the owning declaration and linked feature guide for usage; no standalone example is documented in source.

[INTERFACE] `ContractCompatibilityIssue`

One removed tool, schema incompatibility or execution-policy change.

Imports: @alneas/eaos-core, @alneas/eaos-core/plugin-sdk, @alneas/eaos-core/plugin-sdk/contract-compatibility.

Signature

interface ContractCompatibilityIssue {
    toolName: string;
    kind: 'removed' | 'input-breaking' | 'output-breaking' | 'policy-change';
    message: string;
}

Parameters

Name	Type	Required	Description
`toolName`	`string`	Yes	Registered tool identity used to resolve host execution policy.
`kind`	`'removed' \| 'input-breaking' \| 'output-breaking' \| 'policy-change'`	Yes	Checked incompatibility category: removal, input/output schema break or policy change.
`message`	`string`	Yes	Human-readable provider/failure explanation; do not include secrets in surfaced diagnostics.

Returns

Type declaration; no runtime value.

Public members

`toolName`

Registered tool identity used to resolve host execution policy.

`kind`

Checked incompatibility category: removal, input/output schema break or policy change.

`message`

Human-readable provider/failure explanation; do not include secrets in surfaced diagnostics.

Example

See the owning declaration and linked feature guide for usage; no standalone example is documented in source.

[INTERFACE] `ContractCompatibilityReport`

Compatibility decision and its detailed tool-level issues.

Imports: @alneas/eaos-core, @alneas/eaos-core/plugin-sdk, @alneas/eaos-core/plugin-sdk/contract-compatibility.

Signature

interface ContractCompatibilityReport {
    compatible: boolean;
    issues: ContractCompatibilityIssue[];
}

Parameters

Name	Type	Required	Description
`compatible`	`boolean`	Yes	Whether the supported compatibility checks found no issues; this is not a full JSON Schema proof.
`issues`	`ContractCompatibilityIssue[]`	Yes	Detailed validation or compatibility problems, empty when the corresponding check reports success.

Returns

Type declaration; no runtime value.

Public members

`compatible`

Whether the supported compatibility checks found no issues; this is not a full JSON Schema proof.

`issues`

Detailed validation or compatibility problems, empty when the corresponding check reports success.

Example

See the owning declaration and linked feature guide for usage; no standalone example is documented in source.

[FUNCTION] `createAIExecutionBroker`

Deterministic route selection for server-controlled AI execution.

The broker decides where work may run; it never owns credentials or starts a provider process. Availability and quota facts are supplied by the host.

Imports: @alneas/eaos-core, @alneas/eaos-core/ai, @alneas/eaos-core/ai/execution-broker.

Signature

declare function createAIExecutionBroker(options: {
    routes: readonly AIExecutionCandidate[];
    policyVersion?: string;
}): {
    listRoutes(): readonly AIExecutionCandidate[];
    decide(request: AIExecutionRequest): AIExecutionDecision;
};

Parameters

Name	Type	Required	Description
`options`	`{ routes: readonly AIExecutionCandidate[]; policyVersion?: string; }`	Yes	One to 100 unique routes and optional policyVersion, default ai-execution-policy-v1. Routes are copied; capacities are snapshots.

Returns

{ listRoutes(): readonly AIExecutionCandidate[]; decide(request: AIExecutionRequest): AIExecutionDecision; }

A broker with copied route listings and decide(request); decide returns the highest-ranked compatible route and remaining ranked fallbacks.

Remarks

No process/provider calls, retries or reservations occur. Quality/latency/preferredTargets affect score; they are not hard constraints. Offline, capability, sensitivity, mode, no-training, allowedTargets and userBound checks filter routes. Host authorization and fresh capacity remain caller responsibilities.

Errors and rejections

Error for invalid/duplicate route data or malformed request context; decide throws AIExecutionRouteUnavailableError when no compatible candidate remains.

Public members

`options.routes`

One to 100 unique host-advertised execution candidates; capability/sensitivity/mode lists and optional capacity metadata are copied for local selection.

`options.policyVersion`

Optional host policy label included in decisions; omission uses ai-execution-policy-v1.

`result.listRoutes`

List copied metadata for the configured execution routes without querying or starting providers.

Returns: A new array of copied route candidates, including independent capability/sensitivity/mode arrays and capacity objects.

Remarks

Route availability remains the host snapshot captured when the broker was created; this method performs no live capacity refresh or authorization.

Example:

import { createAIExecutionBroker } from "@alneas/eaos-core/ai/execution-broker";
export function inspectHostRoutes(broker: ReturnType<typeof createAIExecutionBroker>) {
  return broker.listRoutes().map(route => ({ routeId: route.routeId, target: route.target }));
}

`result.decide`

Choose the highest-ranked compatible execution candidate and its ranked fallbacks.

Parameters:

request: Verified operation context and capability/sensitivity/mode/no-training/target constraints; quality, latency and preferredTargets affect scoring rather than hard eligibility.

Returns: Selected route, remaining compatible fallbacks, policy version and explanation, using copied route metadata.

Remarks

Does not execute providers, reserve capacity, authorize the principal or automatically retry fallbacks; hosts supply current policy/capacity and enforce any side-effect boundaries.

Errors and rejections

Error for malformed request scope/required fields; AIExecutionRouteUnavailableError when no route remains compatible.

Example:

import { createAIExecutionBroker, type AIExecutionRequest } from "@alneas/eaos-core/ai/execution-broker";
export function selectHostRoute(
  broker: ReturnType<typeof createAIExecutionBroker>, verifiedRequest: AIExecutionRequest,
) {
  const decision = broker.decide(verifiedRequest);
  return { selected: decision.route.routeId, fallbacks: decision.fallbacks.map(route => route.routeId) };
}

Example

import { createAIExecutionBroker } from "@alneas/eaos-core/ai/execution-broker";
const broker = createAIExecutionBroker({ routes: [{ routeId: "local", target: "local-mlx", adapterId: "mlx", capabilities: ["chat"], allowedSensitivity: ["level1_public"], requiresNoTraining: true, quality: "standard", supportedModes: ["interactive"] }] });
console.log(broker.decide({ context: { tenantId: "tenant-demo", userId: "user-demo", operation: "preview" }, capability: "chat", sensitivityLevel: "level1_public", mode: "interactive", quality: "standard", latency: "interactive", requiresNoTraining: true }).route.routeId);

[FUNCTION] `createAIModelRegistry`

Creates an immutable registry for approved model routes.

Tenant and user policy still belongs to the host (AIModelResolveInput.context is deliberately passed to the resolver contract). This registry only validates the host’s approved route set and fails closed on unknown or incompatible routes.

Imports: @alneas/eaos-core, @alneas/eaos-core/ai, @alneas/eaos-core/ai/model-registry.

Signature

declare function createAIModelRegistry(options: AIModelRegistryOptions): AIModelRegistry;

Parameters

Name	Type	Required	Description
`options`	`AIModelRegistryOptions`	Yes	One to 100 unique routes and an optional registered default model ID; route limits must be positive safe integers up to 1,000,000 characters.

Returns

AIModelRegistry

A registry whose list/resolve results are fresh route copies; resolution validates capability and any supplied sensitivity level.

Remarks

No provider calls or authorization checks occur. The host owns tenant/user authorization and must supply sensitivity to enforce that restriction.

Errors and rejections

Error for invalid routes/defaults; resolve throws for invalid context, missing/unknown model or incompatible capability/sensitivity.

Example

import { createAIModelRegistry } from "@alneas/eaos-core/ai/model-registry";
const registry = createAIModelRegistry({ routes: [{ modelId: "local-chat", adapterId: "local", capabilities: ["chat"], allowedSensitivity: ["level1_public"] }], defaultModelId: "local-chat" });
console.log(registry.resolve({ context: { tenantId: "tenant-demo", userId: "user-demo", operation: "preview" }, capability: "chat" }).modelId);

[FUNCTION] `createApprovalBinding`

Bind an operation, request and versioned contract to a stable approval hash.

Imports: @alneas/eaos-core, @alneas/eaos-core/agent/approved-execution.

Signature

declare function createApprovalBinding(input: ApprovalBindingInput, options?: {
    now?: Date;
}): ApprovalBinding;

Parameters

Name	Type	Required	Description
`input`	`ApprovalBindingInput`	Yes	Approval scope, JSON-safe input and execution contract; optional expiry must be after options.now and target revision positive.
`options`	`{ now?: Date; }`	No	Optional evaluation clock; now defaults to current Date.

Returns

ApprovalBinding

A shallow-frozen identity containing hashes rather than the request input.

Remarks

Hash identity does not prove approval or authorization. No approval is stored, signed or executed.

Errors and rejections

Error for invalid scope, target, contract, expired/invalid expiry or non-JSON hash input; clone/date errors propagate.

Public members

`options.now`

Optional reference time used to reject expired bindings; omission uses a new current Date.

Example

import { createApprovalBinding } from "@alneas/eaos-core/agent/approved-execution";
const input = { tenantId: "tenant-demo", requestedBy: "user-demo", operation: "note.read", input: { id: "note-1" }, contract: { operation: "note.read", version: "1.0.0", permission: "notes:read", sideEffect: "read", riskLevel: "low", approvalLevel: "L1_AUTO", inputSchema: { type: "object" } } } as const;
console.log(createApprovalBinding(input).bindingHash);

[FUNCTION] `createApprovedExecutionEvent`

Build an outbox event whose idempotency identity is the approval binding.

Imports: @alneas/eaos-core, @alneas/eaos-core/agent/approved-execution.

Signature

declare function createApprovedExecutionEvent<T>(input: {
    binding: ApprovalBinding;
    producer: string;
    topic: string;
    payload: T;
    occurredAt?: Date | string;
    availableAt?: Date | string;
}): OutboxEvent<ApprovedExecutionEvent<T>>;

Parameters

Name	Type	Required	Description
`input`	`{ binding: ApprovalBinding; producer: string; topic: string; payload: T; occurredAt?: Date \| string; availableAt?: Date \| string; }`	Yes	Live binding, producer/topic and payload; optional event/availability timestamps are forwarded to createOutboxEvent.

Returns

OutboxEvent<ApprovedExecutionEvent<T>>

A new pending outbox event containing the validated binding and cloned payload.

Type parameters

T: Payload type retained as the execution event input.

Remarks

Does not persist, publish, execute or independently establish that approval was granted.

Errors and rejections

Error for invalid binding or outbox metadata, non-JSON/uncloneable payload or invalid timestamps.

Public members

`input.binding`

Live validated approval identity; its tenant and bindingHash determine the outbox tenant and idempotency key. Identity alone does not prove approval was granted.

`input.producer`

Host component identity emitting the approved-execution outbox event, validated by createOutboxEvent.

`input.topic`

Exact outbox dispatch topic identifying the host execution handler.

`input.payload`

JSON-safe execution input cloned into the event alongside the validated binding; no domain input-schema validation is performed here.

`input.occurredAt`

Optional occurrence Date or parseable timestamp; omission uses the current time in createOutboxEvent.

`input.availableAt`

Optional earliest-delivery Date or parseable timestamp; omission uses current time, without scheduling delivery itself.

Example

import { createApprovedExecutionEvent } from "@alneas/eaos-core/agent/approved-execution";
import { createApprovalBinding } from "@alneas/eaos-core/agent/approved-execution";
const input = { tenantId: "tenant-demo", requestedBy: "user-demo", operation: "note.read", input: { id: "note-1" }, contract: { operation: "note.read", version: "1.0.0", permission: "notes:read", sideEffect: "read", riskLevel: "low", approvalLevel: "L1_AUTO", inputSchema: { type: "object" } } } as const;
const binding = createApprovalBinding(input);
console.log(createApprovedExecutionEvent({ binding, producer: "notes", topic: "notes.read.approved", payload: input.input }).idempotencyKey);

[FUNCTION] `createDomainEventBus`

Create an event bus scoped to one host or request context.

Imports: @alneas/eaos-core, @alneas/eaos-core/plugin-sdk, @alneas/eaos-core/plugin-sdk/event-bus.

Signature

declare function createDomainEventBus(): DomainEventBus;

Parameters

Name	Type	Required	Description
—	—	—	No call parameters.

Returns

DomainEventBus

A new bus with no listeners.

Remarks

Subscriptions are not shared with other bus instances; caller owns listener cleanup.

Example

import { createDomainEventBus } from "@alneas/eaos-core/plugin-sdk/event-bus";
const bus = createDomainEventBus();
bus.publish("demo", { message: "hello" });

[FUNCTION] `createJsonDocumentAssertion`

Same logical contract for complete payload writes and owned plugin_data subtree updates.

Imports: @alneas/eaos-core, @alneas/eaos-core/data-contracts, @alneas/eaos-core/contracts/data-contracts, @alneas/eaos-core/contracts/json-documents.

Signature

declare function createJsonDocumentAssertion(document: JsonDocumentContract): (value: unknown) => void;

Parameters

Name	Type	Required	Description
`document`	`JsonDocumentContract`	Yes	Logical document contract; schema must be a closed object and optional maxBytes a positive safe integer up to 4 MiB.

Returns

(value: unknown) => void

An assertion callback accepting unknown payload and returning no value when strict canonical JSON size and schema checks pass.

Remarks

Requires the app-core AJV peer and Node Buffer. Uses draft 2020-12 with coercion/defaults/property removal disabled; the contract is cloned before compilation. The returned callback throws on invalid payloads.

Errors and rejections

Error for invalid schema/bounds, AJV schema compilation failures, non-JSON values, oversized payloads or schema mismatch.

Example

import { createJsonDocumentAssertion } from "@alneas/eaos-core/contracts/json-documents";
const document = { id: "notes.body", version: "1.0.0", table: "notes", column: "payload", schema: { type: "object", properties: { title: { type: "string" } }, required: ["title"], additionalProperties: false } };
const assertDocument = createJsonDocumentAssertion(document);
assertDocument({ title: "hello" });

[FUNCTION] `createLivenessReport`

Create a timestamped process-liveness response without probing dependencies.

Imports: @alneas/eaos-core, @alneas/eaos-core/health.

Signature

declare function createLivenessReport(now?: Date): LivenessReport;

Parameters

Name	Type	Required	Description
`now`	`Date`	No	Report time; defaults to current Date.

Returns

LivenessReport

A fresh alive report with an ISO timestamp.

Errors and rejections

RangeError when now is an invalid Date.

Example

import { createLivenessReport } from "@alneas/eaos-core/health";
console.log(createLivenessReport(new Date("2026-10-19T00:00:00Z")));

[FUNCTION] `createOutboxEvent`

Build a validated, immutable event envelope. Persistence is supplied by the host.

Imports: @alneas/eaos-core, @alneas/eaos-core/events/outbox.

Signature

declare function createOutboxEvent<T>(input: OutboxEventInput<T>): OutboxEvent<T>;

Parameters

Name	Type	Required	Description
`input`	`OutboxEventInput<T>`	Yes	Scope, topic, idempotency key and JSON payload. ID defaults to a hash of tenant/producer/key; occurredAt and availableAt default to the current time.

Returns

OutboxEvent<T>

A shallow-frozen pending event with cloned payload, payload hash and zero attempts.

Type parameters

T: JSON-safe event payload type retained in the returned envelope.

Remarks

Requires node:crypto. Idempotency identity excludes topic and payload; the host store must enforce key uniqueness and the intended tenant boundary.

Errors and rejections

Error for invalid identifiers/timestamps or non-JSON/uncloneable payload.

Example

import { createOutboxEvent } from "@alneas/eaos-core/events/outbox";
const event = createOutboxEvent({ tenantId: "tenant-demo", producer: "notes", topic: "note.created", idempotencyKey: "request-1", payload: { id: "note-1" } });
console.log(event.status); // pending

[FUNCTION] `createPlatformContext`

Group host adapters and optional identity into a fresh platform context.

Imports: @alneas/eaos-core, @alneas/eaos-core/adapters, @alneas/eaos-core/adapters/platform-context.

Signature

declare function createPlatformContext(config: PlatformContextConfig): PlatformContext;

Parameters

Name	Type	Required	Description
`config`	`PlatformContextConfig`	Yes	Connected host database/storage and optional content, events, secrets, identity and AI adapters. Omitted events creates a fresh bus; omitted secrets uses the static SecretResolver class.

Returns

PlatformContext

A new context referencing the supplied adapters; no services container is initialized and no adapter is cloned.

Remarks

Does not connect, authenticate, scope, authorize or dispose adapters. The host owns their lifecycle and must establish tenant/user trust before exposing capabilities.

Example

import { createPlatformContext } from "@alneas/eaos-core/adapters/platform-context";
import type { DataAccessAdapter, StorageAdapter } from "@alneas/eaos-core/adapters/types";
function createHostContext(db: DataAccessAdapter, storage: StorageAdapter) {
 return createPlatformContext({ db, storage, tenantId: "tenant-demo", userId: "user-demo" });
}

[FUNCTION] `createPluginContractSnapshot`

Normalize advertised tool schemas/policies into a deterministic plugin snapshot.

Imports: @alneas/eaos-core, @alneas/eaos-core/plugin-sdk, @alneas/eaos-core/plugin-sdk/contract-compatibility.

Signature

declare function createPluginContractSnapshot(manifest: PluginManifest): PluginContractSnapshot;

Parameters

Name	Type	Required	Description
`manifest`	`PluginManifest`	Yes	Plugin discovery manifest; tools default to empty and are sorted by name. Missing tool contracts use version 1.0.0, permission equal to tool name and sideEffect write.

Returns

PluginContractSnapshot

A new snapshot with cloned schemas, normalized policy fields and SHA-256 tool/plugin hashes.

Remarks

Requires node:crypto. Missing risk defaults to low; approval level derives from risk and human-review default is risk != low. The snapshot does not authorize execution.

Errors and rejections

Cloning or strict canonical JSON hashing errors propagate.

Example

import { createPluginContractSnapshot } from "@alneas/eaos-core/plugin-sdk/contract-compatibility";
import type { PluginManifest } from "@alneas/eaos-core/plugin-sdk/types";
function captureHostManifest(manifest: PluginManifest) { return createPluginContractSnapshot(manifest); }

[FUNCTION] `createPluginTestHarness`

Pure SDK harness. No database, server or lifecycle dependency is introduced into Core.

Imports: @alneas/eaos-core/testing.

Signature

declare function createPluginTestHarness(plugin: DefinedPlugin, options?: PluginTestHarnessOptions): Promise<PluginTestHarness>;

Parameters

Name	Type	Required	Description
`plugin`	`DefinedPlugin`	Yes	Definition built by definePlugin; the harness looks up exact GET/POST route paths.
`options`	`PluginTestHarnessOptions`	No	Optional host context factory and real isolation probe; omission supplies capabilities that throw on property access.

Returns

Promise<PluginTestHarness>

A harness whose as(persona) clones the persona and exposes GET/POST calls; expectTenantIsolation requires an explicit isolationProbe.

Remarks

No database/server/lifecycle is connected automatically. Defaults: free plan, test-user identity, member role and no addons, except pro personas receive the plugin addon when addons are omitted. Entitlement checks are previews; this harness does not independently prove tenant isolation.

Errors and rejections

Returned operations throw/reject on invalid persona tenant, missing route, entitlement denial, unconfigured capabilities or host/handler errors. Isolation checks reject without a probe or when that probe rejects.

Example

import { createPluginTestHarness } from "@alneas/eaos-core/testing";
import { definePlugin } from "@alneas/eaos-core/plugin-sdk/define-plugin";
const plugin = definePlugin({ id: "notes", routes(router) { router.get("/status", () => ({ ready: true })); } });
const harness = await createPluginTestHarness(plugin);
console.log(await harness.as({ tenantId: "tenant-demo" }).get("/status"));

[FUNCTION] `createStructuredDraftProposal`

Shared reviewable AI draft contract for official plugins.

Imports: @alneas/eaos-core, @alneas/eaos-core/ai, @alneas/eaos-core/ai/proposal-ui.

Signature

declare function createStructuredDraftProposal(scope: string, targetId: string, draft: StructuredDraft, createdAt: string): RecordProposal<StructuredProposalRecord>;

Parameters

Name	Type	Required	Description
`scope`	`string`	Yes	Prefix used for proposal identity and error messages.
`targetId`	`string`	Yes	Record identity targeted by the proposal.
`draft`	`StructuredDraft`	Yes	Title and JSON-serializable structured draft data.
`createdAt`	`string`	Yes	Creation timestamp accepted by the app-core proposal validator; also included in proposal identity.

Returns

RecordProposal<StructuredProposalRecord>

A validated RecordProposal with title/data changes from empty values at baseVersion zero.

Remarks

Requires app-core proposal peer. Produces review data only; no record is written and human acceptance remains host-owned.

Errors and rejections

Error if proposal validation fails; JSON serialization and peer validator errors propagate.

Example

import { createStructuredDraftProposal } from "@alneas/eaos-core/ai/proposal-ui";
console.log(createStructuredDraftProposal("notes", "note-1", { title: "Draft", data: { text: "hello" } }, "2026-10-19T00:00:00Z").id);

[FUNCTION] `createStructuredDraftUIDocument`

Shared bounded generative UI response contract; component registration remains host-owned.

Imports: @alneas/eaos-core, @alneas/eaos-core/ai, @alneas/eaos-core/ai/proposal-ui.

Signature

declare function createStructuredDraftUIDocument(scope: string, draft: StructuredDraft): GenerativeUIDocument;

Parameters

Name	Type	Required	Description
`scope`	`string`	Yes	Prefix used for the registered summary block type and document identity.
`draft`	`StructuredDraft`	Yes	Title and JSON-serializable data; serialized data is limited to 20000 characters by the generated contract.

Returns

GenerativeUIDocument

A validated version-one document containing one summary block.

Remarks

Requires app-core generative-ui peer. Rendering and registration of the summary component remain host-owned.

Errors and rejections

Error on generative UI validation failure; serialization/peer errors propagate.

Example

import { createStructuredDraftUIDocument } from "@alneas/eaos-core/ai/proposal-ui";
console.log(createStructuredDraftUIDocument("notes", { title: "Draft", data: { text: "hello" } }).version); // 1

[FUNCTION] `createWorkflowEffectReceipt`

Build a provider receipt without allowing the adapter to change the admitted request identity.

Imports: @alneas/eaos-core, @alneas/eaos-core/agent/workflow-effects.

Signature

declare function createWorkflowEffectReceipt<TInput>(input: {
    request: WorkflowEffectRequest<TInput>;
    adapterId: string;
    receiptId: string;
    outcome: WorkflowEffectOutcome;
    occurredAt?: string | Date;
    externalId?: string;
    errorCode?: string;
    metadata?: Readonly<Record<string, unknown>>;
}): WorkflowEffectReceipt;

Parameters

Name	Type	Required	Description
`input`	`{ request: WorkflowEffectRequest<TInput>; adapterId: string; receiptId: string; outcome: WorkflowEffectOutcome; occurredAt?: string \| Date; externalId?: string; errorCode?: string; metadata?: Readonly<Record<string, unknown>>; }`	Yes	Admitted request, adapter and receipt IDs, outcome and optional metadata; occurredAt defaults to current time.

Returns

WorkflowEffectReceipt

A validated receipt containing the request identity and input hash.

Type parameters

TInput: Input type of the request bound to the receipt.

Remarks

A receipt records a reported outcome. Unknown outcomes require host reconciliation before a retry that could duplicate an effect; no execution or persistence occurs here.

Errors and rejections

Error for invalid request, receipt identity/outcome/time/metadata or uncloneable data.

Public members

`input.request`

Exact admitted tenant/workflow/operation/input and replay identity whose normalized input hash is copied into the receipt.

`input.adapterId`

Nonblank host/provider adapter identity, at most 256 characters, recorded as the source of this outcome.

`input.receiptId`

Nonblank provider/host receipt identity, at most 512 characters.

`input.outcome`

Reported succeeded, failed or unknown result; construction does not execute or independently verify the effect.

`input.occurredAt`

Optional Date or parseable timestamp; omission uses the current ISO timestamp. Date inputs are normalized to ISO text.

`input.externalId`

Optional nonblank provider resource identity, at most 512 characters.

`input.errorCode`

Optional nonblank provider failure classification, at most 256 characters; failed/unknown outcomes remain receipt data.

`input.metadata`

Optional object-valued structured-cloneable receipt context; a detached copy is returned and the host must exclude secrets.

Example

import { createWorkflowEffectReceipt } from "@alneas/eaos-core/agent/workflow-effects";
const request = { tenantId: "tenant-demo", workflowId: "notes", operation: "note.create", idempotencyKey: "request-1", input: { text: "hello" } };
console.log(createWorkflowEffectReceipt({ request, adapterId: "notes-store", receiptId: "receipt-1", outcome: "unknown" }).outcome);

[FUNCTION] `createWorkflowEffectRequest`

Normalize a workflow effect request and compute its input hash.

Imports: @alneas/eaos-core, @alneas/eaos-core/agent/workflow-effects.

Signature

declare function createWorkflowEffectRequest<TInput>(input: WorkflowEffectRequest<TInput>): WorkflowEffectRequest<TInput> & {
    inputHash: string;
};

Parameters

Name	Type	Required	Description
`input`	`WorkflowEffectRequest<TInput>`	Yes	Admitted scope and JSON-safe input; optional target revision must be positive and idempotency key at most 256 characters.

Returns

WorkflowEffectRequest<TInput> & { inputHash: string; }

A new request with cloned input/target and an additional SHA-256 inputHash.

Type parameters

TInput: Domain input type preserved in the normalized request.

Remarks

Does not execute an effect, establish authorization or persist the key.

Errors and rejections

Error for invalid scope/target, unsupported JSON or uncloneable input.

Public members

`result.inputHash`

Lowercase SHA-256 digest of the original strict canonical JSON input, used to bind provider receipts to this admitted request.

Example

import { createWorkflowEffectRequest } from "@alneas/eaos-core/agent/workflow-effects";
const request = { tenantId: "tenant-demo", workflowId: "notes", operation: "note.create", idempotencyKey: "request-1", input: { text: "hello" } };
console.log(createWorkflowEffectRequest(request).inputHash);

[FUNCTION] `createWorkflowEvent`

Create a stable, tenant-scoped event envelope for outbox/projector use.

Imports: @alneas/eaos-core, @alneas/eaos-core/workflow-runtime.

Signature

declare function createWorkflowEvent<TPayload>(input: Omit<WorkflowEventEnvelope<TPayload>, 'eventId' | 'occurredAt' | 'idempotencyKey'> & Partial<Pick<WorkflowEventEnvelope<TPayload>, 'eventId' | 'occurredAt' | 'idempotencyKey'>>): WorkflowEventEnvelope<TPayload>;

Parameters

Name	Type	Required	Description
`input`	`Omit<WorkflowEventEnvelope<TPayload>, 'eventId' \| 'occurredAt' \| 'idempotencyKey'> & Partial<Pick<WorkflowEventEnvelope<TPayload>, 'eventId' \| 'occurredAt' \| 'idempotencyKey'>>`	Yes	Envelope data; aggregateRevision must be a nonnegative safe integer. Omitted idempotencyKey hashes tenant, aggregate identity/revision, type and payload; omitted eventId hashes tenant and idempotencyKey; occurredAt defaults to current time.

Returns

WorkflowEventEnvelope<TPayload>

A shallow-frozen envelope containing a cloned payload and normalized ISO timestamp.

Type parameters

TPayload: JSON-safe event payload retained by type in the returned envelope.

Remarks

Does not append or publish events. A caller-supplied idempotency key controls identity independently of payload.

Errors and rejections

Error for invalid required text/revision or non-JSON hashed payload; invalid timestamps and uncloneable payloads propagate native errors.

Example

import { createWorkflowEvent } from "@alneas/eaos-core/workflow-runtime";
const event = createWorkflowEvent({ tenantId: "tenant-demo", aggregateType: "note", aggregateId: "note-1", aggregateRevision: 1, type: "note.created", producer: "notes", correlationId: "request-1", payload: { text: "hello" } });
console.log(event.eventId);

[CONSTANT] `DATA_STANDARDS_VERSION`

Shared value semantics. A business ID is opaque; an external key is never an authority.

Imports: @alneas/eaos-core/plugin-sdk, @alneas/eaos-core/plugin-sdk/data-standards.

Signature

declare const DATA_STANDARDS_VERSION = "1.0.0";

Parameters

Name	Type	Required	Description
—	—	—	No call parameters.

Returns

Declared constant value.

Example

See the owning declaration and linked feature guide for usage; no standalone example is documented in source.

[INTERFACE] `DataAccessAdapter`

Compatibility re-export; its implementation and documentation are owned by the owning package @dataarthub/app-core.

Imports: @alneas/eaos-core, @alneas/eaos-core/adapters, @alneas/eaos-core/adapters/types.

Signature

export interface DataAccessAdapter {
    readonly cacheScope?: string;
    find<T = unknown>(collection: string, filter?: Filter, options?: QueryOptions): Promise<T[]>;
    findOne<T = unknown>(collection: string, id: string, options?: QueryOptions): Promise<T | null>;
    create<T = unknown>(collection: string, data: Record<string, unknown>, options?: QueryOptions): Promise<T>;
    update<T = unknown>(collection: string, id: string, data: Record<string, unknown>, options?: QueryOptions): Promise<T>;
    replace?<T = unknown>(collection: string, id: string, data: Record<string, unknown>, options?: QueryOptions): Promise<T>;
    delete<T = unknown>(collection: string, id: string, options?: QueryOptions): Promise<T>;
    aggregate?<T = unknown>(collection: string, pipeline: unknown[], options?: QueryOptions): Promise<T[]>;
    count(collection: string, filter?: Filter, options?: QueryOptions): Promise<number>;
    createMany?<T = unknown>(collection: string, data: Record<string, unknown>[], options?: QueryOptions): Promise<T[]>;
    updateMany?<T = unknown>(collection: string, filter: Filter, data: Record<string, unknown>, options?: QueryOptions): Promise<T[]>;
    deleteMany?<T = unknown>(collection: string, filter: Filter, options?: QueryOptions): Promise<T[]>;
    insertOne?(collection: string, data: Record<string, unknown>, options?: QueryOptions): Promise<OperationResult>;
    updateOne?(collection: string, filter: Filter, data: Record<string, unknown>, options?: QueryOptions): Promise<OperationResult>;
    replaceOne?(collection: string, filter: Filter, data: Record<string, unknown>, options?: QueryOptions): Promise<OperationResult>;
    deleteOne?(collection: string, filter: Filter, options?: QueryOptions): Promise<OperationResult>;
    findOneAndUpdate?<T = unknown>(collection: string, filter: Filter, data: Record<string, unknown>, options?: QueryOptions): Promise<T | null>;
    findOneAndReplace?<T = unknown>(collection: string, filter: Filter, data: Record<string, unknown>, options?: QueryOptions): Promise<T | null>;
    findOneAndDelete?<T = unknown>(collection: string, filter: Filter, options?: QueryOptions): Promise<T | null>;
}

Parameters

Name	Type	Required	Description
`cacheScope`	`string`	No	See the upstream owning declaration.
`find`	`Promise<T[]>`	Yes	See the upstream owning declaration.
`findOne`	`Promise<T \| null>`	Yes	See the upstream owning declaration.
`create`	`Promise<T>`	Yes	See the upstream owning declaration.
`update`	`Promise<T>`	Yes	See the upstream owning declaration.
`replace`	`Promise<T>`	No	See the upstream owning declaration.
`delete`	`Promise<T>`	Yes	See the upstream owning declaration.
`aggregate`	`Promise<T[]>`	No	See the upstream owning declaration.
`count`	`Promise<number>`	Yes	See the upstream owning declaration.
`createMany`	`Promise<T[]>`	No	See the upstream owning declaration.
`updateMany`	`Promise<T[]>`	No	See the upstream owning declaration.
`deleteMany`	`Promise<T[]>`	No	See the upstream owning declaration.
`insertOne`	`Promise<OperationResult>`	No	See the upstream owning declaration.
`updateOne`	`Promise<OperationResult>`	No	See the upstream owning declaration.
`replaceOne`	`Promise<OperationResult>`	No	See the upstream owning declaration.
`deleteOne`	`Promise<OperationResult>`	No	See the upstream owning declaration.
`findOneAndUpdate`	`Promise<T \| null>`	No	See the upstream owning declaration.
`findOneAndReplace`	`Promise<T \| null>`	No	See the upstream owning declaration.
`findOneAndDelete`	`Promise<T \| null>`	No	See the upstream owning declaration.

Returns

Type declaration; no runtime value.

Example

See the owning declaration and linked feature guide for usage; no standalone example is documented in source.

[INTERFACE] `DatabaseAdapter`

Core database adapter contract. Implementations must handle connection lifecycle, multi-tenant isolation, and driver-specific details internally.

Imports: @alneas/eaos-core, @alneas/eaos-core/db, @alneas/eaos-core/db/adapter.

Signature

interface DatabaseAdapter {
    readonly type: DbDriverType;
    withConnection<T>(domain: string, callback: (connection: any) => Promise<T>): Promise<T>;
    withTenantConnection<T>(domain: string, callback: (connection: any) => Promise<T>, context: TenantSessionContext): Promise<T>;
    ping(): Promise<boolean>;
    getStats(): ConnectionStats;
    close(): Promise<void>;
}

Parameters

Name	Type	Required	Description
`type`	`DbDriverType`	Yes	Driver family implemented by this host connection adapter.
`withConnection`	`Promise<T>`	Yes	Run an asynchronous callback with a host-managed unscoped database connection.
`withTenantConnection`	`Promise<T>`	Yes	Run a callback under host-installed tenant session context.
`ping`	`Promise<boolean>`	Yes	Probe host database connection health.
`getStats`	`ConnectionStats`	Yes	Read the host connection-pool statistics.
`close`	`Promise<void>`	Yes	Release host-managed database connections and pools.

Returns

Type declaration; no runtime value.

Public members

`type`

Driver family implemented by this host connection adapter.

`withConnection`

Run an asynchronous callback with a host-managed unscoped database connection.

Parameters:

domain: Logical connection/pool routing key interpreted by the host adapter.
callback: Called after acquisition with the driver-specific connection; resolve the desired result before the host releases the connection.

Returns: The resolved callback result.

Type parameters

T: Resolved callback result type retained by the Promise.

Remarks

Host implementation owns acquisition/release and transaction behavior; this operation installs no tenant context. Do not retain the connection beyond callback completion.

Errors and rejections

Acquisition, callback and cleanup failures may reject according to the host implementation.

Example:

import type { DatabaseAdapter } from "@alneas/eaos-core/db/adapter";
async function inspectHostDatabase(adapter: DatabaseAdapter) { return adapter.withConnection("health", async connection => typeof connection.execute === "function"); }

`withTenantConnection`

Run a callback under host-installed tenant session context.

Parameters:

domain: Logical host pool/domain routing key.
callback: Asynchronous operation receiving a driver connection only while its tenant context is installed; do not retain the connection.
context: Verified tenant and optional user claims the adapter installs and cleans up on the session.

Returns: The resolved callback result after host-managed connection work.

Type parameters

T: Resolved callback output preserved through the connection Promise.

Remarks

Host implementation must enforce session isolation, release/reset connections and define transaction behavior; the caller establishes identity trust.

Errors and rejections

Host acquisition/context setup, callback and cleanup failures may reject.

Example:

import type { DatabaseAdapter } from "@alneas/eaos-core/db/adapter";
async function inspectTenantDatabase(adapter: DatabaseAdapter) { return adapter.withTenantConnection("notes", async connection => typeof connection.execute === "function", { tenantId: "tenant-demo", userId: "user-demo" }); }

`ping`

Probe host database connection health.

Returns: True when the host probe reports available, false when it reports unavailable.

Remarks

Timeout, retries and network behavior are adapter-defined.

Errors and rejections

Host probe failures may reject rather than resolve false.

Example:

import type { DatabaseAdapter } from "@alneas/eaos-core/db/adapter";
async function pingHost(adapter: DatabaseAdapter) { return adapter.ping(); }

`getStats`

Read the host connection-pool statistics.

Returns: Active connection count, pool capacity and driver family.

Remarks

Snapshot timing and ownership follow the host implementation.

Errors and rejections

Host statistics errors may be thrown.

Example:

import type { DatabaseAdapter } from "@alneas/eaos-core/db/adapter";
function inspectPool(adapter: DatabaseAdapter) { return adapter.getStats(); }

`close`

Release host-managed database connections and pools.

Returns: No value; Promise completion means the host shutdown operation completed.

Remarks

Call when the owning host no longer needs the adapter; idempotency and handling of in-flight operations are implementation-specific.

Errors and rejections

Host shutdown failures reject the Promise.

Example:

import type { DatabaseAdapter } from "@alneas/eaos-core/db/adapter";
async function closeHostDatabase(adapter: DatabaseAdapter) { await adapter.close(); }

Example

See the owning declaration and linked feature guide for usage; no standalone example is documented in source.

[INTERFACE] `DataContract`

A versioned storage contract has no routes, jobs, activation or infrastructure.

Imports: @alneas/eaos-core, @alneas/eaos-core/data-contracts, @alneas/eaos-core/contracts/data-contracts.

Signature

interface DataContract {
    id: string;
    version: string;
    description: string;
    schema: Record<string, unknown>;
    migrations: PluginMigration[];
    dependencies?: Record<string, string>;
    migrationIdentity?: string;
    jsonDocuments?: JsonDocumentContract[];
}

Parameters

Name	Type	Required	Description
`id`	`string`	Yes	Unique lowercase data-contract identity; default migration identity is data- followed by this ID.
`version`	`string`	Yes	Valid semantic version of the trusted data-contract release.
`description`	`string`	Yes	Human-readable metadata describing the capability, workflow node or requirement to host users.
`schema`	`Record<string, unknown>`	Yes	JSON Schema defining owned table/document structure; schema declarations do not apply migrations by themselves.
`migrations`	`PluginMigration[]`	Yes	Ordered driver-specific migration declarations; collecting them does not execute SQL.
`dependencies`	`Record<string, string>`	No	Declared prerequisites; shared data contracts use ID-to-semver ranges and plugin/skill metadata uses identity lists.
`migrationIdentity`	`string`	No	Stable historical migration ledger identity; never grants plugin activation.
`jsonDocuments`	`JsonDocumentContract[]`	No	Canonical JSON contents and ownership; changing these requires a contract version bump.

Returns

Type declaration; no runtime value.

Public members

`id`

Unique lowercase data-contract identity; default migration identity is data- followed by this ID.

`version`

Valid semantic version of the trusted data-contract release.

`description`

Human-readable metadata describing the capability, workflow node or requirement to host users.

`schema`

JSON Schema defining owned table/document structure; schema declarations do not apply migrations by themselves.

`migrations`

Ordered driver-specific migration declarations; collecting them does not execute SQL.

`dependencies`

Declared prerequisites; shared data contracts use ID-to-semver ranges and plugin/skill metadata uses identity lists.

`migrationIdentity`

Stable historical migration ledger identity; never grants plugin activation.

`jsonDocuments`

Canonical JSON contents and ownership; changing these requires a contract version bump.

Example

See the owning declaration and linked feature guide for usage; no standalone example is documented in source.

[INTERFACE] `DataContractBinding`

Required semantic-version range and table ownership for a plugin namespace.

Imports: @alneas/eaos-core, @alneas/eaos-core/data-contracts, @alneas/eaos-core/contracts/data-contracts.

Signature

interface DataContractBinding {
    contractId: string;
    version: string;
    table: string;
    namespace?: string;
}

Parameters

Name	Type	Required	Description
`contractId`	`string`	Yes	Owning shared data-contract identity; not a plugin activation grant.
`version`	`string`	Yes	Accepted semantic-version range for the owning data contract.
`table`	`string`	Yes	Physical table name declared by the owning data contract.
`namespace`	`string`	No	Logical provider/plugin namespace used to prevent ownership collisions.

Returns

Type declaration; no runtime value.

Public members

`contractId`

Owning shared data-contract identity; not a plugin activation grant.

`version`

Accepted semantic-version range for the owning data contract.

`table`

Physical table name declared by the owning data contract.

`namespace`

Logical provider/plugin namespace used to prevent ownership collisions.

Example

See the owning declaration and linked feature guide for usage; no standalone example is documented in source.

[INTERFACE] `DataContractCatalog`

Selected dependency-ordered contracts and sorted table ownership metadata.

Imports: @alneas/eaos-core, @alneas/eaos-core/data-contracts, @alneas/eaos-core/contracts/data-contracts.

Signature

interface DataContractCatalog {
    contracts: DataContract[];
    tables: {
        name: string;
        contractId: string;
        version: string;
        schema: Record<string, unknown>;
    }[];
}

Parameters

Name	Type	Required	Description
`contracts`	`DataContract[]`	Yes	Selected contract releases in dependency-first order; references point to supplied trusted releases.
`tables`	`{ name: string; contractId: string; version: string; schema: Record<string, unknown>; }[]`	Yes	Owned physical table metadata in sorted name order after contract resolution.

Returns

Type declaration; no runtime value.

Public members

`contracts`

Selected contract releases in dependency-first order; references point to supplied trusted releases.

`tables`

Owned physical table metadata in sorted name order after contract resolution.

`tables[].name`

Physical table name declared by the owning data contract.

`tables[].contractId`

Owning shared data-contract identity; not a plugin activation grant.

`tables[].version`

Selected owner contract release version for this table.

`tables[].schema`

JSON Schema defining owned table/document structure; schema declarations do not apply migrations by themselves.

Example

See the owning declaration and linked feature guide for usage; no standalone example is documented in source.

[FUNCTION] `dataContractTables`

Extract tenant-scoped table definitions from a contract schema and its direct $defs.

Imports: @alneas/eaos-core, @alneas/eaos-core/data-contracts, @alneas/eaos-core/contracts/data-contracts.

Signature

declare function dataContractTables(schema: Record<string, unknown>): Map<string, Record<string, unknown>>;

Parameters

Name	Type	Required	Description
`schema`	`Record<string, unknown>`	Yes	Root JSON schema plus optional direct $defs entries with x-db.tableName.

Returns

Map<string, Record<string, unknown>>

A new insertion-ordered map of table names to the original schema definition objects.

Remarks

No SQL runs; definitions are not cloned.

Errors and rejections

Error for invalid/duplicate table names, missing required tenant_id or no declared tables.

Example

import { dataContractTables } from "@alneas/eaos-core/contracts/data-contracts";
const tables = dataContractTables({ type: "object", properties: { tenant_id: { type: "string" } }, required: ["tenant_id"], "x-db": { tableName: "notes" } });
console.log([...tables.keys()]); // ["notes"]

[TYPE] `DataSensitivityLevel`

Prompt data classification used by heuristic sanitization and routing.

Imports: @alneas/eaos-core, @alneas/eaos-core/agentic, @alneas/eaos-core/agentic/types.

Signature

type DataSensitivityLevel = 'level1_public' | 'level2_internal' | 'level3_strict';

Parameters

Name	Type	Required	Description
—	—	—	No call parameters.

Returns

Type declaration; no runtime value.

Example

See the owning declaration and linked feature guide for usage; no standalone example is documented in source.

[CONSTANT] `dataStandardSchemas`

Frozen scalar JSON Schemas for identities, revisions, money, quantities, ratios, dates and instants.

Imports: @alneas/eaos-core/plugin-sdk, @alneas/eaos-core/plugin-sdk/data-standards.

Signature

declare const dataStandardSchemas: {
    readonly id: {
        readonly type: "string";
        readonly minLength: 1;
        readonly maxLength: 256;
        readonly pattern: "^(?!.*[\\u0000-\\u001f\\u007f])\\S(?:.*\\S)?$";
    };
    readonly revision: {
        readonly type: "integer";
        readonly minimum: 1;
        readonly maximum: number;
    };
    readonly moneyMinor: {
        readonly type: "integer";
        readonly minimum: number;
        readonly maximum: number;
    };
    readonly nonnegativeMoneyMinor: {
        readonly type: "integer";
        readonly minimum: 0;
        readonly maximum: number;
    };
    readonly currency: {
        readonly type: "string";
        readonly pattern: "^[A-Z]{3}$";
    };
    readonly quantity: {
        readonly type: "number";
        readonly minimum: 0;
    };
    readonly quantityUnit: {
        readonly type: "string";
        readonly enum: readonly [
            "m",
            "m2",
            "m3",
            "kg",
            "each",
            "lot",
            "hour",
            "day"
        ];
    };
    readonly ratio: {
        readonly type: "number";
        readonly minimum: 0;
        readonly maximum: 1;
    };
    readonly businessDate: {
        readonly type: "string";
        readonly format: "date";
        readonly pattern: "^\\d{4}-\\d{2}-\\d{2}$";
    };
    readonly instant: {
        readonly type: "string";
        readonly format: "date-time";
        readonly pattern: "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}(?:\\.\\d{1,9})?(?:Z|[+-]\\d{2}:\\d{2})$";
    };
};

Parameters

Name	Type	Required	Description
—	—	—	No call parameters.

Returns

Declared constant value.

Example

See the owning declaration and linked feature guide for usage; no standalone example is documented in source.

[TYPE] `DbDriverType`

Unified Database Adapter Interface for EAOS Allows seamless switching between Oracle ADB (OCI VPD), PostgreSQL/Neon (RLS) and local SQLite.

This file defines the contract only. Implementations live in the consuming app (e.g. apps/backend/server/db/) to avoid pulling driver dependencies into core.

Imports: @alneas/eaos-core, @alneas/eaos-core/db, @alneas/eaos-core/db/adapter.

Signature

type DbDriverType = 'oracle' | 'supabase' | 'postgres';

Parameters

Name	Type	Required	Description
—	—	—	No call parameters.

Returns

Type declaration; no runtime value.

Example

See the owning declaration and linked feature guide for usage; no standalone example is documented in source.

[FUNCTION] `decimalToMinor`

Convert exact decimal text to a safe integer without rounding.

Imports: @alneas/eaos-core/plugin-sdk, @alneas/eaos-core/plugin-sdk/decimal-values.

Signature

declare function decimalToMinor(value: string, minorUnits: number): number;

Parameters

Name	Type	Required	Description
`value`	`string`	Yes	Decimal text accepted by assertDecimalValue.
`minorUnits`	`number`	Yes	Power-of-ten exponent from 0 to 18, such as 2 for cents.

Returns

number

The safe integer amount in minor units.

Errors and rejections

Error for invalid decimal/exponent, required rounding or a result outside the safe integer range.

Example

import { decimalToMinor } from "@alneas/eaos-core/plugin-sdk/decimal-values";
console.log(decimalToMinor("12.50", 2)); // 1250

[CONSTANT] `decimalValueSchema`

Exact, bounded decimal strings. No implicit rounding or binary-float arithmetic.

Imports: @alneas/eaos-core/plugin-sdk, @alneas/eaos-core/plugin-sdk/decimal-values.

Signature

declare const decimalValueSchema: {
    readonly type: "string";
    readonly maxLength: 40;
    readonly pattern: "^(?=(?:[^0-9]*[0-9]){1,38}[^0-9]*$)-?(?:0|[1-9][0-9]*)(?:\\.[0-9]{1,18})?$";
};

Parameters

Name	Type	Required	Description
—	—	—	No call parameters.

Returns

Declared constant value.

Example

See the owning declaration and linked feature guide for usage; no standalone example is documented in source.

[CONSTANT] `DEFAULT_PLUGIN_STORAGE_POLICY`

Default 4 MiB payload limit, optional object storage, indefinite history and no archive.

Imports: @alneas/eaos-core/plugin-sdk, @alneas/eaos-core/plugin-sdk/storage-policy.

Signature

declare const DEFAULT_PLUGIN_STORAGE_POLICY: Readonly<PluginStoragePolicy>;

Parameters

Name	Type	Required	Description
—	—	—	No call parameters.

Returns

Declared constant value.

Example

See the owning declaration and linked feature guide for usage; no standalone example is documented in source.

[FUNCTION] `defaultRuntimePlacementPolicy`

Return a detached policy so a host cannot mutate the shared defaults.

Imports: @alneas/eaos-core, @alneas/eaos-core/agentic, @alneas/eaos-core/agentic/runtime-policy.

Signature

declare function defaultRuntimePlacementPolicy(): RuntimePlacementPolicy;

Parameters

Name	Type	Required	Description
—	—	—	No call parameters.

Returns

RuntimePlacementPolicy

A detached policy with one concurrent AI runtime, 900000 ms limit, 2048 MB memory, 100 PIDs, 64 MiB /tmp and 1 GiB ephemeral workspace.

Remarks

This is configuration data. The host must translate and enforce it; no resources, filesystem mounts or processes are created.

Example

import { defaultRuntimePlacementPolicy } from "@alneas/eaos-core/agentic/runtime-policy";
console.log(defaultRuntimePlacementPolicy().ai.agentRuntime.maxConcurrent); // 1

[INTERFACE] `DefinedPlugin`

Frozen plugin metadata with the collected route definitions replacing the registration callback.

Imports: @alneas/eaos-core, @alneas/eaos-core/plugin-sdk, @alneas/eaos-core/plugin-sdk/define-plugin.

Signature

interface DefinedPlugin extends Omit<PluginDefinition, 'routes'> {
    readonly routeDefinitions: readonly PluginRoute[];
}

Parameters

Name	Type	Required	Description
`routeDefinitions`	`readonly PluginRoute[]`	Yes	Readonly collected method/path/handler records; definePlugin freezes the array and each route object.

Returns

Type declaration; no runtime value.

Public members

`routeDefinitions`

Readonly collected method/path/handler records; definePlugin freezes the array and each route object.

Example

See the owning declaration and linked feature guide for usage; no standalone example is documented in source.

[FUNCTION] `definePlugin`

No server/database import: hosts supply connected capabilities after live admission.

Imports: @alneas/eaos-core, @alneas/eaos-core/plugin-sdk, @alneas/eaos-core/plugin-sdk/define-plugin.

Signature

declare function definePlugin<TServices = Record<string, unknown>>(definition: PluginDefinition<TServices>): DefinedPlugin;

Parameters

Name	Type	Required	Description
`definition`	`PluginDefinition<TServices>`	Yes	Plugin metadata and a synchronous route-registration callback. Duplicate method/path pairs are rejected.

Returns

DefinedPlugin

Frozen metadata and route array; version defaults to 0.0.0, and entitlement/schema dependencies are copied.

Type parameters

TServices: Host services exposed to handlers; defaults to a record of unknown values.

Remarks

Runs routes synchronously during definition. Does not mount handlers or connect database/storage; the host supplies scoped capabilities after admission.

Errors and rejections

Error for invalid ID, entitlement, route or duplicate method/path; route-registration callback errors propagate.

Example

import { definePlugin } from "@alneas/eaos-core/plugin-sdk/define-plugin";
const plugin = definePlugin({ id: "notes", routes(router) { router.get("/status", () => ({ ready: true })); } });
console.log(plugin.routeDefinitions.length); // 1

[FUNCTION] `deliverWithRetry`

POST a signed JSON webhook with bounded exponential retry attempts.

Imports: @alneas/eaos-core, @alneas/eaos-core/webhook, @alneas/eaos-core/webhook/delivery.

Signature

declare function deliverWithRetry(options: DeliveryOptions): Promise<DeliveryResult>;

Parameters

Name	Type	Required	Description
`options`	`DeliveryOptions`	Yes	Destination, secret and payload; maxRetries is the total attempt count (default 3), backoffMs is the base delay (default 1000), and custom headers override generated headers.

Returns

Promise<DeliveryResult>

Success with one-based attempt/status, or failure data after attempts are exhausted; HTTP and fetch errors are returned rather than thrown.

Remarks

Requires fetch and node:crypto. All non-2xx responses/fetch errors are retried; there is no cancellation or request timeout. The timestamp/signature are reused across attempts; the receiver must handle duplicate effects safely. No options validation is performed.

Errors and rejections

Rejects if initial JSON serialization or signature construction fails before delivery.

Example

import { deliverWithRetry } from "@alneas/eaos-core/webhook/delivery";
const destination = process.env.WEBHOOK_TEST_URL;
const secret = process.env.WEBHOOK_TEST_SECRET;
if (!destination || !secret) throw new Error("Configure a test receiver and its shared secret");
const result = await deliverWithRetry({ url: destination, secret, payload: { event: "demo", timestamp: Date.now(), data: { message: "hello" } } });
console.log(result);

[INTERFACE] `DeliveryOptions`

Destination, signing secret, payload, attempt count and optional header overrides.

Imports: @alneas/eaos-core, @alneas/eaos-core/webhook, @alneas/eaos-core/webhook/delivery.

Signature

interface DeliveryOptions {
    url: string;
    secret: string;
    payload: WebhookPayload;
    maxRetries?: number;
    backoffMs?: number;
    headers?: Record<string, string>;
}

Parameters

Name	Type	Required	Description
`url`	`string`	Yes	Target/observed HTTP(S) location; adapter/host authorization must restrict navigation and delivery.
`secret`	`string`	Yes	Shared or one-time secret value; keep it out of persistence/logs except through host-approved secret storage.
`payload`	`WebhookPayload`	Yes	Typed event/request body; constructors clone and strictly hash JSON where documented.
`maxRetries`	`number`	No	Total POST attempt count, despite the name; defaults to 3.
`backoffMs`	`number`	No	Optional base retry delay in milliseconds, validated from 0 to 300000.
`headers`	`Record<string, string>`	No	Optional headers overriding generated content type, timestamp and signature headers.

Returns

Type declaration; no runtime value.

Public members

`url`

Target/observed HTTP(S) location; adapter/host authorization must restrict navigation and delivery.

`secret`

Shared or one-time secret value; keep it out of persistence/logs except through host-approved secret storage.

`payload`

Typed event/request body; constructors clone and strictly hash JSON where documented.

`maxRetries`

Total POST attempt count, despite the name; defaults to 3.

`backoffMs`

Optional base retry delay in milliseconds, validated from 0 to 300000.

`headers`

Optional headers overriding generated content type, timestamp and signature headers.

Example

See the owning declaration and linked feature guide for usage; no standalone example is documented in source.

[INTERFACE] `DeliveryResult`

HTTP delivery outcome returned as data with the final attempt number.

Imports: @alneas/eaos-core, @alneas/eaos-core/webhook, @alneas/eaos-core/webhook/delivery.

Signature

interface DeliveryResult {
    success: boolean;
    attempt: number;
    statusCode?: number;
    error?: string;
}

Parameters

Name	Type	Required	Description
`success`	`boolean`	Yes	Reported completion flag; inspect status/receipt and reconcile any uncertain side effects before retrying.
`attempt`	`number`	Yes	Host-recorded one-based execution attempt; helpers consuming it require a positive integer.
`statusCode`	`number`	No	Optional HTTP status received on the final/successful attempt.
`error`	`string`	No	Optional human-readable failure detail; absence does not independently establish success.

Returns

Type declaration; no runtime value.

Public members

`success`

Reported completion flag; inspect status/receipt and reconcile any uncertain side effects before retrying.

`attempt`

Host-recorded one-based execution attempt; helpers consuming it require a positive integer.

`statusCode`

Optional HTTP status received on the final/successful attempt.

`error`

Optional human-readable failure detail; absence does not independently establish success.

Example

See the owning declaration and linked feature guide for usage; no standalone example is documented in source.

[INTERFACE] `DiscussionRound`

One participant contribution and optional similarity measurement.

Imports: @alneas/eaos-core, @alneas/eaos-core/agentic, @alneas/eaos-core/agentic/types.

Signature

interface DiscussionRound {
    roundNumber: number;
    agentId: string;
    agentName: string;
    role: string;
    content: string;
    isRedTeamReview: boolean;
    similarityScoreWithPrevious?: number;
    timestamp: string;
}

Parameters

Name	Type	Required	Description
`roundNumber`	`number`	Yes	Position of the contribution in the discussion sequence.
`agentId`	`string`	Yes	Agent identity associated with the session, execution or assignment.
`agentName`	`string`	Yes	Display name of the contributing agent.
`role`	`string`	Yes	Role label reported for this discussion contribution.
`content`	`string`	Yes	Loaded skill instructions, model response text or proposed file content; treat external text as untrusted input.
`isRedTeamReview`	`boolean`	Yes	Whether this contribution represents an adversarial/review perspective.
`similarityScoreWithPrevious`	`number`	No	Optional host-computed similarity to the previous contribution.
`timestamp`	`string`	Yes	Host-recorded timestamp for this discussion contribution.

Returns

Type declaration; no runtime value.

Public members

`roundNumber`

Position of the contribution in the discussion sequence.

`agentId`

Agent identity associated with the session, execution or assignment.

`agentName`

Display name of the contributing agent.

`role`

Role label reported for this discussion contribution.

`content`

Loaded skill instructions, model response text or proposed file content; treat external text as untrusted input.

`isRedTeamReview`

Whether this contribution represents an adversarial/review perspective.

`similarityScoreWithPrevious`

Optional host-computed similarity to the previous contribution.

`timestamp`

Host-recorded timestamp for this discussion contribution.

Example

See the owning declaration and linked feature guide for usage; no standalone example is documented in source.

[INTERFACE] `DiscussionSession`

Multi-agent discussion participants, rounds and convergence settings.

Imports: @alneas/eaos-core, @alneas/eaos-core/agentic, @alneas/eaos-core/agentic/types.

Signature

interface DiscussionSession {
    id: string;
    taskId: string;
    topic: string;
    participants: AgentNode[];
    rounds: DiscussionRound[];
    status: 'active' | 'converged' | 'max_turns_reached' | 'escalated';
    maxTurns: number;
    similarityThreshold: number;
    finalSummary?: string;
}

Parameters

Name	Type	Required	Description
`id`	`string`	Yes	Host identity of the multi-agent discussion session.
`taskId`	`string`	Yes	Task identity correlating the agent/runtime operation with its owning workflow or task board.
`topic`	`string`	Yes	Exact event dispatch key used to locate a registered host handler.
`participants`	`AgentNode[]`	Yes	Agent records taking part in the discussion.
`rounds`	`DiscussionRound[]`	Yes	Discussion contributions in stored order.
`status`	`'active' \| 'converged' \| 'max_turns_reached' \| 'escalated'`	Yes	Host discussion progress/convergence outcome.
`maxTurns`	`number`	Yes	Host-configured discussion turn cap; Core types do not enforce it.
`similarityThreshold`	`number`	Yes	Convergence threshold conventionally from zero to one; host discussion logic enforces it.
`finalSummary`	`string`	No	Optional host-approved discussion conclusion.

Returns

Type declaration; no runtime value.

Public members

`id`

Host identity of the multi-agent discussion session.

`taskId`

Task identity correlating the agent/runtime operation with its owning workflow or task board.

`topic`

Exact event dispatch key used to locate a registered host handler.

`participants`

Agent records taking part in the discussion.

`rounds`

Discussion contributions in stored order.

`status`

Host discussion progress/convergence outcome.

`maxTurns`

Host-configured discussion turn cap; Core types do not enforce it.

`similarityThreshold`

Convergence threshold conventionally from zero to one; host discussion logic enforces it.

`finalSummary`

Optional host-approved discussion conclusion.

Example

See the owning declaration and linked feature guide for usage; no standalone example is documented in source.

[CLASS] `DomainEventBus`

Maintain in-memory subscriptions and dispatch payloads synchronously.

Imports: @alneas/eaos-core, @alneas/eaos-core/plugin-sdk, @alneas/eaos-core/plugin-sdk/event-bus.

Signature

declare class DomainEventBus {
    publish<T>(eventName: string, payload: T): void;
    subscribe<T>(eventName: string, handler: EventHandler<T>): void;
    unsubscribe<T>(eventName: string, handler: EventHandler<T>): void;
}

Parameters

Name	Type	Required	Description
—	—	—	No call parameters.

Returns

DomainEventBus

Remarks

No persistence, buffering, retries or tenant filtering is supplied. Use one bus per host/request scope; listeners receive the original payload reference.

Public members

`publish`

Invoke current listeners synchronously in Set iteration order.

Parameters:

eventName: Exact subscription key.
payload: Payload passed by reference to each listener.

Returns: No value; synchronous dispatch has finished, but listener Promises are not awaited.

Type parameters

T: Payload type agreed by publisher and listener; no runtime check occurs.

Remarks

Rejected listener Promises are not handled by the bus; listeners must handle asynchronous failures.

Errors and rejections

Synchronous listener errors propagate and stop dispatch to later listeners.

Example:

import { DomainEventBus } from "@alneas/eaos-core/plugin-sdk/event-bus";
const bus = new DomainEventBus();
bus.publish("note.created", { id: "note-1" });

`subscribe`

Add a listener to an event key.

Parameters:

eventName: Exact event key.
handler: Listener invoked during publish with the original payload. Repeated registration of the same function is deduplicated.

Returns: No value; the listener is registered.

Type parameters

T: Payload type agreed by publisher and listener; no runtime check occurs.

Remarks

Caller owns unsubscription; payload typing is a caller contract rather than runtime validation.

Example:

import { DomainEventBus } from "@alneas/eaos-core/plugin-sdk/event-bus";
const bus = new DomainEventBus();
const handler = (payload: { id: string }) => { console.log(payload.id); };
bus.subscribe("note.created", handler);
bus.unsubscribe("note.created", handler);

`unsubscribe`

Remove a listener by its function identity.

Parameters:

eventName: Subscription key.
handler: The same function reference passed to subscribe.

Returns: No value; absent subscriptions are ignored.

Type parameters

T: Payload type agreed by publisher and listener; no runtime check occurs.

Example:

import { DomainEventBus } from "@alneas/eaos-core/plugin-sdk/event-bus";
const bus = new DomainEventBus();
const handler = (payload: { id: string }) => { console.log(payload.id); };
bus.subscribe("note.created", handler);
bus.unsubscribe("note.created", handler);

Example

import { DomainEventBus } from "@alneas/eaos-core/plugin-sdk/event-bus";
const bus = new DomainEventBus();
const handler = (payload: { id: string }) => { console.log(payload.id); };
bus.subscribe("note.created", handler);
bus.publish("note.created", { id: "note-1" });
bus.unsubscribe("note.created", handler);

[CLASS] `DurableAuditTrail`

Serialize audit events through a host sink and advance the local hash only after acceptance.

Imports: @alneas/eaos-core, @alneas/eaos-core/security/platform-security.

Signature

declare class DurableAuditTrail {
    constructor(sink: AuditSink<PlatformAuditEvent>, clock?: () => Date);
    append(input: PlatformAuditEventInput): Promise<PlatformAuditEvent>;
}

Parameters

Name	Type	Required	Description
`sink`	`AuditSink<PlatformAuditEvent>`	Yes	Host durable append capability; awaited before advancing this instance hash.
`clock`	`() => Date`	No	Optional timestamp callback invoked for each append; defaults to current Date.

Returns

DurableAuditTrail

Remarks

Requires node:crypto. Each instance starts at zero-hash genesis and has no persisted-head recovery API; host lifecycle must avoid presenting independent instances as one continuous chain. A rejected sink may have partially committed; deduplication/reconciliation belong to the host.

Constructor contract

Public members

`append`

Clone and append one hash-linked event after earlier queued appends settle.

Parameters:

input: Audit scope/action/outcome; copied before generated UUID, timestamp and previousHash are added.

Returns: The appended event after sink acceptance; the sink receives a separate structured clone.

Remarks

A failure does not stop subsequent queued appends. No cancellation or retry is implemented; a rejected host write can have an uncertain durable outcome.

Errors and rejections

Rejects on cloning/serialization/date failures or propagated sink rejection.

Example:

import { DurableAuditTrail } from "@alneas/eaos-core/security/platform-security";
import type { AuditSink } from "@alneas/eaos-core/security/audit-sink";
import type { PlatformAuditEvent } from "@alneas/eaos-core/security/platform-security";
async function appendHostEvent(sink: AuditSink<PlatformAuditEvent>) {
 const trail = new DurableAuditTrail(sink);
 return trail.append({ tenantId: "tenant-demo", userId: "user-demo", action: "notes.preview", outcome: "success" });
}

Example

import { DurableAuditTrail } from "@alneas/eaos-core/security/platform-security";
import type { AuditSink } from "@alneas/eaos-core/security/audit-sink";
import type { PlatformAuditEvent } from "@alneas/eaos-core/security/platform-security";
async function appendHostEvent(sink: AuditSink<PlatformAuditEvent>) {
 const trail = new DurableAuditTrail(sink);
 return trail.append({ tenantId: "tenant-demo", userId: "user-demo", action: "notes.preview", outcome: "success" });
}

[INTERFACE] `EaosEnv`

Hono-compatible environment wrapper around EAOS request variables.

Imports: @alneas/eaos-core, @alneas/eaos-core/types/env.

Signature

interface EaosEnv {
    Variables: EaosVariables;
}

Parameters

Name	Type	Required	Description
`Variables`	`EaosVariables`	Yes	Hono-compatible request variable contract populated by host middleware.

Returns

Type declaration; no runtime value.

Public members

`Variables`

Hono-compatible request variable contract populated by host middleware.

Example

See the owning declaration and linked feature guide for usage; no standalone example is documented in source.

[INTERFACE] `EaosUser`

Verified request user identity and optional contact/permission claims.

Imports: @alneas/eaos-core, @alneas/eaos-core/types/env.

Signature

interface EaosUser {
    id: string;
    email?: string;
    tenantId: string;
    roles: string[];
    permissions?: string[];
}

Parameters

Name	Type	Required	Description
`id`	`string`	Yes	Host-verified user identity installed in request variables.
`email`	`string`	No	Optional contact email from the host identity system; not proof of email verification.
`tenantId`	`string`	Yes	Verified tenant boundary for the record or operation; host authorization must establish this scope.
`roles`	`string[]`	Yes	Role claims supplied by the host after identity verification.
`permissions`	`string[]`	No	Optional explicit permission names interpreted and enforced by the host.

Returns

Type declaration; no runtime value.

Public members

`id`

Host-verified user identity installed in request variables.

`email`

Optional contact email from the host identity system; not proof of email verification.

`tenantId`

Verified tenant boundary for the record or operation; host authorization must establish this scope.

`roles`

Role claims supplied by the host after identity verification.

`permissions`

Optional explicit permission names interpreted and enforced by the host.

Example

See the owning declaration and linked feature guide for usage; no standalone example is documented in source.

[INTERFACE] `EaosVariables`

Host-populated request variables for data, storage, events and secret capabilities.

Imports: @alneas/eaos-core, @alneas/eaos-core/types/env.

Signature

interface EaosVariables {
    tenantId?: string;
    user?: EaosUser;
    db?: DataAccessAdapter;
    storage?: StorageAdapter;
    events?: DomainEventBus;
    secrets?: typeof SecretResolver;
    [key: string]: any;
}

Parameters

Name	Type	Required	Description
`tenantId`	`string`	No	Verified tenant boundary for the record or operation; host authorization must establish this scope.
`user`	`EaosUser`	No	Optional verified request user installed by host middleware.
`db`	`DataAccessAdapter`	No	Host-owned data-access capability; callers must supply tenant/admission scope where required.
`storage`	`StorageAdapter`	No	Host-owned scoped object storage capability; credentials and persistence remain host-owned.
`events`	`DomainEventBus`	No	In-memory domain event bus for the host/request context.
`secrets`	`typeof SecretResolver`	No	Host secret capability or declarations; Core does not provision an external secret store.

Returns

Type declaration; no runtime value.

Public members

`tenantId`

Verified tenant boundary for the record or operation; host authorization must establish this scope.

`user`

Optional verified request user installed by host middleware.

`db`

Host-owned data-access capability; callers must supply tenant/admission scope where required.

`storage`

Host-owned scoped object storage capability; credentials and persistence remain host-owned.

`events`

In-memory domain event bus for the host/request context.

`secrets`

Host secret capability or declarations; Core does not provision an external secret store.

Example

See the owning declaration and linked feature guide for usage; no standalone example is documented in source.

[INTERFACE] `EligibilityCourseRequirement`

Shared eligibility contract used by training, procedure and task plugins.

Imports: @alneas/eaos-core/plugin-sdk, @alneas/eaos-core/plugin-sdk/eligibility.

Signature

interface EligibilityCourseRequirement {
    namespace: string;
    id: string;
    version: string;
    contentHash: string;
}

Parameters

Name	Type	Required	Description
`namespace`	`string`	Yes	Logical provider/plugin namespace used to prevent ownership collisions.
`id`	`string`	Yes	Course identity within the named training namespace.
`version`	`string`	Yes	Exact three-component numeric course version required by eligibility.
`contentHash`	`string`	Yes	Exact course-content digest required to match the requested revision.

Returns

Type declaration; no runtime value.

Public members

`namespace`

Logical provider/plugin namespace used to prevent ownership collisions.

`id`

Course identity within the named training namespace.

`version`

Exact three-component numeric course version required by eligibility.

`contentHash`

Exact course-content digest required to match the requested revision.

Example

See the owning declaration and linked feature guide for usage; no standalone example is documented in source.

[INTERFACE] `EligibilityQualificationRequirement`

Issuer-qualified credential identity required for eligibility.

Imports: @alneas/eaos-core/plugin-sdk, @alneas/eaos-core/plugin-sdk/eligibility.

Signature

interface EligibilityQualificationRequirement {
    issuer: string;
    id: string;
}

Parameters

Name	Type	Required	Description
`issuer`	`string`	Yes	Credential-issuing authority used to disambiguate qualification IDs.
`id`	`string`	Yes	Credential identity within its issuing authority.

Returns

Type declaration; no runtime value.

Public members

`issuer`

Credential-issuing authority used to disambiguate qualification IDs.

`id`

Credential identity within its issuing authority.

Example

See the owning declaration and linked feature guide for usage; no standalone example is documented in source.

[INTERFACE] `EligibilityRequirements`

Course and qualification requirements evaluated by host training/credential services.

Imports: @alneas/eaos-core/plugin-sdk, @alneas/eaos-core/plugin-sdk/eligibility.

Signature

interface EligibilityRequirements {
    courses: EligibilityCourseRequirement[];
    qualifications: EligibilityQualificationRequirement[];
}

Parameters

Name	Type	Required	Description
`courses`	`EligibilityCourseRequirement[]`	Yes	Exact course namespace/ID/version/content-hash requirements, or their satisfaction results.
`qualifications`	`EligibilityQualificationRequirement[]`	Yes	Issuer-qualified credential requirements, or their satisfaction results.

Returns

Type declaration; no runtime value.

Public members

`courses`

Exact course namespace/ID/version/content-hash requirements, or their satisfaction results.

`qualifications`

Issuer-qualified credential requirements, or their satisfaction results.

Example

See the owning declaration and linked feature guide for usage; no standalone example is documented in source.

[CONSTANT] `eligibilityRequirementsSchema`

Closed JSON Schema limiting course and qualification requirement arrays to 50 entries each.

Imports: @alneas/eaos-core/plugin-sdk, @alneas/eaos-core/plugin-sdk/eligibility.

Signature

declare const eligibilityRequirementsSchema: {
    readonly type: "object";
    readonly additionalProperties: false;
    readonly required: readonly [
        "courses",
        "qualifications"
    ];
    readonly properties: {
        readonly courses: {
            readonly type: "array";
            readonly maxItems: 50;
            readonly items: {
                readonly type: "object";
                readonly additionalProperties: false;
                readonly required: readonly [
                    "namespace",
                    "id",
                    "version",
                    "contentHash"
                ];
                readonly properties: {
                    readonly namespace: {
                        readonly type: "string";
                        readonly pattern: "^[a-zA-Z0-9_-]{1,64}$";
                    };
                    readonly id: {
                        readonly type: "string";
                        readonly pattern: "^[a-zA-Z0-9_-]{1,80}$";
                    };
                    readonly version: {
                        readonly type: "string";
                        readonly pattern: "^\\d{1,6}\\.\\d{1,6}\\.\\d{1,6}$";
                    };
                    readonly contentHash: {
                        readonly type: "string";
                        readonly pattern: "^[a-f0-9]{64}$";
                    };
                };
            };
        };
        readonly qualifications: {
            readonly type: "array";
            readonly maxItems: 50;
            readonly items: {
                readonly type: "object";
                readonly additionalProperties: false;
                readonly required: readonly [
                    "issuer",
                    "id"
                ];
                readonly properties: {
                    readonly issuer: {
                        readonly type: "string";
                        readonly minLength: 1;
                        readonly maxLength: 100;
                    };
                    readonly id: {
                        readonly type: "string";
                        readonly minLength: 1;
                        readonly maxLength: 100;
                    };
                };
            };
        };
    };
};

Parameters

Name	Type	Required	Description
—	—	—	No call parameters.

Returns

Declared constant value.

Example

import { eligibilityRequirementsSchema } from "@alneas/eaos-core/plugin-sdk/eligibility";
console.log(eligibilityRequirementsSchema.properties.courses.maxItems); // 50

[INTERFACE] `EligibilityResult`

Tenant/user eligibility decision with per-requirement satisfaction evidence and check time.

Imports: @alneas/eaos-core/plugin-sdk, @alneas/eaos-core/plugin-sdk/eligibility.

Signature

interface EligibilityResult {
    tenantId: string;
    userId: string;
    requirementsHash: string;
    eligible: boolean;
    checkedAt: string;
    courses: {
        requirement: EligibilityCourseRequirement;
        satisfied: boolean;
    }[];
    qualifications: {
        requirement: EligibilityQualificationRequirement;
        satisfied: boolean;
    }[];
}

Parameters

Name	Type	Required	Description
`tenantId`	`string`	Yes	Verified tenant boundary for the record or operation; host authorization must establish this scope.
`userId`	`string`	Yes	User identity within the tenant supplied by the trusted host.
`requirementsHash`	`string`	Yes	Stable identity of the eligibility requirements evaluated for this result.
`eligible`	`boolean`	Yes	Whether all declared host requirements were satisfied.
`checkedAt`	`string`	Yes	Timestamp associated with the reported evaluation or measurement.
`courses`	`{ requirement: EligibilityCourseRequirement; satisfied: boolean; }[]`	Yes	Exact course namespace/ID/version/content-hash requirements, or their satisfaction results.
`qualifications`	`{ requirement: EligibilityQualificationRequirement; satisfied: boolean; }[]`	Yes	Issuer-qualified credential requirements, or their satisfaction results.

Returns

Type declaration; no runtime value.

Public members

`tenantId`

Verified tenant boundary for the record or operation; host authorization must establish this scope.

`userId`

User identity within the tenant supplied by the trusted host.

`requirementsHash`

Stable identity of the eligibility requirements evaluated for this result.

`eligible`

Whether all declared host requirements were satisfied.

`checkedAt`

Timestamp associated with the reported evaluation or measurement.

`courses`

Exact course namespace/ID/version/content-hash requirements, or their satisfaction results.

`courses[].requirement`

Exact requirement whose satisfaction is reported by this entry.

`courses[].satisfied`

Whether the host eligibility check found evidence meeting this requirement.

`qualifications`

Issuer-qualified credential requirements, or their satisfaction results.

`qualifications[].requirement`

Exact requirement whose satisfaction is reported by this entry.

`qualifications[].satisfied`

Whether the host eligibility check found evidence meeting this requirement.

Example

See the owning declaration and linked feature guide for usage; no standalone example is documented in source.

[TYPE] `EntitlementDecision`

Admission preview as an allowed status/quota or a denied status/reason.

Imports: @alneas/eaos-core, @alneas/eaos-core/plugin-sdk, @alneas/eaos-core/entitlements.

Signature

type EntitlementDecision = {
    allowed: true;
    status: 200;
    quota?: number;
} | {
    allowed: false;
    status: 402 | 404;
    reason: 'tenant-locked' | 'subscription-required' | 'addon-required' | 'quota-exceeded';
};

Parameters

Name	Type	Required	Description
—	—	—	No call parameters.

Returns

Type declaration; no runtime value.

Public members

`allowed`

Admission/check decision; consumers must inspect it before using the associated result or performing an effect.

`status`

HTTP-style preview status: 200 allowed, 402 subscription/addon denial or 404 tenant allowlist denial.

`quota`

Resolved metering allowance; evaluation does not consume it or compare current usage.

`allowed`

Admission/check decision; consumers must inspect it before using the associated result or performing an effect.

`status`

HTTP-style preview status: 200 allowed, 402 subscription/addon denial or 404 tenant allowlist denial.

`reason`

Human-readable explanation of the decision or requested action.

Example

See the owning declaration and linked feature guide for usage; no standalone example is documented in source.

[FUNCTION] `evaluatePluginEntitlement`

Pure preview shared by server and UI. A UI decision is never a server capability.

Imports: @alneas/eaos-core, @alneas/eaos-core/plugin-sdk, @alneas/eaos-core/entitlements.

Signature

declare function evaluatePluginEntitlement(pluginId: string, rule: PluginEntitlement, tenantId: string, entitlement: TenantEntitlements | null, now?: Date): EntitlementDecision;

Parameters

Name	Type	Required	Description
`pluginId`	`string`	Yes	Valid plugin identifier used as a quota key when no addon ID is set.
`rule`	`PluginEntitlement`	Yes	Plugin policy validated before evaluation.
`tenantId`	`string`	Yes	Tenant whose access is being previewed.
`entitlement`	`TenantEntitlements \| null`	Yes	Trusted tenant snapshot, or null when absent; any supplied tenant ID must match.
`now`	`Date`	No	Evaluation time; defaults to a newly constructed current Date.

Returns

EntitlementDecision

Allowed with optional quota, or a denial carrying status 402/404 and reason. This helper does not consume quota or compare usage.

Remarks

Pure preview only. The host must enforce admission and quotas; an allowed browser result is not a server capability.

Errors and rejections

Error for malformed policies/snapshots, invalid time or scope, or a mismatched tenant.

Example

import { evaluatePluginEntitlement } from "@alneas/eaos-core/entitlements";
console.log(evaluatePluginEntitlement("notes", { tier: "public" }, "tenant-demo", null));

[FUNCTION] `evaluateSkillEligibility`

Evaluates skill requirements without reading host process state from core.

Imports: @alneas/eaos-core, @alneas/eaos-core/ai, @alneas/eaos-core/ai/skills.

Signature

declare function evaluateSkillEligibility(skill: Pick<SkillCatalogEntry, 'requirements'>, availability: SkillRuntimeAvailability): SkillEligibilityResult;

Parameters

Name	Type	Required	Description
`skill`	`Pick<SkillCatalogEntry, 'requirements'>`	Yes	Skill requirement metadata; missing requirements mean no restrictions.
`availability`	`SkillRuntimeAvailability`	Yes	Host OS and available binaries, environment/config names and adapters; missing collections satisfy no entries.

Returns

SkillEligibilityResult

Eligibility plus ordered missing requirement descriptors; empty missing means eligible.

Example

import { evaluateSkillEligibility } from "@alneas/eaos-core/ai/skills";
console.log(evaluateSkillEligibility({ requirements: { bins: ["git"] } }, { os: "linux", bins: ["git"] }));

[FUNCTION] `evaluateWorkflowCondition`

Evaluate the safe, data-only condition language used by compiled workflows.

Imports: @alneas/eaos-core, @alneas/eaos-core/workflow-definition.

Signature

declare function evaluateWorkflowCondition(condition: WorkflowCondition, input: unknown): boolean;

Parameters

Name	Type	Required	Description
`condition`	`WorkflowCondition`	Yes	Validated condition; all/any/not recurse, dotted paths use own properties and equality uses Object.is.
`input`	`unknown`	Yes	State to inspect; arrays and nonobjects cannot be traversed as path containers.

Returns

boolean

Whether the condition matches. Missing paths fail positive comparisons but satisfy not_equals/not_in and falsy.

Remarks

Does not validate the condition first or execute expression strings. Validate untrusted definitions with validateWorkflowDefinition.

Example

import { evaluateWorkflowCondition } from "@alneas/eaos-core/workflow-definition";
console.log(evaluateWorkflowCondition({ path: "amount", operator: "greater_than", value: 10 }, { amount: 12 })); // true

[TYPE] `EventHandler`

Listener called synchronously during publish; returned Promises are not awaited by DomainEventBus.

Imports: @alneas/eaos-core, @alneas/eaos-core/plugin-sdk, @alneas/eaos-core/plugin-sdk/event-bus.

Signature

type EventHandler<T = any> = (payload: T) => Promise<void> | void;

Parameters

Name	Type	Required	Description
—	—	—	No call parameters.

Returns

Type declaration; no runtime value.

No value, or a Promise completing listener work. DomainEventBus does not await/catch returned Promises.

Type parameters

T: Payload shape agreed by publisher/listener; defaults to any without runtime validation.

Example

import type { EventHandler } from "@alneas/eaos-core/plugin-sdk/event-bus";
const listener: EventHandler<{ id: string }> = payload => { console.log(payload.id); };
listener({ id: "note-1" });

[TYPE] `ExecutionBridgeMode`

Select the built-in simulated container path or optional Tauri desktop IPC bridge.

Imports: @alneas/eaos-core, @alneas/eaos-core/agentic, @alneas/eaos-core/agentic/execution-sandbox.

Signature

type ExecutionBridgeMode = 'docker_cloud' | 'tauri_local_cli';

Parameters

Name	Type	Required	Description
—	—	—	No call parameters.

Returns

Type declaration; no runtime value.

Example

See the owning declaration and linked feature guide for usage; no standalone example is documented in source.

[TYPE] `ExecutionCliType`

CLI bridge identifiers recognized by sandbox execution options.

Imports: @alneas/eaos-core, @alneas/eaos-core/agentic, @alneas/eaos-core/agentic/types.

Signature

type ExecutionCliType = 'antigravity' | 'codex' | 'claude' | 'opencode' | 'goose' | 'hermes_agent';

Parameters

Name	Type	Required	Description
—	—	—	No call parameters.

Returns

Type declaration; no runtime value.

Example

See the owning declaration and linked feature guide for usage; no standalone example is documented in source.

[INTERFACE] `ExecutionContract`

The versioned meaning of an operation at the moment an approval is created. Hosts may add fields to the schemas, but must keep the value JSON-safe.

Imports: @alneas/eaos-core, @alneas/eaos-core/agent/approved-execution.

Signature

interface ExecutionContract {
    operation: string;
    version: string;
    permission: string;
    sideEffect: ExecutionSideEffect;
    riskLevel: RiskLevel;
    approvalLevel: ApprovalLevel;
    inputSchema: Record<string, unknown>;
    outputSchema?: Record<string, unknown>;
}

Parameters

Name	Type	Required	Description
`operation`	`string`	Yes	Operation identity whose meaning and permission are controlled by the host.
`version`	`string`	Yes	Operation semantic version text captured in approval identity, at most 64 nonblank characters.
`permission`	`string`	Yes	Host permission identity required for this operation.
`sideEffect`	`ExecutionSideEffect`	Yes	Classify whether the operation reads, writes local state or affects an external service.
`riskLevel`	`RiskLevel`	Yes	Declared operation risk used to determine review requirements; it does not itself grant authorization.
`approvalLevel`	`ApprovalLevel`	Yes	Required organizational review category; a level declaration is not proof of approval.
`inputSchema`	`Record<string, unknown>`	Yes	JSON Schema describing admitted operation input.
`outputSchema`	`Record<string, unknown>`	No	Optional JSON Schema describing operation output; absent means no output contract is declared here.

Returns

Type declaration; no runtime value.

Public members

`operation`

Operation identity whose meaning and permission are controlled by the host.

`version`

Operation semantic version text captured in approval identity, at most 64 nonblank characters.

`permission`

Host permission identity required for this operation.

`sideEffect`

Classify whether the operation reads, writes local state or affects an external service.

`riskLevel`

Declared operation risk used to determine review requirements; it does not itself grant authorization.

`approvalLevel`

Required organizational review category; a level declaration is not proof of approval.

`inputSchema`

JSON Schema describing admitted operation input.

`outputSchema`

Optional JSON Schema describing operation output; absent means no output contract is declared here.

Example

See the owning declaration and linked feature guide for usage; no standalone example is documented in source.

[CLASS] `ExecutionSandbox`

Dispatch a legacy execution request to simulation or an optional Tauri IPC bridge.

Imports: @alneas/eaos-core, @alneas/eaos-core/agentic, @alneas/eaos-core/agentic/execution-sandbox.

Signature

declare class ExecutionSandbox {
    executeCode(request: SandboxExecutionRequest, options?: {
        mode?: ExecutionBridgeMode;
        cliType?: ExecutionCliType;
        userContext?: {
            userId: string;
            roles: string[];
        };
    }): Promise<{
        requiresHumanApproval: boolean;
        approvalTicketId?: string;
        result?: SandboxExecutionResult;
    }>;
}

Parameters

Name	Type	Required	Description
—	—	—	No call parameters.

Returns

ExecutionSandbox

Remarks

docker_cloud is a simulation and does not run a container or code. tauri_local_cli invokes window.TAURI.invoke when available and otherwise returns simulated success. The current gate uses a fixed tenant key and checks requireHumanApproval withoutenforcing allowed; this helper must not serve as a production authorization or isolation boundary.

Public members

`executeCode`

Return a review ticket or dispatch through the selected legacy execution bridge.

Parameters:

request: Script metadata; docker_cloud reports a simulation, while Tauri receives code as the CLI prompt. timeoutMs/environmentVariables are not enforced here.
options: Mode defaults to docker_cloud, cliType to antigravity and roles to agent; userId is not used by the implementation.

Returns: An approval-required result with an unpersisted ticket ID, or reported/simulated execution data. Tauri IPC errors are converted to exitCode 1.

Remarks

No cancellation, real cloud sandbox, durable ticket, timeout or replay prevention is implemented. A returned success may be simulated. Hosts must use an admitted, scoped execution adapter for real effects.

Example:

import { ExecutionSandbox } from "@alneas/eaos-core/agentic/execution-sandbox";
const sandbox = new ExecutionSandbox();
console.log(await sandbox.executeCode({ taskId: "task-1", agentId: "agent-1", language: "javascript", code: "1 + 1" }));

`executeCode.requiresHumanApproval`

Whether this bridge response requires a separate host approval workflow.

`executeCode.approvalTicketId`

Unpersisted legacy review-ticket identity; the host must not treat it as approval evidence.

`executeCode.result`

Optional reported/simulated execution details; absence accompanies a review-required response.

`executeCode.options.mode`

Selected operation/storage/execution variant; the owning discriminated union determines applicable fields.

`executeCode.options.cliType`

Optional desktop CLI bridge identifier; defaults to antigravity in executeCode.

`executeCode.options.userContext`

Optional desktop bridge user/roles metadata; current implementation reads roles only.

`executeCode.options.userContext.userId`

User identity within the tenant supplied by the trusted host.

`executeCode.options.userContext.roles`

Role claims supplied by the host after identity verification.

Example

import { ExecutionSandbox } from "@alneas/eaos-core/agentic/execution-sandbox";
const sandbox = new ExecutionSandbox();
console.log(await sandbox.executeCode({ taskId: "task-1", agentId: "agent-1", language: "javascript", code: "1 + 1" }));

[TYPE] `ExecutionSideEffect`

Whether an operation reads, writes local state or causes an external effect.

Imports: @alneas/eaos-core, @alneas/eaos-core/agent/approved-execution.

Signature

type ExecutionSideEffect = 'read' | 'write' | 'external';

Parameters

Name	Type	Required	Description
—	—	—	No call parameters.

Returns

Type declaration; no runtime value.

Example

See the owning declaration and linked feature guide for usage; no standalone example is documented in source.

[INTERFACE] `ExecutionTarget`

Optional resource identity and optimistic revision included in an approval binding.

Imports: @alneas/eaos-core, @alneas/eaos-core/agent/approved-execution.

Signature

interface ExecutionTarget {
    type: string;
    id: string;
    revision?: number;
}

Parameters

Name	Type	Required	Description
`type`	`string`	Yes	Resource category used with its ID and optional revision to bind the exact execution target.
`id`	`string`	Yes	Target resource identity; at most 512 nonblank characters when approval-validated.
`revision`	`number`	No	Optional source/target revision interpreted by the owning host; approval/effect target revisions must be positive integers.

Returns

Type declaration; no runtime value.

Public members

`type`

Resource category used with its ID and optional revision to bind the exact execution target.

`id`

Target resource identity; at most 512 nonblank characters when approval-validated.

`revision`

Optional source/target revision interpreted by the owning host; approval/effect target revisions must be positive integers.

Example

See the owning declaration and linked feature guide for usage; no standalone example is documented in source.

[INTERFACE] `ExtendedGatekeeperPolicy`

Tool policy with an explicit approval level and evidence metadata.

Imports: @alneas/eaos-core, @alneas/eaos-core/security/gatekeeper.

Signature

interface ExtendedGatekeeperPolicy extends GatekeeperPolicy {
    approvalLevel?: ApprovalLevel;
    requireEvidence?: boolean;
}

Parameters

Name	Type	Required	Description
`approvalLevel`	`ApprovalLevel`	No	Required organizational review category; a level declaration is not proof of approval.
`requireEvidence`	`boolean`	No	Optional evidence requirement metadata; current McpGatekeeper.validateCall does not enforce it.

Returns

Type declaration; no runtime value.

Public members

`approvalLevel`

Required organizational review category; a level declaration is not proof of approval.

`requireEvidence`

Optional evidence requirement metadata; current McpGatekeeper.validateCall does not enforce it.

Example

See the owning declaration and linked feature guide for usage; no standalone example is documented in source.

[FUNCTION] `externalEntityId`

Deliberately includes tenant, provider account/facility scope and entity kind.

Imports: @alneas/eaos-core/plugin-sdk, @alneas/eaos-core/plugin-sdk/data-standards.

Signature

declare function externalEntityId(tenantId: string, identity: ExternalEntityIdentity): string;

Parameters

Name	Type	Required	Description
`tenantId`	`string`	Yes	Tenant business identifier accepted by assertBusinessId.
`identity`	`ExternalEntityIdentity`	Yes	Provider system, account/facility scope, entity kind and external identifier; each must be a valid business ID.

Returns

string

An ext- prefixed SHA-256 identity incorporating DATA_STANDARDS_VERSION.

Remarks

External identifiers confer no authorization; hashing requires node:crypto.

Errors and rejections

Error when a scope component is not a business ID.

Example

import { externalEntityId } from "@alneas/eaos-core/plugin-sdk/data-standards";
const id = externalEntityId("tenant-demo", { system: "erp", scope: "warehouse-a", entityType: "order", externalId: "123" });
console.log(id);

[INTERFACE] `ExternalEntityIdentity`

Provider system, account/facility scope, entity kind and opaque external ID.

Imports: @alneas/eaos-core/plugin-sdk, @alneas/eaos-core/plugin-sdk/data-standards.

Signature

interface ExternalEntityIdentity {
    system: string;
    scope: string;
    entityType: string;
    externalId: string;
}

Parameters

Name	Type	Required	Description
`system`	`string`	Yes	External provider/system identity used in deterministic entity identity hashing.
`scope`	`string`	Yes	Provider account/facility boundary included in deterministic external-entity identity; must be a valid business ID.
`entityType`	`string`	Yes	External provider entity category used with system/scope/ID to derive a collision-resistant identity.
`externalId`	`string`	Yes	Optional external resource identity reported by the provider.

Returns

Type declaration; no runtime value.

Public members

`system`

External provider/system identity used in deterministic entity identity hashing.

`scope`

Provider account/facility boundary included in deterministic external-entity identity; must be a valid business ID.

`entityType`

External provider entity category used with system/scope/ID to derive a collision-resistant identity.

`externalId`

Optional external resource identity reported by the provider.

Example

See the owning declaration and linked feature guide for usage; no standalone example is documented in source.

[TYPE] `Filter`

Compatibility re-export; its implementation and documentation are owned by the owning package @dataarthub/app-core.

Imports: @alneas/eaos-core, @alneas/eaos-core/adapters, @alneas/eaos-core/adapters/types.

Signature

export type Filter = Record<string, unknown>;

Parameters

Name	Type	Required	Description
—	—	—	No call parameters.

Returns

Type declaration; no runtime value.

Example

See the owning declaration and linked feature guide for usage; no standalone example is documented in source.

[FUNCTION] `filterEligibleSkills`

Select skills whose requirements are satisfied by host availability.

Imports: @alneas/eaos-core, @alneas/eaos-core/ai, @alneas/eaos-core/ai/skills.

Signature

declare function filterEligibleSkills<T extends Pick<SkillCatalogEntry, 'requirements'>>(skills: readonly T[], availability: SkillRuntimeAvailability): readonly T[];

Parameters

Name	Type	Required	Description
`skills`	`readonly T[]`	Yes	Candidates in the desired output order.
`availability`	`SkillRuntimeAvailability`	Yes	Trusted host facts passed to evaluateSkillEligibility.

Returns

readonly T[]

A new array preserving candidate order and original skill references; empty when none qualify.

Type parameters

T: Skill metadata containing optional requirements; returned elements retain this type.

Example

import { filterEligibleSkills } from "@alneas/eaos-core/ai/skills";
const skills = [{ requirements: { bins: ["git"] } }];
console.log(filterEligibleSkills(skills, { os: "linux", bins: ["git"] }).length); // 1

[INTERFACE] `GatekeeperAuditEntry`

Hash-linked local audit record for an allowed, blocked or approval-pending tool call.

Imports: @alneas/eaos-core, @alneas/eaos-core/security/gatekeeper.

Signature

interface GatekeeperAuditEntry {
    id: string;
    traceId?: string;
    toolName: string;
    userId: string;
    tenantId: string;
    status: 'ALLOWED' | 'BLOCKED' | 'PENDING_APPROVAL';
    riskLevel: RiskLevel;
    approvalLevel: ApprovalLevel;
    reason?: string;
    evidence?: {
        intent?: string;
        confidence?: number;
        ruleMatched?: string;
        inputSummary?: string;
    };
    hash: string;
    previousHash?: string;
    timestamp: string;
    args?: Record<string, unknown>;
}

Parameters

Name	Type	Required	Description
`id`	`string`	Yes	Generated local audit identity; not a durable approval token.
`traceId`	`string`	No	Trace correlation identity propagated through host execution and audit paths.
`toolName`	`string`	Yes	Registered tool identity used to resolve host execution policy.
`userId`	`string`	Yes	User identity within the tenant supplied by the trusted host.
`tenantId`	`string`	Yes	Verified tenant boundary for the record or operation; host authorization must establish this scope.
`status`	`'ALLOWED' \| 'BLOCKED' \| 'PENDING_APPROVAL'`	Yes	Observed policy outcome: allowed, blocked or pending review; does not itself grant approval.
`riskLevel`	`RiskLevel`	Yes	Declared operation risk used to determine review requirements; it does not itself grant authorization.
`approvalLevel`	`ApprovalLevel`	Yes	Required organizational review category; a level declaration is not proof of approval.
`reason`	`string`	No	Human-readable explanation of the decision or requested action.
`evidence`	`{ intent?: string; confidence?: number; ruleMatched?: string; inputSummary?: string; }`	No	Source references or audit rationale supporting review; evidence is data and does not grant execution authority.
`hash`	`string`	Yes	Content integrity digest; hashes are unkeyed and do not establish authorization or writer authenticity.
`previousHash`	`string`	No	Previous audit event hash used to link ordered entries.
`timestamp`	`string`	Yes	ISO timestamp generated when the local audit entry is constructed.
`args`	`Record<string, unknown>`	No	Operation arguments passed to hooks or bound into a proposed action; authorization and schema checks remain host-owned.

Returns

Type declaration; no runtime value.

Public members

`id`

Generated local audit identity; not a durable approval token.

`traceId`

Trace correlation identity propagated through host execution and audit paths.

`toolName`

Registered tool identity used to resolve host execution policy.

`userId`

User identity within the tenant supplied by the trusted host.

`tenantId`

Verified tenant boundary for the record or operation; host authorization must establish this scope.

`status`

Observed policy outcome: allowed, blocked or pending review; does not itself grant approval.

`riskLevel`

Declared operation risk used to determine review requirements; it does not itself grant authorization.

`approvalLevel`

Required organizational review category; a level declaration is not proof of approval.

`reason`

Human-readable explanation of the decision or requested action.

`evidence`

Source references or audit rationale supporting review; evidence is data and does not grant execution authority.

`evidence.intent`

Optional statement of the requested action used as audit evidence.

`evidence.confidence`

Reported confidence ratio, conventionally from zero to one; validate at the consuming boundary.

`evidence.ruleMatched`

Optional policy-rule identity reported as audit evidence.

`evidence.inputSummary`

Optional human-readable argument summary; avoid placing secrets in audit evidence.

`hash`

Content integrity digest; hashes are unkeyed and do not establish authorization or writer authenticity.

`previousHash`

Previous audit event hash used to link ordered entries.

`timestamp`

ISO timestamp generated when the local audit entry is constructed.

`args`

Operation arguments passed to hooks or bound into a proposed action; authorization and schema checks remain host-owned.

Example

See the owning declaration and linked feature guide for usage; no standalone example is documented in source.

[INTERFACE] `GatekeeperAuditSink`

Host-owned durable audit delivery. Core keeps only a bounded local view.

Imports: @alneas/eaos-core, @alneas/eaos-core/security/gatekeeper.

Signature

interface GatekeeperAuditSink {
    append(entry: Readonly<GatekeeperAuditEntry>): Promise<void> | void;
}

Parameters

Name	Type	Required	Description
`append`	`Promise<void> \| void`	Yes	Deliver one gatekeeper entry to host audit persistence.

Returns

Type declaration; no runtime value.

Public members

`append`

Deliver one gatekeeper entry to host audit persistence.

Parameters:

entry: Readonly hash-linked audit entry; the gatekeeper supplies a clone.

Returns: No value; synchronous completion or a resolved Promise indicates host acceptance.

Remarks

Host owns durable storage and replay handling; rejecting does not prove no durable write occurred.

Errors and rejections

Host persistence errors/rejections propagate to durable logging.

Example:

import type { GatekeeperAuditSink } from "@alneas/eaos-core/security/gatekeeper";
async function appendGatekeeperAudit(sink: GatekeeperAuditSink, entry: Parameters<GatekeeperAuditSink["append"]>[0]) { await sink.append(entry); }

Example

See the owning declaration and linked feature guide for usage; no standalone example is documented in source.

[INTERFACE] `GatekeeperOptions`

Select whether synchronous best-effort audit logging is permitted.

Imports: @alneas/eaos-core, @alneas/eaos-core/security/gatekeeper.

Signature

interface GatekeeperOptions {
    requireDurableAudit?: boolean;
}

Parameters

Name	Type	Required	Description
`requireDurableAudit`	`boolean`	No	Reject the legacy synchronous API when durable audit delivery is required.

Returns

Type declaration; no runtime value.

Public members

`requireDurableAudit`

Reject the legacy synchronous API when durable audit delivery is required.

Example

See the owning declaration and linked feature guide for usage; no standalone example is documented in source.

[INTERFACE] `GatekeeperPolicy`

Role, risk and human-review requirements for one registered tool.

Imports: @alneas/eaos-core, @alneas/eaos-core/plugin-sdk, @alneas/eaos-core/plugin-sdk/types.

Signature

interface GatekeeperPolicy {
    requiredRole?: string | string[];
    riskLevel?: RiskLevel;
    requireHumanApproval?: boolean;
}

Parameters

Name	Type	Required	Description
`requiredRole`	`string \| string[]`	No	Optional single role or alternatives; matching admin/SUPER_ADMIN roles bypass the named role requirement.
`riskLevel`	`RiskLevel`	No	Declared operation risk used to determine review requirements; it does not itself grant authorization.
`requireHumanApproval`	`boolean`	No	Whether execution must wait for an explicit host approval workflow.

Returns

Type declaration; no runtime value.

Public members

`requiredRole`

Optional single role or alternatives; matching admin/SUPER_ADMIN roles bypass the named role requirement.

`riskLevel`

Declared operation risk used to determine review requirements; it does not itself grant authorization.

`requireHumanApproval`

Whether execution must wait for an explicit host approval workflow.

Example

See the owning declaration and linked feature guide for usage; no standalone example is documented in source.

[FUNCTION] `generateSecret`

Generate random hexadecimal secret text of a requested length.

Imports: @alneas/eaos-core, @alneas/eaos-core/webhook, @alneas/eaos-core/webhook/delivery.

Signature

declare function generateSecret(length?: number): string;

Parameters

Name	Type	Required	Description
`length`	`number`	No	Number of random bytes requested and maximum hexadecimal character count returned; defaults to 32. Only the first length hexadecimal characters are retained.

Returns

string

Random hexadecimal text truncated to length characters.

Remarks

Requires node:crypto; generated secrets must be stored and transmitted by the host.

Errors and rejections

Native crypto errors for an invalid random byte count.

Example

import { generateSecret } from "@alneas/eaos-core/webhook/delivery";
const secret = generateSecret();
console.log(secret.length); // 32

[FUNCTION] `generateSignature`

Sign a timestamp and exact webhook body with HMAC-SHA256.

Imports: @alneas/eaos-core, @alneas/eaos-core/webhook, @alneas/eaos-core/webhook/delivery.

Signature

declare function generateSignature(timestamp: string, body: string, secret: string): string;

Parameters

Name	Type	Required	Description
`timestamp`	`string`	Yes	Timestamp text, conventionally Unix epoch milliseconds; signed verbatim without validation.
`body`	`string`	Yes	Exact serialized body; whitespace changes alter the signature.
`secret`	`string`	Yes	Shared HMAC secret.

Returns

string

Lowercase hexadecimal signature over timestamp + dot + body.

Remarks

Requires node:crypto. Receivers must independently enforce timestamp freshness and replay protection.

Example

import { generateSignature } from "@alneas/eaos-core/webhook/delivery";
console.log(generateSignature("1792368000000", "{}", "example-only-secret"));

[FUNCTION] `getPlatformNamespaceDocumentContracts`

Select public payload document contracts for one platform namespace.

Imports: @alneas/eaos-core/contracts/platform-records.

Signature

declare function getPlatformNamespaceDocumentContracts(contractId: string, namespace: string): JsonDocumentContract[];

Parameters

Name	Type	Required	Description
`contractId`	`string`	Yes	Must equal platformRecordsContract.id.
`namespace`	`string`	Yes	Exact namespace used to filter payload-column documents.

Returns

JsonDocumentContract[]

A detached array of matching logical document contracts.

Errors and rejections

Error for an unknown public contract or a namespace without payload document contracts.

Example

import { getPlatformNamespaceDocumentContracts } from "@alneas/eaos-core/contracts/platform-records";
import { platformRecordsContract } from "@alneas/eaos-core/contracts/platform-records";
const namespace = platformRecordsContract.jsonDocuments?.find(document => document.column === "payload")?.namespace;
if (!namespace) throw new Error("No payload namespace in this contract");
console.log(getPlatformNamespaceDocumentContracts(platformRecordsContract.id, namespace));

[FUNCTION] `getPlatformRecordsContract`

Clone the recursively frozen public platform record contract.

Imports: @alneas/eaos-core/contracts/platform-records.

Signature

declare const getPlatformRecordsContract: () => DataContract;

Parameters

Name	Type	Required	Description
—	—	—	No call parameters.

Returns

DataContract

A mutable detached DataContract copy suitable for host catalog composition.

Example

import { getPlatformRecordsContract } from "@alneas/eaos-core/contracts/platform-records";
console.log(getPlatformRecordsContract().id);

[CONSTANT] `globalAiCircuitBreaker`

Module-local circuit breaker using the built-in provider priority order.

Imports: @alneas/eaos-core/agent/circuit-breaker.

Signature

declare const globalAiCircuitBreaker: AiCircuitBreaker;

Parameters

Name	Type	Required	Description
—	—	—	No call parameters.

Returns

Declared constant value.

Example

See the owning declaration and linked feature guide for usage; no standalone example is documented in source.

[CONSTANT] `globalExecutionSandbox`

Module-local sandbox/desktop bridge helper; construction does not create isolation resources.

Imports: @alneas/eaos-core, @alneas/eaos-core/agentic, @alneas/eaos-core/agentic/execution-sandbox.

Signature

declare const globalExecutionSandbox: ExecutionSandbox;

Parameters

Name	Type	Required	Description
—	—	—	No call parameters.

Returns

Declared constant value.

Example

See the owning declaration and linked feature guide for usage; no standalone example is documented in source.

[CONSTANT] `globalGatekeeper`

Module-local gatekeeper singleton shared by imports in the same runtime.

Imports: @alneas/eaos-core, @alneas/eaos-core/security/gatekeeper.

Signature

declare const globalGatekeeper: McpGatekeeper;

Parameters

Name	Type	Required	Description
—	—	—	No call parameters.

Returns

Declared constant value.

Example

See the owning declaration and linked feature guide for usage; no standalone example is documented in source.

[CONSTANT] `globalInstinctEngine`

Module-local in-memory instinct engine without a configured vector provider.

Imports: @alneas/eaos-core, @alneas/eaos-core/agentic, @alneas/eaos-core/agentic/instinct-engine.

Signature

declare const globalInstinctEngine: InstinctEngine;

Parameters

Name	Type	Required	Description
—	—	—	No call parameters.

Returns

Declared constant value.

Example

See the owning declaration and linked feature guide for usage; no standalone example is documented in source.

[CONSTANT] `globalMcpCacheManager`

Module-local shared cache/quota tracker with no persistence or eviction timer.

Imports: @alneas/eaos-core/agent/cache-manager.

Signature

declare const globalMcpCacheManager: McpCacheManager;

Parameters

Name	Type	Required	Description
—	—	—	No call parameters.

Returns

Declared constant value.

Example

See the owning declaration and linked feature guide for usage; no standalone example is documented in source.

[CONSTANT] `globalModelRoutingGateway`

Module-local instance of the fixed-catalog heuristic routing helper.

Imports: @alneas/eaos-core, @alneas/eaos-core/agentic, @alneas/eaos-core/agentic/model-routing-gateway.

Signature

declare const globalModelRoutingGateway: ModelRoutingGateway;

Parameters

Name	Type	Required	Description
—	—	—	No call parameters.

Returns

Declared constant value.

Example

See the owning declaration and linked feature guide for usage; no standalone example is documented in source.

[INTERFACE] `GoExtensionConfig`

Build metadata for a host-managed Go handler extension.

Imports: @alneas/eaos-core, @alneas/eaos-core/plugin-sdk, @alneas/eaos-core/plugin-sdk/types.

Signature

interface GoExtensionConfig {
    handlers: string[];
    dockerfile: string;
}

Parameters

Name	Type	Required	Description
`handlers`	`string[]`	Yes	Topic-keyed callbacks or Go handler names; outbox callbacks resolve without a value after effect completion and must tolerate replay.
`dockerfile`	`string`	Yes	Host build path for the Go extension container definition.

Returns

Type declaration; no runtime value.

Public members

`handlers`

Topic-keyed callbacks or Go handler names; outbox callbacks resolve without a value after effect completion and must tolerate replay.

`dockerfile`

Host build path for the Go extension container definition.

Example

See the owning declaration and linked feature guide for usage; no standalone example is documented in source.

[INTERFACE] `GoogleOidcConfig`

Google OIDC provider identity, scopes and mapping; credentials remain runtime bindings.

Imports: @alneas/eaos-core/platform/config.

Signature

interface GoogleOidcConfig {
    id?: string;
    scopes?: string[];
    mapper?: GoogleOidcMapper;
}

Parameters

Name	Type	Required	Description
`id`	`string`	No	Preserve existing IDs: they identify provider credentials and callback routes.
`scopes`	`string[]`	No	Exact API permission scope names associated with the verified identity/key.
`mapper`	`GoogleOidcMapper`	No	Google claim mapping; defaults to google-verified-email-v1, which requires an email scope.

Returns

Type declaration; no runtime value.

Public members

`id`

Preserve existing IDs: they identify provider credentials and callback routes.

`scopes`

Exact API permission scope names associated with the verified identity/key.

`mapper`

Google claim mapping; defaults to google-verified-email-v1, which requires an email scope.

Example

See the owning declaration and linked feature guide for usage; no standalone example is documented in source.

[TYPE] `GoogleOidcMapper`

Built-in verified-email mapper selection or host-owned Jsonnet mapper path.

Imports: @alneas/eaos-core/platform/config.

Signature

type GoogleOidcMapper = 'google-verified-email-v1' | {
    path: string;
};

Parameters

Name	Type	Required	Description
—	—	—	No call parameters.

Returns

Type declaration; no runtime value.

Public members

`path`

Project-relative .jsonnet mapper path without traversal; the host loads the mapper.

Example

See the owning declaration and linked feature guide for usage; no standalone example is documented in source.

[INTERFACE] `GraphProjectionAdapter`

Host-owned projection update/rebuild and optional cursor port.

Imports: @alneas/eaos-core, @alneas/eaos-core/workflow-runtime.

Signature

interface GraphProjectionAdapter {
    apply(event: WorkflowEventEnvelope): Promise<void>;
    rebuild(input: {
        tenantId: string;
        sourceRevision: number;
        snapshot: unknown;
    }): Promise<void>;
    getCursor?(tenantId: string): Promise<GraphProjectionCursor | null>;
}

Parameters

Name	Type	Required	Description
`apply`	`Promise<void>`	Yes	Apply one workflow event to a host graph projection.
`rebuild`	`Promise<void>`	Yes	Rebuild a tenant projection from a host source snapshot.
`getCursor`	`Promise<GraphProjectionCursor \| null>`	No	Read optional host projector progress for a tenant.

Returns

Type declaration; no runtime value.

Public members

`apply`

Apply one workflow event to a host graph projection.

Parameters:

event: Tenant-scoped source event; host should deduplicate its identity/revision as appropriate.

Returns: No value; host projection apply has completed.

Remarks

Host owns isolation, durable cursor updates, ordering and idempotency. Core supplies no projector transaction.

Errors and rejections

Host projection failures reject; partial updates depend on host atomicity.

Example:

import type { GraphProjectionAdapter } from "@alneas/eaos-core/workflow-runtime";
async function applyHostEvent(adapter: GraphProjectionAdapter, event: Parameters<GraphProjectionAdapter["apply"]>[0]) { await adapter.apply(event); }

`rebuild`

Rebuild a tenant projection from a host source snapshot.

Parameters:

input: Verified tenant, source revision and complete snapshot interpreted by the host.

Returns: No value; host rebuild has completed.

Remarks

Host defines atomic replacement, concurrent event handling, resource limits and recovery; this method can replace persisted read-model data.

Errors and rejections

Host rebuild failures reject and may leave a partial/old projection depending on host atomicity.

Example:

import type { GraphProjectionAdapter } from "@alneas/eaos-core/workflow-runtime";
async function rebuildHost(adapter: GraphProjectionAdapter, snapshot: unknown) { await adapter.rebuild({ tenantId: "tenant-demo", sourceRevision: 1, snapshot }); }

`rebuild.input.tenantId`

Verified tenant boundary for the record or operation; host authorization must establish this scope.

`rebuild.input.sourceRevision`

Optional nonnegative safe-integer source revision represented by the graph result.

`rebuild.input.snapshot`

Host-provided source snapshot used for projection rebuild; the adapter owns atomic replacement and isolation.

`getCursor`

Read optional host projector progress for a tenant.

Parameters:

tenantId: Verified tenant whose cursor is requested.

Returns: Cursor or null when no progress is available.

Remarks

Optional capability; absent lookup does not establish projector health.

Errors and rejections

Host cursor-read failures reject.

Example:

import type { GraphProjectionAdapter } from "@alneas/eaos-core/workflow-runtime";
async function inspectCursor(adapter: GraphProjectionAdapter) {
 if (!adapter.getCursor) throw new Error("Host cursor lookup is unavailable");
 return adapter.getCursor("tenant-demo");
}

Example

See the owning declaration and linked feature guide for usage; no standalone example is documented in source.

[INTERFACE] `GraphProjectionCursor`

Per-tenant graph projector progress, lag and failure state.

Imports: @alneas/eaos-core, @alneas/eaos-core/workflow-runtime.

Signature

interface GraphProjectionCursor {
    projectionId: string;
    tenantId: string;
    status: 'healthy' | 'lagging' | 'failed' | 'rebuilding';
    lastEventId?: string;
    lastAggregateType?: string;
    lastAggregateId?: string;
    lastAggregateRevision?: number;
    lagCount: number;
    updatedAt: string;
    lastError?: string;
}

Parameters

Name	Type	Required	Description
`projectionId`	`string`	Yes	Host graph read-model/projector identity.
`tenantId`	`string`	Yes	Verified tenant boundary for the record or operation; host authorization must establish this scope.
`status`	`'healthy' \| 'lagging' \| 'failed' \| 'rebuilding'`	Yes	Host projector health/rebuild state.
`lastEventId`	`string`	No	Most recent source event applied by the projector, when known.
`lastAggregateType`	`string`	No	Aggregate category associated with the recorded projector cursor.
`lastAggregateId`	`string`	No	Aggregate identity associated with the recorded projector cursor.
`lastAggregateRevision`	`number`	No	Aggregate revision associated with the recorded projector cursor.
`lagCount`	`number`	Yes	Host-reported count of pending source events behind the read model.
`updatedAt`	`string`	Yes	Timestamp of the latest host-recorded update; this contract does not persist changes.
`lastError`	`string`	No	Most recent host-recorded failure detail, when available.

Returns

Type declaration; no runtime value.

Public members

`projectionId`

Host graph read-model/projector identity.

`tenantId`

Verified tenant boundary for the record or operation; host authorization must establish this scope.

`status`

Host projector health/rebuild state.

`lastEventId`

Most recent source event applied by the projector, when known.

`lastAggregateType`

Aggregate category associated with the recorded projector cursor.

`lastAggregateId`

Aggregate identity associated with the recorded projector cursor.

`lastAggregateRevision`

Aggregate revision associated with the recorded projector cursor.

`lagCount`

Host-reported count of pending source events behind the read model.

`updatedAt`

Timestamp of the latest host-recorded update; this contract does not persist changes.

`lastError`

Most recent host-recorded failure detail, when available.

Example

See the owning declaration and linked feature guide for usage; no standalone example is documented in source.

[INTERFACE] `GraphProjectionEdge`

A tenant-scoped graph edge exposed by a host read model.

Imports: @alneas/eaos-core, @alneas/eaos-core/workflow-runtime.

Signature

interface GraphProjectionEdge {
    id?: string;
    tenantId: string;
    sourceId: string;
    targetId: string;
    type: string;
    properties?: Readonly<Record<string, unknown>>;
}

Parameters

Name	Type	Required	Description
`id`	`string`	No	Optional provider relationship identity; validation checks endpoints but does not require this field.
`tenantId`	`string`	Yes	Verified tenant boundary for the record or operation; host authorization must establish this scope.
`sourceId`	`string`	Yes	Stable retrieval source identity used to trace returned evidence.
`targetId`	`string`	Yes	Domain target record identity or graph edge destination; host validation enforces scope.
`type`	`string`	Yes	Provider-neutral directed relationship category.
`properties`	`Readonly<Record<string, unknown>>`	No	Optional graph element metadata or table-schema properties; the host validates sensitive/domain fields.

Returns

Type declaration; no runtime value.

Public members

`id`

Optional provider relationship identity; validation checks endpoints but does not require this field.

`tenantId`

Verified tenant boundary for the record or operation; host authorization must establish this scope.

`sourceId`

Stable retrieval source identity used to trace returned evidence.

`targetId`

Domain target record identity or graph edge destination; host validation enforces scope.

`type`

Provider-neutral directed relationship category.

`properties`

Optional graph element metadata or table-schema properties; the host validates sensitive/domain fields.

Example

See the owning declaration and linked feature guide for usage; no standalone example is documented in source.

[INTERFACE] `GraphProjectionNode`

A tenant-scoped graph vertex exposed by a host read model.

Imports: @alneas/eaos-core, @alneas/eaos-core/workflow-runtime.

Signature

interface GraphProjectionNode {
    id: string;
    tenantId: string;
    type: string;
    properties?: Readonly<Record<string, unknown>>;
}

Parameters

Name	Type	Required	Description
`id`	`string`	Yes	Unique node identity within a tenant projection result, up to 256 nonblank characters.
`tenantId`	`string`	Yes	Verified tenant boundary for the record or operation; host authorization must establish this scope.
`type`	`string`	Yes	Provider-neutral domain node category.
`properties`	`Readonly<Record<string, unknown>>`	No	Optional graph element metadata or table-schema properties; the host validates sensitive/domain fields.

Returns

Type declaration; no runtime value.

Public members

`id`

Unique node identity within a tenant projection result, up to 256 nonblank characters.

`tenantId`

Verified tenant boundary for the record or operation; host authorization must establish this scope.

`type`

Provider-neutral domain node category.

`properties`

Optional graph element metadata or table-schema properties; the host validates sensitive/domain fields.

Example

See the owning declaration and linked feature guide for usage; no standalone example is documented in source.

[INTERFACE] `GraphProjectionQuery`

Tenant-scoped graph traversal request with optional seed/type/size limits.

Imports: @alneas/eaos-core, @alneas/eaos-core/workflow-runtime.

Signature

interface GraphProjectionQuery {
    tenantId: string;
    startNodeIds?: readonly string[];
    edgeTypes?: readonly string[];
    maxHops?: number;
    maxNodes?: number;
    maxEdges?: number;
}

Parameters

Name	Type	Required	Description
`tenantId`	`string`	Yes	Verified tenant boundary for the record or operation; host authorization must establish this scope.
`startNodeIds`	`readonly string[]`	No	Optional seed node IDs for graph traversal; omission is adapter-defined.
`edgeTypes`	`readonly string[]`	No	Optional relationship-type filter for graph traversal.
`maxHops`	`number`	No	Optional traversal depth bound enforced by the graph provider.
`maxNodes`	`number`	No	Optional returned-node bound enforced by the graph provider.
`maxEdges`	`number`	No	Optional returned-edge bound enforced by the graph provider.

Returns

Type declaration; no runtime value.

Public members

`tenantId`

Verified tenant boundary for the record or operation; host authorization must establish this scope.

`startNodeIds`

Optional seed node IDs for graph traversal; omission is adapter-defined.

`edgeTypes`

Optional relationship-type filter for graph traversal.

`maxHops`

Optional traversal depth bound enforced by the graph provider.

`maxNodes`

Optional returned-node bound enforced by the graph provider.

`maxEdges`

Optional returned-edge bound enforced by the graph provider.

Example

See the owning declaration and linked feature guide for usage; no standalone example is documented in source.

[INTERFACE] `GraphProjectionQueryResult`

Tenant-scoped graph read model with projection time and staleness metadata.

Imports: @alneas/eaos-core, @alneas/eaos-core/workflow-runtime.

Signature

interface GraphProjectionQueryResult {
    tenantId: string;
    nodes: readonly GraphProjectionNode[];
    edges: readonly GraphProjectionEdge[];
    sourceRevision?: number;
    projectedAt: string;
    stale: boolean;
}

Parameters

Name	Type	Required	Description
`tenantId`	`string`	Yes	Verified tenant boundary for the record or operation; host authorization must establish this scope.
`nodes`	`readonly GraphProjectionNode[]`	Yes	Graph vertices in supplied order; this metadata does not execute node handlers.
`edges`	`readonly GraphProjectionEdge[]`	Yes	Directed graph relationships in supplied order; validation/rendering behavior follows the owning graph contract.
`sourceRevision`	`number`	No	Optional nonnegative safe-integer source revision represented by the graph result.
`projectedAt`	`string`	Yes	Parseable timestamp associated with the graph read-model snapshot.
`stale`	`boolean`	Yes	Whether the host reports the projection as behind its source state.

Returns

Type declaration; no runtime value.

Public members

`tenantId`

Verified tenant boundary for the record or operation; host authorization must establish this scope.

`nodes`

Graph vertices in supplied order; this metadata does not execute node handlers.

`edges`

Directed graph relationships in supplied order; validation/rendering behavior follows the owning graph contract.

`sourceRevision`

Optional nonnegative safe-integer source revision represented by the graph result.

`projectedAt`

Parseable timestamp associated with the graph read-model snapshot.

`stale`

Whether the host reports the projection as behind its source state.

Example

See the owning declaration and linked feature guide for usage; no standalone example is documented in source.

[INTERFACE] `GraphQueryAdapter`

Provider-neutral graph reads. Oracle Graph/PGQL, SQL recursive queries and Neo4j are host implementations.

Imports: @alneas/eaos-core, @alneas/eaos-core/workflow-runtime.

Signature

interface GraphQueryAdapter {
    query(input: GraphProjectionQuery): Promise<GraphProjectionQueryResult>;
}

Parameters

Name	Type	Required	Description
`query`	`Promise<GraphProjectionQueryResult>`	Yes	Read a tenant-scoped graph projection through a host provider.

Returns

Type declaration; no runtime value.

Public members

`query`

Read a tenant-scoped graph projection through a host provider.

Parameters:

input: Verified tenant plus optional seed IDs, relationship filters and traversal/result bounds.

Returns: Graph read model with staleness/projection metadata; nodes/edges may be empty.

Remarks

Host owns authorization, query limits, result freshness and cancellation; validate with assertGraphProjectionResult.

Errors and rejections

Host graph query failures reject the Promise.

Example:

import type { GraphQueryAdapter } from "@alneas/eaos-core/workflow-runtime";
async function queryHost(adapter: GraphQueryAdapter) { return adapter.query({ tenantId: "tenant-demo", maxNodes: 100 }); }

Example

See the owning declaration and linked feature guide for usage; no standalone example is documented in source.

[FUNCTION] `hasActiveConsent`

Find a matching consent that has started, remains unrevoked and has not expired.

Imports: @alneas/eaos-core, @alneas/eaos-core/security/platform-security.

Signature

declare function hasActiveConsent(records: readonly ConsentRecord[], requirement: {
    tenantId: string;
    userId: string;
    purpose: string;
    version?: string;
    now?: Date;
}): boolean;

Parameters

Name	Type	Required	Description
`records`	`readonly ConsentRecord[]`	Yes	Host-supplied consent records; any qualifying match is sufficient.
`requirement`	`{ tenantId: string; userId: string; purpose: string; version?: string; now?: Date; }`	Yes	Exact tenant/user/purpose and optional version; omitted now uses current Date and absent/falsy version accepts any version.

Returns

boolean

Whether at least one active record matches.

Remarks

Does not persist consent or establish that records came from a trusted source.

Public members

`requirement.tenantId`

Exact trusted tenant identity to match against consent records.

`requirement.userId`

Exact authenticated user identity whose grant must match within the tenant.

`requirement.purpose`

Exact consent purpose identifier; a grant for another purpose does not satisfy this requirement.

`requirement.version`

Optional exact consent revision; omission or an empty string accepts any recorded version.

`requirement.now`

Optional evaluation clock for grant-start/expiry checks; omission uses current Date. A matching record must be granted at or before this instant and unrevoked/unexpired.

Example

import { hasActiveConsent } from "@alneas/eaos-core/security/platform-security";
const records = [{ tenantId: "tenant-demo", userId: "user-demo", purpose: "summarization", version: "1", grantedAt: "2026-01-01T00:00:00Z" }];
const requirement = { tenantId: "tenant-demo", userId: "user-demo", purpose: "summarization", version: "1", now: new Date("2026-10-19T00:00:00Z") };
console.log(hasActiveConsent(records, requirement)); // true

[FUNCTION] `hashAgentJobRequest`

Hash a strict JSON agent request for stable job identity.

Imports: @alneas/eaos-core, @alneas/eaos-core/workflow-runtime.

Signature

declare function hashAgentJobRequest(request: unknown): string;

Parameters

Name	Type	Required	Description
`request`	`unknown`	Yes	Acyclic, finite JSON data accepted by canonicalJson.

Returns

string

A lowercase SHA-256 hexadecimal hash.

Remarks

Requires node:crypto and performs no persistence.

Errors and rejections

Error for unsupported JSON values or cycles.

Example

import { hashAgentJobRequest } from "@alneas/eaos-core/workflow-runtime";
console.log(hashAgentJobRequest({ task: "summarize", documentId: "doc-1" }));

[INTERFACE] `HealthCheck`

Read-only host probe with an identifier, criticality and optional deadline.

Imports: @alneas/eaos-core, @alneas/eaos-core/health.

Signature

interface HealthCheck {
    id: string;
    critical?: boolean;
    timeoutMs?: number;
    run: () => boolean | Promise<boolean>;
}

Parameters

Name	Type	Required	Description
`id`	`string`	Yes	Unique lowercase probe identity, at most 128 characters, used for result correlation.
`critical`	`boolean`	No	Whether failure makes readiness not_ready; defaults to true. False failures only degrade readiness.
`timeoutMs`	`number`	No	Optional execution deadline in milliseconds; enforcement belongs to the API/runtime consuming this metadata.
`run`	`() => boolean \| Promise<boolean>`	Yes	Run a read-only host readiness probe when aggregation starts.

Returns

Type declaration; no runtime value.

Public members

`id`

Unique lowercase probe identity, at most 128 characters, used for result correlation.

`critical`

Whether failure makes readiness not_ready; defaults to true. False failures only degrade readiness.

`timeoutMs`

Optional execution deadline in milliseconds; enforcement belongs to the API/runtime consuming this metadata.

`run`

Run a read-only host readiness probe when aggregation starts.

Returns: True only when the checked condition is healthy, directly or asynchronously; false/throws/rejections become failed probe results.

Remarks

Called concurrently with other probes. Timeout stops waiting without cancelling this callback; the host owns resource cleanup.

Example:

import type { HealthCheck } from "@alneas/eaos-core/health";
const configuration = { initialized: true };
const check: HealthCheck = { id: "configuration", run: () => configuration.initialized };
console.log(await check.run());

Example

See the owning declaration and linked feature guide for usage; no standalone example is documented in source.

[INTERFACE] `HealthCheckResult`

Probe identity, criticality, outcome and elapsed duration.

Imports: @alneas/eaos-core, @alneas/eaos-core/health.

Signature

interface HealthCheckResult {
    id: string;
    critical: boolean;
    state: HealthCheckState;
    durationMs: number;
}

Parameters

Name	Type	Required	Description
`id`	`string`	Yes	Identity copied from the probe that produced this result.
`critical`	`boolean`	Yes	Resolved criticality copied from the check, true unless it explicitly declared false.
`state`	`HealthCheckState`	Yes	ok only when the probe resolves exactly true; failed or timed_out otherwise.
`durationMs`	`number`	Yes	Measured elapsed duration in milliseconds.

Returns

Type declaration; no runtime value.

Public members

`id`

Identity copied from the probe that produced this result.

`critical`

Resolved criticality copied from the check, true unless it explicitly declared false.

`state`

ok only when the probe resolves exactly true; failed or timed_out otherwise.

`durationMs`

Measured elapsed duration in milliseconds.

Example

See the owning declaration and linked feature guide for usage; no standalone example is documented in source.

[TYPE] `HealthCheckState`

Per-probe success, failure or timeout result without exposed adapter error details.

Imports: @alneas/eaos-core, @alneas/eaos-core/health.

Signature

type HealthCheckState = 'ok' | 'failed' | 'timed_out';

Parameters

Name	Type	Required	Description
—	—	—	No call parameters.

Returns

Type declaration; no runtime value.

Example

See the owning declaration and linked feature guide for usage; no standalone example is documented in source.

[INTERFACE] `HelpContextItem`

Contextual help text and optional navigation/search metadata.

Imports: @alneas/eaos-core, @alneas/eaos-core/plugin-sdk, @alneas/eaos-core/plugin-sdk/types.

Signature

interface HelpContextItem {
    title: string;
    summary: string;
    docAnchor?: string;
    guidePath?: string;
    tags?: string[];
}

Parameters

Name	Type	Required	Description
`title`	`string`	Yes	Human-readable draft, task, file or event title displayed by the host.
`summary`	`string`	Yes	Human-readable review/result description suitable for host presentation.
`docAnchor`	`string`	No	Optional anchor within the associated documentation page.
`guidePath`	`string`	No	Optional documentation path used for contextual help navigation.
`tags`	`string[]`	No	Optional discovery/search labels carried as metadata.

Returns

Type declaration; no runtime value.

Public members

`title`

Human-readable draft, task, file or event title displayed by the host.

`summary`

Human-readable review/result description suitable for host presentation.

`docAnchor`

Optional anchor within the associated documentation page.

`guidePath`

Optional documentation path used for contextual help navigation.

`tags`

Optional discovery/search labels carried as metadata.

Example

See the owning declaration and linked feature guide for usage; no standalone example is documented in source.

[TYPE] `HookType`

Lifecycle hook names recognized by the agent runtime.

Imports: @alneas/eaos-core, @alneas/eaos-core/agentic, @alneas/eaos-core/agentic/runtime.

Signature

type HookType = 'PreToolUse' | 'PostToolUse' | 'SessionStart' | 'Stop';

Parameters

Name	Type	Required	Description
—	—	—	No call parameters.

Returns

Type declaration; no runtime value.

Example

See the owning declaration and linked feature guide for usage; no standalone example is documented in source.

[INTERFACE] `IdentitySchemaFile`

Host-owned project-relative JSON identity schema and its stable ID.

Imports: @alneas/eaos-core/platform/config.

Signature

interface IdentitySchemaFile {
    id: string;
    path: string;
}

Parameters

Name	Type	Required	Description
`id`	`string`	Yes	Stable identity schema ID referenced by the configured default schema.
`path`	`string`	Yes	Project-relative .json file path without traversal; the host reads it during rendering/bootstrap.

Returns

Type declaration; no runtime value.

Public members

`id`

Stable identity schema ID referenced by the configured default schema.

`path`

Project-relative .json file path without traversal; the host reads it during rendering/bootstrap.

Example

See the owning declaration and linked feature guide for usage; no standalone example is documented in source.

[INTERFACE] `IngressHostRoute`

Exact DNS route mapped to a managed or host-owned HTTP upstream.

Imports: @alneas/eaos-core/platform/config.

Signature

interface IngressHostRoute {
    host: string;
    target: 'backend' | 'frontend' | {
        host: string;
        port: number;
        resolution?: 'docker' | 'system';
    };
    proxy?: {
        readTimeoutSeconds?: number;
        sendTimeoutSeconds?: number;
        buffering?: boolean;
    };
}

Parameters

Name	Type	Required	Description
`host`	`string`	Yes	Exact public DNS name; inherits the app scheme and listener port.
`target`	`'backend' \| 'frontend' \| { host: string; port: number; resolution?: 'docker' \| 'system'; }`	Yes	Managed services follow their resolved name/port; custom HTTP services stay host-owned.
`proxy`	`{ readTimeoutSeconds?: number; sendTimeoutSeconds?: number; buffering?: boolean; }`	No	Per-route ingress settings; default read/send timeouts are 180 seconds and buffering is false.

Returns

Type declaration; no runtime value.

Public members

`host`

Exact public DNS name; inherits the app scheme and listener port.

`target`

Managed services follow their resolved name/port; custom HTTP services stay host-owned.

`target.host`

Exact DNS route or HTTP upstream name; managed route hosts must remain under baseDomain.

`target.port`

Required integer TCP port from 1 to 65535 for the host-owned custom HTTP upstream.

`target.resolution`

Upstream hostname resolution strategy, docker by default for resolved host routes.

`proxy`

Per-route ingress settings; default read/send timeouts are 180 seconds and buffering is false.

`proxy.readTimeoutSeconds`

Ingress upstream read timeout in seconds; defaults to 180.

`proxy.sendTimeoutSeconds`

Ingress upstream send timeout in seconds; defaults to 180.

`proxy.buffering`

Ingress proxy buffering selection; defaults to false.

Example

See the owning declaration and linked feature guide for usage; no standalone example is documented in source.

[CLASS] `InstinctEngine`

Keep session-derived heuristics locally and optionally read a host vector index.

Imports: @alneas/eaos-core, @alneas/eaos-core/agentic, @alneas/eaos-core/agentic/instinct-engine.

Signature

declare class InstinctEngine {
    constructor(vectorAdapter?: VectorSearchAdapter | undefined);
    extractInstinctsFromSession(params: {
        tenantId: string;
        domain: string;
        history: Array<{
            role: string;
            content: string;
        }>;
        success: boolean;
        extractFn?: (history: Array<{
            role: string;
            content: string;
        }>) => Promise<{
            pattern: string;
            heuristic: string;
            confidence: number;
        }>;
    }): Promise<AgentInstinct | null>;
    findRelevantInstincts(options: {
        tenantId: string;
        domain: string;
        queryVector?: number[];
        topK?: number;
    }): Promise<AgentInstinct[]>;
}

Parameters

Name	Type	Required	Description
`vectorAdapter`	`VectorSearchAdapter \| undefined`	No	Trusted host search adapter; omitted means local lookup only.

Returns

InstinctEngine

Remarks

Extraction stores only process-local references and does not embed or index them. Vector search results are mapped from host metadata without an additional tenant-result validator; the adapter must enforce tenant scope. Search failures log a warning and fall back to local filtering.

Constructor contract

Public members

`extractInstinctsFromSession`

Extract or synthesize one heuristic from a successful multi-turn session.

Parameters:

params: Tenant/domain and history; returns null for unsuccessful sessions or fewer than two turns. Optional extractFn receives history and resolves pattern/heuristic/confidence; failures log a warning and use built-in defaults.

Returns: A newly stored local instinct reference, or null. Default confidence is 0.85 with one success and zero failures.

Remarks

No embedding/index write, output validation or durable persistence occurs. The caller must handle sensitive trajectory content and validate extractor output.

Example:

import { InstinctEngine } from "@alneas/eaos-core/agentic/instinct-engine";
const engine = new InstinctEngine();
console.log(await engine.extractInstinctsFromSession({ tenantId: "tenant-demo", domain: "notes", success: true, history: [{ role: "user", content: "Preview notes" }, { role: "assistant", content: "No changes" }] }));

`extractInstinctsFromSession.params.tenantId`

Verified tenant boundary for the record or operation; host authorization must establish this scope.

`extractInstinctsFromSession.params.domain`

Classification key copied to the extracted local heuristic.

`extractInstinctsFromSession.params.history`

Session turns supplied for lifecycle/extraction; sensitive content handling remains host-owned.

`extractInstinctsFromSession.params.history[].role`

Host conversation-speaker label associated with this history turn.

`extractInstinctsFromSession.params.history[].content`

Loaded skill instructions, model response text or proposed file content; treat external text as untrusted input.

`extractInstinctsFromSession.params.success`

Reported completion flag; inspect status/receipt and reconcile any uncertain side effects before retrying.

`extractInstinctsFromSession.params.extractFn`

Extract a proposed heuristic from successful session history.

Parameters:

history: Original session turns passed by reference after success and minimum-length checks.

Returns: Proposed pattern, heuristic and confidence; the engine uses them without domain/range validation.

Remarks

Host owns provider access and sensitive-history handling; this callback does not write a vector index.

Errors and rejections

Callback rejections are caught/logged by extraction, which retains its default heuristic.

Remarks

Provider errors are logged and fall back locally. The adapter is trusted for result tenant scope and score/metadata validity; no cancellation/retry is supplied.

Example:

import { InstinctEngine } from "@alneas/eaos-core/agentic/instinct-engine";
const engine = new InstinctEngine();
console.log(await engine.findRelevantInstincts({ tenantId: "tenant-demo", domain: "notes", topK: 5 }));

`findRelevantInstincts.options.tenantId`

Verified tenant boundary for the record or operation; host authorization must establish this scope.

`findRelevantInstincts.options.domain`

Exact domain filter for local fallback; vector search does not send this as a filter.

`findRelevantInstincts.options.queryVector`

Nonempty finite numeric embedding; the host checks its dimension against the selected index.

`findRelevantInstincts.options.topK`

Requested maximum result count; vector request validation permits integers from 1 to 10000.

Example

import { InstinctEngine } from "@alneas/eaos-core/agentic/instinct-engine";
const engine = new InstinctEngine();
console.log(await engine.findRelevantInstincts({ tenantId: "tenant-demo", domain: "notes" })); // []

[FUNCTION] `isAIHostReceiptSuccessful`

Check whether a host receipt reports completion.

Imports: @alneas/eaos-core, @alneas/eaos-core/ai, @alneas/eaos-core/ai/host-adapters.

Signature

declare function isAIHostReceiptSuccessful(receipt: AIHostReceipt): boolean;

Parameters

Name	Type	Required	Description
`receipt`	`AIHostReceipt`	Yes	Host receipt whose status is inspected; identity and side-effect evidence are not validated.

Returns

boolean

True only for completed; accepted is not counted as success.

Example

import { isAIHostReceiptSuccessful } from "@alneas/eaos-core/ai/host-adapters";
console.log(isAIHostReceiptSuccessful({ adapterId: "mail", operation: "draft", receiptId: "r-1", idempotencyKey: "request-1", status: "accepted", acceptedAt: "2026-10-19T00:00:00Z" })); // false

[FUNCTION] `isAIHostReceiptTerminal`

Check whether a receipt has reached a terminal operation status.

Imports: @alneas/eaos-core, @alneas/eaos-core/ai, @alneas/eaos-core/ai/host-adapters.

Signature

declare function isAIHostReceiptTerminal(receipt: AIHostReceipt): boolean;

Parameters

Name	Type	Required	Description
`receipt`	`AIHostReceipt`	Yes	Host receipt whose status is inspected; other fields are not validated.

Returns

boolean

True for completed, failed or unavailable; false for accepted or pending.

Example

import { isAIHostReceiptTerminal } from "@alneas/eaos-core/ai/host-adapters";
console.log(isAIHostReceiptTerminal({ adapterId: "mail", operation: "draft", receiptId: "r-1", idempotencyKey: "request-1", status: "pending", acceptedAt: "2026-10-19T00:00:00Z" })); // false

[FUNCTION] `isApiKeyActive`

Check whether a key is unrevoked and not expired.

Imports: @alneas/eaos-core, @alneas/eaos-core/security/platform-security.

Signature

declare function isApiKeyActive(record: ApiKeyRecord, now?: Date): boolean;

Parameters

Name	Type	Required	Description
`record`	`ApiKeyRecord`	Yes	Stored key lifecycle metadata; this helper does not validate all record fields.
`now`	`Date`	No	Evaluation clock; defaults to current Date.

Returns

boolean

True when revokedAt is falsy and expiry is absent/falsy or a parseable future instant.

Example

import { isApiKeyActive } from "@alneas/eaos-core/security/platform-security";
import { issueApiKey } from "@alneas/eaos-core/security/platform-security";
const issued = issueApiKey({ tenantId: "tenant-demo", userId: "user-demo", scopes: ["notes:read"] });
console.log(isApiKeyActive(issued.record)); // true

[FUNCTION] `isSafeSkillDocumentPath`

Check the restricted relative path shape used for packaged skill documents.

Imports: @alneas/eaos-core, @alneas/eaos-core/ai, @alneas/eaos-core/ai/skills.

Signature

declare function isSafeSkillDocumentPath(path: string): boolean;

Parameters

Name	Type	Required	Description
`path`	`string`	Yes	Candidate path; must begin skills/, end /SKILL.md, and contain neither .. nor backslashes.

Returns

boolean

Whether the path meets the lexical check; no filesystem access occurs.

Remarks

The host loader remains responsible for safe package/filesystem resolution.

Example

import { isSafeSkillDocumentPath } from "@alneas/eaos-core/ai/skills";
console.log(isSafeSkillDocumentPath("skills/review/SKILL.md")); // true

[FUNCTION] `issueApiKey`

Generate a secret once; only the digest is suitable for persistence.

Imports: @alneas/eaos-core, @alneas/eaos-core/security/platform-security.

Signature

declare function issueApiKey(input: {
    tenantId: string;
    userId: string;
    scopes: readonly string[];
    id?: string;
    now?: Date;
    expiresAt?: string | null;
}): IssuedApiKey;

Parameters

Name	Type	Required	Description
`input`	`{ tenantId: string; userId: string; scopes: readonly string[]; id?: string; now?: Date; expiresAt?: string \| null; }`	Yes	Tenant/user IDs and nonempty scopes; optional ID defaults to randomUUID, now to current Date, and expiry must be absent/null or strictly after now.

Returns

IssuedApiKey

The secret and record. Persist only record; return the secret to its owner through a protected channel.

Remarks

Requires node:crypto. Does not persist or authorize key issuance; the host must protect the secret and enforce tenant/key policy.

Errors and rejections

Error for blank identity/scopes or nonfuture expiry; date/crypto failures propagate.

Public members

`input.tenantId`

Nonblank host-verified tenant identity bound to the generated key record; this function does not authorize key issuance.

`input.userId`

Nonblank verified key owner identity copied into the persistence record.

`input.scopes`

Nonempty exact permission-scope names; every entry must be nonblank. Verification later matches a requested scope exactly.

`input.id`

Optional host key-record identity; omission generates a random UUID, without checking external uniqueness.

`input.now`

Optional issuance clock used for createdAt and expiry comparison; omission uses a new current Date.

`input.expiresAt`

Optional parseable absolute expiry strictly after now; null or omission means no expiry is recorded.

Example

import { issueApiKey } from "@alneas/eaos-core/security/platform-security";
const issued = issueApiKey({ tenantId: "tenant-demo", userId: "user-demo", scopes: ["notes:read"] });
console.log(issued.record.prefix);

[INTERFACE] `IssuedApiKey`

One-time secret paired with its hash-only storage record.

Imports: @alneas/eaos-core, @alneas/eaos-core/security/platform-security.

Signature

interface IssuedApiKey {
    secret: string;
    record: ApiKeyRecord;
}

Parameters

Name	Type	Required	Description
`secret`	`string`	Yes	Shared or one-time secret value; keep it out of persistence/logs except through host-approved secret storage.
`record`	`ApiKeyRecord`	Yes	API-key hash-only metadata suitable for host persistence; it excludes the returned one-time secret.

Returns

Type declaration; no runtime value.

Public members

`secret`

Shared or one-time secret value; keep it out of persistence/logs except through host-approved secret storage.

`record`

API-key hash-only metadata suitable for host persistence; it excludes the returned one-time secret.

Example

See the owning declaration and linked feature guide for usage; no standalone example is documented in source.

[INTERFACE] `JsonDocumentContract`

Logical contents, distinct from the physical string/JSONB/CLOB column schema.

Imports: @alneas/eaos-core, @alneas/eaos-core/data-contracts, @alneas/eaos-core/contracts/data-contracts, @alneas/eaos-core/contracts/json-documents.

Signature

interface JsonDocumentContract {
    id: string;
    version: string;
    table: string;
    column: string;
    namespace?: string;
    jsonPath?: string;
    recordPrefix?: string;
    schema: Record<string, unknown>;
    immutable?: boolean;
    maxBytes?: number;
}

Parameters

Name	Type	Required	Description
`id`	`string`	Yes	Unique lowercase dotted/hyphenated logical document identity within selected contracts.
`version`	`string`	Yes	Valid semantic version of the logical JSON document contract.
`table`	`string`	Yes	Physical table name declared by the owning data contract.
`column`	`string`	Yes	Physical JSON-bearing column whose logical contents are constrained by this contract.
`namespace`	`string`	No	Plugin owner of plugin_data.plugins., or record-store namespace.
`jsonPath`	`string`	No	Owned subtree in plugin_data. Runtime partial updates validate this subtree.
`recordPrefix`	`string`	No	Logical record ID prefix; longest matching prefix wins. Empty means all IDs.
`schema`	`Record<string, unknown>`	Yes	JSON Schema defining owned table/document structure; schema declarations do not apply migrations by themselves.
`immutable`	`boolean`	No	Explicitly append-only documents may only be created at revision 1.
`maxBytes`	`number`	No	Optional positive safe-integer UTF-8 canonical JSON limit up to 4194304 bytes; defaults to 4 MiB.

Returns

Type declaration; no runtime value.

Public members

`id`

Unique lowercase dotted/hyphenated logical document identity within selected contracts.

`version`

Valid semantic version of the logical JSON document contract.

`table`

Physical table name declared by the owning data contract.

`column`

Physical JSON-bearing column whose logical contents are constrained by this contract.

`namespace`

Plugin owner of plugin_data.plugins., or record-store namespace.

`jsonPath`

Owned subtree in plugin_data. Runtime partial updates validate this subtree.

`recordPrefix`

Logical record ID prefix; longest matching prefix wins. Empty means all IDs.

`schema`

JSON Schema defining owned table/document structure; schema declarations do not apply migrations by themselves.

`immutable`

Explicitly append-only documents may only be created at revision 1.

`maxBytes`

Optional positive safe-integer UTF-8 canonical JSON limit up to 4194304 bytes; defaults to 4 MiB.

Example

See the owning declaration and linked feature guide for usage; no standalone example is documented in source.

[FUNCTION] `legacyNumberToDecimal`

Explicit adapter for existing numeric feeds, preserving their displayed decimal value.

Imports: @alneas/eaos-core/plugin-sdk, @alneas/eaos-core/plugin-sdk/decimal-values.

Signature

declare function legacyNumberToDecimal(value: number): string;

Parameters

Name	Type	Required	Description
`value`	`number`	Yes	Finite JavaScript number; any precision already lost in the number cannot be recovered.

Returns

string

Decimal text without exponent notation.

Errors and rejections

Error for a nonfinite number or output exceeding decimalValueSchema.

Example

import { legacyNumberToDecimal } from "@alneas/eaos-core/plugin-sdk/decimal-values";
console.log(legacyNumberToDecimal(1e-7)); // 0.0000001

[INTERFACE] `LivenessReport`

Timestamped indication that report creation code is alive.

Imports: @alneas/eaos-core, @alneas/eaos-core/health.

Signature

interface LivenessReport {
    state: 'alive';
    checkedAt: string;
}

Parameters

Name	Type	Required	Description
`state`	`'alive'`	Yes	Always alive when a liveness report is constructed.
`checkedAt`	`string`	Yes	Timestamp associated with the reported evaluation or measurement.

Returns

Type declaration; no runtime value.

Public members

`state`

Always alive when a liveness report is constructed.

`checkedAt`

Timestamp associated with the reported evaluation or measurement.

Example

See the owning declaration and linked feature guide for usage; no standalone example is documented in source.

[FUNCTION] `majorAmountToMinor`

Exact decimal conversion; requires an explicit power-of-ten currency scale.

Imports: @alneas/eaos-core/plugin-sdk, @alneas/eaos-core/plugin-sdk/data-standards.

Signature

declare function majorAmountToMinor(value: number, minorUnitsPerMajorUnit: number): number;

Parameters

Name	Type	Required	Description
`value`	`number`	Yes	Finite major-unit amount; calculation uses its String representation.
`minorUnitsPerMajorUnit`	`number`	Yes	Explicit scale: 1, 10, 100, 1000, 10000, 100000 or 1000000.

Returns

number

The safe integer minor-unit amount.

Errors and rejections

Error for an unsupported scale, nonfinite amount, required rounding or unsafe result.

Example

import { majorAmountToMinor } from "@alneas/eaos-core/plugin-sdk/data-standards";
console.log(majorAmountToMinor(12.5, 100)); // 1250

[CLASS] `McpCacheManager`

Store process-local tool cache entries and manually incremented tenant call counts.

Imports: @alneas/eaos-core/agent/cache-manager.

Signature

declare class McpCacheManager {
    setTenantQuota(tenantId: string, config: QuotaConfig): void;
    checkQuota(tenantId: string): {
        allowed: boolean;
        reason?: string;
    };
    incrementQuota(tenantId: string): void;
    getCache(tenantId: string, toolName: string, args: Record<string, unknown>): unknown | undefined;
    setCache(tenantId: string, toolName: string, args: Record<string, unknown>, data: unknown, ttlSeconds?: number): void;
}

Parameters

Name	Type	Required	Description
—	—	—	No call parameters.

Returns

McpCacheManager

Remarks

No persistence, eviction timer or cross-process coordination. Cache keys use JSON.stringify argument order. Daily counts reset by UTC date; the monthly count is retained across date changes and has no implemented month reset. Quota checks do not increment usage; zero limits are treated as absent.

Public members

`setTenantQuota`

Replace the quota configuration stored for a tenant.

Parameters:

tenantId: Tenant quota lookup key.
config: Daily/monthly call limits stored by reference; omitted or zero limits are not enforced.

Returns: No value; limits have been set.

Example:

import { McpCacheManager } from "@alneas/eaos-core/agent/cache-manager";
const cache = new McpCacheManager();
cache.setTenantQuota("tenant-demo", { maxCallsPerDay: 100 });

`checkQuota`

Check configured call counts without reserving or consuming quota.

Parameters:

tenantId: Tenant quota key; tenants without limits are allowed.

Returns: Allowed or denied with a reason; checking may initialize/reset the UTC daily counter.

Example:

import { McpCacheManager } from "@alneas/eaos-core/agent/cache-manager";
const cache = new McpCacheManager();
console.log(cache.checkQuota("tenant-demo").allowed); // true

`checkQuota.allowed`

Admission/check decision; consumers must inspect it before using the associated result or performing an effect.

`checkQuota.reason`

Human-readable explanation of the decision or requested action.

`incrementQuota`

Increment both call counters for a tenant.

Parameters:

tenantId: Tenant whose usage increases; works even without a configured limit.

Returns: No value; daily/monthly counters have increased.

Remarks

Resets daily count on a new UTC date, retaining monthly count. No atomic admission reservation occurs with checkQuota.

Example:

import { McpCacheManager } from "@alneas/eaos-core/agent/cache-manager";
const cache = new McpCacheManager();
cache.incrementQuota("tenant-demo");

`getCache`

Read a tool result and lazily remove an expired entry.

Parameters:

tenantId: Tenant key.
toolName: Exact tool name.
args: Arguments serialized in insertion order to form the cache key.

Returns: The original cached data reference, or undefined on miss/expiry; cached undefined is indistinguishable from a miss.

Errors and rejections

JSON serialization errors for unsupported argument values, including cycles and bigint.

Example:

import { McpCacheManager } from "@alneas/eaos-core/agent/cache-manager";
const cache = new McpCacheManager();
console.log(cache.getCache("tenant-demo", "notes.list", {}));

`setCache`

Replace a cached tool result with an expiration time.

Parameters:

tenantId: Tenant key.
toolName: Exact tool name.
args: Arguments serialized in insertion order to form the cache key.
data: Result stored by reference.
ttlSeconds: Lifetime in seconds relative to Date.now; defaults to 60 and is not validated.

Returns: No value; the entry has been stored.

Errors and rejections

JSON serialization errors for unsupported argument values, including cycles and bigint.

Example:

import { McpCacheManager } from "@alneas/eaos-core/agent/cache-manager";
const cache = new McpCacheManager();
cache.setCache("tenant-demo", "notes.list", {}, ["note-1"]);

Example

import { McpCacheManager } from "@alneas/eaos-core/agent/cache-manager";
const cache = new McpCacheManager();
cache.setCache("tenant-demo", "notes.list", {}, ["note-1"], 60);
console.log(cache.getCache("tenant-demo", "notes.list", {}));

[INTERFACE] `McpConfig`

The ordered set of MCP tools advertised by a plugin.

Imports: @alneas/eaos-core, @alneas/eaos-core/plugin-sdk, @alneas/eaos-core/plugin-sdk/types.

Signature

interface McpConfig {
    tools: McpToolDefinition[];
}

Parameters

Name	Type	Required	Description
`tools`	`McpToolDefinition[]`	Yes	Ordered tool definitions used for discovery/compatibility; declaration does not execute them.

Returns

Type declaration; no runtime value.

Public members

`tools`

Ordered tool definitions used for discovery/compatibility; declaration does not execute them.

Example

See the owning declaration and linked feature guide for usage; no standalone example is documented in source.

[CLASS] `McpGatekeeper`

Evaluate local tool policies and record bounded hash-linked audit entries.

Imports: @alneas/eaos-core, @alneas/eaos-core/security/gatekeeper.

Signature

declare class McpGatekeeper {
    constructor(dbAdapter?: DatabaseAdapter | undefined, auditSink?: GatekeeperAuditSink | undefined, options?: GatekeeperOptions);
    registerPolicy(toolName: string, policy: ExtendedGatekeeperPolicy): void;
    validateCall(params: {
        toolName: string;
        userRoles: string[];
        tenantId: string;
        traceId?: string;
    }): {
        allowed: boolean;
        reason?: string;
        requireHumanApproval: boolean;
        riskLevel: RiskLevel;
        approvalLevel: ApprovalLevel;
    };
    logCall(entry: Omit<GatekeeperAuditEntry, 'id' | 'timestamp' | 'hash' | 'previousHash' | 'approvalLevel'> & {
        approvalLevel?: ApprovalLevel;
    }): GatekeeperAuditEntry;
    logCallDurably(entry: Omit<GatekeeperAuditEntry, 'id' | 'timestamp' | 'hash' | 'previousHash' | 'approvalLevel'> & {
        approvalLevel?: ApprovalLevel;
    }): Promise<GatekeeperAuditEntry>;
    getAuditDeliveryFailures(): readonly {
        entryId: string;
        error: string;
    }[];
    getAuditLogs(tenantId?: string): GatekeeperAuditEntry[];
    getTraceLogs(traceId: string): GatekeeperAuditEntry[];
}

Parameters

Name	Type	Required	Description
`dbAdapter`	`DatabaseAdapter \| undefined`	No	Optional host database adapter used for task_audit_logs insertion; the connection must support execute for that insertion path.
`auditSink`	`GatekeeperAuditSink \| undefined`	No	Optional durable append sink; when both destinations exist both are awaited by durable logging.
`options`	`GatekeeperOptions`	No	Optional logging policy; requireDurableAudit defaults to false and disables legacy logCall when true.

Returns

McpGatekeeper

Remarks

Requires node:crypto. Missing policies default to allowed/low/L1_AUTO; this is not a fail-closed authorization system. Validation checks roles, not tenant admission, consent, entitlements or evidence. Local audit view is capped at 500 entries; durable delivery is host-supplied. Avoid mixing legacy and durable logging concurrently when a single ordered chain is required.

Constructor contract

Public members

`registerPolicy`

Store or replace a tool policy by reference.

Parameters:

toolName: Exact tool/skill identity used by validateCall.
policy: Role, risk and review policy; later external mutation changes future evaluations.

Returns: No value; the policy has been replaced.

Example:

import { McpGatekeeper } from "@alneas/eaos-core/security/gatekeeper";
const gatekeeper = new McpGatekeeper();
gatekeeper.registerPolicy("notes.preview", { riskLevel: "low", requiredRole: "member" });

`validateCall`

Evaluate role admission and derive risk/approval metadata without executing a tool.

Parameters:

params: Tool name, verified user roles and tenant/trace metadata; current evaluation uses toolName and roles only.

Returns: Allowed/denied decision plus risk, required review flag and approval level. No policy means low/L1_AUTO allowed; role arrays mean any match and admin/SUPER_ADMIN bypass role restrictions.

Remarks

No audit is automatically recorded. A caller must honor allowed and requireHumanApproval, and separately enforce tenant, entitlement and evidence policy.

Example:

import { McpGatekeeper } from "@alneas/eaos-core/security/gatekeeper";
const gatekeeper = new McpGatekeeper();
console.log(gatekeeper.validateCall({ toolName: "notes.preview", userRoles: ["member"], tenantId: "tenant-demo" }).allowed); // true

`validateCall.allowed`

Admission/check decision; consumers must inspect it before using the associated result or performing an effect.

`validateCall.reason`

Human-readable explanation of the decision or requested action.

`validateCall.requireHumanApproval`

Whether execution must wait for an explicit host approval workflow.

`validateCall.riskLevel`

Declared operation risk used to determine review requirements; it does not itself grant authorization.

`validateCall.approvalLevel`

Required organizational review category; a level declaration is not proof of approval.

`validateCall.params.toolName`

Registered tool identity used to resolve host execution policy.

`validateCall.params.userRoles`

Verified host role claims passed to gatekeeper/runtime evaluation.

`validateCall.params.tenantId`

Verified tenant boundary for the record or operation; host authorization must establish this scope.

`validateCall.params.traceId`

Trace correlation identity propagated through host execution and audit paths.

`logCall`

Append a local audit entry and start best-effort configured persistence.

Parameters:

entry: Audit scope/outcome; ID, timestamp and hash links are generated, and approval level is derived from risk when omitted.

Returns: The local audit entry reference, before any asynchronous persistence has completed.

Remarks

Persistence failures are retained in a bounded 100-entry diagnostic list. Completion does not prove durable storage; use logCallDurably when persistence is required.

Errors and rejections

Error when requireDurableAudit is enabled, or JSON hashing fails.

Example:

import { McpGatekeeper } from "@alneas/eaos-core/security/gatekeeper";
const gatekeeper = new McpGatekeeper();
console.log(gatekeeper.logCall({ toolName: "notes.preview", userId: "user-demo", tenantId: "tenant-demo", status: "ALLOWED", riskLevel: "low" }).hash);

`logCall.entry.approvalLevel`

Required organizational review category; a level declaration is not proof of approval.

`logCallDurably`

Serialize audit appends and add the local entry only after configured destinations accept it.

Parameters:

entry: Audit scope/outcome; generated identity/timestamp/hash and default approval level follow logCall semantics.

Returns: The appended entry after all configured deliveries resolve.

Remarks

Multiple sinks are not one transaction: one may accept before another rejects. The local chain hash is rolled back on failure, but accepted external writes are not undone; hosts must reconcile partial outcomes before retrying.

Errors and rejections

Rejects without a durable destination, on hashing errors, or when a configured database/sink write rejects.

Example:

import { McpGatekeeper } from "@alneas/eaos-core/security/gatekeeper";
import type { GatekeeperAuditSink } from "@alneas/eaos-core/security/gatekeeper";
async function appendHostAudit(sink: GatekeeperAuditSink) {
 const gatekeeper = new McpGatekeeper(undefined, sink, { requireDurableAudit: true });
 return gatekeeper.logCallDurably({ toolName: "notes.preview", userId: "user-demo", tenantId: "tenant-demo", status: "ALLOWED", riskLevel: "low" });
}

`logCallDurably.entry.approvalLevel`

Required organizational review category; a level declaration is not proof of approval.

`getAuditDeliveryFailures`

Copy the bounded legacy persistence-failure diagnostics.

Returns: New failure objects in a new array, up to the latest 100 legacy failures.

Remarks

Local diagnostics are not a substitute for durable host audit storage.

Example:

import { McpGatekeeper } from "@alneas/eaos-core/security/gatekeeper";
const gatekeeper = new McpGatekeeper();
console.log(gatekeeper.getAuditDeliveryFailures()); // []

`getAuditDeliveryFailures[].entryId`

Identity of the audit entry whose delivery failed.

`getAuditDeliveryFailures[].error`

Optional human-readable failure detail; absence does not independently establish success.

`getAuditLogs`

Read the bounded local audit view, optionally filtering by tenant.

Parameters:

tenantId: Optional exact tenant key; omission or a falsy value exposes the full local array.

Returns: A filtered array when tenantId is truthy, otherwise the internal mutable array; entries remain original references.

Remarks

Local diagnostics are not a substitute for durable host audit storage.

Example:

import { McpGatekeeper } from "@alneas/eaos-core/security/gatekeeper";
const gatekeeper = new McpGatekeeper();
console.log(gatekeeper.getAuditLogs("tenant-demo")); // []

`getTraceLogs`

Filter local audit entries by exact trace identity.

Parameters:

traceId: Trace correlation key.

Returns: New array containing original matching entry references.

Remarks

Local diagnostics are not a substitute for durable host audit storage.

Example:

import { McpGatekeeper } from "@alneas/eaos-core/security/gatekeeper";
const gatekeeper = new McpGatekeeper();
console.log(gatekeeper.getTraceLogs("trace-1")); // []

Example

import { McpGatekeeper } from "@alneas/eaos-core/security/gatekeeper";
const gatekeeper = new McpGatekeeper();
console.log(gatekeeper.validateCall({ toolName: "notes.preview", userRoles: ["member"], tenantId: "tenant-demo" }));

[INTERFACE] `McpToolDefinition`

Host-executed tool metadata, argument schema and asynchronous handler.

Imports: @alneas/eaos-core, @alneas/eaos-core/plugin-sdk, @alneas/eaos-core/plugin-sdk/types.

Signature

interface McpToolDefinition {
    name: string;
    description: string;
    parameters: Record<string, any>;
    contract?: {
        version: string;
        permission: string;
        sideEffect: 'read' | 'write' | 'external';
        outputSchema?: Record<string, unknown>;
    };
    handler: (args: any, context?: any) => Promise<any>;
}

Parameters

Name	Type	Required	Description
`name`	`string`	Yes	Exact registered tool identity; parsing/discovery does not authorize its execution.
`description`	`string`	Yes	Human-readable metadata describing the capability, workflow node or requirement to host users.
`parameters`	`Record<string, any>`	Yes	JSON Schema describing tool arguments; the host validates arguments before execution.
`contract`	`{ version: string; permission: string; sideEffect: 'read' \| 'write' \| 'external'; outputSchema?: Record<string, unknown>; }`	No	Optional versioned meaning used for approval and saved-workflow compatibility checks.
`handler`	`(args: any, context?: any) => Promise<any>`	Yes	Execute an admitted host tool with domain arguments and optional host context.

Returns

Type declaration; no runtime value.

Public members

`name`

Exact registered tool identity; parsing/discovery does not authorize its execution.

`description`

Human-readable metadata describing the capability, workflow node or requirement to host users.

`parameters`

JSON Schema describing tool arguments; the host validates arguments before execution.

`contract`

Optional versioned meaning used for approval and saved-workflow compatibility checks.

`contract.version`

Version of the tool meaning used for approval/compatibility snapshots.

`contract.permission`

Host permission identity required for this operation.

`contract.sideEffect`

Classify whether the operation reads, writes local state or affects an external service.

`contract.outputSchema`

Optional JSON Schema describing operation output; absent means no output contract is declared here.

`handler`

Execute an admitted host tool with domain arguments and optional host context.

Parameters:

args: Decoded tool input; the host must validate parameters before invocation.
context: Optional verified host scope/capabilities; PluginToolContext is the preferred EAOS host contract.

Returns: Asynchronous domain result serialized by the host; failures reject.

Remarks

Host owns live authorization, approval, deadlines, idempotency and side effects.

Example

See the owning declaration and linked feature guide for usage; no standalone example is documented in source.

[FUNCTION] `minorToDecimal`

Format a safe integer amount at an explicit decimal scale.

Imports: @alneas/eaos-core/plugin-sdk, @alneas/eaos-core/plugin-sdk/decimal-values.

Signature

declare function minorToDecimal(value: number, minorUnits: number): string;

Parameters

Name	Type	Required	Description
`value`	`number`	Yes	Safe integer amount in minor units.
`minorUnits`	`number`	Yes	Power-of-ten exponent from 0 to 18.

Returns

string

Exact decimal text retaining the requested scale.

Errors and rejections

Error for an unsafe integer, invalid exponent or a formatted value exceeding decimalValueSchema.

Example

import { minorToDecimal } from "@alneas/eaos-core/plugin-sdk/decimal-values";
console.log(minorToDecimal(1250, 2)); // 12.50

[INTERFACE] `ModelRoutingConfig`

Static provider/model route metadata and declared sensitivity limits.

Imports: @alneas/eaos-core, @alneas/eaos-core/agentic, @alneas/eaos-core/agentic/types.

Signature

interface ModelRoutingConfig {
    provider: 'groq' | 'cloudflare_workers_ai' | 'mlx_local' | 'opencode' | 'google_ai_studio' | 'oci_local_2b' | 'ruri_embedding';
    modelName: string;
    tier: ModelTier;
    requiresNoTraining: boolean;
    allowedSensitivity: DataSensitivityLevel[];
}

Parameters

Name	Type	Required	Description
`provider`	`'groq' \| 'cloudflare_workers_ai' \| 'mlx_local' \| 'opencode' \| 'google_ai_studio' \| 'oci_local_2b' \| 'ruri_embedding'`	Yes	Provider identity from model metadata, travel discovery or connection/circuit health.
`modelName`	`string`	Yes	Provider-specific model name from the static routing catalog.
`tier`	`ModelTier`	Yes	Commercial entitlement category or model resource tier, interpreted by its owning policy.
`requiresNoTraining`	`boolean`	Yes	Declared no-training policy requirement; the host must verify and enforce the provider agreement.
`allowedSensitivity`	`DataSensitivityLevel[]`	Yes	Data classifications the host advertises as permitted on this model/route.

Returns

Type declaration; no runtime value.

Public members

`provider`

Provider identity from model metadata, travel discovery or connection/circuit health.

`modelName`

Provider-specific model name from the static routing catalog.

`tier`

Commercial entitlement category or model resource tier, interpreted by its owning policy.

`requiresNoTraining`

Declared no-training policy requirement; the host must verify and enforce the provider agreement.

`allowedSensitivity`

Data classifications the host advertises as permitted on this model/route.

Example

See the owning declaration and linked feature guide for usage; no standalone example is documented in source.

[CLASS] `ModelRoutingGateway`

Apply built-in prompt heuristics and choose from a fixed model catalog.

Imports: @alneas/eaos-core, @alneas/eaos-core/agentic, @alneas/eaos-core/agentic/model-routing-gateway.

Signature

declare class ModelRoutingGateway {
    sanitizePrompt(prompt: string): SanitizationResult;
    selectModel(tier: ModelTier, sensitivityLevel: DataSensitivityLevel): ModelRoutingConfig;
}

Parameters

Name	Type	Required	Description
—	—	—	No call parameters.

Returns

ModelRoutingGateway

Remarks

This is a heuristic helper, not comprehensive PII detection or verified provider policy. Model metadata is static; no provider is called.

Public members

`sanitizePrompt`

Mask recognized phone/email patterns and classify prompt text heuristically.

Parameters:

prompt: Text inspected for phone/email patterns and selected Japanese confidentiality/internal markers.

Returns: Original/sanitized text, detected types, replacement map and recommended tier.

Remarks

Retains the original prompt and sensitive values in the result; caller must protect it. Pattern detection is incomplete and does not establish a privacy guarantee.

Example:

import { ModelRoutingGateway } from "@alneas/eaos-core/agentic/model-routing-gateway";
const gateway = new ModelRoutingGateway();
console.log(gateway.sanitizePrompt("Contact [email protected]").sensitivityLevel); // level3_strict

`selectModel`

Select a built-in model by sensitivity and requested tier.

Parameters:

tier: Preferred tier for nonstrict data.
sensitivityLevel: Strict data selects the first MLX local model regardless of tier; other levels filter by tier and allowedSensitivity.

Returns: The original mutable model configuration; when no ordinary match exists the first catalog entry is returned.

Remarks

Does not enforce live provider no-training agreements or authorization; fallback can disregard the requested tier.

Example:

import { ModelRoutingGateway } from "@alneas/eaos-core/agentic/model-routing-gateway";
const gateway = new ModelRoutingGateway();
console.log(gateway.selectModel("tier2_edge_local", "level3_strict").provider);

Example

import { ModelRoutingGateway } from "@alneas/eaos-core/agentic/model-routing-gateway";
const gateway = new ModelRoutingGateway();
const result = gateway.sanitizePrompt("Contact [email protected]");
console.log(result.sanitizedPrompt);

[TYPE] `ModelTier`

Model capability/cost tiers used by built-in agentic routing metadata.

Imports: @alneas/eaos-core, @alneas/eaos-core/agentic, @alneas/eaos-core/agentic/types.

Signature

type ModelTier = 'tier1_cloud_premium' | 'tier2_edge_local' | 'tier3_embedding_rerank';

Parameters

Name	Type	Required	Description
—	—	—	No call parameters.

Returns

Type declaration; no runtime value.

Example

See the owning declaration and linked feature guide for usage; no standalone example is documented in source.

[INTERFACE] `NavigationConfig`

A labeled navigation group with sorting order and child links.

Imports: @alneas/eaos-core, @alneas/eaos-core/plugin-sdk, @alneas/eaos-core/plugin-sdk/types.

Signature

interface NavigationConfig {
    label: string;
    icon: string;
    order: number;
    children: NavigationItem[];
}

Parameters

Name	Type	Required	Description
`label`	`string`	Yes	Human-readable navigation/node/setting label displayed by the host.
`icon`	`string`	Yes	Host UI icon identifier for displaying the plugin/navigation item.
`order`	`number`	Yes	Numeric navigation sorting order interpreted by the host UI.
`children`	`NavigationItem[]`	Yes	Ordered child navigation links displayed in this group.

Returns

Type declaration; no runtime value.

Public members

`label`

Human-readable navigation/node/setting label displayed by the host.

`icon`

Host UI icon identifier for displaying the plugin/navigation item.

`order`

Numeric navigation sorting order interpreted by the host UI.

`children`

Ordered child navigation links displayed in this group.

Example

See the owning declaration and linked feature guide for usage; no standalone example is documented in source.

[INTERFACE] `NavigationItem`

One child navigation link with its display label and optional icon.

Imports: @alneas/eaos-core, @alneas/eaos-core/plugin-sdk, @alneas/eaos-core/plugin-sdk/types.

Signature

interface NavigationItem {
    path: string;
    label: string;
    icon?: string;
}

Parameters

Name	Type	Required	Description
`path`	`string`	Yes	Client route destination interpreted by the host navigation layer.
`label`	`string`	Yes	Human-readable navigation/node/setting label displayed by the host.
`icon`	`string`	No	Host UI icon identifier for displaying the plugin/navigation item.

Returns

Type declaration; no runtime value.

Public members

`path`

Client route destination interpreted by the host navigation layer.

`label`

Human-readable navigation/node/setting label displayed by the host.

`icon`

Host UI icon identifier for displaying the plugin/navigation item.

Example

See the owning declaration and linked feature guide for usage; no standalone example is documented in source.

[TYPE] `ObjectStorageRequirement`

Whether plugin data may or must use external object storage.

Imports: @alneas/eaos-core/plugin-sdk, @alneas/eaos-core/plugin-sdk/storage-policy.

Signature

type ObjectStorageRequirement = 'forbidden' | 'optional' | 'required';

Parameters

Name	Type	Required	Description
—	—	—	No call parameters.

Returns

Type declaration; no runtime value.

Example

See the owning declaration and linked feature guide for usage; no standalone example is documented in source.

[INTERFACE] `OperationResult`

Compatibility re-export; its implementation and documentation are owned by the owning package @dataarthub/app-core.

Imports: @alneas/eaos-core, @alneas/eaos-core/adapters, @alneas/eaos-core/adapters/types.

Signature

export interface OperationResult {
    acknowledged: boolean;
    matchedCount?: number;
    modifiedCount?: number;
    deletedCount?: number;
    insertedId?: string;
    upsertedId?: string;
}

Parameters

Name	Type	Required	Description
`acknowledged`	`boolean`	Yes	See the upstream owning declaration.
`matchedCount`	`number`	No	See the upstream owning declaration.
`modifiedCount`	`number`	No	See the upstream owning declaration.
`deletedCount`	`number`	No	See the upstream owning declaration.
`insertedId`	`string`	No	See the upstream owning declaration.
`upsertedId`	`string`	No	See the upstream owning declaration.

Returns

Type declaration; no runtime value.

Example

See the owning declaration and linked feature guide for usage; no standalone example is documented in source.

[CLASS] `OutboxDispatcher`

Claim and settle one bounded batch through host-owned storage and topic handlers.

Imports: @alneas/eaos-core, @alneas/eaos-core/events/outbox.

Signature

declare class OutboxDispatcher {
    constructor(options: OutboxDispatcherOptions);
    runOnce(): Promise<OutboxDispatchResult>;
}

Parameters

Name	Type	Required	Description
`options`	`OutboxDispatcherOptions`	Yes	Required store/handlers and optional admission wrapper/clock/retry settings; defaults are 20 records, 5 attempts, 1000 ms base, 60000 ms cap and multiplier 2.

Returns

OutboxDispatcher

Remarks

No timers, cancellation or automatic looping. Hosts own scheduling, atomic claims/claim tokens, tenant admission and idempotent effects. Records are handled sequentially; handler success followed by settlement failure can cause a retry of an already-completed effect.

Constructor contract

Remarks

Constructing the dispatcher performs no claim, handler call or scheduling. Retry settings are validated when retryDelayMs is used.

Errors and rejections

Error for missing store/handlers or batchSize outside integer range 1–100.

Public members

`runOnce`

Claim due events and execute/settle each one sequentially.

Returns: Counts of claimed, published, rescheduled and terminally failed records; empty batches return zero counts.

Remarks

Unknown topic errors are terminal; other errors retry unless OutboxDispatchError says otherwise or attempts are exhausted. Concurrent runOnce safety depends on atomic host claims; no exactly-once guarantee is provided.

Errors and rejections

Rejects on store claim/markFailed errors, invalid retry calculations or clock failures. Handler/admission/markPublished failures normally become failed/rescheduled records.

Example:

import { OutboxDispatcher } from "@alneas/eaos-core/events/outbox";
import type { OutboxDispatcherOptions } from "@alneas/eaos-core/events/outbox";
async function dispatchHostBatch(options: OutboxDispatcherOptions) {
 const dispatcher = new OutboxDispatcher(options);
 return dispatcher.runOnce();
}

Example

import { OutboxDispatcher } from "@alneas/eaos-core/events/outbox";
import type { OutboxDispatcherOptions } from "@alneas/eaos-core/events/outbox";
async function dispatchHostBatch(options: OutboxDispatcherOptions) {
 return new OutboxDispatcher(options).runOnce();
}

[INTERFACE] `OutboxDispatcherOptions`

Host persistence, handlers, scheduling clock and optional admission wrapper for a worker pass.

Imports: @alneas/eaos-core, @alneas/eaos-core/events/outbox.

Signature

interface OutboxDispatcherOptions {
    store: OutboxStore;
    handlers: Record<string, (event: Readonly<OutboxEvent>) => Promise<void>>;
    now?: () => Date;
    retryPolicy?: Partial<OutboxRetryPolicy>;
    batchSize?: number;
    execute?: (event: Readonly<OutboxEvent>, handler: () => Promise<void>) => Promise<void>;
}

Parameters

Name	Type	Required	Description
`store`	`OutboxStore`	Yes	Transactional host outbox port; claiming and settlement must enforce claim ownership and tenant scope.
`handlers`	`Record<string, (event: Readonly<OutboxEvent>) => Promise<void>>`	Yes	Map exact event topics to asynchronous effect handlers.
`now`	`() => Date`	No	Provide the worker clock used for claiming and settlement timestamps.
`retryPolicy`	`Partial<OutboxRetryPolicy>`	No	Optional retry overrides; dispatcher defaults to 5 attempts, 1000 ms base, 60000 ms maximum and multiplier 2.
`batchSize`	`number`	No	Maximum claim size for one pass, from 1 to 100; defaults to 20.
`execute`	`(event: Readonly<OutboxEvent>, handler: () => Promise<void>) => Promise<void>`	No	Optionally enforce live host admission immediately before the handler side effect.

Returns

Type declaration; no runtime value.

Public members

`store`

Transactional host outbox port; claiming and settlement must enforce claim ownership and tenant scope.

`handlers`

Map exact event topics to asynchronous effect handlers.

Remarks

Each callback receives a cloned readonly event and resolves without a value after its effect completes. Rejections normally schedule retries, so handlers must be replay-safe; use OutboxDispatchError with retryable false for terminal failures.

Remarks

Omission calls handler directly. Host owns authorization, replay safety and partial-outcome reconciliation.

Errors and rejections

Wrapper/handler failures enter dispatcher retry/failure settlement.

Example

See the owning declaration and linked feature guide for usage; no standalone example is documented in source.

[CLASS] `OutboxDispatchError`

Mark a dispatch failure as retryable or terminal.

Imports: @alneas/eaos-core, @alneas/eaos-core/events/outbox.

Signature

declare class OutboxDispatchError extends Error {
    readonly retryable: boolean;
    constructor(message: string, options?: {
        retryable?: boolean;
        cause?: unknown;
    });
}

Parameters

Name	Type	Required	Description
`message`	`string`	Yes	Human-readable failure text; dispatcher truncates stored Error messages to 1000 characters.
`options`	`{ retryable?: boolean; cause?: unknown; }`	No	retryable defaults to true; optional cause is forwarded to Error.

Returns

OutboxDispatchError

Constructor contract

Public members

`retryable`

Whether dispatch should be rescheduled; defaults to true when omitted at construction.

`constructor.options.retryable`

Whether the recorded failure permits a host retry; callers must still account for possible completed effects.

`constructor.options.cause`

Optional underlying error passed through the standard Error cause option.

Example

import { OutboxDispatchError } from "@alneas/eaos-core/events/outbox";
const error = new OutboxDispatchError("Receiver declined the event", { retryable: false });
console.log(error.retryable); // false

[INTERFACE] `OutboxDispatchResult`

Counts from one worker pass, including retries and terminal failures.

Imports: @alneas/eaos-core, @alneas/eaos-core/events/outbox.

Signature

interface OutboxDispatchResult {
    claimed: number;
    published: number;
    retried: number;
    failed: number;
}

Parameters

Name	Type	Required	Description
`claimed`	`number`	Yes	Number of records returned by the store claim for this pass.
`published`	`number`	Yes	Number of claimed records whose handler and markPublished completed.
`retried`	`number`	Yes	Number of failed records rescheduled with a nonnull retry timestamp.
`failed`	`number`	Yes	Number of claimed records marked as terminal failures in this pass.

Returns

Type declaration; no runtime value.

Public members

`claimed`

Number of records returned by the store claim for this pass.

`published`

Number of claimed records whose handler and markPublished completed.

`retried`

Number of failed records rescheduled with a nonnull retry timestamp.

`failed`

Number of claimed records marked as terminal failures in this pass.

Example

See the owning declaration and linked feature guide for usage; no standalone example is documented in source.

[INTERFACE] `OutboxEvent`

Tenant-scoped payload envelope plus host-owned claim and publication state.

Imports: @alneas/eaos-core, @alneas/eaos-core/events/outbox.

Signature

interface OutboxEvent<T = unknown> {
    id: string;
    tenantId: string;
    producer: string;
    topic: string;
    idempotencyKey: string;
    payload: T;
    payloadHash: string;
    occurredAt: string;
    availableAt: string;
    status: OutboxEventStatus;
    attempts: number;
    claimedAt?: string;
    claimToken?: string;
    publishedAt?: string;
    lastError?: string;
}

Parameters

Name	Type	Required	Description
`id`	`string`	Yes	Stable event identity; generated IDs hash tenant/producer/idempotency key, excluding topic/payload.
`tenantId`	`string`	Yes	Verified tenant boundary for the record or operation; host authorization must establish this scope.
`producer`	`string`	Yes	Stable component identity emitting the event.
`topic`	`string`	Yes	Exact event dispatch key used to locate a registered host handler.
`idempotencyKey`	`string`	Yes	Replay identity for the same admitted operation; the host must persist/deduplicate it before unsafe retries.
`payload`	`T`	Yes	Typed event/request body; constructors clone and strictly hash JSON where documented.
`payloadHash`	`string`	Yes	SHA-256 identity of the canonical JSON event payload.
`occurredAt`	`string`	Yes	Event/effect occurrence timestamp; creation helpers normalize supported inputs to ISO text.
`availableAt`	`string`	Yes	Earliest timestamp at which the host scheduler may claim or execute this work.
`status`	`OutboxEventStatus`	Yes	Host outbox lifecycle; createOutboxEvent initializes pending.
`attempts`	`number`	Yes	Host-recorded outbox claim attempt count; new envelopes start at zero.
`claimedAt`	`string`	No	Optional timestamp at which the host store claimed the event.
`claimToken`	`string`	No	Host claim ownership token required when settling a claimed event.
`publishedAt`	`string`	No	Timestamp recorded after successful handler completion and host settlement.
`lastError`	`string`	No	Most recent host-recorded failure detail, when available.

Returns

Type declaration; no runtime value.

Type parameters

T: JSON-safe event body type, default unknown; host persistence retains the envelope identity.

Public members

`id`

Stable event identity; generated IDs hash tenant/producer/idempotency key, excluding topic/payload.

`tenantId`

Verified tenant boundary for the record or operation; host authorization must establish this scope.

`producer`

Stable component identity emitting the event.

`topic`

Exact event dispatch key used to locate a registered host handler.

`idempotencyKey`

Replay identity for the same admitted operation; the host must persist/deduplicate it before unsafe retries.

`payload`

Typed event/request body; constructors clone and strictly hash JSON where documented.

`payloadHash`

SHA-256 identity of the canonical JSON event payload.

`occurredAt`

Event/effect occurrence timestamp; creation helpers normalize supported inputs to ISO text.

`availableAt`

Earliest timestamp at which the host scheduler may claim or execute this work.

`status`

Host outbox lifecycle; createOutboxEvent initializes pending.

`attempts`

Host-recorded outbox claim attempt count; new envelopes start at zero.

`claimedAt`

Optional timestamp at which the host store claimed the event.

`claimToken`

Host claim ownership token required when settling a claimed event.

`publishedAt`

Timestamp recorded after successful handler completion and host settlement.

`lastError`

Most recent host-recorded failure detail, when available.

Example

See the owning declaration and linked feature guide for usage; no standalone example is documented in source.

[INTERFACE] `OutboxEventInput`

Inputs for constructing an event before host persistence.

Imports: @alneas/eaos-core, @alneas/eaos-core/events/outbox.

Signature

interface OutboxEventInput<T = unknown> {
    tenantId: string;
    producer: string;
    topic: string;
    idempotencyKey: string;
    payload: T;
    id?: string;
    occurredAt?: Date | string;
    availableAt?: Date | string;
}

Parameters

Name	Type	Required	Description
`tenantId`	`string`	Yes	Verified tenant boundary for the record or operation; host authorization must establish this scope.
`producer`	`string`	Yes	Stable component identity emitting the event.
`topic`	`string`	Yes	Exact event dispatch key used to locate a registered host handler.
`idempotencyKey`	`string`	Yes	Replay identity for the same admitted operation; the host must persist/deduplicate it before unsafe retries.
`payload`	`T`	Yes	Typed event/request body; constructors clone and strictly hash JSON where documented.
`id`	`string`	No	Optional explicit event identity; omission derives it from tenant/producer/idempotency key.
`occurredAt`	`Date \| string`	No	Event/effect occurrence timestamp; creation helpers normalize supported inputs to ISO text.
`availableAt`	`Date \| string`	No	Earliest timestamp at which the host scheduler may claim or execute this work.

Returns

Type declaration; no runtime value.

Type parameters

T: JSON-safe payload type cloned into the constructed envelope; default unknown.

Public members

`tenantId`

Verified tenant boundary for the record or operation; host authorization must establish this scope.

`producer`

Stable component identity emitting the event.

`topic`

Exact event dispatch key used to locate a registered host handler.

`idempotencyKey`

Replay identity for the same admitted operation; the host must persist/deduplicate it before unsafe retries.

`payload`

Typed event/request body; constructors clone and strictly hash JSON where documented.

`id`

Optional explicit event identity; omission derives it from tenant/producer/idempotency key.

`occurredAt`

Event/effect occurrence timestamp; creation helpers normalize supported inputs to ISO text.

`availableAt`

Earliest timestamp at which the host scheduler may claim or execute this work.

Example

See the owning declaration and linked feature guide for usage; no standalone example is documented in source.

[TYPE] `OutboxEventStatus`

Persisted lifecycle states understood by an outbox store.

Imports: @alneas/eaos-core, @alneas/eaos-core/events/outbox.

Signature

type OutboxEventStatus = 'pending' | 'processing' | 'published' | 'failed';

Parameters

Name	Type	Required	Description
—	—	—	No call parameters.

Returns

Type declaration; no runtime value.

Example

See the owning declaration and linked feature guide for usage; no standalone example is documented in source.

[INTERFACE] `OutboxRetryPolicy`

Attempt limit and capped exponential delay configuration in milliseconds.

Imports: @alneas/eaos-core, @alneas/eaos-core/events/outbox.

Signature

interface OutboxRetryPolicy {
    maxAttempts: number;
    baseDelayMs: number;
    maxDelayMs: number;
    backoffMultiplier: number;
}

Parameters

Name	Type	Required	Description
`maxAttempts`	`number`	Yes	Maximum intended attempt count; delay calculators validate it but do not themselves stop retries.
`baseDelayMs`	`number`	Yes	Initial retry delay in milliseconds before exponential scaling.
`maxDelayMs`	`number`	Yes	Upper bound for a calculated retry delay in milliseconds.
`backoffMultiplier`	`number`	Yes	Exponential growth factor for successive retry delays, at least one for validated policies.

Returns

Type declaration; no runtime value.

Public members

`maxAttempts`

Maximum intended attempt count; delay calculators validate it but do not themselves stop retries.

`baseDelayMs`

Initial retry delay in milliseconds before exponential scaling.

`maxDelayMs`

Upper bound for a calculated retry delay in milliseconds.

`backoffMultiplier`

Exponential growth factor for successive retry delays, at least one for validated policies.

Example

See the owning declaration and linked feature guide for usage; no standalone example is documented in source.

[INTERFACE] `OutboxStore`

Transactional host storage port for claiming and settling outbox records.

Imports: @alneas/eaos-core, @alneas/eaos-core/events/outbox.

Signature

interface OutboxStore {
    claim(now: Date, limit: number): Promise<readonly OutboxEvent[]>;
    markPublished(id: string, claimToken: string, publishedAt: Date): Promise<void>;
    markFailed(id: string, claimToken: string, error: string, retryAt: Date | null): Promise<void>;
}

Parameters

Name	Type	Required	Description
`claim`	`Promise<readonly OutboxEvent[]>`	Yes	Atomically claim a bounded set of due records for one host worker.
`markPublished`	`Promise<void>`	Yes	Settle a claimed event after its handler completes.
`markFailed`	`Promise<void>`	Yes	Settle a failed claim with either a retry schedule or terminal state.

Returns

Type declaration; no runtime value.

Public members

`claim`

Atomically claim a bounded set of due records for one host worker.

Parameters:

now: Host claim time used to determine due work.
limit: Maximum records requested; dispatcher supplies its validated batch size.

Returns: Claimed records with host-owned claim/attempt metadata, possibly empty.

Remarks

Host owns transaction/CAS, leases, tenant isolation and claim tokens. Concurrent workers must not claim the same live record.

Errors and rejections

Host claim failures reject the Promise.

Example:

import type { OutboxStore } from "@alneas/eaos-core/events/outbox";
async function claimHostEvents(store: OutboxStore) { return store.claim(new Date(), 20); }

`markPublished`

Settle a claimed event after its handler completes.

Parameters:

id: Claimed event identity.
claimToken: Exact live claim ownership token.
publishedAt: Host publication completion timestamp.

Returns: No value; the host settlement has completed.

Remarks

Host must enforce claim ownership and durable settlement. A rejection after the handler effect does not prove the effect failed.

Errors and rejections

Host settlement failures reject the Promise.

Example:

import type { OutboxStore } from "@alneas/eaos-core/events/outbox";
async function settleHostEvent(store: OutboxStore, id: string, claimToken: string) { await store.markPublished(id, claimToken, new Date()); }

`markFailed`

Settle a failed claim with either a retry schedule or terminal state.

Parameters:

id: Claimed event identity.
claimToken: Exact live claim ownership token.
error: Sanitized failure text; dispatcher truncates Error messages to 1000 characters.
retryAt: Future due time for a retry, or null for terminal failure.

Returns: No value; the host failure/retry settlement has completed.

Remarks

Host must enforce claim ownership and atomically release/reschedule the claim; Core does not implement storage.

Errors and rejections

Host settlement failures reject the Promise.

Example:

import type { OutboxStore } from "@alneas/eaos-core/events/outbox";
async function failHostEvent(store: OutboxStore, id: string, claimToken: string) { await store.markFailed(id, claimToken, "Temporary failure", new Date(Date.now() + 1000)); }

Example

See the owning declaration and linked feature guide for usage; no standalone example is documented in source.

[FUNCTION] `parseWorkflowAgentProposal`

Parse the bounded JSON envelope emitted by a host runtime. Domain-specific validation of output remains in the plugin workflow.

Imports: @alneas/eaos-core, @alneas/eaos-core/workflow-contracts.

Signature

declare function parseWorkflowAgentProposal<TOutput = unknown>(raw: unknown): WorkflowAgentProposal<TOutput>;

Parameters

Name	Type	Required	Description
`raw`	`unknown`	Yes	JSON text or an object with schemaVersion 1.0, nonempty summary, evidence/actions arrays and a valid risk level.

Returns

WorkflowAgentProposal<TOutput>

A structured clone of the normalized proposal; output is carried through without domain-schema validation.

Type parameters

TOutput: Expected domain output type; this assertion does not validate that shape and defaults to unknown.

Remarks

A proposal never authorizes execution. Domain output validation and action authorization belong to the host.

Errors and rejections

Error for invalid JSON, envelope or bounded text; structuredClone errors propagate for uncloneable output/arguments.

Example

import { parseWorkflowAgentProposal } from "@alneas/eaos-core/workflow-contracts";
const proposal = parseWorkflowAgentProposal({ schemaVersion: "1.0", summary: "No changes", output: { count: 0 }, evidence: [], actions: [], riskLevel: "low" });
console.log(proposal.summary);

[CONSTANT] `PLATFORM_DEFAULTS_VERSION`

Pure configuration contract. No environment, filesystem, network or provider access.

Imports: @alneas/eaos-core/platform/config.

Signature

declare const PLATFORM_DEFAULTS_VERSION: "1";

Parameters

Name	Type	Required	Description
—	—	—	No call parameters.

Returns

Declared constant value.

Example

See the owning declaration and linked feature guide for usage; no standalone example is documented in source.

[INTERFACE] `PlatformAuditEvent`

Audit input augmented with generated identity, timestamp and hash-chain links.

Imports: @alneas/eaos-core, @alneas/eaos-core/security/platform-security.

Signature

interface PlatformAuditEvent extends PlatformAuditEventInput {
    id: string;
    occurredAt: string;
    previousHash: string;
    hash: string;
}

Parameters

Name	Type	Required	Description
`id`	`string`	Yes	Random UUID generated when the audit append is processed.
`occurredAt`	`string`	Yes	Event/effect occurrence timestamp; creation helpers normalize supported inputs to ISO text.
`previousHash`	`string`	Yes	Previous audit event hash used to link ordered entries.
`hash`	`string`	Yes	Content integrity digest; hashes are unkeyed and do not establish authorization or writer authenticity.

Returns

Type declaration; no runtime value.

Public members

`id`

Random UUID generated when the audit append is processed.

`occurredAt`

Event/effect occurrence timestamp; creation helpers normalize supported inputs to ISO text.

`previousHash`

Previous audit event hash used to link ordered entries.

`hash`

Content integrity digest; hashes are unkeyed and do not establish authorization or writer authenticity.

Example

See the owning declaration and linked feature guide for usage; no standalone example is documented in source.

[INTERFACE] `PlatformAuditEventInput`

Caller-supplied audit scope, action, outcome and optional resource context.

Imports: @alneas/eaos-core, @alneas/eaos-core/security/platform-security.

Signature

interface PlatformAuditEventInput {
    tenantId: string;
    userId: string;
    action: string;
    outcome: 'success' | 'denied' | 'failure';
    resourceType?: string;
    resourceId?: string;
    traceId?: string;
    metadata?: Readonly<Record<string, unknown>>;
}

Parameters

Name	Type	Required	Description
`tenantId`	`string`	Yes	Verified tenant boundary for the record or operation; host authorization must establish this scope.
`userId`	`string`	Yes	User identity within the tenant supplied by the trusted host.
`action`	`string`	Yes	Named host action performed or requested; procedure exception entries use this as the response instruction.
`outcome`	`'success' \| 'denied' \| 'failure'`	Yes	Reported success/failure/denial/unknown category; reconcile uncertain effects before retrying.
`resourceType`	`string`	No	Optional audit resource category.
`resourceId`	`string`	No	Optional audit resource identity.
`traceId`	`string`	No	Trace correlation identity propagated through host execution and audit paths.
`metadata`	`Readonly<Record<string, unknown>>`	No	Optional host/provider metadata; callers remain responsible for sensitive content and validation.

Returns

Type declaration; no runtime value.

Public members

`tenantId`

Verified tenant boundary for the record or operation; host authorization must establish this scope.

`userId`

User identity within the tenant supplied by the trusted host.

`action`

Named host action performed or requested; procedure exception entries use this as the response instruction.

`outcome`

Reported success/failure/denial/unknown category; reconcile uncertain effects before retrying.

`resourceType`

Optional audit resource category.

`resourceId`

Optional audit resource identity.

`traceId`

Trace correlation identity propagated through host execution and audit paths.

`metadata`

Optional host/provider metadata; callers remain responsible for sensitive content and validation.

Example

See the owning declaration and linked feature guide for usage; no standalone example is documented in source.

[INTERFACE] `PlatformConfig`

Declarative public origins, ingress, service and authentication settings without credentials.

Imports: @alneas/eaos-core/platform/config.

Signature

interface PlatformConfig {
    appName: string;
    baseDomain: string;
    defaultsVersion?: typeof PLATFORM_DEFAULTS_VERSION;
    environment?: 'production' | 'development';
    networkName?: string;
    origins?: {
        app?: string;
        auth?: string;
    };
    ingress?: {
        appAliases?: string[];
        hostRoutes?: IngressHostRoute[];
        additionalApiPrefixes?: string[];
    };
    services?: {
        backend?: ServiceConfig;
        frontend?: ServiceConfig;
        kratos?: ServiceConfig & {
            adminPort?: number;
        };
    };
    cors?: {
        additionalOrigins?: string[];
        honoAdditionalOrigins?: string[];
        kratosAdditionalOrigins?: string[];
    };
    auth?: {
        uiOrigin?: string;
        defaultBrowserReturnUrl?: string;
        identitySchemas?: IdentitySchemaFile[];
        defaultSchemaId?: string;
        cookie?: {
            name?: string;
            domain?: string;
            path?: string;
            sameSite?: SameSite;
            secure?: boolean;
            persistent?: boolean;
        };
        ui?: Partial<Record<AuthUiFlow, string>>;
        registrationHook?: false | RegistrationHookConfig;
        oidc?: false | {
            google: GoogleOidcConfig;
        };
    };
}

Parameters

Name	Type	Required	Description
`appName`	`string`	Yes	Lowercase DNS label identifying the application and derived network settings.
`baseDomain`	`string`	Yes	DNS domain with at least two valid lowercase labels; scopes cookie and managed ingress hosts.
`defaultsVersion`	`typeof PLATFORM_DEFAULTS_VERSION`	No	Supported platform defaults version; omission selects PLATFORM_DEFAULTS_VERSION.
`environment`	`'production' \| 'development'`	No	Production or development configuration mode; defaults to production with HTTPS/secure-cookie requirements.
`networkName`	`string`	No	Host network identity; defaults to appName followed by -network.
`origins`	`{ app?: string; auth?: string; }`	No	Distinct public application and authentication origins; defaults to HTTPS app/auth subdomains of baseDomain.
`ingress`	`{ appAliases?: string[]; hostRoutes?: IngressHostRoute[]; additionalApiPrefixes?: string[]; }`	No	Additional exact DNS names for the same app listener/routes; not Docker aliases or CORS grants.
`services`	`{ backend?: ServiceConfig; frontend?: ServiceConfig; kratos?: ServiceConfig & { adminPort?: number; }; }`	No	Optional backend/frontend/Kratos service names and listener/admin port overrides.
`cors`	`{ additionalOrigins?: string[]; honoAdditionalOrigins?: string[]; kratosAdditionalOrigins?: string[]; }`	No	Optional extra-origin declarations separated into shared, application-only and Kratos-only grants.
`auth`	`{ uiOrigin?: string; defaultBrowserReturnUrl?: string; identitySchemas?: IdentitySchemaFile[]; defaultSchemaId?: string; cookie?: { name?: string; domain?: string; path?: string; sameSite?: SameSite; secure?: boolean; persistent?: boolean; }; ui?: Partial<Record<AuthUiFlow, string>>; registrationHook?: false \| RegistrationHookConfig; oidc?: false \| { google: GoogleOidcConfig; }; }`	No	Optional authentication UI, schema, cookie, callback and OIDC settings without runtime credentials.

Returns

Type declaration; no runtime value.

Public members

`appName`

Lowercase DNS label identifying the application and derived network settings.

`baseDomain`

DNS domain with at least two valid lowercase labels; scopes cookie and managed ingress hosts.

`defaultsVersion`

Supported platform defaults version; omission selects PLATFORM_DEFAULTS_VERSION.

`environment`

Production or development configuration mode; defaults to production with HTTPS/secure-cookie requirements.

`networkName`

Host network identity; defaults to appName followed by -network.

`origins`

Distinct public application and authentication origins; defaults to HTTPS app/auth subdomains of baseDomain.

`origins.app`

Optional public application origin; defaults to HTTPS app..

`origins.auth`

Optional public authentication API origin; defaults to HTTPS auth. and must differ from app origin.

`ingress`

Additional exact DNS names for the same app listener/routes; not Docker aliases or CORS grants.

`ingress.appAliases`

Additional exact app DNS names; must stay inside the shared cookie domain and may not claim the auth hostname.

`ingress.hostRoutes`

Additional exact DNS-to-upstream routes; conflicting/reserved host claims are rejected.

`ingress.additionalApiPrefixes`

Optional additional lowercase absolute API paths without trailing slashes; may not overlap /api or each other.

`services`

Optional backend/frontend/Kratos service names and listener/admin port overrides.

`services.backend`

Backend service name/port or resolved service; defaults to hono-server on port 3000.

`services.frontend`

Frontend service name/port or resolved service; defaults to frontend on port 80.

`services.kratos`

Kratos public/admin service configuration or resolved authentication settings.

`services.kratos.adminPort`

Kratos administration port; defaults to 4434 and must differ from the public listener port.

`cors`

Optional extra-origin declarations separated into shared, application-only and Kratos-only grants.

`cors.additionalOrigins`

Extra browser origins shared by Hono and Kratos.

`cors.honoAdditionalOrigins`

Extra origins for the application API only; does not expand Kratos access.

`cors.kratosAdditionalOrigins`

Extra origins for Kratos only; does not expand application API access.

`auth`

Optional authentication UI, schema, cookie, callback and OIDC settings without runtime credentials.

`auth.uiOrigin`

External authentication UI; defaults to origins.app and does not add an nginx listener.

`auth.defaultBrowserReturnUrl`

Absolute HTTP(S) URL with an optional simple path; defaults to origins.app + ‘/’.

`auth.identitySchemas`

Optional nonempty list of project-relative identity schema files; omission uses builtin default/email-v1.

`auth.defaultSchemaId`

Identity-schema ID selected for registration; defaults to the first configured schema or builtin default.

`auth.cookie`

Shared auth cookie settings; defaults to secure persistent Lax at root path with a domain covering app/auth/UI/return hosts.

`auth.cookie.name`

Auth session cookie name; defaults to ory_kratos_session and special __Host-/__Secure- prefixes have additional constraints.

`auth.cookie.domain`

Optional shared cookie DNS domain; defaults to baseDomain and must cover app/auth/UI/return hosts while staying within baseDomain.

`auth.cookie.path`

Cookie path; defaults to / and defaults version 1 rejects other values.

`auth.cookie.sameSite`

Auth cookie cross-site policy; defaults to Lax. None requires secure true.

`auth.cookie.secure`

Auth cookie HTTPS-only flag; defaults to true and is required in production or with SameSite None.

`auth.cookie.persistent`

Whether auth cookies persist, or whether a workspace survives execution; cookie default is true and runtime workspace is always false.

`auth.ui`

Authentication UI flow paths or derived absolute URLs; no UI routes are deployed by resolution.

`auth.registrationHook`

Internal callback only; the host must supply hook authentication and business handling.

`auth.oidc`

Explicit opt-in; client ID and secret are host runtime bindings, never config values.

`auth.oidc.google`

Explicit Google OIDC provider configuration; credentials are separate host runtime bindings.

Example

See the owning declaration and linked feature guide for usage; no standalone example is documented in source.

[CLASS] `PlatformConfigError`

Expose a sanitized configuration issue without echoing secret values.

Imports: @alneas/eaos-core/platform/config.

Signature

declare class PlatformConfigError extends Error {
    readonly issues: readonly PlatformConfigIssue[];
    constructor(issue: PlatformConfigIssue);
}

Parameters

Name	Type	Required	Description
`issue`	`PlatformConfigIssue`	Yes	Failure path, category and safe human-readable explanation; do not include secrets in the message.

Returns

PlatformConfigError

Remarks

issues is a frozen one-element array containing a frozen copy of the issue.

Constructor contract

Public members

`issues`

Frozen one-element list containing a frozen copy of the sanitized validation issue.

Example

import { PlatformConfigError } from "@alneas/eaos-core/platform/config";
const error = new PlatformConfigError({ path: "config.appName", code: "invalid", message: "Expected a DNS label" });
console.log(error.issues[0].path);

[INTERFACE] `PlatformConfigIssue`

One sanitized configuration failure path, category and explanation.

Imports: @alneas/eaos-core/platform/config.

Signature

interface PlatformConfigIssue {
    path: string;
    code: 'type' | 'unknown_key' | 'invalid' | 'conflict';
    message: string;
}

Parameters

Name	Type	Required	Description
`path`	`string`	Yes	Normalized input/output location associated with a sanitized validation failure.
`code`	`'type' \| 'unknown_key' \| 'invalid' \| 'conflict'`	Yes	Sanitized validation category: type, unknown_key, invalid or conflict.
`message`	`string`	Yes	Human-readable provider/failure explanation; do not include secrets in surfaced diagnostics.

Returns

Type declaration; no runtime value.

Public members

`path`

Normalized input/output location associated with a sanitized validation failure.

`code`

Sanitized validation category: type, unknown_key, invalid or conflict.

`message`

Human-readable provider/failure explanation; do not include secrets in surfaced diagnostics.

Example

See the owning declaration and linked feature guide for usage; no standalone example is documented in source.

[TYPE] `PlatformConfigOverrides`

Optional top-level overrides applied after application configuration.

Imports: @alneas/eaos-core/platform/config.

Signature

type PlatformConfigOverrides = Partial<PlatformConfig>;

Parameters

Name	Type	Required	Description
—	—	—	No call parameters.

Returns

Type declaration; no runtime value.

Example

See the owning declaration and linked feature guide for usage; no standalone example is documented in source.

[INTERFACE] `PlatformContext`

Unified platform context. Passed to route handlers, plugin services, and MCP tool handlers.

Imports: @alneas/eaos-core, @alneas/eaos-core/adapters, @alneas/eaos-core/adapters/platform-context.

Signature

interface PlatformContext {
    db: DataAccessAdapter;
    storage: StorageAdapter;
    content?: ContentAdapter;
    events: DomainEventBus;
    secrets: SecretResolver;
    tenantId?: string;
    userId?: string;
    aiHostAdapters?: AIHostAdapters;
    services?: Record<string, any>;
}

Parameters

Name	Type	Required	Description
`db`	`DataAccessAdapter`	Yes	Database adapter (Oracle, Supabase, Neon, etc.)
`storage`	`StorageAdapter`	Yes	Object storage adapter (R2, S3, Local, etc.)
`content`	`ContentAdapter`	No	Content adapter for SSG (Git + Markdown, optional)
`events`	`DomainEventBus`	Yes	Domain event bus for pub/sub
`secrets`	`SecretResolver`	Yes	Secret resolver for credentials
`tenantId`	`string`	No	Current tenant ID
`userId`	`string`	No	Current user ID
`aiHostAdapters`	`AIHostAdapters`	No	Host-scoped external AI providers; credentials and implementations remain host-owned.
`services`	`Record<string, any>`	No	Optional plugin service container populated by the host; createPlatformContext does not initialize this field.

Returns

Type declaration; no runtime value.

Public members

`db`

Database adapter (Oracle, Supabase, Neon, etc.)

`storage`

Object storage adapter (R2, S3, Local, etc.)

`content`

Content adapter for SSG (Git + Markdown, optional)

`events`

Domain event bus for pub/sub

`secrets`

Secret resolver for credentials

`tenantId`

Current tenant ID

`userId`

Current user ID

`aiHostAdapters`

Host-scoped external AI providers; credentials and implementations remain host-owned.

`services`

Optional plugin service container populated by the host; createPlatformContext does not initialize this field.

Example

See the owning declaration and linked feature guide for usage; no standalone example is documented in source.

[INTERFACE] `PlatformContextConfig`

Configuration for creating a PlatformContext.

Imports: @alneas/eaos-core, @alneas/eaos-core/adapters, @alneas/eaos-core/adapters/platform-context.

Signature

interface PlatformContextConfig {
    db: DataAccessAdapter;
    storage: StorageAdapter;
    content?: ContentAdapter;
    events?: DomainEventBus;
    secrets?: SecretResolver;
    tenantId?: string;
    userId?: string;
    aiHostAdapters?: AIHostAdapters;
}

Parameters

Name	Type	Required	Description
`db`	`DataAccessAdapter`	Yes	Database adapter instance
`storage`	`StorageAdapter`	Yes	Storage adapter instance
`content`	`ContentAdapter`	No	Content adapter instance (optional)
`events`	`DomainEventBus`	No	Domain event bus (optional, creates a context-local bus if omitted)
`secrets`	`SecretResolver`	No	Secret resolver override; omission uses the static SecretResolver class and its shared cache.
`tenantId`	`string`	No	Current tenant ID
`userId`	`string`	No	Current user ID
`aiHostAdapters`	`AIHostAdapters`	No	Already-scoped Host adapters for calendar, email, workspace, travel, browser, messaging or workflow operations.

Returns

Type declaration; no runtime value.

Public members

`db`

Database adapter instance

`storage`

Storage adapter instance

`content`

Content adapter instance (optional)

`events`

Domain event bus (optional, creates a context-local bus if omitted)

`secrets`

Secret resolver override; omission uses the static SecretResolver class and its shared cache.

`tenantId`

Current tenant ID

`userId`

Current user ID

`aiHostAdapters`

Already-scoped Host adapters for calendar, email, workspace, travel, browser, messaging or workflow operations.

Example

See the owning declaration and linked feature guide for usage; no standalone example is documented in source.

[INTERFACE] `PlatformPrincipal`

Host-verified tenant/user identity with role and optional API scope claims.

Imports: @alneas/eaos-core, @alneas/eaos-core/security/platform-security.

Signature

interface PlatformPrincipal {
    userId: string;
    tenantId: string;
    roles: readonly string[];
    scopes?: readonly string[];
}

Parameters

Name	Type	Required	Description
`userId`	`string`	Yes	User identity within the tenant supplied by the trusted host.
`tenantId`	`string`	Yes	Verified tenant boundary for the record or operation; host authorization must establish this scope.
`roles`	`readonly string[]`	Yes	Role claims supplied by the host after identity verification.
`scopes`	`readonly string[]`	No	Exact API permission scope names associated with the verified identity/key.

Returns

Type declaration; no runtime value.

Public members

`userId`

User identity within the tenant supplied by the trusted host.

`tenantId`

Verified tenant boundary for the record or operation; host authorization must establish this scope.

`roles`

Role claims supplied by the host after identity verification.

`scopes`

Exact API permission scope names associated with the verified identity/key.

Example

See the owning declaration and linked feature guide for usage; no standalone example is documented in source.

[CONSTANT] `platformRecordsContract`

Canonical public platform envelope. Historical migration identities are unchanged.

Imports: @alneas/eaos-core/contracts/platform-records.

Signature

declare const platformRecordsContract: Readonly<DataContract>;

Parameters

Name	Type	Required	Description
—	—	—	No call parameters.

Returns

Declared constant value.

Example

See the owning declaration and linked feature guide for usage; no standalone example is documented in source.

[INTERFACE] `PluginArchivePolicy`

Archive strategy and required delay for modes other than none.

Imports: @alneas/eaos-core/plugin-sdk, @alneas/eaos-core/plugin-sdk/storage-policy.

Signature

interface PluginArchivePolicy {
    mode: ArchiveMode;
    afterDays?: number;
}

Parameters

Name	Type	Required	Description
`mode`	`ArchiveMode`	Yes	Selected operation/storage/execution variant; the owning discriminated union determines applicable fields.
`afterDays`	`number`	No	Required for every mode except none.

Returns

Type declaration; no runtime value.

Public members

`mode`

Selected operation/storage/execution variant; the owning discriminated union determines applicable fields.

`afterDays`

Required for every mode except none.

Example

See the owning declaration and linked feature guide for usage; no standalone example is documented in source.

[TYPE] `PluginBundleCatalog`

A catalog of user-facing bundles. The values stay ordered for install and removal.

Imports: @alneas/eaos-core, @alneas/eaos-core/plugin-bundles.

Signature

type PluginBundleCatalog<T extends BundlePlugin = BundlePlugin> = Readonly<Record<string, readonly T[]>>;

Parameters

Name	Type	Required	Description
—	—	—	No call parameters.

Returns

Type declaration; no runtime value.

Type parameters

T: Plugin-shaped values extending BundlePlugin; defaults to BundlePlugin.

Example

See the owning declaration and linked feature guide for usage; no standalone example is documented in source.

[INTERFACE] `PluginContext`

Admitted plugin identity and host-scoped capabilities provided to route handlers.

Imports: @alneas/eaos-core, @alneas/eaos-core/plugin-sdk, @alneas/eaos-core/plugin-sdk/define-plugin.

Signature

interface PluginContext<TServices = Record<string, unknown>> {
    readonly pluginId: string;
    readonly principal: Readonly<PlatformPrincipal> & {
        readonly entitlements: TenantEntitlements | null;
    };
    readonly db: DataAccessAdapter;
    readonly storage: StorageAdapter;
    readonly secrets: {
        get(key: string): Promise<string>;
    };
    readonly jobs: {
        enqueue(name: string, input: unknown): Promise<string>;
    };
    readonly webhooks: {
        verify(name: string, request: Request): Promise<boolean>;
    };
    readonly audit: {
        record(action: string, metadata: Readonly<Record<string, unknown>>): Promise<void>;
    };
    readonly services: TServices;
}

Parameters

Name	Type	Required	Description
`pluginId`	`string`	Yes	Owning plugin identity used for capability scope and discovery.
`principal`	`Readonly<PlatformPrincipal> & { readonly entitlements: TenantEntitlements \| null; }`	Yes	Readonly host-verified user/tenant role claims plus live subscription snapshot for an admitted plugin request.
`db`	`DataAccessAdapter`	Yes	Host-scoped app-core adapter; table/resource permissions are checked on each operation.
`storage`	`StorageAdapter`	Yes	Scoped app-core storage adapter, supplied through createTenantStorage.
`secrets`	`{ get(key: string): Promise<string>; }`	Yes	Host secret capability or declarations; Core does not provision an external secret store.
`jobs`	`{ enqueue(name: string, input: unknown): Promise<string>; }`	Yes	Host-scoped job enqueue capability returning the accepted job identity.
`webhooks`	`{ verify(name: string, request: Request): Promise<boolean>; }`	Yes	Host-scoped inbound verification capability; provider authentication/freshness policy remains host-owned.
`audit`	`{ record(action: string, metadata: Readonly<Record<string, unknown>>): Promise<void>; }`	Yes	Host-scoped durable audit capability; handlers await record completion when audit durability is required.
`services`	`TServices`	Yes	Host-scoped typed service container supplied only after plugin admission.

Returns

Type declaration; no runtime value.

Type parameters

TServices: Host services available to admitted route handlers; defaults to a record of unknown values.

Public members

`pluginId`

Owning plugin identity used for capability scope and discovery.

`principal`

Readonly host-verified user/tenant role claims plus live subscription snapshot for an admitted plugin request.

`principal.entitlements`

Trusted tenant subscription snapshot, or null when unavailable; callers must not derive authorization from browser state.

`db`

Host-scoped app-core adapter; table/resource permissions are checked on each operation.

`storage`

Scoped app-core storage adapter, supplied through createTenantStorage.

`secrets`

Host secret capability or declarations; Core does not provision an external secret store.

`secrets.get`

Resolve a secret through the admitted plugin host scope.

Parameters:

key: Host-approved secret lookup key.

Returns: Resolved secret text; callers must not log or expose it.

Remarks

Requires an admitted, connected host PluginContext. Host owns tenant access, persistence, deadlines, retries and capability cleanup.

Errors and rejections

Host capability errors reject; persistence/effect failures can have uncertain outcomes.

Example:

import type { PluginContext } from "@alneas/eaos-core/plugin-sdk/define-plugin";
async function readHostSecret(ctx: PluginContext) { return ctx.secrets.get("service-key"); }

`jobs`

Host-scoped job enqueue capability returning the accepted job identity.

`jobs.enqueue`

Enqueue a host job under admitted plugin scope.

Parameters:

name: Registered host job identity.
input: Domain job input validated by the host.

Returns: Accepted host job identity; enqueue completion is not job execution completion.

Remarks

Requires an admitted, connected host PluginContext. Host owns tenant access, persistence, deadlines, retries and capability cleanup.

Errors and rejections

Host capability errors reject; persistence/effect failures can have uncertain outcomes.

Example:

import type { PluginContext } from "@alneas/eaos-core/plugin-sdk/define-plugin";
async function queueHostJob(ctx: PluginContext) { return ctx.jobs.enqueue("review", { documentId: "document-1" }); }

`webhooks`

Host-scoped inbound verification capability; provider authentication/freshness policy remains host-owned.

`webhooks.verify`

Verify an inbound webhook through the scoped host provider.

Parameters:

name: Registered host webhook verifier identity.
request: Original inbound Request; host owns body-reading and signature/freshness policy.

Returns: Whether host webhook verification succeeds.

Remarks

Requires an admitted, connected host PluginContext. Host owns tenant access, persistence, deadlines, retries and capability cleanup.

Errors and rejections

Host capability errors reject; persistence/effect failures can have uncertain outcomes.

Example:

import type { PluginContext } from "@alneas/eaos-core/plugin-sdk/define-plugin";
async function verifyHostWebhook(ctx: PluginContext, request: Request) { return ctx.webhooks.verify("provider", request); }

`audit`

Host-scoped durable audit capability; handlers await record completion when audit durability is required.

`audit.record`

Append a plugin audit action through the scoped host capability.

Parameters:

action: Host-recognized action identity.
metadata: Readonly sanitized contextual metadata; exclude credentials and sensitive bodies.

Returns: No value; the host audit append has completed.

Remarks

Requires an admitted, connected host PluginContext. Host owns tenant access, persistence, deadlines, retries and capability cleanup.

Errors and rejections

Host capability errors reject; persistence/effect failures can have uncertain outcomes.

Example:

import type { PluginContext } from "@alneas/eaos-core/plugin-sdk/define-plugin";
async function recordHostAudit(ctx: PluginContext) { await ctx.audit.record("notes.preview", { count: 0 }); }

`services`

Host-scoped typed service container supplied only after plugin admission.

Example

See the owning declaration and linked feature guide for usage; no standalone example is documented in source.

[INTERFACE] `PluginContractSnapshot`

Plugin version and ordered tool contracts captured for compatibility review.

Imports: @alneas/eaos-core, @alneas/eaos-core/plugin-sdk, @alneas/eaos-core/plugin-sdk/contract-compatibility.

Signature

interface PluginContractSnapshot {
    pluginId: string;
    pluginVersion: string;
    tools: ToolContractSnapshot[];
    hash: string;
}

Parameters

Name	Type	Required	Description
`pluginId`	`string`	Yes	Owning plugin identity used for capability scope and discovery.
`pluginVersion`	`string`	Yes	Version of the plugin represented by the captured contract snapshot.
`tools`	`ToolContractSnapshot[]`	Yes	Ordered tool definitions used for discovery/compatibility; declaration does not execute them.
`hash`	`string`	Yes	Content integrity digest; hashes are unkeyed and do not establish authorization or writer authenticity.

Returns

Type declaration; no runtime value.

Public members

`pluginId`

Owning plugin identity used for capability scope and discovery.

`pluginVersion`

Version of the plugin represented by the captured contract snapshot.

`tools`

Ordered tool definitions used for discovery/compatibility; declaration does not execute them.

`hash`

Content integrity digest; hashes are unkeyed and do not establish authorization or writer authenticity.

Example

See the owning declaration and linked feature guide for usage; no standalone example is documented in source.

[INTERFACE] `PluginDefinition`

Input metadata and synchronous route-registration callback for definePlugin.

Imports: @alneas/eaos-core, @alneas/eaos-core/plugin-sdk, @alneas/eaos-core/plugin-sdk/define-plugin.

Signature

interface PluginDefinition<TServices = Record<string, unknown>> {
    id: string;
    version?: string;
    entitlement?: PluginEntitlement;
    schemaDependencies?: Readonly<Record<string, string>>;
    routes: (router: PluginRouteBuilder<TServices>) => void;
}

Parameters

Name	Type	Required	Description
`id`	`string`	Yes	Lowercase plugin ID beginning with a letter, followed by letters/digits/hyphens, at most 128 characters.
`version`	`string`	No	Optional plugin release version; definePlugin defaults it to 0.0.0.
`entitlement`	`PluginEntitlement`	No	Optional declared subscription/allowlist/metering policy; the server must enforce live admission.
`schemaDependencies`	`Readonly<Record<string, string>>`	No	Required data-contract IDs mapped to accepted semver ranges.
`routes`	`(router: PluginRouteBuilder<TServices>) => void`	Yes	Register routes synchronously while definePlugin collects the definition.

Returns

Type declaration; no runtime value.

Type parameters

TServices: Host service container exposed to registered handlers; default record of unknown values.

Public members

`id`

Lowercase plugin ID beginning with a letter, followed by letters/digits/hyphens, at most 128 characters.

`version`

Optional plugin release version; definePlugin defaults it to 0.0.0.

`entitlement`

Optional declared subscription/allowlist/metering policy; the server must enforce live admission.

`schemaDependencies`

Required data-contract IDs mapped to accepted semver ranges.

`routes`

Parameters:

router: Temporary builder; add method/path/handler entries during this call.

Returns: No value; definePlugin freezes the collected route list after this callback returns.

Errors and rejections

Registration errors propagate from definePlugin; asynchronous callbacks are not awaited.

Example

See the owning declaration and linked feature guide for usage; no standalone example is documented in source.

[INTERFACE] `PluginDocConfig`

Paths and searchable help metadata for plugin documentation.

Imports: @alneas/eaos-core, @alneas/eaos-core/plugin-sdk, @alneas/eaos-core/plugin-sdk/types.

Signature

interface PluginDocConfig {
    category?: string;
    specPath?: string;
    userGuidePath?: string;
    maintainerGuidePath?: string;
    helpContexts?: Record<string, HelpContextItem>;
    faq?: Array<{
        question: string;
        answer: string;
    }>;
}

Parameters

Name	Type	Required	Description
`category`	`string`	No	Optional host documentation navigation/search category.
`specPath`	`string`	No	Optional plugin technical specification path.
`userGuidePath`	`string`	No	Optional plugin user-guide path.
`maintainerGuidePath`	`string`	No	Optional plugin maintenance-guide path.
`helpContexts`	`Record<string, HelpContextItem>`	No	Context-keyed help entries used for discovery and search.
`faq`	`Array<{ question: string; answer: string; }>`	No	Optional question/answer entries for host help UI.

Returns

Type declaration; no runtime value.

Public members

`category`

Optional host documentation navigation/search category.

`specPath`

Optional plugin technical specification path.

`userGuidePath`

Optional plugin user-guide path.

`maintainerGuidePath`

Optional plugin maintenance-guide path.

`helpContexts`

Context-keyed help entries used for discovery and search.

`faq`

Optional question/answer entries for host help UI.

`faq[].question`

User-facing FAQ question text.

`faq[].answer`

User-facing FAQ answer text.

Example

See the owning declaration and linked feature guide for usage; no standalone example is documented in source.

[INTERFACE] `PluginEntitlement`

Plugin subscription, tenant allowlist and optional metering requirements.

Imports: @alneas/eaos-core, @alneas/eaos-core/plugin-sdk, @alneas/eaos-core/entitlements.

Signature

interface PluginEntitlement {
    tier: PluginTier;
    addonId?: string;
    allowedTenants?: readonly string[];
    metering?: {
        unit: string;
        defaultMonthlyQuota: number;
    };
}

Parameters

Name	Type	Required	Description
`tier`	`PluginTier`	Yes	Commercial entitlement category or model resource tier, interpreted by its owning policy.
`addonId`	`string`	No	Optional subscription addon identity; required for pro plugin policies.
`allowedTenants`	`readonly string[]`	No	Optional explicit tenant allowlist; corporate policies require a nonempty list.
`metering`	`{ unit: string; defaultMonthlyQuota: number; }`	No	Optional usage unit and nonnegative default monthly quota; admission preview does not measure/consume usage.

Returns

Type declaration; no runtime value.

Public members

`tier`

Commercial entitlement category or model resource tier, interpreted by its owning policy.

`addonId`

Optional subscription addon identity; required for pro plugin policies.

`allowedTenants`

Optional explicit tenant allowlist; corporate policies require a nonempty list.

`metering`

Optional usage unit and nonnegative default monthly quota; admission preview does not measure/consume usage.

`metering.unit`

Metered usage-unit identifier validated as a bounded entitlement identifier.

`metering.defaultMonthlyQuota`

Nonnegative safe-integer quota used when no tenant override exists.

Example

See the owning declaration and linked feature guide for usage; no standalone example is documented in source.

[INTERFACE] `PluginExtensionConfig`

Describe an optional industry or tenant extension and its private schema ownership.

Imports: @alneas/eaos-core, @alneas/eaos-core/plugin-sdk, @alneas/eaos-core/plugin-sdk/types.

Signature

interface PluginExtensionConfig {
    id: string;
    name: string;
    industry?: string;
    schema?: {
        ownedTables: string[];
        externalReferences?: Record<string, string[]>;
    };
}

Parameters

Name	Type	Required	Description
`id`	`string`	Yes	Host extension identity distinct from the owning plugin ID.
`name`	`string`	Yes	Human-readable display name supplied by the plugin/provider catalog; distinct from the stable ID.
`industry`	`string`	No	Optional industry classification for an extension.
`schema`	`{ ownedTables: string[]; externalReferences?: Record<string, string[]>; }`	No	JSON Schema defining owned table/document structure; schema declarations do not apply migrations by themselves.

Returns

Type declaration; no runtime value.

Public members

`id`

Host extension identity distinct from the owning plugin ID.

`name`

Human-readable display name supplied by the plugin/provider catalog; distinct from the stable ID.

`industry`

Optional industry classification for an extension.

`schema`

JSON Schema defining owned table/document structure; schema declarations do not apply migrations by themselves.

`schema.ownedTables`

Legacy plugin/extension-owned tables; shared table ownership belongs to data contracts.

`schema.externalReferences`

Referenced table/resource names grouped by owning external component.

Example

See the owning declaration and linked feature guide for usage; no standalone example is documented in source.

[INTERFACE] `PluginI18nConfig`

Locale resources and optional default locale supplied by a plugin.

Imports: @alneas/eaos-core, @alneas/eaos-core/plugin-sdk, @alneas/eaos-core/plugin-sdk/types.

Signature

interface PluginI18nConfig {
    defaultLocale?: string;
    resources: Record<string, Record<string, any>>;
}

Parameters

Name	Type	Required	Description
`defaultLocale`	`string`	No	Optional default locale chosen by host internationalization integration.
`resources`	`Record<string, Record<string, any>>`	Yes	Locale-keyed translation resources consumed by the host i18n layer.

Returns

Type declaration; no runtime value.

Public members

`defaultLocale`

Optional default locale chosen by host internationalization integration.

`resources`

Locale-keyed translation resources consumed by the host i18n layer.

Example

See the owning declaration and linked feature guide for usage; no standalone example is documented in source.

[INTERFACE] `PluginManifest`

Plugin discovery, compatibility, schema, integration and UI metadata consumed by a host.

Imports: @alneas/eaos-core, @alneas/eaos-core/plugin-sdk, @alneas/eaos-core/plugin-sdk/types.

Signature

interface PluginManifest {
    entitlement?: PluginEntitlement;
    id: string;
    name: string;
    version: string;
    description: string;
    icon: string;
    category: string;
    recommended?: boolean;
    targets: ClientTarget[];
    dependencies: string[];
    optionalDependencies?: string[];
    tier: 'public' | 'standard' | 'pro' | 'corporate' | 'free' | 'premium';
    industries: string[];
    contracts: string[];
    subscribes: string[];
    publishes: string[];
    navigation: TargetNavigationConfig;
    schema: SchemaConfig;
    extensions?: PluginExtensionConfig[];
    api: ApiConfig;
    secrets?: PluginSecretRequirement[];
    settings?: PluginSettingConfig[];
    mcp?: McpConfig;
    agentCapabilities?: AgentCapabilitiesConfig;
    i18n?: PluginI18nConfig;
    docs?: PluginDocConfig;
    goExtension?: GoExtensionConfig;
    createRoutes?: (options?: any) => any;
}

Parameters

Name	Type	Required	Description
`entitlement`	`PluginEntitlement`	No	Explicit commercial policy; hosts must provide live admission for declared policies.
`id`	`string`	Yes	Unique plugin registration identity; used as the registry lookup key.
`name`	`string`	Yes	Human-readable display name supplied by the plugin/provider catalog; distinct from the stable ID.
`version`	`string`	Yes	Plugin release version used by host discovery and contract snapshots.
`description`	`string`	Yes	Human-readable metadata describing the capability, workflow node or requirement to host users.
`icon`	`string`	Yes	Host UI icon identifier for displaying the plugin/navigation item.
`category`	`string`	Yes	Host plugin discovery category.
`recommended`	`boolean`	No	Optional host discovery recommendation hint.
`targets`	`ClientTarget[]`	Yes	Supported client channels advertised by the plugin.
`dependencies`	`string[]`	Yes	Declared prerequisites; shared data contracts use ID-to-semver ranges and plugin/skill metadata uses identity lists.
`optionalDependencies`	`string[]`	No	Optional plugin dependencies that need not be present for discovery.
`tier`	`'public' \| 'standard' \| 'pro' \| 'corporate' \| 'free' \| 'premium'`	Yes	Commercial entitlement category or model resource tier, interpreted by its owning policy.
`industries`	`string[]`	Yes	Industry classifications used by host plugin discovery.
`contracts`	`string[]`	Yes	Host discovery/compatibility labels advertised by this plugin; these do not install shared data contracts.
`subscribes`	`string[]`	Yes	Domain event names the plugin declares it consumes.
`publishes`	`string[]`	Yes	Domain event names the plugin declares it emits.
`navigation`	`TargetNavigationConfig`	Yes	Per-client plugin navigation metadata.
`schema`	`SchemaConfig`	Yes	JSON Schema defining owned table/document structure; schema declarations do not apply migrations by themselves.
`extensions`	`PluginExtensionConfig[]`	No	Optional industry/tenant extension definitions.
`api`	`ApiConfig`	Yes	API mount metadata or derived backend routing; host renders and enforces these routes.
`secrets`	`PluginSecretRequirement[]`	No	Host secret capability or declarations; Core does not provision an external secret store.
`settings`	`PluginSettingConfig[]`	No	Optional plugin settings fields exposed to host configuration UI.
`mcp`	`McpConfig`	No	Optional host-executed MCP tool catalog.
`agentCapabilities`	`AgentCapabilitiesConfig`	No	Optional agent/skill/browser-tool discovery metadata and gatekeeper policies.
`i18n`	`PluginI18nConfig`	No	Optional plugin translation resources and default locale.
`docs`	`PluginDocConfig`	No	Optional plugin documentation paths and contextual help metadata.
`goExtension`	`GoExtensionConfig`	No	Optional Go handler build metadata.
`createRoutes`	`(options?: any) => any`	No	Optional host route factory used when mounting backend routes.

Returns

Type declaration; no runtime value.

Public members

`entitlement`

Explicit commercial policy; hosts must provide live admission for declared policies.

`id`

Unique plugin registration identity; used as the registry lookup key.

`name`

Human-readable display name supplied by the plugin/provider catalog; distinct from the stable ID.

`version`

Plugin release version used by host discovery and contract snapshots.

`description`

Human-readable metadata describing the capability, workflow node or requirement to host users.

`icon`

Host UI icon identifier for displaying the plugin/navigation item.

`category`

Host plugin discovery category.

`recommended`

Optional host discovery recommendation hint.

`targets`

Supported client channels advertised by the plugin.

`dependencies`

Declared prerequisites; shared data contracts use ID-to-semver ranges and plugin/skill metadata uses identity lists.

`optionalDependencies`

Optional plugin dependencies that need not be present for discovery.

`tier`

Commercial entitlement category or model resource tier, interpreted by its owning policy.

`industries`

Industry classifications used by host plugin discovery.

`contracts`

Host discovery/compatibility labels advertised by this plugin; these do not install shared data contracts.

`subscribes`

Domain event names the plugin declares it consumes.

`publishes`

Domain event names the plugin declares it emits.

`navigation`

Per-client plugin navigation metadata.

`schema`

JSON Schema defining owned table/document structure; schema declarations do not apply migrations by themselves.

`extensions`

Optional industry/tenant extension definitions.

`api`

API mount metadata or derived backend routing; host renders and enforces these routes.

`secrets`

Host secret capability or declarations; Core does not provision an external secret store.

`settings`

Optional plugin settings fields exposed to host configuration UI.

`mcp`

Optional host-executed MCP tool catalog.

`agentCapabilities`

Optional agent/skill/browser-tool discovery metadata and gatekeeper policies.

`i18n`

Optional plugin translation resources and default locale.

`docs`

Optional plugin documentation paths and contextual help metadata.

`goExtension`

Optional Go handler build metadata.

`createRoutes`

Optional host route factory used when mounting backend routes.

Parameters:

options: Host-specific route construction options; this manifest does not validate their shape.

Returns: Host router/application value interpreted by the consuming server.

Remarks

Declaring this callback does not mount or authorize routes; the server owns lifecycle and live admission.

Errors and rejections

Host factory errors propagate to its caller.

Example

See the owning declaration and linked feature guide for usage; no standalone example is documented in source.

[INTERFACE] `PluginMigration`

Ordered SQL statements for a plugin or shared data-contract migration, separated by driver and execution scope.

Imports: @alneas/eaos-core, @alneas/eaos-core/migration-types.

Signature

interface PluginMigration {
    id: string;
    scope: 'database' | 'tenant';
    sql: Partial<Record<'sqlite' | 'oracle' | 'postgres', string[]>>;
}

Parameters

Name	Type	Required	Description
`id`	`string`	Yes	Stable historical migration-ledger identity; validated contract sources require unique IDs.
`scope`	`'database' \| 'tenant'`	Yes	Whether the host applies this migration once per database or within each tenant scope.
`sql`	`Partial<Record<'sqlite' \| 'oracle' \| 'postgres', string[]>>`	Yes	Driver-keyed ordered SQL statements; hosts select a supported driver and own execution transactions.

Returns

Type declaration; no runtime value.

Public members

`id`

Stable historical migration-ledger identity; validated contract sources require unique IDs.

`scope`

Whether the host applies this migration once per database or within each tenant scope.

`sql`

Driver-keyed ordered SQL statements; hosts select a supported driver and own execution transactions.

Example

See the owning declaration and linked feature guide for usage; no standalone example is documented in source.

[CLASS] `PluginRegistry`

Keep plugin manifests in memory and expose discovery, tools, skills and help metadata.

Imports: @alneas/eaos-core, @alneas/eaos-core/plugin-sdk, @alneas/eaos-core/plugin-sdk/registry.

Signature

declare class PluginRegistry {
    register(manifest: PluginManifest): void;
    get(id: string): PluginManifest | undefined;
    getAll(): PluginManifest[];
    getByTarget(target: ClientTarget): PluginManifest[];
    getSortedByMigrationOrder(): PluginManifest[];
    getAllMcpTools(): McpToolDefinition[];
    getAllAgentSkills(): Array<{
        pluginId: string;
        skill: SkillCatalogEntry;
    }>;
    getEligibleAgentSkills(availability: SkillRuntimeAvailability): Array<{
        pluginId: string;
        skill: SkillCatalogEntry;
    }>;
    getEligibleAgentSkillDocuments(availability: SkillRuntimeAvailability, loader: SkillDocumentLoader): Promise<SkillDocument[]>;
    getMcpTool(toolName: string): McpToolDefinition | undefined;
    getHelpContext(contextKey: string): {
        pluginId: string;
        item: HelpContextItem;
    } | undefined;
    getAllHelpContexts(): Array<{
        pluginId: string;
        contextKey: string;
        item: HelpContextItem;
    }>;
}

Parameters

Name	Type	Required	Description
—	—	—	No call parameters.

Returns

PluginRegistry

Remarks

Manifests and returned objects are stored by reference; no activation, persistence or tenant authorization occurs. Skill body loading is delegated to the host.

Public members

`register`

Validate entitlement/tier consistency and register a unique plugin ID.

Parameters:

manifest: Manifest stored by reference; commercial tiers require matching entitlement policies.

Returns: No value; the plugin is registered.

Remarks

Does not validate every manifest field or activate plugin capabilities.

Errors and rejections

Error for invalid entitlement, mismatched tier or duplicate plugin ID.

Example:

import { PluginRegistry } from "@alneas/eaos-core/plugin-sdk/registry";
import type { PluginManifest } from "@alneas/eaos-core/plugin-sdk/types";
function registerHostManifest(manifest: PluginManifest) {
 const registry = new PluginRegistry();
 registry.register(manifest);
 return registry;
}

`get`

Find a registered manifest by its exact plugin ID.

Parameters:

id: Plugin registration key.

Returns: Original manifest reference, or undefined when absent.

Example:

import { PluginRegistry } from "@alneas/eaos-core/plugin-sdk/registry";
const registry = new PluginRegistry();
console.log(registry.get("notes")); // undefined

`getAll`

List registered manifests in registration order.

Returns: New array containing original manifest references; empty for a fresh registry.

Example:

import { PluginRegistry } from "@alneas/eaos-core/plugin-sdk/registry";
const registry = new PluginRegistry();
console.log(registry.getAll()); // []

`getByTarget`

Select manifests advertising one client channel.

Parameters:

target: Client channel to match against each manifest targets array.

Returns: New array of original manifest references in registration order.

Example:

import { PluginRegistry } from "@alneas/eaos-core/plugin-sdk/registry";
const registry = new PluginRegistry();
console.log(registry.getByTarget("web")); // []

`getSortedByMigrationOrder`

Sort registered manifests by ascending schema migration order.

Returns: New array of original manifest references sorted by schema.migrationOrder.

Example:

import { PluginRegistry } from "@alneas/eaos-core/plugin-sdk/registry";
const registry = new PluginRegistry();
console.log(registry.getSortedByMigrationOrder()); // []

`getAllMcpTools`

Collect tools from every registered manifest in registration order.

Returns: New array of original MCP tool references; empty when none are declared.

Example:

import { PluginRegistry } from "@alneas/eaos-core/plugin-sdk/registry";
const registry = new PluginRegistry();
console.log(registry.getAllMcpTools()); // []

`getAllAgentSkills`

Collect registered plugin skill metadata without loading or executing instructions.

Returns: New pluginId/skill pairs containing original skill references.

Example:

import { PluginRegistry } from "@alneas/eaos-core/plugin-sdk/registry";
const registry = new PluginRegistry();
console.log(registry.getAllAgentSkills()); // []

`getAllAgentSkills[].pluginId`

Owning plugin identity used for capability scope and discovery.

`getAllAgentSkills[].skill`

Original catalog metadata associated with the loaded/discovered skill.

`getEligibleAgentSkills`

Filter discovered skill metadata using trusted host availability.

Parameters:

availability: Host OS, binaries, environment/config names and adapters; no process state is read.

Returns: New pluginId/skill pairs for eligible skills in discovery order.

Example:

import { PluginRegistry } from "@alneas/eaos-core/plugin-sdk/registry";
const registry = new PluginRegistry();
console.log(registry.getEligibleAgentSkills({ os: "linux" })); // []

`getEligibleAgentSkills[].pluginId`

Owning plugin identity used for capability scope and discovery.

`getEligibleAgentSkills[].skill`

Original catalog metadata associated with the loaded/discovered skill.

`getEligibleAgentSkillDocuments`

Load eligible skill instruction bodies concurrently through a host package loader.

Parameters:

availability: Trusted facts used to filter skill prerequisites before loading.
loader: Host callback receiving plugin ID, safe relative path and metadata; return nonblank instruction text synchronously or asynchronously.

Returns: Loaded documents in eligibility order, including original skill references and instruction text; empty when none qualify.

Remarks

Starts all eligible loads with Promise.all; rejection does not cancel other loads. Omitted documentPath derives skills//SKILL.md. The loader owns package resolution and access checks.

Errors and rejections

Rejects for unsafe paths, empty/nonstring content or propagated loader failures.

Example:

import { PluginRegistry } from "@alneas/eaos-core/plugin-sdk/registry";
import type { SkillDocumentLoader } from "@alneas/eaos-core/ai/governance";
async function loadHostSkills(loader: SkillDocumentLoader) {
 const registry = new PluginRegistry();
 return registry.getEligibleAgentSkillDocuments({ os: "linux" }, loader);
}

`getMcpTool`

Find the first registered tool with an exact name match.

Parameters:

toolName: MCP tool identity to locate across manifests in registration order.

Returns: Original tool reference or undefined when no match exists.

Example:

import { PluginRegistry } from "@alneas/eaos-core/plugin-sdk/registry";
const registry = new PluginRegistry();
console.log(registry.getMcpTool("notes.list")); // undefined

`getHelpContext`

Resolve the first matching contextual-help entry across registered plugins.

Parameters:

contextKey: Exact help key, or a plugin ID followed by dot/colon and a local help key.

Returns: Owning plugin ID and original help item reference, or undefined.

Example:

import { PluginRegistry } from "@alneas/eaos-core/plugin-sdk/registry";
const registry = new PluginRegistry();
console.log(registry.getHelpContext("notes:overview")); // undefined

`getHelpContext.pluginId`

Owning plugin identity used for capability scope and discovery.

`getHelpContext.item`

Original contextual-help item returned by registry discovery; mutating it affects the registered manifest.

`getAllHelpContexts`

Flatten contextual help entries for search and indexing.

Returns: New pluginId/contextKey/item records containing original help references.

Example:

import { PluginRegistry } from "@alneas/eaos-core/plugin-sdk/registry";
const registry = new PluginRegistry();
console.log(registry.getAllHelpContexts()); // []

`getAllHelpContexts[].pluginId`

Owning plugin identity used for capability scope and discovery.

`getAllHelpContexts[].contextKey`

Exact contextual-help lookup key, optionally prefixed by plugin ID and dot/colon.

`getAllHelpContexts[].item`

Original contextual-help item returned by registry discovery; mutating it affects the registered manifest.

Example

import { PluginRegistry } from "@alneas/eaos-core/plugin-sdk/registry";
const registry = new PluginRegistry();
console.log(registry.getAll()); // []

[INTERFACE] `PluginRoute`

One captured HTTP method, plugin-relative path and handler.

Imports: @alneas/eaos-core, @alneas/eaos-core/plugin-sdk, @alneas/eaos-core/plugin-sdk/define-plugin.

Signature

interface PluginRoute {
    method: 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';
    path: string;
    handler: PluginRouteHandler<any, any>;
}

Parameters

Name	Type	Required	Description
`method`	`'GET' \| 'POST' \| 'PUT' \| 'PATCH' \| 'DELETE'`	Yes	HTTP method captured during synchronous route registration.
`path`	`string`	Yes	Plugin-relative URL path; allows simple alphanumeric/underscore/colon/hyphen segments without query strings.
`handler`	`PluginRouteHandler<any, any>`	Yes	Captured route callback retained for later admitted host dispatch.

Returns

Type declaration; no runtime value.

Public members

`method`

HTTP method captured during synchronous route registration.

`path`

Plugin-relative URL path; allows simple alphanumeric/underscore/colon/hyphen segments without query strings.

`handler`

Captured route callback retained for later admitted host dispatch.

Parameters:

ctx: Host-scoped plugin capabilities installed after admission.
input: Decoded route input validated by the host/handler.

Returns: Domain response directly or asynchronously; the host decides serialization.

Example

See the owning declaration and linked feature guide for usage; no standalone example is documented in source.

[INTERFACE] `PluginRouteBuilder`

Synchronous registration surface for plugin HTTP routes.

Imports: @alneas/eaos-core, @alneas/eaos-core/plugin-sdk, @alneas/eaos-core/plugin-sdk/define-plugin.

Signature

interface PluginRouteBuilder<TServices = Record<string, unknown>> {
    get<T = unknown>(path: string, handler: PluginRouteHandler<T, TServices>): void;
    post<T = unknown>(path: string, handler: PluginRouteHandler<T, TServices>): void;
    put<T = unknown>(path: string, handler: PluginRouteHandler<T, TServices>): void;
    patch<T = unknown>(path: string, handler: PluginRouteHandler<T, TServices>): void;
    delete<T = unknown>(path: string, handler: PluginRouteHandler<T, TServices>): void;
}

Parameters

Name	Type	Required	Description
`get`	`void`	Yes	Register a GET route during synchronous plugin definition.
`post`	`void`	Yes	Register a POST route during synchronous plugin definition.
`put`	`void`	Yes	Register a PUT route during synchronous plugin definition.
`patch`	`void`	Yes	Register a PATCH route during synchronous plugin definition.
`delete`	`void`	Yes	Register a DELETE route during synchronous plugin definition.

Returns

Type declaration; no runtime value.

Type parameters

TServices: Host service container shared by registered handlers; default record of unknown values.

Public members

`get`

Parameters:

path: Plugin-relative path with simple alphanumeric/underscore/colon/hyphen segments; duplicate method/path pairs are rejected.
handler: Callback retained until host dispatch; receives admitted context and decoded input, returns a response or Promise. Not invoked during registration.

Returns: No value; the route is collected and later frozen by definePlugin.

Type parameters

T: Decoded request input shape expected by the handler; defaults to unknown and requires host validation.

Remarks

The builder is supplied only while definePlugin runs; host mounting, input validation and handler authorization are separate.

Errors and rejections

Error for invalid path/nonfunction handler or duplicate method/path.

Example:

import { definePlugin } from "@alneas/eaos-core/plugin-sdk/define-plugin";
const plugin = definePlugin({ id: "notes", routes(router) { router.get("/preview", (_ctx, input) => ({ input })); } });
console.log(plugin.routeDefinitions.length); // 1

`post`

Parameters:

path: Plugin-relative path with simple alphanumeric/underscore/colon/hyphen segments; duplicate method/path pairs are rejected.
handler: Callback retained until host dispatch; receives admitted context and decoded input, returns a response or Promise. Not invoked during registration.

Returns: No value; the route is collected and later frozen by definePlugin.

Type parameters

T: Decoded request input shape expected by the handler; defaults to unknown and requires host validation.

Remarks

The builder is supplied only while definePlugin runs; host mounting, input validation and handler authorization are separate.

Errors and rejections

Error for invalid path/nonfunction handler or duplicate method/path.

Example:

import { definePlugin } from "@alneas/eaos-core/plugin-sdk/define-plugin";
const plugin = definePlugin({ id: "notes", routes(router) { router.post("/preview", (_ctx, input) => ({ input })); } });
console.log(plugin.routeDefinitions.length); // 1

`put`

Parameters:

path: Plugin-relative path with simple alphanumeric/underscore/colon/hyphen segments; duplicate method/path pairs are rejected.
handler: Callback retained until host dispatch; receives admitted context and decoded input, returns a response or Promise. Not invoked during registration.

Returns: No value; the route is collected and later frozen by definePlugin.

Type parameters

T: Decoded request input shape expected by the handler; defaults to unknown and requires host validation.

Remarks

The builder is supplied only while definePlugin runs; host mounting, input validation and handler authorization are separate.

Errors and rejections

Error for invalid path/nonfunction handler or duplicate method/path.

Example:

import { definePlugin } from "@alneas/eaos-core/plugin-sdk/define-plugin";
const plugin = definePlugin({ id: "notes", routes(router) { router.put("/preview", (_ctx, input) => ({ input })); } });
console.log(plugin.routeDefinitions.length); // 1

`patch`

Parameters:

path: Plugin-relative path with simple alphanumeric/underscore/colon/hyphen segments; duplicate method/path pairs are rejected.
handler: Callback retained until host dispatch; receives admitted context and decoded input, returns a response or Promise. Not invoked during registration.

Returns: No value; the route is collected and later frozen by definePlugin.

Type parameters

T: Decoded request input shape expected by the handler; defaults to unknown and requires host validation.

Remarks

The builder is supplied only while definePlugin runs; host mounting, input validation and handler authorization are separate.

Errors and rejections

Error for invalid path/nonfunction handler or duplicate method/path.

Example:

import { definePlugin } from "@alneas/eaos-core/plugin-sdk/define-plugin";
const plugin = definePlugin({ id: "notes", routes(router) { router.patch("/preview", (_ctx, input) => ({ input })); } });
console.log(plugin.routeDefinitions.length); // 1

`delete`

Parameters:

path: Plugin-relative path with simple alphanumeric/underscore/colon/hyphen segments; duplicate method/path pairs are rejected.
handler: Callback retained until host dispatch; receives admitted context and decoded input, returns a response or Promise. Not invoked during registration.

Returns: No value; the route is collected and later frozen by definePlugin.

Type parameters

T: Decoded request input shape expected by the handler; defaults to unknown and requires host validation.

Remarks

The builder is supplied only while definePlugin runs; host mounting, input validation and handler authorization are separate.

Errors and rejections

Error for invalid path/nonfunction handler or duplicate method/path.

Example:

import { definePlugin } from "@alneas/eaos-core/plugin-sdk/define-plugin";
const plugin = definePlugin({ id: "notes", routes(router) { router.delete("/preview", (_ctx, input) => ({ input })); } });
console.log(plugin.routeDefinitions.length); // 1

Example

See the owning declaration and linked feature guide for usage; no standalone example is documented in source.

[TYPE] `PluginRouteHandler`

Route callback receiving scoped capabilities and decoded input; execution timing and input validation belong to the host.

Imports: @alneas/eaos-core, @alneas/eaos-core/plugin-sdk, @alneas/eaos-core/plugin-sdk/define-plugin.

Signature

type PluginRouteHandler<TInput = unknown, TServices = Record<string, unknown>> = (ctx: PluginContext<TServices>, input: TInput) => unknown | Promise<unknown>;

Parameters

Name	Type	Required	Description
—	—	—	No call parameters.

Returns

Type declaration; no runtime value.

Domain response directly or via Promise; the host decides HTTP serialization. Handler errors/rejections propagate to host execution.

Type parameters

TInput: Decoded route input expected by the handler; default unknown and runtime validation remains host-owned.
TServices: Host service container shape; defaults to a record of unknown values.

Example

import type { PluginRouteHandler } from "@alneas/eaos-core/plugin-sdk/define-plugin";
const handler: PluginRouteHandler<{ title: string }> = (_ctx, input) => ({ title: input.title });

[INTERFACE] `PluginSecretRequirement`

Declare an environment secret needed by a plugin at boot.

Imports: @alneas/eaos-core, @alneas/eaos-core/plugin-sdk, @alneas/eaos-core/plugin-sdk/types.

Signature

interface PluginSecretRequirement {
    envKey: string;
    description: string;
    required: boolean;
}

Parameters

Name	Type	Required	Description
`envKey`	`string`	Yes	Exact environment variable name to resolve; declarations contain names rather than secret values.
`description`	`string`	Yes	Human-readable metadata describing the capability, workflow node or requirement to host users.
`required`	`boolean`	Yes	Whether an unresolved environment secret must fail validation; resolver calls default to true when the flag is omitted.

Returns

Type declaration; no runtime value.

Public members

`envKey`

Exact environment variable name to resolve; declarations contain names rather than secret values.

`description`

Human-readable metadata describing the capability, workflow node or requirement to host users.

`required`

Whether an unresolved environment secret must fail validation; resolver calls default to true when the flag is omitted.

Example

See the owning declaration and linked feature guide for usage; no standalone example is documented in source.

[INTERFACE] `PluginSettingConfig`

Describe one plugin setting field for a host settings UI.

Imports: @alneas/eaos-core, @alneas/eaos-core/plugin-sdk, @alneas/eaos-core/plugin-sdk/types.

Signature

interface PluginSettingConfig {
    key: string;
    label: string;
    type: 'text' | 'password' | 'boolean' | 'number' | 'select';
    description?: string;
    isSecret?: boolean;
    defaultValue?: any;
    options?: Array<{
        label: string;
        value: any;
    }>;
}

Parameters

Name	Type	Required	Description
`key`	`string`	Yes	Stable setting or procedure-unit lookup key interpreted by the host.
`label`	`string`	Yes	Human-readable navigation/node/setting label displayed by the host.
`type`	`'text' \| 'password' \| 'boolean' \| 'number' \| 'select'`	Yes	Settings UI control kind; select fields use options and secret handling is separately declared.
`description`	`string`	No	Human-readable metadata describing the capability, workflow node or requirement to host users.
`isSecret`	`boolean`	No	Optional instruction to treat the setting as secret; storage/protection remain host-owned.
`defaultValue`	`any`	No	Optional initial setting value when the host has no configured value.
`options`	`Array<{ label: string; value: any; }>`	No	Optional label/value choices for select-type settings.

Returns

Type declaration; no runtime value.

Public members

`key`

Stable setting or procedure-unit lookup key interpreted by the host.

`label`

Human-readable navigation/node/setting label displayed by the host.

`type`

Settings UI control kind; select fields use options and secret handling is separately declared.

`description`

Human-readable metadata describing the capability, workflow node or requirement to host users.

`isSecret`

Optional instruction to treat the setting as secret; storage/protection remain host-owned.

`defaultValue`

Optional initial setting value when the host has no configured value.

`options`

Optional label/value choices for select-type settings.

`options[].label`

Human-readable navigation/node/setting label displayed by the host.

`options[].value`

Actual configured value represented by this select option.

Example

See the owning declaration and linked feature guide for usage; no standalone example is documented in source.

[INTERFACE] `PluginStorageConfig`

Bind plugin records to a versioned shared table contract and namespace.

Imports: @alneas/eaos-core, @alneas/eaos-core/plugin-sdk, @alneas/eaos-core/plugin-sdk/types.

Signature

interface PluginStorageConfig {
    jsonDocuments?: string[];
    table: string;
    namespace: string;
    contractId: string;
    version: string;
}

Parameters

Name	Type	Required	Description
`jsonDocuments`	`string[]`	No	Required JSON document IDs in the owning data contract; omitted during explicit legacy adoption.
`table`	`string`	Yes	Physical table name declared by the owning data contract.
`namespace`	`string`	Yes	Logical provider/plugin namespace used to prevent ownership collisions.
`contractId`	`string`	Yes	Owning shared data-contract identity; not a plugin activation grant.
`version`	`string`	Yes	Accepted version/range of the shared data contract supplying this record table.

Returns

Type declaration; no runtime value.

Public members

`jsonDocuments`

Required JSON document IDs in the owning data contract; omitted during explicit legacy adoption.

`table`

Physical table name declared by the owning data contract.

`namespace`

Logical provider/plugin namespace used to prevent ownership collisions.

`contractId`

Owning shared data-contract identity; not a plugin activation grant.

`version`

Accepted version/range of the shared data contract supplying this record table.

Example

See the owning declaration and linked feature guide for usage; no standalone example is documented in source.

[INTERFACE] `PluginStoragePolicy`

Per-record payload bounds, object-storage requirement and history/archive retention policy.

Imports: @alneas/eaos-core/plugin-sdk, @alneas/eaos-core/plugin-sdk/storage-policy.

Signature

interface PluginStoragePolicy {
    maxPayloadBytes: number;
    objectStorage: ObjectStorageRequirement;
    historyRetentionDays: number | null;
    archive: PluginArchivePolicy;
}

Parameters

Name	Type	Required	Description
`maxPayloadBytes`	`number`	Yes	Maximum UTF-8 JSON payload for one DB record.
`objectStorage`	`ObjectStorageRequirement`	Yes	Whether large/private bodies must be kept outside the operational DB.
`historyRetentionDays`	`number \| null`	Yes	null means retain history indefinitely; deletion is never automatic on uninstall.
`archive`	`PluginArchivePolicy`	Yes	Declared retention/archive strategy; validation does not execute archives or deletion.

Returns

Type declaration; no runtime value.

Public members

`maxPayloadBytes`

Maximum UTF-8 JSON payload for one DB record.

`objectStorage`

Whether large/private bodies must be kept outside the operational DB.

`historyRetentionDays`

null means retain history indefinitely; deletion is never automatic on uninstall.

`archive`

Declared retention/archive strategy; validation does not execute archives or deletion.

Example

See the owning declaration and linked feature guide for usage; no standalone example is documented in source.

[INTERFACE] `PluginTestHarness`

GET/POST route invocation and explicit isolation verification for a defined plugin.

Imports: @alneas/eaos-core/testing.

Signature

interface PluginTestHarness {
    as(persona: TestPersona): {
        get(path: string): Promise<unknown>;
        post(path: string, input: unknown): Promise<unknown>;
    };
    expectTenantIsolation(): Promise<void>;
}

Parameters

Name	Type	Required	Description
`as`	`{ get(path: string): Promise<unknown>; post(path: string, input: unknown): Promise<unknown>; }`	Yes	Create a route client using a cloned test persona.
`expectTenantIsolation`	`Promise<void>`	Yes	Run the explicitly configured host data-isolation probe.

Returns

Type declaration; no runtime value.

Public members

`as`

Create a route client using a cloned test persona.

Parameters:

persona: Tenant fixture; defaults are test-user, member role, free tier and empty addons, except omitted pro addons infer the plugin addon.

Returns: GET/POST route client using the captured persona for each request.

Remarks

No live host authentication/activation is performed; use createContext and a real isolationProbe for data-boundary verification.

Errors and rejections

Error for invalid tenant identity or uncloneable persona.

Example:

import { createPluginTestHarness } from "@alneas/eaos-core/testing";
import { definePlugin } from "@alneas/eaos-core/plugin-sdk/define-plugin";
const plugin = definePlugin({ id: "notes", routes(router) { router.get("/status", () => ({ ready: true })); router.post("/preview", (_ctx, input) => ({ input })); } });
const harness = await createPluginTestHarness(plugin);
const client = harness.as({ tenantId: "tenant-demo" });
console.log(await client.get("/status"));

`as.get`

Invoke an exact GET route using the captured test persona.

Parameters:

path: Exact declared GET route path; no URL parsing is performed.

Returns: Resolved route handler output.

Remarks

Checks declared entitlement preview before host context construction; unconfigured capabilities fail on use.

Errors and rejections

Rejects on missing route, entitlement denial, unavailable host capability or context/handler failure.

Example:

import { createPluginTestHarness } from "@alneas/eaos-core/testing";
import { definePlugin } from "@alneas/eaos-core/plugin-sdk/define-plugin";
const plugin = definePlugin({ id: "notes", routes(router) { router.get("/status", () => ({ ready: true })); router.post("/preview", (_ctx, input) => ({ input })); } });
const harness = await createPluginTestHarness(plugin);
const client = harness.as({ tenantId: "tenant-demo" });
console.log(await client.get("/status"));

`as.post`

Invoke an exact POST route using the captured test persona.

Parameters:

path: Exact declared POST route path.
input: Decoded handler input passed unchanged; the harness does not apply a domain schema.

Returns: Resolved route handler output.

Remarks

Checks declared entitlement preview before host context construction; unconfigured capabilities fail on use.

Errors and rejections

Rejects on missing route, entitlement denial, unavailable host capability or context/handler failure.

Example:

import { createPluginTestHarness } from "@alneas/eaos-core/testing";
import { definePlugin } from "@alneas/eaos-core/plugin-sdk/define-plugin";
const plugin = definePlugin({ id: "notes", routes(router) { router.get("/status", () => ({ ready: true })); router.post("/preview", (_ctx, input) => ({ input })); } });
const harness = await createPluginTestHarness(plugin);
const client = harness.as({ tenantId: "tenant-demo" });
console.log(await client.post("/preview", { title: "hello" }));

`expectTenantIsolation`

Run the explicitly configured host data-isolation probe.

Returns: No value; configured probe has completed without failure.

Remarks

A real create/foreign-read probe is required; route names and personas alone cannot prove tenant isolation.

Errors and rejections

Rejects if isolationProbe is absent or that probe rejects.

Example:

import { createPluginTestHarness } from "@alneas/eaos-core/testing";
import type { PluginTestHarnessOptions } from "@alneas/eaos-core/testing";
import type { DefinedPlugin } from "@alneas/eaos-core/plugin-sdk/define-plugin";
async function verifyHostIsolation(plugin: DefinedPlugin, options: PluginTestHarnessOptions) {
 const harness = await createPluginTestHarness(plugin, options);
 await harness.expectTenantIsolation();
}

Example

See the owning declaration and linked feature guide for usage; no standalone example is documented in source.

[INTERFACE] `PluginTestHarnessOptions`

Optional real host capability factory and explicit data-isolation probe.

Imports: @alneas/eaos-core/testing.

Signature

interface PluginTestHarnessOptions {
    createContext?: (persona: TestPersona, pluginId: string) => Promise<Omit<PluginContext<any>, 'principal' | 'pluginId'>>;
    isolationProbe?: (harness: PluginTestHarness) => Promise<void>;
}

Parameters

Name	Type	Required	Description
`createContext`	`(persona: TestPersona, pluginId: string) => Promise<Omit<PluginContext<any>, 'principal' \| 'pluginId'>>`	No	Create real host capabilities for one persona/plugin route request.
`isolationProbe`	`(harness: PluginTestHarness) => Promise<void>`	No	Prove tenant isolation using real host-backed writes and foreign-tenant reads.

Returns

Type declaration; no runtime value.

Public members

`createContext`

Create real host capabilities for one persona/plugin route request.

Parameters:

persona: Cloned test identity whose tenant/subscription defaults are interpreted by the harness.
pluginId: Defined plugin identity receiving scoped host capabilities.

Returns: Host capabilities without principal/pluginId; the harness supplies those verified fixture fields after this callback resolves.

Remarks

Called per request, after entitlement preview. The host owns connection lifecycle and tenant isolation; no automatic disposal is provided.

Errors and rejections

Host adapter construction failures reject the request.

Remarks

Implement actual create/read assertions; an empty callback does not establish isolation.

Errors and rejections

Probe assertion/errors reject expectTenantIsolation.

Example

See the owning declaration and linked feature guide for usage; no standalone example is documented in source.

[TYPE] `PluginTier`

Browser-safe contracts. The server must resolve these from its control plane.

Imports: @alneas/eaos-core, @alneas/eaos-core/plugin-sdk, @alneas/eaos-core/entitlements.

Signature

type PluginTier = 'public' | 'standard' | 'pro' | 'corporate';

Parameters

Name	Type	Required	Description
—	—	—	No call parameters.

Returns

Type declaration; no runtime value.

Example

See the owning declaration and linked feature guide for usage; no standalone example is documented in source.

[INTERFACE] `PluginToolContext`

Verified runtime context supplied by the EAOS MCP host to a plugin tool.

Imports: @alneas/eaos-core, @alneas/eaos-core/plugin-sdk, @alneas/eaos-core/plugin-sdk/types.

Signature

interface PluginToolContext {
    tenantId: string;
    userId: string;
    roles: readonly string[];
    pluginId: string;
    traceId: string;
    aiHostAdapters?: AIHostAdapters;
    [key: string]: unknown;
}

Parameters

Name	Type	Required	Description
`tenantId`	`string`	Yes	Verified tenant boundary for the record or operation; host authorization must establish this scope.
`userId`	`string`	Yes	User identity within the tenant supplied by the trusted host.
`roles`	`readonly string[]`	Yes	Role claims supplied by the host after identity verification.
`pluginId`	`string`	Yes	Owning plugin identity used for capability scope and discovery.
`traceId`	`string`	Yes	Trace correlation identity propagated through host execution and audit paths.
`aiHostAdapters`	`AIHostAdapters`	No	Host-scoped providers; absent when the host did not configure one.

Returns

Type declaration; no runtime value.

Public members

`tenantId`

Verified tenant boundary for the record or operation; host authorization must establish this scope.

`userId`

User identity within the tenant supplied by the trusted host.

`roles`

Role claims supplied by the host after identity verification.

`pluginId`

Owning plugin identity used for capability scope and discovery.

`traceId`

Trace correlation identity propagated through host execution and audit paths.

`aiHostAdapters`

Host-scoped providers; absent when the host did not configure one.

Example

See the owning declaration and linked feature guide for usage; no standalone example is documented in source.

[INTERFACE] `PopulateOptions`

Compatibility re-export; its implementation and documentation are owned by the owning package @dataarthub/app-core.

Imports: @alneas/eaos-core, @alneas/eaos-core/adapters, @alneas/eaos-core/adapters/types.

Signature

export interface PopulateOptions {
    collection: string;
    localRef?: string;
    foreignRef?: string;
    as?: string;
    unwind?: boolean;
    populate?: PopulateOptions[];
    [key: string]: unknown;
    field?: string;
    foreignField?: string;
}

Parameters

Name	Type	Required	Description
`collection`	`string`	Yes	See the upstream owning declaration.
`localRef`	`string`	No	See the upstream owning declaration.
`foreignRef`	`string`	No	See the upstream owning declaration.
`as`	`string`	No	See the upstream owning declaration.
`unwind`	`boolean`	No	See the upstream owning declaration.
`populate`	`PopulateOptions[]`	No	See the upstream owning declaration.
`field`	`string`	No	See the upstream owning declaration.
`foreignField`	`string`	No	See the upstream owning declaration.

Returns

Type declaration; no runtime value.

Example

See the owning declaration and linked feature guide for usage; no standalone example is documented in source.

[TYPE] `PostToolHookHandler`

Observer invoked after tool execution; its returned Promise is not awaited.

Imports: @alneas/eaos-core, @alneas/eaos-core/agentic, @alneas/eaos-core/agentic/runtime.

Signature

type PostToolHookHandler = (payload: PostToolHookPayload) => Promise<void> | void;

Parameters

Name	Type	Required	Description
—	—	—	No call parameters.

Returns

Type declaration; no runtime value.

No value, or a Promise for observer completion. AgentRuntime does not await returned Promises and logs rejections; synchronous throws can turn its result into BLOCKED after an effect ran.

Example

import type { PostToolHookHandler } from "@alneas/eaos-core/agentic/runtime";
const hook: PostToolHookHandler = payload => { console.log(payload.durationMs); };

[INTERFACE] `PostToolHookPayload`

Completed tool output, executed arguments and measured duration for observers.

Imports: @alneas/eaos-core, @alneas/eaos-core/agentic, @alneas/eaos-core/agentic/runtime.

Signature

interface PostToolHookPayload {
    toolName: string;
    args: Record<string, unknown>;
    result: unknown;
    durationMs: number;
    context: AgentExecutionContext;
}

Parameters

Name	Type	Required	Description
`toolName`	`string`	Yes	Registered tool identity used to resolve host execution policy.
`args`	`Record<string, unknown>`	Yes	Operation arguments passed to hooks or bound into a proposed action; authorization and schema checks remain host-owned.
`result`	`unknown`	Yes	Resolved executor output passed by reference to post-tool observers.
`durationMs`	`number`	Yes	Measured elapsed duration in milliseconds.
`context`	`AgentExecutionContext`	Yes	Verified host execution scope propagated to adapters/guards/hooks; callers must establish identity and authorization before use.

Returns

Type declaration; no runtime value.

Public members

`toolName`

Registered tool identity used to resolve host execution policy.

`args`

Operation arguments passed to hooks or bound into a proposed action; authorization and schema checks remain host-owned.

`result`

Resolved executor output passed by reference to post-tool observers.

`durationMs`

Measured elapsed duration in milliseconds.

`context`

Verified host execution scope propagated to adapters/guards/hooks; callers must establish identity and authorization before use.

Example

See the owning declaration and linked feature guide for usage; no standalone example is documented in source.

[TYPE] `PreToolHookHandler`

Ordered admission callback that may replace arguments or stop execution.

Imports: @alneas/eaos-core, @alneas/eaos-core/agentic, @alneas/eaos-core/agentic/runtime.

Signature

type PreToolHookHandler = (payload: PreToolHookPayload) => Promise<PreToolHookResult> | PreToolHookResult;

Parameters

Name	Type	Required	Description
—	—	—	No call parameters.

Returns

Type declaration; no runtime value.

Admission decision directly or asynchronously; proceed false stops dispatch and modifiedArgs replaces the entire argument object. Throws/rejections propagate.

Example

import type { PreToolHookHandler } from "@alneas/eaos-core/agentic/runtime";
const hook: PreToolHookHandler = () => ({ proceed: true });

[INTERFACE] `PreToolHookPayload`

Tool arguments and scope passed sequentially to pre-execution hooks.

Imports: @alneas/eaos-core, @alneas/eaos-core/agentic, @alneas/eaos-core/agentic/runtime.

Signature

interface PreToolHookPayload {
    toolName: string;
    args: Record<string, unknown>;
    context: AgentExecutionContext;
}

Parameters

Name	Type	Required	Description
`toolName`	`string`	Yes	Registered tool identity used to resolve host execution policy.
`args`	`Record<string, unknown>`	Yes	Operation arguments passed to hooks or bound into a proposed action; authorization and schema checks remain host-owned.
`context`	`AgentExecutionContext`	Yes	Verified host execution scope propagated to adapters/guards/hooks; callers must establish identity and authorization before use.

Returns

Type declaration; no runtime value.

Public members

`toolName`

Registered tool identity used to resolve host execution policy.

`args`

Operation arguments passed to hooks or bound into a proposed action; authorization and schema checks remain host-owned.

`context`

Verified host execution scope propagated to adapters/guards/hooks; callers must establish identity and authorization before use.

Example

See the owning declaration and linked feature guide for usage; no standalone example is documented in source.

[INTERFACE] `PreToolHookResult`

Hook admission result with optional argument replacement and review metadata.

Imports: @alneas/eaos-core, @alneas/eaos-core/agentic, @alneas/eaos-core/agentic/runtime.

Signature

interface PreToolHookResult {
    proceed: boolean;
    modifiedArgs?: Record<string, unknown>;
    blockingReason?: string;
    requireHumanApproval?: boolean;
    riskLevel?: RiskLevel;
}

Parameters

Name	Type	Required	Description
`proceed`	`boolean`	Yes	Whether a pre-tool hook permits the next hook/executor to run.
`modifiedArgs`	`Record<string, unknown>`	No	Optional complete replacement argument object passed to later hooks and the executor.
`blockingReason`	`string`	No	Optional human-readable explanation when the hook stops execution.
`requireHumanApproval`	`boolean`	No	Whether execution must wait for an explicit host approval workflow.
`riskLevel`	`RiskLevel`	No	Declared operation risk used to determine review requirements; it does not itself grant authorization.

Returns

Type declaration; no runtime value.

Public members

`proceed`

Whether a pre-tool hook permits the next hook/executor to run.

`modifiedArgs`

Optional complete replacement argument object passed to later hooks and the executor.

`blockingReason`

Optional human-readable explanation when the hook stops execution.

`requireHumanApproval`

Whether execution must wait for an explicit host approval workflow.

`riskLevel`

Declared operation risk used to determine review requirements; it does not itself grant authorization.

Example

See the owning declaration and linked feature guide for usage; no standalone example is documented in source.

[INTERFACE] `ProcedureExecutionPlan`

Shared resolved procedure plan shape; plugins provide their binding type. *

Imports: @alneas/eaos-core/plugin-sdk, @alneas/eaos-core/plugin-sdk/procedure.

Signature

interface ProcedureExecutionPlan<TBinding = unknown> {
    tenantId: string;
    binding: TBinding;
    units: {
        key: string;
        title: string;
        ownerRole: string;
        targetType: string;
        targetDescription?: string;
        outcome: string;
        prerequisites: string[];
        dependsOn: string[];
        qualificationRequirements?: string[];
        trigger?: {
            kind: 'event' | 'manual' | 'predecessor';
            key: string;
            description: string;
        };
        siteRequirements?: {
            id: string;
            label: string;
            kind: 'text' | 'document' | 'role' | 'duration' | 'number';
        }[];
        dueRule?: string;
        exceptions?: {
            id: string;
            condition: string;
            action: string;
            escalateToRole: string;
            resumeWhen: string;
        }[];
        handoffs?: {
            unitRef: string;
            kind: 'next' | 'rework' | 'reinspect';
            when: 'accepted' | 'failed' | 'corrected';
            targetBinding: 'same_target_occurrence' | 'each_open_issue' | 'source_inspection';
            execution: 'create' | 'reopen';
            deliverables: string[];
        }[];
        eligibility?: EligibilityRequirements;
        checks: {
            id: string;
            instruction: string;
            critical: boolean;
            evidenceRequired: boolean;
            phase?: 'before' | 'during' | 'before_handoff';
            passCriterion?: string;
            evidenceTypes?: ('observation' | 'number' | 'photo' | 'document_ref' | 'recipient_ack')[];
            applicability?: {
                kind: 'always' | 'conditional';
                condition?: string;
            };
            onFailure?: string;
            measurement?: {
                unit: string;
                criterionSettingId: string;
            };
            frequency?: 'per_execution' | 'site_setup' | 'continuous';
        }[];
        acceptance: {
            independentReviewer: boolean;
            reviewerRole?: string;
            separateFrom?: string[];
            evidenceRequired: boolean;
            unresolvedIssues: 'block' | 'allow_source_issue_pending_reinspection';
            release?: 'none' | 'room_ready' | 'next_work';
        };
    }[];
}

Parameters

Name	Type	Required	Description
`tenantId`	`string`	Yes	Verified tenant boundary for the record or operation; host authorization must establish this scope.
`binding`	`TBinding`	Yes	Plugin-specific resolved target binding shared by the procedure plan units.
`units`	{ key: string; title: string; ownerRole: string; targetType: string; targetDescription?: string; outcome: string; prerequisites: string[]; dependsOn: string[]; qualificationRequirements?: string[]; trigger?: { kind: 'event' \| 'manual' \| 'predecessor'; key: string; description: string; }; siteRequirements?: { id: string; label: string; kind: 'text' \| 'document' \| 'role' \| 'duration' \| 'number'; }[]; dueRule?: string; exceptions?: { id: string; condition: string; action: string; escalateToRole: string; resumeWhen: string; }[]; handoffs?: { unitRef: string; kind: 'next' \| 'rework' \| 'reinspect'; when: 'accepted' \| 'failed' \| 'corrected'; targetBinding: 'same_target_occurrence' \| 'each_open_issue' \| 'source_inspection'; execution: 'create' \| 'reopen'; deliverables: string[]; }[]; eligibility?: EligibilityRequirements; checks: { id: string; instruction: string; critical: boolean; evidenceRequired: boolean; phase?: 'before' \| 'during' \| 'before_handoff'; passCriterion?: string; evidenceTypes?: ('observation' \| 'number' \| 'photo' \| 'document_ref' \| 'recipient_ack')[]; applicability?: { kind: 'always' \| 'conditional'; condition?: string; }; onFailure?: string; measurement?: { unit: string; criterionSettingId: string; }; frequency?: 'per_execution' \| 'site_setup' \| 'continuous'; }[]; acceptance: { independentReviewer: boolean; reviewerRole?: string; separateFrom?: string[]; evidenceRequired: boolean; unresolvedIssues: 'block' \| 'allow_source_issue_pending_reinspection'; release?: 'none' \| 'room_ready' \| 'next_work'; }; }[]	Yes	Resolved procedure work units in host-defined plan order.

Returns

Type declaration; no runtime value.

Type parameters

TBinding: Plugin-specific target binding resolved by host procedure logic; defaults to unknown.

Public members

`tenantId`

Verified tenant boundary for the record or operation; host authorization must establish this scope.

`binding`

Plugin-specific resolved target binding shared by the procedure plan units.

`units`

Resolved procedure work units in host-defined plan order.

`units[].key`

Stable setting or procedure-unit lookup key interpreted by the host.

`units[].title`

Human-readable draft, task, file or event title displayed by the host.

`units[].ownerRole`

Role responsible for performing the procedure unit.

`units[].targetType`

Category of resource to which the procedure unit applies.

`units[].targetDescription`

Optional human-readable target scope.

`units[].outcome`

Reported success/failure/denial/unknown category; reconcile uncertain effects before retrying.

`units[].prerequisites`

Named prerequisites that the host must satisfy before starting the unit.

`units[].dependsOn`

Other unit keys whose completion precedes this unit.

`units[].qualificationRequirements`

Optional host credential references required for the unit.

`units[].trigger`

Optional event/manual/predecessor activation metadata interpreted by the host.

`units[].trigger.kind`

Whether the host activates this unit from an event, manually or after its predecessor.

`units[].trigger.key`

Stable setting or procedure-unit lookup key interpreted by the host.

`units[].trigger.description`

Human-readable metadata describing the capability, workflow node or requirement to host users.

`units[].siteRequirements`

Optional site-specific evidence or setting requirements for the work unit.

`units[].siteRequirements[].id`

Stable site requirement identity used for evidence/configuration binding.

`units[].siteRequirements[].label`

Human-readable navigation/node/setting label displayed by the host.

`units[].siteRequirements[].kind`

Site requirement input/evidence kind expected by the host UI.

`units[].dueRule`

Optional host scheduling rule text for this work unit.

`units[].exceptions`

Optional conditional exception handling and escalation definitions.

`units[].exceptions[].id`

Stable exception-path identity within the procedure unit.

`units[].exceptions[].condition`

Data-only routing predicate or host-reviewed instruction; no expression string is executed by Core.

`units[].exceptions[].action`

Named host action performed or requested; procedure exception entries use this as the response instruction.

`units[].exceptions[].escalateToRole`

Role receiving the exception escalation.

`units[].exceptions[].resumeWhen`

Human-readable condition required before resuming an exception path.

`units[].handoffs`

Optional next/rework/reinspection transitions and their output requirements.

`units[].handoffs[].unitRef`

Target unit reference for a procedure handoff.

`units[].handoffs[].kind`

Handoff relationship: next work, rework or reinspection.

`units[].handoffs[].when`

Outcome that activates this handoff.

`units[].handoffs[].targetBinding`

Scope used by the host to resolve target occurrences/issues for the handoff.

`units[].handoffs[].execution`

Whether the host creates or reopens the handoff execution.

`units[].handoffs[].deliverables`

Named evidence/output artifacts required by the handoff.

`units[].eligibility`

Optional exact training/qualification requirements checked by host services.

`units[].checks`

Ordered probe results or procedure check requirements; the owning host performs the actual checks.

`units[].checks[].id`

Stable check identity within the procedure unit.

`units[].checks[].instruction`

Actionable procedure check instruction.

`units[].checks[].critical`

Whether this procedure check is critical to host acceptance policy.

`units[].checks[].evidenceRequired`

Whether acceptance/check completion requires evidence under host policy.

`units[].checks[].phase`

Optional check timing: before, during or before_handoff; host procedure logic applies it.

`units[].checks[].passCriterion`

Optional criterion used to judge a procedure check.

`units[].checks[].evidenceTypes`

Allowed evidence kinds for this procedure check.

`units[].checks[].applicability`

Whether this check always applies or depends on a host-evaluated condition.

`units[].checks[].applicability.kind`

Whether the procedure check always applies or requires a host-evaluated condition.

`units[].checks[].applicability.condition`

Data-only routing predicate or host-reviewed instruction; no expression string is executed by Core.

`units[].checks[].onFailure`

Optional host action/instruction when this check fails.

`units[].checks[].measurement`

Optional measurement unit and criterion-setting binding.

`units[].checks[].measurement.unit`

Measurement unit used with the referenced criterion setting.

`units[].checks[].measurement.criterionSettingId`

Host setting identity supplying the measurement acceptance criterion.

`units[].checks[].frequency`

When the host requires this check: each execution, site setup or continuously.

`units[].acceptance`

Reviewer independence, evidence, unresolved-issue and release requirements for the unit.

`units[].acceptance.independentReviewer`

Whether the host must require a reviewer distinct from execution ownership.

`units[].acceptance.reviewerRole`

Optional role permitted to accept the work unit.

`units[].acceptance.separateFrom`

Optional roles/identities from which the reviewer must be independent.

`units[].acceptance.evidenceRequired`

Whether acceptance/check completion requires evidence under host policy.

`units[].acceptance.unresolvedIssues`

Whether open issues block acceptance or may remain pending source-issue reinspection.

`units[].acceptance.release`

Optional acceptance release category communicated to downstream host workflows.

Example

import { type ProcedureExecutionPlan } from "@alneas/eaos-core/plugin-sdk/procedure";
const plan: ProcedureExecutionPlan<{ recordId: string }> = { tenantId: "tenant-demo", binding: { recordId: "record-1" }, units: [] };
console.log(plan.units.length); // 0

[INTERFACE] `ProvidedAgentConfig`

Plugin-advertised agent role, model tier, budget and capability limits.

Imports: @alneas/eaos-core, @alneas/eaos-core/plugin-sdk, @alneas/eaos-core/plugin-sdk/types.

Signature

interface ProvidedAgentConfig {
    id: string;
    name: string;
    role: 'ceo' | 'executive' | 'manager' | 'worker' | 'red_team';
    tierLevel: 'tier1_cloud_premium' | 'tier2_edge_local' | 'tier3_embedding_rerank';
    allowedSensitivityLevel: 'level1_public' | 'level2_internal' | 'level3_strict';
    dailyBudgetCapUsd: number;
    capabilities: string[];
    skillIds?: string[];
    allowedToolNames?: string[];
    approvalProfile?: string;
}

Parameters

Name	Type	Required	Description
`id`	`string`	Yes	Stable advertised agent identity used by the consuming host.
`name`	`string`	Yes	Human-readable display name supplied by the plugin/provider catalog; distinct from the stable ID.
`role`	`'ceo' \| 'executive' \| 'manager' \| 'worker' \| 'red_team'`	Yes	Organizational role advertised for the provided agent.
`tierLevel`	`'tier1_cloud_premium' \| 'tier2_edge_local' \| 'tier3_embedding_rerank'`	Yes	Advertised agent model capability/cost tier; host routing applies actual policy.
`allowedSensitivityLevel`	`'level1_public' \| 'level2_internal' \| 'level3_strict'`	Yes	Highest/declared sensitivity classification accepted by this agent according to host policy.
`dailyBudgetCapUsd`	`number`	Yes	Maximum advertised daily spending allowance in US dollars; accounting/enforcement belongs to the host.
`capabilities`	`string[]`	Yes	Advertised operation/capability names; presence alone does not authorize execution.
`skillIds`	`string[]`	No	Optional advertised skill identities associated with this agent.
`allowedToolNames`	`string[]`	No	Explicit tool-name allowlist to enforce at the host execution boundary.
`approvalProfile`	`string`	No	Optional host policy profile name governing the agent approval path.

Returns

Type declaration; no runtime value.

Public members

`id`

Stable advertised agent identity used by the consuming host.

`name`

Human-readable display name supplied by the plugin/provider catalog; distinct from the stable ID.

`role`

Organizational role advertised for the provided agent.

`tierLevel`

Advertised agent model capability/cost tier; host routing applies actual policy.

`allowedSensitivityLevel`

Highest/declared sensitivity classification accepted by this agent according to host policy.

`dailyBudgetCapUsd`

Maximum advertised daily spending allowance in US dollars; accounting/enforcement belongs to the host.

`capabilities`

Advertised operation/capability names; presence alone does not authorize execution.

`skillIds`

Optional advertised skill identities associated with this agent.

`allowedToolNames`

Explicit tool-name allowlist to enforce at the host execution boundary.

`approvalProfile`

Optional host policy profile name governing the agent approval path.

Example

See the owning declaration and linked feature guide for usage; no standalone example is documented in source.

[INTERFACE] `ProviderHealth`

Mutable provider failure count, circuit state and optional latest failure time.

Imports: @alneas/eaos-core/agent/circuit-breaker.

Signature

interface ProviderHealth {
    provider: AiProvider;
    failures: number;
    state: 'CLOSED' | 'OPEN' | 'HALF_OPEN';
    lastFailureTime?: number;
}

Parameters

Name	Type	Required	Description
`provider`	`AiProvider`	Yes	Provider identity from model metadata, travel discovery or connection/circuit health.
`failures`	`number`	Yes	Number of failures recorded since the latest success.
`state`	`'CLOSED' \| 'OPEN' \| 'HALF_OPEN'`	Yes	CLOSED permits selection, OPEN waits for cooldown and HALF_OPEN permits a retry without concurrency limiting.
`lastFailureTime`	`number`	No	Optional latest failure time in Unix epoch milliseconds.

Returns

Type declaration; no runtime value.

Public members

`provider`

Provider identity from model metadata, travel discovery or connection/circuit health.

`failures`

Number of failures recorded since the latest success.

`state`

CLOSED permits selection, OPEN waits for cooldown and HALF_OPEN permits a retry without concurrency limiting.

`lastFailureTime`

Optional latest failure time in Unix epoch milliseconds.

Example

See the owning declaration and linked feature guide for usage; no standalone example is documented in source.

[INTERFACE] `QueryOptions`

Compatibility re-export; its implementation and documentation are owned by the owning package @dataarthub/app-core.

Imports: @alneas/eaos-core, @alneas/eaos-core/adapters, @alneas/eaos-core/adapters/types.

Signature

export interface QueryOptions {
    signal?: AbortSignal;
    sort?: Record<string, number>;
    limit?: number;
    skip?: number;
    populate?: PopulateOptions[];
    projection?: string[] | Record<string, unknown>;
    docType?: DocType;
    paginateAll?: boolean;
    [key: string]: unknown;
}

Parameters

Name	Type	Required	Description
`signal`	`AbortSignal`	No	See the upstream owning declaration.
`sort`	`Record<string, number>`	No	See the upstream owning declaration.
`limit`	`number`	No	See the upstream owning declaration.
`skip`	`number`	No	See the upstream owning declaration.
`populate`	`PopulateOptions[]`	No	See the upstream owning declaration.
`projection`	`string[] \| Record<string, unknown>`	No	See the upstream owning declaration.
`docType`	`DocType`	No	See the upstream owning declaration.
`paginateAll`	`boolean`	No	See the upstream owning declaration.

Returns

Type declaration; no runtime value.

Example

See the owning declaration and linked feature guide for usage; no standalone example is documented in source.

[INTERFACE] `QuotaConfig`

Optional process-local daily and cumulative monthly call limits.

Imports: @alneas/eaos-core/agent/cache-manager.

Signature

interface QuotaConfig {
    maxCallsPerDay?: number;
    maxCallsPerMonth?: number;
}

Parameters

Name	Type	Required	Description
`maxCallsPerDay`	`number`	No	Optional UTC daily call limit; zero is treated as no limit by McpCacheManager.
`maxCallsPerMonth`	`number`	No	Optional cumulative call limit; the current cache manager does not reset it at month boundaries, and zero is unenforced.

Returns

Type declaration; no runtime value.

Public members

`maxCallsPerDay`

Optional UTC daily call limit; zero is treated as no limit by McpCacheManager.

`maxCallsPerMonth`

Optional cumulative call limit; the current cache manager does not reset it at month boundaries, and zero is unenforced.

Example

See the owning declaration and linked feature guide for usage; no standalone example is documented in source.

[INTERFACE] `ReadinessReport`

Timestamped aggregate availability and ordered probe results.

Imports: @alneas/eaos-core, @alneas/eaos-core/health.

Signature

interface ReadinessReport {
    state: ReadinessState;
    checkedAt: string;
    checks: readonly HealthCheckResult[];
}

Parameters

Name	Type	Required	Description
`state`	`ReadinessState`	Yes	not_ready for critical failure, degraded for noncritical failure, otherwise ready.
`checkedAt`	`string`	Yes	Timestamp associated with the reported evaluation or measurement.
`checks`	`readonly HealthCheckResult[]`	Yes	Ordered probe results or procedure check requirements; the owning host performs the actual checks.

Returns

Type declaration; no runtime value.

Public members

`state`

not_ready for critical failure, degraded for noncritical failure, otherwise ready.

`checkedAt`

Timestamp associated with the reported evaluation or measurement.

`checks`

Ordered probe results or procedure check requirements; the owning host performs the actual checks.

Example

See the owning declaration and linked feature guide for usage; no standalone example is documented in source.

[TYPE] `ReadinessState`

Aggregate readiness based on critical and noncritical probe outcomes.

Imports: @alneas/eaos-core, @alneas/eaos-core/health.

Signature

type ReadinessState = 'ready' | 'degraded' | 'not_ready';

Parameters

Name	Type	Required	Description
—	—	—	No call parameters.

Returns

Type declaration; no runtime value.

Example

See the owning declaration and linked feature guide for usage; no standalone example is documented in source.

[TYPE] `RegistrationHookBody`

Preserve default body behavior, select the built-in identity-email mapping or use host Jsonnet.

Imports: @alneas/eaos-core/platform/config.

Signature

type RegistrationHookBody = false | 'identity-email-v1' | {
    path: string;
};

Parameters

Name	Type	Required	Description
—	—	—	No call parameters.

Returns

Type declaration; no runtime value.

Public members

`path`

Project-relative standalone .jsonnet body mapping path without traversal.

Example

See the owning declaration and linked feature guide for usage; no standalone example is documented in source.

[INTERFACE] `RegistrationHookConfig`

Host callback path and optional authentication header/session/body mapping.

Imports: @alneas/eaos-core/platform/config.

Signature

interface RegistrationHookConfig {
    path: string;
    authHeader?: string;
    session?: false | 'before' | 'after';
    body?: RegistrationHookBody;
}

Parameters

Name	Type	Required	Description
`path`	`string`	Yes	Absolute simple callback URL path mounted on the internal backend; host owns its implementation.
`authHeader`	`string`	No	Non-secret X-* header name. The value is supplied only at runtime.
`session`	`false \| 'before' \| 'after'`	No	Position of the session hook relative to web_hook; omitted/false adds no session hook.
`body`	`RegistrationHookBody`	No	Omitted/false preserves Kratos’s body behavior; files are host-owned, standalone Jsonnet.

Returns

Type declaration; no runtime value.

Public members

`path`

Absolute simple callback URL path mounted on the internal backend; host owns its implementation.

`authHeader`

Non-secret X-* header name. The value is supplied only at runtime.

`session`

Position of the session hook relative to web_hook; omitted/false adds no session hook.

`body`

Omitted/false preserves Kratos’s body behavior; files are host-owned, standalone Jsonnet.

Example

See the owning declaration and linked feature guide for usage; no standalone example is documented in source.

[FUNCTION] `renderWorkflowDot`

Render a safe Graphviz DOT document for exports and server-side diagrams.

Imports: @alneas/eaos-core, @alneas/eaos-core/workflow-visualization.

Signature

declare function renderWorkflowDot(visualization: WorkflowGraphVisualization): string;

Parameters

Name	Type	Required	Description
`visualization`	`WorkflowGraphVisualization`	Yes	Graph nodes/edges with optional runtime current-node marker; edges with unknown endpoints are omitted.

Returns

string

The diagram source as text; labels are escaped for the target format.

Remarks

No renderer is invoked and no workflow executes; the caller chooses where to render/export the returned text.

Example

import { renderWorkflowDot } from "@alneas/eaos-core/workflow-visualization";
const visualization = { graph: { schemaVersion: "1.0", entryNode: "start", nodes: [{ id: "start", kind: "task", label: "Start", canRequestApproval: false }], edges: [] } } as const;
console.log(renderWorkflowDot(visualization));

[FUNCTION] `renderWorkflowMermaid`

Render a safe Mermaid flowchart without executing any workflow metadata.

Imports: @alneas/eaos-core, @alneas/eaos-core/workflow-visualization.

Signature

declare function renderWorkflowMermaid(visualization: WorkflowGraphVisualization): string;

Parameters

Name	Type	Required	Description
`visualization`	`WorkflowGraphVisualization`	Yes	Graph nodes/edges with optional runtime current-node marker; edges with unknown endpoints are omitted.

Returns

string

The diagram source as text; labels are escaped for the target format.

Remarks

No renderer is invoked and no workflow executes; the caller chooses where to render/export the returned text.

Example

import { renderWorkflowMermaid } from "@alneas/eaos-core/workflow-visualization";
const visualization = { graph: { schemaVersion: "1.0", entryNode: "start", nodes: [{ id: "start", kind: "task", label: "Start", canRequestApproval: false }], edges: [] } } as const;
console.log(renderWorkflowMermaid(visualization));

[FUNCTION] `resolveDataContracts`

Compose only selected contracts; one trusted release per ID, no silent range fallback.

Imports: @alneas/eaos-core, @alneas/eaos-core/data-contracts, @alneas/eaos-core/contracts/data-contracts.

Signature

declare function resolveDataContracts(available: readonly DataContract[], requirements: Record<string, string>): DataContractCatalog;

Parameters

Name	Type	Required	Description
`available`	`readonly DataContract[]`	Yes	One trusted release per unique ID/migration identity. Every supplied release is structurally validated, even when not selected.
`requirements`	`Record<string, string>`	Yes	Contract ID to semver range; empty requirements select no releases. Prereleases are included during requirement resolution.

Returns

DataContractCatalog

A new catalog with dependency-first contracts and alphabetically sorted tables; contract/schema objects retain source references.

Remarks

No SQL, activation or infrastructure changes occur. SQL ownership checks inspect recognized table DDL patterns and are not a general SQL security sandbox.

Errors and rejections

Error for invalid/duplicate releases or migrations, unsatisfied ranges, dependency cycles, foreign-table DDL, invalid JSON contracts or conflicting ownership.

Example

import { resolveDataContracts } from "@alneas/eaos-core/contracts/data-contracts";
const contract = { id: "notes", version: "1.0.0", description: "Tenant notes", schema: { type: "object", properties: { tenant_id: { type: "string" } }, required: ["tenant_id"], "x-db": { tableName: "notes" } }, migrations: [] };
console.log(resolveDataContracts([contract], { notes: "^1.0.0" }).tables.map(table => table.name));

[TYPE] `ResolvedPlatformConfig`

Deeply readonly resolved service, ingress and authentication configuration with provenance.

Imports: @alneas/eaos-core/platform/config.

Signature

type ResolvedPlatformConfig = DeepReadonly<{
    defaultsVersion: typeof PLATFORM_DEFAULTS_VERSION;
    appName: string;
    baseDomain: string;
    environment: 'production' | 'development';
    networkName: string;
    origins: {
        app: string;
        auth: string;
    };
    services: {
        backend: ResolvedService;
        frontend: ResolvedService;
        kratos: ResolvedService & {
            adminPort: number;
            adminUrl: string;
        };
    };
    nginx: {
        appOrigin: string;
        appServerNames: string[];
        hostRoutes: Array<{
            host: string;
            origin: string;
            upstream: string;
            resolution: 'docker' | 'system';
            service: 'backend' | 'frontend' | 'external';
            proxy: {
                readTimeoutSeconds: number;
                sendTimeoutSeconds: number;
                buffering: boolean;
            };
        }>;
        authOrigin: string;
        api: {
            path: '/api/';
            prefixes: string[];
            upstream: string;
        };
        frontendUpstream: string;
        authUpstream: string;
    };
    hono: {
        port: number;
        corsOrigins: string[];
        kratosPublicUrl: string;
        kratosBrowserUrl: string;
    };
    kratos: {
        publicUrl: string;
        adminUrl: string;
        uiOrigin: string;
        corsOrigins: string[];
        defaultBrowserReturnUrl: string;
        allowedReturnUrls: string[];
        ui: Record<AuthUiFlow, string>;
        cookie: {
            name: string;
            domain?: string;
            path: string;
            sameSite: SameSite;
            secure: boolean;
            persistent: boolean;
        };
        defaultSchemaId: string;
        identitySchemas: Array<{
            id: string;
            source: {
                type: 'builtin';
                name: 'email-v1';
            } | {
                type: 'file';
                path: string;
            };
        }>;
        registrationHook: false | {
            url: string;
            authHeader: string;
            session: false | 'before' | 'after';
            body: RegistrationHookBody;
        };
        oidc: false | {
            google: {
                id: string;
                provider: 'google';
                scopes: string[];
                mapper: GoogleOidcMapper;
                callbackUrl: string;
            };
        };
    };
    provenance: Record<string, ConfigSource>;
}>;

Parameters

Name	Type	Required	Description
—	—	—	No call parameters.

Returns

Type declaration; no runtime value.

Public members

`defaultsVersion`

Supported platform defaults version; omission selects PLATFORM_DEFAULTS_VERSION.

`appName`

Lowercase DNS label identifying the application and derived network settings.

`baseDomain`

DNS domain with at least two valid lowercase labels; scopes cookie and managed ingress hosts.

`environment`

Production or development configuration mode; defaults to production with HTTPS/secure-cookie requirements.

`networkName`

Host network identity; defaults to appName followed by -network.

`origins`

Distinct public application and authentication origins; defaults to HTTPS app/auth subdomains of baseDomain.

`origins.app`

Normalized public application origin used by ingress/CORS/return defaults.

`origins.auth`

Normalized public authentication API origin, separate from app and authentication UI origins.

`services`

Resolved internal service names, ports and URLs; resolver does not connect or deploy services.

`services.backend`

Backend service name/port or resolved service; defaults to hono-server on port 3000.

`services.frontend`

Frontend service name/port or resolved service; defaults to frontend on port 80.

`services.kratos`

Kratos public/admin service configuration or resolved authentication settings.

`services.kratos.adminPort`

Kratos administration port; defaults to 4434 and must differ from the public listener port.

`services.kratos.adminUrl`

Derived internal administration URL; hosts must keep it outside public ingress.

`nginx`

Derived ingress routing metadata; resolver does not write nginx files or deploy listeners.

`nginx.appOrigin`

Normalized public application origin used by ingress rendering.

`nginx.appServerNames`

Unique public app hostnames, including the canonical app hostname and configured aliases.

`nginx.hostRoutes`

Additional exact DNS-to-upstream routes; conflicting/reserved host claims are rejected.

`nginx.hostRoutes[].host`

Exact DNS route or HTTP upstream name; managed route hosts must remain under baseDomain.

`nginx.hostRoutes[].origin`

Derived public route origin inheriting application scheme/listener port with the configured exact hostname.

`nginx.hostRoutes[].upstream`

Derived internal HTTP service URL used for ingress routing.

`nginx.hostRoutes[].resolution`

Upstream hostname resolution strategy, docker by default for resolved host routes.

`nginx.hostRoutes[].service`

Resolved route target classification: backend, frontend or host-owned external service.

`nginx.hostRoutes[].proxy`

Per-route ingress settings; default read/send timeouts are 180 seconds and buffering is false.

`nginx.hostRoutes[].proxy.readTimeoutSeconds`

Ingress upstream read timeout in seconds; defaults to 180.

`nginx.hostRoutes[].proxy.sendTimeoutSeconds`

Ingress upstream send timeout in seconds; defaults to 180.

`nginx.hostRoutes[].proxy.buffering`

Ingress proxy buffering selection; defaults to false.

`nginx.authOrigin`

Normalized public Kratos/API origin distinct from the application and auth UI origins.

`nginx.api`

API mount metadata or derived backend routing; host renders and enforces these routes.

`nginx.api.path`

Canonical backend path fixed to /api/.

`nginx.api.prefixes`

Distinct API route prefixes assigned to the backend, starting with /api.

`nginx.api.upstream`

Derived internal HTTP service URL used for ingress routing.

`nginx.frontendUpstream`

Derived internal frontend URL used by ingress rendering.

`nginx.authUpstream`

Derived internal Kratos public-service upstream used by ingress.

`hono`

Resolved application API listener, CORS and Kratos connection metadata.

`hono.port`

Resolved backend listener port, default 3000.

`hono.corsOrigins`

Unique normalized browser origins permitted for the resolved host service.

`hono.kratosPublicUrl`

Derived internal Kratos public-service URL used by backend clients.

`hono.kratosBrowserUrl`

Derived public Kratos origin used by browser clients.

`kratos`

Kratos public/admin service configuration or resolved authentication settings.

`kratos.publicUrl`

Derived public Kratos URL ending with a slash.

`kratos.adminUrl`

Derived internal administration URL; hosts must keep it outside public ingress.

`kratos.uiOrigin`

External authentication UI origin; defaults to app origin and must differ from auth API origin.

`kratos.corsOrigins`

Unique normalized browser origins permitted for the resolved host service.

`kratos.defaultBrowserReturnUrl`

Absolute HTTP(S) return URL without query/fragment; defaults to the application origin root and requires HTTPS in production.

`kratos.allowedReturnUrls`

Derived explicit browser-return allowlist covering the app root, UI flows and configured default return URL.

`kratos.ui`

Authentication UI flow paths or derived absolute URLs; no UI routes are deployed by resolution.

`kratos.cookie`

Shared auth cookie settings; defaults to secure persistent Lax at root path with a domain covering app/auth/UI/return hosts.

`kratos.cookie.name`

Auth session cookie name; defaults to ory_kratos_session and special __Host-/__Secure- prefixes have additional constraints.

`kratos.cookie.domain`

Resolved shared cookie domain covering app/auth/UI/return hosts; defaults to baseDomain.

`kratos.cookie.path`

Cookie scope path fixed to / in defaults version 1.

`kratos.cookie.sameSite`

Auth cookie cross-site policy; defaults to Lax. None requires secure true.

`kratos.cookie.secure`

Auth cookie HTTPS-only flag; defaults to true and is required in production or with SameSite None.

`kratos.cookie.persistent`

Whether auth cookies persist, or whether a workspace survives execution; cookie default is true and runtime workspace is always false.

`kratos.defaultSchemaId`

Identity-schema ID selected for registration; defaults to the first configured schema or builtin default.

`kratos.identitySchemas`

Resolved nonempty identity schema sources; entries reference builtin email-v1 or host-owned JSON files.

`kratos.identitySchemas[].id`

Resolved identity schema ID used by registration.

`kratos.identitySchemas[].source`

Resolved builtin email-v1 schema metadata or host-owned project-relative JSON file source.

`kratos.identitySchemas[].source.type`

Identity schema source discriminator: builtin metadata or a host-owned file.

`kratos.identitySchemas[].source.name`

Builtin identity schema name fixed to email-v1.

`kratos.identitySchemas[].source.type`

Identity schema source discriminator: builtin metadata or a host-owned file.

`kratos.identitySchemas[].source.path`

Host-owned project-relative JSON identity schema file path.

`kratos.registrationHook`

Optional internal callback configuration; false by default and host authentication/business handling are required.

`kratos.registrationHook.url`

Target/observed HTTP(S) location; adapter/host authorization must restrict navigation and delivery.

`kratos.registrationHook.authHeader`

Non-secret X-* header name for callback authentication; defaults to X-EAOS-Webhook-Key and the value is supplied at runtime.

`kratos.registrationHook.session`

Registration session-hook ordering; false by default, otherwise before or after the web hook.

`kratos.registrationHook.body`

Exact inbound body or configured hook body mapping; callback mapping defaults preserve native Kratos behavior.

`kratos.oidc`

Explicit OIDC opt-in, false by default; client credentials remain runtime bindings.

`kratos.oidc.google`

Explicit Google OIDC provider configuration; credentials are separate host runtime bindings.

`kratos.oidc.google.id`

Stable Google provider ID; defaults to google and determines the callback path.

`kratos.oidc.google.provider`

Provider identity from model metadata, travel discovery or connection/circuit health.

`kratos.oidc.google.scopes`

Exact API permission scope names associated with the verified identity/key.

`kratos.oidc.google.mapper`

Google claim mapping; defaults to google-verified-email-v1, which requires an email scope.

`kratos.oidc.google.callbackUrl`

Derived public Google OIDC callback URL using the configured provider ID.

`provenance`

Paths refer to normalized inputs or derived outputs. Values and secret material are never logged.

Example

See the owning declaration and linked feature guide for usage; no standalone example is documented in source.

[FUNCTION] `resolvePlatformConfig`

Validate and resolve app + environment overrides. No IO; all returned objects are immutable.

Imports: @alneas/eaos-core/platform/config.

Signature

declare function resolvePlatformConfig(input: unknown, environmentOverrides?: unknown): ResolvedPlatformConfig;

Parameters

Name	Type	Required	Description
`input`	`unknown`	Yes	Plain configuration object requiring a lowercase DNS-label appName and DNS baseDomain. Unknown keys are rejected; secrets belong to runtime bindings.
`environmentOverrides`	`unknown`	No	Same configuration shape, recursively overriding supplied values; defaults to empty. Arrays replace rather than merge, and undefined is ignored.

Returns

ResolvedPlatformConfig

A recursively frozen resolved configuration with defaults, derived service URLs and source provenance.

Remarks

No process environment, filesystem, provider or network access. Defaults include production, HTTPS app/auth subdomains, backend 3000, frontend 80, Kratos 4433/4434 and secure persistent Lax root-path cookies. Host renders and enforces the resolved settings.

Errors and rejections

PlatformConfigError for invalid shape, unsupported defaults version, insecure/conflicting origins/cookies, overlapping routes/prefixes or invalid auth configuration.

Example

import { resolvePlatformConfig } from "@alneas/eaos-core/platform/config";
const config = resolvePlatformConfig({ appName: "demo", baseDomain: "example.com" });
console.log(config.services.backend.port); // 3000

[FUNCTION] `resolvePluginStoragePolicy`

Resolve an optional storage policy through the standard validator.

Imports: @alneas/eaos-core/plugin-sdk, @alneas/eaos-core/plugin-sdk/storage-policy.

Signature

declare function resolvePluginStoragePolicy(policy?: PluginStoragePolicy): PluginStoragePolicy;

Parameters

Name	Type	Required	Description
`policy`	`PluginStoragePolicy`	No	Explicit policy; omission uses DEFAULT_PLUGIN_STORAGE_POLICY (4 MiB, optional object storage, indefinite history, no archive).

Returns

PluginStoragePolicy

A validated fresh policy object.

Errors and rejections

Error when the supplied policy is invalid.

Example

import { resolvePluginStoragePolicy } from "@alneas/eaos-core/plugin-sdk/storage-policy";
console.log(resolvePluginStoragePolicy().maxPayloadBytes); // 4194304

[FUNCTION] `retryDelayMs`

Compute a capped exponential outbox retry delay.

Imports: @alneas/eaos-core, @alneas/eaos-core/events/outbox.

Signature

declare function retryDelayMs(attempt: number, policy: OutboxRetryPolicy): number;

Parameters

Name	Type	Required	Description
`attempt`	`number`	Yes	Positive one-based attempt number.
`policy`	`OutboxRetryPolicy`	Yes	Positive maxAttempts and multiplier at least 1; nonnegative finite delay values in milliseconds.

Returns

number

Delay in milliseconds, capped at maxDelayMs; maxAttempts does not itself suppress further attempts.

Remarks

Does not sleep, schedule or enforce idempotency.

Errors and rejections

Error for invalid attempt or retry policy.

Example

import { retryDelayMs } from "@alneas/eaos-core/events/outbox";
console.log(retryDelayMs(2, { maxAttempts: 5, baseDelayMs: 1000, maxDelayMs: 60000, backoffMultiplier: 2 })); // 2000

[FUNCTION] `revokeApiKey`

Create a revoked copy of an API key record.

Imports: @alneas/eaos-core, @alneas/eaos-core/security/platform-security.

Signature

declare function revokeApiKey(record: ApiKeyRecord, now?: Date): ApiKeyRecord;

Parameters

Name	Type	Required	Description
`record`	`ApiKeyRecord`	Yes	Stored key; an existing revokedAt is retained.
`now`	`Date`	No	Revocation time when not already revoked; defaults to current Date.

Returns

ApiKeyRecord

A cloned record carrying revokedAt; caller must persist it.

Errors and rejections

Native cloning errors or RangeError for an invalid Date when creating a revocation timestamp.

Example

import { revokeApiKey } from "@alneas/eaos-core/security/platform-security";
import { issueApiKey } from "@alneas/eaos-core/security/platform-security";
const issued = issueApiKey({ tenantId: "tenant-demo", userId: "user-demo", scopes: ["notes:read"] });
console.log(revokeApiKey(issued.record).revokedAt);

[TYPE] `RiskLevel`

Risk labels used by approval and execution policies.

Imports: @alneas/eaos-core, @alneas/eaos-core/plugin-sdk, @alneas/eaos-core/plugin-sdk/types.

Signature

type RiskLevel = 'low' | 'medium' | 'high' | 'critical';

Parameters

Name	Type	Required	Description
—	—	—	No call parameters.

Returns

Type declaration; no runtime value.

Example

See the owning declaration and linked feature guide for usage; no standalone example is documented in source.

[FUNCTION] `runReadinessChecks`

Pure readiness aggregation. It never exposes adapter errors or secrets.

Imports: @alneas/eaos-core, @alneas/eaos-core/health.

Signature

declare function runReadinessChecks(checks: readonly HealthCheck[], now?: Date): Promise<ReadinessReport>;

Parameters

Name	Type	Required	Description
`checks`	`readonly HealthCheck[]`	Yes	Unique checks; critical defaults to true and timeoutMs to 2000 (allowed 1–30000 ms). Probes should be read-only.
`now`	`Date`	No	Timestamp for the report; defaults to current time.

Returns

Promise<ReadinessReport>

Report in input order: not_ready for any failed critical check, degraded for noncritical failures, otherwise ready; an empty set is ready.

Remarks

Timeouts stop waiting but do not cancel a probe. Probes may still run after the report resolves; the host owns probe cancellation and resources.

Errors and rejections

Rejects invalid/duplicate check definitions or an invalid report timestamp. Probe errors become failed results rather than rejections.

Example

import { runReadinessChecks } from "@alneas/eaos-core/health";
const report = await runReadinessChecks([{ id: "configuration", run: () => true }]);
console.log(report.state); // ready

[INTERFACE] `RuntimePlacementPolicy`

Responsibilities and restrictions for edge, application worker and AI hosts.

Imports: @alneas/eaos-core, @alneas/eaos-core/agentic, @alneas/eaos-core/agentic/runtime-policy.

Signature

interface RuntimePlacementPolicy {
    version: typeof AGENT_RUNTIME_POLICY_VERSION;
    edge: {
        agentRuntime: 'forbidden';
        modelInference: 'forbidden';
        publicIngress: 'allowed';
    };
    applicationWorker: {
        agentRuntime: 'dispatch-only';
        durableQueue: 'outbox-or-host-queue';
        workflowState: 'shared-control-database';
    };
    ai: {
        publicIngress: 'forbidden';
        agentRuntime: AgentRuntimeResourcePolicy;
        retrieval: 'ruri-adapter';
    };
}

Parameters

Name	Type	Required	Description
`version`	`typeof AGENT_RUNTIME_POLICY_VERSION`	Yes	Resource/placement contract version fixed to AGENT_RUNTIME_POLICY_VERSION.
`edge`	`{ agentRuntime: 'forbidden'; modelInference: 'forbidden'; publicIngress: 'allowed'; }`	Yes	Public edge placement restrictions; agent runtimes and model inference are forbidden.
`applicationWorker`	`{ agentRuntime: 'dispatch-only'; durableQueue: 'outbox-or-host-queue'; workflowState: 'shared-control-database'; }`	Yes	Application-host dispatch, durable queue and workflow-state responsibilities.
`ai`	`{ publicIngress: 'forbidden'; agentRuntime: AgentRuntimeResourcePolicy; retrieval: 'ruri-adapter'; }`	Yes	AI host placement and resource requirements.

Returns

Type declaration; no runtime value.

Public members

`version`

Resource/placement contract version fixed to AGENT_RUNTIME_POLICY_VERSION.

`edge`

Public edge placement restrictions; agent runtimes and model inference are forbidden.

`edge.agentRuntime`

Role-specific permission or AI-host resource policy for running agents; configuration alone does not enforce it.

`edge.modelInference`

Whether the host role may execute model inference.

`edge.publicIngress`

Whether this host role may accept public traffic; the default permits edge and forbids AI ingress.

`applicationWorker`

Application-host dispatch, durable queue and workflow-state responsibilities.

`applicationWorker.agentRuntime`

Role-specific permission or AI-host resource policy for running agents; configuration alone does not enforce it.

`applicationWorker.durableQueue`

Host durable queue boundary; outbox or another host queue must back dispatch.

`applicationWorker.workflowState`

Host location for durable workflow state.

`ai`

AI host placement and resource requirements.

`ai.publicIngress`

Whether this host role may accept public traffic; the default permits edge and forbids AI ingress.

`ai.agentRuntime`

Role-specific permission or AI-host resource policy for running agents; configuration alone does not enforce it.

`ai.retrieval`

Host retrieval capability or placement binding; indexing remains host-owned.

Example

See the owning declaration and linked feature guide for usage; no standalone example is documented in source.

[TYPE] `SameSite`

Cookie SameSite policy names accepted by platform configuration.

Imports: @alneas/eaos-core/platform/config.

Signature

type SameSite = 'Lax' | 'Strict' | 'None';

Parameters

Name	Type	Required	Description
—	—	—	No call parameters.

Returns

Type declaration; no runtime value.

Example

See the owning declaration and linked feature guide for usage; no standalone example is documented in source.

[INTERFACE] `SandboxExecutionRequest`

Script and execution metadata passed to the sandbox/desktop bridge.

Imports: @alneas/eaos-core, @alneas/eaos-core/agentic, @alneas/eaos-core/agentic/types.

Signature

interface SandboxExecutionRequest {
    taskId: string;
    agentId: string;
    language: 'python' | 'bash' | 'javascript';
    code: string;
    environmentVariables?: Record<string, string>;
    timeoutMs?: number;
}

Parameters

Name	Type	Required	Description
`taskId`	`string`	Yes	Task identity correlating the agent/runtime operation with its owning workflow or task board.
`agentId`	`string`	Yes	Agent identity associated with the session, execution or assignment.
`language`	`'python' \| 'bash' \| 'javascript'`	Yes	Declared source language for sandbox metadata; simulated container mode does not execute it.
`code`	`string`	Yes	Script/prompt source sent to the selected bridge; docker_cloud only simulates processing and Tauri passes this as its CLI prompt.
`environmentVariables`	`Record<string, string>`	No	Optional requested execution bindings; the legacy sandbox does not apply them.
`timeoutMs`	`number`	No	Optional execution deadline in milliseconds; enforcement belongs to the API/runtime consuming this metadata.

Returns

Type declaration; no runtime value.

Public members

`taskId`

Task identity correlating the agent/runtime operation with its owning workflow or task board.

`agentId`

Agent identity associated with the session, execution or assignment.

`language`

Declared source language for sandbox metadata; simulated container mode does not execute it.

`code`

Script/prompt source sent to the selected bridge; docker_cloud only simulates processing and Tauri passes this as its CLI prompt.

`environmentVariables`

Optional requested execution bindings; the legacy sandbox does not apply them.

`timeoutMs`

Optional execution deadline in milliseconds; enforcement belongs to the API/runtime consuming this metadata.

Example

See the owning declaration and linked feature guide for usage; no standalone example is documented in source.

[INTERFACE] `SandboxExecutionResult`

Reported execution identity, exit code, streams and elapsed time.

Imports: @alneas/eaos-core, @alneas/eaos-core/agentic, @alneas/eaos-core/agentic/types.

Signature

interface SandboxExecutionResult {
    executionId: string;
    exitCode: number;
    stdout: string;
    stderr: string;
    executionTimeMs: number;
    error?: string;
}

Parameters

Name	Type	Required	Description
`executionId`	`string`	Yes	Host/provider execution identity; the legacy sandbox may generate this for a simulated result.
`exitCode`	`number`	Yes	Reported process exit code; zero may be simulated by the legacy sandbox.
`stdout`	`string`	Yes	Reported standard output text; the legacy sandbox may synthesize it.
`stderr`	`string`	Yes	Reported standard error text.
`executionTimeMs`	`number`	Yes	Reported elapsed execution time in milliseconds; it may describe simulated execution for the legacy sandbox.
`error`	`string`	No	Optional human-readable failure detail; absence does not independently establish success.

Returns

Type declaration; no runtime value.

Public members

`executionId`

Host/provider execution identity; the legacy sandbox may generate this for a simulated result.

`exitCode`

Reported process exit code; zero may be simulated by the legacy sandbox.

`stdout`

Reported standard output text; the legacy sandbox may synthesize it.

`stderr`

Reported standard error text.

`executionTimeMs`

Reported elapsed execution time in milliseconds; it may describe simulated execution for the legacy sandbox.

`error`

Optional human-readable failure detail; absence does not independently establish success.

Example

See the owning declaration and linked feature guide for usage; no standalone example is documented in source.

[INTERFACE] `SanitizationResult`

Original and masked prompt plus detected patterns and recommended model tier.

Imports: @alneas/eaos-core, @alneas/eaos-core/agentic, @alneas/eaos-core/agentic/types.

Signature

interface SanitizationResult {
    originalPrompt: string;
    sanitizedPrompt: string;
    detectedPiiTypes: string[];
    sensitivityLevel: DataSensitivityLevel;
    appliedMaskings: Record<string, string>;
    recommendedTier: ModelTier;
}

Parameters

Name	Type	Required	Description
`originalPrompt`	`string`	Yes	Unmodified prompt retained for caller use; may contain sensitive data.
`sanitizedPrompt`	`string`	Yes	Prompt after recognized phone/email pattern replacement; detection is heuristic and incomplete.
`detectedPiiTypes`	`string[]`	Yes	Names of phone/email patterns recognized by the heuristic scanner.
`sensitivityLevel`	`DataSensitivityLevel`	Yes	Classification used by the host to constrain eligible execution routes.
`appliedMaskings`	`Record<string, string>`	Yes	Original sensitive text mapped to generated placeholders; protect this map as sensitive data.
`recommendedTier`	`ModelTier`	Yes	Model tier suggested by heuristic classification; not a provider-policy guarantee.

Returns

Type declaration; no runtime value.

Public members

`originalPrompt`

Unmodified prompt retained for caller use; may contain sensitive data.

`sanitizedPrompt`

Prompt after recognized phone/email pattern replacement; detection is heuristic and incomplete.

`detectedPiiTypes`

Names of phone/email patterns recognized by the heuristic scanner.

`sensitivityLevel`

Classification used by the host to constrain eligible execution routes.

`appliedMaskings`

Original sensitive text mapped to generated placeholders; protect this map as sensitive data.

`recommendedTier`

Model tier suggested by heuristic classification; not a provider-policy guarantee.

Example

See the owning declaration and linked feature guide for usage; no standalone example is documented in source.

[INTERFACE] `SchemaConfig`

Plugin table ownership, shared data dependencies, migration order and storage policy metadata.

Imports: @alneas/eaos-core, @alneas/eaos-core/plugin-sdk, @alneas/eaos-core/plugin-sdk/types.

Signature

interface SchemaConfig {
    ownedTables: string[];
    dataContracts?: Record<string, string>;
    externalReferences: Record<string, string[]>;
    migrationOrder: number;
    storage?: PluginStorageConfig;
    storagePolicy: PluginStoragePolicy;
}

Parameters

Name	Type	Required	Description
`ownedTables`	`string[]`	Yes	Legacy private schema ownership. Shared tables belong to data contracts.
`dataContracts`	`Record<string, string>`	No	Optional shared contract IDs mapped to accepted semantic-version ranges.
`externalReferences`	`Record<string, string[]>`	Yes	Referenced table/resource names grouped by owning external component.
`migrationOrder`	`number`	Yes	Numeric plugin migration order used by registry sorting; lower values sort first.
`storage`	`PluginStorageConfig`	No	Physical record table and namespace used when several plugins share a foundation table.
`storagePolicy`	`PluginStoragePolicy`	Yes	Required per-plugin payload, object-storage, history and archive policy.

Returns

Type declaration; no runtime value.

Public members

`ownedTables`

Legacy private schema ownership. Shared tables belong to data contracts.

`dataContracts`

Optional shared contract IDs mapped to accepted semantic-version ranges.

`externalReferences`

Referenced table/resource names grouped by owning external component.

`migrationOrder`

Numeric plugin migration order used by registry sorting; lower values sort first.

`storage`

Physical record table and namespace used when several plugins share a foundation table.

`storagePolicy`

Required per-plugin payload, object-storage, history and archive policy.

Example

See the owning declaration and linked feature guide for usage; no standalone example is documented in source.

[INTERFACE] `SchemaMigrationSource`

Plugin migration list plus optional shared contract requirements and releases.

Imports: @alneas/eaos-core, @alneas/eaos-core/data-contracts, @alneas/eaos-core/contracts/data-contracts.

Signature

interface SchemaMigrationSource {
    migrations: PluginMigration[];
    schemaDependencies?: Record<string, string>;
    schemaContracts?: DataContract[];
}

Parameters

Name	Type	Required	Description
`migrations`	`PluginMigration[]`	Yes	Ordered driver-specific migration declarations; collecting them does not execute SQL.
`schemaDependencies`	`Record<string, string>`	No	Required data-contract IDs mapped to accepted semver ranges.
`schemaContracts`	`DataContract[]`	No	Optional data-contract releases supplied alongside this migration source.

Returns

Type declaration; no runtime value.

Public members

`migrations`

Ordered driver-specific migration declarations; collecting them does not execute SQL.

`schemaDependencies`

Required data-contract IDs mapped to accepted semver ranges.

`schemaContracts`

Optional data-contract releases supplied alongside this migration source.

Example

See the owning declaration and linked feature guide for usage; no standalone example is documented in source.

[INTERFACE] `SecretResolveOptions`

Environment key and optional required flag for host secret declarations.

Imports: @alneas/eaos-core, @alneas/eaos-core/secrets/secret-resolver.

Signature

interface SecretResolveOptions {
    envKey: string;
    required?: boolean;
}

Parameters

Name	Type	Required	Description
`envKey`	`string`	Yes	Exact environment variable name to resolve; declarations contain names rather than secret values.
`required`	`boolean`	No	Whether an unresolved environment secret must fail validation; resolver calls default to true when the flag is omitted.

Returns

Type declaration; no runtime value.

Public members

`envKey`

Exact environment variable name to resolve; declarations contain names rather than secret values.

`required`

Whether an unresolved environment secret must fail validation; resolver calls default to true when the flag is omitted.

Example

See the owning declaration and linked feature guide for usage; no standalone example is documented in source.

[CLASS] `SecretResolver`

Resolve and cache process environment secrets through static methods.

Imports: @alneas/eaos-core, @alneas/eaos-core/secrets/secret-resolver.

Signature

declare class SecretResolver {
    static getSecret(envKey: string, required?: boolean): Promise<string>;
    static validatePluginSecrets(pluginId: string, secretRequirements: Array<{
        envKey: string;
        required: boolean;
    }>): Promise<void>;
    static clearCache(): void;
}

Parameters

Name	Type	Required	Description
—	—	—	No call parameters.

Returns

SecretResolver

Remarks

Requires process.env. The current OCI fallback only inspects environment values and does not perform a Vault API request; it must not be treated as a connected Vault client. Cache is global to this class and does not expire. Missing optional values return an empty string without caching.

Public members

`getSecret`

Read a cached or nonblank environment value, failing when a required secret is absent.

Parameters:

envKey: Exact process.env key.
required: Whether an unresolved value rejects; defaults to true.

Returns: Resolved secret, including original whitespace, or empty string when optional and missing.

Remarks

Successful values are cached across calls until clearCache; OCI fallback failures are logged. No secret is persisted.

Errors and rejections

Rejects with Error when a required secret is unavailable; process access errors propagate.

Example:

import { SecretResolver } from "@alneas/eaos-core/secrets/secret-resolver";
const secret = await SecretResolver.getSecret("EAOS_OPTIONAL_TEST_SECRET", false);
console.log(secret.length > 0);

`validatePluginSecrets`

Resolve plugin secret declarations sequentially during startup.

Parameters:

pluginId: Plugin identifier accepted for call-site context; currently unused by the implementation.
secretRequirements: Environment key and required flag for each secret; optional missing entries do not fail validation.

Returns: No value; all declarations resolved or were optional and missing.

Remarks

May populate the shared cache; earlier resolutions remain cached if a later one fails.

Errors and rejections

Rejects on the first required missing secret or propagated resolver failure.

Example:

import { SecretResolver } from "@alneas/eaos-core/secrets/secret-resolver";
await SecretResolver.validatePluginSecrets("notes", [{ envKey: "EAOS_OPTIONAL_TEST_SECRET", required: false }]);

`validatePluginSecrets.secretRequirements[].envKey`

Exact environment variable name to resolve; declarations contain names rather than secret values.

`validatePluginSecrets.secretRequirements[].required`

Whether an unresolved environment secret must fail validation; resolver calls default to true when the flag is omitted.

`clearCache`

Remove all resolved values from the shared in-memory cache.

Returns: No value; subsequent lookups read the environment again.

Example:

import { SecretResolver } from "@alneas/eaos-core/secrets/secret-resolver";
SecretResolver.clearCache();

Example

import { SecretResolver } from "@alneas/eaos-core/secrets/secret-resolver";
const secret = await SecretResolver.getSecret("EAOS_OPTIONAL_TEST_SECRET", false);
console.log(secret.length > 0);
SecretResolver.clearCache();

[FUNCTION] `selectPluginBundles`

Select and de-duplicate plugins from one or more user-facing bundles.

Imports: @alneas/eaos-core, @alneas/eaos-core/plugin-bundles.

Signature

declare function selectPluginBundles<T extends BundlePlugin>(catalog: PluginBundleCatalog<T>, names: readonly string[]): readonly T[];

Parameters

Name	Type	Required	Description
`catalog`	`PluginBundleCatalog<T>`	Yes	Bundle-name to ordered plugin references.
`names`	`readonly string[]`	Yes	Bundle names visited in supplied order; repeats are allowed.

Returns

readonly T[]

A new array ordered by first occurrence of each ID, containing its last encountered plugin reference; empty names yield an empty result.

Type parameters

T: Plugin-shaped values whose original references are returned.

Errors and rejections

Error when a requested bundle name is unknown.

Example

import { selectPluginBundles } from "@alneas/eaos-core/plugin-bundles";
console.log(selectPluginBundles({ basic: [{ id: "notes" }] }, ["basic"]).map(plugin => plugin.id));

[INTERFACE] `ServiceConfig`

Optional service name and listener-port overrides.

Imports: @alneas/eaos-core/platform/config.

Signature

interface ServiceConfig {
    name?: string;
    port?: number;
}

Parameters

Name	Type	Required	Description
`name`	`string`	No	Optional lowercase DNS service label; service-specific defaults are resolved by resolvePlatformConfig.
`port`	`number`	No	Optional integer listener port from 1 to 65535; defaults are backend 3000, frontend 80 and Kratos public 4433.

Returns

Type declaration; no runtime value.

Public members

`name`

Optional lowercase DNS service label; service-specific defaults are resolved by resolvePlatformConfig.

`port`

Optional integer listener port from 1 to 65535; defaults are backend 3000, frontend 80 and Kratos public 4433.

Example

See the owning declaration and linked feature guide for usage; no standalone example is documented in source.

[INTERFACE] `SessionHookPayload`

Session identity and optional host metadata for startup hooks.

Imports: @alneas/eaos-core, @alneas/eaos-core/agentic, @alneas/eaos-core/agentic/runtime.

Signature

interface SessionHookPayload {
    sessionId: string;
    tenantId: string;
    userId: string;
    metadata?: Record<string, unknown>;
}

Parameters

Name	Type	Required	Description
`sessionId`	`string`	Yes	Host session identity used to correlate lifecycle callbacks and operations.
`tenantId`	`string`	Yes	Verified tenant boundary for the record or operation; host authorization must establish this scope.
`userId`	`string`	Yes	User identity within the tenant supplied by the trusted host.
`metadata`	`Record<string, unknown>`	No	Optional host/provider metadata; callers remain responsible for sensitive content and validation.

Returns

Type declaration; no runtime value.

Public members

`sessionId`

Host session identity used to correlate lifecycle callbacks and operations.

`tenantId`

Verified tenant boundary for the record or operation; host authorization must establish this scope.

`userId`

User identity within the tenant supplied by the trusted host.

`metadata`

Optional host/provider metadata; callers remain responsible for sensitive content and validation.

Example

See the owning declaration and linked feature guide for usage; no standalone example is documented in source.

[TYPE] `SessionStartHookHandler`

Startup callback awaited in registration order with failures logged.

Imports: @alneas/eaos-core, @alneas/eaos-core/agentic, @alneas/eaos-core/agentic/runtime.

Signature

type SessionStartHookHandler = (payload: SessionHookPayload) => Promise<void> | void;

Parameters

Name	Type	Required	Description
—	—	—	No call parameters.

Returns

Type declaration; no runtime value.

No value, or a Promise for startup completion; AgentRuntime awaits hooks sequentially and logs failures.

Example

import type { SessionStartHookHandler } from "@alneas/eaos-core/agentic/runtime";
const hook: SessionStartHookHandler = payload => { console.log(payload.sessionId); };

[FUNCTION] `sha256Digest`

Hash text or bytes with SHA-256.

Imports: @alneas/eaos-core, @alneas/eaos-core/serialization.

Signature

declare function sha256Digest(value: string | Uint8Array): string;

Parameters

Name	Type	Required	Description
`value`	`string \| Uint8Array`	Yes	UTF-8 text or bytes to hash.

Returns

string

A lowercase hexadecimal digest.

Remarks

Requires the Node-compatible node:crypto module. Input is not modified.

Example

import { sha256Digest } from "@alneas/eaos-core/serialization";
console.log(sha256Digest("hello"));

[INTERFACE] `SignatureVerification`

Signature comparison result and optional diagnostic error text.

Imports: @alneas/eaos-core, @alneas/eaos-core/webhook, @alneas/eaos-core/webhook/delivery.

Signature

interface SignatureVerification {
    valid: boolean;
    error?: string;
}

Parameters

Name	Type	Required	Description
`valid`	`boolean`	Yes	Whether signature verification succeeded; does not prove timestamp freshness or replay safety.
`error`	`string`	No	Optional human-readable failure detail; absence does not independently establish success.

Returns

Type declaration; no runtime value.

Public members

`valid`

Whether signature verification succeeded; does not prove timestamp freshness or replay safety.

`error`

Optional human-readable failure detail; absence does not independently establish success.

Example

See the owning declaration and linked feature guide for usage; no standalone example is documented in source.

[FUNCTION] `signPayload`

Sign raw text or a JSON-serialized payload with HMAC-SHA256.

Imports: @alneas/eaos-core, @alneas/eaos-core/webhook, @alneas/eaos-core/webhook/delivery.

Signature

declare function signPayload(payload: unknown, secret: string): string;

Parameters

Name	Type	Required	Description
`payload`	`unknown`	Yes	Raw text is signed verbatim; other values are serialized with JSON.stringify.
`secret`	`string`	Yes	Shared HMAC secret.

Returns

string

Lowercase hexadecimal signature over the body, without a timestamp prefix.

Remarks

Requires node:crypto; payload signing alone provides no replay protection.

Errors and rejections

Native JSON serialization or crypto errors propagate, including cycles, bigint and undefined serialization output.

Example

import { signPayload } from "@alneas/eaos-core/webhook/delivery";
console.log(signPayload({ event: "demo" }, "example-only-secret"));

[INTERFACE] `SkillCatalog`

Tenant/user-scoped host discovery boundary for skill metadata.

Imports: @alneas/eaos-core, @alneas/eaos-core/ai, @alneas/eaos-core/ai/governance.

Signature

interface SkillCatalog {
    list(context: Pick<AIExecutionContext, 'tenantId' | 'userId'>): Promise<readonly SkillCatalogEntry[]>;
}

Parameters

Name	Type	Required	Description
`list`	`Promise<readonly SkillCatalogEntry[]>`	Yes	List skill metadata visible to a verified tenant/user.

Returns

Type declaration; no runtime value.

Public members

`list`

List skill metadata visible to a verified tenant/user.

Parameters:

context: Trusted tenant/user identities used by the host discovery implementation.

Returns: Visible catalog entries, possibly empty.

Remarks

Host owns authorization/discovery sources; catalog metadata does not authorize executing a skill.

Errors and rejections

Host discovery failures reject the Promise.

Example:

import type { SkillCatalog } from "@alneas/eaos-core/ai/governance";
async function listHostSkills(catalog: SkillCatalog) { return catalog.list({ tenantId: "tenant-demo", userId: "user-demo" }); }

Example

See the owning declaration and linked feature guide for usage; no standalone example is documented in source.

[INTERFACE] `SkillCatalogEntry`

Provider-neutral skill metadata. The executable binding remains a plugin action/MCP tool.

Imports: @alneas/eaos-core, @alneas/eaos-core/ai, @alneas/eaos-core/ai/governance.

Signature

interface SkillCatalogEntry {
    id: string;
    name: string;
    description: string;
    documentPath?: string;
    version?: string;
    category?: string;
    tags?: readonly string[];
    triggers?: readonly string[];
    dependencies?: readonly string[];
    requirements?: SkillRequirement;
    capabilities?: readonly string[];
    actionNames?: readonly string[];
    verificationGates?: readonly string[];
}

Parameters

Name	Type	Required	Description
`id`	`string`	Yes	Stable skill discovery identity; omitted document paths use its final dot-separated segment.
`name`	`string`	Yes	Human-readable display name supplied by the plugin/provider catalog; distinct from the stable ID.
`description`	`string`	Yes	Human-readable metadata describing the capability, workflow node or requirement to host users.
`documentPath`	`string`	No	Relative path to the packaged instruction document, resolved by the host loader.
`version`	`string`	No	Optional packaged skill version advertised for host discovery.
`category`	`string`	No	Optional host discovery category for filtering/grouping skills.
`tags`	`readonly string[]`	No	Optional discovery/search labels carried as metadata.
`triggers`	`readonly string[]`	No	Discovery phrases or events advertised for skill selection; execution remains action-bound.
`dependencies`	`readonly string[]`	No	Declared prerequisites; shared data contracts use ID-to-semver ranges and plugin/skill metadata uses identity lists.
`requirements`	`SkillRequirement`	No	Optional prerequisite declaration used by trusted host availability checks.
`capabilities`	`readonly string[]`	No	Advertised operation/capability names; presence alone does not authorize execution.
`actionNames`	`readonly string[]`	No	Host action names a skill may use after normal authorization.
`verificationGates`	`readonly string[]`	No	Named host checks expected before treating the skill result as accepted.

Returns

Type declaration; no runtime value.

Public members

`id`

Stable skill discovery identity; omitted document paths use its final dot-separated segment.

`name`

Human-readable display name supplied by the plugin/provider catalog; distinct from the stable ID.

`description`

Human-readable metadata describing the capability, workflow node or requirement to host users.

`documentPath`

Relative path to the packaged instruction document, resolved by the host loader.

`version`

Optional packaged skill version advertised for host discovery.

`category`

Optional host discovery category for filtering/grouping skills.

`tags`

Optional discovery/search labels carried as metadata.

`triggers`

Discovery phrases or events advertised for skill selection; execution remains action-bound.

`dependencies`

Declared prerequisites; shared data contracts use ID-to-semver ranges and plugin/skill metadata uses identity lists.

`requirements`

Optional prerequisite declaration used by trusted host availability checks.

`capabilities`

Advertised operation/capability names; presence alone does not authorize execution.

`actionNames`

Host action names a skill may use after normal authorization.

`verificationGates`

Named host checks expected before treating the skill result as accepted.

Example

See the owning declaration and linked feature guide for usage; no standalone example is documented in source.

[INTERFACE] `SkillDocument`

Loaded instruction body with its owning plugin, metadata and package-relative path.

Imports: @alneas/eaos-core, @alneas/eaos-core/ai, @alneas/eaos-core/ai/governance.

Signature

interface SkillDocument {
    pluginId: string;
    skill: SkillCatalogEntry;
    path: string;
    content: string;
}

Parameters

Name	Type	Required	Description
`pluginId`	`string`	Yes	Owning plugin identity used for capability scope and discovery.
`skill`	`SkillCatalogEntry`	Yes	Original catalog metadata associated with the loaded/discovered skill.
`path`	`string`	Yes	Host-resolved package-relative instruction document path.
`content`	`string`	Yes	Loaded skill instructions, model response text or proposed file content; treat external text as untrusted input.

Returns

Type declaration; no runtime value.

Public members

`pluginId`

Owning plugin identity used for capability scope and discovery.

`skill`

Original catalog metadata associated with the loaded/discovered skill.

`path`

Host-resolved package-relative instruction document path.

`content`

Loaded skill instructions, model response text or proposed file content; treat external text as untrusted input.

Example

See the owning declaration and linked feature guide for usage; no standalone example is documented in source.

[INTERFACE] `SkillDocumentLoader`

Host-owned package/document access; core never reads the filesystem or process state.

Imports: @alneas/eaos-core, @alneas/eaos-core/ai, @alneas/eaos-core/ai/governance.

Signature

interface SkillDocumentLoader {
    load(input: {
        pluginId: string;
        path: string;
        skill: SkillCatalogEntry;
    }): Promise<string> | string;
}

Parameters

Name	Type	Required	Description
`load`	`Promise<string> \| string`	Yes	Read a packaged skill document through host-controlled access.

Returns

Type declaration; no runtime value.

Public members

`load`

Read a packaged skill document through host-controlled access.

Parameters:

input: Plugin ID, validated package-relative path and original skill metadata.

Returns: Instruction text, directly or asynchronously; registry loading rejects blank/nonstring content.

Remarks

Host owns safe filesystem/package resolution, access control and resource cleanup; Core reads no filesystem here.

Errors and rejections

Host access/read errors/rejections propagate to the registry/caller.

Example:

import type { SkillDocumentLoader } from "@alneas/eaos-core/ai/governance";
async function loadHostDocument(loader: SkillDocumentLoader, input: Parameters<SkillDocumentLoader["load"]>[0]) { return loader.load(input); }

`load.input.pluginId`

Owning plugin identity used for capability scope and discovery.

`load.input.path`

Safe relative packaged instruction path supplied by the registry; the loader must prevent resolution escapes.

`load.input.skill`

Original catalog metadata associated with the loaded/discovered skill.

Example

See the owning declaration and linked feature guide for usage; no standalone example is documented in source.

[INTERFACE] `SkillEligibilityResult`

Eligibility and ordered descriptors for unmet requirements.

Imports: @alneas/eaos-core, @alneas/eaos-core/ai, @alneas/eaos-core/ai/skills.

Signature

interface SkillEligibilityResult {
    eligible: boolean;
    missing: readonly string[];
}

Parameters

Name	Type	Required	Description
`eligible`	`boolean`	Yes	Whether all declared host requirements were satisfied.
`missing`	`readonly string[]`	Yes	Ordered unmet requirement descriptors; an empty array accompanies eligible true.

Returns

Type declaration; no runtime value.

Public members

`eligible`

Whether all declared host requirements were satisfied.

`missing`

Ordered unmet requirement descriptors; an empty array accompanies eligible true.

Example

See the owning declaration and linked feature guide for usage; no standalone example is documented in source.

[CLASS] `SkillGateBridge`

Map named skill policies to gatekeeper decisions and runtime hooks.

Imports: @alneas/eaos-core, @alneas/eaos-core/agentic, @alneas/eaos-core/agentic/skill-gate-bridge.

Signature

declare class SkillGateBridge {
    constructor(gatekeeper: McpGatekeeper, runtime: AgentRuntime);
    registerSkillGate(skill: SkillGateDefinition): void;
    evaluateAndExecuteSkill<T = unknown>(skillName: string, args: Record<string, unknown>, context: AgentExecutionContext, skillExecutor: (args: Record<string, unknown>) => Promise<T>): Promise<{
        success: boolean;
        result?: T | undefined;
        error?: string;
        status: "COMPLETED" | "BLOCKED" | "PENDING_APPROVAL";
        riskLevel?: RiskLevel;
    } | {
        success: boolean;
        status: "PENDING_APPROVAL";
        approvalLevel: ApprovalLevel;
        riskLevel: RiskLevel;
        error: string;
    }>;
}

Parameters

Name	Type	Required	Description
`gatekeeper`	`McpGatekeeper`	Yes	Policy registry used before skill execution.
`runtime`	`AgentRuntime`	Yes	Hook engine called only after the policy allows execution without pending approval.

Returns

SkillGateBridge

Remarks

Does not load skill files or evaluate whenToActivate/version/category. Registration replaces a gatekeeper policy; the host supplies trusted scope and owns any approval workflow.

Constructor contract

Public members

`registerSkillGate`

Parameters:

skill: Name, roles, risk and approval metadata; risk defaults to low. Human approval is computed from the supplied approvalLevel/riskLevel combination.

Returns: No value; named policy has been replaced.

Remarks

Activation triggers, version and category are metadata only; empty role arrays deny users unless they carry an admin override in the gatekeeper.

Example:

import { SkillGateBridge } from "@alneas/eaos-core/agentic/skill-gate-bridge";
import { McpGatekeeper } from "@alneas/eaos-core/security/gatekeeper";
import { AgentRuntime } from "@alneas/eaos-core/agentic/runtime";
const bridge = new SkillGateBridge(new McpGatekeeper(), new AgentRuntime());
bridge.registerSkillGate({ skillName: "notes.preview", version: "1", category: "notes", riskLevel: "low", whenToActivate: [] });

`evaluateAndExecuteSkill`

Check skill policy and execute through runtime hooks when no review is required.

Parameters:

skillName: Policy/tool name to resolve.
args: Arguments passed to runtime hooks after admission.
context: Verified host tenant/user roles and execution scope.
skillExecutor: Asynchronous callback receiving final hook-modified arguments; called only after policy/hook admission.

Returns: BLOCKED or PENDING_APPROVAL data when denied/deferred; otherwise the runtime execution result.

Type parameters

T: Resolved domain output from the supplied executor; defaults to unknown.

Remarks

An unregistered skill follows gatekeeper default policy. No approval is granted, recorded or resumed here; no cancellation/retry is provided.

Errors and rejections

Runtime pre-hook errors/rejections propagate; executor errors are normally returned as BLOCKED data.

Example:

import { SkillGateBridge } from "@alneas/eaos-core/agentic/skill-gate-bridge";
import { McpGatekeeper } from "@alneas/eaos-core/security/gatekeeper";
import { AgentRuntime } from "@alneas/eaos-core/agentic/runtime";
const bridge = new SkillGateBridge(new McpGatekeeper(), new AgentRuntime());
const context = { tenantId: "tenant-demo", userId: "user-demo", sessionId: "session-1", traceId: "trace-1", userRoles: ["member"] };
console.log(await bridge.evaluateAndExecuteSkill("notes.preview", {}, context, async () => ({ count: 0 })));

Example

import { SkillGateBridge } from "@alneas/eaos-core/agentic/skill-gate-bridge";
import { McpGatekeeper } from "@alneas/eaos-core/security/gatekeeper";
import { AgentRuntime } from "@alneas/eaos-core/agentic/runtime";
const bridge = new SkillGateBridge(new McpGatekeeper(), new AgentRuntime());
bridge.registerSkillGate({ skillName: "notes.preview", version: "1", category: "notes", riskLevel: "low", whenToActivate: [] });

[INTERFACE] `SkillGateDefinition`

Skill policy metadata mapped to a named gatekeeper policy.

Imports: @alneas/eaos-core, @alneas/eaos-core/agentic, @alneas/eaos-core/agentic/skill-gate-bridge.

Signature

interface SkillGateDefinition {
    skillName: string;
    version: string;
    category: string;
    approvalLevel?: ApprovalLevel;
    riskLevel?: RiskLevel;
    requiredRoles?: string[];
    whenToActivate: string[];
}

Parameters

Name	Type	Required	Description
`skillName`	`string`	Yes	Exact policy/tool identity used when registering and evaluating this skill gate.
`version`	`string`	Yes	Skill metadata version; SkillGateBridge does not use it in policy evaluation.
`category`	`string`	Yes	Skill discovery classification; SkillGateBridge does not use it for gatekeeper evaluation.
`approvalLevel`	`ApprovalLevel`	No	Required organizational review category; a level declaration is not proof of approval.
`riskLevel`	`RiskLevel`	No	Declared operation risk used to determine review requirements; it does not itself grant authorization.
`requiredRoles`	`string[]`	No	Optional allowed role names mapped to the gatekeeper policy.
`whenToActivate`	`string[]`	Yes	Discovery trigger metadata; SkillGateBridge does not evaluate it.

Returns

Type declaration; no runtime value.

Public members

`skillName`

Exact policy/tool identity used when registering and evaluating this skill gate.

`version`

Skill metadata version; SkillGateBridge does not use it in policy evaluation.

`category`

Skill discovery classification; SkillGateBridge does not use it for gatekeeper evaluation.

`approvalLevel`

Required organizational review category; a level declaration is not proof of approval.

`riskLevel`

Declared operation risk used to determine review requirements; it does not itself grant authorization.

`requiredRoles`

Optional allowed role names mapped to the gatekeeper policy.

`whenToActivate`

Discovery trigger metadata; SkillGateBridge does not evaluate it.

Example

See the owning declaration and linked feature guide for usage; no standalone example is documented in source.

[INTERFACE] `SkillRequirement`

Host OS, executable, environment/config-name and adapter prerequisites for a skill.

Imports: @alneas/eaos-core, @alneas/eaos-core/ai, @alneas/eaos-core/ai/governance.

Signature

interface SkillRequirement {
    bins?: readonly string[];
    anyBins?: readonly string[];
    env?: readonly string[];
    config?: readonly string[];
    adapters?: readonly AIHostAdapterName[];
    os?: readonly ('darwin' | 'linux' | 'win32')[];
}

Parameters

Name	Type	Required	Description
`bins`	`readonly string[]`	No	Executable names that must all be present in trusted host availability.
`anyBins`	`readonly string[]`	No	Alternative executable names; at least one must be available when this list is nonempty.
`env`	`readonly string[]`	No	Required/available environment variable names only; secret values are not stored here.
`config`	`readonly string[]`	No	Host configuration metadata; plugin/node configuration is data and does not execute code by itself.
`adapters`	`readonly AIHostAdapterName[]`	No	Required/available host capability families used during skill eligibility checks.
`os`	`readonly ('darwin' \| 'linux' \| 'win32')[]`	No	Supported/current host operating system used by skill eligibility.

Returns

Type declaration; no runtime value.

Public members

`bins`

Executable names that must all be present in trusted host availability.

`anyBins`

Alternative executable names; at least one must be available when this list is nonempty.

`env`

Required/available environment variable names only; secret values are not stored here.

`config`

Host configuration metadata; plugin/node configuration is data and does not execute code by itself.

`adapters`

Required/available host capability families used during skill eligibility checks.

`os`

Supported/current host operating system used by skill eligibility.

Example

See the owning declaration and linked feature guide for usage; no standalone example is documented in source.

[INTERFACE] `SkillRuntimeAvailability`

Runtime facts supplied by a trusted host when selecting eligible skills.

Imports: @alneas/eaos-core, @alneas/eaos-core/ai, @alneas/eaos-core/ai/skills.

Signature

interface SkillRuntimeAvailability {
    os: 'darwin' | 'linux' | 'win32';
    bins?: ReadonlySet<string> | readonly string[];
    env?: ReadonlySet<string> | readonly string[];
    config?: ReadonlySet<string> | readonly string[];
    adapters?: ReadonlySet<string> | readonly string[];
}

Parameters

Name	Type	Required	Description
`os`	`'darwin' \| 'linux' \| 'win32'`	Yes	Supported/current host operating system used by skill eligibility.
`bins`	`ReadonlySet<string> \| readonly string[]`	No	Executable names that must all be present in trusted host availability.
`env`	`ReadonlySet<string> \| readonly string[]`	No	Required/available environment variable names only; secret values are not stored here.
`config`	`ReadonlySet<string> \| readonly string[]`	No	Host configuration metadata; plugin/node configuration is data and does not execute code by itself.
`adapters`	`ReadonlySet<string> \| readonly string[]`	No	Required/available host capability families used during skill eligibility checks.

Returns

Type declaration; no runtime value.

Public members

`os`

Supported/current host operating system used by skill eligibility.

`bins`

Executable names that must all be present in trusted host availability.

`env`

Required/available environment variable names only; secret values are not stored here.

`config`

Host configuration metadata; plugin/node configuration is data and does not execute code by itself.

`adapters`

Required/available host capability families used during skill eligibility checks.

Example

See the owning declaration and linked feature guide for usage; no standalone example is documented in source.

[TYPE] `StopHookHandler`

Stop callback awaited in registration order with failures logged.

Imports: @alneas/eaos-core, @alneas/eaos-core/agentic, @alneas/eaos-core/agentic/runtime.

Signature

type StopHookHandler = (payload: StopHookPayload) => Promise<void> | void;

Parameters

Name	Type	Required	Description
—	—	—	No call parameters.

Returns

Type declaration; no runtime value.

No value, or a Promise for cleanup completion; AgentRuntime awaits hooks sequentially and logs failures.

Example

import type { StopHookHandler } from "@alneas/eaos-core/agentic/runtime";
const hook: StopHookHandler = payload => { console.log(payload.success); };

[INTERFACE] `StopHookPayload`

Stopped session trajectory and host-reported success for cleanup hooks.

Imports: @alneas/eaos-core, @alneas/eaos-core/agentic, @alneas/eaos-core/agentic/runtime.

Signature

interface StopHookPayload {
    sessionId: string;
    tenantId: string;
    userId: string;
    history: Array<{
        role: string;
        content: string;
        timestamp: string;
    }>;
    success: boolean;
}

Parameters

Name	Type	Required	Description
`sessionId`	`string`	Yes	Host session identity used to correlate lifecycle callbacks and operations.
`tenantId`	`string`	Yes	Verified tenant boundary for the record or operation; host authorization must establish this scope.
`userId`	`string`	Yes	User identity within the tenant supplied by the trusted host.
`history`	`Array<{ role: string; content: string; timestamp: string; }>`	Yes	Session turns supplied for lifecycle/extraction; sensitive content handling remains host-owned.
`success`	`boolean`	Yes	Reported completion flag; inspect status/receipt and reconcile any uncertain side effects before retrying.

Returns

Type declaration; no runtime value.

Public members

`sessionId`

Host session identity used to correlate lifecycle callbacks and operations.

`tenantId`

Verified tenant boundary for the record or operation; host authorization must establish this scope.

`userId`

User identity within the tenant supplied by the trusted host.

`history`

Session turns supplied for lifecycle/extraction; sensitive content handling remains host-owned.

`history[].role`

Host conversation-speaker label associated with this history turn.

`history[].content`

Loaded skill instructions, model response text or proposed file content; treat external text as untrusted input.

`history[].timestamp`

Host-recorded turn timestamp carried to stop observers.

`success`

Reported completion flag; inspect status/receipt and reconcile any uncertain side effects before retrying.

Example

See the owning declaration and linked feature guide for usage; no standalone example is documented in source.

[INTERFACE] `StorageAdapter`

Compatibility re-export; its implementation and documentation are owned by the owning package @dataarthub/app-core.

Imports: @alneas/eaos-core, @alneas/eaos-core/adapters, @alneas/eaos-core/adapters/types.

Signature

export interface StorageAdapter {
    upload(key: string, data: Buffer | Blob | ReadableStream | string, options?: StorageUploadOptions): Promise<StorageObject>;
    download(key: string): Promise<Buffer | null>;
    getUrl(key: string, options?: StorageURLOptions): Promise<string>;
    delete(key: string): Promise<boolean>;
    exists(key: string): Promise<boolean>;
    head(key: string): Promise<StorageObject | null>;
    list(options?: StorageListOptions): Promise<StorageListResult>;
    copy?(sourceKey: string, destinationKey: string): Promise<StorageObject>;
    move?(sourceKey: string, destinationKey: string): Promise<StorageObject>;
}

Parameters

Name	Type	Required	Description
`upload`	`Promise<StorageObject>`	Yes	See the upstream owning declaration.
`download`	`Promise<Buffer \| null>`	Yes	See the upstream owning declaration.
`getUrl`	`Promise<string>`	Yes	See the upstream owning declaration.
`delete`	`Promise<boolean>`	Yes	See the upstream owning declaration.
`exists`	`Promise<boolean>`	Yes	See the upstream owning declaration.
`head`	`Promise<StorageObject \| null>`	Yes	See the upstream owning declaration.
`list`	`Promise<StorageListResult>`	Yes	See the upstream owning declaration.
`copy`	`Promise<StorageObject>`	No	See the upstream owning declaration.
`move`	`Promise<StorageObject>`	No	See the upstream owning declaration.

Returns

Type declaration; no runtime value.

Example

See the owning declaration and linked feature guide for usage; no standalone example is documented in source.

[INTERFACE] `StorageBudget`

Tenant soft byte limits and optional warning ratio; absent planes have no default limit.

Imports: @alneas/eaos-core, @alneas/eaos-core/storage.

Signature

interface StorageBudget {
    tenantId: string;
    limits: Partial<Record<StoragePlane, number>>;
    warnAtRatio?: number;
}

Parameters

Name	Type	Required	Description
`tenantId`	`string`	Yes	Verified tenant boundary for the record or operation; host authorization must establish this scope.
`limits`	`Partial<Record<StoragePlane, number>>`	Yes	Soft byte limits are host policy; omitted planes have no framework default.
`warnAtRatio`	`number`	No	Optional warning fraction greater than zero and at most one; no warning is sent by validation.

Returns

Type declaration; no runtime value.

Public members

`tenantId`

Verified tenant boundary for the record or operation; host authorization must establish this scope.

`limits`

Soft byte limits are host policy; omitted planes have no framework default.

`warnAtRatio`

Optional warning fraction greater than zero and at most one; no warning is sent by validation.

Example

See the owning declaration and linked feature guide for usage; no standalone example is documented in source.

[INTERFACE] `StorageCapacityCheck`

Proposed per-tenant storage growth in one plane.

Imports: @alneas/eaos-core, @alneas/eaos-core/storage.

Signature

interface StorageCapacityCheck {
    tenantId: string;
    plane: StoragePlane;
    estimatedBytes: number;
}

Parameters

Name	Type	Required	Description
`tenantId`	`string`	Yes	Verified tenant boundary for the record or operation; host authorization must establish this scope.
`plane`	`StoragePlane`	Yes	Logical storage plane whose capacity is being checked.
`estimatedBytes`	`number`	Yes	Estimated additional bytes requested before a storage write; host policy decides admission.

Returns

Type declaration; no runtime value.

Public members

`tenantId`

Verified tenant boundary for the record or operation; host authorization must establish this scope.

`plane`

Logical storage plane whose capacity is being checked.

`estimatedBytes`

Estimated additional bytes requested before a storage write; host policy decides admission.

Example

See the owning declaration and linked feature guide for usage; no standalone example is documented in source.

[INTERFACE] `StorageCapacityPolicy`

The host owns metering and enforcement; plugins receive a stable capacity boundary.

Imports: @alneas/eaos-core, @alneas/eaos-core/storage.

Signature

interface StorageCapacityPolicy {
    check(input: StorageCapacityCheck): Promise<{
        allowed: boolean;
        reason?: string;
    }>;
}

Parameters

Name	Type	Required	Description
`check`	`Promise<{ allowed: boolean; reason?: string; }>`	Yes	Ask host policy whether estimated storage growth is allowed.

Returns

Type declaration; no runtime value.

Public members

`check`

Ask host policy whether estimated storage growth is allowed.

Parameters:

input: Verified tenant, logical plane and estimated additional bytes.

Returns: Allowed/denied data with an optional explanation.

Remarks

A decision is not a framework reservation; host must define concurrency, metering and enforcement at the write boundary.

Errors and rejections

Host capacity-policy failures reject the Promise.

Example:

import type { StorageCapacityPolicy } from "@alneas/eaos-core/storage";
async function inspectCapacity(policy: StorageCapacityPolicy) { return policy.check({ tenantId: "tenant-demo", plane: "object", estimatedBytes: 1024 }); }

`check.allowed`

Admission/check decision; consumers must inspect it before using the associated result or performing an effect.

`check.reason`

Human-readable explanation of the decision or requested action.

Example

See the owning declaration and linked feature guide for usage; no standalone example is documented in source.

[INTERFACE] `StorageObject`

Compatibility re-export; its implementation and documentation are owned by the owning package @dataarthub/app-core.

Imports: @alneas/eaos-core, @alneas/eaos-core/adapters, @alneas/eaos-core/adapters/types.

Signature

export interface StorageObject {
    key: string;
    size?: number;
    contentType?: string;
    lastModified?: Date;
    etag?: string;
    metadata?: Record<string, string>;
}

Parameters

Name	Type	Required	Description
`key`	`string`	Yes	See the upstream owning declaration.
`size`	`number`	No	See the upstream owning declaration.
`contentType`	`string`	No	See the upstream owning declaration.
`lastModified`	`Date`	No	See the upstream owning declaration.
`etag`	`string`	No	See the upstream owning declaration.
`metadata`	`Record<string, string>`	No	See the upstream owning declaration.

Returns

Type declaration; no runtime value.

Example

See the owning declaration and linked feature guide for usage; no standalone example is documented in source.

[TYPE] `StoragePlane`

Logical storage categories for host measurement and capacity policy.

Imports: @alneas/eaos-core, @alneas/eaos-core/storage.

Signature

type StoragePlane = 'database' | 'object' | 'vector' | 'graph';

Parameters

Name	Type	Required	Description
—	—	—	No call parameters.

Returns

Type declaration; no runtime value.

Example

See the owning declaration and linked feature guide for usage; no standalone example is documented in source.

[INTERFACE] `StorageUsage`

Tenant usage snapshot with byte counts and optional item counts by plane.

Imports: @alneas/eaos-core, @alneas/eaos-core/storage.

Signature

interface StorageUsage {
    tenantId: string;
    measuredAt: string;
    bytes: Partial<Record<StoragePlane, number>>;
    items?: Partial<Record<StoragePlane, number>>;
}

Parameters

Name	Type	Required	Description
`tenantId`	`string`	Yes	Verified tenant boundary for the record or operation; host authorization must establish this scope.
`measuredAt`	`string`	Yes	Parseable timestamp at which host usage was measured.
`bytes`	`Partial<Record<StoragePlane, number>>`	Yes	Measured nonnegative safe-integer bytes for each available storage plane.
`items`	`Partial<Record<StoragePlane, number>>`	No	Optional nonnegative safe-integer item counts for measurable planes.

Returns

Type declaration; no runtime value.

Public members

`tenantId`

Verified tenant boundary for the record or operation; host authorization must establish this scope.

`measuredAt`

Parseable timestamp at which host usage was measured.

`bytes`

Measured nonnegative safe-integer bytes for each available storage plane.

`items`

Optional nonnegative safe-integer item counts for measurable planes.

Example

See the owning declaration and linked feature guide for usage; no standalone example is documented in source.

[INTERFACE] `StorageUsageAdapter`

Host measurement and optional-budget lookup port.

Imports: @alneas/eaos-core, @alneas/eaos-core/storage.

Signature

interface StorageUsageAdapter {
    getBudget(tenantId: string): Promise<StorageBudget | null>;
    measure(tenantId: string): Promise<StorageUsage>;
}

Parameters

Name	Type	Required	Description
`getBudget`	`Promise<StorageBudget \| null>`	Yes	Read an optional tenant storage budget from host policy.
`measure`	`Promise<StorageUsage>`	Yes	Measure tenant storage usage through the host provider.

Returns

Type declaration; no runtime value.

Public members

`getBudget`

Read an optional tenant storage budget from host policy.

Parameters:

tenantId: Verified tenant whose budget is requested.

Returns: Budget or null when the host has none; omitted planes have no framework default limit.

Remarks

Host owns authorization, freshness and persistence.

Errors and rejections

Host lookup failures reject the Promise.

Example:

import type { StorageUsageAdapter } from "@alneas/eaos-core/storage";
async function inspectBudget(adapter: StorageUsageAdapter) { return adapter.getBudget("tenant-demo"); }

`measure`

Measure tenant storage usage through the host provider.

Parameters:

tenantId: Verified tenant whose storage planes are measured.

Returns: Usage snapshot; hosts may omit planes they cannot measure.

Remarks

Measurement accuracy, cost and freshness are host-defined; validate returned shape with assertStorageUsage before quota decisions.

Errors and rejections

Host measurement failures reject the Promise.

Example:

import type { StorageUsageAdapter } from "@alneas/eaos-core/storage";
async function inspectUsage(adapter: StorageUsageAdapter) { return adapter.measure("tenant-demo"); }

Example

See the owning declaration and linked feature guide for usage; no standalone example is documented in source.

[INTERFACE] `StructuredDraft`

Reviewable draft title and structured JSON data prior to persistence.

Imports: @alneas/eaos-core, @alneas/eaos-core/ai, @alneas/eaos-core/ai/proposal-ui.

Signature

interface StructuredDraft {
    title: string;
    data: Record<string, unknown>;
}

Parameters

Name	Type	Required	Description
`title`	`string`	Yes	Human-readable draft, task, file or event title displayed by the host.
`data`	`Record<string, unknown>`	Yes	Structured draft/event data or cached result; serialization and validation occur at the owning API boundary.

Returns

Type declaration; no runtime value.

Public members

`title`

Human-readable draft, task, file or event title displayed by the host.

`data`

Structured draft/event data or cached result; serialization and validation occur at the owning API boundary.

Example

See the owning declaration and linked feature guide for usage; no standalone example is documented in source.

[INTERFACE] `StructuredToolCall`

Parsed tool name and object arguments prior to host validation/authorization.

Imports: @alneas/eaos-core, @alneas/eaos-core/agentic, @alneas/eaos-core/agentic/structured-tool-call-adapter.

Signature

interface StructuredToolCall {
    name: string;
    arguments: Record<string, unknown>;
}

Parameters

Name	Type	Required	Description
`name`	`string`	Yes	Exact registered tool identity; parsing/discovery does not authorize its execution.
`arguments`	`Record<string, unknown>`	Yes	Object-valued parsed tool arguments awaiting schema validation and authorization.

Returns

Type declaration; no runtime value.

Public members

`name`

Exact registered tool identity; parsing/discovery does not authorize its execution.

`arguments`

Object-valued parsed tool arguments awaiting schema validation and authorization.

Example

See the owning declaration and linked feature guide for usage; no standalone example is documented in source.

[CLASS] `StructuredToolCallAdapter`

Format tool catalogs and extract tool-call objects from model text.

Imports: @alneas/eaos-core, @alneas/eaos-core/agentic, @alneas/eaos-core/agentic/structured-tool-call-adapter.

Signature

declare class StructuredToolCallAdapter {
    formatToolsPrompt(tools: Array<McpToolDefinition | StructuredToolDefinition>): string;
    parseResponse(rawOutput: string): StructuredToolCallResponse;
}

Parameters

Name	Type	Required	Description
—	—	—	No call parameters.

Returns

StructuredToolCallAdapter

Remarks

Parsing is not tool authorization or argument-schema validation; use the host execution gate before invoking extracted calls.

Public members

`formatToolsPrompt`

Format tool definitions into the tools/tool_call prompt convention.

Parameters:

tools: Ordered tool definitions; an empty list yields an empty prompt.

Returns: A prompt containing pretty-printed function metadata and a tool-call format instruction.

Errors and rejections

JSON serialization errors in parameter definitions propagate.

Example:

import { StructuredToolCallAdapter } from "@alneas/eaos-core/agentic/structured-tool-call-adapter";
const adapter = new StructuredToolCallAdapter();
console.log(adapter.formatToolsPrompt([{ name: "notes.list", parameters: { type: "object" } }]));

`parseResponse`

Extract object-valued calls from tool_call tags or a bare JSON object.

Parameters:

rawOutput: Model output; tagged JSON may be retried after removing trailing commas. Null/missing arguments normalize to an empty object.

Returns: Calls plus remaining trimmed text and hasToolCalls; malformed tagged segments are removed from content even when no call is accepted.

Remarks

Does not validate tool names or schemas, execute calls, or authorize side effects.

Example:

import { StructuredToolCallAdapter } from "@alneas/eaos-core/agentic/structured-tool-call-adapter";
const adapter = new StructuredToolCallAdapter();
console.log(adapter.parseResponse('{"name":"notes.list","arguments":{}}'));

Example

import { StructuredToolCallAdapter } from "@alneas/eaos-core/agentic/structured-tool-call-adapter";
const adapter = new StructuredToolCallAdapter();
console.log(adapter.parseResponse('<tool_call>{"name":"notes.list","arguments":{}}</tool_call>').toolCalls);

[INTERFACE] `StructuredToolCallResponse`

Remaining model text and extracted tool calls with a convenience presence flag.

Imports: @alneas/eaos-core, @alneas/eaos-core/agentic, @alneas/eaos-core/agentic/structured-tool-call-adapter.

Signature

interface StructuredToolCallResponse {
    content: string;
    toolCalls: StructuredToolCall[];
    hasToolCalls: boolean;
}

Parameters

Name	Type	Required	Description
`content`	`string`	Yes	Loaded skill instructions, model response text or proposed file content; treat external text as untrusted input.
`toolCalls`	`StructuredToolCall[]`	Yes	Parsed tool requests in encounter order; parsing does not execute them.
`hasToolCalls`	`boolean`	Yes	Whether at least one syntactically accepted call was extracted.

Returns

Type declaration; no runtime value.

Public members

`content`

Loaded skill instructions, model response text or proposed file content; treat external text as untrusted input.

`toolCalls`

Parsed tool requests in encounter order; parsing does not execute them.

`hasToolCalls`

Whether at least one syntactically accepted call was extracted.

Example

See the owning declaration and linked feature guide for usage; no standalone example is documented in source.

[INTERFACE] `StructuredToolDefinition`

Model-facing tool name with optional description and parameter schema.

Imports: @alneas/eaos-core, @alneas/eaos-core/agentic, @alneas/eaos-core/agentic/structured-tool-call-adapter.

Signature

interface StructuredToolDefinition {
    name: string;
    description?: string;
    parameters?: Record<string, unknown>;
}

Parameters

Name	Type	Required	Description
`name`	`string`	Yes	Exact registered tool identity; parsing/discovery does not authorize its execution.
`description`	`string`	No	Human-readable metadata describing the capability, workflow node or requirement to host users.
`parameters`	`Record<string, unknown>`	No	JSON Schema describing tool arguments; the host validates arguments before execution.

Returns

Type declaration; no runtime value.

Public members

`name`

Exact registered tool identity; parsing/discovery does not authorize its execution.

`description`

Human-readable metadata describing the capability, workflow node or requirement to host users.

`parameters`

JSON Schema describing tool arguments; the host validates arguments before execution.

Example

See the owning declaration and linked feature guide for usage; no standalone example is documented in source.

[INTERFACE] `TargetNavigationConfig`

Optional navigation groups for web and LINE clients.

Imports: @alneas/eaos-core, @alneas/eaos-core/plugin-sdk, @alneas/eaos-core/plugin-sdk/types.

Signature

interface TargetNavigationConfig {
    web?: NavigationConfig;
    line?: NavigationConfig;
}

Parameters

Name	Type	Required	Description
`web`	`NavigationConfig`	No	Optional navigation configuration for the browser client.
`line`	`NavigationConfig`	No	Optional navigation configuration for the LINE client.

Returns

Type declaration; no runtime value.

Public members

`web`

Optional navigation configuration for the browser client.

`line`

Optional navigation configuration for the LINE client.

Example

See the owning declaration and linked feature guide for usage; no standalone example is documented in source.

[CLASS] `TenantAwareAdapter`

Decorate selected data operations with a fixed tenant field.

Imports: @alneas/eaos-core, @alneas/eaos-core/adapters, @alneas/eaos-core/adapters/tenant-adapter.

Signature

declare class TenantAwareAdapter implements DataAccessAdapter {
    constructor(base: DataAccessAdapter, config: TenantAwareAdapterConfig);
    find<T = unknown>(collection: string, filter?: Filter, options?: QueryOptions): Promise<T[]>;
    findOne<T = unknown>(collection: string, id: string, options?: QueryOptions): Promise<T | null>;
    count(collection: string, filter?: Filter, options?: QueryOptions): Promise<number>;
    create<T = unknown>(collection: string, data: Record<string, unknown>, options?: QueryOptions): Promise<T>;
    update<T = unknown>(collection: string, id: string, data: Record<string, unknown>, options?: QueryOptions): Promise<T>;
    replace?<T = unknown>(collection: string, id: string, data: Record<string, unknown>, options?: QueryOptions): Promise<T>;
    delete<T = unknown>(collection: string, id: string, options?: QueryOptions): Promise<T>;
    aggregate?<T = unknown>(collection: string, pipeline: unknown[], options?: QueryOptions): Promise<T[]>;
    createMany?<T = unknown>(collection: string, data: Record<string, unknown>[], options?: QueryOptions): Promise<T[]>;
    updateMany?<T = unknown>(collection: string, filter: Filter, data: Record<string, unknown>, options?: QueryOptions): Promise<T[]>;
    deleteMany?<T = unknown>(collection: string, filter: Filter, options?: QueryOptions): Promise<T[]>;
    insertOne?(collection: string, data: Record<string, unknown>, options?: QueryOptions): Promise<OperationResult>;
    updateOne?(collection: string, filter: Filter, data: Record<string, unknown>, options?: QueryOptions): Promise<OperationResult>;
    replaceOne?(collection: string, filter: Filter, data: Record<string, unknown>, options?: QueryOptions): Promise<OperationResult>;
    deleteOne?(collection: string, filter: Filter, options?: QueryOptions): Promise<OperationResult>;
    findOneAndUpdate?<T = unknown>(collection: string, filter: Filter, data: Record<string, unknown>, options?: QueryOptions): Promise<T | null>;
    findOneAndReplace?<T = unknown>(collection: string, filter: Filter, data: Record<string, unknown>, options?: QueryOptions): Promise<T | null>;
    findOneAndDelete?<T = unknown>(collection: string, filter: Filter, options?: QueryOptions): Promise<T | null>;
}

Parameters

Name	Type	Required	Description
`base`	`DataAccessAdapter`	Yes	Host data-access adapter; caller owns its lifecycle and tenant safety for delegated operations.
`config`	`TenantAwareAdapterConfig`	Yes	Tenant identity and optional tenantField (default tenant_id) and createOnly (default false).

Returns

TenantAwareAdapter

Remarks

find/count and filter-based writes inject tenant filters unless createOnly is true; create/update/replace inject tenant data. findOne/delete by ID and aggregate delegate without tenant filters. ID-based update/replace do not independently check existing row ownership. The underlying adapter/database must enforce isolation for those paths; this decorator alone is not an authorization boundary.

Constructor contract

Public members

`find`

Find records with an injected tenant filter unless createOnly is enabled.

Parameters:

collection: Host-approved collection/table identity interpreted by the base adapter.
filter: Caller predicate; fixed tenant field overrides a conflicting value unless createOnly is true.
options: Optional query settings forwarded unchanged; defaults and transaction behavior belong to the base adapter.

Returns: An array of records resolved by the base adapter; empty when none match.

Type parameters

T: Expected base-adapter record/result type; no runtime shape validation is added and the default is unknown.

Remarks

Requires a real connected host adapter. This wrapper supplies no retry/cancellation or transaction boundary; write/ownership guarantees are those of the host.

Errors and rejections

Rejects on base adapter failure.

Example:

import { TenantAwareAdapter } from "@alneas/eaos-core/adapters/tenant-adapter";
import type { DataAccessAdapter } from "@alneas/eaos-core/adapters/types";
async function useHostAdapter(base: DataAccessAdapter) {
 const adapter = new TenantAwareAdapter(base, { tenantId: "tenant-demo" });
 return await adapter.find("notes", { archived: false });
}

`findOne`

Delegate an ID lookup without adding a tenant filter.

Parameters:

collection: Host-approved collection/table identity interpreted by the base adapter.
id: Record identity; this wrapper does not add an ownership predicate for ID-based operations.
options: Optional query settings forwarded unchanged; defaults and transaction behavior belong to the base adapter.

Returns: Resolved record or null, according to the base adapter.

Type parameters

T: Expected base-adapter record/result type; no runtime shape validation is added and the default is unknown.

Remarks

Requires a real connected host adapter. This wrapper supplies no retry/cancellation or transaction boundary; write/ownership guarantees are those of the host.

Errors and rejections

Rejects on base adapter failure.

Example:

import { TenantAwareAdapter } from "@alneas/eaos-core/adapters/tenant-adapter";
import type { DataAccessAdapter } from "@alneas/eaos-core/adapters/types";
async function useHostAdapter(base: DataAccessAdapter) {
 const adapter = new TenantAwareAdapter(base, { tenantId: "tenant-demo" });
 return await adapter.findOne("notes", "note-1");
}

`count`

Count records with an injected tenant filter unless createOnly is enabled.

Parameters:

collection: Host-approved collection/table identity interpreted by the base adapter.
filter: Caller predicate; fixed tenant field overrides a conflicting value unless createOnly is true.
options: Optional query settings forwarded unchanged; defaults and transaction behavior belong to the base adapter.

Returns: The base adapter count.

Remarks

Requires a real connected host adapter. This wrapper supplies no retry/cancellation or transaction boundary; write/ownership guarantees are those of the host.

Errors and rejections

Rejects on base adapter failure.

Example:

import { TenantAwareAdapter } from "@alneas/eaos-core/adapters/tenant-adapter";
import type { DataAccessAdapter } from "@alneas/eaos-core/adapters/types";
async function useHostAdapter(base: DataAccessAdapter) {
 const adapter = new TenantAwareAdapter(base, { tenantId: "tenant-demo" });
 return await adapter.count("notes", {});
}

`create`

Create a record with the fixed tenant field overriding caller data.

Parameters:

collection: Host-approved collection/table identity interpreted by the base adapter.
data: Record data; fixed tenant field overwrites caller tenant data before delegation.
options: Optional query settings forwarded unchanged; defaults and transaction behavior belong to the base adapter.

Returns: The record resolved by the base create operation.

Type parameters

T: Expected base-adapter record/result type; no runtime shape validation is added and the default is unknown.

Remarks

Requires a real connected host adapter. This wrapper supplies no retry/cancellation or transaction boundary; write/ownership guarantees are those of the host.

Errors and rejections

Rejects on base adapter failure.

Example:

import { TenantAwareAdapter } from "@alneas/eaos-core/adapters/tenant-adapter";
import type { DataAccessAdapter } from "@alneas/eaos-core/adapters/types";
async function useHostAdapter(base: DataAccessAdapter) {
 const adapter = new TenantAwareAdapter(base, { tenantId: "tenant-demo" });
 return await adapter.create("notes", { title: "hello" });
}

`update`

Delegate an ID update with the fixed tenant field injected into new data.

Parameters:

collection: Host-approved collection/table identity interpreted by the base adapter.
id: Record identity; this wrapper does not add an ownership predicate for ID-based operations.
data: Record data; fixed tenant field overwrites caller tenant data before delegation.
options: Optional query settings forwarded unchanged; defaults and transaction behavior belong to the base adapter.

Returns: The record resolved by the base update operation.

Type parameters

T: Expected base-adapter record/result type; no runtime shape validation is added and the default is unknown.

Remarks

Requires a real connected host adapter. This wrapper supplies no retry/cancellation or transaction boundary; write/ownership guarantees are those of the host.

Errors and rejections

Rejects on base adapter failure.

Example:

import { TenantAwareAdapter } from "@alneas/eaos-core/adapters/tenant-adapter";
import type { DataAccessAdapter } from "@alneas/eaos-core/adapters/types";
async function useHostAdapter(base: DataAccessAdapter) {
 const adapter = new TenantAwareAdapter(base, { tenantId: "tenant-demo" });
 return await adapter.update("notes", "note-1", { title: "hello" });
}

`replace`

Delegate a supported ID replacement with tenant data injected.

Parameters:

collection: Host-approved collection/table identity interpreted by the base adapter.
id: Record identity; this wrapper does not add an ownership predicate for ID-based operations.
data: Record data; fixed tenant field overwrites caller tenant data before delegation.
options: Optional query settings forwarded unchanged; defaults and transaction behavior belong to the base adapter.

Returns: The record resolved by the base replace operation.

Type parameters

T: Expected base-adapter record/result type; no runtime shape validation is added and the default is unknown.

Remarks

Requires a real connected host adapter. This wrapper supplies no retry/cancellation or transaction boundary; write/ownership guarantees are those of the host.

Errors and rejections

Rejects with Error if the base adapter does not support this operation; base adapter failures propagate.

Example:

import { TenantAwareAdapter } from "@alneas/eaos-core/adapters/tenant-adapter";
import type { DataAccessAdapter } from "@alneas/eaos-core/adapters/types";
async function useHostAdapter(base: DataAccessAdapter) {
 const adapter = new TenantAwareAdapter(base, { tenantId: "tenant-demo" });
 return await adapter.replace?.("notes", "note-1", { title: "hello" });
}

`delete`

Delegate an ID deletion without adding a tenant filter.

Parameters:

collection: Host-approved collection/table identity interpreted by the base adapter.
id: Record identity; this wrapper does not add an ownership predicate for ID-based operations.
options: Optional query settings forwarded unchanged; defaults and transaction behavior belong to the base adapter.

Returns: The base adapter deletion result.

Type parameters

T: Expected base-adapter record/result type; no runtime shape validation is added and the default is unknown.

Remarks

Requires a real connected host adapter. This wrapper supplies no retry/cancellation or transaction boundary; write/ownership guarantees are those of the host.

Errors and rejections

Rejects on base adapter failure.

Example:

import { TenantAwareAdapter } from "@alneas/eaos-core/adapters/tenant-adapter";
import type { DataAccessAdapter } from "@alneas/eaos-core/adapters/types";
async function useHostAdapter(base: DataAccessAdapter) {
 const adapter = new TenantAwareAdapter(base, { tenantId: "tenant-demo" });
 return await adapter.delete("notes", "note-1");
}

`aggregate`

Delegate an aggregation pipeline without injecting tenant constraints.

Parameters:

collection: Host-approved collection/table identity interpreted by the base adapter.
pipeline: Aggregation stages forwarded unchanged; the host must include/enforce tenant scope.
options: Optional query settings forwarded unchanged; defaults and transaction behavior belong to the base adapter.

Returns: The base adapter result array.

Type parameters

T: Expected base-adapter record/result type; no runtime shape validation is added and the default is unknown.

Remarks

Requires a real connected host adapter. This wrapper supplies no retry/cancellation or transaction boundary; write/ownership guarantees are those of the host.

Errors and rejections

Rejects with Error if the base adapter does not support this operation; base adapter failures propagate.

Example:

import { TenantAwareAdapter } from "@alneas/eaos-core/adapters/tenant-adapter";
import type { DataAccessAdapter } from "@alneas/eaos-core/adapters/types";
async function useHostAdapter(base: DataAccessAdapter) {
 const adapter = new TenantAwareAdapter(base, { tenantId: "tenant-demo" });
 return await adapter.aggregate?.("notes", []);
}

`createMany`

Create multiple records with the fixed tenant field applied to each.

Parameters:

collection: Host-approved collection/table identity interpreted by the base adapter.
data: Records copied with the fixed tenant field applied to each.
options: Optional query settings forwarded unchanged; defaults and transaction behavior belong to the base adapter.

Returns: The records resolved by the base bulk create.

Type parameters

T: Expected base-adapter record/result type; no runtime shape validation is added and the default is unknown.

Remarks

Requires a real connected host adapter. This wrapper supplies no retry/cancellation or transaction boundary; write/ownership guarantees are those of the host.

Errors and rejections

Rejects with Error if the base adapter does not support this operation; base adapter failures propagate.

Example:

import { TenantAwareAdapter } from "@alneas/eaos-core/adapters/tenant-adapter";
import type { DataAccessAdapter } from "@alneas/eaos-core/adapters/types";
async function useHostAdapter(base: DataAccessAdapter) {
 const adapter = new TenantAwareAdapter(base, { tenantId: "tenant-demo" });
 return await adapter.createMany?.("notes", [{ title: "hello" }]);
}

`updateMany`

Bulk-update using injected tenant filters and tenant data.

Parameters:

collection: Host-approved collection/table identity interpreted by the base adapter.
filter: Caller predicate; fixed tenant field overrides a conflicting value unless createOnly is true.
data: Record data; fixed tenant field overwrites caller tenant data before delegation.
options: Optional query settings forwarded unchanged; defaults and transaction behavior belong to the base adapter.

Returns: The records resolved by the base bulk update.

Type parameters

T: Expected base-adapter record/result type; no runtime shape validation is added and the default is unknown.

Remarks

Requires a real connected host adapter. This wrapper supplies no retry/cancellation or transaction boundary; write/ownership guarantees are those of the host.

Errors and rejections

Rejects with Error if the base adapter does not support this operation; base adapter failures propagate.

Example:

import { TenantAwareAdapter } from "@alneas/eaos-core/adapters/tenant-adapter";
import type { DataAccessAdapter } from "@alneas/eaos-core/adapters/types";
async function useHostAdapter(base: DataAccessAdapter) {
 const adapter = new TenantAwareAdapter(base, { tenantId: "tenant-demo" });
 return await adapter.updateMany?.("notes", {}, { archived: true });
}

`deleteMany`

Bulk-delete using an injected tenant filter unless createOnly is enabled.

Parameters:

collection: Host-approved collection/table identity interpreted by the base adapter.
filter: Caller predicate; fixed tenant field overrides a conflicting value unless createOnly is true.
options: Optional query settings forwarded unchanged; defaults and transaction behavior belong to the base adapter.

Returns: The base adapter bulk deletion results.

Type parameters

T: Expected base-adapter record/result type; no runtime shape validation is added and the default is unknown.

Remarks

Requires a real connected host adapter. This wrapper supplies no retry/cancellation or transaction boundary; write/ownership guarantees are those of the host.

Errors and rejections

Rejects with Error if the base adapter does not support this operation; base adapter failures propagate.

Example:

import { TenantAwareAdapter } from "@alneas/eaos-core/adapters/tenant-adapter";
import type { DataAccessAdapter } from "@alneas/eaos-core/adapters/types";
async function useHostAdapter(base: DataAccessAdapter) {
 const adapter = new TenantAwareAdapter(base, { tenantId: "tenant-demo" });
 return await adapter.deleteMany?.("notes", {});
}

`insertOne`

Insert one record with the fixed tenant field overriding caller data.

Parameters:

collection: Host-approved collection/table identity interpreted by the base adapter.
data: Record data; fixed tenant field overwrites caller tenant data before delegation.
options: Optional query settings forwarded unchanged; defaults and transaction behavior belong to the base adapter.

Returns: The base adapter operation-result metadata.

Remarks

Requires a real connected host adapter. This wrapper supplies no retry/cancellation or transaction boundary; write/ownership guarantees are those of the host.

Errors and rejections

Rejects with Error if the base adapter does not support this operation; base adapter failures propagate.

Example:

import { TenantAwareAdapter } from "@alneas/eaos-core/adapters/tenant-adapter";
import type { DataAccessAdapter } from "@alneas/eaos-core/adapters/types";
async function useHostAdapter(base: DataAccessAdapter) {
 const adapter = new TenantAwareAdapter(base, { tenantId: "tenant-demo" });
 return await adapter.insertOne?.("notes", { title: "hello" });
}

`updateOne`

Update one match using injected tenant filter and data.

Parameters:

collection: Host-approved collection/table identity interpreted by the base adapter.
filter: Caller predicate; fixed tenant field overrides a conflicting value unless createOnly is true.
data: Record data; fixed tenant field overwrites caller tenant data before delegation.
options: Optional query settings forwarded unchanged; defaults and transaction behavior belong to the base adapter.

Returns: The base adapter operation-result metadata.

Remarks

Requires a real connected host adapter. This wrapper supplies no retry/cancellation or transaction boundary; write/ownership guarantees are those of the host.

Errors and rejections

Rejects with Error if the base adapter does not support this operation; base adapter failures propagate.

Example:

import { TenantAwareAdapter } from "@alneas/eaos-core/adapters/tenant-adapter";
import type { DataAccessAdapter } from "@alneas/eaos-core/adapters/types";
async function useHostAdapter(base: DataAccessAdapter) {
 const adapter = new TenantAwareAdapter(base, { tenantId: "tenant-demo" });
 return await adapter.updateOne?.("notes", { id: "note-1" }, { title: "hello" });
}

`replaceOne`

Replace one match using injected tenant filter and data.

Parameters:

collection: Host-approved collection/table identity interpreted by the base adapter.
filter: Caller predicate; fixed tenant field overrides a conflicting value unless createOnly is true.
data: Record data; fixed tenant field overwrites caller tenant data before delegation.
options: Optional query settings forwarded unchanged; defaults and transaction behavior belong to the base adapter.

Returns: The base adapter operation-result metadata.

Remarks

Requires a real connected host adapter. This wrapper supplies no retry/cancellation or transaction boundary; write/ownership guarantees are those of the host.

Errors and rejections

Rejects with Error if the base adapter does not support this operation; base adapter failures propagate.

Example:

import { TenantAwareAdapter } from "@alneas/eaos-core/adapters/tenant-adapter";
import type { DataAccessAdapter } from "@alneas/eaos-core/adapters/types";
async function useHostAdapter(base: DataAccessAdapter) {
 const adapter = new TenantAwareAdapter(base, { tenantId: "tenant-demo" });
 return await adapter.replaceOne?.("notes", { id: "note-1" }, { title: "hello" });
}

`deleteOne`

Delete one match using the injected tenant filter.

Parameters:

collection: Host-approved collection/table identity interpreted by the base adapter.
filter: Caller predicate; fixed tenant field overrides a conflicting value unless createOnly is true.
options: Optional query settings forwarded unchanged; defaults and transaction behavior belong to the base adapter.

Returns: The base adapter operation-result metadata.

Remarks

Requires a real connected host adapter. This wrapper supplies no retry/cancellation or transaction boundary; write/ownership guarantees are those of the host.

Errors and rejections

Rejects with Error if the base adapter does not support this operation; base adapter failures propagate.

Example:

import { TenantAwareAdapter } from "@alneas/eaos-core/adapters/tenant-adapter";
import type { DataAccessAdapter } from "@alneas/eaos-core/adapters/types";
async function useHostAdapter(base: DataAccessAdapter) {
 const adapter = new TenantAwareAdapter(base, { tenantId: "tenant-demo" });
 return await adapter.deleteOne?.("notes", { id: "note-1" });
}

`findOneAndUpdate`

Update and return one match using injected tenant filter and data.

Parameters:

collection: Host-approved collection/table identity interpreted by the base adapter.
filter: Caller predicate; fixed tenant field overrides a conflicting value unless createOnly is true.
data: Record data; fixed tenant field overwrites caller tenant data before delegation.
options: Optional query settings forwarded unchanged; defaults and transaction behavior belong to the base adapter.

Returns: The updated record or null, as resolved by the base adapter.

Type parameters

T: Expected base-adapter record/result type; no runtime shape validation is added and the default is unknown.

Remarks

Requires a real connected host adapter. This wrapper supplies no retry/cancellation or transaction boundary; write/ownership guarantees are those of the host.

Errors and rejections

Rejects with Error if the base adapter does not support this operation; base adapter failures propagate.

Example:

import { TenantAwareAdapter } from "@alneas/eaos-core/adapters/tenant-adapter";
import type { DataAccessAdapter } from "@alneas/eaos-core/adapters/types";
async function useHostAdapter(base: DataAccessAdapter) {
 const adapter = new TenantAwareAdapter(base, { tenantId: "tenant-demo" });
 return await adapter.findOneAndUpdate?.("notes", { id: "note-1" }, { title: "hello" });
}

`findOneAndReplace`

Replace and return one match using injected tenant filter and data.

Parameters:

collection: Host-approved collection/table identity interpreted by the base adapter.
filter: Caller predicate; fixed tenant field overrides a conflicting value unless createOnly is true.
data: Record data; fixed tenant field overwrites caller tenant data before delegation.
options: Optional query settings forwarded unchanged; defaults and transaction behavior belong to the base adapter.

Returns: The replacement record or null, as resolved by the base adapter.

Type parameters

T: Expected base-adapter record/result type; no runtime shape validation is added and the default is unknown.

Remarks

Requires a real connected host adapter. This wrapper supplies no retry/cancellation or transaction boundary; write/ownership guarantees are those of the host.

Errors and rejections

Rejects with Error if the base adapter does not support this operation; base adapter failures propagate.

Example:

import { TenantAwareAdapter } from "@alneas/eaos-core/adapters/tenant-adapter";
import type { DataAccessAdapter } from "@alneas/eaos-core/adapters/types";
async function useHostAdapter(base: DataAccessAdapter) {
 const adapter = new TenantAwareAdapter(base, { tenantId: "tenant-demo" });
 return await adapter.findOneAndReplace?.("notes", { id: "note-1" }, { title: "hello" });
}

`findOneAndDelete`

Delete and return one match using the injected tenant filter.

Parameters:

collection: Host-approved collection/table identity interpreted by the base adapter.
filter: Caller predicate; fixed tenant field overrides a conflicting value unless createOnly is true.
options: Optional query settings forwarded unchanged; defaults and transaction behavior belong to the base adapter.

Returns: The deleted record or null, as resolved by the base adapter.

Type parameters

T: Expected base-adapter record/result type; no runtime shape validation is added and the default is unknown.

Remarks

Requires a real connected host adapter. This wrapper supplies no retry/cancellation or transaction boundary; write/ownership guarantees are those of the host.

Errors and rejections

Rejects with Error if the base adapter does not support this operation; base adapter failures propagate.

Example:

import { TenantAwareAdapter } from "@alneas/eaos-core/adapters/tenant-adapter";
import type { DataAccessAdapter } from "@alneas/eaos-core/adapters/types";
async function useHostAdapter(base: DataAccessAdapter) {
 const adapter = new TenantAwareAdapter(base, { tenantId: "tenant-demo" });
 return await adapter.findOneAndDelete?.("notes", { id: "note-1" });
}

Example

import { TenantAwareAdapter } from "@alneas/eaos-core/adapters/tenant-adapter";
import type { DataAccessAdapter } from "@alneas/eaos-core/adapters/types";
function scopeHostData(base: DataAccessAdapter) {
 return new TenantAwareAdapter(base, { tenantId: "tenant-demo" });
}

[INTERFACE] `TenantAwareAdapterConfig`

Configuration for TenantAwareAdapter.

Imports: @alneas/eaos-core, @alneas/eaos-core/adapters, @alneas/eaos-core/adapters/tenant-adapter.

Signature

interface TenantAwareAdapterConfig {
    tenantId: string;
    tenantField?: string;
    createOnly?: boolean;
}

Parameters

Name	Type	Required	Description
`tenantId`	`string`	Yes	The tenant ID to inject into all operations
`tenantField`	`string`	No	The field name used for tenant isolation (default: ‘tenant_id’). For Oracle VPD, this is handled at the DB level and doesn’t need injection. For Supabase RLS or non-VPD setups, this field is injected into queries.
`createOnly`	`boolean`	No	If true, tenant_id is injected into created records but NOT into filters. Useful when VPD/RLS handles filtering at the DB level. Default: false (inject into both filters and creates).

Returns

Type declaration; no runtime value.

Public members

`tenantId`

The tenant ID to inject into all operations

`tenantField`

The field name used for tenant isolation (default: ‘tenant_id’). For Oracle VPD, this is handled at the DB level and doesn’t need injection. For Supabase RLS or non-VPD setups, this field is injected into queries.

`createOnly`

If true, tenant_id is injected into created records but NOT into filters. Useful when VPD/RLS handles filtering at the DB level. Default: false (inject into both filters and creates).

Example

See the owning declaration and linked feature guide for usage; no standalone example is documented in source.

[INTERFACE] `TenantEntitlements`

Host-controlled tenant subscription snapshot and quota overrides.

Imports: @alneas/eaos-core, @alneas/eaos-core/plugin-sdk, @alneas/eaos-core/entitlements.

Signature

interface TenantEntitlements {
    tenantId: string;
    plan: 'free' | 'standard' | 'pro';
    status: 'active' | 'suspended';
    validUntil?: string;
    addons: readonly string[];
    monthlyQuotas?: Readonly<Record<string, number>>;
}

Parameters

Name	Type	Required	Description
`tenantId`	`string`	Yes	Verified tenant boundary for the record or operation; host authorization must establish this scope.
`plan`	`'free' \| 'standard' \| 'pro'`	Yes	Host subscription plan used by entitlement preview.
`status`	`'active' \| 'suspended'`	Yes	Subscription state; nonpublic/noncorporate preview requires active status.
`validUntil`	`string`	No	Optional parseable subscription expiry checked against the evaluation clock.
`addons`	`readonly string[]`	Yes	Addon identities present in the host entitlement snapshot.
`monthlyQuotas`	`Readonly<Record<string, number>>`	No	Overrides are keyed by addon ID, otherwise by plugin ID. Zero denies all usage.

Returns

Type declaration; no runtime value.

Public members

`tenantId`

Verified tenant boundary for the record or operation; host authorization must establish this scope.

`plan`

Host subscription plan used by entitlement preview.

`status`

Subscription state; nonpublic/noncorporate preview requires active status.

`validUntil`

Optional parseable subscription expiry checked against the evaluation clock.

`addons`

Addon identities present in the host entitlement snapshot.

`monthlyQuotas`

Overrides are keyed by addon ID, otherwise by plugin ID. Zero denies all usage.

Example

See the owning declaration and linked feature guide for usage; no standalone example is documented in source.

[INTERFACE] `TenantSessionContext`

Tenant and optional user claims installed on a host-managed database session.

Imports: @alneas/eaos-core, @alneas/eaos-core/db, @alneas/eaos-core/db/adapter.

Signature

interface TenantSessionContext {
    tenantId: string;
    userId?: string;
}

Parameters

Name	Type	Required	Description
`tenantId`	`string`	Yes	Verified tenant boundary for the record or operation; host authorization must establish this scope.
`userId`	`string`	No	User identity within the tenant supplied by the trusted host.

Returns

Type declaration; no runtime value.

Public members

`tenantId`

Verified tenant boundary for the record or operation; host authorization must establish this scope.

`userId`

User identity within the tenant supplied by the trusted host.

Example

See the owning declaration and linked feature guide for usage; no standalone example is documented in source.

[TYPE] `TenantStorageMetrics`

Tenant-level capacity and item-count snapshot; the host may omit planes it cannot measure.

Imports: @alneas/eaos-core, @alneas/eaos-core/storage.

Signature

type TenantStorageMetrics = StorageUsage;

Parameters

Name	Type	Required	Description
—	—	—	No call parameters.

Returns

Type declaration; no runtime value.

Example

See the owning declaration and linked feature guide for usage; no standalone example is documented in source.

[TYPE] `TenantStorageMetricsAdapter`

Alias of the host usage/budget measurement port.

Imports: @alneas/eaos-core, @alneas/eaos-core/storage.

Signature

type TenantStorageMetricsAdapter = StorageUsageAdapter;

Parameters

Name	Type	Required	Description
—	—	—	No call parameters.

Returns

Type declaration; no runtime value.

Example

See the owning declaration and linked feature guide for usage; no standalone example is documented in source.

[CLASS] `TenantStrategyRegistry`

Select tenant-specific strategy references with an optional module guard.

Imports: @alneas/eaos-core, @alneas/eaos-core/plugin-sdk/tenant-strategy-registry.

Signature

declare class TenantStrategyRegistry<T> {
    constructor(defaultStrategy: T, moduleGuard?: (tenantId: string, enabledModules?: string[]) => boolean);
    registerTenantStrategy(tenantId: string, strategy: T): void;
    resolve(tenantId: string, enabledModules?: string[]): T;
    hasTenantStrategy(tenantId: string): boolean;
}

Parameters

Name	Type	Required	Description
`defaultStrategy`	`T`	Yes	Fallback returned when no truthy override is available or guard denies it.
`moduleGuard`	`(tenantId: string, enabledModules?: string[]) => boolean`	No	Optional synchronous callback invoked only for a truthy override with tenant ID and supplied modules; false selects default.

Returns

TenantStrategyRegistry

Type parameters

T: Strategy value shared by default and tenant overrides; returned values are not cloned.

Remarks

Stores references in memory; does not persist registrations or establish tenant authentication.

Constructor contract

Public members

`registerTenantStrategy`

Replace the in-memory strategy for a tenant key.

Parameters:

tenantId: Exact tenant lookup key.
strategy: Override stored by reference; falsy values resolve to the default.

Returns: No value; registration has been replaced.

Example:

import { TenantStrategyRegistry } from "@alneas/eaos-core/plugin-sdk/tenant-strategy-registry";
const registry = new TenantStrategyRegistry("default");
registry.registerTenantStrategy("tenant-demo", "custom");

`resolve`

Resolve an authorized override or the original default reference.

Parameters:

tenantId: Exact tenant lookup key.
enabledModules: Optional module list forwarded unchanged to moduleGuard.

Returns: Override when truthy and permitted, otherwise defaultStrategy.

Remarks

A denied override writes a console warning.

Errors and rejections

Errors thrown by moduleGuard propagate.

Example:

import { TenantStrategyRegistry } from "@alneas/eaos-core/plugin-sdk/tenant-strategy-registry";
const registry = new TenantStrategyRegistry("default");
console.log(registry.resolve("tenant-demo")); // default

`hasTenantStrategy`

Check whether a tenant key is registered regardless of guard eligibility.

Parameters:

tenantId: Exact registration key.

Returns: Whether the registry contains the key, even if the stored strategy is falsy.

Example:

import { TenantStrategyRegistry } from "@alneas/eaos-core/plugin-sdk/tenant-strategy-registry";
const registry = new TenantStrategyRegistry("default");
console.log(registry.hasTenantStrategy("tenant-demo")); // false

Example

import { TenantStrategyRegistry } from "@alneas/eaos-core/plugin-sdk/tenant-strategy-registry";
const registry = new TenantStrategyRegistry({ mode: "default" });
registry.registerTenantStrategy("tenant-demo", { mode: "custom" });
console.log(registry.resolve("tenant-demo").mode);

[INTERFACE] `TestPersona`

Cloned test identity and optional role/subscription fixture for SDK route execution.

Imports: @alneas/eaos-core/testing.

Signature

interface TestPersona {
    tenantId: string;
    userId?: string;
    roles?: readonly string[];
    tier?: 'free' | 'standard' | 'pro';
    addons?: readonly string[];
}

Parameters

Name	Type	Required	Description
`tenantId`	`string`	Yes	Verified tenant boundary for the record or operation; host authorization must establish this scope.
`userId`	`string`	No	User identity within the tenant supplied by the trusted host.
`roles`	`readonly string[]`	No	Role claims supplied by the host after identity verification.
`tier`	`'free' \| 'standard' \| 'pro'`	No	Commercial entitlement category or model resource tier, interpreted by its owning policy.
`addons`	`readonly string[]`	No	Addon identities present in the host entitlement snapshot.

Returns

Type declaration; no runtime value.

Public members

`tenantId`

Verified tenant boundary for the record or operation; host authorization must establish this scope.

`userId`

User identity within the tenant supplied by the trusted host.

`roles`

Role claims supplied by the host after identity verification.

`tier`

Commercial entitlement category or model resource tier, interpreted by its owning policy.

`addons`

Addon identities present in the host entitlement snapshot.

Example

See the owning declaration and linked feature guide for usage; no standalone example is documented in source.

[INTERFACE] `ToolContractSnapshot`

Normalized tool schemas and execution policy captured with a deterministic content hash.

Imports: @alneas/eaos-core, @alneas/eaos-core/plugin-sdk, @alneas/eaos-core/plugin-sdk/contract-compatibility.

Signature

interface ToolContractSnapshot {
    name: string;
    version: string;
    inputSchema: Record<string, unknown>;
    outputSchema?: Record<string, unknown>;
    permission: string;
    sideEffect: ExecutionSideEffect;
    riskLevel: RiskLevel;
    approvalLevel: ApprovalLevel;
    requireHumanApproval: boolean;
    hash: string;
}

Parameters

Name	Type	Required	Description
`name`	`string`	Yes	Exact registered tool identity; parsing/discovery does not authorize its execution.
`version`	`string`	Yes	Normalized operation contract version; defaults to 1.0.0 when tool metadata omits it.
`inputSchema`	`Record<string, unknown>`	Yes	JSON Schema describing admitted operation input.
`outputSchema`	`Record<string, unknown>`	No	Optional JSON Schema describing operation output; absent means no output contract is declared here.
`permission`	`string`	Yes	Host permission identity required for this operation.
`sideEffect`	`ExecutionSideEffect`	Yes	Classify whether the operation reads, writes local state or affects an external service.
`riskLevel`	`RiskLevel`	Yes	Declared operation risk used to determine review requirements; it does not itself grant authorization.
`approvalLevel`	`ApprovalLevel`	Yes	Required organizational review category; a level declaration is not proof of approval.
`requireHumanApproval`	`boolean`	Yes	Whether execution must wait for an explicit host approval workflow.
`hash`	`string`	Yes	Content integrity digest; hashes are unkeyed and do not establish authorization or writer authenticity.

Returns

Type declaration; no runtime value.

Public members

`name`

Exact registered tool identity; parsing/discovery does not authorize its execution.

`version`

Normalized operation contract version; defaults to 1.0.0 when tool metadata omits it.

`inputSchema`

JSON Schema describing admitted operation input.

`outputSchema`

Optional JSON Schema describing operation output; absent means no output contract is declared here.

`permission`

Host permission identity required for this operation.

`sideEffect`

Classify whether the operation reads, writes local state or affects an external service.

`riskLevel`

Declared operation risk used to determine review requirements; it does not itself grant authorization.

`approvalLevel`

Required organizational review category; a level declaration is not proof of approval.

`requireHumanApproval`

Whether execution must wait for an explicit host approval workflow.

`hash`

Content integrity digest; hashes are unkeyed and do not establish authorization or writer authenticity.

Example

See the owning declaration and linked feature guide for usage; no standalone example is documented in source.

[INTERFACE] `UnifiedTask`

Shared human/AI task record with assignment, sensitivity and cost tracking.

Imports: @alneas/eaos-core, @alneas/eaos-core/agentic, @alneas/eaos-core/agentic/types.

Signature

interface UnifiedTask {
    id: string;
    parentTaskId?: string;
    orgId: string;
    title: string;
    description: string;
    assignedType: 'HUMAN' | 'AI';
    assignedAgentId?: string;
    assignedUserId?: string;
    priority: 'low' | 'medium' | 'high' | 'critical';
    status: 'backlog' | 'in_progress' | 'pending_approval' | 'completed' | 'failed';
    sensitivityLevel: DataSensitivityLevel;
    budgetCapUsd?: number;
    currentCostUsd: number;
    dueDate?: string;
    createdAt: string;
    updatedAt: string;
}

Parameters

Name	Type	Required	Description
`id`	`string`	Yes	Host task-board identity shared by human/AI task handling.
`parentTaskId`	`string`	No	Optional parent task identity for task decomposition.
`orgId`	`string`	Yes	Organization identity grouping agents/tasks within host data.
`title`	`string`	Yes	Human-readable draft, task, file or event title displayed by the host.
`description`	`string`	Yes	Human-readable metadata describing the capability, workflow node or requirement to host users.
`assignedType`	`'HUMAN' \| 'AI'`	Yes	Whether this task is assigned to a human or AI agent.
`assignedAgentId`	`string`	No	Optional assigned agent identity when assignedType is AI.
`assignedUserId`	`string`	No	Optional assigned user identity when assignedType is HUMAN.
`priority`	`'low' \| 'medium' \| 'high' \| 'critical'`	Yes	Host scheduling priority; execution broker candidate priority uses a signed safe-integer score boost.
`status`	`'backlog' \| 'in_progress' \| 'pending_approval' \| 'completed' \| 'failed'`	Yes	Host task-board lifecycle, including pending approval and terminal outcomes.
`sensitivityLevel`	`DataSensitivityLevel`	Yes	Classification used by the host to constrain eligible execution routes.
`budgetCapUsd`	`number`	No	Optional task spending ceiling in US dollars enforced by the host.
`currentCostUsd`	`number`	Yes	Host-reported cost accumulated for this task in US dollars.
`dueDate`	`string`	No	Optional task due-date metadata interpreted by the host scheduler.
`createdAt`	`string`	Yes	Creation timestamp supplied or generated by the owning API.
`updatedAt`	`string`	Yes	Timestamp of the latest host-recorded update; this contract does not persist changes.

Returns

Type declaration; no runtime value.

Public members

`id`

Host task-board identity shared by human/AI task handling.

`parentTaskId`

Optional parent task identity for task decomposition.

`orgId`

Organization identity grouping agents/tasks within host data.

`title`

Human-readable draft, task, file or event title displayed by the host.

`description`

Human-readable metadata describing the capability, workflow node or requirement to host users.

`assignedType`

Whether this task is assigned to a human or AI agent.

`assignedAgentId`

Optional assigned agent identity when assignedType is AI.

`assignedUserId`

Optional assigned user identity when assignedType is HUMAN.

`priority`

Host scheduling priority; execution broker candidate priority uses a signed safe-integer score boost.

`status`

Host task-board lifecycle, including pending approval and terminal outcomes.

`sensitivityLevel`

Classification used by the host to constrain eligible execution routes.

`budgetCapUsd`

Optional task spending ceiling in US dollars enforced by the host.

`currentCostUsd`

Host-reported cost accumulated for this task in US dollars.

`dueDate`

Optional task due-date metadata interpreted by the host scheduler.

`createdAt`

Creation timestamp supplied or generated by the owning API.

`updatedAt`

Timestamp of the latest host-recorded update; this contract does not persist changes.

Example

See the owning declaration and linked feature guide for usage; no standalone example is documented in source.

[INTERFACE] `UserContext`

Tenant and user identity plus role and optional permission claims supplied by the host.

Imports: @alneas/eaos-core, @alneas/eaos-core/plugin-sdk, @alneas/eaos-core/plugin-sdk/types.

Signature

interface UserContext {
    userId: string;
    tenantId: string;
    roles: string[];
    permissions?: string[];
}

Parameters

Name	Type	Required	Description
`userId`	`string`	Yes	User identity within the tenant supplied by the trusted host.
`tenantId`	`string`	Yes	Verified tenant boundary for the record or operation; host authorization must establish this scope.
`roles`	`string[]`	Yes	Role claims supplied by the host after identity verification.
`permissions`	`string[]`	No	Optional explicit permission names interpreted and enforced by the host.

Returns

Type declaration; no runtime value.

Public members

`userId`

User identity within the tenant supplied by the trusted host.

`tenantId`

Verified tenant boundary for the record or operation; host authorization must establish this scope.

`roles`

Role claims supplied by the host after identity verification.

`permissions`

Optional explicit permission names interpreted and enforced by the host.

Example

See the owning declaration and linked feature guide for usage; no standalone example is documented in source.

[FUNCTION] `validateApprovalBinding`

Validate binding shape, live expiry and the hash of its normalized contents.

Imports: @alneas/eaos-core, @alneas/eaos-core/agent/approved-execution.

Signature

declare function validateApprovalBinding(value: unknown, options?: {
    now?: Date;
}): ApprovalBinding;

Parameters

Name	Type	Required	Description
`value`	`unknown`	Yes	Stored binding to validate; all hash fields must be lowercase 64-character hexadecimal.
`options`	`{ now?: Date; }`	No	Optional evaluation clock; now defaults to current Date.

Returns

ApprovalBinding

A fresh normalized binding, with a cloned target when present.

Remarks

A matching unkeyed hash is an integrity check, not proof that a person approved the request.

Errors and rejections

Error for malformed/expired binding or a content hash mismatch; cloning/date errors propagate.

Public members

`options.now`

Optional reference time used to check the stored expiry; omission uses a new current Date.

Example

import { validateApprovalBinding } from "@alneas/eaos-core/agent/approved-execution";
import { createApprovalBinding } from "@alneas/eaos-core/agent/approved-execution";
const input = { tenantId: "tenant-demo", requestedBy: "user-demo", operation: "note.read", input: { id: "note-1" }, contract: { operation: "note.read", version: "1.0.0", permission: "notes:read", sideEffect: "read", riskLevel: "low", approvalLevel: "L1_AUTO", inputSchema: { type: "object" } } } as const;
console.log(validateApprovalBinding(createApprovalBinding(input)).operation);

[FUNCTION] `validateWorkflowDefinition`

Validate and clone a definition before it reaches a compiler or registry.

Imports: @alneas/eaos-core, @alneas/eaos-core/workflow-definition.

Signature

declare function validateWorkflowDefinition(input: unknown): WorkflowDefinition;

Parameters

Name	Type	Required	Description
`input`	`unknown`	Yes	Version 1.0 data-only definition with 1–200 nodes and up to 500 edges; IDs must match the schema, references must resolve and routing fallbacks must be unambiguous.

Returns

WorkflowDefinition

A fresh normalized definition containing cloned configuration, conditions and metadata.

Remarks

This checks the implemented structural constraints, not executability, authorization or handler availability. Cyclic workflows are not rejected; no workflow is started.

Errors and rejections

Error for malformed fields, duplicate/missing nodes, invalid condition/approval/retry/tool scope or conflicting outgoing edges; clone failures propagate.

Example

import { validateWorkflowDefinition } from "@alneas/eaos-core/workflow-definition";
const definition = validateWorkflowDefinition({ schemaVersion: "1.0", workflowId: "demo", version: "1.0.0", entryNode: "start", nodes: [{ id: "start", type: "task" }], edges: [] });
console.log(definition.nodes.length); // 1

[FUNCTION] `validateWorkflowEffectReceipt`

Validate a provider result against the exact request that was admitted.

Imports: @alneas/eaos-core, @alneas/eaos-core/agent/workflow-effects.

Signature

declare function validateWorkflowEffectReceipt<TInput>(request: WorkflowEffectRequest<TInput>, receipt: unknown): WorkflowEffectReceipt;

Parameters

Name	Type	Required	Description
`request`	`WorkflowEffectRequest<TInput>`	Yes	Expected tenant/workflow/operation/idempotency key and JSON-safe input.
`receipt`	`unknown`	Yes	Untrusted receipt; identity and input hash must match request and outcome must be succeeded, failed or unknown.

Returns

WorkflowEffectReceipt

A new normalized receipt with cloned metadata; failed/unknown are returned as data.

Type parameters

TInput: Expected domain input type used to recompute request identity.

Remarks

No provider reconciliation or authorization occurs.

Errors and rejections

Error for mismatched/malformed receipt or request; cloning/hashing errors propagate.

Example

import { validateWorkflowEffectReceipt } from "@alneas/eaos-core/agent/workflow-effects";
import { createWorkflowEffectReceipt } from "@alneas/eaos-core/agent/workflow-effects";
const request = { tenantId: "tenant-demo", workflowId: "notes", operation: "note.create", idempotencyKey: "request-1", input: { text: "hello" } };
const receipt = createWorkflowEffectReceipt({ request, adapterId: "notes-store", receiptId: "receipt-1", outcome: "unknown" });
console.log(validateWorkflowEffectReceipt(request, receipt).outcome);

[INTERFACE] `VectorSearchAdapter`

Provider-neutral vector search. pgvector, Oracle Vector Search and hosted indexes implement this boundary.

Imports: @alneas/eaos-core, @alneas/eaos-core/vector.

Signature

interface VectorSearchAdapter {
    search(input: VectorSearchRequest): Promise<readonly VectorSearchHit[]>;
}

Parameters

Name	Type	Required	Description
`search`	`Promise<readonly VectorSearchHit[]>`	Yes	Search a trusted host vector index within a tenant boundary.

Returns

Type declaration; no runtime value.

Public members

`search`

Search a trusted host vector index within a tenant boundary.

Parameters:

input: Verified tenant, catalog index ID, query vector, result count and optional approved filters.

Returns: Provider-ranked hits, possibly empty; score scale and ordering are provider-defined.

Remarks

Host owns index authorization, vector dimensions/filter validation and cancellation. Validate results with assertVectorSearchHits before consuming them.

Errors and rejections

Host index/search failures reject the Promise.

Example:

import type { VectorSearchAdapter } from "@alneas/eaos-core/vector";
async function searchHost(adapter: VectorSearchAdapter) { return adapter.search({ tenantId: "tenant-demo", indexId: "documents", queryVector: [0.1, 0.2], topK: 5 }); }

Example

See the owning declaration and linked feature guide for usage; no standalone example is documented in source.

[INTERFACE] `VectorSearchHit`

Provider result identity and finite relevance score scoped to one tenant.

Imports: @alneas/eaos-core, @alneas/eaos-core/vector.

Signature

interface VectorSearchHit {
    tenantId: string;
    id: string;
    score: number;
    metadata?: Readonly<Record<string, unknown>>;
}

Parameters

Name	Type	Required	Description
`tenantId`	`string`	Yes	Verified tenant boundary for the record or operation; host authorization must establish this scope.
`id`	`string`	Yes	Provider result identity unique within one validated result set.
`score`	`number`	Yes	Provider/detector relevance or anomaly score; interpret using the owning result contract.
`metadata`	`Readonly<Record<string, unknown>>`	No	Optional host/provider metadata; callers remain responsible for sensitive content and validation.

Returns

Type declaration; no runtime value.

Public members

`tenantId`

Verified tenant boundary for the record or operation; host authorization must establish this scope.

`id`

Provider result identity unique within one validated result set.

`score`

Provider/detector relevance or anomaly score; interpret using the owning result contract.

`metadata`

Optional host/provider metadata; callers remain responsible for sensitive content and validation.

Example

See the owning declaration and linked feature guide for usage; no standalone example is documented in source.

[INTERFACE] `VectorSearchRequest`

Tenant-scoped trusted index query with a finite vector and bounded result count.

Imports: @alneas/eaos-core, @alneas/eaos-core/vector.

Signature

interface VectorSearchRequest {
    tenantId: string;
    indexId: string;
    queryVector: readonly number[];
    topK: number;
    filters?: Readonly<Record<string, string | number | boolean | readonly string[]>>;
}

Parameters

Name	Type	Required	Description
`tenantId`	`string`	Yes	Verified tenant boundary for the record or operation; host authorization must establish this scope.
`indexId`	`string`	Yes	Trusted host catalog key; callers never provide a physical table or column name.
`queryVector`	`readonly number[]`	Yes	Nonempty finite numeric embedding; the host checks its dimension against the selected index.
`topK`	`number`	Yes	Requested maximum result count; vector request validation permits integers from 1 to 10000.
`filters`	`Readonly<Record<string, string \| number \| boolean \| readonly string[]>>`	No	Optional host-approved metadata filters; physical field permissions and semantics remain adapter-owned.

Returns

Type declaration; no runtime value.

Public members

`tenantId`

Verified tenant boundary for the record or operation; host authorization must establish this scope.

`indexId`

Trusted host catalog key; callers never provide a physical table or column name.

`queryVector`

Nonempty finite numeric embedding; the host checks its dimension against the selected index.

`topK`

Requested maximum result count; vector request validation permits integers from 1 to 10000.

`filters`

Optional host-approved metadata filters; physical field permissions and semantics remain adapter-owned.

Example

See the owning declaration and linked feature guide for usage; no standalone example is documented in source.

[FUNCTION] `verifyApiKey`

Compare an API secret against an active stored digest and optional scope.

Imports: @alneas/eaos-core, @alneas/eaos-core/security/platform-security.

Signature

declare function verifyApiKey(secret: string, record: ApiKeyRecord, requiredScope?: string, now?: Date): boolean;

Parameters

Name	Type	Required	Description
`secret`	`string`	Yes	Presented eaos_ secret.
`record`	`ApiKeyRecord`	Yes	Trusted stored record selected by the host.
`requiredScope`	`string`	No	Exact scope required when supplied; omission skips scope checking.
`now`	`Date`	No	Evaluation clock; defaults to current Date.

Returns

boolean

Whether prefix, active lifecycle, constant-time digest comparison and optional exact scope match.

Remarks

Requires node:crypto. The caller must select the record within the correct tenant and enforce any additional authorization.

Example

import { verifyApiKey } from "@alneas/eaos-core/security/platform-security";
import { issueApiKey } from "@alneas/eaos-core/security/platform-security";
const issued = issueApiKey({ tenantId: "tenant-demo", userId: "user-demo", scopes: ["notes:read"] });
console.log(verifyApiKey(issued.secret, issued.record, "notes:read")); // true

[FUNCTION] `verifyAuditChain`

Verify an ordered audit chain starting from the zero-hash genesis.

Imports: @alneas/eaos-core, @alneas/eaos-core/security/platform-security.

Signature

declare function verifyAuditChain(events: readonly PlatformAuditEvent[]): boolean;

Parameters

Name	Type	Required	Description
`events`	`readonly PlatformAuditEvent[]`	Yes	Full chain in append order, starting at genesis rather than an arbitrary suffix.

Returns

boolean

True when previousHash links and JSON-based event hashes all match; an empty chain is valid.

Remarks

Requires node:crypto. Unkeyed hashes do not authenticate the writer or detect a rewritten complete history without an externally trusted anchor.

Errors and rejections

JSON serialization errors for data that cannot be encoded.

Example

import { verifyAuditChain } from "@alneas/eaos-core/security/platform-security";
console.log(verifyAuditChain([])); // true

[FUNCTION] `verifySignature`

Verify either a timestamped body or a payload signature.

Imports: @alneas/eaos-core, @alneas/eaos-core/webhook, @alneas/eaos-core/webhook/delivery.

Signature

declare function verifySignature(timestampOrPayload: string | unknown, bodyOrSignature: string, signatureOrSecret: string, secretParam?: string): SignatureVerification;

Parameters

Name	Type	Required	Description
`timestampOrPayload`	`string \| unknown`	Yes	Timestamp text in four-argument mode, or raw/JSON payload in three-argument mode.
`bodyOrSignature`	`string`	Yes	Exact body in four-argument mode, otherwise hexadecimal signature.
`signatureOrSecret`	`string`	Yes	Hexadecimal signature in four-argument mode, otherwise shared secret.
`secretParam`	`string`	No	Shared secret when verifying timestamp + dot + body; omission selects payload-only mode.

Returns

SignatureVerification

Verification data with valid false on comparison, decoding, serialization or crypto errors; error may describe the failure.

Remarks

Uses timingSafeEqual on decoded bytes. Does not validate timestamp freshness or enforce replay protection.

Example

import { verifySignature } from "@alneas/eaos-core/webhook/delivery";
import { signPayload } from "@alneas/eaos-core/webhook/delivery";
import { randomBytes } from "node:crypto";
const body = "{}";
const secret = randomBytes(32).toString('hex'); // Ephemeral key for this local round trip only.
console.log(verifySignature(body, signPayload(body, secret), secret).valid); // true

[INTERFACE] `WebhookPayload`

Webhook event name, caller timestamp and JSON data sent to a receiver.

Imports: @alneas/eaos-core, @alneas/eaos-core/webhook, @alneas/eaos-core/webhook/delivery.

Signature

interface WebhookPayload {
    event: string;
    timestamp: number;
    data: Record<string, unknown>;
}

Parameters

Name	Type	Required	Description
`event`	`string`	Yes	Inbound provider event or webhook event name interpreted by the connected host.
`timestamp`	`number`	Yes	Caller event timestamp, conventionally Unix epoch milliseconds; delivery signs a separate generated header timestamp.
`data`	`Record<string, unknown>`	Yes	Structured draft/event data or cached result; serialization and validation occur at the owning API boundary.

Returns

Type declaration; no runtime value.

Public members

`event`

Inbound provider event or webhook event name interpreted by the connected host.

`timestamp`

Caller event timestamp, conventionally Unix epoch milliseconds; delivery signs a separate generated header timestamp.

`data`

Structured draft/event data or cached result; serialization and validation occur at the owning API boundary.

Example

See the owning declaration and linked feature guide for usage; no standalone example is documented in source.

[INTERFACE] `WebMcpToolDefinition`

Browser-executed tool metadata with an optional local handler.

Imports: @alneas/eaos-core, @alneas/eaos-core/plugin-sdk, @alneas/eaos-core/plugin-sdk/types.

Signature

interface WebMcpToolDefinition {
    name: string;
    description: string;
    parameters: Record<string, any>;
    clientSide: true;
    handler?: (args: any) => Promise<any> | void;
}

Parameters

Name	Type	Required	Description
`name`	`string`	Yes	Exact registered tool identity; parsing/discovery does not authorize its execution.
`description`	`string`	Yes	Human-readable metadata describing the capability, workflow node or requirement to host users.
`parameters`	`Record<string, any>`	Yes	JSON Schema describing tool arguments; the host validates arguments before execution.
`clientSide`	`true`	Yes	Marks this definition as a browser-side tool rather than a host MCP handler.
`handler`	`(args: any) => Promise<any> \| void`	No	Optionally execute the tool in the browser host.

Returns

Type declaration; no runtime value.

Public members

`name`

Exact registered tool identity; parsing/discovery does not authorize its execution.

`description`

Human-readable metadata describing the capability, workflow node or requirement to host users.

`parameters`

JSON Schema describing tool arguments; the host validates arguments before execution.

`clientSide`

Marks this definition as a browser-side tool rather than a host MCP handler.

`handler`

Optionally execute the tool in the browser host.

Parameters:

args: Decoded input validated against parameters by the host before invocation.

Returns: No value or an asynchronous domain result, depending on the registered handler.

Remarks

Requires the browser host to bind and authorize execution; model tool metadata is not permission.

Example

See the owning declaration and linked feature guide for usage; no standalone example is documented in source.

[CONSTANT] `WORKFLOW_DEFINITION_SCHEMA`

JSON Schema consumed by visual editors and host-side validators.

Imports: @alneas/eaos-core, @alneas/eaos-core/workflow-definition.

Signature

declare const WORKFLOW_DEFINITION_SCHEMA: {
    readonly $schema: "https://json-schema.org/draft/2020-12/schema";
    readonly $id: "https://eaos.dev/schemas/workflow-definition-1.0.json";
    readonly title: "EAOS Workflow Definition";
    readonly type: "object";
    readonly $defs: {
        readonly workflowCondition: {
            readonly oneOf: readonly [
                {
                    readonly type: "object";
                    readonly additionalProperties: false;
                    readonly required: readonly [
                        "path",
                        "operator"
                    ];
                    readonly properties: {
                        readonly path: {
                            readonly type: "string";
                            readonly minLength: 1;
                            readonly maxLength: 256;
                            readonly pattern: "^[A-Za-z0-9_.-]+$";
                        };
                        readonly operator: {
                            readonly enum: readonly [
                                "equals",
                                "not_equals",
                                "in",
                                "not_in",
                                "exists",
                                "truthy",
                                "falsy",
                                "greater_than",
                                "greater_or_equal",
                                "less_than",
                                "less_or_equal"
                            ];
                        };
                        readonly value: {};
                    };
                },
                {
                    readonly type: "object";
                    readonly additionalProperties: false;
                    readonly required: readonly [
                        "all"
                    ];
                    readonly properties: {
                        readonly all: {
                            readonly type: "array";
                            readonly minItems: 1;
                            readonly maxItems: 32;
                            readonly items: {
                                readonly $ref: "#/$defs/workflowCondition";
                            };
                        };
                    };
                },
                {
                    readonly type: "object";
                    readonly additionalProperties: false;
                    readonly required: readonly [
                        "any"
                    ];
                    readonly properties: {
                        readonly any: {
                            readonly type: "array";
                            readonly minItems: 1;
                            readonly maxItems: 32;
                            readonly items: {
                                readonly $ref: "#/$defs/workflowCondition";
                            };
                        };
                    };
                },
                {
                    readonly type: "object";
                    readonly additionalProperties: false;
                    readonly required: readonly [
                        "not"
                    ];
                    readonly properties: {
                        readonly not: {
                            readonly $ref: "#/$defs/workflowCondition";
                        };
                    };
                }
            ];
        };
    };
    readonly additionalProperties: false;
    readonly required: readonly [
        "schemaVersion",
        "workflowId",
        "version",
        "entryNode",
        "nodes",
        "edges"
    ];
    readonly properties: {
        readonly schemaVersion: {
            readonly const: "1.0";
        };
        readonly workflowId: {
            readonly type: "string";
            readonly minLength: 1;
            readonly maxLength: 128;
            readonly pattern: "^[a-z0-9][a-z0-9._-]{0,127}$";
        };
        readonly version: {
            readonly type: "string";
            readonly minLength: 1;
            readonly maxLength: 64;
        };
        readonly entryNode: {
            readonly type: "string";
            readonly minLength: 1;
            readonly maxLength: 128;
            readonly pattern: "^[a-z0-9][a-z0-9._-]{0,127}$";
        };
        readonly nodes: {
            readonly type: "array";
            readonly minItems: 1;
            readonly maxItems: 200;
            readonly items: {
                readonly type: "object";
                readonly additionalProperties: false;
                readonly required: readonly [
                    "id",
                    "type"
                ];
                readonly properties: {
                    readonly id: {
                        readonly type: "string";
                        readonly minLength: 1;
                        readonly maxLength: 128;
                        readonly pattern: "^[a-z0-9][a-z0-9._-]{0,127}$";
                    };
                    readonly type: {
                        readonly type: "string";
                        readonly minLength: 1;
                        readonly maxLength: 128;
                        readonly pattern: "^[a-z0-9][a-z0-9._-]{0,127}$";
                    };
                    readonly kind: {
                        readonly enum: readonly [
                            "trigger",
                            "task",
                            "agent",
                            "human_review",
                            "approval",
                            "effect",
                            "subgraph",
                            "wait",
                            "system",
                            "custom"
                        ];
                    };
                    readonly label: {
                        readonly type: "string";
                        readonly minLength: 1;
                        readonly maxLength: 256;
                    };
                    readonly description: {
                        readonly type: "string";
                        readonly maxLength: 2000;
                    };
                    readonly pluginId: {
                        readonly type: "string";
                        readonly minLength: 1;
                        readonly maxLength: 128;
                        readonly pattern: "^[a-z0-9][a-z0-9._-]{0,127}$";
                    };
                    readonly config: {
                        readonly type: "object";
                        readonly additionalProperties: true;
                        readonly maxProperties: 100;
                    };
                    readonly approval: {
                        readonly type: "object";
                        readonly additionalProperties: false;
                        readonly required: readonly [
                            "toolName",
                            "approvalLevel",
                            "riskLevel",
                            "reason"
                        ];
                        readonly properties: {
                            readonly toolName: {
                                readonly type: "string";
                                readonly minLength: 1;
                                readonly maxLength: 256;
                            };
                            readonly approvalLevel: {
                                readonly enum: readonly [
                                    "L1_AUTO",
                                    "L2_LEAD",
                                    "L3_MANAGER",
                                    "L4_EXECUTIVE"
                                ];
                            };
                            readonly riskLevel: {
                                readonly enum: readonly [
                                    "low",
                                    "medium",
                                    "high",
                                    "critical"
                                ];
                            };
                            readonly reason: {
                                readonly type: "string";
                                readonly minLength: 1;
                                readonly maxLength: 2000;
                            };
                            readonly argsPath: {
                                readonly type: "string";
                                readonly minLength: 1;
                                readonly maxLength: 256;
                                readonly pattern: "^[A-Za-z0-9_.-]+$";
                            };
                            readonly permission: {
                                readonly type: "string";
                                readonly minLength: 1;
                                readonly maxLength: 256;
                            };
                            readonly contractVersion: {
                                readonly type: "string";
                                readonly minLength: 1;
                                readonly maxLength: 64;
                            };
                        };
                    };
                    readonly retry: {
                        readonly type: "object";
                        readonly additionalProperties: false;
                        readonly required: readonly [
                            "maxAttempts"
                        ];
                        readonly properties: {
                            readonly maxAttempts: {
                                readonly type: "integer";
                                readonly minimum: 1;
                                readonly maximum: 10;
                            };
                            readonly backoffMs: {
                                readonly type: "integer";
                                readonly minimum: 0;
                                readonly maximum: 300000;
                            };
                            readonly maxBackoffMs: {
                                readonly type: "integer";
                                readonly minimum: 0;
                                readonly maximum: 3600000;
                            };
                            readonly jitter: {
                                readonly type: "boolean";
                            };
                        };
                    };
                    readonly timeoutMs: {
                        readonly type: "integer";
                        readonly minimum: 1;
                        readonly maximum: 3600000;
                    };
                    readonly subflow: {
                        readonly type: "object";
                        readonly additionalProperties: false;
                        readonly required: readonly [
                            "workflowId",
                            "version"
                        ];
                        readonly properties: {
                            readonly workflowId: {
                                readonly type: "string";
                                readonly minLength: 1;
                                readonly maxLength: 128;
                                readonly pattern: "^[a-z0-9][a-z0-9._-]{0,127}$";
                            };
                            readonly version: {
                                readonly type: "string";
                                readonly minLength: 1;
                                readonly maxLength: 64;
                            };
                            readonly inputPath: {
                                readonly type: "string";
                                readonly minLength: 1;
                                readonly maxLength: 256;
                                readonly pattern: "^[A-Za-z0-9_.-]+$";
                            };
                            readonly outputKey: {
                                readonly type: "string";
                                readonly minLength: 1;
                                readonly maxLength: 128;
                                readonly pattern: "^[a-z0-9][a-z0-9._-]{0,127}$";
                            };
                        };
                    };
                    readonly toolScope: {
                        readonly type: "object";
                        readonly additionalProperties: false;
                        readonly required: readonly [
                            "mode",
                            "allowedToolNames"
                        ];
                        readonly properties: {
                            readonly mode: {
                                readonly enum: readonly [
                                    "read",
                                    "preview",
                                    "action"
                                ];
                            };
                            readonly allowedToolNames: {
                                readonly type: "array";
                                readonly maxItems: 100;
                                readonly items: {
                                    readonly type: "string";
                                    readonly minLength: 1;
                                    readonly maxLength: 256;
                                };
                            };
                        };
                    };
                };
            };
        };
        readonly edges: {
            readonly type: "array";
            readonly maxItems: 500;
            readonly items: {
                readonly type: "object";
                readonly additionalProperties: false;
                readonly required: readonly [
                    "from",
                    "to"
                ];
                readonly properties: {
                    readonly from: {
                        readonly type: "string";
                        readonly minLength: 1;
                        readonly maxLength: 128;
                        readonly pattern: "^[a-z0-9][a-z0-9._-]{0,127}$";
                    };
                    readonly to: {
                        readonly type: "string";
                        readonly minLength: 1;
                        readonly maxLength: 128;
                        readonly pattern: "^[a-z0-9][a-z0-9._-]{0,127}$";
                    };
                    readonly label: {
                        readonly type: "string";
                        readonly maxLength: 256;
                    };
                    readonly condition: {
                        readonly $ref: "#/$defs/workflowCondition";
                    };
                    readonly default: {
                        readonly type: "boolean";
                    };
                };
            };
        };
        readonly metadata: {
            readonly type: "object";
            readonly additionalProperties: true;
            readonly maxProperties: 100;
        };
    };
};

Parameters

Name	Type	Required	Description
—	—	—	No call parameters.

Returns

Declared constant value.

Example

See the owning declaration and linked feature guide for usage; no standalone example is documented in source.

[INTERFACE] `WorkflowAgentActionIntent`

An action proposal is a plan. It is not authorization to execute it.

Imports: @alneas/eaos-core, @alneas/eaos-core/workflow-contracts.

Signature

interface WorkflowAgentActionIntent {
    toolName: string;
    args: Record<string, unknown>;
    idempotencyKey: string;
    expectedRevision?: number;
    riskLevel?: WorkflowAgentRiskLevel;
}

Parameters

Name	Type	Required	Description
`toolName`	`string`	Yes	Registered tool identity used to resolve host execution policy.
`args`	`Record<string, unknown>`	Yes	Operation arguments passed to hooks or bound into a proposed action; authorization and schema checks remain host-owned.
`idempotencyKey`	`string`	Yes	Replay identity for the same admitted operation; the host must persist/deduplicate it before unsafe retries.
`expectedRevision`	`number`	No	Optional optimistic target revision the host must check before applying an action.
`riskLevel`	`WorkflowAgentRiskLevel`	No	Declared operation risk used to determine review requirements; it does not itself grant authorization.

Returns

Type declaration; no runtime value.

Public members

`toolName`

Registered tool identity used to resolve host execution policy.

`args`

Operation arguments passed to hooks or bound into a proposed action; authorization and schema checks remain host-owned.

`idempotencyKey`

Replay identity for the same admitted operation; the host must persist/deduplicate it before unsafe retries.

`expectedRevision`

Optional optimistic target revision the host must check before applying an action.

`riskLevel`

Declared operation risk used to determine review requirements; it does not itself grant authorization.

Example

See the owning declaration and linked feature guide for usage; no standalone example is documented in source.

[INTERFACE] `WorkflowAgentEvidence`

Source reference and optional revision/excerpt supporting a proposal.

Imports: @alneas/eaos-core, @alneas/eaos-core/workflow-contracts.

Signature

interface WorkflowAgentEvidence {
    kind: 'record' | 'tool' | 'event' | 'document' | 'other';
    source: string;
    revision?: number | string;
    excerpt?: string;
}

Parameters

Name	Type	Required	Description
`kind`	`'record' \| 'tool' \| 'event' \| 'document' \| 'other'`	Yes	Evidence source category validated by parseWorkflowAgentProposal.
`source`	`string`	Yes	Nonblank evidence source reference, at most 512 characters when proposal-parsed.
`revision`	`number \| string`	No	Optional source/target revision interpreted by the owning host; approval/effect target revisions must be positive integers.
`excerpt`	`string`	No	Source text excerpt; callers should preserve provenance when presenting it.

Returns

Type declaration; no runtime value.

Public members

`kind`

Evidence source category validated by parseWorkflowAgentProposal.

`source`

Nonblank evidence source reference, at most 512 characters when proposal-parsed.

`revision`

Optional source/target revision interpreted by the owning host; approval/effect target revisions must be positive integers.

`excerpt`

Source text excerpt; callers should preserve provenance when presenting it.

Example

See the owning declaration and linked feature guide for usage; no standalone example is documented in source.

[TYPE] `WorkflowAgentFailureCode`

Host/runtime failure classification used by durable retry policy.

Imports: @alneas/eaos-core, @alneas/eaos-core/workflow-contracts.

Signature

type WorkflowAgentFailureCode = 'AGENT_UNAVAILABLE' | 'TIMEOUT' | 'OUTPUT_LIMIT' | 'RUNTIME_FAILED' | 'INVALID_PROPOSAL';

Parameters

Name	Type	Required	Description
—	—	—	No call parameters.

Returns

Type declaration; no runtime value.

Example

See the owning declaration and linked feature guide for usage; no standalone example is documented in source.

[INTERFACE] `WorkflowAgentProposal`

Versioned reviewable agent output with evidence, proposed actions and risk.

Imports: @alneas/eaos-core, @alneas/eaos-core/workflow-contracts.

Signature

interface WorkflowAgentProposal<TOutput = unknown> {
    schemaVersion: '1.0';
    summary: string;
    output: TOutput;
    evidence: readonly WorkflowAgentEvidence[];
    actions: readonly WorkflowAgentActionIntent[];
    riskLevel: WorkflowAgentRiskLevel;
    confidence?: number;
    requestedApproval?: boolean;
}

Parameters

Name	Type	Required	Description
`schemaVersion`	`'1.0'`	Yes	Envelope format discriminator accepted by the corresponding parser/validator.
`summary`	`string`	Yes	Human-readable review/result description suitable for host presentation.
`output`	`TOutput`	Yes	Optional domain output; validate it separately and inspect the accompanying status/receipt.
`evidence`	`readonly WorkflowAgentEvidence[]`	Yes	Source references or audit rationale supporting review; evidence is data and does not grant execution authority.
`actions`	`readonly WorkflowAgentActionIntent[]`	Yes	Ordered proposed actions; the host must validate and authorize them before any side effect.
`riskLevel`	`WorkflowAgentRiskLevel`	Yes	Declared operation risk used to determine review requirements; it does not itself grant authorization.
`confidence`	`number`	No	Reported confidence ratio, conventionally from zero to one; validate at the consuming boundary.
`requestedApproval`	`boolean`	No	Optional request that a host obtain review; this flag is not approval evidence.

Returns

Type declaration; no runtime value.

Type parameters

TOutput: Domain output shape requiring caller validation; defaults to unknown.

Public members

`schemaVersion`

Envelope format discriminator accepted by the corresponding parser/validator.

`summary`

Human-readable review/result description suitable for host presentation.

`output`

Optional domain output; validate it separately and inspect the accompanying status/receipt.

`evidence`

Source references or audit rationale supporting review; evidence is data and does not grant execution authority.

`actions`

Ordered proposed actions; the host must validate and authorize them before any side effect.

`riskLevel`

Declared operation risk used to determine review requirements; it does not itself grant authorization.

`confidence`

Reported confidence ratio, conventionally from zero to one; validate at the consuming boundary.

`requestedApproval`

Optional request that a host obtain review; this flag is not approval evidence.

Example

See the owning declaration and linked feature guide for usage; no standalone example is documented in source.

[INTERFACE] `WorkflowAgentRequest`

Tenant-scoped agent task with replay identity, input and requested tool scope.

Imports: @alneas/eaos-core, @alneas/eaos-core/workflow-contracts.

Signature

interface WorkflowAgentRequest<TInput = unknown> {
    taskId: string;
    workflowId: string;
    tenantId: string;
    userId: string;
    correlationId: string;
    purpose: string;
    jobKind?: AgentJobKind;
    input: TInput;
    toolScope: WorkflowAgentToolScope;
    idempotencyKey: string;
    timeoutMs?: number;
}

Parameters

Name	Type	Required	Description
`taskId`	`string`	Yes	Task identity correlating the agent/runtime operation with its owning workflow or task board.
`workflowId`	`string`	Yes	Workflow definition identity used to correlate execution and effects.
`tenantId`	`string`	Yes	Verified tenant boundary for the record or operation; host authorization must establish this scope.
`userId`	`string`	Yes	User identity within the tenant supplied by the trusted host.
`correlationId`	`string`	Yes	Identity grouping causally related workflow requests and events.
`purpose`	`string`	Yes	Named consent or agent-task purpose used by host policy evaluation.
`jobKind`	`AgentJobKind`	No	General agent use-case; workflow proposals are only one supported kind.
`input`	`TInput`	Yes	Domain request value passed to the admitted operation; no domain-schema proof is implied solely by this type.
`toolScope`	`WorkflowAgentToolScope`	Yes	Requested tool mode and exact allowed names; enforcement is host/runtime-owned.
`idempotencyKey`	`string`	Yes	Replay identity for the same admitted operation; the host must persist/deduplicate it before unsafe retries.
`timeoutMs`	`number`	No	Optional execution deadline in milliseconds; enforcement belongs to the API/runtime consuming this metadata.

Returns

Type declaration; no runtime value.

Type parameters

TInput: Agent job input shape carried to the host runtime; defaults to unknown.

Public members

`taskId`

Task identity correlating the agent/runtime operation with its owning workflow or task board.

`workflowId`

Workflow definition identity used to correlate execution and effects.

`tenantId`

Verified tenant boundary for the record or operation; host authorization must establish this scope.

`userId`

User identity within the tenant supplied by the trusted host.

`correlationId`

Identity grouping causally related workflow requests and events.

`purpose`

Named consent or agent-task purpose used by host policy evaluation.

`jobKind`

General agent use-case; workflow proposals are only one supported kind.

`input`

Domain request value passed to the admitted operation; no domain-schema proof is implied solely by this type.

`toolScope`

Requested tool mode and exact allowed names; enforcement is host/runtime-owned.

`idempotencyKey`

Replay identity for the same admitted operation; the host must persist/deduplicate it before unsafe retries.

`timeoutMs`

Optional execution deadline in milliseconds; enforcement belongs to the API/runtime consuming this metadata.

Example

See the owning declaration and linked feature guide for usage; no standalone example is documented in source.

[TYPE] `WorkflowAgentRiskLevel`

Risk labels carried by workflow proposals and action intents.

Imports: @alneas/eaos-core, @alneas/eaos-core/workflow-contracts.

Signature

type WorkflowAgentRiskLevel = 'low' | 'medium' | 'high' | 'critical';

Parameters

Name	Type	Required	Description
—	—	—	No call parameters.

Returns

Type declaration; no runtime value.

Example

See the owning declaration and linked feature guide for usage; no standalone example is documented in source.

[INTERFACE] `WorkflowAgentRunner`

Host-owned runtime port. The implementation may be Goose, Hermes or another agent.

Imports: @alneas/eaos-core, @alneas/eaos-core/workflow-contracts.

Signature

interface WorkflowAgentRunner {
    run<TOutput>(request: WorkflowAgentRequest): Promise<WorkflowAgentRunResult<TOutput>>;
}

Parameters

Name	Type	Required	Description
`run`	`Promise<WorkflowAgentRunResult<TOutput>>`	Yes	Execute a tenant-scoped agent request through a host runtime.

Returns

Type declaration; no runtime value.

Public members

`run`

Execute a tenant-scoped agent request through a host runtime.

Parameters:

request: Verified scope, input, allowed tools and replay identity; optional timeout is milliseconds.

Returns: Runtime status and optional proposal/failure/usage; domain output remains caller-validated.

Type parameters

TOutput: Expected proposal output type; host/caller validates the domain shape.

Remarks

Host owns process lifecycle, timeout/cancellation, tool authorization, resources and replay safety. An action proposal is never approval.

Errors and rejections

Host runtime failures may reject; classified failures can also be returned as result data.

Example:

import type { WorkflowAgentRunner } from "@alneas/eaos-core/workflow-contracts";
async function runHostAgent(runner: WorkflowAgentRunner, request: Parameters<WorkflowAgentRunner["run"]>[0]) { return runner.run(request); }

Example

See the owning declaration and linked feature guide for usage; no standalone example is documented in source.

[INTERFACE] `WorkflowAgentRunResult`

Runtime status, optional proposal/failure metadata and elapsed duration.

Imports: @alneas/eaos-core, @alneas/eaos-core/workflow-contracts.

Signature

interface WorkflowAgentRunResult<TOutput = unknown> {
    status: WorkflowAgentRunStatus;
    proposal?: WorkflowAgentProposal<TOutput>;
    runtimeId?: string;
    error?: string;
    failureCode?: WorkflowAgentFailureCode;
    retryable?: boolean;
    durationMs: number;
    usage?: WorkflowAgentUsage;
}

Parameters

Name	Type	Required	Description
`status`	`WorkflowAgentRunStatus`	Yes	Runtime completed/unavailable/failed outcome; output remains separately validated.
`proposal`	`WorkflowAgentProposal<TOutput>`	No	Optional reviewable output produced by the agent runtime.
`runtimeId`	`string`	No	Optional host/runtime implementation identity.
`error`	`string`	No	Optional human-readable failure detail; absence does not independently establish success.
`failureCode`	`WorkflowAgentFailureCode`	No	Host/runtime classification for circuit breakers and durable retry policy.
`retryable`	`boolean`	No	Whether the recorded failure permits a host retry; callers must still account for possible completed effects.
`durationMs`	`number`	Yes	Measured elapsed duration in milliseconds.
`usage`	`WorkflowAgentUsage`	No	Optional token/cost telemetry reported by a host/runtime; absence does not mean zero use.

Returns

Type declaration; no runtime value.

Type parameters

TOutput: Proposed domain output type; defaults to unknown and does not imply schema validation.

Public members

`status`

Runtime completed/unavailable/failed outcome; output remains separately validated.

`proposal`

Optional reviewable output produced by the agent runtime.

`runtimeId`

Optional host/runtime implementation identity.

`error`

Optional human-readable failure detail; absence does not independently establish success.

`failureCode`

Host/runtime classification for circuit breakers and durable retry policy.

`retryable`

Whether the recorded failure permits a host retry; callers must still account for possible completed effects.

`durationMs`

Measured elapsed duration in milliseconds.

`usage`

Optional token/cost telemetry reported by a host/runtime; absence does not mean zero use.

Example

See the owning declaration and linked feature guide for usage; no standalone example is documented in source.

[TYPE] `WorkflowAgentRunStatus`

External runtime completion, unavailability or failure status.

Imports: @alneas/eaos-core, @alneas/eaos-core/workflow-contracts.

Signature

type WorkflowAgentRunStatus = 'COMPLETED' | 'UNAVAILABLE' | 'FAILED';

Parameters

Name	Type	Required	Description
—	—	—	No call parameters.

Returns

Type declaration; no runtime value.

Example

See the owning declaration and linked feature guide for usage; no standalone example is documented in source.

[TYPE] `WorkflowAgentToolMode`

Vendor-neutral contracts for running an external agent inside an EAOS workflow. Goose, Hermes and other runtimes are host implementations of these contracts; core does not know how a runtime is started.

Imports: @alneas/eaos-core, @alneas/eaos-core/workflow-contracts.

Signature

type WorkflowAgentToolMode = 'read' | 'preview' | 'action';

Parameters

Name	Type	Required	Description
—	—	—	No call parameters.

Returns

Type declaration; no runtime value.

Example

See the owning declaration and linked feature guide for usage; no standalone example is documented in source.

[INTERFACE] `WorkflowAgentToolScope`

Requested tool mode and explicit allowed tool-name list.

Imports: @alneas/eaos-core, @alneas/eaos-core/workflow-contracts.

Signature

interface WorkflowAgentToolScope {
    mode: WorkflowAgentToolMode;
    allowedToolNames: readonly string[];
}

Parameters

Name	Type	Required	Description
`mode`	`WorkflowAgentToolMode`	Yes	Selected operation/storage/execution variant; the owning discriminated union determines applicable fields.
`allowedToolNames`	`readonly string[]`	Yes	Explicit tool-name allowlist to enforce at the host execution boundary.

Returns

Type declaration; no runtime value.

Public members

`mode`

Selected operation/storage/execution variant; the owning discriminated union determines applicable fields.

`allowedToolNames`

Explicit tool-name allowlist to enforce at the host execution boundary.

Example

See the owning declaration and linked feature guide for usage; no standalone example is documented in source.

[INTERFACE] `WorkflowAgentUsage`

Optional runtime-reported token counts and US-dollar cost.

Imports: @alneas/eaos-core, @alneas/eaos-core/workflow-contracts.

Signature

interface WorkflowAgentUsage {
    inputTokens?: number;
    outputTokens?: number;
    totalTokens?: number;
    costUsd?: number;
}

Parameters

Name	Type	Required	Description
`inputTokens`	`number`	No	Optional count of tokens consumed as model/runtime input.
`outputTokens`	`number`	No	Optional count of generated model/runtime tokens.
`totalTokens`	`number`	No	Optional total token count reported by the provider/runtime.
`costUsd`	`number`	No	Optional runtime-reported cost in US dollars.

Returns

Type declaration; no runtime value.

Public members

`inputTokens`

Optional count of tokens consumed as model/runtime input.

`outputTokens`

Optional count of generated model/runtime tokens.

`totalTokens`

Optional total token count reported by the provider/runtime.

`costUsd`

Optional runtime-reported cost in US dollars.

Example

See the owning declaration and linked feature guide for usage; no standalone example is documented in source.

[INTERFACE] `WorkflowApprovalDefinition`

Declared operation/risk/review metadata for an approval node.

Imports: @alneas/eaos-core, @alneas/eaos-core/workflow-definition.

Signature

interface WorkflowApprovalDefinition {
    toolName: string;
    approvalLevel: ApprovalLevel;
    riskLevel: RiskLevel;
    reason: string;
    argsPath?: string;
    permission?: string;
    contractVersion?: string;
}

Parameters

Name	Type	Required	Description
`toolName`	`string`	Yes	Registered tool identity used to resolve host execution policy.
`approvalLevel`	`ApprovalLevel`	Yes	Required organizational review category; a level declaration is not proof of approval.
`riskLevel`	`RiskLevel`	Yes	Declared operation risk used to determine review requirements; it does not itself grant authorization.
`reason`	`string`	Yes	Human-readable explanation of the decision or requested action.
`argsPath`	`string`	No	State path containing the operation arguments, for example context.approvalArgs.
`permission`	`string`	No	Host permission identity required for this operation.
`contractVersion`	`string`	No	Optional version of the operation meaning used by the host approval path.

Returns

Type declaration; no runtime value.

Public members

`toolName`

Registered tool identity used to resolve host execution policy.

`approvalLevel`

Required organizational review category; a level declaration is not proof of approval.

`riskLevel`

Declared operation risk used to determine review requirements; it does not itself grant authorization.

`reason`

Human-readable explanation of the decision or requested action.

`argsPath`

State path containing the operation arguments, for example context.approvalArgs.

`permission`

Host permission identity required for this operation.

`contractVersion`

Optional version of the operation meaning used by the host approval path.

Example

See the owning declaration and linked feature guide for usage; no standalone example is documented in source.

[TYPE] `WorkflowCondition`

Recursive leaf, conjunction, disjunction or negation predicate without executable expressions.

Imports: @alneas/eaos-core, @alneas/eaos-core/workflow-definition.

Signature

type WorkflowCondition = WorkflowLeafCondition | {
    all: readonly WorkflowCondition[];
} | {
    any: readonly WorkflowCondition[];
} | {
    not: WorkflowCondition;
};

Parameters

Name	Type	Required	Description
—	—	—	No call parameters.

Returns

Type declaration; no runtime value.

Public members

`all`

Nonempty conjunction of up to 32 child conditions; all must match.

`any`

Nonempty disjunction of up to 32 child conditions; at least one must match.

`not`

Single nested condition whose result is inverted.

Example

See the owning declaration and linked feature guide for usage; no standalone example is documented in source.

[TYPE] `WorkflowConditionOperator`

Safe data comparison operators supported by condition evaluation.

Imports: @alneas/eaos-core, @alneas/eaos-core/workflow-definition.

Signature

type WorkflowConditionOperator = 'equals' | 'not_equals' | 'in' | 'not_in' | 'exists' | 'truthy' | 'falsy' | 'greater_than' | 'greater_or_equal' | 'less_than' | 'less_or_equal';

Parameters

Name	Type	Required	Description
—	—	—	No call parameters.

Returns

Type declaration; no runtime value.

Example

See the owning declaration and linked feature guide for usage; no standalone example is documented in source.

[INTERFACE] `WorkflowDefinition`

Versioned serializable workflow graph validated before host compilation.

Imports: @alneas/eaos-core, @alneas/eaos-core/workflow-definition.

Signature

interface WorkflowDefinition {
    schemaVersion: '1.0';
    workflowId: string;
    version: string;
    entryNode: string;
    nodes: readonly WorkflowDefinitionNode[];
    edges: readonly WorkflowDefinitionEdge[];
    metadata?: Record<string, unknown>;
}

Parameters

Name	Type	Required	Description
`schemaVersion`	`'1.0'`	Yes	Envelope format discriminator accepted by the corresponding parser/validator.
`workflowId`	`string`	Yes	Workflow definition identity used to correlate execution and effects.
`version`	`string`	Yes	Host workflow version text, up to 64 nonblank characters; runtime validation does not require semver.
`entryNode`	`string`	Yes	Identity of the graph node where host execution/display begins.
`nodes`	`readonly WorkflowDefinitionNode[]`	Yes	Graph vertices in supplied order; this metadata does not execute node handlers.
`edges`	`readonly WorkflowDefinitionEdge[]`	Yes	Directed graph relationships in supplied order; validation/rendering behavior follows the owning graph contract.
`metadata`	`Record<string, unknown>`	No	Optional host/provider metadata; callers remain responsible for sensitive content and validation.

Returns

Type declaration; no runtime value.

Public members

`schemaVersion`

Envelope format discriminator accepted by the corresponding parser/validator.

`workflowId`

Workflow definition identity used to correlate execution and effects.

`version`

Host workflow version text, up to 64 nonblank characters; runtime validation does not require semver.

`entryNode`

Identity of the graph node where host execution/display begins.

`nodes`

Graph vertices in supplied order; this metadata does not execute node handlers.

`edges`

Directed graph relationships in supplied order; validation/rendering behavior follows the owning graph contract.

`metadata`

Optional host/provider metadata; callers remain responsible for sensitive content and validation.

Example

See the owning declaration and linked feature guide for usage; no standalone example is documented in source.

[INTERFACE] `WorkflowDefinitionEdge`

Directed edge with an optional data-only condition or explicit fallback marker.

Imports: @alneas/eaos-core, @alneas/eaos-core/workflow-definition.

Signature

interface WorkflowDefinitionEdge {
    from: string;
    to: string;
    label?: string;
    condition?: WorkflowCondition;
    default?: boolean;
}

Parameters

Name	Type	Required	Description
`from`	`string`	Yes	Existing source node ID; outgoing fallback/conditional consistency is validated per source.
`to`	`string`	Yes	Existing destination node ID; unknown endpoints are rejected during definition validation.
`label`	`string`	No	Human-readable navigation/node/setting label displayed by the host.
`condition`	`WorkflowCondition`	No	Data-only routing predicate or host-reviewed instruction; no expression string is executed by Core.
`default`	`boolean`	No	Optional fallback edge marker; at most one per source node.

Returns

Type declaration; no runtime value.

Public members

`from`

Existing source node ID; outgoing fallback/conditional consistency is validated per source.

`to`

Existing destination node ID; unknown endpoints are rejected during definition validation.

`label`

Human-readable navigation/node/setting label displayed by the host.

`condition`

Data-only routing predicate or host-reviewed instruction; no expression string is executed by Core.

`default`

Optional fallback edge marker; at most one per source node.

Example

See the owning declaration and linked feature guide for usage; no standalone example is documented in source.

[TYPE] `WorkflowDefinitionLifecycle`

Publication stages for a host-managed workflow definition.

Imports: @alneas/eaos-core, @alneas/eaos-core/workflow-definition.

Signature

type WorkflowDefinitionLifecycle = 'draft' | 'validated' | 'approved' | 'published' | 'retired';

Parameters

Name	Type	Required	Description
—	—	—	No call parameters.

Returns

Type declaration; no runtime value.

Example

See the owning declaration and linked feature guide for usage; no standalone example is documented in source.

[INTERFACE] `WorkflowDefinitionNode`

Serializable node type, host configuration and optional execution policies.

Imports: @alneas/eaos-core, @alneas/eaos-core/workflow-definition.

Signature

interface WorkflowDefinitionNode {
    id: string;
    type: string;
    kind?: WorkflowDefinitionNodeKind;
    label?: string;
    description?: string;
    pluginId?: string;
    config?: Record<string, unknown>;
    approval?: WorkflowApprovalDefinition;
    retry?: WorkflowRetryDefinition;
    timeoutMs?: number;
    subflow?: WorkflowSubflowDefinition;
    toolScope?: WorkflowToolScopeDefinition;
}

Parameters

Name	Type	Required	Description
`id`	`string`	Yes	Unique lowercase graph node identity referenced by entryNode and edges.
`type`	`string`	Yes	Host-registered node handler/compiler type; structural validation does not prove the handler exists.
`kind`	`WorkflowDefinitionNodeKind`	No	Semantic workflow node category; definition omission leaves interpretation to the host.
`label`	`string`	No	Human-readable navigation/node/setting label displayed by the host.
`description`	`string`	No	Human-readable metadata describing the capability, workflow node or requirement to host users.
`pluginId`	`string`	No	Owning plugin identity used for capability scope and discovery.
`config`	`Record<string, unknown>`	No	Host configuration metadata; plugin/node configuration is data and does not execute code by itself.
`approval`	`WorkflowApprovalDefinition`	No	Optional host review metadata; an approved value must be established by a trusted host, never by model output.
`retry`	`WorkflowRetryDefinition`	No	Optional bounded retry metadata interpreted by the host workflow compiler/runtime.
`timeoutMs`	`number`	No	Optional execution deadline in milliseconds; enforcement belongs to the API/runtime consuming this metadata.
`subflow`	`WorkflowSubflowDefinition`	No	Optional referenced workflow version and state mapping; no subflow is run during validation.
`toolScope`	`WorkflowToolScopeDefinition`	No	Requested tool mode and exact allowed names; enforcement is host/runtime-owned.

Returns

Type declaration; no runtime value.

Public members

`id`

Unique lowercase graph node identity referenced by entryNode and edges.

`type`

Host-registered node handler/compiler type; structural validation does not prove the handler exists.

`kind`

Semantic workflow node category; definition omission leaves interpretation to the host.

`label`

Human-readable navigation/node/setting label displayed by the host.

`description`

Human-readable metadata describing the capability, workflow node or requirement to host users.

`pluginId`

Owning plugin identity used for capability scope and discovery.

`config`

Host configuration metadata; plugin/node configuration is data and does not execute code by itself.

`approval`

Optional host review metadata; an approved value must be established by a trusted host, never by model output.

`retry`

Optional bounded retry metadata interpreted by the host workflow compiler/runtime.

`timeoutMs`

Optional execution deadline in milliseconds; enforcement belongs to the API/runtime consuming this metadata.

`subflow`

Optional referenced workflow version and state mapping; no subflow is run during validation.

`toolScope`

Requested tool mode and exact allowed names; enforcement is host/runtime-owned.

Example

See the owning declaration and linked feature guide for usage; no standalone example is documented in source.

[TYPE] `WorkflowDefinitionNodeKind`

Semantic categories used by workflow editors and host compilers.

Imports: @alneas/eaos-core, @alneas/eaos-core/workflow-definition.

Signature

type WorkflowDefinitionNodeKind = 'trigger' | 'task' | 'agent' | 'human_review' | 'approval' | 'effect' | 'subgraph' | 'wait' | 'system' | 'custom';

Parameters

Name	Type	Required	Description
—	—	—	No call parameters.

Returns

Type declaration; no runtime value.

Example

See the owning declaration and linked feature guide for usage; no standalone example is documented in source.

[INTERFACE] `WorkflowEffectAdapter`

Host execution and optional reconciliation port for effects with replay identity.

Imports: @alneas/eaos-core, @alneas/eaos-core/agent/workflow-effects.

Signature

interface WorkflowEffectAdapter<TInput = unknown, TOutput = unknown> {
    execute(request: WorkflowEffectRequest<TInput>): Promise<WorkflowEffectResult<TOutput>>;
    reconcile?(request: WorkflowEffectRequest<TInput>, previous: WorkflowEffectReceipt): Promise<WorkflowEffectResult<TOutput>>;
}

Parameters

Name	Type	Required	Description
`execute`	`Promise<WorkflowEffectResult<TOutput>>`	Yes	Execute an admitted workflow effect through the connected host adapter.
`reconcile`	`Promise<WorkflowEffectResult<TOutput>>`	No	Reconcile a previous uncertain or failed effect using the exact admitted request.

Returns

Type declaration; no runtime value.

Type parameters

TInput: Admitted domain request shape; default unknown.
TOutput: Domain output accompanying the authoritative receipt; default unknown.

Public members

`execute`

Execute an admitted workflow effect through the connected host adapter.

Parameters:

request: Exact tenant/workflow/operation/input and replay key admitted by host policy.

Returns: Provider receipt and optional output; failed/unknown outcomes remain data and must be reconciled.

Remarks

Host owns idempotency, authorization, provider persistence and deadlines; Core does not implement an adapter or retry. A rejection can follow a partially completed effect.

Errors and rejections

Host adapter errors/rejections propagate.

Example:

import type { WorkflowEffectAdapter } from "@alneas/eaos-core/agent/workflow-effects";
async function executeHost(adapter: WorkflowEffectAdapter, request: Parameters<WorkflowEffectAdapter["execute"]>[0]) { return adapter.execute(request); }

`reconcile`

Reconcile a previous uncertain or failed effect using the exact admitted request.

Parameters:

request: Original admitted request, including its unchanged replay identity/input.
previous: Previous receipt to reconcile rather than blindly replaying an effect.

Returns: Current provider receipt and optional output; outcome can remain unknown.

Remarks

Optional host capability; absence is not evidence that a retry is safe.

Errors and rejections

Host reconciliation errors/rejections propagate; external state may remain uncertain.

Example:

import type { WorkflowEffectAdapter } from "@alneas/eaos-core/agent/workflow-effects";
async function reconcileHost(adapter: WorkflowEffectAdapter, request: Parameters<WorkflowEffectAdapter["execute"]>[0], previous: Parameters<NonNullable<WorkflowEffectAdapter["reconcile"]>>[1]) {
 if (!adapter.reconcile) throw new Error("Host reconciliation is unavailable");
 return adapter.reconcile(request, previous);
}

Example

See the owning declaration and linked feature guide for usage; no standalone example is documented in source.

[TYPE] `WorkflowEffectOutcome`

Reported effect result; unknown requires reconciliation rather than assuming success or safe retry.

Imports: @alneas/eaos-core, @alneas/eaos-core/agent/workflow-effects.

Signature

type WorkflowEffectOutcome = 'succeeded' | 'failed' | 'unknown';

Parameters

Name	Type	Required	Description
—	—	—	No call parameters.

Returns

Type declaration; no runtime value.

Example

See the owning declaration and linked feature guide for usage; no standalone example is documented in source.

[INTERFACE] `WorkflowEffectReceipt`

Provider outcome bound to the exact admitted request and its input hash.

Imports: @alneas/eaos-core, @alneas/eaos-core/agent/workflow-effects.

Signature

interface WorkflowEffectReceipt {
    schemaVersion: '1';
    tenantId: string;
    workflowId: string;
    operation: string;
    idempotencyKey: string;
    inputHash: string;
    adapterId: string;
    receiptId: string;
    outcome: WorkflowEffectOutcome;
    occurredAt: string;
    externalId?: string;
    errorCode?: string;
    metadata?: Readonly<Record<string, unknown>>;
}

Parameters

Name	Type	Required	Description
`schemaVersion`	`'1'`	Yes	Envelope format discriminator accepted by the corresponding parser/validator.
`tenantId`	`string`	Yes	Verified tenant boundary for the record or operation; host authorization must establish this scope.
`workflowId`	`string`	Yes	Workflow definition identity used to correlate execution and effects.
`operation`	`string`	Yes	Operation identity whose meaning and permission are controlled by the host.
`idempotencyKey`	`string`	Yes	Replay identity for the same admitted operation; the host must persist/deduplicate it before unsafe retries.
`inputHash`	`string`	Yes	SHA-256 identity of the canonical JSON request input.
`adapterId`	`string`	Yes	Host adapter identity that binds routing/receipts to the implementation actually used.
`receiptId`	`string`	Yes	Provider/host identity of the effect receipt.
`outcome`	`WorkflowEffectOutcome`	Yes	Reported success/failure/denial/unknown category; reconcile uncertain effects before retrying.
`occurredAt`	`string`	Yes	Event/effect occurrence timestamp; creation helpers normalize supported inputs to ISO text.
`externalId`	`string`	No	Optional external resource identity reported by the provider.
`errorCode`	`string`	No	Optional machine-readable provider failure code.
`metadata`	`Readonly<Record<string, unknown>>`	No	Optional host/provider metadata; callers remain responsible for sensitive content and validation.

Returns

Type declaration; no runtime value.

Public members

`schemaVersion`

Envelope format discriminator accepted by the corresponding parser/validator.

`tenantId`

Verified tenant boundary for the record or operation; host authorization must establish this scope.

`workflowId`

Workflow definition identity used to correlate execution and effects.

`operation`

Operation identity whose meaning and permission are controlled by the host.

`idempotencyKey`

Replay identity for the same admitted operation; the host must persist/deduplicate it before unsafe retries.

`inputHash`

SHA-256 identity of the canonical JSON request input.

`adapterId`

Host adapter identity that binds routing/receipts to the implementation actually used.

`receiptId`

Provider/host identity of the effect receipt.

`outcome`

Reported success/failure/denial/unknown category; reconcile uncertain effects before retrying.

`occurredAt`

Event/effect occurrence timestamp; creation helpers normalize supported inputs to ISO text.

`externalId`

Optional external resource identity reported by the provider.

`errorCode`

Optional machine-readable provider failure code.

`metadata`

Optional host/provider metadata; callers remain responsible for sensitive content and validation.

Example

See the owning declaration and linked feature guide for usage; no standalone example is documented in source.

[INTERFACE] `WorkflowEffectRequest`

Admitted tenant/workflow operation and replay identity supplied to an effect adapter.

Imports: @alneas/eaos-core, @alneas/eaos-core/agent/workflow-effects.

Signature

interface WorkflowEffectRequest<TInput = unknown> {
    tenantId: string;
    workflowId: string;
    operation: string;
    idempotencyKey: string;
    input: TInput;
    target?: {
        type: string;
        id: string;
        revision?: number;
    };
}

Parameters

Name	Type	Required	Description
`tenantId`	`string`	Yes	Verified tenant boundary for the record or operation; host authorization must establish this scope.
`workflowId`	`string`	Yes	Workflow definition identity used to correlate execution and effects.
`operation`	`string`	Yes	Operation identity whose meaning and permission are controlled by the host.
`idempotencyKey`	`string`	Yes	Replay identity for the same admitted operation; the host must persist/deduplicate it before unsafe retries.
`input`	`TInput`	Yes	Domain request value passed to the admitted operation; no domain-schema proof is implied solely by this type.
`target`	`{ type: string; id: string; revision?: number; }`	No	Approved resource identity or execution placement; this metadata does not independently enforce access.

Returns

Type declaration; no runtime value.

Type parameters

TInput: Domain input type supplied to the effect adapter; defaults to unknown.

Public members

`tenantId`

Verified tenant boundary for the record or operation; host authorization must establish this scope.

`workflowId`

Workflow definition identity used to correlate execution and effects.

`operation`

Operation identity whose meaning and permission are controlled by the host.

`idempotencyKey`

Replay identity for the same admitted operation; the host must persist/deduplicate it before unsafe retries.

`input`

Domain request value passed to the admitted operation; no domain-schema proof is implied solely by this type.

`target`

Approved resource identity or execution placement; this metadata does not independently enforce access.

`target.type`

Resource category used with its ID and optional revision to bind the exact execution target.

`target.id`

Effect target resource identity; at most 512 nonblank characters when normalized.

`target.revision`

Optional source/target revision interpreted by the owning host; approval/effect target revisions must be positive integers.

Example

See the owning declaration and linked feature guide for usage; no standalone example is documented in source.

[INTERFACE] `WorkflowEffectResult`

A provider receipt and optional domain output; receipt outcome remains authoritative.

Imports: @alneas/eaos-core, @alneas/eaos-core/agent/workflow-effects.

Signature

interface WorkflowEffectResult<TOutput = unknown> {
    receipt: WorkflowEffectReceipt;
    output?: TOutput;
}

Parameters

Name	Type	Required	Description
`receipt`	`WorkflowEffectReceipt`	Yes	Authoritative host operation receipt; inspect its status/outcome before treating optional output as successful.
`output`	`TOutput`	No	Optional domain output; validate it separately and inspect the accompanying status/receipt.

Returns

Type declaration; no runtime value.

Type parameters

TOutput: Optional provider output type; default unknown, with success determined by receipt outcome.

Public members

`receipt`

Authoritative host operation receipt; inspect its status/outcome before treating optional output as successful.

`output`

Optional domain output; validate it separately and inspect the accompanying status/receipt.

Example

See the owning declaration and linked feature guide for usage; no standalone example is documented in source.

[INTERFACE] `WorkflowEventEnvelope`

Tenant-scoped aggregate event with causation, replay identity and typed payload.

Imports: @alneas/eaos-core, @alneas/eaos-core/workflow-runtime.

Signature

interface WorkflowEventEnvelope<TPayload = unknown> {
    eventId: string;
    tenantId: string;
    workflowInstanceId?: string;
    aggregateType: string;
    aggregateId: string;
    aggregateRevision: number;
    type: string;
    producer: string;
    correlationId: string;
    causationId?: string;
    idempotencyKey: string;
    occurredAt: string;
    payload: TPayload;
}

Parameters

Name	Type	Required	Description
`eventId`	`string`	Yes	Stable event identity used for projection and causal correlation.
`tenantId`	`string`	Yes	Verified tenant boundary for the record or operation; host authorization must establish this scope.
`workflowInstanceId`	`string`	No	Optional durable instance identity correlating this event/job with a workflow.
`aggregateType`	`string`	Yes	Domain aggregate category whose state change this event describes.
`aggregateId`	`string`	Yes	Domain aggregate identity within the tenant.
`aggregateRevision`	`number`	Yes	Nonnegative safe-integer domain revision associated with this event.
`type`	`string`	Yes	Domain event type used for consumer/projector dispatch.
`producer`	`string`	Yes	Stable component identity emitting the event.
`correlationId`	`string`	Yes	Identity grouping causally related workflow requests and events.
`causationId`	`string`	No	Optional identity of the event/request that caused this event.
`idempotencyKey`	`string`	Yes	Replay identity for the same admitted operation; the host must persist/deduplicate it before unsafe retries.
`occurredAt`	`string`	Yes	Event/effect occurrence timestamp; creation helpers normalize supported inputs to ISO text.
`payload`	`TPayload`	Yes	Typed event/request body; constructors clone and strictly hash JSON where documented.

Returns

Type declaration; no runtime value.

Type parameters

TPayload: Domain event payload shape; defaults to unknown.

Public members

`eventId`

Stable event identity used for projection and causal correlation.

`tenantId`

Verified tenant boundary for the record or operation; host authorization must establish this scope.

`workflowInstanceId`

Optional durable instance identity correlating this event/job with a workflow.

`aggregateType`

Domain aggregate category whose state change this event describes.

`aggregateId`

Domain aggregate identity within the tenant.

`aggregateRevision`

Nonnegative safe-integer domain revision associated with this event.

`type`

Domain event type used for consumer/projector dispatch.

`producer`

Stable component identity emitting the event.

`correlationId`

Identity grouping causally related workflow requests and events.

`causationId`

Optional identity of the event/request that caused this event.

`idempotencyKey`

Replay identity for the same admitted operation; the host must persist/deduplicate it before unsafe retries.

`occurredAt`

Event/effect occurrence timestamp; creation helpers normalize supported inputs to ISO text.

`payload`

Typed event/request body; constructors clone and strictly hash JSON where documented.

Example

See the owning declaration and linked feature guide for usage; no standalone example is documented in source.

[INTERFACE] `WorkflowEventSink`

Host append boundary for typed workflow event envelopes.

Imports: @alneas/eaos-core, @alneas/eaos-core/workflow-runtime.

Signature

interface WorkflowEventSink {
    append<TPayload>(event: WorkflowEventEnvelope<TPayload>): Promise<void>;
}

Parameters

Name	Type	Required	Description
`append`	`Promise<void>`	Yes	Append a tenant-scoped workflow event through host persistence.

Returns

Type declaration; no runtime value.

Public members

`append`

Append a tenant-scoped workflow event through host persistence.

Parameters:

event: Complete event envelope with stable identity, revision and replay key.

Returns: No value; host append has completed.

Type parameters

TPayload: Domain payload type retained by the supplied event envelope.

Remarks

Host defines persistence transactions, deduplication, event ordering and partial-append reconciliation.

Errors and rejections

Host append failures reject; a rejection may follow a committed write.

Example:

import type { WorkflowEventSink } from "@alneas/eaos-core/workflow-runtime";
async function appendHostEvent(sink: WorkflowEventSink, event: Parameters<WorkflowEventSink["append"]>[0]) { await sink.append(event); }

Example

See the owning declaration and linked feature guide for usage; no standalone example is documented in source.

[INTERFACE] `WorkflowGraphDescription`

Versioned graph metadata with entry node and ordered nodes/edges.

Imports: @alneas/eaos-core, @alneas/eaos-core/workflow-visualization.

Signature

interface WorkflowGraphDescription {
    schemaVersion: '1.0';
    workflowId?: string;
    workflowVersion?: string;
    entryNode: string;
    nodes: readonly WorkflowGraphNode[];
    edges: readonly WorkflowGraphEdge[];
}

Parameters

Name	Type	Required	Description
`schemaVersion`	`'1.0'`	Yes	Envelope format discriminator accepted by the corresponding parser/validator.
`workflowId`	`string`	No	Workflow definition identity used to correlate execution and effects.
`workflowVersion`	`string`	No	Version of the workflow definition pinned to this runtime/display record.
`entryNode`	`string`	Yes	Identity of the graph node where host execution/display begins.
`nodes`	`readonly WorkflowGraphNode[]`	Yes	Graph vertices in supplied order; this metadata does not execute node handlers.
`edges`	`readonly WorkflowGraphEdge[]`	Yes	Directed graph relationships in supplied order; validation/rendering behavior follows the owning graph contract.

Returns

Type declaration; no runtime value.

Public members

`schemaVersion`

Envelope format discriminator accepted by the corresponding parser/validator.

`workflowId`

Workflow definition identity used to correlate execution and effects.

`workflowVersion`

Version of the workflow definition pinned to this runtime/display record.

`entryNode`

Identity of the graph node where host execution/display begins.

`nodes`

Graph vertices in supplied order; this metadata does not execute node handlers.

`edges`

Directed graph relationships in supplied order; validation/rendering behavior follows the owning graph contract.

Example

See the owning declaration and linked feature guide for usage; no standalone example is documented in source.

[INTERFACE] `WorkflowGraphEdge`

Display connection with endpoint IDs and a resolved category.

Imports: @alneas/eaos-core, @alneas/eaos-core/workflow-visualization.

Signature

interface WorkflowGraphEdge extends WorkflowGraphEdgeInput {
    from: string;
    to: string;
    kind: WorkflowGraphEdgeKind;
}

Parameters

Name	Type	Required	Description
`from`	`string`	Yes	Display source node ID; renderers omit edges with unknown endpoints.
`to`	`string`	Yes	Display destination node ID; renderers omit edges with unknown endpoints.
`kind`	`WorkflowGraphEdgeKind`	Yes	Display connection category; it has no executable routing effect by itself.

Returns

Type declaration; no runtime value.

Public members

`from`

Display source node ID; renderers omit edges with unknown endpoints.

`to`

Display destination node ID; renderers omit edges with unknown endpoints.

`kind`

Display connection category; it has no executable routing effect by itself.

Example

See the owning declaration and linked feature guide for usage; no standalone example is documented in source.

[INTERFACE] `WorkflowGraphEdgeInput`

Optional display category, label and condition description for an edge.

Imports: @alneas/eaos-core, @alneas/eaos-core/workflow-visualization.

Signature

interface WorkflowGraphEdgeInput {
    kind?: WorkflowGraphEdgeKind;
    label?: string;
    condition?: string;
}

Parameters

Name	Type	Required	Description
`kind`	`WorkflowGraphEdgeKind`	No	Display connection category; it has no executable routing effect by itself.
`label`	`string`	No	Human-readable navigation/node/setting label displayed by the host.
`condition`	`string`	No	Data-only routing predicate or host-reviewed instruction; no expression string is executed by Core.

Returns

Type declaration; no runtime value.

Public members

`kind`

Display connection category; it has no executable routing effect by itself.

`label`

Human-readable navigation/node/setting label displayed by the host.

`condition`

Data-only routing predicate or host-reviewed instruction; no expression string is executed by Core.

Example

See the owning declaration and linked feature guide for usage; no standalone example is documented in source.

[TYPE] `WorkflowGraphEdgeKind`

Display categories for workflow graph connections.

Imports: @alneas/eaos-core, @alneas/eaos-core/workflow-visualization.

Signature

type WorkflowGraphEdgeKind = 'normal' | 'conditional' | 'approval' | 'system';

Parameters

Name	Type	Required	Description
—	—	—	No call parameters.

Returns

Type declaration; no runtime value.

Example

See the owning declaration and linked feature guide for usage; no standalone example is documented in source.

[INTERFACE] `WorkflowGraphNode`

Display node with resolved identity, kind, label and approval-request flag.

Imports: @alneas/eaos-core, @alneas/eaos-core/workflow-visualization.

Signature

interface WorkflowGraphNode extends WorkflowGraphNodeInput {
    id: string;
    kind: WorkflowGraphNodeKind;
    label: string;
    canRequestApproval: boolean;
}

Parameters

Name	Type	Required	Description
`id`	`string`	Yes	Display node identity used to map edges and runtime highlighting.
`kind`	`WorkflowGraphNodeKind`	Yes	Semantic workflow node category; definition omission leaves interpretation to the host.
`label`	`string`	Yes	Human-readable navigation/node/setting label displayed by the host.
`canRequestApproval`	`boolean`	Yes	Whether the display metadata advertises a possible approval request; not an approval grant.

Returns

Type declaration; no runtime value.

Public members

`id`

Display node identity used to map edges and runtime highlighting.

`kind`

Semantic workflow node category; definition omission leaves interpretation to the host.

`label`

Human-readable navigation/node/setting label displayed by the host.

`canRequestApproval`

Whether the display metadata advertises a possible approval request; not an approval grant.

Example

See the owning declaration and linked feature guide for usage; no standalone example is documented in source.

[INTERFACE] `WorkflowGraphNodeInput`

Serializable, non-executable metadata for displaying an EAOS workflow.

Imports: @alneas/eaos-core, @alneas/eaos-core/workflow-visualization.

Signature

interface WorkflowGraphNodeInput {
    kind?: WorkflowGraphNodeKind;
    label?: string;
    description?: string;
    pluginId?: string;
    approvalLevel?: ApprovalLevel;
    riskLevel?: RiskLevel;
    toolName?: string;
    canRequestApproval?: boolean;
    retryable?: boolean;
    subgraphId?: string;
    subgraphVersion?: string;
}

Parameters

Name	Type	Required	Description
`kind`	`WorkflowGraphNodeKind`	No	Semantic workflow node category; definition omission leaves interpretation to the host.
`label`	`string`	No	Human-readable navigation/node/setting label displayed by the host.
`description`	`string`	No	Human-readable metadata describing the capability, workflow node or requirement to host users.
`pluginId`	`string`	No	Owning plugin identity used for capability scope and discovery.
`approvalLevel`	`ApprovalLevel`	No	Required organizational review category; a level declaration is not proof of approval.
`riskLevel`	`RiskLevel`	No	Declared operation risk used to determine review requirements; it does not itself grant authorization.
`toolName`	`string`	No	Registered tool identity used to resolve host execution policy.
`canRequestApproval`	`boolean`	No	Whether the display metadata advertises a possible approval request; not an approval grant.
`retryable`	`boolean`	No	Whether the recorded failure permits a host retry; callers must still account for possible completed effects.
`subgraphId`	`string`	No	Optional nested workflow identity displayed by the graph viewer.
`subgraphVersion`	`string`	No	Optional nested workflow version displayed by the graph viewer.

Returns

Type declaration; no runtime value.

Public members

`kind`

Semantic workflow node category; definition omission leaves interpretation to the host.

`label`

Human-readable navigation/node/setting label displayed by the host.

`description`

Human-readable metadata describing the capability, workflow node or requirement to host users.

`pluginId`

Owning plugin identity used for capability scope and discovery.

`approvalLevel`

Required organizational review category; a level declaration is not proof of approval.

`riskLevel`

Declared operation risk used to determine review requirements; it does not itself grant authorization.

`toolName`

Registered tool identity used to resolve host execution policy.

`canRequestApproval`

Whether the display metadata advertises a possible approval request; not an approval grant.

`retryable`

Whether the recorded failure permits a host retry; callers must still account for possible completed effects.

`subgraphId`

Optional nested workflow identity displayed by the graph viewer.

`subgraphVersion`

Optional nested workflow version displayed by the graph viewer.

Example

See the owning declaration and linked feature guide for usage; no standalone example is documented in source.

[TYPE] `WorkflowGraphNodeKind`

Display categories for non-executable workflow graph nodes.

Imports: @alneas/eaos-core, @alneas/eaos-core/workflow-visualization.

Signature

type WorkflowGraphNodeKind = 'trigger' | 'task' | 'agent' | 'human_review' | 'approval' | 'effect' | 'subgraph' | 'wait' | 'system' | 'custom';

Parameters

Name	Type	Required	Description
—	—	—	No call parameters.

Returns

Type declaration; no runtime value.

Example

See the owning declaration and linked feature guide for usage; no standalone example is documented in source.

[INTERFACE] `WorkflowGraphRuntimeSnapshot`

Current display state with optional node, pending approval or failure.

Imports: @alneas/eaos-core, @alneas/eaos-core/workflow-visualization.

Signature

interface WorkflowGraphRuntimeSnapshot {
    status: WorkflowGraphRuntimeStatus;
    currentNodeId?: string;
    checkpointRevision?: number;
    pendingApproval?: {
        approvalId?: string;
        toolName: string;
        approvalLevel: ApprovalLevel;
        riskLevel: string;
        reason: string;
    };
    error?: string;
}

Parameters

Name	Type	Required	Description
`status`	`WorkflowGraphRuntimeStatus`	Yes	Display-only runtime lifecycle used by viewers.
`currentNodeId`	`string`	No	Optional node identity highlighted as the current runtime location.
`checkpointRevision`	`number`	No	Optional host checkpoint revision used for optimistic runtime progress.
`pendingApproval`	`{ approvalId?: string; toolName: string; approvalLevel: ApprovalLevel; riskLevel: string; reason: string; }`	No	Optional display-only review request awaiting host decision.
`error`	`string`	No	Optional human-readable failure detail; absence does not independently establish success.

Returns

Type declaration; no runtime value.

Public members

`status`

Display-only runtime lifecycle used by viewers.

`currentNodeId`

Optional node identity highlighted as the current runtime location.

`checkpointRevision`

Optional host checkpoint revision used for optimistic runtime progress.

`pendingApproval`

Optional display-only review request awaiting host decision.

`pendingApproval.approvalId`

Host identity for the review request/decision associated with this operation.

`pendingApproval.toolName`

Registered tool identity used to resolve host execution policy.

`pendingApproval.approvalLevel`

Required organizational review category; a level declaration is not proof of approval.

`pendingApproval.riskLevel`

Declared operation risk used to determine review requirements; it does not itself grant authorization.

`pendingApproval.reason`

Human-readable explanation of the decision or requested action.

`error`

Optional human-readable failure detail; absence does not independently establish success.

Example

See the owning declaration and linked feature guide for usage; no standalone example is documented in source.

[TYPE] `WorkflowGraphRuntimeStatus`

Display statuses for runtime progress snapshots.

Imports: @alneas/eaos-core, @alneas/eaos-core/workflow-visualization.

Signature

type WorkflowGraphRuntimeStatus = 'idle' | 'running' | 'waiting_approval' | 'completed' | 'failed';

Parameters

Name	Type	Required	Description
—	—	—	No call parameters.

Returns

Type declaration; no runtime value.

Example

See the owning declaration and linked feature guide for usage; no standalone example is documented in source.

[INTERFACE] `WorkflowGraphVisualization`

Graph description and optional runtime overlay rendered as a diagram.

Imports: @alneas/eaos-core, @alneas/eaos-core/workflow-visualization.

Signature

interface WorkflowGraphVisualization {
    graph: WorkflowGraphDescription;
    runtime?: WorkflowGraphRuntimeSnapshot;
}

Parameters

Name	Type	Required	Description
`graph`	`WorkflowGraphDescription`	Yes	Serializable non-executable workflow graph description.
`runtime`	`WorkflowGraphRuntimeSnapshot`	No	Optional display overlay of current progress or pending approval.

Returns

Type declaration; no runtime value.

Public members

`graph`

Serializable non-executable workflow graph description.

`runtime`

Optional display overlay of current progress or pending approval.

Example

See the owning declaration and linked feature guide for usage; no standalone example is documented in source.

[INTERFACE] `WorkflowInstanceRecord`

Host-persisted workflow version/identity, domain correlation and current state.

Imports: @alneas/eaos-core, @alneas/eaos-core/workflow-runtime.

Signature

interface WorkflowInstanceRecord {
    instanceId: string;
    workflowId: string;
    workflowVersion: string;
    workflowHash: string;
    tenantId: string;
    userId: string;
    threadId: string;
    status: WorkflowInstanceStatus;
    domainAggregateType?: string;
    domainAggregateId?: string;
    domainRevision?: number;
    checkpointRevision?: number;
    updatedAt: string;
    error?: string;
}

Parameters

Name	Type	Required	Description
`instanceId`	`string`	Yes	Host-generated durable workflow instance identity.
`workflowId`	`string`	Yes	Workflow definition identity used to correlate execution and effects.
`workflowVersion`	`string`	Yes	Version of the workflow definition pinned to this runtime/display record.
`workflowHash`	`string`	Yes	Integrity identity of the exact workflow definition pinned by the host.
`tenantId`	`string`	Yes	Verified tenant boundary for the record or operation; host authorization must establish this scope.
`userId`	`string`	Yes	User identity within the tenant supplied by the trusted host.
`threadId`	`string`	Yes	Host conversation/thread identity for correlation.
`status`	`WorkflowInstanceStatus`	Yes	Host-persisted durable workflow lifecycle separate from graph execution cursor.
`domainAggregateType`	`string`	No	Optional domain aggregate category associated with the workflow instance.
`domainAggregateId`	`string`	No	Optional domain aggregate identity associated with the workflow instance.
`domainRevision`	`number`	No	Optional domain aggregate revision pinned by the host.
`checkpointRevision`	`number`	No	Optional host checkpoint revision used for optimistic runtime progress.
`updatedAt`	`string`	Yes	Timestamp of the latest host-recorded update; this contract does not persist changes.
`error`	`string`	No	Optional human-readable failure detail; absence does not independently establish success.

Returns

Type declaration; no runtime value.

Public members

`instanceId`

Host-generated durable workflow instance identity.

`workflowId`

Workflow definition identity used to correlate execution and effects.

`workflowVersion`

Version of the workflow definition pinned to this runtime/display record.

`workflowHash`

Integrity identity of the exact workflow definition pinned by the host.

`tenantId`

Verified tenant boundary for the record or operation; host authorization must establish this scope.

`userId`

User identity within the tenant supplied by the trusted host.

`threadId`

Host conversation/thread identity for correlation.

`status`

Host-persisted durable workflow lifecycle separate from graph execution cursor.

`domainAggregateType`

Optional domain aggregate category associated with the workflow instance.

`domainAggregateId`

Optional domain aggregate identity associated with the workflow instance.

`domainRevision`

Optional domain aggregate revision pinned by the host.

`checkpointRevision`

Optional host checkpoint revision used for optimistic runtime progress.

`updatedAt`

Timestamp of the latest host-recorded update; this contract does not persist changes.

`error`

Optional human-readable failure detail; absence does not independently establish success.

Example

See the owning declaration and linked feature guide for usage; no standalone example is documented in source.

[TYPE] `WorkflowInstanceStatus`

Durable workflow state is deliberately separate from LangGraph’s execution cursor. Hosts persist this record next to their domain/control data.

Imports: @alneas/eaos-core, @alneas/eaos-core/workflow-runtime.

Signature

type WorkflowInstanceStatus = 'queued' | 'running' | 'waiting_agent' | 'waiting_approval' | 'waiting_external' | 'retryable' | 'failed' | 'completed' | 'cancelled';

Parameters

Name	Type	Required	Description
—	—	—	No call parameters.

Returns

Type declaration; no runtime value.

Example

See the owning declaration and linked feature guide for usage; no standalone example is documented in source.

[INTERFACE] `WorkflowLeafCondition`

Own-property path predicate and optional comparison operand.

Imports: @alneas/eaos-core, @alneas/eaos-core/workflow-definition.

Signature

interface WorkflowLeafCondition {
    path: string;
    operator: WorkflowConditionOperator;
    value?: unknown;
}

Parameters

Name	Type	Required	Description
`path`	`string`	Yes	Dot-separated own-property state path; arrays are not traversed by evaluateWorkflowCondition.
`operator`	`WorkflowConditionOperator`	Yes	Safe comparison operation; exists/truthy/falsy forbid an operand, others require value.
`value`	`unknown`	No	Comparison operand; required except for exists/truthy/falsy, which forbid this field.

Returns

Type declaration; no runtime value.

Public members

`path`

Dot-separated own-property state path; arrays are not traversed by evaluateWorkflowCondition.

`operator`

Safe comparison operation; exists/truthy/falsy forbid an operand, others require value.

`value`

Comparison operand; required except for exists/truthy/falsy, which forbid this field.

Example

See the owning declaration and linked feature guide for usage; no standalone example is documented in source.

[INTERFACE] `WorkflowRetryDefinition`

Host retry settings validated as bounded counts and millisecond delays.

Imports: @alneas/eaos-core, @alneas/eaos-core/workflow-definition.

Signature

interface WorkflowRetryDefinition {
    maxAttempts: number;
    backoffMs?: number;
    maxBackoffMs?: number;
    jitter?: boolean;
}

Parameters

Name	Type	Required	Description
`maxAttempts`	`number`	Yes	Maximum intended attempt count; delay calculators validate it but do not themselves stop retries.
`backoffMs`	`number`	No	Optional base retry delay in milliseconds, validated from 0 to 300000.
`maxBackoffMs`	`number`	No	Optional maximum retry delay in milliseconds, validated from 0 to 3600000.
`jitter`	`boolean`	No	Optional host retry-jitter selection; definition validation does not schedule retries.

Returns

Type declaration; no runtime value.

Public members

`maxAttempts`

Maximum intended attempt count; delay calculators validate it but do not themselves stop retries.

`backoffMs`

Optional base retry delay in milliseconds, validated from 0 to 300000.

`maxBackoffMs`

Optional maximum retry delay in milliseconds, validated from 0 to 3600000.

`jitter`

Optional host retry-jitter selection; definition validation does not schedule retries.

Example

See the owning declaration and linked feature guide for usage; no standalone example is documented in source.

[INTERFACE] `WorkflowSubflowDefinition`

Referenced workflow/version with optional state mapping paths.

Imports: @alneas/eaos-core, @alneas/eaos-core/workflow-definition.

Signature

interface WorkflowSubflowDefinition {
    workflowId: string;
    version: string;
    inputPath?: string;
    outputKey?: string;
}

Parameters

Name	Type	Required	Description
`workflowId`	`string`	Yes	Workflow definition identity used to correlate execution and effects.
`version`	`string`	Yes	Referenced workflow release version, up to 64 nonblank characters.
`inputPath`	`string`	No	Optional dotted input-state path used by a host subflow compiler.
`outputKey`	`string`	No	Optional output-state key used by a host subflow compiler.

Returns

Type declaration; no runtime value.

Public members

`workflowId`

Workflow definition identity used to correlate execution and effects.

`version`

Referenced workflow release version, up to 64 nonblank characters.

`inputPath`

Optional dotted input-state path used by a host subflow compiler.

`outputKey`

Optional output-state key used by a host subflow compiler.

Example

See the owning declaration and linked feature guide for usage; no standalone example is documented in source.

[INTERFACE] `WorkflowToolScopeDefinition`

Declared agent tool mode and explicit allowed tool names.

Imports: @alneas/eaos-core, @alneas/eaos-core/workflow-definition.

Signature

interface WorkflowToolScopeDefinition {
    mode: 'read' | 'preview' | 'action';
    allowedToolNames: readonly string[];
}

Parameters

Name	Type	Required	Description
`mode`	`'read' \| 'preview' \| 'action'`	Yes	Selected operation/storage/execution variant; the owning discriminated union determines applicable fields.
`allowedToolNames`	`readonly string[]`	Yes	Explicit tool-name allowlist to enforce at the host execution boundary.

Returns

Type declaration; no runtime value.

Public members

`mode`

Selected operation/storage/execution variant; the owning discriminated union determines applicable fields.

`allowedToolNames`

Explicit tool-name allowlist to enforce at the host execution boundary.

Example

See the owning declaration and linked feature guide for usage; no standalone example is documented in source.

@alneas/eaos-core API

@alneas/eaos-core API

Public entrypoints

[FUNCTION] addDecimalValues

Signature

Parameters

Returns

Errors and rejections

Example

[CONSTANT] AGENT_RUNTIME_POLICY_VERSION

Signature

Parameters

Returns

See also

Example

[INTERFACE] AgentCapabilitiesConfig

Signature

Parameters

Returns

See also

Public members

providedAgents

skills

webMcpTools

gatekeeperPolicies

Example

[INTERFACE] AgentExecutionContext

Signature

Parameters

Returns

See also

Public members

tenantId

userId

sessionId

traceId

userRoles

metadata

Example

[INTERFACE] AgentInstinct

Signature

Parameters

Returns

See also

Public members

id

tenantId

domain

pattern

heuristic

confidence

successCount

failureCount

embedding

createdAt

updatedAt

Example

[TYPE] AgentJobKind

Signature

Parameters

Returns

See also

Example

[INTERFACE] AgentJobRecord

Signature

Parameters

Returns

Type parameters

See also

Public members

jobId

tenantId

kind

status

request

requestHash

workflowInstanceId

correlationId

idempotencyKey

attempt

[FUNCTION] `addDecimalValues`

[CONSTANT] `AGENT_RUNTIME_POLICY_VERSION`

[INTERFACE] `AgentCapabilitiesConfig`

`providedAgents`

`skills`

`webMcpTools`

`gatekeeperPolicies`

[INTERFACE] `AgentExecutionContext`

`tenantId`

`userId`

`sessionId`

`traceId`

`userRoles`

`metadata`

[INTERFACE] `AgentInstinct`

`id`

`tenantId`

`domain`

`pattern`

`heuristic`

`confidence`

`successCount`

`failureCount`

`embedding`

`createdAt`

`updatedAt`

[TYPE] `AgentJobKind`

[INTERFACE] `AgentJobRecord`

`jobId`

`tenantId`

`kind`

`status`

`request`

`requestHash`

`workflowInstanceId`

`correlationId`

`idempotencyKey`

`attempt`

`maxAttempts`

`availableAt`

`leaseUntil`

`leaseToken`

`result`

`error`

`failureCode`

`createdAt`

`updatedAt`

[TYPE] `AgentJobStatus`

[INTERFACE] `AgentNode`

`id`

`orgId`

`parentId`

`name`

`role`

`tierLevel`

`allowedSensitivityLevel`

`dailyBudgetCapUsd`

`currentDailySpendUsd`

`capabilities`

`status`

`createdAt`

`updatedAt`

[CLASS] `AgentRuntime`

`registerPreToolHook`

`registerPostToolHook`

`registerSessionStartHook`

`registerStopHook`

`onSessionStart`

`executeTool`

`executeTool.success`

`executeTool.result`

`executeTool.error`

`executeTool.status`

`executeTool.riskLevel`

`onStop`

[INTERFACE] `AgentRuntimeResourcePolicy`

`placement`

`maxConcurrent`