@0xmaxma/claude-gateway 1.6.8 → 1.7.0

package/dist/agent/skill-learning/types.js

@@ -0,0 +1,11 @@
+"use strict";
+/**
+ * Skill-learning types — the closed Do → Learn → Improve loop.
+ *
+ * See planning-62-skill-learning.md. All durable rows live in the per-agent
+ * history.db (no second database). Provenance keys (`origin`, `pinned`,
+ * `createdFromSession`, `createdAt`) are ordinary extra frontmatter the skill
+ * parser already ignores, so a learned skill is a plain SKILL.md.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=types.js.map

package/dist/agent/skill-learning/types.js.map

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

package/dist/agent/skill-learning/writer.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Skill writer — applies a validated ReviewProposal to disk.
+ *
+ * The gateway (this module), NOT the reviewer model, writes files. All the
+ * safety guards live here:
+ *   - name / reserved-name / size validation (mirrors mcp/tools/skills/handlers.ts
+ *     — keep in sync; src/ cannot import from mcp/ because tsc rootDir is ./src).
+ *   - HARD provenance guard: only `origin: auto` skills are ever edited or
+ *     overwritten; a create that collides with a non-auto skill is refused.
+ *   - priority/dedup: a create that duplicates an existing auto skill (by name
+ *     or description) is downgraded to an edit of that skill.
+ *   - `mode: propose` writes to a review queue (`skills/.pending/`) instead of live.
+ */
+import type { ReviewProposal, WriteOutcome, SkillOrigin, SkillLearningMode } from './types';
+export declare const PENDING_DIRNAME = ".pending";
+export interface ExistingSkill {
+    name: string;
+    description: string;
+    origin: SkillOrigin;
+    filePath: string;
+}
+export interface WriterContext {
+    workspaceDir: string;
+    sessionId: string;
+    now: number;
+    mode: SkillLearningMode;
+    /** Existing skills for dedup + provenance decisions (name, desc, origin, path). */
+    existing: ExistingSkill[];
+}
+/** Read the `origin` frontmatter of an on-disk skill; missing ⇒ 'user' (never writable). */
+export declare function readSkillOrigin(filePath: string): SkillOrigin;
+/**
+ * Apply a proposal. Never throws — validation/guard failures return a
+ * `written:false` outcome with a reason. Idempotent per (name, content).
+ */
+export declare function applyProposal(proposal: ReviewProposal, ctx: WriterContext): WriteOutcome;
+//# sourceMappingURL=writer.d.ts.map

package/dist/agent/skill-learning/writer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"writer.d.ts","sourceRoot":"","sources":["../../../src/agent/skill-learning/writer.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAKH,OAAO,KAAK,EAAE,cAAc,EAAE,YAAY,EAAE,WAAW,EAAE,iBAAiB,EAAE,MAAM,SAAS,CAAC;AAU5F,eAAO,MAAM,eAAe,aAAa,CAAC;AAE1C,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,MAAM,EAAE,WAAW,CAAC;IACpB,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,aAAa;IAC5B,YAAY,EAAE,MAAM,CAAC;IACrB,SAAS,EAAE,MAAM,CAAC;IAClB,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,EAAE,iBAAiB,CAAC;IACxB,mFAAmF;IACnF,QAAQ,EAAE,aAAa,EAAE,CAAC;CAC3B;AAUD,4FAA4F;AAC5F,wBAAgB,eAAe,CAAC,QAAQ,EAAE,MAAM,GAAG,WAAW,CAQ7D;AAkDD;;;GAGG;AACH,wBAAgB,aAAa,CAAC,QAAQ,EAAE,cAAc,EAAE,GAAG,EAAE,aAAa,GAAG,YAAY,CAiGxF"}

package/dist/agent/skill-learning/writer.js

