zidane 4.0.2 → 4.1.4

package/dist/index-28otmfLX.d.ts

@@ -0,0 +1,400 @@
+import { It as TurnUsage, _ as ToolDef, c as SkillActivationState, ft as AgentStats, g as ToolContext, n as AgentHooks, pt as ChildRunStats, r as AgentOptions, y as SkillConfig } from "./agent-BoV5Twdl.js";
+import { Hookable } from "hookable";
+
+//#region src/presets/basic.d.ts
+/**
+ * Core tools available in every basic preset (without spawn).
+ *
+ * `edit` and `multi_edit` ship in the basic set because surgical edits are the
+ * default modality for production agents — `write_file` is for full overwrites.
+ * `glob` and `grep` are exported but opt-in: not every agent needs codebase
+ * search, and shipping them by default would force `tool:gate` work onto
+ * consumers that prefer the model to use `shell` + classic Unix tools.
+ */
+declare const basicTools: {
+  shell: ToolDef;
+  readFile: ToolDef;
+  writeFile: ToolDef;
+  listFiles: ToolDef;
+  edit: ToolDef;
+  multiEdit: ToolDef;
+};
+declare const _default: Preset;
+//#endregion
+//#region src/presets/index.d.ts
+/**
+ * A preset is a reusable slice of `AgentOptions` — spread it into `createAgent()`
+ * to configure tools, a default system prompt, aliases, and behavior defaults.
+ *
+ * `provider`, `execution`, `session`, and internal fields are excluded so presets
+ * remain shareable and composable.
+ *
+ * ```ts
+ * import { basic } from 'zidane/presets'
+ * createAgent({ ...basic, provider })
+ * ```
+ */
+type Preset = Omit<Partial<AgentOptions>, 'provider' | 'execution' | 'session' | 'mcpConnector'>;
+/**
+ * Identity helper for type inference when defining a preset.
+ */
+declare function definePreset(config: Preset): Preset;
+//#endregion
+//#region src/stats.d.ts
+/**
+ * Per-model usage rollup produced by {@link statsByModel}.
+ *
+ * `turns` counts the number of `TurnUsage` entries attributed to the model
+ * across the whole tree (parent loop + every recursively-spawned child).
+ * Cache and cost numbers are summed from the same set of turns.
+ */
+interface ModelUsage {
+  input: number;
+  output: number;
+  cost: number;
+  cacheRead: number;
+  cacheCreation: number;
+  turns: number;
+}
+/**
+ * Depth-first walk over the stats tree, returning every `TurnUsage` entry
+ * — parent loop first, then each child subtree in completion order.
+ *
+ * Closes the cache-token aggregation gap: `TurnUsage.cacheRead` /
+ * `cacheCreation` live only on per-turn entries, and the top-level
+ * `AgentStats` deliberately doesn't carry cumulative forms (one source of
+ * truth, no risk of drift). Anything that needs a tree-wide sum walks
+ * through this.
+ */
+declare function flattenTurns(stats: AgentStats): TurnUsage[];
+/**
+ * Group cumulative usage by `TurnUsage.modelId`. Each entry sums the input,
+ * output, cache, cost, and turn-count across every turn the tree attributed
+ * to that model — naturally handling cross-model runs (vision-fallback,
+ * model-shifted subagents, mixed-provider workflows).
+ *
+ * Turns missing `modelId` (mock providers, providers that don't echo a model
+ * id) are bucketed under the literal string `'(unknown)'`.
+ */
+declare function statsByModel(stats: AgentStats): Map<string, ModelUsage>;
+//#endregion
+//#region src/tools/edit.d.ts
+/**
+ * Surgical edit — replace `old_string` with `new_string` in a single file.
+ *
+ * Mirrors Claude Code's `Edit` semantics so models post-trained on Anthropic's
+ * tool surface need no relearning. Fails clearly when `old_string` isn't unique
+ * (unless `replace_all: true`) and when not found, with a nearest-match preview
+ * so the model can recover without a separate `read_file` round-trip.
+ */
+declare const edit: ToolDef;
+//#endregion
+//#region src/tools/glob.d.ts
+declare const glob: ToolDef;
+//#endregion
+//#region src/tools/grep.d.ts
+declare const grep: ToolDef;
+//#endregion
+//#region src/tools/interaction.d.ts
+interface InteractionToolOptions {
+  /** JSON Schema for the request payload the model sends */
+  schema: Record<string, unknown>;
+  /** Tool name (default: 'interaction') */
+  name?: string;
+  /** Tool description shown to the model */
+  description?: string;
+  /** Called when the model invokes this tool. Receives the validated payload and tool context, returns data for the model. */
+  onRequest: (payload: Record<string, unknown>, ctx: ToolContext) => Promise<Record<string, unknown> | string>;
+}
+/**
+ * Create an interaction tool that lets the agent request structured input.
+ *
+ * The model calls this tool with a payload matching the schema.
+ * `onRequest` is called with the payload and should return the response
+ * (string or object) that gets sent back to the model as the tool result.
+ */
+declare function createInteractionTool(options: InteractionToolOptions): ToolDef;
+//#endregion
+//#region src/tools/list-files.d.ts
+declare const listFiles: ToolDef;
+//#endregion
+//#region src/tools/multi-edit.d.ts
+declare const multiEdit: ToolDef;
+//#endregion
+//#region src/tools/read-file.d.ts
+declare const readFile: ToolDef;
+//#endregion
+//#region src/tools/shell.d.ts
+declare const shell: ToolDef;
+//#endregion
+//#region src/tools/skills-read.d.ts
+interface SkillsReadToolOptions {
+  catalog: readonly SkillConfig[];
+  state: SkillActivationState;
+}
+declare function createSkillsReadTool(options: SkillsReadToolOptions): ToolDef;
+//#endregion
+//#region src/tools/skills-run-script.d.ts
+interface SkillsRunScriptToolOptions {
+  catalog: readonly SkillConfig[];
+  state: SkillActivationState;
+  /** Script timeout in milliseconds. Default 60000. */
+  scriptTimeoutMs?: number;
+}
+declare function createSkillsRunScriptTool(options: SkillsRunScriptToolOptions): ToolDef;
+//#endregion
+//#region src/tools/skills-use.d.ts
+interface SkillsUseToolOptions {
+  /** Resolved skills catalog for this run. */
+  catalog: readonly SkillConfig[];
+  /** Per-agent activation state the tool mutates. */
+  state: SkillActivationState;
+  /** Agent hooks — used to fire `skills:activate` on first activation. */
+  hooks: Hookable<AgentHooks>;
+}
+/**
+ * Factory for `skills_use`. Auto-injected into the agent's tool set by the
+ * agent runtime when a non-empty skills catalog is available (unless
+ * `SkillsConfig.tool === false`).
+ *
+ * The tool schema's `name` property is `enum`-constrained to the resolved
+ * catalog so the LLM cannot hallucinate a skill that doesn't exist.
+ */
+declare function createSkillsUseTool(options: SkillsUseToolOptions): ToolDef;
+//#endregion
+//#region src/tools/spawn.d.ts
+interface ChildAgent {
+  id: string;
+  task: string;
+  startedAt: number;
+  /** Subagent depth — 1 for a direct child of a top-level agent. */
+  depth: number;
+}
+interface SpawnToolState {
+  /** Currently running children. */
+  readonly children: ReadonlyMap<string, ChildAgent>;
+  /**
+   * Cumulative stats across every completed direct child of this spawn-tool
+   * instance (returns a copy). Each child's contribution is the cumulative
+   * `AgentStats` returned by its `agent.run()` — so
+   * `totalIn`/`totalOut`/`totalCacheRead`/`totalCacheCreation` cover the
+   * entire subtree (children + grandchildren + …), while `turns` and
+   * `elapsed` stay parent-loop-only per child and are summed across direct
+   * children. `elapsed` over-counts when children ran in parallel.
+   *
+   * Lives across multiple parent runs that share this instance.
+   */
+  readonly totalChildStats: Readonly<AgentStats>;
+}
+interface SpawnToolOptions {
+  /** Maximum concurrent sub-agents (default: 3). */
+  maxConcurrent?: number;
+  /**
+   * Maximum subagent depth. 0 disables spawning entirely; 1 allows top-level
+   * spawns but forbids grandchildren; 3 (default) allows three levels of
+   * recursion — enough for most orchestration patterns, a sharp ceiling
+   * against runaway loops.
+   */
+  maxDepth?: number;
+  /** Child model override. */
+  model?: string;
+  /** Child system prompt override. Per-spawn `input.system` takes precedence. */
+  system?: string;
+  /** Child thinking level. */
+  thinking?: 'off' | 'minimal' | 'low' | 'medium' | 'high';
+  /** Preset override for children. Shallow-merged over the parent's preset (parent fields still win for anything left unset). */
+  preset?: Preset;
+  /**
+   * Per-child timeout, in milliseconds. When the child exceeds it the spawn
+   * tool returns a timeout marker, fires `spawn:error`, and destroys the
+   * child agent. Default: none.
+   */
+  timeoutMs?: number;
+  /**
+   * When `true` and the parent has a session, the child reuses the parent's
+   * session — child turns are appended with the child's own `runId`, and the
+   * resulting `SessionRun` carries `parentRunId` so the tree is
+   * reconstructible. Default: `false` (child is in-memory only).
+   */
+  persist?: boolean;
+  /**
+   * Forward a curated subset of child hook events (`stream:*`, `tool:*`,
+   * `turn:after`) onto the parent's hook bus as `child:*` events. Default:
+   * `true`. Grandchildren bubble through their child transparently.
+   */
+  forwardHooks?: boolean;
+  /** Called when a child agent starts. */
+  onSpawn?: (child: ChildAgent) => void;
+  /** Called when a child agent completes (success, abort, timeout, or error). */
+  onComplete?: (child: ChildAgent, stats: AgentStats, status: NonNullable<ChildRunStats['status']>) => void;
+}
+/**
+ * Create a configured spawn tool.
+ *
+ * State (`children`, `totalChildStats`, counters, active count) is scoped to
+ * the returned instance. Multiple parent agents using the same instance will
+ * share counters + stats + concurrency slots — call `createSpawnTool()` per
+ * agent (or use the stateless default `spawn`) to keep them isolated.
+ */
+declare function createSpawnTool(options?: SpawnToolOptions): ToolDef & SpawnToolState;
+//#endregion
+//#region src/tools/tool-search.d.ts
+interface LazyToolEntry {
+  /**
+   * Wire name (after `toolAliases` rewrite). What the model sees in the
+   * catalog, what `tool_search` matches against, and what the provider's
+   * tool list will carry once the entry is unlocked.
+   */
+  name: string;
+  /**
+   * Canonical (registry-key) name used for unlock-set membership and for the
+   * loop's `ctx.tools[name]` dispatch lookup. Equal to `name` when no alias
+   * is configured for this tool.
+   */
+  canonicalName: string;
+  description: string;
+  inputSchema: Record<string, unknown>;
+  /** Source MCP server, when applicable. Used for `server`-bulk unlock. */
+  server?: string;
+}
+interface ToolSearchToolOptions {
+  /**
+   * Snapshot of every lazy tool the model can discover. Built once per run by
+   * the agent — the tool closes over this array and never mutates it.
+   */
+  catalog: readonly LazyToolEntry[];
+  /**
+   * Mutable per-run set of unlocked **canonical** tool names. The tool adds
+   * matches in place; the loop reads the set when rebuilding the wire-level
+   * tool list. Keyed by canonical (not wire) so dispatch lookups stay
+   * alias-stable.
+   */
+  unlocked: Set<string>;
+  /** Default cap on returned matches when the model omits `limit`. */
+  defaultLimit?: number;
+}
+/**
+ * Factory for `tool_search`. Auto-injected by the agent when
+ * `behavior.toolDisclosure === 'lazy'` and at least one MCP tool is in the
+ * registry. Opt out via `behavior.toolSearch.tool === false`.
+ */
+declare function createToolSearchTool(options: ToolSearchToolOptions): ToolDef;
+//#endregion
+//#region src/tools/validation.d.ts
+/**
+ * Tool argument validation against JSON Schema-style inputSchema.
+ *
+ * Two passes:
+ *   1. Required-field presence. Missing or null/undefined required fields fail.
+ *   2. Top-level type checks with **best-effort coercion**. Small/OSS models
+ *      routinely send `"true"` for a `boolean` field or `"42"` for a `number`,
+ *      and rejecting outright forces a confusing retry. Instead, we auto-heal
+ *      coerce when the conversion is unambiguous, fail only when the value
+ *      cannot be reasonably normalized to any of the declared types.
+ *
+ * Nested validation is intentionally out of scope — keep it cheap and let the
+ * tool's `execute` body assert deeper invariants.
+ */
+interface ValidationResult {
+  valid: boolean;
+  /** Human-readable reason. Present on failure only. */
+  error?: string;
+  /**
+   * Possibly-coerced input. Present iff `valid: true`. Tools should call
+   * `execute(coercedInput, ctx)` so auto-healed values reach the tool body.
+   * When no coercion was applied, this is reference-equal to the input.
+   */
+  coercedInput?: Record<string, unknown>;
+  /**
+   * Names of fields whose values were coerced. Empty when nothing changed.
+   * Useful for telemetry (`validation:reject` on failure already carries the
+   * reason; this is the success-path equivalent).
+   */
+  coercions?: readonly string[];
+}
+declare function validateToolArgs(input: Record<string, unknown>, schema: Record<string, unknown>): ValidationResult;
+//#endregion
+//#region src/tools/write-file.d.ts
+/**
+ * Write a file, with an idempotency signal when the content is unchanged.
+ *
+ * Three return shapes — chosen so the model can recognize a no-op without a
+ * separate read:
+ *   - `Created path (N bytes)` — file did not exist
+ *   - `Updated path (N bytes)` — content differed from on-disk
+ *   - `No change needed: path already at target state (N bytes)` — equal
+ *
+ * Race window: in non-process execution contexts (docker, sandbox) shared by
+ * multiple agents, another writer can mutate the file between our read and
+ * our write. Local process context is single-writer per agent so the race is
+ * a non-issue there. Documented rather than locked because the cost of
+ * cross-context locking outweighs the cost of a stale "No change" message.
+ */
+declare const writeFile: ToolDef;
+//#endregion
+//#region src/tracing.d.ts
+/** Minimal span shape — any tracer that provides these two methods is compatible. */
+interface Span {
+  /** Close the span. Called exactly once per span. */
+  end: () => void;
+  /** Optional: attach additional attributes after the span is started (ignored if unsupported). */
+  setAttributes?: (attrs: Record<string, unknown>) => void;
+}
+/** Function that opens a span. Caller-provided so we stay tracer-agnostic. */
+type StartSpan = (name: string, attrs?: Record<string, unknown>) => Span;
+interface TracingHooksOptions {
+  /** Tracer seam. Receives a span name + attributes; must return a `Span`. */
+  startSpan: StartSpan;
+  /**
+   * Optional attribute namespace. Prepended to every span name (e.g. `"agent"` →
+   * span names like `agent/turn:0`, `agent/tool:Bash`).
+   */
+  namespace?: string;
+}
+/** Value returned by {@link createTracingHooks} — install entrypoint. */
+interface TracingHookSet {
+  /**
+   * Attach every hook handler to the given agent hooks instance.
+   *
+   * @returns an `uninstall` function that detaches every handler and closes any
+   * still-open spans. Safe to call multiple times.
+   */
+  install: (hooks: Hookable<AgentHooks>) => () => void;
+}
+/**
+ * Build a set of tracing hook handlers that can be installed on an agent.
+ *
+ * @example Sentry
+ * ```ts
+ * const tracing = createTracingHooks({
+ *   startSpan: (name, attrs) => Sentry.startInactiveSpan({ name, attributes: attrs }),
+ * })
+ * const uninstall = tracing.install(agent.hooks)
+ * try { await agent.run({ prompt }) }
+ * finally { uninstall() }
+ * ```
+ */
+declare function createTracingHooks(options: TracingHooksOptions): TracingHookSet;
+//#endregion
+//#region src/zod.d.ts
+/**
+ * Zod v4 integration helper.
+ *
+ * Normalizes the output of z.toJsonSchema() for use as ToolSpec.inputSchema.
+ * Zod is an optional peer dependency — consumers call z.toJsonSchema() themselves.
+ *
+ * Usage:
+ *   import { z } from 'zod'
+ *   import { zodToJsonSchema } from 'zidane'
+ *   const schema = zodToJsonSchema(z.toJsonSchema(z.object({ name: z.string() })))
+ */
+/**
+ * Normalize a JSON Schema (e.g. from zod v4's z.toJsonSchema()) for use
+ * as a ToolSpec.inputSchema.
+ *
+ * Strips the $schema key that some providers reject.
+ */
+declare function zodToJsonSchema(jsonSchema: Record<string, unknown>): Record<string, unknown>;
+//#endregion
+export { edit as A, readFile as C, createInteractionTool as D, InteractionToolOptions as E, definePreset as F, _default as I, basicTools as L, flattenTurns as M, statsByModel as N, grep as O, Preset as P, shell as S, listFiles as T, createSkillsUseTool as _, createTracingHooks as a, SkillsReadToolOptions as b, validateToolArgs as c, createToolSearchTool as d, ChildAgent as f, SkillsUseToolOptions as g, createSpawnTool as h, TracingHooksOptions as i, ModelUsage as j, glob as k, LazyToolEntry as l, SpawnToolState as m, Span as n, writeFile as o, SpawnToolOptions as p, TracingHookSet as r, ValidationResult as s, zodToJsonSchema as t, ToolSearchToolOptions as u, SkillsRunScriptToolOptions as v, multiEdit as w, createSkillsReadTool as x, createSkillsRunScriptTool as y };
+//# sourceMappingURL=index-28otmfLX.d.ts.map

