@wastedcode/claudemux 0.2.0

package/dist/backends/tmux/sessions.d.ts

@@ -0,0 +1,70 @@
+import { type TmuxExec } from "./exec.js";
+/**
+ * Build the namespaced tmux session target name from `namespace` + `name`.
+ * The namespace prefix is what lets two consumers + manual user tmux
+ * sessions coexist on one private server without collision.
+ *
+ * The separator is `--` because `:` and `.` are reserved by tmux's target
+ * grammar (`session:window.pane`) — a colon-separated name would parse as
+ * "session=<namespace>, window=<name>" and trip "no such window" errors.
+ */
+export declare function targetOf(namespace: string, name: string): string;
+/**
+ * Create a new tmux session running `cmd` + `argv` in `cwd`, with the
+ * substrate's server-global options set in the same invocation so they
+ * land before the agent's pane is allocated.
+ *
+ * Per-session environment (including `LC_ALL=C.UTF-8` for unicode glyph
+ * stability — a substrate concern, not an agent one) rides on `new-session
+ * -e KEY=VAL` pairs. `-e` on `new-session` is tmux ≥3.2; that sets the
+ * substrate's supported floor (see README §Compatibility / details.md
+ * §Quality). `set-environment` after `new-session` is not an option — it
+ * doesn't affect the already-spawned pane process.
+ */
+export declare function newSession(exec: TmuxExec, o: {
+    namespace: string;
+    name: string;
+    cwd: string;
+    env?: Record<string, string>;
+    cmd: string;
+    argv: string[];
+    /** User-facing label for error messages (defaults to tmux target encoding). */
+    label?: string;
+}): Promise<void>;
+/**
+ * Is the named session currently alive on the server?
+ *
+ * Returns `false` (never throws) for "the session isn't here":
+ *   - exit 0 → `true`
+ *   - `can't find session/window/pane: …` (any level of tmux's target
+ *     grammar) → `false`, via `isSessionGoneStderr`. A name that trips the
+ *     `session:window.pane` parser still yields a boolean, not a throw.
+ *   - `no-server` BackendUnreachable (empty/down server) → `false`.
+ *
+ * It DOES throw `BackendUnreachable` for `spawn-failed` (backend binary
+ * missing) and `timeout` (wedged backend) — those are real faults; a missing
+ * dependency must not masquerade as "no such session." The no-server gate
+ * lives solely in the catch (exec.run rejects no-server before it could
+ * resolve), so there is no dead resolve-path branch here.
+ *
+ * `label` is the user-facing identifier used in error messages (defaults to
+ * `target`). Errors thrown from this function carry `label`, not the tmux
+ * internal target encoding.
+ */
+export declare function hasSession(exec: TmuxExec, target: string, label?: string): Promise<boolean>;
+/**
+ * Kill a session by target name. Idempotent — "session was already gone" or
+ * "no server running" is treated as success. A *missing backend binary*
+ * (`spawn-failed`) or a *wedged* server (`timeout`) still throws — those are
+ * real faults, not "the session is already gone."
+ */
+export declare function killSession(exec: TmuxExec, target: string, label?: string): Promise<void>;
+/**
+ * List the *short* session names within `namespace` (the piece after the
+ * `<namespace>--` prefix), in whatever order tmux reports. A running-but-empty
+ * server, or no server at all, returns `[]`. A missing backend binary or a
+ * wedged server throws `BackendUnreachable` — an empty list must mean "no
+ * sessions," never "we couldn't reach the backend."
+ */
+export declare function listSessions(exec: TmuxExec, namespace: string): Promise<string[]>;
+//# sourceMappingURL=sessions.d.ts.map

package/dist/backends/tmux/sessions.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sessions.d.ts","sourceRoot":"","sources":["../../../src/backends/tmux/sessions.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,KAAK,QAAQ,EAAwD,MAAM,WAAW,CAAC;AAGhG;;;;;;;;GAQG;AACH,wBAAgB,QAAQ,CAAC,SAAS,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,CAEhE;AAED;;;;;;;;;;;GAWG;AACH,wBAAsB,UAAU,CAC9B,IAAI,EAAE,QAAQ,EACd,CAAC,EAAE;IACD,SAAS,EAAE,MAAM,CAAC;IAClB,IAAI,EAAE,MAAM,CAAC;IACb,GAAG,EAAE,MAAM,CAAC;IACZ,GAAG,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC7B,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,EAAE,MAAM,EAAE,CAAC;IACf,+EAA+E;IAC/E,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB,GACA,OAAO,CAAC,IAAI,CAAC,CAmCf;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAsB,UAAU,CAC9B,IAAI,EAAE,QAAQ,EACd,MAAM,EAAE,MAAM,EACd,KAAK,GAAE,MAAe,GACrB,OAAO,CAAC,OAAO,CAAC,CAYlB;AAED;;;;;GAKG;AACH,wBAAsB,WAAW,CAC/B,IAAI,EAAE,QAAQ,EACd,MAAM,EAAE,MAAM,EACd,KAAK,GAAE,MAAe,GACrB,OAAO,CAAC,IAAI,CAAC,CAWf;AAED;;;;;;GAMG;AACH,wBAAsB,YAAY,CAAC,IAAI,EAAE,QAAQ,EAAE,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CAmBvF"}

