@sapiom/harness 0.1.0 → 0.1.2

package/CHANGELOG.md

@@ -0,0 +1,162 @@
+# @sapiom/harness
+
+## 0.1.2
+
+### Patch Changes
+
+- 0cc7cd5: Fix two canvas v0 bugs:
+
+  **UI (CanvasPane)**: While an enrichment task runs, the activity strip now overlays the iframe instead of replacing it. The deterministic SVG render is visible immediately after binding; the spinner appears on top during the LLM annotation pass and disappears on completion. Failure state (Retry/Dismiss) remains full-screen and is unchanged.
+
+  **Server (forceRefresh)**: The already-running check for a workflow's enrichment task is now performed before any cache invalidation or re-render. A double-clicked Visualize correctly rejects with a 409 and leaves the enrichment cache and render files exactly as the still-running task will need them.
+
+- a318f0b: HarnessAdapter registry with embedded/external modes
+
+  - Introduces `HarnessAdapterInfo` union type (`EmbeddedHarnessAdapterInfo` | `ExternalHarnessAdapterInfo`) with a `mode` field distinguishing harnesses spawned by the harness server from companion-app harnesses that own their own sessions.
+  - Adds a data-driven registry (`createHarnessAdapterRegistry`, `listHarnessAdapters`, `getHarnessAdapter`) backed by five built-in adapters: claude-code, codex (both embedded), pi, opencode (embedded, experimental), and conductor (external).
+  - Each adapter entry carries an `installMcpPrompt()` method with per-harness MCP install guidance — the skills-panel Install MCP modal reads these from the registry rather than embedding its own copy.
+  - Adds `GET /api/harnesses` endpoint returning all adapters with `id`, `label`, `mode`, `experimental`, and `installed` fields. Embedded entries are session-createable today; external entries expose `mode:"external"` for future UI rendering.
+  - Adds `ExternalHarnessError` (code `HARNESS_EXTERNAL`, HTTP 409) thrown from `SessionManager.getAdapter()` (resume path) and `SessionManager.submitInput()` (input path) when a session's harness id resolves to an external-mode adapter. A `sessions.json` entry written by an earlier build, hand-edited, or imported with `harness="conductor"` now surfaces a clear "managed by the Conductor app" 409 instead of a generic adapter-not-found error or a silent 404.
+  - Exports `SPAWNABLE_HARNESS_KINDS` as a const tuple from `shared/types.ts` — the single source of truth that both derives the `HarnessKind` type and supplies the values to `z.enum()` in the session-creation schema, preventing drift between the two.
+  - Routes the codex-tailer branching in server/index.ts through `adapter.eventSource` instead of a hardcoded `session.harness !== "codex"` check.
+  - `UnknownHarnessAdapterError` (code `UNKNOWN_HARNESS_ADAPTER`) is thrown by registry lookups for unknown ids, listing known ids in the message for self-correction.
+  - claude-code and codex behavior is byte-identical — no changes to their existing runtime adapter implementations (launch/resume/doctor/listPastSessions).
+
+- c8c4746: Remote telemetry now reaches the hosted collector.
+
+  The bespoke `CollectorBatcher` (which posted to a non-existent `/v1/harness/events` endpoint) has been replaced by `@sapiom/analytics-core`. Events are now delivered to `POST /v1/analytics/collector` — the same endpoint used by all other Sapiom SDK packages.
+
+  **What changes for users:**
+  - Remote telemetry (consent-gated, as before) now actually works. Previously all remote traffic was silently dropped because the target endpoint did not exist.
+  - The local `~/.sapiom/harness/events.ndjson` sink continues to be written on every event regardless of consent, unchanged.
+  - Consent behavior (stored settings toggle, `--no-telemetry` flag, `SAPIOM_TELEMETRY_DISABLED=1`, `DO_NOT_TRACK=1`) is unchanged.
+  - Anonymous identity migrates: on first boot after upgrade, the install's existing `~/.sapiom/harness/machine-id` value is seeded into `~/.sapiom/analytics.json` so the longitudinal join key survives across versions.
+
+- 97e8259: Awaitable kill for harness sessions and tasks with liveness-fallback resolution.
+
+  `SessionManager.kill()` now returns `Promise<boolean>` that resolves once the
+  process is **actually gone** — not fire-and-forget. Existing callers that do not
+  await the return value keep working unchanged.
+
+  Resolution is driven by whichever path fires first: node-pty's real `onExit`
+  event, or a synthesized exit from `kill()`'s own escalation path. The escalation
+  path is genuinely bounded:
+
+  1. SIGTERM sent immediately.
+  2. After `KILL_ESCALATION_MS` (2000 ms): if still alive, send SIGKILL.
+  3. After a further `KILL_ESCALATION_CONFIRM_MS` (500 ms): `markExited()` is
+     called **unconditionally** — SIGKILL has been sent and the window has
+     elapsed, so the session is over regardless of any liveness probe. This
+     prevents an EPERM zombie (a process that `isPidAlive` still reports as alive
+     after SIGKILL) from leaving the promise pending forever.
+
+  `SessionManager.killAll()` is now `async` and resolves when all concurrent kills
+  have confirmed death via `markExited()` — the single convergence point for real
+  and synthesized exits alike.
+
+  `TaskManager.killAll()` gains the same awaitable treatment with SIGTERM→SIGKILL
+  escalation and per-task exit promises wired through the existing `finish()`
+  convergence point. After the SIGKILL confirm window, `finish(id, null)` is
+  synthesized for any still-registered process — a zombie that never emits an exit
+  event is declared dead rather than leaving `killAll()` pending forever.
+  `finish()`'s idempotence guard prevents a double-fire if the real exit event
+  arrives concurrently.
+
+  Server shutdown (`close()` in server/index.ts) now awaits both `killAll()` calls
+  with a 5-second outer timeout, so the process actually exits cleanly instead of
+  leaving orphaned agent children.
+
+- 1ff8d3c: Document that the harness is also launchable via `sapiom dev [dir]` from `@sapiom/cli`.
+- 6d7ccd8: Packaging polish: LICENSE file, explicit exports map, and pack-contents audit.
+
+  Adds a per-package LICENSE file (MIT, matching repo root) so published tarballs include it. Adds an explicit `exports` map with a main entry (`"."`) and `"./package.json"` sub-path — the latter is required by `@sapiom/cli`'s `createRequire().resolve('@sapiom/harness/package.json')` resolution path; without it a conditional-exports package would fire `ERR_PACKAGE_PATH_NOT_EXPORTED` and break `sapiom dev`. Updates `files` to include `LICENSE`, `CHANGELOG.md`, and `README.md` alongside `dist`. Excludes `src/test-setup.ts` from the build tsconfig so `dist/test-setup.*` no longer appears in the published tarball. Stays ESM-only (`"type": "module"`) — the harness is an app-style bin package, not a library; a dual CJS+ESM build would introduce the dual-package hazard for the typed error hierarchy (`instanceof` dispatch) with no user benefit.
+
+- e0334ca: Terminal-only center pane for v0
+
+  The center pane renders the xterm terminal as the sole content when a session
+  is live, and the exited-session overlay (resume / close) when the session has
+  exited. The first-run welcome panel continues to appear when no session exists
+  on a fresh install.
+
+  - Analytics hook pipeline (SessionStart / UserPromptSubmit / PreToolUse /
+    PostToolUse / Stop / SessionEnd → /ingest → normalizer → store + emitter →
+    collector) is fully intact and independent of the center-pane shape
+  - Skills panel, canvas, consent chip, telemetry, adapter registry, session
+    kill/resume, and typed errors are all preserved
+
+- 6c64501: Internal robustness fixes (no behavior change for users):
+
+  - Serialize WorkflowRegistry writes through a promise queue so concurrent prune/scan/connectPath calls can't interleave and drop entries from workflows.json.
+  - Thread the resolved workflow path from the macros router into background task requests so TaskManager can dedupe per-workflow across sessions, not just per-session.
+  - Make the workspace-watcher polling fallback walk async (fs/promises) to avoid blocking the event loop on wide directories; lengthen the poll interval to 2 s.
+
+- 58ec57f: Fix Sapiom skill registration in harness sessions. `@sapiom/agent-core` now
+  exposes its `package.json` through the `exports` map so consumers can resolve
+  its bundled `skills/` directory; previously `require.resolve` threw
+  `ERR_PACKAGE_PATH_NOT_EXPORTED` and the skill silently never loaded. The harness
+  skill-plugin resolver also gains a fallback that locates the skills directory by
+  resolving the package's main entry when the `package.json` subpath isn't
+  exported. Skills register under the `sapiom` plugin namespace, so the
+  agent-authoring skill is available as `/sapiom:sapiom-agent-authoring`.
+- 1b355a4: Typed error codes on session and spawn failures; HTTP status mappings unchanged.
+
+  Adds a `HarnessError` base class and five typed subclasses — `UnknownSessionError`, `SessionNotReadyError`, `SessionNotResumeableError`, `SessionAlreadyLiveError`, `AdapterNotFoundError` — each carrying a stable machine-readable `code` property. Server routes now dispatch on `instanceof` rather than parsing `error.message` text, so future message rewordings cannot silently alter the HTTP status they produce. Wire responses and response body shapes are unchanged.
+
+- a686143: Skills panel Use button populates the terminal (no auto-submit); Sapiom skills registered as session slash commands via --plugin-dir.
+
+  - Re-adds the "Use skill" button to the skill detail view. Clicking it calls
+    `injectInput` with `submit:false`, writing the text to Claude's input line
+    without sending Enter — the user edits and presses Enter themselves.
+  - Package skills populate `/<id> ` (slash command with trailing space for args);
+    user skills populate a natural-language invocation `Use the "<name>" skill: <desc>`.
+  - Button is disabled with a visible reason when there is no ready session.
+  - On success, a toast confirms "Typed into the terminal — edit and press Enter."
+  - Adds `generateSkillsPlugin` in `core/inject/skills-plugin.ts`: creates a
+    per-session `--plugin-dir` from the Sapiom skills bundled in `@sapiom/agent-core`.
+    claude-code auto-discovers `<plugin-dir>/skills/<name>/SKILL.md` and registers
+    `/<name>` as a slash command. Gracefully no-ops when agent-core's skills dir is
+    absent or unresolvable — the session still launches normally without the flag.
+  - `LaunchOpts.pluginDir` added; `ClaudeCodeAdapter.buildConfigArgs` emits
+    `--plugin-dir <path>` when set. Codex adapter ignores the field (unchanged).
+
+- Updated dependencies [696f111]
+- Updated dependencies [48fb35c]
+- Updated dependencies [95bfcd1]
+- Updated dependencies [bf44229]
+- Updated dependencies [dab6d44]
+- Updated dependencies [ebfa0bc]
+- Updated dependencies [58ec57f]
+- Updated dependencies [5e9659a]
+  - @sapiom/agent-core@0.9.2
+  - @sapiom/analytics-core@0.2.1
+  - @sapiom/mcp@0.11.2
+
+## 0.1.1
+
+### Patch Changes
+
+- Updated dependencies [5f73ae7]
+- Updated dependencies [d661d57]
+  - @sapiom/mcp@0.11.0
+  - @sapiom/agent-core@0.9.0
+  - @sapiom/agent@0.6.2
+
+## 0.1.0
+
+### Minor Changes
+
+- 020139a: Canvas serving, macro engine, and dev-server port detection — the backend half of the canvas/action-rail/preview workstream:
+
+  - `GET /canvas/:harnessSessionId/*` serves whatever a session's agent wrote to its `.sapiom/canvas/` directory, with a friendly HTML empty-state when nothing's been rendered yet.
+  - `GET /api/macros` / `POST /api/macros/:id/run` resolve and execute the action-rail macros (`{{workflow.path}}`-style placeholder substitution, missing-value validation).
+  - Per-session canvas file watching (`canvas.reload` on change) and streaming `localhost:<port>` detection (`port.detected`) for the Preview pane's port chip.
+
+### Patch Changes
+
+- Updated dependencies [020139a]
+- Updated dependencies [020139a]
+- Updated dependencies [c0fef6d]
+- Updated dependencies [3dfbd10]
+  - @sapiom/agent@0.6.1
+  - @sapiom/agent-core@0.8.0
+  - @sapiom/mcp@0.10.0

