@nodetool-ai/agents 0.7.0-rc.23 → 0.8.1

package/dist/app-build/author.d.ts

@@ -0,0 +1,67 @@
+/**
+ * The Author stage: a model drives the real `ui_app_*` tool contract until the
+ * document matches the spec.
+ *
+ * There is no second authoring surface here — the tools are the bridge the
+ * `app-tools` eval scores and the browser's own tool contract, and the loop is
+ * the one `runToolLoop` runs for every tool-loop suite. What this module adds
+ * is the *briefing*: the spec rendered as a system prompt with the exact node
+ * ids each binding must name, so the model binds to what the planner actually
+ * built rather than to the names the spec wished for.
+ *
+ * A repair round is not a rebuild. The round resumes from the document the
+ * last one produced (`loadDocument`) and opens with the complaint, so the model
+ * edits what is wrong and leaves the rest alone; the orchestrator's oscillation
+ * guard depends on that being true.
+ */
+import type { BaseProvider, TurnBudget } from "@nodetool-ai/runtime";
+import type { AppIO } from "@nodetool-ai/execution/app-debug";
+import { type AppBridgeDocument } from "./bridge.js";
+import { type ToolLoopRun } from "./tool-loop.js";
+import type { BuildComplaint, BuildSpec, StageRecord } from "./types.js";
+/** Turn cap for one authoring round. */
+export declare const DEFAULT_AUTHOR_TURNS = 40;
+/** The application id the bridge's tools are addressed with. */
+export declare const AUTHORED_APP_ID = "app-under-build";
+/** One operation's workflow, as the author must reference it. */
+export interface AuthorWorkflow {
+    operationId: string;
+    /** Bundle-local key the operation binding must name. */
+    key: string;
+    /** The bindable surface of the graph behind that key. */
+    io: AppIO;
+}
+export interface AuthorStageOptions {
+    spec: BuildSpec;
+    workflows: AuthorWorkflow[];
+    provider: BaseProvider;
+    model: string;
+    /** Repair round this execution belongs to; 0 is the first pass. */
+    round: number;
+    /** The document to resume from. Absent on the first pass. */
+    resumeFrom?: AppBridgeDocument;
+    /** What the last round got wrong. Absent on the first pass. */
+    complaint?: BuildComplaint;
+    maxTurns?: number;
+    turnBudget?: TurnBudget;
+    signal?: AbortSignal;
+    onLog?: (line: string) => void;
+}
+export interface AuthorStageResult {
+    document: AppBridgeDocument;
+    /** The model called `ui_app_finish` rather than running out of turns. */
+    finished: boolean;
+    record: StageRecord;
+    run: ToolLoopRun;
+}
+/**
+ * Run one authoring round. A provider failure or an exhausted turn cap is
+ * reported, not thrown: whatever document exists goes to Check, whose
+ * complaints are that round's result (design §7).
+ */
+export declare function runAuthorStage(opts: AuthorStageOptions): Promise<AuthorStageResult>;
+/** The spec, rendered as the author's briefing. */
+export declare function renderAuthorSystemPrompt(spec: BuildSpec, workflows: AuthorWorkflow[]): string;
+/** A repair round's opening message: everything wrong, and the edit rule. */
+export declare function renderComplaintPrompt(complaint: BuildComplaint): string;
+//# sourceMappingURL=author.d.ts.map

