pi-daddy 0.13.0

package/dist/definitions.d.ts

@@ -0,0 +1,101 @@
+/**
+ * Agent Skills (`SKILL.md`) as this package's definition format — ADR-0016.
+ *
+ * A subagent is a skill you spawn: the `SKILL.md` body becomes the child's system prompt
+ * (`--append-system-prompt`) and `allowed-tools` becomes its capability ceiling, enforced through
+ * `--tools`. That collapses a duplication `principal-pi-skills` already strains against, where
+ * `plan`/`review`/`debug` exist twice — once as a skill and once as a subagent prompt — and are
+ * generated from one contract precisely so the two cannot drift.
+ *
+ * **The spec's own words about `allowed-tools`:** *"a space-separated string of tools that are
+ * pre-approved to run"*, marked **experimental**. Pre-approved, not enforced — the field declares intent
+ * and blocks nothing, and implementations differ on whether they honour it at all. Turning that
+ * declaration into something structural is this package's entire value here.
+ *
+ * **One inversion is deliberate and load-bearing.** In pi-subagents' frontmatter an absent `tools:` key
+ * means *pi's full default toolset*, so an undeclared definition was the most powerful kind and any
+ * parse failure produced a wildcard — the direction that caused R-28 and review finding F18. Here an
+ * absent `allowed-tools` means **undeclared, therefore not spawnable**. A typo or an unreadable YAML
+ * form now costs a refusal instead of a grant.
+ */
+import type { Capability } from "./resolve.ts";
+/**
+ * Identifies WHICH instructions a child was given, without reproducing them (ADR-0018).
+ *
+ * The ledger's standing rule is *capability ids, counts and identifiers only — never prompts, tool
+ * arguments or results*. A hash is an identifier: it names a version of an operator-authored file. The
+ * **task** is model-assembled from the parent's context and is never recorded anywhere, by decision.
+ */
+export interface DefinitionDigest {
+    name: string;
+    /** Where the definition was read from, so a reader can go and rehash it. */
+    source: string;
+    /** SHA-256 of the body — the exact text passed as `--append-system-prompt`. */
+    sha256: string;
+}
+/**
+ * Digest a definition's body.
+ *
+ * Over the **body alone**, deliberately: that is precisely the text the child receives, so a digest that
+ * also covered the frontmatter would change when `description` was reworded and report an instruction
+ * change that never happened. `allowed-tools` is already recorded in full on every record.
+ */
+export declare function digestDefinition(definition: SkillDefinition): DefinitionDigest;
+export interface SkillDefinition {
+    /** From the path, never the frontmatter — see `parseSkillDefinition`. */
+    name: string;
+    description: string;
+    /** Raw `allowed-tools` value. `undefined` means the key was absent; `""` means it declared none. */
+    allowedTools?: string;
+    /** The spec's sanctioned extension point: a map of string keys to string values. */
+    metadata?: Record<string, string>;
+    /** Everything after the frontmatter — the child's system prompt. */
+    body: string;
+    source: string;
+}
+export interface DefinitionCeiling {
+    /** The declared capabilities, as this package's ids. */
+    capabilities: Capability[];
+    /**
+     * Entries carrying a sub-tool pattern, e.g. `Bash(git:*)`.
+     *
+     * ADR-0016 refuses these rather than reinterpreting them, because every reinterpretation is wrong:
+     * granting bare `bash` **widens** a deliberately narrow declaration, dropping the tool silently
+     * **narrows** and yields a child that mysteriously cannot work, and matching patterns inside a wrapper
+     * would be a security control implemented by string-matching a shell command. Non-empty means the
+     * caller must refuse and say so.
+     */
+    patterns: string[];
+    /** The `allowed-tools` key was absent entirely: the definition is not spawnable. */
+    undeclared: boolean;
+}
+/**
+ * Read a `SKILL.md`.
+ *
+ * The frontmatter reader handles the subset these files use — `key: value`, block scalars (`>` / `|`),
+ * and a one-level `metadata:` map. Anything it cannot read leaves the key **absent**, which for
+ * `allowed-tools` means *undeclared* and therefore refused. That is the whole reason this parser can be
+ * hand-rolled without the hazard its sibling in `agent-types.ts` carries.
+ */
+export declare function parseSkillDefinition(source: string, text: string): SkillDefinition | null;
+/**
+ * Turn a definition's `allowed-tools` into a capability ceiling.
+ *
+ * Name mapping is **lowercasing and nothing else**, deliberately. A translation table from Claude
+ * Code's names to pi's would have to decide what `Glob` means, and pi has no glob tool — so the table
+ * would either invent a grant or quietly drop one. Lowercasing leaves `Glob` as `tool:glob`, which the
+ * catalog then refuses as unknown, naming the actual problem to whoever wrote the file.
+ */
+export declare function ceilingForDefinition(definition: SkillDefinition): DefinitionCeiling;
+/**
+ * Discover `SKILL.md` definitions under pi's skill roots.
+ *
+ * Deliberately the SAME roots and the same convention the catalog uses (`skillDirs`): a directory
+ * containing `SKILL.md` is one definition named after the directory, and a top-level `.md` is one named
+ * after the file. If discovery and the catalog disagreed, a definition could be spawnable but not
+ * grantable, or listed but unspawnable.
+ *
+ * Earlier directories win on a name collision, matching pi's own precedence — project before global.
+ */
+export declare function loadDefinitions(cwd: string): Promise<Map<string, SkillDefinition>>;
+//# sourceMappingURL=definitions.d.ts.map