@@ -0,0 +1,223 @@
+"use strict";
+/**
+ * Skill writer — applies a validated ReviewProposal to disk.
+ *
+ * The gateway (this module), NOT the reviewer model, writes files. All the
+ * safety guards live here:
+ *   - name / reserved-name / size validation (mirrors mcp/tools/skills/handlers.ts
+ *     — keep in sync; src/ cannot import from mcp/ because tsc rootDir is ./src).
+ *   - HARD provenance guard: only `origin: auto` skills are ever edited or
+ *     overwritten; a create that collides with a non-auto skill is refused.
+ *   - priority/dedup: a create that duplicates an existing auto skill (by name
+ *     or description) is downgraded to an edit of that skill.
+ *   - `mode: propose` writes to a review queue (`skills/.pending/`) instead of live.
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PENDING_DIRNAME = void 0;
+exports.readSkillOrigin = readSkillOrigin;
+exports.applyProposal = applyProposal;
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+const parser_1 = require("../../skills/parser");
+// --- Guards mirrored from mcp/tools/skills/handlers.ts (keep in sync) ---------
+const VALID_NAME_RE = /^[a-z0-9][a-z0-9-]{0,63}$/;
+const RESERVED_NAMES = new Set([
+    'help', 'sessions', 'session', 'new', 'clear', 'compact',
+    'rename', 'model', 'restart', 'access', 'configure',
+]);
+const MAX_SKILL_SIZE = 100 * 1024; // 100KB
+exports.PENDING_DIRNAME = '.pending';
+function validateName(name) {
+    if (!VALID_NAME_RE.test(name)) {
+        return `invalid skill name "${name}" (lowercase alphanumeric + hyphens, 1-64 chars)`;
+    }
+    if (RESERVED_NAMES.has(name))
+        return `skill name "${name}" is reserved`;
+    return null;
+}
+/** Read the `origin` frontmatter of an on-disk skill; missing ⇒ 'user' (never writable). */
+function readSkillOrigin(filePath) {
+    try {
+        const raw = fs.readFileSync(filePath, 'utf-8');
+        const fm = (0, parser_1.extractFrontmatter)(raw)?.frontmatter;
+        return fm && fm['origin'] === 'auto' ? 'auto' : 'user';
+    }
+    catch {
+        return 'user';
+    }
+}
+function buildSkillMd(opts) {
+    // YAML-safe double-quoted scalar: collapse newlines (desc is single-line),
+    // strip other control chars, then escape backslashes BEFORE quotes. A raw
+    // backslash/newline in the (transcript-derived) description would otherwise
+    // produce invalid frontmatter → the freshly written skill never parses/loads.
+    const desc = opts.description
+        .replace(/[\r\n]+/g, ' ')
+        .replace(/[\x00-\x1f]/g, ' ')
+        .replace(/\\/g, '\\\\')
+        .replace(/"/g, '\\"');
+    return [
+        '---',
+        `name: ${opts.name}`,
+        `description: "${desc}"`,
+        `origin: ${opts.origin}`,
+        `createdFromSession: ${opts.createdFromSession}`,
+        `createdAt: ${opts.createdAt}`,
+        `pinned: ${opts.pinned}`,
+        '---',
+        '',
+        opts.body.trimEnd(),
+        '',
+    ].join('\n');
+}
+function atomicWrite(filePath, content) {
+    fs.mkdirSync(path.dirname(filePath), { recursive: true });
+    const tmp = filePath + '.tmp';
+    fs.writeFileSync(tmp, content, 'utf-8');
+    fs.renameSync(tmp, filePath);
+}
+/** Directory a skill (or its pending queue entry) is written to. */
+function skillFilePath(workspaceDir, name, queued) {
+    const base = queued
+        ? path.join(workspaceDir, 'skills', exports.PENDING_DIRNAME, name)
+        : path.join(workspaceDir, 'skills', name);
+    return path.join(base, 'SKILL.md');
+}
+/**
+ * Apply a proposal. Never throws — validation/guard failures return a
+ * `written:false` outcome with a reason. Idempotent per (name, content).
+ */
+function applyProposal(proposal, ctx) {
+    if (proposal.action === 'none')
+        return { written: false, action: 'none' };
+    const queued = ctx.mode === 'propose';
+    // Resolve intended action + target, applying priority/dedup for `create`.
+    let action = proposal.action;
+    let name = (proposal.name ?? proposal.targetSkill ?? '').trim();
+    let target;
+    if (proposal.action === 'edit') {
+        name = (proposal.targetSkill ?? proposal.name ?? '').trim();
+        target = ctx.existing.find((s) => s.name === name);
+        if (!target)
+            return { written: false, action: 'edit', name, reason: 'edit target not found' };
+        if (target.origin !== 'auto') {
+            return { written: false, action: 'edit', name, reason: 'provenance guard: target is not origin:auto' };
+        }
+    }
+    else {
+        // create — collision + dedup
+        const byName = ctx.existing.find((s) => s.name === name);
+        if (byName) {
+            if (byName.origin !== 'auto') {
+                return { written: false, action: 'create', name, reason: 'provenance guard: name collides with non-auto skill' };
+            }
+            // duplicate of an existing auto skill → downgrade to edit
+            action = 'edit';
+            target = byName;
+        }
+        else {
+            // dedup by description against auto skills → downgrade to edit
+            const byDesc = ctx.existing.find((s) => s.origin === 'auto' && normalizeDesc(s.description) === normalizeDesc(proposal.desc ?? ''));
+            if (byDesc && normalizeDesc(proposal.desc ?? '')) {
+                action = 'edit';
+                name = byDesc.name;
+                target = byDesc;
+            }
+        }
+    }
+    const nameError = validateName(name);
+    if (nameError)
+        return { written: false, action, name, reason: nameError };
+    const description = (proposal.desc ?? target?.description ?? '').trim();
+    const body = (proposal.body ?? '').trim();
+    if (!description)
+        return { written: false, action, name, reason: 'missing description' };
+    if (!body)
+        return { written: false, action, name, reason: 'missing body' };
+    // Preserve provenance on edit; stamp fresh on create.
+    let createdAt = ctx.now;
+    let createdFromSession = ctx.sessionId;
+    let pinned = false;
+    if (action === 'edit' && target) {
+        try {
+            const fm = (0, parser_1.extractFrontmatter)(fs.readFileSync(target.filePath, 'utf-8'))?.frontmatter;
+            if (fm) {
+                if (typeof fm['createdAt'] === 'number')
+                    createdAt = fm['createdAt'];
+                if (typeof fm['createdFromSession'] === 'string')
+                    createdFromSession = fm['createdFromSession'];
+                if (fm['pinned'] === true)
+                    pinned = true;
+            }
+        }
+        catch {
+            /* keep defaults */
+        }
+    }
+    const skillMd = buildSkillMd({
+        name,
+        description,
+        body,
+        origin: 'auto',
+        createdFromSession,
+        createdAt,
+        pinned,
+    });
+    if (Buffer.byteLength(skillMd, 'utf-8') > MAX_SKILL_SIZE) {
+        return { written: false, action, name, reason: `skill exceeds ${MAX_SKILL_SIZE} bytes` };
+    }
+    // HARD provenance guard against the on-disk source of truth (not just the
+    // in-memory `ctx.existing` registry). A user file can occupy the exact target
+    // path while being invisible to `ctx.existing` — its frontmatter fails to
+    // parse, or its `name` field differs from its directory. Re-read the real
+    // target and refuse unless it is origin:auto. Skips the `.pending` queue
+    // (separate namespace, never a live user skill).
+    const targetPath = skillFilePath(ctx.workspaceDir, name, queued);
+    if (!queued && fs.existsSync(targetPath) && readSkillOrigin(targetPath) !== 'auto') {
+        return { written: false, action, name, reason: 'provenance guard: on-disk target is not origin:auto' };
+    }
+    try {
+        atomicWrite(targetPath, skillMd);
+    }
+    catch (err) {
+        return { written: false, action, name, reason: `write failed: ${err.message}` };
+    }
+    return { written: true, action, name, queued };
+}
+function normalizeDesc(d) {
+    return d.trim().toLowerCase().replace(/\s+/g, ' ');
+}
+//# sourceMappingURL=writer.js.map

package/dist/agent/skill-learning/writer.js.map

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

package/dist/agent/workspace-loader.d.ts

@@ -2,6 +2,32 @@ import { LoadedWorkspace, WatchHandle } from '../types';
 export declare class MissingRequiredFileError extends Error {
     constructor(fileName: string);
 }
+export type OverBudgetMode = 'warn' | 'error';
+export interface MemoryBudgetConfig {
+    memoryBudgetChars: number;
+    userBudgetChars: number;
+    overBudget: OverBudgetMode;
+    writeRouting: boolean;
+}
+export declare const DEFAULT_MEMORY_BUDGET: MemoryBudgetConfig;
+/**
+ * Resolve a (possibly partial or malformed) memory-budget config into a complete
+ * one, falling back to the documented defaults. An unknown `overBudget` value or
+ * a non-numeric / negative budget is treated as "not set" and defaulted, so bad
+ * operator config never throws at compose (fail-safe, mirrors #310's tz guard).
+ */
+export declare function resolveMemoryBudget(cfg?: Partial<MemoryBudgetConfig>): MemoryBudgetConfig;
+/**
+ * Build a compact, injectable INDEX of an over-budget MEMORY.md (planning-64 K2
+ * core-shrink): the section headings, each top-level (`#`/`##`) section with a
+ * short brief, plus a pointer telling the agent the full content lives on disk and
+ * is reachable via the `memory_search` / `memory_get` tools. Derived
+ * deterministically from the file structure — NO LLM and NO mutation of the
+ * on-disk file. Fenced code blocks are skipped so a `# comment` inside ``` is not
+ * mistaken for a heading. Returns `null` when the file has no headings to index
+ * (caller then keeps full content).
+ */
+export declare function buildMemoryIndex(content: string, maxChars?: number): string | null;
 /**
  * Migrate workspace files from legacy lowercase names to uppercase canonical names.
  * - If lowercase exists and uppercase does NOT: rename lowercase → uppercase
@@ -15,6 +41,20 @@ export interface LoadWorkspaceOptions {
     logger?: {
         warn: (msg: string) => void;
     };
+    /**
+     * Soft per-file char budgets for MEMORY.md/USER.md. When omitted, the
+     * documented defaults (DEFAULT_MEMORY_BUDGET) apply — so callers and tests
+     * that don't pass it are unaffected.
+     */
+    memoryBudget?: Partial<MemoryBudgetConfig>;
+    /**
+     * K2 core-shrink (planning-64): when true, an over-budget MEMORY.md is injected
+     * as a compact auto-generated index + a pointer to the memory_search tool,
+     * instead of the banner + truncated full text. Defaults to FALSE (opt-in) — the
+     * gateway sets it true only when the knowledge archive is enabled, so the index
+     * pointer never references a tool that isn't wired.
+     */
+    coreShrink?: boolean;
 }
 /**
  * Load workspace markdown files and assemble the system prompt.
@@ -22,14 +62,51 @@ export interface LoadWorkspaceOptions {
 export declare function loadWorkspace(workspaceDir: string, opts?: LoadWorkspaceOptions): Promise<LoadedWorkspace>;
 /**
  * Canonical workspace files the agent is authorized to write itself, per the
- * memory rule (see MEMORY_RULE above). When ONLY these change, a busy session
- * must not be force-restarted: the change most likely came from that very
- * session mid-turn, and a deferred restart would stop it the moment the turn
- * completes (the self-restart footgun). Idle sessions are still restarted so
- * the change reaches them on their next spawn, and the recomposed CLAUDE.md
- * carries the change into every future spawn regardless.
+ * memory rule (see MEMORY_RULE above), split into two tiers by how urgently a
+ * change needs to reach a running session — and, crucially, by the fact that
+ * CLAUDE.md is frozen-at-spawn (a live process never re-reads it; the recomposed
+ * file applies on the next natural spawn regardless).
+ *
+ * MEMORY_FILES — self-authored data the agent writes about itself/the user
+ *   (MEMORY.md, USER.md). A write here is almost always the running session
+ *   curating its own memory mid-work. Since the process already holds what it
+ *   just wrote and every future spawn reads the recomposed CLAUDE.md, restarting
+ *   ANY session (busy or idle) buys nothing — it only drops in-context state and
+ *   forces a SQLite-replay respawn. Memory-only changes therefore restart
+ *   nothing at all (see the watcher callback in src/index.ts).
+ *
+ * IDENTITY_FILES — operator-authored identity (SOUL.md, AGENTS.md, IDENTITY.md).
+ *   These want to reach sessions "soon-ish", but still never justify SIGKILLing
+ *   an idle bystander: a deferred restart (respawn on next message) is lossless
+ *   and applies the change just as correctly. IDENTITY.md is API-writable and
+ *   composed into CLAUDE.md exactly like SOUL/AGENTS, so it belongs in this tier
+ *   for the same reason — omitting it would SIGKILL idle sessions on an
+ *   IDENTITY.md write while deferring the semantically identical SOUL write.
+ */
+export declare const MEMORY_FILES: Set<string>;
+export declare const IDENTITY_FILES: Set<string>;
+/**
+ * Union of the two tiers — kept for callers that only need "did the agent write
+ * this itself?" (e.g. the busy-session skip guard).
  */
 export declare const AGENT_WRITABLE_FILES: Set<string>;
