@skillstate/opencode 2.2.1 → 3.0.0

package/dist/session-registry.d.ts

@@ -0,0 +1,148 @@
+/**
+ * Sub-agent session registry for the OpenCode v2 plugin.
+ *
+ * OpenCode spawns a CHILD SESSION for every sub-agent (the `task` tool and
+ * every custom agent). Those child sessions are first-class: they run the
+ * agent loop, call tools, and would otherwise all write to the SAME project
+ * state file — the last writer wins and the main agent's notes are silently
+ * clobbered mid-task.
+ *
+ * The v1 plugin inferred this from an in-process `Map` fed by an `event`
+ * hook. v2 exposes a real event stream (`ctx.event.subscribe()`), so the
+ * registry is an explicit, testable value object instead of module-level
+ * mutable state shared by tests and a single plugin instance.
+ *
+ * PARENT EDGES come from the server's own event stream. In OpenCode v2 the
+ * relevant payloads are:
+ *
+ * ```ts
+ * { type: "session.created", data: { sessionID: string, parentID?: string } }
+ * { type: "session.forked",  data: { sessionID: string, parentID: string } }
+ * { type: "session.deleted", data: { sessionID: string } }
+ * ```
+ *
+ * There is no `session.updated` event in v2, and the parent lives on
+ * `data.parentID` — not on a `properties.info` envelope as it did in v1.
+ * A session with a non-empty `parentID` is a sub-agent; a session with an
+ * absent or empty `parentID` is a root session. The registry never guesses
+ * from the id shape — a session that has not been observed on the stream
+ * yet is treated as a ROOT session (the safe default: it gets the shared
+ * project file, which is what a plain single-session user expects).
+ *
+ * LIFECYCLE: entries are refreshed on every event and evicted after
+ * {@link DEFAULT_SESSION_TTL_MS} of silence, so a long-lived OpenCode
+ * process does not accumulate one entry per session it has ever seen.
+ */
+/** How long a session stays registered after its last event. */
+export declare const DEFAULT_SESSION_TTL_MS: number;
+/** A session as observed on the OpenCode event stream. */
+export interface SessionRecord {
+    /** The host session id, verbatim. */
+    readonly id: string;
+    /** The parent session id, or `null` for a root session. */
+    readonly parentID: string | null;
+    /** Event receive time (epoch ms) — drives TTL eviction. */
+    readonly seenAt: number;
+}
+/**
+ * Options for {@link SessionRegistry}. Tests inject a clock and a TTL so
+ * eviction is deterministic.
+ */
+export interface SessionRegistryOptions {
+    /** Clock in epoch milliseconds. Defaults to `Date.now`. */
+    now?: () => number;
+    /** Idle time after which a session is evicted. Defaults to 6h. */
+    ttlMs?: number;
+    /** Cap on retained sessions; the oldest are evicted first. */
+    maxSessions?: number;
+}
+/**
+ * Tracks the session→parent forest reported by the OpenCode event stream.
+ *
+ * Every method is pure with respect to the plugin's other state: the
+ * registry only ever answers questions about the shape of the session tree.
+ */
+export declare class SessionRegistry {
+    private readonly sessions;
+    private readonly now;
+    private readonly ttlMs;
+    private readonly maxSessions;
+    constructor(options?: SessionRegistryOptions);
+    /**
+     * Fold one server event into the registry.
+     *
+     * `session.created` and `session.forked` register (or re-parent) a
+     * session; `session.deleted` forgets it. Any other event, and any
+     * malformed payload, is ignored — the stream carries far more than
+     * sessions and one odd record must never break the subscription loop.
+     *
+     * Returns the {@link SessionRecord} it wrote, or `null` when nothing was
+     * registered (including a deletion).
+     */
+    ingestEvent(event: unknown): SessionRecord | null;
+    /** The recorded session, or `undefined` when it was never observed. */
+    get(sessionID: string): SessionRecord | undefined;
+    /**
+     * Whether `sessionID` is a sub-agent session (a session with a parent).
+     *
+     * An UNOBSERVED session answers `false`: the plugin then treats it as a
+     * root session, which is the behaviour a single-session user expects and
+     * never creates a surprise `agents/` directory.
+     */
+    isSubAgent(sessionID: string): boolean;
+    /**
+     * The topmost ancestor of `sessionID` (itself when it is a root
+     * session). Follows parent edges with a visited set so a cycle — which a
+     * buggy or hostile event stream could produce — terminates instead of
+     * hanging the agent loop.
+     */
+    rootOf(sessionID: string): string;
+    /**
+     * Every session below `sessionID` in the tree - i.e. every session whose
+     * parent chain passes through `sessionID`, excluding `sessionID` itself.
+     *
+     * "Root ancestor" would be the wrong definition here: asked about a
+     * sub-agent it would also return that sub-agent, because the sub-agent's
+     * root is further up. Walking up to the queried session instead answers
+     * both cases uniformly, and a root session still gets every sub-agent.
+     *
+     * Sorted by id for a stable, testable result.
+     */
+    descendantsOf(sessionID: string): string[];
+    /**
+     * Whether `candidate` sits somewhere below `ancestor`. Cycle-safe: a
+     * parent chain that loops back on itself terminates instead of hanging
+     * the agent loop.
+     */
+    private isDescendantOf;
+    /** Every registered session, oldest-observed first. */
+    list(): readonly SessionRecord[];
+    /** How many sessions are currently registered. */
+    get size(): number;
+    /** Forget every session (test isolation, and a clean reload). */
+    clear(): void;
+    /**
+     * Drop sessions idle for longer than the TTL, then enforce the size cap
+     * by dropping the least-recently-seen entries. Called after every
+     * ingest; also exposed for tests.
+     */
+    evict(): void;
+}
+/**
+ * The on-disk scope name for a session: a stable, filesystem-safe id that
+ * keeps SUB-AGENT sessions in their own directory and root sessions on the
+ * shared project file.
+ *
+ * Returns `''` for a root session (the shared project state) and a
+ * sanitized `<parent>-<session>` id for a sub-agent.
+ *
+ * The child part is the FULL sanitized session id, not a short prefix. The
+ * v1 code truncated to 8 characters, which silently collapses two sibling
+ * sub-agents into one state file whenever their ids share a prefix — they
+ * overwrite each other's notes with no error. `sanitizeAgentId` caps the
+ * result at 64 characters, so the directory name stays bounded. The parent
+ * part is truncated to 8 characters because it only has to disambiguate
+ * which root a sub-agent belongs to.
+ */
+export declare function stateScopeFor(registry: SessionRegistry, sessionID: string): string;
+//# sourceMappingURL=session-registry.d.ts.map

