agor-live 0.18.0 → 0.19.1

package/dist/core/claude-cli/index.d.cts

@@ -0,0 +1,602 @@
+/**
+ * JSONL event types written by `claude` v2.1.x to the on-disk transcript at
+ * `~/.claude/projects/<slug>/<session-id>.jsonl`.
+ *
+ * These are deliberately structural / `unknown`-tolerant. Anthropic owns the
+ * schema and can rename or add fields between CLI versions. The watcher's
+ * defensive parser logs+skips unknown shapes rather than crashing — once
+ * ccusage is wired in (see analysis doc Appendix C) its valibot schemas
+ * replace these for line-validation, but we keep these for adapter code that
+ * doesn't pull in valibot.
+ *
+ * The complete enumeration of `type` values observed in a real CLI session
+ * (Appendix A) is: ai-title, assistant, attachment, create, deferred_tools_delta,
+ * direct, last-prompt, mcp_instructions_delta, message, messages_changed,
+ * pr-link, previous_message_not_found, queue-operation, skill_listing,
+ * system_changed, text, thinking, todo_reminder, tool_reference, tool_result,
+ * tool_use, tools_changed, unavailable, update, user.
+ *
+ * Only a small subset drive the Agor message/task surfaces; everything else is
+ * either a nested content block (rendered inside an `assistant` event) or
+ * attachment metadata we log but don't persist in v1.
+ */
+/** Fields every JSONL line carries (with rare exceptions like `queue-operation`). */
+interface JsonlLineCommon {
+    /** v4 UUID per-line. NOT the same as `message.id` — multiple lines can
+     *  share one `message.id` (the cumulative-snapshot footgun). */
+    uuid?: string;
+    /** ISO 8601 timestamp. */
+    timestamp?: string;
+    /** The CLI session UUID — same value across every line in the file. */
+    sessionId?: string;
+    /** `claude` binary version (e.g. "2.1.132"). */
+    version?: string;
+    /** Working dir the session was launched from. */
+    cwd?: string;
+    /** Git branch name at the time the line was written. */
+    gitBranch?: string;
+    /** UUID of the JSONL line that triggered this one (turn ancestry). */
+    parentUuid?: string | null;
+    /** `true` for sub-agent (Task() tool) lines living in
+     *  `<sessionId>/subagents/agent-<id>.jsonl`. */
+    isSidechain?: boolean;
+}
+/** Queue lifecycle around each turn. */
+interface QueueOperationLine extends JsonlLineCommon {
+    type: 'queue-operation';
+    operation: 'enqueue' | 'dequeue' | string;
+}
+/** Auto-generated session title (e.g. "Analyze Claude Code CLI agentic-tool integration"). */
+interface AiTitleLine extends JsonlLineCommon {
+    type: 'ai-title';
+    aiTitle?: string;
+}
+/** Preview of the most recent user prompt, truncated ~120 chars. */
+interface LastPromptLine extends JsonlLineCommon {
+    type: 'last-prompt';
+    lastPrompt?: string;
+}
+/** User-driven message — top-level prompt OR `tool_result` envelope. */
+interface UserLine extends JsonlLineCommon {
+    type: 'user';
+    userType?: string;
+    permissionMode?: string;
+    /** Present when this line is a tool_result; the assistant turn's tool_use
+     *  uuid being reported on. */
+    sourceToolAssistantUUID?: string;
+    /** `tool_result` payload from the previous assistant `tool_use`. */
+    toolUseResult?: unknown;
+    message?: {
+        role?: 'user';
+        content?: unknown;
+    };
+}
+/** Assistant turn — the meat of the conversation surface. */
+interface AssistantLine extends JsonlLineCommon {
+    type: 'assistant';
+    /** API request id that produced this turn. 1:1 with `message.id`. */
+    requestId?: string;
+    userType?: string;
+    /** Always `"sdk-ts"` for `claude` v2.1.x regardless of how the session
+     *  was launched — not a useful discriminator. */
+    entrypoint?: string;
+    message?: {
+        /** The Anthropic API message id (`msg_…`). **Mandatory dedup key** —
+         *  one assistant turn writes one JSONL line per content block emitted,
+         *  each with the same `message.id` and the cumulative-to-that-point
+         *  `usage`. Naive sum across lines over-counts ~6× in our live sample. */
+        id?: string;
+        type?: 'message';
+        role?: 'assistant';
+        model?: string;
+        content?: AssistantContentBlock[];
+        stop_reason?: 'end_turn' | 'tool_use' | 'max_tokens' | 'stop_sequence' | string | null;
+        stop_sequence?: string | null;
+        stop_details?: unknown;
+        usage?: AssistantUsage;
+        diagnostics?: unknown;
+    };
+}
+/** Per-turn token usage with cache tiering. */
+interface AssistantUsage {
+    input_tokens?: number;
+    output_tokens?: number;
+    cache_creation_input_tokens?: number;
+    cache_read_input_tokens?: number;
+    cache_creation?: {
+        ephemeral_5m_input_tokens?: number;
+        ephemeral_1h_input_tokens?: number;
+    };
+    server_tool_use?: {
+        web_search_requests?: number;
+        web_fetch_requests?: number;
+    };
+    service_tier?: string;
+    iterations?: AssistantUsage[];
+}
+/** Content blocks within an assistant turn. */
+type AssistantContentBlock = {
+    type: 'text';
+    text: string;
+} | {
+    type: 'thinking';
+    thinking?: string;
+    signature?: string;
+} | {
+    type: 'tool_use';
+    id: string;
+    name: string;
+    input?: Record<string, unknown>;
+} | {
+    type: string;
+    [k: string]: unknown;
+};
+/** Attachment metadata — system notes attached around turns. */
+interface AttachmentLine extends JsonlLineCommon {
+    type: 'attachment';
+    /** Specific attachment subtype, e.g. `skill_listing`, `budget_usd`,
+     *  `deferred_tools_delta`, `pendingMcpServers`. The shape inside varies. */
+    attachmentType?: string;
+    [k: string]: unknown;
+}
+/** Catch-all for shapes we don't explicitly model. */
+interface UnknownLine extends JsonlLineCommon {
+    type: string;
+    [k: string]: unknown;
+}
+/** Discriminated union of all events we explicitly model. */
+type JsonlLine = QueueOperationLine | AiTitleLine | LastPromptLine | UserLine | AssistantLine | AttachmentLine | UnknownLine;
+/**
+ * The dedup key recommended by ccusage and validated in our live sample:
+ * `message.id` is 1:1 with `requestId`. Either field works; we prefer
+ * `message.id` because it's semantically anchored to the Anthropic API.
+ */
+declare function dedupKeyForAssistantLine(line: AssistantLine): string | null;
+
+/**
+ * Translate `claude` CLI JSONL lines into structured events the
+ * daemon-side watcher writes to MessagesService / TasksService.
+ *
+ * Three responsibilities:
+ *  1. Parse one JSONL line into a typed event. Unknown lines are surfaced
+ *     as `unknown` events (caller logs+skips).
+ *  2. Dedup assistant turns by `message.id` so the cumulative-snapshot
+ *     repetition (one JSONL line per content block, each carrying the
+ *     same cumulative usage — verified live to over-count ~6×) collapses
+ *     to a single emit per turn.
+ *  3. Emit a `turn_end` event when an assistant line carries
+ *     `stop_reason: "end_turn"` — this is the signal the prompt-injection
+ *     queue drains on.
+ *
+ * Cost math (price × usage with the cache-tier ratios) lives in a separate
+ * module — see `./cost.ts` once ccusage is wired in.
+ */
+
+/** A normalized assistant turn — what the watcher writes to `messages`. */
+interface NormalizedAssistantTurn {
+    /** Anthropic API message id, also the dedup key. */
+    messageId: string;
+    /** The JSONL `uuid` of the FIRST line that carried this message id.
+     *  Useful for `parentUuid` references on subsequent user/tool_result lines. */
+    firstLineUuid: string | null;
+    timestamp: string | null;
+    model: string | null;
+    content: AssistantContentBlock[];
+    usage: AssistantUsage | null;
+    stopReason: string | null;
+    /** Sub-agent (Task() tool) turns are marked so the UI can render them
+     *  as collapsible internal rows. */
+    isSidechain: boolean;
+}
+/** Output shape from the translator. One JSONL line can emit multiple events
+ *  (e.g. an assistant `end_turn` line emits both `assistant_message` and
+ *  `turn_end`). */
+type TranslatedEvent = {
+    type: 'user_message';
+    uuid: string | null;
+    timestamp: string | null;
+    permissionMode: string | null;
+    /** Plain text or content array — caller normalizes for storage. */
+    content: unknown;
+    isSidechain: boolean;
+} | {
+    type: 'tool_result';
+    uuid: string | null;
+    timestamp: string | null;
+    /** The assistant turn's `tool_use.id` this result corresponds to. */
+    sourceToolAssistantUUID: string | null;
+    /** Raw `toolUseResult` payload from the JSONL — schema varies by tool. */
+    result: unknown;
+    isSidechain: boolean;
+} | {
+    type: 'assistant_message';
+    turn: NormalizedAssistantTurn;
+} | {
+    type: 'turn_start';
+    timestamp: string | null;
+} | {
+    type: 'turn_end';
+    /** `messageId` of the turn that closed (always populated since we only
+     *  emit on an `assistant` line). */
+    messageId: string;
+    timestamp: string | null;
+} | {
+    type: 'ai_title';
+    title: string;
+} | {
+    type: 'last_prompt';
+    preview: string;
+} | {
+    type: 'attachment';
+    attachmentType: string | null;
+    payload: Record<string, unknown>;
+} | {
+    type: 'unknown';
+    jsonType: string;
+    raw: Record<string, unknown>;
+};
+/**
+ * Stateful translator for one JSONL transcript.
+ *
+ * Holds the "seen message ids" set in memory. Construct one per session.
+ * Construct fresh on watcher restart — the offset bookkeeping (in
+ * claude-cli-watcher.ts) ensures we don't re-process lines, so the in-memory
+ * Set never needs to survive restart.
+ */
+declare class JsonlEventTranslator {
+    private readonly seenMessageIds;
+    /**
+     * Parse one JSONL line (string) and emit zero or more translated events.
+     * Returns `[]` for lines that produced no events (e.g. duplicate assistant
+     * lines with a `message.id` already seen — the snapshot footgun handled).
+     */
+    translateLine(rawLine: string): TranslatedEvent[];
+    /** Same as `translateLine` but for already-parsed objects (useful in
+     *  tests + fixture replay). */
+    translateParsed(parsed: JsonlLine): TranslatedEvent[];
+    private handleQueueOperation;
+    private handleAiTitle;
+    private handleLastPrompt;
+    private handleUser;
+    private handleAssistant;
+    private handleAttachment;
+    /** Test/debug hook. Returns the set of message ids the translator has
+     *  already emitted for. */
+    getSeenMessageIds(): ReadonlySet<string>;
+}
+
+/**
+ * Path helpers for the Claude Code CLI on-disk session storage.
+ *
+ * The `claude` binary writes each session's transcript to:
+ *
+ *   ~/.claude/projects/<slug>/<session-id>.jsonl
+ *
+ * `<slug>` is the working directory the session was launched from, with every
+ * `/` and `.` replaced by `-`. This rule was verified live on
+ * `claude` v2.1.132 against multiple paths.
+ *
+ * See docs/internal/claude-code-cli-integration-analysis-2026-05-14.md
+ * (Appendix A) for the live session sample these helpers were validated
+ * against.
+ */
+/**
+ * Slug a working-directory path the way the `claude` CLI does.
+ *
+ * Replaces every `/` and `.` with `-`. The path is NOT lowercased — the slug
+ * preserves case so we can round-trip back to the absolute path if needed.
+ *
+ * Examples:
+ *
+ *   /Users/max/projects/agor       → -Users-max-projects-agor
+ *   /home/agor/.agor/repos/agor    → -home-agor--agor-repos-agor
+ *   /tmp/foo.bar/baz               → -tmp-foo-bar-baz
+ *
+ * Note the `.agor` directory: the leading dot becomes `-` and the
+ * surrounding `/` separators also become `-`, producing the `--` doubling.
+ * This matches Anthropic's slug rule exactly.
+ */
+declare function slugForCwd(cwd: string): string;
+/**
+ * Compute the directory under `~/.claude/projects/` for a given working dir.
+ *
+ * The directory exists as soon as the first session for that cwd has written
+ * any data, but we never create it ourselves — the CLI does.
+ */
+declare function claudeProjectDir(homeDir: string, cwd: string): {
+    slug: string;
+    dir: string;
+};
+/**
+ * Compute the absolute path of a session's JSONL transcript.
+ *
+ * @param homeDir       The Unix user's home directory whose `~/.claude/`
+ *                      we're targeting. In `strict` Unix mode this is the
+ *                      session owner's home; in `insulated` mode it's the
+ *                      shared executor user's home.
+ * @param cwd           The cwd the `claude` process was launched from.
+ *                      Same value that goes to `--add-dir` / the spawn cwd.
+ * @param sessionId     The UUID passed to `claude --session-id <uuid>`.
+ */
+declare function claudeSessionJsonlPath(homeDir: string, cwd: string, sessionId: string): string;
+/**
+ * Compute the directory under `<slug>/<sessionId>/subagents/` that holds
+ * sub-agent JSONL files for Task() tool internals.
+ *
+ * Watching this directory (and creating child watchers as `agent-<id>.jsonl`
+ * files appear) is how we surface internal Task() sub-agents in the
+ * conversation view. See § Subagent JSONL ingestion in the analysis doc.
+ */
+declare function claudeSubagentsDir(homeDir: string, cwd: string, sessionId: string): string;
+
+/**
+ * Per-token pricing for Claude models, used by the CLI adapter to compute
+ * cost from JSONL `usage` fields at `turn_end`.
+ *
+ * Numbers mirror Anthropic's public pricing page and the constants we
+ * extracted from the `claude` binary itself (`Au$` table — same rates the
+ * REPL's `/usage` command displays). Units are USD per **token** (the
+ * public table is "per 1M tokens"; we divide by 1e6 below at the call
+ * site to keep these constants legible).
+ *
+ * Why hand-roll vs `ccusage`:
+ *   - v1 ships without a network/dependency hop for cost math.
+ *   - The set of models that flow through the CLI adapter is small and
+ *     bounded by what Anthropic exposes via `claude --model <X>`.
+ *   - Flipping to ccusage (which fetches prices from LiteLLM) is queued
+ *     and covered in docs/internal/claude-code-cli-integration-analysis-2026-05-14.md.
+ *
+ * If a model is missing from this table, callers should treat the
+ * resulting `costUsd` as `undefined` rather than zero — `getModelPricing`
+ * returns null in that case.
+ */
+interface ClaudeModelPricing {
+    /** USD per 1M input tokens (non-cached). */
+    inputPerMTok: number;
+    /** USD per 1M output tokens. */
+    outputPerMTok: number;
+    /** USD per 1M cache-creation (write) tokens, 5m ephemeral tier. */
+    cacheWritePerMTok: number;
+    /** USD per 1M cache-read tokens. */
+    cacheReadPerMTok: number;
+    /** USD per web-search request (server-side tool). */
+    webSearchPerRequest?: number;
+}
+/**
+ * Resolve pricing for a model id. Longest-prefix match against the table
+ * above so versioned suffixes don't break us (e.g. `claude-opus-4-7-20260101`
+ * still hits the `claude-opus-4` entry).
+ *
+ * Returns `null` for unknown models — caller treats that as "cost unknown"
+ * rather than zero.
+ */
+declare function getModelPricing(modelId: string | null | undefined): ClaudeModelPricing | null;
+/**
+ * Compute total cost in USD for one assistant turn's usage.
+ *
+ * Mirrors the math we extracted from the `claude` binary:
+ *   inputTokens × input + outputTokens × output
+ *   + cache_creation × cacheWrite
+ *   + cache_read × cacheRead
+ *   + web_search_requests × webSearch
+ *
+ * Returns `undefined` when pricing is unknown — never returns 0 as a
+ * "missing data" signal because legitimate small turns can cost ~$0.
+ *
+ * The `usage` parameter is the JSONL transcript's `assistant.message.usage`
+ * shape — `AssistantUsage` from `./event-types`.
+ */
+declare function computeCost(modelId: string | null | undefined, usage: AssistantUsage | null | undefined): number | undefined;
+/**
+ * Model context-window capacity in tokens. Used to compute "% of context
+ * consumed" for the session-detail UI. Same prefix-match strategy as
+ * `getModelPricing`.
+ */
+declare function getContextWindowLimit(modelId: string | null | undefined): number;
+
+/**
+ * SDK-response shapes for the Claude Code CLI adapter.
+ *
+ * Lives in `@agor/core/claude-cli/` (not the daemon service file) so the
+ * shapes can be referenced by tests, type-only consumers in the UI, and
+ * any future tool that ingests CLI task analytics — without pulling in
+ * the daemon's runtime wiring.
+ *
+ * Field names are kept in **lockstep** with two existing SDK-side types:
+ *   - `SDKResultMessage` from `@anthropic-ai/claude-agent-sdk` (mirrored
+ *     by `ClaudeCliRawSdkResponse`)
+ *   - `NormalizedSdkData` in
+ *     `packages/executor/src/sdk-handlers/base/normalizer.interface.ts`
+ *     (mirrored by `ClaudeCliNormalizedSdkResponse`)
+ *
+ * We don't import either of those — the daemon shouldn't depend on the
+ * executor package, and the SDK type is for SDK sessions, not CLI ones —
+ * but if either ever drifts, the existing `ClaudeCodeNormalizer`
+ * (executor) will start producing different shapes for SDK vs CLI tasks
+ * and downstream cost/token cards will diverge. The deliberate type
+ * duplication is documented; lockstep maintenance is the contract.
+ */
+/**
+ * One model's slice of the per-turn rollup. Field names match the SDK's
+ * `ClaudeModelUsage` so the same UI code reads both.
+ */
+interface ClaudeCliModelUsageEntry {
+    inputTokens: number;
+    outputTokens: number;
+    cacheCreationInputTokens: number;
+    cacheReadInputTokens: number;
+    contextWindow: number;
+}
+/**
+ * What we persist to `task.data.raw_sdk_response` for CLI-driven turns.
+ *
+ * Mirrors `SDKResultMessage` — same `modelUsage` / `usage` /
+ * `duration_ms` / `total_cost_usd` fields — so the existing
+ * `ClaudeCodeNormalizer` reads CLI turns the same as SDK turns.
+ *
+ * `_cli_provenance` is the one CLI-specific addition: a debugging
+ * breadcrumb so "did we miss `end_turn`?" investigations don't have to
+ * re-read the JSONL. Nothing in the UI depends on it; structurally
+ * additive.
+ */
+interface ClaudeCliRawSdkResponse {
+    type: 'result';
+    subtype: 'success';
+    session_id: string;
+    duration_ms: number;
+    total_cost_usd: number | undefined;
+    modelUsage: Record<string, ClaudeCliModelUsageEntry>;
+    usage: {
+        input_tokens: number;
+        output_tokens: number;
+        cache_read_input_tokens: number;
+        cache_creation_input_tokens: number;
+    };
+    _cli_provenance: {
+        adapter: 'claude-code-cli';
+        assistantTurns: number;
+        lastAssistantSnapshot: unknown;
+    };
+}
+/**
+ * Normalized rollup we persist to `task.data.normalized_sdk_response`.
+ * Shape matches `NormalizedSdkData` (see file-level comment).
+ */
+interface ClaudeCliNormalizedSdkResponse {
+    tokenUsage: {
+        inputTokens: number;
+        outputTokens: number;
+        totalTokens: number;
+        cacheReadTokens: number;
+        cacheCreationTokens: number;
+    };
+    contextWindowLimit: number;
+    costUsd: number | undefined;
+    primaryModel: string | undefined;
+    durationMs: number;
+}
+
+/**
+ * Build the argv for spawning the `claude` shell binary in a Zellij pane.
+ *
+ * Verified against `claude` v2.1.132. We use the **interactive** subset of
+ * flags (NO `-p`/`--print`) — see the analysis doc's "Policy & ToS landscape"
+ * section for why the print-mode path is deliberately avoided.
+ *
+ * Flags we emit (when applicable):
+ *
+ *   --session-id <uuid>            REQUIRED. Maps agor.session_id ↔ claude session.
+ *   --resume <id>                  Resume an existing session by id.
+ *   --fork-session                 With --resume, mint a new session-id.
+ *   --model <alias>                e.g. claude-opus-4-7. Stripped of [1m] suffix.
+ *   --betas <flag>                 e.g. context-1m-2025-08-07 (only with [1m] models).
+ *   --effort <level>               low | medium | high | xhigh | max
+ *   --permission-mode <mode>       default|acceptEdits|bypassPermissions|plan|dontAsk|auto.
+ *                                  Mutually exclusive with --dangerously-skip-permissions.
+ *   --dangerously-skip-permissions Distinct argv per Anthropic's flag design — same
+ *                                  runtime as bypassPermissions, separate telemetry.
+ *   --mcp-config <file>            JSON file with Agor + scoped user MCPs.
+ *   --strict-mcp-config            Ignore the user's other MCP sources.
+ *   --add-dir <dir...>             Extra context/work dirs beyond cwd.
+ *   --append-system-prompt-file <f> Path to a file Agor wrote with session context.
+ *   -n <name>                      Display name (shown in /resume picker + terminal title).
+ *
+ * Print-only flags we deliberately DO NOT emit: `-p`, `--output-format`,
+ * `--input-format`, `--include-partial-messages`, `--include-hook-events`,
+ * `--max-budget-usd`, `--no-session-persistence`, `--replay-user-messages`.
+ */
+/**
+ * Permission modes the CLI accepts. Mirrors the SDK's `ClaudeCodePermissionMode`
+ * union but extended with `auto` and the synthetic `dangerously-skip-permissions`
+ * marker — picked from the user-facing Defaults dropdown (analysis doc § Claude
+ * Code CLI Defaults panel).
+ *
+ * `dangerously-skip-permissions` emits the dedicated argv flag rather than
+ * `--permission-mode bypassPermissions`. Runtime is identical; telemetry differs.
+ */
+type ClaudeCliPermissionMode = 'default' | 'acceptEdits' | 'bypassPermissions' | 'plan' | 'dontAsk' | 'auto' | 'dangerously-skip-permissions';
+interface ClaudeCliSpawnConfig {
+    /**
+     * The session-id the CLI will use. Agor mints this — typically equals the
+     * Agor session_id (UUIDv7). If omitted, the CLI generates its own and the
+     * caller has to discover it by tailing the slug dir for a new JSONL file.
+     * Strongly prefer setting this.
+     */
+    sessionId?: string;
+    /** Resume an existing session by claude-side session id. */
+    resumeSessionId?: string;
+    /**
+     * With `resumeSessionId`, mint a new session id (true fork at the CLI
+     * level — capability flag `supportsSessionFork`).
+     */
+    forkSession?: boolean;
+    /** Display name (terminal title + /resume picker label). */
+    displayName?: string;
+    /**
+     * Model alias — `claude-opus-4-7`, `claude-sonnet-4-6`, etc. A trailing
+     * `[1m]` suffix enables the 1M context window via the `context-1m-2025-08-07`
+     * beta flag.
+     */
+    model?: string;
+    /** Reasoning effort. */
+    effort?: 'low' | 'medium' | 'high' | 'xhigh' | 'max';
+    /** Permission handling at spawn. See type comment. */
+    permissionMode?: ClaudeCliPermissionMode;
+    /** Absolute path to per-session MCP config tmp file. */
+    mcpConfigPath?: string;
+    /**
+     * When MCP config is set, also pass `--strict-mcp-config` so the user's
+     * other MCP sources are ignored. Defaults to `true` since we always want
+     * Agor MCP-only at spawn.
+     */
+    strictMcp?: boolean;
+    /** Extra `--add-dir` paths beyond cwd. */
+    addDirs?: string[];
+    /** Absolute path to a system-prompt file Agor wrote at spawn. */
+    appendSystemPromptFile?: string;
+    /**
+     * Additional raw argv to append. Power-user escape hatch for flags we
+     * don't model explicitly. Caller is responsible for shell-safety.
+     */
+    extraArgs?: string[];
+}
+interface BuiltSpawn {
+    /** `claude` */
+    bin: string;
+    /** Argv (does NOT include the binary itself). */
+    args: string[];
+}
+/**
+ * Resolve the SDK's `permission_config.mode` to the CLI's argv flag.
+ * Returns `acceptEdits` as the v1 default for user-driven sessions when
+ * no mode is configured, mirroring the Defaults-panel out-of-box choice
+ * in the analysis doc.
+ */
+declare function permissionModeForCli(mode: string | null | undefined): ClaudeCliPermissionMode | undefined;
+/**
+ * Build the spawn invocation for the `claude` binary.
+ *
+ * Pure function — no fs / process side-effects. Caller (the Zellij command
+ * handler) decides how to actually exec it.
+ */
+declare function buildClaudeCliSpawn(cfg: ClaudeCliSpawnConfig): BuiltSpawn;
+/**
+ * Render `claude <args...>` as a shell-safe command string suitable for
+ * passing to `zellij action new-tab --command` (which spawns one binary
+ * with argv, not a full shell). Each argv element is quoted separately.
+ *
+ * Zellij's `new-tab --command` actually accepts a binary and `--args`;
+ * see `formatForZellijNewTab` for the shape we usually want.
+ */
+declare function formatAsShellCommand(built: BuiltSpawn): string;
+/**
+ * Zellij's `new-tab` takes `--command <bin>` plus repeated `--args <one>` for
+ * each argv element. This helper gives back the flag bundle we'd append.
+ *
+ * Example:
+ *   formatForZellijNewTab(built)
+ *   // => ['--command', 'claude', '--args', '--session-id', '--args', '...']
+ */
+declare function formatForZellijNewTab(built: BuiltSpawn): string[];
+
+export { type AiTitleLine, type AssistantContentBlock, type AssistantLine, type AssistantUsage, type AttachmentLine, type BuiltSpawn, type ClaudeCliModelUsageEntry, type ClaudeCliNormalizedSdkResponse, type ClaudeCliPermissionMode, type ClaudeCliRawSdkResponse, type ClaudeCliSpawnConfig, type ClaudeModelPricing, JsonlEventTranslator, type JsonlLine, type JsonlLineCommon, type LastPromptLine, type NormalizedAssistantTurn, type QueueOperationLine, type TranslatedEvent, type UnknownLine, type UserLine, buildClaudeCliSpawn, claudeProjectDir, claudeSessionJsonlPath, claudeSubagentsDir, computeCost, dedupKeyForAssistantLine, formatAsShellCommand, formatForZellijNewTab, getContextWindowLimit, getModelPricing, permissionModeForCli, slugForCwd };