+/**
+ * How a workspace change should affect already-running sessions. CLAUDE.md is
+ * always recomposed on disk regardless; this only decides the restart strategy.
+ *
+ *  - `none`        Restart nothing. Self-authored memory (MEMORY.md/USER.md):
+ *                  the writing session already holds the change and every future
+ *                  spawn reads the recomposed CLAUDE.md, so a restart is pure
+ *                  downside. A memory write can never drop a live session.
+ *  - `defer-idle`  Operator identity (SOUL.md/AGENTS.md/IDENTITY.md), possibly
+ *                  mixed with memory files: skip busy sessions (self-restart footgun) and
+ *                  defer idle ones (lossless respawn on next message) — never
+ *                  SIGKILL an idle bystander.
+ *  - `restart`     Any non-agent-writable change (HEARTBEAT.md, operator config,
+ *                  etc.) or an empty change list: today's normal restart-or-defer.
+ */
+export type WorkspaceRestartAction = 'none' | 'defer-idle' | 'restart';
+export declare function classifyWorkspaceRestart(changedFiles: string[]): WorkspaceRestartAction;
 /**
  * Watch a workspace directory for changes.
  * Calls onChange (debounced 300ms) with the de-duplicated list of canonical

package/dist/agent/workspace-loader.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"workspace-loader.d.ts","sourceRoot":"","sources":["../../src/agent/workspace-loader.ts"],"names":[],"mappings":"AAEA,OAAO,EAAkB,eAAe,EAAE,WAAW,EAAE,MAAM,UAAU,CAAC;AAIxE,qBAAa,wBAAyB,SAAQ,KAAK;gBACrC,QAAQ,EAAE,MAAM;CAI7B;AA6CD;;;;;GAKG;AACH,wBAAgB,qBAAqB,CAAC,YAAY,EAAE,MAAM,GAAG,IAAI,CAuBhE;AAED,MAAM,WAAW,oBAAoB;IACnC,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,MAAM,CAAC,EAAE;QAAE,IAAI,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,IAAI,CAAA;KAAE,CAAC;CAC1C;AAED;;GAEG;AACH,wBAAsB,aAAa,CAAC,YAAY,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,oBAAoB,GAAG,OAAO,CAAC,eAAe,CAAC,CAuE/G;AAID;;;;;;;;GAQG;AACH,eAAO,MAAM,oBAAoB,aAK/B,CAAC;AAWH;;;;;;;GAOG;AACH,wBAAgB,cAAc,CAC5B,YAAY,EAAE,MAAM,EACpB,QAAQ,EAAE,CAAC,YAAY,EAAE,MAAM,EAAE,KAAK,IAAI,GACzC,WAAW,CA8Cb"}
+{"version":3,"file":"workspace-loader.d.ts","sourceRoot":"","sources":["../../src/agent/workspace-loader.ts"],"names":[],"mappings":"AAEA,OAAO,EAAkB,eAAe,EAAE,WAAW,EAAE,MAAM,UAAU,CAAC;AAIxE,qBAAa,wBAAyB,SAAQ,KAAK;gBACrC,QAAQ,EAAE,MAAM;CAI7B;AA8ED,MAAM,MAAM,cAAc,GAAG,MAAM,GAAG,OAAO,CAAC;AAE9C,MAAM,WAAW,kBAAkB;IACjC,iBAAiB,EAAE,MAAM,CAAC;IAC1B,eAAe,EAAE,MAAM,CAAC;IAIxB,UAAU,EAAE,cAAc,CAAC;IAI3B,YAAY,EAAE,OAAO,CAAC;CACvB;AAKD,eAAO,MAAM,qBAAqB,EAAE,kBAKnC,CAAC;AAEF;;;;;GAKG;AACH,wBAAgB,mBAAmB,CAAC,GAAG,CAAC,EAAE,OAAO,CAAC,kBAAkB,CAAC,GAAG,kBAAkB,CAYzF;AAED;;;;;;;;;GASG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,MAAM,EAAE,QAAQ,SAAO,GAAG,MAAM,GAAG,IAAI,CA2ChF;AA+CD;;;;;GAKG;AACH,wBAAgB,qBAAqB,CAAC,YAAY,EAAE,MAAM,GAAG,IAAI,CAuBhE;AAED,MAAM,WAAW,oBAAoB;IACnC,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,MAAM,CAAC,EAAE;QAAE,IAAI,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,IAAI,CAAA;KAAE,CAAC;IACzC;;;;OAIG;IACH,YAAY,CAAC,EAAE,OAAO,CAAC,kBAAkB,CAAC,CAAC;IAC3C;;;;;;OAMG;IACH,UAAU,CAAC,EAAE,OAAO,CAAC;CACtB;AAED;;GAEG;AACH,wBAAsB,aAAa,CAAC,YAAY,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,oBAAoB,GAAG,OAAO,CAAC,eAAe,CAAC,CA+F/G;AAID;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,eAAO,MAAM,YAAY,aAA4C,CAAC;AACtE,eAAO,MAAM,cAAc,aAA2D,CAAC;AAEvF;;;GAGG;AACH,eAAO,MAAM,oBAAoB,aAG/B,CAAC;AAEH;;;;;;;;;;;;;;GAcG;AACH,MAAM,MAAM,sBAAsB,GAAG,MAAM,GAAG,YAAY,GAAG,SAAS,CAAC;AAEvE,wBAAgB,wBAAwB,CAAC,YAAY,EAAE,MAAM,EAAE,GAAG,sBAAsB,CAKvF;AAWD;;;;;;;GAOG;AACH,wBAAgB,cAAc,CAC5B,YAAY,EAAE,MAAM,EACpB,QAAQ,EAAE,CAAC,YAAY,EAAE,MAAM,EAAE,KAAK,IAAI,GACzC,WAAW,CA8Cb"}