appduct 0.9.0 → 0.11.0

package/dist/mcp/tool-mapping.js

@@ -1,143 +0,0 @@
-/**
- * Maps a `NamespacedTool` (daemon `ToolDescriptor` + resolved external name) onto the MCP SDK's
- * `Tool` wire shape (ARCHITECTURE.md §9/§7): `description` maps directly and `annotations` map
- * verbatim, while `input_schema`/`output_schema` are emitted only if the SDK's own `ToolSchema`
- * accepts them (issue #26) — a rejected `input_schema` is replaced with an empty, permissive
- * object schema and a rejected `output_schema` is dropped entirely. Either way the tool stays
- * listed and callable: one app-side schema MCP cannot represent must never take down the whole
- * `tools/list`.
- *
- * The gate is the SDK schema itself rather than a hand-rolled `type === "object"` check, because
- * MCP constrains more than the root type — `properties` must be a record of *object* subschemas
- * (the JSON Schema shorthand `properties: { a: true }` is rejected) and `required` must be an
- * array. Any of those makes a client reject the entire `tools/list` result, so the only safe
- * predicate is the one the client will actually apply.
- *
- * A tool whose effective policy is `"prompt"` (ARCHITECTURE.md §12) gets
- * `_meta["anthropic/requiresUserInteraction"] = true` — but only when the caller says to
- * (`emitRequiresUserInteractionFlag`), which `mcp/server.ts` decides is true only when the
- * connected client is known to enforce the flag (issue #14) *and* it hasn't already preferred the
- * elicitation channel instead (issue #10). Emitting the flag for a client that ignores it would
- * create a false sense of security; emitting it *and* using elicitation for the same tool would
- * arm two consent prompts for one call — so this function never decides that itself, only renders
- * the decision it's handed.
- */
-import { ToolSchema } from "@modelcontextprotocol/sdk/types.js";
-/** MCP requires `inputSchema.type === "object"`; an app that registered a tool without a schema
- * gets the most permissive possible one rather than an MCP-invalid `{}`. */
-const EMPTY_OBJECT_SCHEMA = { type: "object", additionalProperties: true };
-/**
- * Why the SDK's `ToolSchema` would reject `schema` in this slot, or `undefined` when it accepts
- * it. The probe wraps the schema in an otherwise-minimal valid `Tool` so the only thing under test
- * is the schema; the returned reason is the first issue, with the leading `inputSchema`/
- * `outputSchema` path segment stripped so the message reads from the app author's point of view.
- */
-const mcpSchemaRejection = (schema, slot) => {
-    const probe = slot === "input"
-        ? { name: "probe", inputSchema: schema }
-        : { name: "probe", inputSchema: EMPTY_OBJECT_SCHEMA, outputSchema: schema };
-    const parsed = ToolSchema.safeParse(probe);
-    if (parsed.success) {
-        return undefined;
-    }
-    const issue = parsed.error.issues[0];
-    if (!issue) {
-        return "it does not match MCP's tool schema";
-    }
-    const path = issue.path.slice(1).join(".");
-    return path.length > 0 ? `${path}: ${issue.message}` : issue.message;
-};
-/**
- * Whether `tools/list` will carry an `outputSchema` for this descriptor. `server.ts`'s success
- * path shares this predicate so the "did we advertise a schema?" and "must this result carry
- * `structuredContent`?" decisions can never disagree — a client demands the latter exactly when
- * it saw the former.
- */
-export const emitsMcpOutputSchema = (schema) => {
-    return schema !== undefined && mcpSchemaRejection(schema, "output") === undefined;
-};
-/** stderr only — stdout carries the MCP transport's protocol frames (ARCHITECTURE.md §9). */
-const defaultWarn = (message) => {
-    console.error(`appduct mcp: ${message}`);
-};
-/**
- * Upper bound on remembered notices. A key embeds the offending schema, and an app is free to
- * build a schema from live data (a `z.enum` over rows it just fetched), so an unbounded set would
- * grow with every distinct broken schema for the life of the process. Past the cap the oldest key
- * is evicted, which at worst re-prints a notice the operator has already seen.
- */
-const MAX_REMEMBERED_NOTICES = 256;
-/**
- * Builds a mapper with its own degradation-notice dedup, so nothing here is module state and no
- * reset hook has to be exported for tests: a server owns one mapper for its lifetime, and a test
- * owns one per case. `warn` defaults to stderr and exists so a test can capture notices without
- * spying on the console.
- *
- * Notices dedupe on session + tool name + the offending schema, because `tools/list` is
- * re-answered on every client request and on every `notifications/tools/list_changed` refresh. Two
- * devices exposing the same broken tool each get their own notice, and re-registering a tool with
- * a *differently* broken schema warns again; only the same problem on the same tool of the same
- * session stays quiet. The session's `selector` is the key rather than the namespaced `mcpName` so
- * the single↔multi session flip, which rewrites every `mcpName`, does not re-warn about tools
- * nothing changed about.
- */
-export const createMcpToolMapper = (warn = defaultWarn) => {
-    const warned = new Set();
-    const warnOnce = (tool, slot, schema, message) => {
-        const key = `${tool.selector}\u0000${tool.descriptor.name}\u0000${slot}\u0000${JSON.stringify(schema)}`;
-        if (warned.has(key)) {
-            return;
-        }
-        // A `Set` iterates in insertion order, so the first key is the oldest.
-        if (warned.size >= MAX_REMEMBERED_NOTICES) {
-            const oldest = warned.values().next();
-            if (!oldest.done) {
-                warned.delete(oldest.value);
-            }
-        }
-        warned.add(key);
-        warn(message);
-    };
-    const mapInputSchema = (tool) => {
-        const schema = tool.descriptor.input_schema;
-        if (schema === undefined) {
-            return EMPTY_OBJECT_SCHEMA;
-        }
-        const rejection = mcpSchemaRejection(schema, "input");
-        if (rejection === undefined) {
-            return schema;
-        }
-        warnOnce(tool, "input", schema, `Tool "${tool.mcpName}" declares an input schema MCP cannot accept (${rejection}); MCP tool ` +
-            "arguments are always an object, so the schema was replaced with a permissive empty object " +
-            "schema and agents cannot see the tool's real arguments. Wrap the input in an object schema.");
-        return EMPTY_OBJECT_SCHEMA;
-    };
-    const mapOutputSchema = (tool) => {
-        const schema = tool.descriptor.output_schema;
-        if (schema === undefined) {
-            return undefined;
-        }
-        const rejection = mcpSchemaRejection(schema, "output");
-        if (rejection === undefined) {
-            return schema;
-        }
-        warnOnce(tool, "output", schema, `Tool "${tool.mcpName}" declares an output schema MCP cannot accept (${rejection}); it was ` +
-            "dropped from tools/list, so agents get the result without a schema to validate it against. " +
-            "Wrap the output in an object schema to give agents a described, structured result.");
-        return undefined;
-    };
-    return (tool, emitRequiresUserInteractionFlag) => {
-        const { descriptor } = tool;
-        const requiresUserInteraction = tool.policy === "prompt" && emitRequiresUserInteractionFlag;
-        const outputSchema = mapOutputSchema(tool);
-        return {
-            name: tool.mcpName,
-            description: descriptor.description,
-            inputSchema: mapInputSchema(tool),
-            ...(outputSchema ? { outputSchema } : {}),
-            ...(descriptor.annotations ? { annotations: { ...descriptor.annotations } } : {}),
-            // Must be the JSON boolean `true` literal — any other value is ignored by the client.
-            ...(requiresUserInteraction ? { _meta: { "anthropic/requiresUserInteraction": true } } : {}),
-        };
-    };
-};

