@nexrall/code-core 1.4.66 → 1.4.67

package/dist/agent/agentTypes.d.ts

@@ -82,8 +82,12 @@ export interface AgentType {
     hooks?: AgentHooks;
 }
 export interface AgentHookDef {
-    type: 'command';
-    command: string;
+    type: 'command' | 'http';
+    command?: string;
+    /** `type:"http"`: POST the hook payload here. */
+    url?: string;
+    headers?: Record<string, string>;
+    allowedEnvVars?: string[];
     timeout_ms?: number;
 }
 export interface AgentHookEntry {

package/dist/agent/agentTypes.d.ts.map

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

package/dist/agent/agentTypes.js

@@ -588,12 +588,21 @@ function parseAgentHooks(raw) {
             throw new Error(`${where}: expected a list of hooks`);
         return list.map((h, i) => {
             const o = h;
-            if (!o || o.type !== 'command' || typeof o.command !== 'string' || !o.command.trim()) {
-                throw new Error(`${where}[${i}]: each hook needs type: command and a command`);
-            }
             const ms = typeof o.timeout_ms === 'number' ? o.timeout_ms
                 : typeof o.timeout === 'number' ? o.timeout * 1000 : undefined;
-            return { type: 'command', command: o.command, ...(ms && ms > 0 ? { timeout_ms: ms } : {}) };
+            const timeout = ms && ms > 0 ? { timeout_ms: ms } : {};
+            if (o && o.type === 'http' && typeof o.url === 'string' && o.url.trim()) {
+                if (!/^https?:\/\//i.test(o.url.trim()))
+                    throw new Error(`${where}[${i}]: http hooks need an http(s) url`);
+                const headers = o.headers && typeof o.headers === 'object' && !Array.isArray(o.headers)
+                    ? o.headers : undefined;
+                const allowed = Array.isArray(o.allowedEnvVars) ? o.allowedEnvVars.filter((v) => typeof v === 'string') : undefined;
+                return { type: 'http', url: o.url.trim(), ...(headers ? { headers } : {}), ...(allowed ? { allowedEnvVars: allowed } : {}), ...timeout };
+            }
+            if (!o || o.type !== 'command' || typeof o.command !== 'string' || !o.command.trim()) {
+                throw new Error(`${where}[${i}]: each hook needs type: command and a command, or type: http and a url`);
+            }
+            return { type: 'command', command: o.command, ...timeout };
         });
     };
     const entries = (list, ev) => {

package/dist/agent/askOnce.d.ts

@@ -0,0 +1,12 @@
+import type { EnvContext } from '../types';
+export interface AskOnceOptions {
+    model: string;
+    cwd: string;
+    env?: EnvContext;
+    timeoutMs?: number;
+    abortSignal?: {
+        aborted: boolean;
+    };
+}
+export declare function askModelOnce(prompt: string, opts: AskOnceOptions): Promise<string | null>;
+//# sourceMappingURL=askOnce.d.ts.map

package/dist/agent/askOnce.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"askOnce.d.ts","sourceRoot":"","sources":["../../src/agent/askOnce.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EAAgB,UAAU,EAAW,MAAM,UAAU,CAAC;AAKlE,MAAM,WAAW,cAAc;IAC7B,KAAK,EAAE,MAAM,CAAC;IACd,GAAG,EAAE,MAAM,CAAC;IACZ,GAAG,CAAC,EAAE,UAAU,CAAC;IACjB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,WAAW,CAAC,EAAE;QAAE,OAAO,EAAE,OAAO,CAAA;KAAE,CAAC;CACpC;AAED,wBAAsB,YAAY,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,cAAc,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAwB/F"}

package/dist/agent/askOnce.js

@@ -0,0 +1,41 @@
+"use strict";
+// A single tool-less model call: send one prompt, get the text back. Used by small
+// judges (e.g. the CLI's /goal) that need an answer, not an agent loop. It never
+// runs tools, never throws on a model/network failure (returns null) and never
+// outlives its timeout, so a judge can never hang or crash the turn that asked.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.askModelOnce = askModelOnce;
+const client_1 = require("../api/client");
+/** The same marker prompt hooks use: matches no tool, so the backend sends none. */
+const NO_TOOLS_MARKER = '\u0000hook-no-tools';
+async function askModelOnce(prompt, opts) {
+    const ctl = { aborted: false };
+    const timer = setTimeout(() => { ctl.aborted = true; }, Math.max(1000, opts.timeoutMs ?? 45000));
+    const poll = opts.abortSignal
+        ? setInterval(() => { if (opts.abortSignal?.aborted)
+            ctl.aborted = true; }, 100)
+        : undefined;
+    try {
+        if (opts.abortSignal?.aborted)
+            return null;
+        const messages = [{ role: 'user', content: [{ type: 'text', text: prompt }] }];
+        const msg = await (0, client_1.streamChat)(messages, {
+            model: opts.model,
+            env: opts.env ?? { cwd: opts.cwd },
+            abortSignal: ctl,
+            toolAllowlist: [NO_TOOLS_MARKER],
+        }, () => { });
+        const blocks = Array.isArray(msg.content) ? msg.content : [];
+        const text = blocks.filter((b) => b.type === 'text' && typeof b.text === 'string').map((b) => b.text).join('\n');
+        return ctl.aborted ? null : text;
+    }
+    catch {
+        return null;
+    }
+    finally {
+        clearTimeout(timer);
+        if (poll)
+            clearInterval(poll);
+    }
+}
+//# sourceMappingURL=askOnce.js.map

package/dist/agent/compaction.d.ts

@@ -0,0 +1,244 @@
+import type { Message, AgentLoopOptions, EnvContext } from '../types';
+import { streamChat } from '../api/client';
+import { type MemoryScope } from './memory';
+export declare const MODEL_CONTEXT_TOKENS: Record<string, number>;
+/**
+ * Context window (tokens) for a model alias or real model id.
+ *
+ * Checks the LIVE catalogue (GET /api/code/models, modelCatalogue.ts) first —
+ * populated once per process by whichever client fetched it (CLI at session
+ * start, VS Code via _postModelCatalogue, desktop via its main-process
+ * fetch) — falling back to this hard-coded table when no live data exists yet
+ * (offline, older backend, or the catalogue simply hasn't been fetched by
+ * this call site). This is what lets a model added to the backend registry
+ * (services/providers/modelRegistry.js) get the CORRECT context window here
+ * even before this table is updated by hand for a new nexrall-code release —
+ * exactly the class of bug GPT-5.6's 922K-vs-1.05M mismatch was (see
+ * modelRegistry.js's own comment on that row).
+ *
+ * The static-table fallback is deliberately the SMALLEST window in the table
+ * rather than the largest. An unknown model is most likely a newly added one
+ * this client build predates, and guessing high is the failure that cannot be
+ * recovered from: the turn hits a provider 400 with no chance to compact.
+ * Guessing low only costs an earlier, lossy compaction — annoying, not broken.
+ */
+export declare function contextWindowFor(model?: string): number;
+/** Token counts at which auto-prune and auto-compact (summarise) fire for a model window. */
+export declare function compactionLimits(contextWindow: number, settingsRaw?: Record<string, unknown>): {
+    prune: number;
+    compact: number;
+};
+/** Auto-prune / auto-compact thresholds as fractions of the context window — for UI display (e.g. `/context`). */
+export declare function compactionThresholds(contextWindow?: number, settingsRaw?: Record<string, unknown>): {
+    prune: number;
+    compact: number;
+};
+export declare const PRUNE_MIN_RECLAIM_BYTES: number;
+export declare const _lastApiCallEndedAt: Map<string, number>;
+export declare function pruneReclaimFloor(lastCallEndedAt: number | undefined, now?: number): number;
+export declare const COMPACT_KEEP_MIN = 6;
+/**
+ * Bytes a compaction must reclaim to count as productive.
+ *
+ * Deliberately much smaller than PRUNE_MIN_RECLAIM_BYTES: a prune declines when the
+ * gain isn't worth busting the prompt cache, whereas by the time we are summarising
+ * we are already committed to rewriting the prefix — the only question is whether the
+ * summariser is making ANY headway. 32 KB is small enough that a genuinely useful
+ * compaction always clears it, large enough that shuffling a few bytes doesn't.
+ */
+export declare const COMPACT_MIN_RECLAIM_BYTES: number;
+/**
+ * Consecutive non-productive compaction attempts before auto-compaction is switched
+ * off for the rest of the run.
+ *
+ * 3 rather than 1 because the failure is often transient — a summariser stream that
+ * blipped will usually succeed on the next turn, and giving up instantly would lose
+ * the safety net for a whole long session over one network hiccup. 3 also bounds the
+ * wasted spend: at most three summariser calls, not hundreds.
+ */
+export declare const COMPACT_MAX_FAILURES = 3;
+export declare const MAX_BODY_BYTES: number;
+/** Approximate serialised request-body size (bytes) for the messages array. */
+export declare function estimateBodyBytes(messages: Message[]): number;
+export declare function resolveAutoCompact(fromOptions: boolean | undefined, rawSettings: Record<string, unknown>): boolean;
+/** Opt-out for the one-shot verification nudge (GAP D). Defaults to on. */
+export declare function resolveVerificationNudge(rawSettings: Record<string, unknown>): boolean;
+/** Tools that mutate the filesystem — used by the verification nudge (GAP D). */
+export declare const WRITE_TOOL_NAMES: Set<string>;
+/**
+ * May an agent restricted to `testFilesOnly` perform this tool call?
+ *
+ * A tool allowlist is all-or-nothing per tool: granting `edit_file` grants it for
+ * every path in the repo. A user-defined test-writer agent needs write access to produce
+ * tests, but must NOT be able to "fix" production source so a failing test goes
+ * green — the single most common way a test-writing agent destroys the signal it
+ * was asked to create. Its prompt says so; this makes it a refusal rather than a
+ * request.
+ *
+ * Pure + exported so the rules are testable directly, without running a real
+ * sub-agent.
+ *
+ * KNOWN LIMIT, stated rather than hidden: this gates the file TOOLS, not `bash`.
+ * A determined model could still write source via `bash: echo ... > src/x.ts`.
+ * Closing that means parsing shell redirection, which is not reliably doable — so
+ * this is a strong guardrail against the realistic failure mode, not a sandbox.
+ * Real isolation is the sandbox config (tools/sandbox.ts), a separate mechanism.
+ */
+export declare function allowsTestOnlyWrite(tool: string, input: Record<string, unknown> | undefined): boolean;
+/** Heuristic: does a bash command look like it's running tests/build/lint/typecheck? (GAP D) */
+export declare const VERIFY_CMD_RE: RegExp;
+/**
+ * Find the latest index ≤ maxIdx where history can be cut safely.
+ *
+ * A safe cut point is a **turn boundary**: an assistant message (which always
+ * begins a fresh turn after a user message). Cutting there guarantees that
+ * `messages[cut..]` starts with an assistant whose `tool_use` blocks are all
+ * answered by `tool_result`s that remain in the kept slice — so we never orphan
+ * a tool_result (which the API rejects). We deliberately allow cutting across
+ * tool_result-bearing user messages: the OLD implementation only cut at a
+ * *non*-tool_result user message, which never exists inside a single long
+ * agentic run (every user turn is a tool_result), so compaction was a no-op
+ * exactly when a long task needs it most.
+ */
+export declare function findSafeCutIndex(messages: Message[], maxIdx: number): number;
+/**
+ * Render messages to a plain-text transcript for the summariser (tool noise
+ * truncated per-block AND the whole transcript hard-capped). When the transcript
+ * would exceed MAX_TRANSCRIPT_CHARS we keep the HEAD (original task + early
+ * decisions) and the TAIL (most-recent, highest-signal context) and drop the
+ * middle — a middle-out elision that preserves both "what we set out to do" and
+ * "where we are now", which is what the continuation summary needs most.
+ */
+/**
+ * Appends the backend-announced runtime-context block to the user message it was
+ * attached to. No-op if that message is not a user turn or already ends with the
+ * identical block. Exported for tests.
+ */
+export declare function persistRuntimeContext(messages: Message[], idx: number, text: string): boolean;
+export declare function transcriptOf(messages: Message[]): string;
+export interface ProgressLedger {
+    filesTouched: Map<string, {
+        tool: string;
+        edits: number;
+    }>;
+    /**
+     * DISTINCT paths ever touched, including any since evicted from `filesTouched`.
+     *
+     * The Map is bounded (see ledgerRecord), so `filesTouched.size` is a window, not a
+     * total. The preamble states "FILES CHANGED THIS SESSION (N)" as a fact the model
+     * reasons about, so N must not silently shrink when eviction kicks in on a very long
+     * run — that would tell the model less work happened than actually did.
+     */
+    filesTouchedTotal: number;
+    verifications: Array<{
+        cmd: string;
+        ok: boolean;
+        epoch: number;
+    }>;
+    /** Test-integrity findings (reward-hacking signals) that must survive compaction. */
+    testIntegrity: Array<{
+        path: string;
+        reason: string;
+    }>;
+    /**
+     * TOTAL test-integrity findings ever recorded, including ones since trimmed.
+     *
+     * `testIntegrity` is a bounded window (older entries are spliced off once it grows
+     * past 2×LEDGER_MAX_NOTES), so its `.length` STOPS being a running total after the
+     * first trim. The one-shot nudge compares "how many findings exist" against "how
+     * many I've already surfaced", and comparing against a window that shrinks meant the
+     * count could never move ahead again — silently disabling the reward-hacking warning
+     * for the remainder of a long session, i.e. exactly when it matters most.
+     *
+     * This counter only ever increases, so it is a safe basis for that comparison.
+     */
+    testIntegrityTotal: number;
+    /**
+     * Monotonic mutation epoch: incremented on every successful source write. Two
+     * verification runs sharing an epoch had NO edit between them, so a PASS↔FAIL
+     * flip across that boundary proves the test is flaky (see detectFlaky).
+     */
+    epoch: number;
+}
+export declare function createLedger(): ProgressLedger;
+/** Record one tool call's effect on the ledger (deterministic, no model call). */
+export declare function ledgerRecord(ledger: ProgressLedger, toolName: string, input: Record<string, unknown> | undefined, ok: boolean, output?: string, exitCode?: number): void;
+/** Render the ledger as a compact, verbatim block for the compaction preamble. */
+export declare function ledgerSummary(ledger: ProgressLedger): string;
+export declare const PRUNE_KEEP_RECENT = 8;
+/**
+ * Lossy-but-structure-preserving prune: shrink OLD, large tool_result blocks in
+ * place, keeping the last PRUNE_KEEP_RECENT messages untouched. This is tried
+ * BEFORE summarisation because it:
+ *   • keeps every turn and every tool_use/tool_result pair (API stays valid),
+ *   • never makes an extra model call (summarisation does — cost + latency),
+ *   • degrades gracefully on repeat (summarise-of-summarise loses the most on
+ *     long runs; pruning just trims already-consumed output further).
+ *
+ * IMPORTANT: pruned state is encoded in the content string (PRUNE_MARKER_TAIL
+ * suffix), NOT as an extra property on the block — a stray field on a content
+ * block is rejected by the Anthropic API as an unknown key (400). This keeps the
+ * serialised body schema-clean while remaining idempotent across repeat calls.
+ *
+ * Returns the number of bytes reclaimed (0 if nothing was prunable).
+ *
+ * `minReclaimBytes` (default 0): if the TOTAL prunable amount is below this, the
+ * function makes NO changes and returns 0. This is a cache-safety gate — pruning
+ * even one old block changes the request prefix and invalidates the message-level
+ * prompt cache, so a tiny prune would bust the cache (re-write at 1.25×) for
+ * almost no size win. Measuring first, then applying only if worthwhile, keeps
+ * the "don't bust cache for a trivial gain" contract truly atomic (the old code
+ * mutated first and let the caller decide, which had already invalidated the
+ * cache by the time the caller declined).
+ */
+export declare function pruneOldToolResults(messages: Message[], minReclaimBytes?: number): number;
+/**
+ * The summariser's own model call failed — as opposed to running fine but not
+ * shrinking anything.
+ *
+ * These two outcomes used to be one `return false`, and collapsing them was a
+ * real bug: the in-loop circuit breaker disables auto-compaction permanently
+ * after COMPACT_MAX_FAILURES, on the sound theory that a compaction which cannot
+ * reclaim bytes will never start. But a summariser that THREW says nothing about
+ * whether compaction would help — only that the network/provider was unavailable
+ * for a moment. Feeding those into the same counter meant three transient blips
+ * (a 529 burst, a brief outage, a rate-limit spike) permanently switched off the
+ * one mechanism keeping the context under control, and the run then died at the
+ * context wall minutes later with its own recovery already disabled.
+ */
+export declare class CompactionUnavailableError extends Error {
+    constructor();
+}
+/**
+ * Summarises the WHOLE conversation by appending the instruction to its final user
+ * message and sending it with the conversation's own request options — Claude Code's
+ * approach. The prefix is byte-identical to the previous request, so the history is a
+ * cache READ (0.10×) instead of a fresh uncached transcript of up to 600K chars.
+ * Returns '' when it cannot be used (last turn is not the user's) or yields no text.
+ */
+export type CachedSummarizer = (instruction: string) => Promise<string>;
+export declare function makeCachedSummarizer(messages: Message[], requestOptions: () => Parameters<typeof streamChat>[1], abortSignal?: {
+    aborted: boolean;
+}): CachedSummarizer;
+export declare function autoCompactMessages(messages: Message[], options: AgentLoopOptions, ledger?: ProgressLedger, summarizeCached?: CachedSummarizer): Promise<boolean>;
+export declare function maybeCompactMemory(scope: MemoryScope, options: AgentLoopOptions): Promise<void>;
+/** Rough token estimate for a resumed transcript — no API round-trip needed. */
+export declare function estimateTokensRough(messages: Message[]): number;
+/**
+ * Proactively compact `messages` in place if resuming this session would blow
+ * past the auto-compact threshold on the very first turn. Returns true if any
+ * compaction happened (so the caller can surface a one-line notice to the
+ * user). Safe to call on any message array, including empty/small ones (no-op).
+ *
+ * `model` picks the right context window (mirrors runAgentLoop's own lookup);
+ * `onNotice` is optional — pass it to show the same "auto-compacted" message
+ * the in-loop path shows, so the behaviour is visually consistent.
+ */
+export declare function compactMessagesForResume(messages: Message[], opts: {
+    model?: string;
+    workDir: string;
+    clientType?: string;
+    env?: EnvContext;
+    onNotice?: (text: string) => void;
+}): Promise<boolean>;
+//# sourceMappingURL=compaction.d.ts.map

package/dist/agent/compaction.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"compaction.d.ts","sourceRoot":"","sources":["../../src/agent/compaction.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAgB,gBAAgB,EAAE,UAAU,EAAE,MAAM,UAAU,CAAC;AAIpF,OAAO,EAAE,UAAU,EAAE,MAAM,eAAe,CAAC;AAE3C,OAAO,EAAyB,KAAK,WAAW,EAAE,MAAM,UAAU,CAAC;AAmCnE,eAAO,MAAM,oBAAoB,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CA0CvD,CAAC;AAEF;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,CAAC,EAAE,MAAM,GAAG,MAAM,CAGvD;AAmDD,6FAA6F;AAC7F,wBAAgB,gBAAgB,CAC9B,aAAa,EAAE,MAAM,EACrB,WAAW,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GACpC;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CASpC;AAED,kHAAkH;AAClH,wBAAgB,oBAAoB,CAClC,aAAa,SAAY,EACzB,WAAW,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GACpC;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CAGpC;AAMD,eAAO,MAAM,uBAAuB,QAAa,CAAC;AAUlD,eAAO,MAAM,mBAAmB,qBAA4B,CAAC;AAC7D,wBAAgB,iBAAiB,CAAC,eAAe,EAAE,MAAM,GAAG,SAAS,EAAE,GAAG,SAAa,GAAG,MAAM,CAI/F;AACD,eAAO,MAAM,gBAAgB,IAAI,CAAC;AAElC;;;;;;;;GAQG;AACH,eAAO,MAAM,yBAAyB,QAAY,CAAC;AAEnD;;;;;;;;GAQG;AACH,eAAO,MAAM,oBAAoB,IAAI,CAAC;AAgBtC,eAAO,MAAM,cAAc,QAAkB,CAAC;AAE9C,+EAA+E;AAC/E,wBAAgB,iBAAiB,CAAC,QAAQ,EAAE,OAAO,EAAE,GAAG,MAAM,CAM7D;AAED,wBAAgB,kBAAkB,CAAC,WAAW,EAAE,OAAO,GAAG,SAAS,EAAE,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,OAAO,CAQlH;AAED,2EAA2E;AAC3E,wBAAgB,wBAAwB,CAAC,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,OAAO,CAOtF;AAED,iFAAiF;AACjF,eAAO,MAAM,gBAAgB,aAA+G,CAAC;AAC7I;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,GAAG,OAAO,CA8BrG;AAED,gGAAgG;AAChG,eAAO,MAAM,aAAa,QAA2J,CAAC;AAEtL;;;;;;;;;;;;GAYG;AACH,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,OAAO,EAAE,EAAE,MAAM,EAAE,MAAM,GAAG,MAAM,CAK5E;AAUD;;;;;;;GAOG;AACH;;;;GAIG;AACH,wBAAgB,qBAAqB,CAAC,QAAQ,EAAE,OAAO,EAAE,EAAE,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAO7F;AAED,wBAAgB,YAAY,CAAC,QAAQ,EAAE,OAAO,EAAE,GAAG,MAAM,CAyBxD;AAoBD,MAAM,WAAW,cAAc;IAC7B,YAAY,EAAE,GAAG,CAAC,MAAM,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IAC3D;;;;;;;OAOG;IACH,iBAAiB,EAAE,MAAM,CAAC;IAC1B,aAAa,EAAE,KAAK,CAAC;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,EAAE,EAAE,OAAO,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IAClE,qFAAqF;IACrF,aAAa,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IACvD;;;;;;;;;;;OAWG;IACH,kBAAkB,EAAE,MAAM,CAAC;IAC3B;;;;OAIG;IACH,KAAK,EAAE,MAAM,CAAC;CACf;AAED,wBAAgB,YAAY,IAAI,cAAc,CAE7C;AAED,kFAAkF;AAClF,wBAAgB,YAAY,CAC1B,MAAM,EAAE,cAAc,EACtB,QAAQ,EAAE,MAAM,EAChB,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,EAC1C,EAAE,EAAE,OAAO,EACX,MAAM,CAAC,EAAE,MAAM,EACf,QAAQ,CAAC,EAAE,MAAM,GAChB,IAAI,CA2EN;AAED,kFAAkF;AAClF,wBAAgB,aAAa,CAAC,MAAM,EAAE,cAAc,GAAG,MAAM,CAgC5D;AAOD,eAAO,MAAM,iBAAiB,IAAI,CAAC;AAYnC;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,wBAAgB,mBAAmB,CAAC,QAAQ,EAAE,OAAO,EAAE,EAAE,eAAe,SAAI,GAAG,MAAM,CAwCpF;AAiBD;;;;;;;;;;;;;GAaG;AACH,qBAAa,0BAA2B,SAAQ,KAAK;;CAKpD;AAED;;;;;;GAMG;AACH,MAAM,MAAM,gBAAgB,GAAG,CAAC,WAAW,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,CAAC,CAAC;AAExE,wBAAgB,oBAAoB,CAClC,QAAQ,EAAE,OAAO,EAAE,EACnB,cAAc,EAAE,MAAM,UAAU,CAAC,OAAO,UAAU,CAAC,CAAC,CAAC,CAAC,EACtD,WAAW,CAAC,EAAE;IAAE,OAAO,EAAE,OAAO,CAAA;CAAE,GACjC,gBAAgB,CAsBlB;AASD,wBAAsB,mBAAmB,CACvC,QAAQ,EAAE,OAAO,EAAE,EACnB,OAAO,EAAE,gBAAgB,EACzB,MAAM,CAAC,EAAE,cAAc,EACvB,eAAe,CAAC,EAAE,gBAAgB,GACjC,OAAO,CAAC,OAAO,CAAC,CA2HlB;AAaD,wBAAsB,kBAAkB,CAAC,KAAK,EAAE,WAAW,EAAE,OAAO,EAAE,gBAAgB,GAAG,OAAO,CAAC,IAAI,CAAC,CAgCrG;AAwBD,gFAAgF;AAChF,wBAAgB,mBAAmB,CAAC,QAAQ,EAAE,OAAO,EAAE,GAAG,MAAM,CAE/D;AAED;;;;;;;;;GASG;AACH,wBAAsB,wBAAwB,CAC5C,QAAQ,EAAE,OAAO,EAAE,EACnB,IAAI,EAAE;IACJ,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,GAAG,CAAC,EAAE,UAAU,CAAC;IACjB,QAAQ,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;CACnC,GACA,OAAO,CAAC,OAAO,CAAC,CAmFlB"}