@swarmclawai/swarmclaw 1.5.41 → 1.5.42

package/README.md

@@ -389,6 +389,12 @@ Operational docs: https://swarmclaw.ai/docs/observability
 
 ## Releases
 
+### v1.5.42 Highlights
+
+- **New `opencode-web` provider — connect to remote OpenCode HTTP servers** ([#40](https://github.com/swarmclawai/swarmclaw/issues/40), requested by [@SteamedFish](https://github.com/SteamedFish)): point an agent at any host running `opencode serve` or `opencode web` (default port `4096`). Supports HTTPS endpoints, HTTP Basic Auth (encode credentials as `username:password` in the API key field; bare passwords default the username to `opencode`), automatic OpenCode session reuse across chat turns, and per-session workspace isolation via `?directory=...`. Models are entered as `providerID/modelID` (e.g. `anthropic/claude-sonnet-4-5`). The existing `opencode-cli` provider is unchanged.
+- **New `CONTRIBUTING.md`**: short, scannable guide covering bug reports, feature requests, PR expectations, commit conventions, and where to look in the codebase. Models the gold-standard examples after issues #39 and #40.
+- **`GET /api/memory/:id` now returns a single entry by default**: previously it eagerly traversed linked memories and returned an array, which broke naive callers that expected a single object per REST convention. Linked traversal is now opt-in via `?depth=N` or `?envelope=true`.
+
 ### v1.5.41 Highlights
 
 - **Moonshot / Kimi compatibility — duplicate `files` tool name fixed**: any agent with the default `files` extension was sending two tools both literally named `files` to the LLM. Most providers tolerated the duplicate; Moonshot's strict tool-schema validation rejected it with `MoonshotException - function name files is duplicated` ([#39](https://github.com/swarmclawai/swarmclaw/issues/39), reported by [@SteamedFish](https://github.com/SteamedFish)). Three fixes: the v2 file builder is now correctly gated on `files_v2` (not `files`), it registers under the matching capability key, and the session-tools assembler now shares a single dedup Set across native, CRUD, and extension phases so any future name collision is rejected with a clear warning instead of a silent double-register.
@@ -422,14 +428,6 @@ Operational docs: https://swarmclaw.ai/docs/observability
 - **OpenClaw gateway: fast-fail on dangling credentials**: when an agent's OpenClaw route references a deleted or missing credential, the gateway now refuses to dial the WebSocket up front instead of attempting an unauthenticated handshake and waiting the full 120 s for the agent-side timeout. The credential-missing log line is promoted from warn to error so it surfaces in routine monitoring.
 - **Prompt size profiler**: setting `SWARMCLAW_PROFILE_PROMPT=1` now logs a per-section size breakdown of the assembled system prompt (block index, first-line label, char count) on every turn, making it practical to diagnose why a specific agent is eating context budget. Off by default so production turns stay quiet.
 
-### v1.5.37 Highlights
-
-- **Factory Droid CLI as a provider and delegation backend**: adds [`droid`](https://docs.factory.ai/cli/droid-exec/overview) as a first-class chat provider and `delegate` backend with streaming JSON output, session resume, and a conservative `--auto low` autonomy pin on the delegate path. Install `droid` and sign in via browser (or set `FACTORY_API_KEY`), then pick **Factory Droid CLI** in the setup wizard. Resolves #38.
-- **Desktop Release CI hardening**: v1.5.36's Electron build workflow failed on all three platforms. This release:
-  - Adds a proper `author` with email to `package.json` and a `linux.maintainer` entry in `electron-builder.yml` so the Linux `.deb` target stops rejecting the build.
-  - Pins `outputFileTracingRoot` in `next.config.ts` to the project root so the Next.js build no longer walks `C:\Users\<user>\Application Data` (a legacy NTFS junction that throws EPERM on Windows runners).
-  - Pins Python 3.11 in the desktop-release workflow so `node-gyp` rebuilds of native modules (`node-liblzma`, etc.) succeed on Python 3.12+ runners where `distutils` was removed from the stdlib.
-
 Older releases: https://swarmclaw.ai/docs/release-notes
 
 - GitHub releases: https://github.com/swarmclawai/swarmclaw/releases

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@swarmclawai/swarmclaw",
-  "version": "1.5.41",
+  "version": "1.5.42",
   "description": "Build and run autonomous AI agents with OpenClaw, Hermes, multiple model providers, orchestration, delegation, memory, skills, schedules, and chat connectors.",
   "main": "electron-dist/main.js",
   "license": "MIT",

package/src/app/api/memory/[id]/route.ts

@@ -35,8 +35,13 @@ export async function GET(req: Request, { params }: { params: Promise<{ id: stri
   const requestedLinkedLimit = parseOptionalInt(searchParams.get('linkedLimit'))
   const db = getMemoryDb()
   const defaults = getMemoryLookupLimits()
+  // By default, GET /memory/:id returns a single entry (REST convention).
+  // Linked-traversal is opt-in via ?depth=N or ?envelope=true — previously
+  // this endpoint returned an array of linked entries by default, which
+  // broke every naive caller that expected a single object.
+  const linkedTraversalRequested = requestedDepth !== undefined || envelope
   const limits = resolveLookupRequest(defaults, {
-    depth: requestedDepth,
+    depth: linkedTraversalRequested ? requestedDepth : 0,
     limit: requestedLimit,
     linkedLimit: requestedLinkedLimit,
   })

package/src/lib/provider-sets.ts

@@ -1,5 +1,5 @@
 /** CLI providers that use their own tool execution outside the shared tool-runtime path. */
-export const NON_LANGGRAPH_PROVIDER_IDS = new Set(['claude-cli', 'codex-cli', 'opencode-cli', 'gemini-cli', 'copilot-cli', 'droid-cli', 'cursor-cli', 'qwen-code-cli'])
+export const NON_LANGGRAPH_PROVIDER_IDS = new Set(['claude-cli', 'codex-cli', 'opencode-cli', 'opencode-web', 'gemini-cli', 'copilot-cli', 'droid-cli', 'cursor-cli', 'qwen-code-cli'])
 
 /** Providers that manage their own runtime/tool loop even when reached over an API endpoint. */
 export const RUNTIME_MANAGED_PROVIDER_IDS = new Set(['hermes', 'goose'])

package/src/lib/providers/index.ts

@@ -1,6 +1,7 @@
 import { streamClaudeCliChat } from './claude-cli'
 import { streamCodexCliChat } from './codex-cli'
 import { streamOpenCodeCliChat } from './opencode-cli'
+import { streamOpenCodeWebChat } from './opencode-web'
 import { streamGeminiCliChat } from './gemini-cli'
 import { streamCopilotCliChat } from './copilot-cli'
 import { streamDroidCliChat } from './droid-cli'
@@ -136,6 +137,18 @@ export const PROVIDERS: Record<string, BuiltinProviderConfig> = {
     requiresEndpoint: false,
     handler: { streamChat: streamOpenCodeCliChat },
   },
+  'opencode-web': {
+    id: 'opencode-web',
+    name: 'OpenCode Web',
+    // OpenCode addresses models as `providerID/modelID`. Free-text entry is
+    // supported; these defaults seed the dropdown with common combinations.
+    models: ['anthropic/claude-sonnet-4-5', 'anthropic/claude-opus-4-5', 'openai/gpt-4.1', 'openai/o4-mini', 'google/gemini-2.5-pro'],
+    requiresApiKey: false,
+    optionalApiKey: true,
+    requiresEndpoint: true,
+    defaultEndpoint: 'http://localhost:4096',
+    handler: { streamChat: streamOpenCodeWebChat },
+  },
   'gemini-cli': {
     id: 'gemini-cli',
     name: 'Gemini CLI',

package/src/lib/providers/opencode-web.test.ts

@@ -0,0 +1,113 @@
+import { describe, it } from 'node:test'
+import assert from 'node:assert/strict'
+import {
+  parseBasicAuth,
+  buildAuthHeader,
+  parseModelId,
+  joinUrl,
+  SseLineParser,
+} from '@/lib/providers/opencode-web'
+
+describe('opencode-web parseBasicAuth', () => {
+  it('returns null for null / undefined / empty / whitespace', () => {
+    assert.equal(parseBasicAuth(null), null)
+    assert.equal(parseBasicAuth(undefined), null)
+    assert.equal(parseBasicAuth(''), null)
+    assert.equal(parseBasicAuth('   '), null)
+  })
+
+  it('treats a value with no colon as the password and defaults the username to "opencode"', () => {
+    assert.deepEqual(parseBasicAuth('mypass'), { username: 'opencode', password: 'mypass' })
+  })
+
+  it('splits on the first colon and preserves later colons in the password', () => {
+    assert.deepEqual(parseBasicAuth('bob:secret'), { username: 'bob', password: 'secret' })
+    assert.deepEqual(parseBasicAuth('bob:s3cr:et'), { username: 'bob', password: 's3cr:et' })
+  })
+
+  it('handles empty halves', () => {
+    assert.deepEqual(parseBasicAuth('bob:'), { username: 'bob', password: '' })
+    assert.deepEqual(parseBasicAuth(':secret'), { username: '', password: 'secret' })
+  })
+})
+
+describe('opencode-web buildAuthHeader', () => {
+  it('returns undefined for null', () => {
+    assert.equal(buildAuthHeader(null), undefined)
+  })
+
+  it('builds RFC-compliant Basic auth from username:password', () => {
+    const header = buildAuthHeader({ username: 'opencode', password: 'mypass' })
+    assert.equal(header, `Basic ${Buffer.from('opencode:mypass').toString('base64')}`)
+  })
+
+  it('round-trips with parseBasicAuth for a custom user', () => {
+    const parsed = parseBasicAuth('bob:secret')
+    assert.equal(buildAuthHeader(parsed), `Basic ${Buffer.from('bob:secret').toString('base64')}`)
+  })
+})
+
+describe('opencode-web parseModelId', () => {
+  it('splits providerID/modelID on the first slash', () => {
+    assert.deepEqual(parseModelId('anthropic/claude-sonnet-4-5'), { providerID: 'anthropic', modelID: 'claude-sonnet-4-5' })
+    assert.deepEqual(parseModelId('openai/gpt-4.1'), { providerID: 'openai', modelID: 'gpt-4.1' })
+  })
+
+  it('preserves slashes inside the modelID', () => {
+    assert.deepEqual(parseModelId('local/qwen/coder-14b'), { providerID: 'local', modelID: 'qwen/coder-14b' })
+  })
+
+  it('returns providerID-only when the user enters a bare string (server will reject with a real error)', () => {
+    assert.deepEqual(parseModelId('claude-sonnet-4-5'), { providerID: 'claude-sonnet-4-5', modelID: '' })
+  })
+
+  it('handles empty / whitespace input', () => {
+    assert.deepEqual(parseModelId(''), { providerID: '', modelID: '' })
+    assert.deepEqual(parseModelId('   '), { providerID: '', modelID: '' })
+    assert.deepEqual(parseModelId(undefined), { providerID: '', modelID: '' })
+  })
+})
+
+describe('opencode-web joinUrl', () => {
+  it('handles trailing and leading slashes idempotently', () => {
+    assert.equal(joinUrl('http://localhost:4096', '/session'), 'http://localhost:4096/session')
+    assert.equal(joinUrl('http://localhost:4096/', '/session'), 'http://localhost:4096/session')
+    assert.equal(joinUrl('http://localhost:4096/', 'session'), 'http://localhost:4096/session')
+    assert.equal(joinUrl('http://localhost:4096///', '///session'), 'http://localhost:4096///session')
+  })
+})
+
+describe('opencode-web SseLineParser', () => {
+  it('emits one event per data: line and ignores comments / event: / id:', () => {
+    const events: unknown[] = []
+    const parser = new SseLineParser()
+    parser.feed(
+      ':keepalive\nevent: message\ndata: {"type":"text-delta","text":"hi"}\nid: 1\n\n',
+      (ev) => events.push(ev),
+    )
+    assert.deepEqual(events, [{ type: 'text-delta', text: 'hi' }])
+  })
+
+  it('buffers across chunk boundaries (split mid-line)', () => {
+    const events: unknown[] = []
+    const parser = new SseLineParser()
+    parser.feed('data: {"type":"text-delta","text":"he', (ev) => events.push(ev))
+    assert.equal(events.length, 0, 'incomplete line should not emit')
+    parser.feed('llo"}\n', (ev) => events.push(ev))
+    assert.deepEqual(events, [{ type: 'text-delta', text: 'hello' }])
+  })
+
+  it('tolerates CRLF line endings and skips blank data: lines', () => {
+    const events: unknown[] = []
+    const parser = new SseLineParser()
+    parser.feed('data: {"type":"x","v":1}\r\ndata: \r\ndata: {"type":"y","v":2}\r\n', (ev) => events.push(ev))
+    assert.deepEqual(events, [{ type: 'x', v: 1 }, { type: 'y', v: 2 }])
+  })
+
+  it('silently ignores malformed JSON payloads (heartbeats, partial frames)', () => {
+    const events: unknown[] = []
+    const parser = new SseLineParser()
+    parser.feed('data: not json\ndata: {"type":"text-delta","text":"ok"}\n', (ev) => events.push(ev))
+    assert.deepEqual(events, [{ type: 'text-delta', text: 'ok' }])
+  })
+})

package/src/lib/providers/opencode-web.ts

@@ -0,0 +1,307 @@
+import type { StreamChatOptions } from './index'
+import { log } from '../server/logger'
+
+const TAG = 'opencode-web'
+
+const DEFAULT_ENDPOINT = 'http://localhost:4096'
+const DEFAULT_USERNAME = 'opencode'
+
+interface BasicAuth { username: string; password: string }
+
+/**
+ * Parse an apiKey field into HTTP Basic Auth components. Stored as a single
+ * encrypted string per the project-wide credential model.
+ *
+ * - null / empty → no auth header.
+ * - "user:pass"   → { username: 'user', password: 'pass' }
+ * - "pass"        → { username: 'opencode', password: 'pass' } (FR-10).
+ *
+ * Mirrors RFC 3986 userinfo and `curl -u` conventions so the format is
+ * unsurprising and self-documenting in the credential field placeholder.
+ */
+export function parseBasicAuth(apiKey: string | null | undefined): BasicAuth | null {
+  if (apiKey === null || apiKey === undefined) return null
+  const trimmed = apiKey.trim()
+  if (!trimmed) return null
+  const colon = trimmed.indexOf(':')
+  if (colon < 0) return { username: DEFAULT_USERNAME, password: trimmed }
+  return { username: trimmed.slice(0, colon), password: trimmed.slice(colon + 1) }
+}
+
+export function buildAuthHeader(auth: BasicAuth | null): string | undefined {
+  if (!auth) return undefined
+  const encoded = Buffer.from(`${auth.username}:${auth.password}`, 'utf8').toString('base64')
+  return `Basic ${encoded}`
+}
+
+/**
+ * Split a SwarmClaw model string into the `{ providerID, modelID }` shape
+ * OpenCode expects. The convention is a single forward slash:
+ *   "anthropic/claude-sonnet-4-5" → { providerID: 'anthropic', modelID: 'claude-sonnet-4-5' }
+ *
+ * If the user enters a bare string with no slash, send providerID=value and
+ * an empty modelID so OpenCode rejects with a real error rather than us
+ * guessing wrong. Whitespace is trimmed.
+ */
+export function parseModelId(model: string | null | undefined): { providerID: string; modelID: string } {
+  const trimmed = (model || '').trim()
+  if (!trimmed) return { providerID: '', modelID: '' }
+  const slash = trimmed.indexOf('/')
+  if (slash < 0) return { providerID: trimmed, modelID: '' }
+  return {
+    providerID: trimmed.slice(0, slash).trim(),
+    modelID: trimmed.slice(slash + 1).trim(),
+  }
+}
+
+export function joinUrl(baseUrl: string, path: string): string {
+  const base = baseUrl.replace(/\/+$/, '')
+  const suffix = path.startsWith('/') ? path : `/${path}`
+  return `${base}${suffix}`
+}
+
+/**
+ * Stateful SSE line parser. Buffers across chunk boundaries and emits
+ * one parsed JSON object per `data:` line. Lines that do not start with
+ * `data:` (comments, `event:`, `id:`, blank separators) are ignored.
+ */
+export class SseLineParser {
+  private buf = ''
+
+  feed(chunk: string, onEvent: (data: unknown) => void): void {
+    this.buf += chunk
+    const lines = this.buf.split('\n')
+    this.buf = lines.pop() ?? ''
+    for (const raw of lines) {
+      const line = raw.replace(/\r$/, '').trim()
+      if (!line.startsWith('data:')) continue
+      const payload = line.slice(5).trim()
+      if (!payload) continue
+      try {
+        onEvent(JSON.parse(payload))
+      } catch {
+        // Non-JSON SSE payload (heartbeat, keep-alive). Ignore.
+      }
+    }
+  }
+}
+
+/**
+ * Best-effort extraction of streamed text out of an OpenCode SSE event.
+ * The shape varies a bit between versions; we accept the common variants
+ * and return null for everything else.
+ */
+function extractTextDelta(ev: unknown): string | null {
+  if (!ev || typeof ev !== 'object') return null
+  const e = ev as Record<string, unknown>
+  if (typeof e.text === 'string' && (e.type === 'text-delta' || e.type === 'text' || e.type === 'message.update.delta')) {
+    return e.text
+  }
+  if (e.type === 'message.update.delta' && typeof (e.delta as Record<string, unknown>)?.text === 'string') {
+    return (e.delta as Record<string, unknown>).text as string
+  }
+  if (e.type === 'text' && typeof (e.part as Record<string, unknown>)?.text === 'string') {
+    return (e.part as Record<string, unknown>).text as string
+  }
+  return null
+}
+
+function isCompletionEvent(ev: unknown): boolean {
+  if (!ev || typeof ev !== 'object') return false
+  const t = (ev as Record<string, unknown>).type
+  return t === 'message.complete' || t === 'message.completed' || t === 'done' || t === 'response.completed'
+}
+
+function extractErrorMessage(ev: unknown): string | null {
+  if (!ev || typeof ev !== 'object') return null
+  const e = ev as Record<string, unknown>
+  if (e.type !== 'error') return null
+  if (typeof e.message === 'string') return e.message
+  if (typeof e.error === 'string') return e.error
+  return 'Unknown OpenCode event error'
+}
+
+interface CreateSessionResponse { id?: string; sessionID?: string; sessionId?: string }
+
+async function createSession(opts: {
+  endpoint: string
+  cwd: string
+  authHeader: string | undefined
+  signal: AbortSignal
+}): Promise<string> {
+  const url = `${joinUrl(opts.endpoint, '/session')}?directory=${encodeURIComponent(opts.cwd)}`
+  const res = await fetch(url, {
+    method: 'POST',
+    headers: {
+      'Content-Type': 'application/json',
+      ...(opts.authHeader ? { Authorization: opts.authHeader } : {}),
+    },
+    body: '{}',
+    signal: opts.signal,
+  })
+  if (res.status === 401 || res.status === 403) {
+    throw new HttpError(res.status, 'OpenCode rejected the credentials. Check the username:password configured for this agent.')
+  }
+  if (!res.ok) {
+    const body = await safeReadText(res)
+    throw new HttpError(res.status, `OpenCode session create failed (HTTP ${res.status})${body ? `: ${body.slice(0, 200)}` : ''}`)
+  }
+  const json = (await res.json()) as CreateSessionResponse
+  const id = json.id || json.sessionID || json.sessionId
+  if (!id || typeof id !== 'string') {
+    throw new HttpError(0, 'OpenCode session create response did not include an id')
+  }
+  return id
+}
+
+async function postPrompt(opts: {
+  endpoint: string
+  sessionId: string
+  cwd: string
+  prompt: string
+  providerID: string
+  modelID: string
+  authHeader: string | undefined
+  signal: AbortSignal
+}): Promise<{ status: number }> {
+  const url = `${joinUrl(opts.endpoint, `/session/${encodeURIComponent(opts.sessionId)}/prompt_async`)}?directory=${encodeURIComponent(opts.cwd)}`
+  const res = await fetch(url, {
+    method: 'POST',
+    headers: {
+      'Content-Type': 'application/json',
+      ...(opts.authHeader ? { Authorization: opts.authHeader } : {}),
+    },
+    body: JSON.stringify({
+      providerID: opts.providerID,
+      modelID: opts.modelID,
+      prompt: opts.prompt,
+    }),
+    signal: opts.signal,
+  })
+  if (res.status === 401 || res.status === 403) {
+    throw new HttpError(res.status, 'OpenCode rejected the credentials. Check the username:password configured for this agent.')
+  }
+  if (res.status !== 204 && res.status !== 200 && res.status !== 202) {
+    if (res.status === 404) return { status: 404 }
+    const body = await safeReadText(res)
+    throw new HttpError(res.status, `OpenCode prompt_async failed (HTTP ${res.status})${body ? `: ${body.slice(0, 200)}` : ''}`)
+  }
+  return { status: res.status }
+}
+
+async function safeReadText(res: Response): Promise<string> {
+  try { return await res.text() } catch { return '' }
+}
+
+class HttpError extends Error {
+  constructor(public readonly status: number, message: string) {
+    super(message)
+  }
+}
+
+/**
+ * Stream an agent chat turn against a remote OpenCode HTTP server
+ * (`opencode serve` or `opencode web`). Talks to the same REST + SSE API
+ * as the official CLI. Stores the OpenCode session id on
+ * `session.opencodeWebSessionId` so subsequent turns reuse it.
+ */
+export function streamOpenCodeWebChat(opts: StreamChatOptions): Promise<string> {
+  const { session, message, systemPrompt, apiKey, write, active, signal } = opts
+
+  const endpoint = (session.apiEndpoint as string | undefined) || DEFAULT_ENDPOINT
+  const cwd = (session.cwd as string | undefined) || process.cwd()
+  const auth = parseBasicAuth(apiKey)
+  const authHeader = buildAuthHeader(auth)
+  const { providerID, modelID } = parseModelId(session.model as string | undefined)
+
+  const controller = new AbortController()
+  if (signal) {
+    if (signal.aborted) controller.abort()
+    else signal.addEventListener('abort', () => controller.abort(), { once: true })
+  }
+  active.set(session.id, controller)
+
+  const promptParts: string[] = []
+  if (systemPrompt && !session.opencodeWebSessionId) {
+    promptParts.push(`[System instructions]\n${systemPrompt}`)
+  }
+  promptParts.push(message)
+  const prompt = promptParts.join('\n\n')
+
+  return (async () => {
+    let fullResponse = ''
+    try {
+      // Ensure we have a server-side session id. On HTTP 404 from prompt
+      // (FR-9: graceful expiry), we null this and recreate exactly once.
+      let sessionId = (session.opencodeWebSessionId as string | null | undefined)
+        || await createSession({ endpoint, cwd, authHeader, signal: controller.signal })
+      session.opencodeWebSessionId = sessionId
+
+      let postResult = await postPrompt({
+        endpoint, sessionId, cwd, prompt, providerID, modelID, authHeader, signal: controller.signal,
+      })
+      if (postResult.status === 404) {
+        log.info(TAG, `[${session.id}] session ${sessionId} returned 404, recreating`)
+        sessionId = await createSession({ endpoint, cwd, authHeader, signal: controller.signal })
+        session.opencodeWebSessionId = sessionId
+        postResult = await postPrompt({
+          endpoint, sessionId, cwd, prompt, providerID, modelID, authHeader, signal: controller.signal,
+        })
+        if (postResult.status === 404) {
+          throw new HttpError(404, 'OpenCode rejected the prompt for a freshly-created session — the server may be misconfigured.')
+        }
+      }
+
+      const eventUrl = `${joinUrl(endpoint, '/event')}?session=${encodeURIComponent(sessionId)}`
+      const eventRes = await fetch(eventUrl, {
+        method: 'GET',
+        headers: {
+          Accept: 'text/event-stream',
+          ...(authHeader ? { Authorization: authHeader } : {}),
+        },
+        signal: controller.signal,
+      })
+      if (!eventRes.ok || !eventRes.body) {
+        throw new HttpError(eventRes.status, `OpenCode event stream failed (HTTP ${eventRes.status})`)
+      }
+
+      const reader = eventRes.body.getReader()
+      const decoder = new TextDecoder()
+      const parser = new SseLineParser()
+      let completed = false
+
+      while (!completed) {
+        const { done, value } = await reader.read()
+        if (done) break
+        const chunk = decoder.decode(value, { stream: true })
+        parser.feed(chunk, (ev) => {
+          const text = extractTextDelta(ev)
+          if (text) {
+            fullResponse += text
+            write(`data: ${JSON.stringify({ t: 'd', text })}\n\n`)
+            return
+          }
+          const errMsg = extractErrorMessage(ev)
+          if (errMsg) {
+            write(`data: ${JSON.stringify({ t: 'err', text: errMsg })}\n\n`)
+            return
+          }
+          if (isCompletionEvent(ev)) completed = true
+        })
+      }
+
+      return fullResponse
+    } catch (err: unknown) {
+      const msg = err instanceof HttpError
+        ? err.message
+        : err instanceof Error
+          ? err.message
+          : String(err)
+      log.error(TAG, `[${session.id}] ${msg}`)
+      write(`data: ${JSON.stringify({ t: 'err', text: msg })}\n\n`)
+      return fullResponse
+    } finally {
+      active.delete(session.id)
+    }
+  })()
+}

package/src/lib/server/context-manager.ts

@@ -77,6 +77,7 @@ const PROVIDER_DEFAULT_WINDOWS: Record<string, number> = {
   openai: 128_000,
   'codex-cli': 1_047_576,
   'opencode-cli': 200_000,
+  'opencode-web': 200_000,
   'gemini-cli': 1_048_576,
   'copilot-cli': 200_000,
   'droid-cli': 200_000,

package/src/lib/setup-defaults.ts

@@ -7,6 +7,7 @@ export type SetupProvider =
   | 'claude-cli'
   | 'codex-cli'
   | 'opencode-cli'
+  | 'opencode-web'
   | 'gemini-cli'
   | 'copilot-cli'
   | 'droid-cli'
@@ -79,6 +80,19 @@ export const SETUP_PROVIDERS: SetupProviderOption[] = [
     badge: 'CLI',
     icon: 'O',
   },
+  {
+    id: 'opencode-web',
+    name: 'OpenCode Web',
+    description: 'Connect to a remote OpenCode HTTP server (`opencode serve` or `opencode web`). Supports HTTPS and HTTP Basic Auth.',
+    requiresKey: false,
+    optionalKey: true,
+    supportsEndpoint: true,
+    defaultEndpoint: 'http://localhost:4096',
+    keyLabel: 'username:password (Basic Auth)',
+    keyPlaceholder: 'opencode:••••••• (or just the password)',
+    badge: 'HTTP',
+    icon: 'O',
+  },
   {
     id: 'gemini-cli',
     name: 'Gemini CLI',
@@ -743,6 +757,13 @@ export const DEFAULT_AGENTS: Record<SetupProvider, DefaultAgentConfig> = {
     model: 'claude-sonnet-4-6',
     tools: STARTER_AGENT_TOOLS,
   },
+  'opencode-web': {
+    name: 'OpenCode Web',
+    description: 'A helpful assistant powered by a remote OpenCode HTTP server.',
+    systemPrompt: SWARMCLAW_ASSISTANT_PROMPT,
+    model: 'anthropic/claude-sonnet-4-5',
+    tools: STARTER_AGENT_TOOLS,
+  },
   'gemini-cli': {
     name: 'Gemini CLI',
     description: 'A helpful assistant powered by Gemini CLI.',

package/src/types/provider.ts

@@ -1,4 +1,4 @@
-export type ProviderType = 'claude-cli' | 'codex-cli' | 'opencode-cli' | 'gemini-cli' | 'copilot-cli' | 'droid-cli' | 'cursor-cli' | 'qwen-code-cli' | 'goose' | 'openai' | 'openrouter' | 'ollama' | 'anthropic' | 'openclaw' | 'hermes' | 'google' | 'deepseek' | 'groq' | 'together' | 'mistral' | 'xai' | 'fireworks' | 'nebius' | 'deepinfra'
+export type ProviderType = 'claude-cli' | 'codex-cli' | 'opencode-cli' | 'opencode-web' | 'gemini-cli' | 'copilot-cli' | 'droid-cli' | 'cursor-cli' | 'qwen-code-cli' | 'goose' | 'openai' | 'openrouter' | 'ollama' | 'anthropic' | 'openclaw' | 'hermes' | 'google' | 'deepseek' | 'groq' | 'together' | 'mistral' | 'xai' | 'fireworks' | 'nebius' | 'deepinfra'
 export type ProviderId = ProviderType | (string & {})
 
 export interface ProviderInfo {

package/src/types/session.ts

@@ -69,6 +69,7 @@ export interface Session {
   claudeSessionId: string | null
   codexThreadId?: string | null
   opencodeSessionId?: string | null
+  opencodeWebSessionId?: string | null
   geminiSessionId?: string | null
   copilotSessionId?: string | null
   droidSessionId?: string | null