@halfwhey/claudraband 0.1.0

package/dist/session-registry.d.ts

@@ -0,0 +1,46 @@
+import type { ResolvedTerminalBackend } from "./terminal";
+export interface LocalSessionOwnerRecord {
+    kind: "local";
+    pid?: number;
+}
+export interface DaemonSessionOwnerRecord {
+    kind: "daemon";
+    serverUrl: string;
+    serverPid?: number;
+    serverInstanceId: string;
+}
+export type SessionOwnerRecord = LocalSessionOwnerRecord | DaemonSessionOwnerRecord;
+export interface SessionRecord {
+    version: 1;
+    sessionId: string;
+    cwd: string;
+    backend: ResolvedTerminalBackend;
+    title?: string;
+    createdAt: string;
+    updatedAt: string;
+    lastKnownAlive: boolean;
+    reattachable: boolean;
+    transcriptPath?: string;
+    owner: SessionOwnerRecord;
+}
+export interface KnownSessionRecord {
+    version: 1;
+    sessionId: string;
+    cwd: string;
+    backend: ResolvedTerminalBackend;
+    title?: string;
+    createdAt: string;
+    updatedAt: string;
+    transcriptPath?: string;
+}
+export declare function ensureSessionRegistry(): Promise<void>;
+export declare function readSessionRecord(sessionId: string): Promise<SessionRecord | null>;
+export declare function listSessionRecords(): Promise<SessionRecord[]>;
+export declare function readKnownSessionRecord(sessionId: string): Promise<KnownSessionRecord | null>;
+export declare function listKnownSessionRecords(): Promise<KnownSessionRecord[]>;
+export declare function writeSessionRecord(record: SessionRecord): Promise<void>;
+export declare function writeKnownSessionRecord(record: KnownSessionRecord): Promise<void>;
+export declare function deleteSessionRecord(sessionId: string): Promise<void>;
+export declare function deleteKnownSessionRecord(sessionId: string): Promise<void>;
+export declare function normalizeServerUrl(server: string): string;
+export declare function isPidAlive(pid?: number): boolean;

package/dist/terminal/activity.d.ts

@@ -0,0 +1,23 @@
+export interface PaneActivityOptions {
+    /** Milliseconds between captures. Default: 250 */
+    intervalMs?: number;
+    /** Number of consecutive identical captures required to declare idle. Default: 3 */
+    stableCount?: number;
+    /** Maximum wait time in ms before giving up. Default: 60_000 */
+    timeoutMs?: number;
+    /** AbortSignal for cancellation. */
+    signal?: AbortSignal;
+}
+export type ActivityResult = "idle" | "timeout" | "aborted";
+/**
+ * Poll `capture()` until the pane content is stable for `stableCount`
+ * consecutive intervals. Backend-agnostic: works for tmux (capturePane)
+ * and xterm (serialize) alike.
+ *
+ * Returns:
+ * - `"idle"` when the pane has not changed for the required number of
+ *   consecutive captures
+ * - `"timeout"` if `timeoutMs` elapses before stability is reached
+ * - `"aborted"` if the provided `signal` is aborted
+ */
+export declare function awaitPaneIdle(capture: () => Promise<string>, options?: PaneActivityOptions): Promise<ActivityResult>;

package/dist/terminal/index.d.ts

