@nodetool-ai/execution 0.8.1

package/dist/service/app-debug-service.js

@@ -0,0 +1,201 @@
+/**
+ * `nodetool app debug` as a service — the engine behind
+ * `POST /api/applications/debug` and the `debug_app` agent tool.
+ *
+ * The simulation itself is `simulateApp`, unchanged: this module supplies the
+ * three things it cannot get for itself — the target (an application row, or
+ * the document the caller posted inline), the workflow loader its operations
+ * resolve against, and a kernel runner for the runs.
+ *
+ * The inline `document` path is the one that matters for an editor assistant.
+ * A draft lives in the browser until the user saves, so anything keyed on
+ * `application_id` grades a stale row — a verdict that lies exactly when the
+ * assistant is mid-edit.
+ *
+ * A run with `run: true` executes real workflows, so it can take minutes:
+ * `poll: true` fronts it with the same session registry a build uses. A
+ * simulation parks no escalations, so its session only ever reports `running`
+ * or `done`.
+ */
+import { randomUUID } from "node:crypto";
+import { createLogger } from "@nodetool-ai/config";
+import { Application, Workflow, createJsScriptResolver } from "@nodetool-ai/models";
+import { applicationTarget, inlineDocumentTarget, simulateApp, summarizeAppReport } from "../app-debug/index.js";
+import { createAppServerRunner } from "./app-run-server.js";
+import { debugSessions, InteractiveEscalationHandle } from "./debug-sessions.js";
+import { isNonEmptyString, isPositiveFiniteNumber } from "../predicates.js";
+const log = createLogger("nodetool.execution.app-debug");
+/**
+ * A refusal the caller turns into its own transport error. `code` is the
+ * vocabulary the HTTP layer maps onto `ApiErrorCode`; nothing here knows about
+ * Fastify or tRPC.
+ */
+export class AppServiceError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.code = code;
+        this.name = "AppServiceError";
+    }
+}
+/** A pinned script version the user owns, for a script operation. */
+async function loadUserJsScript(userId, scriptId, scriptVersion) {
+    const resolved = await createJsScriptResolver().resolve({ id: scriptId, version: scriptVersion }, userId);
+    return resolved ? { name: resolved.name, document: resolved.document } : null;
+}
+/** A workflow the user can read, in the shape the simulator wants. */
+async function loadUserWorkflow(userId, id) {
+    const workflow = await Workflow.find(userId, id);
+    const graph = workflow?.getGraph();
+    return graph ? { graph } : null;
+}
+/** An application the user owns, with its document still unparsed. */
+async function loadUserApplication(userId, id) {
+    const application = await Application.findById(id);
+    if (!application || application.user_id !== userId)
+        return null;
+    return {
+        id: application.id,
+        name: application.name,
+        document: application.document
+    };
+}
+/** A body number that is a finite positive value, or undefined. */
+function positive(value) {
+    return isPositiveFiniteNumber(value) ? value : undefined;
+}
+/** The simulation's payload while it is still running. */
+function runningPayload(session, debugId) {
+    return {
+        status: "running",
+        session_id: session.id,
+        debug_id: debugId,
+        poll: `GET /api/debug/sessions/${session.id}`,
+        cancel: `POST /api/debug/sessions/${session.id}/cancel`
+    };
+}
+/**
+ * The compacted report as the HTTP surface and the tool see it. The session
+ * fronts an untyped JSON payload, so the summary's own fields are spread
+ * through `Object.entries` rather than asserted into a dictionary.
+ */
+function debugPayload(report, debugId) {
+    return {
+        debug_id: debugId,
+        status: report.verdict.ok ? "completed" : "failed",
+        ...Object.fromEntries(Object.entries(summarizeAppReport(report)))
+    };
+}
+/**
+ * Resolve the request's target: an application row, or the document it carries.
+ * Exactly one of the two, so a caller never has to wonder which one was graded.
+ */
+async function resolveTarget(userId, body, deps) {
+    const hasId = isNonEmptyString(body.application_id);
+    const hasDocument = body.document !== undefined && body.document !== null;
+    if (hasId && hasDocument) {
+        throw new AppServiceError("invalid_input", "Pass either application_id or document, not both — a saved row and a " +
+            "live draft are different apps the moment the draft changes.");
+    }
+    const loadFromDb = (id) => (deps.loadWorkflow ?? loadUserWorkflow)(userId, id);
+    if (hasId) {
+        const id = body.application_id;
+        const application = await (deps.loadApplication ?? loadUserApplication)(userId, id);
+        if (!application) {
+            throw new AppServiceError("not_found", `No application found: ${id}`);
+        }
+        return applicationTarget(id, application, loadFromDb);
+    }
+    if (hasDocument) {
+        return inlineDocumentTarget(body.document, loadFromDb);
+    }
+    throw new AppServiceError("invalid_input", "An app debug run needs either an application_id or a document.");
+}
+/**
+ * Debug an app. Resolves with the compacted report (plus the session id), or —
+ * with `poll: true` — with the session id as soon as the run is under way.
+ */
+export async function runApplicationDebug(userId, body, defaultRegistry, deps = {}) {
+    const debugId = `app-debug-${randomUUID()}`;
+    const resolved = await resolveTarget(userId, body, deps);
+    const registry = deps.registry ?? defaultRegistry;
+    const timeoutMs = positive(body.timeout_ms);
+    // Cancelling a simulation settles its session with a failed report; the runs
+    // already in flight finish in the background, since `simulateApp` takes no
+    // signal. Nothing they touch is persisted, so a finished orphan run is spend,
+    // not state.
+    let cancelled = null;
+    const abandoned = new Promise((resolve) => {
+        cancelled = resolve;
+    });
+    // The promise a session fronts must never reject: a rejected run would leave
+    // the session parked forever with no report to hand back.
+    const simulation = (async () => {
+        try {
+            const simulateOptions = {};
+            if (body.params) {
+                simulateOptions.params = body.params;
+            }
+            if (body.interact) {
+                simulateOptions.interact = body.interact;
+            }
+            if (body.run !== undefined) {
+                simulateOptions.run = body.run;
+            }
+            if (timeoutMs !== undefined) {
+                simulateOptions.timeoutMs = timeoutMs;
+            }
+            const simulateDeps = {
+                loadFromDb: (id) => (deps.loadWorkflow ?? loadUserWorkflow)(userId, id),
+                runOnServer: createAppServerRunner(userId, registry, {
+                    jobPrefix: "app-debug-run",
+                    assetStorage: deps.assetStorage ?? null
+                }),
+                loadScript: (scriptId, scriptVersion) => loadUserJsScript(userId, scriptId, scriptVersion)
+            };
+            if (deps.runScript) {
+                simulateDeps.runScript = deps.runScript;
+            }
+            const report = await simulateApp(resolved, simulateOptions, simulateDeps);
+            return debugPayload(report, debugId);
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            log.error("app debug failed outside the report", { debugId, message });
+            return {
+                debug_id: debugId,
+                status: "failed",
+                error: message,
+                verdict: {
+                    ok: false,
+                    headline: message,
+                    issues: [message],
+                    warnings: []
+                }
+            };
+        }
+    })();
+    const done = Promise.race([simulation, abandoned]);
+    const session = debugSessions.create({
+        userId,
+        workflowId: resolved.info.workflowId,
+        jobId: debugId,
+        handle: new InteractiveEscalationHandle(),
+        done,
+        cancel: () => cancelled?.({
+            debug_id: debugId,
+            status: "failed",
+            error: "cancelled",
+            verdict: {
+                ok: false,
+                headline: "App debug cancelled before it finished.",
+                issues: ["cancelled"],
+                warnings: []
+            }
+        })
+    });
+    if (body.poll === true)
+        return runningPayload(session, debugId);
+    return { ...(await done), session_id: session.id };
+}
+//# sourceMappingURL=app-debug-service.js.map

