@sapiom/harness 0.1.6 → 0.2.0

package/dist/core/canvas-watcher.js

@@ -3,6 +3,13 @@ import * as path from "node:path";
 import { CANVAS_DIR } from "../shared/types.js";
 const DEBOUNCE_MS = 150;
 const POLL_INTERVAL_MS = 500;
+/** Directories a workflow-source walk never descends into (heavy or generated)
+ *  — mirrors core/canvas-interconnections.ts's `listSourceFiles`. */
+const SKIP_DIR_NAMES = new Set(["node_modules", ".git", "dist", "build", ".sapiom"]);
+const SOURCE_EXTENSIONS = new Set([".ts", ".tsx"]);
+/** Bounds the polling snapshot walk — the extraction itself already caps at
+ *  200 files; this is just a defensive ceiling on the fingerprint cost. */
+const MAX_SOURCE_FILES = 400;
 /**
  * Cheap change fingerprint for a directory tree: sorted `path:mtime:size`
  * entries. Used by the polling fallback (and directly testable on its own)
@@ -28,57 +35,120 @@ export function snapshotCanvasDir(canvasDir) {
     return parts.sort().join("|");
 }
 /**
- * One session's watcher. Watches the whole project root (not the canvas dir
- * directly) recursively and filters to CANVAS_DIR-prefixed changes — so
- * there's no separate "wait for the dir to appear" phase, and it naturally
- * survives the canvas dir itself being deleted/recreated. Falls back to
- * polling a directory-tree fingerprint when recursive `fs.watch` isn't
- * available (notably Linux) or the watcher errors out at runtime.
+ * Cheap change fingerprint over a project's own `.ts`/`.tsx` sources (skipping
+ * node_modules/dist/.git/.sapiom), the polling fallback's equivalent of
+ * `snapshotCanvasDir` for the workflow SOURCE — so an editor save on a step
+ * file is noticed on platforms without recursive `fs.watch` too. Bounded and
+ * total: an unreadable dir simply contributes nothing.
+ */
+export function snapshotWorkflowSources(root) {
+    const parts = [];
+    const walk = (dir) => {
+        if (parts.length >= MAX_SOURCE_FILES)
+            return;
+        let entries;
+        try {
+            entries = fs.readdirSync(dir, { withFileTypes: true });
+        }
+        catch {
+            return;
+        }
+        for (const entry of entries) {
+            if (parts.length >= MAX_SOURCE_FILES)
+                return;
+            const full = path.join(dir, entry.name);
+            if (entry.isDirectory()) {
+                if (SKIP_DIR_NAMES.has(entry.name))
+                    continue;
+                walk(full);
+            }
+            else if (SOURCE_EXTENSIONS.has(path.extname(entry.name))) {
+                try {
+                    const stat = fs.statSync(full);
+                    parts.push(`${full}:${stat.mtimeMs}:${stat.size}`);
+                }
+                catch {
+                    parts.push(`${full}:gone`);
+                }
+            }
+        }
+    };
+    walk(root);
+    return parts.sort().join("|");
+}
+/**
+ * One session's watcher. Watches the whole project root recursively and routes
+ * each change: a change under CANVAS_DIR is a rendered-output change (reload
+ * the iframe); a `.ts`/`.tsx` change anywhere else is a workflow-source change
+ * (re-render). No separate "wait for the dir to appear" phase, and it survives
+ * the canvas dir itself being deleted/recreated. Falls back to polling two
+ * directory-tree fingerprints (canvas output + sources) when recursive
+ * `fs.watch` isn't available (notably Linux) or the watcher errors out.
  */
 class SessionCanvasWatcher {
-    constructor(cwd, harnessSessionId, onChange) {
+    constructor(cwd, harnessSessionId, callbacks) {
         this.cwd = cwd;
         this.harnessSessionId = harnessSessionId;
-        this.onChange = onChange;
+        this.callbacks = callbacks;
         this.watcher = null;
         this.pollTimer = null;
-        this.debounceTimer = null;
+        this.canvasDebounceTimer = null;
+        this.sourceDebounceTimer = null;
         this.closed = false;
         this.lastSnapshot = "";
+        this.lastSourceSnapshot = "";
         this.canvasDir = path.join(cwd, CANVAS_DIR);
         this.canvasPrefix = CANVAS_DIR + path.sep;
         this.arm();
     }
-    scheduleChange() {
+    scheduleCanvasChange() {
         if (this.closed)
             return;
-        if (this.debounceTimer)
-            clearTimeout(this.debounceTimer);
-        this.debounceTimer = setTimeout(() => this.onChange(this.harnessSessionId), DEBOUNCE_MS);
+        if (this.canvasDebounceTimer)
+            clearTimeout(this.canvasDebounceTimer);
+        this.canvasDebounceTimer = setTimeout(() => this.callbacks.onCanvasChange(this.harnessSessionId), DEBOUNCE_MS);
+    }
+    scheduleSourceChange() {
+        if (this.closed)
+            return;
+        if (this.sourceDebounceTimer)
+            clearTimeout(this.sourceDebounceTimer);
+        this.sourceDebounceTimer = setTimeout(() => this.callbacks.onSourceChange(this.harnessSessionId), DEBOUNCE_MS);
     }
     isCanvasPath(filename) {
-        // A `null` filename means the platform couldn't report which path
-        // changed — reload to be safe rather than miss an update.
-        if (!filename)
-            return true;
         return filename === CANVAS_DIR || filename.startsWith(this.canvasPrefix);
     }
+    isWorkflowSourcePath(filename) {
+        if (!SOURCE_EXTENSIONS.has(path.extname(filename)))
+            return false;
+        return !filename.split(path.sep).some((seg) => SKIP_DIR_NAMES.has(seg));
+    }
     arm() {
         if (this.closed)
             return;
         try {
             this.watcher = fs.watch(this.cwd, { recursive: true }, (event, filename) => {
-                if (!this.isCanvasPath(filename))
+                // A `null` filename means the platform couldn't report which path
+                // changed — do both (reload AND re-render) rather than miss an update.
+                if (filename === null) {
+                    this.scheduleCanvasChange();
+                    this.scheduleSourceChange();
                     return;
-                this.scheduleChange();
-                // A rename at (or above) the canvas dir — e.g. an editor's atomic
-                // write-then-rename, or the agent `mkdir -p`'ing it for the first
-                // time — can leave a recursive watcher no longer covering the new
-                // inode on some platforms. Re-arm defensively rather than risk
-                // silently going deaf.
-                if (event === "rename" && (filename === CANVAS_DIR || filename === path.dirname(CANVAS_DIR))) {
-                    this.rearm();
                 }
+                if (this.isCanvasPath(filename)) {
+                    this.scheduleCanvasChange();
+                    // A rename at (or above) the canvas dir — e.g. an editor's atomic
+                    // write-then-rename, or the agent `mkdir -p`'ing it for the first
+                    // time — can leave a recursive watcher no longer covering the new
+                    // inode on some platforms. Re-arm defensively rather than risk
+                    // silently going deaf.
+                    if (event === "rename" && (filename === CANVAS_DIR || filename === path.dirname(CANVAS_DIR))) {
+                        this.rearm();
+                    }
+                    return;
+                }
+                if (this.isWorkflowSourcePath(filename))
+                    this.scheduleSourceChange();
             });
             this.watcher.on("error", () => this.fallBackToPolling());
         }
@@ -98,18 +168,26 @@ class SessionCanvasWatcher {
         this.watcher?.close();
         this.watcher = null;
         this.lastSnapshot = snapshotCanvasDir(this.canvasDir);
+        this.lastSourceSnapshot = snapshotWorkflowSources(this.cwd);
         this.pollTimer = setInterval(() => {
             const snapshot = snapshotCanvasDir(this.canvasDir);
             if (snapshot !== this.lastSnapshot) {
                 this.lastSnapshot = snapshot;
-                this.scheduleChange();
+                this.scheduleCanvasChange();
+            }
+            const sourceSnapshot = snapshotWorkflowSources(this.cwd);
+            if (sourceSnapshot !== this.lastSourceSnapshot) {
+                this.lastSourceSnapshot = sourceSnapshot;
+                this.scheduleSourceChange();
             }
         }, POLL_INTERVAL_MS);
     }
     close() {
         this.closed = true;
-        if (this.debounceTimer)
-            clearTimeout(this.debounceTimer);
+        if (this.canvasDebounceTimer)
+            clearTimeout(this.canvasDebounceTimer);
+        if (this.sourceDebounceTimer)
+            clearTimeout(this.sourceDebounceTimer);
         if (this.pollTimer)
             clearInterval(this.pollTimer);
         this.watcher?.close();
@@ -126,7 +204,10 @@ export class CanvasWatcherManager {
      *  into a different cwd). */
     start(harnessSessionId, cwd) {
         this.stop(harnessSessionId);
-        this.watchers.set(harnessSessionId, new SessionCanvasWatcher(cwd, harnessSessionId, (id) => this.deps.onChange(id)));
+        this.watchers.set(harnessSessionId, new SessionCanvasWatcher(cwd, harnessSessionId, {
+            onCanvasChange: (id) => this.deps.onChange(id),
+            onSourceChange: (id) => this.deps.onSourceChange(id),
+        }));
     }
     stop(harnessSessionId) {
         this.watchers.get(harnessSessionId)?.close();

package/dist/core/canvas-watcher.js.map

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

package/dist/core/collector/normalizer.d.ts

@@ -24,6 +24,14 @@ export interface NormalizeContext {
 }
 /** Stringify + truncate a value so a giant tool payload can't blow up storage. */
 export declare function truncateForPayload(value: unknown, maxLength?: number): string;
+/**
+ * The suffix {@link truncateForPayload} leaves behind, with the omitted count
+ * captured. Exported so every consumer that has to recognize truncated text —
+ * the record fold's `responseTruncated`, the archive's re-clip — tests for the
+ * same marker this function writes, instead of keeping its own copy of the
+ * format. No `g` flag: callers use `test`/`exec` freely.
+ */
+export declare const PAYLOAD_TRUNCATION_MARKER: RegExp;
 /**
  * Normalize one Claude Code hook invocation into an AnalyticsEvent, or
  * `null` when the hook doesn't map to an analytics event (PreToolUse, or an

package/dist/core/collector/normalizer.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"normalizer.d.ts","sourceRoot":"","sources":["../../../src/core/collector/normalizer.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAIH,OAAO,KAAK,EAAE,cAAc,EAAsB,WAAW,EAAE,MAAM,uBAAuB,CAAC;AAE7F,sEAAsE;AACtE,MAAM,MAAM,eAAe,GACvB,cAAc,GACd,kBAAkB,GAClB,YAAY,GACZ,aAAa,GACb,MAAM,GACN,YAAY,CAAC;AAEjB,8EAA8E;AAC9E,MAAM,MAAM,cAAc,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;AAErD,MAAM,WAAW,gBAAgB;IAC/B,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IACtB,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,SAAS,EAAE,MAAM,CAAC;IAClB,gBAAgB,EAAE,MAAM,CAAC;IACzB,OAAO,EAAE,WAAW,CAAC;IACrB,4EAA4E;IAC5E,cAAc,EAAE,MAAM,GAAG,IAAI,CAAC;IAC9B,kGAAkG;IAClG,GAAG,EAAE,MAAM,CAAC;CACb;AAiBD,kFAAkF;AAClF,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,OAAO,EAAE,SAAS,SAAmB,GAAG,MAAM,CAIvF;AA+CD;;;;GAIG;AACH,wBAAgB,kBAAkB,CAChC,SAAS,EAAE,MAAM,EACjB,WAAW,EAAE,cAAc,EAC3B,OAAO,EAAE,gBAAgB,GACxB,cAAc,GAAG,IAAI,CAmBvB"}
+{"version":3,"file":"normalizer.d.ts","sourceRoot":"","sources":["../../../src/core/collector/normalizer.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAIH,OAAO,KAAK,EAAE,cAAc,EAAsB,WAAW,EAAE,MAAM,uBAAuB,CAAC;AAE7F,sEAAsE;AACtE,MAAM,MAAM,eAAe,GACvB,cAAc,GACd,kBAAkB,GAClB,YAAY,GACZ,aAAa,GACb,MAAM,GACN,YAAY,CAAC;AAEjB,8EAA8E;AAC9E,MAAM,MAAM,cAAc,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;AAErD,MAAM,WAAW,gBAAgB;IAC/B,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IACtB,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,SAAS,EAAE,MAAM,CAAC;IAClB,gBAAgB,EAAE,MAAM,CAAC;IACzB,OAAO,EAAE,WAAW,CAAC;IACrB,4EAA4E;IAC5E,cAAc,EAAE,MAAM,GAAG,IAAI,CAAC;IAC9B,kGAAkG;IAClG,GAAG,EAAE,MAAM,CAAC;CACb;AAiBD,kFAAkF;AAClF,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,OAAO,EAAE,SAAS,SAAmB,GAAG,MAAM,CAIvF;AAED;;;;;;GAMG;AACH,eAAO,MAAM,yBAAyB,QAAgC,CAAC;AA+CvE;;;;GAIG;AACH,wBAAgB,kBAAkB,CAChC,SAAS,EAAE,MAAM,EACjB,WAAW,EAAE,cAAc,EAC3B,OAAO,EAAE,gBAAgB,GACxB,cAAc,GAAG,IAAI,CAmBvB"}

package/dist/core/collector/normalizer.js

@@ -27,6 +27,14 @@ export function truncateForPayload(value, maxLength = MAX_FIELD_LENGTH) {
         return str;
     return `${str.slice(0, maxLength)}…[truncated ${str.length - maxLength} chars]`;
 }
+/**
+ * The suffix {@link truncateForPayload} leaves behind, with the omitted count
+ * captured. Exported so every consumer that has to recognize truncated text —
+ * the record fold's `responseTruncated`, the archive's re-clip — tests for the
+ * same marker this function writes, instead of keeping its own copy of the
+ * format. No `g` flag: callers use `test`/`exec` freely.
+ */
+export const PAYLOAD_TRUNCATION_MARKER = /…\[truncated (\d+) chars\]$/;
 function stringField(payload, key) {
     const value = payload[key];
     return typeof value === "string" ? value : undefined;

package/dist/core/collector/normalizer.js.map

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

package/dist/core/collector/store.d.ts

@@ -9,8 +9,60 @@
  * never overlap with an in-flight append and no appended line can be lost
  * in a sweep's read window. Overhead is negligible — appends are low-frequency
  * (one per hook event), and the queue never holds more than O(sessions) entries.
+ *
+ * Reads (`read`, `index`) run deliberately OUTSIDE that queue: an append is a
+ * single `appendFile` of one line, so a reader can never be left waiting out a
+ * half-written record it would otherwise have to skip — the worst case is a
+ * torn final line from a crash, which the parser drops. Blocking writers
+ * behind a 50 MB scan to buy nothing would be the wrong trade.
+ *
+ * Index: reading one session's events must not rescan the whole file (capped
+ * at 50 MB — see store-retention.ts). The index maps each harnessSessionId to
+ * the byte spans its lines occupy. It is built lazily on the first read and
+ * maintained incrementally after that: each subsequent read scans only the
+ * bytes appended since the last one — by this process or by a second harness
+ * boot writing to the same file, which is why the trigger is the file's size
+ * rather than our own append path. A shrink or an inode change means the file
+ * was rewritten underneath us (a retention sweep), which invalidates every
+ * offset, so the index is rebuilt from scratch.
  */
-import { type AnalyticsEvent } from "../../shared/types.js";
+import { type AnalyticsEvent, type AnalyticsEventType, type HarnessKind } from "../../shared/types.js";
+/** A half-open byte range `[start, end)` of the ndjson file. */
+export interface ByteSpan {
+    start: number;
+    end: number;
+}
+/** What the index knows about one harnessSessionId. */
+export interface EventIndexEntry {
+    harnessSessionId: string;
+    /** Byte spans holding this session's lines, ascending, adjacent ones merged. */
+    spans: ByteSpan[];
+    /** Total events recorded for the session. */
+    eventCount: number;
+    /** `prompt.submitted` events — the exact human-turn count, at any file size. */
+    turnCount: number;
+    /** Agent session ids seen on this session's events, in first-seen order. */
+    agentSessionIds: string[];
+    /** Harness kind from the session's first event carrying one. */
+    harness: HarnessKind | null;
+    /** ISO-8601 `ts` of the first / last event seen for the session. */
+    firstTs: string | null;
+    lastTs: string | null;
+}
+export interface EventIndex {
+    /** Keyed by harnessSessionId. */
+    bySession: ReadonlyMap<string, EventIndexEntry>;
+    /** agentSessionId → harnessSessionIds that reported it, in first-seen order. */
+    byAgentSession: ReadonlyMap<string, readonly string[]>;
+}
+export interface EventReadFilter {
+    /** One or more harnessSessionIds. Index-accelerated: only those byte spans
+     *  are read, never the whole file. */
+    harnessSessionId?: string | readonly string[];
+    /** Keep only these event types. Applied after parsing (the type isn't part
+     *  of the index key, so it saves parsing work for the caller, not I/O). */
+    types?: readonly AnalyticsEventType[];
+}
 export interface EventStore {
     /** Append one event as a single ndjson line, serialized through the queue. */
     append(event: AnalyticsEvent): Promise<void>;
@@ -21,9 +73,31 @@ export interface EventStore {
      *
      * A failed `fn` never poisons the queue (later appends proceed normally).
      * The return value of `fn` is forwarded to the caller.
+     *
+     * The byte-offset index is dropped on entry: a sweep rewrites the file, so
+     * every offset it holds is presumed stale.
      */
     runExclusive<T>(fn: () => Promise<T>): Promise<T>;
+    /**
+     * Stream matching events in file order (= append order, which is only
+     * roughly `ts` order; callers needing a strict order sort by `(ts, seq)` —
+     * see core/session-record.ts).
+     *
+     * Runs outside the append queue. Unparseable lines — including a torn final
+     * line from a crash mid-append — are skipped, never thrown on. Yields
+     * nothing when the file doesn't exist yet.
+     */
+    read(filter?: EventReadFilter): AsyncIterable<AnalyticsEvent>;
+    /**
+     * The byte-offset index, built on first call and extended on later ones by
+     * scanning only the bytes appended since. Reconciles against the file on
+     * every call, so it is always as fresh as the moment it was asked for. Empty
+     * when the file doesn't exist.
+     */
+    index(): Promise<EventIndex>;
 }
+/** Minimal read surface — what session-record.ts actually needs from a store. */
+export type EventReader = Pick<EventStore, "read" | "index">;
 /**
  * @param filePath Defaults to `HARNESS_PATHS.events`
  *   (`~/.sapiom/harness/events.ndjson`). Override in tests.

package/dist/core/collector/store.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"store.d.ts","sourceRoot":"","sources":["../../../src/core/collector/store.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAKH,OAAO,EAAiB,KAAK,cAAc,EAAE,MAAM,uBAAuB,CAAC;AAG3E,MAAM,WAAW,UAAU;IACzB,8EAA8E;IAC9E,MAAM,CAAC,KAAK,EAAE,cAAc,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC7C;;;;;;;OAOG;IACH,YAAY,CAAC,CAAC,EAAE,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC;CACnD;AAED;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,QAAQ,GAAE,MAA6B,GAAG,UAAU,CAqCpF"}
+{"version":3,"file":"store.d.ts","sourceRoot":"","sources":["../../../src/core/collector/store.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAQH,OAAO,EAEL,KAAK,cAAc,EACnB,KAAK,kBAAkB,EACvB,KAAK,WAAW,EACjB,MAAM,uBAAuB,CAAC;AAM/B,gEAAgE;AAChE,MAAM,WAAW,QAAQ;IACvB,KAAK,EAAE,MAAM,CAAC;IACd,GAAG,EAAE,MAAM,CAAC;CACb;AAED,uDAAuD;AACvD,MAAM,WAAW,eAAe;IAC9B,gBAAgB,EAAE,MAAM,CAAC;IACzB,gFAAgF;IAChF,KAAK,EAAE,QAAQ,EAAE,CAAC;IAClB,6CAA6C;IAC7C,UAAU,EAAE,MAAM,CAAC;IACnB,gFAAgF;IAChF,SAAS,EAAE,MAAM,CAAC;IAClB,4EAA4E;IAC5E,eAAe,EAAE,MAAM,EAAE,CAAC;IAC1B,gEAAgE;IAChE,OAAO,EAAE,WAAW,GAAG,IAAI,CAAC;IAC5B,oEAAoE;IACpE,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;CACvB;AAED,MAAM,WAAW,UAAU;IACzB,iCAAiC;IACjC,SAAS,EAAE,WAAW,CAAC,MAAM,EAAE,eAAe,CAAC,CAAC;IAChD,gFAAgF;IAChF,cAAc,EAAE,WAAW,CAAC,MAAM,EAAE,SAAS,MAAM,EAAE,CAAC,CAAC;CACxD;AAED,MAAM,WAAW,eAAe;IAC9B;0CACsC;IACtC,gBAAgB,CAAC,EAAE,MAAM,GAAG,SAAS,MAAM,EAAE,CAAC;IAC9C;+EAC2E;IAC3E,KAAK,CAAC,EAAE,SAAS,kBAAkB,EAAE,CAAC;CACvC;AAED,MAAM,WAAW,UAAU;IACzB,8EAA8E;IAC9E,MAAM,CAAC,KAAK,EAAE,cAAc,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC7C;;;;;;;;;;OAUG;IACH,YAAY,CAAC,CAAC,EAAE,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC;IAClD;;;;;;;;OAQG;IACH,IAAI,CAAC,MAAM,CAAC,EAAE,eAAe,GAAG,aAAa,CAAC,cAAc,CAAC,CAAC;IAC9D;;;;;OAKG;IACH,KAAK,IAAI,OAAO,CAAC,UAAU,CAAC,CAAC;CAC9B;AAED,iFAAiF;AACjF,MAAM,MAAM,WAAW,GAAG,IAAI,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,CAAC;AAmD7D;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,QAAQ,GAAE,MAA6B,GAAG,UAAU,CA8SpF"}