Use agent AI accounts in SSH environments

Stage the selected agent account in a private remote home and restore refreshed credentials before cleanup. Preserve remote authentication for existing SSH environments and expose it as an advanced option.

Co-Authored-By: Paperclip <noreply@paperclip.ing>
This commit is contained in:
Devin FoleyandPaperclip committed 2026-11-12 17:08:59 -08:00
1 parent 2dcfdabc79
commit 8490bf9df2
41 files changed
+4471 -3774

No files matched your search

+34
View File
@@ -433,6 +433,40 @@ 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.
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. A disconnected target can prevent remote cleanup; the run reports
the resulting failure rather than silently selecting another account.
ACP SSH sessions use the existing remote process bridge and session reuse
lifecycle. 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. 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,69 @@ 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 home = path.join(root, "selected-account");await fs.mkdir(home);
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 } };
const restore = vi.fn(async () => {}), 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]) => {
const stagedRuntime = await input.stage([{ key: "home", localDir: home }]);
input.env.CODEX_HOME = stagedRuntime.assetDirs.home!;
return { stagedRuntime };
});
const actual = await vi.importActual<typeof import("@paperclipai/adapter-utils/execution-target")>("@paperclipai/adapter-utils/execution-target");
vi.mocked(prepareAdapterExecutionTargetRuntime).mockResolvedValueOnce({ 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 config = { agent: "custom", agentCommand: "node ./fake-acp.js", stateDir, cwd: localCwd,
managedAiConnection: { identity: "selected-agent-account" }, env: { CODEX_HOME: home, HOME: home }, mode: "persistent" };
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);
expect(restore).toHaveBeenCalledOnce();
expect(stopControl).toHaveBeenCalledOnce();
expect(stopProcess).toHaveBeenCalledOnce();
expect(dispose).not.toHaveBeenCalled();
const resumed = await runExecutor(config, { ...options, runId: "run-2", runtime: { sessionParams: result.result.sessionParams } });
expect(resumed.sessionInputs[0]?.cwd).toBe(result.sessionInputs[0]?.cwd);
expect(seam).toHaveBeenCalledOnce();
expect(restore).toHaveBeenCalledTimes(2);
if (failure === "bridge") {
vi.mocked(startAdapterExecutionTargetProcessSessionBridge).mockRejectedValueOnce(new Error("fixture SSH bridge unavailable"));
await expect(runExecutor(config, { ...options, runId: "run-3", runtime: { sessionParams: resumed.result.sessionParams } })).rejects.toThrow("fixture SSH bridge unavailable");
} else {
failTurn = true;
await runExecutor(config, { ...options, runId: "run-3", expectedExitCode: 1, runtime: { sessionParams: resumed.result.sessionParams } });
}
expect(restore).toHaveBeenCalledTimes(3);
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);
} 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,4 @@
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 +22,7 @@ import type {
UsageSummary,
} from "@paperclipai/adapter-utils";
import {
managedRemoteHomeEnvironment,
adapterExecutionTargetSessionIdentity,
describeAdapterExecutionTarget,
adapterExecutionTargetDuplexObservabilityRecorder,
@@ -506,6 +508,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">;
// 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 +1747,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 +1773,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 +2239,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 +2285,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 +2294,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,
@@ -2331,8 +2333,15 @@ async function buildRuntime(input: {
// resolvedAdapterEnv, so they don't churn the fingerprint every heartbeat.
adapterEnvHash: shortHash(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 +2399,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"> | 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
@@ -2413,23 +2423,27 @@ async function buildRuntime(input: {
env,
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 +2456,18 @@ 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,
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 +2502,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,
@@ -2521,6 +2542,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 +2558,23 @@ async function buildRuntime(input: {
stagedRuntime = placedStaged?.stagedRuntime ?? null;
remoteManagedHomeTeardown = placedStaged?.teardown ?? null;
remoteStagingDispose = placedStaged?.dispose ?? null;
if (remoteTarget.transport === "ssh") {
const owner = { teardown: remoteManagedHomeTeardown, dispose: remoteStagingDispose };
remoteStagingOwner = owner;
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 +2751,7 @@ async function buildRuntime(input: {
stagedRuntime,
remoteManagedHomeTeardown,
remoteStagingDispose,
...(remoteStagingOwner ? { remoteStagingOwner } : {}),
remoteStagingEnvDelta,
sessionStagingLeaseRelease,
remoteExecutionIdentity,
@@ -3741,8 +3782,8 @@ function saveStagedRuntimeAfterCleanTurn(input: {
observabilityCompatibilityKey: input.observabilityCompatibilityKey,
stagedRuntime: prepared.stagedRuntime,
envDelta: prepared.remoteStagingEnvDelta,
teardown: prepared.remoteManagedHomeTeardown,
dispose: prepared.remoteStagingDispose,
teardown: prepared.remoteStagingOwner?.teardown ?? prepared.remoteManagedHomeTeardown,
dispose: prepared.remoteStagingOwner?.dispose ?? prepared.remoteStagingDispose,
lastUsedAt: input.now,
});
}
@@ -237,6 +237,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", () => {
+15 -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));
}
/**
@@ -1492,6 +1495,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 +1557,8 @@ export async function prepareAdapterExecutionTargetRuntime(input: {
workspaceLocalDir: input.workspaceLocalDir,
workspaceRemoteDir: input.workspaceRemoteDir,
syncWorkspace: input.syncWorkspace,
privateRuntime: input.privateRuntime && target.spec.useHostAuth === false,
retainRuntime: input.retainRuntime,
workspaceFileMode: input.workspaceFileMode,
workspaceExclude: input.workspaceExclude,
assets: input.assets,
@@ -1568,6 +1575,7 @@ export async function prepareAdapterExecutionTargetRuntime(input: {
// reports a per-project staging failure.
additionalSourceFailures: [],
workspaceSyncSnapshot: null,
disposeRuntime: prepared.disposeRuntime,
restoreWorkspace: prepared.restoreWorkspace,
};
}
@@ -2071,7 +2079,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 +2090,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 +2099,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 +2191,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 +2544,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
@@ -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"),
};
}
@@ -11,7 +11,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 +61,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 +69,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);
@@ -53,6 +53,7 @@ export interface PreparedRemoteManagedRuntime {
* absent (per-project failure isolation).
*/
additionalSourceDirs: Record<string, string>;
disposeRuntime(): Promise<void>;
restoreWorkspace(onProgress?: RuntimeProgressSink): Promise<void>;
}
@@ -85,6 +86,7 @@ export function buildRemoteExecutionSessionIdentity(spec: SshRemoteExecutionSpec
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 +101,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 +116,8 @@ export async function prepareRemoteManagedRuntime(input: {
workspaceLocalDir: string;
workspaceRemoteDir?: string;
syncWorkspace?: boolean;
privateRuntime?: boolean;
retainRuntime?: boolean;
workspaceFileMode?: "all";
workspaceExclude?: string[];
assets?: RemoteManagedRuntimeAsset[];
@@ -133,7 +138,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 +180,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 +201,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 +211,7 @@ export async function prepareRemoteManagedRuntime(input: {
onProgress: input.onProgress,
repositories: repositoryBaselines,
});
}
} finally { await cleanupPrivateRuntime(); }
throw error;
}
@@ -243,6 +261,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 +295,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;
@@ -3739,6 +3740,7 @@ async function resolveSpawnTarget(
args: spawnTarget.args,
cwd: process.cwd(),
cleanup: spawnTarget.cleanup,
stdinPrefix: spawnTarget.stdinPrefix,
};
}
@@ -4839,6 +4841,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];
@@ -4848,7 +4851,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);
@@ -5002,7 +5005,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;
@@ -5022,7 +5025,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);
});
});
@@ -2,6 +2,7 @@ import { mkdtemp, rm } 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")>();
@@ -38,6 +39,14 @@ async function runner() {
}
describe("SSH command-managed argv", () => {
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");
+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 --decode) || 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,
@@ -1330,19 +1334,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();
}
@@ -1356,6 +1355,7 @@ export async function buildSshSpawnTarget(input: {
}): Promise<{
command: string;
args: string[];
stdinPrefix: string;
cleanup: () => Promise<void>;
}> {
for (const key of Object.keys(input.env)) {
@@ -1395,12 +1395,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 } : {}) };
}
});
@@ -310,6 +310,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,
@@ -958,24 +959,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);
}
@@ -11,6 +11,7 @@ const {
prepareWorkspaceForSshExecution,
restoreWorkspaceFromSshExecution,
syncDirectoryToSsh,
runSshCommand,
startAdapterExecutionTargetPaperclipBridge,
} = vi.hoisted(() => ({
runChildProcess: vi.fn(async (_runId: string, _command: string, args: string[]): Promise<RunProcessResult> => ({
@@ -33,6 +34,7 @@ const {
prepareWorkspaceForSshExecution: vi.fn(async () => ({ gitBacked: false })),
restoreWorkspaceFromSshExecution: vi.fn(async () => undefined),
syncDirectoryToSsh: vi.fn(async () => 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",
@@ -64,6 +66,7 @@ vi.mock("@paperclipai/adapter-utils/ssh", async () => {
prepareWorkspaceForSshExecution,
restoreWorkspaceFromSshExecution,
syncDirectoryToSsh,
runSshCommand,
};
});
@@ -95,6 +98,48 @@ describe("claude remote execution", () => {
}
});
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
+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?.();
}
}
@@ -26,7 +26,7 @@ const {
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: "" })),
runSshCommand: vi.fn(async (_spec?: unknown, _command?: string) => ({ stdout: Buffer.from("{}").toString("base64"), stderr: "" })),
syncDirectoryToSsh: vi.fn(async () => undefined),
startAdapterExecutionTargetPaperclipBridge: vi.fn(async () => ({
env: {
@@ -88,6 +88,56 @@ describe("codex remote execution", () => {
}
});
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("uses the remote Codex login without uploading the controller's home when host authentication is enabled", async () => {
const root = await mkdtemp(path.join(os.tmpdir(), "paperclip-codex-host-auth-"));
cleanupDirs.push(root);
const home = path.join(root, "controller-home");
await mkdir(home);
await writeFile(path.join(home, "auth.json"), '{"tokens":{"account_id":"controller-only","refresh_token":"fixture-controller-token"}}');
vi.stubEnv("CODEX_HOME", home);
vi.stubEnv("PAPERCLIP_HOME", path.join(root, "paperclip"));
try {
await execute({ runId: "remote-auth", 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" }, context: { paperclipWorkspace: { cwd: root, source: "project_primary" } },
executionTransport: { remoteExecution: { useHostAuth: true, host: "127.0.0.1", port: 2222, username: "fixture", remoteCwd: "/workspace", remoteWorkspacePath: "/workspace", privateKey: null, knownHosts: null, strictHostKeyChecking: true } }, onLog: async () => {},
});
expect(syncDirectoryToSsh).not.toHaveBeenCalled();
const invocation = runChildProcess.mock.calls[0] as unknown as [string, string, string[], { env: Record<string, string> }];
expect(invocation[3].env.CODEX_HOME).toBeUndefined();
expect(invocation[3].env.HOME).toBeUndefined();
expect(await readFile(path.join(home, "auth.json"), "utf8")).toContain("controller-only");
} finally { vi.unstubAllEnvs(); }
});
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);
File diff suppressed because it is too large. Load diff
@@ -17,6 +17,7 @@ import {
describeAdapterExecutionTarget,
resolveAdapterExecutionTargetCwd,
prepareAdapterExecutionTargetRuntime,
managedRemoteHomeEnvironment,
} from "@paperclipai/adapter-utils/execution-target";
import fs from "node:fs/promises";
import path from "node:path";
@@ -94,6 +95,9 @@ 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;
@@ -157,7 +161,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 +168,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 +175,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 +188,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",
@@ -212,7 +215,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 &&
@@ -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);
+1
View File
@@ -12,6 +12,7 @@ export interface LocalEnvironmentConfig {
}
export interface SshEnvironmentConfig {
useHostAuth?: boolean;
host: string;
port: number;
username: string;
@@ -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 });
@@ -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",
@@ -333,7 +333,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 +344,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 +356,31 @@ 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("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" });
+13 -3
View File
@@ -3262,6 +3262,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 });
@@ -3299,7 +3300,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;
@@ -3312,7 +3313,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);
@@ -3347,6 +3348,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
@@ -3381,7 +3390,8 @@ export function agentRoutes(
defaultEnvironmentId: requestedEnvironmentId,
});
type = selection.adapterType;
adapterConfigForTest = selection.adapterConfig;
adapterConfigForTest = { ...selection.adapterConfig,
...(type === "paperclip_runner" && requestedEnvironment?.driver === "ssh" && requestedEnvironment.config.useHostAuth !== false ? { homeMode: "preconfigured" } : {}) };
if (requestedEnvironment) await assertAdapterTestEnvironmentForCompany(companyId, requestedEnvironment.id, type);
const adapter = requireServerAdapter(type);
if (!retainsSavedExecution) await assertSelectableAdapterType(type, adapterConfigForTest, companyId);
@@ -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."),
@@ -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,
@@ -99,9 +99,10 @@ 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;
const sourceWorkspaceConfig = agent.adapterType === "paperclip_runner"
? { ...input.config.sourceWorkspaceConfig,
homeMode: bindHeartbeatRunnerHomeMode(parseObject(agent.adapterConfig), persistedNativeExecutionInput).homeMode }
homeMode: bindHeartbeatRunnerHomeMode({ ...parseObject(agent.adapterConfig), ...(useSshHostAuth ? { homeMode: "preconfigured" } : {}) }, persistedNativeExecutionInput).homeMode }
: input.config.sourceWorkspaceConfig;
const preconfiguredHome = agent.adapterType === "paperclip_runner" && sourceWorkspaceConfig.homeMode === "preconfigured";
if (preconfiguredHome && pinnedSkillTest) {
@@ -135,7 +136,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, useIsolatedTaskDirectory, explicitTaskDirectory, requestedExecutionWorkspaceMode } = input.policy;
const { secretsSvc, companySkills, appendRunEvent, finalizeAiConnectionBusyDeferral } = input.services;
let managedAiRuntime: ManagedAiRuntime | undefined;
+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"