llui-agent 0.0.2 → 0.0.4

package/README.md

@@ -1,6 +1,6 @@
 # llui-agent
 
-MCP bridge for the [LLui Agent Protocol](../../docs/superpowers/specs/2026-04-19-llui-agent-design.md). Install once into your LLM client; paste a `/llui-connect <url> <token>` into any Claude conversation to bind it to a running LLui app.
+MCP bridge for the [LLui Agent Protocol](../../docs/superpowers/specs/2026-04-19-llui-agent-design.md). Install once into your LLM client; paste the connect snippet from any LLui app to bind the conversation to that app.
 
 ## Install (Claude Desktop)
 
@@ -17,18 +17,58 @@ Edit `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) o
 }
 ```
 
-Restart Claude Desktop. The 11 LLui tools (`llui_connect_session`, `llui_disconnect_session`, `describe_app`, `get_state`, `list_actions`, `send_message`, `get_confirm_result`, `wait_for_change`, `query_dom`, `describe_visible_content`, `describe_context`) and the `/llui-connect` prompt now appear in Claude.
+Restart Claude Desktop. The 11 LLui tools (`llui_connect_session`, `llui_disconnect_session`, `describe_app`, `get_state`, `list_actions`, `send_message`, `get_confirm_result`, `wait_for_change`, `query_dom`, `describe_visible_content`, `describe_context`) now appear. Desktop exposes the bundled `llui-connect` MCP prompt as a slash command — see "Slash shortcuts" below.
+
+## Install (Claude Code CLI)
+
+```bash
+claude mcp add --transport stdio llui -- npx -y llui-agent
+```
+
+For local development against unpublished bridge code, point at the built CLI instead:
+
+```bash
+claude mcp add --transport stdio llui -- node /absolute/path/to/llui/packages/agent-bridge/dist/cli.js
+```
+
+Run `/mcp` inside CC to confirm the server connected (or start a new session). The same 11 tools become available.
+
+> **If you run CC in auto mode** (`permissions.defaultMode: "auto"` in `~/.claude/settings.json`), the auto-classifier silently rejects unrecognized MCP tools the first time they're called — Claude reports "tool was rejected" but no UI prompt is shown. Add the bridge's tools to your allowlist once so subsequent calls go through:
+>
+> ```jsonc
+> // ~/.claude/settings.json
+> {
+>   "permissions": {
+>     "allow": [
+>       "mcp__llui__*", // replace `llui` with the name you used in `claude mcp add`
+>     ],
+>   },
+> }
+> ```
+>
+> Users on `defaultMode: "default"` or `"ask"` instead get a permission prompt on the first call and don't need this allowlist entry.
 
 ## Use
 
-Open any LLui app that's built with `@llui/agent/client`. Click "Connect with Claude" in the app. Copy the generated `/llui-connect <url> <token>` string into Claude. Claude will now talk to that specific app instance.
+Open any LLui app built with `@llui/agent/client`. Click "Connect with Claude" in the app and copy the generated snippet. Paste it into Claude — the snippet is a natural-language instruction containing the URL and token. Claude reads it and calls `llui_connect_session` to bind. The same snippet works in Desktop and CC.
+
+Each Claude chat is bound to ONE LLui app at a time. To switch, ask Claude to call `llui_disconnect_session` and paste a new snippet.
+
+## Slash shortcuts (optional)
+
+The bridge registers an MCP prompt named `llui-connect`. Both clients surface it as a slash command, but the namespacing differs:
+
+| Client          | Shortcut                                          |
+| --------------- | ------------------------------------------------- |
+| Claude Desktop  | `/llui-connect <url> <token>`                     |
+| Claude Code CLI | `/mcp__<server-name>__llui-connect <url> <token>` |
 
-Each Claude chat is bound to ONE LLui app at a time. To switch, run `/llui-disconnect` or start a new chat.
+The `<server-name>` in CC is whatever you passed to `claude mcp add` — `llui` if you used the command above. Power-user shortcut only; the natural-language snippet from the app works the same in either client and doesn't depend on the server-name choice.
 
 ## How it works
 
