agentfootprint 1.22.0 → 2.0.1

package/dist/esm/lib/call/parseResponseStage.js

@@ -1,63 +0,0 @@
-/**
- * ParseResponse stage — extract ParsedResponse from AdapterResult.
- *
- * Also appends the assistant message to conversation history.
- *
- * Reads from scope:
- *   - adapterResult (set by CallLLM)
- *
- * Writes to scope:
- *   - parsedResponse (hasToolCalls, toolCalls[], content)
- *   - hasToolCalls (flat mirror so RouteResponse can use decide() filter form)
- *   - messages (appends assistant message)
- *   - responseType (narrative summary of the response)
- */
-import { assistantMessage } from '../../types';
-import { appendMessage } from '../../memory';
-/**
- * ParseResponse stage function.
- * Stateless — no factory needed.
- */
-export function parseResponseStage(scope) {
-    const result = scope.adapterResult;
-    if (!result) {
-        throw new Error('ParseResponse: no adapter result in scope');
-    }
-    if (result.type === 'error') {
-        throw new Error(`LLM call failed: [${result.code}] ${result.message}`);
-    }
-    const parsed = {
-        hasToolCalls: result.type === 'tools',
-        toolCalls: result.type === 'tools' ? result.toolCalls : [],
-        content: result.content,
-    };
-    scope.parsedResponse = parsed;
-    // Flat mirror — enables RouteResponse's decide() to use filter form
-    // (`{ hasToolCalls: { eq: true } }`) which captures structured
-    // `{ key, op, threshold, actual, result }` evidence in the commit log,
-    // vs. the opaque function-form match boolean.
-    scope.hasToolCalls = parsed.hasToolCalls;
-    // Append assistant message to conversation
-    const messages = scope.messages ?? [];
-    const asstMsg = assistantMessage(result.content, result.type === 'tools' ? result.toolCalls : undefined);
-    scope.messages = appendMessage(messages, asstMsg);
-    // Write summary for narrative visibility — include arguments so debuggers
-    // can see at a glance whether the LLM passed required fields. Names alone
-    // hide the common failure mode of retrying with empty / wrong args.
-    if (parsed.hasToolCalls) {
-        const signatures = parsed.toolCalls
-            .map((tc) => {
-            const argsStr = JSON.stringify(tc.arguments ?? {});
-            // Tight cap — narrative line, not a full dump
-            const truncated = argsStr.length > 120 ? argsStr.slice(0, 117) + '...' : argsStr;
-            return `${tc.name}(${truncated})`;
-        })
-            .join(', ');
-        scope.responseType = `tool_calls: [${signatures}]`;
-    }
-    else {
-        const preview = result.content.length > 80 ? result.content.slice(0, 80) + '...' : result.content;
-        scope.responseType = `final: "${preview}"`;
-    }
-}
-//# sourceMappingURL=parseResponseStage.js.map

