apcore-mcp 0.6.1 → 0.8.0

package/README.md

@@ -16,6 +16,7 @@ Converts apcore module registries into [Model Context Protocol (MCP)](https://mo
 - **Annotation Mapping** — Map module annotations to MCP hints and OpenAI description suffixes
 - **Error Mapping** — Sanitize internal errors for safe client-facing responses
 - **Dynamic Registration** — Listen for registry changes and update tools at runtime
+- **Tool Explorer** — Browser-based UI for browsing schemas and testing tools interactively
 - **CLI** — Launch an MCP server from the command line
 
 ## Requirements
@@ -78,6 +79,73 @@ npx apcore-mcp --extensions-dir ./extensions --transport sse --port 8000
 | `--name` | `apcore-mcp` | MCP server name |
 | `--version` | package version | MCP server version |
 | `--log-level` | `INFO` | `DEBUG`, `INFO`, `WARNING`, `ERROR` |
+| `--explorer` | off | Enable the browser-based Tool Explorer UI (HTTP only) |
+| `--explorer-prefix` | `/explorer` | URL prefix for the explorer UI |
+| `--allow-execute` | off | Allow tool execution from the explorer UI |
+| `--jwt-secret` | — | JWT secret key for Bearer token authentication |
+| `--jwt-algorithm` | `HS256` | JWT algorithm |
+| `--jwt-audience` | — | Expected JWT audience claim |
+| `--jwt-issuer` | — | Expected JWT issuer claim |
+| `--jwt-require-auth` | `true` | Require auth (use `--no-jwt-require-auth` for permissive mode) |
+| `--exempt-paths` | `/health,/metrics` | Comma-separated paths exempt from auth |
+
+## MCP Client Configuration
+
+### Claude Desktop
+
+Add to `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or `%APPDATA%\Claude\claude_desktop_config.json` (Windows):
+
+```json
+{
+  "mcpServers": {
+    "apcore": {
+      "command": "npx",
+      "args": ["apcore-mcp", "--extensions-dir", "/path/to/your/extensions"]
+    }
+  }
+}
+```
+
+### Claude Code
+
+Add to `.mcp.json` in your project root:
+
+```json
+{
+  "mcpServers": {
+    "apcore": {
+      "command": "npx",
+      "args": ["apcore-mcp", "--extensions-dir", "./extensions"]
+    }
+  }
+}
+```
+
+### Cursor
+
+Add to `.cursor/mcp.json` in your project root:
+
+```json
+{
+  "mcpServers": {
+    "apcore": {
+      "command": "npx",
+      "args": ["apcore-mcp", "--extensions-dir", "./extensions"]
+    }
+  }
+}
+```
+
+### Remote HTTP access
+
+```bash
+npx apcore-mcp --extensions-dir ./extensions \
+    --transport streamable-http \
+    --host 0.0.0.0 \
+    --port 9000
+```
+
+Connect any MCP client to `http://your-host:9000/mcp`.
 
 ## API Reference
 
@@ -94,10 +162,101 @@ function serve(
     port?: number;
     name?: string;
     version?: string;
+    explorer?: boolean;
+    explorerPrefix?: string;
+    allowExecute?: boolean;
+    authenticator?: Authenticator;
+    exemptPaths?: string[];
   }
 ): Promise<void>;
 ```
 
+### Tool Explorer
+
+When `explorer: true` is passed to `serve()`, a browser-based Tool Explorer UI is mounted on HTTP transports. It provides an interactive page for browsing tool schemas and testing tool execution.
+
+```typescript
+await serve(registry, {
+  transport: "streamable-http",
+  explorer: true,
+  allowExecute: true,
+});
+// Open http://127.0.0.1:8000/explorer/ in a browser
+```
+
+**Endpoints:**
+
+| Endpoint | Description |
+|----------|-------------|
+| `GET /explorer/` | Interactive HTML page (self-contained, no external dependencies) |
+| `GET /explorer/tools` | JSON array of all tools with name, description, annotations |
+| `GET /explorer/tools/<name>` | Full tool detail with inputSchema |
+| `POST /explorer/tools/<name>/call` | Execute a tool (requires `allowExecute: true`) |
+
+- **HTTP transports only** (`streamable-http`, `sse`). Silently ignored for `stdio`.
+- **Execution disabled by default** — set `allowExecute: true` to enable Try-it.
+- **Custom prefix** — use `explorerPrefix: "/browse"` to mount at a different path.
+- **Authorization UI** — Swagger-UI-style Authorization input field. Paste a Bearer token to authenticate tool execution requests. Generated cURL commands automatically include the Authorization header.
+
+### JWT Authentication
+
+apcore-mcp supports JWT Bearer token authentication for HTTP-based transports.
+
+#### Programmatic Usage
+
+```typescript
+import { serve, JWTAuthenticator } from "apcore-mcp";
+
+const authenticator = new JWTAuthenticator({
+  secret: "your-secret-key",
+  algorithms: ["HS256"],
+  audience: "my-app",
+  issuer: "auth-service",
+  // Map custom claims to Identity fields
+  claimMapping: {
+    id: "sub",
+    type: "type",
+    roles: "roles",
+    attrs: ["email", "org"],  // Extra claims → Identity.attrs
+  },
+  // Claims that must be present in the token (default: ["sub"])
+  requireClaims: ["sub", "email"],
+  // Set to false for permissive mode (allow unauthenticated requests)
+  requireAuth: true,
+});
+
+await serve(executor, {
+  transport: "streamable-http",
+  authenticator,
+  // Custom exempt paths (default: ["/health", "/metrics"])
+  exemptPaths: ["/health", "/metrics", "/status"],
+});
+```
+
+#### CLI Flags
+
+| Flag | Default | Description |
+|------|---------|-------------|
+| `--jwt-secret` | — | JWT secret key for Bearer token authentication |
+| `--jwt-algorithm` | `HS256` | JWT algorithm |
+| `--jwt-audience` | — | Expected audience claim |
+| `--jwt-issuer` | — | Expected issuer claim |
+| `--jwt-require-auth` | `true` | Require auth. Use `--no-jwt-require-auth` for permissive mode |
+| `--exempt-paths` | `/health,/metrics` | Comma-separated paths exempt from auth |
+
+#### curl Examples
+
+```bash
+# Authenticated request
+curl -X POST http://localhost:8000/mcp \
+  -H "Content-Type: application/json" \
+  -H "Authorization: Bearer <your-jwt-token>" \
+  -d '{"jsonrpc":"2.0","method":"tools/list","id":1}'
+
+# Health check (always exempt)
+curl http://localhost:8000/health
+```
+
 ### `toOpenaiTools(registryOrExecutor, options?)`
 
 Export apcore modules as OpenAI-compatible tool definitions.
@@ -128,16 +287,25 @@ src/
 ├── index.ts              # Public API: serve(), toOpenaiTools()
 ├── cli.ts                # CLI entry point
 ├── types.ts              # TypeScript interfaces
+├── helpers.ts            # reportProgress() / elicit() helpers
 ├── adapters/
 │   ├── schema.ts         # JSON Schema $ref inlining
 │   ├── annotations.ts    # Module annotations -> MCP hints
 │   ├── errors.ts         # Error sanitization
 │   └── idNormalizer.ts   # Dot-notation <-> dash-notation
+├── auth/
+│   ├── jwt.ts            # JWT Bearer token authenticator
+│   ├── storage.ts        # AsyncLocalStorage identity propagation
+│   └── types.ts          # Authenticator / Identity interfaces
 ├── converters/
 │   └── openai.ts         # OpenAI tool definition converter
+├── explorer/
+│   ├── handler.ts        # Explorer HTTP route handler
+│   └── html.ts           # Self-contained HTML/CSS/JS page
 └── server/
     ├── factory.ts        # MCP Server creation & handler registration
     ├── router.ts         # Tool call execution routing
+    ├── context.ts        # BridgeContext for executor call chains
     ├── transport.ts      # Transport lifecycle (stdio/HTTP/SSE)
     └── listener.ts       # Dynamic registry event listener
 ```
