@cleocode/core 2026.6.12 → 2026.6.13

package/dist/llm/pi/pi-agent-adapter.js

@@ -0,0 +1,329 @@
+/**
+ * `PiAgentAdapter` — the in-process Pi agent-loop embed (T11761 · S2 · T11898).
+ *
+ * THE KEYSTONE of the Pi-harness work: the Pi agent loop runs **in-process**
+ * inside the Cleo daemon as the body of the `SkillRunner` strategy slot, with
+ * ZERO authority. It:
+ *
+ *  - resolves its LLM ONLY through the E9 chokepoint (`resolveLLMForSystem` →
+ *    `ModelRunner`) via the Cleo-owned {@link createPiStreamFn} — `pi-ai`'s
+ *    registry env-fallback is never reached;
+ *  - touches the filesystem/shell ONLY through the deny-first
+ *    {@link GuardedExecutionEnv} (S1) bound to the injected guarded tool surface;
+ *  - reads its session identity from the daemon-stamped env (NEVER mints one);
+ *  - runs under {@link wrapPiCall} containment so a `process.exit()` from any Pi
+ *    code path becomes a thrown typed error, not a daemon-fatal exit;
+ *  - is gated behind a **default-OFF** feature flag ({@link isPiRunnerEnabled}).
+ *
+ * The `SkillRunner` slot (`SkillExecutorAdapterOptions.runner`, line 124 of
+ * `skill-executor-adapter.ts`) CALLS this adapter via {@link createPiSkillRunner};
+ * the adapter is NOT hosted inside `defaultSkillRunner` (which stays untouched).
+ *
+ * Session durability is S3's concern: this subtask uses
+ * {@link InMemorySessionStorage} (in-RAM, no DB writer, no lease) so the
+ * read/stream path is buildable with ZERO write authority.
+ *
+ * @epic T10403
+ * @task T11761
+ * @task T11898
+ */
+import { InMemorySessionRepo, runAgentLoop } from '@earendil-works/pi-agent-core';
+import { getLogger } from '../../logger.js';
+import { resolveAgentIdFromEnv, resolveParentSessionIdFromEnv, resolveSessionIdFromEnv, } from '../../sessions/session-id.js';
+import { ToolCallBudget, ToolDispatchEngine } from '../../tools/dispatch.js';
+import { PiContainmentError, wrapPiCall } from './pi-errors.js';
+import { createPiStreamFn } from './pi-stream-fn.js';
+import { buildPiAgentTools } from './pi-tool-bridge.js';
+const logger = getLogger('pi-agent-adapter');
+/**
+ * Default-OFF feature flag controlling whether the Pi runner is constructed and
+ * used. Reads `CLEO_PI_RUNNER_ENABLED === '1'`. The whole adapter is gated by
+ * this — when disabled, {@link createPiSkillRunner} is never wired into the
+ * dispatcher and `defaultSkillRunner` runs instead.
+ *
+ * @returns `true` when the Pi runner is explicitly enabled.
+ */
+export function isPiRunnerEnabled() {
+    return process.env['CLEO_PI_RUNNER_ENABLED'] === '1';
+}
+/**
+ * In-process Pi agent-loop adapter with ZERO authority.
+ *
+ * {@link run} drives `pi-agent-core`'s `runAgentLoop` with a Cleo-owned streamFn
+ * (Gate-13), an in-RAM session (no DB writer), and `wrapPiCall` exit/error
+ * containment, then projects the terminal assistant message onto a
+ * {@link PiAgentResult}. It NEVER throws past the containment boundary for a Pi
+ * failure — a Pi error becomes a `{ status: 'failure', error }` result.
+ */
+export class PiAgentAdapter {
+    /** Construction defaults merged under the per-run {@link PiAgentRunContext}. */
+    #deps;
+    /**
+     * Construct the adapter.
+     *
+     * `deps` supplies the construction-time defaults (resolution system + project
+     * root) that {@link run} merges UNDER the per-call context — a field the call
+     * supplies on `ctx` always wins. The factory {@link createPiSkillRunner} builds
+     * the full `ctx` from these same deps; a direct caller may pass a partial `ctx`
+     * and rely on the deps for the rest.
+     *
+     * @param deps - Resolution system + optional project root defaults.
+     */
+    constructor(deps = {}) {
+        this.#deps = deps;
+    }
+    /**
+     * Run one Pi agent turn over the guarded tool surface.
+     *
+     * The `tools` surface is the injected {@link GuardedToolSurface}; the v0
+     * read/stream path threads it into the loop for future tool wiring (S3+ maps
+     * Pi's `ExecutionEnv` onto it). Resolution + streaming are owned by
+     * {@link createPiStreamFn} (Gate-13). The session id MUST already be
+     * daemon-stamped (read from env in {@link createPiSkillRunner}); the adapter
+     * never mints one.
+     *
+     * @param prompt - The user prompt for this turn.
+     * @param tools - The deny-first guarded tool surface (injected, never built here).
+     * @param ctx - The run context (system label + daemon-stamped identity + signal).
+     * @returns The terminal {@link PiAgentResult}; never throws for a Pi failure.
+     */
+    async run(prompt, tools, ctx) {
+        // Merge construction defaults UNDER the per-call ctx — a field the caller
+        // supplied on `ctx` always wins; deps fill the `projectRoot` gap.
+        const runCtx = ctx.projectRoot === undefined && this.#deps.projectRoot !== undefined
+            ? { ...ctx, projectRoot: this.#deps.projectRoot }
+            : ctx;
+        try {
+            const messages = await wrapPiCall(async (signal) => {
+                // In-RAM session seeded with the daemon-stamped id — the default
+                // `createSessionId()` uuidv7 mint is never reached (ZERO authority,
+                // no DB writer, no lease).
+                const repo = new InMemorySessionRepo();
+                const session = await repo.create({ id: runCtx.sessionId });
+                const metadata = await session.getMetadata();
+                if (metadata.id !== runCtx.sessionId) {
+                    // Identity contract violation — refuse rather than run under a minted id.
+                    throw new PiContainmentError('E_PI_LOOP_FAILED', `Pi session id mismatch: expected daemon-stamped "${runCtx.sessionId}", got "${metadata.id}"`);
+                }
+                // The streamFn is the single Gate-13 LLM route; `signal` is the
+                // containment-managed abort threaded into the loop.
+                const streamFn = createPiStreamFn({ ...runCtx, signal });
+                const config = this.#buildConfig();
+                const events = [];
+                const emit = (event) => {
+                    events.push(event);
+                };
+                // AC6 — close the tool-call loop. When a registry is wired, build the
+                // T1740 dispatch engine over it + the injected guarded surface, project
+                // executable `AgentTool`s onto the loop context, and (separately) advertise
+                // the same schemas to the model on the wire (Context.tools is read by the
+                // streamFn). When NO registry is supplied the loop is text-only — the
+                // guarded surface is still asserted so the seam is never ambient.
+                void tools;
+                const agentContext = this.#buildAgentContext(tools);
+                const result = await runAgentLoop([userMessage(prompt)], agentContext, config, emit, signal, streamFn);
+                return result;
+            }, runCtx.signal);
+            return projectResult(messages);
+        }
+        catch (err) {
+            // Containment already mapped Pi exits/aborts/failures to a typed error.
+            const message = err instanceof Error ? err.message : String(err);
+            logger.warn({ system: runCtx.system, error: message }, 'pi agent run failed (contained)');
+            return { status: 'failure', output: {}, error: message };
+        }
+    }
+    /**
+     * Build the {@link AgentLoopConfig} for this run.
+     *
+     * The `model` is a syntactically-valid placeholder ONLY — the actual provider/
+     * model/credential is resolved inside the streamFn by `ctx.system`, never by
+     * this descriptor (the resolver/registry is the SSoT, NOT a literal here). The
+     * placeholder id is a non-model-literal sentinel so it cannot trip Gate-13's
+     * `hardcoded-model-literal` rule.
+     *
+     * @returns The loop config.
+     */
+    #buildConfig() {
+        return {
+            model: placeholderModel(),
+            // Pass AgentMessages straight through to the LLM boundary — the streamFn
+            // re-projects them onto cleo transport messages. Must not throw (Pi contract).
+            convertToLlm: (messages) => messages,
+        };
+    }
+    /**
+     * Build the loop's {@link AgentContext}, wiring the executable tools when a
+     * registry is configured (T1740 · AC6).
+     *
+     * With a registry: a {@link ToolDispatchEngine} is constructed over it + the
+     * injected guarded surface + the optional run-scoped budget, and {@link
+     * buildPiAgentTools} projects executable `AgentTool`s onto `context.tools`. The
+     * loop reads those `execute` bodies when the model emits a tool-call, so the
+     * call runs through the dispatch engine (lookup → validate → availability →
+     * budget → guarded side effect → formatted result) and the result is fed back.
+     * Without a registry the context is text-only — the prior behaviour.
+     *
+     * @param tools - The injected guarded tool surface every executable runs through.
+     * @returns The loop context (`systemPrompt` + empty transcript + optional tools).
+     */
+    #buildAgentContext(tools) {
+        if (!this.#deps.registry) {
+            return { systemPrompt: '', messages: [] };
+        }
+        const engine = new ToolDispatchEngine({
+            registry: this.#deps.registry,
+            tools,
+            ...(this.#deps.budget !== undefined ? { budget: new ToolCallBudget(this.#deps.budget) } : {}),
+        });
+        const agentTools = buildPiAgentTools(engine, this.#deps.registry);
+        // `buildPiAgentTools` returns the structural `AgentTool` subset the loop
+        // reads (name/description/parameters/label/execute); the cast bridges to
+        // `pi-agent-core`'s generic `AgentTool<TSchema, TDetails>` without importing
+        // its TypeBox-parameterized type into the bridge (Gate-10 quarantine).
+        return {
+            systemPrompt: '',
+            messages: [],
+            tools: agentTools,
+        };
+    }
+}
+/**
+ * Factory returning a {@link SkillRunner} whose body delegates to
+ * {@link PiAgentAdapter.run}.
+ *
+ * This is the seam adaptation: the real `SkillRunner` shape is
+ * `(skill, input) => Promise<SkillExecuteResult>` — it carries NO free `prompt`
+ * / `ctx`, so the closure DERIVES the prompt from the skill+context and reads
+ * the daemon-stamped identity from env. When the env is un-stamped the runner
+ * fails closed (it NEVER mints a session id).
+ *
+ * Wire it into the dispatcher behind the default-OFF flag:
+ * ```ts
+ * new SkillExecutorAdapter({
+ *   runner: isPiRunnerEnabled() ? createPiSkillRunner(deps) : undefined,
+ * });
+ * ```
+ *
+ * @param deps - Adapter construction deps (resolution system + project root).
+ * @returns A `SkillRunner` that runs the Pi loop in-process.
+ */
+export function createPiSkillRunner(deps = {}) {
+    // The adapter receives the full deps (incl. the optional tool registry + budget
+    // for AC6 tool-call dispatch).
+    const adapter = new PiAgentAdapter(deps);
+    return async (skill, input) => {
+        const sessionId = resolveSessionIdFromEnv();
+        if (sessionId === null) {
+            // ZERO authority: a Pi-in-process run without a daemon-stamped session is
+            // a contract violation. Fail closed — never mint.
+            return {
+                status: 'failure',
+                output: {},
+                error: 'E_PI_NO_SESSION_IDENTITY: CLEO_SESSION_ID is not set; the Pi runner refuses to mint a session id',
+            };
+        }
+        const ctx = {
+            system: deps.system ?? 'task-executor',
+            sessionId,
+            agentId: resolveAgentIdFromEnv(),
+            parentSessionId: resolveParentSessionIdFromEnv(),
+            ...(deps.projectRoot !== undefined ? { projectRoot: deps.projectRoot } : {}),
+        };
+        const prompt = buildPromptFromSkill(skill, input);
+        const result = await adapter.run(prompt, input.tools, ctx);
+        return result.status === 'success'
+            ? { status: 'success', output: result.output }
+            : {
+                status: 'failure',
+                output: result.output,
+                ...(result.error !== undefined ? { error: result.error } : {}),
+            };
+    };
+}
+/**
+ * Derive the Pi prompt from a resolved skill + its execution input.
+ *
+ * v0: the skill's content is the instruction body; the accumulated context is
+ * appended as a JSON block so the model can read prior bindings. Kept small and
+ * deterministic — the richer prompt-template path is a later subtask.
+ *
+ * @param skill - The resolved skill (frontmatter + content).
+ * @param input - The execution input (skill id + context + tools).
+ * @returns The composed prompt string.
+ */
+function buildPromptFromSkill(skill, input) {
+    const body = skill.content ?? skill.frontmatter.description ?? skill.name;
+    const contextKeys = Object.keys(input.context);
+    const contextBlock = contextKeys.length > 0 ? `\n\n## Context\n${JSON.stringify(input.context, null, 2)}` : '';
+    return `${body}${contextBlock}`;
+}
+/** Build a Pi user {@link AgentMessage} from a prompt string. */
+function userMessage(prompt) {
+    return {
+        role: 'user',
+        content: prompt,
+        timestamp: Date.now(),
+    };
+}
+/**
+ * Project the loop's terminal assistant message onto a {@link PiAgentResult}.
+ *
+ * The loop returns the full `AgentMessage[]`; the last assistant message's text
+ * is the terminal output. A `stopReason: 'error'` message becomes a failure.
+ *
+ * @param messages - The loop's returned message list.
+ * @returns The projected result.
+ */
+function projectResult(messages) {
+    const last = [...messages].reverse().find((m) => m.role === 'assistant');
+    if (!last) {
+        return { status: 'success', output: { text: '' } };
+    }
+    const text = assistantText(last);
+    const stopReason = last.stopReason;
+    if (stopReason === 'error') {
+        const errorMessage = last.errorMessage ?? 'pi loop error';
+        return { status: 'failure', output: { text }, error: errorMessage };
+    }
+    return { status: 'success', output: { text } };
+}
+/** Extract concatenated visible text from a Pi assistant message. */
+function assistantText(message) {
+    const content = message.content;
+    if (typeof content === 'string')
+        return content;
+    if (Array.isArray(content)) {
+        return content
+            .map((c) => typeof c === 'object' && c !== null && 'text' in c
+            ? String(c.text)
+            : '')
+            .join('');
+    }
+    return '';
+}
+/**
+ * Build a syntactically-valid placeholder {@link Model} for the loop config.
+ *
+ * The streamFn ignores this model for resolution (it resolves by `ctx.system`),
+ * so the fields are inert sentinels. The `id`/`name` are NON-model-literals so
+ * they never trip Gate-13's `hardcoded-model-literal` rule, and `provider` is a
+ * neutral marker (NOT a real provider's credential trigger).
+ *
+ * @returns A placeholder model.
+ */
+function placeholderModel() {
+    return {
+        id: 'cleo-resolved',
+        name: 'cleo-resolved',
+        api: 'anthropic-messages',
+        provider: 'cleo',
+        baseUrl: '',
+        reasoning: false,
+        input: ['text'],
+        cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
+        contextWindow: 0,
+        maxTokens: 0,
+    };
+}
+//# sourceMappingURL=pi-agent-adapter.js.map

package/dist/llm/pi/pi-agent-adapter.js.map

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

package/dist/llm/pi/pi-errors.d.ts

@@ -0,0 +1,161 @@
+/**
+ * Pi error / exit containment (T11761 · S1 · T11897).
+ *
+ * The Pi agent loop runs **in-process** inside the Cleo daemon with ZERO
+ * authority. Two library packages are in the safe import set
+ * (`@earendil-works/pi-agent-core` + `@earendil-works/pi-ai`) and both are
+ * verified exit-clean, but the daemon MUST be protected from a process
+ * termination originating from a Pi code path. This module is the containment
+ * boundary: it converts a `process.exit()` call or a `process.exitCode` mutation
+ * attempted while running Pi code into a typed {@link PiContainmentError} thrown
+ * back to the caller.
+ *
+ * ## Containment scope (honest guarantee)
+ *
+ * The `process.exit` trap is process-global and REF-COUNTED across overlapping
+ * {@link wrapPiCall} scopes, so it covers the synchronous body, every awaited
+ * continuation, AND any deferred/detached exit (`setTimeout`, un-awaited
+ * promise, microtask) that fires while ANY Pi call is still active. The ONLY
+ * residual window is an exit fired AFTER the last active call has settled. To
+ * close that too — a daemon-lifetime guarantee covering ANY present/future Pi
+ * exit, synchronous or detached — the daemon calls {@link installDaemonExitGuard}
+ * once at startup to PIN the trap for its whole lifetime.
+ *
+ * Scope discipline (S1): NO `pi-ai`/`pi-agent-core` imports, NO DB access, NO
+ * LLM calls. Import-time side-effect free — the logger is resolved lazily
+ * (never at module top level).
+ *
+ * @epic T10403
+ * @task T11761
+ * @task T11897
+ */
+import { ExitCode } from '@cleocode/contracts';
+import { CleoError } from '../../errors.js';
+/**
+ * Stable string codes for the Pi-containment error surface.
+ *
+ * `CleoError` carries a NUMERIC {@link ExitCode}; these string codes are the
+ * machine-readable discriminators a caller switches on, carried on
+ * {@link PiContainmentError.piCode} (and mirrored into the LAFS error `details`
+ * via `CleoErrorDetails`). They are NOT exit codes themselves.
+ */
+export type PiContainmentCode = 
+/** Pi (or a transitive dep) called `process.exit()` while in-process. */
+'E_PI_PROCESS_EXIT_TRAPPED'
+/** Pi (or a transitive dep) mutated `process.exitCode` while in-process. */
+ | 'E_PI_EXIT_CODE_MUTATION_TRAPPED'
+/** The wrapped Pi call was aborted via the supplied `AbortSignal`. */
+ | 'E_PI_ABORTED'
+/** The wrapped Pi call threw an unexpected error. */
+ | 'E_PI_LOOP_FAILED';
+/**
+ * Typed containment error for the Pi in-process embed.
+ *
+ * Extends {@link CleoError} so it flows through the existing LAFS error
+ * projection (`toLAFSError`/`toProblemDetails`). It carries the Pi-specific
+ * string {@link PiContainmentCode} on {@link piCode} (the numeric `ExitCode`
+ * super-field is `INTERNAL`/`GENERAL_ERROR`-class — it is the daemon, not the
+ * caller, that is being protected, so the failure is an internal one).
+ */
+export declare class PiContainmentError extends CleoError {
+    /** Machine-readable Pi-containment discriminator. */
+    readonly piCode: PiContainmentCode;
+    /**
+     * @param piCode - The Pi-containment discriminator.
+     * @param message - Human-readable description.
+     * @param options - Optional `cause` and the numeric `ExitCode` (defaults to
+     *   {@link ExitCode.GENERAL_ERROR}).
+     */
+    constructor(piCode: PiContainmentCode, message: string, options?: {
+        cause?: unknown;
+        exitCode?: ExitCode;
+    });
+}
+/**
+ * Type guard for {@link PiContainmentError} (cross-realm-safe via `piCode`).
+ *
+ * @param err - The value to test.
+ * @returns `true` when `err` is a {@link PiContainmentError}.
+ */
+export declare function isPiContainmentError(err: unknown): err is PiContainmentError;
+/**
+ * Convert an arbitrary thrown value into a {@link PiContainmentError}.
+ *
+ * A value that is ALREADY a {@link PiContainmentError} passes through unchanged
+ * (so an exit-trap error is not re-wrapped as a generic loop failure). Anything
+ * else becomes an `E_PI_LOOP_FAILED` carrying the original as `cause`.
+ *
+ * @param err - The thrown value.
+ * @returns A typed {@link PiContainmentError}.
+ */
+export declare function wrapPiError(err: unknown): PiContainmentError;
+/**
+ * Pin the `process.exit` trap for the ENTIRE daemon lifetime.
+ *
+ * This is the durable, complete fix for the async-exit leak: once pinned, the
+ * trap is NEVER restored, so a `process.exit()` originating from ANY Pi code path
+ * — synchronous, awaited, deferred (`setTimeout`), detached (fire-and-forget),
+ * present or future — is neutralized for as long as the daemon runs. Call this
+ * once at daemon startup BEFORE any Pi-touching work is dispatched.
+ *
+ * Idempotent. The returned function un-pins (e.g. for a graceful shutdown that
+ * legitimately needs to exit); after un-pinning, the trap is restored when no
+ * {@link wrapPiCall} scope is active.
+ *
+ * @returns A function that un-pins the daemon-lifetime trap.
+ *
+ * @example
+ * ```ts
+ * // daemon bootstrap, before serving requests:
+ * const unpin = installDaemonExitGuard();
+ * // ... daemon runs; all Pi exits are trapped for the whole lifetime ...
+ * unpin(); // only if a controlled shutdown must reach the real process.exit
+ * ```
+ */
+export declare function installDaemonExitGuard(): () => void;
+/**
+ * Un-pin the daemon-lifetime `process.exit` trap (idempotent).
+ *
+ * Identical to the closure returned by {@link installDaemonExitGuard}, but
+ * callable WITHOUT that handle — for code paths that must reach the real
+ * `process.exit` yet do not hold the closure (e.g. a daemon bootstrap-failure
+ * handler in a different module). After un-pinning, the trap is restored once no
+ * {@link wrapPiCall} scope is active. A no-op if the guard was never pinned.
+ *
+ * Idempotent: safe to call multiple times and from multiple paths.
+ */
+export declare function releaseDaemonExitGuard(): void;
+/**
+ * Run a Pi-touching async function under process-exit containment + abort
+ * routing.
+ *
+ * Behaviour:
+ * - Acquires the REF-COUNTED, process-global {@link acquireExitTrap} for the
+ *   duration of `fn` and releases it in a `finally`. A `process.exit()` call —
+ *   synchronous, awaited, OR deferred/detached but firing while ANY Pi call is
+ *   still active — becomes a thrown {@link PiContainmentError} (the daemon
+ *   survives). A `process.exitCode` mutation is detected-and-restored the instant
+ *   `fn` settles, then surfaced as a thrown `E_PI_EXIT_CODE_MUTATION_TRAPPED`.
+ *   For a guarantee that spans even an exit fired AFTER the last call settles,
+ *   the daemon should additionally pin the trap once at startup via
+ *   {@link installDaemonExitGuard}.
+ * - If `signal` is already aborted, rejects with `E_PI_ABORTED` WITHOUT invoking
+ *   `fn`. Otherwise the signal is propagated to `fn` (the caller threads it into
+ *   Pi's agent loop); an abort that surfaces as a thrown `AbortError`/`DOMException`
+ *   is normalized to `E_PI_ABORTED`.
+ * - Any other thrown value is normalized via {@link wrapPiError}.
+ *
+ * @typeParam T - The resolved value type of the wrapped call.
+ * @param fn - The Pi-touching async function. Receives the (live) `AbortSignal`
+ *   so it can thread cancellation into the agent loop.
+ * @param signal - Optional cancellation signal.
+ * @returns The resolved value of `fn`.
+ * @throws {PiContainmentError} On exit-trap, abort, or any failure from `fn`.
+ *
+ * @example
+ * ```ts
+ * const result = await wrapPiCall(async (sig) => runAgentLoop(prompts, ctx, cfg, emit, sig), signal);
+ * ```
+ */
+export declare function wrapPiCall<T>(fn: (signal: AbortSignal) => Promise<T>, signal?: AbortSignal): Promise<T>;
+//# sourceMappingURL=pi-errors.d.ts.map

package/dist/llm/pi/pi-errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pi-errors.d.ts","sourceRoot":"","sources":["../../../src/llm/pi/pi-errors.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AAEH,OAAO,EAAE,QAAQ,EAAE,MAAM,qBAAqB,CAAC;AAC/C,OAAO,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAG5C;;;;;;;GAOG;AACH,MAAM,MAAM,iBAAiB;AAC3B,yEAAyE;AACvE,2BAA2B;AAC7B,4EAA4E;GAC1E,iCAAiC;AACnC,sEAAsE;GACpE,cAAc;AAChB,qDAAqD;GACnD,kBAAkB,CAAC;AAEvB;;;;;;;;GAQG;AACH,qBAAa,kBAAmB,SAAQ,SAAS;IAC/C,qDAAqD;IACrD,QAAQ,CAAC,MAAM,EAAE,iBAAiB,CAAC;IAEnC;;;;;OAKG;gBAED,MAAM,EAAE,iBAAiB,EACzB,OAAO,EAAE,MAAM,EACf,OAAO,CAAC,EAAE;QAAE,KAAK,CAAC,EAAE,OAAO,CAAC;QAAC,QAAQ,CAAC,EAAE,QAAQ,CAAA;KAAE;CASrD;AAED;;;;;GAKG;AACH,wBAAgB,oBAAoB,CAAC,GAAG,EAAE,OAAO,GAAG,GAAG,IAAI,kBAAkB,CAE5E;AAED;;;;;;;;;GASG;AACH,wBAAgB,WAAW,CAAC,GAAG,EAAE,OAAO,GAAG,kBAAkB,CAI5D;AAwED;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,sBAAsB,IAAI,MAAM,IAAI,CAInD;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,sBAAsB,IAAI,IAAI,CAG7C;AAkDD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,wBAAsB,UAAU,CAAC,CAAC,EAChC,EAAE,EAAE,CAAC,MAAM,EAAE,WAAW,KAAK,OAAO,CAAC,CAAC,CAAC,EACvC,MAAM,CAAC,EAAE,WAAW,GACnB,OAAO,CAAC,CAAC,CAAC,CAwCZ"}