@ai-devkit/agent-manager 0.35.0 → 0.37.0

package/dist/utils/jsonlTail.js

@@ -0,0 +1,238 @@
+/**
+ * Tail reader for append-only JSONL transcripts.
+ *
+ * Reading the last N conversation messages from a large transcript should not
+ * require reading (and JSON-parsing) the whole file. This reader:
+ *
+ * 1. On the first call for a file, reads backward from the end in fixed-size
+ *    chunks until enough messages are collected (or the start is reached).
+ * 2. Remembers `{dev, ino, offset}` plus a small window of parsed items, and
+ *    on later calls parses only bytes appended since `offset`.
+ * 3. Resets (re-reads from the end) when the file is truncated or replaced by
+ *    a different inode.
+ *
+ * Each adapter supplies a {@link JsonlTailSource}: `parseLine` maps one raw
+ * line to a candidate item (or null) and the optional `finalize` turns a
+ * contiguous window of items into messages. `finalize` exists for formats
+ * where one line's visibility depends on other lines (e.g. Codex drops an
+ * `event_msg` mirrored by a `response_item`); line-independent formats can
+ * omit it and return a {@link ConversationMessage} directly from `parseLine`.
+ */ import * as fs from "fs";
+/**
+ * Normalize a `tail` option: a positive integer, or undefined for "full
+ * conversation" (the pre-existing behaviour).
+ */ export function normalizeTail(tail) {
+    if (tail === undefined || !Number.isFinite(tail)) return undefined;
+    const n = Math.floor(tail);
+    return n > 0 ? n : undefined;
+}
+/** Keep the last `tail` messages of an already fully-parsed conversation. */ export function sliceTail(messages, tail) {
+    const n = normalizeTail(tail);
+    return n !== undefined && messages.length > n ? messages.slice(-n) : messages;
+}
+export const DEFAULT_TAIL_CHUNK_SIZE = 64 * 1024;
+const DEFAULT_MAX_FILES = 16;
+const NEWLINE = 0x0a;
+const ANCHOR_BYTES = 32;
+export class JsonlTailReader {
+    chunkSize;
+    maxFiles;
+    cache = new Map();
+    constructor(options = {}){
+        this.chunkSize = Math.max(1, options.chunkSize ?? DEFAULT_TAIL_CHUNK_SIZE);
+        this.maxFiles = Math.max(1, options.maxFiles ?? DEFAULT_MAX_FILES);
+    }
+    /**
+   * Return the last `tail` messages of `filePath`.
+   *
+   * @param variant  Cache discriminator for sources whose output differs by
+   *                 option (e.g. verbose vs. non-verbose).
+   * @param overscan Extra messages collected beyond `tail` before trimming,
+   *                 for sources whose `finalize` looks at neighbouring lines.
+   */ read(filePath, tail, source, variant = "", overscan = 0) {
+        const key = `${variant}\0${tail}\0${filePath}`;
+        const threshold = tail + Math.max(0, overscan);
+        let stat;
+        try {
+            stat = fs.statSync(filePath);
+        } catch  {
+            this.cache.delete(key);
+            return [];
+        }
+        const cached = this.cache.get(key);
+        if (cached && cached.dev === stat.dev && cached.ino === stat.ino && cached.size === stat.size && cached.mtimeMs === stat.mtimeMs) {
+            this.touch(key, cached);
+            return cached.result.slice();
+        }
+        let fd;
+        try {
+            fd = fs.openSync(filePath, "r");
+        } catch  {
+            this.cache.delete(key);
+            return [];
+        }
+        try {
+            const current = fs.fstatSync(fd);
+            const canAppend = cached !== undefined && cached.dev === current.dev && cached.ino === current.ino && current.size >= cached.offset && // A very large append is cheaper to re-read from the end.
+            current.size - cached.offset <= Math.max(this.chunkSize * 16, 1024 * 1024);
+            const state = canAppend && this.readAppended(fd, current, cached, tail, threshold, source) || this.readBackward(fd, current, tail, threshold, source);
+            this.touch(key, state);
+            return state.result.slice();
+        } catch  {
+            this.cache.delete(key);
+            return [];
+        } finally{
+            fs.closeSync(fd);
+        }
+    }
+    /** Forget all cached windows. */ clear() {
+        this.cache.clear();
+    }
+    readBackward(fd, stat, tail, threshold, source) {
+        const reversed = [];
+        let partial = null;
+        let offset = 0;
+        let sawNewline = false;
+        // Pieces of the line currently being assembled, in file order.
+        let pending = [];
+        let pos = stat.size;
+        const takeLine = (piece)=>{
+            const lineBuf = pending.length === 0 ? piece : Buffer.concat([
+                piece,
+                ...pending
+            ]);
+            pending = [];
+            if (!sawNewline) {
+                // Bytes after the file's last newline: an unterminated (possibly
+                // still being written) line. Parsed tentatively, never cached.
+                sawNewline = true;
+                partial = this.parse(lineBuf, source);
+                return;
+            }
+            const item = this.parse(lineBuf, source);
+            if (item !== null) reversed.push(item);
+        };
+        while(pos > 0){
+            const len = Math.min(this.chunkSize, pos);
+            pos -= len;
+            const buf = readExactly(fd, pos, len);
+            let end = len;
+            let nl = end > 0 ? buf.lastIndexOf(NEWLINE, end - 1) : -1;
+            while(nl !== -1){
+                if (!sawNewline) offset = pos + nl + 1;
+                takeLine(buf.subarray(nl + 1, end));
+                end = nl;
+                nl = end > 0 ? buf.lastIndexOf(NEWLINE, end - 1) : -1;
+            }
+            if (end > 0) pending.unshift(buf.subarray(0, end));
+            if (this.countMessages(reversed, partial, source, threshold) >= threshold) break;
+        }
+        if (pos === 0 && pending.length > 0) {
+            // The first line of the file (no newline before it).
+            const first = pending.shift();
+            takeLine(first);
+        }
+        const items = reversed.reverse();
+        return {
+            dev: stat.dev,
+            ino: stat.ino,
+            size: stat.size,
+            mtimeMs: stat.mtimeMs,
+            offset,
+            anchor: readAnchor(fd, offset),
+            items,
+            result: this.finish(items, partial, source, tail)
+        };
+    }
+    /**
+   * Parse bytes appended since the cached offset. Returns null when the
+   * bytes before the offset no longer match (file rewritten in place).
+   */ readAppended(fd, stat, cached, tail, threshold, source) {
+        let items = cached.items;
+        let offset = cached.offset;
+        let partial = null;
+        const anchorLength = cached.anchor.length;
+        const raw = readExactly(fd, cached.offset - anchorLength, stat.size - offset + anchorLength);
+        if (!raw.subarray(0, anchorLength).equals(cached.anchor)) return null;
+        const buf = raw.subarray(anchorLength);
+        let anchor = cached.anchor;
+        if (buf.length > 0) {
+            const added = [];
+            let start = 0;
+            let nl = buf.indexOf(NEWLINE, start);
+            while(nl !== -1){
+                const item = this.parse(buf.subarray(start, nl), source);
+                if (item !== null) added.push(item);
+                start = nl + 1;
+                nl = buf.indexOf(NEWLINE, start);
+            }
+            offset = cached.offset + start;
+            if (start > 0) anchor = tailBytes(raw.subarray(0, anchorLength + start));
+            if (start < buf.length) partial = this.parse(buf.subarray(start), source);
+            if (added.length > 0) {
+                items = items.concat(added);
+                // Bound the retained window; keep a generous margin so sources whose
+                // finalize() drops items (e.g. de-duplication) still cover `tail`.
+                if (items.length > threshold * 4) items = items.slice(-threshold * 2);
+            }
+        }
+        return {
+            dev: stat.dev,
+            ino: stat.ino,
+            size: stat.size,
+            mtimeMs: stat.mtimeMs,
+            offset,
+            anchor,
+            items,
+            result: this.finish(items, partial, source, tail)
+        };
+    }
+    parse(lineBuf, source) {
+        const line = lineBuf.toString("utf-8");
+        if (line.trim().length === 0) return null;
+        return source.parseLine(line);
+    }
+    countMessages(reversed, partial, source, threshold) {
+        const available = reversed.length + (partial === null ? 0 : 1);
+        if (!source.finalize || available < threshold) return available;
+        const window = reversed.slice().reverse();
+        if (partial !== null) window.push(partial);
+        return source.finalize(window).length;
+    }
+    finish(items, partial, source, tail) {
+        const window = partial === null ? items : [
+            ...items,
+            partial
+        ];
+        const messages = source.finalize ? source.finalize(window) : window.slice();
+        return messages.length > tail ? messages.slice(-tail) : messages;
+    }
+    touch(key, state) {
+        this.cache.delete(key);
+        this.cache.set(key, state);
+        while(this.cache.size > this.maxFiles){
+            const oldest = this.cache.keys().next().value;
+            if (oldest === undefined) break;
+            this.cache.delete(oldest);
+        }
+    }
+}
+function readExactly(fd, position, length) {
+    const buf = Buffer.allocUnsafe(length);
+    let filled = 0;
+    while(filled < length){
+        const n = fs.readSync(fd, buf, filled, length - filled, position + filled);
+        if (n === 0) break;
+        filled += n;
+    }
+    return filled === length ? buf : buf.subarray(0, filled);
+}
+function readAnchor(fd, offset) {
+    const start = Math.max(0, offset - ANCHOR_BYTES);
+    return Buffer.from(readExactly(fd, start, offset - start));
+}
+function tailBytes(buf) {
+    return Buffer.from(buf.subarray(Math.max(0, buf.length - ANCHOR_BYTES)));
+}
+
+//# sourceMappingURL=jsonlTail.js.map