package/dist/app-build/author.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"author.d.ts","sourceRoot":"","sources":["../../src/app-build/author.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,UAAU,EAAE,MAAM,sBAAsB,CAAC;AACrE,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,kCAAkC,CAAC;AAE9D,OAAO,EAEL,KAAK,iBAAiB,EAEvB,MAAM,aAAa,CAAC;AACrB,OAAO,EAGL,KAAK,WAAW,EACjB,MAAM,gBAAgB,CAAC;AACxB,OAAO,KAAK,EACV,cAAc,EAEd,SAAS,EACT,WAAW,EACZ,MAAM,YAAY,CAAC;AAEpB,wCAAwC;AACxC,eAAO,MAAM,oBAAoB,KAAK,CAAC;AAEvC,gEAAgE;AAChE,eAAO,MAAM,eAAe,oBAAoB,CAAC;AAEjD,iEAAiE;AACjE,MAAM,WAAW,cAAc;IAC7B,WAAW,EAAE,MAAM,CAAC;IACpB,wDAAwD;IACxD,GAAG,EAAE,MAAM,CAAC;IACZ,yDAAyD;IACzD,EAAE,EAAE,KAAK,CAAC;CACX;AAED,MAAM,WAAW,kBAAkB;IACjC,IAAI,EAAE,SAAS,CAAC;IAChB,SAAS,EAAE,cAAc,EAAE,CAAC;IAC5B,QAAQ,EAAE,YAAY,CAAC;IACvB,KAAK,EAAE,MAAM,CAAC;IACd,mEAAmE;IACnE,KAAK,EAAE,MAAM,CAAC;IACd,6DAA6D;IAC7D,UAAU,CAAC,EAAE,iBAAiB,CAAC;IAC/B,+DAA+D;IAC/D,SAAS,CAAC,EAAE,cAAc,CAAC;IAC3B,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,UAAU,CAAC,EAAE,UAAU,CAAC;IACxB,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB,KAAK,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;CAChC;AAED,MAAM,WAAW,iBAAiB;IAChC,QAAQ,EAAE,iBAAiB,CAAC;IAC5B,yEAAyE;IACzE,QAAQ,EAAE,OAAO,CAAC;IAClB,MAAM,EAAE,WAAW,CAAC;IACpB,GAAG,EAAE,WAAW,CAAC;CAClB;AAuBD;;;;GAIG;AACH,wBAAsB,cAAc,CAClC,IAAI,EAAE,kBAAkB,GACvB,OAAO,CAAC,iBAAiB,CAAC,CAuE5B;AAqGD,mDAAmD;AACnD,wBAAgB,wBAAwB,CACtC,IAAI,EAAE,SAAS,EACf,SAAS,EAAE,cAAc,EAAE,GAC1B,MAAM,CA2CR;AAED,6EAA6E;AAC7E,wBAAgB,qBAAqB,CAAC,SAAS,EAAE,cAAc,GAAG,MAAM,CAcvE"}

package/dist/app-build/author.js

