From 091292af9f87b1c567d1d860d9404b3e8534d702 Mon Sep 17 00:00:00 2001
From: Stephen Frederick
Date: Wed, 4 Nov 2026 00:22:04 -0500
Subject: [PATCH 1/3] Add a custom endpoint and OpenCode Go settings, and lower
Go traffic
Review settings can save an OpenCode Go key and one OpenAI-compatible endpoint,
and choose the model for Initial Review. A custom endpoint runs on this computer
only, its key never reaches the cloud, and redirects are refused so drawings go
only to the chosen server. Go now runs 3 sheet reviewers at 60 requests a minute,
never resends a usage-limit refusal, and sends one session per conversation.
---
.env.example | 3 +-
backend/application.ts | 15 +-
backend/cloud/contracts.ts | 13 +-
backend/cloud/sandbox-port.ts | 9 +-
backend/cloud/service.ts | 17 +-
backend/inference/pacing.ts | 11 +-
backend/inference/provider.ts | 306 +++++++++++----
backend/packet-review/service.ts | 23 +-
backend/review/execution.ts | 93 +++--
backend/review/prompts/review-prompt.ts | 12 +-
desktop/connection-check.ts | 172 +++++++++
desktop/credential-files.ts | 32 +-
desktop/credentials.ts | 200 +++++++---
desktop/main.ts | 147 +++++++-
docs/deployment.md | 9 +
docs/inference.md | 134 ++++++-
docs/review-runtime.md | 3 +-
src/lib/backend-rpc.ts | 25 +-
src/lib/review/client.ts | 30 +-
.../components/CustomEndpointSettings.svelte | 204 ++++++++++
.../components/OpenCodeGoSettings.svelte | 149 ++++++++
.../review/components/ReviewWorkbench.svelte | 164 +++++++-
src/lib/review/execution.ts | 1 +
src/lib/review/models.ts | 68 +++-
src/lib/review/shell.ts | 53 +++
tests/e2e/custom-endpoint.spec.ts | 143 +++++++
tests/e2e/workbench-fixture.ts | 40 +-
tests/fixtures/packet-review.ts | 6 +
tests/smoke/cloud-cache.test.ts | 6 +-
tests/smoke/cloud-progress-preview.test.ts | 5 +-
tests/smoke/cloud-reviews.test.ts | 9 +-
tests/smoke/cloud-state-budget.test.ts | 10 +-
tests/smoke/cloud-sync.test.ts | 6 +-
tests/smoke/cloud-transfer-progress.test.ts | 6 +-
tests/smoke/custom-endpoint.test.ts | 356 ++++++++++++++++++
tests/smoke/opencode-go.test.ts | 325 ++++++++++++++++
tests/smoke/packet-provider.test.ts | 9 +-
tests/smoke/packet-refusal.test.ts | 60 ++-
tests/smoke/review-conversation.test.ts | 6 +-
39 files changed, 2628 insertions(+), 252 deletions(-)
create mode 100644 desktop/connection-check.ts
create mode 100644 src/lib/review/components/CustomEndpointSettings.svelte
create mode 100644 src/lib/review/components/OpenCodeGoSettings.svelte
create mode 100644 tests/e2e/custom-endpoint.spec.ts
create mode 100644 tests/smoke/custom-endpoint.test.ts
create mode 100644 tests/smoke/opencode-go.test.ts
diff --git a/.env.example b/.env.example
index 64c14c3c..f8a1908a 100644
--- a/.env.example
+++ b/.env.example
@@ -14,7 +14,8 @@ BASETEN_API_KEY=
BASETEN_API_BASE_URL=https://inference.baseten.co/v1
BASETEN_MODEL=meta-models/muse-spark-open-1026
-# OpenCode Go key, for drawing-set reviews. Muse Spark there trains on drawings; see docs/inference.md.
+# OpenCode Go key (oc_sk_...), the variable Pi and OpenCode read, for drawing-set reviews.
+# Muse Spark there trains on drawings; see docs/inference.md.
OPENCODE_API_KEY=
# Setup and model reference: docs/inference.md and docs/models.md.
diff --git a/backend/application.ts b/backend/application.ts
index 54408a68..fc14fa2f 100644
--- a/backend/application.ts
+++ b/backend/application.ts
@@ -37,6 +37,7 @@ import { ExecutionError } from "#lib/review/execution.ts";
import { CloudReviewError } from "#lib/review/cloud.ts";
import { CloudReviews, CloudSandbox, unavailableCloudSandbox } from "./cloud/service.ts";
import { modalSandboxLayer } from "./cloud/modal.ts";
+import { isCloudProvider } from "./cloud/contracts.ts";
import { executionPersistence } from "./review/execution-store.ts";
import { cloudPackageLimits } from "./cloud/transfer.ts";
import { CloudReviewSynchronization } from "./cloud/sync.ts";
@@ -201,7 +202,9 @@ export class Application extends Context.Service<
const executionOptions = { owner, queries: operations, port, runPromise: entry.runPromise };
// Count checks stay on Meta or Baseten; see the guard in ReviewExecution.
- const countProvider = providers.find((provider) => provider.provider !== "opencode-go");
+ const countProvider = providers.find(
+ (provider) => provider.provider === "meta" || provider.provider === "baseten",
+ );
const connected = {
...executionOptions,
@@ -393,10 +396,14 @@ export class Application extends Context.Service<
restorePending: pendingRestore,
};
+ // A custom endpoint's key stays on this computer; it never reaches the cloud.
+ const cloudProviders = providers.filter(isCloudProvider);
+ const [cloudProvider] = cloudProviders;
+
const withProvider =
- inference === undefined
+ cloudProvider === undefined
? cloudOptions
- : { ...cloudOptions, provider: inference, providers };
+ : { ...cloudOptions, provider: cloudProvider, providers: cloudProviders };
const cloud = yield* CloudReviews.pipe(
Effect.provide(
@@ -410,7 +417,7 @@ export class Application extends Context.Service<
cloudSandbox ??
(config.modal === undefined
? unavailableCloudSandbox
- : modalSandboxLayer(config.modal, inference?.apiKey)),
+ : modalSandboxLayer(config.modal, cloudProvider?.apiKey)),
),
),
),
diff --git a/backend/cloud/contracts.ts b/backend/cloud/contracts.ts
index 862fb6f2..d40c7d05 100644
--- a/backend/cloud/contracts.ts
+++ b/backend/cloud/contracts.ts
@@ -100,8 +100,17 @@ export const CloudReviewRecord = Schema.Struct({
/** Persisted record type stays private to cloud application and adapters. */
export type CloudReviewRecord = typeof CloudReviewRecord.Type;
-/** Provider injection uses the canonical application route and a separately supplied secret. */
-export const CloudProvider = InferenceConfiguration;
+/**
+ * Provider injection uses the canonical application route and a separately supplied secret. A
+ * custom endpoint is not a cloud route: its key stays on the computer that saved it.
+ */
+export const CloudProvider = Schema.Struct({
+ ...InferenceConfiguration.fields,
+ provider: Schema.Literals(["meta", "baseten", "opencode-go"]),
+});
+
+/** Whether a configured provider may run cloud reviews. */
+export const isCloudProvider = Schema.is(CloudProvider);
/** Cloud outbound policy admits exactly these provider routes. */
export const cloudProviderEndpoints = {
diff --git a/backend/cloud/sandbox-port.ts b/backend/cloud/sandbox-port.ts
index 7876a0be..c2fdf7df 100644
--- a/backend/cloud/sandbox-port.ts
+++ b/backend/cloud/sandbox-port.ts
@@ -1,16 +1,15 @@
import type { Effect, Stream } from "effect";
-import type { InferenceConfiguration } from "#lib/backend-rpc.ts";
import type { CloudReviewError, CloudTransferProgress } from "#lib/review/cloud.ts";
import type { PackageFile } from "#lib/review/packages.ts";
import type { CloudCachedFile, CloudPendingRetain } from "./cache.ts";
-import type { CloudReviewRecord } from "./contracts.ts";
+import type { CloudProvider, CloudReviewRecord } from "./contracts.ts";
import type { CloudRecoveredWorkerProgress } from "./progress.ts";
/** Sandbox mechanics stay behind the cloud application's replay and ownership policy. */
export interface CloudSandboxPort {
/** Resolve the published image and every outbound provider secret without starting compute. */
readonly preflight: (
- providers: ReadonlyArray,
+ providers: ReadonlyArray,
) => Effect.Effect;
/** Change signals are hints; callers reconcile the durable job after subscribing and on reconnect. */
readonly changes: (record: CloudReviewRecord) => Stream.Stream;
@@ -23,8 +22,8 @@ export interface CloudSandboxPort {
) => Effect.Effect;
readonly dispatch: (
record: CloudReviewRecord,
- provider: typeof InferenceConfiguration.Type,
- alternatives: ReadonlyArray,
+ provider: typeof CloudProvider.Type,
+ alternatives: ReadonlyArray,
) => Effect.Effect;
readonly progress: (
record: CloudReviewRecord,
diff --git a/backend/cloud/service.ts b/backend/cloud/service.ts
index b4d1af9f..f1f1dc43 100644
--- a/backend/cloud/service.ts
+++ b/backend/cloud/service.ts
@@ -12,7 +12,7 @@ import {
import { readFile } from "node:fs/promises";
import { join } from "node:path";
import { randomUUID } from "node:crypto";
-import type { InferenceConfiguration, ModalConfiguration } from "#lib/backend-rpc.ts";
+import type { ModalConfiguration } from "#lib/backend-rpc.ts";
import {
CloudReviewError,
CloudReviewSetup,
@@ -21,9 +21,10 @@ import {
type CloudReviewRequest,
type CloudWorkspaceEstimate,
} from "#lib/review/cloud.ts";
-import { reviewModels } from "#lib/review/models.ts";
+import { reviewModels, runsInCloud } from "#lib/review/models.ts";
import {
cloudEngineIdentity,
+ type CloudProvider,
cloudProviderEndpoints,
cloudWorkerMinimumTimeoutMs,
type CloudReviewRecord,
@@ -63,8 +64,9 @@ interface WorkspaceVersions {
export interface CloudReviewConfiguration {
readonly directory: string;
readonly modal?: typeof ModalConfiguration.Type;
- readonly provider?: typeof InferenceConfiguration.Type;
- readonly providers?: ReadonlyArray;
+ /** Never a custom endpoint; the parent keeps its key on this computer. */
+ readonly provider?: typeof CloudProvider.Type;
+ readonly providers?: ReadonlyArray;
readonly inspect: (
request: typeof CloudReviewRequest.Type,
) => Effect.Effect;
@@ -546,6 +548,13 @@ export class CloudReviews extends Context.Service<
const model = reviewModels.find((item) => item.id === request.model);
+ if (model !== undefined && !runsInCloud(model.provider))
+ return yield* new CloudReviewError({
+ reason: "configuration",
+ message:
+ "A custom endpoint's key stays on this computer, so it runs reviews here only. Run this review here, or choose a Meta or Baseten model to push it to the cloud. Your workspace has not been uploaded.",
+ });
+
const provider =
request.model === undefined
? config.provider
diff --git a/backend/inference/pacing.ts b/backend/inference/pacing.ts
index 6012116a..877c991d 100644
--- a/backend/inference/pacing.ts
+++ b/backend/inference/pacing.ts
@@ -1,6 +1,6 @@
-import type { ReviewProvider } from "#lib/review/models.ts";
import { Option, Predicate, Redacted, Schema } from "effect";
import { createHash } from "node:crypto";
+import type { ReviewProvider } from "#lib/review/models.ts";
/** Per-minute request and token allowances a provider enforces for one credential. */
export interface RateLimits {
@@ -15,8 +15,13 @@ export interface RateLimits {
export const reportedRateLimits = {
meta: { requestsPerMinute: 3000, tokensPerMinute: 4_000_000 },
baseten: { requestsPerMinute: 100, tokensPerMinute: 2_000_000 },
- // Go publishes dollar allowances, not per-minute limits; this is a cautious starting point.
- "opencode-go": { requestsPerMinute: 300, tokensPerMinute: 4_000_000 },
+ // OpenCode Go publishes no request rate; it asks for typical coding agent traffic and monitors for
+ // abuse. This ceiling is MOKE's own choice, well above three reviewers' measured 8 requests a
+ // minute, so a burst of quick answers still looks like one person's agents.
+ "opencode-go": { requestsPerMinute: 60, tokensPerMinute: 5_000_000 },
+ // A custom endpoint's limits are unknown until it sends these headers. A 429 starts the shared
+ // cooldown, so the generous start is corrected on first refusal.
+ "openai-compatible": { requestsPerMinute: 600, tokensPerMinute: 10_000_000 },
} as const satisfies Record;
/** Monotonic time and timers; tests supply a manual clock. */
diff --git a/backend/inference/provider.ts b/backend/inference/provider.ts
index 756cd483..07f0199b 100644
--- a/backend/inference/provider.ts
+++ b/backend/inference/provider.ts
@@ -1,25 +1,33 @@
-import { createModels, type Provider } from "@earendil-works/pi-ai/models";
+import { createModels, createProvider, type Provider } from "@earendil-works/pi-ai/models";
import { metaProvider } from "@earendil-works/pi-ai/providers/meta";
import { basetenProvider } from "@earendil-works/pi-ai/providers/baseten";
import { opencodeGoProvider } from "@earendil-works/pi-ai/providers/opencode-go";
+import type { ClientIdentity } from "@earendil-works/pi-ai/utils/identity";
+import { openAICompletionsApi } from "@earendil-works/pi-ai/api/openai-completions.lazy";
import type {
AssistantMessage,
FetchFunction,
Model,
Api,
- ProviderRequestOptions,
+ StreamOptions,
TranscriptContext,
SimpleStreamOptions,
ImageContent,
} from "@earendil-works/pi-ai";
import { createAssistantMessageEventStream } from "@earendil-works/pi-ai/utils/event-stream";
import { Effect, Option, Predicate, Redacted, Schema, Semaphore } from "effect";
-import { createHash } from "node:crypto";
+import { createHash, randomUUID } from "node:crypto";
import { type PacerLease, type Refusal, RequestPacer, sharedPacer } from "./pacing.ts";
import { parseResponseReceipt } from "./response.ts";
import { createExecutionTelemetry, type RequestPhase } from "./telemetry.ts";
import type { ProviderFailure } from "#lib/review/execution.ts";
-import { ReviewProvider, reviewModels, reviewProviderRoutes } from "#lib/review/models.ts";
+import {
+ customContextWindow,
+ ReviewProvider,
+ reviewModels,
+ reviewProviderRoutes,
+} from "#lib/review/models.ts";
+import packageInfo from "../../package.json";
/** Injectable HTTP transport; Bun's optional fetch utilities are supplied by the adapter. */
export type ProviderTransport = (
@@ -33,7 +41,12 @@ export interface ProviderConfiguration {
readonly apiKey: Redacted.Redacted;
readonly route: "live" | "recorded";
readonly baseUrl?: string;
+ /** The upstream model name. For a custom endpoint it comes from its settings, not the review. */
readonly model?: string;
+ /** Custom endpoint only: whether the model reads images. Absent means it does. */
+ readonly images?: boolean;
+ /** Custom endpoint only: the model's context window in tokens. */
+ readonly contextWindow?: number;
/** Test/recorded transport; still exercises the published SDK request path. */
readonly transport?: ProviderTransport;
readonly timeoutMs?: number;
@@ -49,11 +62,20 @@ export interface ProviderConfiguration {
readonly pacer?: RequestPacer;
}
+/**
+ * OpenCode Go asks each client to send its own user agent rather than an SDK's, and Pi sends the
+ * attribution name as `x-opencode-client` (OpenCode Console docs, 2026-11-01).
+ */
+const openCodeIdentity: ClientIdentity = {
+ userAgent: { custom: `moke/${packageInfo.version}` },
+ attribution: { name: "moke", url: "https://github.com/sc-frederick/moke-meta-hackathon" },
+};
+
/** Meta serves Muse Spark 1.3 with a larger output ceiling than Pi's catalog records (checked 2026-10-29). */
const metaOutputCeilings = new Map([["muse-spark-1.3", 256_000]]);
/** Pi's implementation of each provider a review can run on. */
-const reviewProviders: Record Provider> = {
+const reviewProviders: Record Provider> = {
meta: metaProvider,
baseten: basetenProvider,
"opencode-go": opencodeGoProvider,
@@ -63,9 +85,6 @@ const reviewProviders: Record Provider> = {
export const packetReasoning = (modelId: string) =>
reviewModels.find((model) => model.id === modelId)?.reasoning ?? "high";
-/** Go asks clients to name themselves; a generic SDK name counts against traffic review. */
-const opencodeGoUserAgent = "moke-review/1.0";
-
/** Meta runs this search server-side and returns cited text; read_source still records evidence. */
const metaWebSearch = { type: "web_search", search_context_size: "high" } as const;
@@ -108,6 +127,23 @@ const ModelNotFound = Schema.fromJsonString(
const refusalBudgetMs = 10 * 60_000;
const maxRefusals = 40;
+/** OpenCode's own client resends a rate-limited request at most ten times; MOKE matches it. */
+const openCodeMaxRefusals = 11;
+
+const OpenCodeRefusal = Schema.fromJsonString(
+ Schema.Struct({ error: Schema.Struct({ type: Schema.String }) }),
+);
+
+/**
+ * OpenCode account caps that last until a 5-hour, weekly or monthly window resets. OpenCode's own
+ * client treats them as not retryable (`QUOTA_CODES` in its provider-error.ts, 2026-11-01).
+ */
+const openCodeAccountCaps = new Set([
+ "gousagelimiterror",
+ "budgetlimiterror",
+ "creditlimitexceeded",
+]);
+
/** Allowances a recorded transport never reaches. */
const unpacedLimits = { requestsPerMinute: 1e9, tokensPerMinute: 1e15 } as const;
@@ -134,7 +170,7 @@ function pacingEstimate(transcript: TranscriptContext) {
/** A dispatch the provider refused before generating anything, kept to decide how to resend it. */
interface RefusedDispatch {
- readonly kind: Refusal | "model_not_found";
+ readonly kind: Refusal | "model_not_found" | "usage_limit";
/** The wait the provider's Retry-After asked for, when valid. */
readonly retryAfterMs: number | undefined;
/** The shared cooldown a rate-limit or capacity refusal started; zero for a routing refusal. */
@@ -149,22 +185,8 @@ interface RefusedDispatch {
export const isQuickGatewayRefusal = (status: number, elapsedMs: number) =>
(status === 502 || status === 503) && elapsedMs <= 5000;
-/**
- * Why a response refused the request before generating anything: a rate limit (429), missing
- * serving capacity (529, or a quick gateway 502 or 503), or Meta's intermittent 404
- * `model_not_found` for a served model (about one request in eight for one team's key on
- * 2026-10-30).
- */
-async function refusalOf(
- response: Response,
- elapsedMs: number,
-): Promise {
- if (response.status === 429) return "rate_limit";
-
- if (response.status === 529 || isQuickGatewayRefusal(response.status, elapsedMs))
- return "overloaded";
-
- if (response.status !== 404) return undefined;
+/** A refusal's text up to 16 KiB, read from a clone; anything longer is not a refusal we recognize. */
+async function refusalBody(response: Response) {
const reader = response.clone().body?.getReader();
const chunks: Uint8Array[] = [];
let bytes = 0;
@@ -174,7 +196,7 @@ async function refusalOf(
for (let part = await reader.read(); !part.done; part = await reader.read()) {
bytes += part.value.length;
- if (bytes > 16384) return undefined;
+ if (bytes > 16384) return "";
chunks.push(part.value);
}
} finally {
@@ -183,9 +205,35 @@ async function refusalOf(
}
}
- return Option.isSome(
- Schema.decodeUnknownOption(ModelNotFound)(Buffer.concat(chunks).toString("utf8")),
- )
+ return Buffer.concat(chunks).toString("utf8");
+}
+
+/**
+ * Why a response refused the request before generating anything: a rate limit (429), an OpenCode
+ * account cap (429 with a typed body), missing serving capacity (529, or a quick gateway 502 or 503), or Meta's intermittent 404
+ * `model_not_found` for a served model (about one request in eight for one team's key on
+ * 2026-10-30).
+ */
+async function refusalOf(
+ response: Response,
+ elapsedMs: number,
+ openCodeGo: boolean,
+): Promise {
+ if (response.status === 429) {
+ if (!openCodeGo) return "rate_limit";
+ const refusal = Schema.decodeUnknownOption(OpenCodeRefusal)(await refusalBody(response));
+
+ return Option.isSome(refusal) && openCodeAccountCaps.has(refusal.value.error.type.toLowerCase())
+ ? "usage_limit"
+ : "rate_limit";
+ }
+
+ if (response.status === 529 || isQuickGatewayRefusal(response.status, elapsedMs))
+ return "overloaded";
+
+ if (response.status !== 404) return undefined;
+
+ return Option.isSome(Schema.decodeUnknownOption(ModelNotFound)(await refusalBody(response)))
? "model_not_found"
: undefined;
}
@@ -208,11 +256,31 @@ export function promptCacheKey(role: string, ...prefix: ReadonlyArray) {
return `moke-${role}-${digest.slice(0, 32)}`;
}
-/** Catalog capability for a pinned review model; Open's separate serving output maximum is unpublished. */
-export function reviewModelCapabilities(modelId: string) {
+/**
+ * The upstream model a review's request names. A custom endpoint keeps the model name from its
+ * settings; a pinned model is named by the review.
+ */
+export function routeModel(provider: ProviderConfiguration, modelId: string) {
+ return provider.provider === "openai-compatible" ? (provider.model ?? modelId) : modelId;
+}
+
+/**
+ * Catalog capability for a pinned review model; Open's separate serving output maximum is
+ * unpublished. A custom endpoint declares its context in settings and its output maximum is unknown.
+ */
+export function reviewModelCapabilities(
+ modelId: string,
+ endpoint?: Pick,
+) {
if (modelId === "meta-models/muse-spark-open-1026")
return { contextWindow: 1048576, maxOutputTokens: null };
+ if (modelId === "openai-compatible")
+ return {
+ contextWindow: endpoint?.contextWindow ?? customContextWindow.default,
+ maxOutputTokens: null,
+ };
+
const route = reviewModels.find((entry) => entry.id === modelId);
const model = (route?.provider === "opencode-go" ? opencodeGoProvider() : metaProvider())
@@ -452,6 +520,36 @@ async function providerRejectionDetail(
return "unclassified";
}
+/**
+ * The Pi model for the reviewer's OpenAI-compatible endpoint. Its features are unknown, so requests
+ * use only fields such servers commonly accept: `max_tokens`, a system role and no reasoning effort,
+ * store flag or session headers. Its rates are unknown, so the SDK's zero cost is a sentinel only.
+ */
+function customModel(configuration: ProviderConfiguration): Model<"openai-completions"> {
+ if (configuration.model === undefined || configuration.baseUrl === undefined)
+ throw new Error("A custom endpoint needs its address and model name");
+ const contextWindow = configuration.contextWindow ?? customContextWindow.default;
+
+ return {
+ id: configuration.model,
+ name: configuration.model,
+ api: "openai-completions",
+ provider: "openai-compatible",
+ baseUrl: configuration.baseUrl.replace(/\/+$/, ""),
+ input: configuration.images === false ? ["text"] : ["text", "image"],
+ reasoning: false,
+ contextWindow,
+ maxTokens: contextWindow,
+ cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
+ compat: {
+ supportsStore: false,
+ supportsDeveloperRole: false,
+ supportsReasoningEffort: false,
+ maxTokensField: "max_tokens",
+ },
+ };
+}
+
/** Both SDK entrypoints pass the same durable guard, including complete/completeSimple callers. */
export function createAdmittedModels(
configuration: ProviderConfiguration,
@@ -460,19 +558,45 @@ export function createAdmittedModels(
if (configuration.route === "recorded" && configuration.transport === undefined)
throw new Error("Recorded execution requires a recorded transport");
const identity = createExecutionTelemetry(admission.packetReview === true);
- const route = configuration.provider ?? "meta";
-
- const base = reviewProviders[route]();
+ const custom = configuration.provider === "openai-compatible" ? customModel(configuration) : null;
+
+ const route =
+ configuration.provider === undefined || configuration.provider === "openai-compatible"
+ ? "meta"
+ : configuration.provider;
+
+ const openCodeGo = custom === null && route === "opencode-go";
+
+ const base: Provider =
+ custom !== null
+ ? createProvider({
+ id: custom.provider,
+ name: "Custom endpoint",
+ baseUrl: custom.baseUrl,
+ auth: {
+ apiKey: {
+ name: "Private startup credential",
+ resolve: async () => ({ auth: { apiKey: Redacted.value(configuration.apiKey) } }),
+ },
+ },
+ models: [custom],
+ api: openAICompletionsApi(),
+ })
+ : reviewProviders[route]();
- const modelId = configuration.model ?? reviewProviderRoutes[route].model;
- const baseUrl = reviewProviderRoutes[route].endpoint;
+ const modelId = custom?.id ?? configuration.model ?? reviewProviderRoutes[route].model;
+ const baseUrl = custom?.baseUrl ?? reviewProviderRoutes[route].endpoint;
if (
- !reviewModels.some((model) => model.id === modelId && model.provider === route) ||
+ (custom === null &&
+ !reviewModels.some((model) => model.id === modelId && model.provider === route)) ||
(configuration.baseUrl !== undefined && configuration.baseUrl.replace(/\/$/, "") !== baseUrl)
)
throw new Error("Inference route does not match the selected pinned model");
- const catalog = base.getModels().find((model) => model.id === modelId);
+ const catalog = custom === null ? base.getModels().find((model) => model.id === modelId) : null;
+
+ // Every OpenCode Go model comes from Pi's catalog, which picks its wire format and fields.
+ if (openCodeGo && !catalog) throw new Error("Pinned model catalog is incompatible");
const metaModel = metaProvider()
.getModels()
@@ -482,27 +606,29 @@ export function createAdmittedModels(
// The alternative route is organizer-provided and absent from Pi's catalog. Its rates are unknown.
// SDK-required zero rates are an internal sentinel only; application cost remains null for both routes.
- const selected: Model = catalog
- ? { ...catalog, maxTokens: metaOutputCeilings.get(catalog.id) ?? catalog.maxTokens }
- : {
- id: modelId,
- name: "Muse Spark Open",
- api: "openai-completions",
- provider: "baseten",
- baseUrl: "https://inference.baseten.co/v1",
- input: ["text", "image"],
- reasoning: true,
- contextWindow: 1048576,
- // Open serving does not publish a separate output ceiling; the context is the upper bound.
- maxTokens: 1048576,
- cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
- };
+ const selected: Model =
+ custom ??
+ (catalog
+ ? { ...catalog, maxTokens: metaOutputCeilings.get(catalog.id) ?? catalog.maxTokens }
+ : {
+ id: modelId,
+ name: "Muse Spark Open",
+ api: "openai-completions",
+ provider: "baseten",
+ baseUrl: "https://inference.baseten.co/v1",
+ input: ["text", "image"],
+ reasoning: true,
+ contextWindow: 1048576,
+ // Open serving does not publish a separate output ceiling; the context is the upper bound.
+ maxTokens: 1048576,
+ cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
+ });
// A recorded transport replays at full speed; it still waits out refusals like a live route.
const pacer =
configuration.pacer ??
(configuration.route === "live"
- ? sharedPacer(route, configuration.apiKey)
+ ? sharedPacer(custom !== null ? "openai-compatible" : route, configuration.apiKey)
: new RequestPacer(unpacedLimits));
const imageFiles =
@@ -512,6 +638,16 @@ export function createAdmittedModels(
const uploadSlots = Semaphore.makeUnsafe(imageUploadConcurrency);
+ // Baseten's Muse Spark media encoder takes at most eight images per request. The limits of a
+ // custom server and of OpenCode Go's upstream models are unknown, so they get the same window.
+ const eightImages = selected.provider === "baseten" || custom !== null || openCodeGo;
+
+ // None publishes an output ceiling for packet reviews, so their requests leave it unset.
+ const serverOutputLimit = selected.provider === "baseten" || custom !== null;
+
+ // Pi supplies each conversation's durable session; a request outside one gets this adapter's.
+ const fallbackSession = `moke-${randomUUID()}`;
+
/** Send one image to the Files API once a slot is free; any failure or stop leaves it inline. */
const uploadImage = (image: string, sha256: string, signal: AbortSignal) =>
Effect.runPromise(
@@ -656,7 +792,7 @@ export function createAdmittedModels(
const guarded = (
model: Model,
transcript: TranscriptContext,
- options: ProviderRequestOptions | undefined,
+ options: StreamOptions | undefined,
send: (
fetch: FetchFunction,
context: TranscriptContext,
@@ -705,11 +841,11 @@ export function createAdmittedModels(
)
throw new Error("Provider admission denied");
- // Baseten's Muse Spark media encoder accepts at most eight images per request, including
- // images retained in earlier tool results. Go has no Files API, so every image would be
- // resent inline on every request; it keeps the same window. The durable journal stays intact.
+ // Baseten's Muse Spark media encoder accepts at most eight images per request,
+ // including images retained in earlier tool results; a custom server gets the same window.
+ // The durable journal stays intact.
const bounded = admission.packetReview
- ? selected.provider !== "meta"
+ ? eightImages
? boundedImageContext(transcript, {
images: 8,
step: 4,
@@ -767,7 +903,7 @@ export function createAdmittedModels(
bounds.imageBytes > (admission.packetReview ? 64 : 2) * 1024 * 1024 ||
bounds.requestBytes > (admission.packetReview ? 72 : 3) * 1024 * 1024 ||
(!admission.packetReview && bounds.images > 6) ||
- (selected.provider !== "meta" && bounds.images > 8)
+ (eightImages && bounds.images > 8)
)
throw new Error("Transport admission denied");
dispatched = true;
@@ -784,7 +920,13 @@ export function createAdmittedModels(
try {
const dispatch = configuration.transport ?? globalThis.fetch;
const sentAt = performance.now();
- const response = await dispatch(input, init);
+
+ // Following a custom server's redirect would forward the drawings somewhere else.
+ const response = await dispatch(
+ input,
+ custom === null ? init : { ...init, redirect: "error" },
+ );
+
const elapsedMs = performance.now() - sentAt;
httpStatus = response.status;
@@ -792,7 +934,7 @@ export function createAdmittedModels(
// A rate-limit, capacity or model-routing refusal happens before generation, so
// resending it cannot duplicate paid work. Parallel sheet reviewers rely on this.
- const refused = await refusalOf(response, elapsedMs);
+ const refused = await refusalOf(response, elapsedMs, openCodeGo);
const retryAfterMs =
refused === undefined ? undefined : pacer.retryAfter(response.headers);
@@ -811,7 +953,8 @@ export function createAdmittedModels(
refusedUnsent = true;
await response.body?.cancel();
transportFailure = "http";
- rejectionDetail = refused === "rate_limit" ? "rate_limit" : "unclassified";
+ rejectionDetail =
+ refused === "rate_limit" || refused === "usage_limit" ? refused : "unclassified";
return Response.json(
{ error: { message: `Provider refused request: ${rejectionDetail}` } },
@@ -889,9 +1032,11 @@ export function createAdmittedModels(
? refusalDelay(refused.retryAfterMs, refusals)
: refused.cooldownMs;
- // A resend that could go out only after the budget ends the attempt now, without waiting.
+ // A usage limit lasts for hours, so resending only spends requests against it. A resend
+ // that could go out only after the budget ends the attempt now, without waiting.
if (
- refusals + 1 >= maxRefusals ||
+ refused.kind === "usage_limit" ||
+ refusals + 1 >= (openCodeGo ? openCodeMaxRefusals : maxRefusals) ||
pacer.now() + waitMs - admittedAt > refusalBudgetMs ||
options?.signal?.aborted
)
@@ -986,7 +1131,7 @@ export function createAdmittedModels(
};
const requestOptions = (
- options: ProviderRequestOptions | undefined,
+ options: StreamOptions | undefined,
fetch: FetchFunction,
cacheKey: string | undefined,
): SimpleStreamOptions => {
@@ -1003,7 +1148,8 @@ export function createAdmittedModels(
if (admission.packetReview) result.reasoningEffort = effort;
- // Pi's per-conversation session ID is deliberately not forwarded: sheet reviewers share a prefix.
+ // Except on OpenCode Go, Pi's per-conversation session ID is not forwarded: sheet reviewers share
+ // a prefix and its cache key.
if (selected.provider === "meta")
result.onPayload = async (payload) => {
if (!Predicate.isObject(payload)) return payload;
@@ -1026,17 +1172,19 @@ export function createAdmittedModels(
return { ...payload, ...changes };
};
- // Go routes and caches by session; the shared key keeps sheet reviewers on one cached prefix.
- else if (selected.provider === "opencode-go") {
- result.headers = { "User-Agent": opencodeGoUserAgent };
-
- if (cacheKey !== undefined) result.sessionId = cacheKey;
+ // OpenCode Go requires a stable session per conversation and routes and caches by it. Pi's
+ // provider sends it as `x-opencode-session`, with MOKE's identity, so sheet reviewers sharing a
+ // prompt prefix still keep their own sessions, as OpenCode's guidance asks.
+ else if (openCodeGo) {
+ result.sessionId = options?.sessionId ?? fallbackSession;
+ result.identity = openCodeIdentity;
}
- // Baseten routes cache hits by replica affinity rather than a request field.
- else if (cacheKey !== undefined) result.headers = { "x-session-affinity": cacheKey };
+ // Baseten routes cache hits by replica affinity rather than a request field. A custom server's
+ // caching is unknown, so it receives no routing key.
+ else if (cacheKey !== undefined && custom === null)
+ result.headers = { "x-session-affinity": cacheKey };
- if (!admission.packetReview || selected.provider !== "baseten")
- result.maxTokens = admission.maxOutputTokens;
+ if (!admission.packetReview || !serverOutputLimit) result.maxTokens = admission.maxOutputTokens;
if (options?.signal !== undefined) result.signal = options.signal;
@@ -1062,9 +1210,9 @@ export function createAdmittedModels(
),
streamSimple: (model, context, options) =>
guarded(model, context, options, (fetch, bounded, cacheKey) =>
- // Simple options inject a context-sized output limit. Packet requests on Baseten
- // use the API default; reasoning is already set explicitly in requestOptions.
- admission.packetReview && selected.provider === "baseten"
+ // Simple options inject a context-sized output limit. Packet requests on Baseten and a
+ // custom endpoint use the server's default; reasoning is set explicitly in requestOptions.
+ admission.packetReview && serverOutputLimit
? base.stream(model, bounded, requestOptions(options, fetch, cacheKey))
: base.streamSimple(model, bounded, requestOptions(options, fetch, cacheKey)),
),
diff --git a/backend/packet-review/service.ts b/backend/packet-review/service.ts
index f67f55a4..789d067c 100644
--- a/backend/packet-review/service.ts
+++ b/backend/packet-review/service.ts
@@ -73,6 +73,7 @@ import {
promptCacheKey,
packetReasoning,
reviewModelCapabilities,
+ routeModel,
type ProviderConfiguration,
isQuickGatewayRefusal,
} from "../inference/provider.ts";
@@ -123,11 +124,13 @@ const promptVersion = packetPromptVersion;
* 220 of 1,276 checks in 33 minutes. Run in parallel at 16 sheets, it recorded all 1,276 using
* about 1.5M of Meta's 4M tokens a minute, so Meta reviews start every sheet at once. The Baseten
* key allows 100 requests and 2M tokens a minute (2026-10-31); 16 sheet reviewers send about 40
- * requests a minute, and the shared request pacer holds any burst inside the limit.
+ * requests a minute, and the shared request pacer holds any burst inside the limit. OpenCode Go
+ * asks for typical coding-agent traffic, and a custom endpoint may be one self-hosted server, so
+ * both start eight at a time.
*/
export const defaultParallel = {
minSheets: 4,
- concurrency: { meta: 32, baseten: 16, "opencode-go": 16 },
+ concurrency: { meta: 32, baseten: 16, "opencode-go": 3, "openai-compatible": 8 },
setup: defaultSetupLimits,
// Sheet reviewers used 10 to 82 requests on drawing sheets; Spark Open once looped past 250.
sheetRequests: 120,
@@ -559,7 +562,8 @@ interface Configuration {
/** Packets with at least minSheets sheets review each sheet in its own conversation. */
readonly parallel?: {
readonly minSheets: number;
- readonly concurrency: Readonly>;
+ /** Sheet reviewers at once per provider; a provider left out uses `defaultParallel`. */
+ readonly concurrency: Readonly>>;
/** Coordinator setup's sheet and request limits; defaults to `defaultSetupLimits`. */
readonly setup?: SetupLimits;
/** Model requests one sheet reviewer may make before its sheet stops with its gaps shown. */
@@ -3216,7 +3220,7 @@ export class PacketReviews extends Context.Service<
if (!provider)
throw error("unavailable", "The selected model's provider is not connected.");
- const capabilities = reviewModelCapabilities(row.payload.model);
+ const capabilities = reviewModelCapabilities(row.payload.model, provider);
const assignments: SheetAssignments = {
sheets: new Map(),
@@ -3259,7 +3263,7 @@ export class PacketReviews extends Context.Service<
const toolRegistry = registryFor(row, assignments);
const admitted = createAdmittedModels(
- { ...provider, model: row.payload.model },
+ { ...provider, model: routeModel(provider, row.payload.model) },
{
packetReview: true,
maxInputTokens: 4 * capabilities.contextWindow,
@@ -3495,7 +3499,10 @@ export class PacketReviews extends Context.Service<
...review,
state: "paused",
providerFailure: diagnostic,
- error: `The provider refused the request (HTTP ${diagnostic.httpStatus ?? "error"}) until its retry limit ran out. Nothing was generated or charged. Findings and coverage were saved; resume when the provider is available.`,
+ error:
+ diagnostic.detail === "usage_limit"
+ ? "OpenCode reports a usage limit for this model (HTTP 429), so the review paused instead of sending more requests. Nothing was generated or charged. Findings and coverage were saved; OpenCode Console shows when the limit resets, and Resume continues then."
+ : `The provider refused the request (HTTP ${diagnostic.httpStatus ?? "error"}) until its retry limit ran out. Nothing was generated or charged. Findings and coverage were saved; resume when the provider is available.`,
})
: review,
false,
@@ -4097,7 +4104,9 @@ export class PacketReviews extends Context.Service<
Struct.assign(planned, {
parallel: {
stage: "setup" as const,
- concurrency: parallel.concurrency[model.provider],
+ concurrency:
+ parallel.concurrency[model.provider] ??
+ defaultParallel.concurrency[model.provider],
sheets: sheets.map((sheet) => ({
sheetId: sheet.id,
conversationId: null,
diff --git a/backend/review/execution.ts b/backend/review/execution.ts
index 483ab29e..8199d2b7 100644
--- a/backend/review/execution.ts
+++ b/backend/review/execution.ts
@@ -51,7 +51,23 @@ import {
selectedReviewPrompt,
packetPromptVersion,
} from "./prompts/review-prompt.ts";
-import { reviewModels } from "#lib/review/models.ts";
+import {
+ customContextWindow,
+ defaultOpenCodeGoModel,
+ type ReviewProvider,
+ reviewModels,
+} from "#lib/review/models.ts";
+
+/** The review model a provider selects when a request names none. */
+function defaultModel(provider: typeof ReviewProvider.Type, configured: string | undefined) {
+ if (provider === "openai-compatible") return "openai-compatible";
+
+ if (provider === "opencode-go") return configured ?? defaultOpenCodeGoModel;
+
+ return (
+ configured ?? (provider === "meta" ? "muse-spark-1.3" : "meta-models/muse-spark-open-1026")
+ );
+}
/** One parent ManagedRuntime enters callback Effects; this service never creates a runtime. */
export interface ExecutionConfiguration {
@@ -840,31 +856,41 @@ export class ReviewExecution extends Context.Service<
const requestedRoute = reviewModels.find((entry) => entry.id === request.model);
const model =
- (requestedRoute?.provider === "opencode-go" ? undefined : request.model) ??
- configuration.provider?.model ??
- ((configuration.provider?.provider ?? providers[0]?.provider ?? "meta") === "meta"
- ? "muse-spark-1.3"
- : "meta-models/muse-spark-open-1026");
+ (requestedRoute?.provider === "opencode-go" ||
+ requestedRoute?.provider === "openai-compatible"
+ ? undefined
+ : request.model) ??
+ defaultModel(
+ configuration.provider?.provider ?? providers[0]?.provider ?? "meta",
+ configuration.provider?.model,
+ );
const modelRoute = reviewModels.find((entry) => entry.id === model);
+ // Count-check records name Meta or Baseten; OpenCode Go and the custom endpoint run
+ // drawing reviews only.
+ if (
+ modelRoute !== undefined &&
+ modelRoute.provider !== "meta" &&
+ modelRoute.provider !== "baseten"
+ )
+ return yield* failure(
+ "unavailable",
+ "Count checks run on Meta or Baseten models. Choose one of them for this check; drawing reviews can use OpenCode Go or the custom endpoint.",
+ );
+
const provider = providers.find(
(entry) => (entry.provider ?? "meta") === modelRoute?.provider,
);
- if (provider === undefined)
+ const providerName = provider?.provider ?? "meta";
+
+ if (provider === undefined || (providerName !== "meta" && providerName !== "baseten"))
return yield* failure(
"unavailable",
"Count checks run on Meta or Baseten. Configure a supported provider credential before starting a live inspection.",
);
- const providerName = provider.provider ?? "meta";
-
- if (providerName === "opencode-go")
- return yield* failure(
- "unavailable",
- "Count checks run on Meta or Baseten. Choose one of their models for this inspection.",
- );
const selected = yield* port.inspect(new ExecutionSelection(request));
const evidence = yield* Schema.decodeUnknownEffect(ExecutionEvidence)(selected).pipe(
@@ -1273,18 +1299,35 @@ export class ReviewExecution extends Context.Service<
? null
: (configuration.provider.provider ?? "meta"),
model:
- configuration.provider?.model ??
- (configuration.provider === undefined
+ configuration.provider === undefined
? null
- : (configuration.provider.provider ?? "meta") === "meta"
- ? "muse-spark-1.3"
- : "meta-models/muse-spark-open-1026"),
- models: reviewModels.map((model) => ({
- ...model,
- available: providers.some(
- (provider) => (provider.provider ?? "meta") === model.provider,
- ),
- })),
+ : defaultModel(
+ configuration.provider.provider ?? "meta",
+ configuration.provider.model,
+ ),
+ models: reviewModels.map((model) => {
+ const provider = providers.find(
+ (entry) => (entry.provider ?? "meta") === model.provider,
+ );
+
+ const option = { ...model, available: provider !== undefined };
+
+ // The custom endpoint is shown by its own model name and address, never its key.
+ return model.provider !== "openai-compatible" ||
+ provider?.model === undefined ||
+ provider.baseUrl === undefined
+ ? option
+ : {
+ ...option,
+ label: provider.model,
+ endpoint: {
+ baseUrl: provider.baseUrl,
+ model: provider.model,
+ images: provider.images !== false,
+ contextWindow: provider.contextWindow ?? customContextWindow.default,
+ },
+ };
+ }),
segmentation: port.segmentation !== undefined,
promptVersion: reviewPromptVersion,
packetPromptVersion,
diff --git a/backend/review/prompts/review-prompt.ts b/backend/review/prompts/review-prompt.ts
index dc7d9da6..aea5c7e1 100644
--- a/backend/review/prompts/review-prompt.ts
+++ b/backend/review/prompts/review-prompt.ts
@@ -1,9 +1,9 @@
-import type { ReviewProvider } from "#lib/review/models.ts";
import { Match } from "effect";
import type {
ExecutionReviewContext,
ReviewDiscipline,
} from "../../../src/lib/review/execution.ts";
+import type { ReviewProvider } from "#lib/review/models.ts";
import master from "./assets/AGENTS.md" with { type: "text" };
import method from "./assets/REVIEW_METHOD.md" with { type: "text" };
import general from "./assets/disciplines/general.md" with { type: "text" };
@@ -85,11 +85,16 @@ export type PacketPromptRole = "review" | "coordinator" | "sheet";
const rollingImageGuidance = (model: string) =>
`${model} accepts at most eight images per request, including retained source images. Request at most eight render_sheet images in a tool batch, inspect their content and record concise page/content notes before requesting another batch. Earlier pixels may be replaced by an explicit omission notice in later requests; their metadata and durable artifacts remain available, but render an omitted detail again before making a new source claim. Rendering every assigned page remains required; the rolling image window is not a packet scope limit.`;
+/** A custom endpoint's image limits are unknown, so it gets Baseten's eight-image window. */
+const imageWindowGuidance =
+ "Each request carries at most eight images, including retained source images. Request at most eight render_sheet images in a tool batch, inspect their content and record concise page/content notes before requesting another batch. Earlier pixels may be replaced by an explicit omission notice in later requests; their metadata and durable artifacts remain available, but render an omitted detail again before making a new source claim. If rendered images arrive only as an omission notice, you cannot read drawings: record each affected check as Needs input naming the unread sheet instead of describing its content.";
+
const imageGuidance = {
baseten: rollingImageGuidance("Muse Spark Open"),
"opencode-go": rollingImageGuidance("This model route"),
meta: "Rendered pages and crops stay in your conversation. Render the full assigned page first, then focused crops at legible scale for dense notes, schedules, tables and details. Render a detail again before relying on a reading you are unsure of.",
-} as const;
+ "openai-compatible": imageWindowGuidance,
+} as const satisfies Record;
/** Shared instructions for citations whose text must be confirmed in a browser. */
export const browserCitationGuidance =
@@ -102,8 +107,9 @@ const hostedSearchGuidance = `${codeGuidance} Use search_sources and read_source
const sourceGuidance = {
baseten: hostedSearchGuidance,
"opencode-go": hostedSearchGuidance,
+ "openai-compatible": hostedSearchGuidance,
meta: `${codeGuidance} For other governing sources and adopted editions, use your built-in web search, then read_source on the primary official page to retrieve and record it; record exact citations and applicability. search_sources remains available as a fallback. Web search results alone are leads, not recorded evidence.`,
-} as const;
+} as const satisfies Record;
const roleGuidance: Record> = {
review: [],
diff --git a/desktop/connection-check.ts b/desktop/connection-check.ts
new file mode 100644
index 00000000..a7a80683
--- /dev/null
+++ b/desktop/connection-check.ts
@@ -0,0 +1,172 @@
+import { Effect, Option, Redacted, Schema } from "effect";
+
+/** How a custom endpoint answered one small tool-calling request. */
+export type EndpointCheck =
+ | { readonly kind: "ready" }
+ | { readonly kind: "no_tool_call" }
+ | { readonly kind: "rejected"; readonly status: number }
+ | { readonly kind: "unreachable" }
+ | { readonly kind: "unexpected" };
+
+const checkTool = "moke_connection_check";
+
+/** Only the fields the check reads; everything else in the answer is ignored. */
+const Completion = Schema.Struct({
+ choices: Schema.NonEmptyArray(
+ Schema.Struct({
+ message: Schema.Struct({
+ tool_calls: Schema.optional(
+ Schema.NullOr(
+ Schema.Array(Schema.Struct({ function: Schema.Struct({ name: Schema.String }) })),
+ ),
+ ),
+ }),
+ }),
+ ),
+});
+
+/** Larger answers are not a chat completion for this request. */
+const maxAnswerBytes = 1024 * 1024;
+
+/** A response's text, or undefined past the limit, without buffering more than the limit. */
+async function boundedText(response: Response) {
+ const reader = response.body?.getReader();
+ const chunks = new Array();
+ let bytes = 0;
+
+ if (reader)
+ try {
+ for (let part = await reader.read(); !part.done; part = await reader.read()) {
+ bytes += part.value.length;
+
+ if (bytes > maxAnswerBytes) return undefined;
+ chunks.push(part.value);
+ }
+ } finally {
+ await reader.cancel().catch(() => undefined);
+ }
+
+ return Buffer.concat(chunks).toString("utf8");
+}
+
+/**
+ * Send one tool-calling chat completion before the endpoint is saved. Packet reviews work only
+ * through tool calls, so an endpoint that answers in prose cannot run one. Provider error text is
+ * never read or shown; only the HTTP status is kept.
+ */
+export const checkConnection = Effect.fn("checkConnection")(function* (endpoint: {
+ readonly baseUrl: string;
+ readonly model: string;
+ readonly apiKey: Redacted.Redacted;
+ /** Provider-specific headers, such as OpenCode's session and client identity. */
+ readonly headers?: Readonly>;
+}) {
+ const response = yield* Effect.tryPromise({
+ try: (signal) =>
+ globalThis.fetch(`${endpoint.baseUrl}/chat/completions`, {
+ method: "POST",
+ headers: {
+ ...endpoint.headers,
+ authorization: `Bearer ${Redacted.value(endpoint.apiKey)}`,
+ "content-type": "application/json",
+ },
+ body: JSON.stringify({
+ model: endpoint.model,
+ messages: [{ role: "user", content: `Call the ${checkTool} tool once.` }],
+ tools: [
+ {
+ type: "function",
+ function: {
+ name: checkTool,
+ description: "Confirms that this endpoint can call tools.",
+ parameters: { type: "object", properties: {} },
+ },
+ },
+ ],
+ max_tokens: 1024,
+ stream: false,
+ }),
+ redirect: "error",
+ signal: AbortSignal.any([signal, AbortSignal.timeout(60_000)]),
+ }),
+ catch: () => "unreachable" as const,
+ }).pipe(Effect.option);
+
+ if (Option.isNone(response)) return { kind: "unreachable" } satisfies EndpointCheck;
+
+ if (!response.value.ok) {
+ yield* Effect.promise(() => response.value.body?.cancel() ?? Promise.resolve());
+
+ return { kind: "rejected", status: response.value.status } satisfies EndpointCheck;
+ }
+
+ const text = yield* Effect.tryPromise(() => boundedText(response.value)).pipe(Effect.option);
+
+ if (Option.isNone(text) || text.value === undefined)
+ return { kind: "unexpected" } satisfies EndpointCheck;
+
+ return Option.match(Schema.decodeUnknownOption(Schema.fromJsonString(Completion))(text.value), {
+ onNone: (): EndpointCheck => ({ kind: "unexpected" }),
+ onSome: (completion): EndpointCheck =>
+ completion.choices.some((choice) =>
+ choice.message.tool_calls?.some((call) => call.function.name === checkTool),
+ )
+ ? { kind: "ready" }
+ : { kind: "no_tool_call" },
+ });
+});
+
+/**
+ * OpenCode Go identifies its client by user agent and `x-opencode-client`, and routes and caches
+ * by `x-opencode-session`, which it requires (400 `MissingSessionID` without it, 2026-11-01).
+ */
+export function openCodeHeaders(version: string, session: string) {
+ return {
+ "user-agent": `moke/${version}`,
+ "x-opencode-client": "moke",
+ "x-opencode-session": session,
+ };
+}
+
+/** What OpenCode Go's refusals mean for a Go key, per its Console docs (2026-11-01). */
+function describeOpenCodeRefusal(status: number) {
+ if (status === 401)
+ return "OpenCode refused the key (HTTP 401). Copy a key from a workspace with a Go subscription.";
+
+ if (status === 403)
+ return "OpenCode refused this model for the key (HTTP 403). In Console Settings › Privacy, DeepSeek needs the Global region and Muse Spark Contributor needs “Allow paid endpoints that train on request data”.";
+
+ if (status === 429)
+ return "OpenCode reports a usage limit for this model (HTTP 429). Go limits reset over 5-hour, weekly and monthly windows.";
+
+ return undefined;
+}
+
+/** Plain-language result for the save confirmation; never includes provider text. */
+export function describeEndpointCheck(
+ check: EndpointCheck,
+ service: "opencode-go" | "custom" = "custom",
+) {
+ if (service === "opencode-go" && check.kind === "rejected") {
+ const refusal = describeOpenCodeRefusal(check.status);
+
+ if (refusal !== undefined) return refusal;
+ }
+
+ switch (check.kind) {
+ case "ready":
+ return "The endpoint answered and called the test tool.";
+ case "no_tool_call":
+ return "The endpoint answered but did not call the test tool. Packet reviews need a model that supports tool calling, so reviews on this endpoint will likely stop early.";
+ case "rejected":
+ return check.status === 401 || check.status === 403
+ ? `The endpoint refused the key (HTTP ${check.status}).`
+ : check.status === 404
+ ? "The endpoint answered HTTP 404. Check the base URL (it usually ends in /v1) and the model name."
+ : `The endpoint refused the test request (HTTP ${check.status}).`;
+ case "unreachable":
+ return "The endpoint could not be reached within a minute.";
+ case "unexpected":
+ return "The endpoint's answer was not an OpenAI chat completion.";
+ }
+}
diff --git a/desktop/credential-files.ts b/desktop/credential-files.ts
index 303ef2ab..86ea3dfd 100644
--- a/desktop/credential-files.ts
+++ b/desktop/credential-files.ts
@@ -8,11 +8,41 @@ export class CredentialError extends Schema.TaggedError()("Cred
message: Schema.String,
}) {}
-/** Parse only the explicitly selected, canonical provider routes. */
+/**
+ * A custom endpoint's address without a trailing slash. It may not carry credentials, a query or a
+ * fragment, which the SDK would either drop or send with every request.
+ */
+export function customEndpointUrl(value: string) {
+ const url = new URL(value.trim());
+ const loopback = ["localhost", "127.0.0.1", "[::1]"].includes(url.hostname);
+
+ if (
+ (url.protocol !== "https:" && !(url.protocol === "http:" && loopback)) ||
+ url.username !== "" ||
+ url.password !== "" ||
+ url.search !== "" ||
+ url.hash !== ""
+ )
+ throw new Error("Unsupported endpoint address");
+
+ return `${url.origin}${url.pathname.replace(/\/+$/, "")}`;
+}
+
+/** Parse the canonical Meta, Baseten and OpenCode Go routes, or the reviewer's custom endpoint. */
export function parseProviderConfiguration(text: string) {
try {
const config = Schema.decodeUnknownSync(Schema.fromJsonString(InferenceConfiguration))(text);
+ if (config.provider === "openai-compatible") {
+ if (config.model.length > 256 || Redacted.value(config.apiKey).length > 4096)
+ throw new Error("Invalid route");
+
+ return { ...config, baseUrl: customEndpointUrl(config.baseUrl) };
+ }
+
+ if (config.images !== undefined || config.contextWindow !== undefined)
+ throw new Error("Invalid route");
+
const endpoint = reviewProviderRoutes[config.provider].endpoint;
if (
diff --git a/desktop/credentials.ts b/desktop/credentials.ts
index 78d1456f..8e691fec 100644
--- a/desktop/credentials.ts
+++ b/desktop/credentials.ts
@@ -1,12 +1,13 @@
import { safeStorage } from "electron";
import { Schema } from "effect";
import { existsSync } from "node:fs";
-import { readFile, writeFile } from "node:fs/promises";
+import { readFile, rm, writeFile } from "node:fs/promises";
import { join } from "node:path";
import { InferenceConfiguration } from "../src/lib/backend-rpc.ts";
import { reviewProviderRoutes } from "../src/lib/review/models.ts";
import {
CredentialError,
+ parseProviderConfiguration,
parseProviderConfigurations,
readProviderConfigurations,
} from "./credential-files.ts";
@@ -16,6 +17,24 @@ const StoredCredential = Schema.Struct({
encrypted: Schema.NonEmptyString,
});
+/** Imported Meta and Baseten credentials. */
+const importedFile = "provider-credential.json";
+
+/**
+ * Connections saved in Review settings, one file each, so removing one leaves the others. They
+ * apply even when a session-only file supplies Meta and Baseten.
+ */
+const settingsFiles = {
+ "opencode-go": "opencode-go-credential.json",
+ "openai-compatible": "custom-endpoint-credential.json",
+} as const;
+
+/** A provider whose connection is saved from Review settings. */
+export type SettingsProvider = keyof typeof settingsFiles;
+
+const isSettingsProvider = (provider: string): provider is SettingsProvider =>
+ Object.hasOwn(settingsFiles, provider);
+
const secureStorageAvailable = async () => {
if (!(await safeStorage.isAsyncEncryptionAvailable())) return false;
@@ -28,36 +47,54 @@ const secureStorageAvailable = async () => {
return probe.subarray(0, 3).toString() !== "v10";
};
-/** Packaged launches use OS-encrypted storage or an explicitly selected session-only file. */
-export async function readInferenceConfigurations(directory: string, packaged: boolean) {
- const sessionFile = process.env.MOKE_SESSION_CREDENTIAL_FILE;
+/** Decrypt one stored credential file, or fail without revealing its contents. */
+async function readStored(path: string, message: string) {
+ if (!(await secureStorageAvailable()))
+ throw new CredentialError({
+ message:
+ "Secure credential storage is unavailable. Select a session-only credential configuration.",
+ });
- if (sessionFile !== undefined) return readProviderConfigurations(sessionFile, true);
- const storedFile = join(directory, "provider-credential.json");
+ try {
+ const stored = Schema.decodeUnknownSync(Schema.fromJsonString(StoredCredential))(
+ await readFile(path, "utf8"),
+ );
- if (existsSync(storedFile)) {
- if (!(await secureStorageAvailable()))
- throw new CredentialError({
- message:
- "Secure credential storage is unavailable. Select a session-only credential configuration.",
- });
+ const decrypted = await safeStorage.decryptStringAsync(Buffer.from(stored.encrypted, "base64"));
+
+ return decrypted.result;
+ } catch {
+ throw new CredentialError({ message });
+ }
+}
+
+/** Encrypt with the OS store and write an owner-only file; never falls back to plain text. */
+async function writeStored(path: string, plain: string) {
+ if (!(await secureStorageAvailable()))
+ throw new CredentialError({
+ message:
+ "OS credential encryption is unavailable. Use an explicitly selected session-only configuration.",
+ });
- try {
- const stored = Schema.decodeUnknownSync(Schema.fromJsonString(StoredCredential))(
- await readFile(storedFile, "utf8"),
- );
+ const encrypted = await safeStorage.encryptStringAsync(plain);
- const decrypted = await safeStorage.decryptStringAsync(
- Buffer.from(stored.encrypted, "base64"),
- );
+ await writeFile(path, JSON.stringify({ version: 1, encrypted: encrypted.toString("base64") }), {
+ mode: 0o600,
+ flush: true,
+ });
+}
- return parseProviderConfigurations(decrypted.result);
- } catch {
- throw new CredentialError({
- message: "The saved provider credential could not be unlocked.",
- });
- }
- }
+/** Session file, imported credentials, or (in development only) the environment. */
+async function readImportedConfigurations(directory: string, packaged: boolean) {
+ const sessionFile = process.env.MOKE_SESSION_CREDENTIAL_FILE;
+
+ if (sessionFile !== undefined) return readProviderConfigurations(sessionFile, true);
+ const storedFile = join(directory, importedFile);
+
+ if (existsSync(storedFile))
+ return parseProviderConfigurations(
+ await readStored(storedFile, "The saved provider credential could not be unlocked."),
+ );
if (packaged) return [];
@@ -88,31 +125,106 @@ export async function readInferenceConfigurations(directory: string, packaged: b
});
}
-/** A shell-selected configuration is encrypted before saving, and never enters renderer RPC. */
-export async function storeInferenceConfiguration(directory: string, source: string) {
- const incoming = await readProviderConfigurations(source);
- const existing = await readInferenceConfigurations(directory, true);
+/**
+ * Packaged launches use OS-encrypted storage or an explicitly selected session-only file.
+ * Connections saved in Review settings replace the same provider from those sources and are listed
+ * after them, so Meta or Baseten stays the startup default when present.
+ */
+export async function readInferenceConfigurations(directory: string, packaged: boolean) {
+ let configs = await readImportedConfigurations(directory, packaged);
- const configs = [
- ...incoming,
- ...existing.filter((entry) => !incoming.some((item) => item.provider === entry.provider)),
- ];
+ // A session-only launch must still start when the keyring is down.
+ if (process.env.MOKE_SESSION_CREDENTIAL_FILE !== undefined && !(await secureStorageAvailable()))
+ return configs;
- if (!(await secureStorageAvailable()))
+ for (const [provider, file] of Object.entries(settingsFiles)) {
+ const stored = join(directory, file);
+
+ if (!existsSync(stored)) continue;
+
+ const saved = parseProviderConfiguration(
+ await readStored(stored, "A connection saved in Review settings could not be unlocked."),
+ );
+
+ if (saved.provider !== provider)
+ throw new CredentialError({
+ message: "A connection saved in Review settings is for another provider.",
+ });
+ configs = [...configs.filter((entry) => entry.provider !== provider), saved];
+ }
+
+ return configs;
+}
+
+/** Save a Review settings connection; the next launch passes it to the backend. */
+export async function storeSettingsConnection(
+ directory: string,
+ config: typeof InferenceConfiguration.Type,
+) {
+ const parsed = parseProviderConfiguration(
+ JSON.stringify(Schema.encodeSync(InferenceConfiguration)(config)),
+ );
+
+ if (!isSettingsProvider(parsed.provider))
throw new CredentialError({
- message:
- "OS credential encryption is unavailable. Use an explicitly selected session-only configuration.",
+ message: "Meta and Baseten keys are imported from the File menu.",
});
- const encrypted = await safeStorage.encryptStringAsync(
+ await writeStored(
+ join(directory, settingsFiles[parsed.provider]),
+ JSON.stringify(Schema.encodeSync(InferenceConfiguration)(parsed)),
+ );
+}
+
+/**
+ * Forget a saved Review settings connection, including a copy imported from the File menu by an
+ * earlier version; a session-only file can still supply one.
+ */
+export async function removeSettingsConnection(directory: string, provider: SettingsProvider) {
+ await rm(join(directory, settingsFiles[provider]), { force: true });
+ const imported = join(directory, importedFile);
+
+ if (!existsSync(imported)) return;
+
+ const configs = parseProviderConfigurations(
+ await readStored(imported, "The saved provider credential could not be unlocked."),
+ );
+
+ const kept = configs.filter((entry) => entry.provider !== provider);
+
+ if (kept.length === configs.length) return;
+
+ if (kept.length === 0) return await rm(imported, { force: true });
+
+ await writeStored(
+ imported,
JSON.stringify({
- providers: configs.map((config) => Schema.encodeSync(InferenceConfiguration)(config)),
+ providers: kept.map((config) => Schema.encodeSync(InferenceConfiguration)(config)),
}),
);
+}
- await writeFile(
- join(directory, "provider-credential.json"),
- JSON.stringify({ version: 1, encrypted: encrypted.toString("base64") }),
- { mode: 0o600, flush: true },
- );
+/** A shell-selected configuration is encrypted before saving, and never enters renderer RPC. */
+export async function storeInferenceConfiguration(directory: string, source: string) {
+ const incoming = await readProviderConfigurations(source);
+ const saved = incoming.filter((entry) => isSettingsProvider(entry.provider));
+ const imported = incoming.filter((entry) => !isSettingsProvider(entry.provider));
+
+ if (imported.length > 0) {
+ const existing = await readImportedConfigurations(directory, true);
+
+ const configs = [
+ ...imported,
+ ...existing.filter((entry) => !imported.some((item) => item.provider === entry.provider)),
+ ];
+
+ await writeStored(
+ join(directory, importedFile),
+ JSON.stringify({
+ providers: configs.map((config) => Schema.encodeSync(InferenceConfiguration)(config)),
+ }),
+ );
+ }
+
+ for (const entry of saved) await storeSettingsConnection(directory, entry);
}
diff --git a/desktop/main.ts b/desktop/main.ts
index 2025c019..618170c5 100644
--- a/desktop/main.ts
+++ b/desktop/main.ts
@@ -16,12 +16,22 @@ import { appendFileSync } from "node:fs";
import { mkdir, readFile, stat, writeFile } from "node:fs/promises";
import { basename, dirname, extname, isAbsolute, join, relative, resolve, sep } from "node:path";
import { fileURLToPath, pathToFileURL } from "node:url";
+import { randomUUID } from "node:crypto";
import { ReviewDesktopRpc, ReviewShellRpc } from "../src/lib/review/shell.ts";
import { ReviewError, ReviewStorageError } from "../src/lib/review/contracts.ts";
import { cachedPromptShare } from "../src/lib/review/packet.ts";
+import { reviewProviderRoutes } from "../src/lib/review/models.ts";
import { BackendApi, type BackendLaunch } from "./backend.ts";
import { ReviewProxy, ExecutionProxy, PacketProxy, CloudReviewProxy } from "./review-proxy.ts";
-import { readInferenceConfigurations, storeInferenceConfiguration } from "./credentials.ts";
+import {
+ readInferenceConfigurations,
+ removeSettingsConnection,
+ type SettingsProvider,
+ storeInferenceConfiguration,
+ storeSettingsConnection,
+} from "./credentials.ts";
+import { CredentialError, customEndpointUrl } from "./credential-files.ts";
+import { checkConnection, describeEndpointCheck, openCodeHeaders } from "./connection-check.ts";
import { readModalConfiguration } from "./modal-credentials.ts";
import { createDropImports } from "./drop-imports.ts";
@@ -171,6 +181,36 @@ if (!app.requestSingleInstanceLock()) {
}).catch(() => undefined);
};
+ /** Confirm, delete a Review settings connection and restart; false when declined. */
+ const removeConnection = (provider: SettingsProvider, name: string) =>
+ Effect.gen(function* () {
+ const confirmation = yield* Effect.tryPromise({
+ try: () =>
+ dialog.showMessageBox({
+ type: "warning",
+ buttons: ["Cancel", "Remove and restart"],
+ defaultId: 0,
+ cancelId: 0,
+ message: `Remove ${name}?`,
+ detail:
+ "Its saved key is deleted and MOKE restarts. Reviews already run on it keep their results.",
+ }),
+ catch: () =>
+ new ReviewStorageError({ message: "The remove confirmation could not open." }),
+ });
+
+ if (confirmation.response !== 1) return false;
+ yield* Effect.tryPromise({
+ try: () => removeSettingsConnection(dataDirectory, provider),
+ catch: () =>
+ new ReviewStorageError({ message: "The saved connection could not be removed." }),
+ });
+ app.relaunch();
+ app.quit();
+
+ return true;
+ });
+
const shellHandlers = ReviewShellRpc.toLayer(
Effect.gen(function* () {
const { api } = yield* BackendApi;
@@ -403,6 +443,111 @@ if (!app.requestSingleInstanceLock()) {
return true;
}),
+ SaveCustomEndpoint: (settings) =>
+ Effect.gen(function* () {
+ const baseUrl = yield* Effect.try({
+ try: () => customEndpointUrl(settings.baseUrl),
+ catch: () =>
+ new ReviewStorageError({
+ message:
+ "Enter the endpoint's https:// address, or http:// for a server on this computer, without a query or sign-in details.",
+ }),
+ });
+
+ const check = yield* checkConnection({
+ baseUrl,
+ model: settings.model,
+ apiKey: settings.apiKey,
+ });
+
+ const confirmation = yield* Effect.tryPromise({
+ try: () =>
+ dialog.showMessageBox({
+ type: check.kind === "ready" ? "question" : "warning",
+ buttons: ["Cancel", "Save and restart"],
+ defaultId: check.kind === "ready" ? 1 : 0,
+ cancelId: 0,
+ message: "Save this custom endpoint?",
+ detail: `${describeEndpointCheck(check)} MOKE restarts to connect it. The key is encrypted on this computer and is used only for reviews you run here.`,
+ }),
+ catch: () =>
+ new ReviewStorageError({ message: "The save confirmation could not open." }),
+ });
+
+ if (confirmation.response !== 1) return false;
+ yield* Effect.tryPromise({
+ try: () =>
+ storeSettingsConnection(dataDirectory, {
+ provider: "openai-compatible",
+ apiKey: settings.apiKey,
+ baseUrl,
+ model: settings.model,
+ images: settings.images,
+ contextWindow: settings.contextWindow,
+ }),
+ catch: (cause) =>
+ new ReviewStorageError({
+ message:
+ cause instanceof CredentialError
+ ? cause.message
+ : "The custom endpoint could not be saved.",
+ }),
+ });
+ app.relaunch();
+ app.quit();
+
+ return true;
+ }),
+ RemoveCustomEndpoint: () =>
+ removeConnection("openai-compatible", "the custom endpoint"),
+ SaveOpenCodeGo: (settings) =>
+ Effect.gen(function* () {
+ const upstream = settings.model;
+
+ const check = yield* checkConnection({
+ baseUrl: reviewProviderRoutes["opencode-go"].endpoint,
+ model: upstream,
+ apiKey: settings.apiKey,
+ headers: openCodeHeaders(app.getVersion(), `moke-check-${randomUUID()}`),
+ });
+
+ const confirmation = yield* Effect.tryPromise({
+ try: () =>
+ dialog.showMessageBox({
+ type: check.kind === "ready" ? "question" : "warning",
+ buttons: ["Cancel", "Save and restart"],
+ defaultId: check.kind === "ready" ? 1 : 0,
+ cancelId: 0,
+ message: "Save this OpenCode Go key?",
+ detail: `${describeEndpointCheck(check, "opencode-go")} Tested with ${upstream}. MOKE restarts to connect it. The key is encrypted on this computer and is used only for reviews you run here.`,
+ }),
+ catch: () =>
+ new ReviewStorageError({ message: "The save confirmation could not open." }),
+ });
+
+ if (confirmation.response !== 1) return false;
+ yield* Effect.tryPromise({
+ try: () =>
+ storeSettingsConnection(dataDirectory, {
+ provider: "opencode-go",
+ apiKey: settings.apiKey,
+ baseUrl: reviewProviderRoutes["opencode-go"].endpoint,
+ model: settings.model,
+ }),
+ catch: (cause) =>
+ new ReviewStorageError({
+ message:
+ cause instanceof CredentialError
+ ? cause.message
+ : "The OpenCode Go key could not be saved.",
+ }),
+ });
+ app.relaunch();
+ app.quit();
+
+ return true;
+ }),
+ RemoveOpenCodeGo: () => removeConnection("opencode-go", "the OpenCode Go key"),
};
}),
);
diff --git a/docs/deployment.md b/docs/deployment.md
index 70d8024a..0895fcf8 100644
--- a/docs/deployment.md
+++ b/docs/deployment.md
@@ -122,5 +122,14 @@ Meta uses `https://api.meta.ai/v1` and `muse-spark-1.3`; Baseten uses
is selected. Packaged builds do not auto-load `.env`. The shell sends the key
over the private backend startup pipe; renderer RPC and packages exclude it.
+Review settings can add an OpenCode Go key and one OpenAI-compatible endpoint.
+The renderer sends each key to the shell once; the shell encrypts it with
+safeStorage in its own file and restarts. Like imported credentials, it reaches the backend only over the startup
+pipe. A custom endpoint's key is never sent to cloud reviews. This is the one
+exception to keeping keys out of renderer RPC: a pasted key crosses once, as a
+redacted value, and is never returned. See
+[OpenCode Go](inference.md#opencode-go) and
+[custom endpoints](inference.md#custom-openai-compatible-endpoint).
+
Set `MOKE_E2E_LIVE=1` only for the explicitly budgeted packaged acceptance test.
It adds a live inspection to the ordinary four-outcome desktop flow.
diff --git a/docs/inference.md b/docs/inference.md
index f45411a4..4e35a4fe 100644
--- a/docs/inference.md
+++ b/docs/inference.md
@@ -37,8 +37,8 @@ refuses it. The other three Go models here do not train: MiMo-V2.6-Flash and GLM
nothing, and GPT-6 Luna keeps abuse logs for 30 days. They have not been tried on drawings.
- **Traffic.** Go is designed for coding agents and monitors traffic for abuse. Parallel drawing
- reviews are not typical coding traffic. Moke identifies itself as `moke-review/1.0`, sends a session
- ID per prompt prefix and runs 16 sheet reviewers at a time.
+ reviews are not typical coding traffic. Moke identifies itself as `moke/`, sends a session
+ ID per conversation and runs 3 sheet reviewers at a time. See [OpenCode Go](#opencode-go).
- **Images.** Go has no Files API, so images travel inline. Reviews keep the eight-image window Baseten
uses, so a reviewer inspects a batch before requesting the next.
- **The only chat route once connected.** With a Go key present, the model menu and the Initial Review
@@ -113,8 +113,8 @@ after it began are refused again. Baseten's 429 carries no `Retry-After`. Meta
also answers a served model with HTTP 404 `model_not_found` now and then (1 in 8
requests for one team's key on 2026-10-30). Nothing is generated, so that request
alone is resent after its own backoff. A refused request is resent within the same
-admitted attempt for up to 10 minutes or 40 sends, and stops at once if its next
-send could go out only after the 10 minutes. A packet request refused on every
+admitted attempt for up to 10 minutes or 40 sends (11 on OpenCode Go), and stops at
+once if its next send could go out only after the 10 minutes. A packet request refused on every
send generated nothing, so the review pauses without an unresolved request and
says it was not charged; Resume continues it. Other failures are not resent.
Large packets review each sheet in its own conversation; see
@@ -209,6 +209,132 @@ the same key and a 7,216-token prefix was 99.1% cached. Each review records its
token totals, overall and per sheet reviewer. The packet panel shows the cached
share, and **Copy review diagnostics** includes it for every finished review.
+## OpenCode Go
+
+Review settings → OpenCode Go connects an [OpenCode Go](https://opencode.ai/docs/go/)
+subscription, so reviews need not spend Meta or Baseten credits. Paste a key from
+the Console harnesses page (`oc_sk_...`) and pick the model to test it with. In
+development, `OPENCODE_API_KEY` in `.env` does the same; Pi and OpenCode read the
+same variable. The model menu then offers these Go models, which read images and
+call tools:
+
+| Review model | OpenCode Go wire format |
+| ---------------------------- | ----------------------- |
+| `glm-5.3-flash` | Chat Completions |
+| `muse-spark-1.3-contributor` | Responses |
+| `mimo-v2.6-flash` | Chat Completions |
+| `gpt-6-luna` | Responses |
+
+Requests go through Pi's built-in `opencode-go` provider, which OpenCode lists as
+a supported harness. Its catalog picks each model's wire format, reasoning field
+and request fields, under `https://opencode.ai/inference/go/v1`. OpenCode asks
+clients for a stable `x-opencode-session` per conversation and rejects requests
+without one (HTTP 400 `MissingSessionID`, checked 2026-11-01). Pi sends it from
+each durable conversation's session ID, so every sheet reviewer keeps its own
+session across restarts; Baseten's shared prefix key is not used. Requests also
+identify MOKE with `User-Agent: moke/` and `x-opencode-client: moke`,
+as OpenCode asks of third-party clients. Free Go models are not offered: OpenCode
+answers them with HTTP 403 outside its own app.
+
+Go meters spend per model over 5-hour, weekly and monthly windows (20%, 50% and
+100% of the monthly limit) and publishes no request rate or concurrency limit.
+Its [docs](https://opencode.ai/docs/go/) say Go "is designed for OpenCode and
+other coding agents", ask clients to "send typical coding agent traffic", and
+monitor "for abuse that degrades the experience for other users". OpenCode's
+[terms](https://opencode.ai/legal/terms-of-service) also bar "placing an
+unreasonable load" on its infrastructure and using the service on behalf of a
+third party. MOKE is an agent but not a coding agent, so it keeps its traffic
+modest, identifies itself honestly, and should not run client work on a Go key:
+
+- A packet review starts three sheet reviewers at once, about one person's agents.
+ One reviewer sends about three requests a minute (measured on Muse Spark 1.3,
+ 2026-10-30), so a 29-sheet review takes about an hour at that speed.
+- The pacer caps every use of the key at 60 requests and 5M tokens a minute. This
+ is MOKE's own ceiling, not a published limit.
+- A `GoUsageLimitError`, `BudgetLimitError` or `CreditLimitExceeded` 429 is never
+ resent, matching OpenCode's own client. The review pauses until the reviewer
+ resumes it.
+- Any other 429 is resent at most ten times, also matching OpenCode's client.
+
+"Extra Usage" on the Console's Go page moves requests past a limit onto
+pay-as-you-go instead of refusing them, so leave it off to keep the limit as a
+hard stop.
+
+Packet reviews keep Baseten's eight-image window. A full window is about 4.5 MB
+of base64 images per request, more than a coding agent's text request, and is the
+least typical part of this traffic. Model images are at most 2048 pixels on their
+long edge; OpenCode's catalog suggests 2000, so a model that receives them
+resized could place an image box up to about 2% off.
+
+Some models need Console settings first.
+Muse Spark 1.3 Contributor needs "Allow paid endpoints that train on request
+data" under Settings › Privacy. Meta may then train on those reviews' drawings and
+text. **Test and save** sends one tool-calling Chat Completions request (OpenCode
+translates the format for every model) and reports a refused key, a refused
+model or a usage limit. The key is stored and removed like a custom endpoint's,
+in `opencode-go-credential.json`. Count checks stay on Meta and Baseten, and SAM
+3.1 keeps using the Meta connection.
+
+## Model for Initial Review and new conversations
+
+Review settings → Model connections chooses the model the Initial Review button
+and new conversations use. Until it is set, a connected OpenCode Go key selects
+Muse Spark 1.3 Contributor, then a connected custom endpoint, then Muse Spark 1.3.
+The choice is stored
+in the window's local storage and holds no credential. A review records the model
+it started with. Initial Review runs on this computer whenever its model's key
+stays here.
+
+## Custom OpenAI-compatible endpoint
+
+Review settings → Custom endpoint runs drawing reviews on another server that
+speaks the OpenAI Chat Completions API, such as vLLM, Ollama, LM Studio or a
+hosted gateway. Use the OpenCode Go section for OpenCode, which needs its session
+header. Enter the base URL (usually ending in `/v1`), the model name the server
+expects, the API key, the model's context window and whether it reads images.
+The context must be at least 32,768 tokens: packet review instructions alone are
+about 15,000 (59 KB), before tool definitions, sheet images and conversation. The
+address must be `https://`, or `http://` for a server on this computer
+(`localhost`, `127.0.0.1`, `[::1]`), without sign-in details, a query or a
+fragment.
+
+**Test and save** first sends one small tool-calling request from the desktop
+shell. Packet reviews work through tool calls, so the confirmation says whether
+the model called the test tool, refused the key, or answered with something
+other than a chat completion. Only the HTTP status is kept, never provider text.
+Saving encrypts the endpoint with Electron safeStorage in
+`custom-endpoint-credential.json`, apart from imported Meta and Baseten
+credentials, and restarts the app. Connections saved in Review settings apply
+even when a session-only file supplies Meta and Baseten. The key is never sent
+back to the renderer; editing the endpoint means entering the key again.
+**Remove** deletes the file and restarts. Saving and removing are disabled while
+a review runs, because a restart marks an in-flight request unresolved. A
+provider set imported from File → Import provider credential configuration may
+also carry one `opencode-go` entry and one `openai-compatible` entry, with
+optional `images` and `contextWindow` fields for the latter; each is stored the
+same way, and a session-only file may include them too.
+
+The endpoint appears in the model menu as one fixed review model,
+`openai-compatible`, labelled with its model name. A review records that ID;
+the upstream model name stays in the endpoint's settings, so a paused review
+resumes on whatever model the endpoint names then.
+
+Requests use only the fields such servers commonly accept: a `system` role,
+`max_tokens` outside packet review (packet requests leave it to the server),
+and no `store`, `reasoning_effort`, prompt-cache key or session-affinity header.
+The server's limits are unknown, so packet reviews keep the eight-image request
+window used for Baseten and start eight sheet reviewers at once. The shared
+pacer starts at 600 requests and 10M tokens a minute, adopts the server's
+`x-ratelimit-*` headers, and waits out 429 refusals as for the other providers.
+A text-only model receives an omission notice in place of each image, and the
+prompt tells it to record unread sheets as Needs input.
+
+SAM 3.1 still runs on the Meta connection, so device counts and finding zooms
+keep using Meta credits while chat requests go to the endpoint. Without a Meta
+key, reviews on the endpoint run without SAM. The custom endpoint does not run
+cloud reviews: its key never leaves this computer. Count checks also stay on Meta and Baseten,
+whose execution records are constrained to those providers.
+
## Packaged desktop credentials
Packaged builds use an explicitly selected private credential file or the File
diff --git a/docs/review-runtime.md b/docs/review-runtime.md
index d6e21724..826d953f 100644
--- a/docs/review-runtime.md
+++ b/docs/review-runtime.md
@@ -39,7 +39,8 @@ The review moves through three stages, recorded in `PacketReview.parallel`:
is built from it, before and after a restart.
2. **Sheets.** One conversation per sheet with unsettled checks. They run `concurrency` at a time:
32 on Meta (3,000 requests and 4M tokens a minute per team) and 16 on Baseten (100 requests and
- 2M tokens a minute for the hackathon key). Sixteen Baseten reviewers send about 40 requests a
+ 2M tokens a minute for the hackathon key). OpenCode Go runs 3 and a custom endpoint 8; see
+ [OpenCode Go](inference.md#opencode-go). Sixteen Baseten reviewers send about 40 requests a
minute; the shared [request pacer](inference.md#rate-limit-pacing-and-refusals) holds bursts and
refusals inside the key's limits. A sheet reviewer can
open, record coverage for, and segment only its own sheet. It records findings visible on that
diff --git a/src/lib/backend-rpc.ts b/src/lib/backend-rpc.ts
index 1f76764a..efe405c8 100644
--- a/src/lib/backend-rpc.ts
+++ b/src/lib/backend-rpc.ts
@@ -1,11 +1,11 @@
import { Schema } from "effect";
import { Rpc, RpcGroup } from "effect/rpc";
import { ReviewFilesRpc, ReviewRpc } from "./review/contracts.ts";
-import { ReviewProvider } from "./review/models.ts";
import { PacketReviewRpc } from "./review/packet.ts";
import { ExecutionRpc } from "./review/execution.ts";
import { ReviewPackageFilesRpc } from "./review/packages.ts";
import { CloudReviewRpc } from "./review/cloud.ts";
+import { customContextWindow, ReviewProvider } from "./review/models.ts";
/** A safe failure at the database file, migration, or recovery boundary. */
export class DatabaseFileError extends Schema.TaggedError()(
@@ -38,12 +38,31 @@ const ProcessingConfiguration = Schema.Struct({
nativeLibraryPath: Path,
});
-/** Credentials cross the startup pipe only; application exports never contain them. */
+/**
+ * Credentials cross the startup pipe only; application exports never contain them. Plain HTTP is
+ * accepted only for a server on this computer, so a key never crosses a network unencrypted.
+ */
export const InferenceConfiguration = Schema.Struct({
provider: ReviewProvider,
apiKey: Schema.RedactedFromValue(Schema.NonEmptyString),
- baseUrl: Schema.String.check(Schema.isPattern(/^https:\/\/[^\s]+$/)),
+ baseUrl: Schema.String.check(
+ Schema.isPattern(
+ /^(?:https:\/\/[^\s]+|http:\/\/(?:localhost|127\.0\.0\.1|\[::1\])(?::\d+)?(?:\/[^\s]*)?)$/,
+ ),
+ ),
+ /** The upstream model name; for Meta and Baseten it is one of the pinned review models. */
model: Schema.NonEmptyString,
+ /** Custom endpoint only: whether the model reads images. Absent means it does. */
+ images: Schema.optionalKey(Schema.Boolean),
+ /** Custom endpoint only: the model's context window in tokens. */
+ contextWindow: Schema.optionalKey(
+ Schema.Int.check(
+ Schema.isBetween({
+ minimum: customContextWindow.minimum,
+ maximum: customContextWindow.maximum,
+ }),
+ ),
+ ),
});
/** Modal credentials cross only the trusted startup pipe, never renderer RPC or packages. */
diff --git a/src/lib/review/client.ts b/src/lib/review/client.ts
index 3d91a2a1..0e8a8ad6 100644
--- a/src/lib/review/client.ts
+++ b/src/lib/review/client.ts
@@ -13,7 +13,11 @@ import {
ReviewStorageError,
type SheetId,
} from "#lib/review/contracts.ts";
-import { ReviewDesktopRpc } from "#lib/review/shell.ts";
+import {
+ type CustomEndpointSettings,
+ type OpenCodeGoSettings,
+ ReviewDesktopRpc,
+} from "#lib/review/shell.ts";
import type {
PacketFindingVerdict,
PacketReview,
@@ -383,6 +387,30 @@ export function createReviewClient() {
"The review package could not be restored.",
),
+ saveCustomEndpoint: (settings: typeof CustomEndpointSettings.Type) =>
+ run(
+ Effect.flatMap(ReviewDesktopApi, (client) => client.SaveCustomEndpoint(settings)),
+ "The custom endpoint could not be saved.",
+ ),
+
+ removeCustomEndpoint: () =>
+ run(
+ Effect.flatMap(ReviewDesktopApi, (client) => client.RemoveCustomEndpoint({})),
+ "The custom endpoint could not be removed.",
+ ),
+
+ saveOpenCodeGo: (settings: typeof OpenCodeGoSettings.Type) =>
+ run(
+ Effect.flatMap(ReviewDesktopApi, (client) => client.SaveOpenCodeGo(settings)),
+ "The OpenCode Go key could not be saved.",
+ ),
+
+ removeOpenCodeGo: () =>
+ run(
+ Effect.flatMap(ReviewDesktopApi, (client) => client.RemoveOpenCodeGo({})),
+ "The OpenCode Go key could not be removed.",
+ ),
+
/** Load a PNG artifact through bounded chunks and return an object URL. */
loadArtifactBlobUrl: async (
projectId: typeof ProjectId.Type,
diff --git a/src/lib/review/components/CustomEndpointSettings.svelte b/src/lib/review/components/CustomEndpointSettings.svelte
new file mode 100644
index 00000000..42a6a4e4
--- /dev/null
+++ b/src/lib/review/components/CustomEndpointSettings.svelte
@@ -0,0 +1,204 @@
+
+
+
+
+ Run drawing reviews on another OpenAI-compatible chat completions endpoint, such as a vLLM or
+ Ollama server. For OpenCode Go, use its own section above. The model must support tool calling
+ and a context of at least 32,768 tokens; review instructions alone use about 15,000. SAM keeps
+ using the Meta connection, and reviews on this endpoint run on this computer only.
+
+
+ {#if disabled}
+ Finish or pause the running review to change the endpoint; saving restarts MOKE.
+
+ OpenCode Go {connected ? "Connected" : "Not connected"}
+
+
+ Use your OpenCode Go subscription for drawing reviews. Its models appear in the model menu.
+ Create a key on the OpenCode Console harnesses page.
+
+
+ In Console Settings › Privacy, Muse Spark 1.3 Contributor needs “Allow paid endpoints that train
+ on request data”: Meta may train on those reviews’ drawings and text.
+
+
+ {#if disabled}
+ Finish or pause the running review to change the key; saving restarts MOKE.
+
{/if}
+
{message}
+
+
+
diff --git a/src/lib/review/components/ReviewWorkbench.svelte b/src/lib/review/components/ReviewWorkbench.svelte
index ee812d10..8c68c70a 100644
--- a/src/lib/review/components/ReviewWorkbench.svelte
+++ b/src/lib/review/components/ReviewWorkbench.svelte
@@ -38,6 +38,8 @@
import FindingInspector from "./FindingInspector.svelte";
import FindingDecision from "./FindingDecision.svelte";
import FirmChecklistSettings from "./FirmChecklistSettings.svelte";
+ import CustomEndpointSettings from "./CustomEndpointSettings.svelte";
+ import OpenCodeGoSettings from "./OpenCodeGoSettings.svelte";
import PacketReviewPanel from "./PacketReviewPanel.svelte";
import { ReviewDiscipline } from "#lib/review/disciplines.ts";
import { SheetId } from "#lib/review/contracts.ts";
@@ -69,9 +71,13 @@
ReviewModelId,
ReviewModelOption,
reviewModels,
- reviewProviderRoutes,
+ runsInCloud,
trainsOnDrawings,
} from "#lib/review/models.ts";
+ import type {
+ CustomEndpointSettings as CustomEndpointSettingsInput,
+ OpenCodeGoSettings as OpenCodeGoSettingsInput,
+ } from "#lib/review/shell.ts";
import {
findingSubtitle,
formatOutcome,
@@ -163,6 +169,17 @@
let firmChecklistLoaded = $state(false);
let firmChecklistMessage = $state("");
+ // The reviewer's model for Initial Review and new conversations, kept in this window's storage.
+ const preferredModelKey = "moke.preferredReviewModel";
+
+ let preferredModelChoice = $state(
+ Option.getOrUndefined(
+ Schema.decodeUnknownOption(ReviewModelId)(
+ globalThis.localStorage?.getItem(preferredModelKey),
+ ),
+ ),
+ );
+
let steeringCommand: {
commandId: ReturnType;
reviewId: string;
@@ -368,7 +385,7 @@
).map((model) => ({
value: model.id,
label: model.label,
- description: `${reviewProviderRoutes[model.provider].label}${model.available ? "" : " · add a connection in settings"}`,
+ description: `${providerName(model)}${model.available ? "" : " · add a connection in settings"}`,
disabled: !model.available,
})),
);
@@ -381,6 +398,36 @@
selectedModel = first;
});
+ // The connected custom endpoint without its key.
+ const customEndpoint = $derived(
+ setup?.models?.find((model) => model.provider === "openai-compatible" && model.available)
+ ?.endpoint,
+ );
+
+ const openCodeGoConnected = $derived(
+ setup?.models?.some((model) => model.provider === "opencode-go" && model.available) === true,
+ );
+
+ const modelAvailable = (id: typeof ReviewModelId.Type) =>
+ modelOptions.some((model) => model.value === id && !model.disabled);
+
+ // Until the reviewer chooses, Initial Review's default applies; a custom endpoint spares Meta credits.
+ const preferredModel = $derived.by((): typeof ReviewModelId.Type => {
+ if (preferredModelChoice !== undefined && modelAvailable(preferredModelChoice))
+ return preferredModelChoice;
+
+ const fallback = initialReviewModelFor((id) =>
+ modelOptions.some((model) => model.value === id && !model.disabled),
+ );
+
+ return !modelAvailable(fallback) && modelAvailable("openai-compatible")
+ ? "openai-compatible"
+ : fallback;
+ });
+
+ const providerOf = (id: typeof ReviewModelId.Type) =>
+ reviewModels.find((model) => model.id === id)?.provider ?? "meta";
+
const selectedModelAvailable = $derived(
modelOptions.some((model) => model.value === selectedModel && !model.disabled),
);
@@ -393,11 +440,8 @@
(executionStatus.unresolvedAttempts > 0 && !executionStatus.uncertaintyAcknowledged))),
);
- const initialReviewModel = $derived(
- initialReviewModelFor((id) =>
- modelOptions.some((model) => model.value === id && !model.disabled),
- ),
- );
+ // Initial Review keeps its fixed request and runs on the reviewer's chosen model.
+ const initialReviewModel = $derived(preferredModel);
// Shown until a revised set arrives; a first set made of several PDFs keeps it.
const initialReviewVisible = $derived(
@@ -415,6 +459,9 @@
if (!cloudSetup?.configured) return { location: "local", label: "on this computer" } as const;
+ if (!runsInCloud(providerOf(initialReviewModel)))
+ return local("this model's key stays on this computer");
+
if (cloudSetup.workspaceEstimate === undefined)
return local("the cloud size check is unavailable");
@@ -839,6 +886,59 @@
}
}
+ function providerName(model: Pick) {
+ if (model.provider === "meta") return "Meta";
+
+ if (model.provider === "baseten") return "Baseten";
+
+ if (model.provider === "opencode-go") return "OpenCode Go";
+
+ return model.endpoint === undefined
+ ? "OpenAI-compatible endpoint"
+ : `Custom · ${new URL(model.endpoint.baseUrl).host}`;
+ }
+
+ /** Electron tests the endpoint and asks before saving; a saved endpoint restarts the app. */
+ async function saveCustomEndpoint(settings: typeof CustomEndpointSettingsInput.Type) {
+ const result = await client.saveCustomEndpoint(settings);
+
+ if (!result.ok) return result.error.message;
+
+ return result.value ? "Saved. MOKE is restarting to connect the endpoint." : "Not saved.";
+ }
+
+ async function removeCustomEndpoint() {
+ const result = await client.removeCustomEndpoint();
+
+ if (!result.ok) return result.error.message;
+
+ return result.value ? "Removed. MOKE is restarting." : "The endpoint is still connected.";
+ }
+
+ async function saveOpenCodeGo(settings: typeof OpenCodeGoSettingsInput.Type) {
+ const result = await client.saveOpenCodeGo(settings);
+
+ if (!result.ok) return result.error.message;
+
+ return result.value ? "Saved. MOKE is restarting to connect OpenCode Go." : "Not saved.";
+ }
+
+ async function removeOpenCodeGo() {
+ const result = await client.removeOpenCodeGo();
+
+ if (!result.ok) return result.error.message;
+
+ return result.value ? "Removed. MOKE is restarting." : "OpenCode Go is still connected.";
+ }
+
+ function choosePreferredModel(value: string) {
+ const chosen = Schema.decodeUnknownOption(ReviewModelId)(value);
+
+ if (Option.isNone(chosen)) return;
+ preferredModelChoice = chosen.value;
+ globalThis.localStorage?.setItem(preferredModelKey, chosen.value);
+ }
+
function openPacketFocus(focus: typeof PacketFindingFocus.Type) {
return openPacketEvidence(focus.artifactId, {
sheetId: focus.sheetId,
@@ -1656,6 +1756,7 @@
selectedModel =
saved?.model ??
previousReview?.model ??
+ (modelAvailable(preferredModel) ? preferredModel : undefined) ??
offeredReviewModels(setup?.models ?? []).find((model) => model.available)?.id ??
selectedModel;
modelChosen = saved?.model !== undefined;
@@ -1952,7 +2053,10 @@
if (result.ok) {
setup = result.value;
- const configuredModel = Schema.decodeUnknownOption(ReviewModelId)(result.value.model);
+
+ const configuredModel = modelAvailable(preferredModel)
+ ? Option.some(preferredModel)
+ : Schema.decodeUnknownOption(ReviewModelId)(result.value.model);
// A conversation that already has a review keeps that review's model.
if (
@@ -2270,17 +2374,35 @@
: "Not connected"}