agent-sh 0.15.0 → 0.15.2

package/src/shell/shell.ts

@@ -0,0 +1,414 @@
+import * as fs from "fs";
+import * as os from "os";
+import * as pty from "node-pty";
+import type { EventBus } from "../core/event-bus.js";
+import { InputHandler, type InputContext } from "./input-handler.js";
+import { OutputParser } from "./output-parser.js";
+import { getSettings } from "../core/settings.js";
+import { clearOpost } from "../utils/tty.js";
+import { processTerminal, surfaceFromTerminal, type Terminal } from "./terminal.js";
+import { TuiInputView } from "./tui-input-view.js";
+import {
+  pickStrategy,
+  FALLBACK_STRATEGY,
+  SUPPORTED_SHELL_NAMES,
+  type ShellStrategy,
+} from "./strategies/index.js";
+
+/* eslint-disable @typescript-eslint/no-explicit-any */
+export interface ShellHandlers {
+  define: (name: string, fn: (...args: any[]) => any) => void;
+  call: (name: string, ...args: any[]) => any;
+}
+
+/**
+ * A claim on the shell's stdout-mute state. Acquire from shell.acquire*,
+ * pair with release() in a try/finally. Token-shape forces symmetry —
+ * the only way to influence the gate is to hold and release a scope.
+ */
+export interface ShellScope {
+  readonly reason: string;
+  release(): void;
+}
+
+export class Shell implements InputContext {
+  private ptyProcess: pty.IPty;
+  private bus: EventBus;
+  private handlers: ShellHandlers;
+  private inputHandler: InputHandler;
+  private outputParser: OutputParser;
+  private terminal: Terminal;
+  private inputDispose: (() => void) | null = null;
+  // hardMute is unconditional (overlay compositing); softMute is overridable
+  // by unmute (terminal_keys, permission UI). Gate: hard wins; otherwise
+  // muted iff softMute held without an unmute.
+  private hardMuteScopes = new Set<ShellScope>();
+  private softMuteScopes = new Set<ShellScope>();
+  private unmuteScopes = new Set<ShellScope>();
+  private pendingEchoSkips = 0;
+  private agentActive = false;
+  private strategy: ShellStrategy;
+  private tmpDir?: string;
+
+  constructor(opts: {
+    bus: EventBus;
+    handlers: ShellHandlers;
+    onShowAgentInfo?: () => { info: string; model?: string };
+    cols: number;
+    rows: number;
+    shell: string;
+    cwd: string;
+    instanceId: string;
+    terminal?: Terminal;
+  }) {
+    this.terminal = opts.terminal ?? processTerminal();
+
+    // Build environment — filter out undefined values (node-pty's native
+    // posix_spawnp fails if any env value is undefined)
+    const env: Record<string, string> = {};
+    for (const [k, v] of Object.entries(process.env)) {
+      if (v !== undefined) env[k] = v;
+    }
+    env.AGENT_SH = "1";
+
+    // Spawn the user's shell with their full config (aliases, plugins, PATH,
+    // completions, etc.). The core injects three invisible OSC hooks:
+    //   - OSC 7: cwd tracking (required by OutputParser)
+    //   - OSC 9999: prompt start marker (command boundary detection)
+    //   - OSC 9998: prompt end marker (bracketed prompt capture)
+    // Prompt theming is left entirely to the user's shell config. Per-shell
+    // rc-file generation lives in src/shell/strategies/.
+    const matched = pickStrategy(opts.shell);
+    if (!matched) {
+      console.warn(
+        `Warning: agent-sh only supports ${SUPPORTED_SHELL_NAMES.join(", ")}. ` +
+        `"${opts.shell}" may not work correctly — falling back to /bin/bash.`
+      );
+    }
+    this.strategy = matched ?? FALLBACK_STRATEGY;
+    const shellBin = matched ? opts.shell : "/bin/bash";
+
+    // Per-instance tag so nested agent-sh hooks don't cross-trigger.
+    const instanceTag = `id=${opts.instanceId}`;
+    const settings = getSettings();
+    const spawnConfig = this.strategy.prepareSpawn({
+      tmpDirRoot: os.tmpdir(),
+      instanceTag,
+      showIndicator: settings.promptIndicator !== false,
+      userHome: env.HOME || os.homedir(),
+      env,
+    });
+    this.tmpDir = spawnConfig.tmpDir;
+    Object.assign(env, spawnConfig.envOverrides);
+    const shellArgs = spawnConfig.args;
+
+    // The PTY will become the controlling terminal for the child shell;
+    // suspend the host terminal's input around spawn to avoid TTY contention
+    // on macOS. Headless terminals make this a no-op.
+    const suspended = this.terminal.suspendInput?.();
+
+    this.ptyProcess = pty.spawn(shellBin, shellArgs, {
+      name: "xterm-256color",
+      cols: opts.cols,
+      rows: opts.rows,
+      cwd: opts.cwd,
+      env,
+    });
+
+    suspended?.resume();
+
+    clearOpost();
+
+    this.bus = opts.bus;
+    this.handlers = opts.handlers;
+    this.outputParser = new OutputParser(opts.bus, opts.cwd, instanceTag, {
+      cleanOutput: this.strategy.cleanOutput?.bind(this.strategy),
+    });
+
+    // Ensure temp dir cleanup on abnormal exit (SIGKILL won't fire this,
+    // but it covers uncaught exceptions and normal process.exit paths)
+    if (this.tmpDir) {
+      const dir = this.tmpDir;
+      process.on("exit", () => {
+        try { fs.rmSync(dir, { recursive: true, force: true }); } catch {}
+      });
+    }
+
+    this.inputHandler = new InputHandler({
+      ctx: this,
+      bus: opts.bus,
+      handlers: opts.handlers,
+      onShowAgentInfo: opts.onShowAgentInfo ?? (() => ({ info: "" })),
+      view: new TuiInputView(surfaceFromTerminal(this.terminal)),
+    });
+
+    this.setupOutput();
+    this.setupInput();
+    this.setupAgentLifecycle();
+
+    // Allow extensions to inject raw keystrokes into the PTY
+    this.bus.on("shell:pty-write", ({ data }) => {
+      this.ptyProcess.write(data);
+    });
+
+    // Allow extensions to resize the PTY (sends SIGWINCH to child)
+    this.bus.on("shell:pty-resize", ({ cols, rows }) => {
+      this.ptyProcess.resize(cols, rows);
+    });
+
+    this.bus.on("shell:host-write", ({ data }) => {
+      this.terminal.write(data);
+    });
+
+    // Compat shims for the bus-event API. shell:stdout-hold maps to hard
+    // mute so terminal_keys' stdout-show can't paint through the overlay.
+    let holdRefcount = 0;
+    let holdScope: ShellScope | null = null;
+    this.bus.on("shell:stdout-hold", () => {
+      if (holdRefcount === 0) holdScope = this.acquireHardMute("bus:stdout-hold");
+      holdRefcount++;
+    });
+    this.bus.on("shell:stdout-release", () => {
+      if (holdRefcount === 0) return;
+      holdRefcount--;
+      if (holdRefcount === 0) { holdScope?.release(); holdScope = null; }
+    });
+
+    let showRefcount = 0;
+    let showScope: ShellScope | null = null;
+    this.bus.on("shell:stdout-show", () => {
+      if (showRefcount === 0) showScope = this.acquireUnmute("bus:stdout-show");
+      showRefcount++;
+    });
+    this.bus.on("shell:stdout-hide", () => {
+      if (showRefcount === 0) return;
+      showRefcount--;
+      if (showRefcount === 0) { showScope?.release(); showScope = null; }
+    });
+  }
+
+  // ── Scope-based gating ─────────────────────────────────────
+
+  /** Compositing-layer claim — overrides any unmute. */
+  acquireHardMute(reason: string): ShellScope {
+    const scope: ShellScope = {
+      reason,
+      release: () => { this.hardMuteScopes.delete(scope); },
+    };
+    this.hardMuteScopes.add(scope);
+    return scope;
+  }
+
+  /** Agent-turn / exec-style mute — overridable by unmute. */
+  acquireMute(reason: string): ShellScope {
+    const scope: ShellScope = {
+      reason,
+      release: () => { this.softMuteScopes.delete(scope); },
+    };
+    this.softMuteScopes.add(scope);
+    return scope;
+  }
+
+  /** Force visible while held; overrides soft mutes only. */
+  acquireUnmute(reason: string): ShellScope {
+    const scope: ShellScope = {
+      reason,
+      release: () => { this.unmuteScopes.delete(scope); },
+    };
+    this.unmuteScopes.add(scope);
+    return scope;
+  }
+
+  /** Swallow the next \n-terminated chunk from PTY (one per call). */
+  skipNextLine(): void { this.pendingEchoSkips++; }
+
+  private isHostMuted(): boolean {
+    if (this.hardMuteScopes.size > 0) return true;
+    return this.softMuteScopes.size > 0 && this.unmuteScopes.size === 0;
+  }
+
+  // ── InputContext implementation (delegates to OutputParser) ──
+
+  isForegroundBusy(): boolean {
+    return this.outputParser.isForegroundBusy();
+  }
+
+  getCwd(): string {
+    return this.outputParser.getCwd();
+  }
+
+  isAgentActive(): boolean {
+    return this.agentActive;
+  }
+
+  writeToPty(data: string): void {
+    this.ptyProcess.write(data);
+  }
+
+  /**
+   * Ask the shell to redraw its own prompt in place. The escape sequence is
+   * defined per-strategy and bound in the generated rc file (zsh: ZLE widget,
+   * bash: readline redraw-current-line). When the strategy returns null we
+   * skip the in-place redraw and let freshPrompt do a heavy redraw instead.
+   */
+  redrawPrompt(): void {
+    const result = this.bus.emitPipe("shell:redraw-prompt", {
+      cwd: this.outputParser.getCwd(),
+      kind: "redraw",
+      handled: false,
+    });
+    if (result.handled) return;
+    const escape = this.strategy.redrawEscape();
+    if (escape) this.ptyProcess.write(escape);
+  }
+
+  /**
+   * Heavy redraw: send \n to PTY to trigger a full precmd → prompt cycle.
+   * Use this after agent responses where stdout has moved far from where
+   * zle expects the cursor. The blank line is acceptable as a separator.
+   *
+   * Routed through shell:redraw-prompt pipe so extensions (e.g. overlay)
+   * can suppress it by setting `handled: true`.
+   */
+  freshPrompt(): boolean {
+    const result = this.bus.emitPipe("shell:redraw-prompt", {
+      cwd: this.outputParser.getCwd(),
+      kind: "fresh",
+      handled: false,
+    });
+    if (!result.handled) {
+      this.ptyProcess.write("\n");
+      return true;
+    }
+    return false;
+  }
+
+  onCommandEntered(command: string, cwd: string): void {
+    this.outputParser.onCommandEntered(command, cwd);
+  }
+
+  // ── PTY I/O wiring ─────────────────────────────────────────
+
+  private setupOutput(): void {
+    this.ptyProcess.onData((data: string) => {
+      this.bus.emit("shell:pty-data", { raw: data });
+      this.outputParser.processData(data);
+
+      if (this.isHostMuted()) return;
+
+      if (this.pendingEchoSkips > 0) {
+        const nlIdx = data.indexOf("\n");
+        if (nlIdx === -1) return;
+        this.pendingEchoSkips--;
+        const rest = data.slice(nlIdx + 1);
+        if (rest) this.terminal.write(rest);
+        return;
+      }
+
+      this.terminal.write(data);
+    });
+  }
+
+  private setupInput(): void {
+    this.inputDispose = this.terminal.onInput((str) => {
+      this.inputHandler.handleInput(str);
+    });
+  }
+
+  /**
+   * shell:on-processing-done splits into unconditional state cleanup
+   * (release agent-turn scope) and an advisable redraw (freshPrompt).
+   * RemoteSession suppresses the redraw, never the cleanup, so soft-mute
+   * can't leak past the end of a turn even when overlays are involved.
+   */
+  private setupAgentLifecycle(): void {
+    let agentTurnScope: ShellScope | null = null;
+
+    this.handlers.define("shell:on-processing-start", () => {
+      this.agentActive = true;
+      agentTurnScope = this.acquireMute("agent-turn");
+    });
+
+    this.handlers.define("shell:on-processing-redraw", () => {
+      if (!this.inputHandler.handleProcessingDone()) {
+        if (this.freshPrompt()) this.skipNextLine();
+      }
+    });
+
+    this.handlers.define("shell:on-processing-done", () => {
+      this.agentActive = false;
+      agentTurnScope?.release();
+      agentTurnScope = null;
+      this.handlers.call("shell:on-processing-redraw");
+    });
+
+    this.bus.on("agent:processing-start", () => {
+      this.handlers.call("shell:on-processing-start");
+    });
+
+    this.bus.on("agent:processing-done", () => {
+      this.handlers.call("shell:on-processing-done");
+    });
+
+    this.bus.onPipeAsync("shell:exec-request", async (payload) => {
+      const visible = this.acquireUnmute("exec-request");
+      this.skipNextLine();
+      this.terminal.write("\r\n");
+      this.bus.emit("shell:agent-exec-start", {});
+
+      try {
+        const output = await new Promise<{ output: string; cwd: string; exitCode: number | null }>((resolve, reject) => {
+          const timeout = setTimeout(() => {
+            this.bus.off("shell:command-done", handler);
+            this.ptyProcess.write("\x03");
+            reject(new Error("Shell exec timed out after 30s"));
+          }, 30_000);
+
+          const handler = (e: { command: string; output: string; cwd: string; exitCode: number | null }) => {
+            clearTimeout(timeout);
+            this.bus.off("shell:command-done", handler);
+            resolve({ output: e.output, cwd: e.cwd, exitCode: e.exitCode });
+          };
+          this.bus.on("shell:command-done", handler);
+
+          this.outputParser.onCommandEntered(payload.command, this.outputParser.getCwd());
+          // Collapse literal newlines to spaces so the PTY receives a single-line
+          // command. Multi-line commands (e.g. git commit -m "...\n...") would
+          // cause the shell to execute prematurely, producing garbled output from
+          // syntax highlighting plugins (zsh syntax highlighting, etc).
+          const oneLine = payload.command.replace(/\n/g, " ");
+          this.ptyProcess.write(oneLine + "\r");
+        });
+
+        return { ...payload, output: output.output, cwd: output.cwd, exitCode: output.exitCode, done: true };
+      } finally {
+        visible.release();
+        this.bus.emit("shell:agent-exec-done", {});
+      }
+    });
+  }
+
+  // ── Public API (used by index.ts) ──
+
+  /** Temp directory used for shell config and sockets. */
+  getTmpDir(): string | undefined {
+    return this.tmpDir;
+  }
+
+  resize(cols: number, rows: number): void {
+    this.ptyProcess.resize(cols, rows);
+  }
+
+  onExit(callback: (e: { exitCode: number; signal?: number }) => void): void {
+    this.ptyProcess.onExit(callback);
+  }
+
+  kill(): void {
+    this.inputDispose?.();
+    this.inputDispose = null;
+    this.ptyProcess.kill();
+    if (this.tmpDir) {
+      fs.rmSync(this.tmpDir, { recursive: true, force: true });
+    }
+  }
+}

