agenticreplay 0.1.0 → 0.1.2

package/packages/cli/dist/mcp-server.d.ts

@@ -0,0 +1,44 @@
+import type { Readable, Writable } from 'node:stream';
+import { AgenticReplay } from './api.js';
+export interface McpTool {
+    name: string;
+    description: string;
+    inputSchema: {
+        type: 'object';
+        properties: Record<string, unknown>;
+        required?: string[];
+    };
+}
+export declare const MCP_TOOLS: McpTool[];
+type JsonRpcId = string | number;
+interface JsonRpcResponse {
+    jsonrpc: '2.0';
+    id: JsonRpcId;
+    result?: unknown;
+    error?: {
+        code: number;
+        message: string;
+    };
+}
+/**
+ * Handle one message.
+ *
+ * Returns `undefined` for a notification, which by definition has no id to answer — replying to
+ * one is a protocol error that some clients treat as fatal.
+ */
+export declare function handleMcpMessage(agenticreplay: AgenticReplay, message: unknown): Promise<JsonRpcResponse | undefined>;
+export interface ServeMcpOptions {
+    agenticreplay: AgenticReplay;
+    input: Readable;
+    output: Writable;
+}
+/**
+ * Serve MCP over a stream pair until the input ends.
+ *
+ * Messages are handled one at a time. Concurrency would buy nothing — every tool here is either a
+ * file read or a subprocess that owns the working tree — and it would let two replays fight over
+ * the same checkout.
+ */
+export declare function serveMcp({ agenticreplay, input, output }: ServeMcpOptions): Promise<void>;
+export {};
+//# sourceMappingURL=mcp-server.d.ts.map

package/packages/cli/dist/mcp-server.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mcp-server.d.ts","sourceRoot":"","sources":["../src/mcp-server.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AAEtD,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AAyBzC,MAAM,WAAW,OAAO;IACtB,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE;QACX,IAAI,EAAE,QAAQ,CAAC;QACf,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;QACpC,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAC;KACrB,CAAC;CACH;AAYD,eAAO,MAAM,SAAS,EAAE,OAAO,EA2F9B,CAAC;AAEF,KAAK,SAAS,GAAG,MAAM,GAAG,MAAM,CAAC;AASjC,UAAU,eAAe;IACvB,OAAO,EAAE,KAAK,CAAC;IACf,EAAE,EAAE,SAAS,CAAC;IACd,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,KAAK,CAAC,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,CAAC;CAC3C;AAiBD;;;;;GAKG;AACH,wBAAsB,gBAAgB,CACpC,aAAa,EAAE,aAAa,EAC5B,OAAO,EAAE,OAAO,GACf,OAAO,CAAC,eAAe,GAAG,SAAS,CAAC,CA+BtC;AA8ED,MAAM,WAAW,eAAe;IAC9B,aAAa,EAAE,aAAa,CAAC;IAC7B,KAAK,EAAE,QAAQ,CAAC;IAChB,MAAM,EAAE,QAAQ,CAAC;CAClB;AAED;;;;;;GAMG;AACH,wBAAsB,QAAQ,CAAC,EAAE,aAAa,EAAE,KAAK,EAAE,MAAM,EAAE,EAAE,eAAe,GAAG,OAAO,CAAC,IAAI,CAAC,CAW/F"}

package/packages/cli/dist/mcp-server.js