package/dist/index-28otmfLX.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index-28otmfLX.d.ts","names":[],"sources":["../src/presets/basic.ts","../src/presets/index.ts","../src/stats.ts","../src/tools/edit.ts","../src/tools/glob.ts","../src/tools/grep.ts","../src/tools/interaction.ts","../src/tools/list-files.ts","../src/tools/multi-edit.ts","../src/tools/read-file.ts","../src/tools/shell.ts","../src/tools/skills-read.ts","../src/tools/skills-run-script.ts","../src/tools/skills-use.ts","../src/tools/spawn.ts","../src/tools/tool-search.ts","../src/tools/validation.ts","../src/tools/write-file.ts","../src/tracing.ts","../src/zod.ts"],"mappings":"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"}

package/dist/index-BfSdALzk.d.ts

@@ -0,0 +1,113 @@
+//#region src/contexts/types.d.ts
+/**
+ * Execution context types.
+ *
+ * An execution context defines *where* and *how* an agent's tools run.
+ * The agent loop and tools interact through this interface without knowing
+ * whether they're running in-process, in a Docker container, or in a
+ * remote sandbox.
+ */
+interface ContextCapabilities {
+  /** Can execute shell commands */
+  shell: boolean;
+  /** Can read/write files in a workspace */
+  filesystem: boolean;
+  /** Can make outbound network requests */
+  network: boolean;
+  /** Has GPU access */
+  gpu: boolean;
+}
+/** Opaque handle to a running execution context instance */
+interface ExecutionHandle {
+  id: string;
+  type: ContextType;
+  /** Working directory within the context */
+  cwd: string;
+}
+interface ExecResult {
+  stdout: string;
+  stderr: string;
+  exitCode: number;
+}
+interface SpawnConfig {
+  /** Working directory (created if it doesn't exist) */
+  cwd?: string;
+  /** Environment variables */
+  env?: Record<string, string>;
+  /** Docker image (only for 'docker' context) */
+  image?: string;
+  /** Resource limits */
+  limits?: {
+    /** Memory limit in MB */memory?: number; /** CPU limit (e.g. '1.0' = 1 core) */
+    cpu?: string; /** Timeout in seconds for the entire context lifetime */
+    timeout?: number;
+  };
+  /** Sandbox provider config (only for 'sandbox' context) */
+  sandbox?: {
+    provider: string;
+    apiKey?: string;
+    [key: string]: unknown;
+  };
+}
+type ContextType = 'process' | 'docker' | 'sandbox';
+interface ExecutionContext {
+  /** Context type identifier */
+  readonly type: ContextType;
+  /** What this context supports */
+  readonly capabilities: ContextCapabilities;
+  /** Spawn a new execution environment */
+  spawn: (config?: SpawnConfig) => Promise<ExecutionHandle>;
+  /** Execute a shell command in the context */
+  exec: (handle: ExecutionHandle, command: string, options?: {
+    cwd?: string;
+    env?: Record<string, string>;
+    timeout?: number;
+  }) => Promise<ExecResult>;
+  /** Read a file from the context's filesystem */
+  readFile: (handle: ExecutionHandle, path: string) => Promise<string>;
+  /**
+   * Read a file from the context's filesystem as raw bytes.
+   *
+   * Used by `read_file` to dispatch image / binary files into the multimodal
+   * `ToolResultContent[]` route. Optional — when not implemented, the tool
+   * falls back to `base64 < path` via the `exec` seam, which works in any
+   * shell-capable context. Implementations that already have a native
+   * binary read (in-process `fs.readFile` without encoding, container API,
+   * sandbox SDK) should override for the latency win.
+   */
+  readFileBinary?: (handle: ExecutionHandle, path: string) => Promise<Uint8Array>;
+  /** Write a file to the context's filesystem */
+  writeFile: (handle: ExecutionHandle, path: string, content: string) => Promise<void>;
+  /** List files in a directory */
+  listFiles: (handle: ExecutionHandle, path: string) => Promise<string[]>;
+  /** Destroy the execution environment and clean up resources */
+  destroy: (handle: ExecutionHandle) => Promise<void>;
+}
+//#endregion
+//#region src/contexts/docker.d.ts
+declare function createDockerContext(config?: SpawnConfig): ExecutionContext;
+//#endregion
+//#region src/contexts/process.d.ts
+declare function createProcessContext(config?: SpawnConfig): ExecutionContext;
+//#endregion
+//#region src/contexts/sandbox.d.ts
+interface SandboxProvider {
+  name: string;
+  spawn: (config: SpawnConfig) => Promise<{
+    id: string;
+    cwd: string;
+  }>;
+  exec: (sandboxId: string, command: string, options?: {
+    cwd?: string;
+    env?: Record<string, string>;
+    timeout?: number;
+  }) => Promise<ExecResult>;
+  readFile: (sandboxId: string, path: string) => Promise<string>;
+  writeFile: (sandboxId: string, path: string, content: string) => Promise<void>;
+  listFiles: (sandboxId: string, path: string) => Promise<string[]>;
+  destroy: (sandboxId: string) => Promise<void>;
+}
+declare function createSandboxContext(provider: SandboxProvider): ExecutionContext;
+//#endregion
+export { ContextCapabilities as a, ExecutionContext as c, createDockerContext as i, ExecutionHandle as l, createSandboxContext as n, ContextType as o, createProcessContext as r, ExecResult as s, SandboxProvider as t, SpawnConfig as u };
+//# sourceMappingURL=index-BfSdALzk.d.ts.map