package/dist/mcp/tool-namespace.d.ts

@@ -1,40 +0,0 @@
-/**
- * Builds the effective MCP tool list from live daemon sessions and their tool registries
- * (ARCHITECTURE.md §9): exactly one live session exposes tools under their
- * own names; two or more namespace every tool as `<alias>__<name>` so names never collide across
- * devices.
- *
- * The `__` separator is unambiguous to split back apart even though a tool's own name
- * (`[a-zA-Z0-9_-]{1,64}`, `daemon/registry.ts`) may itself contain underscores: aliases
- * (`daemon/sessions.ts`'s `slugifyDeviceModel`/`dedupeAlias`) only ever contain lowercase
- * alphanumerics and hyphens, so the alias half of a namespaced name never itself contains `__` —
- * the first occurrence of `__` in a namespaced name is always the alias/tool-name boundary.
- */
-import type { EffectivePolicyDecision, SessionSummary, ToolDescriptor, ToolsListEntry } from "@appduct/shared";
-export declare const TOOL_NAMESPACE_SEPARATOR = "__";
-export type NamespacedTool = {
-    /** The name exposed to MCP clients: `descriptor.name` verbatim when exactly one session is live,
-     * else `<alias>__<name>`. */
-    mcpName: string;
-    /** The session alias `tools.call`'s `selector` should target for this tool. */
-    selector: string;
-    descriptor: ToolDescriptor;
-    /** The effective policy decision for this tool right now (ARCHITECTURE.md §12), as resolved by
-     * the daemon's `tools.list` — carried through so the MCP server can emit
-     * `_meta["anthropic/requiresUserInteraction"]` and set `consent` on `tools.call` without a
-     * second round trip (issue #14). */
-    policy: EffectivePolicyDecision;
-};
-/** Builds the namespaced (or not) tool list for the current set of live sessions. `toolsByAlias`
- * is looked up by `session.alias` (not `sessionId`) to match `tools.list`'s `selector` semantics. */
-export declare const buildNamespacedTools: (sessions: readonly SessionSummary[], toolsByAlias: ReadonlyMap<string, readonly ToolsListEntry[]>) => NamespacedTool[];
-export declare const findNamespacedTool: (tools: readonly NamespacedTool[], mcpName: string) => NamespacedTool | undefined;
-/** A stable, order-independent key used to detect whether the effective tool list actually
- * changed (name, target session, and the descriptor fields a client can see) — used to decide
- * whether to fire `notifications/tools/list_changed` rather than on every qualifying daemon event.
- *
- * `timeout_ms` is deliberately excluded: it never reaches the MCP `Tool` JSON (`tool-mapping.ts`),
- * so an app re-registering a tool with only a different deadline changes nothing a client could
- * observe, and telling it the list changed would just make it re-fetch an identical list. */
-export declare const namespacedToolsSnapshotKey: (tools: readonly NamespacedTool[]) => string;
-//# sourceMappingURL=tool-namespace.d.ts.map

