axexec 1.0.0

package/dist/agents/opencode/server-types.js

@@ -0,0 +1,293 @@
+/**
+ * SSE event types from OpenCode server mode.
+ *
+ * These types represent the events streamed via SSE from:
+ * `GET /event` endpoint on `opencode serve`
+ *
+ * The parser transforms these into normalized {@link AxexecEvent} types.
+ */
+import { z } from "zod";
+// =============================================================================
+// Session Events
+// =============================================================================
+/** Session info schema */
+const SessionInfo = z.object({
+    id: z.string(),
+    parentID: z.string().optional(),
+    title: z.string().optional(),
+    projectID: z.string().optional(),
+    share: z.string().optional(),
+    updated: z.number(),
+    created: z.number(),
+});
+/** session.created event */
+const SessionCreatedEvent = z.object({
+    type: z.literal("session.created"),
+    properties: z.object({
+        info: SessionInfo,
+    }),
+});
+/** session.updated event */
+const SessionUpdatedEvent = z.object({
+    type: z.literal("session.updated"),
+    properties: z.object({
+        info: SessionInfo,
+    }),
+});
+/** session.idle event - signals session has finished processing */
+const SessionIdleEvent = z.object({
+    type: z.literal("session.idle"),
+    properties: z.object({
+        sessionID: z.string(),
+    }),
+});
+/** Session status types */
+const SessionStatusInfo = z.discriminatedUnion("type", [
+    z.object({ type: z.literal("idle") }),
+    z.object({
+        type: z.literal("retry"),
+        attempt: z.number(),
+        message: z.string(),
+        next: z.number(),
+    }),
+    z.object({ type: z.literal("busy") }),
+]);
+/** session.status event */
+const SessionStatusEvent = z.object({
+    type: z.literal("session.status"),
+    properties: z.object({
+        sessionID: z.string(),
+        status: SessionStatusInfo,
+    }),
+});
+/** session.error event */
+const SessionErrorEvent = z.object({
+    type: z.literal("session.error"),
+    properties: z.object({
+        sessionID: z.string().optional(),
+        error: z
+            .object({
+            name: z.string(),
+            data: z
+                .looseObject({
+                message: z.string().optional(),
+                providerID: z.string().optional(),
+                statusCode: z.number().optional(),
+                isRetryable: z.boolean().optional(),
+            })
+                .optional(),
+        })
+            .optional(),
+    }),
+});
+// =============================================================================
+// Message Part Events
+// =============================================================================
+/** Token usage in step-finish parts */
+const StepTokens = z.object({
+    input: z.number(),
+    output: z.number(),
+    reasoning: z.number(),
+    cache: z.object({
+        read: z.number(),
+        write: z.number(),
+    }),
+});
+/** Text part */
+const TextPart = z.object({
+    id: z.string(),
+    sessionID: z.string(),
+    messageID: z.string(),
+    type: z.literal("text"),
+    text: z.string(),
+    synthetic: z.boolean().optional(),
+    ignored: z.boolean().optional(),
+    time: z
+        .object({
+        start: z.number(),
+        end: z.number().optional(),
+    })
+        .optional(),
+    metadata: z.record(z.string(), z.unknown()).optional(),
+});
+/** Reasoning part (chain-of-thought) */
+const ReasoningPart = z.object({
+    id: z.string(),
+    sessionID: z.string(),
+    messageID: z.string(),
+    type: z.literal("reasoning"),
+    text: z.string(),
+    time: z
+        .object({
+        start: z.number(),
+        end: z.number().optional(),
+    })
+        .optional(),
+    metadata: z.record(z.string(), z.unknown()).optional(),
+});
+/** Tool state - pending */
+const ToolStatePending = z.object({
+    status: z.literal("pending"),
+    input: z.record(z.string(), z.unknown()),
+    raw: z.string().optional(),
+});
+/** Tool state - running */
+const ToolStateRunning = z.object({
+    status: z.literal("running"),
+    input: z.record(z.string(), z.unknown()),
+    title: z.string().optional(),
+    metadata: z.record(z.string(), z.unknown()).optional(),
+    time: z.object({ start: z.number() }),
+});
+/** Tool state - completed */
+const ToolStateCompleted = z.object({
+    status: z.literal("completed"),
+    input: z.record(z.string(), z.unknown()),
+    output: z.string(),
+    title: z.string(),
+    metadata: z.record(z.string(), z.unknown()),
+    time: z.object({
+        start: z.number(),
+        end: z.number(),
+        compacted: z.number().optional(),
+    }),
+    attachments: z.array(z.unknown()).optional(),
+});
+/** Tool state - error */
+const ToolStateError = z.object({
+    status: z.literal("error"),
+    input: z.record(z.string(), z.unknown()),
+    error: z.string(),
+    metadata: z.record(z.string(), z.unknown()).optional(),
+    time: z.object({
+        start: z.number(),
+        end: z.number(),
+    }),
+});
+/** Tool state discriminated union */
+const ToolState = z.discriminatedUnion("status", [
+    ToolStatePending,
+    ToolStateRunning,
+    ToolStateCompleted,
+    ToolStateError,
+]);
+/** Tool part */
+const ToolPart = z.object({
+    id: z.string(),
+    sessionID: z.string(),
+    messageID: z.string(),
+    type: z.literal("tool"),
+    callID: z.string(),
+    tool: z.string(),
+    state: ToolState,
+    metadata: z.record(z.string(), z.unknown()).optional(),
+});
+/** Step-start part */
+const StepStartPart = z.object({
+    id: z.string(),
+    sessionID: z.string(),
+    messageID: z.string(),
+    type: z.literal("step-start"),
+    snapshot: z.string().optional(),
+});
+/** Step-finish part with cost and token data */
+const StepFinishPart = z.object({
+    id: z.string(),
+    sessionID: z.string(),
+    messageID: z.string(),
+    type: z.literal("step-finish"),
+    reason: z.string().optional(),
+    snapshot: z.string().optional(),
+    cost: z.number(),
+    tokens: StepTokens,
+});
+/** All part types */
+const Part = z.discriminatedUnion("type", [
+    TextPart,
+    ReasoningPart,
+    ToolPart,
+    StepStartPart,
+    StepFinishPart,
+]);
+/** message.part.updated event */
+const MessagePartUpdatedEvent = z.object({
+    type: z.literal("message.part.updated"),
+    properties: z.object({
+        part: Part,
+        delta: z.string().optional(),
+    }),
+});
+// =============================================================================
+// Permission Events
+// =============================================================================
+/** permission.updated event - requires user approval */
+const PermissionUpdatedEvent = z.object({
+    type: z.literal("permission.updated"),
+    properties: z.object({
+        id: z.string(),
+        sessionID: z.string(),
+        messageID: z.string().optional(),
+        title: z.string(),
+        description: z.string().optional(),
+        tool: z.string().optional(),
+        metadata: z.record(z.string(), z.unknown()).optional(),
+        time: z.object({
+            created: z.number(),
+            responded: z.number().optional(),
+        }),
+    }),
+});
+// =============================================================================
+// Server Events
+// =============================================================================
+/** server.connected event - first event on SSE connect */
+const ServerConnectedEvent = z.object({
+    type: z.literal("server.connected"),
+    properties: z.object({}),
+});
+/** server.heartbeat event - keepalive every 30s */
+const ServerHeartbeatEvent = z.object({
+    type: z.literal("server.heartbeat"),
+    properties: z.object({}),
+});
+// =============================================================================
+// Union Type
+// =============================================================================
+/** All SSE event types we handle */
+const OpenCodeSSEEvent = z.discriminatedUnion("type", [
+    // Server events
+    ServerConnectedEvent,
+    ServerHeartbeatEvent,
+    // Session events
+    SessionCreatedEvent,
+    SessionUpdatedEvent,
+    SessionIdleEvent,
+    SessionStatusEvent,
+    SessionErrorEvent,
+    // Message events
+    MessagePartUpdatedEvent,
+    // Permission events
+    PermissionUpdatedEvent,
+]);
+// =============================================================================
+// Type Guards
+// =============================================================================
+function isSessionCreatedEvent(event) {
+    return event.type === "session.created";
+}
+function isSessionIdleEvent(event) {
+    return event.type === "session.idle";
+}
+function isSessionErrorEvent(event) {
+    return event.type === "session.error";
+}
+function isMessagePartUpdatedEvent(event) {
+    return event.type === "message.part.updated";
+}
+function isPermissionUpdatedEvent(event) {
+    return event.type === "permission.updated";
+}
+// =============================================================================
+// Exports
+// =============================================================================
+export { OpenCodeSSEEvent, isMessagePartUpdatedEvent, isPermissionUpdatedEvent, isSessionCreatedEvent, isSessionErrorEvent, isSessionIdleEvent, };

