opensquid 0.5.395

package/dist/setup/cli/cache.js

@@ -0,0 +1,154 @@
+/**
+ * `opensquid cache` CLI verb group (CLI.7).
+ *
+ * Two verbs, backed by the DURABLE.3 `MemoCache`:
+ *
+ *   stats  — per-primitive hit / size table. Reads `MemoCache.stats()`,
+ *            which queries the libsql tier (the authoritative cross-
+ *            restart record). The in-memory LRU tier deliberately does
+ *            NOT contribute — a restart would otherwise reset reported
+ *            hits to zero and trip the "is this thing working" check
+ *            (see memo_cache.ts MemoStats comment).
+ *   clear  — selective invalidation. `--primitive <name>` purges one
+ *            primitive's rows; `--older-than <duration>` purges rows
+ *            older than the window; both flags combine via AND. A
+ *            zero-filter (full) clear requires `--yes` or interactive
+ *            y/N confirmation; non-TTY without `--yes` exits 1.
+ *
+ * Confirmation policy (locked):
+ *   - At least one filter → no confirmation. Output reports row count
+ *     removed; the user already declared the scope.
+ *   - No filter (full wipe) → `--yes` or TTY confirmation required.
+ *     Mirrors the `checkpoints clean` non-TTY refusal pattern.
+ *
+ * File-size budget: this file ≤ 200 LOC including both verbs (CLI.7
+ * deliverable). Pure runtime logic (`MemoCache.stats` / `.clear`)
+ * already lives in `runtime/durable/memo_cache.ts`; we just wire
+ * commander + format output.
+ *
+ * Imports from: commander, @libsql/client, ../../runtime/durable/index.js,
+ *   ./audit_state.js (parseDurationToMs + defaultAuditDbPath).
+ * Imported by: src/cli.ts, src/setup/cli/cache.test.ts.
+ */
+import { createClient } from '@libsql/client';
+import { MemoCache } from '../../runtime/durable/index.js';
+import { defaultAuditDbPath, parseDurationToMs } from './audit_state.js';
+function defaultOpen(dbPath) {
+    const url = dbPath.startsWith('file:') || dbPath === ':memory:' ? dbPath : `file:${dbPath}`;
+    return createClient({ url });
+}
+function buildDeps(deps) {
+    return {
+        open: deps.openClient ?? defaultOpen,
+        out: deps.stdout ?? ((s) => void process.stdout.write(s)),
+        err: deps.stderr ?? ((s) => void process.stderr.write(s)),
+        isTty: deps.isTty ?? (() => process.stdout.isTTY === true),
+        now: deps.now ?? (() => Date.now()),
+    };
+}
+async function confirmTty(question, isTty) {
+    if (!isTty())
+        return false;
+    const rl = (await import('node:readline/promises')).createInterface({
+        input: process.stdin,
+        output: process.stdout,
+    });
+    try {
+        const answer = (await rl.question(question)).trim().toLowerCase();
+        return answer === 'y' || answer === 'yes';
+    }
+    finally {
+        rl.close();
+    }
+}
+// Fixed-column table render. Same posture as checkpoints_render.ts —
+// human-eyeballed columns, jq-piped consumers should query libsql directly.
+function renderStatsTable(rows) {
+    const lines = [];
+    lines.push(pad('PRIMITIVE', 24) + pad('HITS', 10) + pad('SIZE', 10));
+    for (const r of rows) {
+        lines.push(pad(r.fn, 24) + pad(String(r.hits), 10) + pad(String(r.size), 10));
+    }
+    return lines.join('\n');
+}
+function pad(s, w) {
+    if (s.length >= w)
+        return s.slice(0, w - 1) + ' ';
+    return s + ' '.repeat(w - s.length);
+}
+async function actStats(deps, opts) {
+    const client = deps.open(opts.db);
+    try {
+        const cache = new MemoCache(client, { nowMs: deps.now });
+        await cache.init();
+        const rows = await cache.stats();
+        if (rows.length === 0) {
+            deps.out('(no cached primitives)\n');
+            return;
+        }
+        deps.out(renderStatsTable(rows) + '\n');
+    }
+    finally {
+        client.close();
+    }
+}
+async function actClear(deps, opts) {
+    // Parse --older-than first so a bad duration aborts before opening the DB.
+    let olderThanMs;
+    if (opts.olderThan !== undefined) {
+        const parsed = parseDurationToMs(opts.olderThan);
+        if (parsed === null) {
+            deps.err(`opensquid cache clear: --older-than "${opts.olderThan}" must be like 30s|10m|2h|7d\n`);
+            process.exitCode = 1;
+            return;
+        }
+        olderThanMs = parsed;
+    }
+    const hasFilter = opts.primitive !== undefined || olderThanMs !== undefined;
+    // Full clear (no filter) — require --yes or TTY confirmation.
+    if (!hasFilter) {
+        if (!opts.yes && !deps.isTty()) {
+            deps.err('opensquid cache clear: refusing full clear without --yes in non-interactive context\n');
+            process.exitCode = 1;
+            return;
+        }
+        if (!opts.yes && !(await confirmTty('Clear ALL cached primitives? [y/N] ', deps.isTty))) {
+            deps.out('aborted\n');
+            return;
+        }
+    }
+    const client = deps.open(opts.db);
+    try {
+        const cache = new MemoCache(client, { nowMs: deps.now });
+        await cache.init();
+        const clearOpts = {};
+        if (opts.primitive !== undefined)
+            clearOpts.fn = opts.primitive;
+        if (olderThanMs !== undefined)
+            clearOpts.olderThanMs = olderThanMs;
+        const removed = await cache.clear(clearOpts);
+        deps.out(`removed ${String(removed)} cache row${removed === 1 ? '' : 's'}\n`);
+    }
+    finally {
+        client.close();
+    }
+}
+/** Register `opensquid cache` on the parent program. */
+export function registerCache(parent, deps = {}) {
+    const r = buildDeps(deps);
+    const c = parent.command('cache').description('Memoization cache (DURABLE.3)');
+    const db = defaultAuditDbPath();
+    c.command('stats')
+        .description('Per-primitive hit / size table from the persistent cache tier')
+        .option('--db <path>', 'Path to the libsql DB', db)
+        .action((opts) => actStats(r, opts));
+    c.command('clear')
+        .description('Invalidate cache entries (selective by --primitive / --older-than, or full)')
+        .option('--db <path>', 'Path to the libsql DB', db)
+        .option('--primitive <name>', 'restrict to one primitive (e.g. llm_classify)')
+        .option('--older-than <duration>', 'remove rows cached more than this ago (e.g. 7d)')
+        .option('--yes', 'skip confirmation for full clear', false)
+        .action((opts) => actClear(r, opts));
+    return c;
+}
+//# sourceMappingURL=cache.js.map

