operon-agents 0.1.0-alpha.3 → 0.1.0-alpha.4

package/dist/app-server/main.js

@@ -9,7 +9,7 @@
  * redirect console.log/info/debug to stderr so a stray log can never corrupt the
  * protocol stream.
  */
-import { defineModel, DiskSessionRepository } from "operon-agents-core";
+import { defineModel, DiskSessionRepository, T } from "operon-agents-core";
 import { createHarness } from "../harness.js";
 import { nodeStreamTransport } from "./codec.js";
 import { AppServer } from "./server.js";
@@ -63,7 +63,7 @@ async function main() {
     const harness = createHarness({
         model: args.model ?? "anthropic/claude-opus-4-8",
         resolveModel,
-        ...(args.home !== undefined ? { repository: new DiskSessionRepository(args.home) } : {}),
+        ...(args.home !== undefined ? { harness: (scope) => scope.register(T.SessionRepository, new DiskSessionRepository(args.home)) } : {}),
         ...(args.workdir !== undefined ? { workDir: args.workdir } : {}),
         permission: { mode: args.permission ?? "yolo" },
     });

package/dist/cron/extension.js

@@ -29,8 +29,8 @@ export function normalizeCronTaskInput(manager, input) {
 export function cronExtension(options = {}) {
     return {
         id: "cron",
-        async setup(api) {
-            // One manager per session: setup runs per session open, so scheduling state is
+        async session(api) {
+            // One manager per session: session() runs per session open, so scheduling state is
             // session-scoped exactly as the capability's openSession was.
             const manager = new CronManager(options);
             manager.attach({

package/dist/extensions/index.d.ts

@@ -3,11 +3,11 @@ import type { ExtensionDefinition, ExtensionHost } from "./types.ts";
 export { ExtensionRuntime } from "./runtime.ts";
 export { ExtensionLoader, createExtensionLoader } from "./loader.ts";
 export { ServiceRegistry, ServiceUnavailableError, deadServiceHandle } from "./services.ts";
-export { HarnessExtensionManager, stageDefinition } from "./manager.ts";
+export { HarnessExtensionManager, stageDefinition, assertOneSharedHalf } from "./manager.ts";
 export type { ExtensionHostBridge, StagingOptions, HeldSession, StagedDefinition } from "./manager.ts";
-export type { ServiceOptions, ServiceUnavailableReason } from "./services.ts";
+export type { ServiceOptions, ServiceTier, ServiceUnavailableReason } from "./services.ts";
 export type { ExtensionManifest, ExtensionFileState, ExtensionFileStatus, ExtensionAttachTarget } from "./loader.ts";
-export type { ExtensionActions, ExtensionAPI, ExtensionCommand, ExtensionCommandResult, ExtensionRecordEntry, ExtensionSteerOptions, ExtensionDefinition, ExtensionHostContext, ExtensionEventContext, ExtensionEventMap, ExtensionEventName, ExtensionHandler, ExtensionHost, ExtensionModelRequestEvent, ExtensionModelRequestResult, ExtensionModelResponseEvent, ExtensionResultMap, ExtensionRunSettledEvent, ExtensionRunSettledResult, ExtensionRunStartEvent, ExtensionRunStartResult, ExtensionSessionContext, ExtensionSetupContext, ExtensionSessionEndEvent, ExtensionSessionStartEvent, ExtensionState, ExtensionToolSpec, ExtensionStepEndEvent, ExtensionStepEndResult, ExtensionStepStartEvent, ExtensionStepStartResult, ExtensionToolAuthorizeEvent, ExtensionToolAuthorizeResult, ExtensionToolCallEvent, ExtensionToolCallResult, ExtensionToolResultEvent, ExtensionCompactionBeforeEvent, ExtensionCompactionBeforeResult, ExtensionProviderHeadersEvent, ExtensionProviderHeadersResult, ExtensionProviderPayloadEvent, ExtensionProviderPayloadResult, ExtensionProviderResponseEvent, ProviderHeaders, HarnessSessionHandle, ModelProvider, SessionEndReason, SessionStartReason, } from "./types.ts";
+export type { ExtensionActions, ExtensionAPI, ExtensionCommand, ExtensionCommandResult, ExtensionRecordEntry, ExtensionSteerOptions, ExtensionDefinition, ExtensionHostContext, ExtensionWorkspaceContext, ExtensionEventContext, ExtensionEventMap, ExtensionEventName, ExtensionHandler, ExtensionHost, ExtensionModelRequestEvent, ExtensionModelRequestResult, ExtensionModelResponseEvent, ExtensionResultMap, ExtensionRunSettledEvent, ExtensionRunSettledResult, ExtensionRunStartEvent, ExtensionRunStartResult, ExtensionSessionContext, ExtensionSessionEventContext, ExtensionSessionEndEvent, ExtensionSessionStartEvent, ExtensionState, ExtensionToolSpec, ExtensionStepEndEvent, ExtensionStepEndResult, ExtensionStepStartEvent, ExtensionStepStartResult, ExtensionToolAuthorizeEvent, ExtensionToolAuthorizeResult, ExtensionToolCallEvent, ExtensionToolCallResult, ExtensionToolResultEvent, ExtensionCompactionBeforeEvent, ExtensionCompactionBeforeResult, ExtensionProviderHeadersEvent, ExtensionProviderHeadersResult, ExtensionProviderPayloadEvent, ExtensionProviderPayloadResult, ExtensionProviderResponseEvent, ProviderHeaders, HarnessSessionHandle, ModelProvider, SessionEndReason, SessionStartReason, } from "./types.ts";
 /**
  * Build one isolated, session-scoped runtime for programmatic extensions.
  *

package/dist/extensions/index.js

@@ -1,8 +1,9 @@
 import { ExtensionRuntime } from "./runtime.js";
+import { HT } from "../tokens.js";
 export { ExtensionRuntime } from "./runtime.js";
 export { ExtensionLoader, createExtensionLoader } from "./loader.js";
 export { ServiceRegistry, ServiceUnavailableError, deadServiceHandle } from "./services.js";
-export { HarnessExtensionManager, stageDefinition } from "./manager.js";
+export { HarnessExtensionManager, stageDefinition, assertOneSharedHalf } from "./manager.js";
 /**
  * Build one isolated, session-scoped runtime for programmatic extensions.
  *
@@ -15,11 +16,20 @@ export function extensionsCapability(definitions, options = {}) {
     const runtime = new ExtensionRuntime(definitions, options.host, options.params);
     return {
         name: "extensions",
-        service: runtime,
+        provides: [
+            {
+                token: HT.Extensions,
+                create: async (ctx) => {
+                    await runtime.open(ctx);
+                    return runtime;
+                },
+                dispose: () => runtime.close(),
+            },
+        ],
         toolProviders: [{ id: "extensions", listTools: () => runtime.listTools() }],
         toolFilters: [runtime.filterTools],
         gates: { compaction: runtime.compactionGate },
-        // Stable array reference — `setup` (openSession) fills it before any run assembles.
+        // Stable array reference — `session` (the provision's `harness`) fills it before any run assembles.
         injectors: runtime.listInjectors(),
         hooks: {
             beforeRun: async (ctx) => runtime.beforeRun(ctx, ctx.input),
@@ -32,8 +42,6 @@ export function extensionsCapability(definitions, options = {}) {
             authorizeToolExecution: async (ctx) => runtime.authorizeToolCall(ctx, ctx.toolCall.name, ctx.toolCall.id, ctx.tool, ctx.args, ctx.plan),
             finalizeToolResult: async (ctx) => runtime.afterToolResult(ctx, ctx.toolCall.name, ctx.toolCall.id, ctx.tool, ctx.args, ctx.result),
         },
-        openSession: (ctx) => runtime.open(ctx),
-        closeSession: () => runtime.close(),
         start: (ctx) => runtime.attachRun(ctx),
         stop: () => runtime.detachRun(),
     };

package/dist/extensions/loader.d.ts

@@ -30,7 +30,7 @@ export declare function compareVersions(a: string, b: string): number;
 /**
  * What must be known about an extension BEFORE its code is imported — find it (`id`), import
  * it (`entry`, gated by `engine`), show it (`version`, `name`, `description`) — and nothing more. What the
- * extension provides (`create`) and consumes (`uses`) lives on the definition it exports, the
+ * extension provides (`harness`) and consumes (`uses`) lives on the definition it exports, the
  * same on both channels. Only `id` is validated; unknown fields pass through untouched, so a
  * manifest written for a newer loader still loads here.
  */
@@ -102,7 +102,7 @@ export declare class ExtensionLoader {
     }>;
     /** The definitions currently held. On the standalone-loader path these reach sessions through
      *  `attachExtension`/`reloadInto`; a harness built with `extensionDir` registers them itself
-     *  (`harness.extensions.load`), which is the path that also runs `create` halves. */
+     *  (`harness.extensions.load`), which is the path that also runs `harness` halves. */
     definitions(): ExtensionDefinition[];
     /** Convenience: reload a extension and swap it on a live session (detach old, attach new). */
     reloadInto(session: ExtensionAttachTarget, id: string): Promise<ExtensionDefinition>;

package/dist/extensions/loader.js

@@ -155,7 +155,7 @@ export class ExtensionLoader {
     }
     /** The definitions currently held. On the standalone-loader path these reach sessions through
      *  `attachExtension`/`reloadInto`; a harness built with `extensionDir` registers them itself
-     *  (`harness.extensions.load`), which is the path that also runs `create` halves. */
+     *  (`harness.extensions.load`), which is the path that also runs `harness` halves. */
     definitions() {
         return [...this.loaded.values()];
     }
@@ -241,11 +241,11 @@ export class ExtensionLoader {
         }
         let candidate = moduleExports.default;
         // A factory default export lets a extension construct per-load state; called with nothing —
-        // everything a extension may use arrives later through its setup(ctx).
+        // everything a extension may use arrives later through its session(ctx).
         if (typeof candidate === "function")
             candidate = candidate();
         if (!isExtensionDefinition(candidate)) {
-            throw new Error(`extension "${scanned.manifest.id}" default export is not an extension definition ({ id, setup })`);
+            throw new Error(`extension "${scanned.manifest.id}" default export is not an extension definition ({ id, session })`);
         }
         if (candidate.id !== scanned.manifest.id) {
             throw new Error(`extension id mismatch: manifest says "${scanned.manifest.id}", code says "${candidate.id}"`);
@@ -277,7 +277,7 @@ export function createExtensionLoader(options) {
 function isExtensionDefinition(value) {
     return (typeof value === "object" && value !== null
         && typeof value.id === "string"
-        && typeof value.setup === "function");
+        && typeof value.session === "function");
 }
 function messageOf(error) {
     return error instanceof Error ? error.message : String(error);

package/dist/extensions/manager.d.ts

@@ -12,9 +12,27 @@ export interface HeldSession {
         readonly uses: readonly string[];
     }[];
 }
+/**
+ * The workspace-tier side of the bridge: `workspace` halves live in the harness's workspace
+ * scopes, which only the harness can reach. `staged` maps workspace key → the instance the new
+ * half produced for it (staging runs BEFORE the barrier, so a throwing half changes nothing).
+ */
+export interface WorkspaceHalfBridge {
+    /** Run `definition.workspace` against every live workspace; nothing is registered. */
+    stage(definition: ExtensionDefinition): Promise<Map<string, unknown>>;
+    /** In the quiet moment: give every live workspace its staged instance (replace where one is
+     *  registered, register where none is; compose fresh for a workspace born after staging).
+     *  `staged === undefined` ⇒ the definition has no `workspace` half: unregister everywhere. */
+    swap(definition: ExtensionDefinition, staged: Map<string, unknown> | undefined): Promise<void>;
+    /** Unregister `id` from every live workspace (unload). */
+    unregister(id: string): Promise<void>;
+    /** Dispose staged instances that were never published (a failed act). */
+    discard(id: string, staged: Map<string, unknown>): Promise<void>;
+}
 /** The narrow harness face the manager operates through (no import cycle with harness.ts). */
 export interface ExtensionHostBridge {
     readonly services: ServiceRegistry;
+    readonly workspaces: WorkspaceHalfBridge;
     createSession(options?: Record<string, unknown>): Promise<{
         readonly id: string;
     }>;
@@ -24,16 +42,22 @@ export interface ExtensionHostBridge {
     withBarrier(extensionIds: readonly string[], timeoutMs: number, fn: (held: () => readonly HeldSession[]) => Promise<void>): Promise<void>;
     warn(message: string): void;
 }
-/** What staging one `create`-bearing definition produced, before anything is published. */
+/**
+ * A definition carries at most ONE shared half. Its service (and `ctx.shared`) lives at exactly
+ * one tier — the tier of the half that produced it — so consumers and the session half never
+ * have to ask which. Checked wherever a definition is registered (by value or from a file).
+ */
+export declare function assertOneSharedHalf(definition: ExtensionDefinition): void;
+/** What staging one `harness`-bearing definition produced, before anything is published. */
 export interface StagedDefinition {
-    /** The one service `create` returned, to register under the extension's id; absent when the
-     *  definition has no `create`. */
+    /** The one service `harness` returned, to register under the extension's id; absent when the
+     *  definition has no `harness`. */
     readonly service?: {
         readonly name: string;
         readonly instance: unknown;
         readonly options: ServiceOptions;
     };
-    /** The definition itself — its `setup` is the per-session half, mounted into every session. */
+    /** The definition itself — its `session` is the per-session half, mounted into every session. */
     readonly sessionDef: ExtensionDefinition;
 }
 export interface StagingOptions {
@@ -49,9 +73,9 @@ export interface StagingOptions {
     warn(message: string): void;
 }
 /**
- * Run a `create`-bearing definition's `create` half against a staging host and collect the one
- * service it returns — nothing is registered here, so a throwing `create` publishes nothing.
- * Shared by the file manager and the harness's by-value channel. Stays synchronous when `create`
+ * Run a `harness`-bearing definition's `harness` half against a staging host and collect the one
+ * service it returns — nothing is registered here, so a throwing `harness` publishes nothing.
+ * Shared by the file manager and the harness's by-value channel. Stays synchronous when `harness`
  * is, which the by-value channel relies on to have a synchronous extension's service visible the
  * moment `createHarness` returns.
  */
@@ -61,7 +85,7 @@ export declare class HarnessExtensionManager {
     private readonly bridge;
     /** Root of the extensions' data folders (`<root>/<id>`) — outside every code folder. */
     private readonly dataRoot;
-    /** Every loaded extension by id, and whether its `create` published a service. */
+    /** Every loaded extension by id, and whether its `harness` published a service. */
     private readonly loaded;
     /** Definitions newborn sessions receive: every loaded extension's per-session half. */
     private readonly sessionDefs;
@@ -75,10 +99,10 @@ export declare class HarnessExtensionManager {
     sessionDefinitions(): ExtensionDefinition[];
     /**
      * Load (and approve) one extension — a USER action, like `ExtensionLoader.load`. Runs the
-     * definition's `create` (if any) and publishes the result as its service, then hands the
+     * definition's `harness` (if any) and publishes the result as its service, then hands the
      * definition to future sessions. Loading an already-loaded extension reloads it: every
      * session holding it meets at its run boundary, the per-session half is swapped (and the
-     * service replaced), and everyone resumes — the same act whether or not there is a `create`.
+     * service replaced), and everyone resumes — the same act whether or not there is a `harness`.
      */
     load(id: string, options?: {
         readonly timeoutMs?: number;
@@ -88,14 +112,14 @@ export declare class HarnessExtensionManager {
         readonly timeoutMs?: number;
     }): Promise<void>;
     /**
-     * Unload an extension. A `create`-bearing one is refused while any session still runs an
+     * Unload an extension. A `harness`-bearing one is refused while any session still runs an
      * extension that `uses` its service — named, so the caller knows what to detach. Its own
      * per-session half does not block (it is removed as part of the unload).
      */
     unload(id: string): Promise<void>;
     private register;
-    /** Run `create` with a staging host: the service is COLLECTED, not registered, so a throwing
-     *  `create` publishes nothing. Services default to replaceable — reload is their point. */
+    /** Run `harness` with a staging host: the service is COLLECTED, not registered, so a throwing
+     *  `harness` publishes nothing. Services default to replaceable — reload is their point. */
     private stage;
     /** Sessions still running an extension that `uses` `id`'s service — read off the attached
      *  definitions themselves, so by-value and file consumers count alike. No graph walk: the

package/dist/extensions/manager.js

@@ -1,8 +1,8 @@
 /**
  * The file-extension manager (design: docs/architecture.md §5.4-5.5). An extension
- * is a FILE whose default export is an `ExtensionDefinition`; the manager runs its `create` half
+ * is a FILE whose default export is an `ExtensionDefinition`; the manager runs its `harness` half
  * once if it has one, registers the result as a service under the extension's `id`, and hands
- * the SAME definition to every session (its `setup` is the per-session half). One extension,
+ * the SAME definition to every session (its `session` is the per-session half). One extension,
  * one approval, one reload — the manager turns a reload into the coordinated act: barrier →
  * swap the session half → replace the service → release.
  *
@@ -10,26 +10,36 @@
  * single one as for ordinary extensions — manual load/reload IS the approval (mtime-scoped).
  * Nothing here auto-loads or watches.
  *
- * `stageDefinition` — running `create` against a staging host and collecting the one service, so a
- * throwing `create` publishes nothing — is shared with the harness's by-value channel
- * (`createHarness({ extensions })` runs a `create`-bearing definition through it with no loader).
+ * `stageDefinition` — running `harness` against a staging host and collecting the one service, so a
+ * throwing `harness` publishes nothing — is shared with the harness's by-value channel
+ * (`createHarness({ extensions })` runs a `harness`-bearing definition through it with no loader).
  */
 import { mkdir } from "node:fs/promises";
 import { join, resolve } from "node:path";
 import { ExtensionLoader } from "./loader.js";
 import { ServiceRegistry } from "./services.js";
+/**
+ * A definition carries at most ONE shared half. Its service (and `ctx.shared`) lives at exactly
+ * one tier — the tier of the half that produced it — so consumers and the session half never
+ * have to ask which. Checked wherever a definition is registered (by value or from a file).
+ */
+export function assertOneSharedHalf(definition) {
+    if (definition.harness !== undefined && definition.workspace !== undefined) {
+        throw new Error(`extension "${definition.id}" declares both a harness and a workspace half — a definition carries ONE shared half, so its service lives at exactly one tier`);
+    }
+}
 function isPromiseLike(value) {
     return typeof value === "object" && value !== null && typeof value.then === "function";
 }
 /**
- * Run a `create`-bearing definition's `create` half against a staging host and collect the one
- * service it returns — nothing is registered here, so a throwing `create` publishes nothing.
- * Shared by the file manager and the harness's by-value channel. Stays synchronous when `create`
+ * Run a `harness`-bearing definition's `harness` half against a staging host and collect the one
+ * service it returns — nothing is registered here, so a throwing `harness` publishes nothing.
+ * Shared by the file manager and the harness's by-value channel. Stays synchronous when `harness`
  * is, which the by-value channel relies on to have a synchronous extension's service visible the
  * moment `createHarness` returns.
  */
 export function stageDefinition(definition, options) {
-    if (definition.create === undefined)
+    if (definition.harness === undefined)
         return { sessionDef: definition };
     const host = {
         createSession: (sessionOptions) => options.createSession(sessionOptions),
@@ -42,7 +52,7 @@ export function stageDefinition(definition, options) {
         service: { name: definition.id, instance, options: { replaceable: options.defaultReplaceable } },
         sessionDef: definition,
     });
-    const result = definition.create(host);
+    const result = definition.harness(host);
     return isPromiseLike(result) ? Promise.resolve(result).then(finish) : finish(result);
 }
 const DEFAULT_BARRIER_TIMEOUT_MS = 30_000;
@@ -51,7 +61,7 @@ export class HarnessExtensionManager {
     bridge;
     /** Root of the extensions' data folders (`<root>/<id>`) — outside every code folder. */
     dataRoot;
-    /** Every loaded extension by id, and whether its `create` published a service. */
+    /** Every loaded extension by id, and whether its `harness` published a service. */
     loaded = new Map();
     /** Definitions newborn sessions receive: every loaded extension's per-session half. */
     sessionDefs = new Map();
@@ -69,16 +79,23 @@ export class HarnessExtensionManager {
     }
     /**
      * Load (and approve) one extension — a USER action, like `ExtensionLoader.load`. Runs the
-     * definition's `create` (if any) and publishes the result as its service, then hands the
+     * definition's `harness` (if any) and publishes the result as its service, then hands the
      * definition to future sessions. Loading an already-loaded extension reloads it: every
      * session holding it meets at its run boundary, the per-session half is swapped (and the
-     * service replaced), and everyone resumes — the same act whether or not there is a `create`.
+     * service replaced), and everyone resumes — the same act whether or not there is a `harness`.
      */
     async load(id, options = {}) {
         const definition = await this.loader.load(id);
-        // `uses` lives on the definition, so it is readable only after the import; a missing
-        // provider revokes the approval the import just recorded, so a failed load leaves nothing
-        // behind. Same rule for both kinds: load providers first.
+        // Shape and `uses` live on the definition, so they are readable only after the import; a
+        // bad definition or a missing provider revokes the approval the import just recorded, so a
+        // failed load leaves nothing behind. Same rule for both kinds: load providers first.
+        try {
+            assertOneSharedHalf(definition);
+        }
+        catch (error) {
+            await this.loader.unload(id);
+            throw error;
+        }
         for (const name of definition.uses ?? []) {
             if (!this.bridge.services.has(name)) {
                 await this.loader.unload(id);
@@ -92,7 +109,7 @@ export class HarnessExtensionManager {
         return this.load(id, options);
     }
     /**
-     * Unload an extension. A `create`-bearing one is refused while any session still runs an
+     * Unload an extension. A `harness`-bearing one is refused while any session still runs an
      * extension that `uses` its service — named, so the caller knows what to detach. Its own
      * per-session half does not block (it is removed as part of the unload).
      */
@@ -116,6 +133,10 @@ export class HarnessExtensionManager {
         this.sessionDefs.delete(id);
         if (record.hasService)
             await this.bridge.services.unregister(id);
+        if (record.hasWorkspace) {
+            await this.bridge.workspaces.unregister(id);
+            this.bridge.services.undeclareWorkspace(id);
+        }
         this.loaded.delete(id);
         await this.loader.unload(id);
     }
@@ -124,47 +145,74 @@ export class HarnessExtensionManager {
     // ==========================================================================
     async register(id, definition, options) {
         const staged = await this.stage(definition);
+        // The workspace half is staged the same way, once per live workspace: run BEFORE anything
+        // is published, so a throwing half leaves every workspace on what it had.
+        const hasWorkspace = definition.workspace !== undefined;
+        const stagedWorkspaces = hasWorkspace ? await this.bridge.workspaces.stage(definition) : undefined;
         const previous = this.loaded.get(id);
+        const record = { hasService: staged.service !== undefined, hasWorkspace };
         if (previous === undefined) {
             // First load: register the service, then hand the session half to future sessions.
             // Already-open sessions are not touched (a reload only re-attaches to sessions that hold
-            // the half) — attach it explicitly where an open session should get it.
+            // the half) — attach it explicitly where an open session should get it. Workspaces
+            // already open DO get their instance now: a workspace half is composed on first use, and
+            // for them first use is this load.
             if (staged.service !== undefined) {
                 this.bridge.services.register(staged.service.name, staged.service.instance, staged.service.options);
             }
+            if (hasWorkspace)
+                this.bridge.services.declareWorkspace(id);
             this.sessionDefs.set(id, staged.sessionDef);
-            this.loaded.set(id, { hasService: staged.service !== undefined });
+            if (hasWorkspace)
+                await this.bridge.workspaces.swap(definition, stagedWorkspaces);
+            this.loaded.set(id, record);
             return;
         }
-        // Reload: one coordinated act — barrier on the session half, swap half + service in the
-        // quiet moment. Version skew between the two halves is structurally impossible.
-        await this.bridge.withBarrier([id], options.timeoutMs ?? DEFAULT_BARRIER_TIMEOUT_MS, async (held) => {
-            for (const session of held()) {
-                if (session.attachedExtensionIds().includes(id))
-                    await session.detachExtension(id);
-            }
-            if (staged.service !== undefined) {
-                if (this.bridge.services.has(id))
-                    await this.bridge.services.replace(id, staged.service.instance);
-                else
-                    this.bridge.services.register(staged.service.name, staged.service.instance, staged.service.options);
-            }
-            else if (previous.hasService) {
-                await this.bridge.services.unregister(id);
-            }
-            this.sessionDefs.set(id, staged.sessionDef);
-            for (const session of held()) {
-                await session.attachExtension(staged.sessionDef);
-            }
-        });
-        this.loaded.set(id, { hasService: staged.service !== undefined });
+        // Reload: one coordinated act — barrier on the session half, swap half + service(s) in the
+        // quiet moment. Version skew between the halves is structurally impossible.
+        try {
+            await this.bridge.withBarrier([id], options.timeoutMs ?? DEFAULT_BARRIER_TIMEOUT_MS, async (held) => {
+                for (const session of held()) {
+                    if (session.attachedExtensionIds().includes(id))
+                        await session.detachExtension(id);
+                }
+                if (staged.service !== undefined) {
+                    if (this.bridge.services.has(id))
+                        await this.bridge.services.replace(id, staged.service.instance);
+                    else
+                        this.bridge.services.register(staged.service.name, staged.service.instance, staged.service.options);
+                }
+                else if (previous.hasService) {
+                    await this.bridge.services.unregister(id);
+                }
+                this.sessionDefs.set(id, staged.sessionDef);
+                if (hasWorkspace) {
+                    this.bridge.services.declareWorkspace(id);
+                    await this.bridge.workspaces.swap(definition, stagedWorkspaces);
+                }
+                else if (previous.hasWorkspace) {
+                    // The new version dropped its workspace half: every workspace's instance goes with it.
+                    await this.bridge.workspaces.swap(definition, undefined);
+                    this.bridge.services.undeclareWorkspace(id);
+                }
+                for (const session of held()) {
+                    await session.attachExtension(staged.sessionDef);
+                }
+            });
+        }
+        catch (error) {
+            if (stagedWorkspaces !== undefined)
+                await this.bridge.workspaces.discard(id, stagedWorkspaces);
+            throw error;
+        }
+        this.loaded.set(id, record);
     }
-    /** Run `create` with a staging host: the service is COLLECTED, not registered, so a throwing
-     *  `create` publishes nothing. Services default to replaceable — reload is their point. */
+    /** Run `harness` with a staging host: the service is COLLECTED, not registered, so a throwing
+     *  `harness` publishes nothing. Services default to replaceable — reload is their point. */
     async stage(definition) {
-        // The data folder exists before `create` runs, so the extension can use it right away.
+        // The data folder exists before `harness` runs, so the extension can use it right away.
         const dataDir = join(this.dataRoot, definition.id);
-        if (definition.create !== undefined)
+        if (definition.harness !== undefined)
             await mkdir(dataDir, { recursive: true });
         return stageDefinition(definition, {
             defaultReplaceable: true,

package/dist/extensions/runtime.d.ts

@@ -1,5 +1,5 @@
 import type { HeadlessCommand } from "operon-agents-core";
-import type { AssistantMessage, CapabilityContext, CompactionGate, ChatModel, ConversationContext, Injector, LlmRequest, Message, SessionContext, StepStopReason, TerminalStepStopReason, Tool, ToolPlan, ToolResult, Usage } from "operon-agents-core";
+import type { AssistantMessage, RunContext, CompactionGate, ChatModel, ConversationContext, Injector, LlmRequest, Message, ProvisionContext, StepStopReason, TerminalStepStopReason, Tool, ToolPlan, ToolResult, Usage } from "operon-agents-core";
 import type { ExtensionDefinition, ExtensionHost, ExtensionModelRequestResult, ExtensionStepEndResult, ExtensionStepStartResult, ExtensionToolAuthorizeResult, ExtensionToolCallResult, SessionEndReason, SessionStartReason } from "./types.ts";
 /** Shared shape of the loop-hook contexts the dispatch methods are fed from. */
 interface StepOrigin {
@@ -13,7 +13,7 @@ export declare class ExtensionRuntime {
     private readonly definitions;
     private readonly handlers;
     private readonly tools;
-    /** Stable reference: `extensionsCapability` hands this array to the assembler, and `setup`
+    /** Stable reference: `extensionsCapability` hands this array to the assembler, and `session`
      *  (which runs at openSession, before any run assembles) fills it in place. */
     private readonly injectors;
     /** Slash commands by normalized name — surfaced to the session's registry via the
@@ -25,10 +25,10 @@ export declare class ExtensionRuntime {
      *  memoized log read — zero extra traversal) + everything recorded this session. */
     private recordSnapshot;
     private readonly recordWrites;
-    /** Per-extension teardown: setup's cleanup + every registration, undone in reverse. */
+    /** Per-extension teardown: session()'s cleanup + every registration, undone in reverse. */
     private readonly scopes;
     /** 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
+     *  session() 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. */
     private readonly live;
     /** Changes wait here until a quiet point: mid-run requests apply at the run's stop
@@ -37,6 +37,7 @@ export declare class ExtensionRuntime {
     /** Serializes flushes so concurrent attach/detach apply strictly in submission order. */
     private flushChain;
     private readonly memoryState;
+    /** The session binding: its scope (machine, store, events, steer, log reader, controls) + id + signal. */
     private session;
     private run;
     /** The conversation shard the in-flight decision point belongs to; backs `actions.record`. */
@@ -49,18 +50,18 @@ export declare class ExtensionRuntime {
     /** Harness reach. Absent when the capability is built standalone (bare Runner / tests). */
     private readonly 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`. */
+     *  "skip this extension for this session"; any other value is passed to `session` as `params`. */
     private readonly params;
     constructor(definitions: readonly ExtensionDefinition[], host?: ExtensionHost, params?: Readonly<Record<string, unknown>>);
-    open(ctx: SessionContext, reason?: SessionStartReason): Promise<void>;
-    attachRun(ctx: CapabilityContext): void;
+    open(ctx: ProvisionContext, reason?: SessionStartReason): Promise<void>;
+    attachRun(ctx: RunContext): void;
     detachRun(): Promise<void>;
     close(reason?: SessionEndReason): Promise<void>;
     /**
-     * Add an extension to the live session. Resolves once its `setup` has run and its
+     * Add an extension to the live session. Resolves once its `session` 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.
+     * Rejects on duplicate/empty id or when `session` throws.
      */
     attach(definition: ExtensionDefinition): Promise<void>;
     /** Ids of currently attached extensions — the reshape coordinator's affected-set probe. */
@@ -83,7 +84,7 @@ export declare class ExtensionRuntime {
     private drainPending;
     private attachNow;
     private detachNow;
-    /** 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. */
     private setupExtension;
     /**
      * Durable audit trail: replay needs "tool X only exists after record N" to reconstruct the