@nocobase/app-plugin-agents 0.0.0-stage → 0.1.0-beta.1

package/dist/shared/reports.d.ts

@@ -0,0 +1,293 @@
+/**
+ * What runs used and cost, as the reporting service answers it (`agents.reporting`), and the model prices costs are
+ * estimated from. Costs are never stored: they are worked out from the prices whenever a report is read, so changing
+ * a price changes every report. This plugin serves the prices and the usage report over HTTP (`USAGE_ROUTE`, for its
+ * usage page); the application builds its other reports on the reporting service.
+ */
+/**
+ * `GET`: `from`, `to`, `groupBy`, `groupId`, `agentId`, `userId`, `series` → `{ data: UsageReport }`. Needs the usage
+ * page's grant.
+ */
+export declare const USAGE_ROUTE = "agents/usage";
+/**
+ * How the usage report groups runs; `person` is who woke the agent (the run's actor), `group` the group a run's subject
+ * belongs to (`SubjectFacts.group`), `subject` the subject itself, `type` the agent's type (`online` or `runner`; an online
+ * run's `tool` is `online`).
+ */
+export declare const USAGE_GROUP_BYS: readonly ["agent", "person", "group", "subject", "day", "model", "tool", "type"];
+export type UsageGroupBy = (typeof USAGE_GROUP_BYS)[number];
+/** A report covers at most this many days; without a range, the last `DEFAULT_REPORT_DAYS`. */
+export declare const MAX_REPORT_DAYS = 366;
+export declare const DEFAULT_REPORT_DAYS = 30;
+/** The currency of a price that names none. */
+export declare const DEFAULT_CURRENCY = "USD";
+/** The `tool` of an online run's usage: its model calls go through a model service, which is the price's source. */
+export declare const ONLINE_TOOL = "online";
+/**
+ * What a model costs per million tokens at one source. A price belongs to a source and a model together, since the same
+ * model costs differently at different providers and through different coding tools:
+ *
+ * - Online (`tool` `online`): the model service the run called (`modelService`); `model` is the model id, matched exactly.
+ * - Runner (`tool` a coding tool such as `claude` or `codex`, `modelService` null): `model` is an id or a glob (`*` for any
+ *   run of characters, case-insensitive); the most specific match wins (an exact id, then the pattern with the most
+ *   literal characters). A model reported as `provider/id` or with a `[…]` suffix (`claude-opus-5-5[1m]`) is matched
+ *   without them as well.
+ *
+ * A price never applies to another source.
+ */
+export interface ModelPrice {
+    readonly id: string;
+    readonly tool: string;
+    readonly modelService: string | null;
+    readonly model: string;
+    readonly inputPerM: number;
+    readonly outputPerM: number;
+    readonly cacheReadPerM: number;
+    readonly cacheWritePerM: number;
+    /** ISO 4217, such as `USD`. */
+    readonly currency: string;
+    readonly note: string | null;
+    readonly updatedAt: string;
+}
+/** A row of `PUT /prices`, which replaces the whole table. */
+export interface ModelPriceInput {
+    readonly tool: string;
+    /** The model service of a chat price; absent or null for a coding tool's. */
+    readonly modelService?: string | null;
+    readonly model: string;
+    readonly inputPerM: number;
+    readonly outputPerM: number;
+    readonly cacheReadPerM?: number;
+    readonly cacheWritePerM?: number;
+    readonly currency?: string;
+    readonly note?: string | null;
+}
+/** What costs are worked out from: the prices, and the coding tools paid by subscription, whose runs cost nothing. */
+export interface PriceBook {
+    readonly prices: readonly ModelPrice[];
+    readonly subscriptions: readonly string[];
+}
+/** A coding tool's model that runs reported, so it can be priced. */
+export interface SeenModel {
+    readonly tool: string;
+    readonly model: string;
+}
+/** `GET /prices` and the answer of `PUT /prices`. */
+export interface PricesAnswer {
+    readonly items: ModelPrice[];
+    /** The coding tools paid by subscription. */
+    readonly subscriptions: string[];
+    /** The models coding tools reported in runs, each once. */
+    readonly seen: SeenModel[];
+}
+/** `PUT agents/prices`: the whole table and the coding tools paid by subscription. */
+export interface PricesInput {
+    readonly prices: readonly ModelPriceInput[];
+    readonly subscriptions: readonly string[];
+}
+/** What a usage record is priced by. */
+export interface PricedSource {
+    readonly tool: string;
+    readonly modelService: string | null;
+    readonly model: string | null;
+}
+/** Whether `price` belongs to the source of `usage` (the tool, and for chat the model service). */
+export declare function sameSource(price: Pick<ModelPrice, 'tool' | 'modelService'>, usage: Pick<PricedSource, 'tool' | 'modelService'>): boolean;
+/**
+ * The names a reported model is matched by: as reported, without a `provider/` prefix (OpenCode reports
+ * `anthropic/claude-sonnet-4-5`), and without a bracketed suffix (Claude Code reports `claude-opus-5-5[1m]`).
+ */
+export declare function modelNames(model: string): string[];
+/**
+ * The price that applies to what `usage` used, or null. Only prices of its source count. An online model matches its id
+ * exactly (case-insensitive); a coding tool's model is matched by the most specific pattern matching any of its names,
+ * and costs nothing when the tool is paid by subscription.
+ */
+export declare function priceFor(book: PriceBook, usage: PricedSource): ModelPrice | null;
+/** How a source and model read in a report: `model (source)`, the source being the model service or the coding tool. */
+export declare function sourceLabel(usage: PricedSource): string;
+/** An amount per currency; a report adds amounts of one currency only. */
+export type Costs = Readonly<Record<string, number>>;
+/** Usage of a group of runs: tokens of every model, the runs' working time, and their cost where a price matched. */
+export interface UsageRow {
+    readonly key: string;
+    /** What a person reads for the key (an agent's or a person's name, a subject's label); null when unknown. */
+    readonly name: string | null;
+    readonly runs: number;
+    /** The runs' time from start to finish, added up. */
+    readonly durationMs: number;
+    readonly inputTokens: number;
+    readonly outputTokens: number;
+    readonly cacheReadTokens: number;
+    readonly cacheWriteTokens: number;
+    /** Of the output tokens, those spent reasoning (already in `outputTokens`). */
+    readonly reasoningTokens: number;
+    /** Null when no model of the group has a price. */
+    readonly cost: Costs | null;
+    /** Runs whose every model had a price. */
+    readonly pricedRuns: number;
+}
+/** What one group (a row's `key`) used on one day. */
+export interface UsageSeriesPoint {
+    readonly key: string;
+    readonly inputTokens: number;
+    readonly outputTokens: number;
+    readonly cacheReadTokens: number;
+    readonly cacheWriteTokens: number;
+    readonly cost: Costs | null;
+}
+/** One day of the usage chart. */
+export interface UsagePoint {
+    readonly day: string;
+    readonly inputTokens: number;
+    readonly outputTokens: number;
+    readonly cacheReadTokens: number;
+    readonly cacheWriteTokens: number;
+    readonly cost: Costs | null;
+    /** The day by `groupBy` key, when the query asked for `series`. */
+    readonly series?: readonly UsageSeriesPoint[];
+}
+/** `reporting.usage`. */
+export interface UsageReport {
+    /** `YYYY-MM-DD`, both inclusive (UTC). */
+    readonly from: string;
+    readonly to: string;
+    readonly groupBy: UsageGroupBy;
+    readonly rows: readonly UsageRow[];
+    readonly totals: UsageRow;
+    readonly daily: readonly UsagePoint[];
+    /** Models that ran without a matching price at their source (`sourceLabel`), so their tokens add no cost. */
+    readonly unpricedModels: readonly string[];
+}
+export interface UsageQuery {
+    readonly from?: string;
+    readonly to?: string;
+    readonly groupBy?: UsageGroupBy;
+    /** Only runs on subjects of this group. */
+    readonly groupId?: string;
+    readonly agentId?: string;
+    readonly userId?: string;
+    /** Also break each day of `daily` down by the `groupBy` key (`UsagePoint.series`). */
+    readonly series?: boolean;
+}
+/**
+ * What the runs started in a range say (`reporting.runFigures`), over the runs the caller counts: how they went, how
+ * fast runners took them, what they cost, and when and for whom they ran. The application adds what its subjects say
+ * to make its own metrics.
+ */
+export interface RunFigures {
+    readonly runs: number;
+    readonly completedRuns: number;
+    readonly failedRuns: number;
+    readonly failuresByReason: Readonly<Record<string, number>>;
+    /** Created → dispatched (time to first claim). */
+    readonly claimLatencyP50Ms: number | null;
+    readonly claimLatencyP95Ms: number | null;
+    /** Started → finished, of runs that completed or failed. */
+    readonly runDurationP50Ms: number | null;
+    /** Held by a runner with nothing reported for three hours. */
+    readonly lostRuns: number;
+    /** Of the usage reported in the range. */
+    readonly inputTokens: number;
+    readonly outputTokens: number;
+    readonly estimatedCost: Costs | null;
+    /** By cost, unpriced last. */
+    readonly costByAgent: readonly {
+        readonly agentId: string;
+        readonly name: string | null;
+        readonly cost: Costs | null;
+    }[];
+    /** The usage reported in the range by the agents' type: `online` and `runner`, each when it has any. */
+    readonly usageByType: readonly {
+        readonly type: 'online' | 'runner';
+        readonly runs: number;
+        readonly inputTokens: number;
+        readonly outputTokens: number;
+        readonly cacheReadTokens: number;
+        readonly cost: Costs | null;
+    }[];
+    /** `YYYY-MM-DD` days a counted run started on. */
+    readonly activityDays: readonly string[];
+    /**
+     * Day by day, oldest first, every day of the range: the counted runs started that day by how they ended so far, and
+     * the cost of the usage reported that day by agent type (null where nothing was priced).
+     */
+    readonly daily: readonly RunDay[];
+    /** The people who woke the counted runs. */
+    readonly actorIds: readonly string[];
+}
+/**
+ * A run as the application's own reports read it (`reporting.runRecords`): what it worked on, how it ended so far and
+ * when each step happened. Only runs the caller counts, on subjects they may see.
+ */
+export interface ReportRun {
+    readonly id: string;
+    readonly agentId: string;
+    readonly subjectKind: string;
+    readonly subjectId: string;
+    /** `queued`, `dispatched`, `running`, `completed`, `failed` or `cancelled`. */
+    readonly status: string;
+    readonly failureReason: string | null;
+    /** The run this one retries, when it is a retry. */
+    readonly retryOfRunId: string | null;
+    /** When it was queued. */
+    readonly createdAt: string;
+    /** When a runner, or the server, claimed it. */
+    readonly dispatchedAt: string | null;
+    readonly startedAt: string | null;
+    readonly finishedAt: string | null;
+}
+/** Which runs `reporting.runRecords` reads: started in a range, on some subjects, or both. */
+export interface ReportRunQuery {
+    /** Queued on or after this time. */
+    readonly start?: Date;
+    /** Queued before this time. */
+    readonly end?: Date;
+    /** Only runs on these subjects of one kind; none when `ids` is empty. */
+    readonly subjects?: {
+        readonly kind: string;
+        readonly ids: readonly string[];
+    };
+    /** Only runs on subjects of this group; null for every group. */
+    readonly groupId: string | null;
+}
+/** One day of `RunFigures.daily`. */
+export interface RunDay {
+    readonly day: string;
+    readonly completed: number;
+    readonly failed: number;
+    readonly cancelled: number;
+    /** Queued, dispatched or running still. */
+    readonly open: number;
+    readonly onlineCost: Costs | null;
+    readonly runnerCost: Costs | null;
+}
+/**
+ * `GET`: `from`, `to` → `{ data: ModelUsageReport }`. Needs the usage page's grant; only a reader of every run
+ * (`agents.agents` read) sees rows, since this use belongs to no one's run.
+ */
+export declare const MODEL_USAGE_ROUTE = "agents/usage/models";
+/** What a model call outside any run was for. */
+export type ModelUsagePurpose = 'embedding' | 'rerank' | 'text';
+export declare const MODEL_USAGE_PURPOSES: readonly ModelUsagePurpose[];
+/** What model calls outside runs used, for one purpose, caller (`source`) and model, with its cost where priced. */
+export interface ModelUsageRow {
+    readonly purpose: ModelUsagePurpose;
+    /** Who asked, as the application names it (such as `knowledge`). */
+    readonly source: string;
+    readonly modelService: string;
+    readonly model: string;
+    readonly calls: number;
+    /** Texts embedded, or documents reranked. */
+    readonly units: number;
+    readonly inputTokens: number;
+    readonly outputTokens: number;
+    /** Null when the model has no price at its service. */
+    readonly cost: Costs | null;
+}
+export interface ModelUsageReport {
+    readonly from: string;
+    readonly to: string;
+    readonly rows: readonly ModelUsageRow[];
+}
+//# sourceMappingURL=reports.d.ts.map

