@anthropic-ai/sdk 0.95.2 → 0.97.0

package/tools/agent-toolset/fs-util.mjs

@@ -0,0 +1,151 @@
+/**
+ * Shared, Node-only filesystem helpers for the agent toolset's file tools:
+ * path confinement (symlink-aware), an atomic write, and language-independent
+ * error messages. Kept out of `node.ts` so the tool implementations stay focused
+ * and these helpers can be reused by every file tool.
+ */
+import * as fs from 'node:fs/promises';
+import * as path from 'node:path';
+import { randomUUID } from 'node:crypto';
+import { ToolError } from "../../lib/tools/ToolError.mjs";
+/** Mode for directories the file tools create — not world-writable under a 0 umask. */
+export const DIR_CREATE_MODE = 0o755;
+/** Mode for files the file tools create. */
+export const FILE_CREATE_MODE = 0o644;
+/** `realpath` `p`, or return `p` unchanged when it cannot be resolved. */
+async function realpathOrSelf(p) {
+    try {
+        return await fs.realpath(p);
+    }
+    catch {
+        return p;
+    }
+}
+/**
+ * Fully resolve `abs`: `realpath` the longest existing ancestor and re-append
+ * the rest, but never re-append a component that is itself a symlink — read the
+ * link and continue from its target instead. This handles paths being created
+ * (write/edit) without letting a symlink leaf (e.g. a dangling one pointing
+ * outside a confinement root) slip through unresolved.
+ */
+export async function canonicalize(abs) {
+    const tail = [];
+    let prefix = abs;
+    for (;;) {
+        let real;
+        try {
+            real = await fs.realpath(prefix);
+        }
+        catch {
+            let isLink = false;
+            try {
+                isLink = (await fs.lstat(prefix)).isSymbolicLink();
+            }
+            catch {
+                /* prefix truly doesn't exist (ENOENT) — fall through and walk up */
+            }
+            if (isLink) {
+                // Resolve the symlink ourselves and retry; `tail` (the part below it)
+                // still applies to the link's target.
+                prefix = path.resolve(path.dirname(prefix), await fs.readlink(prefix));
+                continue;
+            }
+            const parent = path.dirname(prefix);
+            if (parent === prefix)
+                return abs; // walked past the FS root without a hit
+            tail.push(path.basename(prefix));
+            prefix = parent;
+            continue;
+        }
+        return tail.length ? path.join(real, ...tail.reverse()) : real;
+    }
+}
+/**
+ * Resolve `p` and confine it to `root`.
+ *
+ * Unless `allowOutside` is set, absolute inputs are rejected and the
+ * **canonical** path is returned — every symlink in `p` (including the leaf,
+ * even a dangling one) is resolved before the confinement check, and the
+ * resolved path is what the caller then operates on, so a symlink inside `root`
+ * that points outside it can neither pass the check nor be followed afterwards.
+ *
+ * Residual TOCTOU: a component could still be swapped for a symlink between this
+ * call and the eventual `fs` operation. Closing that fully needs per-component
+ * `O_NOFOLLOW`/`openat`, which Node does not expose ergonomically; this is why a
+ * sandbox is still recommended for the toolset as a whole.
+ */
+export async function confineToRoot(root, p, opts) {
+    const allowOutside = opts?.allowOutside ?? false;
+    if (path.isAbsolute(p)) {
+        if (!allowOutside) {
+            throw new ToolError(`absolute path ${JSON.stringify(p)} not permitted`);
+        }
+        return path.resolve(p);
+    }
+    const realRoot = await realpathOrSelf(path.resolve(root));
+    const abs = path.resolve(realRoot, p);
+    if (allowOutside)
+        return abs;
+    const real = await canonicalize(abs);
+    const rootSep = realRoot.endsWith(path.sep) ? realRoot : realRoot + path.sep;
+    if (real !== realRoot && !real.startsWith(rootSep)) {
+        throw new ToolError(`path ${JSON.stringify(p)} escapes workdir`);
+    }
+    return real;
+}
+/**
+ * Atomically write `content` to `targetPath`: write a sibling temp file, fsync
+ * it, then rename over the target. The rename is atomic on most filesystems, so
+ * a crash mid-write never leaves the target half-written.
+ */
+export async function atomicWriteFile(targetPath, content) {
+    const dir = path.dirname(targetPath);
+    const tempPath = path.join(dir, `.tmp-${process.pid}-${randomUUID()}`);
+    let handle;
+    try {
+        handle = await fs.open(tempPath, 'wx', FILE_CREATE_MODE);
+        await handle.writeFile(content, 'utf-8');
+        await handle.sync();
+        await handle.close();
+        handle = undefined;
+        await fs.rename(tempPath, targetPath);
+    }
+    catch (err) {
+        if (handle)
+            await handle.close().catch(() => { });
+        await fs.unlink(tempPath).catch(() => { });
+        throw err;
+    }
+}
+/**
+ * Map a thrown filesystem error to a consistent, language-independent message,
+ * so the model sees the same wording regardless of the runtime (Node's raw
+ * `ENOENT: no such file...` text would otherwise leak through). Falls back to
+ * the raw error message for codes we don't special-case.
+ */
+export function fsErrorMessage(err, file) {
+    const code = err?.code;
+    switch (code) {
+        case 'ENOENT':
+            return `${file}: no such file or directory`;
+        case 'EACCES':
+        case 'EPERM':
+            return `${file}: permission denied`;
+        case 'ENOTDIR':
+            return `${file}: not a directory`;
+        case 'EISDIR':
+            return `${file}: is a directory`;
+        case 'ELOOP':
+            return `${file}: too many levels of symbolic links`;
+        case 'ENAMETOOLONG':
+            return `${file}: file name too long`;
+        case 'ENOSPC':
+            return `${file}: no space left on device`;
+        case 'EMFILE':
+        case 'ENFILE':
+            return `${file}: too many open files`;
+        default:
+            return `${file}: ${err instanceof Error ? err.message : String(err)}`;
+    }
+}
+//# sourceMappingURL=fs-util.mjs.map

