wotann 0.5.39 → 0.5.41

package/dist/runtime-hooks/ttsr-runner.d.ts

@@ -0,0 +1,129 @@
+/**
+ * TTSR Runner - per-token rule evaluation.
+ *
+ * The Runner is the PURE LOGIC core of WOTANN's time-traveling
+ * streamed rules. It accepts streaming tokens labeled with a
+ * StreamContext, buffers them per stream kind, and emits a
+ * `TTSRTrigger` whenever a rule's regex matches its scoped buffer.
+ *
+ * It deliberately does NOT control the stream. It does not abort,
+ * does not retry, does not call the orchestrator. The middleware in
+ * `src/middleware/ttsr.ts` (which Anthropic / OpenAI / Ollama
+ * stream decoders consult) is responsible for converting a trigger
+ * into an actual abort + retry decision.
+ *
+ * That separation is critical: it lets the Runner be tested with
+ * zero provider mocking, and lets the orchestrator decide retry
+ * semantics (discard vs keep partial, retry once vs fall back to a
+ * smaller model, etc.) independently.
+ *
+ * See:
+ *   - oh-my-pi packages/coding-agent/src/export/ttsr.ts          (reference TtsrManager)
+ *   - oh-my-pi packages/coding-agent/src/modes/controllers/event-controller.ts:631 (`ttsr_triggered` event consumer)
+ */
+import type { TTSRRule } from "./ttsr-rule.js";
+import { type StreamContext, type StreamKind } from "./ttsr-scope.js";
+/**
+ * A trigger emitted by `observeToken` when a rule fires.
+ *
+ * The orchestrator turns this into:
+ *   1. stream.abort()
+ *   2. retry the model turn with `injectionBody` wrapped in
+ *      `<system-reminder>...</system-reminder>` appended to the
+ *      previous system prompt
+ *   3. on retry success, call `acknowledgeFired(rule.id)` so
+ *      one-shot rules do not re-fire on the same session.
+ */
+export interface TTSRTrigger {
+    readonly rule: TTSRRule;
+    readonly matchedAt: number;
+    readonly matchedText: string;
+    readonly context: StreamContext;
+    readonly bufferKey: string;
+}
+/**
+ * Snapshot used by tests and by the middleware for diagnostics.
+ */
+export interface TTSRRunnerState {
+    readonly tokenCount: number;
+    readonly bufferKeys: readonly string[];
+    readonly firedRuleIds: readonly string[];
+    readonly registeredRuleIds: readonly string[];
+}
+export interface TTSRRunnerOptions {
+    readonly rules: readonly TTSRRule[];
+    /**
+     * Maximum buffer size per stream key. When exceeded, the buffer
+     * is sliced down to half-window. Default: 32 KiB. Setting to 0
+     * disables the cap (use with caution on long turns).
+     */
+    readonly maxBufferBytes?: number;
+}
+/**
+ * Runner instance.
+ *
+ * - Constructed with a frozen `rules` array (no hot reload by
+ *   design - reload by building a new runner).
+ * - One instance per session. Reuse across turns is fine; reuse
+ *   across sessions is NOT (fire records would leak).
+ */
+export declare class TTSRRunner {
+    #private;
+    constructor(opts: TTSRRunnerOptions);
+    /**
+     * Feed one streamed token (or chunk) labeled with its stream
+     * context. Returns a `TTSRTrigger` when ANY rule fires, otherwise
+     * `null`.
+     *
+     * Multiple rules can match in principle; the first match wins to
+     * keep the orchestrator wire simple. Callers wanting all matches
+     * can call `observeAll` (below).
+     */
+    observeToken(token: string, ctx: StreamContext): TTSRTrigger | null;
+    /**
+     * Same as `observeToken` but returns every matching rule on the
+     * combined buffer. Useful when an orchestrator wants to inject
+     * multiple system reminders in one retry.
+     */
+    observeAll(token: string, ctx: StreamContext): readonly TTSRTrigger[];
+    /**
+     * Notify the runner that the orchestrator processed the trigger
+     * for `ruleId`. After this call, one-shot rules stop firing for
+     * the rest of the session.
+     *
+     * Non-one-shot rules are unaffected.
+     *
+     * Safe to call repeatedly with the same id (idempotent).
+     */
+    acknowledgeFired(ruleId: string): void;
+    /**
+     * Build the injection body the orchestrator should hand back to
+     * the model as a system reminder.
+     *
+     * Currently just `trigger.rule.body`, but kept as a method so we
+     * can later add metadata (matched text, file path, etc.) without
+     * changing the orchestrator wire.
+     */
+    getInjectionBody(trigger: TTSRTrigger): string;
+    /**
+     * Clear all per-turn buffers. Call between turns so cross-turn
+     * matches do not leak. Does NOT clear the one-shot fired set -
+     * one-shot is per-session.
+     */
+    resetBuffers(): void;
+    /**
+     * Clear EVERYTHING for a new session: buffers AND fired records.
+     * The runner becomes equivalent to a freshly constructed one.
+     */
+    reset(): void;
+    /** Inspect runner state. Used by middleware diagnostics + tests. */
+    getState(): TTSRRunnerState;
+    /** Has this rule already fired (and been acknowledged) this session? */
+    hasFired(ruleId: string): boolean;
+    /**
+     * Convenience: peek the buffer for a stream key. Returns empty
+     * string when nothing has been buffered yet. Read-only.
+     */
+    peekBuffer(kindOrKey: StreamKind | string, toolName?: string): string;
+}
+//# sourceMappingURL=ttsr-runner.d.ts.map