package/src/shell/strategies/bash.ts

@@ -0,0 +1,83 @@
+import * as fs from "fs";
+import * as path from "path";
+import type { ShellStrategy, PrepareSpawnOpts, ShellSpawnConfig } from "./types.js";
+
+const OSC7_CMD = 'printf "\\e]7;file://%s%s\\a" "$(hostname)" "$PWD"';
+const TITLE_CMD = 'printf "\\e]0;⚡ agent-sh: %s\\a" "${PWD/#$HOME/~}"';
+
+export const bashStrategy: ShellStrategy = {
+  name: "bash",
+
+  matches(shellPath: string): boolean {
+    return path.basename(shellPath).includes("bash");
+  },
+
+  prepareSpawn(opts: PrepareSpawnOpts): ShellSpawnConfig {
+    const { tmpDirRoot, instanceTag, showIndicator, env, userHome } = opts;
+
+    // Use --rcfile to source our wrapper, which sources the user's real
+    // bashrc then appends our hooks. No HOME override needed.
+    const tmpDir = fs.mkdtempSync(path.join(tmpDirRoot, "agent-sh-"));
+    const home = env.HOME || userHome;
+    const promptMarker = `printf "\\e]9999;${instanceTag};PROMPT\\a"`;
+
+    const lines = [
+      `[ -f "${home}/.bashrc" ] && source "${home}/.bashrc"`,
+      "",
+      "# agent-sh hooks (invisible OSC sequences for cwd + prompt detection)",
+      "# Wrapped in a function because inlining printf \"...\" into",
+      "# PROMPT_COMMAND=\"...\" breaks the outer quoting.",
+      "__agent_sh_precmd() {",
+      `  ${OSC7_CMD}`,
+      `  ${promptMarker}`,
+      ...(showIndicator ? [`  ${TITLE_CMD}`] : []),
+      "  __agent_sh_preexec_ran=0",
+      "}",
+      `PROMPT_COMMAND="\${PROMPT_COMMAND%;}"`,
+      `PROMPT_COMMAND="\${PROMPT_COMMAND:+\$PROMPT_COMMAND;}__agent_sh_precmd"`,
+      "",
+      "# Preexec hook via DEBUG trap: emit actual command text so agent-sh",
+      "# can track history-recalled and tab-completed commands accurately.",
+      "# Start latched (=1) so the trap stays inert through the rest of",
+      "# rcfile sourcing — readline/history aren't loaded yet, and the case",
+      "# + bind statements below would otherwise fire a phantom preexec with",
+      "# an empty body. __agent_sh_precmd resets it to 0 before user input.",
+      "__agent_sh_preexec_ran=1",
+      "__agent_sh_emit_preexec() {",
+      '  [[ $__agent_sh_preexec_ran == 1 ]] && return',
+      '  [[ -n $COMP_LINE ]] && return',
+      "  __agent_sh_preexec_ran=1",
+      "  local this_cmd",
+      `  this_cmd=$(HISTTIMEFORMAT='' builtin history 1 | command sed 's/^ *[0-9]* *//')`,
+      `  printf '\\e]9997;${instanceTag};%s\\a' "$this_cmd"`,
+      "}",
+      "trap '__agent_sh_emit_preexec' DEBUG",
+      "",
+      "# End-of-prompt marker: append to PS1 (\\[...\\] marks it zero-width)",
+      `case "$PS1" in *9998*) ;; *) PS1="\${PS1}\\[\\e]9998;${instanceTag};READY\\a\\]";; esac`,
+      "",
+      "# Mirrors the zsh \\e[9999~ reset-prompt widget — used by agent-sh",
+      "# to repaint the prompt in place. All keymaps so `set -o vi` works.",
+      `bind -m emacs '"\\e[9999~":redraw-current-line' 2>/dev/null`,
+      `bind -m vi-insert '"\\e[9999~":redraw-current-line' 2>/dev/null`,
+      `bind -m vi-command '"\\e[9999~":redraw-current-line' 2>/dev/null`,
+    ];
+
+    const rcPath = path.join(tmpDir, ".bashrc");
+    fs.writeFileSync(rcPath, lines.join("\n") + "\n");
+
+    return {
+      args: ["--rcfile", rcPath],
+      envOverrides: {},
+      tmpDir,
+    };
+  },
+
+  envCaptureCommand(): string {
+    return "[ -f ~/.bashrc ] && source ~/.bashrc 2>/dev/null; env -0";
+  },
+
+  redrawEscape(): string {
+    return "\x1b[9999~";
+  },
+};

