agentfootprint 7.12.0 → 7.14.0

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

@@ -1,11 +1,14 @@
 /**
- * MCP — Model Context Protocol client integration.
+ * MCP — Model Context Protocol, in both directions.
  *
  * MCP (https://modelcontextprotocol.io) is an open standard for
- * connecting LLMs to external tools and data sources. agentfootprint's
- * MCP adapter is **client-only** — it consumes MCP servers and exposes
- * their tools as agentfootprint `Tool[]` so consumers can plug them
- * straight into `agent.tool(...)`.
+ * connecting LLMs to external tools and data sources. This module
+ * bridges it both ways:
+ *
+ *   - `mcpClient(opts)`  — consume an MCP server; its tools become
+ *     agentfootprint `Tool[]` you can hand to `agent.tools(...)`.
+ *   - `mcpServe(tools, opts)` — the other direction: expose your own
+ *     `Tool[]` AS an MCP server, so any MCP client can call them.
  *
  * Pattern: Adapter (GoF) — translates MCP wire format ↔ agentfootprint
  *          `Tool` interface. The MCP SDK does the protocol work; we
@@ -14,11 +17,8 @@
  *          inline alternative for non-MCP tools).
  * Emits:   N/A directly — wrapped tools emit the standard
  *          `agentfootprint.stream.tool_start` / `tool_end` events
- *          when the agent calls them.
- *
- * Server-side support (exposing an agent or LLMCall as an MCP tool)
- * is a separate concern not yet shipped. This module covers the
- * 80% case: pulling an existing MCP server's tools INTO an agent.
+ *          when the agent calls them. `mcpServe` runs OUTSIDE any
+ *          agent run, so it emits nothing at all.
  */
 import type { Tool } from '../../core/tools.js';
 /**
@@ -32,7 +32,13 @@ export interface McpStdioTransport {
     readonly command: string;
     /** CLI args passed to the executable. */
     readonly args?: readonly string[];
-    /** Optional env vars set on the subprocess. */
+    /**
+     * Environment for the subprocess. Passed to the SDK as-is, and the SDK
+     * treats it as the WHOLE environment: set this and the child no longer
+     * inherits the safe default set (`PATH`, `HOME`, …). Omit it unless you
+     * mean to replace the environment; to merely add a variable, include the
+     * ones the child still needs.
+     */
     readonly env?: Readonly<Record<string, string>>;
     /** Working directory for the subprocess. */
     readonly cwd?: string;
@@ -107,22 +113,29 @@ export interface McpClient {
  *      a lazy peer-dep)
  *
  * The real SDK exports a richer surface; we narrow to what's needed.