package/dist/esm/lib/call/parseResponseStage.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"parseResponseStage.js","sourceRoot":"","sources":["../../../../src/lib/call/parseResponseStage.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAIH,OAAO,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAC/C,OAAO,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAE7C;;;GAGG;AACH,MAAM,UAAU,kBAAkB,CAAC,KAAiC;IAClE,MAAM,MAAM,GAAG,KAAK,CAAC,aAAa,CAAC;IAEnC,IAAI,CAAC,MAAM,EAAE,CAAC;QACZ,MAAM,IAAI,KAAK,CAAC,2CAA2C,CAAC,CAAC;IAC/D,CAAC;IAED,IAAI,MAAM,CAAC,IAAI,KAAK,OAAO,EAAE,CAAC;QAC5B,MAAM,IAAI,KAAK,CAAC,qBAAqB,MAAM,CAAC,IAAI,KAAK,MAAM,CAAC,OAAO,EAAE,CAAC,CAAC;IACzE,CAAC;IAED,MAAM,MAAM,GAAG;QACb,YAAY,EAAE,MAAM,CAAC,IAAI,KAAK,OAAO;QACrC,SAAS,EAAE,MAAM,CAAC,IAAI,KAAK,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC,CAAC,EAAE;QAC1D,OAAO,EAAE,MAAM,CAAC,OAAO;KACxB,CAAC;IAEF,KAAK,CAAC,cAAc,GAAG,MAAM,CAAC;IAC9B,oEAAoE;IACpE,+DAA+D;IAC/D,uEAAuE;IACvE,8CAA8C;IAC9C,KAAK,CAAC,YAAY,GAAG,MAAM,CAAC,YAAY,CAAC;IAEzC,2CAA2C;IAC3C,MAAM,QAAQ,GAAG,KAAK,CAAC,QAAQ,IAAI,EAAE,CAAC;IACtC,MAAM,OAAO,GAAG,gBAAgB,CAC9B,MAAM,CAAC,OAAO,EACd,MAAM,CAAC,IAAI,KAAK,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC,CAAC,SAAS,CACvD,CAAC;IACF,KAAK,CAAC,QAAQ,GAAG,aAAa,CAAC,QAAQ,EAAE,OAAO,CAAC,CAAC;IAElD,0EAA0E;IAC1E,0EAA0E;IAC1E,oEAAoE;IACpE,IAAI,MAAM,CAAC,YAAY,EAAE,CAAC;QACxB,MAAM,UAAU,GAAG,MAAM,CAAC,SAAS;aAChC,GAAG,CAAC,CAAC,EAAE,EAAE,EAAE;YACV,MAAM,OAAO,GAAG,IAAI,CAAC,SAAS,CAAC,EAAE,CAAC,SAAS,IAAI,EAAE,CAAC,CAAC;YACnD,8CAA8C;YAC9C,MAAM,SAAS,GAAG,OAAO,CAAC,MAAM,GAAG,GAAG,CAAC,CAAC,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,EAAE,GAAG,CAAC,GAAG,KAAK,CAAC,CAAC,CAAC,OAAO,CAAC;YACjF,OAAO,GAAG,EAAE,CAAC,IAAI,IAAI,SAAS,GAAG,CAAC;QACpC,CAAC,CAAC;aACD,IAAI,CAAC,IAAI,CAAC,CAAC;QACd,KAAK,CAAC,YAAY,GAAG,gBAAgB,UAAU,GAAG,CAAC;IACrD,CAAC;SAAM,CAAC;QACN,MAAM,OAAO,GACX,MAAM,CAAC,OAAO,CAAC,MAAM,GAAG,EAAE,CAAC,CAAC,CAAC,MAAM,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,GAAG,KAAK,CAAC,CAAC,CAAC,MAAM,CAAC,OAAO,CAAC;QACpF,KAAK,CAAC,YAAY,GAAG,WAAW,OAAO,GAAG,CAAC;IAC7C,CAAC;AACH,CAAC"}

package/dist/esm/lib/call/streamingCallLLMStage.js