package/dist/mcp/tool-namespace.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"tool-namespace.d.ts","sourceRoot":"","sources":["../../src/mcp/tool-namespace.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,KAAK,EAAE,uBAAuB,EAAE,cAAc,EAAE,cAAc,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAC;AAE/G,eAAO,MAAM,wBAAwB,OAAO,CAAC;AAE7C,MAAM,MAAM,cAAc,GAAG;IAC3B;iCAC6B;IAC7B,OAAO,EAAE,MAAM,CAAC;IAChB,+EAA+E;IAC/E,QAAQ,EAAE,MAAM,CAAC;IACjB,UAAU,EAAE,cAAc,CAAC;IAC3B;;;wCAGoC;IACpC,MAAM,EAAE,uBAAuB,CAAC;CACjC,CAAC;AAEF;qGACqG;AACrG,eAAO,MAAM,oBAAoB,GAC/B,UAAU,SAAS,cAAc,EAAE,EACnC,cAAc,WAAW,CAAC,MAAM,EAAE,SAAS,cAAc,EAAE,CAAC,KAC3D,cAAc,EA4BhB,CAAC;AAEF,eAAO,MAAM,kBAAkB,GAC7B,OAAO,SAAS,cAAc,EAAE,EAChC,SAAS,MAAM,KACd,cAAc,GAAG,SAEnB,CAAC;AAEF;;;;;;6FAM6F;AAC7F,eAAO,MAAM,0BAA0B,GAAI,OAAO,SAAS,cAAc,EAAE,KAAG,MAe7E,CAAC"}

package/dist/mcp/tool-namespace.js

