webdaemon 28.1.0 → 28.2.1

package/dist/types/index.d.ts

@@ -10,6 +10,7 @@ export * from "./js/ParentHelper.js";
 export * from "./js/QrCode.js";
 export * from "./js/Storage.js";
 /** Backend libs */
+export * from "./ts/AbstractHandler.ts";
 export * from "./ts/Assertions.ts";
 export * from "./ts/GenerativeChatAgent.ts";
 export * from "./ts/GenerativeChatEvents.ts";

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

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../index.ts"],"names":[],"mappings":"AAAA,kBAAkB;AAClB,cAAc,gBAAgB,CAAC;AAC/B,cAAc,+BAA+B,CAAC;AAC9C,cAAc,iBAAiB,CAAC;AAChC,cAAc,eAAe,CAAC;AAE9B,mBAAmB;AACnB,cAAc,eAAe,CAAC;AAC9B,cAAc,oBAAoB,CAAC;AACnC,cAAc,sBAAsB,CAAC;AACrC,cAAc,gBAAgB,CAAC;AAC/B,cAAc,iBAAiB,CAAC;AAEhC,mBAAmB;AACnB,cAAc,oBAAoB,CAAC;AACnC,cAAc,6BAA6B,CAAC;AAC5C,cAAc,8BAA8B,CAAC;AAC7C,cAAc,qBAAqB,CAAC;AACpC,cAAc,mBAAmB,CAAC;AAClC,cAAc,uBAAuB,CAAC;AACtC,cAAc,mBAAmB,CAAC;AAClC,cAAc,mBAAmB,CAAC;AAClC,cAAc,8BAA8B,CAAC;AAC7C,cAAc,kBAAkB,CAAC;AACjC,cAAc,mBAAmB,CAAC;AAClC,cAAc,qBAAqB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../index.ts"],"names":[],"mappings":"AAAA,kBAAkB;AAClB,cAAc,gBAAgB,CAAC;AAC/B,cAAc,+BAA+B,CAAC;AAC9C,cAAc,iBAAiB,CAAC;AAChC,cAAc,eAAe,CAAC;AAE9B,mBAAmB;AACnB,cAAc,eAAe,CAAC;AAC9B,cAAc,oBAAoB,CAAC;AACnC,cAAc,sBAAsB,CAAC;AACrC,cAAc,gBAAgB,CAAC;AAC/B,cAAc,iBAAiB,CAAC;AAEhC,mBAAmB;AACnB,cAAc,yBAAyB,CAAC;AACxC,cAAc,oBAAoB,CAAC;AACnC,cAAc,6BAA6B,CAAC;AAC5C,cAAc,8BAA8B,CAAC;AAC7C,cAAc,qBAAqB,CAAC;AACpC,cAAc,mBAAmB,CAAC;AAClC,cAAc,uBAAuB,CAAC;AACtC,cAAc,mBAAmB,CAAC;AAClC,cAAc,mBAAmB,CAAC;AAClC,cAAc,8BAA8B,CAAC;AAC7C,cAAc,kBAAkB,CAAC;AACjC,cAAc,mBAAmB,CAAC;AAClC,cAAc,qBAAqB,CAAC"}

package/dist/types/js/KeyPair.d.ts

@@ -1,14 +1,58 @@
+/**
+ * Generates a signing keypair and exports it in the formats the platform
+ * uses: JWK (for Token signing and the daemon's `/device/<id>/public.jwk`
+ * and `/issuer/<id>` endpoints) and PEM.
+ *
+ * The default algorithm is RSASSA-PKCS1-v1_5 / 2048 / SHA-256 — the same
+ * scheme Token verification expects. Works browser- or agent-side, but
+ * requires a secure context (crypto.subtle).
+ *
+ * Usage:
+ *
+ *   const keys = new KeyPair()
+ *   await keys.generate()
+ *   const publicJwk = await keys.publicJwk()
+ *   const privateJwk = await keys.privateJwk()
+ */
 export class KeyPair {
-    constructor(algorithm?: {
-        name: string;
-        modulusLength: number;
-        publicExponent: Uint8Array<ArrayBuffer>;
-        hash: string;
-    });
+    /**
+     * @param {RsaHashedKeyGenParams | EcKeyGenParams} [algorithm] a crypto.subtle.generateKey algorithm;
+     *   defaults to the platform's signing scheme.
+     * @throws {string} exception outside a secure context.
+     */
+    constructor(algorithm?: RsaHashedKeyGenParams | EcKeyGenParams);
+    /**
+     * Generates the keypair (extractable, usages sign/verify). Must be
+     * called before any of the export methods.
+     */
     generate(): Promise<void>;
+    /**
+     * Returns the public key as a JWK object.
+     *
+     * @return {Promise<JsonWebKey>} the public JWK.
+     * @throws {string} exception if generate() has not been called.
+     */
     publicJwk(): Promise<JsonWebKey>;
+    /**
+     * Returns the private key as a JWK object.
+     *
+     * @return {Promise<JsonWebKey>} the private JWK.
+     * @throws {string} exception if generate() has not been called.
+     */
     privateJwk(): Promise<JsonWebKey>;
+    /**
+     * Returns the public key in PEM (SPKI) format.
+     *
+     * @return {Promise<string>} the PEM string.
+     * @throws {string} exception if generate() has not been called.
+     */
     publicPem(): Promise<string>;
+    /**
+     * Returns the private key in PEM (PKCS#8) format.
+     *
+     * @return {Promise<string>} the PEM string.
+     * @throws {string} exception if generate() has not been called.
+     */
     privatePem(): Promise<string>;
     #private;
 }

