mirror of
https://github.com/paperclipai/paperclip.git
synced 2026-11-20 18:26:40 +01:00
## Thinking Path > - Paperclip is the open source app people use to manage AI agents for work. > - Agents run on coding harnesses. Each adapter has a model catalog, and sandboxes contain pinned CLIs. > - Anthropic released Claude Fable 5.2 and OpenAI released GPT-6.2 Sol and GPT-6.2 Astra for Codex. Both need newer CLIs than the Paperclip Runner provider pack ships. > - A stale catalog hides valid models. A model that needs a newer CLI fails with an opaque backend error. > - This pull request adds the verified model IDs with their CLI floors, names the version gap in Paperclip Runner, and refreshes the sandbox CLI pins. > - The benefit is that operators can select current models and get a named version error instead of a backend failure. ## Linked Issues or Issue Description Refs #20774 and #21636 (both add parts of Fable 5.2 support; see "Overlap" below). Refs #18486 (adds GPT-6.1 Terra; this PR does not duplicate it). Refs #16708 (adds Claude Haiku 5.5 to `claude_local`; this PR does not duplicate it). **What happened?** Claude Fable 5.2 (`claude-fable-5-2`) and GPT-6.2 Sol / Astra (`gpt-6.2-sol`, `gpt-6.2-astra`) are generally available. The `claude_local`, `codex_local`, and OpenCode pickers do not list them. Claude Code 2.1.321 is the first release with Fable 5.2. Codex 0.169.1 is the first release whose bundled catalog lists GPT-6.2. The Paperclip Runner provider pack bundles Claude Code 2.1.286 and Codex 0.160.0. **Expected behavior** The pickers list the new models. A run on a CLI below the model minimum stops with the detected and required versions, or falls back to a compatible model with a visible message. **Proposed change** Add the models and their per-model CLI floors. Gate ACPX Claude in Paperclip Runner on the Claude Code version that its Agent SDK bundles. Refresh the sandbox CLI pins with verified digests. Record the audit. ## What Changed - Claude Code (`claude_local`): - Add `claude-fable-5-2` (label "Claude Fable 5.2") at the top of the picker. `claude-fable-5-1` stays selectable after the current-generation models. - Add Bedrock `global.anthropic.claude-fable-5-2`. Anthropic documents only this global ID for Bedrock. - Fable 5.2 offers all five efforts (`low` to `max`). - `minimumClaudeCliVersionForModel("claude-fable-5-2")` returns `2.1.321`. The existing CLI-lane Test and launch checks use this floor. On a managed sandbox, the CLI lane installs a private Claude Code at this version, as it does for the other floors. - Paperclip Runner (ACPX Codex): `resolvePaperclipRunnerProviderProfile` rejects a model whose Codex floor is above the qualified ACPX Codex runtime (`0.160.0`). The error code is `paperclip_runner_codex_cli_version_incompatible`, and the message gives both versions. - Paperclip Runner (ACPX Claude): `resolvePaperclipRunnerProviderProfile` rejects a model whose Claude Code floor is above the version that the qualified Agent SDK bundles. The error code is `paperclip_runner_claude_cli_version_incompatible`. The message gives both versions. A new helper, `claudeCodeVersionForAgentSdk`, maps SDK `0.3.N` to Claude Code `2.1.N` (the SDK's `claudeCodeVersion` field) and returns `null` for any other line. - Codex (`codex_local`): - Add `gpt-6.2-sol` and `gpt-6.2-astra` at the top of the picker, in the bundled catalog order. - Both offer Fast mode and the `low` to `ultra` efforts. - Both have a CLI floor of `0.169.1`. On the native Codex provider with the pinned Codex 0.160.0, the existing fallback moves `gpt-6.2-sol` to `gpt-6.1-sol` and `gpt-6.2-astra` to `gpt-6-astra` with a visible message. - The default stays `gpt-6.1-sol`. - OpenCode fallback catalog: add `openai/gpt-6.2-sol`, `openai/gpt-6.2-astra`, `anthropic/claude-fable-5-2`, `google/gemini-4-carbon`, and `google/gemini-4-hydrogen`. - Evaluation image sandbox layer (`docker/daytona-runner`): | CLI | Before | After | | --- | --- | --- | | Grok CLI | 1.0.70 | 1.0.89 | | Gemini CLI | 0.65.0 | 0.68.0 | | Cursor CLI | 2026.10.22-27dcf5f | 2026.11.17-f532c45 | | GitHub CLI | 2.103.3 | 2.105.0 | - Add `doc/adapter-model-audit-2026-11-18.md` with sources, compatibility findings, and deferred items. Add a note on above-window Codex floors to `doc/architecture/paperclip-runner-compatibility.md`. No saved agent changes model, effort, or spending settings. No picker entry is removed. ### Managed sandboxes On Paperclip Runner, Fable 5.2 and GPT-6.2 stay unusable until the provider pack moves to Claude Code 2.1.321 or later and Codex 0.169.1 or later. A sandbox image that carries that provider pack must also be promoted. This PR does not change the provider pack (see "Deferred items" in the audit). Native remote Codex accepts only `>=0.149.0 <0.161.0`, so GPT-6.2 also needs that window to move. ### Overlap - #21636 sets the Fable 5.2 floor to `2.1.290`. The [Claude Code changelog](https://github.com/anthropics/claude-code/blob/main/CHANGELOG.md) adds Fable 5.2 in 2.1.321. `git merge-tree` merges the two without a text conflict, but #21636's line becomes unreachable after this PR's line, and its test then fails. Rule: keep `2.1.321`. Merge this PR first. Then close #21636 or change its floor and test to `2.1.321`. - #20774 (draft) lists `claude-fable-5-2`. It conflicts in `packages/adapters/claude-local/src/index.ts` and `server/src/__tests__/adapter-models.test.ts`. Rule: keep this PR's catalog order and Bedrock ID. - #18486 adds `gpt-6.1-terra`. It conflicts in `packages/adapters/codex-local/src/index.test.ts` and `src/server/codex-args.test.ts` (the ordered ID list and the Fast-mode message). Rule: keep both sets of models in the bundled catalog order (`gpt-6.2-sol`, `gpt-6.2-astra`, `gpt-6-astra`, `gpt-6.1-sol`, `gpt-6.1-terra`, ...). Either PR can merge first; the second rebases. - #16708 adds Claude Haiku 5.5. It conflicts in `packages/adapters/claude-local/src/index.test.ts` (adjacent test cases) and `doc/DEVELOPING.md`. Rule: keep both test blocks. ## Verification Research date: November 18, 2026. Sources are listed in the audit doc. - `vitest run src/index.test.ts src/server/model-order.test.ts src/server/cli-capabilities.test.ts src/server/test.remote.test.ts` in `packages/adapters/claude-local`: 40 passed. `execute.remote.test.ts` (29), `test.probe.test.ts` (21), `sandbox-cli-version.test.ts` (15), `acp.auth.test.ts` (25), and `acp.test.ts` (47, with `--testTimeout=60000`) also passed when run one file at a time. - `vitest run src/index.test.ts src/server/codex-args.test.ts src/ui/build-config.test.ts src/server/test.remote.test.ts` in `packages/adapters/codex-local`: all passed (155). `acp.test.ts` (49), `acp.cli-version.test.ts` (4), and `execute.test.ts` (10) also passed one file at a time. - `vitest run` in `packages/adapters/opencode-local`: 94 passed. - `vitest run src/services/native-runtime/acpx-qualification.test.ts src/services/native-runtime/codex-model-fallback.test.ts src/__tests__/adapter-models.test.ts src/__tests__/heartbeat-model-fallback-warning.test.ts` in `server`: all passed. The new cases cover the ACPX Claude and ACPX Codex version errors and the native GPT-6.2 fallback on Codex 0.160.0. - `vitest run src/lib/agent-setup-fields.test.ts src/lib/codex-reasoning-effort.test.ts` in `ui`: 11 passed. - `tsc --noEmit` in the three adapters and `pnpm typecheck` in `server`: passed. - Cursor archive SHA-256 `189ed41d8963cd22dcdafbbd62f072cc55ac08374c922dbd04aee525f4018ab6` is computed from the versioned Linux x64 tarball. The extracted binary reports `2026.11.17-f532c45`, the version that `https://cursor.com/install` resolves. - GitHub CLI SHA-256 `79e7ab5db738c48777b696e374f8b428f0647debfb424f44d2f426370407fe2f` matches `gh_2.105.0_checksums.txt`. - Grok CLI 1.0.89 and Gemini CLI 0.68.0 installed from npm report those versions. The flags that Paperclip uses are in `--help` (`-m`, `--effort`, `grok models`; `-m`, `-p`, `--output-format`, `--approval-mode`, `--yolo`). - Host baseline: tests that create an AI provider need the host's empty `ANTHROPIC_BASE_URL` unset. Under full-package parallel runs, SSH and sandbox fixture tests time out at 5 seconds on this host; each file passes alone. The audit doc records both. - Not run locally: the full `pnpm -r typecheck`, `pnpm build`, browser suites, and the image build. CI runs these. No live model inference ran. ## Risks - Low risk for saved agents: no default, saved model, effort, or spending setting changes. - The new Paperclip Runner checks reject `claude-fable-5-2` on ACPX Claude and `gpt-6.2-*` on ACPX Codex (and any later model whose floor is above the bundled runtime) before launch. Without this PR, the turn would start and fail at the backend. - The `0.3.N` → `2.1.N` mapping covers only the current SDK line. Any other line returns `null`, and the check is skipped. - The sandbox CLI pins change only the evaluation image. The fleet image change is separate. - Rollback: revert this PR. No data migration. ## Model Used - Claude Opus 5.5 (`claude-opus-5-5`), Anthropic, through Claude Code with tool use (shell, web fetch, file edits). ## 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 - [ ] All Paperclip CI gates are green - [ ] 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: devinfoley <139239+devinfoley@users.noreply.github.com> Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
968 lines
44 KiB
TypeScript
968 lines
44 KiB
TypeScript
import { resolveGrokDisableWebSearch } from "../../vendor/paperclip-runner/index.js";
|
|
import { agentHarnessType, normalizeClaudeRunnerOptions } from "@paperclipai/shared";
|
|
import { resolveClaudeEffort, resolveGrokEffort, resolveQualifiedAcpxProfile } from "../../vendor/paperclip-runner/index.js";
|
|
import {
|
|
isPaperclipRunnerProvider,
|
|
PAPERCLIP_RUNNER_PERMISSION_CAPABILITIES,
|
|
PAPERCLIP_RUNNER_ACPX_PROFILES,
|
|
resolvePaperclipRunnerPermissionMode,
|
|
resolvePaperclipRunnerCursorMode,
|
|
resolvePaperclipRunnerPiThinkingLevel,
|
|
type PaperclipRunnerProvider,
|
|
} from "@paperclipai/adapter-utils";
|
|
import {
|
|
codexCliVersionAtLeast,
|
|
codexLocalReasoningEffortsForModel,
|
|
isCodexLocalKnownModel,
|
|
minimumCodexCliVersionForModel,
|
|
} from "@paperclipai/adapter-codex-local";
|
|
import {
|
|
AGENTCORE_QUALIFIED_MODEL,
|
|
CLAUDE_MANAGED_QUALIFIED_MODEL,
|
|
} from "../provider-profile-qualification.js";
|
|
import { resolveAcpxQualification, resolveAntigravityCandidateAdmission, resolveKimiCandidateAdmission, type AcpxQualificationCandidate } from "./acpx-qualification.js";
|
|
import { compatibleCodexModel } from "./codex-model-fallback.js";
|
|
import {
|
|
claudeCliVersionAtLeast,
|
|
claudeCodeVersionForAgentSdk,
|
|
minimumClaudeCliVersionForModel,
|
|
} from "@paperclipai/adapter-claude-local/server";
|
|
import { parseNativeCursorCloudConfig, type NativeCursorCloudConfig } from "../../vendor/paperclip-runner/index.js";
|
|
|
|
export const QUALIFIED_OPENCODE_RUNNER_VERSION = "1.18.34" as const;
|
|
export const DEFAULT_OPENCODE_RUNNER_MODEL =
|
|
"openrouter/deepseek/deepseek-v4-flash-0731" as const;
|
|
export const CLAUDE_MANAGED_BETA_VERSION = "managed-agents-2026-04-01" as const;
|
|
|
|
export const DEFAULT_ACPX_RUNNER_MODELS = {
|
|
grok: "grok-4.7",
|
|
claude: "claude-opus-5-5",
|
|
// These profiles require explicit configuration. Admission belongs to the runner.
|
|
codex: null,
|
|
cursor: null,
|
|
copilot: null,
|
|
pi: null,
|
|
kimi: null,
|
|
} as const;
|
|
|
|
export type QualifiedPaperclipRunnerAcpxAgent =
|
|
keyof typeof DEFAULT_ACPX_RUNNER_MODELS;
|
|
type AdmittedPaperclipRunnerAcpxAgent = QualifiedPaperclipRunnerAcpxAgent | AcpxQualificationCandidate | "antigravity";
|
|
|
|
export type PaperclipRunnerProviderProfile =
|
|
| { provider: "cursor_cloud"; backend: "cursor_cloud_api"; model: string }
|
|
| { provider: "muse"; backend: "muse_external"; model: null; museBindingId: string }
|
|
| { provider: "grok_bot"; backend: "grok_bot_mcp"; model: null; externalBindingId: string }
|
|
| { provider: "openai_dot"; backend: "openai_dot_mcp"; model: null; dotBindingId: string }
|
|
| {
|
|
provider: "codex";
|
|
backend: "codex_app_server";
|
|
model: string | null;
|
|
}
|
|
| {
|
|
provider: "opencode";
|
|
backend: "opencode_server";
|
|
model: string;
|
|
}
|
|
| {
|
|
provider: "claude_managed";
|
|
backend: "claude_managed_agents_api";
|
|
managedProfileId: string;
|
|
model: string | null;
|
|
maxSessionListCostUsd: number | null;
|
|
}
|
|
| {
|
|
provider: "aws_agentcore";
|
|
backend: "aws_agentcore_harness_api";
|
|
agentCoreProfileId: string;
|
|
model: string | null;
|
|
maxEstimatedSessionCostUsd: number | null;
|
|
}
|
|
| {
|
|
provider: "acpx";
|
|
backend: "acpx_runtime";
|
|
model: string;
|
|
acpxAgent: AdmittedPaperclipRunnerAcpxAgent;
|
|
};
|
|
|
|
export type PaperclipRunnerNativeProviderInput =
|
|
| { provider: "cursor_cloud"; model: string; cursorCloud: NativeCursorCloudConfig }
|
|
| { provider: "muse"; model: null; museBinding: import("../../vendor/paperclip-runner/index.js").MuseBindingSnapshot }
|
|
| { provider: "grok_bot"; model: null; dotBinding: import("../../vendor/paperclip-runner/index.js").DotBindingSnapshot }
|
|
| { provider: "openai_dot"; model: null; dotBinding: import("../../vendor/paperclip-runner/index.js").DotBindingSnapshot }
|
|
| {
|
|
provider: "codex";
|
|
model: string | null;
|
|
homeMode?: "isolated" | "preconfigured";
|
|
codexApprovalPolicy: "never" | "on-request" | "untrusted";
|
|
codexReasoningEffort?: string;
|
|
codexWebSearch?: "disabled";
|
|
}
|
|
| {
|
|
provider: "opencode";
|
|
model: string;
|
|
opencodePermissionMode: "allow" | "ask" | "deny";
|
|
}
|
|
| {
|
|
provider: "claude_managed";
|
|
model: string;
|
|
managedProfile: {
|
|
profileId: string;
|
|
anthropicAgentId: string;
|
|
agentVersion: string;
|
|
environmentId: string;
|
|
betaVersion: typeof CLAUDE_MANAGED_BETA_VERSION;
|
|
};
|
|
maxSessionListCostUsd: number;
|
|
}
|
|
| {
|
|
provider: "aws_agentcore";
|
|
model: string;
|
|
agentCoreProfile: {
|
|
profileId: string;
|
|
region: string;
|
|
accountId: string;
|
|
harnessArn: string;
|
|
harnessVersion: string;
|
|
endpointArn: string;
|
|
endpointQualifier: string;
|
|
agentRuntimeArn: string;
|
|
memoryArn: string;
|
|
memoryId: string;
|
|
invocationRoleArn: string;
|
|
contextBucket: string;
|
|
contextPrefix: string;
|
|
contextKmsKeyArn: string;
|
|
qualificationRevision: string;
|
|
eventExpiryDays: 90;
|
|
};
|
|
maxEstimatedSessionCostUsd: number;
|
|
invocationLimits: {
|
|
maxIterations: number;
|
|
maxOutputTokens: number;
|
|
timeoutSeconds: number;
|
|
};
|
|
}
|
|
| {
|
|
provider: "acpx";
|
|
model: string;
|
|
acpxAgent: AdmittedPaperclipRunnerAcpxAgent;
|
|
homeMode?: "isolated" | "preconfigured";
|
|
acpxPermissionMode: "approve-all" | "approve-paperclip" | "approve-reads" | "deny-all";
|
|
acpxSessionMode?: "agent" | "plan" | "ask";
|
|
piThinkingLevel?: "off" | "low" | "high" | "max";
|
|
claudeEffort?: "low" | "medium" | "high" | "xhigh" | "max";
|
|
grokEffort?: "minimal" | "low" | "medium" | "high" | "xhigh";
|
|
grokDisableWebSearch?: boolean;
|
|
};
|
|
|
|
export class PaperclipRunnerProviderProfileError extends Error {
|
|
constructor(
|
|
readonly code: string,
|
|
message: string,
|
|
) {
|
|
super(message);
|
|
this.name = "PaperclipRunnerProviderProfileError";
|
|
}
|
|
}
|
|
|
|
function asRecord(value: unknown): Record<string, unknown> {
|
|
return typeof value === "object" && value !== null && !Array.isArray(value)
|
|
? value as Record<string, unknown>
|
|
: {};
|
|
}
|
|
|
|
function optionalString(value: unknown): string | null {
|
|
return typeof value === "string" && value.trim().length > 0
|
|
? value.trim()
|
|
: null;
|
|
}
|
|
|
|
export function resolvePaperclipRunnerCursorCloudConfig(config: Record<string, unknown>): NativeCursorCloudConfig {
|
|
const unsupportedEnvironment = Object.keys(asRecord(config.env)).filter(key => key !== "CURSOR_API_KEY");
|
|
if (unsupportedEnvironment.length) {
|
|
throw new PaperclipRunnerProviderProfileError("paperclip_runner_cursor_cloud_config_invalid",
|
|
`Cursor Cloud with Paperclip Runner only supports CURSOR_API_KEY in agent environment settings. Configure hosted secrets in your Cursor Cloud environment instead of ${unsupportedEnvironment.join(", ")}.`);
|
|
}
|
|
for (const [current, legacy] of [["cloudEnvType", "runtimeEnvType"], ["cloudEnvName", "runtimeEnvName"], ["repoRef", "repoStartingRef"], ["prUrl", "repoPullRequestUrl"]]) {
|
|
if (config[current] !== undefined && config[legacy] !== undefined && config[current] !== config[legacy]) {
|
|
throw new PaperclipRunnerProviderProfileError("paperclip_runner_cursor_cloud_config_invalid", `Choose one matching value for ${current} and ${legacy}.`);
|
|
}
|
|
}
|
|
const unsupported = ["codexPermissionMode", "opencodePermissionMode", "acpxPermissionMode", "acpxSessionMode", "command", "extraArgs", "promptTemplate", "bootstrapPromptTemplate", "modelReasoningEffort", "reasoningEffort", "effort", "modelParams", "executionPlacement", "providerApiPlacement", "controllerPlacement", "apiOnly", "cwd", "workspaceRuntime", "workspaceStrategy"]
|
|
.filter(key => config[key] !== undefined && config[key] !== "" && !(Array.isArray(config[key]) && config[key].length === 0));
|
|
if (config.lifecycleMode !== undefined && config.lifecycleMode !== "per_turn") unsupported.push("lifecycleMode");
|
|
if (config.homeMode === "preconfigured") unsupported.push("homeMode");
|
|
if (unsupported.length) throw new PaperclipRunnerProviderProfileError("paperclip_runner_cursor_cloud_config_invalid", `Cursor Cloud cannot honor these settings: ${unsupported.join(", ")}.`);
|
|
const repoUrl = optionalString(config.repoUrl);
|
|
const startingRef = optionalString(config.repoRef ?? config.repoStartingRef);
|
|
const prUrl = optionalString(config.prUrl ?? config.repoPullRequestUrl);
|
|
const envName = optionalString(config.cloudEnvName ?? config.runtimeEnvName);
|
|
try {
|
|
return parseNativeCursorCloudConfig({
|
|
schema: "paperclip.cursor-cloud.config.v1",
|
|
repos: repoUrl ? [{ url: repoUrl, ...(startingRef ? { startingRef } : {}), ...(prUrl ? { prUrl } : {}) }] : [],
|
|
env: { type: config.cloudEnvType ?? config.runtimeEnvType ?? "cloud", ...(envName ? { name: envName } : {}) },
|
|
...Object.fromEntries(["workOnCurrentBranch", "autoCreatePR", "skipReviewerRequest"].filter(key => config[key] !== undefined).map(key => [key, config[key]])),
|
|
...(config.cursorCloudTimeoutMs !== undefined ? { timeoutMs: config.cursorCloudTimeoutMs } : {}),
|
|
});
|
|
} catch {
|
|
throw new PaperclipRunnerProviderProfileError("paperclip_runner_cursor_cloud_config_invalid", "Cursor Cloud requires an HTTPS repository or named Cursor cloud environment, cloud-hosted execution, and supported settings. Its timeout must be between 1 second and 1 hour.");
|
|
}
|
|
}
|
|
|
|
/** Configuration can be saved before pairing; task admission requires a binding. */
|
|
export function validatePaperclipRunnerDotConfig(config: Record<string, unknown>, requireBinding = true): string | null {
|
|
const bindingId = optionalString(config.dotBindingId);
|
|
if ((requireBinding && !bindingId) || (bindingId && !/^[0-9a-f-]{36}$/i.test(bindingId))
|
|
|| config.allowUnmeteredProvider !== true || (config.lifecycleMode && config.lifecycleMode !== "per_turn")
|
|
|| optionalString(config.model)) {
|
|
throw new PaperclipRunnerProviderProfileError("paperclip_runner_dot_config_invalid", "Dot requires per-turn lifecycle and explicit externally billed, unmetered-provider acknowledgement. Pair a binding before assigning work.");
|
|
}
|
|
return bindingId;
|
|
}
|
|
|
|
/** Closed personal runtime configuration; model and workspace grants are excluded. */
|
|
export function validatePaperclipRunnerMuseConfig(config: Record<string, unknown>, requireBinding = true): string | null {
|
|
const bindingId = optionalString(config.museBindingId);
|
|
if ((requireBinding && !bindingId) || (bindingId && !/^[0-9a-f-]{36}$/i.test(bindingId))
|
|
|| config.allowUnmeteredProvider !== true || (config.lifecycleMode && config.lifecycleMode !== "per_turn")
|
|
|| optionalString(config.model) || config.dotWorkspaceAccess === true || config.dotAttachmentAccess === true) {
|
|
throw new PaperclipRunnerProviderProfileError("paperclip_runner_muse_config_invalid", "Muse requires a paired personal-agent binding, per-turn lifecycle and unavailable-usage acknowledgement.");
|
|
}
|
|
return bindingId;
|
|
}
|
|
|
|
export function validatePaperclipRunnerGrokConfig(config: Record<string, unknown>, requireBinding = true): string | null {
|
|
const bindingId = optionalString(config.externalBindingId);
|
|
if ((requireBinding && !bindingId) || (bindingId && !/^[0-9a-f-]{36}$/i.test(bindingId))
|
|
|| config.allowUnmeteredProvider !== true || (config.lifecycleMode && config.lifecycleMode !== "per_turn")
|
|
|| optionalString(config.model) || config.dotWorkspaceAccess === true || config.dotAttachmentAccess === true
|
|
|| optionalString(config.cwd) || optionalString(config.command)) {
|
|
throw new PaperclipRunnerProviderProfileError("paperclip_runner_grok_config_invalid", "Grok Bot requires a bound per-turn work session and an explicit acknowledgement of unreported provider spending. Paperclip workspace, shell and third-party app tools are unavailable.");
|
|
}
|
|
return bindingId;
|
|
}
|
|
|
|
/** A task may change a Runner model (and supported effort), but not provider identity. */
|
|
export function projectPaperclipRunnerTaskConfig(
|
|
backend: "codex_app_server" | "opencode_server" | "acpx_runtime" | "cursor_cloud_api",
|
|
agentConfig: unknown,
|
|
taskOverrides: unknown,
|
|
managedModel?: string,
|
|
): Record<string, unknown> {
|
|
const base = asRecord(agentConfig);
|
|
const task = asRecord(taskOverrides);
|
|
const config = { ...base };
|
|
// The server resolves a connection's model namespace after task overrides.
|
|
// Carry that model into durable input without allowing routing to change the harness.
|
|
const model = optionalString(managedModel) ?? optionalString(task.model);
|
|
const grok = backend === "acpx_runtime" && agentHarnessType("paperclip_runner", base) === "grok_local";
|
|
const supportsEffort = backend === "codex_app_server" || grok || (backend === "acpx_runtime" && agentHarnessType("paperclip_runner", base) === "claude_local");
|
|
const effortKey = supportsEffort
|
|
? ["modelReasoningEffort", "reasoningEffort", "effort"].find((key) => key in task)
|
|
: undefined;
|
|
if (supportsEffort && ((model !== null && model !== optionalString(base.model)) || effortKey !== undefined)) {
|
|
delete config.modelReasoningEffort;
|
|
delete config.reasoningEffort;
|
|
delete config.effort;
|
|
}
|
|
if (model !== null) config.model = model;
|
|
if (effortKey !== undefined) config[grok ? "reasoningEffort" : "modelReasoningEffort"] = task[effortKey];
|
|
return config;
|
|
}
|
|
|
|
function positiveNumberOrNull(
|
|
value: unknown,
|
|
code: string,
|
|
message: string,
|
|
): number | null {
|
|
if (value === undefined || value === null || value === "") return null;
|
|
const parsed = Number(value);
|
|
if (!Number.isFinite(parsed) || parsed <= 0) {
|
|
throw new PaperclipRunnerProviderProfileError(code, message);
|
|
}
|
|
return parsed;
|
|
}
|
|
|
|
function boundedPositiveInteger(
|
|
value: unknown,
|
|
fallback: number,
|
|
maximum: number,
|
|
code: string,
|
|
label: string,
|
|
): number {
|
|
if (value === undefined || value === null || value === "") return fallback;
|
|
if (
|
|
typeof value !== "number"
|
|
|| !Number.isSafeInteger(value)
|
|
|| value <= 0
|
|
|| value > maximum
|
|
) {
|
|
throw new PaperclipRunnerProviderProfileError(
|
|
code,
|
|
`${label} must be an integer between 1 and ${maximum}.`,
|
|
);
|
|
}
|
|
return value;
|
|
}
|
|
|
|
function assertPermissionMode(
|
|
provider: PaperclipRunnerProvider,
|
|
config: Record<string, unknown>,
|
|
): void {
|
|
const capability = PAPERCLIP_RUNNER_PERMISSION_CAPABILITIES[provider];
|
|
if (!capability.configurable) return;
|
|
const configured = config[capability.configKey];
|
|
if (
|
|
configured !== undefined
|
|
&& resolvePaperclipRunnerPermissionMode(provider, configured) !== configured
|
|
) {
|
|
if (provider === "codex") {
|
|
throw new PaperclipRunnerProviderProfileError(
|
|
"paperclip_runner_codex_permission_mode_unqualified",
|
|
"Paperclip Runner currently supports Codex only with codexPermissionMode set to never. Update the agent configuration before starting a new native run.",
|
|
);
|
|
}
|
|
throw new PaperclipRunnerProviderProfileError(
|
|
"runner_permission_mode_invalid",
|
|
`${capability.configKey} is not supported by ${provider}.`,
|
|
);
|
|
}
|
|
}
|
|
|
|
/**
|
|
* Rebind a persisted Claude Managed run only to the still-qualified profile
|
|
* and the profile's current company secret. The secret itself may rotate, but
|
|
* the agent configuration must rotate its binding to the same profile-owned
|
|
* secret before recovery can continue.
|
|
*/
|
|
export function assertManagedProfileRecoveryBinding(input: {
|
|
adapterConfig: unknown;
|
|
snapshot: {
|
|
profileId: string;
|
|
anthropicAgentId: string;
|
|
agentVersion: string;
|
|
environmentId: string;
|
|
betaVersion: string;
|
|
};
|
|
stored: {
|
|
id: string;
|
|
anthropicAgentId: string;
|
|
agentVersion: string;
|
|
environmentId: string;
|
|
betaVersion: string;
|
|
apiKeySecretId: string;
|
|
};
|
|
}): void {
|
|
const { snapshot, stored } = input;
|
|
if (
|
|
snapshot.profileId !== stored.id
|
|
|| snapshot.anthropicAgentId !== stored.anthropicAgentId
|
|
|| snapshot.agentVersion !== stored.agentVersion
|
|
|| snapshot.environmentId !== stored.environmentId
|
|
|| snapshot.betaVersion !== stored.betaVersion
|
|
) {
|
|
throw new PaperclipRunnerProviderProfileError(
|
|
"paperclip_runner_claude_managed_recovery_identity_mismatch",
|
|
"The persisted Claude Managed identity no longer matches its qualified profile.",
|
|
);
|
|
}
|
|
const rawBinding = asRecord(asRecord(input.adapterConfig).env).ANTHROPIC_API_KEY;
|
|
const boundSecretId = asRecord(rawBinding).secretId;
|
|
if (boundSecretId !== stored.apiKeySecretId) {
|
|
throw new PaperclipRunnerProviderProfileError(
|
|
"paperclip_runner_claude_managed_recovery_secret_mismatch",
|
|
"The persisted Claude Managed run is not bound to its profile's current API-key secret.",
|
|
);
|
|
}
|
|
}
|
|
|
|
/** Revalidate the operator's AWS profile revocation and immutable identity on recovery. */
|
|
export function assertAgentCoreProfileRecoveryBinding(input: {
|
|
snapshot: {
|
|
profileId: string;
|
|
region: string;
|
|
accountId: string;
|
|
harnessArn: string;
|
|
harnessVersion: string;
|
|
endpointArn: string;
|
|
endpointQualifier: string;
|
|
agentRuntimeArn: string;
|
|
memoryArn: string;
|
|
memoryId: string;
|
|
invocationRoleArn: string;
|
|
contextBucket: string;
|
|
contextPrefix: string;
|
|
contextKmsKeyArn: string;
|
|
qualificationRevision: string;
|
|
eventExpiryDays: number;
|
|
};
|
|
stored: {
|
|
id: string;
|
|
configuration: Record<string, unknown>;
|
|
};
|
|
}): void {
|
|
const { snapshot, stored } = input;
|
|
const configuration = asRecord(stored.configuration);
|
|
const fields = [
|
|
"region",
|
|
"accountId",
|
|
"harnessArn",
|
|
"harnessVersion",
|
|
"endpointArn",
|
|
"endpointQualifier",
|
|
"agentRuntimeArn",
|
|
"memoryArn",
|
|
"memoryId",
|
|
"invocationRoleArn",
|
|
"contextBucket",
|
|
"contextPrefix",
|
|
"contextKmsKeyArn",
|
|
"qualificationRevision",
|
|
"eventExpiryDays",
|
|
] as const;
|
|
if (
|
|
snapshot.profileId !== stored.id
|
|
|| fields.some((field) => snapshot[field] !== configuration[field])
|
|
) {
|
|
throw new PaperclipRunnerProviderProfileError(
|
|
"paperclip_runner_aws_agentcore_recovery_identity_mismatch",
|
|
"The persisted AWS AgentCore identity no longer matches its qualified profile.",
|
|
);
|
|
}
|
|
}
|
|
|
|
export function claudeRunnerUnsupportedSettings(config: Record<string, unknown>): string[] {
|
|
config = normalizeClaudeRunnerOptions(config).config;
|
|
const unsupported = ["chrome", "agentCommand", "acpAgentCommand", "stateDir", "acpStateDir", "warmHandleIdleMs", "acpWarmHandleIdleMs", "extraArgs", "args", "filesystemScope", "filesystemExtraPaths", "filesystemSandboxCommand", "networkScope", "networkAllowlist", "maxTurnsPerRun", "permissionMode", "acpPermissionMode"]
|
|
.filter(key => config[key] !== undefined && config[key] !== false && config[key] !== "" && config[key] !== 0 && !(Array.isArray(config[key]) && config[key].length === 0));
|
|
if (config.command && config.command !== "claude") unsupported.push("command");
|
|
if (config.mode && config.mode !== "persistent") unsupported.push("mode");
|
|
if (config.acpMode && config.acpMode !== "persistent") unsupported.push("acpMode");
|
|
if (config.engine && !["auto", "cli", "acp"].includes(String(config.engine))) unsupported.push("engine");
|
|
if (config.nonInteractivePermissions && config.nonInteractivePermissions !== "deny") unsupported.push("nonInteractivePermissions");
|
|
if (config.acpNonInteractivePermissions && config.acpNonInteractivePermissions !== "deny") unsupported.push("acpNonInteractivePermissions");
|
|
if (config.dangerouslySkipPermissions === false) unsupported.push("dangerouslySkipPermissions");
|
|
return unsupported;
|
|
}
|
|
|
|
/**
|
|
* Resolve the immutable provider identity used for a fresh Paperclip Runner
|
|
* selection. The persisted adapterConfig is the authority; runtimeConfig is
|
|
* deliberately not consulted so model-profile or migration metadata cannot
|
|
* silently switch the harness selected for a run.
|
|
*/
|
|
export function resolvePaperclipRunnerProviderProfile(
|
|
adapterConfig: unknown,
|
|
context: { companyId?: string } = {},
|
|
): PaperclipRunnerProviderProfile {
|
|
const config = asRecord(adapterConfig);
|
|
const candidate = config.provider ?? "codex";
|
|
if (!isPaperclipRunnerProvider(candidate)) {
|
|
throw new PaperclipRunnerProviderProfileError(
|
|
"paperclip_runner_provider_unsupported",
|
|
"Paperclip Runner provider must be Codex, OpenCode, Claude Managed, AWS AgentCore, or ACPX.",
|
|
);
|
|
}
|
|
|
|
if (candidate === "cursor_cloud") {
|
|
const model = optionalString(config.model);
|
|
if (!model) throw new PaperclipRunnerProviderProfileError("paperclip_runner_cursor_cloud_model_required", "Cursor Cloud requires an explicit model. Select a model before testing or assigning work.");
|
|
resolvePaperclipRunnerCursorCloudConfig(config);
|
|
return { provider: "cursor_cloud", backend: "cursor_cloud_api", model };
|
|
}
|
|
|
|
if (candidate === "muse") {
|
|
const bindingId = validatePaperclipRunnerMuseConfig(config)!;
|
|
return { provider: "muse", backend: "muse_external", model: null, museBindingId: bindingId };
|
|
}
|
|
if (candidate === "grok_bot") {
|
|
return { provider: "grok_bot", backend: "grok_bot_mcp", model: null, externalBindingId: validatePaperclipRunnerGrokConfig(config)! };
|
|
}
|
|
if (candidate === "openai_dot") {
|
|
const bindingId = validatePaperclipRunnerDotConfig(config)!;
|
|
return { provider: "openai_dot", backend: "openai_dot_mcp", model: null, dotBindingId: bindingId };
|
|
}
|
|
if (candidate === "acpx" && agentHarnessType("paperclip_runner", config) === "claude_local") {
|
|
const unsupported = claudeRunnerUnsupportedSettings(config);
|
|
if (unsupported.length) throw new PaperclipRunnerProviderProfileError("agent_runner_config_incompatible",
|
|
`Paperclip Runner cannot honor these settings: ${unsupported.join(", ")}. Remove them before retrying.`);
|
|
}
|
|
assertPermissionMode(candidate, config);
|
|
try {
|
|
resolvePaperclipRunnerCursorMode(candidate, config.acpxAgent, config.acpxSessionMode);
|
|
} catch (error) {
|
|
throw new PaperclipRunnerProviderProfileError(
|
|
"paperclip_runner_mode_invalid",
|
|
error instanceof Error ? error.message : "Invalid Cursor session mode",
|
|
);
|
|
}
|
|
try { if (candidate === "acpx" && agentHarnessType("paperclip_runner", config) === "claude_local") resolveClaudeEffort("claude", config.modelReasoningEffort ?? config.reasoningEffort ?? config.effort); } catch (error) {
|
|
throw new PaperclipRunnerProviderProfileError("paperclip_runner_claude_effort_invalid", error instanceof Error ? error.message : "Invalid Claude effort");
|
|
}
|
|
try { if (candidate === "acpx" && config.acpxAgent === "grok") resolveGrokEffort("grok", config.modelReasoningEffort ?? config.reasoningEffort ?? config.effort); } catch (error) {
|
|
throw new PaperclipRunnerProviderProfileError("paperclip_runner_grok_effort_invalid", error instanceof Error ? error.message : "Invalid Grok effort");
|
|
}
|
|
try { if (candidate === "acpx" && config.acpxAgent === "grok") resolveGrokDisableWebSearch("grok", config.disableWebSearch); } catch (error) {
|
|
throw new PaperclipRunnerProviderProfileError("paperclip_runner_grok_search_invalid", error instanceof Error ? error.message : "Invalid Grok search policy");
|
|
}
|
|
try { resolvePaperclipRunnerPiThinkingLevel(candidate, config.acpxAgent, config.piThinkingLevel); } catch (error) {
|
|
throw new PaperclipRunnerProviderProfileError("paperclip_runner_pi_thinking_invalid", error instanceof Error ? error.message : "Invalid Pi thinking level");
|
|
}
|
|
const model = optionalString(config.model);
|
|
if (candidate === "codex") {
|
|
return {
|
|
provider: "codex",
|
|
backend: "codex_app_server",
|
|
model,
|
|
};
|
|
}
|
|
|
|
if (candidate === "opencode") {
|
|
if (!model || !model.includes("/") || model.endsWith("/")) {
|
|
throw new PaperclipRunnerProviderProfileError(
|
|
"paperclip_runner_opencode_model_invalid",
|
|
"Paperclip Runner OpenCode requires model in provider/model form.",
|
|
);
|
|
}
|
|
return {
|
|
provider: "opencode",
|
|
backend: "opencode_server",
|
|
model,
|
|
};
|
|
}
|
|
|
|
if (candidate === "claude_managed") {
|
|
const managedProfileId = optionalString(config.managedProfileId);
|
|
if (!managedProfileId) {
|
|
throw new PaperclipRunnerProviderProfileError(
|
|
"paperclip_runner_claude_managed_profile_required",
|
|
"Paperclip Runner Claude Managed requires a company managed-agent profile.",
|
|
);
|
|
}
|
|
if (config.managedAgentsRetentionAcknowledged !== true) {
|
|
throw new PaperclipRunnerProviderProfileError(
|
|
"paperclip_runner_claude_managed_retention_required",
|
|
"Paperclip Runner Claude Managed requires acknowledgement of stateful beta retention.",
|
|
);
|
|
}
|
|
if (model !== null && model !== CLAUDE_MANAGED_QUALIFIED_MODEL) {
|
|
throw new PaperclipRunnerProviderProfileError(
|
|
"paperclip_runner_claude_managed_model_unqualified",
|
|
`The Claude Managed profile requires exact model ${CLAUDE_MANAGED_QUALIFIED_MODEL}.`,
|
|
);
|
|
}
|
|
return {
|
|
provider: "claude_managed",
|
|
backend: "claude_managed_agents_api",
|
|
managedProfileId,
|
|
model,
|
|
maxSessionListCostUsd: positiveNumberOrNull(
|
|
config.maxSessionListCostUsd,
|
|
"paperclip_runner_claude_managed_spend_cap_invalid",
|
|
"Paperclip Runner Claude Managed requires a positive session spend ceiling when overridden.",
|
|
),
|
|
};
|
|
}
|
|
|
|
if (candidate === "aws_agentcore") {
|
|
const agentCoreProfileId = optionalString(config.agentCoreProfileId);
|
|
if (!agentCoreProfileId) {
|
|
throw new PaperclipRunnerProviderProfileError(
|
|
"paperclip_runner_aws_agentcore_profile_required",
|
|
"Paperclip Runner AWS AgentCore requires a company remote-agent profile.",
|
|
);
|
|
}
|
|
if (config.agentCoreRetentionAcknowledged !== true) {
|
|
throw new PaperclipRunnerProviderProfileError(
|
|
"paperclip_runner_aws_agentcore_retention_required",
|
|
"Paperclip Runner AWS AgentCore requires acknowledgement of 90-day Memory retention.",
|
|
);
|
|
}
|
|
if (model !== null && model !== AGENTCORE_QUALIFIED_MODEL) {
|
|
throw new PaperclipRunnerProviderProfileError(
|
|
"paperclip_runner_aws_agentcore_model_unqualified",
|
|
`The AWS AgentCore profile requires exact model ${AGENTCORE_QUALIFIED_MODEL}.`,
|
|
);
|
|
}
|
|
return {
|
|
provider: "aws_agentcore",
|
|
backend: "aws_agentcore_harness_api",
|
|
agentCoreProfileId,
|
|
model,
|
|
maxEstimatedSessionCostUsd: positiveNumberOrNull(
|
|
config.maxEstimatedSessionCostUsd,
|
|
"paperclip_runner_aws_agentcore_spend_cap_invalid",
|
|
"Paperclip Runner AWS AgentCore requires a positive estimated session spend ceiling when overridden.",
|
|
),
|
|
};
|
|
}
|
|
|
|
const acpxAgent = config.acpxAgent ?? "claude";
|
|
if (acpxAgent === "copilot" && (!model || ["auto", "default"].includes(model.toLowerCase()))) {
|
|
throw new PaperclipRunnerProviderProfileError("paperclip_runner_acpx_model_required", "GitHub Copilot requires an explicit model ID; there is no default model.");
|
|
}
|
|
const pendingAcpxProfile = PAPERCLIP_RUNNER_ACPX_PROFILES.find(profile => profile.value === acpxAgent && !profile.qualified);
|
|
if (pendingAcpxProfile) {
|
|
if (!model) throw new PaperclipRunnerProviderProfileError("paperclip_runner_acpx_model_required", `${pendingAcpxProfile.label} requires an explicit model ID; there is no default model.`);
|
|
if (pendingAcpxProfile.value === "antigravity") {
|
|
try {
|
|
if (resolveAntigravityCandidateAdmission({ companyId: context.companyId, model }, process.env)) {
|
|
return { provider: "acpx", backend: "acpx_runtime", model, acpxAgent: "antigravity" };
|
|
}
|
|
} catch {
|
|
throw new PaperclipRunnerProviderProfileError("paperclip_runner_acpx_qualification_invalid", "Antigravity candidate admission requires the authorized company, exact model and runtime identity.");
|
|
}
|
|
}
|
|
if (pendingAcpxProfile.value === "kimi") {
|
|
try {
|
|
if (resolveKimiCandidateAdmission({ companyId: context.companyId, model }, process.env)) {
|
|
return { provider: "acpx", backend: "acpx_runtime", model, acpxAgent: "kimi" };
|
|
}
|
|
} catch {
|
|
throw new PaperclipRunnerProviderProfileError("paperclip_runner_acpx_qualification_invalid", "Kimi candidate admission requires the authorized company, exact model, target and runtime identity.");
|
|
}
|
|
}
|
|
// Qualification authority belongs to the isolated server operator. Never
|
|
// read this allowlist from adapter config, credential refs, or run env.
|
|
let qualification: AcpxQualificationCandidate | undefined;
|
|
try {
|
|
qualification = resolveAcpxQualification({ kind: "acpx", agent: pendingAcpxProfile.value, model }, process.env);
|
|
} catch {
|
|
throw new PaperclipRunnerProviderProfileError("paperclip_runner_acpx_qualification_invalid", "ACPX qualification requires an exact host-authorized candidate and model.");
|
|
}
|
|
if (qualification) {
|
|
return { provider: "acpx", backend: "acpx_runtime", model, acpxAgent: qualification };
|
|
}
|
|
throw new PaperclipRunnerProviderProfileError("paperclip_runner_acpx_agent_unavailable", `${pendingAcpxProfile.label} is awaiting native Runner acceptance. Its profile is not enabled for production runs.`);
|
|
}
|
|
if ((acpxAgent === "cursor" || acpxAgent === "pi" || acpxAgent === "kimi") && !model) {
|
|
throw new PaperclipRunnerProviderProfileError("paperclip_runner_acpx_model_required", "This ACPX agent requires an explicit model ID; there is no default model.");
|
|
}
|
|
if (acpxAgent !== "claude" && acpxAgent !== "codex" && acpxAgent !== "grok" && acpxAgent !== "cursor" && acpxAgent !== "copilot" && acpxAgent !== "pi" && acpxAgent !== "kimi") {
|
|
throw new PaperclipRunnerProviderProfileError(
|
|
"paperclip_runner_acpx_agent_unavailable",
|
|
"Paperclip Runner ACPX requires a qualified agent profile.",
|
|
);
|
|
}
|
|
const selectedModel = acpxAgent === "grok" && model === "grok-build"
|
|
? DEFAULT_ACPX_RUNNER_MODELS.grok
|
|
: model || DEFAULT_ACPX_RUNNER_MODELS[acpxAgent] || "";
|
|
let qualifiedProfile: ReturnType<typeof resolveQualifiedAcpxProfile>;
|
|
try {
|
|
qualifiedProfile = resolveQualifiedAcpxProfile(acpxAgent, selectedModel);
|
|
} catch (error) {
|
|
throw new PaperclipRunnerProviderProfileError(
|
|
"paperclip_runner_acpx_model_unqualified",
|
|
error instanceof Error ? error.message : "Paperclip Runner ACPX requires an admitted model.",
|
|
);
|
|
}
|
|
if (acpxAgent === "claude") {
|
|
// The provider pack runs the Claude Code its Agent SDK bundles; name the gap instead of
|
|
// letting an older CLI fail the turn with an opaque backend error.
|
|
const minimum = minimumClaudeCliVersionForModel(selectedModel);
|
|
const bundled = claudeCodeVersionForAgentSdk(qualifiedProfile.agentRuntimeVersion);
|
|
if (minimum && bundled && !claudeCliVersionAtLeast(bundled, minimum)) {
|
|
throw new PaperclipRunnerProviderProfileError(
|
|
"paperclip_runner_claude_cli_version_incompatible",
|
|
`${selectedModel} requires Claude Code ${minimum} or newer; this Paperclip Runner bundles Claude Code ${bundled}. Choose another model or use the legacy Claude runner until the Runner is updated.`,
|
|
);
|
|
}
|
|
}
|
|
if (acpxAgent === "codex") {
|
|
// ACPX Codex runs the qualified runtime pin, so the backend would reject a newer model.
|
|
const minimum = minimumCodexCliVersionForModel(selectedModel);
|
|
const bundled = qualifiedProfile.agentRuntimeVersion;
|
|
if (minimum && bundled && !codexCliVersionAtLeast(bundled, minimum)) {
|
|
throw new PaperclipRunnerProviderProfileError(
|
|
"paperclip_runner_codex_cli_version_incompatible",
|
|
`${selectedModel} requires Codex ${minimum} or newer; this Paperclip Runner bundles Codex ${bundled}. Choose another model or use the legacy Codex runner until the Runner is updated.`,
|
|
);
|
|
}
|
|
}
|
|
return {
|
|
provider: "acpx",
|
|
backend: "acpx_runtime",
|
|
model: selectedModel,
|
|
acpxAgent,
|
|
};
|
|
}
|
|
|
|
export function supportsPaperclipRunnerPreconfiguredHome(adapterConfig: unknown, options: { companyId?: string } = {}): boolean {
|
|
const config = asRecord(adapterConfig);
|
|
const profile = resolvePaperclipRunnerProviderProfile(config, options);
|
|
return profile.provider === "codex" || (profile.provider === "acpx" && profile.acpxAgent === "claude"
|
|
&& (config.acpxPermissionMode === undefined || config.acpxPermissionMode === "approve-all"));
|
|
}
|
|
|
|
/**
|
|
* Project the operator-owned adapter configuration and a qualified stored
|
|
* profile into the closed native execution descriptor. Editable adapter
|
|
* configuration can select a stored profile, but it cannot replace that
|
|
* profile's immutable remote resource identity.
|
|
*/
|
|
export function resolvePaperclipRunnerNativeProviderInput(input: {
|
|
companyId?: string;
|
|
backend: PaperclipRunnerProviderProfile["backend"];
|
|
adapterConfig: unknown;
|
|
/** Verified image CLI version for a fresh remote Codex run only. */
|
|
codexCliVersion?: string | null;
|
|
museBinding?: import("../../vendor/paperclip-runner/index.js").MuseBindingSnapshot;
|
|
dotBinding?: import("../../vendor/paperclip-runner/index.js").DotBindingSnapshot;
|
|
managedProfile?: {
|
|
id: string;
|
|
profileKey: string;
|
|
anthropicAgentId: string;
|
|
agentVersion: string;
|
|
environmentId: string;
|
|
betaVersion: string;
|
|
defaultModel: string;
|
|
defaultMaxListCostCents: number;
|
|
} | null;
|
|
agentCoreProfile?: {
|
|
id: string;
|
|
profileKey: string;
|
|
configuration: Record<string, unknown>;
|
|
} | null;
|
|
}): PaperclipRunnerNativeProviderInput {
|
|
const config = asRecord(input.adapterConfig);
|
|
const profile = resolvePaperclipRunnerProviderProfile(config, { companyId: input.companyId });
|
|
if (config.homeMode !== undefined && config.homeMode !== "isolated" && config.homeMode !== "preconfigured") {
|
|
throw new PaperclipRunnerProviderProfileError("paperclip_runner_home_mode_invalid", "homeMode must be isolated or preconfigured");
|
|
}
|
|
const preconfigured = config.homeMode === "preconfigured";
|
|
if (preconfigured && profile.provider !== "codex" && !(profile.provider === "acpx" && ["claude", "codex"].includes(profile.acpxAgent))) {
|
|
throw new PaperclipRunnerProviderProfileError("paperclip_runner_home_mode_unsupported", "Preconfigured home supports native Codex and ACPX Claude only");
|
|
}
|
|
if (preconfigured && profile.provider === "acpx" && config.acpxPermissionMode !== undefined && config.acpxPermissionMode !== "approve-all") {
|
|
throw new PaperclipRunnerProviderProfileError("paperclip_runner_home_permission_mode_unsupported", "Preconfigured home currently requires ACPX approve-all; local permission rules still apply");
|
|
}
|
|
if (preconfigured && profile.provider === "acpx" && profile.acpxAgent === "codex") {
|
|
throw new PaperclipRunnerProviderProfileError("paperclip_runner_home_state_boundary_unsupported", "preconfigured ACPX Codex cannot protect Runner state; use native Codex or isolated mode");
|
|
}
|
|
if (profile.backend !== input.backend) {
|
|
throw new PaperclipRunnerProviderProfileError(
|
|
"paperclip_runner_provider_changed",
|
|
"Paperclip Runner provider changed after this run selected its native backend.",
|
|
);
|
|
}
|
|
if (profile.provider === "cursor_cloud") {
|
|
return { provider: "cursor_cloud", model: profile.model, cursorCloud: resolvePaperclipRunnerCursorCloudConfig(config) };
|
|
}
|
|
if (profile.provider === "muse") {
|
|
if (!input.museBinding || input.museBinding.bindingId !== profile.museBindingId) throw new PaperclipRunnerProviderProfileError("paperclip_runner_muse_binding_unavailable", "Muse binding must be resolved by the server after normal admission.");
|
|
return { provider: "muse", model: null, museBinding: input.museBinding };
|
|
}
|
|
if (profile.provider === "grok_bot") {
|
|
if (!input.dotBinding || input.dotBinding.bindingId !== profile.externalBindingId) throw new PaperclipRunnerProviderProfileError("paperclip_runner_grok_binding_unavailable", "The Grok binding must be resolved by the server after normal admission.");
|
|
return { provider: "grok_bot", model: null, dotBinding: input.dotBinding };
|
|
}
|
|
if (profile.provider === "openai_dot") {
|
|
if (!input.dotBinding || input.dotBinding.bindingId !== profile.dotBindingId) throw new PaperclipRunnerProviderProfileError("paperclip_runner_dot_binding_unavailable", "Dot binding must be resolved by the server after normal admission.");
|
|
return { provider: "openai_dot", model: null, dotBinding: input.dotBinding };
|
|
}
|
|
if (profile.provider === "opencode") {
|
|
return {
|
|
provider: "opencode",
|
|
model: profile.model,
|
|
opencodePermissionMode: resolvePaperclipRunnerPermissionMode(
|
|
"opencode",
|
|
config.opencodePermissionMode,
|
|
) as "allow" | "ask" | "deny",
|
|
};
|
|
}
|
|
if (profile.provider === "acpx") {
|
|
return {
|
|
provider: "acpx",
|
|
model: profile.model,
|
|
acpxAgent: profile.acpxAgent,
|
|
...(profile.acpxAgent === "claude" ? { claudeEffort: resolveClaudeEffort("claude", config.modelReasoningEffort ?? config.reasoningEffort ?? config.effort) } : {}),
|
|
...(profile.acpxAgent === "grok" ? { grokEffort: resolveGrokEffort("grok", config.modelReasoningEffort ?? config.reasoningEffort ?? config.effort), grokDisableWebSearch: resolveGrokDisableWebSearch("grok", config.disableWebSearch) } : {}),
|
|
...(profile.acpxAgent === "pi" ? { piThinkingLevel: resolvePaperclipRunnerPiThinkingLevel("acpx", "pi", config.piThinkingLevel) } : {}),
|
|
...(profile.acpxAgent === "cursor" ? {
|
|
acpxSessionMode: resolvePaperclipRunnerCursorMode("acpx", "cursor", config.acpxSessionMode),
|
|
} : {}),
|
|
...(preconfigured ? { homeMode: "preconfigured" as const } : {}),
|
|
acpxPermissionMode: resolvePaperclipRunnerPermissionMode(
|
|
"acpx",
|
|
config.acpxPermissionMode,
|
|
) as "approve-all" | "approve-paperclip" | "approve-reads" | "deny-all",
|
|
};
|
|
}
|
|
if (profile.provider === "claude_managed") {
|
|
const stored = input.managedProfile;
|
|
if (
|
|
!stored
|
|
|| (
|
|
profile.managedProfileId !== stored.id
|
|
&& profile.managedProfileId !== stored.profileKey
|
|
)
|
|
) {
|
|
throw new PaperclipRunnerProviderProfileError(
|
|
"paperclip_runner_claude_managed_profile_mismatch",
|
|
"The qualified Claude Managed profile does not match the adapter selection.",
|
|
);
|
|
}
|
|
if (stored.betaVersion !== CLAUDE_MANAGED_BETA_VERSION) {
|
|
throw new PaperclipRunnerProviderProfileError(
|
|
"paperclip_runner_claude_managed_beta_unqualified",
|
|
"The Claude Managed profile beta version is not qualified.",
|
|
);
|
|
}
|
|
const model = profile.model ?? optionalString(stored.defaultModel);
|
|
const maxSessionListCostUsd = profile.maxSessionListCostUsd
|
|
?? stored.defaultMaxListCostCents / 100;
|
|
if (!model) {
|
|
throw new PaperclipRunnerProviderProfileError(
|
|
"paperclip_runner_claude_managed_model_invalid",
|
|
"The Claude Managed profile requires a model.",
|
|
);
|
|
}
|
|
if (model !== CLAUDE_MANAGED_QUALIFIED_MODEL) {
|
|
throw new PaperclipRunnerProviderProfileError(
|
|
"paperclip_runner_claude_managed_model_unqualified",
|
|
`The Claude Managed profile requires exact model ${CLAUDE_MANAGED_QUALIFIED_MODEL}.`,
|
|
);
|
|
}
|
|
if (!Number.isFinite(maxSessionListCostUsd) || maxSessionListCostUsd <= 0) {
|
|
throw new PaperclipRunnerProviderProfileError(
|
|
"paperclip_runner_claude_managed_spend_cap_invalid",
|
|
"The Claude Managed profile requires a positive session spend ceiling.",
|
|
);
|
|
}
|
|
return {
|
|
provider: "claude_managed",
|
|
model,
|
|
managedProfile: {
|
|
profileId: stored.id,
|
|
anthropicAgentId: stored.anthropicAgentId,
|
|
agentVersion: stored.agentVersion,
|
|
environmentId: stored.environmentId,
|
|
betaVersion: CLAUDE_MANAGED_BETA_VERSION,
|
|
},
|
|
maxSessionListCostUsd,
|
|
};
|
|
}
|
|
if (profile.provider === "aws_agentcore") {
|
|
const stored = input.agentCoreProfile;
|
|
if (
|
|
!stored
|
|
|| (
|
|
profile.agentCoreProfileId !== stored.id
|
|
&& profile.agentCoreProfileId !== stored.profileKey
|
|
)
|
|
) {
|
|
throw new PaperclipRunnerProviderProfileError(
|
|
"paperclip_runner_aws_agentcore_profile_mismatch",
|
|
"The qualified AWS AgentCore profile does not match the adapter selection.",
|
|
);
|
|
}
|
|
const remote = asRecord(stored.configuration);
|
|
const required = (key: string): string => {
|
|
const value = optionalString(remote[key]);
|
|
if (!value) {
|
|
throw new PaperclipRunnerProviderProfileError(
|
|
"paperclip_runner_aws_agentcore_profile_invalid",
|
|
`The qualified AWS AgentCore profile is missing ${key}.`,
|
|
);
|
|
}
|
|
return value;
|
|
};
|
|
if (remote.eventExpiryDays !== 90) {
|
|
throw new PaperclipRunnerProviderProfileError(
|
|
"paperclip_runner_aws_agentcore_retention_unqualified",
|
|
"The qualified AWS AgentCore profile must retain Memory events for exactly 90 days.",
|
|
);
|
|
}
|
|
const maxEstimatedSessionCostUsd = profile.maxEstimatedSessionCostUsd
|
|
?? positiveNumberOrNull(
|
|
remote.defaultMaxEstimatedSessionCostUsd,
|
|
"paperclip_runner_aws_agentcore_spend_cap_invalid",
|
|
"The AWS AgentCore profile requires a positive estimated session spend ceiling.",
|
|
);
|
|
if (maxEstimatedSessionCostUsd === null) {
|
|
throw new PaperclipRunnerProviderProfileError(
|
|
"paperclip_runner_aws_agentcore_spend_cap_invalid",
|
|
"The AWS AgentCore profile requires a positive estimated session spend ceiling.",
|
|
);
|
|
}
|
|
const model = profile.model ?? required("defaultModel");
|
|
if (model !== AGENTCORE_QUALIFIED_MODEL) {
|
|
throw new PaperclipRunnerProviderProfileError(
|
|
"paperclip_runner_aws_agentcore_model_unqualified",
|
|
`The AWS AgentCore profile requires exact model ${AGENTCORE_QUALIFIED_MODEL}.`,
|
|
);
|
|
}
|
|
return {
|
|
provider: "aws_agentcore",
|
|
model,
|
|
agentCoreProfile: {
|
|
profileId: stored.id,
|
|
region: required("region"),
|
|
accountId: required("accountId"),
|
|
harnessArn: required("harnessArn"),
|
|
harnessVersion: required("harnessVersion"),
|
|
endpointArn: required("endpointArn"),
|
|
endpointQualifier: required("endpointQualifier"),
|
|
agentRuntimeArn: required("agentRuntimeArn"),
|
|
memoryArn: required("memoryArn"),
|
|
memoryId: required("memoryId"),
|
|
invocationRoleArn: required("invocationRoleArn"),
|
|
contextBucket: required("contextBucket"),
|
|
contextPrefix: required("contextPrefix"),
|
|
contextKmsKeyArn: required("contextKmsKeyArn"),
|
|
qualificationRevision: required("qualificationRevision"),
|
|
eventExpiryDays: 90,
|
|
},
|
|
maxEstimatedSessionCostUsd,
|
|
invocationLimits: {
|
|
maxIterations: boundedPositiveInteger(
|
|
config.maxIterations,
|
|
8,
|
|
8,
|
|
"paperclip_runner_aws_agentcore_max_iterations_invalid",
|
|
"AWS AgentCore maxIterations",
|
|
),
|
|
maxOutputTokens: boundedPositiveInteger(
|
|
config.maxOutputTokens,
|
|
4_096,
|
|
4_096,
|
|
"paperclip_runner_aws_agentcore_max_output_tokens_invalid",
|
|
"AWS AgentCore maxOutputTokens",
|
|
),
|
|
timeoutSeconds: boundedPositiveInteger(
|
|
config.timeoutSeconds,
|
|
300,
|
|
300,
|
|
"paperclip_runner_aws_agentcore_timeout_invalid",
|
|
"AWS AgentCore timeoutSeconds",
|
|
),
|
|
},
|
|
};
|
|
}
|
|
const effort = config.modelReasoningEffort ?? config.reasoningEffort ?? config.effort;
|
|
const allowedEfforts = ["minimal", "low", "medium", "high", "xhigh", "max", "ultra"];
|
|
if (effort !== undefined && effort !== null && effort !== "" && (
|
|
typeof effort !== "string" || !allowedEfforts.includes(effort)
|
|
|| (profile.model && isCodexLocalKnownModel(profile.model)
|
|
&& !codexLocalReasoningEffortsForModel(profile.model).includes(effort as "minimal" | "low" | "medium" | "high" | "xhigh" | "max" | "ultra"))
|
|
)) {
|
|
throw new PaperclipRunnerProviderProfileError(
|
|
"paperclip_runner_codex_effort_invalid",
|
|
"Paperclip Runner Codex reasoning effort is not supported for this model.",
|
|
);
|
|
}
|
|
return {
|
|
provider: "codex",
|
|
model: compatibleCodexModel(profile.model, input.codexCliVersion ?? null),
|
|
...(preconfigured ? { homeMode: "preconfigured" as const } : {}),
|
|
codexApprovalPolicy: resolvePaperclipRunnerPermissionMode(
|
|
"codex",
|
|
config.codexPermissionMode,
|
|
) as "never" | "on-request" | "untrusted",
|
|
...(typeof effort === "string" && effort ? { codexReasoningEffort: effort } : {}),
|
|
...(config.search === false ? { codexWebSearch: "disabled" as const } : {}),
|
|
};
|
|
}
|