@cuylabs/agent-core 4.9.0 → 5.0.0

package/dist/intervention/intervention.d.ts

@@ -0,0 +1,130 @@
+/**
+ * Intervention Controller for @cuylabs/agent-core
+ *
+ * Manages mid-turn message injection into running agent turns.
+ * Uses Vercel AI SDK v6's `prepareStep` hook for zero-overhead
+ * integration at step boundaries (between LLM calls in a multi-step turn).
+ *
+ * Instead of polling a queue after each tool execution, this leverages
+ * the SDK's native step lifecycle. The
+ * `prepareStep` callback fires before every LLM call, giving us a
+ * natural injection point with no custom loop machinery.
+ *
+ * Two injection modes:
+ * - **Immediate**: `intervene(msg)` — injected at the next step boundary
+ * - **Deferred**: `queueNext(msg)` — held until the turn completes
+ */
+/** A queued intervention message waiting to be applied */
+export interface PendingIntervention {
+    /** Unique identifier for tracking */
+    readonly id: string;
+    /** The user message to inject */
+    readonly message: string;
+    /** When the intervention was created */
+    readonly createdAt: Date;
+}
+/**
+ * Callback fired when an intervention is applied to a step.
+ *
+ * The agent uses this to push `intervention-applied` events into
+ * the streaming event queue so they reach the consumer in the
+ * correct order relative to other events.
+ */
+export type OnInterventionApplied = (intervention: PendingIntervention) => void;
+export type OnFollowUpQueued = (intervention: PendingIntervention) => void;
+/**
+ * Manages mid-turn message injection for agents.
+ *
+ * This is the core primitive that connects user redirection intent
+ * to the AI SDK's multi-step loop. The flow:
+ *
+ * 1. Consumer calls `agent.intervene("focus on auth.ts")` from any async context
+ * 2. The message is queued as a `PendingIntervention`
+ * 3. At the next step boundary, `prepareStep` drains the queue
+ * 4. The message is appended to the LLM's input messages
+ * 5. The LLM responds to the redirect naturally
+ *
+ * Thread safety: All operations are synchronous and run on the
+ * same event loop. No locks needed — Node.js guarantees ordering.
+ *
+ * @example
+ * ```typescript
+ * const ctrl = new InterventionController();
+ *
+ * // Queue an intervention (from a UI handler, WebSocket, etc.)
+ * const id = ctrl.intervene("stop refactoring, fix the failing test first");
+ *
+ * // Later, in prepareStep:
+ * const pending = ctrl.drainImmediate();
+ * // → [{ id, message: "stop refactoring...", createdAt }]
+ * ```
+ */
+export declare class InterventionController {
+    /** Immediate interventions — applied at the next step boundary */
+    private immediate;
+    /** Deferred messages — held until the turn completes */
+    private deferred;
+    /**
+     * Callback fired when an intervention is wired into a step.
+     * Set by the Agent before starting a chat turn, cleared after.
+     */
+    onApplied?: OnInterventionApplied;
+    /** Callback fired when a deferred follow-up is queued. */
+    onDeferredQueued?: OnFollowUpQueued;
+    /**
+     * Inject a message at the next LLM step boundary.
+     *
+     * The message is appended as a user message to the conversation
+     * before the next LLM call in the current multi-step turn. The
+     * LLM will see it and can adjust its behavior accordingly.
+     *
+     * Safe to call from any async context while `chat()` is running.
+     * If called when no turn is active, the message will be picked up
+     * by the first step of the next `chat()` call.
+     *
+     * @param message - The user message to inject
+     * @returns Intervention ID for tracking
+     */
+    intervene(message: string): string;
+    /**
+     * Drain and return all pending immediate interventions.
+     * The internal queue is cleared atomically.
+     *
+     * @internal Called by the LLM stream's `prepareStep` hook
+     */
+    drainImmediate(): PendingIntervention[];
+    /** Adopt existing immediate interventions without changing their IDs. */
+    adoptImmediate(items: PendingIntervention[]): void;
+    /** Whether there are pending immediate interventions */
+    get hasPending(): boolean;
+    /** Number of pending immediate interventions */
+    get pendingCount(): number;
+    /**
+     * Queue a message for after the current turn completes.
+     *
+     * Unlike `intervene()`, this does **not** inject mid-turn. The
+     * message is held and available via `drainDeferred()` after
+     * `chat()` finishes. The consumer decides whether to send it
+     * as a new turn.
+     *
+     * @param message - The message to queue
+     * @returns Intervention ID for tracking
+     */
+    queueNext(message: string): string;
+    /**
+     * Drain and return all deferred messages.
+     * The internal queue is cleared atomically.
+     */
+    drainDeferred(): PendingIntervention[];
+    /** Adopt existing deferred interventions without changing their IDs. */
+    adoptDeferred(items: PendingIntervention[]): void;
+    /** Whether there are deferred messages */
+    get hasDeferred(): boolean;
+    /** Number of deferred messages */
+    get deferredCount(): number;
+    /** Clear all queues (immediate + deferred) */
+    clear(): void;
+    /** Reset the controller for a new turn (clears onApplied, keeps queues) */
+    resetCallbacks(): void;
+}
+//# sourceMappingURL=intervention.d.ts.map