package/dist/backends/tmux/sessions.js

@@ -0,0 +1,156 @@
+import { SessionGone } from "../../errors.js";
+import { PANE_HEIGHT } from "../../session/constants.js";
+import { classifyTmuxFailure, isNoServer, isSessionGoneStderr } from "./exec.js";
+import { serverOptionsArgv } from "./options.js";
+/**
+ * Build the namespaced tmux session target name from `namespace` + `name`.
+ * The namespace prefix is what lets two consumers + manual user tmux
+ * sessions coexist on one private server without collision.
+ *
+ * The separator is `--` because `:` and `.` are reserved by tmux's target
+ * grammar (`session:window.pane`) — a colon-separated name would parse as
+ * "session=<namespace>, window=<name>" and trip "no such window" errors.
+ */
+export function targetOf(namespace, name) {
+    return `${namespace}--${name}`;
+}
+/**
+ * Create a new tmux session running `cmd` + `argv` in `cwd`, with the
+ * substrate's server-global options set in the same invocation so they
+ * land before the agent's pane is allocated.
+ *
+ * Per-session environment (including `LC_ALL=C.UTF-8` for unicode glyph
+ * stability — a substrate concern, not an agent one) rides on `new-session
+ * -e KEY=VAL` pairs. `-e` on `new-session` is tmux ≥3.2; that sets the
+ * substrate's supported floor (see README §Compatibility / details.md
+ * §Quality). `set-environment` after `new-session` is not an option — it
+ * doesn't affect the already-spawned pane process.
+ */
+export async function newSession(exec, o) {
+    const target = targetOf(o.namespace, o.name);
+    const label = o.label ?? target;
+    // LC_ALL=C.UTF-8 is the substrate's default locale; `o.env` may override or
+    // augment it. Merging into one object dedupes the key, so the agent passing
+    // `env: { LC_ALL }` (claude does) doesn't produce a duplicate `-e` flag.
+    const env = { LC_ALL: "C.UTF-8", ...o.env };
+    const envFlags = Object.entries(env).flatMap(([k, v]) => ["-e", `${k}=${v}`]);
+    const newSessionCmd = [
+        "new-session",
+        "-d",
+        "-s",
+        target,
+        "-x",
+        "120",
+        "-y",
+        // Pane height = the classifier's scan cap; one source so they can't drift.
+        String(PANE_HEIGHT),
+        ...envFlags,
+        "-c",
+        o.cwd,
+        o.cmd,
+        ...o.argv,
+    ];
+    // Combine server-options + new-session into ONE tmux invocation so the
+    // globals land in the same client connection that creates the session.
+    // The server only stays alive once a session exists, so `start-server`
+    // followed by `set-option -g` doesn't work — globals must be set in the
+    // same invocation that registers the first session.
+    const argv = [...serverOptionsArgv(), ...newSessionCmd];
+    const r = await exec.run(argv, { sessionName: label });
+    const err = classifyTmuxFailure(label, ["tmux", ...argv], r);
+    if (err)
+        throw err;
+}
+/**
+ * Is the named session currently alive on the server?
+ *
+ * Returns `false` (never throws) for "the session isn't here":
+ *   - exit 0 → `true`
+ *   - `can't find session/window/pane: …` (any level of tmux's target
+ *     grammar) → `false`, via `isSessionGoneStderr`. A name that trips the
+ *     `session:window.pane` parser still yields a boolean, not a throw.
+ *   - `no-server` BackendUnreachable (empty/down server) → `false`.
+ *
+ * It DOES throw `BackendUnreachable` for `spawn-failed` (backend binary
+ * missing) and `timeout` (wedged backend) — those are real faults; a missing
+ * dependency must not masquerade as "no such session." The no-server gate
+ * lives solely in the catch (exec.run rejects no-server before it could
+ * resolve), so there is no dead resolve-path branch here.
+ *
+ * `label` is the user-facing identifier used in error messages (defaults to
+ * `target`). Errors thrown from this function carry `label`, not the tmux
+ * internal target encoding.
+ */
+export async function hasSession(exec, target, label = target) {
+    try {
+        const r = await exec.run(["has-session", "-t", target], { sessionName: label });
+        if (r.exit === 0)
+            return true;
+        if (isSessionGoneStderr(r.stderr))
+            return false;
+        const err = classifyTmuxFailure(label, ["tmux", "has-session", "-t", target], r);
+        if (err)
+            throw err;
+        return false;
+    }
+    catch (err) {
+        if (isNoServer(err))
+            return false; // empty server == no such session
+        throw err; // spawn-failed (binary missing) / timeout (wedged) surface loudly
+    }
+}
+/**
+ * Kill a session by target name. Idempotent — "session was already gone" or
+ * "no server running" is treated as success. A *missing backend binary*
+ * (`spawn-failed`) or a *wedged* server (`timeout`) still throws — those are
+ * real faults, not "the session is already gone."
+ */
+export async function killSession(exec, target, label = target) {
+    try {
+        const r = await exec.run(["kill-session", "-t", target], { sessionName: label });
+        if (r.exit === 0)
+            return;
+        const err = classifyTmuxFailure(label, ["tmux", "kill-session", "-t", target], r);
+        if (err instanceof SessionGone)
+            return;
+        if (err)
+            throw err;
+    }
+    catch (err) {
+        if (isNoServer(err))
+            return; // empty server == no session to kill
+        throw err;
+    }
+}
+/**
+ * List the *short* session names within `namespace` (the piece after the
+ * `<namespace>--` prefix), in whatever order tmux reports. A running-but-empty
+ * server, or no server at all, returns `[]`. A missing backend binary or a
+ * wedged server throws `BackendUnreachable` — an empty list must mean "no
+ * sessions," never "we couldn't reach the backend."
+ */
+export async function listSessions(exec, namespace) {
+    let r;
+    try {
+        r = await exec.run(["list-sessions", "-F", "#{session_name}"], { sessionName: namespace });
+    }
+    catch (err) {
+        if (isNoServer(err))
+            return [];
+        throw err;
+    }
+    if (r.exit !== 0) {
+        if (r.stdout.trim() === "")
+            return [];
+        const err = classifyTmuxFailure(namespace, ["tmux", "list-sessions"], r);
+        if (err)
+            throw err;
+    }
+    const prefix = `${namespace}--`;
+    return r.stdout
+        .split("\n")
+        .map((line) => line.trim())
+        .filter((line) => line.startsWith(prefix))
+        .map((line) => line.slice(prefix.length));
+}
+//# sourceMappingURL=sessions.js.map

