Preserve native provider compatibility and clean partial SSH uploads

Apply preconfigured SSH homes only to supported native providers and permission modes. Preserve isolated mode for OpenCode, Copilot, and restricted Claude while retaining admitted recovery input. Stage host-auth Codex runtime files in private SSH directories so existing cleanup owns partial uploads. Read the selected remote profile before creating its tracing overlay.

Eight new regressions first failed. Verified 21 focused cases and 229 tests across six broader adapter, runtime, configuration, and provider suites. Adapter-utils, Claude, Codex, and server typechecks pass. SDK source, whitespace, and secret scans pass. Fresh CI and Apex review remain required.

Co-Authored-By: Paperclip <noreply@paperclip.ing>
This commit is contained in:
Devin FoleyandPaperclip committed 2026-11-13 10:01:52 -08:00
1 parent 1865127a38
commit a38694571e
10 files changed
+120 -23

No files matched your search

+9 -1
View File
@@ -452,6 +452,10 @@ retains its original home contract. Fresh native Runner launch uses the effectiv
SSH authentication choice. Native Codex Test uses that remote user's login in
preconfigured mode, without reading or staging controller credentials. Remote
home discovery uses the SSH shell, including on machines without `getent`.
Native preconfigured homes support Codex and ACPX Claude with `approve-all`.
Other native providers, and Claude with stricter permissions, retain their
supported isolated home mode on SSH. Explicitly unsupported preconfigured
provider configurations outside this SSH compatibility choice still fail.
Codex CLI host-auth runs also receive the current Paperclip MCP configuration
and authorized skills. Paperclip merges its managed block into the remote
@@ -460,7 +464,11 @@ The native remote home retains authentication and conversation files; they are
not uploaded from or copied back to the controller. This mode shares the remote
user's configuration. Use separate SSH users when independent configuration is
required. Run-specific skill files are removed at teardown, and the next run
replaces or removes the managed skill links.
replaces or removes the managed skill links. Host-auth runtime files use private
SSH staging, with cleanup registered before upload so partial uploads are removed.
When company tracing is enabled with a selected remote Codex profile, the overlay
reads that profile from the remote home and preserves its other settings. Missing
or linked profile files disable export for that run; execution continues.
Managed SSH runs stage the selected account into a randomly allocated directory
with owner-only access and set the harness's home/configuration paths there.
@@ -1574,7 +1574,7 @@ export async function prepareAdapterExecutionTargetRuntime(input: {
workspaceLocalDir: input.workspaceLocalDir,
workspaceRemoteDir: input.workspaceRemoteDir,
syncWorkspace: input.syncWorkspace,
privateRuntime: input.privateRuntime && target.spec.useHostAuth === false,
privateRuntime: input.privateRuntime,
retainRuntime: input.retainRuntime,
workspaceFileMode: input.workspaceFileMode,
workspaceExclude: input.workspaceExclude,
@@ -301,7 +301,7 @@ describe("codex remote execution", () => {
}
});
it.each(["default", "configured", "in_place", "no_config", "observability", "unqualified_observability", "changed_config", "skill_conflict"])("delivers Codex tools and skills while preserving native SSH authentication (%s)", async mode => {
it.each(["default", "configured", "in_place", "no_config", "observability", "unqualified_observability", "observability_profile", "observability_profile_missing", "observability_profile_symlink", "partial_upload", "partial_upload_in_place", "changed_config", "skill_conflict"])("delivers Codex tools and skills while preserving native SSH authentication (%s)", async mode => {
const root = await mkdtemp(path.join(os.tmpdir(), "paperclip-codex-host-auth-"));
cleanupDirs.push(root);
const workspace = path.join(root, "workspace"), remote = path.join(root, "remote-workspace"), userHome = path.join(root, "remote-user");
@@ -310,6 +310,14 @@ describe("codex remote execution", () => {
for (const dir of [workspace, remote, native, controller, skill, path.join(native, "skills", "manual")]) await mkdir(dir, { recursive: true });
await writeFile(path.join(controller, "auth.json"), '{"tokens":{"account_id":"controller-only","refresh_token":"fixture-controller-token"}}');
await writeFile(path.join(native, "auth.json"), "fixture-native-login");
if (mode.startsWith("observability_profile")) {
if (mode === "observability_profile") await writeFile(path.join(native, "work.config.toml"), 'model = "remote-profile-model"\n');
else if (mode === "observability_profile_symlink") {
await writeFile(path.join(native, "linked.config.toml"), 'model = "remote-linked-model"\n');
await symlink(path.join(native, "linked.config.toml"), path.join(native, "work.config.toml"));
}
await writeFile(path.join(controller, "work.config.toml"), 'model = "controller-profile-model"\n');
}
if (mode !== "no_config") await writeFile(path.join(native, "config.toml"), 'model = "native-model"\n[mcp_servers.tools]\nurl = "https://native.example.test/mcp"\n');
if (mode === "skill_conflict") {
await mkdir(path.join(native, "skills", "review"));
@@ -334,13 +342,25 @@ describe("codex remote execution", () => {
await expect(stat(path.join(input!.localDir, "auth.json"))).rejects.toMatchObject({ code: "ENOENT" });
await mkdir(input!.remoteDir, { recursive: true });
await cp(input!.localDir, input!.remoteDir, { recursive: true, dereference: true });
if (mode.startsWith("partial_upload")) throw new Error("fixture partial SSH upload");
});
runChildProcess.mockImplementation(async (...args: unknown[]) => {
if ((args[2] as string[]).includes("--version")) return { exitCode: 0, signal: null, timedOut: false, stdout: mode === "unqualified_observability" ? "codex-cli 0.159.0\n" : "codex-cli 0.160.0\n", stderr: "", pid: 123, startedAt: new Date().toISOString() };
const env = (args[3] as { env: Record<string, string> }).env;
expect(env.CODEX_HOME).toBe(native);
expect(env.HOME).toBeUndefined();
if (mode.endsWith("observability")) expect(await readFile(path.join(native, `paperclip-observability-${calls === 0 ? "remote-auth" : "remote-auth-next"}.config.toml`), "utf8")).toContain("otel");
if (mode.includes("observability") && !mode.endsWith("_missing") && !mode.endsWith("_symlink")) expect(await readFile(path.join(native, `paperclip-observability-${calls === 0 ? "remote-auth" : "remote-auth-next"}.config.toml`), "utf8")).toContain("otel");
if (mode === "observability_profile_missing" || mode === "observability_profile_symlink") {
expect(args[2]).toEqual(expect.arrayContaining(["--profile", "work", 'otel.exporter="none"']));
}
if (mode === "observability_profile") {
const profileName = `paperclip-observability-${calls === 0 ? "remote-auth" : "remote-auth-next"}`;
const profile = await readFile(path.join(native, `${profileName}.config.toml`), "utf8");
expect(profile).toContain('model = "remote-profile-model"');
expect(profile).toContain("https://collector.example.test/v1/logs");
expect(args[2]).toEqual(expect.arrayContaining(["--profile", profileName]));
expect(await readFile(path.join(native, "work.config.toml"), "utf8")).toBe('model = "remote-profile-model"\n');
}
expect(await readFile(path.join(native, "auth.json"), "utf8")).toBe(calls === 0 ? "fixture-native-login" : "fixture-native-refreshed");
const config = await readFile(path.join(native, "config.toml"), "utf8");
if (mode !== "no_config") {
@@ -360,23 +380,23 @@ describe("codex remote execution", () => {
return { exitCode: 0, signal: null, timedOut: false, stdout: '{"type":"turn.completed","usage":{"input_tokens":1,"output_tokens":1}}\n', stderr: "", pid: 123, startedAt: new Date().toISOString() };
});
const ctx = { runId: "remote-auth",
observability: mode.endsWith("observability") ? buildProviderObservabilityLaunch({ kind: "codex", companyId: "company-1", agentId: "agent-1", revision: "revision", compatibilityKey: "fixture", enabled: false, capture: { userPrompts: false, assistantResponses: false, toolDetails: false, toolContent: false } }) : undefined,
observability: mode.includes("observability") ? buildProviderObservabilityLaunch({ kind: "codex", companyId: "company-1", agentId: "agent-1", revision: "revision", compatibilityKey: "fixture", enabled: mode.startsWith("observability_profile"), logsEndpoint: "https://collector.example.test/v1/logs", tracesEndpoint: "https://collector.example.test/v1/traces", capture: { userPrompts: false, assistantResponses: false, toolDetails: false, toolContent: false } }) : undefined,
agent: { id: "agent-1", companyId: "company-1", name: "Remote auth", adapterType: "codex_local", adapterConfig: {} },
runtime: { sessionId: null, sessionParams: null, sessionDisplayId: null, taskKey: null },
config: { engine: "cli", command: "codex", env: mode === "configured" ? { CODEX_HOME: native } : {},
config: { engine: "cli", command: "codex", ...(mode.startsWith("observability_profile") ? { extraArgs: ["--profile", "work"] } : {}), env: mode === "configured" ? { CODEX_HOME: native } : {},
paperclipRuntimeSkills: [{ key: "company/review", runtimeName: "review", source: skill }], paperclipSkillSync: { desiredSkills: ["company/review"] } },
context: { paperclipWorkspace: { cwd: workspace, source: "project_primary" }, paperclipManagedMcp: { managedMcpOnly: true, gateways: [{ name: "tools", endpointPath: "/managed-mcp", bearerToken: "fixture-managed-gateway" }] } },
executionTarget: { kind: "remote" as const, transport: "ssh" as const, remoteCwd: remote,
spec: { useHostAuth: true, host: "127.0.0.1", port: 2222, username: "fixture", remoteCwd: remote, remoteWorkspacePath: remote, privateKey: null, knownHosts: null, strictHostKeyChecking: true },
workspaceRealization: { mode: (mode === "in_place" ? "in_place" : "copy") as "in_place" | "copy", authoritativeRoot: remote, pathAliases: [], outboundRestorePaths: [] } }, onLog: async () => {},
workspaceRealization: { mode: ((mode === "in_place" || mode === "partial_upload_in_place") ? "in_place" : "copy") as "in_place" | "copy", authoritativeRoot: remote, pathAliases: [], outboundRestorePaths: [] } }, onLog: async () => {},
};
if (mode === "changed_config" || mode === "skill_conflict") {
await expect(execute(ctx)).rejects.toThrow("Cannot install remote Codex runtime configuration");
if (mode === "changed_config" || mode === "skill_conflict" || mode.startsWith("partial_upload")) {
await expect(execute(ctx)).rejects.toThrow(mode.startsWith("partial_upload") ? "fixture partial SSH upload" : "Cannot install remote Codex runtime configuration");
expect(runChildProcess).not.toHaveBeenCalled();
expect(await readFile(path.join(native, "auth.json"), "utf8")).toBe("fixture-native-login");
if (mode === "changed_config") expect(await readFile(path.join(native, "config.toml"), "utf8")).toBe('model = "changed-during-setup"\n');
else expect(await readFile(path.join(native, "skills", "review", "SKILL.md"), "utf8")).toBe("native review skill");
expect(restoreWorkspaceFromSshExecution).toHaveBeenCalledTimes(1);
else if (mode === "skill_conflict") expect(await readFile(path.join(native, "skills", "review", "SKILL.md"), "utf8")).toBe("native review skill");
expect(restoreWorkspaceFromSshExecution).toHaveBeenCalledTimes(mode === "partial_upload_in_place" ? 0 : 1);
} else {
expect((await execute(ctx)).exitCode).toBe(0);
expect((await execute({ ...ctx, runId: "remote-auth-next", config: { ...ctx.config, paperclipRuntimeSkills: [] }, context: { ...ctx.context, paperclipManagedMcp: { managedMcpOnly: true, gateways: [] } } })).exitCode).toBe(0);
@@ -12,7 +12,7 @@ import { inferOpenAiCompatibleBiller, resolveManagedOpenAiBilling, type AdapterE
import { buildCodexAuthInboundProvision } from "./codex-auth-merge-scripts.js";
import { copyBackCodexAuth } from "./codex-auth-copyback.js";
import { prepareCodexSshSessionState } from "./ssh-session-state.js";
import { readCodexSshHostHome, buildCodexSshHostRuntimeInstall } from "./ssh-host-runtime.js";
import { readCodexSshHostHome, readCodexSshHostProfile, buildCodexSshHostRuntimeInstall } from "./ssh-host-runtime.js";
import { shellQuote } from "@paperclipai/adapter-utils/ssh";
import {
ensureCodexAuthCacheEntryDir,
@@ -792,16 +792,17 @@ export async function execute(ctx: AdapterExecutionContext): Promise<AdapterExec
let sshSessionState: Awaited<ReturnType<typeof prepareCodexSshSessionState>> | null = null;
let observabilityProfile: Awaited<ReturnType<typeof prepareCodexObservabilityProfile>> | null = null;
let observabilityPreparationFailed = false;
const runSshHostConfigurationCommand = async (command: string) => {
const result = await runAdapterExecutionTargetShellCommand(runId, executionTarget, command, { cwd: "/", env: {}, timeoutSec: 15 });
if (result.exitCode !== 0 || result.timedOut) throw new Error("Cannot read remote Codex configuration");
return result;
};
try {
if (useSshHostAuth) {
stagedCodexHomeDir = await fs.mkdtemp(path.join(os.tmpdir(), "paperclip-codex-host-runtime-"));
sshHostHome = await readCodexSshHostHome({
configuredHome: asString(envConfig.CODEX_HOME, "") || undefined,
run: async command => {
const result = await runAdapterExecutionTargetShellCommand(runId, executionTarget, command, { cwd: "/", env: {}, timeoutSec: 15 });
if (result.exitCode !== 0 || result.timedOut) throw new Error("Cannot read remote Codex configuration");
return result;
},
run: runSshHostConfigurationCommand,
});
await fs.writeFile(path.join(stagedCodexHomeDir, "config.toml"), sshHostHome.config, { mode: 0o600 });
await fs.writeFile(path.join(stagedCodexHomeDir, ".paperclip-native-config-before"), sshHostHome.config, { mode: 0o600 });
@@ -810,8 +811,13 @@ export async function execute(ctx: AdapterExecutionContext): Promise<AdapterExec
if (ctx.observability) {
if (useSshHostAuth || isManagedCodexHomePath(process.env, agent.companyId, effectiveCodexHome)) {
try {
const sourceProfile = selectedCodexProfile(buildCodexExecArgs(config).args);
if (sshHostHome && sourceProfile) {
const content = await readCodexSshHostProfile({ home: sshHostHome.home, profile: sourceProfile, run: runSshHostConfigurationCommand });
await fs.writeFile(path.join(runtimeConfigurationHome, `${sourceProfile}.config.toml`), content, { mode: 0o600 });
}
observabilityProfile = await prepareCodexObservabilityProfile({ home: runtimeConfigurationHome, runId,
launch: ctx.observability, sourceProfile: selectedCodexProfile(buildCodexExecArgs(config).args) });
launch: ctx.observability, sourceProfile });
} catch {
observabilityPreparationFailed = true;
await onLog("stderr", "[paperclip] Company observability configuration could not be prepared; execution continues with export disabled.\n");
@@ -880,10 +886,10 @@ export async function execute(ctx: AdapterExecutionContext): Promise<AdapterExec
// 4-name denylist missed and that a sandbox run never needs.
if (!useSshHostAuth) stagedCodexHomeDir = await stageCodexHomeForSync(effectiveCodexHome, { runId, additionalFiles: observabilityProfile ? [observabilityProfile.filename] : [] });
const prepared = await prepareAdapterExecutionTargetRuntime({
privateRuntime: Boolean(config.managedAiConnection),
privateRuntime: useSshHostAuth || Boolean(config.managedAiConnection),
runId,
target: executionTarget,
adapterKey: useSshHostAuth ? `codex-host-${createHash("sha256").update(runId).digest("hex")}` : "codex",
adapterKey: "codex",
timeoutSec,
workspaceLocalDir: cwd,
workspaceRemoteDir:
@@ -16,6 +16,17 @@ if [ -e "$native_codex_home/config.toml" ]; then printf 'present\\n'; base64 < "
return { home, config: Buffer.from(encodedConfig.join(""), "base64").toString("utf8"), exists: status === "present" };
}
export async function readCodexSshHostProfile(input: {
home: string; profile: string; run: (command: string) => Promise<{ stdout: string }>;
}): Promise<string> {
if (!/^[A-Za-z0-9_-]+$/.test(input.profile)) throw new Error("Invalid remote Codex profile");
const result = await input.run(`set -eu
profile_file=${shellQuote(`${input.home}/${input.profile}.config.toml`)}
test -f "$profile_file" && test ! -L "$profile_file"
base64 < "$profile_file"`);
return Buffer.from(result.stdout, "base64").toString("utf8");
}
export function buildCodexSshHostRuntimeInstall(input: { home: string; assetDir: string; exists: boolean; profileFilename?: string }): string {
if (input.profileFilename && !/^[A-Za-z0-9_-]+\.config\.toml$/.test(input.profileFilename)) throw new Error("Invalid Codex runtime profile");
const script = `set -eu
@@ -389,6 +389,21 @@ describePostgres("heartbeat execution configuration through adapter dispatch", (
}
});
it.each([
{ provider: "opencode", model: "openai/gpt-5" },
{ provider: "acpx", acpxAgent: "copilot", model: "gpt-5.6-luna" },
{ provider: "acpx", acpxAgent: "claude", model: "claude-sonnet-4-6", acpxPermissionMode: "approve-reads" },
])("keeps native SSH provider home support during preparation: $provider $acpxAgent", async config => {
const f = await seed();
const environment = { ...await environmentService(db).ensureLocalEnvironment(), driver: "ssh", config: {
host: "fixture.invalid", username: "fixture", remoteWorkspacePath: "/workspace",
} } as Environment;
const opening = await configuration(f, config, {}, "paperclip_runner", false, "shared_workspace", environment);
const result = await opening.prepare();
if (!result.prepared) throw new Error("SSH preparation failed");
expect(result.runtimeConfig.homeMode).toBe("isolated");
});
it("requires an agent AI account for a new SSH environment when remote authentication is off", async () => {
const f = await seed();
const environment = { ...await environmentService(db).ensureLocalEnvironment(), driver: "ssh", config: { useHostAuth: false } } as Environment;
@@ -1,3 +1,4 @@
import { supportsPaperclipRunnerPreconfiguredHome } from "../native-runtime/provider-profile.js";
import { agentHarnessType } from "@paperclipai/shared";
import { observabilitySecretValues } from "@paperclipai/adapter-utils/agent-observability";
import { agentObservabilityService, unavailableAgentObservability, type ResolvedAgentObservability } from "../agent-observability.js";
@@ -119,9 +120,13 @@ export async function prepareHeartbeatExecutionConfiguration(db: Db, input: Hear
const { issueId, context, responsibleUserId, acceptedPlanContinuationWake, acceptedPlanWakeRoutingDecision, taskProjectContext, routineEnvContext, pinnedSkillTest } = input.task;
const { selectedEnvironmentId, selectedEnvironmentForConfig, resolvedInstanceSettings, persistedNativeExecutionInput } = input.environment;
const useSshHostAuth = selectedEnvironmentForConfig?.driver === "ssh" && selectedEnvironmentForConfig.config.useHostAuth !== false && !persistedNativeExecutionInput;
let sshRunnerHomeMode: "isolated" | "preconfigured" | undefined;
if (agent.adapterType === "paperclip_runner" && selectedEnvironmentForConfig?.driver === "ssh" && !persistedNativeExecutionInput) {
sshRunnerHomeMode = useSshHostAuth && supportsPaperclipRunnerPreconfiguredHome(agent.adapterConfig, { companyId: agent.companyId }) ? "preconfigured" : "isolated";
}
const sourceWorkspaceConfig = agent.adapterType === "paperclip_runner"
? { ...input.config.sourceWorkspaceConfig,
homeMode: bindHeartbeatRunnerHomeMode({ ...parseObject(agent.adapterConfig), ...(selectedEnvironmentForConfig?.driver === "ssh" && !persistedNativeExecutionInput ? { homeMode: useSshHostAuth ? "preconfigured" : "isolated" } : {}) }, persistedNativeExecutionInput).homeMode }
homeMode: bindHeartbeatRunnerHomeMode({ ...parseObject(agent.adapterConfig), ...(sshRunnerHomeMode ? { homeMode: sshRunnerHomeMode } : {}) }, persistedNativeExecutionInput).homeMode }
: input.config.sourceWorkspaceConfig;
const preconfiguredHome = agent.adapterType === "paperclip_runner" && sourceWorkspaceConfig.homeMode === "preconfigured";
if (preconfiguredHome && pinnedSkillTest) {
@@ -198,6 +198,27 @@ describe.skipIf(!support.supported)("heartbeat runtime selection boundary", () =
expect((await read(f.run.id)).runnerProfileJson).toEqual(saved.runnerProfileJson);
});
it.each([
{ provider: "opencode", model: "openai/gpt-5" },
{ provider: "acpx", acpxAgent: "copilot", model: "gpt-5.6-luna" },
{ provider: "acpx", acpxAgent: "claude", model: "claude-sonnet-4-6", acpxPermissionMode: "approve-reads" },
])("retains supported isolated native selection for SSH host auth: $provider $acpxAgent", async adapterConfig => {
const f = await fixture();
f.input.agent = { ...f.agent, adapterConfig };
await db.update(agents).set({ adapterConfig }).where(eq(agents.id, f.agent.id));
f.input.workspace.executionTarget = { kind: "remote", transport: "ssh", remoteCwd: "/workspace", spec: {
host: "fixture.invalid", port: 22, username: "fixture", remoteWorkspacePath: "/workspace", remoteCwd: "/workspace",
useHostAuth: true, privateKey: null, knownHosts: null, strictHostKeyChecking: true,
} };
f.input.nativeRuntimeResolution = resolveHeartbeatNativeRuntimeMode({ persisted: f.run, enabled: true, runtimeConfig: {},
adapterConfig, agent: f.input.agent, issue: f.issue, target: f.input.workspace.executionTarget, workspaceId: null });
f.input.config.runtimeConfig.homeMode = "preconfigured";
const selected = await selectHeartbeatRuntime(db, f.input);
if (!selected.selected || !selected.nativeExecution) throw new Error("Expected native selection");
expect("homeMode" in selected.nativeExecution ? selected.nativeExecution.homeMode : "isolated").toBe("isolated");
expect(selected.nativeExecution.provider.kind).toBe(adapterConfig.provider === "acpx" ? "acpx" : "opencode");
});
it("preserves immutable native recovery when current local Runner configuration is invalid", async () => {
const f = await fixture();
const selected = await selectHeartbeatRuntime(db, f.input);
@@ -67,6 +67,7 @@ import {
assertManagedProfileRecoveryBinding,
projectPaperclipRunnerTaskConfig,
resolvePaperclipRunnerNativeProviderInput,
supportsPaperclipRunnerPreconfiguredHome,
} from "../native-runtime/provider-profile.js";
import { readRemoteCodexModelCliVersion } from "../native-runtime/codex-model-fallback.js";
import {
@@ -784,8 +785,11 @@ export async function selectHeartbeatRuntime(db: Db, input: HeartbeatRuntimeSele
managedAiRuntime ? readNonEmptyString(resolvedConfig.model) ?? undefined : undefined,
)
: agent.adapterConfig;
const nativeProviderConfig = agent.adapterType === "paperclip_runner" && runtimeConfig.homeMode !== undefined
? { ...parseObject(projectedNativeProviderConfig), homeMode: runtimeConfig.homeMode }
const runnerHomeMode = runtimeConfig.homeMode === "preconfigured" && executionTarget?.kind === "remote" && executionTarget.transport === "ssh"
&& !supportsPaperclipRunnerPreconfiguredHome(projectedNativeProviderConfig, { companyId: agent.companyId })
? "isolated" : runtimeConfig.homeMode;
const nativeProviderConfig = agent.adapterType === "paperclip_runner" && runnerHomeMode !== undefined
? { ...parseObject(projectedNativeProviderConfig), homeMode: runnerHomeMode }
: projectedNativeProviderConfig;
const requestedNativeProvider = resolvePaperclipRunnerNativeProviderInput({
companyId: agent.companyId,
@@ -658,6 +658,13 @@ export function resolvePaperclipRunnerProviderProfile(
};
}
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