package/dist/setup/cli/cache.js.map

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

package/dist/setup/cli/chat.d.ts

@@ -0,0 +1,69 @@
+/**
+ * WIZ.5 — `opensquid setup chat` commander wiring.
+ *
+ * Thin shim: parses three flags (--dry-run, --replace, --skip-test) and
+ * delegates to `runChatSetupWizard()` from `./chat_actions.ts`. Mirrors the
+ * registration shape of `permissions.ts` / `triggers.ts` / `schedule.ts`.
+ *
+ * Flag semantics (locked per WIZ.5 spec):
+ *   --dry-run    Walk the wizard, render the plan preview, then EXIT without
+ *                writing. Maps to `WizardDeps.dryRun = true`. The wizard
+ *                short-circuits before `executePlan`. No backups created,
+ *                no files modified.
+ *   --replace    Skip the existing-config (idempotency) branch — proceed
+ *                straight to authoring fresh config. Maps to
+ *                `WizardDeps.replace = true`. The user still sees the
+ *                dry-run preview + confirm before any write happens.
+ *   --skip-test  Skip the WIZ.4 channel-test step. Implemented by setting
+ *                `OPENSQUID_NO_BILLED_CALLS=1` in the wizard's env BEFORE
+ *                invocation — the test step already honors this env var.
+ *                We restore the prior value on exit so adjacent CLI calls
+ *                in the same process aren't poisoned.
+ *
+ * Exit codes (inherited from `runChatSetupWizard`):
+ *   0    completed | no_changes | dry_run
+ *   1    concurrent_lock (another wizard running)
+ *   2    malformed models.yaml (detection-time abort)
+ *   3    write failure (rollback engaged)
+ *
+ * Default `setup` action: if a user runs `opensquid setup` with no
+ * subcommand, commander prints the help text and exits 1 (commander's
+ * default for "unknown subcommand"). We do NOT auto-start the chat wizard
+ * from the bare `setup` verb — per WIZ.5 risk callout, the wizard must
+ * be explicitly opt-in.
+ *
+ * Imports from: commander, ./chat_actions.
+ * Imported by: src/cli.ts.
+ */
+import { type WizardDeps, type WizardResult } from './chat_actions.js';
+import type { Command } from 'commander';
+export interface ChatCliDeps {
+    /** Test injection — override the wizard runner. Defaults to the real
+     *  `runChatSetupWizard`. Tests substitute a stub that records its args. */
+    runWizard?: (deps: WizardDeps) => Promise<WizardResult>;
+    /** Test injection — override env access (read + write of OPENSQUID_NO_BILLED_CALLS).
+     *  Defaults to `process.env`. */
+    env?: NodeJS.ProcessEnv;
+}
+export interface ChatCliFlags {
+    dryRun?: boolean;
+    replace?: boolean;
+    skipTest?: boolean;
+}
+/**
+ * Register the `setup chat` subcommand on the supplied `setup` parent
+ * group. Returns the registered subcommand so callers can chain or inspect.
+ */
+export declare function registerChat(parent: Command, deps?: ChatCliDeps): Command;
+/**
+ * Register the `setup` parent verb group + all of its subcommands.
+ *
+ * Currently only `chat` lives here; future setup wizards (`setup channels`,
+ * `setup permissions-wizard`, etc.) register against the same parent via
+ * this function so `src/cli.ts` stays a one-liner.
+ *
+ * Bare `opensquid setup` prints help (per WIZ.5 risk callout — never
+ * auto-run a wizard from an ambiguous verb).
+ */
+export declare function registerSetup(parent: Command, deps?: ChatCliDeps): Command;
+//# sourceMappingURL=chat.d.ts.map