package/dist/intervention/intervention.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"intervention.d.ts","sourceRoot":"","sources":["../../src/intervention/intervention.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAMH,0DAA0D;AAC1D,MAAM,WAAW,mBAAmB;IAClC,qCAAqC;IACrC,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,iCAAiC;IACjC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,wCAAwC;IACxC,QAAQ,CAAC,SAAS,EAAE,IAAI,CAAC;CAC1B;AAED;;;;;;GAMG;AACH,MAAM,MAAM,qBAAqB,GAAG,CAAC,YAAY,EAAE,mBAAmB,KAAK,IAAI,CAAC;AAChF,MAAM,MAAM,gBAAgB,GAAG,CAAC,YAAY,EAAE,mBAAmB,KAAK,IAAI,CAAC;AAM3E;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,qBAAa,sBAAsB;IACjC,kEAAkE;IAClE,OAAO,CAAC,SAAS,CAA6B;IAE9C,wDAAwD;IACxD,OAAO,CAAC,QAAQ,CAA6B;IAE7C;;;OAGG;IACH,SAAS,CAAC,EAAE,qBAAqB,CAAC;IAClC,0DAA0D;IAC1D,gBAAgB,CAAC,EAAE,gBAAgB,CAAC;IAMpC;;;;;;;;;;;;;OAaG;IACH,SAAS,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM;IAMlC;;;;;OAKG;IACH,cAAc,IAAI,mBAAmB,EAAE;IAKvC,yEAAyE;IACzE,cAAc,CAAC,KAAK,EAAE,mBAAmB,EAAE,GAAG,IAAI;IAKlD,wDAAwD;IACxD,IAAI,UAAU,IAAI,OAAO,CAExB;IAED,gDAAgD;IAChD,IAAI,YAAY,IAAI,MAAM,CAEzB;IAMD;;;;;;;;;;OAUG;IACH,SAAS,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM;IAQlC;;;OAGG;IACH,aAAa,IAAI,mBAAmB,EAAE;IAKtC,wEAAwE;IACxE,aAAa,CAAC,KAAK,EAAE,mBAAmB,EAAE,GAAG,IAAI;IAKjD,0CAA0C;IAC1C,IAAI,WAAW,IAAI,OAAO,CAEzB;IAED,kCAAkC;IAClC,IAAI,aAAa,IAAI,MAAM,CAE1B;IAMD,8CAA8C;IAC9C,KAAK,IAAI,IAAI;IAKb,2EAA2E;IAC3E,cAAc,IAAI,IAAI;CAIvB"}

package/dist/intervention/types.d.ts

