@livx.cc/agentx 0.94.38

package/dist/cli.d.ts

@@ -0,0 +1,293 @@
+#!/usr/bin/env bun
+import { H as Hooks, h as RunResult, R as ReasoningEffort, A as Agent } from './Agent-1DRfsYaK.js';
+import { IFilesystem } from '@livx.cc/wcli/core';
+import { M as Message, c as ContentPart, e as MessageContent } from './tools-DtpN8Agv.js';
+
+/**
+ * On-disk session store for the CLI: each conversation is one JSON file at
+ * `<cwd>/.agent/sessions/<id>.json`. Writes are atomic (temp + rename) so a crash
+ * mid-write never corrupts a prior session. This is what gives the REPL memory across
+ * turns and powers `--continue` / `--resume`.
+ */
+interface SessionMeta {
+    id: string;
+    created: number;
+    updated: number;
+    cwd: string;
+    model?: string;
+    turns: number;
+    title: string;
+    /** Cumulative tokens across all turns in this session (for `/cost`). */
+    tokens?: number;
+    /** Cumulative USD cost across all turns (per-turn model pricing; for `/cost`). */
+    costUsd?: number;
+    /** Sticky: true if any turn's usage was estimated (streamed without provider usage) → cost is approximate. */
+    costEstimated?: boolean;
+    /** Per-turn forensic log: timing, outcome, usage, and provider error per turn — for investigating a reported issue. */
+    events?: TurnEvent[];
+}
+/** One turn's diagnostics, captured for offline forensics (mirrors what the footer prints, but persisted). */
+interface TurnEvent {
+    ts: number;
+    durationMs: number;
+    model: string;
+    finishReason: string;
+    steps: number;
+    tools: number;
+    tokens?: number;
+    costUsd?: number;
+    estimated?: boolean;
+    error?: {
+        message: string;
+        statusCode?: number;
+        code?: string;
+    };
+}
+interface SessionData {
+    meta: SessionMeta;
+    messages: Message[];
+}
+declare class SessionStore {
+    readonly dir: string;
+    constructor(cwd: string);
+    /** Sortable, human-readable id: `YYYYMMDD-HHMMSS-<folder>`. */
+    newId(now?: number, cwd?: string): string;
+    /** A session id must be one safe path segment — blocks `../`-style traversal via --resume/load/save. */
+    private safeId;
+    save(data: SessionData): void;
+    load(id: string): SessionData | undefined;
+    /** All sessions' metadata, most-recently-updated first. */
+    list(): SessionMeta[];
+    latest(): SessionMeta | undefined;
+    /** The most-recently-updated session's full data (single listing pass). */
+    latestData(): SessionData | undefined;
+}
+
+/**
+ * Common contract for the CLI's two checkpoint backends: the in-memory {@link CheckpointStack}
+ * (sandbox mode) and the durable git-backed `GitCheckpoints` (disk mode). Both expose the same
+ * begin/list/rewindTo/size surface consumed by the REPL (`/rewind`, `/undo`, double-Esc rewind).
+ */
+interface Checkpoints {
+    /** Open a restore point for the turn about to run (label = the user's message). */
+    begin(label: string): void | Promise<void>;
+    /** Restore points, newest-first, for an interactive picker. */
+    list(): {
+        index: number;
+        label: string;
+        at: number;
+        files: number;
+    }[];
+    /** Restore the working tree to BEFORE restore point `index` (undo it and every later one). */
+    rewindTo(index: number): Promise<{
+        restored: number;
+        deleted: number;
+    }>;
+    /** Number of restore points currently held. */
+    readonly size: number;
+    /** Optional pre-mutation hook (in-memory backend only; git captures at the turn boundary). */
+    hooks?(): Hooks;
+    /** Re-bind to a different conversation (resume/switch); no-op for the in-memory backend. */
+    use?(sessionId: string): void;
+    /** Sync `list()`/`size` with the durable backend before a read (git backend only). */
+    refresh?(): Promise<void>;
+    /** Unified diff of everything this session changed (oldest restore point → current tree), for `/diff`. */
+    diff?(): Promise<string>;
+}
+
+/** Classify a pasted blob (e.g. a drag-dropped file path) into an attachment: `display` is shown in the
+ *  in-buffer placeholder, `ref` is what the placeholder expands to on submit (e.g. an `@/abs/path` mention). */
+type PasteClassifier = (text: string) => {
+    display: string;
+    ref: string;
+} | null;
+
+/** Programmatic Esc — abort the in-flight turn (tests; the REPL keymap calls activeTurn directly). */
+declare const abortActiveTurn: () => void;
+interface Args {
+    task?: string;
+    model?: string;
+    cwd?: string;
+    stream: boolean;
+    plan: boolean;
+    ask: boolean;
+    yes: boolean;
+    vfs: boolean;
+    shell: boolean | undefined;
+    boddb?: string;
+    seed: boolean;
+    subagents: boolean;
+    maxSteps?: number;
+    maxTokens?: number;
+    timeoutMs?: number;
+    reasoning?: ReasoningEffort;
+    help: boolean;
+    version: boolean;
+    duplex: boolean;
+    voiceModel?: string;
+    thinkModel?: string | false;
+    voice: boolean;
+    cont: boolean;
+    resume?: string;
+    sessionId?: string;
+    fork?: boolean;
+    outputFormat: 'text' | 'json' | 'stream-json';
+    allowedTools?: string[];
+    disallowedTools?: string[];
+    appendSystemPrompt?: string;
+    addDirs?: string[];
+    print?: boolean;
+    debug?: boolean;
+    scratch?: boolean;
+    harden?: boolean;
+    hardenNet?: boolean;
+}
+declare function parseArgs(argv: string[]): Args;
+/** Hooks that render tool activity to stderr: a preToolUse header, and for edits a colorized diff.
+ *  `opts.background` marks the agent as a BACKGROUND one (duplex workers): its chrome lands async on
+ *  top of a live prompt, so it must never drive the foreground spinner (the 'agentx › '/'⠹ thinking…'
+ *  flicker), clears the prompt line before printing, and repaints via the callback after. `opts.gate`
+ *  is evaluated per call — false renders nothing (minimal mode: task events only). */
+/** One-line collapsed summary for read-only lookup results (CC parity — `⎿ read 42 lines` instead of the
+ *  full body flooding the scrollback); null → tool keeps the N-line preview (shell output stays useful). */
+declare function summarizeResult(name: string, text: string): string | null;
+/** Synthetic task-event user messages ("[task t2 completed] <multi-KB worker dump>") aren't real user
+ *  utterances — replaying the raw payload newline-collapsed + hard-cut at N chars garbles it (slices URLs
+ *  mid-token). Condense to a one-line marker. Non-task text is returned unchanged. */
+declare function condenseReplay(t: string): string;
+/** Render a resumed conversation (like CC) so the user sees the context they're continuing: user
+ *  prompts, assistant narration, and a condensed line per tool action. Tool *results* are omitted
+ *  (verbose) and inlined @-mention blocks are stripped from prompts. Pure → unit-testable. */
+declare function formatHistory(messages: Message[]): string;
+/** Render the FULL transcript — user prompts, assistant text, every tool call AND its complete
+ *  result body — for `/transcript` (the past-turn equivalent of Ctrl-O live verbose; CC's
+ *  transcript-viewer parity). `lastTurns` bounds output to the most recent N user turns.
+ *  Each tool result is capped at `resultLines` lines with an elision marker. Pure → unit-testable. */
+declare function formatTranscriptFull(messages: Message[], opts?: {
+    lastTurns?: number;
+    resultLines?: number;
+}): string;
+/** Render a transcript to portable Markdown (no ANSI) for `/export`. Same shape as formatHistory —
+ *  user prompts + assistant narration + one quoted line per tool action; tool results omitted. Pure → unit-testable. */
+declare function exportMarkdown(meta: {
+    id: string;
+    title?: string;
+    model?: string;
+    turns?: number;
+    created?: number;
+    tokens?: number;
+    costUsd?: number;
+    costEstimated?: boolean;
+}, messages: Message[]): string;
+/** Cache-read/write price multipliers over the input rate, by provider (derived from the model
+ *  prefix). Anthropic: write 1.25x / read 0.1x. OpenAI & Gemini auto-cache (no write surcharge),
+ *  reads 0.5x / 0.25x. DeepSeek read 0.1x. Unknown → no discount (1x/1x, safe over-estimate). */
+declare function cacheMultipliers(model?: string): {
+    read: number;
+    write: number;
+};
+/** USD cost from a model's per-1K pricing (ai.libx.js ModelPricing) + token usage. 0 if unpriced.
+ *  Cache-aware: promptTokens includes cache reads/writes — priced at the provider's real multipliers
+ *  (via `model`) so cached runs aren't overstated. Omitting `model` falls back to Anthropic's rates. */
+declare function costOf(pricing: {
+    inputCostPer1K: number;
+    outputCostPer1K: number;
+} | undefined, promptTokens?: number, completionTokens?: number, cacheCreationTokens?: number, cacheReadTokens?: number, model?: string): number;
+/** Format a USD amount: 2 decimals at $1+, 4 below (agent turns are sub-cent). */
+declare function fmtUsd(n: number): string;
+/** ~4 chars/token estimate over a transcript (matches the Agent's context-budget heuristic). */
+declare function estimateTranscriptTokens(messages: Message[]): number;
+/** One-screen session status (model, dir, fs-mode, tools, permission posture, turns/tokens). Pure. */
+declare function formatStatus(s: {
+    model: string;
+    cwd: string;
+    mode: string;
+    tools: string[];
+    permissions: string;
+    turns: number;
+    tokens: number;
+    sessionId: string;
+    /** Whether the token count is estimated (any turn streamed without provider usage). Defaults to estimated. */
+    estimated?: boolean;
+}): string;
+/** Run a `!cmd` line and return its output — no model call. With `realShell` it shells out to a real
+ *  /bin/sh (same executor as the agent's `Shell` tool, so `!open`/`!docker`/`!git` work); otherwise it
+ *  runs over the wcli VFS emulator (sandbox/boddb — a real shell would escape the in-memory/db isolation). */
+declare function runShellLine(fs: IFilesystem, cmd: string, opts?: {
+    realShell?: boolean;
+    cwd?: string;
+}): Promise<string>;
+/** Append a `#note` to the memory index (creating the dir/file if needed). Returns the file path. */
+declare function appendMemoryNote(fs: IFilesystem, dir: string, text: string): Promise<string>;
+interface PermMode {
+    gate: 'ask' | 'allow';
+    notice?: string;
+}
+/**
+ * Default permission posture — CC-inspired: **ask when a human can answer, allow when unattended.**
+ * Pure + exported so the decision is unit-testable without a TTY. Precedence:
+ *   --yes  → allow (explicit trust, no prompts)
+ *   --ask  → ask   (explicit gate, even headless)
+ *   interactive (TTY & not json) → ask  (the safe default)
+ *   else (headless/piped) → allow, with a one-line notice so it's never silent.
+ */
+declare function resolvePermMode(args: {
+    yes?: boolean;
+    ask?: boolean;
+    outputFormat?: string;
+}, interactiveCapable: boolean): PermMode;
+/** Extract `@ref` mentions: bare `@path` (no spaces) or quoted `@"path with spaces"` — the quoted
+ *  form is what lets a drag-dropped macOS screenshot ("Screenshot 2026-06-11 at ….png") attach at all.
+ *  Bare refs get trailing sentence punctuation stripped (e.g. "@a.ts." / "@a.ts?"). */
+declare function mentionRefs(line: string): string[];
+/** Read `@image.png` mentions from `line` as base64 image content parts (real files under cwd; binary,
+ *  so read via node fs — the VFS readFile is utf8). Unreadable/missing images are skipped silently
+ *  (expandMentions reports the missing @ref separately). */
+declare function readImageParts(cwd: string, line: string): ContentPart[];
+/** Classify a pasted blob as a file attachment when it's a drag-dropped/typed path to an existing file.
+ *  Returns an `@<abs>` ref the existing mention pipeline attaches (images) or inlines (other files); the
+ *  in-buffer placeholder shows `[Image #N]` / `[File name #N]`. Returns null for anything not a clear single
+ *  path (so ordinary text pastes are unaffected). Paths with spaces are skipped — the `@\S+` pipeline can't carry them. */
+declare function pastePathClassifier(cwd: string): PasteClassifier;
+/** Inline `@path` file mentions: append referenced files' contents so the model sees them (missing → warn, leave as-is). */
+/** Resolves an `@server:uri` MCP-resource mention to its text body; null = not an MCP ref (fall through
+ *  to file resolution). Set by the REPL once servers are mounted; headless runs leave it unset. */
+declare let mcpMentionResolver: ((ref: string) => Promise<string | null>) | undefined;
+declare function setMcpMentionResolver(fn: typeof mcpMentionResolver): void;
+declare function expandMentions(fs: IFilesystem, line: string): Promise<{
+    text: string;
+    loaded: string[];
+    missing: string[];
+}>;
+/** The headless `--output-format json` result object for a turn. */
+declare function jsonResult(res: RunResult, session: SessionData): {
+    error?: any;
+    ok: boolean;
+    finishReason: "error" | "budget" | "stop" | "max_steps" | "timeout" | "loop" | "max_tool_calls" | "aborted";
+    text: string;
+    steps: number;
+    tools: number;
+    usage: {
+        promptTokens: number;
+        completionTokens: number;
+        totalTokens: number;
+        cacheCreationTokens?: number;
+        cacheReadTokens?: number;
+    } | undefined;
+    sessionId: string;
+};
+/**
+ * Read one logical input, supporting `\`-continuation for multi-line prompts: a line ending in
+ * a backslash drops the `\` and keeps reading; the parts are joined with newlines. `readLine`
+ * is injected (the REPL passes a readline `question`; tests pass a scripted reader).
+ */
+declare function readMultiline(readLine: (continuing: boolean) => Promise<string | null>): Promise<string | null>;
+/** Send one turn (expanding @file mentions), print the footer, persist the session.
+ *  `sendFn` overrides how the turn is dispatched (duplex routes through dx.send's mutex); `agent`
+ *  stays the transcript-owning agent (the voice, in duplex) — mentions/fs/signal/cost read off it. */
+declare function runTurn(agent: Agent, store: SessionStore, session: SessionData, task: string, cp?: Checkpoints, cwd?: string, sendFn?: (content: MessageContent) => Promise<RunResult>): Promise<{
+    ok: boolean;
+    res?: RunResult;
+}>;
+
+export { type PermMode, abortActiveTurn, appendMemoryNote, cacheMultipliers, condenseReplay, costOf, estimateTranscriptTokens, expandMentions, exportMarkdown, fmtUsd, formatHistory, formatStatus, formatTranscriptFull, jsonResult, mcpMentionResolver, mentionRefs, parseArgs, pastePathClassifier, readImageParts, readMultiline, resolvePermMode, runShellLine, runTurn, setMcpMentionResolver, summarizeResult };