package/dist/agents/opencode/session-api.d.ts

@@ -0,0 +1,56 @@
+/**
+ * OpenCode session API client.
+ *
+ * Handles session creation, prompt submission, and cleanup via HTTP API.
+ */
+/** Error thrown when session creation fails */
+declare class SessionCreateError extends Error {
+    readonly statusCode?: number;
+    constructor(message: string, statusCode?: number);
+}
+/** Error thrown when prompt submission fails */
+declare class PromptSubmitError extends Error {
+    readonly statusCode?: number;
+    constructor(message: string, statusCode?: number);
+}
+/** Response from POST /session */
+interface SessionResponse {
+    id: string;
+    title?: string;
+    parentID?: string;
+    projectID?: string;
+    updated: number;
+    created: number;
+}
+/** Model info extracted from messages */
+interface MessageModelInfo {
+    providerID: string;
+    modelID: string;
+}
+/**
+ * Creates a new session on the OpenCode server.
+ */
+declare function createSession(baseUrl: string, directory: string): Promise<SessionResponse>;
+/**
+ * Sends a prompt to an existing session.
+ *
+ * Uses prompt_async endpoint which returns immediately and processes
+ * the prompt asynchronously. Events are streamed via SSE.
+ */
+declare function sendPrompt(baseUrl: string, sessionId: string, prompt: string, directory: string, model?: string): Promise<void>;
+/**
+ * Aborts a running session with timeout.
+ */
+declare function abortSession(baseUrl: string, sessionId: string, directory: string): Promise<void>;
+/**
+ * Disposes the server instance with timeout.
+ */
+declare function disposeInstance(baseUrl: string, directory: string): Promise<void>;
+/**
+ * Queries messages for a session and extracts model info from the first assistant message.
+ *
+ * Returns undefined if no assistant message found or query fails.
+ */
+declare function getSessionModelInfo(baseUrl: string, sessionId: string, directory: string): Promise<MessageModelInfo | undefined>;
+export { PromptSubmitError, SessionCreateError, abortSession, createSession, disposeInstance, getSessionModelInfo, sendPrompt, };
+export type { MessageModelInfo };