package/dist/index-BfSdALzk.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index-BfSdALzk.d.ts","names":[],"sources":["../src/contexts/types.ts","../src/contexts/docker.ts","../src/contexts/process.ts","../src/contexts/sandbox.ts"],"mappings":";;AAaA;;;;;;;UAAiB,mBAAA;EAQZ;EANH,KAAA;EAce;EAZf,UAAA;;EAEA,OAAA;EAWA;EATA,GAAA;AAAA;;UAQe,eAAA;EACf,EAAA;EACA,IAAA,EAAM,WAAA;EASmB;EAPzB,GAAA;AAAA;AAAA,UAOe,UAAA;EACf,MAAA;EACA,MAAA;EACA,QAAA;AAAA;AAAA,UAOe,WAAA;EAAW;EAE1B,GAAA;EAEY;EAAZ,GAAA,GAAM,MAAA;EAAN;EAEA,KAAA;EAAA;EAEA,MAAA;IAEE,yBAAA,MAAA,WAIA;IAFA,GAAA,WAMA;IAJA,OAAA;EAAA;EAMY;EAHd,OAAA;IACE,QAAA;IACA,MAAA;IAAA,CACC,GAAA;EAAA;AAAA;AAAA,KAQO,WAAA;AAAA,UAEK,gBAAA;;WAEN,IAAA,EAAM,WAAA;EAGQ;EAAA,SAAd,YAAA,EAAc,mBAAA;EAGkB;EAAzC,KAAA,GAAQ,MAAA,GAAS,WAAA,KAAgB,OAAA,CAAQ,eAAA;EAG1B;EAAf,IAAA,GAAO,MAAA,EAAQ,eAAA,EAAiB,OAAA,UAAiB,OAAA;IAAY,GAAA;IAAc,GAAA,GAAM,MAAA;IAAwB,OAAA;EAAA,MAAuB,OAAA,CAAQ,UAAA;EAe9G;EAZ1B,QAAA,GAAW,MAAA,EAAQ,eAAA,EAAiB,IAAA,aAAiB,OAAA;EAYO;;;;;;;;;;EAA5D,cAAA,IAAkB,MAAA,EAAQ,eAAA,EAAiB,IAAA,aAAiB,OAAA,CAAQ,UAAA;EArB3D;EAwBT,SAAA,GAAY,MAAA,EAAQ,eAAA,EAAiB,IAAA,UAAc,OAAA,aAAoB,OAAA;EArBvE;EAwBA,SAAA,GAAY,MAAA,EAAQ,eAAA,EAAiB,IAAA,aAAiB,OAAA;EAxB9C;EA2BR,OAAA,GAAU,MAAA,EAAQ,eAAA,KAAoB,OAAA;AAAA;;;iBC/FxB,mBAAA,CAAoB,MAAA,GAAS,WAAA,GAAc,gBAAA;;;iBCL3C,oBAAA,CAAqB,MAAA,GAAS,WAAA,GAAc,gBAAA;;;UCF3C,eAAA;EACf,IAAA;EACA,KAAA,GAAQ,MAAA,EAAQ,WAAA,KAAgB,OAAA;IAAU,EAAA;IAAY,GAAA;EAAA;EACtD,IAAA,GAAO,SAAA,UAAmB,OAAA,UAAiB,OAAA;IAAY,GAAA;IAAc,GAAA,GAAM,MAAA;IAAwB,OAAA;EAAA,MAAuB,OAAA,CAAQ,UAAA;EAClI,QAAA,GAAW,SAAA,UAAmB,IAAA,aAAiB,OAAA;EAC/C,SAAA,GAAY,SAAA,UAAmB,IAAA,UAAc,OAAA,aAAoB,OAAA;EACjE,SAAA,GAAY,SAAA,UAAmB,IAAA,aAAiB,OAAA;EAChD,OAAA,GAAU,SAAA,aAAsB,OAAA;AAAA;AAAA,iBAOlB,oBAAA,CAAqB,QAAA,EAAU,eAAA,GAAkB,gBAAA"}