package/dist/service/app-debug-service.js.map

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

package/dist/service/app-run-server.d.ts

@@ -0,0 +1,28 @@
+/**
+ * The kernel runner every server-side app simulation uses.
+ *
+ * `simulateApp` has exactly one contract with a kernel:
+ * `AppServerRunInput → AppServerRunOutcome`. This builds that closure — one
+ * `ExecutionSession` per run, over the graph the caller holds in memory,
+ * persisting nothing. A build's workflows have no rows until its bundle is
+ * imported, and a debugged draft may have none at all, so neither surface can
+ * run through the job machinery.
+ *
+ * Shared by the app build service (the Run stage) and the app debug service
+ * (`POST /api/applications/debug`), so a run means the same thing to both.
+ */
+import type { AppServerRunInput, AppServerRunOutcome } from "../app-debug/index.js";
+import type { NodeRegistry } from "@nodetool-ai/node-sdk";
+import { type StorageAdapter } from "@nodetool-ai/runtime";
+export interface AppServerRunnerOptions {
+    /** Job-id prefix, so a run is attributable to the surface that started it. */
+    jobPrefix?: string;
+    /**
+     * The store `asset://<id>` inputs resolve through. Only the local assets dir
+     * on a `file` backend, so a host on S3/Supabase must pass its own or the
+     * run reads every uploaded input as empty.
+     */
+    assetStorage?: StorageAdapter | null;
+}
+export declare function createAppServerRunner(userId: string, registry: NodeRegistry, options?: AppServerRunnerOptions): (input: AppServerRunInput) => Promise<AppServerRunOutcome>;
+//# sourceMappingURL=app-run-server.d.ts.map