@@ -1,65 +0,0 @@
-/**
- * Builds the effective MCP tool list from live daemon sessions and their tool registries
- * (ARCHITECTURE.md §9): exactly one live session exposes tools under their
- * own names; two or more namespace every tool as `<alias>__<name>` so names never collide across
- * devices.
- *
- * The `__` separator is unambiguous to split back apart even though a tool's own name
- * (`[a-zA-Z0-9_-]{1,64}`, `daemon/registry.ts`) may itself contain underscores: aliases
- * (`daemon/sessions.ts`'s `slugifyDeviceModel`/`dedupeAlias`) only ever contain lowercase
- * alphanumerics and hyphens, so the alias half of a namespaced name never itself contains `__` —
- * the first occurrence of `__` in a namespaced name is always the alias/tool-name boundary.
- */
-export const TOOL_NAMESPACE_SEPARATOR = "__";
-/** Builds the namespaced (or not) tool list for the current set of live sessions. `toolsByAlias`
- * is looked up by `session.alias` (not `sessionId`) to match `tools.list`'s `selector` semantics. */
-export const buildNamespacedTools = (sessions, toolsByAlias) => {
-    const namespaced = sessions.length > 1;
-    const tools = [];
-    for (const session of sessions) {
-        for (const entry of toolsByAlias.get(session.alias) ?? []) {
-            // Explicit pick (not a `{ policy, ...descriptor }` rest-spread) so a future non-descriptor
-            // field added to `ToolsListEntry` can't silently leak into `descriptor` and from there into
-            // the MCP tool surface and the snapshot key below.
-            const descriptor = {
-                name: entry.name,
-                description: entry.description,
-                input_schema: entry.input_schema,
-                output_schema: entry.output_schema,
-                annotations: entry.annotations,
-                timeout_ms: entry.timeout_ms,
-            };
-            tools.push({
-                mcpName: namespaced ? `${session.alias}${TOOL_NAMESPACE_SEPARATOR}${descriptor.name}` : descriptor.name,
-                selector: session.alias,
-                descriptor,
-                policy: entry.policy,
-            });
-        }
-    }
-    return tools;
-};
-export const findNamespacedTool = (tools, mcpName) => {
-    return tools.find((tool) => tool.mcpName === mcpName);
-};
-/** A stable, order-independent key used to detect whether the effective tool list actually
- * changed (name, target session, and the descriptor fields a client can see) — used to decide
- * whether to fire `notifications/tools/list_changed` rather than on every qualifying daemon event.
- *
- * `timeout_ms` is deliberately excluded: it never reaches the MCP `Tool` JSON (`tool-mapping.ts`),
- * so an app re-registering a tool with only a different deadline changes nothing a client could
- * observe, and telling it the list changed would just make it re-fetch an identical list. */
-export const namespacedToolsSnapshotKey = (tools) => {
-    const sorted = tools
-        .map((tool) => {
-        const { timeout_ms: _timeoutMs, ...clientVisibleDescriptor } = tool.descriptor;
-        return {
-            name: tool.mcpName,
-            selector: tool.selector,
-            descriptor: clientVisibleDescriptor,
-            policy: tool.policy,
-        };
-    })
-        .sort((a, b) => a.name.localeCompare(b.name));
-    return JSON.stringify(sorted);
-};

package/dist/native-scheme.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"native-scheme.d.ts","sourceRoot":"","sources":["../src/native-scheme.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AAQH,MAAM,MAAM,kBAAkB,GAC1B,gBAAgB,GAChB,kBAAkB,GAClB,gBAAgB,GAChB,iBAAiB,CAAC;AAEtB,MAAM,MAAM,uBAAuB,GAAG;IACpC,MAAM,EAAE,kBAAkB,CAAC;IAC3B,MAAM,EAAE,MAAM,CAAC;IACf,mGAAmG;IACnG,MAAM,EAAE,MAAM,CAAC;CAChB,CAAC;AAEF,MAAM,MAAM,qBAAqB,GAAG;IAClC,mDAAmD;IACnD,MAAM,CAAC,EAAE,uBAAuB,CAAC;IACjC;iGAC6F;IAC7F,KAAK,EAAE,MAAM,EAAE,CAAC;CACjB,CAAC;AAihBF;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,oBAAoB,GAAU,MAAM,MAAM,KAAG,OAAO,CAAC,qBAAqB,CA4BtF,CAAC"}