@swarmclawai/swarmclaw 1.5.40 → 1.5.42

package/README.md

@@ -389,6 +389,16 @@ 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.
+
 ### v1.5.40 Highlights
 
 - **Current-thread recall routing**: the message classifier now emits four explicit flags (`isCurrentThreadRecall`, `isGreeting`, `isAcknowledgement`, `isMemoryWriteIntent`) so the chat router stops treating in-thread pronouns ("your last reply", "both answers", "what I just said") as durable-memory queries. Previously small OSS models (`devstral-small-2:24b` and similar) would run `memory_search` for these, come back empty, and truthfully report "no memories found" even when the answer was three messages up.
@@ -418,20 +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.
-
-### v1.5.36 Highlights
-
-- **Desktop app (Electron)**: SwarmClaw now ships as a native desktop app for macOS (Apple Silicon + Intel), Windows, and Linux (AppImage + .deb). Download from [swarmclaw.ai/downloads](https://swarmclaw.ai/downloads). The app wraps the existing standalone server inside an Electron shell, stores data in the OS app-data directory, and auto-updates via GitHub Releases (notify-only on unsigned macOS builds).
-- **Desktop release CI**: new `desktop-release.yml` workflow builds and publishes installers for all three platforms to GitHub Releases on every version tag.
-- **UI cleanup**: removed sibling-product navigation links from the in-app sidebar rail and login gate so the open-source app focuses on SwarmClaw itself. Those links remain in the project README and on swarmclaw.ai.
-
 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.40",
+  "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/server/session-tools/build-session-tools-dedup.test.ts

@@ -0,0 +1,127 @@
+import { describe, it } from 'node:test'
+import assert from 'node:assert/strict'
+
+// Issue #39 (Moonshot/Kimi rejecting duplicate tool names) showed that the
+// Phase 1 native-tool loop in `session-tools/index.ts` was pushing tools
+// without checking for duplicate names. Phase 2 already had a dedup Set; the
+// fix lifts that Set above Phase 1 so all phases share it.
+//
+// This test mirrors the dedup algorithm in pure form so it can be verified
+// without booting the full session-tools graph (which OOMs in test workers
+// when run alongside the dev server).
+
+type FakeTool = { name: string }
+type Builder = () => FakeTool[]
+
+interface DedupWarn {
+  toolName: string
+  source: 'native' | 'crud' | 'extension'
+  extensionId?: string
+}
+
+function dedupAssemble(
+  nativeBuilders: ReadonlyArray<readonly [string, Builder]>,
+  crudBuilder: Builder,
+  extensionTools: ReadonlyArray<{ extensionId: string; tool: FakeTool }>,
+): { tools: FakeTool[]; warnings: DedupWarn[] } {
+  const tools: FakeTool[] = []
+  const warnings: DedupWarn[] = []
+  const existingNames = new Set<string>()
+
+  for (const [extensionId, builder] of nativeBuilders) {
+    for (const t of builder()) {
+      if (existingNames.has(t.name)) {
+        warnings.push({ toolName: t.name, source: 'native', extensionId })
+        continue
+      }
+      existingNames.add(t.name)
+      tools.push(t)
+    }
+  }
+
+  for (const t of crudBuilder()) {
+    if (existingNames.has(t.name)) {
+      warnings.push({ toolName: t.name, source: 'crud' })
+      continue
+    }
+    existingNames.add(t.name)
+    tools.push(t)
+  }
+
+  for (const entry of extensionTools) {
+    if (existingNames.has(entry.tool.name)) {
+      warnings.push({ toolName: entry.tool.name, source: 'extension', extensionId: entry.extensionId })
+      continue
+    }
+    existingNames.add(entry.tool.name)
+    tools.push(entry.tool)
+  }
+
+  return { tools, warnings }
+}
+
+describe('session-tools assembler dedup (issue #39 regression)', () => {
+  it('emits a single `files` tool when two native builders both produce one (the original issue #39 scenario)', () => {
+    const result = dedupAssemble(
+      [
+        ['files', () => [{ name: 'files' }]],
+        ['files_v2', () => [{ name: 'files' }]],
+      ],
+      () => [],
+      [],
+    )
+
+    const fileTools = result.tools.filter((t) => t.name === 'files')
+    assert.equal(fileTools.length, 1, 'must emit exactly one tool named "files"')
+    assert.equal(result.warnings.length, 1)
+    assert.equal(result.warnings[0].toolName, 'files')
+    assert.equal(result.warnings[0].source, 'native')
+    assert.equal(result.warnings[0].extensionId, 'files_v2')
+  })
+
+  it('first builder wins when names collide', () => {
+    const t1 = { name: 'shared' }
+    const t2 = { name: 'shared' }
+    const result = dedupAssemble(
+      [
+        ['ext-a', () => [t1]],
+        ['ext-b', () => [t2]],
+      ],
+      () => [],
+      [],
+    )
+    assert.equal(result.tools.length, 1)
+    assert.strictEqual(result.tools[0], t1)
+  })
+
+  it('CRUD tools cannot collide with native tools', () => {
+    const result = dedupAssemble(
+      [['ext-a', () => [{ name: 'crud_op' }]]],
+      () => [{ name: 'crud_op' }],
+      [],
+    )
+    assert.equal(result.tools.length, 1)
+    assert.equal(result.warnings[0].source, 'crud')
+  })
+
+  it('extension tools dedup against the same shared Set', () => {
+    const result = dedupAssemble(
+      [['ext-a', () => [{ name: 'foo' }]]],
+      () => [],
+      [{ extensionId: 'ext-b', tool: { name: 'foo' } }],
+    )
+    assert.equal(result.tools.length, 1)
+    assert.equal(result.warnings[0].source, 'extension')
+    assert.equal(result.warnings[0].extensionId, 'ext-b')
+  })
+
+  it('lets distinct names through unchanged', () => {
+    const result = dedupAssemble(
+      [['ext-a', () => [{ name: 'a' }, { name: 'b' }]]],
+      () => [{ name: 'c' }],
+      [{ extensionId: 'ext-b', tool: { name: 'd' } }],
+    )
+    assert.deepEqual(result.tools.map((t) => t.name), ['a', 'b', 'c', 'd'])
+    assert.equal(result.warnings.length, 0)
+  })
+})

package/src/lib/server/session-tools/files-tool.test.ts

@@ -0,0 +1,56 @@
+import { describe, it } from 'node:test'
+import assert from 'node:assert/strict'
+import { buildFilesTools } from '@/lib/server/session-tools/files-tool'
+import type { ToolBuildContext } from '@/lib/server/session-tools/context'
+
+function makeBctx(enabled: Set<string>): ToolBuildContext {
+  return {
+    cwd: '/tmp',
+    ctx: undefined,
+    hasExtension: (name) => enabled.has(name),
+    hasTool: (name) => enabled.has(name),
+    cleanupFns: [],
+    commandTimeoutMs: 0,
+    claudeTimeoutMs: 0,
+    cliProcessTimeoutMs: 0,
+    persistDelegateResumeId: () => {},
+    readStoredDelegateResumeId: () => null,
+    resolveCurrentSession: () => null,
+    activeExtensions: Array.from(enabled),
+    filesystemScope: 'workspace',
+  }
+}
+
+describe('buildFilesTools (issue #39)', () => {
+  it('returns no tools when only the legacy `files` extension is enabled', () => {
+    // Pre-fix this returned a tool named "files", on top of the v1 builder
+    // which already produced a tool with the same name. Moonshot/Kimi rejected
+    // the duplicate with `function name files is duplicated`.
+    const bctx = makeBctx(new Set(['files']))
+    const out = buildFilesTools(bctx)
+    assert.equal(out.length, 0)
+  })
+
+  it('returns no tools when no relevant extension is enabled', () => {
+    const bctx = makeBctx(new Set(['shell', 'web']))
+    const out = buildFilesTools(bctx)
+    assert.equal(out.length, 0)
+  })
+
+  it('returns one `files` tool when the v2 extension is explicitly enabled', () => {
+    const bctx = makeBctx(new Set(['files_v2']))
+    const out = buildFilesTools(bctx)
+    assert.equal(out.length, 1)
+    assert.equal(out[0].name, 'files')
+  })
+
+  it('returns one `files` tool when both `files` and `files_v2` are enabled', () => {
+    // Defensive: even with both enabled, this builder emits exactly one tool.
+    // (The duplicate-with-v1 protection lives in the session-tools assembler
+    // dedup loop, covered by build-session-tools-dedup.test.ts.)
+    const bctx = makeBctx(new Set(['files', 'files_v2']))
+    const out = buildFilesTools(bctx)
+    assert.equal(out.length, 1)
+    assert.equal(out[0].name, 'files')
+  })
+})

package/src/lib/server/session-tools/files-tool.ts

@@ -608,14 +608,22 @@ const FilesExtension: Extension = {
   ],
 }
 