package/dist/runtime-hooks/ttsr-runner.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ttsr-runner.d.ts","sourceRoot":"","sources":["../../src/runtime-hooks/ttsr-runner.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,gBAAgB,CAAC;AAC/C,OAAO,EAIL,KAAK,aAAa,EAClB,KAAK,UAAU,EAChB,MAAM,iBAAiB,CAAC;AAEzB;;;;;;;;;;GAUG;AACH,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAC;IACxB,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,OAAO,EAAE,aAAa,CAAC;IAChC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;CAC5B;AAED;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,UAAU,EAAE,SAAS,MAAM,EAAE,CAAC;IACvC,QAAQ,CAAC,YAAY,EAAE,SAAS,MAAM,EAAE,CAAC;IACzC,QAAQ,CAAC,iBAAiB,EAAE,SAAS,MAAM,EAAE,CAAC;CAC/C;AAED,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,KAAK,EAAE,SAAS,QAAQ,EAAE,CAAC;IACpC;;;;OAIG;IACH,QAAQ,CAAC,cAAc,CAAC,EAAE,MAAM,CAAC;CAClC;AA0BD;;;;;;;GAOG;AACH,qBAAa,UAAU;;gBAOT,IAAI,EAAE,iBAAiB;IAYnC;;;;;;;;OAQG;IACH,YAAY,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,EAAE,aAAa,GAAG,WAAW,GAAG,IAAI;IAKnE;;;;OAIG;IACH,UAAU,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,EAAE,aAAa,GAAG,SAAS,WAAW,EAAE;IAoCrE;;;;;;;;OAQG;IACH,gBAAgB,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI;IAKtC;;;;;;;OAOG;IACH,gBAAgB,CAAC,OAAO,EAAE,WAAW,GAAG,MAAM;IAI9C;;;;OAIG;IACH,YAAY,IAAI,IAAI;IAKpB;;;OAGG;IACH,KAAK,IAAI,IAAI;IAMb,oEAAoE;IACpE,QAAQ,IAAI,eAAe;IAS3B,wEAAwE;IACxE,QAAQ,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO;IAIjC;;;OAGG;IACH,UAAU,CAAC,SAAS,EAAE,UAAU,GAAG,MAAM,EAAE,QAAQ,CAAC,EAAE,MAAM,GAAG,MAAM;CAWtE"}