package/dist/session-registry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"session-registry.d.ts","sourceRoot":"","sources":["../src/session-registry.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AAIH,gEAAgE;AAChE,eAAO,MAAM,sBAAsB,QAAqB,CAAC;AAEzD,0DAA0D;AAC1D,MAAM,WAAW,aAAa;IAC5B,qCAAqC;IACrC,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,2DAA2D;IAC3D,QAAQ,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACjC,2DAA2D;IAC3D,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACzB;AAED;;;GAGG;AACH,MAAM,WAAW,sBAAsB;IACrC,2DAA2D;IAC3D,GAAG,CAAC,EAAE,MAAM,MAAM,CAAC;IACnB,kEAAkE;IAClE,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,8DAA8D;IAC9D,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAkCD;;;;;GAKG;AACH,qBAAa,eAAe;IAC1B,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAoC;IAC7D,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAe;IACnC,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAS;IAC/B,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAS;IAErC,YAAY,OAAO,GAAE,sBAA2B,EAI/C;IAED;;;;;;;;;;OAUG;IACH,WAAW,CAAC,KAAK,EAAE,OAAO,GAAG,aAAa,GAAG,IAAI,CAehD;IAED,uEAAuE;IACvE,GAAG,CAAC,SAAS,EAAE,MAAM,GAAG,aAAa,GAAG,SAAS,CAEhD;IAED;;;;;;OAMG;IACH,UAAU,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAErC;IAED;;;;;OAKG;IACH,MAAM,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,CAUhC;IAED;;;;;;;;;;OAUG;IACH,aAAa,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,EAAE,CAQzC;IAED;;;;OAIG;IACH,OAAO,CAAC,cAAc;IActB,uDAAuD;IACvD,IAAI,IAAI,SAAS,aAAa,EAAE,CAE/B;IAED,kDAAkD;IAClD,IAAI,IAAI,IAAI,MAAM,CAEjB;IAED,iEAAiE;IACjE,KAAK,IAAI,IAAI,CAEZ;IAED;;;;OAIG;IACH,KAAK,IAAI,IAAI,CAYZ;CACF;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,aAAa,CAC3B,QAAQ,EAAE,eAAe,EACzB,SAAS,EAAE,MAAM,GAChB,MAAM,CAQR"}

package/dist/session-registry.js