package/tools/agent-toolset/fs-util.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"fs-util.mjs","sourceRoot":"","sources":["../../src/tools/agent-toolset/fs-util.ts"],"names":[],"mappings":"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"}

package/tools/agent-toolset/node.d.mts

@@ -0,0 +1,139 @@
+/**
+ * Node implementation of the `agent_toolset_20260401` tools — `bash`, `read`,
+ * `write`, `edit`, `glob`, `grep` — plus the workdir/skills
+ * {@link AgentToolContext}.
+ *
+ * This mirrors `@anthropic-ai/sdk/tools/memory/node`: it is the explicit,
+ * Node-only entry point for these implementations. Importing it pulls in
+ * `node:child_process`, `node:fs`, etc., so it is kept separate from the rest of
+ * the SDK — depending on it is an opt-in.
+ *
+ * **Node 22+ is required** for this module: the `glob` tool uses the native
+ * `fs.glob`, added in Node 22. The rest of the SDK still supports Node 18+; only
+ * the agent toolset has this requirement.
+ *
+ * The result of {@link betaAgentToolset20260401} is a plain `BetaRunnableTool[]`;
+ * hand it to any tool runner — `client.beta.messages.toolRunner({ …, tools })`
+ * for the Messages API, or `client.beta.sessions.events.toolRunner({ …, tools })`
+ * for a managed-agents session:
+ *
+ * ```ts
+ * import { betaAgentToolset20260401 } from '@anthropic-ai/sdk/tools/agent-toolset/node';
+ *
+ * const tools = betaAgentToolset20260401({ workdir: '/work' });
+ * const tools2 = betaAgentToolset20260401({ workdir: '/work' }).filter((t) => t.name !== 'bash');
+ * ```
+ *
+ * Trust model: the file tools confine to `workdir` (symlink-aware) and are safe
+ * without a sandbox; `bash` is unrestricted and should run inside one. See
+ * {@link AgentToolContext}.
+ */
+import type { Anthropic } from "../../client.mjs";
+import type { BetaRunnableTool } from "../../lib/tools/BetaRunnableTool.mjs";
+export { setupSkills, resolveSkillVersion, extractSkillArchive } from "./skills.mjs";
+/**
+ * Workdir + path-policy for the agent toolset.
+ *
+ * Trust model — two tiers:
+ *
+ * - The file tools ({@link betaReadTool}, {@link betaWriteTool},
+ *   {@link betaEditTool}, {@link betaGlobTool}, {@link betaGrepTool}) confine to
+ *   `workdir` unless `unrestrictedPaths` is set. {@link resolvePath}
+ *   canonicalizes the target (resolving every symlink, including the leaf)
+ *   before the check *and* returns that canonical path for the operation, so a
+ *   symlink inside the workdir that points outside it neither passes the check
+ *   nor gets followed afterwards — this is a real boundary, not a lexical hint
+ *   (modulo the residual TOCTOU noted on {@link resolvePath}).
+ * - {@link betaBashTool} runs an unrestricted `/bin/bash` and cannot be
+ *   confined. Run it — and, for defense in depth, the whole toolset — inside a
+ *   sandbox the host controls (e.g. a self-hosted environment runner).
+ */
+export interface AgentToolContext {
+    /** Base directory for resolving relative tool paths. */
+    workdir: string;
+    /**
+     * When `false` (default), the file tools reject absolute paths and paths
+     * that escape `workdir` (symlinks resolved). Does **not** constrain
+     * {@link betaBashTool}.
+     */
+    unrestrictedPaths?: boolean;
+    /**
+     * Anthropic client. Optional — the bare toolset needs no client; it is only
+     * used by `setupSkills`, which (together with {@link AgentToolContext.sessionId})
+     * fetches the session's resolved agent and downloads each of its skills into
+     * `{workdir}/skills/<name>/`.
+     */
+    client?: Anthropic;
+    /** Session whose agent's skills `setupSkills` should download. */
+    sessionId?: string;
+    /**
+     * Optional environment for the bash subprocess. When unset, the bash tool
+     * inherits the process environment with the runner's `ANTHROPIC_*`
+     * credentials scrubbed. When provided, it FULLY REPLACES that default
+     * environment — the mapping is used verbatim and is NOT merged with or added
+     * to the scrubbed process environment. To keep the defaults plus extra vars,
+     * build the combined mapping yourself before passing it.
+     */
+    env?: NodeJS.ProcessEnv;
+}
+/**
+ * Returns the `agent_toolset_20260401` implementations bound to `ctx`. The
+ * result is a plain array of `BetaRunnableTool`; filter or extend it before
+ * handing it to a tool runner:
+ *
+ * ```ts
+ * const tools = [...betaAgentToolset20260401(ctx), myCustomTool];
+ * const tools = betaAgentToolset20260401(ctx).filter((t) => t.name !== 'grep');
+ * ```
+ *
+ * Concurrency note: `client.beta.sessions.events.toolRunner` dispatches a
+ * session's tool calls serially (the sessions API delivers one `agent.tool_use`
+ * at a time). `client.beta.messages.toolRunner` runs a turn's `tool.run` calls
+ * via `Promise.all`. The toolset below is safe under either model —
+ * {@link betaBashTool} serializes its persistent shell internally and the FS
+ * tools are independent per call — but {@link betaEditTool}/{@link betaWriteTool}
+ * cannot synchronize concurrent writes to the *same* file across processes, so a
+ * multi-edit turn touching one path is still subject to inherent FS lost-update
+ * races. Custom tools that close over mutable state should do their own queueing.
+ */
+export declare function betaAgentToolset20260401(ctx: AgentToolContext): BetaRunnableTool[];
+/**
+ * Resolve `p` relative to `ctx.workdir`. Unless `unrestrictedPaths` is set,
+ * absolute inputs are rejected and the **canonical** path is returned — every
+ * symlink in `p` (including the leaf, even a dangling one) is resolved before
+ * the workdir check, and the resolved path is what the tool then operates on, so
+ * a symlink inside the workdir that points outside it can neither pass the check
+ * nor be followed afterwards. See the trust model on {@link AgentToolContext}.
+ *
+ * Residual TOCTOU: a component could still be swapped for a symlink between this
+ * call and the eventual `fs` operation. Closing that fully needs per-component
+ * `O_NOFOLLOW`/`openat`, which Node does not expose ergonomically; the same
+ * residual exposure exists in `tools/memory/node` and is why a sandbox is still
+ * recommended for the toolset as a whole.
+ */
+export declare function resolvePath(ctx: AgentToolContext, p: string): Promise<string>;
+/**
+ * A persistent /bin/bash process. State (cwd, env, background jobs) survives
+ * across exec() calls. Uses pipes rather than a PTY so input is never echoed.
+ */
+export declare class BashSession {
+    #private;
+    constructor(dir: string, env?: NodeJS.ProcessEnv);
+    /** Whether the underlying shell process has exited. */
+    get closed(): boolean;
+    exec(command: string, opts?: {
+        timeoutMs?: number;
+        signal?: AbortSignal | null | undefined;
+    }): Promise<{
+        output: string;
+        exitCode: number;
+    }>;
+    close(): void;
+}
+export declare function betaBashTool(ctx: AgentToolContext): BetaRunnableTool;
+export declare function betaReadTool(ctx: AgentToolContext): BetaRunnableTool;
+export declare function betaWriteTool(ctx: AgentToolContext): BetaRunnableTool;
+export declare function betaEditTool(ctx: AgentToolContext): BetaRunnableTool;
+export declare function betaGlobTool(ctx: AgentToolContext): BetaRunnableTool;
+export declare function betaGrepTool(ctx: AgentToolContext): BetaRunnableTool;
+//# sourceMappingURL=node.d.mts.map

