charness 0.0.0-stage → 3.0.0

package/dist/requests/requestHeader.d.ts

@@ -0,0 +1,70 @@
+import type { OpenRequestState, RequestWakeUpReason } from './types';
+/**
+ * @description The per-request header that rides inside the prompt text of every
+ * request (request/answer core S3). The standing rule lives in the bot MCP's
+ * connect-time instructions; the header is still needed per request because it
+ * names THIS request's id, and because whether the requester sees the agent's
+ * plain text can change mid-session (a Telegram view switch) or never holds
+ * (a tracker). Agent-facing, so English on every surface.
+ */
+/**
+ * @name RequestHeaderOptions
+ * @description `originDescription` says where the request came from in a few
+ * words ("a message in this topic", "PROJ-123 assigned to you by …").
+ * `isPlainTextHidden` adds the line that the requester never sees the agent's
+ * ordinary output or its thinking. `supersededRequestIds` are the same requester's earlier
+ * requests this one replaced while they were still open (`requestGroup.ts`);
+ * when given, the header names them and asks for only what THIS request adds.
+ * The line holds in both timings (owner decision 2026-10-05): the agent reads it
+ * mid-turn and gives one answer, or — Claude Code delivers a message written
+ * mid-turn only after that turn ends — it has already answered the replaced
+ * request and must not do the work twice.
+ */
+export interface RequestHeaderOptions {
+    requestId: string;
+    originDescription: string;
+    isPlainTextHidden: boolean;
+    supersededRequestIds?: readonly string[];
+}
+/** @description The header's line naming the requests this one replaced; empty when it replaced none. */
+export declare function buildSupersededRequestsLine(supersededRequestIds: readonly string[]): string;
+/** @description The header block, ending with a blank line before the request's own text. */
+export declare function buildRequestHeader(options: RequestHeaderOptions): string;
+/**
+ * @name WakeUpMessage
+ * @description What a wake-up forwards: the request's own prompt when it never
+ * reached the agent (R21), else the reminder for `reason`.
+ */
+export interface WakeUpMessage {
+    reason: RequestWakeUpReason;
+    text: string;
+    isRequestPrompt: boolean;
+}
+/**
+ * @description The request's own prompt while the session never took it in — its
+ * post failed, a restart came first, a usage-limit wait held it (R21); `undefined`
+ * once it was taken in, or when the request keeps no prompt.
+ */
+export declare function getPromptNotTakenIn(request: OpenRequestState | null | undefined): string | undefined;
+/**
+ * @description The prompts of every request in `requests` the session never took
+ * in, in the given order, as ONE text to post — a conversation may hold one open
+ * request per requester, and a resume must re-post each of them. `undefined` when
+ * none is left to post.
+ */
+export declare function joinPromptsNotTakenIn(requests: readonly OpenRequestState[]): string | undefined;
+/**
+ * @description R21: a request whose prompt was never taken in by the session gets
+ * the prompt itself; a bare reminder would name a request the agent never read.
+ */
+export declare function getWakeUpMessage(request: OpenRequestState, reason: RequestWakeUpReason): WakeUpMessage;
+/**
+ * @description The reminder the wake-up engine forwards into the SAME session for
+ * an open request. It is not a request itself: it names the open one and asks
+ * for the answer through `answer_request`.
+ */
+export declare function buildWakeUpReminder(options: {
+    requestId: string;
+    reason: RequestWakeUpReason;
+}): string;
+//# sourceMappingURL=requestHeader.d.ts.map