@@ -0,0 +1,236 @@
+/**
+ * Sub-agent session registry for the OpenCode v2 plugin.
+ *
+ * OpenCode spawns a CHILD SESSION for every sub-agent (the `task` tool and
+ * every custom agent). Those child sessions are first-class: they run the
+ * agent loop, call tools, and would otherwise all write to the SAME project
+ * state file — the last writer wins and the main agent's notes are silently
+ * clobbered mid-task.
+ *
+ * The v1 plugin inferred this from an in-process `Map` fed by an `event`
+ * hook. v2 exposes a real event stream (`ctx.event.subscribe()`), so the
+ * registry is an explicit, testable value object instead of module-level
+ * mutable state shared by tests and a single plugin instance.
+ *
+ * PARENT EDGES come from the server's own event stream. In OpenCode v2 the
+ * relevant payloads are:
+ *
+ * ```ts
+ * { type: "session.created", data: { sessionID: string, parentID?: string } }
+ * { type: "session.forked",  data: { sessionID: string, parentID: string } }
+ * { type: "session.deleted", data: { sessionID: string } }
+ * ```
+ *
+ * There is no `session.updated` event in v2, and the parent lives on
+ * `data.parentID` — not on a `properties.info` envelope as it did in v1.
+ * A session with a non-empty `parentID` is a sub-agent; a session with an
+ * absent or empty `parentID` is a root session. The registry never guesses
+ * from the id shape — a session that has not been observed on the stream
+ * yet is treated as a ROOT session (the safe default: it gets the shared
+ * project file, which is what a plain single-session user expects).
+ *
+ * LIFECYCLE: entries are refreshed on every event and evicted after
+ * {@link DEFAULT_SESSION_TTL_MS} of silence, so a long-lived OpenCode
+ * process does not accumulate one entry per session it has ever seen.
+ */
+import { sanitizeAgentId } from '@skillstate/core';
+/** How long a session stays registered after its last event. */
+export const DEFAULT_SESSION_TTL_MS = 6 * 60 * 60 * 1000;
+const DEFAULT_MAX_SESSIONS = 512;
+function readSessionEvent(event) {
+    if (typeof event !== 'object' || event === null)
+        return null;
+    const type = event.type;
+    if (typeof type !== 'string')
+        return null;
+    if (type !== 'session.created' && type !== 'session.forked' && type !== 'session.deleted') {
+        return null;
+    }
+    const data = event.data;
+    if (typeof data !== 'object' || data === null)
+        return null;
+    const record = data;
+    if (typeof record.sessionID !== 'string' || record.sessionID.length === 0)
+        return null;
+    if (type === 'session.deleted')
+        return { kind: 'delete', id: record.sessionID };
+    const parent = typeof record.parentID === 'string' && record.parentID.length > 0 ? record.parentID : null;
+    return { kind: 'upsert', id: record.sessionID, parentID: parent };
+}
+/**
+ * Tracks the session→parent forest reported by the OpenCode event stream.
+ *
+ * Every method is pure with respect to the plugin's other state: the
+ * registry only ever answers questions about the shape of the session tree.
+ */
+export class SessionRegistry {
+    sessions = new Map();
+    now;
+    ttlMs;
+    maxSessions;
+    constructor(options = {}) {
+        this.now = options.now ?? Date.now;
+        this.ttlMs = options.ttlMs ?? DEFAULT_SESSION_TTL_MS;
+        this.maxSessions = options.maxSessions ?? DEFAULT_MAX_SESSIONS;
+    }
+    /**
+     * Fold one server event into the registry.
+     *
+     * `session.created` and `session.forked` register (or re-parent) a
+     * session; `session.deleted` forgets it. Any other event, and any
+     * malformed payload, is ignored — the stream carries far more than
+     * sessions and one odd record must never break the subscription loop.
+     *
+     * Returns the {@link SessionRecord} it wrote, or `null` when nothing was
+     * registered (including a deletion).
+     */
+    ingestEvent(event) {
+        const parsed = readSessionEvent(event);
+        if (parsed === null)
+            return null;
+        if (parsed.kind === 'delete') {
+            this.sessions.delete(parsed.id);
+            return null;
+        }
+        const record = {
+            id: parsed.id,
+            parentID: parsed.parentID,
+            seenAt: this.now(),
+        };
+        this.sessions.set(record.id, record);
+        this.evict();
+        return record;
+    }
+    /** The recorded session, or `undefined` when it was never observed. */
+    get(sessionID) {
+        return this.sessions.get(sessionID);
+    }
+    /**
+     * Whether `sessionID` is a sub-agent session (a session with a parent).
+     *
+     * An UNOBSERVED session answers `false`: the plugin then treats it as a
+     * root session, which is the behaviour a single-session user expects and
+     * never creates a surprise `agents/` directory.
+     */
+    isSubAgent(sessionID) {
+        return this.sessions.get(sessionID)?.parentID != null;
+    }
+    /**
+     * The topmost ancestor of `sessionID` (itself when it is a root
+     * session). Follows parent edges with a visited set so a cycle — which a
+     * buggy or hostile event stream could produce — terminates instead of
+     * hanging the agent loop.
+     */
+    rootOf(sessionID) {
+        let current = sessionID;
+        const visited = new Set([sessionID]);
+        for (;;) {
+            const record = this.sessions.get(current);
+            const parent = record?.parentID;
+            if (parent === undefined || parent === null || visited.has(parent))
+                return current;
+            visited.add(parent);
+            current = parent;
+        }
+    }
+    /**
+     * Every session below `sessionID` in the tree - i.e. every session whose
+     * parent chain passes through `sessionID`, excluding `sessionID` itself.
+     *
+     * "Root ancestor" would be the wrong definition here: asked about a
+     * sub-agent it would also return that sub-agent, because the sub-agent's
+     * root is further up. Walking up to the queried session instead answers
+     * both cases uniformly, and a root session still gets every sub-agent.
+     *
+     * Sorted by id for a stable, testable result.
+     */
+    descendantsOf(sessionID) {
+        const result = [];
+        for (const record of this.sessions.values()) {
+            if (record.id !== sessionID && this.isDescendantOf(record.id, sessionID)) {
+                result.push(record.id);
+            }
+        }
+        return result.sort();
+    }
+    /**
+     * Whether `candidate` sits somewhere below `ancestor`. Cycle-safe: a
+     * parent chain that loops back on itself terminates instead of hanging
+     * the agent loop.
+     */
+    isDescendantOf(candidate, ancestor) {
+        let current = candidate;
+        const visited = new Set([candidate]);
+        for (;;) {
+            const record = this.sessions.get(current);
+            const parent = record?.parentID ?? null;
+            if (parent === null)
+                return false;
+            if (parent === ancestor)
+                return true;
+            if (visited.has(parent))
+                return false;
+            visited.add(parent);
+            current = parent;
+        }
+    }
+    /** Every registered session, oldest-observed first. */
+    list() {
+        return [...this.sessions.values()].sort((a, b) => a.seenAt - b.seenAt || a.id.localeCompare(b.id));
+    }
+    /** How many sessions are currently registered. */
+    get size() {
+        return this.sessions.size;
+    }
+    /** Forget every session (test isolation, and a clean reload). */
+    clear() {
+        this.sessions.clear();
+    }
+    /**
+     * Drop sessions idle for longer than the TTL, then enforce the size cap
+     * by dropping the least-recently-seen entries. Called after every
+     * ingest; also exposed for tests.
+     */
+    evict() {
+        const cutoff = this.now() - this.ttlMs;
+        for (const [id, record] of this.sessions) {
+            if (record.seenAt < cutoff)
+                this.sessions.delete(id);
+        }
+        if (this.sessions.size <= this.maxSessions)
+            return;
+        const ordered = [...this.sessions.entries()].sort((a, b) => a[1].seenAt - b[1].seenAt || a[0].localeCompare(b[0]));
+        for (const [id] of ordered.slice(0, this.sessions.size - this.maxSessions)) {
+            this.sessions.delete(id);
+        }
+    }
+}
+/**
+ * The on-disk scope name for a session: a stable, filesystem-safe id that
+ * keeps SUB-AGENT sessions in their own directory and root sessions on the
+ * shared project file.
+ *
+ * Returns `''` for a root session (the shared project state) and a
+ * sanitized `<parent>-<session>` id for a sub-agent.
+ *
+ * The child part is the FULL sanitized session id, not a short prefix. The
+ * v1 code truncated to 8 characters, which silently collapses two sibling
+ * sub-agents into one state file whenever their ids share a prefix — they
+ * overwrite each other's notes with no error. `sanitizeAgentId` caps the
+ * result at 64 characters, so the directory name stays bounded. The parent
+ * part is truncated to 8 characters because it only has to disambiguate
+ * which root a sub-agent belongs to.
+ */
+export function stateScopeFor(registry, sessionID) {
+    const record = registry.get(sessionID);
+    if (record === undefined || record.parentID === null)
+        return '';
+    const child = sanitizeAgentId(sessionID);
+    const parentPrefix = sanitizeAgentId(record.parentID).slice(0, 8);
+    if (child.length === 0)
+        return parentPrefix;
+    if (parentPrefix.length === 0)
+        return child;
+    return `${parentPrefix}-${child}`;
+}
+//# sourceMappingURL=session-registry.js.map

