@sapiom/harness 0.1.6 → 0.2.0

package/dist/core/collector/store.js

@@ -9,11 +9,72 @@
  * 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 { createReadStream } from "node:fs";
 import * as fs from "node:fs/promises";
 import * as path from "node:path";
-import { HARNESS_PATHS } from "../../shared/types.js";
+import * as readline from "node:readline";
+import { StringDecoder } from "node:string_decoder";
+import { HARNESS_PATHS, } from "../../shared/types.js";
 import { expandHome } from "../paths.js";
+/** Bytes read per positioned read when walking a span (see readSpanLines). */
+const SPAN_CHUNK_BYTES = 1024 * 1024;
+/** Parse one ndjson line into an event, or null when it isn't one. */
+function parseEventLine(line) {
+    if (!line.trim())
+        return null;
+    let parsed;
+    try {
+        parsed = JSON.parse(line);
+    }
+    catch {
+        return null;
+    }
+    if (typeof parsed !== "object" || parsed === null)
+        return null;
+    const candidate = parsed;
+    // harnessSessionId keys the index and ts orders the fold — a line missing
+    // either can't be placed in a record, so it isn't an event as far as
+    // readers are concerned.
+    if (typeof candidate.harnessSessionId !== "string")
+        return null;
+    if (typeof candidate.ts !== "string" || typeof candidate.type !== "string")
+        return null;
+    return candidate;
+}
+function matchesFilter(event, sessionIds, types) {
+    if (sessionIds && !sessionIds.has(event.harnessSessionId))
+        return false;
+    if (types && !types.has(event.type))
+        return false;
+    return true;
+}
+/** Append a span, merging into the previous one when contiguous — keeps a
+ *  single-session file at one span instead of one per line. */
+function pushSpan(spans, start, end) {
+    const last = spans[spans.length - 1];
+    if (last && last.end >= start) {
+        last.end = Math.max(last.end, end);
+        return;
+    }
+    spans.push({ start, end });
+}
 /**
  * @param filePath Defaults to `HARNESS_PATHS.events`
  *   (`~/.sapiom/harness/events.ndjson`). Override in tests.
@@ -36,15 +97,286 @@ export function createEventStore(filePath = HARNESS_PATHS.events) {
         queue = next.then(() => { }, () => { });
         return next;
     }
+    // ── Reading ─────────────────────────────────────────────────────────────
+    /** Line-by-line over `[start, end]` — inclusive `end`, as fs streams take it. */
+    async function* readLines(start, end) {
+        const stream = createReadStream(resolvedPath, { start, end });
+        const lines = readline.createInterface({ input: stream, crlfDelay: Infinity });
+        try {
+            for await (const line of lines)
+                yield line;
+        }
+        finally {
+            lines.close();
+            stream.destroy();
+        }
+    }
+    /**
+     * Line-by-line over a set of byte spans, through ONE file handle and
+     * positioned reads.
+     *
+     * Not `createReadStream` per span, deliberately: a session interleaved with
+     * others across the file has one span per contiguous run of its lines —
+     * hundreds of them for a busy machine — and standing up a stream plus a
+     * readline interface for each costs far more than the bytes do. A span is
+     * still read in bounded chunks (never all at once) so a session that owns the
+     * whole 50 MB file can't be pulled into memory in one buffer, and a
+     * StringDecoder carries multi-byte characters across chunk boundaries.
+     */
+    async function* readSpanLines(spans) {
+        if (spans.length === 0)
+            return;
+        let handle;
+        try {
+            handle = await fs.open(resolvedPath, "r");
+        }
+        catch (err) {
+            if (err.code === "ENOENT")
+                return;
+            throw err;
+        }
+        try {
+            for (const span of spans) {
+                const decoder = new StringDecoder("utf8");
+                let carry = "";
+                let position = span.start;
+                while (position < span.end) {
+                    const length = Math.min(SPAN_CHUNK_BYTES, span.end - position);
+                    const buffer = Buffer.allocUnsafe(length);
+                    const { bytesRead } = await handle.read(buffer, 0, length, position);
+                    // A short read means the file shrank under us (a sweep landed
+                    // mid-read): stop this span rather than looping on a stale offset.
+                    if (bytesRead <= 0)
+                        break;
+                    position += bytesRead;
+                    const chunk = carry + decoder.write(buffer.subarray(0, bytesRead));
+                    const lines = chunk.split("\n");
+                    carry = lines.pop() ?? "";
+                    for (const line of lines)
+                        yield line;
+                }
+                // Whatever is left has no trailing newline — the file's last line, or
+                // a torn one. Either way it's the caller's parser that decides.
+                const tail = carry + decoder.end();
+                if (tail)
+                    yield tail;
+            }
+        }
+        finally {
+            await handle.close().catch(() => { });
+        }
+    }
+    async function statFile() {
+        try {
+            const stat = await fs.stat(resolvedPath);
+            return { size: stat.size, ino: stat.ino };
+        }
+        catch (err) {
+            if (err.code === "ENOENT")
+                return null;
+            throw err;
+        }
+    }
+    // ── Index ───────────────────────────────────────────────────────────────
+    let state = null;
+    // Serializes index work so two concurrent reads never scan the same tail
+    // twice, nor interleave partial updates into the same maps.
+    let indexWork = Promise.resolve();
+    function entryFor(current, harnessSessionId) {
+        const existing = current.bySession.get(harnessSessionId);
+        if (existing)
+            return existing;
+        const created = {
+            harnessSessionId,
+            spans: [],
+            eventCount: 0,
+            turnCount: 0,
+            agentSessionIds: [],
+            harness: null,
+            firstTs: null,
+            lastTs: null,
+        };
+        current.bySession.set(harnessSessionId, created);
+        return created;
+    }
+    function recordEvent(current, event, start, end) {
+        const entry = entryFor(current, event.harnessSessionId);
+        pushSpan(entry.spans, start, end);
+        entry.eventCount += 1;
+        if (event.type === "prompt.submitted")
+            entry.turnCount += 1;
+        if (entry.harness === null && typeof event.harness === "string")
+            entry.harness = event.harness;
+        if (entry.firstTs === null)
+            entry.firstTs = event.ts;
+        entry.lastTs = event.ts;
+        if (typeof event.agentSessionId === "string" && event.agentSessionId) {
+            if (!entry.agentSessionIds.includes(event.agentSessionId)) {
+                entry.agentSessionIds.push(event.agentSessionId);
+            }
+            const siblings = current.byAgentSession.get(event.agentSessionId);
+            if (!siblings) {
+                current.byAgentSession.set(event.agentSessionId, [event.harnessSessionId]);
+            }
+            else if (!siblings.includes(event.harnessSessionId)) {
+                siblings.push(event.harnessSessionId);
+            }
+        }
+    }
+    /**
+     * Fold `[from, to)` of the file into `current`. Offsets advance by the BYTE
+     * length of each line, not its character count — a multi-byte prompt would
+     * otherwise skew every subsequent span.
+     *
+     * A final line with no trailing newline (a crash mid-append, or a read that
+     * caught an append in flight) rewinds `indexedBytes` to that line's start
+     * rather than claiming it as indexed: the next reconcile re-reads it, so a
+     * line that was merely incomplete at scan time still lands in the index once
+     * it's whole. A line that stays torn forever costs one re-parse per read.
+     */
+    async function scanInto(current, from, to) {
+        if (to <= from)
+            return;
+        let offset = from;
+        let lastLineStart = from;
+        let lastLineWasEvent = false;
+        for await (const line of readLines(from, to - 1)) {
+            lastLineStart = offset;
+            // +1 for the newline readline consumed.
+            offset += Buffer.byteLength(line, "utf8") + 1;
+            const event = parseEventLine(line);
+            lastLineWasEvent = event !== null;
+            // min(): the last line may have had no newline to count.
+            if (event)
+                recordEvent(current, event, lastLineStart, Math.min(offset, to));
+        }
+        // `offset > to` means the last line's counted newline wasn't there. Rewind
+        // only if that line also failed to parse — a complete final event without a
+        // trailing newline is indexed, and re-reading it would double-count it.
+        current.indexedBytes = offset > to && !lastLineWasEvent ? lastLineStart : to;
+    }
+    /**
+     * Bring the index in line with the file on disk, building it if needed.
+     * Grown file → scan only the new tail. Shrunk file or a new inode → the
+     * offsets we hold describe a file that no longer exists (retention sweep),
+     * so rebuild. Unchanged → no I/O beyond the stat.
+     */
+    async function reconcile() {
+        const stat = await statFile();
+        if (!stat) {
+            // No file yet: an empty index is the honest answer, and it must not be
+            // cached as "indexed" — the next call has to look again.
+            state = null;
+            return { bySession: new Map(), byAgentSession: new Map(), indexedBytes: 0, ino: -1 };
+        }
+        const current = state;
+        if (current && current.ino === stat.ino && stat.size >= current.indexedBytes) {
+            if (stat.size > current.indexedBytes)
+                await scanInto(current, current.indexedBytes, stat.size);
+            return current;
+        }
+        const fresh = {
+            bySession: new Map(),
+            byAgentSession: new Map(),
+            indexedBytes: 0,
+            ino: stat.ino,
+        };
+        await scanInto(fresh, 0, stat.size);
+        state = fresh;
+        return fresh;
+    }
+    /** Serialize reconciliation; concurrent readers queue behind one scan. */
+    function withIndex() {
+        const next = indexWork.then(reconcile, reconcile);
+        indexWork = next.catch(() => { });
+        return next;
+    }
     return {
         append(event) {
             return enqueue(async () => {
                 await ensureDir();
                 await fs.appendFile(resolvedPath, `${JSON.stringify(event)}\n`, "utf8");
+                // The index is deliberately NOT written to here. reconcile() is the one
+                // writer, and it absorbs this line by scanning from `indexedBytes` to
+                // the current size — the appended bytes only, never the whole file.
+                //
+                // Writing the entry from this side as well is the obvious optimization
+                // and it is wrong: a reader's reconcile() can stat a size that already
+                // includes this line while its scan is still in flight, so both paths
+                // record the same event and every offset after it shifts by a line. One
+                // writer, serialized, no window. The cost is a tail read on the next
+                // index() call, which is bounded by what was appended since the last
+                // one — a few hundred bytes in practice.
             });
         },
         runExclusive(fn) {
-            return enqueue(fn);
+            return enqueue(() => {
+                // A sweep rewrites the file (temp + rename): every offset the index
+                // holds points into the old inode. Drop it and let the next read
+                // rebuild, rather than trying to predict what the sweep kept.
+                state = null;
+                return fn();
+            });
+        },
+        read(filter = {}) {
+            const requested = filter.harnessSessionId === undefined
+                ? null
+                : typeof filter.harnessSessionId === "string"
+                    ? [filter.harnessSessionId]
+                    : [...filter.harnessSessionId];
+            const sessionIds = requested ? new Set(requested) : null;
+            const types = filter.types ? new Set(filter.types) : null;
+            return {
+                async *[Symbol.asyncIterator]() {
+                    if (!requested) {
+                        // Unfiltered: a full scan IS the answer the caller asked for.
+                        const stat = await statFile();
+                        if (!stat || stat.size === 0)
+                            return;
+                        for await (const line of readLines(0, stat.size - 1)) {
+                            const event = parseEventLine(line);
+                            if (event && matchesFilter(event, null, types))
+                                yield event;
+                        }
+                        return;
+                    }
+                    const index = await withIndex();
+                    // Merge the requested sessions' spans and walk them in file order,
+                    // so a record spanning several sessions still reads sequentially.
+                    const collected = [];
+                    for (const id of requested) {
+                        const entry = index.bySession.get(id);
+                        if (entry)
+                            collected.push(...entry.spans.map((span) => ({ ...span })));
+                    }
+                    collected.sort((a, b) => a.start - b.start);
+                    const spans = [];
+                    for (const span of collected)
+                        pushSpan(spans, span.start, span.end);
+                    for await (const line of readSpanLines(spans)) {
+                        const event = parseEventLine(line);
+                        if (event && matchesFilter(event, sessionIds, types))
+                            yield event;
+                    }
+                },
+            };
+        },
+        async index() {
+            const current = await withIndex();
+            // A snapshot, not the live maps. reconcile() mutates entries IN PLACE as
+            // the file grows, so handing out the internals would let a caller's
+            // `turnCount` or `lastTs` change under it between two reads of the same
+            // object — and let a caller corrupt the index by writing to a span. The
+            // copy is one small object per session; the alternative is a data race
+            // dressed up as a `ReadonlyMap`.
+            const bySession = new Map();
+            for (const [id, entry] of current.bySession) {
+                bySession.set(id, { ...entry, spans: entry.spans.map((span) => ({ ...span })), agentSessionIds: [...entry.agentSessionIds] });
+            }
+            const byAgentSession = new Map();
+            for (const [id, sessionIds] of current.byAgentSession)
+                byAgentSession.set(id, [...sessionIds]);
+            return { bySession, byAgentSession };
         },
     };
 }

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