@@ -0,0 +1,231 @@
+/**
+ * The Author stage: a model drives the real `ui_app_*` tool contract until the
+ * document matches the spec.
+ *
+ * There is no second authoring surface here — the tools are the bridge the
+ * `app-tools` eval scores and the browser's own tool contract, and the loop is
+ * the one `runToolLoop` runs for every tool-loop suite. What this module adds
+ * is the *briefing*: the spec rendered as a system prompt with the exact node
+ * ids each binding must name, so the model binds to what the planner actually
+ * built rather than to the names the spec wished for.
+ *
+ * A repair round is not a rebuild. The round resumes from the document the
+ * last one produced (`loadDocument`) and opens with the complaint, so the model
+ * edits what is wrong and leaves the rest alone; the orchestrator's oscillation
+ * guard depends on that being true.
+ */
+import { createAppToolBridge } from "./bridge.js";
+import { runToolLoop } from "./tool-loop.js";
+/** Turn cap for one authoring round. */
+export const DEFAULT_AUTHOR_TURNS = 40;
+/** The application id the bridge's tools are addressed with. */
+export const AUTHORED_APP_ID = "app-under-build";
+const issue = (code, message, severity = "error") => ({ stage: "author", code, severity, message });
+/** `AppIO` as the bridge's binding-target tool reports it. */
+const bindable = (io) => ({
+    inputs: io.inputs.map((input) => ({
+        nodeId: input.nodeId,
+        name: input.name,
+        label: input.name
+    })),
+    outputs: io.outputs.map((output) => ({
+        nodeId: output.nodeId,
+        name: output.name,
+        label: output.name
+    })),
+    variables: io.variables
+});
+/**
+ * Run one authoring round. A provider failure or an exhausted turn cap is
+ * reported, not thrown: whatever document exists goes to Check, whose
+ * complaints are that round's result (design §7).
+ */
+export async function runAuthorStage(opts) {
+    const startedAt = Date.now();
+    const costBefore = opts.provider.getTotalCost();
+    const host = opts.workflows[0];
+    // Every operation's workflow is loaded, not just the first: an app with two
+    // operations binds against both, and a workflow the bridge does not hold
+    // reports no bindable surface at all.
+    const initial = {
+        title: opts.spec.title,
+        finishTool: true,
+        workflows: Object.fromEntries(opts.workflows.map((workflow) => [workflow.key, bindable(workflow.io)]))
+    };
+    if (host) {
+        initial.workflowId = host.key;
+        initial.workflow = bindable(host.io);
+    }
+    const bridge = createAppToolBridge(initial);
+    if (opts.resumeFrom)
+        bridge.loadDocument(opts.resumeFrom);
+    const loopOptions = {
+        provider: opts.provider,
+        model: opts.model,
+        tools: bridge.tools,
+        systemPrompt: renderAuthorSystemPrompt(opts.spec, opts.workflows),
+        userPrompt: opts.complaint
+            ? renderComplaintPrompt(opts.complaint)
+            : "Build the app the specification describes, then call ui_app_finish.",
+        maxIterations: opts.maxTurns ?? DEFAULT_AUTHOR_TURNS,
+        stopOn: (call) => call.name === "ui_app_finish" && !call.isError
+    };
+    if (opts.turnBudget)
+        loopOptions.turnBudget = opts.turnBudget;
+    if (opts.signal)
+        loopOptions.signal = opts.signal;
+    const onLog = opts.onLog;
+    if (onLog) {
+        loopOptions.onToolCall = (call) => onLog(`  ${call.name}${call.isError ? " (error)" : ""}`);
+    }
+    const run = await runToolLoop(loopOptions);
+    const finished = bridge.finalState().finished;
+    const issues = [];
+    if (run.error !== undefined) {
+        issues.push(issue("author_provider_error", run.error));
+    }
+    else if (!finished) {
+        issues.push(issue("author_unfinished", `the model stopped after ${run.totalCalls} tool call(s) without calling ui_app_finish; checking the document it left`, "warning"));
+    }
+    return {
+        document: bridge.document(),
+        finished,
+        run,
+        record: {
+            stage: "author",
+            round: opts.round,
+            status: run.error === undefined ? "ok" : "failed",
+            startedAt: new Date(startedAt).toISOString(),
+            durationMs: Date.now() - startedAt,
+            issues,
+            costUsd: opts.provider.getTotalCost() - costBefore,
+            detail: `${run.totalCalls} tool call(s)${finished ? ", finished" : ""}`
+        }
+    };
+}
+// ---------------------------------------------------------------------------
+// Prompts
+// ---------------------------------------------------------------------------
+const bullet = (lines) => lines.length > 0 ? lines.join("\n") : "  (none)";
+function renderOperations(spec, workflows) {
+    return workflows
+        .map((workflow) => {
+        const operation = spec.operations.find((op) => op.id === workflow.operationId);
+        const inputs = workflow.io.inputs.map((input) => `  - input "${input.name}" → node id \`${input.nodeId}\``);
+        const outputs = workflow.io.outputs.map((output) => `  - output "${output.name}" → node id \`${output.nodeId}\``);
+        return [
+            `- operation \`${workflow.operationId}\` runs workflow \`${workflow.key}\``,
+            `  (ui_app_add_operation: id "${workflow.operationId}", target_workflow_id "${workflow.key}"${operation?.streaming ? ', policy "replace"' : ""})`,
+            bullet(inputs),
+            bullet(outputs)
+        ].join("\n");
+    })
+        .join("\n");
+}
+function renderWidgets(spec, workflows) {
+    const nodeIdFor = (operationId, kind, name) => {
+        const workflow = workflows.find((w) => w.operationId === operationId);
+        const list = kind === "in" ? workflow?.io.inputs : workflow?.io.outputs;
+        return list?.find((entry) => entry.name === name)?.nodeId ?? name;
+    };
+    const rewrite = (binding) => {
+        const match = /^op:([^/]+)\/(in|out):(.+)$/.exec(binding);
+        if (!match)
+            return binding;
+        const [, operationId, kind, name] = match;
+        return `op:${operationId}/${kind}:${nodeIdFor(operationId, kind, name)}`;
+    };
+    return spec.widgets
+        .map((widget) => {
+        const parts = [
+            `- ${widget.role}: type \`${widget.type}\`, label "${widget.label}"`
+        ];
+        if (widget.binding !== "") {
+            parts.push(`, binding \`${rewrite(widget.binding)}\``);
+        }
+        if (widget.container)
+            parts.push(`, inside \`${widget.container}\``);
+        if (widget.visibleWhen) {
+            parts.push(`, visibleWhen \`${widget.visibleWhen}\``);
+        }
+        return parts.join("");
+    })
+        .join("\n");
+}
+function renderVariables(spec) {
+    return bullet(spec.variables.map((variable) => `- \`${variable.id}\`: scope ${variable.scope === "app" ? "user" : "instance"}, persist ${variable.persist}, written by operation \`${variable.writtenBy}\``));
+}
+function renderInteractions(spec) {
+    return bullet(spec.interactions.map((interaction) => `- ${interaction.name}: ${interaction.steps
+        .map((step) => "click" in step
+        ? `click ${step.click}`
+        : "change" in step
+            ? `change ${step.change}`
+            : "run" in step
+                ? `run ${step.run}`
+                : "cancel" in step
+                    ? `cancel ${step.cancel}`
+                    : "set" in step
+                        ? `set ${step.set.key}`
+                        : `seedResource ${step.seedResource.id}`)
+        .join(" → ")}`));
+}
+/** The spec, rendered as the author's briefing. */
+export function renderAuthorSystemPrompt(spec, workflows) {
+    return `You are building a NodeTool mini app with the ui_app_* tools. The
+application id is "${AUTHORED_APP_ID}" — pass it to every tool.
+
+The workflows already exist. Your job is the app: bind each workflow as an
+operation, place the widgets, bind them, and wire the events that run the
+operations. Do not invent operations, widgets, or bindings the specification
+below does not ask for, and do not rename anything.
+
+# App
+Title: ${spec.title}
+
+# Operations to declare
+${renderOperations(spec, workflows)}
+
+Bindings address nodes by **node id**, not by name — the ids above are the only
+correct ones. An input with no mapping takes its bound widget's value and an
+output with no mapping displays, so pass \`inputs\`/\`outputs\` only where the
+specification asks for a variable mapping.
+
+# Variables to declare
+${renderVariables(spec)}
+
+An operation output that writes a variable is mapped on the operation
+(\`outputs: { "<output node id>": { "to": "variable", "variableId": "<id>" } }\`).
+
+# Widgets to place
+${renderWidgets(spec, workflows)}
+
+Every widget's label must be exactly the label above — the checker finds
+widgets by label. A widget listed with a container goes inside that container
+widget's slot (\`parent_id\`, plus \`slot\`: 'content' for Panel and Accordion,
+'left'/'right' for Columns, 'tab1'..'tab3' for Tabs).
+
+At least one widget must run an operation. A Button runs one through its
+\`events\` prop:
+\`events: [{ "trigger": "click", "kind": "run", "operationId": "<operation id>" }]\`.
+
+# Interactions the app must support
+${renderInteractions(spec)}
+
+Call \`ui_app_get_snapshot\` when you need to see what is placed, and
+\`ui_app_finish\` with a one-line summary when everything above exists.`;
+}
+/** A repair round's opening message: everything wrong, and the edit rule. */
+export function renderComplaintPrompt(complaint) {
+    const lines = complaint.issues.map((i) => `- [${i.stage}/${i.code}]${i.widget ? ` widget "${i.widget}":` : i.operation ? ` operation "${i.operation}":` : ""} ${i.message}`);
+    return `The app you built has problems. This is the full list — nothing else
+is wrong, and everything here must be fixed:
+
+${lines.join("\n")}
+
+The document you built is loaded. Edit it: call ui_app_get_snapshot to see the
+current widgets, then fix exactly what is listed above with
+ui_app_update_component / ui_app_update_operation / ui_app_add_component. Do
+not delete and rebuild what already works. Call ui_app_finish when done.`;
+}
+//# sourceMappingURL=author.js.map