package/dist/setup/cli/chat.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"chat.d.ts","sourceRoot":"","sources":["../../../src/setup/cli/chat.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AAEH,OAAO,EAAsB,KAAK,UAAU,EAAE,KAAK,YAAY,EAAE,MAAM,mBAAmB,CAAC;AAE3F,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAEzC,MAAM,WAAW,WAAW;IAC1B;+EAC2E;IAC3E,SAAS,CAAC,EAAE,CAAC,IAAI,EAAE,UAAU,KAAK,OAAO,CAAC,YAAY,CAAC,CAAC;IACxD;qCACiC;IACjC,GAAG,CAAC,EAAE,MAAM,CAAC,UAAU,CAAC;CACzB;AAED,MAAM,WAAW,YAAY;IAC3B,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB;AAED;;;GAGG;AACH,wBAAgB,YAAY,CAAC,MAAM,EAAE,OAAO,EAAE,IAAI,GAAE,WAAgB,GAAG,OAAO,CAmC7E;AAED;;;;;;;;;GASG;AACH,wBAAgB,aAAa,CAAC,MAAM,EAAE,OAAO,EAAE,IAAI,GAAE,WAAgB,GAAG,OAAO,CAI9E"}

package/dist/setup/cli/chat.js

@@ -0,0 +1,95 @@
+/**
+ * WIZ.5 — `opensquid setup chat` commander wiring.
+ *
+ * Thin shim: parses three flags (--dry-run, --replace, --skip-test) and
+ * delegates to `runChatSetupWizard()` from `./chat_actions.ts`. Mirrors the
+ * registration shape of `permissions.ts` / `triggers.ts` / `schedule.ts`.
+ *
+ * Flag semantics (locked per WIZ.5 spec):
+ *   --dry-run    Walk the wizard, render the plan preview, then EXIT without
+ *                writing. Maps to `WizardDeps.dryRun = true`. The wizard
+ *                short-circuits before `executePlan`. No backups created,
+ *                no files modified.
+ *   --replace    Skip the existing-config (idempotency) branch — proceed
+ *                straight to authoring fresh config. Maps to
+ *                `WizardDeps.replace = true`. The user still sees the
+ *                dry-run preview + confirm before any write happens.
+ *   --skip-test  Skip the WIZ.4 channel-test step. Implemented by setting
+ *                `OPENSQUID_NO_BILLED_CALLS=1` in the wizard's env BEFORE
+ *                invocation — the test step already honors this env var.
+ *                We restore the prior value on exit so adjacent CLI calls
+ *                in the same process aren't poisoned.
+ *
+ * Exit codes (inherited from `runChatSetupWizard`):
+ *   0    completed | no_changes | dry_run
+ *   1    concurrent_lock (another wizard running)
+ *   2    malformed models.yaml (detection-time abort)
+ *   3    write failure (rollback engaged)
+ *
+ * Default `setup` action: if a user runs `opensquid setup` with no
+ * subcommand, commander prints the help text and exits 1 (commander's
+ * default for "unknown subcommand"). We do NOT auto-start the chat wizard
+ * from the bare `setup` verb — per WIZ.5 risk callout, the wizard must
+ * be explicitly opt-in.
+ *
+ * Imports from: commander, ./chat_actions.
+ * Imported by: src/cli.ts.
+ */
+import { runChatSetupWizard } from './chat_actions.js';
+/**
+ * Register the `setup chat` subcommand on the supplied `setup` parent
+ * group. Returns the registered subcommand so callers can chain or inspect.
+ */
+export function registerChat(parent, deps = {}) {
+    const runWizard = deps.runWizard ?? runChatSetupWizard;
+    const env = deps.env ?? process.env;
+    return parent
+        .command('chat')
+        .description('Interactive chat-agent setup wizard (model alias + chat_agent.yaml + optional channel test)')
+        .option('--dry-run', 'render the write plan but DO NOT modify any files', false)
+        .option('--replace', 'overwrite existing fast_chat alias (skips idempotency branch)', false)
+        .option('--skip-test', 'skip the post-write channel-delivery test step', false)
+        .action(async (flags) => {
+        const wizardDeps = {};
+        if (flags.dryRun === true)
+            wizardDeps.dryRun = true;
+        if (flags.replace === true)
+            wizardDeps.replace = true;
+        // --skip-test piggybacks on the existing OPENSQUID_NO_BILLED_CALLS=1
+        // gate inside `runChannelTestStep`. We save/restore the prior value
+        // so we don't pollute the host process's env for any sibling code
+        // running in the same process (rare, but the CLI is also embedded
+        // by some integration tests).
+        const priorSkipFlag = env.OPENSQUID_NO_BILLED_CALLS;
+        if (flags.skipTest === true) {
+            env.OPENSQUID_NO_BILLED_CALLS = '1';
+        }
+        try {
+            await runWizard(wizardDeps);
+        }
+        finally {
+            if (flags.skipTest === true) {
+                if (priorSkipFlag === undefined)
+                    delete env.OPENSQUID_NO_BILLED_CALLS;
+                else
+                    env.OPENSQUID_NO_BILLED_CALLS = priorSkipFlag;
+            }
+        }
+    });
+}
+/**
+ * Register the `setup` parent verb group + all of its subcommands.
+ *
+ * Currently only `chat` lives here; future setup wizards (`setup channels`,
+ * `setup permissions-wizard`, etc.) register against the same parent via
+ * this function so `src/cli.ts` stays a one-liner.
+ *
+ * Bare `opensquid setup` prints help (per WIZ.5 risk callout — never
+ * auto-run a wizard from an ambiguous verb).
+ */
+export function registerSetup(parent, deps = {}) {
+    const setup = parent.command('setup').description('Interactive setup wizards');
+    registerChat(setup, deps);
+    return setup;
+}
+//# sourceMappingURL=chat.js.map