package/dist/utils/jsonlTail.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/utils/jsonlTail.ts"],"sourcesContent":["/**\n * Tail reader for append-only JSONL transcripts.\n *\n * Reading the last N conversation messages from a large transcript should not\n * require reading (and JSON-parsing) the whole file. This reader:\n *\n * 1. On the first call for a file, reads backward from the end in fixed-size\n *    chunks until enough messages are collected (or the start is reached).\n * 2. Remembers `{dev, ino, offset}` plus a small window of parsed items, and\n *    on later calls parses only bytes appended since `offset`.\n * 3. Resets (re-reads from the end) when the file is truncated or replaced by\n *    a different inode.\n *\n * Each adapter supplies a {@link JsonlTailSource}: `parseLine` maps one raw\n * line to a candidate item (or null) and the optional `finalize` turns a\n * contiguous window of items into messages. `finalize` exists for formats\n * where one line's visibility depends on other lines (e.g. Codex drops an\n * `event_msg` mirrored by a `response_item`); line-independent formats can\n * omit it and return a {@link ConversationMessage} directly from `parseLine`.\n */\n\nimport * as fs from \"fs\";\nimport type { ConversationMessage } from \"../adapters/AgentAdapter.js\";\n\n/**\n * Normalize a `tail` option: a positive integer, or undefined for \"full\n * conversation\" (the pre-existing behaviour).\n */\nexport function normalizeTail(tail: number | undefined): number | undefined {\n  if (tail === undefined || !Number.isFinite(tail)) return undefined;\n  const n = Math.floor(tail);\n  return n > 0 ? n : undefined;\n}\n\n/** Keep the last `tail` messages of an already fully-parsed conversation. */\nexport function sliceTail<T>(messages: T[], tail: number | undefined): T[] {\n  const n = normalizeTail(tail);\n  return n !== undefined && messages.length > n ? messages.slice(-n) : messages;\n}\n\nexport const DEFAULT_TAIL_CHUNK_SIZE = 64 * 1024;\nconst DEFAULT_MAX_FILES = 16;\nconst NEWLINE = 0x0a;\nconst ANCHOR_BYTES = 32;\n\nexport interface JsonlTailSource<Item> {\n  /** Map one raw JSONL line (no trailing newline) to an item, or null to skip it. */\n  parseLine(line: string): Item | null;\n  /**\n   * Convert a contiguous window of items (oldest first) into messages. Must\n   * behave like the adapter's full parse restricted to that window. Defaults\n   * to treating every item as a {@link ConversationMessage}.\n   */\n  finalize?(items: Item[]): ConversationMessage[];\n}\n\nexport interface JsonlTailReaderOptions {\n  /** Bytes read per backward step. Defaults to 64 KiB. */\n  chunkSize?: number;\n  /** Number of (file, variant, tail) windows kept in the LRU cache. */\n  maxFiles?: number;\n}\n\ninterface TailState {\n  dev: number;\n  ino: number;\n  size: number;\n  mtimeMs: number;\n  /** Byte offset just past the last newline consumed; appends are read from here. */\n  offset: number;\n  /**\n   * Up to {@link ANCHOR_BYTES} bytes ending at `offset`. Re-checked before an\n   * incremental read so a same-inode truncate-and-regrow is detected.\n   */\n  anchor: Buffer;\n  /** Parsed items from complete (newline-terminated) lines, oldest first. */\n  items: unknown[];\n  /** Last computed result, returned as-is while the file is unchanged. */\n  result: ConversationMessage[];\n}\n\nexport class JsonlTailReader {\n  private readonly chunkSize: number;\n  private readonly maxFiles: number;\n  private readonly cache = new Map<string, TailState>();\n\n  constructor(options: JsonlTailReaderOptions = {}) {\n    this.chunkSize = Math.max(1, options.chunkSize ?? DEFAULT_TAIL_CHUNK_SIZE);\n    this.maxFiles = Math.max(1, options.maxFiles ?? DEFAULT_MAX_FILES);\n  }\n\n  /**\n   * Return the last `tail` messages of `filePath`.\n   *\n   * @param variant  Cache discriminator for sources whose output differs by\n   *                 option (e.g. verbose vs. non-verbose).\n   * @param overscan Extra messages collected beyond `tail` before trimming,\n   *                 for sources whose `finalize` looks at neighbouring lines.\n   */\n  read<Item>(\n    filePath: string,\n    tail: number,\n    source: JsonlTailSource<Item>,\n    variant = \"\",\n    overscan = 0,\n  ): ConversationMessage[] {\n    const key = `${variant}\\0${tail}\\0${filePath}`;\n    const threshold = tail + Math.max(0, overscan);\n\n    let stat: fs.Stats;\n    try {\n      stat = fs.statSync(filePath);\n    } catch {\n      this.cache.delete(key);\n      return [];\n    }\n\n    const cached = this.cache.get(key);\n    if (\n      cached &&\n      cached.dev === stat.dev &&\n      cached.ino === stat.ino &&\n      cached.size === stat.size &&\n      cached.mtimeMs === stat.mtimeMs\n    ) {\n      this.touch(key, cached);\n      return cached.result.slice();\n    }\n\n    let fd: number;\n    try {\n      fd = fs.openSync(filePath, \"r\");\n    } catch {\n      this.cache.delete(key);\n      return [];\n    }\n\n    try {\n      const current = fs.fstatSync(fd);\n      const canAppend =\n        cached !== undefined &&\n        cached.dev === current.dev &&\n        cached.ino === current.ino &&\n        current.size >= cached.offset &&\n        // A very large append is cheaper to re-read from the end.\n        current.size - cached.offset <= Math.max(this.chunkSize * 16, 1024 * 1024);\n\n      const state =\n        (canAppend && this.readAppended(fd, current, cached, tail, threshold, source)) ||\n        this.readBackward(fd, current, tail, threshold, source);\n      this.touch(key, state);\n      return state.result.slice();\n    } catch {\n      this.cache.delete(key);\n      return [];\n    } finally {\n      fs.closeSync(fd);\n    }\n  }\n\n  /** Forget all cached windows. */\n  clear(): void {\n    this.cache.clear();\n  }\n\n  private readBackward<Item>(\n    fd: number,\n    stat: fs.Stats,\n    tail: number,\n    threshold: number,\n    source: JsonlTailSource<Item>,\n  ): TailState {\n    const reversed: Item[] = [];\n    let partial: Item | null = null;\n    let offset = 0;\n    let sawNewline = false;\n    // Pieces of the line currently being assembled, in file order.\n    let pending: Buffer[] = [];\n    let pos = stat.size;\n\n    const takeLine = (piece: Buffer): void => {\n      const lineBuf = pending.length === 0 ? piece : Buffer.concat([piece, ...pending]);\n      pending = [];\n      if (!sawNewline) {\n        // Bytes after the file's last newline: an unterminated (possibly\n        // still being written) line. Parsed tentatively, never cached.\n        sawNewline = true;\n        partial = this.parse(lineBuf, source);\n        return;\n      }\n      const item = this.parse(lineBuf, source);\n      if (item !== null) reversed.push(item);\n    };\n\n    while (pos > 0) {\n      const len = Math.min(this.chunkSize, pos);\n      pos -= len;\n      const buf = readExactly(fd, pos, len);\n\n      let end = len;\n      let nl = end > 0 ? buf.lastIndexOf(NEWLINE, end - 1) : -1;\n      while (nl !== -1) {\n        if (!sawNewline) offset = pos + nl + 1;\n        takeLine(buf.subarray(nl + 1, end));\n        end = nl;\n        nl = end > 0 ? buf.lastIndexOf(NEWLINE, end - 1) : -1;\n      }\n      if (end > 0) pending.unshift(buf.subarray(0, end));\n\n      if (this.countMessages(reversed, partial, source, threshold) >= threshold) break;\n    }\n\n    if (pos === 0 && pending.length > 0) {\n      // The first line of the file (no newline before it).\n      const first = pending.shift()!;\n      takeLine(first);\n    }\n\n    const items = reversed.reverse();\n    return {\n      dev: stat.dev,\n      ino: stat.ino,\n      size: stat.size,\n      mtimeMs: stat.mtimeMs,\n      offset,\n      anchor: readAnchor(fd, offset),\n      items,\n      result: this.finish(items, partial, source, tail),\n    };\n  }\n\n  /**\n   * Parse bytes appended since the cached offset. Returns null when the\n   * bytes before the offset no longer match (file rewritten in place).\n   */\n  private readAppended<Item>(\n    fd: number,\n    stat: fs.Stats,\n    cached: TailState,\n    tail: number,\n    threshold: number,\n    source: JsonlTailSource<Item>,\n  ): TailState | null {\n    let items = cached.items as Item[];\n    let offset = cached.offset;\n    let partial: Item | null = null;\n\n    const anchorLength = cached.anchor.length;\n    const raw = readExactly(fd, cached.offset - anchorLength, stat.size - offset + anchorLength);\n    if (!raw.subarray(0, anchorLength).equals(cached.anchor)) return null;\n    const buf = raw.subarray(anchorLength);\n    let anchor = cached.anchor;\n\n    if (buf.length > 0) {\n      const added: Item[] = [];\n      let start = 0;\n      let nl = buf.indexOf(NEWLINE, start);\n      while (nl !== -1) {\n        const item = this.parse(buf.subarray(start, nl), source);\n        if (item !== null) added.push(item);\n        start = nl + 1;\n        nl = buf.indexOf(NEWLINE, start);\n      }\n      offset = cached.offset + start;\n      if (start > 0) anchor = tailBytes(raw.subarray(0, anchorLength + start));\n      if (start < buf.length) partial = this.parse(buf.subarray(start), source);\n\n      if (added.length > 0) {\n        items = items.concat(added);\n        // Bound the retained window; keep a generous margin so sources whose\n        // finalize() drops items (e.g. de-duplication) still cover `tail`.\n        if (items.length > threshold * 4) items = items.slice(-threshold * 2);\n      }\n    }\n\n    return {\n      dev: stat.dev,\n      ino: stat.ino,\n      size: stat.size,\n      mtimeMs: stat.mtimeMs,\n      offset,\n      anchor,\n      items,\n      result: this.finish(items, partial, source, tail),\n    };\n  }\n\n  private parse<Item>(lineBuf: Buffer, source: JsonlTailSource<Item>): Item | null {\n    const line = lineBuf.toString(\"utf-8\");\n    if (line.trim().length === 0) return null;\n    return source.parseLine(line);\n  }\n\n  private countMessages<Item>(\n    reversed: Item[],\n    partial: Item | null,\n    source: JsonlTailSource<Item>,\n    threshold: number,\n  ): number {\n    const available = reversed.length + (partial === null ? 0 : 1);\n    if (!source.finalize || available < threshold) return available;\n    const window = reversed.slice().reverse();\n    if (partial !== null) window.push(partial);\n    return source.finalize(window).length;\n  }\n\n  private finish<Item>(\n    items: Item[],\n    partial: Item | null,\n    source: JsonlTailSource<Item>,\n    tail: number,\n  ): ConversationMessage[] {\n    const window = partial === null ? items : [...items, partial];\n    const messages = source.finalize\n      ? source.finalize(window)\n      : (window as unknown as ConversationMessage[]).slice();\n    return messages.length > tail ? messages.slice(-tail) : messages;\n  }\n\n  private touch(key: string, state: TailState): void {\n    this.cache.delete(key);\n    this.cache.set(key, state);\n    while (this.cache.size > this.maxFiles) {\n      const oldest = this.cache.keys().next().value;\n      if (oldest === undefined) break;\n      this.cache.delete(oldest);\n    }\n  }\n}\n\nfunction readExactly(fd: number, position: number, length: number): Buffer {\n  const buf = Buffer.allocUnsafe(length);\n  let filled = 0;\n  while (filled < length) {\n    const n = fs.readSync(fd, buf, filled, length - filled, position + filled);\n    if (n === 0) break;\n    filled += n;\n  }\n  return filled === length ? buf : buf.subarray(0, filled);\n}\n\nfunction readAnchor(fd: number, offset: number): Buffer {\n  const start = Math.max(0, offset - ANCHOR_BYTES);\n  return Buffer.from(readExactly(fd, start, offset - start));\n}\n\nfunction tailBytes(buf: Buffer): Buffer {\n  return Buffer.from(buf.subarray(Math.max(0, buf.length - ANCHOR_BYTES)));\n}\n"],"names":["fs","normalizeTail","tail","undefined","Number","isFinite","n","Math","floor","sliceTail","messages","length","slice","DEFAULT_TAIL_CHUNK_SIZE","DEFAULT_MAX_FILES","NEWLINE","ANCHOR_BYTES","JsonlTailReader","chunkSize","maxFiles","cache","Map","options","max","read","filePath","source","variant","overscan","key","threshold","stat","statSync","delete","cached","get","dev","ino","size","mtimeMs","touch","result","fd","openSync","current","fstatSync","canAppend","offset","state","readAppended","readBackward","closeSync","clear","reversed","partial","sawNewline","pending","pos","takeLine","piece","lineBuf","Buffer","concat","parse","item","push","len","min","buf","readExactly","end","nl","lastIndexOf","subarray","unshift","countMessages","first","shift","items","reverse","anchor","readAnchor","finish","anchorLength","raw","equals","added","start","indexOf","tailBytes","line","toString","trim","parseLine","available","finalize","window","set","oldest","keys","next","value","position","allocUnsafe","filled","readSync","from"],"mappings":"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"}

