@try-works/dsh-tool-mode 0.0.0-stage → 0.5.44

package/lib/transport.js

@@ -0,0 +1,332 @@
+/**
+ * Command transports: reaching a model that is not an in-process npm package.
+ *
+ * Two transports share one shape:
+ *
+ * - **cli** — runs the Desert Ant CLI (`desertant`/`da`), which exposes every
+ *   shipping model as `desertant <verb> … --json` and runs on macOS and Linux.
+ * - **remote** — POSTs to a bridge the user runs on a machine that can execute
+ *   the model. This is what makes an Apple-only model such as Title reachable
+ *   from a Windows host.
+ *
+ * Both are injected with their side-effecting primitive (`CommandRunner`,
+ * `HttpPost`) so behaviour is testable without spawning a process or opening a
+ * socket, and so a deployment can substitute its own runner.
+ *
+ * @module @try-works/dsh-tool-mode/transport
+ */
+import { spawn } from 'node:child_process';
+import { accessSync, constants } from 'node:fs';
+import { delimiter, join } from 'node:path';
+import { throwIfAborted } from "./adapters/types.js";
+/** The Desert Ant CLI's exit codes, as documented for agents. */
+export const CLI_EXIT_RUNTIME_ERROR = 1;
+export const CLI_EXIT_USAGE_ERROR = 64;
+/**
+ * Default command name. `da` is the short alias the CLI installs.
+ */
+export const DEFAULT_CLI_COMMAND = 'desertant';
+/** The path every bridge must serve. */
+export const BRIDGE_PATH = '/invoke';
+/**
+ * Whether a command is on PATH.
+ *
+ * Probed by scanning PATH rather than by running the command, because this runs
+ * at plugin load and a capability probe must not start a process (or pay a
+ * CLI's startup cost) just to decide what to advertise.
+ * @param command - command name or an absolute path.
+ * @param pathValue - the PATH to search; defaults to the process environment.
+ * @returns whether an executable file of that name exists.
+ */
+export function commandExists(command, pathValue) {
+    // An explicit path is checked directly; a bare name is searched on PATH.
+    if (command.includes('/') || command.includes('\\')) {
+        return isExecutable(command);
+    }
+    const searchPath = pathValue ?? process.env.PATH ?? '';
+    const extensions = process.platform === 'win32'
+        ? (process.env.PATHEXT ?? '.COM;.EXE;.BAT;.CMD').split(';')
+        : [''];
+    for (const directory of searchPath.split(delimiter)) {
+        if (directory.length === 0)
+            continue;
+        for (const extension of extensions) {
+            if (isExecutable(join(directory, command + extension)))
+                return true;
+        }
+    }
+    return false;
+}
+/** Whether a path is an existing executable file. */
+function isExecutable(candidate) {
+    try {
+        accessSync(candidate, constants.X_OK);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Split the tool arguments into the CLI's positional inputs and its
+ * `--option key=value` flags.
+ *
+ * The first declared catalog parameter is the primary input, matching how the
+ * registrar marks it required. A file model accepts several paths positionally
+ * (the CLI loads the model once for all of them), so a primary declared as a
+ * string list becomes several positionals. Everything else becomes an option,
+ * with lists comma-joined because the CLI's option syntax is `key=value`.
+ * @param entry - the catalog entry being invoked.
+ * @param args - validated tool arguments.
+ * @returns the positional inputs and the option list.
+ */
+export function splitArguments(entry, args) {
+    const names = Object.keys(entry.tool.params);
+    const primaryName = names[0];
+    if (primaryName === undefined) {
+        throw new Error(`${entry.name} declares no parameters, so its input cannot be addressed`);
+    }
+    const primaryValue = args[primaryName];
+    let positionals;
+    if (typeof primaryValue === 'string' && primaryValue.length > 0) {
+        positionals = [primaryValue];
+    }
+    else if (Array.isArray(primaryValue) && primaryValue.length > 0
+        && primaryValue.every(item => typeof item === 'string' && item.length > 0)) {
+        positionals = primaryValue;
+    }
+    else {
+        throw new Error(`argument "${primaryName}" must be a non-empty string or list of paths`);
+    }
+    const options = [];
+    for (const name of names.slice(1)) {
+        const value = args[name];
+        if (value === undefined)
+            continue;
+        if (Array.isArray(value)) {
+            options.push([name.replaceAll('_', '-'), value.map(String).join(',')]);
+        }
+        else if (typeof value === 'boolean' || typeof value === 'number') {
+            options.push([name.replaceAll('_', '-'), String(value)]);
+        }
+        else if (typeof value === 'string') {
+            options.push([name.replaceAll('_', '-'), value]);
+        }
+        else {
+            throw new Error(`argument "${name}" must be a string, number, boolean or string list`);
+        }
+    }
+    return { positionals, options };
+}
+/**
+ * Build the CLI argv for one invocation.
+ *
+ * `--json` is what makes stdout a single JSON value, and it also implies
+ * `--no-color`, so no escape sequences have to be stripped.
+ * @param entry - the catalog entry being invoked.
+ * @param args - validated tool arguments.
+ * @returns the argv to run, after the command itself.
+ */
+export function buildArgv(entry, args) {
+    const verb = entry.cliVerb;
+    if (verb === null)
+        throw new Error(`${entry.name} has no CLI verb, so the CLI cannot run it`);
+    const { positionals, options } = splitArguments(entry, args);
+    const argv = [verb, ...positionals, '--json'];
+    for (const [key, value] of options)
+        argv.push('--option', `${key}=${value}`);
+    return argv;
+}
+/**
+ * Parse the CLI's stdout into a canonical value.
+ *
+ * The CLI writes exactly one JSON value to stdout under `--json` and keeps every
+ * diagnostic on stderr, so a parse failure means the command did not behave as
+ * documented rather than that output needs cleaning.
+ * @param entry - the model, for error messages.
+ * @param outcome - the completed command.
+ * @returns the parsed value.
+ * @throws when the exit code is non-zero or stdout is not a single JSON value.
+ */
+export function parseCliOutcome(entry, outcome) {
+    if (outcome.code === CLI_EXIT_USAGE_ERROR) {
+        throw new Error(`${entry.name}: the CLI rejected the call (exit 64). ${outcome.stderr.trim() || 'usage error'}`);
+    }
+    if (outcome.code === CLI_EXIT_RUNTIME_ERROR) {
+        throw new Error(`${entry.name} failed (exit 1). ${outcome.stderr.trim() || 'runtime error'}`);
+    }
+    if (outcome.code !== 0) {
+        throw new Error(`${entry.name}: the CLI exited ${outcome.code}. ${outcome.stderr.trim() || 'unknown failure'}`);
+    }
+    const text = outcome.stdout.trim();
+    if (text.length === 0) {
+        throw new Error(`${entry.name}: the CLI produced no JSON on stdout`);
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(text);
+    }
+    catch (error) {
+        throw new Error(`${entry.name}: the CLI stdout was not JSON: ${error instanceof Error ? error.message : String(error)}`);
+    }
+    return asRecord(entry, parsed);
+}
+/**
+ * Wrap a JSON value as the object a tool output schema requires.
+ * @param entry - the model, for error messages.
+ * @param value - the parsed value.
+ * @returns the value as a record; a non-object is wrapped under `result`.
+ */
+function asRecord(entry, value) {
+    if (typeof value === 'object' && value !== null && !Array.isArray(value)) {
+        return value;
+    }
+    if (Array.isArray(value))
+        return { result: value };
+    // A scalar result is still a result; naming it keeps the output contract
+    // stable instead of failing a call that actually succeeded.
+    void entry;
+    return { result: value };
+}
+/** Spawn a command and capture its output. */
+export const spawnRunner = (command, argv, signal) => new Promise((resolve, reject) => {
+    // `shell: false` keeps argv elements from being re-interpreted by a shell,
+    // so a model input containing quotes or `&` cannot become a second command.
+    const child = spawn(command, [...argv], { shell: false, windowsHide: true });
+    let stdout = '';
+    let stderr = '';
+    let settled = false;
+    const onAbort = () => {
+        if (settled)
+            return;
+        settled = true;
+        child.kill();
+        reject(signal.reason instanceof Error ? signal.reason : new Error('aborted'));
+    };
+    if (signal.aborted) {
+        onAbort();
+        return;
+    }
+    signal.addEventListener('abort', onAbort, { once: true });
+    child.stdout.setEncoding('utf8');
+    child.stderr.setEncoding('utf8');
+    child.stdout.on('data', (chunk) => { stdout += chunk; });
+    child.stderr.on('data', (chunk) => { stderr += chunk; });
+    child.on('error', (error) => {
+        if (settled)
+            return;
+        settled = true;
+        signal.removeEventListener('abort', onAbort);
+        reject(new Error(`cannot run "${command}": ${error.message}`));
+    });
+    child.on('close', (code) => {
+        if (settled)
+            return;
+        settled = true;
+        signal.removeEventListener('abort', onAbort);
+        resolve({ code: code ?? -1, stdout, stderr });
+    });
+});
+/** POST JSON with the global fetch and read the response as text. */
+export const fetchPost = async (url, body, headers, signal) => {
+    const response = await fetch(url, {
+        method: 'POST',
+        headers: { 'content-type': 'application/json', ...headers },
+        body: JSON.stringify(body),
+        signal,
+    });
+    return { status: response.status, body: await response.text() };
+};
+/**
+ * Build the CLI transport for one model.
+ * @param entry - the catalog entry, which must declare a CLI verb.
+ * @param options - command name and injected runner.
+ * @returns the transport.
+ */
+export function createCliTransport(entry, options = {}) {
+    const command = options.cliCommand ?? DEFAULT_CLI_COMMAND;
+    const run = options.run ?? spawnRunner;
+    return {
+        kind: 'cli',
+        async invoke({ args, signal }) {
+            throwIfAborted(signal);
+            const argv = buildArgv(entry, args);
+            const outcome = await run(command, argv, signal);
+            throwIfAborted(signal);
+            return parseCliOutcome(entry, outcome);
+        },
+    };
+}
+/**
+ * Build the remote transport for one model.
+ *
+ * The bridge contract is deliberately small so a user can implement it in a few
+ * lines on a machine that can run the model:
+ *
+ * ```
+ * POST <endpoint>/invoke
+ *   { "model": "title", "verb": "title", "input": "<primary>", "options": { "max-tokens": "96" } }
+ *   → 200 { "ok": true,  "result": <the model's JSON> }
+ *   → 4xx { "ok": false, "error": "<message>" }
+ * ```
+ * @param entry - the catalog entry to reach.
+ * @param options - endpoint, optional token, injected poster.
+ * @returns the transport.
+ */
+export function createRemoteTransport(entry, options = {}) {
+    const endpoint = options.endpoint;
+    if (endpoint === undefined || endpoint.length === 0) {
+        throw new Error('the remote transport requires an endpoint');
+    }
+    const post = options.post ?? fetchPost;
+    const url = `${endpoint.replace(/\/+$/, '')}${BRIDGE_PATH}`;
+    const headers = options.token === undefined
+        ? {}
+        : { authorization: `Bearer ${options.token}` };
+    return {
+        kind: 'remote',
+        async invoke({ args, signal }) {
+            throwIfAborted(signal);
+            const verb = entry.cliVerb;
+            if (verb === null)
+                throw new Error(`${entry.name} declares no verb for the bridge to run`);
+            const { positionals, options: flags } = splitArguments(entry, args);
+            const response = await post(url, {
+                model: entry.id,
+                verb,
+                // A file model may pass several paths; `input` carries them all so the
+                // bridge does not have to know which models take more than one.
+                input: positionals.length === 1 ? positionals[0] : positionals,
+                options: Object.fromEntries(flags),
+            }, headers, signal);
+            throwIfAborted(signal);
+            return parseBridgeResponse(entry, response);
+        },
+    };
+}
+/**
+ * Interpret one bridge response.
+ * @param entry - the model, for error messages.
+ * @param response - the HTTP status and body.
+ * @returns the model's result as a canonical value.
+ * @throws when the bridge reports a failure or an unreadable body.
+ */
+export function parseBridgeResponse(entry, response) {
+    let parsed;
+    try {
+        parsed = JSON.parse(response.body);
+    }
+    catch {
+        throw new Error(`${entry.name}: the bridge returned a non-JSON body (HTTP ${response.status})`);
+    }
+    if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed)) {
+        throw new Error(`${entry.name}: the bridge returned an unexpected body shape`);
+    }
+    const envelope = parsed;
+    if (envelope.ok !== true) {
+        const detail = typeof envelope.error === 'string' ? envelope.error : `HTTP ${response.status}`;
+        throw new Error(`${entry.name}: the bridge could not run the model. ${detail}`);
+    }
+    return asRecord(entry, envelope.result);
+}
+//# sourceMappingURL=transport.js.map