package/dist/agents/opencode/session-api.js

@@ -0,0 +1,151 @@
+/**
+ * OpenCode session API client.
+ *
+ * Handles session creation, prompt submission, and cleanup via HTTP API.
+ */
+/** Error thrown when session creation fails */
+class SessionCreateError extends Error {
+    statusCode;
+    constructor(message, statusCode) {
+        super(message);
+        this.name = "SessionCreateError";
+        this.statusCode = statusCode;
+    }
+}
+/** Error thrown when prompt submission fails */
+class PromptSubmitError extends Error {
+    statusCode;
+    constructor(message, statusCode) {
+        super(message);
+        this.name = "PromptSubmitError";
+        this.statusCode = statusCode;
+    }
+}
+/** Parses "provider/model" string into components */
+function parseModel(model) {
+    const slashIndex = model.indexOf("/");
+    if (slashIndex === -1)
+        return undefined;
+    return {
+        providerID: model.slice(0, slashIndex),
+        modelID: model.slice(slashIndex + 1),
+    };
+}
+/**
+ * Creates a new session on the OpenCode server.
+ */
+async function createSession(baseUrl, directory) {
+    const response = await fetch(`${baseUrl}/session`, {
+        method: "POST",
+        headers: {
+            "Content-Type": "application/json",
+            "x-opencode-directory": directory,
+        },
+        body: JSON.stringify({}),
+    });
+    if (!response.ok) {
+        throw new SessionCreateError(`Failed to create session: ${response.status} ${response.statusText}`, response.status);
+    }
+    return (await response.json());
+}
+/**
+ * Sends a prompt to an existing session.
+ *
+ * Uses prompt_async endpoint which returns immediately and processes
+ * the prompt asynchronously. Events are streamed via SSE.
+ */
+async function sendPrompt(baseUrl, sessionId, prompt, directory, model) {
+    // Build request body
+    const body = {
+        parts: [{ type: "text", text: prompt }],
+    };
+    // Add model if provided and valid
+    if (model) {
+        const parsed = parseModel(model);
+        if (parsed) {
+            body.model = parsed;
+        }
+    }
+    const response = await fetch(`${baseUrl}/session/${sessionId}/prompt_async`, {
+        method: "POST",
+        headers: {
+            "Content-Type": "application/json",
+            "x-opencode-directory": directory,
+        },
+        body: JSON.stringify(body),
+    });
+    if (!response.ok) {
+        throw new PromptSubmitError(`Failed to send prompt: ${response.status} ${response.statusText}`, response.status);
+    }
+}
+/**
+ * Aborts a running session with timeout.
+ */
+async function abortSession(baseUrl, sessionId, directory) {
+    try {
+        await fetch(`${baseUrl}/session/${sessionId}/abort`, {
+            method: "POST",
+            headers: {
+                "x-opencode-directory": directory,
+            },
+            signal: AbortSignal.timeout(2000),
+        });
+    }
+    catch {
+        // Ignore errors during abort - server may already be down
+    }
+}
+/**
+ * Disposes the server instance with timeout.
+ */
+async function disposeInstance(baseUrl, directory) {
+    try {
+        await fetch(`${baseUrl}/instance/dispose`, {
+            method: "POST",
+            headers: {
+                "x-opencode-directory": directory,
+            },
+            signal: AbortSignal.timeout(2000),
+        });
+    }
+    catch {
+        // Ignore errors during dispose - server may already be down
+    }
+}
+/**
+ * Queries messages for a session and extracts model info from the first assistant message.
+ *
+ * Returns undefined if no assistant message found or query fails.
+ */
+async function getSessionModelInfo(baseUrl, sessionId, directory) {
+    try {
+        const response = await fetch(`${baseUrl}/session/${sessionId}/message`, {
+            method: "GET",
+            headers: {
+                "x-opencode-directory": directory,
+            },
+            signal: AbortSignal.timeout(2000),
+        });
+        if (!response.ok) {
+            return undefined;
+        }
+        const messages = (await response.json());
+        // Find the first assistant message
+        for (const message of messages) {
+            if (message.info.role === "assistant" &&
+                message.info.modelID &&
+                message.info.providerID) {
+                return {
+                    providerID: message.info.providerID,
+                    modelID: message.info.modelID,
+                };
+            }
+        }
+        return undefined;
+    }
+    catch {
+        // Ignore errors - caller will use fallback
+        return undefined;
+    }
+}
+export { PromptSubmitError, SessionCreateError, abortSession, createSession, disposeInstance, getSessionModelInfo, sendPrompt, };