@@ -0,0 +1,74 @@
+/**
+ * Shared intervention/follow-up types for @cuylabs/agent-core.
+ *
+ * These types give runtimes (agent-server, agent-runtime-dapr) a common
+ * vocabulary for user-directed turn control:
+ * - immediate mid-turn steering
+ * - deferred follow-ups queued for the next turn
+ *
+ * The `InterventionController` remains the in-process implementation;
+ * these types are the protocol-level representation for cross-process
+ * and durable scenarios.
+ */
+/**
+ * A steering request surfaced to runtime consumers.
+ *
+ * Created when a client calls `steerTurn()` (agent-server) or
+ * `POST /agents/:id/steer` (agent-runtime-dapr). Runtimes publish
+ * an `intervention-applied` event so UIs can show the injection.
+ */
+export interface SteeringRequest {
+    /** Unique identifier (maps to `PendingIntervention.id` in direct mode) */
+    id: string;
+    /** Session the steering targets */
+    sessionId: string;
+    /** The user message to inject */
+    message: string;
+    /** When the steering was requested */
+    timestamp: number;
+}
+/**
+ * Acknowledgement returned after a steering message is accepted.
+ *
+ * In direct mode, the message is already queued in the
+ * `InterventionController`. In durable mode, it is persisted in
+ * state and will be picked up at the next workflow activity boundary.
+ */
+export interface SteeringResponse {
+    /** The steering request ID */
+    id: string;
+    /** Whether the message was accepted */
+    accepted: boolean;
+}
+/**
+ * A deferred follow-up request surfaced to runtime consumers.
+ *
+ * Created when a client calls `followUpTurn()` (agent-server) or
+ * `POST /agents/:id/follow-up` (agent-runtime-dapr). Runtimes publish
+ * a `follow-up-queued` event so UIs can show that the message will be
+ * available after the current turn completes.
+ */
+export interface FollowUpRequest {
+    /** Unique identifier (maps to `PendingIntervention.id` in direct mode) */
+    id: string;
+    /** Session the follow-up targets */
+    sessionId: string;
+    /** The user message to queue for the next turn */
+    message: string;
+    /** When the follow-up was requested */
+    timestamp: number;
+}
+/**
+ * Acknowledgement returned after a follow-up message is accepted.
+ *
+ * In direct mode, the message is queued in the `InterventionController`.
+ * In durable mode, it is persisted in the runtime's durable follow-up store
+ * and becomes seedable on the next turn for the same session.
+ */
+export interface FollowUpResponse {
+    /** The follow-up request ID */
+    id: string;
+    /** Whether the message was accepted */
+    accepted: boolean;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/intervention/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/intervention/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH;;;;;;GAMG;AACH,MAAM,WAAW,eAAe;IAC9B,0EAA0E;IAC1E,EAAE,EAAE,MAAM,CAAC;IACX,mCAAmC;IACnC,SAAS,EAAE,MAAM,CAAC;IAClB,iCAAiC;IACjC,OAAO,EAAE,MAAM,CAAC;IAChB,sCAAsC;IACtC,SAAS,EAAE,MAAM,CAAC;CACnB;AAED;;;;;;GAMG;AACH,MAAM,WAAW,gBAAgB;IAC/B,8BAA8B;IAC9B,EAAE,EAAE,MAAM,CAAC;IACX,uCAAuC;IACvC,QAAQ,EAAE,OAAO,CAAC;CACnB;AAED;;;;;;;GAOG;AACH,MAAM,WAAW,eAAe;IAC9B,0EAA0E;IAC1E,EAAE,EAAE,MAAM,CAAC;IACX,oCAAoC;IACpC,SAAS,EAAE,MAAM,CAAC;IAClB,kDAAkD;IAClD,OAAO,EAAE,MAAM,CAAC;IAChB,uCAAuC;IACvC,SAAS,EAAE,MAAM,CAAC;CACnB;AAED;;;;;;GAMG;AACH,MAAM,WAAW,gBAAgB;IAC/B,+BAA+B;IAC/B,EAAE,EAAE,MAAM,CAAC;IACX,uCAAuC;IACvC,QAAQ,EAAE,OAAO,CAAC;CACnB"}

package/dist/logger/index.d.ts

@@ -1,50 +1,8 @@
-import { C as ConsoleLoggerOptions, L as Logger, F as FileLoggerOptions } from '../types-RSCv7nQ4.js';
-export { a as LogLevel, b as LogMeta } from '../types-RSCv7nQ4.js';
-
 /**
- * Built-in logger implementations.
+ * Logger module barrel.
  *
- * - `silentLogger`         — no-op (default for agents)
- * - `createConsoleLogger`  — pretty console output with level gating
- * - `createFileLogger`     — append-only file output for debugging
+ * Re-exports the Logger interface, built-in implementations, and factory.
  */
-
-/**
- * A logger that discards every message.
- *
- * This is the default used when no logger is supplied to `createAgent()`.
- */
-declare const silentLogger: Logger;
-/**
- * Create a console-backed logger with configurable minimum level.
- *
- * ```ts
- * import { createConsoleLogger } from "@cuylabs/agent-core";
- *
- * const agent = createAgent({
- *   model,
- *   logger: createConsoleLogger({ level: "debug" }),
- * });
- * ```
- *
- * Respects the `AGENT_LOG_LEVEL` environment variable when no explicit
- * level is supplied, falling back to `"warn"`.
- */
-declare function createConsoleLogger(options?: ConsoleLoggerOptions): Logger;
-/**
- * Create a file-backed logger that appends timestamped entries.
- *
- * ```ts
- * import { createFileLogger } from "@cuylabs/agent-core";
- *
- * const logger = createFileLogger({ filePath: "/tmp/team.log", level: "debug" });
- * ```
- *
- * The log file is created (with parent directories) if it doesn't exist.
- * All writes are non-blocking; write errors are silently swallowed.
- */
-declare function createFileLogger(options: FileLoggerOptions): Logger & {
-    close(): void;
-};
-
-export { ConsoleLoggerOptions, FileLoggerOptions, Logger, createConsoleLogger, createFileLogger, silentLogger };
+export type { Logger, LogLevel, LogMeta, ConsoleLoggerOptions, FileLoggerOptions, } from "./types.js";
+export { silentLogger, createConsoleLogger, createFileLogger, } from "./logger.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/logger/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/logger/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,YAAY,EACV,MAAM,EACN,QAAQ,EACR,OAAO,EACP,oBAAoB,EACpB,iBAAiB,GAClB,MAAM,YAAY,CAAC;AACpB,OAAO,EACL,YAAY,EACZ,mBAAmB,EACnB,gBAAgB,GACjB,MAAM,aAAa,CAAC"}