@@ -0,0 +1,82 @@
+import type { PaneActivityOptions, ActivityResult } from "./activity";
+export type TerminalBackend = "auto" | "tmux" | "xterm";
+export type ResolvedTerminalBackend = Exclude<TerminalBackend, "auto">;
+export type XtermTransportKind = "node-pty" | "bun-terminal";
+export interface TerminalStartOptions {
+    cwd: string;
+    cols: number;
+    rows: number;
+    signal: AbortSignal;
+}
+export interface TerminalHost {
+    readonly backend: ResolvedTerminalBackend;
+    start(command: string[], options: TerminalStartOptions): Promise<void>;
+    stop(): Promise<void>;
+    /** Disconnect without killing the process. For tmux the window stays alive. */
+    detach(): Promise<void>;
+    /**
+     * Reattach to an existing terminal by window name (tmux) or id.
+     * Returns true if an existing process was found, false otherwise.
+     */
+    reattach(windowName: string): Promise<boolean>;
+    send(input: string): Promise<void>;
+    interrupt(): Promise<void>;
+    capture(): Promise<string>;
+    /** Poll capture() until the pane content stabilizes. */
+    awaitIdle(options?: PaneActivityOptions): Promise<ActivityResult>;
+    alive(): boolean;
+    processId(): Promise<number | undefined>;
+}
+export interface CreateTerminalHostOptions {
+    backend: TerminalBackend;
+    tmuxSessionName: string;
+    tmuxWindowName: string;
+}
+export interface CreateTerminalBackendDriverOptions {
+    backend: TerminalBackend;
+    tmuxSessionName: string;
+}
+export interface LiveTerminalSessionSummary {
+    sessionId: string;
+    cwd?: string;
+    updatedAt?: string;
+    pid?: number;
+}
+export interface TerminalBackendDriver {
+    readonly backend: ResolvedTerminalBackend;
+    createHost(windowName: string): TerminalHost;
+    listLiveSessions(): Promise<LiveTerminalSessionSummary[]>;
+    hasLiveSession(sessionId: string): Promise<boolean>;
+    closeLiveSession(sessionId: string): Promise<boolean>;
+    supportsLiveReconnect(): boolean;
+}
+type TmuxDetector = () => boolean;
+type BunRuntimeDetector = () => boolean;
+export declare function hasTmuxBinary(): boolean;
+export declare function hasBunTerminalRuntime(): boolean;
+export declare function resolveXtermTransportKind(detectBunRuntime?: BunRuntimeDetector): XtermTransportKind;
+export declare function resolveTerminalBackend(backend: TerminalBackend, detectTmux?: TmuxDetector): ResolvedTerminalBackend;
+export declare function createTerminalHost(options: CreateTerminalHostOptions): TerminalHost;
+export declare function createTerminalBackendDriver(options: CreateTerminalBackendDriverOptions): TerminalBackendDriver;
+declare class XtermTerminalHost implements TerminalHost {
+    readonly backend: "xterm";
+    private transport;
+    private terminal;
+    private serializeAddon;
+    private outputDrain;
+    private exited;
+    start(command: string[], options: TerminalStartOptions): Promise<void>;
+    stop(): Promise<void>;
+    detach(): Promise<void>;
+    reattach(_windowName: string): Promise<boolean>;
+    send(input: string): Promise<void>;
+    interrupt(): Promise<void>;
+    capture(): Promise<string>;
+    awaitIdle(options?: PaneActivityOptions): Promise<ActivityResult>;
+    alive(): boolean;
+    processId(): Promise<number | undefined>;
+}
+export declare const __test: {
+    createXtermTerminalHost(): XtermTerminalHost;
+};
+export {};

package/dist/tmuxctl/index.d.ts

@@ -0,0 +1,2 @@
+export { Session, killSession, hasSession, listWindows } from "./tmux";
+export type { CaptureOpts, TmuxWindowSummary } from "./tmux";

package/dist/tmuxctl/tmux.d.ts