package/dist/backends/tmux/sessions.js.map

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

package/dist/backends/tmux/socket.d.ts

@@ -0,0 +1,26 @@
+/**
+ * The substrate's default tmux socket name — `"claudemux"`.
+ *
+ * Pure function (no env reads here). The bootstrap layer
+ * (`src/session/default-backend.ts`) composes the precedence:
+ *
+ *   explicit `tmuxBackend({ socket })` > `--socket` flag > `CLAUDEMUX_SOCKET` env >
+ *   `defaultSocketName()`
+ *
+ * tmux already namespaces socket files per-UID (`/tmp/tmux-$UID/claudemux`,
+ * mode 0700), so a fixed name is per-user-safe by construction. Two
+ * consumers from the same user share the same tmux server and coexist via
+ * the substrate's namespace prefix (`<ns>--<name>`) — that is the
+ * substrate's one justified isolation primitive.
+ *
+ * See `brain/decisions/0006-default-backend-rendezvous-identity.md`.
+ */
+export declare function defaultSocketName(): string;
+/**
+ * Mint a unique tmux socket name. Used by the test harness for per-test
+ * isolation (`test/harness/index.ts`). Production code should NOT mint a
+ * random socket — the CLI's cross-process discovery requires a stable
+ * rendezvous identity (see {@link defaultSocketName}).
+ */
+export declare function mintSocket(): string;
+//# sourceMappingURL=socket.d.ts.map

package/dist/backends/tmux/socket.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"socket.d.ts","sourceRoot":"","sources":["../../../src/backends/tmux/socket.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,iBAAiB,IAAI,MAAM,CAE1C;AAED;;;;;GAKG;AACH,wBAAgB,UAAU,IAAI,MAAM,CAEnC"}

package/dist/backends/tmux/socket.js