package/src/shell/strategies/fish.ts

@@ -0,0 +1,77 @@
+import * as fs from "fs";
+import * as path from "path";
+import type { ShellStrategy, PrepareSpawnOpts, ShellSpawnConfig } from "./types.js";
+
+const OSC7_CMD = 'printf "\\e]7;file://%s%s\\a" (hostname) "$PWD"';
+const TITLE_CMD =
+  'printf "\\e]0;⚡ agent-sh: %s\\a" (string replace -- "$HOME" "~" "$PWD")';
+
+export const fishStrategy: ShellStrategy = {
+  name: "fish",
+
+  matches(shellPath: string): boolean {
+    return path.basename(shellPath).includes("fish");
+  },
+
+  prepareSpawn(opts: PrepareSpawnOpts): ShellSpawnConfig {
+    const { tmpDirRoot, instanceTag, showIndicator } = opts;
+
+    // Layer hooks via `-C` so they run after the user's config — our wrapper
+    // around fish_prompt needs to see the user's final definition.
+    const tmpDir = fs.mkdtempSync(path.join(tmpDirRoot, "agent-sh-"));
+    const initPath = path.join(tmpDir, "init.fish");
+    const promptMarker = `printf "\\e]9999;${instanceTag};PROMPT\\a"`;
+
+    const lines = [
+      "# agent-sh hooks (invisible OSC sequences for cwd + prompt detection)",
+      "function __agent_sh_precmd --on-event fish_prompt",
+      `  ${OSC7_CMD}`,
+      `  ${promptMarker}`,
+      ...(showIndicator ? [`  ${TITLE_CMD}`] : []),
+      "end",
+      "",
+      "# Preexec hook: emit actual command text so agent-sh can track",
+      "# history-recalled and tab-completed commands accurately",
+      "function __agent_sh_preexec --on-event fish_preexec",
+      `  printf "\\e]9997;${instanceTag};%s\\a" "$argv"`,
+      "end",
+      "",
+      "# End-of-prompt marker: wrap fish_prompt so READY fires after render",
+      "if functions -q fish_prompt",
+      "  functions --copy fish_prompt __agent_sh_orig_fish_prompt",
+      "  function fish_prompt",
+      "    __agent_sh_orig_fish_prompt",
+      `    printf "\\e]9998;${instanceTag};READY\\a"`,
+      "  end",
+      "else",
+      "  function fish_prompt",
+      "    printf '%s> ' (prompt_pwd)",
+      `    printf "\\e]9998;${instanceTag};READY\\a"`,
+      "  end",
+      "end",
+      "",
+      "# Redraw binding. fish 4 silently drops \\e[N~ outside the F-key table,",
+      "# so we use CSI-u with a private-use codepoint (U+E028) instead.",
+      "bind \\e\\[57400u 'commandline -f repaint' 2>/dev/null",
+      "bind -M insert \\e\\[57400u 'commandline -f repaint' 2>/dev/null",
+      "bind -M default \\e\\[57400u 'commandline -f repaint' 2>/dev/null",
+    ];
+
+    fs.writeFileSync(initPath, lines.join("\n") + "\n");
+
+    return {
+      args: ["-l", "-i", "-C", `source ${initPath}`],
+      envOverrides: {},
+      tmpDir,
+    };
+  },
+
+  envCaptureCommand(): string {
+    // `fish -l` already sources config.fish + conf.d, so no explicit source.
+    return "env -0";
+  },
+
+  redrawEscape(): string {
+    return "\x1b[57400u";
+  },
+};