@@ -0,0 +1,250 @@
+import { JsonRpcFramer } from '@agenticreplay/mcp-shim';
+import { AgenticReplay } from './api.js';
+import { AGENTICREPLAY_VERSION } from './version.js';
+/**
+ * AgenticReplay as tools an agent can call.
+ *
+ * `@agenticreplay/mcp-shim` records an agent's *own* MCP traffic — it is a tee, so nothing has ever
+ * let an agent ask agenticreplay a question. That is backwards for this product in particular: "replay my
+ * last run and tell me what diverged" is the most useful thing an agent could ask a replay
+ * debugger, and it is a question no observability tool can answer, because a trace is a file.
+ *
+ * Written against the framer the shim already has rather than an SDK. The stdio transport is
+ * newline-delimited JSON-RPC and the surface is four method names, so a runtime dependency here
+ * would cost more than it carries — and this package has none.
+ *
+ * The tool set is deliberately narrow and read-mostly. `agenticreplay_replay` costs nothing and touches no
+ * network; `agenticreplay_compare` spends real tokens, and says so in its own description, because an
+ * agent choosing a tool reads that string and nothing else.
+ */
+/** The version of the MCP spec these messages are shaped for. */
+const PROTOCOL_VERSION = '2025-06-18';
+const METHOD_NOT_FOUND = -32601;
+/** Every tool takes `run`, because "which run" is the only question all of them share. */
+const RUN_ARG = {
+    run: {
+        type: 'string',
+        description: 'Run id, or "last" for the newest recording. Defaults to "last". Replay traces are ' +
+            'skipped when resolving "last", so it means the newest run you actually recorded.',
+    },
+};
+export const MCP_TOOLS = [
+    {
+        name: 'agenticreplay_list_runs',
+        description: 'List every agent run recorded in this project, newest first, with the run it was forked ' +
+            'from where there is one. Start here when you do not already know which run to look at.',
+        inputSchema: { type: 'object', properties: {} },
+    },
+    {
+        name: 'agenticreplay_show_run',
+        description: 'The full timeline of one run: every model turn with its token counts and stop reason, ' +
+            'every tool call with its arguments and result, every shell command with its exit code, ' +
+            'and every file the run changed. This is what tells you why an agent did something, ' +
+            'rather than what it cost.',
+        inputSchema: { type: 'object', properties: { ...RUN_ARG } },
+    },
+    {
+        name: 'agenticreplay_checkpoints',
+        description: 'The points in a run a fork can start from — where the conversation prefix is complete and ' +
+            'the workspace was snapshotted. Use before agenticreplay_compare to pick a fork point.',
+        inputSchema: { type: 'object', properties: { ...RUN_ARG } },
+    },
+    {
+        name: 'agenticreplay_graph',
+        description: 'What caused what in a run, as a list of edges. Each edge says which event produced which, ' +
+            'and whether it is `recorded` — the recorder watched it happen and wrote it into the trace ' +
+            '— or `inferred`, meaning this derived it just now from the rule it names and the trace ' +
+            'does not vouch for it. Pass `to` to get only the chain that produced one event, which is ' +
+            'the shape of an answer to "why did this fail" rather than "what happened".',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                ...RUN_ARG,
+                to: {
+                    type: 'number',
+                    description: 'Narrow to the chain that produced this event seq. Omit for the whole run.',
+                },
+            },
+        },
+    },
+    {
+        name: 'agenticreplay_replay',
+        description: 'Re-run a recording exactly, with the network blocked and no tokens spent, and report what ' +
+            'could not be reproduced: divergences, and requests the recording could not serve. Free ' +
+            'and repeatable. It shows the recorded decisions still reproduce; it cannot show a fresh ' +
+            'run would fail the same way, because the model is not asked again — its recorded ' +
+            'responses are served back.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                ...RUN_ARG,
+                worktree: {
+                    type: 'boolean',
+                    description: 'Replay in a scratch copy instead of over the working tree. Slower, and leaves the ' +
+                        'files you are looking at untouched.',
+                },
+            },
+        },
+    },
+    {
+        name: 'agenticreplay_compare',
+        description: 'Fork one recorded run onto several models from the same checkpoint — same files, same ' +
+            'conversation prefix — and grade each with a command you choose. SPENDS REAL TOKENS and ' +
+            'reaches the network: every model named is actually called. Ask before using it.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                ...RUN_ARG,
+                models: {
+                    type: 'array',
+                    items: { type: 'string' },
+                    description: 'Model ids to compare. Required.',
+                },
+                from: {
+                    type: 'number',
+                    description: 'Checkpoint seq to fork at, from agenticreplay_checkpoints.',
+                },
+                verify: {
+                    type: 'string',
+                    description: 'Shell command whose exit code is the verdict, e.g. "npm test".',
+                },
+            },
+            required: ['models'],
+        },
+    },
+];
+function asRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value)
+        ? value
+        : {};
+}
+/** A tool result in MCP's shape: text content, plus the flag that says it failed. */
+function content(text, isError = false) {
+    return { content: [{ type: 'text', text }], ...(isError ? { isError: true } : {}) };
+}
+function ok(json) {
+    return content(JSON.stringify(json, null, 2));
+}
+/**
+ * Handle one message.
+ *
+ * Returns `undefined` for a notification, which by definition has no id to answer — replying to
+ * one is a protocol error that some clients treat as fatal.
+ */
+export async function handleMcpMessage(agenticreplay, message) {
+    const req = asRecord(message);
+    const { id, method } = req;
+    if (id === undefined)
+        return undefined;
+    const reply = (result) => ({ jsonrpc: '2.0', id, result });
+    const fail = (code, message) => ({
+        jsonrpc: '2.0',
+        id,
+        error: { code, message },
+    });
+    switch (method) {
+        case 'initialize':
+            return reply({
+                protocolVersion: PROTOCOL_VERSION,
+                capabilities: { tools: { listChanged: false } },
+                serverInfo: { name: 'agenticreplay', version: AGENTICREPLAY_VERSION },
+            });
+        case 'ping':
+            return reply({});
+        case 'tools/list':
+            return reply({ tools: MCP_TOOLS });
+        case 'tools/call':
+            return reply(await callTool(agenticreplay, asRecord(req.params)));
+        default:
+            return fail(METHOD_NOT_FOUND, `agenticreplay's MCP server does not implement '${method ?? '(none)'}'`);
+    }
+}
+/**
+ * Run one tool.
+ *
+ * Every failure comes back as `isError` content rather than a JSON-RPC error: the spec draws that
+ * line so a model can read what went wrong and try something else, where a transport error ends
+ * the session. A bad run id is an ordinary answer here, not a crash.
+ */
+async function callTool(agenticreplay, params) {
+    const name = typeof params['name'] === 'string' ? params['name'] : '';
+    const args = asRecord(params['arguments']);
+    const run = typeof args['run'] === 'string' && args['run'] !== '' ? args['run'] : 'last';
+    const tool = MCP_TOOLS.find((t) => t.name === name);
+    if (!tool) {
+        return content(`no such tool '${name}'. agenticreplay serves: ${MCP_TOOLS.map((t) => t.name).join(', ')}`, true);
+    }
+    try {
+        switch (name) {
+            case 'agenticreplay_list_runs':
+                return ok(await agenticreplay.list());
+            case 'agenticreplay_show_run':
+                return ok(await agenticreplay.show(run));
+            case 'agenticreplay_checkpoints':
+                return ok(await agenticreplay.checkpoints(run));
+            case 'agenticreplay_graph': {
+                const to = args['to'];
+                if (to !== undefined && typeof to !== 'number') {
+                    return content('to must be a number', true);
+                }
+                return ok(await agenticreplay.graph(run, to === undefined ? {} : { to }));
+            }
+            case 'agenticreplay_replay': {
+                const worktree = args['worktree'];
+                if (worktree !== undefined && typeof worktree !== 'boolean') {
+                    return content('worktree must be a boolean', true);
+                }
+                return ok(await agenticreplay.replay(run, worktree === true ? { worktree: true } : {}));
+            }
+            case 'agenticreplay_compare': {
+                const models = Array.isArray(args['models'])
+                    ? args['models'].filter((m) => typeof m === 'string')
+                    : [];
+                if (models.length === 0)
+                    return content('compare needs at least one model id', true);
+                const from = args['from'];
+                // Coercing a string here would silently fork from checkpoint 0 and produce a comparison
+                // whose one variable was not the model.
+                if (from !== undefined && typeof from !== 'number') {
+                    return content(`from must be a number, got ${JSON.stringify(from)}`, true);
+                }
+                const verify = args['verify'];
+                if (verify !== undefined && typeof verify !== 'string') {
+                    return content('verify must be a string', true);
+                }
+                return ok(await agenticreplay.compare(run, {
+                    models,
+                    ...(typeof from === 'number' ? { from } : {}),
+                    ...(typeof verify === 'string' ? { verify } : {}),
+                }));
+            }
+            default:
+                return content(`no such tool '${name}'`, true);
+        }
+    }
+    catch (err) {
+        return content(err instanceof Error ? err.message : String(err), true);
+    }
+}
+/**
+ * Serve MCP over a stream pair until the input ends.
+ *
+ * Messages are handled one at a time. Concurrency would buy nothing — every tool here is either a
+ * file read or a subprocess that owns the working tree — and it would let two replays fight over
+ * the same checkout.
+ */
+export async function serveMcp({ agenticreplay, input, output }) {
+    const framer = new JsonRpcFramer();
+    for await (const chunk of input) {
+        for (const frame of framer.push(chunk)) {
+            // A line that is not JSON is a stray log from something upstream, not a message. Dropping it
+            // is the only safe answer: there is no id to report an error against.
+            if (frame.message === undefined)
+                continue;
+            const response = await handleMcpMessage(agenticreplay, frame.message);
+            if (response !== undefined)
+                output.write(`${JSON.stringify(response)}\n`);
+        }
+    }
+}
+//# sourceMappingURL=mcp-server.js.map