package/dist/setup/cli/chat.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"chat.js","sourceRoot":"","sources":["../../../src/setup/cli/chat.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AAEH,OAAO,EAAE,kBAAkB,EAAsC,MAAM,mBAAmB,CAAC;AAmB3F;;;GAGG;AACH,MAAM,UAAU,YAAY,CAAC,MAAe,EAAE,OAAoB,EAAE;IAClE,MAAM,SAAS,GAAG,IAAI,CAAC,SAAS,IAAI,kBAAkB,CAAC;IACvD,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,IAAI,OAAO,CAAC,GAAG,CAAC;IAEpC,OAAO,MAAM;SACV,OAAO,CAAC,MAAM,CAAC;SACf,WAAW,CACV,6FAA6F,CAC9F;SACA,MAAM,CAAC,WAAW,EAAE,mDAAmD,EAAE,KAAK,CAAC;SAC/E,MAAM,CAAC,WAAW,EAAE,+DAA+D,EAAE,KAAK,CAAC;SAC3F,MAAM,CAAC,aAAa,EAAE,gDAAgD,EAAE,KAAK,CAAC;SAC9E,MAAM,CAAC,KAAK,EAAE,KAAmB,EAAE,EAAE;QACpC,MAAM,UAAU,GAAe,EAAE,CAAC;QAClC,IAAI,KAAK,CAAC,MAAM,KAAK,IAAI;YAAE,UAAU,CAAC,MAAM,GAAG,IAAI,CAAC;QACpD,IAAI,KAAK,CAAC,OAAO,KAAK,IAAI;YAAE,UAAU,CAAC,OAAO,GAAG,IAAI,CAAC;QAEtD,qEAAqE;QACrE,oEAAoE;QACpE,kEAAkE;QAClE,kEAAkE;QAClE,8BAA8B;QAC9B,MAAM,aAAa,GAAG,GAAG,CAAC,yBAAyB,CAAC;QACpD,IAAI,KAAK,CAAC,QAAQ,KAAK,IAAI,EAAE,CAAC;YAC5B,GAAG,CAAC,yBAAyB,GAAG,GAAG,CAAC;QACtC,CAAC;QACD,IAAI,CAAC;YACH,MAAM,SAAS,CAAC,UAAU,CAAC,CAAC;QAC9B,CAAC;gBAAS,CAAC;YACT,IAAI,KAAK,CAAC,QAAQ,KAAK,IAAI,EAAE,CAAC;gBAC5B,IAAI,aAAa,KAAK,SAAS;oBAAE,OAAO,GAAG,CAAC,yBAAyB,CAAC;;oBACjE,GAAG,CAAC,yBAAyB,GAAG,aAAa,CAAC;YACrD,CAAC;QACH,CAAC;IACH,CAAC,CAAC,CAAC;AACP,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,UAAU,aAAa,CAAC,MAAe,EAAE,OAAoB,EAAE;IACnE,MAAM,KAAK,GAAG,MAAM,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC,WAAW,CAAC,2BAA2B,CAAC,CAAC;IAC/E,YAAY,CAAC,KAAK,EAAE,IAAI,CAAC,CAAC;IAC1B,OAAO,KAAK,CAAC;AACf,CAAC"}