package/src/shell/strategies/index.ts

@@ -0,0 +1,24 @@
+import { zshStrategy } from "./zsh.js";
+import { bashStrategy } from "./bash.js";
+import { fishStrategy } from "./fish.js";
+import type { ShellStrategy } from "./types.js";
+
+export type { ShellStrategy, PrepareSpawnOpts, ShellSpawnConfig } from "./types.js";
+
+const STRATEGIES: ShellStrategy[] = [zshStrategy, bashStrategy, fishStrategy];
+
+/** Strategy used when the requested shell isn't recognized. */
+export const FALLBACK_STRATEGY: ShellStrategy = bashStrategy;
+
+/** Names of supported shells, used for warning messages. */
+export const SUPPORTED_SHELL_NAMES: readonly string[] = STRATEGIES.map((s) => s.name);
+
+/**
+ * Pick the strategy that matches the given shell binary path. Returns null
+ * when no strategy claims the path — caller decides whether to warn and how
+ * to fall back (e.g. shell.ts swaps the binary to /bin/bash; env capture
+ * just runs the fallback strategy's syntax against the original binary).
+ */
+export function pickStrategy(shellPath: string): ShellStrategy | null {
+  return STRATEGIES.find((s) => s.matches(shellPath)) ?? null;
+}

package/src/shell/strategies/types.ts

