agentfootprint 7.13.0 → 7.15.0

package/dist/esm/lib/mcp/types.d.ts

@@ -21,6 +21,7 @@
  *          agent run, so it emits nothing at all.
  */
 import type { Tool } from '../../core/tools.js';
+import type { CredentialProvider } from '../../identity/types.js';
 /**
  * `stdio` transport — spawns a local subprocess and speaks MCP over
  * its stdin/stdout. Best for development, single-user scenarios, and
@@ -54,7 +55,50 @@ export interface McpHttpTransport {
     /** Optional auth headers (e.g., `Authorization: Bearer ...`). */
     readonly headers?: Readonly<Record<string, string>>;
 }
-export type McpTransport = McpStdioTransport | McpHttpTransport;
+/**
+ * `gateway` transport — MCP over Streamable HTTP, with the auth headers vended
+ * **per request** by a {@link CredentialProvider} instead of fixed at connect
+ * time.
+ *
+ * The difference from `http` is entirely about time. `http` takes the headers
+ * you hand it once and reuses them for the life of the connection, which is
+ * exactly right for a static API key and exactly wrong for a token with an
+ * expiry: a long-lived agent outlives its bearer token, and the failure is a
+ * burst of 401s an hour into a session that worked fine when you tested it.
+ * This transport asks the provider on every request, so a rotated, refreshed
+ * or newly-consented token is simply the one used next.
+ *
+ * **The token is never stored by this transport.** It is vended, applied to one
+ * outgoing request, and dropped — it is not cached between requests, not held
+ * on the transport object, and not written to any event, error message or log.
+ * Build it with `gatewayTransport(...)` rather than by hand.
+ */
+export interface McpGatewayTransport {
+    readonly transport: 'gateway';
+    /** The MCP endpoint URL. */
+    readonly url: string;
+    /**
+     * Who vends the token. Anything satisfying the `CredentialProvider` port —
+     * `agentCoreIdentity()` for a managed token vault, `staticTokens()` in dev.
+     */
+    readonly credentials: CredentialProvider;
+    /** The downstream service id the provider understands, e.g. `'gateway'`. */
+    readonly service: string;
+    /** OAuth scopes to request, when the provider uses them. */
+    readonly scopes?: readonly string[];
+    /** `machine` (2-legged, the default) or `user` (3-legged, on behalf of a user). */
+    readonly mode?: 'machine' | 'user';
+    /**
+     * Extra headers sent alongside the vended ones (a tenant id, a correlation
+     * id). Applied FIRST, so a vended auth header always wins — a static header
+     * can never quietly shadow the credential.
+     *
+     * Put no secrets here: these are held for the life of the transport, which is
+     * the property the vended ones exist to avoid.
+     */
+    readonly headers?: Readonly<Record<string, string>>;
+}
+export type McpTransport = McpStdioTransport | McpHttpTransport | McpGatewayTransport;
 export interface McpClientOptions {
     /**
      * Logical name for observability + tool-call routing. Surfaces in

package/dist/esm/memory/store/types.d.ts

@@ -85,6 +85,21 @@ export interface SearchOptions {
      * they're doing.
      */
     readonly embedderId?: string;
+    /**
+     * The natural-language form of the same query, when the caller has it.
+     *
+     * `search()` takes a VECTOR because the reference backends rank locally
+     * by cosine. Several managed stores do not work that way: they embed
+     * and rank **server-side** and their retrieval API takes text, so a
+     * vector is the one thing they cannot use. Those adapters read this
+     * field, and say so by name when it is missing rather than quietly
+     * ranking nothing.
+     *
+     * Stores that rank locally IGNORE it — the vector stays authoritative
+     * and results are unchanged whether you pass it or not. Supply both
+     * whenever you have both, and any store can serve the query.
+     */
+    readonly text?: string;
 }
 /**
  * A `MemoryEntry` annotated with its similarity score. Returned by
@@ -218,6 +233,13 @@ export interface MemoryStore {
      *     Fine for dev / tests. Production needs a real vector DB.
      *   - **pgvector**: `ORDER BY embedding <=> query LIMIT k`.
      *   - **Pinecone / Qdrant / Weaviate**: native vector query API.
+     *
+     * **Server-side stores.** Some backends embed and rank on their own
+     * side and their retrieval API takes TEXT, not a vector. Those
+     * adapters read `options.text` (see {@link SearchOptions.text}) and
+     * refuse by name when it is absent — a vector is genuinely unusable
+     * to them, and returning an empty result would look like "no matches"
+     * instead of "wrong query form".
      */
     search?<T = unknown>(identity: MemoryIdentity, query: readonly number[], options?: SearchOptions): Promise<readonly ScoredEntry<T>[]>;
 }

