@aaep/typescript-producer 1.0.1

package/README.md

@@ -0,0 +1,170 @@
+# TypeScript Minimal Producer Example
+
+A minimal but complete AAEP producer implementation in TypeScript, designed for Node.js (18+). Demonstrates the manual loop pattern with full safety machinery and HTTP/SSE transport.
+
+If you're building AAEP producers in the TypeScript/Node.js ecosystem — whether for browser-side agents, Electron-based AT software, or Node backend agents — this is the example to copy.
+
+---
+
+## What this example demonstrates
+
+- A complete AAEP emitter implemented in idiomatic TypeScript
+- Strict type definitions for every event type (matching the JSON Schemas)
+- Native Node.js streams and `fetch` (no framework dependency)
+- HTTP/SSE transport using Node's `http` module
+- The same safety machinery as the Python examples: irreversible+high MUST default reject, secret redaction, critical urgency on errored events
+- Confirmation flow with `Promise`-based blocking
+- Streaming output with sentence-boundary coalescing
+- All 12 core AAEP event types emitted from a typical agent session
+- Conformance Level 2 compatible
+
+---
+
+## When to use this example
+
+**Pick this pattern when:**
+- You're building agents in Node.js, TypeScript, or modern JavaScript
+- You need AAEP support in browser-side agent UIs
+- You're building AT software in Electron, Tauri, or similar frameworks
+- You want strict type definitions for AAEP events in your codebase
+
+**Pick a Python example when:** your agent stack is Python.
+
+---
+
+## Installation
+
+```bash
+cd examples/producers/typescript-minimal
+npm install
+npm run build
+```
+
+Requires Node.js 18 or newer.
+
+---
+
+## Quick start
+
+```typescript
+import { AAEPEmitter, AgentLoop, makeId } from 'aaep-typescript-producer';
+
+// Step 1: create an emitter with your transport
+const emitter = new AAEPEmitter({
+    sendEvent: (event) => {
+        // Forward to subscribers (HTTP/SSE, WebSocket, etc.)
+        console.log(JSON.stringify(event));
+    },
+    agentId: 'my-agent',
+    agentName: 'My Agent',
+});
+
+// Step 2: create an agent loop
+const agent = new AgentLoop(emitter);
+
+// Step 3: run a session
+const sessionId = await agent.run('Tell me about retirement planning.');
+```
+
+The agent emits AAEP events through the configured transport as it runs. The same safety guarantees as Python: irreversible actions trigger confirmation events, errors emit critical-urgency terminal events, streaming output coalesces at sentence boundaries.
+
+---
+
+## Running the included demo
+
+```bash
+npm run demo
+```
+
+Runs three scenarios (basic query, tool use, irreversible tool with confirmation) and prints every emitted AAEP event in real time.
+
+---
+
+## Running the conformance suite against it
+
+```bash
+# Terminal 1: start the server (port 8084)
+npm run server
+
+# Terminal 2: run the Python conformance suite against the TypeScript server
+aaep-conformance producer --endpoint http://localhost:8084 --level 2
+```
+
+The Python `aaep-conformance` package can verify any HTTP/SSE AAEP producer regardless of implementation language. Cross-language conformance is mechanically demonstrated.
+
+---
+
+## Project layout
+
+```
+typescript-minimal/
+├── README.md
+├── package.json
+├── tsconfig.json
+├── src/
+│   ├── index.ts         # Public API exports
+│   ├── types.ts         # TypeScript types matching the AAEP schemas
+│   ├── emitter.ts       # AAEPEmitter class
+│   ├── coalescer.ts     # StreamCoalescer for sentence-boundary buffering
+│   ├── agent.ts         # AgentLoop with mock LLM
+│   └── server.ts        # HTTP/SSE server
+└── test/
+    ├── emitter.test.ts
+    └── coalescer.test.ts
+```
+
+---
+
+## Key design decisions
+
+### 1. Strict TypeScript types
+
+Every AAEP event has a corresponding TypeScript interface (`SessionStartedEvent`, `ToolInvokedEvent`, etc.). The emitter methods are strongly typed so editor autocomplete shows valid field names and the compiler catches missing required fields. Types match the JSON Schemas exactly.
+
+### 2. No framework dependencies
+
+The example uses only the Node.js standard library plus type definitions. No Express, no Fastify, no agent framework — just the language and runtime. This makes the integration pattern clear and ensures the example survives ecosystem churn.
+
+### 3. Runtime safety enforcement (same as Python)
+
+The `awaitConfirmation` method throws if called with `irreversible: true`, `riskLevel: 'high'`, and `defaultDecision: 'accept'`. This matches the JSON Schema's if/then rule AND the Python emitter's runtime check. The safety contract is enforced at every layer.
+
+### 4. Promise-based confirmation blocking
+
+JavaScript doesn't have Python's `asyncio.Future`, but `Promise` works the same way. `awaitConfirmation()` returns a reply token; calling code does `await emitter.waitForDecision(token)` to block until the subscriber replies via `submitReply()`.
+
+### 5. Compatible with browser-side agents
+
+The emitter code is environment-agnostic (no Node-specific imports in `emitter.ts`). You can use the same `AAEPEmitter` in a browser bundle for browser-side agents. Only `server.ts` is Node-specific.
+
+---
+
+## Cross-language conformance verification
+
+This example demonstrates that **AAEP is genuinely language-agnostic**. The same `aaep-conformance` Python tool that verifies the Python examples also verifies this TypeScript example without modification.
+
+To prove this end-to-end:
+
+```bash
+# Run all 5 servers simultaneously
+python -m aaep_minimal_producer.server --port 8080 &     # Python manual loop
+python -m aaep_langchain.server --port 8081 &            # LangChain callback
+python -m aaep_anthropic_sdk.server --port 8082 &        # Anthropic SDK
+python -m aaep_maf.server --port 8083 &                  # Microsoft Agent Framework
+npm run server &                                         # TypeScript (port 8084)
+
+# Run conformance against all 5
+for port in 8080 8081 8082 8083 8084; do
+  aaep-conformance producer --endpoint http://localhost:$port --level 2
+done
+```
+
+If all 5 pass Level 2, AAEP is interoperable across 4 Python integration patterns AND TypeScript. That's the mechanical proof of "AAEP is language-agnostic" — not a claim, a result.
+
+---
+
+## See also
+
+- [`../python-minimal/`](../python-minimal/) — the Python reference (same machinery, different language)
+- [Implementer's Guide §3.7](../../../guides/IMPLEMENTERS_GUIDE.md) — TypeScript integration specifics
+- [Node.js SSE documentation](https://nodejs.org/api/http.html) — upstream reference for the transport

package/dist/agent.d.ts

@@ -0,0 +1,41 @@
+/**
+ * AgentLoop — TypeScript port of the Python python-minimal AgentLoop.
+ *
+ * Production-grade reference of the manual loop pattern with a mock LLM
+ * for portability. Replace `_MockLLM` with a real client (Anthropic, OpenAI,
+ * Azure OpenAI, etc.) for production use.
+ */
+import { AAEPEmitter } from "./emitter.js";
+export interface ToolDescriptor {
+    name: string;
+    description: string;
+    handler: (args: Record<string, unknown>) => unknown | Promise<unknown>;
+    riskLevel?: "low" | "medium" | "high";
+    irreversible?: boolean;
+}
+export interface AgentLoopOptions {
+    emitter: AAEPEmitter;
+    tools?: ToolDescriptor[];
+}
+export declare class AgentLoop {
+    private readonly emitter;
+    private readonly tools;
+    private readonly llm;
+    private readonly activeSessions;
+    constructor(options: AgentLoopOptions);
+    /**
+     * Run a complete agent session. Returns the session_id.
+     *
+     * The session is fully owned by this method: it emits all lifecycle
+     * events including the terminal event, even on exception.
+     */
+    run(userMessage: string, opts?: {
+        userId?: string;
+    }): Promise<string>;
+    /** Cancel an in-progress session. Returns true if cancellation was issued. */
+    cancel(sessionId: string): boolean;
+    private runLoop;
+    private executeTool;
+    private defaultTools;
+}
+//# sourceMappingURL=agent.d.ts.map

package/dist/agent.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent.d.ts","sourceRoot":"","sources":["../src/agent.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EACH,WAAW,EAKd,MAAM,cAAc,CAAC;AAMtB,MAAM,WAAW,cAAc;IAC3B,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,OAAO,EAAE,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IACvE,SAAS,CAAC,EAAE,KAAK,GAAG,QAAQ,GAAG,MAAM,CAAC;IACtC,YAAY,CAAC,EAAE,OAAO,CAAC;CAC1B;AAKD,MAAM,WAAW,gBAAgB;IAC7B,OAAO,EAAE,WAAW,CAAC;IACrB,KAAK,CAAC,EAAE,cAAc,EAAE,CAAC;CAC5B;AAKD,qBAAa,SAAS;IAClB,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAc;IACtC,OAAO,CAAC,QAAQ,CAAC,KAAK,CAA8B;IACpD,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAW;IAC/B,OAAO,CAAC,QAAQ,CAAC,cAAc,CAA2C;gBAE9D,OAAO,EAAE,gBAAgB;IAQrC;;;;;OAKG;IACG,GAAG,CAAC,WAAW,EAAE,MAAM,EAAE,IAAI,GAAE;QAAE,MAAM,CAAC,EAAE,MAAM,CAAA;KAAO,GAAG,OAAO,CAAC,MAAM,CAAC;IAoB/E,8EAA8E;IAC9E,MAAM,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO;YASpB,OAAO;YAgIP,WAAW;IAuFzB,OAAO,CAAC,YAAY;CAuCvB"}

package/dist/agent.js

@@ -0,0 +1,336 @@
+/**
+ * AgentLoop — TypeScript port of the Python python-minimal AgentLoop.
+ *
+ * Production-grade reference of the manual loop pattern with a mock LLM
+ * for portability. Replace `_MockLLM` with a real client (Anthropic, OpenAI,
+ * Azure OpenAI, etc.) for production use.
+ */
+import { classifyErrorCategory, classifyRisk, makeId, safeArgsSummary, } from "./emitter.js";
+import { StreamCoalescer } from "./coalescer.js";
+// === The agent loop ===
+export class AgentLoop {
+    emitter;
+    tools;
+    llm;
+    activeSessions = new Map();
+    constructor(options) {
+        this.emitter = options.emitter;
+        this.tools = new Map((options.tools ?? this.defaultTools()).map((t) => [t.name, t]));
+        this.llm = new _MockLLM();
+    }
+    /**
+     * Run a complete agent session. Returns the session_id.
+     *
+     * The session is fully owned by this method: it emits all lifecycle
+     * events including the terminal event, even on exception.
+     */
+    async run(userMessage, opts = {}) {
+        const sessionId = this.emitter.startSession({
+            summaryNormal: `Processing: ${userMessage.slice(0, 80)}`,
+            requestText: userMessage,
+            requestedBy: opts.userId ? `user:${opts.userId}` : undefined,
+            toolsAvailable: Array.from(this.tools.keys()),
+        });
+        const abortController = new AbortController();
+        this.activeSessions.set(sessionId, abortController);
+        try {
+            await this.runLoop(sessionId, userMessage, abortController.signal);
+        }
+        finally {
+            this.activeSessions.delete(sessionId);
+        }
+        return sessionId;
+    }
+    /** Cancel an in-progress session. Returns true if cancellation was issued. */
+    cancel(sessionId) {
+        const controller = this.activeSessions.get(sessionId);
+        if (!controller)
+            return false;
+        controller.abort();
+        return true;
+    }
+    // === Internal: the thinking-and-acting loop ===
+    async runLoop(sessionId, userMessage, abortSignal) {
+        const startTime = Date.now();
+        let currentState = "idle";
+        let toolCount = 0;
+        let coalescer = null;
+        const messages = [
+            { role: "user", content: userMessage },
+        ];
+        try {
+            while (true) {
+                if (abortSignal.aborted) {
+                    throw new DOMException("Cancelled", "AbortError");
+                }
+                // Transition to thinking
+                if (currentState !== "thinking") {
+                    this.emitter.stateChanged({
+                        sessionId,
+                        fromState: currentState,
+                        toState: "thinking",
+                        summaryNormal: "Considering the request.",
+                    });
+                    currentState = "thinking";
+                }
+                const response = await this.llm.complete(messages, Array.from(this.tools.values()));
+                if (response.toolCalls.length > 0) {
+                    // Tools requested
+                    this.emitter.stateChanged({
+                        sessionId,
+                        fromState: "thinking",
+                        toState: "calling_tool",
+                        summaryNormal: `Preparing to call ${response.toolCalls.length} tool(s).`,
+                    });
+                    currentState = "calling_tool";
+                    const toolResults = [];
+                    for (const toolCall of response.toolCalls) {
+                        const result = await this.executeTool(sessionId, toolCall);
+                        toolCount++;
+                        toolResults.push({ tool_call_id: toolCall.id, result });
+                    }
+                    messages.push({
+                        role: "assistant",
+                        content: response.text,
+                    });
+                    messages.push({
+                        role: "tool_results",
+                        content: toolResults,
+                    });
+                    continue;
+                }
+                // No more tools; stream output
+                this.emitter.stateChanged({
+                    sessionId,
+                    fromState: "thinking",
+                    toState: "writing_output",
+                    summaryNormal: "Generating response.",
+                });
+                currentState = "writing_output";
+                const outputId = makeId("out");
+                coalescer = new StreamCoalescer({
+                    emitter: this.emitter,
+                    sessionId,
+                    outputId,
+                    coalesceAt: "sentence",
+                });
+                for await (const chunk of this.llm.stream(response)) {
+                    if (abortSignal.aborted) {
+                        throw new DOMException("Cancelled", "AbortError");
+                    }
+                    coalescer.addToken(chunk);
+                }
+                coalescer.finish();
+                coalescer = null;
+                break;
+            }
+            // Success
+            const durationMs = Date.now() - startTime;
+            this.emitter.completeSession({
+                sessionId,
+                summaryNormal: "Response complete.",
+                durationMs,
+                toolInvocationsCount: toolCount,
+            });
+        }
+        catch (error) {
+            if (coalescer) {
+                try {
+                    coalescer.finish();
+                }
+                catch {
+                    // Already finished or in bad state; swallow
+                }
+            }
+            if (error instanceof DOMException && error.name === "AbortError") {
+                this.emitter.cancelledSession({
+                    sessionId,
+                    cancelledBy: "system",
+                    summaryNormal: "Session cancelled.",
+                });
+            }
+            else {
+                const err = error instanceof Error ? error : new Error(String(error));
+                this.emitter.errorSession({
+                    sessionId,
+                    errorCategory: classifyErrorCategory(err),
+                    summaryNormal: `Error: ${err.name}`,
+                    errorMessage: err.message.slice(0, 1000),
+                    recoverable: err.name === "TimeoutError" || err.message.toLowerCase().includes("network"),
+                });
+            }
+            throw error;
+        }
+    }
+    // === Internal: execute one tool with full AAEP cycle ===
+    async executeTool(sessionId, toolCall) {
+        const descriptor = this.tools.get(toolCall.name);
+        const aaepCallId = makeId("call");
+        const args = toolCall.arguments;
+        const { riskLevel, irreversible } = descriptor
+            ? {
+                riskLevel: descriptor.riskLevel ?? "low",
+                irreversible: descriptor.irreversible ?? false,
+            }
+            : classifyRisk(toolCall.name);
+        // Emit tool.invoked BEFORE side effect
+        this.emitter.toolInvoked({
+            sessionId,
+            tool: toolCall.name,
+            toolCallId: aaepCallId,
+            argsSummary: safeArgsSummary(args),
+            riskLevel,
+            irreversible,
+            summaryNormal: `Calling ${toolCall.name}.`,
+        });
+        // Confirmation gating for irreversible or high-risk
+        if (irreversible || riskLevel === "high") {
+            const replyToken = this.emitter.awaitConfirmation({
+                sessionId,
+                action: `Call ${toolCall.name} with: ${safeArgsSummary(args, 200)}`,
+                consequence: irreversible
+                    ? "This action cannot be easily undone."
+                    : "This action will be executed.",
+                timeoutSeconds: 300,
+                defaultDecision: "reject",
+                riskLevel,
+                irreversible,
+                summaryNormal: `Confirm: call ${toolCall.name}?`,
+            });
+            const decision = await this.emitter.waitForDecision(replyToken);
+            if (decision !== "accept") {
+                this.emitter.toolCompleted({
+                    sessionId,
+                    tool: toolCall.name,
+                    toolCallId: aaepCallId,
+                    status: "error",
+                    errorMessage: "User declined to authorize this action.",
+                });
+                return `<user declined to call ${toolCall.name}>`;
+            }
+        }
+        // Execute the tool
+        try {
+            if (!descriptor) {
+                throw new Error(`No handler for tool ${JSON.stringify(toolCall.name)}`);
+            }
+            const result = await descriptor.handler(args);
+            this.emitter.toolCompleted({
+                sessionId,
+                tool: toolCall.name,
+                toolCallId: aaepCallId,
+                status: "success",
+                summaryNormal: String(result).slice(0, 200),
+            });
+            return result;
+        }
+        catch (error) {
+            const err = error instanceof Error ? error : new Error(String(error));
+            const isTimeout = err.name === "TimeoutError" || err.message.includes("timeout");
+            this.emitter.toolCompleted({
+                sessionId,
+                tool: toolCall.name,
+                toolCallId: aaepCallId,
+                status: isTimeout ? "timeout" : "error",
+                errorMessage: err.message.slice(0, 1000),
+            });
+            throw error;
+        }
+    }
+    // === Default mock tools ===
+    defaultTools() {
+        return [
+            {
+                name: "fetch_balance",
+                description: "Look up an account balance",
+                handler: async (args) => {
+                    await sleep(300);
+                    const account = args.account ?? "checking";
+                    const balances = {
+                        checking: "$3,247.18",
+                        savings: "$12,891.40",
+                    };
+                    return balances[account] ?? "$0.00";
+                },
+                riskLevel: "low",
+                irreversible: false,
+            },
+            {
+                name: "send_email",
+                description: "Send an email",
+                handler: async (args) => {
+                    await sleep(500);
+                    return `Email sent to ${args.to ?? "recipient"}`;
+                },
+                riskLevel: "high",
+                irreversible: true,
+            },
+            {
+                name: "transfer_funds",
+                description: "Move money between accounts",
+                handler: async (args) => {
+                    await sleep(700);
+                    return `Transferred $${args.amount} from ${args.from} to ${args.to}`;
+                },
+                riskLevel: "high",
+                irreversible: true,
+            },
+        ];
+    }
+}
+class _MockLLM {
+    calls = 0;
+    async complete(messages, _tools) {
+        await sleep(400);
+        this.calls++;
+        const lastMsg = messages[messages.length - 1];
+        const lastText = typeof lastMsg?.content === "string" ? lastMsg.content : "";
+        const lower = lastText.toLowerCase();
+        // On the first call, sometimes call a tool to exercise the flow
+        if (this.calls === 1) {
+            if (lower.includes("balance")) {
+                return {
+                    text: "Let me check that for you.",
+                    toolCalls: [{
+                            id: `tool_${this.calls}`,
+                            name: "fetch_balance",
+                            arguments: { account: "checking" },
+                        }],
+                };
+            }
+            if (lower.includes("email")) {
+                return {
+                    text: "I'll send that email.",
+                    toolCalls: [{
+                            id: `tool_${this.calls}`,
+                            name: "send_email",
+                            arguments: {
+                                to: "recipient@example.com",
+                                subject: "Re: your request",
+                            },
+                        }],
+                };
+            }
+        }
+        // No more tools; return final output (caller will stream the text)
+        return { text: "", toolCalls: [] };
+    }
+    async *stream(_response) {
+        const chunks = [
+            "Here's what I found. ",
+            "Your account is in good standing ",
+            "with no pending issues. ",
+            "Is there anything else ",
+            "I can help you with?",
+        ];
+        for (const chunk of chunks) {
+            await sleep(50);
+            yield chunk;
+        }
+    }
+}
+// === Helpers ===
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+//# sourceMappingURL=agent.js.map

package/dist/agent.js.map

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

package/dist/coalescer.d.ts

@@ -0,0 +1,57 @@
+/**
+ * StreamCoalescer — TypeScript port of the Python StreamCoalescer.
+ *
+ * Buffers streaming tokens and emits agent.output.streaming events at
+ * coalesce boundaries (default: sentence boundaries). The boundary
+ * detection regexes match the Python implementation exactly.
+ *
+ * Usage:
+ *   const coalescer = new StreamCoalescer({
+ *       emitter,
+ *       sessionId: "sess_x",
+ *       outputId: "out_y",
+ *       coalesceAt: "sentence",
+ *   });
+ *   coalescer.addToken("Hello ");
+ *   coalescer.addToken("world. ");      // sentence boundary -> emit
+ *   coalescer.addToken("Goodbye.");
+ *   coalescer.finish();                 // final emit with complete=true
+ */
+import type { CoalesceHint } from "./types.js";
+import { AAEPEmitter } from "./emitter.js";
+export interface StreamCoalescerOptions {
+    emitter: AAEPEmitter;
+    sessionId: string;
+    outputId: string;
+    coalesceAt?: CoalesceHint;
+    language?: string;
+}
+export declare class StreamCoalescer {
+    private readonly emitter;
+    private readonly sessionId;
+    private readonly outputId;
+    private readonly coalesceAt;
+    private readonly language;
+    private buffer;
+    private position;
+    private finished;
+    constructor(options: StreamCoalescerOptions);
+    /**
+     * Add a token to the buffer. May emit one or more events if coalesce
+     * boundaries are crossed by the addition.
+     */
+    addToken(token: string): void;
+    /**
+     * Flush any remaining buffer and emit the final completion event
+     * (complete=true). Idempotent; safe to call multiple times.
+     */
+    finish(): void;
+    /** Inspect the current buffered text (for tests). */
+    get bufferedText(): string;
+    /** Whether finish() has been called. */
+    get isFinished(): boolean;
+    private flushAtBoundary;
+    private findBoundaries;
+    private emitChunk;
+}
+//# sourceMappingURL=coalescer.d.ts.map

package/dist/coalescer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"coalescer.d.ts","sourceRoot":"","sources":["../src/coalescer.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAC/C,OAAO,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AAG3C,MAAM,WAAW,sBAAsB;IACnC,OAAO,EAAE,WAAW,CAAC;IACrB,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,EAAE,MAAM,CAAC;IACjB,UAAU,CAAC,EAAE,YAAY,CAAC;IAC1B,QAAQ,CAAC,EAAE,MAAM,CAAC;CACrB;AAGD,qBAAa,eAAe;IACxB,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAc;IACtC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAS;IACnC,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAS;IAClC,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAe;IAC1C,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAqB;IAE9C,OAAO,CAAC,MAAM,CAAM;IACpB,OAAO,CAAC,QAAQ,CAAK;IACrB,OAAO,CAAC,QAAQ,CAAS;gBAEb,OAAO,EAAE,sBAAsB;IAQ3C;;;OAGG;IACH,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI;IAQ7B;;;OAGG;IACH,MAAM,IAAI,IAAI;IAQd,qDAAqD;IACrD,IAAI,YAAY,IAAI,MAAM,CAEzB;IAED,wCAAwC;IACxC,IAAI,UAAU,IAAI,OAAO,CAExB;IAID,OAAO,CAAC,eAAe;IAmBvB,OAAO,CAAC,cAAc;IAwBtB,OAAO,CAAC,SAAS;CAepB"}