@fastagent-sh/fastagent 0.27.0 → 0.29.0

package/dist/harnesses/pi-durable/open.d.ts

@@ -1,5 +1,5 @@
 import type { ModelThinkingLevel, Models, Provider } from "@earendil-works/pi-ai";
-import { type Extension, type HarnessSettings, type ModelRef, type Storage, type ToolRegistration } from "@earendil-works/pi-durable";
+import { type Extension, type HarnessSettings, type Storage, type ToolRegistration } from "@earendil-works/pi-durable";
 import type { ResolvedContent } from "../../content/resolve.ts";
 import { type DeclaredSecret } from "../../declared-secrets.ts";
 import type { ChannelModule, LongConnectionChannelModule } from "../../channel.ts";
@@ -14,14 +14,12 @@ export interface AgentDefinition {
     config: AgentConfig;
     registry: Registry;
 }
-export declare function modelRefOf(spec: string, where: string): ModelRef;
 /** The agent package's `fastagent.config.ts`, checked; `{}` without one. */
 export declare function loadConfig(dir: string): Promise<AgentConfig>;
 /** The default model a process here runs with: `--model` > `FASTAGENT_MODEL` > the configuration's `model`. */
 export declare function modelSpecFor(config: AgentConfig, flag: string | undefined, env?: NodeJS.ProcessEnv): string | undefined;
 /** Read the agent package in `dir`: `fastagent.config.ts` (optional) and `.fastagent/registry.ts`, generated first. */
 export declare function loadDefinition(directory: string): Promise<AgentDefinition>;
-/** The secrets the definition declares, wherever: its code's `needs`, and `context.json`'s command variables. */
 export declare function definitionSecrets(definition: AgentDefinition): DeclaredSecret[];
 /**
  * The list a person deploying or running the agent reads instead of its code (`.fastagent/secrets.json`): each name
@@ -65,10 +63,11 @@ export declare function buildDefinitionShape(definition: AgentDefinition, env: N
 export declare function definitionProviders(agentDir: string, env?: NodeJS.ProcessEnv): Promise<Provider[]>;
 export interface AssembleAgentOptions {
     storage: Storage;
-    /** What the agent works on and knows (`context.json`'s content), resolved for this instance. */
+    /** What the agent works on (`context.json`'s content), resolved for this instance. */
     content?: readonly ResolvedContent[];
     /** The definition's code, built once with its secrets (`buildDefinition`). */
     code: BuiltDefinition;
+    mcpTools?: ToolRegistration[];
     /**
      * pi-ai's built-ins and the definition's providers over the instance's credentials, lists refreshed: the model
      * environment's (environment.ts), so the Agent runs on the lists its startup report reads.

package/dist/harnesses/pi-durable/open.js

@@ -19,12 +19,14 @@ import { createRegistry, defineExtension, } from "@earendil-works/pi-durable";
 import { NodeExecutionEnv } from "@earendil-works/pi-durable/env/node";
 import { CodingTools } from "@earendil-works/pi-durable/tools";
 import { loadEnvironment } from "../../content/file.js";
+import { mcpSecrets } from "../../mcp/config.js";
 import { describeSecrets, missingSecrets } from "../../declared-secrets.js";
 import { declaredVariables } from "../../environment/declare.js";
 import { channelModuleProblem } from "../../channels/discover.js";
 import { AGENT_CONFIG_FILE as CONFIG_FILE } from "../../paths.js";
 import { readPackageJson } from "../../runtime.js";
 import { DEV_SERVE_ENV } from "../../serving-command.js";
+import { modelRefOf } from "../../model-ref.js";
 import { MAX_SCHEDULES, scheduleConfigProblem } from "../../schedule/schedule.js";
 import { openDurableAgent } from "./agent.js";
 import { isNeeds } from "./define.js";
@@ -97,13 +99,6 @@ function checkConfig(config, file) {
     }
     return config;
 }
-export function modelRefOf(spec, where) {
-    const slash = typeof spec === "string" ? spec.indexOf("/") : -1;
-    if (slash < 1 || slash === spec.length - 1) {
-        throw new Error(`${where} must be "provider/modelId", got ${JSON.stringify(spec)}`);
-    }
-    return { provider: spec.slice(0, slash), modelId: spec.slice(slash + 1) };
-}
 /** The agent package's `fastagent.config.ts`, checked; `{}` without one. */
 export async function loadConfig(dir) {
     const configPath = join(dir, CONFIG_FILE);
@@ -146,12 +141,15 @@ function declarers(definition) {
     ];
 }
 /** The secrets the definition declares, wherever: its code's `needs`, and `context.json`'s command variables. */
