@halfwhey/claudraband-core 0.1.0

package/dist/claude/claude.d.ts

@@ -0,0 +1,70 @@
+import type { Event } from "../wrap/event";
+import type { Wrapper } from "../wrap/wrapper";
+import { type TerminalBackend } from "../terminal";
+export interface ClaudeConfig {
+    claudeArgs: string[];
+    claudeExecutable?: string;
+    model: string;
+    permissionMode: string;
+    workingDir: string;
+    terminalBackend: TerminalBackend;
+    tmuxSession: string;
+    paneWidth: number;
+    paneHeight: number;
+}
+export declare function sessionPath(cwd: string, sessionID: string): string;
+export declare class ClaudeWrapper implements Wrapper {
+    private cfg;
+    private terminal;
+    private tailer;
+    private _claudeSessionId;
+    private _signal;
+    private abortController;
+    private eventIterable;
+    constructor(cfg: ClaudeConfig);
+    name(): string;
+    model(): string;
+    setModel(model: string): void;
+    setPermissionMode(mode: string): void;
+    /** The Claude Code session UUID used for the JSONL file. */
+    get claudeSessionId(): string;
+    start(signal: AbortSignal): Promise<void>;
+    /** Resume an existing Claude Code session by its UUID. */
+    startResume(claudeSessionId: string, signal: AbortSignal): Promise<void>;
+    /**
+     * Restart Claude Code with updated config (e.g. after a permission mode
+     * change). Stops the current terminal host and re-spawns with --resume.
+     */
+    restart(): Promise<void>;
+    private buildCmd;
+    private spawnAndTail;
+    /**
+     * Poll the terminal until Claude Code is ready to accept input.
+     * Looks for "INSERT" in the status bar, which indicates the TUI has loaded.
+     */
+    private waitForReady;
+    stop(): Promise<void>;
+    /** Disconnect without killing the process. The terminal stays alive. */
+    detach(): Promise<void>;
+    /** Check if the underlying terminal process is still running. */
+    isProcessAlive(): boolean;
+    /**
+     * Check if a Claude Code session has a live process without attaching.
+     * Only meaningful for tmux backend -- xterm processes can't outlive the CLI.
+     */
+    static hasLiveProcess(tmuxSessionName: string, claudeSessionId: string): Promise<boolean>;
+    static stopLiveProcess(tmuxSessionName: string, claudeSessionId: string): Promise<boolean>;
+    send(input: string): Promise<void>;
+    interrupt(): Promise<void>;
+    /** Capture the current visible content of the terminal. */
+    capturePane(): Promise<string>;
+    processId(): Promise<number | undefined>;
+    alive(): boolean;
+    events(): AsyncGenerator<Event>;
+}
+export interface ParsedClaudeArgs {
+    passthroughArgs: string[];
+    model?: string;
+    permissionMode?: string;
+}
+export declare function parseClaudeArgs(args: string[]): ParsedClaudeArgs;

package/dist/claude/index.d.ts

@@ -0,0 +1,9 @@
+export { ClaudeWrapper } from "./claude";
+export { sessionPath } from "./claude";
+export { parseClaudeArgs } from "./claude";
+export type { ClaudeConfig } from "./claude";
+export { resolveClaudeExecutable } from "./resolve";
+export { Tailer, parseLineEvents } from "./parser";
+export { hasPendingNativePrompt, hasPendingQuestion, parseNativePermissionPrompt, } from "./inspect";
+export { createTerminalHost, hasTmuxBinary, resolveTerminalBackend } from "../terminal";
+export type { TerminalBackend, ResolvedTerminalBackend, TerminalHost, TerminalStartOptions, } from "../terminal";

package/dist/claude/inspect.d.ts

@@ -0,0 +1,14 @@
+export interface NativePermissionPrompt {
+    question: string;
+    options: {
+        number: string;
+        label: string;
+    }[];
+}
+/**
+ * Scan a Claude Code session JSONL file for an unresolved AskUserQuestion.
+ * Returns true if the last AskUserQuestion tool_use has no matching tool_result.
+ */
+export declare function hasPendingQuestion(jsonlPath: string): Promise<boolean>;
+export declare function parseNativePermissionPrompt(paneText: string): NativePermissionPrompt | null;
+export declare function hasPendingNativePrompt(paneText: string): boolean;

package/dist/claude/parser.d.ts