package/dist/service/app-run-server.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"app-run-server.d.ts","sourceRoot":"","sources":["../../src/service/app-run-server.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAQH,OAAO,KAAK,EACV,iBAAiB,EACjB,mBAAmB,EACpB,MAAM,uBAAuB,CAAC;AAE/B,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,uBAAuB,CAAC;AAC1D,OAAO,EAAqB,KAAK,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAG9E,MAAM,WAAW,sBAAsB;IACrC,8EAA8E;IAC9E,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;;;;OAIG;IACH,YAAY,CAAC,EAAE,cAAc,GAAG,IAAI,CAAC;CACtC;AAED,wBAAgB,qBAAqB,CACnC,MAAM,EAAE,MAAM,EACd,QAAQ,EAAE,YAAY,EACtB,OAAO,GAAE,sBAA2B,GACnC,CAAC,KAAK,EAAE,iBAAiB,KAAK,OAAO,CAAC,mBAAmB,CAAC,CA8E5D"}

package/dist/service/app-run-server.js

@@ -0,0 +1,104 @@
+/**
+ * The kernel runner every server-side app simulation uses.
+ *
+ * `simulateApp` has exactly one contract with a kernel:
+ * `AppServerRunInput → AppServerRunOutcome`. This builds that closure — one
+ * `ExecutionSession` per run, over the graph the caller holds in memory,
+ * persisting nothing. A build's workflows have no rows until its bundle is
+ * imported, and a debugged draft may have none at all, so neither surface can
+ * run through the job machinery.
+ *
+ * Shared by the app build service (the Run stage) and the app debug service
+ * (`POST /api/applications/debug`), so a run means the same thing to both.
+ */
+import { randomUUID } from "node:crypto";
+import { getDefaultAssetsPath } from "@nodetool-ai/config";
+import { ExecutionSession } from "../session.js";
+import { createFalGenerationLifecycleHooks } from "../generation-lifecycle.js";
+import { isExecutionPreflightError } from "../preflight.js";
+import { collectExecutionSummary } from "../debug/collector.js";
+import { getSecret } from "@nodetool-ai/models";
+import { ProcessingContext } from "@nodetool-ai/runtime";
+import { FileStorageAdapter } from "@nodetool-ai/storage";
+export function createAppServerRunner(userId, registry, options = {}) {
+    const jobPrefix = options.jobPrefix ?? "app-run";
+    return async (input) => {
+        const startedAt = Date.now();
+        const jobId = `${jobPrefix}-${randomUUID()}`;
+        const context = new ProcessingContext({
+            jobId,
+            workflowId: input.workflowId,
+            userId,
+            secretResolver: (key) => getSecret(key, userId),
+            storage: new FileStorageAdapter(getDefaultAssetsPath()),
+            assetStorage: options.assetStorage ?? null,
+            generationLifecycle: createFalGenerationLifecycleHooks({
+                userId,
+                jobId,
+                projectId: null,
+                publicUrl: process.env["NODETOOL_PUBLIC_URL"] ?? null
+            })
+        });
+        const sessionOptions = {
+            graph: input.graph,
+            registry,
+            jobId,
+            workflowId: input.workflowId,
+            params: input.params,
+            context
+        };
+        if (input.timeoutMs !== undefined) {
+            sessionOptions.limits = { runTimeoutMs: input.timeoutMs };
+        }
+        // A graph this runtime cannot honour is refused before the kernel starts.
+        // The simulator's contract is a report, so a refusal becomes a failed run
+        // it can complain about — not a throw out of the simulation.
+        let session;
+        try {
+            session = await ExecutionSession.create(sessionOptions);
+        }
+        catch (err) {
+            if (!isExecutionPreflightError(err))
+                throw err;
+            const summary = collectExecutionSummary([]);
+            summary.status = "failed";
+            summary.error = err.message;
+            return {
+                report: {
+                    surface: "server",
+                    ok: false,
+                    status: "failed",
+                    error: err.message,
+                    durationMs: Date.now() - startedAt,
+                    summary,
+                    trace: null
+                },
+                rawMessages: []
+            };
+        }
+        // `session.result` never rejects: a kernel failure resolves as
+        // `status: "failed"`, which the simulator turns into a complaint.
+        const result = await session.result;
+        const messages = result.messages ?? [];
+        const summary = collectExecutionSummary(messages);
+        summary.status = result.status ?? summary.status;
+        const timedOut = session.cancelReason === "timeout";
+        const error = result.error ??
+            (timedOut ? `run exceeded timeout (${input.timeoutMs}ms)` : undefined);
+        if (error && !summary.error)
+            summary.error = error;
+        return {
+            report: {
+                surface: "server",
+                ok: result.status === "completed",
+                status: result.status ?? summary.status,
+                error: error ?? summary.error ?? null,
+                durationMs: Date.now() - startedAt,
+                summary,
+                trace: null
+            },
+            rawMessages: messages
+        };
+    };
+}
+//# sourceMappingURL=app-run-server.js.map

