pi-session-mcp 0.6.3 → 0.7.0

package/dist/pi-extensions.js

@@ -0,0 +1,67 @@
+import { readFile, realpath, stat } from "node:fs/promises";
+import { isAbsolute, join, relative, sep } from "node:path";
+import { getAgentDir } from "@earendil-works/pi-coding-agent";
+import { PiExtensionError } from "./extension-spec.js";
+// The SDK has no side-effect-free lookup: `resolve()` runs `npm install`, and `getInstalledPath`
+// falls back to a synchronous `npm root -g` on a miss and accepts global installs made outside Pi.
+// So this only computes where Pi puts user-scope npm packages; a missing directory means not installed.
+function installedPathFromPi(source, agentDir) {
+    return join(agentDir, "npm", "node_modules", source.slice("npm:".length));
+}
+function inside(root, candidate) {
+    const path = relative(root, candidate);
+    return path !== "" && path !== ".." && !path.startsWith(`..${sep}`) && !isAbsolute(path);
+}
+function isMissing(error) {
+    return typeof error === "object" && error !== null && error.code === "ENOENT";
+}
+/**
+ * Resolves a pinned extension to the real directory of Pi's installed package.
+ * It never installs, never imports extension code and never reports a path.
+ */
+export async function resolvePiExtension(extension, dependencies = {}) {
+    const agentDir = dependencies.agentDir ?? getAgentDir();
+    const read = dependencies.readFile ?? ((path) => readFile(path, "utf8"));
+    const real = dependencies.realpath ?? realpath;
+    const statFile = dependencies.stat ?? stat;
+    let installed;
+    try {
+        installed = (dependencies.installedPath ?? installedPathFromPi)(`npm:${extension.name}`, agentDir);
+    }
+    catch {
+        throw new PiExtensionError("extension_load_failed");
+    }
+    if (installed === undefined)
+        throw new PiExtensionError("extension_not_installed");
+    let root;
+    let manifest;
+    try {
+        root = await real(installed);
+        manifest = JSON.parse((await read(join(root, "package.json"))).replace(/^\uFEFF/, ""));
+    }
+    catch (error) {
+        throw new PiExtensionError(isMissing(error) ? "extension_not_installed" : "extension_load_failed");
+    }
+    if (typeof manifest !== "object" || manifest === null || Array.isArray(manifest))
+        throw new PiExtensionError("extension_load_failed");
+    const { version, pi } = manifest;
+    if (version !== extension.version)
+        throw new PiExtensionError("extension_version_mismatch");
+    const entries = pi?.extensions;
+    if (!Array.isArray(entries) || entries.length === 0
+        || !entries.every((entry) => typeof entry === "string" && entry.length > 0 && !isAbsolute(entry))) {
+        throw new PiExtensionError("extension_load_failed");
+    }
+    for (const entry of entries) {
+        let target;
+        try {
+            target = await real(join(root, entry));
+            if (!inside(root, target) || !(await statFile(target)).isFile())
+                throw new PiExtensionError("extension_load_failed");
+        }
+        catch {
+            throw new PiExtensionError("extension_load_failed");
+        }
+    }
+    return root;
+}

package/dist/sdk-pi-adapter.d.ts

@@ -1,7 +1,9 @@
-import { type AgentSessionEvent, type CreateAgentSessionOptions, type CreateAgentSessionResult, DefaultResourceLoader, ModelRuntime, type PromptOptions, SettingsManager } from "@earendil-works/pi-coding-agent";
-import type { PermissionProfile, ResolvedExecutionProfile, ThinkingLevel } from "./execution-profile.js";
+import { type AgentSessionEvent, type CreateAgentSessionOptions, type CreateAgentSessionResult, createAgentSessionFromServices, createAgentSessionRuntime, createAgentSessionServices, DefaultResourceLoader, ModelRuntime, type PromptOptions, SettingsManager } from "@earendil-works/pi-coding-agent";
+import { type ExtensionSpec } from "./extension-spec.js";
+import type { ResolvedExecutionProfile, ThinkingLevel } from "./execution-profile.js";
 import { type McpConnectionFactory } from "./mcp-session-tools.js";
 import { type PiSessionAdapter, type PiSessionCreationErrorCode, type PiSessionHandle, type PiTurnOutcome } from "./pi-adapter.js";
