@alneas/eaos-server 0.0.0-stage → 0.2.0

package/dist/browser-auth/public-memberships.js

@@ -0,0 +1,7 @@
+import {
+  publicAccountMemberships
+} from "../chunk-FRRRWAHO.js";
+export {
+  publicAccountMemberships
+};
+//# sourceMappingURL=public-memberships.js.map

package/dist/browser-auth/public-memberships.js.map

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

package/dist/cache/index.d.ts

@@ -0,0 +1,181 @@
+import { Context } from 'hono';
+
+/**
+ * Per-fetch storage controls for {@link MemoryCacheManager.getOrSet}.
+ */
+interface CacheOptions {
+    /** Retention in milliseconds; finite and nonnegative. Zero disables storing; omission uses the manager default. */
+    ttlMs?: number;
+    /** Tags attached to a newly stored entry for invalidation; defaults to none. */
+    tags?: string[];
+    /** Fetch even when a cached value exists; successful fetches may still populate the cache. @defaultValue false */
+    bypass?: boolean;
+}
+/**
+ * Verified identity partition used by {@link MemoryCacheManager.forScope}.
+ */
+interface CacheScope {
+    /** Nonblank authenticated tenant ID. */
+    tenantId: string;
+    /** Nonblank trusted plugin ID. */
+    pluginId: string;
+    /** Nonblank authenticated user ID. */
+    userId: string;
+    /** Permission revision included in the key partition; defaults to an empty string. */
+    permissionVersion?: string;
+}
+/**
+ * Stores cloned values in a bounded process-local cache with TTL and tag invalidation.
+ * @remarks Values must support structuredClone. Entries expire lazily on access; no timers, persistent storage, or cross-process invalidation are installed. Capacity eviction removes the oldest inserted entry. Concurrent misses run separate fetchers; only the latest fetch started for a key may populate it, and any invalidation prevents previously started fetches from repopulating entries.
+ * @example
+ * ```typescript
+ * import { MemoryCacheManager } from "@alneas/eaos-server/cache";
+ * const cache = new MemoryCacheManager();
+ * const result = await cache.getOrSet("answer", async () => ({ value: 42 }));
+ * console.log(result.value);
+ * cache.clear();
+ * ```
+ */
+declare class MemoryCacheManager {
+    private readonly values;
+    private readonly tags;
+    private readonly pending;
+    private epoch;
+    private readonly maxEntries;
+    private readonly ttl;
+    /**
+     * Creates an independent cache with validated capacity and default retention.
+     * @param options - maxEntries defaults to 1000 and must be a positive safe integer; defaultTtlMs defaults to 60000 milliseconds and must be finite and nonnegative.
+     * @throws If capacity or default retention is invalid.
+     */
+    constructor(options?: {
+        /**
+         * Maximum retained cache entries; defaults to 1000 and must be a positive safe integer. Capacity eviction removes the oldest inserted entry.
+         */
+        maxEntries?: number;
+        /**
+         * Default retention in milliseconds, finite and nonnegative; defaults to 60000. Zero disables retaining newly fetched/set entries.
+         */
+        defaultTtlMs?: number;
+    });
+    /** Request bypass detector; see {@link isNoCacheRequested} for parameter semantics and example. */
+    isNoCacheRequested: typeof isNoCacheRequested;
+    private remove;
+    private prune;
+    /**
+     * Stores a cloned value, replacing an existing key and invalidating its in-flight fetch token.
+     * @typeParam T - Structured-cloneable value type.
+     * @param key - Exact cache key, without automatic authorization or partitioning.
+     * @param value - Value to clone for storage.
+     * @param ttlMs - Nonnegative finite milliseconds from the current clock; defaults to the manager retention. Zero removes the prior entry without storing.
+     * @param tags - Invalidation tags; duplicates are collapsed and omission uses none.
+     * @returns No value; completes after cloning and inserting or removing the entry.
+     * @throws For invalid TTL or a value that cannot be structured-cloned. A previous entry may already have been removed when cloning fails.
+     * @example
+     * ```typescript
+     * import { MemoryCacheManager } from "@alneas/eaos-server/cache";
+     * const cache = new MemoryCacheManager();
+     * cache.set("answer", { value: 42 }, 1000, ["answers"]);
+     * ```
+     */
+    set<T>(key: string, value: T, ttlMs?: number, tags?: string[]): void;
+    /**
+     * Returns a cloned cached value or fetches and conditionally caches a new value.
+     * @typeParam T - Structured-cloneable value returned by fetcher and this method.
+     * @param key - Exact cache key; use forScope for authenticated partitions.
+     * @param fetcher - Called without arguments on a miss or bypass; resolves a cloneable value. Concurrent misses are not coalesced.
+     * @param options - Retention, tags, and bypass settings; see {@link CacheOptions}.
+     * @returns A separate clone of the cached or fetched value, including when invalidation prevents storage.
+     * @throws Rejects on fetcher failure, invalid TTL used for insertion, or structuredClone failure.
+     * @example
+     * ```typescript
+     * import { MemoryCacheManager } from "@alneas/eaos-server/cache";
+     * const cache = new MemoryCacheManager();
+     * console.log(await cache.getOrSet("answer", async () => 42));
+     * ```
+     */
+    getOrSet<T>(key: string, fetcher: () => Promise<T>, options?: CacheOptions): Promise<T>;
+    /**
+     * Removes entries carrying any requested tag and prevents pending fetches from populating the cache.
+     * @param tags - One exact tag or multiple tags; an empty array removes no stored entries but still invalidates pending writes.
+     * @returns No value; removal completes synchronously.
+     * @example
+     * ```typescript
+     * import { MemoryCacheManager } from "@alneas/eaos-server/cache";
+     * const cache = new MemoryCacheManager();
+     * cache.set("answer", 42, 1000, ["answers"]);
+     * cache.invalidateTags("answers");
+     * ```
+     */
+    invalidateTags(tags: string | string[]): void;
+    /**
+     * Removes entries whose exact keys start with the supplied prefix and invalidates pending writes.
+     * @param prefix - Case-sensitive key prefix; an empty prefix matches every entry.
+     * @returns No value; removal completes synchronously.
+     * @example
+     * ```typescript
+     * import { MemoryCacheManager } from "@alneas/eaos-server/cache";
+     * const cache = new MemoryCacheManager();
+     * cache.invalidatePrefix("reports:");
+     * ```
+     */
+    invalidatePrefix(prefix: string): void;
+    /**
+     * Removes every cached entry, tag index, and pending write token.
+     * @returns No value; clearing completes synchronously without cancelling fetchers already running.
+     * @example
+     * ```typescript
+     * import { MemoryCacheManager } from "@alneas/eaos-server/cache";
+     * const cache = new MemoryCacheManager();
+     * cache.clear();
+     * ```
+     */
+    clear(): void;
+    /**
+     * Prunes expired entries and counts the remaining stored values.
+     * @returns Current number of unexpired entries, excluding pending fetches.
+     * @example
+     * ```typescript
+     * import { MemoryCacheManager } from "@alneas/eaos-server/cache";
+     * const cache = new MemoryCacheManager();
+     * console.log(cache.size()); // 0
+     * ```
+     */
+    size(): number;
+    /**
+    * Creates a tenant/plugin/user partition with authorization before and after asynchronous work.
+    * @param scope - Verified nonblank identity IDs and optional permission revision; see {@link CacheScope}.
+    * @param authorize - Called without arguments on every lookup, including hits, and after fetching and before returning. Any truthy result permits access; errors propagate.
+    * @returns A scoped getOrSet using the same key/fetcher/options semantics as this manager, plus invalidate(), which removes this partition without returning a value or calling authorize.
+    * @throws Synchronously for missing/blank scope IDs. Scoped lookups reject for denied access or propagated authorization/fetch/clone errors.
+    * @remarks Tenant and plugin tags are added to fetched entries. The host must supply trusted identity and live authorization; partitioning does not authenticate callers. Invalidating a scope also prevents other in-flight manager fetches from populating entries.
+    * @example
+    * ```typescript
+    * import { MemoryCacheManager, type CacheScope } from "@alneas/eaos-server/cache";
+    * export function userCache(scope: CacheScope, authorize: () => Promise<boolean>) {
+    *   return new MemoryCacheManager().forScope(scope, authorize);
+    * }
+    * ```
+    */
+    forScope(scope: CacheScope, authorize: () => boolean | Promise<boolean>): {
+        getOrSet: <T>(key: string, fetcher: () => Promise<T>, options?: CacheOptions) => Promise<T>;
+        invalidate: () => void;
+    };
+}
+/**
+ * Detects request directives or query flags asking to bypass cached values.
+ * @param c - Hono request context; reads Cache-Control, Pragma, refresh, and nocache.
+ * @returns True for no-cache, max-age=0 (optionally quoted), or refresh/nocache equal to true or 1; false otherwise. Header directives are case-insensitive; query flag values are case-sensitive.
+ * @example
+ * ```typescript
+ * import { Hono } from "hono";
+ * import { isNoCacheRequested } from "@alneas/eaos-server/cache";
+ * const app = new Hono();
+ * app.get("/cache-policy", c => c.json({ bypass: isNoCacheRequested(c) }));
+ * console.log(await (await app.request("/cache-policy?refresh=1")).json());
+ * ```
+ */
+declare function isNoCacheRequested(c: Pick<Context, 'req'>): boolean;
+
+export { MemoryCacheManager, isNoCacheRequested };
+export type { CacheOptions, CacheScope };