package/dist/service/app-run-server.js.map

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

package/dist/service/debug-sessions.d.ts

@@ -0,0 +1,158 @@
+/**
+ * Interactive escalation sessions for the agent-facing run/debug endpoints.
+ *
+ * The supervisor design (docs/workflow-supervisor-design.md) puts an LLM agent
+ * on a run's failure path. This module puts the *calling* agent there instead:
+ * `InteractiveEscalationHandle` is a `SupervisorHandle` whose `decide()` parks
+ * the escalation until a verdict arrives over HTTP, so the tool that started
+ * the run gets the problem back as its result and answers with one of the
+ * same verdicts the supervisor vocabulary defines. The kernel's guarantees are
+ * untouched — the handle is wrapped in `BoundedHandle` (decision/retry caps,
+ * timeout, sticky verdicts) and the actor still enforces `allowedActions`.
+ *
+ * A session is one run: the parked escalations, the run's completion promise,
+ * and the final report. Sessions are owned by the user who started the run and
+ * are swept a few minutes after the run settles.
+ *
+ * Long-running work that is not a workflow run uses the same registry for its
+ * polling and cancel — `POST /api/applications/build` fronts a build this way,
+ * with a null `workflowId` and a handle nothing ever escalates to.
+ */
+import type { DecisionOutcome, SupervisorHandle } from "@nodetool-ai/kernel";
+import type { Escalation, Verdict } from "@nodetool-ai/protocol";
+/** How long an agent gets to answer one escalation before it fails closed. */
+export declare const INTERACTIVE_DECISION_TIMEOUT_MS: number;
+/**
+ * Hard ceiling on a session's life. The TTL sweep only arms once a run
+ * settles, so a run whose `done` never resolves — a wedged bridge, a promise
+ * nobody rejects — used to hold its session (and the run behind it) forever.
+ */
+export declare const SESSION_MAX_LIFETIME_MS: number;
+/** How long `cancel()` waits for the run to settle before answering anyway. */
+export declare const CANCEL_SETTLE_TIMEOUT_MS = 30000;
+/** Live (unsettled) sessions one user may hold at once. */
+export declare const MAX_LIVE_SESSIONS_PER_USER = 8;
+/** What escalation subscribers see: the record, never the settle handle. */
+export interface ParkedEscalation {
+    id: string;
+    escalation: Escalation;
+}
+/**
+ * A `SupervisorHandle` that answers nothing itself: each `decide()` parks the
+ * escalation until `submit()` delivers a verdict (or the decision signal
+ * aborts, which fails closed). `BoundedHandle` serializes decisions, so at
+ * most one escalation is pending at a time.
+ */
+export declare class InteractiveEscalationHandle implements SupervisorHandle {
+    private _pending;
+    private _waiters;
+    private _counter;
+    private _closed;
+    decide(e: Escalation, signal: AbortSignal): Promise<DecisionOutcome>;
+    /** The escalation currently awaiting a verdict, if any. */
+    current(): {
+        id: string;
+        escalation: Escalation;
+    } | null;
+    /**
+     * Subscribe to the next parked escalation. Returns an unsubscribe so a
+     * caller racing this against run completion can withdraw when the run wins
+     * — otherwise every verdict round trip would strand one waiter until the
+     * session is swept.
+     */
+    subscribe(waiter: (entry: ParkedEscalation) => void): () => void;
+    /**
+     * Deliver the agent's verdict for the parked escalation. Returns an error
+     * string instead of throwing so the HTTP layer can 400 with it; the verdict
+     * is checked against the escalation's `allowedActions` here so the agent can
+     * correct itself, and enforced again by the kernel regardless.
+     *
+     * A `substitute` payload is validated here too, against the same rules the
+     * actor applies. Accepting it and letting the kernel reject it fails the
+     * node with its *original* error and burns the decision — the agent never
+     * learns its repair was malformed. Rejecting here keeps the escalation
+     * parked, so it can answer again.
+     */
+    submit(escalationId: string, verdict: Verdict): Promise<{
+        error: string;
+    } | null>;
+    close(): void;
+}
+export type DebugSessionEvent = {
+    kind: "escalated";
+    escalationId: string;
+    escalation: Escalation;
+} | {
+    kind: "done";
+    report: Record<string, unknown>;
+} | {
+    kind: "running";
+};
+export interface CreateDebugSessionOptions {
+    userId: string;
+    /** Null when the session fronts something other than a workflow run. */
+    workflowId: string | null;
+    jobId: string;
+    handle: InteractiveEscalationHandle;
+    /** Resolves with the final report once the run settles. Must never reject. */
+    done: Promise<Record<string, unknown>>;
+    cancel: () => void;
+    /** Overrides for tests; production uses the module constants. */
+    maxLifetimeMs?: number;
+    cancelWaitMs?: number;
+}
+export declare class DebugSession {
+    readonly id: string;
+    readonly userId: string;
+    readonly workflowId: string | null;
+    readonly jobId: string;
+    private readonly _handle;
+    /** The run's own completion, raced with a forced settle. Never rejects. */
+    private readonly _done;
+    private readonly _cancel;
+    private readonly _cancelWaitMs;
+    private _force;
+    private _report;
+    constructor(options: CreateDebugSessionOptions, onSettled: () => void);
+    /** True until the run (or a forced settle) has produced a final report. */
+    isLive(): boolean;
+    /**
+     * Settle the session without the run: cancel what can be cancelled, fail the
+     * parked escalation closed, and hand every waiter a failed report. Used by
+     * the lifetime ceiling and by a cancel the run does not answer.
+     */
+    forceSettle(reason: string): void;
+    /**
+     * Wait until the run either parks an escalation or settles. There is no
+     * wait cap of its own: the non-interactive endpoint awaits the whole run
+     * too, a parked decision fails closed on its own timeout, and the session's
+     * lifetime ceiling settles anything that outlives both.
+     */
+    waitForEvent(): Promise<DebugSessionEvent>;
+    /** Current state without waiting. */
+    peek(): DebugSessionEvent;
+    submitVerdict(escalationId: string, verdict: Verdict): Promise<{
+        error: string;
+    } | null>;
+    /**
+     * Cancel the run and return its final report. The wait is bounded: a run
+     * that ignores cancellation used to hang the cancel request itself, so past
+     * the deadline the session settles on its own and answers with that.
+     */
+    cancel(): Promise<Record<string, unknown>>;
+}
+/** Thrown by `create()` when a user already holds the maximum live sessions. */
+export declare class TooManyDebugSessionsError extends Error {
+    constructor(limit: number);
+}
+declare class DebugSessionRegistry {
+    private readonly _sessions;
+    /** Live sessions this user holds. */
+    liveCount(userId: string): number;
+    create(options: CreateDebugSessionOptions): DebugSession;
+    /** Ownership is part of the lookup: a foreign session id is a miss. */
+    get(sessionId: string, userId: string): DebugSession | null;
+}
+export declare const debugSessions: DebugSessionRegistry;
+export {};
+//# sourceMappingURL=debug-sessions.d.ts.map