+export { PROFILE_TOOLS } from "./session-tools.js";
 type CreateSession = (options: CreateAgentSessionOptions) => Promise<CreateAgentSessionResult>;
 export declare const AUTH_OPERATION_TIMEOUT_MS = 5000;
 /** Server-side bound for SDK session construction. The SDK does not document cancellation. */
@@ -9,7 +11,7 @@ export declare const SESSION_CREATION_TIMEOUT_MS = 10000;
 export interface SdkPiAdapterDiagnostic {
     readonly level: "error";
     readonly event: "pi_session_creation_failed";
-    readonly stage: "runtime" | "provider" | "model" | "check_auth" | "get_auth" | "availability" | "resource_loader" | "mcp_tools" | "create_session" | "postcheck";
+    readonly stage: "runtime" | "provider" | "model" | "check_auth" | "get_auth" | "availability" | "resource_loader" | "mcp_tools" | "create_session" | "postcheck" | "extension_resolve" | "extension_load" | "extension_bind";
     readonly code: PiSessionCreationErrorCode;
     readonly executionProfile: string;
     readonly provider: string;
@@ -18,12 +20,23 @@ export interface SdkPiAdapterDiagnostic {
     readonly serverAlias?: string;
     readonly toolAlias?: string;
     readonly discoveredToolCount?: number;
+    /** `<name>@<version>` of the extension that failed to resolve; never a path. */
+    readonly extension?: string;
+}
+/** The Pi SDK session-lifecycle API used for profiles with extensions; injectable for tests. */
+export interface ExtensionSdk {
+    readonly createServices: typeof createAgentSessionServices;
+    readonly createSessionFromServices: typeof createAgentSessionFromServices;
+    readonly createRuntime: typeof createAgentSessionRuntime;
 }
 export interface SdkPiSessionAdapterOptions {
     readonly modelRuntimeFactory?: () => Promise<ModelRuntime>;
     readonly createSession?: CreateSession;
     readonly diagnosticSink?: (diagnostic: SdkPiAdapterDiagnostic) => void;
     readonly mcpConnectionFactory?: McpConnectionFactory;
+    /** Resolves a pinned extension to its installed package directory. */
+    readonly resolveExtension?: (extension: ExtensionSpec) => Promise<string>;
+    readonly extensionSdk?: ExtensionSdk;
 }
 type SdkAssistantMessage = Extract<Extract<AgentSessionEvent, {
     type: "message_end";
@@ -40,7 +53,6 @@ export type SdkStopReason = SdkAssistantMessage["stopReason"];
  * values outside the SDK union, a missing stop reason included, fail closed.
  */
 export declare function normalizeAssistantOutcome(message: unknown): PiTurnOutcome;
-export declare const PROFILE_TOOLS: Readonly<Record<PermissionProfile, readonly string[]>>;
 /** Derived from the root-exported `PromptOptions`; the SDK does not export the union itself. */
 export type PromptDisposition = Parameters<NonNullable<PromptOptions["preflightResult"]>>[0];
 /**
@@ -62,14 +74,20 @@ export declare class SdkPiSessionAdapter implements PiSessionAdapter {
     private readonly createSession;
     private readonly diagnosticSink;
     private readonly mcpConnectionFactory;
+    private readonly resolveExtension;
+    private readonly extensionSdk;
     constructor(options?: SdkPiSessionAdapterOptions);
     create(input: {
         cwd: string;
         executionProfile: ResolvedExecutionProfile;
         signal?: AbortSignal;
     }): Promise<PiSessionHandle>;
-    private createSessionWithDeadline;
+    private createWithExtensions;
+    /** Provider, model, authentication and availability, exactly as configured. */
+    private resolveVerifiedModel;
+    private connectMcpTools;
+    /** Post-verifies a created session and wraps it; a mismatch disposes it before reporting. */
+    private admit;
     private getRuntime;
     private failure;
 }
-export {};

package/dist/sdk-pi-adapter.js

@@ -1,10 +1,19 @@
-import { createAgentSession, DefaultResourceLoader, ModelRuntime, SessionManager, SettingsManager, } from "@earendil-works/pi-coding-agent";
+import { createAgentSession, createAgentSessionFromServices, createAgentSessionRuntime, createAgentSessionServices, DefaultResourceLoader, ModelRuntime, SessionManager, SettingsManager, } from "@earendil-works/pi-coding-agent";
+import { PiExtensionError } from "./extension-spec.js";
 import { classifyMcpStartupError, connectSessionMcpTools, } from "./mcp-session-tools.js";
 import { createStdioMcpConnection } from "./mcp-stdio-client.js";
 import { PiSessionCreationError, } from "./pi-adapter.js";
+import { resolvePiExtension } from "./pi-extensions.js";
+import { composeSessionTools, PROFILE_TOOLS } from "./session-tools.js";
+export { PROFILE_TOOLS } from "./session-tools.js";
 export const AUTH_OPERATION_TIMEOUT_MS = 5_000;
 /** Server-side bound for SDK session construction. The SDK does not document cancellation. */
 export const SESSION_CREATION_TIMEOUT_MS = 10_000;
+const DEFAULT_EXTENSION_SDK = {
+    createServices: createAgentSessionServices,
+    createSessionFromServices: createAgentSessionFromServices,
+    createRuntime: createAgentSessionRuntime,
+};
 class AuthDeadlineError extends Error {
     constructor() {
         super("authentication operation timed out");
@@ -42,6 +51,60 @@ async function withAuthDeadline(operation) {
         controller.abort();
     }
 }
+/** Races an SDK operation against the session-creation bound; a late success goes to `disposeLate`. */
+async function withCreationDeadline(start, disposeLate = () => undefined) {
+    let operation;
+    try {
+        operation = Promise.resolve(start());
+    }
+    catch {
+        throw new SessionCreationDeadlineError();
+    }
+    let timedOut = false;
+    // This continuation is installed immediately and owns late cleanup. Its rejection
+    // branch is required even when the deadline wins the race.
+    const observed = operation.then((value) => {
+        if (timedOut)
+            disposeLate(value);
+        return value;
+    }, (error) => { throw error; });
+    let timer;
+    const timeout = new Promise((_, reject) => {
+        timer = setTimeout(() => {
+            timedOut = true;
+            reject(new SessionCreationDeadlineError());
+        }, SESSION_CREATION_TIMEOUT_MS);
+    });
+    try {
+        return await Promise.race([observed, timeout]);
+    }
+    finally {
+        if (timer)
+            clearTimeout(timer);
+    }
+}
+/** Runs a session disposal bounded by the creation deadline; failures and a timeout are swallowed. */
+async function boundedDisposal(dispose) {
+    let timer;
+    const timeout = new Promise((resolve) => { timer = setTimeout(resolve, SESSION_CREATION_TIMEOUT_MS); });
+    let disposal;
+    try {
+        disposal = Promise.resolve(dispose()).then(() => undefined, () => undefined);
+    }
+    catch {
+        disposal = Promise.resolve();
+    }
+    try {
+        await Promise.race([disposal, timeout]);
+    }
+    finally {
+        if (timer)
+            clearTimeout(timer);
+    }
+}
+function registeredExtensionTools(services) {
+    return services.resourceLoader.getExtensions().extensions.map((extension) => [...extension.tools.keys()]);
+}
 /**
  * Projects the final assistant message of a prompt onto a turn outcome.
  *
@@ -75,10 +138,6 @@ export function normalizeAssistantOutcome(message) {
         }
     }
 }
-export const PROFILE_TOOLS = {
-    "read-only": ["read", "grep", "find", "ls"],
-    coding: ["read", "bash", "edit", "write", "grep", "find", "ls"],
-};
 /**
  * Whether an SDK prompt disposition admits a public turn. The SDK reports how an accepted
  * prompt was dispatched and does not call the hook on rejection: `prompt()` rejects instead,
@@ -93,8 +152,8 @@ export function admitsTurn(disposition) {
             return true;
         // Only while streaming with `streamingBehavior`; Pi Session MCP never passes it and serializes turns.
         case "queued":
-        // An extension command or input handler consumed the prompt without a model turn. The
-        // isolated resource loader (`noExtensions`) makes this unreachable; no public turn exists.
+        // An extension input handler consumed the prompt without a model turn. Commands never
+        // dispatch (`expandPromptTemplates: false`), but allowlisted extensions may handle input.
         case "handled":
             return false;
         default: {
@@ -108,13 +167,15 @@ class SdkHandle {
     session;
     appliedSelection;
     mcpTools;
+    disposeSession;
     disposed = false;
     disposal;
     subscriptions = new Set();
-    constructor(session, appliedSelection, mcpTools) {
+    constructor(session, appliedSelection, mcpTools, disposeSession = () => disposeSdkSession(session)) {
         this.session = session;
         this.appliedSelection = appliedSelection;
         this.mcpTools = mcpTools;
+        this.disposeSession = disposeSession;
     }
     get sdkSessionId() { return this.session.sessionId; }
     prompt(text, preflight, onActivity) {
@@ -159,7 +220,11 @@ class SdkHandle {
         this.subscriptions.add(cleanup);
         let promptResult;
         try {
-            promptResult = this.session.prompt(text, { preflightResult: (disposition) => signalPreflight(admitsTurn(disposition)) });
+            promptResult = this.session.prompt(text, {
+                // Client text is content, never a command: no extension command, skill or template dispatch.
+                expandPromptTemplates: false,
+                preflightResult: (disposition) => signalPreflight(admitsTurn(disposition)),
+            });
         }
         catch {
             cleanup();
@@ -178,8 +243,14 @@ class SdkHandle {
         const closed = this.mcpTools.close();
         for (const cleanup of [...this.subscriptions])
             cleanup();
-        disposeSdkSession(this.session);
-        void closed.then(finish, finish);
+        let sessionClosed;
+        try {
+            sessionClosed = Promise.resolve(this.disposeSession()).then(() => undefined, () => undefined);
+        }
+        catch {
+            sessionClosed = Promise.resolve();
+        }
+        void Promise.all([closed.then(() => undefined, () => undefined), sessionClosed]).then(finish, finish);
         return this.disposal;
     }
 }
@@ -195,12 +266,9 @@ function isTextBlock(block) {
     const candidate = block;
     return candidate.type === "text" && typeof candidate.text === "string";
 }
-export async function createPhase0ResourceLoader(cwd) {
-    const settingsManager = SettingsManager.inMemory(undefined, { projectTrusted: false });
-    const resourceLoader = new DefaultResourceLoader({
-        cwd,
-        agentDir: cwd,
-        settingsManager,
+/** Resource-loader options for every embedded session: no discovery, skills, templates or themes. */
+function phase0ResourceLoaderOptions() {
+    return {
         noExtensions: true,
         noSkills: true,
         noPromptTemplates: true,
@@ -210,7 +278,11 @@ export async function createPhase0ResourceLoader(cwd) {
         appendSystemPrompt: [],
         systemPromptOverride: () => undefined,
         appendSystemPromptOverride: () => [],
-    });
+    };
+}
+export async function createPhase0ResourceLoader(cwd) {
+    const settingsManager = SettingsManager.inMemory(undefined, { projectTrusted: false });
+    const resourceLoader = new DefaultResourceLoader({ cwd, agentDir: cwd, settingsManager, ...phase0ResourceLoaderOptions() });
     await resourceLoader.reload();
     return { resourceLoader, settingsManager };
 }
@@ -220,13 +292,20 @@ export class SdkPiSessionAdapter {
     createSession;
     diagnosticSink;
     mcpConnectionFactory;
+    resolveExtension;
+    extensionSdk;
     constructor(options = {}) {
         this.modelRuntimeFactory = options.modelRuntimeFactory ?? (() => ModelRuntime.create({ refreshOnCreate: false }));
         this.createSession = options.createSession ?? createAgentSession;
         this.diagnosticSink = options.diagnosticSink ?? (() => undefined);
         this.mcpConnectionFactory = options.mcpConnectionFactory ?? createStdioMcpConnection;
+        this.resolveExtension = options.resolveExtension ?? ((extension) => resolvePiExtension(extension));
+        this.extensionSdk = options.extensionSdk ?? DEFAULT_EXTENSION_SDK;
     }
     async create(input) {
+        const extensions = input.executionProfile.extensions ?? [];
+        if (extensions.length > 0)
+            return this.createWithExtensions(input, extensions);
         const { executionProfile } = input;
         let runtime;
         try {
@@ -235,6 +314,142 @@ export class SdkPiSessionAdapter {
         catch {
             throw this.failure(executionProfile, "runtime", "pi_session_creation_failed");
         }
+        const model = await this.resolveVerifiedModel(runtime, executionProfile);
+        let resourceLoader;
+        let settingsManager;
+        try {
+            ({ resourceLoader, settingsManager } = await createPhase0ResourceLoader(input.cwd));
+        }
+        catch {
+            throw this.failure(executionProfile, "resource_loader", "pi_session_creation_failed");
+        }
+        const mcpTools = await this.connectMcpTools(input);
+        const tools = [...PROFILE_TOOLS[executionProfile.permissionProfile], ...mcpTools.tools.map((tool) => tool.name)];
+        let session;
+        try {
+            ({ session } = await withCreationDeadline(() => this.createSession({
+                cwd: input.cwd,
+                modelRuntime: runtime,
+                model,
+                thinkingLevel: executionProfile.thinkingLevel,
+                sessionManager: SessionManager.inMemory(input.cwd),
+                settingsManager,
+                resourceLoader,
+                // With an explicit tools list, Pi also needs custom tool names here to activate them.
+                tools,
+                ...(mcpTools.tools.length === 0 ? {} : { customTools: mcpTools.tools }),
+            }), (late) => disposeSdkSession(late.session)));
+        }
+        catch {
+            await mcpTools.close();
+            throw this.failure(executionProfile, "create_session", "pi_session_creation_failed");
+        }
+        return this.admit(session, executionProfile, tools, mcpTools, () => disposeSdkSession(session), mcpTools.tools.length > 0 ? "external_mcp_activation_mismatch" : undefined);
+    }
+    async createWithExtensions(input, extensions) {
+        const { cwd, executionProfile } = input;
+        const directories = [];
+        for (const extension of extensions) {
+            try {
+                directories.push(await this.resolveExtension(extension));
+            }
+            catch (error) {
+                throw this.failure(executionProfile, "extension_resolve", error instanceof PiExtensionError ? error.code : "extension_load_failed", { extension: `${extension.name}@${extension.version}` });
+            }
+        }
+        // Extension providers register into the runtime they load with, and the last
+        // registration wins, so every extension session gets a runtime of its own.
+        let runtime;
+        try {
+            runtime = await this.modelRuntimeFactory();
+        }
+        catch {
+            throw this.failure(executionProfile, "runtime", "pi_session_creation_failed");
+        }
+        let services;
+        let extensionTools;
+        try {
+            services = await withCreationDeadline(() => this.extensionSdk.createServices({
+                cwd,
+                agentDir: cwd,
+                modelRuntime: runtime,
+                settingsManager: SettingsManager.inMemory(undefined, { projectTrusted: false }),
+                resourceLoaderOptions: { ...phase0ResourceLoaderOptions(), additionalExtensionPaths: directories },
+            }));
+            const loaded = services.resourceLoader.getExtensions();
+            if (loaded.errors.length > 0 || services.diagnostics.some((diagnostic) => diagnostic.type === "error")) {
+                throw new Error("extension load reported errors");
+            }
+            extensionTools = registeredExtensionTools(services);
+        }
+        catch {
+            throw this.failure(executionProfile, "extension_load", "extension_load_failed");
+        }
+        const model = await this.resolveVerifiedModel(services.modelRuntime, executionProfile);
+        const mcpTools = await this.connectMcpTools(input);
+        const tools = composeSessionTools(executionProfile.permissionProfile, mcpTools.tools.map((tool) => tool.name), extensionTools);
+        if (!tools) {
+            await mcpTools.close();
+            throw this.failure(executionProfile, "extension_load", "extension_tool_conflict");
+        }
+        let sessionRuntime;
+        try {
+            sessionRuntime = await withCreationDeadline(() => this.extensionSdk.createRuntime(async ({ sessionManager }) => ({
+                ...(await this.extensionSdk.createSessionFromServices({
+                    services,
+                    sessionManager,
+                    model,
+                    thinkingLevel: executionProfile.thinkingLevel,
+                    tools,
+                    ...(mcpTools.tools.length === 0 ? {} : { customTools: mcpTools.tools }),
+                })),
+                services,
+                diagnostics: services.diagnostics,
+            }), { cwd, agentDir: cwd, sessionManager: SessionManager.inMemory(cwd) }), (late) => { void late.dispose().catch(() => undefined); });
+        }
+        catch {
+            await mcpTools.close();
+            throw this.failure(executionProfile, "create_session", "pi_session_creation_failed");
+        }
+        // `AgentSessionRuntime.dispose()` emits `session_shutdown` before disposing the session.
+        const disposeRuntime = () => sessionRuntime.dispose().catch(() => undefined);
+        // Bounded and concurrent: a hanging `session_shutdown` handler must not keep MCP processes open.
+        const cleanUp = async () => {
+            await Promise.all([boundedDisposal(disposeRuntime), mcpTools.close()]);
+        };
+        let bindErrors = 0;
+        let bound = false;
+        let conflict = false;
+        try {
+            // Without a UI context the SDK binds its no-op UI; binding emits `session_start`.
+            await withCreationDeadline(() => sessionRuntime.session.bindExtensions({
+                mode: "print",
+                // `ExtensionRunner.emit` routes handler errors here instead of rejecting the bind.
+                onError: () => { if (!bound)
+                    bindErrors += 1; },
+            }));
+            bound = true;
+            if (bindErrors > 0)
+                throw new Error("extension hook reported errors while binding");
+            // A `session_start` handler may register a tool that replaces a built-in or granted tool.
+            // Tools an extension registers later, during a turn, are not re-checked: allowlisted
+            // extensions are trusted code.
+            const recheck = composeSessionTools(executionProfile.permissionProfile, mcpTools.tools.map((tool) => tool.name), registeredExtensionTools(services));
+            if (!recheck || recheck.length !== tools.length || recheck.some((name, index) => name !== tools[index]))
+                conflict = true;
+        }
+        catch {
+            await cleanUp();
+            throw this.failure(executionProfile, "extension_bind", "extension_load_failed");
+        }
+        if (conflict) {
+            await cleanUp();
+            throw this.failure(executionProfile, "extension_bind", "extension_tool_conflict");
+        }
+        return this.admit(sessionRuntime.session, executionProfile, tools, mcpTools, disposeRuntime, mcpTools.tools.length > 0 ? "external_mcp_activation_mismatch" : "execution_selection_mismatch", "subset");
+    }
+    /** Provider, model, authentication and availability, exactly as configured. */
+    async resolveVerifiedModel(runtime, executionProfile) {
         let provider;
         try {
             provider = runtime.getProvider(executionProfile.provider);
@@ -281,42 +496,21 @@ export class SdkPiSessionAdapter {
         if (!available.some((candidate) => candidate.provider === executionProfile.provider && candidate.id === executionProfile.model)) {
             throw this.failure(executionProfile, "availability", "model_unavailable");
         }
-        let resourceLoader;
-        let settingsManager;
-        try {
-            ({ resourceLoader, settingsManager } = await createPhase0ResourceLoader(input.cwd));
-        }
-        catch {
-            throw this.failure(executionProfile, "resource_loader", "pi_session_creation_failed");
-        }
-        let mcpTools;
+        return model;
+    }
+    async connectMcpTools(input) {
         try {
-            mcpTools = await connectSessionMcpTools(executionProfile.mcpServers ?? {}, executionProfile.permissionProfile, input.cwd, this.mcpConnectionFactory, input.signal === undefined ? {} : { signal: input.signal });
+            return await connectSessionMcpTools(input.executionProfile.mcpServers ?? {}, input.executionProfile.permissionProfile, input.cwd, this.mcpConnectionFactory, input.signal === undefined ? {} : { signal: input.signal });
         }
         catch (error) {
             const failure = classifyMcpStartupError(error);
-            throw this.failure(executionProfile, "mcp_tools", failure?.code ?? "external_mcp_unavailable", failure);
-        }
-        const tools = [...PROFILE_TOOLS[executionProfile.permissionProfile], ...mcpTools.tools.map((tool) => tool.name)];
-        let session;
-        try {
-            ({ session } = await this.createSessionWithDeadline({
-                cwd: input.cwd,
-                modelRuntime: runtime,
-                model,
-                thinkingLevel: executionProfile.thinkingLevel,
-                sessionManager: SessionManager.inMemory(input.cwd),
-                settingsManager,
-                resourceLoader,
-                // With an explicit tools list, Pi also needs custom tool names here to activate them.
-                tools,
-                ...(mcpTools.tools.length === 0 ? {} : { customTools: mcpTools.tools }),
-            }));
-        }
-        catch {
-            await mcpTools.close();
-            throw this.failure(executionProfile, "create_session", "pi_session_creation_failed");
+            throw this.failure(input.executionProfile, "mcp_tools", failure?.code ?? "external_mcp_unavailable", failure);
         }
+    }
+    /** Post-verifies a created session and wraps it; a mismatch disposes it before reporting. */
+    async admit(session, executionProfile, tools, mcpTools, disposeSession, toolMismatch, 
+    // `subset` lets an extension narrow its own active tools; nothing outside the allowlist may be active.
+    toolCheck = "exact") {
         try {
             if (session.model?.provider !== executionProfile.provider || session.model.id !== executionProfile.model) {
                 throw this.failure(executionProfile, "postcheck", "execution_selection_mismatch");
@@ -324,57 +518,29 @@ export class SdkPiSessionAdapter {
             if (session.thinkingLevel !== executionProfile.thinkingLevel) {
                 throw this.failure(executionProfile, "postcheck", "thinking_level_unavailable");
             }
-            if (mcpTools.tools.length > 0) {
+            if (toolMismatch !== undefined) {
                 const active = new Set(session.getActiveToolNames());
-                if (active.size !== tools.length || tools.some((name) => !active.has(name))) {
-                    throw this.failure(executionProfile, "postcheck", "external_mcp_activation_mismatch");
+                const allowed = new Set(tools);
+                const mismatch = toolCheck === "subset"
+                    ? [...active].some((name) => !allowed.has(name))
+                    : active.size !== tools.length || tools.some((name) => !active.has(name));
+                if (mismatch) {
+                    throw this.failure(executionProfile, "postcheck", toolMismatch);
                 }
             }
             return new SdkHandle(session, {
                 provider: session.model.provider,
                 model: session.model.id,
                 thinkingLevel: session.thinkingLevel,
-            }, mcpTools);
+            }, mcpTools, disposeSession);
         }
         catch (error) {
-            disposeSdkSession(session);
-            await mcpTools.close();
+            await Promise.all([boundedDisposal(disposeSession), mcpTools.close()]);
             if (error instanceof PiSessionCreationError)
                 throw error;
             throw this.failure(executionProfile, "postcheck", "pi_session_creation_failed");
         }
     }
-    async createSessionWithDeadline(options) {
-        let creation;
-        try {
-            creation = Promise.resolve(this.createSession(options));
-        }
-        catch {
-            throw new SessionCreationDeadlineError();
-        }
-        let timedOut = false;
-        // This continuation is installed immediately and owns late cleanup. Its rejection
-        // branch is required even when the deadline wins the race.
-        const observed = creation.then((result) => {
-            if (timedOut)
-                disposeSdkSession(result.session);
-            return result;
-        }, (error) => { throw error; });
-        let timer;
-        const timeout = new Promise((_, reject) => {
-            timer = setTimeout(() => {
-                timedOut = true;
-                reject(new SessionCreationDeadlineError());
-            }, SESSION_CREATION_TIMEOUT_MS);
-        });
-        try {
-            return await Promise.race([observed, timeout]);
-        }
-        finally {
-            if (timer)
-                clearTimeout(timer);
-        }
-    }
     getRuntime() {
         if (!this.runtimePromise) {
             const pending = this.modelRuntimeFactory();
@@ -400,6 +566,7 @@ export class SdkPiSessionAdapter {
                 ...(metadata?.serverAlias === undefined ? {} : { serverAlias: metadata.serverAlias }),
                 ...(metadata?.toolAlias === undefined ? {} : { toolAlias: metadata.toolAlias }),
                 ...(metadata?.discoveredToolCount === undefined ? {} : { discoveredToolCount: metadata.discoveredToolCount }),
+                ...(metadata?.extension === undefined ? {} : { extension: metadata.extension }),
             });
         }
         catch {

package/dist/server.js

@@ -41,6 +41,7 @@ const capabilitiesSchema = z.object({
         provider: z.string(),
         model: z.string(),
         thinkingLevel: thinkingLevelSchema,
+        extensions: z.array(z.string()),
     }).strict()),
 }).strict();
 function result(value, isError = false) {

package/dist/session-tools.d.ts

@@ -0,0 +1,9 @@
+import type { PermissionProfile } from "./execution-profile.js";
+export declare const PROFILE_TOOLS: Readonly<Record<PermissionProfile, readonly string[]>>;
+/**
+ * The tool allowlist of a session, or undefined when an extension tool name conflicts.
+ * Extension tools are active only in coding profiles, but a conflict fails closed in both,
+ * so an extension can never shadow a built-in or granted tool. A name outside the safe
+ * character set also fails closed.
+ */
+export declare function composeSessionTools(permissionProfile: PermissionProfile, mcpToolNames: readonly string[], extensionToolNames: readonly (readonly string[])[]): string[] | undefined;

package/dist/session-tools.js

@@ -0,0 +1,25 @@
+export const PROFILE_TOOLS = {
+    "read-only": ["read", "grep", "find", "ls"],
+    coding: ["read", "bash", "edit", "write", "grep", "find", "ls"],
+};
+/** The SDK reads `*` in an allowlist as a glob and a leading `+` or `-` as a modifier, so those names are rejected: the first character may not be `-`. */
+const EXTENSION_TOOL_NAME = /^[A-Za-z0-9_.:][A-Za-z0-9_.:-]*$/;
+/**
+ * The tool allowlist of a session, or undefined when an extension tool name conflicts.
+ * Extension tools are active only in coding profiles, but a conflict fails closed in both,
+ * so an extension can never shadow a built-in or granted tool. A name outside the safe
+ * character set also fails closed.
+ */
+export function composeSessionTools(permissionProfile, mcpToolNames, extensionToolNames) {
+    const reserved = new Set([...PROFILE_TOOLS.coding, ...PROFILE_TOOLS["read-only"], ...mcpToolNames]);
+    const extensionTools = [];
+    for (const names of extensionToolNames) {
+        for (const name of names) {
+            if (!EXTENSION_TOOL_NAME.test(name) || reserved.has(name))
+                return undefined;
+            reserved.add(name);
+            extensionTools.push(name);
+        }
+    }
+    return [...PROFILE_TOOLS[permissionProfile], ...mcpToolNames, ...(permissionProfile === "coding" ? extensionTools : [])];
+}