package/dist/cache/index.js

@@ -0,0 +1,197 @@
+// src/cache/index.ts
+var MemoryCacheManager = class {
+  values = /* @__PURE__ */ new Map();
+  tags = /* @__PURE__ */ new Map();
+  pending = /* @__PURE__ */ new Map();
+  epoch = 0;
+  maxEntries;
+  ttl;
+  /**
+   * Creates an independent cache with validated capacity and default retention.
+   * @param options - maxEntries defaults to 1000 and must be a positive safe integer; defaultTtlMs defaults to 60000 milliseconds and must be finite and nonnegative.
+   * @throws If capacity or default retention is invalid.
+   */
+  constructor(options = {}) {
+    this.maxEntries = options.maxEntries ?? 1e3;
+    this.ttl = options.defaultTtlMs ?? 6e4;
+    if (!Number.isSafeInteger(this.maxEntries) || this.maxEntries < 1 || !Number.isFinite(this.ttl) || this.ttl < 0) throw new Error("Invalid cache limits");
+  }
+  /** Request bypass detector; see {@link isNoCacheRequested} for parameter semantics and example. */
+  isNoCacheRequested = isNoCacheRequested;
+  remove(key) {
+    const entry = this.values.get(key);
+    if (entry) for (const tag of entry.tags) {
+      const keys = this.tags.get(tag);
+      keys.delete(key);
+      if (!keys.size) this.tags.delete(tag);
+    }
+    this.values.delete(key);
+  }
+  prune() {
+    const now = Date.now();
+    for (const [key, entry] of this.values) if (entry.expiresAt <= now) this.remove(key);
+  }
+  /**
+   * Stores a cloned value, replacing an existing key and invalidating its in-flight fetch token.
+   * @typeParam T - Structured-cloneable value type.
+   * @param key - Exact cache key, without automatic authorization or partitioning.
+   * @param value - Value to clone for storage.
+   * @param ttlMs - Nonnegative finite milliseconds from the current clock; defaults to the manager retention. Zero removes the prior entry without storing.
+   * @param tags - Invalidation tags; duplicates are collapsed and omission uses none.
+   * @returns No value; completes after cloning and inserting or removing the entry.
+   * @throws For invalid TTL or a value that cannot be structured-cloned. A previous entry may already have been removed when cloning fails.
+   * @example
+   * ```typescript
+   * import { MemoryCacheManager } from "@alneas/eaos-server/cache";
+   * const cache = new MemoryCacheManager();
+   * cache.set("answer", { value: 42 }, 1000, ["answers"]);
+   * ```
+   */
+  set(key, value, ttlMs = this.ttl, tags = []) {
+    if (!Number.isFinite(ttlMs) || ttlMs < 0) throw new Error("Invalid cache TTL");
+    this.pending.delete(key);
+    this.remove(key);
+    this.prune();
+    if (ttlMs === 0) return;
+    const entry = { value: structuredClone(value), expiresAt: Date.now() + ttlMs, tags: new Set(tags) };
+    while (this.values.size >= this.maxEntries) this.remove(this.values.keys().next().value);
+    this.values.set(key, entry);
+    for (const tag of entry.tags) {
+      let keys = this.tags.get(tag);
+      if (!keys) this.tags.set(tag, keys = /* @__PURE__ */ new Set());
+      keys.add(key);
+    }
+  }
+  /**
+   * Returns a cloned cached value or fetches and conditionally caches a new value.
+   * @typeParam T - Structured-cloneable value returned by fetcher and this method.
+   * @param key - Exact cache key; use forScope for authenticated partitions.
+   * @param fetcher - Called without arguments on a miss or bypass; resolves a cloneable value. Concurrent misses are not coalesced.
+   * @param options - Retention, tags, and bypass settings; see {@link CacheOptions}.
+   * @returns A separate clone of the cached or fetched value, including when invalidation prevents storage.
+   * @throws Rejects on fetcher failure, invalid TTL used for insertion, or structuredClone failure.
+   * @example
+   * ```typescript
+   * import { MemoryCacheManager } from "@alneas/eaos-server/cache";
+   * const cache = new MemoryCacheManager();
+   * console.log(await cache.getOrSet("answer", async () => 42));
+   * ```
+   */
+  async getOrSet(key, fetcher, options = {}) {
+    this.prune();
+    const cached = this.values.get(key);
+    if (!options.bypass && cached) return structuredClone(cached.value);
+    const token = /* @__PURE__ */ Symbol(), epoch = this.epoch;
+    this.pending.set(key, token);
+    try {
+      const value = await fetcher();
+      if (epoch === this.epoch && this.pending.get(key) === token) this.set(key, value, options.ttlMs ?? this.ttl, options.tags);
+      return structuredClone(value);
+    } finally {
+      if (this.pending.get(key) === token) this.pending.delete(key);
+    }
+  }
+  /**
+   * Removes entries carrying any requested tag and prevents pending fetches from populating the cache.
+   * @param tags - One exact tag or multiple tags; an empty array removes no stored entries but still invalidates pending writes.
+   * @returns No value; removal completes synchronously.
+   * @example
+   * ```typescript
+   * import { MemoryCacheManager } from "@alneas/eaos-server/cache";
+   * const cache = new MemoryCacheManager();
+   * cache.set("answer", 42, 1000, ["answers"]);
+   * cache.invalidateTags("answers");
+   * ```
+   */
+  invalidateTags(tags) {
+    this.epoch++;
+    for (const tag of typeof tags === "string" ? [tags] : tags) for (const key of [...this.tags.get(tag) ?? []]) this.remove(key);
+  }
+  /**
+   * Removes entries whose exact keys start with the supplied prefix and invalidates pending writes.
+   * @param prefix - Case-sensitive key prefix; an empty prefix matches every entry.
+   * @returns No value; removal completes synchronously.
+   * @example
+   * ```typescript
+   * import { MemoryCacheManager } from "@alneas/eaos-server/cache";
+   * const cache = new MemoryCacheManager();
+   * cache.invalidatePrefix("reports:");
+   * ```
+   */
+  invalidatePrefix(prefix) {
+    this.epoch++;
+    for (const key of this.values.keys()) if (key.startsWith(prefix)) this.remove(key);
+  }
+  /**
+   * Removes every cached entry, tag index, and pending write token.
+   * @returns No value; clearing completes synchronously without cancelling fetchers already running.
+   * @example
+   * ```typescript
+   * import { MemoryCacheManager } from "@alneas/eaos-server/cache";
+   * const cache = new MemoryCacheManager();
+   * cache.clear();
+   * ```
+   */
+  clear() {
+    this.epoch++;
+    this.values.clear();
+    this.tags.clear();
+    this.pending.clear();
+  }
+  /**
+   * Prunes expired entries and counts the remaining stored values.
+   * @returns Current number of unexpired entries, excluding pending fetches.
+   * @example
+   * ```typescript
+   * import { MemoryCacheManager } from "@alneas/eaos-server/cache";
+   * const cache = new MemoryCacheManager();
+   * console.log(cache.size()); // 0
+   * ```
+   */
+  size() {
+    this.prune();
+    return this.values.size;
+  }
+  /**
+  * Creates a tenant/plugin/user partition with authorization before and after asynchronous work.
+  * @param scope - Verified nonblank identity IDs and optional permission revision; see {@link CacheScope}.
+  * @param authorize - Called without arguments on every lookup, including hits, and after fetching and before returning. Any truthy result permits access; errors propagate.
+  * @returns A scoped getOrSet using the same key/fetcher/options semantics as this manager, plus invalidate(), which removes this partition without returning a value or calling authorize.
+  * @throws Synchronously for missing/blank scope IDs. Scoped lookups reject for denied access or propagated authorization/fetch/clone errors.
+  * @remarks Tenant and plugin tags are added to fetched entries. The host must supply trusted identity and live authorization; partitioning does not authenticate callers. Invalidating a scope also prevents other in-flight manager fetches from populating entries.
+  * @example
+  * ```typescript
+  * import { MemoryCacheManager, type CacheScope } from "@alneas/eaos-server/cache";
+  * export function userCache(scope: CacheScope, authorize: () => Promise<boolean>) {
+  *   return new MemoryCacheManager().forScope(scope, authorize);
+  * }
+  * ```
+  */
+  forScope(scope, authorize) {
+    for (const id of [scope.tenantId, scope.pluginId, scope.userId]) if (typeof id !== "string" || !id.trim()) throw new Error("Verified cache scope required");
+    const prefix = JSON.stringify([scope.tenantId, scope.pluginId, scope.userId, scope.permissionVersion ?? ""]) + ":";
+    const tenantTag = `tenant:${scope.tenantId}`, pluginTag = `plugin:${scope.pluginId}`;
+    const allowed = async () => {
+      if (!await authorize()) throw new Error("Cache access denied");
+    };
+    return { getOrSet: async (key, fetcher, options = {}) => {
+      await allowed();
+      const value = await this.getOrSet(prefix + key, async () => {
+        const result = await fetcher();
+        await allowed();
+        return result;
+      }, { ...options, tags: [...options.tags ?? [], tenantTag, pluginTag] });
+      await allowed();
+      return value;
+    }, invalidate: () => this.invalidatePrefix(prefix) };
+  }
+};
+function isNoCacheRequested(c) {
+  const directives = `${c.req.header("cache-control") ?? ""},${c.req.header("pragma") ?? ""}`.toLowerCase().split(",").map((v) => v.trim());
+  return directives.some((v) => v === "no-cache" || /^max-age\s*=\s*"?0"?$/.test(v)) || ["refresh", "nocache"].some((key) => ["true", "1"].includes(c.req.query(key) ?? ""));
+}
+export {
+  MemoryCacheManager,
+  isNoCacheRequested
+};
+//# sourceMappingURL=index.js.map