package/dist/setup/cli/chat_actions.d.ts

@@ -0,0 +1,57 @@
+/**
+ * WIZ.3 + WAB-SUB.3 — interactive chat-setup wizard. Implements
+ * `docs/tasks/WIZ.1-flow.md` storyboard with the WAB-SUB.3 mode-choice
+ * extension: detection → mode choice (api | subscription) → mode-specific
+ * alias setup → chat_agent.yaml authoring → dry-run preview → confirm →
+ * atomic write with backup → outro.
+ *
+ * Audit invariants:
+ *   - No write without explicit `confirm()` → true after dry-run preview.
+ *   - `isCancel()` checked after EVERY prompt; cancel path emits a "nothing
+ *     written" message and exits clean.
+ *   - Secrets prompted via `password()` (masked) IN api mode only; subscription
+ *     mode never prompts for a key. Dry-run preview shows `=…<last4>` only.
+ *   - Both `mode=api` and `mode=subscription` are first-class choices —
+ *     NEITHER pre-selected as `initialValue` (WAB-SUB.3 spec criterion A).
+ *   - Existing config (idempotency branch) treats BOTH modes as valid;
+ *     Replace walks the mode-choice prompt again.
+ *   - `OPENSQUID_NO_BILLED_CALLS=1` skips step (f) entirely.
+ *   - `~/.opensquid/setup-chat.lock` via proper-lockfile prevents concurrent runs.
+ *
+ * Writes delegated to `./chat_actions_writers.ts`; prompt sub-flows to
+ * `./chat_actions_prompts.ts`. This file orchestrates only.
+ */
+import { type ChatDaemonState } from './chat_state.js';
+export interface WizardDeps {
+    /** Override for OPENSQUID_HOME (test injection). Defaults to env var. */
+    opensquidHome?: string;
+    /** Override for ~/.loop/.env path. */
+    envPath?: string;
+    /** Exit code sink — tests assert against this without process.exit. */
+    setExitCode?: (code: number) => void;
+    /**
+     * WIZ.5 `--dry-run`. Wizard walks prompts + renders the plan, then exits
+     * WITHOUT calling `executePlan`. The dry-run preview is the deliverable;
+     * no files are written, no backups created. Final confirm prompt is
+     * skipped (we wouldn't honor a `true` answer anyway).
+     */
+    dryRun?: boolean;
+    /**
+     * WIZ.5 `--replace`. Skips the existing-config (idempotency) branch and
+     * always proceeds to author fresh config — overwriting any existing
+     * fast_chat alias. Backup of the prior models.yaml is still made.
+     */
+    replace?: boolean;
+    /** T-FIX-FIRST-RUN-SETUP A: project-identity probe seams (test injection).
+     *  Default process.cwd()/process.env — same pattern as opensquidHome/envPath. */
+    projectCwd?: string;
+    projectEnv?: NodeJS.ProcessEnv;
+}
+export interface WizardResult {
+    outcome: 'completed' | 'aborted' | 'no_changes' | 'concurrent_lock' | 'dry_run';
+    written?: string[];
+}
+export declare function runChatSetupWizard(deps?: WizardDeps): Promise<WizardResult>;
+export type { ChatDaemonState };
+export { runChatSetupWizard as runWizard };
+//# sourceMappingURL=chat_actions.d.ts.map

