ai-runtime-engine 1.2.0 → 2.7.0

package/dist/runtime/types.d.ts

@@ -8,6 +8,8 @@ import type { CompileMetrics, ContextValidation } from '../context/compiler.js';
 import type { PermissionPolicy } from './policy.js';
 import type { ExecutionPlan } from '../orchestration/plan.js';
 import type { ComparisonPin, ComparisonResult } from '../comparison/comparison.js';
+import type { MissingCapabilityReport } from '../capabilities/capability.js';
+import type { AgentDefinition } from '../agents/definition.js';
 export declare const RUNTIME_MODES: readonly ["auto", "chat", "plan", "execute", "orchestrate", "agent", "compare", "debug"];
 export type RuntimeMode = (typeof RUNTIME_MODES)[number];
 /** A mode that can actually run — never 'auto' (auto resolves TO one of these). */
@@ -39,7 +41,7 @@ export interface ArtifactRef {
     metadata?: Record<string, unknown>;
 }
 /** Task-level status. `ok` (on RuntimeResult) is whether the Runtime OP succeeded; this is whether the TASK is done/waiting. */
-export type RuntimeStatus = 'completed' | 'waiting_for_clarification' | 'waiting_for_approval' | 'failed';
+export type RuntimeStatus = 'completed' | 'waiting_for_clarification' | 'waiting_for_approval' | 'waiting_for_budget' | 'failed';
 export interface Clarification {
     question: string;
     options?: string[];
@@ -48,9 +50,13 @@ export interface RuntimeSettings {
     /** Project default mode. 'auto' means "always detect". */
     defaultMode?: RuntimeMode;
     defaultStrategy?: Strategy;
-    /** Context-compilation settings (token budget for the compiled model context). */
+    /** Context-compilation settings. `maxTokens` bounds the compiled context; `verifyLoss` (Phase 16) adds
+     *  a model check for task-critical loss (appended to `validation.checks`, never blocks); `summarize`
+     *  (Phase 16) abstractively shrinks over-budget non-critical blocks before compiling. Both default off. */
     context?: {
         maxTokens?: number;
+        verifyLoss?: boolean;
+        summarize?: boolean;
     };
     /** Project exclude/prefer routing (merged with env + per-run; EXCLUDE hard, PREFER soft). */
     routing?: RoutingPreferences;
@@ -60,9 +66,83 @@ export interface RuntimeSettings {
         packages?: string[];
         autoload?: boolean;
     };
+    /** Semantic memory retrieval (Phase 14). Absent → BM25 keyword retrieval (the default). `local` uses the
+     *  zero-dep HashEmbedder; `openai-compatible` calls a `{baseUrl}/embeddings` endpoint (key by env NAME). */
+    embedding?: {
+        provider: 'local' | 'openai-compatible';
+        baseUrl?: string;
+        apiKeyEnv?: string;
+        model?: string;
+    };
+    /** Intent classification (Phase 15). `aiFallback: true` consults one model call ONLY when the offline
+     *  heuristic is ambiguous; the heuristic stays the default and any model failure degrades back to it. */
+    intent?: {
+        aiFallback?: boolean;
+    };
+    /** Organization identity (Phase 17). When set, the `organization` memory scope becomes available — a
+     *  store above user/project/repository, shared across every project/repo that configures the same name.
+     *  Absent → the scope is unavailable and `remember({scope:'organization'})` errors clearly. */
+    organization?: string;
+    /** Encryption at rest (Phase 18). `encrypt: true` transparently AES-256-GCM-encrypts every store file;
+     *  the key is resolved from the env var NAMED by `keyEnv` (never a value). Missing key ⇒ a hard CONFIG
+     *  error at load. Absent → plaintext store (the default); a mixed store reads pre-encryption files fine. */
+    storage?: {
+        encrypt: boolean;
+        keyEnv: string;
+    };
+    /** Action capabilities (Phase 3.1/3.3). `catalog` enriches the planner catalog (default off);
+     *  `planning` (3.3, default OFF) derives the capabilities a goal needs BEFORE planning — offline BM25
+     *  first, one model call only when that finds nothing AND no call budget is set AND this is not a dry
+     *  run — resolves them against the run's permissions, and reports gaps. ADVISORY: it never blocks a
+     *  run and never grants anything, and with it off the planner prompt and every result field are
+     *  byte-identical. `aliases.<curatedId> = <providerId>` CLAIMS a curated id for a provider;
+     *  `pins.<capabilityId> = <providerId>` SELECTS among already-eligible providers. */
+    capabilities?: {
+        catalog?: boolean;
+        planning?: boolean;
+        aliases?: Record<string, string>;
+        pins?: Record<string, string>;
+    };
+    /** Concurrency caps (Phase 19). `maxParallelSteps` is the orchestrator's batch bound (config rung under
+     *  the per-run override); `perTool`/`perSkill` cap concurrent uses of a given tool/skill within that batch;
+     *  `perProvider` caps concurrent calls to a given provider across the router (bites under fan-out). */
+    concurrency?: {
+        maxParallelSteps?: number;
+        perTool?: Record<string, number>;
+        perSkill?: Record<string, number>;
+        perProvider?: Record<string, number>;
+        perAgent?: Record<string, number>;
+    };
+    /** Multi-agent core (Phase 3.4). Absent ⇒ agent execution is entirely inert: every prompt, every
+     *  OrchestrateInput key, every observation key, and every rendered plan line is byte-identical to
+     *  2.6.0. `definitions` are operator-authored ceilings; the per-task caps here are defaults a
+     *  definition may only LOWER. `maxInnerCalls` is both the budget reservation an agent step costs and
+     *  the worker's hard inner-model-call ceiling. */
+    agents?: {
+        enabled?: boolean;
+        maxToolCalls?: number;
+        maxDurationMs?: number;
+        maxInnerCalls?: number;
+        definitions?: Record<string, AgentDefinition>;
+    };
+}
+/** One user-added MCP server (Phase 3.2). `tokenEnv` names an env var; values live only in `.env`. */
+export interface McpServerSettings {
+    transport: 'stdio' | 'http';
+    url?: string;
+    command?: string;
+    args?: string[];
+    tokenEnv?: string;
+    enabled?: boolean;
+    timeoutMs?: number;
+    capabilities?: Record<string, string[]>;
 }
 export interface RuntimeConfig {
     runtime?: RuntimeSettings;
+    /** MCP servers to connect (Phase 3.2). Absent ⇒ MCP is entirely inert. */
+    mcp?: {
+        servers?: Record<string, McpServerSettings>;
+    };
     /** Tool permission grants (deny-by-default for write/exec; see PermissionPolicy). */
     permissions?: PermissionPolicy;
     /** The existing router configuration (providers, strategy, learning, verification, budget, policy, tasks…). */
@@ -89,6 +169,12 @@ export interface RuntimeRunInput {
     };
     /** Dry-run: plan + report what WOULD happen, performing zero mutations (plan/execute/orchestrate). */
     dryRun?: boolean;
+    /** Stream the answer token-by-token in chat mode: emits `response.delta` lifecycle events (Phase 13).
+     *  Text output only; ignored for JSON output and for dry runs. */
+    stream?: boolean;
+    /** Phase 22: when the plan exceeds the call budget, run the phases that fit and pause resumably instead
+     *  of the default notify-and-wait. Orchestration modes only. */
+    partial?: boolean;
     /** Caller idempotency identity (dedup enforced from Phase 7). */
     requestId?: string;
     /** Per-run exclude/prefer routing (highest precedence; merged with config + env). */
@@ -116,9 +202,12 @@ export interface RuntimeResult {
     runId: string;
     mode: ModeResolution;
     status: RuntimeStatus;
+    /** `streamed` is true when `text` was already delivered via `response.delta` events (Phase 13) — a
+     *  renderer that showed the deltas live should not reprint it. */
     response?: {
         text?: string;
         json?: unknown;
+        streamed?: boolean;
     };
     /** Present when the runtime needs the user to disambiguate. Never a failure. */
     clarification?: Clarification;
@@ -127,6 +216,9 @@ export interface RuntimeResult {
     error?: RouterErrorInfo;
     /** Artifact references produced by this run (empty until the Artifact Store lands in Phase 7). */
     artifacts: ArtifactRef[];
+    /** Structured capability gaps when a plan referenced something unavailable (Phase 3.1). Additive:
+     *  present only when a gap was detected; `status`/`error` semantics are unchanged. */
+    capabilityGaps?: MissingCapabilityReport;
     /** What memory was retrieved into context and/or captured this run (Phase 3). */
     memory?: MemoryTrace;
     /** How the model context was compiled this run: metrics + loss validation (Phase 4). */

package/dist/skills/manifest.d.ts

@@ -5,6 +5,7 @@
  * the permission-gated tool layer and whose validate() confirms every step produced evidence (a tool
  * `ok`). Anything richer than composing tools belongs in a JS-module skill instead.
  */
+import type { ActionCapabilityDecl } from '../capabilities/capability.js';
 import type { Skill } from './skill.js';
 export interface ManifestStep {
     /** A registered tool id (filesystem, shell, git, or a user-registered tool). */
@@ -19,6 +20,8 @@ export interface SkillManifest {
     name: string;
     description: string;
     runtimeCompatibility?: string;
+    /** ACTION capabilities this skill provides (Phase 3.1). Advisory metadata, never authorization. */
+    provides?: ActionCapabilityDecl[];
     steps: ManifestStep[];
 }
 /** Validate an arbitrary parsed object as a SkillManifest. Returns the manifest or a reason it is invalid. */

package/dist/skills/manifest.js

@@ -5,6 +5,7 @@
  * the permission-gated tool layer and whose validate() confirms every step produced evidence (a tool
  * `ok`). Anything richer than composing tools belongs in a JS-module skill instead.
  */
+import { CURATED_ID_RE, NAMESPACED_ID_RE } from '../capabilities/capability.js';
 /** Validate an arbitrary parsed object as a SkillManifest. Returns the manifest or a reason it is invalid. */
 export function parseManifest(raw) {
     if (!raw || typeof raw !== 'object' || Array.isArray(raw))
@@ -25,6 +26,27 @@ export function parseManifest(raw) {
             return { error: `manifest.steps[${i}].tool must be a tool id` };
         steps.push({ tool: step.tool, ...(typeof step.description === 'string' ? { description: step.description } : {}), ...('input' in step ? { input: step.input } : {}) });
     }
+    // Phase 3.1: optional `provides:` — a declaration that cannot be honored must be loud.
+    let provides;
+    if ('provides' in o && o.provides !== undefined) {
+        if (!Array.isArray(o.provides))
+            return { error: 'manifest.provides must be an array' };
+        const out = [];
+        for (const [i, raw] of o.provides.entries()) {
+            if (!raw || typeof raw !== 'object' || Array.isArray(raw))
+                return { error: `manifest.provides[${i}] must be a mapping` };
+            const d = raw;
+            const id = typeof d.id === 'string' ? d.id.trim() : '';
+            if (!id || !(CURATED_ID_RE.test(id) || NAMESPACED_ID_RE.test(id)))
+                return { error: `manifest.provides[${i}].id must be a capability id ([a-z0-9_] or tool:/skill:/mcp: prefixed)` };
+            if (d.effects !== undefined) {
+                if (!Array.isArray(d.effects) || !d.effects.every((e) => e === 'read' || e === 'write'))
+                    return { error: `manifest.provides[${i}].effects must be an array of 'read' | 'write'` };
+            }
+            out.push({ id, ...(Array.isArray(d.effects) ? { effects: d.effects } : {}), ...(typeof d.description === 'string' ? { description: d.description } : {}) });
+        }
+        provides = out;
+    }
     return {
         manifest: {
             id: o.id,
@@ -32,6 +54,7 @@ export function parseManifest(raw) {
             name: o.name,
             description: o.description,
             ...(typeof o.runtimeCompatibility === 'string' ? { runtimeCompatibility: o.runtimeCompatibility } : {}),
+            ...(provides ? { provides } : {}),
             steps,
         },
     };
@@ -45,6 +68,7 @@ export function manifestToSkill(m, sourcePath) {
         name: m.name,
         description: m.description,
         ...(m.runtimeCompatibility ? { runtimeCompatibility: m.runtimeCompatibility } : {}),
+        ...(m.provides ? { provides: m.provides } : {}),
         tools,
         async plan() {
             return { steps: m.steps.map((s) => ({ description: s.description ?? `run ${s.tool}`, tool: s.tool })) };

package/dist/skills/registry.d.ts

@@ -1,12 +1,27 @@
-/** A registry of skills, keyed by id, with a simple capability/tool matcher. */
+/**
+ * A registry of skills, keyed by id, with a simple tool matcher.
+ *
+ * An optional change listener (Phase 3.1) lets the Runtime ingest ACTION-capability declarations at the
+ * one real registration choke point — builtins, autoloaded manifests, npm skill packs, and user
+ * `registerSkill` all pass through `register()`. The zero-arg constructor is preserved (public API).
+ */
 import type { Skill } from './skill.js';
 export interface MatchCriteria {
     /** Tool ids currently registered — a skill matches only if all its required tools are present. */
     tools?: string[];
 }
+export interface SkillRegistryListener {
+    onRegister?: (skill: Skill) => void;
+    onUnregister?: (id: string) => void;
+}
 export declare class SkillRegistry {
     private readonly skills;
+    private listener;
+    /** Attach the change listener (called once by the Runtime before builtin registration). */
+    attach(listener: SkillRegistryListener): this;
     register(skill: Skill): this;
+    /** Remove a skill (and, via the listener, its capability declarations). */
+    unregister(id: string): boolean;
     get(id: string): Skill | undefined;
     has(id: string): boolean;
     list(): Skill[];

package/dist/skills/registry.js

@@ -1,10 +1,30 @@
-/** A registry of skills, keyed by id, with a simple capability/tool matcher. */
+/**
+ * A registry of skills, keyed by id, with a simple tool matcher.
+ *
+ * An optional change listener (Phase 3.1) lets the Runtime ingest ACTION-capability declarations at the
+ * one real registration choke point — builtins, autoloaded manifests, npm skill packs, and user
+ * `registerSkill` all pass through `register()`. The zero-arg constructor is preserved (public API).
+ */
 export class SkillRegistry {
     skills = new Map();
+    listener = {};
+    /** Attach the change listener (called once by the Runtime before builtin registration). */
+    attach(listener) {
+        this.listener = listener ?? {};
+        return this;
+    }
     register(skill) {
         this.skills.set(skill.id, skill);
+        this.listener.onRegister?.(skill);
         return this;
     }
+    /** Remove a skill (and, via the listener, its capability declarations). */
+    unregister(id) {
+        const had = this.skills.delete(id);
+        if (had)
+            this.listener.onUnregister?.(id);
+        return had;
+    }
     get(id) {
         return this.skills.get(id);
     }

package/dist/skills/skill.d.ts

@@ -9,6 +9,7 @@ import type { AI } from '../plugin/ai.js';
 import type { CapabilityRequirement } from '../types.js';
 import type { ArtifactRef } from '../runtime/types.js';
 import type { PermissionPolicy } from '../runtime/policy.js';
+import type { ActionCapabilityDecl } from '../capabilities/capability.js';
 import type { ToolResult } from '../tools/tool.js';
 export interface SkillContext {
     input: unknown;
@@ -50,8 +51,12 @@ export interface Skill {
     runtimeCompatibility?: string;
     name: string;
     description: string;
-    /** Model capabilities the skill needs from whatever model AI.run selects. */
+    /** MODEL capabilities required FROM the routed model (unrelated to action capabilities — see
+     *  `provides`). Advisory in Phase 5; consumed by the router when threaded into a request. */
     capabilities?: CapabilityRequirement[];
+    /** ACTION capabilities this skill provides (Phase 3.1). Advisory metadata, never authorization.
+     *  Absent ⇒ one inferred `skill:<id>` entry. A declared curated id is namespaced to this skill. */
+    provides?: ActionCapabilityDecl[];
     /** Tool ids the skill uses (matched against the registered tools). */
     tools?: string[];
     /** Other skill ids this skill depends on. */

package/dist/store/area.d.ts

@@ -8,6 +8,15 @@ export interface IntegrityIssue {
     problem: 'unreadable' | 'checksum-mismatch' | 'invalid-json';
     detail?: string;
 }
+/**
+ * Transforms the STORED STRING of each file (Phase 18). With a codec, `FileArea` writes `encode(json)` and
+ * reads `decode(raw)` before parsing — the only hook encryption needs. `decode` must pass a non-envelope
+ * string through unchanged (mixed/legacy stores) and may throw on an undecryptable one (→ corruption path).
+ */
+export interface ContentCodec {
+    encode(plain: string): string;
+    decode(stored: string): string;
+}
 export interface Area {
     readonly enabled: boolean;
     /** Strict read: throws on corruption (use for an explicit single-record read). */
@@ -23,10 +32,15 @@ export interface Area {
 }
 export declare class FileArea implements Area {
     private readonly dir;
+    private readonly codec?;
     readonly enabled = true;
     private ensured;
     private counter;
-    constructor(dir: string);
+    constructor(dir: string, codec?: ContentCodec | undefined);
+    /** Transform stored bytes → plaintext string. Without a codec this is the identity. */
+    private decode;
+    /** Transform a plaintext string → stored bytes. Without a codec this is the identity. */
+    private encode;
     private ensure;
     private jsonPath;
     private logPath;

package/dist/store/area.js

@@ -19,11 +19,21 @@ function checksum(data) {
 }
 export class FileArea {
     dir;
+    codec;
     enabled = true;
     ensured = false;
     counter = 0;
-    constructor(dir) {
+    constructor(dir, codec) {
         this.dir = dir;
+        this.codec = codec;
+    }
+    /** Transform stored bytes → plaintext string. Without a codec this is the identity. */
+    decode(raw) {
+        return this.codec ? this.codec.decode(raw) : raw;
+    }
+    /** Transform a plaintext string → stored bytes. Without a codec this is the identity. */
+    encode(plain) {
+        return this.codec ? this.codec.encode(plain) : plain;
     }
     ensure() {
         if (!this.ensured) {
@@ -41,7 +51,7 @@ export class FileArea {
         this.ensure();
         this.counter += 1;
         const tmp = `${path}.tmp-${process.pid}-${this.counter}`;
-        writeFileSync(tmp, contents);
+        writeFileSync(tmp, this.encode(contents));
         renameSync(tmp, path);
     }
     readJson(id) {
@@ -49,7 +59,7 @@ export class FileArea {
         const path = this.jsonPath(id);
         if (!existsSync(path))
             return undefined;
-        const wrapper = JSON.parse(readFileSync(path, 'utf8'));
+        const wrapper = JSON.parse(this.decode(readFileSync(path, 'utf8')));
         if (wrapper.checksum !== checksum(wrapper.data))
             throw new Error(`integrity check failed for ${path}`);
         return wrapper.data;
@@ -85,7 +95,8 @@ export class FileArea {
     appendLine(id, obj) {
         assertId(id);
         this.ensure();
-        appendFileSync(this.logPath(id), JSON.stringify(obj) + '\n');
+        // Each JSONL line is encrypted independently (its own IV), so appends stay append-only.
+        appendFileSync(this.logPath(id), this.encode(JSON.stringify(obj)) + '\n');
     }
     readLines(id) {
         assertId(id);
@@ -97,10 +108,10 @@ export class FileArea {
             if (!line)
                 continue;
             try {
-                out.push(JSON.parse(line));
+                out.push(JSON.parse(this.decode(line)));
             }
             catch {
-                /* skip a corrupt line rather than failing the whole log (surfaced by check()) */
+                /* skip a corrupt/undecryptable line rather than failing the whole log (surfaced by check()) */
             }
         }
         return out;
@@ -117,7 +128,7 @@ export class FileArea {
             }
             if (f.endsWith('.json')) {
                 try {
-                    const wrapper = JSON.parse(readFileSync(path, 'utf8'));
+                    const wrapper = JSON.parse(this.decode(readFileSync(path, 'utf8')));
                     if (wrapper.checksum !== checksum(wrapper.data))
                         issues.push({ file: path, problem: 'checksum-mismatch' });
                 }
@@ -129,7 +140,7 @@ export class FileArea {
                 const lines = readFileSync(path, 'utf8').split('\n').filter(Boolean);
                 lines.forEach((line, i) => {
                     try {
-                        JSON.parse(line);
+                        JSON.parse(this.decode(line));
                     }
                     catch {
                         issues.push({ file: path, problem: 'invalid-json', detail: `line ${i + 1}` });

package/dist/store/crypto.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Transparent encryption at rest (Phase 18) — AES-256-GCM via `node:crypto` (zero new deps). A `ContentCodec`
+ * transforms the STORED STRING of a store file: `encode` wraps plaintext as a self-identifying envelope
+ * `aienc1:<base64(iv|tag|ciphertext)>`; `decode` reverses it. `decode` is deliberately lenient on the way IN —
+ * a string WITHOUT the `aienc1:` prefix is returned unchanged, so a store that predates encryption keeps
+ * reading after it is enabled (new writes are always encrypted). A wrong key / tampered payload makes `decode`
+ * THROW, which the store maps onto its existing corruption path (soft-skip in bulk reads, reported by check()).
+ *
+ * SECURITY: the derived key is a Buffer held only inside the codec closure; it is never serialized, logged, or
+ * placed in an error. The AES key is sha256(secret), so the raw secret length is irrelevant.
+ */
+import type { ContentCodec } from './area.js';
+export declare const ENVELOPE_PREFIX = "aienc1:";
+/** Derive the 32-byte AES-256 key from an arbitrary secret (sha256 → fixed length, secret length irrelevant). */
+export declare function deriveKey(secret: string): Buffer;
+/** Encrypt a UTF-8 string into the self-identifying `aienc1:` envelope. A fresh random IV per call. */
+export declare function encryptString(plain: string, key: Buffer): string;
+/** Decrypt an `aienc1:` envelope; a string without the prefix is returned unchanged (mixed/legacy store). */
+export declare function decryptString(stored: string, key: Buffer): string;
+/** Build the codec `FileArea` uses to encrypt/decrypt its file contents. */
+export declare function makeCodec(key: Buffer): ContentCodec;

package/dist/store/crypto.js

@@ -0,0 +1,49 @@
+/**
+ * Transparent encryption at rest (Phase 18) — AES-256-GCM via `node:crypto` (zero new deps). A `ContentCodec`
+ * transforms the STORED STRING of a store file: `encode` wraps plaintext as a self-identifying envelope
+ * `aienc1:<base64(iv|tag|ciphertext)>`; `decode` reverses it. `decode` is deliberately lenient on the way IN —
+ * a string WITHOUT the `aienc1:` prefix is returned unchanged, so a store that predates encryption keeps
+ * reading after it is enabled (new writes are always encrypted). A wrong key / tampered payload makes `decode`
+ * THROW, which the store maps onto its existing corruption path (soft-skip in bulk reads, reported by check()).
+ *
+ * SECURITY: the derived key is a Buffer held only inside the codec closure; it is never serialized, logged, or
+ * placed in an error. The AES key is sha256(secret), so the raw secret length is irrelevant.
+ */
+import { createHash, randomBytes, createCipheriv, createDecipheriv } from 'node:crypto';
+export const ENVELOPE_PREFIX = 'aienc1:';
+const IV_LEN = 12; // GCM standard nonce
+const TAG_LEN = 16; // GCM auth tag
+/** Derive the 32-byte AES-256 key from an arbitrary secret (sha256 → fixed length, secret length irrelevant). */
+export function deriveKey(secret) {
+    return createHash('sha256').update(secret).digest();
+}
+/** Encrypt a UTF-8 string into the self-identifying `aienc1:` envelope. A fresh random IV per call. */
+export function encryptString(plain, key) {
+    const iv = randomBytes(IV_LEN);
+    const cipher = createCipheriv('aes-256-gcm', key, iv);
+    const ct = Buffer.concat([cipher.update(plain, 'utf8'), cipher.final()]);
+    const tag = cipher.getAuthTag();
+    return ENVELOPE_PREFIX + Buffer.concat([iv, tag, ct]).toString('base64');
+}
+/** Decrypt an `aienc1:` envelope; a string without the prefix is returned unchanged (mixed/legacy store). */
+export function decryptString(stored, key) {
+    if (!stored.startsWith(ENVELOPE_PREFIX))
+        return stored; // plaintext (pre-encryption) record — read as-is
+    const buf = Buffer.from(stored.slice(ENVELOPE_PREFIX.length), 'base64');
+    if (buf.length < IV_LEN + TAG_LEN)
+        throw new Error('encrypted record is truncated');
+    const iv = buf.subarray(0, IV_LEN);
+    const tag = buf.subarray(IV_LEN, IV_LEN + TAG_LEN);
+    const ct = buf.subarray(IV_LEN + TAG_LEN);
+    const decipher = createDecipheriv('aes-256-gcm', key, iv);
+    decipher.setAuthTag(tag);
+    // GCM `final()` throws on a wrong key or tampered ciphertext — surfaces as store corruption to the caller.
+    return Buffer.concat([decipher.update(ct), decipher.final()]).toString('utf8');
+}
+/** Build the codec `FileArea` uses to encrypt/decrypt its file contents. */
+export function makeCodec(key) {
+    return {
+        encode: (plain) => encryptString(plain, key),
+        decode: (stored) => decryptString(stored, key),
+    };
+}

package/dist/store/paths.d.ts

@@ -5,7 +5,7 @@
  * `repository` identity (the git repo root) backs repository-scoped memory across those packages.
  */
 /** Where a memory record physically lives. */
-export type StoreScope = 'user' | 'project' | 'repository';
+export type StoreScope = 'user' | 'project' | 'repository' | 'organization';
 export declare function resolveHome(env?: NodeJS.ProcessEnv): string;
 /** Walk up from a directory to find the git repo root (dir containing `.git`). Undefined if none. */
 export declare function findRepoRoot(start: string): string | undefined;
@@ -13,3 +13,7 @@ export declare function findRepoRoot(start: string): string | undefined;
 export declare function projectId(root: string, name?: string): string;
 /** Stable id for the enclosing git repository (falls back to the project id when not a repo). */
 export declare function repositoryId(root: string, name?: string): string;
+/** Stable id for a configured organization name: `<slug>-<hash>`. Org identity is config-supplied (an org
+ *  has no filesystem source), so it is derived from the name alone — the same name yields the same store,
+ *  shared across every project/repo that configures it. */
+export declare function organizationId(name: string): string;

package/dist/store/paths.js

@@ -46,3 +46,9 @@ export function repositoryId(root, name) {
         return projectId(root, name);
     return `${slug(basename(repo))}-${hash8(repo)}`;
 }
+/** Stable id for a configured organization name: `<slug>-<hash>`. Org identity is config-supplied (an org
+ *  has no filesystem source), so it is derived from the name alone — the same name yields the same store,
+ *  shared across every project/repo that configures it. */
+export function organizationId(name) {
+    return `${slug(name)}-${hash8(name)}`;
+}

package/dist/store/store.d.ts

@@ -4,7 +4,7 @@
  * per-project lock, and an aggregate integrity check. In stateless mode every area is a NullArea.
  */
 import type { Clock } from '../util/clock.js';
-import type { Area, IntegrityIssue } from './area.js';
+import type { Area, IntegrityIssue, ContentCodec } from './area.js';
 import type { StoreScope } from './paths.js';
 export declare const STORE_VERSION = 1;
 export interface RuntimeStoreOptions {
@@ -14,31 +14,43 @@ export interface RuntimeStoreOptions {
     clock?: Clock;
     /** When false, a stateless (in-memory / no-op) store is returned. */
     enabled?: boolean;
+    /** Organization identity (config-supplied). When set, the `organization` memory scope becomes available. */
+    organization?: string;
+    /** Transparent encryption (Phase 18). When set, every file area encrypts/decrypts its contents. */
+    cipher?: ContentCodec;
 }
 export interface StorePaths {
     home: string;
     project: string;
     repository: string;
     user: string;
+    /** Present only when an organization is configured. */
+    organization?: string;
 }
 export declare class RuntimeStore {
     readonly enabled: boolean;
     readonly projectId: string;
     readonly repositoryId: string;
+    /** Present only when an organization is configured — the availability signal for the `organization` scope. */
+    readonly organizationId?: string;
     private readonly clock;
     private readonly home;
     private readonly projectDir;
     private readonly repoDir;
     private readonly userDir;
+    private readonly orgDir?;
+    private readonly cipher?;
     private readonly areas;
     private metaStamped;
     constructor(options: RuntimeStoreOptions);
     paths(): StorePaths;
     private area;
-    /** Memory area for a physical scope. */
+    /** Memory area for a physical scope. `organization` requires a configured org (guarded by callers). */
     memory(scope: StoreScope): Area;
     conversations(): Area;
     indexes(): Area;
+    /** MCP state: dynamic servers, enable/disable overrides, and per-server tool caches (Phase 3.2). */
+    mcp(): Area;
     cache(): Area;
     executions(): Area;
     artifacts(): Area;
@@ -54,6 +66,6 @@ export declare class RuntimeStore {
      * otherwise proceeds anyway (advisory). Hard mutual exclusion for executions is a Phase 7 lease.
      */
     withLock<T>(fn: () => T, staleMs?: number): T;
-    /** Aggregate integrity check across the project areas. */
+    /** Aggregate integrity check across the project areas (plus the org area when configured). */
     check(): IntegrityIssue[];
 }