package/lib/types.d.ts

@@ -0,0 +1,134 @@
+/**
+ * Data model for the Desert Ant Labs model catalog and the capability layer
+ * that decides whether a model can actually run in the current DSH process.
+ *
+ * @module @try-works/dsh-tool-mode/types
+ */
+/** The kind of value a model consumes. */
+export type ModelInput = 'text' | 'audio' | 'image' | 'video' | 'stroke' | 'transcript';
+/**
+ * How the model's weights are reachable from a Node process on each platform.
+ * This is the field the capability resolver keys off, because it encodes the
+ * upstream packaging reality rather than an aspiration.
+ */
+export type WindowsSupport = 
+/** Ships a prebuilt native core for this platform and works in plain Node. */
+'native-node'
+/** Needs a caller-supplied ONNX Runtime module (e.g. `onnxruntime-node`). */
+ | 'onnxruntime-node'
+/** No Node runtime anywhere: Apple platforms only, through the Swift SDK. */
+ | 'apple-only'
+/** Prebuilt native core exists, but not for this platform/arch. */
+ | 'browser-only'
+/** Weights exist but no SDK ships them at all. */
+ | 'no-sdk';
+/** The JSON-level type of one tool parameter. */
+export type ModelParamType = 'string' | 'number' | 'integer' | 'boolean' | 'string[]';
+/**
+ * One declared tool parameter.
+ *
+ * A bare string is shorthand for `{ type: 'string', description }`, which is
+ * what most of the catalog's parameters are; the object form exists for the
+ * parameters that are genuinely numbers, booleans or string lists.
+ */
+export interface ModelParam {
+    /** Model-facing description of the parameter. */
+    readonly description: string;
+    /** Declared type; defaults to `string`. */
+    readonly type?: ModelParamType;
+}
+/** One parameter as written in the catalog document. */
+export type ModelParamSpec = string | ModelParam;
+/** The model-facing tool a catalog entry installs. */
+export interface ModelToolSpec {
+    /** DSH tool name (lower snake_case). */
+    readonly name: string;
+    /** Model-facing description of the tool. */
+    readonly description: string;
+    /** Parameter name -> declaration, in documentation order; the first is the primary input. */
+    readonly params: Readonly<Record<string, ModelParam>>;
+    /** What the tool returns. */
+    readonly returns: string;
+}
+/** The skill a catalog entry publishes alongside its tool. */
+export interface ModelSkillSpec {
+    /** Kebab-case skill name. */
+    readonly name: string;
+    /** Short routing description for the skill catalog. */
+    readonly description: string;
+    /** Optional extra routing guidance. */
+    readonly whenToUse?: string;
+}
+/** One model in the Desert Ant Labs catalog. */
+export interface ModelCatalogEntry {
+    readonly id: string;
+    readonly name: string;
+    readonly summary: string;
+    readonly capability: string;
+    /**
+     * The standard contract this model implements, or null when none exists yet.
+     *
+     * This is what makes tool identity independent of model identity (BASE-02): the
+     * contract decides the tool name a caller sees, so a second model implementing
+     * the same contract joins the existing tool instead of creating a duplicate. A
+     * model with no contract keeps a per-model tool under its own name.
+     */
+    readonly contract: string | null;
+    /**
+     * The extension package that implements this model (BASE-09).
+     *
+     * A binding held as DATA, not a switch on the model name. The host loads
+     * whatever package this names through the PUBLIC extension API, so a first-party
+     * package takes the same route as a third-party one and adding a vendor means
+     * publishing a package plus adding this field — with no host change.
+     */
+    readonly provider?: {
+        readonly extension: string;
+        readonly modelId: string;
+    };
+    readonly input: ModelInput;
+    readonly output: string;
+    readonly languages: number | null;
+    readonly modelSizeMB: number | null;
+    readonly appleOnly: boolean;
+    readonly closedBeta: boolean;
+    /** True only where this repository verified a real inference on Windows x64. */
+    readonly verifiedRunnableOnWindows: boolean;
+    readonly windowsSupport: WindowsSupport;
+    readonly npmPackage: string | null;
+    readonly npmSubpath: string | null;
+    readonly requiresRuntime: readonly string[];
+    readonly cliVerb: string | null;
+    readonly license: string;
+    readonly docsUrl: string;
+    readonly hfRepo: string;
+    readonly tool: ModelToolSpec;
+    readonly skill: ModelSkillSpec;
+}
+/** How an adapter reaches a model at run time. */
+export type ModelRoute = 
+/** A Tool Mode extension package loaded in this process. */
+'extension'
+/** An npm package loaded in this process. */
+ | 'npm-native'
+/** An npm package plus a caller-supplied ONNX Runtime module. */
+ | 'npm-onnxruntime'
+/** The Desert Ant CLI, run as a child process (macOS and Linux). */
+ | 'cli'
+/** A user-hosted bridge, reached over HTTP. */
+ | 'remote'
+/** No route available in this process. */
+ | 'unavailable';
+/** The capability resolver's verdict for one model in the current process. */
+export interface CapabilityVerdict {
+    /** Whether an adapter can actually produce a working tool for this model. */
+    readonly runnable: boolean;
+    readonly route: ModelRoute;
+    /** Why the model is or is not runnable, always populated for a negative verdict. */
+    readonly reason: string;
+    /** Resolved package specifiers this verdict depended on, for diagnostics. */
+    readonly resolved?: readonly string[];
+    /** Resolved package specifiers that were required but missing. */
+    readonly missing?: readonly string[];
+}
+//# sourceMappingURL=types.d.ts.map