-1. Your LLui app mints a per-browser-session token and shows a `/llui-connect` string.
-2. You paste into Claude — the bridge records `{url, token}` for this chat.
+1. Your LLui app mints a per-browser-session token and renders a connect snippet — a one-line instruction containing the LAP URL and the bearer token.
+2. You paste into Claude — Claude reads the snippet, calls `llui_connect_session`, and the bridge records `{url, token}` for this chat.
 3. The bridge pings `POST {url}/describe` to validate and cache the app's schema.
 4. Subsequent Claude tool calls (`get_state`, `send_message`, etc.) forward to `{url}/<path>` with your token as a Bearer.
 5. Sensitive actions (`@requiresConfirm` in the app's code) route through a confirmation prompt that only the user can approve.

package/dist/bridge.d.ts

@@ -1,4 +1,4 @@
-import { Server as McpServer } from '@modelcontextprotocol/sdk/server/index.js';
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { BindingMap } from './binding.js';
 export type BridgeDeps = {
     /** Injectable for tests. */
@@ -10,5 +10,18 @@ export type BridgeDeps = {
     /** Package version — set from package.json at boot. */
     version: string;
 };
+/**
+ * Builds the bridge's MCP server using the high-level `McpServer`
+ * registrars. Each tool's Zod schema (declared once in `tools.ts`)
+ * drives both runtime input validation and the JSON Schema published
+ * to `tools/list` — eliminating the hand-written-schema-vs-handler
+ * drift that the low-level `setRequestHandler` pattern is prone to.
+ *
+ * Forwarded tools (`kind: 'forward'`) share a generic forwarder that
+ * looks up the binding, dispatches to LAP, and caches description
+ * payloads where applicable. The two meta tools
+ * (`llui_connect_session`, `llui_disconnect_session`) carry custom
+ * handlers that mutate the BindingMap directly.
+ */
 export declare function createBridgeServer(deps: BridgeDeps): McpServer;
 //# sourceMappingURL=bridge.d.ts.map

package/dist/bridge.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"bridge.d.ts","sourceRoot":"","sources":["../src/bridge.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,IAAI,SAAS,EAAE,MAAM,2CAA2C,CAAA;AAQ/E,OAAO,EAAE,UAAU,EAAE,MAAM,cAAc,CAAA;AAKzC,MAAM,MAAM,UAAU,GAAG;IACvB,4BAA4B;IAC5B,KAAK,CAAC,EAAE,OAAO,KAAK,CAAA;IACpB,0GAA0G;IAC1G,SAAS,EAAE,MAAM,CAAA;IACjB,uDAAuD;IACvD,QAAQ,EAAE,UAAU,CAAA;IACpB,uDAAuD;IACvD,OAAO,EAAE,MAAM,CAAA;CAChB,CAAA;AAED,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,UAAU,GAAG,SAAS,CAgF9D"}
+{"version":3,"file":"bridge.d.ts","sourceRoot":"","sources":["../src/bridge.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAA;AAGnE,OAAO,EAAE,UAAU,EAAE,MAAM,cAAc,CAAA;AAKzC,MAAM,MAAM,UAAU,GAAG;IACvB,4BAA4B;IAC5B,KAAK,CAAC,EAAE,OAAO,KAAK,CAAA;IACpB,0GAA0G;IAC1G,SAAS,EAAE,MAAM,CAAA;IACjB,uDAAuD;IACvD,QAAQ,EAAE,UAAU,CAAA;IACpB,uDAAuD;IACvD,OAAO,EAAE,MAAM,CAAA;CAChB,CAAA;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,UAAU,GAAG,SAAS,CAa9D"}

package/dist/bridge.js

@@ -1,75 +1,118 @@
-import { Server as McpServer } from '@modelcontextprotocol/sdk/server/index.js';
-import { CallToolRequestSchema, ListToolsRequestSchema, } from '@modelcontextprotocol/sdk/types.js';
-import { TOOLS, TOOL_TO_LAP_PATH } from './tools.js';
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { TOOL_DESCRIPTORS } from './tools.js';
 import { BindingMap } from './binding.js';
 import { forwardLap } from './forwarder.js';
 import { registerPrompts } from './prompts.js';
+/**
+ * Builds the bridge's MCP server using the high-level `McpServer`
+ * registrars. Each tool's Zod schema (declared once in `tools.ts`)
+ * drives both runtime input validation and the JSON Schema published
+ * to `tools/list` — eliminating the hand-written-schema-vs-handler
+ * drift that the low-level `setRequestHandler` pattern is prone to.
+ *
+ * Forwarded tools (`kind: 'forward'`) share a generic forwarder that
+ * looks up the binding, dispatches to LAP, and caches description
+ * payloads where applicable. The two meta tools
+ * (`llui_connect_session`, `llui_disconnect_session`) carry custom
+ * handlers that mutate the BindingMap directly.
+ */
 export function createBridgeServer(deps) {
     const server = new McpServer({ name: 'llui-agent', version: deps.version }, { capabilities: { tools: {}, prompts: {} } });
-    server.setRequestHandler(ListToolsRequestSchema, async () => ({
-        tools: TOOLS,
-    }));
-    server.setRequestHandler(CallToolRequestSchema, async (req) => {
-        const { name, arguments: args = {} } = req.params;
-        if (name === 'llui_connect_session') {
-            const { url, token } = args;
-            if (typeof url !== 'string' || typeof token !== 'string') {
-                return errorResult('invalid: url and token required');
-            }
-            deps.bindings.set(deps.sessionId, url, token);
-            // Validate immediately by pinging /describe
-            const res = await forwardLap(url, token, '/describe', {}, { fetch: deps.fetch });
-            if (!res.ok) {
-                deps.bindings.clear(deps.sessionId);
-                return errorResult(`connect failed: ${JSON.stringify(res.error)}`);
-            }
-            const describe = res.body;
-            deps.bindings.setDescribe(deps.sessionId, describe);
-            return okResult({
-                appName: describe.name,
-                appVersion: describe.version,
-                status: 'connected',
-            });
+    for (const desc of TOOL_DESCRIPTORS) {
+        registerToolDescriptor(server, deps, desc);
+    }
+    registerPrompts(server);
+    return server;
+}
+function registerToolDescriptor(server, deps, desc) {
+    if (desc.kind === 'meta') {
+        if (desc.name === 'llui_connect_session') {
+            registerConnectSession(server, deps, desc);
         }
-        if (name === 'llui_disconnect_session') {
+        else if (desc.name === 'llui_disconnect_session') {
+            registerDisconnectSession(server, deps, desc);
+        }
+        return;
+    }
+    registerForwardedTool(server, deps, desc);
+}
+function registerConnectSession(server, deps, desc) {
+    server.registerTool(desc.name, { description: desc.description, inputSchema: desc.schema.shape }, async (args) => {
+        const { url, token } = args;
+        deps.bindings.set(deps.sessionId, url, token);
+        // Validate AND prefetch the bootstrap bundle in one call.
+        // /observe returns {state, actions, description, context} —
+        // exactly what the LLM needs to start acting. Without this,
+        // Claude has to follow up with `observe` to get anything
+        // usable, costing round-trips and creating a window where
+        // the connect tool's "you are now connected" result is the
+        // entire context the LLM has to reason about.
+        const res = await forwardLap(url, token, '/observe', {}, { fetch: deps.fetch });
+        if (!res.ok) {
             deps.bindings.clear(deps.sessionId);
-            return okResult({ status: 'disconnected' });
+            return errorResult(`connect failed: ${JSON.stringify(res.error)}`);
         }
-        // Forwarded tools
+        const observe = res.body;
+        deps.bindings.setDescribe(deps.sessionId, observe.description);
+        return okResult({
+            status: 'connected',
+            appName: observe.description.name,
+            appVersion: observe.description.version,
+            // Full observe payload — same shape the `observe` tool returns —
+            // so a `describe_app` / `get_state` / `list_actions` /
+            // `describe_context` follow-up is unnecessary on the first turn.
+            state: observe.state,
+            actions: observe.actions,
+            description: observe.description,
+            context: observe.context,
+        });
+    });
+}
+function registerDisconnectSession(server, deps, desc) {
+    server.registerTool(desc.name, { description: desc.description, inputSchema: desc.schema.shape }, async () => {
+        deps.bindings.clear(deps.sessionId);
+        return okResult({ status: 'disconnected' });
+    });
+}
+function registerForwardedTool(server, deps, desc) {
+    server.registerTool(desc.name, { description: desc.description, inputSchema: desc.schema.shape }, async (args) => {
         const binding = deps.bindings.get(deps.sessionId);
         if (!binding) {
-            return errorResult('not bound — ask the user to run /llui-connect <url> <token> first');
+            return errorResult('not bound — ask the user to copy the connect snippet from the LLui app, ' +
+                'or call `llui_connect_session` with the url and token they provide. ' +
+                '(In Claude Desktop only, the snippet is also available as the slash command `/llui-connect`.)');
         }
-        // describe_app can serve from cache
-        if (name === 'describe_app' && binding.describe) {
+        // describe_app can serve from cache when one is available.
+        if (desc.name === 'describe_app' && binding.describe) {
             return okResult(binding.describe);
         }
-        const lapPath = TOOL_TO_LAP_PATH[name];
-        if (!lapPath)
-            return errorResult(`unknown tool: ${name}`);
-        const res = await forwardLap(binding.url, binding.token, lapPath, args, { fetch: deps.fetch });
+        const res = await forwardLap(binding.url, binding.token, desc.lapPath, args ?? {}, {
+            fetch: deps.fetch,
+        });
         if (!res.ok) {
-            return errorResult(`LAP ${lapPath} failed: status=${res.status} ${JSON.stringify(res.error)}`);
+            return errorResult(`LAP ${desc.lapPath} failed: status=${res.status} ${JSON.stringify(res.error)}`);
         }
-        // Cache describe_app responses after the first call too
-        if (name === 'describe_app') {
+        // Cache describe_app responses after the first call too.
+        if (desc.name === 'describe_app') {
             deps.bindings.setDescribe(deps.sessionId, res.body);
         }
         // observe returns description on every call; cache it so a later
-        // describe_app hit can serve from cache and short-circuit the LAP
-        // round-trip.
-        if (name === 'observe') {
+        // describe_app can short-circuit the LAP round-trip.
+        if (desc.name === 'observe') {
             const obs = res.body;
             if (obs?.description)
                 deps.bindings.setDescribe(deps.sessionId, obs.description);
         }
         return okResult(res.body);
     });
-    registerPrompts(server);
-    return server;
 }
 function okResult(body) {
+    // structuredContent is what current Claude clients (Desktop + CC)
+    // consume preferentially when present — typed JSON instead of a
+    // stringified blob. The `content` array stays as a `text` fallback
+    // so older clients still see something sensible.
     return {
+        structuredContent: body,
         content: [{ type: 'text', text: JSON.stringify(body) }],
     };
 }

package/dist/bridge.js.map

@@ -1 +1 @@
-{"version":3,"file":"bridge.js","sourceRoot":"","sources":["../src/bridge.ts"],"names":[],"mappings":"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","sourcesContent":["import { Server as McpServer } from '@modelcontextprotocol/sdk/server/index.js'\nimport {\n  CallToolRequestSchema,\n  ListToolsRequestSchema,\n  type CallToolResult,\n  type ListToolsResult,\n} from '@modelcontextprotocol/sdk/types.js'\nimport { TOOLS, TOOL_TO_LAP_PATH } from './tools.js'\nimport { BindingMap } from './binding.js'\nimport { forwardLap } from './forwarder.js'\nimport type { LapDescribeResponse, LapObserveResponse } from '@llui/agent/protocol'\nimport { registerPrompts } from './prompts.js'\n\nexport type BridgeDeps = {\n  /** Injectable for tests. */\n  fetch?: typeof fetch\n  /** MCP session ID for this client. In stdio mode there's one session; derive from the Server instance. */\n  sessionId: string\n  /** Shared binding map (one BindingMap per process). */\n  bindings: BindingMap\n  /** Package version — set from package.json at boot. */\n  version: string\n}\n\nexport function createBridgeServer(deps: BridgeDeps): McpServer {\n  const server = new McpServer(\n    { name: 'llui-agent', version: deps.version },\n    { capabilities: { tools: {}, prompts: {} } },\n  )\n\n  server.setRequestHandler(\n    ListToolsRequestSchema,\n    async (): Promise<ListToolsResult> => ({\n      tools: TOOLS,\n    }),\n  )\n\n  server.setRequestHandler(CallToolRequestSchema, async (req): Promise<CallToolResult> => {\n    const { name, arguments: args = {} } = req.params\n\n    if (name === 'llui_connect_session') {\n      const { url, token } = args as { url?: string; token?: string }\n      if (typeof url !== 'string' || typeof token !== 'string') {\n        return errorResult('invalid: url and token required')\n      }\n      deps.bindings.set(deps.sessionId, url, token)\n      // Validate immediately by pinging /describe\n      const res = await forwardLap(url, token, '/describe', {}, { fetch: deps.fetch })\n      if (!res.ok) {\n        deps.bindings.clear(deps.sessionId)\n        return errorResult(`connect failed: ${JSON.stringify(res.error)}`)\n      }\n      const describe = res.body as LapDescribeResponse\n      deps.bindings.setDescribe(deps.sessionId, describe)\n      return okResult({\n        appName: describe.name,\n        appVersion: describe.version,\n        status: 'connected',\n      })\n    }\n\n    if (name === 'llui_disconnect_session') {\n      deps.bindings.clear(deps.sessionId)\n      return okResult({ status: 'disconnected' })\n    }\n\n    // Forwarded tools\n    const binding = deps.bindings.get(deps.sessionId)\n    if (!binding) {\n      return errorResult('not bound — ask the user to run /llui-connect <url> <token> first')\n    }\n\n    // describe_app can serve from cache\n    if (name === 'describe_app' && binding.describe) {\n      return okResult(binding.describe)\n    }\n\n    const lapPath = TOOL_TO_LAP_PATH[name]\n    if (!lapPath) return errorResult(`unknown tool: ${name}`)\n\n    const res = await forwardLap(binding.url, binding.token, lapPath, args, { fetch: deps.fetch })\n    if (!res.ok) {\n      return errorResult(`LAP ${lapPath} failed: status=${res.status} ${JSON.stringify(res.error)}`)\n    }\n\n    // Cache describe_app responses after the first call too\n    if (name === 'describe_app') {\n      deps.bindings.setDescribe(deps.sessionId, res.body as LapDescribeResponse)\n    }\n\n    // observe returns description on every call; cache it so a later\n    // describe_app hit can serve from cache and short-circuit the LAP\n    // round-trip.\n    if (name === 'observe') {\n      const obs = res.body as LapObserveResponse\n      if (obs?.description) deps.bindings.setDescribe(deps.sessionId, obs.description)\n    }\n\n    return okResult(res.body)\n  })\n\n  registerPrompts(server)\n\n  return server\n}\n\nfunction okResult(body: unknown): CallToolResult {\n  return {\n    content: [{ type: 'text', text: JSON.stringify(body) }],\n  }\n}\n\nfunction errorResult(msg: string): CallToolResult {\n  return {\n    content: [{ type: 'text', text: msg }],\n    isError: true,\n  }\n}\n"]}
+{"version":3,"file":"bridge.js","sourceRoot":"","sources":["../src/bridge.ts"],"names":[],"mappings":"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","sourcesContent":["import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js'\nimport type { CallToolResult } from '@modelcontextprotocol/sdk/types.js'\nimport { TOOL_DESCRIPTORS, type ToolDescriptor } from './tools.js'\nimport { BindingMap } from './binding.js'\nimport { forwardLap } from './forwarder.js'\nimport type { LapDescribeResponse, LapObserveResponse } from '@llui/agent/protocol'\nimport { registerPrompts } from './prompts.js'\n\nexport type BridgeDeps = {\n  /** Injectable for tests. */\n  fetch?: typeof fetch\n  /** MCP session ID for this client. In stdio mode there's one session; derive from the Server instance. */\n  sessionId: string\n  /** Shared binding map (one BindingMap per process). */\n  bindings: BindingMap\n  /** Package version — set from package.json at boot. */\n  version: string\n}\n\n/**\n * Builds the bridge's MCP server using the high-level `McpServer`\n * registrars. Each tool's Zod schema (declared once in `tools.ts`)\n * drives both runtime input validation and the JSON Schema published\n * to `tools/list` — eliminating the hand-written-schema-vs-handler\n * drift that the low-level `setRequestHandler` pattern is prone to.\n *\n * Forwarded tools (`kind: 'forward'`) share a generic forwarder that\n * looks up the binding, dispatches to LAP, and caches description\n * payloads where applicable. The two meta tools\n * (`llui_connect_session`, `llui_disconnect_session`) carry custom\n * handlers that mutate the BindingMap directly.\n */\nexport function createBridgeServer(deps: BridgeDeps): McpServer {\n  const server = new McpServer(\n    { name: 'llui-agent', version: deps.version },\n    { capabilities: { tools: {}, prompts: {} } },\n  )\n\n  for (const desc of TOOL_DESCRIPTORS) {\n    registerToolDescriptor(server, deps, desc)\n  }\n\n  registerPrompts(server)\n\n  return server\n}\n\nfunction registerToolDescriptor(server: McpServer, deps: BridgeDeps, desc: ToolDescriptor): void {\n  if (desc.kind === 'meta') {\n    if (desc.name === 'llui_connect_session') {\n      registerConnectSession(server, deps, desc)\n    } else if (desc.name === 'llui_disconnect_session') {\n      registerDisconnectSession(server, deps, desc)\n    }\n    return\n  }\n  registerForwardedTool(server, deps, desc)\n}\n\nfunction registerConnectSession(server: McpServer, deps: BridgeDeps, desc: ToolDescriptor): void {\n  server.registerTool(\n    desc.name,\n    { description: desc.description, inputSchema: desc.schema.shape },\n    async (args) => {\n      const { url, token } = args as { url: string; token: string }\n      deps.bindings.set(deps.sessionId, url, token)\n      // Validate AND prefetch the bootstrap bundle in one call.\n      // /observe returns {state, actions, description, context} —\n      // exactly what the LLM needs to start acting. Without this,\n      // Claude has to follow up with `observe` to get anything\n      // usable, costing round-trips and creating a window where\n      // the connect tool's \"you are now connected\" result is the\n      // entire context the LLM has to reason about.\n      const res = await forwardLap(url, token, '/observe', {}, { fetch: deps.fetch })\n      if (!res.ok) {\n        deps.bindings.clear(deps.sessionId)\n        return errorResult(`connect failed: ${JSON.stringify(res.error)}`)\n      }\n      const observe = res.body as LapObserveResponse\n      deps.bindings.setDescribe(deps.sessionId, observe.description)\n      return okResult({\n        status: 'connected',\n        appName: observe.description.name,\n        appVersion: observe.description.version,\n        // Full observe payload — same shape the `observe` tool returns —\n        // so a `describe_app` / `get_state` / `list_actions` /\n        // `describe_context` follow-up is unnecessary on the first turn.\n        state: observe.state,\n        actions: observe.actions,\n        description: observe.description,\n        context: observe.context,\n      })\n    },\n  )\n}\n\nfunction registerDisconnectSession(\n  server: McpServer,\n  deps: BridgeDeps,\n  desc: ToolDescriptor,\n): void {\n  server.registerTool(\n    desc.name,\n    { description: desc.description, inputSchema: desc.schema.shape },\n    async () => {\n      deps.bindings.clear(deps.sessionId)\n      return okResult({ status: 'disconnected' })\n    },\n  )\n}\n\nfunction registerForwardedTool(\n  server: McpServer,\n  deps: BridgeDeps,\n  desc: Extract<ToolDescriptor, { kind: 'forward' }>,\n): void {\n  server.registerTool(\n    desc.name,\n    { description: desc.description, inputSchema: desc.schema.shape },\n    async (args) => {\n      const binding = deps.bindings.get(deps.sessionId)\n      if (!binding) {\n        return errorResult(\n          'not bound — ask the user to copy the connect snippet from the LLui app, ' +\n            'or call `llui_connect_session` with the url and token they provide. ' +\n            '(In Claude Desktop only, the snippet is also available as the slash command `/llui-connect`.)',\n        )\n      }\n\n      // describe_app can serve from cache when one is available.\n      if (desc.name === 'describe_app' && binding.describe) {\n        return okResult(binding.describe)\n      }\n\n      const res = await forwardLap(binding.url, binding.token, desc.lapPath, args ?? {}, {\n        fetch: deps.fetch,\n      })\n      if (!res.ok) {\n        return errorResult(\n          `LAP ${desc.lapPath} failed: status=${res.status} ${JSON.stringify(res.error)}`,\n        )\n      }\n\n      // Cache describe_app responses after the first call too.\n      if (desc.name === 'describe_app') {\n        deps.bindings.setDescribe(deps.sessionId, res.body as LapDescribeResponse)\n      }\n\n      // observe returns description on every call; cache it so a later\n      // describe_app can short-circuit the LAP round-trip.\n      if (desc.name === 'observe') {\n        const obs = res.body as LapObserveResponse\n        if (obs?.description) deps.bindings.setDescribe(deps.sessionId, obs.description)\n      }\n\n      return okResult(res.body)\n    },\n  )\n}\n\nfunction okResult(body: unknown): CallToolResult {\n  // structuredContent is what current Claude clients (Desktop + CC)\n  // consume preferentially when present — typed JSON instead of a\n  // stringified blob. The `content` array stays as a `text` fallback\n  // so older clients still see something sensible.\n  return {\n    structuredContent: body as Record<string, unknown>,\n    content: [{ type: 'text', text: JSON.stringify(body) }],\n  }\n}\n\nfunction errorResult(msg: string): CallToolResult {\n  return {\n    content: [{ type: 'text', text: msg }],\n    isError: true,\n  }\n}\n"]}

package/dist/prompts.d.ts

@@ -1,3 +1,11 @@
-import type { Server as McpServer } from '@modelcontextprotocol/sdk/server/index.js';
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+/**
+ * Registers the bundled `llui-connect` MCP prompt. Both Claude Desktop
+ * and Claude Code surface it as a slash command (Desktop:
+ * `/llui-connect <url> <token>`; CC: `/mcp__<server>__llui-connect …`).
+ * The prompt body Claude sees is the same natural-language instruction
+ * the LLui app shows in its connect snippet — so pasting either form
+ * lands the same `llui_connect_session` tool call.
+ */
 export declare function registerPrompts(server: McpServer): void;
 //# sourceMappingURL=prompts.d.ts.map

package/dist/prompts.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"prompts.d.ts","sourceRoot":"","sources":["../src/prompts.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,IAAI,SAAS,EAAE,MAAM,2CAA2C,CAAA;AAQpF,wBAAgB,eAAe,CAAC,MAAM,EAAE,SAAS,GAAG,IAAI,CAuCvD"}
+{"version":3,"file":"prompts.d.ts","sourceRoot":"","sources":["../src/prompts.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAA;AAGxE;;;;;;;GAOG;AACH,wBAAgB,eAAe,CAAC,MAAM,EAAE,SAAS,GAAG,IAAI,CA0BvD"}

package/dist/prompts.js

@@ -1,36 +1,31 @@
-import { GetPromptRequestSchema, ListPromptsRequestSchema, } from '@modelcontextprotocol/sdk/types.js';
+import { z } from 'zod';
+/**
+ * Registers the bundled `llui-connect` MCP prompt. Both Claude Desktop
+ * and Claude Code surface it as a slash command (Desktop:
+ * `/llui-connect <url> <token>`; CC: `/mcp__<server>__llui-connect …`).
+ * The prompt body Claude sees is the same natural-language instruction
+ * the LLui app shows in its connect snippet — so pasting either form
+ * lands the same `llui_connect_session` tool call.
+ */
 export function registerPrompts(server) {
-    server.setRequestHandler(ListPromptsRequestSchema, async () => ({
-        prompts: [
+    server.registerPrompt('llui-connect', {
+        description: 'Bind this Claude conversation to an LLui app. Paste the URL and token the app showed you.',
+        argsSchema: {
+            url: z.string().describe('LAP base URL'),
+            token: z.string().describe('Bearer token'),
+        },
+    }, ({ url, token }) => ({
+        description: `Bind to LLui app at ${url}`,
+        messages: [
             {
-                name: 'llui-connect',
-                description: 'Bind this Claude conversation to an LLui app. Paste the URL and token the app showed you.',
-                arguments: [
-                    { name: 'url', description: 'LAP base URL', required: true },
-                    { name: 'token', description: 'Bearer token', required: true },
-                ],
+                role: 'user',
+                content: {
+                    type: 'text',
+                    text: `Please connect this conversation to the LLui app at ${url}. ` +
+                        `Call llui_connect_session with url=${JSON.stringify(url)} and token=${JSON.stringify(token)}.`,
+                },
             },
         ],
     }));
-    server.setRequestHandler(GetPromptRequestSchema, async (req) => {
-        if (req.params.name !== 'llui-connect') {
-            throw new Error(`unknown prompt: ${req.params.name}`);
-        }
-        const url = req.params.arguments?.['url'] ?? '';
-        const token = req.params.arguments?.['token'] ?? '';
-        return {
-            description: `Bind to LLui app at ${url}`,
-            messages: [
-                {
-                    role: 'user',
-                    content: {
-                        type: 'text',
-                        text: `Please connect this conversation to the LLui app at ${url}. ` +
-                            `Call llui_connect_session with url=${JSON.stringify(url)} and token=${JSON.stringify(token)}.`,
-                    },
-                },
-            ],
-        };
-    });
 }
 //# sourceMappingURL=prompts.js.map

package/dist/prompts.js.map

@@ -1 +1 @@
-{"version":3,"file":"prompts.js","sourceRoot":"","sources":["../src/prompts.ts"],"names":[],"mappings":"AACA,OAAO,EACL,sBAAsB,EACtB,wBAAwB,GAGzB,MAAM,oCAAoC,CAAA;AAE3C,MAAM,UAAU,eAAe,CAAC,MAAiB;IAC/C,MAAM,CAAC,iBAAiB,CACtB,wBAAwB,EACxB,KAAK,IAAgC,EAAE,CAAC,CAAC;QACvC,OAAO,EAAE;YACP;gBACE,IAAI,EAAE,cAAc;gBACpB,WAAW,EACT,2FAA2F;gBAC7F,SAAS,EAAE;oBACT,EAAE,IAAI,EAAE,KAAK,EAAE,WAAW,EAAE,cAAc,EAAE,QAAQ,EAAE,IAAI,EAAE;oBAC5D,EAAE,IAAI,EAAE,OAAO,EAAE,WAAW,EAAE,cAAc,EAAE,QAAQ,EAAE,IAAI,EAAE;iBAC/D;aACF;SACF;KACF,CAAC,CACH,CAAA;IAED,MAAM,CAAC,iBAAiB,CAAC,sBAAsB,EAAE,KAAK,EAAE,GAAG,EAA4B,EAAE;QACvF,IAAI,GAAG,CAAC,MAAM,CAAC,IAAI,KAAK,cAAc,EAAE,CAAC;YACvC,MAAM,IAAI,KAAK,CAAC,mBAAmB,GAAG,CAAC,MAAM,CAAC,IAAI,EAAE,CAAC,CAAA;QACvD,CAAC;QACD,MAAM,GAAG,GAAG,GAAG,CAAC,MAAM,CAAC,SAAS,EAAE,CAAC,KAAK,CAAC,IAAI,EAAE,CAAA;QAC/C,MAAM,KAAK,GAAG,GAAG,CAAC,MAAM,CAAC,SAAS,EAAE,CAAC,OAAO,CAAC,IAAI,EAAE,CAAA;QACnD,OAAO;YACL,WAAW,EAAE,uBAAuB,GAAG,EAAE;YACzC,QAAQ,EAAE;gBACR;oBACE,IAAI,EAAE,MAAM;oBACZ,OAAO,EAAE;wBACP,IAAI,EAAE,MAAM;wBACZ,IAAI,EACF,uDAAuD,GAAG,IAAI;4BAC9D,sCAAsC,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,cAAc,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,GAAG;qBAClG;iBACF;aACF;SACF,CAAA;IACH,CAAC,CAAC,CAAA;AACJ,CAAC","sourcesContent":["import type { Server as McpServer } from '@modelcontextprotocol/sdk/server/index.js'\nimport {\n  GetPromptRequestSchema,\n  ListPromptsRequestSchema,\n  type ListPromptsResult,\n  type GetPromptResult,\n} from '@modelcontextprotocol/sdk/types.js'\n\nexport function registerPrompts(server: McpServer): void {\n  server.setRequestHandler(\n    ListPromptsRequestSchema,\n    async (): Promise<ListPromptsResult> => ({\n      prompts: [\n        {\n          name: 'llui-connect',\n          description:\n            'Bind this Claude conversation to an LLui app. Paste the URL and token the app showed you.',\n          arguments: [\n            { name: 'url', description: 'LAP base URL', required: true },\n            { name: 'token', description: 'Bearer token', required: true },\n          ],\n        },\n      ],\n    }),\n  )\n\n  server.setRequestHandler(GetPromptRequestSchema, async (req): Promise<GetPromptResult> => {\n    if (req.params.name !== 'llui-connect') {\n      throw new Error(`unknown prompt: ${req.params.name}`)\n    }\n    const url = req.params.arguments?.['url'] ?? ''\n    const token = req.params.arguments?.['token'] ?? ''\n    return {\n      description: `Bind to LLui app at ${url}`,\n      messages: [\n        {\n          role: 'user',\n          content: {\n            type: 'text',\n            text:\n              `Please connect this conversation to the LLui app at ${url}. ` +\n              `Call llui_connect_session with url=${JSON.stringify(url)} and token=${JSON.stringify(token)}.`,\n          },\n        },\n      ],\n    }\n  })\n}\n"]}
+{"version":3,"file":"prompts.js","sourceRoot":"","sources":["../src/prompts.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAA;AAEvB;;;;;;;GAOG;AACH,MAAM,UAAU,eAAe,CAAC,MAAiB;IAC/C,MAAM,CAAC,cAAc,CACnB,cAAc,EACd;QACE,WAAW,EACT,2FAA2F;QAC7F,UAAU,EAAE;YACV,GAAG,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,cAAc,CAAC;YACxC,KAAK,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,cAAc,CAAC;SAC3C;KACF,EACD,CAAC,EAAE,GAAG,EAAE,KAAK,EAAE,EAAE,EAAE,CAAC,CAAC;QACnB,WAAW,EAAE,uBAAuB,GAAG,EAAE;QACzC,QAAQ,EAAE;YACR;gBACE,IAAI,EAAE,MAAM;gBACZ,OAAO,EAAE;oBACP,IAAI,EAAE,MAAM;oBACZ,IAAI,EACF,uDAAuD,GAAG,IAAI;wBAC9D,sCAAsC,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,cAAc,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,GAAG;iBAClG;aACF;SACF;KACF,CAAC,CACH,CAAA;AACH,CAAC","sourcesContent":["import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js'\nimport { z } from 'zod'\n\n/**\n * Registers the bundled `llui-connect` MCP prompt. Both Claude Desktop\n * and Claude Code surface it as a slash command (Desktop:\n * `/llui-connect <url> <token>`; CC: `/mcp__<server>__llui-connect …`).\n * The prompt body Claude sees is the same natural-language instruction\n * the LLui app shows in its connect snippet — so pasting either form\n * lands the same `llui_connect_session` tool call.\n */\nexport function registerPrompts(server: McpServer): void {\n  server.registerPrompt(\n    'llui-connect',\n    {\n      description:\n        'Bind this Claude conversation to an LLui app. Paste the URL and token the app showed you.',\n      argsSchema: {\n        url: z.string().describe('LAP base URL'),\n        token: z.string().describe('Bearer token'),\n      },\n    },\n    ({ url, token }) => ({\n      description: `Bind to LLui app at ${url}`,\n      messages: [\n        {\n          role: 'user',\n          content: {\n            type: 'text',\n            text:\n              `Please connect this conversation to the LLui app at ${url}. ` +\n              `Call llui_connect_session with url=${JSON.stringify(url)} and token=${JSON.stringify(token)}.`,\n          },\n        },\n      ],\n    }),\n  )\n}\n"]}

package/dist/tools.d.ts

@@ -1,27 +1,21 @@
-import type { ListToolsResult } from '@modelcontextprotocol/sdk/types.js';
-/**
- * The MCP tools Claude sees. Two tiers:
- *
- *  - Efficient path (recommended): `observe` + `send_message`.
- *    `observe` returns state + actions + description + context in one
- *    call — replacing the old describe_app + get_state + list_actions
- *    trio. `send_message` defaults to `waitFor: 'drained'`, blocking
- *    until the message queue goes idle (http/delay/debounce round
- *    trips complete), then returns the new state + actions + drain
- *    meta. Together these cut the "check state → act → check state"
- *    loop from 5 round-trips to 2.
- *
- *  - Legacy / specialized: `describe_app`, `get_state`, `list_actions`,
- *    `wait_for_change`. Kept for back-compat and niche uses (e.g.
- *    scoped state reads via JSON pointer, external state pushes). New
- *    integrations should prefer `observe`.
- *
- * Spec §8.
- */
-export declare const TOOLS: ListToolsResult['tools'];
-/**
- * Mapping from tool name → LAP path for the forwarded subset.
- * Meta-tools handled separately in bridge.ts.
- */
-export declare const TOOL_TO_LAP_PATH: Record<string, string>;
+import { z } from 'zod';
+/** Descriptor for a tool that forwards directly to the bound LAP server. */
+export interface ForwardedToolDescriptor {
+    kind: 'forward';
+    name: string;
+    description: string;
+    /** Zod schema defining the tool's input shape. */
+    schema: z.ZodObject<z.ZodRawShape>;
+    /** LAP endpoint path (relative to the binding's base URL). */
+    lapPath: string;
+}
+/** Descriptor for a tool whose handler is implemented in the bridge itself. */
+export interface MetaToolDescriptor {
+    kind: 'meta';
+    name: string;
+    description: string;
+    schema: z.ZodObject<z.ZodRawShape>;
+}
+export type ToolDescriptor = ForwardedToolDescriptor | MetaToolDescriptor;
+export declare const TOOL_DESCRIPTORS: ToolDescriptor[];
 //# sourceMappingURL=tools.d.ts.map

package/dist/tools.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"tools.d.ts","sourceRoot":"","sources":["../src/tools.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,oCAAoC,CAAA;AAEzE;;;;;;;;;;;;;;;;;;GAkBG;AACH,eAAO,MAAM,KAAK,EAAE,eAAe,CAAC,OAAO,CAuI1C,CAAA;AAED;;;GAGG;AACH,eAAO,MAAM,gBAAgB,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAWnD,CAAA"}
+{"version":3,"file":"tools.d.ts","sourceRoot":"","sources":["../src/tools.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAA;AA6BvB,4EAA4E;AAC5E,MAAM,WAAW,uBAAuB;IACtC,IAAI,EAAE,SAAS,CAAA;IACf,IAAI,EAAE,MAAM,CAAA;IACZ,WAAW,EAAE,MAAM,CAAA;IACnB,kDAAkD;IAClD,MAAM,EAAE,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,WAAW,CAAC,CAAA;IAClC,8DAA8D;IAC9D,OAAO,EAAE,MAAM,CAAA;CAChB;AAED,+EAA+E;AAC/E,MAAM,WAAW,kBAAkB;IACjC,IAAI,EAAE,MAAM,CAAA;IACZ,IAAI,EAAE,MAAM,CAAA;IACZ,WAAW,EAAE,MAAM,CAAA;IACnB,MAAM,EAAE,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,WAAW,CAAC,CAAA;CACnC;AAED,MAAM,MAAM,cAAc,GAAG,uBAAuB,GAAG,kBAAkB,CAAA;AAEzE,eAAO,MAAM,gBAAgB,EAAE,cAAc,EAoL5C,CAAA"}

package/dist/tools.js

@@ -1,159 +1,187 @@
+import { z } from 'zod';
 /**
- * The MCP tools Claude sees. Two tiers:
+ * Tool catalogue exposed to Claude through the MCP bridge. Two tiers:
  *
- *  - Efficient path (recommended): `observe` + `send_message`.
- *    `observe` returns state + actions + description + context in one
- *    call — replacing the old describe_app + get_state + list_actions
- *    trio. `send_message` defaults to `waitFor: 'drained'`, blocking
- *    until the message queue goes idle (http/delay/debounce round
- *    trips complete), then returns the new state + actions + drain
- *    meta. Together these cut the "check state → act → check state"
- *    loop from 5 round-trips to 2.
+ *  - **Efficient path (recommended)**: `observe` + `send_message`.
+ *    `observe` returns state + actions + description + context in a
+ *    single LAP call, replacing the old describe_app + get_state +
+ *    list_actions trio. `send_message` defaults to `waitFor:'drained'`,
+ *    blocking until the message queue goes idle (http/delay/debounce
+ *    round-trips complete) and returning the new state + actions +
+ *    drain meta. Together these cut the "check state → act → check
+ *    state" loop from 5 round-trips to 2.
  *
- *  - Legacy / specialized: `describe_app`, `get_state`, `list_actions`,
- *    `wait_for_change`. Kept for back-compat and niche uses (e.g.
- *    scoped state reads via JSON pointer, external state pushes). New
- *    integrations should prefer `observe`.
+ *  - **Legacy / specialized**: `describe_app`, `get_state`,
+ *    `list_actions`, `wait_for_change`. Kept for back-compat and niche
+ *    uses (e.g. scoped state reads via JSON pointer, external state
+ *    pushes). New integrations should prefer `observe`.
  *
  * Spec §8.
+ *
+ * The catalogue is the single source of truth — Zod schemas drive both
+ * runtime input validation and the JSON Schema published in
+ * `tools/list`. Forwarded tools also carry their LAP endpoint path so
+ * `bridge.ts` can register one generic forwarder that loops over them.
  */
-export const TOOLS = [
+const empty = z.object({});
+export const TOOL_DESCRIPTORS = [
     {
+        kind: 'meta',
         name: 'llui_connect_session',
-        description: 'Bind this Claude conversation to a specific LLui app. Call ONCE per chat when the user pastes /llui-connect <url> <token>. Subsequent LLui tool calls target the bound app.',
-        inputSchema: {
-            type: 'object',
-            properties: {
-                url: {
-                    type: 'string',
-                    description: 'LAP base URL (e.g. https://app.example/agent/lap/v1)',
-                },
-                token: { type: 'string', description: 'Bearer token for LAP calls' },
-            },
-            required: ['url', 'token'],
-        },
+        description: 'Bind this Claude conversation to a specific LLui app. Call ONCE per chat when the user pastes a connect snippet from the LLui app — the snippet contains the url and token to forward here. The result includes the full observe bundle ({state, actions, description, context}) so you have everything you need to start acting — no separate describe_app / get_state / list_actions / describe_context follow-up is required on the first turn. Use observe later when you want a refreshed snapshot.',
+        schema: z.object({
+            url: z.string().describe('LAP base URL (e.g. https://app.example/agent/lap/v1)'),
+            token: z.string().describe('Bearer token for LAP calls'),
+        }),
     },
     {
+        kind: 'meta',
         name: 'llui_disconnect_session',
         description: 'Clear the binding for this Claude conversation. Subsequent LLui tool calls will fail until rebind.',
-        inputSchema: { type: 'object', properties: {} },
+        schema: empty,
     },
     {
+        kind: 'forward',
         name: 'observe',
         description: 'Unified snapshot — returns {state, actions, description, context} in one call. Use this as the default "what can I see, what can I do" read; prefer it over describe_app + get_state + list_actions. Typical flow: observe → send_message → (repeat). The response includes the static app description (name, version, msgSchema, docs) on every call so first-time callers do not need a separate describe_app.',
-        inputSchema: { type: 'object', properties: {} },
+        schema: empty,
+        lapPath: '/observe',
     },
     {
+        kind: 'forward',
         name: 'describe_app',
         description: "Return the bound app's name, version, state/message schemas, annotations, and static docs. Legacy — prefer `observe`, which includes this as `description`.",
-        inputSchema: { type: 'object', properties: {} },
+        schema: empty,
+        lapPath: '/describe',
     },
     {
+        kind: 'forward',
         name: 'get_state',
         description: 'Return the current app state. Optional `path` (JSON-pointer) to narrow the slice. Legacy for full-state reads — prefer `observe`. Still useful for scoped reads via JSON pointer.',
-        inputSchema: {
-            type: 'object',
-            properties: {
-                path: { type: 'string', description: 'Optional JSON-pointer, e.g. "/user/name"' },
-            },
-        },
+        schema: z.object({
+            path: z.string().optional().describe('Optional JSON-pointer, e.g. "/user/name"'),
+        }),
+        lapPath: '/state',
+    },
+    {
+        kind: 'forward',
+        name: 'query_state',
+        description: 'Read a single slice of state via JSON-pointer path. Returns `{found: true, value}` on hit or `{found: false, detail}` on miss (missing key, walking through null, etc.). Cheaper than `observe` when checking one field. Path syntax: `""` (whole state), `"/auth/user"`, `"/items/0/id"`, `"/key~1with~1slash"` (escaped `/`), `"/key~0tilde"` (escaped `~`).',
+        schema: z.object({
+            path: z.string().describe('JSON-pointer (RFC 6901) — `/auth/user` or `""` for whole state'),
+        }),
+        lapPath: '/query-state',
+    },
+    {
+        kind: 'forward',
+        name: 'describe_recent_actions',
+        description: 'Return the most recent log entries for this session (newest first). Each `dispatched` entry includes a `stateDiff` showing what changed. Useful for self-correction over multi-step flows — read your own past dispatches without re-querying full state. Filter by `kind` (e.g. `"dispatched"`) to skip read-only entries.',
+        schema: z.object({
+            n: z.number().int().positive().optional().describe('How many entries to return (default 10)'),
+            kind: z
+                .string()
+                .optional()
+                .describe('Filter to a specific kind (e.g. "dispatched", "read", "error")'),
+        }),
+        lapPath: '/recent-actions',
     },
     {
+        kind: 'forward',
+        name: 'would_dispatch',
+        description: 'Predict what dispatching `msg` would do without committing it. Runs the reducer in isolation against current state and returns `{stateDiff, effects}`. Effects are listed but NOT executed — the cloud is not hit, analytics do not fire. Use this to weigh a candidate action before sending: "if I dispatch X, will it change Y?" Pure-reducer assumption: if the reducer branches on Date.now() / localStorage / random, prediction drifts from real dispatch by exactly that impurity.',
+        schema: z.object({
+            msg: z
+                .object({ type: z.string() })
+                .passthrough()
+                .describe('The candidate message; must have a `type` string'),
+        }),
+        lapPath: '/would-dispatch',
+    },
+    {
+        kind: 'forward',
         name: 'list_actions',
         description: 'Return the currently-affordable actions: visible UI bindings plus agent-affordable registry entries, filtered by annotation gates. Legacy — prefer `observe`, which includes this as `actions`.',
-        inputSchema: { type: 'object', properties: {} },
+        schema: empty,
+        lapPath: '/actions',
     },
     {
+        kind: 'forward',
         name: 'send_message',
-        description: 'Dispatch a message to the app. Blocks by default until the message queue goes idle (drain semantics — captures http/delay/debounce round-trips that feed back as messages). Returns {status, stateAfter, actions, drain} on dispatched, {status: "pending-confirmation", confirmId} when the variant is @requiresConfirm, or {status: "rejected", reason} on validation failures. `drain.timedOut: true` means the 5s cap was hit while messages were still arriving — follow up with `observe` to resync. `actions` in the response reflects the new state, so you normally do not need a separate `observe` after a send.',
-        inputSchema: {
-            type: 'object',
-            properties: {
-                msg: { type: 'object', description: 'The message to dispatch; must have a `type` string' },
-                reason: {
-                    type: 'string',
-                    description: 'User-facing rationale (required for confirm-gated variants)',
-                },
-                waitFor: {
-                    type: 'string',
-                    enum: ['drained', 'idle', 'none'],
-                    description: '"drained" (default) waits for the message queue to go idle; "idle" flushes the update cycle only (no async effects); "none" is fire-and-forget.',
-                },
-                drainQuietMs: {
-                    type: 'number',
-                    description: 'Quiescence window for waitFor:"drained". Drain completes when no commit fires for this many ms. Default 100.',
-                },
-                timeoutMs: {
-                    type: 'number',
-                    description: 'Hard cap on total wait. Default 5000. For waitFor:"drained", this bounds how long the drain loop runs; for pending-confirmation, how long to wait for user approval.',
-                },
-            },
-            required: ['msg'],
-        },
+        description: 'Dispatch a message to the app. Blocks by default until the message queue goes idle (drain semantics — captures http/delay/debounce round-trips that feed back as messages). Returns {status, stateDiff, actions, drain} on dispatched, {status: "pending-confirmation", confirmId} when the variant is @requiresConfirm, or {status: "rejected", reason} on validation failures. By default the response carries `stateDiff` (a JSON-Patch-shaped delta) and not the full post-state — apply the diff to the snapshot you got from `connect`/`observe`. Pass `includeState: true` if you want the full snapshot back (rare; expensive on bandwidth and context for large states). `drain.timedOut: true` means the 5s cap was hit while messages were still arriving — follow up with `observe` to resync. `actions` in the response reflects the new state, so you normally do not need a separate `observe` after a send.',
+        schema: z.object({
+            msg: z
+                .object({ type: z.string() })
+                .passthrough()
+                .describe('The message to dispatch; must have a `type` string'),
+            reason: z
+                .string()
+                .optional()
+                .describe('User-facing rationale (required for confirm-gated variants)'),
+            waitFor: z
+                .enum(['drained', 'idle', 'none'])
+                .optional()
+                .describe('"drained" (default) waits for the message queue to go idle; "idle" flushes the update cycle only (no async effects); "none" is fire-and-forget.'),
+            drainQuietMs: z
+                .number()
+                .optional()
+                .describe('Quiescence window for waitFor:"drained". Drain completes when no commit fires for this many ms. Default 100.'),
+            timeoutMs: z
+                .number()
+                .optional()
+                .describe('Hard cap on total wait. Default 5000. For waitFor:"drained", this bounds how long the drain loop runs; for pending-confirmation, how long to wait for user approval.'),
+            includeState: z
+                .boolean()
+                .optional()
+                .describe('Include the full post-drain `stateAfter` snapshot in the response. Default false — `stateDiff` is what callers normally need, and resending the full state on every dispatch wastes bandwidth and context. Set true only when you need a fresh snapshot back (e.g., after a long-running effect that may have produced changes the diff misses).'),
+        }),
+        lapPath: '/message',
     },
     {
+        kind: 'forward',
         name: 'get_confirm_result',
         description: 'Poll a pending-confirmation by confirmId. Returns confirmed / rejected / still-pending.',
-        inputSchema: {
-            type: 'object',
-            properties: {
-                confirmId: { type: 'string' },
-                timeoutMs: { type: 'number' },
-            },
-            required: ['confirmId'],
-        },
+        schema: z.object({
+            confirmId: z.string(),
+            timeoutMs: z.number().optional(),
+        }),
+        lapPath: '/confirm-result',
     },
     {
+        kind: 'forward',
         name: 'wait_for_change',
         description: 'Long-poll for a state change. Returns changed / timeout. Specialized — use for external state pushes (WebSocket messages, timers) that arrive while Claude is idle. For the normal send-then-read loop, `send_message` with `waitFor:"drained"` already waits for effect round-trips.',
-        inputSchema: {
-            type: 'object',
-            properties: {
-                path: {
-                    type: 'string',
-                    description: 'Optional JSON-pointer to narrow which state changes trigger resolution',
-                },
-                timeoutMs: { type: 'number' },
-            },
-        },
+        schema: z.object({
+            path: z
+                .string()
+                .optional()
+                .describe('Optional JSON-pointer to narrow which state changes trigger resolution'),
+            timeoutMs: z.number().optional(),
+        }),
+        lapPath: '/wait',
     },
     {
+        kind: 'forward',
         name: 'query_dom',
         description: 'Read elements tagged with data-agent="<name>" in the rendered UI.',
-        inputSchema: {
-            type: 'object',
-            properties: {
-                name: { type: 'string' },
-                multiple: { type: 'boolean' },
-            },
-            required: ['name'],
-        },
+        schema: z.object({
+            name: z.string(),
+            multiple: z.boolean().optional(),
+        }),
+        lapPath: '/query-dom',
     },
     {
+        kind: 'forward',
         name: 'describe_visible_content',
         description: 'Return a structured outline of the currently-visible data-agent-tagged subtrees.',
-        inputSchema: { type: 'object', properties: {} },
+        schema: empty,
+        lapPath: '/describe-visible',
     },
     {
+        kind: 'forward',
         name: 'describe_context',
         description: 'Return the current per-state narrative docs (agentContext) — what the user is trying to do right now.',
-        inputSchema: { type: 'object', properties: {} },
+        schema: empty,
+        lapPath: '/context',
     },
 ];
-/**
- * Mapping from tool name → LAP path for the forwarded subset.
- * Meta-tools handled separately in bridge.ts.
- */
-export const TOOL_TO_LAP_PATH = {
-    observe: '/observe',
-    describe_app: '/describe',
-    get_state: '/state',
-    list_actions: '/actions',
-    send_message: '/message',
-    get_confirm_result: '/confirm-result',
-    wait_for_change: '/wait',
-    query_dom: '/query-dom',
-    describe_visible_content: '/describe-visible',
-    describe_context: '/context',
-};
 //# sourceMappingURL=tools.js.map

package/dist/tools.js.map

@@ -1 +1 @@
-{"version":3,"file":"tools.js","sourceRoot":"","sources":["../src/tools.ts"],"names":[],"mappings":"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","sourcesContent":["import type { ListToolsResult } from '@modelcontextprotocol/sdk/types.js'\n\n/**\n * The MCP tools Claude sees. Two tiers:\n *\n *  - Efficient path (recommended): `observe` + `send_message`.\n *    `observe` returns state + actions + description + context in one\n *    call — replacing the old describe_app + get_state + list_actions\n *    trio. `send_message` defaults to `waitFor: 'drained'`, blocking\n *    until the message queue goes idle (http/delay/debounce round\n *    trips complete), then returns the new state + actions + drain\n *    meta. Together these cut the \"check state → act → check state\"\n *    loop from 5 round-trips to 2.\n *\n *  - Legacy / specialized: `describe_app`, `get_state`, `list_actions`,\n *    `wait_for_change`. Kept for back-compat and niche uses (e.g.\n *    scoped state reads via JSON pointer, external state pushes). New\n *    integrations should prefer `observe`.\n *\n * Spec §8.\n */\nexport const TOOLS: ListToolsResult['tools'] = [\n  {\n    name: 'llui_connect_session',\n    description:\n      'Bind this Claude conversation to a specific LLui app. Call ONCE per chat when the user pastes /llui-connect <url> <token>. Subsequent LLui tool calls target the bound app.',\n    inputSchema: {\n      type: 'object',\n      properties: {\n        url: {\n          type: 'string',\n          description: 'LAP base URL (e.g. https://app.example/agent/lap/v1)',\n        },\n        token: { type: 'string', description: 'Bearer token for LAP calls' },\n      },\n      required: ['url', 'token'],\n    },\n  },\n  {\n    name: 'llui_disconnect_session',\n    description:\n      'Clear the binding for this Claude conversation. Subsequent LLui tool calls will fail until rebind.',\n    inputSchema: { type: 'object', properties: {} },\n  },\n  {\n    name: 'observe',\n    description:\n      'Unified snapshot — returns {state, actions, description, context} in one call. Use this as the default \"what can I see, what can I do\" read; prefer it over describe_app + get_state + list_actions. Typical flow: observe → send_message → (repeat). The response includes the static app description (name, version, msgSchema, docs) on every call so first-time callers do not need a separate describe_app.',\n    inputSchema: { type: 'object', properties: {} },\n  },\n  {\n    name: 'describe_app',\n    description:\n      \"Return the bound app's name, version, state/message schemas, annotations, and static docs. Legacy — prefer `observe`, which includes this as `description`.\",\n    inputSchema: { type: 'object', properties: {} },\n  },\n  {\n    name: 'get_state',\n    description:\n      'Return the current app state. Optional `path` (JSON-pointer) to narrow the slice. Legacy for full-state reads — prefer `observe`. Still useful for scoped reads via JSON pointer.',\n    inputSchema: {\n      type: 'object',\n      properties: {\n        path: { type: 'string', description: 'Optional JSON-pointer, e.g. \"/user/name\"' },\n      },\n    },\n  },\n  {\n    name: 'list_actions',\n    description:\n      'Return the currently-affordable actions: visible UI bindings plus agent-affordable registry entries, filtered by annotation gates. Legacy — prefer `observe`, which includes this as `actions`.',\n    inputSchema: { type: 'object', properties: {} },\n  },\n  {\n    name: 'send_message',\n    description:\n      'Dispatch a message to the app. Blocks by default until the message queue goes idle (drain semantics — captures http/delay/debounce round-trips that feed back as messages). Returns {status, stateAfter, actions, drain} on dispatched, {status: \"pending-confirmation\", confirmId} when the variant is @requiresConfirm, or {status: \"rejected\", reason} on validation failures. `drain.timedOut: true` means the 5s cap was hit while messages were still arriving — follow up with `observe` to resync. `actions` in the response reflects the new state, so you normally do not need a separate `observe` after a send.',\n    inputSchema: {\n      type: 'object',\n      properties: {\n        msg: { type: 'object', description: 'The message to dispatch; must have a `type` string' },\n        reason: {\n          type: 'string',\n          description: 'User-facing rationale (required for confirm-gated variants)',\n        },\n        waitFor: {\n          type: 'string',\n          enum: ['drained', 'idle', 'none'],\n          description:\n            '\"drained\" (default) waits for the message queue to go idle; \"idle\" flushes the update cycle only (no async effects); \"none\" is fire-and-forget.',\n        },\n        drainQuietMs: {\n          type: 'number',\n          description:\n            'Quiescence window for waitFor:\"drained\". Drain completes when no commit fires for this many ms. Default 100.',\n        },\n        timeoutMs: {\n          type: 'number',\n          description:\n            'Hard cap on total wait. Default 5000. For waitFor:\"drained\", this bounds how long the drain loop runs; for pending-confirmation, how long to wait for user approval.',\n        },\n      },\n      required: ['msg'],\n    },\n  },\n  {\n    name: 'get_confirm_result',\n    description:\n      'Poll a pending-confirmation by confirmId. Returns confirmed / rejected / still-pending.',\n    inputSchema: {\n      type: 'object',\n      properties: {\n        confirmId: { type: 'string' },\n        timeoutMs: { type: 'number' },\n      },\n      required: ['confirmId'],\n    },\n  },\n  {\n    name: 'wait_for_change',\n    description:\n      'Long-poll for a state change. Returns changed / timeout. Specialized — use for external state pushes (WebSocket messages, timers) that arrive while Claude is idle. For the normal send-then-read loop, `send_message` with `waitFor:\"drained\"` already waits for effect round-trips.',\n    inputSchema: {\n      type: 'object',\n      properties: {\n        path: {\n          type: 'string',\n          description: 'Optional JSON-pointer to narrow which state changes trigger resolution',\n        },\n        timeoutMs: { type: 'number' },\n      },\n    },\n  },\n  {\n    name: 'query_dom',\n    description: 'Read elements tagged with data-agent=\"<name>\" in the rendered UI.',\n    inputSchema: {\n      type: 'object',\n      properties: {\n        name: { type: 'string' },\n        multiple: { type: 'boolean' },\n      },\n      required: ['name'],\n    },\n  },\n  {\n    name: 'describe_visible_content',\n    description: 'Return a structured outline of the currently-visible data-agent-tagged subtrees.',\n    inputSchema: { type: 'object', properties: {} },\n  },\n  {\n    name: 'describe_context',\n    description:\n      'Return the current per-state narrative docs (agentContext) — what the user is trying to do right now.',\n    inputSchema: { type: 'object', properties: {} },\n  },\n]\n\n/**\n * Mapping from tool name → LAP path for the forwarded subset.\n * Meta-tools handled separately in bridge.ts.\n */\nexport const TOOL_TO_LAP_PATH: Record<string, string> = {\n  observe: '/observe',\n  describe_app: '/describe',\n  get_state: '/state',\n  list_actions: '/actions',\n  send_message: '/message',\n  get_confirm_result: '/confirm-result',\n  wait_for_change: '/wait',\n  query_dom: '/query-dom',\n  describe_visible_content: '/describe-visible',\n  describe_context: '/context',\n}\n"]}
+{"version":3,"file":"tools.js","sourceRoot":"","sources":["../src/tools.ts"],"names":[],"mappings":"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","sourcesContent":["import { z } from 'zod'\n\n/**\n * Tool catalogue exposed to Claude through the MCP bridge. Two tiers:\n *\n *  - **Efficient path (recommended)**: `observe` + `send_message`.\n *    `observe` returns state + actions + description + context in a\n *    single LAP call, replacing the old describe_app + get_state +\n *    list_actions trio. `send_message` defaults to `waitFor:'drained'`,\n *    blocking until the message queue goes idle (http/delay/debounce\n *    round-trips complete) and returning the new state + actions +\n *    drain meta. Together these cut the \"check state → act → check\n *    state\" loop from 5 round-trips to 2.\n *\n *  - **Legacy / specialized**: `describe_app`, `get_state`,\n *    `list_actions`, `wait_for_change`. Kept for back-compat and niche\n *    uses (e.g. scoped state reads via JSON pointer, external state\n *    pushes). New integrations should prefer `observe`.\n *\n * Spec §8.\n *\n * The catalogue is the single source of truth — Zod schemas drive both\n * runtime input validation and the JSON Schema published in\n * `tools/list`. Forwarded tools also carry their LAP endpoint path so\n * `bridge.ts` can register one generic forwarder that loops over them.\n */\n\nconst empty = z.object({})\n\n/** Descriptor for a tool that forwards directly to the bound LAP server. */\nexport interface ForwardedToolDescriptor {\n  kind: 'forward'\n  name: string\n  description: string\n  /** Zod schema defining the tool's input shape. */\n  schema: z.ZodObject<z.ZodRawShape>\n  /** LAP endpoint path (relative to the binding's base URL). */\n  lapPath: string\n}\n\n/** Descriptor for a tool whose handler is implemented in the bridge itself. */\nexport interface MetaToolDescriptor {\n  kind: 'meta'\n  name: string\n  description: string\n  schema: z.ZodObject<z.ZodRawShape>\n}\n\nexport type ToolDescriptor = ForwardedToolDescriptor | MetaToolDescriptor\n\nexport const TOOL_DESCRIPTORS: ToolDescriptor[] = [\n  {\n    kind: 'meta',\n    name: 'llui_connect_session',\n    description:\n      'Bind this Claude conversation to a specific LLui app. Call ONCE per chat when the user pastes a connect snippet from the LLui app — the snippet contains the url and token to forward here. The result includes the full observe bundle ({state, actions, description, context}) so you have everything you need to start acting — no separate describe_app / get_state / list_actions / describe_context follow-up is required on the first turn. Use observe later when you want a refreshed snapshot.',\n    schema: z.object({\n      url: z.string().describe('LAP base URL (e.g. https://app.example/agent/lap/v1)'),\n      token: z.string().describe('Bearer token for LAP calls'),\n    }),\n  },\n  {\n    kind: 'meta',\n    name: 'llui_disconnect_session',\n    description:\n      'Clear the binding for this Claude conversation. Subsequent LLui tool calls will fail until rebind.',\n    schema: empty,\n  },\n  {\n    kind: 'forward',\n    name: 'observe',\n    description:\n      'Unified snapshot — returns {state, actions, description, context} in one call. Use this as the default \"what can I see, what can I do\" read; prefer it over describe_app + get_state + list_actions. Typical flow: observe → send_message → (repeat). The response includes the static app description (name, version, msgSchema, docs) on every call so first-time callers do not need a separate describe_app.',\n    schema: empty,\n    lapPath: '/observe',\n  },\n  {\n    kind: 'forward',\n    name: 'describe_app',\n    description:\n      \"Return the bound app's name, version, state/message schemas, annotations, and static docs. Legacy — prefer `observe`, which includes this as `description`.\",\n    schema: empty,\n    lapPath: '/describe',\n  },\n  {\n    kind: 'forward',\n    name: 'get_state',\n    description:\n      'Return the current app state. Optional `path` (JSON-pointer) to narrow the slice. Legacy for full-state reads — prefer `observe`. Still useful for scoped reads via JSON pointer.',\n    schema: z.object({\n      path: z.string().optional().describe('Optional JSON-pointer, e.g. \"/user/name\"'),\n    }),\n    lapPath: '/state',\n  },\n  {\n    kind: 'forward',\n    name: 'query_state',\n    description:\n      'Read a single slice of state via JSON-pointer path. Returns `{found: true, value}` on hit or `{found: false, detail}` on miss (missing key, walking through null, etc.). Cheaper than `observe` when checking one field. Path syntax: `\"\"` (whole state), `\"/auth/user\"`, `\"/items/0/id\"`, `\"/key~1with~1slash\"` (escaped `/`), `\"/key~0tilde\"` (escaped `~`).',\n    schema: z.object({\n      path: z.string().describe('JSON-pointer (RFC 6901) — `/auth/user` or `\"\"` for whole state'),\n    }),\n    lapPath: '/query-state',\n  },\n  {\n    kind: 'forward',\n    name: 'describe_recent_actions',\n    description:\n      'Return the most recent log entries for this session (newest first). Each `dispatched` entry includes a `stateDiff` showing what changed. Useful for self-correction over multi-step flows — read your own past dispatches without re-querying full state. Filter by `kind` (e.g. `\"dispatched\"`) to skip read-only entries.',\n    schema: z.object({\n      n: z.number().int().positive().optional().describe('How many entries to return (default 10)'),\n      kind: z\n        .string()\n        .optional()\n        .describe('Filter to a specific kind (e.g. \"dispatched\", \"read\", \"error\")'),\n    }),\n    lapPath: '/recent-actions',\n  },\n  {\n    kind: 'forward',\n    name: 'would_dispatch',\n    description:\n      'Predict what dispatching `msg` would do without committing it. Runs the reducer in isolation against current state and returns `{stateDiff, effects}`. Effects are listed but NOT executed — the cloud is not hit, analytics do not fire. Use this to weigh a candidate action before sending: \"if I dispatch X, will it change Y?\" Pure-reducer assumption: if the reducer branches on Date.now() / localStorage / random, prediction drifts from real dispatch by exactly that impurity.',\n    schema: z.object({\n      msg: z\n        .object({ type: z.string() })\n        .passthrough()\n        .describe('The candidate message; must have a `type` string'),\n    }),\n    lapPath: '/would-dispatch',\n  },\n  {\n    kind: 'forward',\n    name: 'list_actions',\n    description:\n      'Return the currently-affordable actions: visible UI bindings plus agent-affordable registry entries, filtered by annotation gates. Legacy — prefer `observe`, which includes this as `actions`.',\n    schema: empty,\n    lapPath: '/actions',\n  },\n  {\n    kind: 'forward',\n    name: 'send_message',\n    description:\n      'Dispatch a message to the app. Blocks by default until the message queue goes idle (drain semantics — captures http/delay/debounce round-trips that feed back as messages). Returns {status, stateDiff, actions, drain} on dispatched, {status: \"pending-confirmation\", confirmId} when the variant is @requiresConfirm, or {status: \"rejected\", reason} on validation failures. By default the response carries `stateDiff` (a JSON-Patch-shaped delta) and not the full post-state — apply the diff to the snapshot you got from `connect`/`observe`. Pass `includeState: true` if you want the full snapshot back (rare; expensive on bandwidth and context for large states). `drain.timedOut: true` means the 5s cap was hit while messages were still arriving — follow up with `observe` to resync. `actions` in the response reflects the new state, so you normally do not need a separate `observe` after a send.',\n    schema: z.object({\n      msg: z\n        .object({ type: z.string() })\n        .passthrough()\n        .describe('The message to dispatch; must have a `type` string'),\n      reason: z\n        .string()\n        .optional()\n        .describe('User-facing rationale (required for confirm-gated variants)'),\n      waitFor: z\n        .enum(['drained', 'idle', 'none'])\n        .optional()\n        .describe(\n          '\"drained\" (default) waits for the message queue to go idle; \"idle\" flushes the update cycle only (no async effects); \"none\" is fire-and-forget.',\n        ),\n      drainQuietMs: z\n        .number()\n        .optional()\n        .describe(\n          'Quiescence window for waitFor:\"drained\". Drain completes when no commit fires for this many ms. Default 100.',\n        ),\n      timeoutMs: z\n        .number()\n        .optional()\n        .describe(\n          'Hard cap on total wait. Default 5000. For waitFor:\"drained\", this bounds how long the drain loop runs; for pending-confirmation, how long to wait for user approval.',\n        ),\n      includeState: z\n        .boolean()\n        .optional()\n        .describe(\n          'Include the full post-drain `stateAfter` snapshot in the response. Default false — `stateDiff` is what callers normally need, and resending the full state on every dispatch wastes bandwidth and context. Set true only when you need a fresh snapshot back (e.g., after a long-running effect that may have produced changes the diff misses).',\n        ),\n    }),\n    lapPath: '/message',\n  },\n  {\n    kind: 'forward',\n    name: 'get_confirm_result',\n    description:\n      'Poll a pending-confirmation by confirmId. Returns confirmed / rejected / still-pending.',\n    schema: z.object({\n      confirmId: z.string(),\n      timeoutMs: z.number().optional(),\n    }),\n    lapPath: '/confirm-result',\n  },\n  {\n    kind: 'forward',\n    name: 'wait_for_change',\n    description:\n      'Long-poll for a state change. Returns changed / timeout. Specialized — use for external state pushes (WebSocket messages, timers) that arrive while Claude is idle. For the normal send-then-read loop, `send_message` with `waitFor:\"drained\"` already waits for effect round-trips.',\n    schema: z.object({\n      path: z\n        .string()\n        .optional()\n        .describe('Optional JSON-pointer to narrow which state changes trigger resolution'),\n      timeoutMs: z.number().optional(),\n    }),\n    lapPath: '/wait',\n  },\n  {\n    kind: 'forward',\n    name: 'query_dom',\n    description: 'Read elements tagged with data-agent=\"<name>\" in the rendered UI.',\n    schema: z.object({\n      name: z.string(),\n      multiple: z.boolean().optional(),\n    }),\n    lapPath: '/query-dom',\n  },\n  {\n    kind: 'forward',\n    name: 'describe_visible_content',\n    description: 'Return a structured outline of the currently-visible data-agent-tagged subtrees.',\n    schema: empty,\n    lapPath: '/describe-visible',\n  },\n  {\n    kind: 'forward',\n    name: 'describe_context',\n    description:\n      'Return the current per-state narrative docs (agentContext) — what the user is trying to do right now.',\n    schema: empty,\n    lapPath: '/context',\n  },\n]\n"]}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "llui-agent",
-  "version": "0.0.2",
+  "version": "0.0.4",
   "type": "module",
   "bin": {
     "llui-agent": "./dist/cli.js"
@@ -20,7 +20,8 @@
   ],
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.29.0",
-    "@llui/agent": "0.0.30"
+    "zod": "^4.0.0",
+    "@llui/agent": "0.0.34"
   },
   "devDependencies": {
     "@types/node": "^22.0.0"