package/dist/requests/requestHeader.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"requestHeader.d.ts","sourceRoot":"","sources":["../../src/requests/requestHeader.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,mBAAmB,EAAE,MAAM,SAAS,CAAC;AAErE;;;;;;;GAOG;AAEH;;;;;;;;;;;;GAYG;AACH,MAAM,WAAW,oBAAoB;IACnC,SAAS,EAAE,MAAM,CAAC;IAClB,iBAAiB,EAAE,MAAM,CAAC;IAC1B,iBAAiB,EAAE,OAAO,CAAC;IAC3B,oBAAoB,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CAC1C;AAED,yGAAyG;AACzG,wBAAgB,2BAA2B,CAAC,oBAAoB,EAAE,SAAS,MAAM,EAAE,GAAG,MAAM,CAM3F;AAED,6FAA6F;AAC7F,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,oBAAoB,GAAG,MAAM,CAYxE;AAUD;;;;GAIG;AACH,MAAM,WAAW,aAAa;IAC5B,MAAM,EAAE,mBAAmB,CAAC;IAC5B,IAAI,EAAE,MAAM,CAAC;IACb,eAAe,EAAE,OAAO,CAAC;CAC1B;AAED;;;;GAIG;AACH,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,gBAAgB,GAAG,IAAI,GAAG,SAAS,GAAG,MAAM,GAAG,SAAS,CAEpG;AAKD;;;;;GAKG;AACH,wBAAgB,qBAAqB,CAAC,QAAQ,EAAE,SAAS,gBAAgB,EAAE,GAAG,MAAM,GAAG,SAAS,CAG/F;AAED;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,gBAAgB,EAAE,MAAM,EAAE,mBAAmB,GAAG,aAAa,CAItG;AAED;;;;GAIG;AACH,wBAAgB,mBAAmB,CAAC,OAAO,EAAE;IAAE,SAAS,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,mBAAmB,CAAA;CAAE,GAAG,MAAM,CAOvG"}

package/dist/requests/requestHeader.js

@@ -0,0 +1,83 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildSupersededRequestsLine = buildSupersededRequestsLine;
+exports.buildRequestHeader = buildRequestHeader;
+exports.getPromptNotTakenIn = getPromptNotTakenIn;
+exports.joinPromptsNotTakenIn = joinPromptsNotTakenIn;
+exports.getWakeUpMessage = getWakeUpMessage;
+exports.buildWakeUpReminder = buildWakeUpReminder;
+/** @description The header's line naming the requests this one replaced; empty when it replaced none. */
+function buildSupersededRequestsLine(supersededRequestIds) {
+    if (supersededRequestIds.length === 0)
+        return '';
+    const isOne = supersededRequestIds.length === 1;
+    return `It replaces the same requester's earlier ${isOne ? 'request' : 'requests'} ${supersededRequestIds.join(', ')}. ` +
+        `If you already answered ${isOne ? 'it' : 'them'}, do not repeat that answer: reply only to what this message adds. ` +
+        'If it adds nothing new, say briefly that the answer is above.';
+}
+/** @description The header block, ending with a blank line before the request's own text. */
+function buildRequestHeader(options) {
+    const lines = [
+        `[Request ${options.requestId} · from: ${options.originDescription}]`,
+        `Answer it with the answer_request tool (requestId "${options.requestId}"): kind "final" with the full result at the end of your turn, ` +
+            '"question" if you need the requester before you can go on, "progress" for an interim note.',
+    ];
+    const supersededLine = buildSupersededRequestsLine(options.supersededRequestIds ?? []);
+    if (supersededLine !== '')
+        lines.push(supersededLine);
+    if (options.isPlainTextHidden) {
+        lines.push('The requester does not see your plain text output or your thinking — only what you send through answer_request reaches them.');
+    }
+    return `${lines.join('\n')}\n\n`;
+}
+/** What the reminder tells the agent, per wake-up reason. */
+const wakeUpReasonLines = {
+    silentTurn: 'Your last turn ended without answering it.',
+    progressFollowUp: 'Some time has passed since your last progress note on it.',
+    backstop: 'Nothing has been seen working on it for a long time (the session may have restarted).',
+    postRetry: 'It could not be delivered to you earlier.',
+};
+/**
+ * @description The request's own prompt while the session never took it in — its
+ * post failed, a restart came first, a usage-limit wait held it (R21); `undefined`
+ * once it was taken in, or when the request keeps no prompt.
+ */
+function getPromptNotTakenIn(request) {
+    return request?.isPromptTakenIn === true ? undefined : request?.prompt;
+}
+/** Between two requests' prompts re-posted in one message (each prompt ends with its own text, not a blank line). */
+const joinedPromptsSeparator = '\n\n';
+/**
+ * @description The prompts of every request in `requests` the session never took
+ * in, in the given order, as ONE text to post — a conversation may hold one open
+ * request per requester, and a resume must re-post each of them. `undefined` when
+ * none is left to post.
+ */
+function joinPromptsNotTakenIn(requests) {
+    const prompts = requests.map(getPromptNotTakenIn).filter((prompt) => prompt !== undefined);
+    return prompts.length === 0 ? undefined : prompts.join(joinedPromptsSeparator);
+}
+/**
+ * @description R21: a request whose prompt was never taken in by the session gets
+ * the prompt itself; a bare reminder would name a request the agent never read.
+ */
+function getWakeUpMessage(request, reason) {
+    const prompt = getPromptNotTakenIn(request);
+    if (prompt !== undefined)
+        return { reason, text: prompt, isRequestPrompt: true };
+    return { reason, text: buildWakeUpReminder({ requestId: request.id, reason }), isRequestPrompt: false };
+}
+/**
+ * @description The reminder the wake-up engine forwards into the SAME session for
+ * an open request. It is not a request itself: it names the open one and asks
+ * for the answer through `answer_request`.
+ */
+function buildWakeUpReminder(options) {
+    return [
+        `[Reminder · request ${options.requestId} is still open]`,
+        wakeUpReasonLines[options.reason],
+        `Answer it with answer_request (requestId "${options.requestId}"): kind "final" if the work is done, ` +
+            '"question" if you need the requester, or a short "progress" note if you are still working — then continue.',
+    ].join('\n');
+}
+//# sourceMappingURL=requestHeader.js.map