package/dist/session-registry.js.map

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

package/dist/state-store.d.ts

@@ -0,0 +1,126 @@
+/**
+ * Project state persistence for the OpenCode v2 plugin.
+ *
+ * ONE store, THREE guarantees:
+ *
+ * 1. **Per-project addressing.** The state file is derived from the plugin
+ *    instance's location (`ctx.location.project.canonical`), never from
+ *    `process.cwd()`. The v1 plugin called `process.cwd()` on every hook;
+ *    in v2 a single OpenCode server serves many projects, so the process
+ *    cwd is simply the wrong answer. Two checkouts no longer share state.
+ *
+ * 2. **Per-session isolation.** A root session owns the shared project
+ *    file; a sub-agent session owns `agents/<scope>/skillstate.json` (see
+ *    `stateScopeFor`). Parallel sub-agents therefore never last-writer-win
+ *    over the main session's notes.
+ *
+ * 3. **Never lose a write.** Every mutation runs inside the core
+ *    cross-process lock ({@link withStateLock}) and lands via
+ *    {@link atomicWriteFile} (temp sibling → fsync → rename), so a crash
+ *    mid-write can never leave a truncated or interleaved state file. Reads
+ *    never throw: a missing or corrupt file reads as `{}`.
+ *
+ * The store is deliberately schema-free. It does not validate against a
+ * procedural spec: OpenCode sessions are free-form work, and forcing a
+ * fixed `goal`/`progress`/`next_steps` shape is what made the v1 prompt
+ * rewrite the user's actual task into a state machine.
+ */
+import type { StatePatch } from '@skillstate/core';
+/** A skillstate document: a plain JSON object. */
+export type StateDocument = Record<string, unknown>;
+/** Options for {@link ProjectStateStore}. */
+export interface ProjectStateStoreOptions {
+    /**
+     * The project directory the state file lives under. Prefer
+     * `ctx.location.project.canonical` — the canonical checkout, stable
+     * across worktrees.
+     */
+    directory: string;
+    /** Home directory, for the `$HOME` global bucket. Defaults to `os.homedir()`. */
+    home?: string;
+}
+/**
+ * The keys a patch actually changed, split by direction. Mirrors the
+ * `state.patch` MCP contract so behaviour is identical across hosts.
+ */
+export interface StateChanges {
+    readonly added: readonly string[];
+    readonly updated: readonly string[];
+    readonly deleted: readonly string[];
+}
+/** Top-level diff between two state documents. Pure. */
+export declare function diffDocuments(before: StateDocument, after: StateDocument): StateChanges;
+/**
+ * The state file for one session scope inside one project.
+ *
+ * `scope === ''` is the shared project file; any other scope is a
+ * sub-agent's isolated copy. Delegates to the core resolver (shared with
+ * the MCP server, the CLI and the other host adapters) so every host agrees
+ * on where a project's state lives.
+ */
+export declare function statePathFor(directory: string, scope: string, home?: string): string;
+/**
+ * Reads and merges the per-project state documents for a plugin instance.
+ *
+ * Stateless between calls apart from the filesystem, so it is safe to keep
+ * one instance per plugin and to construct it in tests without any global
+ * setup.
+ */
+export declare class ProjectStateStore {
+    private readonly directory;
+    private readonly home;
+    constructor(options: ProjectStateStoreOptions);
+    /** The project directory this store addresses. */
+    get projectDirectory(): string;
+    /** The absolute state file path for a scope (`''` = shared). */
+    pathFor(scope: string): string;
+    /**
+     * Whether a state file already exists for this scope. The plugin uses
+     * this to decide whether to inject the system hint at all — an untouched
+     * project must behave exactly like vanilla OpenCode.
+     */
+    exists(scope: string): boolean;
+    /**
+     * Read a scope's state. A missing, unreadable or corrupt file reads as
+     * `{}` — a best-effort read that never breaks the agent loop.
+     */
+    read(scope: string): StateDocument;
+    /**
+     * Apply a patch to a scope's state and persist it.
+     *
+     * The read, the merge and the write all happen inside the cross-process
+     * lock, so two sub-agents writing disjoint keys both survive — neither
+     * can clobber the other's write by reading a stale snapshot.
+     *
+     * Returns the merged document and the top-level change sets. A `null`
+     * value in the patch deletes that key (paper ⊕).
+     */
+    patch(scope: string, patch: StatePatch): Promise<{
+        state: StateDocument;
+        changes: StateChanges;
+    }>;
+    /**
+     * Fold a sub-agent's document into this scope's document.
+     *
+     * `keep` decides what happens when both sides set the same scalar:
+     * `'existing'` (default) keeps the receiving document's value, `'source'`
+     * takes the sub-agent's. Keys only present in the sub-agent are always
+     * taken, and `null` in either document is a deletion.
+     *
+     * The source document is left on disk — the merge is not destructive, so
+     * a sub-agent's notes remain inspectable after the fold.
+     */
+    merge(scope: string, sourceScope: string, keep?: 'existing' | 'source'): Promise<{
+        state: StateDocument;
+        changes: StateChanges;
+    }>;
+}
+/**
+ * Fold `source` into `target` under a conflict policy. Pure.
+ *
+ * Nested plain objects recurse. A `null` on either side is a deletion and
+ * wins outright — an explicit "remove this" is not a scalar conflict. Every
+ * other scalar conflict follows `keep`.
+ */
+export declare function mergeDocuments(target: StateDocument, source: StateDocument, keep: 'existing' | 'source'): StateDocument;
+//# sourceMappingURL=state-store.d.ts.map