package/dist/types/js/KeyPair.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"KeyPair.d.ts","sourceRoot":"","sources":["../../../js/KeyPair.js"],"names":[],"mappings":"AAOA;IAME;;;;;OAKC;IAED,0BAMC;IAED,iCAOC;IAED,kCAOC;IAED,6BAUC;IAED,8BAUC;;CACF"}
+{"version":3,"file":"KeyPair.d.ts","sourceRoot":"","sources":["../../../js/KeyPair.js"],"names":[],"mappings":"AAOA;;;;;;;;;;;;;;;GAeG;AACH;IAME;;;;OAIG;IACH,wBAJW,qBAAqB,GAAG,cAAc,EAShD;IAED;;;OAGG;IACH,0BAMC;IAED;;;;;OAKG;IACH,aAHY,OAAO,CAAC,UAAU,CAAC,CAU9B;IAED;;;;;OAKG;IACH,cAHY,OAAO,CAAC,UAAU,CAAC,CAU9B;IAED;;;;;OAKG;IACH,aAHY,OAAO,CAAC,MAAM,CAAC,CAa1B;IAED;;;;;OAKG;IACH,cAHY,OAAO,CAAC,MAAM,CAAC,CAa1B;;CACF"}

package/dist/types/ts/AbstractHandler.d.ts

@@ -0,0 +1,55 @@
+import { Token } from '../js/Token.js';
+/**
+ * Base class for agent-side request handlers, giving each request a uniform
+ * shape: token verification, capability assertion, and error-to-response
+ * wrapping. An agent tab dispatches with a chain of
+ * `X.shouldHandle(request)` checks:
+ *
+ * ```ts
+ * Deno.serve({ port: 0 }, (request) => {
+ *   if (Status.shouldHandle(request)) return new Status(request).handler()
+ *   if (Ingest.shouldHandle(request)) return new Ingest(request).handler()
+ *   return response({ error: '404 Not Found' })
+ * })
+ * ```
+ *
+ * Subclasses provide a static `shouldHandle(request)` and implement
+ * `handle()`. `handler()` validates the token then delegates to `handle()`;
+ * any thrown value becomes a standard error response. Handlers that accept
+ * token-less requests (OAuth callbacks, webhooks) override `validate()`:
+ *
+ * ```ts
+ * override async validate(): Promise<void> {
+ *   await super.validate(false)
+ * }
+ * ```
+ */
+export declare abstract class AbstractHandler {
+    token: Token | null;
+    request: Request;
+    url: URL;
+    protocol: string;
+    host: string;
+    constructor(request: Request);
+    /**
+     * Verifies the token signatory and that the token party matches the
+     * request host. With `enforceToken` (the default), a missing token
+     * throws; pass `false` for endpoints that accept token-less requests,
+     * which still verify a token when one is present.
+     */
+    validate(enforceToken?: boolean): Promise<void>;
+    /**
+     * Throws unless the request token holds the capability on this app's
+     * source. The daemon only forwards granted capabilities, so a present
+     * capability is indeed granted.
+     */
+    assertCapability(capability: string): void;
+    /**
+     * Validates then delegates to `handle()`. Never throws — any thrown
+     * value is logged and returned as a standard error response.
+     */
+    handler(): Promise<Response>;
+    /** The request implementation, provided by the subclass. */
+    abstract handle(): Promise<Response>;
+}
+//# sourceMappingURL=AbstractHandler.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"AbstractHandler.d.ts","sourceRoot":"","sources":["../../../ts/AbstractHandler.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,KAAK,EAAE,MAAM,gBAAgB,CAAA;AAEtC;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,8BAAsB,eAAe;IACnC,KAAK,EAAE,KAAK,GAAG,IAAI,CAAA;IACnB,OAAO,EAAE,OAAO,CAAA;IAChB,GAAG,EAAE,GAAG,CAAA;IACR,QAAQ,EAAE,MAAM,CAAA;IAChB,IAAI,EAAE,MAAM,CAAA;gBAEA,OAAO,EAAE,OAAO;IAQ5B;;;;;OAKG;IACG,QAAQ,CAAC,YAAY,UAAO,GAAG,OAAO,CAAC,IAAI,CAAC;IAalD;;;;OAIG;IACH,gBAAgB,CAAC,UAAU,EAAE,MAAM,GAAG,IAAI;IAY1C;;;OAGG;IACG,OAAO,IAAI,OAAO,CAAC,QAAQ,CAAC;IAYlC,4DAA4D;IAC5D,QAAQ,CAAC,MAAM,IAAI,OAAO,CAAC,QAAQ,CAAC;CACrC"}

package/dist/types/ts/McpAgentTools.d.ts