package/packages/cli/dist/mcp-server.js.map

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

package/packages/cli/dist/mcp.d.ts

@@ -0,0 +1,126 @@
+import type { TraceWriter } from '@agenticreplay/core';
+import type { McpFrameRecord } from '@agenticreplay/mcp-shim';
+import type { Output } from './out.js';
+export interface McpCapture {
+    /** Path to the rewritten config the agent should be pointed at. */
+    configPath: string;
+    rewritten: string[];
+    skipped: string[];
+    /** Frames observed so far, drained by the recorder. */
+    drain(): Promise<McpFrameRecord[]>;
+}
+/**
+ * A captured frame, as the shim writes it.
+ *
+ * Re-exported rather than redeclared. The version that used to live here named two of the same
+ * fields differently — `server` for `name`, `direction` for `dir` — and since `JSON.parse` casts to
+ * whatever the call site claims, nothing anywhere disagreed: every MCP event went into the trace
+ * with an undefined server, and `direction === 'in'` was false for all of them, so every request
+ * was recorded as a response. A format has one owner, and it is the thing that writes it.
+ */
+export type { McpFrameRecord };
+/**
+ * The recording's own copy of the config it was given, kept beside the frames it produced.
+ *
+ * A replay used to find the source by reading the path out of the `mcp_instrumented` note, and a
+ * path is a poor thing to depend on. It has to survive the trace's redactor — `mkdtemp` and every
+ * CI workspace end in a random segment, and `agenticreplay-int-mcp-stdio-feH8gJ` is 25 characters of
+ * mixed-case base62, so roughly one in seven cleared the entropy sweep's threshold and reached the
+ * trace as `<secret:high_entropy:…>`. `stat` then failed, MCP was dropped for the replay, and the
+ * agent was launched with no `MCP_CONFIG_PATH`: `KeyError` from a recording that was perfectly
+ * good, intermittently, according to what `mkdtemp` picked.
+ *
+ * It also has to still be there, and mean the same thing. Deleting the config, moving it, or
+ * editing a server's command between the recording and the replay all changed what the replay ran
+ * — for a file the operator has no reason to think of as part of the run.
+ *
+ * Keeping the bytes removes both. Nothing has to survive redaction, because this is not in the
+ * trace; nothing outside the run directory has to still exist. It carries the same material as the
+ * rewritten `mcp-config.json` written next to it — same directory, same `0600` — so it is not a
+ * new kind of thing to protect.
+ */
+export declare const MCP_SOURCE_FILENAME = "mcp-source.json";
+/**
+ * The MCP config a *replay* should instrument: the flag if one was given, else whatever the
+ * recording itself used.
+ *
+ * Replay and fork launch the same agent the recording did, so they hit the same blind spot record
+ * had before `--mcp-config` existed: without a config the harness either talks to servers agenticreplay
+ * cannot see, or — for one that requires the variable — does not start at all. The recording knows
+ * the answer; it just had nowhere to write it down, since `manifest.argv` holds only the agent's
+ * own arguments and `--mcp-config` is agenticreplay's.
+ *
+ * The path is read back from the run's own `mcp_instrumented` note. Nothing is re-instrumented from
+ * the *rewritten* config in the parent run directory: its servers already point at the parent's
+ * frames file, so reusing it would append this replay's traffic to the recording it is replaying.
+ */
+export declare function mcpSourceFrom(flagValue: string | undefined, events: {
+    type: string;
+    attrs?: Record<string, unknown>;
+}[]): string | undefined;
+/** Did this run capture MCP at all? Decides whether a replay without a config is worth warning about. */
+export declare function usedMcp(events: {
+    type: string;
+}[]): boolean;
+/**
+ * Set up MCP capture for a replay or a fork, from the flag or from what the recording used.
+ *
+ * Returns undefined — quietly — when the run never had MCP, which is most runs. When it did and the
+ * source config has since moved or been deleted, that is said out loud rather than silently
+ * dropping a capture layer: an absent `mcp.*` in the replay would otherwise read as "the agent made
+ * no MCP calls" instead of "agenticreplay was not looking".
+ */
+export declare function mcpForReplay(args: {
+    str(name: string): string | undefined;
+    bool?(name: string, dflt?: boolean): boolean;
+}, events: {
+    type: string;
+    attrs?: Record<string, unknown>;
+}[], writer: TraceWriter, out: Output, 
+/** The recording's own frames, so the servers are answered from rather than started. */
+recordedFrames?: string, 
+/** The recording's directory, which holds its own copy of the config it was given. */
+recordedRunDir?: string): Promise<McpCapture | undefined>;
+/**
+ * Point the launched agent at the instrumented config.
+ *
+ * Every target harness reads one of these; setting all three costs nothing and avoids making the
+ * user work out which one their agent uses.
+ */
+export declare function pointAtMcpConfig(env: Record<string, string>, configPath: string): void;
+export declare function drainMcpFrames(mcp: McpCapture, writer: TraceWriter, turnAt: (at: number) => number, fallbackTurn: number): Promise<void>;
+/**
+ * Set up MCP capture for a run.
+ *
+ * The mechanism is a config rewrite, not a patch: each stdio server is relaunched through
+ * `agenticreplay-mcp-shim`, a transparent JSON-RPC tee. The agent's own config file is never touched — a
+ * rewritten copy goes in the run directory, and the agent is pointed at that.
+ *
+ * HTTP and SSE servers are deliberately left alone and reported as skipped; they route through the
+ * HTTP proxy instead, and silently dropping them would be worse than not capturing them.
+ */
+export declare function setupMcpCapture(opts: {
+    sourceConfigPath: string;
+    runDir: string;
+    out: Output;
+    /**
+     * Frames to answer from instead of starting the servers.
+     *
+     * Capture was only half of what this layer is for. The reason to record a server's traffic is
+     * that the run stays reproducible once the server is not — the token revoked, the repository
+     * moved, the service retired. Replay re-instrumented the same config and started the real server
+     * again, so an MCP recording could be read but not reproduced, and came apart on the first call
+     * when the server had gone. Pointed at a capture, the shim serves from it and launches nothing.
+     */
+    replayFrames?: string;
+}): Promise<McpCapture | undefined>;
+/**
+ * Exposed for the doctor command: is the shim runnable at all?
+ *
+ * It checks that the thing it launched *is the shim*, not merely that a process started and
+ * stopped. Asking only for a clean exit is what let doctor vouch for a resolution that had landed
+ * on the library: that module exits 0 having done nothing, which is indistinguishable from success
+ * unless you look at what it said.
+ */
+export declare function shimIsRunnable(): Promise<boolean>;
+//# sourceMappingURL=mcp.d.ts.map

