@alneas/eaos-server 0.0.0-stage → 0.2.0

package/dist/execution/index.d.ts

@@ -0,0 +1,342 @@
+import { AIChatMessage, AIChatAdapter } from '@alneas/appkit-core/ai/ai-chat';
+import { ActionToolBinding, ActionRegistry, ActionToolCall, ActionToolObject, ActionToolDescriptor } from '@alneas/appkit-core/ai/action';
+import { AIModelRegistry, AIGuard, AIBudgetGate, AIObservabilitySink, AIUsage, AIExecutionContext } from '@alneas/eaos-core';
+import * as hono_types from 'hono/types';
+import { Context, Hono } from 'hono';
+import * as _alneas_appkit_core_ai from '@alneas/appkit-core/ai';
+
+/** Host-registered Action binding and explicit automatic-execution policy.
+ * @see createToolAgent
+ */
+interface AgentTool {
+    /** Existing Appkit Action/command binding; registration and input/output schemas remain Appkit-owned. */
+    binding: ActionToolBinding;
+    /** Only host-verified read-only actions may run automatically; handoffs remain unexecuted. */
+    mode: 'read' | 'handoff';
+}
+/** Current host policies and limits for a single-flight Appkit execution session.
+ * @see createToolAgent
+ */
+interface ToolAgentOptions extends Omit<ChatClientOptions, 'tools'> {
+    /**
+     * Resolve the current host registry and explicit tool execution policy.
+     * @param principal - Copied verified tenant/user identity.
+     * @returns Existing Action registry and at most 100 read/handoff bindings.
+     * @throws Rejects missing host session or registry resolution failures.
+     * @example
+     * ```typescript
+     * import type { ToolAgentOptions } from '@alneas/eaos-server/execution/tool-agent';
+     * export function agentSession(resolve: ToolAgentOptions['session']) { return resolve; }
+     * ```
+     */
+    session(principal: ExecutionPrincipal): Promise<{
+        /** Existing host-owned Appkit Action registry for this authorized session. */
+        registry: ActionRegistry;
+        /** Explicit read/handoff policy for every disclosed binding. */
+        tools: readonly AgentTool[];
+    }>;
+    /**
+     * Check current permission to disclose a tool descriptor or result to the model.
+     * @param principal - Copied verified actor.
+     * @param name - Host-registered tool name.
+     * @returns Exactly true permits disclosure; other results deny it.
+     * @throws Host policy errors propagate into the execution outcome.
+     * @example
+     * ```typescript
+     * import type { ToolAgentOptions } from '@alneas/eaos-server/execution/tool-agent';
+     * export function disclosurePolicy(policy: ToolAgentOptions['disclose']) { return policy; }
+     * ```
+     */
+    disclose(principal: ExecutionPrincipal, name: string): Promise<boolean>;
+    /**
+     * Check exact resource/input permission before execution and before result disclosure.
+     * @param principal - Copied verified actor; callback mutation cannot change the trusted identity.
+     * @param call - Untrusted model request with correlated ID, name and arguments.
+     * @returns Exactly true admits the call; it does not approve a handoff for execution.
+     * @throws Host policy errors propagate into the execution outcome.
+     * @example
+     * ```typescript
+     * import type { ToolAgentOptions } from '@alneas/eaos-server/execution/tool-agent';
+     * export function callPolicy(policy: ToolAgentOptions['authorizeCall']) { return policy; }
+     * ```
+     */
+    authorizeCall(principal: ExecutionPrincipal, call: ActionToolCall): Promise<boolean>;
+    /** Maximum model rounds; default 6, allowed integers 1–20. */
+    maxRounds?: number;
+    /** Maximum automatic Action calls per run; default 10, allowed integers 1–100. */
+    maxCalls?: number;
+}
+/** Final in-memory conversational outcome, separate from Appkit execution status.
+ * @see createToolAgent
+ */
+interface ToolAgentResult {
+    /** Completed chat, unexecuted handoff, bounded stop, or an Action validation/execution failure. */
+    status: 'completed' | 'handoff' | 'limited' | 'tool-error';
+    /** Detached correlated chat history, including only authorized projected tool results. */
+    messages: AIChatMessage[];
+    /** Unexecuted requests; the host must validate them through its existing Action/Proposal review path. */
+    pending: ActionToolCall[];
+    /** Number of attempted automatic Action calls, including a returned Action failure. */
+    callsExecuted: number;
+}
+/**
+ * Orchestrate bounded model rounds through existing Appkit Action/Execution and scoped EAOS chat.
+ * @param options - Current session/disclosure/call policies, Appkit adapter and chat/round/call limits.
+ * @returns Single-flight run, cancel, close and summary subscription methods backed by Appkit ExecutionSession.
+ * @throws Invalid policies or round/call limits reject construction. Concurrent/closed runs reject through
+ * Appkit; asynchronous authorization/provider failures become failed execution outcomes. Cancellation is
+ * cooperative and does not roll back previously completed Action effects.
+ * @remarks Only explicitly host-verified read tools execute automatically. A batch containing any handoff
+ * returns all its calls without executing them. No durable command engine, approval grant or transaction
+ * is created; retained tool-call/result history and descriptors are reauthorized at the exact adapter
+ * boundary after chat governance, including caller-supplied history and guard substitutions. Approved writes belong to the host's existing proposal/approval and owning command service.
+ * @example
+ * ```typescript
+ * import { createToolAgent, type ToolAgentOptions } from '@alneas/eaos-server/execution/tool-agent';
+ * export function connectAgent(options: ToolAgentOptions) { return createToolAgent(options); }
+ * ```
+ */
+declare function createToolAgent(options: ToolAgentOptions): {
+    /**
+     * Request cooperative cancellation of the current Appkit execution.
+     * @returns No value; Appkit marks active work cancelling without rolling back completed effects.
+     * @example
+     * ```typescript
+     * import { createToolAgent } from '@alneas/eaos-server/execution/tool-agent';
+     * export function cancel(agent: ReturnType<typeof createToolAgent>) { return agent.cancel(); }
+     * ```
+     */
+    cancel: () => void;
+    /**
+     * Read Appkit's summary-only in-memory execution history.
+     * @returns Appkit execution summaries; raw model inputs/results are not stored in these summaries.
+     * @example
+     * ```typescript
+     * import { createToolAgent } from '@alneas/eaos-server/execution/tool-agent';
+     * export function snapshot(agent: ReturnType<typeof createToolAgent>) { return agent.getSnapshot(); }
+     * ```
+     */
+    getSnapshot: () => readonly _alneas_appkit_core_ai.ExecutionRecord[];
+    /**
+     * Subscribe to Appkit execution summary changes.
+     * @param listener - Callback notified when execution state changes; do not expose raw secrets in UI callbacks.
+     * @returns Unsubscribe function owned by the subscribing host.
+     * @example
+     * ```typescript
+     * import { createToolAgent } from '@alneas/eaos-server/execution/tool-agent';
+     * export function observe(agent: ReturnType<typeof createToolAgent>, listener: () => void) { return agent.subscribe(listener); }
+     * ```
+     */
+    subscribe: (listener: () => void) => () => void;
+    /**
+     * Close the Appkit session and request cooperative cancellation.
+     * @returns No value; the session no longer admits new runs.
+     * @example
+     * ```typescript
+     * import { createToolAgent } from '@alneas/eaos-server/execution/tool-agent';
+     * export function close(agent: ReturnType<typeof createToolAgent>) { agent.close(); }
+     * ```
+     */
+    close: () => void;
+    /**
+     * Run a single authorized model/Action conversation.
+     * @param principal - Verified current tenant/user identity, copied before host callbacks.
+     * @param input - Detached initial messages and optional cooperative cancellation signal.
+     * @returns Appkit execution outcome containing a ToolAgentResult on success; failed/cancelled outcomes omit it.
+     * @throws Appkit rejects concurrent or closed session admission; run failures otherwise become outcomes.
+     * @example
+     * ```typescript
+     * import { createToolAgent } from '@alneas/eaos-server/execution/tool-agent';
+     * export function run(agent: ReturnType<typeof createToolAgent>, ...args: Parameters<typeof agent.run>) { return agent.run(...args); }
+     * ```
+     */
+    run(principal: ExecutionPrincipal, input: {
+        messages: readonly AIChatMessage[];
+        signal?: AbortSignal;
+    }): Promise<_alneas_appkit_core_ai.ExecutionOutcome<ToolAgentResult>>;
+};
+
+/**
+ * Authenticated host identity supplied to {@link createPluginExecutionRouter}.
+ */
+interface ExecutionIdentity {
+    /** Nonblank verified tenant ID. */
+    tenantId: string;
+    /** Nonblank verified user ID. */
+    userId: string;
+}
+/**
+ * Routes authenticated, authorized JSON requests to a fixed plugin/action operation map.
+ * @param options - resolveIdentity receives Hono context and resolves verified identity/null; authorize receives that identity, pluginId, action, and parsed payload and must check current membership, activation, and resource permissions; operations maps pluginId:action to async handlers receiving identity/payload. maxBodyBytes defaults to 1048576; allowedOrigins permits exact Origin values and defaults to none.
+ * @returns A router serving POST /:pluginId/:action with no-store responses. It returns handler output as JSON or explicit 400/401/403/404/413/415 failures; callback/transport/serialization failures become 503.
+ * @throws Synchronously for a nonpositive or unsafe-integer body limit.
+ * @remarks The operation map is shallow-copied at creation. Plugin IDs must be lowercase kebab-case; actions allow letters/digits/underscore/hyphen. Origin is checked only when present and is not authentication. Body readers are released and oversized streams cancelled. No transaction, idempotency, cancellation, or retry is supplied; operation side effects may precede a 503 response.
+ * @example
+ * ```typescript
+ * import { createPluginExecutionRouter } from "@alneas/eaos-server/execution";
+ * export function executionRouter(options: Parameters<typeof createPluginExecutionRouter>[0]) {
+ *   // Host adapters authenticate, authorize, validate payloads, and persist operation results.
+ *   return createPluginExecutionRouter(options);
+ * }
+ * ```
+ */
+declare function createPluginExecutionRouter(options: {
+    /**
+     * Authenticates the Hono request and resolves nonblank verified tenant/user IDs or null; callback failure becomes a 503 response.
+     */
+    resolveIdentity: (context: Context) => Promise<ExecutionIdentity | null>;
+    /** Must check current tenant membership, plugin activation and resource permissions. */
+    authorize: (identity: ExecutionIdentity, pluginId: string, action: string, payload: unknown) => Promise<boolean>;
+    /**
+     * Fixed pluginId:action handlers shallow-copied at creation; each receives admitted identity and parsed JSON and resolves JSON-serializable output.
+     */
+    operations: Record<string, (identity: ExecutionIdentity, payload: unknown) => Promise<unknown>>;
+    /**
+     * Positive safe-integer request body limit in bytes, enforced while reading; defaults to 1048576.
+     */
+    maxBodyBytes?: number;
+    /**
+     * Optional exact Origin allowlist; any present Origin is denied unless included, while an absent Origin skips this check.
+     */
+    allowedOrigins?: string[];
+}): Hono<hono_types.BlankEnv, hono_types.BlankSchema, "/">;
+/** Verified generic execution identity; policy checks remain host-owned.
+ * @see createChatClient
+ */
+type ExecutionPrincipal = ExecutionIdentity;
+/** Current admission policy used by model and action orchestration.
+ * @see createChatClient
+ */
+interface ExecutionPolicy {
+    /**
+     * Check current membership, activation and operation permission.
+     * @param principal - Trusted tenant/user identity copied before calling the host.
+     * @param operation - Host operation identity; chat uses model:chat.
+     * @returns Exactly true to admit; any other value denies execution.
+     * @throws Host policy failures propagate to the caller.
+     * @example
+     * ```typescript
+     * import type { ExecutionPolicy } from '@alneas/eaos-server/execution';
+     * export function currentPolicy(policy: ExecutionPolicy) { return policy; }
+     * ```
+     * @see createChatClient
+     */
+    authorize(principal: ExecutionPrincipal, operation: string): Promise<boolean>;
+}
+
+/** Host-injected model guards, usage budgets and telemetry.
+ * @see createChatClient
+ */
+interface ChatGovernanceOptions {
+    /** Optional pre-input and post-output checks; replacement messages remain host-owned. */
+    guard?: AIGuard;
+    /** Optional request admission and once-per-started-attempt accounting; accounting failures propagate. */
+    budget?: AIBudgetGate;
+    /** Awaited started/event/completed telemetry within the deadline; sink errors are ignored. */
+    observability?: AIObservabilitySink;
+    /** Telemetry operation label; authorization always checks model:chat. */
+    operation?: string;
+    /** Host-selected registry model ID; without a registry this is metadata, not provider selection. */
+    model?: string;
+    /** Optional host session identity recorded in governance context. */
+    sessionId?: string;
+}
+/** Host-configured adapter, current admission and bounded chat policy.
+ * @see createChatClient
+ */
+interface ChatClientOptions extends ExecutionPolicy {
+    /** Existing Appkit transport configured with the host endpoint, model and credentials. */
+    adapter: AIChatAdapter;
+    /** Host-owned provider parameters cloned at creation; model/messages/tools/stream keys are reserved and rejected. */
+    parameters?: ActionToolObject;
+    /**
+     * Resolve descriptors only when the caller explicitly requests tools: catalog.
+     * @param principal - Copied verified actor whose current disclosure permission the host must check.
+     * @returns At most 100 unique descriptors; omission advertises no tools.
+     * @throws Host resolution failures reject completion before the provider starts.
+     * @example
+     * ```typescript
+     * import type { ChatClientOptions } from '@alneas/eaos-server/execution/chat';
+     * export function disclosedTools(resolve: NonNullable<ChatClientOptions['tools']>) { return resolve; }
+     * ```
+     */
+    tools?(principal: ExecutionPrincipal): Promise<readonly ActionToolDescriptor[]>;
+    /** Positive integer deadline in milliseconds; default 30000, maximum 3600000. */
+    timeoutMs?: number;
+    /** Serialized request character ceiling; default 200000, maximum 7000000. */
+    maxInputChars?: number;
+    /** Serialized event and final assistant-message character ceiling; default 100000, maximum 10000000. */
+    maxOutputChars?: number;
+    /** Maximum stream event count; default 10000, maximum 100000. */
+    maxEvents?: number;
+    /** Host-approved route registry; requests cannot select a model or bypass sensitivity limits. */
+    modelRegistry?: AIModelRegistry;
+    /** Required with modelRegistry: host-approved logical model to configured adapter bindings, snapshotted at creation. */
+    modelAdapters?: Readonly<Record<string, AIChatAdapter>>;
+    /** Optional host guards, budgets and telemetry; final current authorization follows their completion. */
+    governance?: ChatGovernanceOptions;
+}
+/** Completed assistant message and optional host-governance metadata.
+ * @see createChatClient
+ */
+interface ChatCompletion {
+    /** Detached assistant response; tool-call parts are unexecuted requests. */
+    message: AIChatMessage;
+    /** Successful provider finish reason; truncated or inconsistent streams reject. */
+    finishReason: 'stop' | 'tool-calls';
+    /** Unique request trace identity generated before governance callbacks. */
+    traceId?: string;
+    /** Recognized nonnegative adapter metadata; undefined means unknown, including Appkit OpenAI SSE without usage events. */
+    usage?: AIUsage;
+    /** Sensitivity label supplied by the input guard. */
+    sensitivityLevel?: AIExecutionContext['sensitivityLevel'];
+}
+/**
+ * Complete scoped chat through the existing Appkit adapter with live admission and host governance.
+ * @param options - Trusted adapter, current authorization, optional routes/governance and bounded limits.
+ * @returns A client whose complete method returns detached, finally authorized assistant data.
+ * @throws Rejects invalid limits or missing adapter/policy during construction. Completion rejects
+ * invalid histories/catalogs, denied or revoked admission, guard/budget/route denial, provider failures,
+ * incomplete streams, exceeded limits, cancellation, deadline expiry and host accounting failure. Telemetry errors are ignored.
+ * @remarks Every completion authorizes model:chat before disclosure, between events and after awaited
+ * output guard, usage recording and completion telemetry. This client never executes model tool calls.
+ * The host must configure real endpoint credentials in the Appkit adapter. Abort is cooperative for a
+ * custom transport; the request promise remains bounded even if its iterator ignores cancellation.
+ * With modelRegistry, provide modelAdapters mapping each approved logical model to its host-configured
+ * Appkit adapter; generic adapter IDs alone do not select or prove the provider model. Binding entries
+ * and stream methods are snapshotted at creation. Reserved transport parameters are rejected in 0.2.
+ * Accounting runs once after each started adapter attempt, including output blocks, revocation and provider
+ * failure. Unknown usage is passed as undefined, never zero. Appkit's OpenAI SSE adapter currently emits
+ * no usage metadata event even for provider include_usage chunks; hosts must reconcile measured usage
+ * through their existing accounting port using trace/session context. Accounting callback errors reject
+ * completion in 0.2; a stalled callback remains bounded by the request deadline.
+ * @example
+ * ```typescript
+ * import { createChatClient, type ChatClientOptions } from '@alneas/eaos-server/execution/chat';
+ * export function connectChat(options: ChatClientOptions) { return createChatClient(options); }
+ * ```
+ */
+declare function createChatClient(options: ChatClientOptions): {
+    /**
+     * Request one bounded completion for the current actor.
+     * @param principal - Verified nonblank tenant/user identity; copied before invoking host callbacks.
+     * @param input - One to 1000 messages, optional cancellation, and explicit none/catalog tool disclosure.
+     * @returns Assistant data only after final live authorization; tools remain unexecuted requests.
+     * @throws Rejects invalid requests, governance/provider failure, revocation, limits or cancellation.
+     * @example
+     * ```typescript
+     * import { createChatClient } from '@alneas/eaos-server/execution/chat';
+     * export function complete(client: ReturnType<typeof createChatClient>, ...args: Parameters<typeof client.complete>) {
+     *   return client.complete(...args);
+     * }
+     * ```
+     */
+    complete(principal: ExecutionPrincipal, input: {
+        messages: readonly AIChatMessage[];
+        signal?: AbortSignal;
+        tools?: "none" | "catalog";
+    }): Promise<ChatCompletion>;
+};
+
+export { createChatClient, createPluginExecutionRouter, createToolAgent };
+export type { AgentTool, ChatClientOptions, ChatCompletion, ChatGovernanceOptions, ExecutionIdentity, ExecutionPolicy, ExecutionPrincipal, ToolAgentOptions, ToolAgentResult };