@@ -1 +1 @@
-{"version":3,"file":"store.js","sourceRoot":"","sources":["../../../src/core/collector/store.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,KAAK,EAAE,MAAM,kBAAkB,CAAC;AACvC,OAAO,KAAK,IAAI,MAAM,WAAW,CAAC;AAElC,OAAO,EAAE,aAAa,EAAuB,MAAM,uBAAuB,CAAC;AAC3E,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAgBzC;;;GAGG;AACH,MAAM,UAAU,gBAAgB,CAAC,WAAmB,aAAa,CAAC,MAAM;IACtE,MAAM,YAAY,GAAG,UAAU,CAAC,QAAQ,CAAC,CAAC;IAC1C,IAAI,QAAQ,GAAyB,IAAI,CAAC;IAE1C,SAAS,SAAS;QAChB,IAAI,CAAC,QAAQ,EAAE,CAAC;YACd,QAAQ,GAAG,EAAE,CAAC,KAAK,CAAC,IAAI,CAAC,OAAO,CAAC,YAAY,CAAC,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC,IAAI,CAAC,GAAG,EAAE,CAAC,SAAS,CAAC,CAAC;QAC7F,CAAC;QACD,OAAO,QAAQ,CAAC;IAClB,CAAC;IAED,gEAAgE;IAChE,gEAAgE;IAChE,oDAAoD;IACpD,IAAI,KAAK,GAAkB,OAAO,CAAC,OAAO,EAAE,CAAC;IAE7C,SAAS,OAAO,CAAI,GAAqB;QACvC,MAAM,IAAI,GAAG,KAAK,CAAC,KAAK,CAAC,GAAG,EAAE,GAAE,CAAC,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;QAC7C,KAAK,GAAG,IAAI,CAAC,IAAI,CACf,GAAG,EAAE,GAAE,CAAC,EACR,GAAG,EAAE,GAAE,CAAC,CACT,CAAC;QACF,OAAO,IAAI,CAAC;IACd,CAAC;IAED,OAAO;QACL,MAAM,CAAC,KAAqB;YAC1B,OAAO,OAAO,CAAC,KAAK,IAAI,EAAE;gBACxB,MAAM,SAAS,EAAE,CAAC;gBAClB,MAAM,EAAE,CAAC,UAAU,CAAC,YAAY,EAAE,GAAG,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;YAC1E,CAAC,CAAC,CAAC;QACL,CAAC;QAED,YAAY,CAAI,EAAoB;YAClC,OAAO,OAAO,CAAC,EAAE,CAAC,CAAC;QACrB,CAAC;KACF,CAAC;AACJ,CAAC"}
+{"version":3,"file":"store.js","sourceRoot":"","sources":["../../../src/core/collector/store.ts"],"names":[],"mappings":"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"}

package/dist/core/errors.d.ts

@@ -34,12 +34,18 @@ export declare class SessionNotReadyError extends HarnessError {
     constructor(id: string);
 }
 /**
- * Thrown by `resume()` when the session record has no `agentSessionId` to
- * resume from (it was never fully started, or is history-only with no
- * recorded session). Maps to HTTP 409.
+ * Thrown by `resume()` when the session cannot be handed back to its agent.
+ * Two causes, both 409:
+ *
+ *  1. No `agentSessionId` at all — never fully started (the default message).
+ *  2. An `agentSessionId` the agent's own store no longer holds, caught by
+ *     `resume()`'s `canResume` pre-flight. Pass `reason` for these: the
+ *     message reaches the user as a toast, and "why" is the whole point —
+ *     the old behaviour spawned a doomed pty and left them with a bare
+ *     "exit code 1" and a Resume button that would fail again.
  */
 export declare class SessionNotResumeableError extends HarnessError {
-    constructor(id: string);
+    constructor(id: string, reason?: string);
 }
 /**
  * Thrown by `resume()` when the session already has a live pty — double-resume

package/dist/core/errors.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../src/core/errors.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,+CAA+C;AAC/C,qBAAa,YAAa,SAAQ,KAAK;IACrC,mFAAmF;IACnF,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,uDAAuD;IACvD,QAAQ,CAAC,KAAK,CAAC,EAAE,OAAO,CAAC;gBAEb,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,OAAO;CAQ3D;AAED;;;GAGG;AACH,qBAAa,mBAAoB,SAAQ,YAAY;gBACvC,EAAE,EAAE,MAAM;CAGvB;AAED;;;;GAIG;AACH,qBAAa,oBAAqB,SAAQ,YAAY;gBACxC,EAAE,EAAE,MAAM;CAMvB;AAED;;;;GAIG;AACH,qBAAa,yBAA0B,SAAQ,YAAY;gBAC7C,EAAE,EAAE,MAAM;CAGvB;AAED;;;GAGG;AACH,qBAAa,uBAAwB,SAAQ,YAAY;gBAC3C,EAAE,EAAE,MAAM;CAGvB;AAED;;;GAGG;AACH,qBAAa,oBAAqB,SAAQ,YAAY;gBACxC,OAAO,EAAE,MAAM;CAG5B;AAED;;;;;;;;GAQG;AACH,qBAAa,oBAAqB,SAAQ,YAAY;IACpD,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;gBAEb,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM;CAO3C"}
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../src/core/errors.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,+CAA+C;AAC/C,qBAAa,YAAa,SAAQ,KAAK;IACrC,mFAAmF;IACnF,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,uDAAuD;IACvD,QAAQ,CAAC,KAAK,CAAC,EAAE,OAAO,CAAC;gBAEb,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,OAAO;CAQ3D;AAED;;;GAGG;AACH,qBAAa,mBAAoB,SAAQ,YAAY;gBACvC,EAAE,EAAE,MAAM;CAGvB;AAED;;;;GAIG;AACH,qBAAa,oBAAqB,SAAQ,YAAY;gBACxC,EAAE,EAAE,MAAM;CAMvB;AAED;;;;;;;;;;GAUG;AACH,qBAAa,yBAA0B,SAAQ,YAAY;gBAC7C,EAAE,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM;CAGxC;AAED;;;GAGG;AACH,qBAAa,uBAAwB,SAAQ,YAAY;gBAC3C,EAAE,EAAE,MAAM;CAGvB;AAED;;;GAGG;AACH,qBAAa,oBAAqB,SAAQ,YAAY;gBACxC,OAAO,EAAE,MAAM;CAG5B;AAED;;;;;;;;GAQG;AACH,qBAAa,oBAAqB,SAAQ,YAAY;IACpD,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;gBAEb,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM;CAO3C"}

package/dist/core/errors.js

@@ -41,13 +41,19 @@ export class SessionNotReadyError extends HarnessError {
     }
 }
 /**
- * Thrown by `resume()` when the session record has no `agentSessionId` to
- * resume from (it was never fully started, or is history-only with no
- * recorded session). Maps to HTTP 409.
+ * Thrown by `resume()` when the session cannot be handed back to its agent.
+ * Two causes, both 409:
+ *
+ *  1. No `agentSessionId` at all — never fully started (the default message).
+ *  2. An `agentSessionId` the agent's own store no longer holds, caught by
+ *     `resume()`'s `canResume` pre-flight. Pass `reason` for these: the
+ *     message reaches the user as a toast, and "why" is the whole point —
+ *     the old behaviour spawned a doomed pty and left them with a bare
+ *     "exit code 1" and a Resume button that would fail again.
  */
 export class SessionNotResumeableError extends HarnessError {
-    constructor(id) {
-        super("SESSION_NOT_RESUMEABLE", `Session "${id}" has no agentSessionId to resume from`);
+    constructor(id, reason) {
+        super("SESSION_NOT_RESUMEABLE", reason ?? `Session "${id}" has no agentSessionId to resume from`);
     }
 }
 /**

package/dist/core/errors.js.map

@@ -1 +1 @@
-{"version":3,"file":"errors.js","sourceRoot":"","sources":["../../src/core/errors.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,+CAA+C;AAC/C,MAAM,OAAO,YAAa,SAAQ,KAAK;IAMrC,YAAY,IAAY,EAAE,OAAe,EAAE,KAAe;QACxD,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;QACjB,IAAI,CAAC,KAAK,GAAG,KAAK,CAAC;QACnB,sEAAsE;QACtE,IAAI,CAAC,IAAI,GAAG,GAAG,CAAC,MAAM,CAAC,IAAI,CAAC;QAC5B,MAAM,CAAC,cAAc,CAAC,IAAI,EAAE,GAAG,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC;IACpD,CAAC;CACF;AAED;;;GAGG;AACH,MAAM,OAAO,mBAAoB,SAAQ,YAAY;IACnD,YAAY,EAAU;QACpB,KAAK,CAAC,iBAAiB,EAAE,oBAAoB,EAAE,GAAG,CAAC,CAAC;IACtD,CAAC;CACF;AAED;;;;GAIG;AACH,MAAM,OAAO,oBAAqB,SAAQ,YAAY;IACpD,YAAY,EAAU;QACpB,KAAK,CACH,mBAAmB,EACnB,YAAY,EAAE,gFAAgF,CAC/F,CAAC;IACJ,CAAC;CACF;AAED;;;;GAIG;AACH,MAAM,OAAO,yBAA0B,SAAQ,YAAY;IACzD,YAAY,EAAU;QACpB,KAAK,CAAC,wBAAwB,EAAE,YAAY,EAAE,wCAAwC,CAAC,CAAC;IAC1F,CAAC;CACF;AAED;;;GAGG;AACH,MAAM,OAAO,uBAAwB,SAAQ,YAAY;IACvD,YAAY,EAAU;QACpB,KAAK,CAAC,sBAAsB,EAAE,YAAY,EAAE,0BAA0B,CAAC,CAAC;IAC1E,CAAC;CACF;AAED;;;GAGG;AACH,MAAM,OAAO,oBAAqB,SAAQ,YAAY;IACpD,YAAY,OAAe;QACzB,KAAK,CAAC,mBAAmB,EAAE,sCAAsC,OAAO,GAAG,CAAC,CAAC;IAC/E,CAAC;CACF;AAED;;;;;;;;GAQG;AACH,MAAM,OAAO,oBAAqB,SAAQ,YAAY;IAGpD,YAAY,OAAe,EAAE,KAAa;QACxC,KAAK,CACH,kBAAkB,EAClB,GAAG,KAAK,gCAAgC,KAAK,0CAA0C,CACxF,CAAC;QACF,IAAI,CAAC,OAAO,GAAG,OAAO,CAAC;IACzB,CAAC;CACF"}
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../../src/core/errors.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,+CAA+C;AAC/C,MAAM,OAAO,YAAa,SAAQ,KAAK;IAMrC,YAAY,IAAY,EAAE,OAAe,EAAE,KAAe;QACxD,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;QACjB,IAAI,CAAC,KAAK,GAAG,KAAK,CAAC;QACnB,sEAAsE;QACtE,IAAI,CAAC,IAAI,GAAG,GAAG,CAAC,MAAM,CAAC,IAAI,CAAC;QAC5B,MAAM,CAAC,cAAc,CAAC,IAAI,EAAE,GAAG,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC;IACpD,CAAC;CACF;AAED;;;GAGG;AACH,MAAM,OAAO,mBAAoB,SAAQ,YAAY;IACnD,YAAY,EAAU;QACpB,KAAK,CAAC,iBAAiB,EAAE,oBAAoB,EAAE,GAAG,CAAC,CAAC;IACtD,CAAC;CACF;AAED;;;;GAIG;AACH,MAAM,OAAO,oBAAqB,SAAQ,YAAY;IACpD,YAAY,EAAU;QACpB,KAAK,CACH,mBAAmB,EACnB,YAAY,EAAE,gFAAgF,CAC/F,CAAC;IACJ,CAAC;CACF;AAED;;;;;;;;;;GAUG;AACH,MAAM,OAAO,yBAA0B,SAAQ,YAAY;IACzD,YAAY,EAAU,EAAE,MAAe;QACrC,KAAK,CAAC,wBAAwB,EAAE,MAAM,IAAI,YAAY,EAAE,wCAAwC,CAAC,CAAC;IACpG,CAAC;CACF;AAED;;;GAGG;AACH,MAAM,OAAO,uBAAwB,SAAQ,YAAY;IACvD,YAAY,EAAU;QACpB,KAAK,CAAC,sBAAsB,EAAE,YAAY,EAAE,0BAA0B,CAAC,CAAC;IAC1E,CAAC;CACF;AAED;;;GAGG;AACH,MAAM,OAAO,oBAAqB,SAAQ,YAAY;IACpD,YAAY,OAAe;QACzB,KAAK,CAAC,mBAAmB,EAAE,sCAAsC,OAAO,GAAG,CAAC,CAAC;IAC/E,CAAC;CACF;AAED;;;;;;;;GAQG;AACH,MAAM,OAAO,oBAAqB,SAAQ,YAAY;IAGpD,YAAY,OAAe,EAAE,KAAa;QACxC,KAAK,CACH,kBAAkB,EAClB,GAAG,KAAK,gCAAgC,KAAK,0CAA0C,CACxF,CAAC;QACF,IAAI,CAAC,OAAO,GAAG,OAAO,CAAC;IACzB,CAAC;CACF"}

package/dist/core/example-seed.d.ts

@@ -11,6 +11,10 @@ export interface SeedExampleProjectOptions {
     versions?: ResolvedVersions;
     /** Overrides where the scaffold templates live (tests). */
     templatesDir?: string;
+    /** Run `npm install` in the freshly-scaffolded project so the Canvas can
+     *  bundle it on first render. Defaults to true; set false in tests to keep
+     *  them offline/fast. Ignored on reuse (nothing is re-scaffolded). */
+    installDependencies?: boolean;
 }
 export interface SeedExampleProjectResult {
     /** == options.targetRoot, resolved — the directory to open a session in. */
@@ -21,6 +25,10 @@ export interface SeedExampleProjectResult {
     created: boolean;
     /** Whether a git repo with an initial commit was created (false on reuse or when `git` is unavailable). */
     gitInitialized: boolean;
+    /** Whether `npm install` succeeded for the freshly-scaffolded project (false
+     *  on reuse, or when npm is missing/offline — the Canvas then degrades to its
+     *  "ask your agent to fix it" prompt on first render). */
+    dependenciesInstalled: boolean;
 }
 /**
  * Seeds (or reuses) the example project under `options.targetRoot`.

package/dist/core/example-seed.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"example-seed.d.ts","sourceRoot":"","sources":["../../src/core/example-seed.ts"],"names":[],"mappings":"AAqCA,OAAO,EAA0C,KAAK,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AAMnG,eAAO,MAAM,mBAAmB,iBAAiB,CAAC;AA6LlD,MAAM,WAAW,yBAAyB;IACxC;sFACkF;IAClF,UAAU,EAAE,MAAM,CAAC;IACnB;mEAC+D;IAC/D,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,sEAAsE;IACtE,QAAQ,CAAC,EAAE,gBAAgB,CAAC;IAC5B,2DAA2D;IAC3D,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAED,MAAM,WAAW,wBAAwB;IACvC,4EAA4E;IAC5E,IAAI,EAAE,MAAM,CAAC;IACb,uEAAuE;IACvE,UAAU,EAAE,MAAM,CAAC;IACnB,2DAA2D;IAC3D,OAAO,EAAE,OAAO,CAAC;IACjB,2GAA2G;IAC3G,cAAc,EAAE,OAAO,CAAC;CACzB;AAED;;;;;;;GAOG;AACH,wBAAsB,kBAAkB,CAAC,OAAO,EAAE,yBAAyB,GAAG,OAAO,CAAC,wBAAwB,CAAC,CAoD9G"}
+{"version":3,"file":"example-seed.d.ts","sourceRoot":"","sources":["../../src/core/example-seed.ts"],"names":[],"mappings":"AAyCA,OAAO,EAA0C,KAAK,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AAMnG,eAAO,MAAM,mBAAmB,iBAAiB,CAAC;AA2NlD,MAAM,WAAW,yBAAyB;IACxC;sFACkF;IAClF,UAAU,EAAE,MAAM,CAAC;IACnB;mEAC+D;IAC/D,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,sEAAsE;IACtE,QAAQ,CAAC,EAAE,gBAAgB,CAAC;IAC5B,2DAA2D;IAC3D,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB;;0EAEsE;IACtE,mBAAmB,CAAC,EAAE,OAAO,CAAC;CAC/B;AAED,MAAM,WAAW,wBAAwB;IACvC,4EAA4E;IAC5E,IAAI,EAAE,MAAM,CAAC;IACb,uEAAuE;IACvE,UAAU,EAAE,MAAM,CAAC;IACnB,2DAA2D;IAC3D,OAAO,EAAE,OAAO,CAAC;IACjB,2GAA2G;IAC3G,cAAc,EAAE,OAAO,CAAC;IACxB;;8DAE0D;IAC1D,qBAAqB,EAAE,OAAO,CAAC;CAChC;AAED;;;;;;;GAOG;AACH,wBAAsB,kBAAkB,CAAC,OAAO,EAAE,yBAAyB,GAAG,OAAO,CAAC,wBAAwB,CAAC,CA0D9G"}

package/dist/core/example-seed.js

@@ -1,13 +1,17 @@
 /**
  * Seeds the bundled example project — a directory the harness opens
- * beautifully on first run. Shared by two callers with different needs:
+ * beautifully on first run.
  *
- *   - `POST /api/sample-project` (the welcome panel's "Run the sample
- *     project" action) — seeds `~/.sapiom/harness/sample-project` lazily and
- *     idempotently: an already-seeded copy is reused as-is, including any
- *     edits the user's agent has made to it since.
- *   - `scripts/seed-example.mjs` (demo prep) — same seeding with
- *     `force: true`, which wipes and regenerates from scratch.
+ * ONE caller today: `scripts/seed-example.mjs` (demo prep), which seeds with
+ * `force: true` — wipe and regenerate from scratch.
+ *
+ * There was a second: `POST /api/sample-project`, behind the welcome panel's
+ * "Sample project" action, which seeded `~/.sapiom/harness/sample-project`
+ * lazily and idempotently. Both the route and the action were removed because
+ * the in-app flow did not work; this module was kept because the demo script
+ * still needs it. So an existing `~/.sapiom/harness/sample-project/` on a
+ * machine is leftover output, not state the app maintains — nothing in the
+ * running Studio reads or writes it.
  *
  * Produces:
  *   <targetRoot>/order-triage/    — a real scaffolded agent project
@@ -41,7 +45,12 @@ export const SAMPLE_PROJECT_NAME = "order-triage";
 /** Locate @sapiom/agent-core's bundled templates dir (no `__dirname` in ESM). */
 function agentCoreTemplatesDir() {
     const entry = nodeRequire.resolve("@sapiom/agent-core");
-    return path.resolve(path.dirname(entry), "..", "..", "templates");
+    const dir = path.resolve(path.dirname(entry), "..", "..", "templates");
+    // Embedded in Electron, require.resolve reports the app.asar (virtual) path;
+    // scaffold()'s cpSync can't opendir inside the asar archive (ENOTDIR), so
+    // point at the unpacked twin. No-op under the CLI (real filesystem path).
+    // The desktop host must asarUnpack node_modules (it unpacks all of them).
+    return dir.replace(/([\\/])app\.asar([\\/])/, "$1app.asar.unpacked$2");
 }
 function tryGit(cwd, args) {
     try {
@@ -52,6 +61,31 @@ function tryGit(cwd, args) {
         return false;
     }
 }
+/**
+ * Best-effort `npm install` in the freshly-scaffolded project. The Canvas
+ * step-graph extraction esbuild-bundles the project, so without its declared
+ * deps (`@sapiom/agent`, `zod`, …) installed the very first render fails with
+ * "Could not resolve …". Installing here means a freshly-seeded project opens
+ * with a working Canvas instead of an error the user has to ask the agent to
+ * fix. Non-fatal: if npm is missing or offline, seeding still succeeds and the
+ * Canvas falls back to its existing "ask your agent to fix it" prompt.
+ * `shell: true` lets Windows resolve the `npm.cmd` shim; cwd (which may contain
+ * spaces) is passed via options, not the command line, so it stays safe.
+ */
+function tryInstallDependencies(projectDir) {
+    try {
+        execFileSync("npm", ["install", "--no-audit", "--no-fund", "--loglevel=error"], {
+            cwd: projectDir,
+            stdio: "ignore",
+            shell: process.platform === "win32",
+            timeout: 120000,
+        });
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
 /** Fold the demo customizations (index.ts, sapiom.json) into the scaffold's initial commit. */
 function commitCustomizations(projectDir) {
     if (!existsSync(path.join(projectDir, ".git")))
@@ -251,7 +285,7 @@ export async function seedExampleProject(options) {
     };
     if (alreadySeeded && !options.force) {
         await writeCanvasPair(false);
-        return { root, projectDir, created: false, gitInitialized: false };
+        return { root, projectDir, created: false, gitInitialized: false, dependenciesInstalled: false };
     }
     // Wipe a stale copy before rescaffolding — scaffold() refuses a non-empty dir.
     await fs.rm(projectDir, { recursive: true, force: true });
@@ -270,8 +304,11 @@ export async function seedExampleProject(options) {
     });
     await fs.writeFile(path.join(projectDir, "index.ts"), ORDER_TRIAGE_INDEX_TS, "utf8");
     writeConfig(projectDir, { name: SAMPLE_PROJECT_NAME });
+    // Install deps BEFORE the initial commit so the (gitignored) node_modules is
+    // present for the Canvas's first bundle, while staying out of git history.
+    const dependenciesInstalled = (options.installDependencies ?? true) ? tryInstallDependencies(projectDir) : false;
     commitCustomizations(projectDir);
     await writeCanvasPair(true);
-    return { root, projectDir, created: true, gitInitialized: result.gitInitialized };
+    return { root, projectDir, created: true, gitInitialized: result.gitInitialized, dependenciesInstalled };
 }
 //# sourceMappingURL=example-seed.js.map

package/dist/core/example-seed.js.map

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

package/dist/core/inject/system-prompt.d.ts

@@ -4,6 +4,14 @@ export interface GenerateSystemPromptFileOptions {
     generatedRoot?: string;
     /** Defaults to the harness's default profile (DEFAULT_SYSTEM_PROMPT). */
     prompt?: string;
+    /**
+     * Extra text appended after the prompt, separated by a blank line — today
+     * the portable-continue brief (core/rehydration.ts). Kept distinct from
+     * `prompt` so a caller that only wants to *add* context doesn't have to
+     * re-import and re-compose the default profile (and can't accidentally
+     * replace it). Empty/whitespace appendices are ignored.
+     */
+    appendix?: string;
 }
 /** Writes `<generated>/<harnessSessionId>/system-prompt.txt`. Returns its
  *  absolute path (LaunchOpts.systemPromptFile). */

package/dist/core/inject/system-prompt.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"system-prompt.d.ts","sourceRoot":"","sources":["../../../src/core/inject/system-prompt.ts"],"names":[],"mappings":"AAaA,MAAM,WAAW,+BAA+B;IAC9C;iFAC6E;IAC7E,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,yEAAyE;IACzE,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED;mDACmD;AACnD,wBAAsB,wBAAwB,CAC5C,gBAAgB,EAAE,MAAM,EACxB,OAAO,GAAE,+BAAoC,GAC5C,OAAO,CAAC,MAAM,CAAC,CAQjB"}
+{"version":3,"file":"system-prompt.d.ts","sourceRoot":"","sources":["../../../src/core/inject/system-prompt.ts"],"names":[],"mappings":"AAaA,MAAM,WAAW,+BAA+B;IAC9C;iFAC6E;IAC7E,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,yEAAyE;IACzE,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB;;;;;;OAMG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED;mDACmD;AACnD,wBAAsB,wBAAwB,CAC5C,gBAAgB,EAAE,MAAM,EACxB,OAAO,GAAE,+BAAoC,GAC5C,OAAO,CAAC,MAAM,CAAC,CAUjB"}

package/dist/core/inject/system-prompt.js

@@ -15,8 +15,10 @@ export async function generateSystemPromptFile(harnessSessionId, options = {}) {
     const root = expandHome(options.generatedRoot ?? HARNESS_PATHS.generated);
     const dir = path.join(root, harnessSessionId);
     await fs.mkdir(dir, { recursive: true });
+    const base = options.prompt ?? DEFAULT_SYSTEM_PROMPT;
+    const appendix = options.appendix?.trim();
     const filePath = path.join(dir, "system-prompt.txt");
-    await fs.writeFile(filePath, options.prompt ?? DEFAULT_SYSTEM_PROMPT, "utf8");
+    await fs.writeFile(filePath, appendix ? `${base}\n\n${appendix}\n` : base, "utf8");
     return filePath;
 }
 //# sourceMappingURL=system-prompt.js.map

package/dist/core/inject/system-prompt.js.map

@@ -1 +1 @@
-{"version":3,"file":"system-prompt.js","sourceRoot":"","sources":["../../../src/core/inject/system-prompt.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,OAAO,KAAK,EAAE,MAAM,kBAAkB,CAAC;AACvC,OAAO,KAAK,IAAI,MAAM,WAAW,CAAC;AAElC,OAAO,EAAE,aAAa,EAAE,MAAM,uBAAuB,CAAC;AACtD,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AACzC,OAAO,EAAE,qBAAqB,EAAE,MAAM,2BAA2B,CAAC;AAUlE;mDACmD;AACnD,MAAM,CAAC,KAAK,UAAU,wBAAwB,CAC5C,gBAAwB,EACxB,UAA2C,EAAE;IAE7C,MAAM,IAAI,GAAG,UAAU,CAAC,OAAO,CAAC,aAAa,IAAI,aAAa,CAAC,SAAS,CAAC,CAAC;IAC1E,MAAM,GAAG,GAAG,IAAI,CAAC,IAAI,CAAC,IAAI,EAAE,gBAAgB,CAAC,CAAC;IAC9C,MAAM,EAAE,CAAC,KAAK,CAAC,GAAG,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;IAEzC,MAAM,QAAQ,GAAG,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,mBAAmB,CAAC,CAAC;IACrD,MAAM,EAAE,CAAC,SAAS,CAAC,QAAQ,EAAE,OAAO,CAAC,MAAM,IAAI,qBAAqB,EAAE,MAAM,CAAC,CAAC;IAC9E,OAAO,QAAQ,CAAC;AAClB,CAAC"}
+{"version":3,"file":"system-prompt.js","sourceRoot":"","sources":["../../../src/core/inject/system-prompt.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,OAAO,KAAK,EAAE,MAAM,kBAAkB,CAAC;AACvC,OAAO,KAAK,IAAI,MAAM,WAAW,CAAC;AAElC,OAAO,EAAE,aAAa,EAAE,MAAM,uBAAuB,CAAC;AACtD,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AACzC,OAAO,EAAE,qBAAqB,EAAE,MAAM,2BAA2B,CAAC;AAkBlE;mDACmD;AACnD,MAAM,CAAC,KAAK,UAAU,wBAAwB,CAC5C,gBAAwB,EACxB,UAA2C,EAAE;IAE7C,MAAM,IAAI,GAAG,UAAU,CAAC,OAAO,CAAC,aAAa,IAAI,aAAa,CAAC,SAAS,CAAC,CAAC;IAC1E,MAAM,GAAG,GAAG,IAAI,CAAC,IAAI,CAAC,IAAI,EAAE,gBAAgB,CAAC,CAAC;IAC9C,MAAM,EAAE,CAAC,KAAK,CAAC,GAAG,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;IAEzC,MAAM,IAAI,GAAG,OAAO,CAAC,MAAM,IAAI,qBAAqB,CAAC;IACrD,MAAM,QAAQ,GAAG,OAAO,CAAC,QAAQ,EAAE,IAAI,EAAE,CAAC;IAC1C,MAAM,QAAQ,GAAG,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,mBAAmB,CAAC,CAAC;IACrD,MAAM,EAAE,CAAC,SAAS,CAAC,QAAQ,EAAE,QAAQ,CAAC,CAAC,CAAC,GAAG,IAAI,OAAO,QAAQ,IAAI,CAAC,CAAC,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;IACnF,OAAO,QAAQ,CAAC;AAClB,CAAC"}