package/README.md

@@ -4,6 +4,8 @@ A local web app for building on Sapiom with your own coding agent.
 
 ```bash
 npx @sapiom/harness [dir]
+# also available via the Sapiom CLI (npm i -g @sapiom/cli @sapiom/harness):
+sapiom dev [dir]
 ```
 
 One command: checks your environment, signs you in, and opens a browser app
@@ -44,3 +46,37 @@ pnpm --filter @sapiom/harness build      # server (tsc) + SPA (vite) → dist/
 Architecture: a single Node process (Express + ws + node-pty) serves the built
 SPA, a small REST API, terminal WebSocket streams, and the local telemetry
 ingest endpoint. The interface contract lives in `src/shared/types.ts`.
+
+## Testing
+
+Three tiers — run whatever fits your change:
+
+**Unit tier** (vitest, no browser, no agent): covers server logic, adapters,
+analytics, and canvas rendering. Runs in CI on every PR.
+
+```bash
+pnpm --filter @sapiom/harness test
+```
+
+**Playwright mock tier** (chromium, Vite dev server with `VITE_MOCK=1`, no
+harness server or agent process). The full `web/e2e/` suite against the SPA in
+mock mode. Runs in CI on every PR. For a fast watch loop locally, use UI mode:
+
+```bash
+# One-time browser install (not included in pnpm install):
+pnpm --filter @sapiom/harness exec playwright install chromium
+
+# Watch/UI mode — re-runs affected specs on save:
+pnpm --filter @sapiom/harness exec playwright test \
+  --config web/e2e/playwright.config.ts --ui
+
+# Or run the full suite once (same command CI uses):
+pnpm --filter @sapiom/harness test:ui
+```
+
+**E2E live tier** (real agent binaries, real pty, no CI). Requires Claude Code
+or Codex installed and a valid `SAPIOM_API_KEY` in your environment.
+
+```bash
+pnpm --filter @sapiom/harness e2e:live
+```

