@sapiom/harness 0.0.0 → 0.1.0

package/dist/core/session-manager.d.ts

@@ -0,0 +1,275 @@
+/**
+ * SessionManager — node-pty registry implementing the session lifecycle from
+ * the shared contract: create, resume, kill, list. Persists HarnessSession[]
+ * to disk (HARNESS_PATHS.sessions) so the SPA's session dropdown survives
+ * server restarts, even though the ptys themselves do not.
+ */
+import { type CreateSessionRequest, type HarnessAdapter, type HarnessKind, type HarnessSession, type LaunchOpts } from "../shared/types.js";
+type IPty = import("node-pty").IPty;
+type PtyForkOptions = import("node-pty").IPtyForkOptions;
+export type PtySpawnFn = (file: string, args: string[], options: PtyForkOptions) => IPty;
+/**
+ * node-pty ships prebuilt native binaries (including a tiny `spawn-helper`
+ * on macOS/Linux) rather than compiling from source. Observed in the wild:
+ * a pnpm-managed install can extract that helper without its executable bit
+ * set, which fails every single spawn with an opaque "posix_spawnp failed"
+ * — nothing to do with the harness's own code, but fatal to every session
+ * launch. Best-effort self-heal before the first real spawn; silently a
+ * no-op if the file's missing (wrong platform/arch) or already executable.
+ * Exported so scripts/e2e-live.ts's preflight check shares this exact fix
+ * instead of duplicating it.
+ */
+export declare function ensureSpawnHelperExecutable(): Promise<void>;
+/**
+ * Thrown by `submitInput()` when a session's pty is alive but never became
+ * ready (see `HarnessSession.ready`) within `READY_GRACE_MS` — the trust-
+ * dialog race this whole readiness mechanism exists to catch. Callers
+ * (rest.ts, macros.ts) catch this specifically and surface it as a 409 with
+ * a UI-visible reason, rather than letting it fall into a generic 500 or
+ * (worse, the bug this fixes) silently writing into a non-interactive TUI.
+ */
+export declare class SessionNotReadyError extends Error {
+    constructor(id: string);
+}
+export type SessionStatusListener = (session: HarnessSession) => void;
+export type SessionDataListener = (chunk: string) => void;
+/** See `onActivity()`. */
+export type SessionActivityListener = (harnessSessionId: string) => void;
+/**
+ * Builds the harness-specific part of LaunchOpts (generated system-prompt /
+ * mcp-config / settings file paths). SessionManager owns cwd + harnessSessionId;
+ * this lets the server layer inject config-file generation (profiles, MCP
+ * wiring) without SessionManager needing to know how those files are produced.
+ * May return synchronously or a Promise — generating the config files is
+ * inherently async (they're written to disk), so `create()`/`resume()` await
+ * whichever shape is handed in; existing sync test doubles keep working
+ * unchanged (`await` on a plain value just resolves immediately).
+ */
+export type LaunchOptsBuilder = (harnessSessionId: string, req: Pick<CreateSessionRequest, "cwd" | "harness" | "profile">) => Omit<LaunchOpts, "harnessSessionId" | "cwd"> | Promise<Omit<LaunchOpts, "harnessSessionId" | "cwd">>;
+export interface SessionManagerOptions {
+    adapters: Partial<Record<HarnessKind, HarnessAdapter>>;
+    /** Base URL the harness server is reachable at, e.g. http://127.0.0.1:4100. */
+    ingestUrl: string;
+    /** Per-boot secret; injected into every session's env so hook scripts can auth to /ingest. */
+    ingestToken: string;
+    /** Forwarded to sessions as SAPIOM_COLLECTOR_URL when set. */
+    collectorUrl?: string;
+    /** Absolute path to the session registry file. Defaults to HARNESS_PATHS.sessions (expanded). */
+    sessionsPath?: string;
+    /** Injectable for tests. Defaults to a lazily-loaded node-pty. */
+    spawnPty?: PtySpawnFn;
+    buildLaunchOpts?: LaunchOptsBuilder;
+    now?: () => string;
+    generateId?: () => string;
+    /**
+     * Writes HARNESS_CONTEXT_FILE for a session — the caller (server/index.ts's
+     * `writeSessionContext`) owns resolving the session's `boundWorkflowPath`
+     * against the live workflow registry and serializing the full workspace
+     * state; this layer just decides *when* to call it. Called unconditionally
+     * from `create()`, before the pty is spawned, so every session gets the
+     * file regardless of entry point (REST, `autoCreateSession`) — no entry
+     * point can skip it by calling `create()` directly. Also used by
+     * `resume()` as a backfill when the file is entirely missing (see
+     * `workspaceContextExists`). Defaults to a no-op so tests that pass a fake
+     * `cwd` (e.g. `/tmp/proj`) never touch the real filesystem unless they opt
+     * in.
+     */
+    writeWorkspaceContext?: (session: HarnessSession) => Promise<void>;
+    /**
+     * Reports whether HARNESS_CONTEXT_FILE already exists for a cwd. Used only
+     * by `resume()`, to decide whether a backfill write is needed — resume
+     * must never clobber a file that could already reflect a real binding.
+     * Defaults to `true` (assume it exists, never backfill) to match the
+     * no-op default of `writeWorkspaceContext`.
+     */
+    workspaceContextExists?: (cwd: string) => Promise<boolean>;
+    /**
+     * Drops the canvas kit template into `<cwd>/.sapiom/canvas/index.html`
+     * when nothing is there yet (backfill-only — the real implementation,
+     * `ensureCanvasTemplate` from core/canvas-template.ts, does its own
+     * existence check internally, so unlike `writeWorkspaceContext` this
+     * needs no separate `*Exists` companion). Called from both `create()` and
+     * `resume()` so the canvas pane is never a blank iframe, regardless of
+     * entry point. Defaults to a no-op so tests that pass a fake `cwd` never
+     * touch the real filesystem unless they opt in.
+     */
+    ensureCanvasTemplate?: (cwd: string) => Promise<void>;
+    /**
+     * Injectable for tests (fake ptys carry fake pids that must never be
+     * probed against real OS processes). Defaults to `defaultIsPidAlive`.
+     */
+    isPidAlive?: (pid: number) => boolean;
+}
+export declare class SessionManager {
+    private readonly adapters;
+    private readonly ingestUrl;
+    private readonly ingestToken;
+    private readonly collectorUrl;
+    private readonly sessionsPath;
+    private readonly spawnPty;
+    private readonly buildLaunchOpts;
+    private readonly now;
+    private readonly generateId;
+    private readonly writeWorkspaceContext;
+    private readonly workspaceContextExists;
+    private readonly ensureCanvasTemplate;
+    private readonly isPidAlive;
+    private readonly sessions;
+    private readonly ptys;
+    private readonly statusEmitter;
+    private readonly activityEmitter;
+    /** Epoch ms of the last `onActivity` broadcast per session — see `recordActivity()`. */
+    private readonly lastActivityBroadcast;
+    private writeQueue;
+    private writeSeq;
+    private initialized;
+    constructor(options: SessionManagerOptions);
+    /**
+     * Loads the persisted registry. Any session left "starting"/"running" from
+     * a previous process is marked "exited" — ptys don't survive a restart.
+     */
+    init(): Promise<void>;
+    list(): HarnessSession[];
+    get(id: string): HarnessSession | undefined;
+    private getAdapter;
+    create(req: CreateSessionRequest): Promise<HarnessSession>;
+    /**
+     * Registers a purely historical (never-launched-by-this-harness) session so
+     * it can subsequently be resumed via `resume()`. Used by the server layer
+     * when a user picks a past session out of transcript-scanned history.
+     */
+    registerHistorical(input: {
+        agentSessionId: string;
+        harness: HarnessKind;
+        cwd: string;
+        title: string;
+        lastActiveAt: string;
+    }): HarnessSession;
+    resume(id: string): Promise<HarnessSession>;
+    kill(id: string): boolean;
+    /** Kills every currently-live pty. Call this on server shutdown — without
+     *  it, spawned agent processes (claude/codex) outlive the harness server
+     *  itself, e.g. after Ctrl+C, since closing the HTTP/WS server doesn't
+     *  touch unrelated child processes on its own. */
+    killAll(): void;
+    /**
+     * Defensive liveness backstop, run periodically by the server: any
+     * non-exited session whose pty process is provably gone gets its exit
+     * synthesized. The specific transitions are already reconciled at their
+     * source (create/resume pre-pty failures, kill()'s missed-exit fallback),
+     * but node-pty has been observed to simply never fire `onExit` for a
+     * process that died moments after spawning (see `kill()`) — and a process
+     * that dies *on its own* that way has no kill()-style fallback watching
+     * it. This sweep is the catch-all for that and any transition not yet
+     * root-caused: a stale record shows as a ghost tab (non-exited status, no
+     * live pty) until something reconciles it.
+     */
+    sweepDeadSessions(): void;
+    write(id: string, data: string): boolean;
+    /**
+     * Inject a discrete prompt (macros, the Visualize button, `/api/sessions/:id/input`)
+     * with proper submit semantics — distinct from `write()`, which is a raw
+     * passthrough for live keystrokes from the terminal WS and must never add
+     * this delay/splitting behavior. See `SUBMIT_DELAY_MS` for why non-empty
+     * submitted text can't just be written as `${text}\r` in one call.
+     *
+     * Gated on readiness (see `HarnessSession.ready` / `isReadyEnough`): a
+     * "running" pty can still be sitting on a blocking prompt that swallows
+     * whatever's written to it. Briefly waits out `READY_GRACE_MS` for the
+     * ordinary "fired a beat too early" case; throws `SessionNotReadyError`
+     * — never silently proceeds — if the session still isn't ready after
+     * that, so the caller (rest.ts, macros.ts) can surface a clear reason
+     * instead of the input just vanishing.
+     */
+    submitInput(id: string, text: string, submit?: boolean): Promise<boolean>;
+    resize(id: string, cols: number, rows: number): boolean;
+    /**
+     * Subscribe to a session's output. Replays the retained scrollback buffer
+     * synchronously before returning so a reconnecting WS client sees recent
+     * output immediately. Returns undefined if the session has no live pty.
+     */
+    attach(id: string, listener: SessionDataListener): (() => void) | undefined;
+    onStatusChange(listener: SessionStatusListener): () => void;
+    /**
+     * Subscribe to a session producing terminal output — throttled (see
+     * `ACTIVITY_BROADCAST_THROTTLE_MS`), not one event per pty.onData chunk.
+     * Fires for every session regardless of whether anything has its
+     * /ws/terminal socket open, unlike `attach()`.
+     */
+    onActivity(listener: SessionActivityListener): () => void;
+    /**
+     * Leading-edge throttle: broadcasts immediately on the first byte after a
+     * quiet period, then drops everything else for this session until
+     * `ACTIVITY_BROADCAST_THROTTLE_MS` has elapsed — a busy TUI's onData fires
+     * far more often than that, and callers (the SPA's per-tab pulse) only
+     * care that the session is active right now, not each individual chunk.
+     */
+    private recordActivity;
+    setAgentSessionId(id: string, agentSessionId: string): void;
+    /**
+     * Marks a session's TUI as genuinely interactive — see `HarnessSession.ready`.
+     * Called from the ingest pipeline when a SessionStart(-equivalent) event
+     * is processed for this session (real hook for Claude Code, tailer-
+     * translated for Codex). Idempotent; a session that's exited or already
+     * ready is a silent no-op.
+     */
+    setReady(id: string): void;
+    /**
+     * Whether `id` should be treated as ready to receive programmatic input
+     * right now — `session.ready` (the real signal), OR, for a harness that
+     * declares `detectBlockingPrompt` (currently: Codex, whose rollout file —
+     * and therefore its SessionStart-equivalent — isn't written until the
+     * *first* turn is submitted, so the real signal can never arrive before
+     * the very first injection that needs it): the pty has had a moment to
+     * render its first real frame (`READY_SETTLE_MS`) and that frame doesn't
+     * show a known blocking prompt. A harness without `detectBlockingPrompt`
+     * (Claude Code) gets no such fallback — its SessionStart hook is reliable
+     * standalone, and a scrollback guess would just reopen the exact race
+     * this mechanism exists to close.
+     */
+    private isReadyEnough;
+    /**
+     * Polls `isReadyEnough` until it's true, the session's pty goes away
+     * (killed/exited — it's never going to become ready now), or `timeoutMs`
+     * elapses. Used by `submitInput()` only — `write()` (raw terminal
+     * keystrokes) must never wait on this, since a human answering the very
+     * prompt this is waiting out is exactly how a session becomes ready.
+     */
+    private waitUntilReady;
+    /** Waits for all in-flight registry writes to settle. Useful before process
+     * shutdown (and in tests that assert against the on-disk registry). */
+    flush(): Promise<void>;
+    setTitle(id: string, title: string): void;
+    /** Binds (or, with `null`, unbinds) the session's current workflow
+     *  selection. The caller (rest.ts) owns validating `workflowPath` against
+     *  the workflow registry and mirroring the binding into
+     *  HARNESS_CONTEXT_FILE — this only updates the in-memory/persisted
+     *  registry entry and broadcasts the change like any other status update. */
+    setBoundWorkflowPath(id: string, workflowPath: string | null): void;
+    private spawn;
+    /**
+     * Transitions a session to "exited". Shared by node-pty's own `onExit`
+     * callback and `kill()`'s missed-event fallback (see `kill()`) — both are
+     * racing to be the one that reports a given pty's death, so this is
+     * idempotent: a stale/duplicate call (`this.ptys.get(id) !== handle`,
+     * i.e. this handle was already replaced or already reported exited) is a
+     * silent no-op rather than double-transitioning or clobbering a newer
+     * session/handle that's since taken its place (e.g. a resume).
+     */
+    private markExited;
+    /**
+     * The single place a session record flips to "exited" — shared by
+     * `markExited()` (live-pty deaths), `create()`/`resume()`'s pre-pty
+     * failure reconciliation, `kill()`'s stale-record path, and
+     * `sweepDeadSessions()`. Returns the persist promise so callers that need
+     * the registry durably updated before rethrowing (create/resume) can
+     * await it; event-driven callers fire-and-forget it like any other write.
+     */
+    private transitionExited;
+    private emitStatus;
+    /** Serializes writes so overlapping persist() calls can't interleave and
+     * corrupt the registry file; a failed write doesn't poison later ones. */
+    private persist;
+}
+export {};
+//# sourceMappingURL=session-manager.d.ts.map

package/dist/core/session-manager.d.ts.map

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