@@ -0,0 +1,17 @@
+import type { Event } from "../wrap/event";
+export declare function parseLineEvents(line: string): Event[];
+export declare class Tailer {
+    private path;
+    private abortController;
+    private eventQueue;
+    private resolvers;
+    private done;
+    private startOffset;
+    constructor(path: string, startOffset?: number);
+    close(): void;
+    events(): AsyncGenerator<Event>;
+    private pushEvent;
+    private finish;
+    private emitCompleteLines;
+    private run;
+}

package/dist/claude/resolve.d.ts

@@ -0,0 +1,4 @@
+export declare function resolveClaudeExecutable(explicitPath?: string): string;
+export declare const __test: {
+    ENV_OVERRIDE: string;
+};

package/dist/index.d.ts

@@ -0,0 +1,207 @@
+import { hasPendingNativePrompt, hasPendingQuestion, parseClaudeArgs, resolveTerminalBackend, sessionPath, type TerminalBackend } from "./claude";
+import { type ResolvedTerminalBackend } from "./terminal";
+import type { Event as ClaudrabandEvent } from "./wrap/event";
+import { EventKind } from "./wrap/event";
+import type { Wrapper } from "./wrap/wrapper";
+import { type SessionOwnerRecord } from "./session-registry";
+export { EventKind };
+export { hasPendingNativePrompt };
+export { hasPendingQuestion };
+export { parseClaudeArgs };
+export { resolveTerminalBackend };
+export { sessionPath };
+export { awaitPaneIdle } from "./terminal/activity";
+export type { PaneActivityOptions, ActivityResult } from "./terminal/activity";
+export type { ClaudrabandEvent };
+export type { TerminalBackend };
+export type { ResolvedTerminalBackend };
+export type { SessionOwnerRecord };
+/** Check if a Claude Code session has a live tmux process. */
+export declare function hasLiveProcess(sessionId: string): Promise<boolean>;
+export declare function closeLiveProcess(sessionId: string): Promise<boolean>;
+export type PermissionMode = "default" | "plan" | "auto" | "acceptEdits" | "dontAsk" | "bypassPermissions";
+export type ToolKind = "read" | "edit" | "execute" | "search" | "fetch" | "think" | "other";
+export interface ClaudrabandLogger {
+    info(msg: string, ...args: unknown[]): void;
+    debug(msg: string, ...args: unknown[]): void;
+    warn(msg: string, ...args: unknown[]): void;
+    error(msg: string, ...args: unknown[]): void;
+}
+export interface ClaudrabandContentBlock {
+    type: "text";
+    text: string;
+}
+export interface ClaudrabandPermissionOption {
+    kind: "allow_once" | "reject_once";
+    optionId: string;
+    name: string;
+    textInput?: boolean;
+}
+export interface ClaudrabandPermissionRequest {
+    source: "native_prompt" | "ask_user_question";
+    sessionId: string;
+    toolCallId: string;
+    title: string;
+    kind: ToolKind;
+    content: ClaudrabandContentBlock[];
+    options: ClaudrabandPermissionOption[];
+}
+export type ClaudrabandPermissionDecision = {
+    outcome: "selected";
+    optionId: string;
+} | {
+    outcome: "text";
+    text: string;
+} | {
+    outcome: "deferred";
+} | {
+    outcome: "cancelled";
+};
+export interface ClaudrabandOptions {
+    cwd?: string;
+    claudeArgs?: string[];
+    claudeExecutable?: string;
+    model?: string;
+    permissionMode?: PermissionMode;
+    allowTextResponses?: boolean;
+    terminalBackend?: TerminalBackend;
+    paneWidth?: number;
+    paneHeight?: number;
+    logger?: ClaudrabandLogger;
+    onPermissionRequest?: (request: ClaudrabandPermissionRequest) => Promise<ClaudrabandPermissionDecision>;
+    sessionOwner?: SessionOwnerRecord;
+}
+export interface SessionSummary {
+    sessionId: string;
+    cwd: string;
+    title?: string;
+    createdAt: string;
+    updatedAt?: string;
+    backend: ResolvedTerminalBackend;
+    source: "live" | "history";
+    alive: boolean;
+    reattachable: boolean;
+    owner: SessionOwnerRecord;
+}
+export interface PromptResult {
+    stopReason: "end_turn" | "cancelled";
+}
+export interface ClaudrabandSession {
+    readonly sessionId: string;
+    readonly cwd: string;
+    readonly backend: ResolvedTerminalBackend;
+    readonly model: string;
+    readonly permissionMode: PermissionMode;
+    events(): AsyncIterable<ClaudrabandEvent>;
+    prompt(text: string): Promise<PromptResult>;
+    awaitTurn(): Promise<PromptResult>;
+    sendAndAwaitTurn(text: string): Promise<PromptResult>;
+    send(text: string): Promise<void>;
+    interrupt(): Promise<void>;
+    stop(): Promise<void>;
+    /** Disconnect without killing the process. */
+    detach(): Promise<void>;
+    isProcessAlive(): boolean;
+    capturePane(): Promise<string>;
+    hasPendingInput(): Promise<{
+        pending: boolean;
+        source: "none" | "terminal";
+    }>;
+    setModel(model: string): Promise<void>;
+    setPermissionMode(mode: PermissionMode): Promise<void>;
+    flushEvents(): Promise<void>;
+}
+export interface Claudraband {
+    startSession(options?: ClaudrabandOptions): Promise<ClaudrabandSession>;
+    resumeSession(sessionId: string, options?: ClaudrabandOptions): Promise<ClaudrabandSession>;
+    listSessions(cwd?: string): Promise<SessionSummary[]>;
+    inspectSession(sessionId: string, cwd?: string): Promise<SessionSummary | null>;
+    closeSession(sessionId: string): Promise<boolean>;
+    replaySession(sessionId: string, cwd: string): Promise<ClaudrabandEvent[]>;
+}
+export declare const MODEL_OPTIONS: readonly [{
+    readonly value: "haiku";
+    readonly name: "Haiku";
+    readonly description: "Fast and lightweight";
+}, {
+    readonly value: "sonnet";
+    readonly name: "Sonnet";
+    readonly description: "Balanced speed and intelligence";
+}, {
+    readonly value: "opus";
+    readonly name: "Opus";
+    readonly description: "Most capable";
+}];
+export declare const PERMISSION_MODES: readonly [{
+    readonly id: "default";
+    readonly name: "Default";
+    readonly description: "Ask before tool use";
+}, {
+    readonly id: "plan";
+    readonly name: "Plan";
+    readonly description: "Plan-only mode, no edits";
+}, {
+    readonly id: "auto";
+    readonly name: "Auto";
+    readonly description: "Bypass permission checks";
+}, {
+    readonly id: "acceptEdits";
+    readonly name: "Accept Edits";
+    readonly description: "Auto-accept file edits";
+}, {
+    readonly id: "dontAsk";
+    readonly name: "Don't Ask";
+    readonly description: "Skip all confirmations";
+}, {
+    readonly id: "bypassPermissions";
+    readonly name: "Bypass Permissions";
+    readonly description: "Dangerously Skip Permissions";
+}];
+export declare const TERMINAL_BACKENDS: readonly [{
+    readonly id: "auto";
+    readonly name: "Auto";
+    readonly description: "Prefer tmux, then fall back to headless xterm";
+}, {
+    readonly id: "tmux";
+    readonly name: "tmux";
+    readonly description: "Run Claude Code inside a tmux session";
+}, {
+    readonly id: "xterm";
+    readonly name: "xterm";
+    readonly description: "Run Claude Code in a headless xterm-backed PTY";
+}];
+interface AskUserQuestionOption {
+    label: string;
+    description: string;
+}
+interface AskUserQuestionItem {
+    question: string;
+    header: string;
+    multiSelect: boolean;
+    options: AskUserQuestionOption[];
+}
+export declare function createClaudraband(defaults?: ClaudrabandOptions): Claudraband;
+interface SessionWrapper extends Wrapper {
+    capturePane(): Promise<string>;
+    setModel(model: string): void;
+    setPermissionMode(mode: string): void;
+    restart(): Promise<void>;
+    detach(): Promise<void>;
+    isProcessAlive(): boolean;
+    processId(): Promise<number | undefined>;
+}
+export declare const __test: {
+    buildAskUserQuestionOptions: typeof buildAskUserQuestionOptions;
+    createSession(wrapper: SessionWrapper, options?: {
+        sessionId?: string;
+        cwd?: string;
+        backend?: ResolvedTerminalBackend;
+        model?: string;
+        permissionMode?: PermissionMode;
+        allowTextResponses?: boolean;
+        logger?: ClaudrabandLogger;
+        onPermissionRequest?: ClaudrabandOptions["onPermissionRequest"];
+        lifetime?: AbortController;
+    }): ClaudrabandSession;
+};
+declare function buildAskUserQuestionOptions(question: AskUserQuestionItem, allowTextResponses?: boolean): ClaudrabandPermissionOption[];