@@ -0,0 +1,64 @@
+/**
+ * Per-shell adapter for the bits of agent-sh that are inherently shell-syntax
+ * specific: rc-file generation, spawn args/env, env-capture command, and the
+ * escape sequence used to repaint the prompt in place.
+ *
+ * Everything else (PTY I/O, OSC parsing, mute scopes, prompt boundary
+ * detection) is shell-agnostic and lives in shell.ts / output-parser.ts.
+ */
+
+export interface PrepareSpawnOpts {
+  /** Root for mkdtemp — typically os.tmpdir(). */
+  tmpDirRoot: string;
+  /** Per-instance tag (e.g. "id=abc123") so nested agent-sh hooks don't cross-trigger. */
+  instanceTag: string;
+  /** Whether to emit the terminal title indicator from the prompt hook. */
+  showIndicator: boolean;
+  /** Resolved user home (env.HOME ?? os.homedir()). */
+  userHome: string;
+  /** Inherited env at spawn time — strategies may read ZDOTDIR etc. */
+  env: Record<string, string>;
+}
+
+export interface ShellSpawnConfig {
+  /** Args to pass to pty.spawn after the shell binary. */
+  args: string[];
+  /** Env vars the strategy needs to set on the child (e.g. ZDOTDIR, XDG_CONFIG_HOME). */
+  envOverrides: Record<string, string>;
+  /** Temp directory the strategy created, if any — caller cleans up on exit. */
+  tmpDir?: string;
+}
+
+export interface ShellStrategy {
+  /** Short name used for fallback warnings ("zsh", "bash", "fish"). */
+  readonly name: string;
+
+  /** Does this strategy claim the binary at `shellPath`? */
+  matches(shellPath: string): boolean;
+
+  /**
+   * Generate any rc files and return spawn args + env overrides. May create
+   * a tmp directory; caller is responsible for cleanup via the returned path.
+   */
+  prepareSpawn(opts: PrepareSpawnOpts): ShellSpawnConfig;
+
+  /**
+   * Shell-syntax command run via `<shell> -l -c "<cmd>"` to source the user's
+   * config and dump env. Used at startup to inherit shell-only env vars.
+   */
+  envCaptureCommand(): string;
+
+  /**
+   * Escape sequence to write to the PTY to ask the shell to repaint its
+   * prompt in place. The corresponding binding is set up in prepareSpawn.
+   * Returns null if the shell can't redraw — caller falls back to freshPrompt.
+   */
+  redrawEscape(): string | null;
+
+  /**
+   * Strip shell-specific artifacts from raw PTY output before stripAnsi
+   * collapses SGR codes (e.g. zsh's PROMPT_SP inverse-video `%`). Default
+   * is identity — most shells need no cleanup.
+   */
+  cleanOutput?(raw: string): string;
+}