@@ -0,0 +1,31 @@
+import { randomBytes } from "node:crypto";
+/**
+ * The substrate's default tmux socket name — `"claudemux"`.
+ *
+ * Pure function (no env reads here). The bootstrap layer
+ * (`src/session/default-backend.ts`) composes the precedence:
+ *
+ *   explicit `tmuxBackend({ socket })` > `--socket` flag > `CLAUDEMUX_SOCKET` env >
+ *   `defaultSocketName()`
+ *
+ * tmux already namespaces socket files per-UID (`/tmp/tmux-$UID/claudemux`,
+ * mode 0700), so a fixed name is per-user-safe by construction. Two
+ * consumers from the same user share the same tmux server and coexist via
+ * the substrate's namespace prefix (`<ns>--<name>`) — that is the
+ * substrate's one justified isolation primitive.
+ *
+ * See `brain/decisions/0006-default-backend-rendezvous-identity.md`.
+ */
+export function defaultSocketName() {
+    return "claudemux";
+}
+/**
+ * Mint a unique tmux socket name. Used by the test harness for per-test
+ * isolation (`test/harness/index.ts`). Production code should NOT mint a
+ * random socket — the CLI's cross-process discovery requires a stable
+ * rendezvous identity (see {@link defaultSocketName}).
+ */
+export function mintSocket() {
+    return `claudemux-${randomBytes(6).toString("hex")}`;
+}
+//# sourceMappingURL=socket.js.map

package/dist/backends/tmux/socket.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"socket.js","sourceRoot":"","sources":["../../../src/backends/tmux/socket.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAE1C;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,UAAU,iBAAiB;IAC/B,OAAO,WAAW,CAAC;AACrB,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,UAAU;IACxB,OAAO,aAAa,WAAW,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,KAAK,CAAC,EAAE,CAAC;AACvD,CAAC"}

package/dist/backends/types.d.ts