-export function definitionSecrets(definition) {
+function codeSecrets(definition) {
     return [
         ...declarers(definition).flatMap(({ source, value }) => isNeeds(value) ? value.secrets.map((secret) => ({ ...secret, source })) : []),
         ...declaredVariables(loadEnvironment(definition.dir)),
     ];
 }
+export function definitionSecrets(definition) {
+    return [...codeSecrets(definition), ...mcpSecrets(definition.dir)];
+}
 /**
  * The list a person deploying or running the agent reads instead of its code (`.fastagent/secrets.json`): each name
  * once, what it is for, whether the agent runs without it, and where it is declared.
@@ -205,7 +203,7 @@ const scheduleProblem = (value) => value?.kind !== "fastagent.schedule"
  * the values it declared, and refuse one that is not what its directory holds.
  */
 export function buildDefinition(definition, env = process.env) {
-    const missing = missingSecrets(definitionSecrets(definition), env);
+    const missing = missingSecrets(codeSecrets(definition), env);
     if (missing.length > 0) {
         throw new Error(`missing required secrets: ${describeSecrets(missing)} (set them in the environment)`);
     }
@@ -299,13 +297,18 @@ export async function assembleAgent(definition, options) {
         throw new Error(`unknown model "${spec}": no provider "${model.provider}" offers "${model.modelId}"${stale}`);
     }
     const ownWake = [...code.tools, ...code.extensions.flatMap((extension) => extension.tools ?? [])].some(({ name }) => WAKE_TOOLS.includes(name));
+    const authoredNames = new Set([...code.tools, ...code.extensions.flatMap((extension) => extension.tools ?? [])].map((tool) => tool.name));
+    for (const tool of options.mcpTools ?? []) {
+        if (authoredNames.has(tool.name))
+            throw new Error(`MCP tool ${tool.name} conflicts with an authored tool`);
+    }
     const registry = createRegistry();
     registry.install(CodingTools);
     // After the coding tools, so a tool of the definition's own with one of their names replaces it.
     registry.install(defineExtension({
         name: DEFINITION_EXTENSION,
         sections: definitionSections(dir, options.content ?? [], { wake: ownWake || options.stateRoot !== undefined }),
-        tools: code.tools,
+        tools: [...code.tools, ...(options.mcpTools ?? [])],
     }));
     for (const extension of code.extensions)
         registry.install(extension);

package/dist/harnesses/pi-durable/serve.d.ts

@@ -3,6 +3,7 @@ import { type Harness } from "@earendil-works/pi-durable";
 import type { CredentialSourceOptions } from "../models/credentials.ts";
 import { type ModelEnvironment } from "../models/environment.ts";
 import type { CredentialStore } from "../../sign-in-api.ts";
+import type { McpOptions } from "../../mcp-api.ts";
 import { type ResolvedContent } from "../../content/resolve.ts";
 import type { Agent } from "../../agent-api.ts";
 import { type Service } from "../../service.ts";
@@ -10,6 +11,7 @@ import type { DurableAgent, Unfinished } from "./agent.ts";
 import { type AgentDefinition, type BuiltDefinition } from "./open.ts";
 import { type StorageLocking } from "./storage.ts";
 export interface OpenServingOptions extends CredentialSourceOptions {
+    mcp?: McpOptions;
     /** What a deployment sets over the definition's defaults (a flag, `FASTAGENT_MODEL`). */
     model?: string;
     thinkingLevel?: ModelThinkingLevel;
@@ -39,7 +41,7 @@ export interface OpenedServing {
     definition: AgentDefinition;
     code: BuiltDefinition;
     models: ModelEnvironment;
-    /** What the agent works on and knows, resolved for this instance. */
+    /** What the agent works on, resolved for this instance. */
     content: readonly ResolvedContent[];
     agentDir: string;
     /** Where the instance's state is: its storage, its channels' and schedules' state, its wake-ups. */
@@ -71,6 +73,8 @@ export interface ServeAgentOptions {
     apiKeys?: readonly string[];
 }
 export interface OpenAgentOptions {
+    /** Per-instance MCP grants and interpolation values; no global credential discovery. */
+    mcp?: McpOptions;
     /** `"provider/modelId"`, over the definition's: what a session that names none answers with. */
     model?: string;
     /** Where provider credentials are kept, instead of the agent's own `.secrets/auth.json` over the machine's. */

package/dist/harnesses/pi-durable/serve.js

@@ -9,6 +9,10 @@ import { BACKGROUND_CONTEXT } from "@earendil-works/chord/context";
 import { MemoryStorage } from "@earendil-works/pi-durable";
 import { modelEnvironment } from "../models/environment.js";
 import { piCredentials } from "../models/host.js";
+import { openMcpClients } from "../../mcp/client.js";
+import { resolveMcpServers } from "../../mcp/config.js";
+import { mcpAuthorization } from "../../mcp/host.js";
+import { mcpTools } from "./mcp.js";
 import { loadContent } from "../../content/file.js";
 import { absentNotice, cloneContent, contentAbsentHere, resolveContent, } from "../../content/resolve.js";
 import { agentValues } from "../../value-file.js";
@@ -53,7 +57,7 @@ const instanceStorageFile = (stateRoot) => join(stateRoot, "agent.sqlite");
 export async function holdingInstance(stateRoot, work) {
     const storage = await openLockedStorage(instanceStorageFile(stateRoot), "posix", INSTANCE_HOLDERS);
     try {
-        return work();
+        return await work();
     }
     finally {
         await storage.close(BACKGROUND_CONTEXT);
@@ -84,23 +88,48 @@ export async function openServing(directory, options = {}) {
     }, code.providers, { stateRoot, environment });
     const chosen = options.storage ?? { instance: "posix" };
     const storage = await openStorage(stateRoot, chosen);
-    const agent = await assembleAgent(definition, {
-        storage,
-        code,
-        content,
-        environment,
-        models: models.models,
-        ...(models.catalogProblem === undefined ? {} : { catalogProblem: models.catalogProblem }),
-        ...(typeof chosen === "object" && "instance" in chosen ? { stateRoot } : {}),
-        ...(options.model === undefined ? {} : { model: options.model }),
-        ...(options.thinkingLevel === undefined ? {} : { thinkingLevel: options.thinkingLevel }),
-        ...(options.unfinished === undefined ? {} : { unfinished: options.unfinished }),
-        ...(options.wakeTicking === undefined ? {} : { wakeTicking: options.wakeTicking }),
-    }).catch(async (error) => {
-        // An Agent that did not open does not own the storage, and its lock would refuse this process's next attempt.
-        await storage.close(BACKGROUND_CONTEXT);
-        throw error;
+    let mcp;
+    let agent;
+    try {
+        const mcpEnvironment = { ...env, ...options.mcp?.variables };
+        mcp = await openMcpClients(resolveMcpServers(dir, mcpEnvironment), mcpAuthorization(dir, env, stateRoot, options.mcp), options.mcp);
+        agent = await assembleAgent(definition, {
+            mcpTools: mcpTools(mcp.tools),
+            storage,
+            code,
+            content,
+            environment,
+            models: models.models,
+            ...(models.catalogProblem === undefined ? {} : { catalogProblem: models.catalogProblem }),
+            ...(typeof chosen === "object" && "instance" in chosen ? { stateRoot } : {}),
+            ...(options.model === undefined ? {} : { model: options.model }),
+            ...(options.thinkingLevel === undefined ? {} : { thinkingLevel: options.thinkingLevel }),
+            ...(options.unfinished === undefined ? {} : { unfinished: options.unfinished }),
+            ...(options.wakeTicking === undefined ? {} : { wakeTicking: options.wakeTicking }),
+        });
+    }
+    catch (error) {
+        const failures = [error];
+        if (mcp)
+            await mcp.close().catch((cleanup) => failures.push(cleanup));
+        await storage.close(BACKGROUND_CONTEXT).catch((cleanup) => failures.push(cleanup));
+        throw failures.length === 1 ? error : new AggregateError(failures, "Agent open and cleanup failed");
+    }
+    // A storage failure or a direct harness close also ends the resources this open acquired.
+    void agent.harness.closed
+        .then(() => mcp.close())
+        .catch((error) => {
+        log.warn(`[fastagent] MCP cleanup after harness shutdown failed: ${String(error)}`);
     });
+    const closeAgent = agent.close.bind(agent);
+    let closing;
+    agent.close = () => (closing ??= (async () => {
+        const failures = [];
+        await closeAgent().catch((error) => failures.push(error));
+        await mcp.close().catch((error) => failures.push(error));
+        if (failures.length)
+            throw new AggregateError(failures, "Agent close failed");
+    })());
     return {
         agent,
         definition,
@@ -130,6 +159,7 @@ export async function openAgent(dir, options = {}) {
     let ticking = false;
     const opened = await openServing(dir, {
         wakeTicking: () => ticking,
+        ...(options.mcp === undefined ? {} : { mcp: options.mcp }),
         ...(options.model === undefined ? {} : { model: options.model }),
         ...(options.credentials === undefined ? {} : { credentialStore: piCredentials(options.credentials) }),
         ...(options.stateDir === undefined ? {} : { stateRoot: stateDirOf(options.stateDir) }),

package/dist/harnesses/pi-durable/text.js

@@ -263,14 +263,12 @@ function contentKind(c) {
     // changes stays, and reaches anyone else only when pushed. The declared ref is what it follows, not a claim about
     // where it is: a clone the agent moved elsewhere is left there.
     const clone = `a shallow clone of github ${c.repo}${c.ref ? ` (declared ${c.ref})` : ""} in your own storage`;
-    return c.readonly
-        ? `${clone}, brought up to date each time you start`
-        : `${clone}: what you change in it stays, and each time you start it is brought up to date where that touches nothing of yours; push to share a change`;
+    return `${clone}: what you change in it stays, and each time you start it is brought up to date where that touches nothing of yours; push to share a change`;
 }
 /**
  * Where the agent is and what it works on (agent-model.md §4): its own directory is itself, and each content entry is named
- * with its location, whether it is the agent's to change, and where a change there goes. A result written where it
- * does not last is how knowledge gets lost, so the agent is told which is which.
+ * with its location and where a change there goes. A result written where it does not last is how knowledge gets
+ * lost, so the agent is told which is which.
  */
 function contentSection({ agentDir, content }) {
     const own = `Your working directory, ${agentDir}, is your own directory: it holds your definition, and files you create ` +
@@ -278,15 +276,11 @@ function contentSection({ agentDir, content }) {
     if (content.length === 0)
         return `${own} Nothing else is declared for you: you work only in your own directory.`;
     const line = (c) => `- ${c.name}: ${c.location} (${contentKind(c)})${c.description !== undefined ? ` ${c.description}` : ""}`;
-    const worksOn = content.filter((c) => !c.readonly);
-    const knows = content.filter((c) => c.readonly);
     return [
         own,
-        ...(worksOn.length > 0 ? ["You work on:", ...worksOn.map(line)] : []),
-        ...(knows.length > 0 ? ["You know, and do not write:", ...knows.map(line)] : []),
-        `Run a command in one of these directories with \`cd <its location> && …\`; file tools take the location directly.` +
-            (worksOn.length > 0
-                ? " A result worth keeping belongs in a directory you work on, not in your own directory."
-                : " You write only in your own directory: the directories above are for reading."),
+        "You work on:",
+        ...content.map(line),
+        `Run a command in one of these directories with \`cd <its location> && …\`; file tools take the location directly. ` +
+            `A result worth keeping belongs in a directory you work on, not in your own directory.`,
     ].join("\n");
 }

package/dist/http/contract.d.ts

@@ -464,9 +464,6 @@ declare const AgentHttpApi_base: HttpApi.HttpApi<"fastagent", HttpApiGroup.HttpA
     readonly event: Schema.String;
     readonly data: Schema.String;
 }>, never, never>, Schema.Never, {
-    readonly type: "message";
-    readonly message: Message;
-} | {
     readonly type: "entry";
     readonly entry: Entry;
 } | {
@@ -502,6 +499,9 @@ declare const AgentHttpApi_base: HttpApi.HttpApi<"fastagent", HttpApiGroup.HttpA
         readonly retryable: boolean;
         readonly details?: Schema.Json | undefined;
     };
+} | {
+    readonly type: "message";
+    readonly message: Message;
 } | {
     readonly type: string;
 }> | Schema.toCodecJson<typeof Message>, Schema.toCodecJson<Schema.decodeTo<Schema.declare<AgentError, AgentError>, Schema.Struct<{

package/dist/index.d.ts

@@ -7,9 +7,17 @@ export type { Agent, AgentErrorData, AgentInfo, CompactOptions, ContentPart, Cre
 export { AgentError, LIMITS, hasEnded } from "./agent-api.ts";
 export { openAgent, type LocalAgent, type OpenAgentOptions, type ServeAgentOptions, } from "./harnesses/pi-durable/serve.ts";
 export type { Service } from "./service.ts";
-export { createAgent, type CreatedAgent } from "./authoring.ts";
+export { ContentNameError, addContent, createAgent, listContent, removeContent, type ContentEdit, type CreatedAgent, } from "./authoring.ts";
+export type { ContentAddition, SourceOptions } from "./content/source.ts";
+export { readContentSource } from "./content/source.ts";
+export type { BoundContent, ContentBinding, ContentEntry } from "./content/declare.ts";
+export type { ResolvedContent } from "./content/resolve.ts";
 export { SignInCancelled, type Credential, type CredentialStore, type ProviderAuth, type SignInEvent, type SignInInteraction, type SignInMethod, type SignInOption, type SignInPrompt, type SignInRequest, type SignInResult, } from "./sign-in-api.ts";
 export { credentialFile, providerAuth, signIn, signInOptions } from "./harnesses/models/host.ts";
+export { McpError, type McpErrorCode, type McpOptions, type McpAuthorization, type McpGrantRecord, type McpGrantSummary, type McpGrantStore, type McpGrantAccess, type McpServerSummary, type McpSignInRequest, type McpSignInInteraction, } from "./mcp-api.ts";
+export { inspectMcp } from "./mcp/host.ts";
+export { signInMcp } from "./mcp/sign-in.ts";
+export { mcpGrantFile } from "./mcp/grants.ts";
 export { defineAgent, defineSchedule, needs, type AgentConfig, type Needs, type SecretSpec, type SecretValues, } from "./harnesses/pi-durable/define.ts";
 export type { ScheduleConfig } from "./schedule/schedule.ts";
 export { defineChannel, type ChannelContext, type ChannelHandler, type ChannelModule, type ForkSource, type LongConnection, type LongConnectionChannelModule, type Routes, } from "./channel.ts";

package/dist/index.js

@@ -1,8 +1,13 @@
 export { AgentError, LIMITS, hasEnded } from "./agent-api.js";
 export { openAgent, } from "./harnesses/pi-durable/serve.js";
-export { createAgent } from "./authoring.js";
+export { ContentNameError, addContent, createAgent, listContent, removeContent, } from "./authoring.js";
+export { readContentSource } from "./content/source.js";
 export { SignInCancelled, } from "./sign-in-api.js";
 export { credentialFile, providerAuth, signIn, signInOptions } from "./harnesses/models/host.js";
+export { McpError, } from "./mcp-api.js";
+export { inspectMcp } from "./mcp/host.js";
+export { signInMcp } from "./mcp/sign-in.js";
+export { mcpGrantFile } from "./mcp/grants.js";
 export { defineAgent, defineSchedule, needs, } from "./harnesses/pi-durable/define.js";
 export { defineChannel, } from "./channel.js";
 // What a channel reads a request with, answers with, and compares its platform's secret with (constant time).

package/dist/locked-file.d.ts

@@ -3,8 +3,8 @@ export interface LockResult<T> {
     /** New file content to persist under the lock; undefined = no write. */
     next?: string;
 }
-/** Serialized cross-process read-modify-write of one file, replaced whole so its readers need no lock. */
-export declare function withLockedFile<T>(path: string, fn: (current: string | undefined) => Promise<LockResult<T>>, 
+/** Serialized read-modify-write. `replace` commits immediately under the lock; those writes survive a later failure. */
+export declare function withLockedFile<T>(path: string, fn: (current: string | undefined, replace: (next: string) => void) => Promise<LockResult<T>>, 
 /**
  * `mode`: the replaced file's permissions; default {@link SECRET_FILE_MODE}, for the credential and catalog files.
  * `create: false` locks a file that may not exist without creating it (the lock is `<file>.lock` either way), for a

package/dist/locked-file.js

@@ -26,7 +26,7 @@ function writeTarget(path) {
     // ever shows up in a real layout.
     return link?.isSymbolicLink() ? resolve(dirname(path), readlinkSync(path)) : path;
 }
-/** Serialized cross-process read-modify-write of one file, replaced whole so its readers need no lock. */
+/** Serialized read-modify-write. `replace` commits immediately under the lock; those writes survive a later failure. */
 export async function withLockedFile(path, fn, 
 /**
  * `mode`: the replaced file's permissions; default {@link SECRET_FILE_MODE}, for the credential and catalog files.
@@ -71,7 +71,12 @@ options = {}) {
     try {
         throwIfCompromised();
         const current = existsSync(path) ? readFileSync(path, "utf8") : undefined;
-        const out = await fn(current);
+        const replace = (next) => {
+            throwIfCompromised();
+            options.signal?.throwIfAborted();
+            writeFileAtomic(writeTarget(path), next, options.mode ?? SECRET_FILE_MODE);
+        };
+        const out = await fn(current, replace);
         throwIfCompromised();
         // The last moment a caller that gave up can keep its change off disk: waiting for the lock may have outlasted it
         // (another process held the lock through the caller's timeout or cancel).
@@ -79,7 +84,7 @@ options = {}) {
         // Rename, not an in-place rewrite: it is what lets `read` stay unlocked, and it is the only spelling that applies
         // the mode before the content is reachable.
         if (out.next !== undefined) {
-            writeFileAtomic(writeTarget(path), out.next, options.mode ?? SECRET_FILE_MODE);
+            replace(out.next);
         }
         throwIfCompromised();
         result = out.result;

package/dist/mcp/auth.d.ts

@@ -0,0 +1,22 @@
+import { type AuthorizationServerMetadata, type OAuthProtectedResourceMetadata } from "@modelcontextprotocol/client";
+import { McpError, type McpGrantRecord, type McpGrantStore } from "../mcp-api.ts";
+export interface McpDiscovery {
+    metadata: AuthorizationServerMetadata;
+    resourceMetadata: OAuthProtectedResourceMetadata;
+    issuer: string;
+    resource: string;
+}
+export declare function discoverMcp(url: string, fetchImpl: typeof globalThis.fetch): Promise<McpDiscovery>;
+export declare function checkGrantTarget(record: McpGrantRecord, url: string, discovery?: McpDiscovery): void;
+export declare function mcpFailure(error: unknown, operation: string, server?: string): McpError;
+export declare function grantToken(input: {
+    store: McpGrantStore;
+    id: string;
+    url: string;
+    fetch: typeof globalThis.fetch;
+    discovery?: McpDiscovery;
+    rejectedGeneration?: number;
+}): Promise<{
+    token: string;
+    generation: number;
+}>;

package/dist/mcp/auth.js

@@ -0,0 +1,180 @@
+/** OAuth discovery and refresh policy. Background calls never start an interactive sign-in. */
+import { getSystemErrorMap } from "node:util";
+import { checkResourceAllowed, discoverOAuthProtectedResourceMetadata, discoverAuthorizationServerMetadata, extractWWWAuthenticateParams, refreshAuthorization, OAuthError, OAuthErrorCode, SdkError, SdkErrorCode, SdkHttpError, UnauthorizedError, InsufficientScopeError, IssuerMismatchError, } from "@modelcontextprotocol/client";
+import { McpError } from "../mcp-api.js";
+import { checkMcpTarget } from "./network.js";
+import { checkedGrant } from "./grants.js";
+export async function discoverMcp(url, fetchImpl) {
+    const challenge = await fetchImpl(url, { headers: { Accept: "application/json, text/event-stream" } });
+    await challenge.body?.cancel();
+    if (!challenge.ok && ![401, 403, 404, 405].includes(challenge.status))
+        throw new McpError("connection", `MCP resource probe failed (HTTP ${challenge.status})`);
+    const { resourceMetadataUrl } = extractWWWAuthenticateParams(challenge);
+    const hints = challenge.headers.get("www-authenticate")?.match(/\bresource_metadata\s*=/gi) ?? [];
+    if (hints.length > 1 || (hints.length === 1 && !resourceMetadataUrl))
+        throw new McpError("protocol", "Unusable MCP resource_metadata challenge; refusing default discovery");
+    if (resourceMetadataUrl)
+        checkMcpTarget(url, resourceMetadataUrl.href);
+    const resource = await discoverOAuthProtectedResourceMetadata(url, { resourceMetadataUrl }, fetchImpl);
+    const issuer = resource.authorization_servers?.[0] ?? new URL("/", url).href;
+    checkMcpTarget(url, issuer);
+    const metadata = await discoverAuthorizationServerMetadata(issuer, { fetchFn: fetchImpl });
+    if (!metadata ||
+        !resource ||
+        !checkResourceAllowed({ requestedResource: new URL(url), configuredResource: resource.resource })) {
+        throw new McpError("authorization_mismatch", "MCP authorization discovery did not identify the configured resource and issuer");
+    }
+    checkMcpTarget(url, metadata.issuer);
+    checkMcpTarget(url, metadata.authorization_endpoint);
+    checkMcpTarget(url, metadata.token_endpoint);
+    if (metadata.registration_endpoint)
+        checkMcpTarget(url, metadata.registration_endpoint);
+    return { metadata, resourceMetadata: resource, resource: resource.resource, issuer: metadata.issuer };
+}
+export function checkGrantTarget(record, url, discovery) {
+    if (record.serverUrl !== url ||
+        (discovery && (record.issuer !== discovery.issuer || record.resource !== discovery.resource))) {
+        throw new McpError("authorization_mismatch", "MCP grant belongs to a different endpoint, resource or issuer; sign in explicitly for this server");
+    }
+}
+const safeReasons = new Map([
+    ...getSystemErrorMap().values(),
+    ["ENOTFOUND", "DNS name not found"],
+    ["ERR_SSL_WRONG_VERSION_NUMBER", "TLS peer did not speak the expected protocol"],
+    ["UND_ERR_CONNECT_TIMEOUT", "connection timed out"],
+    ["UND_ERR_HEADERS_TIMEOUT", "response headers timed out"],
+    ["UND_ERR_BODY_TIMEOUT", "response body timed out"],
+    ["UND_ERR_SOCKET", "socket closed or failed"],
+    ["UND_ERR_CLOSED", "HTTP client closed"],
+    ["UND_ERR_DESTROYED", "HTTP client destroyed"],
+    ["ERR_TLS_CERT_ALTNAME_INVALID", "TLS certificate hostname mismatch"],
+    ["CERT_HAS_EXPIRED", "TLS certificate expired"],
+    ["DEPTH_ZERO_SELF_SIGNED_CERT", "untrusted self-signed TLS certificate"],
+    ["SELF_SIGNED_CERT_IN_CHAIN", "untrusted TLS certificate chain"],
+    ["UNABLE_TO_VERIFY_LEAF_SIGNATURE", "TLS certificate could not be verified"],
+    ["UNABLE_TO_GET_ISSUER_CERT_LOCALLY", "TLS certificate issuer is not trusted"],
+]);
+const sdkCodes = new Set([...Object.values(SdkErrorCode), ...Object.values(OAuthErrorCode)]);
+const errorNames = new Set([
+    "Error",
+    "TypeError",
+    "SyntaxError",
+    "RangeError",
+    "ReferenceError",
+    "URIError",
+    "EvalError",
+    "AbortError",
+    "TimeoutError",
+    "AggregateError",
+    "OAuthError",
+    "SdkError",
+]);
+function safeFailureReason(error) {
+    const pending = [error];
+    const seen = new Set();
+    const reasons = new Set();
+    while (pending.length) {
+        const current = pending.pop();
+        if (!(current instanceof Error) || seen.has(current))
+            continue;
+        seen.add(current);
+        const code = "code" in current && typeof current.code === "string" ? current.code : undefined;
+        if (code !== undefined) {
+            const reason = safeReasons.get(code);
+            if (reason !== undefined)
+                reasons.add(`${code}: ${reason}`);
+            else if (sdkCodes.has(code))
+                reasons.add(code);
+        }
+        // SDK 2.4's pinned stdio probe omits structured close data; recognize only its fixed diagnostic prefix.
+        if (current.message === "Connection closed during the version negotiation probe" ||
+            (current instanceof SdkError &&
+                current.code === SdkErrorCode.EraNegotiationFailed &&
+                current.message.startsWith("Version negotiation failed: the connection closed during the server/discover probe before the server offered pinned protocol version ")))
+            reasons.add("CONNECTION_CLOSED: server closed during protocol discovery");
+        if (current instanceof SdkHttpError &&
+            Number.isInteger(current.status) &&
+            current.status >= 100 &&
+            current.status <= 599)
+            reasons.add(`HTTP ${current.status}`);
+        pending.push(current.cause);
+        if (current instanceof AggregateError && Array.isArray(current.errors))
+            pending.push(...current.errors);
+    }
+    if (reasons.size)
+        return [...reasons].join("; ");
+    return error instanceof Error ? (errorNames.has(error.name) ? error.name : "Error") : "unknown error";
+}
+export function mcpFailure(error, operation, server) {
+    if (error instanceof McpError)
+        return error.server || !server ? error : new McpError(error.code, error.message, server);
+    if (error instanceof IssuerMismatchError)
+        return new McpError("authorization_mismatch", `${operation}: OAuth issuer validation failed`, server);
+    if (error instanceof UnauthorizedError || (error instanceof SdkHttpError && error.status === 401))
+        return new McpError("authorization_required", `${operation}: MCP authorization required; sign in for this server`, server);
+    if (error instanceof InsufficientScopeError || (error instanceof SdkHttpError && error.status === 403))
+        return new McpError("insufficient_scope", `${operation}: MCP access refused (HTTP 403); review the grant permissions`, server);
+    // Error messages, paths, args, stderr and raw causes can contain credentials; only allowlisted facts escape.
+    return new McpError("connection", `${operation} failed (${safeFailureReason(error)})`, server);
+}
+export async function grantToken(input) {
+    return input.store.withGrant(input.id, async (access) => {
+        const raw = access.read();
+        if (!raw)
+            throw new McpError("authorization_required", "No MCP grant is stored; sign in before opening this agent");
+        const record = checkedGrant(raw);
+        checkGrantTarget(record, input.url, input.discovery);
+        if (record.status !== "ready")
+            throw new McpError(record.status === "refreshing" ? "refresh_uncertain" : "authorization_required", "MCP authorization must be renewed; the previous grant cannot be refreshed safely");
+        const fresh = record.expiresAt === undefined || record.expiresAt > Date.now() + 30_000;
+        if (fresh && (input.rejectedGeneration === undefined || record.generation !== input.rejectedGeneration)) {
+            return { token: record.accessToken, generation: record.generation };
+        }
+        if (!record.refreshToken) {
+            await access.write({ ...record, status: "reauthorization_required" });
+            throw new McpError("authorization_required", "MCP authorization expired and has no refresh token; sign in again");
+        }
+        const discovery = await discoverMcp(input.url, input.fetch);
+        checkGrantTarget(record, input.url, discovery);
+        // Persist before the remote server can consume the old token. A lost response cannot be replayed safely.
+        await access.write({ ...record, status: "refreshing" });
+        let tokens;
+        try {
+            tokens = await refreshAuthorization(record.issuer, {
+                metadata: discovery.metadata,
+                clientInformation: {
+                    client_id: record.client.id,
+                    ...(record.client.secret === undefined ? {} : { client_secret: record.client.secret }),
+                    token_endpoint_auth_method: record.client.tokenEndpointAuthMethod,
+                },
+                refreshToken: record.refreshToken,
+                resource: record.resource,
+                fetchFn: input.fetch,
+            });
+        }
+        catch (error) {
+            if (error instanceof OAuthError &&
+                ["invalid_grant", "invalid_client", "unauthorized_client"].includes(error.code)) {
+                await access.write({ ...record, status: "reauthorization_required" });
+                throw new McpError("authorization_required", "The MCP authorization server refused the refresh; sign in again");
+            }
+            throw mcpFailure(error, "MCP token refresh");
+        }
+        const scopes = tokens.scope === undefined ? record.scopes : tokens.scope.split(/\s+/).filter(Boolean);
+        if (scopes.some((scope) => !record.scopes.includes(scope)))
+            throw new McpError("insufficient_scope", "MCP refresh unexpectedly expanded the grant's scopes");
+        const next = {
+            ...record,
+            scopes,
+            status: "ready",
+            generation: record.generation + 1,
+            accessToken: tokens.access_token,
+            ...(tokens.refresh_token === undefined ? {} : { refreshToken: tokens.refresh_token }),
+            expiresAt: tokens.expires_in === undefined ? undefined : Date.now() + tokens.expires_in * 1000,
+        };
+        if (tokens.token_type.toLowerCase() !== "bearer")
+            throw new McpError("protocol", "Only bearer MCP grants are supported");
+        await access.write(next);
+        return { token: next.accessToken, generation: next.generation };
+    });
+}

package/dist/mcp/client.d.ts

@@ -0,0 +1,15 @@
+/** Instance-owned MCP clients. The scope also joins refreshes after a caller abandons its wait. */
+import { type Tool, type CallToolResult } from "@modelcontextprotocol/client";
+import { type McpAuthorization, type McpOptions } from "../mcp-api.ts";
+import type { McpServer } from "./config.ts";
+export interface McpTool {
+    name: string;
+    server: string;
+    definition: Tool;
+    call(args: Record<string, unknown>, signal?: AbortSignal, progress?: (text: string) => void): Promise<CallToolResult>;
+}
+export interface McpClients {
+    tools: McpTool[];
+    close(): Promise<void>;
+}
+export declare function openMcpClients(servers: readonly McpServer[], auth: McpAuthorization, options?: Pick<McpOptions, "fetch">): Promise<McpClients>;