operon-agents 0.1.0-alpha.2 → 0.1.0-alpha.21

package/dist/extensions/runtime.js

@@ -1,6 +1,5 @@
-import { randomBytes } from "node:crypto";
 import { ServiceUnavailableError, isProbeProperty } from "./services.js";
-import { tagToolSource } from "operon-agents-core";
+import { appendAudit, tagToolSource } from "operon-agents-core";
 /** Decision points block the loop, so they get room to do real work (network, subprocess). */
 const DECISION_TIMEOUT_MS = 30_000;
 /** Observers must not become latency: a slow one is dropped, not waited on. */
@@ -12,37 +11,35 @@ const OBSERVE_EVENTS = new Set([
     // here is latency on every streamed token, so it gets the short budget.
     "provider.response",
 ]);
+/**
+ * One extension, running in one session. `extensionCapability` wraps it as that session's
+ * capability, so everything around the extension — assembly, hook isolation, attach and detach
+ * at a run boundary, its state and records — is the engine's, the same as for any capability.
+ * What is left here is the translation the extension API exists for: `api` registrations into
+ * capability parts, and the engine's decision points into the extension's event vocabulary.
+ */
 export class ExtensionRuntime {
-    definitions;
+    definition;
     handlers = new Map();
     tools = new Map();
-    /** Stable reference: `extensionsCapability` hands this array to the assembler, and `setup`
+    /** Stable reference: `extensionCapability` hands this array to the assembler, and `session`
      *  (which runs at openSession, before any run assembles) fills it in place. */
     injectors = [];
-    /** Slash commands by normalized name — surfaced to the session's registry via the
-     *  `sessionCommands()` duck protocol. Two extensions claiming one name fail closed. */
-    extCommands = new Map();
-    /** Host-facing control surfaces published via `api.expose`, by extension id. */
-    exposedHandles = new Map();
-    /** Records read path: open-time snapshot buckets (built lazily off the session's shared
-     *  memoized log read — zero extra traversal) + everything recorded this session. */
-    recordSnapshot;
-    recordWrites = new Map();
-    /** Per-extension teardown: setup's cleanup + every registration, undone in reverse. */
-    scopes = new Map();
-    /** Extensions whose contributions are currently honored. An id leaves on detach (and on
-     *  setup failure), which turns every `actions`/`api` closure the extension still holds
-     *  into a warn-and-noop — a detached extension must not keep steering the session. */
-    live = new Set();
-    /** Changes wait here until a quiet point: mid-run requests apply at the run's stop
-     *  boundary, so a turn never sees its toolset change underneath it. */
-    pending = [];
-    /** Serializes flushes so concurrent attach/detach apply strictly in submission order. */
-    flushChain = Promise.resolve();
-    memoryState = new Map();
+    /** Slash commands, filled in place by `api.registerCommand` — the capability's `commands`. */
+    commands = [];
+    /** The host-facing control surface published via `api.expose`. */
+    exposed;
+    /** `session()`'s cleanup plus every registration, undone in reverse. */
+    teardown;
+    /** False until `session` has run, and again once the extension is closed: every `actions` /
+     *  `api` closure it still holds turns into a warn-and-noop — a detached extension must not
+     *  keep steering the session. */
+    live = false;
+    /** The session binding: the services the capability DECLARED, plus the session's id/signal. */
     session;
     run;
-    /** The conversation shard the in-flight decision point belongs to; backs `actions.record`. */
+    /** The conversation shard the in-flight decision point belongs to — the address a
+     *  `compaction.before` handler is told about. */
     activeContext;
     /** Snapshot of the last assembled registry, refreshed once per turn by `filterTools`. */
     allToolNames = [];
@@ -51,210 +48,93 @@ export class ExtensionRuntime {
     reportingWarning = false;
     /** Harness reach. Absent when the capability is built standalone (bare Runner / tests). */
     host;
-    /** This session's per-session extension arguments, by extension id. A value of `false` means
-     *  "skip this extension for this session"; any other value is passed to `setup` as `params`. */
+    /** This session's argument for the extension (`createSession({ params: { [id]: … } })`). */
     params;
-    constructor(definitions, host, params = {}) {
-        this.host = host;
-        this.params = params;
-        const seen = new Set();
-        for (const definition of definitions) {
-            if (!definition.id.trim())
-                throw new Error("extension id must not be empty");
-            // Slug only, colons forbidden: records and state scope by the "extension:<id>:" prefix,
-            // so an id containing ":" would make one extension's bucket swallow another's.
-            if (!/^[A-Za-z0-9][A-Za-z0-9_.-]*$/.test(definition.id)) {
-                throw new Error(`extension id "${definition.id}" must be a slug ([A-Za-z0-9_.-], no colons)`);
-            }
-            if (seen.has(definition.id))
-                throw new Error(`duplicate extension id "${definition.id}"`);
-            seen.add(definition.id);
+    /** What `session.start` reports: `attach` for an extension added to a live session. */
+    startReason;
+    constructor(definition, options = {}) {
+        if (!definition.id.trim())
+            throw new Error("extension id must not be empty");
+        // Slug only, colons forbidden: records and state scope by the "extension:<id>:" prefix,
+        // so an id containing ":" would make one extension's bucket swallow another's.
+        if (!/^[A-Za-z0-9][A-Za-z0-9_.-]*$/.test(definition.id)) {
+            throw new Error(`extension id "${definition.id}" must be a slug ([A-Za-z0-9_.-], no colons)`);
         }
-        // A session that opted an extension out (`params[id] === false`) never carries it: not in
-        // the definition list, never set up, never reported as attached.
-        this.definitions = definitions.filter((definition) => params[definition.id] !== false);
+        this.definition = definition;
+        this.host = options.host;
+        this.params = options.params;
+        this.startReason = options.startReason ?? "open";
+    }
+    get id() {
+        return this.definition.id;
     }
     // ==========================================================================
     // Lifecycle
     // ==========================================================================
-    async open(ctx, reason = "open") {
-        this.session = ctx;
-        for (const definition of this.definitions) {
-            await this.setupExtension(definition);
-        }
+    /** Run `session` and fire `session.start`. Throws when `session` does — the capability is then
+     *  absent from the session, with nothing it registered left behind. */
+    async open(services, ctx) {
+        this.session = { ...ctx, ...services };
+        if (!(await this.setupExtension(this.definition)))
+            throw new Error(`extension "${this.id}" session() failed`);
         for (const registered of [...this.handlersFor("session.start")]) {
-            await this.invoke("session.start", registered, { ...this.sessionContext(registered.extensionId), reason });
+            await this.invoke("session.start", registered, { ...this.sessionContext(this.id), reason: this.startReason });
         }
+        if (this.startReason === "attach")
+            await this.logChange("attached");
     }
     attachRun(ctx) {
         this.run = ctx;
     }
-    async detachRun() {
+    detachRun() {
         this.run = undefined;
         this.activeContext = undefined;
-        // The run just ended — this is the quiet point mid-run attach/detach requests wait for.
-        await this.flushPending();
     }
+    /** Fire `session.end` while the handlers are still registered, then unwind everything. */
     async close(reason = "close") {
-        if (this.session) {
+        if (this.session && this.live) {
             for (const registered of [...this.handlersFor("session.end")]) {
-                await this.invoke("session.end", registered, { ...this.sessionContext(registered.extensionId), reason });
+                await this.invoke("session.end", registered, { ...this.sessionContext(this.id), reason });
             }
         }
-        for (const [id, scope] of [...this.scopes].reverse()) {
+        this.live = false;
+        const teardown = this.teardown;
+        this.teardown = undefined;
+        if (teardown) {
             try {
-                await scope();
+                await teardown();
             }
             catch (error) {
-                await this.warn(id, `teardown failed: ${messageOf(error)}`);
+                await this.warn(this.id, `teardown failed: ${messageOf(error)}`);
             }
         }
-        this.scopes.clear();
-        this.live.clear();
-        this.extCommands.clear();
-        this.exposedHandles.clear();
-        this.recordSnapshot = undefined;
-        this.recordWrites.clear();
-        for (const entry of this.pending.splice(0))
-            entry.reject(new Error("session closed"));
+        if (reason === "detach")
+            await this.logChange("detached");
+        this.commands.length = 0;
+        this.exposed = undefined;
         this.injectors.length = 0;
-        this.session = undefined;
-    }
-    // ==========================================================================
-    // Hot attach / detach — host API, applied at the next quiet point
-    // ==========================================================================
-    /**
-     * Add an extension to the live session. Resolves once its `setup` has run and its
-     * contributions are in place — with no run in flight that is immediately; mid-run it is
-     * the current run's stop boundary, so an in-flight turn never sees its registry change.
-     * Rejects on duplicate/empty id or when `setup` throws.
-     */
-    attach(definition) {
-        return this.submit({ kind: "attach", definition });
-    }
-    /** Ids of currently attached extensions — the reshape coordinator's affected-set probe. */
-    attachedIds() {
-        return [...this.live];
-    }
-    /** Currently attached extensions with what each declared it `uses` — the unload consumer scan. */
-    attachedExtensions() {
-        return this.definitions.filter((definition) => this.live.has(definition.id)).map((definition) => ({ id: definition.id, uses: definition.uses ?? [] }));
-    }
-    /** The duck protocol the session's command registry consumes: dynamic commands contributed
-     *  by attached extensions (`api.registerCommand`). */
-    sessionCommands() {
-        return [...this.extCommands.values()].map((entry) => entry.command);
-    }
-    /** The control surface `extensionId` published via `api.expose`; undefined when absent
-     *  (never attached, detached, or nothing exposed). */
-    exposedHandle(extensionId) {
-        return this.exposedHandles.get(extensionId);
+        // The session binding stays: a closure the extension stashed must still be able to say, into
+        // the event stream, that it was ignored because the extension is gone.
     }
-    /** Remove an extension: its `session.end` fires, then its whole scope is torn down. */
-    detach(id) {
-        return this.submit({ kind: "detach", id });
+    /** The control surface published via `api.expose`; undefined when nothing is (or it was
+     *  disposed, or the extension is closed). */
+    exposedHandle() {
+        return this.exposed;
     }
-    submit(change) {
-        return new Promise((resolve, reject) => {
-            this.pending.push({ ...change, resolve, reject });
-            if (this.run === undefined)
-                void this.flushPending();
-        });
-    }
-    flushPending() {
-        const next = this.flushChain.then(() => this.drainPending());
-        this.flushChain = next.catch(() => undefined);
-        return next;
-    }
-    async drainPending() {
-        while (this.pending.length > 0) {
-            const entry = this.pending.shift();
-            if (!entry)
-                break;
-            try {
-                if (entry.kind === "attach")
-                    await this.attachNow(entry.definition);
-                else
-                    await this.detachNow(entry.id);
-                entry.resolve();
-            }
-            catch (error) {
-                entry.reject(error);
-            }
-        }
-    }
-    async attachNow(definition) {
-        if (!definition.id.trim())
-            throw new Error("extension id must not be empty");
-        // Slug only, colons forbidden: records and state scope by the "extension:<id>:" prefix,
-        // so an id containing ":" would make one extension's bucket swallow another's.
-        if (!/^[A-Za-z0-9][A-Za-z0-9_.-]*$/.test(definition.id)) {
-            throw new Error(`extension id "${definition.id}" must be a slug ([A-Za-z0-9_.-], no colons)`);
-        }
-        if (this.params[definition.id] === false) {
-            throw new Error(`extension "${definition.id}" is opted out for this session (params["${definition.id}"] is false)`);
-        }
-        if (this.definitions.some((existing) => existing.id === definition.id)) {
-            throw new Error(`duplicate extension id "${definition.id}"`);
-        }
-        this.definitions.push(definition);
-        // Not open yet: `open()` will run setup with everything else.
-        if (!this.session)
-            return;
-        const ok = await this.setupExtension(definition);
-        if (!ok) {
-            const index = this.definitions.findIndex((existing) => existing.id === definition.id);
-            if (index >= 0)
-                this.definitions.splice(index, 1);
-            throw new Error(`extension "${definition.id}" setup failed`);
-        }
-        for (const registered of [...this.handlersFor("session.start")]) {
-            if (registered.extensionId !== definition.id)
-                continue;
-            await this.invoke("session.start", registered, { ...this.sessionContext(definition.id), reason: "attach" });
-        }
-        await this.logChange("attached", definition.id);
-    }
-    async detachNow(id) {
-        const index = this.definitions.findIndex((existing) => existing.id === id);
-        if (index < 0)
-            throw new Error(`unknown extension "${id}"`);
-        // Notify while its handlers are still registered.
-        if (this.session && this.live.has(id)) {
-            for (const registered of [...this.handlersFor("session.end")]) {
-                if (registered.extensionId !== id)
-                    continue;
-                await this.invoke("session.end", registered, { ...this.sessionContext(id), reason: "detach" });
-            }
-        }
-        this.definitions.splice(index, 1);
-        this.live.delete(id);
-        const scope = this.scopes.get(id);
-        this.scopes.delete(id);
-        if (scope) {
-            try {
-                await scope();
-            }
-            catch (error) {
-                await this.warn(id, `teardown failed: ${messageOf(error)}`);
-            }
-        }
-        if (this.session)
-            await this.logChange("detached", id);
-    }
-    /** Runs one extension's `setup` and files its scope. Failure ⇒ skipped, contributions undone. */
+    /** Runs one extension's `session` and files its scope. Failure ⇒ skipped, contributions undone. */
     async setupExtension(definition) {
-        const params = this.params[definition.id];
-        // A `create`-bearing definition reaches a session only after the harness ran its `create`
-        // and registered the result under the id. Not registered ⇒ it was handed to a session
-        // directly instead of being registered — a programming error, so it throws rather than
-        // being skipped.
-        if (definition.create !== undefined && this.host?.services?.has(definition.id) !== true) {
-            throw new Error(`extension "${definition.id}" has a create half but no service "${definition.id}" is registered — its create never ran. Register it in createHarness({ extensions }) or load it from extensionDir; a definition with create cannot be handed to a session directly`);
-        }
-        const shared = definition.create !== undefined ? this.serviceHandle(definition.id, definition.id) : undefined;
+        const params = this.params;
+        // A definition with a shared half reaches a session only after that half ran — the harness
+        // ran `harness` once and registered the result under the id. Not registered ⇒ it was handed
+        // to a session directly instead of being registered — a programming error, so it throws
+        // rather than being skipped.
+        const sharedHalf = definition.harness !== undefined;
+        if (sharedHalf && this.host?.services?.has(definition.id) !== true) {
+            throw new Error(`extension "${definition.id}" has a shared half but no service "${definition.id}" is reachable from this session — its harness half never ran. Register it in createHarness({ extensions }) or load it from extensionDir; a definition with a shared half cannot be handed to a session directly`);
+        }
+        const shared = sharedHalf ? this.serviceHandle(definition.id, definition.id) : undefined;
         const registrations = [];
-        this.live.add(definition.id);
+        this.live = true;
         try {
             // `uses`: checked at registration, re-checked here (a provider may have unloaded since)
             // and handed in resolved — an extension never looks a service up by name.
@@ -264,40 +144,41 @@ export class ExtensionRuntime {
                     throw new Error(`uses "${name}": no such service is registered`);
                 services[name] = this.serviceHandle(definition.id, name);
             }
-            const teardown = await definition.setup(this.apiFor(definition, registrations), { shared, params, services });
-            this.scopes.set(definition.id, async () => {
+            const teardown = await definition.session(this.apiFor(definition, registrations), { shared, params, services });
+            this.teardown = async () => {
                 if (teardown)
                     await teardown();
                 for (const dispose of [...registrations].reverse())
                     dispose();
-            });
+            };
             return true;
         }
         catch (error) {
-            this.live.delete(definition.id);
+            this.live = false;
             for (const dispose of [...registrations].reverse())
                 dispose();
-            await this.warn(definition.id, `setup failed; extension skipped: ${messageOf(error)}`);
+            await this.warn(definition.id, `session() failed; extension skipped: ${messageOf(error)}`);
             return false;
         }
     }
     /**
-     * Durable audit trail: replay needs "tool X only exists after record N" to reconstruct the
-     * capability timeline. Rides the `custom` record type — audit-only, ignored by reducers.
+     * Durable audit trail of when this extension joined or left the session — written to the
+     * session's audit shard, which nothing replays from.
      */
-    async logChange(kind, extensionId) {
+    async logChange(kind) {
+        const extensionId = this.id;
         const store = this.session?.store;
         if (!store)
             return;
         try {
-            await store.appendRecord({ type: "custom", name: `extensions.${kind}`, data: { extensionId } });
+            await appendAudit(store, { type: "custom", name: `extensions.${kind}`, data: { extensionId } });
         }
         catch (error) {
             await this.warn(extensionId, `failed to journal extension ${kind}: ${messageOf(error)}`);
         }
     }
     listTools() {
-        return [...this.tools.values()].map((entry) => entry.tool);
+        return [...this.tools.values()];
     }
     listInjectors() {
         return this.injectors;
@@ -447,75 +328,55 @@ export class ExtensionRuntime {
                 changed = true;
             }
         }
-        // Fold the provider-tier callbacks into the request pi-ai will actually send. They cannot be
-        // driven from here — pi-ai invokes them from inside its HTTP path — so the only way to reach
-        // them is to ride along on `providerOptions`.
-        const withProvider = this.withProviderHooks(current, origin);
-        if (withProvider !== undefined) {
-            current = withProvider;
-            changed = true;
-        }
         return changed ? { request: current } : undefined;
     }
     /**
-     * Attach `transformHeaders` / `onPayload` / `onResponse` when anything is listening. Returns
-     * `undefined` when nothing is, so a request with no provider-tier extensions is left byte-identical.
-     *
-     * These fire once per HTTP ATTEMPT, so a retry re-runs them — the contract tells handlers to be
-     * idempotent, and the runtime does not try to dedupe on their behalf.
+     * The capability's provider hooks — `provider.headers` / `payload` / `response`. The engine
+     * composes them into the request with every other capability's, so two extensions rewriting
+     * headers both take effect instead of the second replacing the first. They fire once per HTTP
+     * ATTEMPT, so a retry re-runs them — the contract tells handlers to be idempotent, and the
+     * runtime does not try to dedupe on their behalf.
      */
-    withProviderHooks(request, origin) {
-        const headerHandlers = this.handlersFor("provider.headers");
-        const payloadHandlers = this.handlersFor("provider.payload");
-        const responseHandlers = this.handlersFor("provider.response");
-        if (headerHandlers.length === 0 && payloadHandlers.length === 0 && responseHandlers.length === 0) {
-            return undefined;
-        }
-        const base = { turnId: origin.turnId, stepNumber: origin.stepNumber };
-        const providerOptions = { ...request.providerOptions };
-        if (headerHandlers.length > 0) {
-            providerOptions.transformHeaders = async (headers) => {
-                let current = headers;
-                for (const registered of headerHandlers) {
-                    const result = await this.invoke("provider.headers", registered, {
-                        ...this.eventContext(registered.extensionId, origin),
-                        ...base,
-                        headers: current,
-                    });
-                    if (result?.headers !== undefined)
-                        current = result.headers;
-                }
-                return current;
-            };
-        }
-        if (payloadHandlers.length > 0) {
-            providerOptions.onPayload = async (payload) => {
-                let current = payload;
-                for (const registered of payloadHandlers) {
-                    const result = await this.invoke("provider.payload", registered, {
-                        ...this.eventContext(registered.extensionId, origin),
-                        ...base,
-                        payload: current,
-                    });
-                    if (result !== undefined && "payload" in result)
-                        current = result.payload;
-                }
-                return current;
-            };
-        }
-        if (responseHandlers.length > 0) {
-            providerOptions.onResponse = async (response) => {
-                for (const registered of responseHandlers) {
-                    await this.invoke("provider.response", registered, {
-                        ...this.eventContext(registered.extensionId, origin),
-                        ...base,
-                        status: response.status,
-                        headers: response.headers,
-                    });
+    providerHooks = {
+        headers: async (headers, ctx) => {
+            let current = headers;
+            for (const registered of this.handlersFor("provider.headers")) {
+                const result = await this.invoke("provider.headers", registered, { ...this.providerContext(ctx), headers: current });
+                if (result?.headers !== undefined)
+                    current = result.headers;
+            }
+            return current;
+        },
+        payload: async (payload, ctx) => {
+            let current = payload;
+            let changed = false;
+            for (const registered of this.handlersFor("provider.payload")) {
+                const result = await this.invoke("provider.payload", registered, { ...this.providerContext(ctx), payload: current });
+                if (result !== undefined && "payload" in result) {
+                    current = result.payload;
+                    changed = true;
                 }
-            };
-        }
-        return { ...request, providerOptions };
+            }
+            return changed ? { payload: current } : undefined;
+        },
+        response: async (response, ctx) => {
+            for (const registered of this.handlersFor("provider.response")) {
+                await this.invoke("provider.response", registered, { ...this.providerContext(ctx), status: response.status, headers: response.headers });
+            }
+        },
+    };
+    /** Whether any provider-tier handler is registered — the capability omits `provider` otherwise,
+     *  so a request with no provider-tier extension is left byte-identical. */
+    hasProviderHandlers() {
+        return this.handlersFor("provider.headers").length + this.handlersFor("provider.payload").length + this.handlersFor("provider.response").length > 0;
+    }
+    providerContext(ctx) {
+        const session = this.requireSession();
+        return {
+            ...this.eventContext(this.id, { ...(ctx.address !== undefined ? { address: ctx.address } : {}), signal: session.signal }),
+            turnId: ctx.turnId,
+            stepNumber: ctx.stepNumber,
+        };
     }
     async afterModelResponse(origin, request, response, context) {
         this.activeContext = context;
@@ -609,7 +470,7 @@ export class ExtensionRuntime {
     apiFor(definition, registrations) {
         return {
             on: (event, handler) => {
-                if (!this.live.has(definition.id)) {
+                if (!this.live) {
                     void this.warn(definition.id, `on("${event}") ignored: extension is detached.`);
                     return () => undefined;
                 }
@@ -630,11 +491,11 @@ export class ExtensionRuntime {
                 return dispose;
             },
             onEvent: (listener) => {
-                if (!this.live.has(definition.id)) {
+                if (!this.live) {
                     void this.warn(definition.id, "onEvent() ignored: extension is detached.");
                     return () => undefined;
                 }
-                // `setup` runs inside `open`, so the session context is already in place.
+                // `session` runs inside `open`, so the session context is already in place.
                 const sink = this.session?.events;
                 if (sink === undefined)
                     return () => undefined;
@@ -654,27 +515,26 @@ export class ExtensionRuntime {
                 // A plain spec (file extensions — no framework imports, so no `tool()` helper) is
                 // expanded here; a real Tool passes through untouched.
                 const tool = "schema" in toolOrSpec ? toolOrSpec : toolFromSpec(toolOrSpec);
-                if (!this.live.has(definition.id)) {
+                if (!this.live) {
                     void this.warn(definition.id, `registerTool("${tool.schema.name}") ignored: extension is detached.`);
                     return () => undefined;
                 }
                 const name = tool.schema.name;
-                const existing = this.tools.get(name);
-                if (existing) {
-                    throw new Error(`extension tool "${name}" from "${definition.id}" collides with "${existing.extensionId}"`);
-                }
-                this.tools.set(name, { extensionId: definition.id, tool });
-                // Core's toolset assembly reads this tag to fail a name collision closed, naming us.
+                if (this.tools.has(name))
+                    throw new Error(`extension "${definition.id}" registered tool "${name}" twice`);
+                this.tools.set(name, tool);
+                // Core's toolset assembly reads this tag to fail a collision with ANOTHER capability's
+                // tool closed, naming us.
                 tagToolSource(tool, definition.id);
                 const dispose = () => {
-                    if (this.tools.get(name)?.tool === tool)
+                    if (this.tools.get(name) === tool)
                         this.tools.delete(name);
                 };
                 registrations.push(dispose);
                 return dispose;
             },
             registerInjector: (injector) => {
-                if (!this.live.has(definition.id)) {
+                if (!this.live) {
                     void this.warn(definition.id, `registerInjector("${injector.id}") ignored: extension is detached.`);
                     return () => undefined;
                 }
@@ -688,14 +548,13 @@ export class ExtensionRuntime {
                 return dispose;
             },
             registerCommand: (command) => {
-                if (!this.live.has(definition.id)) {
+                if (!this.live) {
                     void this.warn(definition.id, `registerCommand("/${command.name}") ignored: extension is detached.`);
                     return () => undefined;
                 }
                 const key = command.name.trim().toLowerCase();
-                const existing = this.extCommands.get(key);
-                if (existing) {
-                    throw new Error(`extension command "/${key}" from "${definition.id}" collides with "${existing.extensionId}"`);
+                if (this.commands.some((existing) => existing.name.trim().toLowerCase() === key)) {
+                    throw new Error(`extension "${definition.id}" registered command "/${key}" twice`);
                 }
                 const headless = {
                     name: command.name,
@@ -703,16 +562,17 @@ export class ExtensionRuntime {
                     description: command.description,
                     run: async (_ctx, args) => command.run(args),
                 };
-                this.extCommands.set(key, { extensionId: definition.id, command: headless });
+                this.commands.push(headless);
                 const dispose = () => {
-                    if (this.extCommands.get(key)?.command === headless)
-                        this.extCommands.delete(key);
+                    const index = this.commands.indexOf(headless);
+                    if (index >= 0)
+                        this.commands.splice(index, 1);
                 };
                 registrations.push(dispose);
                 return dispose;
             },
             emitEvent: (name, data) => {
-                if (!this.live.has(definition.id)) {
+                if (!this.live) {
                     void this.warn(definition.id, `emitEvent("${name}") ignored: extension is detached.`);
                     return;
                 }
@@ -731,27 +591,24 @@ export class ExtensionRuntime {
                 });
             },
             expose: (handle) => {
-                if (!this.live.has(definition.id)) {
+                if (!this.live) {
                     void this.warn(definition.id, "expose() ignored: extension is detached.");
                     return () => undefined;
                 }
-                this.exposedHandles.set(definition.id, handle);
+                this.exposed = handle;
                 const dispose = () => {
-                    if (this.exposedHandles.get(definition.id) === handle)
-                        this.exposedHandles.delete(definition.id);
+                    if (this.exposed === handle)
+                        this.exposed = undefined;
                 };
                 registrations.push(dispose);
                 return dispose;
             },
-            records: async () => {
-                const snapshot = (await this.ensureRecordSnapshot()).get(definition.id) ?? [];
-                const writes = this.recordWrites.get(definition.id) ?? [];
-                return [...snapshot, ...writes];
-            },
+            // The engine keeps both, partitioned by this capability's name — the extension's id.
+            records: () => this.requireSession().records(),
             state: {
-                get: (key) => this.stateFor(definition.id, this.session?.store).get(key),
-                set: (key, value) => this.stateFor(definition.id, this.session?.store).set(key, value),
-                delete: (key) => this.stateFor(definition.id, this.session?.store).delete(key),
+                get: (key) => this.requireSession().state.get(key),
+                set: (key, value) => this.requireSession().state.set(key, value),
+                delete: (key) => this.requireSession().state.delete(key),
             },
             actions: this.actionsFor(definition.id),
         };
@@ -777,13 +634,13 @@ export class ExtensionRuntime {
             get(_target, prop) {
                 if (isProbeProperty(prop))
                     return undefined;
-                if (!runtime.live.has(extensionId))
+                if (!runtime.live)
                     return dead();
                 const inner = services.handle(name)[prop];
                 if (typeof inner !== "function")
                     return inner;
                 return (...args) => {
-                    if (!runtime.live.has(extensionId))
+                    if (!runtime.live)
                         return dead()();
                     return inner(...args);
                 };
@@ -791,7 +648,7 @@ export class ExtensionRuntime {
             // Forward `in` so consumers can probe registration ("route" in handle) through the
             // collar; a detached extension's probe reads false like a dead handle's.
             has: (_target, prop) => {
-                if (!runtime.live.has(extensionId))
+                if (!runtime.live)
                     return false;
                 return Reflect.has(services.handle(name), prop);
             },
@@ -819,7 +676,7 @@ export class ExtensionRuntime {
         return new Proxy(actions, {
             get(target, prop, receiver) {
                 const value = Reflect.get(target, prop, receiver);
-                if (typeof value !== "function" || runtime.live.has(extensionId))
+                if (typeof value !== "function" || runtime.live)
                     return value;
                 return (..._args) => {
                     void runtime.warn(extensionId, `${String(prop)}() ignored: extension is detached.`);
@@ -840,19 +697,15 @@ export class ExtensionRuntime {
         return this.revocable(extensionId, {
             steer: (content, options) => runtime.enqueue(extensionId, content, "steering", options?.metadata),
             followUp: (content, options) => runtime.enqueue(extensionId, content, "follow_up", options?.metadata),
+            // Written by the engine to the session's audit shard as `extension:<id>:<name>`, and seen
+            // by `records()` straight away.
             record: (name, data) => {
-                const context = runtime.activeContext;
-                if (!context) {
-                    void runtime.warn(extensionId, `record("${name}") ignored: no active conversation.`);
+                const session = runtime.session;
+                if (!session) {
+                    void runtime.warn(extensionId, `record("${name}") ignored: no open session.`);
                     return;
                 }
-                context.record({ type: "custom", name: `extension:${extensionId}:${name}`, data });
-                // Mirror into the in-memory bucket so `records()` sees this session's writes without
-                // re-reading the log (the open-time memoized read predates them).
-                const bucket = runtime.recordWrites.get(extensionId) ?? [];
-                if (!runtime.recordWrites.has(extensionId))
-                    runtime.recordWrites.set(extensionId, bucket);
-                bucket.push({ name, ...(data !== undefined ? { data } : {}) });
+                session.record(name, data);
             },
             abort: (reason) => {
                 const controls = runtime.controls();
@@ -942,7 +795,7 @@ export class ExtensionRuntime {
      * schema untouched. `source` names the extension so a fold can attribute the message.
      */
     enqueue(extensionId, content, channel, metadata) {
-        const bus = this.run?.steer ?? this.session?.steer;
+        const bus = this.session?.steer;
         if (!bus) {
             void this.warn(extensionId, `${channel === "steering" ? "steer" : "followUp"}() ignored: no steer bus.`);
             return undefined;
@@ -975,82 +828,31 @@ export class ExtensionRuntime {
     // ==========================================================================
     sessionContext(extensionId) {
         const session = this.requireSession();
+        const store = session.store;
         return {
             extensionId,
             sessionId: session.sessionId,
             signal: session.signal,
-            machine: session.machine,
-            store: session.store,
-            state: this.stateFor(extensionId, session.store),
+            environment: session.environment,
+            store,
+            state: session.state,
             actions: this.actionsFor(extensionId),
         };
     }
     eventContext(extensionId, origin) {
         const session = this.requireSession();
+        const store = session.store;
         return {
             extensionId,
             sessionId: session.sessionId,
             address: origin.address ?? "main",
             signal: origin.signal,
-            machine: this.run?.machine ?? session.machine,
-            store: session.store,
-            state: this.stateFor(extensionId, session.store),
+            environment: session.environment,
+            store,
+            state: session.state,
             actions: this.actionsFor(extensionId),
         };
     }
-    /** Open-time record buckets, built ONCE off the session's shared memoized log read — the
-     *  same single read goal/plan/todo fold from, so `records()` adds zero log traversals. One
-     *  filter pass buckets every extension's records; ids are colon-free slugs so the
-     *  "extension:<id>:" prefix parse is unambiguous. */
-    async ensureRecordSnapshot() {
-        if (this.recordSnapshot !== undefined)
-            return this.recordSnapshot;
-        const buckets = new Map();
-        const log = this.session?.logRecords !== undefined ? await this.session.logRecords() : [];
-        for (const record of log) {
-            if (record.type !== "custom")
-                continue;
-            const full = record.name;
-            if (typeof full !== "string" || !full.startsWith("extension:"))
-                continue;
-            const rest = full.slice("extension:".length);
-            const sep = rest.indexOf(":");
-            if (sep <= 0)
-                continue;
-            const id = rest.slice(0, sep);
-            const data = record.data;
-            const bucket = buckets.get(id) ?? [];
-            if (!buckets.has(id))
-                buckets.set(id, bucket);
-            bucket.push({ name: rest.slice(sep + 1), ...(data !== undefined ? { data } : {}) });
-        }
-        this.recordSnapshot = buckets;
-        return buckets;
-    }
-    stateFor(extensionId, store) {
-        const prefix = `extension:${extensionId}:`;
-        return {
-            get: async (key) => {
-                const full = prefix + key;
-                const value = store ? await store.getState(full) : this.memoryState.get(full) ?? null;
-                return value;
-            },
-            set: async (key, value) => {
-                const full = prefix + key;
-                if (store)
-                    await store.putState(full, value);
-                else
-                    this.memoryState.set(full, value);
-            },
-            delete: async (key) => {
-                const full = prefix + key;
-                if (store)
-                    await store.deleteState(full);
-                else
-                    this.memoryState.delete(full);
-            },
-        };
-    }
     handlersFor(name) {
         return (this.handlers.get(name) ?? []);
     }