package/dist/execution/index.js

@@ -0,0 +1,66 @@
+import {
+  createToolAgent
+} from "../chunk-4BARRLJR.js";
+import {
+  createChatClient
+} from "../chunk-YMHVRBUU.js";
+
+// src/execution/index.ts
+import { Hono } from "hono";
+function createPluginExecutionRouter(options) {
+  const router = new Hono(), operations = { ...options.operations }, maxBytes = options.maxBodyBytes ?? 1048576;
+  if (!Number.isSafeInteger(maxBytes) || maxBytes < 1) throw new Error("Invalid request limit");
+  router.post("/:pluginId/:action", async (c) => {
+    c.header("Cache-Control", "no-store");
+    try {
+      if (c.req.header("Content-Type")?.split(";")[0].trim().toLowerCase() !== "application/json") return c.json({ error: "JSON required" }, 415);
+      const origin = c.req.header("Origin");
+      if (origin && !options.allowedOrigins?.includes(origin)) return c.json({ error: "Origin denied" }, 403);
+      const identity = await options.resolveIdentity(c);
+      if (!identity?.tenantId?.trim() || !identity.userId?.trim()) return c.json({ error: "Authentication required" }, 401);
+      const { pluginId, action } = c.req.param();
+      if (!/^[a-z0-9]+(?:-[a-z0-9]+)*$/.test(pluginId) || !/^[a-zA-Z0-9_-]+$/.test(action) || !Object.hasOwn(operations, `${pluginId}:${action}`)) return c.json({ error: "Unknown operation" }, 404);
+      const reader = c.req.raw.body?.getReader();
+      const chunks = [];
+      let size = 0;
+      if (reader) try {
+        while (true) {
+          const { done, value } = await reader.read();
+          if (done) break;
+          size += value.length;
+          if (size > maxBytes) {
+            await reader.cancel();
+            return c.json({ error: "Request too large" }, 413);
+          }
+          ;
+          chunks.push(value);
+        }
+      } finally {
+        reader.releaseLock();
+      }
+      const bytes = new Uint8Array(size);
+      let offset = 0;
+      for (const chunk of chunks) {
+        bytes.set(chunk, offset);
+        offset += chunk.length;
+      }
+      let payload;
+      try {
+        payload = JSON.parse(new TextDecoder().decode(bytes));
+      } catch {
+        return c.json({ error: "Invalid JSON" }, 400);
+      }
+      if (!await options.authorize(identity, pluginId, action, payload)) return c.json({ error: "Execution denied" }, 403);
+      return c.json(await operations[`${pluginId}:${action}`](identity, payload));
+    } catch {
+      return c.json({ error: "Execution unavailable" }, 503);
+    }
+  });
+  return router;
+}
+export {
+  createChatClient,
+  createPluginExecutionRouter,
+  createToolAgent
+};
+//# sourceMappingURL=index.js.map

