feat(ssh): use the agent AI account in new environments (#21248)

Use the agent-selected AI account for new SSH environments. Preserve
remote-machine authentication for existing environments and expose it as
an advanced option. Keep managed credentials private while preserving
supported conversation state and credential refreshes across turns.

Validated with focused route, adapter, lifecycle, and real-process tests;
final CI passed on d634944df1.
Greptile Apex reviewed that revision at 5/5 with no unresolved threads.
External neutral security reports remain documented in the pull request.

Co-Authored-By: Paperclip <noreply@paperclip.ing>
This commit is contained in:
Devin FoleyandPaperclip authored and GitHub committed 2026-11-13 13:20:13 -08:00
1 parent 2a8b485140
commit 12aa08721c
77 files changed
+6115 -3898

No files matched your search

+92
View File
@@ -433,6 +433,98 @@ identity before reusing the session; changing identity retires the previous owne
Other managed harnesses retain per-turn cleanup. A suspended native execution
whose credential identity changed must restart as a new execution.
New SSH environments use the agent's configured AI account, including
subscriptions. Account selection and
authorization remain in Paperclip. The remote computer supplies the harness
executable and workspace. In this mode, the SSH user's provider login is not a
fallback, and Paperclip does not replace that user's saved credentials. A
missing or unavailable agent account prevents execution and provider probes.
The **Use authentication configured on the remote machine** option under
**Advanced** selects the remote user's provider login instead. New environments
save `useHostAuth: false`; enabling it saves `true`, skips the agent's managed AI
credential projection, and uses the preconfigured home for native Runner.
Existing environments without the field default to the remote machine's
configured authentication and display the option as enabled when edited. No
migration rewrites existing SSH records. Changing an explicit authentication source invalidates the saved
SSH provider session identity for future runs; already admitted native recovery
retains its original home contract. Fresh native Runner launch uses the effective
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
user's configuration and preserves other settings and manually installed skills.
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. 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.
Credential-bearing launch commands travel through SSH stdin instead of SSH
process arguments. The existing account-specific refresh merge runs before
per-turn directories are removed, including after provider or setup failure.
Environment tests use the selected account and remove their temporary homes
after probing. Managed Codex probes copy refreshed credentials to that account's
local home before cleanup, even when the provider request fails. Managed Codex
ACP runs also copy back subscription refreshes when the controller has an API
key; the selected run's authentication decides whether copyback is needed. The merge rejects
credentials from another account. Routed accounts can omit `auth.json`; the SSH
reader reports confirmed file absence as `ENOENT`, which needs no copyback.
Connection and file-read failures still fail the probe. A disconnected target can prevent remote cleanup; the run reports
the resulting failure rather than silently selecting another account.
Claude and Codex CLI runs in an in-place SSH workspace keep conversation files
(and Codex's native SQLite indexes) in a private remote home scoped to the company, agent, AI account,
and conversation. The home path stays stable across turns and token refreshes.
Each turn installs the current managed files, copies refreshed authentication
back, and removes everything except conversation state, including on provider
failure. Credentials and managed MCP configuration do not remain there between
turns. Switching accounts selects a different home and starts a new conversation.
The cache lives below the environment's remote workspace root. Removing that
root also removes the retained conversation state.
Older SSH host-auth sessions keep their existing remote home. A managed SSH
session saved before conversation retention has no retained state reference and
starts a fresh conversation instead of reusing an unavailable thread. This reset
is recorded as `claude_ssh_session_state_unavailable` or
`codex_ssh_session_state_unavailable`; existing saved files remain. Claude retains
only its `projects` transcript directory, removing credentials and configuration
after every turn. Saved CLI sessions preserve normalized remote identity and
account-scoped conversation references across server persistence.
ACP SSH sessions use the existing remote process bridge and session reuse
lifecycle. Both provider adapters admit managed SSH through their public
execution entry points. SSH ACP needs
an agent-managed account and a copied workspace. Host authentication, in-place
SSH workspaces, and local filesystem/network confinement require the CLI engine.
The SSH prerequisite check retains only the controller's `PATH` to resolve the
local SSH client; it excludes controller credentials. The ACP server command
must be installed on the remote machine and is started there by the process bridge.
A compatible session can retain its private remote home; workspace
sync and credential refresh run at turn teardown, and the session disposal hook
removes the home on retirement. Workspace identity includes the company, agent,
task and execution fingerprint. The fingerprint normalizes temporary managed-home
paths and credential refreshes against the stable account session identity.
Switching accounts or changing other adapter environment values starts a fresh
conversation. The launch still receives the current credentials. When a Codex
ACP session reuses its staged remote home, credential copyback and logging bind
to the current run's local managed home before the remote environment is applied.
Refreshed credentials cannot recreate a retired run's local home.
Older managed SSH ACP sessions used a different
working-directory identity and start fresh after this change. Native runner
session identities and sandbox staging are unchanged.
After a verified provider resume, plain-text Slack follow-ups send the new
authorized message delta instead of repeating the full task framing. The saved
run and current message identities and bodies must match. Actual brief edits
@@ -181,6 +181,10 @@ function buildRuntime(
async function runExecutor(
config: Record<string, unknown>,
options: {
runId?: string;
expectedExitCode?: number;
onStartTurn?: () => void;
stagedRuntimes?: AcpxEngineExecutorOptions["stagedRuntimes"];
context?: Record<string, unknown>;
runtime?: Record<string, unknown>;
executionTransport?: Record<string, unknown>;
@@ -209,21 +213,25 @@ async function runExecutor(
const events: Array<{ eventType: string; payload?: Record<string, unknown> }> = [];
const receipts: unknown[] = [];
const execute = createAcpxEngineExecutor({
...(options.stagedRuntimes ? { stagedRuntimes: options.stagedRuntimes } : {}),
...(options.prepareRemoteManagedHome
? { prepareRemoteManagedHome: options.prepareRemoteManagedHome }
: {}),
createRuntime: (options) => {
runtimeOptions.push(options as unknown as Record<string, unknown>);
createRuntime: (runtimeInput) => {
runtimeOptions.push(runtimeInput as unknown as Record<string, unknown>);
return buildRuntime(
({ key, value }) => configOptions.push({ key, value }),
(input) => sessionInputs.push(input),
(input) => turnInputs.push(input),
(input) => {
turnInputs.push(input);
options.onStartTurn?.();
},
) as never;
},
});
const result = await execute({
runId: "run-1",
runId: options.runId ?? "run-1",
agent: {
id: "agent-1",
companyId: "company-1",
@@ -250,7 +258,7 @@ async function runExecutor(
onUsage: async (receipt: unknown) => { receipts.push(receipt); },
} as never);
expect(result.exitCode).toBe(0);
expect(result.exitCode).toBe(options.expectedExitCode ?? 0);
return { logs, meta, events, receipts, runtimeOptions, configOptions, sessionInputs, turnInputs, result };
}
@@ -4551,6 +4559,114 @@ describe("ACPX engine remote managed-home seam (PR 2: per-adapter home seed)", (
return { root, stateDir, localCwd, remoteCwd, executionTarget };
}
it.each(["turn", "bridge"])("stages the configured agent account for SSH, resumes it, and copies back before disposal after a %s failure", async failure => {
const { root, stateDir, localCwd, remoteCwd } = await setupRemoteSandbox();
const homes = await Promise.all(["first", "second", "third"].map(async name => {
const home = path.join(root, `selected-account-${name}`);
await fs.mkdir(path.join(home, "provider"), { recursive: true });
return home;
}));
const home = path.join(homes[0]!, "provider");
const workspace = path.posix.join(remoteCwd, ".paperclip-runtime/runs/run-1/workspace");
const runtimeRootDir = path.posix.join(workspace, ".paperclip-runtime/custom");
const executionTarget = { kind: "remote", transport: "ssh", remoteCwd, spec: { useHostAuth: false, host: "ssh.example.test", port: 22, username: "agent", remoteCwd, remoteWorkspacePath: remoteCwd, privateKey: null, knownHosts: null, strictHostKeyChecking: true } };
let copybackHome = "";
const restore = vi.fn(async () => {
await fs.mkdir(copybackHome, { recursive: true });
await fs.writeFile(path.join(copybackHome, "copyback"), "fixture refreshed credential");
}), dispose = vi.fn(async () => {});
const stopControl = vi.fn(async () => {}), stopProcess = vi.fn(async () => {});
const stagedRuntimes: NonNullable<AcpxEngineExecutorOptions["stagedRuntimes"]> = new Map();
const seam = vi.fn(async (input: Parameters<NonNullable<AcpxEngineExecutorOptions["prepareRemoteManagedHome"]>>[0]) => {
copybackHome = input.env.CODEX_HOME!;
const stagedRuntime = await input.stage([{ key: "home", localDir: copybackHome }]);
input.env.CODEX_HOME = stagedRuntime.assetDirs.home!;
return { stagedRuntime, rebindRun: async ({ env }: { env: Readonly<Record<string, string>> }) => { copybackHome = env.CODEX_HOME!; } };
});
const actual = await vi.importActual<typeof import("@paperclipai/adapter-utils/execution-target")>("@paperclipai/adapter-utils/execution-target");
vi.mocked(prepareAdapterExecutionTargetRuntime).mockResolvedValue({ target: executionTarget as never, workspaceRemoteDir: workspace, runtimeRootDir,
assetDirs: { home: path.posix.join(runtimeRootDir, "home") }, additionalSourceDirs: {}, additionalSourceFailures: [], workspaceSyncSnapshot: null, restoreWorkspace: restore, disposeRuntime: dispose });
vi.mocked(startAdapterExecutionTargetPaperclipBridge).mockResolvedValue({ env: { PAPERCLIP_API_URL: "http://127.0.0.1:3210", PAPERCLIP_API_KEY: "bridge-fixture" }, stop: stopControl });
vi.mocked(startAdapterExecutionTargetProcessSessionBridge).mockResolvedValue({ agentCommand: "/fixture/agent-proxy.cjs", stop: stopProcess });
try {
const configForTurn = (turn: number) => ({ agent: "custom", agentCommand: "fixture-acp-client", stateDir, cwd: localCwd,
managedAiConnection: { identity: `credential-revision-${turn}`, sessionIdentity: "selected-agent-account" },
env: { CODEX_HOME: path.join(homes[turn]!, "provider"), HOME: homes[turn]!, XDG_CONFIG_HOME: path.join(homes[turn]!, "config"),
XDG_DATA_HOME: path.join(homes[turn]!, "data"), OPENAI_API_KEY: `fixture-token-${turn}`, USER_OPTION: "kept" }, mode: "persistent" });
const config = configForTurn(0);
let failTurn = false;
const options = { authToken: "run-fixture", executionTarget, prepareRemoteManagedHome: seam, stagedRuntimes,
onStartTurn: () => { if (failTurn) throw new Error("fixture SSH turn failed"); } };
const result = await runExecutor(config, options);
expect(seam).toHaveBeenCalledOnce();
expect(seam.mock.calls[0]![0].executionTarget).toMatchObject({ kind: "remote", transport: "ssh" });
expect(prepareAdapterExecutionTargetRuntime).toHaveBeenCalledWith(expect.objectContaining({ assets: [{ key: "home", localDir: home }] }));
expect(result.sessionInputs[0]?.cwd).toMatch(new RegExp(`${remoteCwd}/\\.paperclip-runtime/runs/[a-f0-9]+/workspace$`));
const bridgeInput = vi.mocked(startAdapterExecutionTargetProcessSessionBridge).mock.calls[0]![0];
const env = typeof bridgeInput.env === "function" ? await bridgeInput.env() : bridgeInput.env;
expect(env.CODEX_HOME).toBe(path.posix.join(runtimeRootDir, "home"));
expect(env.HOME).toBe(runtimeRootDir);
const bin = path.join(root, "remote-user-bin");
await fs.mkdir(bin);
await fs.writeFile(path.join(bin, "fixture-acp-client"), '#!/bin/sh\nprintf "%s" "$HOME"\n', { mode: 0o700 });
const shell = path.join(root, "remote-profile-shell");
await fs.writeFile(shell, '#!/bin/sh\nif [ "$1" = "-lc" ]; then PATH=/usr/bin:/bin; export PATH; fi\nexec /bin/sh -c "$2"\n', { mode: 0o700 });
const { execFile } = await import("node:child_process");
const { promisify } = await import("node:util");
const launched = await promisify(execFile)(shell, bridgeInput.args!, {
cwd: root, env: { ...env, PATH: `${bin}:/usr/bin:/bin` },
});
expect(launched.stdout).toBe(runtimeRootDir);
expect(restore).toHaveBeenCalledOnce();
expect(stopControl).toHaveBeenCalledOnce();
expect(stopProcess).toHaveBeenCalledOnce();
expect(dispose).not.toHaveBeenCalled();
await fs.rm(homes[0]!, { recursive: true, force: true });
const resumed = await runExecutor(configForTurn(1), { ...options, runId: "run-2", runtime: { sessionParams: result.result.sessionParams } });
expect(resumed.sessionInputs[0]?.cwd).toBe(result.sessionInputs[0]?.cwd);
expect(resumed.sessionInputs[0]?.resumeSessionId).toBe(result.result.sessionId);
const resumeBridge = vi.mocked(startAdapterExecutionTargetProcessSessionBridge).mock.calls.at(-1)![0];
const resumedEnv = typeof resumeBridge.env === "function" ? await resumeBridge.env() : resumeBridge.env;
expect(resumedEnv.OPENAI_API_KEY).toBe("fixture-token-1");
expect(seam).toHaveBeenCalledOnce();
expect(restore).toHaveBeenCalledTimes(2);
await expect(fs.readFile(path.join(homes[1]!, "provider", "copyback"), "utf8")).resolves.toBe("fixture refreshed credential");
await expect(fs.stat(homes[0]!)).rejects.toMatchObject({ code: "ENOENT" });
if (failure === "bridge") {
vi.mocked(startAdapterExecutionTargetProcessSessionBridge).mockRejectedValueOnce(new Error("fixture SSH bridge unavailable"));
await expect(runExecutor(configForTurn(2), { ...options, runId: "run-3", runtime: { sessionParams: resumed.result.sessionParams } })).rejects.toThrow("fixture SSH bridge unavailable");
} else {
failTurn = true;
await runExecutor(configForTurn(2), { ...options, runId: "run-3", expectedExitCode: 1, runtime: { sessionParams: resumed.result.sessionParams } });
}
expect(restore).toHaveBeenCalledTimes(3);
await expect(fs.readFile(path.join(homes[2]!, "provider", "copyback"), "utf8")).resolves.toBe("fixture refreshed credential");
await expect(fs.stat(homes[0]!)).rejects.toMatchObject({ code: "ENOENT" });
expect(stopControl.mock.invocationCallOrder[2]).toBeLessThan(restore.mock.invocationCallOrder[2]!);
expect(restore.mock.invocationCallOrder[2]).toBeLessThan(dispose.mock.invocationCallOrder[0]!);
expect(dispose).toHaveBeenCalledOnce();
expect(stopControl).toHaveBeenCalledTimes(3);
expect(stopProcess).toHaveBeenCalledTimes(failure === "bridge" ? 2 : 3);
expect(stagedRuntimes.size).toBe(0);
failTurn = true;
const changed = configForTurn(0);
if (failure === "turn") changed.managedAiConnection.sessionIdentity = "different-agent-account";
else changed.env.USER_OPTION = "changed";
const reset = await runExecutor(changed, { ...options, runId: "run-4", expectedExitCode: 1,
runtime: { sessionParams: resumed.result.sessionParams } });
expect(reset.sessionInputs[0]?.cwd).not.toBe(result.sessionInputs[0]?.cwd);
expect(reset.sessionInputs[0]?.resumeSessionId).not.toBe(result.result.sessionId);
expect(seam).toHaveBeenCalledTimes(2);
expect(restore).toHaveBeenCalledTimes(4);
expect(dispose).toHaveBeenCalledTimes(2);
expect(stagedRuntimes.size).toBe(0);
} finally {
vi.mocked(prepareAdapterExecutionTargetRuntime).mockReset().mockImplementation(actual.prepareAdapterExecutionTargetRuntime);
vi.mocked(startAdapterExecutionTargetPaperclipBridge).mockReset().mockImplementation(actual.startAdapterExecutionTargetPaperclipBridge);
vi.mocked(startAdapterExecutionTargetProcessSessionBridge).mockReset().mockImplementation(actual.startAdapterExecutionTargetProcessSessionBridge);
}
});
it("test_remote_seam_receives_adapter_agnostic_context", async () => {
const { stateDir, localCwd, remoteCwd, executionTarget } = await setupRemoteSandbox();
let captured: Record<string, unknown> | null = null;
@@ -1,3 +1,5 @@
import { managedAiSessionFingerprintConfig } from "../managed-ai-runtime-env.js";
import { createWorkspaceRestoreTeardown } from "../workspace-restore-teardown.js";
import { isOpenRouterUrl, openRouterClaudeHeaders } from "@paperclipai/shared/openrouter-attribution";
import { prepareAcpxCodexObservabilityHome } from "../codex-observability-home.js";
import { codexShellEnvironmentKeys } from "../codex-shell-environment.js";
@@ -21,6 +23,7 @@ import type {
UsageSummary,
} from "@paperclipai/adapter-utils";
import {
managedRemoteHomeEnvironment,
adapterExecutionTargetSessionIdentity,
describeAdapterExecutionTarget,
adapterExecutionTargetDuplexObservabilityRecorder,
@@ -164,7 +167,7 @@ import {
type ChildStderrState,
type RuntimeCacheEntry,
} from "./run-site-host.js";
import { createSandboxRunSite, type SandboxRunSite } from "./run-site-sandbox.js";
import { createSandboxRunSite, type SandboxRunSite, type ManagedHomeRunRebind } from "./run-site-sandbox.js";
import {
createRuntimeSpanRunner,
emitRunPhaseTiming,
@@ -240,6 +243,7 @@ type AcpxRuntimeFactory = (options: PaperclipAcpRuntimeOptions) => AcpRuntime;
* in-sandbox staged workspace + home, which this cache reuses.
*/
export interface StagedRuntimeCacheEntry {
rebindRun?: ManagedHomeRunRebind;
observabilityCompatibilityKey?: string;
stagedRuntime: PreparedAdapterExecutionTargetRuntime;
/**
@@ -352,6 +356,8 @@ export interface AcpxRemoteManagedHomeContext {
}
export interface AcpxRemoteManagedHomeResult {
/** Rebind a retained home's copyback destination before a compatible follow-up. */
rebindRun?: ManagedHomeRunRebind;
stagedRuntime: PreparedAdapterExecutionTargetRuntime;
/**
* Per-run copy-back, invoked once on every teardown/exit path (mirrors the CLI
@@ -506,6 +512,7 @@ interface AcpxPreparedRuntime {
// keeps the runtime warm. Null for local runs, the runner-less fallback, and
// adapters with no disposable temp.
remoteStagingDispose: (() => Promise<void>) | null;
remoteStagingOwner?: Pick<StagedRuntimeCacheEntry, "teardown" | "dispose" | "rebindRun">;
// PR 3: for the remote runner-backed lane, the env keys the managed-home seam
// mutated on this run (or the reused delta on a compatible resume), so the
// executor can cache/refresh the staged-runtime entry after a clean turn.
@@ -1744,6 +1751,7 @@ async function writePaperclipClaudeSettings(input: {
async function stageAcpRemoteRuntime(input: {
runId: string;
target: AdapterExecutionTarget;
privateRuntime?: boolean;
adapterKey: string;
workspaceLocalDir: string;
// Pin the in-sandbox workspace dir so it provably equals the deterministic
@@ -1769,6 +1777,8 @@ async function stageAcpRemoteRuntime(input: {
`[paperclip] Syncing workspace to ${describeAdapterExecutionTarget(input.target)}.\n`,
);
return await prepareAdapterExecutionTargetRuntime({
privateRuntime: input.privateRuntime,
retainRuntime: input.privateRuntime,
runId: input.runId,
target: input.target,
adapterKey: input.adapterKey,
@@ -2233,13 +2243,9 @@ async function buildRuntime(input: {
});
let agentCommand = configuredCommand || builtInCommand?.command || null;
let agentCommandShell = configuredCommand || builtInCommand?.shellCommand || "";
// A runner-backed remote sandbox is the only lane that crosses the staging
// and serialized-launch-env seam. Runner-less ACP→CLI fallback, SSH, and
// local runs keep their historical host-provider compatibility behavior.
const useRemoteProcessSession =
executionTarget?.kind === "remote" &&
executionTarget.transport === "sandbox" &&
Boolean(executionTarget.runner) &&
(executionTarget.transport === "sandbox" ? Boolean(executionTarget.runner) : executionTarget.spec.useHostAuth === false && Boolean(config.managedAiConnection)) &&
Boolean(agentCommandShell);
if (acpxAgent === "gemini" && agentCommandShell) {
const normalized = await normalizeGeminiAcpCommandShell(
@@ -2283,7 +2289,7 @@ async function buildRuntime(input: {
// workspace / re-seeding the managed home. The stage call below pins its
// `workspaceRemoteDir` to this same value, so the staged cwd can never
// diverge from the cwd that fed the fingerprint.
const sessionCwd =
let sessionCwd =
useRemoteProcessSession && executionTarget?.kind === "remote"
? executionTarget.remoteCwd
: acpxAgent === "gemini" && !executionTargetIsRemote
@@ -2292,7 +2298,7 @@ async function buildRuntime(input: {
// The 17 fields the session fingerprint hashes. Company, agent, and task
// identifiers are NOT here; they scope the outer session key only (see
// `keyIdentity`). The fingerprint builder accepts only this identity.
const fingerprintIdentity: SessionFingerprintIdentity = {
let fingerprintIdentity: SessionFingerprintIdentity = {
...(input.ctx.agentIdentity ? { agentIdentityKeyId: input.ctx.agentIdentity.keyId } : {}),
acpxAgent,
agentCommand: agentCommand ?? acpxAgent,
@@ -2329,10 +2335,26 @@ async function buildRuntime(input: {
// that sources the latest env. secretManifestHash alone misses plain-value
// edits and same-version secret rotations. Per-wake runtime vars never enter
// resolvedAdapterEnv, so they don't churn the fingerprint every heartbeat.
adapterEnvHash: shortHash(resolvedAdapterEnv),
// Managed SSH identity uses the selected account's stable session identity;
// temporary credential homes and token refreshes affect only the launch env.
adapterEnvHash: shortHash(
useRemoteProcessSession && executionTarget?.kind === "remote" && executionTarget.transport === "ssh"
? managedAiSessionFingerprintConfig(
{ env: resolvedAdapterEnv, managedAiConnection: config.managedAiConnection },
asString(resolvedAdapterEnv.HOME, "") || undefined,
)
: resolvedAdapterEnv,
),
};
const fingerprint = buildSessionFingerprint(fingerprintIdentity);
const taskKey = asString(input.ctx.runtime.taskKey, "") || wakeTaskId || workspaceId || "default";
const sshWorkspaceRunId = useRemoteProcessSession && executionTarget?.kind === "remote" && executionTarget.transport === "ssh"
? shortHash({ companyId: agent.companyId, agentId: agent.id, taskKey, fingerprintIdentity })
: null;
if (sshWorkspaceRunId && executionTarget?.kind === "remote") {
sessionCwd = path.posix.join(executionTarget.remoteCwd, ".paperclip-runtime", "runs", sshWorkspaceRunId, "workspace");
fingerprintIdentity = { ...fingerprintIdentity, cwd: sessionCwd };
}
const fingerprint = buildSessionFingerprint(fingerprintIdentity);
// Company, agent, and task identity for the outer session key. These parts
// stay out of the fingerprint hash.
const keyIdentity: SessionKeyIdentity = {
@@ -2390,6 +2412,7 @@ async function buildRuntime(input: {
let stagedRuntime: PreparedAdapterExecutionTargetRuntime | null = null;
let remoteManagedHomeTeardown: (() => Promise<WorkspaceRestoreOutcome>) | null = null;
let remoteStagingDispose: (() => Promise<void>) | null = null;
let remoteStagingOwner: Pick<StagedRuntimeCacheEntry, "teardown" | "dispose" | "rebindRun"> | undefined;
let remoteStagingEnvDelta: Record<string, string> | null = null;
let sessionStagingLeaseRelease: (() => void) | null = null;
// The sandbox run site owns the sandbox lane's staging, the per-session
@@ -2411,25 +2434,30 @@ async function buildRuntime(input: {
spawnCwd: cwd,
target: remoteTarget,
env,
managedHomeRunBinding: { env: { ...env }, onLog: input.ctx.onLog },
isCompatibleResume,
observabilityCompatibilityKey: input.ctx.observability?.compatibilityKey,
stage: (assets) =>
stageAcpRemoteRuntime({
runId,
stage: async (assets) => {
const staged = await stageAcpRemoteRuntime({
runId: sshWorkspaceRunId ?? runId,
privateRuntime: remoteTarget.transport === "ssh",
target: remoteTarget,
adapterKey: input.engine.adapterType,
workspaceLocalDir: cwd,
workspaceRemoteDir: sessionCwd,
workspaceRemoteDir: remoteTarget.transport === "ssh" ? remoteTarget.remoteCwd : sessionCwd,
timeoutSec,
assets,
additionalSources,
onLog: input.ctx.onLog,
onRuntimeProgress: input.ctx.onRuntimeProgress,
runtimeSpan: input.stageRuntimeSpan,
}),
seedManagedHome: input.deps.prepareRemoteManagedHome
});
if (remoteTarget.transport === "ssh" && config.managedAiConnection && staged.runtimeRootDir) Object.assign(env, managedRemoteHomeEnvironment(staged.runtimeRootDir));
return staged;
},
seedManagedHome: input.deps.prepareRemoteManagedHome || remoteTarget.transport === "ssh"
? async (stage) => {
const seeded = await input.deps.prepareRemoteManagedHome!({
const seeded: AcpxRemoteManagedHomeResult = input.deps.prepareRemoteManagedHome ? await input.deps.prepareRemoteManagedHome({
acpxAgent,
companyId: agent.companyId,
runId,
@@ -2442,11 +2470,19 @@ async function buildRuntime(input: {
onRuntimeProgress: input.ctx.onRuntimeProgress,
skillsBundleDir: claudeSkillsBundleDir,
stage,
});
}) : { stagedRuntime: await stage([]) };
return {
stagedRuntime: seeded.stagedRuntime,
teardown: seeded.teardown ?? null,
dispose: seeded.disposeStaged ?? null,
rebindRun: seeded.rebindRun,
teardown: seeded.teardown ?? (remoteTarget.transport === "ssh" ? createWorkspaceRestoreTeardown({
stagedRuntime: seeded.stagedRuntime, onLog: input.ctx.onLog,
startMessage: "[paperclip] Restoring SSH workspace and managed credentials.\n",
failurePrefix: "[paperclip] SSH workspace restore failed",
}) : null),
dispose: remoteTarget.transport === "ssh" ? async () => {
try { await seeded.disposeStaged?.(); }
finally { await seeded.stagedRuntime.disposeRuntime?.(); }
} : seeded.disposeStaged ?? null,
};
}
: undefined,
@@ -2481,7 +2517,7 @@ async function buildRuntime(input: {
startPaperclipBridge: (runtimeRootDir) =>
startAdapterExecutionTargetPaperclipBridge({
runId,
target: { ...remoteTarget, streamRunLogs: false },
target: remoteTarget.transport === "sandbox" ? { ...remoteTarget, streamRunLogs: false } : remoteTarget,
runtimeRootDir,
adapterKey: input.engine.adapterType,
timeoutSec,
@@ -2499,7 +2535,7 @@ async function buildRuntime(input: {
runtimeRootDir,
adapterKey: input.engine.adapterType,
command: "sh",
args: ["-lc", `exec ${agentCommandShell}`],
args: [remoteTarget.transport === "ssh" ? "-c" : "-lc", `exec ${agentCommandShell}`],
cwd: sessionCwd,
env: launchEnv,
timeoutSec,
@@ -2521,6 +2557,8 @@ async function buildRuntime(input: {
await Promise.allSettled([agentBridge?.stop(), controlBridge?.stop()]);
if (remoteManagedHomeTeardown) {
await remoteManagedHomeTeardown().catch(() => {});
} else if (remoteTarget.transport === "ssh") {
await stagedRuntime?.restoreWorkspace();
}
},
});
@@ -2535,6 +2573,23 @@ async function buildRuntime(input: {
stagedRuntime = placedStaged?.stagedRuntime ?? null;
remoteManagedHomeTeardown = placedStaged?.teardown ?? null;
remoteStagingDispose = placedStaged?.dispose ?? null;
remoteStagingOwner = { teardown: remoteManagedHomeTeardown, dispose: remoteStagingDispose, rebindRun: placedStaged?.rebindRun };
if (remoteTarget.transport === "ssh") {
const owner = remoteStagingOwner;
let copyBackComplete = false;
let disposeRequested = false;
remoteManagedHomeTeardown = async () => {
try { return await owner.teardown?.() ?? { ok: true }; }
finally {
copyBackComplete = true;
if (disposeRequested) await owner.dispose?.();
}
};
remoteStagingDispose = async () => {
disposeRequested = true;
if (copyBackComplete) await owner.dispose?.();
};
}
remoteStagingEnvDelta = placedStaged?.envDelta ?? null;
sessionStagingLeaseRelease = sandboxSite.stagingLeaseRelease;
}
@@ -2711,6 +2766,7 @@ async function buildRuntime(input: {
stagedRuntime,
remoteManagedHomeTeardown,
remoteStagingDispose,
...(remoteStagingOwner ? { remoteStagingOwner } : {}),
remoteStagingEnvDelta,
sessionStagingLeaseRelease,
remoteExecutionIdentity,
@@ -3740,9 +3796,10 @@ function saveStagedRuntimeAfterCleanTurn(input: {
input.handles.set(prepared.sessionKey, {
observabilityCompatibilityKey: input.observabilityCompatibilityKey,
stagedRuntime: prepared.stagedRuntime,
rebindRun: prepared.remoteStagingOwner?.rebindRun,
envDelta: prepared.remoteStagingEnvDelta,
teardown: prepared.remoteManagedHomeTeardown,
dispose: prepared.remoteStagingDispose,
teardown: prepared.remoteStagingOwner?.teardown ?? prepared.remoteManagedHomeTeardown,
dispose: prepared.remoteStagingOwner?.dispose ?? prepared.remoteStagingDispose,
lastUsedAt: input.now,
});
}
@@ -46,7 +46,7 @@ it('stops an actual ACP process and resumes its established session with the new
const launches = (await fs.readFile(path.join(root, 'run-env'), 'utf8')).trim().split('\n').map(line => JSON.parse(line));
expect(launches.map(launch => launch.runId)).toEqual(['stop-test', 'follow-up']);
expect(launches[1].tokenHash).toBe(createHash('sha256').update('follow-up-test-token').digest('hex'));
});
}, 15000);
it('continues after an interrupted write without replaying that write', async () => {
const { root, ctx, abort, started, execute } = await setup('write');
const running = execute(ctx);
@@ -89,7 +89,7 @@ it.each(['missing session', 'changed configuration'])('starts a new turn when th
}
expect(next.exitCode, JSON.stringify(next)).toBe(0);
expect((await fs.readFile(path.join(root, 'prompts'), 'utf8')).trim().split('\n')).toHaveLength(2);
});
}, 15000);
it('keeps the Stop deadline active after cancellation returns until provider exit', async () => {
const { ctx, abort, started, execute } = await setup();
@@ -11,6 +11,7 @@ import { describe, expect, it, vi } from "vitest";
import {
createSandboxRunSite,
type ManagedHomeSeamResult,
type ManagedHomeRunBinding,
type SandboxRunSiteOptions,
type StagedRuntimeStoreEntry,
} from "./run-site-sandbox.js";
@@ -244,11 +245,15 @@ describe("sandbox run site", () => {
it("test_sandbox_site_borrow_yields_files_and_runtime_is_still_created", async () => {
const cachedRuntime = makeStagedRuntime("cached");
let observedLocalHome: string | undefined;
const binding: ManagedHomeRunBinding = { env: { CODEX_HOME: "/current/local-home" }, onLog: async () => {} };
const rebindRun = vi.fn(async (current: ManagedHomeRunBinding) => { observedLocalHome = current.env.CODEX_HOME; });
const stagedRuntimes = new Map<string, StagedRuntimeStoreEntry>([
[
"paperclip:c:a:t:fp",
{
stagedRuntime: cachedRuntime,
rebindRun,
envDelta: { CODEX_HOME: "/remote/home" },
teardown: async () => ({ ok: true }),
dispose: async () => {},
@@ -256,7 +261,7 @@ describe("sandbox run site", () => {
},
],
]);
const { site, env } = makeSite({ stagedRuntimes, isCompatibleResume: true });
const { site, env } = makeSite({ stagedRuntimes, isCompatibleResume: true, managedHomeRunBinding: binding });
// A borrow reads the staged entry without removal, so an overlapping run of
// the same session still reads it.
@@ -272,12 +277,27 @@ describe("sandbox run site", () => {
expect(site.staged?.reused).toBe(true);
expect(site.staged?.stagedRuntime).toBe(cachedRuntime);
expect(env.CODEX_HOME).toBe("/remote/home");
expect(rebindRun).toHaveBeenCalledWith(binding);
expect(observedLocalHome).toBe("/current/local-home");
const candidate: SandboxReuseCandidate = site.reuseCandidate(makeReady(cachedRuntime));
expect(candidate).toEqual({ stagedRuntime: cachedRuntime });
expect("runtime" in candidate).toBe(false);
expect("sessionHandle" in candidate).toBe(false);
});
it("releases the staging lease if rebinding a retained managed home fails", async () => {
const rebindRun = vi.fn(async () => { throw new Error("fixture binding failed"); });
const entry = { stagedRuntime: makeStagedRuntime("cached"), envDelta: { CODEX_HOME: "/remote/home" },
rebindRun, teardown: null, dispose: null, lastUsedAt: 500 };
const stagedRuntimes = new Map([["s", entry]]);
const { site, stagingLocks, env } = makeSite({ stagedRuntimes, isCompatibleResume: true,
managedHomeRunBinding: { env: { CODEX_HOME: "/current/local-home" }, onLog: async () => {} } });
await expect(site.placeWorkspace(makeContext("s"))).rejects.toThrow("fixture binding failed");
expect(stagingLocks.size).toBe(0);
expect(env.CODEX_HOME).toBeUndefined();
expect(stagedRuntimes.get("s")).toBe(entry);
});
it("test_site_plan_supplies_session_cwd_spawn_cwd_and_tracing_before_the_fingerprint_build", () => {
const { site } = makeSite();
// `plan()` is synchronous and reads no staged state, so it runs before the
@@ -21,6 +21,7 @@
// candidate never retain a run-scoped contribution or a bridge token. The staged
// reuse payload carries the staged files only.
import type { AdapterExecutionContext } from "../types.js";
import type {
AdapterExecutionTarget,
AdapterExecutionTargetPaperclipBridgeHandle,
@@ -43,6 +44,13 @@ import type {
import { createSessionReuseStore } from "./session-reuse-store.js";
import type { WorkspaceRestoreOutcome } from "../workspace-restore-merge.js";
export interface ManagedHomeRunBinding {
readonly env: Readonly<Record<string, string>>;
readonly onLog: AdapterExecutionContext["onLog"];
}
export type ManagedHomeRunRebind = (binding: ManagedHomeRunBinding) => void | Promise<void>;
/**
* One staged in-sandbox runtime the store keeps for the next compatible resume.
* It is the value the staged-runtime map holds. The engine still owns this shape;
@@ -51,6 +59,7 @@ import type { WorkspaceRestoreOutcome } from "../workspace-restore-merge.js";
* none — the run-start sweep is the only eviction path.
*/
export interface StagedRuntimeStoreEntry {
readonly rebindRun?: ManagedHomeRunRebind;
observabilityCompatibilityKey?: string;
stagedRuntime: PreparedAdapterExecutionTargetRuntime;
envDelta: Record<string, string>;
@@ -64,6 +73,7 @@ export interface StagedRuntimeStoreEntry {
* fields on the run and, after a clean turn, into the staged store.
*/
export interface StagedWorkspace {
readonly rebindRun?: ManagedHomeRunRebind;
readonly stagedRuntime: PreparedAdapterExecutionTargetRuntime;
readonly teardown: (() => Promise<WorkspaceRestoreOutcome>) | null;
readonly dispose: (() => Promise<void>) | null;
@@ -80,6 +90,7 @@ export type StageWorkspace = (assets: AdapterManagedRuntimeAsset[]) => Promise<P
* its adapter seam onto this before it passes the seam in.
*/
export interface ManagedHomeSeamResult {
readonly rebindRun?: ManagedHomeRunRebind;
readonly stagedRuntime: PreparedAdapterExecutionTargetRuntime;
readonly teardown: (() => Promise<WorkspaceRestoreOutcome>) | null;
readonly dispose: (() => Promise<void>) | null;
@@ -87,6 +98,7 @@ export interface ManagedHomeSeamResult {
/** The construction options for the sandbox site. Every value is per run. */
export interface SandboxRunSiteOptions {
readonly managedHomeRunBinding?: ManagedHomeRunBinding;
/** The run ledger. `executeAcpxEngine` creates it and passes it in (one ledger). */
readonly ledger: AcquiredRunResources;
/** The staged-runtime map the store operates over. The engine owns it across runs. */
@@ -240,11 +252,16 @@ export function createSandboxRunSite(options: SandboxRunSiteOptions): SandboxRun
// Reuse the already-staged in-sandbox workspace and managed home.
// Re-apply the env keys the seam repointed and reuse the per-run
// copy-back so the copy-back cadence stays exactly per run.
if (cached.rebindRun) {
if (!options.managedHomeRunBinding) throw new Error("Managed home requires the current run binding");
await cached.rebindRun(options.managedHomeRunBinding);
}
Object.assign(options.env, cached.envDelta);
cached.lastUsedAt = options.now();
await options.onReuseLog();
return {
stagedRuntime: cached.stagedRuntime,
rebindRun: cached.rebindRun,
teardown: cached.teardown,
dispose: cached.dispose,
envDelta: cached.envDelta,
@@ -286,6 +303,7 @@ export function createSandboxRunSite(options: SandboxRunSiteOptions): SandboxRun
}
return {
stagedRuntime: seam.stagedRuntime,
rebindRun: seam.rebindRun,
teardown: seam.teardown,
dispose: seam.dispose,
envDelta,
@@ -7,6 +7,8 @@ import {
cleanupGitHubOperationLaunchers,
prepareGitHubOperationLaunchers,
adapterExecutionTargetUsesManagedHome,
adapterExecutionTargetSessionIdentity,
normalizeAdapterExecutionTargetSessionIdentity,
ensureAdapterExecutionTargetRuntimeCommandInstalled,
ensureAdapterExecutionTargetDirectory,
ensureAdapterExecutionTargetCommandResolvable,
@@ -35,6 +37,23 @@ function sshExecutionTarget(): AdapterSshExecutionTarget {
};
}
describe("persisted execution target identities", () => {
it("retains SSH session guards without persisting connection credentials or socket paths", () => {
const target = sshExecutionTarget();
target.spec.useHostAuth = false;
const identity = adapterExecutionTargetSessionIdentity(target)!;
expect(normalizeAdapterExecutionTargetSessionIdentity({ ...identity, privateKey: "credential canary", tailscaleSocket: "/private/socket", unexpected: { secret: "canary" } })).toEqual(identity);
expect(normalizeAdapterExecutionTargetSessionIdentity({ ...identity, port: "22" })).toBeNull();
expect(normalizeAdapterExecutionTargetSessionIdentity({ ...identity, host: {} })).toBeNull();
});
it("retains sandbox lease guards and rejects unknown transports", () => {
const target = { kind: "remote" as const, transport: "sandbox" as const, remoteCwd: "/workspace", providerKey: "fixture", environmentId: "environment", leaseId: "lease" };
const identity = adapterExecutionTargetSessionIdentity(target)!;
expect(normalizeAdapterExecutionTargetSessionIdentity({ ...identity, credential: "canary" })).toEqual(identity);
expect(normalizeAdapterExecutionTargetSessionIdentity({ ...identity, transport: "unknown" })).toBeNull();
});
});
describe("execution target validation failures", () => {
afterEach(() => vi.restoreAllMocks());
const result = { exitCode: 0, signal: null, timedOut: false, stdout: "", stderr: "", pid: null, startedAt: "" };
@@ -237,6 +256,14 @@ describe("runAdapterExecutionTargetShellCommand", () => {
},
})).toBe(false);
});
it("uses a managed home on SSH when the agent has a configured AI connection", () => {
const target = sshExecutionTarget();
expect(adapterExecutionTargetUsesManagedHome(target, true)).toBe(false);
expect(adapterExecutionTargetUsesManagedHome({ ...target, spec: { ...target.spec, useHostAuth: false } }, true)).toBe(true);
expect(adapterExecutionTargetUsesManagedHome({ ...target, spec: { ...target.spec, useHostAuth: true } }, true)).toBe(false);
expect(adapterExecutionTargetUsesManagedHome(null, true)).toBe(false);
});
});
describe("runAdapterExecutionTargetProcess", () => {
+32 -7
View File
@@ -284,6 +284,7 @@ export interface PreparedAdapterExecutionTargetRuntime {
repositories?: NonNullable<GitWorkspaceSnapshot["repositories"]>;
} | null;
cleanupWorkspaceSnapshot?(): Promise<void>;
disposeRuntime?(): Promise<void>;
restoreWorkspace(onProgress?: RuntimeProgressSink): Promise<void>;
}
@@ -401,6 +402,7 @@ export interface AdapterExecutionTargetProcessSessionBridgeHandle {
}
export { sanitizeRemoteExecutionEnv } from "./remote-execution-env.js";
export { managedRemoteHomeEnvironment } from "./remote-execution-env.js";
// Four-hour wall-clock backstop for sandbox-backed adapter runs. Keep this
// execution limit independent of the earlier informational silence warnings
@@ -490,8 +492,9 @@ export function adapterExecutionTargetIsRemote(
export function adapterExecutionTargetUsesManagedHome(
target: AdapterExecutionTarget | null | undefined,
managedAiConnection = false,
): boolean {
return target?.kind === "remote" && target.transport === "sandbox";
return target?.kind === "remote" && (target.transport === "sandbox" || (managedAiConnection && target.spec.useHostAuth === false));
}
/**
@@ -1382,6 +1385,23 @@ export function adapterExecutionTargetSessionIdentity(
};
}
export function normalizeAdapterExecutionTargetSessionIdentity(value: unknown): Record<string, unknown> | null {
const saved = parseObject(value);
if (saved.transport === "ssh") {
if (!readStringMeta(saved, "host") || !readStringMeta(saved, "username") || !readStringMeta(saved, "remoteCwd")
|| typeof saved.port !== "number" || !Number.isInteger(saved.port) || saved.port < 1 || saved.port > 65535
|| (saved.useHostAuth !== undefined && typeof saved.useHostAuth !== "boolean")) return null;
const fields = Object.fromEntries(Object.entries(saved).filter(([key, entry]) => typeof entry === "string"
|| (key === "port" && typeof entry === "number") || (key === "useHostAuth" && typeof entry === "boolean")));
return buildRemoteExecutionSessionIdentity(fields as unknown as SshRemoteExecutionSpec);
}
if (saved.transport === "sandbox" && readStringMeta(saved, "remoteCwd")) {
return adapterExecutionTargetSessionIdentity({ kind: "remote", transport: "sandbox", remoteCwd: readStringMeta(saved, "remoteCwd")!,
providerKey: readStringMeta(saved, "providerKey"), environmentId: readStringMeta(saved, "environmentId"), leaseId: readStringMeta(saved, "leaseId") });
}
return null;
}
export function adapterExecutionTargetSessionMatches(
saved: unknown,
target: AdapterExecutionTarget | null | undefined,
@@ -1492,6 +1512,8 @@ export async function prepareAdapterExecutionTargetRuntime(input: {
/** Sandbox transfer scratch, confined to the lease's reserved runtime tree. */
runtimeRootDir?: string;
syncWorkspace?: boolean;
privateRuntime?: boolean;
retainRuntime?: boolean;
workspaceInboundMode?: WorkspaceInboundMode;
workspaceSnapshotIsolation?: "worker";
workspaceGitIndexRefresh?: boolean;
@@ -1552,6 +1574,8 @@ export async function prepareAdapterExecutionTargetRuntime(input: {
workspaceLocalDir: input.workspaceLocalDir,
workspaceRemoteDir: input.workspaceRemoteDir,
syncWorkspace: input.syncWorkspace,
privateRuntime: input.privateRuntime,
retainRuntime: input.retainRuntime,
workspaceFileMode: input.workspaceFileMode,
workspaceExclude: input.workspaceExclude,
assets: input.assets,
@@ -1568,6 +1592,7 @@ export async function prepareAdapterExecutionTargetRuntime(input: {
// reports a per-project staging failure.
additionalSourceFailures: [],
workspaceSyncSnapshot: null,
disposeRuntime: prepared.disposeRuntime,
restoreWorkspace: prepared.restoreWorkspace,
};
}
@@ -2071,7 +2096,7 @@ export async function startAdapterExecutionTargetProcessSessionBridge(input: {
// it does not start the 100 ms poll. Default OFF: the bridge keeps the poll.
streamOutputViaSession?: boolean;
}): Promise<AdapterExecutionTargetProcessSessionBridgeHandle | null> {
if (!input.target || input.target.kind !== "remote" || input.target.transport !== "sandbox") {
if (!input.target || input.target.kind !== "remote") {
return null;
}
@@ -2082,7 +2107,7 @@ export async function startAdapterExecutionTargetProcessSessionBridge(input: {
const logFailureWithoutWaiting = (message: string) => {
void Promise.resolve().then(() => onLog("stderr", message)).catch(() => undefined);
};
const runner = requireSandboxRunner(target);
const runner = adapterExecutionTargetCommandRunner(target);
// Run one unit of run-time work under its named wrapper span when a span
// runner is injected. Without a runner, run the work under the current run
// parent, so the inner `sandbox.exec` spans parent to the live run span,
@@ -2091,11 +2116,11 @@ export async function startAdapterExecutionTargetProcessSessionBridge(input: {
input.runtimeSpan
? input.runtimeSpan(name, work)
: runWithRuntimeParent(input.getRuntimeParentContext?.(), work);
const shellCommand = preferredSandboxShell(target);
const shellCommand = adapterExecutionTargetShellCommand(target);
const timeoutMs =
typeof input.timeoutSec === "number" && Number.isFinite(input.timeoutSec) && input.timeoutSec > 0
? Math.trunc(input.timeoutSec * 1000)
: target.timeoutMs ?? undefined;
: adapterExecutionTargetTimeoutMs(target) ?? undefined;
const bridgeRuntimeDir = path.posix.join(
input.runtimeRootDir?.trim() || path.posix.join(target.remoteCwd, ".paperclip-runtime", input.adapterKey),
"process-sessions",
@@ -2183,7 +2208,7 @@ export async function startAdapterExecutionTargetProcessSessionBridge(input: {
// event files with the host poll below. The streamed path launches the wrapper
// as one foreground session command further down instead, so skip this.
if (!streamOutput) {
await onLog("stdout", `[paperclip] Starting ACP process session bridge in sandbox (${target.providerKey ?? "provider"}).\n`);
await onLog("stdout", `[paperclip] Starting ACP process session bridge in ${describeAdapterExecutionTarget(target)}.\n`);
const startResult = await runSandboxBridgeControlCommand(runner, {
command: shellCommand,
args: shellCommandArgs(
@@ -2536,7 +2561,7 @@ export async function startAdapterExecutionTargetProcessSessionBridge(input: {
await onLog(
"stdout",
`[paperclip] Starting streamed ACP process session bridge in sandbox (${target.providerKey ?? "provider"}).\n`,
`[paperclip] Starting streamed ACP process session bridge in ${describeAdapterExecutionTarget(target)}.\n`,
);
// Fire the long-lived command; do NOT await it here. `useSession` forces the
// persistent session so the provider streams the wrapper stdout back through
@@ -0,0 +1,48 @@
import path from "node:path";
export function managedAiHomeEnvironment(home: string): Record<string, string> {
const providerHome = path.join(home, "provider");
return {
HOME: home,
XDG_CONFIG_HOME: path.join(home, "config"),
XDG_DATA_HOME: path.join(home, "data"),
CODEX_HOME: providerHome,
GROK_HOME: providerHome,
CLAUDE_CONFIG_DIR: providerHome,
HERMES_HOME: providerHome,
};
}
/** Only the server-created credential home is volatile; retain all other config. */
export function managedAiSessionFingerprintConfig(
config: Record<string, unknown>,
managedHome: string | undefined,
): Record<string, unknown> {
if (!managedHome) return config;
const env = { ...(config.env as Record<string, unknown> | undefined) };
const stable = managedAiHomeEnvironment("<managed-ai-home>");
for (const [key, value] of Object.entries(managedAiHomeEnvironment(managedHome))) {
if (env[key] === value) env[key] = stable[key];
}
if (env.GEMINI_HOME === path.join(managedHome, "provider")) {
env.GEMINI_HOME = path.join("<managed-ai-home>", "provider");
}
const managed = config.managedAiConnection as Record<string, unknown> | undefined;
if (managed?.sessionIdentity) {
for (const key of [
"ANTHROPIC_API_KEY", "ANTHROPIC_AUTH_TOKEN", "CLAUDE_CODE_OAUTH_TOKEN",
"OPENAI_API_KEY", "CODEX_API_KEY", "OPENROUTER_API_KEY", "XAI_API_KEY",
"GROK_API_KEY", "GEMINI_API_KEY", "GOOGLE_API_KEY",
"OPENCODE_AUTH_JSON", "OPENCODE_CONFIG_CONTENT",
]) {
if (env[key]) env[key] = "<managed-ai-credential>";
}
}
return {
...config,
env,
...(managed?.sessionIdentity
? { managedAiConnection: { ...managed, identity: managed.sessionIdentity } }
: {}),
};
}
@@ -47,3 +47,14 @@ export function sanitizeRemoteExecutionEnv(
}
return sanitized;
}
import path from "node:path";
export function managedRemoteHomeEnvironment(home: string): Record<string, string> {
return {
HOME: home,
XDG_CONFIG_HOME: path.posix.join(home, ".config"),
XDG_DATA_HOME: path.posix.join(home, ".local", "share"),
XDG_CACHE_HOME: path.posix.join(home, ".cache"),
XDG_STATE_HOME: path.posix.join(home, ".local", "state"),
};
}
@@ -1,3 +1,5 @@
import { execFile } from "node:child_process";
import { promisify } from "node:util";
import { mkdir, mkdtemp, rm, writeFile } from "node:fs/promises";
import os from "node:os";
import path from "node:path";
@@ -11,7 +13,7 @@ const {
} = vi.hoisted(() => ({
prepareWorkspaceForSshExecution: vi.fn(async () => ({ gitBacked: false })),
restoreWorkspaceFromSshExecution: vi.fn(async () => undefined),
runSshCommand: vi.fn(async () => ({
runSshCommand: vi.fn(async (_spec?: unknown, _command?: string, _options?: unknown) => ({
stdout: Buffer.from('{"token":"remote"}\n').toString("base64"),
stderr: "",
})),
@@ -61,6 +63,7 @@ describe("remote managed runtime", () => {
afterEach(async () => {
vi.clearAllMocks();
runSshCommand.mockReset().mockResolvedValue({ stdout: Buffer.from('{"token":"remote"}\n').toString("base64"), stderr: "" });
while (cleanupDirs.length > 0) {
const dir = cleanupDirs.pop();
if (!dir) continue;
@@ -68,6 +71,65 @@ describe("remote managed runtime", () => {
}
});
it("isolates managed credentials for overlapping in-place SSH runs and removes each private runtime after copy-back", async () => {
const rootDir = await mkdtemp(path.join(os.tmpdir(), "paperclip-ssh-credentials-"));
cleanupDirs.push(rootDir);
const homeDir = path.join(rootDir, "selected-account");
await mkdir(homeDir);
await writeFile(path.join(homeDir, "auth.json"), '{"account":"selected-agent"}');
runSshCommand.mockResolvedValueOnce({ stdout: "/tmp/paperclip-ssh-runtime.first\n", stderr: "" })
.mockResolvedValueOnce({ stdout: "/tmp/paperclip-ssh-runtime.second\n", stderr: "" });
const restore = vi.fn(async () => {});
const input = {
spec: { host: "127.0.0.1", port: 2222, username: "fixture", remoteWorkspacePath: "/app", remoteCwd: "/app", privateKey: null, knownHosts: null, strictHostKeyChecking: true },
runId: "first", adapterKey: "codex", workspaceLocalDir: rootDir, syncWorkspace: false, privateRuntime: true,
assets: [{ key: "home", localDir: homeDir, restore }],
};
const first = await prepareRemoteManagedRuntime(input);
const second = await prepareRemoteManagedRuntime({ ...input, runId: "second" });
expect(first.runtimeRootDir).toBe("/tmp/paperclip-ssh-runtime.first");
expect(second.runtimeRootDir).toBe("/tmp/paperclip-ssh-runtime.second");
expect(first.assetDirs.home).not.toBe(second.assetDirs.home);
await Promise.all([first.restoreWorkspace(), first.restoreWorkspace()]);
await first.restoreWorkspace();
expect(restore).toHaveBeenCalledTimes(1);
expect(restore).toHaveBeenCalledWith(expect.objectContaining({ assetDir: "/tmp/paperclip-ssh-runtime.first/home" }));
expect(runSshCommand).toHaveBeenCalledWith(expect.anything(), "rm -rf -- '/tmp/paperclip-ssh-runtime.first'", expect.anything());
expect(runSshCommand.mock.calls.some(call => call[1] === "rm -rf -- '/tmp/paperclip-ssh-runtime.second'")).toBe(false);
expect(prepareWorkspaceForSshExecution).not.toHaveBeenCalled();
await second.restoreWorkspace();
});
it("retains an ACP credential home across turns until its session owner disposes it", async () => {
runSshCommand.mockResolvedValueOnce({ stdout: "/tmp/paperclip-ssh-runtime.retained\n", stderr: "" });
const restore = vi.fn(async () => {});
const runtime = await prepareRemoteManagedRuntime({
spec: { host: "127.0.0.1", port: 2222, username: "fixture", remoteWorkspacePath: "/app", remoteCwd: "/app", privateKey: null, knownHosts: null, strictHostKeyChecking: true },
runId: "retained", adapterKey: "codex", workspaceLocalDir: "/unused", syncWorkspace: false,
privateRuntime: true, retainRuntime: true, assets: [{ key: "home", localDir: "/fixture", restore }],
});
await runtime.restoreWorkspace();
await runtime.restoreWorkspace();
expect(restore).toHaveBeenCalledTimes(2);
expect(runSshCommand).not.toHaveBeenCalledWith(expect.anything(), expect.stringContaining("rm -rf"), expect.anything());
await runtime.disposeRuntime();
await runtime.disposeRuntime();
expect(runSshCommand.mock.calls.filter(call => call[1]?.includes("rm -rf"))).toHaveLength(1);
});
it.each(["staging", "refresh"])("removes a private credential home after a %s failure", async phase => {
runSshCommand.mockResolvedValueOnce({ stdout: "/tmp/paperclip-ssh-runtime.failed\n", stderr: "" });
if (phase === "staging") syncDirectoryToSsh.mockRejectedValueOnce(new Error("staging failed"));
const prepare = prepareRemoteManagedRuntime({
spec: { host: "127.0.0.1", port: 2222, username: "fixture", remoteWorkspacePath: "/app", remoteCwd: "/app", privateKey: null, knownHosts: null, strictHostKeyChecking: true },
runId: "failed", adapterKey: "codex", workspaceLocalDir: "/unused", syncWorkspace: false, privateRuntime: true,
assets: [{ key: "home", localDir: "/fixture", restore: async () => { throw new Error("refresh failed"); } }],
});
if (phase === "staging") await expect(prepare).rejects.toThrow("staging failed");
else await expect((await prepare).restoreWorkspace()).rejects.toThrow("refresh failed");
expect(runSshCommand).toHaveBeenCalledWith(expect.anything(), "rm -rf -- '/tmp/paperclip-ssh-runtime.failed'", expect.anything());
});
it("restores runtime assets without restoring an in-place SSH workspace", async () => {
const rootDir = await mkdtemp(path.join(os.tmpdir(), "paperclip-remote-runtime-assets-only-"));
cleanupDirs.push(rootDir);
@@ -116,12 +178,55 @@ describe("remote managed runtime", () => {
expect(restoreWorkspaceFromSshExecution).not.toHaveBeenCalled();
expect(runSshCommand).toHaveBeenCalledWith(
expect.anything(),
"base64 < '/app/.paperclip-runtime/codex/home/auth.json'",
expect.stringContaining("base64 < '/app/.paperclip-runtime/codex/home/auth.json'"),
{ maxBuffer: 1024 * 1024 },
);
expect(restoredAuth).toBe('{"token":"remote"}\n');
});
it.each(["missing", "missing with SSH warning", "present", "read failure", "connection failure"])(
"preserves SSH file-read error semantics for %s files",
async outcome => {
const root = await mkdtemp(path.join(os.tmpdir(), "paperclip-ssh-file-read-"));
cleanupDirs.push(root);
const remoteCwd = path.join(root, "remote's workspace");
const assetDir = path.join(remoteCwd, ".paperclip-runtime", "codex", "home");
await mkdir(assetDir, { recursive: true });
const content = Buffer.from([0, 255, 1, 10]);
if (!outcome.startsWith("missing")) await writeFile(path.join(assetDir, "auth.json"), content);
const transportError = Object.assign(new Error("fixture SSH connection failed"), { code: 255 });
runSshCommand.mockImplementationOnce(async (_spec, command) => {
if (outcome === "connection failure") throw transportError;
const script = outcome === "read failure"
? `base64() { printf '%s\\n' 'fixture read failure' >&2; return 44; }; ${command}`
: outcome === "missing with SSH warning"
? `printf '%s\\n' 'fixture SSH host-key warning' >&2; ${command}`
: command!;
return promisify(execFile)("sh", ["-c", script!]);
});
let bytes: Buffer | undefined;
const prepared = await prepareRemoteManagedRuntime({
spec: { host: "ssh.example.test", port: 22, username: "agent", remoteWorkspacePath: remoteCwd,
remoteCwd, privateKey: null, knownHosts: null, strictHostKeyChecking: true },
runId: "read-file", adapterKey: "codex", workspaceLocalDir: root, workspaceRemoteDir: remoteCwd,
syncWorkspace: false,
assets: [{ key: "home", localDir: root, restore: async ({ assetDir, readFile }) => {
bytes = await readFile(path.posix.join(assetDir, "auth.json"));
} }],
});
if (outcome === "present") {
await prepared.restoreWorkspace();
expect(bytes).toEqual(content);
} else if (outcome.startsWith("missing")) {
await expect(prepared.restoreWorkspace()).rejects.toMatchObject({ code: "ENOENT" });
} else if (outcome === "connection failure") {
await expect(prepared.restoreWorkspace()).rejects.toBe(transportError);
} else {
await expect(prepared.restoreWorkspace()).rejects.toMatchObject({ code: 44, stderr: "fixture read failure\n" });
}
},
);
it("stages each additional project into its own isolated SSH dir, isolating one failure", async () => {
const rootDir = await mkdtemp(path.join(os.tmpdir(), "paperclip-remote-runtime-additional-"));
cleanupDirs.push(rootDir);
@@ -53,6 +53,7 @@ export interface PreparedRemoteManagedRuntime {
* absent (per-project failure isolation).
*/
additionalSourceDirs: Record<string, string>;
disposeRuntime(): Promise<void>;
restoreWorkspace(onProgress?: RuntimeProgressSink): Promise<void>;
}
@@ -75,16 +76,29 @@ function shellQuote(value: string): string {
}
async function readRemoteFile(spec: SshRemoteExecutionSpec, remotePath: string): Promise<Buffer> {
const result = await runSshCommand(spec, `base64 < ${shellQuote(remotePath)}`, {
maxBuffer: 1024 * 1024,
});
return Buffer.from(result.stdout.replace(/\s+/g, ""), "base64");
const missingMarker = "paperclip:remote-file-missing";
const missingExitCode = 44;
const file = shellQuote(remotePath);
const parent = shellQuote(path.posix.dirname(remotePath));
/* Confirm the parent is searchable so a permission error cannot masquerade as absence. */
const command = `if [ -d ${parent} ] && [ -x ${parent} ] && [ ! -e ${file} ]; then printf '%s\\n' '${missingMarker}'; exit ${missingExitCode}; fi; base64 < ${file}`;
try {
const result = await runSshCommand(spec, command, { maxBuffer: 1024 * 1024 });
return Buffer.from(result.stdout.replace(/\s+/g, ""), "base64");
} catch (error) {
const failure = error as { code?: unknown; stdout?: unknown } | null;
if (failure?.code === missingExitCode && typeof failure.stdout === "string" && failure.stdout.trim() === missingMarker) {
throw Object.assign(new Error("Remote runtime file does not exist"), { code: "ENOENT" });
}
throw error;
}
}
export function buildRemoteExecutionSessionIdentity(spec: SshRemoteExecutionSpec | null) {
if (!spec) return null;
return {
transport: "ssh",
...(typeof spec.useHostAuth === "boolean" ? { useHostAuth: spec.useHostAuth } : {}),
host: spec.host,
port: spec.port,
username: spec.username,
@@ -99,6 +113,7 @@ export function remoteExecutionSessionMatches(saved: unknown, current: SshRemote
const parsedSaved = asObject(saved);
return (
asString(parsedSaved.transport) === currentIdentity.transport &&
parsedSaved.useHostAuth === currentIdentity.useHostAuth &&
asString(parsedSaved.host) === currentIdentity.host &&
asNumber(parsedSaved.port) === currentIdentity.port &&
asString(parsedSaved.username) === currentIdentity.username &&
@@ -113,6 +128,8 @@ export async function prepareRemoteManagedRuntime(input: {
workspaceLocalDir: string;
workspaceRemoteDir?: string;
syncWorkspace?: boolean;
privateRuntime?: boolean;
retainRuntime?: boolean;
workspaceFileMode?: "all";
workspaceExclude?: string[];
assets?: RemoteManagedRuntimeAsset[];
@@ -133,7 +150,13 @@ export async function prepareRemoteManagedRuntime(input: {
"workspace",
)
: baseWorkspaceRemoteDir;
const runtimeRootDir = path.posix.join(workspaceRemoteDir, ".paperclip-runtime", input.adapterKey);
let runtimeRootDir = path.posix.join(workspaceRemoteDir, ".paperclip-runtime", input.adapterKey);
let privateRuntimeDir: string | null = null;
const cleanupPrivateRuntime = async () => {
if (!privateRuntimeDir) return;
await runSshCommand(input.spec, `rm -rf -- ${shellQuote(privateRuntimeDir)}`, { timeoutMs: 15_000 });
privateRuntimeDir = null;
};
const preparedWorkspace = syncWorkspace
? await prepareWorkspaceForSshExecution({
@@ -169,7 +192,14 @@ export async function prepareRemoteManagedRuntime(input: {
const assetDirs: Record<string, string> = {};
try {
if (input.privateRuntime) {
const result = await runSshCommand(input.spec, "umask 077; mktemp -d /tmp/paperclip-ssh-runtime.XXXXXXXXXX", { timeoutMs: 15_000 });
const directory = result.stdout.trim();
if (!/^\/tmp\/paperclip-ssh-runtime\.[A-Za-z0-9]+$/.test(directory)) throw new Error("SSH private runtime directory unavailable");
runtimeRootDir = privateRuntimeDir = directory;
}
for (const asset of input.assets ?? []) {
if (input.privateRuntime && !/^[A-Za-z0-9_-]+$/.test(asset.key)) throw new Error("Invalid SSH runtime asset key");
const remoteDir = path.posix.join(runtimeRootDir, asset.key);
assetDirs[asset.key] = remoteDir;
await syncDirectoryToSsh({
@@ -183,8 +213,8 @@ export async function prepareRemoteManagedRuntime(input: {
});
}
} catch (error) {
if (preparedWorkspace && baselineSnapshot) {
await restoreWorkspaceFromSshExecution({
try {
if (preparedWorkspace && baselineSnapshot) await restoreWorkspaceFromSshExecution({
spec: input.spec,
localDir: input.workspaceLocalDir,
remoteDir: workspaceRemoteDir,
@@ -193,7 +223,7 @@ export async function prepareRemoteManagedRuntime(input: {
onProgress: input.onProgress,
repositories: repositoryBaselines,
});
}
} finally { await cleanupPrivateRuntime(); }
throw error;
}
@@ -243,6 +273,33 @@ export async function prepareRemoteManagedRuntime(input: {
}
}
const restore = async (onProgress?: RuntimeProgressSink) => {
let failure: unknown;
try {
if (preparedWorkspace && baselineSnapshot) await restoreWorkspaceFromSshExecution({
spec: input.spec,
localDir: input.workspaceLocalDir,
remoteDir: workspaceRemoteDir,
baselineSnapshot,
restoreGitHistory: preparedWorkspace.gitBacked,
onProgress,
repositories: repositoryBaselines,
});
} catch (error) { failure = error; }
for (const asset of input.assets ?? []) {
if (!asset.restore) continue;
try { await asset.restore({
assetDir: path.posix.join(runtimeRootDir, asset.key),
readFile: (remotePath) => readRemoteFile(input.spec, remotePath),
}); } catch (error) { failure ??= error; }
}
if (!input.retainRuntime) {
try { await cleanupPrivateRuntime(); } catch (error) { failure ??= error; }
}
if (failure) throw failure;
};
let privateRestore: Promise<void> | undefined;
return {
spec: input.spec,
workspaceLocalDir: input.workspaceLocalDir,
@@ -250,25 +307,10 @@ export async function prepareRemoteManagedRuntime(input: {
runtimeRootDir,
assetDirs,
additionalSourceDirs,
restoreWorkspace: async (onProgress?: RuntimeProgressSink) => {
if (preparedWorkspace && baselineSnapshot) {
await restoreWorkspaceFromSshExecution({
spec: input.spec,
localDir: input.workspaceLocalDir,
remoteDir: workspaceRemoteDir,
baselineSnapshot,
restoreGitHistory: preparedWorkspace.gitBacked,
onProgress,
repositories: repositoryBaselines,
});
}
for (const asset of input.assets ?? []) {
if (!asset.restore) continue;
await asset.restore({
assetDir: path.posix.join(runtimeRootDir, asset.key),
readFile: (remotePath) => readRemoteFile(input.spec, remotePath),
});
}
disposeRuntime: cleanupPrivateRuntime,
restoreWorkspace: (onProgress?: RuntimeProgressSink) => {
if (!input.privateRuntime || input.retainRuntime) return restore(onProgress);
return privateRestore ??= restore(onProgress);
},
};
}
+6 -3
View File
@@ -100,6 +100,7 @@ interface SpawnTarget {
cwd?: string;
env?: Record<string, string | undefined>;
cleanup?: () => Promise<void>;
stdinPrefix?: string;
}
type RemoteExecutionSpec = SshRemoteExecutionSpec;
@@ -3753,6 +3754,7 @@ async function resolveSpawnTarget(
args: spawnTarget.args,
cwd: process.cwd(),
cleanup: spawnTarget.cleanup,
stdinPrefix: spawnTarget.stdinPrefix,
};
}
@@ -4869,6 +4871,7 @@ export async function runChildProcess(
localProcessSandbox: opts.localProcessSandbox ?? null,
})
.then((target) => {
const processStdin = target.stdinPrefix ? target.stdinPrefix + (opts.stdin ?? "") : opts.stdin;
const childEnv = { ...mergedEnv, ...target.env };
for (const [key, value] of Object.entries(childEnv)) {
if (value === undefined) delete childEnv[key];
@@ -4878,7 +4881,7 @@ export async function runChildProcess(
env: childEnv,
detached: process.platform !== "win32",
shell: false,
stdio: [opts.stdin != null ? "pipe" : "ignore", "pipe", "pipe"],
stdio: [processStdin != null ? "pipe" : "ignore", "pipe", "pipe"],
}) as ChildProcessWithEvents;
const startedAt = new Date().toISOString();
const processGroupId = resolveProcessGroupId(child);
@@ -5032,7 +5035,7 @@ export async function runChildProcess(
});
const stdin = child.stdin;
if (opts.stdin != null && stdin) {
if (processStdin != null && stdin) {
let stdinFailureHandled = false;
const handleStdinFailure = (err: unknown) => {
if (!err || stdinFailureHandled) return;
@@ -5052,7 +5055,7 @@ export async function runChildProcess(
)
return;
try {
stdin.write(opts.stdin as string, handleStdinFailure);
stdin.write(processStdin, handleStdinFailure);
stdin.end();
} catch (err) {
handleStdinFailure(err);
@@ -0,0 +1,22 @@
import { describe, expect, it } from "vitest";
import { parseSshRemoteExecutionSpec } from "./ssh.js";
import { buildRemoteExecutionSessionIdentity, remoteExecutionSessionMatches } from "./remote-managed-runtime.js";
const spec = { host: "ssh.example.test", port: 22, username: "fixture", remoteCwd: "/workspace", remoteWorkspacePath: "/workspace", privateKey: null, knownHosts: null, strictHostKeyChecking: true };
describe("SSH authentication source", () => {
it.each([undefined, true, false])("preserves the SSH authentication option through target parsing (%s)", useHostAuth => {
const target = { ...spec, ...(useHostAuth !== undefined ? { useHostAuth } : {}) };
expect(parseSshRemoteExecutionSpec(target)).toEqual(target);
expect(parseSshRemoteExecutionSpec({ ...spec, useHostAuth: "false" })).toBeNull();
});
it("starts a fresh SSH session when its authentication source changes", () => {
const saved = buildRemoteExecutionSessionIdentity(spec);
expect(remoteExecutionSessionMatches(saved, { ...spec })).toBe(true);
expect(remoteExecutionSessionMatches(saved, { ...spec, useHostAuth: false })).toBe(false);
const configured = buildRemoteExecutionSessionIdentity({ ...spec, useHostAuth: false });
expect(remoteExecutionSessionMatches(configured, { ...spec, useHostAuth: false })).toBe(true);
expect(remoteExecutionSessionMatches(configured, { ...spec, useHostAuth: true })).toBe(false);
});
});
@@ -1,7 +1,8 @@
import { mkdtemp, rm } from "node:fs/promises";
import { mkdtemp, rm, writeFile } from "node:fs/promises";
import os from "node:os";
import path from "node:path";
import { afterEach, describe, expect, it, vi } from "vitest";
import { spawn } from "node:child_process";
vi.mock("node:child_process", async (importOriginal) => {
const actual = await importOriginal<typeof import("node:child_process")>();
@@ -18,10 +19,11 @@ vi.mock("node:child_process", async (importOriginal) => {
};
});
import { createSshCommandManagedRuntimeRunner } from "./ssh.js";
import { createSshCommandManagedRuntimeRunner, runSshCommand } from "./ssh.js";
const roots: string[] = [];
afterEach(async () => {
vi.unstubAllEnvs();
for (const root of roots.splice(0)) await rm(root, { recursive: true, force: true });
});
@@ -38,6 +40,23 @@ async function runner() {
}
describe("SSH command-managed argv", () => {
it.each(["spawn", "command"])("decodes with BSD-compatible flags and preserves stdin through %s", async mode => {
const bin = await mkdtemp(path.join(os.tmpdir(), "ssh-bsd-base64-"));
roots.push(bin);
await writeFile(path.join(bin, "base64"), `#!${process.execPath}\nif (process.argv.length !== 3 || process.argv[2] !== '-d') process.exit(2);\nlet text='';process.stdin.on('data', b => text+=b);process.stdin.on('end', () => process.stdout.write(Buffer.from(text,'base64')));\n`, { mode: 0o700 });
vi.stubEnv("PATH", bin + path.delimiter + process.env.PATH);
const invocation = { command: "sh", args: ["-c", 'printf "%s\\n" "$SENTINEL_TEXT"; cat'], env: { SENTINEL_TEXT: "fixture-credential" }, stdin: "provider input\n", timeoutMs: 5000 };
const result = mode === "spawn" ? await (await runner()).execute(invocation) : await runSshCommand({ host: "fixture.invalid", port: 22, username: "fixture", remoteWorkspacePath: "/tmp", privateKey: null, knownHosts: null, strictHostKeyChecking: true }, 'printf "%s\\n" "$SENTINEL_TEXT"; cat', invocation);
expect(result.stdout).toBe("fixture-credential\nprovider input\n");
});
it("delivers configured credentials without placing them in SSH process arguments and preserves provider stdin", async () => {
const token = "selected-agent-subscription-canary";
const result = await (await runner()).execute({ command: "sh", args: ["-c", 'printf "%s\\n" "$CLAUDE_CODE_OAUTH_TOKEN"; cat'],
env: { CLAUDE_CODE_OAUTH_TOKEN: token }, stdin: "provider input\n", timeoutMs: 5000 });
expect(result.exitCode).toBe(0);
expect(result.stdout).toBe(token + "\nprovider input\n");
expect(vi.mocked(spawn).mock.calls.at(-1)?.[1]?.join(" ")).not.toContain(token);
});
it("rejects environment keys that could be interpreted as env options", async () => {
await expect((await runner()).execute({ command: "true", env: { "-u": "PATH" } }))
.rejects.toThrow("Invalid SSH environment variable key");
@@ -0,0 +1,48 @@
import { createHash } from "node:crypto";
import path from "node:path";
import { shellQuote } from "./ssh.js";
/** Retain provider-owned conversation files while scrubbing per-turn credentials. */
export async function prepareSshConversationState(input: {
adapterKey: string;
preserve: readonly string[];
remoteRoot: string;
companyId: string;
agentId: string;
accountIdentity: string;
executionIdentity: unknown;
runId: string;
savedScope: unknown;
savedConversationId: unknown;
stagedHome?: string;
run: (command: string) => Promise<void>;
}) {
if (!/^[a-z0-9_-]+$/.test(input.adapterKey) || input.preserve.length === 0
|| input.preserve.some(pattern => !/^[A-Za-z0-9_.*-]+$/.test(pattern))) {
throw new Error("Invalid SSH conversation retention policy");
}
const hash = (value: unknown) => createHash("sha256").update(JSON.stringify(value)).digest("hex");
const scope = hash([input.companyId, input.agentId, input.accountIdentity, input.executionIdentity]);
const savedId = input.savedConversationId;
const canResume = input.savedScope === scope && typeof savedId === "string" && /^[a-f0-9]{64}$/.test(savedId);
const conversationId = canResume ? savedId : hash(input.runId);
const home = path.posix.join(input.remoteRoot, ".paperclip-runtime", input.adapterKey, "conversations", scope, conversationId);
const prefix = `set -eu\numask 077\nhome=${shellQuote(home)}\n[ ! -L "$home" ]\n`;
const stateOnly = `for entry in "$home"/* "$home"/.[!.]* "$home"/..?*; do
[ -e "$entry" ] || [ -L "$entry" ] || continue
if [ ! -L "$entry" ]; then
case "\${entry##*/}" in
${input.preserve.join("|")} ) continue ;;
esac
fi
rm -rf -- "$entry"
done`;
const cleanup = () => input.run(`${prefix}if [ -d "$home" ]; then\n${stateOnly}\nfi`);
try {
await input.run(`${prefix}mkdir -p "$home"\nchmod 700 "$home"\n${stateOnly}${input.stagedHome ? `\ncp -RP ${shellQuote(input.stagedHome + "/.")} "$home/"` : ""}`);
} catch (error) {
await cleanup();
throw error;
}
return { home, scope, conversationId, canResume, cleanup };
}
+71 -4
View File
@@ -14,11 +14,15 @@ import {
runSshCommand,
syncDirectoryFromSsh,
syncDirectoryToSsh,
shellQuote,
startSshEnvLabFixture,
stopSshEnvLabFixture,
type SshEnvLabFixtureState,
} from "./ssh.js";
import { runChildProcess } from "./server-utils.js";
import { startAdapterExecutionTargetProcessSessionBridge } from "./execution-target.js";
import { prepareRemoteManagedRuntime } from "./remote-managed-runtime.js";
import { managedRemoteHomeEnvironment } from "./remote-execution-env.js";
const SSH_FIXTURE_TEST_TIMEOUT_MS = 30_000;
const UNREACHABLE_SSH_SPEC = {
@@ -204,6 +208,71 @@ describe("ssh env-lab fixture", () => {
expect(stopped.running).toBe(false);
}, SSH_FIXTURE_TEST_TIMEOUT_MS);
it("isolates managed agent credentials over real SSH and copies refreshes back before cleanup", async context => {
const rootDir = await createFixtureRootDir();
const started = await startSshEnvLabFixtureOrSkip(path.join(rootDir, "state.json"), "managed SSH account test");
if (!started) { context.skip();return; }
const spec = { ...await buildSshEnvLabFixtureConfig(started), remoteCwd: started.workspaceDir };
const selected = path.join(rootDir, "selected-account"), other = path.join(rootDir, "other-account");
await mkdir(selected, { mode: 0o700 });await mkdir(other, { mode: 0o700 });
await writeFile(path.join(selected, "auth.json"), '{"account":"configured-agent","token":"fixture-before"}', { mode: 0o600 });
await writeFile(path.join(other, "auth.json"), '{"account":"another-agent"}', { mode: 0o600 });
const first = await prepareRemoteManagedRuntime({ spec, runId: "selected", adapterKey: "codex", workspaceLocalDir: started.workspaceDir, syncWorkspace: false, privateRuntime: true,
assets: [{ key: "home", localDir: selected, restore: async ({ assetDir, readFile }) => { await writeFile(path.join(selected, "auth.json"), await readFile(path.posix.join(assetDir, "auth.json")), { mode: 0o600 }); } }] });
let second: Awaited<ReturnType<typeof prepareRemoteManagedRuntime>> | undefined;
try {
second = await prepareRemoteManagedRuntime({ spec, runId: "other", adapterKey: "codex", workspaceLocalDir: started.workspaceDir, syncWorkspace: false, privateRuntime: true, assets: [{ key: "home", localDir: other }] });
expect(second.runtimeRootDir).not.toBe(first.runtimeRootDir);
expect((await stat(first.runtimeRootDir)).mode & 0o777).toBe(0o700);
const read = await runSshCommand(spec, 'cat "$CODEX_HOME/auth.json"', { env: { ...managedRemoteHomeEnvironment(first.runtimeRootDir), CODEX_HOME: first.assetDirs.home! } });
expect(JSON.parse(read.stdout).account).toBe("configured-agent");
const provider = await runChildProcess("selected-account-fixture", "sh", ["-c", 'cat "$CODEX_HOME/auth.json"; printf "\\n"; cat'], {
cwd: started.workspaceDir, env: { ...managedRemoteHomeEnvironment(first.runtimeRootDir), CODEX_HOME: first.assetDirs.home! },
remoteExecution: spec, stdin: "provider-input\n", timeoutSec: 10, graceSec: 1, onLog: async () => {},
});
expect(provider.exitCode).toBe(0);
expect(provider.stdout).toBe('{"account":"configured-agent","token":"fixture-before"}\nprovider-input\n');
const refreshed = '{"account":"configured-agent","token":"fixture-refreshed"}';
await runSshCommand(spec, `printf '%s' ${shellQuote(refreshed)} > ${shellQuote(path.posix.join(first.assetDirs.home!, "auth.json"))}`);
await first.restoreWorkspace();
expect(await readFile(path.join(selected, "auth.json"), "utf8")).toBe(refreshed);
await expect(stat(first.runtimeRootDir)).rejects.toMatchObject({ code: "ENOENT" });
expect(JSON.parse(await readFile(path.join(second.assetDirs.home!, "auth.json"), "utf8")).account).toBe("another-agent");
} finally {
try {
await Promise.all([first.restoreWorkspace(), second?.restoreWorkspace()]);
} finally {
await stopSshEnvLabFixture(started);
}
}
}, SSH_FIXTURE_TEST_TIMEOUT_MS);
it("runs the ACP process bridge through real SSH with the selected account's home", async context => {
const root = await createFixtureRootDir();
const started = await startSshEnvLabFixtureOrSkip(path.join(root, "state.json"), "SSH ACP bridge test");
if (!started) { context.skip(); return; }
const spec = { ...await buildSshEnvLabFixtureConfig(started), remoteCwd: started.workspaceDir };
const runtime = await prepareRemoteManagedRuntime({ spec, runId: "acp", adapterKey: "custom", workspaceLocalDir: started.workspaceDir, syncWorkspace: false, privateRuntime: true });
let bridge: Awaited<ReturnType<typeof startAdapterExecutionTargetProcessSessionBridge>>;
try {
bridge = await startAdapterExecutionTargetProcessSessionBridge({
runId: "acp-ssh-fixture", target: { kind: "remote", transport: "ssh", spec, remoteCwd: spec.remoteCwd },
runtimeRootDir: runtime.runtimeRootDir, adapterKey: "custom", cwd: spec.remoteCwd, command: "node",
args: ["-e", 'process.stdin.on("data", data => { process.stdout.write(JSON.stringify({home:process.env.HOME, input:data.toString()})+"\\n"); process.exit(0); });'],
env: managedRemoteHomeEnvironment(runtime.runtimeRootDir), timeoutSec: 15, onLog: async () => {},
});
expect(bridge).not.toBeNull();
const result = await runChildProcess("acp-proxy-fixture", "sh", ["-c", bridge!.agentCommand], {
cwd: root, env: {}, stdin: "hello\n", timeoutSec: 15, graceSec: 1, onLog: async () => {},
});
expect(result.exitCode).toBe(0);
expect(JSON.parse(result.stdout)).toEqual({ home: runtime.runtimeRootDir, input: "hello\n" });
} finally {
try { await bridge!?.stop(); }
finally { await runtime.restoreWorkspace(); await stopSshEnvLabFixture(started); }
}
}, SSH_FIXTURE_TEST_TIMEOUT_MS);
it("resolves a relative statePath to the same absolute state across start, status, and stop", async () => {
const rootDir = await createFixtureRootDir();
const absoluteStatePath = path.join(rootDir, "state.json");
@@ -474,11 +543,11 @@ describe("ssh env-lab fixture", () => {
env: { FOO: "bar" },
});
// The remote script rides the last ssh argument. The SSH target is an
// The remote script travels through stdin. The SSH target is an
// operator-configured host that can expose `node` only through a login
// profile, so the wrapper sources the profiles. It no longer sources
// `nvm.sh`; a profile that adds nvm still runs.
const remoteScript = String(target.args.at(-1) ?? "");
const remoteScript = Buffer.from(target.stdinPrefix.trim(), "base64").toString("utf8");
expect(remoteScript).not.toContain("nvm.sh");
expect(remoteScript).not.toContain("NVM_DIR");
// Source /etc/profile so a host that exposes the PATH through
@@ -490,8 +559,6 @@ describe("ssh env-lab fixture", () => {
// Fall back to .bashrc when no .bash_profile exists, so a host that adds
// nvm in .bashrc still resolves node under a non-login SSH command.
expect(remoteScript).toContain(".bashrc");
// The last ssh argument wraps the script as `sh -c '...'`, so the inner
// quotes are escaped. Assert the command still runs: cd, env, and the argv.
expect(remoteScript).toContain("cd ");
expect(remoteScript).toContain("/srv/paperclip/workspace");
expect(remoteScript).toContain("exec env ");
+17 -16
View File
@@ -17,6 +17,7 @@ import {
} from "./git-workspace-sync.js";
import type { RunProcessResult } from "./server-utils.js";
import type { DirectorySnapshot } from "./workspace-restore-merge.js";
import { mergeDirectoryWithBaseline } from "./workspace-restore-merge.js";
import {
createRuntimeProgressReporter,
@@ -25,7 +26,10 @@ import {
type RuntimeProgressSink,
} from "./runtime-progress.js";
const SSH_STDIN_COMMAND = "IFS= read -r paperclip_ssh_command_b64 || exit 125; paperclip_ssh_command=$(printf '%s' \"$paperclip_ssh_command_b64\" | base64 -d) || exit 125; unset paperclip_ssh_command_b64; eval \"$paperclip_ssh_command\"";
export interface SshConnectionConfig {
useHostAuth?: boolean;
host: string;
port: number;
username: string;
@@ -68,14 +72,12 @@ export function createSshCommandManagedRuntimeRunner(input: {
throw new Error(`Invalid SSH environment variable key: ${key}`);
}
}
const envPrefix = envEntries.length > 0
? `env ${envEntries.map(([key, value]) => shellQuote(`${key}=${value}`)).join(" ")} `
: "";
const commandScript = `exec ${envPrefix}${[shellQuote(command), ...args.map((arg) => shellQuote(arg))].join(" ")}`;
const commandScript = `exec ${[shellQuote(command), ...args.map((arg) => shellQuote(arg))].join(" ")}`;
const remoteCommand = `cd ${shellQuote(cwd)} && ${commandScript}`;
try {
const result = await runSshCommand(input.spec, remoteCommand, {
env: Object.fromEntries(envEntries),
stdin: commandInput.stdin,
timeoutMs: commandInput.timeoutMs,
maxBuffer: maxBufferBytes,
@@ -174,8 +176,10 @@ export function parseSshRemoteExecutionSpec(value: unknown): SshRemoteExecutionS
if (!host || !username || !remoteCwd || !Number.isInteger(portValue) || portValue < 1 || portValue > 65535) {
return null;
}
if (parsed.useHostAuth !== undefined && typeof parsed.useHostAuth !== "boolean") return null;
return {
...(typeof parsed.useHostAuth === "boolean" ? { useHostAuth: parsed.useHostAuth } : {}),
host,
port: portValue,
username,
@@ -1343,19 +1347,14 @@ export async function runSshCommand(
"-p",
String(config.port),
`${config.username}@${config.host}`,
`sh -c ${shellQuote(remoteScript)}`,
`sh -c ${shellQuote(SSH_STDIN_COMMAND)}`,
);
return options.stdin != null
? await spawnText("ssh", sshArgs, {
stdin: options.stdin,
timeout: options.timeoutMs ?? 15_000,
maxBuffer: options.maxBuffer ?? 1024 * 128,
})
: await execFileText("ssh", sshArgs, {
timeout: options.timeoutMs ?? 15_000,
maxBuffer: options.maxBuffer ?? 1024 * 128,
});
return await spawnText("ssh", sshArgs, {
stdin: Buffer.from(remoteScript).toString("base64") + "\n" + (options.stdin ?? ""),
timeout: options.timeoutMs ?? 15_000,
maxBuffer: options.maxBuffer ?? 1024 * 128,
});
} finally {
await cleanup();
}
@@ -1369,6 +1368,7 @@ export async function buildSshSpawnTarget(input: {
}): Promise<{
command: string;
args: string[];
stdinPrefix: string;
cleanup: () => Promise<void>;
}> {
for (const key of Object.keys(input.env)) {
@@ -1408,12 +1408,13 @@ export async function buildSshSpawnTarget(input: {
"-p",
String(input.spec.port),
`${input.spec.username}@${input.spec.host}`,
`sh -c ${shellQuote(remoteScript)}`,
`sh -c ${shellQuote(SSH_STDIN_COMMAND)}`,
);
return {
command: "ssh",
args: sshArgs,
stdinPrefix: Buffer.from(remoteScript).toString("base64") + "\n",
cleanup: auth.cleanup,
};
}
@@ -51,6 +51,16 @@ describe.each(ADAPTER_MESSAGE_PAIRS)("createWorkspaceRestoreTeardown ($adapter)"
} });
});
it("restores workspace and credentials even when the run log has closed", async () => {
let restored = false;
const outcome = await createWorkspaceRestoreTeardown({
stagedRuntime: { restoreWorkspace: async () => { restored = true; } },
onLog: async () => { throw new Error("fixture log closed"); }, startMessage, failurePrefix,
})();
expect(restored).toBe(true);
expect(outcome).toEqual({ ok: true });
});
it("logs the start message to stdout and returns ok on a clean restore", async () => {
const logLines: Array<{ stream: "stdout" | "stderr"; chunk: string }> = [];
const teardown = createWorkspaceRestoreTeardown({
@@ -36,7 +36,7 @@ export function createWorkspaceRestoreTeardown(input: {
const { stagedRuntime, onLog, startMessage, failurePrefix } = input;
return () => withWorkspaceRestoreDiagnosticCapture(async () => {
try {
await onLog("stdout", startMessage);
await Promise.resolve().then(() => onLog("stdout", startMessage)).catch(() => {});
await stagedRuntime.restoreWorkspace((line) => onLog("stdout", line));
return { ok: true };
} catch (err) {
@@ -46,7 +46,7 @@ export function createWorkspaceRestoreTeardown(input: {
// diagnostic for the classified code.
const code = classifyWorkspaceRestoreFailure(err);
const diagnostic = getWorkspaceRestoreDiagnostic(err);
await onLog("stderr", `${failurePrefix}: ${describeWorkspaceRestoreFailure(code)}\n`);
await Promise.resolve().then(() => onLog("stderr", `${failurePrefix}: ${describeWorkspaceRestoreFailure(code)}\n`)).catch(() => {});
return { ok: false, code, ...(diagnostic ? { diagnostic } : {}) };
}
});
@@ -443,7 +443,7 @@ describe("claude_local ACP lane", () => {
});
});
it("reports unavailable ACP for non-sandbox remote auto runs", async () => {
it("reports unavailable ACP for SSH host authentication", async () => {
setNodeVersion("v24.11.0");
await expect(
resolveClaudeExecutionEngineForRun({
@@ -467,7 +467,7 @@ describe("claude_local ACP lane", () => {
).resolves.toMatchObject({
engine: "acp",
explicit: false,
unavailableReason: expect.stringContaining("sandbox remote targets only"),
unavailableReason: expect.stringContaining("agent-managed SSH account"),
});
});
@@ -315,6 +315,7 @@ async function prepareClaudeRemoteManagedHome(
await onLog("stdout", `[paperclip] Materializing Claude auth/config into ${remoteClaudeConfigDir}.\n`);
const { toolShellPrefixInstalled } = await materializeRemoteClaudeConfig({
allowHostCredentials: !input.config.managedAiConnection,
runId,
target: executionTarget,
remoteClaudeConfigDir,
@@ -564,7 +565,7 @@ async function commandIsResolvable(
trimmed,
target,
resolveAdapterExecutionTargetCwd(target, asString(input?.config.cwd, ""), process.cwd()),
{},
target.transport === "ssh" ? { PATH: process.env.PATH } : {},
{
// Fresh sandboxes need the same ACP server that ships with this
// adapter. Only bootstrap our default command; an operator's custom
@@ -617,11 +618,16 @@ async function claudeAcpUnavailableReason(
executionTarget: input.executionTarget,
legacyRemoteExecution: input.executionTransport?.remoteExecution,
});
if (target?.kind === "remote" && !sandboxTargetHasProcessSessionBridge(target)) {
const managedSsh = target?.kind === "remote" && target.transport === "ssh"
&& target.spec.useHostAuth === false && Boolean(input.config.managedAiConnection);
if (managedSsh && target.workspaceRealization?.mode === "in_place") {
return "In-place SSH workspace realization requires the Claude CLI engine; ACP archive staging is not supported.";
}
if (target?.kind === "remote" && !sandboxTargetHasProcessSessionBridge(target) && !managedSsh) {
if (target.transport === "sandbox") {
return "Claude ACP requires a bidirectional remote process target; this sandbox exposes only one-shot command execution.";
}
return "Claude ACP supports sandbox remote targets only; this run targets a non-sandbox remote environment.";
return "Claude ACP requires an agent-managed SSH account; host authentication is supported by the CLI engine.";
}
if (!nodeVersionMeetsClaudeAcpMinimum()) {
return `Node ${process.version} (${process.execPath}) does not satisfy Claude ACP's Node >=${MIN_ACP_NODE_VERSION} prerequisite.`;
@@ -1006,24 +1012,30 @@ export async function testClaudeAcpEnvironment(
probeEnv.CLAUDE_CONFIG_DIR = hostConfigDir.trim();
}
const runId = `claude-acp-envtest-${Date.now()}-${Math.random().toString(16).slice(2)}`;
checks.push(
...(await prepareSandboxClaudeProbeRuntime({
managedAiConnection: Boolean(config.managedAiConnection),
runId,
target,
cwd,
companyId: ctx.companyId,
env: probeEnv,
installCommand: SANDBOX_INSTALL_COMMAND,
detectCommand: "claude",
targetIsRemote,
targetIsSandbox,
helloProbeTimeoutSec: asNumber(config.helloProbeTimeoutSec, targetIsSandbox ? 90 : 45),
})),
);
const canProbe = !checks.some((check) => check.code === "claude_managed_config_dir_failed");
if (canProbe) {
checks.push(...(await probeClaudeAcpSandboxLogin({ config, target, env: probeEnv })));
let cleanupManagedProbe: (() => Promise<void>) | undefined;
try {
checks.push(
...(await prepareSandboxClaudeProbeRuntime({
registerCleanup: (cleanup) => { cleanupManagedProbe = cleanup; },
managedAiConnection: Boolean(config.managedAiConnection),
runId,
target,
cwd,
companyId: ctx.companyId,
env: probeEnv,
installCommand: SANDBOX_INSTALL_COMMAND,
detectCommand: "claude",
targetIsRemote,
targetIsSandbox,
helloProbeTimeoutSec: asNumber(config.helloProbeTimeoutSec, targetIsSandbox ? 90 : 45),
})),
);
const canProbe = !checks.some((check) => check.code === "claude_managed_config_dir_failed");
if (canProbe) {
checks.push(...(await probeClaudeAcpSandboxLogin({ config, target, env: probeEnv })));
}
} finally {
await cleanupManagedProbe?.();
}
}
@@ -2,6 +2,7 @@ import * as fs from "node:fs/promises";
import os from "node:os";
import path from "node:path";
import { afterEach, describe, expect, it, vi } from "vitest";
import { runAdapterExecutionTargetShellCommand } from "@paperclipai/adapter-utils/execution-target";
import type { AdapterExecutionTarget } from "@paperclipai/adapter-utils/execution-target";
// A shared handle so the managed-config test can force the runtime preparation
@@ -19,6 +20,7 @@ vi.mock("@paperclipai/adapter-utils/execution-target", async () => {
adapterExecutionTargetUsesManagedHome: () => true,
maybeRunSandboxInstallCommand: async () => null,
prepareAdapterExecutionTargetRuntime,
runAdapterExecutionTargetShellCommand: vi.fn(actual.runAdapterExecutionTargetShellCommand),
};
});
@@ -56,6 +58,17 @@ describe("prepareClaudeConfigSeed", () => {
};
}
it("does not copy the SSH user's existing login into a managed agent's config", async () => {
const root = await fs.mkdtemp(path.join(os.tmpdir(), "paperclip-claude-host-fallback-"));cleanupDirs.push(root);
const hostHome = path.join(root, "ssh-user"), seed = path.join(root, "seed"), target = path.join(root, "managed-config");
await fs.mkdir(path.join(hostHome, ".claude"), { recursive: true });await fs.mkdir(seed);
const original = '{"token":"ssh-user-account-canary"}';
await fs.writeFile(path.join(hostHome, ".claude", ".credentials.json"), original);
await execFileAsync("sh", ["-c", buildRemoteClaudeConfigMaterializationCommand({ remoteClaudeConfigDir: target, remoteClaudeConfigSeedDir: seed, allowHostCredentials: false })], { env: { ...process.env, HOME: hostHome } });
await expect(fs.access(path.join(target, ".credentials.json"))).rejects.toMatchObject({ code: "ENOENT" });
expect(await fs.readFile(path.join(hostHome, ".claude", ".credentials.json"), "utf8")).toBe(original);
});
it("reuses the same snapshot path when the seeded files are unchanged", async () => {
const root = await fs.mkdtemp(path.join(os.tmpdir(), "paperclip-claude-config-seed-"));
cleanupDirs.push(root);
@@ -221,6 +234,25 @@ describe("prepareSandboxClaudeProbeRuntime managed-config diagnostics", () => {
}
});
it("keeps the selected SSH account's probe home until the provider probe finishes", async () => {
const target: AdapterExecutionTarget = { kind: "remote", transport: "ssh", remoteCwd: "/workspace", spec: {
useHostAuth: false, host: "fixture.invalid", port: 22, username: "fixture", remoteCwd: "/workspace", remoteWorkspacePath: "/workspace", privateKey: null, knownHosts: null, strictHostKeyChecking: true,
} };
const restore = vi.fn(async () => {}), registerCleanup = vi.fn<(cleanup: () => Promise<void>) => void>();
const env: Record<string, string> = { HOME: "/controller/selected", CLAUDE_CONFIG_DIR: "/controller/selected/provider", CLAUDE_CODE_OAUTH_TOKEN: "fixture-selected" };
prepareAdapterExecutionTargetRuntime.mockResolvedValueOnce({ runtimeRootDir: "/tmp/paperclip-ssh-runtime.probe", assetDirs: { "config-seed": "/tmp/paperclip-ssh-runtime.probe/config-seed" }, restoreWorkspace: restore });
vi.mocked(runAdapterExecutionTargetShellCommand).mockResolvedValueOnce({ exitCode: 0, signal: null, timedOut: false, stdout: "", stderr: "", pid: null, startedAt: new Date().toISOString() });
const checks = await prepareSandboxClaudeProbeRuntime({ managedAiConnection: true, registerCleanup, runId: "selected-probe", target, cwd: "/workspace", env,
installCommand: "", detectCommand: "claude", targetIsRemote: true, targetIsSandbox: false, helloProbeTimeoutSec: 10 });
expect(checks).toContainEqual(expect.objectContaining({ code: "claude_managed_config_dir" }));
expect(prepareAdapterExecutionTargetRuntime).toHaveBeenCalledWith(expect.objectContaining({ privateRuntime: true, syncWorkspace: false,
assets: [expect.objectContaining({ localDir: "/controller/selected/provider" })] }));
expect(env).toMatchObject({ HOME: "/tmp/paperclip-ssh-runtime.probe", CLAUDE_CONFIG_DIR: "/tmp/paperclip-ssh-runtime.probe/config", CLAUDE_CODE_OAUTH_TOKEN: "fixture-selected" });
expect(restore).not.toHaveBeenCalled();
await registerCleanup.mock.calls[0]![0]();
expect(restore).toHaveBeenCalledOnce();
});
it("keeps a thrown config-materialization error out of every check and the log", async () => {
// The runtime preparation throws an error that carries two untrusted values:
// an opaque credential marker and a proxy marker. Neither may reach a check
@@ -10,6 +10,7 @@ import type {
import {
adapterExecutionTargetUsesManagedHome,
maybeRunSandboxInstallCommand,
managedRemoteHomeEnvironment,
prepareAdapterExecutionTargetRuntime,
runAdapterExecutionTargetShellCommand,
type AdapterExecutionTarget,
@@ -254,6 +255,7 @@ export function buildRemoteClaudeConfigMaterializationCommand(input: {
remoteClaudeConfigDir: string;
remoteClaudeConfigSeedDir: string;
remoteToolShellPrefixPath?: string | null;
allowHostCredentials?: boolean;
}): string {
const prefixPath = input.remoteToolShellPrefixPath;
const installToolShellPrefix = prefixPath
@@ -265,11 +267,11 @@ export function buildRemoteClaudeConfigMaterializationCommand(input: {
`if [ -d ${shellQuote(input.remoteClaudeConfigSeedDir)} ]; then ` +
`cp -R ${shellQuote(`${input.remoteClaudeConfigSeedDir}/.`)} ${shellQuote(input.remoteClaudeConfigDir)}/; ` +
`fi; ` +
`for file in .credentials.json credentials.json; do ` +
(input.allowHostCredentials === false ? "true" : `for file in .credentials.json credentials.json; do ` +
`if [ -n "\${HOME:-}" ] && [ -f "\${HOME}/.claude/\${file}" ] && [ ! -f ${shellQuote(input.remoteClaudeConfigDir)}/"\${file}" ]; then ` +
`cp "\${HOME}/.claude/\${file}" ${shellQuote(input.remoteClaudeConfigDir)}/"\${file}"; ` +
`fi; ` +
`done` +
`done`) +
installToolShellPrefix;
}
@@ -287,6 +289,7 @@ export async function materializeRemoteClaudeConfig(input: {
remoteClaudeConfigDir: string;
remoteClaudeConfigSeedDir: string;
remoteToolShellPrefixPath?: string | null;
allowHostCredentials?: boolean;
options: AdapterExecutionTargetShellOptions;
}): Promise<{ toolShellPrefixInstalled: boolean }> {
const result = await runAdapterExecutionTargetShellCommand(
@@ -296,6 +299,7 @@ export async function materializeRemoteClaudeConfig(input: {
remoteClaudeConfigDir: input.remoteClaudeConfigDir,
remoteClaudeConfigSeedDir: input.remoteClaudeConfigSeedDir,
remoteToolShellPrefixPath: input.remoteToolShellPrefixPath,
allowHostCredentials: input.allowHostCredentials,
}),
input.options,
);
@@ -416,6 +420,7 @@ function isNonEmptyString(value: unknown): value is string {
* the function keeps it and skips the managed materialization.
*/
export async function prepareSandboxClaudeProbeRuntime(input: {
registerCleanup?: (cleanup: () => Promise<void>) => void;
managedAiConnection?: boolean;
runId: string;
target: AdapterExecutionTarget | null;
@@ -442,11 +447,13 @@ export async function prepareSandboxClaudeProbeRuntime(input: {
const hasExplicitClaudeConfigDir = isNonEmptyString(input.env.CLAUDE_CONFIG_DIR);
if (
input.targetIsRemote &&
adapterExecutionTargetUsesManagedHome(input.target) &&
adapterExecutionTargetUsesManagedHome(input.target, input.managedAiConnection) &&
(!hasExplicitClaudeConfigDir || input.managedAiConnection)
) {
let tempWorkspaceDir: string | null = null;
let preparedRuntime: Awaited<ReturnType<typeof prepareAdapterExecutionTargetRuntime>> | null = null;
let cleanupDeferred = false;
const managedSsh = input.target?.kind === "remote" && input.target.transport === "ssh" && input.target.spec.useHostAuth === false && input.managedAiConnection;
try {
const seedDir = input.managedAiConnection ? input.env.CLAUDE_CONFIG_DIR : await prepareClaudeConfigSeed(process.env, async () => {}, input.companyId);
const managedRemoteCwd =
@@ -455,6 +462,8 @@ export async function prepareSandboxClaudeProbeRuntime(input: {
path.join(os.tmpdir(), "paperclip-claude-envtest-workspace-"),
);
preparedRuntime = await prepareAdapterExecutionTargetRuntime({
privateRuntime: Boolean(managedSsh),
syncWorkspace: managedSsh ? false : undefined,
runId: input.runId,
target: input.target,
adapterKey: "claude",
@@ -479,7 +488,9 @@ export async function prepareSandboxClaudeProbeRuntime(input: {
path.posix.join(runtimeRootDir, "config-seed");
const remoteClaudeConfigDir = path.posix.join(runtimeRootDir, "config");
input.env.CLAUDE_CONFIG_DIR = remoteClaudeConfigDir;
if (managedSsh) Object.assign(input.env, managedRemoteHomeEnvironment(runtimeRootDir));
await materializeRemoteClaudeConfig({
allowHostCredentials: !input.managedAiConnection,
runId: input.runId,
target: input.target,
remoteClaudeConfigDir,
@@ -492,6 +503,11 @@ export async function prepareSandboxClaudeProbeRuntime(input: {
onLog: async () => {},
},
});
if (managedSsh && input.registerCleanup) {
const runtime = preparedRuntime;
input.registerCleanup(() => runtime.restoreWorkspace());
cleanupDeferred = true;
}
checks.push({
code: "claude_managed_config_dir",
level: "info",
@@ -514,7 +530,7 @@ export async function prepareSandboxClaudeProbeRuntime(input: {
hint: "Retry the Test. If the failure repeats, check the server log for the redacted diagnostic.",
});
} finally {
await preparedRuntime?.restoreWorkspace().catch(() => undefined);
if (!cleanupDeferred) await preparedRuntime?.restoreWorkspace().catch(() => undefined);
if (tempWorkspaceDir) {
await fs.rm(tempWorkspaceDir, { recursive: true, force: true }).catch(() => undefined);
}
@@ -1,4 +1,6 @@
import { mkdir, mkdtemp, rm, writeFile } from "node:fs/promises";
import { execFile } from "node:child_process";
import { promisify } from "node:util";
import { cp, mkdir, mkdtemp, readdir, readFile, rm, stat, writeFile } from "node:fs/promises";
import os from "node:os";
import path from "node:path";
import { afterEach, describe, expect, it, vi } from "vitest";
@@ -6,13 +8,16 @@ import type { RunProcessResult } from "@paperclipai/adapter-utils/server-utils";
const {
runChildProcess,
executeAcp,
ensureCommandResolvable,
resolveCommandForLogs,
prepareWorkspaceForSshExecution,
restoreWorkspaceFromSshExecution,
syncDirectoryToSsh,
runSshCommand,
startAdapterExecutionTargetPaperclipBridge,
} = vi.hoisted(() => ({
executeAcp: vi.fn(async (_ctx?: unknown) => ({ exitCode: 0, signal: null, timedOut: false, resultJson: { engine: "acp" } })),
runChildProcess: vi.fn(async (_runId: string, _command: string, args: string[]): Promise<RunProcessResult> => ({
exitCode: 0,
signal: null,
@@ -28,11 +33,12 @@ const {
pid: 123,
startedAt: new Date().toISOString(),
})),
ensureCommandResolvable: vi.fn(async () => undefined),
ensureCommandResolvable: vi.fn<typeof import("@paperclipai/adapter-utils/server-utils").ensureCommandResolvable>(async () => undefined),
resolveCommandForLogs: vi.fn(async () => "ssh://fixture@127.0.0.1:2222/remote/workspace :: claude"),
prepareWorkspaceForSshExecution: vi.fn(async () => ({ gitBacked: false })),
restoreWorkspaceFromSshExecution: vi.fn(async () => undefined),
syncDirectoryToSsh: vi.fn(async () => undefined),
syncDirectoryToSsh: vi.fn(async (_input?: { localDir: string; remoteDir: string }) => undefined),
runSshCommand: vi.fn(async (_spec: unknown, command: string) => ({ stdout: command.includes("mktemp -d") ? "/tmp/paperclip-ssh-runtime.claude\n" : "", stderr: "" })),
startAdapterExecutionTargetPaperclipBridge: vi.fn(async () => ({
env: {
PAPERCLIP_API_URL: "http://127.0.0.1:4310",
@@ -43,6 +49,11 @@ const {
})),
}));
vi.mock("./acp.js", async (importOriginal) => {
const actual = await importOriginal<typeof import("./acp.js")>();
return { ...actual, createClaudeAcpExecutor: () => executeAcp };
});
vi.mock("@paperclipai/adapter-utils/server-utils", async () => {
const actual = await vi.importActual<typeof import("@paperclipai/adapter-utils/server-utils")>(
"@paperclipai/adapter-utils/server-utils",
@@ -64,6 +75,7 @@ vi.mock("@paperclipai/adapter-utils/ssh", async () => {
prepareWorkspaceForSshExecution,
restoreWorkspaceFromSshExecution,
syncDirectoryToSsh,
runSshCommand,
};
});
@@ -79,6 +91,7 @@ vi.mock("@paperclipai/adapter-utils/execution-target", async () => {
import { createPromptContextFixture } from "@paperclipai/adapter-utils/test-fixtures/prompt-context";
import { execute } from "./execute.js";
import { sessionCodec } from "./index.js";
import { resetClaudeCliCapabilitiesCacheForTests } from "./cli-capabilities.js";
describe("claude remote execution", () => {
@@ -95,6 +108,208 @@ describe("claude remote execution", () => {
}
});
function managedSshAcpContext(engine?: string) {
return {
runId: "managed-ssh-acp", agent: { id: "agent-1", companyId: "company-1", name: "Selected agent", adapterType: "claude_local", adapterConfig: {} },
runtime: { sessionId: null, sessionParams: null, sessionDisplayId: null, taskKey: "task" },
config: { engine, managedAiConnection: { provider: "anthropic", method: "subscription", identity: "selected-account" },
env: { CLAUDE_CODE_OAUTH_TOKEN: "fixture-selected-token" } } as Record<string, unknown>,
context: {}, onLog: async () => {},
executionTarget: { kind: "remote" as const, transport: "ssh" as const, remoteCwd: "/remote/workspace",
spec: { useHostAuth: false as boolean | undefined, host: "ssh.example.test", port: 22, username: "agent", remoteCwd: "/remote/workspace", remoteWorkspacePath: "/remote/workspace", privateKey: null, knownHosts: null, strictHostKeyChecking: true },
workspaceRealization: { mode: "copy" as "copy" | "in_place", authoritativeRoot: "/remote/workspace", pathAliases: [], outboundRestorePaths: [] } },
};
}
it.each([undefined, "acp"])("admits managed SSH ACP through the public execution entry (engine=%s)", async engine => {
const ctx = managedSshAcpContext(engine);
const actual = await vi.importActual<typeof import("@paperclipai/adapter-utils/server-utils")>("@paperclipai/adapter-utils/server-utils");
const bin = await mkdtemp(path.join(os.tmpdir(), "paperclip-ssh-client-probe-"));
cleanupDirs.push(bin);
await writeFile(path.join(bin, "ssh"), "#!/bin/sh\nexit 0\n", { mode: 0o700 });
const originalResolve = ensureCommandResolvable.getMockImplementation()!;
ensureCommandResolvable.mockImplementationOnce(actual.ensureCommandResolvable);
const previousPath = process.env.PATH;
process.env.PATH = bin;
const previous = process.env.CLAUDE_CODE_OAUTH_TOKEN;
process.env.CLAUDE_CODE_OAUTH_TOKEN = "fixture-server-secret";
try {
expect(await execute(ctx)).toMatchObject({ exitCode: 0, resultJson: { engine: "acp" } });
expect(executeAcp).toHaveBeenCalledWith(ctx);
const probe = ensureCommandResolvable.mock.calls[0] as unknown as unknown[];
expect(probe[0]).toBe("claude-agent-acp");
expect(Object.keys(probe[2] as Record<string, unknown>)).toEqual(["PATH"]);
expect((probe[2] as Record<string, unknown>).PATH === bin).toBe(true);
expect(probe[3]).toMatchObject({ remoteExecution: { host: "ssh.example.test", useHostAuth: false } });
} finally {
ensureCommandResolvable.mockReset().mockImplementation(originalResolve);
if (previousPath === undefined) delete process.env.PATH;
else process.env.PATH = previousPath;
if (previous === undefined) delete process.env.CLAUDE_CODE_OAUTH_TOKEN;
else process.env.CLAUDE_CODE_OAUTH_TOKEN = previous;
}
});
it.each(["host auth", "legacy auth", "missing account", "in-place", "confinement", "missing SSH client"])("rejects unsupported SSH ACP at the public execution entry: %s", async reason => {
const ctx = managedSshAcpContext("acp");
const originalResolve = ensureCommandResolvable.getMockImplementation()!;
if (reason === "host auth") ctx.executionTarget.spec.useHostAuth = true;
if (reason === "legacy auth") ctx.executionTarget.spec.useHostAuth = undefined;
if (reason === "missing account") delete ctx.config.managedAiConnection;
if (reason === "in-place") ctx.executionTarget.workspaceRealization.mode = "in_place";
if (reason === "confinement") ctx.config.filesystemScope = "workspace";
const previousPath = process.env.PATH;
if (reason === "missing SSH client") {
const bin = await mkdtemp(path.join(os.tmpdir(), "paperclip-no-ssh-client-"));
cleanupDirs.push(bin);
process.env.PATH = bin;
const actual = await vi.importActual<typeof import("@paperclipai/adapter-utils/server-utils")>("@paperclipai/adapter-utils/server-utils");
ensureCommandResolvable.mockImplementationOnce(actual.ensureCommandResolvable);
}
try {
expect(await execute(ctx)).toMatchObject({ exitCode: 1, errorCode: "adapter_engine_unavailable" });
expect(executeAcp).not.toHaveBeenCalled();
} finally {
ensureCommandResolvable.mockReset().mockImplementation(originalResolve);
if (previousPath === undefined) delete process.env.PATH;
else process.env.PATH = previousPath;
}
});
it.each([false, true])("keeps managed SSH Claude conversations and scrubs credentials (follow-up fails=%s)", async fails => {
const root = await mkdtemp(path.join(os.tmpdir(), "paperclip-claude-ssh-conversation-"));
cleanupDirs.push(root);
const workspace = path.join(root, "workspace");
await mkdir(workspace);
const homes = await Promise.all(["first", "next"].map(async name => {
const home = path.join(root, name); await mkdir(home); return home;
}));
const sessionId = "aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa";
const originalRun = runChildProcess.getMockImplementation()!;
const originalSsh = runSshCommand.getMockImplementation()!;
const originalSync = syncDirectoryToSsh.getMockImplementation()!;
let firstHome = "";
let calls = 0;
const privateRoots: string[] = [];
runSshCommand.mockImplementation(async (_spec, command) => {
const result = await promisify(execFile)("sh", ["-c", command]);
if (command.includes("mktemp -d")) privateRoots.push(result.stdout.trim());
return result;
});
syncDirectoryToSsh.mockImplementation(async input => { await cp(input!.localDir, input!.remoteDir, { recursive: true }); });
runChildProcess.mockImplementation(async (...args: unknown[]) => {
const argv = args[2] as string[];
if (!argv.includes("--print")) return originalRun(args[0] as string, args[1] as string, argv);
const options = args[3] as { env: Record<string, string>; cwd: string };
const home = options.env.CLAUDE_CONFIG_DIR!;
const transcript = path.join(home, "projects", "fixture-workspace", sessionId + ".jsonl");
calls += 1;
expect(options.cwd).toBe(workspace);
if (calls === 1) {
firstHome = home;
await mkdir(path.dirname(transcript), { recursive: true });
await writeFile(transcript, "fixture prior conversation");
} else if (calls === 2) {
expect(home).toBe(firstHome);
expect(argv).toContain("--resume");
expect(argv).toContain(sessionId);
expect(await readFile(transcript, "utf8")).toBe("fixture prior conversation");
} else {
expect(home).not.toBe(firstHome);
expect(argv).not.toContain("--resume");
await expect(stat(transcript)).rejects.toMatchObject({ code: "ENOENT" });
}
await writeFile(path.join(home, ".credentials.json"), "fixture credential");
await writeFile(path.join(home, "settings.json"), "fixture private config");
if (calls === 2 && fails) throw new Error("fixture Claude follow-up failed");
return { exitCode: 0, signal: null, timedOut: false, stdout: JSON.stringify({ type: "result", subtype: "success", session_id: sessionId, result: "hello" }), stderr: "", pid: 123, startedAt: new Date().toISOString() };
});
const context = {
agent: { id: "agent-1", companyId: "company-1", name: "Selected agent", adapterType: "claude_local", adapterConfig: {} },
context: { paperclipWorkspace: { cwd: workspace, source: "project_primary" } },
executionTarget: { kind: "remote" as const, transport: "ssh" as const, remoteCwd: workspace,
spec: { useHostAuth: false, host: "ssh.example.test", port: 22, username: "agent", remoteWorkspacePath: workspace, remoteCwd: workspace, privateKey: null, knownHosts: null, strictHostKeyChecking: true },
workspaceRealization: { mode: "in_place" as const, authoritativeRoot: workspace, pathAliases: [], outboundRestorePaths: [] } },
onLog: async () => {},
};
const config = (home: string) => ({ engine: "cli", command: "claude", managedAiConnection: { provider: "anthropic", method: "subscription", identity: "selected-account", sessionIdentity: "selected-account-session" },
env: { HOME: home, CLAUDE_CONFIG_DIR: home, CLAUDE_CODE_OAUTH_TOKEN: "fixture-token", ANTHROPIC_API_KEY: "" } });
try {
const first = await execute({ ...context, runId: "first", config: config(homes[0]!), runtime: { sessionId: null, sessionParams: null, sessionDisplayId: null, taskKey: "task" } });
expect(first.sessionId).toBe(sessionId);
expect(await readdir(firstHome)).toEqual(["projects"]);
const saved = sessionCodec.deserialize(JSON.parse(JSON.stringify(sessionCodec.serialize(first.sessionParams!))))!;
await rm(homes[0]!, { recursive: true, force: true });
const next = execute({ ...context, runId: "next", config: config(homes[1]!), runtime: { sessionId, sessionParams: saved, sessionDisplayId: sessionId, taskKey: "task" } });
if (fails) await expect(next).rejects.toThrow("fixture Claude follow-up failed");
else expect((await next).sessionId).toBe(sessionId);
expect(calls).toBe(2);
expect(await readdir(firstHome)).toEqual(["projects"]);
expect((await stat(firstHome)).mode & 0o077).toBe(0);
await expect(stat(homes[0]!)).rejects.toMatchObject({ code: "ENOENT" });
if (!fails) {
const changed = config(homes[1]!);
changed.managedAiConnection.sessionIdentity = "another-account-session";
for (const [runId, nextConfig, sessionParams] of [
["another-account", changed, saved],
["old-params", config(homes[1]!), { sessionId, cwd: workspace, remoteExecution: saved.remoteExecution }],
] as const) {
const result = await execute({ ...context, runId, config: nextConfig, runtime: { sessionId, sessionParams, sessionDisplayId: sessionId, taskKey: "task" } });
expect(result.resultJson).toMatchObject({ sessionReset: { code: "claude_ssh_session_state_unavailable" } });
expect(result.sessionParams?.sshClaudeConversationId).not.toBe(saved.sshClaudeConversationId);
}
expect(calls).toBe(4);
}
for (const dir of privateRoots) await expect(stat(dir)).rejects.toMatchObject({ code: "ENOENT" });
} finally {
runChildProcess.mockReset().mockImplementation(originalRun);
runSshCommand.mockReset().mockImplementation(originalSsh);
syncDirectoryToSsh.mockReset().mockImplementation(originalSync);
}
});
it("uses the agent's subscription in a private SSH home without reading the SSH user's Claude login", async () => {
const rootDir = await mkdtemp(path.join(os.tmpdir(), "paperclip-claude-selected-ssh-"));
cleanupDirs.push(rootDir);
const workspaceDir = path.join(rootDir, "workspace");
const providerHome = path.join(rootDir, "selected-provider");
await mkdir(workspaceDir);await mkdir(providerHome);
const logs: string[] = [];
await execute({
runId: "selected-subscription", agent: { id: "agent-1", companyId: "company-1", name: "Configured agent", adapterType: "claude_local", adapterConfig: {} },
runtime: { sessionId: null, sessionParams: null, sessionDisplayId: null, taskKey: null },
config: { engine: "cli", command: "claude", managedAiConnection: { provider: "anthropic", method: "subscription", identity: "selected-account" },
env: { HOME: rootDir, CLAUDE_CONFIG_DIR: providerHome, CLAUDE_CODE_OAUTH_TOKEN: "selected-agent-token", ANTHROPIC_API_KEY: "" } },
context: { paperclipWorkspace: { cwd: workspaceDir, source: "project_primary" } },
executionTransport: { remoteExecution: { useHostAuth: false, host: "127.0.0.1", port: 2222, username: "fixture", remoteWorkspacePath: "/remote/workspace", remoteCwd: "/remote/workspace", privateKey: null, knownHosts: null, strictHostKeyChecking: false } },
onLog: async (_stream, chunk) => { logs.push(chunk); },
});
expect(syncDirectoryToSsh).toHaveBeenCalledWith(expect.objectContaining({ localDir: providerHome, remoteDir: "/tmp/paperclip-ssh-runtime.claude/config-seed" }));
const providerCall = runChildProcess.mock.calls.find(call => call[2].includes("--print")) as unknown as [string, string, string[], { env: Record<string, string> }];
expect(providerCall[3].env).toMatchObject({ CLAUDE_CODE_OAUTH_TOKEN: "selected-agent-token", CLAUDE_CONFIG_DIR: "/tmp/paperclip-ssh-runtime.claude/config", HOME: "/tmp/paperclip-ssh-runtime.claude", ANTHROPIC_API_KEY: "" });
const materialize = runSshCommand.mock.calls.find(call => call[1].includes("config-seed"));
expect(materialize?.[1]).not.toContain(".claude/\u0024{file}");
expect(runSshCommand).toHaveBeenCalledWith(expect.anything(), "rm -rf -- '/tmp/paperclip-ssh-runtime.claude'", expect.anything());
expect(logs.join("")).not.toContain("selected-agent-token");
});
it("removes the selected account's SSH home when Claude setup fails before launch", async () => {
const root = await mkdtemp(path.join(os.tmpdir(), "paperclip-claude-ssh-failure-"));
cleanupDirs.push(root);
const workspace = path.join(root, "workspace"), home = path.join(root, "selected");
await mkdir(workspace); await mkdir(home);
runSshCommand.mockImplementationOnce(async () => ({ stdout: "/tmp/paperclip-ssh-runtime.failed\n", stderr: "" }))
.mockRejectedValueOnce(new Error("fixture materialization failure"));
await expect(execute({ runId: "failed", agent: { id: "agent-1", companyId: "company-1", name: "Selected", adapterType: "claude_local", adapterConfig: {} },
runtime: { sessionId: null, sessionParams: null, sessionDisplayId: null, taskKey: null },
config: { engine: "cli", command: "claude", managedAiConnection: { provider: "anthropic", identity: "selected" }, env: { CLAUDE_CONFIG_DIR: home, CLAUDE_CODE_OAUTH_TOKEN: "fixture-selected" } },
context: { paperclipWorkspace: { cwd: workspace, source: "project_primary" } },
executionTransport: { remoteExecution: { useHostAuth: false, host: "127.0.0.1", port: 2222, username: "fixture", remoteCwd: "/workspace", remoteWorkspacePath: "/workspace", privateKey: null, knownHosts: null, strictHostKeyChecking: true } }, onLog: async () => {},
})).rejects.toThrow("fixture materialization failure");
expect(runChildProcess).not.toHaveBeenCalled();
expect(runSshCommand).toHaveBeenCalledWith(expect.anything(), "rm -rf -- '/tmp/paperclip-ssh-runtime.failed'", expect.anything());
});
it("prepares the workspace, syncs Claude runtime assets, and restores workspace changes for remote SSH execution", async () => {
vi.stubEnv("CLAUDE_CODE_USE_BEDROCK", "1");
vi.stubEnv("ANTHROPIC_MODEL", "host-only-model");
File diff suppressed because it is too large. Load diff
@@ -65,11 +65,23 @@ export type {
} from "./setup-token-runner.js";
import type { AdapterSessionCodec } from "@paperclipai/adapter-utils";
import { sessionCodec as acpxSessionCodec } from "@paperclipai/adapter-utils/acpx-engine/session-codec";
import { normalizeAdapterExecutionTargetSessionIdentity } from "@paperclipai/adapter-utils/execution-target";
function readNonEmptyString(value: unknown): string | null {
return typeof value === "string" && value.trim().length > 0 ? value.trim() : null;
}
function remoteSessionMetadata(record: Record<string, unknown>): Record<string, unknown> {
const remoteExecution = normalizeAdapterExecutionTargetSessionIdentity(record.remoteExecution);
const conversationId = readNonEmptyString(record.sshClaudeConversationId);
const scope = readNonEmptyString(record.sshClaudeAccountScope);
return {
...(remoteExecution ? { remoteExecution } : {}),
...(conversationId && scope && /^[a-f0-9]{64}$/.test(conversationId) && /^[a-f0-9]{64}$/.test(scope)
? { sshClaudeConversationId: conversationId, sshClaudeAccountScope: scope } : {}),
};
}
export const sessionCodec: AdapterSessionCodec = {
deserialize(raw: unknown) {
if (typeof raw !== "object" || raw === null || Array.isArray(raw)) return null;
@@ -89,6 +101,7 @@ export const sessionCodec: AdapterSessionCodec = {
const repoRef = readNonEmptyString(record.repoRef) ?? readNonEmptyString(record.repo_ref);
return {
sessionId,
...remoteSessionMetadata(record),
...(cwd ? { cwd } : {}),
...(promptBundleKey ? { promptBundleKey } : {}),
...(mcpServerIdentity ? { mcpServerIdentity } : {}),
@@ -114,6 +127,7 @@ export const sessionCodec: AdapterSessionCodec = {
const repoRef = readNonEmptyString(params.repoRef) ?? readNonEmptyString(params.repo_ref);
return {
sessionId,
...remoteSessionMetadata(params),
...(cwd ? { cwd } : {}),
...(promptBundleKey ? { promptBundleKey } : {}),
...(mcpServerIdentity ? { mcpServerIdentity } : {}),
+380 -374
View File
@@ -135,393 +135,399 @@ export async function testEnvironment(
const localProbe = targetIsRemote
? null
: await buildLocalAdapterTestProbeEnv({ callerEnv: env, trustedEnv: process.env });
checks.push(
...(await prepareSandboxClaudeProbeRuntime({
managedAiConnection: Boolean(config.managedAiConnection),
runId,
target,
cwd,
companyId: ctx.companyId,
env,
installCommand: SANDBOX_INSTALL_COMMAND,
detectCommand: command,
targetIsRemote,
targetIsSandbox,
helloProbeTimeoutSec: asNumber(config.helloProbeTimeoutSec, targetIsSandbox ? 90 : 45),
})),
);
const runtimeEnv = ensurePathInEnv({ ...process.env, ...env });
let localRuntimeCommand: string | null = null;
let cleanupManagedProbe: (() => Promise<void>) | undefined;
try {
await ensureAdapterExecutionTargetCommandResolvable(command, target, cwd, runtimeEnv);
if (!targetIsRemote) {
localRuntimeCommand = await resolveAdapterExecutionTargetCommandForLogs(
command,
checks.push(
...(await prepareSandboxClaudeProbeRuntime({
registerCleanup: (cleanup) => { cleanupManagedProbe = cleanup; },
managedAiConnection: Boolean(config.managedAiConnection),
runId,
target,
cwd,
runtimeEnv,
);
}
checks.push({
code: "claude_command_resolvable",
level: "info",
message: `Command is executable: ${command}`,
});
} catch (err) {
checks.push({
code: "claude_command_unresolvable",
...(isAdapterExecutionTargetUnavailableError(err) ? { retryable: true } : {}),
level: "error",
message: err instanceof Error ? err.message : "Command is not executable",
detail: command,
});
}
// When probing a remote target, the Paperclip host's process.env does not
// reflect what the agent will actually see at runtime. Only consider env
// vars from the adapter config in that case; the probe itself will surface
// any auth issues on the remote box.
const considerHostEnv = !targetIsRemote && !config.managedAiConnection;
const hasBedrock =
env.CLAUDE_CODE_USE_BEDROCK === "1" ||
env.CLAUDE_CODE_USE_BEDROCK === "true" ||
(considerHostEnv && process.env.CLAUDE_CODE_USE_BEDROCK === "1") ||
(considerHostEnv && process.env.CLAUDE_CODE_USE_BEDROCK === "true") ||
isNonEmpty(env.ANTHROPIC_BEDROCK_BASE_URL) ||
(considerHostEnv && isNonEmpty(process.env.ANTHROPIC_BEDROCK_BASE_URL));
const configApiKey = env.ANTHROPIC_API_KEY;
const hostApiKey = considerHostEnv ? process.env.ANTHROPIC_API_KEY : undefined;
if (hasBedrock) {
const source =
env.CLAUDE_CODE_USE_BEDROCK === "1" ||
env.CLAUDE_CODE_USE_BEDROCK === "true" ||
isNonEmpty(env.ANTHROPIC_BEDROCK_BASE_URL)
? "adapter config env"
: "server environment";
checks.push({
code: "claude_bedrock_auth",
level: "info",
message: "AWS Bedrock auth detected. Claude will use Bedrock for inference.",
detail: `Detected in ${source}.`,
hint: "Ensure AWS credentials (AWS_ACCESS_KEY_ID/AWS_SECRET_ACCESS_KEY or AWS_PROFILE) and AWS_REGION are configured.",
});
} else if (config.managedAiRouting) {
checks.push({ code: "claude_managed_provider_configured", level: "info", message: "Testing the selected connection’s provider and model." });
} else if (isNonEmpty(configApiKey) || isNonEmpty(hostApiKey)) {
const source = isNonEmpty(configApiKey) ? "adapter config env" : "server environment";
const selectedApiKey = Boolean(config.managedAiConnection) || isNonEmpty(configApiKey);
checks.push({
code: "claude_anthropic_api_key_overrides_subscription",
level: selectedApiKey ? "info" : "warn",
message:
selectedApiKey ? "Using the selected Claude API connection." : "ANTHROPIC_API_KEY is set. Claude will use API-key auth instead of subscription credentials.",
detail: `Detected in ${source}.`,
hint: selectedApiKey ? undefined : "Unset ANTHROPIC_API_KEY if you want subscription-based Claude login behavior.",
});
} else if (
isNonEmpty(env.CLAUDE_CODE_OAUTH_TOKEN) ||
(considerHostEnv && isNonEmpty(process.env.CLAUDE_CODE_OAUTH_TOKEN))
) {
const source = isNonEmpty(env.CLAUDE_CODE_OAUTH_TOKEN)
? "configured environment variables"
: "server environment";
checks.push({
code: "claude_oauth_token_configured",
level: "info",
message:
"CLAUDE_CODE_OAUTH_TOKEN is set. Claude will authenticate with the configured subscription token; no stored login is needed on the execution target.",
detail: `Detected in ${source}.`,
});
} else if (!targetIsRemote) {
checks.push({
code: "claude_subscription_mode_possible",
level: "info",
message: "ANTHROPIC_API_KEY is not set; subscription-based auth can be used if Claude is logged in.",
});
}
const canRunProbe =
checks.every(
(check) =>
check.code !== "claude_cwd_invalid" &&
check.code !== "claude_command_unresolvable" &&
check.code !== "claude_managed_config_dir_failed",
companyId: ctx.companyId,
env,
installCommand: SANDBOX_INSTALL_COMMAND,
detectCommand: command,
targetIsRemote,
targetIsSandbox,
helloProbeTimeoutSec: asNumber(config.helloProbeTimeoutSec, targetIsSandbox ? 90 : 45),
})),
);
let configuredModelIsCompatible = true;
const configuredModel = resolveClaudeModel(config.model, considerHostEnv ? { ...process.env, ...env } : env);
const minimumCliVersion =
claudeCommandLooksLike(command, "claude") &&
(!hasBedrock || isBedrockModelId(configuredModel))
? minimumClaudeCliVersionForModel(configuredModel)
: null;
const versionProbeCommand = localProbe?.command ?? (targetIsRemote ? command : null);
const versionProbeMatchesRuntime = targetIsRemote || localExecutablesMatch(
localProbe?.command ?? null,
localRuntimeCommand,
);
if (
canRunProbe &&
minimumCliVersion &&
versionProbeCommand &&
!versionProbeMatchesRuntime
) {
configuredModelIsCompatible = false;
checks.push({
code: "claude_cli_version_probe_mismatch",
level: "warn",
message:
`Skipped ${configuredModel} readiness probing because the runtime PATH selects a different Claude executable than the trusted local Test probe.`,
hint:
`Ensure the runtime-selected Claude Code is ${minimumCliVersion} or newer. Execution will verify that exact executable before launch.`,
});
} else if (canRunProbe && minimumCliVersion && versionProbeCommand) {
const versionProbeEnv = localProbe?.env ?? env;
const prepared = await prepareCompatibleClaudeCommand({
runId,
command: versionProbeCommand,
target,
cwd,
env: versionProbeEnv,
timeoutSec: 45,
graceSec: 5,
minimumVersion: minimumCliVersion,
});
if (prepared.check) checks.push(prepared.check);
command = prepared.command;
const detectedCliVersion = prepared.version;
if (
!detectedCliVersion ||
!claudeCliVersionAtLeast(detectedCliVersion, minimumCliVersion)
) {
configuredModelIsCompatible = false;
checks.push({
code: "claude_cli_version_incompatible",
level: "error",
message: `${configuredModel} requires Claude Code ${minimumCliVersion} or newer on the CLI lane.`,
detail: detectedCliVersion
? `Detected Claude Code ${detectedCliVersion}.`
: "Could not determine the installed Claude Code version.",
hint: targetIsSandbox && command === "claude"
? "Paperclip could not prepare a compatible Claude runtime. Retry connecting."
: "Upgrade Claude Code or restore the default ACP lane, then retry the Test.",
});
}
}
if (canRunProbe && configuredModelIsCompatible) {
if (!claudeCommandLooksLike(command, "claude")) {
checks.push({
code: "claude_hello_probe_skipped_custom_command",
level: "info",
message: "Skipped hello probe because command is not `claude`.",
detail: command,
hint: "Use the `claude` CLI command to run the automatic login and installation probe.",
});
} else if (localProbe && !localProbe.command) {
// The trusted server PATH holds no `claude`, so the local probe cannot
// run. Report a warn, never a silent pass.
checks.push({
code: "claude_hello_probe_skipped_unresolved_command",
level: "warn",
message: "Skipped the Claude hello probe because `claude` is not installed on the Paperclip host.",
hint: "Install the `claude` CLI on the Paperclip host, then retry the Test.",
});
} else {
const model = configuredModel;
const effort = asString(config.effort, "").trim();
const chrome = asBoolean(config.chrome, false);
const maxTurns = asNumber(config.maxTurnsPerRun, 0);
const dangerouslySkipPermissions = asBoolean(config.dangerouslySkipPermissions, true);
Object.assign(env, claudeSandboxPermissionEnv({ dangerouslySkipPermissions, targetIsSandbox }));
const extraArgs = (() => {
const fromExtraArgs = asStringArray(config.extraArgs);
if (fromExtraArgs.length > 0) return fromExtraArgs;
return asStringArray(config.args);
})();
let effectiveEffort = effort;
if (targetIsSandbox && effort) {
const supportsEffort = await claudeCommandSupportsEffortFlag({
runId,
const runtimeEnv = ensurePathInEnv({ ...process.env, ...env });
let localRuntimeCommand: string | null = null;
try {
await ensureAdapterExecutionTargetCommandResolvable(command, target, cwd, runtimeEnv);
if (!targetIsRemote) {
localRuntimeCommand = await resolveAdapterExecutionTargetCommandForLogs(
command,
target,
cwd,
env,
timeoutSec: 45,
graceSec: 5,
});
if (supportsEffort === false) {
effectiveEffort = "";
checks.push({
code: "claude_effort_flag_unsupported",
level: "warn",
message:
"Claude CLI in the environment does not advertise --effort; the probe omitted the configured reasoning effort.",
hint: "Upgrade the environment CLI/template to a newer Claude Code release to restore reasoning-effort control.",
});
}
runtimeEnv,
);
}
const args = ["--print", "-", "--output-format", "stream-json", "--verbose"];
if (config.managedAiConnection) args.push("--setting-sources", "user");
args.push(...buildClaudeProbePermissionArgs({
dangerouslySkipPermissions,
targetIsRemote,
localProcessUid: process.getuid?.() ?? null,
}));
if (chrome) args.push("--chrome");
// For Bedrock: only pass --model when the ID is a Bedrock-native identifier.
if (model && (!hasBedrock || isBedrockModelId(model))) {
args.push("--model", model);
}
if (effectiveEffort) args.push("--effort", effectiveEffort);
if (maxTurns > 0) args.push("--max-turns", String(maxTurns));
if (extraArgs.length > 0) args.push(...extraArgs);
// Sandbox bridges still add lease warmup and transport overhead, but
// the standard-2 Cloudflare tier now probes fast enough that a 90s
// budget leaves headroom without masking real hangs.
const helloProbeTimeoutSec = Math.max(
1,
asNumber(config.helloProbeTimeoutSec, targetIsSandbox ? 90 : 45),
);
// A local probe uses the trusted resolved executable and the
// deny-by-default child env. A remote probe uses the caller command and
// env, because the remote transport owns its own env sanitization.
const probeCommand = localProbe?.command ?? command;
const probeEnv = localProbe ? localProbe.env : env;
const probe = await runAdapterExecutionTargetProcess(
runId,
target,
probeCommand,
args,
{
cwd,
env: probeEnv,
timeoutSec: helloProbeTimeoutSec,
graceSec: 5,
stdin: "Respond with hello.",
onLog: async () => {},
},
);
const parsedStream = parseClaudeStreamJson(probe.stdout);
const parsed = parsedStream.resultJson;
const loginMeta = detectClaudeLoginRequired({
parsed,
stdout: probe.stdout,
stderr: probe.stderr,
checks.push({
code: "claude_command_resolvable",
level: "info",
message: `Command is executable: ${command}`,
});
} catch (err) {
checks.push({
code: "claude_command_unresolvable",
...(isAdapterExecutionTargetUnavailableError(err) ? { retryable: true } : {}),
level: "error",
message: err instanceof Error ? err.message : "Command is not executable",
detail: command,
});
}
if (probe.timedOut) {
// When probing a remote target, the Paperclip host's process.env does not
// reflect what the agent will actually see at runtime. Only consider env
// vars from the adapter config in that case; the probe itself will surface
// any auth issues on the remote box.
const considerHostEnv = !targetIsRemote && !config.managedAiConnection;
const hasBedrock =
env.CLAUDE_CODE_USE_BEDROCK === "1" ||
env.CLAUDE_CODE_USE_BEDROCK === "true" ||
(considerHostEnv && process.env.CLAUDE_CODE_USE_BEDROCK === "1") ||
(considerHostEnv && process.env.CLAUDE_CODE_USE_BEDROCK === "true") ||
isNonEmpty(env.ANTHROPIC_BEDROCK_BASE_URL) ||
(considerHostEnv && isNonEmpty(process.env.ANTHROPIC_BEDROCK_BASE_URL));
const configApiKey = env.ANTHROPIC_API_KEY;
const hostApiKey = considerHostEnv ? process.env.ANTHROPIC_API_KEY : undefined;
if (hasBedrock) {
const source =
env.CLAUDE_CODE_USE_BEDROCK === "1" ||
env.CLAUDE_CODE_USE_BEDROCK === "true" ||
isNonEmpty(env.ANTHROPIC_BEDROCK_BASE_URL)
? "adapter config env"
: "server environment";
checks.push({
code: "claude_bedrock_auth",
level: "info",
message: "AWS Bedrock auth detected. Claude will use Bedrock for inference.",
detail: `Detected in ${source}.`,
hint: "Ensure AWS credentials (AWS_ACCESS_KEY_ID/AWS_SECRET_ACCESS_KEY or AWS_PROFILE) and AWS_REGION are configured.",
});
} else if (config.managedAiRouting) {
checks.push({ code: "claude_managed_provider_configured", level: "info", message: "Testing the selected connection’s provider and model." });
} else if (isNonEmpty(configApiKey) || isNonEmpty(hostApiKey)) {
const source = isNonEmpty(configApiKey) ? "adapter config env" : "server environment";
const selectedApiKey = Boolean(config.managedAiConnection) || isNonEmpty(configApiKey);
checks.push({
code: "claude_anthropic_api_key_overrides_subscription",
level: selectedApiKey ? "info" : "warn",
message:
selectedApiKey ? "Using the selected Claude API connection." : "ANTHROPIC_API_KEY is set. Claude will use API-key auth instead of subscription credentials.",
detail: `Detected in ${source}.`,
hint: selectedApiKey ? undefined : "Unset ANTHROPIC_API_KEY if you want subscription-based Claude login behavior.",
});
} else if (
isNonEmpty(env.CLAUDE_CODE_OAUTH_TOKEN) ||
(considerHostEnv && isNonEmpty(process.env.CLAUDE_CODE_OAUTH_TOKEN))
) {
const source = isNonEmpty(env.CLAUDE_CODE_OAUTH_TOKEN)
? "configured environment variables"
: "server environment";
checks.push({
code: "claude_oauth_token_configured",
level: "info",
message:
"CLAUDE_CODE_OAUTH_TOKEN is set. Claude will authenticate with the configured subscription token; no stored login is needed on the execution target.",
detail: `Detected in ${source}.`,
});
} else if (!targetIsRemote) {
checks.push({
code: "claude_subscription_mode_possible",
level: "info",
message: "ANTHROPIC_API_KEY is not set; subscription-based auth can be used if Claude is logged in.",
});
}
const canRunProbe =
checks.every(
(check) =>
check.code !== "claude_cwd_invalid" &&
check.code !== "claude_command_unresolvable" &&
check.code !== "claude_managed_config_dir_failed",
);
let configuredModelIsCompatible = true;
const configuredModel = resolveClaudeModel(config.model, considerHostEnv ? { ...process.env, ...env } : env);
const minimumCliVersion =
claudeCommandLooksLike(command, "claude") &&
(!hasBedrock || isBedrockModelId(configuredModel))
? minimumClaudeCliVersionForModel(configuredModel)
: null;
const versionProbeCommand = localProbe?.command ?? (targetIsRemote ? command : null);
const versionProbeMatchesRuntime = targetIsRemote || localExecutablesMatch(
localProbe?.command ?? null,
localRuntimeCommand,
);
if (
canRunProbe &&
minimumCliVersion &&
versionProbeCommand &&
!versionProbeMatchesRuntime
) {
configuredModelIsCompatible = false;
checks.push({
code: "claude_cli_version_probe_mismatch",
level: "warn",
message:
`Skipped ${configuredModel} readiness probing because the runtime PATH selects a different Claude executable than the trusted local Test probe.`,
hint:
`Ensure the runtime-selected Claude Code is ${minimumCliVersion} or newer. Execution will verify that exact executable before launch.`,
});
} else if (canRunProbe && minimumCliVersion && versionProbeCommand) {
const versionProbeEnv = localProbe?.env ?? env;
const prepared = await prepareCompatibleClaudeCommand({
runId,
command: versionProbeCommand,
target,
cwd,
env: versionProbeEnv,
timeoutSec: 45,
graceSec: 5,
minimumVersion: minimumCliVersion,
});
if (prepared.check) checks.push(prepared.check);
command = prepared.command;
const detectedCliVersion = prepared.version;
if (
!detectedCliVersion ||
!claudeCliVersionAtLeast(detectedCliVersion, minimumCliVersion)
) {
configuredModelIsCompatible = false;
checks.push({
code: "claude_hello_probe_timed_out",
level: "warn",
message: "Claude hello probe timed out.",
hint: "Retry the probe. If this persists, verify Claude can run `Respond with hello` from this directory manually.",
code: "claude_cli_version_incompatible",
level: "error",
message: `${configuredModel} requires Claude Code ${minimumCliVersion} or newer on the CLI lane.`,
detail: detectedCliVersion
? `Detected Claude Code ${detectedCliVersion}.`
: "Could not determine the installed Claude Code version.",
hint: targetIsSandbox && command === "claude"
? "Paperclip could not prepare a compatible Claude runtime. Retry connecting."
: "Upgrade Claude Code or restore the default ACP lane, then retry the Test.",
});
} else if (loginMeta.requiresLogin) {
// The raw probe output is untrusted. Log only the fixed context and the
// allowlisted classification. Return only a fixed public message and a
// safe hint.
logSandboxProbeDiagnostic(
"Claude CLI hello probe reported login required",
"auth_required",
);
checks.push({
code: "claude_hello_probe_auth_required",
level: "warn",
message: "Claude CLI is installed, but login is required.",
hint: buildClaudeLoginRequiredHint(loginMeta.loginUrl),
});
if (targetIsSandbox) {
// Emit the neutral canonical check so the user interface can decide
// login eligibility from a stable code. The user interface does not
// read the message text or the top-level status.
checks.push({
code: ADAPTER_AUTH_MISSING_CHECK_CODE,
level: "warn",
message: "This environment has no ready authentication for this adapter.",
hint: "Provide credentials for this adapter, or start login in the environment.",
});
}
} else if ((probe.exitCode ?? 1) === 0) {
const summary = parsedStream.summary.trim();
const hasHello = /\bhello\b/i.test(summary);
if (!hasHello) {
// The unexpected summary is untrusted probe output. Log only the fixed
// context and the allowlisted classification. Keep the check text
// fixed.
logSandboxProbeDiagnostic(
"Claude CLI hello probe returned unexpected output",
"unexpected_output",
);
}
checks.push({
code: hasHello ? "claude_hello_probe_passed" : "claude_hello_probe_unexpected_output",
level: hasHello ? "info" : "warn",
message: hasHello
? "Claude hello probe succeeded."
: "Claude probe ran but did not return `hello` as expected.",
...(hasHello
? {}
: {
hint: "Try the probe manually (`claude --print - --output-format stream-json --verbose`) and prompt `Respond with hello`.",
}),
});
} else {
// The failure diagnostic is untrusted. Log only the fixed context, the
// allowlisted classification, and the safe exit code. Return only a
// fixed public message and hint.
logSandboxProbeDiagnostic("Claude CLI hello probe failed", "nonzero_exit", {
exitCode: probe.exitCode ?? null,
});
// Provider-quota exhaustion (usage/session limit) is classified
// separately from generic transient upstream errors: auth works, the
// subscription's usage window is just spent. Surface it as its own
// warning instead of a hard probe failure.
const usageLimited = isClaudeProviderQuotaError({
parsed,
stdout: probe.stdout,
stderr: probe.stderr,
});
const transient = isClaudeTransientUpstreamError({
parsed,
stdout: probe.stdout,
stderr: probe.stderr,
});
checks.push(
usageLimited
? {
code: "claude_hello_probe_usage_limited",
level: "warn",
message: "Claude hello probe hit the subscription usage limit.",
hint: "Authentication works; the account's usage window is exhausted. Wait for the limit to reset and re-run Test.",
}
: transient
? {
code: "claude_hello_probe_transient_upstream",
level: "warn",
message: "Claude hello probe hit a transient upstream error (rate limit or overload).",
hint: "This is usually temporary. Wait a moment and re-run Test.",
}
: {
code: "claude_hello_probe_failed",
level: "error",
message: "Claude hello probe failed.",
hint: `Exit code ${probe.exitCode ?? "unknown"}. Run \`claude --print - --output-format stream-json --verbose\` manually in this directory and prompt \`Respond with hello\` to debug.`,
},
);
}
}
}
return {
adapterType: ctx.adapterType,
status: summarizeStatus(checks),
checks,
testedAt: new Date().toISOString(),
};
if (canRunProbe && configuredModelIsCompatible) {
if (!claudeCommandLooksLike(command, "claude")) {
checks.push({
code: "claude_hello_probe_skipped_custom_command",
level: "info",
message: "Skipped hello probe because command is not `claude`.",
detail: command,
hint: "Use the `claude` CLI command to run the automatic login and installation probe.",
});
} else if (localProbe && !localProbe.command) {
// The trusted server PATH holds no `claude`, so the local probe cannot
// run. Report a warn, never a silent pass.
checks.push({
code: "claude_hello_probe_skipped_unresolved_command",
level: "warn",
message: "Skipped the Claude hello probe because `claude` is not installed on the Paperclip host.",
hint: "Install the `claude` CLI on the Paperclip host, then retry the Test.",
});
} else {
const model = configuredModel;
const effort = asString(config.effort, "").trim();
const chrome = asBoolean(config.chrome, false);
const maxTurns = asNumber(config.maxTurnsPerRun, 0);
const dangerouslySkipPermissions = asBoolean(config.dangerouslySkipPermissions, true);
Object.assign(env, claudeSandboxPermissionEnv({ dangerouslySkipPermissions, targetIsSandbox }));
const extraArgs = (() => {
const fromExtraArgs = asStringArray(config.extraArgs);
if (fromExtraArgs.length > 0) return fromExtraArgs;
return asStringArray(config.args);
})();
let effectiveEffort = effort;
if (targetIsSandbox && effort) {
const supportsEffort = await claudeCommandSupportsEffortFlag({
runId,
command,
target,
cwd,
env,
timeoutSec: 45,
graceSec: 5,
});
if (supportsEffort === false) {
effectiveEffort = "";
checks.push({
code: "claude_effort_flag_unsupported",
level: "warn",
message:
"Claude CLI in the environment does not advertise --effort; the probe omitted the configured reasoning effort.",
hint: "Upgrade the environment CLI/template to a newer Claude Code release to restore reasoning-effort control.",
});
}
}
const args = ["--print", "-", "--output-format", "stream-json", "--verbose"];
if (config.managedAiConnection) args.push("--setting-sources", "user");
args.push(...buildClaudeProbePermissionArgs({
dangerouslySkipPermissions,
targetIsRemote,
localProcessUid: process.getuid?.() ?? null,
}));
if (chrome) args.push("--chrome");
// For Bedrock: only pass --model when the ID is a Bedrock-native identifier.
if (model && (!hasBedrock || isBedrockModelId(model))) {
args.push("--model", model);
}
if (effectiveEffort) args.push("--effort", effectiveEffort);
if (maxTurns > 0) args.push("--max-turns", String(maxTurns));
if (extraArgs.length > 0) args.push(...extraArgs);
// Sandbox bridges still add lease warmup and transport overhead, but
// the standard-2 Cloudflare tier now probes fast enough that a 90s
// budget leaves headroom without masking real hangs.
const helloProbeTimeoutSec = Math.max(
1,
asNumber(config.helloProbeTimeoutSec, targetIsSandbox ? 90 : 45),
);
// A local probe uses the trusted resolved executable and the
// deny-by-default child env. A remote probe uses the caller command and
// env, because the remote transport owns its own env sanitization.
const probeCommand = localProbe?.command ?? command;
const probeEnv = localProbe ? localProbe.env : env;
const probe = await runAdapterExecutionTargetProcess(
runId,
target,
probeCommand,
args,
{
cwd,
env: probeEnv,
timeoutSec: helloProbeTimeoutSec,
graceSec: 5,
stdin: "Respond with hello.",
onLog: async () => {},
},
);
const parsedStream = parseClaudeStreamJson(probe.stdout);
const parsed = parsedStream.resultJson;
const loginMeta = detectClaudeLoginRequired({
parsed,
stdout: probe.stdout,
stderr: probe.stderr,
});
if (probe.timedOut) {
checks.push({
code: "claude_hello_probe_timed_out",
level: "warn",
message: "Claude hello probe timed out.",
hint: "Retry the probe. If this persists, verify Claude can run `Respond with hello` from this directory manually.",
});
} else if (loginMeta.requiresLogin) {
// The raw probe output is untrusted. Log only the fixed context and the
// allowlisted classification. Return only a fixed public message and a
// safe hint.
logSandboxProbeDiagnostic(
"Claude CLI hello probe reported login required",
"auth_required",
);
checks.push({
code: "claude_hello_probe_auth_required",
level: "warn",
message: "Claude CLI is installed, but login is required.",
hint: buildClaudeLoginRequiredHint(loginMeta.loginUrl),
});
if (targetIsSandbox) {
// Emit the neutral canonical check so the user interface can decide
// login eligibility from a stable code. The user interface does not
// read the message text or the top-level status.
checks.push({
code: ADAPTER_AUTH_MISSING_CHECK_CODE,
level: "warn",
message: "This environment has no ready authentication for this adapter.",
hint: "Provide credentials for this adapter, or start login in the environment.",
});
}
} else if ((probe.exitCode ?? 1) === 0) {
const summary = parsedStream.summary.trim();
const hasHello = /\bhello\b/i.test(summary);
if (!hasHello) {
// The unexpected summary is untrusted probe output. Log only the fixed
// context and the allowlisted classification. Keep the check text
// fixed.
logSandboxProbeDiagnostic(
"Claude CLI hello probe returned unexpected output",
"unexpected_output",
);
}
checks.push({
code: hasHello ? "claude_hello_probe_passed" : "claude_hello_probe_unexpected_output",
level: hasHello ? "info" : "warn",
message: hasHello
? "Claude hello probe succeeded."
: "Claude probe ran but did not return `hello` as expected.",
...(hasHello
? {}
: {
hint: "Try the probe manually (`claude --print - --output-format stream-json --verbose`) and prompt `Respond with hello`.",
}),
});
} else {
// The failure diagnostic is untrusted. Log only the fixed context, the
// allowlisted classification, and the safe exit code. Return only a
// fixed public message and hint.
logSandboxProbeDiagnostic("Claude CLI hello probe failed", "nonzero_exit", {
exitCode: probe.exitCode ?? null,
});
// Provider-quota exhaustion (usage/session limit) is classified
// separately from generic transient upstream errors: auth works, the
// subscription's usage window is just spent. Surface it as its own
// warning instead of a hard probe failure.
const usageLimited = isClaudeProviderQuotaError({
parsed,
stdout: probe.stdout,
stderr: probe.stderr,
});
const transient = isClaudeTransientUpstreamError({
parsed,
stdout: probe.stdout,
stderr: probe.stderr,
});
checks.push(
usageLimited
? {
code: "claude_hello_probe_usage_limited",
level: "warn",
message: "Claude hello probe hit the subscription usage limit.",
hint: "Authentication works; the account's usage window is exhausted. Wait for the limit to reset and re-run Test.",
}
: transient
? {
code: "claude_hello_probe_transient_upstream",
level: "warn",
message: "Claude hello probe hit a transient upstream error (rate limit or overload).",
hint: "This is usually temporary. Wait a moment and re-run Test.",
}
: {
code: "claude_hello_probe_failed",
level: "error",
message: "Claude hello probe failed.",
hint: `Exit code ${probe.exitCode ?? "unknown"}. Run \`claude --print - --output-format stream-json --verbose\` manually in this directory and prompt \`Respond with hello\` to debug.`,
},
);
}
}
}
return {
adapterType: ctx.adapterType,
status: summarizeStatus(checks),
checks,
testedAt: new Date().toISOString(),
};
} finally {
await cleanupManagedProbe?.();
}
}
@@ -87,6 +87,7 @@ const originalPaperclipHome = process.env.PAPERCLIP_HOME;
const originalPaperclipInstanceId = process.env.PAPERCLIP_INSTANCE_ID;
const originalCodexHome = process.env.CODEX_HOME;
const originalOpenAiApiKey = process.env.OPENAI_API_KEY;
const originalCodexApiKey = process.env.CODEX_API_KEY;
// Older/newer ISO timestamps for the copy-back monotonic (strictly-newer)
// decision predicate, plus a subscription-shaped auth.json fixture matching the
@@ -139,6 +140,8 @@ afterEach(async () => {
else process.env.CODEX_HOME = originalCodexHome;
if (originalOpenAiApiKey === undefined) delete process.env.OPENAI_API_KEY;
else process.env.OPENAI_API_KEY = originalOpenAiApiKey;
if (originalCodexApiKey === undefined) delete process.env.CODEX_API_KEY;
else process.env.CODEX_API_KEY = originalCodexApiKey;
await Promise.all(tempRoots.splice(0).map((root) => fs.rm(root, { recursive: true, force: true })));
});
@@ -437,7 +440,7 @@ describe("codex_local ACP lane", () => {
});
});
it("reports unavailable ACP for non-sandbox remote auto runs", async () => {
it("reports unavailable ACP for SSH host authentication", async () => {
setNodeVersion("v24.11.0");
await expect(
resolveCodexExecutionEngineForRun({
@@ -461,7 +464,7 @@ describe("codex_local ACP lane", () => {
).resolves.toMatchObject({
engine: "acp",
explicit: false,
unavailableReason: expect.stringContaining("sandbox remote targets only"),
unavailableReason: expect.stringContaining("agent-managed SSH account"),
});
});
@@ -1233,6 +1236,54 @@ describe("codex_local ACP lane", () => {
await Promise.all(stagedDirs.map((dir) => fs.rm(dir, { recursive: true, force: true })));
});
it.each(["none", "OPENAI_API_KEY", "CODEX_API_KEY"])("copies selected subscription refreshes to the current home with controller key %s", async controllerKey => {
const root = await makeTempRoot("paperclip-codex-acp-rebind-");
const localCwd = path.join(root, "workspace");
const remoteCwd = path.join(root, "remote");
const firstHome = path.join(root, "first-account-home");
const nextHome = path.join(root, "next-account-home");
for (const dir of [localCwd, remoteCwd, firstHome, nextHome]) await fs.mkdir(dir);
const originalAuth = subscriptionAuthJson("acct-same", OLDER_REFRESH, "original");
for (const home of [firstHome, nextHome]) await fs.writeFile(path.join(home, "auth.json"), originalAuth, { mode: 0o600 });
process.env.OPENAI_API_KEY = "";
process.env.CODEX_API_KEY = "";
if (controllerKey !== "none") process.env[controllerKey] = "fixture-unselected-controller-key";
const stagedRuntimes = new Map();
const execute = createCodexAcpExecutor({
createRuntime: options => new FakeRuntime(options) as never,
stagedRuntimes, stagingLocks: new Map(),
});
const result = await execute(buildContext(localCwd, {
runId: `run-rebind-home-${randomUUID()}`,
config: {
engine: "acp", cwd: localCwd, agentCommand: "node ./fake-acp.js", stateDir: path.join(root, "state"),
managedAiConnection: { identity: "selected-account", sessionIdentity: "selected-account-session" },
env: { CODEX_HOME: firstHome, OPENAI_API_KEY: "", CODEX_API_KEY: "" }, promptTemplate: "Do the assigned work.",
},
context: { issueId: "issue-1", paperclipWorkspace: { cwd: localCwd, source: "project_workspace", workspaceId: "workspace-1" } },
executionTarget: { kind: "remote", transport: "sandbox", providerKey: "fake-plugin", remoteCwd, runner: createLocalSandboxRunner() } as never,
authToken: "fixture-run-jwt",
}));
expect(result.exitCode).toBe(0);
expect(stagedRuntimes.size).toBe(1);
const entry = [...stagedRuntimes.values()][0]!;
try {
await fs.rm(firstHome, { recursive: true });
const currentLogs: string[] = [];
await entry.rebindRun({ env: { CODEX_HOME: nextHome }, onLog: async (_stream: string, chunk: string) => { currentLogs.push(chunk); } });
await fs.writeFile(path.join(entry.stagedRuntime.assetDirs.home, "auth.json"), subscriptionAuthJson("acct-same", NEWER_REFRESH, "refreshed"));
expect(await entry.teardown()).toMatchObject({ ok: true });
const auth = JSON.parse(await fs.readFile(path.join(nextHome, "auth.json"), "utf8"));
expect(auth.tokens.refresh_token).toBe("ref-refreshed");
expect(auth.last_refresh).toBe(NEWER_REFRESH);
expect((await fs.stat(path.join(nextHome, "auth.json"))).mode & 0o777).toBe(0o600);
await expect(fs.stat(firstHome)).rejects.toMatchObject({ code: "ENOENT" });
expect(currentLogs.some(line => line.includes("Codex auth"))).toBe(true);
} finally {
await entry.dispose();
}
});
it("removes the host staged Codex home when a failed turn drops the staged runtime", async () => {
// The complementary guardrail: when the staged runtime IS dropped (here, a
// failed turn), the one-time `disposeStaged` fires and removes the host
@@ -183,7 +183,9 @@ async function prepareCodexRemoteManagedHome(
): Promise<AcpxRemoteManagedHomeResult> {
const { env, runId, onLog } = input;
// The host managed Codex home the engine seeded and set on env.CODEX_HOME.
const effectiveCodexHome = env.CODEX_HOME;
let effectiveCodexHome = env.CODEX_HOME;
let currentLog = onLog;
const copybackLog: typeof onLog = (stream, chunk) => currentLog(stream, chunk);
if (!effectiveCodexHome) {
// No managed home resolved (e.g. custom CODEX_HOME cleared) — stage the
// workspace with no home asset, identical to the no-seam fallback.
@@ -193,7 +195,7 @@ async function prepareCodexRemoteManagedHome(
// sandbox auth out of the shared subscription copy-back path altogether.
const apiKeyAuth = Boolean(
env.OPENAI_API_KEY?.trim() || env.CODEX_API_KEY?.trim()
|| process.env.OPENAI_API_KEY?.trim() || process.env.CODEX_API_KEY?.trim(),
|| (!input.config.managedAiConnection && (process.env.OPENAI_API_KEY?.trim() || process.env.CODEX_API_KEY?.trim())),
);
// Curated allowlist temp dir (auth/config/skills only); caller owns cleanup.
const stagedCodexHomeDir = await stageCodexHomeForSync(effectiveCodexHome, { runId });
@@ -214,7 +216,7 @@ async function prepareCodexRemoteManagedHome(
void (await copyBackCodexAuth({
readSandboxAuth: () => readFile(path.posix.join(assetDir, "auth.json")),
hostAuthPath: path.join(input.config.managedAiConnection ? effectiveCodexHome : resolveSharedCodexHomeDir(process.env), "auth.json"),
log: (line) => onLog("stdout", `${line}\n`),
log: (line) => copybackLog("stdout", `${line}\n`),
})),
},
]);
@@ -229,6 +231,13 @@ async function prepareCodexRemoteManagedHome(
return {
stagedRuntime,
rebindRun: binding => {
if (input.config.managedAiConnection) {
if (!binding.env.CODEX_HOME) throw new Error("Managed Codex copyback requires the current account home");
effectiveCodexHome = binding.env.CODEX_HOME;
}
currentLog = binding.onLog;
},
// Subscription copy-back fires on EVERY run's teardown (including a compatible
// resume that reuses this staged runtime). It reads the sandbox auth.json /
// workspace live and copies back to the host; it does NOT remove the staged
@@ -242,7 +251,7 @@ async function prepareCodexRemoteManagedHome(
// mask the run result.
teardown: createWorkspaceRestoreTeardown({
stagedRuntime,
onLog,
onLog: copybackLog,
startMessage: apiKeyAuth
? "[paperclip] Restoring workspace changes from the sandbox.\n"
: "[paperclip] Restoring workspace changes and Codex auth from the sandbox.\n",
@@ -454,7 +463,7 @@ async function commandIsResolvable(
trimmed,
target,
resolveAdapterExecutionTargetCwd(target, asString(input?.config.cwd, ""), process.cwd()),
process.env,
target.transport === "ssh" ? { PATH: process.env.PATH } : process.env,
);
return true;
} catch {
@@ -498,11 +507,16 @@ async function codexAcpUnavailableReason(
executionTarget: input.executionTarget,
legacyRemoteExecution: input.executionTransport?.remoteExecution,
});
if (target?.kind === "remote" && !sandboxTargetHasProcessSessionBridge(target)) {
const managedSsh = target?.kind === "remote" && target.transport === "ssh"
&& target.spec.useHostAuth === false && Boolean(input.config.managedAiConnection);
if (managedSsh && target.workspaceRealization?.mode === "in_place") {
return "In-place SSH workspace realization requires the Codex CLI engine; ACP archive staging is not supported.";
}
if (target?.kind === "remote" && !sandboxTargetHasProcessSessionBridge(target) && !managedSsh) {
if (target.transport === "sandbox") {
return "Codex ACP requires a bidirectional remote process target; this sandbox exposes only one-shot command execution.";
}
return "Codex ACP supports sandbox remote targets only; this run targets a non-sandbox remote environment.";
return "Codex ACP requires an agent-managed SSH account; host authentication is supported by the CLI engine.";
}
if (!nodeVersionMeetsCodexAcpMinimum()) {
return `Node ${process.version} (${process.execPath}) does not satisfy Codex ACP's Node >=${MIN_ACP_NODE_VERSION} prerequisite.`;
@@ -1,10 +1,13 @@
import { mkdir, mkdtemp, readdir, readFile, rm, symlink, writeFile } from "node:fs/promises";
import { cp, mkdir, mkdtemp, readdir, readFile, rm, stat, symlink, writeFile } from "node:fs/promises";
import { execFile } from "node:child_process";
import { promisify } from "node:util";
import os from "node:os";
import path from "node:path";
import { afterEach, describe, expect, it, vi } from "vitest";
const {
runChildProcess,
executeAcp,
ensureCommandResolvable,
resolveCommandForLogs,
prepareWorkspaceForSshExecution,
@@ -13,6 +16,7 @@ const {
syncDirectoryToSsh,
startAdapterExecutionTargetPaperclipBridge,
} = vi.hoisted(() => ({
executeAcp: vi.fn(async (_ctx?: unknown) => ({ exitCode: 0, signal: null, timedOut: false, resultJson: { engine: "acp" } })),
runChildProcess: vi.fn(async () => ({
exitCode: 1,
signal: null,
@@ -22,12 +26,12 @@ const {
pid: 123,
startedAt: new Date().toISOString(),
})),
ensureCommandResolvable: vi.fn(async () => undefined),
ensureCommandResolvable: vi.fn<typeof import("@paperclipai/adapter-utils/server-utils").ensureCommandResolvable>(async () => undefined),
resolveCommandForLogs: vi.fn(async () => "/usr/bin/codex"),
prepareWorkspaceForSshExecution: vi.fn(async () => ({ gitBacked: false })),
restoreWorkspaceFromSshExecution: vi.fn(async () => undefined),
runSshCommand: vi.fn(async () => ({ stdout: Buffer.from("{}").toString("base64"), stderr: "" })),
syncDirectoryToSsh: vi.fn(async () => undefined),
runSshCommand: vi.fn(async (_spec?: unknown, _command?: string) => ({ stdout: Buffer.from("{}").toString("base64"), stderr: "" })),
syncDirectoryToSsh: vi.fn(async (_input?: { localDir: string; remoteDir: string }) => undefined),
startAdapterExecutionTargetPaperclipBridge: vi.fn(async () => ({
env: {
PAPERCLIP_API_URL: "http://127.0.0.1:4310",
@@ -38,6 +42,11 @@ const {
})),
}));
vi.mock("./acp.js", async (importOriginal) => {
const actual = await importOriginal<typeof import("./acp.js")>();
return { ...actual, createCodexAcpExecutor: () => executeAcp };
});
vi.mock("@paperclipai/adapter-utils/server-utils", async () => {
const actual = await vi.importActual<typeof import("@paperclipai/adapter-utils/server-utils")>(
"@paperclipai/adapter-utils/server-utils",
@@ -75,6 +84,7 @@ vi.mock("@paperclipai/adapter-utils/execution-target", async () => {
import { createPromptContextFixture } from "@paperclipai/adapter-utils/test-fixtures/prompt-context";
import { execute } from "./execute.js";
import { sessionCodec } from "./index.js";
describe("codex remote execution", () => {
const cleanupDirs: string[] = [];
@@ -88,6 +98,208 @@ describe("codex remote execution", () => {
}
});
function managedSshAcpContext(engine?: string) {
return {
runId: "managed-ssh-acp", agent: { id: "agent-1", companyId: "company-1", name: "Selected agent", adapterType: "codex_local", adapterConfig: {} },
runtime: { sessionId: null, sessionParams: null, sessionDisplayId: null, taskKey: "task" },
config: { engine, managedAiConnection: { provider: "openai", method: "subscription", identity: "selected-account" },
env: { OPENAI_API_KEY: "fixture-selected-token" } } as Record<string, unknown>,
context: {}, onLog: async () => {},
executionTarget: { kind: "remote" as const, transport: "ssh" as const, remoteCwd: "/remote/workspace",
spec: { useHostAuth: false as boolean | undefined, host: "ssh.example.test", port: 22, username: "agent", remoteCwd: "/remote/workspace", remoteWorkspacePath: "/remote/workspace", privateKey: null, knownHosts: null, strictHostKeyChecking: true },
workspaceRealization: { mode: "copy" as "copy" | "in_place", authoritativeRoot: "/remote/workspace", pathAliases: [], outboundRestorePaths: [] } },
};
}
it.each([undefined, "acp"])("admits managed SSH ACP through the public execution entry (engine=%s)", async engine => {
const ctx = managedSshAcpContext(engine);
const actual = await vi.importActual<typeof import("@paperclipai/adapter-utils/server-utils")>("@paperclipai/adapter-utils/server-utils");
const bin = await mkdtemp(path.join(os.tmpdir(), "paperclip-ssh-client-probe-"));
cleanupDirs.push(bin);
await writeFile(path.join(bin, "ssh"), "#!/bin/sh\nexit 0\n", { mode: 0o700 });
const originalResolve = ensureCommandResolvable.getMockImplementation()!;
ensureCommandResolvable.mockImplementationOnce(actual.ensureCommandResolvable);
const previousPath = process.env.PATH;
process.env.PATH = bin;
const previous = process.env.OPENAI_API_KEY;
process.env.OPENAI_API_KEY = "fixture-server-secret";
try {
expect(await execute(ctx)).toMatchObject({ exitCode: 0, resultJson: { engine: "acp" } });
expect(executeAcp).toHaveBeenCalledWith(ctx);
const probe = ensureCommandResolvable.mock.calls[0] as unknown as unknown[];
expect(probe[0]).toBe("codex-acp");
expect(Object.keys(probe[2] as Record<string, unknown>)).toEqual(["PATH"]);
expect((probe[2] as Record<string, unknown>).PATH === bin).toBe(true);
expect(probe[3]).toMatchObject({ remoteExecution: { host: "ssh.example.test", useHostAuth: false } });
} finally {
ensureCommandResolvable.mockReset().mockImplementation(originalResolve);
if (previousPath === undefined) delete process.env.PATH;
else process.env.PATH = previousPath;
if (previous === undefined) delete process.env.OPENAI_API_KEY;
else process.env.OPENAI_API_KEY = previous;
}
});
it.each(["host auth", "legacy auth", "missing account", "in-place", "confinement", "missing SSH client"])("rejects unsupported SSH ACP at the public execution entry: %s", async reason => {
const ctx = managedSshAcpContext("acp");
const originalResolve = ensureCommandResolvable.getMockImplementation()!;
if (reason === "host auth") ctx.executionTarget.spec.useHostAuth = true;
if (reason === "legacy auth") ctx.executionTarget.spec.useHostAuth = undefined;
if (reason === "missing account") delete ctx.config.managedAiConnection;
if (reason === "in-place") ctx.executionTarget.workspaceRealization.mode = "in_place";
if (reason === "confinement") ctx.config.filesystemScope = "workspace";
const previousPath = process.env.PATH;
if (reason === "missing SSH client") {
const bin = await mkdtemp(path.join(os.tmpdir(), "paperclip-no-ssh-client-"));
cleanupDirs.push(bin);
process.env.PATH = bin;
const actual = await vi.importActual<typeof import("@paperclipai/adapter-utils/server-utils")>("@paperclipai/adapter-utils/server-utils");
ensureCommandResolvable.mockImplementationOnce(actual.ensureCommandResolvable);
}
try {
expect(await execute(ctx)).toMatchObject({ exitCode: 1, errorCode: "adapter_engine_unavailable" });
expect(executeAcp).not.toHaveBeenCalled();
} finally {
ensureCommandResolvable.mockReset().mockImplementation(originalResolve);
if (previousPath === undefined) delete process.env.PATH;
else process.env.PATH = previousPath;
}
});
it.each([false, true])("retains a managed SSH Codex conversation across turns and removes credentials (second turn throws=%s)", async fails => {
const root = await mkdtemp(path.join(os.tmpdir(), "paperclip-codex-ssh-resume-"));
cleanupDirs.push(root);
const workspace = path.join(root, "workspace"), home = path.join(root, "account"), secondHome = path.join(root, "next-invocation");
await mkdir(workspace); await mkdir(home); await mkdir(secondHome);
const auth = (account: string, marker: string, last_refresh: string) => JSON.stringify({ tokens: {
account_id: account, access_token: `fixture-access-${marker}`, refresh_token: `fixture-refresh-${marker}`, id_token: `fixture-id-${marker}`,
}, last_refresh });
const credential = auth("selected", "before", "2000-01-01T00:00:00Z");
const refreshed = auth("selected", "after", new Date().toISOString());
const otherCredential = auth("other", "other", "2000-01-01T00:00:00Z");
await writeFile(path.join(home, "auth.json"), credential);
await writeFile(path.join(secondHome, "auth.json"), credential);
const executeShell = promisify(execFile);
const originalRun = runChildProcess.getMockImplementation()!;
let firstRemoteHome: string | undefined;
let otherRemoteHome: string | undefined;
const privateRoots: string[] = [];
let calls = 0;
runSshCommand.mockImplementation(async (_spec, command) => {
const result = await executeShell("sh", ["-c", command!]);
if (command!.includes("mktemp -d")) privateRoots.push(result.stdout.trim());
return result;
});
syncDirectoryToSsh.mockImplementation(async input => { await cp(input!.localDir, input!.remoteDir, { recursive: true }); });
runChildProcess.mockImplementation(async (...args: unknown[]) => {
const env = (args[3] as { env: Record<string, string> }).env;
const remoteHome = env.CODEX_HOME!;
calls++;
expect(await readFile(path.join(remoteHome, "auth.json"), "utf8")).toBe(calls === 1 ? credential : calls === 2 ? refreshed : otherCredential);
if (calls === 1) {
firstRemoteHome = remoteHome;
await mkdir(path.join(remoteHome, "sessions"));
await writeFile(path.join(remoteHome, "sessions", "rollout.jsonl"), "fixture conversation");
await writeFile(path.join(remoteHome, "state_5.sqlite"), "fixture native index");
await writeFile(path.join(remoteHome, "auth.json"), refreshed);
} else if (calls === 2) {
expect(remoteHome).toBe(firstRemoteHome);
expect(args[2]).toContain("resume");
expect(args[2]).toContain("ssh-thread");
expect(await readFile(path.join(remoteHome, "sessions", "rollout.jsonl"), "utf8")).toBe("fixture conversation");
expect(await readFile(path.join(remoteHome, "state_5.sqlite"), "utf8")).toBe("fixture native index");
if (fails) throw new Error("fixture provider failed");
} else {
if (calls === 3) otherRemoteHome = remoteHome;
expect(remoteHome).not.toBe(firstRemoteHome);
expect(args[2]).not.toContain("resume");
await expect(readFile(path.join(remoteHome, "sessions", "rollout.jsonl"))).rejects.toThrow("ENOENT");
if (calls === 3) {
await mkdir(path.join(remoteHome, "sessions"));
await writeFile(path.join(remoteHome, "sessions", "rollout.jsonl"), "other conversation");
}
}
return { exitCode: 0, signal: null, timedOut: false, stdout: JSON.stringify({ type: "thread.started", thread_id: calls < 3 ? "ssh-thread" : "other-thread" })+'\n{"type":"turn.completed","usage":{"input_tokens":1,"output_tokens":1}}\n', stderr: "", pid: 123, startedAt: new Date().toISOString() };
});
const ctx = {
agent: { id: "agent-1", companyId: "company-1", name: "Selected agent", adapterType: "codex_local", adapterConfig: {} },
config: { engine: "cli", command: "codex", managedAiConnection: { identity: "generation-one", sessionIdentity: "selected-account", provider: "openai", method: "subscription" }, env: { CODEX_HOME: home, OPENAI_API_KEY: "" } },
context: { paperclipWorkspace: { cwd: workspace, source: "project_primary" } },
executionTarget: { kind: "remote" as const, transport: "ssh" as const, remoteCwd: workspace,
spec: { useHostAuth: false, host: "127.0.0.1", port: 2222, username: "fixture", remoteCwd: workspace, remoteWorkspacePath: workspace, privateKey: null, knownHosts: null, strictHostKeyChecking: true },
workspaceRealization: { mode: "in_place" as const, authoritativeRoot: workspace, pathAliases: [], outboundRestorePaths: [] } }, onLog: async () => {},
};
try {
const first = await execute({ ...ctx, runId: "first", runtime: { sessionId: null, sessionParams: null, sessionDisplayId: null, taskKey: "task-one" } });
expect(first.sessionId).toBe("ssh-thread");
const saved = sessionCodec.deserialize(JSON.parse(JSON.stringify(sessionCodec.serialize(first.sessionParams!))))!;
expect(saved).toMatchObject({ remoteExecution: first.sessionParams!.remoteExecution,
sshCodexConversationId: first.sessionParams!.sshCodexConversationId, sshCodexAccountScope: first.sessionParams!.sshCodexAccountScope });
expect(await readFile(path.join(home, "auth.json"), "utf8")).toBe(refreshed);
await writeFile(path.join(secondHome, "auth.json"), refreshed);
expect(await readdir(firstRemoteHome!)).toEqual(expect.arrayContaining(["sessions", "state_5.sqlite"]));
expect(await readdir(firstRemoteHome!)).not.toContain("auth.json");
const second = execute({ ...ctx, runId: "second", config: { ...ctx.config,
managedAiConnection: { ...ctx.config.managedAiConnection, identity: "generation-two" }, env: { CODEX_HOME: secondHome, OPENAI_API_KEY: "" } },
runtime: { sessionId: first.sessionId!, sessionParams: saved, sessionDisplayId: first.sessionId!, taskKey: "task-one" } });
if (fails) await expect(second).rejects.toThrow("fixture provider failed");
else expect((await second).sessionId).toBe("ssh-thread");
expect(calls).toBe(2);
expect((await readdir(firstRemoteHome!)).sort()).toEqual(["sessions", "state_5.sqlite"]);
expect((await stat(firstRemoteHome!)).mode & 0o077).toBe(0);
if (!fails) {
await writeFile(path.join(secondHome, "auth.json"), otherCredential);
const switched = await execute({ ...ctx, runId: "other-account", config: { ...ctx.config,
managedAiConnection: { ...ctx.config.managedAiConnection, identity: "other-account", sessionIdentity: "other-account" }, env: { CODEX_HOME: secondHome, OPENAI_API_KEY: "" } },
runtime: { sessionId: first.sessionId!, sessionParams: first.sessionParams!, sessionDisplayId: first.sessionId!, taskKey: "task-one" } });
expect(switched.sessionId).toBe("other-thread");
expect(switched.sessionParams?.sshCodexAccountScope).not.toBe(first.sessionParams?.sshCodexAccountScope);
expect(switched.resultJson).toMatchObject({ sessionReset: { code: "codex_ssh_session_state_unavailable" } });
expect(await readdir(otherRemoteHome!)).not.toContain("auth.json");
expect(await readFile(path.join(firstRemoteHome!, "sessions", "rollout.jsonl"), "utf8")).toBe("fixture conversation");
const oldShape = { sessionId: switched.sessionId!, cwd: workspace, remoteExecution: switched.sessionParams!.remoteExecution };
const legacy = await execute({ ...ctx, runId: "old-saved-shape", config: { ...ctx.config,
managedAiConnection: { ...ctx.config.managedAiConnection, identity: "other-account", sessionIdentity: "other-account" }, env: { CODEX_HOME: secondHome, OPENAI_API_KEY: "" } },
runtime: { sessionId: switched.sessionId!, sessionParams: oldShape, sessionDisplayId: switched.sessionId!, taskKey: "task-one" } });
expect(legacy.resultJson).toMatchObject({ sessionReset: { code: "codex_ssh_session_state_unavailable" } });
expect(await readFile(path.join(otherRemoteHome!, "sessions", "rollout.jsonl"), "utf8")).toBe("other conversation");
}
for (const dir of privateRoots) await expect(stat(dir)).rejects.toThrow("ENOENT");
} finally {
runChildProcess.mockImplementation(originalRun);
runSshCommand.mockReset().mockResolvedValue({ stdout: Buffer.from("{}").toString("base64"), stderr: "" });
syncDirectoryToSsh.mockReset().mockResolvedValue(undefined);
}
});
it("stages only the selected agent subscription and returns SSH refreshes to that account", async () => {
const root = await mkdtemp(path.join(os.tmpdir(), "paperclip-codex-selected-ssh-"));
cleanupDirs.push(root);
const workspace = path.join(root, "workspace"), home = path.join(root, "selected-account");
await mkdir(workspace); await mkdir(home);
const auth = (marker: string, last_refresh: string) => JSON.stringify({
tokens: { account_id: "selected-account", access_token: `fixture-access-${marker}`, refresh_token: `fixture-refresh-${marker}`, id_token: `fixture-id-${marker}` }, last_refresh,
});
await writeFile(path.join(home, "auth.json"), auth("before", "2000-01-01T00:00:00Z"), { mode: 0o600 });
const refreshed = auth("after", new Date().toISOString());
runSshCommand.mockImplementation(async (_spec, command) => ({ stdout: command?.includes("mktemp -d")
? "/tmp/paperclip-ssh-runtime.selected\n" : Buffer.from(refreshed).toString("base64"), stderr: "" }));
try {
await execute({ runId: "selected", agent: { id: "agent-1", companyId: "company-1", name: "Selected agent", adapterType: "codex_local", adapterConfig: {} },
runtime: { sessionId: null, sessionParams: null, sessionDisplayId: null, taskKey: null },
config: { engine: "cli", command: "codex", managedAiConnection: { identity: "selected-account", provider: "openai", method: "subscription" }, env: { CODEX_HOME: home, OPENAI_API_KEY: "" } },
context: { paperclipWorkspace: { cwd: workspace, source: "project_primary" } },
executionTransport: { remoteExecution: { useHostAuth: false, host: "127.0.0.1", port: 2222, username: "fixture", remoteCwd: "/workspace", remoteWorkspacePath: "/workspace", privateKey: null, knownHosts: null, strictHostKeyChecking: true } }, onLog: async () => {},
});
const invocation = runChildProcess.mock.calls[0] as unknown as [string, string, string[], { env: Record<string, string> }];
expect(invocation[3].env).toMatchObject({ CODEX_HOME: "/tmp/paperclip-ssh-runtime.selected/home", HOME: "/tmp/paperclip-ssh-runtime.selected", OPENAI_API_KEY: "" });
expect(await readFile(path.join(home, "auth.json"), "utf8")).toBe(refreshed);
expect(runSshCommand).toHaveBeenCalledWith(expect.anything(), "rm -rf -- '/tmp/paperclip-ssh-runtime.selected'", expect.anything());
} finally {
runSshCommand.mockReset().mockResolvedValue({ stdout: Buffer.from("{}").toString("base64"), stderr: "" });
}
});
it("prepares the workspace, syncs CODEX_HOME, and restores workspace changes for remote SSH execution", async () => {
const rootDir = await mkdtemp(path.join(os.tmpdir(), "paperclip-codex-remote-"));
cleanupDirs.push(rootDir);
@@ -0,0 +1,219 @@
import { cp, mkdir, mkdtemp, readdir, readFile, rm, stat, symlink, writeFile } from "node:fs/promises";
import { execFile } from "node:child_process";
import { promisify } from "node:util";
import os from "node:os";
import path from "node:path";
import { afterEach, describe, expect, it, vi } from "vitest";
const {
runChildProcess,
ensureCommandResolvable,
resolveCommandForLogs,
prepareWorkspaceForSshExecution,
restoreWorkspaceFromSshExecution,
runSshCommand,
syncDirectoryToSsh,
startAdapterExecutionTargetPaperclipBridge,
} = vi.hoisted(() => ({
runChildProcess: vi.fn(async () => ({
exitCode: 1,
signal: null,
timedOut: false,
stdout: "",
stderr: "remote failure",
pid: 123,
startedAt: new Date().toISOString(),
})),
ensureCommandResolvable: vi.fn<typeof import("@paperclipai/adapter-utils/server-utils").ensureCommandResolvable>(async () => undefined),
resolveCommandForLogs: vi.fn(async () => "/usr/bin/codex"),
prepareWorkspaceForSshExecution: vi.fn(async () => ({ gitBacked: false })),
restoreWorkspaceFromSshExecution: vi.fn(async () => undefined),
runSshCommand: vi.fn(async (_spec?: unknown, _command?: string) => ({ stdout: Buffer.from("{}").toString("base64"), stderr: "" })),
syncDirectoryToSsh: vi.fn(async (_input?: { localDir: string; remoteDir: string }) => undefined),
startAdapterExecutionTargetPaperclipBridge: vi.fn(async () => ({
env: {
PAPERCLIP_API_URL: "http://127.0.0.1:4310",
PAPERCLIP_API_KEY: "bridge-token",
PAPERCLIP_API_BRIDGE_MODE: "queue_v1",
},
stop: async () => {},
})),
}));
vi.mock("@paperclipai/adapter-utils/server-utils", async () => {
const actual = await vi.importActual<typeof import("@paperclipai/adapter-utils/server-utils")>(
"@paperclipai/adapter-utils/server-utils",
);
return {
...actual,
ensureCommandResolvable,
resolveCommandForLogs,
runChildProcess,
};
});
vi.mock("@paperclipai/adapter-utils/ssh", async () => {
const actual = await vi.importActual<typeof import("@paperclipai/adapter-utils/ssh")>(
"@paperclipai/adapter-utils/ssh",
);
return {
...actual,
prepareWorkspaceForSshExecution,
restoreWorkspaceFromSshExecution,
runSshCommand,
syncDirectoryToSsh,
};
});
vi.mock("@paperclipai/adapter-utils/execution-target", async () => {
const actual = await vi.importActual<typeof import("@paperclipai/adapter-utils/execution-target")>(
"@paperclipai/adapter-utils/execution-target",
);
return {
...actual,
startAdapterExecutionTargetPaperclipBridge,
};
});
import { execute } from "./execute.js";
import { shellQuote } from "@paperclipai/adapter-utils/ssh";
import { buildProviderObservabilityLaunch } from "@paperclipai/adapter-utils/agent-observability";
describe("codex SSH host authentication", () => {
const cleanupDirs: string[] = [];
afterEach(async () => {
vi.clearAllMocks();
while (cleanupDirs.length > 0) {
const dir = cleanupDirs.pop();
if (!dir) continue;
await rm(dir, { recursive: true, force: true }).catch(() => undefined);
}
});
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", "failed_install_retry"])("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");
const native = mode === "configured" ? path.join(root, "custom-codex") : path.join(userHome, ".codex");
const controller = path.join(root, "controller-home"), skill = path.join(root, "review");
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"));
await writeFile(path.join(native, "skills", "review", "SKILL.md"), "native review skill");
}
await writeFile(path.join(native, "skills", "manual", "SKILL.md"), "native skill");
await writeFile(path.join(skill, "SKILL.md"), "---\n---\nSelected review skill.\n");
const bin = path.join(root, "fault-bin"), failCopy = path.join(root, "fail-config-copy");
if (mode === "failed_install_retry") {
await mkdir(bin);
await writeFile(failCopy, "fail once");
await writeFile(path.join(bin, "cp"), `#!/bin/sh
case "$1" in */config.toml) if [ -f ${shellQuote(failCopy)} ]; then rm -f ${shellQuote(failCopy)}; echo 'fixture config copy failed' >&2; exit 71; fi ;; esac
exec /bin/cp "$@"
`, { mode: 0o700 });
}
vi.stubEnv("CODEX_HOME", controller);
vi.stubEnv("PAPERCLIP_HOME", path.join(root, "paperclip"));
const originalRun = runSshCommand.getMockImplementation()!, originalSync = syncDirectoryToSsh.getMockImplementation()!, originalChild = runChildProcess.getMockImplementation()!;
const staged: string[] = [], remoteAssets: string[] = [];
let calls = 0;
try {
runSshCommand.mockImplementation(async (_spec, command) => {
const remoteEnv: NodeJS.ProcessEnv = { ...process.env, HOME: userHome, ...(mode === "failed_install_retry" ? { PATH: `${bin}:${process.env.PATH}` } : {}) };
delete remoteEnv.CODEX_HOME;
return promisify(execFile)("/bin/sh", ["-c", command!], { env: remoteEnv, timeout: 5000 });
});
syncDirectoryToSsh.mockImplementation(async input => {
staged.push(input!.localDir); remoteAssets.push(input!.remoteDir);
if (mode === "changed_config") await writeFile(path.join(native, "config.toml"), 'model = "changed-during-setup"\n');
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.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") {
expect(config).toContain('model = "native-model"');
expect(config).toContain("https://native.example.test/mcp");
}
if (calls++ === 0) {
expect(config).toContain(mode === "no_config" ? '[mcp_servers."tools"]' : '[mcp_servers."paperclip-tools"]');
expect(config).toContain("fixture-managed-gateway");
expect(await readFile(path.join(native, "skills", "review", "SKILL.md"), "utf8")).toContain("Selected review");
await writeFile(path.join(native, "auth.json"), "fixture-native-refreshed");
} else {
expect(config).not.toContain("fixture-managed-gateway");
await expect(stat(path.join(native, "skills", "review"))).rejects.toMatchObject({ code: "ENOENT" });
}
expect(await readFile(path.join(native, "skills", "manual", "SKILL.md"), "utf8")).toBe("native skill");
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.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", ...(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" || mode === "partial_upload_in_place") ? "in_place" : "copy") as "in_place" | "copy", authoritativeRoot: remote, pathAliases: [], outboundRestorePaths: [] } }, onLog: async () => {},
};
if (mode === "failed_install_retry") {
await expect(execute(ctx)).rejects.toThrow();
expect(runChildProcess).not.toHaveBeenCalled();
expect(await readdir(path.join(native, "skills"))).toEqual(["manual"]);
expect(await readFile(path.join(native, "auth.json"), "utf8")).toBe("fixture-native-login");
expect(await readFile(path.join(native, "config.toml"), "utf8")).toContain('model = "native-model"');
}
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 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);
expect(calls).toBe(2);
expect(await readFile(path.join(native, "auth.json"), "utf8")).toBe("fixture-native-refreshed");
}
expect(await readFile(path.join(controller, "auth.json"), "utf8")).toContain("controller-only");
for (const dir of [...staged, ...remoteAssets]) await expect(stat(dir)).rejects.toMatchObject({ code: "ENOENT" });
expect((await readdir(native)).some(name => name.startsWith(".paperclip-runtime-config.") || name.startsWith("paperclip-observability-"))).toBe(false);
} finally {
runSshCommand.mockImplementation(originalRun); syncDirectoryToSsh.mockImplementation(originalSync); runChildProcess.mockImplementation(originalChild); vi.unstubAllEnvs();
}
});
});
File diff suppressed because it is too large. Load diff
@@ -65,11 +65,23 @@ export {
} from "./quota.js";
import type { AdapterSessionCodec } from "@paperclipai/adapter-utils";
import { sessionCodec as acpxSessionCodec } from "@paperclipai/adapter-utils/acpx-engine/session-codec";
import { normalizeAdapterExecutionTargetSessionIdentity } from "@paperclipai/adapter-utils/execution-target";
function readNonEmptyString(value: unknown): string | null {
return typeof value === "string" && value.trim().length > 0 ? value.trim() : null;
}
function remoteSessionMetadata(record: Record<string, unknown>): Record<string, unknown> {
const remoteExecution = normalizeAdapterExecutionTargetSessionIdentity(record.remoteExecution);
const conversationId = readNonEmptyString(record.sshCodexConversationId);
const scope = readNonEmptyString(record.sshCodexAccountScope);
return {
...(remoteExecution ? { remoteExecution } : {}),
...(conversationId && scope && /^[a-f0-9]{64}$/.test(conversationId) && /^[a-f0-9]{64}$/.test(scope)
? { sshCodexConversationId: conversationId, sshCodexAccountScope: scope } : {}),
};
}
export const sessionCodec: AdapterSessionCodec = {
deserialize(raw: unknown) {
if (typeof raw !== "object" || raw === null || Array.isArray(raw)) return null;
@@ -85,6 +97,7 @@ export const sessionCodec: AdapterSessionCodec = {
const repoRef = readNonEmptyString(record.repoRef) ?? readNonEmptyString(record.repo_ref);
return {
sessionId,
...remoteSessionMetadata(record),
...(cwd ? { cwd } : {}),
...(workspaceId ? { workspaceId } : {}),
...(repoUrl ? { repoUrl } : {}),
@@ -104,6 +117,7 @@ export const sessionCodec: AdapterSessionCodec = {
const repoRef = readNonEmptyString(params.repoRef) ?? readNonEmptyString(params.repo_ref);
return {
sessionId,
...remoteSessionMetadata(params),
...(cwd ? { cwd } : {}),
...(workspaceId ? { workspaceId } : {}),
...(repoUrl ? { repoUrl } : {}),
@@ -0,0 +1,88 @@
import { shellQuote } from "@paperclipai/adapter-utils/ssh";
export async function readCodexSshHostHome(input: {
configuredHome?: string;
run: (command: string) => Promise<{ stdout: string }>;
}): Promise<{ home: string; config: string; exists: boolean }> {
const result = await input.run(`set -eu
native_codex_home=${input.configuredHome ? shellQuote(input.configuredHome) : '"${CODEX_HOME:-$HOME/.codex}"'}
case "$native_codex_home" in /*) ;; *) echo 'Remote CODEX_HOME must be absolute' >&2; exit 1 ;; esac
printf '%s' "$native_codex_home" | base64 | tr -d '\\r\\n'
printf '\\n'
if [ -e "$native_codex_home/config.toml" ]; then printf 'present\\n'; base64 < "$native_codex_home/config.toml"; else printf 'absent\\n'; fi`);
const [encodedHome, status, ...encodedConfig] = result.stdout.split("\n");
const home = Buffer.from(encodedHome ?? "", "base64").toString("utf8");
if (!home.startsWith("/") || !["present", "absent"].includes(status ?? "")) throw new Error("Cannot read remote Codex configuration");
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
umask 077
native_codex_home=$1
asset=$2
mkdir -p "$native_codex_home" "$native_codex_home/skills"
tmp=
created_skills=
cleanup_install() {
install_status=$?
trap - EXIT
if [ "$install_status" -ne 0 ]; then
for name in $created_skills; do
if [ -L "$native_codex_home/skills/$name" ] && [ "$(readlink "$native_codex_home/skills/$name")" = "$asset/skills/$name" ]; then
rm -f -- "$native_codex_home/skills/$name" || install_status=1
fi
done
fi
if [ -n "$tmp" ]; then rm -f "$tmp" "$tmp.skills" || install_status=1; fi
exit "$install_status"
}
trap cleanup_install EXIT
trap 'exit 1' HUP INT TERM
tmp=$(mktemp "$native_codex_home/.paperclip-runtime-config.XXXXXX")
${input.exists ? 'cmp -s "$asset/.paperclip-native-config-before" "$native_codex_home/config.toml"' : '[ ! -e "$native_codex_home/config.toml" ]'} || { echo 'Codex configuration changed; retry this task' >&2; exit 1; }
${input.profileFilename ? `[ ! -e "$native_codex_home/"${shellQuote(input.profileFilename)} ] || { echo 'Codex runtime profile already exists' >&2; exit 1; }` : ""}
manifest="$native_codex_home/.paperclip-managed-skills"
for skill in "$asset/skills"/*; do
[ -d "$skill" ] || continue
name=\${skill##*/}
case "$name" in ''|.|..|*[!A-Za-z0-9_.-]*) echo 'Invalid managed skill name' >&2; exit 1 ;; esac
if [ -e "$native_codex_home/skills/$name" ] || [ -L "$native_codex_home/skills/$name" ]; then
if ! [ -L "$native_codex_home/skills/$name" ] || ! grep -Fqx -- "$name" "$manifest" 2>/dev/null; then
echo 'A remote skill conflicts with a managed skill; rename it before retrying' >&2; exit 1
fi
fi
done
if [ -f "$manifest" ]; then
while IFS= read -r name; do
case "$name" in ''|.|..|*[!A-Za-z0-9_.-]*) continue ;; esac
if [ -L "$native_codex_home/skills/$name" ]; then rm -f -- "$native_codex_home/skills/$name"; fi
done < "$manifest"
fi
: > "$tmp.skills"
for skill in "$asset/skills"/*; do
[ -d "$skill" ] || continue
name=\${skill##*/}
created_skills="$created_skills $name"
ln -s "$skill" "$native_codex_home/skills/$name"
printf '%s\\n' "$name" >> "$tmp.skills"
done
cp "$asset/config.toml" "$tmp"
chmod 600 "$tmp"
mv -f "$tmp" "$native_codex_home/config.toml"
mv -f "$tmp.skills" "$manifest"
${input.profileFilename ? `cp "$asset/"${shellQuote(input.profileFilename)} "$native_codex_home/"${shellQuote(input.profileFilename)}` : ""}`;
return `sh -c ${shellQuote(script)} -- ${shellQuote(input.home)} ${shellQuote(input.assetDir)}`;
}
@@ -0,0 +1,21 @@
import { prepareSshConversationState } from "@paperclipai/adapter-utils/ssh-conversation-state";
export async function prepareCodexSshSessionState(input: {
remoteRoot: string;
companyId: string;
agentId: string;
accountIdentity: string;
executionIdentity: unknown;
runId: string;
saved: Record<string, unknown>;
stagedHome: string;
run: (command: string) => Promise<void>;
}) {
return prepareSshConversationState({
...input,
adapterKey: "codex",
preserve: ["sessions", "archived_sessions", "session_index.jsonl", "history.jsonl", "state_*.sqlite", "state_*.sqlite-*", "thread_history_*.sqlite", "thread_history_*.sqlite-*"],
savedScope: input.saved.sshCodexAccountScope,
savedConversationId: input.saved.sshCodexConversationId,
});
}
@@ -2,7 +2,7 @@ import fs from "node:fs/promises";
import os from "node:os";
import path from "node:path";
import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
import type { AdapterExecutionTarget } from "@paperclipai/adapter-utils/execution-target";
import type { AdapterManagedRuntimeAsset, AdapterExecutionTarget } from "@paperclipai/adapter-utils/execution-target";
const {
ensureAdapterExecutionTargetDirectory,
@@ -52,7 +52,7 @@ const {
}
return fallbackCwd;
}),
prepareAdapterExecutionTargetRuntime: vi.fn(async (input: { assets?: Array<{ key: string; localDir: string }> }) => {
prepareAdapterExecutionTargetRuntime: vi.fn(async (input: { assets?: AdapterManagedRuntimeAsset[] }) => {
const homeAsset = input?.assets?.find((asset) => asset.key === "home");
if (homeAsset) {
capturedHomeAssetFiles.value = (await fs.readdir(homeAsset.localDir)).sort();
@@ -176,7 +176,7 @@ describe("codex remote environment diagnostics", () => {
workspaceLocalDir: string;
target?: { remoteCwd?: string };
workspaceRemoteDir?: string;
assets?: Array<{ key: string; localDir: string }>;
assets?: AdapterManagedRuntimeAsset[];
},
]>;
const runtimeInput = runtimeCalls[0]?.[0];
@@ -512,6 +512,74 @@ describe("codex remote environment diagnostics", () => {
last_refresh: lastRefresh,
});
it.each(["success", "provider failure", "foreign account", "copyback failure", "routed account"])(
"preserves managed SSH probe credentials through %s before cleanup",
async outcome => {
const selectedHome = await makeScratchDir("paperclip-test-selected-codex-");
const original = subscriptionAuth("acct-selected", "original", "2020-01-01T00:00:00Z");
const refreshed = subscriptionAuth(outcome === "foreign account" ? "acct-other" : "acct-selected", "refreshed", "2020-01-02T00:00:00Z");
const shared = subscriptionAuth("acct-shared", "untouched", "2020-01-01T00:00:00Z");
const authPath = path.join(selectedHome, "auth.json");
if (outcome === "routed account") {
await fs.writeFile(path.join(selectedHome, "config.toml"), 'model_provider = "paperclip"\n[model_providers.paperclip]\nrequires_openai_auth = false\nenv_key = "PAPERCLIP_AI_PROVIDER_KEY"\n');
} else await fs.writeFile(authPath, original);
await fs.writeFile(path.join(process.env.CODEX_HOME!, "auth.json"), shared);
const basePrepare = prepareAdapterExecutionTargetRuntime.getMockImplementation()!;
let stagingDir = "";
let assetRestoreCalls = 0;
prepareAdapterExecutionTargetRuntime.mockImplementationOnce(async input => {
const prepared = await basePrepare(input);
const home = input.assets!.find(asset => asset.key === "home")!;
stagingDir = home.localDir;
return { ...prepared, restoreWorkspace: vi.fn(async () => {
try {
expect(home.restore).toBeTypeOf("function");
await home.restore!({ assetDir: prepared.assetDirs.home,
readFile: async remotePath => {
expect(remotePath).toBe(path.posix.join(prepared.assetDirs.home, "auth.json"));
assetRestoreCalls += 1;
await expect(fs.stat(stagingDir)).resolves.toBeDefined();
if (outcome === "routed account") throw Object.assign(new Error("fixture auth file absent"), { code: "ENOENT" });
if (outcome === "copyback failure") throw new Error("fixture credential read failed");
return Buffer.from(refreshed);
},
} as Parameters<NonNullable<AdapterManagedRuntimeAsset["restore"]>>[0]);
expect(await fs.readFile(authPath, "utf8").catch(() => null)).toBe(
outcome === "routed account" ? null : outcome === "foreign account" ? original : refreshed,
);
} finally {
await restoreWorkspace();
}
}) };
});
if (outcome === "provider failure") {
const success = await runAdapterExecutionTargetProcess.getMockImplementation()!();
runAdapterExecutionTargetProcess.mockResolvedValueOnce({ ...success, exitCode: 1, stdout: "", stderr: "fixture provider unavailable" });
}
const probe = testEnvironment({ companyId: "company-1", adapterType: "codex_local",
config: { engine: "cli", command: "codex", managedAiConnection: { identity: "selected-account" }, env: { CODEX_HOME: selectedHome,
...(outcome === "routed account" ? { PAPERCLIP_AI_PROVIDER_KEY: "fixture-route-key" } : {}) } },
executionTarget: { kind: "remote", transport: "ssh", remoteCwd: "/remote/workspace",
spec: { host: "ssh.example.test", port: 22, username: "agent", privateKey: null, knownHosts: null,
strictHostKeyChecking: true, remoteCwd: "/remote/workspace", remoteWorkspacePath: "/remote/workspace", useHostAuth: false } },
});
if (outcome === "copyback failure") await expect(probe).rejects.toThrow("fixture credential read failed");
else {
const result = await probe;
expect(result.status).toBe(outcome === "provider failure" ? "fail" : "pass");
expect(JSON.stringify(result)).not.toContain("synthetic-");
}
expect(assetRestoreCalls).toBe(1);
expect(restoreWorkspace).toHaveBeenCalledOnce();
await expect(fs.stat(stagingDir)).rejects.toMatchObject({ code: "ENOENT" });
expect(await fs.readFile(path.join(process.env.CODEX_HOME!, "auth.json"), "utf8")).toBe(shared);
expect(await fs.readFile(authPath, "utf8").catch(() => null)).toBe(
outcome === "routed account" ? null : ["foreign account", "copyback failure"].includes(outcome) ? original : refreshed,
);
if (outcome === "routed account") expect(capturedHomeAssetFiles.value).toEqual(["config.toml"]);
},
);
function sandboxTarget(): AdapterExecutionTarget {
return {
kind: "remote",
@@ -17,10 +17,12 @@ import {
describeAdapterExecutionTarget,
resolveAdapterExecutionTargetCwd,
prepareAdapterExecutionTargetRuntime,
managedRemoteHomeEnvironment,
} from "@paperclipai/adapter-utils/execution-target";
import fs from "node:fs/promises";
import path from "node:path";
import os from "node:os";
import { copyBackCodexAuth } from "./codex-auth-copyback.js";
import { parseCodexJsonl } from "./parse.js";
import { SANDBOX_INSTALL_COMMAND } from "../index.js";
import { codexHomeDir, readCodexAuthInfo } from "./quota.js";
@@ -94,17 +96,25 @@ async function prepareCodexHelloProbe(input: {
env: Record<string, string>;
cleanup: () => Promise<void>;
}> {
if (input.target?.kind === "remote" && input.target.transport === "ssh" && input.target.spec.useHostAuth === true) {
return { command: input.command, args: input.args, env: { ...input.env }, cleanup: async () => {} };
}
let preparedRuntime: Awaited<ReturnType<typeof prepareAdapterExecutionTargetRuntime>> | null = null;
let preparedRuntimeWorkspaceLocalDir: string | null = null;
let probeHomeLocalDir: string | null = null;
const cleanup = async () => {
await preparedRuntime?.restoreWorkspace().catch(() => {});
if (preparedRuntimeWorkspaceLocalDir) {
await fs.rm(preparedRuntimeWorkspaceLocalDir, { recursive: true, force: true }).catch(() => {});
}
if (probeHomeLocalDir) {
await fs.rm(probeHomeLocalDir, { recursive: true, force: true }).catch(() => {});
try {
await preparedRuntime?.restoreWorkspace();
} catch (error) {
if (input.managedAiConnection) throw error;
} finally {
if (preparedRuntimeWorkspaceLocalDir) {
await fs.rm(preparedRuntimeWorkspaceLocalDir, { recursive: true, force: true }).catch(() => {});
}
if (probeHomeLocalDir) {
await fs.rm(probeHomeLocalDir, { recursive: true, force: true }).catch(() => {});
}
}
};
@@ -157,7 +167,6 @@ async function prepareCodexHelloProbe(input: {
path.join(os.tmpdir(), `paperclip-codex-probe-home-${input.runId}-`),
);
let seededAuth = false;
let seededConfig = false;
for (const file of ["auth.json", "config.toml"]) {
// `fs.readFile` follows the home's `auth.json` symlink into the host's
// `~/.codex`, so we copy the resolved bytes as a plain file.
@@ -165,7 +174,6 @@ async function prepareCodexHelloProbe(input: {
if (contents) {
await fs.writeFile(path.join(probeHomeLocalDir, file), contents);
if (file === "auth.json") seededAuth = true;
if (file === "config.toml") seededConfig = true;
}
}
@@ -173,7 +181,7 @@ async function prepareCodexHelloProbe(input: {
// Pointing Codex at an empty uploaded home would mask any login already
// baked into the sandbox (e.g. a captured custom-image snapshot); leaving
// CODEX_HOME unset lets the probe exercise that in-sandbox login instead.
if (!seededAuth && !(input.managedAiConnection && seededConfig)) {
if (!seededAuth && !input.managedAiConnection) {
return {
command: input.command,
args: input.args,
@@ -186,6 +194,7 @@ async function prepareCodexHelloProbe(input: {
path.join(os.tmpdir(), `paperclip-codex-envtest-${input.runId}-`),
);
preparedRuntime = await prepareAdapterExecutionTargetRuntime({
privateRuntime: Boolean(input.managedAiConnection),
runId: input.runId,
target: input.target,
adapterKey: "codex",
@@ -204,6 +213,15 @@ async function prepareCodexHelloProbe(input: {
key: "home",
localDir: probeHomeLocalDir,
followSymlinks: true,
restore: input.managedAiConnection
? async ({ assetDir, readFile }) => {
await copyBackCodexAuth({
readSandboxAuth: () => readFile(path.posix.join(assetDir, "auth.json")),
hostAuthPath: path.join(effectiveHome, "auth.json"),
log: async () => {},
});
}
: undefined,
},
],
});
@@ -212,7 +230,10 @@ async function prepareCodexHelloProbe(input: {
command: input.command,
args: input.args,
env: preparedRuntime.assetDirs.home
? { ...input.env, CODEX_HOME: preparedRuntime.assetDirs.home }
? { ...input.env,
...(input.target?.kind === "remote" && input.target.transport === "ssh" && input.target.spec.useHostAuth === false && input.managedAiConnection && preparedRuntime.runtimeRootDir
? managedRemoteHomeEnvironment(preparedRuntime.runtimeRootDir) : {}),
CODEX_HOME: preparedRuntime.assetDirs.home }
: { ...input.env },
cleanup,
};
@@ -6,6 +6,7 @@ import path from "node:path";
import { fileURLToPath } from "node:url";
import { inferOpenAiCompatibleBiller, type AdapterExecutionContext, type AdapterExecutionResult } from "@paperclipai/adapter-utils";
import {
managedRemoteHomeEnvironment,
adapterExecutionTargetIsRemote,
adapterExecutionTargetRemoteCwd,
overrideAdapterExecutionTargetRemoteCwd,
@@ -350,444 +351,447 @@ export async function execute(ctx: AdapterExecutionContext): Promise<AdapterExec
let remoteRuntimeRootDir: string | null = null;
let paperclipBridge: Awaited<ReturnType<typeof startAdapterExecutionTargetPaperclipBridge>> = null;
if (executionTargetIsRemote) {
try {
localSkillsDir = await buildCursorSkillsDir(config);
await onLog(
"stdout",
`[paperclip] Syncing workspace and Cursor runtime assets to ${describeAdapterExecutionTarget(executionTarget)}.\n`,
);
const preparedExecutionTargetRuntime = await prepareAdapterExecutionTargetRuntime({
try {
if (executionTargetIsRemote) {
try {
localSkillsDir = await buildCursorSkillsDir(config);
await onLog(
"stdout",
`[paperclip] Syncing workspace and Cursor runtime assets to ${describeAdapterExecutionTarget(executionTarget)}.\n`,
);
const preparedExecutionTargetRuntime = await prepareAdapterExecutionTargetRuntime({
privateRuntime: Boolean(config.managedAiConnection),
runId,
target: executionTarget,
adapterKey: "cursor",
timeoutSec,
workspaceLocalDir: cwd,
installCommand: SANDBOX_INSTALL_COMMAND,
detectCommand: command,
onProgress: (line) => onLog("stdout", line),
onRuntimeProgress: ctx.onRuntimeProgress,
assets: [{
key: "skills",
localDir: localSkillsDir,
followSymlinks: true,
}],
});
restoreRemoteWorkspace = () =>
preparedExecutionTargetRuntime.restoreWorkspace((line) => onLog("stdout", line));
effectiveExecutionCwd = preparedExecutionTargetRuntime.workspaceRemoteDir ?? effectiveExecutionCwd;
refreshPaperclipWorkspaceEnvForExecution({
env,
envConfig,
workspaceCwd: effectiveWorkspaceCwd,
workspaceSource,
workspaceId,
workspaceRepoUrl,
workspaceRepoRef,
workspaceHints,
agentHome,
executionTargetIsRemote,
executionCwd: effectiveExecutionCwd,
});
remoteRuntimeRootDir = preparedExecutionTargetRuntime.runtimeRootDir;
if (executionTarget?.kind === "remote" && executionTarget.transport === "ssh" && executionTarget.spec.useHostAuth === false && config.managedAiConnection && remoteRuntimeRootDir) Object.assign(env, managedRemoteHomeEnvironment(remoteRuntimeRootDir));
const managedHome = adapterExecutionTargetUsesManagedHome(executionTarget, Boolean(config.managedAiConnection));
if (managedHome && preparedExecutionTargetRuntime.runtimeRootDir) {
env.HOME = preparedExecutionTargetRuntime.runtimeRootDir;
}
const remoteHomeDir = managedHome && preparedExecutionTargetRuntime.runtimeRootDir
? preparedExecutionTargetRuntime.runtimeRootDir
: await readAdapterExecutionTargetHomeDir(runId, executionTarget, {
cwd,
env,
timeoutSec,
graceSec,
onLog,
});
if (remoteHomeDir && preparedExecutionTargetRuntime.assetDirs.skills) {
const remoteSkillsDir = path.posix.join(remoteHomeDir, ".cursor", "skills");
await runAdapterExecutionTargetShellCommand(
runId,
executionTarget,
`mkdir -p ${JSON.stringify(path.posix.dirname(remoteSkillsDir))} && rm -rf ${JSON.stringify(remoteSkillsDir)} && cp -a ${JSON.stringify(preparedExecutionTargetRuntime.assetDirs.skills)} ${JSON.stringify(remoteSkillsDir)}`,
{ cwd, env, timeoutSec, graceSec, onLog },
);
}
} catch (error) {
await Promise.allSettled([
restoreRemoteWorkspace?.(),
localSkillsDir ? fs.rm(localSkillsDir, { recursive: true, force: true }).catch(() => undefined) : Promise.resolve(),
]);
restoreRemoteWorkspace = null;
throw error;
}
}
const finalSandboxCommand = executionTarget?.kind === "remote" && executionTarget.transport === "sandbox"
? await prepareCursorSandboxCommand({
runId,
target: executionTarget,
command,
cwd,
env,
remoteSystemHomeDirHint: sandboxSystemHomeDir,
timeoutSec,
graceSec,
})
: null;
if (finalSandboxCommand) {
command = finalSandboxCommand.command;
env = finalSandboxCommand.env;
}
const runtimeExecutionTarget = overrideAdapterExecutionTargetRemoteCwd(executionTarget, effectiveExecutionCwd);
const effectiveEnv = Object.fromEntries(
Object.entries({ ...process.env, ...env }).filter(
(entry): entry is [string, string] => typeof entry[1] === "string",
),
);
const billingType = resolveCursorBillingType(effectiveEnv);
const runtimeEnv = ensurePathInEnv(effectiveEnv);
await ensureAdapterExecutionTargetCommandResolvable(command, executionTarget, cwd, runtimeEnv, {
installCommand: SANDBOX_INSTALL_COMMAND,
timeoutSec,
});
const resolvedCommand = await resolveAdapterExecutionTargetCommandForLogs(command, executionTarget, cwd, runtimeEnv);
let loggedEnv = buildInvocationEnvForLogs(env, {
runtimeEnv,
includeRuntimeKeys: ["HOME"],
resolvedCommand,
});
if (executionTargetIsRemote && adapterExecutionTargetUsesPaperclipBridge(runtimeExecutionTarget)) {
paperclipBridge = await startAdapterExecutionTargetPaperclipBridge({
runId,
target: runtimeExecutionTarget,
enableSandboxDuplexBridge: adapterExecutionTargetEnablesSandboxDuplexBridge(runtimeExecutionTarget),
duplexObservabilityRecorder: adapterExecutionTargetDuplexObservabilityRecorder(runtimeExecutionTarget),
runtimeRootDir: remoteRuntimeRootDir,
adapterKey: "cursor",
timeoutSec,
workspaceLocalDir: cwd,
installCommand: SANDBOX_INSTALL_COMMAND,
detectCommand: command,
onProgress: (line) => onLog("stdout", line),
onRuntimeProgress: ctx.onRuntimeProgress,
assets: [{
key: "skills",
localDir: localSkillsDir,
followSymlinks: true,
}],
hostApiToken: env.PAPERCLIP_API_KEY,
onLog,
});
restoreRemoteWorkspace = () =>
preparedExecutionTargetRuntime.restoreWorkspace((line) => onLog("stdout", line));
effectiveExecutionCwd = preparedExecutionTargetRuntime.workspaceRemoteDir ?? effectiveExecutionCwd;
refreshPaperclipWorkspaceEnvForExecution({
env,
envConfig,
workspaceCwd: effectiveWorkspaceCwd,
workspaceSource,
workspaceId,
workspaceRepoUrl,
workspaceRepoRef,
workspaceHints,
agentHome,
executionTargetIsRemote,
executionCwd: effectiveExecutionCwd,
});
remoteRuntimeRootDir = preparedExecutionTargetRuntime.runtimeRootDir;
const managedHome = adapterExecutionTargetUsesManagedHome(executionTarget);
if (managedHome && preparedExecutionTargetRuntime.runtimeRootDir) {
env.HOME = preparedExecutionTargetRuntime.runtimeRootDir;
if (paperclipBridge) {
Object.assign(env, paperclipBridge.env);
loggedEnv = buildInvocationEnvForLogs(env, {
runtimeEnv: ensurePathInEnv({ ...process.env, ...env }),
includeRuntimeKeys: ["HOME"],
resolvedCommand,
});
}
const remoteHomeDir = managedHome && preparedExecutionTargetRuntime.runtimeRootDir
? preparedExecutionTargetRuntime.runtimeRootDir
: await readAdapterExecutionTargetHomeDir(runId, executionTarget, {
cwd,
env,
timeoutSec,
graceSec,
onLog,
});
if (remoteHomeDir && preparedExecutionTargetRuntime.assetDirs.skills) {
const remoteSkillsDir = path.posix.join(remoteHomeDir, ".cursor", "skills");
await runAdapterExecutionTargetShellCommand(
runId,
executionTarget,
`mkdir -p ${JSON.stringify(path.posix.dirname(remoteSkillsDir))} && rm -rf ${JSON.stringify(remoteSkillsDir)} && cp -a ${JSON.stringify(preparedExecutionTargetRuntime.assetDirs.skills)} ${JSON.stringify(remoteSkillsDir)}`,
{ cwd, env, timeoutSec, graceSec, onLog },
);
}
} catch (error) {
await Promise.allSettled([
restoreRemoteWorkspace?.(),
localSkillsDir ? fs.rm(localSkillsDir, { recursive: true, force: true }).catch(() => undefined) : Promise.resolve(),
]);
throw error;
}
}
const finalSandboxCommand = executionTarget?.kind === "remote" && executionTarget.transport === "sandbox"
? await prepareCursorSandboxCommand({
runId,
target: executionTarget,
command,
cwd,
env,
remoteSystemHomeDirHint: sandboxSystemHomeDir,
timeoutSec,
graceSec,
})
: null;
if (finalSandboxCommand) {
command = finalSandboxCommand.command;
env = finalSandboxCommand.env;
}
const runtimeExecutionTarget = overrideAdapterExecutionTargetRemoteCwd(executionTarget, effectiveExecutionCwd);
const effectiveEnv = Object.fromEntries(
Object.entries({ ...process.env, ...env }).filter(
(entry): entry is [string, string] => typeof entry[1] === "string",
),
);
const billingType = resolveCursorBillingType(effectiveEnv);
const runtimeEnv = ensurePathInEnv(effectiveEnv);
await ensureAdapterExecutionTargetCommandResolvable(command, executionTarget, cwd, runtimeEnv, {
installCommand: SANDBOX_INSTALL_COMMAND,
timeoutSec,
});
const resolvedCommand = await resolveAdapterExecutionTargetCommandForLogs(command, executionTarget, cwd, runtimeEnv);
let loggedEnv = buildInvocationEnvForLogs(env, {
runtimeEnv,
includeRuntimeKeys: ["HOME"],
resolvedCommand,
});
if (executionTargetIsRemote && adapterExecutionTargetUsesPaperclipBridge(runtimeExecutionTarget)) {
paperclipBridge = await startAdapterExecutionTargetPaperclipBridge({
runId,
target: runtimeExecutionTarget,
enableSandboxDuplexBridge: adapterExecutionTargetEnablesSandboxDuplexBridge(runtimeExecutionTarget),
duplexObservabilityRecorder: adapterExecutionTargetDuplexObservabilityRecorder(runtimeExecutionTarget),
runtimeRootDir: remoteRuntimeRootDir,
adapterKey: "cursor",
timeoutSec,
hostApiToken: env.PAPERCLIP_API_KEY,
onLog,
});
if (paperclipBridge) {
Object.assign(env, paperclipBridge.env);
loggedEnv = buildInvocationEnvForLogs(env, {
runtimeEnv: ensurePathInEnv({ ...process.env, ...env }),
includeRuntimeKeys: ["HOME"],
resolvedCommand,
});
}
}
const runtimeSessionParams = parseObject(runtime.sessionParams);
const runtimeSessionId = asString(runtimeSessionParams.sessionId, runtime.sessionId ?? "");
const runtimeSessionCwd = asString(runtimeSessionParams.cwd, "");
const runtimeRemoteExecution = parseObject(runtimeSessionParams.remoteExecution);
const canResumeSession =
runtimeSessionId.length > 0 &&
(runtimeSessionCwd.length === 0 || path.resolve(runtimeSessionCwd) === path.resolve(effectiveExecutionCwd)) &&
adapterExecutionTargetSessionMatches(runtimeRemoteExecution, runtimeExecutionTarget);
const sessionId = canResumeSession ? runtimeSessionId : null;
if (executionTargetIsRemote && runtimeSessionId && !canResumeSession) {
await onLog(
"stdout",
`[paperclip] Cursor session "${runtimeSessionId}" does not match the current remote execution identity and will not be resumed in "${effectiveExecutionCwd}". Starting a fresh remote session.\n`,
);
} else if (runtimeSessionId && !canResumeSession) {
await onLog(
"stdout",
`[paperclip] Cursor session "${runtimeSessionId}" was saved for cwd "${runtimeSessionCwd}" and will not be resumed in "${effectiveExecutionCwd}".\n`,
);
}
const instructionsFilePath = asString(config.instructionsFilePath, "").trim();
const instructionsDir = instructionsFilePath ? `${path.dirname(instructionsFilePath)}/` : "";
let instructionsPrefix = "";
let instructionsChars = 0;
if (instructionsFilePath) {
try {
const instructionsContents = await fs.readFile(instructionsFilePath, "utf8");
instructionsPrefix =
`${instructionsContents}\n\n` +
`The above agent instructions were loaded from ${instructionsFilePath}. ` +
`Resolve any relative file references from ${instructionsDir}.\n\n`;
instructionsChars = instructionsPrefix.length;
} catch (err) {
const reason = err instanceof Error ? err.message : String(err);
const runtimeSessionParams = parseObject(runtime.sessionParams);
const runtimeSessionId = asString(runtimeSessionParams.sessionId, runtime.sessionId ?? "");
const runtimeSessionCwd = asString(runtimeSessionParams.cwd, "");
const runtimeRemoteExecution = parseObject(runtimeSessionParams.remoteExecution);
const canResumeSession =
runtimeSessionId.length > 0 &&
(runtimeSessionCwd.length === 0 || path.resolve(runtimeSessionCwd) === path.resolve(effectiveExecutionCwd)) &&
adapterExecutionTargetSessionMatches(runtimeRemoteExecution, runtimeExecutionTarget);
const sessionId = canResumeSession ? runtimeSessionId : null;
if (executionTargetIsRemote && runtimeSessionId && !canResumeSession) {
await onLog(
"stdout",
`[paperclip] Warning: could not read agent instructions file "${instructionsFilePath}": ${reason}\n`,
`[paperclip] Cursor session "${runtimeSessionId}" does not match the current remote execution identity and will not be resumed in "${effectiveExecutionCwd}". Starting a fresh remote session.\n`,
);
} else if (runtimeSessionId && !canResumeSession) {
await onLog(
"stdout",
`[paperclip] Cursor session "${runtimeSessionId}" was saved for cwd "${runtimeSessionCwd}" and will not be resumed in "${effectiveExecutionCwd}".\n`,
);
}
}
const commandNotes = (() => {
const notes: string[] = [];
if (autoTrustEnabled) {
notes.push("Auto-added --yolo to bypass interactive prompts.");
const instructionsFilePath = asString(config.instructionsFilePath, "").trim();
const instructionsDir = instructionsFilePath ? `${path.dirname(instructionsFilePath)}/` : "";
let instructionsPrefix = "";
let instructionsChars = 0;
if (instructionsFilePath) {
try {
const instructionsContents = await fs.readFile(instructionsFilePath, "utf8");
instructionsPrefix =
`${instructionsContents}\n\n` +
`The above agent instructions were loaded from ${instructionsFilePath}. ` +
`Resolve any relative file references from ${instructionsDir}.\n\n`;
instructionsChars = instructionsPrefix.length;
} catch (err) {
const reason = err instanceof Error ? err.message : String(err);
await onLog(
"stdout",
`[paperclip] Warning: could not read agent instructions file "${instructionsFilePath}": ${reason}\n`,
);
}
}
notes.push("Prompt is piped to Cursor via stdin.");
const sandboxCommand = finalSandboxCommand ?? initialSandboxCommand;
if (sandboxCommand?.addedPathEntry) {
notes.push(`Remote sandbox runs prepend ${sandboxCommand.addedPathEntry} to PATH.`);
}
if (sandboxCommand?.preferredCommandPath) {
const commandNotes = (() => {
const notes: string[] = [];
if (autoTrustEnabled) {
notes.push("Auto-added --yolo to bypass interactive prompts.");
}
notes.push("Prompt is piped to Cursor via stdin.");
const sandboxCommand = finalSandboxCommand ?? initialSandboxCommand;
if (sandboxCommand?.addedPathEntry) {
notes.push(`Remote sandbox runs prepend ${sandboxCommand.addedPathEntry} to PATH.`);
}
if (sandboxCommand?.preferredCommandPath) {
notes.push(
`Remote sandbox runs prefer ${sandboxCommand.preferredCommandPath} when using the default Cursor entrypoint.`,
);
}
if (!instructionsFilePath) return notes;
if (instructionsPrefix.length > 0) {
notes.push(
`Loaded agent instructions from ${instructionsFilePath}`,
`Prepended instructions + path directive to prompt (relative references from ${instructionsDir}).`,
);
return notes;
}
notes.push(
`Remote sandbox runs prefer ${sandboxCommand.preferredCommandPath} when using the default Cursor entrypoint.`,
);
}
if (!instructionsFilePath) return notes;
if (instructionsPrefix.length > 0) {
notes.push(
`Loaded agent instructions from ${instructionsFilePath}`,
`Prepended instructions + path directive to prompt (relative references from ${instructionsDir}).`,
`Configured instructionsFilePath ${instructionsFilePath}, but file could not be read; continuing without injected instructions.`,
);
return notes;
}
notes.push(
`Configured instructionsFilePath ${instructionsFilePath}, but file could not be read; continuing without injected instructions.`,
);
return notes;
})();
})();
const bootstrapPromptTemplate = asString(config.bootstrapPromptTemplate, "");
const templateData = {
agentId: agent.id,
companyId: agent.companyId,
runId,
company: { id: agent.companyId },
agent,
run: { id: runId, source: "on_demand" },
context,
};
const buildPrompt = (resumedSession: boolean) => {
const renderedBootstrapPrompt =
!resumedSession && bootstrapPromptTemplate.trim().length > 0
? renderTemplate(bootstrapPromptTemplate, templateData).trim()
: "";
const { taskContextNote, wakePrompt } = selectPaperclipPromptSections(context, {
resumedSession,
includeCommunicationGuidance: false,
});
const shouldUseResumeDeltaPrompt = resumedSession && wakePrompt.length > 0;
const renderedPrompt = shouldUseResumeDeltaPrompt || isPaperclipRecoveryWakePayload(context.paperclipWake)
? ""
: renderTemplate(promptTemplate, templateData);
const sessionHandoffNote = asString(context.paperclipSessionHandoffMarkdown, "").trim();
const paperclipEnvNote = renderPaperclipEnvNote(env);
const basePrompt = joinPromptSections([
instructionsPrefix,
renderedBootstrapPrompt,
wakePrompt,
taskContextNote,
sessionHandoffNote,
paperclipEnvNote,
renderedPrompt,
]);
return {
basePrompt,
promptMetrics: {
promptChars: basePrompt.length,
instructionsChars,
bootstrapPromptChars: renderedBootstrapPrompt.length,
wakePromptChars: wakePrompt.length,
taskContextChars: taskContextNote.length,
sessionHandoffChars: sessionHandoffNote.length,
runtimeNoteChars: paperclipEnvNote.length,
heartbeatPromptChars: renderedPrompt.length,
},
const bootstrapPromptTemplate = asString(config.bootstrapPromptTemplate, "");
const templateData = {
agentId: agent.id,
companyId: agent.companyId,
runId,
company: { id: agent.companyId },
agent,
run: { id: runId, source: "on_demand" },
context,
};
};
const buildArgs = (resumeSessionId: string | null) => {
const args = ["-p", "--output-format", "stream-json", "--workspace", effectiveExecutionCwd];
if (resumeSessionId) args.push("--resume", resumeSessionId);
if (model) args.push("--model", model);
if (mode) args.push("--mode", mode);
if (autoTrustEnabled) args.push("--yolo");
if (extraArgs.length > 0) args.push(...extraArgs);
return args;
};
const runAttempt = async (resumeSessionId: string | null) => {
await hydrateFreshSessionHandoff(ctx, { resumedSession: Boolean(resumeSessionId) });
const { basePrompt, promptMetrics } = buildPrompt(Boolean(resumeSessionId));
const prompt = joinPromptSections([
selectInitialCommunicationGuidance(context, { resumedSession: Boolean(resumeSessionId) }),
basePrompt,
]);
const args = buildArgs(resumeSessionId);
if (onMeta) {
await onMeta({
adapterType: "cursor",
command: resolvedCommand,
cwd: effectiveExecutionCwd,
commandNotes,
commandArgs: args,
env: loggedEnv,
prompt,
promptMetrics: { ...promptMetrics, promptChars: prompt.length },
context,
const buildPrompt = (resumedSession: boolean) => {
const renderedBootstrapPrompt =
!resumedSession && bootstrapPromptTemplate.trim().length > 0
? renderTemplate(bootstrapPromptTemplate, templateData).trim()
: "";
const { taskContextNote, wakePrompt } = selectPaperclipPromptSections(context, {
resumedSession,
includeCommunicationGuidance: false,
});
}
const consumeAccounting = createCursorJsonlParser();
const accountingLog = createUsageCheckpointLog(onLog, ctx.onUsage, stdout => {
const parsed = consumeAccounting(stdout);
const provider = resolveProviderFromModel(model);
const hasCompleteAccounting = parsed.usageComplete || parsed.costUsd != null;
const shouldUseResumeDeltaPrompt = resumedSession && wakePrompt.length > 0;
const renderedPrompt = shouldUseResumeDeltaPrompt || isPaperclipRecoveryWakePayload(context.paperclipWake)
? ""
: renderTemplate(promptTemplate, templateData);
const sessionHandoffNote = asString(context.paperclipSessionHandoffMarkdown, "").trim();
const paperclipEnvNote = renderPaperclipEnvNote(env);
const basePrompt = joinPromptSections([
instructionsPrefix,
renderedBootstrapPrompt,
wakePrompt,
taskContextNote,
sessionHandoffNote,
paperclipEnvNote,
renderedPrompt,
]);
return {
usage: parsed.usageReported ? parsed.usage : undefined,
costUsd: parsed.costUsd,
costStatus: hasCompleteAccounting ? undefined : "unpriced",
usageBasis: "per_run", provider,
biller: resolveCursorBiller(effectiveEnv, billingType, provider), billingType, model,
complete: parsed.sawResult && hasCompleteAccounting,
basePrompt,
promptMetrics: {
promptChars: basePrompt.length,
instructionsChars,
bootstrapPromptChars: renderedBootstrapPrompt.length,
wakePromptChars: wakePrompt.length,
taskContextChars: taskContextNote.length,
sessionHandoffChars: sessionHandoffNote.length,
runtimeNoteChars: paperclipEnvNote.length,
heartbeatPromptChars: renderedPrompt.length,
},
};
});
let stdoutLineBuffer = "";
const emitNormalizedStdoutLine = async (rawLine: string) => {
const normalized = normalizeCursorStreamLine(rawLine);
if (!normalized.line) return;
await accountingLog(normalized.stream ?? "stdout", `${normalized.line}\n`);
};
const flushStdoutChunk = async (chunk: string, finalize = false) => {
const combined = `${stdoutLineBuffer}${chunk}`;
const lines = combined.split(/\r?\n/);
stdoutLineBuffer = lines.pop() ?? "";
for (const line of lines) {
await emitNormalizedStdoutLine(line);
}
if (finalize) {
const trailing = stdoutLineBuffer.trim();
stdoutLineBuffer = "";
if (trailing) {
await emitNormalizedStdoutLine(trailing);
}
}
};
const proc = await runAdapterExecutionTargetProcess(runId, runtimeExecutionTarget, command, args, {
onProcessStopped: providerStop.beginInvocation(),
cwd,
env,
timeoutSec,
graceSec,
stdin: prompt,
onSpawn,
onRuntimeProgress: ctx.onRuntimeProgress,
onLog: async (stream, chunk) => {
if (stream !== "stdout") {
await onLog(stream, chunk);
return;
const buildArgs = (resumeSessionId: string | null) => {
const args = ["-p", "--output-format", "stream-json", "--workspace", effectiveExecutionCwd];
if (resumeSessionId) args.push("--resume", resumeSessionId);
if (model) args.push("--model", model);
if (mode) args.push("--mode", mode);
if (autoTrustEnabled) args.push("--yolo");
if (extraArgs.length > 0) args.push(...extraArgs);
return args;
};
const runAttempt = async (resumeSessionId: string | null) => {
await hydrateFreshSessionHandoff(ctx, { resumedSession: Boolean(resumeSessionId) });
const { basePrompt, promptMetrics } = buildPrompt(Boolean(resumeSessionId));
const prompt = joinPromptSections([
selectInitialCommunicationGuidance(context, { resumedSession: Boolean(resumeSessionId) }),
basePrompt,
]);
const args = buildArgs(resumeSessionId);
if (onMeta) {
await onMeta({
adapterType: "cursor",
command: resolvedCommand,
cwd: effectiveExecutionCwd,
commandNotes,
commandArgs: args,
env: loggedEnv,
prompt,
promptMetrics: { ...promptMetrics, promptChars: prompt.length },
context,
});
}
const consumeAccounting = createCursorJsonlParser();
const accountingLog = createUsageCheckpointLog(onLog, ctx.onUsage, stdout => {
const parsed = consumeAccounting(stdout);
const provider = resolveProviderFromModel(model);
const hasCompleteAccounting = parsed.usageComplete || parsed.costUsd != null;
return {
usage: parsed.usageReported ? parsed.usage : undefined,
costUsd: parsed.costUsd,
costStatus: hasCompleteAccounting ? undefined : "unpriced",
usageBasis: "per_run", provider,
biller: resolveCursorBiller(effectiveEnv, billingType, provider), billingType, model,
complete: parsed.sawResult && hasCompleteAccounting,
};
});
let stdoutLineBuffer = "";
const emitNormalizedStdoutLine = async (rawLine: string) => {
const normalized = normalizeCursorStreamLine(rawLine);
if (!normalized.line) return;
await accountingLog(normalized.stream ?? "stdout", `${normalized.line}\n`);
};
const flushStdoutChunk = async (chunk: string, finalize = false) => {
const combined = `${stdoutLineBuffer}${chunk}`;
const lines = combined.split(/\r?\n/);
stdoutLineBuffer = lines.pop() ?? "";
for (const line of lines) {
await emitNormalizedStdoutLine(line);
}
await flushStdoutChunk(chunk);
if (finalize) {
const trailing = stdoutLineBuffer.trim();
stdoutLineBuffer = "";
if (trailing) {
await emitNormalizedStdoutLine(trailing);
}
}
};
const proc = await runAdapterExecutionTargetProcess(runId, runtimeExecutionTarget, command, args, {
onProcessStopped: providerStop.beginInvocation(),
cwd,
env,
timeoutSec,
graceSec,
stdin: prompt,
onSpawn,
onRuntimeProgress: ctx.onRuntimeProgress,
onLog: async (stream, chunk) => {
if (stream !== "stdout") {
await onLog(stream, chunk);
return;
}
await flushStdoutChunk(chunk);
},
runLogTail: paperclipBridge?.runLogTail,
settleRunDisposition: paperclipBridge?.settleRunDisposition,
});
await flushStdoutChunk("", true);
await accountingLog.flush();
return {
proc,
parsed: parseCursorJsonl(proc.stdout),
};
};
const providerFromModel = resolveProviderFromModel(model);
const toResult = (
attempt: {
proc: {
exitCode: number | null;
signal: string | null;
timedOut: boolean;
stdout: string;
stderr: string;
errorCode?: string | null;
};
parsed: ReturnType<typeof parseCursorJsonl>;
},
runLogTail: paperclipBridge?.runLogTail,
settleRunDisposition: paperclipBridge?.settleRunDisposition,
});
await flushStdoutChunk("", true);
await accountingLog.flush();
clearSessionOnMissingSession = false,
): AdapterExecutionResult => {
const hasCompleteAccounting = attempt.parsed.usageComplete || attempt.parsed.costUsd != null;
const usageComplete = hasCompleteAccounting && (attempt.parsed.sawResult || (attempt.parsed.sawLegacyStep
&& attempt.proc.exitCode === 0 && !attempt.proc.signal && !attempt.proc.timedOut
&& !attempt.parsed.errorMessage));
if (attempt.proc.timedOut) {
return {
exitCode: attempt.proc.exitCode,
signal: attempt.proc.signal,
timedOut: true,
usageComplete,
usage: attempt.parsed.usageReported ? attempt.parsed.usage : undefined,
usageBasis: "per_run",
provider: providerFromModel,
biller: resolveCursorBiller(effectiveEnv, billingType, providerFromModel),
model,
billingType,
costUsd: attempt.parsed.costUsd,
costStatus: hasCompleteAccounting ? undefined : "unpriced",
errorMessage: `Timed out after ${timeoutSec}s`,
clearSession: clearSessionOnMissingSession,
};
}
return {
proc,
parsed: parseCursorJsonl(proc.stdout),
};
};
const resolvedSessionId = attempt.parsed.sessionId ?? runtimeSessionId ?? runtime.sessionId ?? null;
const resolvedSessionParams = resolvedSessionId
? ({
sessionId: resolvedSessionId,
cwd: effectiveExecutionCwd,
...(workspaceId ? { workspaceId } : {}),
...(workspaceRepoUrl ? { repoUrl: workspaceRepoUrl } : {}),
...(workspaceRepoRef ? { repoRef: workspaceRepoRef } : {}),
...(executionTargetIsRemote
? {
remoteExecution: adapterExecutionTargetSessionIdentity(runtimeExecutionTarget),
}
: {}),
} as Record<string, unknown>)
: null;
const parsedError = typeof attempt.parsed.errorMessage === "string" ? attempt.parsed.errorMessage.trim() : "";
const stderrLine = firstCursorDiagnosticLine(attempt.proc.stderr);
const fallbackErrorMessage =
parsedError ||
stderrLine ||
`Cursor exited with code ${attempt.proc.exitCode ?? -1}`;
const providerFromModel = resolveProviderFromModel(model);
const toResult = (
attempt: {
proc: {
exitCode: number | null;
signal: string | null;
timedOut: boolean;
stdout: string;
stderr: string;
errorCode?: string | null;
};
parsed: ReturnType<typeof parseCursorJsonl>;
},
clearSessionOnMissingSession = false,
): AdapterExecutionResult => {
const hasCompleteAccounting = attempt.parsed.usageComplete || attempt.parsed.costUsd != null;
const usageComplete = hasCompleteAccounting && (attempt.parsed.sawResult || (attempt.parsed.sawLegacyStep
&& attempt.proc.exitCode === 0 && !attempt.proc.signal && !attempt.proc.timedOut
&& !attempt.parsed.errorMessage));
if (attempt.proc.timedOut) {
return {
exitCode: attempt.proc.exitCode,
signal: attempt.proc.signal,
timedOut: true,
timedOut: false,
usageComplete,
usage: attempt.parsed.usageReported ? attempt.parsed.usage : undefined,
usageBasis: "per_run",
errorMessage:
(attempt.proc.exitCode ?? 0) === 0
? null
: fallbackErrorMessage,
// Forward the transport-level error code from the run-disposition seam. A
// lost duplex control channel surfaces the typed `duplex_channel_lost`
// code; every other result carries no code here.
errorCode: attempt.proc.errorCode ?? null,
usage: attempt.parsed.usageReported ? attempt.parsed.usage : undefined,
sessionId: resolvedSessionId,
sessionParams: resolvedSessionParams,
sessionDisplayId: resolvedSessionId,
provider: providerFromModel,
biller: resolveCursorBiller(effectiveEnv, billingType, providerFromModel),
model,
billingType,
costUsd: attempt.parsed.costUsd,
costStatus: hasCompleteAccounting ? undefined : "unpriced",
errorMessage: `Timed out after ${timeoutSec}s`,
clearSession: clearSessionOnMissingSession,
resultJson: {
stdout: attempt.proc.stdout,
stderr: attempt.proc.stderr,
},
summary: attempt.parsed.summary,
clearSession: Boolean(clearSessionOnMissingSession && !resolvedSessionId),
};
}
const resolvedSessionId = attempt.parsed.sessionId ?? runtimeSessionId ?? runtime.sessionId ?? null;
const resolvedSessionParams = resolvedSessionId
? ({
sessionId: resolvedSessionId,
cwd: effectiveExecutionCwd,
...(workspaceId ? { workspaceId } : {}),
...(workspaceRepoUrl ? { repoUrl: workspaceRepoUrl } : {}),
...(workspaceRepoRef ? { repoRef: workspaceRepoRef } : {}),
...(executionTargetIsRemote
? {
remoteExecution: adapterExecutionTargetSessionIdentity(runtimeExecutionTarget),
}
: {}),
} as Record<string, unknown>)
: null;
const parsedError = typeof attempt.parsed.errorMessage === "string" ? attempt.parsed.errorMessage.trim() : "";
const stderrLine = firstCursorDiagnosticLine(attempt.proc.stderr);
const fallbackErrorMessage =
parsedError ||
stderrLine ||
`Cursor exited with code ${attempt.proc.exitCode ?? -1}`;
return {
exitCode: attempt.proc.exitCode,
signal: attempt.proc.signal,
timedOut: false,
usageComplete,
usageBasis: "per_run",
errorMessage:
(attempt.proc.exitCode ?? 0) === 0
? null
: fallbackErrorMessage,
// Forward the transport-level error code from the run-disposition seam. A
// lost duplex control channel surfaces the typed `duplex_channel_lost`
// code; every other result carries no code here.
errorCode: attempt.proc.errorCode ?? null,
usage: attempt.parsed.usageReported ? attempt.parsed.usage : undefined,
sessionId: resolvedSessionId,
sessionParams: resolvedSessionParams,
sessionDisplayId: resolvedSessionId,
provider: providerFromModel,
biller: resolveCursorBiller(effectiveEnv, billingType, providerFromModel),
model,
billingType,
costUsd: attempt.parsed.costUsd,
costStatus: hasCompleteAccounting ? undefined : "unpriced",
resultJson: {
stdout: attempt.proc.stdout,
stderr: attempt.proc.stderr,
},
summary: attempt.parsed.summary,
clearSession: Boolean(clearSessionOnMissingSession && !resolvedSessionId),
};
};
try {
const initial = await runAttempt(sessionId);
if (
sessionId &&
@@ -807,18 +811,21 @@ export async function execute(ctx: AdapterExecutionContext): Promise<AdapterExec
try {
await providerStop.collectBeforeRestore();
} finally {
if (paperclipBridge) {
await paperclipBridge.stop();
}
if (restoreRemoteWorkspace) {
await onLog(
"stdout",
`[paperclip] Restoring workspace changes from ${describeAdapterExecutionTarget(executionTarget)}.\n`,
);
await restoreRemoteWorkspace();
}
if (localSkillsDir) {
await fs.rm(localSkillsDir, { recursive: true, force: true }).catch(() => undefined);
try {
if (paperclipBridge) {
await paperclipBridge.stop();
}
} finally {
if (restoreRemoteWorkspace) {
await onLog(
"stdout",
`[paperclip] Restoring workspace changes from ${describeAdapterExecutionTarget(executionTarget)}.\n`,
).catch(() => undefined);
await restoreRemoteWorkspace();
}
if (localSkillsDir) {
await fs.rm(localSkillsDir, { recursive: true, force: true }).catch(() => undefined);
}
}
}
}
@@ -7,6 +7,7 @@ import path from "node:path";
import { fileURLToPath } from "node:url";
import type { AdapterExecutionContext, AdapterExecutionResult } from "@paperclipai/adapter-utils";
import {
managedRemoteHomeEnvironment,
adapterExecutionTargetIsRemote,
adapterExecutionTargetRemoteCwd,
overrideAdapterExecutionTargetRemoteCwd,
@@ -362,434 +363,437 @@ export async function execute(ctx: AdapterExecutionContext): Promise<AdapterExec
let remoteRuntimeRootDir: string | null = null;
let paperclipBridge: Awaited<ReturnType<typeof startAdapterExecutionTargetPaperclipBridge>> = null;
if (executionTargetIsRemote) {
try {
localSkillsDir = await buildGeminiSkillsDir(config);
await onLog(
"stdout",
`[paperclip] Syncing workspace and Gemini runtime assets to ${describeAdapterExecutionTarget(executionTarget)}.\n`,
);
const preparedExecutionTargetRuntime = await prepareAdapterExecutionTargetRuntime({
try {
if (executionTargetIsRemote) {
try {
localSkillsDir = await buildGeminiSkillsDir(config);
await onLog(
"stdout",
`[paperclip] Syncing workspace and Gemini runtime assets to ${describeAdapterExecutionTarget(executionTarget)}.\n`,
);
const preparedExecutionTargetRuntime = await prepareAdapterExecutionTargetRuntime({
privateRuntime: Boolean(config.managedAiConnection),
runId,
target: executionTarget,
adapterKey: "gemini",
timeoutSec,
workspaceLocalDir: cwd,
installCommand: SANDBOX_INSTALL_COMMAND,
detectCommand: command,
onProgress: (line) => onLog("stdout", line),
onRuntimeProgress: ctx.onRuntimeProgress,
assets: [{
key: "skills",
localDir: localSkillsDir,
followSymlinks: true,
}],
});
restoreRemoteWorkspace = () =>
preparedExecutionTargetRuntime.restoreWorkspace((line) => onLog("stdout", line));
effectiveExecutionCwd = preparedExecutionTargetRuntime.workspaceRemoteDir ?? effectiveExecutionCwd;
refreshPaperclipWorkspaceEnvForExecution({
env,
envConfig,
workspaceCwd: effectiveWorkspaceCwd,
workspaceSource,
workspaceId,
workspaceRepoUrl,
workspaceRepoRef,
workspaceHints,
agentHome,
executionTargetIsRemote,
executionCwd: effectiveExecutionCwd,
});
remoteRuntimeRootDir = preparedExecutionTargetRuntime.runtimeRootDir;
if (executionTarget?.kind === "remote" && executionTarget.transport === "ssh" && executionTarget.spec.useHostAuth === false && config.managedAiConnection && remoteRuntimeRootDir) Object.assign(env, managedRemoteHomeEnvironment(remoteRuntimeRootDir));
const managedHome = adapterExecutionTargetUsesManagedHome(executionTarget, Boolean(config.managedAiConnection));
const managedRemoteHomeDir =
managedHome && preparedExecutionTargetRuntime.runtimeRootDir
? preparedExecutionTargetRuntime.runtimeRootDir
: null;
if (managedRemoteHomeDir) {
env.HOME = managedRemoteHomeDir;
}
const remoteHomeDir =
managedRemoteHomeDir ??
(await readAdapterExecutionTargetHomeDir(runId, executionTarget, {
cwd,
env,
timeoutSec,
graceSec,
onLog,
}));
if (remoteHomeDir && preparedExecutionTargetRuntime.assetDirs.skills) {
remoteSkillsDir = path.posix.join(remoteHomeDir, ".gemini", "skills");
await runAdapterExecutionTargetShellCommand(
runId,
executionTarget,
`mkdir -p ${JSON.stringify(path.posix.dirname(remoteSkillsDir))} && rm -rf ${JSON.stringify(remoteSkillsDir)} && cp -a ${JSON.stringify(preparedExecutionTargetRuntime.assetDirs.skills)} ${JSON.stringify(remoteSkillsDir)}`,
{ cwd, env, timeoutSec, graceSec, onLog },
);
}
// Gemini CLI refuses headless runs without an auth selection persisted in
// $HOME/.gemini/settings.json ("Invalid auth method selected."); env vars
// alone (GEMINI_DEFAULT_AUTH_TYPE) do not satisfy it. With a managed HOME
// the runtime root replaces the image home, so any settings baked into the
// image are invisible -- pre-select the api-key auth whenever an API key
// is provided. Both settings schema generations are written (legacy
// selectedAuthType + current security.auth.selectedType). An existing
// settings.json (user-shipped via workspace) is left untouched.
// Only the managed HOME (the per-run runtime root) is touched: on
// non-managed remote targets remoteHomeDir is the user's real home, where
// creating files is out of scope and existing settings remain visible.
// Key presence check spans the run env AND the host process env: in the
// managed sandbox path the key never enters the adapter's run env -- it
// reaches the agent pod via the provider's per-run secret (envKeys
// passthrough from the host env), so the host env is the signal here.
const hasGeminiApiKey = Boolean(
env.GEMINI_API_KEY || env.GOOGLE_API_KEY ||
process.env.GEMINI_API_KEY || process.env.GOOGLE_API_KEY,
);
if (managedRemoteHomeDir && hasGeminiApiKey) {
const remoteSettingsPath = path.posix.join(managedRemoteHomeDir, ".gemini", "settings.json");
const authSettingsJson = JSON.stringify({
selectedAuthType: "gemini-api-key",
security: { auth: { selectedType: "gemini-api-key" } },
});
await runAdapterExecutionTargetShellCommand(
runId,
executionTarget,
`mkdir -p ${JSON.stringify(path.posix.dirname(remoteSettingsPath))} && { [ -f ${JSON.stringify(remoteSettingsPath)} ] || printf '%s' ${JSON.stringify(authSettingsJson)} > ${JSON.stringify(remoteSettingsPath)}; }`,
{ cwd, env, timeoutSec, graceSec, onLog },
);
}
} catch (error) {
await Promise.allSettled([
restoreRemoteWorkspace?.(),
localSkillsDir ? fs.rm(path.dirname(localSkillsDir), { recursive: true, force: true }).catch(() => undefined) : Promise.resolve(),
]);
restoreRemoteWorkspace = null;
throw error;
}
}
const runtimeExecutionTarget = overrideAdapterExecutionTargetRemoteCwd(executionTarget, effectiveExecutionCwd);
if (executionTargetIsRemote && adapterExecutionTargetUsesPaperclipBridge(executionTarget)) {
paperclipBridge = await startAdapterExecutionTargetPaperclipBridge({
runId,
target: executionTarget,
target: runtimeExecutionTarget,
enableSandboxDuplexBridge: adapterExecutionTargetEnablesSandboxDuplexBridge(runtimeExecutionTarget),
duplexObservabilityRecorder: adapterExecutionTargetDuplexObservabilityRecorder(runtimeExecutionTarget),
runtimeRootDir: remoteRuntimeRootDir,
adapterKey: "gemini",
timeoutSec,
workspaceLocalDir: cwd,
installCommand: SANDBOX_INSTALL_COMMAND,
detectCommand: command,
onProgress: (line) => onLog("stdout", line),
onRuntimeProgress: ctx.onRuntimeProgress,
assets: [{
key: "skills",
localDir: localSkillsDir,
followSymlinks: true,
}],
hostApiToken: env.PAPERCLIP_API_KEY,
onLog,
});
restoreRemoteWorkspace = () =>
preparedExecutionTargetRuntime.restoreWorkspace((line) => onLog("stdout", line));
effectiveExecutionCwd = preparedExecutionTargetRuntime.workspaceRemoteDir ?? effectiveExecutionCwd;
refreshPaperclipWorkspaceEnvForExecution({
env,
envConfig,
workspaceCwd: effectiveWorkspaceCwd,
workspaceSource,
workspaceId,
workspaceRepoUrl,
workspaceRepoRef,
workspaceHints,
agentHome,
executionTargetIsRemote,
executionCwd: effectiveExecutionCwd,
});
remoteRuntimeRootDir = preparedExecutionTargetRuntime.runtimeRootDir;
const managedHome = adapterExecutionTargetUsesManagedHome(executionTarget);
const managedRemoteHomeDir =
managedHome && preparedExecutionTargetRuntime.runtimeRootDir
? preparedExecutionTargetRuntime.runtimeRootDir
: null;
if (managedRemoteHomeDir) {
env.HOME = managedRemoteHomeDir;
if (paperclipBridge) {
Object.assign(env, paperclipBridge.env);
}
const remoteHomeDir =
managedRemoteHomeDir ??
(await readAdapterExecutionTargetHomeDir(runId, executionTarget, {
cwd,
env,
timeoutSec,
graceSec,
onLog,
}));
if (remoteHomeDir && preparedExecutionTargetRuntime.assetDirs.skills) {
remoteSkillsDir = path.posix.join(remoteHomeDir, ".gemini", "skills");
await runAdapterExecutionTargetShellCommand(
runId,
executionTarget,
`mkdir -p ${JSON.stringify(path.posix.dirname(remoteSkillsDir))} && rm -rf ${JSON.stringify(remoteSkillsDir)} && cp -a ${JSON.stringify(preparedExecutionTargetRuntime.assetDirs.skills)} ${JSON.stringify(remoteSkillsDir)}`,
{ cwd, env, timeoutSec, graceSec, onLog },
);
}
// Gemini CLI refuses headless runs without an auth selection persisted in
// $HOME/.gemini/settings.json ("Invalid auth method selected."); env vars
// alone (GEMINI_DEFAULT_AUTH_TYPE) do not satisfy it. With a managed HOME
// the runtime root replaces the image home, so any settings baked into the
// image are invisible -- pre-select the api-key auth whenever an API key
// is provided. Both settings schema generations are written (legacy
// selectedAuthType + current security.auth.selectedType). An existing
// settings.json (user-shipped via workspace) is left untouched.
// Only the managed HOME (the per-run runtime root) is touched: on
// non-managed remote targets remoteHomeDir is the user's real home, where
// creating files is out of scope and existing settings remain visible.
// Key presence check spans the run env AND the host process env: in the
// managed sandbox path the key never enters the adapter's run env -- it
// reaches the agent pod via the provider's per-run secret (envKeys
// passthrough from the host env), so the host env is the signal here.
const hasGeminiApiKey = Boolean(
env.GEMINI_API_KEY || env.GOOGLE_API_KEY ||
process.env.GEMINI_API_KEY || process.env.GOOGLE_API_KEY,
);
if (managedRemoteHomeDir && hasGeminiApiKey) {
const remoteSettingsPath = path.posix.join(managedRemoteHomeDir, ".gemini", "settings.json");
const authSettingsJson = JSON.stringify({
selectedAuthType: "gemini-api-key",
security: { auth: { selectedType: "gemini-api-key" } },
});
await runAdapterExecutionTargetShellCommand(
runId,
executionTarget,
`mkdir -p ${JSON.stringify(path.posix.dirname(remoteSettingsPath))} && { [ -f ${JSON.stringify(remoteSettingsPath)} ] || printf '%s' ${JSON.stringify(authSettingsJson)} > ${JSON.stringify(remoteSettingsPath)}; }`,
{ cwd, env, timeoutSec, graceSec, onLog },
);
}
} catch (error) {
await Promise.allSettled([
restoreRemoteWorkspace?.(),
localSkillsDir ? fs.rm(path.dirname(localSkillsDir), { recursive: true, force: true }).catch(() => undefined) : Promise.resolve(),
]);
throw error;
}
}
const runtimeExecutionTarget = overrideAdapterExecutionTargetRemoteCwd(executionTarget, effectiveExecutionCwd);
if (executionTargetIsRemote && adapterExecutionTargetUsesPaperclipBridge(executionTarget)) {
paperclipBridge = await startAdapterExecutionTargetPaperclipBridge({
runId,
target: runtimeExecutionTarget,
enableSandboxDuplexBridge: adapterExecutionTargetEnablesSandboxDuplexBridge(runtimeExecutionTarget),
duplexObservabilityRecorder: adapterExecutionTargetDuplexObservabilityRecorder(runtimeExecutionTarget),
runtimeRootDir: remoteRuntimeRootDir,
adapterKey: "gemini",
timeoutSec,
hostApiToken: env.PAPERCLIP_API_KEY,
onLog,
});
if (paperclipBridge) {
Object.assign(env, paperclipBridge.env);
}
}
const runtimeSessionParams = parseObject(runtime.sessionParams);
const runtimeSessionId = asString(runtimeSessionParams.sessionId, runtime.sessionId ?? "");
const runtimeSessionCwd = asString(runtimeSessionParams.cwd, "");
const runtimeRemoteExecution = parseObject(runtimeSessionParams.remoteExecution);
const canResumeSession =
runtimeSessionId.length > 0 &&
(runtimeSessionCwd.length === 0 || path.resolve(runtimeSessionCwd) === path.resolve(effectiveExecutionCwd)) &&
adapterExecutionTargetSessionMatches(runtimeRemoteExecution, runtimeExecutionTarget);
const sessionId = canResumeSession ? runtimeSessionId : null;
if (executionTargetIsRemote && runtimeSessionId && !canResumeSession) {
await onLog(
"stdout",
`[paperclip] Gemini session "${runtimeSessionId}" does not match the current remote execution identity and will not be resumed in "${effectiveExecutionCwd}". Starting a fresh remote session.\n`,
);
} else if (runtimeSessionId && !canResumeSession) {
await onLog(
"stdout",
`[paperclip] Gemini session "${runtimeSessionId}" was saved for cwd "${runtimeSessionCwd}" and will not be resumed in "${effectiveExecutionCwd}".\n`,
);
}
const instructionsFilePath = asString(config.instructionsFilePath, "").trim();
const instructionsDir = instructionsFilePath ? `${path.dirname(instructionsFilePath)}/` : "";
let instructionsPrefix = "";
if (instructionsFilePath) {
try {
const instructionsContents = await fs.readFile(instructionsFilePath, "utf8");
instructionsPrefix =
`${instructionsContents}\n\n` +
`The above agent instructions were loaded from ${instructionsFilePath}. ` +
`Resolve any relative file references from ${instructionsDir}.\n\n`;
} catch (err) {
const reason = err instanceof Error ? err.message : String(err);
const runtimeSessionParams = parseObject(runtime.sessionParams);
const runtimeSessionId = asString(runtimeSessionParams.sessionId, runtime.sessionId ?? "");
const runtimeSessionCwd = asString(runtimeSessionParams.cwd, "");
const runtimeRemoteExecution = parseObject(runtimeSessionParams.remoteExecution);
const canResumeSession =
runtimeSessionId.length > 0 &&
(runtimeSessionCwd.length === 0 || path.resolve(runtimeSessionCwd) === path.resolve(effectiveExecutionCwd)) &&
adapterExecutionTargetSessionMatches(runtimeRemoteExecution, runtimeExecutionTarget);
const sessionId = canResumeSession ? runtimeSessionId : null;
if (executionTargetIsRemote && runtimeSessionId && !canResumeSession) {
await onLog(
"stdout",
`[paperclip] Warning: could not read agent instructions file "${instructionsFilePath}": ${reason}\n`,
`[paperclip] Gemini session "${runtimeSessionId}" does not match the current remote execution identity and will not be resumed in "${effectiveExecutionCwd}". Starting a fresh remote session.\n`,
);
} else if (runtimeSessionId && !canResumeSession) {
await onLog(
"stdout",
`[paperclip] Gemini session "${runtimeSessionId}" was saved for cwd "${runtimeSessionCwd}" and will not be resumed in "${effectiveExecutionCwd}".\n`,
);
}
}
const commandNotes = (() => {
const notes: string[] = ["Prompt is passed to Gemini via --prompt for non-interactive execution."];
notes.push("Added --approval-mode yolo for unattended execution.");
notes.push("Set headless terminal/browser env so Gemini fails fast instead of opening interactive auth or color prompts.");
if (executionTargetIsRemote) {
notes.push("Set GEMINI_CLI_TRUST_WORKSPACE=true for remote headless execution.");
const instructionsFilePath = asString(config.instructionsFilePath, "").trim();
const instructionsDir = instructionsFilePath ? `${path.dirname(instructionsFilePath)}/` : "";
let instructionsPrefix = "";
if (instructionsFilePath) {
try {
const instructionsContents = await fs.readFile(instructionsFilePath, "utf8");
instructionsPrefix =
`${instructionsContents}\n\n` +
`The above agent instructions were loaded from ${instructionsFilePath}. ` +
`Resolve any relative file references from ${instructionsDir}.\n\n`;
} catch (err) {
const reason = err instanceof Error ? err.message : String(err);
await onLog(
"stdout",
`[paperclip] Warning: could not read agent instructions file "${instructionsFilePath}": ${reason}\n`,
);
}
}
if (!instructionsFilePath) return notes;
if (instructionsPrefix.length > 0) {
const commandNotes = (() => {
const notes: string[] = ["Prompt is passed to Gemini via --prompt for non-interactive execution."];
notes.push("Added --approval-mode yolo for unattended execution.");
notes.push("Set headless terminal/browser env so Gemini fails fast instead of opening interactive auth or color prompts.");
if (executionTargetIsRemote) {
notes.push("Set GEMINI_CLI_TRUST_WORKSPACE=true for remote headless execution.");
}
if (!instructionsFilePath) return notes;
if (instructionsPrefix.length > 0) {
notes.push(
`Loaded agent instructions from ${instructionsFilePath}`,
`Prepended instructions + path directive to prompt (relative references from ${instructionsDir}).`,
);
return notes;
}
notes.push(
`Loaded agent instructions from ${instructionsFilePath}`,
`Prepended instructions + path directive to prompt (relative references from ${instructionsDir}).`,
`Configured instructionsFilePath ${instructionsFilePath}, but file could not be read; continuing without injected instructions.`,
);
return notes;
}
notes.push(
`Configured instructionsFilePath ${instructionsFilePath}, but file could not be read; continuing without injected instructions.`,
);
return notes;
})();
})();
const bootstrapPromptTemplate = asString(config.bootstrapPromptTemplate, "");
const templateData = {
agentId: agent.id,
companyId: agent.companyId,
runId,
company: { id: agent.companyId },
agent,
run: { id: runId, source: "on_demand" },
context,
};
const buildPrompt = (resumedSession: boolean) => {
const renderedBootstrapPrompt =
!resumedSession && bootstrapPromptTemplate.trim().length > 0
? renderTemplate(bootstrapPromptTemplate, templateData).trim()
: "";
const { taskContextNote, wakePrompt } = selectPaperclipPromptSections(context, {
resumedSession,
includeCommunicationGuidance: false,
});
const shouldUseResumeDeltaPrompt = resumedSession && wakePrompt.length > 0;
const renderedPrompt = shouldUseResumeDeltaPrompt || isPaperclipRecoveryWakePayload(context.paperclipWake)
? ""
: renderTemplate(promptTemplate, templateData);
const sessionHandoffNote = asString(context.paperclipSessionHandoffMarkdown, "").trim();
const paperclipEnvNote = renderPaperclipEnvNote(env);
const apiAccessNote = renderApiAccessNote(env);
const basePrompt = joinPromptSections([
instructionsPrefix,
renderedBootstrapPrompt,
wakePrompt,
taskContextNote,
sessionHandoffNote,
paperclipEnvNote,
apiAccessNote,
renderedPrompt,
]);
return {
basePrompt,
promptMetrics: {
promptChars: basePrompt.length,
instructionsChars: instructionsPrefix.length,
bootstrapPromptChars: renderedBootstrapPrompt.length,
wakePromptChars: wakePrompt.length,
taskContextChars: taskContextNote.length,
sessionHandoffChars: sessionHandoffNote.length,
runtimeNoteChars: paperclipEnvNote.length + apiAccessNote.length,
heartbeatPromptChars: renderedPrompt.length,
},
const bootstrapPromptTemplate = asString(config.bootstrapPromptTemplate, "");
const templateData = {
agentId: agent.id,
companyId: agent.companyId,
runId,
company: { id: agent.companyId },
agent,
run: { id: runId, source: "on_demand" },
context,
};
};
const buildArgs = (resumeSessionId: string | null, prompt: string) => {
const args = ["--output-format", "stream-json"];
if (resumeSessionId) args.push("--resume", resumeSessionId);
if (model && model !== DEFAULT_GEMINI_LOCAL_MODEL) args.push("--model", model);
args.push("--approval-mode", "yolo");
if (sandbox) {
args.push("--sandbox");
} else {
args.push("--sandbox=none");
}
if (extraArgs.length > 0) args.push(...extraArgs);
args.push("--prompt", prompt);
return args;
};
const runAttempt = async (resumeSessionId: string | null) => {
await hydrateFreshSessionHandoff(ctx, { resumedSession: Boolean(resumeSessionId) });
const { basePrompt, promptMetrics } = buildPrompt(Boolean(resumeSessionId));
const prompt = joinPromptSections([
selectInitialCommunicationGuidance(context, { resumedSession: Boolean(resumeSessionId) }),
basePrompt,
]);
const args = buildArgs(resumeSessionId, prompt);
const invocationEnv = buildGeminiHeadlessEnv(env);
const invocationRuntimeEnv = buildGeminiRuntimeEnv(env);
const loggedEnv = buildInvocationEnvForLogs(invocationEnv, {
runtimeEnv: invocationRuntimeEnv,
includeRuntimeKeys: ["HOME"],
resolvedCommand,
});
if (onMeta) {
await onMeta({
adapterType: "gemini_local",
command: resolvedCommand,
cwd: effectiveExecutionCwd,
commandNotes,
commandArgs: args.map((value, index) => (
index === args.length - 1 ? `<prompt ${prompt.length} chars>` : value
)),
env: loggedEnv,
prompt,
promptMetrics: { ...promptMetrics, promptChars: prompt.length },
context,
const buildPrompt = (resumedSession: boolean) => {
const renderedBootstrapPrompt =
!resumedSession && bootstrapPromptTemplate.trim().length > 0
? renderTemplate(bootstrapPromptTemplate, templateData).trim()
: "";
const { taskContextNote, wakePrompt } = selectPaperclipPromptSections(context, {
resumedSession,
includeCommunicationGuidance: false,
});
}
const shouldUseResumeDeltaPrompt = resumedSession && wakePrompt.length > 0;
const renderedPrompt = shouldUseResumeDeltaPrompt || isPaperclipRecoveryWakePayload(context.paperclipWake)
? ""
: renderTemplate(promptTemplate, templateData);
const sessionHandoffNote = asString(context.paperclipSessionHandoffMarkdown, "").trim();
const paperclipEnvNote = renderPaperclipEnvNote(env);
const apiAccessNote = renderApiAccessNote(env);
const basePrompt = joinPromptSections([
instructionsPrefix,
renderedBootstrapPrompt,
wakePrompt,
taskContextNote,
sessionHandoffNote,
paperclipEnvNote,
apiAccessNote,
renderedPrompt,
]);
return {
basePrompt,
promptMetrics: {
promptChars: basePrompt.length,
instructionsChars: instructionsPrefix.length,
bootstrapPromptChars: renderedBootstrapPrompt.length,
wakePromptChars: wakePrompt.length,
taskContextChars: taskContextNote.length,
sessionHandoffChars: sessionHandoffNote.length,
runtimeNoteChars: paperclipEnvNote.length + apiAccessNote.length,
heartbeatPromptChars: renderedPrompt.length,
},
};
};
const buildArgs = (resumeSessionId: string | null, prompt: string) => {
const args = ["--output-format", "stream-json"];
if (resumeSessionId) args.push("--resume", resumeSessionId);
if (model && model !== DEFAULT_GEMINI_LOCAL_MODEL) args.push("--model", model);
args.push("--approval-mode", "yolo");
if (sandbox) {
args.push("--sandbox");
} else {
args.push("--sandbox=none");
}
if (extraArgs.length > 0) args.push(...extraArgs);
args.push("--prompt", prompt);
return args;
};
const runAttempt = async (resumeSessionId: string | null) => {
await hydrateFreshSessionHandoff(ctx, { resumedSession: Boolean(resumeSessionId) });
const { basePrompt, promptMetrics } = buildPrompt(Boolean(resumeSessionId));
const prompt = joinPromptSections([
selectInitialCommunicationGuidance(context, { resumedSession: Boolean(resumeSessionId) }),
basePrompt,
]);
const args = buildArgs(resumeSessionId, prompt);
const invocationEnv = buildGeminiHeadlessEnv(env);
const invocationRuntimeEnv = buildGeminiRuntimeEnv(env);
const loggedEnv = buildInvocationEnvForLogs(invocationEnv, {
runtimeEnv: invocationRuntimeEnv,
includeRuntimeKeys: ["HOME"],
resolvedCommand,
});
if (onMeta) {
await onMeta({
adapterType: "gemini_local",
command: resolvedCommand,
cwd: effectiveExecutionCwd,
commandNotes,
commandArgs: args.map((value, index) => (
index === args.length - 1 ? `<prompt ${prompt.length} chars>` : value
)),
env: loggedEnv,
prompt,
promptMetrics: { ...promptMetrics, promptChars: prompt.length },
context,
});
}
const consumeAccounting = createGeminiJsonlParser();
const accountingLog = createUsageCheckpointLog(onLog, ctx.onUsage, stdout => {
const parsed = consumeAccounting(stdout);
return { usage: parsed.usage, costUsd: parsed.costUsd, usageBasis: "per_run", provider: "google", biller: "google", billingType, model, complete: parsed.resultEvent !== null };
});
const proc = await runAdapterExecutionTargetProcess(runId, runtimeExecutionTarget, command, args, {
onProcessStopped: providerStop.beginInvocation(),
cwd,
env: invocationEnv,
timeoutSec,
graceSec,
onSpawn,
onRuntimeProgress: ctx.onRuntimeProgress,
onLog: accountingLog,
runLogTail: paperclipBridge?.runLogTail,
settleRunDisposition: paperclipBridge?.settleRunDisposition,
});
await accountingLog.flush();
return {
proc,
parsed: parseGeminiJsonl(proc.stdout),
const consumeAccounting = createGeminiJsonlParser();
const accountingLog = createUsageCheckpointLog(onLog, ctx.onUsage, stdout => {
const parsed = consumeAccounting(stdout);
return { usage: parsed.usage, costUsd: parsed.costUsd, usageBasis: "per_run", provider: "google", biller: "google", billingType, model, complete: parsed.resultEvent !== null };
});
const proc = await runAdapterExecutionTargetProcess(runId, runtimeExecutionTarget, command, args, {
onProcessStopped: providerStop.beginInvocation(),
cwd,
env: invocationEnv,
timeoutSec,
graceSec,
onSpawn,
onRuntimeProgress: ctx.onRuntimeProgress,
onLog: accountingLog,
runLogTail: paperclipBridge?.runLogTail,
settleRunDisposition: paperclipBridge?.settleRunDisposition,
});
await accountingLog.flush();
return {
proc,
parsed: parseGeminiJsonl(proc.stdout),
};
};
};
const toResult = (
attempt: {
proc: {
exitCode: number | null;
signal: string | null;
timedOut: boolean;
stdout: string;
stderr: string;
errorCode?: string | null;
};
parsed: ReturnType<typeof parseGeminiJsonl>;
},
clearSessionOnMissingSession = false,
isRetry = false,
): AdapterExecutionResult => {
const authMeta = detectGeminiAuthRequired({
parsed: attempt.parsed.resultEvent,
stdout: attempt.proc.stdout,
stderr: attempt.proc.stderr,
});
const networkUnavailable = isGeminiTransientNetworkError(attempt.proc.stdout, attempt.proc.stderr);
if (attempt.proc.timedOut) {
return {
exitCode: attempt.proc.exitCode,
signal: attempt.proc.signal,
timedOut: true,
usageComplete: attempt.parsed.resultEvent !== null,
usage: attempt.parsed.usage,
usageBasis: "per_run",
provider: "google",
biller: "google",
model,
billingType,
costUsd: attempt.parsed.costUsd,
errorMessage: `Timed out after ${timeoutSec}s`,
errorCode: authMeta.requiresAuth
? "gemini_auth_required"
: networkUnavailable
? "gemini_network_unavailable"
: null,
clearSession: clearSessionOnMissingSession,
};
}
const parsedError = typeof attempt.parsed.errorMessage === "string" ? attempt.parsed.errorMessage.trim() : "";
const stderrLine = firstNonEmptyLine(attempt.proc.stderr);
const structuredFailure = attempt.parsed.resultEvent
? describeGeminiFailure(attempt.parsed.resultEvent)
: null;
const fallbackErrorMessage =
parsedError ||
structuredFailure ||
stderrLine ||
`Gemini exited with code ${attempt.proc.exitCode ?? -1}`;
const failed = (attempt.proc.exitCode ?? 0) !== 0;
const clearSessionForTurnLimit = isGeminiTurnLimitResult(
attempt.parsed.resultEvent,
attempt.proc.exitCode,
);
const toResult = (
attempt: {
proc: {
exitCode: number | null;
signal: string | null;
timedOut: boolean;
stdout: string;
stderr: string;
errorCode?: string | null;
// On retry, don't fall back to old session ID — the old session was stale
const canFallbackToRuntimeSession = !isRetry;
const resolvedSessionId = attempt.parsed.sessionId
?? (canFallbackToRuntimeSession ? (runtimeSessionId ?? runtime.sessionId ?? null) : null);
const resolvedSessionParams = resolvedSessionId
? ({
sessionId: resolvedSessionId,
cwd: effectiveExecutionCwd,
...(workspaceId ? { workspaceId } : {}),
...(workspaceRepoUrl ? { repoUrl: workspaceRepoUrl } : {}),
...(workspaceRepoRef ? { repoRef: workspaceRepoRef } : {}),
...(executionTargetIsRemote
? {
remoteExecution: adapterExecutionTargetSessionIdentity(runtimeExecutionTarget),
}
: {}),
} as Record<string, unknown>)
: null;
const resultJson: Record<string, unknown> = {
...(attempt.parsed.resultEvent ?? {
stdout: attempt.proc.stdout,
stderr: attempt.proc.stderr,
}),
...(failed && clearSessionForTurnLimit ? { stopReason: "max_turns_exhausted" } : {}),
};
parsed: ReturnType<typeof parseGeminiJsonl>;
},
clearSessionOnMissingSession = false,
isRetry = false,
): AdapterExecutionResult => {
const authMeta = detectGeminiAuthRequired({
parsed: attempt.parsed.resultEvent,
stdout: attempt.proc.stdout,
stderr: attempt.proc.stderr,
});
const networkUnavailable = isGeminiTransientNetworkError(attempt.proc.stdout, attempt.proc.stderr);
if (attempt.proc.timedOut) {
return {
exitCode: attempt.proc.exitCode,
signal: attempt.proc.signal,
timedOut: true,
timedOut: false,
usageComplete: attempt.parsed.resultEvent !== null,
usage: attempt.parsed.usage,
usageBasis: "per_run",
provider: "google",
biller: "google",
model,
billingType,
costUsd: attempt.parsed.costUsd,
errorMessage: `Timed out after ${timeoutSec}s`,
errorCode: authMeta.requiresAuth
usageBasis: "per_run",
errorMessage: failed ? fallbackErrorMessage : null,
// Forward the transport-level error code from the run-disposition seam
// first. A lost duplex control channel surfaces the typed
// `duplex_channel_lost` code before any provider classification.
errorCode: attempt.proc.errorCode
? attempt.proc.errorCode
: failed && authMeta.requiresAuth
? "gemini_auth_required"
: networkUnavailable
? "gemini_network_unavailable"
: null,
clearSession: clearSessionOnMissingSession,
};
}
const parsedError = typeof attempt.parsed.errorMessage === "string" ? attempt.parsed.errorMessage.trim() : "";
const stderrLine = firstNonEmptyLine(attempt.proc.stderr);
const structuredFailure = attempt.parsed.resultEvent
? describeGeminiFailure(attempt.parsed.resultEvent)
: null;
const fallbackErrorMessage =
parsedError ||
structuredFailure ||
stderrLine ||
`Gemini exited with code ${attempt.proc.exitCode ?? -1}`;
const failed = (attempt.proc.exitCode ?? 0) !== 0;
const clearSessionForTurnLimit = isGeminiTurnLimitResult(
attempt.parsed.resultEvent,
attempt.proc.exitCode,
);
// On retry, don't fall back to old session ID — the old session was stale
const canFallbackToRuntimeSession = !isRetry;
const resolvedSessionId = attempt.parsed.sessionId
?? (canFallbackToRuntimeSession ? (runtimeSessionId ?? runtime.sessionId ?? null) : null);
const resolvedSessionParams = resolvedSessionId
? ({
: failed && clearSessionForTurnLimit
? "max_turns_exhausted"
: failed && networkUnavailable
? "gemini_network_unavailable"
: null,
usage: attempt.parsed.usage,
sessionId: resolvedSessionId,
cwd: effectiveExecutionCwd,
...(workspaceId ? { workspaceId } : {}),
...(workspaceRepoUrl ? { repoUrl: workspaceRepoUrl } : {}),
...(workspaceRepoRef ? { repoRef: workspaceRepoRef } : {}),
...(executionTargetIsRemote
? {
remoteExecution: adapterExecutionTargetSessionIdentity(runtimeExecutionTarget),
}
: {}),
} as Record<string, unknown>)
: null;
const resultJson: Record<string, unknown> = {
...(attempt.parsed.resultEvent ?? {
stdout: attempt.proc.stdout,
stderr: attempt.proc.stderr,
}),
...(failed && clearSessionForTurnLimit ? { stopReason: "max_turns_exhausted" } : {}),
sessionParams: resolvedSessionParams,
sessionDisplayId: resolvedSessionId,
provider: "google",
biller: "google",
model,
billingType,
costUsd: attempt.parsed.costUsd,
resultJson,
summary: attempt.parsed.summary,
question: attempt.parsed.question,
clearSession: clearSessionForTurnLimit || Boolean(clearSessionOnMissingSession && !resolvedSessionId),
};
};
return {
exitCode: attempt.proc.exitCode,
signal: attempt.proc.signal,
timedOut: false,
usageComplete: attempt.parsed.resultEvent !== null,
usageBasis: "per_run",
errorMessage: failed ? fallbackErrorMessage : null,
// Forward the transport-level error code from the run-disposition seam
// first. A lost duplex control channel surfaces the typed
// `duplex_channel_lost` code before any provider classification.
errorCode: attempt.proc.errorCode
? attempt.proc.errorCode
: failed && authMeta.requiresAuth
? "gemini_auth_required"
: failed && clearSessionForTurnLimit
? "max_turns_exhausted"
: failed && networkUnavailable
? "gemini_network_unavailable"
: null,
usage: attempt.parsed.usage,
sessionId: resolvedSessionId,
sessionParams: resolvedSessionParams,
sessionDisplayId: resolvedSessionId,
provider: "google",
biller: "google",
model,
billingType,
costUsd: attempt.parsed.costUsd,
resultJson,
summary: attempt.parsed.summary,
question: attempt.parsed.question,
clearSession: clearSessionForTurnLimit || Boolean(clearSessionOnMissingSession && !resolvedSessionId),
};
};
try {
const initial = await runAttempt(sessionId);
if (
sessionId &&
@@ -64,7 +64,10 @@ vi.mock("@paperclipai/adapter-utils/execution-target", () => ({
prepareAdapterExecutionTargetRuntime: (...args: unknown[]) =>
(mocks.prepareRuntimeMock as (...args: unknown[]) => unknown)(...args),
readAdapterExecutionTarget: (input: { executionTarget?: unknown }) => input.executionTarget ??
(mocks.state.isRemote ? { kind: "remote", transport: "ssh" } : { kind: "local" }),
(mocks.state.isRemote ? { kind: "remote", transport: "ssh", remoteCwd: "/remote/workspace", spec: {
host: "fixture.invalid", port: 22, username: "fixture", remoteCwd: "/remote/workspace", remoteWorkspacePath: "/remote/workspace",
privateKey: null, knownHosts: null, strictHostKeyChecking: true,
} } : { kind: "local" }),
resolveAdapterExecutionTargetCommandForLogs: (...args: unknown[]) =>
(mocks.resolveCommandForLogsMock as (...args: unknown[]) => unknown)(...args),
resolveAdapterExecutionTargetTimeoutSec: (_target: unknown, timeoutSec: number) => timeoutSec,
@@ -6,6 +6,7 @@ import path from "node:path";
import { fileURLToPath } from "node:url";
import type { AdapterExecutionContext, AdapterExecutionResult } from "@paperclipai/adapter-utils";
import {
managedRemoteHomeEnvironment,
adapterExecutionTargetIsRemote,
adapterExecutionTargetRemoteCwd,
adapterExecutionTargetSessionIdentity,
@@ -254,6 +255,7 @@ async function executeTurn(ctx: AdapterExecutionContext): Promise<AdapterExecuti
legacyRemoteExecution: ctx.executionTransport?.remoteExecution,
});
const executionTargetIsRemote = adapterExecutionTargetIsRemote(executionTarget);
const useSshHostAuth = executionTarget?.kind === "remote" && executionTarget.transport === "ssh" && executionTarget.spec.useHostAuth === true;
const promptTemplate = asString(
config.promptTemplate,
@@ -377,7 +379,7 @@ async function executeTurn(ctx: AdapterExecutionContext): Promise<AdapterExecuti
config.managedAiConnection ? env : { ...process.env, ...env },
"XAI_API_KEY",
);
if (isGrokSubscriptionMode) {
if (isGrokSubscriptionMode && !useSshHostAuth) {
const pinManagedHome =
executionTargetIsRemote ||
Boolean(config.managedAiConnection) ||
@@ -413,10 +415,11 @@ async function executeTurn(ctx: AdapterExecutionContext): Promise<AdapterExecuti
// temp dir and ship THAT as the `home` asset, the same curated-snapshot
// approach the Codex adapter uses. Subscription mode only: an API-key
// run authenticates from the environment variable and needs no home.
if (isGrokSubscriptionMode) {
if (isGrokSubscriptionMode && !useSshHostAuth) {
stagedGrokHomeDir = await stageGrokHomeForSync(hostGrokHome, { runId });
}
const preparedExecutionTargetRuntime = await prepareAdapterExecutionTargetRuntime({
privateRuntime: Boolean(config.managedAiConnection),
runId,
target: executionTarget,
adapterKey: "grok",
@@ -471,7 +474,8 @@ async function executeTurn(ctx: AdapterExecutionContext): Promise<AdapterExecuti
// Set GROK_HOME after the refresh above, so the refresh cannot overwrite
// it. The fixed fallback path mirrors `prepareAdapterExecutionTargetRuntime`'s
// own `home` asset layout, in case `assetDirs.home` is absent.
if (isGrokSubscriptionMode) {
if (executionTarget?.kind === "remote" && executionTarget.transport === "ssh" && executionTarget.spec.useHostAuth === false && config.managedAiConnection && preparedExecutionTargetRuntime.runtimeRootDir) Object.assign(env, managedRemoteHomeEnvironment(preparedExecutionTargetRuntime.runtimeRootDir));
if (isGrokSubscriptionMode && !useSshHostAuth) {
env.GROK_HOME =
preparedExecutionTargetRuntime.assetDirs.home ??
path.posix.join(effectiveExecutionCwd, ".paperclip-runtime", "grok", "home");
+369 -365
View File
@@ -5,6 +5,7 @@ import path from "node:path";
import { fileURLToPath } from "node:url";
import type { AdapterExecutionContext, AdapterExecutionResult } from "@paperclipai/adapter-utils";
import {
managedRemoteHomeEnvironment,
adapterExecutionTargetIsRemote,
adapterExecutionTargetRemoteCwd,
overrideAdapterExecutionTargetRemoteCwd,
@@ -340,408 +341,411 @@ export async function execute(ctx: AdapterExecutionContext): Promise<AdapterExec
let remoteRuntimeRootDir: string | null = null;
let paperclipBridge: Awaited<ReturnType<typeof startAdapterExecutionTargetPaperclipBridge>> = null;
if (executionTargetIsRemote) {
try {
localSkillsDir = await buildKimiSkillsDir(config);
await onLog(
"stdout",
`[paperclip] Syncing workspace and Kimi runtime assets to ${describeAdapterExecutionTarget(executionTarget)}.\n`,
);
const preparedExecutionTargetRuntime = await prepareAdapterExecutionTargetRuntime({
try {
if (executionTargetIsRemote) {
try {
localSkillsDir = await buildKimiSkillsDir(config);
await onLog(
"stdout",
`[paperclip] Syncing workspace and Kimi runtime assets to ${describeAdapterExecutionTarget(executionTarget)}.\n`,
);
const preparedExecutionTargetRuntime = await prepareAdapterExecutionTargetRuntime({
privateRuntime: Boolean(config.managedAiConnection),
runId,
target: executionTarget,
adapterKey: "kimi",
timeoutSec,
workspaceLocalDir: cwd,
installCommand: SANDBOX_INSTALL_COMMAND,
detectCommand: command,
onProgress: (line) => onLog("stdout", line),
onRuntimeProgress: ctx.onRuntimeProgress,
assets: [{
key: "skills",
localDir: localSkillsDir,
followSymlinks: true,
}],
});
restoreRemoteWorkspace = () =>
preparedExecutionTargetRuntime.restoreWorkspace((line) => onLog("stdout", line));
effectiveExecutionCwd = preparedExecutionTargetRuntime.workspaceRemoteDir ?? effectiveExecutionCwd;
refreshPaperclipWorkspaceEnvForExecution({
env,
envConfig,
workspaceCwd: effectiveWorkspaceCwd,
workspaceSource,
workspaceId,
workspaceRepoUrl,
workspaceRepoRef,
workspaceHints,
agentHome,
executionTargetIsRemote,
executionCwd: effectiveExecutionCwd,
});
remoteRuntimeRootDir = preparedExecutionTargetRuntime.runtimeRootDir;
if (executionTarget?.kind === "remote" && executionTarget.transport === "ssh" && executionTarget.spec.useHostAuth === false && config.managedAiConnection && remoteRuntimeRootDir) Object.assign(env, managedRemoteHomeEnvironment(remoteRuntimeRootDir));
const managedHome = adapterExecutionTargetUsesManagedHome(executionTarget, Boolean(config.managedAiConnection));
const managedRemoteHomeDir =
managedHome && preparedExecutionTargetRuntime.runtimeRootDir
? preparedExecutionTargetRuntime.runtimeRootDir
: null;
if (managedRemoteHomeDir) {
env.HOME = managedRemoteHomeDir;
}
// Deliver the synced skills snapshot via --skills-dir (see buildArgs)
// from its isolated per-run location instead of copying it over the
// shared $KIMI_CODE_HOME/skills home. Overwriting the shared home would
// delete Kimi skills installed by the operator or other agents that
// Paperclip does not own.
if (desiredKimiSkillNames.length > 0 && preparedExecutionTargetRuntime.assetDirs.skills) {
remoteSkillsDir = preparedExecutionTargetRuntime.assetDirs.skills;
}
} catch (error) {
await Promise.allSettled([
restoreRemoteWorkspace?.(),
localSkillsDir ? fs.rm(path.dirname(localSkillsDir), { recursive: true, force: true }).catch(() => undefined) : Promise.resolve(),
]);
restoreRemoteWorkspace = null;
throw error;
}
}
const runtimeExecutionTarget = overrideAdapterExecutionTargetRemoteCwd(executionTarget, effectiveExecutionCwd);
if (executionTargetIsRemote && adapterExecutionTargetUsesPaperclipBridge(executionTarget)) {
paperclipBridge = await startAdapterExecutionTargetPaperclipBridge({
runId,
target: executionTarget,
target: runtimeExecutionTarget,
runtimeRootDir: remoteRuntimeRootDir,
adapterKey: "kimi",
timeoutSec,
workspaceLocalDir: cwd,
installCommand: SANDBOX_INSTALL_COMMAND,
detectCommand: command,
onProgress: (line) => onLog("stdout", line),
onRuntimeProgress: ctx.onRuntimeProgress,
assets: [{
key: "skills",
localDir: localSkillsDir,
followSymlinks: true,
}],
hostApiToken: env.PAPERCLIP_API_KEY,
onLog,
});
restoreRemoteWorkspace = () =>
preparedExecutionTargetRuntime.restoreWorkspace((line) => onLog("stdout", line));
effectiveExecutionCwd = preparedExecutionTargetRuntime.workspaceRemoteDir ?? effectiveExecutionCwd;
refreshPaperclipWorkspaceEnvForExecution({
env,
envConfig,
workspaceCwd: effectiveWorkspaceCwd,
workspaceSource,
workspaceId,
workspaceRepoUrl,
workspaceRepoRef,
workspaceHints,
agentHome,
executionTargetIsRemote,
executionCwd: effectiveExecutionCwd,
});
remoteRuntimeRootDir = preparedExecutionTargetRuntime.runtimeRootDir;
const managedHome = adapterExecutionTargetUsesManagedHome(executionTarget);
const managedRemoteHomeDir =
managedHome && preparedExecutionTargetRuntime.runtimeRootDir
? preparedExecutionTargetRuntime.runtimeRootDir
: null;
if (managedRemoteHomeDir) {
env.HOME = managedRemoteHomeDir;
if (paperclipBridge) {
Object.assign(env, paperclipBridge.env);
}
// Deliver the synced skills snapshot via --skills-dir (see buildArgs)
// from its isolated per-run location instead of copying it over the
// shared $KIMI_CODE_HOME/skills home. Overwriting the shared home would
// delete Kimi skills installed by the operator or other agents that
// Paperclip does not own.
if (desiredKimiSkillNames.length > 0 && preparedExecutionTargetRuntime.assetDirs.skills) {
remoteSkillsDir = preparedExecutionTargetRuntime.assetDirs.skills;
}
} catch (error) {
await Promise.allSettled([
restoreRemoteWorkspace?.(),
localSkillsDir ? fs.rm(path.dirname(localSkillsDir), { recursive: true, force: true }).catch(() => undefined) : Promise.resolve(),
]);
throw error;
}
}
const runtimeExecutionTarget = overrideAdapterExecutionTargetRemoteCwd(executionTarget, effectiveExecutionCwd);
if (executionTargetIsRemote && adapterExecutionTargetUsesPaperclipBridge(executionTarget)) {
paperclipBridge = await startAdapterExecutionTargetPaperclipBridge({
runId,
target: runtimeExecutionTarget,
runtimeRootDir: remoteRuntimeRootDir,
adapterKey: "kimi",
timeoutSec,
hostApiToken: env.PAPERCLIP_API_KEY,
onLog,
});
if (paperclipBridge) {
Object.assign(env, paperclipBridge.env);
// Local runs deliver desired skills via `--skills-dir` (see buildArgs) from a
// dedicated per-run directory, rather than symlinking into the user's
// ~/.kimi-code/skills home. This keeps skill loading reliable and isolated
// without polluting the operator's Kimi install. Remote runs sync skills into
// the remote skills home above, so this only applies to local execution.
if (!executionTargetIsRemote && desiredKimiSkillNames.length > 0) {
localSkillsDir = await buildKimiSkillsDir(config);
await onLog(
"stderr",
`[paperclip] Prepared ${desiredKimiSkillNames.length} Kimi skill(s) for --skills-dir delivery.\n`,
);
}
}
// Local runs deliver desired skills via `--skills-dir` (see buildArgs) from a
// dedicated per-run directory, rather than symlinking into the user's
// ~/.kimi-code/skills home. This keeps skill loading reliable and isolated
// without polluting the operator's Kimi install. Remote runs sync skills into
// the remote skills home above, so this only applies to local execution.
if (!executionTargetIsRemote && desiredKimiSkillNames.length > 0) {
localSkillsDir = await buildKimiSkillsDir(config);
await onLog(
"stderr",
`[paperclip] Prepared ${desiredKimiSkillNames.length} Kimi skill(s) for --skills-dir delivery.\n`,
);
}
const runtimeSessionParams = parseObject(runtime.sessionParams);
const runtimeSessionId = asString(runtimeSessionParams.sessionId, runtime.sessionId ?? "");
const runtimeSessionCwd = asString(runtimeSessionParams.cwd, "");
const runtimeRemoteExecution = parseObject(runtimeSessionParams.remoteExecution);
const canResumeSession =
runtimeSessionId.length > 0 &&
(runtimeSessionCwd.length === 0 || path.resolve(runtimeSessionCwd) === path.resolve(effectiveExecutionCwd)) &&
adapterExecutionTargetSessionMatches(runtimeRemoteExecution, runtimeExecutionTarget);
const sessionId = canResumeSession ? runtimeSessionId : null;
if (executionTargetIsRemote && runtimeSessionId && !canResumeSession) {
await onLog(
"stdout",
`[paperclip] Kimi session "${runtimeSessionId}" does not match the current remote execution identity and will not be resumed in "${effectiveExecutionCwd}". Starting a fresh remote session.\n`,
);
} else if (runtimeSessionId && !canResumeSession) {
await onLog(
"stdout",
`[paperclip] Kimi session "${runtimeSessionId}" was saved for cwd "${runtimeSessionCwd}" and will not be resumed in "${effectiveExecutionCwd}".\n`,
);
}
const instructionsFilePath = asString(config.instructionsFilePath, "").trim();
const instructionsDir = instructionsFilePath ? `${path.dirname(instructionsFilePath)}/` : "";
let instructionsPrefix = "";
if (instructionsFilePath) {
try {
const instructionsContents = await fs.readFile(instructionsFilePath, "utf8");
instructionsPrefix =
`${instructionsContents}\n\n` +
`The above agent instructions were loaded from ${instructionsFilePath}. ` +
`Resolve any relative file references from ${instructionsDir}. ` +
`This base directory is authoritative for sibling instruction files such as ` +
`./HEARTBEAT.md, ./SOUL.md, and ./TOOLS.md; do not resolve those from the parent agent directory.\n\n`;
} catch (err) {
const reason = err instanceof Error ? err.message : String(err);
const runtimeSessionParams = parseObject(runtime.sessionParams);
const runtimeSessionId = asString(runtimeSessionParams.sessionId, runtime.sessionId ?? "");
const runtimeSessionCwd = asString(runtimeSessionParams.cwd, "");
const runtimeRemoteExecution = parseObject(runtimeSessionParams.remoteExecution);
const canResumeSession =
runtimeSessionId.length > 0 &&
(runtimeSessionCwd.length === 0 || path.resolve(runtimeSessionCwd) === path.resolve(effectiveExecutionCwd)) &&
adapterExecutionTargetSessionMatches(runtimeRemoteExecution, runtimeExecutionTarget);
const sessionId = canResumeSession ? runtimeSessionId : null;
if (executionTargetIsRemote && runtimeSessionId && !canResumeSession) {
await onLog(
"stdout",
`[paperclip] Warning: could not read agent instructions file "${instructionsFilePath}": ${reason}\n`,
`[paperclip] Kimi session "${runtimeSessionId}" does not match the current remote execution identity and will not be resumed in "${effectiveExecutionCwd}". Starting a fresh remote session.\n`,
);
} else if (runtimeSessionId && !canResumeSession) {
await onLog(
"stdout",
`[paperclip] Kimi session "${runtimeSessionId}" was saved for cwd "${runtimeSessionCwd}" and will not be resumed in "${effectiveExecutionCwd}".\n`,
);
}
}
const commandNotes = (() => {
const notes: string[] = ["Prompt is passed to Kimi via -p for non-interactive execution."];
notes.push("Added --output-format stream-json for structured headless output.");
notes.push("Set headless env (CI=1, NO_COLOR=1, KIMI_CODE_NO_AUTO_UPDATE=1) so unattended runs skip interactive prompts and update preflight.");
if (hasNonEmptyEnvValue(env, "KIMI_MODEL_THINKING_EFFORT")) {
notes.push(`Set KIMI_MODEL_THINKING_EFFORT=${env.KIMI_MODEL_THINKING_EFFORT} for model ${model}.`);
const instructionsFilePath = asString(config.instructionsFilePath, "").trim();
const instructionsDir = instructionsFilePath ? `${path.dirname(instructionsFilePath)}/` : "";
let instructionsPrefix = "";
if (instructionsFilePath) {
try {
const instructionsContents = await fs.readFile(instructionsFilePath, "utf8");
instructionsPrefix =
`${instructionsContents}\n\n` +
`The above agent instructions were loaded from ${instructionsFilePath}. ` +
`Resolve any relative file references from ${instructionsDir}. ` +
`This base directory is authoritative for sibling instruction files such as ` +
`./HEARTBEAT.md, ./SOUL.md, and ./TOOLS.md; do not resolve those from the parent agent directory.\n\n`;
} catch (err) {
const reason = err instanceof Error ? err.message : String(err);
await onLog(
"stdout",
`[paperclip] Warning: could not read agent instructions file "${instructionsFilePath}": ${reason}\n`,
);
}
}
const effectiveSkillsDir = executionTargetIsRemote ? remoteSkillsDir : localSkillsDir;
if (effectiveSkillsDir) {
notes.push(`Loading ${desiredKimiSkillNames.length} desired skill(s) via --skills-dir ${effectiveSkillsDir}.`);
}
if (!executionTargetIsRemote && instructionsFilePath) {
notes.push(`Added --add-dir ${path.dirname(instructionsFilePath)} so sibling instruction files are readable.`);
}
if (!instructionsFilePath) return notes;
if (instructionsPrefix.length > 0) {
const commandNotes = (() => {
const notes: string[] = ["Prompt is passed to Kimi via -p for non-interactive execution."];
notes.push("Added --output-format stream-json for structured headless output.");
notes.push("Set headless env (CI=1, NO_COLOR=1, KIMI_CODE_NO_AUTO_UPDATE=1) so unattended runs skip interactive prompts and update preflight.");
if (hasNonEmptyEnvValue(env, "KIMI_MODEL_THINKING_EFFORT")) {
notes.push(`Set KIMI_MODEL_THINKING_EFFORT=${env.KIMI_MODEL_THINKING_EFFORT} for model ${model}.`);
}
const effectiveSkillsDir = executionTargetIsRemote ? remoteSkillsDir : localSkillsDir;
if (effectiveSkillsDir) {
notes.push(`Loading ${desiredKimiSkillNames.length} desired skill(s) via --skills-dir ${effectiveSkillsDir}.`);
}
if (!executionTargetIsRemote && instructionsFilePath) {
notes.push(`Added --add-dir ${path.dirname(instructionsFilePath)} so sibling instruction files are readable.`);
}
if (!instructionsFilePath) return notes;
if (instructionsPrefix.length > 0) {
notes.push(
`Loaded agent instructions from ${instructionsFilePath}`,
`Prepended instructions + path directive to prompt (relative references from ${instructionsDir}).`,
);
return notes;
}
notes.push(
`Loaded agent instructions from ${instructionsFilePath}`,
`Prepended instructions + path directive to prompt (relative references from ${instructionsDir}).`,
`Configured instructionsFilePath ${instructionsFilePath}, but file could not be read; continuing without injected instructions.`,
);
return notes;
}
notes.push(
`Configured instructionsFilePath ${instructionsFilePath}, but file could not be read; continuing without injected instructions.`,
);
return notes;
})();
})();
const bootstrapPromptTemplate = asString(config.bootstrapPromptTemplate, "");
const templateData = {
agentId: agent.id,
companyId: agent.companyId,
runId,
company: { id: agent.companyId },
agent,
run: { id: runId, source: "on_demand" },
context,
};
const sessionHandoffNote = asString(context.paperclipSessionHandoffMarkdown, "").trim();
const paperclipEnvNote = renderPaperclipEnvNote(env);
const apiAccessNote = renderApiAccessNote(env);
const buildArgs = (resumeSessionId: string | null, prompt: string) => {
const args = ["--output-format", "stream-json"];
if (resumeSessionId) args.push("-r", resumeSessionId);
if (model) args.push("-m", model);
// Make the agent instructions directory readable so Kimi can open sibling
// instruction files (./HEARTBEAT.md, ./SOUL.md, ./TOOLS.md) referenced by
// the prepended entry file. Local-only: the directory is a host path that
// is not synced to remote execution targets.
if (!executionTargetIsRemote && instructionsFilePath) {
args.push("--add-dir", path.dirname(instructionsFilePath));
}
// Load desired Paperclip skills from the dedicated per-run directory
// (local snapshot, or the synced remote snapshot) instead of the shared
// skills home. Only passed when skills are desired so unconfigured agents
// keep Kimi's default skill discovery.
const effectiveSkillsDir = executionTargetIsRemote ? remoteSkillsDir : localSkillsDir;
if (effectiveSkillsDir) {
args.push("--skills-dir", effectiveSkillsDir);
}
if (extraArgs.length > 0) args.push(...extraArgs);
args.push("-p", prompt);
return args;
};
const runAttempt = async (resumeSessionId: string | null) => {
await hydrateFreshSessionHandoff(ctx, { resumedSession: Boolean(resumeSessionId) });
const attemptSections = selectPaperclipPromptSections(context, {
resumedSession: Boolean(resumeSessionId),
includeCommunicationGuidance: false,
});
const attemptBootstrapPrompt = !resumeSessionId && bootstrapPromptTemplate.trim().length > 0
? renderTemplate(bootstrapPromptTemplate, templateData).trim()
: "";
const attemptWakePrompt = attemptSections.wakePrompt;
const attemptRenderedPrompt = Boolean(resumeSessionId) && attemptWakePrompt.length > 0
|| isPaperclipRecoveryWakePayload(context.paperclipWake)
? ""
: renderTemplate(promptTemplate, templateData);
const attemptBasePrompt = joinPromptSections([
instructionsPrefix,
attemptBootstrapPrompt,
attemptWakePrompt,
attemptSections.taskContextNote,
sessionHandoffNote,
paperclipEnvNote,
apiAccessNote,
attemptRenderedPrompt,
]);
const prompt = joinPromptSections([
selectInitialCommunicationGuidance(context, { resumedSession: Boolean(resumeSessionId) }),
attemptBasePrompt,
]);
const promptMetrics = {
promptChars: prompt.length,
instructionsChars: instructionsPrefix.length,
bootstrapPromptChars: attemptBootstrapPrompt.length,
wakePromptChars: attemptWakePrompt.length,
taskContextChars: attemptSections.taskContextNote.length,
sessionHandoffChars: sessionHandoffNote.length,
runtimeNoteChars: paperclipEnvNote.length + apiAccessNote.length,
heartbeatPromptChars: attemptRenderedPrompt.length,
const bootstrapPromptTemplate = asString(config.bootstrapPromptTemplate, "");
const templateData = {
agentId: agent.id,
companyId: agent.companyId,
runId,
company: { id: agent.companyId },
agent,
run: { id: runId, source: "on_demand" },
context,
};
const args = buildArgs(resumeSessionId, prompt);
const invocationEnv = buildKimiHeadlessEnv(env);
const invocationRuntimeEnv = buildKimiRuntimeEnv(env);
const loggedEnv = buildInvocationEnvForLogs(invocationEnv, {
runtimeEnv: invocationRuntimeEnv,
includeRuntimeKeys: ["HOME"],
resolvedCommand,
});
if (onMeta) {
await onMeta({
adapterType: "kimi_local",
command: resolvedCommand,
cwd: effectiveExecutionCwd,
commandNotes,
commandArgs: args.map((value, index) => (
index === args.length - 1 ? `<prompt ${prompt.length} chars>` : value
)),
env: loggedEnv,
prompt,
promptMetrics: { ...promptMetrics, promptChars: prompt.length },
context,
const sessionHandoffNote = asString(context.paperclipSessionHandoffMarkdown, "").trim();
const paperclipEnvNote = renderPaperclipEnvNote(env);
const apiAccessNote = renderApiAccessNote(env);
const buildArgs = (resumeSessionId: string | null, prompt: string) => {
const args = ["--output-format", "stream-json"];
if (resumeSessionId) args.push("-r", resumeSessionId);
if (model) args.push("-m", model);
// Make the agent instructions directory readable so Kimi can open sibling
// instruction files (./HEARTBEAT.md, ./SOUL.md, ./TOOLS.md) referenced by
// the prepended entry file. Local-only: the directory is a host path that
// is not synced to remote execution targets.
if (!executionTargetIsRemote && instructionsFilePath) {
args.push("--add-dir", path.dirname(instructionsFilePath));
}
// Load desired Paperclip skills from the dedicated per-run directory
// (local snapshot, or the synced remote snapshot) instead of the shared
// skills home. Only passed when skills are desired so unconfigured agents
// keep Kimi's default skill discovery.
const effectiveSkillsDir = executionTargetIsRemote ? remoteSkillsDir : localSkillsDir;
if (effectiveSkillsDir) {
args.push("--skills-dir", effectiveSkillsDir);
}
if (extraArgs.length > 0) args.push(...extraArgs);
args.push("-p", prompt);
return args;
};
const runAttempt = async (resumeSessionId: string | null) => {
await hydrateFreshSessionHandoff(ctx, { resumedSession: Boolean(resumeSessionId) });
const attemptSections = selectPaperclipPromptSections(context, {
resumedSession: Boolean(resumeSessionId),
includeCommunicationGuidance: false,
});
}
const attemptBootstrapPrompt = !resumeSessionId && bootstrapPromptTemplate.trim().length > 0
? renderTemplate(bootstrapPromptTemplate, templateData).trim()
: "";
const attemptWakePrompt = attemptSections.wakePrompt;
const attemptRenderedPrompt = Boolean(resumeSessionId) && attemptWakePrompt.length > 0
|| isPaperclipRecoveryWakePayload(context.paperclipWake)
? ""
: renderTemplate(promptTemplate, templateData);
const attemptBasePrompt = joinPromptSections([
instructionsPrefix,
attemptBootstrapPrompt,
attemptWakePrompt,
attemptSections.taskContextNote,
sessionHandoffNote,
paperclipEnvNote,
apiAccessNote,
attemptRenderedPrompt,
]);
const prompt = joinPromptSections([
selectInitialCommunicationGuidance(context, { resumedSession: Boolean(resumeSessionId) }),
attemptBasePrompt,
]);
const promptMetrics = {
promptChars: prompt.length,
instructionsChars: instructionsPrefix.length,
bootstrapPromptChars: attemptBootstrapPrompt.length,
wakePromptChars: attemptWakePrompt.length,
taskContextChars: attemptSections.taskContextNote.length,
sessionHandoffChars: sessionHandoffNote.length,
runtimeNoteChars: paperclipEnvNote.length + apiAccessNote.length,
heartbeatPromptChars: attemptRenderedPrompt.length,
};
const args = buildArgs(resumeSessionId, prompt);
const invocationEnv = buildKimiHeadlessEnv(env);
const invocationRuntimeEnv = buildKimiRuntimeEnv(env);
const loggedEnv = buildInvocationEnvForLogs(invocationEnv, {
runtimeEnv: invocationRuntimeEnv,
includeRuntimeKeys: ["HOME"],
resolvedCommand,
});
if (onMeta) {
await onMeta({
adapterType: "kimi_local",
command: resolvedCommand,
cwd: effectiveExecutionCwd,
commandNotes,
commandArgs: args.map((value, index) => (
index === args.length - 1 ? `<prompt ${prompt.length} chars>` : value
)),
env: loggedEnv,
prompt,
promptMetrics: { ...promptMetrics, promptChars: prompt.length },
context,
});
}
const eventForwarder = createKimiEventForwardingLog(onLog, onEvent);
const proc = await runAdapterExecutionTargetProcess(runId, runtimeExecutionTarget, command, args, {
onProcessStopped: providerStop.beginInvocation(),
cwd,
env: invocationEnv,
timeoutSec,
graceSec,
onSpawn,
onRuntimeProgress: ctx.onRuntimeProgress,
onLog: eventForwarder.log,
runLogTail: paperclipBridge?.runLogTail,
settleRunDisposition: paperclipBridge?.settleRunDisposition,
});
await eventForwarder.flush();
return {
proc,
parsed: parseKimiJsonl(proc.stdout),
const eventForwarder = createKimiEventForwardingLog(onLog, onEvent);
const proc = await runAdapterExecutionTargetProcess(runId, runtimeExecutionTarget, command, args, {
onProcessStopped: providerStop.beginInvocation(),
cwd,
env: invocationEnv,
timeoutSec,
graceSec,
onSpawn,
onRuntimeProgress: ctx.onRuntimeProgress,
onLog: eventForwarder.log,
runLogTail: paperclipBridge?.runLogTail,
settleRunDisposition: paperclipBridge?.settleRunDisposition,
});
await eventForwarder.flush();
return {
proc,
parsed: parseKimiJsonl(proc.stdout),
};
};
};
const toResult = (
attempt: {
proc: {
exitCode: number | null;
signal: string | null;
timedOut: boolean;
stdout: string;
stderr: string;
errorCode?: string | null;
const toResult = (
attempt: {
proc: {
exitCode: number | null;
signal: string | null;
timedOut: boolean;
stdout: string;
stderr: string;
errorCode?: string | null;
};
parsed: ReturnType<typeof parseKimiJsonl>;
},
clearSessionOnMissingSession = false,
isRetry = false,
): AdapterExecutionResult => {
const authMeta = detectKimiAuthRequired({
stdout: attempt.proc.stdout,
stderr: attempt.proc.stderr,
});
const networkUnavailable = isKimiTransientNetworkError(attempt.proc.stdout, attempt.proc.stderr);
if (attempt.proc.timedOut) {
return {
exitCode: attempt.proc.exitCode,
signal: attempt.proc.signal,
timedOut: true,
// This stream protocol has no usage receipt to recover after exit.
// Close collection with an explicitly unknown price, never a free run.
usageComplete: true,
costStatus: "unpriced",
usageBasis: "per_run",
provider: "moonshot",
biller: "moonshot",
model: model || null,
billingType,
costUsd: null,
errorMessage: `Timed out after ${timeoutSec}s`,
errorCode: authMeta.requiresAuth
? "kimi_auth_required"
: networkUnavailable
? "kimi_network_unavailable"
: null,
clearSession: clearSessionOnMissingSession,
};
}
const parsedError = typeof attempt.parsed.errorMessage === "string" ? attempt.parsed.errorMessage.trim() : "";
const stderrLine = firstNonEmptyLine(attempt.proc.stderr);
const structuredFailure = describeKimiFailure({
errorMessage: attempt.parsed.errorMessage,
stderr: attempt.proc.stderr,
});
const fallbackErrorMessage =
parsedError ||
structuredFailure ||
stderrLine ||
(attempt.proc.signal
? `Kimi was terminated by signal ${attempt.proc.signal}`
: `Kimi exited with code ${attempt.proc.exitCode ?? -1}`);
// A null exit code means the process never exited normally (e.g. killed by
// a signal). Timeouts are handled earlier; treat any other non-zero or
// null exit as a failure so a signaled kill is never reported as success.
const failed = attempt.proc.exitCode === null || attempt.proc.exitCode !== 0;
// On retry, don't fall back to old session ID — the old session was stale
const canFallbackToRuntimeSession = !isRetry;
const resolvedSessionId = attempt.parsed.sessionId
?? (canFallbackToRuntimeSession ? (runtimeSessionId ?? runtime.sessionId ?? null) : null);
const resolvedSessionParams = resolvedSessionId
? ({
sessionId: resolvedSessionId,
cwd: effectiveExecutionCwd,
...(workspaceId ? { workspaceId } : {}),
...(workspaceRepoUrl ? { repoUrl: workspaceRepoUrl } : {}),
...(workspaceRepoRef ? { repoRef: workspaceRepoRef } : {}),
...(executionTargetIsRemote
? {
remoteExecution: adapterExecutionTargetSessionIdentity(runtimeExecutionTarget),
}
: {}),
} as Record<string, unknown>)
: null;
const resultJson: Record<string, unknown> = {
toolCalls: attempt.parsed.toolCalls,
toolResults: attempt.parsed.toolResults,
...(failed ? { stderr: attempt.proc.stderr } : {}),
};
parsed: ReturnType<typeof parseKimiJsonl>;
},
clearSessionOnMissingSession = false,
isRetry = false,
): AdapterExecutionResult => {
const authMeta = detectKimiAuthRequired({
stdout: attempt.proc.stdout,
stderr: attempt.proc.stderr,
});
const networkUnavailable = isKimiTransientNetworkError(attempt.proc.stdout, attempt.proc.stderr);
if (attempt.proc.timedOut) {
return {
exitCode: attempt.proc.exitCode,
signal: attempt.proc.signal,
timedOut: true,
// This stream protocol has no usage receipt to recover after exit.
// Close collection with an explicitly unknown price, never a free run.
timedOut: false,
usageComplete: true,
costStatus: "unpriced",
usageBasis: "per_run",
errorMessage: failed ? fallbackErrorMessage : null,
// Forward the transport-level error code from the run-disposition seam
// first. A lost duplex control channel surfaces the typed
// `duplex_channel_lost` code before any provider classification.
errorCode: attempt.proc.errorCode
? attempt.proc.errorCode
: failed && authMeta.requiresAuth
? "kimi_auth_required"
: failed && networkUnavailable
? "kimi_network_unavailable"
: null,
sessionId: resolvedSessionId,
sessionParams: resolvedSessionParams,
sessionDisplayId: resolvedSessionId,
provider: "moonshot",
biller: "moonshot",
model: model || null,
billingType,
costUsd: null,
errorMessage: `Timed out after ${timeoutSec}s`,
errorCode: authMeta.requiresAuth
? "kimi_auth_required"
: networkUnavailable
? "kimi_network_unavailable"
: null,
clearSession: clearSessionOnMissingSession,
resultJson,
summary: attempt.parsed.summary,
clearSession: Boolean(clearSessionOnMissingSession && !resolvedSessionId),
};
}
const parsedError = typeof attempt.parsed.errorMessage === "string" ? attempt.parsed.errorMessage.trim() : "";
const stderrLine = firstNonEmptyLine(attempt.proc.stderr);
const structuredFailure = describeKimiFailure({
errorMessage: attempt.parsed.errorMessage,
stderr: attempt.proc.stderr,
});
const fallbackErrorMessage =
parsedError ||
structuredFailure ||
stderrLine ||
(attempt.proc.signal
? `Kimi was terminated by signal ${attempt.proc.signal}`
: `Kimi exited with code ${attempt.proc.exitCode ?? -1}`);
// A null exit code means the process never exited normally (e.g. killed by
// a signal). Timeouts are handled earlier; treat any other non-zero or
// null exit as a failure so a signaled kill is never reported as success.
const failed = attempt.proc.exitCode === null || attempt.proc.exitCode !== 0;
// On retry, don't fall back to old session ID — the old session was stale
const canFallbackToRuntimeSession = !isRetry;
const resolvedSessionId = attempt.parsed.sessionId
?? (canFallbackToRuntimeSession ? (runtimeSessionId ?? runtime.sessionId ?? null) : null);
const resolvedSessionParams = resolvedSessionId
? ({
sessionId: resolvedSessionId,
cwd: effectiveExecutionCwd,
...(workspaceId ? { workspaceId } : {}),
...(workspaceRepoUrl ? { repoUrl: workspaceRepoUrl } : {}),
...(workspaceRepoRef ? { repoRef: workspaceRepoRef } : {}),
...(executionTargetIsRemote
? {
remoteExecution: adapterExecutionTargetSessionIdentity(runtimeExecutionTarget),
}
: {}),
} as Record<string, unknown>)
: null;
const resultJson: Record<string, unknown> = {
toolCalls: attempt.parsed.toolCalls,
toolResults: attempt.parsed.toolResults,
...(failed ? { stderr: attempt.proc.stderr } : {}),
};
return {
exitCode: attempt.proc.exitCode,
signal: attempt.proc.signal,
timedOut: false,
usageComplete: true,
costStatus: "unpriced",
usageBasis: "per_run",
errorMessage: failed ? fallbackErrorMessage : null,
// Forward the transport-level error code from the run-disposition seam
// first. A lost duplex control channel surfaces the typed
// `duplex_channel_lost` code before any provider classification.
errorCode: attempt.proc.errorCode
? attempt.proc.errorCode
: failed && authMeta.requiresAuth
? "kimi_auth_required"
: failed && networkUnavailable
? "kimi_network_unavailable"
: null,
sessionId: resolvedSessionId,
sessionParams: resolvedSessionParams,
sessionDisplayId: resolvedSessionId,
provider: "moonshot",
biller: "moonshot",
model: model || null,
billingType,
resultJson,
summary: attempt.parsed.summary,
clearSession: Boolean(clearSessionOnMissingSession && !resolvedSessionId),
};
};
try {
const initial = await runAttempt(sessionId);
if (
sessionId &&
@@ -47,8 +47,8 @@ const {
resolveCommandForLogs: vi.fn(async () => "ssh://fixture@127.0.0.1:2222/remote/workspace :: opencode"),
prepareWorkspaceForSshExecution: vi.fn(async () => ({ gitBacked: false })),
restoreWorkspaceFromSshExecution: vi.fn(async () => undefined),
runSshCommand: vi.fn(async () => ({
stdout: "/home/agent",
runSshCommand: vi.fn(async (_spec?: unknown, command?: string) => ({
stdout: command?.includes("mktemp -d") ? "/tmp/paperclip-ssh-runtime.opencode" : "/home/agent",
stderr: "",
exitCode: 0,
})),
@@ -163,6 +163,7 @@ describe("opencode remote execution", () => {
const workspaceDir = path.join(rootDir, "workspace");
const alternateWorkspaceDir = path.join(rootDir, "workspace-other");
const managedRemoteWorkspace = "/remote/workspace/.paperclip-runtime/runs/run-1/workspace";
const runtimeRoot = managed ? "/tmp/paperclip-ssh-runtime.opencode" : `${managedRemoteWorkspace}/.paperclip-runtime/opencode`;
await mkdir(workspaceDir, { recursive: true });
await mkdir(alternateWorkspaceDir, { recursive: true });
@@ -215,6 +216,7 @@ describe("opencode remote execution", () => {
},
executionTransport: {
remoteExecution: {
useHostAuth: !managed,
host: "127.0.0.1",
port: 2222,
username: "fixture",
@@ -242,10 +244,10 @@ describe("opencode remote execution", () => {
expect(prepareWorkspaceForSshExecution).toHaveBeenCalledTimes(1);
expect(syncDirectoryToSsh).toHaveBeenCalledTimes(2);
expect(syncDirectoryToSsh).toHaveBeenCalledWith(expect.objectContaining({
remoteDir: `${managedRemoteWorkspace}/.paperclip-runtime/opencode/xdgConfig`,
remoteDir: `${runtimeRoot}/xdgConfig`,
}));
expect(syncDirectoryToSsh).toHaveBeenCalledWith(expect.objectContaining({
remoteDir: `${managedRemoteWorkspace}/.paperclip-runtime/opencode/skills`,
remoteDir: `${runtimeRoot}/skills`,
followSymlinks: true,
}));
expect(runSshCommand).toHaveBeenCalledWith(
@@ -265,7 +267,7 @@ describe("opencode remote execution", () => {
// original target remoteCwd — the per-run subdirectory is layered
// underneath via XDG/runtime config rather than by switching the cwd.
expect(modelProbeCall?.[3].env.XDG_CONFIG_HOME).toBe(
`${managedRemoteWorkspace}/.paperclip-runtime/opencode/xdgConfig`,
`${runtimeRoot}/xdgConfig`,
);
expect(modelProbeCall?.[3].remoteExecution?.remoteCwd).toBe("/remote/workspace");
expect(runCall?.[2].slice(-4)).toEqual(["--dir", managedRemoteWorkspace, "--", "--dir"]);
@@ -274,7 +276,7 @@ describe("opencode remote execution", () => {
| undefined;
expect(call?.[3].env.PAPERCLIP_WORKSPACE_CWD).toBe(managedRemoteWorkspace);
if (managed) {
const home = `${managedRemoteWorkspace}/.paperclip-runtime/opencode/managed-auth/run-1`;
const home = `${runtimeRoot}/managed-auth/run-1`;
expect(call?.[3].env.HOME).toBe(home);
expect(call?.[3].env.XDG_DATA_HOME).toBe(`${home}/data`);
expect(modelProbeCall?.[3].env.XDG_DATA_HOME).toBe(`${home}/data`);
@@ -299,7 +301,7 @@ describe("opencode remote execution", () => {
]);
expect(call?.[3].env.PAPERCLIP_API_URL).toBe("http://127.0.0.1:4310");
expect(call?.[3].env.PAPERCLIP_API_BRIDGE_MODE).toBe("queue_v1");
expect(call?.[3].env.XDG_CONFIG_HOME).toBe(`${managedRemoteWorkspace}/.paperclip-runtime/opencode/xdgConfig`);
expect(call?.[3].env.XDG_CONFIG_HOME).toBe(`${runtimeRoot}/xdgConfig`);
expect(call?.[3].remoteExecution?.remoteCwd).toBe(managedRemoteWorkspace);
expect(startAdapterExecutionTargetPaperclipBridge).toHaveBeenCalledTimes(1);
expect(restoreWorkspaceFromSshExecution).toHaveBeenCalledTimes(1);
@@ -6,6 +6,7 @@ import path from "node:path";
import { fileURLToPath } from "node:url";
import { inferOpenAiCompatibleBiller, type AdapterExecutionContext, type AdapterExecutionResult } from "@paperclipai/adapter-utils";
import {
managedRemoteHomeEnvironment,
adapterExecutionTargetIsRemote,
adapterExecutionTargetRemoteCwd,
overrideAdapterExecutionTargetRemoteCwd,
@@ -388,416 +389,418 @@ export async function execute(ctx: AdapterExecutionContext): Promise<AdapterExec
let remoteRuntimeRootDir: string | null = null;
let paperclipBridge: Awaited<ReturnType<typeof startAdapterExecutionTargetPaperclipBridge>> = null;
if (executionTarget?.kind === "remote") {
localSkillsDir = await buildOpenCodeSkillsDir(config);
await onLog(
"stdout",
`[paperclip] Syncing workspace and OpenCode runtime assets to ${describeAdapterExecutionTarget(executionTarget)}.\n`,
);
const preparedExecutionTargetRuntime = await prepareAdapterExecutionTargetRuntime({
runId,
target: executionTarget,
adapterKey: "opencode",
timeoutSec,
workspaceLocalDir: cwd,
installCommand: SANDBOX_INSTALL_COMMAND,
detectCommand: command,
onProgress: (line) => onLog("stdout", line),
onRuntimeProgress: ctx.onRuntimeProgress,
assets: [
{
key: "skills",
localDir: localSkillsDir,
followSymlinks: true,
},
...(localRuntimeConfigHome
? [{
key: "xdgConfig",
localDir: localRuntimeConfigHome,
}]
: []),
],
});
restoreRemoteWorkspace = () =>
preparedExecutionTargetRuntime.restoreWorkspace((line) => onLog("stdout", line));
effectiveExecutionCwd = preparedExecutionTargetRuntime.workspaceRemoteDir ?? effectiveExecutionCwd;
refreshPaperclipWorkspaceEnvForExecution({
env: preparedRuntimeConfig.env,
envConfig,
workspaceCwd: effectiveWorkspaceCwd,
workspaceSource,
workspaceId,
workspaceRepoUrl,
workspaceRepoRef,
workspaceHints,
agentHome,
executionTargetIsRemote,
executionCwd: effectiveExecutionCwd,
});
remoteRuntimeRootDir = preparedExecutionTargetRuntime.runtimeRootDir;
const managedHome = adapterExecutionTargetUsesManagedHome(executionTarget);
if (managedHome && preparedExecutionTargetRuntime.runtimeRootDir) {
preparedRuntimeConfig.env.HOME = preparedExecutionTargetRuntime.runtimeRootDir;
}
if (localRuntimeConfigHome && preparedExecutionTargetRuntime.assetDirs.xdgConfig) {
preparedRuntimeConfig.env.XDG_CONFIG_HOME = preparedExecutionTargetRuntime.assetDirs.xdgConfig;
}
prepareManagedOpenCodeRemoteHomes({
env: preparedRuntimeConfig.env,
config,
runtimeRootDir: preparedExecutionTargetRuntime.runtimeRootDir,
runId,
configDir: preparedExecutionTargetRuntime.assetDirs.xdgConfig,
});
const remoteHomeDir = config.managedAiConnection
? preparedRuntimeConfig.env.HOME
: managedHome && preparedExecutionTargetRuntime.runtimeRootDir
? preparedExecutionTargetRuntime.runtimeRootDir
: await readAdapterExecutionTargetHomeDir(runId, executionTarget, {
cwd,
env: preparedRuntimeConfig.env,
timeoutSec,
graceSec,
onLog,
});
if (remoteHomeDir && preparedExecutionTargetRuntime.assetDirs.skills) {
const remoteSkillsDir = path.posix.join(remoteHomeDir, ".claude", "skills");
await runAdapterExecutionTargetShellCommand(
runId,
executionTarget,
`mkdir -p ${JSON.stringify(path.posix.dirname(remoteSkillsDir))} && rm -rf ${JSON.stringify(remoteSkillsDir)} && cp -a ${JSON.stringify(preparedExecutionTargetRuntime.assetDirs.skills)} ${JSON.stringify(remoteSkillsDir)}`,
{ cwd, env: preparedRuntimeConfig.env, timeoutSec, graceSec, onLog },
);
}
await ensureRemoteOpenCodeModelConfiguredAndAvailable({
runId,
executionTarget,
command,
model,
cwd,
env: preparedRuntimeConfig.env,
timeoutSec,
graceSec,
});
}
const runtimeExecutionTarget = overrideAdapterExecutionTargetRemoteCwd(executionTarget, effectiveExecutionCwd);
if (executionTargetIsRemote && adapterExecutionTargetUsesPaperclipBridge(runtimeExecutionTarget)) {
paperclipBridge = await startAdapterExecutionTargetPaperclipBridge({
runId,
target: runtimeExecutionTarget,
enableSandboxDuplexBridge: adapterExecutionTargetEnablesSandboxDuplexBridge(runtimeExecutionTarget),
duplexObservabilityRecorder: adapterExecutionTargetDuplexObservabilityRecorder(runtimeExecutionTarget),
runtimeRootDir: remoteRuntimeRootDir,
adapterKey: "opencode",
timeoutSec,
hostApiToken: preparedRuntimeConfig.env.PAPERCLIP_API_KEY,
onLog,
});
if (paperclipBridge) {
Object.assign(preparedRuntimeConfig.env, paperclipBridge.env);
loggedEnv = buildInvocationEnvForLogs(preparedRuntimeConfig.env, {
runtimeEnv: Object.fromEntries(
Object.entries(ensurePathInEnv({ ...process.env, ...preparedRuntimeConfig.env })).filter(
(entry): entry is [string, string] => typeof entry[1] === "string",
),
),
includeRuntimeKeys: ["HOME"],
resolvedCommand,
});
}
}
const runtimeSessionParams = parseObject(runtime.sessionParams);
const runtimeSessionId = asString(runtimeSessionParams.sessionId, runtime.sessionId ?? "");
const runtimeSessionCwd = asString(runtimeSessionParams.cwd, "");
const runtimeRemoteExecution = parseObject(runtimeSessionParams.remoteExecution);
const canResumeSession =
runtimeSessionId.length > 0 &&
(runtimeSessionCwd.length === 0 || path.resolve(runtimeSessionCwd) === path.resolve(effectiveExecutionCwd)) &&
adapterExecutionTargetSessionMatches(runtimeRemoteExecution, runtimeExecutionTarget);
const sessionId = canResumeSession ? runtimeSessionId : null;
if (executionTargetIsRemote && runtimeSessionId && !canResumeSession) {
await onLog(
"stdout",
`[paperclip] OpenCode session "${runtimeSessionId}" does not match the current remote execution identity and will not be resumed in "${effectiveExecutionCwd}". Starting a fresh remote session.\n`,
);
} else if (runtimeSessionId && !canResumeSession) {
await onLog(
"stdout",
`[paperclip] OpenCode session "${runtimeSessionId}" was saved for cwd "${runtimeSessionCwd}" and will not be resumed in "${effectiveExecutionCwd}".\n`,
);
}
const instructionsFilePath = asString(config.instructionsFilePath, "").trim();
const resolvedInstructionsFilePath = instructionsFilePath
? path.resolve(cwd, instructionsFilePath)
: "";
const instructionsDir = resolvedInstructionsFilePath ? `${path.dirname(resolvedInstructionsFilePath)}/` : "";
let instructionsPrefix = "";
if (resolvedInstructionsFilePath) {
try {
const instructionsContents = await fs.readFile(resolvedInstructionsFilePath, "utf8");
instructionsPrefix =
`${instructionsContents}\n\n` +
`The above agent instructions were loaded from ${resolvedInstructionsFilePath}. ` +
`Resolve any relative file references from ${instructionsDir}.\n\n`;
} catch (err) {
const reason = err instanceof Error ? err.message : String(err);
try {
if (executionTarget?.kind === "remote") {
localSkillsDir = await buildOpenCodeSkillsDir(config);
await onLog(
"stdout",
`[paperclip] Warning: could not read agent instructions file "${resolvedInstructionsFilePath}": ${reason}\n`,
`[paperclip] Syncing workspace and OpenCode runtime assets to ${describeAdapterExecutionTarget(executionTarget)}.\n`,
);
}
}
const commandNotes = (() => {
const notes = [...preparedRuntimeConfig.notes];
if (!resolvedInstructionsFilePath) return notes;
if (instructionsPrefix.length > 0) {
notes.push(`Loaded agent instructions from ${resolvedInstructionsFilePath}`);
notes.push(
`Prepended instructions + path directive to stdin prompt (relative references from ${instructionsDir}).`,
);
return notes;
}
notes.push(
`Configured instructionsFilePath ${resolvedInstructionsFilePath}, but file could not be read; continuing without injected instructions.`,
);
return notes;
})();
const bootstrapPromptTemplate = asString(config.bootstrapPromptTemplate, "");
const templateData = {
agentId: agent.id,
companyId: agent.companyId,
runId,
company: { id: agent.companyId },
agent,
run: { id: runId, source: "on_demand" },
context,
};
const buildPrompt = (resumedSession: boolean) => {
const renderedBootstrapPrompt =
!resumedSession && bootstrapPromptTemplate.trim().length > 0
? renderTemplate(bootstrapPromptTemplate, templateData).trim()
: "";
const { taskContextNote, wakePrompt } = selectPaperclipPromptSections(context, {
resumedSession,
includeCommunicationGuidance: false,
});
const shouldUseResumeDeltaPrompt = resumedSession && wakePrompt.length > 0;
const renderedPrompt = shouldUseResumeDeltaPrompt || isPaperclipRecoveryWakePayload(context.paperclipWake)
? ""
: renderTemplate(promptTemplate, templateData);
const sessionHandoffNote = asString(context.paperclipSessionHandoffMarkdown, "").trim();
const basePrompt = joinPromptSections([
instructionsPrefix,
renderedBootstrapPrompt,
wakePrompt,
taskContextNote,
sessionHandoffNote,
renderedPrompt,
]);
return {
basePrompt,
promptMetrics: {
promptChars: basePrompt.length,
instructionsChars: instructionsPrefix.length,
bootstrapPromptChars: renderedBootstrapPrompt.length,
wakePromptChars: wakePrompt.length,
taskContextChars: taskContextNote.length,
sessionHandoffChars: sessionHandoffNote.length,
heartbeatPromptChars: renderedPrompt.length,
},
};
};
// Optional diagnostic: surface OpenCode's own logs on stderr (captured into the
// run result) so failures that OpenCode otherwise wraps as an opaque
// "Unexpected server error" can be diagnosed in remote/sandbox runs where the
// log file is unreachable. Toggle via PAPERCLIP_OPENCODE_PRINT_LOGS (run env,
// then process env).
const printLogs = isTruthyEnvFlag(
env.PAPERCLIP_OPENCODE_PRINT_LOGS ?? process.env.PAPERCLIP_OPENCODE_PRINT_LOGS,
);
const buildArgs = (resumeSessionId: string | null) => {
const args = ["run", "--format", "json"];
if (printLogs) args.push("--print-logs");
if (resumeSessionId) args.push("--session", resumeSessionId);
if (model) args.push("--model", model);
if (variant) args.push("--variant", variant);
// OpenCode prefers the inherited PWD over process.cwd(). Use the realized
// workspace unless the operator already selected a directory explicitly.
const optionTerminator = extraArgs.indexOf("--");
const extraOptionArgs = optionTerminator === -1 ? extraArgs : extraArgs.slice(0, optionTerminator);
if (!extraOptionArgs.some((arg) => arg === "--dir" || arg.startsWith("--dir="))) {
args.push("--dir", effectiveExecutionCwd);
}
if (extraArgs.length > 0) args.push(...extraArgs);
return args;
};
// Remote targets receive only the prepared environment, never host keys.
const accountingEnv = executionTargetIsRemote ? preparedRuntimeConfig.env : runtimeEnv;
const runAttempt = async (resumeSessionId: string | null) => {
await hydrateFreshSessionHandoff(ctx, { resumedSession: Boolean(resumeSessionId) });
const { basePrompt, promptMetrics } = buildPrompt(Boolean(resumeSessionId));
const prompt = joinPromptSections([
selectInitialCommunicationGuidance(context, { resumedSession: Boolean(resumeSessionId) }),
basePrompt,
]);
const args = buildArgs(resumeSessionId);
if (onMeta) {
await onMeta({
adapterType: "opencode_local",
command: resolvedCommand,
cwd: effectiveExecutionCwd,
commandNotes,
commandArgs: [...args, `<stdin prompt ${prompt.length} chars>`],
env: loggedEnv,
prompt,
promptMetrics: { ...promptMetrics, promptChars: prompt.length },
context,
const preparedExecutionTargetRuntime = await prepareAdapterExecutionTargetRuntime({
privateRuntime: Boolean(config.managedAiConnection),
runId,
target: executionTarget,
adapterKey: "opencode",
timeoutSec,
workspaceLocalDir: cwd,
installCommand: SANDBOX_INSTALL_COMMAND,
detectCommand: command,
onProgress: (line) => onLog("stdout", line),
onRuntimeProgress: ctx.onRuntimeProgress,
assets: [
{
key: "skills",
localDir: localSkillsDir,
followSymlinks: true,
},
...(localRuntimeConfigHome
? [{
key: "xdgConfig",
localDir: localRuntimeConfigHome,
}]
: []),
],
});
restoreRemoteWorkspace = () =>
preparedExecutionTargetRuntime.restoreWorkspace((line) => onLog("stdout", line));
effectiveExecutionCwd = preparedExecutionTargetRuntime.workspaceRemoteDir ?? effectiveExecutionCwd;
refreshPaperclipWorkspaceEnvForExecution({
env: preparedRuntimeConfig.env,
envConfig,
workspaceCwd: effectiveWorkspaceCwd,
workspaceSource,
workspaceId,
workspaceRepoUrl,
workspaceRepoRef,
workspaceHints,
agentHome,
executionTargetIsRemote,
executionCwd: effectiveExecutionCwd,
});
remoteRuntimeRootDir = preparedExecutionTargetRuntime.runtimeRootDir;
if (executionTarget?.kind === "remote" && executionTarget.transport === "ssh" && executionTarget.spec.useHostAuth === false && config.managedAiConnection && remoteRuntimeRootDir) Object.assign(preparedRuntimeConfig.env, managedRemoteHomeEnvironment(remoteRuntimeRootDir));
const managedHome = adapterExecutionTargetUsesManagedHome(executionTarget, Boolean(config.managedAiConnection));
if (managedHome && preparedExecutionTargetRuntime.runtimeRootDir) {
preparedRuntimeConfig.env.HOME = preparedExecutionTargetRuntime.runtimeRootDir;
}
if (localRuntimeConfigHome && preparedExecutionTargetRuntime.assetDirs.xdgConfig) {
preparedRuntimeConfig.env.XDG_CONFIG_HOME = preparedExecutionTargetRuntime.assetDirs.xdgConfig;
}
prepareManagedOpenCodeRemoteHomes({
env: preparedRuntimeConfig.env,
config,
runtimeRootDir: preparedExecutionTargetRuntime.runtimeRootDir,
runId,
configDir: preparedExecutionTargetRuntime.assetDirs.xdgConfig,
});
const remoteHomeDir = config.managedAiConnection
? preparedRuntimeConfig.env.HOME
: managedHome && preparedExecutionTargetRuntime.runtimeRootDir
? preparedExecutionTargetRuntime.runtimeRootDir
: await readAdapterExecutionTargetHomeDir(runId, executionTarget, {
cwd,
env: preparedRuntimeConfig.env,
timeoutSec,
graceSec,
onLog,
});
if (remoteHomeDir && preparedExecutionTargetRuntime.assetDirs.skills) {
const remoteSkillsDir = path.posix.join(remoteHomeDir, ".claude", "skills");
await runAdapterExecutionTargetShellCommand(
runId,
executionTarget,
`mkdir -p ${JSON.stringify(path.posix.dirname(remoteSkillsDir))} && rm -rf ${JSON.stringify(remoteSkillsDir)} && cp -a ${JSON.stringify(preparedExecutionTargetRuntime.assetDirs.skills)} ${JSON.stringify(remoteSkillsDir)}`,
{ cwd, env: preparedRuntimeConfig.env, timeoutSec, graceSec, onLog },
);
}
await ensureRemoteOpenCodeModelConfiguredAndAvailable({
runId,
executionTarget,
command,
model,
cwd,
env: preparedRuntimeConfig.env,
timeoutSec,
graceSec,
});
}
const consumeAccounting = createOpenCodeJsonlParser();
let hasAccounting = false;
const accountingLog = createUsageCheckpointLog(onLog, ctx.onUsage ?? (async () => {}), stdout => {
hasAccounting = true;
const parsed = consumeAccounting(stdout);
const provider = parseModelProvider(model || null);
return { usage: parsed.usageReported ? parsed.usage : undefined, costUsd: parsed.costUsd,
costStatus: parsed.usageComplete || parsed.costUsd != null ? undefined : "unpriced",
usageBasis: "per_run", provider, biller: resolveOpenCodeBiller(accountingEnv, provider), billingType: apiKeyBillingType(provider, accountingEnv), model, complete: false };
});
const proc = await runAdapterExecutionTargetProcess(runId, runtimeExecutionTarget, command, args, {
onProcessStopped: providerStop.beginInvocation(),
// Keep a long sandbox run off the synchronous command HTTP request.
// Probes and preparation keep their existing execution paths.
...(runtimeExecutionTarget?.kind === "remote" && runtimeExecutionTarget.transport === "sandbox"
&& runtimeExecutionTarget.providerKey === "daytona" ? { useSession: true } : {}),
cwd,
env: preparedRuntimeConfig.env,
stdin: prompt,
timeoutSec,
graceSec,
onSpawn,
onRuntimeProgress: ctx.onRuntimeProgress,
onLog: accountingLog,
runLogTail: paperclipBridge?.runLogTail,
settleRunDisposition: paperclipBridge?.settleRunDisposition,
});
// Parse any unterminated final record before deciding whether its usage
// is complete. A clean exit alone cannot turn absent counters into zero.
await accountingLog.flush();
const retainedAccounting = consumeAccounting("");
await accountingLog.flush({ complete: proc.exitCode === 0 && !proc.timedOut && !proc.signal
&& (retainedAccounting.usageComplete || retainedAccounting.costUsd != null) });
// Display output is capped by the process transport. Keep accounting
// from the full stream, including when no checkpoint callback is installed.
const parsed = parseOpenCodeJsonl(proc.stdout);
if (hasAccounting) {
const retained = consumeAccounting("");
parsed.usage = retained.usage;
parsed.usageReported = retained.usageReported;
parsed.usageComplete = retained.usageComplete;
parsed.costUsd = retained.costUsd;
const runtimeExecutionTarget = overrideAdapterExecutionTargetRemoteCwd(executionTarget, effectiveExecutionCwd);
if (executionTargetIsRemote && adapterExecutionTargetUsesPaperclipBridge(runtimeExecutionTarget)) {
paperclipBridge = await startAdapterExecutionTargetPaperclipBridge({
runId,
target: runtimeExecutionTarget,
enableSandboxDuplexBridge: adapterExecutionTargetEnablesSandboxDuplexBridge(runtimeExecutionTarget),
duplexObservabilityRecorder: adapterExecutionTargetDuplexObservabilityRecorder(runtimeExecutionTarget),
runtimeRootDir: remoteRuntimeRootDir,
adapterKey: "opencode",
timeoutSec,
hostApiToken: preparedRuntimeConfig.env.PAPERCLIP_API_KEY,
onLog,
});
if (paperclipBridge) {
Object.assign(preparedRuntimeConfig.env, paperclipBridge.env);
loggedEnv = buildInvocationEnvForLogs(preparedRuntimeConfig.env, {
runtimeEnv: Object.fromEntries(
Object.entries(ensurePathInEnv({ ...process.env, ...preparedRuntimeConfig.env })).filter(
(entry): entry is [string, string] => typeof entry[1] === "string",
),
),
includeRuntimeKeys: ["HOME"],
resolvedCommand,
});
}
}
return { proc, rawStderr: proc.stderr, parsed };
};
const toResult = (
attempt: {
proc: { exitCode: number | null; signal: string | null; timedOut: boolean; stdout: string; stderr: string; errorCode?: string | null };
rawStderr: string;
parsed: ReturnType<typeof parseOpenCodeJsonl>;
},
clearSessionOnMissingSession = false,
): AdapterExecutionResult => {
if (attempt.proc.timedOut) {
const runtimeSessionParams = parseObject(runtime.sessionParams);
const runtimeSessionId = asString(runtimeSessionParams.sessionId, runtime.sessionId ?? "");
const runtimeSessionCwd = asString(runtimeSessionParams.cwd, "");
const runtimeRemoteExecution = parseObject(runtimeSessionParams.remoteExecution);
const canResumeSession =
runtimeSessionId.length > 0 &&
(runtimeSessionCwd.length === 0 || path.resolve(runtimeSessionCwd) === path.resolve(effectiveExecutionCwd)) &&
adapterExecutionTargetSessionMatches(runtimeRemoteExecution, runtimeExecutionTarget);
const sessionId = canResumeSession ? runtimeSessionId : null;
if (executionTargetIsRemote && runtimeSessionId && !canResumeSession) {
await onLog(
"stdout",
`[paperclip] OpenCode session "${runtimeSessionId}" does not match the current remote execution identity and will not be resumed in "${effectiveExecutionCwd}". Starting a fresh remote session.\n`,
);
} else if (runtimeSessionId && !canResumeSession) {
await onLog(
"stdout",
`[paperclip] OpenCode session "${runtimeSessionId}" was saved for cwd "${runtimeSessionCwd}" and will not be resumed in "${effectiveExecutionCwd}".\n`,
);
}
const instructionsFilePath = asString(config.instructionsFilePath, "").trim();
const resolvedInstructionsFilePath = instructionsFilePath
? path.resolve(cwd, instructionsFilePath)
: "";
const instructionsDir = resolvedInstructionsFilePath ? `${path.dirname(resolvedInstructionsFilePath)}/` : "";
let instructionsPrefix = "";
if (resolvedInstructionsFilePath) {
try {
const instructionsContents = await fs.readFile(resolvedInstructionsFilePath, "utf8");
instructionsPrefix =
`${instructionsContents}\n\n` +
`The above agent instructions were loaded from ${resolvedInstructionsFilePath}. ` +
`Resolve any relative file references from ${instructionsDir}.\n\n`;
} catch (err) {
const reason = err instanceof Error ? err.message : String(err);
await onLog(
"stdout",
`[paperclip] Warning: could not read agent instructions file "${resolvedInstructionsFilePath}": ${reason}\n`,
);
}
}
const commandNotes = (() => {
const notes = [...preparedRuntimeConfig.notes];
if (!resolvedInstructionsFilePath) return notes;
if (instructionsPrefix.length > 0) {
notes.push(`Loaded agent instructions from ${resolvedInstructionsFilePath}`);
notes.push(
`Prepended instructions + path directive to stdin prompt (relative references from ${instructionsDir}).`,
);
return notes;
}
notes.push(
`Configured instructionsFilePath ${resolvedInstructionsFilePath}, but file could not be read; continuing without injected instructions.`,
);
return notes;
})();
const bootstrapPromptTemplate = asString(config.bootstrapPromptTemplate, "");
const templateData = {
agentId: agent.id,
companyId: agent.companyId,
runId,
company: { id: agent.companyId },
agent,
run: { id: runId, source: "on_demand" },
context,
};
const buildPrompt = (resumedSession: boolean) => {
const renderedBootstrapPrompt =
!resumedSession && bootstrapPromptTemplate.trim().length > 0
? renderTemplate(bootstrapPromptTemplate, templateData).trim()
: "";
const { taskContextNote, wakePrompt } = selectPaperclipPromptSections(context, {
resumedSession,
includeCommunicationGuidance: false,
});
const shouldUseResumeDeltaPrompt = resumedSession && wakePrompt.length > 0;
const renderedPrompt = shouldUseResumeDeltaPrompt || isPaperclipRecoveryWakePayload(context.paperclipWake)
? ""
: renderTemplate(promptTemplate, templateData);
const sessionHandoffNote = asString(context.paperclipSessionHandoffMarkdown, "").trim();
const basePrompt = joinPromptSections([
instructionsPrefix,
renderedBootstrapPrompt,
wakePrompt,
taskContextNote,
sessionHandoffNote,
renderedPrompt,
]);
return {
exitCode: attempt.proc.exitCode,
basePrompt,
promptMetrics: {
promptChars: basePrompt.length,
instructionsChars: instructionsPrefix.length,
bootstrapPromptChars: renderedBootstrapPrompt.length,
wakePromptChars: wakePrompt.length,
taskContextChars: taskContextNote.length,
sessionHandoffChars: sessionHandoffNote.length,
heartbeatPromptChars: renderedPrompt.length,
},
};
};
// Optional diagnostic: surface OpenCode's own logs on stderr (captured into the
// run result) so failures that OpenCode otherwise wraps as an opaque
// "Unexpected server error" can be diagnosed in remote/sandbox runs where the
// log file is unreachable. Toggle via PAPERCLIP_OPENCODE_PRINT_LOGS (run env,
// then process env).
const printLogs = isTruthyEnvFlag(
env.PAPERCLIP_OPENCODE_PRINT_LOGS ?? process.env.PAPERCLIP_OPENCODE_PRINT_LOGS,
);
const buildArgs = (resumeSessionId: string | null) => {
const args = ["run", "--format", "json"];
if (printLogs) args.push("--print-logs");
if (resumeSessionId) args.push("--session", resumeSessionId);
if (model) args.push("--model", model);
if (variant) args.push("--variant", variant);
// OpenCode prefers the inherited PWD over process.cwd(). Use the realized
// workspace unless the operator already selected a directory explicitly.
const optionTerminator = extraArgs.indexOf("--");
const extraOptionArgs = optionTerminator === -1 ? extraArgs : extraArgs.slice(0, optionTerminator);
if (!extraOptionArgs.some((arg) => arg === "--dir" || arg.startsWith("--dir="))) {
args.push("--dir", effectiveExecutionCwd);
}
if (extraArgs.length > 0) args.push(...extraArgs);
return args;
};
// Remote targets receive only the prepared environment, never host keys.
const accountingEnv = executionTargetIsRemote ? preparedRuntimeConfig.env : runtimeEnv;
const runAttempt = async (resumeSessionId: string | null) => {
await hydrateFreshSessionHandoff(ctx, { resumedSession: Boolean(resumeSessionId) });
const { basePrompt, promptMetrics } = buildPrompt(Boolean(resumeSessionId));
const prompt = joinPromptSections([
selectInitialCommunicationGuidance(context, { resumedSession: Boolean(resumeSessionId) }),
basePrompt,
]);
const args = buildArgs(resumeSessionId);
if (onMeta) {
await onMeta({
adapterType: "opencode_local",
command: resolvedCommand,
cwd: effectiveExecutionCwd,
commandNotes,
commandArgs: [...args, `<stdin prompt ${prompt.length} chars>`],
env: loggedEnv,
prompt,
promptMetrics: { ...promptMetrics, promptChars: prompt.length },
context,
});
}
const consumeAccounting = createOpenCodeJsonlParser();
let hasAccounting = false;
const accountingLog = createUsageCheckpointLog(onLog, ctx.onUsage ?? (async () => {}), stdout => {
hasAccounting = true;
const parsed = consumeAccounting(stdout);
const provider = parseModelProvider(model || null);
return { usage: parsed.usageReported ? parsed.usage : undefined, costUsd: parsed.costUsd,
costStatus: parsed.usageComplete || parsed.costUsd != null ? undefined : "unpriced",
usageBasis: "per_run", provider, biller: resolveOpenCodeBiller(accountingEnv, provider), billingType: apiKeyBillingType(provider, accountingEnv), model, complete: false };
});
const proc = await runAdapterExecutionTargetProcess(runId, runtimeExecutionTarget, command, args, {
onProcessStopped: providerStop.beginInvocation(),
// Keep a long sandbox run off the synchronous command HTTP request.
// Probes and preparation keep their existing execution paths.
...(runtimeExecutionTarget?.kind === "remote" && runtimeExecutionTarget.transport === "sandbox"
&& runtimeExecutionTarget.providerKey === "daytona" ? { useSession: true } : {}),
cwd,
env: preparedRuntimeConfig.env,
stdin: prompt,
timeoutSec,
graceSec,
onSpawn,
onRuntimeProgress: ctx.onRuntimeProgress,
onLog: accountingLog,
runLogTail: paperclipBridge?.runLogTail,
settleRunDisposition: paperclipBridge?.settleRunDisposition,
});
// Parse any unterminated final record before deciding whether its usage
// is complete. A clean exit alone cannot turn absent counters into zero.
await accountingLog.flush();
const retainedAccounting = consumeAccounting("");
await accountingLog.flush({ complete: proc.exitCode === 0 && !proc.timedOut && !proc.signal
&& (retainedAccounting.usageComplete || retainedAccounting.costUsd != null) });
// Display output is capped by the process transport. Keep accounting
// from the full stream, including when no checkpoint callback is installed.
const parsed = parseOpenCodeJsonl(proc.stdout);
if (hasAccounting) {
const retained = consumeAccounting("");
parsed.usage = retained.usage;
parsed.usageReported = retained.usageReported;
parsed.usageComplete = retained.usageComplete;
parsed.costUsd = retained.costUsd;
}
return { proc, rawStderr: proc.stderr, parsed };
};
const toResult = (
attempt: {
proc: { exitCode: number | null; signal: string | null; timedOut: boolean; stdout: string; stderr: string; errorCode?: string | null };
rawStderr: string;
parsed: ReturnType<typeof parseOpenCodeJsonl>;
},
clearSessionOnMissingSession = false,
): AdapterExecutionResult => {
if (attempt.proc.timedOut) {
return {
exitCode: attempt.proc.exitCode,
signal: attempt.proc.signal,
timedOut: true,
usageComplete: false,
usage: attempt.parsed.usageReported ? attempt.parsed.usage : undefined,
usageBasis: "per_run",
provider: parseModelProvider(model || null),
biller: resolveOpenCodeBiller(accountingEnv, parseModelProvider(model || null)),
model,
billingType: apiKeyBillingType(parseModelProvider(model || null), accountingEnv),
costUsd: attempt.parsed.costUsd,
costStatus: attempt.parsed.usageComplete || attempt.parsed.costUsd != null ? undefined : "unpriced",
// A provider or output-observation timeout can arrive before the
// configured execution deadline. The boolean does not prove which
// timer fired, and provider stderr is not safe exception text.
errorMessage: "OpenCode execution timed out",
resultJson: { adapterExecutionTimeout },
clearSession: clearSessionOnMissingSession,
};
}
const resolvedSessionId =
attempt.parsed.sessionId ??
(clearSessionOnMissingSession ? null : runtimeSessionId ?? runtime.sessionId ?? null);
const resolvedSessionParams = resolvedSessionId
? ({
sessionId: resolvedSessionId,
cwd: effectiveExecutionCwd,
...(workspaceId ? { workspaceId } : {}),
...(workspaceRepoUrl ? { repoUrl: workspaceRepoUrl } : {}),
...(workspaceRepoRef ? { repoRef: workspaceRepoRef } : {}),
...(executionTargetIsRemote
? {
remoteExecution: adapterExecutionTargetSessionIdentity(runtimeExecutionTarget),
}
: {}),
} as Record<string, unknown>)
: null;
const parsedError = typeof attempt.parsed.errorMessage === "string" ? attempt.parsed.errorMessage.trim() : "";
const stderrLine = firstNonEmptyLine(attempt.proc.stderr);
const rawExitCode = attempt.proc.exitCode;
const synthesizedExitCode = parsedError && (rawExitCode ?? 0) === 0 ? 1 : rawExitCode;
const fallbackErrorMessage =
parsedError ||
stderrLine ||
`OpenCode exited with code ${synthesizedExitCode ?? -1}`;
const modelId = model || null;
return {
exitCode: synthesizedExitCode,
signal: attempt.proc.signal,
timedOut: true,
usageComplete: false,
usage: attempt.parsed.usageReported ? attempt.parsed.usage : undefined,
timedOut: false,
usageComplete: attempt.proc.exitCode === 0 && !attempt.proc.signal
&& (attempt.parsed.usageComplete || attempt.parsed.costUsd != null),
usageBasis: "per_run",
provider: parseModelProvider(model || null),
biller: resolveOpenCodeBiller(accountingEnv, parseModelProvider(model || null)),
model,
billingType: apiKeyBillingType(parseModelProvider(model || null), accountingEnv),
errorMessage: (synthesizedExitCode ?? 0) === 0 ? null : fallbackErrorMessage,
// Forward the transport-level error code from the run-disposition seam.
// A lost duplex control channel surfaces the typed `duplex_channel_lost`
// code; every other result carries no code here.
errorCode: attempt.proc.errorCode ?? null,
usage: attempt.parsed.usageReported ? attempt.parsed.usage : undefined,
sessionId: resolvedSessionId,
sessionParams: resolvedSessionParams,
sessionDisplayId: resolvedSessionId,
provider: parseModelProvider(modelId),
biller: resolveOpenCodeBiller(accountingEnv, parseModelProvider(modelId)),
model: modelId,
billingType: apiKeyBillingType(parseModelProvider(modelId), accountingEnv),
costUsd: attempt.parsed.costUsd,
costStatus: attempt.parsed.usageComplete || attempt.parsed.costUsd != null ? undefined : "unpriced",
// A provider or output-observation timeout can arrive before the
// configured execution deadline. The boolean does not prove which
// timer fired, and provider stderr is not safe exception text.
errorMessage: "OpenCode execution timed out",
resultJson: { adapterExecutionTimeout },
clearSession: clearSessionOnMissingSession,
resultJson: {
adapterExecutionTimeout,
stdout: attempt.proc.stdout,
stderr: attempt.proc.stderr,
},
summary: attempt.parsed.summary,
clearSession: Boolean(clearSessionOnMissingSession && !attempt.parsed.sessionId),
};
}
const resolvedSessionId =
attempt.parsed.sessionId ??
(clearSessionOnMissingSession ? null : runtimeSessionId ?? runtime.sessionId ?? null);
const resolvedSessionParams = resolvedSessionId
? ({
sessionId: resolvedSessionId,
cwd: effectiveExecutionCwd,
...(workspaceId ? { workspaceId } : {}),
...(workspaceRepoUrl ? { repoUrl: workspaceRepoUrl } : {}),
...(workspaceRepoRef ? { repoRef: workspaceRepoRef } : {}),
...(executionTargetIsRemote
? {
remoteExecution: adapterExecutionTargetSessionIdentity(runtimeExecutionTarget),
}
: {}),
} as Record<string, unknown>)
: null;
const parsedError = typeof attempt.parsed.errorMessage === "string" ? attempt.parsed.errorMessage.trim() : "";
const stderrLine = firstNonEmptyLine(attempt.proc.stderr);
const rawExitCode = attempt.proc.exitCode;
const synthesizedExitCode = parsedError && (rawExitCode ?? 0) === 0 ? 1 : rawExitCode;
const fallbackErrorMessage =
parsedError ||
stderrLine ||
`OpenCode exited with code ${synthesizedExitCode ?? -1}`;
const modelId = model || null;
return {
exitCode: synthesizedExitCode,
signal: attempt.proc.signal,
timedOut: false,
usageComplete: attempt.proc.exitCode === 0 && !attempt.proc.signal
&& (attempt.parsed.usageComplete || attempt.parsed.costUsd != null),
usageBasis: "per_run",
errorMessage: (synthesizedExitCode ?? 0) === 0 ? null : fallbackErrorMessage,
// Forward the transport-level error code from the run-disposition seam.
// A lost duplex control channel surfaces the typed `duplex_channel_lost`
// code; every other result carries no code here.
errorCode: attempt.proc.errorCode ?? null,
usage: attempt.parsed.usageReported ? attempt.parsed.usage : undefined,
sessionId: resolvedSessionId,
sessionParams: resolvedSessionParams,
sessionDisplayId: resolvedSessionId,
provider: parseModelProvider(modelId),
biller: resolveOpenCodeBiller(accountingEnv, parseModelProvider(modelId)),
model: modelId,
billingType: apiKeyBillingType(parseModelProvider(modelId), accountingEnv),
costUsd: attempt.parsed.costUsd,
costStatus: attempt.parsed.usageComplete || attempt.parsed.costUsd != null ? undefined : "unpriced",
resultJson: {
adapterExecutionTimeout,
stdout: attempt.proc.stdout,
stderr: attempt.proc.stderr,
},
summary: attempt.parsed.summary,
clearSession: Boolean(clearSessionOnMissingSession && !attempt.parsed.sessionId),
};
};
try {
const initial = await runAttempt(sessionId);
const initialFailed =
!initial.proc.timedOut && ((initial.proc.exitCode ?? 0) !== 0 || Boolean(initial.parsed.errorMessage));
+419 -415
View File
@@ -6,6 +6,7 @@ import path from "node:path";
import { fileURLToPath } from "node:url";
import { inferOpenAiCompatibleBiller, type AdapterExecutionContext, type AdapterExecutionResult } from "@paperclipai/adapter-utils";
import {
managedRemoteHomeEnvironment,
adapterExecutionTargetIsRemote,
adapterExecutionTargetRemoteCwd,
overrideAdapterExecutionTargetRemoteCwd,
@@ -422,458 +423,461 @@ export async function execute(ctx: AdapterExecutionContext): Promise<AdapterExec
let remoteSkillsDir: string | null = null;
let paperclipBridge: Awaited<ReturnType<typeof startAdapterExecutionTargetPaperclipBridge>> = null;
if (executionTargetIsRemote) {
try {
localSkillsDir = await buildPiSkillsDir(config);
await onLog(
"stdout",
`[paperclip] Syncing workspace and Pi runtime assets to ${describeAdapterExecutionTarget(executionTarget)}.\n`,
);
const preparedRemoteRuntime = await prepareAdapterExecutionTargetRuntime({
try {
if (executionTargetIsRemote) {
try {
localSkillsDir = await buildPiSkillsDir(config);
await onLog(
"stdout",
`[paperclip] Syncing workspace and Pi runtime assets to ${describeAdapterExecutionTarget(executionTarget)}.\n`,
);
const preparedRemoteRuntime = await prepareAdapterExecutionTargetRuntime({
privateRuntime: Boolean(config.managedAiConnection),
runId,
target: executionTarget,
adapterKey: "pi",
timeoutSec,
workspaceLocalDir: cwd,
installCommand: SANDBOX_INSTALL_COMMAND,
detectCommand: command,
onProgress: (line) => onLog("stdout", line),
onRuntimeProgress: ctx.onRuntimeProgress,
assets: [
{
key: "attribution",
localDir: attributionExtension.directory,
},
{
key: "skills",
localDir: localSkillsDir,
followSymlinks: true,
},
...(localAgentConfigDir
? [{
key: "agentConfig",
localDir: localAgentConfigDir,
}]
: []),
],
});
restoreRemoteWorkspace = () =>
preparedRemoteRuntime.restoreWorkspace((line) => onLog("stdout", line));
effectiveExecutionCwd = preparedRemoteRuntime.workspaceRemoteDir ?? effectiveExecutionCwd;
refreshPaperclipWorkspaceEnvForExecution({
env,
envConfig,
workspaceCwd: effectiveWorkspaceCwd,
workspaceSource,
workspaceId,
workspaceRepoUrl,
workspaceRepoRef,
workspaceHints,
agentHome,
executionTargetIsRemote,
executionCwd: effectiveExecutionCwd,
});
if (executionTarget?.kind === "remote" && executionTarget.transport === "ssh" && executionTarget.spec.useHostAuth === false && config.managedAiConnection && preparedRemoteRuntime.runtimeRootDir) Object.assign(env, managedRemoteHomeEnvironment(preparedRemoteRuntime.runtimeRootDir));
if (adapterExecutionTargetUsesManagedHome(executionTarget, Boolean(config.managedAiConnection)) && preparedRemoteRuntime.runtimeRootDir) {
env.HOME = preparedRemoteRuntime.runtimeRootDir;
}
remoteRuntimeRootDir = preparedRemoteRuntime.runtimeRootDir;
remoteSkillsDir = preparedRemoteRuntime.assetDirs.skills ?? null;
const remoteAttributionDir = preparedRemoteRuntime.assetDirs.attribution;
if (!remoteAttributionDir) throw new Error("Pi attribution extension was not staged to the execution target.");
attributionExtensionPath = path.posix.join(remoteAttributionDir, "openrouter-attribution.mjs");
if (localAgentConfigDir && preparedRemoteRuntime.assetDirs.agentConfig) {
env.PI_CODING_AGENT_DIR = preparedRemoteRuntime.assetDirs.agentConfig;
}
} catch (error) {
await Promise.allSettled([
restoreRemoteWorkspace?.(),
localSkillsDir ? fs.rm(path.dirname(localSkillsDir), { recursive: true, force: true }).catch(() => undefined) : Promise.resolve(),
]);
restoreRemoteWorkspace = null;
throw error;
}
}
const runtimeExecutionTarget = overrideAdapterExecutionTargetRemoteCwd(executionTarget, effectiveExecutionCwd);
if (executionTargetIsRemote && adapterExecutionTargetUsesPaperclipBridge(runtimeExecutionTarget)) {
paperclipBridge = await startAdapterExecutionTargetPaperclipBridge({
runId,
target: executionTarget,
target: runtimeExecutionTarget,
enableSandboxDuplexBridge: adapterExecutionTargetEnablesSandboxDuplexBridge(runtimeExecutionTarget),
duplexObservabilityRecorder: adapterExecutionTargetDuplexObservabilityRecorder(runtimeExecutionTarget),
runtimeRootDir: remoteRuntimeRootDir,
adapterKey: "pi",
timeoutSec,
workspaceLocalDir: cwd,
installCommand: SANDBOX_INSTALL_COMMAND,
detectCommand: command,
onProgress: (line) => onLog("stdout", line),
onRuntimeProgress: ctx.onRuntimeProgress,
assets: [
{
key: "attribution",
localDir: attributionExtension.directory,
},
{
key: "skills",
localDir: localSkillsDir,
followSymlinks: true,
},
...(localAgentConfigDir
? [{
key: "agentConfig",
localDir: localAgentConfigDir,
}]
: []),
],
});
restoreRemoteWorkspace = () =>
preparedRemoteRuntime.restoreWorkspace((line) => onLog("stdout", line));
effectiveExecutionCwd = preparedRemoteRuntime.workspaceRemoteDir ?? effectiveExecutionCwd;
refreshPaperclipWorkspaceEnvForExecution({
env,
envConfig,
workspaceCwd: effectiveWorkspaceCwd,
workspaceSource,
workspaceId,
workspaceRepoUrl,
workspaceRepoRef,
workspaceHints,
agentHome,
executionTargetIsRemote,
executionCwd: effectiveExecutionCwd,
});
if (adapterExecutionTargetUsesManagedHome(executionTarget) && preparedRemoteRuntime.runtimeRootDir) {
env.HOME = preparedRemoteRuntime.runtimeRootDir;
}
remoteRuntimeRootDir = preparedRemoteRuntime.runtimeRootDir;
remoteSkillsDir = preparedRemoteRuntime.assetDirs.skills ?? null;
const remoteAttributionDir = preparedRemoteRuntime.assetDirs.attribution;
if (!remoteAttributionDir) throw new Error("Pi attribution extension was not staged to the execution target.");
attributionExtensionPath = path.posix.join(remoteAttributionDir, "openrouter-attribution.mjs");
if (localAgentConfigDir && preparedRemoteRuntime.assetDirs.agentConfig) {
env.PI_CODING_AGENT_DIR = preparedRemoteRuntime.assetDirs.agentConfig;
}
} catch (error) {
await Promise.allSettled([
restoreRemoteWorkspace?.(),
localSkillsDir ? fs.rm(path.dirname(localSkillsDir), { recursive: true, force: true }).catch(() => undefined) : Promise.resolve(),
]);
throw error;
}
}
const runtimeExecutionTarget = overrideAdapterExecutionTargetRemoteCwd(executionTarget, effectiveExecutionCwd);
if (executionTargetIsRemote && adapterExecutionTargetUsesPaperclipBridge(runtimeExecutionTarget)) {
paperclipBridge = await startAdapterExecutionTargetPaperclipBridge({
runId,
target: runtimeExecutionTarget,
enableSandboxDuplexBridge: adapterExecutionTargetEnablesSandboxDuplexBridge(runtimeExecutionTarget),
duplexObservabilityRecorder: adapterExecutionTargetDuplexObservabilityRecorder(runtimeExecutionTarget),
runtimeRootDir: remoteRuntimeRootDir,
adapterKey: "pi",
timeoutSec,
hostApiToken: env.PAPERCLIP_API_KEY,
onLog,
});
if (paperclipBridge) {
Object.assign(env, paperclipBridge.env);
loggedEnv = buildInvocationEnvForLogs(env, {
runtimeEnv: Object.fromEntries(
Object.entries(ensurePathInEnv({ ...sanitizeInheritedPaperclipEnv(process.env), ...env })).filter(
(entry): entry is [string, string] => typeof entry[1] === "string",
),
),
includeRuntimeKeys: ["HOME"],
resolvedCommand,
});
}
}
const runtimeSessionParams = parseObject(runtime.sessionParams);
const runtimeSessionId = asString(runtimeSessionParams.sessionId, runtime.sessionId ?? "");
const runtimeSessionCwd = asString(runtimeSessionParams.cwd, "");
const runtimeRemoteExecution = parseObject(runtimeSessionParams.remoteExecution);
const sessionTargetMatches = adapterExecutionTargetSessionMatches(runtimeRemoteExecution, runtimeExecutionTarget);
const sessionParamsCwdMatches =
runtimeSessionCwd.length === 0 ||
executionCwdsMatch(runtimeSessionCwd, effectiveExecutionCwd, executionTargetIsRemote);
const savedSessionCwd =
runtimeSessionId.length > 0
? await readSavedSessionCwd({
runId,
sessionPath: runtimeSessionId,
executionTarget: runtimeExecutionTarget ?? null,
cwd,
env,
timeoutSec,
graceSec,
})
: null;
const sessionHeaderCwdMatches =
runtimeSessionId.length === 0 ||
(savedSessionCwd !== null &&
executionCwdsMatch(savedSessionCwd, effectiveExecutionCwd, executionTargetIsRemote));
const canResumeSession =
runtimeSessionId.length > 0 &&
sessionTargetMatches &&
sessionParamsCwdMatches &&
sessionHeaderCwdMatches;
const sessionPath = canResumeSession
? runtimeSessionId
: executionTargetIsRemote && remoteRuntimeRootDir
? buildRemoteSessionPath(remoteRuntimeRootDir, agent.id, new Date().toISOString())
: buildSessionPath(agent.id, new Date().toISOString());
if (runtimeSessionId && !canResumeSession) {
const staleSessionCwdNote =
savedSessionCwd !== null && !sessionHeaderCwdMatches
? ` Pi stored cwd "${savedSessionCwd}" in the session header, so Paperclip will start a fresh session for "${effectiveExecutionCwd}".`
: "";
await onLog(
"stdout",
executionTargetIsRemote
? `[paperclip] Pi session "${runtimeSessionId}" does not match the current remote execution state and will not be resumed in "${effectiveExecutionCwd}".${staleSessionCwdNote} Starting a fresh remote session.\n`
: `[paperclip] Pi session "${runtimeSessionId}" was saved for cwd "${runtimeSessionCwd}" and will not be resumed in "${effectiveExecutionCwd}".${staleSessionCwdNote}\n`,
);
}
if (!canResumeSession) {
if (executionTargetIsRemote) {
await ensureAdapterExecutionTargetFile(runId, runtimeExecutionTarget, sessionPath, {
cwd,
env,
timeoutSec: 15,
graceSec: 5,
hostApiToken: env.PAPERCLIP_API_KEY,
onLog,
});
} else {
try {
await fs.writeFile(sessionPath, "", { flag: "wx" });
} catch (err) {
if ((err as NodeJS.ErrnoException).code !== "EEXIST") {
throw err;
}
if (paperclipBridge) {
Object.assign(env, paperclipBridge.env);
loggedEnv = buildInvocationEnvForLogs(env, {
runtimeEnv: Object.fromEntries(
Object.entries(ensurePathInEnv({ ...sanitizeInheritedPaperclipEnv(process.env), ...env })).filter(
(entry): entry is [string, string] => typeof entry[1] === "string",
),
),
includeRuntimeKeys: ["HOME"],
resolvedCommand,
});
}
}
}
// Handle instructions file and build system prompt extension
const instructionsFilePath = asString(config.instructionsFilePath, "").trim();
const resolvedInstructionsFilePath = instructionsFilePath
? path.resolve(cwd, instructionsFilePath)
: "";
const instructionsFileDir = instructionsFilePath ? `${path.dirname(instructionsFilePath)}/` : "";
const runtimeSessionParams = parseObject(runtime.sessionParams);
const runtimeSessionId = asString(runtimeSessionParams.sessionId, runtime.sessionId ?? "");
const runtimeSessionCwd = asString(runtimeSessionParams.cwd, "");
const runtimeRemoteExecution = parseObject(runtimeSessionParams.remoteExecution);
const sessionTargetMatches = adapterExecutionTargetSessionMatches(runtimeRemoteExecution, runtimeExecutionTarget);
const sessionParamsCwdMatches =
runtimeSessionCwd.length === 0 ||
executionCwdsMatch(runtimeSessionCwd, effectiveExecutionCwd, executionTargetIsRemote);
const savedSessionCwd =
runtimeSessionId.length > 0
? await readSavedSessionCwd({
runId,
sessionPath: runtimeSessionId,
executionTarget: runtimeExecutionTarget ?? null,
cwd,
env,
timeoutSec,
graceSec,
})
: null;
const sessionHeaderCwdMatches =
runtimeSessionId.length === 0 ||
(savedSessionCwd !== null &&
executionCwdsMatch(savedSessionCwd, effectiveExecutionCwd, executionTargetIsRemote));
const canResumeSession =
runtimeSessionId.length > 0 &&
sessionTargetMatches &&
sessionParamsCwdMatches &&
sessionHeaderCwdMatches;
const sessionPath = canResumeSession
? runtimeSessionId
: executionTargetIsRemote && remoteRuntimeRootDir
? buildRemoteSessionPath(remoteRuntimeRootDir, agent.id, new Date().toISOString())
: buildSessionPath(agent.id, new Date().toISOString());
let systemPromptExtension = "";
let instructionsReadFailed = false;
if (resolvedInstructionsFilePath) {
try {
const instructionsContents = await fs.readFile(resolvedInstructionsFilePath, "utf8");
systemPromptExtension =
`${instructionsContents}\n\n` +
`The above agent instructions were loaded from ${resolvedInstructionsFilePath}. ` +
`Resolve any relative file references from ${instructionsFileDir}.\n\n` +
(context.conversationMode === true
? DEFAULT_PAPERCLIP_CONVERSATION_PROMPT_TEMPLATE
: DEFAULT_PAPERCLIP_AGENT_PROMPT_TEMPLATE);
} catch (err) {
instructionsReadFailed = true;
const reason = err instanceof Error ? err.message : String(err);
if (runtimeSessionId && !canResumeSession) {
const staleSessionCwdNote =
savedSessionCwd !== null && !sessionHeaderCwdMatches
? ` Pi stored cwd "${savedSessionCwd}" in the session header, so Paperclip will start a fresh session for "${effectiveExecutionCwd}".`
: "";
await onLog(
"stdout",
`[paperclip] Warning: could not read agent instructions file "${resolvedInstructionsFilePath}": ${reason}\n`,
executionTargetIsRemote
? `[paperclip] Pi session "${runtimeSessionId}" does not match the current remote execution state and will not be resumed in "${effectiveExecutionCwd}".${staleSessionCwdNote} Starting a fresh remote session.\n`
: `[paperclip] Pi session "${runtimeSessionId}" was saved for cwd "${runtimeSessionCwd}" and will not be resumed in "${effectiveExecutionCwd}".${staleSessionCwdNote}\n`,
);
// Fall back to base prompt template
}
if (!canResumeSession) {
if (executionTargetIsRemote) {
await ensureAdapterExecutionTargetFile(runId, runtimeExecutionTarget, sessionPath, {
cwd,
env,
timeoutSec: 15,
graceSec: 5,
onLog,
});
} else {
try {
await fs.writeFile(sessionPath, "", { flag: "wx" });
} catch (err) {
if ((err as NodeJS.ErrnoException).code !== "EEXIST") {
throw err;
}
}
}
}
// Handle instructions file and build system prompt extension
const instructionsFilePath = asString(config.instructionsFilePath, "").trim();
const resolvedInstructionsFilePath = instructionsFilePath
? path.resolve(cwd, instructionsFilePath)
: "";
const instructionsFileDir = instructionsFilePath ? `${path.dirname(instructionsFilePath)}/` : "";
let systemPromptExtension = "";
let instructionsReadFailed = false;
if (resolvedInstructionsFilePath) {
try {
const instructionsContents = await fs.readFile(resolvedInstructionsFilePath, "utf8");
systemPromptExtension =
`${instructionsContents}\n\n` +
`The above agent instructions were loaded from ${resolvedInstructionsFilePath}. ` +
`Resolve any relative file references from ${instructionsFileDir}.\n\n` +
(context.conversationMode === true
? DEFAULT_PAPERCLIP_CONVERSATION_PROMPT_TEMPLATE
: DEFAULT_PAPERCLIP_AGENT_PROMPT_TEMPLATE);
} catch (err) {
instructionsReadFailed = true;
const reason = err instanceof Error ? err.message : String(err);
await onLog(
"stdout",
`[paperclip] Warning: could not read agent instructions file "${resolvedInstructionsFilePath}": ${reason}\n`,
);
// Fall back to base prompt template
systemPromptExtension = promptTemplate;
}
} else {
systemPromptExtension = promptTemplate;
}
} else {
systemPromptExtension = promptTemplate;
}
const bootstrapPromptTemplate = asString(config.bootstrapPromptTemplate, "");
const templateData = {
agentId: agent.id,
companyId: agent.companyId,
runId,
company: { id: agent.companyId },
agent,
run: { id: runId, source: "on_demand" },
context,
};
const renderedSystemPromptExtension = renderTemplate(systemPromptExtension, templateData);
const systemOwnsDefaultPolicy = !hasCustomPromptTemplate || Boolean(resolvedInstructionsFilePath && !instructionsReadFailed);
const sessionHandoffNote = asString(context.paperclipSessionHandoffMarkdown, "").trim();
const bootstrapPromptTemplate = asString(config.bootstrapPromptTemplate, "");
const templateData = {
agentId: agent.id,
companyId: agent.companyId,
runId,
company: { id: agent.companyId },
agent,
run: { id: runId, source: "on_demand" },
context,
};
const renderedSystemPromptExtension = renderTemplate(systemPromptExtension, templateData);
const systemOwnsDefaultPolicy = !hasCustomPromptTemplate || Boolean(resolvedInstructionsFilePath && !instructionsReadFailed);
const sessionHandoffNote = asString(context.paperclipSessionHandoffMarkdown, "").trim();
const commandNotes = (() => {
const notes = [...preparedRuntimeConfig.notes];
if (stdoutLogMode !== "raw") {
notes.push(`Pi stdout run-log compaction mode: ${stdoutLogMode}`);
}
if (!resolvedInstructionsFilePath) return notes;
if (instructionsReadFailed) {
const commandNotes = (() => {
const notes = [...preparedRuntimeConfig.notes];
if (stdoutLogMode !== "raw") {
notes.push(`Pi stdout run-log compaction mode: ${stdoutLogMode}`);
}
if (!resolvedInstructionsFilePath) return notes;
if (instructionsReadFailed) {
notes.push(
`Configured instructionsFilePath ${resolvedInstructionsFilePath}, but file could not be read; continuing without injected instructions.`,
);
return notes;
}
notes.push(`Loaded agent instructions from ${resolvedInstructionsFilePath}`);
notes.push(
`Configured instructionsFilePath ${resolvedInstructionsFilePath}, but file could not be read; continuing without injected instructions.`,
`Appended instructions + path directive to system prompt (relative references from ${instructionsFileDir}).`,
);
return notes;
}
notes.push(`Loaded agent instructions from ${resolvedInstructionsFilePath}`);
notes.push(
`Appended instructions + path directive to system prompt (relative references from ${instructionsFileDir}).`,
);
return notes;
})();
})();
const buildArgs = (sessionFile: string, userPrompt: string): string[] => {
const args: string[] = [];
const buildArgs = (sessionFile: string, userPrompt: string): string[] => {
const args: string[] = [];
// Use JSON mode for structured output with print mode (non-interactive)
args.push("--mode", "json");
args.push("-p"); // Non-interactive mode: process prompt and exit
// Use JSON mode for structured output with print mode (non-interactive)
args.push("--mode", "json");
args.push("-p"); // Non-interactive mode: process prompt and exit
// Use --append-system-prompt to extend Pi's default system prompt
args.push("--append-system-prompt", renderedSystemPromptExtension);
// Use --append-system-prompt to extend Pi's default system prompt
args.push("--append-system-prompt", renderedSystemPromptExtension);
if (provider) args.push("--provider", provider);
if (modelId) args.push("--model", modelId);
if (thinking) args.push("--thinking", thinking);
if (provider) args.push("--provider", provider);
if (modelId) args.push("--model", modelId);
if (thinking) args.push("--thinking", thinking);
args.push("--tools", "read,bash,edit,write,grep,find,ls");
args.push("--session", sessionFile);
args.push("--skill", remoteSkillsDir ?? PI_AGENT_SKILLS_DIR);
args.push("--tools", "read,bash,edit,write,grep,find,ls");
args.push("--session", sessionFile);
args.push("--skill", remoteSkillsDir ?? PI_AGENT_SKILLS_DIR);
if (extraArgs.length > 0) args.push(...extraArgs);
args.push("--extension", attributionExtensionPath);
if (extraArgs.length > 0) args.push(...extraArgs);
args.push("--extension", attributionExtensionPath);
// Add the user prompt as the last argument
args.push(userPrompt);
// Add the user prompt as the last argument
args.push(userPrompt);
return args;
};
const runAttempt = async (sessionFile: string) => {
const attemptResumedSession = canResumeSession && sessionFile === sessionPath;
await hydrateFreshSessionHandoff(ctx, { resumedSession: attemptResumedSession });
const attemptSections = selectPaperclipPromptSections(context, {
resumedSession: attemptResumedSession,
includeCommunicationGuidance: false,
includeExecutionContract: systemOwnsDefaultPolicy ? false : undefined,
});
const attemptBootstrapPrompt = !attemptResumedSession && bootstrapPromptTemplate.trim().length > 0
? renderTemplate(bootstrapPromptTemplate, templateData).trim()
: "";
const attemptWakePrompt = attemptSections.wakePrompt;
const attemptRenderedHeartbeatPrompt = attemptResumedSession && attemptWakePrompt.length > 0
|| isPaperclipRecoveryWakePayload(context.paperclipWake)
|| !hasCustomPromptTemplate
? ""
: renderTemplate(promptTemplate, templateData);
const attemptBaseUserPrompt = joinPromptSections([
attemptBootstrapPrompt,
attemptWakePrompt,
attemptSections.taskContextNote,
sessionHandoffNote,
attemptRenderedHeartbeatPrompt,
]);
const userPrompt = joinPromptSections([
selectInitialCommunicationGuidance(context, { resumedSession: attemptResumedSession }),
attemptBaseUserPrompt,
]);
const promptMetrics = {
systemPromptChars: renderedSystemPromptExtension.length,
promptChars: userPrompt.length,
bootstrapPromptChars: attemptBootstrapPrompt.length,
wakePromptChars: attemptWakePrompt.length,
taskContextChars: attemptSections.taskContextNote.length,
sessionHandoffChars: sessionHandoffNote.length,
heartbeatPromptChars: attemptRenderedHeartbeatPrompt.length,
return args;
};
const args = buildArgs(sessionFile, userPrompt);
if (onMeta) {
await onMeta({
adapterType: "pi_local",
command: resolvedCommand,
cwd: effectiveExecutionCwd,
commandNotes,
commandArgs: args,
env: loggedEnv,
prompt: userPrompt,
promptMetrics: { ...promptMetrics, promptChars: userPrompt.length },
context,
const runAttempt = async (sessionFile: string) => {
const attemptResumedSession = canResumeSession && sessionFile === sessionPath;
await hydrateFreshSessionHandoff(ctx, { resumedSession: attemptResumedSession });
const attemptSections = selectPaperclipPromptSections(context, {
resumedSession: attemptResumedSession,
includeCommunicationGuidance: false,
includeExecutionContract: systemOwnsDefaultPolicy ? false : undefined,
});
}
// Buffer stdout by lines to handle partial JSON chunks
let stdoutBuffer = "";
const compactStdoutLine = createPiStdoutCompactor(stdoutLogMode);
// Compaction only affects the persisted run log; parsePiJsonl reads the unfiltered proc.stdout.
const emitCompacted = async (line: string, suffix: string) => {
const compacted = compactStdoutLine(line);
if (compacted !== null) {
await onLog("stdout", compacted + suffix);
}
};
const bufferedOnLog = async (stream: "stdout" | "stderr", chunk: string) => {
if (stream === "stderr") {
// Pass stderr through immediately (not JSONL)
await onLog(stream, chunk);
return;
}
stdoutBuffer += chunk;
const lines = stdoutBuffer.split("\n");
// Keep the last (potentially incomplete) line in the buffer
stdoutBuffer = lines.pop() || "";
for (const line of lines) {
if (line) {
await emitCompacted(line, "\n");
}
}
};
const consumeAccounting = createPiJsonlParser();
let hasAccounting = false;
const accountingLog = createUsageCheckpointLog(bufferedOnLog, ctx.onUsage ?? (async () => {}), stdout => {
hasAccounting = true;
const parsed = consumeAccounting(stdout);
return { usage: parsed.usage, costUsd: parsed.usage.costUsd, usageBasis: "per_run", provider, biller: resolvePiBiller(runtimeEnv, provider), billingType: "unknown", model, complete: parsed.sawAgentEnd };
});
const proc = await runAdapterExecutionTargetProcess(runId, runtimeExecutionTarget, command, args, {
onProcessStopped: providerStop.beginInvocation(),
cwd,
env: executionTargetIsRemote ? env : runtimeEnv,
timeoutSec,
graceSec,
onSpawn,
onRuntimeProgress: ctx.onRuntimeProgress,
onLog: accountingLog,
runLogTail: paperclipBridge?.runLogTail,
settleRunDisposition: paperclipBridge?.settleRunDisposition,
});
await accountingLog.flush();
// Flush any remaining buffer content
if (stdoutBuffer) {
await emitCompacted(stdoutBuffer, "");
}
// Display output is capped by the process transport. Keep accounting
// from the full stream, including when no checkpoint callback is installed.
const parsed = parsePiJsonl(proc.stdout);
if (hasAccounting) {
const retained = consumeAccounting("");
parsed.usage = retained.usage;
parsed.sawAgentEnd = retained.sawAgentEnd;
}
return { proc, rawStderr: proc.stderr, parsed };
};
const toResult = (
attempt: {
proc: { exitCode: number | null; signal: string | null; timedOut: boolean; stdout: string; stderr: string; errorCode?: string | null };
rawStderr: string;
parsed: ReturnType<typeof parsePiJsonl>;
},
clearSessionOnMissingSession = false,
): AdapterExecutionResult => {
if (attempt.proc.timedOut) {
return {
exitCode: attempt.proc.exitCode,
signal: attempt.proc.signal,
timedOut: true,
usageComplete: attempt.parsed.sawAgentEnd,
usage: attempt.parsed.usage, usageBasis: "per_run", provider, biller: resolvePiBiller(runtimeEnv, provider), model, billingType: "unknown", costUsd: attempt.parsed.usage.costUsd,
errorMessage: `Timed out after ${timeoutSec}s`,
clearSession: clearSessionOnMissingSession,
const attemptBootstrapPrompt = !attemptResumedSession && bootstrapPromptTemplate.trim().length > 0
? renderTemplate(bootstrapPromptTemplate, templateData).trim()
: "";
const attemptWakePrompt = attemptSections.wakePrompt;
const attemptRenderedHeartbeatPrompt = attemptResumedSession && attemptWakePrompt.length > 0
|| isPaperclipRecoveryWakePayload(context.paperclipWake)
|| !hasCustomPromptTemplate
? ""
: renderTemplate(promptTemplate, templateData);
const attemptBaseUserPrompt = joinPromptSections([
attemptBootstrapPrompt,
attemptWakePrompt,
attemptSections.taskContextNote,
sessionHandoffNote,
attemptRenderedHeartbeatPrompt,
]);
const userPrompt = joinPromptSections([
selectInitialCommunicationGuidance(context, { resumedSession: attemptResumedSession }),
attemptBaseUserPrompt,
]);
const promptMetrics = {
systemPromptChars: renderedSystemPromptExtension.length,
promptChars: userPrompt.length,
bootstrapPromptChars: attemptBootstrapPrompt.length,
wakePromptChars: attemptWakePrompt.length,
taskContextChars: attemptSections.taskContextNote.length,
sessionHandoffChars: sessionHandoffNote.length,
heartbeatPromptChars: attemptRenderedHeartbeatPrompt.length,
};
}
const resolvedSessionId = clearSessionOnMissingSession ? null : sessionPath;
const resolvedSessionParams = resolvedSessionId
? {
sessionId: resolvedSessionId,
const args = buildArgs(sessionFile, userPrompt);
if (onMeta) {
await onMeta({
adapterType: "pi_local",
command: resolvedCommand,
cwd: effectiveExecutionCwd,
...(workspaceId ? { workspaceId } : {}),
...(workspaceRepoUrl ? { repoUrl: workspaceRepoUrl } : {}),
...(workspaceRepoRef ? { repoRef: workspaceRepoRef } : {}),
...(executionTargetIsRemote
? {
remoteExecution: adapterExecutionTargetSessionIdentity(runtimeExecutionTarget),
}
: {}),
commandNotes,
commandArgs: args,
env: loggedEnv,
prompt: userPrompt,
promptMetrics: { ...promptMetrics, promptChars: userPrompt.length },
context,
});
}
// Buffer stdout by lines to handle partial JSON chunks
let stdoutBuffer = "";
const compactStdoutLine = createPiStdoutCompactor(stdoutLogMode);
// Compaction only affects the persisted run log; parsePiJsonl reads the unfiltered proc.stdout.
const emitCompacted = async (line: string, suffix: string) => {
const compacted = compactStdoutLine(line);
if (compacted !== null) {
await onLog("stdout", compacted + suffix);
}
};
const bufferedOnLog = async (stream: "stdout" | "stderr", chunk: string) => {
if (stream === "stderr") {
// Pass stderr through immediately (not JSONL)
await onLog(stream, chunk);
return;
}
: null;
const stderrLine = firstNonEmptyLine(attempt.proc.stderr);
const rawExitCode = attempt.proc.exitCode;
const parsedError = attempt.parsed.errors.find((error) => error.trim().length > 0) ?? "";
const effectiveExitCode = (rawExitCode ?? 0) === 0 && parsedError ? 1 : rawExitCode;
const fallbackErrorMessage = parsedError || stderrLine || `Pi exited with code ${rawExitCode ?? -1}`;
stdoutBuffer += chunk;
const lines = stdoutBuffer.split("\n");
// Keep the last (potentially incomplete) line in the buffer
stdoutBuffer = lines.pop() || "";
return {
exitCode: effectiveExitCode,
signal: attempt.proc.signal,
timedOut: false,
usageComplete: attempt.parsed.sawAgentEnd,
usageBasis: "per_run",
errorMessage: (effectiveExitCode ?? 0) === 0 ? null : fallbackErrorMessage,
// Forward the transport-level error code from the run-disposition seam.
// A lost duplex control channel surfaces the typed `duplex_channel_lost`
// code; every other result carries no code here.
errorCode: attempt.proc.errorCode ?? null,
usage: {
inputTokens: attempt.parsed.usage.inputTokens,
outputTokens: attempt.parsed.usage.outputTokens,
cachedInputTokens: attempt.parsed.usage.cachedInputTokens,
for (const line of lines) {
if (line) {
await emitCompacted(line, "\n");
}
}
};
const consumeAccounting = createPiJsonlParser();
let hasAccounting = false;
const accountingLog = createUsageCheckpointLog(bufferedOnLog, ctx.onUsage ?? (async () => {}), stdout => {
hasAccounting = true;
const parsed = consumeAccounting(stdout);
return { usage: parsed.usage, costUsd: parsed.usage.costUsd, usageBasis: "per_run", provider, biller: resolvePiBiller(runtimeEnv, provider), billingType: "unknown", model, complete: parsed.sawAgentEnd };
});
const proc = await runAdapterExecutionTargetProcess(runId, runtimeExecutionTarget, command, args, {
onProcessStopped: providerStop.beginInvocation(),
cwd,
env: executionTargetIsRemote ? env : runtimeEnv,
timeoutSec,
graceSec,
onSpawn,
onRuntimeProgress: ctx.onRuntimeProgress,
onLog: accountingLog,
runLogTail: paperclipBridge?.runLogTail,
settleRunDisposition: paperclipBridge?.settleRunDisposition,
});
await accountingLog.flush();
// Flush any remaining buffer content
if (stdoutBuffer) {
await emitCompacted(stdoutBuffer, "");
}
// Display output is capped by the process transport. Keep accounting
// from the full stream, including when no checkpoint callback is installed.
const parsed = parsePiJsonl(proc.stdout);
if (hasAccounting) {
const retained = consumeAccounting("");
parsed.usage = retained.usage;
parsed.sawAgentEnd = retained.sawAgentEnd;
}
return { proc, rawStderr: proc.stderr, parsed };
};
const toResult = (
attempt: {
proc: { exitCode: number | null; signal: string | null; timedOut: boolean; stdout: string; stderr: string; errorCode?: string | null };
rawStderr: string;
parsed: ReturnType<typeof parsePiJsonl>;
},
sessionId: resolvedSessionId,
sessionParams: resolvedSessionParams,
sessionDisplayId: resolvedSessionId,
provider: provider,
biller: resolvePiBiller(runtimeEnv, provider),
model: model,
billingType: "unknown",
costUsd: attempt.parsed.usage.costUsd,
resultJson: {
stdout: attempt.proc.stdout,
stderr: attempt.proc.stderr,
},
summary: attempt.parsed.finalMessage ?? attempt.parsed.messages.join("\n\n").trim(),
clearSession: Boolean(clearSessionOnMissingSession),
clearSessionOnMissingSession = false,
): AdapterExecutionResult => {
if (attempt.proc.timedOut) {
return {
exitCode: attempt.proc.exitCode,
signal: attempt.proc.signal,
timedOut: true,
usageComplete: attempt.parsed.sawAgentEnd,
usage: attempt.parsed.usage, usageBasis: "per_run", provider, biller: resolvePiBiller(runtimeEnv, provider), model, billingType: "unknown", costUsd: attempt.parsed.usage.costUsd,
errorMessage: `Timed out after ${timeoutSec}s`,
clearSession: clearSessionOnMissingSession,
};
}
const resolvedSessionId = clearSessionOnMissingSession ? null : sessionPath;
const resolvedSessionParams = resolvedSessionId
? {
sessionId: resolvedSessionId,
cwd: effectiveExecutionCwd,
...(workspaceId ? { workspaceId } : {}),
...(workspaceRepoUrl ? { repoUrl: workspaceRepoUrl } : {}),
...(workspaceRepoRef ? { repoRef: workspaceRepoRef } : {}),
...(executionTargetIsRemote
? {
remoteExecution: adapterExecutionTargetSessionIdentity(runtimeExecutionTarget),
}
: {}),
}
: null;
const stderrLine = firstNonEmptyLine(attempt.proc.stderr);
const rawExitCode = attempt.proc.exitCode;
const parsedError = attempt.parsed.errors.find((error) => error.trim().length > 0) ?? "";
const effectiveExitCode = (rawExitCode ?? 0) === 0 && parsedError ? 1 : rawExitCode;
const fallbackErrorMessage = parsedError || stderrLine || `Pi exited with code ${rawExitCode ?? -1}`;
return {
exitCode: effectiveExitCode,
signal: attempt.proc.signal,
timedOut: false,
usageComplete: attempt.parsed.sawAgentEnd,
usageBasis: "per_run",
errorMessage: (effectiveExitCode ?? 0) === 0 ? null : fallbackErrorMessage,
// Forward the transport-level error code from the run-disposition seam.
// A lost duplex control channel surfaces the typed `duplex_channel_lost`
// code; every other result carries no code here.
errorCode: attempt.proc.errorCode ?? null,
usage: {
inputTokens: attempt.parsed.usage.inputTokens,
outputTokens: attempt.parsed.usage.outputTokens,
cachedInputTokens: attempt.parsed.usage.cachedInputTokens,
},
sessionId: resolvedSessionId,
sessionParams: resolvedSessionParams,
sessionDisplayId: resolvedSessionId,
provider: provider,
biller: resolvePiBiller(runtimeEnv, provider),
model: model,
billingType: "unknown",
costUsd: attempt.parsed.usage.costUsd,
resultJson: {
stdout: attempt.proc.stdout,
stderr: attempt.proc.stderr,
},
summary: attempt.parsed.finalMessage ?? attempt.parsed.messages.join("\n\n").trim(),
clearSession: Boolean(clearSessionOnMissingSession),
};
};
};
try {
const initial = await runAttempt(sessionPath);
const initialFailed =
!initial.proc.timedOut && ((initial.proc.exitCode ?? 0) !== 0 || initial.parsed.errors.length > 0);
@@ -4677,7 +4677,7 @@ it("does not certify probe cleanup while owned credential preparation is unconfi
}
}, 15_000);
it.each(["admission-only", "admission-only-mismatched-model", "complete", "api-key", "default-model", "mismatched-model", "model-refresh-error", "model-cleanup-error", "missing-model", "missing-runtime", "missing-completion", "late-bootstrap", "remote-complete", "remote-mismatched-model", "late-remote-preparation", "late-remote-release-error"] as const)("native Codex setup requires its daemon/app-server hello (%s)", async mode => {
it.each(["admission-only", "admission-only-mismatched-model", "complete", "api-key", "default-model", "mismatched-model", "model-refresh-error", "model-cleanup-error", "missing-model", "missing-runtime", "missing-completion", "late-bootstrap", "remote-complete", "preconfigured", "remote-preconfigured", "remote-mismatched-model", "late-remote-preparation", "late-remote-release-error"] as const)("native Codex setup requires its daemon/app-server hello (%s)", async mode => {
const root = await mkdtemp(join(tmpdir(), "runnerd-native-setup-"));
const runtimeDirectory = join(root, "native-state");
await mkdir(runtimeDirectory, { mode: 0o700 });
@@ -4686,6 +4686,8 @@ it.each(["admission-only", "admission-only-mismatched-model", "complete", "api-k
await mkdir(sourceHome, { mode: 0o700 });
await writeFile(join(sourceHome, "auth.json"), JSON.stringify({ OPENAI_API_KEY: mode === "api-key" ? "unrelated-login" : "selected-account" }), { mode: 0o600 });
if (mode === "api-key") await writeFile(join(sourceHome, "config.toml"), 'model = "ambient-model"\n[mcp_servers.ambient]\ncommand = "untrusted-ambient-command"\n', { mode: 0o600 });
const preconfigured = mode.endsWith("preconfigured");
if (preconfigured) await writeFile(join(sourceHome, "config.toml"), 'model = "native-model"\n', { mode: 0o600 });
const remote = mode.startsWith("remote-") || mode.startsWith("late-remote-");
const remoteRoot = join(root, "assigned-remote-filesystem");
const remoteFilesystem = join(remoteRoot, "filesystem");
@@ -4697,18 +4699,21 @@ it.each(["admission-only", "admission-only-mismatched-model", "complete", "api-k
const probe = probeNativeRunnerEnvironment({
runtimeDirectory, provider: "codex", model: mode === "default-model" ? null : "gpt-6.1-sol", reasoningEffort: "low",
...(mode.startsWith("admission-only") ? { admissionOnly: true } : {}),
environment: { PATH: process.env.PATH, OPENAI_API_KEY: mode === "api-key" ? "selected-account" : "", HOME: "/unrelated/home" },
environment: { PATH: process.env.PATH, OPENAI_API_KEY: mode === "api-key" ? "selected-account" : "", HOME: preconfigured ? root : "/unrelated/home", ...(preconfigured ? { CODEX_HOME: sourceHome } : {}) },
timeoutMs: mode.startsWith("late-remote-") ? 800 : mode === "late-bootstrap" ? 100 : mode === "missing-completion" ? 1_000 : 10_000,
...(remote ? { workingDirectory: remoteWorkspace } : {}),
transportOptions: {
...(preconfigured ? { homeMode: "preconfigured" as const } : {}),
...(remote ? {
runnerFilesystemRoot: remoteFilesystem, runnerStateDirectory: join(remoteRoot, "runner"),
readRunnerState: async () => JSON.parse(await readFile(join(remoteRoot, "runner", "runner-state.json"), "utf8")),
controlPlaneRegistration: async authority => {
await mkdir(remoteWorkspace, { recursive: true, mode: 0o700 });
if (!preconfigured) {
const remoteHome = join(remoteFilesystem, "codex-home");
await mkdir(remoteHome, { mode: 0o700 });
for (const name of ["auth.json", "config.toml"] as const) await cp(join(runtimeDirectory, "codex-home", name), join(remoteHome, name));
}
if (mode.startsWith("late-remote-")) await new Promise(resolve => setTimeout(resolve, 1000));
await authority.start();
return { connectUrl: authority.connectUrl, release: async () => { registrationReleased = true; await authority.stop(); if (mode === "late-remote-release-error") throw new Error("PRP registration release failed"); } };
@@ -4722,7 +4727,7 @@ it.each(["admission-only", "admission-only-mismatched-model", "complete", "api-k
...(mode === "late-bootstrap" ? ["--thread-start-delay-ms", "1000"] : [])),
sourceCodexHome: sourceHome,
},
onCodexCredentialRefresh: async filename => {
onCodexCredentialRefresh: preconfigured ? undefined : async filename => {
expect(filename).toBe(join(remote ? remoteFilesystem : runtimeDirectory, "codex-home", "auth.json"));
expect(JSON.parse(await readFile(filename, "utf8"))).toEqual({ OPENAI_API_KEY: "selected-account" });
if (mode === "api-key") {
@@ -4734,16 +4739,21 @@ it.each(["admission-only", "admission-only-mismatched-model", "complete", "api-k
if (mode === "model-refresh-error") throw new Error("credential refresh failed after the native model error");
},
onCleanupConfirmed: async () => {
if (preconfigured) {
await expect(stat(join(runtimeDirectory, "codex-home"))).rejects.toMatchObject({ code: "ENOENT" });
if (remote) await expect(stat(join(remoteFilesystem, "codex-home"))).rejects.toMatchObject({ code: "ENOENT" });
}
cleanupConfirmed = true;
expect(refreshed || mode === "missing-runtime" || mode === "late-bootstrap" || mode.startsWith("late-remote-")).toBe(true);
expect(preconfigured || refreshed || mode === "missing-runtime" || mode === "late-bootstrap" || mode.startsWith("late-remote-")).toBe(true);
if (mode === "model-cleanup-error") throw new Error("owned temporary state cleanup failed");
await rm(runtimeDirectory, { recursive: true, force: true });
},
});
if (mode === "admission-only" || mode === "complete" || mode === "api-key" || mode === "default-model" || mode === "remote-complete") {
if (preconfigured || mode === "admission-only" || mode === "complete" || mode === "api-key" || mode === "default-model" || mode === "remote-complete") {
const observedModel = mode === "default-model" ? "gpt-test" : "gpt-6.1-sol";
await expect(probe).resolves.toEqual({ provider: "codex", providerDriver: "codex_app_server", effectiveModel: observedModel, ...(mode === "admission-only" ? { helloProbePassed: false, admissionOnly: true, sessionAdmissionPassed: true } : { helloProbePassed: true }) });
expect(refreshed).toBe(true);
expect(refreshed).toBe(!preconfigured);
if (preconfigured) expect(await readFile(join(sourceHome, "config.toml"), "utf8")).toBe('model = "native-model"\n');
if (remote) expect(registrationReleased).toBe(true);
expect(cleanupConfirmed).toBe(true);
await expect(stat(runtimeDirectory)).rejects.toThrow();
@@ -9327,6 +9327,7 @@ export async function probeNativeRunnerEnvironment(options: {
const environment = { ...options.environment };
const remoteFilesystemRoot = options.transportOptions?.runnerFilesystemRoot;
const ownsPreparation = options.transportOptions?.prepareLaunch !== undefined;
const preconfiguredHome = options.transportOptions?.homeMode === "preconfigured";
if (options.workingDirectory !== undefined && !remoteFilesystemRoot && !ownsPreparation) throw new Error("Native setup remote working directory requires a remote runner filesystem.");
const workingDirectory = options.workingDirectory ?? resolve(options.runtimeDirectory, "workspace");
if (!remoteFilesystemRoot && !ownsPreparation) mkdirSync(workingDirectory, { mode: 0o700 });
@@ -9348,9 +9349,9 @@ export async function probeNativeRunnerEnvironment(options: {
};
let registrationCleanupConfirmed = true;
const cleanupBudget = probeCleanupBudget(options.cleanupTimeoutMs);
const sourceCodexHome = ownsPreparation ? undefined : options.transportOptions?.sourceCodexHome ?? resolveSourceCodexHome(environment);
const sourceCodexHome = ownsPreparation || preconfiguredHome ? undefined : options.transportOptions?.sourceCodexHome ?? resolveSourceCodexHome(environment);
delete environment.PAPERCLIP_RUNNER_EXTERNAL_SANDBOX;
if (!ownsPreparation) {
if (!ownsPreparation && !preconfiguredHome) {
environment.HOME = resolve(remoteFilesystemRoot ?? options.runtimeDirectory, "probe-home");
environment.CODEX_HOME = resolve(remoteFilesystemRoot ?? options.runtimeDirectory, "codex-home");
}
+1
View File
@@ -12,6 +12,7 @@ export interface LocalEnvironmentConfig {
}
export interface SshEnvironmentConfig {
useHostAuth?: boolean;
host: string;
port: number;
username: string;
@@ -16,6 +16,23 @@ import {
import { sessionCodec as acpxSessionCodec } from "@paperclipai/adapter-utils/acpx-engine/session-codec";
describe("adapter session codecs", () => {
it.each([claudeSessionCodec.serialize, claudeSessionCodec.deserialize])("keeps only normalized Claude remote identity and valid conversation references", transform => {
const params = {
sessionId: "11111111-1111-4111-8111-111111111111",
sshClaudeConversationId: "a".repeat(64), sshClaudeAccountScope: "b".repeat(64),
remoteExecution: { transport: "ssh", host: "fixture.example.test", port: 22, username: "agent", remoteCwd: "/work",
useHostAuth: false, privateKey: "fixture-private-key", tailscaleSocksProxySocketPath: "/fixture/socket" },
};
const output = transform(params)!;
expect(output).toMatchObject({ sessionId: params.sessionId, sshClaudeConversationId: params.sshClaudeConversationId,
sshClaudeAccountScope: params.sshClaudeAccountScope, remoteExecution: { transport: "ssh", host: "fixture.example.test", useHostAuth: false } });
expect(JSON.stringify(output)).not.toContain("fixture-private-key");
expect(JSON.stringify(output)).not.toContain("/fixture/socket");
const invalid = transform({ ...params, sshClaudeConversationId: "../../untrusted" })!;
expect(invalid.sshClaudeConversationId).toBeUndefined();
expect(invalid.sshClaudeAccountScope).toBeUndefined();
});
it("normalizes claude session params with cwd", () => {
const parsed = claudeSessionCodec.deserialize({
session_id: "claude-session-1",
@@ -575,6 +575,24 @@ describe("agent test-environment route", () => {
expect(mockCopilotModels).not.toHaveBeenCalled();
});
it.each([undefined, true, false])("uses the selected SSH authentication source for probes (%s)", async useHostAuth => {
const environmentId = "11111111-1111-4111-8111-111111111111";
mockEnvironmentService.getById.mockResolvedValue({ id: environmentId, name: "SSH", driver: "ssh",
config: { ...(useHostAuth !== undefined ? { useHostAuth } : {}), host: "fixture.invalid", username: "fixture", remoteWorkspacePath: "/workspace" } });
const target = { kind: "remote", transport: "ssh", remoteCwd: "/workspace", spec: { host: "fixture.invalid", port: 22, username: "fixture", remoteCwd: "/workspace", remoteWorkspacePath: "/workspace", useHostAuth } };
mockResolveEnvironmentExecutionTarget.mockResolvedValue(target);
const response = await request(await createApp()).post("/api/companies/company-1/adapters/external_test/test-environment")
.send({ adapterConfig: {}, environmentId });
if (useHostAuth === false) {
expect(response.status, JSON.stringify(response.body)).toBe(422);
expect(response.body.code).toBe("ssh_ai_connection_required");
expect(testEnvironmentSpy).not.toHaveBeenCalled();
} else {
expect(response.status, JSON.stringify(response.body)).toBe(200);
expect(testEnvironmentSpy).toHaveBeenCalledWith(expect.objectContaining({ executionTarget: target }));
}
});
it("tests the instance default sandbox when the agent inherits its environment", async () => {
const environmentId = "11111111-1111-4111-8111-111111111111";
mockInstanceSettingsService.get.mockResolvedValue({ defaultEnvironmentId: environmentId });
@@ -27,6 +27,8 @@ import { legacyExecutionNeedsReconciliation } from "../services/legacy-execution
import { getServerAdapter, registerServerAdapter, unregisterServerAdapter } from "../adapters/index.js";
import { waitForPendingRunFailureReports } from "../services/run-failure-report.js";
import { dotRunnerBroker } from "../services/dot-runner-broker.js";
import { environmentService } from "../services/environments.js";
import * as executionConfiguration from "../services/heartbeat/execution-configuration.js";
const captureRunFailure = vi.hoisted(() => vi.fn());
vi.mock("../sentry.js", async (importOriginal) => ({
@@ -446,6 +448,52 @@ describe("durable, authorized connection routing", () => {
expect(resolveTaskSessionConfigFreshness({ hasTaskSession: true, configuredModel: String(selected.runtimeConfig.model), taskSessionParams: { __paperclipConfiguredModel: selected.runtimeConfig.model, __paperclipConfigFingerprint: previous.fingerprint, __paperclipConfigFingerprintVersion: previous.version, __paperclipConfigCategoryFingerprints: previous.categoryFingerprints }, configMetadata: current, compatibleConfigMetadata }).reset).toBe(false);
} finally { await before.cleanup(); await after.cleanup(); }
});
it.each([
{ useHostAuth: undefined, nativeHomeMode: undefined }, { useHostAuth: true, nativeHomeMode: undefined },
{ useHostAuth: false, nativeHomeMode: undefined }, { useHostAuth: false, nativeHomeMode: "preconfigured" },
])("applies SSH authentication before selecting a busy pool (%j)", async ({ useHostAuth, nativeHomeMode }) => {
const original = await instanceSettingsService(db).getExperimental();
await instanceSettingsService(db).updateExperimental({ enableAiConnectionRouters: true, enableNativeRunner: true, enableEnvironments: true, enableWorktreeRunExecution: true });
const pool = await makePool({ members: [members[0]!] });
const environment = await environmentService(db).create(companyId, { name: `SSH routing fixture ${useHostAuth} ${nativeHomeMode}`, driver: "ssh", status: "active", envVars: {}, config: {
host: "ssh.example.test", username: "fixture", remoteWorkspacePath: "/workspace", ...(useHostAuth === undefined ? {} : { useHostAuth }),
} });
const configured = { provider: "acpx", acpxAgent: "claude", model: "fixture-host-model", ...(nativeHomeMode ? { homeMode: nativeHomeMode } : {}) };
const [agent] = await db.insert(agents).values({ companyId, name: "SSH routing fixture", status: "idle", adapterType: "paperclip_runner",
adapterConfig: configured, defaultEnvironmentId: environment.id,
runtimeConfig: { aiConnection: { mode: "router", connectionId: pool.id }, heartbeat: { enabled: false, wakeOnDemand: true } } }).returning();
const [issue] = await db.insert(issues).values({ companyId, title: "SSH pool routing fixture", status: "todo", assigneeAgentId: agent.id, responsibleUserId: "alice", createdByUserId: "alice" }).returning();
proposal.mockClear();
proposal.mockImplementation(async () => ({ kind: "exhausted", retryAt: new Date(Date.now() + 60_000).toISOString(), skipped: {} }));
const preparation = vi.spyOn(executionConfiguration, "prepareHeartbeatExecutionConfiguration").mockRejectedValue(new Error("fixture stopped before provider configuration"));
const heartbeat = heartbeatService(db, { pluginWorkerManager: worker, runtimeEnv: {} });
try {
const run = await heartbeat.wakeup(agent.id, { source: "assignment", reason: "issue_assigned", triggerDetail: "system",
payload: { issueId: issue.id }, contextSnapshot: { issueId: issue.id, responsibleUserId: "alice" } });
expect(run).not.toBeNull();
await heartbeat.drainActiveRunExecutions();
const saved = await heartbeat.getRun(run!.id);
if (useHostAuth === false) {
expect(proposal).toHaveBeenCalled();
expect(preparation).not.toHaveBeenCalled();
expect(saved?.errorCode).toBe("ai_connection_pool_exhausted");
} else {
expect(proposal).not.toHaveBeenCalled();
expect(saved?.contextSnapshot?.aiRouterSelection).toBeUndefined();
expect(saved?.error).toContain("fixture stopped before provider configuration");
expect(preparation).toHaveBeenCalledWith(expect.anything(), expect.objectContaining({ config: expect.objectContaining({
aiBinding: undefined, sourceWorkspaceConfig: expect.objectContaining(configured),
}) }));
}
} finally {
await db.update(agents).set({ status: "paused" }).where(eq(agents.id, agent.id));
await heartbeat.drainActiveRunExecutions();
preparation.mockRestore();
proposal.mockImplementation(defaultProposal);
await instanceSettingsService(db).updateExperimental(original);
}
}, 30_000);
it("admits a healthy pool member when the saved Grok connection is held", async () => {
const original = await instanceSettingsService(db).getExperimental();
await instanceSettingsService(db).updateExperimental({ enableAiConnectionRouters: true,
@@ -61,8 +61,11 @@ function oracle(db: Db, scope: AttentionRetentionScope, cursor?: Cursor, sourceI
async function seed(company: string, prefix: string, status: string, size: number) {
await db.execute(sql`insert into companies (id, name, issue_prefix, status) values (${company}::uuid, ${prefix}, ${prefix}, ${status})`);
await db.execute(sql`insert into agents (company_id, name, status)
select ${company}::uuid, 'Agent ' || n, case when n % 3 = 0 then 'error' else 'idle' end from generate_series(1, 6) n`);
// Put error agents in the archived and kept retention positions. The
// unretained error added below guarantees a candidate of this kind.
await db.execute(sql`insert into agents (id, company_id, name, status)
select (left(${company}::text, 24) || lpad(n::text, 12, '0'))::uuid,
${company}::uuid, 'Agent ' || n, case when n in (4, 6) then 'error' else 'idle' end from generate_series(1, 6) n`);
// Issues: blocked, in review, hidden, harness-owned and ordinary ones.
await db.execute(sql`insert into issues (company_id, title, status, hidden_at, harness_kind, updated_at)
select ${company}::uuid, 'Issue ' || n,
@@ -108,6 +111,8 @@ function oracle(db: Db, scope: AttentionRetentionScope, cursor?: Cursor, sourceI
union all select company_id, 'decision', id::text, row_number() over (order by id) from decisions where company_id = ${company}::uuid
union all select company_id, 'agent_error_alert', id::text, row_number() over (order by id) from agents where company_id = ${company}::uuid
) x where n % 2 = 0`);
await db.execute(sql`insert into agents (company_id, name, status)
values (${company}::uuid, 'Unretained error agent', 'error')`);
}
beforeAll(async () => {
@@ -3,6 +3,17 @@ import { HttpError } from "../errors.js";
import { normalizeEnvironmentConfig, parseEnvironmentDriverConfig } from "../services/environment-config.ts";
describe("environment config helpers", () => {
it.each([undefined, true, false])("preserves SSH authentication compatibility when useHostAuth is %s", useHostAuth => {
const config = normalizeEnvironmentConfig({ driver: "ssh", config: {
host: "ssh.example.test", username: "fixture", remoteWorkspacePath: "/workspace",
...(useHostAuth !== undefined ? { useHostAuth } : {}),
} });
expect(config.useHostAuth).toBe(useHostAuth);
expect(Object.hasOwn(config, "useHostAuth")).toBe(useHostAuth !== undefined);
expect(() => normalizeEnvironmentConfig({ driver: "ssh", config: { ...config, useHostAuth: "false" } })).toThrow(HttpError);
});
it("normalizes SSH config into its canonical stored shape", () => {
const config = normalizeEnvironmentConfig({
driver: "ssh",
@@ -2111,6 +2111,27 @@ describe("environment routes", () => {
);
});
it.each([undefined, true, false])("defaults new SSH API environments to managed auth while preserving explicit %s", async (useHostAuth) => {
const environment = { ...createEnvironment(), driver: "ssh" as const, config: createSshConfig() };
mockEnvironmentService.create.mockResolvedValue(environment);
const app = createApp(localBoardActor());
const res = await request(app).post("/api/companies/company-1/environments").send({
name: "SSH Fixture", driver: "ssh", config: { ...createSshConfig(), ...(useHostAuth === undefined ? {} : { useHostAuth }) },
});
expect(res.status).toBe(201);
expect(mockEnvironmentService.create.mock.calls[0]![0].config.useHostAuth).toBe(useHostAuth ?? false);
});
it("preserves absent authentication on an existing SSH API environment update", async () => {
const environment = { ...createEnvironment(), id: "env-ssh", driver: "ssh" as const, config: createSshConfig() };
mockEnvironmentService.getById.mockResolvedValue(environment);
mockEnvironmentService.update.mockResolvedValue(environment);
const app = createApp(localBoardActor());
const res = await request(app).patch("/api/environments/env-ssh").send({ config: { host: "changed.example.test" } });
expect(res.status).toBe(200);
expect(mockEnvironmentService.update.mock.calls[0]![1].config).not.toHaveProperty("useHostAuth");
});
it("rejects invalid SSH config on create", async () => {
const app = createApp(localBoardActor());
@@ -25,7 +25,7 @@ import * as assignedMcp from "../services/native-runtime/assigned-mcp-tools.js";
import * as sentry from "../sentry.js";
import { waitForPendingRunFailureReports } from "../services/run-failure-report.js";
import { recoveryPostgresSupport, startRecoveryPostgres } from "./helpers/recovery-postgres.js";
import { selectHeartbeatEnvironment, type HeartbeatEnvironmentSelectionInput } from "../services/heartbeat/environment-selection.js";
import { selectHeartbeatEnvironment, resolveSshAuthenticationBeforeRouting, type HeartbeatEnvironmentSelectionInput } from "../services/heartbeat/environment-selection.js";
import { environmentService } from "../services/environments.js";
import { executionWorkspaceService } from "../services/execution-workspaces.js";
import { buildExecutionWorkspaceAdapterConfig } from "../services/execution-workspace-policy.js";
@@ -41,6 +41,21 @@ function deferred<T>() {
const skillFailures = vi.hoisted(() => new Map<string, string>());
const skillWaits = vi.hoisted(() => new Map<string, () => Promise<void>>());
describe("SSH authentication before account routing", () => {
it.each([
{ agentDefaultEnvironmentId: "agent", lowTrustIssueEnvironmentId: null, executionMode: "any", expectedId: "agent", expected: "host" },
{ agentDefaultEnvironmentId: null, lowTrustIssueEnvironmentId: null, executionMode: "any", expectedId: "instance", expected: "host" },
{ agentDefaultEnvironmentId: "agent", lowTrustIssueEnvironmentId: "sandbox", executionMode: "any", expectedId: "sandbox", expected: null },
{ agentDefaultEnvironmentId: "agent", lowTrustIssueEnvironmentId: null, executionMode: "kubernetes", expectedId: null, expected: null },
] as const)("honors environment precedence and forced execution policy: %j", async value => {
const get = vi.fn(async () => ({ defaultEnvironmentId: "instance", general: { executionMode: value.executionMode } }));
const getById = vi.fn(async (id: string) => ({ id, driver: id === "sandbox" ? "sandbox" : "ssh", config: {} } as Environment));
expect(await resolveSshAuthenticationBeforeRouting({ ...value, instanceSettings: { get }, environmentsSvc: { getById } })).toBe(value.expected);
if (value.expectedId) expect(getById).toHaveBeenCalledExactlyOnceWith(value.expectedId);
else expect(getById).not.toHaveBeenCalled();
});
});
describe("Runner home mode during recovery preparation", () => {
const fingerprint = (effectiveAdapterConfig: Record<string, unknown>) => buildEffectiveRunSessionConfigMetadata({
adapterType: "paperclip_runner", effectiveAdapterConfig, agentRuntimeConfig: {}, issueOverrides: null,
@@ -333,7 +348,7 @@ describePostgres("heartbeat execution configuration through adapter dispatch", (
}
});
async function configuration(f: Awaited<ReturnType<typeof seed>>, config: Record<string, unknown>, snapshot: Record<string, unknown> = {}, type = "paperclip_runner", explicitTaskDirectory = false, requestedExecutionWorkspaceMode: HeartbeatExecutionConfigurationInput["policy"]["requestedExecutionWorkspaceMode"] = "shared_workspace", selectedEnvironmentForConfig: HeartbeatExecutionConfigurationInput["environment"]["selectedEnvironmentForConfig"] = null, pinnedSkillTest?: HeartbeatExecutionConfigurationInput["task"]["pinnedSkillTest"], adoptingLiveRunner = false) {
async function configuration(f: Awaited<ReturnType<typeof seed>>, config: Record<string, unknown>, snapshot: Record<string, unknown> = {}, type = "paperclip_runner", explicitTaskDirectory = false, requestedExecutionWorkspaceMode: HeartbeatExecutionConfigurationInput["policy"]["requestedExecutionWorkspaceMode"] = "shared_workspace", selectedEnvironmentForConfig: HeartbeatExecutionConfigurationInput["environment"]["selectedEnvironmentForConfig"] = null, pinnedSkillTest?: HeartbeatExecutionConfigurationInput["task"]["pinnedSkillTest"], adoptingLiveRunner = false, aiBinding?: HeartbeatExecutionConfigurationInput["config"]["aiBinding"]) {
const [agent] = await db.update(agents).set({ adapterType: type, adapterConfig: config }).where(eq(agents.id, f.agentId)).returning();
const [run] = await db.insert(heartbeatRuns).values({ companyId: f.companyId, agentId: f.agentId, issueId: f.issueId, scopeKind: "issue", status: "running", contextSnapshot: snapshot }).returning();
const resolvedInstanceSettings = await instanceSettingsService(db).get();
@@ -344,7 +359,7 @@ describePostgres("heartbeat execution configuration through adapter dispatch", (
task: { issueId: f.issueId, context: { ...snapshot, issueId: f.issueId }, responsibleUserId: null, pinnedSkillTest, adoptingLiveRunner,
acceptedPlanContinuationWake: false, acceptedPlanWakeRoutingDecision: null,
taskProjectContext: null, routineEnvContext: { routineId: null, env: null, responsibleUserId: null } },
config: { sourceWorkspaceConfig: config, aiBinding: undefined },
config: { sourceWorkspaceConfig: config, aiBinding },
policy: { trustPreset: { kind: "standard", preset: "standard", boundary: null, sourcePresets: {} }, useIsolatedTaskDirectory: false, explicitTaskDirectory, requestedExecutionWorkspaceMode },
environment: { selectedEnvironmentId: environment.id, selectedEnvironmentForConfig: environment,
resolvedInstanceSettings, persistedNativeExecutionInput: adoptingLiveRunner
@@ -356,6 +371,46 @@ describePostgres("heartbeat execution configuration through adapter dispatch", (
}) };
}
it.each([undefined, true, false])("defaults existing SSH environments to remote authentication and honors the saved choice (saved=%s)", async useHostAuth => {
const f = await seed(true);
const environment = { ...await environmentService(db).ensureLocalEnvironment(), driver: "ssh", config: { ...(useHostAuth !== undefined ? { useHostAuth } : {}), host: "fixture.invalid", username: "fixture", remoteWorkspacePath: "/workspace" } } as Environment;
const binding = aiConnectionBindingSchema.parse((await db.select().from(agents).where(eq(agents.id, f.agentId)))[0]!.runtimeConfig!.aiConnection);
const prepare = vi.spyOn(aiRuntime, "prepareManagedAiRuntime").mockRejectedValue(new Error("fixture managed account reached"));
const opening = await configuration(f, { provider: "codex" }, {}, "paperclip_runner", false, "shared_workspace", environment, undefined, false, binding);
if (useHostAuth !== false) {
const result = await opening.prepare();
expect(result.prepared).toBe(true);
if (!result.prepared) throw new Error("SSH configuration failed");
expect(result.runtimeConfig.homeMode).toBe("preconfigured");
expect(prepare).not.toHaveBeenCalled();
} else {
await expect(opening.prepare()).rejects.toThrow("fixture managed account reached");
expect(prepare).toHaveBeenCalledOnce();
}
});
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;
const opening = await configuration(f, { provider: "codex" }, {}, "paperclip_runner", false, "shared_workspace", environment);
await expect(opening.prepare()).rejects.toMatchObject({ resultJson: { configurationIncomplete: { reason: "ssh_ai_connection_required" } } });
});
it("delivers the Studio pin instead of ordinary assignments and recovers that exact native selection", async () => {
const f = await seed(), skills = companySkillService(db);
const selected = await skills.createLocalSkill(f.companyId, { name: "Unassigned Studio skill", markdown: "# Studio\nOriginal selected bytes.\n" });
@@ -24,7 +24,7 @@ vi.mock("node:child_process", async importOriginal => {
spawn: (file: string, args: string[], options: Parameters<typeof actual.spawn>[2]) => {
if (file !== "ssh") return actual.spawn(file, args, options);
mocks.wire.push({ file, args, stdin: true });
return actual.spawn(process.execPath, ["-e", 'process.stdout.write(require("node:fs").readFileSync(0,"utf8"))'], options);
return actual.spawn(process.execPath, ["-e", 'const wire = require("node:fs").readFileSync(0); process.stdout.write(wire.subarray(wire.indexOf(10) + 1))'], options);
},
};
});
+13 -3
View File
@@ -3265,6 +3265,7 @@ export function agentRoutes(
return { connectionId: selection.connection.id };
}
const testEnvironment = testEnvironmentId ? await environmentsSvc.getById(testEnvironmentId) : null;
if (testEnvironment?.driver === "ssh" && testEnvironment.config.useHostAuth !== false) return { connectionId: selection.connection.id };
if (adapterType === "paperclip_runner" && config.homeMode === "preconfigured" && testEnvironment
&& await pluginEnvironmentRunnerTaskDriver(db, testEnvironment)) {
throw unprocessable(pluginRunnerAiConnectionRequiredMessage(true), { code: PLUGIN_RUNNER_AI_CONNECTION_REQUIRED });
@@ -3302,7 +3303,7 @@ export function agentRoutes(
await assertCanCreateAgentsForCompany(req, companyId);
const requestedBinding = req.body.aiConnection ? aiRuntimeConnectionBindingSchema.parse(req.body.aiConnection) : undefined;
const aiBinding = requestedBinding?.mode === "router" ? undefined : requestedBinding;
let aiBinding = requestedBinding?.mode === "router" ? undefined : requestedBinding;
if (aiBinding && req.body.testCredentials && Object.keys(req.body.testCredentials).length) throw unprocessable("A managed connection test cannot override its credentials");
const inputAdapterConfig = aiBinding ? { ...req.body.adapterConfig, env: stripAiAuthBindings(req.body.adapterConfig?.env) } : (req.body?.adapterConfig ?? {}) as Record<string, unknown>;
const savedAgentId = typeof req.body.agentId === "string" ? req.body.agentId : null;
@@ -3315,7 +3316,7 @@ export function agentRoutes(
await assertCanConfigureAgentSetup(req, savedAgent);
}
const testingSetup = savedAgent ? isAgentSetupDraft(savedAgent) : false;
const poolBinding = requestedBinding ?? (savedAgent?.runtimeConfig?.aiConnection ? aiRuntimeConnectionBindingSchema.parse(savedAgent.runtimeConfig.aiConnection) : undefined);
let poolBinding = requestedBinding ?? (savedAgent?.runtimeConfig?.aiConnection ? aiRuntimeConnectionBindingSchema.parse(savedAgent.runtimeConfig.aiConnection) : undefined);
const prospectiveCursorDefault = type === "cursor_cloud" && !savedAgent
&& (req.body.runner === undefined || req.body.runner === "auto")
&& managedCursorApiDefaultEnabled((await instanceSettings.get()).experimental);
@@ -3350,6 +3351,14 @@ export function agentRoutes(
const requestedEnvironment = requestedEnvironmentId
? await assertAdapterTestEnvironmentBinding(companyId, requestedEnvironmentId)
: null;
if (requestedEnvironment?.driver === "ssh" && requestedEnvironment.config.useHostAuth !== false) {
aiBinding = undefined;
poolBinding = undefined;
}
if (requestedEnvironment?.driver === "ssh" && requestedEnvironment.config.useHostAuth === false) {
if (!aiBinding && poolBinding?.mode !== "router") aiBinding = poolBinding;
if (!aiBinding && !poolBinding) throw unprocessable("Select an AI account for this agent or enable authentication configured on the remote machine in the SSH environment's advanced settings.", { code: "ssh_ai_connection_required" });
}
// Agent reads redact every plain environment value. When this is a saved
// agent test, restore those display-only placeholders from the
// server-side config before validating or resolving secrets; otherwise
@@ -3384,7 +3393,8 @@ export function agentRoutes(
defaultEnvironmentId: requestedEnvironmentId,
});
type = selection.adapterType;
adapterConfigForTest = selection.adapterConfig;
adapterConfigForTest = { ...selection.adapterConfig,
...(type === "paperclip_runner" && requestedEnvironment?.driver === "ssh" ? { homeMode: requestedEnvironment.config.useHostAuth === false ? "isolated" : "preconfigured" } : {}) };
if (requestedEnvironment) await assertAdapterTestEnvironmentForCompany(companyId, requestedEnvironment.id, type);
const adapter = requireServerAdapter(type);
if (!retainsSavedExecution) await assertSelectableAdapterType(type, adapterConfigForTest, companyId);
+1
View File
@@ -1086,6 +1086,7 @@ export function environmentRoutes(
),
config: await normalizeEnvironmentConfigForPersistence({
db,
operation: "create",
companyId,
environmentName: req.body.name,
driver: req.body.driver,
+2 -34
View File
@@ -1,3 +1,5 @@
import { managedAiHomeEnvironment } from "@paperclipai/adapter-utils/managed-ai-runtime-env";
export { managedAiSessionFingerprintConfig } from "@paperclipai/adapter-utils/managed-ai-runtime-env";
import { environmentTaskResultSchema } from "@paperclipai/plugin-sdk";
import type { ManagedAiCredentialWritebackBinding } from "./managed-ai-credential-writeback.js";
import { OPENROUTER_ATTRIBUTION_HEADERS, openRouterClaudeHeaders } from "@paperclipai/shared/openrouter-attribution";
@@ -208,40 +210,6 @@ done`,
}
}
function managedAiHomeEnvironment(home: string): Record<string, string> {
const providerHome = path.join(home, "provider");
return {
HOME: home,
XDG_CONFIG_HOME: path.join(home, "config"),
XDG_DATA_HOME: path.join(home, "data"),
CODEX_HOME: providerHome,
GROK_HOME: providerHome,
CLAUDE_CONFIG_DIR: providerHome,
HERMES_HOME: providerHome,
};
}
/** Only the server-created credential home is volatile; retain all other config. */
export function managedAiSessionFingerprintConfig(
config: Record<string, unknown>,
managedHome: string | undefined,
): Record<string, unknown> {
if (!managedHome) return config;
const env = { ...(config.env as Record<string, unknown> | undefined) };
const stable = managedAiHomeEnvironment("<managed-ai-home>");
for (const [key, value] of Object.entries(managedAiHomeEnvironment(managedHome))) {
if (env[key] === value) env[key] = stable[key];
}
if (env.GEMINI_HOME === path.join(managedHome, "provider")) env.GEMINI_HOME = path.join("<managed-ai-home>", "provider");
const managed = config.managedAiConnection as Record<string, unknown> | undefined;
if (managed?.sessionIdentity) {
for (const key of ["ANTHROPIC_API_KEY", "ANTHROPIC_AUTH_TOKEN", "CLAUDE_CODE_OAUTH_TOKEN", "OPENAI_API_KEY", "CODEX_API_KEY", "OPENROUTER_API_KEY", "XAI_API_KEY", "GROK_API_KEY", "GEMINI_API_KEY", "GOOGLE_API_KEY", "OPENCODE_AUTH_JSON", "OPENCODE_CONFIG_CONTENT"]) {
if (env[key]) env[key] = "<managed-ai-credential>";
}
}
return { ...config, env, ...(managed?.sessionIdentity ? { managedAiConnection: { ...managed, identity: managed.sessionIdentity } } : {}) };
}
export async function prepareManagedAiRuntime(
db: Db,
input: {
@@ -38,6 +38,7 @@ const secretRefSchema = z.object({
}).strict();
const sshEnvironmentConfigSchema = z.object({
useHostAuth: z.boolean().optional(),
host: z.string({ error: "SSH environments require a host." }).trim().min(1, "SSH environments require a host."),
port: z.coerce.number().int().min(1).max(65535).default(22),
username: z.string({ error: "SSH environments require a username." }).trim().min(1, "SSH environments require a username."),
@@ -545,6 +546,7 @@ export function normalizeEnvironmentConfigForProbe(input: {
export async function normalizeEnvironmentConfigForPersistence(input: {
db: Db;
operation?: "create" | "update";
companyId: string;
environmentName: string;
driver: EnvironmentDriver;
@@ -583,6 +585,7 @@ export async function normalizeEnvironmentConfigForPersistence(input: {
}
return {
...stored,
...(input.operation === "create" ? { useHostAuth: stored.useHostAuth ?? false } : {}),
privateKey: null,
privateKeySecretRef: nextPrivateKeySecretRef,
} satisfies SshEnvironmentConfig;
@@ -699,6 +699,7 @@ export async function resolveEnvironmentExecutionTarget(input: {
leaseId: input.leaseId ?? null,
remoteCwd,
spec: {
useHostAuth: parsed.config.useHostAuth !== false,
host: parsed.config.host,
port: parsed.config.port,
username: parsed.config.username,
+11 -2
View File
@@ -58,7 +58,7 @@ import { readRecoverableRunLog } from "./native-runtime/native-run-log-recovery.
import { observabilitySecretValues } from "@paperclipai/adapter-utils/agent-observability";
import { prepareHeartbeatSession, resolveHeartbeatAdapterSession } from "./heartbeat/session-preparation.js";
import { prepareHeartbeatTaskContext } from "./heartbeat/task-context.js";
import { selectHeartbeatEnvironment } from "./heartbeat/environment-selection.js";
import { selectHeartbeatEnvironment, resolveSshAuthenticationBeforeRouting } from "./heartbeat/environment-selection.js";
import { reconcileMuseNativeTerminalRun } from "./native-runtime/muse-terminal-reconciliation.js";
import { prepareHeartbeatWorkspace, RetryWorkspaceRefused } from "./heartbeat/workspace-preparation.js";
import { nativeRecoveryClaimRelinquished, ownNativeExecutionLeaseLapsed, releaseLapsedNativeRestartClaim } from "./native-runtime/native-execution-lease.js";
@@ -2715,8 +2715,17 @@ export function heartbeatService(
if ("homeMode" in homeConfig) config = { ...config, homeMode: homeConfig.homeMode };
}
const persistedRouterPoolId = routerHasPersistedInput ? readNonEmptyString(parseObject(context.aiRouterSelection).poolId) : null;
const sshAuthentication = routerHasPersistedInput ? null : await resolveSshAuthenticationBeforeRouting({
agentDefaultEnvironmentId: agent.defaultEnvironmentId,
lowTrustIssueEnvironmentId: trustPreset.kind === "low_trust_review"
? parseIssueExecutionWorkspaceSettings(issueContext?.executionWorkspaceSettings, { includeEnvironmentId: true })?.environmentId ?? null : null,
environmentsSvc, instanceSettings,
});
if (agent.adapterType === "paperclip_runner" && sshAuthentication) {
config = { ...config, homeMode: sshAuthentication === "host" ? "preconfigured" : "isolated" };
}
const preconfiguredHome = agent.adapterType === "paperclip_runner" && config.homeMode === "preconfigured";
const requestedAiBinding = preconfiguredHome ? undefined : persistedRouterPoolId ? { mode: "router" as const, connectionId: persistedRouterPoolId } : agent.runtimeConfig?.aiConnection ? aiRuntimeConnectionBindingSchema.parse(agent.runtimeConfig.aiConnection) : undefined;
const requestedAiBinding = preconfiguredHome || sshAuthentication === "host" ? undefined : persistedRouterPoolId ? { mode: "router" as const, connectionId: persistedRouterPoolId } : agent.runtimeConfig?.aiConnection ? aiRuntimeConnectionBindingSchema.parse(agent.runtimeConfig.aiConnection) : undefined;
let aiBinding = requestedAiBinding?.mode === "router" ? undefined : requestedAiBinding;
const originalAiIssueOverrides = issueAssigneeOverrides;
if (requestedAiBinding?.mode === "router") {
@@ -3,7 +3,7 @@ import { heartbeatExternalProvider, nativeExecutionUsesTaskWorkspace } from "./e
import { heartbeatRuns, issues, type Db, type agents } from "@paperclipai/db";
import { and, eq } from "drizzle-orm";
import { readGitCacheExpiration } from "../git-workspace-restoration.js";
import type { ExecutionWorkspace, IssueExecutionWorkspaceSettings, ProjectExecutionWorkspacePolicy } from "@paperclipai/shared";
import type { ExecutionWorkspace, InstanceSettings, IssueExecutionWorkspaceSettings, ProjectExecutionWorkspacePolicy } from "@paperclipai/shared";
import { parseObject } from "../../adapters/utils.js";
import { logger } from "../../middleware/logger.js";
import { parseNativeExecutionInput } from "../../vendor/paperclip-runner/index.js";
@@ -39,6 +39,23 @@ import { resolveNativeRecoveryExecutionWorkspaceBinding, resolveExecutionWorkspa
type Issue = typeof issues.$inferSelect;
export async function resolveSshAuthenticationBeforeRouting(input: {
agentDefaultEnvironmentId: string | null;
lowTrustIssueEnvironmentId: string | null;
environmentsSvc: Pick<ReturnType<typeof environmentService>, "getById">;
instanceSettings: { get(): Promise<{
defaultEnvironmentId: InstanceSettings["defaultEnvironmentId"];
general: Pick<InstanceSettings["general"], "executionMode">;
}> };
}): Promise<"host" | "managed" | null> {
const settings = await input.instanceSettings.get();
if (isExecutionForcedToKubernetes({ executionMode: settings.general.executionMode })) return null;
const id = input.lowTrustIssueEnvironmentId ?? input.agentDefaultEnvironmentId ?? settings.defaultEnvironmentId;
if (!id) return null;
const environment = await input.environmentsSvc.getById(id);
return environment?.driver === "ssh" ? environment.config.useHostAuth === false ? "managed" : "host" : null;
}
/** Selects policy and reuse inputs; lease acquisition and cleanup belong to the executor. */
export interface HeartbeatEnvironmentSelectionInput {
run: Pick<typeof heartbeatRuns.$inferSelect,
@@ -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";
@@ -118,9 +119,14 @@ export async function prepareHeartbeatExecutionConfiguration(db: Db, input: Hear
const time = createHeartbeatPreparationTiming(run.id);
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), 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) {
@@ -154,7 +160,12 @@ export async function prepareHeartbeatExecutionConfiguration(db: Db, input: Hear
// The executor keeps these values in its failure redactor before any later
// preparation step can fail. Subsequent provider/identity values extend it.
onFailureSecretsResolved(() => []);
const aiBinding = preconfiguredHome ? undefined : input.config.aiBinding;
const aiBinding = preconfiguredHome || useSshHostAuth ? undefined : input.config.aiBinding;
if (selectedEnvironmentForConfig?.driver === "ssh" && selectedEnvironmentForConfig.config.useHostAuth === false && !aiBinding && !persistedNativeExecutionInput) {
throw new ConfigurationIncompleteFailure("Select an AI account for this agent or enable authentication configured on the remote machine in the SSH environment's advanced settings.", {
configurationIncomplete: { reason: "ssh_ai_connection_required", actionUrl: `/agents/${agent.id}/runtime` },
});
}
const { trustPreset } = input.policy;
const { secretsSvc, companySkills, appendRunEvent, finalizeAiConnectionBusyDeferral } = input.services;
let managedAiRuntime: ManagedAiRuntime | undefined;
@@ -182,6 +182,43 @@ describe.skipIf(!support.supported)("heartbeat runtime selection boundary", () =
expect(await coordinators(f.run.id)).toHaveLength(1);
});
it.each(["isolated", "preconfigured"] as const)("pins the prepared %s home mode into fresh native selection and recovery", async homeMode => {
const f = await fixture();
f.agent.adapterConfig = { ...f.agent.adapterConfig, homeMode: homeMode === "isolated" ? "preconfigured" : "isolated" };
f.input.config.runtimeConfig.homeMode = homeMode;
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(homeMode);
const saved = await read(f.run.id);
f.input.run = saved;
f.input.session.persistedRunnerProfile = saved.runnerProfileJson ?? {};
f.input.session.persistedNativeExecutionInput = selected.nativeExecution;
f.input.config.runtimeConfig.homeMode = homeMode === "isolated" ? "preconfigured" : "isolated";
expect(await selectHeartbeatRuntime(db, f.input)).toMatchObject({ selected: true, nativeExecution: selected.nativeExecution });
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 {
@@ -771,7 +772,7 @@ export async function selectHeartbeatRuntime(db: Db, input: HeartbeatRuntimeSele
instructionWorkingCopy: instructionCopy ? { rootPath: instructionCopy.executionRoot, entryPath: instructionCopy.entryFile, ...(isAgentDirectoryCopy(instructionCopy) ? { kind: "agent_files" as const } : {}) } : undefined,
}));
getNativeFreshSessionHandoff = nativeReviewRequest ? undefined : getFreshSessionHandoff;
const nativeProviderConfig = nativeRuntimeResolution.profile.backend === "cursor_cloud_api"
const projectedNativeProviderConfig = nativeRuntimeResolution.profile.backend === "cursor_cloud_api"
|| nativeRuntimeResolution.profile.backend === "codex_app_server"
|| (nativeRuntimeResolution.profile.backend === "acpx_runtime" && ["claude_local", "grok_local"].includes(agentHarnessType(agent.adapterType, parseObject(agent.adapterConfig))))
|| nativeRuntimeResolution.profile.backend === "opencode_server"
@@ -784,6 +785,12 @@ export async function selectHeartbeatRuntime(db: Db, input: HeartbeatRuntimeSele
managedAiRuntime ? readNonEmptyString(resolvedConfig.model) ?? undefined : undefined,
)
: agent.adapterConfig;
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,
backend: nativeRuntimeResolution.profile.backend,
@@ -21613,7 +21613,7 @@ describe("runnerd provider runtime wiring", () => {
homeMode: "preconfigured" as const, executionMode: "default" as const, planningContext: null,
provider: { kind: "codex" as const, model: null, approvalPolicy: "never" as const }, runtimeContext: nativeRuntimeContextFixture() };
const remoteExecute = vi.fn(async (command: { args?: string[] }) => ({
exitCode: 0, timedOut: false, stderr: "", stdout: command.args?.[1]?.includes("getent passwd") ? "/home/executor\n" : "",
exitCode: 0, timedOut: false, stderr: "", stdout: command.args?.includes("paperclip-remote-home") ? "/home/executor\n" : "",
}));
await createRunnerdBackend({ db: leaseDb(remoteExecution), execution: remoteExecution, runnerInstanceId: "remote-home-manifest",
runnerEnvironment, runnerIngressAuthorized: true, runnerExecutionTarget: {
@@ -22092,7 +22092,7 @@ describe("runnerd provider runtime wiring", () => {
if (command.args?.[0] === "--version") return {
exitCode: 0, timedOut: false, stdout: "codex-cli 0.160.0", stderr: "",
};
if (command.args?.[1]?.includes("getent passwd")) return {
if (command.args?.includes("paperclip-remote-home")) return {
exitCode: 0, timedOut: false, stdout: "/home/executor\n", stderr: "",
};
if (command.args?.[2] === "paperclip-runner-launch") {
@@ -233,6 +233,7 @@ import type { NativeRunnerAttachmentDownload, NativeRunnerAttachmentStage } from
import { discoverRemoteExecutable, parseRemoteExecutableCandidate } from "./codex-model-fallback.js";
export { parseRemoteExecutableCandidate } from "./codex-model-fallback.js";
import type { CommandManagedRuntimeRunner } from "@paperclipai/adapter-utils/command-managed-runtime";
import { readRemoteUserHome } from "./remote-user-home.js";
import { NativeRunnerIngressAcquisitionError, prepareNativeRemoteRunner, createNativeRunnerExecutionDriver, resolveRemoteRunnerTransportMode } from "./native-runner-execution-driver.js";
import type { Db } from "@paperclipai/db";
import {
@@ -18048,14 +18049,7 @@ async function createRunnerdBackendWithinSessionClaim(
delete effectiveRunnerEnvironmentBase.PAPERCLIP_RUNNER_PREPARED_HARNESS_HOME;
if (preconfiguredHome) {
if (remoteCommandRunner) {
const discovered = await remoteCommandRunner.execute({
command: "sh", args: ["-c", 'getent passwd "$(id -u)" | cut -d: -f6'],
bypassSession: true, timeoutMs: 10_000,
});
const home = discovered.stdout.trim();
if (discovered.exitCode !== 0 || discovered.timedOut || !home.startsWith("/") || /[\0\r\n]/.test(home)) {
throw new Error("runner_preconfigured_remote_home_unavailable");
}
const home = await readRemoteUserHome(remoteCommandRunner);
// Paths from the controller's account cannot select a remote account's config.
const hostPathKeys = new Set(["CODEX_HOME", "CLAUDE_CONFIG_DIR", "XDG_CONFIG_HOME", "XDG_DATA_HOME", "XDG_CACHE_HOME"]);
const configured = configuredEnvironment(effectiveRunnerEnvironmentBase);
@@ -58,7 +58,7 @@ describe("native SSH deliverable output budget", () => {
});
it("still delivers every byte when SSH consumes the upload", async () => {
await writeFile(join(root, "ssh"), `#!${process.execPath}\nconst hash = require('node:crypto').createHash('sha256');\nprocess.stdin.on('data', chunk => hash.update(chunk));\nprocess.stdin.on('end', () => process.stdout.write(hash.digest('hex')));\n`);
await writeFile(join(root, "ssh"), `#!${process.execPath}\nconst chunks = [];\nprocess.stdin.on('data', chunk => chunks.push(chunk));\nprocess.stdin.on('end', () => { const wire = Buffer.concat(chunks); const end = wire.indexOf(10); if (end < 0) process.exit(1); process.stdout.write(require('node:crypto').createHash('sha256').update(wire.subarray(end + 1)).digest('hex')); });\n`);
const stdin = "synthetic upload bytes\0".repeat(32_768);
const result = await createRunner().execute({ command: "node", args: ["unused"], stdin, timeoutMs: 5000 });
expect(result.exitCode).toBe(0);
@@ -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
@@ -0,0 +1,11 @@
import type { CommandManagedRuntimeRunner } from "@paperclipai/adapter-utils/command-managed-runtime";
export async function readRemoteUserHome(runner: Pick<CommandManagedRuntimeRunner, "execute">): Promise<string> {
const result = await runner.execute({ command: "sh", args: ["-c", 'printf "%s\\n" "$HOME"', "paperclip-remote-home"],
bypassSession: true, timeoutMs: 10_000 });
const home = result.stdout.trim();
if (result.exitCode !== 0 || result.timedOut || !home.startsWith("/") || /[\0\r\n]/.test(home)) {
throw new Error("runner_preconfigured_remote_home_unavailable");
}
return home;
}
@@ -330,6 +330,31 @@ describe("Codex selected native account verification", () => {
expect(await readFile(join(home, "account-store.json"), "utf8")).toBe(auth);
} finally { await rm(home, { recursive: true, force: true }); }
});
it.each(["valid", "invalid home"])("probes the native SSH user's login without reading controller credentials (%s)", async mode => {
vi.stubEnv("HOME", "/controller-only/home");
vi.stubEnv("CODEX_HOME", "/controller-only/codex");
vi.stubEnv("OPENAI_API_KEY", "fixture-controller-key");
const readCredential = vi.spyOn(localCredentialFile, "readLocalAiCredentialFile");
sshExecute.mockImplementation(async command => ({ exitCode: 0, timedOut: false, stderr: "", stdout: command.args?.includes("paperclip-remote-home") ? (mode === "valid" ? "/home/remote-user\n" : "relative-home\n") : "" }));
nativeProbe.mockImplementation(async input => {
expect(input.environment.HOME).toBe("/home/remote-user");
expect(input.environment.CODEX_HOME).toBeUndefined();
expect(input.environment.OPENAI_API_KEY).toBeUndefined();
expect(input.transportOptions.homeMode).toBe("preconfigured");
expect(input.transportOptions.sourceCodexHome).toBe("");
expect(input.onCodexCredentialRefresh).toBeUndefined();
await input.onCleanupConfirmed();
return receipt("codex", "gpt-6.1-sol");
});
const result = await testNativeRunnerAuthentication({ ...sshContext, config: { homeMode: "preconfigured", env: { CODEX_HOME: "/controller-only/configured-home" } } }, "codex", "gpt-6.1-sol");
expect(result.status).toBe(mode === "valid" ? "pass" : "fail");
expect(readCredential).not.toHaveBeenCalled();
if (mode === "valid") expect(nativeProbe).toHaveBeenCalledOnce();
else expect(nativeProbe).not.toHaveBeenCalled();
expect(sshExecute.mock.calls.some(([command]) => JSON.stringify(command).includes("controller-only"))).toBe(false);
readCredential.mockRestore();
});
it.each(["linux-arm64", "linux-x64"])("uses task staging and the selected %s SSH daemon without a provider pack", async target => {
const selectedBinary = `/fixture/bin/${target}/paperclip-runnerd`;
selectedRemoteRunner.mockResolvedValue(selectedBinary);
@@ -9,6 +9,7 @@ import { ADAPTER_AUTH_MISSING_CHECK_CODE } from "@paperclipai/shared";
import { NativeEnvironmentProbeCleanupError, probeNativeRunnerEnvironment, resolveSourceCodexHome } from "../../vendor/paperclip-runner/index.js";
import { resolvePaperclipRunnerBinary, resolveRemotePaperclipRunnerBinary } from "./native-codex-runner.js";
import { readLocalAiCredentialFile } from "../local-ai-credential-file.js";
import { readRemoteUserHome } from "./remote-user-home.js";
import { createNativeSshCommandRunner } from "./native-ssh-command-runner.js";
import { resolvePaperclipRunnerTransport } from "@paperclipai/adapter-utils/runner-connectivity";
import { createNativeRunnerExecutionDriver } from "./native-runner-execution-driver.js";
@@ -97,6 +98,12 @@ async function probeRemoteNativeCodex(options: {
const { createRemoteNativeArtifactPreparation, createRemoteRunnerProcessLauncher, stageRemoteRunnerFile, readRemoteRunnerState } = await import("./native-session-executor.js");
const runner = target.transport === "ssh" ? createNativeSshCommandRunner({ spec: target.spec, defaultCwd: target.remoteCwd }) : target.runner;
if (!runner) throw new Error("runner_transport_ineligible: remote process runner is unavailable");
const preconfigured = target.transport === "ssh" && options.context.config.homeMode === "preconfigured";
const environment = { ...options.environment };
if (preconfigured) {
delete environment.CODEX_HOME;
environment.HOME = await readRemoteUserHome(runner);
}
const id = crypto.randomUUID();
const runnerInstanceId = `setup-${id}`;
const ingress = target.transport === "sandbox" && target.effectiveCapabilities?.runnerWebSocketIngress === true;
@@ -122,14 +129,15 @@ async function probeRemoteNativeCodex(options: {
};
const runtimeDirectory = await realpath(await mkdtemp(join(tmpdir(), "paperclip-native-setup-")));
return probePreparedNativeRuntime(runtimeDirectory, async () => {
const sourceCodexHome = await prepareProbeCodexSource(runtimeDirectory, options.sourceCodexHome, options.sourceAuthJson);
const sourceCodexHome = preconfigured ? "" : await prepareProbeCodexSource(runtimeDirectory, options.sourceCodexHome, options.sourceAuthJson);
let remoteDirectoryCreated = false;
let signalSpawned!: () => void;
const spawned = new Promise<void>(resolve => { signalSpawned = resolve; });
return { runtimeDirectory: runtimeDirectory, provider: "codex", model: options.model, reasoningEffort: options.reasoningEffort,
workingDirectory: remoteWorkspace, environment: options.environment, timeoutMs: options.timeoutMs,
workingDirectory: remoteWorkspace, environment, timeoutMs: options.timeoutMs,
transportOptions: {
externallySandboxed: target.transport === "sandbox",
...(preconfigured ? { homeMode: "preconfigured" as const } : {}),
runnerBinary: controllerRunnerBinary, codexCommand: remoteCodexBinary, sourceCodexHome,
runnerFilesystemRoot: remoteFilesystemRoot,
prpIdentity: { runnerInstanceId, runId: id, environmentLeaseId: `setup-${id}`, normalizedSessionId: `setup-${id}`, turnId: `turn-${id}`, itemId: `item-${id}` },
@@ -157,6 +165,7 @@ async function probeRemoteNativeCodex(options: {
runnerProcessLauncher: createRemoteRunnerProcessLauncher({ target, runner, remoteBinary, stateDirectory: remoteStateDirectory,
onRunnerProcessSpawned: signalSpawned, processIdentityPath: posix.join(remoteStateDirectory, "runner-process.identity"), diagnosticsDirectory: posix.join(remoteRoot, "diagnostics"), runnerInstanceId,
ensureArtifact: async () => {
if (preconfigured) return;
for (const name of ["auth.json", "config.toml"] as const) {
const sourcePath = join(runtimeDirectory, "codex-home", name);
try { await stat(sourcePath); } catch (error) { if ((error as NodeJS.ErrnoException).code === "ENOENT") continue; throw error; }
@@ -205,7 +214,7 @@ export async function testNativeRunnerAuthentication(context: AdapterEnvironment
let runtimeDirectory: string | undefined;
let sourceAuthJson: string | undefined;
try {
if (provider === "codex") {
if (provider === "codex" && !(context.executionTarget?.kind === "remote" && context.executionTarget.transport === "ssh" && context.config.homeMode === "preconfigured")) {
const { buildNativeProviderEnvironment } = await import("./native-session-executor.js");
sourceCodexHome = context.managedAiCredentialHome ?? resolveSourceCodexHome(buildNativeProviderEnvironment(environment));
}
@@ -394,7 +394,7 @@
"packages/shared/src/types/decision.ts": "b0d40077d481ce6180de6b02bad6df5bb0fbf977",
"packages/shared/src/types/document-annotation.ts": "7769a42f1ccd707a2259774e7fe6aa536b5d183f",
"packages/shared/src/types/email.ts": "556ff6a0dcefa01eb704d6d00d3b191de81ff4dc",
"packages/shared/src/types/environment.ts": "a380b9ce9d2d1763011e9adaa58615a3ef1e56c5",
"packages/shared/src/types/environment.ts": "16b9d9598abfa2583602181b44483b0fa24d5bc2",
"packages/shared/src/types/execution-continuation.ts": "5afe62afd227efa03ff847d8f73291c14707ab5b",
"packages/shared/src/types/execution-projection.ts": "7a4b8567cb1a8204f9e9f878eb594b745a0428cc",
"packages/shared/src/types/external-object.ts": "7a225e0f5a6777d449019a30530c858b753eb4c1",
+26
View File
@@ -696,6 +696,32 @@ describe("CompanyEnvironments — test provider button", () => {
expect(buttons[1].disabled).toBe(true);
});
it("defaults new SSH environments to the agent's Paperclip account", async () => {
root = createRoot(container);
const queryClient = new QueryClient({ defaultOptions: { queries: { retry: false } } });
await act(async () => { root!.render(renderCompanyEnvironments(queryClient, `${ENVIRONMENTS_PATH}/new`)); });
await waitForAssertion(() => {
const toggle = getEnvironmentFormPage()?.querySelector('[aria-label="Use authentication configured on the remote machine"]');
expect(toggle?.getAttribute("aria-checked")).toBe("false");
expect(toggle?.closest("details")?.open).toBe(false);
});
});
it.each([undefined, true, false])("preserves the remote-auth option when editing an existing SSH environment (saved=%s)", async useHostAuth => {
mockEnvironmentsApi.list.mockResolvedValue([{ id: "env-existing-ssh", name: "Existing SSH", driver: "ssh", description: null, envVars: {},
config: { ...(useHostAuth !== undefined ? { useHostAuth } : {}), host: "ssh.example.test", username: "developer", port: 22, remoteWorkspacePath: "/workspace", strictHostKeyChecking: true } }]);
root = createRoot(container);
const queryClient = new QueryClient({ defaultOptions: { queries: { retry: false } } });
await act(async () => { root!.render(renderCompanyEnvironments(queryClient, `${ENVIRONMENTS_PATH}/env-existing-ssh/edit`)); });
await waitForAssertion(() => {
expect(getEnvironmentFormPage()?.querySelector('[aria-label="Use authentication configured on the remote machine"]')?.getAttribute("aria-checked")).toBe(String(useHostAuth !== false));
});
await act(async () => { click(findButton(getEnvironmentFormPage()!, "Save environment")); });
await waitForAssertion(() => {
expect(mockEnvironmentsApi.update).toHaveBeenCalledWith("env-existing-ssh", expect.objectContaining({ config: expect.objectContaining({ useHostAuth: useHostAuth !== false }) }), "company-1");
});
});
it("opens the add-environment form on a standalone page and closes it on cancel", async () => {
root = createRoot(container);
const queryClient = new QueryClient({ defaultOptions: { queries: { retry: false } } });
+16
View File
@@ -70,6 +70,7 @@ type EnvironmentFormState = {
name: string;
description: string;
driver: "local" | "ssh" | "sandbox";
sshUseHostAuth: boolean;
sshHost: string;
sshPort: string;
sshUsername: string;
@@ -126,6 +127,7 @@ function buildEnvironmentPayload(form: EnvironmentFormState) {
config:
form.driver === "ssh"
? {
useHostAuth: form.sshUseHostAuth,
host: form.sshHost.trim(),
port: Number.parseInt(form.sshPort || "22", 10) || 22,
username: form.sshUsername.trim(),
@@ -152,6 +154,7 @@ function createEmptyEnvironmentForm(): EnvironmentFormState {
name: "",
description: "",
driver: "ssh",
sshUseHostAuth: false,
sshHost: "",
sshPort: "22",
sshUsername: "",
@@ -182,6 +185,7 @@ function normalizeNonLocalEnvironmentId(
function readSshConfig(environment: Environment) {
const config = environment.config ?? {};
return {
useHostAuth: config.useHostAuth !== false,
host: typeof config.host === "string" ? config.host : "",
port:
typeof config.port === "number"
@@ -227,6 +231,7 @@ function createEnvironmentFormFromEnvironment(environment: Environment): Environ
name: environment.name,
description: environment.description ?? "",
driver: "ssh",
sshUseHostAuth: ssh.useHostAuth,
sshHost: ssh.host,
sshPort: ssh.port,
sshUsername: ssh.username,
@@ -2378,6 +2383,17 @@ export function CompanyEnvironments({ mode = "list" }: CompanyEnvironmentsProps)
onChange={(e) => setEnvironmentForm((current) => ({ ...current, sshKnownHosts: e.target.value }))}
/>
</Field>
<details className="md:col-span-2">
<summary className="cursor-pointer text-sm font-medium">Advanced</summary>
<div className="pt-3">
<ToggleField
label="Use authentication configured on the remote machine"
hint="Use the remote user's provider login instead of the agent's Paperclip AI account."
checked={environmentForm.sshUseHostAuth}
onChange={(checked) => setEnvironmentForm((current) => ({ ...current, sshUseHostAuth: checked }))}
/>
</div>
</details>
<div className="md:col-span-2">
<ToggleField
label="Strict host key checking"