@@ -1,16 +1,23 @@
 export type JSONRecord = Record<string, unknown>;
+/** A tool invocation requested by the chat model. */
 export interface ChatToolCall {
     id: string;
     name: string;
     input: JSONRecord;
 }
+/** A tool as presented to the chat model; executed agent-side. */
 export interface ChatToolDescriptor {
     type: 'function';
     name: string;
     execution: 'server';
     description?: string;
+    /** JSON Schema for the tool's input. */
     parameters?: JSONRecord;
 }
+/**
+ * A tool executed in the browser by the app's frontend rather than by the
+ * agent; passed through `chatTools()` untouched.
+ */
 export interface ClientToolDescriptor {
     type: 'function';
     name: string;
@@ -18,18 +25,25 @@ export interface ClientToolDescriptor {
     description?: string;
     parameters?: JSONRecord;
 }
+/** Outcome of one executed tool call, for the model's next turn. */
 export interface ToolResult {
     toolCallId: string;
     name?: string;
     content: string;
     isError?: boolean;
 }
+/**
+ * How a catalog tool is reached: `kind` is `platform` (a daemon POST route
+ * such as `/ai/memory/search`) or `mcp` (an app's MCP server, addressed by
+ * `path` and optionally a differing `mcpToolName`).
+ */
 export interface ToolRoute {
     kind: string;
     method?: string;
     path?: string;
     mcpToolName?: string;
 }
+/** One entry of the party tool catalog returned by `/ai/tools/catalog`. */
 export interface ToolCatalogEntry {
     tool?: {
         name?: string;
@@ -38,20 +52,43 @@ export interface ToolCatalogEntry {
     };
     route?: ToolRoute;
 }
+/**
+ * Transports for {@link AgentToolRuntime}, both POSTing to party endpoints
+ * with the agent's token: `postParty` unwraps the daemon's `Ok`/`Error`
+ * envelope, `postPartyRaw` returns the raw JSON body (required for JSON-RPC,
+ * whose envelope must pass through untouched).
+ */
 export interface AgentToolRuntimeOptions {
     postParty: (path: string, body: JSONRecord) => Promise<JSONRecord>;
     postPartyRaw: (path: string, body: JSONRecord) => Promise<JSONRecord>;
 }
+/**
+ * The single-party tool runtime: loads the party's tool catalog, exposes it
+ * as chat tool descriptors, and executes calls by routing each to its
+ * catalog-declared route — platform routes via `postParty`, MCP tools via a
+ * cached {@link JsonRpcMcpClient} per MCP path.
+ */
 export declare class AgentToolRuntime {
     #private;
     constructor(options: AgentToolRuntimeOptions);
     get toolCatalog(): ToolCatalogEntry[];
+    /** Reloads the party tool catalog from `/ai/tools/catalog`. */
     refreshCatalog(): Promise<void>;
+    /** Replaces the catalog with an already-fetched `tools` value. */
     setCatalog(value: unknown): void;
+    /** The catalog as chat tool descriptors, plus any given client tools. */
     chatTools(options?: {
         clientTools?: ClientToolDescriptor[];
     }): Array<ChatToolDescriptor | ClientToolDescriptor>;
+    /**
+     * Executes calls sequentially; a failed call yields an `isError` result
+     * rather than throwing, so one failure doesn't abort the batch.
+     */
     executeToolCalls(toolCalls: ChatToolCall[]): Promise<ToolResult[]>;
+    /**
+     * Executes one call via its catalog route and returns the JSON-stringified
+     * result. Throws on unknown tools or unsupported routes.
+     */
     executeToolCall(call: ChatToolCall): Promise<string>;
 }
 /**
@@ -112,6 +149,7 @@ export declare class GatewayToolRuntime implements SessionToolRuntime {
     }): Array<ChatToolDescriptor | ClientToolDescriptor>;
     executeToolCall(call: ChatToolCall): Promise<string>;
 }
+/** A catalog entry as a chat tool descriptor; `null` if it has no name. */
 export declare function toChatTool(entry: ToolCatalogEntry): ChatToolDescriptor | null;
 /**
  * Combines an app's once-authored, app-level description (`appDescription`) with

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

@@ -1 +1 @@
-{"version":3,"file":"McpAgentTools.d.ts","sourceRoot":"","sources":["../../../ts/McpAgentTools.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"McpAgentTools.d.ts","sourceRoot":"","sources":["../../../ts/McpAgentTools.ts"],"names":[],"mappings":"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"}

package/dist/types/ts/McpClient.d.ts

@@ -1,17 +1,56 @@
+/**
+ * Client side of the Model Context Protocol (MCP) over JSON-RPC 2.0 / HTTP.
+ *
+ * {@link JsonRpcMcpClient} talks to any MCP server that accepts JSON-RPC via
+ * HTTP POST — an app tab's own server (see McpServer.ts) or a daemon's MCP
+ * gateway at `/mcp/rpc`. Only the tool methods are implemented (`tools/list`,
+ * `tools/call`); there is no `initialize` handshake.
+ */
 import type { JSONValue } from './Assertions.ts';
 type JSONRecord = Record<string, unknown>;
+/**
+ * Either a ready-made `post` transport (given a JSON-RPC body, returns the
+ * parsed JSON response — useful when requests must be signed or proxied), or a
+ * `url` to POST to directly, with optional `headers` (a value or a possibly
+ * async factory, e.g. to mint a fresh token per request) and a `fetch`
+ * replacement.
+ */
 export interface JsonRpcMcpClientOptions {
     post?: (body: JSONRecord) => Promise<JSONRecord>;
     url?: string;
     headers?: HeadersInit | (() => HeadersInit | Promise<HeadersInit>);
     fetch?: typeof fetch;
 }
+/**
+ * Minimal MCP client. Wire it to a server with either a `post` function or a
+ * `url` (see {@link JsonRpcMcpClientOptions}); request ids are assigned
+ * sequentially per client instance.
+ *
+ * ```ts
+ * const client = new JsonRpcMcpClient({
+ *   url: 'https://alice.daemon.com/mcp/rpc',
+ *   headers: () => ({ 'X-Tabserver-Token': token }),
+ * })
+ * const tools = await client.listTools()
+ * const result = await client.callTool('expert_ask', { question: '…' })
+ * ```
+ */
 export declare class JsonRpcMcpClient {
     #private;
     constructor(options: JsonRpcMcpClientOptions);
+    /** The server's tool descriptors (`tools/list`); empty array if none. */
     listTools(): Promise<JSONValue[]>;
+    /**
+     * Calls the named tool and returns its `structuredContent` (or `null` when
+     * the server sent none). Throws the server's error text when the result is
+     * flagged `isError`, and the JSON-RPC error message on protocol failures.
+     */
     callTool(name: string, args?: JSONRecord): Promise<JSONValue>;
 }
+/**
+ * Extracts a human-readable message from an `isError` MCP tool result — the
+ * first `content` text block, or a generic fallback.
+ */
 export declare function mcpToolErrorMessage(result: unknown): string;
 export {};
 //# sourceMappingURL=McpClient.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"McpClient.d.ts","sourceRoot":"","sources":["../../../ts/McpClient.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAA;AAEhD,KAAK,UAAU,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;AAEzC,MAAM,WAAW,uBAAuB;IACtC,IAAI,CAAC,EAAE,CAAC,IAAI,EAAE,UAAU,KAAK,OAAO,CAAC,UAAU,CAAC,CAAA;IAChD,GAAG,CAAC,EAAE,MAAM,CAAA;IACZ,OAAO,CAAC,EAAE,WAAW,GAAG,CAAC,MAAM,WAAW,GAAG,OAAO,CAAC,WAAW,CAAC,CAAC,CAAA;IAClE,KAAK,CAAC,EAAE,OAAO,KAAK,CAAA;CACrB;AAED,qBAAa,gBAAgB;;gBAIf,OAAO,EAAE,uBAAuB;IAwBtC,SAAS,IAAI,OAAO,CAAC,SAAS,EAAE,CAAC;IAMjC,QAAQ,CACZ,IAAI,EAAE,MAAM,EACZ,IAAI,GAAE,UAAe,GACpB,OAAO,CAAC,SAAS,CAAC;CA6BtB;AAED,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,OAAO,GAAG,MAAM,CAO3D"}
+{"version":3,"file":"McpClient.d.ts","sourceRoot":"","sources":["../../../ts/McpClient.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAA;AAEhD,KAAK,UAAU,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;AAEzC;;;;;;GAMG;AACH,MAAM,WAAW,uBAAuB;IACtC,IAAI,CAAC,EAAE,CAAC,IAAI,EAAE,UAAU,KAAK,OAAO,CAAC,UAAU,CAAC,CAAA;IAChD,GAAG,CAAC,EAAE,MAAM,CAAA;IACZ,OAAO,CAAC,EAAE,WAAW,GAAG,CAAC,MAAM,WAAW,GAAG,OAAO,CAAC,WAAW,CAAC,CAAC,CAAA;IAClE,KAAK,CAAC,EAAE,OAAO,KAAK,CAAA;CACrB;AAED;;;;;;;;;;;;;GAaG;AACH,qBAAa,gBAAgB;;gBAIf,OAAO,EAAE,uBAAuB;IAwB5C,yEAAyE;IACnE,SAAS,IAAI,OAAO,CAAC,SAAS,EAAE,CAAC;IAMvC;;;;OAIG;IACG,QAAQ,CACZ,IAAI,EAAE,MAAM,EACZ,IAAI,GAAE,UAAe,GACpB,OAAO,CAAC,SAAS,CAAC;CA6BtB;AAED;;;GAGG;AACH,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,OAAO,GAAG,MAAM,CAO3D"}

package/dist/types/ts/McpServer.d.ts

@@ -1,11 +1,48 @@
+/**
+ * Server side of the Model Context Protocol (MCP) over JSON-RPC 2.0 / HTTP.
+ *
+ * An app's agent tab uses {@link JsonRpcMcpServer} to expose tools declared in
+ * its YAML `mcp:` block at the tab's MCP path (by default `/rpc`). The daemon's
+ * MCP gateway (`/mcp/rpc`) aggregates these per-app servers into one catalog;
+ * see docs/reference/mcp-gateway.md.
+ *
+ * Typical agent-side wiring:
+ *
+ * ```ts
+ * const server = new JsonRpcMcpServer(
+ *   new McpToolRegistry([myToolDefinition]),
+ *   (request) => contextFromRequest(request),
+ * )
+ * // in the tab's fetch handler:
+ * if (url.pathname === '/rpc') return server.handle(request)
+ * ```
+ */
 import type { JSONObject, JSONValue } from './Assertions.ts';
+/** The `arguments` object of a `tools/call` request, as sent by the client. */
 export type McpToolArguments = Record<string, unknown>;
+/**
+ * Per-request context passed to every tool call, derived from the incoming
+ * HTTP request by the `context` function given to {@link JsonRpcMcpServer}.
+ * Servers may extend it with their own fields (e.g. the verified token).
+ */
 export interface McpContext {
+    /** Hostname of the party (daemon) the request addresses. */
     party?: string;
+    /** URL of the app source the request is for. */
     source?: string;
+    /** Request protocol, e.g. `https:`. */
     protocol?: string;
+    /** The app's tab prefix, when the request arrived via `/tab/<prefix>/…`. */
     sourcePrefix?: string;
 }
+/**
+ * One tool as registered with a {@link McpToolRegistry}: its MCP metadata
+ * (mirrored verbatim into `tools/list`) plus the `call` implementation.
+ *
+ * `capability` is not part of the MCP wire format — it names the capability a
+ * caller's token must hold for this tool, and must match the tool's entry in
+ * the app YAML `mcp.tools` block (see McpToolAuthorization.ts).
+ */
 export interface McpToolDefinition<TContext extends McpContext> {
     name: string;
     title?: string;
@@ -16,31 +53,76 @@ export interface McpToolDefinition<TContext extends McpContext> {
     capability?: string;
     call: (args: McpToolArguments, context: TContext) => Promise<JSONValue> | JSONValue;
 }
+/**
+ * Source of tools for a {@link JsonRpcMcpServer}. {@link McpToolRegistry} is
+ * the static implementation; implement this directly when the tool list is
+ * dynamic or depends on the caller (as the daemon's MCP gateway does).
+ */
 export interface McpToolProvider<TContext extends McpContext> {
+    /** Tool descriptors for `tools/list`, optionally scoped to the caller. */
     listTools(context?: TContext): Promise<JSONValue[]> | JSONValue[];
+    /**
+     * Runs the named tool and returns its structured result. Throw
+     * {@link ProtocolError} for protocol-level failures (unknown tool, bad
+     * params); any other thrown error becomes an in-band tool error result.
+     */
     callTool(name: string, args: McpToolArguments, context: TContext): Promise<JSONValue>;
 }
 export interface JsonRpcMcpServerOptions<TContext extends McpContext> {
+    /** Reported in the `initialize` response; defaults to `mcp-server`/`1`. */
     serverInfo?: {
         name: string;
         version: string;
     };
+    /** Derives the per-request {@link McpContext} passed to tool calls. */
     context: (request: Request) => TContext;
 }
+/**
+ * A fixed list of {@link McpToolDefinition}s exposed as a
+ * {@link McpToolProvider}. `listTools` reflects each definition's metadata;
+ * `callTool` dispatches by name and rejects unknown names with JSON-RPC
+ * `-32602`.
+ */
 export declare class McpToolRegistry<TContext extends McpContext> implements McpToolProvider<TContext> {
     #private;
     constructor(tools: McpToolDefinition<TContext>[]);
     listTools(): JSONValue[];
     callTool(name: string, args: McpToolArguments, context: TContext): Promise<JSONValue>;
 }
+/**
+ * A minimal MCP server speaking JSON-RPC 2.0 over HTTP POST. Supports the
+ * methods `initialize`, `notifications/initialized`, `tools/list` and
+ * `tools/call` (protocol version 2025-06-18); GET returns an SSE endpoint
+ * event for clients that probe for the legacy SSE transport. All responses
+ * carry `Access-Control-Allow-Origin: *`.
+ *
+ * Authentication is not handled here — callers gate `handle()` behind their
+ * own token checks (see McpToolAuthorization.ts).
+ */
 export declare class JsonRpcMcpServer<TContext extends McpContext = McpContext> {
     #private;
     constructor(tools: McpToolProvider<TContext>, contextOrOptions: ((request: Request) => TContext) | JsonRpcMcpServerOptions<TContext>);
+    /**
+     * Handles one HTTP request against the MCP endpoint and always resolves to
+     * a Response — protocol errors are encoded as JSON-RPC error responses,
+     * tool failures as in-band tool results with `isError: true`. Requests
+     * without an `id` (notifications) are acknowledged with `202`.
+     */
     handle(request: Request): Promise<Response>;
 }
+/**
+ * A JSON-RPC protocol-level failure. Thrown from a {@link McpToolProvider} it
+ * becomes a JSON-RPC error response with the given `code` (e.g. `-32601`
+ * method not found, `-32602` invalid params) rather than a tool result.
+ */
 export declare class ProtocolError extends Error {
     code: number;
     constructor(code: number, message: string);
 }
+/**
+ * Wraps a tool's structured result in the MCP `tools/call` result shape:
+ * a `content` text block (JSON-stringified unless already a string) alongside
+ * `structuredContent` and the `isError` flag.
+ */
 export declare function mcpToolResult(structuredContent: JSONValue, isError?: boolean): JSONValue;
 //# sourceMappingURL=McpServer.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"McpServer.d.ts","sourceRoot":"","sources":["../../../ts/McpServer.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAA;AAS5D,MAAM,MAAM,gBAAgB,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;AAEtD,MAAM,WAAW,UAAU;IACzB,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,YAAY,CAAC,EAAE,MAAM,CAAA;CACtB;AAED,MAAM,WAAW,iBAAiB,CAAC,QAAQ,SAAS,UAAU;IAC5D,IAAI,EAAE,MAAM,CAAA;IACZ,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,WAAW,EAAE,MAAM,CAAA;IACnB,WAAW,EAAE,SAAS,CAAA;IACtB,YAAY,CAAC,EAAE,SAAS,CAAA;IACxB,WAAW,CAAC,EAAE,UAAU,CAAA;IACxB,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB,IAAI,EAAE,CACJ,IAAI,EAAE,gBAAgB,EACtB,OAAO,EAAE,QAAQ,KACd,OAAO,CAAC,SAAS,CAAC,GAAG,SAAS,CAAA;CACpC;AAED,MAAM,WAAW,eAAe,CAAC,QAAQ,SAAS,UAAU;IAC1D,SAAS,CAAC,OAAO,CAAC,EAAE,QAAQ,GAAG,OAAO,CAAC,SAAS,EAAE,CAAC,GAAG,SAAS,EAAE,CAAA;IACjE,QAAQ,CACN,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,gBAAgB,EACtB,OAAO,EAAE,QAAQ,GAChB,OAAO,CAAC,SAAS,CAAC,CAAA;CACtB;AAED,MAAM,WAAW,uBAAuB,CAAC,QAAQ,SAAS,UAAU;IAClE,UAAU,CAAC,EAAE;QACX,IAAI,EAAE,MAAM,CAAA;QACZ,OAAO,EAAE,MAAM,CAAA;KAChB,CAAA;IACD,OAAO,EAAE,CAAC,OAAO,EAAE,OAAO,KAAK,QAAQ,CAAA;CACxC;AAED,qBAAa,eAAe,CAAC,QAAQ,SAAS,UAAU,CACtD,YAAW,eAAe,CAAC,QAAQ,CAAC;;gBAGxB,KAAK,EAAE,iBAAiB,CAAC,QAAQ,CAAC,EAAE;IAIhD,SAAS,IAAI,SAAS,EAAE;IAelB,QAAQ,CACZ,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,gBAAgB,EACtB,OAAO,EAAE,QAAQ,GAChB,OAAO,CAAC,SAAS,CAAC;CAOtB;AAED,qBAAa,gBAAgB,CAAC,QAAQ,SAAS,UAAU,GAAG,UAAU;;gBAMlE,KAAK,EAAE,eAAe,CAAC,QAAQ,CAAC,EAChC,gBAAgB,EACZ,CAAC,CAAC,OAAO,EAAE,OAAO,KAAK,QAAQ,CAAC,GAChC,uBAAuB,CAAC,QAAQ,CAAC;IAkBjC,MAAM,CAAC,OAAO,EAAE,OAAO,GAAG,OAAO,CAAC,QAAQ,CAAC;CA8GlD;AAED,qBAAa,aAAc,SAAQ,KAAK;IACtC,IAAI,EAAE,MAAM,CAAA;gBAEA,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM;CAI1C;AAED,wBAAgB,aAAa,CAC3B,iBAAiB,EAAE,SAAS,EAC5B,OAAO,UAAQ,GACd,SAAS,CAaX"}
+{"version":3,"file":"McpServer.d.ts","sourceRoot":"","sources":["../../../ts/McpServer.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AACH,OAAO,KAAK,EAAE,UAAU,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAA;AAU5D,+EAA+E;AAC/E,MAAM,MAAM,gBAAgB,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;AAEtD;;;;GAIG;AACH,MAAM,WAAW,UAAU;IACzB,4DAA4D;IAC5D,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,gDAAgD;IAChD,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,uCAAuC;IACvC,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,4EAA4E;IAC5E,YAAY,CAAC,EAAE,MAAM,CAAA;CACtB;AAED;;;;;;;GAOG;AACH,MAAM,WAAW,iBAAiB,CAAC,QAAQ,SAAS,UAAU;IAC5D,IAAI,EAAE,MAAM,CAAA;IACZ,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,WAAW,EAAE,MAAM,CAAA;IACnB,WAAW,EAAE,SAAS,CAAA;IACtB,YAAY,CAAC,EAAE,SAAS,CAAA;IACxB,WAAW,CAAC,EAAE,UAAU,CAAA;IACxB,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB,IAAI,EAAE,CACJ,IAAI,EAAE,gBAAgB,EACtB,OAAO,EAAE,QAAQ,KACd,OAAO,CAAC,SAAS,CAAC,GAAG,SAAS,CAAA;CACpC;AAED;;;;GAIG;AACH,MAAM,WAAW,eAAe,CAAC,QAAQ,SAAS,UAAU;IAC1D,0EAA0E;IAC1E,SAAS,CAAC,OAAO,CAAC,EAAE,QAAQ,GAAG,OAAO,CAAC,SAAS,EAAE,CAAC,GAAG,SAAS,EAAE,CAAA;IACjE;;;;OAIG;IACH,QAAQ,CACN,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,gBAAgB,EACtB,OAAO,EAAE,QAAQ,GAChB,OAAO,CAAC,SAAS,CAAC,CAAA;CACtB;AAED,MAAM,WAAW,uBAAuB,CAAC,QAAQ,SAAS,UAAU;IAClE,2EAA2E;IAC3E,UAAU,CAAC,EAAE;QACX,IAAI,EAAE,MAAM,CAAA;QACZ,OAAO,EAAE,MAAM,CAAA;KAChB,CAAA;IACD,uEAAuE;IACvE,OAAO,EAAE,CAAC,OAAO,EAAE,OAAO,KAAK,QAAQ,CAAA;CACxC;AAED;;;;;GAKG;AACH,qBAAa,eAAe,CAAC,QAAQ,SAAS,UAAU,CACtD,YAAW,eAAe,CAAC,QAAQ,CAAC;;gBAGxB,KAAK,EAAE,iBAAiB,CAAC,QAAQ,CAAC,EAAE;IAIhD,SAAS,IAAI,SAAS,EAAE;IAelB,QAAQ,CACZ,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,gBAAgB,EACtB,OAAO,EAAE,QAAQ,GAChB,OAAO,CAAC,SAAS,CAAC;CAOtB;AAED;;;;;;;;;GASG;AACH,qBAAa,gBAAgB,CAAC,QAAQ,SAAS,UAAU,GAAG,UAAU;;gBAMlE,KAAK,EAAE,eAAe,CAAC,QAAQ,CAAC,EAChC,gBAAgB,EACZ,CAAC,CAAC,OAAO,EAAE,OAAO,KAAK,QAAQ,CAAC,GAChC,uBAAuB,CAAC,QAAQ,CAAC;IAkBvC;;;;;OAKG;IACG,MAAM,CAAC,OAAO,EAAE,OAAO,GAAG,OAAO,CAAC,QAAQ,CAAC;CA8GlD;AAED;;;;GAIG;AACH,qBAAa,aAAc,SAAQ,KAAK;IACtC,IAAI,EAAE,MAAM,CAAA;gBAEA,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM;CAI1C;AAED;;;;GAIG;AACH,wBAAgB,aAAa,CAC3B,iBAAiB,EAAE,SAAS,EAC5B,OAAO,UAAQ,GACd,SAAS,CAaX"}

package/dist/types/ts/McpToolAuthorization.d.ts

@@ -1,22 +1,55 @@
+/**
+ * Authorization for MCP tool calls. A tool call succeeds on either of two
+ * paths (see docs/reference/mcp-gateway.md, "How a tool call is authorized"):
+ *
+ * 1. Direct grant — the caller's token holds the tool's `capability` on the
+ *    provider's source.
+ * 2. `useTools` delegation — the caller's token holds only the broad
+ *    `useTools` capability on its own source, and the provider's YAML both
+ *    declares the tool/capability pair and grants that capability to the
+ *    calling counterparty.
+ *
+ * Used by the daemon's MCP gateway and by agent tabs gating their own per-tab
+ * MCP servers.
+ */
 import type { Grant, YamlContent } from './YamlContent.ts';
+/** The capability that lets a caller invoke provider-declared MCP tools. */
 export declare const USE_TOOLS_CAPABILITY = "useTools";
+/** The subset of a verified `Token` that authorization decisions consume. */
 export interface McpCapabilityToken {
     hasCapability(source: string, capability: string): boolean;
     getCounterparty(): string;
     getSourceUrl(): URL;
     getSrc(): string;
 }
+/** One tool call to authorize: who is calling, and what they are calling. */
 export interface McpToolAuthorization {
+    /** The caller's verified token; `null` always denies. */
     token: McpCapabilityToken | null;
+    /** Source URL of the app providing the tool. */
     providerSource: string;
     toolName: string;
+    /** The capability the tool requires (its YAML `capability` field). */
     capability: string;
+    /** The provider app's YAML; required for the `useTools` delegation path. */
     providerYaml?: YamlContent;
 }
+/**
+ * Whether the call described by `authorization` is permitted, via direct
+ * grant or `useTools` delegation (see the module comment).
+ */
 export declare function hasMcpToolCapability(authorization: McpToolAuthorization): boolean;
+/** `token.hasCapability`, with verification errors treated as "no". */
 export declare function tokenHasCapability(token: {
     hasCapability(source: string, capability: string): boolean;
 }, source: string, capability: string): boolean;
+/** Whether the YAML `mcp.tools` block declares this tool/capability pair. */
 export declare function yamlDeclaresMcpToolCapability(yaml: Pick<YamlContent, 'mcp'>, toolName: string, capability: string): boolean;
+/**
+ * Whether a YAML `grant` block grants `capability` to the given counterparty
+ * and source. Counterparty and source keys are SQL-`LIKE` patterns (`%`/`_`);
+ * counterparties match case-insensitively. A grant entry is either an array of
+ * capabilities (any source) or a map of source pattern → capability list.
+ */
 export declare function yamlGrantsCapability(grant: Grant | undefined, counterparty: string, src: string, capability: string): boolean;
 //# sourceMappingURL=McpToolAuthorization.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"McpToolAuthorization.d.ts","sourceRoot":"","sources":["../../../ts/McpToolAuthorization.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,KAAK,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAA;AAE1D,eAAO,MAAM,oBAAoB,aAAa,CAAA;AAI9C,MAAM,WAAW,kBAAkB;IACjC,aAAa,CAAC,MAAM,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,OAAO,CAAA;IAC1D,eAAe,IAAI,MAAM,CAAA;IACzB,YAAY,IAAI,GAAG,CAAA;IACnB,MAAM,IAAI,MAAM,CAAA;CACjB;AAED,MAAM,WAAW,oBAAoB;IACnC,KAAK,EAAE,kBAAkB,GAAG,IAAI,CAAA;IAChC,cAAc,EAAE,MAAM,CAAA;IACtB,QAAQ,EAAE,MAAM,CAAA;IAChB,UAAU,EAAE,MAAM,CAAA;IAClB,YAAY,CAAC,EAAE,WAAW,CAAA;CAC3B;AAED,wBAAgB,oBAAoB,CAClC,aAAa,EAAE,oBAAoB,GAClC,OAAO,CAwBT;AAED,wBAAgB,kBAAkB,CAChC,KAAK,EAAE;IAAE,aAAa,CAAC,MAAM,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,OAAO,CAAA;CAAE,EACrE,MAAM,EAAE,MAAM,EACd,UAAU,EAAE,MAAM,GACjB,OAAO,CAMT;AAED,wBAAgB,6BAA6B,CAC3C,IAAI,EAAE,IAAI,CAAC,WAAW,EAAE,KAAK,CAAC,EAC9B,QAAQ,EAAE,MAAM,EAChB,UAAU,EAAE,MAAM,GACjB,OAAO,CAMT;AAED,wBAAgB,oBAAoB,CAClC,KAAK,EAAE,KAAK,GAAG,SAAS,EACxB,YAAY,EAAE,MAAM,EACpB,GAAG,EAAE,MAAM,EACX,UAAU,EAAE,MAAM,GACjB,OAAO,CA2BT"}
+{"version":3,"file":"McpToolAuthorization.d.ts","sourceRoot":"","sources":["../../../ts/McpToolAuthorization.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AACH,OAAO,KAAK,EAAE,KAAK,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAA;AAE1D,4EAA4E;AAC5E,eAAO,MAAM,oBAAoB,aAAa,CAAA;AAI9C,6EAA6E;AAC7E,MAAM,WAAW,kBAAkB;IACjC,aAAa,CAAC,MAAM,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,OAAO,CAAA;IAC1D,eAAe,IAAI,MAAM,CAAA;IACzB,YAAY,IAAI,GAAG,CAAA;IACnB,MAAM,IAAI,MAAM,CAAA;CACjB;AAED,6EAA6E;AAC7E,MAAM,WAAW,oBAAoB;IACnC,yDAAyD;IACzD,KAAK,EAAE,kBAAkB,GAAG,IAAI,CAAA;IAChC,gDAAgD;IAChD,cAAc,EAAE,MAAM,CAAA;IACtB,QAAQ,EAAE,MAAM,CAAA;IAChB,sEAAsE;IACtE,UAAU,EAAE,MAAM,CAAA;IAClB,4EAA4E;IAC5E,YAAY,CAAC,EAAE,WAAW,CAAA;CAC3B;AAED;;;GAGG;AACH,wBAAgB,oBAAoB,CAClC,aAAa,EAAE,oBAAoB,GAClC,OAAO,CAwBT;AAED,uEAAuE;AACvE,wBAAgB,kBAAkB,CAChC,KAAK,EAAE;IAAE,aAAa,CAAC,MAAM,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,OAAO,CAAA;CAAE,EACrE,MAAM,EAAE,MAAM,EACd,UAAU,EAAE,MAAM,GACjB,OAAO,CAMT;AAED,6EAA6E;AAC7E,wBAAgB,6BAA6B,CAC3C,IAAI,EAAE,IAAI,CAAC,WAAW,EAAE,KAAK,CAAC,EAC9B,QAAQ,EAAE,MAAM,EAChB,UAAU,EAAE,MAAM,GACjB,OAAO,CAMT;AAED;;;;;GAKG;AACH,wBAAgB,oBAAoB,CAClC,KAAK,EAAE,KAAK,GAAG,SAAS,EACxB,YAAY,EAAE,MAAM,EACpB,GAAG,EAAE,MAAM,EACX,UAAU,EAAE,MAAM,GACjB,OAAO,CA2BT"}

package/package.json

@@ -13,7 +13,7 @@
   "files": [
     "dist"
   ],
-  "version": "28.1.0",
+  "version": "28.2.1",
   "description": "Web Daemon",
   "module": "./dist/index.js",
   "keywords": [