ai-runtime-engine 1.2.0 → 2.7.0

package/dist/store/store.js

@@ -7,17 +7,21 @@ import { existsSync, mkdirSync, readFileSync, rmSync, statSync, writeFileSync }
 import { join } from 'node:path';
 import { systemClock } from '../util/clock.js';
 import { FileArea, NullArea } from './area.js';
-import { projectId as computeProjectId, repositoryId as computeRepositoryId, resolveHome } from './paths.js';
+import { projectId as computeProjectId, repositoryId as computeRepositoryId, organizationId as computeOrganizationId, resolveHome } from './paths.js';
 export const STORE_VERSION = 1;
 export class RuntimeStore {
     enabled;
     projectId;
     repositoryId;
+    /** Present only when an organization is configured — the availability signal for the `organization` scope. */
+    organizationId;
     clock;
     home;
     projectDir;
     repoDir;
     userDir;
+    orgDir;
+    cipher;
     areas = new Map();
     metaStamped = false;
     constructor(options) {
@@ -30,26 +34,38 @@ export class RuntimeStore {
         this.projectDir = join(this.home, 'projects', this.projectId);
         this.repoDir = join(this.home, 'repos', this.repositoryId);
         this.userDir = join(this.home, 'user');
+        if (options.organization && options.organization.trim()) {
+            this.organizationId = computeOrganizationId(options.organization);
+            this.orgDir = join(this.home, 'organizations', this.organizationId);
+        }
+        if (options.cipher)
+            this.cipher = options.cipher;
     }
     paths() {
-        return { home: this.home, project: this.projectDir, repository: this.repoDir, user: this.userDir };
+        return { home: this.home, project: this.projectDir, repository: this.repoDir, user: this.userDir, ...(this.orgDir ? { organization: this.orgDir } : {}) };
     }
     area(dir) {
         if (!this.enabled)
-            return new NullArea();
+            return new NullArea(); // stateless areas are never wrapped
         let a = this.areas.get(dir);
         if (!a) {
-            a = new FileArea(dir);
+            a = new FileArea(dir, this.cipher); // cipher (when configured) encrypts every file area transparently
             this.areas.set(dir, a);
         }
         return a;
     }
-    /** Memory area for a physical scope. */
+    /** Memory area for a physical scope. `organization` requires a configured org (guarded by callers). */
     memory(scope) {
         if (scope === 'user')
             return this.area(join(this.userDir, 'memory'));
         if (scope === 'repository')
             return this.area(join(this.repoDir, 'memory'));
+        if (scope === 'organization') {
+            // Callers only traverse this scope when `organizationId` is set; a stray call with no org is a no-op.
+            if (!this.orgDir)
+                return new NullArea();
+            return this.area(join(this.orgDir, 'memory'));
+        }
         return this.area(join(this.projectDir, 'memory'));
     }
     conversations() {
@@ -58,6 +74,10 @@ export class RuntimeStore {
     indexes() {
         return this.area(join(this.projectDir, 'indexes'));
     }
+    /** MCP state: dynamic servers, enable/disable overrides, and per-server tool caches (Phase 3.2). */
+    mcp() {
+        return this.area(join(this.projectDir, 'mcp'));
+    }
     cache() {
         return this.area(join(this.projectDir, 'cache'));
     }
@@ -131,10 +151,11 @@ export class RuntimeStore {
                 rmSync(lockPath);
         }
     }
-    /** Aggregate integrity check across the project areas. */
+    /** Aggregate integrity check across the project areas (plus the org area when configured). */
     check() {
         if (!this.enabled)
             return [];
-        return [...this.memory('project').check(), ...this.memory('user').check(), ...this.memory('repository').check(), ...this.conversations().check(), ...this.indexes().check()];
+        const org = this.orgDir ? this.memory('organization').check() : [];
+        return [...this.memory('project').check(), ...this.memory('user').check(), ...this.memory('repository').check(), ...org, ...this.conversations().check(), ...this.indexes().check()];
     }
 }

package/dist/telemetry/sinks/otlp.d.ts

@@ -0,0 +1,31 @@
+/**
+ * OTLP-shaped telemetry exporter (Phase 19). Maps the four frozen `TelemetryEvent` members to an
+ * OpenTelemetry-JSON-ish payload (resource + a scope with logRecords) and POSTs them, batched, to an
+ * OTLP/HTTP-style `endpoint`. Metadata ONLY — the events are already routing/perf metadata and are passed
+ * through `redact()` before they leave the process; prompt text / inputs / keys never appear. Like every
+ * sink, ALL IO is wrapped and swallowed: telemetry must never fail a run.
+ *
+ * An optional auth header value is read from the env var NAMED by `headersEnv` (never a value in config).
+ */
+import type { TelemetrySink } from '../telemetry.js';
+import type { TelemetryEvent } from '../../types.js';
+import type { FetchLike } from '../../providers/httpClient.js';
+export interface OtlpSinkOptions {
+    endpoint: string;
+    fetchImpl?: FetchLike;
+    /** Resolved auth header value (from an env-var NAME upstream), sent as `authorization` if present. */
+    authHeader?: string;
+    /** Flush when this many events are buffered (default 20). */
+    batchSize?: number;
+}
+export declare class OtlpSink implements TelemetrySink {
+    private readonly endpoint;
+    private readonly fetchImpl;
+    private readonly authHeader?;
+    private readonly batchSize;
+    private buffer;
+    constructor(opts: OtlpSinkOptions);
+    emit(event: TelemetryEvent): void;
+    /** POST the buffered batch. Fire-and-forget; every error is swallowed. */
+    flush(): void;
+}

package/dist/telemetry/sinks/otlp.js

@@ -0,0 +1,76 @@
+/**
+ * OTLP-shaped telemetry exporter (Phase 19). Maps the four frozen `TelemetryEvent` members to an
+ * OpenTelemetry-JSON-ish payload (resource + a scope with logRecords) and POSTs them, batched, to an
+ * OTLP/HTTP-style `endpoint`. Metadata ONLY — the events are already routing/perf metadata and are passed
+ * through `redact()` before they leave the process; prompt text / inputs / keys never appear. Like every
+ * sink, ALL IO is wrapped and swallowed: telemetry must never fail a run.
+ *
+ * An optional auth header value is read from the env var NAMED by `headersEnv` (never a value in config).
+ */
+import { redact } from '../../security/redact.js';
+/** Severity mapping for the four event types (INFO by default; a failed result is WARN). */
+function toLogRecord(event) {
+    const attributes = Object.entries(event)
+        .filter(([k]) => k !== 'ts' && k !== 'type')
+        .map(([k, v]) => ({ key: k, value: otlpAnyValue(v) }));
+    const severe = event.type === 'route.result' && event.ok === false;
+    return {
+        timeUnixNano: String(BigInt(Math.trunc(event.ts)) * 1000000n), // ms → ns
+        severityText: severe ? 'WARN' : 'INFO',
+        body: { stringValue: event.type },
+        attributes,
+    };
+}
+function otlpAnyValue(v) {
+    if (typeof v === 'string')
+        return { stringValue: v };
+    if (typeof v === 'boolean')
+        return { boolValue: v };
+    if (typeof v === 'number')
+        return Number.isInteger(v) ? { intValue: String(v) } : { doubleValue: v };
+    return { stringValue: JSON.stringify(v) };
+}
+export class OtlpSink {
+    endpoint;
+    fetchImpl;
+    authHeader;
+    batchSize;
+    buffer = [];
+    constructor(opts) {
+        this.endpoint = opts.endpoint;
+        this.fetchImpl = opts.fetchImpl ?? fetch;
+        if (opts.authHeader)
+            this.authHeader = opts.authHeader;
+        this.batchSize = opts.batchSize && opts.batchSize > 0 ? opts.batchSize : 20;
+    }
+    emit(event) {
+        this.buffer.push(redact(event));
+        if (this.buffer.length >= this.batchSize)
+            this.flush();
+    }
+    /** POST the buffered batch. Fire-and-forget; every error is swallowed. */
+    flush() {
+        if (this.buffer.length === 0)
+            return;
+        const batch = this.buffer;
+        this.buffer = [];
+        const payload = {
+            resourceLogs: [
+                {
+                    resource: { attributes: [{ key: 'service.name', value: { stringValue: 'ai-runtime' } }] },
+                    scopeLogs: [{ scope: { name: 'ai-runtime.router' }, logRecords: batch.map(toLogRecord) }],
+                },
+            ],
+        };
+        const headers = { 'content-type': 'application/json' };
+        if (this.authHeader)
+            headers.authorization = this.authHeader;
+        try {
+            // Fire-and-forget: never await, never let a rejection escape (telemetry must not fail a run).
+            void Promise.resolve(this.fetchImpl(this.endpoint, { method: 'POST', headers, body: JSON.stringify(payload) })).catch(() => { });
+        }
+        catch {
+            /* a telemetry export must never fail a run */
+        }
+    }
+}

package/dist/tools/builtins/filesystem.js

@@ -10,6 +10,7 @@ import { resolveInJail, JailError } from '../jail.js';
 export const filesystemTool = {
     id: 'filesystem',
     description: 'Read, write, list, and check files within the workspace (jailed; no escape).',
+    provides: [{ id: 'read_file' }, { id: 'write_file' }],
     parameters: { op: 'read | write | list | exists', path: 'string (relative to workspace)', content: 'string (write only)' },
     async execute(input, ctx) {
         const { op, path, content } = (input ?? {});

package/dist/tools/builtins/git.js

@@ -19,6 +19,7 @@ export function createGitTool(runner = defaultRunner) {
         id: 'git',
         description: 'Read git state (status/diff/log); commit/push are permission-gated and off by default.',
         parameters: { op: 'status | diff | log | commit | push', message: 'string (commit)', args: 'string[] (refs only)' },
+        provides: [{ id: 'read_repository' }, { id: 'commit_changes' }],
         async execute(input, ctx) {
             const { op, message, args = [] } = (input ?? {});
             if (!op)

package/dist/tools/builtins/shell.js

@@ -56,6 +56,7 @@ export function createShellTool(runner = defaultRunner) {
         id: 'shell',
         description: 'Run an allowlisted shell command in the workspace (destructive commands need approval).',
         parameters: { command: 'string (argv[0])', args: 'string[]' },
+        provides: [{ id: 'run_command' }, { id: 'run_tests' }],
         async execute(input, ctx) {
             const { command, args = [] } = (input ?? {});
             if (typeof command !== 'string' || command === '')

package/dist/tools/permissions.d.ts

@@ -5,6 +5,8 @@
  * allowlist fields win over the flat Phase-1 fields when both are present.
  */
 import type { PermissionPolicy } from '../runtime/policy.js';
+/** Per-server MCP grant. `off` denies before any prompt; `read` admits read-only tools; `full` admits all. */
+export type McpServerGrant = 'off' | 'read' | 'full';
 export interface ResolvedPermissions {
     filesystem: {
         read: boolean;
@@ -21,5 +23,31 @@ export interface ResolvedPermissions {
     network: {
         enabled: boolean;
     };
+    /**
+     * MCP execution (Phase 3.2). This is the SOLE authority for MCP tool execution: adding or connecting a
+     * server grants nothing, and `network`/`shell` are tool-local concerns that do not gate MCP transports
+     * (recorded as a decision — one dimension answers one question, so deny-by-default cannot fail open).
+     */
+    mcp: {
+        servers: Record<string, McpServerGrant>;
+    };
 }
+/**
+ * Combine two MCP permission maps by MINIMUM per server — the only nested permission dimension, so its
+ * merge rule is explicit: an override can never widen a grant, and a server absent from the override
+ * keeps the base grant. Every agent/skill/tool override path must go through this.
+ */
+export declare function clampMcpPermissions(base: Record<string, McpServerGrant>, override: Record<string, McpServerGrant | boolean> | undefined): Record<string, McpServerGrant>;
+/**
+ * Combine two permission policies by MINIMUM — the permission half of an agent envelope.
+ *
+ * The output is FULLY EXPLICIT on every dimension (it is resolved through `resolvePermissions` first),
+ * and that is what makes it safe to hand to `Runtime.resolvedPermissions` as an override: that merge is
+ * a shallow spread, so an override with ABSENT fields would silently fall back to defaults — and
+ * `fsRead` defaults to TRUE. Emitting explicit values means the spread can only ever narrow.
+ *
+ * Booleans combine by AND, `shellAllowedCommands` by INTERSECTION, and `mcp.servers` by
+ * `clampMcpPermissions` (per-server minimum). An override can never widen anything.
+ */
+export declare function clampPermissions(base: PermissionPolicy, override?: PermissionPolicy): PermissionPolicy;
 export declare function resolvePermissions(policy?: PermissionPolicy): ResolvedPermissions;

package/dist/tools/permissions.js

@@ -4,6 +4,74 @@
  * the workspace), writes/shell/git-mutations/network are OFF unless explicitly granted. The structured
  * allowlist fields win over the flat Phase-1 fields when both are present.
  */
+const GRANT_RANK = { off: 0, read: 1, full: 2 };
+/**
+ * Normalize the config-facing value (`true` ≡ full, `false` ≡ off) into a grant. Anything that is not
+ * exactly one of the three grant names collapses to `off`: the value comes from a YAML file, so
+ * `read: yes` (a string), a number, or a typo must never be treated as "some grant".
+ */
+function toGrant(v) {
+    if (v === true)
+        return 'full';
+    if (v === 'off' || v === 'read' || v === 'full')
+        return v;
+    return 'off';
+}
+/**
+ * Combine two MCP permission maps by MINIMUM per server — the only nested permission dimension, so its
+ * merge rule is explicit: an override can never widen a grant, and a server absent from the override
+ * keeps the base grant. Every agent/skill/tool override path must go through this.
+ */
+export function clampMcpPermissions(base, override) {
+    const out = Object.create(null);
+    for (const [k, v] of Object.entries(base))
+        out[k] = toGrant(v);
+    if (!override)
+        return out;
+    for (const [server, raw] of Object.entries(override)) {
+        const want = toGrant(raw);
+        const have = Object.prototype.hasOwnProperty.call(out, server) ? out[server] : 'off';
+        out[server] = GRANT_RANK[want] < GRANT_RANK[have] ? want : have;
+    }
+    return out;
+}
+/** Build a prototype-free grant map, so an unconfigured key can only ever answer `undefined`. */
+function grantMap(raw) {
+    const out = Object.create(null);
+    for (const [k, v] of Object.entries(raw ?? {}))
+        out[k] = toGrant(v);
+    return out;
+}
+/**
+ * Combine two permission policies by MINIMUM — the permission half of an agent envelope.
+ *
+ * The output is FULLY EXPLICIT on every dimension (it is resolved through `resolvePermissions` first),
+ * and that is what makes it safe to hand to `Runtime.resolvedPermissions` as an override: that merge is
+ * a shallow spread, so an override with ABSENT fields would silently fall back to defaults — and
+ * `fsRead` defaults to TRUE. Emitting explicit values means the spread can only ever narrow.
+ *
+ * Booleans combine by AND, `shellAllowedCommands` by INTERSECTION, and `mcp.servers` by
+ * `clampMcpPermissions` (per-server minimum). An override can never widen anything.
+ */
+export function clampPermissions(base, override) {
+    const b = resolvePermissions(base);
+    const and = (left, right) => left && (right ?? true);
+    const allowed = override?.shellAllowedCommands
+        ? b.shell.allowedCommands.filter((c) => override.shellAllowedCommands.includes(c))
+        : [...b.shell.allowedCommands];
+    return {
+        fsRead: and(b.filesystem.read, override?.fsRead),
+        fsWrite: and(b.filesystem.write, override?.fsWrite),
+        shell: and(b.shell.enabled, override?.shell),
+        shellAllowedCommands: allowed,
+        // `gitWrite` is the Phase-1 umbrella; emitting the two explicit grants instead means the resolved
+        // view cannot be widened by an absent umbrella on a later merge.
+        gitCommit: and(b.git.commit, override?.gitCommit ?? override?.gitWrite),
+        gitPush: and(b.git.push, override?.gitPush ?? override?.gitWrite),
+        network: and(b.network.enabled, override?.network),
+        mcp: { servers: { ...clampMcpPermissions(b.mcp.servers, override?.mcp?.servers) } },
+    };
+}
 export function resolvePermissions(policy = {}) {
     const gitDefault = policy.gitWrite ?? false;
     return {
@@ -20,5 +88,9 @@ export function resolvePermissions(policy = {}) {
             push: policy.gitPush ?? gitDefault,
         },
         network: { enabled: policy.network ?? false },
+        // A NULL-PROTOTYPE map: `Object.fromEntries` inherits Object.prototype, so `servers['constructor']`
+        // would answer with a function — and a lookup of `?? 'off'` would then see a truthy non-'off' value.
+        // Deny-by-default has to hold for every possible key, not just the configured ones.
+        mcp: { servers: grantMap(policy.mcp?.servers) },
     };
 }

package/dist/tools/registry.d.ts

@@ -1,8 +1,24 @@
-/** A registry of tools, keyed by id. Registration is idempotent-by-id (last wins, like tasks). */
+/**
+ * A registry of tools, keyed by id. Registration is idempotent-by-id (last wins, like tasks).
+ *
+ * An optional change listener (Phase 3.1) lets the Runtime ingest ACTION-capability declarations at the
+ * one real registration choke point — builtins, user `registerTool`, and future sources all pass through
+ * `register()`. The zero-arg constructor is preserved (this class is public API).
+ */
 import type { Tool } from './tool.js';
+export interface ToolRegistryListener {
+    /** Called after a tool is registered. `trusted` marks in-tree builtins (see the claiming rule). */
+    onRegister?: (tool: Tool, trusted: boolean) => void;
+    onUnregister?: (id: string) => void;
+}
 export declare class ToolRegistry {
     private readonly tools;
-    register(tool: Tool): this;
+    private listener;
+    /** Attach the change listener (called once by the Runtime before builtin registration). */
+    attach(listener: ToolRegistryListener): this;
+    /** Register a tool. `trusted` is set only for in-tree builtins registered by the Runtime itself. */
+    register(tool: Tool, trusted?: boolean): this;
+    unregister(id: string): boolean;
     get(id: string): Tool | undefined;
     has(id: string): boolean;
     list(): Tool[];

package/dist/tools/registry.js

@@ -1,10 +1,30 @@
-/** A registry of tools, keyed by id. Registration is idempotent-by-id (last wins, like tasks). */
+/**
+ * A registry of tools, keyed by id. Registration is idempotent-by-id (last wins, like tasks).
+ *
+ * An optional change listener (Phase 3.1) lets the Runtime ingest ACTION-capability declarations at the
+ * one real registration choke point — builtins, user `registerTool`, and future sources all pass through
+ * `register()`. The zero-arg constructor is preserved (this class is public API).
+ */
 export class ToolRegistry {
     tools = new Map();
-    register(tool) {
+    listener = {};
+    /** Attach the change listener (called once by the Runtime before builtin registration). */
+    attach(listener) {
+        this.listener = listener ?? {};
+        return this;
+    }
+    /** Register a tool. `trusted` is set only for in-tree builtins registered by the Runtime itself. */
+    register(tool, trusted = false) {
         this.tools.set(tool.id, tool);
+        this.listener.onRegister?.(tool, trusted);
         return this;
     }
+    unregister(id) {
+        const had = this.tools.delete(id);
+        if (had)
+            this.listener.onUnregister?.(id);
+        return had;
+    }
     get(id) {
         return this.tools.get(id);
     }

package/dist/tools/tool.d.ts

@@ -9,6 +9,7 @@ import type { ArtifactRef } from '../runtime/types.js';
 import type { ApprovalProvider } from '../runtime/host.js';
 import type { Clock } from '../util/clock.js';
 import type { ResolvedPermissions } from './permissions.js';
+import type { ActionCapabilityDecl } from '../capabilities/capability.js';
 export interface ToolContext {
     workspaceRoot: string;
     permissions: ResolvedPermissions;
@@ -35,6 +36,9 @@ export interface Tool {
     description: string;
     /** JSON-schema-ish parameter description (advisory; validated by the tool's own execute). */
     parameters?: unknown;
+    /** ACTION capabilities this tool provides (Phase 3.1). Advisory metadata, NEVER authorization — this
+     *  tool's own permission checks remain the only gate. Absent ⇒ one inferred `tool:<id>` entry. */
+    provides?: ActionCapabilityDecl[];
     execute(input: unknown, ctx: ToolContext): Promise<ToolResult>;
 }
 /** Helper: a denied result with a consistent shape. */

package/dist/types.d.ts

@@ -80,6 +80,8 @@ export interface AIRequest {
     signal?: AbortSignal;
     sensitivity: Sensitivity;
     metadata?: Record<string, unknown>;
+    /** Request token-by-token streaming (text output only). A provider without `executeStream` ignores it. */
+    stream?: boolean;
 }
 export type FinishReason = 'stop' | 'length' | 'tool_calls' | 'content_filter' | 'error';
 /** What every provider adapter returns — normalized so callers never parse vendor JSON. */
@@ -335,6 +337,10 @@ export interface RunRequest {
     verification?: boolean;
     /** Attach tools from registered MCP sources to this run (requires a tool-calling model). */
     mcp?: boolean;
+    /** Stream the answer token-by-token (text output only; ignored for JSON output). Needs `onDelta`. */
+    stream?: boolean;
+    /** Called with each text chunk as it streams. The final `AIResponse.text` is still the full aggregate. */
+    onDelta?: (chunk: string) => void;
 }
 /**
  * User exclude/prefer routing (all optional). EXCLUDE is a HARD filter — an excluded candidate is never
@@ -375,9 +381,13 @@ export interface ProviderConfig {
 }
 export interface TelemetryConfig {
     enabled: boolean;
-    sink: 'memory' | 'file';
+    sink: 'memory' | 'file' | 'otlp';
     storePrompts: false;
     path?: string;
+    /** OTLP sink: the OTLP/HTTP endpoint to POST batched, redacted, metadata-only events to. */
+    endpoint?: string;
+    /** OTLP sink: env-var NAME (never a value) whose value is sent as the `authorization` header. */
+    headersEnv?: string;
 }
 export interface RouterConfig {
     providers: ProviderConfig[];

package/dist/util/flatten.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Flatten and clamp a source-, server- or MODEL-controlled string before it crosses a rendering
+ * boundary. ONE implementation behind three named entry points: `promptSafe` (model prompts,
+ * src/runtime/runtime.ts), `displaySafe` (the terminal, src/cli/render.ts), and the capability deriver's
+ * candidate labels. Internal — deliberately not exported from src/index.ts.
+ *
+ * The two properties that matter: no control characters or newlines survive (so a value can never forge
+ * an extra row in a rendered list), and the length is bounded (so it cannot dominate a prompt or a
+ * terminal line).
+ */
+export declare function flattenClamp(raw: string, max?: number): string;

package/dist/util/flatten.js

@@ -0,0 +1,18 @@
+/**
+ * Flatten and clamp a source-, server- or MODEL-controlled string before it crosses a rendering
+ * boundary. ONE implementation behind three named entry points: `promptSafe` (model prompts,
+ * src/runtime/runtime.ts), `displaySafe` (the terminal, src/cli/render.ts), and the capability deriver's
+ * candidate labels. Internal — deliberately not exported from src/index.ts.
+ *
+ * The two properties that matter: no control characters or newlines survive (so a value can never forge
+ * an extra row in a rendered list), and the length is bounded (so it cannot dominate a prompt or a
+ * terminal line).
+ */
+export function flattenClamp(raw, max = 80) {
+    const flat = String(raw ?? '')
+        // eslint-disable-next-line no-control-regex
+        .replace(/[\u0000-\u001f\u007f]+/g, ' ')
+        .replace(/\s+/g, ' ')
+        .trim();
+    return flat.length > max ? `${flat.slice(0, max)}…` : flat;
+}

package/dist/util/semaphore.d.ts

@@ -0,0 +1,19 @@
+/**
+ * A tiny keyed async semaphore (Phase 19). Each key has an independent concurrency limit; `run(key, fn)`
+ * waits until a slot for that key is free, runs `fn`, and releases the slot even if `fn` throws. Waiters are
+ * served FIFO. A key with no configured limit (or a limit ≤ 0) is UNLIMITED — `run` calls `fn` immediately,
+ * so an empty limits map is a zero-overhead pass-through (the "no concurrency config" default).
+ */
+export declare class KeyedSemaphore {
+    private readonly limits;
+    private readonly inFlight;
+    private readonly waiters;
+    constructor(limits?: Record<string, number>);
+    /** Whether this semaphore constrains anything at all (empty/limitless → no-op fast path). */
+    get active(): boolean;
+    private limitFor;
+    acquire(key: string): Promise<void>;
+    release(key: string): void;
+    /** Acquire a slot for `key`, run `fn`, and always release — even on throw. */
+    run<T>(key: string, fn: () => Promise<T>): Promise<T>;
+}

package/dist/util/semaphore.js

@@ -0,0 +1,60 @@
+/**
+ * A tiny keyed async semaphore (Phase 19). Each key has an independent concurrency limit; `run(key, fn)`
+ * waits until a slot for that key is free, runs `fn`, and releases the slot even if `fn` throws. Waiters are
+ * served FIFO. A key with no configured limit (or a limit ≤ 0) is UNLIMITED — `run` calls `fn` immediately,
+ * so an empty limits map is a zero-overhead pass-through (the "no concurrency config" default).
+ */
+export class KeyedSemaphore {
+    limits;
+    inFlight = new Map();
+    waiters = new Map();
+    constructor(limits = {}) {
+        this.limits = limits;
+    }
+    /** Whether this semaphore constrains anything at all (empty/limitless → no-op fast path). */
+    get active() {
+        return Object.values(this.limits).some((n) => n > 0);
+    }
+    limitFor(key) {
+        const n = this.limits[key];
+        return n !== undefined && n > 0 ? n : undefined;
+    }
+    async acquire(key) {
+        const limit = this.limitFor(key);
+        if (limit === undefined)
+            return; // unlimited
+        const cur = this.inFlight.get(key) ?? 0;
+        if (cur < limit) {
+            this.inFlight.set(key, cur + 1);
+            return;
+        }
+        await new Promise((resolve) => {
+            const q = this.waiters.get(key) ?? [];
+            q.push(resolve);
+            this.waiters.set(key, q);
+        });
+        // Resumed by release(), which handed its slot directly to us — the in-flight count is unchanged.
+    }
+    release(key) {
+        const limit = this.limitFor(key);
+        if (limit === undefined)
+            return; // unlimited — nothing was counted
+        const q = this.waiters.get(key);
+        if (q && q.length) {
+            const next = q.shift();
+            next(); // hand the slot to the next waiter; count stays at the limit
+            return;
+        }
+        this.inFlight.set(key, Math.max(0, (this.inFlight.get(key) ?? 1) - 1));
+    }
+    /** Acquire a slot for `key`, run `fn`, and always release — even on throw. */
+    async run(key, fn) {
+        await this.acquire(key);
+        try {
+            return await fn();
+        }
+        finally {
+            this.release(key);
+        }
+    }
+}

package/package.json

@@ -1,13 +1,28 @@
 {
   "name": "ai-runtime-engine",
-  "version": "1.2.0",
-  "description": "AI Runtime — a provider-agnostic AI runtime and orchestration platform. Point it at whatever AI providers you have; it routes each task to the best available model. Ships the `ai-runtime` CLI and the `Runtime`/`AI` library API.",
+  "version": "2.7.0",
+  "description": "AI Runtime \u2014 a provider-agnostic AI runtime and orchestration platform. Point it at whatever AI providers you have; it routes each task to the best available model. Ships the `ai-runtime` CLI and the `Runtime`/`AI` library API.",
   "type": "module",
   "license": "ISC",
   "author": "pavan",
   "keywords": [
-    "ai", "llm", "ai-runtime", "runtime", "orchestration", "router", "provider-agnostic", "agent",
-    "openai", "gemini", "groq", "anthropic", "ollama", "openrouter", "mcp", "cli", "typescript"
+    "ai",
+    "llm",
+    "ai-runtime",
+    "runtime",
+    "orchestration",
+    "router",
+    "provider-agnostic",
+    "agent",
+    "openai",
+    "gemini",
+    "groq",
+    "anthropic",
+    "ollama",
+    "openrouter",
+    "mcp",
+    "cli",
+    "typescript"
   ],
   "engines": {
     "node": ">=22"
@@ -43,11 +58,11 @@
   "scripts": {
     "build": "tsc -p tsconfig.build.json",
     "typecheck": "tsc --noEmit",
-    "test": "node --import tsx --test \"tests/**/*.test.ts\"",
-    "test:unit": "node --import tsx --test \"tests/unit/**/*.test.ts\"",
-    "test:integration": "node --import tsx --test \"tests/integration/**/*.test.ts\"",
-    "test:contract": "node --import tsx --test \"tests/contract/**/*.test.ts\"",
-    "test:chaos": "node --import tsx --test \"tests/chaos/**/*.test.ts\"",
+    "test": "node --import tsx --test --test-timeout=120000 \"tests/**/*.test.ts\"",
+    "test:unit": "node --import tsx --test --test-timeout=120000 \"tests/unit/**/*.test.ts\"",
+    "test:integration": "node --import tsx --test --test-timeout=120000 \"tests/integration/**/*.test.ts\"",
+    "test:contract": "node --import tsx --test --test-timeout=120000 \"tests/contract/**/*.test.ts\"",
+    "test:chaos": "node --import tsx --test --test-timeout=120000 \"tests/chaos/**/*.test.ts\"",
     "cli": "node --import tsx src/cli/cli.ts",
     "example:fallback": "node --import tsx examples/fallback.ts",
     "example:minimal": "node --import tsx examples/minimal.ts",