package/dist/shared/reports.d.ts.map

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

package/dist/shared/reports.js

@@ -0,0 +1,135 @@
+/**
+ * What runs used and cost, as the reporting service answers it (`agents.reporting`), and the model prices costs are
+ * estimated from. Costs are never stored: they are worked out from the prices whenever a report is read, so changing
+ * a price changes every report. This plugin serves the prices and the usage report over HTTP (`USAGE_ROUTE`, for its
+ * usage page); the application builds its other reports on the reporting service.
+ */
+/**
+ * `GET`: `from`, `to`, `groupBy`, `groupId`, `agentId`, `userId`, `series` → `{ data: UsageReport }`. Needs the usage
+ * page's grant.
+ */
+export const USAGE_ROUTE = 'agents/usage';
+/**
+ * How the usage report groups runs; `person` is who woke the agent (the run's actor), `group` the group a run's subject
+ * belongs to (`SubjectFacts.group`), `subject` the subject itself, `type` the agent's type (`online` or `runner`; an online
+ * run's `tool` is `online`).
+ */
+export const USAGE_GROUP_BYS = [
+    'agent',
+    'person',
+    'group',
+    'subject',
+    'day',
+    'model',
+    'tool',
+    'type',
+];
+/** A report covers at most this many days; without a range, the last `DEFAULT_REPORT_DAYS`. */
+export const MAX_REPORT_DAYS = 366;
+export const DEFAULT_REPORT_DAYS = 30;
+/** The currency of a price that names none. */
+export const DEFAULT_CURRENCY = 'USD';
+/** The `tool` of an online run's usage: its model calls go through a model service, which is the price's source. */
+export const ONLINE_TOOL = 'online';
+/** Whether `price` belongs to the source of `usage` (the tool, and for chat the model service). */
+export function sameSource(price, usage) {
+    if (price.tool !== usage.tool)
+        return false;
+    return usage.tool === ONLINE_TOOL
+        ? price.modelService !== null && price.modelService === usage.modelService
+        : price.modelService === null;
+}
+function globToRegExp(glob) {
+    const escaped = glob
+        .split('*')
+        .map((part) => part.replace(/[.+?^${}()|[\]\\]/gu, '\\$&'))
+        .join('.*');
+    return new RegExp(`^${escaped}$`, 'iu');
+}
+/** How specific a pattern is: an exact id beats any glob, then the more literal characters the better. */
+function specificity(pattern) {
+    return pattern.includes('*')
+        ? pattern.replaceAll('*', '').length
+        : Number.MAX_SAFE_INTEGER;
+}
+/**
+ * The names a reported model is matched by: as reported, without a `provider/` prefix (OpenCode reports
+ * `anthropic/claude-sonnet-4-5`), and without a bracketed suffix (Claude Code reports `claude-opus-5-5[1m]`).
+ */
+export function modelNames(model) {
+    const names = [model.trim()];
+    const slash = names[0].lastIndexOf('/');
+    if (slash >= 0)
+        names.push(names[0].slice(slash + 1));
+    for (const name of [...names]) {
+        const bare = name.replace(/\[[^\]]*\]$/u, '').trim();
+        if (bare !== name)
+            names.push(bare);
+    }
+    return [...new Set(names.filter(Boolean))];
+}
+/** The price of a coding tool paid by subscription: nothing. */
+function subscriptionPrice(tool) {
+    return {
+        id: `subscription:${tool}`,
+        tool,
+        modelService: null,
+        model: '*',
+        inputPerM: 0,
+        outputPerM: 0,
+        cacheReadPerM: 0,
+        cacheWritePerM: 0,
+        currency: DEFAULT_CURRENCY,
+        note: null,
+        updatedAt: '',
+    };
+}
+/**
+ * The price that applies to what `usage` used, or null. Only prices of its source count. An online model matches its id
+ * exactly (case-insensitive); a coding tool's model is matched by the most specific pattern matching any of its names,
+ * and costs nothing when the tool is paid by subscription.
+ */
+export function priceFor(book, usage) {
+    if (!usage.model)
+        return null;
+    if (usage.tool !== ONLINE_TOOL && book.subscriptions.includes(usage.tool))
+        return subscriptionPrice(usage.tool);
+    const candidates = book.prices.filter((price) => sameSource(price, usage));
+    if (usage.tool === ONLINE_TOOL) {
+        const model = usage.model.trim().toLowerCase();
+        return (candidates.find((price) => price.model.trim().toLowerCase() === model) ??
+            null);
+    }
+    const names = modelNames(usage.model);
+    let best = null;
+    let bestScore = -1;
+    for (const price of candidates) {
+        const pattern = globToRegExp(price.model);
+        if (!names.some((name) => pattern.test(name)))
+            continue;
+        const score = specificity(price.model);
+        if (score > bestScore) {
+            best = price;
+            bestScore = score;
+        }
+    }
+    return best;
+}
+/** How a source and model read in a report: `model (source)`, the source being the model service or the coding tool. */
+export function sourceLabel(usage) {
+    const source = usage.tool === ONLINE_TOOL
+        ? (usage.modelService ?? ONLINE_TOOL)
+        : usage.tool;
+    return `${usage.model ?? ''} (${source})`;
+}
+/**
+ * `GET`: `from`, `to` → `{ data: ModelUsageReport }`. Needs the usage page's grant; only a reader of every run
+ * (`agents.agents` read) sees rows, since this use belongs to no one's run.
+ */
+export const MODEL_USAGE_ROUTE = 'agents/usage/models';
+export const MODEL_USAGE_PURPOSES = [
+    'embedding',
+    'rerank',
+    'text',
+];
+//# sourceMappingURL=reports.js.map

