@oh-my-pi/pi-coding-agent 17.2.10 → 17.2.12

package/dist/types/advisor/runtime.d.ts

@@ -1,6 +1,6 @@
 import type { AgentMessage } from "@oh-my-pi/pi-agent-core";
 import type { AssistantMessage } from "@oh-my-pi/pi-ai";
-import { type SecretObfuscator } from "../secrets/obfuscator.js";
+import type { SecretObfuscator } from "../secrets/obfuscator.js";
 /**
  * Minimal slice of `Agent` the runtime drives — satisfied by pi-agent-core
  * `Agent`. `state.error` mirrors `Agent.state.error`: provider/stream failures

package/dist/types/capability/mcp.d.ts

@@ -24,12 +24,23 @@ export interface MCPServer {
     args?: string[];
     /** Environment variables */
     env?: Record<string, string>;
+    /**
+     * `literal`: env values are opaque plugin package data (Agent Plugins
+     * §§4.1/9.2) — exempt from env-name lookup and `!command` resolution.
+     */
+    envPolicy?: "literal";
     /** Working directory for stdio transport */
     cwd?: string;
     /** URL (for HTTP/SSE transport) */
     url?: string;
     /** HTTP headers (for HTTP transport) */
     headers?: Record<string, string>;
+    /**
+     * `origin-locked`: configured headers are literal package data pinned to the
+     * configured URL's origin (Agent Plugins §7.2.1) — never expanded, never
+     * forwarded cross-origin, and client-generated headers win case-insensitively.
+     */
+    headerPolicy?: "origin-locked";
     /** Authentication configuration */
     auth?: {
         type: "oauth" | "apikey";

package/dist/types/capability/skill.d.ts

@@ -35,6 +35,12 @@ export interface Skill {
     content: string;
     /** Parsed frontmatter */
     frontmatter?: SkillFrontmatter;
+    /**
+     * Filesystem-resolved plugin root this skill was packaged in (Agent Plugins
+     * §4.1). When set, every `skill://` resource access must realpath-resolve
+     * within this directory; symlinks may target other files inside it.
+     */
+    containRoot?: string;
     /** Source level */
     level: "user" | "project";
     /** Source metadata */

package/dist/types/cli/command-help.d.ts

@@ -67,6 +67,9 @@ export declare const sayHelp: {
 export declare const searchHelp: {
     description: string;
 };
+export declare const shareHelp: {
+    description: string;
+};
 export declare const setupHelp: {
     description: string;
 };

package/dist/types/commands/share.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Share a saved session as an encrypted link without launching the agent.
+ *
+ * `omp share <session>` accepts a session id (prefix) or a path to a session
+ * `.jsonl` and uploads the sealed snapshot exactly like the `/share` slash
+ * command, honoring `share.serverUrl`, `share.store`, and
+ * `share.redactSecrets`.
+ */
+import { Command } from "@oh-my-pi/pi-utils/cli";
+export default class Share extends Command {
+    static description: string;
+    static args: {
+        session: import("@oh-my-pi/pi-utils/cli").ArgDescriptor & {
+            description: string;
+            required: true;
+        };
+    };
+    static flags: {
+        gist: import("@oh-my-pi/pi-utils/cli").FlagDescriptor<"boolean"> & {
+            description: string;
+            default: boolean;
+        };
+    };
+    run(): Promise<void>;
+}

package/dist/types/commit/agentic/index.d.ts

@@ -1,2 +1,4 @@
 import type { CommitCommandArgs } from "../../commit/types.js";
-export declare function runAgenticCommit(args: CommitCommandArgs): Promise<void>;
+export declare function runAgenticCommit(args: CommitCommandArgs): Promise<{
+    usedFallback: boolean;
+}>;

package/dist/types/commit/execute.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Shared commit-execution helpers for the agentic and legacy `omp commit`
+ * pipelines: readable failure reporting for refusing git hooks and a push
+ * wrapper that keeps a requested `--push` honest.
+ */
+import * as git from "../utils/git.js";
+/**
+ * A commit or push failure that has already been reported to the user with a
+ * readable message. It is thrown so the CLI exits non-zero without the runtime
+ * dumping a stack trace — in a bundled build that trace is several kilobytes of
+ * minified source, which buries the one line the user needs (issue #7834).
+ *
+ * `runCommitCommand`'s caller (`commands/commit.ts`) maps this to exit code 1.
+ */
+export declare class CommitAbortedError extends Error {
+    constructor();
+}
+/**
+ * Print a git-command failure — most often a `pre-commit`/`commit-msg` hook
+ * that exited non-zero — as an indented message under `context`, then abort.
+ *
+ * @param context Label for the failed step, e.g. `"Commit 1 of 2 failed"`.
+ * @param error The failure to surface; its captured stderr/stdout is shown.
+ * @param note Optional trailing status line (split-plan progress, recovery).
+ */
+export declare function abortOnGitFailure(context: string, error: git.GitCommandError, note?: string): never;
+/**
+ * Push the current branch, reporting a refused push (missing upstream, rejected
+ * ref) through {@link abortOnGitFailure} instead of letting the raw
+ * `GitCommandError` escape. Prints the success line on completion.
+ */
+export declare function pushOrAbort(cwd: string): Promise<void>;

package/dist/types/commit/index.d.ts

@@ -1,4 +1,5 @@
 /**
  * Entry points for the omp commit command.
  */
-export { runCommitCommand } from "./pipeline.js";
+export * from "./execute.js";
+export * from "./pipeline.js";

package/dist/types/commit/pipeline.d.ts

@@ -1,5 +1,11 @@
 import type { CommitCommandArgs } from "./types.js";
 /**
  * Execute the omp commit pipeline for staged changes.
+ *
+ * Returns whether the commit was generated by the mechanical fallback rather
+ * than by the commit agent, so callers can signal a degraded outcome (issue
+ * #7835). The legacy pipeline has no fallback: model failures throw.
  */
-export declare function runCommitCommand(args: CommitCommandArgs): Promise<void>;
+export declare function runCommitCommand(args: CommitCommandArgs): Promise<{
+    usedFallback: boolean;
+}>;

package/dist/types/config/custom-models.d.ts

@@ -0,0 +1,31 @@
+import type { Api, Model, ModelSpec, RemoteCompactionConfig } from "@oh-my-pi/pi-ai/types";
+import { type HeaderSource } from "./model-config-values.js";
+import { type ModelPatch } from "./model-patch.js";
+import type { ModelOverride, ProviderAuthMode } from "./models-config-schema.js";
+export interface CustomModelDefinitionLike extends ModelPatch {
+    id: string;
+    api?: Api;
+    baseUrl?: string;
+    cost?: Model<Api>["cost"];
+}
+export interface CustomModelBuildOptions {
+    useDefaults: boolean;
+}
+export interface CustomModelOverlay extends ModelPatch {
+    id: string;
+    provider: string;
+    api: Api;
+    baseUrl: string;
+    cost?: Model<Api>["cost"];
+    isOAuth?: boolean;
+}
+export declare function mergeAuthHeaderSources(sources: readonly HeaderSource[], authHeader: boolean | undefined, apiKeyConfig: string | undefined): Record<string, string> | undefined;
+export declare function buildCustomModelOverlay(providerName: string, providerBaseUrl: string, providerApi: Api | undefined, providerHeaders: Record<string, string> | undefined, providerApiKey: string | undefined, authHeader: boolean | undefined, providerCompat: ModelSpec<Api>["compat"] | undefined, providerAuth: ProviderAuthMode | undefined, providerRemoteCompaction: RemoteCompactionConfig<Api> | undefined, modelDef: CustomModelDefinitionLike): CustomModelOverlay | undefined;
+export declare function finalizeCustomModel(model: CustomModelOverlay, options: CustomModelBuildOptions): Model<Api>;
+export declare function normalizeSuppressedSelector(selector: string, hasLiveModel?: (provider: string, id: string) => boolean): string;
+/**
+ * Look up a model's override, falling back to entries keyed by retired
+ * effort-tier variant ids (models.yml authored before collapsing). A raw key
+ * only re-binds when no live model holds that id.
+ */
+export declare function resolveModelOverrideWithAliases(overrides: Map<string, ModelOverride>, model: Model<Api>, hasLiveModel: (provider: string, id: string) => boolean): ModelOverride | undefined;

package/dist/types/config/model-config-values.d.ts

@@ -0,0 +1,19 @@
+export declare function isCommandConfigValue(valueConfig: string | undefined): valueConfig is string;
+export interface CommandApiKeyResolution {
+    configured: boolean;
+    value?: string;
+}
+/**
+ * Resolve a models.yml/models.yaml secret/config value to an actual value.
+ * `!cmd` runs a shell command and returns trimmed stdout, otherwise env vars are
+ * checked first and the input falls back to a literal value.
+ */
+export declare function resolveConfigValue(valueConfig: string): string | undefined;
+export type HeaderSource = Record<string, string> | undefined;
+interface HeaderResolutionOptions {
+    authHeader?: boolean;
+    apiKeyConfig?: string;
+}
+export declare function createLiveConfigHeaders(sources: readonly HeaderSource[], options?: HeaderResolutionOptions): Record<string, string> | undefined;
+export declare function resolveConfigHeaders(headers: Record<string, string> | undefined): Record<string, string> | undefined;
+export {};

package/dist/types/config/model-patch.d.ts

@@ -0,0 +1,93 @@
+import type { Api, Model, ModelSpec, RemoteCompactionConfig, ThinkingConfig } from "@oh-my-pi/pi-ai/types";
+import type { ModelOverride } from "./models-config-schema.js";
+/** Provider override config (baseUrl, headers, apiKey, compat, transport) without custom models */
+export interface ProviderOverride {
+    baseUrl?: string;
+    headers?: Record<string, string>;
+    apiKey?: string;
+    authHeader?: boolean;
+    compat?: ModelSpec<Api>["compat"];
+    remoteCompaction?: RemoteCompactionConfig<Api>;
+    transport?: Model<Api>["transport"];
+}
+/**
+ * Merge a freshly discovered model with the matching bundled/configured entry
+ * (or a runtime provider override when no bundled entry exists).
+ *
+ * `baseUrl` resolution priority:
+ *   1. User-set `providerOverride.baseUrl` (explicit override in models.json)
+ *   2. Discovered baseUrl (xiaomi `tp-` token-plan keys resolve to
+ *      `token-plan-sgp.xiaomimimo.com` at discovery time)
+ *   3. Existing bundled baseUrl (the host baked into `models.json`)
+ *
+ * `transport` resolution priority:
+ *   1. `providerOverride.transport` (e.g. `pi-native` for auth-gateway users)
+ *   2. `existing.transport` (carried over from boot-time override application)
+ *   3. `model.transport` (rarely set — discovery defaults omit it)
+ *
+ * Without (1), the user's override would lose to discovery; without (2)
+ * preferred over (3), the bundled `api.xiaomimimo.com` would shadow the
+ * tp- token-plan host and produce 401s on the first stream call.
+ * Without explicit transport propagation, an openrouter (or any) entry
+ * marked `transport: pi-native` in models.yml silently reverts to the
+ * default openai-completions transport after the background catalog
+ * refresh — so the first `/model` switch after boot hits the raw OpenAI
+ * chat-completions URL instead of the gateway's `/v1/pi/stream` (#2555).
+ * See `xiaomi-tp-discovery-merge.test.ts` and the `refresh()` baseUrl-override
+ * regression in `model-registry.test.ts`.
+ */
+export declare function mergeDiscoveredModel<TApi extends Api>(model: Model<TApi>, existing: Model<Api> | undefined, providerOverride?: Pick<ProviderOverride, "baseUrl" | "compat" | "headers" | "remoteCompaction" | "transport">): Model<TApi>;
+export declare const AUTHORITATIVE_RUNTIME_CATALOG_PROVIDERS: Set<string>;
+export declare function providersWithAuthoritativeProjectCatalog(models: readonly Model<Api>[]): Set<string>;
+export declare function dropProviderModels(models: readonly Model<Api>[], providers: ReadonlySet<string>): Model<Api>[];
+/**
+ * Merge `incoming` entries into a copy of `base`, keyed by `provider`+`id`.
+ * Matches are replaced with `combine(existing, entry)`; new entries are
+ * appended as `combine(undefined, entry)`.
+ */
+export declare function mergeByModelKey<T extends {
+    provider: string;
+    id: string;
+}>(base: readonly Model<Api>[], incoming: readonly T[], combine: (existing: Model<Api> | undefined, entry: T) => Model<Api>): Model<Api>[];
+export declare function mergeCompat<TBase extends object, TOverride extends object>(baseCompat: TBase | null | undefined, overrideCompat: TOverride | null | undefined): (TBase & TOverride) | TBase | TOverride | undefined;
+export declare function mergeRemoteCompactionConfig(baseConfig: RemoteCompactionConfig<Api> | undefined, overrideConfig: RemoteCompactionConfig<Api> | undefined): RemoteCompactionConfig<Api> | undefined;
+export declare function mergeProviderRemoteCompactionConfig(modelConfig: RemoteCompactionConfig<Api> | undefined, providerConfig: RemoteCompactionConfig<Api> | undefined): RemoteCompactionConfig<Api> | undefined;
+/**
+ * Project a built model back to spec shape for the model-manager/cache
+ * boundary: sparse compat comes from `compatConfig`, never from the resolved
+ * record.
+ */
+export declare function toModelSpec<TApi extends Api>(model: Model<TApi>): ModelSpec<TApi>;
+/**
+ * The patchable subset of `Model` fields shared by `modelOverrides` entries,
+ * custom model definitions, and parsed custom-model overlays. `undefined`
+ * always means "leave the base value alone".
+ */
+export interface ModelPatch {
+    name?: string;
+    reasoning?: boolean;
+    thinking?: ThinkingConfig;
+    input?: ("text" | "image")[];
+    supportsTools?: boolean;
+    cost?: Partial<Model<Api>["cost"]>;
+    contextWindow?: number;
+    maxTokens?: number;
+    omitMaxOutputTokens?: boolean;
+    headers?: Record<string, string>;
+    compat?: ModelSpec<Api>["compat"];
+    contextPromotionTarget?: string;
+    compactionModel?: string;
+    remoteCompaction?: RemoteCompactionConfig<Api>;
+    premiumMultiplier?: number;
+}
+/**
+ * How a patch treats the base model's transport metadata (headers/compat):
+ * - `merge`: fold the patch into the base's (modelOverrides semantics).
+ * - `replace`: the patch owns transport wholesale — same-id custom definitions
+ *   already folded provider-level headers/compat in during parsing, so bundled
+ *   transport metadata must not be re-merged (see `#mergeCustomModels`).
+ */
+type ModelTransportPolicy = "merge" | "replace";
+export declare function applyModelPatch(base: Model<Api>, patch: ModelPatch, transport: ModelTransportPolicy): Model<Api>;
+export declare function applyModelOverride(model: Model<Api>, override: ModelOverride): Model<Api>;
+export {};

package/dist/types/config/model-provider-discovery.d.ts

@@ -0,0 +1,51 @@
+import type { Api, Model } from "@oh-my-pi/pi-ai/types";
+import { type OpenAICodexAccount } from "@oh-my-pi/pi-catalog/provider-models";
+import type { AuthStorage, OAuthCredential } from "../session/auth-storage.js";
+export declare const STARTUP_MODEL_CACHE_PROVIDER_IDS: readonly string[];
+/**
+ * Hard bound for extension-provided fetchDynamicModels to prevent indefinite hangs
+ * during runtime provider discovery. Uses a cancellable manual timer (not AbortSignal.timeout)
+ * so a successful fast path does not leave an armed timeout signal for concurrent GC.
+ */
+export declare const RUNTIME_DYNAMIC_MODEL_FETCH_TIMEOUT_MS = 15000;
+export declare const BUILT_IN_DISCOVERY_CACHE_TTL_MS: number;
+export declare const BUILT_IN_DISCOVERY_NON_AUTHORITATIVE_RETRY_MS: number;
+export declare const kNoAuth = "N/A";
+export declare function isAuthenticated(apiKey: string | undefined | null): apiKey is string;
+export declare function isDiscoveryBearerApiKey(apiKey: string | undefined | null): apiKey is string;
+/**
+ * Wraps an extension-provided fetchDynamicModels call with a hard timeout.
+ * Uses a cancellable manual timer (not AbortSignal.timeout) so that a fast
+ * successful path does not leave an armed timeout signal for concurrent GC.
+ * The inner fetcher does not receive a signal (extension contract has none).
+ */
+export declare function withRuntimeDynamicModelsTimeout<T>(timeoutMs: number, run: () => Promise<T>): Promise<T>;
+export interface BuiltInDiscoveryResult {
+    models: Model<Api>[];
+    authoritativeProviders: Set<string>;
+}
+export type ProviderDiscoveryStatus = "idle" | "ok" | "empty" | "cached" | "unavailable" | "unauthenticated";
+export interface ProviderDiscoveryState {
+    provider: string;
+    status: ProviderDiscoveryStatus;
+    optional: boolean;
+    stale: boolean;
+    fetchedAt?: number;
+    models: string[];
+    error?: string;
+}
+export declare function extractGoogleOAuthToken(value: string | undefined): string | undefined;
+export declare function getOAuthCredentialsForProvider(authStorage: AuthStorage, provider: string): OAuthCredential[];
+/**
+ * Resolve every configured Codex OAuth account for catalog discovery, refreshing
+ * each credential exactly once. Codex `/models` is account-scoped, so discovery
+ * must fetch per account and union the results; resolving a single access token
+ * (as before) hid models available only through a sibling account (#6265).
+ *
+ * Returns `null` when any stored account fails to resolve (e.g. a transient
+ * refresh failure): the Codex manager is authoritative, so unioning only the
+ * accounts that resolved would cache a partial catalog and hide the failed
+ * account's models for the cache TTL. Aborting keeps the previous/bundled
+ * catalog instead.
+ */
+export declare function resolveCodexDiscoveryAccounts(authStorage: AuthStorage, resolvedAccessToken: string): Promise<OpenAICodexAccount[] | null>;

package/dist/types/config/model-registry.d.ts

@@ -1,60 +1,14 @@
+import type { ApiKeyResolver, FetchImpl } from "@oh-my-pi/pi-ai";
+import type { OAuthCredentials, OAuthLoginCallbacks } from "@oh-my-pi/pi-ai/oauth/types";
 import type { Api, Context, Model, ModelSpec, RemoteCompactionConfig, SimpleStreamOptions, ThinkingConfig } from "@oh-my-pi/pi-ai/types";
 import type { AssistantMessageEventStream } from "@oh-my-pi/pi-ai/utils/event-stream";
 import { type ModelRefreshStrategy } from "@oh-my-pi/pi-catalog/model-manager";
-import type { ApiKeyResolver, FetchImpl } from "@oh-my-pi/pi-ai";
-import type { OAuthCredentials, OAuthLoginCallbacks } from "@oh-my-pi/pi-ai/oauth/types";
 import type { AuthStorage } from "../session/auth-storage.js";
 import { type ApiKeyResolverModel, type ApiKeyResolverOptions } from "./api-key-resolver.js";
 import type { ConfigError } from "./config-file.js";
-export declare const kNoAuth = "N/A";
-export declare function isAuthenticated(apiKey: string | undefined | null): apiKey is string;
-/** Provider override config (baseUrl, headers, apiKey, compat, transport) without custom models */
-interface ProviderOverride {
-    baseUrl?: string;
-    headers?: Record<string, string>;
-    apiKey?: string;
-    authHeader?: boolean;
-    compat?: ModelSpec<Api>["compat"];
-    remoteCompaction?: RemoteCompactionConfig<Api>;
-    transport?: Model<Api>["transport"];
-}
-/**
- * Merge a freshly discovered model with the matching bundled/configured entry
- * (or a runtime provider override when no bundled entry exists).
- *
- * `baseUrl` resolution priority:
- *   1. User-set `providerOverride.baseUrl` (explicit override in models.json)
- *   2. Discovered baseUrl (xiaomi `tp-` token-plan keys resolve to
- *      `token-plan-sgp.xiaomimimo.com` at discovery time)
- *   3. Existing bundled baseUrl (the host baked into `models.json`)
- *
- * `transport` resolution priority:
- *   1. `providerOverride.transport` (e.g. `pi-native` for auth-gateway users)
- *   2. `existing.transport` (carried over from boot-time override application)
- *   3. `model.transport` (rarely set — discovery defaults omit it)
- *
- * Without (1), the user's override would lose to discovery; without (2)
- * preferred over (3), the bundled `api.xiaomimimo.com` would shadow the
- * tp- token-plan host and produce 401s on the first stream call.
- * Without explicit transport propagation, an openrouter (or any) entry
- * marked `transport: pi-native` in models.yml silently reverts to the
- * default openai-completions transport after the background catalog
- * refresh — so the first `/model` switch after boot hits the raw OpenAI
- * chat-completions URL instead of the gateway's `/v1/pi/stream` (#2555).
- * See `xiaomi-tp-discovery-merge.test.ts` and the `refresh()` baseUrl-override
- * regression in `model-registry.test.ts`.
- */
-export declare function mergeDiscoveredModel<TApi extends Api>(model: Model<TApi>, existing: Model<Api> | undefined, providerOverride?: Pick<ProviderOverride, "baseUrl" | "compat" | "headers" | "remoteCompaction" | "transport">): Model<TApi>;
-export type ProviderDiscoveryStatus = "idle" | "ok" | "empty" | "cached" | "unavailable" | "unauthenticated";
-export interface ProviderDiscoveryState {
-    provider: string;
-    status: ProviderDiscoveryStatus;
-    optional: boolean;
-    stale: boolean;
-    fetchedAt?: number;
-    models: string[];
-    error?: string;
-}
+import { type ProviderDiscoveryState } from "./model-provider-discovery.js";
+export { mergeDiscoveredModel } from "./model-patch.js";
+export { isAuthenticated, kNoAuth, type ProviderDiscoveryState, type ProviderDiscoveryStatus, } from "./model-provider-discovery.js";
 /** Authentication material returned to legacy extensions for one model request. */
 export type ResolvedRequestAuth = {
     ok: true;
@@ -227,6 +181,10 @@ export declare class ModelRegistry {
      * Remove custom API/OAuth registrations for a specific extension source.
      */
     clearSourceRegistrations(sourceId: string): void;
+    /**
+     * Remove one extension-registered provider and restore its static models.
+     */
+    unregisterProvider(providerName: string): void;
     /**
      * Remove registrations for extension sources that are no longer active.
      */
@@ -311,4 +269,3 @@ export interface ProviderConfigInput {
         premiumMultiplier?: number;
     }>;
 }
-export {};

package/dist/types/config/settings-schema.d.ts

@@ -5981,17 +5981,7 @@ export declare const SETTINGS_SCHEMA: {
             readonly tab: "providers";
             readonly group: "Services";
             readonly label: "Exa";
-            readonly description: "Master toggle for all Exa search tools";
-        };
-    };
-    readonly "exa.enableSearch": {
-        readonly type: "boolean";
-        readonly default: true;
-        readonly ui: {
-            readonly tab: "providers";
-            readonly group: "Services";
-            readonly label: "Exa Search";
-            readonly description: "Enable Exa basic search, deep search, code search, and crawl tools";
+            readonly description: "Enable the Exa web search provider";
         };
     };
     readonly "exa.searchDelayMs": {
@@ -6004,26 +5994,6 @@ export declare const SETTINGS_SCHEMA: {
             readonly description: "Minimum delay between Exa web search requests in milliseconds; set 0 to disable pacing";
         };
     };
-    readonly "exa.enableResearcher": {
-        readonly type: "boolean";
-        readonly default: false;
-        readonly ui: {
-            readonly tab: "providers";
-            readonly group: "Services";
-            readonly label: "Exa Researcher";
-            readonly description: "Enable the Exa researcher tool for AI-powered deep research";
-        };
-    };
-    readonly "exa.enableWebsets": {
-        readonly type: "boolean";
-        readonly default: false;
-        readonly ui: {
-            readonly tab: "providers";
-            readonly group: "Services";
-            readonly label: "Exa Websets";
-            readonly description: "Enable Exa webset management and enrichment tools";
-        };
-    };
     readonly "searxng.endpoint": {
         readonly type: "string";
         readonly default: undefined;
@@ -6329,10 +6299,7 @@ export interface TtsrSettings {
 }
 export interface ExaSettings {
     enabled: boolean;
-    enableSearch: boolean;
     searchDelayMs: number;
-    enableResearcher: boolean;
-    enableWebsets: boolean;
 }
 export interface StatusLineSettings {
     preset: StatusLinePreset;

package/dist/types/config/settings.d.ts

@@ -55,10 +55,12 @@ export declare class Settings {
      */
     static loadIsolated(options?: SettingsOptions): Promise<Settings>;
     /**
-     * Create an isolated instance for testing.
-     * Does not affect the global singleton.
+     * Create an in-memory settings instance without affecting the global singleton.
+     * A supplied storage handle remains shared for runtime data while setting overrides stay non-persistent.
      */
-    static isolated(overrides?: Partial<Record<SettingPath, unknown>>): Settings;
+    static isolated(overrides?: Partial<Record<SettingPath, unknown>>, options?: {
+        storage?: AgentStorage | null;
+    }): Settings;
     /**
      * Get the global singleton.
      * Throws if not initialized.

package/dist/types/debug/raw-sse-buffer.d.ts

@@ -40,5 +40,14 @@ export declare class RawSseDebugBuffer {
     recordEvent(event: RawSseEvent, model?: Model): void;
     snapshot(): RawSseDebugSnapshot;
     toRawText(): string;
+    /**
+     * Drop every retained record and reset accounting. Called from
+     * {@link AgentSession} teardown so a disposed (e.g. parked subagent) session
+     * stops pinning captured wire frames — each trimmed record holds a
+     * `slice()` of its parent SSE frame, which under JSC keeps the whole
+     * multi-MB frame alive. Notifies subscribers so a live debug viewer redraws
+     * empty.
+     */
+    clear(): void;
 }
 export declare function resolveRawSseDebugBuffer(owner?: object): RawSseDebugBuffer;

package/dist/types/discovery/agent-plugin-format.d.ts

@@ -0,0 +1,136 @@
+/** Canonical `plugin.json` `$schema` identifier for Agent Plugins 1.0.0 (spec §5.2). */
+export declare const AGENT_PLUGIN_MANIFEST_SCHEMA = "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json";
+/** Canonical `mcp.json` `$schema` identifier for Agent Plugins 1.0.0 (spec §7.2.1). */
+export declare const AGENT_PLUGIN_MCP_SCHEMA = "https://agent-plugins.org/schemas/1.0.0/mcp.schema.json";
+/** Validated portable manifest fields from a plugin's root `plugin.json` (spec §5). */
+export interface AgentPluginManifest {
+    name: string;
+    version?: string;
+    description?: string;
+    author?: {
+        name?: string;
+        email?: string;
+        url?: string;
+    };
+    homepage?: string;
+    repository?: string;
+    license?: string;
+    keywords?: string[];
+    /**
+     * Client-owned data keyed by reverse-domain namespace. Member values are
+     * opaque: this client implements no namespace, and §8.1/§11.1 require
+     * ignoring unimplemented namespaces without validating their values.
+     */
+    extensions?: Record<string, unknown>;
+}
+/**
+ * Outcome of parsing a candidate `plugin.json`:
+ * - `none` — the document does not target Agent Plugins (no recognized `$schema`);
+ *   legacy plugin conventions may still apply to the directory.
+ * - `valid` — a conformant manifest; `warnings` carries the non-fatal violations
+ *   the spec requires reporting (unknown top-level fields, non-object `extensions`).
+ * - `invalid` — the document targets Agent Plugins but violates the closed schema
+ *   fatally; the plugin must be rejected and none of its components loaded (spec §5.2).
+ */
+type AgentPluginManifestResult = {
+    status: "none";
+} | {
+    status: "valid";
+    manifest: AgentPluginManifest;
+    warnings: string[];
+} | {
+    status: "invalid";
+    reason: string;
+};
+/**
+ * Validate `SKILL.md` frontmatter against the Agent Skills specification
+ * (https://agentskills.io/specification), the source of truth for skill
+ * validity under Agent Plugins §7.1, mirroring the official skills-ref
+ * reference validator: the frontmatter schema is CLOSED to its six fields and
+ * any unexpected key rejects the skill. Returns the first violation, or `null`
+ * when the skill conforms. Frontmatter keys must be raw (unnormalized).
+ */
+export declare function validateAgentSkillFrontmatter(frontmatter: Record<string, unknown>, dirName: string): string | null;
+/**
+ * Parse and validate a root `plugin.json` document against the closed
+ * Agent Plugins 1.0.0 manifest schema (spec §5.2–§5.5, §8.1).
+ */
+export declare function parseAgentPluginManifest(raw: string): AgentPluginManifestResult;
+/** A validated `mcp.json` server entry, resolved to launch-ready values. */
+interface AgentPluginMcpServer {
+    name: string;
+    transport: "stdio" | "http" | "sse";
+    /** Absolute path for `./`-relative commands; bare executable token otherwise. */
+    command?: string;
+    args?: string[];
+    /** Expanded configured env plus the client-supplied `PLUGIN_ROOT`/`PLUGIN_DATA`. */
+    env?: Record<string, string>;
+    /** Absolute working directory; defaults to the plugin root for stdio servers. */
+    cwd?: string;
+    url?: string;
+    headers?: Record<string, string>;
+}
+/**
+ * Outcome of parsing a plugin's `mcp.json`:
+ * - `disabled` — the top-level document is invalid, so MCP is disabled for the
+ *   plugin while other component types keep loading (spec §7.2.2 rule 2).
+ * - `ok` — the document is valid; individually invalid server entries are
+ *   skipped with a warning (spec §7.2.2 rule 3).
+ */
+type AgentPluginMcpResult = {
+    status: "disabled";
+    reason: string;
+} | {
+    status: "ok";
+    servers: AgentPluginMcpServer[];
+    warnings: string[];
+};
+interface AgentPluginMcpOptions {
+    /** Filesystem-resolved plugin root. */
+    pluginRoot: string;
+    /** Client-managed persistent data directory for this plugin (spec §9.1). */
+    pluginData: string;
+}
+/**
+ * Parse and validate a plugin's `mcp.json` against the closed Agent Plugins
+ * 1.0.0 MCP configuration (spec §7.2), resolving stdio commands and working
+ * directories against the plugin root and expanding plugin variables.
+ */
+export declare function parseAgentPluginMcp(raw: string, options: AgentPluginMcpOptions): Promise<AgentPluginMcpResult>;
+/**
+ * Classification of a plugin root directory against the Agent Plugins standard:
+ * - `none` — no Agent Plugins manifest; legacy plugin conventions govern.
+ * - `standard` — a valid Agent Plugin; the standard governs its portable
+ *   components (skills and MCP servers). `realRoot` is the filesystem-resolved
+ *   plugin root every package path is contained within.
+ * - `invalid` — the root claims Agent Plugins conformance but its manifest is
+ *   fatally invalid; no component may be discovered or executed (spec §11.3).
+ */
+type AgentPluginRootStatus = {
+    kind: "none";
+} | {
+    kind: "standard";
+    manifest: AgentPluginManifest;
+    warnings: string[];
+    realRoot: string;
+} | {
+    kind: "invalid";
+    reason: string;
+};
+/** Drop cached classifications (tests, or after plugin installs outside the shared registry flow). */
+export declare function clearAgentPluginRootCache(): void;
+/**
+ * Determine whether a plugin root is governed by the Agent Plugins standard.
+ * Results are cached per root path; the cache clears with the shared plugin
+ * roots cache and via {@link clearAgentPluginRootCache}.
+ */
+export declare function classifyAgentPluginRoot(rootPath: string): Promise<AgentPluginRootStatus>;
+/**
+ * Whether a legacy plugin provider (claude-plugins, omp-plugins) may process a
+ * root for the given surface. Roots governed by the Agent Plugins standard keep
+ * their portable components (`skills`, `mcp`) exclusive to the standard loader,
+ * while client-specific surfaces (commands, hooks, tools, …) still load from
+ * hybrid packages. Fatally invalid Agent Plugins packages are rejected entirely.
+ */
+export declare function legacyProviderAllowed(rootPath: string, surface: "skills" | "mcp" | "other"): Promise<boolean>;
+export {};

package/dist/types/discovery/agent-plugins.d.ts

@@ -0,0 +1 @@
+export {};