@skelm/opencode 0.4.2 → 0.4.4

package/README.md

@@ -40,7 +40,7 @@ export default defineConfig({
 A workflow that applies a fix to a codebase:
 
 ```ts
-// workflows/fix-bug.workflow.ts
+// workflows/fix-bug.workflow.mts
 import { agent, pipeline } from 'skelm'
 import { z } from 'zod'
 
@@ -74,7 +74,7 @@ export default pipeline({
 ## What's exported
 
 ```ts
-export { createOpencodeBackend, createOpencodeAcpBackend } from './backend.js'
+export { createOpencodeBackend } from './backend.js'
 export { createOpencodeBackendFromConfig } from './factory.js'
 export { OpencodeProvider, createOpencodeProvider } from './provider.js'
 export { OpencodeClientWrapper } from './client.js'

package/dist/backend.d.ts

@@ -15,25 +15,17 @@ export declare function createOpencodeBackend(options: OpencodeBackendOptions):
  * Custom error types for opencode backend
  */
 export declare class BackendAuthenticationError extends Error {
-    constructor(message: string);
+    constructor(message: string, options?: {
+        cause?: unknown;
+    });
 }
 export declare class BackendRateLimitError extends Error {
-    constructor(message: string);
+    constructor(message: string, options?: {
+        cause?: unknown;
+    });
 }
 export declare class BackendTimeoutError extends Error {
-    constructor(message: string);
+    constructor(message: string, options?: {
+        cause?: unknown;
+    });
 }
-/**
- * Create an opencode backend with ACP compatibility mode
- *
- * This runs opencode as a subprocess via ACP instead of using the SDK directly.
- * Useful for testing or when API access is restricted.
- */
-export declare function createOpencodeAcpBackend(options: {
-    command?: string;
-    args?: readonly string[];
-    cwd?: string;
-    env?: NodeJS.ProcessEnv;
-    id?: string;
-    label?: string;
-}): SkelmBackend;

package/dist/backend.js

@@ -1,6 +1,6 @@
-import { loadSkillBodies } from '@skelm/core';
+import { PermissionDeniedError, loadSkillBodies } from '@skelm/core';
 import { OpencodeClientWrapper } from './client.js';
-import { buildPermissionAuditEntry, mapSkelmPermissionsToOpencode, validatePermissions, } from './permission-mapper.js';
+import { mapSkelmPermissionsToOpencode, validatePermissions } from './permission-mapper.js';
 /**
  * SkelmBackend implementation for opencode.ai with full permission enforcement
  *
@@ -20,6 +20,13 @@ export function createOpencodeBackend(options) {
         skills: true,
         modelSelection: options.model !== undefined,
         toolPermissions: 'native',
+        // Image content is threaded into opencode as a `FilePartInput` alongside
+        // the text part (see buildOpencodePromptParts in client.ts); whether the
+        // *upstream* model actually processes images depends on the configured
+        // opencode model (Sonnet, GPT-4o, etc. — see opencode docs). Set
+        // `vision: false` via the second capability block above if a deployment
+        // pins a known text-only model.
+        vision: options.vision ?? true,
     };
     // Single client instance per backend — server started on first call and
     // kept alive for subsequent calls (one session per prompt call).
@@ -40,14 +47,9 @@ export function createOpencodeBackend(options) {
                 }),
             });
             if (!permissionResult.allowed) {
-                // Log audit entry for denied permissions
-                const auditEntry = buildPermissionAuditEntry('unknown', // runId not available in BackendContext
-                'unknown', // stepId not available in AgentRequest
-                policy, permissionResult);
-                // In production, this would be written to the audit log
-                // For now, we log to console
-                console.warn('Permission denied:', JSON.stringify(auditEntry, null, 2));
-                throw new Error(`Permission denied: ${permissionResult.denied.join(', ')}`);
+                // Throw the typed error so the runner's audit writer (the single
+                // durable record) captures the denial; no parallel console log.
+                throw new PermissionDeniedError(`opencode: permission denied: ${permissionResult.denied.join(', ')}`);
             }
             // Load skills and inject into system prompt before forwarding
             const enrichedRequest = await injectSkills(request, context);
@@ -59,14 +61,20 @@ export function createOpencodeBackend(options) {
             }
             catch (error) {
                 if (error instanceof Error) {
+                    // The opencode SDK surfaces these conditions as plain Errors
+                    // with descriptive messages; substring matching is the only
+                    // signal available. The original error is attached as `cause`
+                    // so callers retain stack and any provider-specific fields.
                     if (error.message.includes('Authentication')) {
-                        throw new BackendAuthenticationError(`Opencode authentication failed: ${error.message}`);
+                        throw new BackendAuthenticationError(`Opencode authentication failed: ${error.message}`, { cause: error });
                     }
                     if (error.message.includes('Rate limit')) {
-                        throw new BackendRateLimitError(`Opencode rate limit exceeded: ${error.message}`);
+                        throw new BackendRateLimitError(`Opencode rate limit exceeded: ${error.message}`, {
+                            cause: error,
+                        });
                     }
                     if (error.message.includes('timed out')) {
-                        throw new BackendTimeoutError(error.message);
+                        throw new BackendTimeoutError(error.message, { cause: error });
                     }
                 }
                 throw error;
@@ -123,51 +131,20 @@ function createEmptyPolicy() {
  * Custom error types for opencode backend
  */
 export class BackendAuthenticationError extends Error {
-    constructor(message) {
-        super(message);
+    constructor(message, options) {
+        super(message, options);
         this.name = 'BackendAuthenticationError';
     }
 }
 export class BackendRateLimitError extends Error {
-    constructor(message) {
-        super(message);
+    constructor(message, options) {
+        super(message, options);
         this.name = 'BackendRateLimitError';
     }
 }
 export class BackendTimeoutError extends Error {
-    constructor(message) {
-        super(message);
+    constructor(message, options) {
+        super(message, options);
         this.name = 'BackendTimeoutError';
     }
 }
-/**
- * Create an opencode backend with ACP compatibility mode
- *
- * This runs opencode as a subprocess via ACP instead of using the SDK directly.
- * Useful for testing or when API access is restricted.
- */
-export function createOpencodeAcpBackend(options) {
-    const command = options.command ?? 'opencode';
-    const args = options.args ?? ['acp'];
-    const capabilities = {
-        prompt: true,
-        streaming: true,
-        sessionLifecycle: true,
-        mcp: true,
-        skills: false, // ACP mode has limited skill control
-        modelSelection: false,
-        toolPermissions: 'unsupported', // ACP forwards permissions as metadata only
-    };
-    const backend = {
-        id: options.id ?? 'opencode-acp',
-        capabilities,
-        ...(options.label !== undefined && { label: options.label }),
-        async run(request, context) {
-            // ACP mode: permissions are advisory only
-            // Forward the request to opencode via stdio
-            // This is a placeholder - full ACP implementation would use the AcpClient
-            throw new Error('ACP mode not yet implemented. Use SDK mode with createOpencodeBackend() instead.');
-        },
-    };
-    return backend;
-}

package/dist/client.js

@@ -8,7 +8,35 @@
 //   #3 — Non-blocking promptAsync + SSE stream instead of blocking session.prompt()
 import { spawn } from 'node:child_process'; // @subprocess-ok: spawns opencode serve for HTTP backend
 import { createOpencodeClient } from '@opencode-ai/sdk';
-import { TrustEnforcer } from '@skelm/core';
+import { BackendSessionError, RunCancelledError, TrustEnforcer, extractPromptText, } from '@skelm/core';
+/**
+ * Map a skelm `AgentRequest.prompt` (string or `ContentPart[]`) onto
+ * opencode's prompt-parts shape. Text parts become `{type:'text'}`; image
+ * parts are forwarded as `{type:'file'}` with a base64 data URL, matching
+ * the opencode SDK's documented `FilePartInput` schema. opencode's own
+ * vision-capable models (Sonnet, GPT-4o, etc.) consume these attachments
+ * directly; non-vision models surface their own provider error which
+ * propagates as a thrown step failure.
+ */
+function buildOpencodePromptParts(prompt) {
+    if (typeof prompt === 'string') {
+        return [{ type: 'text', text: prompt }];
+    }
+    const parts = [];
+    for (const part of prompt) {
+        if (part.type === 'text') {
+            parts.push({ type: 'text', text: part.text });
+        }
+        else if (part.type === 'image') {
+            parts.push({
+                type: 'file',
+                mime: part.mimeType,
+                url: `data:${part.mimeType};base64,${part.data}`,
+            });
+        }
+    }
+    return parts.length > 0 ? parts : [{ type: 'text', text: extractPromptText(prompt) }];
+}
 // Module-singleton process-exit hook. Without this, every OpencodeClientWrapper
 // that called process.once('SIGTERM', …) would add a fresh listener, tripping
 // Node's MaxListeners=10 warning under any non-trivial backend churn. Wrappers
@@ -104,20 +132,32 @@ export class OpencodeClientWrapper {
             liveChildren.add(proc);
             ensureSignalHook();
             let resolved = false;
-            let buf = '';
-            const tryParse = (chunk) => {
+            let stdoutBuf = '';
+            const MAX_BUF_BYTES = 64 * 1024;
+            // opencode prints its listen URL on stdout. Parse stdout only and
+            // anchor strictly to a loopback URL so noisy stderr (or LLM output
+            // proxied through stderr) cannot redirect the gateway to an
+            // attacker-controlled URL. The buffer is capped so a flood of
+            // non-matching output can't be retained indefinitely.
+            const LISTEN_RE = /(?:^|\n)opencode(?: \w+)? listening on (https?:\/\/(?:127\.0\.0\.1|localhost|\[::1\]):\d+)(?=\s|$)/;
+            const tryParseStdout = (chunk) => {
                 if (resolved)
                     return;
-                buf += chunk.toString();
-                const m = buf.match(/listening on (https?:\/\/[^\s]+)/);
+                stdoutBuf += chunk.toString('utf8');
+                if (stdoutBuf.length > MAX_BUF_BYTES) {
+                    stdoutBuf = stdoutBuf.slice(stdoutBuf.length - MAX_BUF_BYTES);
+                }
+                const m = stdoutBuf.match(LISTEN_RE);
                 if (m?.[1]) {
                     resolved = true;
                     this.client = createOpencodeClient({ baseUrl: m[1].trim() });
                     resolve();
                 }
             };
-            proc.stdout?.on('data', tryParse);
-            proc.stderr?.on('data', tryParse);
+            proc.stdout?.on('data', tryParseStdout);
+            // stderr is consumed only to drain the pipe and avoid backpressure;
+            // its content is no longer parsed for the listen URL.
+            proc.stderr?.on('data', () => { });
             proc.once('error', (err) => {
                 if (!resolved)
                     reject(err);
@@ -147,7 +187,7 @@ export class OpencodeClientWrapper {
     async prompt(request, signal, timeoutMs = 300_000, resolvedPolicy, onPartial) {
         await this.ensureStarted();
         if (!this.client)
-            throw new Error('opencode serve not ready');
+            throw new BackendSessionError('opencode serve not ready', 'opencode');
         const cwd = request.cwd ?? process.cwd();
         // Forward each per-step McpServerConfig to opencode so its model sees the
         // namespaced tools. The opencode subprocess persists across calls, so the
@@ -158,7 +198,7 @@ export class OpencodeClientWrapper {
         }
         const sessResult = await this.client.session.create({ query: { directory: cwd } });
         if (!sessResult.data) {
-            throw new Error(`session.create failed: ${JSON.stringify(sessResult.error)}`);
+            throw new BackendSessionError(`session.create failed: ${JSON.stringify(sessResult.error)}`, 'opencode', { cause: sessResult.error });
         }
         const sessionId = sessResult.data.id;
         // (#3) Subscribe to the global SSE stream BEFORE calling promptAsync so
@@ -174,7 +214,7 @@ export class OpencodeClientWrapper {
             const promptResult = await this.client.session.promptAsync({
                 path: { id: sessionId },
                 body: {
-                    parts: [{ type: 'text', text: request.prompt }],
+                    parts: buildOpencodePromptParts(request.prompt),
                     ...(request.system !== undefined && { system: request.system }),
                     ...(resolvedPolicy !== undefined && {
                         tools: buildOpencodeToolsFromPolicy(resolvedPolicy),
@@ -182,7 +222,7 @@ export class OpencodeClientWrapper {
                 },
             });
             if (!promptResult.data) {
-                throw new Error(`session.promptAsync failed: ${JSON.stringify(promptResult.error)}`);
+                throw new BackendSessionError(`session.promptAsync failed: ${JSON.stringify(promptResult.error)}`, 'opencode', { cause: promptResult.error });
             }
             return await this._collectFromStream(stream, sessionId, signal, onPartial, resolvedPolicy);
         }
@@ -209,7 +249,7 @@ export class OpencodeClientWrapper {
             if (event.type === 'session.error') {
                 const props = event.properties;
                 if (!props.sessionID || props.sessionID === sessionId) {
-                    throw new Error(`opencode session error: ${JSON.stringify(props.error)}`);
+                    throw new BackendSessionError(`opencode session error: ${JSON.stringify(props.error)}`, 'opencode', { cause: props.error });
                 }
             }
             // Opencode pauses the session and emits permission.asked when a tool
@@ -260,7 +300,7 @@ export class OpencodeClientWrapper {
             }
         }
         if (signal.aborted)
-            throw new Error('opencode agent aborted');
+            throw new RunCancelledError();
         const text = [...textParts.values()].join('');
         return { text: text.trim(), stopReason: 'end_turn' };
     }
@@ -276,7 +316,7 @@ export class OpencodeClientWrapper {
             if (this.attachedMcp.has(server.id))
                 continue;
             if (server.transport !== 'stdio') {
-                throw new Error(`opencode backend currently only forwards stdio MCP servers; "${server.id}" uses ${server.transport}`);
+                throw new BackendSessionError(`opencode backend currently only forwards stdio MCP servers; "${server.id}" uses ${server.transport}`, 'opencode');
             }
             const command = [server.command, ...(server.args ?? [])];
             const result = await this.client.mcp.add({
@@ -291,7 +331,7 @@ export class OpencodeClientWrapper {
                 },
             });
             if (result.error !== undefined) {
-                throw new Error(`opencode mcp.add(${server.id}) failed: ${JSON.stringify(result.error)}`);
+                throw new BackendSessionError(`opencode mcp.add(${server.id}) failed: ${JSON.stringify(result.error)}`, 'opencode', { cause: result.error });
             }
             this.attachedMcp.add(server.id);
         }

package/dist/index.d.ts

@@ -4,7 +4,7 @@
  * Full integration with opencode.ai coding agent via the official SDK,
  * with granular permission enforcement and multi-agent support.
  */
-export { createOpencodeBackend, createOpencodeAcpBackend } from './backend.js';
+export { createOpencodeBackend } from './backend.js';
 export { createOpencodeBackendFromConfig } from './factory.js';
 export type { OpencodeBackendConfig } from './factory.js';
 export { OpencodeProvider, createOpencodeProvider } from './provider.js';

package/dist/index.js

@@ -4,7 +4,7 @@
  * Full integration with opencode.ai coding agent via the official SDK,
  * with granular permission enforcement and multi-agent support.
  */
-export { createOpencodeBackend, createOpencodeAcpBackend } from './backend.js';
+export { createOpencodeBackend } from './backend.js';
 export { createOpencodeBackendFromConfig } from './factory.js';
 export { OpencodeProvider, createOpencodeProvider } from './provider.js';
 export { OpencodeClientWrapper } from './client.js';

package/dist/provider.js

@@ -3,7 +3,7 @@
  *
  * Implements ProviderPluginBase for the opencode.ai coding agent.
  */
-import { ProviderPluginBase } from '@skelm/core';
+import { BackendConfigError, ProviderPluginBase } from '@skelm/core';
 import { createOpencodeBackend } from './backend.js';
 /**
  * Opencode provider implementation
@@ -83,7 +83,7 @@ export class OpencodeProvider extends ProviderPluginBase {
         // Validate API key
         const apiKey = config.apiKey ?? process.env.OPENCODE_API_KEY;
         if (!apiKey) {
-            throw new Error('Opencode API key is required. Set apiKey config or OPENCODE_API_KEY env var.');
+            throw new BackendConfigError('Opencode API key is required. Set apiKey config or OPENCODE_API_KEY env var.', 'opencode');
         }
     }
     /**
@@ -91,7 +91,7 @@ export class OpencodeProvider extends ProviderPluginBase {
      */
     async createBackend(options) {
         if (!this.initialized) {
-            throw new Error('Provider must be initialized before creating backends');
+            throw new BackendConfigError('Provider must be initialized before creating backends', 'opencode');
         }
         const config = {};
         const apiKey = this.config.apiKey ?? process.env.OPENCODE_API_KEY;
@@ -199,7 +199,7 @@ export class OpencodeProvider extends ProviderPluginBase {
     validateConfig(config) {
         const apiKey = config.apiKey ?? process.env.OPENCODE_API_KEY;
         if (!apiKey) {
-            throw new Error('Opencode API key is required');
+            throw new BackendConfigError('Opencode API key is required', 'opencode');
         }
         return config;
     }

package/dist/types.d.ts

@@ -28,6 +28,14 @@ export interface OpencodeBackendOptions {
     maxRetries?: number;
     /** Log level */
     logLevel?: 'debug' | 'info' | 'warn' | 'error' | 'off';
+    /**
+     * Advertise `capabilities.vision`. Defaults to `true`: image content is
+     * forwarded to opencode as a `FilePartInput` and the upstream model
+     * decides whether it can process it. Set `false` when targeting an
+     * opencode model known to be text-only — the framework gate then rejects
+     * image prompts at step start with no opencode session ever spawned.
+     */
+    vision?: boolean;
     /** Egress proxy URL for outbound HTTP requests (e.g., 'http://127.0.0.1:14739'). */
     egressProxyUrl?: string;
     /** Egress token for proxy authentication (injected into subprocesses). */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@skelm/opencode",
-  "version": "0.4.2",
+  "version": "0.4.4",
   "description": "Opencode.ai backend for skelm with full permission enforcement",
   "license": "MIT",
   "author": "Scott Glover <scottgl@gmail.com>",
@@ -48,10 +48,10 @@
     "@opencode-ai/sdk": "^1.14.33"
   },
   "peerDependencies": {
-    "@skelm/core": "^0.4.2"
+    "@skelm/core": "^0.4.4"
   },
   "devDependencies": {
-    "@skelm/core": "^0.4.2",
+    "@skelm/core": "^0.4.4",
     "@types/node": "^20.10.0",
     "typescript": "^5.3.0",
     "vitest": "^1.0.0"