wicked-crew 0.7.7 → 0.7.9

package/dist/api/stall-watchdog.js

@@ -1,4 +1,5 @@
-// Worker stall watchdog (crew#287): platform-native liveness detection for executing runs.
+// Worker stall watchdog (crew#287 detection + crew#341 escalation): platform-native liveness
+// for executing runs, and — opt-in — recovery when liveness is gone.
 //
 // A wedged worker emits nothing — no unitOutputDelta, no gate frames — and its run sits in
 // `executing` until an operator notices by absence (run 8aa1cd42: a design unit burned 3+ hours
@@ -14,12 +15,41 @@
 // - once per quiet period: after the frame fires, the run stays alerted until a NEW event for
 //   it arrives; a second quiet period then emits a second frame.
 //
-// DETECTION ONLY. The watchdog never cancels, mutates, or re-dispatches a run — the operator
-// decides. The synthetic frame goes straight to the /ws fan-out, never back through the engine
-// relay, so it cannot stamp or re-arm itself.
-import { DEFAULT_WORKER_STALL_MINUTES } from '../core/types.js';
+// THE ESCALATION LADDER (crew#341) — detection now drives action, but only when armed:
+//
+//   notify (always)  →  act (opt-in, `workerStallEscalateMinutes` > 0)  →  fail loud
+//
+// - OFF BY DEFAULT. The issue's design: automatic recovery on a run that is merely slow rather
+//   than wedged would be worse than the wedge. `workerStallEscalateMinutes` absent/0 keeps the
+//   watchdog detection-only — bit-for-bit the crew#287 behaviour.
+// - When armed, a run still silent past the escalation threshold (never before the detection
+//   threshold — the ladder notifies before it acts) gets ONE escalation per quiet period:
+//   - action `reassign` (default): recycle the wedged cursor unit IN PLACE via the engine's
+//     `reassignUnit` — the stale turn is superseded (not folded as a failure), the worker
+//     session closed, the attempt bumped, the unit re-dispatched to the same seat; queued
+//     operator injects survive into the fresh turn. This is both of crew#341's candidate
+//     recoveries in one primitive.
+//   - action `notify`: the fail-loud rung — surface a `needsYou` frame + an audit entry and
+//     leave the run alone.
+// - A per-run budget (`workerStallMaxEscalations`, default 2) caps AUTOMATIC reassigns: a
+//   worker that wedges deterministically must reach a human, not loop through re-dispatches
+//   forever. A spent budget answers further quiet periods with `outcome: "exhausted"`.
+// - Every escalation is REPORTED on its own distinctly-named /ws frame —
+//   `workerStallEscalated` (`workerStalled` is already two producers deep: the daemon's
+//   synthetic detection frame AND the engine's PTY-path event) — and AUDITED via the crew
+//   audit trail (`run.stall.escalated`), because an automated actor touching a run is a
+//   privileged action exactly like an operator doing it.
+//
+// The synthetic frames go straight to the /ws fan-out, never back through the engine relay, so
+// they cannot stamp or re-arm the watchdog themselves. A SUCCESSFUL reassign, by contrast,
+// makes the engine emit real events (workerSessionClosed, unitReassigned, unitDispatched, …),
+// which restamp the clock and re-arm both stages — a re-wedged fresh turn walks the same ladder
+// with the remaining budget.
+import { DEFAULT_WORKER_STALL_ESCALATE_ACTION, DEFAULT_WORKER_STALL_MAX_ESCALATIONS, DEFAULT_WORKER_STALL_MINUTES, } from '../core/types.js';
 /** Default sweep cadence — frequent enough that `quietForMs` is at most ~30s stale. */
 export const DEFAULT_SWEEP_INTERVAL_MS = 30_000;