package/dist/cache/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/cache/index.ts"],"sourcesContent":["import type { Context } from 'hono'\n/**\n * Per-fetch storage controls for {@link MemoryCacheManager.getOrSet}.\n */\nexport interface CacheOptions {\n /** Retention in milliseconds; finite and nonnegative. Zero disables storing; omission uses the manager default. */\n ttlMs?: number\n /** Tags attached to a newly stored entry for invalidation; defaults to none. */\n tags?: string[]\n /** Fetch even when a cached value exists; successful fetches may still populate the cache. @defaultValue false */\n bypass?: boolean\n}\n/**\n * Verified identity partition used by {@link MemoryCacheManager.forScope}.\n */\nexport interface CacheScope {\n /** Nonblank authenticated tenant ID. */\n tenantId: string\n /** Nonblank trusted plugin ID. */\n pluginId: string\n /** Nonblank authenticated user ID. */\n userId: string\n /** Permission revision included in the key partition; defaults to an empty string. */\n permissionVersion?: string\n}\ninterface Entry { value: unknown; expiresAt: number; tags: Set<string> }\n/**\n * Stores cloned values in a bounded process-local cache with TTL and tag invalidation.\n * @remarks Values must support structuredClone. Entries expire lazily on access; no timers, persistent storage, or cross-process invalidation are installed. Capacity eviction removes the oldest inserted entry. Concurrent misses run separate fetchers; only the latest fetch started for a key may populate it, and any invalidation prevents previously started fetches from repopulating entries.\n * @example\n * ```typescript\n * import { MemoryCacheManager } from \"@alneas/eaos-server/cache\";\n * const cache = new MemoryCacheManager();\n * const result = await cache.getOrSet(\"answer\", async () => ({ value: 42 }));\n * console.log(result.value);\n * cache.clear();\n * ```\n */\nexport class MemoryCacheManager {\n private readonly values = new Map<string, Entry>()\n private readonly tags = new Map<string, Set<string>>()\n private readonly pending = new Map<string, symbol>()\n private epoch = 0\n private readonly maxEntries: number\n private readonly ttl: number\n /**\n  * Creates an independent cache with validated capacity and default retention.\n  * @param options - maxEntries defaults to 1000 and must be a positive safe integer; defaultTtlMs defaults to 60000 milliseconds and must be finite and nonnegative.\n  * @throws If capacity or default retention is invalid.\n  */\n constructor(options: { \n  /**\n   * Maximum retained cache entries; defaults to 1000 and must be a positive safe integer. Capacity eviction removes the oldest inserted entry.\n   */\n  maxEntries?: number; \n  /**\n   * Default retention in milliseconds, finite and nonnegative; defaults to 60000. Zero disables retaining newly fetched/set entries.\n   */\n  defaultTtlMs?: number } = {}) {\n  this.maxEntries = options.maxEntries ?? 1000; this.ttl = options.defaultTtlMs ?? 60_000\n  if (!Number.isSafeInteger(this.maxEntries) || this.maxEntries < 1 || !Number.isFinite(this.ttl) || this.ttl < 0) throw new Error('Invalid cache limits')\n }\n /** Request bypass detector; see {@link isNoCacheRequested} for parameter semantics and example. */\n isNoCacheRequested = isNoCacheRequested\n private remove(key: string) {\n  const entry = this.values.get(key)\n  if (entry) for (const tag of entry.tags) { const keys = this.tags.get(tag)!; keys.delete(key); if (!keys.size) this.tags.delete(tag) }\n  this.values.delete(key)\n }\n private prune() { const now = Date.now(); for (const [key, entry] of this.values) if (entry.expiresAt <= now) this.remove(key) }\n /**\n  * Stores a cloned value, replacing an existing key and invalidating its in-flight fetch token.\n  * @typeParam T - Structured-cloneable value type.\n  * @param key - Exact cache key, without automatic authorization or partitioning.\n  * @param value - Value to clone for storage.\n  * @param ttlMs - Nonnegative finite milliseconds from the current clock; defaults to the manager retention. Zero removes the prior entry without storing.\n  * @param tags - Invalidation tags; duplicates are collapsed and omission uses none.\n  * @returns No value; completes after cloning and inserting or removing the entry.\n  * @throws For invalid TTL or a value that cannot be structured-cloned. A previous entry may already have been removed when cloning fails.\n  * @example\n  * ```typescript\n  * import { MemoryCacheManager } from \"@alneas/eaos-server/cache\";\n  * const cache = new MemoryCacheManager();\n  * cache.set(\"answer\", { value: 42 }, 1000, [\"answers\"]);\n  * ```\n  */\n set<T>(key: string, value: T, ttlMs = this.ttl, tags: string[] = []) {\n  if (!Number.isFinite(ttlMs) || ttlMs < 0) throw new Error('Invalid cache TTL')\n  this.pending.delete(key); this.remove(key); this.prune()\n  if (ttlMs === 0) return\n  const entry = { value: structuredClone(value), expiresAt: Date.now() + ttlMs, tags: new Set(tags) }\n  while (this.values.size >= this.maxEntries) this.remove(this.values.keys().next().value!)\n  this.values.set(key, entry)\n  for (const tag of entry.tags) { let keys = this.tags.get(tag); if (!keys) this.tags.set(tag, keys = new Set()); keys.add(key) }\n }\n /**\n  * Returns a cloned cached value or fetches and conditionally caches a new value.\n  * @typeParam T - Structured-cloneable value returned by fetcher and this method.\n  * @param key - Exact cache key; use forScope for authenticated partitions.\n  * @param fetcher - Called without arguments on a miss or bypass; resolves a cloneable value. Concurrent misses are not coalesced.\n  * @param options - Retention, tags, and bypass settings; see {@link CacheOptions}.\n  * @returns A separate clone of the cached or fetched value, including when invalidation prevents storage.\n  * @throws Rejects on fetcher failure, invalid TTL used for insertion, or structuredClone failure.\n  * @example\n  * ```typescript\n  * import { MemoryCacheManager } from \"@alneas/eaos-server/cache\";\n  * const cache = new MemoryCacheManager();\n  * console.log(await cache.getOrSet(\"answer\", async () => 42));\n  * ```\n  */\n async getOrSet<T>(key: string, fetcher: () => Promise<T>, options: CacheOptions = {}): Promise<T> {\n  this.prune()\n  const cached = this.values.get(key)\n  if (!options.bypass && cached) return structuredClone(cached.value) as T\n  const token = Symbol(), epoch = this.epoch; this.pending.set(key, token)\n  try {\n   const value = await fetcher()\n   if (epoch === this.epoch && this.pending.get(key) === token) this.set(key, value, options.ttlMs ?? this.ttl, options.tags)\n   return structuredClone(value)\n  } finally { if (this.pending.get(key) === token) this.pending.delete(key) }\n }\n /**\n  * Removes entries carrying any requested tag and prevents pending fetches from populating the cache.\n  * @param tags - One exact tag or multiple tags; an empty array removes no stored entries but still invalidates pending writes.\n  * @returns No value; removal completes synchronously.\n  * @example\n  * ```typescript\n  * import { MemoryCacheManager } from \"@alneas/eaos-server/cache\";\n  * const cache = new MemoryCacheManager();\n  * cache.set(\"answer\", 42, 1000, [\"answers\"]);\n  * cache.invalidateTags(\"answers\");\n  * ```\n  */\n invalidateTags(tags: string | string[]) {\n  this.epoch++\n  for (const tag of typeof tags === 'string' ? [tags] : tags) for (const key of [...(this.tags.get(tag) ?? [])]) this.remove(key)\n }\n /**\n  * Removes entries whose exact keys start with the supplied prefix and invalidates pending writes.\n  * @param prefix - Case-sensitive key prefix; an empty prefix matches every entry.\n  * @returns No value; removal completes synchronously.\n  * @example\n  * ```typescript\n  * import { MemoryCacheManager } from \"@alneas/eaos-server/cache\";\n  * const cache = new MemoryCacheManager();\n  * cache.invalidatePrefix(\"reports:\");\n  * ```\n  */\n invalidatePrefix(prefix: string) { this.epoch++; for (const key of this.values.keys()) if (key.startsWith(prefix)) this.remove(key) }\n /**\n  * Removes every cached entry, tag index, and pending write token.\n  * @returns No value; clearing completes synchronously without cancelling fetchers already running.\n  * @example\n  * ```typescript\n  * import { MemoryCacheManager } from \"@alneas/eaos-server/cache\";\n  * const cache = new MemoryCacheManager();\n  * cache.clear();\n  * ```\n  */\n clear() { this.epoch++; this.values.clear(); this.tags.clear(); this.pending.clear() }\n /**\n  * Prunes expired entries and counts the remaining stored values.\n  * @returns Current number of unexpired entries, excluding pending fetches.\n  * @example\n  * ```typescript\n  * import { MemoryCacheManager } from \"@alneas/eaos-server/cache\";\n  * const cache = new MemoryCacheManager();\n  * console.log(cache.size()); // 0\n  * ```\n  */\n size() { this.prune(); return this.values.size }\n /**\n * Creates a tenant/plugin/user partition with authorization before and after asynchronous work.\n * @param scope - Verified nonblank identity IDs and optional permission revision; see {@link CacheScope}.\n * @param authorize - Called without arguments on every lookup, including hits, and after fetching and before returning. Any truthy result permits access; errors propagate.\n * @returns A scoped getOrSet using the same key/fetcher/options semantics as this manager, plus invalidate(), which removes this partition without returning a value or calling authorize.\n * @throws Synchronously for missing/blank scope IDs. Scoped lookups reject for denied access or propagated authorization/fetch/clone errors.\n * @remarks Tenant and plugin tags are added to fetched entries. The host must supply trusted identity and live authorization; partitioning does not authenticate callers. Invalidating a scope also prevents other in-flight manager fetches from populating entries.\n * @example\n * ```typescript\n * import { MemoryCacheManager, type CacheScope } from \"@alneas/eaos-server/cache\";\n * export function userCache(scope: CacheScope, authorize: () => Promise<boolean>) {\n *   return new MemoryCacheManager().forScope(scope, authorize);\n * }\n * ```\n */\n forScope(scope: CacheScope, authorize: () => boolean | Promise<boolean>) {\n  for (const id of [scope.tenantId, scope.pluginId, scope.userId]) if (typeof id !== 'string' || !id.trim()) throw new Error('Verified cache scope required')\n  const prefix = JSON.stringify([scope.tenantId, scope.pluginId, scope.userId, scope.permissionVersion ?? '']) + ':'\n  const tenantTag = `tenant:${scope.tenantId}`, pluginTag = `plugin:${scope.pluginId}`\n  const allowed = async () => { if (!await authorize()) throw new Error('Cache access denied') }\n  return { getOrSet: async <T>(key: string, fetcher: () => Promise<T>, options: CacheOptions = {}) => {\n   await allowed()\n   const value = await this.getOrSet(prefix + key, async () => { const result = await fetcher(); await allowed(); return result }, { ...options, tags: [...(options.tags ?? []), tenantTag, pluginTag] })\n   await allowed(); return value\n  }, invalidate: () => this.invalidatePrefix(prefix) }\n }\n}\n/**\n * Detects request directives or query flags asking to bypass cached values.\n * @param c - Hono request context; reads Cache-Control, Pragma, refresh, and nocache.\n * @returns True for no-cache, max-age=0 (optionally quoted), or refresh/nocache equal to true or 1; false otherwise. Header directives are case-insensitive; query flag values are case-sensitive.\n * @example\n * ```typescript\n * import { Hono } from \"hono\";\n * import { isNoCacheRequested } from \"@alneas/eaos-server/cache\";\n * const app = new Hono();\n * app.get(\"/cache-policy\", c => c.json({ bypass: isNoCacheRequested(c) }));\n * console.log(await (await app.request(\"/cache-policy?refresh=1\")).json());\n * ```\n */\nexport function isNoCacheRequested(c: Pick<Context, 'req'>): boolean {\n const directives = `${c.req.header('cache-control') ?? ''},${c.req.header('pragma') ?? ''}`.toLowerCase().split(',').map(v => v.trim())\n return directives.some(v => v === 'no-cache' || /^max-age\\s*=\\s*\"?0\"?$/.test(v)) || ['refresh', 'nocache'].some(key => ['true', '1'].includes(c.req.query(key) ?? ''))\n}\n"],"mappings":"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","names":[]}