package/tools/agent-toolset/node.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"node.d.mts","sourceRoot":"","sources":["../../src/tools/agent-toolset/node.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AAQH,OAAO,KAAK,EAAE,SAAS,EAAE,yBAAqB;AAE9C,OAAO,KAAK,EAAE,gBAAgB,EAAE,6CAAyC;AAMzE,OAAO,EAAE,WAAW,EAAE,mBAAmB,EAAE,mBAAmB,EAAE,qBAAiB;AA6BjF;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,WAAW,gBAAgB;IAC/B,wDAAwD;IACxD,OAAO,EAAE,MAAM,CAAC;IAChB;;;;OAIG;IACH,iBAAiB,CAAC,EAAE,OAAO,CAAC;IAC5B;;;;;OAKG;IACH,MAAM,CAAC,EAAE,SAAS,CAAC;IACnB,kEAAkE;IAClE,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;;;;;;;OAOG;IACH,GAAG,CAAC,EAAE,MAAM,CAAC,UAAU,CAAC;CACzB;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,wBAAwB,CAAC,GAAG,EAAE,gBAAgB,GAAG,gBAAgB,EAAE,CASlF;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,WAAW,CAAC,GAAG,EAAE,gBAAgB,EAAE,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAE7E;AA0BD;;;GAGG;AACH,qBAAa,WAAW;;gBASV,GAAG,EAAE,MAAM,EAAE,GAAG,GAAE,MAAM,CAAC,UAA+B;IAyBpE,uDAAuD;IACvD,IAAI,MAAM,IAAI,OAAO,CAEpB;IAkBK,IAAI,CACR,OAAO,EAAE,MAAM,EACf,IAAI,GAAE;QAAE,SAAS,CAAC,EAAE,MAAM,CAAC;QAAC,MAAM,CAAC,EAAE,WAAW,GAAG,IAAI,GAAG,SAAS,CAAA;KAAO,GACzE,OAAO,CAAC;QAAE,MAAM,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAA;KAAE,CAAC;IAkEhD,KAAK,IAAI,IAAI;CAkBd;AAED,wBAAgB,YAAY,CAAC,GAAG,EAAE,gBAAgB,GAAG,gBAAgB,CAgEpE;AAID,wBAAgB,YAAY,CAAC,GAAG,EAAE,gBAAgB,GAAG,gBAAgB,CAgDpE;AAED,wBAAgB,aAAa,CAAC,GAAG,EAAE,gBAAgB,GAAG,gBAAgB,CAqBrE;AAED,wBAAgB,YAAY,CAAC,GAAG,EAAE,gBAAgB,GAAG,gBAAgB,CA6DpE;AAID,wBAAgB,YAAY,CAAC,GAAG,EAAE,gBAAgB,GAAG,gBAAgB,CAgEpE;AAED,wBAAgB,YAAY,CAAC,GAAG,EAAE,gBAAgB,GAAG,gBAAgB,CAmBpE"}

