Files
PaperClipAI/server/src/services/native-runtime/provider-profile.ts
T
eaac8ed0f7 feat(adapters): add Claude Fable 5.2 and GPT-6.2 with CLI floors, and refresh sandbox CLI pins (Nov 18 audit) (#22222)
## 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>
2026-11-18 14:27:00 -08:00

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 } : {}),
};
}