package/dist/chunk-32746UQZ.js

@@ -0,0 +1,131 @@
+import {
+  ServerAgentExecutionError
+} from "./chunk-YABTQZDJ.js";
+
+// src/agentic/executor.ts
+import { randomUUID } from "node:crypto";
+import { spawn } from "node:child_process";
+import { resolve } from "node:path";
+import { defaultRuntimePlacementPolicy } from "@alneas/eaos-core";
+function validateAgentRuntimePolicy(policy) {
+  const baseline = defaultRuntimePlacementPolicy().ai.agentRuntime;
+  if (!policy || policy.placement !== "ai" || policy.rootFilesystem !== "read-only" || policy.network !== "private-only" || !Number.isSafeInteger(policy.maxConcurrent) || policy.maxConcurrent < 1 || policy.maxConcurrent > baseline.maxConcurrent || !Number.isSafeInteger(policy.maxRuntimeMs) || policy.maxRuntimeMs < 1 || policy.maxRuntimeMs > baseline.maxRuntimeMs || !Number.isSafeInteger(policy.memoryLimitMb) || policy.memoryLimitMb < 1 || policy.memoryLimitMb > baseline.memoryLimitMb || !Number.isSafeInteger(policy.pidsLimit) || policy.pidsLimit < 1 || policy.pidsLimit > baseline.pidsLimit || policy.tmpfs.path !== "/tmp" || policy.tmpfs.noexec !== true || policy.tmpfs.nosuid !== true || policy.tmpfs.nodev !== true || !Number.isSafeInteger(policy.tmpfs.maxBytes) || policy.tmpfs.maxBytes < 1 || policy.tmpfs.maxBytes > baseline.tmpfs.maxBytes || policy.workspace.path !== "/workspace" || policy.workspace.mode !== baseline.workspace.mode || policy.workspace.persistent !== false || !Number.isSafeInteger(policy.workspace.maxBytes) || policy.workspace.maxBytes < 1 || policy.workspace.maxBytes > baseline.workspace.maxBytes) {
+    throw new Error("Agent runtime policy may only tighten the framework default");
+  }
+  return structuredClone(policy);
+}
+function buildSystemdRunArgs(command, args, policy, cwd, unit) {
+  const workingDirectory = resolve(cwd || process.cwd());
+  const runtimeSeconds = Math.max(1, Math.ceil(policy.maxRuntimeMs / 1e3));
+  const user = typeof process.getuid === "function" && process.getuid() !== 0;
+  return [
+    ...user ? ["--user"] : [],
+    "--wait",
+    "--collect",
+    "--pipe",
+    "--quiet",
+    `--unit=${unit}`,
+    `--property=MemoryMax=${policy.memoryLimitMb}M`,
+    `--property=TasksMax=${policy.pidsLimit}`,
+    `--property=RuntimeMaxSec=${runtimeSeconds}s`,
+    "--property=ProtectSystem=strict",
+    "--property=NoNewPrivileges=yes",
+    "--property=PrivateTmp=yes",
+    `--property=TemporaryFileSystem=${policy.tmpfs.path}:rw,noexec,nosuid,nodev,size=${policy.tmpfs.maxBytes}`,
+    `--property=ReadWritePaths=${workingDirectory}`,
+    `--working-directory=${workingDirectory}`,
+    "--",
+    command,
+    ...args
+  ];
+}
+function sandboxMode(options) {
+  return options?.mode || "auto";
+}
+function useSystemd(mode) {
+  if (mode === "direct") return false;
+  if (mode === "systemd") return true;
+  return process.platform === "linux";
+}
+function stopSystemdUnit(unit) {
+  const user = typeof process.getuid === "function" && process.getuid() !== 0;
+  const child = spawn("systemctl", [...user ? ["--user"] : [], "stop", unit], { stdio: "ignore" });
+  child.once("error", () => void 0);
+}
+function createCommandAgentExecutor(options) {
+  if (typeof options.command !== "string" || !options.command.trim() || typeof options.buildArgs !== "function") throw new Error("Invalid command agent executor");
+  const timeoutDefault = options.timeoutMs ?? 6e4;
+  const maxOutputChars = options.maxOutputChars ?? 1e6;
+  if (!Number.isSafeInteger(timeoutDefault) || timeoutDefault < 1 || timeoutDefault > 36e5 || !Number.isSafeInteger(maxOutputChars) || maxOutputChars < 1 || maxOutputChars > 1e7) throw new Error("Invalid command agent executor limits");
+  return async (request) => {
+    const args = options.buildArgs(structuredClone(request));
+    if (!Array.isArray(args) || args.some((arg) => typeof arg !== "string")) throw new Error("Command agent arguments must be strings");
+    const timeoutMs = request.timeoutMs ?? timeoutDefault;
+    if (!Number.isSafeInteger(timeoutMs) || timeoutMs < 1 || timeoutMs > 36e5) throw new Error("Invalid command agent timeout");
+    const customEnv = options.env?.(structuredClone(request)) ?? {};
+    const env = {
+      ...options.includeProcessEnv ? process.env : {},
+      EAOS_TENANT_ID: request.tenantId,
+      EAOS_TASK_ID: request.id,
+      ...request.executionContext?.workflowId ? { EAOS_WORKFLOW_ID: request.executionContext.workflowId } : {},
+      ...request.executionContext?.correlationId ? { EAOS_CORRELATION_ID: request.executionContext.correlationId } : {},
+      ...request.executionContext?.idempotencyKey ? { EAOS_IDEMPOTENCY_KEY: request.executionContext.idempotencyKey } : {},
+      ...request.executionContext?.toolMode ? { EAOS_TOOL_MODE: request.executionContext.toolMode } : {},
+      ...request.executionContext?.allowedToolNames ? { EAOS_ALLOWED_TOOL_NAMES: JSON.stringify(request.executionContext.allowedToolNames) } : {},
+      ...customEnv
+    };
+    const policy = validateAgentRuntimePolicy(options.sandbox?.policy || request.runtimePolicy || defaultRuntimePlacementPolicy().ai.agentRuntime);
+    const unit = `eaos-agent-${randomUUID()}`;
+    const managed = useSystemd(sandboxMode(options.sandbox));
+    const launchCommand = managed ? "systemd-run" : options.command;
+    const launchArgs = managed ? buildSystemdRunArgs(options.command, args, policy, options.cwd, unit) : args;
+    return new Promise((resolve2, reject) => {
+      let stdout = "";
+      let stderr = "";
+      let settled = false;
+      const child = spawn(launchCommand, launchArgs, { cwd: options.cwd, env, stdio: ["ignore", "pipe", "pipe"] });
+      const timer = setTimeout(() => {
+        fail(new ServerAgentExecutionError("Agent runtime timed out", "TIMEOUT", true));
+      }, timeoutMs);
+      const fail = (error) => {
+        if (settled) return;
+        settled = true;
+        clearTimeout(timer);
+        if (managed) stopSystemdUnit(unit);
+        child.kill("SIGTERM");
+        reject(error);
+      };
+      const append = (target, data) => {
+        if (settled) return;
+        if (target === "stdout") stdout += data.toString();
+        else stderr += data.toString();
+        if (stdout.length + stderr.length > maxOutputChars) fail(new ServerAgentExecutionError("Agent output exceeds configured limit", "OUTPUT_LIMIT", false));
+      };
+      child.stdout?.on("data", (data) => append("stdout", data));
+      child.stderr?.on("data", (data) => append("stderr", data));
+      child.once("error", (error) => fail(new ServerAgentExecutionError(`Agent runtime unavailable: ${error.message}`, "AGENT_UNAVAILABLE", true, { cause: error })));
+      child.once("close", (code) => {
+        if (settled) return;
+        settled = true;
+        clearTimeout(timer);
+        if (code !== 0) {
+          const sandboxUnavailable = managed && /(?:systemd-run|Failed to (?:connect|start|find executable)|No medium found)/i.test(stderr);
+          const message = sandboxUnavailable ? `Agent runtime unavailable: ${stderr.slice(0, 1e3)}` : `Agent runtime exited with code ${code}: ${stderr.slice(0, 1e3)}`;
+          return reject(new ServerAgentExecutionError(
+            message,
+            sandboxUnavailable ? "AGENT_UNAVAILABLE" : "RUNTIME_FAILED",
+            true
+          ));
+        }
+        resolve2(stdout);
+      });
+    });
+  };
+}
+
+export {
+  validateAgentRuntimePolicy,
+  buildSystemdRunArgs,
+  createCommandAgentExecutor
+};
+//# sourceMappingURL=chunk-32746UQZ.js.map