package/dist/utils/matching.d.ts

@@ -5,7 +5,9 @@
  * based on CWD and birth-time proximity to process start time.
  */
 import type { ProcessInfo } from "../adapters/AgentAdapter.js";
+import { MATCH_TOLERANCE_MS } from "./matchingConstants.js";
 import type { SessionFile } from "./session.js";
+export { MATCH_TOLERANCE_MS };
 /**
  * Result of matching a process to a session file.
  */

package/dist/utils/matching.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"matching.d.ts","sourceRoot":"","sources":["../../src/utils/matching.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAGH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,6BAA6B,CAAC;AAC/D,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AAKhD;;GAEG;AACH,MAAM,WAAW,WAAW;IAC1B,0BAA0B;IAC1B,OAAO,EAAE,WAAW,CAAC;IAErB,+BAA+B;IAC/B,OAAO,EAAE,WAAW,CAAC;IAErB,6EAA6E;IAC7E,OAAO,EAAE,MAAM,CAAC;CACjB;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,wBAAwB,CACtC,SAAS,EAAE,WAAW,EAAE,EACxB,QAAQ,EAAE,WAAW,EAAE,GACtB,WAAW,EAAE,CAsCf;AAED;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,MAAM,CAOlE"}
+{"version":3,"file":"matching.d.ts","sourceRoot":"","sources":["../../src/utils/matching.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAGH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,6BAA6B,CAAC;AAC/D,OAAO,EAAE,kBAAkB,EAAE,MAAM,wBAAwB,CAAC;AAC5D,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AAEhD,OAAO,EAAE,kBAAkB,EAAE,CAAC;AAE9B;;GAEG;AACH,MAAM,WAAW,WAAW;IAC1B,0BAA0B;IAC1B,OAAO,EAAE,WAAW,CAAC;IAErB,+BAA+B;IAC/B,OAAO,EAAE,WAAW,CAAC;IAErB,6EAA6E;IAC7E,OAAO,EAAE,MAAM,CAAC;CACjB;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,wBAAwB,CACtC,SAAS,EAAE,WAAW,EAAE,EACxB,QAAQ,EAAE,WAAW,EAAE,GACtB,WAAW,EAAE,CAsCf;AAED;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,MAAM,CAOlE"}

package/dist/utils/matching.js

@@ -4,7 +4,8 @@
  * Shared 1:1 greedy matching algorithm that pairs running processes with session files
  * based on CWD and birth-time proximity to process start time.
  */ import * as path from "path";
-/** Maximum allowed delta between process start time and session file birth time. */ const TOLERANCE_MS = 3 * 60 * 1000; // 3 minutes
+import { MATCH_TOLERANCE_MS } from "./matchingConstants.js";
+export { MATCH_TOLERANCE_MS };
 /**
  * Match processes to session files using 1:1 greedy assignment.
  *
@@ -26,7 +27,7 @@
             if (!session.resolvedCwd) continue;
             if (proc.cwd !== session.resolvedCwd) continue;
             const deltaMs = Math.abs(processStartMs - session.birthtimeMs);
-            if (deltaMs > TOLERANCE_MS) continue;
+            if (deltaMs > MATCH_TOLERANCE_MS) continue;
             candidates.push({
                 process: proc,
                 session,

package/dist/utils/matching.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../../src/utils/matching.ts"],"sourcesContent":["/**\n * Session Matching Utilities\n *\n * Shared 1:1 greedy matching algorithm that pairs running processes with session files\n * based on CWD and birth-time proximity to process start time.\n */\n\nimport * as path from \"path\";\nimport type { ProcessInfo } from \"../adapters/AgentAdapter.js\";\nimport type { SessionFile } from \"./session.js\";\n\n/** Maximum allowed delta between process start time and session file birth time. */\nconst TOLERANCE_MS = 3 * 60 * 1000; // 3 minutes\n\n/**\n * Result of matching a process to a session file.\n */\nexport interface MatchResult {\n  /** The matched process */\n  process: ProcessInfo;\n\n  /** The matched session file */\n  session: SessionFile;\n\n  /** Absolute time delta in ms between process start and session birth time */\n  deltaMs: number;\n}\n\n/**\n * Match processes to session files using 1:1 greedy assignment.\n *\n * Algorithm:\n * 1. Exclude processes without startTime (they become process-only fallback).\n * 2. Build candidate pairs where process.cwd === session.resolvedCwd\n *    and |process.startTime - session.birthtimeMs| <= 3 minutes.\n * 3. Sort candidates by deltaMs ascending (best matches first).\n * 4. Greedily assign: once a process or session is matched, skip it.\n *\n * Adapters must set session.resolvedCwd before calling this function.\n */\nexport function matchProcessesToSessions(\n  processes: ProcessInfo[],\n  sessions: SessionFile[],\n): MatchResult[] {\n  // Build all candidate pairs\n  const candidates: Array<{ process: ProcessInfo; session: SessionFile; deltaMs: number }> = [];\n\n  for (const proc of processes) {\n    if (!proc.startTime || !proc.cwd) continue;\n\n    const processStartMs = proc.startTime.getTime();\n\n    for (const session of sessions) {\n      if (!session.resolvedCwd) continue;\n      if (proc.cwd !== session.resolvedCwd) continue;\n\n      const deltaMs = Math.abs(processStartMs - session.birthtimeMs);\n      if (deltaMs > TOLERANCE_MS) continue;\n\n      candidates.push({ process: proc, session, deltaMs });\n    }\n  }\n\n  // Sort by smallest delta first\n  candidates.sort((a, b) => a.deltaMs - b.deltaMs);\n\n  // Greedy 1:1 assignment\n  const matchedPids = new Set<number>();\n  const matchedSessionIds = new Set<string>();\n  const results: MatchResult[] = [];\n\n  for (const candidate of candidates) {\n    if (matchedPids.has(candidate.process.pid)) continue;\n    if (matchedSessionIds.has(candidate.session.sessionId)) continue;\n\n    matchedPids.add(candidate.process.pid);\n    matchedSessionIds.add(candidate.session.sessionId);\n    results.push(candidate);\n  }\n\n  return results;\n}\n\n/**\n * Generate a deterministic agent name from CWD and PID.\n *\n * Format: \"folder-name-pid\" (lowercase kebab-case)\n */\nexport function generateAgentName(cwd: string, pid: number): string {\n  const folderName = path.basename(cwd) || \"unknown\";\n  const kebab = folderName\n    .toLowerCase()\n    .replace(/[^a-z0-9]+/g, \"-\")\n    .replace(/^-+|-+$/g, \"\");\n  return `${kebab || \"unknown\"}-${pid}`;\n}\n"],"names":["path","TOLERANCE_MS","matchProcessesToSessions","processes","sessions","candidates","proc","startTime","cwd","processStartMs","getTime","session","resolvedCwd","deltaMs","Math","abs","birthtimeMs","push","process","sort","a","b","matchedPids","Set","matchedSessionIds","results","candidate","has","pid","sessionId","add","generateAgentName","folderName","basename","kebab","toLowerCase","replace"],"mappings":"AAAA;;;;;CAKC,GAED,YAAYA,UAAU,OAAO;AAI7B,kFAAkF,GAClF,MAAMC,eAAe,IAAI,KAAK,MAAM,YAAY;AAgBhD;;;;;;;;;;;CAWC,GACD,OAAO,SAASC,yBACdC,SAAwB,EACxBC,QAAuB;IAEvB,4BAA4B;IAC5B,MAAMC,aAAqF,EAAE;IAE7F,KAAK,MAAMC,QAAQH,UAAW;QAC5B,IAAI,CAACG,KAAKC,SAAS,IAAI,CAACD,KAAKE,GAAG,EAAE;QAElC,MAAMC,iBAAiBH,KAAKC,SAAS,CAACG,OAAO;QAE7C,KAAK,MAAMC,WAAWP,SAAU;YAC9B,IAAI,CAACO,QAAQC,WAAW,EAAE;YAC1B,IAAIN,KAAKE,GAAG,KAAKG,QAAQC,WAAW,EAAE;YAEtC,MAAMC,UAAUC,KAAKC,GAAG,CAACN,iBAAiBE,QAAQK,WAAW;YAC7D,IAAIH,UAAUZ,cAAc;YAE5BI,WAAWY,IAAI,CAAC;gBAAEC,SAASZ;gBAAMK;gBAASE;YAAQ;QACpD;IACF;IAEA,+BAA+B;IAC/BR,WAAWc,IAAI,CAAC,CAACC,GAAGC,IAAMD,EAAEP,OAAO,GAAGQ,EAAER,OAAO;IAE/C,wBAAwB;IACxB,MAAMS,cAAc,IAAIC;IACxB,MAAMC,oBAAoB,IAAID;IAC9B,MAAME,UAAyB,EAAE;IAEjC,KAAK,MAAMC,aAAarB,WAAY;QAClC,IAAIiB,YAAYK,GAAG,CAACD,UAAUR,OAAO,CAACU,GAAG,GAAG;QAC5C,IAAIJ,kBAAkBG,GAAG,CAACD,UAAUf,OAAO,CAACkB,SAAS,GAAG;QAExDP,YAAYQ,GAAG,CAACJ,UAAUR,OAAO,CAACU,GAAG;QACrCJ,kBAAkBM,GAAG,CAACJ,UAAUf,OAAO,CAACkB,SAAS;QACjDJ,QAAQR,IAAI,CAACS;IACf;IAEA,OAAOD;AACT;AAEA;;;;CAIC,GACD,OAAO,SAASM,kBAAkBvB,GAAW,EAAEoB,GAAW;IACxD,MAAMI,aAAahC,KAAKiC,QAAQ,CAACzB,QAAQ;IACzC,MAAM0B,QAAQF,WACXG,WAAW,GACXC,OAAO,CAAC,eAAe,KACvBA,OAAO,CAAC,YAAY;IACvB,OAAO,GAAGF,SAAS,UAAU,CAAC,EAAEN,KAAK;AACvC"}
+{"version":3,"sources":["../../src/utils/matching.ts"],"sourcesContent":["/**\n * Session Matching Utilities\n *\n * Shared 1:1 greedy matching algorithm that pairs running processes with session files\n * based on CWD and birth-time proximity to process start time.\n */\n\nimport * as path from \"path\";\nimport type { ProcessInfo } from \"../adapters/AgentAdapter.js\";\nimport { MATCH_TOLERANCE_MS } from \"./matchingConstants.js\";\nimport type { SessionFile } from \"./session.js\";\n\nexport { MATCH_TOLERANCE_MS };\n\n/**\n * Result of matching a process to a session file.\n */\nexport interface MatchResult {\n  /** The matched process */\n  process: ProcessInfo;\n\n  /** The matched session file */\n  session: SessionFile;\n\n  /** Absolute time delta in ms between process start and session birth time */\n  deltaMs: number;\n}\n\n/**\n * Match processes to session files using 1:1 greedy assignment.\n *\n * Algorithm:\n * 1. Exclude processes without startTime (they become process-only fallback).\n * 2. Build candidate pairs where process.cwd === session.resolvedCwd\n *    and |process.startTime - session.birthtimeMs| <= 3 minutes.\n * 3. Sort candidates by deltaMs ascending (best matches first).\n * 4. Greedily assign: once a process or session is matched, skip it.\n *\n * Adapters must set session.resolvedCwd before calling this function.\n */\nexport function matchProcessesToSessions(\n  processes: ProcessInfo[],\n  sessions: SessionFile[],\n): MatchResult[] {\n  // Build all candidate pairs\n  const candidates: Array<{ process: ProcessInfo; session: SessionFile; deltaMs: number }> = [];\n\n  for (const proc of processes) {\n    if (!proc.startTime || !proc.cwd) continue;\n\n    const processStartMs = proc.startTime.getTime();\n\n    for (const session of sessions) {\n      if (!session.resolvedCwd) continue;\n      if (proc.cwd !== session.resolvedCwd) continue;\n\n      const deltaMs = Math.abs(processStartMs - session.birthtimeMs);\n      if (deltaMs > MATCH_TOLERANCE_MS) continue;\n\n      candidates.push({ process: proc, session, deltaMs });\n    }\n  }\n\n  // Sort by smallest delta first\n  candidates.sort((a, b) => a.deltaMs - b.deltaMs);\n\n  // Greedy 1:1 assignment\n  const matchedPids = new Set<number>();\n  const matchedSessionIds = new Set<string>();\n  const results: MatchResult[] = [];\n\n  for (const candidate of candidates) {\n    if (matchedPids.has(candidate.process.pid)) continue;\n    if (matchedSessionIds.has(candidate.session.sessionId)) continue;\n\n    matchedPids.add(candidate.process.pid);\n    matchedSessionIds.add(candidate.session.sessionId);\n    results.push(candidate);\n  }\n\n  return results;\n}\n\n/**\n * Generate a deterministic agent name from CWD and PID.\n *\n * Format: \"folder-name-pid\" (lowercase kebab-case)\n */\nexport function generateAgentName(cwd: string, pid: number): string {\n  const folderName = path.basename(cwd) || \"unknown\";\n  const kebab = folderName\n    .toLowerCase()\n    .replace(/[^a-z0-9]+/g, \"-\")\n    .replace(/^-+|-+$/g, \"\");\n  return `${kebab || \"unknown\"}-${pid}`;\n}\n"],"names":["path","MATCH_TOLERANCE_MS","matchProcessesToSessions","processes","sessions","candidates","proc","startTime","cwd","processStartMs","getTime","session","resolvedCwd","deltaMs","Math","abs","birthtimeMs","push","process","sort","a","b","matchedPids","Set","matchedSessionIds","results","candidate","has","pid","sessionId","add","generateAgentName","folderName","basename","kebab","toLowerCase","replace"],"mappings":"AAAA;;;;;CAKC,GAED,YAAYA,UAAU,OAAO;AAE7B,SAASC,kBAAkB,QAAQ,yBAAyB;AAG5D,SAASA,kBAAkB,GAAG;AAgB9B;;;;;;;;;;;CAWC,GACD,OAAO,SAASC,yBACdC,SAAwB,EACxBC,QAAuB;IAEvB,4BAA4B;IAC5B,MAAMC,aAAqF,EAAE;IAE7F,KAAK,MAAMC,QAAQH,UAAW;QAC5B,IAAI,CAACG,KAAKC,SAAS,IAAI,CAACD,KAAKE,GAAG,EAAE;QAElC,MAAMC,iBAAiBH,KAAKC,SAAS,CAACG,OAAO;QAE7C,KAAK,MAAMC,WAAWP,SAAU;YAC9B,IAAI,CAACO,QAAQC,WAAW,EAAE;YAC1B,IAAIN,KAAKE,GAAG,KAAKG,QAAQC,WAAW,EAAE;YAEtC,MAAMC,UAAUC,KAAKC,GAAG,CAACN,iBAAiBE,QAAQK,WAAW;YAC7D,IAAIH,UAAUZ,oBAAoB;YAElCI,WAAWY,IAAI,CAAC;gBAAEC,SAASZ;gBAAMK;gBAASE;YAAQ;QACpD;IACF;IAEA,+BAA+B;IAC/BR,WAAWc,IAAI,CAAC,CAACC,GAAGC,IAAMD,EAAEP,OAAO,GAAGQ,EAAER,OAAO;IAE/C,wBAAwB;IACxB,MAAMS,cAAc,IAAIC;IACxB,MAAMC,oBAAoB,IAAID;IAC9B,MAAME,UAAyB,EAAE;IAEjC,KAAK,MAAMC,aAAarB,WAAY;QAClC,IAAIiB,YAAYK,GAAG,CAACD,UAAUR,OAAO,CAACU,GAAG,GAAG;QAC5C,IAAIJ,kBAAkBG,GAAG,CAACD,UAAUf,OAAO,CAACkB,SAAS,GAAG;QAExDP,YAAYQ,GAAG,CAACJ,UAAUR,OAAO,CAACU,GAAG;QACrCJ,kBAAkBM,GAAG,CAACJ,UAAUf,OAAO,CAACkB,SAAS;QACjDJ,QAAQR,IAAI,CAACS;IACf;IAEA,OAAOD;AACT;AAEA;;;;CAIC,GACD,OAAO,SAASM,kBAAkBvB,GAAW,EAAEoB,GAAW;IACxD,MAAMI,aAAahC,KAAKiC,QAAQ,CAACzB,QAAQ;IACzC,MAAM0B,QAAQF,WACXG,WAAW,GACXC,OAAO,CAAC,eAAe,KACvBA,OAAO,CAAC,YAAY;IACvB,OAAO,GAAGF,SAAS,UAAU,CAAC,EAAEN,KAAK;AACvC"}