package/dist/runtime-hooks/ttsr-runner.js

@@ -0,0 +1,193 @@
+/**
+ * TTSR Runner - per-token rule evaluation.
+ *
+ * The Runner is the PURE LOGIC core of WOTANN's time-traveling
+ * streamed rules. It accepts streaming tokens labeled with a
+ * StreamContext, buffers them per stream kind, and emits a
+ * `TTSRTrigger` whenever a rule's regex matches its scoped buffer.
+ *
+ * It deliberately does NOT control the stream. It does not abort,
+ * does not retry, does not call the orchestrator. The middleware in
+ * `src/middleware/ttsr.ts` (which Anthropic / OpenAI / Ollama
+ * stream decoders consult) is responsible for converting a trigger
+ * into an actual abort + retry decision.
+ *
+ * That separation is critical: it lets the Runner be tested with
+ * zero provider mocking, and lets the orchestrator decide retry
+ * semantics (discard vs keep partial, retry once vs fall back to a
+ * smaller model, etc.) independently.
+ *
+ * See:
+ *   - oh-my-pi packages/coding-agent/src/export/ttsr.ts          (reference TtsrManager)
+ *   - oh-my-pi packages/coding-agent/src/modes/controllers/event-controller.ts:631 (`ttsr_triggered` event consumer)
+ */
+import { matchScope, parseScope, } from "./ttsr-scope.js";
+const DEFAULT_MAX_BUFFER_BYTES = 32 * 1024;
+/**
+ * Determine the buffer key for a given stream context.
+ *
+ * - text   -> "text"
+ * - thinking -> "thinking"
+ * - tool   -> "tool:<name>" or just "tool" if unnamed
+ *
+ * Keeping buffers isolated per context prevents prose-side matches
+ * from bleeding into tool-call buffers and vice versa.
+ */
+function bufferKeyFor(ctx) {
+    if (ctx.kind === "text")
+        return "text";
+    if (ctx.kind === "thinking")
+        return "thinking";
+    const tool = ctx.toolName?.trim().toLowerCase();
+    return tool ? `tool:${tool}` : "tool";
+}
+/**
+ * Runner instance.
+ *
+ * - Constructed with a frozen `rules` array (no hot reload by
+ *   design - reload by building a new runner).
+ * - One instance per session. Reuse across turns is fine; reuse
+ *   across sessions is NOT (fire records would leak).
+ */
+export class TTSRRunner {
+    #compiled;
+    #buffers = new Map();
+    #fired = new Set();
+    #maxBufferBytes;
+    #tokenCount = 0;
+    constructor(opts) {
+        if (!opts || !Array.isArray(opts.rules)) {
+            throw new Error("TTSRRunner requires a rules array");
+        }
+        // Defensive copy + pre-parse the scope to avoid re-parsing per token.
+        this.#compiled = opts.rules.map((r) => ({ rule: r, scope: parseScope(r.scope) }));
+        this.#maxBufferBytes =
+            typeof opts.maxBufferBytes === "number" && opts.maxBufferBytes >= 0
+                ? opts.maxBufferBytes
+                : DEFAULT_MAX_BUFFER_BYTES;
+    }
+    /**
+     * Feed one streamed token (or chunk) labeled with its stream
+     * context. Returns a `TTSRTrigger` when ANY rule fires, otherwise
+     * `null`.
+     *
+     * Multiple rules can match in principle; the first match wins to
+     * keep the orchestrator wire simple. Callers wanting all matches
+     * can call `observeAll` (below).
+     */
+    observeToken(token, ctx) {
+        const all = this.observeAll(token, ctx);
+        return all.length > 0 ? (all[0] ?? null) : null;
+    }
+    /**
+     * Same as `observeToken` but returns every matching rule on the
+     * combined buffer. Useful when an orchestrator wants to inject
+     * multiple system reminders in one retry.
+     */
+    observeAll(token, ctx) {
+        if (typeof token !== "string" || token.length === 0)
+            return [];
+        this.#tokenCount++;
+        const key = bufferKeyFor(ctx);
+        const previous = this.#buffers.get(key) ?? "";
+        let buffer = previous + token;
+        // Cap buffer size to bound memory + regex work. Keep the most
+        // recent half so the suffix the token landed in survives.
+        if (this.#maxBufferBytes > 0 && buffer.length > this.#maxBufferBytes) {
+            buffer = buffer.slice(-Math.floor(this.#maxBufferBytes / 2));
+        }
+        this.#buffers.set(key, buffer);
+        const triggers = [];
+        for (const cr of this.#compiled) {
+            // One-shot enforcement: never re-fire.
+            if ((cr.rule.oneShot ?? true) && this.#fired.has(cr.rule.id))
+                continue;
+            if (!cr.scope.reachable)
+                continue;
+            if (!matchScope(cr.scope, ctx))
+                continue;
+            const matched = buffer.match(cr.rule.condition);
+            if (!matched || matched[0] === undefined)
+                continue;
+            triggers.push({
+                rule: cr.rule,
+                matchedAt: this.#tokenCount,
+                matchedText: matched[0],
+                context: ctx,
+                bufferKey: key,
+            });
+        }
+        return triggers;
+    }
+    /**
+     * Notify the runner that the orchestrator processed the trigger
+     * for `ruleId`. After this call, one-shot rules stop firing for
+     * the rest of the session.
+     *
+     * Non-one-shot rules are unaffected.
+     *
+     * Safe to call repeatedly with the same id (idempotent).
+     */
+    acknowledgeFired(ruleId) {
+        if (typeof ruleId !== "string" || ruleId.length === 0)
+            return;
+        this.#fired.add(ruleId);
+    }
+    /**
+     * Build the injection body the orchestrator should hand back to
+     * the model as a system reminder.
+     *
+     * Currently just `trigger.rule.body`, but kept as a method so we
+     * can later add metadata (matched text, file path, etc.) without
+     * changing the orchestrator wire.
+     */
+    getInjectionBody(trigger) {
+        return trigger.rule.body;
+    }
+    /**
+     * Clear all per-turn buffers. Call between turns so cross-turn
+     * matches do not leak. Does NOT clear the one-shot fired set -
+     * one-shot is per-session.
+     */
+    resetBuffers() {
+        this.#buffers.clear();
+        this.#tokenCount = 0;
+    }
+    /**
+     * Clear EVERYTHING for a new session: buffers AND fired records.
+     * The runner becomes equivalent to a freshly constructed one.
+     */
+    reset() {
+        this.#buffers.clear();
+        this.#fired.clear();
+        this.#tokenCount = 0;
+    }
+    /** Inspect runner state. Used by middleware diagnostics + tests. */
+    getState() {
+        return {
+            tokenCount: this.#tokenCount,
+            bufferKeys: Array.from(this.#buffers.keys()),
+            firedRuleIds: Array.from(this.#fired),
+            registeredRuleIds: this.#compiled.map((c) => c.rule.id),
+        };
+    }
+    /** Has this rule already fired (and been acknowledged) this session? */
+    hasFired(ruleId) {
+        return this.#fired.has(ruleId);
+    }
+    /**
+     * Convenience: peek the buffer for a stream key. Returns empty
+     * string when nothing has been buffered yet. Read-only.
+     */
+    peekBuffer(kindOrKey, toolName) {
+        const key = kindOrKey === "text" || kindOrKey === "thinking"
+            ? kindOrKey
+            : kindOrKey === "tool"
+                ? toolName
+                    ? `tool:${toolName.toLowerCase()}`
+                    : "tool"
+                : kindOrKey;
+        return this.#buffers.get(key) ?? "";
+    }
+}
+//# sourceMappingURL=ttsr-runner.js.map

package/dist/runtime-hooks/ttsr-runner.js.map

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

package/dist/runtime-hooks/ttsr-scope.d.ts

@@ -0,0 +1,115 @@
+/**
+ * TTSR Scope filter parsing + matching.
+ *
+ * Port of oh-my-pi's stream-scope filter:
+ *   - packages/coding-agent/src/capability/rule.ts  (quote/brace-aware tokenizer)
+ *   - packages/coding-agent/src/export/ttsr.ts      (TtsrScope + parseToolScopeToken)
+ *
+ * A ScopeFilter restricts WHEN a TTSR rule may fire during a streamed
+ * model turn. The rule only triggers when the current stream context
+ * matches its scope, so a rule scoped to `tool:edit(*.ts)` will not
+ * fire while the model is producing prose, thinking text, or arguments
+ * for a `write` tool call on a `*.md` file.
+ *
+ * This file is intentionally PURE — it builds matcher predicates and
+ * answers boolean questions. It does not touch streams, providers, or
+ * the orchestrator. Wiring lives in `ttsr-runner.ts` and (further out)
+ * `src/middleware/ttsr.ts`.
+ */
+/**
+ * Stream context kind associated with the chunk currently being
+ * inspected. The orchestrator labels each delta with one of these
+ * before handing it to the runner.
+ */
+export type StreamKind = "text" | "thinking" | "tool";
+/**
+ * Context about the current stream chunk. Tool deltas carry the tool
+ * name and (optionally) a `toolInput` partial — file paths are read
+ * out of `toolInput.path`, `toolInput.paths`, `toolInput.file_path`,
+ * or `toolInput.files[]` so we accept the common provider shapes.
+ */
+export interface StreamContext {
+    readonly kind: StreamKind;
+    readonly toolName?: string;
+    readonly toolInput?: Record<string, unknown>;
+    /** Optional file paths if the orchestrator pre-extracted them. */
+    readonly filePaths?: readonly string[];
+}
+/**
+ * Tokens accepted in a scope filter string:
+ *
+ *   "any"                  - every stream kind
+ *   "text"                 - assistant prose
+ *   "thinking"             - chain-of-thought / reasoning channel
+ *   "tool"                 - any tool call (no name/path filter)
+ *   "tool:<name>"          - only the named tool
+ *   "tool:<name>(<glob>)"  - only the named tool with matching file path
+ *
+ * Multi-token scopes are valid too: `"text, tool:write(*.{ts,tsx})"`
+ * - the tokenizer in `parseScope` is quote / brace / bracket aware so
+ * the comma inside `*.{ts,tsx}` does NOT split the token.
+ */
+export type ScopeFilter = string;
+export type ParsedScopeTokenKind = "any" | "text" | "thinking" | "tool";
+/**
+ * One parsed token in a (possibly multi-token) scope filter.
+ *
+ * `kind: "tool"` is the only kind that carries a name or a glob.
+ */
+export interface ParsedScopeToken {
+    readonly kind: ParsedScopeTokenKind;
+    readonly raw: string;
+    readonly toolName?: string;
+    readonly glob?: string;
+}
+export interface ParsedScope {
+    readonly raw: string;
+    readonly tokens: readonly ParsedScopeToken[];
+    /** True iff the scope is reachable at all (has at least one valid token). */
+    readonly reachable: boolean;
+}
+/**
+ * Quote-, paren-, bracket-, and brace-aware split on `,`.
+ *
+ * Mirrors oh-my-pi rule.ts splitScopeTokens so that scope strings such
+ * as `"tool:write(*.{ts,tsx}), text"` parse as two tokens, not three.
+ *
+ * Returns trimmed, non-empty tokens preserving original order.
+ */
+export declare function splitScopeTokens(value: string): readonly string[];
+/**
+ * Parse a `ScopeFilter` string into a structured `ParsedScope`.
+ *
+ * - Empty or all-whitespace input -> `reachable: false` with no tokens.
+ * - Unknown / malformed tokens are dropped silently (the runner can
+ *   surface a warning if it wants to).
+ * - Multi-token scopes are UNIONed at match time: any one match -> true.
+ */
+export declare function parseScope(s: ScopeFilter | undefined | null): ParsedScope;
+/**
+ * Pull candidate file paths from a tool input bag. Accepts the
+ * common shapes used by tool calls across providers:
+ *   { path: "src/a.ts" }
+ *   { file_path: "src/a.ts" }
+ *   { paths: ["src/a.ts", "src/b.ts"] }
+ *   { files: [{ path: "src/a.ts" }] }
+ *
+ * Anything that does not look like a string path is ignored.
+ */
+export declare function extractFilePaths(ctx: StreamContext): readonly string[];
+/**
+ * Test whether a parsed scope matches the supplied stream context.
+ *
+ * Multi-token scopes are UNIONed - a single token match returns true.
+ * `kind: "any"` always returns true. An unreachable scope (no tokens)
+ * returns false: callers must default to a sentinel like `"any"` if
+ * they want a permissive default.
+ */
+export declare function matchScope(scope: ScopeFilter | ParsedScope | undefined | null, ctx: StreamContext): boolean;
+/**
+ * Convenience for tests + downstream wires that have a raw scope string.
+ *
+ * Returns true if at least one parsed token reaches some stream kind.
+ */
+export declare function isReachableScope(s: ScopeFilter | undefined | null): boolean;
+//# sourceMappingURL=ttsr-scope.d.ts.map

package/dist/runtime-hooks/ttsr-scope.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ttsr-scope.d.ts","sourceRoot":"","sources":["../../src/runtime-hooks/ttsr-scope.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH;;;;GAIG;AACH,MAAM,MAAM,UAAU,GAAG,MAAM,GAAG,UAAU,GAAG,MAAM,CAAC;AAEtD;;;;;GAKG;AACH,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,IAAI,EAAE,UAAU,CAAC;IAC1B,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC7C,kEAAkE;IAClE,QAAQ,CAAC,SAAS,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CACxC;AAED;;;;;;;;;;;;;GAaG;AACH,MAAM,MAAM,WAAW,GAAG,MAAM,CAAC;AAEjC,MAAM,MAAM,oBAAoB,GAAG,KAAK,GAAG,MAAM,GAAG,UAAU,GAAG,MAAM,CAAC;AAExE;;;;GAIG;AACH,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,IAAI,EAAE,oBAAoB,CAAC;IACpC,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;CACxB;AAED,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,MAAM,EAAE,SAAS,gBAAgB,EAAE,CAAC;IAC7C,6EAA6E;IAC7E,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAC;CAC7B;AAED;;;;;;;GAOG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,MAAM,GAAG,SAAS,MAAM,EAAE,CAiEjE;AAsDD;;;;;;;GAOG;AACH,wBAAgB,UAAU,CAAC,CAAC,EAAE,WAAW,GAAG,SAAS,GAAG,IAAI,GAAG,WAAW,CAkBzE;AAqGD;;;;;;;;;GASG;AACH,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,aAAa,GAAG,SAAS,MAAM,EAAE,CAkCtE;AAED;;;;;;;GAOG;AACH,wBAAgB,UAAU,CACxB,KAAK,EAAE,WAAW,GAAG,WAAW,GAAG,SAAS,GAAG,IAAI,EACnD,GAAG,EAAE,aAAa,GACjB,OAAO,CAoDT;AAED;;;;GAIG;AACH,wBAAgB,gBAAgB,CAAC,CAAC,EAAE,WAAW,GAAG,SAAS,GAAG,IAAI,GAAG,OAAO,CAE3E"}