agent-nuvira 3.3.3 → 3.3.4

package/dist/gateway/hooks.d.ts

@@ -1,32 +1,83 @@
 /**
  * I2 — Hook registry (`src/gateway/hooks.ts`).
  *
- * Lifecycle hooks the agent
- * runtime fires at well-defined moments. Two events today (extensible):
+ * Lifecycle hooks the agent runtime fires at well-defined moments. The tool
+ * phases are the WS4 (#26) triple, in the order a call goes through them:
  *
- * - `post_tool_call`  — after the tool loop executes a registry tool. Driven
- *   by the `tool:called` event-bus event emitted from `src/tools/tool-loop.ts`
- *   (the `post_tool_call` hook). Handlers receive the tool name,
- *   result, success flag and duration.
- * - `on_session_end`  — after a pipeline run finishes (execute:completed /
- *   execute:failed). Handlers receive the run's success + summary.
+ * - `before_tool_call` — BEFORE the call runs, and the ONLY phase that can stop
+ *   it: a handler returns a {@link HookDecision} and the call is not made.
+ * - `after_tool_call`  — the call ran and succeeded. Handlers receive the tool
+ *   name, the result, the success flag and the duration.
+ * - `failed_tool_call` — the call ran and did NOT succeed (a thrown error, or a
+ *   result the loop`s own convention marks as a failure).
+ * - `on_session_end`   — after a pipeline run finishes (execute:completed /
+ *   execute:failed). Handlers receive the run`s success + summary.
  *
- * Wiring is through the EXISTING observability event bus — hooks are typed
- * consumers, not a parallel system. `installHooks(bus)` subscribes and returns
- * an unsubscribe; the default built-in hook logs session summaries.
+ * `post_tool_call` was this event`s previous name. It is renamed rather than
+ * aliased so the three phases read exactly as the capability is stated
+ * (before/after/failed); nothing in production subscribed to it, and an alias
+ * would leave two names for one moment — the drift this repo removes elsewhere.
+ *
+ * THE TOOL PHASES ARE DRIVEN BY THE EXECUTION SEAM, not the event bus, and that
+ * is a deliberate reversal of the original wiring. A bus subscription is
+ * fire-and-forget: it cannot stop a call, it cannot tell the loop what a
+ * subscriber decided, and it only fires on a surface that happens to put
+ * `tool:called` on the bus — so a hook installed that way reached the gateway and
+ * nowhere else. `src/tools/tool-loop.ts` and `src/tools/child-agent-runtime.ts`
+ * call {@link HookRegistry.runBefore} / {@link HookRegistry.run} directly, which
+ * is what makes the hooks fire on all five surfaces and lets a veto be honoured.
+ */
+export type HookEvent = 'before_tool_call' | 'after_tool_call' | 'failed_tool_call' | 'on_session_end';
+/**
+ * What a `before_tool_call` handler may return to stop the call.
+ *
+ * A RETURN VALUE rather than a mutation, because the registry has to hand the
+ * decision back to the caller that is about to run the tool: a subscriber that
+ * could only observe could not veto.
+ */
+export interface HookDecision {
+    /** `true` stops the call. There is no "deny: false" — an absent decision allows. */
+    deny: true;
+    /** Why, in the operator's words. Flows to the model and to the turn's trace. */
+    reason?: string;
+    /** Which hook decided (a declaration label, or a subscriber's own name). */
+    by?: string;
+}
+/**
+ * The call itself, as every tool phase sees it.
+ *
+ * `report` is how a subscriber says something went wrong in its OWN handling.
+ * It exists because the seam FAILS OPEN: a broken hook must not block work, so if
+ * there were no way to report one, a hook that silently stopped working would be
+ * indistinguishable from a hook that allowed everything.
  */