package/dist/app-build/author.js.map

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

package/dist/app-build/bridge.d.ts

@@ -0,0 +1,130 @@
+/**
+ * Headless bridge for the App Builder (Puck) `ui_app_*` tool surface.
+ *
+ * Two callers share it: the `app-tools` eval suite
+ * (`../evals/surfaces/app.ts`, which re-exports this module) and the app-build
+ * Author stage, which drives the same tools with a real model to produce a
+ * mini app. They cannot drift, because there is one implementation.
+ *
+ * The real frontend tools (`web/src/lib/tools/builtin/puck.ts`) delegate to a
+ * `PuckAgentHandler` the live editor registers on `puckAgentBridge` — it drives
+ * the Puck editor through usePuck's dispatch, so it can only run in the browser.
+ * This bridge reimplements the *effects* of the layout tools against a plain
+ * in-memory document tree (the same shape `puckDataOps.ts` walks: a top-level
+ * `content` array plus slot-valued props on layout widgets), so a model can
+ * drive the same `ui_app_*` tool surface headlessly.
+ *
+ * The document-meta tools (operations, variables, resources, binding targets)
+ * are not reimplemented at all: they call the same `@nodetool-ai/app-runtime`
+ * doc-ops the browser handler calls, so the two surfaces cannot drift.
+ *
+ * What it does NOT fork is the tool *contract*: names, descriptions, and Zod
+ * parameter shapes are copied verbatim from the builtin file — the single
+ * source of truth the browser tools also expose. Nor does it fork the widget
+ * catalog: types, labels, fields, and slots come from `WIDGET_CATALOG`, the
+ * same table the Puck config is checked against, so a model driving this bridge
+ * sees every widget the editor offers.
+ *
+ * Two tools exist here that the browser has no counterpart for, both opt-in so
+ * the eval surface stays exactly the frontend contract: `ui_app_finish`, which
+ * lets an authoring model end its turn deliberately instead of trailing off,
+ * and the `loadDocument`/`document` pair, which lets a repair round resume from
+ * the document the previous round produced instead of an empty one.
+ */
+import { type AppDocMeta, type BindableWorkflow, type OperationBinding, type ResourceBinding, type VariableDeclaration } from "@nodetool-ai/app-runtime";
+import type { HeadlessTool } from "../evals/tool-loop-bridge.js";
+/** A placed widget: type plus props (props always carry an `id`). */
+export interface ComponentNode {
+    type: string;
+    props: Record<string, unknown> & {
+        id: string;
+    };
+}
+/**
+ * The whole document the bridge holds — the Puck-shaped widget tree plus the
+ * non-UI half. This is what round-trips through `document()` / `loadDocument`,
+ * and what an `ApplicationBundle` is assembled from.
+ */
+export interface AppBridgeDocument {
+    title: string | null;
+    content: ComponentNode[];
+    meta: AppDocMeta;
+}
+/** Flattened view of one placed widget, matching the real `ComponentSummary`. */
+export interface AppComponentSummary {
+    id: string;
+    type: string;
+    props: Record<string, unknown>;
+    parentId: string | null;
+    slot: string | null;
+}
+export interface AppBridgeFinalState {
+    title: string | null;
+    selectedId: string | null;
+    components: AppComponentSummary[];
+    /** The non-UI half of the document, so a case can score bindings. */
+    operations: OperationBinding[];
+    variables: VariableDeclaration[];
+    resources: ResourceBinding[];
+    /** The model called `ui_app_finish` (only reachable with `finishTool`). */
+    finished: boolean;
+    /** The summary it passed to `ui_app_finish`, when it called it. */
+    finishSummary: string | null;
+}
+/** A widget to seed, optionally nesting children into its slots. */
+export interface SeedComponent {
+    type: string;
+    id?: string;
+    props?: Record<string, unknown>;
+    /** Children keyed by slot field name (e.g. `content`, `left`, `right`). */
+    slots?: Record<string, SeedComponent[]>;
+}
+export interface AppBridgeInitialState {
+    title?: string;
+    components?: SeedComponent[];
+    /** Operations, variables, and resources the document starts with. */
+    meta?: AppDocMeta;
+    /**
+     * Id of the host workflow this editor has loaded — NOT the app's identity.
+     * An operation pointing at it resolves against {@link workflow}; every other
+     * operation resolves against {@link workflows}.
+     */
+    workflowId?: string;
+    /** Bindable surface of that host workflow: its input/output nodes and channels. */
+    workflow?: BindableWorkflow;
+    /**
+     * Every other workflow this editor has loaded, keyed by workflow id. An app
+     * with one operation per workflow binds against all of them, so reporting
+     * node targets for the host alone would leave every further operation with
+     * no bindable surface.
+     */
+    workflows?: Readonly<Record<string, BindableWorkflow>>;
+    /**
+     * Offer `ui_app_finish` so the model can end the loop deliberately. Off by
+     * default: the eval surface exposes the frontend contract and nothing else.
+     */
+    finishTool?: boolean;
+}
+/**
+ * The bridge: the tool set, a final-state snapshot for structural predicates,
+ * and the document round-trip the repair loop resumes through.
+ */
+export interface AppToolBridge {
+    tools: HeadlessTool[];
+    finalState: () => AppBridgeFinalState;
+    /** The full document, for assembly into an `ApplicationBundle`. */
+    document: () => AppBridgeDocument;
+    /** Replace the document, e.g. to resume a repair round where the last ended. */
+    loadDocument: (doc: AppBridgeDocument) => void;
+}
+/**
+ * Build an in-memory App Builder bridge whose tools share the `ui_app_*`
+ * contract but run headlessly against a plain document tree (no Puck editor).
+ *
+ * A single app is modeled: every tool takes an `application_id` (mirroring the
+ * real tools), which is accepted but not used to disambiguate — the bridge
+ * holds one document. Passing an unknown id is not an error, matching how a
+ * scored run only cares about the resulting document.
+ */
+export declare function createAppToolBridge(initial?: AppBridgeInitialState): AppToolBridge;
+//# sourceMappingURL=bridge.d.ts.map