+/** Bound on the `error` excerpt an escalation frame / audit entry carries. */
+const ESCALATION_ERROR_EXCERPT_CHARS = 300;
 export class WorkerStallWatchdog {
     deps;
     /** run id → epoch ms of the last engine event observed for it (or the seed, see sweep). */
@@ -28,6 +58,10 @@ export class WorkerStallWatchdog {
     lastOrd = new Map();
     /** Runs already alerted for the CURRENT quiet period (cleared by any new event). */
     alerted = new Set();
+    /** Runs already escalated for the CURRENT quiet period (cleared by any new event). */
+    escalated = new Set();
+    /** run id → automatic reassigns consumed (the crew#341 budget). Pruned with the run. */
+    escalationCount = new Map();
     now;
     log;
     handle = null;
@@ -46,6 +80,7 @@ export class WorkerStallWatchdog {
         if (typeof event.ord === 'number')
             this.lastOrd.set(session, event.ord);
         this.alerted.delete(session);
+        this.escalated.delete(session);
     }
     /** One detection pass. Public so tests drive it directly; the armed interval calls it too. */
     async sweep() {
@@ -63,15 +98,19 @@ export class WorkerStallWatchdog {
             }
             const ids = new Set(executing.map((r) => r.id));
             // Prune state for runs no longer executing (completed / cancelled / awaiting_human):
-            // their silence is not a stall, and a later return to executing starts a fresh clock.
+            // their silence is not a stall, and a later return to executing starts a fresh clock —
+            // and a fresh escalation budget (the run left the wedge; a NEW wedge is a new fact).
             for (const key of [...this.lastEventAt.keys()]) {
                 if (!ids.has(key)) {
                     this.lastEventAt.delete(key);
                     this.lastOrd.delete(key);
                     this.alerted.delete(key);
+                    this.escalated.delete(key);
+                    this.escalationCount.delete(key);
                 }
             }
             const thresholdMs = await this.thresholdMs();
+            const escalation = await this.escalationArmed(thresholdMs);
             const now = this.now();
             for (const run of executing) {
                 const last = this.lastEventAt.get(run.id);
@@ -84,19 +123,29 @@ export class WorkerStallWatchdog {
                     continue;
                 }
                 const quietForMs = now - last;
-                if (quietForMs < thresholdMs || this.alerted.has(run.id))
-                    continue;
-                this.alerted.add(run.id);
-                const ord = this.lastOrd.get(run.id) ?? run.ord;
-                this.deps.broadcast({
-                    type: 'workerStalled',
-                    session: run.id,
-                    ...(ord !== undefined ? { ord } : {}),
-                    quietForMs,
-                });
-                this.log(`[stall-watchdog] run ${run.id}${ord !== undefined ? ` (unit ${ord})` : ''} silent for ` +
-                    `${(quietForMs / 60_000).toFixed(1)} min — workerStalled frame broadcast ` +
-                    `(detection only: the run was NOT touched; the operator decides)`);
+                // ── stage 1: detect + notify (crew#287, always on) ──────────────────────────────
+                if (quietForMs >= thresholdMs && !this.alerted.has(run.id)) {
+                    this.alerted.add(run.id);
+                    const ord = this.lastOrd.get(run.id) ?? run.ord;
+                    this.deps.broadcast({
+                        type: 'workerStalled',
+                        session: run.id,
+                        ...(ord !== undefined ? { ord } : {}),
+                        quietForMs,
+                    });
+                    this.log(`[stall-watchdog] run ${run.id}${ord !== undefined ? ` (unit ${ord})` : ''} silent for ` +
+                        `${(quietForMs / 60_000).toFixed(1)} min — workerStalled frame broadcast` +
+                        (escalation === undefined
+                            ? ` (detection only: the run was NOT touched; the operator decides)`
+                            : ` (escalation armed at ${(escalation.thresholdMs / 60_000).toFixed(1)} min)`));
+                }
+                // ── stage 2: act (crew#341, opt-in) — never before stage 1's threshold ──────────
+                if (escalation !== undefined &&
+                    quietForMs >= escalation.thresholdMs &&
+                    !this.escalated.has(run.id)) {
+                    this.escalated.add(run.id);
+                    await this.escalate(run, quietForMs, escalation);
+                }
             }
         }
         finally {
@@ -134,5 +183,130 @@ export class WorkerStallWatchdog {
             : DEFAULT_WORKER_STALL_MINUTES;
         return m * 60_000;
     }
+    /**
+     * Resolve the escalation stage for THIS sweep, or `undefined` while it is off. Fail-safe on
+     * a throwing config read: acting on a run is exactly the wrong response to uncertainty, so a
+     * failed read logs and keeps this sweep detection-only.
+     */
+    async escalationArmed(detectMs) {
+        if (this.deps.escalation === undefined)
+            return undefined;
+        let cfg;
+        try {
+            cfg = await this.deps.escalation.config();
+        }
+        catch (err) {
+            this.log(`[stall-watchdog] escalation config read failed, staying detection-only this sweep: ${String(err)}`);
+            return undefined;
+        }
+        const minutes = cfg?.minutes;
+        if (typeof minutes !== 'number' || !Number.isFinite(minutes) || minutes <= 0) {
+            return undefined; // OFF — the crew#341 default
+        }
+        const action = cfg?.action === 'notify' ? 'notify' : DEFAULT_WORKER_STALL_ESCALATE_ACTION;
+        const rawMax = cfg?.maxPerRun;
+        // Same 1..10 envelope the settings route enforces — the createServer override seam must
+        // not admit a budget large enough to hammer reassignUnit on a deterministically wedging run.
+        const maxPerRun = typeof rawMax === 'number' && Number.isFinite(rawMax) && Math.floor(rawMax) >= 1
+            ? Math.min(Math.floor(rawMax), 10)
+            : DEFAULT_WORKER_STALL_MAX_ESCALATIONS;
+        // The ladder notifies before it acts: an escalation threshold set below the detection
+        // threshold acts AT the detection threshold, never before it.
+        return { thresholdMs: Math.max(minutes * 60_000, detectMs), action, maxPerRun };
+    }
+    /** Perform one escalation for `run`, emit its `workerStallEscalated` frame, audit, log. */
+    async escalate(run, quietForMs, escalation) {
+        // Prefer the cursor ord read from the engine THIS sweep (`run.ord`) over the last event's
+        // ord: `reassignUnit` validates against the live cursor, and events can predate a rework.
+        const ord = run.ord ?? this.lastOrd.get(run.id);
+        const base = {
+            type: 'workerStallEscalated',
+            session: run.id,
+            ...(ord !== undefined ? { ord } : {}),
+            quietForMs,
+        };
+        let frame;
+        if (escalation.action === 'notify') {
+            // The fail-loud rung: surface for a human, touch nothing. No budget — notifying is free.
+            frame = { ...base, action: 'notify', outcome: 'ok', needsYou: true };
+        }
+        else {
+            const used = this.escalationCount.get(run.id) ?? 0;
+            if (used >= escalation.maxPerRun) {
+                frame = {
+                    ...base,
+                    action: 'reassign',
+                    outcome: 'exhausted',
+                    needsYou: true,
+                    escalations: used,
+                };
+            }
+            else if (ord === undefined) {
+                // Cannot name the cursor unit — the engine would reject any ord we invent. Loud, no
+                // budget consumed: nothing was attempted.
+                frame = {
+                    ...base,
+                    action: 'reassign',
+                    outcome: 'failed',
+                    needsYou: true,
+                    escalations: used,
+                    error: 'cursor unit unknown: the run listing carried no ord for this run',
+                };
+            }
+            else {
+                // Budget is consumed by the ATTEMPT, success or not — a rejecting engine call must not
+                // be retried indefinitely on the platform's own initiative.
+                this.escalationCount.set(run.id, used + 1);
+                try {
+                    await this.deps.escalation?.reassign(run.id, ord, run.cli);
+                    frame = {
+                        ...base,
+                        action: 'reassign',
+                        outcome: 'ok',
+                        needsYou: false,
+                        escalations: used + 1,
+                        ...(run.cli !== undefined ? { cli: run.cli } : {}),
+                    };
+                }
+                catch (err) {
+                    frame = {
+                        ...base,
+                        action: 'reassign',
+                        outcome: 'failed',
+                        needsYou: true,
+                        escalations: used + 1,
+                        error: String(err instanceof Error ? err.message : err).slice(0, ESCALATION_ERROR_EXCERPT_CHARS),
+                    };
+                }
+            }
+        }
+        this.deps.broadcast(frame);
+        try {
+            this.deps.escalation?.audit?.(frame);
+        }
+        catch (err) {
+            this.log(`[stall-watchdog] escalation audit sink failed: ${String(err)}`);
+        }
+        const where = `run ${run.id}${ord !== undefined ? ` (unit ${ord})` : ''}`;
+        const quiet = `${(quietForMs / 60_000).toFixed(1)} min silent`;
+        if (frame.action === 'notify') {
+            this.log(`[stall-watchdog] ESCALATED ${where}: ${quiet} — action notify (fail-loud): ` +
+                `needs-you frame broadcast, the run was NOT touched`);
+        }
+        else if (frame.outcome === 'ok') {
+            this.log(`[stall-watchdog] ESCALATED ${where}: ${quiet} — reassigned in place` +
+                `${run.cli !== undefined ? ` (seat ${run.cli})` : ''} ` +
+                `(automatic recovery ${frame.escalations}/${escalation.maxPerRun}; the stale turn is ` +
+                `superseded and the unit re-dispatched)`);
+        }
+        else if (frame.outcome === 'exhausted') {
+            this.log(`[stall-watchdog] ESCALATION EXHAUSTED for ${where}: ${quiet} and the per-run budget ` +
+                `(${escalation.maxPerRun}) is spent — needs-you frame broadcast; a human must intervene`);
+        }
+        else {
+            this.log(`[stall-watchdog] ESCALATION FAILED for ${where}: ${quiet} — the reassign did not ` +
+                `happen (${frame.error ?? 'unknown error'}); needs-you frame broadcast`);
+        }
+    }
 }
 //# sourceMappingURL=stall-watchdog.js.map

package/dist/api/stall-watchdog.js.map

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

package/dist/api/steering-landing.d.ts

@@ -0,0 +1,130 @@
+/**
+ * THE STEERING-AUTHOR LANDING (crew#388) — the post-approval write that closes TH-12.
+ *
+ * ## The defect
+ *
+ * The `steering-author` workflow's doctrine says "approved rules land via the rules CRUD with
+ * `provenance.source: "chat"` — the run itself writes nothing", and the propose phase tells the
+ * worker "do not write them yourself". Correct on both counts — evaluator≠creator — but NO
+ * component performed the write: the generic `POST /runs/:id/gate` only confirmed the gate, core
+ * has no steering-author hook, and the studio's `onRunResolved` only reloads rules. Every
+ * chat-authored rule ever approved was silently lost, orphaned as prose in the run's transcript
+ * (campaign 2026-09-01, scenario C5, run f3db4335).
+ *
+ * ## The design
+ *
+ * The landing is CREW-side, on APPROVE of the propose gate — the run keeps writing nothing to the
+ * store. The proposal is read machine-readably first: the propose phase now ALSO writes the
+ * proposed-rules JSON to a declared per-run artifact (`<steering inbox>/proposed-rules.json`,
+ * inside the run's own `extraWriteRoots`) — an ARTIFACT of the proposal, not a store write, so
+ * evaluator≠creator holds. Parsing the propose unit's stored transcript is the FALLBACK (runs
+ * launched before this fix, or a worker that ignored the file contract), and the cached gate
+ * prompt is the last resort (the transcript is written only on approval, so a store hiccup there
+ * still has the prompt core composed FROM that output).
+ *
+ * Invariants:
+ *  - AUDITABLE — every landed rule records `governance.rule.upserted` with the chat provenance
+ *    and the run id, exactly as the doctrine documents; a landing that could not happen records
+ *    `governance.steering.landing_failed` with the reason.
+ *  - IDEMPOTENT — a durable marker (`landed.json` beside the proposal) is written after a full
+ *    landing; a replayed approve (daemon restart mid-request, double-driven gate) finds it and
+ *    re-lands nothing. The rule write itself is an UPSERT keyed by rule id, so even a lost
+ *    marker degrades to a same-content overwrite, never a duplicate rule.
+ *  - FAIL-LOUD — when no source yields a parseable proposal the approve still succeeds for the
+ *    RUN (the gate decision is the operator's and already happened), but the response and the
+ *    audit trail carry an explicit `landing.outcome: "failed"` with the reason. A silent no-op
+ *    is the bug this module exists to end.
+ *  - AMEND-APPROVE — an approve carrying an amend note lands the proposal UNCHANGED: the amend
+ *    steers the RUN (core injects it into the run's continuation), not the rule text. An
+ *    operator who wants different rules rejects and re-authors; editing rule text inside a gate
+ *    note would land words nobody reviewed as JSON nobody saw.
+ */
+import type { CoreAdapter } from '../core/adapter.js';
+import type { Actor, ConformanceRule, SessionView, WorkflowDef } from '../core/types.js';
+export { STEERING_PROPOSAL_FILENAME } from './governance-steering.js';
+import type { AuditLog } from './audit.js';
+/** The workflow whose propose gate this landing serves. */
+export declare const STEERING_AUTHOR_WORKFLOW = "steering-author";
+/** Durable idempotency marker written beside the proposal after a full landing. */
+export declare const STEERING_LANDED_MARKER_FILENAME = "landed.json";
+/** Where the propose phase is told to write its machine-readable proposal. */
+export declare function steeringProposalPath(runId: string): string;
+/** Where a completed landing records what it landed (replay dedupe). */
+export declare function steeringLandedMarkerPath(runId: string): string;
+/**
+ * The steering fields a rule write may carry (the merged model's additions) — mirrored by
+ * `POST /governance/rules`, which refuses them on a pre-steering engine because the engine
+ * would silently DROP them and persist a rule that enforces differently than written. The
+ * landing applies the same guard: authored-then-downgraded is a loud landing failure, never
+ * a quiet field amputation.
+ */
+export declare const STEERING_RULE_FIELDS: readonly ["steering_type", "applies_to", "excludes", "weight", "effect", "trigger", "obligations", "criteria"];
+/** Where the landed proposal was read from, most-preferred first. */
+export type SteeringProposalSource = 'deliverable' | 'transcript' | 'gate-prompt';
+/**
+ * The `landing` field on the `POST /runs/:id/gate` (and gated `/resume`) 200 body — present
+ * ONLY when the approved gate was a steering-author propose gate. Published as
+ * `SteeringLandingResult` in wicked-crew-api-types.
+ */
+export interface SteeringLandingResult {
+    /** `landed` = every proposed rule is in the store; `failed` = the RUN still advanced but the
+     *  landing (wholly or partly) did not — `error` says why, and the audit trail carries it. */
+    outcome: 'landed' | 'failed';
+    /** Rule ids actually upserted (all of them on `landed`; the partial set on a partial `failed`). */
+    ruleIds: string[];
+    /** Where the proposal was read from. Absent when no source yielded one. */
+    source?: SteeringProposalSource;
+    /** `true` when a replayed approve found the durable marker — nothing was re-landed. */
+    alreadyLanded?: boolean;
+    /** Present iff `outcome: "failed"` — the loud, operator-readable reason. */
+    error?: string;
+}
+/** True when this run IS a steering-author run (by workflow id, or — for runs whose stored
+ *  `workflow_id` is core's `wf-<uuid>` instance id — by exact phase sequence). Defensive on a
+ *  view without a `workflow_id` (partial-stub adapters in tests; a free-text run has no def):
+ *  "not steering-author" is the honest answer there, and the legacy gate path must not 500. */
+export declare function isSteeringAuthorRun(run: SessionView, workflows: WorkflowDef[]): boolean;
+/**
+ * Recover the default steering type from the author route's own problem-statement preamble
+ * (`Author steering rules for the '<type>' steering type …`) so a proposed rule that omitted
+ * `steering_type` still lands on the sub-page the operator authored it for. `undefined` when
+ * the problem does not carry the preamble (a hand-launched run) — the engine's serde default
+ * (`architecture`) then applies, same as any other write.
+ */
+export declare function steeringTypeFromProblem(problem: string): string | undefined;
+/** A parsed-but-not-yet-normalized proposal entry. */
+type RawRule = Record<string, unknown>;
+/**
+ * Extract the proposed rules from free text — the whole text as JSON first (the deliverable
+ * file's shape), then each fenced code block, then every balanced top-level `[...]` in the
+ * text (the transcript / gate-prompt shape, where the JSON array is embedded in prose).
+ * `null` when nothing parses to a non-empty array of `{id, statement}` objects.
+ */
+export declare function extractProposedRules(text: string): RawRule[] | null;
+/**
+ * Stamp the chat provenance and the recovered default steering type onto one proposed rule.
+ * `source: "chat"` is FORCED, not defaulted — the landing is the doctrine's one write path for
+ * chat-authored rules, and a worker that wrote some other source into its proposal must not be
+ * able to disguise where the rule came from. Everything else passes through untouched: the
+ * ENGINE's upsert path is the one spelling of what a valid rule is.
+ */
+export declare function normalizeProposedRule(raw: RawRule, defaultType?: string): ConformanceRule;
+/** The adapter surface the landing needs — narrow, so tests stub exactly what runs. */
+export type SteeringLandingAdapter = Pick<CoreAdapter, 'workOutput' | 'upsertConformanceRule' | 'steeringSupported'>;
+export interface SteeringLandingDeps {
+    adapter: SteeringLandingAdapter;
+    audit: AuditLog;
+    actor: Actor;
+}
+/**
+ * Perform the landing for an APPROVED steering-author propose gate. Called AFTER
+ * `confirmGate` resolved — the gate decision is already durable; this function's only job is
+ * the write the doctrine promised. Never throws: every failure is folded into a loud
+ * `outcome: "failed"` result (and the audit trail), because a landing error must not turn an
+ * already-successful gate approval into an HTTP 500.
+ *
+ * `gatePrompt` is the cached gate prompt captured BEFORE the confirm (terminal events prune
+ * the cache) — the last-resort proposal source.
+ */
+export declare function landSteeringProposal(deps: SteeringLandingDeps, run: SessionView, gatePrompt?: string): Promise<SteeringLandingResult>;
+//# sourceMappingURL=steering-landing.d.ts.map

package/dist/api/steering-landing.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"steering-landing.d.ts","sourceRoot":"","sources":["../../src/api/steering-landing.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwCG;AAKH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AACtD,OAAO,KAAK,EAAE,KAAK,EAAE,eAAe,EAAE,WAAW,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAIzF,OAAO,EAAE,0BAA0B,EAAE,MAAM,0BAA0B,CAAC;AACtE,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAE3C,2DAA2D;AAC3D,eAAO,MAAM,wBAAwB,oBAAoB,CAAC;AAE1D,mFAAmF;AACnF,eAAO,MAAM,+BAA+B,gBAAgB,CAAC;AAE7D,8EAA8E;AAC9E,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAE1D;AAED,wEAAwE;AACxE,wBAAgB,wBAAwB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAE9D;AAED;;;;;;GAMG;AACH,eAAO,MAAM,oBAAoB,gHASvB,CAAC;AAEX,qEAAqE;AACrE,MAAM,MAAM,sBAAsB,GAAG,aAAa,GAAG,YAAY,GAAG,aAAa,CAAC;AAElF;;;;GAIG;AACH,MAAM,WAAW,qBAAqB;IACpC;iGAC6F;IAC7F,OAAO,EAAE,QAAQ,GAAG,QAAQ,CAAC;IAC7B,mGAAmG;IACnG,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,2EAA2E;IAC3E,MAAM,CAAC,EAAE,sBAAsB,CAAC;IAChC,uFAAuF;IACvF,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB,4EAA4E;IAC5E,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED;;;+FAG+F;AAC/F,wBAAgB,mBAAmB,CAAC,GAAG,EAAE,WAAW,EAAE,SAAS,EAAE,WAAW,EAAE,GAAG,OAAO,CAGvF;AAED;;;;;;GAMG;AACH,wBAAgB,uBAAuB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAI3E;AAED,sDAAsD;AACtD,KAAK,OAAO,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;AAyBvC;;;;;GAKG;AACH,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,EAAE,GAAG,IAAI,CA0DnE;AAED;;;;;;GAMG;AACH,wBAAgB,qBAAqB,CAAC,GAAG,EAAE,OAAO,EAAE,WAAW,CAAC,EAAE,MAAM,GAAG,eAAe,CAkBzF;AAED,uFAAuF;AACvF,MAAM,MAAM,sBAAsB,GAAG,IAAI,CACvC,WAAW,EACX,YAAY,GAAG,uBAAuB,GAAG,mBAAmB,CAC7D,CAAC;AAEF,MAAM,WAAW,mBAAmB;IAClC,OAAO,EAAE,sBAAsB,CAAC;IAChC,KAAK,EAAE,QAAQ,CAAC;IAChB,KAAK,EAAE,KAAK,CAAC;CACd;AAmBD;;;;;;;;;GASG;AACH,wBAAsB,oBAAoB,CACxC,IAAI,EAAE,mBAAmB,EACzB,GAAG,EAAE,WAAW,EAChB,UAAU,CAAC,EAAE,MAAM,GAClB,OAAO,CAAC,qBAAqB,CAAC,CAkJhC"}