package/tools/agent-toolset/node.d.ts

@@ -0,0 +1,139 @@
+/**
+ * Node implementation of the `agent_toolset_20260401` tools — `bash`, `read`,
+ * `write`, `edit`, `glob`, `grep` — plus the workdir/skills
+ * {@link AgentToolContext}.
+ *
+ * This mirrors `@anthropic-ai/sdk/tools/memory/node`: it is the explicit,
+ * Node-only entry point for these implementations. Importing it pulls in
+ * `node:child_process`, `node:fs`, etc., so it is kept separate from the rest of
+ * the SDK — depending on it is an opt-in.
+ *
+ * **Node 22+ is required** for this module: the `glob` tool uses the native
+ * `fs.glob`, added in Node 22. The rest of the SDK still supports Node 18+; only
+ * the agent toolset has this requirement.
+ *
+ * The result of {@link betaAgentToolset20260401} is a plain `BetaRunnableTool[]`;
+ * hand it to any tool runner — `client.beta.messages.toolRunner({ …, tools })`
+ * for the Messages API, or `client.beta.sessions.events.toolRunner({ …, tools })`
+ * for a managed-agents session:
+ *
+ * ```ts
+ * import { betaAgentToolset20260401 } from '@anthropic-ai/sdk/tools/agent-toolset/node';
+ *
+ * const tools = betaAgentToolset20260401({ workdir: '/work' });
+ * const tools2 = betaAgentToolset20260401({ workdir: '/work' }).filter((t) => t.name !== 'bash');
+ * ```
+ *
+ * Trust model: the file tools confine to `workdir` (symlink-aware) and are safe
+ * without a sandbox; `bash` is unrestricted and should run inside one. See
+ * {@link AgentToolContext}.
+ */
+import type { Anthropic } from "../../client.js";
+import type { BetaRunnableTool } from "../../lib/tools/BetaRunnableTool.js";
+export { setupSkills, resolveSkillVersion, extractSkillArchive } from "./skills.js";
+/**
+ * Workdir + path-policy for the agent toolset.
+ *
+ * Trust model — two tiers:
+ *
+ * - The file tools ({@link betaReadTool}, {@link betaWriteTool},
+ *   {@link betaEditTool}, {@link betaGlobTool}, {@link betaGrepTool}) confine to
+ *   `workdir` unless `unrestrictedPaths` is set. {@link resolvePath}
+ *   canonicalizes the target (resolving every symlink, including the leaf)
+ *   before the check *and* returns that canonical path for the operation, so a
+ *   symlink inside the workdir that points outside it neither passes the check
+ *   nor gets followed afterwards — this is a real boundary, not a lexical hint
+ *   (modulo the residual TOCTOU noted on {@link resolvePath}).
+ * - {@link betaBashTool} runs an unrestricted `/bin/bash` and cannot be
+ *   confined. Run it — and, for defense in depth, the whole toolset — inside a
+ *   sandbox the host controls (e.g. a self-hosted environment runner).
+ */
+export interface AgentToolContext {
+    /** Base directory for resolving relative tool paths. */
+    workdir: string;
+    /**
+     * When `false` (default), the file tools reject absolute paths and paths
+     * that escape `workdir` (symlinks resolved). Does **not** constrain
+     * {@link betaBashTool}.
+     */
+    unrestrictedPaths?: boolean;
+    /**
+     * Anthropic client. Optional — the bare toolset needs no client; it is only
+     * used by `setupSkills`, which (together with {@link AgentToolContext.sessionId})
+     * fetches the session's resolved agent and downloads each of its skills into
+     * `{workdir}/skills/<name>/`.
+     */
+    client?: Anthropic;
+    /** Session whose agent's skills `setupSkills` should download. */
+    sessionId?: string;
+    /**
+     * Optional environment for the bash subprocess. When unset, the bash tool
+     * inherits the process environment with the runner's `ANTHROPIC_*`
+     * credentials scrubbed. When provided, it FULLY REPLACES that default
+     * environment — the mapping is used verbatim and is NOT merged with or added
+     * to the scrubbed process environment. To keep the defaults plus extra vars,
+     * build the combined mapping yourself before passing it.
+     */
+    env?: NodeJS.ProcessEnv;
+}
+/**
+ * Returns the `agent_toolset_20260401` implementations bound to `ctx`. The
+ * result is a plain array of `BetaRunnableTool`; filter or extend it before
+ * handing it to a tool runner:
+ *
+ * ```ts
+ * const tools = [...betaAgentToolset20260401(ctx), myCustomTool];
+ * const tools = betaAgentToolset20260401(ctx).filter((t) => t.name !== 'grep');
+ * ```
+ *
+ * Concurrency note: `client.beta.sessions.events.toolRunner` dispatches a
+ * session's tool calls serially (the sessions API delivers one `agent.tool_use`
+ * at a time). `client.beta.messages.toolRunner` runs a turn's `tool.run` calls
+ * via `Promise.all`. The toolset below is safe under either model —
+ * {@link betaBashTool} serializes its persistent shell internally and the FS
+ * tools are independent per call — but {@link betaEditTool}/{@link betaWriteTool}
+ * cannot synchronize concurrent writes to the *same* file across processes, so a
+ * multi-edit turn touching one path is still subject to inherent FS lost-update
+ * races. Custom tools that close over mutable state should do their own queueing.
+ */
+export declare function betaAgentToolset20260401(ctx: AgentToolContext): BetaRunnableTool[];
+/**
+ * Resolve `p` relative to `ctx.workdir`. Unless `unrestrictedPaths` is set,
+ * absolute inputs are rejected and the **canonical** path is returned — every
+ * symlink in `p` (including the leaf, even a dangling one) is resolved before
+ * the workdir check, and the resolved path is what the tool then operates on, so
+ * a symlink inside the workdir that points outside it can neither pass the check
+ * nor be followed afterwards. See the trust model on {@link AgentToolContext}.
+ *
+ * Residual TOCTOU: a component could still be swapped for a symlink between this
+ * call and the eventual `fs` operation. Closing that fully needs per-component
+ * `O_NOFOLLOW`/`openat`, which Node does not expose ergonomically; the same
+ * residual exposure exists in `tools/memory/node` and is why a sandbox is still
+ * recommended for the toolset as a whole.
+ */
+export declare function resolvePath(ctx: AgentToolContext, p: string): Promise<string>;
+/**
+ * A persistent /bin/bash process. State (cwd, env, background jobs) survives
+ * across exec() calls. Uses pipes rather than a PTY so input is never echoed.
+ */
+export declare class BashSession {
+    #private;
+    constructor(dir: string, env?: NodeJS.ProcessEnv);
+    /** Whether the underlying shell process has exited. */
+    get closed(): boolean;
+    exec(command: string, opts?: {
+        timeoutMs?: number;
+        signal?: AbortSignal | null | undefined;
+    }): Promise<{
+        output: string;
+        exitCode: number;
+    }>;
+    close(): void;
+}
+export declare function betaBashTool(ctx: AgentToolContext): BetaRunnableTool;
+export declare function betaReadTool(ctx: AgentToolContext): BetaRunnableTool;
+export declare function betaWriteTool(ctx: AgentToolContext): BetaRunnableTool;
+export declare function betaEditTool(ctx: AgentToolContext): BetaRunnableTool;
+export declare function betaGlobTool(ctx: AgentToolContext): BetaRunnableTool;
+export declare function betaGrepTool(ctx: AgentToolContext): BetaRunnableTool;
+//# sourceMappingURL=node.d.ts.map