package/dist/esm/memory-providers.d.ts

@@ -33,5 +33,5 @@
  *   import { RedisStore, AgentCoreStore } from 'agentfootprint/memory-providers';
  */
 export { RedisStore, type RedisStoreOptions, type RedisLikeClient, type RedisLikePipeline, } from './adapters/memory/redis.js';
-export { AgentCoreStore, type AgentCoreStoreOptions, type AgentCoreLikeClient, } from './adapters/memory/agentcore.js';
+export { AgentCoreStore, type AgentCoreStoreOptions, type AgentCoreLikeClient, type AgentCoreEvent, type AgentCoreMemoryRecord, } from './adapters/memory/agentcore.js';
 export { BedrockAgentMemory, type BedrockAgentMemoryOptions, type BedrockAgentMemoryLikeClient, type BedrockAgentSummary, } from './adapters/memory/bedrockAgentMemory.js';

package/dist/esm/memory-providers.js.map

@@ -1 +1 @@
-{"version":3,"file":"memory-providers.js","sourceRoot":"","sources":["../../src/memory-providers.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AAEH,sEAAsE;AACtE,sEAAsE;AACtE,wDAAwD;AACxD,OAAO,EACL,UAAU,GAIX,MAAM,4BAA4B,CAAC;AAEpC,OAAO,EACL,cAAc,GAGf,MAAM,gCAAgC,CAAC;AAExC,8EAA8E;AAC9E,yEAAyE;AACzE,OAAO,EACL,kBAAkB,GAInB,MAAM,yCAAyC,CAAC"}
+{"version":3,"file":"memory-providers.js","sourceRoot":"","sources":["../../src/memory-providers.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AAEH,sEAAsE;AACtE,sEAAsE;AACtE,wDAAwD;AACxD,OAAO,EACL,UAAU,GAIX,MAAM,4BAA4B,CAAC;AAEpC,OAAO,EACL,cAAc,GAKf,MAAM,gCAAgC,CAAC;AAExC,8EAA8E;AAC9E,yEAAyE;AACzE,OAAO,EACL,kBAAkB,GAInB,MAAM,yCAAyC,CAAC"}

package/dist/esm/security/index.d.ts

@@ -10,7 +10,15 @@
  * Today's surface is small and data-driven on purpose: one role
  * allowlist primitive that satisfies BOTH the v2.4 `PermissionChecker`
  * interface AND a sync `isAllowed(toolId)` predicate for use with
- * `gatedTools` from `agentfootprint/tool-providers`.
+ * `gatedTools` from `agentfootprint/tool-providers` — plus
+ * `agentCorePolicy()`, the same port answered by a remote policy store.
+ *
+ * A local allowlist and a remote policy engine differ in one way that
+ * matters here: the local one can answer synchronously, so it doubles
+ * as a `gatedTools` predicate; a remote one cannot, so it plugs in ONLY
+ * as `permissionChecker`. That is not a limitation of either — the gate
+ * decides what the model is shown, the checker decides what actually
+ * runs, and they compose without knowing about each other.
  *
  * Future additions (capability gating, gate_open flows, audit logs)
  * land here without expanding the public root barrel.
@@ -41,4 +49,5 @@ export type { PolicyHaltContext } from './PolicyHaltError.js';
 export { extractSequence, SYNTHETIC_DENY_PREFIX } from './extractSequence.js';
 export type { ExtractSequenceOptions } from './extractSequence.js';
 export { redactThinkingBlocks, REDACTED_PLACEHOLDER } from './thinkingRedaction.js';
+export { agentCorePolicy, type AgentCorePolicyOptions, type AgentCorePolicyClientLike, type AgentCorePolicyEvaluation, type AgentCorePolicyUnavailable, type BedrockAgentCorePolicySdkModule, } from '../adapters/security/agentcore.js';
 export type { PermissionChecker, PermissionRequest, PermissionDecision, ToolCallEntry, ToolResultContent, } from '../adapters/types.js';

package/dist/esm/security/index.js

@@ -10,7 +10,15 @@
  * Today's surface is small and data-driven on purpose: one role
  * allowlist primitive that satisfies BOTH the v2.4 `PermissionChecker`
  * interface AND a sync `isAllowed(toolId)` predicate for use with
- * `gatedTools` from `agentfootprint/tool-providers`.
+ * `gatedTools` from `agentfootprint/tool-providers` — plus
+ * `agentCorePolicy()`, the same port answered by a remote policy store.
+ *
+ * A local allowlist and a remote policy engine differ in one way that
+ * matters here: the local one can answer synchronously, so it doubles
+ * as a `gatedTools` predicate; a remote one cannot, so it plugs in ONLY
+ * as `permissionChecker`. That is not a limitation of either — the gate
+ * decides what the model is shown, the checker decides what actually
+ * runs, and they compose without knowing about each other.
  *
  * Future additions (capability gating, gate_open flows, audit logs)
  * land here without expanding the public root barrel.
@@ -38,4 +46,9 @@ export { PermissionPolicy } from './PermissionPolicy.js';
 export { PolicyHaltError } from './PolicyHaltError.js';
 export { extractSequence, SYNTHETIC_DENY_PREFIX } from './extractSequence.js';
 export { redactThinkingBlocks, REDACTED_PLACEHOLDER } from './thinkingRedaction.js';
+// A remote policy engine behind the same port. Lazy peer-dep: importing this
+// barrel loads no AWS SDK — only constructing the checker and letting it
+// evaluate does. Same home as `PermissionPolicy` because it is the same job,
+// just asked of somebody else.
+export { agentCorePolicy, } from '../adapters/security/agentcore.js';
 //# sourceMappingURL=index.js.map

package/dist/esm/security/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/security/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AAEH,OAAO,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAC;AAGzD,OAAO,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAC;AAGvD,OAAO,EAAE,eAAe,EAAE,qBAAqB,EAAE,MAAM,sBAAsB,CAAC;AAG9E,OAAO,EAAE,oBAAoB,EAAE,oBAAoB,EAAE,MAAM,wBAAwB,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/security/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2CG;AAEH,OAAO,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAC;AAGzD,OAAO,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAC;AAGvD,OAAO,EAAE,eAAe,EAAE,qBAAqB,EAAE,MAAM,sBAAsB,CAAC;AAG9E,OAAO,EAAE,oBAAoB,EAAE,oBAAoB,EAAE,MAAM,wBAAwB,CAAC;AAEpF,6EAA6E;AAC7E,yEAAyE;AACzE,6EAA6E;AAC7E,+BAA+B;AAC/B,OAAO,EACL,eAAe,GAMhB,MAAM,mCAAmC,CAAC"}

package/dist/esm/tool-providers/index.d.ts

@@ -12,6 +12,10 @@
  * 2. Tool sources (re-exported from existing modules)
  *    - `mcpClient(opts)` — connect to an MCP server (real)
  *    - `mockMcpClient({ tools })` — in-memory MCP source for dev / tests
+ *    - `gatewayTransport({ url, credentials, service })` — an MCP
+ *      transport whose auth headers are vended PER REQUEST by a
+ *      `CredentialProvider`, for endpoints behind a token with an
+ *      expiry. The token is used once and never stored.
  *
  * 3. Tool sink — the other direction
  *    - `mcpServe(tools, opts)` — expose your own `Tool[]` AS an MCP
@@ -43,5 +47,5 @@ export { staticTools } from './staticTools.js';
 export { gatedTools } from './gatedTools.js';
 export { skillScopedTools } from './skillScopedTools.js';
 export type { ToolProvider, ToolDispatchContext, ToolGatePredicate } from './types.js';
-export { mcpClient, mcpServe, mockMcpClient } from '../lib/mcp/index.js';
-export type { McpClient, McpClientOptions, McpSdkClient, McpTransport, McpStdioTransport, McpHttpTransport, MockMcpClientOptions, MockMcpTool, McpServeOptions, McpServeHandle, McpServeTransport, McpStdioServeTransport, McpHttpServeTransport, McpSdkServer, } from '../lib/mcp/index.js';
+export { mcpClient, mcpServe, mockMcpClient, gatewayTransport, GatewayAuthorizationRequiredError, } from '../lib/mcp/index.js';
+export type { GatewayTransportOptions, McpClient, McpClientOptions, McpSdkClient, McpTransport, McpStdioTransport, McpHttpTransport, McpGatewayTransport, MockMcpClientOptions, MockMcpTool, McpServeOptions, McpServeHandle, McpServeTransport, McpStdioServeTransport, McpHttpServeTransport, McpSdkServer, } from '../lib/mcp/index.js';

package/dist/esm/tool-providers/index.js

@@ -12,6 +12,10 @@
  * 2. Tool sources (re-exported from existing modules)
  *    - `mcpClient(opts)` — connect to an MCP server (real)
  *    - `mockMcpClient({ tools })` — in-memory MCP source for dev / tests
+ *    - `gatewayTransport({ url, credentials, service })` — an MCP
+ *      transport whose auth headers are vended PER REQUEST by a
+ *      `CredentialProvider`, for endpoints behind a token with an
+ *      expiry. The token is used once and never stored.
  *
  * 3. Tool sink — the other direction
  *    - `mcpServe(tools, opts)` — expose your own `Tool[]` AS an MCP
@@ -45,5 +49,5 @@ export { skillScopedTools } from './skillScopedTools.js';
 // Re-export tool sources from the MCP module so consumers find them in
 // one place. This subpath is the ONLY place `mcpClient` is public — the
 // top-level barrel does not re-export it.
-export { mcpClient, mcpServe, mockMcpClient } from '../lib/mcp/index.js';
+export { mcpClient, mcpServe, mockMcpClient, gatewayTransport, GatewayAuthorizationRequiredError, } from '../lib/mcp/index.js';
 //# sourceMappingURL=index.js.map

package/dist/esm/tool-providers/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/tool-providers/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwCG;AAEH,OAAO,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAC/C,OAAO,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAC7C,OAAO,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAC;AAGzD,uEAAuE;AACvE,wEAAwE;AACxE,0CAA0C;AAC1C,OAAO,EAAE,SAAS,EAAE,QAAQ,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/tool-providers/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4CG;AAEH,OAAO,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAC/C,OAAO,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAC7C,OAAO,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAC;AAGzD,uEAAuE;AACvE,wEAAwE;AACxE,0CAA0C;AAC1C,OAAO,EACL,SAAS,EACT,QAAQ,EACR,aAAa,EACb,gBAAgB,EAChB,iCAAiC,GAClC,MAAM,qBAAqB,CAAC"}

package/dist/hosting/envelope.js

@@ -0,0 +1,54 @@
+"use strict";
+/**
+ * hosting/envelope — pack a conversation for storage, and refuse to unpack one
+ * you cannot read.
+ *
+ * Two functions and one rule: **an unknown format is refused by name, never
+ * guessed at.** A store outlives the code that wrote to it. Somebody will
+ * deploy a newer runtime, it will write a newer format, and an older instance
+ * still running will read it. The only honest thing that older instance can do
+ * is say which format it found, which ones it knows, and stop — because
+ * "restore what I can and hope" means an agent answering from a conversation
+ * that is missing whatever the older reader did not understand.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.readEnvelope = exports.toEnvelope = void 0;
+const runCheckpoint_js_1 = require("../core/runCheckpoint.js");
+/** Every format this runtime can read. Add, never redefine. */
+const KNOWN_FORMATS = ['conversation-v1'];
+/**
+ * Pack a conversation checkpoint for storage.
+ *
+ * @example
+ *   const conversation = agent.checkpoint();
+ *   if (conversation) await sessions.persist(sessionId, toEnvelope(conversation));
+ */
+function toEnvelope(checkpoint) {
+    return { format: 'conversation-v1', data: checkpoint, savedAt: Date.now() };
+}
+exports.toEnvelope = toEnvelope;
+/**
+ * Unpack a stored envelope back into a conversation checkpoint.
+ *
+ * Takes `unknown` on purpose: what comes back from a store is bytes somebody
+ * else wrote, in a format this runtime may not know, and typing the parameter
+ * as the happy shape would be assuming the very thing that needs checking.
+ *
+ * @throws TypeError naming the format when it is one this runtime cannot read,
+ *   and naming the missing field when the conversation inside is malformed.
+ */
+function readEnvelope(envelope) {
+    if (!envelope || typeof envelope !== 'object') {
+        throw new TypeError(`[hosting] stored session is not an envelope (got ${envelope === null ? 'null' : typeof envelope}). ` + `Expected { format, data, savedAt } as written by toEnvelope().`);
+    }
+    const found = envelope.format;
+    if (typeof found !== 'string' || !KNOWN_FORMATS.includes(found)) {
+        throw new TypeError(`[hosting] unknown checkpoint format '${String(found)}'. ` +
+            `This runtime reads: ${KNOWN_FORMATS.join(', ')}. ` +
+            `Refusing rather than restoring a conversation it cannot read — a newer envelope ` +
+            `needs a runtime that knows the format that wrote it.`);
+    }
+    return (0, runCheckpoint_js_1.validateCheckpoint)(envelope.data);
+}
+exports.readEnvelope = readEnvelope;
+//# sourceMappingURL=envelope.js.map

package/dist/hosting/envelope.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"envelope.js","sourceRoot":"","sources":["../../src/hosting/envelope.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;GAWG;;;AAEH,+DAAuF;AAGvF,+DAA+D;AAC/D,MAAM,aAAa,GAAsB,CAAC,iBAAiB,CAAC,CAAC;AAE7D;;;;;;GAMG;AACH,SAAgB,UAAU,CAAC,UAA8B;IACvD,OAAO,EAAE,MAAM,EAAE,iBAAiB,EAAE,IAAI,EAAE,UAAU,EAAE,OAAO,EAAE,IAAI,CAAC,GAAG,EAAE,EAAE,CAAC;AAC9E,CAAC;AAFD,gCAEC;AAED;;;;;;;;;GASG;AACH,SAAgB,YAAY,CAAC,QAAiB;IAC5C,IAAI,CAAC,QAAQ,IAAI,OAAO,QAAQ,KAAK,QAAQ,EAAE,CAAC;QAC9C,MAAM,IAAI,SAAS,CACjB,oDACE,QAAQ,KAAK,IAAI,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,OAAO,QACtC,KAAK,GAAG,gEAAgE,CACzE,CAAC;IACJ,CAAC;IACD,MAAM,KAAK,GAAI,QAAwC,CAAC,MAAM,CAAC;IAC/D,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,CAAC,aAAa,CAAC,QAAQ,CAAC,KAAK,CAAC,EAAE,CAAC;QAChE,MAAM,IAAI,SAAS,CACjB,wCAAwC,MAAM,CAAC,KAAK,CAAC,KAAK;YACxD,uBAAuB,aAAa,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI;YACnD,kFAAkF;YAClF,sDAAsD,CACzD,CAAC;IACJ,CAAC;IACD,OAAO,IAAA,qCAAkB,EAAE,QAA+B,CAAC,IAAI,CAAC,CAAC;AACnE,CAAC;AAlBD,oCAkBC"}

package/dist/hosting/errors.js

@@ -0,0 +1,126 @@
+"use strict";
+/**
+ * hosting/errors — the refusals, authored once so every adapter refuses in the
+ * same words.
+ *
+ * A refusal that varies by adapter is a refusal nobody can write a test or a
+ * runbook against. These three carry a stable `code`, name WHO refused, and say
+ * what the caller should do instead. Adapters map the codes onto whatever their
+ * transport uses to say "no" — that mapping is the adapter's business and lives
+ * in the adapter, never here.
+ *
+ * `requireCapability` is the fourth refusal and the only one that is a
+ * programming mistake rather than a runtime condition, so it throws a plain
+ * `Error`: nothing branches on "I forgot to feature-detect", it just needs to
+ * say so loudly and name the adapter it is talking about.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.requireCapability = exports.PauseNotCarriedError = exports.ConcurrentRunError = exports.HostClosedError = void 0;
+/**
+ * Thrown when a request arrives at a host that is shutting down or shut down.
+ *
+ * `close()` lets in-flight work finish and refuses everything after it; this is
+ * what "everything after it" receives.
+ */
+class HostClosedError extends Error {
+    code = 'ERR_HOST_CLOSED';
+    /** Which adapter refused. */
+    hostName;
+    constructor(hostName) {
+        super(`[hosting] the '${hostName}' host is closed and is not accepting new requests. ` +
+            `In-flight requests were allowed to finish; this one arrived after close() was called. ` +
+            `Serve again on a fresh host to accept new work.`);
+        this.name = 'HostClosedError';
+        this.hostName = hostName;
+    }
+}
+exports.HostClosedError = HostClosedError;
+/**
+ * Thrown when a request arrives for a session that already has a run in flight
+ * and the policy is `'reject'`.
+ *
+ * The refusal is about the SESSION, not about load: two turns of one
+ * conversation racing each other would each answer from the state the other is
+ * about to replace. A request for any OTHER session is never refused — it
+ * simply waits.
+ */
+class ConcurrentRunError extends Error {
+    code = 'ERR_CONCURRENT_RUN';
+    /** The session that already has a run going. */
+    sessionId;
+    /** The run that is already going, when it has announced itself. */
+    activeRunId;
+    constructor(sessionId, activeRunId) {
+        super(`[hosting] session '${sessionId}' already has a run in flight` +
+            (activeRunId ? ` (run '${activeRunId}')` : '') +
+            `. Refusing rather than running two turns of one conversation at once — ` +
+            `they would each answer from state the other is about to replace. ` +
+            `Wait for the active run, or build the standing agent with ` +
+            `onConcurrentInvoke: 'enqueue' to queue this turn behind it instead.`);
+        this.name = 'ConcurrentRunError';
+        this.sessionId = sessionId;
+        if (activeRunId !== undefined)
+            this.activeRunId = activeRunId;
+    }
+}
+exports.ConcurrentRunError = ConcurrentRunError;
+/**
+ * Raised when a run paused to ask a person something and the reply cannot carry
+ * a pause.
+ *
+ * **The run did not fail.** A pause is unfinished work: the agent stopped to ask
+ * and is waiting for an answer. What cannot happen here is storing it — the
+ * `'conversation-v1'` envelope holds a conversation, and a paused run is a
+ * conversation plus an engine checkpoint. So nothing is written, and the
+ * session keeps exactly the conversation it had before this request.
+ */
+class PauseNotCarriedError extends Error {
+    code = 'ERR_PAUSE_NOT_CARRIED';
+    /** The tool that asked, when the run recorded which one it was. */
+    toolName;
+    /** The session whose stored conversation was left untouched. */
+    sessionId;
+    constructor(toolName, sessionId) {
+        super(`[hosting] the run paused to ask a person about ` +
+            (toolName ? `'${toolName}'` : 'a tool') +
+            ` and this reply cannot carry a pause. ` +
+            `The run did not fail — it is unfinished, waiting on an answer. ` +
+            `Nothing was written: ` +
+            (sessionId ? `session '${sessionId}'` : 'the session') +
+            ` still holds the conversation it held before this request. ` +
+            `The 'conversation-v1' envelope stores a conversation; a paused run is a ` +
+            `conversation plus an engine checkpoint, and storing half of it would be worse ` +
+            `than storing none. Carry the pause yourself with agent.run() / agent.resume().`);
+        this.name = 'PauseNotCarriedError';
+        if (toolName !== undefined)
+            this.toolName = toolName;
+        if (sessionId !== undefined)
+            this.sessionId = sessionId;
+    }
+}
+exports.PauseNotCarriedError = PauseNotCarriedError;
+/**
+ * Assert that a host can do something, and throw a corrective error naming the
+ * adapter when it cannot.
+ *
+ * This is the feature-detection law with teeth: capabilities are read, never
+ * assumed, and asking for one that is absent tells you which adapter you are
+ * actually holding rather than failing quietly somewhere downstream.
+ *
+ * @example
+ *   requireCapability(host, 'streaming'); // throws unless this host streams
+ *
+ *   // or branch instead of insisting:
+ *   if (host.capabilities.includes('streaming')) { ... }
+ */
+function requireCapability(host, capability) {
+    if (host.capabilities.includes(capability))
+        return;
+    const has = host.capabilities.length > 0 ? host.capabilities.join(', ') : 'none';
+    throw new Error(`[hosting] the '${host.name}' host does not support '${capability}'. ` +
+        `It reports: ${has}. Feature-detect with ` +
+        `host.capabilities.includes('${capability}') and fall back, or serve on a host ` +
+        `that has it — capabilities are read from the adapter, never assumed from its name.`);
+}
+exports.requireCapability = requireCapability;
+//# sourceMappingURL=errors.js.map

package/dist/hosting/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../../src/hosting/errors.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;GAcG;;;AAIH;;;;;GAKG;AACH,MAAa,eAAgB,SAAQ,KAAK;IAC/B,IAAI,GAAG,iBAA0B,CAAC;IAC3C,6BAA6B;IACpB,QAAQ,CAAS;IAE1B,YAAY,QAAgB;QAC1B,KAAK,CACH,kBAAkB,QAAQ,sDAAsD;YAC9E,wFAAwF;YACxF,iDAAiD,CACpD,CAAC;QACF,IAAI,CAAC,IAAI,GAAG,iBAAiB,CAAC;QAC9B,IAAI,CAAC,QAAQ,GAAG,QAAQ,CAAC;IAC3B,CAAC;CACF;AAdD,0CAcC;AAED;;;;;;;;GAQG;AACH,MAAa,kBAAmB,SAAQ,KAAK;IAClC,IAAI,GAAG,oBAA6B,CAAC;IAC9C,gDAAgD;IACvC,SAAS,CAAS;IAC3B,mEAAmE;IAC1D,WAAW,CAAU;IAE9B,YAAY,SAAiB,EAAE,WAAoB;QACjD,KAAK,CACH,sBAAsB,SAAS,+BAA+B;YAC5D,CAAC,WAAW,CAAC,CAAC,CAAC,UAAU,WAAW,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC;YAC9C,yEAAyE;YACzE,mEAAmE;YACnE,4DAA4D;YAC5D,qEAAqE,CACxE,CAAC;QACF,IAAI,CAAC,IAAI,GAAG,oBAAoB,CAAC;QACjC,IAAI,CAAC,SAAS,GAAG,SAAS,CAAC;QAC3B,IAAI,WAAW,KAAK,SAAS;YAAE,IAAI,CAAC,WAAW,GAAG,WAAW,CAAC;IAChE,CAAC;CACF;AApBD,gDAoBC;AAED;;;;;;;;;GASG;AACH,MAAa,oBAAqB,SAAQ,KAAK;IACpC,IAAI,GAAG,uBAAgC,CAAC;IACjD,mEAAmE;IAC1D,QAAQ,CAAU;IAC3B,gEAAgE;IACvD,SAAS,CAAU;IAE5B,YAAY,QAAiB,EAAE,SAAkB;QAC/C,KAAK,CACH,iDAAiD;YAC/C,CAAC,QAAQ,CAAC,CAAC,CAAC,IAAI,QAAQ,GAAG,CAAC,CAAC,CAAC,QAAQ,CAAC;YACvC,wCAAwC;YACxC,iEAAiE;YACjE,uBAAuB;YACvB,CAAC,SAAS,CAAC,CAAC,CAAC,YAAY,SAAS,GAAG,CAAC,CAAC,CAAC,aAAa,CAAC;YACtD,6DAA6D;YAC7D,0EAA0E;YAC1E,gFAAgF;YAChF,gFAAgF,CACnF,CAAC;QACF,IAAI,CAAC,IAAI,GAAG,sBAAsB,CAAC;QACnC,IAAI,QAAQ,KAAK,SAAS;YAAE,IAAI,CAAC,QAAQ,GAAG,QAAQ,CAAC;QACrD,IAAI,SAAS,KAAK,SAAS;YAAE,IAAI,CAAC,SAAS,GAAG,SAAS,CAAC;IAC1D,CAAC;CACF;AAxBD,oDAwBC;AAED;;;;;;;;;;;;;GAaG;AACH,SAAgB,iBAAiB,CAAC,IAAe,EAAE,UAA0B;IAC3E,IAAI,IAAI,CAAC,YAAY,CAAC,QAAQ,CAAC,UAAU,CAAC;QAAE,OAAO;IACnD,MAAM,GAAG,GAAG,IAAI,CAAC,YAAY,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,YAAY,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC;IACjF,MAAM,IAAI,KAAK,CACb,kBAAkB,IAAI,CAAC,IAAI,4BAA4B,UAAU,KAAK;QACpE,eAAe,GAAG,wBAAwB;QAC1C,+BAA+B,UAAU,uCAAuC;QAChF,oFAAoF,CACvF,CAAC;AACJ,CAAC;AATD,8CASC"}