-export type HookEvent = 'post_tool_call' | 'on_session_end';
-/** Context for `post_tool_call` handlers. */
-export interface ToolCallHookContext {
+export interface ToolCallRef {
     tool: string;
+    /** The call's arguments, as the model produced them. */
+    args?: Record<string, unknown>;
+    /** The provider's call id, when there is one. */
+    callId?: string;
+    /** The surface label the turn declared (`cli-chat`, `subagent`, …). */
+    surface?: string;
+    cwd?: string;
+    report?: (message: string) => void;
+}
+/** Context for `after_tool_call` handlers. */
+export interface ToolCallHookContext extends ToolCallRef {
     ok: boolean;
     /** The tool-result text fed back to the model (truncated for hooks). */
     result?: string;
-    /** Error text when the tool failed. */
-    error?: string;
     /** Execution duration in ms. */
     durationMs?: number;
 }
+/** Context for `failed_tool_call` handlers. */
+export interface FailedToolCallHookContext extends ToolCallRef {
+    /** Why it failed — the thrown message, or the failing result's own text. */
+    error: string;
+    /** The result text, when the tool returned a failure rather than throwing. */
+    result?: string;
+    durationMs?: number;
+}
 /** Context for `on_session_end` handlers. */
 export interface SessionEndHookContext {
     success: boolean;
@@ -34,8 +85,14 @@ export interface SessionEndHookContext {
     /** The pipeline goal when known. */
     goal?: string;
 }
-/** A hook handler — sync or async; the registry runs them serially. */
-export type HookHandler<T> = (ctx: T) => void | Promise<void>;
+/**
+ * A hook handler — sync or async; the registry runs them serially.
+ *
+ * A returned {@link HookDecision} is honoured for `before_tool_call` (the only
+ * phase where stopping the call is possible) and ignored elsewhere, so one
+ * handler type serves the whole registry.
+ */
+export type HookHandler<T> = (ctx: T) => void | HookDecision | Promise<void | HookDecision>;
 declare class HookRegistry {
     private handlers;
     /** Register a handler for a hook event. Idempotent per (event, fn) pair. */
@@ -44,10 +101,21 @@ declare class HookRegistry {
     unregister<T extends HookEvent>(event: T, handler: HookHandler<HookContextFor<T>>): void;
     /** Run every handler for an event, serially, best-effort (never throws). */
     run<T extends HookEvent>(event: T, ctx: HookContextFor<T>): Promise<void>;
+    /**
+     * Run the `before_tool_call` handlers and return the FIRST decision.
+     *
+     * Serial by construction: two hooks must not race over whether a call happens,
+     * and the first denial is the answer — a later hook cannot un-deny a call that
+     * has already been stopped. A handler that throws is reported and skipped
+     * (FAIL OPEN), so one broken hook cannot stop every tool call in the process.
+     */
+    runBefore(ctx: BeforeToolCallHookContext): Promise<HookDecision | null>;
     /** Registered handler counts per event (CLI/tests introspection). */
     list(): Record<HookEvent, number>;
 }
-type HookContextFor<T extends HookEvent> = T extends 'post_tool_call' ? ToolCallHookContext : SessionEndHookContext;
+/** Context for `before_tool_call` handlers: the call, before it happens. */
+export type BeforeToolCallHookContext = ToolCallRef;
+type HookContextFor<T extends HookEvent> = T extends 'before_tool_call' ? BeforeToolCallHookContext : T extends 'after_tool_call' ? ToolCallHookContext : T extends 'failed_tool_call' ? FailedToolCallHookContext : SessionEndHookContext;
 /** The singleton registry. */
 export declare const hooks: HookRegistry;
 /** Wire the registry to the event bus. Returns an unsubscribe function. */

package/dist/gateway/hooks.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"hooks.d.ts","sourceRoot":"","sources":["../../src/gateway/hooks.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAOH,MAAM,MAAM,SAAS,GAAG,gBAAgB,GAAG,gBAAgB,CAAC;AAE5D,6CAA6C;AAC7C,MAAM,WAAW,mBAAmB;IAClC,IAAI,EAAE,MAAM,CAAC;IACb,EAAE,EAAE,OAAO,CAAC;IACZ,wEAAwE;IACxE,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,uCAAuC;IACvC,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,gCAAgC;IAChC,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,6CAA6C;AAC7C,MAAM,WAAW,qBAAqB;IACpC,OAAO,EAAE,OAAO,CAAC;IACjB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,oCAAoC;IACpC,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED,uEAAuE;AACvE,MAAM,MAAM,WAAW,CAAC,CAAC,IAAI,CAAC,GAAG,EAAE,CAAC,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;AAI9D,cAAM,YAAY;IAChB,OAAO,CAAC,QAAQ,CAAiD;IAEjE,4EAA4E;IAC5E,QAAQ,CAAC,CAAC,SAAS,SAAS,EAAE,KAAK,EAAE,CAAC,EAAE,OAAO,EAAE,WAAW,CAAC,cAAc,CAAC,CAAC,CAAC,CAAC,GAAG,IAAI;IAMtF,4EAA4E;IAC5E,UAAU,CAAC,CAAC,SAAS,SAAS,EAAE,KAAK,EAAE,CAAC,EAAE,OAAO,EAAE,WAAW,CAAC,cAAc,CAAC,CAAC,CAAC,CAAC,GAAG,IAAI;IAQxF,4EAA4E;IACtE,GAAG,CAAC,CAAC,SAAS,SAAS,EAAE,KAAK,EAAE,CAAC,EAAE,GAAG,EAAE,cAAc,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC;IAU/E,qEAAqE;IACrE,IAAI,IAAI,MAAM,CAAC,SAAS,EAAE,MAAM,CAAC;CAMlC;AAED,KAAK,cAAc,CAAC,CAAC,SAAS,SAAS,IAAI,CAAC,SAAS,gBAAgB,GACjE,mBAAmB,GACnB,qBAAqB,CAAC;AAE1B,8BAA8B;AAC9B,eAAO,MAAM,KAAK,cAAqB,CAAC;AAIxC,2EAA2E;AAC3E,wBAAgB,YAAY,CAAC,GAAG,iCAAgB,GAAG,MAAM,IAAI,CA0C5D;AAID;;;GAGG;AACH,wBAAgB,oBAAoB,IAAI,IAAI,CAQ3C"}
+{"version":3,"file":"hooks.d.ts","sourceRoot":"","sources":["../../src/gateway/hooks.ts"],"names":[],"mappings":"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"}

package/dist/gateway/hooks.js

@@ -1,19 +1,31 @@
 /**
  * I2 — Hook registry (`src/gateway/hooks.ts`).
  *
- * Lifecycle hooks the agent
- * runtime fires at well-defined moments. Two events today (extensible):
+ * Lifecycle hooks the agent runtime fires at well-defined moments. The tool
+ * phases are the WS4 (#26) triple, in the order a call goes through them:
  *
- * - `post_tool_call`  — after the tool loop executes a registry tool. Driven
- *   by the `tool:called` event-bus event emitted from `src/tools/tool-loop.ts`
- *   (the `post_tool_call` hook). Handlers receive the tool name,
- *   result, success flag and duration.
- * - `on_session_end`  — after a pipeline run finishes (execute:completed /
- *   execute:failed). Handlers receive the run's success + summary.
+ * - `before_tool_call` — BEFORE the call runs, and the ONLY phase that can stop
+ *   it: a handler returns a {@link HookDecision} and the call is not made.
+ * - `after_tool_call`  — the call ran and succeeded. Handlers receive the tool
+ *   name, the result, the success flag and the duration.
+ * - `failed_tool_call` — the call ran and did NOT succeed (a thrown error, or a
+ *   result the loop`s own convention marks as a failure).
+ * - `on_session_end`   — after a pipeline run finishes (execute:completed /
+ *   execute:failed). Handlers receive the run`s success + summary.
  *
- * Wiring is through the EXISTING observability event bus — hooks are typed
- * consumers, not a parallel system. `installHooks(bus)` subscribes and returns
- * an unsubscribe; the default built-in hook logs session summaries.
+ * `post_tool_call` was this event`s previous name. It is renamed rather than
+ * aliased so the three phases read exactly as the capability is stated
+ * (before/after/failed); nothing in production subscribed to it, and an alias
+ * would leave two names for one moment — the drift this repo removes elsewhere.
+ *
+ * THE TOOL PHASES ARE DRIVEN BY THE EXECUTION SEAM, not the event bus, and that
+ * is a deliberate reversal of the original wiring. A bus subscription is
+ * fire-and-forget: it cannot stop a call, it cannot tell the loop what a
+ * subscriber decided, and it only fires on a surface that happens to put
+ * `tool:called` on the bus — so a hook installed that way reached the gateway and
+ * nowhere else. `src/tools/tool-loop.ts` and `src/tools/child-agent-runtime.ts`
+ * call {@link HookRegistry.runBefore} / {@link HookRegistry.run} directly, which
+ * is what makes the hooks fire on all five surfaces and lets a veto be honoured.
  */
 import { logger } from '../utils/logger.js';
 import { getEventBus, EventNames } from '../observability/event-bus.js';
@@ -45,14 +57,46 @@ class HookRegistry {
                 await handler(ctx);
             }
             catch (err) {
-                logger.debug(`hook '${event}' handler failed: ${err instanceof Error ? err.message : err}`);
+                const message = `hook '${event}' handler failed: ${err instanceof Error ? err.message : err}`;
+                // Told to the CALLER as well as the log, because a handler that throws is
+                // fail-open: without this, a broken subscriber is indistinguishable from
+                // one that approved.
+                ctx.report?.(message);
+                logger.debug(message);
+            }
+        }
+    }
+    /**
+     * Run the `before_tool_call` handlers and return the FIRST decision.
+     *
+     * Serial by construction: two hooks must not race over whether a call happens,
+     * and the first denial is the answer — a later hook cannot un-deny a call that
+     * has already been stopped. A handler that throws is reported and skipped
+     * (FAIL OPEN), so one broken hook cannot stop every tool call in the process.
+     */
+    async runBefore(ctx) {
+        for (const handler of this.handlers.get('before_tool_call') ?? []) {
+            let decision;
+            try {
+                decision = await handler(ctx);
+            }
+            catch (err) {
+                const message = `hook 'before_tool_call' handler failed: ${err instanceof Error ? err.message : err}`;
+                ctx.report?.(message);
+                logger.debug(message);
+                continue;
             }
+            if (decision && decision.deny)
+                return decision;
         }
+        return null;
     }
     /** Registered handler counts per event (CLI/tests introspection). */
     list() {
         return {
-            post_tool_call: this.handlers.get('post_tool_call')?.length ?? 0,
+            before_tool_call: this.handlers.get('before_tool_call')?.length ?? 0,
+            after_tool_call: this.handlers.get('after_tool_call')?.length ?? 0,
+            failed_tool_call: this.handlers.get('failed_tool_call')?.length ?? 0,
             on_session_end: this.handlers.get('on_session_end')?.length ?? 0,
         };
     }
@@ -63,16 +107,11 @@ export const hooks = new HookRegistry();
 /** Wire the registry to the event bus. Returns an unsubscribe function. */
 export function installHooks(bus = getEventBus()) {
     const unsubscribers = [];
-    unsubscribers.push(bus.on(EventNames.TOOL_CALLED, (record) => {
-        const d = (record.data ?? {});
-        void hooks.run('post_tool_call', {
-            tool: d.tool ?? 'unknown',
-            ok: d.ok !== false,
-            result: typeof d.result === 'string' ? d.result.slice(0, 500) : undefined,
-            error: d.error,
-            durationMs: d.durationMs,
-        });
-    }));
+    // NOTE: there is deliberately no `tool:called` subscription here any more. The
+    // tool phases are driven by the execution seam (see the module header), and a
+    // bus subscription would fire every tool hook a SECOND time on any surface
+    // that puts the event on the bus — which is the kind of double-fire nobody
+    // notices until a hook has an external side effect.
     unsubscribers.push(bus.on(EventNames.EXECUTE_COMPLETED, (record) => {
         const d = (record.data ?? {});
         void hooks.run('on_session_end', {

package/dist/gateway/hooks.js.map

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

package/dist/gateway/inbound-media.d.ts

@@ -0,0 +1,147 @@
+/**
+ * Inbound document hydration for the gateway (`src/gateway/inbound-media.ts`).
+ *
+ * A messaging transport delivers a DOCUMENT (a PDF report, a DOCX contract, a
+ * spreadsheet) as bytes + a filename — never as text. The bridge only extracted
+ * `conversation` / `extendedTextMessage`, so a document message arrived with an
+ * empty `text` and was dropped at `if (!text) continue`: the sender's own file
+ * vanished with no reply and no record.
+ *
+ * This module is the fix for the inbound half of that gap. The bridge DOWNLOADS
+ * the bytes, they ride on `InboundMessage.media`, and `handleInbound` calls
+ * `hydrateInboundMedia` — which writes them to the artifact sandbox and runs the
+ * SAME `read_extract` the agent uses for a file in the project folder. The
+ * returned section is prepended to the turn's text, so a caption + a document
+ * becomes one request the model can act on.
+ *
+ * Extraction (not the download) is what makes the file usable: a document whose
+ * bytes never become text is still a message the agent cannot answer. When the
+ * file cannot be extracted the section says so, with the typed code and the
+ * concrete alternatives `read_extract` produces — never a silent empty result.
+ *
+ * Never throws: a media failure must not break the text turn it arrived with.
+ */
+/** A media attachment that rode in on an inbound message. */
+export interface InboundMedia {
+    type: 'image' | 'video' | 'audio' | 'document';
+    /** The file's bytes (already downloaded by the transport). */
+    data: Uint8Array;
+    /** The sender's filename, when the transport provides one. */
+    filename?: string;
+    /** MIME type, when the transport provides one. */
+    mimetype?: string;
+    /** The transport's caption on the media message (may carry the instruction). */
+    caption?: string;
+}
+/** What we are willing to write + extract in one inbound turn. */
+export declare const MAX_INBOUND_MEDIA_BYTES: number;
+/** How long an extracted inbound attachment is kept before the sweep (ms). */
+export declare const INBOUND_MEDIA_TTL_MS: number;
+/**
+ * Sandbox size cap (bytes). Past this, the OLDEST remaining files are swept
+ * even if they are still inside the TTL — a long-running gateway fed scanned
+ * reports should not grow without bound.
+ */
+export declare const INBOUND_MEDIA_MAX_BYTES: number;
+/**
+ * Reduce a sender-supplied name to a safe basename that keeps its extension —
+ * the name is untrusted and must never escape the artifact dir.
+ */
+export declare function safeInboundName(media: InboundMedia): string;
+/** A document that arrived but could not be turned into text. */
+export interface InboundMediaFailure {
+    /** The attachment's display name. */
+    name: string;
+    /** The media kind (only 'document' triggers the sender reply — see below). */
+    type: InboundMedia['type'];
+    /** A short, sender-safe reason (no stack traces, no not artifact paths). */
+    reason: string;
+}
+/** The outcome of hydrating one inbound attachment. */
+export interface HydratedInboundMedia {
+    /**
+     * The labelled context section to prepend to the turn, or null when there is
+     * nothing to add. Never null in practice: extracted text, an image note, or a
+     * refusal note all produce a section.
+     */
+    section: string | null;
+    /**
+     * Set when a DOCUMENT arrived but could not be turned into text. The registry
+     * auto-replies with this to the sender — a document that produces no text and
+     * no reply is precisely the failure this whole path exists to remove.
+     */
+    failure?: InboundMediaFailure;
+}
+/**
+ * Render the sender-facing reply for a document that could not be extracted.
+ *
+ * Built from `reason` alone on purpose: the model-facing section carries the
+ * saved artifact path and agent-jargon alternatives (`call read_extract again
+ * with ocr:true`), neither of which belongs in a chat with the person who sent
+ * the file.
+ */
+export declare function formatMediaFailureReply(failure: InboundMediaFailure): string;
+/**
+ * Extract an inbound media attachment into a labelled context section. Never
+ * throws — a failure is reported as `failure` (plus a refusal section) instead.
+ *
+ * The saved path is always included so the model can follow up on the ORIGINAL
+ * file (e.g. `read_extract` with `ocr:true` for a scanned PDF, or
+ * `describe_image` for an image) instead of only seeing the extracted text.
+ */
+export declare function hydrateInboundMedia(media: InboundMedia, opts?: {
+    maxBytes?: number;
+}): Promise<HydratedInboundMedia>;
+/** The effective inbound-attachment policy (config `gateway.inboundAttachments`). */
+export interface InboundAttachmentPolicy {
+    /** When false, attachments are accepted but never downloaded or extracted. */
+    enabled: boolean;
+    /** Per-attachment byte cap (default MAX_INBOUND_MEDIA_BYTES). */
+    maxBytes: number;
+}
+/**
+ * Read the effective inbound-attachment policy from config. Never throws — an
+ * absent config (or a throwing ConfigManager) means the safe default: enabled,
+ * with the module's own cap.
+ */
+export declare function inboundAttachmentPolicy(cm?: {
+    getAll?: () => unknown;
+}): InboundAttachmentPolicy;
+/** A remote attachment to fetch before hydration (Discord CDN URL / Slack file). */
+export interface RemoteAttachment {
+    /** The attachment's media kind (already classified by the caller). */
+    type: InboundMedia['type'];
+    url: string;
+    filename?: string;
+    mimetype?: string;
+    size?: number;
+    /** True when fetching the URL needs an Authorization bearer token (Slack). */
+    authenticated?: boolean;
+    /** The token to send when `authenticated` (the caller supplies its own). */
+    token?: string;
+}
+/**
+ * Download a remote attachment's bytes (never throws — null on any failure or
+ * an over-cap size). Shared by the webhook receiver and the real-time Discord
+ * gateway / Slack Socket Mode transports, so one code path fetches every
+ * inbound attachment.
+ */
+export declare function downloadInboundAttachment(att: RemoteAttachment): Promise<InboundMedia | null>;
+/** What a sandbox sweep did (returned for the caller's log line). */
+export interface InboundPruneResult {
+    removed: number;
+    bytesFreed: number;
+    kept: number;
+}
+/**
+ * Sweep the inbound artifact sandbox: remove files older than `maxAgeMs`, then
+ * (if still over `maxBytes`) the OLDEST of what remains until it fits. Safe to
+ * call on a schedule — never throws, and a file that cannot be removed is
+ * skipped rather than aborting the sweep.
+ */
+export declare function pruneInboundMedia(opts?: {
+    maxAgeMs?: number;
+    maxBytes?: number;
+    now?: number;
+}): InboundPruneResult;
+//# sourceMappingURL=inbound-media.d.ts.map

package/dist/gateway/inbound-media.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"inbound-media.d.ts","sourceRoot":"","sources":["../../src/gateway/inbound-media.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAMH,6DAA6D;AAC7D,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,OAAO,GAAG,OAAO,GAAG,OAAO,GAAG,UAAU,CAAC;IAC/C,8DAA8D;IAC9D,IAAI,EAAE,UAAU,CAAC;IACjB,8DAA8D;IAC9D,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,kDAAkD;IAClD,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,gFAAgF;IAChF,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,kEAAkE;AAClE,eAAO,MAAM,uBAAuB,QAAmB,CAAC;AAExD,8EAA8E;AAC9E,eAAO,MAAM,oBAAoB,QAA0B,CAAC;AAE5D;;;;GAIG;AACH,eAAO,MAAM,uBAAuB,QAAoB,CAAC;AAkCzD;;;GAGG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,YAAY,GAAG,MAAM,CAO3D;AAwBD,iEAAiE;AACjE,MAAM,WAAW,mBAAmB;IAClC,qCAAqC;IACrC,IAAI,EAAE,MAAM,CAAC;IACb,8EAA8E;IAC9E,IAAI,EAAE,YAAY,CAAC,MAAM,CAAC,CAAC;IAC3B,4EAA4E;IAC5E,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,uDAAuD;AACvD,MAAM,WAAW,oBAAoB;IACnC;;;;OAIG;IACH,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB;;;;OAIG;IACH,OAAO,CAAC,EAAE,mBAAmB,CAAC;CAC/B;AAED;;;;;;;GAOG;AACH,wBAAgB,uBAAuB,CAAC,OAAO,EAAE,mBAAmB,GAAG,MAAM,CAM5E;AAED;;;;;;;GAOG;AACH,wBAAsB,mBAAmB,CACvC,KAAK,EAAE,YAAY,EACnB,IAAI,GAAE;IAAE,QAAQ,CAAC,EAAE,MAAM,CAAA;CAAO,GAC/B,OAAO,CAAC,oBAAoB,CAAC,CA+E/B;AAED,qFAAqF;AACrF,MAAM,WAAW,uBAAuB;IACtC,8EAA8E;IAC9E,OAAO,EAAE,OAAO,CAAC;IACjB,iEAAiE;IACjE,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED;;;;GAIG;AACH,wBAAgB,uBAAuB,CAAC,EAAE,CAAC,EAAE;IAAE,MAAM,CAAC,EAAE,MAAM,OAAO,CAAA;CAAE,GAAG,uBAAuB,CAahG;AAED,oFAAoF;AACpF,MAAM,WAAW,gBAAgB;IAC/B,sEAAsE;IACtE,IAAI,EAAE,YAAY,CAAC,MAAM,CAAC,CAAC;IAC3B,GAAG,EAAE,MAAM,CAAC;IACZ,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,8EAA8E;IAC9E,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB,4EAA4E;IAC5E,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED;;;;;GAKG;AACH,wBAAsB,yBAAyB,CAAC,GAAG,EAAE,gBAAgB,GAAG,OAAO,CAAC,YAAY,GAAG,IAAI,CAAC,CAgBnG;AAED,qEAAqE;AACrE,MAAM,WAAW,kBAAkB;IACjC,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,EAAE,MAAM,CAAC;IACnB,IAAI,EAAE,MAAM,CAAC;CACd;AAYD;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAC/B,IAAI,GAAE;IAAE,QAAQ,CAAC,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAAC,GAAG,CAAC,EAAE,MAAM,CAAA;CAAO,GAChE,kBAAkB,CAuDpB"}