From dce4d47f60bcdeff06b133e1e652f2624ab99f7e Mon Sep 17 00:00:00 2001 From: Nicky Leach Date: Fri, 20 Nov 2026 08:47:18 -0800 Subject: [PATCH] feat(plugins): carry Grok, Copilot and OpenCode credentials to plugin Runners (#22359) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit ## Thinking Path > - Paperclip is the open source app people use to manage AI agents for work > - Environment-driver plugins can run `paperclip_runner` tasks on hosts that the plugin owns > - Core transfers the selected managed AI credential to the plugin as a typed task credential > - The credential contract has only two types: a Codex auth file and a direct Claude credential > - Grok, GitHub Copilot and OpenCode agents in a task-capable plugin environment therefore fail closed, although the Runner already reads their credentials from its environment > - This pull request adds one generic, allowlisted environment credential for these three harnesses and accepts the Runner's Grok launch settings > - The benefit is that plugin-provided Runner execution can run Grok, Copilot and OpenCode agents with their selected connection ## Linked Issues or Issue Description **Subsystem affected** Plugin environment tasks (`packages/plugins/sdk` task contract) and plugin-provided Runner execution in `server`. **Problem or motivation** An agent with the Grok, Copilot or OpenCode harness cannot run in a plugin environment that runs Runner tasks. Core stops at credential preparation with "Plugin Runner does not support the selected credential provider". A Grok agent fails before that point too. The Runner emits `grokEffort` and `grokDisableWebSearch` in its launch requirements (Core turns off Grok web search by default), but the strict `settings` schema of `environmentRunnerLaunchRequirementsSchema` rejects both keys. **Proposed solution** Core transfers the selected connection's credential variables for these harnesses through one typed `provider-env` credential. Each provider has a fixed allowlist of complete variable sets. The plugin sets the variables in the Runner process environment. **Alternatives considered** One credential type per harness (`grok-env`, `copilot-env`, `opencode-env`). This adds a type for each new harness. One generic type with an exported allowlist keeps the same strictness with less surface. **Roadmap alignment** The roadmap lists Grok and OpenCode as supported harnesses. This change lets plugin environments run them. It adds no new product concept. **Additional context** Grok subscription login (an auth file with refresh and writeback) is out of scope. It still fails closed, with an error that names the xAI API key as the supported option. ## What Changed - `packages/plugins/sdk`: Added the `provider-env` task credential: `{ type: "provider-env", provider: "grok" | "copilot" | "opencode", environment }`. The environment must contain exactly one complete variable set for the provider and no other variable. Values are non-empty, NUL-free and at most 65,536 characters, as for the other credential types. - `grok`: `XAI_API_KEY` - `copilot`: `COPILOT_GITHUB_TOKEN` - `opencode`: `OPENROUTER_API_KEY`, or `PAPERCLIP_AI_PROVIDER_URL` with `PAPERCLIP_AI_PROVIDER_KEY` - `packages/plugins/sdk`: Exported the allowlist as `ENVIRONMENT_TASK_PROVIDER_CREDENTIAL_KEY_SETS` and the `PluginEnvironmentTaskCredentialProvider` type. `claude-env` and `codex-auth-json` do not change. - `packages/plugins/sdk`: Added `grokEffort` (`minimal` to `xhigh`) and `grokDisableWebSearch` (boolean) to the launch requirements `settings`, with the types that the Runner uses. - `server`: `preparePluginRunnerCredentials` now transfers the selected connection's variables for the `grok`, `copilot` and `opencode` harnesses, with the same account identity semantics as the Claude branch. It refuses a Grok subscription, a Grok base URL override, and an incomplete or ambiguous set. The error never contains a credential value. - `server`: The submit check now matches a `provider-env` credential to the task harness. Before, it treated every non-Codex credential as Anthropic. - Drift test: `server/src/__tests__/plugin-runner-credential-names.test.ts` checks the SDK key sets against the Runner. The SDK list stays written by hand, and the Runner keeps its own lists of forwarded names. For `grok` and `copilot`, each name must be in `ACPX_CREDENTIAL_NAMES`, survive sidecar admission with the session binding that the Runner mints, and reach the agent process. The binding requirement must match the Rust sidecar's candidate agents. For `opencode`, each name must be in the OpenCode proxy environment set. Each name must also be in the Rust sidecar credential keys or the Rust OpenCode provider keys. The test reads those from the Runner source, as the Codex security test does. A provider without a Runner route fails the test. `OPEN_CODE_RUNNER_ENVIRONMENT_KEYS` is now exported for this test. - Docs: Added a "Typed credentials" section to `doc/plugins/PLUGIN_ENVIRONMENT_TASKS.md`. It also documents the ACPX credential binding that the Runner requires with a Copilot token. Updated `doc/plugins/PLUGIN_RUNNER_EXECUTION.md`. ## Verification - `npx vitest run tests/environment-task-release-resume.test.ts tests/environment-tasks.test.ts` in `packages/plugins/sdk`: 96 passed. The tests accept each valid shape. They reject mixed sets, two sets, extra variables, another provider's variable, empty values, NUL bytes, oversized values, unknown providers and extra fields, on `submit` and on `resume`. They also check that every published allowlist set parses. - `npx vitest run src/services/native-runtime/plugin-runner-credentials.test.ts src/__tests__/environment-task-runtime.test.ts` in `server`: 79 passed. The new tests cover each provider's transfer, Grok subscription refusal, Grok routing refusal, the fail-closed cases without value leaks, harness matching at submit, and Runner-built Grok requirements (`runnerProviderLaunchRequirements`) that parse through the task contract and produce a Grok launch. - `npx vitest run src/__tests__/plugin-runner-credential-names.test.ts` in `server`: 4 passed. I broke each list locally to confirm that the test fails: a renamed SDK key, an SDK provider without a Runner route, and a dropped name in the Rust sidecar keys, the Rust candidate agents, the Rust OpenCode keys and the TypeScript OpenCode keys. Each change failed the test. - `node scripts/typecheck-layers.mjs` in `server` (includes `src/__tests__`): no errors. - `npx vitest run server/src/services/native-runtime/plugin-runner-probe.test.ts` (from the root): 15 passed. `server/src/services/native-runtime/plugin-runner-task.test.ts`: passed. - `tsc --noEmit` for `packages/plugins/sdk` and `server`: no errors. - I did not run the full suite locally. CI supplies that coverage. ## Risks - Low risk for existing plugins. The change only adds a credential type and two optional settings. A plugin that does not handle `provider-env` gets a typed value that it does not recognize. Before this change, Core failed these runs before it called the plugin. - A plugin must set `PAPERCLIP_ACPX_CREDENTIAL_BINDING` for a Copilot task. Otherwise the Runner refuses the token. The new doc section shows the value. - An OpenCode gateway connection without a key (`auth: none`) still fails closed, because every value must be non-empty. > For core feature work, check [`ROADMAP.md`](ROADMAP.md) first and discuss it in `#dev` before opening the PR. Feature PRs that overlap with planned core work may need to be redirected — check the roadmap first. See `CONTRIBUTING.md`. ## Model Used - Claude Opus 5.5 (`claude-opus-5-5`) by Anthropic, through Claude Code with tool use (shell, file edits, test runs). ## 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 and confirmed this PR does not duplicate planned core work - [x] I have searched GitHub for duplicate or related PRs and linked them above - [x] I have either (a) linked existing issues with `Fixes: #` / `Closes #` / `Refs #` OR (b) described the issue in-PR following the relevant issue template - [x] I have not referenced internal/instance-local Paperclip issues or links (only public GitHub `#NNN` / `github.com/paperclipai/paperclip` URLs) - [x] My branch name describes the change (e.g. `docs/...`, `fix/...`) and contains no internal Paperclip ticket id or instance-derived details - [x] I have run tests locally and they pass - [x] I have added or updated tests where applicable - [x] I have updated relevant documentation to reflect my changes - [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 - [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 5.5 --- doc/plugins/PLUGIN_ENVIRONMENT_TASKS.md | 41 ++++++++++++++- doc/plugins/PLUGIN_RUNNER_EXECUTION.md | 6 ++- .../src/live/runnerd-codex-transport.ts | 2 +- packages/plugins/sdk/src/environment-tasks.ts | 21 ++++++++ packages/plugins/sdk/src/index.ts | 4 +- .../environment-task-release-resume.test.ts | 19 +++++++ .../sdk/tests/environment-tasks.test.ts | 27 +++++++++- .../environment-task-runtime.test.ts | 36 ++++++++++++- .../plugin-runner-credential-names.test.ts | 51 +++++++++++++++++++ .../src/services/environment-task-runtime.ts | 3 +- .../plugin-runner-credentials.test.ts | 48 ++++++++++++++++- .../plugin-runner-credentials.ts | 18 ++++++- .../runner-e2e/source-sdk-public-inputs.json | 4 +- 13 files changed, 267 insertions(+), 13 deletions(-) create mode 100644 server/src/__tests__/plugin-runner-credential-names.test.ts diff --git a/doc/plugins/PLUGIN_ENVIRONMENT_TASKS.md b/doc/plugins/PLUGIN_ENVIRONMENT_TASKS.md index bf02fb8396e..c516aa2ddc4 100644 --- a/doc/plugins/PLUGIN_ENVIRONMENT_TASKS.md +++ b/doc/plugins/PLUGIN_ENVIRONMENT_TASKS.md @@ -66,8 +66,45 @@ query, or fragment. Return authentication in the secret headers. `submit` contains the PRP version range, Runner identity, bootstrap ticket, authorized project IDs, and optional launch limits. It can also contain a saved -task ID for session reuse and a typed Codex or Claude credential. Core does not -supply an executable command or a guest path. +task ID for session reuse and a typed credential. Core does not supply an +executable command or a guest path. + +### Typed credentials + +The `credential` field has one of these types: + +| `type` | Contents | Harness | +| --- | --- | --- | +| `codex-auth-json` | `authJson`: the selected Codex `auth.json` | `codex` | +| `claude-env` | `environment`: exactly one of `CLAUDE_CODE_OAUTH_TOKEN` or `ANTHROPIC_API_KEY` | `claude` | +| `provider-env` | `provider` and `environment`: one complete variable set for that provider | `grok`, `copilot` or `opencode` | + +A `provider-env` credential contains exactly one of these variable sets and no +other variable: + +| `provider` | Variable sets | +| --- | --- | +| `grok` | `XAI_API_KEY` | +| `copilot` | `COPILOT_GITHUB_TOKEN` | +| `opencode` | `OPENROUTER_API_KEY`, or `PAPERCLIP_AI_PROVIDER_URL` with `PAPERCLIP_AI_PROVIDER_KEY` | + +`ENVIRONMENT_TASK_PROVIDER_CREDENTIAL_KEY_SETS` exports this list. A server test +checks every set against the names that the Runner forwards to each provider. Every value +is non-empty and contains no NUL byte. The `provider` always matches the +Runner harness of the task. Set the variables in the environment of the Runner +process. The Runner gives each variable only to its provider. + +For `copilot`, also set `PAPERCLIP_ACPX_CREDENTIAL_BINDING` in the Runner +environment. Its value is this JSON object, with the normalized session ID of +the task's PRP identity: + +```json +{"schema":"paperclip.acpx_credential_binding.v1","agent":"copilot","sessionId":"","names":["COPILOT_GITHUB_TOKEN"]} +``` + +The Runner refuses a Copilot token without a matching binding. +Core does not send a Grok subscription login. A Grok agent must use an xAI API +key in a plugin environment. ## Configured environment diff --git a/doc/plugins/PLUGIN_RUNNER_EXECUTION.md b/doc/plugins/PLUGIN_RUNNER_EXECUTION.md index 09bce17810c..361ac89ffd7 100644 --- a/doc/plugins/PLUGIN_RUNNER_EXECUTION.md +++ b/doc/plugins/PLUGIN_RUNNER_EXECUTION.md @@ -102,8 +102,12 @@ reconciliation for the same task. ## Credentials and tools -Core can transfer a selected Codex account or a direct Claude credential. +Core can transfer a selected Codex account, a direct Claude credential, or the +API credential of a Grok, Copilot or OpenCode connection. See +[typed credentials](PLUGIN_ENVIRONMENT_TASKS.md#typed-credentials). Other managed routes fail closed until they have a typed credential contract. +A Grok subscription login, Claude provider routing, and an OpenCode gateway +without a key also fail closed. Do not put credentials in task metadata, journals, logs, or errors. Assigned MCP tools run through the Core gateway over PRP. diff --git a/packages/paperclip-runner/src/live/runnerd-codex-transport.ts b/packages/paperclip-runner/src/live/runnerd-codex-transport.ts index fdae1e47985..378837d2d70 100644 --- a/packages/paperclip-runner/src/live/runnerd-codex-transport.ts +++ b/packages/paperclip-runner/src/live/runnerd-codex-transport.ts @@ -4018,7 +4018,7 @@ export function createCapabilityRunnerdProviderEnvironment(input: Parameters; +export const ENVIRONMENT_TASK_PROVIDER_CREDENTIAL_KEY_SETS = { + grok: [["XAI_API_KEY"]], + copilot: [["COPILOT_GITHUB_TOKEN"]], + opencode: [["OPENROUTER_API_KEY"], ["PAPERCLIP_AI_PROVIDER_URL", "PAPERCLIP_AI_PROVIDER_KEY"]], +} as const satisfies Record; +export type PluginEnvironmentTaskCredentialProvider = keyof typeof ENVIRONMENT_TASK_PROVIDER_CREDENTIAL_KEY_SETS; +const providerCredential = z.object({ + type: z.literal("provider-env"), + provider: z.enum(["grok", "copilot", "opencode"]), + environment: z.record(z.string(), credentialValue), +}).strict().superRefine((credential, ctx) => { + const names = Object.keys(credential.environment).sort(); + const sets: readonly (readonly string[])[] = ENVIRONMENT_TASK_PROVIDER_CREDENTIAL_KEY_SETS[credential.provider]; + if (!sets.some(set => set.length === names.length && [...set].sort().every((name, index) => name === names[index]))) { + ctx.addIssue({ code: z.ZodIssueCode.custom, message: "Select one complete credential for the provider", path: ["environment"] }); + } +}); + /** Only provider authentication is transferred. Paths and executable settings remain provider-owned. */ export const environmentTaskCredentialSchema = z.discriminatedUnion("type", [ z.object({ type: z.literal("codex-auth-json"), authJson: credentialValue }).strict(), z.object({ type: z.literal("claude-env"), environment: claudeCredentialEnvironment }).strict(), + providerCredential, ]); export type PluginEnvironmentTaskCredential = z.infer; @@ -74,6 +93,8 @@ export const environmentRunnerLaunchRequirementsSchema = z.object({ acpxPermissionMode: z.enum(["approve-all", "approve-paperclip", "approve-reads", "deny-all"]).optional(), acpxPermissionModePinned: z.boolean().optional(), piThinkingLevel: z.enum(["off", "low", "high", "max"]).optional(), claudeEffort: z.enum(["low", "medium", "high", "xhigh", "max"]).optional(), + grokEffort: z.enum(["minimal", "low", "medium", "high", "xhigh"]).optional(), + grokDisableWebSearch: z.boolean().optional(), opencodePermissionMode: z.enum(["allow", "ask", "deny"]).optional(), disableCodexWebSearch: z.literal(true).optional(), disableCodexProjectInstructions: z.literal(true).optional(), diff --git a/packages/plugins/sdk/src/index.ts b/packages/plugins/sdk/src/index.ts index de69769668c..686c87d177f 100644 --- a/packages/plugins/sdk/src/index.ts +++ b/packages/plugins/sdk/src/index.ts @@ -498,8 +498,8 @@ export type { PluginEnvironmentTaskErrorDiagnostic } from "./environment-task-er export type { AiConnectionPool, AiConnectionPoolConfig, AiConnectionPoolMember, AiConnectionRouterRequest, AiConnectionRouterResult, AiConnectionRouterSelection } from "@paperclipai/shared"; -export { MAX_ENVIRONMENT_TASK_FILE_BYTES, environmentRunnerLaunchRequirementsSchema, environmentTaskOperationSchema, environmentTaskResultSchema, environmentTaskCredentialSchema, environmentTaskConfiguredEnvironmentSchema, MAX_CONFIGURED_ENVIRONMENT_KEYS, MAX_CONFIGURED_ENVIRONMENT_ENTRY_BYTES, MAX_CONFIGURED_ENVIRONMENT_BYTES, parseEnvironmentTaskResult } from "./environment-tasks.js"; -export type { PluginEnvironmentTaskOperation, PluginEnvironmentTaskParams, PluginEnvironmentTaskResult, PluginEnvironmentTaskCredential, PluginEnvironmentTaskConfiguredEnvironment, PluginEnvironmentTaskExecutionContext } from "./environment-tasks.js"; +export { MAX_ENVIRONMENT_TASK_FILE_BYTES, ENVIRONMENT_TASK_PROVIDER_CREDENTIAL_KEY_SETS, environmentRunnerLaunchRequirementsSchema, environmentTaskOperationSchema, environmentTaskResultSchema, environmentTaskCredentialSchema, environmentTaskConfiguredEnvironmentSchema, MAX_CONFIGURED_ENVIRONMENT_KEYS, MAX_CONFIGURED_ENVIRONMENT_ENTRY_BYTES, MAX_CONFIGURED_ENVIRONMENT_BYTES, parseEnvironmentTaskResult } from "./environment-tasks.js"; +export type { PluginEnvironmentTaskOperation, PluginEnvironmentTaskParams, PluginEnvironmentTaskResult, PluginEnvironmentTaskCredential, PluginEnvironmentTaskCredentialProvider, PluginEnvironmentTaskConfiguredEnvironment, PluginEnvironmentTaskExecutionContext } from "./environment-tasks.js"; export type { AgentLifecycleRequest, AgentLifecycleResult } from "@paperclipai/shared"; export type { PluginEnvironmentRunnerLaunchRequirements, PluginEnvironmentPreparedLaunch } from "./environment-tasks.js"; diff --git a/packages/plugins/sdk/tests/environment-task-release-resume.test.ts b/packages/plugins/sdk/tests/environment-task-release-resume.test.ts index 60e47256303..5f72f05c980 100644 --- a/packages/plugins/sdk/tests/environment-task-release-resume.test.ts +++ b/packages/plugins/sdk/tests/environment-task-release-resume.test.ts @@ -36,6 +36,25 @@ const credentials: [string, unknown, boolean][] = [ ["an oversized value", { type: "codex-auth-json", authJson: "x".repeat(65_537) }, false], ["an unknown type", { type: "gemini-env", environment: { GEMINI_API_KEY: "fixture" } }, false], ["an extra field", { type: "codex-auth-json", authJson: "{}", path: "/home/agent/.codex" }, false], + ["an xAI API key for Grok", { type: "provider-env", provider: "grok", environment: { XAI_API_KEY: "fixture-xai" } }, true], + ["a Copilot token", { type: "provider-env", provider: "copilot", environment: { COPILOT_GITHUB_TOKEN: "fixture-copilot" } }, true], + ["an OpenRouter key for OpenCode", { type: "provider-env", provider: "opencode", environment: { OPENROUTER_API_KEY: "fixture-openrouter" } }, true], + ["an OpenCode gateway", { type: "provider-env", provider: "opencode", + environment: { PAPERCLIP_AI_PROVIDER_URL: "https://gateway.example.test/v1", PAPERCLIP_AI_PROVIDER_KEY: "fixture-gateway" } }, true], + ["half of an OpenCode gateway", { type: "provider-env", provider: "opencode", environment: { PAPERCLIP_AI_PROVIDER_URL: "https://gateway.example.test/v1" } }, false], + ["a mixed OpenCode set", { type: "provider-env", provider: "opencode", + environment: { OPENROUTER_API_KEY: "fixture-openrouter", PAPERCLIP_AI_PROVIDER_KEY: "fixture-gateway" } }, false], + ["two OpenCode sets", { type: "provider-env", provider: "opencode", environment: { OPENROUTER_API_KEY: "fixture-openrouter", + PAPERCLIP_AI_PROVIDER_URL: "https://gateway.example.test/v1", PAPERCLIP_AI_PROVIDER_KEY: "fixture-gateway" } }, false], + ["another provider's variable", { type: "provider-env", provider: "grok", environment: { COPILOT_GITHUB_TOKEN: "fixture-copilot" } }, false], + ["an extra provider variable", { type: "provider-env", provider: "grok", environment: { XAI_API_KEY: "fixture-xai", XAI_BASE_URL: "https://router.example.test" } }, false], + ["no provider variable", { type: "provider-env", provider: "copilot", environment: {} }, false], + ["an empty provider value", { type: "provider-env", provider: "copilot", environment: { COPILOT_GITHUB_TOKEN: "" } }, false], + ["a NUL byte in a provider value", { type: "provider-env", provider: "grok", environment: { XAI_API_KEY: "a\0b" } }, false], + ["an oversized provider value", { type: "provider-env", provider: "grok", environment: { XAI_API_KEY: "x".repeat(65_537) } }, false], + ["an unsupported provider", { type: "provider-env", provider: "gemini", environment: { GEMINI_API_KEY: "fixture-gemini" } }, false], + ["a provider credential without a provider", { type: "provider-env", environment: { XAI_API_KEY: "fixture-xai" } }, false], + ["an extra provider credential field", { type: "provider-env", provider: "grok", environment: { XAI_API_KEY: "fixture-xai" }, home: "/home/agent" }, false], ]; async function invoke(operation: unknown, handler: (params: PluginEnvironmentTaskParams) => Promise) { diff --git a/packages/plugins/sdk/tests/environment-tasks.test.ts b/packages/plugins/sdk/tests/environment-tasks.test.ts index bd52cb8ccc7..124bcadecb2 100644 --- a/packages/plugins/sdk/tests/environment-tasks.test.ts +++ b/packages/plugins/sdk/tests/environment-tasks.test.ts @@ -1,5 +1,5 @@ import {describe,expect,it} from "vitest"; -import {environmentTaskOperationSchema,environmentTaskResultSchema} from "../src/environment-tasks.js"; +import {ENVIRONMENT_TASK_PROVIDER_CREDENTIAL_KEY_SETS,environmentTaskCredentialSchema,environmentTaskOperationSchema,environmentTaskResultSchema} from "../src/environment-tasks.js"; const submit={kind:"submit",projectIds:[],bootstrapTicket:"synthetic",runner:{harness:"codex",protocolMin:1,protocolMax:3,runnerId:"runner",leaseId:"lease",runId:"run",sessionId:"session",turnId:"turn",itemId:"item"}, launch:{runnerVersion:"fixture",runnerDigest:`sha256:${"a".repeat(64)}`,maxOutboxBytes:262144,p0ReserveBytes:65536,lifecyclePolicy:{mode:"warm",idleTimeoutMs:300000}}}; describe("task lifecycle policy",()=>{ @@ -124,3 +124,28 @@ describe("configured environment", () => { expect(environmentTaskResultSchema.safeParse({ ...description, configuredEnvironmentVersion: 2 }).success).toBe(false); }); }); + +describe("Grok launch settings", () => { + const grok = (settings: Record) => ({ ...prepare, requirements: { ...prepare.requirements, + provider: "acpx", settings: { acpxAgent: "grok", ...settings } } }); + it.each([{ grokDisableWebSearch: true }, { grokDisableWebSearch: false }, { grokEffort: "minimal", grokDisableWebSearch: true }, + { grokEffort: "xhigh" }, {}])("accepts the Runner's Grok settings %j", settings => { + expect(environmentTaskOperationSchema.parse(grok(settings))).toEqual(grok(settings)); + }); + it.each([{ grokEffort: "max" }, { grokEffort: "" }, { grokDisableWebSearch: "true" }, { grokDisableWebSearch: null }])("rejects invalid Grok settings %j", settings => { + expect(environmentTaskOperationSchema.safeParse(grok(settings)).success).toBe(false); + }); +}); + +describe("provider environment credential allowlist", () => { + it("accepts every published set and nothing beyond it", () => { + for (const [provider, sets] of Object.entries(ENVIRONMENT_TASK_PROVIDER_CREDENTIAL_KEY_SETS)) { + for (const set of sets) { + const environment = Object.fromEntries(set.map(name => [name, "fixture-value"])); + expect(environmentTaskCredentialSchema.safeParse({ type: "provider-env", provider, environment }).success).toBe(true); + expect(environmentTaskCredentialSchema.safeParse({ type: "provider-env", provider, + environment: { ...environment, UNRELATED_SECRET: "fixture-value" } }).success).toBe(false); + } + } + }); +}); diff --git a/server/src/__tests__/environment-task-runtime.test.ts b/server/src/__tests__/environment-task-runtime.test.ts index 68e1df593b0..cabd46e3808 100644 --- a/server/src/__tests__/environment-task-runtime.test.ts +++ b/server/src/__tests__/environment-task-runtime.test.ts @@ -5,7 +5,7 @@ import { environmentTaskErrorCodeData, environmentTaskOperationSchema, parseEnvi readEnvironmentTaskErrorCode, readEnvironmentTaskErrorDiagnostic } from "@paperclipai/plugin-sdk"; import { executeEnvironmentTask, isSettledReadyRunnerState, settleDispatchedEnvironmentTask } from "../services/environment-task-runtime.js"; import { NativeExecutionContext } from "../services/native-runtime/native-execution-context.js"; -import { runnerLaunchPreparationDigest, runnerLaunchRunDigest } from "../vendor/paperclip-runner/index.js"; +import { createRunnerProviderLaunch, runnerLaunchPreparationDigest, runnerLaunchRunDigest, runnerProviderLaunchRequirements } from "../vendor/paperclip-runner/index.js"; const state = vi.hoisted(() => ({ plugin: {} as any, release: vi.fn(), identity: vi.fn(), config: vi.fn() })); vi.mock("../services/provider-fresh-workspace.js", () => ({ @@ -328,6 +328,26 @@ describe("plugin-provided Runner execution", () => { await expect(executeEnvironmentTask(database(value).db, worker() as never, { companyId: "company", leaseId, operation: { ...operation, credential: { type: "claude-env", environment: { ANTHROPIC_API_KEY: "never-leak" } } } })).rejects.toThrow("validation unavailable"); }); + it.each(["grok", "copilot", "opencode"] as const)("dispatches a %s environment credential only for the matching harness", async harness => { + const credentials = { + grok: { type: "provider-env" as const, provider: "grok" as const, environment: { XAI_API_KEY: "never-leak" } }, + copilot: { type: "provider-env" as const, provider: "copilot" as const, environment: { COPILOT_GITHUB_TOKEN: "never-leak" } }, + opencode: { type: "provider-env" as const, provider: "opencode" as const, environment: { OPENROUTER_API_KEY: "never-leak" } }, + }; + const operation = { ...submit, runner: { ...submit.runner, harness }, accountIdentity: "account", credential: credentials[harness] }; + const validated = () => { + const value = row(); + Object.assign(value.lease.metadata, { runnerTaskProjectAuthValidation: { configurationId: "configuration", provider: harness, projectIds: [projectId] } }); + return value; + }; + const accepted = worker(); + await expect(executeEnvironmentTask(database(validated()).db, accepted as never, { companyId: "company", leaseId, operation })).resolves.toMatchObject({ kind: "accepted" }); + expect(accepted.call).toHaveBeenCalledOnce(); + const denied = worker(); + await expect(executeEnvironmentTask(database(validated()).db, denied as never, { companyId: "company", leaseId, + operation: { ...operation, credential: credentials[harness === "grok" ? "copilot" : "grok"] } })).rejects.toThrow("validation unavailable"); + expect(denied.call).not.toHaveBeenCalled(); + }); it.each(["allowed", "denied", "wrong-configuration", "wrong-provider", "timeout"])("records only a matching successful project validation (%s)", async mode => { const operation = { kind: "check_project_auth" as const, configurationId: "configuration", provider: "openai" as const, projectIds: [projectId] }; const result = { kind: "project_auth", taskId: "attempt-1", configurationId: mode === "wrong-configuration" ? "other" : "configuration", @@ -697,3 +717,17 @@ describe("plugin-provided Runner execution", () => { expect(() => parseEnvironmentTaskResult({ kind: "stop" }, "attempt-1", rejected)).toThrow(); }); }); + +describe("Runner launch requirements for plugin preparation", () => { + const identity = { runnerInstanceId: "runner", environmentLeaseId: leaseId, runId: "run", normalizedSessionId: "session", turnId: "turn", itemId: "item" }; + it.each([{ grokDisableWebSearch: true }, { grokEffort: "high" as const, grokDisableWebSearch: true }, { grokDisableWebSearch: false }])( + "passes the Runner's Grok settings %j through the task contract", settings => { + const requirements = runnerProviderLaunchRequirements({ provider: "acpx", acpxAgent: "grok", ...settings }, identity, + { model: "grok-build" }, null, "Follow the assigned instructions."); + const prepared = environmentTaskOperationSchema.parse({ kind: "prepare", projectIds: [], requirements }); + expect(prepared).toMatchObject({ requirements: { settings: { acpxAgent: "grok", ...settings } } }); + expect(createRunnerProviderLaunch(requirements, { options: {}, root: "/runner", cwd: "/workspace", codexHome: "/runner/codex", + providerNodeCommand: "node", opencodeProxyPath: "/runner/opencode.cjs", acpxSidecarPath: "/runner/acpx.cjs" })) + .toMatchObject({ agent: "grok", grokDisableWebSearch: settings.grokDisableWebSearch }); + }); +}); diff --git a/server/src/__tests__/plugin-runner-credential-names.test.ts b/server/src/__tests__/plugin-runner-credential-names.test.ts new file mode 100644 index 00000000000..43b0433cbfb --- /dev/null +++ b/server/src/__tests__/plugin-runner-credential-names.test.ts @@ -0,0 +1,51 @@ +import { readFileSync } from "node:fs"; +import { resolve } from "node:path"; +import { describe, expect, it } from "vitest"; +import { ENVIRONMENT_TASK_PROVIDER_CREDENTIAL_KEY_SETS } from "@paperclipai/plugin-sdk"; +import { + ACPX_CREDENTIAL_BINDING_ENV, ACPX_CREDENTIAL_NAMES, createAcpxCredentialBinding, createAcpxSidecarHostEnvironment, createSanitizedAcpxSpawnInput, +} from "../../../packages/paperclip-runner/src/drivers/acpx/environment.js"; +import { OPEN_CODE_RUNNER_ENVIRONMENT_KEYS } from "../../../packages/paperclip-runner/src/live/runnerd-codex-transport.js"; + +const runnerSource = (file: string) => + readFileSync(resolve(import.meta.dirname, "../../../packages/paperclip-runner/runner/crates/runner-core/src", file), "utf8"); +const names = (block: string | undefined) => [...(block ?? "").matchAll(/"([A-Za-z0-9_]+)"/gu)].map(match => match[1]); +const acpxSidecar = runnerSource("acpx_sidecar_transport.rs"); +const rustAcpxCredentialNames = (agent: string) => + names(new RegExp(`"${agent}" => &\\[([^\\]]*)\\]`, "u").exec(acpxSidecar)?.[1]); +const rustCandidateAgents = names(/if matches!\(agent, ([^)]*)\) \{[^}]*keys\.push\("PAPERCLIP_ACPX_CREDENTIAL_BINDING"\)/u.exec(acpxSidecar)?.[1]); +const rustOpenCodeNames = names(/const OPENCODE_PROVIDER_ENVIRONMENT_KEYS: &\[&str\] = &\[([^\]]*)\];/u.exec(runnerSource("codex_provider.rs"))?.[1]); +const acpxAgents = Object.keys(ACPX_CREDENTIAL_NAMES) as (keyof typeof ACPX_CREDENTIAL_NAMES)[]; +const providers = Object.entries(ENVIRONMENT_TASK_PROVIDER_CREDENTIAL_KEY_SETS); + +describe("plugin Runner provider credential names", () => { + it("reads the Runner's Rust allowlists", () => { + expect(rustAcpxCredentialNames("copilot")).toContain("COPILOT_GITHUB_TOKEN"); + expect(rustCandidateAgents).toContain("copilot"); + expect(rustOpenCodeNames).toContain("OPENROUTER_API_KEY"); + }); + + it.each(providers)("routes every %s credential variable through the Runner", (provider, sets) => { + const variables = sets.flat(); + const environment = Object.fromEntries(variables.map(name => [name, `fixture-${name.toLowerCase()}`])); + if (provider === "opencode") { + for (const name of variables) { + expect(OPEN_CODE_RUNNER_ENVIRONMENT_KEYS.has(name), `${name} reaches the OpenCode proxy`).toBe(true); + expect(rustOpenCodeNames, `${name} reaches OpenCode from the Runner process`).toContain(name); + } + return; + } + expect(acpxAgents, `${provider} is an ACPX agent with credential names`).toContain(provider); + const agent = provider as (typeof acpxAgents)[number]; + const binding = createAcpxCredentialBinding(environment, agent, "session"); + expect(rustCandidateAgents.includes(agent), `${agent} binding forwarding matches the sidecar`).toBe(binding !== undefined); + const host = createAcpxSidecarHostEnvironment(binding === undefined ? environment : { ...environment, [ACPX_CREDENTIAL_BINDING_ENV]: binding }, agent, "session"); + const spawned = createSanitizedAcpxSpawnInput(host, agent).env; + for (const name of variables) { + expect(ACPX_CREDENTIAL_NAMES[agent], `${name} is an ACPX ${agent} credential`).toContain(name); + expect(rustAcpxCredentialNames(agent), `${name} reaches the ACPX sidecar from the Runner process`).toContain(name); + expect(host[name], `${name} survives sidecar admission`).toBe(environment[name]); + expect(spawned[name], `${name} reaches the ${agent} process`).toBe(environment[name]); + } + }); +}); diff --git a/server/src/services/environment-task-runtime.ts b/server/src/services/environment-task-runtime.ts index d656c547113..9ce9e49fe75 100644 --- a/server/src/services/environment-task-runtime.ts +++ b/server/src/services/environment-task-runtime.ts @@ -299,7 +299,8 @@ export async function executeEnvironmentTask(db: Db, workers: Pick; diff --git a/server/src/services/native-runtime/plugin-runner-credentials.test.ts b/server/src/services/native-runtime/plugin-runner-credentials.test.ts index 3c6d20d820b..d2e1a1ed8a1 100644 --- a/server/src/services/native-runtime/plugin-runner-credentials.test.ts +++ b/server/src/services/native-runtime/plugin-runner-credentials.test.ts @@ -36,7 +36,53 @@ describe("plugin Runner selected credentials", () => { }); it("does not read a controller credential when the provider owns the account", async () => { expect(await preparePluginRunnerCredentials({ provider: "codex", home: "/must/not/read", environment: {} })).toEqual({}); - await expect(preparePluginRunnerCredentials({ provider: "opencode", identity: "revision", environment: {} })).rejects.toThrow("credential provider"); + await expect(preparePluginRunnerCredentials({ provider: "cursor", identity: "revision", environment: { CURSOR_API_KEY: "fixture-key" } })).rejects.toThrow("credential provider"); + }); +}); + +describe("plugin Runner provider environment credentials", () => { + const blanks = { XAI_API_KEY: "", COPILOT_GITHUB_TOKEN: "", OPENROUTER_API_KEY: "", PAPERCLIP_AI_PROVIDER_URL: "", PAPERCLIP_AI_PROVIDER_KEY: "", + ANTHROPIC_API_KEY: "", HOME: "/controller/private", GROK_HOME: "/controller/private/provider", OTHER_SECRET: "fixture-unrelated" }; + it.each([ + ["grok", { XAI_API_KEY: "fixture-xai" }], + ["copilot", { COPILOT_GITHUB_TOKEN: "fixture-copilot" }], + ["opencode", { OPENROUTER_API_KEY: "fixture-openrouter" }], + ["opencode", { PAPERCLIP_AI_PROVIDER_URL: "https://gateway.example.test/v1", PAPERCLIP_AI_PROVIDER_KEY: "fixture-gateway" }], + ] as const)("transfers only the selected %s variables", async (provider, environment) => { + const transfer = await preparePluginRunnerCredentials({ provider, identity: "revision", accountIdentity: "account", + environment: { ...blanks, ...environment, OPENCODE_CONFIG_CONTENT: "{\"provider\":{}}" } }); + expect(transfer).toEqual({ accountIdentity: "account", credential: { type: "provider-env", provider, environment } }); + expect(transfer.needsWriteback).toBeUndefined(); + }); + it("uses the credential revision as the account when no account identity is supplied", async () => { + const transfer = await preparePluginRunnerCredentials({ provider: "copilot", identity: "revision", environment: { COPILOT_GITHUB_TOKEN: "fixture-copilot" } }); + expect(transfer.accountIdentity).toBe("revision"); + }); + it("keeps the GitHub broker authority beside the provider credential", async () => { + const transfer = await preparePluginRunnerCredentials({ provider: "grok", identity: "revision", environment: { + XAI_API_KEY: "fixture-xai", PAPERCLIP_GITHUB_BROKER_URL: "https://core.example.test", PAPERCLIP_GITHUB_BROKER_TOKEN: "runtime-capability" } }); + expect(transfer.githubBroker).toEqual({ url: "https://core.example.test", token: "runtime-capability" }); + expect(transfer.credential).toEqual({ type: "provider-env", provider: "grok", environment: { XAI_API_KEY: "fixture-xai" } }); + }); + it("refuses a Grok subscription, which needs an auth file with refresh and writeback", async () => { + await expect(preparePluginRunnerCredentials({ provider: "grok", identity: "revision", home: "/controller/private/provider", + environment: blanks })).rejects.toThrow("Grok subscription login is not supported"); + }); + it("refuses Grok provider routing that would redirect the key", async () => { + await expect(preparePluginRunnerCredentials({ provider: "grok", identity: "revision", + environment: { XAI_API_KEY: "fixture-xai", XAI_BASE_URL: "https://router.example.test" } })).rejects.toThrow("routing"); + }); + it.each([ + ["copilot", {}], + ["opencode", {}], + ["opencode", { PAPERCLIP_AI_PROVIDER_URL: "https://gateway.example.test/v1" }], + ["opencode", { PAPERCLIP_AI_PROVIDER_KEY: "fixture-gateway" }], + ["opencode", { OPENROUTER_API_KEY: "fixture-openrouter", PAPERCLIP_AI_PROVIDER_URL: "https://gateway.example.test/v1", PAPERCLIP_AI_PROVIDER_KEY: "fixture-gateway" }], + ["opencode", { OPENROUTER_API_KEY: "fixture\0value" }], + ] as const)("fails closed for an incomplete or ambiguous %s credential", async (provider, environment) => { + const result = preparePluginRunnerCredentials({ provider, identity: "revision", environment: { ...blanks, ...environment } }); + await expect(result).rejects.toThrow("Plugin Runner selected credential unavailable"); + await result.catch((error: Error) => expect(error.message).not.toContain("fixture")); }); }); diff --git a/server/src/services/native-runtime/plugin-runner-credentials.ts b/server/src/services/native-runtime/plugin-runner-credentials.ts index 08d2cce011e..b4060632cdb 100644 --- a/server/src/services/native-runtime/plugin-runner-credentials.ts +++ b/server/src/services/native-runtime/plugin-runner-credentials.ts @@ -1,7 +1,10 @@ import { realpath } from "node:fs/promises"; import { join } from "node:path"; import { copyBackCodexAuth } from "@paperclipai/adapter-codex-local/server"; -import { environmentTaskCredentialSchema, type PluginEnvironmentTaskCredential } from "@paperclipai/plugin-sdk"; +import { + ENVIRONMENT_TASK_PROVIDER_CREDENTIAL_KEY_SETS, environmentTaskCredentialSchema, + type PluginEnvironmentTaskCredential, type PluginEnvironmentTaskCredentialProvider, +} from "@paperclipai/plugin-sdk"; import { readLocalAiCredentialFile } from "../local-ai-credential-file.js"; interface PreparedPluginRunnerCredentials { @@ -48,5 +51,18 @@ export async function preparePluginRunnerCredentials(input: { .flatMap(key => input.environment[key] ? [[key, input.environment[key]]] : [])); return { ...github, accountIdentity, credential: environmentTaskCredentialSchema.parse({ type: "claude-env", environment }) }; } + if (input.provider === "grok" || input.provider === "copilot" || input.provider === "opencode") { + const provider: PluginEnvironmentTaskCredentialProvider = input.provider; + if (provider === "grok") { + if (input.environment.XAI_BASE_URL) throw new Error("Plugin Runner does not support the selected provider routing"); + if (!input.environment.XAI_API_KEY) throw new Error("Plugin Runner supports Grok only with an xAI API key. Grok subscription login is not supported."); + } + const names = new Set(ENVIRONMENT_TASK_PROVIDER_CREDENTIAL_KEY_SETS[provider].flat()); + const environment = Object.fromEntries([...names] + .flatMap(key => input.environment[key] ? [[key, input.environment[key]]] : [])); + const credential = environmentTaskCredentialSchema.safeParse({ type: "provider-env", provider, environment }); + if (!credential.success) throw new Error("Plugin Runner selected credential unavailable"); + return { ...github, accountIdentity, credential: credential.data }; + } throw new Error("Plugin Runner does not support the selected credential provider"); } diff --git a/tests/runner-e2e/source-sdk-public-inputs.json b/tests/runner-e2e/source-sdk-public-inputs.json index 3273cb5e903..6424be8240f 100644 --- a/tests/runner-e2e/source-sdk-public-inputs.json +++ b/tests/runner-e2e/source-sdk-public-inputs.json @@ -13,11 +13,11 @@ "packages/plugins/sdk/src/environment-stop-error.ts": "b0e03f8aa2b2170ba095da5c7138050fced3f3cb", "packages/plugins/sdk/src/environment-sync-error.ts": "7d6a51a95da49a7da4525aebbab6382dc5c44ae8", "packages/plugins/sdk/src/environment-task-error.ts": "98aae8a06743b38884b68cb9a3ec44c57b34c0e4", - "packages/plugins/sdk/src/environment-tasks.ts": "e4c952039c74bcc3b206f34fa751e2a82d1a7cda", + "packages/plugins/sdk/src/environment-tasks.ts": "5557e21415c67aca5c2dff7e06e8ea590f6c582e", "packages/plugins/sdk/src/host-client-factory.ts": "e0301c390ea13f2340b669383f07af2455e48c8a", "packages/plugins/sdk/src/idle-drain.test.ts": "cc59f7881e7d46c89395a1d93d74f6c6b9b0a64a", "packages/plugins/sdk/src/idle-drain.ts": "ae6e4c6be4657a3d541396922b3bc551b8db557f", - "packages/plugins/sdk/src/index.ts": "de69769668c7d555d52576548d7fc1a35617627e", + "packages/plugins/sdk/src/index.ts": "686c87d177f180a05e4162dd762fd0447572956f", "packages/plugins/sdk/src/invocation-tracer.ts": "b28ac4aa4bc3e82658abac4a8081ed4508008696", "packages/plugins/sdk/src/protocol.duplex-channel.test.ts": "18255eb3d63038dc459240c111cbcb29fcba25cc", "packages/plugins/sdk/src/protocol.ts": "4861d78f1c57f1485a79e037932f39e8c91446b8",