@sema-ai/core 1.275.1

package/dist/core/tool-errors.js

@@ -0,0 +1,194 @@
+import { Value } from "typebox/value";
+/**
+ * Tool-error formatting (design/64 §11, ported from CC's `utils/toolErrors.ts`). A weak model self-corrects
+ * far better from a structured error (exit code + stderr + stdout, or a readable "required parameter X is
+ * missing") than from a raw `error.message` or a Zod stack. Lives in OUR src and is applied at the tool /
+ * adapter layer (the vendored loop passes a thrown tool error's `.message` straight through), so the loop
+ * is untouched.
+ */
+/** Truncation budget for an error string (CC `formatError`: 10000 = 5000 head + marker + 5000 tail). */
+const MAX_ERROR_CHARS = 10_000;
+const HALF = MAX_ERROR_CHARS / 2;
+/** Truncate a long error to head + "[N characters truncated]" + tail (design/64 §11.2, CC parity). */
+export function truncateError(s) {
+    if (s.length <= MAX_ERROR_CHARS)
+        return s;
+    const removed = s.length - MAX_ERROR_CHARS;
+    // Marker matches CC `toolErrors.ts:18-21` verbatim: "\n\n... [N characters truncated] ...\n\n".
+    return `${s.slice(0, HALF)}\n\n... [${removed} characters truncated] ...\n\n${s.slice(s.length - HALF)}`;
+}
+function isShellLike(e) {
+    return typeof e === "object" && e !== null && ("exitCode" in e || "stderr" in e || "stdout" in e);
+}
+/**
+ * Format a thrown tool error into model-facing text (design/64 §11.1/§11.2): a shell/exec error becomes
+ * `Exit code N` + stderr + stdout; a plain Error becomes its message (+ any captured streams); anything
+ * else is stringified. The result is truncated to {@link MAX_ERROR_CHARS}. An AbortError is reported as an
+ * interruption.
+ */
+export function formatToolError(error) {
+    if (error instanceof Error && error.name === "AbortError")
+        return "Interrupted";
+    const parts = [];
+    if (isShellLike(error)) {
+        if (typeof error.exitCode === "number")
+            parts.push(`Exit code ${error.exitCode}`);
+        if (error instanceof Error && error.message)
+            parts.push(error.message);
+        if (error.stderr && error.stderr.trim())
+            parts.push(error.stderr);
+        if (error.stdout && error.stdout.trim())
+            parts.push(error.stdout);
+    }
+    else if (error instanceof Error) {
+        parts.push(error.message || error.name || "Error");
+    }
+    else {
+        parts.push(String(error));
+    }
+    return truncateError(parts.join("\n").trim() || "Error");
+}
+/** The flat (non-dotted) 1.36 brain error codes (brain/errors.ts `BRAIN_ERROR_CODES`). Kept as a literal
+ *  Set here — `tool-errors.ts` is a leaf util and must not import the brain layer — but the values are
+ *  asserted to match the brain enum by a unit test, so the two can't silently diverge. */
+const BRAIN_FLAT_CODES = new Set([
+    "auth",
+    "rate_limit",
+    "invalid_request",
+    "server",
+    "network",
+    "http",
+]);
+/** The dotted-namespace prefix → class map (1.37+ terminal codes). Order-independent (each prefix is unique). */
+const DOTTED_PREFIX_CLASS = [
+    ["budget.", "budget"],
+    ["limit.", "limit"],
+    ["output.", "output"],
+    ["suspend.", "suspend"],
+    ["review.", "review"],
+    ["unexpected.", "unexpected"],
+    ["oracle.", "oracle"],
+    ["resume.", "resume"],
+    ["config.", "config"],
+];
+/**
+ * Fold a {@link "../core/types.js".TaskResult}.`errorCode` into its typed {@link WorkerErrorClass} (design/80
+ * D-G). PURE and DERIVED — it reads an existing code, never produces or changes one; an unknown / missing
+ * code folds to `"unknown"` (never throws). Replaces scattered `errorCode.startsWith("budget.")` consumer
+ * code with one tested folder so the class taxonomy lives in exactly one place.
+ *
+ * SCOPE: this folds a TERMINAL `TaskResult.errorCode` only — i.e. every OUR dotted prefix that the runner can
+ * assemble into a failed task outcome (`budget.`/`limit.`/`output.`/`suspend.`/`review.`/`unexpected.`/
+ * `oracle.`/`resume.`/`config.`) plus the flat 1.36 codes. Operation-level dotted codes that are surfaced to
+ * a *caller* and never become a task outcome are deliberately OUT of scope: `steering.*`
+ * (`steering.not_running`/`steering.invalid_content`, rejected to the `steer()` caller) and `mcp.*`
+ * (`mcp.server_unavailable`, an `onWarn` warning code) — neither reaches `TaskResult.errorCode`, so a caller
+ * will never pass them here. A genuinely unmapped code → `"unknown"` (which therefore means "known-but-foreign
+ * or no code", e.g. a leaked fs/Node code, NOT "an OUR terminal class we forgot to add").
+ */
+export function errorClassOf(errorCode) {
+    if (!errorCode)
+        return "unknown";
+    for (const [prefix, cls] of DOTTED_PREFIX_CLASS) {
+        if (errorCode.startsWith(prefix))
+            return cls;
+    }
+    if (errorCode === "conflict")
+        return "conflict";
+    if (errorCode === "aborted")
+        return "aborted";
+    if (BRAIN_FLAT_CODES.has(errorCode))
+        return "brain";
+    return "unknown";
+}
+/**
+ * Convert a TypeBox/JSON-Schema error path (`/todos/0/activeForm`) into a readable accessor
+ * (`todos[0].activeForm`), CC `formatValidationPath` parity. Numeric segments become `[i]`, named
+ * segments become `.name`. Empty path → "" (the root object).
+ */
+export function formatValidationPath(path) {
+    const segs = path.split("/").filter((s) => s.length > 0);
+    let out = "";
+    for (const seg of segs) {
+        if (/^\d+$/.test(seg))
+            out += `[${seg}]`;
+        else
+            out += out === "" ? seg : `.${seg}`;
+    }
+    return out;
+}
+/**
+ * Recurse into a failing property to find the precise (possibly nested) offending accessor + its expected
+ * type. Needed because this TypeBox build's `Value.Errors` carries NO path (P-19) — so a wrong nested
+ * element (e.g. `questions[0].options`) was mis-blamed on its valid parent array. Emits parameter names +
+ * indices only — never an absolute path / stack / fs context (§16.4 leak-free).
+ */
+function locateInvalidParam(schema, value, prefix) {
+    const s = schema;
+    if (s.type === "object" && s.properties && value !== null && typeof value === "object" && !Array.isArray(value)) {
+        const obj = value;
+        for (const name of s.required ?? []) {
+            if (!(name in obj))
+                return { accessor: prefix ? `${prefix}.${name}` : name, missing: true };
+        }
+        for (const [name, sub] of Object.entries(s.properties)) {
+            if (name in obj && !Value.Check(sub, obj[name])) {
+                return locateInvalidParam(sub, obj[name], prefix ? `${prefix}.${name}` : name);
+            }
+        }
+    }
+    else if (s.type === "array" && s.items && Array.isArray(value)) {
+        for (let i = 0; i < value.length; i++) {
+            if (!Value.Check(s.items, value[i]))
+                return locateInvalidParam(s.items, value[i], `${prefix}[${i}]`);
+        }
+        // Every element is valid, yet the array node fails → a COUNT constraint (minItems/maxItems, e.g. the
+        // AskUserQuestion 1-4 questions / 2-4 options bounds). "expected array" would be actively misleading
+        // (the model DID pass an array) — name the bound so the model can correct the call.
+        const a = s;
+        if (typeof a.minItems === "number" && value.length < a.minItems) {
+            const bound = typeof a.maxItems === "number" ? `between ${a.minItems} and ${a.maxItems}` : `at least ${a.minItems}`;
+            return { accessor: prefix, type: `an array with ${bound} items (got ${value.length})` };
+        }
+        if (typeof a.maxItems === "number" && value.length > a.maxItems) {
+            const bound = typeof a.minItems === "number" ? `between ${a.minItems} and ${a.maxItems}` : `at most ${a.maxItems}`;
+            return { accessor: prefix, type: `an array with ${bound} items (got ${value.length})` };
+        }
+    }
+    // Leaf (or no deeper structure matched) — this node is the failure.
+    return { accessor: prefix, type: s.type };
+}
+/**
+ * Turn a schema-validation failure into a human-readable message (design/64 §11.3 / §16.4). Reports the
+ * parameter NAME + the expected type only — never an absolute path, stack trace, or filesystem context, so
+ * a validation message can't leak internals (§16.4). Examples:
+ *   - "The required parameter `todos` is missing."
+ *   - "The parameter `questions[0].options` is invalid: Expected array."
+ */
+export function formatZodValidationError(schema, value) {
+    // Walk an object schema ourselves to name the offending parameter precisely — this TypeBox build's
+    // `Value.Errors` yields AJV-style messages without a path. We only ever emit a parameter NAME + the
+    // expected type, never an internal path/stack/filesystem context (§16.4).
+    const s = schema;
+    if (s.type === "object" && s.properties && typeof value === "object" && value !== null) {
+        const obj = value;
+        for (const name of s.required ?? []) {
+            if (!(name in obj))
+                return `The required parameter \`${name}\` is missing.`;
+        }
+        for (const [name, sub] of Object.entries(s.properties)) {
+            if (name in obj && !Value.Check(sub, obj[name])) {
+                // Recurse to the precise nested accessor instead of blaming the (valid) parent property (P-19).
+                const loc = locateInvalidParam(sub, obj[name], name);
+                if (loc.missing)
+                    return `The required parameter \`${loc.accessor}\` is missing.`;
+                return `The parameter \`${loc.accessor}\` is invalid${loc.type ? `: expected ${loc.type}` : ""}.`;
+            }
+        }
+    }
+    // Fallback for non-object schemas: the first validator message (still leak-free — no path/stack).
+    const errs = [...Value.Errors(schema, value)];
+    const msg = errs[0]?.message?.trim();
+    return msg ? `Invalid arguments: ${msg}.` : "The arguments do not match the tool's parameter schema.";
+}
+//# sourceMappingURL=tool-errors.js.map