package/dist/logger/logger.d.ts

@@ -0,0 +1,46 @@
+/**
+ * Built-in logger implementations.
+ *
+ * - `silentLogger`         — no-op (default for agents)
+ * - `createConsoleLogger`  — pretty console output with level gating
+ * - `createFileLogger`     — append-only file output for debugging
+ */
+import type { ConsoleLoggerOptions, FileLoggerOptions, Logger } from "./types.js";
+/**
+ * A logger that discards every message.
+ *
+ * This is the default used when no logger is supplied to `createAgent()`.
+ */
+export declare const silentLogger: Logger;
+/**
+ * Create a console-backed logger with configurable minimum level.
+ *
+ * ```ts
+ * import { createConsoleLogger } from "@cuylabs/agent-core";
+ *
+ * const agent = createAgent({
+ *   model,
+ *   logger: createConsoleLogger({ level: "debug" }),
+ * });
+ * ```
+ *
+ * Respects the `AGENT_LOG_LEVEL` environment variable when no explicit
+ * level is supplied, falling back to `"warn"`.
+ */
+export declare function createConsoleLogger(options?: ConsoleLoggerOptions): Logger;
+/**
+ * Create a file-backed logger that appends timestamped entries.
+ *
+ * ```ts
+ * import { createFileLogger } from "@cuylabs/agent-core";
+ *
+ * const logger = createFileLogger({ filePath: "/tmp/team.log", level: "debug" });
+ * ```
+ *
+ * The log file is created (with parent directories) if it doesn't exist.
+ * All writes are non-blocking; write errors are silently swallowed.
+ */
+export declare function createFileLogger(options: FileLoggerOptions): Logger & {
+    close(): void;
+};
+//# sourceMappingURL=logger.d.ts.map

package/dist/logger/logger.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"logger.d.ts","sourceRoot":"","sources":["../../src/logger/logger.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAIH,OAAO,KAAK,EACV,oBAAoB,EACpB,iBAAiB,EACjB,MAAM,EAGP,MAAM,YAAY,CAAC;AAqBpB;;;;GAIG;AACH,eAAO,MAAM,YAAY,EAAE,MAQ1B,CAAC;AAuDF;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,mBAAmB,CACjC,OAAO,GAAE,oBAAyB,GACjC,MAAM,CAQR;AAkDD;;;;;;;;;;;GAWG;AACH,wBAAgB,gBAAgB,CAC9B,OAAO,EAAE,iBAAiB,GACzB,MAAM,GAAG;IAAE,KAAK,IAAI,IAAI,CAAA;CAAE,CAe5B"}

package/dist/{types-RSCv7nQ4.d.ts → logger/types.d.ts}

@@ -8,9 +8,9 @@
  * output by supplying a concrete logger via `createAgent({ logger })`.
  */
 /** Structured metadata bag attached to log entries. */