-registerNativeCapability('files', FilesExtension)
+// Registered under 'files_v2' to avoid colliding with the v1 FileExtension
+// in `file.ts`, which also registers under the literal key 'files'. The
+// builder below is wired into `session-tools/index.ts` via the same key.
+registerNativeCapability('files_v2', FilesExtension)
 
 // ---------------------------------------------------------------------------
 // Tool builder (called from session-tools/index.ts)
 // ---------------------------------------------------------------------------
 
 export function buildFilesTools(bctx: ToolBuildContext) {
-  if (!bctx.hasExtension('files')) return []
+  // Gate on 'files_v2' (not 'files'). Previously this checked 'files', which
+  // meant that enabling the v1 `files` extension activated BOTH builders and
+  // registered two tools literally named "files". Most providers tolerate
+  // duplicate tool names; Moonshot/Kimi rejects them with `function name
+  // files is duplicated`. Reported as issue #39.
+  if (!bctx.hasExtension('files_v2')) return []
 
   return [
     tool(

package/src/lib/server/session-tools/index.ts

@@ -221,24 +221,41 @@ export async function buildSessionTools(cwd: string, enabledExtensions: string[]
       ['swarmdock', buildSwarmDockTools],
     ]
 
+    // Track tool names across all phases so duplicates are rejected
+    // consistently. Issue #39: Moonshot rejects duplicate tool names that
+    // most providers silently tolerate, so guarding only Phase 2 (as the
+    // pre-fix code did) was not enough.
+    const existingNames = new Set<string>()
     for (const [extensionId, builder] of nativeBuilders) {
       const builtTools = builder(bctx)
       for (const t of builtTools) {
+        if (existingNames.has(t.name)) {
+          log.warn('session-tools', 'Skipping native tool due to duplicate name', {
+            toolName: t.name,
+            extensionId,
+          })
+          continue
+        }
+        existingNames.add(t.name)
         toolToExtensionMap[t.name] = extensionId
+        tools.push(t)
       }
-      tools.push(...builtTools)
     }
 
     const crudTools = buildCrudTools(bctx)
     for (const toolEntry of crudTools) {
+      if (existingNames.has(toolEntry.name)) {
+        log.warn('session-tools', 'Skipping CRUD tool due to duplicate name', { toolName: toolEntry.name })
+        continue
+      }
+      existingNames.add(toolEntry.name)
       toolToExtensionMap[toolEntry.name] = toolEntry.name
+      tools.push(toolEntry)
     }
-    tools.push(...crudTools)
 
     // 2. Build Extension Tools (Built-in + External)
     try {
       const extensionTools = extensionManager.getTools(activeExtensions)
-      const existingNames = new Set(tools.map((t) => t.name))
       
       for (const entry of extensionTools) {
         const pt = entry.tool

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