package/dist/core/tool-errors.js.map

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

package/dist/core/tool-name-aliases.d.ts

@@ -0,0 +1,5 @@
+export declare const TOMBSTONED_TOOLS: Readonly<Record<string, string>>;
+/** Map a possibly-pre-Q6/batch-A/① persisted tool name to its current canonical (CC) name; identity for an
+ *  already-canonical name. One-way old→new; safe to call on any tool name before a live-roster/effects lookup. */
+export declare function canonicalToolName(name: string): string;
+//# sourceMappingURL=tool-name-aliases.d.ts.map

package/dist/core/tool-name-aliases.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tool-name-aliases.d.ts","sourceRoot":"","sources":["../../src/core/tool-name-aliases.ts"],"names":[],"mappings":"AA+FA,eAAO,MAAM,gBAAgB,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAgB7D,CAAC;AAgBF;kHACkH;AAClH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAItD"}

package/dist/core/tool-name-aliases.js

@@ -0,0 +1,130 @@
+/**
+ * design/102 §3.6 (Q6 CC-name rename) — migration shim for PERSISTED tool names. The model-facing tool names were
+ * renamed to the CC set (read_file→Read, edit_file→Edit, write_file→Write, bash/bash_readonly→Bash, glob→Glob,
+ * grep→Grep, web_fetch→WebFetch, tool_search→ToolSearch, skill→Skill). The live tool roster + `HAND_TOOL_EFFECTS`
+ * now carry the NEW names, but DURABLE state minted pre-rename — a suspended tool-approval checkpoint's
+ * `pendingAction.toolName`, an interrupted orphan tool-call in a persisted session — still holds the OLD name. Any
+ * code that reads a persisted tool name and matches it against the live roster / toolEffects must canonicalize it
+ * FIRST, or a pre-rename checkpoint resumed after the upgrade strands its approved gated call (`resume.tool_unavailable`)
+ * — a cross-version durability break a version pin cannot absorb (release-gate review blocker). New code emits the new
+ * names, so this is a one-way old→new normalization that is identity for any already-canonical name.
+ *
+ * design/108 batch-A (2026-06-30): a SECOND CC-name wave renamed the remaining first-party tools to their CC
+ * 2.1.187 names (verified against the decompiled source): present_plan→ExitPlanMode, enter_plan_mode→EnterPlanMode,
+ * spawn_subagent→Task, CronCancel→CronDelete, lsp→LSP, submit_output→StructuredOutput. Same durability contract —
+ * a pre-rename checkpoint/orphan holding an OLD name must still resolve to the live roster after upgrade.
+ *
+ * design/115 P0 (2026-07-02): CC 2.1.187 canonicalizes the delegation/background-task/MCP-resource tools as
+ * Agent / TaskOutput / TaskStop / *Tool. The older names stay as model-call aliases, but persisted names must
+ * normalize to the canonical live roster before resume/reconcile/policy matching.
+ */
+const OLD_TO_NEW = {
+    // design/119: sema-own memory tools joined the PascalCase roster (config/permission canonicalize).
+    recall: "Recall",
+    remember: "Remember",
+    read_file: "Read",
+    edit_file: "Edit",
+    write_file: "Write",
+    bash: "Bash",
+    bash_readonly: "Bash",
+    glob: "Glob",
+    grep: "Grep",
+    web_fetch: "WebFetch",
+    tool_search: "ToolSearch",
+    skill: "Skill",
+    // batch-A (design/108): second CC-name wave
+    present_plan: "ExitPlanMode",
+    enter_plan_mode: "EnterPlanMode",
+    spawn_subagent: "Agent",
+    CronCancel: "CronDelete",
+    lsp: "LSP",
+    submit_output: "StructuredOutput",
+    // design/108 PascalCase sweep (2026-06-30): the remaining snake_case first-party tools → CC PascalCase
+    // convention (these are sema-specific tools, not CC tools — alignment is style-consistency, not parity).
+    repo_map: "RepoMap",
+    read_tool_result: "ReadToolResult",
+    report_blocked: "ReportBlocked",
+    declare_done: "DeclareDone",
+    run_workflow: "Workflow",
+    // Audit [485]④: CC's primary name is `Workflow` (RunWorkflow is its alias) — primary flipped so
+    // CC-trained prompts addressing "Workflow" hit; pre-rename persisted calls still resolve.
+    RunWorkflow: "Workflow",
+    // design/115 P0: CC 2.1.187 canonical names with legacy aliases preserved on the live tools.
+    Task: "Agent",
+    BashOutput: "TaskOutput",
+    AgentOutputTool: "TaskOutput",
+    BashOutputTool: "TaskOutput",
+    AgentOutput: "TaskOutput",
+    KillShell: "TaskStop",
+    KillBash: "TaskStop",
+    ListMcpResources: "ListMcpResourcesTool",
+    ReadMcpResource: "ReadMcpResourceTool",
+    ReadMcpResourceDir: "ReadMcpResourceDirTool",
+    // design/116 W2: MultiEdit retired (CC-187 has no MultiEdit) — a persisted MultiEdit call replays
+    // through Edit, whose execute accepts the `edits[]` args shape.
+    MultiEdit: "Edit",
+    // design/136 §2.1.c (BREAKING 去超集批): the standalone `Fork` tool retired — the capability lives in
+    // `Agent(subagent_type:"fork")` (1.254 收编). A persisted Fork call (a pre-removal approved checkpoint's
+    // pendingAction) resolves to the live Agent tool, whose execute adapts the legacy `{directive}` shape
+    // (directive→prompt + forced fork routing) — the approved work RUNS, it is not dropped (MultiEdit mode).
+    Fork: "Agent",
+    // design/136 §2.3: WorkflowStatus merged into the single Workflow face — poll capability is TaskOutput
+    // (field superset + delimitUntrusted fencing + cross-replica workflowStore fallback; `runId` was already
+    // accepted). Live alias on TaskOutput keeps old model-facing calls running verbatim; this entry covers
+    // the durable face (persisted names, policy/permission rules, resume/reconcile).
+    WorkflowStatus: "TaskOutput",
+};
+/**
+ * design/136 §2.4 — TOMBSTONED tools: retired tool names with NO live successor alias, mapped to an explicit
+ * MIGRATION message. Consumed by the engine's roster-miss branch (agent-loop `prepareToolCall`) AFTER
+ * `findToolByName` misses — a deployment's own same-named custom tool always wins (the tombstone yields);
+ * a hit returns the migration text as an immediate error result (model can self-correct), never the generic
+ * "Tool X not found". Three-layer division of labor: live alias = old name keeps working (WorkflowStatus);
+ * OLD_TO_NEW = durable-state normalization (Fork/WorkflowStatus); tombstone = explicit re-education for a
+ * name with no compatible successor call shape on the live roster (Sleep, and the model-facing Fork face —
+ * the Agent tool deliberately does NOT alias "Fork", so a NEW model call gets taught the CC-shaped form).
+ * Removal policy: keep an entry ≥2 minors or until bench observes zero old-name calls; entries note their
+ * introduction version for that accounting.
+ */
+const MEMORY_TOOLS_TOMBSTONE = "The Remember/Recall memory tools were removed (design/138): long-term memory is now file-based. " +
+    "Durable notes live in the memory directory shown in your # Memory instruction (MEMORY.md index + topic files) — " +
+    "use your ordinary file tools (Read/Write/Edit) on those files to record or look up memories. " +
+    "If no # Memory section is present, memory is not enabled for this task; do not retry this tool.";
+export const TOMBSTONED_TOOLS = {
+    // since 1.256+ (design/136 BREAKING batch)
+    Sleep: 'Sleep was removed. To pause and resume later, schedule a self-contained re-wake with CronCreate({ schedule: { kind: "delay", delaySec: … }, prompt: "<what to do on wake>" }) and then end your turn. To wait for an external condition or a long-running command, use Monitor. Do not poll in a loop.',
+    // since 1.256+ (design/136 BREAKING batch)
+    Fork: 'Fork was removed as a standalone tool. Use Agent with subagent_type: "fork" instead — it spawns the same context-inheriting child (pass your directive as \'prompt\'; run_in_background is supported).',
+    // since 1.258+ (design/138 S4 — legacy remember/recall retirement). Keyed on BOTH the canonical
+    // PascalCase names and the pre-design/119 lowercase aliases: the roster-miss tombstone lookup uses
+    // the RAW model-emitted name (no canonicalization), and old transcripts/habits still emit the
+    // lowercase forms. Durable-state normalization stays in OLD_TO_NEW (remember→Remember), so a
+    // pre-retirement approved checkpoint resumes down the P-7 `resume.tool_unavailable` reopen
+    // (operator re-decides) instead of stranding.
+    Remember: MEMORY_TOOLS_TOMBSTONE,
+    remember: MEMORY_TOOLS_TOMBSTONE,
+    Recall: MEMORY_TOOLS_TOMBSTONE,
+    recall: MEMORY_TOOLS_TOMBSTONE,
+};
+/**
+ * design/108 ① (MCP `mcp__` prefix migration) — pre-① persisted MCP tool names were `<server>__<tool>` (no
+ * global marker). The live roster now mints `mcp__<server>__<tool>` (see `MCP_PREFIX` in `mcp.ts`). Normalize a
+ * persisted namespaced MCP name so a pre-① checkpoint's pending/orphan MCP tool resolves against the new roster.
+ * Heuristic: sema first-party tool names are the CC set (Read/Edit/Bash/Agent/…) and NEVER contain `__`; the Q6/
+ * batch-A old names use single `_` only — so a `__` ⟹ an MCP namespaced name. KNOWN edge: a server literally
+ * named `mcp` minted `mcp__<tool>` pre-①, which reads as already-prefixed and is left as-is (its pre-① checkpoint
+ * strands across the upgrade) — deployments SHOULD NOT name an MCP server `mcp`. Kept as string literals (not an
+ * `mcp.ts` import) so this lightweight durability shim pulls no MCP-SDK deps; `tool-name-aliases.test.ts` asserts
+ * they stay in lockstep with `mcp.ts`'s `MCP_PREFIX`/`NAME_SEP`.
+ */
+const MCP_PREFIX = "mcp__";
+const MCP_NAME_SEP = "__";
+/** Map a possibly-pre-Q6/batch-A/① persisted tool name to its current canonical (CC) name; identity for an
+ *  already-canonical name. One-way old→new; safe to call on any tool name before a live-roster/effects lookup. */
+export function canonicalToolName(name) {
+    const renamed = OLD_TO_NEW[name] ?? name;
+    if (renamed.includes(MCP_NAME_SEP) && !renamed.startsWith(MCP_PREFIX))
+        return MCP_PREFIX + renamed;
+    return renamed;
+}
+//# sourceMappingURL=tool-name-aliases.js.map