package/dist/definitions.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"definitions.d.ts","sourceRoot":"","sources":["../src/definitions.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAMH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAE/C;;;;;;GAMG;AACH,MAAM,WAAW,gBAAgB;IAC/B,IAAI,EAAE,MAAM,CAAC;IACb,4EAA4E;IAC5E,MAAM,EAAE,MAAM,CAAC;IACf,+EAA+E;IAC/E,MAAM,EAAE,MAAM,CAAC;CAChB;AAED;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAAC,UAAU,EAAE,eAAe,GAAG,gBAAgB,CAM9E;AAED,MAAM,WAAW,eAAe;IAC9B,yEAAyE;IACzE,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,oGAAoG;IACpG,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,oFAAoF;IACpF,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAClC,oEAAoE;IACpE,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,iBAAiB;IAChC,wDAAwD;IACxD,YAAY,EAAE,UAAU,EAAE,CAAC;IAC3B;;;;;;;;OAQG;IACH,QAAQ,EAAE,MAAM,EAAE,CAAC;IACnB,oFAAoF;IACpF,UAAU,EAAE,OAAO,CAAC;CACrB;AAED;;;;;;;GAOG;AACH,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,eAAe,GAAG,IAAI,CAyDzF;AAUD;;;;;;;GAOG;AACH,wBAAgB,oBAAoB,CAAC,UAAU,EAAE,eAAe,GAAG,iBAAiB,CAsBnF;AAED;;;;;;;;;GASG;AACH,wBAAsB,eAAe,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,GAAG,CAAC,MAAM,EAAE,eAAe,CAAC,CAAC,CA4BxF"}

package/dist/definitions.js