package/dist/execution/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/execution/index.ts"],"sourcesContent":["import { Hono, type Context } from 'hono'\n/**\n * Authenticated host identity supplied to {@link createPluginExecutionRouter}.\n */\nexport interface ExecutionIdentity {\n /** Nonblank verified tenant ID. */\n tenantId: string\n /** Nonblank verified user ID. */\n userId: string\n}\n/**\n * Routes authenticated, authorized JSON requests to a fixed plugin/action operation map.\n * @param options - resolveIdentity receives Hono context and resolves verified identity/null; authorize receives that identity, pluginId, action, and parsed payload and must check current membership, activation, and resource permissions; operations maps pluginId:action to async handlers receiving identity/payload. maxBodyBytes defaults to 1048576; allowedOrigins permits exact Origin values and defaults to none.\n * @returns A router serving POST /:pluginId/:action with no-store responses. It returns handler output as JSON or explicit 400/401/403/404/413/415 failures; callback/transport/serialization failures become 503.\n * @throws Synchronously for a nonpositive or unsafe-integer body limit.\n * @remarks The operation map is shallow-copied at creation. Plugin IDs must be lowercase kebab-case; actions allow letters/digits/underscore/hyphen. Origin is checked only when present and is not authentication. Body readers are released and oversized streams cancelled. No transaction, idempotency, cancellation, or retry is supplied; operation side effects may precede a 503 response.\n * @example\n * ```typescript\n * import { createPluginExecutionRouter } from \"@alneas/eaos-server/execution\";\n * export function executionRouter(options: Parameters<typeof createPluginExecutionRouter>[0]) {\n *   // Host adapters authenticate, authorize, validate payloads, and persist operation results.\n *   return createPluginExecutionRouter(options);\n * }\n * ```\n */\nexport function createPluginExecutionRouter(options: {\n  /**\n   * Authenticates the Hono request and resolves nonblank verified tenant/user IDs or null; callback failure becomes a 503 response.\n   */\n  resolveIdentity: (context: Context) => Promise<ExecutionIdentity | null>\n  /** Must check current tenant membership, plugin activation and resource permissions. */\n  authorize: (identity: ExecutionIdentity, pluginId: string, action: string, payload: unknown) => Promise<boolean>\n  /**\n   * Fixed pluginId:action handlers shallow-copied at creation; each receives admitted identity and parsed JSON and resolves JSON-serializable output.\n   */\n  operations: Record<string, (identity: ExecutionIdentity, payload: unknown) => Promise<unknown>>\n  /**\n   * Positive safe-integer request body limit in bytes, enforced while reading; defaults to 1048576.\n   */\n  maxBodyBytes?: number\n  /**\n   * Optional exact Origin allowlist; any present Origin is denied unless included, while an absent Origin skips this check.\n   */\n  allowedOrigins?: string[]\n}) {\n  const router = new Hono(), operations = { ...options.operations }, maxBytes = options.maxBodyBytes ?? 1_048_576\n  if (!Number.isSafeInteger(maxBytes) || maxBytes < 1) throw new Error('Invalid request limit')\n  router.post('/:pluginId/:action', async c => {\n    c.header('Cache-Control', 'no-store')\n    try {\n      if (c.req.header('Content-Type')?.split(';')[0].trim().toLowerCase() !== 'application/json') return c.json({ error: 'JSON required' }, 415)\n      const origin = c.req.header('Origin')\n      if (origin && !options.allowedOrigins?.includes(origin)) return c.json({ error: 'Origin denied' }, 403)\n      const identity = await options.resolveIdentity(c)\n      if (!identity?.tenantId?.trim() || !identity.userId?.trim()) return c.json({ error: 'Authentication required' }, 401)\n      const { pluginId, action } = c.req.param()\n      if (!/^[a-z0-9]+(?:-[a-z0-9]+)*$/.test(pluginId) || !/^[a-zA-Z0-9_-]+$/.test(action) || !Object.hasOwn(operations, `${pluginId}:${action}`)) return c.json({ error: 'Unknown operation' }, 404)\n      const reader = c.req.raw.body?.getReader(); const chunks: Uint8Array[] = []; let size = 0\n      if (reader) try {\n        while (true) { const { done, value } = await reader.read(); if (done) break; size += value.length; if (size > maxBytes) { await reader.cancel(); return c.json({ error: 'Request too large' }, 413) }; chunks.push(value) }\n      } finally { reader.releaseLock() }\n      const bytes = new Uint8Array(size); let offset = 0\n      for (const chunk of chunks) { bytes.set(chunk, offset); offset += chunk.length }\n      let payload: unknown\n      try { payload = JSON.parse(new TextDecoder().decode(bytes)) } catch { return c.json({ error: 'Invalid JSON' }, 400) }\n      if (!await options.authorize(identity, pluginId, action, payload)) return c.json({ error: 'Execution denied' }, 403)\n      return c.json(await operations[`${pluginId}:${action}`](identity, payload))\n    } catch { return c.json({ error: 'Execution unavailable' }, 503) }\n  })\n  return router\n}\n\n/** Verified generic execution identity; policy checks remain host-owned.\n * @see createChatClient\n */\nexport type ExecutionPrincipal = ExecutionIdentity\n/** Current admission policy used by model and action orchestration.\n * @see createChatClient\n */\nexport interface ExecutionPolicy {\n /**\n  * Check current membership, activation and operation permission.\n  * @param principal - Trusted tenant/user identity copied before calling the host.\n  * @param operation - Host operation identity; chat uses model:chat.\n  * @returns Exactly true to admit; any other value denies execution.\n  * @throws Host policy failures propagate to the caller.\n  * @example\n  * ```typescript\n  * import type { ExecutionPolicy } from '@alneas/eaos-server/execution';\n  * export function currentPolicy(policy: ExecutionPolicy) { return policy; }\n  * ```\n  * @see createChatClient\n  */\n authorize(principal: ExecutionPrincipal, operation: string): Promise<boolean>\n}\nexport {createChatClient, type ChatGovernanceOptions, type ChatClientOptions, type ChatCompletion} from './chat'\nexport {createToolAgent, type AgentTool, type ToolAgentOptions, type ToolAgentResult} from './tool-agent'\n"],"mappings":";;;;;;;;AAAA,SAAS,YAA0B;AAyB5B,SAAS,4BAA4B,SAmBzC;AACD,QAAM,SAAS,IAAI,KAAK,GAAG,aAAa,EAAE,GAAG,QAAQ,WAAW,GAAG,WAAW,QAAQ,gBAAgB;AACtG,MAAI,CAAC,OAAO,cAAc,QAAQ,KAAK,WAAW,EAAG,OAAM,IAAI,MAAM,uBAAuB;AAC5F,SAAO,KAAK,sBAAsB,OAAM,MAAK;AAC3C,MAAE,OAAO,iBAAiB,UAAU;AACpC,QAAI;AACF,UAAI,EAAE,IAAI,OAAO,cAAc,GAAG,MAAM,GAAG,EAAE,CAAC,EAAE,KAAK,EAAE,YAAY,MAAM,mBAAoB,QAAO,EAAE,KAAK,EAAE,OAAO,gBAAgB,GAAG,GAAG;AAC1I,YAAM,SAAS,EAAE,IAAI,OAAO,QAAQ;AACpC,UAAI,UAAU,CAAC,QAAQ,gBAAgB,SAAS,MAAM,EAAG,QAAO,EAAE,KAAK,EAAE,OAAO,gBAAgB,GAAG,GAAG;AACtG,YAAM,WAAW,MAAM,QAAQ,gBAAgB,CAAC;AAChD,UAAI,CAAC,UAAU,UAAU,KAAK,KAAK,CAAC,SAAS,QAAQ,KAAK,EAAG,QAAO,EAAE,KAAK,EAAE,OAAO,0BAA0B,GAAG,GAAG;AACpH,YAAM,EAAE,UAAU,OAAO,IAAI,EAAE,IAAI,MAAM;AACzC,UAAI,CAAC,6BAA6B,KAAK,QAAQ,KAAK,CAAC,mBAAmB,KAAK,MAAM,KAAK,CAAC,OAAO,OAAO,YAAY,GAAG,QAAQ,IAAI,MAAM,EAAE,EAAG,QAAO,EAAE,KAAK,EAAE,OAAO,oBAAoB,GAAG,GAAG;AAC9L,YAAM,SAAS,EAAE,IAAI,IAAI,MAAM,UAAU;AAAG,YAAM,SAAuB,CAAC;AAAG,UAAI,OAAO;AACxF,UAAI,OAAQ,KAAI;AACd,eAAO,MAAM;AAAE,gBAAM,EAAE,MAAM,MAAM,IAAI,MAAM,OAAO,KAAK;AAAG,cAAI,KAAM;AAAO,kBAAQ,MAAM;AAAQ,cAAI,OAAO,UAAU;AAAE,kBAAM,OAAO,OAAO;AAAG,mBAAO,EAAE,KAAK,EAAE,OAAO,oBAAoB,GAAG,GAAG;AAAA,UAAE;AAAC;AAAE,iBAAO,KAAK,KAAK;AAAA,QAAE;AAAA,MAC5N,UAAE;AAAU,eAAO,YAAY;AAAA,MAAE;AACjC,YAAM,QAAQ,IAAI,WAAW,IAAI;AAAG,UAAI,SAAS;AACjD,iBAAW,SAAS,QAAQ;AAAE,cAAM,IAAI,OAAO,MAAM;AAAG,kBAAU,MAAM;AAAA,MAAO;AAC/E,UAAI;AACJ,UAAI;AAAE,kBAAU,KAAK,MAAM,IAAI,YAAY,EAAE,OAAO,KAAK,CAAC;AAAA,MAAE,QAAQ;AAAE,eAAO,EAAE,KAAK,EAAE,OAAO,eAAe,GAAG,GAAG;AAAA,MAAE;AACpH,UAAI,CAAC,MAAM,QAAQ,UAAU,UAAU,UAAU,QAAQ,OAAO,EAAG,QAAO,EAAE,KAAK,EAAE,OAAO,mBAAmB,GAAG,GAAG;AACnH,aAAO,EAAE,KAAK,MAAM,WAAW,GAAG,QAAQ,IAAI,MAAM,EAAE,EAAE,UAAU,OAAO,CAAC;AAAA,IAC5E,QAAQ;AAAE,aAAO,EAAE,KAAK,EAAE,OAAO,wBAAwB,GAAG,GAAG;AAAA,IAAE;AAAA,EACnE,CAAC;AACD,SAAO;AACT;","names":[]}

