Keep PATH when checking managed SSH ACP prerequisites

Managed SSH ACP checked its command with an empty environment. The shared
resolver needs the controller PATH to locate the local SSH client, so the
default Claude and Codex ACP commands were rejected before startup.

Retain only PATH for the SSH prerequisite check. Keep sandbox behavior and
controller credential exclusion intact. Exercise the real resolver from both
public execution entries with a fixture SSH executable and an empty PATH.
Clarify the local prerequisite and remote installation requirements in docs.

Validation: reproduced four default/explicit ACP failures before the fix;
140 provider tests and both provider typechecks pass after the fix.

Co-Authored-By: Paperclip <noreply@paperclip.ing>
This commit is contained in:
Devin FoleyandPaperclip committed 2026-11-13 04:00:21 -08:00
1 parent 342a87ba12
commit 0495fad19a
5 files changed
+62 -14

No files matched your search

+4 -2
View File
@@ -483,10 +483,12 @@ account-scoped conversation references across server persistence.
ACP SSH sessions use the existing remote process bridge and session reuse
lifecycle. Both provider adapters admit managed SSH through their public
execution entry points when the remote ACP command is available. SSH ACP needs
execution entry points. SSH ACP needs
an agent-managed account and a copied workspace. Host authentication, in-place
SSH workspaces, and local filesystem/network confinement require the CLI engine.
Command availability checks do not send controller credentials to the SSH host.
The SSH prerequisite check retains only the controller's `PATH` to resolve the
local SSH client; it excludes controller credentials. The ACP server command
must be installed on the remote machine and is started there by the process bridge.
A compatible session can retain its private remote home; workspace
sync and credential refresh run at turn teardown, and the session disposal hook
removes the home on retirement. Workspace identity includes the company, agent,
@@ -565,7 +565,7 @@ async function commandIsResolvable(
trimmed,
target,
resolveAdapterExecutionTargetCwd(target, asString(input?.config.cwd, ""), process.cwd()),
{},
target.transport === "ssh" ? { PATH: process.env.PATH } : {},
{
// Fresh sandboxes need the same ACP server that ships with this
// adapter. Only bootstrap our default command; an operator's custom
@@ -33,7 +33,7 @@ const {
pid: 123,
startedAt: new Date().toISOString(),
})),
ensureCommandResolvable: vi.fn(async () => undefined),
ensureCommandResolvable: vi.fn<typeof import("@paperclipai/adapter-utils/server-utils").ensureCommandResolvable>(async () => undefined),
resolveCommandForLogs: vi.fn(async () => "ssh://fixture@127.0.0.1:2222/remote/workspace :: claude"),
prepareWorkspaceForSshExecution: vi.fn(async () => ({ gitBacked: false })),
restoreWorkspaceFromSshExecution: vi.fn(async () => undefined),
@@ -123,6 +123,14 @@ describe("claude remote execution", () => {
it.each([undefined, "acp"])("admits managed SSH ACP through the public execution entry (engine=%s)", async engine => {
const ctx = managedSshAcpContext(engine);
const actual = await vi.importActual<typeof import("@paperclipai/adapter-utils/server-utils")>("@paperclipai/adapter-utils/server-utils");
const bin = await mkdtemp(path.join(os.tmpdir(), "paperclip-ssh-client-probe-"));
cleanupDirs.push(bin);
await writeFile(path.join(bin, "ssh"), "#!/bin/sh\nexit 0\n", { mode: 0o700 });
const originalResolve = ensureCommandResolvable.getMockImplementation()!;
ensureCommandResolvable.mockImplementationOnce(actual.ensureCommandResolvable);
const previousPath = process.env.PATH;
process.env.PATH = bin;
const previous = process.env.CLAUDE_CODE_OAUTH_TOKEN;
process.env.CLAUDE_CODE_OAUTH_TOKEN = "fixture-server-secret";
try {
@@ -130,15 +138,19 @@ describe("claude remote execution", () => {
expect(executeAcp).toHaveBeenCalledWith(ctx);
const probe = ensureCommandResolvable.mock.calls[0] as unknown as unknown[];
expect(probe[0]).toBe("claude-agent-acp");
expect(Object.keys(probe[2] as Record<string, unknown>)).toEqual([]);
expect(Object.keys(probe[2] as Record<string, unknown>)).toEqual(["PATH"]);
expect((probe[2] as Record<string, unknown>).PATH === bin).toBe(true);
expect(probe[3]).toMatchObject({ remoteExecution: { host: "ssh.example.test", useHostAuth: false } });
} finally {
ensureCommandResolvable.mockReset().mockImplementation(originalResolve);
if (previousPath === undefined) delete process.env.PATH;
else process.env.PATH = previousPath;
if (previous === undefined) delete process.env.CLAUDE_CODE_OAUTH_TOKEN;
else process.env.CLAUDE_CODE_OAUTH_TOKEN = previous;
}
});
it.each(["host auth", "legacy auth", "missing account", "in-place", "confinement", "missing command"])("rejects unsupported SSH ACP at the public execution entry: %s", async reason => {
it.each(["host auth", "legacy auth", "missing account", "in-place", "confinement", "missing SSH client"])("rejects unsupported SSH ACP at the public execution entry: %s", async reason => {
const ctx = managedSshAcpContext("acp");
const originalResolve = ensureCommandResolvable.getMockImplementation()!;
if (reason === "host auth") ctx.executionTarget.spec.useHostAuth = true;
@@ -146,11 +158,22 @@ describe("claude remote execution", () => {
if (reason === "missing account") delete ctx.config.managedAiConnection;
if (reason === "in-place") ctx.executionTarget.workspaceRealization.mode = "in_place";
if (reason === "confinement") ctx.config.filesystemScope = "workspace";
if (reason === "missing command") ensureCommandResolvable.mockRejectedValueOnce(new Error("fixture ACP command unavailable"));
const previousPath = process.env.PATH;
if (reason === "missing SSH client") {
const bin = await mkdtemp(path.join(os.tmpdir(), "paperclip-no-ssh-client-"));
cleanupDirs.push(bin);
process.env.PATH = bin;
const actual = await vi.importActual<typeof import("@paperclipai/adapter-utils/server-utils")>("@paperclipai/adapter-utils/server-utils");
ensureCommandResolvable.mockImplementationOnce(actual.ensureCommandResolvable);
}
try {
expect(await execute(ctx)).toMatchObject({ exitCode: 1, errorCode: "adapter_engine_unavailable" });
expect(executeAcp).not.toHaveBeenCalled();
} finally { ensureCommandResolvable.mockReset().mockImplementation(originalResolve); }
} finally {
ensureCommandResolvable.mockReset().mockImplementation(originalResolve);
if (previousPath === undefined) delete process.env.PATH;
else process.env.PATH = previousPath;
}
});
it.each([false, true])("keeps managed SSH Claude conversations and scrubs credentials (follow-up fails=%s)", async fails => {
@@ -463,7 +463,7 @@ async function commandIsResolvable(
trimmed,
target,
resolveAdapterExecutionTargetCwd(target, asString(input?.config.cwd, ""), process.cwd()),
target.transport === "ssh" ? {} : process.env,
target.transport === "ssh" ? { PATH: process.env.PATH } : process.env,
);
return true;
} catch {
@@ -26,7 +26,7 @@ const {
pid: 123,
startedAt: new Date().toISOString(),
})),
ensureCommandResolvable: vi.fn(async () => undefined),
ensureCommandResolvable: vi.fn<typeof import("@paperclipai/adapter-utils/server-utils").ensureCommandResolvable>(async () => undefined),
resolveCommandForLogs: vi.fn(async () => "/usr/bin/codex"),
prepareWorkspaceForSshExecution: vi.fn(async () => ({ gitBacked: false })),
restoreWorkspaceFromSshExecution: vi.fn(async () => undefined),
@@ -113,6 +113,14 @@ describe("codex remote execution", () => {
it.each([undefined, "acp"])("admits managed SSH ACP through the public execution entry (engine=%s)", async engine => {
const ctx = managedSshAcpContext(engine);
const actual = await vi.importActual<typeof import("@paperclipai/adapter-utils/server-utils")>("@paperclipai/adapter-utils/server-utils");
const bin = await mkdtemp(path.join(os.tmpdir(), "paperclip-ssh-client-probe-"));
cleanupDirs.push(bin);
await writeFile(path.join(bin, "ssh"), "#!/bin/sh\nexit 0\n", { mode: 0o700 });
const originalResolve = ensureCommandResolvable.getMockImplementation()!;
ensureCommandResolvable.mockImplementationOnce(actual.ensureCommandResolvable);
const previousPath = process.env.PATH;
process.env.PATH = bin;
const previous = process.env.OPENAI_API_KEY;
process.env.OPENAI_API_KEY = "fixture-server-secret";
try {
@@ -120,15 +128,19 @@ describe("codex remote execution", () => {
expect(executeAcp).toHaveBeenCalledWith(ctx);
const probe = ensureCommandResolvable.mock.calls[0] as unknown as unknown[];
expect(probe[0]).toBe("codex-acp");
expect(Object.keys(probe[2] as Record<string, unknown>)).toEqual([]);
expect(Object.keys(probe[2] as Record<string, unknown>)).toEqual(["PATH"]);
expect((probe[2] as Record<string, unknown>).PATH === bin).toBe(true);
expect(probe[3]).toMatchObject({ remoteExecution: { host: "ssh.example.test", useHostAuth: false } });
} finally {
ensureCommandResolvable.mockReset().mockImplementation(originalResolve);
if (previousPath === undefined) delete process.env.PATH;
else process.env.PATH = previousPath;
if (previous === undefined) delete process.env.OPENAI_API_KEY;
else process.env.OPENAI_API_KEY = previous;
}
});
it.each(["host auth", "legacy auth", "missing account", "in-place", "confinement", "missing command"])("rejects unsupported SSH ACP at the public execution entry: %s", async reason => {
it.each(["host auth", "legacy auth", "missing account", "in-place", "confinement", "missing SSH client"])("rejects unsupported SSH ACP at the public execution entry: %s", async reason => {
const ctx = managedSshAcpContext("acp");
const originalResolve = ensureCommandResolvable.getMockImplementation()!;
if (reason === "host auth") ctx.executionTarget.spec.useHostAuth = true;
@@ -136,11 +148,22 @@ describe("codex remote execution", () => {
if (reason === "missing account") delete ctx.config.managedAiConnection;
if (reason === "in-place") ctx.executionTarget.workspaceRealization.mode = "in_place";
if (reason === "confinement") ctx.config.filesystemScope = "workspace";
if (reason === "missing command") ensureCommandResolvable.mockRejectedValueOnce(new Error("fixture ACP command unavailable"));
const previousPath = process.env.PATH;
if (reason === "missing SSH client") {
const bin = await mkdtemp(path.join(os.tmpdir(), "paperclip-no-ssh-client-"));
cleanupDirs.push(bin);
process.env.PATH = bin;
const actual = await vi.importActual<typeof import("@paperclipai/adapter-utils/server-utils")>("@paperclipai/adapter-utils/server-utils");
ensureCommandResolvable.mockImplementationOnce(actual.ensureCommandResolvable);
}
try {
expect(await execute(ctx)).toMatchObject({ exitCode: 1, errorCode: "adapter_engine_unavailable" });
expect(executeAcp).not.toHaveBeenCalled();
} finally { ensureCommandResolvable.mockReset().mockImplementation(originalResolve); }
} finally {
ensureCommandResolvable.mockReset().mockImplementation(originalResolve);
if (previousPath === undefined) delete process.env.PATH;
else process.env.PATH = previousPath;
}
});
it.each([false, true])("retains a managed SSH Codex conversation across turns and removes credentials (second turn throws=%s)", async fails => {