package/dist/chunk-32746UQZ.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/agentic/executor.ts"],"sourcesContent":["import { randomUUID } from 'node:crypto'\nimport { spawn } from 'node:child_process'\nimport { resolve } from 'node:path'\nimport { defaultRuntimePlacementPolicy, type AgentRuntimeResourcePolicy } from '@alneas/eaos-core'\nimport { ServerAgentExecutionError, type ServerAgentExecutor, type ServerAgentTaskRequest } from './types'\n\n/**\n * Chooses Linux systemd-run, direct spawning, or automatic platform selection.\n * @see createCommandAgentExecutor.\n */\nexport type CommandAgentSandboxMode = 'auto' | 'systemd' | 'direct'\n\n/**\n * Host sandbox selection for {@link createCommandAgentExecutor}.\n */\nexport interface CommandAgentSandboxOptions {\n  /** auto uses transient systemd on Linux and direct execution on local development hosts. */\n  mode?: CommandAgentSandboxMode\n  /** Resource policy is framework-owned by default; consumers may only tighten it in a host adapter. */\n  policy?: AgentRuntimeResourcePolicy\n}\n\n/**\n * Trusted executable, argument/environment builders, and limits for {@link createCommandAgentExecutor}.\n */\nexport interface CommandAgentExecutorOptions {\n  /** Host-configured executable. It is never taken from a task request. */\n  command: string\n  /** Called once per task with a structured clone; must return string arguments. Arguments are passed without a shell, and callback errors reject execution. */\n  buildArgs: (request: ServerAgentTaskRequest) => readonly string[]\n  /** Process working directory; omitted uses the host process directory. Under systemd this directory is also explicitly writable. */\n  cwd?: string\n  /** Per-task environment callback receiving a clone; its entries override framework EAOS variables. Defaults to no additional variables. */\n  env?: (request: ServerAgentTaskRequest) => Record<string, string | undefined>\n  /** Inherit host process environment before framework/custom variables. @defaultValue false */\n  includeProcessEnv?: boolean\n  /** Default task timeout in milliseconds, safe integer 1–3600000; task.timeoutMs overrides it. @defaultValue 60000 */\n  timeoutMs?: number\n  /** Combined stdout/stderr string-length ceiling, safe integer 1–10000000. @defaultValue 1000000 */\n  maxOutputChars?: number\n  /** Sandbox selection; defaults to auto and a validated task/framework policy. Direct mode does not apply systemd resource/filesystem restrictions. */\n  sandbox?: CommandAgentSandboxOptions\n}\n\n/**\n * Validates that resource-policy fields retain or tighten the current framework baseline.\n * @param policy - Runtime resource policy with AI placement, read-only root, private-only network, and bounded resources.\n * @returns A structured clone of the accepted policy.\n * @throws For weaker/invalid fields; malformed nested fields can also throw property-access errors.\n * @remarks Validation does not itself apply operating-system isolation, concurrency, or network controls.\n * @example\n * ```typescript\n * import { defaultRuntimePlacementPolicy } from \"@alneas/eaos-core\";\n * import { validateAgentRuntimePolicy } from \"@alneas/eaos-server/agentic/executor\";\n * const policy = validateAgentRuntimePolicy(defaultRuntimePlacementPolicy().ai.agentRuntime);\n * console.log(policy.placement); // \"ai\"\n * ```\n */\nexport function validateAgentRuntimePolicy(policy: AgentRuntimeResourcePolicy): AgentRuntimeResourcePolicy {\n  const baseline = defaultRuntimePlacementPolicy().ai.agentRuntime\n  if (!policy || policy.placement !== 'ai' || policy.rootFilesystem !== 'read-only' || policy.network !== 'private-only' ||\n      !Number.isSafeInteger(policy.maxConcurrent) || policy.maxConcurrent < 1 || policy.maxConcurrent > baseline.maxConcurrent ||\n      !Number.isSafeInteger(policy.maxRuntimeMs) || policy.maxRuntimeMs < 1 || policy.maxRuntimeMs > baseline.maxRuntimeMs ||\n      !Number.isSafeInteger(policy.memoryLimitMb) || policy.memoryLimitMb < 1 || policy.memoryLimitMb > baseline.memoryLimitMb ||\n      !Number.isSafeInteger(policy.pidsLimit) || policy.pidsLimit < 1 || policy.pidsLimit > baseline.pidsLimit ||\n      policy.tmpfs.path !== '/tmp' || policy.tmpfs.noexec !== true || policy.tmpfs.nosuid !== true || policy.tmpfs.nodev !== true ||\n      !Number.isSafeInteger(policy.tmpfs.maxBytes) || policy.tmpfs.maxBytes < 1 || policy.tmpfs.maxBytes > baseline.tmpfs.maxBytes ||\n      policy.workspace.path !== '/workspace' || policy.workspace.mode !== baseline.workspace.mode || policy.workspace.persistent !== false ||\n      !Number.isSafeInteger(policy.workspace.maxBytes) || policy.workspace.maxBytes < 1 || policy.workspace.maxBytes > baseline.workspace.maxBytes) {\n    throw new Error('Agent runtime policy may only tighten the framework default')\n  }\n  return structuredClone(policy)\n}\n\n/**\n * Builds systemd-run arguments for transient process resource and filesystem restrictions.\n * @param command - Trusted executable passed after the systemd option terminator.\n * @param args - Executable arguments, passed unchanged without a shell.\n * @param policy - Already validated resource policy; this helper does not validate it.\n * @param cwd - Working directory, resolved absolutely; absent/empty uses process.cwd().\n * @param unit - Host-selected transient unit name, used for later stop requests.\n * @returns A new argument array, using --user for a nonroot host user and rounding runtime milliseconds upward to at least one second.\n * @remarks Requires a host with systemd-run and appropriate service-manager permissions when executed. This array does not implement network allowlisting, workspace capacity, or a concurrency scheduler; those policy fields require host enforcement.\n * @example\n * ```typescript\n * import { defaultRuntimePlacementPolicy } from \"@alneas/eaos-core\";\n * import { buildSystemdRunArgs } from \"@alneas/eaos-server/agentic/executor\";\n * const args = buildSystemdRunArgs(\"agent-runtime\", [\"--version\"], defaultRuntimePlacementPolicy().ai.agentRuntime, undefined, \"example-agent\");\n * console.log(args.includes(\"--wait\")); // true\n * ```\n */\nexport function buildSystemdRunArgs(command: string, args: readonly string[], policy: AgentRuntimeResourcePolicy, cwd: string | undefined, unit: string): string[] {\n  const workingDirectory = resolve(cwd || process.cwd())\n  const runtimeSeconds = Math.max(1, Math.ceil(policy.maxRuntimeMs / 1000))\n  const user = typeof process.getuid === 'function' && process.getuid() !== 0\n  return [\n    ...(user ? ['--user'] : []),\n    '--wait', '--collect', '--pipe', '--quiet', `--unit=${unit}`,\n    `--property=MemoryMax=${policy.memoryLimitMb}M`,\n    `--property=TasksMax=${policy.pidsLimit}`,\n    `--property=RuntimeMaxSec=${runtimeSeconds}s`,\n    '--property=ProtectSystem=strict',\n    '--property=NoNewPrivileges=yes',\n    '--property=PrivateTmp=yes',\n    `--property=TemporaryFileSystem=${policy.tmpfs.path}:rw,noexec,nosuid,nodev,size=${policy.tmpfs.maxBytes}`,\n    `--property=ReadWritePaths=${workingDirectory}`,\n    `--working-directory=${workingDirectory}`,\n    '--', command, ...args,\n  ]\n}\n\nfunction sandboxMode(options: CommandAgentSandboxOptions | undefined): CommandAgentSandboxMode {\n  return options?.mode || 'auto'\n}\n\nfunction useSystemd(mode: CommandAgentSandboxMode): boolean {\n  if (mode === 'direct') return false\n  if (mode === 'systemd') return true\n  return process.platform === 'linux'\n}\n\nfunction stopSystemdUnit(unit: string) {\n  const user = typeof process.getuid === 'function' && process.getuid() !== 0\n  const child = spawn('systemctl', [...(user ? ['--user'] : []), 'stop', unit], { stdio: 'ignore' })\n  child.once('error', () => undefined)\n}\n\n/**\n * Creates a shell-free executor for OpenCode, Codex, Goose or another trusted\n * CLI. Authorization and approval happen before this adapter is called.\n * @param options - Trusted executable, argument/environment callbacks, output/timeout limits, and sandbox settings.\n * @returns A per-task async executor resolving stdout on exit code zero, including an empty string when no output was produced.\n * @throws Synchronously for invalid factory settings. Execution rejects callback/clone/policy errors and ServerAgentExecutionError for spawn, timeout, output-limit, or nonzero-exit failures.\n * @remarks Requires Node child_process. auto selects systemd on Linux and direct execution elsewhere. No task concurrency limit is enforced here. stdin is ignored, stdout/stderr are bounded together, and stderr is excluded from successful output. On timeout/output/spawn failure the timer is cleared, SIGTERM is sent, and systemd stop is requested when managed; termination is not awaited and descendants may outlive direct-mode failure. Idempotency is only propagated through environment variables; host/runtime code must enforce safe retries.\n * @example\n * ```typescript\n * import { createCommandAgentExecutor, type CommandAgentExecutorOptions } from \"@alneas/eaos-server/agentic/executor\";\n * export function hostExecutor(configuration: CommandAgentExecutorOptions) {\n *   // The host provisions the executable and performs admission/approval first.\n *   return createCommandAgentExecutor(configuration);\n * }\n * ```\n */\nexport function createCommandAgentExecutor(options: CommandAgentExecutorOptions): ServerAgentExecutor {\n  if (typeof options.command !== 'string' || !options.command.trim() || typeof options.buildArgs !== 'function') throw new Error('Invalid command agent executor')\n  const timeoutDefault = options.timeoutMs ?? 60_000\n  const maxOutputChars = options.maxOutputChars ?? 1_000_000\n  if (!Number.isSafeInteger(timeoutDefault) || timeoutDefault < 1 || timeoutDefault > 3_600_000 || !Number.isSafeInteger(maxOutputChars) || maxOutputChars < 1 || maxOutputChars > 10_000_000) throw new Error('Invalid command agent executor limits')\n\n  return async request => {\n    const args = options.buildArgs(structuredClone(request))\n    if (!Array.isArray(args) || args.some(arg => typeof arg !== 'string')) throw new Error('Command agent arguments must be strings')\n    const timeoutMs = request.timeoutMs ?? timeoutDefault\n    if (!Number.isSafeInteger(timeoutMs) || timeoutMs < 1 || timeoutMs > 3_600_000) throw new Error('Invalid command agent timeout')\n    const customEnv = options.env?.(structuredClone(request)) ?? {}\n    const env = {\n      ...(options.includeProcessEnv ? process.env : {}),\n      EAOS_TENANT_ID: request.tenantId,\n      EAOS_TASK_ID: request.id,\n      ...(request.executionContext?.workflowId ? { EAOS_WORKFLOW_ID: request.executionContext.workflowId } : {}),\n      ...(request.executionContext?.correlationId ? { EAOS_CORRELATION_ID: request.executionContext.correlationId } : {}),\n      ...(request.executionContext?.idempotencyKey ? { EAOS_IDEMPOTENCY_KEY: request.executionContext.idempotencyKey } : {}),\n      ...(request.executionContext?.toolMode ? { EAOS_TOOL_MODE: request.executionContext.toolMode } : {}),\n      ...(request.executionContext?.allowedToolNames ? { EAOS_ALLOWED_TOOL_NAMES: JSON.stringify(request.executionContext.allowedToolNames) } : {}),\n      ...customEnv,\n    }\n    const policy = validateAgentRuntimePolicy(options.sandbox?.policy || request.runtimePolicy || defaultRuntimePlacementPolicy().ai.agentRuntime)\n    const unit = `eaos-agent-${randomUUID()}`\n    const managed = useSystemd(sandboxMode(options.sandbox))\n    const launchCommand = managed ? 'systemd-run' : options.command\n    const launchArgs = managed ? buildSystemdRunArgs(options.command, args, policy, options.cwd, unit) : args\n\n    return new Promise((resolve, reject) => {\n      let stdout = ''\n      let stderr = ''\n      let settled = false\n      const child = spawn(launchCommand, launchArgs, { cwd: options.cwd, env, stdio: ['ignore', 'pipe', 'pipe'] })\n      const timer = setTimeout(() => {\n        fail(new ServerAgentExecutionError('Agent runtime timed out', 'TIMEOUT', true))\n      }, timeoutMs)\n      const fail = (error: Error) => {\n        if (settled) return\n        settled = true\n        clearTimeout(timer)\n        if (managed) stopSystemdUnit(unit)\n        child.kill('SIGTERM')\n        reject(error)\n      }\n      const append = (target: 'stdout' | 'stderr', data: Buffer | string) => {\n        if (settled) return\n        if (target === 'stdout') stdout += data.toString()\n        else stderr += data.toString()\n        if (stdout.length + stderr.length > maxOutputChars) fail(new ServerAgentExecutionError('Agent output exceeds configured limit', 'OUTPUT_LIMIT', false))\n      }\n      child.stdout?.on('data', data => append('stdout', data))\n      child.stderr?.on('data', data => append('stderr', data))\n      child.once('error', error => fail(new ServerAgentExecutionError(`Agent runtime unavailable: ${error.message}`, 'AGENT_UNAVAILABLE', true, { cause: error })))\n      child.once('close', code => {\n        if (settled) return\n        settled = true\n        clearTimeout(timer)\n        if (code !== 0) {\n          const sandboxUnavailable = managed && /(?:systemd-run|Failed to (?:connect|start|find executable)|No medium found)/i.test(stderr)\n          const message = sandboxUnavailable\n            ? `Agent runtime unavailable: ${stderr.slice(0, 1000)}`\n            : `Agent runtime exited with code ${code}: ${stderr.slice(0, 1000)}`\n          return reject(new ServerAgentExecutionError(\n            message,\n            sandboxUnavailable ? 'AGENT_UNAVAILABLE' : 'RUNTIME_FAILED',\n            true,\n          ))\n        }\n        resolve(stdout)\n      })\n    })\n  }\n}\n"],"mappings":"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","names":["resolve"]}