@@ -0,0 +1,110 @@
+/**
+ * The `Backend` seam — drives a named pane: spawn a process, send input,
+ * capture output, kill. Knows **nothing** about claude or any specific agent.
+ *
+ * This file is internal. The public surface (`src/index.ts`) does NOT
+ * re-export `Backend`, `SendPayload`, or `BackendEvent`.
+ *
+ * Two input primitives only — `paste` (multi-line safe) and `key` (named).
+ * There is no `sendRawText`: multi-line input that would submit per-line
+ * cannot leak around this seam.
+ */
+/** A single backend-issued operation observable via `Backend.onCommand`. */
+export interface BackendEvent {
+    /** Unix epoch milliseconds when the command was issued. */
+    ts: number;
+    /** The argv the substrate spawned. */
+    argv: string[];
+    /** Wall-clock milliseconds the command took. */
+    durationMs: number;
+    /** Process exit code. */
+    exit: number;
+    /** Captured stdout, if any. */
+    stdout?: string;
+    /** Captured stderr, if any. */
+    stderr?: string;
+}
+/**
+ * The shape of one backend write. Multi-line input rides as `paste`;
+ * submission and dialog responses ride as `key`.
+ */
+export type SendPayload = {
+    kind: "paste";
+    text: string;
+} | {
+    kind: "key";
+    key: "Enter" | "Escape" | "1" | "2" | "3" | "y" | "n";
+};
+/**
+ * Identifier for one named session. Every Backend method takes this shape
+ * so the backend owns its own naming convention — callers never construct
+ * `<namespace>--<name>` or any other concrete encoding. Future backends
+ * (node-pty, CustomPaneBackend) implement the same interface and may
+ * encode the pair differently internally.
+ */
+export interface SessionRef {
+    namespace: string;
+    name: string;
+}
+/**
+ * Format a {@link SessionRef} as the human-readable label used in error
+ * messages and observability output. The substrate's public label format
+ * is `<namespace>/<name>` — distinct from any backend's internal encoding
+ * (the tmux backend, for example, uses `<namespace>--<name>` internally).
+ *
+ * One place; one format; rename here if the user-facing label ever changes
+ * (e.g. to `<namespace>:<name>`).
+ */
+export declare function formatSessionLabel(ref: SessionRef): string;
+/**
+ * The substrate's view of one named pane in a backend. Implemented by
+ * `src/backends/tmux/index.ts` currently; future backends (node-pty,
+ * `CustomPaneBackend`) implement the same interface.
+ */
+export interface Backend {
+    /** The backend's short identifier (e.g. `"tmux"`). For diagnostics only. */
+    readonly id: string;
+    /** Create a named session running `cmd` + `argv` in `cwd`. */
+    spawn(o: SessionRef & {
+        cwd: string;
+        env?: Record<string, string>;
+        cmd: string;
+        argv: string[];
+    }): Promise<void>;
+    /** Kill the named session. Idempotent — kill of a missing session is success. */
+    kill(ref: SessionRef): Promise<void>;
+    /** Whether the named session is alive. */
+    exists(ref: SessionRef): Promise<boolean>;
+    /** List short session names owned by `namespace`. */
+    list(namespace: string): Promise<string[]>;
+    /** Send one payload to the named session. */
+    send(ref: SessionRef, payload: SendPayload): Promise<void>;
+    /**
+     * Return the named session's pane text.
+     * @param o.ansi — preserve escape sequences when `true`.
+     * @param o.lines — return only the bottom-N lines (default: full visible region).
+     */
+    capture(ref: SessionRef, o?: {
+        ansi?: boolean;
+        lines?: number;
+    }): Promise<string>;
+    /**
+     * Persist a small opaque string under a **session-scoped** key. The value
+     * lives and dies with the session. Used for cross-process coordination —
+     * specifically the post-submit pane fingerprint `send()` leaves for a later
+     * (possibly different-process) `wait()` to read. Backend-specific storage
+     * (the tmux backend uses a `@`-prefixed session user option); callers treat
+     * it as an opaque per-session key/value store and never depend on where it
+     * lives.
+     */
+    setSessionMeta(ref: SessionRef, key: string, value: string): Promise<void>;
+    /**
+     * Read a value previously written via {@link setSessionMeta}. Returns
+     * `undefined` when the key was never set (or the session/value is
+     * unreadable) — it is metadata, so absence is not an error.
+     */
+    getSessionMeta(ref: SessionRef, key: string): Promise<string | undefined>;
+    /** Subscribe to every backend command + result. Returns an unsubscribe fn. */
+    onCommand(handler: (e: BackendEvent) => void): () => void;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/backends/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/backends/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,4EAA4E;AAC5E,MAAM,WAAW,YAAY;IAC3B,2DAA2D;IAC3D,EAAE,EAAE,MAAM,CAAC;IACX,sCAAsC;IACtC,IAAI,EAAE,MAAM,EAAE,CAAC;IACf,gDAAgD;IAChD,UAAU,EAAE,MAAM,CAAC;IACnB,yBAAyB;IACzB,IAAI,EAAE,MAAM,CAAC;IACb,+BAA+B;IAC/B,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,+BAA+B;IAC/B,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED;;;GAGG;AACH,MAAM,MAAM,WAAW,GACnB;IAAE,IAAI,EAAE,OAAO,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,GAC/B;IAAE,IAAI,EAAE,KAAK,CAAC;IAAC,GAAG,EAAE,OAAO,GAAG,QAAQ,GAAG,GAAG,GAAG,GAAG,GAAG,GAAG,GAAG,GAAG,GAAG,GAAG,CAAA;CAAE,CAAC;AAE3E;;;;;;GAMG;AACH,MAAM,WAAW,UAAU;IACzB,SAAS,EAAE,MAAM,CAAC;IAClB,IAAI,EAAE,MAAM,CAAC;CACd;AAED;;;;;;;;GAQG;AACH,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,UAAU,GAAG,MAAM,CAE1D;AAED;;;;GAIG;AACH,MAAM,WAAW,OAAO;IACtB,4EAA4E;IAC5E,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IAEpB,8DAA8D;IAC9D,KAAK,CACH,CAAC,EAAE,UAAU,GAAG;QACd,GAAG,EAAE,MAAM,CAAC;QACZ,GAAG,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;QAC7B,GAAG,EAAE,MAAM,CAAC;QACZ,IAAI,EAAE,MAAM,EAAE,CAAC;KAChB,GACA,OAAO,CAAC,IAAI,CAAC,CAAC;IAEjB,iFAAiF;IACjF,IAAI,CAAC,GAAG,EAAE,UAAU,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAErC,0CAA0C;IAC1C,MAAM,CAAC,GAAG,EAAE,UAAU,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IAE1C,qDAAqD;IACrD,IAAI,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CAAC;IAE3C,6CAA6C;IAC7C,IAAI,CAAC,GAAG,EAAE,UAAU,EAAE,OAAO,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAE3D;;;;OAIG;IACH,OAAO,CAAC,GAAG,EAAE,UAAU,EAAE,CAAC,CAAC,EAAE;QAAE,IAAI,CAAC,EAAE,OAAO,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;IAElF;;;;;;;;OAQG;IACH,cAAc,CAAC,GAAG,EAAE,UAAU,EAAE,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAE3E;;;;OAIG;IACH,cAAc,CAAC,GAAG,EAAE,UAAU,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAAC;IAE1E,8EAA8E;IAC9E,SAAS,CAAC,OAAO,EAAE,CAAC,CAAC,EAAE,YAAY,KAAK,IAAI,GAAG,MAAM,IAAI,CAAC;CAC3D"}

package/dist/backends/types.js

@@ -0,0 +1,24 @@
+/**
+ * The `Backend` seam — drives a named pane: spawn a process, send input,
+ * capture output, kill. Knows **nothing** about claude or any specific agent.
+ *
+ * This file is internal. The public surface (`src/index.ts`) does NOT
+ * re-export `Backend`, `SendPayload`, or `BackendEvent`.
+ *
+ * Two input primitives only — `paste` (multi-line safe) and `key` (named).
+ * There is no `sendRawText`: multi-line input that would submit per-line
+ * cannot leak around this seam.
+ */
+/**
+ * Format a {@link SessionRef} as the human-readable label used in error
+ * messages and observability output. The substrate's public label format
+ * is `<namespace>/<name>` — distinct from any backend's internal encoding
+ * (the tmux backend, for example, uses `<namespace>--<name>` internally).
+ *
+ * One place; one format; rename here if the user-facing label ever changes
+ * (e.g. to `<namespace>:<name>`).
+ */
+export function formatSessionLabel(ref) {
+    return `${ref.namespace}/${ref.name}`;
+}
+//# sourceMappingURL=types.js.map

package/dist/backends/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/backends/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAsCH;;;;;;;;GAQG;AACH,MAAM,UAAU,kBAAkB,CAAC,GAAe;IAChD,OAAO,GAAG,GAAG,CAAC,SAAS,IAAI,GAAG,CAAC,IAAI,EAAE,CAAC;AACxC,CAAC"}

package/dist/cli/ask.d.ts

@@ -0,0 +1,11 @@
+import { type CommonOpts, type PatienceCliOpts } from "./context.js";
+export interface AskCliOpts extends CommonOpts, PatienceCliOpts {
+}
+/**
+ * `claudemux ask <name> <text>` — the Q&A round-trip face: send → wait → read.
+ * Prints the {@link AskResult} as JSON (`outcome`, `messages`, `cursor`). Exit
+ * code is 0 on `completed`, non-zero otherwise, so a shell caller can gate
+ * without parsing. `text` = `"-"` reads the prompt from stdin.
+ */
+export declare function askCli(name: string, text: string, opts?: AskCliOpts): Promise<void>;
+//# sourceMappingURL=ask.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"ask.d.ts","sourceRoot":"","sources":["../../src/cli/ask.ts"],"names":[],"mappings":"AACA,OAAO,EACL,KAAK,UAAU,EACf,KAAK,eAAe,EAIrB,MAAM,cAAc,CAAC;AAEtB,MAAM,WAAW,UAAW,SAAQ,UAAU,EAAE,eAAe;CAAG;AAElE;;;;;GAKG;AACH,wBAAsB,MAAM,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,GAAE,UAAe,GAAG,OAAO,CAAC,IAAI,CAAC,CAM7F"}

package/dist/cli/ask.js

@@ -0,0 +1,17 @@
+import { ask } from "../compose.js";
+import { handleFor, patienceOpts, readStdin, } from "./context.js";
+/**
+ * `claudemux ask <name> <text>` — the Q&A round-trip face: send → wait → read.
+ * Prints the {@link AskResult} as JSON (`outcome`, `messages`, `cursor`). Exit
+ * code is 0 on `completed`, non-zero otherwise, so a shell caller can gate
+ * without parsing. `text` = `"-"` reads the prompt from stdin.
+ */
+export async function askCli(name, text, opts = {}) {
+    const body = text === "-" ? await readStdin() : text;
+    const handle = await handleFor({ ...opts, name });
+    const result = await ask(handle, body, patienceOpts(opts));
+    process.stdout.write(`${JSON.stringify(result)}\n`);
+    if (result.outcome.kind !== "completed")
+        process.exitCode = 1;
+}
+//# sourceMappingURL=ask.js.map

package/dist/cli/ask.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ask.js","sourceRoot":"","sources":["../../src/cli/ask.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,GAAG,EAAE,MAAM,eAAe,CAAC;AACpC,OAAO,EAGL,SAAS,EACT,YAAY,EACZ,SAAS,GACV,MAAM,cAAc,CAAC;AAItB;;;;;GAKG;AACH,MAAM,CAAC,KAAK,UAAU,MAAM,CAAC,IAAY,EAAE,IAAY,EAAE,OAAmB,EAAE;IAC5E,MAAM,IAAI,GAAG,IAAI,KAAK,GAAG,CAAC,CAAC,CAAC,MAAM,SAAS,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC;IACrD,MAAM,MAAM,GAAG,MAAM,SAAS,CAAC,EAAE,GAAG,IAAI,EAAE,IAAI,EAAE,CAAC,CAAC;IAClD,MAAM,MAAM,GAAG,MAAM,GAAG,CAAC,MAAM,EAAE,IAAI,EAAE,YAAY,CAAC,IAAI,CAAC,CAAC,CAAC;IAC3D,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,GAAG,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;IACpD,IAAI,MAAM,CAAC,OAAO,CAAC,IAAI,KAAK,WAAW;QAAE,OAAO,CAAC,QAAQ,GAAG,CAAC,CAAC;AAChE,CAAC"}

package/dist/cli/capture.d.ts

@@ -0,0 +1,8 @@
+import { type CommonOpts } from "./context.js";
+export interface CaptureCliOpts extends CommonOpts {
+    ansi?: boolean;
+    lines?: number;
+}
+/** `claudemux capture <name>` — print the pane text (optionally with ANSI). */
+export declare function captureCli(name: string, opts?: CaptureCliOpts): Promise<void>;
+//# sourceMappingURL=capture.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"capture.d.ts","sourceRoot":"","sources":["../../src/cli/capture.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,UAAU,EAAa,MAAM,cAAc,CAAC;AAE1D,MAAM,WAAW,cAAe,SAAQ,UAAU;IAChD,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,+EAA+E;AAC/E,wBAAsB,UAAU,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,GAAE,cAAmB,GAAG,OAAO,CAAC,IAAI,CAAC,CAQvF"}

package/dist/cli/capture.js

@@ -0,0 +1,15 @@
+import { handleFor } from "./context.js";
+/** `claudemux capture <name>` — print the pane text (optionally with ANSI). */
+export async function captureCli(name, opts = {}) {
+    const handle = await handleFor({ ...opts, name });
+    const captureOpts = {};
+    if (opts.ansi === true)
+        captureOpts.ansi = true;
+    if (opts.lines !== undefined)
+        captureOpts.lines = opts.lines;
+    const text = await handle.capture(captureOpts);
+    process.stdout.write(text);
+    if (!text.endsWith("\n"))
+        process.stdout.write("\n");
+}
+//# sourceMappingURL=capture.js.map

package/dist/cli/capture.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"capture.js","sourceRoot":"","sources":["../../src/cli/capture.ts"],"names":[],"mappings":"AAAA,OAAO,EAAmB,SAAS,EAAE,MAAM,cAAc,CAAC;AAO1D,+EAA+E;AAC/E,MAAM,CAAC,KAAK,UAAU,UAAU,CAAC,IAAY,EAAE,OAAuB,EAAE;IACtE,MAAM,MAAM,GAAG,MAAM,SAAS,CAAC,EAAE,GAAG,IAAI,EAAE,IAAI,EAAE,CAAC,CAAC;IAClD,MAAM,WAAW,GAAuC,EAAE,CAAC;IAC3D,IAAI,IAAI,CAAC,IAAI,KAAK,IAAI;QAAE,WAAW,CAAC,IAAI,GAAG,IAAI,CAAC;IAChD,IAAI,IAAI,CAAC,KAAK,KAAK,SAAS;QAAE,WAAW,CAAC,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC;IAC7D,MAAM,IAAI,GAAG,MAAM,MAAM,CAAC,OAAO,CAAC,WAAW,CAAC,CAAC;IAC/C,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;IAC3B,IAAI,CAAC,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC;QAAE,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;AACvD,CAAC"}

