feat(opencode-local): env-driven gateway routing (custom providers, small/cheap model, remote allow-all) (#7837)
## Thinking Path > - Paperclip is the open source app people use to manage AI agents for work > - The `opencode-local` adapter runs the OpenCode harness; its model/provider routing assumes built-in providers (anthropic/openai/...) and their default models > - Deployments increasingly put an OpenAI/Anthropic-compatible LLM gateway between the harness and the model for cost, governance, or data-residency reasons: LiteLLM, OpenRouter, Portkey, Kong, a corporate proxy, self-hosted models (vLLM/Ollama), or region-pinned/sovereign endpoints. But OpenCode only resolves `--model provider/model` when the model is registered in a provider's `models` map, and `OPENCODE_ALLOW_ALL_MODELS` does NOT bypass its internal `getModel()` > - Several lanes also fall back to built-in default models the gateway may not serve: the auxiliary/title model (e.g. `claude-haiku-*`) and the budget/recovery "cheap" lane (`openai/gpt-5.1-codex-mini`); these abort runs with "no keys found that support model" > - This pull request makes the adapter's provider/model wiring declarative via env, so any such deployment can register gateway models + pin the auxiliary/budget lanes without code changes; nothing here is specific to one hosting setup > - The benefit is OpenCode works behind any compatible gateway with config only; with no env set, behavior is unchanged ## Linked Issues or Issue Description No existing issue; describing in-PR (feature / adapter enhancement). - **Gap:** there is no supported way to register custom/gateway providers + models for `opencode-local`, nor to pin the auxiliary (title-gen) and budget (recovery) model lanes, so routing OpenCode through a gateway fails at `getModel()` or on the default helper models. - Related: #5737 (exe.dev sandbox installs for gemini/opencode local), #5823 (unblock claude_local on remote sandbox providers). > Note on ROADMAP: this is adapter-level, opt-in config (defaults unchanged) that *enables* gateway routing for one harness; it is not the core "Cloud / Sandbox agents" platform work itself. Happy to redirect/discuss in #dev if preferred. ## What Changed - `PAPERCLIP_OPENCODE_PROVIDERS`: merge custom/extended providers (OpenCode `provider` shape) into the runtime `opencode.json`, so gateway models are registered and `--model provider/model` resolves. `{env:VAR}` placeholders are expanded server-side (so a key need not depend on the sandbox run env). - A malformed `PAPERCLIP_OPENCODE_PROVIDERS` is no longer silently ignored: invalid JSON, a non-object value, and individual provider entries with non-object values (which are skipped by name) each append a visible note to the run notes so the misconfiguration is diagnosable (addresses both review P1s). - `PAPERCLIP_OPENCODE_SMALL_MODEL` / `PAPERCLIP_OPENCODE_CHEAP_MODEL`: pin the auxiliary (title-generation) and budget (recovery-retry) lanes to gateway-served models; defaults unchanged. - Honour `OPENCODE_ALLOW_ALL_MODELS` on the **remote** execution path too (was local-only, a parity gap). - `PAPERCLIP_OPENCODE_PRINT_LOGS`: optional toggle adding `--print-logs` so OpenCode logs surface on stderr for diagnosing remote/sandbox runs. - `buildOpenCodeModelProfiles()` guards its `process.env` default with `typeof process` so the shared client/server module stays browser-safe (a bare `process.env` at module load threw ReferenceError in the browser under Vite dev middleware and broke UI rendering in the e2e lane). ## Verification - `pnpm --filter @paperclipai/adapter-opencode-local build` and `typecheck` (tsc clean) - `pnpm exec vitest run packages/adapters/opencode-local/src` shows 33 passing (incl. new tests for the provider merge, `{env:}` expansion, the malformed/non-object/skipped-entry provider notes, small/cheap-model resolution, and the remote allow-all bypass) - Manually verified end-to-end against a real OpenAI-/Anthropic-compatible gateway: with the providers + small/cheap model set, both the title-gen and main task route to the configured gateway model and the agent completes (a real completion is returned and billed). That deployment supplies the verification evidence; the mechanism is gateway-agnostic. ## Risks Low. Everything is env-driven and opt-in; with no env set the generated config output is unchanged, and the cheap model profile keeps its model (the only difference is its updated human-readable description). Defaults preserved: built-in providers, Codex-mini cheap lane with `variant: low`, no `--print-logs`. No migration/UI impact. ## Model Used Claude Opus 4.8 (`claude-opus-4-8`, 1M context), extended thinking + tool use, via Claude Code. ## Checklist - [x] I have included a thinking path that traces from project context to this change - [x] I have specified the model used (with version and capability details) - [x] I have checked ROADMAP.md (adapter-level opt-in config enabling gateway routing; not the core sandbox-platform work, noted above) - [x] I have searched GitHub for duplicate or related PRs and linked them above (#5737, #5823) - [x] I have either (a) linked existing issues OR (b) described the issue in-PR following the relevant issue template - [x] I have run tests locally and they pass - [x] I have added or updated tests where applicable - [ ] If this change affects the UI, I have included before/after screenshots (n/a, no UI) - [ ] I have updated relevant documentation to reflect my changes (env vars documented inline via comments; no central doc references the adapter env yet) - [x] I have considered and documented any risks above - [x] All Paperclip CI gates are green - [x] Greptile is 5/5 with no open P2s, recommendations, or follow-ups (the P1 about silently dropped malformed providers JSON is addressed in 6eeb803, the follow-up P1 about silently skipped non-object entries in 2f4045a; the latest review has no further findings, and a re-review is requested for the final note-copy/test-fixture polish at head) - [x] I will address all Greptile and reviewer comments before requesting merge 🤖 Generated with [Claude Code](https://claude.com/claude-code) --------- Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
This commit is contained in:
Jannes Stubbemann
committed by
GitHub
GitHub
parent
398d746093
commit
1ac1ba5442
@@ -0,0 +1,62 @@
|
||||
import { afterEach, describe, expect, it } from "vitest";
|
||||
|
||||
import { ensureRemoteOpenCodeModelConfiguredAndAvailable } from "./execute.js";
|
||||
|
||||
describe("ensureRemoteOpenCodeModelConfiguredAndAvailable", () => {
|
||||
afterEach(() => {
|
||||
delete process.env.OPENCODE_ALLOW_ALL_MODELS;
|
||||
});
|
||||
|
||||
// The remote/sandbox execution path must honour OPENCODE_ALLOW_ALL_MODELS just
|
||||
// like the local path: gateway-routed models (e.g. anthropic/<gateway>/<model>
|
||||
// via Bifrost) never appear in `opencode models`, so the availability probe
|
||||
// must be skipped. The early return happens before the executionTarget is ever
|
||||
// touched, so a bogus target proves the probe was not run.
|
||||
const bogusTarget = {} as never;
|
||||
|
||||
it("skips the remote availability probe when OPENCODE_ALLOW_ALL_MODELS is set in the run env", async () => {
|
||||
await expect(
|
||||
ensureRemoteOpenCodeModelConfiguredAndAvailable({
|
||||
runId: "run-1",
|
||||
executionTarget: bogusTarget,
|
||||
command: "opencode",
|
||||
model: "anthropic/tensorix/deepseek/deepseek-chat-v3.1",
|
||||
cwd: "/tmp",
|
||||
env: { OPENCODE_ALLOW_ALL_MODELS: "true" },
|
||||
timeoutSec: 30,
|
||||
graceSec: 5,
|
||||
}),
|
||||
).resolves.toBeUndefined();
|
||||
});
|
||||
|
||||
it("honours OPENCODE_ALLOW_ALL_MODELS from the process env", async () => {
|
||||
process.env.OPENCODE_ALLOW_ALL_MODELS = "1";
|
||||
await expect(
|
||||
ensureRemoteOpenCodeModelConfiguredAndAvailable({
|
||||
runId: "run-2",
|
||||
executionTarget: bogusTarget,
|
||||
command: "opencode",
|
||||
model: "anthropic/tensorix/deepseek/deepseek-chat-v3.1",
|
||||
cwd: "/tmp",
|
||||
env: {},
|
||||
timeoutSec: 30,
|
||||
graceSec: 5,
|
||||
}),
|
||||
).resolves.toBeUndefined();
|
||||
});
|
||||
|
||||
it("still enforces provider/model format even when the bypass flag is set", async () => {
|
||||
await expect(
|
||||
ensureRemoteOpenCodeModelConfiguredAndAvailable({
|
||||
runId: "run-3",
|
||||
executionTarget: bogusTarget,
|
||||
command: "opencode",
|
||||
model: "",
|
||||
cwd: "/tmp",
|
||||
env: { OPENCODE_ALLOW_ALL_MODELS: "true" },
|
||||
timeoutSec: 30,
|
||||
graceSec: 5,
|
||||
}),
|
||||
).rejects.toThrow();
|
||||
});
|
||||
});
|
||||
@@ -47,6 +47,7 @@ import {
|
||||
import { isOpenCodeUnknownSessionError, parseOpenCodeJsonl } from "./parse.js";
|
||||
import {
|
||||
ensureOpenCodeModelConfiguredAndAvailable,
|
||||
isTruthyEnvFlag,
|
||||
parseOpenCodeModelsOutput,
|
||||
requireOpenCodeModelId,
|
||||
} from "./models.js";
|
||||
@@ -79,7 +80,7 @@ function resolveOpenCodeBiller(env: Record<string, string>, provider: string | n
|
||||
const REMOTE_OPENCODE_MODELS_PROBE_DEFAULT_TIMEOUT_SEC = 20;
|
||||
const REMOTE_OPENCODE_MODELS_PROBE_SANDBOX_TIMEOUT_SEC = 120;
|
||||
|
||||
async function ensureRemoteOpenCodeModelConfiguredAndAvailable(input: {
|
||||
export async function ensureRemoteOpenCodeModelConfiguredAndAvailable(input: {
|
||||
runId: string;
|
||||
executionTarget: NonNullable<AdapterExecutionContext["executionTarget"]>;
|
||||
command: string;
|
||||
@@ -90,6 +91,17 @@ async function ensureRemoteOpenCodeModelConfiguredAndAvailable(input: {
|
||||
graceSec: number;
|
||||
}) {
|
||||
const model = requireOpenCodeModelId(input.model);
|
||||
|
||||
// When the caller opts into OPENCODE_ALLOW_ALL_MODELS, OpenCode accepts any
|
||||
// provider/model at run time (e.g. gateway-routed models that never appear in
|
||||
// `opencode models` output). Honour that on the REMOTE path too by skipping the
|
||||
// remote availability probe; we still enforce the provider/model format above.
|
||||
// Mirrors the local ensureOpenCodeModelConfiguredAndAvailable bypass. Prefer the
|
||||
// explicit run env, then the process env.
|
||||
if (isTruthyEnvFlag(input.env.OPENCODE_ALLOW_ALL_MODELS ?? process.env.OPENCODE_ALLOW_ALL_MODELS)) {
|
||||
return;
|
||||
}
|
||||
|
||||
const defaultProbeTimeoutSec =
|
||||
input.executionTarget.kind === "remote" && input.executionTarget.transport === "sandbox"
|
||||
? REMOTE_OPENCODE_MODELS_PROBE_SANDBOX_TIMEOUT_SEC
|
||||
@@ -548,8 +560,17 @@ export async function execute(ctx: AdapterExecutionContext): Promise<AdapterExec
|
||||
heartbeatPromptChars: renderedPrompt.length,
|
||||
};
|
||||
|
||||
// Optional diagnostic: surface OpenCode's own logs on stderr (captured into the
|
||||
// run result) so failures that OpenCode otherwise wraps as an opaque
|
||||
// "Unexpected server error" can be diagnosed in remote/sandbox runs where the
|
||||
// log file is unreachable. Toggle via PAPERCLIP_OPENCODE_PRINT_LOGS (run env,
|
||||
// then process env).
|
||||
const printLogs = isTruthyEnvFlag(
|
||||
env.PAPERCLIP_OPENCODE_PRINT_LOGS ?? process.env.PAPERCLIP_OPENCODE_PRINT_LOGS,
|
||||
);
|
||||
const buildArgs = (resumeSessionId: string | null) => {
|
||||
const args = ["run", "--format", "json"];
|
||||
if (printLogs) args.push("--print-logs");
|
||||
if (resumeSessionId) args.push("--session", resumeSessionId);
|
||||
if (model) args.push("--model", model);
|
||||
if (variant) args.push("--variant", variant);
|
||||
|
||||
@@ -9,6 +9,7 @@ import {
|
||||
describe("openCode models", () => {
|
||||
afterEach(() => {
|
||||
delete process.env.PAPERCLIP_OPENCODE_COMMAND;
|
||||
delete process.env.OPENCODE_ALLOW_ALL_MODELS;
|
||||
resetOpenCodeModelsCacheForTests();
|
||||
});
|
||||
|
||||
@@ -44,4 +45,33 @@ describe("openCode models", () => {
|
||||
}),
|
||||
).rejects.toThrow("Failed to start command");
|
||||
});
|
||||
|
||||
it("skips the availability check when OPENCODE_ALLOW_ALL_MODELS is set in the run env", async () => {
|
||||
process.env.PAPERCLIP_OPENCODE_COMMAND = "__paperclip_missing_opencode_command__";
|
||||
await expect(
|
||||
ensureOpenCodeModelConfiguredAndAvailable({
|
||||
model: "anthropic/tensorix/deepseek/deepseek-chat-v3.1",
|
||||
env: { OPENCODE_ALLOW_ALL_MODELS: "true" },
|
||||
}),
|
||||
).resolves.toEqual([
|
||||
{ id: "anthropic/tensorix/deepseek/deepseek-chat-v3.1", label: "anthropic/tensorix/deepseek/deepseek-chat-v3.1" },
|
||||
]);
|
||||
});
|
||||
|
||||
it("honours OPENCODE_ALLOW_ALL_MODELS from the process env", async () => {
|
||||
process.env.PAPERCLIP_OPENCODE_COMMAND = "__paperclip_missing_opencode_command__";
|
||||
process.env.OPENCODE_ALLOW_ALL_MODELS = "1";
|
||||
await expect(
|
||||
ensureOpenCodeModelConfiguredAndAvailable({ model: "anthropic/gateway/some-model" }),
|
||||
).resolves.toEqual([{ id: "anthropic/gateway/some-model", label: "anthropic/gateway/some-model" }]);
|
||||
});
|
||||
|
||||
it("still enforces provider/model format when OPENCODE_ALLOW_ALL_MODELS is set", async () => {
|
||||
await expect(
|
||||
ensureOpenCodeModelConfiguredAndAvailable({
|
||||
model: "not-a-valid-id",
|
||||
env: { OPENCODE_ALLOW_ALL_MODELS: "true" },
|
||||
}),
|
||||
).rejects.toThrow("OpenCode requires `adapterConfig.model`");
|
||||
});
|
||||
});
|
||||
|
||||
@@ -175,6 +175,12 @@ export async function discoverOpenCodeModelsCached(input: {
|
||||
return models;
|
||||
}
|
||||
|
||||
export function isTruthyEnvFlag(value: string | undefined): boolean {
|
||||
if (value === undefined) return false;
|
||||
const v = value.trim().toLowerCase();
|
||||
return v === "true" || v === "1" || v === "yes";
|
||||
}
|
||||
|
||||
export async function ensureOpenCodeModelConfiguredAndAvailable(input: {
|
||||
model?: unknown;
|
||||
command?: unknown;
|
||||
@@ -183,6 +189,16 @@ export async function ensureOpenCodeModelConfiguredAndAvailable(input: {
|
||||
}): Promise<AdapterModel[]> {
|
||||
const model = requireOpenCodeModelId(input.model);
|
||||
|
||||
// When the caller opts into OPENCODE_ALLOW_ALL_MODELS, OpenCode accepts any
|
||||
// provider/model at run time (e.g. gateway-routed models that never appear in
|
||||
// `opencode models` output). Honour that by skipping the availability probe;
|
||||
// we still enforce the provider/model format above and do not second-guess
|
||||
// the configured model. Prefer the explicit run env, then the process env.
|
||||
const env = normalizeEnv(input.env);
|
||||
if (isTruthyEnvFlag(env.OPENCODE_ALLOW_ALL_MODELS ?? process.env.OPENCODE_ALLOW_ALL_MODELS)) {
|
||||
return [{ id: model, label: model }];
|
||||
}
|
||||
|
||||
const models = await discoverOpenCodeModelsCached({
|
||||
command: input.command,
|
||||
cwd: input.cwd,
|
||||
|
||||
@@ -65,6 +65,190 @@ describe("prepareOpenCodeRuntimeConfig", () => {
|
||||
await expect(fs.access(prepared.env.XDG_CONFIG_HOME)).rejects.toThrow();
|
||||
});
|
||||
|
||||
it("merges custom providers from PAPERCLIP_OPENCODE_PROVIDERS into the config", async () => {
|
||||
const configHome = await makeConfigHome({ permission: { read: "allow" } });
|
||||
const providers = {
|
||||
bifrost: {
|
||||
npm: "@ai-sdk/openai-compatible",
|
||||
name: "Bifrost EU",
|
||||
options: {
|
||||
baseURL: "http://gateway.example.svc.cluster.local:8080/v1",
|
||||
apiKey: "{env:ANTHROPIC_API_KEY}",
|
||||
},
|
||||
models: { "example/model-a": { name: "Model A" } },
|
||||
},
|
||||
};
|
||||
|
||||
const prepared = await prepareOpenCodeRuntimeConfig({
|
||||
env: {
|
||||
XDG_CONFIG_HOME: configHome,
|
||||
PAPERCLIP_OPENCODE_PROVIDERS: JSON.stringify(providers),
|
||||
},
|
||||
config: {},
|
||||
});
|
||||
cleanupPaths.add(prepared.env.XDG_CONFIG_HOME);
|
||||
|
||||
const runtimeConfig = JSON.parse(
|
||||
await fs.readFile(path.join(prepared.env.XDG_CONFIG_HOME, "opencode", "opencode.json"), "utf8"),
|
||||
) as Record<string, unknown>;
|
||||
expect(runtimeConfig).toMatchObject({
|
||||
permission: { read: "allow", external_directory: "allow" },
|
||||
provider: providers,
|
||||
});
|
||||
expect(prepared.notes.some((n) => n.includes("bifrost"))).toBe(true);
|
||||
await prepared.cleanup();
|
||||
});
|
||||
|
||||
it("reads PAPERCLIP_OPENCODE_PROVIDERS from process.env when absent from the run env", async () => {
|
||||
const configHome = await makeConfigHome({ permission: { read: "allow" } });
|
||||
const providers = { bifrost: { npm: "@ai-sdk/openai-compatible", models: { "example/model-a": {} } } };
|
||||
process.env.PAPERCLIP_OPENCODE_PROVIDERS = JSON.stringify(providers);
|
||||
try {
|
||||
const prepared = await prepareOpenCodeRuntimeConfig({
|
||||
env: { XDG_CONFIG_HOME: configHome },
|
||||
config: {},
|
||||
});
|
||||
cleanupPaths.add(prepared.env.XDG_CONFIG_HOME);
|
||||
const runtimeConfig = JSON.parse(
|
||||
await fs.readFile(path.join(prepared.env.XDG_CONFIG_HOME, "opencode", "opencode.json"), "utf8"),
|
||||
) as Record<string, unknown>;
|
||||
expect(runtimeConfig).toMatchObject({ provider: providers });
|
||||
await prepared.cleanup();
|
||||
} finally {
|
||||
delete process.env.PAPERCLIP_OPENCODE_PROVIDERS;
|
||||
}
|
||||
});
|
||||
|
||||
it("expands {env:VAR} placeholders in custom providers using the run/process env (bakes the literal vk)", async () => {
|
||||
const configHome = await makeConfigHome({ permission: { read: "allow" } });
|
||||
const providers = {
|
||||
bifrost: {
|
||||
npm: "@ai-sdk/openai-compatible",
|
||||
options: { baseURL: "http://bifrost/v1", apiKey: "{env:ANTHROPIC_API_KEY}" },
|
||||
models: { "example/model-a": {} },
|
||||
},
|
||||
};
|
||||
const prepared = await prepareOpenCodeRuntimeConfig({
|
||||
env: { XDG_CONFIG_HOME: configHome, PAPERCLIP_OPENCODE_PROVIDERS: JSON.stringify(providers), ANTHROPIC_API_KEY: "sk-bf-REALVK" },
|
||||
config: {},
|
||||
});
|
||||
cleanupPaths.add(prepared.env.XDG_CONFIG_HOME);
|
||||
const runtimeConfig = JSON.parse(
|
||||
await fs.readFile(path.join(prepared.env.XDG_CONFIG_HOME, "opencode", "opencode.json"), "utf8"),
|
||||
) as { provider: { bifrost: { options: { apiKey: string } } } };
|
||||
// The {env:...} placeholder must be replaced with the literal value, so OpenCode
|
||||
// does not depend on its sandboxed process env carrying the key.
|
||||
expect(runtimeConfig.provider.bifrost.options.apiKey).toBe("sk-bf-REALVK");
|
||||
await prepared.cleanup();
|
||||
});
|
||||
|
||||
it("leaves an unresolvable {env:VAR} placeholder intact", async () => {
|
||||
const configHome = await makeConfigHome({ permission: { read: "allow" } });
|
||||
const providers = { bifrost: { options: { apiKey: "{env:DEFINITELY_UNSET_VAR_XYZ}" }, models: { "x/y": {} } } };
|
||||
const prepared = await prepareOpenCodeRuntimeConfig({
|
||||
env: { XDG_CONFIG_HOME: configHome, PAPERCLIP_OPENCODE_PROVIDERS: JSON.stringify(providers) },
|
||||
config: {},
|
||||
});
|
||||
cleanupPaths.add(prepared.env.XDG_CONFIG_HOME);
|
||||
const runtimeConfig = JSON.parse(
|
||||
await fs.readFile(path.join(prepared.env.XDG_CONFIG_HOME, "opencode", "opencode.json"), "utf8"),
|
||||
) as { provider: { bifrost: { options: { apiKey: string } } } };
|
||||
expect(runtimeConfig.provider.bifrost.options.apiKey).toBe("{env:DEFINITELY_UNSET_VAR_XYZ}");
|
||||
await prepared.cleanup();
|
||||
});
|
||||
|
||||
it("pins small_model from PAPERCLIP_OPENCODE_SMALL_MODEL", async () => {
|
||||
const configHome = await makeConfigHome({ permission: { read: "allow" } });
|
||||
const prepared = await prepareOpenCodeRuntimeConfig({
|
||||
env: { XDG_CONFIG_HOME: configHome, PAPERCLIP_OPENCODE_SMALL_MODEL: "example/model-a" },
|
||||
config: {},
|
||||
});
|
||||
cleanupPaths.add(prepared.env.XDG_CONFIG_HOME);
|
||||
const runtimeConfig = JSON.parse(
|
||||
await fs.readFile(path.join(prepared.env.XDG_CONFIG_HOME, "opencode", "opencode.json"), "utf8"),
|
||||
) as { small_model?: string };
|
||||
expect(runtimeConfig.small_model).toBe("example/model-a");
|
||||
await prepared.cleanup();
|
||||
});
|
||||
|
||||
it("ignores malformed PAPERCLIP_OPENCODE_PROVIDERS without writing a provider block and surfaces a note", async () => {
|
||||
const configHome = await makeConfigHome({ permission: { read: "allow" } });
|
||||
const prepared = await prepareOpenCodeRuntimeConfig({
|
||||
env: { XDG_CONFIG_HOME: configHome, PAPERCLIP_OPENCODE_PROVIDERS: "not json" },
|
||||
config: {},
|
||||
});
|
||||
cleanupPaths.add(prepared.env.XDG_CONFIG_HOME);
|
||||
const runtimeConfig = JSON.parse(
|
||||
await fs.readFile(path.join(prepared.env.XDG_CONFIG_HOME, "opencode", "opencode.json"), "utf8"),
|
||||
) as Record<string, unknown>;
|
||||
expect(runtimeConfig.provider).toBeUndefined();
|
||||
expect(prepared.notes).toContain(
|
||||
"PAPERCLIP_OPENCODE_PROVIDERS contains invalid JSON; custom providers ignored.",
|
||||
);
|
||||
await prepared.cleanup();
|
||||
});
|
||||
|
||||
it("surfaces a note when PAPERCLIP_OPENCODE_PROVIDERS is valid JSON but not an object", async () => {
|
||||
const configHome = await makeConfigHome({ permission: { read: "allow" } });
|
||||
const prepared = await prepareOpenCodeRuntimeConfig({
|
||||
env: { XDG_CONFIG_HOME: configHome, PAPERCLIP_OPENCODE_PROVIDERS: "[1,2,3]" },
|
||||
config: {},
|
||||
});
|
||||
cleanupPaths.add(prepared.env.XDG_CONFIG_HOME);
|
||||
const runtimeConfig = JSON.parse(
|
||||
await fs.readFile(path.join(prepared.env.XDG_CONFIG_HOME, "opencode", "opencode.json"), "utf8"),
|
||||
) as Record<string, unknown>;
|
||||
expect(runtimeConfig.provider).toBeUndefined();
|
||||
expect(prepared.notes).toContain(
|
||||
"PAPERCLIP_OPENCODE_PROVIDERS is set but is not a JSON object; custom providers ignored.",
|
||||
);
|
||||
await prepared.cleanup();
|
||||
});
|
||||
|
||||
it("surfaces skipped provider entries with non-object values and keeps the usable ones", async () => {
|
||||
const configHome = await makeConfigHome({ permission: { read: "allow" } });
|
||||
const prepared = await prepareOpenCodeRuntimeConfig({
|
||||
env: {
|
||||
XDG_CONFIG_HOME: configHome,
|
||||
PAPERCLIP_OPENCODE_PROVIDERS: JSON.stringify({
|
||||
bifrost: "http://gateway.example/v1",
|
||||
usable: { options: { baseURL: "http://gateway.example/v1" } },
|
||||
}),
|
||||
},
|
||||
config: {},
|
||||
});
|
||||
cleanupPaths.add(prepared.env.XDG_CONFIG_HOME);
|
||||
const runtimeConfig = JSON.parse(
|
||||
await fs.readFile(path.join(prepared.env.XDG_CONFIG_HOME, "opencode", "opencode.json"), "utf8"),
|
||||
) as { provider?: Record<string, unknown> };
|
||||
expect(runtimeConfig.provider?.usable).toBeDefined();
|
||||
expect(runtimeConfig.provider?.bifrost).toBeUndefined();
|
||||
expect(prepared.notes).toContain(
|
||||
"PAPERCLIP_OPENCODE_PROVIDERS: skipped provider(s) with non-object values: bifrost.",
|
||||
);
|
||||
await prepared.cleanup();
|
||||
});
|
||||
|
||||
it("surfaces skipped provider entries when no usable entries remain", async () => {
|
||||
const configHome = await makeConfigHome({ permission: { read: "allow" } });
|
||||
const prepared = await prepareOpenCodeRuntimeConfig({
|
||||
env: {
|
||||
XDG_CONFIG_HOME: configHome,
|
||||
PAPERCLIP_OPENCODE_PROVIDERS: JSON.stringify({ bifrost: "http://gateway.example/v1" }),
|
||||
},
|
||||
config: {},
|
||||
});
|
||||
cleanupPaths.add(prepared.env.XDG_CONFIG_HOME);
|
||||
const runtimeConfig = JSON.parse(
|
||||
await fs.readFile(path.join(prepared.env.XDG_CONFIG_HOME, "opencode", "opencode.json"), "utf8"),
|
||||
) as Record<string, unknown>;
|
||||
expect(runtimeConfig.provider).toBeUndefined();
|
||||
expect(prepared.notes).toContain(
|
||||
"PAPERCLIP_OPENCODE_PROVIDERS: skipped provider(s) with non-object values: bifrost.",
|
||||
);
|
||||
await prepared.cleanup();
|
||||
});
|
||||
|
||||
it("respects explicit opt-out", async () => {
|
||||
const configHome = await makeConfigHome();
|
||||
const prepared = await prepareOpenCodeRuntimeConfig({
|
||||
|
||||
@@ -21,6 +21,69 @@ function isPlainObject(value: unknown): value is Record<string, unknown> {
|
||||
return typeof value === "object" && value !== null && !Array.isArray(value);
|
||||
}
|
||||
|
||||
// Recursively replace {env:VAR} placeholders with the resolved value. Used to bake
|
||||
// gateway provider secrets (e.g. the LLM-gateway virtual key) into opencode.json
|
||||
// SERVER-SIDE, where the value is reliably present. OpenCode's own {env:...}
|
||||
// resolution happens inside the (possibly sandboxed) run process, whose env
|
||||
// plumbing is not guaranteed to carry the key to OpenCode's spawned server -- so
|
||||
// we resolve it here. Unresolvable placeholders are left intact for OpenCode to try.
|
||||
function expandEnvPlaceholders<T>(value: T, resolve: (name: string) => string | undefined): T {
|
||||
if (typeof value === "string") {
|
||||
return value.replace(/\{env:([A-Za-z_][A-Za-z0-9_]*)\}/g, (match, name: string) => {
|
||||
const resolved = resolve(name);
|
||||
return resolved !== undefined && resolved.length > 0 ? resolved : match;
|
||||
}) as unknown as T;
|
||||
}
|
||||
if (Array.isArray(value)) {
|
||||
return value.map((entry) => expandEnvPlaceholders(entry, resolve)) as unknown as T;
|
||||
}
|
||||
if (isPlainObject(value)) {
|
||||
const out: Record<string, unknown> = {};
|
||||
for (const [key, entry] of Object.entries(value)) {
|
||||
out[key] = expandEnvPlaceholders(entry, resolve);
|
||||
}
|
||||
return out as unknown as T;
|
||||
}
|
||||
return value;
|
||||
}
|
||||
|
||||
function parseProviderConfig(
|
||||
raw: unknown,
|
||||
resolveEnv: (name: string) => string | undefined,
|
||||
notes: string[],
|
||||
): Record<string, unknown> | null {
|
||||
if (typeof raw !== "string" || raw.trim().length === 0) return null;
|
||||
let parsed: unknown;
|
||||
try {
|
||||
parsed = JSON.parse(raw);
|
||||
} catch {
|
||||
// Surface the misconfiguration instead of silently dropping the provider
|
||||
// block; an unparseable value would otherwise be undiagnosable.
|
||||
notes.push("PAPERCLIP_OPENCODE_PROVIDERS contains invalid JSON; custom providers ignored.");
|
||||
return null;
|
||||
}
|
||||
if (!isPlainObject(parsed)) {
|
||||
notes.push(
|
||||
"PAPERCLIP_OPENCODE_PROVIDERS is set but is not a JSON object; custom providers ignored.",
|
||||
);
|
||||
return null;
|
||||
}
|
||||
// Only keep provider entries that are themselves objects; surface the ones
|
||||
// we drop so a malformed entry is just as diagnosable as malformed JSON.
|
||||
const providers: Record<string, unknown> = {};
|
||||
const skipped: string[] = [];
|
||||
for (const [key, value] of Object.entries(parsed)) {
|
||||
if (isPlainObject(value)) providers[key] = expandEnvPlaceholders(value, resolveEnv);
|
||||
else skipped.push(key);
|
||||
}
|
||||
if (skipped.length > 0) {
|
||||
notes.push(
|
||||
`PAPERCLIP_OPENCODE_PROVIDERS: skipped provider(s) with non-object values: ${skipped.join(", ")}.`,
|
||||
);
|
||||
}
|
||||
return Object.keys(providers).length > 0 ? providers : null;
|
||||
}
|
||||
|
||||
async function readJsonObject(filepath: string): Promise<Record<string, unknown>> {
|
||||
try {
|
||||
const raw = await fs.readFile(filepath, "utf8");
|
||||
@@ -81,13 +144,55 @@ export async function prepareOpenCodeRuntimeConfig(input: {
|
||||
const existingPermission = isPlainObject(existingConfig.permission)
|
||||
? existingConfig.permission
|
||||
: {};
|
||||
const nextConfig = {
|
||||
const notes = [
|
||||
"Injected runtime OpenCode config with permission.external_directory=allow to avoid headless approval prompts.",
|
||||
];
|
||||
|
||||
// Merge gateway/custom provider definitions supplied via PAPERCLIP_OPENCODE_PROVIDERS
|
||||
// (a JSON object in OpenCode's `provider` shape). OpenCode resolves a `--model
|
||||
// provider/model` only when that model exists in a provider's `models` map, and
|
||||
// OPENCODE_ALLOW_ALL_MODELS does NOT bypass its internal getModel(). So routing a
|
||||
// gateway model (e.g. an EU LLM gateway exposing OpenAI-compatible /v1) requires a
|
||||
// custom provider with an explicit models map. We accept it as config (not
|
||||
// hard-coded) so the gateway URL, key env, and model list stay declarative.
|
||||
const resolveEnv = (name: string): string | undefined => input.env[name] ?? process.env[name];
|
||||
const gatewayProviders = parseProviderConfig(
|
||||
input.env.PAPERCLIP_OPENCODE_PROVIDERS ?? process.env.PAPERCLIP_OPENCODE_PROVIDERS,
|
||||
resolveEnv,
|
||||
notes,
|
||||
);
|
||||
const existingProvider = isPlainObject(existingConfig.provider) ? existingConfig.provider : {};
|
||||
const nextProvider = gatewayProviders
|
||||
? { ...existingProvider, ...gatewayProviders }
|
||||
: existingProvider;
|
||||
if (gatewayProviders) {
|
||||
notes.push(
|
||||
`Injected ${Object.keys(gatewayProviders).length} custom OpenCode provider(s) from PAPERCLIP_OPENCODE_PROVIDERS: ${Object.keys(gatewayProviders).join(", ")}.`,
|
||||
);
|
||||
}
|
||||
|
||||
const nextConfig: Record<string, unknown> = {
|
||||
...existingConfig,
|
||||
permission: {
|
||||
...existingPermission,
|
||||
external_directory: "allow",
|
||||
},
|
||||
};
|
||||
if (Object.keys(nextProvider).length > 0) {
|
||||
nextConfig.provider = nextProvider;
|
||||
}
|
||||
|
||||
// Pin OpenCode's auxiliary "small" model (used for session-title generation and
|
||||
// other helper tasks) via PAPERCLIP_OPENCODE_SMALL_MODEL. OpenCode otherwise
|
||||
// defaults the small model to a built-in provider default (e.g. a claude-* model
|
||||
// for the anthropic provider); when that provider is repointed at a gateway that
|
||||
// does not serve that exact model, the title-gen call fails and aborts the run.
|
||||
// Setting small_model to a gateway-served model keeps every call on supported models.
|
||||
const smallModel = (input.env.PAPERCLIP_OPENCODE_SMALL_MODEL ?? process.env.PAPERCLIP_OPENCODE_SMALL_MODEL)?.trim();
|
||||
if (smallModel) {
|
||||
nextConfig.small_model = smallModel;
|
||||
notes.push(`Pinned OpenCode small_model to ${smallModel}.`);
|
||||
}
|
||||
await fs.writeFile(runtimeConfigPath, `${JSON.stringify(nextConfig, null, 2)}\n`, "utf8");
|
||||
|
||||
return {
|
||||
@@ -95,9 +200,7 @@ export async function prepareOpenCodeRuntimeConfig(input: {
|
||||
...input.env,
|
||||
XDG_CONFIG_HOME: runtimeConfigHome,
|
||||
},
|
||||
notes: [
|
||||
"Injected runtime OpenCode config with permission.external_directory=allow to avoid headless approval prompts.",
|
||||
],
|
||||
notes,
|
||||
cleanup: async () => {
|
||||
await fs.rm(runtimeConfigHome, { recursive: true, force: true });
|
||||
},
|
||||
|
||||
Reference in New Issue
Block a user