package/dist/app-build/bridge.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bridge.d.ts","sourceRoot":"","sources":["../../src/app-build/bridge.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AAIH,OAAO,EAcL,KAAK,UAAU,EACf,KAAK,gBAAgB,EAGrB,KAAK,gBAAgB,EAIrB,KAAK,eAAe,EAGpB,KAAK,mBAAmB,EAEzB,MAAM,0BAA0B,CAAC;AAClC,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,8BAA8B,CAAC;AAUjE,qEAAqE;AACrE,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG;QAAE,EAAE,EAAE,MAAM,CAAA;KAAE,CAAC;CACjD;AAED;;;;GAIG;AACH,MAAM,WAAW,iBAAiB;IAChC,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IACrB,OAAO,EAAE,aAAa,EAAE,CAAC;IACzB,IAAI,EAAE,UAAU,CAAC;CAClB;AAED,iFAAiF;AACjF,MAAM,WAAW,mBAAmB;IAClC,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC/B,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;CACrB;AAED,MAAM,WAAW,mBAAmB;IAClC,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IACrB,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,UAAU,EAAE,mBAAmB,EAAE,CAAC;IAClC,qEAAqE;IACrE,UAAU,EAAE,gBAAgB,EAAE,CAAC;IAC/B,SAAS,EAAE,mBAAmB,EAAE,CAAC;IACjC,SAAS,EAAE,eAAe,EAAE,CAAC;IAC7B,2EAA2E;IAC3E,QAAQ,EAAE,OAAO,CAAC;IAClB,mEAAmE;IACnE,aAAa,EAAE,MAAM,GAAG,IAAI,CAAC;CAC9B;AAED,oEAAoE;AACpE,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,MAAM,CAAC;IACb,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAChC,2EAA2E;IAC3E,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,aAAa,EAAE,CAAC,CAAC;CACzC;AAED,MAAM,WAAW,qBAAqB;IACpC,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,UAAU,CAAC,EAAE,aAAa,EAAE,CAAC;IAC7B,qEAAqE;IACrE,IAAI,CAAC,EAAE,UAAU,CAAC;IAClB;;;;OAIG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,mFAAmF;IACnF,QAAQ,CAAC,EAAE,gBAAgB,CAAC;IAC5B;;;;;OAKG;IACH,SAAS,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,gBAAgB,CAAC,CAAC,CAAC;IACvD;;;OAGG;IACH,UAAU,CAAC,EAAE,OAAO,CAAC;CACtB;AAED;;;GAGG;AACH,MAAM,WAAW,aAAa;IAC5B,KAAK,EAAE,YAAY,EAAE,CAAC;IACtB,UAAU,EAAE,MAAM,mBAAmB,CAAC;IACtC,mEAAmE;IACnE,QAAQ,EAAE,MAAM,iBAAiB,CAAC;IAClC,gFAAgF;IAChF,YAAY,EAAE,CAAC,GAAG,EAAE,iBAAiB,KAAK,IAAI,CAAC;CAChD;AAmID;;;;;;;;GAQG;AACH,wBAAgB,mBAAmB,CACjC,OAAO,GAAE,qBAA0B,GAClC,aAAa,CAipBf"}