@@ -1,152 +0,0 @@
-/**
- * Streaming CallLLM stage — bridges LLMProvider.chatStream() with footprintjs StreamCallback
- * and emits AgentStreamEvents for consumer visibility.
- *
- * Events emitted:
- *   - llm_start { iteration } — before the LLM call
- *   - token { content } — each text chunk from the LLM
- *   - thinking { content } — extended thinking blocks (Anthropic)
- *   - llm_end { iteration, toolCallCount, content, model, latencyMs } — after LLM completes
- */
-import { STREAM_EMIT_PREFIX } from '../../streaming';
-import { normalizeAdapterResponse } from './helpers';
-/**
- * Create a streaming-capable CallLLM stage function. Stream lifecycle
- * events (`llm_start`, `token`, `thinking`, `llm_end`) flow through
- * the emit channel — see `StreamEventRecorder` for the plumbing.
- */
-export function createStreamingCallLLMStage(provider, options) {
-    const responseFormat = options?.responseFormat;
-    return async (scope, _breakFn, streamCallback) => {
-        const messages = scope.messages ?? [];
-        const tools = scope.toolDescriptions ?? [];
-        const signal = scope.$getEnv?.()?.signal;
-        const callOpts = {
-            ...(tools.length > 0 ? { tools } : {}),
-            ...(signal ? { signal } : {}),
-            ...(responseFormat ? { responseFormat } : {}),
-        };
-        const iteration = (scope.loopCount ?? 0) + 1;
-        const startMs = Date.now();
-        scope.$emit(`${STREAM_EMIT_PREFIX}llm_start`, { type: 'llm_start', iteration });
-        // ── Emit: request-side ─────────────────────────────────────────────
-        // Mirror of callLLMStage.ts — surface the EXACT shape being sent so
-        // attached EmitRecorders (including CombinedNarrativeRecorder) render
-        // it inline under the CallLLM stage. Critical for debugging stuck
-        // patterns like "LLM returns empty args every turn".
-        scope.$emit('agentfootprint.llm.request', {
-            iteration,
-            messageCount: messages.length,
-            messageRoles: messages.map((m) => m.role),
-            toolCount: tools.length,
-            toolNames: tools.map((t) => t.name),
-            toolsWithRequired: tools.map((t) => ({
-                name: t.name,
-                description: t.description,
-                required: t.inputSchema?.required ?? [],
-            })),
-            hasResponseFormat: !!responseFormat,
-        });
-        // If streaming is available and callback is injected, use chatStream
-        if (streamCallback && provider.chatStream) {
-            const contentParts = [];
-            const thinkingParts = [];
-            const toolCalls = [];
-            let usage;
-            for await (const chunk of provider.chatStream(messages, Object.keys(callOpts).length > 0 ? callOpts : undefined)) {
-                switch (chunk.type) {
-                    case 'thinking':
-                        if (chunk.content) {
-                            thinkingParts.push(chunk.content);
-                            scope.$emit(`${STREAM_EMIT_PREFIX}thinking`, {
-                                type: 'thinking',
-                                content: chunk.content,
-                            });
-                        }
-                        break;
-                    case 'token':
-                        if (chunk.content) {
-                            contentParts.push(chunk.content);
-                            streamCallback(chunk.content);
-                        }
-                        break;
-                    case 'tool_call':
-                        if (chunk.toolCall) {
-                            toolCalls.push(chunk.toolCall);
-                        }
-                        break;
-                    case 'usage':
-                        if (chunk.usage) {
-                            usage = chunk.usage;
-                        }
-                        break;
-                    case 'done':
-                        break;
-                }
-            }
-            const content = contentParts.join('');
-            const thinking = thinkingParts.length > 0 ? thinkingParts.join('') : undefined;
-            const response = {
-                content,
-                toolCalls: toolCalls.length > 0 ? toolCalls : undefined,
-                usage,
-                model: 'model' in provider ? provider.model : undefined,
-                thinking,
-            };
-            scope.adapterRawResponse = response;
-            scope.adapterResult = normalizeAdapterResponse(response);
-            const latencyMs = Date.now() - startMs;
-            scope.$emit('agentfootprint.llm.response', {
-                iteration,
-                model: response.model,
-                stopReason: response.finishReason,
-                usage: response.usage,
-                content: response.content,
-                toolCalls: (response.toolCalls ?? []).map((tc) => ({
-                    name: tc.name,
-                    arguments: tc.arguments,
-                })),
-                latencyMs,
-            });
-            scope.$emit(`${STREAM_EMIT_PREFIX}llm_end`, {
-                type: 'llm_end',
-                iteration,
-                toolCallCount: toolCalls.length,
-                content,
-                model: response.model,
-                latencyMs,
-                usage: response.usage,
-                stopReason: response.finishReason,
-            });
-            return;
-        }
-        // Fallback: non-streaming chat()
-        const response = await provider.chat(messages, callOpts);
-        scope.adapterRawResponse = response;
-        scope.adapterResult = normalizeAdapterResponse(response);
-        const latencyMs = Date.now() - startMs;
-        scope.$emit('agentfootprint.llm.response', {
-            iteration,
-            model: response.model,
-            stopReason: response.finishReason,
-            usage: response.usage,
-            content: response.content,
-            toolCalls: (response.toolCalls ?? []).map((tc) => ({
-                name: tc.name,
-                arguments: tc.arguments,
-            })),
-            latencyMs,
-        });
-        scope.$emit(`${STREAM_EMIT_PREFIX}llm_end`, {
-            type: 'llm_end',
-            iteration,
-            toolCallCount: response.toolCalls?.length ?? 0,
-            content: response.content,
-            model: response.model,
-            latencyMs,
-            usage: response.usage,
-            stopReason: response.finishReason,
-        });
-    };
-}
-//# sourceMappingURL=streamingCallLLMStage.js.map

