opencode-plugboard 0.15.0 → 0.16.0

package/README.md

@@ -30,7 +30,7 @@ export PLUGBOARD_KEY_MY_APP=choose-a-long-random-string
 {
   "plugins": [
     {
-      "package": "opencode-plugboard@0.15.0",
+      "package": "opencode-plugboard@0.16.0",
       "options": {
         "keys": { "my-app": "{env:PLUGBOARD_KEY_MY_APP}" },
         "models": ["anthropic/claude-sonnet-4-6", "github-copilot/*", "opencode-go/glm-5.3-flash"],

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "opencode-plugboard",
-  "version": "0.15.0",
+  "version": "0.16.0",
   "type": "module",
   "license": "MIT",
   "description": "Use the ChatGPT, Claude, Copilot and OpenCode Go logins in your OpenCode server from any app. An OpenCode V2 plugin serving OpenAI-compatible Chat Completions, Responses and model endpoints.",
@@ -37,10 +37,14 @@
     "@ai-sdk/anthropic": "4.0.78",
     "@ai-sdk/google": "4.0.93",
     "@ai-sdk/openai": "4.0.91",
+    "@ai-sdk/openai-compatible": "3.0.67",
     "@anthropic-ai/sdk": "0.133.0",
     "@commitlint/cli": "21.2.3",
     "@commitlint/config-conventional": "21.2.3",
     "@google/genai": "2.28.0",
+    "@langchain/anthropic": "1.5.12",
+    "@langchain/google-genai": "2.3.2",
+    "@langchain/openai": "1.6.2",
     "@opencode/plugin": "2.0.26",
     "@types/bun": "1.4.2",
     "@types/escape-html": "^1.0.4",

package/src/anthropic/route.ts

@@ -21,6 +21,7 @@ import {
   checkJsonContentType,
   checkOrigin,
   readJsonBody,
+  sendError,
   sendJson,
   sseWriter,
   type RequestScope,
@@ -65,7 +66,7 @@ const authenticateRequest = (host: RouteHost, request: IncomingMessage) => {
 
 export async function serveMessages(host: RouteHost, call: MessagesCall): Promise<void> {
   const { path, request, response, scope, info } = call
-  const fail = (error: PlugError, close = false) => sendJson(response, error.status, encodeError(error), { close })
+  const fail = (error: PlugError, close = false) => sendError(response, error, encodeError(error), { close })
   if (request.method === "POST") info.route = `POST ${path}`
   response.setHeader("request-id", `req_${crypto.randomUUID().replaceAll("-", "")}`)
 
@@ -84,13 +85,14 @@ export async function serveMessages(host: RouteHost, call: MessagesCall): Promis
   }
 
   async function serve(): Promise<void> {
-    if (request.method !== "POST")
-      return fail({ status: 405, kind: "invalid_request", code: "method_not_allowed", message: `Method ${request.method} is not allowed for ${path}; use POST` })
     const rejected = checkOrigin(request, host.options)
     if (rejected) return fail(rejected)
+    // Authenticate before the method check, so an unauthenticated caller cannot map this path (#137).
     const auth = authenticateRequest(host, request)
     if (isPlugError(auth)) return fail(auth)
     info.app = auth.app
+    if (request.method !== "POST")
+      return fail({ status: 405, kind: "invalid_request", code: "method_not_allowed", message: `Method ${request.method} is not allowed for ${path}; use POST` })
     if (path === COUNT_TOKENS)
       return fail({ status: 404, kind: "not_found", code: "not_found", message: "count_tokens is not supported by plugboard" })
     const unsupported = checkJsonContentType(request)

package/src/completions/response.ts

@@ -44,7 +44,7 @@ const encodeUsage = (usage: PlugUsage) => {
 const prefixOf = (exchange: CompletionsExchange, index: number) => exchange.echo?.[Math.floor(index / exchange.perPrompt)] ?? ""
 
 /** One choice as a complete body: `choices[0]` carries the text, `usage` the totals. */
-async function collectText(events: AsyncIterable<PlugEvent>, exchange: CompletionsExchange, index: number): Promise<{ status: number; body: object }> {
+async function collectText(events: AsyncIterable<PlugEvent>, exchange: CompletionsExchange, index: number): Promise<{ status: number; body: object; retryAfterSeconds?: number }> {
   let text = ""
   let finish: Exclude<PlugFinish, "error"> | undefined
   let usage: PlugUsage | undefined
@@ -63,7 +63,7 @@ async function collectText(events: AsyncIterable<PlugEvent>, exchange: Completio
   if (!failure && !finish) failure = noFinish()
   if (failure || !finish) {
     const error = failure ?? noFinish()
-    return { status: error.status, body: encodeError(error) }
+    return { status: error.status, body: encodeError(error), retryAfterSeconds: error.retryAfterSeconds }
   }
   return {
     status: 200,

package/src/completions/route.ts

@@ -12,7 +12,7 @@
 import type { ServerResponse } from "node:http"
 import { isPlugError, type PlugError, type PlugRequest } from "../contract.js"
 import type { ServedInfo } from "../fallback.js"
-import { sendJson, type RequestScope } from "../http.js"
+import { sendError, type RequestScope } from "../http.js"
 import { resolveModel } from "../models.js"
 import { serveChoices } from "../openai/fanout.js"
 import { encodeError } from "../openai/response.js"
@@ -33,7 +33,7 @@ export interface CompletionsCall {
 }
 
 export async function serveCompletions(host: RouteHost, { app, body, response, scope, info }: CompletionsCall): Promise<void> {
-  const fail = (error: PlugError) => sendJson(response, error.status, encodeError(error))
+  const fail = (error: PlugError) => sendError(response, error, encodeError(error))
 
   const parsed = parseCompletionsRequest(body, host.options)
   if (isPlugError(parsed)) return fail(parsed)

package/src/contract.ts

@@ -153,7 +153,7 @@ export interface PlugError {
   readonly message: string
   readonly code?: string
   readonly param?: string
-  /** Seconds to wait before a retry, for a `Retry-After` header. Set by the limiter (`src/limits.ts`); no route reads it yet. */
+  /** Seconds to wait before a retry, sent as the `Retry-After` header (`sendError` in `src/http.ts`). Set by the limiter (`src/limits.ts`). */
   readonly retryAfterSeconds?: number
 }
 

package/src/discovery.ts

@@ -58,18 +58,30 @@ export interface Endpoint {
   readonly description: string
 }
 
-function endpoints(options: PlugboardOptions): Endpoint[] {
-  return [
-    { method: "GET", path: "/", auth: false, description: "This page." },
-    { method: "GET", path: "/v1", auth: false, description: "This page as JSON." },
-    { method: "GET", path: "/healthz", auth: false, description: "Liveness: {\"ok\":true}." },
-    { method: "GET", path: "/v1/models", auth: true, description: "Models this app may call." },
-    { method: "GET", path: "/v1/models/{id}", auth: true, description: "One model." },
-    { method: "POST", path: "/v1/chat/completions", auth: true, description: "OpenAI Chat Completions." },
-    { method: "POST", path: "/v1/responses", auth: true, description: "OpenAI Responses (stateless)." },
-    { method: "GET", path: "/v1/status", auth: true, description: "Runtime status: generations, address, model count, uptime." },
-    ...(options.metrics ? [{ method: "GET", path: "/metrics", auth: true, description: "Prometheus metrics." }] : []),
-  ]
+/**
+ * Every endpoint plugboard serves, in the order the document lists them. Dispatch lives in
+ * `src/openai/route.ts` and the front-end routes; `test/http/discovery.test.ts` probes each served
+ * route and fails when this list omits one (#136). `/metrics` is added only when option `metrics` is on.
+ */
+export const ENDPOINTS: ReadonlyArray<Endpoint> = [
+  { method: "GET", path: "/", auth: false, description: "This page." },
+  { method: "GET", path: "/v1", auth: false, description: "This page as JSON." },
+  { method: "GET", path: "/healthz", auth: false, description: "Liveness: {\"ok\":true}." },
+  { method: "GET", path: "/v1/models", auth: true, description: "Models this app may call (OpenAI shape)." },
+  { method: "GET", path: "/v1/models/{id}", auth: true, description: "One model." },
+  { method: "POST", path: "/v1/chat/completions", auth: true, description: "OpenAI Chat Completions." },
+  { method: "POST", path: "/v1/completions", auth: true, description: "Legacy OpenAI completions." },
+  { method: "POST", path: "/v1/responses", auth: true, description: "OpenAI Responses (stateless)." },
+  { method: "POST", path: "/v1/messages", auth: true, description: "Anthropic Messages (x-api-key or Bearer)." },
+  { method: "GET", path: "/v1beta/models", auth: true, description: "Gemini model list." },
+  { method: "GET", path: "/v1beta/models/{model}", auth: true, description: "One Gemini model." },
+  { method: "POST", path: "/v1beta/models/{model}:generateContent", auth: true, description: "Gemini generateContent." },
+  { method: "POST", path: "/v1beta/models/{model}:streamGenerateContent", auth: true, description: "Gemini streamGenerateContent, with ?alt=sse." },
+  { method: "GET", path: "/v1/status", auth: true, description: "Runtime status: generations, address, model count, uptime." },
+]
+
+function endpoints(options: PlugboardOptions): ReadonlyArray<Endpoint> {
+  return options.metrics ? [...ENDPOINTS, { method: "GET", path: "/metrics", auth: true, description: "Prometheus metrics." }] : ENDPOINTS
 }
 
 type ModelsState = "ready" | "no_models_configured" | "none_available" | "catalog_unavailable"

package/src/gemini/route.ts

@@ -17,7 +17,7 @@
 import type { IncomingMessage, ServerResponse } from "node:http"
 import { isPlugError, type PlugError, type PlugRequest } from "../contract.js"
 import { reportServed, type ServedInfo } from "../fallback.js"
-import { boundEvents, checkJsonContentType, readJsonBody, sendJson, sseWriter, type RequestScope } from "../http.js"
+import { boundEvents, checkJsonContentType, readJsonBody, sendError, sendJson, sseWriter, type RequestScope } from "../http.js"
 import { listAvailableModels, resolveModel } from "../models.js"
 import { reportCache } from "../cache.js"
 import { reportPolicy } from "../policy.js"
@@ -64,10 +64,10 @@ export function matchGeminiRoute(method: string | undefined, path: string): Gemi
     const verb = colon > 0 ? rest.slice(colon + 1) : ""
     const model = decode(rest.slice(0, colon))
     if (!/^[A-Za-z]+$/.test(verb) || model === undefined) return undefined
-    const label = `POST ${prefix.slice(0, -1)}/{model}:${verb}`
     if (verb === "generateContent" || verb === "streamGenerateContent")
-      return { op: "generate", route: label, model: model.startsWith("models/") ? model.slice(7) : model, stream: verb === "streamGenerateContent" }
-    return { op: "unsupported", route: label, verb }
+      return { op: "generate", route: `POST ${prefix.slice(0, -1)}/{model}:${verb}`, model: model.startsWith("models/") ? model.slice(7) : model, stream: verb === "streamGenerateContent" }
+    // The client's verb never becomes a metric or log label: every other verb is `unknown` (#135).
+    return { op: "unsupported", route: "unknown", verb }
   }
   return undefined
 }
@@ -95,7 +95,7 @@ export interface GeminiCall {
 }
 
 export async function serveGemini(host: RouteHost, { match, request, url, app, response, scope, info }: GeminiCall): Promise<void> {
-  const fail = (error: PlugError) => sendJson(response, error.status, encodeGeminiError(error))
+  const fail = (error: PlugError) => sendError(response, error, encodeGeminiError(error))
 
   if (match.op === "unsupported")
     return fail({ status: 404, kind: "not_found", code: "method_not_supported", message: `Method ${match.verb} is not supported; plugboard serves generateContent and streamGenerateContent` })

package/src/http.ts

@@ -165,18 +165,29 @@ export function finishRequest(request: IncomingMessage, response: ServerResponse
   response.once("close", () => clearTimeout(timer))
 }
 
-/** `close`: also tell the client to drop the connection (after an unread or abandoned body). */
-export const sendJson = (response: ServerResponse, status: number, payload: unknown, options?: { close?: boolean }) => {
+/**
+ * `close`: also tell the client to drop the connection (after an unread or abandoned body).
+ * `retryAfterSeconds`: sent as `Retry-After` (a rate-limit refusal, see `PlugError.retryAfterSeconds`).
+ */
+export const sendJson = (response: ServerResponse, status: number, payload: unknown, options?: { close?: boolean; retryAfterSeconds?: number }) => {
   if (response.headersSent || response.destroyed) return
   const body = JSON.stringify(payload)
   response.writeHead(status, {
     "content-type": "application/json",
     "content-length": Buffer.byteLength(body),
     ...(options?.close ? { connection: "close" } : {}),
+    ...(options?.retryAfterSeconds !== undefined ? { "retry-after": String(options.retryAfterSeconds) } : {}),
   })
   response.end(body)
 }
 
+/**
+ * A `PlugError` answered in a front-end's own wire body, before any output. Every route's `fail` goes
+ * through here, so a refused call (`PlugError.retryAfterSeconds`) always carries `Retry-After`.
+ */
+export const sendError = (response: ServerResponse, error: PlugError, body: unknown, options?: { close?: boolean }) =>
+  sendJson(response, error.status, body, { ...options, retryAfterSeconds: error.retryAfterSeconds })
+
 /**
  * SSE response writer. Headers go out with the first chunk, so nothing is committed until there
  * is something to send; chunks after the client is gone are dropped. `write` is synchronous (the

package/src/openai/fanout.ts

@@ -25,7 +25,7 @@ import type { PlugError, PlugEvent, PlugRequest, PlugUsage } from "../contract.j
 import { reportServed, type ServedInfo } from "../fallback.js"
 import { reportCache } from "../cache.js"
 import { reportPolicy } from "../policy.js"
-import { RequestAborted, boundEvents, sendJson, sseWriter, type RequestScope } from "../http.js"
+import { RequestAborted, boundEvents, sendError, sendJson, sseWriter, type RequestScope } from "../http.js"
 import { chatUsageChunk, collectCompletion, encodeError, streamCompletion, type OpenAiExchange, type StreamChoice, type StreamResult } from "./response.js"
 import type { RouteHost } from "./route.js"
 
@@ -38,7 +38,7 @@ export interface ChoiceCodec {
   /** Prefix of the shared stream id (`chatcmpl-`, `cmpl-`). */
   readonly idPrefix: string
   /** One choice as a complete JSON body with `choices[0]` and `usage`. */
-  collect(events: AsyncIterable<PlugEvent>, index: number): Promise<{ status: number; body: object }>
+  collect(events: AsyncIterable<PlugEvent>, index: number): Promise<{ status: number; body: object; retryAfterSeconds?: number }>
   /** One choice of the shared stream: this choice's chunks only (see `StreamChoice`). */
   streamChoice(events: AsyncIterable<PlugEvent>, write: (chunk: string) => void, choice: StreamChoice): Promise<StreamResult>
   /** The final chunk with the summed usage (`include_usage`). */
@@ -155,7 +155,7 @@ const addUsage = (a: PlugUsage, b: PlugUsage): PlugUsage => {
 }
 
 export async function serveChoices(host: Pick<RouteHost, "caller">, { app, calls, response, scope, info, codec }: ChoicesCall): Promise<void> {
-  const fail = (error: PlugError) => sendJson(response, error.status, encodeError(error))
+  const fail = (error: PlugError) => sendError(response, error, encodeError(error))
   // Abandoned requests (client gone, deadline passed) must never reach the model caller.
   if (scope.signal.aborted) throw scope.signal.reason
 
@@ -190,8 +190,8 @@ export async function serveChoices(host: Pick<RouteHost, "caller">, { app, calls
     )
 
   if (!codec.stream) {
-    const results = await new Promise<Array<{ status: number; body: object }>>((resolve, reject) => {
-      const done: Array<{ status: number; body: object }> = []
+    const results = await new Promise<Array<{ status: number; body: object; retryAfterSeconds?: number }>>((resolve, reject) => {
+      const done: Array<{ status: number; body: object; retryAfterSeconds?: number }> = []
       let left = calls.length
       calls.forEach((_, index) => {
         codec.collect(open(index), index).then(
@@ -211,7 +211,7 @@ export async function serveChoices(host: Pick<RouteHost, "caller">, { app, calls
       })
     })
     const first = results[0]!
-    return sendJson(response, first.status, results.length === 1 ? first.body : mergeBodies(results.map((result) => result.body)))
+    return sendJson(response, first.status, results.length === 1 ? first.body : mergeBodies(results.map((result) => result.body)), { retryAfterSeconds: first.retryAfterSeconds })
   }
 
   const sse = sseWriter(response, scope.signal)

package/src/openai/response.ts

@@ -195,7 +195,7 @@ const now = () => Math.floor(Date.now() / 1000)
 export async function collectCompletion(
   events: AsyncIterable<PlugEvent>,
   exchange: OpenAiExchange,
-): Promise<{ status: number; body: object }> {
+): Promise<{ status: number; body: object; retryAfterSeconds?: number }> {
   let text = ""
   const calls: ToolCall[] = []
   let finish: Exclude<PlugFinish, "error"> | undefined
@@ -217,7 +217,7 @@ export async function collectCompletion(
   if (!failure && !finish) failure = noFinish()
   if (failure || !finish) {
     const error = failure ?? noFinish()
-    return { status: error.status, body: encodeError(error) }
+    return { status: error.status, body: encodeError(error), retryAfterSeconds: error.retryAfterSeconds }
   }
 
   const answer = calls.find((call) => structured.isAnswer(exchange, call))

package/src/openai/route.ts

@@ -32,6 +32,7 @@ import {
   checkOrigin,
   finishRequest,
   readJsonBody,
+  sendError,
   sendJson,
   sseWriter,
   type RequestScope,
@@ -41,7 +42,7 @@ import { encodeGeminiError } from "../gemini/response.js"
 import { geminiAuthorization, matchGeminiRoute, serveGemini } from "../gemini/route.js"
 import { errorMessage, log, logError, withRequestId } from "../log.js"
 import { NO_APP, outcomeLabel, type Metrics } from "../metrics.js"
-import { listAvailableModels, resolveModel } from "../models.js"
+import { filterByCapability, listAvailableModels, parseCapability, resolveModel } from "../models.js"
 import { reportCache } from "../cache.js"
 import { reportPolicy } from "../policy.js"
 import { isMessagesPath, serveMessages } from "../anthropic/route.js"
@@ -119,7 +120,7 @@ export function createOpenAiRoute(routeHost: RouteHost) {
   /** Responses to Gemini routes: errors there use Google's body. */
   const googleErrors = new WeakSet<ServerResponse>()
   const fail = (response: ServerResponse, error: PlugError, close = false) =>
-    sendJson(response, error.status, googleErrors.has(response) ? encodeGeminiError(error) : encodeError(error), { close })
+    sendError(response, error, googleErrors.has(response) ? encodeGeminiError(error) : encodeError(error), { close })
 
   /** The catalog for a page that can do without it: a failure is logged and reported as absent; an abort still ends the request. */
   async function optionalCatalog(scope: RequestScope): Promise<ReadonlyArray<CatalogModel> | undefined> {
@@ -198,8 +199,13 @@ export function createOpenAiRoute(routeHost: RouteHost) {
     }
 
     if (route === "GET /v1/models" || modelId !== undefined) {
+      // `?capability=vision|tools` filters the list (#61). Any other value is refused before the catalog loads.
+      const requested = modelId === undefined ? url.searchParams.get("capability") : null
+      const capability = requested === null ? undefined : parseCapability(requested)
+      if (requested !== null && capability === undefined)
+        return fail(response, { status: 400, kind: "invalid_request", code: "invalid_capability", param: "capability", message: "capability must be vision or tools" })
       const listed = listAvailableModels(host.options, await scope.race(host.loadCatalog()), auth.app)
-      if (modelId === undefined) return sendJson(response, 200, encodeModelList(listed))
+      if (modelId === undefined) return sendJson(response, 200, encodeModelList(capability ? filterByCapability(listed, capability) : listed))
       const item = listed.find((m) => m.id === modelId)
       if (!item) {
         return fail(response, {
@@ -277,7 +283,7 @@ export function createOpenAiRoute(routeHost: RouteHost) {
     }
 
     const result = await collectCompletion(events, exchange)
-    sendJson(response, result.status, result.body)
+    sendJson(response, result.status, result.body, { retryAfterSeconds: result.retryAfterSeconds })
   }
 
   /** Never rejects: every failure ends in a response (or a closed socket) and one log line. */

package/src/responses/route.ts

@@ -11,7 +11,7 @@
 import type { ServerResponse } from "node:http"
 import { isPlugError, type PlugError, type PlugRequest } from "../contract.js"
 import { reportServed, type ServedInfo } from "../fallback.js"
-import { boundEvents, sendJson, sseWriter, type RequestScope } from "../http.js"
+import { boundEvents, sendError, sendJson, sseWriter, type RequestScope } from "../http.js"
 import { resolveModel } from "../models.js"
 import { reportCache } from "../cache.js"
 import { reportPolicy } from "../policy.js"
@@ -32,7 +32,7 @@ export interface ResponsesCall {
 }
 
 export async function serveResponses(host: RouteHost, { app, body, response, scope, info }: ResponsesCall): Promise<void> {
-  const fail = (error: PlugError) => sendJson(response, error.status, encodeError(error))
+  const fail = (error: PlugError) => sendError(response, error, encodeError(error))
 
   const parsed = parseResponsesRequest(body, host.options)
   if (isPlugError(parsed)) return fail(parsed)