package/dist/utils/matchingConstants.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Session Matching Constants
+ *
+ * Kept apart from matching.ts so session locators can import them even when
+ * adapter tests fully mock matching.ts.
+ */
+/**
+ * Maximum allowed delta between process start time and session file birth time.
+ *
+ * Single source of truth for matchProcessesToSessions and for locator
+ * discovery windows: a window narrower than this would skip files the matcher
+ * would accept.
+ */
+export declare const MATCH_TOLERANCE_MS: number;
+//# sourceMappingURL=matchingConstants.d.ts.map

package/dist/utils/matchingConstants.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"matchingConstants.d.ts","sourceRoot":"","sources":["../../src/utils/matchingConstants.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH;;;;;;GAMG;AACH,eAAO,MAAM,kBAAkB,QAAgB,CAAC"}

package/dist/utils/matchingConstants.js

@@ -0,0 +1,14 @@
+/**
+ * Session Matching Constants
+ *
+ * Kept apart from matching.ts so session locators can import them even when
+ * adapter tests fully mock matching.ts.
+ */ /**
+ * Maximum allowed delta between process start time and session file birth time.
+ *
+ * Single source of truth for matchProcessesToSessions and for locator
+ * discovery windows: a window narrower than this would skip files the matcher
+ * would accept.
+ */ export const MATCH_TOLERANCE_MS = 3 * 60 * 1000; // 3 minutes
+
+//# sourceMappingURL=matchingConstants.js.map