@@ -0,0 +1,39 @@
+import type { PaneActivityOptions, ActivityResult } from "../terminal/activity";
+export interface TmuxWindowSummary {
+    windowId: string;
+    paneId: string;
+    windowName: string;
+    paneCurrentPath?: string;
+    windowActivity?: string;
+    panePid?: number;
+}
+export declare function hasSession(name: string): boolean;
+export declare function killSession(name: string): Promise<void>;
+export declare function listWindows(name: string): Promise<TmuxWindowSummary[]>;
+export interface CaptureOpts {
+    withEscapes?: boolean;
+    includeScrollback?: boolean;
+}
+export declare class Session {
+    readonly name: string;
+    readonly command: string[];
+    readonly windowId: string;
+    readonly paneId: string;
+    private constructor();
+    static newSession(name: string, width: number, height: number, workingDir: string, command: string[], windowName: string): Promise<Session>;
+    /**
+     * Find an existing tmux window by session name and window name.
+     * Returns a Session if the window is alive, null otherwise.
+     */
+    static find(sessionName: string, windowName: string): Promise<Session | null>;
+    kill(): Promise<void>;
+    get isAlive(): boolean;
+    resize(width: number, height: number): Promise<void>;
+    sendKeys(input: string): Promise<void>;
+    sendLine(input: string): Promise<void>;
+    sendSpecial(...keys: string[]): Promise<void>;
+    interrupt(): Promise<void>;
+    capturePane(opts?: CaptureOpts): Promise<string>;
+    awaitIdle(options?: PaneActivityOptions): Promise<ActivityResult>;
+    panePID(): Promise<number>;
+}

package/dist/wrap/event.d.ts

@@ -0,0 +1,24 @@
+export declare enum EventKind {
+    UserMessage = "user_message",
+    AssistantText = "assistant_text",
+    AssistantThinking = "assistant_thinking",
+    ToolCall = "tool_call",
+    ToolResult = "tool_result",
+    System = "system",
+    Error = "error",
+    SessionStart = "session_start",
+    TurnStart = "turn_start",
+    TurnEnd = "turn_end"
+}
+export interface Event {
+    kind: EventKind;
+    time: Date;
+    text: string;
+    toolName: string;
+    toolID: string;
+    toolInput: string;
+    role: string;
+}
+export declare function makeEvent(partial: Partial<Event> & {
+    kind: EventKind;
+}): Event;

package/dist/wrap/index.d.ts

@@ -0,0 +1,3 @@
+export { EventKind, makeEvent } from "./event";
+export type { Event } from "./event";
+export type { Wrapper } from "./wrapper";

package/dist/wrap/wrapper.d.ts

@@ -0,0 +1,11 @@
+import type { Event } from "./event";
+export interface Wrapper {
+    name(): string;
+    model(): string;
+    start(signal: AbortSignal): Promise<void>;
+    stop(): Promise<void>;
+    send(input: string): Promise<void>;
+    interrupt(): Promise<void>;
+    alive(): boolean;
+    events(): AsyncIterable<Event>;
+}

package/package.json

@@ -0,0 +1,58 @@
+{
+  "name": "@halfwhey/claudraband",
+  "version": "0.1.0",
+  "description": "Control the official Claude Code CLI programmatically. Use as a library, a direct CLI, an ACP server, or a persistent session daemon.",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "bin": {
+    "claudraband": "dist/bin.js",
+    "cband": "dist/bin.js"
+  },
+  "files": [
+    "dist"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "scripts": {
+    "clean": "rm -rf dist",
+    "build:bin": "bun build src/bin.ts --target node --external '@agentclientprotocol/*' --external 'node-pty' --outdir dist",
+    "build:lib": "bun build ../claudraband-core/src/index.ts --target node --external 'node-pty' --outdir dist --entry-naming index.js",
+    "build:types": "tsc -p tsconfig.build.json --emitDeclarationOnly",
+    "build": "bun run clean && bun run build:bin && bun run build:lib && bun run build:types",
+    "prepack": "bun run build",
+    "test": "bun test src",
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "@agentclientprotocol/sdk": "^0.18.0",
+    "@anthropic-ai/claude-code": "2.1.96",
+    "@xterm/addon-serialize": "^0.13.0",
+    "@xterm/headless": "^5.5.0"
+  },
+  "optionalDependencies": {
+    "node-pty": "^1.0.0"
+  },
+  "devDependencies": {
+    "@types/bun": "^1.2.0",
+    "@types/node": "^24.6.0",
+    "typescript": "^5.8.0"
+  },
+  "keywords": [
+    "claude",
+    "claude-code",
+    "acp",
+    "agent",
+    "cli",
+    "tmux"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/halfwhey/claudraband"
+  }
+}