package/dist/shared/reports.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"reports.js","sourceRoot":"","sources":["../../shared/reports.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH;;;GAGG;AACH,MAAM,CAAC,MAAM,WAAW,GAAG,cAAc,CAAC;AAE1C;;;;GAIG;AACH,MAAM,CAAC,MAAM,eAAe,GAAG;IAC7B,OAAO;IACP,QAAQ;IACR,OAAO;IACP,SAAS;IACT,KAAK;IACL,OAAO;IACP,MAAM;IACN,MAAM;CACE,CAAC;AAIX,+FAA+F;AAC/F,MAAM,CAAC,MAAM,eAAe,GAAG,GAAG,CAAC;AACnC,MAAM,CAAC,MAAM,mBAAmB,GAAG,EAAE,CAAC;AAEtC,+CAA+C;AAC/C,MAAM,CAAC,MAAM,gBAAgB,GAAG,KAAK,CAAC;AAEtC,oHAAoH;AACpH,MAAM,CAAC,MAAM,WAAW,GAAG,QAAQ,CAAC;AA6EpC,mGAAmG;AACnG,MAAM,UAAU,UAAU,CACxB,KAAgD,EAChD,KAAkD;IAElD,IAAI,KAAK,CAAC,IAAI,KAAK,KAAK,CAAC,IAAI;QAAE,OAAO,KAAK,CAAC;IAC5C,OAAO,KAAK,CAAC,IAAI,KAAK,WAAW;QAC/B,CAAC,CAAC,KAAK,CAAC,YAAY,KAAK,IAAI,IAAI,KAAK,CAAC,YAAY,KAAK,KAAK,CAAC,YAAY;QAC1E,CAAC,CAAC,KAAK,CAAC,YAAY,KAAK,IAAI,CAAC;AAClC,CAAC;AAED,SAAS,YAAY,CAAC,IAAY;IAChC,MAAM,OAAO,GAAG,IAAI;SACjB,KAAK,CAAC,GAAG,CAAC;SACV,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,OAAO,CAAC,qBAAqB,EAAE,MAAM,CAAC,CAAC;SAC1D,IAAI,CAAC,IAAI,CAAC,CAAC;IACd,OAAO,IAAI,MAAM,CAAC,IAAI,OAAO,GAAG,EAAE,IAAI,CAAC,CAAC;AAC1C,CAAC;AAED,0GAA0G;AAC1G,SAAS,WAAW,CAAC,OAAe;IAClC,OAAO,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAC;QAC1B,CAAC,CAAC,OAAO,CAAC,UAAU,CAAC,GAAG,EAAE,EAAE,CAAC,CAAC,MAAM;QACpC,CAAC,CAAC,MAAM,CAAC,gBAAgB,CAAC;AAC9B,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,UAAU,CAAC,KAAa;IACtC,MAAM,KAAK,GAAG,CAAC,KAAK,CAAC,IAAI,EAAE,CAAC,CAAC;IAC7B,MAAM,KAAK,GAAG,KAAK,CAAC,CAAC,CAAC,CAAC,WAAW,CAAC,GAAG,CAAC,CAAC;IACxC,IAAI,KAAK,IAAI,CAAC;QAAE,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,KAAK,GAAG,CAAC,CAAC,CAAC,CAAC;IACtD,KAAK,MAAM,IAAI,IAAI,CAAC,GAAG,KAAK,CAAC,EAAE,CAAC;QAC9B,MAAM,IAAI,GAAG,IAAI,CAAC,OAAO,CAAC,cAAc,EAAE,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC;QACrD,IAAI,IAAI,KAAK,IAAI;YAAE,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IACtC,CAAC;IACD,OAAO,CAAC,GAAG,IAAI,GAAG,CAAC,KAAK,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC;AAC7C,CAAC;AAED,gEAAgE;AAChE,SAAS,iBAAiB,CAAC,IAAY;IACrC,OAAO;QACL,EAAE,EAAE,gBAAgB,IAAI,EAAE;QAC1B,IAAI;QACJ,YAAY,EAAE,IAAI;QAClB,KAAK,EAAE,GAAG;QACV,SAAS,EAAE,CAAC;QACZ,UAAU,EAAE,CAAC;QACb,aAAa,EAAE,CAAC;QAChB,cAAc,EAAE,CAAC;QACjB,QAAQ,EAAE,gBAAgB;QAC1B,IAAI,EAAE,IAAI;QACV,SAAS,EAAE,EAAE;KACd,CAAC;AACJ,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,QAAQ,CACtB,IAAe,EACf,KAAmB;IAEnB,IAAI,CAAC,KAAK,CAAC,KAAK;QAAE,OAAO,IAAI,CAAC;IAC9B,IAAI,KAAK,CAAC,IAAI,KAAK,WAAW,IAAI,IAAI,CAAC,aAAa,CAAC,QAAQ,CAAC,KAAK,CAAC,IAAI,CAAC;QACvE,OAAO,iBAAiB,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;IACvC,MAAM,UAAU,GAAG,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,UAAU,CAAC,KAAK,EAAE,KAAK,CAAC,CAAC,CAAC;IAC3E,IAAI,KAAK,CAAC,IAAI,KAAK,WAAW,EAAE,CAAC;QAC/B,MAAM,KAAK,GAAG,KAAK,CAAC,KAAK,CAAC,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC;QAC/C,OAAO,CACL,UAAU,CAAC,IAAI,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,KAAK,CAAC,IAAI,EAAE,CAAC,WAAW,EAAE,KAAK,KAAK,CAAC;YACtE,IAAI,CACL,CAAC;IACJ,CAAC;IACD,MAAM,KAAK,GAAG,UAAU,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC;IACtC,IAAI,IAAI,GAAsB,IAAI,CAAC;IACnC,IAAI,SAAS,GAAG,CAAC,CAAC,CAAC;IACnB,KAAK,MAAM,KAAK,IAAI,UAAU,EAAE,CAAC;QAC/B,MAAM,OAAO,GAAG,YAAY,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC;QAC1C,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;YAAE,SAAS;QACxD,MAAM,KAAK,GAAG,WAAW,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC;QACvC,IAAI,KAAK,GAAG,SAAS,EAAE,CAAC;YACtB,IAAI,GAAG,KAAK,CAAC;YACb,SAAS,GAAG,KAAK,CAAC;QACpB,CAAC;IACH,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC;AAED,wHAAwH;AACxH,MAAM,UAAU,WAAW,CAAC,KAAmB;IAC7C,MAAM,MAAM,GACV,KAAK,CAAC,IAAI,KAAK,WAAW;QACxB,CAAC,CAAC,CAAC,KAAK,CAAC,YAAY,IAAI,WAAW,CAAC;QACrC,CAAC,CAAC,KAAK,CAAC,IAAI,CAAC;IACjB,OAAO,GAAG,KAAK,CAAC,KAAK,IAAI,EAAE,KAAK,MAAM,GAAG,CAAC;AAC5C,CAAC;AAwKD;;;GAGG;AACH,MAAM,CAAC,MAAM,iBAAiB,GAAG,qBAAqB,CAAC;AAKvD,MAAM,CAAC,MAAM,oBAAoB,GAAiC;IAChE,WAAW;IACX,QAAQ;IACR,MAAM;CACP,CAAC"}