package/dist/requests/requestHeader.js.map

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

package/dist/requests/requestLedger.d.ts

@@ -0,0 +1,217 @@
+import { type SessionKey } from '../sessionKey';
+import { type StateStore } from '../state';
+import { RotatingJsonlFile } from '../utils/rotatingJsonlFile';
+import { type RequestGroupKey } from './requestGroup';
+import type { ClosedRequestRecord, OpenRequestState, OpenRequestUpdate, RequestCloseReason, RequestLookup, RequestOrigin, UnreleasedRequestAlert, RequestPromptOutcome } from './types';
+/**
+ * @description The request ledger (core plan S2): which unit of work each
+ * conversation's agent still owes an answer to.
+ *
+ *   open set  — `state.json` `openRequests`, at most ONE per request GROUP
+ *               (`requestGroup.ts`: the platform-agnostic `SessionKey` of the
+ *               conversation — Telegram topics and tracker issues alike — plus
+ *               the requester). A new request SUPERSEDES the group's open one;
+ *               other requesters' requests in the conversation stay open.
+ *   history   — `DATA_DIR/requests.jsonl`, one line per CLOSED request
+ *               (append-only, one rotated backup).
+ *
+ * A recently closed request stays known by id — an answer to it is still
+ * delivered, it just changes no request — so the history is indexed in memory
+ * at {@link RequestLedger.load}, bounded to the most recent
+ * {@link closedRequestIndexMaxSize} closed requests. A new request is durably
+ * saved before its id is handed out. Until the load resolves the ledger refuses every call
+ * (it throws): the bot MCP server starts serving before sessions re-attach, and
+ * an answer looked up against a not-yet-loaded history would wrongly be refused
+ * as an unknown id. Tool handlers gate on {@link RequestLedger.whenLoaded}.
+ *
+ * Crash ordering: the history line is written BEFORE the open entry is dropped,
+ * and `load` drops any open entry the history already shows closed — so a crash
+ * between the two writes never leaves a request both open and closed.
+ */
+/** History size bound per file before it rolls to `.1` (same as the run ledger). */
+export declare const requestHistoryMaxBytes: number;
+/** The longest prompt an open request keeps for a re-post (R21); `state.json` is rewritten whole. */
+export declare const requestPromptMaxLength = 64000;
+/**
+ * How many replaced ids a request carries (`supersededRequestIds`): a requester
+ * who keeps writing without an answer in between builds a chain, and the header
+ * naming it must stay short. The newest ones are kept.
+ */
+export declare const supersededRequestIdsMaxLength = 10;
+/**
+ * How many CLOSED requests stay known by id (the most recent ones). A closed id
+ * is looked up only for a late answer — a turn still running when a newer
+ * request superseded its own — which arrives minutes, at most hours (a usage
+ * limit wait) after the close. 5 000 covers weeks of traffic even with every
+ * operator message a request (a few hundred a day), while keeping memory fixed
+ * (~1–2 MB) regardless of how long the bot runs. An answer to an id that fell
+ * out of the window is refused as unknown.
+ */
+export declare const closedRequestIndexMaxSize = 5000;
+/** Thrown when the ledger is used before {@link RequestLedger.load} resolved. */
+export declare class RequestLedgerNotLoadedError extends Error {
+    constructor();
+}
+/** The part of the state store the ledger reads and writes. */
+export type RequestLedgerStore = Pick<StateStore, 'getOpenRequests' | 'getOpenRequest' | 'updateOpenRequest' | 'flush' | 'getUnreleasedRequestAlerts' | 'addUnreleasedRequestAlert' | 'removeUnreleasedRequestAlert'>;
+/**
+ * @name RequestLedgerDeps
+ * @description `history`, `now` and `closedIndexMaxSize` are injectable for
+ * tests; production uses the `DATA_DIR` history file, the wall clock and
+ * {@link closedRequestIndexMaxSize}.
+ */
+export interface RequestLedgerDeps {
+    store: RequestLedgerStore;
+    /**
+     * Release the alert a closed request held (Telegram: unpin it). The ledger
+     * keeps the alert in `state.json` until this resolves, and retries every one
+     * still unreleased at the next load — a rejection leaves it for that retry.
+     */
+    releaseAlert?: (alert: UnreleasedRequestAlert) => Promise<void>;
+    /**
+     * Called for every new request once it is durably saved, before its id is
+     * handed out — whoever opened it. The boot uses it to tell a request opened
+     * during a usage-limit wait about that wait. Must not throw.
+     */
+    onRequestCreated?: (key: SessionKey, request: OpenRequestState) => void;
+    /**
+     * Told once what became of a request's prompt (`RequestPromptOutcome`), after the change is applied (a
+     * supersede: also flushed; a flag or a close: its save only scheduled — a crash before it re-posts the whole
+     * prompt, so nothing is lost) — so a connector can count what the prompt carried as sent only once the agent
+     * took it in. Every writer of `isPromptTakenIn` and every close goes through the ledger, so none is missed.
+     * Must not throw.
+     */
+    onPromptSettled?: (key: SessionKey, requestId: string, outcome: RequestPromptOutcome) => void;
+    history?: RotatingJsonlFile<ClosedRequestRecord>;
+    now?: () => number;
+    closedIndexMaxSize?: number;
+}
+/**
+ * @name OpenRequestUpdater
+ * @description How to change an open request: a patch, or a function of the
+ * CURRENT request run under the per-conversation lock (for a read-modify-write
+ * such as a counter increment that must not lose a concurrent one).
+ */
+export type OpenRequestUpdater = OpenRequestUpdate | ((current: OpenRequestState) => OpenRequestUpdate);
+/** @description An open request together with its conversation (`key`) and its group. */
+export interface OpenRequestEntry {
+    key: SessionKey;
+    group: RequestGroupKey;
+    request: OpenRequestState;
+}
+/**
+ * @name CreateRequestOptions
+ * @description `createPrompt` builds the prompt the request keeps for a re-post
+ * (R21) from the id just drawn and the ids of the open requests it replaces —
+ * the same inputs the header is built from, so the kept prompt and the forwarded
+ * one read the same.
+ */
+export interface CreateRequestOptions {
+    createPrompt?: (requestId: string, supersededRequestIds: readonly string[]) => string;
+}
+/**
+ * @description Parse one history line, or `null` for a line that is not a
+ * closed request (truncated by a crash, hand-edited, written by a different
+ * version). Every field is checked and the record rebuilt from them.
+ */
+export declare function parseClosedRequestLine(line: string): ClosedRequestRecord | null;
+export declare class RequestLedger {
+    private readonly store;
+    private readonly history;
+    private readonly now;
+    private readonly closedIndexMaxSize;
+    private readonly releaseAlert;
+    private readonly onRequestCreated;
+    private readonly onPromptSettled;
+    /** Request ids whose alert release is under way, so two paths never release one twice at once. */
+    private readonly alertReleasesInFlight;
+    /** Insertion order = close order, so the first key is always the oldest. */
+    private readonly closedById;
+    private loadPromise;
+    private isLoaded;
+    private resolveLoaded;
+    private readonly loadedPromise;
+    constructor(deps: RequestLedgerDeps);
+    /**
+     * @description Index the closed-request history and drop open entries it
+     * already shows closed. Idempotent: every call returns the same promise. A
+     * history that cannot be read rejects (the boot surfaces it) and leaves the
+     * ledger unloaded rather than serving a partial index as the truth.
+     */
+    load(): Promise<void>;
+    /** @description Resolves once {@link load} has finished; never rejects. */
+    whenLoaded(): Promise<void>;
+    /** @description True once {@link load} has finished. */
+    checkIsLoaded(): boolean;
+    private runLoad;
+    private assertLoaded;
+    /** Open entries whose group key still decodes (a key of an unregistered platform is left alone), oldest first. */
+    private getOpenEntries;
+    private getOpenEntryById;
+    private createRequestId;
+    /** A close settles the prompt unless it was already taken in: by its own answer it was, otherwise it was dropped. */
+    private getCloseOutcome;
+    private notePromptSettled;
+    private appendClosed;
+    /**
+     * Record a closed request's alert as still to release (synchronously, so it
+     * rides the close's own save), then release it.
+     */
+    private queueAlertRelease;
+    /** Release an alert; it leaves the unreleased list only once the release succeeded. */
+    private releaseAlertOf;
+    /**
+     * @description Store the alert a request now holds, DURABLY (flushed): a crash
+     * that lost it would leave the alert pinned forever. Resolves `false` when the
+     * request closed meanwhile — its close found no alert, so it is released here.
+     */
+    recordAlert(key: SessionKey, requestId: string, alertRef: string): Promise<boolean>;
+    /** Remember a closed request by id, forgetting the oldest beyond the window. */
+    private indexClosed;
+    /**
+     * @description Open a new request for `key`'s conversation. The open request of
+     * the same GROUP (same conversation, same requester — `getRequestGroupKey`), if
+     * any, is closed as `superseded` first, in the same atomic step — the latest
+     * message of a requester is the one that matters, and the new request names it
+     * (and what it had replaced in turn) in `supersededRequestIds`, so the agent
+     * answers only what the new one adds. Another requester's open request in the conversation is
+     * untouched. A request WITHOUT a requester (persisted before requesters
+     * existed, or raised by an origin that names none) keeps the old rule: the
+     * conversation's next request supersedes it whoever raised that one — else it
+     * would linger, woken again and again, with nothing left that could close it.
+     * Resolves only once the new request is DURABLY saved: its id is
+     * about to reach an agent, and an id the agent was told about but a crash lost
+     * would make its answer refused as unknown — a dropped result.
+     */
+    createRequest(key: SessionKey, origin: RequestOrigin, options?: CreateRequestOptions): Promise<OpenRequestState>;
+    /** @description A request by id, open or closed, or `null` for an unknown id. */
+    getRequest(id: string): RequestLookup | null;
+    /** @description The open request `id`, with its conversation, or `undefined` when `id` is not open. */
+    getOpenRequestById(id: string): OpenRequestEntry | undefined;
+    /**
+     * @description The open requests of `key`'s conversation, oldest first — one per
+     * requester at most (see `requestGroup.ts`).
+     */
+    listOpenRequestsOf(key: SessionKey): OpenRequestState[];
+    /**
+     * @description The NEWEST open request of `key`'s conversation, or `undefined`.
+     * A conversation may hold one open request per requester; a caller that must
+     * act on all of them uses {@link listOpenRequestsOf}.
+     */
+    getNewestOpenRequest(key: SessionKey): OpenRequestState | undefined;
+    /** @description Every open request with its conversation, oldest first. */
+    listOpenRequests(): OpenRequestEntry[];
+    /**
+     * @description Change the answer and wake-up bookkeeping of an open request.
+     * Resolves the updated request, or `null` when `id` is not open (closed or
+     * superseded in the meantime — the update is then dropped, never applied to
+     * its successor).
+     */
+    updateOpenRequest(id: string, update: OpenRequestUpdater): Promise<OpenRequestState | null>;
+    /**
+     * @description Close an open request. Resolves the closed record, or `null` when
+     * `id` is not open (an already closed request is never closed twice).
+     */
+    closeRequest(id: string, reason: RequestCloseReason): Promise<ClosedRequestRecord | null>;
+}
+//# sourceMappingURL=requestLedger.d.ts.map

