@glrs-dev/cli 2.3.0 → 2.4.1

package/dist/node_modules/@glrs-dev/adapter-opencode/dist/index.d.ts

@@ -0,0 +1,261 @@
+import { execFile } from 'node:child_process';
+import { OpencodeClient } from '@opencode-ai/sdk';
+import { AgentAdapter, AgentHandle, AdapterSessionResult } from '@glrs-dev/autopilot';
+
+/**
+ * OpenCode server lifecycle helpers.
+ *
+ * General-purpose utilities for starting an OpenCode server, creating
+ * sessions, sending messages, and waiting for idle. Used by the Ralph
+ * autopilot loop and any future feature that needs to drive OpenCode
+ * programmatically.
+ *
+ * Extracted from src/pilot/server.ts so these helpers are not coupled
+ * to the pilot subsystem.
+ */
+
+declare const execFileP: typeof execFile.__promisify__;
+type StartedServer = {
+    url: string;
+    client: OpencodeClient;
+    shutdown: () => Promise<void>;
+};
+type SessionResult = {
+    kind: "idle";
+} | {
+    kind: "stall";
+    stallMs: number;
+} | {
+    kind: "abort";
+} | {
+    kind: "error";
+    message: string;
+} | {
+    kind: "question_rejected";
+    title: string;
+};
+declare const DEFAULT_STARTUP_TIMEOUT_MS = 30000;
+/**
+ * Start an OpenCode server for the given working directory.
+ * Returns the server URL, a bound client, and a shutdown function.
+ *
+ * Uses createOpencode() which spawns the server process and creates
+ * a connected client. The server inherits process.cwd() as its project
+ * directory.
+ */
+declare function startServer(opts: {
+    cwd: string;
+    port?: number;
+    timeoutMs?: number;
+}): Promise<StartedServer>;
+/**
+ * Verify the server is responsive by listing sessions.
+ * Fails fast with a diagnostic if the server isn't working.
+ */
+declare function selfTest(client: OpencodeClient): Promise<void>;
+/**
+ * Create a new OpenCode session for the given directory.
+ *
+ * Note: the SDK's `session.create` body takes only `parentID` and `title`
+ * — agent selection is a per-message concern in OpenCode's model and lives
+ * on `session.prompt`'s body, not on session creation. The working
+ * directory is passed via the `query.directory` param.
+ *
+ * Returns the session ID.
+ */
+declare function createSession(client: OpencodeClient, opts: {
+    cwd: string;
+    agentName?: string;
+}): Promise<string>;
+/**
+ * Send a message to a session and wait for the agent to go idle.
+ *
+ * Uses `session.prompt` (the correct SDK method for sending a message).
+ * `session.chat` does not exist on the SDK — an earlier version of this
+ * module used that name and silently failed at runtime.
+ *
+ * The optional `onToolCall` callback fires once per tool invocation that
+ * reaches the `completed` state. Used by the autopilot loop to emit
+ * debug-level log events for each tool call.
+ *
+ * The optional `onTextDelta` callback fires for each assistant text
+ * chunk the agent streams. Used by the autopilot loop's stream-liveness
+ * indicator — between tool calls, the agent may stream text for minutes
+ * while reasoning, and without this signal the user can't distinguish
+ * "still working" from "hung."
+ *
+ * When `autoRejectPermissions: true`, any `permission.updated` event
+ * fired for this session is immediately answered with `response: "reject"`.
+ * Used by autopilot to prevent the `question` tool (or any tool-approval
+ * prompt) from deadlocking the session — no human is available to answer.
+ * The `onPermissionRejected` callback (if provided) fires each time a
+ * permission is auto-rejected so the caller can log it.
+ *
+ * Returns the result kind.
+ */
+declare function sendAndWait(client: OpencodeClient, opts: {
+    sessionId: string;
+    message: string;
+    agentName?: string;
+    stallMs?: number;
+    abortSignal?: AbortSignal;
+    onToolCall?: (toolName: string, firstArg?: string) => void;
+    onTextDelta?: (charCount: number) => void;
+    /** Fires on `message.updated` events with cost/token data. Used for
+     *  real-time cost visibility during long iterations. */
+    onCostUpdate?: (cost: number, tokens: {
+        input: number;
+        output: number;
+    }) => void;
+    autoRejectPermissions?: boolean;
+    /** Server URL for raw HTTP calls (question-reject endpoint). */
+    serverUrl?: string;
+    onPermissionRejected?: (permission: {
+        id: string;
+        type: string;
+        title: string;
+    }) => void;
+}): Promise<SessionResult>;
+/**
+ * Wait for a session to go idle (agent done), stall, abort, or error.
+ *
+ * `client.event.subscribe()` is async and returns `{ stream }` (a
+ * `ServerSentEventsResult`). The stream is an AsyncGenerator of events.
+ *
+ * When `onToolCall` is provided, fires once per tool invocation that
+ * reaches the `completed` state. Filters out pending/running transitions
+ * to avoid double-counting.
+ *
+ * When `onTextDelta` is provided, fires for each non-empty delta string
+ * the server emits (charCount = delta.length). Used by autopilot to
+ * signal liveness during long reasoning streams between tool calls.
+ *
+ * When `autoRejectPermissions: true`, any `permission.updated` event
+ * for this session is answered with `response: "reject"` via
+ * `POST /session/{id}/permissions/{permissionID}`. This prevents the
+ * `question` tool (and any tool-approval prompts) from deadlocking the
+ * session when no human is present to answer. `onPermissionRejected`
+ * fires synchronously with the permission payload so callers can log.
+ */
+declare function waitForIdle(client: OpencodeClient, opts: {
+    sessionId: string;
+    stallMs?: number;
+    abortSignal?: AbortSignal;
+    onToolCall?: (toolName: string, firstArg?: string) => void;
+    onTextDelta?: (charCount: number) => void;
+    /** Fires on `message.updated` events with cost/token data. Used for
+     *  real-time cost visibility during long iterations. */
+    onCostUpdate?: (cost: number, tokens: {
+        input: number;
+        output: number;
+    }) => void;
+    autoRejectPermissions?: boolean;
+    /** Server URL for raw HTTP calls (question-reject endpoint). */
+    serverUrl?: string;
+    onPermissionRejected?: (permission: {
+        id: string;
+        type: string;
+        title: string;
+    }) => void;
+}): Promise<SessionResult>;
+/**
+ * Get the cumulative cost of a session in USD.
+ *
+ * Cost is tracked per-message on the server (AssistantMessage.cost),
+ * not aggregated on the Session object. We sum across all assistant
+ * messages to get a session total.
+ */
+declare function getSessionCost(client: OpencodeClient, sessionId: string): Promise<number>;
+/**
+ * Get cumulative cost + token totals for a session.
+ *
+ * Sums cost, input tokens, and output tokens across all assistant
+ * messages. Returns zeros on any error (non-fatal).
+ */
+declare function getSessionStats(client: OpencodeClient, sessionId: string): Promise<{
+    cost: number;
+    tokensIn: number;
+    tokensOut: number;
+}>;
+/**
+ * Fetch the last assistant message text from a session.
+ *
+ * Calls `client.session.messages()`, filters to assistant-role messages,
+ * takes the last one, and concatenates all text parts.
+ *
+ * Returns an empty string if there are no assistant messages or if the
+ * API call fails.
+ */
+declare function getLastAssistantMessage(client: OpencodeClient, sessionId: string): Promise<string>;
+
+/**
+ * Extract actionable error details from OpenCode server logs.
+ *
+ * When the SSE `session.error` event carries only a generic "session error"
+ * message, the real error (credential failure, model not found, etc.) is
+ * only in the OpenCode server's own log at ~/.local/share/opencode/log/.
+ *
+ * This module reads the most recent log file and extracts the last
+ * session.processor error line — which contains the actual provider error.
+ */
+/**
+ * Read the most recent OpenCode server log and extract the last
+ * session.processor error message. Returns null if no log found
+ * or no error extracted.
+ *
+ * This is best-effort — the log directory may not exist, the log
+ * format may change, or the error may not be present. Callers
+ * should fall back to the generic message when this returns null.
+ */
+declare function extractServerError(): string | null;
+/**
+ * Enhance a generic "session error" message with details from the
+ * OpenCode server log. If the log contains a more specific error,
+ * returns that. Otherwise returns the original message unchanged.
+ */
+declare function enhanceSessionError(genericMessage: string): string;
+
+/**
+ * OpenCodeAdapter — implements AgentAdapter using the OpenCode SDK.
+ *
+ * Wraps the low-level opencode-server.ts functions into the AgentAdapter
+ * interface so the autopilot loop engine can drive OpenCode without
+ * importing the SDK directly.
+ */
+
+/**
+ * OpenCode implementation of AgentAdapter.
+ * Creates and manages OpenCode server instances.
+ */
+declare class OpenCodeAdapter implements AgentAdapter {
+    readonly name = "opencode";
+    start(opts: {
+        cwd: string;
+    }): Promise<AgentHandle>;
+    createSession(handle: AgentHandle, opts: {
+        agentName?: string;
+    }): Promise<string>;
+    sendAndWait(handle: AgentHandle, opts: {
+        sessionId: string;
+        message: string;
+        stallMs?: number;
+        abortSignal?: AbortSignal;
+        onToolCall?: (name: string, arg?: string) => void;
+        onTextDelta?: (chars: number) => void;
+        onCostUpdate?: (cost: number, tokens: {
+            input: number;
+            output: number;
+        }) => void;
+    }): Promise<AdapterSessionResult>;
+    getLastResponse(handle: AgentHandle, sessionId: string): Promise<string>;
+    getSessionCost(handle: AgentHandle, sessionId: string): Promise<number>;
+    getSessionStats(handle: AgentHandle, sessionId: string): Promise<{
+        cost: number;
+        tokensIn: number;
+        tokensOut: number;
+    }>;
+    shutdown(handle: AgentHandle): Promise<void>;
+    enhanceError(message: string): Promise<string>;
+}
+
+export { DEFAULT_STARTUP_TIMEOUT_MS, OpenCodeAdapter, type SessionResult as OpenCodeSessionResult, type StartedServer, createSession, enhanceSessionError, execFileP, extractServerError, getLastAssistantMessage, getSessionCost, getSessionStats, selfTest, sendAndWait, startServer, waitForIdle };