+ *
+ * Argument POSITION matters here and is easy to get wrong: the SDK keeps
+ * per-request options (`signal`, `timeout`) in a SEPARATE trailing
+ * argument, never inside the JSON-RPC params. A `signal` smuggled into
+ * the params object is serialized onto the wire as `{}` and silently
+ * fails to cancel anything, so these signatures mirror the SDK's own
+ * shape rather than a flattened convenience version of it.
  */
 export interface McpSdkClient {
-    connect(transport: unknown): Promise<void>;
-    listTools(): Promise<{
+    connect(transport: unknown, options?: McpRequestOptions): Promise<void>;
+    listTools(params?: undefined, options?: McpRequestOptions): Promise<{
         readonly tools: ReadonlyArray<{
             readonly name: string;
             readonly description?: string;
             readonly inputSchema: Readonly<Record<string, unknown>>;
         }>;
     }>;
-    callTool(args: {
+    callTool(params: {
         readonly name: string;
         readonly arguments?: Readonly<Record<string, unknown>>;
-        /** Forwarded from `McpClientOptions.signal` so consumers can cancel hung tool calls. */
-        readonly signal?: AbortSignal;
-    }): Promise<{
+    }, 
+    /** The SDK's result schema. We always want its default, so we pass `undefined`. */
+    resultSchema?: undefined, options?: McpRequestOptions): Promise<{
         readonly content: ReadonlyArray<{
             readonly type: string;
             readonly text?: string;
@@ -131,3 +144,103 @@ export interface McpSdkClient {
     }>;
     close(): Promise<void>;
 }
+/**
+ * The SDK's trailing per-request options argument, narrowed to the one
+ * field we forward from {@link McpClientOptions.signal}.
+ */
+export interface McpRequestOptions {
+    readonly signal?: AbortSignal;
+}
+/**
+ * `stdio` transport — the server speaks MCP over its own stdin/stdout.
+ * This is how a desktop MCP host launches a server: it spawns your
+ * process and talks down the pipe. The default.
+ *
+ * One consequence worth stating out loud: stdout belongs to the
+ * protocol. Anything else your process prints there corrupts the
+ * stream, so log to stderr.
+ */
+export interface McpStdioServeTransport {
+    readonly transport: 'stdio';
+}
+/**
+ * `http` transport — the server listens on a port and speaks MCP over
+ * Streamable HTTP. Stateless (no session ids): every request is
+ * self-contained, which is what makes it safe to run several replicas
+ * behind a load balancer.
+ */
+export interface McpHttpServeTransport {
+    readonly transport: 'http';
+    /** TCP port to listen on. */
+    readonly port: number;
+    /** Interface to bind. Defaults to Node's own default (all interfaces). */
+    readonly host?: string;
+    /** URL path the MCP endpoint answers on. Default `'/mcp'`. */
+    readonly path?: string;
+}
+export type McpServeTransport = McpStdioServeTransport | McpHttpServeTransport;
+export interface McpServeOptions {
+    /**
+     * Server name reported to clients on connect. Surfaces in the
+     * client's server list. Default `'agentfootprint'`.
+     */
+    readonly name?: string;
+    /** Server version reported to clients. Default `'0.0.0'`. */
+    readonly version?: string;
+    /** Transport configuration. Default `{ transport: 'stdio' }`. */
+    readonly transport?: McpServeTransport;
+    /**
+     * Credential provider for served tools that declare `needs`. The
+     * credential is resolved BEFORE `execute` and injected as
+     * `ctx.credential`, exactly as the Agent's tool-call stage does it.
+     *
+     * Serving a `needs`-declaring tool without this is refused at
+     * construction: the tool would run with `ctx.credential` undefined
+     * and fail somewhere further in, or worse, not fail at all.
+     */
+    readonly credentials?: import('../../identity/types.js').CredentialProvider;
+    /**
+     * @internal Pre-built SDK server for tests. Skips SDK import +
+     * transport construction. Mirrors `McpClientOptions._client`.
+     */
+    readonly _server?: McpSdkServer;
+}
+/**
+ * What `mcpServe(...)` returns. The server is already listening by the
+ * time you hold this; `close()` is the only thing left to do.
+ */
+export interface McpServeHandle {
+    /** Server name from options (or the default). */
+    readonly name: string;
+    /** Names of the tools being served, in the order clients will list them. */
+    readonly toolNames: readonly string[];
+    /**
+     * Stop serving: closes the transport (and, for `http`, the listening
+     * socket) and then the MCP server. Idempotent — calling it twice is
+     * not an error, so a shutdown hook and an explicit close can coexist.
+     */
+    close(): Promise<void>;
+}
+/**
+ * Minimal structural type for the parts of the MCP SDK's low-level
+ * `Server` we touch. Defined locally for the same two reasons as
+ * {@link McpSdkClient}: test injection via `McpServeOptions._server`,
+ * and no hard import on the lazy peer-dep.
+ */
+export interface McpSdkServer {
+    setRequestHandler(schema: unknown, handler: (request: McpCallToolRequest, extra: {
+        readonly signal?: AbortSignal;
+    }) => unknown): void;
+    connect(transport: unknown): Promise<void>;
+    close(): Promise<void>;
+}
+/**
+ * The shape `tools/call` requests arrive in. `tools/list` requests carry
+ * no params we read, so one request type covers both handlers.
+ */
+export interface McpCallToolRequest {
+    readonly params?: {
+        readonly name?: string;
+        readonly arguments?: unknown;
+    };
+}

package/dist/esm/lib/mcp/types.js

@@ -1,11 +1,14 @@
 /**
- * MCP — Model Context Protocol client integration.
+ * MCP — Model Context Protocol, in both directions.
  *
  * MCP (https://modelcontextprotocol.io) is an open standard for
- * connecting LLMs to external tools and data sources. agentfootprint's
- * MCP adapter is **client-only** — it consumes MCP servers and exposes
- * their tools as agentfootprint `Tool[]` so consumers can plug them
- * straight into `agent.tool(...)`.
+ * connecting LLMs to external tools and data sources. This module
+ * bridges it both ways:
+ *
+ *   - `mcpClient(opts)`  — consume an MCP server; its tools become
+ *     agentfootprint `Tool[]` you can hand to `agent.tools(...)`.
+ *   - `mcpServe(tools, opts)` — the other direction: expose your own
+ *     `Tool[]` AS an MCP server, so any MCP client can call them.
  *
  * Pattern: Adapter (GoF) — translates MCP wire format ↔ agentfootprint
  *          `Tool` interface. The MCP SDK does the protocol work; we
@@ -14,11 +17,8 @@
  *          inline alternative for non-MCP tools).
  * Emits:   N/A directly — wrapped tools emit the standard
  *          `agentfootprint.stream.tool_start` / `tool_end` events
- *          when the agent calls them.
- *
- * Server-side support (exposing an agent or LLMCall as an MCP tool)
- * is a separate concern not yet shipped. This module covers the
- * 80% case: pulling an existing MCP server's tools INTO an agent.
+ *          when the agent calls them. `mcpServe` runs OUTSIDE any
+ *          agent run, so it emits nothing at all.
  */
 export {};
 //# sourceMappingURL=types.js.map

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

@@ -13,6 +13,12 @@
  *    - `mcpClient(opts)` — connect to an MCP server (real)
  *    - `mockMcpClient({ tools })` — in-memory MCP source for dev / tests
  *
+ * 3. Tool sink — the other direction
+ *    - `mcpServe(tools, opts)` — expose your own `Tool[]` AS an MCP
+ *      server, so any MCP client can call them. The served tool is the
+ *      SAME object you pass in, so whatever governance you composed
+ *      around it still runs.
+ *
  * Compose freely. The dispatch layer is decorator-shaped (mirroring
  * `withRetry` / `withFallback` over LLMProvider). Tool sources produce
  * `Tool[]` that flow into a `staticTools(arr)` provider, which can
@@ -37,5 +43,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, mockMcpClient } from '../lib/mcp/index.js';
-export type { McpClient, McpClientOptions, McpSdkClient, McpTransport, McpStdioTransport, McpHttpTransport, MockMcpClientOptions, MockMcpTool, } from '../lib/mcp/index.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';

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

@@ -13,6 +13,12 @@
  *    - `mcpClient(opts)` — connect to an MCP server (real)
  *    - `mockMcpClient({ tools })` — in-memory MCP source for dev / tests
  *
+ * 3. Tool sink — the other direction
+ *    - `mcpServe(tools, opts)` — expose your own `Tool[]` AS an MCP
+ *      server, so any MCP client can call them. The served tool is the
+ *      SAME object you pass in, so whatever governance you composed
+ *      around it still runs.
+ *
  * Compose freely. The dispatch layer is decorator-shaped (mirroring
  * `withRetry` / `withFallback` over LLMProvider). Tool sources produce
  * `Tool[]` that flow into a `staticTools(arr)` provider, which can
@@ -39,5 +45,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, mockMcpClient } from '../lib/mcp/index.js';
+export { mcpClient, mcpServe, mockMcpClient } 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;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;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,aAAa,EAAE,MAAM,qBAAqB,CAAC"}
+{"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"}

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"}

package/dist/hosting/index.js

@@ -0,0 +1,64 @@
+"use strict";
+/**
+ * agentfootprint/hosting — the two ports between an agent and the place it runs.
+ *
+ * An agent that answers one call in a script and an agent that has been up for
+ * a month differ in two things, and only two: something has to carry requests
+ * to it, and the conversation has to outlive the request. This subpath is those
+ * two things as **ports**, plus local adapters that prove the ports work, plus
+ * the composer that wires them together.
+ *
+ *   `AgentHost`         — something can call me.
+ *   `SessionLifecycle`  — the conversation outlives the request.
+ *   `standingAgent`     — hydrate → resume-or-fresh → persist → reply.
+ *
+ * ── Why the ports look like nothing in particular ────────────────────────────
+ * Deliberately. Not one field, name or assumption here comes from any hosting
+ * product, cloud or protocol. A port shaped around one provider's request
+ * envelope stops being a port and becomes that provider's SDK with extra steps,
+ * and every adapter after the first pays for the shortcut. So the ports carry
+ * an input, a reply, an optional session id, headers, a signal — the vocabulary
+ * every transport already has — and everything specific to one place you might
+ * deploy lives in the adapter for that place. `nodeHost` gets no special
+ * treatment: its paths, status codes and JSON body shape are all in
+ * `nodeHost.ts` and the port types do not know they exist. A test greps these
+ * source files for vendor names, crudely and on purpose.
+ *
+ * ── What ships here ──────────────────────────────────────────────────────────
+ *   • `nodeHost({ port?, hostname?, invokePath?, healthPath? })` — plain
+ *     `node:http`, zero dependencies. `POST /invoke`, `GET /health`, and
+ *     Server-Sent Events when the caller asks for them.
+ *   • `memorySessions()` — conversations in a Map, for tests and local dev.
+ *   • `standingAgent({ agent, sessions, host })` — the composer.
+ *   • `toEnvelope` / `readEnvelope` — pack a conversation, and refuse by name to
+ *     unpack a format this runtime does not know.
+ *   • `requireCapability` — feature-detection with teeth.
+ *
+ * @example  An agent that stays up and remembers
+ *   import { Agent } from 'agentfootprint';
+ *   import { standingAgent, nodeHost, memorySessions } from 'agentfootprint/hosting';
+ *
+ *   const handle = await standingAgent({
+ *     agent: Agent.create({ provider, model }).system('You help customers.').build(),
+ *     sessions: memorySessions(),
+ *     host: nodeHost({ port: 8080 }),
+ *   });
+ *   process.on('SIGTERM', () => void handle.close());
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PauseNotCarriedError = exports.ConcurrentRunError = exports.HostClosedError = exports.requireCapability = exports.standingAgent = exports.readEnvelope = exports.toEnvelope = exports.memorySessions = exports.nodeHost = void 0;
+var nodeHost_js_1 = require("./nodeHost.js");
+Object.defineProperty(exports, "nodeHost", { enumerable: true, get: function () { return nodeHost_js_1.nodeHost; } });
+var memorySessions_js_1 = require("./memorySessions.js");
+Object.defineProperty(exports, "memorySessions", { enumerable: true, get: function () { return memorySessions_js_1.memorySessions; } });
+var envelope_js_1 = require("./envelope.js");
+Object.defineProperty(exports, "toEnvelope", { enumerable: true, get: function () { return envelope_js_1.toEnvelope; } });
+Object.defineProperty(exports, "readEnvelope", { enumerable: true, get: function () { return envelope_js_1.readEnvelope; } });
+var standingAgent_js_1 = require("./standingAgent.js");
+Object.defineProperty(exports, "standingAgent", { enumerable: true, get: function () { return standingAgent_js_1.standingAgent; } });
+var errors_js_1 = require("./errors.js");
+Object.defineProperty(exports, "requireCapability", { enumerable: true, get: function () { return errors_js_1.requireCapability; } });
+Object.defineProperty(exports, "HostClosedError", { enumerable: true, get: function () { return errors_js_1.HostClosedError; } });
+Object.defineProperty(exports, "ConcurrentRunError", { enumerable: true, get: function () { return errors_js_1.ConcurrentRunError; } });
+Object.defineProperty(exports, "PauseNotCarriedError", { enumerable: true, get: function () { return errors_js_1.PauseNotCarriedError; } });
+//# sourceMappingURL=index.js.map

package/dist/hosting/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/hosting/index.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6CG;;;AAEH,6CAAyC;AAAhC,uGAAA,QAAQ,OAAA;AAGjB,yDAAqD;AAA5C,mHAAA,cAAc,OAAA;AACvB,6CAAyD;AAAhD,yGAAA,UAAU,OAAA;AAAE,2GAAA,YAAY,OAAA;AACjC,uDAAmD;AAA1C,iHAAA,aAAa,OAAA;AAEtB,yCAKqB;AAJnB,8GAAA,iBAAiB,OAAA;AACjB,4GAAA,eAAe,OAAA;AACf,+GAAA,kBAAkB,OAAA;AAClB,iHAAA,oBAAoB,OAAA"}

package/dist/hosting/memorySessions.js

@@ -0,0 +1,35 @@
+"use strict";
+/**
+ * hosting/memorySessions — conversations in a Map.
+ *
+ * The smallest thing that satisfies `SessionLifecycle`, for tests and for local
+ * development where a Redis is ceremony you have not earned yet. It is exactly
+ * as durable as the process: restart and every conversation is gone.
+ *
+ * That is not a shortcoming to apologise for, it is the point of the port. Swap
+ * this for a store that survives a restart and the standing agent is unchanged
+ * — which is also how the "a crashed process resumes the conversation" test is
+ * written: keep the store, throw away everything else, and watch the
+ * conversation come back through the envelope alone.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.memorySessions = void 0;
+/**
+ * An in-process session store.
+ *
+ * @example
+ *   const sessions = memorySessions();
+ *   await standingAgent({ agent, sessions, host: nodeHost({ port: 8080 }) });
+ */
+function memorySessions() {
+    const stored = new Map();
+    return {
+        hydrate: (sessionId) => Promise.resolve(stored.get(sessionId)),
+        persist: (sessionId, envelope) => {
+            stored.set(sessionId, envelope);
+            return Promise.resolve();
+        },
+    };
+}
+exports.memorySessions = memorySessions;
+//# sourceMappingURL=memorySessions.js.map

package/dist/hosting/memorySessions.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"memorySessions.js","sourceRoot":"","sources":["../../src/hosting/memorySessions.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;GAYG;;;AAIH;;;;;;GAMG;AACH,SAAgB,cAAc;IAC5B,MAAM,MAAM,GAAG,IAAI,GAAG,EAA8B,CAAC;IACrD,OAAO;QACL,OAAO,EAAE,CAAC,SAAS,EAAE,EAAE,CAAC,OAAO,CAAC,OAAO,CAAC,MAAM,CAAC,GAAG,CAAC,SAAS,CAAC,CAAC;QAC9D,OAAO,EAAE,CAAC,SAAS,EAAE,QAAQ,EAAE,EAAE;YAC/B,MAAM,CAAC,GAAG,CAAC,SAAS,EAAE,QAAQ,CAAC,CAAC;YAChC,OAAO,OAAO,CAAC,OAAO,EAAE,CAAC;QAC3B,CAAC;KACF,CAAC;AACJ,CAAC;AATD,wCASC"}