package/dist/utils/matchingConstants.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/utils/matchingConstants.ts"],"sourcesContent":["/**\n * Session Matching Constants\n *\n * Kept apart from matching.ts so session locators can import them even when\n * adapter tests fully mock matching.ts.\n */\n\n/**\n * Maximum allowed delta between process start time and session file birth time.\n *\n * Single source of truth for matchProcessesToSessions and for locator\n * discovery windows: a window narrower than this would skip files the matcher\n * would accept.\n */\nexport const MATCH_TOLERANCE_MS = 3 * 60 * 1000; // 3 minutes\n"],"names":["MATCH_TOLERANCE_MS"],"mappings":"AAAA;;;;;CAKC,GAED;;;;;;CAMC,GACD,OAAO,MAAMA,qBAAqB,IAAI,KAAK,KAAK,CAAC,YAAY"}

package/dist/utils/process.d.ts

@@ -6,6 +6,18 @@
  * remain exported for compatibility with existing consumers.
  */
 import type { ProcessInfo } from "../adapters/AgentAdapter.js";
+/**
+ * Resolve argv[0] from a `ps` command line.
+ *
+ * `ps` joins argv with spaces, so an executable installed under a directory
+ * containing spaces (`/Applications/Some App.app/Contents/Resources/codex`)
+ * spans several whitespace tokens. When the first token of an absolute path
+ * is not itself a file, longer space-joined prefixes ending in a token with a
+ * path separator are tried, and the first one that exists on disk wins.
+ * Otherwise the first token is returned, so arguments are never folded into
+ * the executable path unless that combined path really is a file.
+ */
+export declare function executablePath(command: string): string;
 export declare function executableBasename(command: string): string;
 export declare function filterByProcessNames(processes: readonly ProcessInfo[], namePatterns: readonly string[]): ProcessInfo[];
 /**
@@ -18,11 +30,35 @@ export declare function filterByProcessNames(processes: readonly ProcessInfo[],
  * cwd and startTime are NOT populated — call enrichProcesses() to fill them.
  */
 export declare function listAgentProcesses(namePattern: string): ProcessInfo[];
