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

package/dist/extensions/index.d.ts

@@ -1,5 +1,6 @@
-import type { Capability } from "operon-agents-core";
-import type { ExtensionDefinition, ExtensionHost } from "./types.ts";
+import { type Capability } from "operon-agents-core";
+import type { ExtensionDefinition, ExtensionHost, SessionStartReason } from "./types.ts";
+import { ExtensionRuntime } from "./runtime.ts";
 export { ExtensionRuntime } from "./runtime.ts";
 export { ExtensionLoader, createExtensionLoader } from "./loader.ts";
 export { ServiceRegistry, ServiceUnavailableError, deadServiceHandle } from "./services.ts";
@@ -7,17 +8,30 @@ export { HarnessExtensionManager, stageDefinition } from "./manager.ts";
 export type { ExtensionHostBridge, StagingOptions, HeldSession, StagedDefinition } from "./manager.ts";
 export type { ServiceOptions, 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, 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";
+/** The extension runtime behind `capability`, or undefined when it is not an extension. */
+export declare function extensionRuntimeOf(capability: Capability): ExtensionRuntime | undefined;
 /**
- * Build one isolated, session-scoped runtime for programmatic extensions.
+ * One extension, as one of the session's capabilities — named by its id, `detachable`, and
+ * assembled, isolated, attached and detached exactly like any other capability.
  *
  * Every decision point in the extension contract is a `LoopHooks` slot — that is the only
  * channel where a handler's return value can reach the loop. Observation does NOT come through
  * here: observation goes through `api.onEvent`, which passes the session's event stream straight
  * through (with fault isolation and teardown), rather than through this hook table.
  */
+export declare function extensionCapability(definition: ExtensionDefinition, options?: {
+    readonly host?: ExtensionHost;
+    readonly params?: unknown;
+    readonly startReason?: SessionStartReason;
+}): Capability;
+/**
+ * A capability per extension, in order — what a session mounts for a list of definitions. A
+ * definition this session opted out of (`params[id] === false`) is left out entirely: never set
+ * up, never reported as attached.
+ */
 export declare function extensionsCapability(definitions: readonly ExtensionDefinition[], options?: {
     readonly host?: ExtensionHost;
     readonly params?: Readonly<Record<string, unknown>>;
-}): Capability;
+}): Capability[];
 //# sourceMappingURL=index.d.ts.map

package/dist/extensions/index.js

@@ -1,26 +1,63 @@
+import { readSessionLog } from "operon-agents-core";
 import { ExtensionRuntime } from "./runtime.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";
+/** The runtime behind each extension capability — how the harness reaches an extension it mounted. */
+const runtimes = new WeakMap();
+/** The extension runtime behind `capability`, or undefined when it is not an extension. */
+export function extensionRuntimeOf(capability) {
+    return runtimes.get(capability);
+}
 /**
- * Build one isolated, session-scoped runtime for programmatic extensions.
+ * One extension, as one of the session's capabilities — named by its id, `detachable`, and
+ * assembled, isolated, attached and detached exactly like any other capability.
  *
  * Every decision point in the extension contract is a `LoopHooks` slot — that is the only
  * channel where a handler's return value can reach the loop. Observation does NOT come through
  * here: observation goes through `api.onEvent`, which passes the session's event stream straight
  * through (with fault isolation and teardown), rather than through this hook table.
  */