package/dist/cli/context.d.ts

@@ -0,0 +1,71 @@
+import type { AgentDef } from "../agents/types.js";
+import type { Backend } from "../backends/types.js";
+import type { ReadyOpts, SessionHandle } from "../types.js";
+/**
+ * Options to **locate** a session — every verb takes these. Mirrors the
+ * `common()` helper in `main.ts` (namespace + socket, no agent).
+ */
+export interface RefOpts {
+    namespace?: string;
+    /**
+     * Explicit socket override. Precedence:
+     *   `--socket <name>` flag > `CLAUDEMUX_SOCKET` env > default `"claudemux"`.
+     */
+    socket?: string;
+}
+/**
+ * {@link RefOpts} plus the agent — for verbs that build a session handle.
+ * Mirrors the `withAgent()` helper. Registry verbs (kill/list/exists) take only
+ * {@link RefOpts}, so the two types track the two helpers exactly.
+ */
+export interface CommonOpts extends RefOpts {
+    agent?: string;
+}
+/**
+ * Resolve the agent by short name. Only `claude` is supported currently;
+ * any other value exits with a typed error message.
+ */
+export declare function resolveAgent(name: string | undefined): AgentDef;
+/** Resolve the namespace, applying the substrate's default. */
+export declare function resolveNamespace(name: string | undefined): string;
+/**
+ * Resolve the backend for this CLI invocation. If `--socket` was passed
+ * (and is non-empty after trimming), builds a fresh backend on the
+ * resolved socket; otherwise returns the process-wide shared default
+ * (which itself honors `CLAUDEMUX_SOCKET`). The trim → gate-and-return
+ * consistency lives in `resolveSocket` so a padded `--socket ' x '` lands
+ * on the same server as `--socket x`.
+ */
+export declare function backend(opts?: RefOpts): Backend;
+/**
+ * Attach a session handle for the CLI's per-invocation reattach. Delegates to
+ * the library {@link adopt} — the ONE owner of "re-attach to a running session"
+ * — so the CLI **recovers the agentSessionId** (and thus can locate the
+ * transcript + hook rendezvous) instead of reimplementing a weaker attach.
+ * Async because recovery reads session metadata.
+ *
+ * @throws `SessionGone` if the named session is not alive (adopt's contract) —
+ *   the CLI surfaces it as a typed, no-tmux-leak error.
+ */
+export declare function handleFor(o: CommonOpts & {
+    name: string;
+}): Promise<SessionHandle>;
+/** Wait-patience flags shared by `wait` and `ask`. */
+export interface PatienceCliOpts {
+    /** `--timeout-ms` — wall-clock cap (maps to {@link ReadyOpts.maxMs}). */
+    timeoutMs?: number;
+    /** `--idle-ms` — no-progress cap (maps to {@link ReadyOpts.idleMs}). */
+    idleMs?: number;
+}
+/**
+ * Build the library's {@link ReadyOpts} from CLI patience flags. The library
+ * imposes **no** default patience; the CLI is a *consumer* and supplies its own
+ * so a shell `wait`/`ask` can't hang forever: if neither bound is given it caps
+ * the wall-clock at {@link CLI_DEFAULT_MAX_MS}. `--timeout-ms` and `--idle-ms`
+ * override; passing `--idle-ms` alone opts out of the wall-clock default (the
+ * caller chose a no-progress bound deliberately).
+ */
+export declare function patienceOpts(o: PatienceCliOpts): ReadyOpts;
+/** Read all of stdin as UTF-8 — the `<text>` = `"-"` piping convention. */
+export declare function readStdin(): Promise<string>;
+//# sourceMappingURL=context.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"context.d.ts","sourceRoot":"","sources":["../../src/cli/context.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,oBAAoB,CAAC;AACnD,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,sBAAsB,CAAC;AAQpD,OAAO,KAAK,EAAE,SAAS,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAE5D;;;GAGG;AACH,MAAM,WAAW,OAAO;IACtB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;;;OAGG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED;;;;GAIG;AACH,MAAM,WAAW,UAAW,SAAQ,OAAO;IACzC,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED;;;GAGG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,SAAS,GAAG,QAAQ,CAO/D;AAED,+DAA+D;AAC/D,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG,SAAS,GAAG,MAAM,CAEjE;AAED;;;;;;;GAOG;AACH,wBAAgB,OAAO,CAAC,IAAI,GAAE,OAAY,GAAG,OAAO,CAKnD;AAED;;;;;;;;;GASG;AACH,wBAAgB,SAAS,CAAC,CAAC,EAAE,UAAU,GAAG;IAAE,IAAI,EAAE,MAAM,CAAA;CAAE,GAAG,OAAO,CAAC,aAAa,CAAC,CAOlF;AAED,sDAAsD;AACtD,MAAM,WAAW,eAAe;IAC9B,yEAAyE;IACzE,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,wEAAwE;IACxE,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAKD;;;;;;;GAOG;AACH,wBAAgB,YAAY,CAAC,CAAC,EAAE,eAAe,GAAG,SAAS,CAM1D;AAED,2EAA2E;AAC3E,wBAAgB,SAAS,IAAI,OAAO,CAAC,MAAM,CAAC,CAU3C"}