package/dist/execution/tool-agent.d.ts

@@ -0,0 +1,7 @@
+import '@alneas/appkit-core/ai';
+import '@alneas/appkit-core/ai/action';
+import '@alneas/appkit-core/ai/ai-chat';
+export { AgentTool, ToolAgentOptions, ToolAgentResult, createToolAgent } from './index.js';
+import '@alneas/eaos-core';
+import 'hono/types';
+import 'hono';

package/dist/execution/tool-agent.js

@@ -0,0 +1,8 @@
+import {
+  createToolAgent
+} from "../chunk-4BARRLJR.js";
+import "../chunk-YMHVRBUU.js";
+export {
+  createToolAgent
+};
+//# sourceMappingURL=tool-agent.js.map

package/dist/execution/tool-agent.js.map

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

package/dist/extensions/index.d.ts

@@ -0,0 +1,172 @@
+import { Hono, Context, MiddlewareHandler } from 'hono';
+import { PluginManifest } from '@alneas/eaos-core';
+import { PlatformContribution } from '@alneas/eaos-server/platform';
+
+/**
+ * Plugin-manifest route factory supplied by trusted deployment composition.
+ * @see PlatformExtension.
+ */
+type HostRouteFactory = NonNullable<PluginManifest['createRoutes']>;
+/**
+ * Adds host route composition to a trusted platform contribution with explicit tenant scope.
+ * @remarks Never populate this object from request input.
+ * @see validateExtensions for a complete composition example.
+ */
+interface PlatformExtension extends PlatformContribution {
+    /** Plugin-ID factories for every contributed manifest; may not override plugins absent from this contribution. */
+    routeFactories?: Record<string, HostRouteFactory>;
+    /** Optional host API routes with an absolute, wildcard-free prefix, nonblank moduleId, and Hono router. */
+    routes?: Array<{
+        /** Absolute wildcard-free mount prefix; overlapping tenant contributions may not claim the same prefix. */
+        prefix: string;
+        /** Nonblank module identity passed to the host requireModule factory after the extension tenant-scope check. */
+        moduleId: string;
+        /** Trusted Hono child router wrapped with tenant-scope and live host module middleware during extension composition. */
+        router: Hono;
+    }>;
+    /** Optional request context resolver; contributions using it may not overlap tenant scope. Its result/authorization semantics belong to the host. */
+    userContext?: (context: Context) => Promise<unknown>;
+}
+/**
+ * Checks trusted extension shapes, IDs, route factories, and conflicting tenant/user-context contributions.
+ * @param values - Deployment module values to validate; request input must not supply implementations.
+ * @returns A new array containing the original validated objects; no deep clone or sandboxing occurs.
+ * @throws For invalid version/ID/explicit tenant scopes, duplicate extension/plugin IDs, overlapping userContext tenant scopes, invalid routes, or missing/unauthorized route factories.
+ * @remarks Independent plugins can share tenants. This validates composition constraints, not manifest internals or implementation safety.
+ * @example
+ * ```typescript
+ * import { validateExtensions } from "@alneas/eaos-server/extensions";
+ * const extensions = validateExtensions([{ apiVersion: 1, id: "example", tenantIds: ["example"] }]);
+ * console.log(extensions.length); // 1
+ * ```
+ */
+declare function validateExtensions(values: unknown[]): PlatformExtension[];
+/**
+ * Wraps each contributed plugin route factory with an explicit tenant-scope middleware.
+ * @param item - Trusted validated extension; tenantIds is consulted at request time.
+ * @returns A shallow copy with fresh route factory wrappers; each wrapper invokes the original factory with unchanged arguments.
+ * @throws Calling a wrapped factory propagates the original route-factory errors.
+ * @remarks Set trusted tenantId context before handling requests. Out-of-scope or missing tenantId returns 403. This wrapper performs no membership or module authorization.
+ * @example
+ * ```typescript
+ * import { scopeExtensionFactories, validateExtensions } from "@alneas/eaos-server/extensions";
+ * const [extension] = validateExtensions([{ apiVersion: 1, id: "example", tenantIds: ["example"] }]);
+ * const scoped = scopeExtensionFactories(extension);
+ * console.log(scoped.id);
+ * ```
+ */
+declare function scopeExtensionFactories(item: PlatformExtension): PlatformExtension;
+/**
+ * Wraps contributed host routers with tenant-scope checks followed by host module authorization.
+ * @param extension - Trusted validated contribution; omitted routes produce an empty array.
+ * @param requireModule - Called once per route with moduleId during composition; returns middleware enforcing current module permissions.
+ * @returns New prefix/router pairs preserving original route order and mounting original routers beneath their guards.
+ * @throws Propagates module middleware factory or route composition errors; request execution propagates downstream failures.
+ * @remarks Requires a verified tenantId in Hono context. No authentication is installed here.
+ * @example
+ * ```typescript
+ * import { scopeExtensionRoutes, validateExtensions } from "@alneas/eaos-server/extensions";
+ * import { createModuleGuard } from "@alneas/eaos-server/middleware/module-guard";
+ * const [extension] = validateExtensions([{ apiVersion: 1, id: "example", tenantIds: ["example"] }]);
+ * console.log(scopeExtensionRoutes(extension, id => createModuleGuard(id, { isDev: false }))); // []
+ * ```
+ */
+declare function scopeExtensionRoutes(extension: PlatformExtension, requireModule: (moduleId: string) => MiddlewareHandler): Array<{
+    /**
+   * Original host route prefix preserved for subsequent mounting.
+   */
+    prefix: string;
+    /**
+   * Fresh Hono wrapper enforcing tenant scope and host module authorization before forwarding to the original router.
+   */
+    router: Hono;
+}>;
+/**
+ * Mounts tenant-dispatched extension routes, allowing a shared prefix across disjoint tenant scopes.
+ * @param app - Host Hono app mutated with exact-prefix and descendant dispatch routes.
+ * @param extensions - Trusted validated extensions with explicit tenant IDs.
+ * @param requireModule - Host factory producing current module authorization middleware for each route moduleId.
+ * @returns No value; completes after mounting all route groups.
+ * @throws For an overlapping tenant at the same prefix, or propagated route/middleware composition errors.
+ * @remarks Install verified identity/tenant middleware before these routes. Dispatch copies parent context variables into the selected child and forwards server environment; missing tenant scope returns 403. There is no automatic route unmount or per-request persistence.
+ * @example
+ * ```typescript
+ * import { Hono } from "hono";
+ * import { mountExtensionRoutes, type PlatformExtension } from "@alneas/eaos-server/extensions";
+ * import { createModuleGuard } from "@alneas/eaos-server/middleware/module-guard";
+ * export function mount(app: Hono, extensions: PlatformExtension[]) {
+ *   mountExtensionRoutes(app, extensions, id => createModuleGuard(id, { isDev: false }));
+ * }
+ * ```
+ */
+declare function mountExtensionRoutes(app: Hono, extensions: PlatformExtension[], requireModule: (id: string) => MiddlewareHandler): void;
+/** Request-scoped host authorization supplied after verified membership middleware.
+ * @see getPlatformPluginAuthorization for binding lookup and a usage example.
+ */
+interface PlatformPluginAuthorization {
+    /**
+     * Resolves the current verified principal after host authentication/membership checks.
+     * @returns Tenant/user identity, verified roles, and current enabled plugin IDs, or null to deny.
+     * @throws Host authentication or persistence failures propagate to callers.
+     
+     * @example
+     * ```typescript
+     * import type { PlatformPluginAuthorization } from "@alneas/eaos-server/extensions";
+     * export async function readHostPrincipal(authorization: PlatformPluginAuthorization) {
+     *   const principal = await authorization.resolvePrincipal();
+     *   return principal; // Null denies access; never replace it with request-supplied claims.
+     * }
+     * ```
+     */
+    resolvePrincipal(): Promise<{
+        /** Tenant identity established by trusted host authentication/membership resolution; request-supplied headers/body must not define this claim. */
+        tenantId: string;
+        /** Authenticated user identity within the resolved tenant scope. */
+        userId: string;
+        /** Verified host role claims used for downstream authorization; tenant roles must not fabricate platform authority. */
+        roles: string[];
+        /** Current plugin activation identities visible to this verified principal; the host supplies live lifecycle data. */
+        enabledPluginIds: string[];
+    } | null>;
+    /**
+     * Checks live plugin activation for a verified tenant.
+     * @param tenantId - Verified tenant ID.
+     * @param pluginId - Exact installed plugin ID.
+     * @returns True only when the plugin is currently enabled for this tenant.
+     * @throws Host lifecycle/persistence failures propagate to callers.
+     
+     * @example
+     * ```typescript
+     * import type { PlatformPluginAuthorization } from "@alneas/eaos-server/extensions";
+     * export async function checkCurrentPlugin(
+     *   authorization: PlatformPluginAuthorization, verifiedTenantId: string, installedPluginId: string,
+     * ) {
+     *   return await authorization.isPluginEnabled(verifiedTenantId, installedPluginId);
+     * }
+     * ```
+     */
+    isPluginEnabled(tenantId: string, pluginId: string): Promise<boolean>;
+}
+/**
+ * Hono variable/environment key for the host-only {@link PlatformPluginAuthorization} binding.
+ * @see getPlatformPluginAuthorization for access behavior.
+ */
+declare const PLATFORM_PLUGIN_AUTHORIZATION = "eaosPlatformPluginAuthorization";
+/**
+ * Reads a structurally valid host authorization port from Hono context or server environment.
+ * @param context - Hono-like context; get(bindingKey) takes precedence over env[bindingKey] when nonnull. Missing contexts return undefined.
+ * @returns The original port when both required members are functions, or undefined otherwise.
+ * @throws Propagates errors thrown by the context get accessor.
+ * @remarks Hono environment forwarding is internal-only; HTTP headers never supply this binding. Structural validation does not establish trust: only host middleware may install it.
+ * @example
+ * ```typescript
+ * import { Hono } from "hono";
+ * import { getPlatformPluginAuthorization } from "@alneas/eaos-server/extensions";
+ * const app = new Hono();
+ * app.get("/authorization-state", c => c.json({ configured: !!getPlatformPluginAuthorization(c) }));
+ * ```
+ */
+declare function getPlatformPluginAuthorization(context: unknown): PlatformPluginAuthorization | undefined;
+
+export { PLATFORM_PLUGIN_AUTHORIZATION, getPlatformPluginAuthorization, mountExtensionRoutes, scopeExtensionFactories, scopeExtensionRoutes, validateExtensions };
+export type { HostRouteFactory, PlatformExtension, PlatformPluginAuthorization };