-export function extensionsCapability(definitions, options = {}) {
-    const runtime = new ExtensionRuntime(definitions, options.host, options.params);
-    return {
-        name: "extensions",
-        service: runtime,
-        toolProviders: [{ id: "extensions", listTools: () => runtime.listTools() }],
+export function extensionCapability(definition, options = {}) {
+    const runtime = new ExtensionRuntime(definition, options);
+    const capability = {
+        name: definition.id,
+        contract: "detachable",
+        // The runtime already gives every handler its own budget (`timeoutMs`) and isolates its
+        // failure; an outer deadline would only cut a chain of individually-healthy handlers short.
+        hookTimeoutMs: Number.POSITIVE_INFINITY,
+        // Read once the extension has opened: what it published with `api.expose`, so
+        // `session.service(id)` is the extension's own control surface.
+        get service() {
+            return runtime.exposedHandle();
+        },
+        // An extension can touch the whole session surface, so this list IS the blast radius —
+        // written down once, here, instead of discovered by reading the runtime for lookups.
+        openSession: async (ctx) => {
+            if (ctx.controls === undefined)
+                throw new Error("an extension needs the session's controls");
+            await runtime.open({
+                environment: ctx.environment,
+                events: ctx.events,
+                steer: ctx.steer,
+                controls: ctx.controls,
+                readLog: () => readSessionLog(ctx),
+                store: ctx.store,
+            }, ctx);
+        },
+        closeSession: (reason) => runtime.close(reason),
+        toolProviders: [{ id: definition.id, listTools: () => runtime.listTools() }],
         toolFilters: [runtime.filterTools],
         gates: { compaction: runtime.compactionGate },
-        // Stable array reference — `setup` (openSession) fills it before any run assembles.
+        // Stable array references — `session` fills them before any run assembles.
         injectors: runtime.listInjectors(),
+        commands: runtime.commands,
+        // Read at each run's assembly: absent while no provider-tier handler is registered, so such a
+        // request is left byte-identical.
+        get provider() {
+            return runtime.hasProviderHandlers() ? runtime.providerHooks : undefined;
+        },
         hooks: {
             beforeRun: async (ctx) => runtime.beforeRun(ctx, ctx.input),
             beforeStep: async (ctx) => runtime.beforeStep(ctx, ctx.context, ctx.system),
@@ -32,10 +69,29 @@ 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(),
     };
+    runtimes.set(capability, runtime);
+    return capability;
+}
+/**
+ * A capability per extension, in order — what a session mounts for a list of definitions. A
+ * definition this session opted out of (`params[id] === false`) is left out entirely: never set
+ * up, never reported as attached.
+ */
+export function extensionsCapability(definitions, options = {}) {
+    const seen = new Set();
+    const out = [];
+    for (const definition of definitions) {
+        if (seen.has(definition.id))
+            throw new Error(`duplicate extension id "${definition.id}"`);
+        seen.add(definition.id);
+        const params = options.params?.[definition.id];
+        if (params === false)
+            continue;
+        out.push(extensionCapability(definition, { ...(options.host !== undefined ? { host: options.host } : {}), params }));
+    }
+    return out;
 }
 //# sourceMappingURL=index.js.map

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

@@ -10,6 +10,7 @@ import { readFile, readdir, stat, writeFile } from "node:fs/promises";
 import { join, resolve } from "node:path";
 import { createRequire } from "node:module";
 import { pathToFileURL } from "node:url";
+import { z } from "zod";
 /**
  * File-extension loader — the shell that turns a extension directory into extension VALUES for
  * `attachExtension`. The framework core stays file-blind: everything here ends in a plain
@@ -63,6 +64,15 @@ export function compareVersions(a, b) {
     }
     return 0;
 }
+/** The manifest as read from disk: only the fields above are checked; the rest pass through. */
+const ExtensionManifestSchema = z.looseObject({
+    id: z.string().refine((id) => id.trim().length > 0, 'must declare a non-empty string "id"'),
+    version: z.string().optional(),
+    entry: z.string().optional(),
+    engine: z.string().regex(VERSION_RE, 'must be a version like "1.2.0"').optional(),
+    name: z.string().optional(),
+    description: z.string().optional(),
+});
 const APPROVALS_FILE = ".approvals.json";
 export class ExtensionLoader {
     directory;
@@ -155,7 +165,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()];
     }
@@ -177,23 +187,21 @@ export class ExtensionLoader {
     async scan(dirName) {
         const dir = join(this.directory, dirName);
         const manifestPath = join(dir, "manifest.json");
-        let manifest;
+        let raw;
         try {
-            manifest = JSON.parse(await readFile(manifestPath, "utf8"));
+            raw = JSON.parse(await readFile(manifestPath, "utf8"));
         }
         catch (error) {
             throw new Error(`unreadable manifest.json: ${messageOf(error)}`);
         }
-        if (typeof manifest.id !== "string" || !manifest.id.trim()) {
-            throw new Error("manifest.json must declare a non-empty string \"id\"");
+        const parsed = ExtensionManifestSchema.safeParse(raw);
+        if (!parsed.success) {
+            const issues = parsed.error.issues.map((issue) => `${issue.path.length > 0 ? `"${issue.path.join(".")}" ` : ""}${issue.message}`);
+            throw new Error(`manifest.json: ${issues.join("; ")}`);
         }
-        if (manifest.engine !== undefined) {
-            if (typeof manifest.engine !== "string" || !VERSION_RE.test(manifest.engine)) {
-                throw new Error(`manifest "engine" must be a version like "1.2.0", got ${JSON.stringify(manifest.engine)}`);
-            }
-            if (compareVersions(FRAMEWORK_VERSION, manifest.engine) < 0) {
-                throw new Error(`requires operon-agents >= ${manifest.engine}; this host runs ${FRAMEWORK_VERSION}`);
-            }
+        const manifest = parsed.data;
+        if (manifest.engine !== undefined && compareVersions(FRAMEWORK_VERSION, manifest.engine) < 0) {
+            throw new Error(`requires operon-agents >= ${manifest.engine}; this host runs ${FRAMEWORK_VERSION}`);
         }
         const entryPath = join(dir, manifest.entry ?? "index.js");
         const stats = await stat(entryPath).catch(() => {
@@ -241,11 +249,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 +285,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

@@ -24,16 +24,16 @@ 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. */
+/** 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 {
@@ -44,12 +44,14 @@ export interface StagingOptions {
     /** The extension's data folder, already created. */
     readonly dataDir?: string;
     createSession: ExtensionHostContext["createSession"];
+    /** Resolve one of the definition's `uses` names to its service handle. */
+    service(name: string): unknown;
     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.
  */
@@ -59,7 +61,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;
@@ -73,10 +75,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;
@@ -86,14 +88,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,9 +10,9 @@
  * 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";
@@ -22,17 +22,18 @@ 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),
+        services: Object.freeze(Object.fromEntries((definition.uses ?? []).map((name) => [name, options.service(name)]))),
         ...(options.dir !== undefined ? { dir: options.dir } : {}),
         ...(options.dataDir !== undefined ? { dataDir: options.dataDir } : {}),
         warn: (message) => options.warn(`[extension ${definition.id}] ${message}`),
@@ -41,7 +42,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;
@@ -50,7 +51,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();
@@ -68,16 +69,16 @@ 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.
         for (const name of definition.uses ?? []) {
             if (!this.bridge.services.has(name)) {
                 await this.loader.unload(id);
@@ -91,7 +92,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).
      */
@@ -124,6 +125,7 @@ export class HarnessExtensionManager {
     async register(id, definition, options) {
         const staged = await this.stage(definition);
         const previous = this.loaded.get(id);
+        const record = { hasService: staged.service !== undefined };
         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
@@ -132,11 +134,11 @@ export class HarnessExtensionManager {
                 this.bridge.services.register(staged.service.name, staged.service.instance, staged.service.options);
             }
             this.sessionDefs.set(id, staged.sessionDef);
-            this.loaded.set(id, { hasService: staged.service !== undefined });
+            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.
+        // 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.
         await this.bridge.withBarrier([id], options.timeoutMs ?? DEFAULT_BARRIER_TIMEOUT_MS, async (held) => {
             for (const session of held()) {
                 if (session.attachedExtensionIds().includes(id))
@@ -156,20 +158,21 @@ export class HarnessExtensionManager {
                 await session.attachExtension(staged.sessionDef);
             }
         });
-        this.loaded.set(id, { hasService: staged.service !== undefined });
+        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,
             dir: await this.loader.manifestDir(definition.id),
             dataDir,
             createSession: (sessionOptions) => this.bridge.createSession(sessionOptions),
+            service: (name) => this.bridge.services.handle(name),
             warn: (message) => this.bridge.warn(message),
         });
     }