package/dist/requests/requestLedger.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"requestLedger.d.ts","sourceRoot":"","sources":["../../src/requests/requestLedger.ts"],"names":[],"mappings":"AAEA,OAAO,EAAe,KAAK,UAAU,EAAE,MAAM,eAAe,CAAC;AAC7D,OAAO,EAAkB,KAAK,UAAU,EAAE,MAAM,UAAU,CAAC;AAC3D,OAAO,EAAE,iBAAiB,EAAE,MAAM,4BAA4B,CAAC;AAC/D,OAAO,EAAoE,KAAK,eAAe,EAAE,MAAM,gBAAgB,CAAC;AACxH,OAAO,KAAK,EACV,mBAAmB,EACnB,gBAAgB,EAChB,iBAAiB,EACjB,kBAAkB,EAClB,aAAa,EACb,aAAa,EAEb,sBAAsB,EACtB,oBAAoB,EACrB,MAAM,SAAS,CAAC;AAEjB;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAEH,oFAAoF;AACpF,eAAO,MAAM,sBAAsB,QAAmB,CAAC;AACvD,qGAAqG;AACrG,eAAO,MAAM,sBAAsB,QAAS,CAAC;AAM7C;;;;GAIG;AACH,eAAO,MAAM,6BAA6B,KAAK,CAAC;AAEhD;;;;;;;;GAQG;AACH,eAAO,MAAM,yBAAyB,OAAQ,CAAC;AAE/C,iFAAiF;AACjF,qBAAa,2BAA4B,SAAQ,KAAK;;CAKrD;AAED,+DAA+D;AAC/D,MAAM,MAAM,kBAAkB,GAAG,IAAI,CACnC,UAAU,EACR,iBAAiB,GACjB,gBAAgB,GAChB,mBAAmB,GACnB,OAAO,GACP,4BAA4B,GAC5B,2BAA2B,GAC3B,8BAA8B,CACjC,CAAC;AAEF;;;;;GAKG;AACH,MAAM,WAAW,iBAAiB;IAChC,KAAK,EAAE,kBAAkB,CAAC;IAC1B;;;;OAIG;IACH,YAAY,CAAC,EAAE,CAAC,KAAK,EAAE,sBAAsB,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IAChE;;;;OAIG;IACH,gBAAgB,CAAC,EAAE,CAAC,GAAG,EAAE,UAAU,EAAE,OAAO,EAAE,gBAAgB,KAAK,IAAI,CAAC;IACxE;;;;;;OAMG;IACH,eAAe,CAAC,EAAE,CAAC,GAAG,EAAE,UAAU,EAAE,SAAS,EAAE,MAAM,EAAE,OAAO,EAAE,oBAAoB,KAAK,IAAI,CAAC;IAC9F,OAAO,CAAC,EAAE,iBAAiB,CAAC,mBAAmB,CAAC,CAAC;IACjD,GAAG,CAAC,EAAE,MAAM,MAAM,CAAC;IACnB,kBAAkB,CAAC,EAAE,MAAM,CAAC;CAC7B;AAED;;;;;GAKG;AACH,MAAM,MAAM,kBAAkB,GAAG,iBAAiB,GAAG,CAAC,CAAC,OAAO,EAAE,gBAAgB,KAAK,iBAAiB,CAAC,CAAC;AAExG,yFAAyF;AACzF,MAAM,WAAW,gBAAgB;IAC/B,GAAG,EAAE,UAAU,CAAC;IAChB,KAAK,EAAE,eAAe,CAAC;IACvB,OAAO,EAAE,gBAAgB,CAAC;CAC3B;AAED;;;;;;GAMG;AACH,MAAM,WAAW,oBAAoB;IACnC,YAAY,CAAC,EAAE,CAAC,SAAS,EAAE,MAAM,EAAE,oBAAoB,EAAE,SAAS,MAAM,EAAE,KAAK,MAAM,CAAC;CACvF;AAUD;;;;GAIG;AACH,wBAAgB,sBAAsB,CAAC,IAAI,EAAE,MAAM,GAAG,mBAAmB,GAAG,IAAI,CAgD/E;AAED,qBAAa,aAAa;IACxB,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAqB;IAC3C,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAyC;IACjE,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAe;IACnC,OAAO,CAAC,QAAQ,CAAC,kBAAkB,CAAS;IAC5C,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAiE;IAC9F,OAAO,CAAC,QAAQ,CAAC,gBAAgB,CAAqE;IACtG,OAAO,CAAC,QAAQ,CAAC,eAAe,CAA4F;IAC5H,kGAAkG;IAClG,OAAO,CAAC,QAAQ,CAAC,qBAAqB,CAAqB;IAC3D,4EAA4E;IAC5E,OAAO,CAAC,QAAQ,CAAC,UAAU,CAA0C;IACrE,OAAO,CAAC,WAAW,CAA8B;IACjD,OAAO,CAAC,QAAQ,CAAS;IACzB,OAAO,CAAC,aAAa,CAAwB;IAC7C,OAAO,CAAC,QAAQ,CAAC,aAAa,CAE3B;gBAES,IAAI,EAAE,iBAAiB;IAUnC;;;;;OAKG;IACH,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;IAKrB,2EAA2E;IAC3E,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC;IAI3B,wDAAwD;IACxD,aAAa,IAAI,OAAO;YAIV,OAAO;IA+BrB,OAAO,CAAC,YAAY;IAIpB,kHAAkH;IAClH,OAAO,CAAC,cAAc;IAStB,OAAO,CAAC,gBAAgB;IAIxB,OAAO,CAAC,eAAe;IAQvB,qHAAqH;IACrH,OAAO,CAAC,eAAe;IAKvB,OAAO,CAAC,iBAAiB;IAIzB,OAAO,CAAC,YAAY;IAapB;;;OAGG;IACH,OAAO,CAAC,iBAAiB;IAKzB,uFAAuF;YACzE,cAAc;IAa5B;;;;OAIG;IACG,WAAW,CAAC,GAAG,EAAE,UAAU,EAAE,SAAS,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAWzF,gFAAgF;IAChF,OAAO,CAAC,WAAW;IAUnB;;;;;;;;;;;;;;OAcG;IACG,aAAa,CAAC,GAAG,EAAE,UAAU,EAAE,MAAM,EAAE,aAAa,EAAE,OAAO,GAAE,oBAAyB,GAAG,OAAO,CAAC,gBAAgB,CAAC;IAuD1H,iFAAiF;IACjF,UAAU,CAAC,EAAE,EAAE,MAAM,GAAG,aAAa,GAAG,IAAI;IAQ5C,uGAAuG;IACvG,kBAAkB,CAAC,EAAE,EAAE,MAAM,GAAG,gBAAgB,GAAG,SAAS;IAK5D;;;OAGG;IACH,kBAAkB,CAAC,GAAG,EAAE,UAAU,GAAG,gBAAgB,EAAE;IAQvD;;;;OAIG;IACH,oBAAoB,CAAC,GAAG,EAAE,UAAU,GAAG,gBAAgB,GAAG,SAAS;IAKnE,2EAA2E;IAC3E,gBAAgB,IAAI,gBAAgB,EAAE;IAKtC;;;;;OAKG;IACG,iBAAiB,CAAC,EAAE,EAAE,MAAM,EAAE,MAAM,EAAE,kBAAkB,GAAG,OAAO,CAAC,gBAAgB,GAAG,IAAI,CAAC;IAiBjG;;;OAGG;IACG,YAAY,CAAC,EAAE,EAAE,MAAM,EAAE,MAAM,EAAE,kBAAkB,GAAG,OAAO,CAAC,mBAAmB,GAAG,IAAI,CAAC;CAiBhG"}