package/lib/types.d.ts.map

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

package/lib/types.js

@@ -0,0 +1,8 @@
+/**
+ * Data model for the Desert Ant Labs model catalog and the capability layer
+ * that decides whether a model can actually run in the current DSH process.
+ *
+ * @module @try-works/dsh-tool-mode/types
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/lib/update-surface.d.ts

@@ -0,0 +1,79 @@
+/**
+ * The host's UpdateHostSurface (EXT-30, slice 3): the operator approval
+ * surface, the two-phase commit with quiesce/rebind hooks, and the standalone
+ * rollback with a bounded rebindRestored.
+ *
+ * The SDK owns the durable mechanics (staging, validation reports, approval
+ * RECORDS, the atomic pointer, the auto-rollback); this module owns the HOST
+ * decisions the SDK refuses to invent (design doc §6):
+ *
+ * - the pending listing + approve/deny over the SDK's approval records;
+ * - the quiesce (stop old-generation admissions) and the rebind (republish the
+ *   new generation) — supplied as closures so the index wiring passes the
+ *   lifecycle/registrar pair and tests can pass recorded fakes;
+ * - the ALL-OR-NOTHING rebind wrapper: the SDK's auto-rollback re-runs NO
+ *   hooks (the REBIND-REVERT contract), so a rebind failure restores the
+ *   previous surface HERE, before the pointer rollback lands;
+ * - the host-side timeout bound on rebindRestored (the SDK awaits it with no
+ *   bound; only the management caller must not hang).
+ *
+ * The management channel stays the ONLY caller of this surface (AT-39).
+ *
+ * @module @dsh-tool-mode/update-surface
+ */
+import type { UpdateCommitResult, UpdateRollbackResult, UpdateValidationReport } from '@try-works/tool-mode-extension-sdk';
+/** One pending staged update, from the staging directory + the approval record. */
+export interface PendingUpdateEntry {
+    readonly extensionId: string;
+    readonly stagedVersion: string;
+    /** The version the report was computed against. */
+    readonly currentVersion: string;
+    readonly stagedAt: string;
+    readonly report: UpdateValidationReport;
+    /** The persisted approval, when one was recorded. */
+    readonly approval?: {
+        readonly approved: boolean;
+        readonly reason?: string;
+    };
+}
+/** The host-side lifecycle closures the surface drives. */
+export interface UpdateHostHooks {
+    /** Stop old-generation admissions (withdraw handles, stop admitting). */
+    readonly quiesce: (extensionId: string) => Promise<void>;
+    /** Publish the new generation's surface (must be all-or-nothing per the SDK contract). */
+    readonly rebind: (extensionId: string, version: string) => Promise<void>;
+}
+/** The operator approval surface + commit/rollback. */
+export interface UpdateHostSurface {
+    /** The pending staged updates with their reports and approval records. */
+    listPendingUpdates(): PendingUpdateEntry[];
+    /** Record ONE approval decision (write-once per staged version). */
+    decide(extensionId: string, stagedVersion: string, decision: {
+        approved: true;
+    } | {
+        approved: false;
+        reason: string;
+    }): void;
+    /**
+     * Commit a staged update through the two-phase seam.
+     * @throws when the SDK refuses (no approved record, integrity, quiesce, rebind).
+     */
+    commit(extensionId: string, stagedVersion: string): Promise<UpdateCommitResult>;
+    /** Roll the pointer back with a TIME-BOUNDED rebindRestored. */
+    rollback(extensionId: string): Promise<UpdateRollbackResult>;
+}
+/** The surface options. */
+export interface UpdateHostSurfaceOptions {
+    readonly storeDir: string;
+    readonly profile: string;
+    readonly hooks: UpdateHostHooks;
+    /** The host-side bound on rebindRestored; default 30 s. */
+    readonly rebindTimeoutMs?: number;
+}
+/**
+ * Create the host update surface.
+ * @param options - the store location, profile, lifecycle hooks and the timeout bound.
+ * @returns the surface.
+ */
+export declare function createUpdateHostSurface(options: UpdateHostSurfaceOptions): UpdateHostSurface;
+//# sourceMappingURL=update-surface.d.ts.map