+/** Runs an executable and resolves with its stdout. Injectable for tests. */
+export type ProcessExec = (file: string, args: readonly string[]) => Promise<string>;
+export interface ProcessSnapshotOptions {
+    /**
+     * Decides which name-matched processes are worth enriching with cwd and
+     * start time. Non-candidates are still returned (pid, ppid, tty, command
+     * only) so adapters can walk parent chains. Omitted = enrich everything.
+     */
+    isCandidate?: (process: ProcessInfo) => boolean;
+}
+export type ProcessSnapshotCapture = (namePatterns: readonly string[], options?: ProcessSnapshotOptions) => Promise<ProcessInfo[]>;
+/**
+ * Create a snapshot capture function with its own start-time cache.
+ *
+ * Start times never change for a live process, so each PID is queried with
+ * `ps lstart` once and reused on later refreshes. A cache entry is dropped
+ * when its PID disappears from the base listing, and ignored when the PID's
+ * ppid/command no longer match (PID reuse). cwd is re-read every refresh
+ * because a process can change directory.
+ */
+export declare function createProcessSnapshotCapture(deps?: {
+    exec?: ProcessExec;
+}): ProcessSnapshotCapture;
 /**
  * Capture and enrich relevant processes without blocking the event loop.
- * One base process listing is shared by every requested executable name.
+ * One base process listing is shared by every requested executable name;
+ * only processes accepted by `options.isCandidate` are enriched.
  */
