autodev-cli 1.4.189 → 1.4.191

package/out/providers/acp/AcpSession.d.ts

@@ -0,0 +1,188 @@
+/** Callbacks the host injects so hook emission + redaction stay in one place. */
+export interface AcpHostHooks {
+    /** Emit ONE hook event (host adds redaction + provider tagging). */
+    emitHook(name: string, extra: Record<string, unknown>): void;
+    /** Human log line. */
+    log(msg: string): void;
+}
+export interface AcpTurnResult {
+    clean: boolean;
+    stopReason: string;
+    error?: string;
+    /** True when the turn ended clean but produced NO assistant text / tool calls
+     *  (e.g. an unusable model). Lets the host surface a clear log instead of
+     *  silently spinning. */
+    emptyOutput?: boolean;
+}
+/** A decoded session/update notification (pure; unit-tested). */
+export type AcpUpdate = {
+    kind: 'assistant';
+    text: string;
+} | {
+    kind: 'reasoning';
+    text: string;
+} | {
+    kind: 'tool_call';
+    id: string;
+    name: string;
+    input: unknown;
+} | {
+    kind: 'tool_result';
+    id: string;
+    outputText: string;
+    status: string;
+} | {
+    kind: 'other';
+};
+/** Provider-specific launch + decode configuration. */
+export interface AcpLaunchSpec {
+    /** Build the argv (after the binary) for `spawn`. */
+    buildArgs(model: string | undefined, extraArgs: string[]): string[];
+    /** Decode a raw JSON-RPC session/update into an AcpUpdate. Defaults to the
+     *  standard-ACP decoder (`decodeAcpUpdateStandard`). */
+    decodeUpdate?: (msg: unknown) => AcpUpdate;
+    /** Title attached to narration (Notification) hooks. */
+    narrationTitle: string;
+    /** Forward agent_thought_chunk as narration too (default false). */
+    narrateReasoning?: boolean;
+}
+/**
+ * STANDARD-ACP decoder (opencode, and the generic default). Handles the ACP-spec
+ * session/update shapes:
+ *   agent_message_chunk {content:{type:'text',text}}       -> assistant
+ *   agent_thought_chunk {content:{type:'text',text}}       -> reasoning
+ *   tool_call           {toolCallId,title,rawInput}        -> tool_call (name=title)
+ *   tool_call_update    {toolCallId,status,content|rawOutput} -> tool_result
+ * Anything else (available_commands_update, usage_update, plan, …) -> other. PURE.
+ */
+export declare function decodeAcpUpdateStandard(msg: unknown): AcpUpdate;
+/** Best-effort flatten of a tool_call_update's output into a short string. PURE. */
+export declare function extractToolOutput(u: Record<string, unknown>): string;
+/**
+ * Classify a session/prompt RESULT into clean-vs-error for the exit file. PURE.
+ * - end_turn / max_tokens / max_turn_requests → clean (exit 0)
+ * - cancelled → clean (an intentional interrupt, not a failure)
+ * - a JSON-RPC error, or any other stopReason → error (exit 1)
+ */
+export declare function classifyAcpResult(result: {
+    result?: {
+        stopReason?: string;
+    };
+    error?: {
+        message?: string;
+    };
+}): AcpTurnResult;
+/**
+ * One persistent ACP process for a workspace root. Not a singleton — the host
+ * keeps a Map<root, AcpSession> and reuses it. Provider behaviour is injected via
+ * the `spec`.
+ */
+export declare class AcpSession {
+    protected readonly root: string;
+    protected readonly model: string | undefined;
+    protected readonly bin: string;
+    protected readonly hooks: AcpHostHooks;
+    protected readonly extraArgs: string[];
+    protected readonly spec: AcpLaunchSpec;
+    /** Extra env vars merged into the child's environment (e.g. OPENCODE_CONFIG). */
+    protected readonly extraEnv: Record<string, string>;
+    private readonly _decode;
+    private child;
+    private buf;
+    private nextId;
+    private readonly pending;
+    private _sessionId;
+    private _wantSessionId;
+    private _ready;
+    private _busy;
+    private _startCount;
+    private earlyStderr;
+    /** True WHILE session/load is replaying prior history — every session/update
+     *  during the replay is dropped (emits ZERO hooks) so a (re)start never
+     *  re-spams historical narration + tool_calls to the office feed (Layer A.1). */
+    private _loading;
+    /** The active PRIMARY turn's stdout sink (assistant text). Null between turns. */
+    private _sink;
+    /** Tool-call names by id, so a tool_result can carry the originating name. */
+    private readonly _toolNames;
+    /** Accumulates assistant chunks so Notification hooks are line-granular. */
+    private _narrationBuf;
+    /** The current tool activity label (set on tool_call, cleared on result). */
+    private _activity;
+    /** Did the active turn produce ANY assistant text or tool call? (empty-turn guard) */
+    private _turnHadOutput;
+    /** ALL outstanding session/prompt promises — the primary turn AND any steered
+     *  (queued) continuation prompts. The turn is not "done" until this drains, so
+     *  the loop keeps the agent WORKING through steers instead of going idle while
+     *  the agent runs an untracked queued turn (Bug A). */
+    private readonly _inflight;
+    constructor(opts: {
+        root: string;
+        model?: string;
+        bin: string;
+        hooks: AcpHostHooks;
+        spec: AcpLaunchSpec;
+        initialSessionId?: string;
+        extraArgs?: string[];
+        extraEnv?: Record<string, string>;
+    });
+    /** Per-turn watchdog budget (ms). Env: AUTODEV_ACP_MAX_RUN_MS, else GROK_MAX_RUN_MS
+     *  (parity with the headless path), else 20 minutes. A 0/negative value disables. */
+    static maxRunMs(): number;
+    get pid(): number | undefined;
+    get sessionId(): string | undefined;
+    get activity(): string | undefined;
+    /** Busy while the primary turn is running OR any steered/queued prompt is still
+     *  in-flight — so the loop never treats the agent as idle mid-queue (Bug A). */
+    isBusy(): boolean;
+    isAlive(): boolean;
+    /** Spawn + initialize + session/new|load, once. Respawns transparently if dead. */
+    ensureReady(): Promise<void>;
+    private _startup;
+    private _spawnChild;
+    private _onExit;
+    private _onStdout;
+    private _handle;
+    private _onUpdate;
+    /**
+     * Bug B invariant: every forwarded tool-START must get a matching tool-END. On
+     * turn end / cancel / teardown, FLUSH any tool_call ids still open (never got a
+     * terminal tool_call_update) as ended, so pixel-office (which pairs start→end)
+     * never shows a tool stuck "running" after the agent is idle.
+     */
+    private _flushOpenTools;
+    /** Emit completed narration lines as Notification hooks. `final` flushes the
+     *  trailing partial line (turn end). Keeps the office feed line-granular. */
+    private _flushNarration;
+    /**
+     * Run ONE primary turn: send the prompt and await turn end. Streams assistant
+     * text to `sink`. Emits Stop/StopFailure + SessionEnd. The process stays alive.
+     */
+    runTurn(promptText: string, sink: (text: string) => void): Promise<AcpTurnResult>;
+    /**
+     * Deliver a mid-run STEER: send an additional session/prompt the agent QUEUES
+     * (FIFO) and runs next — without exiting. The prompt is TRACKED in `_inflight`
+     * so the in-progress runTurn drains it before finishing (Bug A) — the steered
+     * turn's session/update hooks are forwarded like a normal turn and the loop
+     * stays WORKING until it completes. Returns true if handed to the live agent.
+     */
+    steer(text: string): boolean;
+    /** Send a tracked session/prompt (primary or steer) and register it in
+     *  `_inflight` until it resolves. */
+    private _promptRequest;
+    /** Wait until every in-flight/queued prompt has resolved. */
+    private _drainInflight;
+    /**
+     * Send a QUIET prompt (e.g. `/compact`) and await it WITHOUT emitting the
+     * Stop/SessionEnd turn-boundary hooks — used for maintenance commands so they
+     * don't register as a task turn. Best-effort.
+     */
+    sendQuiet(text: string): Promise<void>;
+    /** Cancel the running turn (process stays alive). */
+    cancel(): void;
+    /** Kill the persistent process. Preserves the known session id for a later load. */
+    close(): void;
+    private _request;
+    private _send;
+    get stderrSnapshot(): string;
+}