package/packages/cli/dist/mcp.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mcp.d.ts","sourceRoot":"","sources":["../src/mcp.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAC;AAEvD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,yBAAyB,CAAC;AAC9D,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,UAAU,CAAC;AAEvC,MAAM,WAAW,UAAU;IACzB,mEAAmE;IACnE,UAAU,EAAE,MAAM,CAAC;IACnB,SAAS,EAAE,MAAM,EAAE,CAAC;IACpB,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,uDAAuD;IACvD,KAAK,IAAI,OAAO,CAAC,cAAc,EAAE,CAAC,CAAC;CACpC;AAED;;;;;;;;GAQG;AACH,YAAY,EAAE,cAAc,EAAE,CAAC;AAE/B;;;;;;;;;;;;;;;;;;;GAmBG;AACH,eAAO,MAAM,mBAAmB,oBAAoB,CAAC;AAErD;;;;;;;;;;;;;GAaG;AAEH,wBAAgB,aAAa,CAC3B,SAAS,EAAE,MAAM,GAAG,SAAS,EAC7B,MAAM,EAAE;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;CAAE,EAAE,GAC1D,MAAM,GAAG,SAAS,CAQpB;AAED,yGAAyG;AACzG,wBAAgB,OAAO,CAAC,MAAM,EAAE;IAAE,IAAI,EAAE,MAAM,CAAA;CAAE,EAAE,GAAG,OAAO,CAE3D;AAED;;;;;;;GAOG;AACH,wBAAsB,YAAY,CAChC,IAAI,EAAE;IAAE,GAAG,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAAC;IAAC,IAAI,CAAC,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,OAAO,GAAG,OAAO,CAAA;CAAE,EAC7F,MAAM,EAAE;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;CAAE,EAAE,EAC3D,MAAM,EAAE,WAAW,EACnB,GAAG,EAAE,MAAM;AACX,wFAAwF;AACxF,cAAc,CAAC,EAAE,MAAM;AACvB,sFAAsF;AACtF,cAAc,CAAC,EAAE,MAAM,GACtB,OAAO,CAAC,UAAU,GAAG,SAAS,CAAC,CAuCjC;AAED;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,EAAE,UAAU,EAAE,MAAM,GAAG,IAAI,CAItF;AAqCD,wBAAsB,cAAc,CAClC,GAAG,EAAE,UAAU,EACf,MAAM,EAAE,WAAW,EACnB,MAAM,EAAE,CAAC,EAAE,EAAE,MAAM,KAAK,MAAM,EAC9B,YAAY,EAAE,MAAM,GACnB,OAAO,CAAC,IAAI,CAAC,CAgBf;AAED;;;;;;;;;GASG;AACH,wBAAsB,eAAe,CAAC,IAAI,EAAE;IAC1C,gBAAgB,EAAE,MAAM,CAAC;IACzB,MAAM,EAAE,MAAM,CAAC;IACf,GAAG,EAAE,MAAM,CAAC;IACZ;;;;;;;;OAQG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB,GAAG,OAAO,CAAC,UAAU,GAAG,SAAS,CAAC,CA0DlC;AAwBD;;;;;;;GAOG;AACH,wBAAsB,cAAc,IAAI,OAAO,CAAC,OAAO,CAAC,CAqBvD"}