package/dist/agents/opencode/spawn-server.d.ts

@@ -0,0 +1,29 @@
+/**
+ * OpenCode server spawning and management.
+ *
+ * Handles spawning the OpenCode server process and waiting for it to start.
+ */
+import type { ChildProcess } from "node:child_process";
+/** Error thrown when server fails to start */
+declare class ServerStartError extends Error {
+    constructor(message: string, cause?: Error);
+}
+/** Result of spawning the server */
+interface SpawnServerResult {
+    url: string;
+    process: ChildProcess;
+}
+/** Options for spawning the server */
+interface SpawnServerOptions {
+    cwd: string;
+    signal: AbortSignal;
+    /** Environment variables to pass to the server process */
+    env?: Record<string, string>;
+}
+/**
+ * Spawns OpenCode server and waits for it to start.
+ *
+ * @returns Server URL and process handle
+ */
+declare function spawnServer(options: SpawnServerOptions): Promise<SpawnServerResult>;
+export { ServerStartError, spawnServer };

package/dist/agents/opencode/spawn-server.js

@@ -0,0 +1,95 @@
+/**
+ * OpenCode server spawning and management.
+ *
+ * Handles spawning the OpenCode server process and waiting for it to start.
+ */
+import { spawn } from "node:child_process";
+import { resolveBinary } from "../../resolve-binary.js";
+/** Error thrown when server fails to start */
+class ServerStartError extends Error {
+    constructor(message, cause) {
+        super(message);
+        this.name = "ServerStartError";
+        this.cause = cause;
+    }
+}
+/**
+ * Spawns OpenCode server and waits for it to start.
+ *
+ * @returns Server URL and process handle
+ */
+async function spawnServer(options) {
+    const { cwd, signal, env } = options;
+    return new Promise((resolve, reject) => {
+        const bin = resolveBinary({
+            name: "opencode",
+            command: "opencode",
+            environmentVariable: "AXEXEC_OPENCODE_PATH",
+            installHint: "npm install -g opencode-ai",
+        });
+        const child = spawn(bin, ["serve", "--port", "0"], {
+            cwd,
+            stdio: ["ignore", "pipe", "pipe"],
+            env: { ...process.env, ...env },
+        });
+        let stderrBuffer = "";
+        let resolved = false;
+        // Cleanup function to remove all listeners
+        const cleanup = () => {
+            child.stdout.removeListener("data", onStdoutData);
+            child.stderr.removeListener("data", onStderrData);
+            child.removeListener("error", onError);
+            child.removeListener("close", onClose);
+            signal.removeEventListener("abort", onAbort);
+        };
+        // Handle spawn errors
+        const onError = (error) => {
+            cleanup();
+            if (error.code === "ENOENT") {
+                reject(new ServerStartError("OpenCode binary not found. Make sure opencode-ai is installed.", error));
+            }
+            else {
+                reject(new ServerStartError(`Failed to spawn OpenCode server`, error));
+            }
+        };
+        child.once("error", onError);
+        // Capture stderr for error messages
+        const onStderrData = (chunk) => {
+            stderrBuffer += chunk.toString();
+        };
+        child.stderr.on("data", onStderrData);
+        // Watch stdout for "listening on" message
+        let buffer = "";
+        const onStdoutData = (chunk) => {
+            buffer += chunk.toString();
+            // Parse "opencode server listening on http://127.0.0.1:XXXX"
+            const match = buffer.match(/opencode server listening on (https?:\/\/[^\s]+)/u);
+            if (match?.[1]) {
+                const url = match[1];
+                resolved = true;
+                cleanup();
+                resolve({ url, process: child });
+            }
+        };
+        child.stdout.on("data", onStdoutData);
+        // Handle early exit (including code 0 before URL is detected)
+        const onClose = (code) => {
+            if (resolved)
+                return; // Already resolved, ignore
+            cleanup();
+            const message = stderrBuffer.trim()
+                ? `Server exited with code ${code}: ${stderrBuffer}`
+                : `Server exited with code ${code} before startup complete`;
+            reject(new ServerStartError(message));
+        };
+        child.once("close", onClose);
+        // Handle abort signal
+        const onAbort = () => {
+            cleanup();
+            child.kill("SIGTERM");
+            reject(new ServerStartError("Server start aborted"));
+        };
+        signal.addEventListener("abort", onAbort, { once: true });
+    });
+}
+export { ServerStartError, spawnServer };