@@ -176,18 +344,7 @@ npm run dev
 
 ## Testing
 
-100 tests across 10 test suites with 96%+ line coverage:
-
-| Module | Coverage |
-|---|---|
-| annotations.ts | 100% |
-| idNormalizer.ts | 100% |
-| factory.ts | 100% |
-| router.ts | 100% |
-| errors.ts | 98.8% |
-| schema.ts | 97.0% |
-| openai.ts | 91.7% |
-| listener.ts | 89.7% |
+284 tests across 22 test suites.
 
 ## License
 

package/dist/adapters/annotations.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"annotations.d.ts","sourceRoot":"","sources":["../../src/adapters/annotations.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,iBAAiB,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAC;AAEzE,qBAAa,gBAAgB;IAC3B;;;;;;;;;OASG;IACH,gBAAgB,CAAC,WAAW,EAAE,iBAAiB,GAAG,IAAI,GAAG,kBAAkB;IAoB3E;;;;;;;;;;;OAWG;IACH,mBAAmB,CAAC,WAAW,EAAE,iBAAiB,GAAG,IAAI,GAAG,MAAM;IAgClE;;;;OAIG;IACH,mBAAmB,CAAC,WAAW,EAAE,iBAAiB,GAAG,IAAI,GAAG,OAAO;CAOpE"}
+{"version":3,"file":"annotations.d.ts","sourceRoot":"","sources":["../../src/adapters/annotations.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,iBAAiB,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAC;AAEzE,qBAAa,gBAAgB;IAC3B;;;;;;;;;OASG;IACH,gBAAgB,CAAC,WAAW,EAAE,iBAAiB,GAAG,IAAI,GAAG,kBAAkB;IAoB3E;;;;;;;;;;;OAWG;IACH,mBAAmB,CAAC,WAAW,EAAE,iBAAiB,GAAG,IAAI,GAAG,MAAM;IAmClE;;;;OAIG;IACH,mBAAmB,CAAC,WAAW,EAAE,iBAAiB,GAAG,IAAI,GAAG,OAAO;CAOpE"}

package/dist/adapters/annotations.js

@@ -56,6 +56,7 @@ export class AnnotationMapper {
             idempotent: false,
             requires_approval: false,
             open_world: true,
+            streaming: false,
         };
         const parts = [];
         if (annotations.readonly !== DEFAULTS.readonly)
@@ -68,6 +69,8 @@ export class AnnotationMapper {
             parts.push(`requires_approval=${annotations.requiresApproval}`);
         if (annotations.openWorld !== DEFAULTS.open_world)
             parts.push(`open_world=${annotations.openWorld}`);
+        if (annotations.streaming !== DEFAULTS.streaming)
+            parts.push(`streaming=${annotations.streaming}`);
         if (parts.length === 0) {
             return "";
         }

package/dist/adapters/annotations.js.map

@@ -1 +1 @@
-{"version":3,"file":"annotations.js","sourceRoot":"","sources":["../../src/adapters/annotations.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAIH,MAAM,OAAO,gBAAgB;IAC3B;;;;;;;;;OASG;IACH,gBAAgB,CAAC,WAAqC;QACpD,IAAI,WAAW,KAAK,IAAI,EAAE,CAAC;YACzB,OAAO;gBACL,YAAY,EAAE,KAAK;gBACnB,eAAe,EAAE,KAAK;gBACtB,cAAc,EAAE,KAAK;gBACrB,aAAa,EAAE,IAAI;gBACnB,KAAK,EAAE,IAAI;aACZ,CAAC;QACJ,CAAC;QAED,OAAO;YACL,YAAY,EAAE,WAAW,CAAC,QAAQ;YAClC,eAAe,EAAE,WAAW,CAAC,WAAW;YACxC,cAAc,EAAE,WAAW,CAAC,UAAU;YACtC,aAAa,EAAE,WAAW,CAAC,SAAS;YACpC,KAAK,EAAE,IAAI;SACZ,CAAC;IACJ,CAAC;IAED;;;;;;;;;;;OAWG;IACH,mBAAmB,CAAC,WAAqC;QACvD,IAAI,WAAW,KAAK,IAAI,EAAE,CAAC;YACzB,OAAO,EAAE,CAAC;QACZ,CAAC;QAED,MAAM,QAAQ,GAA4B;YACxC,QAAQ,EAAE,KAAK;YACf,WAAW,EAAE,KAAK;YAClB,UAAU,EAAE,KAAK;YACjB,iBAAiB,EAAE,KAAK;YACxB,UAAU,EAAE,IAAI;SACjB,CAAC;QAEF,MAAM,KAAK,GAAa,EAAE,CAAC;QAC3B,IAAI,WAAW,CAAC,QAAQ,KAAK,QAAQ,CAAC,QAAQ;YAC5C,KAAK,CAAC,IAAI,CAAC,YAAY,WAAW,CAAC,QAAQ,EAAE,CAAC,CAAC;QACjD,IAAI,WAAW,CAAC,WAAW,KAAK,QAAQ,CAAC,WAAW;YAClD,KAAK,CAAC,IAAI,CAAC,eAAe,WAAW,CAAC,WAAW,EAAE,CAAC,CAAC;QACvD,IAAI,WAAW,CAAC,UAAU,KAAK,QAAQ,CAAC,UAAU;YAChD,KAAK,CAAC,IAAI,CAAC,cAAc,WAAW,CAAC,UAAU,EAAE,CAAC,CAAC;QACrD,IAAI,WAAW,CAAC,gBAAgB,KAAK,QAAQ,CAAC,iBAAiB;YAC7D,KAAK,CAAC,IAAI,CAAC,qBAAqB,WAAW,CAAC,gBAAgB,EAAE,CAAC,CAAC;QAClE,IAAI,WAAW,CAAC,SAAS,KAAK,QAAQ,CAAC,UAAU;YAC/C,KAAK,CAAC,IAAI,CAAC,cAAc,WAAW,CAAC,SAAS,EAAE,CAAC,CAAC;QAEpD,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YACvB,OAAO,EAAE,CAAC;QACZ,CAAC;QAED,OAAO,qBAAqB,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC;IAClD,CAAC;IAED;;;;OAIG;IACH,mBAAmB,CAAC,WAAqC;QACvD,IAAI,WAAW,KAAK,IAAI,EAAE,CAAC;YACzB,OAAO,KAAK,CAAC;QACf,CAAC;QAED,OAAO,WAAW,CAAC,gBAAgB,CAAC;IACtC,CAAC;CACF"}
+{"version":3,"file":"annotations.js","sourceRoot":"","sources":["../../src/adapters/annotations.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAIH,MAAM,OAAO,gBAAgB;IAC3B;;;;;;;;;OASG;IACH,gBAAgB,CAAC,WAAqC;QACpD,IAAI,WAAW,KAAK,IAAI,EAAE,CAAC;YACzB,OAAO;gBACL,YAAY,EAAE,KAAK;gBACnB,eAAe,EAAE,KAAK;gBACtB,cAAc,EAAE,KAAK;gBACrB,aAAa,EAAE,IAAI;gBACnB,KAAK,EAAE,IAAI;aACZ,CAAC;QACJ,CAAC;QAED,OAAO;YACL,YAAY,EAAE,WAAW,CAAC,QAAQ;YAClC,eAAe,EAAE,WAAW,CAAC,WAAW;YACxC,cAAc,EAAE,WAAW,CAAC,UAAU;YACtC,aAAa,EAAE,WAAW,CAAC,SAAS;YACpC,KAAK,EAAE,IAAI;SACZ,CAAC;IACJ,CAAC;IAED;;;;;;;;;;;OAWG;IACH,mBAAmB,CAAC,WAAqC;QACvD,IAAI,WAAW,KAAK,IAAI,EAAE,CAAC;YACzB,OAAO,EAAE,CAAC;QACZ,CAAC;QAED,MAAM,QAAQ,GAA4B;YACxC,QAAQ,EAAE,KAAK;YACf,WAAW,EAAE,KAAK;YAClB,UAAU,EAAE,KAAK;YACjB,iBAAiB,EAAE,KAAK;YACxB,UAAU,EAAE,IAAI;YAChB,SAAS,EAAE,KAAK;SACjB,CAAC;QAEF,MAAM,KAAK,GAAa,EAAE,CAAC;QAC3B,IAAI,WAAW,CAAC,QAAQ,KAAK,QAAQ,CAAC,QAAQ;YAC5C,KAAK,CAAC,IAAI,CAAC,YAAY,WAAW,CAAC,QAAQ,EAAE,CAAC,CAAC;QACjD,IAAI,WAAW,CAAC,WAAW,KAAK,QAAQ,CAAC,WAAW;YAClD,KAAK,CAAC,IAAI,CAAC,eAAe,WAAW,CAAC,WAAW,EAAE,CAAC,CAAC;QACvD,IAAI,WAAW,CAAC,UAAU,KAAK,QAAQ,CAAC,UAAU;YAChD,KAAK,CAAC,IAAI,CAAC,cAAc,WAAW,CAAC,UAAU,EAAE,CAAC,CAAC;QACrD,IAAI,WAAW,CAAC,gBAAgB,KAAK,QAAQ,CAAC,iBAAiB;YAC7D,KAAK,CAAC,IAAI,CAAC,qBAAqB,WAAW,CAAC,gBAAgB,EAAE,CAAC,CAAC;QAClE,IAAI,WAAW,CAAC,SAAS,KAAK,QAAQ,CAAC,UAAU;YAC/C,KAAK,CAAC,IAAI,CAAC,cAAc,WAAW,CAAC,SAAS,EAAE,CAAC,CAAC;QACpD,IAAI,WAAW,CAAC,SAAS,KAAK,QAAQ,CAAC,SAAS;YAC9C,KAAK,CAAC,IAAI,CAAC,aAAa,WAAW,CAAC,SAAS,EAAE,CAAC,CAAC;QAEnD,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YACvB,OAAO,EAAE,CAAC;QACZ,CAAC;QAED,OAAO,qBAAqB,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC;IAClD,CAAC;IAED;;;;OAIG;IACH,mBAAmB,CAAC,WAAqC;QACvD,IAAI,WAAW,KAAK,IAAI,EAAE,CAAC;YACzB,OAAO,KAAK,CAAC;QACf,CAAC;QAED,OAAO,WAAW,CAAC,gBAAgB,CAAC;IACtC,CAAC;CACF"}

package/dist/adapters/approval.d.ts

@@ -0,0 +1,35 @@
+/**
+ * ElicitationApprovalHandler: bridges MCP elicitation to apcore's approval system.
+ *
+ * Uses the MCP elicit callback (injected into Context.data) to present
+ * approval requests to the human user via the MCP client.
+ */
+export interface ApprovalRequest {
+    moduleId: string;
+    description?: string | null;
+    arguments: Record<string, unknown>;
+    context?: {
+        data?: Record<string, unknown>;
+    } | null;
+}
+export interface ApprovalResult {
+    status: "approved" | "rejected" | "timeout" | "pending";
+    reason?: string | null;
+}
+export declare class ElicitationApprovalHandler {
+    /**
+     * Request approval via MCP elicitation.
+     *
+     * Extracts the elicit callback from request.context.data, builds
+     * an approval message, and maps the elicit response to an ApprovalResult.
+     */
+    requestApproval(request: ApprovalRequest): Promise<ApprovalResult>;
+    /**
+     * Check status of an existing approval.
+     *
+     * Phase B (async polling) is not supported via MCP elicitation since
+     * elicitation is stateless.
+     */
+    checkApproval(_approvalId: string): Promise<ApprovalResult>;
+}
+//# sourceMappingURL=approval.d.ts.map

package/dist/adapters/approval.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"approval.d.ts","sourceRoot":"","sources":["../../src/adapters/approval.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAIH,MAAM,WAAW,eAAe;IAC9B,QAAQ,EAAE,MAAM,CAAC;IACjB,WAAW,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACnC,OAAO,CAAC,EAAE;QAAE,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;KAAE,GAAG,IAAI,CAAC;CACrD;AAED,MAAM,WAAW,cAAc;IAC7B,MAAM,EAAE,UAAU,GAAG,UAAU,GAAG,SAAS,GAAG,SAAS,CAAC;IACxD,MAAM,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CACxB;AAED,qBAAa,0BAA0B;IACrC;;;;;OAKG;IACG,eAAe,CAAC,OAAO,EAAE,eAAe,GAAG,OAAO,CAAC,cAAc,CAAC;IAsCxE;;;;;OAKG;IACG,aAAa,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,cAAc,CAAC;CAGlE"}

package/dist/adapters/approval.js

@@ -0,0 +1,53 @@
+/**
+ * ElicitationApprovalHandler: bridges MCP elicitation to apcore's approval system.
+ *
+ * Uses the MCP elicit callback (injected into Context.data) to present
+ * approval requests to the human user via the MCP client.
+ */
+import { MCP_ELICIT_KEY } from "../helpers.js";
+export class ElicitationApprovalHandler {
+    /**
+     * Request approval via MCP elicitation.
+     *
+     * Extracts the elicit callback from request.context.data, builds
+     * an approval message, and maps the elicit response to an ApprovalResult.
+     */
+    async requestApproval(request) {
+        const data = request.context?.data ?? null;
+        if (data === null) {
+            return { status: "rejected", reason: "No context available for elicitation" };
+        }
+        const elicitCallback = data[MCP_ELICIT_KEY];
+        if (!elicitCallback) {
+            return { status: "rejected", reason: "No elicitation callback available" };
+        }
+        const message = `Approval required for tool: ${request.moduleId}\n\n` +
+            `${request.description ?? ""}\n\n` +
+            `Arguments: ${JSON.stringify(request.arguments)}`;
+        let result;
+        try {
+            result = await elicitCallback(message);
+        }
+        catch {
+            return { status: "rejected", reason: "Elicitation request failed" };
+        }
+        if (result === null || result === undefined) {
+            return { status: "rejected", reason: "Elicitation returned no response" };
+        }
+        const action = result.action;
+        if (action === "accept") {
+            return { status: "approved" };
+        }
+        return { status: "rejected", reason: `User action: ${action}` };
+    }
+    /**
+     * Check status of an existing approval.
+     *
+     * Phase B (async polling) is not supported via MCP elicitation since
+     * elicitation is stateless.
+     */
+    async checkApproval(_approvalId) {
+        return { status: "rejected", reason: "Phase B not supported via MCP elicitation" };
+    }
+}
+//# sourceMappingURL=approval.js.map

package/dist/adapters/approval.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"approval.js","sourceRoot":"","sources":["../../src/adapters/approval.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AAc/C,MAAM,OAAO,0BAA0B;IACrC;;;;;OAKG;IACH,KAAK,CAAC,eAAe,CAAC,OAAwB;QAC5C,MAAM,IAAI,GAAG,OAAO,CAAC,OAAO,EAAE,IAAI,IAAI,IAAI,CAAC;QAC3C,IAAI,IAAI,KAAK,IAAI,EAAE,CAAC;YAClB,OAAO,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,EAAE,sCAAsC,EAAE,CAAC;QAChF,CAAC;QAED,MAAM,cAAc,GAAG,IAAI,CAAC,cAAc,CAE7B,CAAC;QAEd,IAAI,CAAC,cAAc,EAAE,CAAC;YACpB,OAAO,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,EAAE,mCAAmC,EAAE,CAAC;QAC7E,CAAC;QAED,MAAM,OAAO,GACX,+BAA+B,OAAO,CAAC,QAAQ,MAAM;YACrD,GAAG,OAAO,CAAC,WAAW,IAAI,EAAE,MAAM;YAClC,cAAc,IAAI,CAAC,SAAS,CAAC,OAAO,CAAC,SAAS,CAAC,EAAE,CAAC;QAEpD,IAAI,MAAoE,CAAC;QACzE,IAAI,CAAC;YACH,MAAM,GAAG,MAAM,cAAc,CAAC,OAAO,CAAC,CAAC;QACzC,CAAC;QAAC,MAAM,CAAC;YACP,OAAO,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,EAAE,4BAA4B,EAAE,CAAC;QACtE,CAAC;QAED,IAAI,MAAM,KAAK,IAAI,IAAI,MAAM,KAAK,SAAS,EAAE,CAAC;YAC5C,OAAO,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,EAAE,kCAAkC,EAAE,CAAC;QAC5E,CAAC;QAED,MAAM,MAAM,GAAG,MAAM,CAAC,MAAM,CAAC;QAC7B,IAAI,MAAM,KAAK,QAAQ,EAAE,CAAC;YACxB,OAAO,EAAE,MAAM,EAAE,UAAU,EAAE,CAAC;QAChC,CAAC;QAED,OAAO,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,EAAE,gBAAgB,MAAM,EAAE,EAAE,CAAC;IAClE,CAAC;IAED;;;;;OAKG;IACH,KAAK,CAAC,aAAa,CAAC,WAAmB;QACrC,OAAO,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,EAAE,2CAA2C,EAAE,CAAC;IACrF,CAAC;CACF"}

package/dist/adapters/errors.d.ts

@@ -2,8 +2,8 @@
  * ErrorMapper - Maps apcore errors to MCP-compatible error responses.
  *
  * Handles ModuleError instances with specific error codes, sanitizes
- * internal error details, and formats schema validation errors with
- * field-level detail.
+ * internal error details, formats schema validation errors with
+ * field-level detail, and extracts AI guidance fields.
  */
 import type { McpErrorResponse } from "../types.js";
 export declare class ErrorMapper {
@@ -14,6 +14,10 @@ export declare class ErrorMapper {
      * Applies sanitization and formatting rules based on the error code.
      */
     toMcpError(error: unknown): McpErrorResponse;
+    /**
+     * Extract AI guidance fields from error and attach non-undefined values to result.
+     */
+    private _attachAiGuidance;
     /**
      * Duck-type check for ModuleError-like objects.
      *

package/dist/adapters/errors.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../src/adapters/errors.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAGH,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AASpD,qBAAa,WAAW;IACtB;;;;;OAKG;IACH,UAAU,CAAC,KAAK,EAAE,OAAO,GAAG,gBAAgB;IAuD5C;;;;OAIG;IACH,OAAO,CAAC,cAAc;IAetB;;;;;OAKG;IACH,OAAO,CAAC,sBAAsB;CA4B/B"}
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../src/adapters/errors.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAGH,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAgBpD,qBAAa,WAAW;IACtB;;;;;OAKG;IACH,UAAU,CAAC,KAAK,EAAE,OAAO,GAAG,gBAAgB;IA2G5C;;OAEG;IACH,OAAO,CAAC,iBAAiB;IAazB;;;;OAIG;IACH,OAAO,CAAC,cAAc;IAetB;;;;;OAKG;IACH,OAAO,CAAC,sBAAsB;CA4B/B"}

package/dist/adapters/errors.js

@@ -2,8 +2,8 @@
  * ErrorMapper - Maps apcore errors to MCP-compatible error responses.
  *
  * Handles ModuleError instances with specific error codes, sanitizes
- * internal error details, and formats schema validation errors with
- * field-level detail.
+ * internal error details, formats schema validation errors with
+ * field-level detail, and extracts AI guidance fields.
  */
 import { ErrorCodes } from "../types.js";
 /** Internal error codes that should be sanitized to a generic message. */
@@ -12,6 +12,12 @@ const INTERNAL_ERROR_CODES = new Set([
     ErrorCodes.CIRCULAR_CALL,
     ErrorCodes.CALL_FREQUENCY_EXCEEDED,
 ]);
+/**
+ * AI guidance field names on the MCP wire format (camelCase).
+ * Both Python and TypeScript output identical camelCase keys in MCP responses.
+ * Python reads snake_case from apcore errors and maps to camelCase on output.
+ */
+const _AI_GUIDANCE_FIELDS = ["retryable", "aiGuidance", "userFixable", "suggestion"];
 export class ErrorMapper {
     /**
      * Convert an error to an MCP error response.
@@ -45,20 +51,69 @@ export class ErrorMapper {
             // Schema validation error -> formatted with field-level details
             if (code === ErrorCodes.SCHEMA_VALIDATION_ERROR) {
                 const message = this._formatValidationError(details);
-                return {
+                const result = {
                     isError: true,
                     errorType: ErrorCodes.SCHEMA_VALIDATION_ERROR,
                     message,
                     details,
                 };
+                this._attachAiGuidance(error, result);
+                return result;
+            }
+            // Approval pending -> narrow details to approvalId only
+            // NOTE: apcore-js may use camelCase (approvalId) or snake_case (approval_id).
+            // Check both to stay compatible with either convention.
+            if (code === ErrorCodes.APPROVAL_PENDING) {
+                const idKey = details && "approvalId" in details
+                    ? "approvalId"
+                    : details && "approval_id" in details
+                        ? "approval_id"
+                        : null;
+                const narrowed = idKey
+                    ? { approvalId: details[idKey] }
+                    : null;
+                const result = {
+                    isError: true,
+                    errorType: code,
+                    message: error.message,
+                    details: narrowed,
+                };
+                this._attachAiGuidance(error, result);
+                return result;
+            }
+            // Approval timeout -> mark as retryable
+            if (code === ErrorCodes.APPROVAL_TIMEOUT) {
+                const result = {
+                    isError: true,
+                    errorType: code,
+                    message: error.message,
+                    details,
+                    retryable: true,
+                };
+                this._attachAiGuidance(error, result);
+                return result;
+            }
+            // Approval denied -> extract reason from details
+            if (code === ErrorCodes.APPROVAL_DENIED) {
+                const reason = details ? details.reason : undefined;
+                const result = {
+                    isError: true,
+                    errorType: code,
+                    message: error.message,
+                    details: reason ? { reason } : details,
+                };
+                this._attachAiGuidance(error, result);
+                return result;
             }
             // Other known ModuleError codes -> pass through
-            return {
+            const result = {
                 isError: true,
                 errorType: code,
                 message: error.message,
                 details,
             };
+            this._attachAiGuidance(error, result);
+            return result;
         }
         // Unknown/unexpected exceptions -> generic error
         return {
@@ -68,6 +123,18 @@ export class ErrorMapper {
             details: null,
         };
     }
+    /**
+     * Extract AI guidance fields from error and attach non-undefined values to result.
+     */
+    _attachAiGuidance(error, result) {
+        for (const field of _AI_GUIDANCE_FIELDS) {
+            const value = error[field];
+            if (value !== undefined && value !== null && result[field] === undefined) {
+                // eslint-disable-next-line @typescript-eslint/no-explicit-any
+                result[field] = value;
+            }
+        }
+    }
     /**
      * Duck-type check for ModuleError-like objects.
      *

package/dist/adapters/errors.js.map

@@ -1 +1 @@
-{"version":3,"file":"errors.js","sourceRoot":"","sources":["../../src/adapters/errors.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAGzC,0EAA0E;AAC1E,MAAM,oBAAoB,GAAgB,IAAI,GAAG,CAAC;IAChD,UAAU,CAAC,mBAAmB;IAC9B,UAAU,CAAC,aAAa;IACxB,UAAU,CAAC,uBAAuB;CACnC,CAAC,CAAC;AAEH,MAAM,OAAO,WAAW;IACtB;;;;;OAKG;IACH,UAAU,CAAC,KAAc;QACvB,+CAA+C;QAC/C,IAAI,IAAI,CAAC,cAAc,CAAC,KAAK,CAAC,EAAE,CAAC;YAC/B,MAAM,IAAI,GAAG,KAAK,CAAC,IAAI,CAAC;YACxB,MAAM,OAAO,GAAG,KAAK,CAAC,OAAO,CAAC;YAE9B,0CAA0C;YAC1C,IAAI,oBAAoB,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,CAAC;gBACnC,OAAO;oBACL,OAAO,EAAE,IAAI;oBACb,SAAS,EAAE,IAAI;oBACf,OAAO,EAAE,yBAAyB;oBAClC,OAAO,EAAE,IAAI;iBACd,CAAC;YACJ,CAAC;YAED,wCAAwC;YACxC,IAAI,IAAI,KAAK,UAAU,CAAC,UAAU,EAAE,CAAC;gBACnC,OAAO;oBACL,OAAO,EAAE,IAAI;oBACb,SAAS,EAAE,UAAU,CAAC,UAAU;oBAChC,OAAO,EAAE,eAAe;oBACxB,OAAO,EAAE,IAAI;iBACd,CAAC;YACJ,CAAC;YAED,gEAAgE;YAChE,IAAI,IAAI,KAAK,UAAU,CAAC,uBAAuB,EAAE,CAAC;gBAChD,MAAM,OAAO,GAAG,IAAI,CAAC,sBAAsB,CAAC,OAAO,CAAC,CAAC;gBACrD,OAAO;oBACL,OAAO,EAAE,IAAI;oBACb,SAAS,EAAE,UAAU,CAAC,uBAAuB;oBAC7C,OAAO;oBACP,OAAO;iBACR,CAAC;YACJ,CAAC;YAED,gDAAgD;YAChD,OAAO;gBACL,OAAO,EAAE,IAAI;gBACb,SAAS,EAAE,IAAI;gBACf,OAAO,EAAE,KAAK,CAAC,OAAO;gBACtB,OAAO;aACR,CAAC;QACJ,CAAC;QAED,iDAAiD;QACjD,OAAO;YACL,OAAO,EAAE,IAAI;YACb,SAAS,EAAE,UAAU,CAAC,cAAc;YACpC,OAAO,EAAE,yBAAyB;YAClC,OAAO,EAAE,IAAI;SACd,CAAC;IACJ,CAAC;IAED;;;;OAIG;IACK,cAAc,CACpB,KAAc;QAEd,IAAI,KAAK,KAAK,IAAI,IAAI,OAAO,KAAK,KAAK,QAAQ,EAAE,CAAC;YAChD,OAAO,KAAK,CAAC;QACf,CAAC;QAED,MAAM,GAAG,GAAG,KAAgC,CAAC;QAC7C,OAAO,CACL,OAAO,GAAG,CAAC,MAAM,CAAC,KAAK,QAAQ;YAC/B,OAAO,GAAG,CAAC,SAAS,CAAC,KAAK,QAAQ;YAClC,SAAS,IAAI,GAAG,CACjB,CAAC;IACJ,CAAC;IAED;;;;;OAKG;IACK,sBAAsB,CAC5B,OAAuC;QAEvC,MAAM,WAAW,GAAG,0BAA0B,CAAC;QAE/C,IAAI,OAAO,KAAK,IAAI,EAAE,CAAC;YACrB,OAAO,WAAW,CAAC;QACrB,CAAC;QAED,MAAM,MAAM,GAAG,OAAO,CAAC,QAAQ,CAAC,CAAC;QACjC,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC,IAAI,MAAM,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YAClD,OAAO,WAAW,CAAC;QACrB,CAAC;QAED,MAAM,WAAW,GAAG,MAAM;aACvB,GAAG,CAAC,CAAC,GAAG,EAAE,EAAE;YACX,IAAI,GAAG,KAAK,IAAI,IAAI,OAAO,GAAG,KAAK,QAAQ,EAAE,CAAC;gBAC5C,MAAM,KAAK,GAAG,GAA8B,CAAC;gBAC7C,MAAM,KAAK,GAAG,KAAK,CAAC,OAAO,CAAC,IAAI,SAAS,CAAC;gBAC1C,MAAM,OAAO,GAAG,KAAK,CAAC,SAAS,CAAC,IAAI,kBAAkB,CAAC;gBACvD,OAAO,KAAK,MAAM,CAAC,KAAK,CAAC,KAAK,MAAM,CAAC,OAAO,CAAC,EAAE,CAAC;YAClD,CAAC;YACD,OAAO,KAAK,MAAM,CAAC,GAAG,CAAC,EAAE,CAAC;QAC5B,CAAC,CAAC;aACD,IAAI,CAAC,IAAI,CAAC,CAAC;QAEd,OAAO,GAAG,WAAW,MAAM,WAAW,EAAE,CAAC;IAC3C,CAAC;CACF"}
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../../src/adapters/errors.ts"],"names":[],"mappings":"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"}

package/dist/adapters/index.d.ts

@@ -5,4 +5,6 @@ export { SchemaConverter } from "./schema.js";
 export { AnnotationMapper } from "./annotations.js";
 export { ErrorMapper } from "./errors.js";
 export { ModuleIDNormalizer } from "./idNormalizer.js";
+export { ElicitationApprovalHandler } from "./approval.js";
+export type { ApprovalRequest, ApprovalResult } from "./approval.js";
 //# sourceMappingURL=index.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/adapters/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAC9C,OAAO,EAAE,gBAAgB,EAAE,MAAM,kBAAkB,CAAC;AACpD,OAAO,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAC1C,OAAO,EAAE,kBAAkB,EAAE,MAAM,mBAAmB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/adapters/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAC9C,OAAO,EAAE,gBAAgB,EAAE,MAAM,kBAAkB,CAAC;AACpD,OAAO,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAC1C,OAAO,EAAE,kBAAkB,EAAE,MAAM,mBAAmB,CAAC;AACvD,OAAO,EAAE,0BAA0B,EAAE,MAAM,eAAe,CAAC;AAC3D,YAAY,EAAE,eAAe,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC"}

package/dist/adapters/index.js

@@ -5,4 +5,5 @@ export { SchemaConverter } from "./schema.js";
 export { AnnotationMapper } from "./annotations.js";
 export { ErrorMapper } from "./errors.js";
 export { ModuleIDNormalizer } from "./idNormalizer.js";
+export { ElicitationApprovalHandler } from "./approval.js";
 //# sourceMappingURL=index.js.map

package/dist/adapters/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/adapters/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAC9C,OAAO,EAAE,gBAAgB,EAAE,MAAM,kBAAkB,CAAC;AACpD,OAAO,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAC1C,OAAO,EAAE,kBAAkB,EAAE,MAAM,mBAAmB,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/adapters/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAC9C,OAAO,EAAE,gBAAgB,EAAE,MAAM,kBAAkB,CAAC;AACpD,OAAO,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAC1C,OAAO,EAAE,kBAAkB,EAAE,MAAM,mBAAmB,CAAC;AACvD,OAAO,EAAE,0BAA0B,EAAE,MAAM,eAAe,CAAC"}

package/dist/auth/index.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Auth module barrel exports.
+ */
+export type { Authenticator, Identity } from "./types.js";
+export { JWTAuthenticator } from "./jwt.js";
+export type { ClaimMapping, JWTAuthenticatorOptions } from "./jwt.js";
+export { identityStorage, getCurrentIdentity } from "./storage.js";
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/auth/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,YAAY,EAAE,aAAa,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAC1D,OAAO,EAAE,gBAAgB,EAAE,MAAM,UAAU,CAAC;AAC5C,YAAY,EAAE,YAAY,EAAE,uBAAuB,EAAE,MAAM,UAAU,CAAC;AACtE,OAAO,EAAE,eAAe,EAAE,kBAAkB,EAAE,MAAM,cAAc,CAAC"}

package/dist/auth/index.js

@@ -0,0 +1,6 @@
+/**
+ * Auth module barrel exports.
+ */
+export { JWTAuthenticator } from "./jwt.js";
+export { identityStorage, getCurrentIdentity } from "./storage.js";
+//# sourceMappingURL=index.js.map

package/dist/auth/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/auth/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AAGH,OAAO,EAAE,gBAAgB,EAAE,MAAM,UAAU,CAAC;AAE5C,OAAO,EAAE,eAAe,EAAE,kBAAkB,EAAE,MAAM,cAAc,CAAC"}

package/dist/auth/jwt.d.ts

@@ -0,0 +1,59 @@
+/**
+ * JWT Authenticator — verifies Bearer tokens and maps claims to Identity.
+ *
+ * Mirrors the Python `JWTAuthenticator` from apcore-mcp-python.
+ */
+import type { IncomingMessage } from "node:http";
+import jwt from "jsonwebtoken";
+import { type Identity } from "apcore-js";
+import type { Authenticator } from "./types.js";
+/** Mapping from JWT claims to Identity fields. */
+export interface ClaimMapping {
+    /** JWT claim for Identity.id. Default: "sub" */
+    id?: string;
+    /** JWT claim for Identity.type. Default: "type" */
+    type?: string;
+    /** JWT claim for Identity.roles. Default: "roles" */
+    roles?: string;
+    /** Extra claims to copy into Identity.attrs. */
+    attrs?: string[];
+}
+/** Options for constructing a JWTAuthenticator. */
+export interface JWTAuthenticatorOptions {
+    /** Secret key (symmetric) or public key (asymmetric) for token verification. */
+    secret: string;
+    /** Allowed algorithms. Default: ["HS256"] */
+    algorithms?: jwt.Algorithm[];
+    /** Expected audience claim. */
+    audience?: string;
+    /** Expected issuer claim. */
+    issuer?: string;
+    /** Custom claim-to-Identity field mapping. */
+    claimMapping?: ClaimMapping;
+    /** Claims that must be present in the token. Default: ["sub"] */
+    requireClaims?: string[];
+    /** If true (default), unauthenticated requests are rejected. If false, they proceed without identity. */
+    requireAuth?: boolean;
+}
+/**
+ * Authenticator that verifies JWT Bearer tokens from the Authorization header.
+ *
+ * Returns an Identity on success, or `null` if:
+ * - No Authorization header is present
+ * - The header is not a valid "Bearer <token>" format
+ * - The token fails verification (expired, wrong signature, etc.)
+ */
+export declare class JWTAuthenticator implements Authenticator {
+    private readonly _secret;
+    private readonly _algorithms;
+    private readonly _audience?;
+    private readonly _issuer?;
+    private readonly _claimMapping;
+    private readonly _requireClaims;
+    private readonly _requireAuth;
+    constructor(options: JWTAuthenticatorOptions);
+    /** Whether unauthenticated requests should be rejected. */
+    get requireAuth(): boolean;
+    authenticate(req: IncomingMessage): Promise<Identity | null>;
+}
+//# sourceMappingURL=jwt.d.ts.map

package/dist/auth/jwt.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"jwt.d.ts","sourceRoot":"","sources":["../../src/auth/jwt.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,WAAW,CAAC;AACjD,OAAO,GAAG,MAAM,cAAc,CAAC;AAC/B,OAAO,EAAkB,KAAK,QAAQ,EAAE,MAAM,WAAW,CAAC;AAC1D,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAEhD,kDAAkD;AAClD,MAAM,WAAW,YAAY;IAC3B,gDAAgD;IAChD,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,mDAAmD;IACnD,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,qDAAqD;IACrD,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,gDAAgD;IAChD,KAAK,CAAC,EAAE,MAAM,EAAE,CAAC;CAClB;AAED,mDAAmD;AACnD,MAAM,WAAW,uBAAuB;IACtC,gFAAgF;IAChF,MAAM,EAAE,MAAM,CAAC;IACf,6CAA6C;IAC7C,UAAU,CAAC,EAAE,GAAG,CAAC,SAAS,EAAE,CAAC;IAC7B,+BAA+B;IAC/B,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,6BAA6B;IAC7B,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,8CAA8C;IAC9C,YAAY,CAAC,EAAE,YAAY,CAAC;IAC5B,iEAAiE;IACjE,aAAa,CAAC,EAAE,MAAM,EAAE,CAAC;IACzB,yGAAyG;IACzG,WAAW,CAAC,EAAE,OAAO,CAAC;CACvB;AAED;;;;;;;GAOG;AACH,qBAAa,gBAAiB,YAAW,aAAa;IACpD,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAS;IACjC,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAkB;IAC9C,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAC,CAAS;IACpC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAS;IAClC,OAAO,CAAC,QAAQ,CAAC,aAAa,CAA+D;IAC7F,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAW;IAC1C,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAU;gBAE3B,OAAO,EAAE,uBAAuB;IAe5C,2DAA2D;IAC3D,IAAI,WAAW,IAAI,OAAO,CAEzB;IAEK,YAAY,CAAC,GAAG,EAAE,eAAe,GAAG,OAAO,CAAC,QAAQ,GAAG,IAAI,CAAC;CAsDnE"}