agenthub-multiagent-mcp 1.51.0 → 1.53.0

package/dist/sessionCapture.js

@@ -0,0 +1,279 @@
+/**
+ * Session-capture wiring for daemon shifts (add-multiplayer-sessions §1.5).
+ *
+ * The capture hook (`session-capture.sh`) has always existed but has never
+ * produced anything for the live fleet, because two halves were missing:
+ *
+ *  1. Nothing created a coding session, so `AGENTHUB_SESSION_ID` was never set
+ *     and the hook exited at its first guard (`session-capture.sh:14`).
+ *  2. Nothing registered the hook for the spawned Claude process — the MCP
+ *     installers cover only the inbox and activity hooks.
+ *
+ * This module supplies both, and is the single place the daemon touches for
+ * capture concerns. Everything here is **fail-soft**: a capture failure logs and
+ * returns a null/empty result so the shift still runs. A shift must never die
+ * for an observability reason.
+ *
+ * Gated on `AGENTHUB_SESSION_STREAMING_ENABLED` (default off, matching the
+ * server-side flag added in §1.2). With the flag off, `beginShiftCapture`
+ * performs no network call, no filesystem access, and returns `null`, and
+ * `applyCaptureEnv` leaves the child env untouched — the shift is byte-for-byte
+ * what it is today.
+ */
+import * as fs from "fs";
+import * as path from "path";
+/** Default bound on every capture HTTP call. Shift startup must not block on it. */
+export const CAPTURE_TIMEOUT_MS = 5000;
+/**
+ * Identifies our PostToolUse entry inside a settings object so repeated merges
+ * never duplicate it (same marker discipline as activityHookInstall.ts /
+ * inboxHookInstall.ts, which key off the CLI filename in the command string).
+ */
+export const CAPTURE_HOOK_MARKER = "session-capture.sh";
+/**
+ * Live session streaming kill switch. Default **off** — an unset, empty, or
+ * unrecognised value means disabled, so the producer stays silent unless an
+ * operator deliberately turns it on.
+ */
+export function sessionStreamingEnabled(env = process.env) {
+    return /^(1|true|yes|on)$/i.test((env.AGENTHUB_SESSION_STREAMING_ENABLED || "").trim());
+}
+/**
+ * Merge the capture PostToolUse hook into a settings object **without**
+ * discarding anything already there: other hook events, other PostToolUse
+ * entries, and every non-`hooks` key are preserved. Idempotent — a settings
+ * object that already carries the capture hook is returned unchanged.
+ *
+ * Returns a new object; the input is never mutated.
+ */
+export function mergeCaptureHook(base, command, timeoutSeconds = 3) {
+    const merged = { ...base };
+    const hooks = { ...(base.hooks ?? {}) };
+    const postToolUse = Array.isArray(hooks.PostToolUse) ? [...hooks.PostToolUse] : [];
+    const alreadyPresent = postToolUse.some((entry) => (entry?.hooks ?? []).some((h) => typeof h?.command === "string" && h.command.includes(CAPTURE_HOOK_MARKER)));
+    if (!alreadyPresent) {
+        postToolUse.push({
+            matcher: "",
+            hooks: [{ type: "command", command, timeout: timeoutSeconds }],
+        });
+    }
+    hooks.PostToolUse = postToolUse;
+    merged.hooks = hooks;
+    return merged;
+}
+/**
+ * Locate `session-capture.sh` relative to the compiled module directory.
+ * Ordered most-specific first:
+ *   1. `dist/session-capture.sh`      — the published npm package (build copies it)
+ *   2. `mcp-server/session-capture.sh` — running from a source checkout's dist/
+ *   3. `<repo>/.claude/hooks/session-capture.sh` — repo checkout fallback
+ * Returns `null` when the script cannot be found; the caller then runs the shift
+ * without capture rather than inventing a degraded inline copy.
+ */
+export function resolveCaptureHookScript(moduleDir, exists = fs.existsSync) {
+    const candidates = [
+        path.join(moduleDir, "session-capture.sh"),
+        path.join(moduleDir, "..", "session-capture.sh"),
+        path.join(moduleDir, "..", "..", ".claude", "hooks", "session-capture.sh"),
+    ];
+    for (const candidate of candidates) {
+        if (exists(candidate))
+            return candidate.replace(/\\/g, "/");
+    }
+    return null;
+}
+/** Shell command Claude Code runs for the PostToolUse capture hook. */
+export function captureHookCommand(scriptPath) {
+    return `bash "${scriptPath}"`;
+}
+/**
+ * Build a memoised factory that materialises the per-daemon-process settings
+ * file registering the capture hook, and returns its path ("" when the hook
+ * script is unavailable or the write fails).
+ *
+ * **Why a dedicated file rather than editing `~/.claude/settings.json`:** the
+ * daemon already passes a settings file to `run-claude.sh` (arg 4 → `claude
+ * --settings`). Writing a fresh file scoped to the spawned process means no
+ * user-owned or workspace-owned settings file is ever rewritten, so there is
+ * nothing to clobber — a strictly stronger guarantee than merging in place. The
+ * file contains only our hook, so hook entries from the user's own settings
+ * sources are neither dropped nor double-registered. `mergeCaptureHook` is used
+ * (rather than a literal) so the same non-destructive merge is exercised here
+ * and reusable by the in-place installer Phase 3 will need for human sessions.
+ */
+export function createCaptureSettingsFactory(moduleDir, settingsPath, deps = {}) {
+    const exists = deps.exists ?? fs.existsSync;
+    const writeFile = deps.writeFile ?? ((p, data) => fs.writeFileSync(p, data));
+    const log = deps.log ?? (() => { });
+    let cached = null;
+    return function ensureCaptureSettingsFile() {
+        if (cached !== null)
+            return cached;
+        const script = resolveCaptureHookScript(moduleDir, exists);
+        if (!script) {
+            log("session capture: session-capture.sh not found next to the daemon build — " +
+                "shift runs without the capture hook");
+            cached = "";
+            return cached;
+        }
+        try {
+            const settings = mergeCaptureHook({}, captureHookCommand(script));
+            writeFile(settingsPath, JSON.stringify(settings, null, 2));
+            cached = settingsPath.replace(/\\/g, "/");
+        }
+        catch (e) {
+            log(`session capture: could not write settings file — ${errText(e)}`);
+            cached = "";
+        }
+        return cached;
+    };
+}
+/**
+ * Create the coding session that a shift will be captured under.
+ *
+ * Uses `POST /api/sessions` (`handleCreateSession`) — the plain record-creating
+ * endpoint. Deliberately **not** `POST /api/sessions/start`: that one also calls
+ * `Orchestrator().DispatchSession`, i.e. it asks a daemon to start a shift. The
+ * daemon calling it would dispatch a second shift for work it is already doing.
+ *
+ * Never throws and never blocks beyond `timeoutMs`. Returns the session id, or
+ * `null` when the session could not be created — the caller then runs the shift
+ * uncaptured.
+ */
+export async function openCaptureSession(opts) {
+    const log = opts.log ?? (() => { });
+    const body = { agent_id: opts.agentId };
+    if (opts.title)
+        body.title = opts.title.slice(0, 200);
+    if (opts.workingDirectory)
+        body.working_directory = opts.workingDirectory;
+    if (opts.projectId)
+        body.project_id = opts.projectId;
+    const parsed = await captureRequest(opts, "POST", "/api/sessions", body, "create");
+    if (parsed === null)
+        return null;
+    const id = parsed?.id;
+    if (typeof id !== "string" || id === "") {
+        log("session capture: create returned no session id — shift runs without capture");
+        return null;
+    }
+    return id;
+}
+/**
+ * Close a captured session. Uses `POST /api/sessions/{id}/terminate`, the only
+ * endpoint that moves a session to a terminal state and stamps a reason.
+ * Never throws — a shift that already finished must not fail on cleanup.
+ */
+export async function closeCaptureSession(sessionId, reason, opts) {
+    const parsed = await captureRequest(opts, "POST", `/api/sessions/${encodeURIComponent(sessionId)}/terminate`, { termination_reason: reason }, "terminate");
+    return parsed !== null;
+}
+/**
+ * Remove the hook's per-session scratch markers.
+ *
+ * `session-capture.sh` keys both of its markers by `AGENTHUB_SESSION_ID`
+ * (`/tmp/agenthub-transcript-offset-<id>`, `/tmp/agenthub-claude-sid-<id>`), so
+ * concurrent shifts on one host never collide — each shift gets its own session
+ * id. They are, however, never cleaned up by the script itself, so the daemon
+ * removes them when the session closes. Best-effort: absent files are fine.
+ */
+export function cleanupCaptureMarkers(sessionId, tmpDir = "/tmp", removeFile = fs.unlinkSync) {
+    for (const name of [`agenthub-transcript-offset-${sessionId}`, `agenthub-claude-sid-${sessionId}`]) {
+        try {
+            removeFile(path.join(tmpDir, name));
+        }
+        catch {
+            /* never existed, or already gone */
+        }
+    }
+}
+/**
+ * Open a session and register the capture hook for one shift.
+ *
+ * Returns `null` — meaning "run the shift uncaptured" — when streaming is
+ * disabled or the session could not be created. With streaming disabled this
+ * returns before any I/O of any kind.
+ */
+export async function beginShiftCapture(opts) {
+    if (!sessionStreamingEnabled(opts.env ?? process.env))
+        return null;
+    const sessionId = await openCaptureSession(opts);
+    if (!sessionId)
+        return null;
+    return { sessionId, settingsFile: opts.ensureSettingsFile() };
+}
+/** Close a shift's session and clean up its hook markers. Never throws. */
+export async function endShiftCapture(capture, outcome, opts) {
+    if (!capture)
+        return;
+    await closeCaptureSession(capture.sessionId, outcome, opts);
+    cleanupCaptureMarkers(capture.sessionId, opts.tmpDir ?? "/tmp");
+}
+/**
+ * Stamp the capture variables onto a shift's child environment.
+ *
+ * `AGENTHUB_SESSION_ID` is what un-gates `session-capture.sh`; the URL and key
+ * are re-asserted because the hook reads them from its own environment and
+ * would otherwise silently fall back to the compiled-in default host.
+ *
+ * With `capture === null` the env object is returned untouched — this is the
+ * off-path guarantee, expressed as a single early return.
+ */
+export function applyCaptureEnv(env, capture, apiUrl, apiKey) {
+    if (!capture)
+        return env;
+    env.AGENTHUB_SESSION_ID = capture.sessionId;
+    env.AGENTHUB_URL = apiUrl;
+    env.AGENTHUB_API_KEY = apiKey;
+    return env;
+}
+// ---------------------------------------------------------------------------
+// internals
+// ---------------------------------------------------------------------------
+function errText(e) {
+    return e instanceof Error ? e.message : String(e);
+}
+function trimTrailingSlash(url) {
+    return url.replace(/\/+$/, "");
+}
+/**
+ * One bounded, never-throwing JSON request. Returns the parsed body on success
+ * (`{}` when the body is not JSON) or `null` on any failure, so every caller
+ * has exactly one degradation path.
+ */
+async function captureRequest(opts, method, route, body, label) {
+    const log = opts.log ?? (() => { });
+    const doFetch = opts.fetchImpl ?? globalThis.fetch;
+    if (!doFetch) {
+        log(`session capture: ${label} skipped — no fetch implementation available`);
+        return null;
+    }
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), opts.timeoutMs ?? CAPTURE_TIMEOUT_MS);
+    try {
+        const res = await doFetch(`${trimTrailingSlash(opts.apiUrl)}${route}`, {
+            method,
+            headers: { "Content-Type": "application/json", "X-API-Key": opts.apiKey },
+            body: JSON.stringify(body),
+            signal: controller.signal,
+        });
+        if (!res.ok) {
+            log(`session capture: ${label} failed (HTTP ${res.status}) — continuing without capture`);
+            return null;
+        }
+        try {
+            return (await res.json()) ?? {};
+        }
+        catch {
+            return {};
+        }
+    }
+    catch (e) {
+        log(`session capture: ${label} failed (${errText(e)}) — continuing without capture`);
+        return null;
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+//# sourceMappingURL=sessionCapture.js.map

package/dist/sessionCapture.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sessionCapture.js","sourceRoot":"","sources":["../src/sessionCapture.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAEH,OAAO,KAAK,EAAE,MAAM,IAAI,CAAC;AACzB,OAAO,KAAK,IAAI,MAAM,MAAM,CAAC;AAU7B,oFAAoF;AACpF,MAAM,CAAC,MAAM,kBAAkB,GAAG,IAAI,CAAC;AAEvC;;;;GAIG;AACH,MAAM,CAAC,MAAM,mBAAmB,GAAG,oBAAoB,CAAC;AAexD;;;;GAIG;AACH,MAAM,UAAU,uBAAuB,CAAC,MAAyB,OAAO,CAAC,GAAG;IAC1E,OAAO,oBAAoB,CAAC,IAAI,CAAC,CAAC,GAAG,CAAC,kCAAkC,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC;AAC1F,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,gBAAgB,CAC9B,IAA6B,EAC7B,OAAe,EACf,cAAc,GAAG,CAAC;IAElB,MAAM,MAAM,GAA4B,EAAE,GAAG,IAAI,EAAE,CAAC;IACpD,MAAM,KAAK,GAAgC,EAAE,GAAI,CAAC,IAAI,CAAC,KAAK,IAAI,EAAE,CAAiC,EAAE,CAAC;IACtG,MAAM,WAAW,GAAG,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,KAAK,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;IAEnF,MAAM,cAAc,GAAG,WAAW,CAAC,IAAI,CAAC,CAAC,KAAK,EAAE,EAAE,CAChD,CAAC,KAAK,EAAE,KAAK,IAAI,EAAE,CAAC,CAAC,IAAI,CACvB,CAAC,CAAC,EAAE,EAAE,CAAC,OAAO,CAAC,EAAE,OAAO,KAAK,QAAQ,IAAI,CAAC,CAAC,OAAO,CAAC,QAAQ,CAAC,mBAAmB,CAAC,CACjF,CACF,CAAC;IACF,IAAI,CAAC,cAAc,EAAE,CAAC;QACpB,WAAW,CAAC,IAAI,CAAC;YACf,OAAO,EAAE,EAAE;YACX,KAAK,EAAE,CAAC,EAAE,IAAI,EAAE,SAAS,EAAE,OAAO,EAAE,OAAO,EAAE,cAAc,EAAE,CAAC;SAC/D,CAAC,CAAC;IACL,CAAC;IAED,KAAK,CAAC,WAAW,GAAG,WAAW,CAAC;IAChC,MAAM,CAAC,KAAK,GAAG,KAAK,CAAC;IACrB,OAAO,MAAM,CAAC;AAChB,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,wBAAwB,CACtC,SAAiB,EACjB,SAAiC,EAAE,CAAC,UAAU;IAE9C,MAAM,UAAU,GAAG;QACjB,IAAI,CAAC,IAAI,CAAC,SAAS,EAAE,oBAAoB,CAAC;QAC1C,IAAI,CAAC,IAAI,CAAC,SAAS,EAAE,IAAI,EAAE,oBAAoB,CAAC;QAChD,IAAI,CAAC,IAAI,CAAC,SAAS,EAAE,IAAI,EAAE,IAAI,EAAE,SAAS,EAAE,OAAO,EAAE,oBAAoB,CAAC;KAC3E,CAAC;IACF,KAAK,MAAM,SAAS,IAAI,UAAU,EAAE,CAAC;QACnC,IAAI,MAAM,CAAC,SAAS,CAAC;YAAE,OAAO,SAAS,CAAC,OAAO,CAAC,KAAK,EAAE,GAAG,CAAC,CAAC;IAC9D,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC;AAED,uEAAuE;AACvE,MAAM,UAAU,kBAAkB,CAAC,UAAkB;IACnD,OAAO,SAAS,UAAU,GAAG,CAAC;AAChC,CAAC;AAQD;;;;;;;;;;;;;;GAcG;AACH,MAAM,UAAU,4BAA4B,CAC1C,SAAiB,EACjB,YAAoB,EACpB,OAA4B,EAAE;IAE9B,MAAM,MAAM,GAAG,IAAI,CAAC,MAAM,IAAI,EAAE,CAAC,UAAU,CAAC;IAC5C,MAAM,SAAS,GAAG,IAAI,CAAC,SAAS,IAAI,CAAC,CAAC,CAAS,EAAE,IAAY,EAAE,EAAE,CAAC,EAAE,CAAC,aAAa,CAAC,CAAC,EAAE,IAAI,CAAC,CAAC,CAAC;IAC7F,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,IAAI,CAAC,GAAG,EAAE,GAAE,CAAC,CAAC,CAAC;IAEnC,IAAI,MAAM,GAAkB,IAAI,CAAC;IACjC,OAAO,SAAS,yBAAyB;QACvC,IAAI,MAAM,KAAK,IAAI;YAAE,OAAO,MAAM,CAAC;QAEnC,MAAM,MAAM,GAAG,wBAAwB,CAAC,SAAS,EAAE,MAAM,CAAC,CAAC;QAC3D,IAAI,CAAC,MAAM,EAAE,CAAC;YACZ,GAAG,CACD,2EAA2E;gBACzE,qCAAqC,CACxC,CAAC;YACF,MAAM,GAAG,EAAE,CAAC;YACZ,OAAO,MAAM,CAAC;QAChB,CAAC;QAED,IAAI,CAAC;YACH,MAAM,QAAQ,GAAG,gBAAgB,CAAC,EAAE,EAAE,kBAAkB,CAAC,MAAM,CAAC,CAAC,CAAC;YAClE,SAAS,CAAC,YAAY,EAAE,IAAI,CAAC,SAAS,CAAC,QAAQ,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC,CAAC;YAC3D,MAAM,GAAG,YAAY,CAAC,OAAO,CAAC,KAAK,EAAE,GAAG,CAAC,CAAC;QAC5C,CAAC;QAAC,OAAO,CAAC,EAAE,CAAC;YACX,GAAG,CAAC,oDAAoD,OAAO,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC;YACtE,MAAM,GAAG,EAAE,CAAC;QACd,CAAC;QACD,OAAO,MAAM,CAAC;IAChB,CAAC,CAAC;AACJ,CAAC;AAiBD;;;;;;;;;;;GAWG;AACH,MAAM,CAAC,KAAK,UAAU,kBAAkB,CAAC,IAAwB;IAC/D,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,IAAI,CAAC,GAAG,EAAE,GAAE,CAAC,CAAC,CAAC;IACnC,MAAM,IAAI,GAA2B,EAAE,QAAQ,EAAE,IAAI,CAAC,OAAO,EAAE,CAAC;IAChE,IAAI,IAAI,CAAC,KAAK;QAAE,IAAI,CAAC,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC;IACtD,IAAI,IAAI,CAAC,gBAAgB;QAAE,IAAI,CAAC,iBAAiB,GAAG,IAAI,CAAC,gBAAgB,CAAC;IAC1E,IAAI,IAAI,CAAC,SAAS;QAAE,IAAI,CAAC,UAAU,GAAG,IAAI,CAAC,SAAS,CAAC;IAErD,MAAM,MAAM,GAAG,MAAM,cAAc,CAAC,IAAI,EAAE,MAAM,EAAE,eAAe,EAAE,IAAI,EAAE,QAAQ,CAAC,CAAC;IACnF,IAAI,MAAM,KAAK,IAAI;QAAE,OAAO,IAAI,CAAC;IAEjC,MAAM,EAAE,GAAI,MAA2B,EAAE,EAAE,CAAC;IAC5C,IAAI,OAAO,EAAE,KAAK,QAAQ,IAAI,EAAE,KAAK,EAAE,EAAE,CAAC;QACxC,GAAG,CAAC,6EAA6E,CAAC,CAAC;QACnF,OAAO,IAAI,CAAC;IACd,CAAC;IACD,OAAO,EAAE,CAAC;AACZ,CAAC;AAED;;;;GAIG;AACH,MAAM,CAAC,KAAK,UAAU,mBAAmB,CACvC,SAAiB,EACjB,MAAoB,EACpB,IAAuB;IAEvB,MAAM,MAAM,GAAG,MAAM,cAAc,CACjC,IAAI,EACJ,MAAM,EACN,iBAAiB,kBAAkB,CAAC,SAAS,CAAC,YAAY,EAC1D,EAAE,kBAAkB,EAAE,MAAM,EAAE,EAC9B,WAAW,CACZ,CAAC;IACF,OAAO,MAAM,KAAK,IAAI,CAAC;AACzB,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,qBAAqB,CACnC,SAAiB,EACjB,MAAM,GAAG,MAAM,EACf,aAAkC,EAAE,CAAC,UAAU;IAE/C,KAAK,MAAM,IAAI,IAAI,CAAC,8BAA8B,SAAS,EAAE,EAAE,uBAAuB,SAAS,EAAE,CAAC,EAAE,CAAC;QACnG,IAAI,CAAC;YACH,UAAU,CAAC,IAAI,CAAC,IAAI,CAAC,MAAM,EAAE,IAAI,CAAC,CAAC,CAAC;QACtC,CAAC;QAAC,MAAM,CAAC;YACP,oCAAoC;QACtC,CAAC;IACH,CAAC;AACH,CAAC;AAcD;;;;;;GAMG;AACH,MAAM,CAAC,KAAK,UAAU,iBAAiB,CACrC,IAA8B;IAE9B,IAAI,CAAC,uBAAuB,CAAC,IAAI,CAAC,GAAG,IAAI,OAAO,CAAC,GAAG,CAAC;QAAE,OAAO,IAAI,CAAC;IAEnE,MAAM,SAAS,GAAG,MAAM,kBAAkB,CAAC,IAAI,CAAC,CAAC;IACjD,IAAI,CAAC,SAAS;QAAE,OAAO,IAAI,CAAC;IAE5B,OAAO,EAAE,SAAS,EAAE,YAAY,EAAE,IAAI,CAAC,kBAAkB,EAAE,EAAE,CAAC;AAChE,CAAC;AAED,2EAA2E;AAC3E,MAAM,CAAC,KAAK,UAAU,eAAe,CACnC,OAA4B,EAC5B,OAAqB,EACrB,IAA6C;IAE7C,IAAI,CAAC,OAAO;QAAE,OAAO;IACrB,MAAM,mBAAmB,CAAC,OAAO,CAAC,SAAS,EAAE,OAAO,EAAE,IAAI,CAAC,CAAC;IAC5D,qBAAqB,CAAC,OAAO,CAAC,SAAS,EAAE,IAAI,CAAC,MAAM,IAAI,MAAM,CAAC,CAAC;AAClE,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,UAAU,eAAe,CAC7B,GAA2B,EAC3B,OAA4B,EAC5B,MAAc,EACd,MAAc;IAEd,IAAI,CAAC,OAAO;QAAE,OAAO,GAAG,CAAC;IACzB,GAAG,CAAC,mBAAmB,GAAG,OAAO,CAAC,SAAS,CAAC;IAC5C,GAAG,CAAC,YAAY,GAAG,MAAM,CAAC;IAC1B,GAAG,CAAC,gBAAgB,GAAG,MAAM,CAAC;IAC9B,OAAO,GAAG,CAAC;AACb,CAAC;AAED,8EAA8E;AAC9E,YAAY;AACZ,8EAA8E;AAE9E,SAAS,OAAO,CAAC,CAAU;IACzB,OAAO,CAAC,YAAY,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC;AACpD,CAAC;AAED,SAAS,iBAAiB,CAAC,GAAW;IACpC,OAAO,GAAG,CAAC,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC;AACjC,CAAC;AAED;;;;GAIG;AACH,KAAK,UAAU,cAAc,CAC3B,IAAuB,EACvB,MAAc,EACd,KAAa,EACb,IAAa,EACb,KAAa;IAEb,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,IAAI,CAAC,GAAG,EAAE,GAAE,CAAC,CAAC,CAAC;IACnC,MAAM,OAAO,GAAG,IAAI,CAAC,SAAS,IAAK,UAAU,CAAC,KAA8B,CAAC;IAC7E,IAAI,CAAC,OAAO,EAAE,CAAC;QACb,GAAG,CAAC,oBAAoB,KAAK,8CAA8C,CAAC,CAAC;QAC7E,OAAO,IAAI,CAAC;IACd,CAAC;IAED,MAAM,UAAU,GAAG,IAAI,eAAe,EAAE,CAAC;IACzC,MAAM,KAAK,GAAG,UAAU,CAAC,GAAG,EAAE,CAAC,UAAU,CAAC,KAAK,EAAE,EAAE,IAAI,CAAC,SAAS,IAAI,kBAAkB,CAAC,CAAC;IACzF,IAAI,CAAC;QACH,MAAM,GAAG,GAAG,MAAM,OAAO,CAAC,GAAG,iBAAiB,CAAC,IAAI,CAAC,MAAM,CAAC,GAAG,KAAK,EAAE,EAAE;YACrE,MAAM;YACN,OAAO,EAAE,EAAE,cAAc,EAAE,kBAAkB,EAAE,WAAW,EAAE,IAAI,CAAC,MAAM,EAAE;YACzE,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC;YAC1B,MAAM,EAAE,UAAU,CAAC,MAAM;SAC1B,CAAC,CAAC;QACH,IAAI,CAAC,GAAG,CAAC,EAAE,EAAE,CAAC;YACZ,GAAG,CAAC,oBAAoB,KAAK,iBAAiB,GAAG,CAAC,MAAM,gCAAgC,CAAC,CAAC;YAC1F,OAAO,IAAI,CAAC;QACd,CAAC;QACD,IAAI,CAAC;YACH,OAAO,CAAC,MAAM,GAAG,CAAC,IAAI,EAAE,CAAC,IAAI,EAAE,CAAC;QAClC,CAAC;QAAC,MAAM,CAAC;YACP,OAAO,EAAE,CAAC;QACZ,CAAC;IACH,CAAC;IAAC,OAAO,CAAC,EAAE,CAAC;QACX,GAAG,CAAC,oBAAoB,KAAK,YAAY,OAAO,CAAC,CAAC,CAAC,gCAAgC,CAAC,CAAC;QACrF,OAAO,IAAI,CAAC;IACd,CAAC;YAAS,CAAC;QACT,YAAY,CAAC,KAAK,CAAC,CAAC;IACtB,CAAC;AACH,CAAC"}

package/dist/sessionCapture.test.d.ts

@@ -0,0 +1,9 @@
+/**
+ * add-multiplayer-sessions §1.5 — daemon session-capture wiring.
+ *
+ * The load-bearing properties are (a) the flag-off path is completely inert,
+ * (b) every capture failure degrades to "run the shift uncaptured" instead of
+ * throwing, and (c) hook registration never destroys existing hook config.
+ */
+export {};
+//# sourceMappingURL=sessionCapture.test.d.ts.map

package/dist/sessionCapture.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sessionCapture.test.d.ts","sourceRoot":"","sources":["../src/sessionCapture.test.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG"}

package/dist/sessionCapture.test.js

@@ -0,0 +1,366 @@
+/**
+ * add-multiplayer-sessions §1.5 — daemon session-capture wiring.
+ *
+ * The load-bearing properties are (a) the flag-off path is completely inert,
+ * (b) every capture failure degrades to "run the shift uncaptured" instead of
+ * throwing, and (c) hook registration never destroys existing hook config.
+ */
+import { describe, it, expect, vi } from "vitest";
+import { buildShiftEnv } from "./daemonPolicy.js";
+import { sessionStreamingEnabled, mergeCaptureHook, resolveCaptureHookScript, captureHookCommand, createCaptureSettingsFactory, openCaptureSession, closeCaptureSession, cleanupCaptureMarkers, beginShiftCapture, endShiftCapture, applyCaptureEnv, CAPTURE_HOOK_MARKER, } from "./sessionCapture.js";
+function okFetch(payload, status = 201) {
+    return vi.fn(async () => ({ ok: true, status, json: async () => payload }));
+}
+function failFetch(status = 500) {
+    return vi.fn(async () => ({ ok: false, status, json: async () => ({}) }));
+}
+const API = { apiUrl: "https://hub.example.com", apiKey: "k-1" };
+// ---------------------------------------------------------------------------
+// Kill switch
+// ---------------------------------------------------------------------------
+describe("sessionStreamingEnabled", () => {
+    it("defaults off when the variable is unset", () => {
+        expect(sessionStreamingEnabled({})).toBe(false);
+    });
+    it("stays off for empty, false, and unrecognised values", () => {
+        for (const v of ["", "  ", "false", "0", "off", "no", "maybe"]) {
+            expect(sessionStreamingEnabled({ AGENTHUB_SESSION_STREAMING_ENABLED: v })).toBe(false);
+        }
+    });
+    it("turns on only for explicit truthy values", () => {
+        for (const v of ["1", "true", "TRUE", "yes", "on", " true "]) {
+            expect(sessionStreamingEnabled({ AGENTHUB_SESSION_STREAMING_ENABLED: v })).toBe(true);
+        }
+    });
+});
+// ---------------------------------------------------------------------------
+// Hook registration — merge, never overwrite
+// ---------------------------------------------------------------------------
+describe("mergeCaptureHook", () => {
+    it("adds the capture hook to an empty settings object", () => {
+        const merged = mergeCaptureHook({}, captureHookCommand("/opt/h/session-capture.sh"));
+        const hooks = merged.hooks;
+        expect(hooks.PostToolUse).toHaveLength(1);
+        expect(hooks.PostToolUse[0].hooks[0].command).toContain(CAPTURE_HOOK_MARKER);
+    });
+    it("preserves existing PostToolUse entries instead of overwriting them", () => {
+        const base = {
+            hooks: {
+                PostToolUse: [
+                    { matcher: "", hooks: [{ type: "command", command: 'node "/x/activityHookCli.js"' }] },
+                ],
+            },
+        };
+        const merged = mergeCaptureHook(base, captureHookCommand("/opt/h/session-capture.sh"));
+        const entries = merged.hooks
+            .PostToolUse;
+        expect(entries).toHaveLength(2);
+        expect(entries[0].hooks[0].command).toContain("activityHookCli");
+        expect(entries[1].hooks[0].command).toContain(CAPTURE_HOOK_MARKER);
+    });
+    it("preserves other hook events and unrelated settings keys", () => {
+        const base = {
+            permissions: { allow: ["Bash"] },
+            hooks: {
+                SessionStart: [
+                    { matcher: "startup", hooks: [{ type: "command", command: 'node "/x/inboxHookCli.js"' }] },
+                ],
+            },
+        };
+        const merged = mergeCaptureHook(base, captureHookCommand("/opt/h/session-capture.sh"));
+        const hooks = merged.hooks;
+        expect(merged.permissions).toEqual({ allow: ["Bash"] });
+        expect(hooks.SessionStart).toHaveLength(1);
+        expect(hooks.PostToolUse).toHaveLength(1);
+    });
+    it("is idempotent — re-merging never duplicates the capture hook", () => {
+        const cmd = captureHookCommand("/opt/h/session-capture.sh");
+        const once = mergeCaptureHook({}, cmd);
+        const twice = mergeCaptureHook(once, cmd);
+        expect(twice.hooks.PostToolUse).toHaveLength(1);
+    });
+    it("does not mutate the input settings object", () => {
+        const base = { hooks: { PostToolUse: [] } };
+        mergeCaptureHook(base, captureHookCommand("/x/session-capture.sh"));
+        expect(base.hooks.PostToolUse).toHaveLength(0);
+    });
+});
+describe("resolveCaptureHookScript", () => {
+    it("prefers the packaged dist/ copy", () => {
+        const found = resolveCaptureHookScript("/opt/app/dist", () => true);
+        expect(found).toBe("/opt/app/dist/session-capture.sh");
+    });
+    it("falls back to the source-checkout copy beside dist/", () => {
+        const found = resolveCaptureHookScript("/repo/mcp-server/dist", (p) => p.replace(/\\/g, "/").endsWith("/repo/mcp-server/session-capture.sh"));
+        expect(found).toBe("/repo/mcp-server/session-capture.sh");
+    });
+    it("returns null when the script is nowhere to be found", () => {
+        expect(resolveCaptureHookScript("/opt/app/dist", () => false)).toBeNull();
+    });
+});
+describe("createCaptureSettingsFactory", () => {
+    it("writes a settings file containing only the capture hook", () => {
+        const writes = [];
+        const factory = createCaptureSettingsFactory("/opt/app/dist", "/tmp/s.json", {
+            exists: () => true,
+            writeFile: (p, d) => writes.push([p, d]),
+        });
+        expect(factory()).toBe("/tmp/s.json");
+        expect(writes).toHaveLength(1);
+        const parsed = JSON.parse(writes[0][1]);
+        expect(Object.keys(parsed)).toEqual(["hooks"]);
+        expect(parsed.hooks.PostToolUse[0].hooks[0].command).toContain(CAPTURE_HOOK_MARKER);
+    });
+    it("memoises — repeated calls write the file once", () => {
+        const writeFile = vi.fn();
+        const factory = createCaptureSettingsFactory("/opt/app/dist", "/tmp/s.json", {
+            exists: () => true,
+            writeFile,
+        });
+        factory();
+        factory();
+        factory();
+        expect(writeFile).toHaveBeenCalledTimes(1);
+    });
+    it("returns '' (no hook) when the capture script is missing, and logs", () => {
+        const log = vi.fn();
+        const factory = createCaptureSettingsFactory("/opt/app/dist", "/tmp/s.json", {
+            exists: () => false,
+            writeFile: () => {
+                throw new Error("should not be called");
+            },
+            log,
+        });
+        expect(factory()).toBe("");
+        expect(log).toHaveBeenCalled();
+    });
+    it("returns '' rather than throwing when the settings write fails", () => {
+        const factory = createCaptureSettingsFactory("/opt/app/dist", "/tmp/s.json", {
+            exists: () => true,
+            writeFile: () => {
+                throw new Error("EACCES");
+            },
+        });
+        expect(factory()).toBe("");
+    });
+});
+// ---------------------------------------------------------------------------
+// Session lifecycle
+// ---------------------------------------------------------------------------
+describe("openCaptureSession", () => {
+    it("POSTs to /api/sessions (never /sessions/start, which dispatches a shift)", async () => {
+        const fetchImpl = okFetch({ id: "sess-1" });
+        const id = await openCaptureSession({
+            ...API,
+            agentId: "eng-ic-test",
+            title: "task shift",
+            workingDirectory: "/opt/ws",
+            fetchImpl,
+        });
+        expect(id).toBe("sess-1");
+        const [url, init] = fetchImpl.mock.calls[0];
+        expect(url).toBe("https://hub.example.com/api/sessions");
+        expect(init.method).toBe("POST");
+        expect(init.headers["X-API-Key"]).toBe("k-1");
+        expect(JSON.parse(init.body)).toEqual({
+            agent_id: "eng-ic-test",
+            title: "task shift",
+            working_directory: "/opt/ws",
+        });
+    });
+    it("returns null on a non-2xx response without throwing", async () => {
+        const id = await openCaptureSession({ ...API, agentId: "a", fetchImpl: failFetch(500) });
+        expect(id).toBeNull();
+    });
+    it("returns null when the transport throws (network down, abort)", async () => {
+        const fetchImpl = async () => {
+            throw new Error("ECONNREFUSED");
+        };
+        const id = await openCaptureSession({ ...API, agentId: "a", fetchImpl });
+        expect(id).toBeNull();
+    });
+    it("returns null when the response carries no session id", async () => {
+        const id = await openCaptureSession({ ...API, agentId: "a", fetchImpl: okFetch({}) });
+        expect(id).toBeNull();
+    });
+    it("aborts rather than hanging when the server is slow", async () => {
+        const fetchImpl = (_url, init) => new Promise((_resolve, reject) => {
+            const signal = init.signal;
+            signal.addEventListener("abort", () => reject(new Error("aborted")));
+        });
+        const id = await openCaptureSession({ ...API, agentId: "a", fetchImpl, timeoutMs: 10 });
+        expect(id).toBeNull();
+    });
+});
+describe("closeCaptureSession", () => {
+    it("POSTs to /{id}/terminate with the outcome as the reason", async () => {
+        const fetchImpl = okFetch({ status: "terminated" }, 200);
+        const ok = await closeCaptureSession("sess-1", "completed", { ...API, fetchImpl });
+        expect(ok).toBe(true);
+        const [url, init] = fetchImpl.mock.calls[0];
+        expect(url).toBe("https://hub.example.com/api/sessions/sess-1/terminate");
+        expect(JSON.parse(init.body)).toEqual({ termination_reason: "completed" });
+    });
+    it("reports failure instead of throwing when the server rejects", async () => {
+        const ok = await closeCaptureSession("sess-1", "failed", { ...API, fetchImpl: failFetch(404) });
+        expect(ok).toBe(false);
+    });
+});
+describe("cleanupCaptureMarkers", () => {
+    it("removes both per-session markers, keyed by session id", () => {
+        const removed = [];
+        cleanupCaptureMarkers("sess-1", "/tmp", (p) => removed.push(p.replace(/\\/g, "/")));
+        expect(removed).toEqual([
+            "/tmp/agenthub-transcript-offset-sess-1",
+            "/tmp/agenthub-claude-sid-sess-1",
+        ]);
+    });
+    it("swallows ENOENT for markers that were never written", () => {
+        expect(() => cleanupCaptureMarkers("sess-1", "/tmp", () => {
+            throw new Error("ENOENT");
+        })).not.toThrow();
+    });
+    it("gives concurrent shifts disjoint marker paths", () => {
+        const a = [];
+        const b = [];
+        cleanupCaptureMarkers("sess-a", "/tmp", (p) => a.push(p));
+        cleanupCaptureMarkers("sess-b", "/tmp", (p) => b.push(p));
+        expect(a.some((p) => b.includes(p))).toBe(false);
+    });
+});
+// ---------------------------------------------------------------------------
+// Shift wiring
+// ---------------------------------------------------------------------------
+describe("beginShiftCapture", () => {
+    it("is completely inert with the flag off — no fetch, no settings file", async () => {
+        const fetchImpl = vi.fn();
+        const ensureSettingsFile = vi.fn(() => "/tmp/s.json");
+        const capture = await beginShiftCapture({
+            ...API,
+            agentId: "a",
+            env: {},
+            ensureSettingsFile,
+            fetchImpl: fetchImpl,
+        });
+        expect(capture).toBeNull();
+        expect(fetchImpl).not.toHaveBeenCalled();
+        expect(ensureSettingsFile).not.toHaveBeenCalled();
+    });
+    it("stays inert when the flag is explicitly false", async () => {
+        const fetchImpl = vi.fn();
+        const capture = await beginShiftCapture({
+            ...API,
+            agentId: "a",
+            env: { AGENTHUB_SESSION_STREAMING_ENABLED: "false" },
+            ensureSettingsFile: () => "/tmp/s.json",
+            fetchImpl: fetchImpl,
+        });
+        expect(capture).toBeNull();
+        expect(fetchImpl).not.toHaveBeenCalled();
+    });
+    it("with the flag on, returns the session id and the settings file", async () => {
+        const capture = await beginShiftCapture({
+            ...API,
+            agentId: "a",
+            env: { AGENTHUB_SESSION_STREAMING_ENABLED: "true" },
+            ensureSettingsFile: () => "/tmp/s.json",
+            fetchImpl: okFetch({ id: "sess-9" }),
+        });
+        expect(capture).toEqual({ sessionId: "sess-9", settingsFile: "/tmp/s.json" });
+    });
+    it("degrades to no capture (not a throw) when session creation fails", async () => {
+        const ensureSettingsFile = vi.fn(() => "/tmp/s.json");
+        const capture = await beginShiftCapture({
+            ...API,
+            agentId: "a",
+            env: { AGENTHUB_SESSION_STREAMING_ENABLED: "true" },
+            ensureSettingsFile,
+            fetchImpl: failFetch(503),
+        });
+        expect(capture).toBeNull();
+        expect(ensureSettingsFile).not.toHaveBeenCalled();
+    });
+    it("still opens the session when the hook script is unavailable", async () => {
+        const capture = await beginShiftCapture({
+            ...API,
+            agentId: "a",
+            env: { AGENTHUB_SESSION_STREAMING_ENABLED: "true" },
+            ensureSettingsFile: () => "",
+            fetchImpl: okFetch({ id: "sess-9" }),
+        });
+        expect(capture).toEqual({ sessionId: "sess-9", settingsFile: "" });
+    });
+});
+describe("endShiftCapture", () => {
+    it("is a no-op when the shift was never captured", async () => {
+        const fetchImpl = vi.fn();
+        await endShiftCapture(null, "completed", { ...API, fetchImpl: fetchImpl });
+        expect(fetchImpl).not.toHaveBeenCalled();
+    });
+    it("terminates the session on the success path", async () => {
+        const fetchImpl = okFetch({}, 200);
+        await endShiftCapture({ sessionId: "s", settingsFile: "" }, "completed", { ...API, fetchImpl });
+        const [, init] = fetchImpl.mock.calls[0];
+        expect(JSON.parse(init.body).termination_reason).toBe("completed");
+    });
+    it("terminates the session on the failure path too", async () => {
+        const fetchImpl = okFetch({}, 200);
+        await endShiftCapture({ sessionId: "s", settingsFile: "" }, "failed", { ...API, fetchImpl });
+        const [, init] = fetchImpl.mock.calls[0];
+        expect(JSON.parse(init.body).termination_reason).toBe("failed");
+    });
+    it("does not throw when termination itself fails", async () => {
+        await expect(endShiftCapture({ sessionId: "s", settingsFile: "" }, "spawn_error", {
+            ...API,
+            fetchImpl: failFetch(500),
+        })).resolves.toBeUndefined();
+    });
+});
+describe("applyCaptureEnv", () => {
+    it("leaves the child env untouched when there is no capture", () => {
+        const env = { PATH: "/usr/bin", AGENTHUB_AGENT_ID: "a" };
+        const before = { ...env };
+        applyCaptureEnv(env, null, API.apiUrl, API.apiKey);
+        expect(env).toEqual(before);
+        expect(env.AGENTHUB_SESSION_ID).toBeUndefined();
+    });
+    it("sets AGENTHUB_SESSION_ID plus the URL/key the hook reads", () => {
+        const capture = { sessionId: "sess-7", settingsFile: "/tmp/s.json" };
+        const env = { PATH: "/usr/bin" };
+        applyCaptureEnv(env, capture, API.apiUrl, API.apiKey);
+        expect(env.AGENTHUB_SESSION_ID).toBe("sess-7");
+        expect(env.AGENTHUB_URL).toBe(API.apiUrl);
+        expect(env.AGENTHUB_API_KEY).toBe(API.apiKey);
+        expect(env.PATH).toBe("/usr/bin");
+    });
+});
+// ---------------------------------------------------------------------------
+// The composition daemon.ts actually performs:
+//   applyCaptureEnv(buildShiftEnv(process.env, AGENT_ID), capture, URL, KEY)
+// ---------------------------------------------------------------------------
+describe("daemon shift env composition", () => {
+    const processEnv = {
+        PATH: "/usr/bin",
+        CLAUDECODE: "1",
+        CLAUDE_CODE_OAUTH_TOKEN: "oauth-abc",
+        AGENTHUB_API_KEY: "k-1",
+    };
+    it("flag off: the child env is exactly the historical shift env", () => {
+        const historical = buildShiftEnv(processEnv, "eng-ic-test");
+        const actual = applyCaptureEnv(buildShiftEnv(processEnv, "eng-ic-test"), null, API.apiUrl, API.apiKey);
+        expect(actual).toEqual(historical);
+        expect(actual.AGENTHUB_SESSION_ID).toBeUndefined();
+    });
+    it("flag on: AGENTHUB_SESSION_ID reaches the child, and buildShiftEnv's own rules survive", () => {
+        const capture = { sessionId: "sess-42", settingsFile: "/tmp/s.json" };
+        const env = applyCaptureEnv(buildShiftEnv(processEnv, "eng-ic-test"), capture, API.apiUrl, API.apiKey);
+        expect(env.AGENTHUB_SESSION_ID).toBe("sess-42");
+        // buildShiftEnv invariants must not be disturbed by capture.
+        expect(env.AGENTHUB_AGENT_ID).toBe("eng-ic-test");
+        expect(env.AGENTHUB_AUTO_INBOX).toBe("false");
+        expect(env.AGENTHUB_DISABLE_WEBSOCKET).toBe("true");
+        expect(env.CLAUDE_CODE_OAUTH_TOKEN).toBe("oauth-abc");
+        expect(env.CLAUDECODE).toBeUndefined();
+    });
+});
+//# sourceMappingURL=sessionCapture.test.js.map