package/dist/core/tool-name-aliases.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tool-name-aliases.js","sourceRoot":"","sources":["../../src/core/tool-name-aliases.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,UAAU,GAAqC;IACnD,mGAAmG;IACnG,MAAM,EAAE,QAAQ;IAChB,QAAQ,EAAE,UAAU;IACpB,SAAS,EAAE,MAAM;IACjB,SAAS,EAAE,MAAM;IACjB,UAAU,EAAE,OAAO;IACnB,IAAI,EAAE,MAAM;IACZ,aAAa,EAAE,MAAM;IACrB,IAAI,EAAE,MAAM;IACZ,IAAI,EAAE,MAAM;IACZ,SAAS,EAAE,UAAU;IACrB,WAAW,EAAE,YAAY;IACzB,KAAK,EAAE,OAAO;IACd,4CAA4C;IAC5C,YAAY,EAAE,cAAc;IAC5B,eAAe,EAAE,eAAe;IAChC,cAAc,EAAE,OAAO;IACvB,UAAU,EAAE,YAAY;IACxB,GAAG,EAAE,KAAK;IACV,aAAa,EAAE,kBAAkB;IACjC,uGAAuG;IACvG,yGAAyG;IACzG,QAAQ,EAAE,SAAS;IACnB,gBAAgB,EAAE,gBAAgB;IAClC,cAAc,EAAE,eAAe;IAC/B,YAAY,EAAE,aAAa;IAC3B,YAAY,EAAE,UAAU;IACxB,gGAAgG;IAChG,0FAA0F;IAC1F,WAAW,EAAE,UAAU;IACvB,6FAA6F;IAC7F,IAAI,EAAE,OAAO;IACb,UAAU,EAAE,YAAY;IACxB,eAAe,EAAE,YAAY;IAC7B,cAAc,EAAE,YAAY;IAC5B,WAAW,EAAE,YAAY;IACzB,SAAS,EAAE,UAAU;IACrB,QAAQ,EAAE,UAAU;IACpB,gBAAgB,EAAE,sBAAsB;IACxC,eAAe,EAAE,qBAAqB;IACtC,kBAAkB,EAAE,wBAAwB;IAC5C,kGAAkG;IAClG,gEAAgE;IAChE,SAAS,EAAE,MAAM;IACjB,kGAAkG;IAClG,uGAAuG;IACvG,sGAAsG;IACtG,yGAAyG;IACzG,IAAI,EAAE,OAAO;IACb,uGAAuG;IACvG,yGAAyG;IACzG,uGAAuG;IACvG,iFAAiF;IACjF,cAAc,EAAE,YAAY;CAC7B,CAAC;AAEF;;;;;;;;;;;GAWG;AACH,MAAM,sBAAsB,GAC1B,kGAAkG;IAClG,kHAAkH;IAClH,+FAA+F;IAC/F,iGAAiG,CAAC;AAEpG,MAAM,CAAC,MAAM,gBAAgB,GAAqC;IAChE,2CAA2C;IAC3C,KAAK,EACH,wSAAwS;IAC1S,2CAA2C;IAC3C,IAAI,EAAE,wMAAwM;IAC9M,gGAAgG;IAChG,mGAAmG;IACnG,8FAA8F;IAC9F,6FAA6F;IAC7F,2FAA2F;IAC3F,8CAA8C;IAC9C,QAAQ,EAAE,sBAAsB;IAChC,QAAQ,EAAE,sBAAsB;IAChC,MAAM,EAAE,sBAAsB;IAC9B,MAAM,EAAE,sBAAsB;CAC/B,CAAC;AAEF;;;;;;;;;;GAUG;AACH,MAAM,UAAU,GAAG,OAAO,CAAC;AAC3B,MAAM,YAAY,GAAG,IAAI,CAAC;AAE1B;kHACkH;AAClH,MAAM,UAAU,iBAAiB,CAAC,IAAY;IAC5C,MAAM,OAAO,GAAG,UAAU,CAAC,IAAI,CAAC,IAAI,IAAI,CAAC;IACzC,IAAI,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAC,IAAI,CAAC,OAAO,CAAC,UAAU,CAAC,UAAU,CAAC;QAAE,OAAO,UAAU,GAAG,OAAO,CAAC;IACnG,OAAO,OAAO,CAAC;AACjB,CAAC"}