package/dist/cli/bin.js

@@ -112,7 +112,8 @@ const main = async () => {
     if (identity?.source === "cached") {
         console.log(`\nSigned in as ${identity.organizationName} (cached credential).`);
     }
-    const telemetryOptIn = await ensureConsent({ noTelemetry: options.noTelemetry });
+    const consentResult = await ensureConsent({ noTelemetry: options.noTelemetry });
+    const { telemetryOptIn } = consentResult;
     // First run = no recent directories recorded before this boot. Must be read
     // BEFORE recordRecentDir below stamps the launch dir in — after that the
     // signal is gone for good. Drives the SPA's welcome panel (AppState.firstRun)
@@ -128,6 +129,8 @@ const main = async () => {
             port: options.port,
             bootToken,
             telemetryOptIn,
+            consentSource: consentResult.source,
+            consentEnvReason: consentResult.envReason,
             identity,
             machineId,
             launchDir: options.dir,
@@ -149,12 +152,33 @@ const main = async () => {
         port: server?.port ?? options.port,
         bootToken,
         identity,
-        telemetryOptIn,
+        telemetryOptIn: consentResult.telemetryOptIn,
         serverStarted: server !== null,
     });
     if (server && !options.noOpen) {
         await open(`http://localhost:${server.port}/?token=${bootToken}`);
     }
+    if (server) {
+        // Wire SIGINT (Ctrl+C) and SIGTERM so the awaitable close() path actually
+        // runs, which kills all live claude/codex ptys before the process exits.
+        // Without this, server.close() is never called from the CLI and the pty
+        // orphan problem the awaitable-kill feature was built to fix remains inert
+        // in the primary usage path.
+        // Guard against double-fire: once is enough; a second signal gets default
+        // handling (immediate termination) which is the correct behavior anyway.
+        let closing = false;
+        const handleSignal = (signal) => {
+            if (closing)
+                return;
+            closing = true;
+            // server.close() is already race-bounded to 5s internally.
+            void server.close().finally(() => {
+                process.exit(signal === "SIGINT" ? 130 : 143);
+            });
+        };
+        process.once("SIGINT", () => handleSignal("SIGINT"));
+        process.once("SIGTERM", () => handleSignal("SIGTERM"));
+    }
 };
 main().catch((err) => {
     console.error(err);

package/dist/cli/bin.js.map

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

package/dist/cli/consent.d.ts

@@ -2,6 +2,30 @@ export interface EnsureConsentOptions {
     /** The `--no-telemetry` flag — forces telemetry off without prompting. */
     noTelemetry: boolean;
 }
+/**
+ * How the telemetry consent state was determined for this boot.
+ * Exposed to the server so the UI can show a first-run notice when
+ * consent was implicitly set by the non-TTY default rather than explicitly
+ * answered by the user.
+ */
+export type ConsentSource = 
+/** `--no-telemetry` flag or SAPIOM_TELEMETRY_DISABLED/DO_NOT_TRACK env var. */
+"env-forced-off"
+/** Stored consent from a previous first-run prompt — user answered explicitly. */
+ | "stored-explicit"
+/** User answered the Y/n prompt just now (interactive TTY). */
+ | "prompted"
+/** Non-TTY first run: the silent default was applied and persisted. */
+ | "default-silent";
+export interface ConsentResult {
+    telemetryOptIn: boolean;
+    /**
+     * Which env var (if any) is forcing telemetry off this run.
+     * Only set when source === "env-forced-off".
+     */
+    envReason: string | null;
+    source: ConsentSource;
+}
 /**
  * Resolves the telemetry opt-in state. Prompts once on first run and persists
  * the answer; subsequent runs reuse the stored value silently. `--no-telemetry`
@@ -10,6 +34,10 @@ export interface EnsureConsentOptions {
  * skipping the prompt entirely — without touching what's actually stored, so
  * a later run without the env var set sees whatever the user answered (or
  * will still be asked, if this env-vetoed run was their first).
+ *
+ * Returns a ConsentResult that includes the source of the decision — the UI
+ * uses this to show a first-run notice when the user never explicitly answered
+ * (source === "default-silent"), skipping it when they did.
  */
-export declare function ensureConsent(options: EnsureConsentOptions): Promise<boolean>;
+export declare function ensureConsent(options: EnsureConsentOptions): Promise<ConsentResult>;
 //# sourceMappingURL=consent.d.ts.map

package/dist/cli/consent.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"consent.d.ts","sourceRoot":"","sources":["../../src/cli/consent.ts"],"names":[],"mappings":"AAqCA,MAAM,WAAW,oBAAoB;IACnC,0EAA0E;IAC1E,WAAW,EAAE,OAAO,CAAC;CACtB;AAuBD;;;;;;;;GAQG;AACH,wBAAsB,aAAa,CAAC,OAAO,EAAE,oBAAoB,GAAG,OAAO,CAAC,OAAO,CAAC,CAiBnF"}
+{"version":3,"file":"consent.d.ts","sourceRoot":"","sources":["../../src/cli/consent.ts"],"names":[],"mappings":"AAoDA,MAAM,WAAW,oBAAoB;IACnC,0EAA0E;IAC1E,WAAW,EAAE,OAAO,CAAC;CACtB;AAED;;;;;GAKG;AACH,MAAM,MAAM,aAAa;AACvB,+EAA+E;AAC7E,gBAAgB;AAClB,kFAAkF;GAChF,iBAAiB;AACnB,+DAA+D;GAC7D,UAAU;AACZ,uEAAuE;GACrE,gBAAgB,CAAC;AAErB,MAAM,WAAW,aAAa;IAC5B,cAAc,EAAE,OAAO,CAAC;IACxB;;;OAGG;IACH,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,MAAM,EAAE,aAAa,CAAC;CACvB;AAuBD;;;;;;;;;;;;GAYG;AACH,wBAAsB,aAAa,CAAC,OAAO,EAAE,oBAAoB,GAAG,OAAO,CAAC,aAAa,CAAC,CAwBzF"}

package/dist/cli/consent.js

@@ -1,11 +1,20 @@
 import * as readline from "node:readline/promises";
 import { hasStoredSettings, loadSettings, saveSettings } from "./settings.js";
-// Internal/friendlies phase: default to opted in (matches the on-by-default
-// prompt below and the non-TTY fallback) — flip this the other way for a
-// wider release.
+// Early-access phase: default to opted in (matches the on-by-default prompt
+// below and the non-TTY fallback) — intentional for the early-access phase;
+// flip for a wider release.
+//
+// Pre-wider-release checklist: revisit the non-TTY silent opt-in below.
+// The current default (true) is intentional for the early-access phase;
+// for a wider/public release the conservative choice is false (opt-out by
+// default) so users who never see a TTY (CI, Docker, headless environments)
+// are not silently opted in.
+// See also the first-run UI notice wiring in web/src/components/TelemetryNotice.tsx,
+// which surfaces this path to interactive users who did get the default.
 const DEFAULT_TELEMETRY_OPT_IN = true;
 const CONSENT_COPY = `
-Sapiom Harness collects local usage analytics to improve the product:
+Sapiom Harness collects usage analytics locally and, with telemetry on,
+sends them to Sapiom to improve the product:
   - the prompts you send and the tool calls your agent makes
   - session start/stop lifecycle events
 This is always written locally to ~/.sapiom/harness/events.ndjson for your
@@ -17,7 +26,11 @@ gear, or run with --no-telemetry).
 async function promptConsent() {
     console.log(`\n${CONSENT_COPY}\n`);
     if (!process.stdin.isTTY) {
-        console.log(`Non-interactive session — defaulting telemetry to ${DEFAULT_TELEMETRY_OPT_IN ? "on" : "off"}.\n`);
+        // The full consent copy (what's collected, local store, and opt-out path)
+        // was already printed above. Make the default explicit so non-TTY users
+        // reviewing logs see it clearly.
+        console.log(`Non-interactive session — telemetry is defaulting to ${DEFAULT_TELEMETRY_OPT_IN ? "on" : "off"}` +
+            ` per the notice above. Run with --no-telemetry or set SAPIOM_TELEMETRY_DISABLED=1 to opt out.\n`);
         return DEFAULT_TELEMETRY_OPT_IN;
     }
     const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
@@ -61,21 +74,30 @@ function envDisableReason() {
  * skipping the prompt entirely — without touching what's actually stored, so
  * a later run without the env var set sees whatever the user answered (or
  * will still be asked, if this env-vetoed run was their first).
+ *
+ * Returns a ConsentResult that includes the source of the decision — the UI
+ * uses this to show a first-run notice when the user never explicitly answered
+ * (source === "default-silent"), skipping it when they did.
  */
 export async function ensureConsent(options) {
-    if (options.noTelemetry)
-        return false;
+    if (options.noTelemetry) {
+        return { telemetryOptIn: false, envReason: null, source: "env-forced-off" };
+    }
     const envReason = envDisableReason();
     if (envReason) {
         console.log(`Telemetry disabled via ${envReason} — skipping the consent prompt.\n`);
-        return false;
+        return { telemetryOptIn: false, envReason, source: "env-forced-off" };
     }
     const isFirstRun = !(await hasStoredSettings());
     const settings = await loadSettings();
-    if (!isFirstRun)
-        return settings.telemetryOptIn;
+    if (!isFirstRun) {
+        return { telemetryOptIn: settings.telemetryOptIn, envReason: null, source: "stored-explicit" };
+    }
+    // First run: prompt the user (TTY) or apply the silent default (non-TTY).
+    const isTTY = process.stdin.isTTY;
     const telemetryOptIn = await promptConsent();
     await saveSettings({ ...settings, telemetryOptIn });
-    return telemetryOptIn;
+    const source = isTTY ? "prompted" : "default-silent";
+    return { telemetryOptIn, envReason: null, source };
 }
 //# sourceMappingURL=consent.js.map

package/dist/cli/consent.js.map

@@ -1 +1 @@
-{"version":3,"file":"consent.js","sourceRoot":"","sources":["../../src/cli/consent.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,QAAQ,MAAM,wBAAwB,CAAC;AACnD,OAAO,EAAE,iBAAiB,EAAE,YAAY,EAAE,YAAY,EAAE,MAAM,eAAe,CAAC;AAE9E,4EAA4E;AAC5E,yEAAyE;AACzE,iBAAiB;AACjB,MAAM,wBAAwB,GAAG,IAAI,CAAC;AAEtC,MAAM,YAAY,GAAG;;;;;;;;;CASpB,CAAC,IAAI,EAAE,CAAC;AAET,KAAK,UAAU,aAAa;IAC1B,OAAO,CAAC,GAAG,CAAC,KAAK,YAAY,IAAI,CAAC,CAAC;IAEnC,IAAI,CAAC,OAAO,CAAC,KAAK,CAAC,KAAK,EAAE,CAAC;QACzB,OAAO,CAAC,GAAG,CAAC,qDAAqD,wBAAwB,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,KAAK,KAAK,CAAC,CAAC;QAC/G,OAAO,wBAAwB,CAAC;IAClC,CAAC;IAED,MAAM,EAAE,GAAG,QAAQ,CAAC,eAAe,CAAC,EAAE,KAAK,EAAE,OAAO,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,CAAC,MAAM,EAAE,CAAC,CAAC;IACtF,IAAI,CAAC;QACH,MAAM,MAAM,GAAG,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,oBAAoB,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC;QAC9E,IAAI,MAAM,KAAK,EAAE;YAAE,OAAO,wBAAwB,CAAC;QACnD,OAAO,MAAM,KAAK,GAAG,IAAI,MAAM,KAAK,KAAK,CAAC;IAC5C,CAAC;YAAS,CAAC;QACT,EAAE,CAAC,KAAK,EAAE,CAAC;IACb,CAAC;AACH,CAAC;AAOD;;;;;;;GAOG;AACH,SAAS,YAAY,CAAC,KAAyB;IAC7C,IAAI,OAAO,KAAK,KAAK,QAAQ;QAAE,OAAO,KAAK,CAAC;IAC5C,MAAM,UAAU,GAAG,KAAK,CAAC,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC;IAC9C,OAAO,UAAU,KAAK,GAAG,IAAI,UAAU,KAAK,MAAM,CAAC;AACrD,CAAC;AAED,oFAAoF;AACpF,SAAS,gBAAgB;IACvB,IAAI,YAAY,CAAC,OAAO,CAAC,GAAG,CAAC,yBAAyB,CAAC;QAAE,OAAO,2BAA2B,CAAC;IAC5F,IAAI,YAAY,CAAC,OAAO,CAAC,GAAG,CAAC,YAAY,CAAC;QAAE,OAAO,cAAc,CAAC;IAClE,OAAO,IAAI,CAAC;AACd,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,CAAC,KAAK,UAAU,aAAa,CAAC,OAA6B;IAC/D,IAAI,OAAO,CAAC,WAAW;QAAE,OAAO,KAAK,CAAC;IAEtC,MAAM,SAAS,GAAG,gBAAgB,EAAE,CAAC;IACrC,IAAI,SAAS,EAAE,CAAC;QACd,OAAO,CAAC,GAAG,CAAC,0BAA0B,SAAS,mCAAmC,CAAC,CAAC;QACpF,OAAO,KAAK,CAAC;IACf,CAAC;IAED,MAAM,UAAU,GAAG,CAAC,CAAC,MAAM,iBAAiB,EAAE,CAAC,CAAC;IAChD,MAAM,QAAQ,GAAG,MAAM,YAAY,EAAE,CAAC;IAEtC,IAAI,CAAC,UAAU;QAAE,OAAO,QAAQ,CAAC,cAAc,CAAC;IAEhD,MAAM,cAAc,GAAG,MAAM,aAAa,EAAE,CAAC;IAC7C,MAAM,YAAY,CAAC,EAAE,GAAG,QAAQ,EAAE,cAAc,EAAE,CAAC,CAAC;IACpD,OAAO,cAAc,CAAC;AACxB,CAAC"}
+{"version":3,"file":"consent.js","sourceRoot":"","sources":["../../src/cli/consent.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,QAAQ,MAAM,wBAAwB,CAAC;AACnD,OAAO,EAAE,iBAAiB,EAAE,YAAY,EAAE,YAAY,EAAE,MAAM,eAAe,CAAC;AAE9E,4EAA4E;AAC5E,4EAA4E;AAC5E,4BAA4B;AAC5B,EAAE;AACF,wEAAwE;AACxE,wEAAwE;AACxE,0EAA0E;AAC1E,4EAA4E;AAC5E,6BAA6B;AAC7B,qFAAqF;AACrF,yEAAyE;AACzE,MAAM,wBAAwB,GAAG,IAAI,CAAC;AAEtC,MAAM,YAAY,GAAG;;;;;;;;;;CAUpB,CAAC,IAAI,EAAE,CAAC;AAET,KAAK,UAAU,aAAa;IAC1B,OAAO,CAAC,GAAG,CAAC,KAAK,YAAY,IAAI,CAAC,CAAC;IAEnC,IAAI,CAAC,OAAO,CAAC,KAAK,CAAC,KAAK,EAAE,CAAC;QACzB,0EAA0E;QAC1E,wEAAwE;QACxE,iCAAiC;QACjC,OAAO,CAAC,GAAG,CACT,wDAAwD,wBAAwB,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,KAAK,EAAE;YACjG,iGAAiG,CAClG,CAAC;QACF,OAAO,wBAAwB,CAAC;IAClC,CAAC;IAED,MAAM,EAAE,GAAG,QAAQ,CAAC,eAAe,CAAC,EAAE,KAAK,EAAE,OAAO,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,CAAC,MAAM,EAAE,CAAC,CAAC;IACtF,IAAI,CAAC;QACH,MAAM,MAAM,GAAG,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,oBAAoB,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC;QAC9E,IAAI,MAAM,KAAK,EAAE;YAAE,OAAO,wBAAwB,CAAC;QACnD,OAAO,MAAM,KAAK,GAAG,IAAI,MAAM,KAAK,KAAK,CAAC;IAC5C,CAAC;YAAS,CAAC;QACT,EAAE,CAAC,KAAK,EAAE,CAAC;IACb,CAAC;AACH,CAAC;AAiCD;;;;;;;GAOG;AACH,SAAS,YAAY,CAAC,KAAyB;IAC7C,IAAI,OAAO,KAAK,KAAK,QAAQ;QAAE,OAAO,KAAK,CAAC;IAC5C,MAAM,UAAU,GAAG,KAAK,CAAC,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC;IAC9C,OAAO,UAAU,KAAK,GAAG,IAAI,UAAU,KAAK,MAAM,CAAC;AACrD,CAAC;AAED,oFAAoF;AACpF,SAAS,gBAAgB;IACvB,IAAI,YAAY,CAAC,OAAO,CAAC,GAAG,CAAC,yBAAyB,CAAC;QAAE,OAAO,2BAA2B,CAAC;IAC5F,IAAI,YAAY,CAAC,OAAO,CAAC,GAAG,CAAC,YAAY,CAAC;QAAE,OAAO,cAAc,CAAC;IAClE,OAAO,IAAI,CAAC;AACd,CAAC;AAED;;;;;;;;;;;;GAYG;AACH,MAAM,CAAC,KAAK,UAAU,aAAa,CAAC,OAA6B;IAC/D,IAAI,OAAO,CAAC,WAAW,EAAE,CAAC;QACxB,OAAO,EAAE,cAAc,EAAE,KAAK,EAAE,SAAS,EAAE,IAAI,EAAE,MAAM,EAAE,gBAAgB,EAAE,CAAC;IAC9E,CAAC;IAED,MAAM,SAAS,GAAG,gBAAgB,EAAE,CAAC;IACrC,IAAI,SAAS,EAAE,CAAC;QACd,OAAO,CAAC,GAAG,CAAC,0BAA0B,SAAS,mCAAmC,CAAC,CAAC;QACpF,OAAO,EAAE,cAAc,EAAE,KAAK,EAAE,SAAS,EAAE,MAAM,EAAE,gBAAgB,EAAE,CAAC;IACxE,CAAC;IAED,MAAM,UAAU,GAAG,CAAC,CAAC,MAAM,iBAAiB,EAAE,CAAC,CAAC;IAChD,MAAM,QAAQ,GAAG,MAAM,YAAY,EAAE,CAAC;IAEtC,IAAI,CAAC,UAAU,EAAE,CAAC;QAChB,OAAO,EAAE,cAAc,EAAE,QAAQ,CAAC,cAAc,EAAE,SAAS,EAAE,IAAI,EAAE,MAAM,EAAE,iBAAiB,EAAE,CAAC;IACjG,CAAC;IAED,0EAA0E;IAC1E,MAAM,KAAK,GAAG,OAAO,CAAC,KAAK,CAAC,KAAK,CAAC;IAClC,MAAM,cAAc,GAAG,MAAM,aAAa,EAAE,CAAC;IAC7C,MAAM,YAAY,CAAC,EAAE,GAAG,QAAQ,EAAE,cAAc,EAAE,CAAC,CAAC;IACpD,MAAM,MAAM,GAAkB,KAAK,CAAC,CAAC,CAAC,UAAU,CAAC,CAAC,CAAC,gBAAgB,CAAC;IACpE,OAAO,EAAE,cAAc,EAAE,SAAS,EAAE,IAAI,EAAE,MAAM,EAAE,CAAC;AACrD,CAAC"}

package/dist/core/adapters/adapter.d.ts

@@ -0,0 +1,72 @@
+/**
+ * HarnessAdapter union type — the shape every adapter (embedded or external)
+ * must satisfy.
+ *
+ * "embedded" adapters are spawned inside a pty session by the harness.
+ * "external" adapters run in their own companion app and have no spawn path —
+ * the type makes calling spawn/send on them a compile error, not just a
+ * convention.
+ *
+ * Adding an external harness = one descriptor file + one HARNESS_ADAPTER_INFOS
+ * line. An embedded harness that can be spawned as a session additionally
+ * requires: a runtime adapter (launch/resume/doctor/listPastSessions) in
+ * core/adapters/, a new id in SPAWNABLE_HARNESS_KINDS (shared/types.ts —
+ * which widens HarnessKind and the z.enum gate automatically), and a real
+ * e2e suite confirming the lifecycle works end-to-end.
+ */
+/** Stable identifier for every harness the registry knows about. */
+export type HarnessAdapterId = "claude-code" | "codex" | "pi" | "opencode" | "conductor";
+/** Whether the harness is spawned by the harness (embedded) or managed by its
+ *  own companion app (external). */
+export type HarnessAdapterMode = "embedded" | "external";
+/** Fields shared by every adapter regardless of mode. */
+export interface HarnessAdapterBase {
+    /** Stable identifier used in APIs and the session registry. */
+    id: HarnessAdapterId;
+    /** Human-readable name for pickers and logs. */
+    label: string;
+    /** Spawn mode — narrow on this before calling any spawn-path methods. */
+    mode: HarnessAdapterMode;
+    /**
+     * Per-agent prompt text guiding the user through installing and
+     * configuring the Sapiom MCP server (`@sapiom/mcp`) for this harness.
+     * Consumed by the skills-panel Install MCP modal. Returns the text string
+     * directly — callers may render it as preformatted text.
+     */
+    installMcpPrompt(): string;
+    /**
+     * Best-effort detection of whether the harness is installed on this
+     * machine. Never throws.
+     */
+    detectInstalled(): Promise<boolean>;
+    /**
+     * Marks adapters whose launch behavior is best-effort and not yet
+     * hardened by an end-to-end suite. Absent (or false) for fully
+     * supported harnesses.
+     */
+    experimental?: boolean;
+}
+/**
+ * An adapter the harness spawns inside a pty session.
+ * The existing `HarnessAdapter` interface (shared/types.ts) carries the actual
+ * launch/resume/doctor/listPastSessions contract consumed by SessionManager;
+ * this is the registry-level description used for enumeration and the
+ * harnesses listing endpoint.
+ */
+export interface EmbeddedHarnessAdapterInfo extends HarnessAdapterBase {
+    mode: "embedded";
+}
+/**
+ * An adapter for a harness that runs in its own companion app.
+ * There is deliberately no spawn path — `launchCommand` is absent so a
+ * spawn attempt is a compile error rather than a runtime surprise.
+ */
+export interface ExternalHarnessAdapterInfo extends HarnessAdapterBase {
+    mode: "external";
+}
+/**
+ * Every registry entry satisfies this union. Narrow on `mode` before
+ * attempting any spawn-path operation — external adapters have none.
+ */
+export type HarnessAdapterInfo = EmbeddedHarnessAdapterInfo | ExternalHarnessAdapterInfo;
+//# sourceMappingURL=adapter.d.ts.map

package/dist/core/adapters/adapter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"adapter.d.ts","sourceRoot":"","sources":["../../../src/core/adapters/adapter.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,oEAAoE;AACpE,MAAM,MAAM,gBAAgB,GACxB,aAAa,GACb,OAAO,GACP,IAAI,GACJ,UAAU,GACV,WAAW,CAAC;AAEhB;oCACoC;AACpC,MAAM,MAAM,kBAAkB,GAAG,UAAU,GAAG,UAAU,CAAC;AAEzD,yDAAyD;AACzD,MAAM,WAAW,kBAAkB;IACjC,+DAA+D;IAC/D,EAAE,EAAE,gBAAgB,CAAC;IACrB,gDAAgD;IAChD,KAAK,EAAE,MAAM,CAAC;IACd,yEAAyE;IACzE,IAAI,EAAE,kBAAkB,CAAC;IACzB;;;;;OAKG;IACH,gBAAgB,IAAI,MAAM,CAAC;IAC3B;;;OAGG;IACH,eAAe,IAAI,OAAO,CAAC,OAAO,CAAC,CAAC;IACpC;;;;OAIG;IACH,YAAY,CAAC,EAAE,OAAO,CAAC;CACxB;AAED;;;;;;GAMG;AACH,MAAM,WAAW,0BAA2B,SAAQ,kBAAkB;IACpE,IAAI,EAAE,UAAU,CAAC;CAClB;AAED;;;;GAIG;AACH,MAAM,WAAW,0BAA2B,SAAQ,kBAAkB;IACpE,IAAI,EAAE,UAAU,CAAC;CAClB;AAED;;;GAGG;AACH,MAAM,MAAM,kBAAkB,GAAG,0BAA0B,GAAG,0BAA0B,CAAC"}

package/dist/core/adapters/adapter.js

@@ -0,0 +1,18 @@
+/**
+ * HarnessAdapter union type — the shape every adapter (embedded or external)
+ * must satisfy.
+ *
+ * "embedded" adapters are spawned inside a pty session by the harness.
+ * "external" adapters run in their own companion app and have no spawn path —
+ * the type makes calling spawn/send on them a compile error, not just a
+ * convention.
+ *
+ * Adding an external harness = one descriptor file + one HARNESS_ADAPTER_INFOS
+ * line. An embedded harness that can be spawned as a session additionally
+ * requires: a runtime adapter (launch/resume/doctor/listPastSessions) in
+ * core/adapters/, a new id in SPAWNABLE_HARNESS_KINDS (shared/types.ts —
+ * which widens HarnessKind and the z.enum gate automatically), and a real
+ * e2e suite confirming the lifecycle works end-to-end.
+ */
+export {};
+//# sourceMappingURL=adapter.js.map

package/dist/core/adapters/adapter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"adapter.js","sourceRoot":"","sources":["../../../src/core/adapters/adapter.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG"}

package/dist/core/adapters/claude-code-info.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Registry descriptor for the Claude Code adapter.
+ *
+ * The runtime adapter implementation (launch/resume/doctor/listPastSessions)
+ * lives in claude-code.ts. This file carries only the registry-level metadata
+ * consumed by the harness listing endpoint and the skills panel Install MCP
+ * modal: the human label, spawn mode, MCP install guidance, and PATH detection.
+ */
+import type { EmbeddedHarnessAdapterInfo } from "./adapter.js";
+export declare const claudeCodeAdapterInfo: EmbeddedHarnessAdapterInfo;
+//# sourceMappingURL=claude-code-info.d.ts.map

package/dist/core/adapters/claude-code-info.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"claude-code-info.d.ts","sourceRoot":"","sources":["../../../src/core/adapters/claude-code-info.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,OAAO,KAAK,EAAE,0BAA0B,EAAE,MAAM,cAAc,CAAC;AAkB/D,eAAO,MAAM,qBAAqB,EAAE,0BAUnC,CAAC"}

package/dist/core/adapters/claude-code-info.js

@@ -0,0 +1,27 @@
+import { isExecutableOnPath } from "./detect.js";
+const INSTALL_MCP_PROMPT = [
+    "Set up the Sapiom MCP server for Claude Code.",
+    "",
+    "1. Register it under the server name `sapiom-dev`:",
+    "",
+    "   claude mcp add sapiom-dev -- npx -y @sapiom/mcp",
+    "",
+    "   The `@sapiom/mcp` npm package ships the `sapiom-mcp` binary, a local",
+    "   MCP server that speaks stdio — no global install or daemon needed.",
+    "2. Verify the registration: `claude mcp list` should show `sapiom-dev`.",
+    "3. Restart Claude Code (or start a new session) so the server is loaded.",
+    "4. Networked Sapiom tools need an API key: run the `sapiom_authenticate`",
+    "   tool once and complete the browser login it opens.",
+].join("\n");
+export const claudeCodeAdapterInfo = {
+    id: "claude-code",
+    label: "Claude Code",
+    mode: "embedded",
+    installMcpPrompt() {
+        return INSTALL_MCP_PROMPT;
+    },
+    detectInstalled() {
+        return isExecutableOnPath("claude");
+    },
+};
+//# sourceMappingURL=claude-code-info.js.map

package/dist/core/adapters/claude-code-info.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"claude-code-info.js","sourceRoot":"","sources":["../../../src/core/adapters/claude-code-info.ts"],"names":[],"mappings":"AASA,OAAO,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAC;AAEjD,MAAM,kBAAkB,GAAG;IACzB,+CAA+C;IAC/C,EAAE;IACF,oDAAoD;IACpD,EAAE;IACF,oDAAoD;IACpD,EAAE;IACF,yEAAyE;IACzE,uEAAuE;IACvE,yEAAyE;IACzE,0EAA0E;IAC1E,0EAA0E;IAC1E,uDAAuD;CACxD,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AAEb,MAAM,CAAC,MAAM,qBAAqB,GAA+B;IAC/D,EAAE,EAAE,aAAa;IACjB,KAAK,EAAE,aAAa;IACpB,IAAI,EAAE,UAAU;IAChB,gBAAgB;QACd,OAAO,kBAAkB,CAAC;IAC5B,CAAC;IACD,eAAe;QACb,OAAO,kBAAkB,CAAC,QAAQ,CAAC,CAAC;IACtC,CAAC;CACF,CAAC"}

package/dist/core/adapters/claude-code.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"claude-code.d.ts","sourceRoot":"","sources":["../../../src/core/adapters/claude-code.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AASH,OAAO,KAAK,EACV,WAAW,EACX,cAAc,EACd,UAAU,EACV,cAAc,EACd,SAAS,EACV,MAAM,uBAAuB,CAAC;AAQ/B,MAAM,WAAW,wBAAwB;IACvC,wFAAwF;IACxF,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,kEAAkE;IAClE,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAuGD,qBAAa,iBAAkB,YAAW,cAAc;IACtD,QAAQ,CAAC,EAAE,EAAG,aAAa,CAAU;IACrC,QAAQ,CAAC,WAAW,EAAG,OAAO,CAAU;IACxC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAS;IAChC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAS;gBAErB,OAAO,GAAE,wBAA6B;IAK5C,MAAM,IAAI,OAAO,CAAC,WAAW,EAAE,CAAC;IAetC,MAAM,CAAC,IAAI,EAAE,UAAU,GAAG,SAAS;IAgBnC,MAAM,CAAC,cAAc,EAAE,MAAM,EAAE,IAAI,EAAE,UAAU,GAAG,SAAS;IAa3D;;;;;;;;;;;;;OAaG;IACH,UAAU,CAAC,IAAI,EAAE,UAAU,GAAG,SAAS;IAmBjC,gBAAgB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,cAAc,EAAE,CAAC;CA8B/D;AAcD,wBAAgB,uBAAuB,CAAC,OAAO,CAAC,EAAE,wBAAwB,GAAG,cAAc,CAE1F"}
+{"version":3,"file":"claude-code.d.ts","sourceRoot":"","sources":["../../../src/core/adapters/claude-code.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AASH,OAAO,KAAK,EACV,WAAW,EACX,cAAc,EACd,UAAU,EACV,cAAc,EACd,SAAS,EACV,MAAM,uBAAuB,CAAC;AAiB/B,MAAM,WAAW,wBAAwB;IACvC,wFAAwF;IACxF,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,kEAAkE;IAClE,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AA8FD,qBAAa,iBAAkB,YAAW,cAAc;IACtD,QAAQ,CAAC,EAAE,EAAG,aAAa,CAAU;IACrC,QAAQ,CAAC,WAAW,EAAG,OAAO,CAAU;IACxC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAS;IAChC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAS;gBAErB,OAAO,GAAE,wBAA6B;IAK5C,MAAM,IAAI,OAAO,CAAC,WAAW,EAAE,CAAC;IAetC,MAAM,CAAC,IAAI,EAAE,UAAU,GAAG,SAAS;IAgBnC,MAAM,CAAC,cAAc,EAAE,MAAM,EAAE,IAAI,EAAE,UAAU,GAAG,SAAS;IAa3D;;;;;;;;;;;;;OAaG;IACH,UAAU,CAAC,IAAI,EAAE,UAAU,GAAG,SAAS;IAmBjC,gBAAgB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,cAAc,EAAE,CAAC;CA8B/D;AAcD,wBAAgB,uBAAuB,CAAC,OAAO,CAAC,EAAE,wBAAwB,GAAG,cAAc,CAE1F"}

package/dist/core/adapters/claude-code.js

@@ -10,20 +10,19 @@ import { readFile, readdir, stat, open } from "node:fs/promises";
 import { homedir } from "node:os";
 import { basename, join } from "node:path";
 import { promisify } from "node:util";
-const execFileAsync = promisify(execFile);
-/** Bytes read from the tail of a transcript file. Files can be 100MB+; the
- * summary/title we need is always near the end. */
-const TRANSCRIPT_TAIL_BYTES = 65536;
 /**
- * Claude Code stores transcripts at `~/.claude/projects/<encoded-cwd>/*.jsonl`.
- * The encoding strips the leading `/` and replaces `/` and `.` with `-`.
- * If Claude Code changes this scheme, discovery silently returns no history
- * (listPastSessions degrades to an empty list, not an error).
+ * Maps a project cwd to the directory name Claude Code uses for its transcript
+ * store under `~/.claude/projects/`. Claude Code applies this encoding before
+ * creating the directory — see its own source for the canonical definition.
  */
 function encodeProjectPath(cwd) {
     const normalized = cwd.replace(/\\/g, "/");
     return normalized.replace(/:/g, "").replace(/[/.]/g, "-");
 }
+const execFileAsync = promisify(execFile);
+/** Bytes read from the tail of a transcript file. Files can be 100MB+; the
+ * summary/title we need is always near the end. */
+const TRANSCRIPT_TAIL_BYTES = 65536;
 function extractTextFromContent(content) {
     if (typeof content === "string")
         return content;
@@ -105,6 +104,8 @@ function buildConfigArgs(opts) {
         args.push("--settings", opts.settingsFile);
     if (opts.mcpConfigFile)
         args.push("--mcp-config", opts.mcpConfigFile);
+    if (opts.pluginDir)
+        args.push("--plugin-dir", opts.pluginDir);
     return args;
 }
 export class ClaudeCodeAdapter {