@sapiom/harness 0.1.5 → 0.2.0

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"}

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

@@ -1 +1 @@
-{"version":3,"file":"macros.d.ts","sourceRoot":"","sources":["../../src/core/macros.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,oBAAoB,CAAC;AAEnD,eAAO,MAAM,cAAc,EAAE,QAAQ,EA4DpC,CAAC"}
+{"version":3,"file":"macros.d.ts","sourceRoot":"","sources":["../../src/core/macros.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,oBAAoB,CAAC;AAEnD,eAAO,MAAM,cAAc,EAAE,QAAQ,EA2DpC,CAAC"}

package/dist/core/macros.js

@@ -46,12 +46,11 @@ export const DEFAULT_MACROS = [
         },
     },
     {
-        // One-click force refresh of the bound workflow's canvas: re-runs the
-        // deterministic, zero-LLM structure render (core/canvas-render.ts —
-        // instant, cache-invalidated) AND re-spawns the bounded AI enrichment
-        // task (core/canvas-enrich.ts, a headless background run that returns
-        // validated JSON annotations, never HTML) — all server-side, without
-        // touching the session's pty. A cheap no-op when the session is unbound.
+        // One-click refresh of the bound workflow's canvas: drops the extraction
+        // cache and re-runs the fully deterministic render (core/canvas-render.ts
+        // — structure + derived annotations, no LLM, no user token), all
+        // server-side without touching the session's pty. A cheap no-op when the
+        // session is unbound.
         id: "visualize",
         label: "Visualize",
         icon: "Sparkles",

package/dist/core/macros.js.map

@@ -1 +1 @@
-{"version":3,"file":"macros.js","sourceRoot":"","sources":["../../src/core/macros.ts"],"names":[],"mappings":"AASA,MAAM,CAAC,MAAM,cAAc,GAAe;IACxC;QACE,EAAE,EAAE,WAAW;QACf,KAAK,EAAE,WAAW;QAClB,IAAI,EAAE,MAAM;QACZ,gBAAgB,EAAE,IAAI;QACtB,MAAM,EAAE;YACN,IAAI,EAAE,QAAQ;YACd,MAAM,EAAE,IAAI;YACZ,+EAA+E;YAC/E,yEAAyE;YACzE,qDAAqD;YACrD,IAAI,EAAE,0DAA0D;SACjE;KACF;IACD;QACE,EAAE,EAAE,QAAQ;QACZ,KAAK,EAAE,QAAQ;QACf,IAAI,EAAE,OAAO;QACb,gBAAgB,EAAE,IAAI;QACtB,MAAM,EAAE;YACN,IAAI,EAAE,QAAQ;YACd,MAAM,EAAE,IAAI;YACZ,IAAI,EAAE,8CAA8C;SACrD;KACF;IACD;QACE,EAAE,EAAE,UAAU;QACd,KAAK,EAAE,UAAU;QACjB,IAAI,EAAE,KAAK;QACX,gBAAgB,EAAE,IAAI;QACtB,MAAM,EAAE;YACN,IAAI,EAAE,QAAQ;YACd,MAAM,EAAE,IAAI;YACZ,IAAI,EAAE,yDAAyD;SAChE;KACF;IACD;QACE,EAAE,EAAE,WAAW;QACf,KAAK,EAAE,WAAW;QAClB,IAAI,EAAE,cAAc;QACpB,gBAAgB,EAAE,IAAI;QACtB,MAAM,EAAE;YACN,IAAI,EAAE,UAAU;YAChB,GAAG,EAAE,2DAA2D;SACjE;KACF;IACD;QACE,sEAAsE;QACtE,oEAAoE;QACpE,sEAAsE;QACtE,sEAAsE;QACtE,qEAAqE;QACrE,yEAAyE;QACzE,EAAE,EAAE,WAAW;QACf,KAAK,EAAE,WAAW;QAClB,IAAI,EAAE,UAAU;QAChB,gBAAgB,EAAE,KAAK;QACvB,MAAM,EAAE,EAAE,IAAI,EAAE,eAAe,EAAE;KAClC;CACF,CAAC"}
+{"version":3,"file":"macros.js","sourceRoot":"","sources":["../../src/core/macros.ts"],"names":[],"mappings":"AASA,MAAM,CAAC,MAAM,cAAc,GAAe;IACxC;QACE,EAAE,EAAE,WAAW;QACf,KAAK,EAAE,WAAW;QAClB,IAAI,EAAE,MAAM;QACZ,gBAAgB,EAAE,IAAI;QACtB,MAAM,EAAE;YACN,IAAI,EAAE,QAAQ;YACd,MAAM,EAAE,IAAI;YACZ,+EAA+E;YAC/E,yEAAyE;YACzE,qDAAqD;YACrD,IAAI,EAAE,0DAA0D;SACjE;KACF;IACD;QACE,EAAE,EAAE,QAAQ;QACZ,KAAK,EAAE,QAAQ;QACf,IAAI,EAAE,OAAO;QACb,gBAAgB,EAAE,IAAI;QACtB,MAAM,EAAE;YACN,IAAI,EAAE,QAAQ;YACd,MAAM,EAAE,IAAI;YACZ,IAAI,EAAE,8CAA8C;SACrD;KACF;IACD;QACE,EAAE,EAAE,UAAU;QACd,KAAK,EAAE,UAAU;QACjB,IAAI,EAAE,KAAK;QACX,gBAAgB,EAAE,IAAI;QACtB,MAAM,EAAE;YACN,IAAI,EAAE,QAAQ;YACd,MAAM,EAAE,IAAI;YACZ,IAAI,EAAE,yDAAyD;SAChE;KACF;IACD;QACE,EAAE,EAAE,WAAW;QACf,KAAK,EAAE,WAAW;QAClB,IAAI,EAAE,cAAc;QACpB,gBAAgB,EAAE,IAAI;QACtB,MAAM,EAAE;YACN,IAAI,EAAE,UAAU;YAChB,GAAG,EAAE,2DAA2D;SACjE;KACF;IACD;QACE,yEAAyE;QACzE,0EAA0E;QAC1E,iEAAiE;QACjE,yEAAyE;QACzE,sBAAsB;QACtB,EAAE,EAAE,WAAW;QACf,KAAK,EAAE,WAAW;QAClB,IAAI,EAAE,UAAU;QAChB,gBAAgB,EAAE,KAAK;QACvB,MAAM,EAAE,EAAE,IAAI,EAAE,eAAe,EAAE;KAClC;CACF,CAAC"}

package/dist/core/paths.d.ts

@@ -15,6 +15,7 @@ export interface HarnessStatePaths {
     events: string;
     settings: string;
     generated: string;
+    records: string;
     sampleProject: string;
 }
 /**

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

@@ -1 +1 @@
-{"version":3,"file":"paths.d.ts","sourceRoot":"","sources":["../../src/core/paths.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAOH,iFAAiF;AACjF,wBAAgB,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAI/C;AAED;oDACoD;AACpD,MAAM,WAAW,iBAAiB;IAChC,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;IAClB,aAAa,EAAE,MAAM,CAAC;CACvB;AAUD;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAAC,SAAS,CAAC,EAAE,MAAM,GAAG,iBAAiB,CAYvE"}
+{"version":3,"file":"paths.d.ts","sourceRoot":"","sources":["../../src/core/paths.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAOH,iFAAiF;AACjF,wBAAgB,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAI/C;AAED;oDACoD;AACpD,MAAM,WAAW,iBAAiB;IAChC,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,MAAM,CAAC;IAChB,aAAa,EAAE,MAAM,CAAC;CACvB;AAUD;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAAC,SAAS,CAAC,EAAE,MAAM,GAAG,iBAAiB,CAavE"}

package/dist/core/paths.js

@@ -37,6 +37,7 @@ export function resolveStatePaths(stateRoot) {
         events: join(root, relativeToHome(HARNESS_PATHS.events)),
         settings: join(root, relativeToHome(HARNESS_PATHS.settings)),
         generated: join(root, relativeToHome(HARNESS_PATHS.generated)),
+        records: join(root, relativeToHome(HARNESS_PATHS.records)),
         sampleProject: join(root, relativeToHome(HARNESS_PATHS.sampleProject)),
     };
 }

package/dist/core/paths.js.map

@@ -1 +1 @@
-{"version":3,"file":"paths.js","sourceRoot":"","sources":["../../src/core/paths.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,OAAO,EAAE,MAAM,SAAS,CAAC;AAClC,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAE1C,OAAO,EAAE,YAAY,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AAEjE,iFAAiF;AACjF,MAAM,UAAU,UAAU,CAAC,IAAY;IACrC,IAAI,IAAI,KAAK,GAAG;QAAE,OAAO,OAAO,EAAE,CAAC;IACnC,IAAI,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC;QAAE,OAAO,OAAO,CAAC,OAAO,EAAE,EAAE,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC;IACpE,OAAO,OAAO,CAAC,IAAI,CAAC,CAAC;AACvB,CAAC;AAeD;;;2CAG2C;AAC3C,SAAS,cAAc,CAAC,KAAa;IACnC,OAAO,KAAK,CAAC,KAAK,CAAC,YAAY,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC;AAC9C,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,iBAAiB,CAAC,SAAkB;IAClD,MAAM,IAAI,GAAG,UAAU,CAAC,SAAS,IAAI,YAAY,CAAC,CAAC;IACnD,OAAO;QACL,IAAI;QACJ,SAAS,EAAE,IAAI,CAAC,IAAI,EAAE,cAAc,CAAC,aAAa,CAAC,SAAS,CAAC,CAAC;QAC9D,QAAQ,EAAE,IAAI,CAAC,IAAI,EAAE,cAAc,CAAC,aAAa,CAAC,QAAQ,CAAC,CAAC;QAC5D,SAAS,EAAE,IAAI,CAAC,IAAI,EAAE,cAAc,CAAC,aAAa,CAAC,SAAS,CAAC,CAAC;QAC9D,MAAM,EAAE,IAAI,CAAC,IAAI,EAAE,cAAc,CAAC,aAAa,CAAC,MAAM,CAAC,CAAC;QACxD,QAAQ,EAAE,IAAI,CAAC,IAAI,EAAE,cAAc,CAAC,aAAa,CAAC,QAAQ,CAAC,CAAC;QAC5D,SAAS,EAAE,IAAI,CAAC,IAAI,EAAE,cAAc,CAAC,aAAa,CAAC,SAAS,CAAC,CAAC;QAC9D,aAAa,EAAE,IAAI,CAAC,IAAI,EAAE,cAAc,CAAC,aAAa,CAAC,aAAa,CAAC,CAAC;KACvE,CAAC;AACJ,CAAC"}
+{"version":3,"file":"paths.js","sourceRoot":"","sources":["../../src/core/paths.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,OAAO,EAAE,MAAM,SAAS,CAAC;AAClC,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAE1C,OAAO,EAAE,YAAY,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AAEjE,iFAAiF;AACjF,MAAM,UAAU,UAAU,CAAC,IAAY;IACrC,IAAI,IAAI,KAAK,GAAG;QAAE,OAAO,OAAO,EAAE,CAAC;IACnC,IAAI,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC;QAAE,OAAO,OAAO,CAAC,OAAO,EAAE,EAAE,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC;IACpE,OAAO,OAAO,CAAC,IAAI,CAAC,CAAC;AACvB,CAAC;AAgBD;;;2CAG2C;AAC3C,SAAS,cAAc,CAAC,KAAa;IACnC,OAAO,KAAK,CAAC,KAAK,CAAC,YAAY,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC;AAC9C,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,iBAAiB,CAAC,SAAkB;IAClD,MAAM,IAAI,GAAG,UAAU,CAAC,SAAS,IAAI,YAAY,CAAC,CAAC;IACnD,OAAO;QACL,IAAI;QACJ,SAAS,EAAE,IAAI,CAAC,IAAI,EAAE,cAAc,CAAC,aAAa,CAAC,SAAS,CAAC,CAAC;QAC9D,QAAQ,EAAE,IAAI,CAAC,IAAI,EAAE,cAAc,CAAC,aAAa,CAAC,QAAQ,CAAC,CAAC;QAC5D,SAAS,EAAE,IAAI,CAAC,IAAI,EAAE,cAAc,CAAC,aAAa,CAAC,SAAS,CAAC,CAAC;QAC9D,MAAM,EAAE,IAAI,CAAC,IAAI,EAAE,cAAc,CAAC,aAAa,CAAC,MAAM,CAAC,CAAC;QACxD,QAAQ,EAAE,IAAI,CAAC,IAAI,EAAE,cAAc,CAAC,aAAa,CAAC,QAAQ,CAAC,CAAC;QAC5D,SAAS,EAAE,IAAI,CAAC,IAAI,EAAE,cAAc,CAAC,aAAa,CAAC,SAAS,CAAC,CAAC;QAC9D,OAAO,EAAE,IAAI,CAAC,IAAI,EAAE,cAAc,CAAC,aAAa,CAAC,OAAO,CAAC,CAAC;QAC1D,aAAa,EAAE,IAAI,CAAC,IAAI,EAAE,cAAc,CAAC,aAAa,CAAC,aAAa,CAAC,CAAC;KACvE,CAAC;AACJ,CAAC"}

package/dist/core/record-archive.d.ts

@@ -0,0 +1,187 @@
+/**
+ * Durable session records — what makes session history outlive the raw event
+ * log it was rebuilt from.
+ *
+ * THE PROBLEM. `events.ndjson` is an analytics sink with an analytics sink's
+ * retention: 50 MB / 30 days, truncated oldest-first (core/collector/
+ * store-retention.ts). Once session history is *built on* that file
+ * (core/session-record.ts), the sweep silently deletes history — a session a
+ * user can read today is gone next month, with no way to tell "never existed"
+ * from "swept". A record the user can open is a product surface; a byte cap on
+ * an append-only debug log is not the right lifetime for it.
+ *
+ * THE FIX. At session end we fold the record once and write a compacted copy to
+ * `~/.sapiom/harness/records/<harnessSessionId>.json`. It is bounded (see the
+ * caps below), it is one file per conversation, and it survives every sweep of
+ * the ndjson because it isn't in it. The ndjson goes back to being what it is:
+ * the raw analytics sink.
+ *
+ * WHY NOT UNDER `<generated>/<sessionId>/`, which the ticket suggested and
+ * which already has a retention sweep: that directory is deleted the moment a
+ * session's pty exits (server/index.ts's "exited" handler calls
+ * removeGeneratedSessionDir — every file in it is regenerated on the next
+ * launch), and whatever survives that is swept 7 days after it goes stale.
+ * Both lifetimes are *shorter* than the 30 days of events the archive exists to
+ * outlive, so a record written there would die sooner than the log it was meant
+ * to survive. Records get their own root and their own policy instead.
+ *
+ * COMPACTION is lossy, on purpose, and says so. Tool inputs and tool results
+ * are the bulk of the bytes (`tool.call` was ~80% of observed event volume) and
+ * the least useful part of a record read weeks later, so they are clipped hard;
+ * prompts and assistant text — the conversation — are clipped only at the
+ * collector's own field cap, so in practice they are kept whole. Every loss
+ * lands in `SessionRecord.limitations` (`compacted-archive`,
+ * `dropped-early-turns`) and the UI renders it as prose, per this epic's rule
+ * that a reconstruction never gets to imply it is complete.
+ *
+ * SIZE CEILING, stated exactly: a record is compacted to at most
+ * {@link RECORD_MAX_BYTES} by clipping fields and then dropping whole turns
+ * oldest-first — but never below one turn. A single turn with hundreds of tool
+ * calls can therefore exceed the per-record cap; the store's total-bytes cap
+ * ({@link RECORDS_MAX_TOTAL_BYTES}, enforced against real file sizes) is the
+ * hard bound, and one outsized record just crowds out older ones sooner.
+ */
+import type { SessionRecord } from "../shared/types.js";
+/** Tool input, clipped hard: a 40 KB Edit payload is not what makes a
+ *  months-old record worth keeping, and it is most of its bytes. */
+export declare const RECORDS_MAX_TOOL_INPUT_CHARS = 512;
+/** Tool result, same reasoning. The collector already caps these at 16 KB. */
+export declare const RECORDS_MAX_TOOL_RESPONSE_CHARS = 512;
+/** Prompts and assistant text — the conversation itself. Set at the
+ *  collector's own field cap (normalizer.ts's MAX_FIELD_LENGTH), so this
+ *  clips nothing the log didn't already clip. Kept as our own constant
+ *  because the archive's contract is "the conversation survives whole". */
+export declare const RECORDS_MAX_TEXT_CHARS = 4000;
+/** Per-record byte ceiling — see the module header for the one case that
+ *  legitimately exceeds it. ~64 KB holds a long session comfortably once tool
+ *  payloads are clipped. */
+export declare const RECORD_MAX_BYTES: number;
+/** Whole-store byte ceiling. A third of the raw sink's 50 MB, for two orders
+ *  of magnitude more sessions: at 64 KB worst-case per record it guarantees
+ *  256 archived conversations, and at realistic sizes holds thousands. */
+export declare const RECORDS_MAX_TOTAL_BYTES: number;
+/** Age ceiling. Deliberately far longer than the events' 30 days — the whole
+ *  point of the archive is to outlive them — while still bounded, so an
+ *  install that runs for years doesn't accumulate forever. */
+export declare const RECORDS_MAX_AGE_MS: number;
+/**
+ * A record that has been through the archive: identical to a {@link
+ * SessionRecord} except that `archivedAt` is known to be set. The distinction
+ * is load-bearing for the reader, which compares that stamp against the event
+ * log to decide which of the two sources still holds the whole conversation.
+ */
+export type ArchivedSessionRecord = SessionRecord & {
+    archivedAt: string;
+};
+/** What the archive knows about one stored record without reading it again. */
+export interface ArchivedRecordSummary {
+    /** Primary id the record is filed under (the conversation's first session). */
+    harnessSessionId: string;
+    /** Every id this record answers to: primary, merged sessions, agent session. */
+    keys: string[];
+    /** Human turns in the CONVERSATION (not necessarily in the stored turns —
+     *  see `SessionRecord.turnCount`). */
+    turnCount: number;
+    /** ISO-8601 of when the record was archived. */
+    archivedAt: string;
+    /** Size of the file on disk. */
+    bytes: number;
+    /** Absolute path of the record file. */
+    file: string;
+}
+export interface RecordArchiveOptions {
+    /** Root the record files live in. Required — the caller resolves it from the
+     *  server's state root so an isolated boot never writes to the real home. */
+    root: string;
+    maxRecordBytes?: number;
+    maxTotalBytes?: number;
+    maxAgeMs?: number;
+    /** Injectable clock (epoch ms) for tests. */
+    now?: () => number;
+    /** Diagnostics sink. Defaults to console.error. */
+    onError?: (err: unknown) => void;
+}
+export interface RecordArchive {
+    /**
+     * Compact `record` and write it, replacing any earlier archive of the same
+     * conversation. Returns what was written, or null when there was nothing
+     * worth archiving (a record with no turns) or the write failed — never
+     * throws: failing to archive must not take a session's exit down with it.
+     */
+    write(record: SessionRecord): Promise<ArchivedSessionRecord | null>;
+    /**
+     * The archived record for `id` — a harnessSessionId (primary or merged) or
+     * the agent's own session id — or null when there is none. Never throws; a
+     * corrupt file reads as absent.
+     */
+    read(id: string): Promise<ArchivedSessionRecord | null>;
+    /** True when {@link read} would find a record, without reading the file. */
+    has(id: string): Promise<boolean>;
+    /** Every stored record's summary, newest first. */
+    list(): Promise<ArchivedRecordSummary[]>;
+    /**
+     * Enforce the age and total-size caps, oldest-first. Returns the primary ids
+     * removed. Best-effort per file: one undeletable record doesn't abort the
+     * rest.
+     */
+    sweep(): Promise<string[]>;
+}
+export interface CompactionOptions {
+    maxBytes?: number;
+    maxToolInputChars?: number;
+    maxToolResponseChars?: number;
+    maxTextChars?: number;
+    /** ISO-8601 stamp to record as `archivedAt`. Defaults to now. */
+    archivedAt?: string;
+}
+/**
+ * The bounded, archivable form of a record: fields clipped, oldest turns
+ * dropped if it still doesn't fit, and every loss declared in `limitations`.
+ *
+ * Pure and idempotent — compacting an already-compacted record clips nothing
+ * further and drops nothing further, which matters because a re-archive
+ * (a session that ends twice, a backfill) must not shrink a record a little
+ * more each time.
+ *
+ * `turnCount` and `eventCount` deliberately keep their pre-compaction values:
+ * they describe the conversation that happened, not the excerpt that survived.
+ * A history row's turn count therefore doesn't change when its record is
+ * archived, and `dropped-early-turns` is what tells the reader that `turns`
+ * holds fewer than `turnCount` of them.
+ */
+export declare function compactSessionRecord(record: SessionRecord, options?: CompactionOptions): ArchivedSessionRecord;
+export declare function createRecordArchive(options: RecordArchiveOptions): RecordArchive;
+export interface BackfillOptions {
+    /** Conversations present in the event log, newest activity first. */
+    conversationIds: () => Promise<string[]>;
+    /** Fold a conversation from the events alone (never from the archive). */
+    readFromEvents: (harnessSessionId: string) => Promise<SessionRecord | null>;
+    archive: Pick<RecordArchive, "has" | "write">;
+    /** A live session is still writing events; archiving it now would store a
+     *  half-finished record and pre-empt the archive its exit will write. */
+    isLiveSession?: (harnessSessionId: string) => boolean;
+    /** Ceiling on how many conversations one pass archives. */
+    maxRecords?: number;
+    /** Called with the number of eligible conversations left unarchived when the
+     *  cap cut the pass short — a bounded pass must say what it didn't do. */
+    onCapped?: (remaining: number) => void;
+}
+/** Default ceiling for one backfill pass. High enough to cover a typical
+ *  install's whole history on the first boot after this shipped, low enough
+ *  that a pathological log doesn't turn boot into a write storm. Whatever is
+ *  left is archived by the next boot's pass. */
+export declare const RECORDS_BACKFILL_MAX = 200;
+/**
+ * Archive conversations the event log still holds but the archive doesn't.
+ *
+ * Two things need this, and neither is covered by archiving at session end:
+ * sessions that ended without one (the harness force-killed, the machine
+ * rebooted), and every session that ended *before* this feature existed — whose
+ * history would otherwise disappear at its 30-day mark with the archive looking
+ * on. Idempotent: a conversation already archived is skipped, so the steady
+ * state after the first pass is "nothing to do".
+ *
+ * Never throws. Returns the ids it archived.
+ */
+export declare function backfillSessionRecords(options: BackfillOptions): Promise<string[]>;
+//# sourceMappingURL=record-archive.d.ts.map

package/dist/core/record-archive.d.ts.map

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