operon-agents 0.1.0-alpha.31 → 0.1.0-alpha.32

package/dist/extensions/index.d.ts

@@ -4,11 +4,13 @@ import { ExtensionRuntime } from "./runtime.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 type { ExtensionHostBridge, StagingOptions, HeldSession, StagedDefinition } from "./manager.ts";
+export { HarnessExtensionManager, ExtensionSettingsInvalidError, stageDefinition } from "./manager.ts";
+export type { ExtensionHostBridge, ExtensionStatus, StagingOptions, HeldSession, StagedDefinition } from "./manager.ts";
+export { createFileSettingsStore, resolveSettings, validateSettings, validateSettingsSchema, SETTINGS_PERMISSION_MODES } from "./settings.ts";
+export type { ExtensionSettingsStore, ExtensionSettingsView, SettingsFormat, SettingsIssue, SettingsSchema, SettingsSchemaType } from "./settings.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, ExtensionSessionEventContext, ExtensionSessionEndEvent, ExtensionSessionStartEvent, ExtensionState, ExtensionToolSpec, ExtensionStepEndEvent, ExtensionStepEndResult, ExtensionStepStartEvent, ExtensionStepStartResult, ExtensionToolAuthorizeEvent, ExtensionToolAuthorizeResult, ExtensionToolCallEvent, ExtensionToolCallResult, ExtensionToolResultEvent, ExtensionCompactionBeforeEvent, ExtensionCompactionBeforeResult, ExtensionProviderHeadersEvent, ExtensionProviderHeadersResult, ExtensionProviderPayloadEvent, ExtensionProviderPayloadResult, ExtensionProviderResponseEvent, ProviderHeaders, HarnessSessionHandle, ExtensionSessionOptions, ModelProvider, SessionEndReason, SessionStartReason, } from "./types.ts";
+export type { ExtensionActions, ExtensionAPI, ExtensionCommand, ExtensionCommandResult, ExtensionRecordEntry, ExtensionSteerOptions, ExtensionDefinition, ExtensionHostContext, ExtensionInheritedSetting, 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, ExtensionSessionOptions, 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;
 /**

package/dist/extensions/index.js

@@ -3,7 +3,8 @@ 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";
+export { HarnessExtensionManager, ExtensionSettingsInvalidError, stageDefinition } from "./manager.js";
+export { createFileSettingsStore, resolveSettings, validateSettings, validateSettingsSchema, SETTINGS_PERMISSION_MODES } from "./settings.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. */

package/dist/extensions/loader.d.ts

@@ -1,4 +1,5 @@
 import type { ExtensionDefinition } from "./types.ts";
+import { type SettingsSchema } from "./settings.ts";
 /** The slice of a session the loader swaps extensions on — `HarnessSession` satisfies it. */
 export interface ExtensionAttachTarget {
     attachExtension(definition: ExtensionDefinition): Promise<void>;
@@ -47,6 +48,13 @@ export interface ExtensionManifest {
     readonly name?: string;
     /** One line for listings. */
     readonly description?: string;
+    /**
+     * The extension's settings, as a JSON Schema subset (see `settings.ts` for what is supported —
+     * anything else makes the manifest unusable, never silently ignored). Declared here rather than
+     * in code so a host can show and edit them before the extension is loaded or approved; the
+     * extension reads the values as `host.settings` / `ctx.settings`.
+     */
+    readonly settings?: SettingsSchema;
 }
 export type ExtensionFileState = 
 /** Approved at the current mtime and produced a definition this loader holds. */
@@ -83,6 +91,11 @@ export declare class ExtensionLoader {
     manifestDir(id: string): Promise<string>;
     /** Every extension folder under the directory, with its trust/load state. */
     list(): Promise<ExtensionFileStatus[]>;
+    /** `list()`, with each usable folder's manifest beside its status. */
+    scanAll(): Promise<Array<{
+        readonly status: ExtensionFileStatus;
+        readonly manifest?: ExtensionManifest;
+    }>>;
     /**
      * Import one extension and approve it as it stands. The call itself is the consent — reserve
      * it for user-initiated actions, never for something an agent triggers on its own.

package/dist/extensions/loader.js

@@ -11,6 +11,7 @@ import { join, resolve } from "node:path";
 import { createRequire } from "node:module";
 import { pathToFileURL } from "node:url";
 import { z } from "zod";
+import { validateSettingsSchema } from "./settings.js";
 /**
  * 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
@@ -72,6 +73,7 @@ const ExtensionManifestSchema = z.looseObject({
     engine: z.string().regex(VERSION_RE, 'must be a version like "1.2.0"').optional(),
     name: z.string().optional(),
     description: z.string().optional(),
+    settings: z.unknown().optional(),
 });
 const APPROVALS_FILE = ".approvals.json";
 export class ExtensionLoader {
@@ -93,23 +95,30 @@ export class ExtensionLoader {
     }
     /** Every extension folder under the directory, with its trust/load state. */
     async list() {
+        return (await this.scanAll()).map((entry) => entry.status);
+    }
+    /** `list()`, with each usable folder's manifest beside its status. */
+    async scanAll() {
         const approvals = await this.readApprovals();
         const out = [];
         for (const entry of await this.readExtensionDirs()) {
             try {
                 const scanned = await this.scan(entry);
                 out.push({
-                    id: scanned.manifest.id,
-                    dir: scanned.dir,
-                    ...(scanned.manifest.version !== undefined ? { version: scanned.manifest.version } : {}),
-                    ...(scanned.manifest.engine !== undefined ? { engine: scanned.manifest.engine } : {}),
-                    ...(scanned.manifest.name !== undefined ? { name: scanned.manifest.name } : {}),
-                    ...(scanned.manifest.description !== undefined ? { description: scanned.manifest.description } : {}),
-                    state: this.stateOf(scanned, approvals),
+                    manifest: scanned.manifest,
+                    status: {
+                        id: scanned.manifest.id,
+                        dir: scanned.dir,
+                        ...(scanned.manifest.version !== undefined ? { version: scanned.manifest.version } : {}),
+                        ...(scanned.manifest.engine !== undefined ? { engine: scanned.manifest.engine } : {}),
+                        ...(scanned.manifest.name !== undefined ? { name: scanned.manifest.name } : {}),
+                        ...(scanned.manifest.description !== undefined ? { description: scanned.manifest.description } : {}),
+                        state: this.stateOf(scanned, approvals),
+                    },
                 });
             }
             catch (error) {
-                out.push({ id: entry, dir: join(this.directory, entry), state: "error", error: messageOf(error) });
+                out.push({ status: { id: entry, dir: join(this.directory, entry), state: "error", error: messageOf(error) } });
             }
         }
         return out;
@@ -199,6 +208,12 @@ export class ExtensionLoader {
             const issues = parsed.error.issues.map((issue) => `${issue.path.length > 0 ? `"${issue.path.join(".")}" ` : ""}${issue.message}`);
             throw new Error(`manifest.json: ${issues.join("; ")}`);
         }
+        if (parsed.data.settings !== undefined) {
+            const issues = validateSettingsSchema(parsed.data.settings);
+            if (issues.length > 0) {
+                throw new Error(`manifest.json "settings": ${issues.map((issue) => `${issue.path !== "" ? `${issue.path}: ` : ""}${issue.message}`).join("; ")}`);
+            }
+        }
         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}`);

package/dist/extensions/manager.d.ts

@@ -1,6 +1,19 @@
 import type { ExtensionDefinition, ExtensionHostContext } from "./types.ts";
 import { type ExtensionFileStatus } from "./loader.ts";
 import { ServiceRegistry, type ServiceOptions } from "./services.ts";
+import { type ExtensionSettingsStore, type ExtensionSettingsView, type SettingsIssue } from "./settings.ts";
+/** What `harness.extensions.list()` reports for one extension folder: its file status, and its
+ *  settings when its manifest declares some. */
+export interface ExtensionStatus extends ExtensionFileStatus {
+    readonly settings?: ExtensionSettingsView;
+}
+/** `setSettings` was handed a value its schema refuses; nothing was stored. */
+export declare class ExtensionSettingsInvalidError extends Error {
+    readonly name = "ExtensionSettingsInvalidError";
+    readonly extensionId: string;
+    readonly issues: readonly SettingsIssue[];
+    constructor(extensionId: string, issues: readonly SettingsIssue[]);
+}
 /** The session surface the barrier hands to a swap function. */
 export interface HeldSession {
     readonly id: string;
@@ -20,6 +33,7 @@ export interface ExtensionHostBridge {
     createSession(options: Parameters<ExtensionHostContext["createSession"]>[0], extensionId: string): Promise<{
         readonly id: string;
     }>;
+    readSessionMessages: ExtensionHostContext["readSessionMessages"];
     sessions(): readonly HeldSession[];
     /** Rendezvous every session holding one of `extensionIds` at its run boundary, run `fn` in
      *  the quiet moment (held() reads live — sessions born gated during the barrier appear). */
@@ -47,8 +61,12 @@ export interface StagingOptions {
     readonly dataDir?: string;
     createSession: ExtensionHostContext["createSession"];
     resumeSession: ExtensionHostContext["resumeSession"];
+    readSessionMessages: ExtensionHostContext["readSessionMessages"];
     /** Resolve one of the definition's `uses` names to its service handle. */
     service(name: string): unknown;
+    /** The extension's resolved settings — `host.settings` and `ctx.settings`. Absent when it
+     *  declares none (and always by value). */
+    readonly settings?: Readonly<Record<string, unknown>>;
     warn(message: string): void;
 }
 /**
@@ -68,12 +86,33 @@ export declare class HarnessExtensionManager {
     private readonly loaded;
     /** Definitions newborn sessions receive: every loaded extension's per-session half. */
     private readonly sessionDefs;
+    private readonly settingsStore;
+    /** The tail of each extension's settings writes — one at a time per extension. */
+    private readonly settingsWrites;
     constructor(options: {
         readonly directory: string;
         readonly dataDir: string;
+        readonly settings: ExtensionSettingsStore;
         readonly bridge: ExtensionHostBridge;
     });
-    list(): Promise<ExtensionFileStatus[]>;
+    /** Every extension folder, with its trust/load state and — when it declares them — its settings. */
+    list(): Promise<ExtensionStatus[]>;
+    /**
+     * One extension's settings: the schema its manifest declares, the value it reads (stored, over
+     * the defaults) and the issues found reading it. `undefined` when it declares none. Works for an
+     * extension that is not loaded or not approved — only its manifest is read.
+     */
+    getSettings(id: string): Promise<ExtensionSettingsView | undefined>;
+    /**
+     * Replace one extension's settings. The value is checked against its schema first — on any issue
+     * this throws `ExtensionSettingsInvalidError` and stores nothing. Once stored, a loaded extension
+     * is reloaded the coordinated way (its sessions meet at their run boundary; none is
+     * interrupted), so its `harness` half runs again against the new value. One write at a time per
+     * extension. An extension not loaded just keeps the value for its next load.
+     */
+    setSettings(id: string, value: unknown, options?: {
+        readonly timeoutMs?: number;
+    }): Promise<void>;
     /** What every new session is born with. Wire into the harness's extension evaluation. */
     sessionDefinitions(): ExtensionDefinition[];
     /**
@@ -100,6 +139,9 @@ export declare class HarnessExtensionManager {
     /** 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;
+    /** The settings an extension reads, from its manifest and the store; `undefined` when it
+     *  declares none. A store that cannot be read is reported, and the defaults are used. */
+    private settingsView;
     /** 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
      *  graph is depth 1. */

package/dist/extensions/manager.js

@@ -18,6 +18,18 @@ import { mkdir } from "node:fs/promises";
 import { join, resolve } from "node:path";
 import { ExtensionLoader } from "./loader.js";
 import { ServiceRegistry } from "./services.js";
+import { resolveSettings, validateSettings } from "./settings.js";
+/** `setSettings` was handed a value its schema refuses; nothing was stored. */
+export class ExtensionSettingsInvalidError extends Error {
+    name = "ExtensionSettingsInvalidError";
+    extensionId;
+    issues;
+    constructor(extensionId, issues) {
+        super(`settings for extension "${extensionId}" are invalid: ${issues.map((issue) => `${issue.path !== "" ? `${issue.path}: ` : ""}${issue.message}`).join("; ")}`);
+        this.extensionId = extensionId;
+        this.issues = issues;
+    }
+}
 function isPromiseLike(value) {
     return typeof value === "object" && value !== null && typeof value.then === "function";
 }
@@ -29,23 +41,37 @@ function isPromiseLike(value) {
  * moment `createHarness` returns.
  */
 export function stageDefinition(definition, options) {
+    const settings = options.settings;
+    const sessionDef = settings === undefined ? definition : withSessionSettings(definition, settings);
     if (definition.harness === undefined)
-        return { sessionDef: definition };
+        return { sessionDef };
     const host = {
         createSession: (sessionOptions) => options.createSession(sessionOptions),
         resumeSession: (id) => options.resumeSession(id),
+        readSessionMessages: (id, pageOptions) => options.readSessionMessages(id, pageOptions),
         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 } : {}),
+        ...(settings !== undefined ? { settings } : {}),
         warn: (message) => options.warn(`[extension ${definition.id}] ${message}`),
     };
     const finish = (instance) => ({
         service: { name: definition.id, instance, options: { replaceable: options.defaultReplaceable } },
-        sessionDef: definition,
+        sessionDef,
     });
     const result = definition.harness(host);
     return isPromiseLike(result) ? Promise.resolve(result).then(finish) : finish(result);
 }
+/** The definition, its `session` handed `settings` in its context. Everything else is read through
+ *  to the original (a prototype link, so a definition that is a class instance keeps its methods). */
+function withSessionSettings(definition, settings) {
+    const wrapped = Object.create(definition);
+    Object.defineProperty(wrapped, "session", {
+        enumerable: true,
+        value: (api, ctx) => definition.session.call(definition, api, { ...ctx, settings }),
+    });
+    return wrapped;
+}
 const DEFAULT_BARRIER_TIMEOUT_MS = 30_000;
 export class HarnessExtensionManager {
     loader;
@@ -56,13 +82,61 @@ export class HarnessExtensionManager {
     loaded = new Map();
     /** Definitions newborn sessions receive: every loaded extension's per-session half. */
     sessionDefs = new Map();
+    settingsStore;
+    /** The tail of each extension's settings writes — one at a time per extension. */
+    settingsWrites = new Map();
     constructor(options) {
         this.loader = new ExtensionLoader({ directory: options.directory });
         this.dataRoot = resolve(options.dataDir);
+        this.settingsStore = options.settings;
         this.bridge = options.bridge;
     }
-    list() {
-        return this.loader.list();
+    /** Every extension folder, with its trust/load state and — when it declares them — its settings. */
+    async list() {
+        const out = [];
+        for (const { status, manifest } of await this.loader.scanAll()) {
+            const settings = manifest === undefined ? undefined : await this.settingsView(manifest);
+            out.push(settings === undefined ? status : { ...status, settings });
+        }
+        return out;
+    }
+    /**
+     * One extension's settings: the schema its manifest declares, the value it reads (stored, over
+     * the defaults) and the issues found reading it. `undefined` when it declares none. Works for an
+     * extension that is not loaded or not approved — only its manifest is read.
+     */
+    async getSettings(id) {
+        return this.settingsView(await this.loader.manifest(id));
+    }
+    /**
+     * Replace one extension's settings. The value is checked against its schema first — on any issue
+     * this throws `ExtensionSettingsInvalidError` and stores nothing. Once stored, a loaded extension
+     * is reloaded the coordinated way (its sessions meet at their run boundary; none is
+     * interrupted), so its `harness` half runs again against the new value. One write at a time per
+     * extension. An extension not loaded just keeps the value for its next load.
+     */
+    async setSettings(id, value, options = {}) {
+        const previous = this.settingsWrites.get(id) ?? Promise.resolve();
+        const write = previous.catch(() => undefined).then(async () => {
+            const schema = (await this.loader.manifest(id)).settings;
+            if (schema === undefined)
+                throw new Error(`extension "${id}" declares no settings`);
+            const issues = validateSettings(schema, value);
+            if (issues.length > 0)
+                throw new ExtensionSettingsInvalidError(id, issues);
+            await this.settingsStore.put(id, value);
+            const record = this.loaded.get(id);
+            if (record !== undefined)
+                await this.register(id, record.definition, options);
+        });
+        this.settingsWrites.set(id, write);
+        try {
+            await write;
+        }
+        finally {
+            if (this.settingsWrites.get(id) === write)
+                this.settingsWrites.delete(id);
+        }
     }
     /** What every new session is born with. Wire into the harness's extension evaluation. */
     sessionDefinitions() {
@@ -126,7 +200,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 };
+        const record = { hasService: staged.service !== undefined, definition };
         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
@@ -168,16 +242,39 @@ export class HarnessExtensionManager {
         const dataDir = join(this.dataRoot, definition.id);
         if (definition.harness !== undefined)
             await mkdir(dataDir, { recursive: true });
+        const settings = await this.settingsView(await this.loader.manifest(definition.id));
+        for (const issue of settings?.issues ?? []) {
+            this.bridge.warn(`[extension ${definition.id}] setting ${issue.path !== "" ? `"${issue.path}"` : "(root)"} ${issue.message}`);
+        }
         return stageDefinition(definition, {
+            ...(settings !== undefined ? { settings: deepFreeze(settings.value) } : {}),
             defaultReplaceable: true,
             dir: await this.loader.manifestDir(definition.id),
             dataDir,
             createSession: (sessionOptions) => this.bridge.createSession(sessionOptions, definition.id),
             resumeSession: (id) => this.bridge.resumeSession(id, definition.id),
+            readSessionMessages: (id, pageOptions) => this.bridge.readSessionMessages(id, pageOptions),
             service: (name) => this.bridge.services.handle(name),
             warn: (message) => this.bridge.warn(message),
         });
     }
+    /** The settings an extension reads, from its manifest and the store; `undefined` when it
+     *  declares none. A store that cannot be read is reported, and the defaults are used. */
+    async settingsView(manifest) {
+        const schema = manifest.settings;
+        if (schema === undefined)
+            return undefined;
+        let stored;
+        const issues = [];
+        try {
+            stored = await this.settingsStore.get(manifest.id);
+        }
+        catch (error) {
+            issues.push({ path: "", message: `the stored settings could not be read (${error instanceof Error ? error.message : String(error)}); using the defaults` });
+        }
+        const resolved = resolveSettings(schema, stored);
+        return { schema, value: resolved.value, issues: [...issues, ...resolved.issues] };
+    }
     /** 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
      *  graph is depth 1. */
@@ -192,4 +289,13 @@ export class HarnessExtensionManager {
         return found;
     }
 }
+/** Settings are handed to an extension read-only: every half sees the same value. */
+function deepFreeze(value) {
+    if (typeof value === "object" && value !== null && !Object.isFrozen(value)) {
+        Object.freeze(value);
+        for (const child of Object.values(value))
+            deepFreeze(child);
+    }
+    return value;
+}
 //# sourceMappingURL=manager.js.map

package/dist/extensions/settings.d.ts

@@ -0,0 +1,82 @@
+import type { PermissionMode } from "operon-agents-core";
+/** One problem with a schema or a value, at a dotted path (`types.coder.permissionMode`; `""` is the root). */
+export interface SettingsIssue {
+    readonly path: string;
+    readonly message: string;
+}
+export type SettingsSchemaType = "object" | "array" | "string" | "integer" | "number" | "boolean";
+/** A string whose options the host provides. `model`: a `provider/model` id, rendered as the
+ *  host's model picker (only checked to be a string — the host owns the model list).
+ *  `permission-mode`: a `PermissionMode`, checked against that enum. */
+export type SettingsFormat = "model" | "permission-mode";
+/** The JSON Schema subset a manifest's `settings` is written in. */
+export interface SettingsSchema {
+    readonly type: SettingsSchemaType;
+    readonly title?: string;
+    readonly description?: string;
+    readonly default?: unknown;
+    readonly enum?: readonly unknown[];
+    readonly properties?: Readonly<Record<string, SettingsSchema>>;
+    readonly required?: readonly string[];
+    readonly additionalProperties?: SettingsSchema;
+    readonly propertyNames?: {
+        readonly pattern: string;
+    };
+    readonly items?: SettingsSchema;
+    readonly minimum?: number;
+    readonly maximum?: number;
+    readonly maxLength?: number;
+    readonly pattern?: string;
+    readonly format?: SettingsFormat;
+    readonly "x-multiline"?: boolean;
+    readonly "x-order"?: number;
+}
+/** Everything a host needs to render and edit one extension's settings. */
+export interface ExtensionSettingsView {
+    readonly schema: SettingsSchema;
+    /** The resolved value — what the extension reads as `host.settings`. */
+    readonly value: Readonly<Record<string, unknown>>;
+    /** Where the stored value did not fit the schema (each such field fell back to its default). */
+    readonly issues: readonly SettingsIssue[];
+}
+/** The `permission-mode` format's values. */
+export declare const SETTINGS_PERMISSION_MODES: readonly PermissionMode[];
+/**
+ * Check a manifest's `settings` against the supported subset. Empty ⇒ usable. The root must be an
+ * object schema (an extension's settings are a record of named fields), and every `default` must
+ * itself be a valid value.
+ */
+export declare function validateSettingsSchema(schema: unknown): SettingsIssue[];
+/**
+ * Check a value to be stored against `schema` — strict: a wrong type, an unknown key, a missing
+ * required field or a broken constraint is an issue, each at its path. Empty ⇒ it may be stored.
+ */
+export declare function validateSettings(schema: SettingsSchema, value: unknown): SettingsIssue[];
+/**
+ * Read a stored value through `schema` — lenient: what is missing takes its default, an unknown
+ * key is dropped, and an invalid field falls back to its default and is reported in `issues`.
+ * Never throws for a bad value; the result is always an object (the root is an object schema).
+ */
+export declare function resolveSettings(schema: SettingsSchema, stored: unknown): {
+    readonly value: Record<string, unknown>;
+    readonly issues: SettingsIssue[];
+};
+/**
+ * Where extensions' settings values are kept, by extension id — what `setSettings` writes and
+ * every `harness` half run reads. A value is stored as it was given (validated, but without the
+ * defaults filled in), so a default an update changes still reaches a field the user never set.
+ * Replace it with `createHarness({ extensionSettings })` to keep settings in the host's own store.
+ */
+export interface ExtensionSettingsStore {
+    /** The stored value, or `undefined` when none was ever stored. */
+    get(extensionId: string): Promise<unknown | undefined>;
+    put(extensionId: string, value: unknown): Promise<void>;
+}
+/**
+ * The default store: one JSON file per extension, `<directory>/<id>.json` — for a harness with an
+ * `extensionDir`, `<extensionDir>/.settings`. Apart from the extension's own `dataDir` on purpose:
+ * an extension cannot rewrite its settings past validation, and an update of its bundle leaves
+ * them alone. Writes go to a temporary file first and are renamed into place.
+ */
+export declare function createFileSettingsStore(directory: string): ExtensionSettingsStore;
+//# sourceMappingURL=settings.d.ts.map

package/dist/extensions/settings.js

@@ -0,0 +1,398 @@
+/**
+ * Extension settings: a manifest declares them as a small JSON Schema subset, the framework keeps
+ * the values (validated, defaulted), the extension reads them as `host.settings`, and a host
+ * renders one generic form from the schema — no settings page per extension.
+ *
+ * The schema lives in the manifest, not the code, because the manifest is read before any code is
+ * imported: settings can be shown and edited while the extension is not loaded or not yet
+ * approved to run.
+ *
+ * The subset (anything else is refused when the manifest is read, never silently ignored):
+ *
+ * | keyword                                          | meaning                                    |
+ * |--------------------------------------------------|--------------------------------------------|
+ * | `type`                                           | object, array, string, integer, number, boolean (required) |
+ * | `properties`, `required`                         | an object with fixed fields                |
+ * | `additionalProperties` (a schema) + `propertyNames.pattern` | an object whose keys come and go (a table) |
+ * | `items`                                          | the elements of an array                   |
+ * | `enum`, `default`                                | allowed values, the value when unset       |
+ * | `title`, `description`                           | labels for the form                        |
+ * | `minimum`, `maximum`, `maxLength`, `pattern`     | constraints                                |
+ * | `format`                                         | a string whose options the host provides: `model`, `permission-mode` |
+ * | `x-multiline`, `x-order`                         | rendering hints                            |
+ *
+ * Reading is lenient, writing is strict. A stored value is read through `resolveSettings`: a
+ * missing field takes its default, an unknown key is dropped, an invalid field falls back to its
+ * default and is reported — an extension update that changed its schema must not stop it from
+ * loading. A value to be stored goes through `validateSettings` and is refused on any issue.
+ */
+import { mkdir, readFile, rename, writeFile } from "node:fs/promises";
+import { join as joinPath } from "node:path";
+/** The `permission-mode` format's values. */
+export const SETTINGS_PERMISSION_MODES = ["manual", "workspace", "auto", "yolo"];
+const TYPES = new Set(["object", "array", "string", "integer", "number", "boolean"]);
+const FORMATS = new Set(["model", "permission-mode"]);
+const COMMON_KEYWORDS = ["type", "title", "description", "default", "enum", "x-order"];
+const KEYWORDS_BY_TYPE = {
+    object: new Set([...COMMON_KEYWORDS, "properties", "required", "additionalProperties", "propertyNames"]),
+    array: new Set([...COMMON_KEYWORDS, "items"]),
+    string: new Set([...COMMON_KEYWORDS, "maxLength", "pattern", "format", "x-multiline"]),
+    integer: new Set([...COMMON_KEYWORDS, "minimum", "maximum"]),
+    number: new Set([...COMMON_KEYWORDS, "minimum", "maximum"]),
+    boolean: new Set(COMMON_KEYWORDS),
+};
+/** Known JSON Schema keywords this first version does not support — named in the refusal, so an
+ *  author is told "not supported" rather than "unknown". */
+const RESERVED = new Set(["x-secret", "oneOf", "anyOf", "allOf", "not", "$ref", "const", "minLength", "minItems", "maxItems", "uniqueItems", "exclusiveMinimum", "exclusiveMaximum", "multipleOf", "patternProperties", "if", "then", "else"]);
+function join(path, key) {
+    return path === "" ? String(key) : `${path}.${key}`;
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function describe(path) {
+    return path === "" ? "the root" : `"${path}"`;
+}
+// ============================================================================
+// The schema itself
+// ============================================================================
+/**
+ * Check a manifest's `settings` against the supported subset. Empty ⇒ usable. The root must be an
+ * object schema (an extension's settings are a record of named fields), and every `default` must
+ * itself be a valid value.
+ */
+export function validateSettingsSchema(schema) {
+    const issues = [];
+    checkSchema(schema, "", issues);
+    if (issues.length === 0 && schema.type !== "object") {
+        issues.push({ path: "", message: 'settings must be an object schema ("type": "object")' });
+    }
+    return issues;
+}
+function checkSchema(schema, path, issues) {
+    const at = (message, sub = path) => {
+        issues.push({ path: sub, message });
+    };
+    if (!isRecord(schema))
+        return at("must be a schema object");
+    const type = schema.type;
+    if (typeof type !== "string" || !TYPES.has(type)) {
+        return at(`needs a "type": one of ${[...TYPES].join(", ")}`);
+    }
+    const allowed = KEYWORDS_BY_TYPE[type];
+    for (const key of Object.keys(schema)) {
+        if (allowed.has(key))
+            continue;
+        if (RESERVED.has(key))
+            at(`"${key}" is not supported in extension settings`);
+        else if (Object.values(KEYWORDS_BY_TYPE).some((keys) => keys.has(key)))
+            at(`"${key}" does not apply to a ${type}`);
+        else
+            at(`unknown keyword "${key}"`);
+    }
+    for (const key of ["title", "description"]) {
+        if (schema[key] !== undefined && typeof schema[key] !== "string")
+            at(`"${key}" must be a string`);
+    }
+    if (schema["x-order"] !== undefined && typeof schema["x-order"] !== "number")
+        at('"x-order" must be a number');
+    if (schema["x-multiline"] !== undefined && typeof schema["x-multiline"] !== "boolean")
+        at('"x-multiline" must be a boolean');
+    for (const key of ["minimum", "maximum"]) {
+        if (schema[key] !== undefined && (typeof schema[key] !== "number" || !Number.isFinite(schema[key])))
+            at(`"${key}" must be a number`);
+    }
+    if (schema.maxLength !== undefined && !(Number.isInteger(schema.maxLength) && schema.maxLength >= 0))
+        at('"maxLength" must be a non-negative integer');
+    if (schema.pattern !== undefined)
+        checkPattern(schema.pattern, '"pattern"', path, issues);
+    if (schema.format !== undefined && (typeof schema.format !== "string" || !FORMATS.has(schema.format))) {
+        at(`"format" must be one of ${[...FORMATS].join(", ")}`);
+    }
+    if (type === "object") {
+        if (schema.properties !== undefined) {
+            if (!isRecord(schema.properties))
+                at('"properties" must be an object of schemas');
+            else
+                for (const [key, sub] of Object.entries(schema.properties))
+                    checkSchema(sub, join(path, key), issues);
+        }
+        if (schema.required !== undefined) {
+            const properties = isRecord(schema.properties) ? schema.properties : {};
+            if (!Array.isArray(schema.required) || schema.required.some((key) => typeof key !== "string"))
+                at('"required" must be an array of property names');
+            else
+                for (const key of schema.required)
+                    if (!(key in properties))
+                        at(`"required" names "${key}", which is not in "properties"`);
+        }
+        if (schema.additionalProperties !== undefined) {
+            if (typeof schema.additionalProperties === "boolean")
+                at('"additionalProperties" must be a schema (unknown keys are always dropped)');
+            else
+                checkSchema(schema.additionalProperties, join(path, "*"), issues);
+        }
+        if (schema.propertyNames !== undefined) {
+            if (schema.additionalProperties === undefined)
+                at('"propertyNames" only applies with "additionalProperties"');
+            if (!isRecord(schema.propertyNames) || Object.keys(schema.propertyNames).some((key) => key !== "pattern") || schema.propertyNames.pattern === undefined) {
+                at('"propertyNames" supports only { "pattern": … }');
+            }
+            else
+                checkPattern(schema.propertyNames.pattern, '"propertyNames.pattern"', path, issues);
+        }
+    }
+    if (type === "array") {
+        if (schema.items === undefined)
+            at('an array needs "items"');
+        else
+            checkSchema(schema.items, join(path, "[]"), issues);
+    }
+    // Only once the schema is sound can its own values be checked against it.
+    if (issues.length > 0)
+        return;
+    if (schema.enum !== undefined) {
+        if (!Array.isArray(schema.enum) || schema.enum.length === 0)
+            at('"enum" must be a non-empty array');
+        else {
+            const leafOnly = { ...schema, enum: undefined, default: undefined };
+            schema.enum.forEach((value, index) => {
+                for (const issue of validateSettings(leafOnly, value))
+                    at(`"enum" value ${index}: ${issue.message}`);
+            });
+        }
+    }
+    if (schema.default !== undefined) {
+        for (const issue of validateSettings(schema, schema.default)) {
+            at(`"default" is not a valid value${issue.path !== "" ? ` at "${issue.path}"` : ""}: ${issue.message}`);
+        }
+    }
+}
+function checkPattern(pattern, label, path, issues) {
+    if (typeof pattern !== "string") {
+        issues.push({ path, message: `${label} must be a string` });
+        return;
+    }
+    try {
+        new RegExp(pattern, "u");
+    }
+    catch (error) {
+        issues.push({ path, message: `${label} is not a valid regular expression: ${error instanceof Error ? error.message : String(error)}` });
+    }
+}
+// ============================================================================
+// Values
+// ============================================================================
+/**
+ * Check a value to be stored against `schema` — strict: a wrong type, an unknown key, a missing
+ * required field or a broken constraint is an issue, each at its path. Empty ⇒ it may be stored.
+ */
+export function validateSettings(schema, value) {
+    const issues = [];
+    checkValue(schema, value, "", issues, true);
+    return issues;
+}
+/** The problems with `value` itself, for a leaf; for a container, its shape and — strictly —
+ *  everything under it. */
+function checkValue(schema, value, path, issues, strict) {
+    const at = (message, sub = path) => {
+        issues.push({ path: sub, message });
+    };
+    switch (schema.type) {
+        case "object": {
+            if (!isRecord(value))
+                return at("must be an object");
+            if (!strict)
+                return;
+            for (const [key, item] of Object.entries(value)) {
+                const property = schema.properties?.[key];
+                if (property !== undefined) {
+                    if (item !== undefined)
+                        checkValue(property, item, join(path, key), issues, true);
+                    continue;
+                }
+                if (schema.additionalProperties === undefined) {
+                    at("is not a known setting", join(path, key));
+                    continue;
+                }
+                const keyIssue = keyProblem(schema, key);
+                if (keyIssue !== undefined)
+                    at(keyIssue, join(path, key));
+                else
+                    checkValue(schema.additionalProperties, item, join(path, key), issues, true);
+            }
+            for (const key of schema.required ?? []) {
+                if (value[key] === undefined)
+                    at("is required", join(path, key));
+            }
+            break;
+        }
+        case "array": {
+            if (!Array.isArray(value))
+                return at("must be an array");
+            if (!strict)
+                return;
+            value.forEach((item, index) => checkValue(schema.items, item, join(path, index), issues, true));
+            break;
+        }
+        case "string": {
+            if (typeof value !== "string")
+                return at("must be a string");
+            if (schema.maxLength !== undefined && [...value].length > schema.maxLength)
+                at(`must be at most ${schema.maxLength} characters`);
+            if (schema.pattern !== undefined && !new RegExp(schema.pattern, "u").test(value))
+                at(`must match ${schema.pattern}`);
+            if (schema.format === "permission-mode" && !SETTINGS_PERMISSION_MODES.includes(value)) {
+                at(`must be a permission mode: ${SETTINGS_PERMISSION_MODES.join(", ")}`);
+            }
+            break;
+        }
+        case "integer":
+        case "number": {
+            if (typeof value !== "number" || !Number.isFinite(value))
+                return at("must be a number");
+            if (schema.type === "integer" && !Number.isInteger(value))
+                return at("must be an integer");
+            if (schema.minimum !== undefined && value < schema.minimum)
+                at(`must be at least ${schema.minimum}`);
+            if (schema.maximum !== undefined && value > schema.maximum)
+                at(`must be at most ${schema.maximum}`);
+            break;
+        }
+        case "boolean": {
+            if (typeof value !== "boolean")
+                at("must be true or false");
+            break;
+        }
+    }
+    if (schema.enum !== undefined && !schema.enum.some((allowed) => sameValue(allowed, value))) {
+        at(`must be one of ${schema.enum.map((allowed) => JSON.stringify(allowed)).join(", ")}`);
+    }
+}
+function keyProblem(schema, key) {
+    const pattern = schema.propertyNames?.pattern;
+    return pattern !== undefined && !new RegExp(pattern, "u").test(key) ? `the key "${key}" must match ${pattern}` : undefined;
+}
+function sameValue(a, b) {
+    return a === b || JSON.stringify(a) === JSON.stringify(b);
+}
+/**
+ * Read a stored value through `schema` — lenient: what is missing takes its default, an unknown
+ * key is dropped, and an invalid field falls back to its default and is reported in `issues`.
+ * Never throws for a bad value; the result is always an object (the root is an object schema).
+ */
+export function resolveSettings(schema, stored) {
+    const issues = [];
+    let source = stored;
+    if (stored !== undefined && !isRecord(stored)) {
+        issues.push({ path: "", message: "the stored settings are not an object; using the defaults" });
+        source = undefined;
+    }
+    const value = resolveValue(schema, source, "", issues);
+    return { value: isRecord(value) ? value : {}, issues };
+}
+function resolveValue(schema, value, path, issues) {
+    if (value === undefined)
+        return defaultOf(schema, path);
+    const problems = [];
+    checkValue(schema, value, path, problems, false);
+    if (problems.length > 0) {
+        issues.push(...problems.map((issue) => ({ ...issue, message: `${issue.message}; using the default` })));
+        return defaultOf(schema, path);
+    }
+    if (schema.type === "object") {
+        const record = value;
+        const out = {};
+        for (const [key, property] of Object.entries(schema.properties ?? {})) {
+            const resolved = resolveValue(property, record[key], join(path, key), issues);
+            if (resolved !== undefined)
+                out[key] = resolved;
+        }
+        if (schema.additionalProperties !== undefined) {
+            for (const [key, item] of Object.entries(record)) {
+                if (schema.properties?.[key] !== undefined || item === undefined)
+                    continue;
+                const keyIssue = keyProblem(schema, key);
+                if (keyIssue !== undefined) {
+                    issues.push({ path: join(path, key), message: `${keyIssue}; dropped` });
+                    continue;
+                }
+                const resolved = resolveValue(schema.additionalProperties, item, join(path, key), issues);
+                if (resolved !== undefined)
+                    out[key] = resolved;
+            }
+        }
+        const missing = (schema.required ?? []).filter((key) => out[key] === undefined);
+        if (missing.length > 0) {
+            issues.push({ path, message: `${missing.map((key) => `"${key}"`).join(", ")} ${missing.length > 1 ? "are" : "is"} required; using the default` });
+            return defaultOf(schema, path);
+        }
+        return out;
+    }
+    if (schema.type === "array") {
+        return value.flatMap((item, index) => {
+            const resolved = resolveValue(schema.items, item, join(path, index), issues);
+            return resolved === undefined ? [] : [resolved];
+        });
+    }
+    return value;
+}
+/**
+ * What an unset field reads as: its `default` (itself resolved, so an object default gains the
+ * defaults of the fields it leaves out); for an object without one, the defaults of its fields —
+ * `undefined` when that comes to nothing or misses a required field.
+ */
+function defaultOf(schema, path) {
+    if (schema.default !== undefined) {
+        // A default was checked against the schema when the manifest was read.
+        return resolveValue({ ...schema, default: undefined }, structuredClone(schema.default), path, []);
+    }
+    if (schema.type !== "object" || schema.properties === undefined)
+        return path === "" && schema.type === "object" ? {} : undefined;
+    const out = {};
+    for (const [key, property] of Object.entries(schema.properties)) {
+        const value = defaultOf(property, join(path, key));
+        if (value !== undefined)
+            out[key] = value;
+    }
+    if ((schema.required ?? []).some((key) => out[key] === undefined))
+        return undefined;
+    return Object.keys(out).length > 0 || path === "" ? out : undefined;
+}
+/**
+ * The default store: one JSON file per extension, `<directory>/<id>.json` — for a harness with an
+ * `extensionDir`, `<extensionDir>/.settings`. Apart from the extension's own `dataDir` on purpose:
+ * an extension cannot rewrite its settings past validation, and an update of its bundle leaves
+ * them alone. Writes go to a temporary file first and are renamed into place.
+ */
+export function createFileSettingsStore(directory) {
+    const fileOf = (extensionId) => {
+        if (!/^[A-Za-z0-9._-]+$/.test(extensionId) || extensionId.startsWith("."))
+            throw new Error(`not an extension id: ${JSON.stringify(extensionId)}`);
+        return joinPath(directory, `${extensionId}.json`);
+    };
+    let counter = 0;
+    return {
+        async get(extensionId) {
+            let text;
+            try {
+                text = await readFile(fileOf(extensionId), "utf8");
+            }
+            catch (error) {
+                if (error.code === "ENOENT")
+                    return undefined;
+                throw error;
+            }
+            return JSON.parse(text);
+        },
+        async put(extensionId, value) {
+            const file = fileOf(extensionId);
+            await mkdir(directory, { recursive: true });
+            counter += 1;
+            const temporary = `${file}.${process.pid}.${counter}.tmp`;
+            await writeFile(temporary, `${JSON.stringify(value, null, 2)}\n`, "utf8");
+            await rename(temporary, file);
+        },
+    };
+}
+//# sourceMappingURL=settings.js.map

package/dist/extensions/types.d.ts

@@ -24,7 +24,7 @@
  * `ExtensionRuntime` is the façade that hides which physical channel a decision point arrives on;
  * extension authors only ever see one `api.on(...)` table.
  */
-import type { AgentEvent, AssistantMessage, ChatModel, AgentInput, ContextBreakdown, ConversationContext, Injector, LlmRequest, Environment, Message, ModelManager, RunResult, SessionConfig, SessionSummary, PendingApprovalInterrupt, SessionStore, SteerContent, SteerOptions, SteerOrigin, SteerReceipt, StepStopReason, TerminalStepStopReason, ThinkingLevel, Tool, ToolPlan, ToolResult, ToolResultContent, ToolRunContext, Usage } from "operon-agents-core";
+import type { AgentEvent, AssistantMessage, ChatModel, AgentInput, ContextBreakdown, ConversationContext, Injector, LlmRequest, Environment, Message, ModelManager, RunResult, SessionConfig, SessionSummary, PendingApprovalInterrupt, SessionStore, SteerContent, SteerOptions, SteerOrigin, SteerReceipt, StepStopReason, TerminalStepStopReason, ThinkingLevel, TranscriptPage, TranscriptPageOptions, Tool, ToolPlan, ToolResult, ToolResultContent, ToolRunContext, Usage } from "operon-agents-core";
 /** Per-extension key/value state, namespaced into the session store (memory without one). */
 /** A slash command an extension carries (see `ExtensionAPI.registerCommand`). The run
  *  receives only the raw argument string — an extension command closes over what it needs. */
@@ -517,6 +517,8 @@ export interface ExtensionAPI {
     /** The same imperative surface handlers get via `ctx.actions`, usable from `session`. */
     readonly actions: ExtensionActions;
 }
+/** What `ExtensionHostContext.createSession` can copy from its `from` session. */
+export type ExtensionInheritedSetting = "model";
 /**
  * What an extension's `harness` half is handed — the harness reach it needs to build a
  * process-shared instance. Deliberately narrow: session creation (a spawn factory's one
@@ -524,9 +526,12 @@ export interface ExtensionAPI {
  * of the services it declared in `uses`. No service-registration call: the instance IS the
  * return value, registered under the extension's `id`.
  */
-export interface ExtensionHostContext<TServices extends Readonly<Record<string, unknown>> = Readonly<Record<string, unknown>>> {
+export interface ExtensionHostContext<TServices extends Readonly<Record<string, unknown>> = Readonly<Record<string, unknown>>, TSettings = unknown> {
     /** Get a session by id, loading it if it is not loaded — `harness.resumeSession(id)`. */
     resumeSession(id: string): Promise<HarnessSessionHandle>;
+    /** One page of a session's transcript WITHOUT loading it — `harness.readSessionMessages(id)`.
+     *  A parked session stays parked: reading never resumes it. */
+    readSessionMessages(id: string, options?: TranscriptPageOptions): Promise<TranscriptPage>;
     /**
      * Open a brand-new session on this harness — what a spawn factory calls. The options are
      * `harness.createSession`'s own (`title`, `workDir`, `ownerKey`, `config`, …); a key the harness
@@ -537,6 +542,11 @@ export interface ExtensionHostContext<TServices extends Readonly<Record<string,
      * otherwise, the host's `resolveSession` is told its source, and — because it runs for the same
      * party — where that session runs in an environment of its own (a sandbox), the new one must be
      * given one too: it is refused rather than opened on the harness's own machine.
+     *
+     * `inherit` names settings copied from that `from` session as it is right now, for each one
+     * `config` does not set itself — `"model"`: the model it currently runs on (a runtime
+     * `setModel` included). A source on the harness default, or on a model given as a live object,
+     * has no model to copy, and the new session takes the harness default. Requires `from`.
      */
     createSession(options?: {
         readonly title?: string;
@@ -544,6 +554,7 @@ export interface ExtensionHostContext<TServices extends Readonly<Record<string,
         readonly ownerKey?: string;
         readonly config?: SessionConfig;
         readonly from?: string;
+        readonly inherit?: readonly ExtensionInheritedSetting[];
     }): Promise<{
         readonly id: string;
     }>;
@@ -565,6 +576,14 @@ export interface ExtensionHostContext<TServices extends Readonly<Record<string,
      * by value it is opt-in (`createHarness({ extensionDataDir })`).
      */
     readonly dataDir?: string;
+    /**
+     * This extension's settings, as the user set them over the defaults its manifest declares
+     * (`manifest.json` `settings`) — read-only, and checked against that schema: a field that does
+     * not fit reads as its default. A settings change reloads the extension, so this half runs again
+     * with the new value. `undefined` when the manifest declares no settings, and always for an
+     * extension passed by value (its host gives it options in code instead).
+     */
+    readonly settings?: Readonly<TSettings>;
     warn(message: string): void;
 }
 /**
@@ -574,7 +593,7 @@ export interface ExtensionHostContext<TServices extends Readonly<Record<string,
  * others') and
  * arrives resolved.
  */
-export interface ExtensionSessionContext<TShared = unknown, TParams = unknown, TServices extends Readonly<Record<string, unknown>> = Readonly<Record<string, unknown>>> {
+export interface ExtensionSessionContext<TShared = unknown, TParams = unknown, TServices extends Readonly<Record<string, unknown>> = Readonly<Record<string, unknown>>, TSettings = unknown> {
     /** Handle to this extension's own shared instance — its `harness` result, one per process;
      *  `undefined` when the definition has no `harness` half. */
     readonly shared: TShared;
@@ -586,6 +605,9 @@ export interface ExtensionSessionContext<TShared = unknown, TParams = unknown, T
      * die with the extension (after detach every call throws `ServiceUnavailableError`).
      */
     readonly services: TServices;
+    /** The same settings the `harness` half was given (`ExtensionHostContext.settings`): the value
+     *  as of the last load or settings change. `undefined` when the manifest declares none. */
+    readonly settings?: Readonly<TSettings>;
 }
 /**
  * An extension: a programmatic participant assembled into a session. One definition, handed to
@@ -604,11 +626,11 @@ export interface ExtensionSessionContext<TShared = unknown, TParams = unknown, T
  *   session varies it with `createSession({ config: { extensions: { [id]: … } } })` — `ctx.params` — and opts
  *   out of it entirely with `false`.
  *
- * `TShared`/`TParams`/`TServices` are for the author's own typing (use an object type alias for
+ * `TShared`/`TParams`/`TServices`/`TSettings` are for the author's own typing (use an object type alias for
  * `TServices`, not an interface); the framework holds definitions as `ExtensionDefinition` and
  * every concrete definition is assignable to it.
  */
-export interface ExtensionDefinition<TShared = unknown, TParams = unknown, TServices extends Readonly<Record<string, unknown>> = Readonly<Record<string, unknown>>> {
+export interface ExtensionDefinition<TShared = unknown, TParams = unknown, TServices extends Readonly<Record<string, unknown>> = Readonly<Record<string, unknown>>, TSettings = unknown> {
     readonly id: string;
     /** Per-handler invocation budget. Defaults to 30s for decision points, 1s for observers. */
     readonly timeoutMs?: number;
@@ -619,10 +641,10 @@ export interface ExtensionDefinition<TShared = unknown, TParams = unknown, TServ
      */
     readonly forkParams?: "inherit" | "drop";
     /** The process-shared half: once per harness. See above. */
-    harness?(host: ExtensionHostContext<TServices>): TShared | Promise<TShared>;
+    harness?(host: ExtensionHostContext<TServices, TSettings>): TShared | Promise<TShared>;
     /** Services this extension consumes, by name — other extensions' shared-half results (their
      *  `id`s) or host-registered `services`. Resolved into `ctx.services` for `session`. */
     readonly uses?: readonly (keyof TServices & string)[];
-    session(api: ExtensionAPI, ctx: ExtensionSessionContext<TShared, TParams, TServices>): void | (() => void | Promise<void>) | Promise<void | (() => void | Promise<void>)>;
+    session(api: ExtensionAPI, ctx: ExtensionSessionContext<TShared, TParams, TServices, TSettings>): void | (() => void | Promise<void>) | Promise<void | (() => void | Promise<void>)>;
 }
 //# sourceMappingURL=types.d.ts.map

package/dist/harness.d.ts

@@ -1,7 +1,8 @@
+import { type TranscriptPage, type TranscriptPageOptions } from "operon-agents-core";
 import { type TelemetryService, type AgentEventListener, type AgentInput, SessionProjection, type SessionSnapshot, type SnapshotOptions, type DirectoryEntry, type ProjectionObservation, type ProjectionListener, type ApprovalRequest, type ApprovalResponse, type Capability, type InterruptAnswer, type ChatModel, type RunOptions, ListenerSink, type AutoApprover, type PermissionMode, type PermissionRule, type PendingRunInterrupt, type QuestionRequest, type QuestionResult, type Responder, type RunHandle, type RunResult, type SessionHandle, type SessionSummary, type ListSessionsFilter, type OpenSessionOptions, type DeleteSessionOptions, type ThinkingLevel, type Tool, type SteerMessage, type SteerOptions, type SteerOrigin, type SteerReceipt, Agent, Runner, Session, McpOAuthService, SkillRegistry, type HookDef, type McpServerConfig, type McpTransportKind, type McpCredentialProvider, type PluginManager, type ApprovalRequestOptions, type Environment, type EnvironmentFactory, type SessionRepository, type ResolvedAgentProfile, type SubagentProvider, type SessionConfig, type HarnessConfig, type SessionPolicy, type SessionMcpConfig, type SkillsConfig } from "operon-agents-core";
 import type { SkillsService, CompactionService, BackgroundManager, McpServersHandle, McpServersCapabilityOptions, GoalStore, PlanMode, Logger, ModelManager, TracingProcessor } from "operon-agents-core";
 import { type WorkspaceMcpPool } from "./workspace-mcp.ts";
-import { HarnessExtensionManager, ServiceRegistry, type ExtensionDefinition, type ServiceOptions } from "./extensions/index.ts";
+import { HarnessExtensionManager, ServiceRegistry, type ExtensionDefinition, type ExtensionSettingsStore, type ServiceOptions } from "./extensions/index.ts";
 import { type CommandResult, type TodoItem } from "operon-agents-core";
 export type ApprovalHandler = (request: ApprovalRequest, options?: ApprovalRequestOptions) => Promise<ApprovalResponse> | ApprovalResponse;
 export type QuestionHandler = (request: QuestionRequest, options?: {
@@ -128,8 +129,10 @@ export interface SessionResolveRequest<TContext = unknown> {
 /**
  * What the host resolves for one open. A `config` returned here is FINAL — the host saw what was
  * requested and what was stored and decided — and is not stored by the harness, so a host that
- * keeps configuration in its own database has exactly one copy. `bindings` are laid over the
- * requested ones key by key.
+ * keeps configuration in its own database has exactly one copy. What IS stored is unchanged by
+ * it: a reopen keeps the setup the session had, and a create stores what it was asked for (its
+ * `requested.config` — for a session an extension creates, that extension's parameters), so the
+ * next open's `stored` still carries it. `bindings` are laid over the requested ones key by key.
  */
 export interface SessionResolution<TContext = unknown> {
     readonly config?: SessionConfig;
@@ -398,6 +401,13 @@ export interface HarnessOptions<TContext = unknown> {
      * `undefined`). Kept outside the code folders so an update never touches state.
      */
     readonly extensionDataDir?: string;
+    /**
+     * Where file extensions' settings values are kept (`harness.extensions.setSettings`, read as
+     * `host.settings`). Defaults to one JSON file per extension in `<extensionDir>/.settings` — apart
+     * from the extensions' own data folders, so an extension cannot rewrite its settings past
+     * validation. Replace it to keep settings in the host's own store. Only with `extensionDir`.
+     */
+    readonly extensionSettings?: ExtensionSettingsStore;
     /**
      * Programmatic runtime extensions, registered once here — the by-value twin of `extensionDir`.
      * Every definition's `session` runs in every session; a session varies that with
@@ -964,6 +974,10 @@ export declare class Harness<TContext = unknown, TOutput = unknown> {
      * provided for it too.
      */
     private createFromExtension;
+    /** The model a session runs on right now, by name: the loaded instance's setting (a runtime
+     *  `setModel` included), or — when it is not loaded here — the one stored with it. `undefined`
+     *  when it runs on the harness default or on a model given as a live object. */
+    private currentModelOf;
     /** The session an extension is acting from, as the source of what it creates: the loaded
      *  instance, or — when it is not loaded here — what is stored with it. */
     private sourceOf;
@@ -973,6 +987,18 @@ export declare class Harness<TContext = unknown, TOutput = unknown> {
      *  reconciling background tasks, or subscribing Projection. Intended for read-only servers.
      *  Soft-deleted sessions resolve only with `{ includeDeleted: true }` — audit/purge tooling. */
     inspectSession(id: string, options?: OpenSessionOptions): Promise<SessionHandle | undefined>;
+    /**
+     * One page of a session's transcript, newest page first — open or closed alike, and NEVER by
+     * opening it: a closed session stays closed (no Session built, no capabilities, no recovery).
+     * What happened, including messages a compaction has since summarized away; see
+     * `readTranscriptPage` for exactly what is read. Page backwards with the returned `next`.
+     *
+     * An open session is read through its own store after its pending appends have landed, so a
+     * message appended a moment ago is already on the page. Only durable records are read: text
+     * still streaming is not on any page — follow it live with `observeProjection`.
+     * Soft-deleted and unknown ids throw `SessionRepositoryNotFoundError`.
+     */
+    readSessionMessages(id: string, options?: TranscriptPageOptions): Promise<TranscriptPage>;
     /** Read one catalog row without the O(N) `listSessions()` scan. */
     getSessionSummary(id: string): Promise<SessionSummary | undefined>;
     /** Close one open session by id (no-op if it isn't open). An open in flight for this id is

package/dist/harness.js

@@ -14,12 +14,13 @@
 import { randomUUID } from "node:crypto";
 import { AsyncLocalStorage } from "node:async_hooks";
 import { closeDeadlines } from "./harness-test-hooks.js";
+import { readTranscriptPage } from "operon-agents-core";
 import { readSessionTails, SessionProjection, ListenerSink, Agent, buildAgentFromProfile, INTERRUPTION_STATE_KEY, flattenPendingInterrupts, parseInterruptionState, Runner, Session, emptyUsage, isGuardrailTripwireError, askUserQuestionTool, createAutoApprover, createModelManager, backgroundCapability, compactionCapability, filesystemTools, goalCapability, LocalEnvironment, McpOAuthService, MemorySessionRepository, SessionRepositoryNotFoundError, SessionBusyError, SessionClosedError, SessionInterruptedError, SessionNotInterruptedError, SteerTargetNotFoundError, isAbortError, planCapability, skillsCapability, SkillRegistry, mcpServersCapability, pluginsCapability, userHooksCapability, taskCapability, workflowCapability, DEFAULT_AGENT_PROFILES, DEFAULT_AGENT_PROFILE_NAME, DEFAULT_SUBAGENT_NAMES, profileSubagentProvider, DEFAULT_ADDRESS, envLogger, noopLogger, parseSessionConfig, resolveSessionConfig, inlineMcpSecretPaths, sessionPolicyViolation, hookDefsFromConfig, SessionPolicySchema, SESSION_MODEL_KEY, SESSION_PERMISSION_KEY, SESSION_THINKING_KEY } from "operon-agents-core";
 import { recoverOrphanedTurns } from "operon-agents-core/internal";
 import { mkdirSync } from "node:fs";
 import { workspaceMcpCapability } from "./workspace-mcp.js";
 import { join } from "node:path";
-import { extensionCapability, extensionRuntimeOf, extensionsCapability, HarnessExtensionManager, ServiceRegistry, stageDefinition } from "./extensions/index.js";
+import { extensionCapability, extensionRuntimeOf, extensionsCapability, HarnessExtensionManager, ServiceRegistry, stageDefinition, createFileSettingsStore } from "./extensions/index.js";
 import { createExtensionCommandRegistry } from "operon-agents-core";
 /** The harness has been closed and can open nothing further. */
 export class HarnessClosedError extends Error {
@@ -97,8 +98,10 @@ const SESSION_CONFIG_STATE_KEY = "session:config";
 const DEFAULT_PERMISSION_MODE = "workspace";
 /** Every key `createSession` takes — what an extension's options are checked against. */
 const CREATE_SESSION_OPTION_KEYS = new Set([
-    "workDir", "ownerKey", "title", "config", "from",
+    "workDir", "ownerKey", "title", "config", "from", "inherit",
 ]);
+/** What an extension's `createSession({ from, inherit })` can copy from its source. */
+const INHERITABLE_SETTINGS = new Set(["model"]);
 function definedOnly(value) {
     return Object.fromEntries(Object.entries(value).filter(([, v]) => v !== undefined));
 }
@@ -1186,10 +1189,12 @@ export class Harness {
             : new HarnessExtensionManager({
                 directory: options.extensionDir,
                 dataDir: this.dataRoot ?? join(options.extensionDir, ".data"),
+                settings: options.extensionSettings ?? createFileSettingsStore(join(options.extensionDir, ".settings")),
                 bridge: {
                     services: this.services,
                     resumeSession: (id, extensionId) => this.resumeFrom(id, undefined, { kind: "extension", extensionId }),
                     createSession: (sessionOptions, extensionId) => this.createFromExtension(sessionOptions, extensionId),
+                    readSessionMessages: (id, pageOptions) => this.readSessionMessages(id, pageOptions),
                     sessions: () => [...this.activeSessions.values()],
                     withBarrier: (extensionIds, timeoutMs, fn) => this.withBarrier(extensionIds, timeoutMs, fn),
                     warn: (message) => console.warn(`[extensions] ${message}`),
@@ -1288,6 +1293,7 @@ export class Harness {
                     return this.createFromExtension(sessionOptions, definition.id);
                 },
                 resumeSession: (id) => this.resumeFrom(id, undefined, { kind: "extension", extensionId: definition.id }),
+                readSessionMessages: (id, pageOptions) => this.readSessionMessages(id, pageOptions),
                 service: (name) => this.services.handle(name),
                 warn: (message) => console.warn(`[extensions] ${message}`),
             });
@@ -1574,10 +1580,37 @@ export class Harness {
         if (unknown.length > 0) {
             throw new HarnessConfigError(`createSession from an extension got unknown option${unknown.length > 1 ? "s" : ""} ${unknown.map((key) => `"${key}"`).join(", ")}; per-extension parameters go in config.extensions`);
         }
-        const { from, ...rest } = (sessionOptions ?? {});
+        const { from, inherit, ...rest } = (sessionOptions ?? {});
         if (from !== undefined && typeof from !== "string")
             throw new HarnessConfigError("createSession from an extension: `from` is the id of the session it is created on behalf of");
-        return this.createFrom({ ...rest, origin: { kind: "extension", extensionId } }, from === undefined ? undefined : await this.sourceOf(from));
+        if (inherit !== undefined) {
+            if (!Array.isArray(inherit) || inherit.some((key) => !INHERITABLE_SETTINGS.has(key))) {
+                throw new HarnessConfigError(`createSession from an extension: \`inherit\` lists settings to copy from \`from\` — any of ${[...INHERITABLE_SETTINGS].map((key) => `"${key}"`).join(", ")}`);
+            }
+            if (from === undefined)
+                throw new HarnessConfigError("createSession from an extension: `inherit` copies from the `from` session, so it needs one");
+        }
+        const source = from === undefined ? undefined : await this.sourceOf(from);
+        let options = rest;
+        if (from !== undefined && inherit?.includes("model") === true && rest.config?.model === undefined) {
+            const model = await this.currentModelOf(from);
+            if (model !== undefined)
+                options = { ...rest, config: { ...(rest.config ?? {}), model } };
+        }
+        return this.createFrom({ ...options, origin: { kind: "extension", extensionId } }, source);
+    }
+    /** The model a session runs on right now, by name: the loaded instance's setting (a runtime
+     *  `setModel` included), or — when it is not loaded here — the one stored with it. `undefined`
+     *  when it runs on the harness default or on a model given as a live object. */
+    async currentModelOf(sessionId) {
+        const live = this.activeSessions.get(sessionId);
+        if (live !== undefined) {
+            const setting = live.modelSetting;
+            return typeof setting === "string" ? setting : undefined;
+        }
+        const handle = await (await this.repository()).open(sessionId);
+        const stored = await handle?.store.getState(SESSION_MODEL_KEY);
+        return typeof stored === "string" ? stored : undefined;
     }
     /** The session an extension is acting from, as the source of what it creates: the loaded
      *  instance, or — when it is not loaded here — what is stored with it. */