package/lib/update-surface.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"update-surface.d.ts","sourceRoot":"","sources":["../src/update-surface.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAGH,OAAO,KAAK,EACV,kBAAkB,EAClB,oBAAoB,EACpB,sBAAsB,EACvB,MAAM,oCAAoC,CAAA;AAI3C,mFAAmF;AACnF,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAA;IAC5B,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAA;IAC9B,mDAAmD;IACnD,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAA;IAC/B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAA;IACzB,QAAQ,CAAC,MAAM,EAAE,sBAAsB,CAAA;IACvC,qDAAqD;IACrD,QAAQ,CAAC,QAAQ,CAAC,EAAE;QAAE,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC;QAAC,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAA;KAAE,CAAA;CAC7E;AAED,2DAA2D;AAC3D,MAAM,WAAW,eAAe;IAC9B,yEAAyE;IACzE,QAAQ,CAAC,OAAO,EAAE,CAAC,WAAW,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAA;IACxD,0FAA0F;IAC1F,QAAQ,CAAC,MAAM,EAAE,CAAC,WAAW,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAA;CACzE;AAED,uDAAuD;AACvD,MAAM,WAAW,iBAAiB;IAChC,0EAA0E;IAC1E,kBAAkB,IAAI,kBAAkB,EAAE,CAAA;IAC1C,oEAAoE;IACpE,MAAM,CACJ,WAAW,EAAE,MAAM,EACnB,aAAa,EAAE,MAAM,EACrB,QAAQ,EAAE;QAAE,QAAQ,EAAE,IAAI,CAAA;KAAE,GAAG;QAAE,QAAQ,EAAE,KAAK,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,GACjE,IAAI,CAAA;IACP;;;OAGG;IACH,MAAM,CAAC,WAAW,EAAE,MAAM,EAAE,aAAa,EAAE,MAAM,GAAG,OAAO,CAAC,kBAAkB,CAAC,CAAA;IAC/E,gEAAgE;IAChE,QAAQ,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,oBAAoB,CAAC,CAAA;CAC7D;AAED,2BAA2B;AAC3B,MAAM,WAAW,wBAAwB;IACvC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAA;IACzB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;IACxB,QAAQ,CAAC,KAAK,EAAE,eAAe,CAAA;IAC/B,2DAA2D;IAC3D,QAAQ,CAAC,eAAe,CAAC,EAAE,MAAM,CAAA;CAClC;AA6CD;;;;GAIG;AACH,wBAAgB,uBAAuB,CAAC,OAAO,EAAE,wBAAwB,GAAG,iBAAiB,CAsJ5F"}