package/tools/agent-toolset/node.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"node.d.ts","sourceRoot":"","sources":["../../src/tools/agent-toolset/node.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AAQH,OAAO,KAAK,EAAE,SAAS,EAAE,wBAAqB;AAE9C,OAAO,KAAK,EAAE,gBAAgB,EAAE,4CAAyC;AAMzE,OAAO,EAAE,WAAW,EAAE,mBAAmB,EAAE,mBAAmB,EAAE,oBAAiB;AA6BjF;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,WAAW,gBAAgB;IAC/B,wDAAwD;IACxD,OAAO,EAAE,MAAM,CAAC;IAChB;;;;OAIG;IACH,iBAAiB,CAAC,EAAE,OAAO,CAAC;IAC5B;;;;;OAKG;IACH,MAAM,CAAC,EAAE,SAAS,CAAC;IACnB,kEAAkE;IAClE,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;;;;;;;OAOG;IACH,GAAG,CAAC,EAAE,MAAM,CAAC,UAAU,CAAC;CACzB;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,wBAAwB,CAAC,GAAG,EAAE,gBAAgB,GAAG,gBAAgB,EAAE,CASlF;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,WAAW,CAAC,GAAG,EAAE,gBAAgB,EAAE,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAE7E;AA0BD;;;GAGG;AACH,qBAAa,WAAW;;gBASV,GAAG,EAAE,MAAM,EAAE,GAAG,GAAE,MAAM,CAAC,UAA+B;IAyBpE,uDAAuD;IACvD,IAAI,MAAM,IAAI,OAAO,CAEpB;IAkBK,IAAI,CACR,OAAO,EAAE,MAAM,EACf,IAAI,GAAE;QAAE,SAAS,CAAC,EAAE,MAAM,CAAC;QAAC,MAAM,CAAC,EAAE,WAAW,GAAG,IAAI,GAAG,SAAS,CAAA;KAAO,GACzE,OAAO,CAAC;QAAE,MAAM,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAA;KAAE,CAAC;IAkEhD,KAAK,IAAI,IAAI;CAkBd;AAED,wBAAgB,YAAY,CAAC,GAAG,EAAE,gBAAgB,GAAG,gBAAgB,CAgEpE;AAID,wBAAgB,YAAY,CAAC,GAAG,EAAE,gBAAgB,GAAG,gBAAgB,CAgDpE;AAED,wBAAgB,aAAa,CAAC,GAAG,EAAE,gBAAgB,GAAG,gBAAgB,CAqBrE;AAED,wBAAgB,YAAY,CAAC,GAAG,EAAE,gBAAgB,GAAG,gBAAgB,CA6DpE;AAID,wBAAgB,YAAY,CAAC,GAAG,EAAE,gBAAgB,GAAG,gBAAgB,CAgEpE;AAED,wBAAgB,YAAY,CAAC,GAAG,EAAE,gBAAgB,GAAG,gBAAgB,CAmBpE"}