package/dist/service/debug-sessions.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"debug-sessions.d.ts","sourceRoot":"","sources":["../../src/service/debug-sessions.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAKH,OAAO,KAAK,EAAE,eAAe,EAAE,gBAAgB,EAAE,MAAM,qBAAqB,CAAC;AAC7E,OAAO,KAAK,EAAE,UAAU,EAAE,OAAO,EAAE,MAAM,uBAAuB,CAAC;AAIjE,8EAA8E;AAC9E,eAAO,MAAM,+BAA+B,QAAc,CAAC;AAK3D;;;;GAIG;AACH,eAAO,MAAM,uBAAuB,QAAc,CAAC;AAEnD,+EAA+E;AAC/E,eAAO,MAAM,wBAAwB,QAAS,CAAC;AAE/C,2DAA2D;AAC3D,eAAO,MAAM,0BAA0B,IAAI,CAAC;AAa5C,4EAA4E;AAC5E,MAAM,WAAW,gBAAgB;IAC/B,EAAE,EAAE,MAAM,CAAC;IACX,UAAU,EAAE,UAAU,CAAC;CACxB;AAED;;;;;GAKG;AACH,qBAAa,2BAA4B,YAAW,gBAAgB;IAClE,OAAO,CAAC,QAAQ,CAAkC;IAClD,OAAO,CAAC,QAAQ,CAAgD;IAChE,OAAO,CAAC,QAAQ,CAAK;IACrB,OAAO,CAAC,OAAO,CAAS;IAExB,MAAM,CAAC,CAAC,EAAE,UAAU,EAAE,MAAM,EAAE,WAAW,GAAG,OAAO,CAAC,eAAe,CAAC,CAsBnE;IAED,2DAA2D;IAC3D,OAAO,IAAI;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,UAAU,EAAE,UAAU,CAAA;KAAE,GAAG,IAAI,CAGvD;IAED;;;;;OAKG;IACH,SAAS,CAAC,MAAM,EAAE,CAAC,KAAK,EAAE,gBAAgB,KAAK,IAAI,GAAG,MAAM,IAAI,CAM/D;IAED;;;;;;;;;;;OAWG;IACG,MAAM,CACV,YAAY,EAAE,MAAM,EACpB,OAAO,EAAE,OAAO,GACf,OAAO,CAAC;QAAE,KAAK,EAAE,MAAM,CAAA;KAAE,GAAG,IAAI,CAAC,CA2CnC;IAED,KAAK,IAAI,IAAI,CAGZ;CACF;AAED,MAAM,MAAM,iBAAiB,GACzB;IAAE,IAAI,EAAE,WAAW,CAAC;IAAC,YAAY,EAAE,MAAM,CAAC;IAAC,UAAU,EAAE,UAAU,CAAA;CAAE,GACnE;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;CAAE,GACjD;IAAE,IAAI,EAAE,SAAS,CAAA;CAAE,CAAC;AAExB,MAAM,WAAW,yBAAyB;IACxC,MAAM,EAAE,MAAM,CAAC;IACf,wEAAwE;IACxE,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,2BAA2B,CAAC;IACpC,8EAA8E;IAC9E,IAAI,EAAE,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;IACvC,MAAM,EAAE,MAAM,IAAI,CAAC;IACnB,iEAAiE;IACjE,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAED,qBAAa,YAAY;IACvB,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IACnC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,OAAO,CAAC,QAAQ,CAAC,OAAO,CAA8B;IACtD,2EAA2E;IAC3E,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAmC;IACzD,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAa;IACrC,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAS;IACvC,OAAO,CAAC,MAAM,CAAuD;IACrE,OAAO,CAAC,OAAO,CAAwC;IAEvD,YAAY,OAAO,EAAE,yBAAyB,EAAE,SAAS,EAAE,MAAM,IAAI,EAmBpE;IAED,2EAA2E;IAC3E,MAAM,IAAI,OAAO,CAEhB;IAED;;;;OAIG;IACH,WAAW,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAiBhC;IAED;;;;;OAKG;IACG,YAAY,IAAI,OAAO,CAAC,iBAAiB,CAAC,CA4B/C;IAED,qCAAqC;IACrC,IAAI,IAAI,iBAAiB,CAWxB;IAEK,aAAa,CACjB,YAAY,EAAE,MAAM,EACpB,OAAO,EAAE,OAAO,GACf,OAAO,CAAC;QAAE,KAAK,EAAE,MAAM,CAAA;KAAE,GAAG,IAAI,CAAC,CAKnC;IAED;;;;OAIG;IACG,MAAM,IAAI,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAwB/C;CACF;AAED,gFAAgF;AAChF,qBAAa,yBAA0B,SAAQ,KAAK;IAClD,YAAY,KAAK,EAAE,MAAM,EAMxB;CACF;AAED,cAAM,oBAAoB;IACxB,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAmC;IAE7D,qCAAqC;IACrC,SAAS,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAMhC;IAED,MAAM,CAAC,OAAO,EAAE,yBAAyB,GAAG,YAAY,CA4BvD;IAED,uEAAuE;IACvE,GAAG,CAAC,SAAS,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,YAAY,GAAG,IAAI,CAI1D;CACF;AAED,eAAO,MAAM,aAAa,sBAA6B,CAAC"}