package/dist/agents/opencode/sse-client.d.ts

@@ -0,0 +1,33 @@
+/**
+ * SSE client for OpenCode server mode.
+ *
+ * Connects to the OpenCode server's /event endpoint and streams
+ * parsed SSE events.
+ */
+import type { OpenCodeSSEEvent } from "./server-types.js";
+/** Options for SSE client */
+interface SSEClientOptions {
+    /** Base URL of OpenCode server (e.g., "http://127.0.0.1:4096") */
+    baseUrl: string;
+    /** Working directory to set via header */
+    directory: string;
+    /** Abort signal for cancellation */
+    signal?: AbortSignal;
+    /** Callback to receive the reader for manual cancellation */
+    onReader?: (reader: ReadableStreamDefaultReader<Uint8Array>) => void;
+}
+/** Error when SSE connection fails */
+declare class SSEConnectionError extends Error {
+    readonly statusCode?: number;
+    constructor(message: string, statusCode?: number);
+}
+/**
+ * Connects to OpenCode server's SSE endpoint and yields events.
+ *
+ * The generator will yield events until:
+ * - The connection is closed by the server
+ * - The abort signal is triggered
+ * - An error occurs
+ */
+declare function streamSSE(options: SSEClientOptions): AsyncGenerator<OpenCodeSSEEvent>;
+export { SSEConnectionError, streamSSE };