@@ -1606,6 +1639,31 @@ export class Harness {
     async inspectSession(id, options) {
         return (await this.repository()).open(id, options);
     }
+    /**
+     * One page of a session's transcript, newest page first — open or closed alike, and NEVER by
+     * opening it: a closed session stays closed (no Session built, no capabilities, no recovery).
+     * What happened, including messages a compaction has since summarized away; see
+     * `readTranscriptPage` for exactly what is read. Page backwards with the returned `next`.
+     *
+     * An open session is read through its own store after its pending appends have landed, so a
+     * message appended a moment ago is already on the page. Only durable records are read: text
+     * still streaming is not on any page — follow it live with `observeProjection`.
+     * Soft-deleted and unknown ids throw `SessionRepositoryNotFoundError`.
+     */
+    async readSessionMessages(id, options) {
+        const live = this.getSession(id);
+        const liveStore = live?.core.store;
+        if (live !== undefined && liveStore !== undefined) {
+            await live.core.flushEvents();
+            return readTranscriptPage(liveStore, options);
+        }
+        const handle = await this.inspectSession(id);
+        if (handle === undefined)
+            throw new SessionRepositoryNotFoundError(id);
+        // Not closed on purpose: a read holds nothing, and some repositories hand back the very
+        // store a later open will use (the in-memory one) — closing it here would close that.
+        return readTranscriptPage(handle.store, options);
+    }
     /** Read one catalog row without the O(N) `listSessions()` scan. */
     async getSessionSummary(id) {
         return (await this.repository()).get(id);
@@ -2105,7 +2163,10 @@ export class Harness {
             const sessionTools = bindings.tools ?? (effective.tools !== undefined ? this.toolsNamed(id, effective.tools) : undefined);
             // Store the setup: only what was explicitly configured (never the harness defaults, so a
             // change to those still reaches this session), and never what the host resolves each time.
-            const storedConfig = withoutModel(fromResolver ? inherited : explicit);
+            // A host's config replaces what is stored for THIS open only: a reopen keeps the setup it
+            // had, and a create keeps what it was asked for — so what the caller set (an extension's
+            // parameters for the session it spawns, say) survives a host that resolves every open.
+            const storedConfig = withoutModel(fromResolver ? (operation === "create" ? asked : inherited) : explicit);
             const requires = SESSION_BINDING_KEYS.filter((key) => bindings[key] !== undefined || (operation !== "create" && stored.requires.includes(key)));
             const changed = JSON.stringify({ config: storedConfig, requires }) !== JSON.stringify({ config: stored.config, requires: stored.requires });
             if (changed) {
@@ -2387,7 +2448,7 @@ function isServiceDescriptor(value) {
 /** Every key `createHarness` takes. */
 const HARNESS_OPTION_KEYS = new Set([
     "config", "registry", "resolveSession", "context", "autoApprover", "modelManager", "infrastructure",
-    "sessionCapabilities", "telemetry", "services", "extensions", "extensionDir", "extensionDataDir", "extraSubagentProfiles",
+    "sessionCapabilities", "telemetry", "services", "extensions", "extensionDir", "extensionDataDir", "extensionSettings", "extraSubagentProfiles",
 ]);
 /** Where each option `createHarness` used to take flat lives now. */
 const MOVED_HARNESS_OPTIONS = {

package/dist/index.d.ts

@@ -17,10 +17,13 @@ export type { LocalDeploymentOptions } from "./local.ts";
 export { Agent, defineAgent, defineTool, handoff } from "operon-agents-core";
 export type { AgentConfig, AgentGuardrails, AgentRunContext, FunctionToolDef, HandoffOptions, OutputSchema, ResolveToolDef, Tool, ToolPlan, ToolResolveContext, ToolResult, ToolReturn, ToolRunContext, } from "operon-agents-core";
 export type { AgentEvent, AgentInput, ApprovalRequest, ApprovalResponse, CompletedRunResult, FailedRunResult, GuardrailBlockedRunResult, InterruptAnswer, InterruptedRunResult, PendingRunInterrupt, QuestionRequest, QuestionResult, RunError, RunResult, RunStatus, SteerReceipt, StoppedRunResult, } from "operon-agents-core";
+export type { TranscriptCompactionItem, TranscriptItem, TranscriptMessageItem, TranscriptPage, TranscriptPageOptions, } from "operon-agents-core";
 export { GuardrailTripwireError, SessionBusyError, SessionClosedError, SessionInterruptedError, SessionNotInterruptedError, SessionRepositoryConflictError, SessionRepositoryNotFoundError, SteerTargetNotFoundError, } from "operon-agents-core";
 export type { AutoApprover, PermissionMode, PermissionRule } from "operon-agents-core";
 export { createModelManager, defineModel, LocalEnvironment } from "operon-agents-core";
 export type { ChatModel, Environment, EnvironmentFactory, ImageContent, Message, ModelManager, ModelSettings, TextContent, ThinkingLevel, Usage, } from "operon-agents-core";
 export type { ExtensionActions, ExtensionAPI, ExtensionDefinition } from "./extensions/index.ts";
+export { ExtensionSettingsInvalidError } from "./extensions/index.ts";
+export type { ExtensionSettingsStore, ExtensionSettingsView, ExtensionStatus, SettingsFormat, SettingsIssue, SettingsSchema } from "./extensions/index.ts";
 export type { McpServerConfig } from "operon-agents-core";
 //# sourceMappingURL=index.d.ts.map

package/dist/index.js

@@ -19,4 +19,6 @@ export { Agent, defineAgent, defineTool, handoff } from "operon-agents-core";
 export { GuardrailTripwireError, SessionBusyError, SessionClosedError, SessionInterruptedError, SessionNotInterruptedError, SessionRepositoryConflictError, SessionRepositoryNotFoundError, SteerTargetNotFoundError, } from "operon-agents-core";
 // Models, messages and where tools run.
 export { createModelManager, defineModel, LocalEnvironment } from "operon-agents-core";
+// Extension settings — what a host renders and edits through `harness.extensions`.
+export { ExtensionSettingsInvalidError } from "./extensions/index.js";
 //# sourceMappingURL=index.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "operon-agents",
-  "version": "0.1.0-alpha.31",
+  "version": "0.1.0-alpha.32",
   "description": "Public SDK entrypoint for building agents.",
   "type": "module",
   "engines": {
@@ -74,7 +74,7 @@
     "zod": "^4.4.3",
     "smol-toml": "^1.6.1",
     "@earendil-works/pi-ai": "1.5.0",
-    "operon-agents-core": "0.1.0-alpha.31"
+    "operon-agents-core": "0.1.0-alpha.32"
   },
   "devDependencies": {
     "@earendil-works/pi-ai": "1.5.0"