-type LogMeta = Record<string, unknown>;
+export type LogMeta = Record<string, unknown>;
 /** Log severity levels, lowest to highest. */
-type LogLevel = "debug" | "info" | "warn" | "error";
+export type LogLevel = "debug" | "info" | "warn" | "error";
 /**
  * Core logger contract.
  *
@@ -18,7 +18,7 @@ type LogLevel = "debug" | "info" | "warn" | "error";
  * The interface is intentionally compatible with `RuntimeLogger` from
  * `@cuylabs/agent-runtime` so the same object can serve both roles.
  */
-interface Logger {
+export interface Logger {
     debug(message: string, meta?: LogMeta): void;
     info(message: string, meta?: LogMeta): void;
     warn(message: string, meta?: LogMeta): void;
@@ -38,7 +38,7 @@ interface Logger {
 /**
  * Options accepted by the built-in console logger factory.
  */
-interface ConsoleLoggerOptions {
+export interface ConsoleLoggerOptions {
     /** Minimum level to emit. Messages below this are discarded. Default: `"warn"`. */
     level?: LogLevel;
     /** Prefix prepended to every line. Default: `"agent-core"`. */
@@ -47,7 +47,7 @@ interface ConsoleLoggerOptions {
 /**
  * Options for the file-backed logger factory.
  */
-interface FileLoggerOptions {
+export interface FileLoggerOptions {
     /** Absolute path to the log file. Created (with parents) if it doesn't exist. */
     filePath: string;
     /** Minimum level to emit. Default: `"debug"`. */
@@ -55,5 +55,4 @@ interface FileLoggerOptions {
     /** Prefix prepended to every line. Default: `"agent-core"`. */
     prefix?: string;
 }
-
-export type { ConsoleLoggerOptions as C, FileLoggerOptions as F, Logger as L, LogLevel as a, LogMeta as b };
+//# sourceMappingURL=types.d.ts.map

package/dist/logger/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/logger/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,uDAAuD;AACvD,MAAM,MAAM,OAAO,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;AAE9C,8CAA8C;AAC9C,MAAM,MAAM,QAAQ,GAAG,OAAO,GAAG,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC;AAE3D;;;;;;GAMG;AACH,MAAM,WAAW,MAAM;IACrB,KAAK,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,OAAO,GAAG,IAAI,CAAC;IAC7C,IAAI,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,OAAO,GAAG,IAAI,CAAC;IAC5C,IAAI,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,OAAO,GAAG,IAAI,CAAC;IAC5C,KAAK,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,OAAO,GAAG,IAAI,CAAC;IAE7C;;;;;;;;;OASG;IACH,KAAK,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,CAAC;CAClC;AAED;;GAEG;AACH,MAAM,WAAW,oBAAoB;IACnC,mFAAmF;IACnF,KAAK,CAAC,EAAE,QAAQ,CAAC;IACjB,+DAA+D;IAC/D,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED;;GAEG;AACH,MAAM,WAAW,iBAAiB;IAChC,iFAAiF;IACjF,QAAQ,EAAE,MAAM,CAAC;IACjB,iDAAiD;IACjD,KAAK,CAAC,EAAE,QAAQ,CAAC;IACjB,+DAA+D;IAC/D,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB"}

package/dist/mcp/auth.d.ts

@@ -0,0 +1,109 @@
+import type { OAuthClientProvider } from "@modelcontextprotocol/sdk/client/auth.js";
+import type { OAuthClientInformation, OAuthClientMetadata, OAuthTokens } from "@modelcontextprotocol/sdk/shared/auth.js";
+/**
+ * Options for {@linkcode ClientCredentialsProvider}.
+ */
+export interface ClientCredentialsOptions {
+    /**
+     * OAuth `client_id`.
+     */
+    clientId: string;
+    /**
+     * OAuth `client_secret`.
+     */
+    clientSecret: string;
+    /**
+     * The token endpoint URL.
+     * Required because machine-to-machine flows don't go through OAuth discovery
+     * (there is no user redirect that would trigger `/.well-known` lookups).
+     *
+     * @example "https://auth.example.com/oauth/token"
+     * @example "https://login.microsoftonline.com/<tenant>/oauth2/v2.0/token"
+     */
+    tokenUrl: string;
+    /**
+     * Space-separated OAuth scopes to request.
+     */
+    scope?: string;
+    /**
+     * Seconds before token expiry at which a proactive refresh is triggered.
+     * @default 60
+     */
+    expiryBufferSeconds?: number;
+    /**
+     * Fetch implementation for the token endpoint.
+     * Defaults to `globalThis.fetch`.
+     */
+    fetch?: typeof fetch;
+    /**
+     * Abort the token fetch if no response is received before this many
+     * milliseconds.
+     */
+    timeoutMs?: number;
+    /**
+     * Human-readable operation label used in token-fetch diagnostics.
+     * @default "ClientCredentialsProvider"
+     */
+    diagnosticsLabel?: string;
+    /**
+     * Extra values to redact from diagnostic text. `clientId` and `clientSecret`
+     * are always redacted automatically.
+     */
+    redactValues?: string[];
+}
+/**
+ * OAuth `client_credentials` provider for machine-to-machine MCP authentication.
+ *
+ * Implements {@linkcode OAuthClientProvider} from the official MCP TypeScript
+ * SDK so it can be passed directly to `httpServer()` / `sseServer()` as
+ * `authProvider`.
+ *
+ * Unlike user-interactive OAuth flows, this provider proactively fetches a
+ * bearer token via the `client_credentials` grant before any request is made,
+ * so the MCP transport's `Authorization` header is always populated.
+ * Token expiry is tracked and a new token is fetched automatically before the
+ * old one expires (controlled by {@linkcode ClientCredentialsOptions.expiryBufferSeconds}).
+ *
+ * @example
+ * ```ts
+ * import { serviceAccountServer } from "@cuylabs/agent-core/mcp";
+ *
+ * const mcpManager = createMCPManager({
+ *   myServer: serviceAccountServer("https://my-mcp.example.com", {
+ *     clientId: "my-service-account",
+ *     clientSecret: process.env.CLIENT_SECRET!,
+ *     tokenUrl: "https://auth.example.com/oauth/token",
+ *     scope: "mcp:read",
+ *   }),
+ * });
+ * ```
+ *
+ * @example Static API key (no OAuth needed — use headers instead)
+ * ```ts
+ * httpServer("https://my-mcp.example.com", {
+ *   headers: { Authorization: `Bearer ${process.env.API_KEY}` },
+ * });
+ * ```
+ */
+export declare class ClientCredentialsProvider implements OAuthClientProvider {
+    private _tokens?;
+    private _expiresAt?;
+    private readonly _options;
+    private readonly _tokenFetch;
+    private readonly _redactValues;
+    constructor(options: ClientCredentialsOptions);
+    get redirectUrl(): undefined;
+    get clientMetadata(): OAuthClientMetadata;
+    clientInformation(): OAuthClientInformation;
+    saveClientInformation(): void;
+    tokens(): Promise<OAuthTokens | undefined>;
+    saveTokens(tokens: OAuthTokens): Promise<void>;
+    redirectToAuthorization(_authorizationUrl: URL): never;
+    saveCodeVerifier(): void;
+    codeVerifier(): never;
+    prepareTokenRequest(scope?: string): URLSearchParams;
+    addClientAuthentication(headers: Headers): void;
+    invalidateCredentials(scope: "all" | "client" | "tokens" | "verifier"): void;
+    private _fetchTokens;
+}
+//# sourceMappingURL=auth.d.ts.map

package/dist/mcp/auth.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"auth.d.ts","sourceRoot":"","sources":["../../src/mcp/auth.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,0CAA0C,CAAC;AACpF,OAAO,KAAK,EACV,sBAAsB,EACtB,mBAAmB,EACnB,WAAW,EACZ,MAAM,0CAA0C,CAAC;AAkDlD;;GAEG;AACH,MAAM,WAAW,wBAAwB;IACvC;;OAEG;IACH,QAAQ,EAAE,MAAM,CAAC;IAEjB;;OAEG;IACH,YAAY,EAAE,MAAM,CAAC;IAErB;;;;;;;OAOG;IACH,QAAQ,EAAE,MAAM,CAAC;IAEjB;;OAEG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;IAEf;;;OAGG;IACH,mBAAmB,CAAC,EAAE,MAAM,CAAC;IAE7B;;;OAGG;IACH,KAAK,CAAC,EAAE,OAAO,KAAK,CAAC;IAErB;;;OAGG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;IAEnB;;;OAGG;IACH,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAE1B;;;OAGG;IACH,YAAY,CAAC,EAAE,MAAM,EAAE,CAAC;CACzB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AACH,qBAAa,yBAA0B,YAAW,mBAAmB;IACnE,OAAO,CAAC,OAAO,CAAC,CAAc;IAC9B,OAAO,CAAC,UAAU,CAAC,CAAS;IAC5B,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAA2B;IACpD,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAe;IAC3C,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAW;gBAE7B,OAAO,EAAE,wBAAwB;IAiB7C,IAAI,WAAW,IAAI,SAAS,CAG3B;IAED,IAAI,cAAc,IAAI,mBAAmB,CAOxC;IAED,iBAAiB,IAAI,sBAAsB;IAO3C,qBAAqB,IAAI,IAAI;IAIvB,MAAM,IAAI,OAAO,CAAC,WAAW,GAAG,SAAS,CAAC;IAc1C,UAAU,CAAC,MAAM,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC;IAQpD,uBAAuB,CAAC,iBAAiB,EAAE,GAAG,GAAG,KAAK;IAUtD,gBAAgB,IAAI,IAAI;IAIxB,YAAY,IAAI,KAAK;IAMrB,mBAAmB,CAAC,KAAK,CAAC,EAAE,MAAM,GAAG,eAAe;IAOpD,uBAAuB,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI;IAO/C,qBAAqB,CAAC,KAAK,EAAE,KAAK,GAAG,QAAQ,GAAG,QAAQ,GAAG,UAAU,GAAG,IAAI;YAS9D,YAAY;CA+B3B"}

package/dist/mcp/diagnostics.d.ts

@@ -0,0 +1,23 @@
+export interface DiagnosticFetchOptions {
+    /**
+     * Base fetch implementation. Defaults to `globalThis.fetch`.
+     */
+    fetch?: typeof fetch;
+    /**
+     * Human-readable operation label used in wrapped network errors.
+     */
+    label?: string;
+    /**
+     * Abort the fetch if no response is received before this many milliseconds.
+     */
+    timeoutMs?: number;
+    /**
+     * Values to redact from diagnostic text.
+     */
+    redactValues?: string[];
+}
+export declare function createDiagnosticFetch(options?: DiagnosticFetchOptions): typeof fetch;
+export declare function enrichMcpFetchError(message: string, error: unknown, redactValues?: string[]): Error;
+export declare function redactSensitiveText(text: string, values: string[]): string;
+export declare function readDiagnosticBody(response: Response, maxChars?: number): Promise<string>;
+//# sourceMappingURL=diagnostics.d.ts.map

package/dist/mcp/diagnostics.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"diagnostics.d.ts","sourceRoot":"","sources":["../../src/mcp/diagnostics.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,sBAAsB;IACrC;;OAEG;IACH,KAAK,CAAC,EAAE,OAAO,KAAK,CAAC;IACrB;;OAEG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;IACf;;OAEG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;;OAEG;IACH,YAAY,CAAC,EAAE,MAAM,EAAE,CAAC;CACzB;AAED,wBAAgB,qBAAqB,CACnC,OAAO,GAAE,sBAA2B,GACnC,OAAO,KAAK,CA6Cd;AAED,wBAAgB,mBAAmB,CACjC,OAAO,EAAE,MAAM,EACf,KAAK,EAAE,OAAO,EACd,YAAY,GAAE,MAAM,EAAO,GAC1B,KAAK,CASP;AAED,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,GAAG,MAAM,CAO1E;AAED,wBAAsB,kBAAkB,CACtC,QAAQ,EAAE,QAAQ,EAClB,QAAQ,SAAM,GACb,OAAO,CAAC,MAAM,CAAC,CAGjB"}

package/dist/mcp/factories.d.ts

@@ -0,0 +1,47 @@
+import type { ClientCredentialsOptions } from "./auth.js";
+import type { MCPConfig, MCPManager, MCPServerConfig, RemoteTransportConfig, StdioTransportConfig } from "./types.js";
+export type ServiceAccountServerOptions = Omit<RemoteTransportConfig, "transport" | "url" | "authProvider"> & Pick<MCPServerConfig, "capabilities" | "enabled" | "name" | "onUncaughtError" | "timeout">;
+export type ServiceAccountServerConfig = RemoteTransportConfig & Pick<MCPServerConfig, "capabilities" | "enabled" | "name" | "onUncaughtError" | "timeout">;
+/**
+ * Create an MCP manager for connecting to multiple MCP servers.
+ */
+export declare function createMCPManager(config: MCPConfig): MCPManager;
+/**
+ * Helper to create a stdio server config.
+ */
+export declare function stdioServer(command: string, args?: string[], options?: Omit<StdioTransportConfig, "transport" | "command" | "args">): StdioTransportConfig;
+/**
+ * Helper to create an HTTP server config.
+ */
+export declare function httpServer(url: string, options?: Omit<RemoteTransportConfig, "transport" | "url">): RemoteTransportConfig;
+/**
+ * Helper to create an SSE server config.
+ */
+export declare function sseServer(url: string, options?: Omit<RemoteTransportConfig, "transport" | "url">): RemoteTransportConfig;
+/**
+ * Helper to create an HTTP server config authenticated with the OAuth
+ * `client_credentials` grant (machine-to-machine / service account).
+ *
+ * This uses agent-core's convenience `ClientCredentialsProvider`, which
+ * proactively fetches a bearer token from an explicit token endpoint before
+ * the first request. The official MCP SDK transport still owns the underlying
+ * auth orchestration and transport behavior.
+ *
+ * @example
+ * ```ts
+ * createMCPManager({
+ *   myServer: serviceAccountServer(
+ *     "https://my-mcp.example.com",
+ *     {
+ *       clientId: "svc-account-id",
+ *       clientSecret: process.env.CLIENT_SECRET!,
+ *       tokenUrl: "https://auth.example.com/oauth/token",
+ *       scope: "mcp:read",
+ *     }
+ *   ),
+ * });
+ * ```
+ */
+export declare function serviceAccountServer(url: string, credentials: ClientCredentialsOptions, options?: ServiceAccountServerOptions): ServiceAccountServerConfig;
+export type { ClientCredentialsOptions };
+//# sourceMappingURL=factories.d.ts.map

package/dist/mcp/factories.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"factories.d.ts","sourceRoot":"","sources":["../../src/mcp/factories.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,wBAAwB,EAAE,MAAM,WAAW,CAAC;AAE1D,OAAO,KAAK,EACV,SAAS,EACT,UAAU,EACV,eAAe,EACf,qBAAqB,EACrB,oBAAoB,EACrB,MAAM,YAAY,CAAC;AAEpB,MAAM,MAAM,2BAA2B,GAAG,IAAI,CAC5C,qBAAqB,EACrB,WAAW,GAAG,KAAK,GAAG,cAAc,CACrC,GACC,IAAI,CACF,eAAe,EACf,cAAc,GAAG,SAAS,GAAG,MAAM,GAAG,iBAAiB,GAAG,SAAS,CACpE,CAAC;AAEJ,MAAM,MAAM,0BAA0B,GAAG,qBAAqB,GAC5D,IAAI,CACF,eAAe,EACf,cAAc,GAAG,SAAS,GAAG,MAAM,GAAG,iBAAiB,GAAG,SAAS,CACpE,CAAC;AAEJ;;GAEG;AACH,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,SAAS,GAAG,UAAU,CAE9D;AAED;;GAEG;AACH,wBAAgB,WAAW,CACzB,OAAO,EAAE,MAAM,EACf,IAAI,CAAC,EAAE,MAAM,EAAE,EACf,OAAO,CAAC,EAAE,IAAI,CAAC,oBAAoB,EAAE,WAAW,GAAG,SAAS,GAAG,MAAM,CAAC,GACrE,oBAAoB,CAOtB;AAED;;GAEG;AACH,wBAAgB,UAAU,CACxB,GAAG,EAAE,MAAM,EACX,OAAO,CAAC,EAAE,IAAI,CAAC,qBAAqB,EAAE,WAAW,GAAG,KAAK,CAAC,GACzD,qBAAqB,CAMvB;AAED;;GAEG;AACH,wBAAgB,SAAS,CACvB,GAAG,EAAE,MAAM,EACX,OAAO,CAAC,EAAE,IAAI,CAAC,qBAAqB,EAAE,WAAW,GAAG,KAAK,CAAC,GACzD,qBAAqB,CAMvB;AAED;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAgB,oBAAoB,CAClC,GAAG,EAAE,MAAM,EACX,WAAW,EAAE,wBAAwB,EACrC,OAAO,CAAC,EAAE,2BAA2B,GACpC,0BAA0B,CAmB5B;AAED,YAAY,EAAE,wBAAwB,EAAE,CAAC"}