package/dist/setup/cli/chat_actions.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"chat_actions.d.ts","sourceRoot":"","sources":["../../../src/setup/cli/chat_actions.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AA0BH,OAAO,EAOL,KAAK,eAAe,EAIrB,MAAM,iBAAiB,CAAC;AAMzB,MAAM,WAAW,UAAU;IACzB,yEAAyE;IACzE,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,sCAAsC;IACtC,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,uEAAuE;IACvE,WAAW,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;IACrC;;;;;OAKG;IACH,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB;;;;OAIG;IACH,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB;qFACiF;IACjF,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,UAAU,CAAC,EAAE,MAAM,CAAC,UAAU,CAAC;CAChC;AAED,MAAM,WAAW,YAAY;IAC3B,OAAO,EAAE,WAAW,GAAG,SAAS,GAAG,YAAY,GAAG,iBAAiB,GAAG,SAAS,CAAC;IAChF,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC;CACpB;AAMD,wBAAsB,kBAAkB,CAAC,IAAI,GAAE,UAAe,GAAG,OAAO,CAAC,YAAY,CAAC,CAyCrF;AAmVD,YAAY,EAAE,eAAe,EAAE,CAAC;AAEhC,OAAO,EAAE,kBAAkB,IAAI,SAAS,EAAE,CAAC"}