@@ -0,0 +1,182 @@
+/**
+ * Agent Skills (`SKILL.md`) as this package's definition format — ADR-0016.
+ *
+ * A subagent is a skill you spawn: the `SKILL.md` body becomes the child's system prompt
+ * (`--append-system-prompt`) and `allowed-tools` becomes its capability ceiling, enforced through
+ * `--tools`. That collapses a duplication `principal-pi-skills` already strains against, where
+ * `plan`/`review`/`debug` exist twice — once as a skill and once as a subagent prompt — and are
+ * generated from one contract precisely so the two cannot drift.
+ *
+ * **The spec's own words about `allowed-tools`:** *"a space-separated string of tools that are
+ * pre-approved to run"*, marked **experimental**. Pre-approved, not enforced — the field declares intent
+ * and blocks nothing, and implementations differ on whether they honour it at all. Turning that
+ * declaration into something structural is this package's entire value here.
+ *
+ * **One inversion is deliberate and load-bearing.** In pi-subagents' frontmatter an absent `tools:` key
+ * means *pi's full default toolset*, so an undeclared definition was the most powerful kind and any
+ * parse failure produced a wildcard — the direction that caused R-28 and review finding F18. Here an
+ * absent `allowed-tools` means **undeclared, therefore not spawnable**. A typo or an unreadable YAML
+ * form now costs a refusal instead of a grant.
+ */
+import { createHash } from "node:crypto";
+import { readFile, readdir } from "node:fs/promises";
+import { join } from "node:path";
+import { skillDirs } from "./catalog.js";
+/**
+ * Digest a definition's body.
+ *
+ * Over the **body alone**, deliberately: that is precisely the text the child receives, so a digest that
+ * also covered the frontmatter would change when `description` was reworded and report an instruction
+ * change that never happened. `allowed-tools` is already recorded in full on every record.
+ */
+export function digestDefinition(definition) {
+    return {
+        name: definition.name,
+        source: definition.source,
+        sha256: createHash("sha256").update(definition.body, "utf8").digest("hex"),
+    };
+}
+/**
+ * Read a `SKILL.md`.
+ *
+ * The frontmatter reader handles the subset these files use — `key: value`, block scalars (`>` / `|`),
+ * and a one-level `metadata:` map. Anything it cannot read leaves the key **absent**, which for
+ * `allowed-tools` means *undeclared* and therefore refused. That is the whole reason this parser can be
+ * hand-rolled without the hazard its sibling in `agent-types.ts` carries.
+ */
+export function parseSkillDefinition(source, text) {
+    const match = /^---\r?\n([\s\S]*?)\r?\n---\r?\n?/.exec(text);
+    if (!match)
+        return null;
+    const fields = new Map();
+    const metadata = {};
+    const lines = match[1].split(/\r?\n/);
+    for (let i = 0; i < lines.length; i++) {
+        const kv = /^([A-Za-z_][A-Za-z0-9_-]*)\s*:\s*(.*)$/.exec(lines[i]);
+        if (!kv)
+            continue;
+        const [, key, rawValue] = kv;
+        const value = rawValue.trim();
+        // A folded/literal scalar: fold the indented continuation into one line. `principal-pi-skills`
+        // writes every description this way, and the sibling parser SKIPS these — which is safe there only
+        // because it never needs the value. Here a skipped `description` would be a missing required field.
+        if (value === ">" || value === "|") {
+            const parts = [];
+            for (let j = i + 1; j < lines.length; j++) {
+                if (!/^\s+\S/.test(lines[j]))
+                    break;
+                parts.push(lines[j].trim());
+                i = j;
+            }
+            fields.set(key, parts.join(" "));
+            continue;
+        }
+        // `metadata:` introduces a one-level map of string keys to string values (the spec's shape).
+        if (key === "metadata" && value === "") {
+            for (let j = i + 1; j < lines.length; j++) {
+                const item = /^\s+([A-Za-z_][A-Za-z0-9_-]*)\s*:\s*(.*)$/.exec(lines[j]);
+                if (!item)
+                    break;
+                metadata[item[1]] = item[2].trim().replace(/^["']|["']$/g, "");
+                i = j;
+            }
+            continue;
+        }
+        fields.set(key, value);
+    }
+    const description = fields.get("description");
+    if (description === undefined)
+        return null;
+    return {
+        // Identity comes from the PATH. ADR-0013 learned this the hard way on the other format: pi keys
+        // skills by their directory, so trusting a frontmatter `name` lets our view and the loader's
+        // disagree about which file a name refers to. The spec requires `name` to match the parent
+        // directory anyway, so a mismatch is the file's defect and not something to honour.
+        name: nameFromPath(source),
+        description,
+        allowedTools: fields.get("allowed-tools"),
+        metadata: Object.keys(metadata).length > 0 ? metadata : undefined,
+        body: text.slice(match[0].length).trim(),
+        source,
+    };
+}
+/** `/skills/review/SKILL.md` -> `review`; `/skills/triage.md` -> `triage`. */
+function nameFromPath(source) {
+    const parts = source.split("/").filter((p) => p.length > 0);
+    const last = parts.at(-1) ?? "";
+    if (last.toLowerCase() === "skill.md")
+        return parts.at(-2) ?? "";
+    return last.replace(/\.md$/i, "");
+}
+/**
+ * Turn a definition's `allowed-tools` into a capability ceiling.
+ *
+ * Name mapping is **lowercasing and nothing else**, deliberately. A translation table from Claude
+ * Code's names to pi's would have to decide what `Glob` means, and pi has no glob tool — so the table
+ * would either invent a grant or quietly drop one. Lowercasing leaves `Glob` as `tool:glob`, which the
+ * catalog then refuses as unknown, naming the actual problem to whoever wrote the file.
+ */
+export function ceilingForDefinition(definition) {
+    const raw = definition.allowedTools;
+    if (raw === undefined)
+        return { capabilities: [], patterns: [], undeclared: true };
+    const capabilities = new Set();
+    const patterns = [];
+    // The spec says space-separated. Commas are tolerated because `Read, Grep` is what people type, and
+    // accepting them grants nothing extra — it only avoids a comma becoming part of a capability name.
+    for (const entry of raw.split(/[\s,]+/).filter((e) => e.length > 0)) {
+        if (entry.includes("(")) {
+            patterns.push(entry);
+            continue;
+        }
+        if (entry.startsWith("ext:") || entry.startsWith("skill:") || entry.startsWith("agent:")) {
+            capabilities.add(entry);
+            continue;
+        }
+        capabilities.add(`tool:${entry.toLowerCase()}`);
+    }
+    return { capabilities: [...capabilities].sort(), patterns, undeclared: false };
+}
+/**
+ * Discover `SKILL.md` definitions under pi's skill roots.
+ *
+ * Deliberately the SAME roots and the same convention the catalog uses (`skillDirs`): a directory
+ * containing `SKILL.md` is one definition named after the directory, and a top-level `.md` is one named
+ * after the file. If discovery and the catalog disagreed, a definition could be spawnable but not
+ * grantable, or listed but unspawnable.
+ *
+ * Earlier directories win on a name collision, matching pi's own precedence — project before global.
+ */
+export async function loadDefinitions(cwd) {
+    const definitions = new Map();
+    for (const dir of skillDirs(cwd)) {
+        let names;
+        try {
+            names = await readdir(dir);
+        }
+        catch {
+            continue; // an absent skill root is normal
+        }
+        for (const name of [...names].sort()) {
+            // A directory holding SKILL.md, or a top-level .md — try the former first, exactly as the
+            // catalog does, so the two cannot disagree about what exists.
+            const candidates = [join(dir, name, "SKILL.md"), ...(name.endsWith(".md") ? [join(dir, name)] : [])];
+            for (const path of candidates) {
+                let text;
+                try {
+                    text = await readFile(path, "utf8");
+                }
+                catch {
+                    continue; // not this shape; try the next candidate
+                }
+                const parsed = parseSkillDefinition(path, text);
+                // First writer wins, so project definitions shadow global ones rather than the reverse.
+                if (parsed && !definitions.has(parsed.name))
+                    definitions.set(parsed.name, parsed);
+                break;
+            }
+        }
+    }
+    return definitions;
+}
+//# sourceMappingURL=definitions.js.map

package/dist/definitions.js.map

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

package/dist/delegate.d.ts

@@ -0,0 +1,133 @@
+/**
+ * Governed delegation — provisioning, not merely enforcement.
+ *
+ * The `tool_call` interceptor can only *permit or refuse* a `pi-subagents` spawn, because that package's
+ * `Agent` tool has no `tools` parameter. When we do the spawning ourselves the grant becomes an argument,
+ * which is what "give them some tools but not others" actually requires.
+ *
+ * Two properties fall out of owning the spawn:
+ *
+ *  1. **No propagation race at all.** Each child receives its own explicit `env` object, so nothing is
+ *     written to the shared `process.env`. The interceptor's constraint (only parent-level facts may be
+ *     pushed, because the channel is global) does not apply here.
+ *  2. **Depth control by capability.** `tool:delegate` is itself a capability. Grant it and the child can
+ *     sub-delegate; withhold it and the child is a leaf. No separate depth mechanism is required, though
+ *     `maxDepth` remains as a cheap backstop.
+ */
+import { type DefinitionDigest, type SkillDefinition } from "./definitions.ts";
+import { type Capability, type ResolveResult } from "./resolve.ts";
+export { DELEGATE_CAPABILITY, agentCapability, maySpawnDefinition, normaliseCapability } from "./capabilities.ts";
+import { type InheritableApproval } from "./approval.ts";
+import { type Catalog } from "./catalog.ts";
+export interface DelegationRequest {
+    task: string;
+    /**
+     * Capabilities the delegator wants the child to hold.
+     *
+     * Optional since ADR-0016: prefer `agent`, which names an operator-authored definition. This form
+     * lets the MODEL choose the capability set, which is the weaker arrangement — it is still bounded by
+     * the session grant (ADR-0008), so it cannot escalate, but nothing about it was reviewed by a human.
+     */
+    tools?: string[];
+    /**
+     * Name of a `SKILL.md` definition to spawn (ADR-0016).
+     *
+     * When given, the definition's `allowed-tools` is the ceiling and its body is the child's system
+     * prompt. The model chooses only *which* definition and *what* task; the capability set is the
+     * operator's, written down in a file.
+     */
+    agent?: string;
+    model?: string;
+    provider?: string;
+    thinking?: string;
+}
+export interface DelegationContext {
+    ownGrant: Capability[];
+    depth: number;
+    maxDepth: number;
+    gated: Capability[];
+    /**
+     * Approvals in force for this delegation, with subject and scope (ADR-0014).
+     *
+     * One source of truth for two different questions. The **gate check here** honours every entry,
+     * including `once` — that approval applies to *this* spawn, which is exactly what the human said yes
+     * to. What crosses to the CHILD is `inheritApprovals`, which drops `once` and keeps the subject, so
+     * the same list cannot silently authorise a subtree.
+     */
+    approved?: InheritableApproval[];
+    ledgerPath?: string;
+    /** Path to this extension, so a child granted `tool:delegate` can delegate in turn. */
+    extensionPath?: string;
+    /** Live capability catalog. When supplied, capabilities absent from it are refused as unknown. */
+    catalog?: Catalog;
+    /**
+     * Absolute path per skill NAME, from the catalog's `source` field (R-32).
+     *
+     * Without it every granted `skill:` capability is unresolvable and the delegation is refused, which
+     * is the correct direction: a caller that cannot say where a skill lives cannot honestly grant it.
+     */
+    skillPaths?: Record<string, string>;
+    /** Let the child load `AGENTS.md` / `CLAUDE.md`. Default false — see `planSpawn`. */
+    contextFiles?: boolean;
+    /** Known `SKILL.md` definitions by name, for `DelegationRequest.agent` (ADR-0016). */
+    definitions?: Map<string, SkillDefinition>;
+    /**
+     * Build an INTERACTIVE plan — no `--print` — for an executor that drives the child after starting it.
+     *
+     * `runHerdrPane` requires this: `--print` makes pi process the prompt and exit, so it never reaches the
+     * interactive readiness `herdr agent start` waits for and the agent is never detected. Default is the
+     * non-interactive plan, because a governed child should not sit waiting for a human by accident.
+     */
+    interactive?: boolean;
+    /**
+     * Total descendants this session may still create (`src/fanout.ts`). Split among children by the caller.
+     *
+     * Omitted means unbounded, which is the pre-fan-out behaviour and correct for a single blocking
+     * delegation — the accident that used to bound cardinality to one.
+     */
+    fanoutBudget?: number;
+    /** This session's ledger id, so a child's `parentId` names its real parent (F8). */
+    spawnId?: string;
+    /** Ledger id assigned to THIS child, distinguishing it from its siblings (F8). */
+    childSpawnId?: string;
+}
+export interface Delegation {
+    ok: boolean;
+    reason?: string;
+    args: string[];
+    /** Per-child environment — never merged into the parent's process.env. */
+    env: Record<string, string>;
+    effective: Capability[];
+    /**
+     * The result this plan was made from. **Required** (B-I3): while it was optional the extension
+     * guarded its ledger write with `if (ledgerPath && plan.result)`, silently dropping every refusal
+     * that returned before `resolve()` ran. The type is what keeps a new early exit auditable.
+     */
+    result: ResolveResult;
+    childDepth: number;
+    /**
+     * The capabilities this delegation asked for, whatever route named them.
+     *
+     * Carried on the plan rather than re-derived by the caller (the B-I3 lesson): with `agent`, the
+     * request names a DEFINITION and the capabilities come from its `allowed-tools`, so a ledger that
+     * read the tool parameters would record an empty request for every definition spawn.
+     */
+    requested: Capability[];
+    /** Ledger id for this child, if the caller assigned one (F8). */
+    childId?: string;
+    /**
+     * Which operator-authored instructions this spawn used (ADR-0018).
+     *
+     * Absent for a `tools:`-style delegation, which has no definition and therefore no instructions to
+     * identify — and absent on an ADR-0017 authorisation refusal, which is decided before the file is read.
+     */
+    definitionDigest?: DefinitionDigest;
+}
+/**
+ * Plan a governed delegation. Pure: returns argv and env, spawns nothing.
+ *
+ * Fails closed on depth, on any requested capability the delegator does not hold, on gated capabilities
+ * without approval, and on a grant that cannot narrow (a universal capability slipping through).
+ */
+export declare function planDelegation(request: DelegationRequest, ctx: DelegationContext): Delegation;
+//# sourceMappingURL=delegate.d.ts.map

package/dist/delegate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"delegate.d.ts","sourceRoot":"","sources":["../src/delegate.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAGH,OAAO,EAA0C,KAAK,gBAAgB,EAAE,KAAK,eAAe,EAAE,MAAM,kBAAkB,CAAC;AACvH,OAAO,EAA4B,KAAK,UAAU,EAAE,KAAK,aAAa,EAAE,MAAM,cAAc,CAAC;AAO7F,OAAO,EAAE,mBAAmB,EAAE,eAAe,EAAE,kBAAkB,EAAE,mBAAmB,EAAE,MAAM,mBAAmB,CAAC;AAElH,OAAO,EAAoB,KAAK,mBAAmB,EAAE,MAAM,eAAe,CAAC;AAC3E,OAAO,EAAuB,KAAK,OAAO,EAAE,MAAM,cAAc,CAAC;AAEjE,MAAM,WAAW,iBAAiB;IAChC,IAAI,EAAE,MAAM,CAAC;IACb;;;;;;OAMG;IACH,KAAK,CAAC,EAAE,MAAM,EAAE,CAAC;IACjB;;;;;;OAMG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,iBAAiB;IAChC,QAAQ,EAAE,UAAU,EAAE,CAAC;IACvB,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,EAAE,UAAU,EAAE,CAAC;IACpB;;;;;;;OAOG;IACH,QAAQ,CAAC,EAAE,mBAAmB,EAAE,CAAC;IACjC,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,uFAAuF;IACvF,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,kGAAkG;IAClG,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB;;;;;OAKG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACpC,qFAAqF;IACrF,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,sFAAsF;IACtF,WAAW,CAAC,EAAE,GAAG,CAAC,MAAM,EAAE,eAAe,CAAC,CAAC;IAC3C;;;;;;OAMG;IACH,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB;;;;;OAKG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,oFAAoF;IACpF,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,kFAAkF;IAClF,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAED,MAAM,WAAW,UAAU;IACzB,EAAE,EAAE,OAAO,CAAC;IACZ,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,MAAM,EAAE,CAAC;IACf,0EAA0E;IAC1E,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC5B,SAAS,EAAE,UAAU,EAAE,CAAC;IACxB;;;;OAIG;IACH,MAAM,EAAE,aAAa,CAAC;IACtB,UAAU,EAAE,MAAM,CAAC;IACnB;;;;;;OAMG;IACH,SAAS,EAAE,UAAU,EAAE,CAAC;IACxB,iEAAiE;IACjE,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB;;;;;OAKG;IACH,gBAAgB,CAAC,EAAE,gBAAgB,CAAC;CACrC;AAED;;;;;GAKG;AACH,wBAAgB,cAAc,CAAC,OAAO,EAAE,iBAAiB,EAAE,GAAG,EAAE,iBAAiB,GAAG,UAAU,CA8O7F"}