package/dist/state-store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"state-store.d.ts","sourceRoot":"","sources":["../src/state-store.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAaH,OAAO,KAAK,EAAc,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAE/D,kDAAkD;AAClD,MAAM,MAAM,aAAa,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;AAEpD,6CAA6C;AAC7C,MAAM,WAAW,wBAAwB;IACvC;;;;OAIG;IACH,SAAS,EAAE,MAAM,CAAC;IAClB,iFAAiF;IACjF,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED;;;GAGG;AACH,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,KAAK,EAAE,SAAS,MAAM,EAAE,CAAC;IAClC,QAAQ,CAAC,OAAO,EAAE,SAAS,MAAM,EAAE,CAAC;IACpC,QAAQ,CAAC,OAAO,EAAE,SAAS,MAAM,EAAE,CAAC;CACrC;AAED,wDAAwD;AACxD,wBAAgB,aAAa,CAC3B,MAAM,EAAE,aAAa,EACrB,KAAK,EAAE,aAAa,GACnB,YAAY,CAed;AAED;;;;;;;GAOG;AACH,wBAAgB,YAAY,CAC1B,SAAS,EAAE,MAAM,EACjB,KAAK,EAAE,MAAM,EACb,IAAI,GAAE,MAAqB,GAC1B,MAAM,CAER;AAED;;;;;;GAMG;AACH,qBAAa,iBAAiB;IAC5B,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAS;IACnC,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAS;IAE9B,YAAY,OAAO,EAAE,wBAAwB,EAG5C;IAED,kDAAkD;IAClD,IAAI,gBAAgB,IAAI,MAAM,CAE7B;IAED,gEAAgE;IAChE,OAAO,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAE7B;IAED;;;;OAIG;IACH,MAAM,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAM7B;IAED;;;OAGG;IACH,IAAI,CAAC,KAAK,EAAE,MAAM,GAAG,aAAa,CAQjC;IAED;;;;;;;;;OASG;IACG,KAAK,CACT,KAAK,EAAE,MAAM,EACb,KAAK,EAAE,UAAU,GAChB,OAAO,CAAC;QAAE,KAAK,EAAE,aAAa,CAAC;QAAC,OAAO,EAAE,YAAY,CAAA;KAAE,CAAC,CAY1D;IAED;;;;;;;;;;OAUG;IACG,KAAK,CACT,KAAK,EAAE,MAAM,EACb,WAAW,EAAE,MAAM,EACnB,IAAI,GAAE,UAAU,GAAG,QAAqB,GACvC,OAAO,CAAC;QAAE,KAAK,EAAE,aAAa,CAAC;QAAC,OAAO,EAAE,YAAY,CAAA;KAAE,CAAC,CAoB1D;CACF;AAED;;;;;;GAMG;AACH,wBAAgB,cAAc,CAC5B,MAAM,EAAE,aAAa,EACrB,MAAM,EAAE,aAAa,EACrB,IAAI,EAAE,UAAU,GAAG,QAAQ,GAC1B,aAAa,CAsBf"}