package/dist/esm/lib/call/streamingCallLLMStage.js.map

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

package/dist/esm/lib/call/toolExecutionSubflow.js

@@ -1,198 +0,0 @@
-/**
- * Tool Execution Subflow — executes tool calls as a visible subflow.
- *
- * Replaces inline executeToolCalls() in HandleResponse with a proper subflow
- * that appears in the flowchart and narrative. Enables:
- *   - BTS drill-down into tool execution
- *   - Per-tool visibility in narrative
- *   - Future: parallel fork stages for individual tool calls
- *
- * The subflow has a single stage (ExecuteToolCalls) that runs all tools
- * sequentially and appends results to messages.
- *
- * Config (registry, toolProvider) is closed over at build time — not
- * passed through inputMapper.
- */
-import { flowChart } from 'footprintjs';
-import { STREAM_EMIT_PREFIX } from '../../streaming';
-import { executeToolCalls } from './helpers';
-// ── Builder ──────────────────────────────────────────────────
-/**
- * Build the tool execution subflow.
- *
- * Registry and toolProvider are closed over — they don't travel
- * through inputMapper. Only scope state (parsedResponse, messages,
- * loopCount) is mapped.
- */
-export function buildToolExecutionSubflow(config) {
-    const { registry, toolProvider, instructionConfig, parallel, maxIdenticalFailures } = config;
-    const executeStageFn = async (scope) => {
-        const parsed = scope.parsedResponse;
-        const loopCount = scope.currentLoopCount ?? 0;
-        const maxIter = scope.maxIterations ?? 10;
-        // Defense-in-depth: the RouteResponse decider already routes to 'final'
-        // when loopCount >= maxIter, but this guard protects against standalone
-        // subflow usage without a preceding decider.
-        if (!parsed?.toolCalls?.length || loopCount >= maxIter) {
-            scope.toolResultMessages = [];
-            scope.updatedLoopCount = loopCount;
-            return;
-        }
-        const messages = scope.currentMessages ?? [];
-        // $getEnv() is a TypedScope proxy method — always available, not in state interface
-        const signal = scope.$getEnv()?.signal;
-        // Copy decision scope for tool-driven mutations.
-        // Two mutation paths feed into this ref:
-        //   1. `decide()` inside tool flowcharts — mutates the ref in-place
-        //   2. `ToolResult.decisionUpdate` — shallow-merged by executeToolCalls
-        // Always allocate `{}` when the scope arrives without a decision so
-        // autoActivate-style decision writes land on the first turn too
-        // (footprintjs inputMapper drops empty-object decisions; without an
-        // allocation here, a skill's `read_skill` decisionUpdate would be
-        // dropped on the first iteration — surfaced by the 1.17.0 test
-        // `autoActivate — scenario: end-to-end: read_skill flips decision`).
-        const rawDecision = scope.currentDecision;
-        const decisionRef = rawDecision ? { ...rawDecision } : {};
-        // `helpers.executeToolCalls` takes an `onStreamEvent` callback in its
-        // instruction config for `tool_start` / `tool_end` lifecycle events.
-        // We construct that callback as a thin scope-emit wrapper so events
-        // flow through the same emit channel as everything else — zero
-        // closure capture of per-run handlers. `StreamEventRecorder`
-        // (attached by AgentRunner) consumes them and forwards to `onEvent`.
-        const emitAsScope = (event) => {
-            scope.$emit(`${STREAM_EMIT_PREFIX}${event.type}`, event);
-        };
-        // Context-engineering emit: wrap onInstructionsFired so when per-tool
-        // agent instructions fire, Lens can tag the iteration with
-        // "instructions → sys prompt · N". Preserves the original callback
-        // (which routes to InstructionRecorder) — we're a tee, not a replacement.
-        const userOnInstructionsFired = instructionConfig?.onInstructionsFired;
-        const teeInstructionsFired = (toolId, fired) => {
-            // Forward to the original recorder callback first.
-            userOnInstructionsFired?.(toolId, fired);
-            // Then emit the context-engineering event.
-            //
-            // Teaching detail: instructions inject guidance AFTER a specific
-            // tool result — they land in the recency window of the next
-            // iteration (effectively the system prompt slot at that point,
-            // since the guidance is authoritative app-controlled text not
-            // part of the conversation). Char-delta approximated from the
-            // resolved injection content length.
-            const totalChars = fired.reduce((n, f) => {
-                const c = f.resolvedFollowUp?.description ??
-                    f.followUp?.description ??
-                    '';
-                return n + (typeof c === 'string' ? c.length : 0);
-            }, 0);
-            scope.$emit('agentfootprint.context.instructions.fired', {
-                slot: 'system-prompt',
-                toolId,
-                count: fired.length,
-                ids: fired.map((f) => f.id),
-                deltaCount: {
-                    // Approximate — falls back to the count of instructions × 1
-                    // if we can't read lengths (better than no signal).
-                    systemPromptChars: totalChars > 0 ? totalChars : fired.length,
-                },
-            });
-        };
-        const effectiveInstructionConfig = instructionConfig
-            ? {
-                ...instructionConfig,
-                onStreamEvent: emitAsScope,
-                onInstructionsFired: teeInstructionsFired,
-            }
-            : {
-                instructionsByToolId: new Map(),
-                onStreamEvent: emitAsScope,
-            };
-        const { messages: resultMessages, askHumanPause } = await executeToolCalls(parsed.toolCalls, registry, messages, toolProvider, signal, effectiveInstructionConfig, decisionRef, {
-            ...(parallel ? { parallel: true } : {}),
-            ...(maxIdenticalFailures !== undefined ? { maxIdenticalFailures } : {}),
-        });
-        // Output DELTA only — footprintjs applyOutputMapping concatenates arrays,
-        // so the parent's outputMapper maps this to `messages` and concat appends correctly.
-        scope.toolResultMessages = resultMessages.slice(messages.length);
-        scope.updatedLoopCount = (scope.currentLoopCount ?? 0) + 1;
-        // Write mutated decision as output so it flows through outputMapper.
-        // Always writes — even if no decide() and no decisionUpdate ran, the
-        // decision may need to propagate for the next iteration's InstructionsToLLM.
-        scope.updatedDecision = decisionRef;
-        // Context-engineering emit: detect a skill activation. A successful
-        // `read_skill(id)` call writes `{ currentSkill: id }` (or the custom
-        // stateField) via decisionUpdate. If decisionRef now carries a new
-        // currentSkill, the skill just became active for the NEXT iteration.
-        //
-        // Teaching-surface detail: a skill activation does TWO things under
-        // the hood — (1) the skill body appears in the NEXT iteration's
-        // system prompt (via the SystemPrompt slot's provider re-resolving
-        // under Dynamic ReAct OR on next turn's assembly for Regular), and
-        // (2) any `activeWhen` tools gated on the skill id now appear in
-        // the Tools slot. We emit BOTH deltas so Lens can show the counter
-        // jump on both slots.
-        const priorSkill = rawDecision?.currentSkill;
-        const nextSkill = decisionRef.currentSkill;
-        if (nextSkill !== priorSkill && typeof nextSkill === 'string' && nextSkill.length > 0) {
-            // Read the resolved tool result to figure out how big the skill
-            // body is + whether the skill carries its own tools. Skill
-            // activation flows through `read_skill` whose `content` is the
-            // skill's body text. We don't have direct access here to the
-            // registry / skill metadata, so approximate via the tool result.
-            const skillToolResult = parsed.toolCalls.find((tc) => tc.name === 'read_skill');
-            // eslint-disable-next-line @typescript-eslint/no-explicit-any
-            const bodyChars = (() => {
-                // Find the matching result in resultMessages (tool-role message).
-                const resultMsg = resultMessages.find((m) => m.role === 'tool' &&
-                    m.toolCallId === skillToolResult?.id);
-                const c = resultMsg?.content;
-                if (typeof c === 'string')
-                    return c.length;
-                return undefined;
-            })();
-            scope.$emit('agentfootprint.context.skill.activated', {
-                // Skills touch TWO slots simultaneously. Primary slot = system-prompt
-                // (skill body), secondary = tools (skill-gated tools). Lens UI
-                // tags both; the ledger delta reflects both.
-                slot: 'system-prompt',
-                skillId: nextSkill,
-                previousSkillId: priorSkill,
-                deltaCount: {
-                    // Skill body gets concatenated into the system prompt on the
-                    // next iteration's assembly — its char count is the delta.
-                    ...(bodyChars !== undefined && { systemPromptChars: bodyChars }),
-                    // Skill-gated tools appear in the Tools slot. The exact count
-                    // is a registry concern the tool subflow doesn't own; surface
-                    // it as unknown-positive with a flag so Lens can render
-                    // "+? tools" until a later enrichment pass carries the number.
-                    toolsFromSkill: true,
-                },
-            });
-        }
-        // If ask_human was called, store pause data on scope and return it.
-        // Engine: non-void return from isPausable stage → PauseSignal with this as pauseData.
-        if (askHumanPause) {
-            scope.askHumanPause = askHumanPause;
-            return askHumanPause;
-        }
-        return undefined;
-    };
-    const resumeStageFn = (scope, humanResponse) => {
-        const pauseInfo = scope.askHumanPause;
-        if (pauseInfo && humanResponse !== undefined) {
-            const toolCallId = pauseInfo.toolCallId;
-            scope.toolResultMessages = (scope.toolResultMessages ?? []).map((msg) => msg.role === 'tool' && msg.toolCallId === toolCallId
-                ? { ...msg, content: String(humanResponse) }
-                : msg);
-        }
-    };
-    // Pausable root stage — flowChart() accepts PausableHandler directly (footprintjs v4.4.1+).
-    // Cast needed: executeStageFn has wider return type (includes pause data object)
-    // than PausableHandler.execute's generic — this is the standard pattern for stages
-    // that conditionally return pause data.
-    const handler = {
-        execute: executeStageFn,
-        resume: resumeStageFn,
-    };
-    return flowChart('ExecuteToolCalls', handler, 'execute-tool-calls', undefined, 'Execute tool calls and append results to conversation').build();
-}
-//# sourceMappingURL=toolExecutionSubflow.js.map

package/dist/esm/lib/call/toolExecutionSubflow.js.map

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

package/dist/esm/lib/call/types.js

@@ -1,10 +0,0 @@
-/**
- * Call module types.
- *
- * The call module contains the three stages that happen AFTER the three API slots:
- *   CallLLM → ParseResponse → HandleResponse
- *
- * These stages consume what the slots wrote to scope and produce the LLM result.
- */
-export {};
-//# sourceMappingURL=types.js.map

package/dist/esm/lib/call/types.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../../src/lib/call/types.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG"}

package/dist/esm/lib/concepts/Agent.js

@@ -1,7 +0,0 @@
-/**
- * Agent — re-exports builder and runner from split files.
- * Preserves backward compatibility for imports.
- */
-export { Agent } from './AgentBuilder';
-export { AgentRunner } from './AgentRunner';
-//# sourceMappingURL=Agent.js.map

package/dist/esm/lib/concepts/Agent.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"Agent.js","sourceRoot":"","sources":["../../../../src/lib/concepts/Agent.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,OAAO,EAAE,KAAK,EAAE,MAAM,gBAAgB,CAAC;AAEvC,OAAO,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC"}