-export declare function captureProcessSnapshot(namePatterns: readonly string[]): Promise<ProcessInfo[]>;
+export declare const captureProcessSnapshot: ProcessSnapshotCapture;
 /**
  * Batch-get current working directories for multiple PIDs.
  *

package/dist/utils/process.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"process.d.ts","sourceRoot":"","sources":["../../src/utils/process.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAIH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,6BAA6B,CAAC;AAK/D,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAG1D;AAWD,wBAAgB,oBAAoB,CAClC,SAAS,EAAE,SAAS,WAAW,EAAE,EACjC,YAAY,EAAE,SAAS,MAAM,EAAE,GAC9B,WAAW,EAAE,CAMf;AAED;;;;;;;;GAQG;AACH,wBAAgB,kBAAkB,CAAC,WAAW,EAAE,MAAM,GAAG,WAAW,EAAE,CA0CrE;AAwGD;;;GAGG;AACH,wBAAsB,sBAAsB,CAC1C,YAAY,EAAE,SAAS,MAAM,EAAE,GAC9B,OAAO,CAAC,WAAW,EAAE,CAAC,CAsBxB;AAED;;;;;GAKG;AACH,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAuCvE;AAED;;;;;;GAMG;AACH,wBAAgB,yBAAyB,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,GAAG,CAAC,MAAM,EAAE,IAAI,CAAC,CAiC3E;AAED;;;;;;GAMG;AACH,wBAAgB,eAAe,CAAC,SAAS,EAAE,WAAW,EAAE,GAAG,WAAW,EAAE,CAavE;AAaD,wBAAgB,kBAAkB,CAChC,SAAS,EAAE,WAAW,EAAE,EACxB,KAAK,EAAE,WAAW,GACjB,WAAW,GAAG,SAAS,CAKzB;AAED;;;;;;GAMG;AACH,wBAAgB,sBAAsB,CACpC,SAAS,EAAE,WAAW,EAAE,EACxB,gBAAgB,GAAE,WAAW,EAAO,GACnC,GAAG,CAAC,MAAM,CAAC,CAqBb;AAED;;GAEG;AACH,wBAAgB,aAAa,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CASjD"}
+{"version":3,"file":"process.d.ts","sourceRoot":"","sources":["../../src/utils/process.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAKH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,6BAA6B,CAAC;AAmB/D;;;;;;;;;;GAUG;AACH,wBAAgB,cAAc,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAWtD;AAED,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAE1D;AAkCD,wBAAgB,oBAAoB,CAClC,SAAS,EAAE,SAAS,WAAW,EAAE,EACjC,YAAY,EAAE,SAAS,MAAM,EAAE,GAC9B,WAAW,EAAE,CAIf;AAED;;;;;;;;GAQG;AACH,wBAAgB,kBAAkB,CAAC,WAAW,EAAE,MAAM,GAAG,WAAW,EAAE,CA0CrE;AAED,6EAA6E;AAC7E,MAAM,MAAM,WAAW,GAAG,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,SAAS,MAAM,EAAE,KAAK,OAAO,CAAC,MAAM,CAAC,CAAC;AAErF,MAAM,WAAW,sBAAsB;IACrC;;;;OAIG;IACH,WAAW,CAAC,EAAE,CAAC,OAAO,EAAE,WAAW,KAAK,OAAO,CAAC;CACjD;AAED,MAAM,MAAM,sBAAsB,GAAG,CACnC,YAAY,EAAE,SAAS,MAAM,EAAE,EAC/B,OAAO,CAAC,EAAE,sBAAsB,KAC7B,OAAO,CAAC,WAAW,EAAE,CAAC,CAAC;AA8H5B;;;;;;;;GAQG;AACH,wBAAgB,4BAA4B,CAC1C,IAAI,GAAE;IAAE,IAAI,CAAC,EAAE,WAAW,CAAA;CAAO,GAChC,sBAAsB,CAwDxB;AAED;;;;GAIG;AACH,eAAO,MAAM,sBAAsB,EAAE,sBAAuD,CAAC;AAE7F;;;;;GAKG;AACH,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAuCvE;AAED;;;;;;GAMG;AACH,wBAAgB,yBAAyB,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,GAAG,CAAC,MAAM,EAAE,IAAI,CAAC,CAiC3E;AAED;;;;;;GAMG;AACH,wBAAgB,eAAe,CAAC,SAAS,EAAE,WAAW,EAAE,GAAG,WAAW,EAAE,CAavE;AAaD,wBAAgB,kBAAkB,CAChC,SAAS,EAAE,WAAW,EAAE,EACxB,KAAK,EAAE,WAAW,GACjB,WAAW,GAAG,SAAS,CAKzB;AAED;;;;;;GAMG;AACH,wBAAgB,sBAAsB,CACpC,SAAS,EAAE,WAAW,EAAE,EACxB,gBAAgB,GAAE,WAAW,EAAO,GACnC,GAAG,CAAC,MAAM,CAAC,CAqBb;AAED;;GAEG;AACH,wBAAgB,aAAa,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CASjD"}