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. > - Paperclip Runner runs Claude and Codex agents from one shared provider pack. The pack pins an exact Claude Agent SDK (which bundles Claude Code) and an exact Codex CLI. > - #22222 added Claude Fable 5.2 (minimum Claude Code 2.1.321) and GPT-6.2 Sol and Astra (minimum Codex 0.169.1). The pack still bundles Claude Code 2.1.286 and Codex 0.160.0. > - Because of this, Paperclip Runner stops these models with a named version error, and native remote Codex accepts only `>=0.149.0 <0.161.0`. > - This pull request moves the provider pack to Agent SDK 0.3.328 (Claude Code 2.1.328) and Codex 0.170.0. It moves every constant that depends on these pins, and the remote Codex window to `<0.171.0`. > - The benefit is that Fable 5.2 and GPT-6.2 run on Paperclip Runner after a sandbox image with this pack is promoted. ## Linked Issues or Issue Description Refs #22222 (adds the models and the version floors; this pull request makes them runnable on Paperclip Runner). Refs #18488 (moves only the Codex pin to 0.166.0 and the window to `<0.167.0`; it is not updated since November 1 and has conflicts with `master`). Refs #18486 (GPT-6.1 Terra needs Codex 0.165.0; Codex 0.170.0 satisfies it). **Overlap with #18488.** #18488 changes the same Codex pin locations. This pull request uses a newer pin (0.170.0) and also moves the Claude runtime. If this pull request merges first, #18488 has no remaining change. I did not change the #18488 branch. ## What Changed - Claude runtime: `@anthropic-ai/claude-agent-sdk` 0.3.286 → 0.3.328 (Claude Code 2.1.286 → 2.1.328). This changes the root `pnpm.overrides`, `pnpm-workspace.yaml`, the ACPX `claude` profile, and the qualified Claude runtime in `installation-integrity.ts`, with new executable digests for Linux x64, Linux ARM64, macOS ARM64, and macOS x64. - Codex runtime: `@openai/codex` 0.160.0 → 0.170.0. This changes the runner dependency, the `codex-acp@1.6.2>@openai/codex` override, the `codex-acp` patch dependency line, the ACPX `codex` profile, and the qualified Linux x64 runtime with its new executable digest. - The ACP bridges do not change: `claude-agent-acp` 0.73.0 and the patched `codex-acp` 1.6.2. Their `commandDigest` values and profile versions do not change. - Generated declarations: `generated-profiles.ts` and `generated_acpx_profiles.rs` are regenerated with `generate:acpx-profiles`. - Remote native Codex window: `REMOTE_CODEX_MAXIMUM_VERSION_EXCLUSIVE` 0.161.0 → 0.171.0. The minimum stays at 0.149.0. Images with Codex 0.149.0 through 0.170.x are accepted. - Codex company observability: the qualified-version check moves to `codex-cli 0.170.0`. The `otel` configuration keys that Paperclip writes (`exporter`, `trace_exporter`, `metrics_exporter`) are present in the 0.170.0 configuration schema. The `OtelExporterKind`, `OtelHttpProtocol`, and `OtelTlsConfig` definitions are identical to 0.160.0. - Daytona runner image probes (`Dockerfile`, `Dockerfile.release`) expect `codex-cli 0.170.0` and `2.1.328 (Claude Code)`. The remote npm install spec in `server/src/adapters/registry.ts` is `@openai/codex@0.170.0`. - Tests: fixtures and assertions that mirror the pins use the new versions. The window tests accept 0.161.0 through 0.170.99 and reject 0.171.0. The ACPX gate tests now show that Fable 5.2 and GPT-6.2 are admitted. A new test mocks an older bundled runtime and keeps the named version-gap errors covered. The fallback test shows that GPT-6.2 stays on 0.170.0 and still falls back on 0.160.0. - Opt-in qualification scripts (`scripts/tests/native-cleanup-paginated-codex.mjs`, `native-provider-startup-codex.mjs`) require Codex 0.170.0. - Documentation: `docker/daytona-runner/README.md`, `doc/architecture/paperclip-runner-compatibility.md`, `doc/agent-observability.md`, `docs/deploy/environment-variables.md`, and the deferred item in `doc/adapter-model-audit-2026-11-18.md`. - `pnpm-lock.yaml` is not part of this pull request. The refresh bot regenerates it on `master`, as for the previous pin refreshes (#14942, #14993). ## Verification Sources, checked on 2026-11-19: - npm registry: `@openai/codex@0.170.0` (published 2026-11-18T03:45Z) and `@anthropic-ai/claude-agent-sdk@0.3.328` (published 2026-11-18T23:13Z, `claudeCodeVersion` 2.1.328). Both are the `latest` tags. - [Codex releases](https://github.com/openai/codex/releases) 0.161.0 through 0.170.0. The notes record no app-server protocol break. 0.169.0 keeps project configuration disabled for `codex exec` in untrusted directories; Paperclip's CLI path already uses `--skip-git-repo-check`, and the native path uses `app-server`. - [Claude Code changelog](https://github.com/anthropics/claude-code/blob/main/CHANGELOG.md) 2.1.287 through 2.1.328. See "Risks" for the headless changes that I reviewed. Digests and package shape: - I downloaded each platform archive with `npm pack`, which verifies registry integrity, and computed the SHA-256 of the executable. As a method check, the same command on the 0.3.286 Linux x64 archive gives the digest that is on `master` (`fe503f65…`). The Codex 0.160.0 archive also gives the `master` digest (`12eb3e81…`). - The extracted executables report `codex-cli 0.170.0` and `2.1.328 (Claude Code)`. - The Codex 0.170.0 Linux x64 archive no longer contains `codex-resources/zsh/bin/zsh`. Paperclip does not reference that path. - The Agent SDK 0.3.328 `optionalDependencies` have the same platform set as 0.3.286. The Codex 0.170.0 `optionalDependencies` use the same `npm:@openai/codex@<version>-<platform>` aliases. - Bridge link check: I installed `@agentclientprotocol/claude-agent-acp@0.73.0` with an override to Agent SDK 0.3.328 and imported its entry module. Node linked all of the named SDK imports, and the import completed. Real Codex qualification (no model turn, no credentials): - `PAPERCLIP_TEST_CODEX_BINARY=<installed 0.170.0 Linux x64 binary> node --import ./server/node_modules/tsx/dist/loader.mjs scripts/tests/native-cleanup-paginated-codex.mjs` passed: `green: true`, with the expected red control and paginated `thread/resume` through the real 0.170.0 `app-server`. The installed binary digest matches the pinned digest. Focused suites (Linux x64, Node 25.9.0, local `pnpm install --no-frozen-lockfile`): - `cd packages/paperclip-runner && pnpm run typecheck:typescript` passed, including `check:acpx-profiles`. - `npx tsc --noEmit` passed in `packages/adapters/codex-local` and `packages/adapters/claude-local`. - `packages/adapters/codex-local`: 625 passed. `packages/adapters/claude-local`: 419 passed, 1 skipped. - `node --test`: `acpx-codex-package-contract` 9 passed, `controlled-evals/controller` 77 passed, `scripts/acpx-patch-packaging` 26 passed, `scripts/__tests__/grok-public-install-sandbox` 27 passed. - `server`: `acpx-qualification`, `codex-runtime-compatibility`, and `codex-model-fallback` 110 passed. `native-session-executor` 1541 passed, 1 failed. The failure (`compares export process compatibility … db.transaction is not a function`) also fails on unchanged `master` on this host. - `packages/paperclip-runner` vitest (`installation-integrity`, `qualified-profiles`, `codex-security-config`, `native-execution`, `native-backend-factory`): 283 passed, 25 failed. All 25 failures are in `installation-integrity.test.ts` with "ACPX provider lifetime guardian failed to start". The same 25 tests fail on unchanged `master` on this host (master fails 30 here). Rust (toolchain 1.97.1 from `rust-toolchain.toml`, Linux x64): - `cargo test -p paperclip-runner-core --lib`: 658 passed, 2 failed, 4 ignored. `warm_run_attachment_reuses_the_provider_ingress_listener` also fails on unchanged `master` on this host. `reaping_stops_a_dead_runners_provider_and_its_escaped_tool_job` is flaky here: on this branch it passed 2 of 3 reruns. - `cargo test -p paperclip-runner-core --test acpx_warm_attachment --test native_provider_backend`: 7 and 45 passed. - The new and changed saved-session tests pass: `a_session_saved_by_the_previous_agent_runtime_is_refused_by_name`, `unrestorable_saved_sessions_keep_strict_bindings_and_name_their_class`, and `a_settled_session_saved_by_the_previous_acpx_release_continues`. `rustfmt --check` passes. - `server`: `native-session-resume.test.ts` and `acpx-qualification.test.ts` 110 passed, 2 skipped. Both new resume cases run and pass. Not run here: - `native-provider-startup-codex.mjs`, because it needs a compiled `paperclip-runnerd`. The trusted CI runner workflow covers startup and session-resume probes. - The Docker image build and any live model turn. A live Fable 5.2 and GPT-6.2 test follows the staging image rollout. ## Saved sessions from the previous release This change keeps the ACPX bridge command digests and profile versions. It changes `agentRuntimeVersion` in the `claude` and `codex` ACPX profiles. That field is part of the saved session identity. The previous release saved sessions with Agent SDK 0.3.286 or Codex 0.160.0. This build refuses those saved sessions. It does not migrate them. - **Next run (the usual case):** the saved provider descriptor names the old runtime. `rebindNativeSessionCheckpoint` does not match it, so the next run starts a fresh provider session in the same workspace with the complete handoff prompt. No run fails. The earlier provider conversation does not carry over. - **A run in flight at the deploy (settled or mid-turn):** the runner restore refuses the saved descriptor with the permanent class `provider_state_incompatible`. The server reports it as `native_provider_state_incompatible` and stops automatic retries. The runner opens no provider and keeps the saved state bytes and the workspace. The next run on the task starts a fresh provider session. - **Native Codex (`codex_app_server`) and OpenCode** sessions do not record this field, so their resume decision does not change. After a new image is promoted, native Codex resumes a saved thread with Codex 0.170.0 instead of 0.160.0. This pull request does not test that cross-version thread resume. New tests: - `acpx_provider_backend.rs`: `a_session_saved_by_the_previous_agent_runtime_is_refused_by_name` covers settled Claude and Codex sessions and a Claude turn interrupted mid-run by the deploy. `unrestorable_saved_sessions_keep_strict_bindings_and_name_their_class` has a new `agent_runtime_release` case. Each case checks the named class, that no provider session opens, and that the saved bytes do not change. - `native-session-resume.test.ts`: "a session saved by the previous Claude or Codex ACPX runtime" checks that a same-release session resumes, and that a session saved with Agent SDK 0.3.286 or Codex 0.160.0 starts fresh in the same workspace. ## Risks - Medium. Every Paperclip Runner Claude and Codex run uses the new executables. The digests, generated profiles, image probes, and window must agree. They agree locally, and CI runs the Rust and runner suites again. - Claude Code 2.1.287 through 2.1.328 change some headless defaults. I checked each one against Paperclip: - 2.1.302: `-p` and Agent SDK sessions with no permission mode start in `default` mode on third-party providers. Paperclip always sets a mode (`bypassPermissions` or `default`), so this does not apply. - 2.1.299: MCP allow rules now match only the whole server name. Paperclip already writes `mcp__<server>__*` and exact `mcp__paperclip__<tool>` rules. - 2.1.302: fork subagents are on by default in `-p` and the Agent SDK, as in the terminal. This pull request keeps the upstream default and does not set `CLAUDE_CODE_FORK_SUBAGENT=0`. Reviewers can ask to keep them off. - 2.1.299 and later: stdio MCP connections negotiate MCP protocol 2026-07-28 first and fall back to the older protocol for servers that do not answer. - Agent SDK 0.3.328 is less than one day old. If a regression appears, revert this pull request to return to 0.3.286 and Codex 0.160.0. - Sandbox images built before this change still carry Codex 0.160.0 and Claude Code 2.1.286. They stay accepted. On those images, Fable 5.2 and GPT-6.2 keep the existing named errors and fallbacks until a new image is promoted. - Until the refresh bot updates `pnpm-lock.yaml` on `master`, a local `--frozen-lockfile` install fails, as with the previous pin refreshes. > For core feature work, check [`ROADMAP.md`](ROADMAP.md) first and discuss it in `#dev` before opening the PR. Feature PRs that overlap with planned core work may need to be redirected — check the roadmap first. See `CONTRIBUTING.md`. ## Model Used - Anthropic Claude, model ID `claude-opus-5-5`, through Claude Code with tool use (shell, file edit, `gh`) and code execution. The context window and reasoning mode are not reported in this session. - The registry archives, digests, release notes, configuration schemas, and changelog were read directly. No model output was used as a source for those facts. ## 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 - [ ] 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>
1331 lines
57 KiB
TypeScript
1331 lines
57 KiB
TypeScript
import { pluginRunnerAiConnectionRequiredTestResult } from "../services/plugin-runner-ai-connection.js";
|
|
import { HttpError } from "../errors.js";
|
|
import type { AdapterRuntimeCommandSpec, ServerAdapterModule } from "./types.js";
|
|
import { parseAdapterModelsEnv } from "../services/adapter-models-env.js";
|
|
import { validateAiApiKey } from "../services/ai-api-key-test.js";
|
|
import type { AdapterEnvironmentTestResult } from "@paperclipai/shared";
|
|
import { stampClaudeAgentIdHeader } from "./claude-agent-id-header.js";
|
|
import {
|
|
buildSandboxNpmInstallCommand,
|
|
getAdapterSessionManagement,
|
|
PAPERCLIP_RUNNER_PERMISSION_CAPABILITIES,
|
|
PAPERCLIP_RUNNER_ACPX_PROFILES,
|
|
} from "@paperclipai/adapter-utils";
|
|
import type { AdapterLoginCapability } from "@paperclipai/adapter-utils";
|
|
import { runAdapterExecutionTargetShellCommand } from "@paperclipai/adapter-utils/execution-target";
|
|
import {
|
|
execute as claudeExecute,
|
|
listClaudeSkills,
|
|
syncClaudeSkills,
|
|
listClaudeModels,
|
|
refreshClaudeModels,
|
|
testEnvironment as claudeTestEnvironment,
|
|
sessionCodec as claudeSessionCodec,
|
|
getQuotaWindows as claudeGetQuotaWindows,
|
|
getConfigSchema as getClaudeConfigSchema,
|
|
CLAUDE_SETUP_TOKEN_COMMAND,
|
|
parseSetupTokenPrompt,
|
|
parseSetupTokenCredential,
|
|
} from "@paperclipai/adapter-claude-local/server";
|
|
import {
|
|
agentConfigurationDoc as claudeAgentConfigurationDoc,
|
|
models as claudeModels,
|
|
} from "@paperclipai/adapter-claude-local";
|
|
import {
|
|
execute as codexExecute,
|
|
listCodexSkills,
|
|
syncCodexSkills,
|
|
testEnvironment as codexTestEnvironment,
|
|
sessionCodec as codexSessionCodec,
|
|
getQuotaWindows as codexGetQuotaWindows,
|
|
getConfigSchema as getCodexConfigSchema,
|
|
CODEX_DEVICE_LOGIN_COMMAND,
|
|
parseDeviceLoginPrompt,
|
|
} from "@paperclipai/adapter-codex-local/server";
|
|
import {
|
|
agentConfigurationDoc as codexAgentConfigurationDoc,
|
|
models as codexModels,
|
|
} from "@paperclipai/adapter-codex-local";
|
|
import {
|
|
execute as cursorExecute,
|
|
listCursorSkills,
|
|
syncCursorSkills,
|
|
testEnvironment as cursorTestEnvironment,
|
|
sessionCodec as cursorSessionCodec,
|
|
} from "@paperclipai/adapter-cursor-local/server";
|
|
import {
|
|
agentConfigurationDoc as cursorAgentConfigurationDoc,
|
|
models as cursorModels,
|
|
} from "@paperclipai/adapter-cursor-local";
|
|
import {
|
|
execute as cursorCloudExecute,
|
|
getConfigSchema as getCursorCloudConfigSchema,
|
|
sessionCodec as cursorCloudSessionCodec,
|
|
testEnvironment as cursorCloudTestEnvironment,
|
|
} from "@paperclipai/adapter-cursor-cloud/server";
|
|
import { agentConfigurationDoc as cursorCloudAgentConfigurationDoc } from "@paperclipai/adapter-cursor-cloud";
|
|
import {
|
|
execute as geminiExecute,
|
|
listGeminiSkills,
|
|
syncGeminiSkills,
|
|
testEnvironment as geminiTestEnvironment,
|
|
sessionCodec as geminiSessionCodec,
|
|
getConfigSchema as getGeminiConfigSchema,
|
|
} from "@paperclipai/adapter-gemini-local/server";
|
|
import {
|
|
agentConfigurationDoc as geminiAgentConfigurationDoc,
|
|
models as geminiModels,
|
|
} from "@paperclipai/adapter-gemini-local";
|
|
import {
|
|
execute as grokExecute,
|
|
listGrokSkills,
|
|
syncGrokSkills,
|
|
testEnvironment as grokTestEnvironment,
|
|
sessionCodec as grokSessionCodec,
|
|
GROK_DEVICE_LOGIN_COMMAND,
|
|
parseGrokDeviceLoginPrompt,
|
|
} from "@paperclipai/adapter-grok-local/server";
|
|
import {
|
|
agentConfigurationDoc as grokAgentConfigurationDoc,
|
|
models as grokModels,
|
|
} from "@paperclipai/adapter-grok-local";
|
|
import {
|
|
execute as kimiExecute,
|
|
listKimiSkills,
|
|
syncKimiSkills,
|
|
testEnvironment as kimiTestEnvironment,
|
|
sessionCodec as kimiSessionCodec,
|
|
} from "@paperclipai/adapter-kimi-local/server";
|
|
import {
|
|
agentConfigurationDoc as kimiAgentConfigurationDoc,
|
|
models as kimiModels,
|
|
} from "@paperclipai/adapter-kimi-local";
|
|
import {
|
|
createHermesGatewayServerAdapter,
|
|
createHermesLocalServerAdapter,
|
|
} from "@paperclipai/hermes-paperclip-adapter";
|
|
import {
|
|
execute as openCodeExecute,
|
|
listOpenCodeSkills,
|
|
syncOpenCodeSkills,
|
|
testEnvironment as openCodeTestEnvironment,
|
|
sessionCodec as openCodeSessionCodec,
|
|
listOpenCodeModels,
|
|
} from "@paperclipai/adapter-opencode-local/server";
|
|
import {
|
|
agentConfigurationDoc as openCodeAgentConfigurationDoc,
|
|
models as openCodeModels,
|
|
} from "@paperclipai/adapter-opencode-local";
|
|
import {
|
|
execute as openclawGatewayExecute,
|
|
testEnvironment as openclawGatewayTestEnvironment,
|
|
} from "@paperclipai/adapter-openclaw-gateway/server";
|
|
import {
|
|
agentConfigurationDoc as openclawGatewayAgentConfigurationDoc,
|
|
models as openclawGatewayModels,
|
|
} from "@paperclipai/adapter-openclaw-gateway";
|
|
import { listCodexModels, refreshCodexModels } from "./codex-models.js";
|
|
import { listCursorModels } from "./cursor-models.js";
|
|
import {
|
|
execute as piExecute,
|
|
listPiSkills,
|
|
syncPiSkills,
|
|
testEnvironment as piTestEnvironment,
|
|
sessionCodec as piSessionCodec,
|
|
listPiModels,
|
|
} from "@paperclipai/adapter-pi-local/server";
|
|
import { agentConfigurationDoc as piAgentConfigurationDoc } from "@paperclipai/adapter-pi-local";
|
|
import { BUILTIN_ADAPTER_TYPES } from "./builtin-adapter-types.js";
|
|
import { buildExternalAdapters } from "./plugin-loader.js";
|
|
import { isCloudManagedInstance } from "../services/cloud-instance.js";
|
|
import { assertExternalAdapterCodeAllowed } from "../services/adapter-code-policy.js";
|
|
import { NativeEnvironmentProbeCleanupError } from "../vendor/paperclip-runner/index.js";
|
|
import { processAdapter } from "./process/index.js";
|
|
import { httpAdapter } from "./http/index.js";
|
|
import {
|
|
DEFAULT_OPENCODE_RUNNER_MODEL,
|
|
PaperclipRunnerProviderProfileError,
|
|
DEFAULT_ACPX_RUNNER_MODELS,
|
|
QUALIFIED_OPENCODE_RUNNER_VERSION,
|
|
resolvePaperclipRunnerProviderProfile,
|
|
} from "../services/native-runtime/provider-profile.js";
|
|
|
|
async function verifyNativeAcpxApiKey(
|
|
config: Record<string, unknown>,
|
|
result: AdapterEnvironmentTestResult,
|
|
): Promise<AdapterEnvironmentTestResult> {
|
|
const env = config.env as Record<string, unknown> | undefined;
|
|
const account = config.acpxAgent === "claude" ? { provider: "anthropic" as const, name: "Anthropic", key: "ANTHROPIC_API_KEY",
|
|
routing: ["ANTHROPIC_BASE_URL", "ANTHROPIC_AUTH_TOKEN", "CLAUDE_CODE_USE_BEDROCK", "CLAUDE_CODE_USE_VERTEX", "CLAUDE_CODE_USE_FOUNDRY"] }
|
|
: config.acpxAgent === "grok" ? { provider: "xai" as const, name: "xAI", key: "XAI_API_KEY", routing: ["XAI_BASE_URL", "GROK_BASE_URL"] } : null;
|
|
if (!account || !env || typeof env[account.key] !== "string" || !env[account.key]
|
|
|| config.managedAiRouting || config.managedAiConnection || account.routing.some(key => env[key])) return result;
|
|
try {
|
|
await validateAiApiKey(account.provider, env[account.key] as string);
|
|
return { ...result, checks: [...result.checks, {
|
|
code: "ai_connection_api_key_reverified", level: "info",
|
|
message: `${account.name} verified this API key. Model access is checked when the agent runs.`,
|
|
}] };
|
|
} catch (error) {
|
|
const details = error && typeof error === "object" && "details" in error
|
|
? error.details as { code?: string } | undefined : undefined;
|
|
return { ...result, status: "fail", checks: [...result.checks, {
|
|
code: details?.code === "ai_connection_api_key_rejected" ? details.code : "ai_connection_verification_failed",
|
|
level: "error", message: `Could not verify the ${account.name} API key. Check the connection and try again.`,
|
|
}] };
|
|
}
|
|
}
|
|
|
|
function readConfiguredCommand(config: Record<string, unknown>, fallback: string): string {
|
|
const value = typeof config.command === "string" ? config.command.trim() : "";
|
|
return value.length > 0 ? value : fallback;
|
|
}
|
|
|
|
function hasPathSeparator(command: string): boolean {
|
|
return command.includes("/") || command.includes("\\");
|
|
}
|
|
|
|
function shellQuote(value: string): string {
|
|
return `'${value.replace(/'/g, `'"'"'`)}'`;
|
|
}
|
|
|
|
function buildNpmRuntimeCommandSpec(
|
|
config: Record<string, unknown>,
|
|
fallbackCommand: string,
|
|
packageName: string,
|
|
): AdapterRuntimeCommandSpec {
|
|
const command = readConfiguredCommand(config, fallbackCommand);
|
|
const canSelfInstall = !hasPathSeparator(command) && command === fallbackCommand;
|
|
const installLine = buildSandboxNpmInstallCommand(packageName);
|
|
return {
|
|
command,
|
|
detectCommand: command,
|
|
installCommand: canSelfInstall
|
|
? `if ! command -v ${shellQuote(command)} >/dev/null 2>&1; then ${installLine}; fi`
|
|
: null,
|
|
};
|
|
}
|
|
|
|
function buildCursorRuntimeCommandSpec(config: Record<string, unknown>): AdapterRuntimeCommandSpec {
|
|
const command = readConfiguredCommand(config, "agent");
|
|
return {
|
|
command,
|
|
detectCommand: command,
|
|
installCommand: null,
|
|
};
|
|
}
|
|
|
|
const retiredAcpxMessage =
|
|
"The acpx_local adapter has been retired. Existing Claude and Codex ACPX agents should be migrated to claude_local or codex_local with adapterConfig.engine=\"acp\".";
|
|
|
|
const retiredAcpxAgentConfigurationDoc = `# acpx_local retired
|
|
|
|
Adapter: acpx_local
|
|
|
|
The standalone ACPX adapter has been retired. Use:
|
|
|
|
- claude_local with adapterConfig.engine="acp" for Claude ACP execution.
|
|
- codex_local with adapterConfig.engine="acp" for Codex ACP execution.
|
|
|
|
Paperclip keeps this tombstone registered so stale acpx_local rows fail clearly instead of falling back to the process adapter.
|
|
`;
|
|
|
|
// The Claude interactive login capability. Claude runs `claude setup-token` on a
|
|
// real pseudo-terminal. The user pastes a browser code back into the flow. The
|
|
// flow uses a fixed host-side timeout and records a stored session identifier on
|
|
// success. The capability data holds no secret; the callbacks return runtime
|
|
// values only.
|
|
const claudeLoginCapability: AdapterLoginCapability = {
|
|
panelMode: "submitted_browser_code",
|
|
timeoutPolicy: "fixed",
|
|
getCommand: () => CLAUDE_SETUP_TOKEN_COMMAND,
|
|
parsePrompt: (output) => {
|
|
const prompt = parseSetupTokenPrompt(output);
|
|
return prompt ? { url: prompt.url } : null;
|
|
},
|
|
captureCredential: (output) => {
|
|
const token = parseSetupTokenCredential(output);
|
|
return token === null ? null : Buffer.from(token, "utf8");
|
|
},
|
|
completionClaim: "storedSessionId",
|
|
};
|
|
|
|
// The Codex interactive login capability. Codex runs `codex login --device-auth`
|
|
// on a real pseudo-terminal, because a pipe emits no login prompt. The flow shows
|
|
// a one-time code that the user enters in the browser. The caller sets the
|
|
// host-side timeout. The device-login flow writes its credential inside the
|
|
// sandbox, so the capability declares no terminal credential capture and no
|
|
// completion claim.
|
|
const codexLoginCapability: AdapterLoginCapability = {
|
|
panelMode: "displayed_code",
|
|
timeoutPolicy: "caller_bounded",
|
|
getCommand: () => CODEX_DEVICE_LOGIN_COMMAND,
|
|
parsePrompt: (output) => {
|
|
const prompt = parseDeviceLoginPrompt(output);
|
|
return prompt ? { url: prompt.url, code: prompt.code } : null;
|
|
},
|
|
};
|
|
|
|
// The Grok interactive login capability. Grok runs `grok login --device-auth`
|
|
// on a real pseudo-terminal, the same way Codex does. The flow shows a
|
|
// one-time code that the user enters in the browser. The caller sets the
|
|
// host-side timeout. The device-login flow writes its credential inside the
|
|
// sandbox, so the capability declares no terminal credential capture and no
|
|
// completion claim. `getCommand` is descriptive only: the login path selects
|
|
// the real command from the closed key map in `login-command.ts`, never from
|
|
// this member.
|
|
const grokLoginCapability: AdapterLoginCapability = {
|
|
panelMode: "displayed_code",
|
|
timeoutPolicy: "caller_bounded",
|
|
getCommand: () => GROK_DEVICE_LOGIN_COMMAND,
|
|
parsePrompt: (output) => {
|
|
const prompt = parseGrokDeviceLoginPrompt(output);
|
|
return prompt ? { url: prompt.url, code: prompt.code } : null;
|
|
},
|
|
};
|
|
|
|
const claudeLocalAdapter: ServerAdapterModule = {
|
|
type: "claude_local",
|
|
runtimeToolDelivery: "native_mcp",
|
|
execute: stampClaudeAgentIdHeader(claudeExecute),
|
|
testEnvironment: claudeTestEnvironment,
|
|
acp: {
|
|
agentId: "claude",
|
|
skillsMode: "ephemeral",
|
|
prerequisites: {
|
|
nodeRange: ">=24.11.0",
|
|
packages: ["@agentclientprotocol/claude-agent-acp"],
|
|
},
|
|
},
|
|
listSkills: listClaudeSkills,
|
|
syncSkills: syncClaudeSkills,
|
|
sessionCodec: claudeSessionCodec,
|
|
sessionManagement: getAdapterSessionManagement("claude_local") ?? undefined,
|
|
supportsToolRefreshOnResume: true,
|
|
models: claudeModels,
|
|
listModels: listClaudeModels,
|
|
refreshModels: refreshClaudeModels,
|
|
supportsLocalAgentJwt: true,
|
|
supportsInstructionsBundle: true,
|
|
instructionsPathKey: "instructionsFilePath",
|
|
requiresMaterializedRuntimeSkills: false,
|
|
getRuntimeCommandSpec: (config) =>
|
|
buildNpmRuntimeCommandSpec(config, "claude", "@anthropic-ai/claude-code"),
|
|
agentConfigurationDoc: claudeAgentConfigurationDoc,
|
|
getConfigSchema: getClaudeConfigSchema,
|
|
getQuotaWindows: claudeGetQuotaWindows,
|
|
loginCapability: claudeLoginCapability,
|
|
};
|
|
|
|
const acpxLocalAdapter: ServerAdapterModule = {
|
|
type: "acpx_local",
|
|
runtimeToolDelivery: "environment",
|
|
async execute(ctx) {
|
|
await ctx.onLog("stderr", `${retiredAcpxMessage}\n`);
|
|
await ctx.onMeta?.({
|
|
adapterType: "acpx_local",
|
|
command: "acpx_local-retired",
|
|
commandNotes: [retiredAcpxMessage],
|
|
});
|
|
return {
|
|
exitCode: 1,
|
|
signal: null,
|
|
timedOut: false,
|
|
errorMessage: retiredAcpxMessage,
|
|
errorCode: "acpx_local_retired",
|
|
provider: "acpx",
|
|
summary: retiredAcpxMessage,
|
|
};
|
|
},
|
|
async testEnvironment() {
|
|
return {
|
|
adapterType: "acpx_local",
|
|
status: "fail",
|
|
testedAt: new Date().toISOString(),
|
|
checks: [
|
|
{
|
|
code: "acpx_local_retired",
|
|
level: "error",
|
|
message: retiredAcpxMessage,
|
|
hint: "Set the agent adapter to claude_local or codex_local and set adapterConfig.engine to acp.",
|
|
},
|
|
],
|
|
};
|
|
},
|
|
models: [],
|
|
supportsLocalAgentJwt: false,
|
|
supportsInstructionsBundle: false,
|
|
requiresMaterializedRuntimeSkills: false,
|
|
agentConfigurationDoc: retiredAcpxAgentConfigurationDoc,
|
|
getConfigSchema: () => ({ fields: [] }),
|
|
};
|
|
|
|
const codexLocalAdapter: ServerAdapterModule = {
|
|
type: "codex_local",
|
|
runtimeToolDelivery: "native_mcp",
|
|
execute: codexExecute,
|
|
testEnvironment: codexTestEnvironment,
|
|
acp: {
|
|
agentId: "codex",
|
|
skillsMode: "ephemeral",
|
|
prerequisites: {
|
|
nodeRange: ">=24.11.0",
|
|
packages: ["@agentclientprotocol/codex-acp"],
|
|
},
|
|
},
|
|
listSkills: listCodexSkills,
|
|
syncSkills: syncCodexSkills,
|
|
sessionCodec: codexSessionCodec,
|
|
sessionManagement: getAdapterSessionManagement("codex_local") ?? undefined,
|
|
supportsToolRefreshOnResume: true,
|
|
models: codexModels,
|
|
listModels: listCodexModels,
|
|
refreshModels: refreshCodexModels,
|
|
supportsLocalAgentJwt: true,
|
|
supportsInstructionsBundle: true,
|
|
instructionsPathKey: "instructionsFilePath",
|
|
requiresMaterializedRuntimeSkills: false,
|
|
getRuntimeCommandSpec: (config) => buildNpmRuntimeCommandSpec(config, "codex", "@openai/codex"),
|
|
agentConfigurationDoc: codexAgentConfigurationDoc,
|
|
getConfigSchema: getCodexConfigSchema,
|
|
getQuotaWindows: codexGetQuotaWindows,
|
|
loginCapability: codexLoginCapability,
|
|
};
|
|
|
|
const paperclipRunnerAdapter: ServerAdapterModule = {
|
|
type: "paperclip_runner",
|
|
runtimeToolDelivery: "environment",
|
|
async execute(ctx) {
|
|
const message = "paperclip_runner requires the native runner coordinator";
|
|
await ctx.onLog("stderr", `${message}\n`);
|
|
return {
|
|
exitCode: 1,
|
|
signal: null,
|
|
timedOut: false,
|
|
errorMessage: message,
|
|
errorCode: "paperclip_runner_coordinator_required",
|
|
provider: ctx.config.provider === "opencode"
|
|
? "opencode"
|
|
: ctx.config.provider === "claude_managed"
|
|
? "anthropic"
|
|
: ctx.config.provider === "aws_agentcore"
|
|
? "amazon-bedrock"
|
|
: ctx.config.provider === "acpx"
|
|
? "acpx"
|
|
: ctx.config.provider === "cursor_cloud" ? "cursor"
|
|
: "codex",
|
|
summary: message,
|
|
};
|
|
},
|
|
async testEnvironment(context) {
|
|
let profile: ReturnType<typeof resolvePaperclipRunnerProviderProfile>;
|
|
try {
|
|
profile = resolvePaperclipRunnerProviderProfile(context.config, { companyId: context.companyId });
|
|
} catch (error) {
|
|
const profileError = error instanceof PaperclipRunnerProviderProfileError
|
|
? error
|
|
: new PaperclipRunnerProviderProfileError(
|
|
"paperclip_runner_provider_unsupported",
|
|
"Paperclip Runner provider configuration is invalid.",
|
|
);
|
|
return {
|
|
adapterType: "paperclip_runner",
|
|
status: "fail" as const,
|
|
testedAt: new Date().toISOString(),
|
|
checks: [{
|
|
code: profileError.code,
|
|
level: "error" as const,
|
|
message: profileError.message,
|
|
}],
|
|
};
|
|
}
|
|
if (profile.provider !== "cursor_cloud" && context.executionTarget?.kind === "remote" && context.executionTarget.transport === "sandbox" && context.executionTarget.runnerTask) {
|
|
// Managed connections probe through testManagedEnvironment. This path has
|
|
// none, which a plugin Runner-task environment never runs.
|
|
return pluginRunnerAiConnectionRequiredTestResult("paperclip_runner");
|
|
}
|
|
if (profile.provider === "cursor_cloud") {
|
|
const failure = (code: string, message: string) => ({ adapterType: "paperclip_runner", status: "fail" as const, testedAt: new Date().toISOString(), checks: [{ code, level: "error" as const, message }] });
|
|
if (context.executionTarget?.kind === "remote") return failure("cursor_cloud_local_controller_required", "Select a local Paperclip controller. Cursor hosts the execution environment.");
|
|
const configuredEnv = context.config.env;
|
|
const binding = configuredEnv && typeof configuredEnv === "object" && !Array.isArray(configuredEnv)
|
|
? (configuredEnv as Record<string, unknown>).CURSOR_API_KEY : undefined;
|
|
const apiKey = typeof binding === "string" ? binding : binding && typeof binding === "object" && "type" in binding && binding.type === "plain" && "value" in binding && typeof binding.value === "string" ? binding.value : "";
|
|
if (!apiKey.trim()) return failure("cursor_cloud_api_key_missing", "Bind a Cursor Cloud API key to CURSOR_API_KEY before testing.");
|
|
try {
|
|
const { remoteMcpRelayUrl } = await import("../services/native-runtime/remote-mcp-relay.js");
|
|
const { resolveCursorCloudPublicOrigin } = await import("../services/native-runtime/cursor-cloud-runtime.js");
|
|
const url = remoteMcpRelayUrl(resolveCursorCloudPublicOrigin() ?? "", "00000000-0000-4000-8000-000000000000");
|
|
const response = await fetch(url, { method: "POST", headers: { "Content-Type": "application/json" }, body: "{}", redirect: "error", signal: AbortSignal.timeout(5_000) });
|
|
await response.body?.cancel();
|
|
if (response.status !== 401) throw new Error("relay_unavailable");
|
|
} catch {
|
|
return failure("cursor_cloud_public_relay_unavailable", "Configure PAPERCLIP_PUBLIC_URL as a reachable HTTPS origin for /mcp/native-runs/. The callback must reject unauthenticated requests with HTTP 401. Expose only this callback path through the public proxy.");
|
|
}
|
|
try {
|
|
const { CursorCloudClient } = await import("../vendor/paperclip-runner/index.js");
|
|
const { items } = await new CursorCloudClient({ apiKey }).listModels();
|
|
const listed = items.some(item => item.id === profile.model || item.aliases?.includes(profile.model));
|
|
return { adapterType: "paperclip_runner", status: "warn" as const, testedAt: new Date().toISOString(), checks: [
|
|
{ code: "cursor_cloud_account_ready", level: "info" as const, message: "The bound Cursor Cloud API key can read its model catalog. No prompt was sent." },
|
|
{ code: listed ? "cursor_cloud_model_listed" : "cursor_cloud_model_unlisted", level: listed ? "info" as const : "warn" as const,
|
|
message: listed ? "The selected model appears in this account's catalog." : "The selected model is absent from the recommended catalog. Cursor will decide whether this exact model is available when it runs." },
|
|
{ code: "cursor_cloud_model_identity_unverified", level: "warn" as const, message: "This experimental integration forwards the selected model; Cursor does not acknowledge the effective model. Cloud commands use Cursor-managed permissions." },
|
|
] };
|
|
} catch { return failure("cursor_cloud_account_unavailable", "Cursor Cloud could not validate the bound key. Check its Cloud Agents access and retry."); }
|
|
}
|
|
if (profile.provider === "muse") {
|
|
return { adapterType: "paperclip_runner", status: "warn" as const, testedAt: new Date().toISOString(),
|
|
checks: [{ code: "muse_background_test_required", level: "warn" as const, message: "Muse manages its model and billing. Verify the paired receiver and independent background reply in Paperclip; this read-only check does not wake Muse." }] };
|
|
}
|
|
if (profile.provider === "openai_dot") {
|
|
return { adapterType: "paperclip_runner", status: "warn" as const, testedAt: new Date().toISOString(),
|
|
checks: [{ code: "dot_event_test_required", level: "warn" as const, message: "Dot manages its model and billing. Validate the dedicated agent binding and event round trip in Paperclip; this read-only check does not wake the Dot." }] };
|
|
}
|
|
if (profile.provider === "acpx") {
|
|
try {
|
|
if (profile.acpxAgent === "antigravity") {
|
|
const { testAntigravityConnection } = await import("../services/antigravity-connection-probe.js");
|
|
return await testAntigravityConnection(context, profile.model);
|
|
}
|
|
if (profile.acpxAgent === "copilot") {
|
|
const configured = context.config.env;
|
|
const token = configured && typeof configured === "object" && !Array.isArray(configured)
|
|
? (configured as Record<string, unknown>).COPILOT_GITHUB_TOKEN : undefined;
|
|
if (typeof token !== "string" || !token) {
|
|
return { adapterType: "paperclip_runner", status: "fail" as const, testedAt: new Date().toISOString(),
|
|
checks: [{ code: "COPILOT_AUTH_REQUIRED", level: "error" as const, message: "Select a saved Copilot token connection." }] };
|
|
}
|
|
const { probeCopilotExecutionTarget } = await import("../services/copilot-connection-probe.js");
|
|
await probeCopilotExecutionTarget(token, context.executionTarget, profile.model);
|
|
return { adapterType: "paperclip_runner", status: "pass" as const, testedAt: new Date().toISOString(),
|
|
checks: [{ code: "copilot_metadata_verified", level: "info" as const,
|
|
message: "The verified Copilot runtime authenticated this account and accepted the selected model. No model prompt was sent." }] };
|
|
}
|
|
if (profile.acpxAgent !== "claude" && profile.acpxAgent !== "grok" && profile.acpxAgent !== "cursor" && profile.acpxAgent !== "pi" && profile.acpxAgent !== "kimi") throw new Error("Select Codex to use the native Codex runner.");
|
|
if (profile.acpxAgent === "kimi") {
|
|
const environment = context.config.env as Record<string, unknown> | undefined;
|
|
if (typeof environment?.KIMI_API_KEY !== "string" || !environment.KIMI_API_KEY.trim()) {
|
|
return { adapterType: "paperclip_runner", status: "fail" as const, testedAt: new Date().toISOString(),
|
|
checks: [{ code: "KIMI_AUTH_REQUIRED", level: "error" as const, message: "Bind a company secret to KIMI_API_KEY in the agent environment." }] };
|
|
}
|
|
}
|
|
const target = context.executionTarget;
|
|
if (profile.acpxAgent === "kimi") {
|
|
const { probeKimiExecutionTarget } = await import("../services/kimi-connection-probe.js");
|
|
await probeKimiExecutionTarget((context.config.env as Record<string, string>).KIMI_API_KEY, target, profile.model, { companyId: context.companyId });
|
|
return { adapterType: "paperclip_runner", status: "pass" as const, testedAt: new Date().toISOString(),
|
|
checks: [{ code: "kimi_metadata_verified", level: "info" as const,
|
|
message: "The selected environment verified the pinned Kimi Code runtime. Its Code model catalog accepted the credential and lists the exact selected model. No model prompt was sent." }] };
|
|
}
|
|
if (target?.kind === "remote") {
|
|
const probe = await runAdapterExecutionTargetShellCommand(
|
|
`acpx-platform-${crypto.randomUUID()}`, target, "uname -s && uname -m",
|
|
{ cwd: target.remoteCwd, env: {}, timeoutSec: 15 },
|
|
);
|
|
if (probe.timedOut || probe.exitCode !== 0) throw new Error("Could not verify the remote ACPX runner platform.");
|
|
const [os, arch] = probe.stdout.trim().split(/\s+/);
|
|
if (!((os === "Linux" && (arch === "x86_64" || (profile.acpxAgent === "claude" && ["aarch64", "arm64"].includes(arch)))) || (os === "Darwin" && (arch === "arm64" || (!["grok"].includes(profile.acpxAgent) && arch === "x86_64"))))) {
|
|
throw new Error(`ACPX ${profile.acpxAgent} requires a qualified Linux ${profile.acpxAgent === "claude" ? "x64/ARM64" : "x64"} or macOS architecture.`);
|
|
}
|
|
return verifyNativeAcpxApiKey(context.config, {
|
|
adapterType: "paperclip_runner", status: "warn" as const, testedAt: new Date().toISOString(),
|
|
checks: [{ code: "acpx_remote_runtime_unverified", level: "warn" as const,
|
|
message: "The remote platform is supported. Runtime package integrity and readiness must still be verified by the remote runner before launch." }],
|
|
});
|
|
}
|
|
const { probeAcpxClaudeInstallation, probeAcpxGrokInstallation, probeAcpxCursorInstallation, probeAcpxPiInstallation } = await import("../vendor/paperclip-runner/live/index.js");
|
|
await (profile.acpxAgent === "pi" ? probeAcpxPiInstallation : profile.acpxAgent === "grok" ? probeAcpxGrokInstallation : profile.acpxAgent === "cursor" ? probeAcpxCursorInstallation : probeAcpxClaudeInstallation)(profile.model);
|
|
return verifyNativeAcpxApiKey(context.config, {
|
|
adapterType: "paperclip_runner", status: "pass" as const, testedAt: new Date().toISOString(),
|
|
checks: [{ code: "acpx_runtime_ready", level: "info" as const, message: `ACPX ${profile.acpxAgent} runtime is installed and verified. Model access is checked when it runs.` }],
|
|
});
|
|
} catch (error) {
|
|
// The selected managed credential home must outlive an uncertain
|
|
// native retirement. Its caller retains writeback until proof arrives.
|
|
if (error instanceof NativeEnvironmentProbeCleanupError) throw error;
|
|
if (profile.acpxAgent === "antigravity") {
|
|
const { antigravityConnectionProbeFailure } = await import("../services/antigravity-connection-probe.js");
|
|
return antigravityConnectionProbeFailure(context.companyId, error);
|
|
}
|
|
if (profile.acpxAgent === "copilot") {
|
|
const details = error instanceof HttpError && error.details && typeof error.details === "object" && !Array.isArray(error.details)
|
|
? error.details as Record<string, unknown> : {};
|
|
const codes = ["COPILOT_AUTH_REQUIRED", "COPILOT_ENTITLEMENT_DENIED", "COPILOT_MODEL_UNAVAILABLE", "COPILOT_INSTALLATION_INVALID", "COPILOT_REQUEST_FAILED"];
|
|
const code = typeof details.code === "string" && codes.includes(details.code) ? details.code : "COPILOT_REQUEST_FAILED";
|
|
return { adapterType: "paperclip_runner", status: "fail" as const, testedAt: new Date().toISOString(),
|
|
checks: [{ code, level: "error" as const, message: error instanceof HttpError ? error.message : "Copilot metadata verification failed." }] };
|
|
}
|
|
return {
|
|
adapterType: "paperclip_runner", status: "fail" as const, testedAt: new Date().toISOString(),
|
|
checks: [{
|
|
code: error instanceof Error && "code" in error && error.code === "ACPX_RUNTIME_PACKAGE_MISSING"
|
|
? "acpx_runtime_package_missing" : "acpx_runtime_unavailable",
|
|
level: "error" as const,
|
|
message: error instanceof Error ? error.message : "The ACPX runtime could not be verified.",
|
|
}],
|
|
};
|
|
}
|
|
}
|
|
if (profile.provider === "claude_managed") {
|
|
return {
|
|
adapterType: "paperclip_runner",
|
|
status: "warn" as const,
|
|
testedAt: new Date().toISOString(),
|
|
checks: [{
|
|
code: "claude_managed_profile_selected",
|
|
level: "info" as const,
|
|
message: `Claude Managed profile ${profile.managedProfileId} is selected with retention acknowledged. Its stored qualification, API-key binding, and spend ceiling are verified before the first turn.`,
|
|
}, {
|
|
code: "claude_managed_retention_notice",
|
|
level: "warn" as const,
|
|
message: "Claude Managed is a stateful beta service and is not eligible for ZDR or HIPAA modes.",
|
|
}],
|
|
};
|
|
}
|
|
if (profile.provider === "aws_agentcore") {
|
|
return {
|
|
adapterType: "paperclip_runner",
|
|
status: "warn" as const,
|
|
testedAt: new Date().toISOString(),
|
|
checks: [{
|
|
code: "aws_agentcore_profile_selected",
|
|
level: "info" as const,
|
|
message: `AWS AgentCore profile ${profile.agentCoreProfileId} is selected with retention acknowledged. Its stored qualification, invocation limits, and estimated spend ceiling are verified before the first turn.`,
|
|
}, {
|
|
code: "aws_agentcore_retention_notice",
|
|
level: "warn" as const,
|
|
message: "AgentCore Memory retains short-term events for 90 days; the spend ceiling is an estimate, not an AWS currency hard stop.",
|
|
}],
|
|
};
|
|
}
|
|
if (profile.provider === "codex") {
|
|
const { testNativeRunnerAuthentication } = await import("../services/native-runtime/setup-readiness.js");
|
|
return testNativeRunnerAuthentication(context, "codex", profile.model);
|
|
}
|
|
const result = await openCodeTestEnvironment(context);
|
|
return { ...result, adapterType: "paperclip_runner" };
|
|
},
|
|
listSkills: listCodexSkills,
|
|
syncSkills: syncCodexSkills,
|
|
sessionCodec: codexSessionCodec,
|
|
models: [
|
|
...codexModels,
|
|
{ id: DEFAULT_OPENCODE_RUNNER_MODEL, label: "OpenRouter · DeepSeek V4 Flash 0731" },
|
|
{ id: DEFAULT_ACPX_RUNNER_MODELS.claude, label: "Claude Opus 5.5" },
|
|
{ id: "global.anthropic.claude-sonnet-4-6", label: "Amazon Bedrock · Claude Sonnet 4.6 (global)" },
|
|
],
|
|
listModels: async () => [
|
|
...await listCodexModels(),
|
|
{ id: DEFAULT_OPENCODE_RUNNER_MODEL, label: "OpenRouter · DeepSeek V4 Flash 0731" },
|
|
{ id: DEFAULT_ACPX_RUNNER_MODELS.claude, label: "Claude Opus 5.5" },
|
|
{ id: "global.anthropic.claude-sonnet-4-6", label: "Amazon Bedrock · Claude Sonnet 4.6 (global)" },
|
|
],
|
|
refreshModels: async () => [
|
|
...await refreshCodexModels(),
|
|
{ id: DEFAULT_OPENCODE_RUNNER_MODEL, label: "OpenRouter · DeepSeek V4 Flash 0731" },
|
|
{ id: DEFAULT_ACPX_RUNNER_MODELS.claude, label: "Claude Opus 5.5" },
|
|
{ id: "global.anthropic.claude-sonnet-4-6", label: "Amazon Bedrock · Claude Sonnet 4.6 (global)" },
|
|
],
|
|
supportsLocalAgentJwt: false,
|
|
supportsInstructionsBundle: true,
|
|
instructionsPathKey: "instructionsFilePath",
|
|
requiresMaterializedRuntimeSkills: false,
|
|
getRuntimeCommandSpec: (config) => config.provider === "claude_managed"
|
|
|| config.provider === "aws_agentcore"
|
|
|| config.provider === "acpx"
|
|
|| config.provider === "cursor_cloud"
|
|
? { command: "paperclip-runnerd", detectCommand: null, installCommand: null }
|
|
: config.provider === "opencode"
|
|
? buildNpmRuntimeCommandSpec(
|
|
config,
|
|
"opencode",
|
|
`opencode-ai@${QUALIFIED_OPENCODE_RUNNER_VERSION}`,
|
|
)
|
|
: buildNpmRuntimeCommandSpec(config, "codex", "@openai/codex@0.170.0"),
|
|
agentConfigurationDoc:
|
|
"# Paperclip Runner\n\nAdapter: paperclip_runner\n\nRuns Codex, OpenCode, Claude Managed, AWS AgentCore, or ACPX Claude/Grok Build/Cursor/Pi through the Rust Paperclip runner and authenticated PRP transport. Pi accepts an explicit provider/model ID and uses the company credentials bound to the agent environment. GitHub Copilot requires a saved GitHub token and an explicitly selected available model. Managed providers use company-scoped qualified profiles, explicit retention acknowledgement, and spend limits. A board operator creates each Claude Managed (Anthropic managed agent) profile through POST /api/companies/{companyId}/managed-agent-profiles; agent credentials cannot create, qualify or list one.\n",
|
|
getConfigSchema: () => ({
|
|
fields: [
|
|
{
|
|
key: "provider",
|
|
label: "Provider",
|
|
type: "select" as const,
|
|
default: "codex",
|
|
options: [
|
|
{ value: "codex", label: "Codex" },
|
|
{ value: "opencode", label: `OpenCode ${QUALIFIED_OPENCODE_RUNNER_VERSION}` },
|
|
{ value: "claude_managed", label: "Claude Managed" },
|
|
{ value: "aws_agentcore", label: "AWS AgentCore" },
|
|
{ value: "acpx", label: "ACP agents" },
|
|
{ value: "cursor_cloud", label: "Cursor Cloud (experimental)" },
|
|
],
|
|
hint: "Select a local provider, company-qualified managed provider, or an ACP agent.",
|
|
},
|
|
{
|
|
key: "acpxAgent", label: "ACP agent", type: "select" as const, default: "claude",
|
|
options: PAPERCLIP_RUNNER_ACPX_PROFILES.filter(profile => profile.qualified).map(profile => ({ value: profile.value, label: profile.label })),
|
|
meta: { visibleWhen: { key: "provider", value: "acpx" } },
|
|
},
|
|
...[
|
|
{ key: "repoUrl", label: "GitHub repository" },
|
|
{ key: "repoRef", label: "Starting ref" },
|
|
{ key: "prUrl", label: "Pull request URL" },
|
|
{ key: "cloudEnvName", label: "Cursor cloud environment" },
|
|
].map(field => ({ ...field, type: "text" as const, meta: { visibleWhen: { key: "provider", value: "cursor_cloud" } } })),
|
|
...[
|
|
{ key: "workOnCurrentBranch", label: "Work on current branch" },
|
|
{ key: "autoCreatePR", label: "Auto-create pull request" },
|
|
{ key: "skipReviewerRequest", label: "Skip reviewer request" },
|
|
].map(field => ({ ...field, type: "toggle" as const, default: false, meta: { visibleWhen: { key: "provider", value: "cursor_cloud" } } })),
|
|
{
|
|
key: "codexPermissionMode",
|
|
label: "Codex permission mode",
|
|
type: "select" as const,
|
|
default: PAPERCLIP_RUNNER_PERMISSION_CAPABILITIES.codex.defaultMode,
|
|
options: PAPERCLIP_RUNNER_PERMISSION_CAPABILITIES.codex.options.map(
|
|
({ value, label }) => ({ value, label }),
|
|
),
|
|
hint: PAPERCLIP_RUNNER_PERMISSION_CAPABILITIES.codex.description,
|
|
meta: { visibleWhen: { key: "provider", value: "codex" } },
|
|
},
|
|
{
|
|
key: "opencodePermissionMode",
|
|
label: "OpenCode permission mode",
|
|
type: "select" as const,
|
|
default: PAPERCLIP_RUNNER_PERMISSION_CAPABILITIES.opencode.defaultMode,
|
|
options: PAPERCLIP_RUNNER_PERMISSION_CAPABILITIES.opencode.options.map(
|
|
({ value, label }) => ({ value, label }),
|
|
),
|
|
hint: PAPERCLIP_RUNNER_PERMISSION_CAPABILITIES.opencode.description,
|
|
meta: { visibleWhen: { key: "provider", value: "opencode" } },
|
|
},
|
|
{
|
|
key: "acpxSessionMode",
|
|
label: "Cursor mode",
|
|
type: "select" as const,
|
|
default: "agent",
|
|
options: [
|
|
{ value: "agent", label: "Agent" },
|
|
{ value: "plan", label: "Plan" },
|
|
{ value: "ask", label: "Ask" },
|
|
],
|
|
hint: "Select Cursor's session mode. Permissions and company approval rules still apply.",
|
|
meta: { visibleWhen: { key: "acpxAgent", value: "cursor" } },
|
|
},
|
|
{
|
|
key: "acpxPermissionMode",
|
|
label: "ACPX permission mode",
|
|
type: "select" as const,
|
|
default: PAPERCLIP_RUNNER_PERMISSION_CAPABILITIES.acpx.defaultMode,
|
|
options: PAPERCLIP_RUNNER_PERMISSION_CAPABILITIES.acpx.options.map(
|
|
({ value, label }) => ({ value, label }),
|
|
),
|
|
hint: PAPERCLIP_RUNNER_PERMISSION_CAPABILITIES.acpx.description,
|
|
meta: { visibleWhen: { key: "provider", value: "acpx" } },
|
|
},
|
|
{
|
|
key: "model",
|
|
label: "Provider model",
|
|
type: "text" as const,
|
|
default: "",
|
|
placeholder: DEFAULT_OPENCODE_RUNNER_MODEL,
|
|
hint: "OpenCode uses provider/model form. ACPX Claude accepts Claude model IDs, including custom IDs.",
|
|
meta: { visibleWhen: { key: "provider", value: "opencode" } },
|
|
},
|
|
{
|
|
key: "managedProfileId",
|
|
label: "Managed Agent profile",
|
|
type: "text" as const,
|
|
required: true,
|
|
hint: "Company-scoped qualified profile ID or key.",
|
|
meta: { visibleWhen: { key: "provider", value: "claude_managed" } },
|
|
},
|
|
{
|
|
key: "maxSessionListCostUsd",
|
|
label: "Session spend ceiling (USD)",
|
|
type: "number" as const,
|
|
default: 1,
|
|
hint: "Hard ceiling for one Claude Managed session.",
|
|
meta: { visibleWhen: { key: "provider", value: "claude_managed" } },
|
|
},
|
|
{
|
|
key: "managedAgentsRetentionAcknowledged",
|
|
label: "Acknowledge managed retention",
|
|
type: "toggle" as const,
|
|
default: false,
|
|
hint: "Claude Managed is stateful beta and is not eligible for ZDR or HIPAA modes.",
|
|
meta: { visibleWhen: { key: "provider", value: "claude_managed" } },
|
|
},
|
|
{
|
|
key: "agentCoreProfileId",
|
|
label: "AgentCore profile",
|
|
type: "text" as const,
|
|
required: true,
|
|
hint: "Company-scoped qualified AgentCore profile ID or key.",
|
|
meta: { visibleWhen: { key: "provider", value: "aws_agentcore" } },
|
|
},
|
|
{
|
|
key: "maxEstimatedSessionCostUsd",
|
|
label: "Estimated session ceiling (USD)",
|
|
type: "number" as const,
|
|
default: 1,
|
|
hint: "Paperclip estimate; AWS does not provide a per-session currency hard stop.",
|
|
meta: { visibleWhen: { key: "provider", value: "aws_agentcore" } },
|
|
},
|
|
{
|
|
key: "maxIterations",
|
|
label: "Maximum iterations",
|
|
type: "number" as const,
|
|
default: 8,
|
|
hint: "Must be between 1 and the qualified maximum of 8.",
|
|
meta: { visibleWhen: { key: "provider", value: "aws_agentcore" } },
|
|
},
|
|
{
|
|
key: "maxOutputTokens",
|
|
label: "Maximum output tokens",
|
|
type: "number" as const,
|
|
default: 4_096,
|
|
hint: "Must be between 1 and the qualified maximum of 4096.",
|
|
meta: { visibleWhen: { key: "provider", value: "aws_agentcore" } },
|
|
},
|
|
{
|
|
key: "timeoutSeconds",
|
|
label: "Invocation timeout (seconds)",
|
|
type: "number" as const,
|
|
default: 300,
|
|
hint: "Must be between 1 and the qualified maximum of 300 seconds.",
|
|
meta: { visibleWhen: { key: "provider", value: "aws_agentcore" } },
|
|
},
|
|
{
|
|
key: "agentCoreRetentionAcknowledged",
|
|
label: "Acknowledge 90-day Memory retention",
|
|
type: "toggle" as const,
|
|
default: false,
|
|
hint: "The qualified AgentCore profile retains short-term Memory events for 90 days.",
|
|
meta: { visibleWhen: { key: "provider", value: "aws_agentcore" } },
|
|
},
|
|
{
|
|
key: "lifecycleMode",
|
|
label: "Runner lifecycle",
|
|
type: "select" as const,
|
|
default: "per_turn",
|
|
options: [
|
|
{ value: "per_turn", label: "Turn by turn" },
|
|
{ value: "warm", label: "Warm session" },
|
|
],
|
|
hint: "Warm sessions retain runnerd and Codex between governed runs.",
|
|
},
|
|
{
|
|
key: "idleTimeoutMs",
|
|
label: "Warm idle timeout (ms)",
|
|
type: "number" as const,
|
|
default: 300_000,
|
|
hint: "Warm sessions suspend after this much inactivity.",
|
|
meta: { visibleWhen: { key: "lifecycleMode", value: "warm" } },
|
|
},
|
|
],
|
|
}),
|
|
loginCapability: codexLoginCapability,
|
|
};
|
|
|
|
const cursorLocalAdapter: ServerAdapterModule = {
|
|
type: "cursor",
|
|
runtimeToolDelivery: "environment",
|
|
execute: cursorExecute,
|
|
testEnvironment: cursorTestEnvironment,
|
|
listSkills: listCursorSkills,
|
|
syncSkills: syncCursorSkills,
|
|
sessionCodec: cursorSessionCodec,
|
|
sessionManagement: getAdapterSessionManagement("cursor") ?? undefined,
|
|
supportsToolRefreshOnResume: true,
|
|
models: cursorModels,
|
|
listModels: listCursorModels,
|
|
supportsLocalAgentJwt: true,
|
|
supportsInstructionsBundle: true,
|
|
instructionsPathKey: "instructionsFilePath",
|
|
requiresMaterializedRuntimeSkills: true,
|
|
getRuntimeCommandSpec: buildCursorRuntimeCommandSpec,
|
|
agentConfigurationDoc: cursorAgentConfigurationDoc,
|
|
};
|
|
|
|
const cursorCloudAdapter: ServerAdapterModule = {
|
|
type: "cursor_cloud",
|
|
runtimeToolDelivery: "invocation_context",
|
|
execute: cursorCloudExecute,
|
|
testEnvironment: cursorCloudTestEnvironment,
|
|
sessionCodec: cursorCloudSessionCodec,
|
|
sessionManagement: getAdapterSessionManagement("cursor_cloud") ?? undefined,
|
|
models: [],
|
|
supportsLocalAgentJwt: false,
|
|
supportsInstructionsBundle: true,
|
|
instructionsPathKey: "instructionsFilePath",
|
|
requiresMaterializedRuntimeSkills: false,
|
|
agentConfigurationDoc: cursorCloudAgentConfigurationDoc,
|
|
getConfigSchema: getCursorCloudConfigSchema,
|
|
};
|
|
|
|
const geminiLocalAdapter: ServerAdapterModule = {
|
|
type: "gemini_local",
|
|
runtimeToolDelivery: "environment",
|
|
execute: geminiExecute,
|
|
testEnvironment: geminiTestEnvironment,
|
|
acp: {
|
|
agentId: "gemini",
|
|
skillsMode: "ephemeral",
|
|
prerequisites: {
|
|
nodeRange: ">=24.11.0",
|
|
packages: ["@google/gemini-cli"],
|
|
},
|
|
},
|
|
listSkills: listGeminiSkills,
|
|
syncSkills: syncGeminiSkills,
|
|
sessionCodec: geminiSessionCodec,
|
|
sessionManagement: getAdapterSessionManagement("gemini_local") ?? undefined,
|
|
supportsToolRefreshOnResume: true,
|
|
models: geminiModels,
|
|
supportsLocalAgentJwt: true,
|
|
supportsInstructionsBundle: true,
|
|
instructionsPathKey: "instructionsFilePath",
|
|
requiresMaterializedRuntimeSkills: true,
|
|
getRuntimeCommandSpec: (config) =>
|
|
buildNpmRuntimeCommandSpec(config, "gemini", "@google/gemini-cli"),
|
|
agentConfigurationDoc: geminiAgentConfigurationDoc,
|
|
getConfigSchema: getGeminiConfigSchema,
|
|
};
|
|
|
|
const grokLocalAdapter: ServerAdapterModule = {
|
|
type: "grok_local",
|
|
runtimeToolDelivery: "environment",
|
|
execute: grokExecute,
|
|
testEnvironment: grokTestEnvironment,
|
|
listSkills: listGrokSkills,
|
|
syncSkills: syncGrokSkills,
|
|
sessionCodec: grokSessionCodec,
|
|
sessionManagement: getAdapterSessionManagement("grok_local") ?? undefined,
|
|
supportsToolRefreshOnResume: true,
|
|
models: grokModels,
|
|
supportsLocalAgentJwt: true,
|
|
supportsInstructionsBundle: true,
|
|
instructionsPathKey: "instructionsFilePath",
|
|
requiresMaterializedRuntimeSkills: true,
|
|
getRuntimeCommandSpec: (config) => ({
|
|
command: readConfiguredCommand(config, "grok"),
|
|
detectCommand: readConfiguredCommand(config, "grok"),
|
|
installCommand: null,
|
|
}),
|
|
agentConfigurationDoc: grokAgentConfigurationDoc,
|
|
loginCapability: grokLoginCapability,
|
|
};
|
|
|
|
const kimiLocalAdapter: ServerAdapterModule = {
|
|
type: "kimi_local",
|
|
runtimeToolDelivery: "environment",
|
|
execute: kimiExecute,
|
|
testEnvironment: kimiTestEnvironment,
|
|
acp: {
|
|
agentId: "kimi",
|
|
skillsMode: "ephemeral",
|
|
prerequisites: {
|
|
nodeRange: ">=20.0.0",
|
|
packages: ["@moonshot-ai/kimi-code"],
|
|
},
|
|
},
|
|
listSkills: listKimiSkills,
|
|
syncSkills: syncKimiSkills,
|
|
sessionCodec: kimiSessionCodec,
|
|
sessionManagement: getAdapterSessionManagement("kimi_local") ?? undefined,
|
|
supportsToolRefreshOnResume: true,
|
|
models: kimiModels,
|
|
supportsLocalAgentJwt: true,
|
|
supportsInstructionsBundle: true,
|
|
instructionsPathKey: "instructionsFilePath",
|
|
requiresMaterializedRuntimeSkills: true,
|
|
getRuntimeCommandSpec: (config) =>
|
|
buildNpmRuntimeCommandSpec(config, "kimi", "@moonshot-ai/kimi-code"),
|
|
agentConfigurationDoc: kimiAgentConfigurationDoc,
|
|
};
|
|
|
|
const hermesGatewayAdapter: ServerAdapterModule = {
|
|
...createHermesGatewayServerAdapter(),
|
|
runtimeToolDelivery: "invocation_context",
|
|
};
|
|
|
|
const hermesLocalAdapter: ServerAdapterModule = {
|
|
...createHermesLocalServerAdapter(),
|
|
runtimeToolDelivery: "environment",
|
|
};
|
|
|
|
const openclawGatewayAdapter: ServerAdapterModule = {
|
|
type: "openclaw_gateway",
|
|
runtimeToolDelivery: "invocation_context",
|
|
execute: openclawGatewayExecute,
|
|
testEnvironment: openclawGatewayTestEnvironment,
|
|
models: openclawGatewayModels,
|
|
supportsLocalAgentJwt: false,
|
|
supportsInstructionsBundle: false,
|
|
requiresMaterializedRuntimeSkills: false,
|
|
agentConfigurationDoc: openclawGatewayAgentConfigurationDoc,
|
|
};
|
|
|
|
const openCodeLocalAdapter: ServerAdapterModule = {
|
|
type: "opencode_local",
|
|
runtimeToolDelivery: "environment",
|
|
execute: openCodeExecute,
|
|
testEnvironment: openCodeTestEnvironment,
|
|
listSkills: listOpenCodeSkills,
|
|
syncSkills: syncOpenCodeSkills,
|
|
sessionCodec: openCodeSessionCodec,
|
|
models: openCodeModels,
|
|
sessionManagement: getAdapterSessionManagement("opencode_local") ?? undefined,
|
|
supportsToolRefreshOnResume: true,
|
|
listModels: listOpenCodeModels,
|
|
supportsLocalAgentJwt: true,
|
|
supportsInstructionsBundle: true,
|
|
instructionsPathKey: "instructionsFilePath",
|
|
requiresMaterializedRuntimeSkills: true,
|
|
getRuntimeCommandSpec: (config) => buildNpmRuntimeCommandSpec(config, "opencode", "opencode-ai"),
|
|
agentConfigurationDoc: openCodeAgentConfigurationDoc,
|
|
};
|
|
|
|
const piLocalAdapter: ServerAdapterModule = {
|
|
type: "pi_local",
|
|
runtimeToolDelivery: "environment",
|
|
execute: piExecute,
|
|
testEnvironment: piTestEnvironment,
|
|
listSkills: listPiSkills,
|
|
syncSkills: syncPiSkills,
|
|
sessionCodec: piSessionCodec,
|
|
sessionManagement: getAdapterSessionManagement("pi_local") ?? undefined,
|
|
supportsToolRefreshOnResume: true,
|
|
models: [],
|
|
listModels: listPiModels,
|
|
supportsLocalAgentJwt: true,
|
|
supportsInstructionsBundle: true,
|
|
instructionsPathKey: "instructionsFilePath",
|
|
requiresMaterializedRuntimeSkills: true,
|
|
getRuntimeCommandSpec: (config) =>
|
|
buildNpmRuntimeCommandSpec(config, "pi", "@mariozechner/pi-coding-agent"),
|
|
agentConfigurationDoc: piAgentConfigurationDoc,
|
|
};
|
|
|
|
const adaptersByType = new Map<string, ServerAdapterModule>();
|
|
|
|
// For builtin types that are overridden by an external adapter, we keep the
|
|
// original builtin so it can be restored when the override is deactivated.
|
|
const builtinFallbacks = new Map<string, ServerAdapterModule>();
|
|
|
|
// Tracks which override types are currently deactivated (paused). When
|
|
// paused, `getServerAdapter()` returns the builtin fallback instead of the
|
|
// external. Persisted across reloads via the same disabled-adapters store.
|
|
const pausedOverrides = new Set<string>();
|
|
|
|
function registerBuiltInAdapters() {
|
|
for (const adapter of [
|
|
acpxLocalAdapter,
|
|
claudeLocalAdapter,
|
|
codexLocalAdapter,
|
|
paperclipRunnerAdapter,
|
|
openCodeLocalAdapter,
|
|
piLocalAdapter,
|
|
cursorCloudAdapter,
|
|
cursorLocalAdapter,
|
|
geminiLocalAdapter,
|
|
grokLocalAdapter,
|
|
kimiLocalAdapter,
|
|
hermesGatewayAdapter,
|
|
hermesLocalAdapter,
|
|
openclawGatewayAdapter,
|
|
processAdapter,
|
|
httpAdapter,
|
|
]) {
|
|
adaptersByType.set(adapter.type, adapter);
|
|
}
|
|
}
|
|
|
|
registerBuiltInAdapters();
|
|
|
|
// ---------------------------------------------------------------------------
|
|
// Load external adapter plugins (e.g. droid_local)
|
|
//
|
|
// External adapter packages export createServerAdapter() which returns a
|
|
// ServerAdapterModule. When the module provides its own sessionManagement
|
|
// it is preserved; otherwise the host falls back to the built-in registry
|
|
// lookup (so externals that override a built-in type inherit the builtin's
|
|
// policy). This brings init-time registration to at-least-as-good behavior
|
|
// as the hot-install path (routes/adapters.ts:179 -> registerServerAdapter):
|
|
// both preserve module-provided sessionManagement, and init-time additionally
|
|
// applies the registry fallback for externals overriding a built-in type.
|
|
// ---------------------------------------------------------------------------
|
|
|
|
/**
|
|
* Merge an external adapter module with host-provided session management.
|
|
*
|
|
* Module-provided `sessionManagement` takes precedence. When absent, fall
|
|
* back to the hardcoded registry keyed by adapter type (so externals that
|
|
* override a built-in — same `type` — inherit the builtin's policy). If
|
|
* neither is available, `sessionManagement` remains `undefined`.
|
|
*
|
|
* Used by both the init-time IIFE below (external-adapter load pass on
|
|
* server start) and the hot-install path in `routes/adapters.ts`
|
|
* (`registerWithSessionManagement`), so the two load paths resolve
|
|
* `sessionManagement` identically.
|
|
*/
|
|
export function resolveExternalAdapterRegistration(
|
|
externalAdapter: ServerAdapterModule,
|
|
): ServerAdapterModule {
|
|
return {
|
|
...externalAdapter,
|
|
sessionManagement:
|
|
externalAdapter.sessionManagement
|
|
?? getAdapterSessionManagement(externalAdapter.type)
|
|
?? undefined,
|
|
};
|
|
}
|
|
|
|
/**
|
|
* Load external adapters from the plugin store and hardcoded sources.
|
|
* Called once at module initialization. The promise is exported so that
|
|
* callers (e.g. assertKnownAdapterType, app startup) can await completion
|
|
* and avoid racing against the loading window.
|
|
*/
|
|
const externalAdaptersReady: Promise<void> = (async () => {
|
|
if (isCloudManagedInstance()) return;
|
|
try {
|
|
const externalAdapters = await buildExternalAdapters();
|
|
for (const externalAdapter of externalAdapters) {
|
|
const overriding = BUILTIN_ADAPTER_TYPES.has(externalAdapter.type);
|
|
if (overriding) {
|
|
console.log(
|
|
`[paperclip] External adapter "${externalAdapter.type}" overrides built-in adapter`,
|
|
);
|
|
// Save the original builtin for later restoration.
|
|
const existing = adaptersByType.get(externalAdapter.type);
|
|
if (existing && !builtinFallbacks.has(externalAdapter.type)) {
|
|
builtinFallbacks.set(externalAdapter.type, existing);
|
|
}
|
|
}
|
|
adaptersByType.set(
|
|
externalAdapter.type,
|
|
resolveExternalAdapterRegistration(externalAdapter),
|
|
);
|
|
}
|
|
} catch (err) {
|
|
console.error("[paperclip] Failed to load external adapters:", err);
|
|
}
|
|
})();
|
|
|
|
/**
|
|
* Await this before validating adapter types to avoid race conditions
|
|
* during server startup. External adapters are loaded asynchronously;
|
|
* calling assertKnownAdapterType before this resolves will reject
|
|
* valid external adapter types.
|
|
*/
|
|
export function waitForExternalAdapters(): Promise<void> {
|
|
return externalAdaptersReady;
|
|
}
|
|
|
|
export function registerServerAdapter(adapter: ServerAdapterModule): void {
|
|
assertExternalAdapterCodeAllowed();
|
|
if (BUILTIN_ADAPTER_TYPES.has(adapter.type) && !builtinFallbacks.has(adapter.type)) {
|
|
const existing = adaptersByType.get(adapter.type);
|
|
if (existing) {
|
|
builtinFallbacks.set(adapter.type, existing);
|
|
}
|
|
}
|
|
adaptersByType.set(adapter.type, adapter);
|
|
}
|
|
|
|
export function unregisterServerAdapter(type: string): void {
|
|
assertExternalAdapterCodeAllowed();
|
|
if (type === processAdapter.type || type === httpAdapter.type) return;
|
|
if (builtinFallbacks.has(type)) {
|
|
pausedOverrides.delete(type);
|
|
const fallback = builtinFallbacks.get(type);
|
|
if (fallback) {
|
|
adaptersByType.set(type, fallback);
|
|
}
|
|
return;
|
|
}
|
|
if (BUILTIN_ADAPTER_TYPES.has(type)) {
|
|
return;
|
|
}
|
|
adaptersByType.delete(type);
|
|
}
|
|
|
|
export function requireServerAdapter(type: string): ServerAdapterModule {
|
|
const adapter = findActiveServerAdapter(type);
|
|
if (!adapter) {
|
|
throw new Error(`Unknown adapter type: ${type}`);
|
|
}
|
|
return adapter;
|
|
}
|
|
|
|
export function getServerAdapter(type: string): ServerAdapterModule {
|
|
return findActiveServerAdapter(type) ?? processAdapter;
|
|
}
|
|
|
|
/**
|
|
* Memoized view of PAPERCLIP_ADAPTER_MODELS, keyed by the raw env string so
|
|
* tests (and live env mutation) that change the variable are still observed.
|
|
* Parsing happens at most once per distinct raw value instead of per
|
|
* `listAdapterModels` request, and malformed values fail SOFT here: we log the
|
|
* parse error once (per distinct raw value) and fall back to adapter-discovered
|
|
* models rather than throwing at request time.
|
|
*/
|
|
let adapterModelsEnvCache: {
|
|
raw: string | undefined;
|
|
value: ReturnType<typeof parseAdapterModelsEnv>;
|
|
} | null = null;
|
|
|
|
function getDeclaredAdapterModels(): ReturnType<typeof parseAdapterModelsEnv> {
|
|
const raw = process.env.PAPERCLIP_ADAPTER_MODELS;
|
|
if (adapterModelsEnvCache && adapterModelsEnvCache.raw === raw) {
|
|
return adapterModelsEnvCache.value;
|
|
}
|
|
let value: ReturnType<typeof parseAdapterModelsEnv> = null;
|
|
try {
|
|
value = parseAdapterModelsEnv(process.env);
|
|
} catch (err) {
|
|
console.error(
|
|
"[paperclip] Invalid PAPERCLIP_ADAPTER_MODELS; ignoring declared model lists:",
|
|
err,
|
|
);
|
|
}
|
|
adapterModelsEnvCache = { raw, value };
|
|
return value;
|
|
}
|
|
|
|
function declaredModelsForAdapter(type: string): { id: string; label: string }[] | null {
|
|
const declared = getDeclaredAdapterModels()?.[type];
|
|
return declared?.length
|
|
? declared.map((model) => ({ id: model.id, label: model.label ?? model.id }))
|
|
: null;
|
|
}
|
|
|
|
export async function listAdapterModels(type: string): Promise<{ id: string; label: string }[]> {
|
|
const declaredModels = declaredModelsForAdapter(type);
|
|
if (declaredModels) return declaredModels;
|
|
const adapter = findActiveServerAdapter(type);
|
|
if (!adapter) return [];
|
|
// The built-in Codex adapter's OpenAI discovery includes image, audio, and
|
|
// embedding models that Codex cannot run. Use its curated list; declared
|
|
// models above and custom adapter discovery remain authoritative.
|
|
if (adapter === codexLocalAdapter) return adapter.models ?? [];
|
|
if (adapter.listModels) {
|
|
const discovered = await adapter.listModels();
|
|
if (discovered.length > 0) return discovered;
|
|
}
|
|
return adapter.models ?? [];
|
|
}
|
|
|
|
export async function refreshAdapterModels(type: string): Promise<{ id: string; label: string }[]> {
|
|
const declaredModels = declaredModelsForAdapter(type);
|
|
if (declaredModels) return declaredModels;
|
|
if (findActiveServerAdapter(type) === codexLocalAdapter) return listAdapterModels(type);
|
|
const adapter = findActiveServerAdapter(type);
|
|
if (!adapter) return [];
|
|
if (adapter.refreshModels) {
|
|
const refreshed = await adapter.refreshModels();
|
|
if (refreshed.length > 0) return refreshed;
|
|
}
|
|
if (adapter.listModels) {
|
|
const discovered = await adapter.listModels();
|
|
if (discovered.length > 0) return discovered;
|
|
}
|
|
return adapter.models ?? [];
|
|
}
|
|
|
|
export function listServerAdapters(): ServerAdapterModule[] {
|
|
return Array.from(adaptersByType.values());
|
|
}
|
|
|
|
/**
|
|
* List adapters excluding those that are disabled in settings.
|
|
* Used for menus and agent creation flows — disabled adapters remain
|
|
* functional for existing agents but hidden from selection.
|
|
*/
|
|
export function listEnabledServerAdapters(disabled: string[]): ServerAdapterModule[] {
|
|
const disabledSet = disabled.length > 0 ? new Set(disabled) : null;
|
|
return disabledSet
|
|
? Array.from(adaptersByType.values()).filter((a) => !disabledSet.has(a.type))
|
|
: Array.from(adaptersByType.values());
|
|
}
|
|
|
|
export async function detectAdapterModel(
|
|
type: string,
|
|
): Promise<{ model: string; provider: string; source: string; candidates?: string[] } | null> {
|
|
const adapter = findActiveServerAdapter(type);
|
|
if (!adapter?.detectModel) return null;
|
|
const detected = await adapter.detectModel();
|
|
if (!detected) return null;
|
|
return {
|
|
model: detected.model,
|
|
provider: detected.provider,
|
|
source: detected.source,
|
|
...(detected.candidates?.length ? { candidates: detected.candidates } : {}),
|
|
};
|
|
}
|
|
|
|
// ---------------------------------------------------------------------------
|
|
// Override pause / resume
|
|
// ---------------------------------------------------------------------------
|
|
|
|
/**
|
|
* Pause or resume an external override for a builtin adapter type.
|
|
*
|
|
* - `paused = true` → subsequent calls to `getServerAdapter(type)` return
|
|
* the builtin fallback instead of the external adapter. Already-running
|
|
* agent sessions are unaffected (they hold a reference to the module they
|
|
* started with).
|
|
*
|
|
* - `paused = false` → the external adapter is active again.
|
|
*
|
|
* Returns `true` if the state actually changed, `false` if the type is not
|
|
* an override or was already in the requested state.
|
|
*/
|
|
export function setOverridePaused(type: string, paused: boolean): boolean {
|
|
assertExternalAdapterCodeAllowed();
|
|
if (!builtinFallbacks.has(type)) return false;
|
|
const wasPaused = pausedOverrides.has(type);
|
|
if (paused && !wasPaused) {
|
|
pausedOverrides.add(type);
|
|
console.log(`[paperclip] Override paused for "${type}" — builtin adapter restored`);
|
|
return true;
|
|
}
|
|
if (!paused && wasPaused) {
|
|
pausedOverrides.delete(type);
|
|
console.log(`[paperclip] Override resumed for "${type}" — external adapter active`);
|
|
return true;
|
|
}
|
|
return false;
|
|
}
|
|
|
|
/** Check whether the external override for a builtin type is currently paused. */
|
|
export function isOverridePaused(type: string): boolean {
|
|
return pausedOverrides.has(type);
|
|
}
|
|
|
|
export function hasActiveAdapterOverride(type: string): boolean {
|
|
const registered = adaptersByType.get(type);
|
|
return builtinFallbacks.has(type) && registered !== undefined
|
|
&& registered !== builtinFallbacks.get(type) && !pausedOverrides.has(type);
|
|
}
|
|
|
|
/** Get the set of types whose overrides are currently paused. */
|
|
export function getPausedOverrides(): Set<string> {
|
|
return pausedOverrides;
|
|
}
|
|
|
|
export function findServerAdapter(type: string): ServerAdapterModule | null {
|
|
return adaptersByType.get(type) ?? null;
|
|
}
|
|
|
|
export function findActiveServerAdapter(type: string): ServerAdapterModule | null {
|
|
if (pausedOverrides.has(type)) {
|
|
const fallback = builtinFallbacks.get(type);
|
|
if (fallback) return fallback;
|
|
}
|
|
return adaptersByType.get(type) ?? null;
|
|
}
|