The open-source app everyone uses to manage agents at work
TypeScript acpxagent-orchestrationagent-skillsagentic-aiai-agentsai-engineeringai-governanceai-toolsautonomous-agentsclaudeclaude-codeclaude-skillscodexhermesllmmcpmulti-agentopenclawproject-managementworkflow-automation
Add SSH environment support (#4358)
Devin Foleye4995bbb1cc3
diff --git a/cli/src/__tests__/env-lab.test.ts b/cli/src/__tests__/env-lab.test.tsnew file mode 100644index 0000000000..02d6d7daf1--- /dev/null+++ b/cli/src/__tests__/env-lab.test.ts@@ -0,0 +1,24 @@+import path from "node:path";+import { describe, expect, it } from "vitest";+import { collectEnvLabDoctorStatus, resolveEnvLabSshStatePath } from "../commands/env-lab.js";++describe("env-lab command", () => {+ it("resolves the default SSH fixture state path under the instance root", () => {+ const statePath = resolveEnvLabSshStatePath("fixture-test");++ expect(statePath).toContain(+ path.join("instances", "fixture-test", "env-lab", "ssh-fixture", "state.json"),+ );+ });++ it("reports doctor status for an instance without a running fixture", async () => {+ const status = await collectEnvLabDoctorStatus({ instance: "fixture-test-missing" });++ expect(status.statePath).toContain(+ path.join("instances", "fixture-test-missing", "env-lab", "ssh-fixture", "state.json"),+ );+ expect(typeof status.ssh.supported).toBe("boolean");+ expect(status.ssh.running).toBe(false);+ expect(status.ssh.environment).toBeNull();+ });+});diff --git a/cli/src/commands/env-lab.ts b/cli/src/commands/env-lab.tsnew file mode 100644index 0000000000..55227c9f63--- /dev/null+++ b/cli/src/commands/env-lab.ts@@ -0,0 +1,174 @@+import path from "node:path";+import type { Command } from "commander";+import * as p from "@clack/prompts";+import pc from "picocolors";+import {+ buildSshEnvLabFixtureConfig,+ getSshEnvLabSupport,+ readSshEnvLabFixtureStatus,+ startSshEnvLabFixture,+ stopSshEnvLabFixture,+} from "@paperclipai/adapter-utils/ssh";+import { resolvePaperclipInstanceId, resolvePaperclipInstanceRoot } from "../config/home.js";++export function resolveEnvLabSshStatePath(instanceId?: string): string {+ const resolvedInstanceId = resolvePaperclipInstanceId(instanceId);+ return path.resolve(+ resolvePaperclipInstanceRoot(resolvedInstanceId),+ "env-lab",+ "ssh-fixture",+ "state.json",+ );+}++function printJson(value: unknown) {+ process.stdout.write(`${JSON.stringify(value, null, 2)}\n`);+}++function summarizeFixture(state: {+ host: string;+ port: number;+ username: string;+ workspaceDir: string;+ sshdLogPath: string;+}) {+ p.log.message(`Host: ${pc.cyan(state.host)}:${pc.cyan(String(state.port))}`);+ p.log.message(`User: ${pc.cyan(state.username)}`);+ p.log.message(`Workspace: ${pc.cyan(state.workspaceDir)}`);+ p.log.message(`Log: ${pc.dim(state.sshdLogPath)}`);+}++export async function collectEnvLabDoctorStatus(opts: { instance?: string }) {+ const statePath = resolveEnvLabSshStatePath(opts.instance);+ const [sshSupport, sshStatus] = await Promise.all([+ getSshEnvLabSupport(),+ readSshEnvLabFixtureStatus(statePath),+ ]);+ const environment = sshStatus.state ? await buildSshEnvLabFixtureConfig(sshStatus.state) : null;++ return {+ statePath,+ ssh: {+ supported: sshSupport.supported,+ reason: sshSupport.reason,+ running: sshStatus.running,+ state: sshStatus.state,+ environment,+ },+ };+}++export async function envLabUpCommand(opts: { instance?: string; json?: boolean }) {+ const statePath = resolveEnvLabSshStatePath(opts.instance);+ const state = await startSshEnvLabFixture({ statePath });+ const environment = await buildSshEnvLabFixtureConfig(state);++ if (opts.json) {+ printJson({ state, environment });+ return;+ }++ p.log.success("SSH env-lab fixture is running.");+ summarizeFixture(state);+ p.log.message(`State: ${pc.dim(statePath)}`);+}++export async function envLabStatusCommand(opts: { instance?: string; json?: boolean }) {+ const statePath = resolveEnvLabSshStatePath(opts.instance);+ const status = await readSshEnvLabFixtureStatus(statePath);+ const environment = status.state ? await buildSshEnvLabFixtureConfig(status.state) : null;++ if (opts.json) {+ printJson({ ...status, environment, statePath });+ return;+ }++ if (!status.state || !status.running) {+ p.log.info(`SSH env-lab fixture is not running (${pc.dim(statePath)}).`);+ return;+ }++ p.log.success("SSH env-lab fixture is running.");+ summarizeFixture(status.state);+ p.log.message(`State: ${pc.dim(statePath)}`);+}++export async function envLabDownCommand(opts: { instance?: string; json?: boolean }) {+ const statePath = resolveEnvLabSshStatePath(opts.instance);+ const stopped = await stopSshEnvLabFixture(statePath);++ if (opts.json) {+ printJson({ stopped, statePath });+ return;+ }++ if (!stopped) {+ p.log.info(`No SSH env-lab fixture was running (${pc.dim(statePath)}).`);+ return;+ }++ p.log.success("SSH env-lab fixture stopped.");+ p.log.message(`State: ${pc.dim(statePath)}`);+}++export async function envLabDoctorCommand(opts: { instance?: string; json?: boolean }) {+ const status = await collectEnvLabDoctorStatus(opts);++ if (opts.json) {+ printJson(status);+ return;+ }++ if (status.ssh.supported) {+ p.log.success("SSH fixture prerequisites are installed.");+ } else {+ p.log.warn(`SSH fixture prerequisites are incomplete: ${status.ssh.reason ?? "unknown reason"}`);+ }++ if (status.ssh.state && status.ssh.running) {+ p.log.success("SSH env-lab fixture is running.");+ summarizeFixture(status.ssh.state);+ p.log.message(`Private key: ${pc.dim(status.ssh.state.clientPrivateKeyPath)}`);+ p.log.message(`Known hosts: ${pc.dim(status.ssh.state.knownHostsPath)}`);+ } else if (status.ssh.state) {+ p.log.warn("SSH env-lab fixture state exists, but the process is not running.");+ p.log.message(`State: ${pc.dim(status.statePath)}`);+ } else {+ p.log.info("SSH env-lab fixture is not running.");+ p.log.message(`State: ${pc.dim(status.statePath)}`);+ }++ p.log.message(`Cleanup: ${pc.dim("pnpm paperclipai env-lab down")}`);+}++export function registerEnvLabCommands(program: Command) {+ const envLab = program.command("env-lab").description("Deterministic local environment fixtures");++ envLab+ .command("up")+ .description("Start the default SSH env-lab fixture")+ .option("-i, --instance <id>", "Paperclip instance id (default: current/default)")+ .option("--json", "Print machine-readable fixture details")+ .action(envLabUpCommand);++ envLab+ .command("status")+ .description("Show the current SSH env-lab fixture state")+ .option("-i, --instance <id>", "Paperclip instance id (default: current/default)")+ .option("--json", "Print machine-readable fixture details")+ .action(envLabStatusCommand);++ envLab+ .command("down")+ .description("Stop the default SSH env-lab fixture")+ .option("-i, --instance <id>", "Paperclip instance id (default: current/default)")+ .option("--json", "Print machine-readable stop details")+ .action(envLabDownCommand);++ envLab+ .command("doctor")+ .description("Check SSH fixture prerequisites and current status")+ .option("-i, --instance <id>", "Paperclip instance id (default: current/default)")+ .option("--json", "Print machine-readable diagnostic details")+ .action(envLabDoctorCommand);+}diff --git a/cli/src/commands/worktree.ts b/cli/src/commands/worktree.tsindex bff59f50d9..faa8e490e3 100644--- a/cli/src/commands/worktree.ts+++ b/cli/src/commands/worktree.ts@@ -1311,6 +1311,7 @@ async function seedWorktreeDatabase(input: {backupDir: path.resolve(input.targetPaths.backupDir, "seed"),retention: { dailyDays: 7, weeklyWeeks: 4, monthlyMonths: 1 },filenamePrefix: `${input.instanceId}-seed`,+ backupEngine: "javascript",includeMigrationJournal: true,excludeTables: seedPlan.excludedTables,nullifyColumns: seedPlan.nullifyColumns,diff --git a/cli/src/index.ts b/cli/src/index.tsindex b2208798a7..bbec356f34 100644--- a/cli/src/index.ts+++ b/cli/src/index.ts@@ -8,6 +8,7 @@ import { heartbeatRun } from "./commands/heartbeat-run.js";import { runCommand } from "./commands/run.js";import { bootstrapCeoInvite } from "./commands/auth-bootstrap-ceo.js";import { dbBackupCommand } from "./commands/db-backup.js";+import { registerEnvLabCommands } from "./commands/env-lab.js";import { registerContextCommands } from "./commands/client/context.js";import { registerCompanyCommands } from "./commands/client/company.js";import { registerIssueCommands } from "./commands/client/issue.js";@@ -147,6 +148,7 @@ registerDashboardCommands(program);registerRoutineCommands(program);registerFeedbackCommands(program);registerWorktreeCommands(program);+registerEnvLabCommands(program);registerPluginCommands(program);const auth = program.command("auth").description("Authentication and bootstrap utilities");diff --git a/doc/CLI.md b/doc/CLI.mdindex c124b44745..9f2aba8645 100644--- a/doc/CLI.md+++ b/doc/CLI.md@@ -2,7 +2,7 @@Paperclip CLI now supports both:-- instance setup/diagnostics (`onboard`, `doctor`, `configure`, `env`, `allowed-hostname`)+- instance setup/diagnostics (`onboard`, `doctor`, `configure`, `env`, `allowed-hostname`, `env-lab`)- control-plane client operations (issues, approvals, agents, activity, dashboard)## Base Usage@@ -45,6 +45,15 @@ Allow an authenticated/private hostname (for example custom Tailscale DNS):pnpm paperclipai allowed-hostname dotta-macbook-pro```+Bring up the default local SSH fixture for environment testing:++```sh+pnpm paperclipai env-lab up+pnpm paperclipai env-lab doctor+pnpm paperclipai env-lab status --json+pnpm paperclipai env-lab down+```+All client commands support:- `--data-dir <path>`diff --git a/packages/adapter-utils/src/execution-target.test.ts b/packages/adapter-utils/src/execution-target.test.tsnew file mode 100644index 0000000000..b68c8c10b2--- /dev/null+++ b/packages/adapter-utils/src/execution-target.test.ts@@ -0,0 +1,161 @@+import { afterEach, describe, expect, it, vi } from "vitest";+import * as ssh from "./ssh.js";+import {+ adapterExecutionTargetUsesManagedHome,+ runAdapterExecutionTargetShellCommand,+} from "./execution-target.js";++describe("runAdapterExecutionTargetShellCommand", () => {+ afterEach(() => {+ vi.restoreAllMocks();+ });++ it("quotes remote shell commands with the shared SSH quoting helper", async () => {+ const runSshCommandSpy = vi.spyOn(ssh, "runSshCommand").mockResolvedValue({+ stdout: "",+ stderr: "",+ });++ await runAdapterExecutionTargetShellCommand(+ "run-1",+ {+ kind: "remote",+ transport: "ssh",+ remoteCwd: "/srv/paperclip/workspace",+ spec: {+ host: "ssh.example.test",+ port: 22,+ username: "ssh-user",+ remoteCwd: "/srv/paperclip/workspace",+ remoteWorkspacePath: "/srv/paperclip/workspace",+ privateKey: null,+ knownHosts: null,+ strictHostKeyChecking: true,+ },+ },+ `printf '%s\\n' "$HOME" && echo "it's ok"`,+ {+ cwd: "/tmp/local",+ env: {},+ },+ );++ expect(runSshCommandSpy).toHaveBeenCalledWith(+ expect.objectContaining({+ host: "ssh.example.test",+ username: "ssh-user",+ }),+ `sh -lc ${ssh.shellQuote(`printf '%s\\n' "$HOME" && echo "it's ok"`)}`,+ expect.any(Object),+ );+ });++ it("returns a timedOut result when the SSH shell command times out", async () => {+ vi.spyOn(ssh, "runSshCommand").mockRejectedValue(Object.assign(new Error("timed out"), {+ code: "ETIMEDOUT",+ stdout: "partial stdout",+ stderr: "partial stderr",+ signal: "SIGTERM",+ }));+ const onLog = vi.fn(async () => {});++ const result = await runAdapterExecutionTargetShellCommand(+ "run-2",+ {+ kind: "remote",+ transport: "ssh",+ remoteCwd: "/srv/paperclip/workspace",+ spec: {+ host: "ssh.example.test",+ port: 22,+ username: "ssh-user",+ remoteCwd: "/srv/paperclip/workspace",+ remoteWorkspacePath: "/srv/paperclip/workspace",+ privateKey: null,+ knownHosts: null,+ strictHostKeyChecking: true,+ },+ },+ "sleep 10",+ {+ cwd: "/tmp/local",+ env: {},+ onLog,+ },+ );++ expect(result).toMatchObject({+ exitCode: null,+ signal: "SIGTERM",+ timedOut: true,+ stdout: "partial stdout",+ stderr: "partial stderr",+ });+ expect(onLog).toHaveBeenCalledWith("stdout", "partial stdout");+ expect(onLog).toHaveBeenCalledWith("stderr", "partial stderr");+ });++ it("returns the SSH process exit code for non-zero remote command failures", async () => {+ vi.spyOn(ssh, "runSshCommand").mockRejectedValue(Object.assign(new Error("non-zero exit"), {+ code: 17,+ stdout: "partial stdout",+ stderr: "partial stderr",+ signal: null,+ }));+ const onLog = vi.fn(async () => {});++ const result = await runAdapterExecutionTargetShellCommand(+ "run-3",+ {+ kind: "remote",+ transport: "ssh",+ remoteCwd: "/srv/paperclip/workspace",+ spec: {+ host: "ssh.example.test",+ port: 22,+ username: "ssh-user",+ remoteCwd: "/srv/paperclip/workspace",+ remoteWorkspacePath: "/srv/paperclip/workspace",+ privateKey: null,+ knownHosts: null,+ strictHostKeyChecking: true,+ },+ },+ "false",+ {+ cwd: "/tmp/local",+ env: {},+ onLog,+ },+ );++ expect(result).toMatchObject({+ exitCode: 17,+ signal: null,+ timedOut: false,+ stdout: "partial stdout",+ stderr: "partial stderr",+ });+ expect(onLog).toHaveBeenCalledWith("stdout", "partial stdout");+ expect(onLog).toHaveBeenCalledWith("stderr", "partial stderr");+ });++ it("keeps managed homes disabled for both local and SSH targets", () => {+ expect(adapterExecutionTargetUsesManagedHome(null)).toBe(false);+ expect(adapterExecutionTargetUsesManagedHome({+ kind: "remote",+ transport: "ssh",+ remoteCwd: "/srv/paperclip/workspace",+ spec: {+ host: "ssh.example.test",+ port: 22,+ username: "ssh-user",+ remoteCwd: "/srv/paperclip/workspace",+ remoteWorkspacePath: "/srv/paperclip/workspace",+ privateKey: null,+ knownHosts: null,+ strictHostKeyChecking: true,+ },+ })).toBe(false);+ });+});diff --git a/packages/adapter-utils/src/execution-target.ts b/packages/adapter-utils/src/execution-target.tsnew file mode 100644index 0000000000..d55c9debdc--- /dev/null+++ b/packages/adapter-utils/src/execution-target.ts@@ -0,0 +1,399 @@+import path from "node:path";+import type { SshRemoteExecutionSpec } from "./ssh.js";+import {+ buildRemoteExecutionSessionIdentity,+ prepareRemoteManagedRuntime,+ remoteExecutionSessionMatches,+ type RemoteManagedRuntimeAsset,+} from "./remote-managed-runtime.js";+import { parseSshRemoteExecutionSpec, runSshCommand, shellQuote } from "./ssh.js";+import {+ ensureCommandResolvable,+ resolveCommandForLogs,+ runChildProcess,+ type RunProcessResult,+ type TerminalResultCleanupOptions,+} from "./server-utils.js";++export interface AdapterLocalExecutionTarget {+ kind: "local";+ environmentId?: string | null;+ leaseId?: string | null;+}++export interface AdapterSshExecutionTarget {+ kind: "remote";+ transport: "ssh";+ environmentId?: string | null;+ leaseId?: string | null;+ remoteCwd: string;+ paperclipApiUrl?: string | null;+ spec: SshRemoteExecutionSpec;+}++export type AdapterExecutionTarget =+ | AdapterLocalExecutionTarget+ | AdapterSshExecutionTarget;++export type AdapterRemoteExecutionSpec = SshRemoteExecutionSpec;++export type AdapterManagedRuntimeAsset = RemoteManagedRuntimeAsset;++export interface PreparedAdapterExecutionTargetRuntime {+ target: AdapterExecutionTarget;+ runtimeRootDir: string | null;+ assetDirs: Record<string, string>;+ restoreWorkspace(): Promise<void>;+}++export interface AdapterExecutionTargetProcessOptions {+ cwd: string;+ env: Record<string, string>;+ stdin?: string;+ timeoutSec: number;+ graceSec: number;+ onLog: (stream: "stdout" | "stderr", chunk: string) => Promise<void>;+ onSpawn?: (meta: { pid: number; processGroupId: number | null; startedAt: string }) => Promise<void>;+ terminalResultCleanup?: TerminalResultCleanupOptions;+}++export interface AdapterExecutionTargetShellOptions {+ cwd: string;+ env: Record<string, string>;+ timeoutSec?: number;+ graceSec?: number;+ onLog?: (stream: "stdout" | "stderr", chunk: string) => Promise<void>;+}++function parseObject(value: unknown): Record<string, unknown> {+ return value && typeof value === "object" && !Array.isArray(value)+ ? (value as Record<string, unknown>)+ : {};+}++function readString(value: unknown): string | null {+ return typeof value === "string" && value.trim().length > 0 ? value.trim() : null;+}++function readStringMeta(parsed: Record<string, unknown>, key: string): string | null {+ return readString(parsed[key]);+}++function isAdapterExecutionTargetInstance(value: unknown): value is AdapterExecutionTarget {+ const parsed = parseObject(value);+ if (parsed.kind === "local") return true;+ if (parsed.kind !== "remote") return false;+ if (parsed.transport === "ssh") return parseSshRemoteExecutionSpec(parseObject(parsed.spec)) !== null;+ return false;+}++export function adapterExecutionTargetToRemoteSpec(+ target: AdapterExecutionTarget | null | undefined,+): AdapterRemoteExecutionSpec | null {+ return target?.kind === "remote" && target.transport === "ssh" ? target.spec : null;+}++export function adapterExecutionTargetIsRemote(+ target: AdapterExecutionTarget | null | undefined,+): boolean {+ return target?.kind === "remote";+}++export function adapterExecutionTargetUsesManagedHome(+ target: AdapterExecutionTarget | null | undefined,+): boolean {+ // SSH execution targets sync the runtime assets they need into the remote cwd today,+ // so neither local nor remote targets provision a separate managed adapter home.+ void target;+ return false;+}++export function adapterExecutionTargetRemoteCwd(+ target: AdapterExecutionTarget | null | undefined,+ localCwd: string,+): string {+ return target?.kind === "remote" ? target.remoteCwd : localCwd;+}++export function adapterExecutionTargetPaperclipApiUrl(+ target: AdapterExecutionTarget | null | undefined,+): string | null {+ if (target?.kind !== "remote") return null;+ return target.paperclipApiUrl ?? target.spec.paperclipApiUrl ?? null;+}++export function describeAdapterExecutionTarget(+ target: AdapterExecutionTarget | null | undefined,+): string {+ if (!target || target.kind === "local") return "local environment";+ return `SSH environment ${target.spec.username}@${target.spec.host}:${target.spec.port}`;+}++export async function ensureAdapterExecutionTargetCommandResolvable(+ command: string,+ target: AdapterExecutionTarget | null | undefined,+ cwd: string,+ env: NodeJS.ProcessEnv,+) {+ await ensureCommandResolvable(command, cwd, env, {+ remoteExecution: adapterExecutionTargetToRemoteSpec(target),+ });+}++export async function resolveAdapterExecutionTargetCommandForLogs(+ command: string,+ target: AdapterExecutionTarget | null | undefined,+ cwd: string,+ env: NodeJS.ProcessEnv,+): Promise<string> {+ return await resolveCommandForLogs(command, cwd, env, {+ remoteExecution: adapterExecutionTargetToRemoteSpec(target),+ });+}++export async function runAdapterExecutionTargetProcess(+ runId: string,+ target: AdapterExecutionTarget | null | undefined,+ command: string,+ args: string[],+ options: AdapterExecutionTargetProcessOptions,+): Promise<RunProcessResult> {+ return await runChildProcess(runId, command, args, {+ cwd: options.cwd,+ env: options.env,+ stdin: options.stdin,+ timeoutSec: options.timeoutSec,+ graceSec: options.graceSec,+ onLog: options.onLog,+ onSpawn: options.onSpawn,+ terminalResultCleanup: options.terminalResultCleanup,+ remoteExecution: adapterExecutionTargetToRemoteSpec(target),+ });+}++export async function runAdapterExecutionTargetShellCommand(+ runId: string,+ target: AdapterExecutionTarget | null | undefined,+ command: string,+ options: AdapterExecutionTargetShellOptions,+): Promise<RunProcessResult> {+ const onLog = options.onLog ?? (async () => {});+ if (target?.kind === "remote") {+ const startedAt = new Date().toISOString();+ try {+ const result = await runSshCommand(target.spec, `sh -lc ${shellQuote(command)}`, {+ timeoutMs: (options.timeoutSec ?? 15) * 1000,+ });+ if (result.stdout) await onLog("stdout", result.stdout);+ if (result.stderr) await onLog("stderr", result.stderr);+ return {+ exitCode: 0,+ signal: null,+ timedOut: false,+ stdout: result.stdout,+ stderr: result.stderr,+ pid: null,+ startedAt,+ };+ } catch (error) {+ const timedOutError = error as NodeJS.ErrnoException & {+ stdout?: string;+ stderr?: string;+ signal?: string | null;+ };+ const stdout = timedOutError.stdout ?? "";+ const stderr = timedOutError.stderr ?? "";+ if (typeof timedOutError.code === "number") {+ if (stdout) await onLog("stdout", stdout);+ if (stderr) await onLog("stderr", stderr);+ return {+ exitCode: timedOutError.code,+ signal: timedOutError.signal ?? null,+ timedOut: false,+ stdout,+ stderr,+ pid: null,+ startedAt,+ };+ }+ if (timedOutError.code !== "ETIMEDOUT") {+ throw error;+ }+ if (stdout) await onLog("stdout", stdout);+ if (stderr) await onLog("stderr", stderr);+ return {+ exitCode: null,+ signal: timedOutError.signal ?? null,+ timedOut: true,+ stdout,+ stderr,+ pid: null,+ startedAt,+ };+ }+ }++ return await runAdapterExecutionTargetProcess(+ runId,+ target,+ "sh",+ ["-lc", command],+ {+ cwd: options.cwd,+ env: options.env,+ timeoutSec: options.timeoutSec ?? 15,+ graceSec: options.graceSec ?? 5,+ onLog,+ },+ );+}++export async function readAdapterExecutionTargetHomeDir(+ runId: string,+ target: AdapterExecutionTarget | null | undefined,+ options: AdapterExecutionTargetShellOptions,+): Promise<string | null> {+ const result = await runAdapterExecutionTargetShellCommand(+ runId,+ target,+ 'printf %s "$HOME"',+ options,+ );+ const homeDir = result.stdout.trim();+ return homeDir.length > 0 ? homeDir : null;+}++export async function ensureAdapterExecutionTargetFile(+ runId: string,+ target: AdapterExecutionTarget | null | undefined,+ filePath: string,+ options: AdapterExecutionTargetShellOptions,+): Promise<void> {+ await runAdapterExecutionTargetShellCommand(+ runId,+ target,+ `mkdir -p ${shellQuote(path.posix.dirname(filePath))} && : > ${shellQuote(filePath)}`,+ options,+ );+}++export function adapterExecutionTargetSessionIdentity(+ target: AdapterExecutionTarget | null | undefined,+): Record<string, unknown> | null {+ if (!target || target.kind === "local") return null;+ return buildRemoteExecutionSessionIdentity(target.spec);+}++export function adapterExecutionTargetSessionMatches(+ saved: unknown,+ target: AdapterExecutionTarget | null | undefined,+): boolean {+ if (!target || target.kind === "local") {+ return Object.keys(parseObject(saved)).length === 0;+ }+ return remoteExecutionSessionMatches(saved, target.spec);+}++export function parseAdapterExecutionTarget(value: unknown): AdapterExecutionTarget | null {+ const parsed = parseObject(value);+ const kind = readStringMeta(parsed, "kind");++ if (kind === "local") {+ return {+ kind: "local",+ environmentId: readStringMeta(parsed, "environmentId"),+ leaseId: readStringMeta(parsed, "leaseId"),+ };+ }++ if (kind === "remote" && readStringMeta(parsed, "transport") === "ssh") {+ const spec = parseSshRemoteExecutionSpec(parseObject(parsed.spec));+ if (!spec) return null;+ return {+ kind: "remote",+ transport: "ssh",+ environmentId: readStringMeta(parsed, "environmentId"),+ leaseId: readStringMeta(parsed, "leaseId"),+ remoteCwd: spec.remoteCwd,+ paperclipApiUrl: readStringMeta(parsed, "paperclipApiUrl") ?? spec.paperclipApiUrl ?? null,+ spec,+ };+ }++ return null;+}++export function adapterExecutionTargetFromRemoteExecution(+ remoteExecution: unknown,+ metadata: Pick<AdapterLocalExecutionTarget, "environmentId" | "leaseId"> = {},+): AdapterExecutionTarget | null {+ const parsed = parseObject(remoteExecution);+ const ssh = parseSshRemoteExecutionSpec(parsed);+ if (ssh) {+ return {+ kind: "remote",+ transport: "ssh",+ environmentId: metadata.environmentId ?? null,+ leaseId: metadata.leaseId ?? null,+ remoteCwd: ssh.remoteCwd,+ paperclipApiUrl: ssh.paperclipApiUrl ?? null,+ spec: ssh,+ };+ }++ return null;+}++export function readAdapterExecutionTarget(input: {+ executionTarget?: unknown;+ legacyRemoteExecution?: unknown;+}): AdapterExecutionTarget | null {+ if (isAdapterExecutionTargetInstance(input.executionTarget)) {+ return input.executionTarget;+ }+ return (+ parseAdapterExecutionTarget(input.executionTarget) ??+ adapterExecutionTargetFromRemoteExecution(input.legacyRemoteExecution)+ );+}++export async function prepareAdapterExecutionTargetRuntime(input: {+ target: AdapterExecutionTarget | null | undefined;+ adapterKey: string;+ workspaceLocalDir: string;+ workspaceExclude?: string[];+ preserveAbsentOnRestore?: string[];+ assets?: AdapterManagedRuntimeAsset[];+ installCommand?: string | null;+}): Promise<PreparedAdapterExecutionTargetRuntime> {+ const target = input.target ?? { kind: "local" as const };+ if (target.kind === "local") {+ return {+ target,+ runtimeRootDir: null,+ assetDirs: {},+ restoreWorkspace: async () => {},+ };+ }++ const prepared = await prepareRemoteManagedRuntime({+ spec: target.spec,+ adapterKey: input.adapterKey,+ workspaceLocalDir: input.workspaceLocalDir,+ assets: input.assets,+ });+ return {+ target,+ runtimeRootDir: prepared.runtimeRootDir,+ assetDirs: prepared.assetDirs,+ restoreWorkspace: prepared.restoreWorkspace,+ };+}++export function runtimeAssetDir(+ prepared: Pick<PreparedAdapterExecutionTargetRuntime, "assetDirs">,+ key: string,+ fallbackRemoteCwd: string,+): string {+ return prepared.assetDirs[key] ?? path.posix.join(fallbackRemoteCwd, ".paperclip-runtime", key);+}diff --git a/packages/adapter-utils/src/remote-managed-runtime.ts b/packages/adapter-utils/src/remote-managed-runtime.tsnew file mode 100644index 0000000000..089ff46aba--- /dev/null+++ b/packages/adapter-utils/src/remote-managed-runtime.ts@@ -0,0 +1,118 @@+import path from "node:path";+import {+ type SshRemoteExecutionSpec,+ prepareWorkspaceForSshExecution,+ restoreWorkspaceFromSshExecution,+ syncDirectoryToSsh,+} from "./ssh.js";++export interface RemoteManagedRuntimeAsset {+ key: string;+ localDir: string;+ followSymlinks?: boolean;+ exclude?: string[];+}++export interface PreparedRemoteManagedRuntime {+ spec: SshRemoteExecutionSpec;+ workspaceLocalDir: string;+ workspaceRemoteDir: string;+ runtimeRootDir: string;+ assetDirs: Record<string, string>;+ restoreWorkspace(): Promise<void>;+}++function asObject(value: unknown): Record<string, unknown> {+ return value && typeof value === "object" && !Array.isArray(value)+ ? (value as Record<string, unknown>)+ : {};+}++function asString(value: unknown): string {+ return typeof value === "string" ? value : "";+}++function asNumber(value: unknown): number {+ return typeof value === "number" ? value : Number(value);+}++export function buildRemoteExecutionSessionIdentity(spec: SshRemoteExecutionSpec | null) {+ if (!spec) return null;+ return {+ transport: "ssh",+ host: spec.host,+ port: spec.port,+ username: spec.username,+ remoteCwd: spec.remoteCwd,+ ...(spec.paperclipApiUrl ? { paperclipApiUrl: spec.paperclipApiUrl } : {}),+ } as const;+}++export function remoteExecutionSessionMatches(saved: unknown, current: SshRemoteExecutionSpec | null): boolean {+ const currentIdentity = buildRemoteExecutionSessionIdentity(current);+ if (!currentIdentity) return false;++ const parsedSaved = asObject(saved);+ return (+ asString(parsedSaved.transport) === currentIdentity.transport &&+ asString(parsedSaved.host) === currentIdentity.host &&+ asNumber(parsedSaved.port) === currentIdentity.port &&+ asString(parsedSaved.username) === currentIdentity.username &&+ asString(parsedSaved.remoteCwd) === currentIdentity.remoteCwd &&+ asString(parsedSaved.paperclipApiUrl) === asString(currentIdentity.paperclipApiUrl)+ );+}++export async function prepareRemoteManagedRuntime(input: {+ spec: SshRemoteExecutionSpec;+ adapterKey: string;+ workspaceLocalDir: string;+ workspaceRemoteDir?: string;+ assets?: RemoteManagedRuntimeAsset[];+}): Promise<PreparedRemoteManagedRuntime> {+ const workspaceRemoteDir = input.workspaceRemoteDir ?? input.spec.remoteCwd;+ const runtimeRootDir = path.posix.join(workspaceRemoteDir, ".paperclip-runtime", input.adapterKey);++ await prepareWorkspaceForSshExecution({+ spec: input.spec,+ localDir: input.workspaceLocalDir,+ remoteDir: workspaceRemoteDir,+ });++ const assetDirs: Record<string, string> = {};+ try {+ for (const asset of input.assets ?? []) {+ const remoteDir = path.posix.join(runtimeRootDir, asset.key);+ assetDirs[asset.key] = remoteDir;+ await syncDirectoryToSsh({+ spec: input.spec,+ localDir: asset.localDir,+ remoteDir,+ followSymlinks: asset.followSymlinks,+ exclude: asset.exclude,+ });+ }+ } catch (error) {+ await restoreWorkspaceFromSshExecution({+ spec: input.spec,+ localDir: input.workspaceLocalDir,+ remoteDir: workspaceRemoteDir,+ });+ throw error;+ }++ return {+ spec: input.spec,+ workspaceLocalDir: input.workspaceLocalDir,+ workspaceRemoteDir,+ runtimeRootDir,+ assetDirs,+ restoreWorkspace: async () => {+ await restoreWorkspaceFromSshExecution({+ spec: input.spec,+ localDir: input.workspaceLocalDir,+ remoteDir: workspaceRemoteDir,+ });+ },+ };+}diff --git a/packages/adapter-utils/src/server-utils.ts b/packages/adapter-utils/src/server-utils.tsindex 4ec8f3e0d8..9e40d4ae39 100644--- a/packages/adapter-utils/src/server-utils.ts+++ b/packages/adapter-utils/src/server-utils.ts@@ -1,6 +1,7 @@import { spawn, type ChildProcess } from "node:child_process";import { constants as fsConstants, promises as fs, type Dirent } from "node:fs";import path from "node:path";+import { buildSshSpawnTarget, type SshRemoteExecutionSpec } from "./ssh.js";import type {AdapterSkillEntry,AdapterSkillSnapshot,@@ -30,8 +31,12 @@ interface RunningProcess {interface SpawnTarget {command: string;args: string[];+ cwd?: string;+ cleanup?: () => Promise<void>;}+type RemoteExecutionSpec = SshRemoteExecutionSpec;+type ChildProcessWithEvents = ChildProcess & {on(event: "error", listener: (err: Error) => void): ChildProcess;on(@@ -806,11 +811,26 @@ export function buildPaperclipEnv(agent: { id: string; companyId: string }): Recprocess.env.PAPERCLIP_LISTEN_HOST ?? process.env.HOST ?? "localhost",);const runtimePort = process.env.PAPERCLIP_LISTEN_PORT ?? process.env.PORT ?? "3100";- const apiUrl = process.env.PAPERCLIP_API_URL ?? `http://${runtimeHost}:${runtimePort}`;+ const apiUrl =+ process.env.PAPERCLIP_RUNTIME_API_URL ??+ process.env.PAPERCLIP_API_URL ??+ `http://${runtimeHost}:${runtimePort}`;vars.PAPERCLIP_API_URL = apiUrl;return vars;}+export function sanitizeInheritedPaperclipEnv(baseEnv: NodeJS.ProcessEnv): NodeJS.ProcessEnv {+ const env: NodeJS.ProcessEnv = { ...baseEnv };+ for (const key of Object.keys(env)) {+ if (!key.startsWith("PAPERCLIP_")) continue;+ if (key === "PAPERCLIP_RUNTIME_API_URL") continue;+ if (key === "PAPERCLIP_LISTEN_HOST") continue;+ if (key === "PAPERCLIP_LISTEN_PORT") continue;+ delete env[key];+ }+ return env;+}+export function defaultPathForPlatform() {if (process.platform === "win32") {return "C:\\Windows\\System32;C:\\Windows;C:\\Windows\\System32\\Wbem";@@ -859,7 +879,18 @@ async function resolveCommandPath(command: string, cwd: string, env: NodeJS.Procreturn null;}-export async function resolveCommandForLogs(command: string, cwd: string, env: NodeJS.ProcessEnv): Promise<string> {+export async function resolveCommandForLogs(+ command: string,+ cwd: string,+ env: NodeJS.ProcessEnv,+ options: {+ remoteExecution?: RemoteExecutionSpec | null;+ } = {},+): Promise<string> {+ const remote = options.remoteExecution ?? null;+ if (remote) {+ return `ssh://${remote.username}@${remote.host}:${remote.port}/${remote.remoteCwd} :: ${command}`;+ }return (await resolveCommandPath(command, cwd, env)) ?? command;}@@ -879,7 +910,33 @@ async function resolveSpawnTarget(args: string[],cwd: string,env: NodeJS.ProcessEnv,+ options: {+ remoteExecution?: RemoteExecutionSpec | null;+ remoteEnv?: Record<string, string> | null;+ } = {},): Promise<SpawnTarget> {+ const remote = options.remoteExecution ?? null;+ if (remote) {+ const sshResolved = await resolveCommandPath("ssh", process.cwd(), env);+ if (!sshResolved) {+ throw new Error('Command not found in PATH: "ssh"');+ }+ const spawnTarget = await buildSshSpawnTarget({+ spec: remote,+ command,+ args,+ env: Object.fromEntries(+ Object.entries(options.remoteEnv ?? {}).filter((entry): entry is [string, string] => typeof entry[1] === "string"),+ ),+ });+ return {+ command: sshResolved,+ args: spawnTarget.args,+ cwd: process.cwd(),+ cleanup: spawnTarget.cleanup,+ };+ }+const resolved = await resolveCommandPath(command, cwd, env);const executable = resolved ?? command;@@ -1306,7 +1363,19 @@ export async function removeMaintainerOnlySkillSymlinks(}}-export async function ensureCommandResolvable(command: string, cwd: string, env: NodeJS.ProcessEnv) {+export async function ensureCommandResolvable(+ command: string,+ cwd: string,+ env: NodeJS.ProcessEnv,+ options: {+ remoteExecution?: RemoteExecutionSpec | null;+ } = {},+) {+ if (options.remoteExecution) {+ const resolvedSsh = await resolveCommandPath("ssh", process.cwd(), env);+ if (resolvedSsh) return;+ throw new Error('Command not found in PATH: "ssh"');+ }const resolved = await resolveCommandPath(command, cwd, env);if (resolved) return;if (command.includes("/") || command.includes("\\")) {@@ -1330,12 +1399,15 @@ export async function runChildProcess(onSpawn?: (meta: { pid: number; processGroupId: number | null; startedAt: string }) => Promise<void>;terminalResultCleanup?: TerminalResultCleanupOptions;stdin?: string;+ remoteExecution?: RemoteExecutionSpec | null;},): Promise<RunProcessResult> {const onLogError = opts.onLogError ?? ((err, id, msg) => console.warn({ err, runId: id }, msg));-return new Promise<RunProcessResult>((resolve, reject) => {- const rawMerged: NodeJS.ProcessEnv = { ...process.env, ...opts.env };+ const rawMerged: NodeJS.ProcessEnv = {+ ...sanitizeInheritedPaperclipEnv(process.env),+ ...opts.env,+ };// Strip Claude Code nesting-guard env vars so spawned `claude` processes// don't refuse to start with "cannot be launched inside another session".@@ -1353,10 +1425,13 @@ export async function runChildProcess(}const mergedEnv = ensurePathInEnv(rawMerged);- void resolveSpawnTarget(command, args, opts.cwd, mergedEnv)+ void resolveSpawnTarget(command, args, opts.cwd, mergedEnv, {+ remoteExecution: opts.remoteExecution ?? null,+ remoteEnv: opts.remoteExecution ? opts.env : null,+ }).then((target) => {const child = spawn(target.command, target.args, {- cwd: opts.cwd,+ cwd: target.cwd ?? opts.cwd,env: mergedEnv,detached: process.platform !== "win32",shell: false,@@ -1484,6 +1559,7 @@ export async function runChildProcess(if (timeout) clearTimeout(timeout);clearTerminalCleanupTimers();runningProcesses.delete(runId);+ void target.cleanup?.();const errno = (err as NodeJS.ErrnoException).code;const pathValue = mergedEnv.PATH ?? mergedEnv.Path ?? "";const msg =@@ -1502,15 +1578,19 @@ export async function runChildProcess(clearTerminalCleanupTimers();runningProcesses.delete(runId);void logChain.finally(() => {- resolve({- exitCode: code,- signal,- timedOut,- stdout,- stderr,- pid: child.pid ?? null,- startedAt,- });+ void Promise.resolve()+ .then(() => target.cleanup?.())+ .finally(() => {+ resolve({+ exitCode: code,+ signal,+ timedOut,+ stdout,+ stderr,+ pid: child.pid ?? null,+ startedAt,+ });+ });});});})diff --git a/packages/adapter-utils/src/ssh-fixture.test.ts b/packages/adapter-utils/src/ssh-fixture.test.tsnew file mode 100644index 0000000000..dd1ae28ae4--- /dev/null+++ b/packages/adapter-utils/src/ssh-fixture.test.ts@@ -0,0 +1,275 @@+import { execFile } from "node:child_process";+import { mkdir, mkdtemp, rm, symlink, writeFile } from "node:fs/promises";+import os from "node:os";+import path from "node:path";+import { afterEach, describe, expect, it } from "vitest";+import {+ buildSshSpawnTarget,+ buildSshEnvLabFixtureConfig,+ getSshEnvLabSupport,+ prepareWorkspaceForSshExecution,+ readSshEnvLabFixtureStatus,+ restoreWorkspaceFromSshExecution,+ runSshCommand,+ syncDirectoryToSsh,+ startSshEnvLabFixture,+ stopSshEnvLabFixture,+} from "./ssh.js";++async function git(cwd: string, args: string[]): Promise<string> {+ return await new Promise((resolve, reject) => {+ execFile("git", ["-C", cwd, ...args], (error, stdout, stderr) => {+ if (error) {+ reject(new Error((stderr || stdout || error.message).trim()));+ return;+ }+ resolve(stdout.trim());+ });+ });+}++describe("ssh env-lab fixture", () => {+ const cleanupDirs: string[] = [];++ afterEach(async () => {+ while (cleanupDirs.length > 0) {+ const dir = cleanupDirs.pop();+ if (!dir) continue;+ await rm(dir, { recursive: true, force: true }).catch(() => undefined);+ }+ });++ it("starts an isolated sshd fixture and executes commands through it", async () => {+ const support = await getSshEnvLabSupport();+ if (!support.supported) {+ console.warn(+ `Skipping SSH env-lab fixture test: ${support.reason ?? "unsupported environment"}`,+ );+ return;+ }++ const rootDir = await mkdtemp(path.join(os.tmpdir(), "paperclip-ssh-fixture-"));+ cleanupDirs.push(rootDir);+ const statePath = path.join(rootDir, "state.json");++ const started = await startSshEnvLabFixture({ statePath });+ const config = await buildSshEnvLabFixtureConfig(started);+ const quotedWorkspace = JSON.stringify(started.workspaceDir);+ const result = await runSshCommand(+ config,+ `sh -lc 'cd ${quotedWorkspace} && pwd'`,+ );++ expect(result.stdout.trim()).toBe(started.workspaceDir);+ const status = await readSshEnvLabFixtureStatus(statePath);+ expect(status.running).toBe(true);++ await stopSshEnvLabFixture(statePath);++ const stopped = await readSshEnvLabFixtureStatus(statePath);+ expect(stopped.running).toBe(false);+ });++ it("does not treat an unrelated reused pid as the running fixture", async () => {+ const support = await getSshEnvLabSupport();+ if (!support.supported) {+ console.warn(+ `Skipping SSH env-lab fixture test: ${support.reason ?? "unsupported environment"}`,+ );+ return;+ }++ const rootDir = await mkdtemp(path.join(os.tmpdir(), "paperclip-ssh-fixture-"));+ cleanupDirs.push(rootDir);+ const statePath = path.join(rootDir, "state.json");++ const started = await startSshEnvLabFixture({ statePath });+ await stopSshEnvLabFixture(statePath);+ await mkdir(path.dirname(statePath), { recursive: true });++ await writeFile(+ statePath,+ JSON.stringify({ ...started, pid: process.pid }, null, 2),+ { mode: 0o600 },+ );++ const staleStatus = await readSshEnvLabFixtureStatus(statePath);+ expect(staleStatus.running).toBe(false);++ const restarted = await startSshEnvLabFixture({ statePath });+ expect(restarted.pid).not.toBe(process.pid);++ await stopSshEnvLabFixture(statePath);+ });++ it("rejects invalid environment variable keys when constructing SSH spawn targets", async () => {+ await expect(+ buildSshSpawnTarget({+ spec: {+ host: "ssh.example.test",+ port: 22,+ username: "ssh-user",+ remoteCwd: "/srv/paperclip/workspace",+ remoteWorkspacePath: "/srv/paperclip/workspace",+ privateKey: null,+ knownHosts: null,+ strictHostKeyChecking: true,+ },+ command: "env",+ args: [],+ env: {+ "BAD KEY": "value",+ },+ }),+ ).rejects.toThrow("Invalid SSH environment variable key: BAD KEY");+ });++ it("syncs a local directory into the remote fixture workspace", async () => {+ const support = await getSshEnvLabSupport();+ if (!support.supported) {+ console.warn(+ `Skipping SSH env-lab fixture test: ${support.reason ?? "unsupported environment"}`,+ );+ return;+ }++ const rootDir = await mkdtemp(path.join(os.tmpdir(), "paperclip-ssh-fixture-"));+ cleanupDirs.push(rootDir);+ const statePath = path.join(rootDir, "state.json");+ const localDir = path.join(rootDir, "local-overlay");++ await mkdir(localDir, { recursive: true });+ await writeFile(path.join(localDir, "message.txt"), "hello from paperclip\n", "utf8");+ await writeFile(path.join(localDir, "._message.txt"), "should never sync\n", "utf8");++ const started = await startSshEnvLabFixture({ statePath });+ const config = await buildSshEnvLabFixtureConfig(started);+ const remoteDir = path.posix.join(started.workspaceDir, "overlay");++ await syncDirectoryToSsh({+ spec: {+ ...config,+ remoteCwd: started.workspaceDir,+ },+ localDir,+ remoteDir,+ });++ const result = await runSshCommand(+ config,+ `sh -lc 'cat ${JSON.stringify(path.posix.join(remoteDir, "message.txt"))} && if [ -e ${JSON.stringify(path.posix.join(remoteDir, "._message.txt"))} ]; then echo appledouble-present; fi'`,+ );++ expect(result.stdout).toContain("hello from paperclip");+ expect(result.stdout).not.toContain("appledouble-present");+ });++ it("can dereference local symlinks while syncing to the remote fixture", async () => {+ const support = await getSshEnvLabSupport();+ if (!support.supported) {+ console.warn(+ `Skipping SSH symlink sync test: ${support.reason ?? "unsupported environment"}`,+ );+ return;+ }++ const rootDir = await mkdtemp(path.join(os.tmpdir(), "paperclip-ssh-fixture-"));+ cleanupDirs.push(rootDir);+ const statePath = path.join(rootDir, "state.json");+ const sourceDir = path.join(rootDir, "source");+ const localDir = path.join(rootDir, "local-overlay");++ await mkdir(sourceDir, { recursive: true });+ await mkdir(localDir, { recursive: true });+ await writeFile(path.join(sourceDir, "auth.json"), "{\"token\":\"secret\"}\n", "utf8");+ await symlink(path.join(sourceDir, "auth.json"), path.join(localDir, "auth.json"));++ const started = await startSshEnvLabFixture({ statePath });+ const config = await buildSshEnvLabFixtureConfig(started);+ const remoteDir = path.posix.join(started.workspaceDir, "overlay-follow-links");++ await syncDirectoryToSsh({+ spec: {+ ...config,+ remoteCwd: started.workspaceDir,+ },+ localDir,+ remoteDir,+ followSymlinks: true,+ });++ const result = await runSshCommand(+ config,+ `sh -lc 'if [ -L ${JSON.stringify(path.posix.join(remoteDir, "auth.json"))} ]; then echo symlink; else echo regular; fi && cat ${JSON.stringify(path.posix.join(remoteDir, "auth.json"))}'`,+ );++ expect(result.stdout).toContain("regular");+ expect(result.stdout).toContain("{\"token\":\"secret\"}");+ });++ it("round-trips a git workspace through the SSH fixture", async () => {+ const support = await getSshEnvLabSupport();+ if (!support.supported) {+ console.warn(+ `Skipping SSH workspace round-trip test: ${support.reason ?? "unsupported environment"}`,+ );+ return;+ }++ const rootDir = await mkdtemp(path.join(os.tmpdir(), "paperclip-ssh-fixture-"));+ cleanupDirs.push(rootDir);+ const statePath = path.join(rootDir, "state.json");+ const localRepo = path.join(rootDir, "local-workspace");++ await mkdir(localRepo, { recursive: true });+ await git(localRepo, ["init", "-b", "main"]);+ await git(localRepo, ["config", "user.name", "Paperclip Test"]);+ await git(localRepo, ["config", "user.email", "[email protected]"]);+ await writeFile(path.join(localRepo, "tracked.txt"), "base\n", "utf8");+ await writeFile(path.join(localRepo, "._tracked.txt"), "should stay local only\n", "utf8");+ await git(localRepo, ["add", "tracked.txt"]);+ await git(localRepo, ["commit", "-m", "initial"]);+ const originalHead = await git(localRepo, ["rev-parse", "HEAD"]);+ await writeFile(path.join(localRepo, "tracked.txt"), "dirty local\n", "utf8");+ await writeFile(path.join(localRepo, "untracked.txt"), "from local\n", "utf8");++ const started = await startSshEnvLabFixture({ statePath });+ const config = await buildSshEnvLabFixtureConfig(started);+ const spec = {+ ...config,+ remoteCwd: started.workspaceDir,+ } as const;++ await prepareWorkspaceForSshExecution({+ spec,+ localDir: localRepo,+ remoteDir: started.workspaceDir,+ });++ const remoteStatus = await runSshCommand(+ config,+ `sh -lc 'cd ${JSON.stringify(started.workspaceDir)} && git status --short'`,+ );+ expect(remoteStatus.stdout).toContain("M tracked.txt");+ expect(remoteStatus.stdout).toContain("?? untracked.txt");+ expect(remoteStatus.stdout).not.toContain("._tracked.txt");++ await runSshCommand(+ config,+ `sh -lc 'cd ${JSON.stringify(started.workspaceDir)} && git config user.name "Paperclip SSH" && git config user.email "[email protected]" && git add tracked.txt untracked.txt && git commit -m "remote update" >/dev/null && printf "remote dirty\\n" > tracked.txt && printf "remote extra\\n" > remote-only.txt'`,+ { timeoutMs: 30_000, maxBuffer: 256 * 1024 },+ );++ await restoreWorkspaceFromSshExecution({+ spec,+ localDir: localRepo,+ remoteDir: started.workspaceDir,+ });++ const restoredHead = await git(localRepo, ["rev-parse", "HEAD"]);+ expect(restoredHead).not.toBe(originalHead);+ expect(await git(localRepo, ["log", "-1", "--pretty=%s"])).toBe("remote update");+ expect(await git(localRepo, ["status", "--short"])).toContain("M tracked.txt");+ expect(await git(localRepo, ["status", "--short"])).not.toContain("._tracked.txt");+ });+});diff --git a/packages/adapter-utils/src/ssh.ts b/packages/adapter-utils/src/ssh.tsnew file mode 100644index 0000000000..461d36c15a--- /dev/null+++ b/packages/adapter-utils/src/ssh.ts@@ -0,0 +1,1233 @@+import { execFile, spawn } from "node:child_process";+import { constants as fsConstants, createReadStream, createWriteStream, promises as fs } from "node:fs";+import net from "node:net";+import os from "node:os";+import path from "node:path";++export interface SshConnectionConfig {+ host: string;+ port: number;+ username: string;+ remoteWorkspacePath: string;+ privateKey: string | null;+ knownHosts: string | null;+ strictHostKeyChecking: boolean;+}++export interface SshCommandResult {+ stdout: string;+ stderr: string;+}++export interface SshRemoteExecutionSpec extends SshConnectionConfig {+ remoteCwd: string;+ paperclipApiUrl?: string | null;+}++export interface SshEnvLabSupport {+ supported: boolean;+ reason: string | null;+}++export interface SshEnvLabFixtureState {+ kind: "ssh_openbsd";+ bindHost: string;+ host: string;+ port: number;+ username: string;+ rootDir: string;+ workspaceDir: string;+ statePath: string;+ pid: number;+ createdAt: string;+ clientPrivateKeyPath: string;+ clientPublicKeyPath: string;+ hostPrivateKeyPath: string;+ hostPublicKeyPath: string;+ authorizedKeysPath: string;+ knownHostsPath: string;+ sshdConfigPath: string;+ sshdLogPath: string;+}++interface LocalGitWorkspaceSnapshot {+ headCommit: string;+ branchName: string | null;+ deletedPaths: string[];+}++export function shellQuote(value: string) {+ return `'${value.replace(/'/g, `'\"'\"'`)}'`;+}++function isValidShellEnvKey(value: string) {+ return /^[A-Za-z_][A-Za-z0-9_]*$/.test(value);+}++export function parseSshRemoteExecutionSpec(value: unknown): SshRemoteExecutionSpec | null {+ if (!value || typeof value !== "object" || Array.isArray(value)) {+ return null;+ }++ const parsed = value as Record<string, unknown>;+ const host = typeof parsed.host === "string" ? parsed.host.trim() : "";+ const username = typeof parsed.username === "string" ? parsed.username.trim() : "";+ const remoteCwd = typeof parsed.remoteCwd === "string" ? parsed.remoteCwd.trim() : "";+ const portValue = typeof parsed.port === "number" ? parsed.port : Number(parsed.port);+ if (!host || !username || !remoteCwd || !Number.isInteger(portValue) || portValue < 1 || portValue > 65535) {+ return null;+ }++ return {+ host,+ port: portValue,+ username,+ remoteCwd,+ paperclipApiUrl:+ typeof parsed.paperclipApiUrl === "string" && parsed.paperclipApiUrl.trim().length > 0+ ? parsed.paperclipApiUrl.trim()+ : null,+ remoteWorkspacePath:+ typeof parsed.remoteWorkspacePath === "string" && parsed.remoteWorkspacePath.trim().length > 0+ ? parsed.remoteWorkspacePath.trim()+ : remoteCwd,+ privateKey: typeof parsed.privateKey === "string" && parsed.privateKey.length > 0 ? parsed.privateKey : null,+ knownHosts: typeof parsed.knownHosts === "string" && parsed.knownHosts.length > 0 ? parsed.knownHosts : null,+ strictHostKeyChecking:+ typeof parsed.strictHostKeyChecking === "boolean" ? parsed.strictHostKeyChecking : true,+ };+}++function normalizeHttpUrlCandidate(value: string): string | null {+ const trimmed = value.trim();+ if (!trimmed) return null;+ try {+ const parsed = new URL(trimmed);+ if (parsed.protocol !== "http:" && parsed.protocol !== "https:") {+ return null;+ }+ return parsed.origin;+ } catch {+ return null;+ }+}++export async function findReachablePaperclipApiUrlOverSsh(input: {+ config: SshConnectionConfig;+ candidates: string[];+ timeoutMs?: number;+}): Promise<string | null> {+ const uniqueCandidates = Array.from(+ new Set(+ input.candidates+ .map((candidate) => normalizeHttpUrlCandidate(candidate))+ .filter((candidate): candidate is string => candidate !== null),+ ),+ );++ for (const candidate of uniqueCandidates) {+ const healthUrl = new URL("/api/health", candidate).toString();+ try {+ await runSshCommand(+ input.config,+ `sh -lc ${shellQuote(`curl -fsS -m ${Math.max(1, Math.ceil((input.timeoutMs ?? 5_000) / 1000))} ${shellQuote(healthUrl)} >/dev/null`)}`,+ { timeoutMs: input.timeoutMs ?? 5_000 },+ );+ return candidate;+ } catch {+ continue;+ }+ }++ return null;+}++async function execFileText(+ file: string,+ args: string[],+ options: {+ timeout?: number;+ maxBuffer?: number;+ } = {},+): Promise<SshCommandResult> {+ return await new Promise<SshCommandResult>((resolve, reject) => {+ execFile(+ file,+ args,+ {+ timeout: options.timeout ?? 15_000,+ maxBuffer: options.maxBuffer ?? 1024 * 128,+ },+ (error, stdout, stderr) => {+ if (error) {+ reject(Object.assign(error, { stdout: stdout ?? "", stderr: stderr ?? "" }));+ return;+ }+ resolve({+ stdout: stdout ?? "",+ stderr: stderr ?? "",+ });+ },+ );+ });+}++async function runLocalGit(+ localDir: string,+ args: string[],+ options: {+ timeout?: number;+ maxBuffer?: number;+ } = {},+): Promise<SshCommandResult> {+ return await execFileText("git", ["-C", localDir, ...args], options);+}++async function commandExists(command: string): Promise<boolean> {+ return (await resolveCommandPath(command)) !== null;+}++async function resolveCommandPath(command: string): Promise<string | null> {+ try {+ const result = await execFileText("sh", ["-lc", `command -v ${shellQuote(command)}`], {+ timeout: 5_000,+ maxBuffer: 8 * 1024,+ });+ const resolved = result.stdout.trim().split("\n")[0]?.trim() ?? "";+ return resolved.length > 0 ? resolved : null;+ } catch {+ return null;+ }+}++async function withTempFile(+ prefix: string,+ contents: string,+ mode: number,+): Promise<{ path: string; cleanup: () => Promise<void> }> {+ const dir = await fs.mkdtemp(path.join(os.tmpdir(), prefix));+ const filePath = path.join(dir, "payload");+ const normalizedContents = contents.endsWith("\n") ? contents : `${contents}\n`;+ await fs.writeFile(filePath, normalizedContents, { mode, encoding: "utf8" });+ return {+ path: filePath,+ cleanup: async () => {+ await fs.rm(dir, { recursive: true, force: true }).catch(() => undefined);+ },+ };+}++async function createSshAuthArgs(+ config: Pick<SshConnectionConfig, "privateKey" | "knownHosts" | "strictHostKeyChecking">,+): Promise<{ args: string[]; cleanup: () => Promise<void> }> {+ const tempFiles: Array<() => Promise<void>> = [];+ const sshArgs = [+ "-o",+ "BatchMode=yes",+ "-o",+ "ConnectTimeout=10",+ "-o",+ `StrictHostKeyChecking=${config.strictHostKeyChecking ? "yes" : "no"}`,+ ];++ if (config.strictHostKeyChecking) {+ if (config.knownHosts) {+ const knownHosts = await withTempFile("paperclip-ssh-known-hosts-", config.knownHosts, 0o600);+ tempFiles.push(knownHosts.cleanup);+ sshArgs.push("-o", `UserKnownHostsFile=${knownHosts.path}`);+ }+ } else {+ sshArgs.push("-o", "UserKnownHostsFile=/dev/null");+ }++ if (config.privateKey) {+ const privateKey = await withTempFile("paperclip-ssh-key-", config.privateKey, 0o600);+ tempFiles.push(privateKey.cleanup);+ sshArgs.push("-i", privateKey.path);+ }++ return {+ args: sshArgs,+ cleanup: async () => {+ await Promise.all(tempFiles.map((cleanup) => cleanup()));+ },+ };+}++function tarExcludeArgs(exclude: string[] | undefined): string[] {+ const combined = ["._*", ...(exclude ?? [])];+ return combined.flatMap((entry) => ["--exclude", entry]);+}++function tarSpawnEnv(): NodeJS.ProcessEnv {+ return {+ ...process.env,+ // Prevent macOS bsdtar from emitting AppleDouble metadata files like ._README.md.+ COPYFILE_DISABLE: "1",+ };+}++async function runSshScript(+ config: SshConnectionConfig,+ script: string,+ options: {+ timeoutMs?: number;+ maxBuffer?: number;+ } = {},+): Promise<SshCommandResult> {+ return await runSshCommand(+ config,+ `sh -lc ${shellQuote(script)}`,+ options,+ );+}++async function clearLocalDirectory(+ localDir: string,+ preserveEntries: string[] = [],+): Promise<void> {+ await fs.mkdir(localDir, { recursive: true });+ const preserve = new Set(preserveEntries);+ const entries = await fs.readdir(localDir);+ await Promise.all(+ entries+ .filter((entry) => !preserve.has(entry))+ .map((entry) => fs.rm(path.join(localDir, entry), { recursive: true, force: true })),+ );+}++async function copyDirectoryContents(sourceDir: string, targetDir: string): Promise<void> {+ await fs.mkdir(targetDir, { recursive: true });+ const entries = await fs.readdir(sourceDir);+ await Promise.all(entries.map(async (entry) => {+ await fs.cp(path.join(sourceDir, entry), path.join(targetDir, entry), {+ recursive: true,+ force: true,+ preserveTimestamps: true,+ });+ }));+}++async function readLocalGitWorkspaceSnapshot(localDir: string): Promise<LocalGitWorkspaceSnapshot | null> {+ try {+ const insideWorkTree = await runLocalGit(localDir, ["rev-parse", "--is-inside-work-tree"], {+ timeout: 10_000,+ maxBuffer: 16 * 1024,+ });+ if (insideWorkTree.stdout.trim() !== "true") {+ return null;+ }++ const [headCommitResult, branchResult, deletedResult] = await Promise.all([+ runLocalGit(localDir, ["rev-parse", "HEAD"], {+ timeout: 10_000,+ maxBuffer: 16 * 1024,+ }),+ runLocalGit(localDir, ["rev-parse", "--abbrev-ref", "HEAD"], {+ timeout: 10_000,+ maxBuffer: 16 * 1024,+ }),+ runLocalGit(localDir, ["ls-files", "--deleted", "-z"], {+ timeout: 10_000,+ maxBuffer: 256 * 1024,+ }),+ ]);++ const branchName = branchResult.stdout.trim();+ return {+ headCommit: headCommitResult.stdout.trim(),+ branchName: branchName && branchName !== "HEAD" ? branchName : null,+ deletedPaths: deletedResult.stdout+ .split("\0")+ .map((entry) => entry.trim())+ .filter(Boolean),+ };+ } catch {+ return null;+ }+}++async function streamLocalFileToSsh(input: {+ spec: SshConnectionConfig;+ localFile: string;+ remoteScript: string;+}): Promise<void> {+ const auth = await createSshAuthArgs(input.spec);+ const sshArgs = [+ ...auth.args,+ "-p",+ String(input.spec.port),+ `${input.spec.username}@${input.spec.host}`,+ `sh -lc ${shellQuote(input.remoteScript)}`,+ ];++ await new Promise<void>((resolve, reject) => {+ const source = createReadStream(input.localFile);+ const ssh = spawn("ssh", sshArgs, {+ stdio: ["pipe", "ignore", "pipe"],+ });++ let sshStderr = "";+ let settled = false;++ const fail = (error: Error) => {+ if (settled) return;+ settled = true;+ source.destroy();+ ssh.kill("SIGTERM");+ reject(error);+ };++ ssh.stderr?.on("data", (chunk) => {+ sshStderr += String(chunk);+ });+ source.on("error", fail);+ ssh.on("error", fail);+ source.pipe(ssh.stdin ?? null);+ ssh.on("close", (code) => {+ if (settled) return;+ settled = true;+ if ((code ?? 0) !== 0) {+ reject(new Error(sshStderr.trim() || `ssh exited with code ${code ?? -1}`));+ return;+ }+ resolve();+ });+ }).finally(auth.cleanup);+}++async function streamSshToLocalFile(input: {+ spec: SshConnectionConfig;+ remoteScript: string;+ localFile: string;+}): Promise<void> {+ const auth = await createSshAuthArgs(input.spec);+ const sshArgs = [+ ...auth.args,+ "-p",+ String(input.spec.port),+ `${input.spec.username}@${input.spec.host}`,+ `sh -lc ${shellQuote(input.remoteScript)}`,+ ];++ await new Promise<void>((resolve, reject) => {+ const ssh = spawn("ssh", sshArgs, {+ stdio: ["ignore", "pipe", "pipe"],+ });+ const sink = createWriteStream(input.localFile, { mode: 0o600 });++ let sshStderr = "";+ let settled = false;++ const fail = (error: Error) => {+ if (settled) return;+ settled = true;+ ssh.kill("SIGTERM");+ sink.destroy();+ reject(error);+ };++ ssh.stdout?.pipe(sink);+ ssh.stderr?.on("data", (chunk) => {+ sshStderr += String(chunk);+ });+ ssh.on("error", fail);+ sink.on("error", fail);+ ssh.on("close", (code) => {+ sink.end(() => {+ if (settled) return;+ settled = true;+ if ((code ?? 0) !== 0) {+ reject(new Error(sshStderr.trim() || `ssh exited with code ${code ?? -1}`));+ return;+ }+ resolve();+ });+ });+ }).finally(auth.cleanup);+}++async function importGitWorkspaceToSsh(input: {+ spec: SshRemoteExecutionSpec;+ localDir: string;+ remoteDir: string;+ snapshot: LocalGitWorkspaceSnapshot;+}): Promise<void> {+ const bundleDir = await fs.mkdtemp(path.join(os.tmpdir(), "paperclip-ssh-bundle-"));+ const bundlePath = path.join(bundleDir, "workspace.bundle");+ const tempRef = "refs/paperclip/ssh-sync/import";++ try {+ await runLocalGit(input.localDir, ["update-ref", tempRef, input.snapshot.headCommit], {+ timeout: 10_000,+ maxBuffer: 16 * 1024,+ });+ await runLocalGit(input.localDir, ["bundle", "create", bundlePath, tempRef], {+ timeout: 60_000,+ maxBuffer: 1024 * 1024,+ });++ const remoteSetupScript = [+ "set -e",+ `mkdir -p ${shellQuote(path.posix.join(input.remoteDir, ".paperclip-runtime"))}`,+ `tmp_bundle=$(mktemp ${shellQuote(path.posix.join(input.remoteDir, ".paperclip-runtime", "import-XXXXXX.bundle"))})`,+ 'trap \'rm -f "$tmp_bundle"\' EXIT',+ 'cat > "$tmp_bundle"',+ `if [ ! -d ${shellQuote(path.posix.join(input.remoteDir, ".git"))} ]; then git init ${shellQuote(input.remoteDir)} >/dev/null; fi`,+ `git -C ${shellQuote(input.remoteDir)} fetch --force "$tmp_bundle" '${tempRef}:${tempRef}' >/dev/null`,+ input.snapshot.branchName+ ? `git -C ${shellQuote(input.remoteDir)} checkout -B ${shellQuote(input.snapshot.branchName)} ${shellQuote(input.snapshot.headCommit)} >/dev/null`+ : `git -C ${shellQuote(input.remoteDir)} -c advice.detachedHead=false checkout --detach ${shellQuote(input.snapshot.headCommit)} >/dev/null`,+ `git -C ${shellQuote(input.remoteDir)} reset --hard ${shellQuote(input.snapshot.headCommit)} >/dev/null`,+ `git -C ${shellQuote(input.remoteDir)} clean -fdx -e .paperclip-runtime >/dev/null`,+ ].join("\n");++ await streamLocalFileToSsh({+ spec: input.spec,+ localFile: bundlePath,+ remoteScript: remoteSetupScript,+ });+ } finally {+ await runLocalGit(input.localDir, ["update-ref", "-d", tempRef], {+ timeout: 10_000,+ maxBuffer: 16 * 1024,+ }).catch(() => undefined);+ await fs.rm(bundleDir, { recursive: true, force: true }).catch(() => undefined);+ }+}++async function exportGitWorkspaceFromSsh(input: {+ spec: SshRemoteExecutionSpec;+ remoteDir: string;+ localDir: string;+}): Promise<void> {+ const bundleDir = await fs.mkdtemp(path.join(os.tmpdir(), "paperclip-ssh-bundle-"));+ const bundlePath = path.join(bundleDir, "workspace.bundle");+ const importedRef = "refs/paperclip/ssh-sync/imported";++ try {+ const exportScript = [+ "set -e",+ `git -C ${shellQuote(input.remoteDir)} update-ref refs/paperclip/ssh-sync/export HEAD`,+ `mkdir -p ${shellQuote(path.posix.join(input.remoteDir, ".paperclip-runtime"))}`,+ `tmp_bundle=$(mktemp ${shellQuote(path.posix.join(input.remoteDir, ".paperclip-runtime", "export-XXXXXX.bundle"))})`,+ 'cleanup() { rm -f "$tmp_bundle"; git -C ' + shellQuote(input.remoteDir) + ' update-ref -d refs/paperclip/ssh-sync/export >/dev/null 2>&1 || true; }',+ 'trap cleanup EXIT',+ `git -C ${shellQuote(input.remoteDir)} bundle create "$tmp_bundle" refs/paperclip/ssh-sync/export >/dev/null`,+ 'cat "$tmp_bundle"',+ ].join("\n");++ await streamSshToLocalFile({+ spec: input.spec,+ remoteScript: exportScript,+ localFile: bundlePath,+ });++ await runLocalGit(input.localDir, ["fetch", "--force", bundlePath, `refs/paperclip/ssh-sync/export:${importedRef}`], {+ timeout: 60_000,+ maxBuffer: 1024 * 1024,+ });+ await runLocalGit(input.localDir, ["reset", "--hard", importedRef], {+ timeout: 60_000,+ maxBuffer: 1024 * 1024,+ });+ } finally {+ await runLocalGit(input.localDir, ["update-ref", "-d", importedRef], {+ timeout: 10_000,+ maxBuffer: 16 * 1024,+ }).catch(() => undefined);+ await fs.rm(bundleDir, { recursive: true, force: true }).catch(() => undefined);+ }+}++async function clearRemoteDirectory(input: {+ spec: SshConnectionConfig;+ remoteDir: string;+ preserveEntries?: string[];+}): Promise<void> {+ const preservePatterns = (input.preserveEntries ?? [])+ .map((entry) => `! -name ${shellQuote(entry)}`)+ .join(" ");+ const script = [+ "set -e",+ `mkdir -p ${shellQuote(input.remoteDir)}`,+ `find ${shellQuote(input.remoteDir)} -mindepth 1 -maxdepth 1 ${preservePatterns} -exec rm -rf -- {} +`,+ ].join("\n");+ await runSshScript(input.spec, script, {+ timeoutMs: 30_000,+ maxBuffer: 256 * 1024,+ });+}++async function removeDeletedPathsOnSsh(input: {+ spec: SshConnectionConfig;+ remoteDir: string;+ deletedPaths: string[];+}): Promise<void> {+ if (input.deletedPaths.length === 0) return;+ const quotedPaths = input.deletedPaths.map((entry) => shellQuote(entry)).join(" ");+ const script = `cd ${shellQuote(input.remoteDir)} && rm -rf -- ${quotedPaths}`;+ await runSshScript(input.spec, script, {+ timeoutMs: 30_000,+ maxBuffer: 256 * 1024,+ });+}++async function allocateLoopbackPort(host: string): Promise<number> {+ return await new Promise<number>((resolve, reject) => {+ const server = net.createServer();+ server.once("error", reject);+ server.listen(0, host, () => {+ const address = server.address();+ if (!address || typeof address === "string") {+ server.close(() => reject(new Error("Failed to allocate a loopback port.")));+ return;+ }+ const { port } = address;+ server.close((error) => {+ if (error) {+ reject(error);+ return;+ }+ resolve(port);+ });+ });+ });+}++async function waitForCondition(+ fn: () => Promise<void>,+ options: {+ timeoutMs?: number;+ intervalMs?: number;+ } = {},+): Promise<void> {+ const timeoutAt = Date.now() + (options.timeoutMs ?? 10_000);+ const intervalMs = options.intervalMs ?? 200;+ let lastError: unknown = null;+ while (Date.now() < timeoutAt) {+ try {+ await fn();+ return;+ } catch (error) {+ lastError = error;+ await new Promise((resolve) => setTimeout(resolve, intervalMs));+ }+ }+ throw lastError instanceof Error+ ? lastError+ : new Error("Timed out waiting for SSH fixture readiness.");+}++async function isPidRunning(pid: number): Promise<boolean> {+ try {+ process.kill(pid, 0);+ return true;+ } catch {+ return false;+ }+}++async function readProcessCommand(pid: number): Promise<string | null> {+ for (const format of ["command=", "args="]) {+ try {+ const result = await execFileText("ps", ["-o", format, "-p", String(pid)], {+ timeout: 5_000,+ maxBuffer: 16 * 1024,+ });+ const command = result.stdout.trim();+ if (command.length > 0) {+ return command;+ }+ } catch {+ continue;+ }+ }++ return null;+}++async function isSshEnvLabFixtureProcess(state: Pick<SshEnvLabFixtureState, "pid" | "sshdConfigPath">): Promise<boolean> {+ if (!(await isPidRunning(state.pid))) {+ return false;+ }++ const command = await readProcessCommand(state.pid);+ if (!command) {+ return false;+ }++ return command.includes(state.sshdConfigPath);+}++export async function getSshEnvLabSupport(): Promise<SshEnvLabSupport> {+ for (const command of ["ssh", "sshd", "ssh-keygen"]) {+ if (!(await commandExists(command))) {+ return {+ supported: false,+ reason: `Missing required command: ${command}`,+ };+ }+ }++ return {+ supported: true,+ reason: null,+ };+}++export function buildKnownHostsEntry(input: {+ host: string;+ port: number;+ publicKey: string;+}): string {+ return `[${input.host}]:${input.port} ${input.publicKey.trim()}`;+}++export async function runSshCommand(+ config: SshConnectionConfig,+ remoteCommand: string,+ options: {+ timeoutMs?: number;+ maxBuffer?: number;+ } = {},+): Promise<SshCommandResult> {+ let cleanup: () => Promise<void> = () => Promise.resolve();+ try {+ const auth = await createSshAuthArgs(config);+ cleanup = auth.cleanup;+ const sshArgs = [...auth.args];++ sshArgs.push(+ "-p",+ String(config.port),+ `${config.username}@${config.host}`,+ remoteCommand,+ );++ return await execFileText("ssh", sshArgs, {+ timeout: options.timeoutMs ?? 15_000,+ maxBuffer: options.maxBuffer ?? 1024 * 128,+ });+ } finally {+ await cleanup();+ }+}++export async function buildSshSpawnTarget(input: {+ spec: SshRemoteExecutionSpec;+ command: string;+ args: string[];+ env: Record<string, string>;+}): Promise<{+ command: string;+ args: string[];+ cleanup: () => Promise<void>;+}> {+ for (const key of Object.keys(input.env)) {+ if (!isValidShellEnvKey(key)) {+ throw new Error(`Invalid SSH environment variable key: ${key}`);+ }+ }+ const auth = await createSshAuthArgs(input.spec);+ const sshArgs = [...auth.args];+ const envArgs = Object.entries(input.env)+ .filter((entry): entry is [string, string] => typeof entry[1] === "string")+ .map(([key, value]) => `${key}=${shellQuote(value)}`);+ const remoteCommandParts = [shellQuote(input.command), ...input.args.map((arg) => shellQuote(arg))].join(" ");+ const remoteScript = [+ 'if [ -f "$HOME/.profile" ]; then . "$HOME/.profile" >/dev/null 2>&1 || true; fi',+ 'if [ -f "$HOME/.bash_profile" ]; then . "$HOME/.bash_profile" >/dev/null 2>&1 || true; fi',+ 'if [ -f "$HOME/.zprofile" ]; then . "$HOME/.zprofile" >/dev/null 2>&1 || true; fi',+ 'export NVM_DIR="${NVM_DIR:-$HOME/.nvm}"',+ '[ -s "$NVM_DIR/nvm.sh" ] && . "$NVM_DIR/nvm.sh" >/dev/null 2>&1 || true',+ `cd ${shellQuote(input.spec.remoteCwd)}`,+ envArgs.length > 0+ ? `exec env ${envArgs.join(" ")} ${remoteCommandParts}`+ : `exec ${remoteCommandParts}`,+ ].join(" && ");++ sshArgs.push(+ "-p",+ String(input.spec.port),+ `${input.spec.username}@${input.spec.host}`,+ `sh -lc ${shellQuote(remoteScript)}`,+ );++ return {+ command: "ssh",+ args: sshArgs,+ cleanup: auth.cleanup,+ };+}++export async function syncDirectoryToSsh(input: {+ spec: SshRemoteExecutionSpec;+ localDir: string;+ remoteDir: string;+ exclude?: string[];+ followSymlinks?: boolean;+}): Promise<void> {+ const auth = await createSshAuthArgs(input.spec);+ const sshArgs = [+ ...auth.args,+ "-p",+ String(input.spec.port),+ `${input.spec.username}@${input.spec.host}`,+ `sh -lc ${shellQuote(`mkdir -p ${shellQuote(input.remoteDir)} && tar -xf - -C ${shellQuote(input.remoteDir)}`)}`,+ ];++ await new Promise<void>((resolve, reject) => {+ const tarArgs = [+ ...(input.followSymlinks ? ["-h"] : []),+ "-C",+ input.localDir,+ ...tarExcludeArgs(input.exclude),+ "-cf",+ "-",+ ".",+ ];+ const tar = spawn("tar", tarArgs, {+ stdio: ["ignore", "pipe", "pipe"],+ env: tarSpawnEnv(),+ });+ const ssh = spawn("ssh", sshArgs, {+ stdio: ["pipe", "ignore", "pipe"],+ });++ let tarStderr = "";+ let sshStderr = "";+ let settled = false;+ let tarExited = false;+ let sshExited = false;+ let tarExitCode: number | null = null;+ let sshExitCode: number | null = null;++ const maybeFinish = () => {+ if (settled || !tarExited || !sshExited) {+ return;+ }+ settled = true;+ if ((tarExitCode ?? 0) !== 0) {+ reject(new Error(tarStderr.trim() || `tar exited with code ${tarExitCode ?? -1}`));+ return;+ }+ if ((sshExitCode ?? 0) !== 0) {+ reject(new Error(sshStderr.trim() || `ssh exited with code ${sshExitCode ?? -1}`));+ return;+ }+ resolve();+ };++ const fail = (error: Error) => {+ if (settled) {+ return;+ }+ settled = true;+ tar.kill("SIGTERM");+ ssh.kill("SIGTERM");+ reject(error);+ };++ tar.stdout?.pipe(ssh.stdin ?? null);+ tar.stderr?.on("data", (chunk) => {+ tarStderr += String(chunk);+ });+ ssh.stderr?.on("data", (chunk) => {+ sshStderr += String(chunk);+ });++ tar.on("error", fail);+ ssh.on("error", fail);+ tar.on("close", (code) => {+ tarExited = true;+ tarExitCode = code;+ maybeFinish();+ });+ ssh.on("close", (code) => {+ sshExited = true;+ sshExitCode = code;+ maybeFinish();+ });+ }).finally(auth.cleanup);+}++export async function syncDirectoryFromSsh(input: {+ spec: SshRemoteExecutionSpec;+ remoteDir: string;+ localDir: string;+ exclude?: string[];+ preserveLocalEntries?: string[];+}): Promise<void> {+ const auth = await createSshAuthArgs(input.spec);+ const stagingDir = await fs.mkdtemp(path.join(os.tmpdir(), "paperclip-ssh-sync-back-"));+ const remoteTarScript = [+ `cd ${shellQuote(input.remoteDir)}`,+ `tar ${[...tarExcludeArgs(input.exclude).map(shellQuote), "-cf", "-", "."].join(" ")}`,+ ].join(" && ");+ const sshArgs = [+ ...auth.args,+ "-p",+ String(input.spec.port),+ `${input.spec.username}@${input.spec.host}`,+ `sh -lc ${shellQuote(remoteTarScript)}`,+ ];++ try {+ await new Promise<void>((resolve, reject) => {+ const ssh = spawn("ssh", sshArgs, {+ stdio: ["ignore", "pipe", "pipe"],+ });+ const tar = spawn("tar", ["-xf", "-", "-C", stagingDir], {+ stdio: ["pipe", "ignore", "pipe"],+ env: tarSpawnEnv(),+ });++ let sshStderr = "";+ let tarStderr = "";+ let settled = false;+ let sshExited = false;+ let tarExited = false;+ let sshExitCode: number | null = null;+ let tarExitCode: number | null = null;++ const maybeFinish = () => {+ if (settled || !sshExited || !tarExited) return;+ settled = true;+ if ((sshExitCode ?? 0) !== 0) {+ reject(new Error(sshStderr.trim() || `ssh exited with code ${sshExitCode ?? -1}`));+ return;+ }+ if ((tarExitCode ?? 0) !== 0) {+ reject(new Error(tarStderr.trim() || `tar exited with code ${tarExitCode ?? -1}`));+ return;+ }+ resolve();+ };++ const fail = (error: Error) => {+ if (settled) return;+ settled = true;+ ssh.kill("SIGTERM");+ tar.kill("SIGTERM");+ reject(error);+ };++ ssh.stdout?.pipe(tar.stdin ?? null);+ ssh.stderr?.on("data", (chunk) => {+ sshStderr += String(chunk);+ });+ tar.stderr?.on("data", (chunk) => {+ tarStderr += String(chunk);+ });++ ssh.on("error", fail);+ tar.on("error", fail);+ ssh.on("close", (code) => {+ sshExited = true;+ sshExitCode = code;+ maybeFinish();+ });+ tar.on("close", (code) => {+ tarExited = true;+ tarExitCode = code;+ maybeFinish();+ });+ });++ await clearLocalDirectory(input.localDir, input.preserveLocalEntries);+ await copyDirectoryContents(stagingDir, input.localDir);+ } finally {+ await fs.rm(stagingDir, { recursive: true, force: true }).catch(() => undefined);+ await auth.cleanup();+ }+}++export async function prepareWorkspaceForSshExecution(input: {+ spec: SshRemoteExecutionSpec;+ localDir: string;+ remoteDir?: string;+}): Promise<void> {+ const remoteDir = input.remoteDir ?? input.spec.remoteCwd;+ const gitSnapshot = await readLocalGitWorkspaceSnapshot(input.localDir);++ if (gitSnapshot) {+ await importGitWorkspaceToSsh({+ spec: input.spec,+ localDir: input.localDir,+ remoteDir,+ snapshot: gitSnapshot,+ });+ await syncDirectoryToSsh({+ spec: input.spec,+ localDir: input.localDir,+ remoteDir,+ exclude: [".git", ".paperclip-runtime"],+ });+ await removeDeletedPathsOnSsh({+ spec: input.spec,+ remoteDir,+ deletedPaths: gitSnapshot.deletedPaths,+ });+ return;+ }++ await clearRemoteDirectory({+ spec: input.spec,+ remoteDir,+ preserveEntries: [".paperclip-runtime"],+ });+ await syncDirectoryToSsh({+ spec: input.spec,+ localDir: input.localDir,+ remoteDir,+ exclude: [".paperclip-runtime"],+ });+}++export async function restoreWorkspaceFromSshExecution(input: {+ spec: SshRemoteExecutionSpec;+ localDir: string;+ remoteDir?: string;+}): Promise<void> {+ const remoteDir = input.remoteDir ?? input.spec.remoteCwd;+ const gitSnapshot = await readLocalGitWorkspaceSnapshot(input.localDir);++ if (gitSnapshot) {+ await exportGitWorkspaceFromSsh({+ spec: input.spec,+ remoteDir,+ localDir: input.localDir,+ });+ await syncDirectoryFromSsh({+ spec: input.spec,+ remoteDir,+ localDir: input.localDir,+ exclude: [".git", ".paperclip-runtime"],+ preserveLocalEntries: [".git"],+ });+ return;+ }++ await syncDirectoryFromSsh({+ spec: input.spec,+ remoteDir,+ localDir: input.localDir,+ exclude: [".paperclip-runtime"],+ });+}++export async function ensureSshWorkspaceReady(+ config: SshConnectionConfig,+): Promise<{ remoteCwd: string }> {+ const result = await runSshCommand(+ config,+ `sh -lc ${shellQuote(`mkdir -p ${shellQuote(config.remoteWorkspacePath)} && cd ${shellQuote(config.remoteWorkspacePath)} && pwd`)}`,+ );+ return {+ remoteCwd: result.stdout.trim(),+ };+}++export async function readSshEnvLabFixtureState(+ statePath: string,+): Promise<SshEnvLabFixtureState | null> {+ try {+ const raw = JSON.parse(await fs.readFile(statePath, "utf8")) as SshEnvLabFixtureState;+ if (!raw || raw.kind !== "ssh_openbsd") return null;+ return raw;+ } catch {+ return null;+ }+}++export async function stopSshEnvLabFixture(statePath: string): Promise<boolean> {+ const state = await readSshEnvLabFixtureState(statePath);+ if (!state) return false;++ if (await isSshEnvLabFixtureProcess(state)) {+ process.kill(state.pid, "SIGTERM");+ await waitForCondition(async () => {+ if (await isSshEnvLabFixtureProcess(state)) {+ throw new Error("SSH fixture process is still running.");+ }+ }, { timeoutMs: 5_000, intervalMs: 100 });+ }++ await fs.rm(state.rootDir, { recursive: true, force: true }).catch(() => undefined);+ return true;+}++export async function startSshEnvLabFixture(input: {+ statePath: string;+ bindHost?: string;+ host?: string;+}): Promise<SshEnvLabFixtureState> {+ const existing = await readSshEnvLabFixtureState(input.statePath);+ if (existing && await isSshEnvLabFixtureProcess(existing)) {+ return existing;+ }+ if (existing) {+ await fs.rm(existing.rootDir, { recursive: true, force: true }).catch(() => undefined);+ }++ const support = await getSshEnvLabSupport();+ if (!support.supported) {+ throw new Error(`SSH env-lab fixture is unavailable: ${support.reason}`);+ }+ const sshdPath = await resolveCommandPath("sshd");+ if (!sshdPath) {+ throw new Error("SSH env-lab fixture is unavailable: missing required command: sshd");+ }++ const bindHost = input.bindHost ?? "127.0.0.1";+ const host = input.host ?? bindHost;+ const rootDir = path.dirname(input.statePath);+ await fs.mkdir(rootDir, { recursive: true });++ const username = os.userInfo().username;+ const port = await allocateLoopbackPort(bindHost);+ const workspaceDir = path.join(rootDir, "workspace");+ const clientPrivateKeyPath = path.join(rootDir, "client_key");+ const clientPublicKeyPath = `${clientPrivateKeyPath}.pub`;+ const hostPrivateKeyPath = path.join(rootDir, "host_key");+ const hostPublicKeyPath = `${hostPrivateKeyPath}.pub`;+ const authorizedKeysPath = path.join(rootDir, "authorized_keys");+ const knownHostsPath = path.join(rootDir, "known_hosts");+ const sshdConfigPath = path.join(rootDir, "sshd_config");+ const sshdLogPath = path.join(rootDir, "sshd.log");+ const sshdPidPath = path.join(rootDir, "sshd.pid");++ await fs.mkdir(workspaceDir, { recursive: true });+ await execFileText("ssh-keygen", ["-q", "-t", "ed25519", "-N", "", "-f", clientPrivateKeyPath], {+ timeout: 15_000,+ });+ await execFileText("ssh-keygen", ["-q", "-t", "ed25519", "-N", "", "-f", hostPrivateKeyPath], {+ timeout: 15_000,+ });++ await fs.copyFile(clientPublicKeyPath, authorizedKeysPath);+ const hostPublicKey = (await execFileText("ssh-keygen", ["-y", "-f", hostPrivateKeyPath], {+ timeout: 15_000,+ })).stdout.trim();+ await fs.writeFile(+ knownHostsPath,+ `${buildKnownHostsEntry({ host, port, publicKey: hostPublicKey })}\n`,+ { mode: 0o600 },+ );+ await fs.writeFile(+ sshdConfigPath,+ [+ `Port ${port}`,+ `ListenAddress ${bindHost}`,+ `HostKey ${hostPrivateKeyPath}`,+ `PidFile ${sshdPidPath}`,+ `AuthorizedKeysFile ${authorizedKeysPath}`,+ "PasswordAuthentication no",+ "ChallengeResponseAuthentication no",+ "KbdInteractiveAuthentication no",+ "PubkeyAuthentication yes",+ "PermitRootLogin no",+ "UsePAM no",+ "StrictModes no",+ `AllowUsers ${username}`,+ "LogLevel VERBOSE",+ "PrintMotd no",+ "UseDNS no",+ "Subsystem sftp internal-sftp",+ "",+ ].join("\n"),+ { mode: 0o600 },+ );++ const child = spawn(sshdPath, ["-D", "-f", sshdConfigPath, "-E", sshdLogPath], {+ detached: true,+ stdio: "ignore",+ });+ child.unref();++ const state: SshEnvLabFixtureState = {+ kind: "ssh_openbsd",+ bindHost,+ host,+ port,+ username,+ rootDir,+ workspaceDir,+ statePath: input.statePath,+ pid: child.pid ?? 0,+ createdAt: new Date().toISOString(),+ clientPrivateKeyPath,+ clientPublicKeyPath,+ hostPrivateKeyPath,+ hostPublicKeyPath,+ authorizedKeysPath,+ knownHostsPath,+ sshdConfigPath,+ sshdLogPath,+ };++ if (!state.pid) {+ throw new Error("Failed to start SSH env-lab fixture.");+ }++ try {+ await waitForCondition(async () => {+ if (!(await isPidRunning(state.pid))) {+ const logOutput = await fs.readFile(sshdLogPath, "utf8").catch(() => "");+ throw new Error(logOutput || "SSH env-lab fixture exited before becoming ready.");+ }+ const config = await buildSshEnvLabFixtureConfig(state);+ await ensureSshWorkspaceReady(config);+ }, { timeoutMs: 10_000, intervalMs: 250 });+ await fs.writeFile(input.statePath, JSON.stringify(state, null, 2), { mode: 0o600 });+ return state;+ } catch (error) {+ if (await isPidRunning(state.pid)) {+ process.kill(state.pid, "SIGTERM");+ }+ await fs.rm(rootDir, { recursive: true, force: true }).catch(() => undefined);+ throw error;+ }+}++export async function buildSshEnvLabFixtureConfig(+ state: SshEnvLabFixtureState,+): Promise<SshConnectionConfig> {+ const [privateKey, knownHosts] = await Promise.all([+ fs.readFile(state.clientPrivateKeyPath, "utf8"),+ fs.readFile(state.knownHostsPath, "utf8"),+ ]);+ return {+ host: state.host,+ port: state.port,+ username: state.username,+ remoteWorkspacePath: state.workspaceDir,+ privateKey,+ knownHosts,+ strictHostKeyChecking: true,+ };+}++export async function readSshEnvLabFixtureStatus(statePath: string): Promise<{+ running: boolean;+ state: SshEnvLabFixtureState | null;+}> {+ const state = await readSshEnvLabFixtureState(statePath);+ if (!state) {+ return { running: false, state: null };+ }+ return {+ running: await isSshEnvLabFixtureProcess(state),+ state,+ };+}++export async function fileExists(filePath: string): Promise<boolean> {+ try {+ await fs.access(filePath, fsConstants.F_OK);+ return true;+ } catch {+ return false;+ }+}diff --git a/packages/adapter-utils/src/types.ts b/packages/adapter-utils/src/types.tsindex e02b9efe8d..ff00a0e989 100644--- a/packages/adapter-utils/src/types.ts+++ b/packages/adapter-utils/src/types.ts@@ -2,6 +2,9 @@// Minimal adapter-facing interfaces (no drizzle dependency)// ---------------------------------------------------------------------------+import type { SshRemoteExecutionSpec } from "./ssh.js";+import type { AdapterExecutionTarget } from "./execution-target.js";+export interface AdapterAgent {id: string;companyId: string;@@ -118,6 +121,14 @@ export interface AdapterExecutionContext {runtime: AdapterRuntime;config: Record<string, unknown>;context: Record<string, unknown>;+ executionTarget?: AdapterExecutionTarget | null;+ /**+ * Legacy remote transport view. Prefer `executionTarget`, which is the+ * provider-neutral contract produced by core runtime code.+ */+ executionTransport?: {+ remoteExecution?: Record<string, unknown> | null;+ };onLog: (stream: "stdout" | "stderr", chunk: string) => Promise<void>;onMeta?: (meta: AdapterInvocationMeta) => Promise<void>;onSpawn?: (meta: { pid: number; processGroupId: number | null; startedAt: string }) => Promise<void>;@@ -417,6 +428,7 @@ export interface CreateConfigValues {workspaceBranchTemplate?: string;worktreeParentDir?: string;runtimeServicesJson?: string;+ defaultEnvironmentId?: string;maxTurnsPerRun: number;heartbeatEnabled: boolean;intervalSec: number;diff --git a/packages/adapters/claude-local/src/server/execute.remote.test.ts b/packages/adapters/claude-local/src/server/execute.remote.test.tsnew file mode 100644index 0000000000..c96b91643f--- /dev/null+++ b/packages/adapters/claude-local/src/server/execute.remote.test.ts@@ -0,0 +1,262 @@+import { mkdir, mkdtemp, rm, writeFile } from "node:fs/promises";+import os from "node:os";+import path from "node:path";+import { afterEach, describe, expect, it, vi } from "vitest";++const {+ runChildProcess,+ ensureCommandResolvable,+ resolveCommandForLogs,+ prepareWorkspaceForSshExecution,+ restoreWorkspaceFromSshExecution,+ syncDirectoryToSsh,+} = vi.hoisted(() => ({+ runChildProcess: vi.fn(async () => ({+ exitCode: 0,+ signal: null,+ timedOut: false,+ stdout: [+ JSON.stringify({ type: "system", subtype: "init", session_id: "claude-session-1", model: "claude-sonnet" }),+ JSON.stringify({ type: "assistant", session_id: "claude-session-1", message: { content: [{ type: "text", text: "hello" }] } }),+ JSON.stringify({ type: "result", session_id: "claude-session-1", result: "hello", usage: { input_tokens: 1, cache_read_input_tokens: 0, output_tokens: 1 } }),+ ].join("\n"),+ stderr: "",+ pid: 123,+ startedAt: new Date().toISOString(),+ })),+ ensureCommandResolvable: vi.fn(async () => undefined),+ resolveCommandForLogs: vi.fn(async () => "ssh://[email protected]:2222/remote/workspace :: claude"),+ prepareWorkspaceForSshExecution: vi.fn(async () => undefined),+ restoreWorkspaceFromSshExecution: vi.fn(async () => undefined),+ syncDirectoryToSsh: vi.fn(async () => undefined),+}));++vi.mock("@paperclipai/adapter-utils/server-utils", async () => {+ const actual = await vi.importActual<typeof import("@paperclipai/adapter-utils/server-utils")>(+ "@paperclipai/adapter-utils/server-utils",+ );+ return {+ ...actual,+ ensureCommandResolvable,+ resolveCommandForLogs,+ runChildProcess,+ };+});++vi.mock("@paperclipai/adapter-utils/ssh", async () => {+ const actual = await vi.importActual<typeof import("@paperclipai/adapter-utils/ssh")>(+ "@paperclipai/adapter-utils/ssh",+ );+ return {+ ...actual,+ prepareWorkspaceForSshExecution,+ restoreWorkspaceFromSshExecution,+ syncDirectoryToSsh,+ };+});++import { execute } from "./execute.js";++describe("claude remote execution", () => {+ const cleanupDirs: string[] = [];++ afterEach(async () => {+ vi.clearAllMocks();+ while (cleanupDirs.length > 0) {+ const dir = cleanupDirs.pop();+ if (!dir) continue;+ await rm(dir, { recursive: true, force: true }).catch(() => undefined);+ }+ });++ it("prepares the workspace, syncs Claude runtime assets, and restores workspace changes for remote SSH execution", async () => {+ const rootDir = await mkdtemp(path.join(os.tmpdir(), "paperclip-claude-remote-"));+ cleanupDirs.push(rootDir);+ const workspaceDir = path.join(rootDir, "workspace");+ const instructionsPath = path.join(rootDir, "instructions.md");+ await mkdir(workspaceDir, { recursive: true });+ await writeFile(instructionsPath, "Use the remote workspace.\n", "utf8");++ await execute({+ runId: "run-1",+ agent: {+ id: "agent-1",+ companyId: "company-1",+ name: "Claude Coder",+ adapterType: "claude_local",+ adapterConfig: {},+ },+ runtime: {+ sessionId: null,+ sessionParams: null,+ sessionDisplayId: null,+ taskKey: null,+ },+ config: {+ command: "claude",+ instructionsFilePath: instructionsPath,+ },+ context: {+ paperclipWorkspace: {+ cwd: workspaceDir,+ source: "project_primary",+ },+ },+ executionTransport: {+ remoteExecution: {+ host: "127.0.0.1",+ port: 2222,+ username: "fixture",+ remoteWorkspacePath: "/remote/workspace",+ remoteCwd: "/remote/workspace",+ privateKey: "PRIVATE KEY",+ knownHosts: "[127.0.0.1]:2222 ssh-ed25519 AAAA",+ strictHostKeyChecking: true,+ paperclipApiUrl: "http://198.51.100.10:3102",+ },+ },+ onLog: async () => {},+ });++ expect(prepareWorkspaceForSshExecution).toHaveBeenCalledTimes(1);+ expect(prepareWorkspaceForSshExecution).toHaveBeenCalledWith(expect.objectContaining({+ localDir: workspaceDir,+ remoteDir: "/remote/workspace",+ }));+ expect(syncDirectoryToSsh).toHaveBeenCalledTimes(1);+ expect(syncDirectoryToSsh).toHaveBeenCalledWith(expect.objectContaining({+ remoteDir: "/remote/workspace/.paperclip-runtime/claude/skills",+ followSymlinks: true,+ }));+ expect(runChildProcess).toHaveBeenCalledTimes(1);+ const call = runChildProcess.mock.calls[0] as unknown as+ | [string, string, string[], { env: Record<string, string>; remoteExecution?: { remoteCwd: string } | null }]+ | undefined;+ expect(call?.[2]).toContain("--append-system-prompt-file");+ expect(call?.[2]).toContain("/remote/workspace/.paperclip-runtime/claude/skills/agent-instructions.md");+ expect(call?.[2]).toContain("--add-dir");+ expect(call?.[2]).toContain("/remote/workspace/.paperclip-runtime/claude/skills");+ expect(call?.[3].env.PAPERCLIP_API_URL).toBe("http://198.51.100.10:3102");+ expect(call?.[3].remoteExecution?.remoteCwd).toBe("/remote/workspace");+ expect(restoreWorkspaceFromSshExecution).toHaveBeenCalledTimes(1);+ expect(restoreWorkspaceFromSshExecution).toHaveBeenCalledWith(expect.objectContaining({+ localDir: workspaceDir,+ remoteDir: "/remote/workspace",+ }));+ });++ it("does not resume saved Claude sessions for remote SSH execution without a matching remote identity", async () => {+ const rootDir = await mkdtemp(path.join(os.tmpdir(), "paperclip-claude-remote-resume-"));+ cleanupDirs.push(rootDir);+ const workspaceDir = path.join(rootDir, "workspace");+ await mkdir(workspaceDir, { recursive: true });++ await execute({+ runId: "run-ssh-no-resume",+ agent: {+ id: "agent-1",+ companyId: "company-1",+ name: "Claude Coder",+ adapterType: "claude_local",+ adapterConfig: {},+ },+ runtime: {+ sessionId: "session-123",+ sessionParams: {+ sessionId: "session-123",+ cwd: "/remote/workspace",+ },+ sessionDisplayId: "session-123",+ taskKey: null,+ },+ config: {+ command: "claude",+ },+ context: {+ paperclipWorkspace: {+ cwd: workspaceDir,+ source: "project_primary",+ },+ },+ executionTransport: {+ remoteExecution: {+ host: "127.0.0.1",+ port: 2222,+ username: "fixture",+ remoteWorkspacePath: "/remote/workspace",+ remoteCwd: "/remote/workspace",+ privateKey: "PRIVATE KEY",+ knownHosts: "[127.0.0.1]:2222 ssh-ed25519 AAAA",+ strictHostKeyChecking: true,+ },+ },+ onLog: async () => {},+ });++ expect(runChildProcess).toHaveBeenCalledTimes(1);+ const call = runChildProcess.mock.calls[0] as unknown as [string, string, string[]] | undefined;+ expect(call?.[2]).not.toContain("--resume");+ });++ it("resumes saved Claude sessions for remote SSH execution when the remote identity matches", async () => {+ const rootDir = await mkdtemp(path.join(os.tmpdir(), "paperclip-claude-remote-resume-match-"));+ cleanupDirs.push(rootDir);+ const workspaceDir = path.join(rootDir, "workspace");+ await mkdir(workspaceDir, { recursive: true });++ await execute({+ runId: "run-ssh-resume",+ agent: {+ id: "agent-1",+ companyId: "company-1",+ name: "Claude Coder",+ adapterType: "claude_local",+ adapterConfig: {},+ },+ runtime: {+ sessionId: "session-123",+ sessionParams: {+ sessionId: "session-123",+ cwd: "/remote/workspace",+ remoteExecution: {+ transport: "ssh",+ host: "127.0.0.1",+ port: 2222,+ username: "fixture",+ remoteCwd: "/remote/workspace",+ },+ },+ sessionDisplayId: "session-123",+ taskKey: null,+ },+ config: {+ command: "claude",+ },+ context: {+ paperclipWorkspace: {+ cwd: workspaceDir,+ source: "project_primary",+ },+ },+ executionTransport: {+ remoteExecution: {+ host: "127.0.0.1",+ port: 2222,+ username: "fixture",+ remoteWorkspacePath: "/remote/workspace",+ remoteCwd: "/remote/workspace",+ privateKey: "PRIVATE KEY",+ knownHosts: "[127.0.0.1]:2222 ssh-ed25519 AAAA",+ strictHostKeyChecking: true,+ },+ },+ onLog: async () => {},+ });++ expect(runChildProcess).toHaveBeenCalledTimes(1);+ const call = runChildProcess.mock.calls[0] as unknown as [string, string, string[]] | undefined;+ expect(call?.[2]).toContain("--resume");+ expect(call?.[2]).toContain("session-123");+ });++});diff --git a/packages/adapters/claude-local/src/server/execute.ts b/packages/adapters/claude-local/src/server/execute.tsindex 79327fdb44..6fa870c85d 100644--- a/packages/adapters/claude-local/src/server/execute.ts+++ b/packages/adapters/claude-local/src/server/execute.ts@@ -3,6 +3,20 @@ import path from "node:path";import { fileURLToPath } from "node:url";import type { AdapterExecutionContext, AdapterExecutionResult } from "@paperclipai/adapter-utils";import type { RunProcessResult } from "@paperclipai/adapter-utils/server-utils";+import {+ adapterExecutionTargetIsRemote,+ adapterExecutionTargetPaperclipApiUrl,+ adapterExecutionTargetRemoteCwd,+ adapterExecutionTargetSessionIdentity,+ adapterExecutionTargetSessionMatches,+ adapterExecutionTargetUsesManagedHome,+ describeAdapterExecutionTarget,+ ensureAdapterExecutionTargetCommandResolvable,+ prepareAdapterExecutionTargetRuntime,+ readAdapterExecutionTarget,+ resolveAdapterExecutionTargetCommandForLogs,+ runAdapterExecutionTargetProcess,+} from "@paperclipai/adapter-utils/execution-target";import {asString,asNumber,@@ -15,14 +29,11 @@ import {joinPromptSections,buildInvocationEnvForLogs,ensureAbsoluteDirectory,- ensureCommandResolvable,ensurePathInEnv,- resolveCommandForLogs,renderTemplate,renderPaperclipWakePrompt,stringifyPaperclipWakePayload,DEFAULT_PAPERCLIP_AGENT_PROMPT_TEMPLATE,- runChildProcess,} from "@paperclipai/adapter-utils/server-utils";import {parseClaudeStreamJson,@@ -42,6 +53,7 @@ interface ClaudeExecutionInput {agent: AdapterExecutionContext["agent"];config: Record<string, unknown>;context: Record<string, unknown>;+ executionTarget?: ReturnType<typeof readAdapterExecutionTarget>;authToken?: string;}@@ -92,7 +104,7 @@ function resolveClaudeBillingType(env: Record<string, string>): "api" | "subscri}async function buildClaudeRuntimeConfig(input: ClaudeExecutionInput): Promise<ClaudeRuntimeConfig> {- const { runId, agent, config, context, authToken } = input;+ const { runId, agent, config, context, executionTarget, authToken } = input;const command = asString(config.command, "claude");const workspaceContext = parseObject(context.paperclipWorkspace);@@ -218,6 +230,10 @@ async function buildClaudeRuntimeConfig(input: ClaudeExecutionInput): Promise<Clif (runtimePrimaryUrl) {env.PAPERCLIP_RUNTIME_PRIMARY_URL = runtimePrimaryUrl;}+ const targetPaperclipApiUrl = adapterExecutionTargetPaperclipApiUrl(executionTarget);+ if (targetPaperclipApiUrl) {+ env.PAPERCLIP_API_URL = targetPaperclipApiUrl;+ }for (const [key, value] of Object.entries(envConfig)) {if (typeof value === "string") env[key] = value;@@ -228,8 +244,8 @@ async function buildClaudeRuntimeConfig(input: ClaudeExecutionInput): Promise<Cl}const runtimeEnv = ensurePathInEnv({ ...process.env, ...env });- await ensureCommandResolvable(command, cwd, runtimeEnv);- const resolvedCommand = await resolveCommandForLogs(command, cwd, runtimeEnv);+ await ensureAdapterExecutionTargetCommandResolvable(command, executionTarget, cwd, runtimeEnv);+ const resolvedCommand = await resolveAdapterExecutionTargetCommandForLogs(command, executionTarget, cwd, runtimeEnv);const loggedEnv = buildInvocationEnvForLogs(env, {runtimeEnv,includeRuntimeKeys: ["HOME", "CLAUDE_CONFIG_DIR"],@@ -276,7 +292,7 @@ export async function runClaudeLogin(input: {authToken: input.authToken,});- const proc = await runChildProcess(input.runId, runtime.command, ["login"], {+ const proc = await runAdapterExecutionTargetProcess(input.runId, null, runtime.command, ["login"], {cwd: runtime.cwd,env: runtime.env,timeoutSec: runtime.timeoutSec,@@ -298,6 +314,11 @@ export async function runClaudeLogin(input: {export async function execute(ctx: AdapterExecutionContext): Promise<AdapterExecutionResult> {const { runId, agent, runtime, config, context, onLog, onMeta, onSpawn, authToken } = ctx;+ const executionTarget = readAdapterExecutionTarget({+ executionTarget: ctx.executionTarget,+ legacyRemoteExecution: ctx.executionTransport?.remoteExecution,+ });+ const executionTargetIsRemote = adapterExecutionTargetIsRemote(executionTarget);const promptTemplate = asString(config.promptTemplate,@@ -315,6 +336,7 @@ export async function execute(ctx: AdapterExecutionContext): Promise<AdapterExecagent,config,context,+ executionTarget,authToken,});const {@@ -330,6 +352,7 @@ export async function execute(ctx: AdapterExecutionContext): Promise<AdapterExecgraceSec,extraArgs,} = runtimeConfig;+ const effectiveExecutionCwd = adapterExecutionTargetRemoteCwd(executionTarget, cwd);const terminalResultCleanupGraceMs = Math.max(0,asNumber(config.terminalResultCleanupGraceMs, 5_000),@@ -369,27 +392,74 @@ export async function execute(ctx: AdapterExecutionContext): Promise<AdapterExecinstructionsContents: combinedInstructionsContents,onLog,});- const effectiveInstructionsFilePath = promptBundle.instructionsFilePath ?? undefined;+ const preparedExecutionTargetRuntime = executionTargetIsRemote+ ? await (async () => {+ await onLog(+ "stdout",+ `[paperclip] Syncing workspace and Claude runtime assets to ${describeAdapterExecutionTarget(executionTarget)}.\n`,+ );+ return await prepareAdapterExecutionTargetRuntime({+ target: executionTarget,+ adapterKey: "claude",+ workspaceLocalDir: cwd,+ assets: [+ {+ key: "skills",+ localDir: promptBundle.addDir,+ followSymlinks: true,+ },+ ],+ });+ })()+ : null;+ const restoreRemoteWorkspace = preparedExecutionTargetRuntime+ ? () => preparedExecutionTargetRuntime.restoreWorkspace()+ : null;+ const effectivePromptBundleAddDir = executionTargetIsRemote+ ? preparedExecutionTargetRuntime?.assetDirs.skills ??+ path.posix.join(effectiveExecutionCwd, ".paperclip-runtime", "claude", "skills")+ : promptBundle.addDir;+ const effectiveInstructionsFilePath = promptBundle.instructionsFilePath+ ? executionTargetIsRemote+ ? path.posix.join(effectivePromptBundleAddDir, path.basename(promptBundle.instructionsFilePath))+ : promptBundle.instructionsFilePath+ : undefined;const runtimeSessionParams = parseObject(runtime.sessionParams);const runtimeSessionId = asString(runtimeSessionParams.sessionId, runtime.sessionId ?? "");const runtimeSessionCwd = asString(runtimeSessionParams.cwd, "");+ const runtimeRemoteExecution = parseObject(runtimeSessionParams.remoteExecution);const runtimePromptBundleKey = asString(runtimeSessionParams.promptBundleKey, "");const hasMatchingPromptBundle =runtimePromptBundleKey.length === 0 || runtimePromptBundleKey === promptBundle.bundleKey;const canResumeSession =runtimeSessionId.length > 0 &&hasMatchingPromptBundle &&- (runtimeSessionCwd.length === 0 || path.resolve(runtimeSessionCwd) === path.resolve(cwd));+ (runtimeSessionCwd.length === 0 || path.resolve(runtimeSessionCwd) === path.resolve(effectiveExecutionCwd)) &&+ adapterExecutionTargetSessionMatches(runtimeRemoteExecution, executionTarget);const sessionId = canResumeSession ? runtimeSessionId : null;if (+ executionTargetIsRemote &&+ runtimeSessionId &&+ !canResumeSession+ ) {+ await onLog(+ "stdout",+ `[paperclip] Claude 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 &&runtimeSessionCwd.length > 0 &&- path.resolve(runtimeSessionCwd) !== path.resolve(cwd)+ path.resolve(runtimeSessionCwd) !== path.resolve(effectiveExecutionCwd)) {await onLog("stdout",- `[paperclip] Claude session "${runtimeSessionId}" was saved for cwd "${runtimeSessionCwd}" and will not be resumed in "${cwd}".\n`,+ `[paperclip] Claude 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] Claude session "${runtimeSessionId}" was saved for cwd "${runtimeSessionCwd}" and will not be resumed in "${effectiveExecutionCwd}".\n`,);}if (runtimeSessionId && runtimePromptBundleKey.length > 0 && runtimePromptBundleKey !== promptBundle.bundleKey) {@@ -416,10 +486,12 @@ export async function execute(ctx: AdapterExecutionContext): Promise<AdapterExecconst shouldUseResumeDeltaPrompt = Boolean(sessionId) && wakePrompt.length > 0;const renderedPrompt = shouldUseResumeDeltaPrompt ? "" : renderTemplate(promptTemplate, templateData);const sessionHandoffNote = asString(context.paperclipSessionHandoffMarkdown, "").trim();+ const taskContextNote = asString(context.paperclipTaskMarkdown, "").trim();const prompt = joinPromptSections([renderedBootstrapPrompt,wakePrompt,sessionHandoffNote,+ taskContextNote,renderedPrompt,]);const promptMetrics = {@@ -427,6 +499,7 @@ export async function execute(ctx: AdapterExecutionContext): Promise<AdapterExecbootstrapPromptChars: renderedBootstrapPrompt.length,wakePromptChars: wakePrompt.length,sessionHandoffChars: sessionHandoffNote.length,+ taskContextChars: taskContextNote.length,heartbeatPromptChars: renderedPrompt.length,};@@ -452,7 +525,7 @@ export async function execute(ctx: AdapterExecutionContext): Promise<AdapterExecif (attemptInstructionsFilePath && !resumeSessionId) {args.push("--append-system-prompt-file", attemptInstructionsFilePath);}- args.push("--add-dir", promptBundle.addDir);+ args.push("--add-dir", effectivePromptBundleAddDir);if (extraArgs.length > 0) args.push(...extraArgs);return args;};@@ -489,7 +562,7 @@ export async function execute(ctx: AdapterExecutionContext): Promise<AdapterExecawait onMeta({adapterType: "claude_local",command: resolvedCommand,- cwd,+ cwd: effectiveExecutionCwd,commandArgs: args,commandNotes,env: loggedEnv,@@ -499,7 +572,7 @@ export async function execute(ctx: AdapterExecutionContext): Promise<AdapterExec});}- const proc = await runChildProcess(runId, command, args, {+ const proc = await runAdapterExecutionTargetProcess(runId, executionTarget, command, args, {cwd,env,stdin: prompt,@@ -584,8 +657,13 @@ export async function execute(ctx: AdapterExecutionContext): Promise<AdapterExecconst resolvedSessionParams = resolvedSessionId? ({sessionId: resolvedSessionId,- cwd,+ cwd: effectiveExecutionCwd,promptBundleKey: promptBundle.bundleKey,+ ...(executionTargetIsRemote+ ? {+ remoteExecution: adapterExecutionTargetSessionIdentity(executionTarget),+ }+ : {}),...(workspaceId ? { workspaceId } : {}),...(workspaceRepoUrl ? { repoUrl: workspaceRepoUrl } : {}),...(workspaceRepoRef ? { repoRef: workspaceRepoRef } : {}),@@ -618,21 +696,31 @@ export async function execute(ctx: AdapterExecutionContext): Promise<AdapterExec};};- const initial = await runAttempt(sessionId ?? null);- if (- sessionId &&- !initial.proc.timedOut &&- (initial.proc.exitCode ?? 0) !== 0 &&- initial.parsed &&- isClaudeUnknownSessionError(initial.parsed)- ) {- await onLog(- "stdout",- `[paperclip] Claude resume session "${sessionId}" is unavailable; retrying with a fresh session.\n`,- );- const retry = await runAttempt(null);- return toAdapterResult(retry, { fallbackSessionId: null, clearSessionOnMissingSession: true });- }+ try {+ const initial = await runAttempt(sessionId ?? null);+ if (+ sessionId &&+ !initial.proc.timedOut &&+ (initial.proc.exitCode ?? 0) !== 0 &&+ initial.parsed &&+ isClaudeUnknownSessionError(initial.parsed)+ ) {+ await onLog(+ "stdout",+ `[paperclip] Claude resume session "${sessionId}" is unavailable; retrying with a fresh session.\n`,+ );+ const retry = await runAttempt(null);+ return toAdapterResult(retry, { fallbackSessionId: null, clearSessionOnMissingSession: true });+ }- return toAdapterResult(initial, { fallbackSessionId: runtimeSessionId || runtime.sessionId });+ return toAdapterResult(initial, { fallbackSessionId: runtimeSessionId || runtime.sessionId });+ } finally {+ if (restoreRemoteWorkspace) {+ await onLog(+ "stdout",+ `[paperclip] Restoring workspace changes from ${describeAdapterExecutionTarget(executionTarget)}.\n`,+ );+ await restoreRemoteWorkspace();+ }+ }}diff --git a/packages/adapters/claude-local/vitest.config.ts b/packages/adapters/claude-local/vitest.config.tsnew file mode 100644index 0000000000..f624398e8d--- /dev/null+++ b/packages/adapters/claude-local/vitest.config.ts@@ -0,0 +1,7 @@+import { defineConfig } from "vitest/config";++export default defineConfig({+ test: {+ environment: "node",+ },+});diff --git a/packages/adapters/codex-local/src/server/execute.remote.test.ts b/packages/adapters/codex-local/src/server/execute.remote.test.tsnew file mode 100644index 0000000000..8e22f7b3db--- /dev/null+++ b/packages/adapters/codex-local/src/server/execute.remote.test.ts@@ -0,0 +1,359 @@+import { mkdir, mkdtemp, rm, writeFile } from "node:fs/promises";+import os from "node:os";+import path from "node:path";+import { afterEach, describe, expect, it, vi } from "vitest";++const {+ runChildProcess,+ ensureCommandResolvable,+ resolveCommandForLogs,+ prepareWorkspaceForSshExecution,+ restoreWorkspaceFromSshExecution,+ syncDirectoryToSsh,+} = vi.hoisted(() => ({+ runChildProcess: vi.fn(async () => ({+ exitCode: 1,+ signal: null,+ timedOut: false,+ stdout: "",+ stderr: "remote failure",+ pid: 123,+ startedAt: new Date().toISOString(),+ })),+ ensureCommandResolvable: vi.fn(async () => undefined),+ resolveCommandForLogs: vi.fn(async () => "/usr/bin/codex"),+ prepareWorkspaceForSshExecution: vi.fn(async () => undefined),+ restoreWorkspaceFromSshExecution: vi.fn(async () => undefined),+ syncDirectoryToSsh: vi.fn(async () => undefined),+}));++vi.mock("@paperclipai/adapter-utils/server-utils", async () => {+ const actual = await vi.importActual<typeof import("@paperclipai/adapter-utils/server-utils")>(+ "@paperclipai/adapter-utils/server-utils",+ );+ return {+ ...actual,+ ensureCommandResolvable,+ resolveCommandForLogs,+ runChildProcess,+ };+});++vi.mock("@paperclipai/adapter-utils/ssh", async () => {+ const actual = await vi.importActual<typeof import("@paperclipai/adapter-utils/ssh")>(+ "@paperclipai/adapter-utils/ssh",+ );+ return {+ ...actual,+ prepareWorkspaceForSshExecution,+ restoreWorkspaceFromSshExecution,+ syncDirectoryToSsh,+ };+});++import { execute } from "./execute.js";++describe("codex remote execution", () => {+ const cleanupDirs: string[] = [];++ afterEach(async () => {+ vi.clearAllMocks();+ while (cleanupDirs.length > 0) {+ const dir = cleanupDirs.pop();+ if (!dir) continue;+ await rm(dir, { recursive: true, force: true }).catch(() => undefined);+ }+ });++ it("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);+ const workspaceDir = path.join(rootDir, "workspace");+ const codexHomeDir = path.join(rootDir, "codex-home");+ await mkdir(workspaceDir, { recursive: true });+ await mkdir(codexHomeDir, { recursive: true });+ await writeFile(path.join(rootDir, "instructions.md"), "Use the remote workspace.\n", "utf8");+ await writeFile(path.join(codexHomeDir, "auth.json"), "{}", "utf8");++ await execute({+ runId: "run-1",+ agent: {+ id: "agent-1",+ companyId: "company-1",+ name: "CodexCoder",+ adapterType: "codex_local",+ adapterConfig: {},+ },+ runtime: {+ sessionId: null,+ sessionParams: null,+ sessionDisplayId: null,+ taskKey: null,+ },+ config: {+ command: "codex",+ env: {+ CODEX_HOME: codexHomeDir,+ },+ },+ context: {+ paperclipWorkspace: {+ cwd: workspaceDir,+ source: "project_primary",+ },+ },+ executionTransport: {+ remoteExecution: {+ host: "127.0.0.1",+ port: 2222,+ username: "fixture",+ remoteWorkspacePath: "/remote/workspace",+ remoteCwd: "/remote/workspace",+ privateKey: "PRIVATE KEY",+ knownHosts: "[127.0.0.1]:2222 ssh-ed25519 AAAA",+ strictHostKeyChecking: true,+ },+ },+ onLog: async () => {},+ });++ expect(prepareWorkspaceForSshExecution).toHaveBeenCalledTimes(1);+ expect(prepareWorkspaceForSshExecution).toHaveBeenCalledWith(expect.objectContaining({+ localDir: workspaceDir,+ remoteDir: "/remote/workspace",+ }));+ expect(syncDirectoryToSsh).toHaveBeenCalledTimes(1);+ expect(syncDirectoryToSsh).toHaveBeenCalledWith(expect.objectContaining({+ localDir: codexHomeDir,+ remoteDir: "/remote/workspace/.paperclip-runtime/codex/home",+ followSymlinks: true,+ }));++ expect(runChildProcess).toHaveBeenCalledTimes(1);+ const call = runChildProcess.mock.calls[0] as unknown as+ | [string, string, string[], { env: Record<string, string>; remoteExecution?: { remoteCwd: string } | null }]+ | undefined;+ expect(call?.[3].env.CODEX_HOME).toBe("/remote/workspace/.paperclip-runtime/codex/home");+ expect(call?.[3].remoteExecution?.remoteCwd).toBe("/remote/workspace");+ expect(restoreWorkspaceFromSshExecution).toHaveBeenCalledTimes(1);+ expect(restoreWorkspaceFromSshExecution).toHaveBeenCalledWith(expect.objectContaining({+ localDir: workspaceDir,+ remoteDir: "/remote/workspace",+ }));+ });++ it("does not resume saved Codex sessions for remote SSH execution without a matching remote identity", async () => {+ const rootDir = await mkdtemp(path.join(os.tmpdir(), "paperclip-codex-remote-resume-"));+ cleanupDirs.push(rootDir);+ const workspaceDir = path.join(rootDir, "workspace");+ const codexHomeDir = path.join(rootDir, "codex-home");+ await mkdir(workspaceDir, { recursive: true });+ await mkdir(codexHomeDir, { recursive: true });+ await writeFile(path.join(codexHomeDir, "auth.json"), "{}", "utf8");++ await execute({+ runId: "run-ssh-no-resume",+ agent: {+ id: "agent-1",+ companyId: "company-1",+ name: "CodexCoder",+ adapterType: "codex_local",+ adapterConfig: {},+ },+ runtime: {+ sessionId: "session-123",+ sessionParams: {+ sessionId: "session-123",+ cwd: "/remote/workspace",+ },+ sessionDisplayId: "session-123",+ taskKey: null,+ },+ config: {+ command: "codex",+ env: {+ CODEX_HOME: codexHomeDir,+ },+ },+ context: {+ paperclipWorkspace: {+ cwd: workspaceDir,+ source: "project_primary",+ },+ },+ executionTransport: {+ remoteExecution: {+ host: "127.0.0.1",+ port: 2222,+ username: "fixture",+ remoteWorkspacePath: "/remote/workspace",+ remoteCwd: "/remote/workspace",+ privateKey: "PRIVATE KEY",+ knownHosts: "[127.0.0.1]:2222 ssh-ed25519 AAAA",+ strictHostKeyChecking: true,+ },+ },+ onLog: async () => {},+ });++ expect(runChildProcess).toHaveBeenCalledTimes(1);+ const call = runChildProcess.mock.calls[0] as unknown as [string, string, string[]] | undefined;+ expect(call?.[2]).toEqual([+ "exec",+ "--json",+ "-",+ ]);+ });++ it("resumes saved Codex sessions for remote SSH execution when the remote identity matches", async () => {+ const rootDir = await mkdtemp(path.join(os.tmpdir(), "paperclip-codex-remote-resume-match-"));+ cleanupDirs.push(rootDir);+ const workspaceDir = path.join(rootDir, "workspace");+ const codexHomeDir = path.join(rootDir, "codex-home");+ await mkdir(workspaceDir, { recursive: true });+ await mkdir(codexHomeDir, { recursive: true });+ await writeFile(path.join(codexHomeDir, "auth.json"), "{}", "utf8");++ await execute({+ runId: "run-ssh-resume",+ agent: {+ id: "agent-1",+ companyId: "company-1",+ name: "CodexCoder",+ adapterType: "codex_local",+ adapterConfig: {},+ },+ runtime: {+ sessionId: "session-123",+ sessionParams: {+ sessionId: "session-123",+ cwd: "/remote/workspace",+ remoteExecution: {+ transport: "ssh",+ host: "127.0.0.1",+ port: 2222,+ username: "fixture",+ remoteCwd: "/remote/workspace",+ },+ },+ sessionDisplayId: "session-123",+ taskKey: null,+ },+ config: {+ command: "codex",+ env: {+ CODEX_HOME: codexHomeDir,+ },+ },+ context: {+ paperclipWorkspace: {+ cwd: workspaceDir,+ source: "project_primary",+ },+ },+ executionTransport: {+ remoteExecution: {+ host: "127.0.0.1",+ port: 2222,+ username: "fixture",+ remoteWorkspacePath: "/remote/workspace",+ remoteCwd: "/remote/workspace",+ privateKey: "PRIVATE KEY",+ knownHosts: "[127.0.0.1]:2222 ssh-ed25519 AAAA",+ strictHostKeyChecking: true,+ },+ },+ onLog: async () => {},+ });++ expect(runChildProcess).toHaveBeenCalledTimes(1);+ const call = runChildProcess.mock.calls[0] as unknown as [string, string, string[]] | undefined;+ expect(call?.[2]).toEqual([+ "exec",+ "--json",+ "resume",+ "session-123",+ "-",+ ]);+ });++ it("uses the provider-neutral execution target contract for remote SSH execution", async () => {+ const rootDir = await mkdtemp(path.join(os.tmpdir(), "paperclip-codex-target-"));+ cleanupDirs.push(rootDir);+ const workspaceDir = path.join(rootDir, "workspace");+ const codexHomeDir = path.join(rootDir, "codex-home");+ await mkdir(workspaceDir, { recursive: true });+ await mkdir(codexHomeDir, { recursive: true });+ await writeFile(path.join(codexHomeDir, "auth.json"), "{}", "utf8");++ await execute({+ runId: "run-target",+ agent: {+ id: "agent-1",+ companyId: "company-1",+ name: "CodexCoder",+ adapterType: "codex_local",+ adapterConfig: {},+ },+ runtime: {+ sessionId: "session-123",+ sessionParams: {+ sessionId: "session-123",+ cwd: "/remote/workspace",+ remoteExecution: {+ transport: "ssh",+ host: "127.0.0.1",+ port: 2222,+ username: "fixture",+ remoteCwd: "/remote/workspace",+ },+ },+ sessionDisplayId: "session-123",+ taskKey: null,+ },+ config: {+ command: "codex",+ env: {+ CODEX_HOME: codexHomeDir,+ },+ },+ context: {+ paperclipWorkspace: {+ cwd: workspaceDir,+ source: "project_primary",+ },+ },+ executionTarget: {+ kind: "remote",+ transport: "ssh",+ remoteCwd: "/remote/workspace",+ spec: {+ host: "127.0.0.1",+ port: 2222,+ username: "fixture",+ remoteWorkspacePath: "/remote/workspace",+ remoteCwd: "/remote/workspace",+ privateKey: "PRIVATE KEY",+ knownHosts: "[127.0.0.1]:2222 ssh-ed25519 AAAA",+ strictHostKeyChecking: true,+ },+ },+ onLog: async () => {},+ });++ expect(syncDirectoryToSsh).toHaveBeenCalledTimes(1);+ expect(runChildProcess).toHaveBeenCalledTimes(1);+ const call = runChildProcess.mock.calls[0] as unknown as+ | [string, string, string[], { env: Record<string, string>; remoteExecution?: { remoteCwd: string } | null }]+ | undefined;+ expect(call?.[2]).toEqual([+ "exec",+ "--json",+ "resume",+ "session-123",+ "-",+ ]);+ expect(call?.[3].env.CODEX_HOME).toBe("/remote/workspace/.paperclip-runtime/codex/home");+ expect(call?.[3].remoteExecution?.remoteCwd).toBe("/remote/workspace");+ });+});diff --git a/packages/adapters/codex-local/src/server/execute.ts b/packages/adapters/codex-local/src/server/execute.tsindex 95a0d70cd5..87d14a7249 100644--- a/packages/adapters/codex-local/src/server/execute.ts+++ b/packages/adapters/codex-local/src/server/execute.ts@@ -2,6 +2,19 @@ import fs from "node:fs/promises";import path from "node:path";import { fileURLToPath } from "node:url";import { inferOpenAiCompatibleBiller, type AdapterExecutionContext, type AdapterExecutionResult } from "@paperclipai/adapter-utils";+import {+ adapterExecutionTargetIsRemote,+ adapterExecutionTargetPaperclipApiUrl,+ adapterExecutionTargetRemoteCwd,+ adapterExecutionTargetSessionIdentity,+ adapterExecutionTargetSessionMatches,+ describeAdapterExecutionTarget,+ ensureAdapterExecutionTargetCommandResolvable,+ prepareAdapterExecutionTargetRuntime,+ readAdapterExecutionTarget,+ resolveAdapterExecutionTargetCommandForLogs,+ runAdapterExecutionTargetProcess,+} from "@paperclipai/adapter-utils/execution-target";import {asString,asNumber,@@ -9,18 +22,15 @@ import {buildPaperclipEnv,buildInvocationEnvForLogs,ensureAbsoluteDirectory,- ensureCommandResolvable,ensurePaperclipSkillSymlink,ensurePathInEnv,readPaperclipRuntimeSkillEntries,- resolveCommandForLogs,resolvePaperclipDesiredSkillNames,renderTemplate,renderPaperclipWakePrompt,stringifyPaperclipWakePayload,DEFAULT_PAPERCLIP_AGENT_PROMPT_TEMPLATE,joinPromptSections,- runChildProcess,} from "@paperclipai/adapter-utils/server-utils";import {parseCodexJsonl,@@ -305,6 +315,11 @@ export async function execute(ctx: AdapterExecutionContext): Promise<AdapterExecconst effectiveWorkspaceCwd = useConfiguredInsteadOfAgentHome ? "" : workspaceCwd;const cwd = effectiveWorkspaceCwd || configuredCwd || process.cwd();const envConfig = parseObject(config.env);+ const executionTarget = readAdapterExecutionTarget({+ executionTarget: ctx.executionTarget,+ legacyRemoteExecution: ctx.executionTransport?.remoteExecution,+ });+ const executionTargetIsRemote = adapterExecutionTargetIsRemote(executionTarget);const configuredCodexHome =typeof envConfig.CODEX_HOME === "string" && envConfig.CODEX_HOME.trim().length > 0? path.resolve(envConfig.CODEX_HOME.trim())@@ -328,10 +343,37 @@ export async function execute(ctx: AdapterExecutionContext): Promise<AdapterExecdesiredSkillNames,},);+ const effectiveExecutionCwd = adapterExecutionTargetRemoteCwd(executionTarget, cwd);+ const preparedExecutionTargetRuntime = executionTargetIsRemote+ ? await (async () => {+ await onLog(+ "stdout",+ `[paperclip] Syncing workspace and CODEX_HOME to ${describeAdapterExecutionTarget(executionTarget)}.\n`,+ );+ return await prepareAdapterExecutionTargetRuntime({+ target: executionTarget,+ adapterKey: "codex",+ workspaceLocalDir: cwd,+ assets: [+ {+ key: "home",+ localDir: effectiveCodexHome,+ followSymlinks: true,+ },+ ],+ });+ })()+ : null;+ const restoreRemoteWorkspace = preparedExecutionTargetRuntime+ ? () => preparedExecutionTargetRuntime.restoreWorkspace()+ : null;+ const remoteCodexHome = executionTargetIsRemote+ ? preparedExecutionTargetRuntime?.assetDirs.home ??+ path.posix.join(effectiveExecutionCwd, ".paperclip-runtime", "codex", "home")+ : null;const hasExplicitApiKey =typeof envConfig.PAPERCLIP_API_KEY === "string" && envConfig.PAPERCLIP_API_KEY.trim().length > 0;const env: Record<string, string> = { ...buildPaperclipEnv(agent) };- env.CODEX_HOME = effectiveCodexHome;env.PAPERCLIP_RUN_ID = runId;const wakeTaskId =(typeof context.taskId === "string" && context.taskId.trim().length > 0 && context.taskId.trim()) ||@@ -417,9 +459,14 @@ export async function execute(ctx: AdapterExecutionContext): Promise<AdapterExecif (runtimePrimaryUrl) {env.PAPERCLIP_RUNTIME_PRIMARY_URL = runtimePrimaryUrl;}+ const targetPaperclipApiUrl = adapterExecutionTargetPaperclipApiUrl(executionTarget);+ if (targetPaperclipApiUrl) {+ env.PAPERCLIP_API_URL = targetPaperclipApiUrl;+ }for (const [k, v] of Object.entries(envConfig)) {if (typeof v === "string") env[k] = v;}+ env.CODEX_HOME = remoteCodexHome ?? effectiveCodexHome;if (!hasExplicitApiKey && authToken) {env.PAPERCLIP_API_KEY = authToken;}@@ -430,8 +477,8 @@ export async function execute(ctx: AdapterExecutionContext): Promise<AdapterExec);const billingType = resolveCodexBillingType(effectiveEnv);const runtimeEnv = ensurePathInEnv(effectiveEnv);- await ensureCommandResolvable(command, cwd, runtimeEnv);- const resolvedCommand = await resolveCommandForLogs(command, cwd, runtimeEnv);+ await ensureAdapterExecutionTargetCommandResolvable(command, executionTarget, cwd, runtimeEnv);+ const resolvedCommand = await resolveAdapterExecutionTargetCommandForLogs(command, executionTarget, cwd, runtimeEnv);const loggedEnv = buildInvocationEnvForLogs(env, {runtimeEnv,includeRuntimeKeys: ["HOME"],@@ -444,17 +491,24 @@ export async function execute(ctx: AdapterExecutionContext): Promise<AdapterExecconst 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(cwd));+ (runtimeSessionCwd.length === 0 || path.resolve(runtimeSessionCwd) === path.resolve(effectiveExecutionCwd)) &&+ adapterExecutionTargetSessionMatches(runtimeRemoteExecution, executionTarget);const codexTransientFallbackMode = readCodexTransientFallbackMode(context);const forceSaferInvocation = fallbackModeUsesSaferInvocation(codexTransientFallbackMode);const forceFreshSession = fallbackModeUsesFreshSession(codexTransientFallbackMode);const sessionId = canResumeSession && !forceFreshSession ? runtimeSessionId : null;- if (runtimeSessionId && !canResumeSession) {+ if (executionTargetIsRemote && runtimeSessionId && !canResumeSession) {+ await onLog(+ "stdout",+ `[paperclip] Codex 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] Codex session "${runtimeSessionId}" was saved for cwd "${runtimeSessionCwd}" and will not be resumed in "${cwd}".\n`,+ `[paperclip] Codex session "${runtimeSessionId}" was saved for cwd "${runtimeSessionCwd}" and will not be resumed in "${effectiveExecutionCwd}".\n`,);}const instructionsFilePath = asString(config.instructionsFilePath, "").trim();@@ -591,7 +645,7 @@ export async function execute(ctx: AdapterExecutionContext): Promise<AdapterExecawait onMeta({adapterType: "codex_local",command: resolvedCommand,- cwd,+ cwd: effectiveExecutionCwd,commandNotes: commandNotesWithFastMode,commandArgs: args.map((value, idx) => {if (idx === args.length - 1 && value !== "-") return `<prompt ${prompt.length} chars>`;@@ -604,7 +658,7 @@ export async function execute(ctx: AdapterExecutionContext): Promise<AdapterExec});}- const proc = await runChildProcess(runId, command, args, {+ const proc = await runAdapterExecutionTargetProcess(runId, executionTarget, command, args, {cwd,env,stdin: prompt,@@ -654,7 +708,12 @@ export async function execute(ctx: AdapterExecutionContext): Promise<AdapterExecconst resolvedSessionParams = resolvedSessionId? ({sessionId: resolvedSessionId,- cwd,+ cwd: effectiveExecutionCwd,+ ...(executionTargetIsRemote+ ? {+ remoteExecution: adapterExecutionTargetSessionIdentity(executionTarget),+ }+ : {}),...(workspaceId ? { workspaceId } : {}),...(workspaceRepoUrl ? { repoUrl: workspaceRepoUrl } : {}),...(workspaceRepoRef ? { repoRef: workspaceRepoRef } : {}),@@ -702,20 +761,30 @@ export async function execute(ctx: AdapterExecutionContext): Promise<AdapterExec};};- const initial = await runAttempt(sessionId);- if (- sessionId &&- !initial.proc.timedOut &&- (initial.proc.exitCode ?? 0) !== 0 &&- isCodexUnknownSessionError(initial.proc.stdout, initial.rawStderr)- ) {- await onLog(- "stdout",- `[paperclip] Codex resume session "${sessionId}" is unavailable; retrying with a fresh session.\n`,- );- const retry = await runAttempt(null);- return toResult(retry, true, true);- }+ try {+ const initial = await runAttempt(sessionId);+ if (+ sessionId &&+ !initial.proc.timedOut &&+ (initial.proc.exitCode ?? 0) !== 0 &&+ isCodexUnknownSessionError(initial.proc.stdout, initial.rawStderr)+ ) {+ await onLog(+ "stdout",+ `[paperclip] Codex resume session "${sessionId}" is unavailable; retrying with a fresh session.\n`,+ );+ const retry = await runAttempt(null);+ return toResult(retry, true, true);+ }- return toResult(initial, false, false);+ return toResult(initial, false, false);+ } finally {+ if (restoreRemoteWorkspace) {+ await onLog(+ "stdout",+ `[paperclip] Restoring workspace changes from ${describeAdapterExecutionTarget(executionTarget)}.\n`,+ );+ await restoreRemoteWorkspace();+ }+ }}diff --git a/packages/adapters/cursor-local/src/server/execute.remote.test.ts b/packages/adapters/cursor-local/src/server/execute.remote.test.tsnew file mode 100644index 0000000000..e0e6d09f61--- /dev/null+++ b/packages/adapters/cursor-local/src/server/execute.remote.test.ts@@ -0,0 +1,268 @@+import { mkdir, mkdtemp, rm } from "node:fs/promises";+import os from "node:os";+import path from "node:path";+import { afterEach, describe, expect, it, vi } from "vitest";++const {+ runChildProcess,+ ensureCommandResolvable,+ resolveCommandForLogs,+ prepareWorkspaceForSshExecution,+ restoreWorkspaceFromSshExecution,+ runSshCommand,+ syncDirectoryToSsh,+} = vi.hoisted(() => ({+ runChildProcess: vi.fn(async () => ({+ exitCode: 0,+ signal: null,+ timedOut: false,+ stdout: [+ JSON.stringify({ type: "system", session_id: "cursor-session-1" }),+ JSON.stringify({ type: "assistant", text: "hello" }),+ JSON.stringify({ type: "result", is_error: false, result: "hello", session_id: "cursor-session-1" }),+ ].join("\n"),+ stderr: "",+ pid: 123,+ startedAt: new Date().toISOString(),+ })),+ ensureCommandResolvable: vi.fn(async () => undefined),+ resolveCommandForLogs: vi.fn(async () => "ssh://[email protected]:2222/remote/workspace :: agent"),+ prepareWorkspaceForSshExecution: vi.fn(async () => undefined),+ restoreWorkspaceFromSshExecution: vi.fn(async () => undefined),+ runSshCommand: vi.fn(async () => ({+ stdout: "/home/agent",+ stderr: "",+ exitCode: 0,+ })),+ syncDirectoryToSsh: vi.fn(async () => undefined),+}));++vi.mock("@paperclipai/adapter-utils/server-utils", async () => {+ const actual = await vi.importActual<typeof import("@paperclipai/adapter-utils/server-utils")>(+ "@paperclipai/adapter-utils/server-utils",+ );+ return {+ ...actual,+ ensureCommandResolvable,+ resolveCommandForLogs,+ runChildProcess,+ };+});++vi.mock("@paperclipai/adapter-utils/ssh", async () => {+ const actual = await vi.importActual<typeof import("@paperclipai/adapter-utils/ssh")>(+ "@paperclipai/adapter-utils/ssh",+ );+ return {+ ...actual,+ prepareWorkspaceForSshExecution,+ restoreWorkspaceFromSshExecution,+ runSshCommand,+ syncDirectoryToSsh,+ };+});++import { execute } from "./execute.js";++describe("cursor remote execution", () => {+ const cleanupDirs: string[] = [];++ afterEach(async () => {+ vi.clearAllMocks();+ while (cleanupDirs.length > 0) {+ const dir = cleanupDirs.pop();+ if (!dir) continue;+ await rm(dir, { recursive: true, force: true }).catch(() => undefined);+ }+ });++ it("prepares the workspace, syncs Cursor skills, and restores workspace changes for remote SSH execution", async () => {+ const rootDir = await mkdtemp(path.join(os.tmpdir(), "paperclip-cursor-remote-"));+ cleanupDirs.push(rootDir);+ const workspaceDir = path.join(rootDir, "workspace");+ await mkdir(workspaceDir, { recursive: true });++ const result = await execute({+ runId: "run-1",+ agent: {+ id: "agent-1",+ companyId: "company-1",+ name: "Cursor Builder",+ adapterType: "cursor",+ adapterConfig: {},+ },+ runtime: {+ sessionId: null,+ sessionParams: null,+ sessionDisplayId: null,+ taskKey: null,+ },+ config: {+ command: "agent",+ },+ context: {+ paperclipWorkspace: {+ cwd: workspaceDir,+ source: "project_primary",+ },+ },+ executionTransport: {+ remoteExecution: {+ host: "127.0.0.1",+ port: 2222,+ username: "fixture",+ remoteWorkspacePath: "/remote/workspace",+ remoteCwd: "/remote/workspace",+ privateKey: "PRIVATE KEY",+ knownHosts: "[127.0.0.1]:2222 ssh-ed25519 AAAA",+ strictHostKeyChecking: true,+ paperclipApiUrl: "http://198.51.100.10:3102",+ },+ },+ onLog: async () => {},+ });++ expect(result.sessionParams).toMatchObject({+ sessionId: "cursor-session-1",+ cwd: "/remote/workspace",+ remoteExecution: {+ transport: "ssh",+ host: "127.0.0.1",+ port: 2222,+ username: "fixture",+ remoteCwd: "/remote/workspace",+ paperclipApiUrl: "http://198.51.100.10:3102",+ },+ });+ expect(prepareWorkspaceForSshExecution).toHaveBeenCalledTimes(1);+ expect(syncDirectoryToSsh).toHaveBeenCalledTimes(1);+ expect(syncDirectoryToSsh).toHaveBeenCalledWith(expect.objectContaining({+ remoteDir: "/remote/workspace/.paperclip-runtime/cursor/skills",+ followSymlinks: true,+ }));+ expect(runSshCommand).toHaveBeenCalledWith(+ expect.anything(),+ expect.stringContaining(".cursor/skills"),+ expect.anything(),+ );+ const call = runChildProcess.mock.calls[0] as unknown as+ | [string, string, string[], { env: Record<string, string>; remoteExecution?: { remoteCwd: string } | null }]+ | undefined;+ expect(call?.[2]).toContain("--workspace");+ expect(call?.[2]).toContain("/remote/workspace");+ expect(call?.[3].env.PAPERCLIP_API_URL).toBe("http://198.51.100.10:3102");+ expect(call?.[3].remoteExecution?.remoteCwd).toBe("/remote/workspace");+ expect(restoreWorkspaceFromSshExecution).toHaveBeenCalledTimes(1);+ });++ it("resumes saved Cursor sessions for remote SSH execution only when the identity matches", async () => {+ const rootDir = await mkdtemp(path.join(os.tmpdir(), "paperclip-cursor-remote-resume-"));+ cleanupDirs.push(rootDir);+ const workspaceDir = path.join(rootDir, "workspace");+ await mkdir(workspaceDir, { recursive: true });++ await execute({+ runId: "run-ssh-resume",+ agent: {+ id: "agent-1",+ companyId: "company-1",+ name: "Cursor Builder",+ adapterType: "cursor",+ adapterConfig: {},+ },+ runtime: {+ sessionId: "session-123",+ sessionParams: {+ sessionId: "session-123",+ cwd: "/remote/workspace",+ remoteExecution: {+ transport: "ssh",+ host: "127.0.0.1",+ port: 2222,+ username: "fixture",+ remoteCwd: "/remote/workspace",+ },+ },+ sessionDisplayId: "session-123",+ taskKey: null,+ },+ config: {+ command: "agent",+ },+ context: {+ paperclipWorkspace: {+ cwd: workspaceDir,+ source: "project_primary",+ },+ },+ executionTransport: {+ remoteExecution: {+ host: "127.0.0.1",+ port: 2222,+ username: "fixture",+ remoteWorkspacePath: "/remote/workspace",+ remoteCwd: "/remote/workspace",+ privateKey: "PRIVATE KEY",+ knownHosts: "[127.0.0.1]:2222 ssh-ed25519 AAAA",+ strictHostKeyChecking: true,+ },+ },+ onLog: async () => {},+ });++ const call = runChildProcess.mock.calls[0] as unknown as [string, string, string[]] | undefined;+ expect(call?.[2]).toContain("--resume");+ expect(call?.[2]).toContain("session-123");+ });++ it("restores the remote workspace if skills sync fails after workspace prep", async () => {+ const rootDir = await mkdtemp(path.join(os.tmpdir(), "paperclip-cursor-remote-sync-fail-"));+ cleanupDirs.push(rootDir);+ const workspaceDir = path.join(rootDir, "workspace");+ await mkdir(workspaceDir, { recursive: true });+ syncDirectoryToSsh.mockRejectedValueOnce(new Error("sync failed"));++ await expect(execute({+ runId: "run-sync-fail",+ agent: {+ id: "agent-1",+ companyId: "company-1",+ name: "Cursor Builder",+ adapterType: "cursor",+ adapterConfig: {},+ },+ runtime: {+ sessionId: null,+ sessionParams: null,+ sessionDisplayId: null,+ taskKey: null,+ },+ config: {+ command: "agent",+ },+ context: {+ paperclipWorkspace: {+ cwd: workspaceDir,+ source: "project_primary",+ },+ },+ executionTransport: {+ remoteExecution: {+ host: "127.0.0.1",+ port: 2222,+ username: "fixture",+ remoteWorkspacePath: "/remote/workspace",+ remoteCwd: "/remote/workspace",+ privateKey: "PRIVATE KEY",+ knownHosts: "[127.0.0.1]:2222 ssh-ed25519 AAAA",+ strictHostKeyChecking: true,+ },+ },+ onLog: async () => {},+ })).rejects.toThrow("sync failed");++ expect(prepareWorkspaceForSshExecution).toHaveBeenCalledTimes(1);+ expect(restoreWorkspaceFromSshExecution).toHaveBeenCalledTimes(1);+ expect(runChildProcess).not.toHaveBeenCalled();+ });+});diff --git a/packages/adapters/cursor-local/src/server/execute.ts b/packages/adapters/cursor-local/src/server/execute.tsindex 7c457e02f2..6d7f79662d 100644--- a/packages/adapters/cursor-local/src/server/execute.ts+++ b/packages/adapters/cursor-local/src/server/execute.ts@@ -3,6 +3,22 @@ import os from "node:os";import path from "node:path";import { fileURLToPath } from "node:url";import { inferOpenAiCompatibleBiller, type AdapterExecutionContext, type AdapterExecutionResult } from "@paperclipai/adapter-utils";+import {+ adapterExecutionTargetIsRemote,+ adapterExecutionTargetPaperclipApiUrl,+ adapterExecutionTargetRemoteCwd,+ adapterExecutionTargetSessionIdentity,+ adapterExecutionTargetSessionMatches,+ adapterExecutionTargetUsesManagedHome,+ describeAdapterExecutionTarget,+ ensureAdapterExecutionTargetCommandResolvable,+ prepareAdapterExecutionTargetRuntime,+ readAdapterExecutionTarget,+ readAdapterExecutionTargetHomeDir,+ resolveAdapterExecutionTargetCommandForLogs,+ runAdapterExecutionTargetProcess,+ runAdapterExecutionTargetShellCommand,+} from "@paperclipai/adapter-utils/execution-target";import {asString,asNumber,@@ -11,11 +27,9 @@ import {buildPaperclipEnv,buildInvocationEnvForLogs,ensureAbsoluteDirectory,- ensureCommandResolvable,ensurePaperclipSkillSymlink,ensurePathInEnv,readPaperclipRuntimeSkillEntries,- resolveCommandForLogs,resolvePaperclipDesiredSkillNames,removeMaintainerOnlySkillSymlinks,renderTemplate,@@ -23,7 +37,6 @@ import {stringifyPaperclipWakePayload,DEFAULT_PAPERCLIP_AGENT_PROMPT_TEMPLATE,joinPromptSections,- runChildProcess,} from "@paperclipai/adapter-utils/server-utils";import { DEFAULT_CURSOR_LOCAL_MODEL } from "../index.js";import { parseCursorJsonl, isCursorUnknownSessionError } from "./parse.js";@@ -97,6 +110,19 @@ function cursorSkillsHome(): string {return path.join(os.homedir(), ".cursor", "skills");}+async function buildCursorSkillsDir(config: Record<string, unknown>): Promise<string> {+ const tmp = await fs.mkdtemp(path.join(os.tmpdir(), "paperclip-cursor-skills-"));+ const target = path.join(tmp, "skills");+ await fs.mkdir(target, { recursive: true });+ const availableEntries = await readPaperclipRuntimeSkillEntries(config, __moduleDir);+ const desiredNames = new Set(resolvePaperclipDesiredSkillNames(config, availableEntries));+ for (const entry of availableEntries) {+ if (!desiredNames.has(entry.key)) continue;+ await fs.symlink(entry.source, path.join(target, entry.runtimeName));+ }+ return target;+}+type EnsureCursorSkillsInjectedOptions = {skillsDir?: string | null;skillsEntries?: Array<{ key: string; runtimeName: string; source: string }>;@@ -162,6 +188,11 @@ export async function ensureCursorSkillsInjected(export async function execute(ctx: AdapterExecutionContext): Promise<AdapterExecutionResult> {const { runId, agent, runtime, config, context, onLog, onMeta, onSpawn, authToken } = ctx;+ const executionTarget = readAdapterExecutionTarget({+ executionTarget: ctx.executionTarget,+ legacyRemoteExecution: ctx.executionTransport?.remoteExecution,+ });+ const executionTargetIsRemote = adapterExecutionTargetIsRemote(executionTarget);const promptTemplate = asString(config.promptTemplate,@@ -190,9 +221,11 @@ export async function execute(ctx: AdapterExecutionContext): Promise<AdapterExecawait ensureAbsoluteDirectory(cwd, { createIfMissing: true });const cursorSkillEntries = await readPaperclipRuntimeSkillEntries(config, __moduleDir);const desiredCursorSkillNames = resolvePaperclipDesiredSkillNames(config, cursorSkillEntries);- await ensureCursorSkillsInjected(onLog, {- skillsEntries: cursorSkillEntries.filter((entry) => desiredCursorSkillNames.includes(entry.key)),- });+ if (!executionTargetIsRemote) {+ await ensureCursorSkillsInjected(onLog, {+ skillsEntries: cursorSkillEntries.filter((entry) => desiredCursorSkillNames.includes(entry.key)),+ });+ }const envConfig = parseObject(config.env);const hasExplicitApiKey =@@ -265,6 +298,10 @@ export async function execute(ctx: AdapterExecutionContext): Promise<AdapterExecif (workspaceHints.length > 0) {env.PAPERCLIP_WORKSPACES_JSON = JSON.stringify(workspaceHints);}+ const targetPaperclipApiUrl = adapterExecutionTargetPaperclipApiUrl(executionTarget);+ if (targetPaperclipApiUrl) {+ env.PAPERCLIP_API_URL = targetPaperclipApiUrl;+ }for (const [k, v] of Object.entries(envConfig)) {if (typeof v === "string") env[k] = v;}@@ -278,8 +315,8 @@ export async function execute(ctx: AdapterExecutionContext): Promise<AdapterExec);const billingType = resolveCursorBillingType(effectiveEnv);const runtimeEnv = ensurePathInEnv(effectiveEnv);- await ensureCommandResolvable(command, cwd, runtimeEnv);- const resolvedCommand = await resolveCommandForLogs(command, cwd, runtimeEnv);+ await ensureAdapterExecutionTargetCommandResolvable(command, executionTarget, cwd, runtimeEnv);+ const resolvedCommand = await resolveAdapterExecutionTargetCommandForLogs(command, executionTarget, cwd, runtimeEnv);const loggedEnv = buildInvocationEnvForLogs(env, {runtimeEnv,includeRuntimeKeys: ["HOME"],@@ -294,18 +331,77 @@ export async function execute(ctx: AdapterExecutionContext): Promise<AdapterExecreturn asStringArray(config.args);})();const autoTrustEnabled = !hasCursorTrustBypassArg(extraArgs);+ const effectiveExecutionCwd = adapterExecutionTargetRemoteCwd(executionTarget, cwd);+ let restoreRemoteWorkspace: (() => Promise<void>) | null = null;+ let localSkillsDir: string | null = 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({+ target: executionTarget,+ adapterKey: "cursor",+ workspaceLocalDir: cwd,+ assets: [{+ key: "skills",+ localDir: localSkillsDir,+ followSymlinks: true,+ }],+ });+ restoreRemoteWorkspace = () => preparedExecutionTargetRuntime.restoreWorkspace();+ const managedHome = adapterExecutionTargetUsesManagedHome(executionTarget);+ 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(),+ ]);+ throw error;+ }+ }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(cwd));+ (runtimeSessionCwd.length === 0 || path.resolve(runtimeSessionCwd) === path.resolve(effectiveExecutionCwd)) &&+ adapterExecutionTargetSessionMatches(runtimeRemoteExecution, executionTarget);const sessionId = canResumeSession ? runtimeSessionId : null;- if (runtimeSessionId && !canResumeSession) {+ if (executionTargetIsRemote && runtimeSessionId && !canResumeSession) {await onLog("stdout",- `[paperclip] Cursor session "${runtimeSessionId}" was saved for cwd "${runtimeSessionCwd}" and will not be resumed in "${cwd}".\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`,);}@@ -387,7 +483,7 @@ export async function execute(ctx: AdapterExecutionContext): Promise<AdapterExec};const buildArgs = (resumeSessionId: string | null) => {- const args = ["-p", "--output-format", "stream-json", "--workspace", cwd];+ 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);@@ -402,7 +498,7 @@ export async function execute(ctx: AdapterExecutionContext): Promise<AdapterExecawait onMeta({adapterType: "cursor",command: resolvedCommand,- cwd,+ cwd: effectiveExecutionCwd,commandNotes,commandArgs: args,env: loggedEnv,@@ -436,7 +532,7 @@ export async function execute(ctx: AdapterExecutionContext): Promise<AdapterExec}};- const proc = await runChildProcess(runId, command, args, {+ const proc = await runAdapterExecutionTargetProcess(runId, executionTarget, command, args, {cwd,env,timeoutSec,@@ -488,10 +584,15 @@ export async function execute(ctx: AdapterExecutionContext): Promise<AdapterExecconst resolvedSessionParams = resolvedSessionId? ({sessionId: resolvedSessionId,- cwd,+ cwd: effectiveExecutionCwd,...(workspaceId ? { workspaceId } : {}),...(workspaceRepoUrl ? { repoUrl: workspaceRepoUrl } : {}),...(workspaceRepoRef ? { repoRef: workspaceRepoRef } : {}),+ ...(executionTargetIsRemote+ ? {+ remoteExecution: adapterExecutionTargetSessionIdentity(executionTarget),+ }+ : {}),} as Record<string, unknown>): null;const parsedError = typeof attempt.parsed.errorMessage === "string" ? attempt.parsed.errorMessage.trim() : "";@@ -527,20 +628,32 @@ export async function execute(ctx: AdapterExecutionContext): Promise<AdapterExec};};- const initial = await runAttempt(sessionId);- if (- sessionId &&- !initial.proc.timedOut &&- (initial.proc.exitCode ?? 0) !== 0 &&- isCursorUnknownSessionError(initial.proc.stdout, initial.proc.stderr)- ) {- await onLog(- "stdout",- `[paperclip] Cursor resume session "${sessionId}" is unavailable; retrying with a fresh session.\n`,- );- const retry = await runAttempt(null);- return toResult(retry, true);+ try {+ const initial = await runAttempt(sessionId);+ if (+ sessionId &&+ !initial.proc.timedOut &&+ (initial.proc.exitCode ?? 0) !== 0 &&+ isCursorUnknownSessionError(initial.proc.stdout, initial.proc.stderr)+ ) {+ await onLog(+ "stdout",+ `[paperclip] Cursor resume session "${sessionId}" is unavailable; retrying with a fresh session.\n`,+ );+ const retry = await runAttempt(null);+ return toResult(retry, true);+ }+ return toResult(initial);+ } finally {+ 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);+ }}-- return toResult(initial);}diff --git a/packages/adapters/gemini-local/src/server/execute.remote.test.ts b/packages/adapters/gemini-local/src/server/execute.remote.test.tsnew file mode 100644index 0000000000..4c97e91513--- /dev/null+++ b/packages/adapters/gemini-local/src/server/execute.remote.test.ts@@ -0,0 +1,272 @@+import { mkdir, mkdtemp, rm } from "node:fs/promises";+import os from "node:os";+import path from "node:path";+import { afterEach, describe, expect, it, vi } from "vitest";++const {+ runChildProcess,+ ensureCommandResolvable,+ resolveCommandForLogs,+ prepareWorkspaceForSshExecution,+ restoreWorkspaceFromSshExecution,+ runSshCommand,+ syncDirectoryToSsh,+} = vi.hoisted(() => ({+ runChildProcess: vi.fn(async () => ({+ exitCode: 0,+ signal: null,+ timedOut: false,+ stdout: [+ JSON.stringify({ type: "system", subtype: "init", session_id: "gemini-session-1", model: "gemini-2.5-pro" }),+ JSON.stringify({ type: "assistant", message: { content: [{ type: "output_text", text: "hello" }] } }),+ JSON.stringify({+ type: "result",+ subtype: "success",+ session_id: "gemini-session-1",+ usage: { promptTokenCount: 1, cachedContentTokenCount: 0, candidatesTokenCount: 1 },+ result: "hello",+ }),+ ].join("\n"),+ stderr: "",+ pid: 123,+ startedAt: new Date().toISOString(),+ })),+ ensureCommandResolvable: vi.fn(async () => undefined),+ resolveCommandForLogs: vi.fn(async () => "ssh://[email protected]:2222/remote/workspace :: gemini"),+ prepareWorkspaceForSshExecution: vi.fn(async () => undefined),+ restoreWorkspaceFromSshExecution: vi.fn(async () => undefined),+ runSshCommand: vi.fn(async () => ({+ stdout: "/home/agent",+ stderr: "",+ exitCode: 0,+ })),+ syncDirectoryToSsh: vi.fn(async () => undefined),+}));++vi.mock("@paperclipai/adapter-utils/server-utils", async () => {+ const actual = await vi.importActual<typeof import("@paperclipai/adapter-utils/server-utils")>(+ "@paperclipai/adapter-utils/server-utils",+ );+ return {+ ...actual,+ ensureCommandResolvable,+ resolveCommandForLogs,+ runChildProcess,+ };+});++vi.mock("@paperclipai/adapter-utils/ssh", async () => {+ const actual = await vi.importActual<typeof import("@paperclipai/adapter-utils/ssh")>(+ "@paperclipai/adapter-utils/ssh",+ );+ return {+ ...actual,+ prepareWorkspaceForSshExecution,+ restoreWorkspaceFromSshExecution,+ runSshCommand,+ syncDirectoryToSsh,+ };+});++import { execute } from "./execute.js";++describe("gemini remote execution", () => {+ const cleanupDirs: string[] = [];++ afterEach(async () => {+ vi.clearAllMocks();+ while (cleanupDirs.length > 0) {+ const dir = cleanupDirs.pop();+ if (!dir) continue;+ await rm(dir, { recursive: true, force: true }).catch(() => undefined);+ }+ });++ it("prepares the workspace, syncs Gemini skills, and restores workspace changes for remote SSH execution", async () => {+ const rootDir = await mkdtemp(path.join(os.tmpdir(), "paperclip-gemini-remote-"));+ cleanupDirs.push(rootDir);+ const workspaceDir = path.join(rootDir, "workspace");+ await mkdir(workspaceDir, { recursive: true });++ const result = await execute({+ runId: "run-1",+ agent: {+ id: "agent-1",+ companyId: "company-1",+ name: "Gemini Builder",+ adapterType: "gemini_local",+ adapterConfig: {},+ },+ runtime: {+ sessionId: null,+ sessionParams: null,+ sessionDisplayId: null,+ taskKey: null,+ },+ config: {+ command: "gemini",+ },+ context: {+ paperclipWorkspace: {+ cwd: workspaceDir,+ source: "project_primary",+ },+ },+ executionTransport: {+ remoteExecution: {+ host: "127.0.0.1",+ port: 2222,+ username: "fixture",+ remoteWorkspacePath: "/remote/workspace",+ remoteCwd: "/remote/workspace",+ privateKey: "PRIVATE KEY",+ knownHosts: "[127.0.0.1]:2222 ssh-ed25519 AAAA",+ strictHostKeyChecking: true,+ paperclipApiUrl: "http://198.51.100.10:3102",+ },+ },+ onLog: async () => {},+ });++ expect(result.sessionParams).toMatchObject({+ sessionId: "gemini-session-1",+ cwd: "/remote/workspace",+ remoteExecution: {+ transport: "ssh",+ host: "127.0.0.1",+ port: 2222,+ username: "fixture",+ remoteCwd: "/remote/workspace",+ paperclipApiUrl: "http://198.51.100.10:3102",+ },+ });+ expect(prepareWorkspaceForSshExecution).toHaveBeenCalledTimes(1);+ expect(syncDirectoryToSsh).toHaveBeenCalledTimes(1);+ expect(syncDirectoryToSsh).toHaveBeenCalledWith(expect.objectContaining({+ remoteDir: "/remote/workspace/.paperclip-runtime/gemini/skills",+ followSymlinks: true,+ }));+ expect(runSshCommand).toHaveBeenCalledWith(+ expect.anything(),+ expect.stringContaining(".gemini/skills"),+ expect.anything(),+ );+ const call = runChildProcess.mock.calls[0] as unknown as+ | [string, string, string[], { env: Record<string, string>; remoteExecution?: { remoteCwd: string } | null }]+ | undefined;+ expect(call?.[3].env.PAPERCLIP_API_URL).toBe("http://198.51.100.10:3102");+ expect(call?.[3].remoteExecution?.remoteCwd).toBe("/remote/workspace");+ expect(restoreWorkspaceFromSshExecution).toHaveBeenCalledTimes(1);+ });++ it("resumes saved Gemini sessions for remote SSH execution only when the identity matches", async () => {+ const rootDir = await mkdtemp(path.join(os.tmpdir(), "paperclip-gemini-remote-resume-"));+ cleanupDirs.push(rootDir);+ const workspaceDir = path.join(rootDir, "workspace");+ await mkdir(workspaceDir, { recursive: true });++ await execute({+ runId: "run-ssh-resume",+ agent: {+ id: "agent-1",+ companyId: "company-1",+ name: "Gemini Builder",+ adapterType: "gemini_local",+ adapterConfig: {},+ },+ runtime: {+ sessionId: "session-123",+ sessionParams: {+ sessionId: "session-123",+ cwd: "/remote/workspace",+ remoteExecution: {+ transport: "ssh",+ host: "127.0.0.1",+ port: 2222,+ username: "fixture",+ remoteCwd: "/remote/workspace",+ },+ },+ sessionDisplayId: "session-123",+ taskKey: null,+ },+ config: {+ command: "gemini",+ },+ context: {+ paperclipWorkspace: {+ cwd: workspaceDir,+ source: "project_primary",+ },+ },+ executionTransport: {+ remoteExecution: {+ host: "127.0.0.1",+ port: 2222,+ username: "fixture",+ remoteWorkspacePath: "/remote/workspace",+ remoteCwd: "/remote/workspace",+ privateKey: "PRIVATE KEY",+ knownHosts: "[127.0.0.1]:2222 ssh-ed25519 AAAA",+ strictHostKeyChecking: true,+ },+ },+ onLog: async () => {},+ });++ const call = runChildProcess.mock.calls[0] as unknown as [string, string, string[]] | undefined;+ expect(call?.[2]).toContain("--resume");+ expect(call?.[2]).toContain("session-123");+ });++ it("restores the remote workspace if skills sync fails after workspace prep", async () => {+ const rootDir = await mkdtemp(path.join(os.tmpdir(), "paperclip-gemini-remote-sync-fail-"));+ cleanupDirs.push(rootDir);+ const workspaceDir = path.join(rootDir, "workspace");+ await mkdir(workspaceDir, { recursive: true });+ syncDirectoryToSsh.mockRejectedValueOnce(new Error("sync failed"));++ await expect(execute({+ runId: "run-sync-fail",+ agent: {+ id: "agent-1",+ companyId: "company-1",+ name: "Gemini Builder",+ adapterType: "gemini_local",+ adapterConfig: {},+ },+ runtime: {+ sessionId: null,+ sessionParams: null,+ sessionDisplayId: null,+ taskKey: null,+ },+ config: {+ command: "gemini",+ },+ context: {+ paperclipWorkspace: {+ cwd: workspaceDir,+ source: "project_primary",+ },+ },+ executionTransport: {+ remoteExecution: {+ host: "127.0.0.1",+ port: 2222,+ username: "fixture",+ remoteWorkspacePath: "/remote/workspace",+ remoteCwd: "/remote/workspace",+ privateKey: "PRIVATE KEY",+ knownHosts: "[127.0.0.1]:2222 ssh-ed25519 AAAA",+ strictHostKeyChecking: true,+ },+ },+ onLog: async () => {},+ })).rejects.toThrow("sync failed");++ expect(prepareWorkspaceForSshExecution).toHaveBeenCalledTimes(1);+ expect(restoreWorkspaceFromSshExecution).toHaveBeenCalledTimes(1);+ expect(runChildProcess).not.toHaveBeenCalled();+ });+});diff --git a/packages/adapters/gemini-local/src/server/execute.ts b/packages/adapters/gemini-local/src/server/execute.tsindex eb529e409f..4c79b75375 100644--- a/packages/adapters/gemini-local/src/server/execute.ts+++ b/packages/adapters/gemini-local/src/server/execute.ts@@ -4,6 +4,22 @@ import os from "node:os";import path from "node:path";import { fileURLToPath } from "node:url";import type { AdapterExecutionContext, AdapterExecutionResult } from "@paperclipai/adapter-utils";+import {+ adapterExecutionTargetIsRemote,+ adapterExecutionTargetPaperclipApiUrl,+ adapterExecutionTargetRemoteCwd,+ adapterExecutionTargetSessionIdentity,+ adapterExecutionTargetSessionMatches,+ adapterExecutionTargetUsesManagedHome,+ describeAdapterExecutionTarget,+ ensureAdapterExecutionTargetCommandResolvable,+ prepareAdapterExecutionTargetRuntime,+ readAdapterExecutionTarget,+ readAdapterExecutionTargetHomeDir,+ resolveAdapterExecutionTargetCommandForLogs,+ runAdapterExecutionTargetProcess,+ runAdapterExecutionTargetShellCommand,+} from "@paperclipai/adapter-utils/execution-target";import {asBoolean,asNumber,@@ -12,12 +28,10 @@ import {buildPaperclipEnv,buildInvocationEnvForLogs,ensureAbsoluteDirectory,- ensureCommandResolvable,ensurePaperclipSkillSymlink,joinPromptSections,ensurePathInEnv,readPaperclipRuntimeSkillEntries,- resolveCommandForLogs,resolvePaperclipDesiredSkillNames,removeMaintainerOnlySkillSymlinks,parseObject,@@ -136,8 +150,28 @@ async function ensureGeminiSkillsInjected(}}+async function buildGeminiSkillsDir(+ config: Record<string, unknown>,+): Promise<string> {+ const tmp = await fs.mkdtemp(path.join(os.tmpdir(), "paperclip-gemini-skills-"));+ const target = path.join(tmp, "skills");+ await fs.mkdir(target, { recursive: true });+ const availableEntries = await readPaperclipRuntimeSkillEntries(config, __moduleDir);+ const desiredNames = new Set(resolvePaperclipDesiredSkillNames(config, availableEntries));+ for (const entry of availableEntries) {+ if (!desiredNames.has(entry.key)) continue;+ await fs.symlink(entry.source, path.join(target, entry.runtimeName));+ }+ return target;+}+export async function execute(ctx: AdapterExecutionContext): Promise<AdapterExecutionResult> {const { runId, agent, runtime, config, context, onLog, onMeta, onSpawn, authToken } = ctx;+ const executionTarget = readAdapterExecutionTarget({+ executionTarget: ctx.executionTarget,+ legacyRemoteExecution: ctx.executionTransport?.remoteExecution,+ });+ const executionTargetIsRemote = adapterExecutionTargetIsRemote(executionTarget);const promptTemplate = asString(config.promptTemplate,@@ -166,7 +200,9 @@ export async function execute(ctx: AdapterExecutionContext): Promise<AdapterExecawait ensureAbsoluteDirectory(cwd, { createIfMissing: true });const geminiSkillEntries = await readPaperclipRuntimeSkillEntries(config, __moduleDir);const desiredGeminiSkillNames = resolvePaperclipDesiredSkillNames(config, geminiSkillEntries);- await ensureGeminiSkillsInjected(onLog, geminiSkillEntries, desiredGeminiSkillNames);+ if (!executionTargetIsRemote) {+ await ensureGeminiSkillsInjected(onLog, geminiSkillEntries, desiredGeminiSkillNames);+ }const envConfig = parseObject(config.env);const hasExplicitApiKey =@@ -211,6 +247,8 @@ export async function execute(ctx: AdapterExecutionContext): Promise<AdapterExecif (workspaceRepoRef) env.PAPERCLIP_WORKSPACE_REPO_REF = workspaceRepoRef;if (agentHome) env.AGENT_HOME = agentHome;if (workspaceHints.length > 0) env.PAPERCLIP_WORKSPACES_JSON = JSON.stringify(workspaceHints);+ const targetPaperclipApiUrl = adapterExecutionTargetPaperclipApiUrl(executionTarget);+ if (targetPaperclipApiUrl) env.PAPERCLIP_API_URL = targetPaperclipApiUrl;for (const [key, value] of Object.entries(envConfig)) {if (typeof value === "string") env[key] = value;@@ -225,8 +263,8 @@ export async function execute(ctx: AdapterExecutionContext): Promise<AdapterExec);const billingType = resolveGeminiBillingType(effectiveEnv);const runtimeEnv = ensurePathInEnv(effectiveEnv);- await ensureCommandResolvable(command, cwd, runtimeEnv);- const resolvedCommand = await resolveCommandForLogs(command, cwd, runtimeEnv);+ await ensureAdapterExecutionTargetCommandResolvable(command, executionTarget, cwd, runtimeEnv);+ const resolvedCommand = await resolveAdapterExecutionTargetCommandForLogs(command, executionTarget, cwd, runtimeEnv);const loggedEnv = buildInvocationEnvForLogs(env, {runtimeEnv,includeRuntimeKeys: ["HOME"],@@ -240,18 +278,78 @@ export async function execute(ctx: AdapterExecutionContext): Promise<AdapterExecif (fromExtraArgs.length > 0) return fromExtraArgs;return asStringArray(config.args);})();+ const effectiveExecutionCwd = adapterExecutionTargetRemoteCwd(executionTarget, cwd);+ let restoreRemoteWorkspace: (() => Promise<void>) | null = null;+ let remoteSkillsDir: string | null = null;+ let localSkillsDir: string | null = 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({+ target: executionTarget,+ adapterKey: "gemini",+ workspaceLocalDir: cwd,+ assets: [{+ key: "skills",+ localDir: localSkillsDir,+ followSymlinks: true,+ }],+ });+ restoreRemoteWorkspace = () => preparedExecutionTargetRuntime.restoreWorkspace();+ const managedHome = adapterExecutionTargetUsesManagedHome(executionTarget);+ 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) {+ 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 },+ );+ }+ } catch (error) {+ await Promise.allSettled([+ restoreRemoteWorkspace?.(),+ localSkillsDir ? fs.rm(path.dirname(localSkillsDir), { recursive: true, force: true }).catch(() => undefined) : Promise.resolve(),+ ]);+ throw error;+ }+ }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(cwd));+ (runtimeSessionCwd.length === 0 || path.resolve(runtimeSessionCwd) === path.resolve(effectiveExecutionCwd)) &&+ adapterExecutionTargetSessionMatches(runtimeRemoteExecution, executionTarget);const sessionId = canResumeSession ? runtimeSessionId : null;- if (runtimeSessionId && !canResumeSession) {+ if (executionTargetIsRemote && runtimeSessionId && !canResumeSession) {await onLog("stdout",- `[paperclip] Gemini session "${runtimeSessionId}" was saved for cwd "${runtimeSessionCwd}" and will not be resumed in "${cwd}".\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`,);}@@ -350,7 +448,7 @@ export async function execute(ctx: AdapterExecutionContext): Promise<AdapterExecawait onMeta({adapterType: "gemini_local",command: resolvedCommand,- cwd,+ cwd: effectiveExecutionCwd,commandNotes,commandArgs: args.map((value, index) => (index === args.length - 1 ? `<prompt ${prompt.length} chars>` : value@@ -362,7 +460,7 @@ export async function execute(ctx: AdapterExecutionContext): Promise<AdapterExec});}- const proc = await runChildProcess(runId, command, args, {+ const proc = await runAdapterExecutionTargetProcess(runId, executionTarget, command, args, {cwd,env,timeoutSec,@@ -416,10 +514,15 @@ export async function execute(ctx: AdapterExecutionContext): Promise<AdapterExecconst resolvedSessionParams = resolvedSessionId? ({sessionId: resolvedSessionId,- cwd,+ cwd: effectiveExecutionCwd,...(workspaceId ? { workspaceId } : {}),...(workspaceRepoUrl ? { repoUrl: workspaceRepoUrl } : {}),...(workspaceRepoRef ? { repoRef: workspaceRepoRef } : {}),+ ...(executionTargetIsRemote+ ? {+ remoteExecution: adapterExecutionTargetSessionIdentity(executionTarget),+ }+ : {}),} as Record<string, unknown>): null;const parsedError = typeof attempt.parsed.errorMessage === "string" ? attempt.parsed.errorMessage.trim() : "";@@ -458,20 +561,27 @@ export async function execute(ctx: AdapterExecutionContext): Promise<AdapterExec};};- const initial = await runAttempt(sessionId);- if (- sessionId &&- !initial.proc.timedOut &&- (initial.proc.exitCode ?? 0) !== 0 &&- isGeminiUnknownSessionError(initial.proc.stdout, initial.proc.stderr)- ) {- await onLog(- "stdout",- `[paperclip] Gemini resume session "${sessionId}" is unavailable; retrying with a fresh session.\n`,- );- const retry = await runAttempt(null);- return toResult(retry, true, true);- }+ try {+ const initial = await runAttempt(sessionId);+ if (+ sessionId &&+ !initial.proc.timedOut &&+ (initial.proc.exitCode ?? 0) !== 0 &&+ isGeminiUnknownSessionError(initial.proc.stdout, initial.proc.stderr)+ ) {+ await onLog(+ "stdout",+ `[paperclip] Gemini resume session "${sessionId}" is unavailable; retrying with a fresh session.\n`,+ );+ const retry = await runAttempt(null);+ return toResult(retry, true, true);+ }- return toResult(initial);+ return toResult(initial);+ } finally {+ await Promise.all([+ restoreRemoteWorkspace?.(),+ localSkillsDir ? fs.rm(path.dirname(localSkillsDir), { recursive: true, force: true }).catch(() => undefined) : Promise.resolve(),+ ]);+ }}diff --git a/packages/adapters/opencode-local/src/server/execute.remote.test.ts b/packages/adapters/opencode-local/src/server/execute.remote.test.tsnew file mode 100644index 0000000000..bdf559915d--- /dev/null+++ b/packages/adapters/opencode-local/src/server/execute.remote.test.ts@@ -0,0 +1,225 @@+import { mkdir, mkdtemp, rm } from "node:fs/promises";+import os from "node:os";+import path from "node:path";+import { afterEach, describe, expect, it, vi } from "vitest";++const {+ runChildProcess,+ ensureCommandResolvable,+ resolveCommandForLogs,+ prepareWorkspaceForSshExecution,+ restoreWorkspaceFromSshExecution,+ runSshCommand,+ syncDirectoryToSsh,+} = vi.hoisted(() => ({+ runChildProcess: vi.fn(async () => ({+ exitCode: 0,+ signal: null,+ timedOut: false,+ stdout: [+ JSON.stringify({ type: "step_start", sessionID: "session_123" }),+ JSON.stringify({ type: "text", sessionID: "session_123", part: { text: "hello" } }),+ JSON.stringify({+ type: "step_finish",+ sessionID: "session_123",+ part: { cost: 0.001, tokens: { input: 1, output: 1, reasoning: 0, cache: { read: 0, write: 0 } } },+ }),+ ].join("\n"),+ stderr: "",+ pid: 123,+ startedAt: new Date().toISOString(),+ })),+ ensureCommandResolvable: vi.fn(async () => undefined),+ resolveCommandForLogs: vi.fn(async () => "ssh://[email protected]:2222/remote/workspace :: opencode"),+ prepareWorkspaceForSshExecution: vi.fn(async () => undefined),+ restoreWorkspaceFromSshExecution: vi.fn(async () => undefined),+ runSshCommand: vi.fn(async () => ({+ stdout: "/home/agent",+ stderr: "",+ exitCode: 0,+ })),+ syncDirectoryToSsh: vi.fn(async () => undefined),+}));++vi.mock("@paperclipai/adapter-utils/server-utils", async () => {+ const actual = await vi.importActual<typeof import("@paperclipai/adapter-utils/server-utils")>(+ "@paperclipai/adapter-utils/server-utils",+ );+ return {+ ...actual,+ ensureCommandResolvable,+ resolveCommandForLogs,+ runChildProcess,+ };+});++vi.mock("@paperclipai/adapter-utils/ssh", async () => {+ const actual = await vi.importActual<typeof import("@paperclipai/adapter-utils/ssh")>(+ "@paperclipai/adapter-utils/ssh",+ );+ return {+ ...actual,+ prepareWorkspaceForSshExecution,+ restoreWorkspaceFromSshExecution,+ runSshCommand,+ syncDirectoryToSsh,+ };+});++import { execute } from "./execute.js";++describe("opencode remote execution", () => {+ const cleanupDirs: string[] = [];++ afterEach(async () => {+ vi.clearAllMocks();+ while (cleanupDirs.length > 0) {+ const dir = cleanupDirs.pop();+ if (!dir) continue;+ await rm(dir, { recursive: true, force: true }).catch(() => undefined);+ }+ });++ it("prepares the workspace, syncs OpenCode skills, and restores workspace changes for remote SSH execution", async () => {+ const rootDir = await mkdtemp(path.join(os.tmpdir(), "paperclip-opencode-remote-"));+ cleanupDirs.push(rootDir);+ const workspaceDir = path.join(rootDir, "workspace");+ await mkdir(workspaceDir, { recursive: true });++ const result = await execute({+ runId: "run-1",+ agent: {+ id: "agent-1",+ companyId: "company-1",+ name: "OpenCode Builder",+ adapterType: "opencode_local",+ adapterConfig: {},+ },+ runtime: {+ sessionId: null,+ sessionParams: null,+ sessionDisplayId: null,+ taskKey: null,+ },+ config: {+ command: "opencode",+ model: "opencode/gpt-5-nano",+ },+ context: {+ paperclipWorkspace: {+ cwd: workspaceDir,+ source: "project_primary",+ },+ },+ executionTransport: {+ remoteExecution: {+ host: "127.0.0.1",+ port: 2222,+ username: "fixture",+ remoteWorkspacePath: "/remote/workspace",+ remoteCwd: "/remote/workspace",+ privateKey: "PRIVATE KEY",+ knownHosts: "[127.0.0.1]:2222 ssh-ed25519 AAAA",+ strictHostKeyChecking: true,+ paperclipApiUrl: "http://198.51.100.10:3102",+ },+ },+ onLog: async () => {},+ });++ expect(result.sessionParams).toMatchObject({+ sessionId: "session_123",+ cwd: "/remote/workspace",+ remoteExecution: {+ transport: "ssh",+ host: "127.0.0.1",+ port: 2222,+ username: "fixture",+ remoteCwd: "/remote/workspace",+ paperclipApiUrl: "http://198.51.100.10:3102",+ },+ });+ expect(prepareWorkspaceForSshExecution).toHaveBeenCalledTimes(1);+ expect(syncDirectoryToSsh).toHaveBeenCalledTimes(2);+ expect(syncDirectoryToSsh).toHaveBeenCalledWith(expect.objectContaining({+ remoteDir: "/remote/workspace/.paperclip-runtime/opencode/xdgConfig",+ }));+ expect(syncDirectoryToSsh).toHaveBeenCalledWith(expect.objectContaining({+ remoteDir: "/remote/workspace/.paperclip-runtime/opencode/skills",+ followSymlinks: true,+ }));+ expect(runSshCommand).toHaveBeenCalledWith(+ expect.anything(),+ expect.stringContaining(".claude/skills"),+ expect.anything(),+ );+ const call = runChildProcess.mock.calls[0] as unknown as+ | [string, string, string[], { env: Record<string, string>; remoteExecution?: { remoteCwd: string } | null }]+ | undefined;+ expect(call?.[3].env.PAPERCLIP_API_URL).toBe("http://198.51.100.10:3102");+ expect(call?.[3].env.XDG_CONFIG_HOME).toBe("/remote/workspace/.paperclip-runtime/opencode/xdgConfig");+ expect(call?.[3].remoteExecution?.remoteCwd).toBe("/remote/workspace");+ expect(restoreWorkspaceFromSshExecution).toHaveBeenCalledTimes(1);+ });++ it("resumes saved OpenCode sessions for remote SSH execution only when the identity matches", async () => {+ const rootDir = await mkdtemp(path.join(os.tmpdir(), "paperclip-opencode-remote-resume-"));+ cleanupDirs.push(rootDir);+ const workspaceDir = path.join(rootDir, "workspace");+ await mkdir(workspaceDir, { recursive: true });++ await execute({+ runId: "run-ssh-resume",+ agent: {+ id: "agent-1",+ companyId: "company-1",+ name: "OpenCode Builder",+ adapterType: "opencode_local",+ adapterConfig: {},+ },+ runtime: {+ sessionId: "session-123",+ sessionParams: {+ sessionId: "session-123",+ cwd: "/remote/workspace",+ remoteExecution: {+ transport: "ssh",+ host: "127.0.0.1",+ port: 2222,+ username: "fixture",+ remoteCwd: "/remote/workspace",+ },+ },+ sessionDisplayId: "session-123",+ taskKey: null,+ },+ config: {+ command: "opencode",+ model: "opencode/gpt-5-nano",+ },+ context: {+ paperclipWorkspace: {+ cwd: workspaceDir,+ source: "project_primary",+ },+ },+ executionTransport: {+ remoteExecution: {+ host: "127.0.0.1",+ port: 2222,+ username: "fixture",+ remoteWorkspacePath: "/remote/workspace",+ remoteCwd: "/remote/workspace",+ privateKey: "PRIVATE KEY",+ knownHosts: "[127.0.0.1]:2222 ssh-ed25519 AAAA",+ strictHostKeyChecking: true,+ },+ },+ onLog: async () => {},+ });++ const call = runChildProcess.mock.calls[0] as unknown as [string, string, string[]] | undefined;+ expect(call?.[2]).toContain("--session");+ expect(call?.[2]).toContain("session-123");+ });+});diff --git a/packages/adapters/opencode-local/src/server/execute.ts b/packages/adapters/opencode-local/src/server/execute.tsindex 93de85fd98..0aa86b171b 100644--- a/packages/adapters/opencode-local/src/server/execute.ts+++ b/packages/adapters/opencode-local/src/server/execute.ts@@ -3,6 +3,22 @@ import os from "node:os";import path from "node:path";import { fileURLToPath } from "node:url";import { inferOpenAiCompatibleBiller, type AdapterExecutionContext, type AdapterExecutionResult } from "@paperclipai/adapter-utils";+import {+ adapterExecutionTargetIsRemote,+ adapterExecutionTargetPaperclipApiUrl,+ adapterExecutionTargetRemoteCwd,+ adapterExecutionTargetSessionIdentity,+ adapterExecutionTargetSessionMatches,+ adapterExecutionTargetUsesManagedHome,+ describeAdapterExecutionTarget,+ ensureAdapterExecutionTargetCommandResolvable,+ prepareAdapterExecutionTargetRuntime,+ readAdapterExecutionTarget,+ readAdapterExecutionTargetHomeDir,+ resolveAdapterExecutionTargetCommandForLogs,+ runAdapterExecutionTargetProcess,+ runAdapterExecutionTargetShellCommand,+} from "@paperclipai/adapter-utils/execution-target";import {asString,asNumber,@@ -12,10 +28,8 @@ import {joinPromptSections,buildInvocationEnvForLogs,ensureAbsoluteDirectory,- ensureCommandResolvable,ensurePaperclipSkillSymlink,ensurePathInEnv,- resolveCommandForLogs,renderTemplate,renderPaperclipWakePrompt,stringifyPaperclipWakePayload,@@ -93,8 +107,26 @@ async function ensureOpenCodeSkillsInjected(}}+async function buildOpenCodeSkillsDir(config: Record<string, unknown>): Promise<string> {+ const tmp = await fs.mkdtemp(path.join(os.tmpdir(), "paperclip-opencode-skills-"));+ const target = path.join(tmp, "skills");+ await fs.mkdir(target, { recursive: true });+ const availableEntries = await readPaperclipRuntimeSkillEntries(config, __moduleDir);+ const desiredNames = new Set(resolvePaperclipDesiredSkillNames(config, availableEntries));+ for (const entry of availableEntries) {+ if (!desiredNames.has(entry.key)) continue;+ await fs.symlink(entry.source, path.join(target, entry.runtimeName));+ }+ return target;+}+export async function execute(ctx: AdapterExecutionContext): Promise<AdapterExecutionResult> {const { runId, agent, runtime, config, context, onLog, onMeta, onSpawn, authToken } = ctx;+ const executionTarget = readAdapterExecutionTarget({+ executionTarget: ctx.executionTarget,+ legacyRemoteExecution: ctx.executionTransport?.remoteExecution,+ });+ const executionTargetIsRemote = adapterExecutionTargetIsRemote(executionTarget);const promptTemplate = asString(config.promptTemplate,@@ -123,11 +155,13 @@ export async function execute(ctx: AdapterExecutionContext): Promise<AdapterExecawait ensureAbsoluteDirectory(cwd, { createIfMissing: true });const openCodeSkillEntries = await readPaperclipRuntimeSkillEntries(config, __moduleDir);const desiredOpenCodeSkillNames = resolvePaperclipDesiredSkillNames(config, openCodeSkillEntries);- await ensureOpenCodeSkillsInjected(- onLog,- openCodeSkillEntries,- desiredOpenCodeSkillNames,- );+ if (!executionTargetIsRemote) {+ await ensureOpenCodeSkillsInjected(+ onLog,+ openCodeSkillEntries,+ desiredOpenCodeSkillNames,+ );+ }const envConfig = parseObject(config.env);const hasExplicitApiKey =@@ -172,6 +206,8 @@ export async function execute(ctx: AdapterExecutionContext): Promise<AdapterExecif (workspaceRepoRef) env.PAPERCLIP_WORKSPACE_REPO_REF = workspaceRepoRef;if (agentHome) env.AGENT_HOME = agentHome;if (workspaceHints.length > 0) env.PAPERCLIP_WORKSPACES_JSON = JSON.stringify(workspaceHints);+ const targetPaperclipApiUrl = adapterExecutionTargetPaperclipApiUrl(executionTarget);+ if (targetPaperclipApiUrl) env.PAPERCLIP_API_URL = targetPaperclipApiUrl;for (const [key, value] of Object.entries(envConfig)) {if (typeof value === "string") env[key] = value;@@ -185,26 +221,30 @@ export async function execute(ctx: AdapterExecutionContext): Promise<AdapterExecenv.PAPERCLIP_API_KEY = authToken;}const preparedRuntimeConfig = await prepareOpenCodeRuntimeConfig({ env, config });+ const localRuntimeConfigHome =+ preparedRuntimeConfig.notes.length > 0 ? preparedRuntimeConfig.env.XDG_CONFIG_HOME : "";try {const runtimeEnv = Object.fromEntries(Object.entries(ensurePathInEnv({ ...process.env, ...preparedRuntimeConfig.env })).filter((entry): entry is [string, string] => typeof entry[1] === "string",),);- await ensureCommandResolvable(command, cwd, runtimeEnv);- const resolvedCommand = await resolveCommandForLogs(command, cwd, runtimeEnv);+ await ensureAdapterExecutionTargetCommandResolvable(command, executionTarget, cwd, runtimeEnv);+ const resolvedCommand = await resolveAdapterExecutionTargetCommandForLogs(command, executionTarget, cwd, runtimeEnv);const loggedEnv = buildInvocationEnvForLogs(preparedRuntimeConfig.env, {runtimeEnv,includeRuntimeKeys: ["HOME"],resolvedCommand,});- await ensureOpenCodeModelConfiguredAndAvailable({- model,- command,- cwd,- env: runtimeEnv,- });+ if (!executionTargetIsRemote) {+ await ensureOpenCodeModelConfiguredAndAvailable({+ model,+ command,+ cwd,+ env: runtimeEnv,+ });+ }const timeoutSec = asNumber(config.timeoutSec, 0);const graceSec = asNumber(config.graceSec, 20);@@ -213,18 +253,80 @@ export async function execute(ctx: AdapterExecutionContext): Promise<AdapterExecif (fromExtraArgs.length > 0) return fromExtraArgs;return asStringArray(config.args);})();+ const effectiveExecutionCwd = adapterExecutionTargetRemoteCwd(executionTarget, cwd);+ let restoreRemoteWorkspace: (() => Promise<void>) | null = null;+ let localSkillsDir: string | null = null;++ if (executionTargetIsRemote) {+ localSkillsDir = await buildOpenCodeSkillsDir(config);+ await onLog(+ "stdout",+ `[paperclip] Syncing workspace and OpenCode runtime assets to ${describeAdapterExecutionTarget(executionTarget)}.\n`,+ );+ const preparedExecutionTargetRuntime = await prepareAdapterExecutionTargetRuntime({+ target: executionTarget,+ adapterKey: "opencode",+ workspaceLocalDir: cwd,+ assets: [+ {+ key: "skills",+ localDir: localSkillsDir,+ followSymlinks: true,+ },+ ...(localRuntimeConfigHome+ ? [{+ key: "xdgConfig",+ localDir: localRuntimeConfigHome,+ }]+ : []),+ ],+ });+ restoreRemoteWorkspace = () => preparedExecutionTargetRuntime.restoreWorkspace();+ 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;+ }+ const remoteHomeDir = 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 },+ );+ }+ }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(cwd));+ (runtimeSessionCwd.length === 0 || path.resolve(runtimeSessionCwd) === path.resolve(effectiveExecutionCwd)) &&+ adapterExecutionTargetSessionMatches(runtimeRemoteExecution, executionTarget);const sessionId = canResumeSession ? runtimeSessionId : null;- if (runtimeSessionId && !canResumeSession) {+ 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 "${cwd}".\n`,+ `[paperclip] OpenCode session "${runtimeSessionId}" was saved for cwd "${runtimeSessionCwd}" and will not be resumed in "${effectiveExecutionCwd}".\n`,);}const instructionsFilePath = asString(config.instructionsFilePath, "").trim();@@ -314,7 +416,7 @@ export async function execute(ctx: AdapterExecutionContext): Promise<AdapterExecawait onMeta({adapterType: "opencode_local",command: resolvedCommand,- cwd,+ cwd: effectiveExecutionCwd,commandNotes,commandArgs: [...args, `<stdin prompt ${prompt.length} chars>`],env: loggedEnv,@@ -324,9 +426,9 @@ export async function execute(ctx: AdapterExecutionContext): Promise<AdapterExec});}- const proc = await runChildProcess(runId, command, args, {+ const proc = await runAdapterExecutionTargetProcess(runId, executionTarget, command, args, {cwd,- env: runtimeEnv,+ env: preparedRuntimeConfig.env,stdin: prompt,timeoutSec,graceSec,@@ -364,10 +466,15 @@ export async function execute(ctx: AdapterExecutionContext): Promise<AdapterExecconst resolvedSessionParams = resolvedSessionId? ({sessionId: resolvedSessionId,- cwd,+ cwd: effectiveExecutionCwd,...(workspaceId ? { workspaceId } : {}),...(workspaceRepoUrl ? { repoUrl: workspaceRepoUrl } : {}),...(workspaceRepoRef ? { repoRef: workspaceRepoRef } : {}),+ ...(executionTargetIsRemote+ ? {+ remoteExecution: adapterExecutionTargetSessionIdentity(executionTarget),+ }+ : {}),} as Record<string, unknown>): null;@@ -408,23 +515,30 @@ export async function execute(ctx: AdapterExecutionContext): Promise<AdapterExec};};- const initial = await runAttempt(sessionId);- const initialFailed =- !initial.proc.timedOut && ((initial.proc.exitCode ?? 0) !== 0 || Boolean(initial.parsed.errorMessage));- if (- sessionId &&- initialFailed &&- isOpenCodeUnknownSessionError(initial.proc.stdout, initial.rawStderr)- ) {- await onLog(- "stdout",- `[paperclip] OpenCode session "${sessionId}" is unavailable; retrying with a fresh session.\n`,- );- const retry = await runAttempt(null);- return toResult(retry, true);- }+ try {+ const initial = await runAttempt(sessionId);+ const initialFailed =+ !initial.proc.timedOut && ((initial.proc.exitCode ?? 0) !== 0 || Boolean(initial.parsed.errorMessage));+ if (+ sessionId &&+ initialFailed &&+ isOpenCodeUnknownSessionError(initial.proc.stdout, initial.rawStderr)+ ) {+ await onLog(+ "stdout",+ `[paperclip] OpenCode session "${sessionId}" is unavailable; retrying with a fresh session.\n`,+ );+ const retry = await runAttempt(null);+ return toResult(retry, true);+ }- return toResult(initial);+ return toResult(initial);+ } finally {+ await Promise.all([+ restoreRemoteWorkspace?.(),+ localSkillsDir ? fs.rm(path.dirname(localSkillsDir), { recursive: true, force: true }).catch(() => undefined) : Promise.resolve(),+ ]);+ }} finally {await preparedRuntimeConfig.cleanup();}diff --git a/packages/adapters/opencode-local/src/server/parse.test.ts b/packages/adapters/opencode-local/src/server/parse.test.tsindex 5f4a3a360c..51d5a5911a 100644--- a/packages/adapters/opencode-local/src/server/parse.test.ts+++ b/packages/adapters/opencode-local/src/server/parse.test.ts@@ -40,6 +40,33 @@ describe("parseOpenCodeJsonl", () => {});expect(parsed.costUsd).toBeCloseTo(0.0025, 6);expect(parsed.errorMessage).toContain("model unavailable");+ expect(parsed.toolErrors).toEqual([]);+ });++ it("keeps failed tool calls separate from fatal run errors", () => {+ const stdout = [+ JSON.stringify({+ type: "tool_use",+ sessionID: "session_123",+ part: {+ state: {+ status: "error",+ error: "File not found: e2b-adapter-result.txt",+ },+ },+ }),+ JSON.stringify({+ type: "text",+ sessionID: "session_123",+ part: { text: "Recovered and completed the task" },+ }),+ ].join("\n");++ const parsed = parseOpenCodeJsonl(stdout);+ expect(parsed.sessionId).toBe("session_123");+ expect(parsed.summary).toBe("Recovered and completed the task");+ expect(parsed.errorMessage).toBeNull();+ expect(parsed.toolErrors).toEqual(["File not found: e2b-adapter-result.txt"]);});it("detects unknown session errors", () => {diff --git a/packages/adapters/opencode-local/src/server/parse.ts b/packages/adapters/opencode-local/src/server/parse.tsindex 96af0ed19b..ee7fd41279 100644--- a/packages/adapters/opencode-local/src/server/parse.ts+++ b/packages/adapters/opencode-local/src/server/parse.ts@@ -23,6 +23,7 @@ export function parseOpenCodeJsonl(stdout: string) {let sessionId: string | null = null;const messages: string[] = [];const errors: string[] = [];+ const toolErrors: string[] = [];const usage = {inputTokens: 0,cachedInputTokens: 0,@@ -65,7 +66,7 @@ export function parseOpenCodeJsonl(stdout: string) {const state = parseObject(part.state);if (asString(state.status, "") === "error") {const text = asString(state.error, "").trim();- if (text) errors.push(text);+ if (text) toolErrors.push(text);}continue;}@@ -83,6 +84,7 @@ export function parseOpenCodeJsonl(stdout: string) {usage,costUsd,errorMessage: errors.length > 0 ? errors.join("\n") : null,+ toolErrors,};}diff --git a/packages/adapters/pi-local/src/server/execute.remote.test.ts b/packages/adapters/pi-local/src/server/execute.remote.test.tsnew file mode 100644index 0000000000..302f44410c--- /dev/null+++ b/packages/adapters/pi-local/src/server/execute.remote.test.ts@@ -0,0 +1,229 @@+import { mkdir, mkdtemp, rm } from "node:fs/promises";+import os from "node:os";+import path from "node:path";+import { afterEach, describe, expect, it, vi } from "vitest";++const {+ runChildProcess,+ ensureCommandResolvable,+ resolveCommandForLogs,+ prepareWorkspaceForSshExecution,+ restoreWorkspaceFromSshExecution,+ runSshCommand,+ syncDirectoryToSsh,+} = vi.hoisted(() => ({+ runChildProcess: vi.fn(async () => ({+ exitCode: 0,+ signal: null,+ timedOut: false,+ stdout: JSON.stringify({+ type: "turn_end",+ message: {+ role: "assistant",+ content: "done",+ usage: {+ input: 10,+ output: 20,+ cacheRead: 0,+ cost: { total: 0.01 },+ },+ },+ toolResults: [],+ }),+ stderr: "",+ pid: 123,+ startedAt: new Date().toISOString(),+ })),+ ensureCommandResolvable: vi.fn(async () => undefined),+ resolveCommandForLogs: vi.fn(async () => "ssh://[email protected]:2222/remote/workspace :: pi"),+ prepareWorkspaceForSshExecution: vi.fn(async () => undefined),+ restoreWorkspaceFromSshExecution: vi.fn(async () => undefined),+ runSshCommand: vi.fn(async () => ({+ stdout: "",+ stderr: "",+ exitCode: 0,+ })),+ syncDirectoryToSsh: vi.fn(async () => undefined),+}));++vi.mock("@paperclipai/adapter-utils/server-utils", async () => {+ const actual = await vi.importActual<typeof import("@paperclipai/adapter-utils/server-utils")>(+ "@paperclipai/adapter-utils/server-utils",+ );+ return {+ ...actual,+ ensureCommandResolvable,+ resolveCommandForLogs,+ runChildProcess,+ };+});++vi.mock("@paperclipai/adapter-utils/ssh", async () => {+ const actual = await vi.importActual<typeof import("@paperclipai/adapter-utils/ssh")>(+ "@paperclipai/adapter-utils/ssh",+ );+ return {+ ...actual,+ prepareWorkspaceForSshExecution,+ restoreWorkspaceFromSshExecution,+ runSshCommand,+ syncDirectoryToSsh,+ };+});++import { execute } from "./execute.js";++describe("pi remote execution", () => {+ const cleanupDirs: string[] = [];++ afterEach(async () => {+ vi.clearAllMocks();+ while (cleanupDirs.length > 0) {+ const dir = cleanupDirs.pop();+ if (!dir) continue;+ await rm(dir, { recursive: true, force: true }).catch(() => undefined);+ }+ });++ it("prepares the workspace, syncs Pi skills, and restores workspace changes for remote SSH execution", async () => {+ const rootDir = await mkdtemp(path.join(os.tmpdir(), "paperclip-pi-remote-"));+ cleanupDirs.push(rootDir);+ const workspaceDir = path.join(rootDir, "workspace");+ await mkdir(workspaceDir, { recursive: true });++ const result = await execute({+ runId: "run-1",+ agent: {+ id: "agent-1",+ companyId: "company-1",+ name: "Pi Builder",+ adapterType: "pi_local",+ adapterConfig: {},+ },+ runtime: {+ sessionId: null,+ sessionParams: null,+ sessionDisplayId: null,+ taskKey: null,+ },+ config: {+ command: "pi",+ model: "openai/gpt-5.4-mini",+ },+ context: {+ paperclipWorkspace: {+ cwd: workspaceDir,+ source: "project_primary",+ },+ },+ executionTransport: {+ remoteExecution: {+ host: "127.0.0.1",+ port: 2222,+ username: "fixture",+ remoteWorkspacePath: "/remote/workspace",+ remoteCwd: "/remote/workspace",+ privateKey: "PRIVATE KEY",+ knownHosts: "[127.0.0.1]:2222 ssh-ed25519 AAAA",+ strictHostKeyChecking: true,+ paperclipApiUrl: "http://198.51.100.10:3102",+ },+ },+ onLog: async () => {},+ });++ expect(result.sessionParams).toMatchObject({+ cwd: "/remote/workspace",+ remoteExecution: {+ transport: "ssh",+ host: "127.0.0.1",+ port: 2222,+ username: "fixture",+ remoteCwd: "/remote/workspace",+ paperclipApiUrl: "http://198.51.100.10:3102",+ },+ });+ expect(String(result.sessionId)).toContain("/remote/workspace/.paperclip-runtime/pi/sessions/");+ expect(prepareWorkspaceForSshExecution).toHaveBeenCalledTimes(1);+ expect(syncDirectoryToSsh).toHaveBeenCalledTimes(1);+ expect(syncDirectoryToSsh).toHaveBeenCalledWith(expect.objectContaining({+ remoteDir: "/remote/workspace/.paperclip-runtime/pi/skills",+ followSymlinks: true,+ }));+ expect(runSshCommand).toHaveBeenCalledWith(+ expect.anything(),+ expect.stringContaining(".paperclip-runtime/pi/sessions"),+ expect.anything(),+ );+ const call = runChildProcess.mock.calls[0] as unknown as+ | [string, string, string[], { env: Record<string, string>; remoteExecution?: { remoteCwd: string } | null }]+ | undefined;+ expect(call?.[2]).toContain("--session");+ expect(call?.[2]).toContain("--skill");+ expect(call?.[2]).toContain("/remote/workspace/.paperclip-runtime/pi/skills");+ expect(call?.[3].env.PAPERCLIP_API_URL).toBe("http://198.51.100.10:3102");+ expect(call?.[3].remoteExecution?.remoteCwd).toBe("/remote/workspace");+ expect(restoreWorkspaceFromSshExecution).toHaveBeenCalledTimes(1);+ });++ it("resumes saved Pi sessions for remote SSH execution only when the identity matches", async () => {+ const rootDir = await mkdtemp(path.join(os.tmpdir(), "paperclip-pi-remote-resume-"));+ cleanupDirs.push(rootDir);+ const workspaceDir = path.join(rootDir, "workspace");+ await mkdir(workspaceDir, { recursive: true });++ await execute({+ runId: "run-ssh-resume",+ agent: {+ id: "agent-1",+ companyId: "company-1",+ name: "Pi Builder",+ adapterType: "pi_local",+ adapterConfig: {},+ },+ runtime: {+ sessionId: "/remote/workspace/.paperclip-runtime/pi/sessions/session-123.jsonl",+ sessionParams: {+ sessionId: "/remote/workspace/.paperclip-runtime/pi/sessions/session-123.jsonl",+ cwd: "/remote/workspace",+ remoteExecution: {+ transport: "ssh",+ host: "127.0.0.1",+ port: 2222,+ username: "fixture",+ remoteCwd: "/remote/workspace",+ },+ },+ sessionDisplayId: "session-123",+ taskKey: null,+ },+ config: {+ command: "pi",+ model: "openai/gpt-5.4-mini",+ },+ context: {+ paperclipWorkspace: {+ cwd: workspaceDir,+ source: "project_primary",+ },+ },+ executionTransport: {+ remoteExecution: {+ host: "127.0.0.1",+ port: 2222,+ username: "fixture",+ remoteWorkspacePath: "/remote/workspace",+ remoteCwd: "/remote/workspace",+ privateKey: "PRIVATE KEY",+ knownHosts: "[127.0.0.1]:2222 ssh-ed25519 AAAA",+ strictHostKeyChecking: true,+ },+ },+ onLog: async () => {},+ });++ const call = runChildProcess.mock.calls[0] as unknown as [string, string, string[]] | undefined;+ expect(call?.[2]).toContain("--session");+ expect(call?.[2]).toContain("/remote/workspace/.paperclip-runtime/pi/sessions/session-123.jsonl");+ });+});diff --git a/packages/adapters/pi-local/src/server/execute.ts b/packages/adapters/pi-local/src/server/execute.tsindex 79af1be32d..819be8e1b3 100644--- a/packages/adapters/pi-local/src/server/execute.ts+++ b/packages/adapters/pi-local/src/server/execute.ts@@ -3,6 +3,21 @@ import os from "node:os";import path from "node:path";import { fileURLToPath } from "node:url";import { inferOpenAiCompatibleBiller, type AdapterExecutionContext, type AdapterExecutionResult } from "@paperclipai/adapter-utils";+import {+ adapterExecutionTargetIsRemote,+ adapterExecutionTargetPaperclipApiUrl,+ adapterExecutionTargetRemoteCwd,+ adapterExecutionTargetSessionIdentity,+ adapterExecutionTargetSessionMatches,+ adapterExecutionTargetUsesManagedHome,+ describeAdapterExecutionTarget,+ ensureAdapterExecutionTargetCommandResolvable,+ ensureAdapterExecutionTargetFile,+ prepareAdapterExecutionTargetRuntime,+ readAdapterExecutionTarget,+ resolveAdapterExecutionTargetCommandForLogs,+ runAdapterExecutionTargetProcess,+} from "@paperclipai/adapter-utils/execution-target";import {asString,asNumber,@@ -12,11 +27,9 @@ import {joinPromptSections,buildInvocationEnvForLogs,ensureAbsoluteDirectory,- ensureCommandResolvable,ensurePaperclipSkillSymlink,ensurePathInEnv,readPaperclipRuntimeSkillEntries,- resolveCommandForLogs,resolvePaperclipDesiredSkillNames,removeMaintainerOnlySkillSymlinks,renderTemplate,@@ -95,6 +108,19 @@ async function ensurePiSkillsInjected(}}+async function buildPiSkillsDir(config: Record<string, unknown>): Promise<string> {+ const tmp = await fs.mkdtemp(path.join(os.tmpdir(), "paperclip-pi-skills-"));+ const target = path.join(tmp, "skills");+ await fs.mkdir(target, { recursive: true });+ const availableEntries = await readPaperclipRuntimeSkillEntries(config, __moduleDir);+ const desiredNames = new Set(resolvePaperclipDesiredSkillNames(config, availableEntries));+ for (const entry of availableEntries) {+ if (!desiredNames.has(entry.key)) continue;+ await fs.symlink(entry.source, path.join(target, entry.runtimeName));+ }+ return target;+}+function resolvePiBiller(env: Record<string, string>, provider: string | null): string {return inferOpenAiCompatibleBiller(env, null) ?? provider ?? "unknown";}@@ -109,8 +135,18 @@ function buildSessionPath(agentId: string, timestamp: string): string {return path.join(PAPERCLIP_SESSIONS_DIR, `${safeTimestamp}-${agentId}.jsonl`);}+function buildRemoteSessionPath(runtimeRootDir: string, agentId: string, timestamp: string): string {+ const safeTimestamp = timestamp.replace(/[:.]/g, "-");+ return path.posix.join(runtimeRootDir, "sessions", `${safeTimestamp}-${agentId}.jsonl`);+}+export async function execute(ctx: AdapterExecutionContext): Promise<AdapterExecutionResult> {const { runId, agent, runtime, config, context, onLog, onMeta, onSpawn, authToken } = ctx;+ const executionTarget = readAdapterExecutionTarget({+ executionTarget: ctx.executionTarget,+ legacyRemoteExecution: ctx.executionTransport?.remoteExecution,+ });+ const executionTargetIsRemote = adapterExecutionTargetIsRemote(executionTarget);const promptTemplate = asString(config.promptTemplate,@@ -140,15 +176,18 @@ export async function execute(ctx: AdapterExecutionContext): Promise<AdapterExecconst useConfiguredInsteadOfAgentHome = workspaceSource === "agent_home" && configuredCwd.length > 0;const effectiveWorkspaceCwd = useConfiguredInsteadOfAgentHome ? "" : workspaceCwd;const cwd = effectiveWorkspaceCwd || configuredCwd || process.cwd();+ const effectiveExecutionCwd = adapterExecutionTargetRemoteCwd(executionTarget, cwd);await ensureAbsoluteDirectory(cwd, { createIfMissing: true });-- // Ensure sessions directory exists- await ensureSessionsDir();-- // Inject skills++ if (!executionTargetIsRemote) {+ await ensureSessionsDir();+ }+const piSkillEntries = await readPaperclipRuntimeSkillEntries(config, __moduleDir);const desiredPiSkillNames = resolvePaperclipDesiredSkillNames(config, piSkillEntries);- await ensurePiSkillsInjected(onLog, piSkillEntries, desiredPiSkillNames);+ if (!executionTargetIsRemote) {+ await ensurePiSkillsInjected(onLog, piSkillEntries, desiredPiSkillNames);+ }// Build environmentconst envConfig = parseObject(config.env);@@ -156,7 +195,7 @@ export async function execute(ctx: AdapterExecutionContext): Promise<AdapterExectypeof envConfig.PAPERCLIP_API_KEY === "string" && envConfig.PAPERCLIP_API_KEY.trim().length > 0;const env: Record<string, string> = { ...buildPaperclipEnv(agent) };env.PAPERCLIP_RUN_ID = runId;-+const wakeTaskId =(typeof context.taskId === "string" && context.taskId.trim().length > 0 && context.taskId.trim()) ||(typeof context.issueId === "string" && context.issueId.trim().length > 0 && context.issueId.trim()) ||@@ -196,6 +235,8 @@ export async function execute(ctx: AdapterExecutionContext): Promise<AdapterExecif (workspaceRepoRef) env.PAPERCLIP_WORKSPACE_REPO_REF = workspaceRepoRef;if (agentHome) env.AGENT_HOME = agentHome;if (workspaceHints.length > 0) env.PAPERCLIP_WORKSPACES_JSON = JSON.stringify(workspaceHints);+ const targetPaperclipApiUrl = adapterExecutionTargetPaperclipApiUrl(executionTarget);+ if (targetPaperclipApiUrl) env.PAPERCLIP_API_URL = targetPaperclipApiUrl;for (const [key, value] of Object.entries(envConfig)) {if (typeof value === "string") env[key] = value;@@ -203,7 +244,7 @@ export async function execute(ctx: AdapterExecutionContext): Promise<AdapterExecif (!hasExplicitApiKey && authToken) {env.PAPERCLIP_API_KEY = authToken;}-+// Prepend installed skill `bin/` dirs to PATH so an agent's bash tool can// invoke skill binaries (e.g. `paperclip-get-issue`) by name. Without this,// any pi_local agent whose AGENTS.md calls a skill command via bash hits@@ -232,21 +273,22 @@ export async function execute(ctx: AdapterExecutionContext): Promise<AdapterExec(entry): entry is [string, string] => typeof entry[1] === "string",),);- await ensureCommandResolvable(command, cwd, runtimeEnv);- const resolvedCommand = await resolveCommandForLogs(command, cwd, runtimeEnv);+ await ensureAdapterExecutionTargetCommandResolvable(command, executionTarget, cwd, runtimeEnv);+ const resolvedCommand = await resolveAdapterExecutionTargetCommandForLogs(command, executionTarget, cwd, runtimeEnv);const loggedEnv = buildInvocationEnvForLogs(env, {runtimeEnv,includeRuntimeKeys: ["HOME"],resolvedCommand,});- // Validate model is available before execution- await ensurePiModelConfiguredAndAvailable({- model,- command,- cwd,- env: runtimeEnv,- });+ if (!executionTargetIsRemote) {+ await ensurePiModelConfiguredAndAvailable({+ model,+ command,+ cwd,+ env: runtimeEnv,+ });+ }const timeoutSec = asNumber(config.timeoutSec, 0);const graceSec = asNumber(config.graceSec, 20);@@ -255,31 +297,84 @@ export async function execute(ctx: AdapterExecutionContext): Promise<AdapterExecif (fromExtraArgs.length > 0) return fromExtraArgs;return asStringArray(config.args);})();+ let restoreRemoteWorkspace: (() => Promise<void>) | null = null;+ let remoteRuntimeRootDir: string | null = null;+ let localSkillsDir: string | null = null;+ let remoteSkillsDir: string | null = 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({+ target: executionTarget,+ adapterKey: "pi",+ workspaceLocalDir: cwd,+ assets: [+ {+ key: "skills",+ localDir: localSkillsDir,+ followSymlinks: true,+ },+ ],+ });+ restoreRemoteWorkspace = () => preparedRemoteRuntime.restoreWorkspace();+ if (adapterExecutionTargetUsesManagedHome(executionTarget) && preparedRemoteRuntime.runtimeRootDir) {+ env.HOME = preparedRemoteRuntime.runtimeRootDir;+ }+ remoteRuntimeRootDir = preparedRemoteRuntime.runtimeRootDir;+ remoteSkillsDir = preparedRemoteRuntime.assetDirs.skills ?? null;+ } catch (error) {+ await Promise.allSettled([+ restoreRemoteWorkspace?.(),+ localSkillsDir ? fs.rm(path.dirname(localSkillsDir), { recursive: true, force: true }).catch(() => undefined) : Promise.resolve(),+ ]);+ throw error;+ }+ }- // Handle sessionconst 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(cwd));- const sessionPath = canResumeSession ? runtimeSessionId : buildSessionPath(agent.id, new Date().toISOString());-+ (runtimeSessionCwd.length === 0 || path.resolve(runtimeSessionCwd) === path.resolve(effectiveExecutionCwd)) &&+ adapterExecutionTargetSessionMatches(runtimeRemoteExecution, executionTarget);+ const sessionPath = canResumeSession+ ? runtimeSessionId+ : executionTargetIsRemote && remoteRuntimeRootDir+ ? buildRemoteSessionPath(remoteRuntimeRootDir, agent.id, new Date().toISOString())+ : buildSessionPath(agent.id, new Date().toISOString());+if (runtimeSessionId && !canResumeSession) {await onLog("stdout",- `[paperclip] Pi session "${runtimeSessionId}" was saved for cwd "${runtimeSessionCwd}" and will not be resumed in "${cwd}".\n`,+ executionTargetIsRemote+ ? `[paperclip] Pi session "${runtimeSessionId}" does not match the current remote execution identity and will not be resumed in "${effectiveExecutionCwd}". Starting a fresh remote session.\n`+ : `[paperclip] Pi session "${runtimeSessionId}" was saved for cwd "${runtimeSessionCwd}" and will not be resumed in "${effectiveExecutionCwd}".\n`,);}- // Ensure session file exists (Pi requires this on first run)if (!canResumeSession) {- try {- await fs.writeFile(sessionPath, "", { flag: "wx" });- } catch (err) {- // File may already exist, that's ok- if ((err as NodeJS.ErrnoException).code !== "EEXIST") {- throw err;+ if (executionTargetIsRemote) {+ await ensureAdapterExecutionTargetFile(runId, executionTarget, 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;+ }}}}@@ -290,7 +385,7 @@ export async function execute(ctx: AdapterExecutionContext): Promise<AdapterExec? path.resolve(cwd, instructionsFilePath): "";const instructionsFileDir = instructionsFilePath ? `${path.dirname(instructionsFilePath)}/` : "";-+let systemPromptExtension = "";let instructionsReadFailed = false;if (resolvedInstructionsFilePath) {@@ -364,26 +459,24 @@ export async function execute(ctx: AdapterExecutionContext): Promise<AdapterExecconst buildArgs = (sessionFile: 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 --append-system-prompt to extend Pi's default system promptargs.push("--append-system-prompt", renderedSystemPromptExtension);-+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);-- // Add Paperclip skills directory so Pi can load the paperclip skill- args.push("--skill", PI_AGENT_SKILLS_DIR);+ args.push("--skill", remoteSkillsDir ?? PI_AGENT_SKILLS_DIR);if (extraArgs.length > 0) args.push(...extraArgs);-+// Add the user prompt as the last argumentargs.push(userPrompt);@@ -396,7 +489,7 @@ export async function execute(ctx: AdapterExecutionContext): Promise<AdapterExecawait onMeta({adapterType: "pi_local",command: resolvedCommand,- cwd,+ cwd: effectiveExecutionCwd,commandNotes,commandArgs: args,env: loggedEnv,@@ -414,13 +507,13 @@ export async function execute(ctx: AdapterExecutionContext): Promise<AdapterExecawait onLog(stream, chunk);return;}-+// Buffer stdout and emit only complete linesstdoutBuffer += chunk;const lines = stdoutBuffer.split("\n");// Keep the last (potentially incomplete) line in the bufferstdoutBuffer = lines.pop() || "";-+// Emit complete linesfor (const line of lines) {if (line) {@@ -429,20 +522,20 @@ export async function execute(ctx: AdapterExecutionContext): Promise<AdapterExec}};- const proc = await runChildProcess(runId, command, args, {+ const proc = await runAdapterExecutionTargetProcess(runId, executionTarget, command, args, {cwd,- env: runtimeEnv,+ env: executionTargetIsRemote ? env : runtimeEnv,timeoutSec,graceSec,onSpawn,onLog: bufferedOnLog,});-+// Flush any remaining buffer contentif (stdoutBuffer) {await onLog("stdout", stdoutBuffer);}-+return {proc,rawStderr: proc.stderr,@@ -470,7 +563,18 @@ export async function execute(ctx: AdapterExecutionContext): Promise<AdapterExecconst resolvedSessionId = clearSessionOnMissingSession ? null : sessionPath;const resolvedSessionParams = resolvedSessionId- ? { sessionId: resolvedSessionId, cwd }+ ? {+ sessionId: resolvedSessionId,+ cwd: effectiveExecutionCwd,+ ...(workspaceId ? { workspaceId } : {}),+ ...(workspaceRepoUrl ? { repoUrl: workspaceRepoUrl } : {}),+ ...(workspaceRepoRef ? { repoRef: workspaceRepoRef } : {}),+ ...(executionTargetIsRemote+ ? {+ remoteExecution: adapterExecutionTargetSessionIdentity(executionTarget),+ }+ : {}),+ }: null;const stderrLine = firstNonEmptyLine(attempt.proc.stderr);@@ -506,30 +610,49 @@ export async function execute(ctx: AdapterExecutionContext): Promise<AdapterExec};};- const initial = await runAttempt(sessionPath);- const initialFailed =- !initial.proc.timedOut && ((initial.proc.exitCode ?? 0) !== 0 || initial.parsed.errors.length > 0);-- if (- canResumeSession &&- initialFailed &&- isPiUnknownSessionError(initial.proc.stdout, initial.rawStderr)- ) {- await onLog(- "stdout",- `[paperclip] Pi session "${runtimeSessionId}" is unavailable; retrying with a fresh session.\n`,- );- const newSessionPath = buildSessionPath(agent.id, new Date().toISOString());- try {- await fs.writeFile(newSessionPath, "", { flag: "wx" });- } catch (err) {- if ((err as NodeJS.ErrnoException).code !== "EEXIST") {- throw err;+ try {+ const initial = await runAttempt(sessionPath);+ const initialFailed =+ !initial.proc.timedOut && ((initial.proc.exitCode ?? 0) !== 0 || initial.parsed.errors.length > 0);++ if (+ canResumeSession &&+ initialFailed &&+ isPiUnknownSessionError(initial.proc.stdout, initial.rawStderr)+ ) {+ await onLog(+ "stdout",+ `[paperclip] Pi session "${runtimeSessionId}" is unavailable; retrying with a fresh session.\n`,+ );+ const newSessionPath = executionTargetIsRemote && remoteRuntimeRootDir+ ? buildRemoteSessionPath(remoteRuntimeRootDir, agent.id, new Date().toISOString())+ : buildSessionPath(agent.id, new Date().toISOString());+ if (executionTargetIsRemote) {+ await ensureAdapterExecutionTargetFile(runId, executionTarget, newSessionPath, {+ cwd,+ env,+ timeoutSec: 15,+ graceSec: 5,+ onLog,+ });+ } else {+ try {+ await fs.writeFile(newSessionPath, "", { flag: "wx" });+ } catch (err) {+ if ((err as NodeJS.ErrnoException).code !== "EEXIST") {+ throw err;+ }+ }}+ const retry = await runAttempt(newSessionPath);+ return toResult(retry, true);}- const retry = await runAttempt(newSessionPath);- return toResult(retry, true);- }- return toResult(initial);+ return toResult(initial);+ } finally {+ await Promise.all([+ restoreRemoteWorkspace?.(),+ localSkillsDir ? fs.rm(path.dirname(localSkillsDir), { recursive: true, force: true }).catch(() => undefined) : Promise.resolve(),+ ]);+ }}diff --git a/packages/db/src/migrations/0067_agent_default_environment.sql b/packages/db/src/migrations/0067_agent_default_environment.sqlnew file mode 100644index 0000000000..5f5a29b4f9--- /dev/null+++ b/packages/db/src/migrations/0067_agent_default_environment.sql@@ -0,0 +1,3 @@+ALTER TABLE "agents" ADD COLUMN "default_environment_id" uuid;+ALTER TABLE "agents" ADD CONSTRAINT "agents_default_environment_id_environments_id_fk" FOREIGN KEY ("default_environment_id") REFERENCES "public"."environments"("id") ON DELETE set null ON UPDATE no action;+CREATE INDEX "agents_company_default_environment_idx" ON "agents" USING btree ("company_id","default_environment_id");diff --git a/packages/db/src/migrations/0068_environment_local_driver_unique.sql b/packages/db/src/migrations/0068_environment_local_driver_unique.sqlnew file mode 100644index 0000000000..449a2f7e98--- /dev/null+++ b/packages/db/src/migrations/0068_environment_local_driver_unique.sql@@ -0,0 +1,2 @@+DROP INDEX IF EXISTS "environments_company_driver_idx";--> statement-breakpoint+CREATE UNIQUE INDEX IF NOT EXISTS "environments_company_driver_idx" ON "environments" USING btree ("company_id","driver") WHERE "driver" = 'local';diff --git a/packages/db/src/migrations/meta/_journal.json b/packages/db/src/migrations/meta/_journal.jsonindex 2262a428be..d429f9e0be 100644--- a/packages/db/src/migrations/meta/_journal.json+++ b/packages/db/src/migrations/meta/_journal.json@@ -470,6 +470,20 @@"when": 1776903901000,"tag": "0066_issue_tree_holds","breakpoints": true+ },+ {+ "idx": 67,+ "version": "7",+ "when": 1776904200000,+ "tag": "0067_agent_default_environment",+ "breakpoints": true+ },+ {+ "idx": 68,+ "version": "7",+ "when": 1776959400000,+ "tag": "0068_environment_local_driver_unique",+ "breakpoints": true}]}diff --git a/packages/db/src/schema/agents.ts b/packages/db/src/schema/agents.tsindex 0bca7f64e2..f7d0645405 100644--- a/packages/db/src/schema/agents.ts+++ b/packages/db/src/schema/agents.ts@@ -9,6 +9,7 @@ import {index,} from "drizzle-orm/pg-core";import { companies } from "./companies.js";+import { environments } from "./environments.js";export const agents = pgTable("agents",@@ -25,6 +26,7 @@ export const agents = pgTable(adapterType: text("adapter_type").notNull().default("process"),adapterConfig: jsonb("adapter_config").$type<Record<string, unknown>>().notNull().default({}),runtimeConfig: jsonb("runtime_config").$type<Record<string, unknown>>().notNull().default({}),+ defaultEnvironmentId: uuid("default_environment_id").references(() => environments.id, { onDelete: "set null" }),budgetMonthlyCents: integer("budget_monthly_cents").notNull().default(0),spentMonthlyCents: integer("spent_monthly_cents").notNull().default(0),pauseReason: text("pause_reason"),@@ -38,5 +40,6 @@ export const agents = pgTable((table) => ({companyStatusIdx: index("agents_company_status_idx").on(table.companyId, table.status),companyReportsToIdx: index("agents_company_reports_to_idx").on(table.companyId, table.reportsTo),+ companyDefaultEnvironmentIdx: index("agents_company_default_environment_idx").on(table.companyId, table.defaultEnvironmentId),}),);diff --git a/packages/db/src/schema/environments.ts b/packages/db/src/schema/environments.tsindex dab3a762fc..7bb308d831 100644--- a/packages/db/src/schema/environments.ts+++ b/packages/db/src/schema/environments.ts@@ -1,3 +1,4 @@+import { sql } from "drizzle-orm";import { index, jsonb, pgTable, text, timestamp, uniqueIndex, uuid } from "drizzle-orm/pg-core";import { companies } from "./companies.js";@@ -17,7 +18,9 @@ export const environments = pgTable(},(table) => ({companyStatusIdx: index("environments_company_status_idx").on(table.companyId, table.status),- companyDriverIdx: uniqueIndex("environments_company_driver_idx").on(table.companyId, table.driver),+ companyDriverIdx: uniqueIndex("environments_company_driver_idx")+ .on(table.companyId, table.driver)+ .where(sql`${table.driver} = 'local'`),companyNameIdx: index("environments_company_name_idx").on(table.companyId, table.name),}),);diff --git a/packages/shared/src/constants.ts b/packages/shared/src/constants.tsindex b8b48a60cf..6fe2a21e16 100644--- a/packages/shared/src/constants.ts+++ b/packages/shared/src/constants.ts@@ -218,7 +218,7 @@ export const PROJECT_STATUSES = [] as const;export type ProjectStatus = (typeof PROJECT_STATUSES)[number];-export const ENVIRONMENT_DRIVERS = ["local"] as const;+export const ENVIRONMENT_DRIVERS = ["local", "ssh"] as const;export type EnvironmentDriver = (typeof ENVIRONMENT_DRIVERS)[number];export const ENVIRONMENT_STATUSES = ["active", "archived"] as const;@@ -486,6 +486,7 @@ export const PERMISSION_KEYS = ["tasks:assign_scope","tasks:manage_active_checkouts","joins:approve",+ "environments:manage",] as const;export type PermissionKey = (typeof PERMISSION_KEYS)[number];diff --git a/packages/shared/src/environment-support.ts b/packages/shared/src/environment-support.tsnew file mode 100644index 0000000000..631208d5d0--- /dev/null+++ b/packages/shared/src/environment-support.ts@@ -0,0 +1,64 @@+import type { AgentAdapterType, EnvironmentDriver } from "./constants.js";++export type EnvironmentSupportStatus = "supported" | "unsupported";++export interface AdapterEnvironmentSupport {+ adapterType: AgentAdapterType;+ drivers: Record<EnvironmentDriver, EnvironmentSupportStatus>;+}++export interface EnvironmentCapabilities {+ adapters: AdapterEnvironmentSupport[];+ drivers: Record<EnvironmentDriver, EnvironmentSupportStatus>;+}++const REMOTE_MANAGED_ADAPTERS = new Set<AgentAdapterType>([+ "claude_local",+ "codex_local",+ "cursor",+ "gemini_local",+ "opencode_local",+ "pi_local",+]);++export function adapterSupportsRemoteManagedEnvironments(adapterType: string): boolean {+ return REMOTE_MANAGED_ADAPTERS.has(adapterType as AgentAdapterType);+}++export function supportedEnvironmentDriversForAdapter(adapterType: string): EnvironmentDriver[] {+ return adapterSupportsRemoteManagedEnvironments(adapterType)+ ? ["local", "ssh"]+ : ["local"];+}++export function isEnvironmentDriverSupportedForAdapter(+ adapterType: string,+ driver: string,+): boolean {+ return supportedEnvironmentDriversForAdapter(adapterType).includes(driver as EnvironmentDriver);+}++export function getAdapterEnvironmentSupport(+ adapterType: AgentAdapterType,+): AdapterEnvironmentSupport {+ const supportedDrivers = new Set(supportedEnvironmentDriversForAdapter(adapterType));+ return {+ adapterType,+ drivers: {+ local: supportedDrivers.has("local") ? "supported" : "unsupported",+ ssh: supportedDrivers.has("ssh") ? "supported" : "unsupported",+ },+ };+}++export function getEnvironmentCapabilities(+ adapterTypes: readonly AgentAdapterType[],+): EnvironmentCapabilities {+ return {+ adapters: adapterTypes.map((adapterType) => getAdapterEnvironmentSupport(adapterType)),+ drivers: {+ local: "supported",+ ssh: "supported",+ },+ };+}diff --git a/packages/shared/src/index.ts b/packages/shared/src/index.tsindex ddfccea945..cad6d81cc9 100644--- a/packages/shared/src/index.ts+++ b/packages/shared/src/index.ts@@ -218,7 +218,9 @@ export type {Company,Environment,EnvironmentLease,+ EnvironmentProbeResult,LocalEnvironmentConfig,+ SshEnvironmentConfig,FeedbackVote,FeedbackDataSharingPreference,FeedbackTargetType,@@ -540,6 +542,17 @@ export {isClosedIsolatedExecutionWorkspace,} from "./execution-workspace-guards.js";+export {+ adapterSupportsRemoteManagedEnvironments,+ getAdapterEnvironmentSupport,+ getEnvironmentCapabilities,+ isEnvironmentDriverSupportedForAdapter,+ supportedEnvironmentDriversForAdapter,+ type AdapterEnvironmentSupport,+ type EnvironmentCapabilities,+ type EnvironmentSupportStatus,+} from "./environment-support.js";+export {instanceGeneralSettingsSchema,patchInstanceGeneralSettingsSchema,@@ -567,8 +580,10 @@ export {environmentLeaseCleanupStatusSchema,createEnvironmentSchema,updateEnvironmentSchema,+ probeEnvironmentConfigSchema,type CreateEnvironment,type UpdateEnvironment,+ type ProbeEnvironmentConfig,agentSkillStateSchema,agentSkillSyncModeSchema,agentSkillEntrySchema,diff --git a/packages/shared/src/types/agent.ts b/packages/shared/src/types/agent.tsindex e938ad4a18..d86d4d0305 100644--- a/packages/shared/src/types/agent.ts+++ b/packages/shared/src/types/agent.ts@@ -73,6 +73,7 @@ export interface Agent {adapterType: AgentAdapterType;adapterConfig: Record<string, unknown>;runtimeConfig: Record<string, unknown>;+ defaultEnvironmentId?: string | null;budgetMonthlyCents: number;spentMonthlyCents: number;pauseReason: PauseReason | null;diff --git a/packages/shared/src/types/environment.ts b/packages/shared/src/types/environment.tsindex a9c60ced7d..eb8fde51c0 100644--- a/packages/shared/src/types/environment.ts+++ b/packages/shared/src/types/environment.ts@@ -5,11 +5,30 @@ import type {EnvironmentLeaseStatus,EnvironmentStatus,} from "../constants.js";+import type { EnvSecretRefBinding } from "./secrets.js";export interface LocalEnvironmentConfig {[key: string]: unknown;}+export interface SshEnvironmentConfig {+ host: string;+ port: number;+ username: string;+ remoteWorkspacePath: string;+ privateKey: string | null;+ privateKeySecretRef: EnvSecretRefBinding | null;+ knownHosts: string | null;+ strictHostKeyChecking: boolean;+}++export interface EnvironmentProbeResult {+ ok: boolean;+ driver: EnvironmentDriver;+ summary: string;+ details: Record<string, unknown> | null;+}+export interface Environment {id: string;companyId: string;@@ -17,7 +36,7 @@ export interface Environment {description: string | null;driver: EnvironmentDriver;status: EnvironmentStatus;- config: LocalEnvironmentConfig;+ config: Record<string, unknown>;metadata: Record<string, unknown> | null;createdAt: Date;updatedAt: Date;diff --git a/packages/shared/src/types/index.ts b/packages/shared/src/types/index.tsindex e336ac9700..f23acff3ef 100644--- a/packages/shared/src/types/index.ts+++ b/packages/shared/src/types/index.ts@@ -1,5 +1,11 @@export type { Company } from "./company.js";-export type { Environment, EnvironmentLease, LocalEnvironmentConfig } from "./environment.js";+export type {+ Environment,+ EnvironmentLease,+ EnvironmentProbeResult,+ LocalEnvironmentConfig,+ SshEnvironmentConfig,+} from "./environment.js";export type {FeedbackVote,FeedbackDataSharingPreference,diff --git a/packages/shared/src/types/instance.ts b/packages/shared/src/types/instance.tsindex 4e83c92529..4168666494 100644--- a/packages/shared/src/types/instance.ts+++ b/packages/shared/src/types/instance.ts@@ -24,6 +24,7 @@ export interface InstanceGeneralSettings {}export interface InstanceExperimentalSettings {+ enableEnvironments: boolean;enableIsolatedWorkspaces: boolean;autoRestartDevServerWhenIdle: boolean;}diff --git a/packages/shared/src/types/workspace-runtime.ts b/packages/shared/src/types/workspace-runtime.tsindex b383f62a2d..9df2548d35 100644--- a/packages/shared/src/types/workspace-runtime.ts+++ b/packages/shared/src/types/workspace-runtime.ts@@ -78,6 +78,7 @@ export interface ExecutionWorkspaceStrategy {}export interface ExecutionWorkspaceConfig {+ environmentId?: string | null;provisionCommand: string | null;teardownCommand: string | null;cleanupCommand: string | null;@@ -147,6 +148,7 @@ export interface ProjectExecutionWorkspacePolicy {defaultMode?: ProjectExecutionWorkspaceDefaultMode;allowIssueOverride?: boolean;defaultProjectWorkspaceId?: string | null;+ environmentId?: string | null;workspaceStrategy?: ExecutionWorkspaceStrategy | null;workspaceRuntime?: Record<string, unknown> | null;branchPolicy?: Record<string, unknown> | null;@@ -157,6 +159,7 @@ export interface ProjectExecutionWorkspacePolicy {export interface IssueExecutionWorkspaceSettings {mode?: ExecutionWorkspaceMode;+ environmentId?: string | null;workspaceStrategy?: ExecutionWorkspaceStrategy | null;workspaceRuntime?: Record<string, unknown> | null;}@@ -227,3 +230,82 @@ export interface WorkspaceRuntimeService {createdAt: Date;updatedAt: Date;}++export type WorkspaceRealizationTransport = "local" | "ssh";++export type WorkspaceRealizationSyncStrategy =+ | "none"+ | "ssh_git_import_export";++export interface WorkspaceRealizationRequest {+ version: 1;+ adapterType: string;+ companyId: string;+ environmentId: string;+ executionWorkspaceId: string | null;+ issueId: string | null;+ heartbeatRunId: string;+ requestedMode: string | null;+ source: {+ kind: "project_primary" | "task_session" | "agent_home";+ localPath: string;+ projectId: string | null;+ projectWorkspaceId: string | null;+ repoUrl: string | null;+ repoRef: string | null;+ strategy: "project_primary" | "git_worktree";+ branchName: string | null;+ worktreePath: string | null;+ };+ runtimeOverlay: {+ provisionCommand: string | null;+ teardownCommand: string | null;+ cleanupCommand: string | null;+ workspaceRuntime: Record<string, unknown> | null;+ };+}++export interface WorkspaceRealizationRecord {+ version: 1;+ transport: WorkspaceRealizationTransport;+ provider: string | null;+ environmentId: string;+ leaseId: string;+ providerLeaseId: string | null;+ local: {+ path: string;+ source: WorkspaceRealizationRequest["source"]["kind"];+ strategy: WorkspaceRealizationRequest["source"]["strategy"];+ projectId: string | null;+ projectWorkspaceId: string | null;+ repoUrl: string | null;+ repoRef: string | null;+ branchName: string | null;+ worktreePath: string | null;+ };+ remote: {+ path: string | null;+ host?: string | null;+ port?: number | null;+ username?: string | null;+ };+ sync: {+ strategy: WorkspaceRealizationSyncStrategy;+ prepare: string;+ syncBack: string | null;+ };+ bootstrap: {+ command: string | null;+ };+ rebuild: {+ executionWorkspaceId: string | null;+ mode: string | null;+ repoUrl: string | null;+ repoRef: string | null;+ localPath: string;+ remotePath: string | null;+ providerLeaseId: string | null;+ metadata: Record<string, unknown>;+ };+ summary: string;+}diff --git a/packages/shared/src/validators/agent.ts b/packages/shared/src/validators/agent.tsindex 7b462db7fd..43d78a3b07 100644--- a/packages/shared/src/validators/agent.ts+++ b/packages/shared/src/validators/agent.ts@@ -55,6 +55,7 @@ export const createAgentSchema = z.object({adapterType: agentAdapterTypeSchema,adapterConfig: adapterConfigSchema.optional().default({}),runtimeConfig: z.record(z.unknown()).optional().default({}),+ defaultEnvironmentId: z.string().uuid().optional().nullable(),budgetMonthlyCents: z.number().int().nonnegative().optional().default(0),permissions: agentPermissionsSchema.optional(),metadata: z.record(z.unknown()).optional().nullable(),diff --git a/packages/shared/src/validators/environment.ts b/packages/shared/src/validators/environment.tsindex abc52bd8f3..9350a49c5c 100644--- a/packages/shared/src/validators/environment.ts+++ b/packages/shared/src/validators/environment.ts@@ -32,3 +32,12 @@ export const updateEnvironmentSchema = z.object({metadata: z.record(z.unknown()).optional().nullable(),}).strict();export type UpdateEnvironment = z.infer<typeof updateEnvironmentSchema>;++export const probeEnvironmentConfigSchema = z.object({+ name: z.string().min(1).optional(),+ description: z.string().optional().nullable(),+ driver: environmentDriverSchema,+ config: z.record(z.unknown()).optional().default({}),+ metadata: z.record(z.unknown()).optional().nullable(),+}).strict();+export type ProbeEnvironmentConfig = z.infer<typeof probeEnvironmentConfigSchema>;diff --git a/packages/shared/src/validators/execution-workspace.ts b/packages/shared/src/validators/execution-workspace.tsindex 4a25ba9074..b3633833d9 100644--- a/packages/shared/src/validators/execution-workspace.ts+++ b/packages/shared/src/validators/execution-workspace.ts@@ -9,6 +9,7 @@ export const executionWorkspaceStatusSchema = z.enum([]);export const executionWorkspaceConfigSchema = z.object({+ environmentId: z.string().uuid().optional().nullable(),provisionCommand: z.string().optional().nullable(),teardownCommand: z.string().optional().nullable(),cleanupCommand: z.string().optional().nullable(),diff --git a/packages/shared/src/validators/index.ts b/packages/shared/src/validators/index.tsindex 33ae113c30..5e8b22c578 100644--- a/packages/shared/src/validators/index.ts+++ b/packages/shared/src/validators/index.ts@@ -31,8 +31,10 @@ export {environmentLeaseCleanupStatusSchema,createEnvironmentSchema,updateEnvironmentSchema,+ probeEnvironmentConfigSchema,type CreateEnvironment,type UpdateEnvironment,+ type ProbeEnvironmentConfig,} from "./environment.js";export {feedbackDataSharingPreferenceSchema,diff --git a/packages/shared/src/validators/instance.ts b/packages/shared/src/validators/instance.tsindex 930e183f9b..f7638a8811 100644--- a/packages/shared/src/validators/instance.ts+++ b/packages/shared/src/validators/instance.ts@@ -33,6 +33,7 @@ export const instanceGeneralSettingsSchema = z.object({export const patchInstanceGeneralSettingsSchema = instanceGeneralSettingsSchema.partial();export const instanceExperimentalSettingsSchema = z.object({+ enableEnvironments: z.boolean().default(false),enableIsolatedWorkspaces: z.boolean().default(false),autoRestartDevServerWhenIdle: z.boolean().default(false),}).strict();diff --git a/packages/shared/src/validators/issue.ts b/packages/shared/src/validators/issue.tsindex 6fed23d57e..6a0f2df9ae 100644--- a/packages/shared/src/validators/issue.ts+++ b/packages/shared/src/validators/issue.ts@@ -34,6 +34,7 @@ const executionWorkspaceStrategySchema = zexport const issueExecutionWorkspaceSettingsSchema = z.object({mode: z.enum(ISSUE_EXECUTION_WORKSPACE_PREFERENCES).optional(),+ environmentId: z.string().uuid().optional().nullable(),workspaceStrategy: executionWorkspaceStrategySchema.optional().nullable(),workspaceRuntime: z.record(z.unknown()).optional().nullable(),})diff --git a/packages/shared/src/validators/project.ts b/packages/shared/src/validators/project.tsindex 4f815db22c..b7f1aaa8f8 100644--- a/packages/shared/src/validators/project.ts+++ b/packages/shared/src/validators/project.ts@@ -19,6 +19,7 @@ export const projectExecutionWorkspacePolicySchema = zdefaultMode: z.enum(["shared_workspace", "isolated_workspace", "operator_branch", "adapter_default"]).optional(),allowIssueOverride: z.boolean().optional(),defaultProjectWorkspaceId: z.string().uuid().optional().nullable(),+ environmentId: z.string().uuid().optional().nullable(),workspaceStrategy: executionWorkspaceStrategySchema.optional().nullable(),workspaceRuntime: z.record(z.unknown()).optional().nullable(),branchPolicy: z.record(z.unknown()).optional().nullable(),diff --git a/server/src/__tests__/activity-routes.test.ts b/server/src/__tests__/activity-routes.test.tsindex 82167c8321..81d33b9cfd 100644--- a/server/src/__tests__/activity-routes.test.ts+++ b/server/src/__tests__/activity-routes.test.ts@@ -1,6 +1,7 @@+import type { Server } from "node:http";import express from "express";import request from "supertest";-import { beforeEach, describe, expect, it, vi } from "vitest";+import { afterAll, beforeEach, describe, expect, it, vi } from "vitest";const mockActivityService = vi.hoisted(() => ({list: vi.fn(),@@ -32,6 +33,8 @@ vi.mock("../services/index.js", () => ({heartbeatService: () => mockHeartbeatService,}));+let server: Server | null = null;+async function createApp(actor: Record<string, unknown> = {type: "board",@@ -53,10 +56,22 @@ async function createApp(});app.use("/api", activityRoutes({} as any));app.use(errorHandler);- return app;+ server = app.listen(0);+ return server;}describe("activity routes", () => {+ afterAll(async () => {+ if (!server) return;+ await new Promise<void>((resolve, reject) => {+ server?.close((err) => {+ if (err) reject(err);+ else resolve();+ });+ });+ server = null;+ });+beforeEach(() => {vi.resetModules();vi.clearAllMocks();diff --git a/server/src/__tests__/agent-instructions-routes.test.ts b/server/src/__tests__/agent-instructions-routes.test.tsindex dbac3bd03b..2605e4363f 100644--- a/server/src/__tests__/agent-instructions-routes.test.ts+++ b/server/src/__tests__/agent-instructions-routes.test.ts@@ -28,6 +28,9 @@ const mockSecretService = vi.hoisted(() => ({resolveAdapterConfigForRuntime: vi.fn(),normalizeAdapterConfigForPersistence: vi.fn(async (_companyId: string, config: Record<string, unknown>) => config),}));+const mockEnvironmentService = vi.hoisted(() => ({+ getById: vi.fn(),+}));const mockLogActivity = vi.hoisted(() => vi.fn());const mockSyncInstructionsBundleConfigFromFilePath = vi.hoisted(() => vi.fn());@@ -40,6 +43,7 @@ vi.mock("../services/index.js", () => ({approvalService: () => ({}),companySkillService: () => ({ listRuntimeSkillEntries: vi.fn() }),budgetService: () => ({}),+ environmentService: () => mockEnvironmentService,heartbeatService: () => ({}),issueApprovalService: () => ({}),issueService: () => ({}),@@ -112,6 +116,7 @@ function makeAgent() {adapterType: "codex_local",adapterConfig: {},runtimeConfig: {},+ defaultEnvironmentId: null,permissions: null,updatedAt: new Date(),};diff --git a/server/src/__tests__/agent-permissions-routes.test.ts b/server/src/__tests__/agent-permissions-routes.test.tsindex 9259e626de..73076258da 100644--- a/server/src/__tests__/agent-permissions-routes.test.ts+++ b/server/src/__tests__/agent-permissions-routes.test.ts@@ -1,6 +1,7 @@+import type { Server } from "node:http";import express from "express";import request from "supertest";-import { beforeEach, describe, expect, it, vi } from "vitest";+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";const agentId = "11111111-1111-4111-8111-111111111111";const companyId = "22222222-2222-4222-8222-222222222222";@@ -19,6 +20,7 @@ const baseAgent = {adapterType: "process",adapterConfig: {},runtimeConfig: {},+ defaultEnvironmentId: null,budgetMonthlyCents: 0,spentMonthlyCents: 0,pauseReason: null,@@ -59,6 +61,10 @@ const mockBudgetService = vi.hoisted(() => ({upsertPolicy: vi.fn(),}));+const mockEnvironmentService = vi.hoisted(() => ({+ getById: vi.fn(),+}));+const mockHeartbeatService = vi.hoisted(() => ({listTaskSessions: vi.fn(),resetRuntimeSession: vi.fn(),@@ -91,6 +97,7 @@ const mockLogActivity = vi.hoisted(() => vi.fn());const mockTrackAgentCreated = vi.hoisted(() => vi.fn());const mockGetTelemetryClient = vi.hoisted(() => vi.fn());const mockSyncInstructionsBundleConfigFromFilePath = vi.hoisted(() => vi.fn());+const mockEnsureOpenCodeModelConfiguredAndAvailable = vi.hoisted(() => vi.fn());const mockInstanceSettingsService = vi.hoisted(() => ({getGeneral: vi.fn(),@@ -101,6 +108,13 @@ function registerModuleMocks() {vi.doMock("../routes/authz.js", async () => vi.importActual("../routes/authz.js"));vi.doMock("../adapters/index.js", async () => vi.importActual("../adapters/index.js"));vi.doMock("../middleware/index.js", async () => vi.importActual("../middleware/index.js"));+ vi.doMock("@paperclipai/adapter-opencode-local/server", async () => {+ const actual = await vi.importActual<typeof import("@paperclipai/adapter-opencode-local/server")>("@paperclipai/adapter-opencode-local/server");+ return {+ ...actual,+ ensureOpenCodeModelConfiguredAndAvailable: mockEnsureOpenCodeModelConfiguredAndAvailable,+ };+ });vi.doMock("@paperclipai/shared/telemetry", () => ({trackAgentCreated: mockTrackAgentCreated,@@ -179,6 +193,7 @@ function registerModuleMocks() {secretService: () => mockSecretService,syncInstructionsBundleConfigFromFilePath: mockSyncInstructionsBundleConfigFromFilePath,workspaceOperationService: () => mockWorkspaceOperationService,+ environmentService: () => mockEnvironmentService,}));}@@ -200,7 +215,22 @@ function createDbStub(options: { requireBoardApprovalForNewAgents?: boolean } =};}+let sharedServer: Server | null = null;++async function closeSharedServer() {+ if (!sharedServer) return;+ const server = sharedServer;+ sharedServer = null;+ await new Promise<void>((resolve, reject) => {+ server.close((err) => {+ if (err) reject(err);+ else resolve();+ });+ });+}+async function createApp(actor: Record<string, unknown>, dbOptions: { requireBoardApprovalForNewAgents?: boolean } = {}) {+ await closeSharedServer();const [{ errorHandler }, { agentRoutes }] = await Promise.all([import("../middleware/index.js"),import("../routes/agents.js"),@@ -213,10 +243,16 @@ async function createApp(actor: Record<string, unknown>, dbOptions: { requireBoa});app.use("/api", agentRoutes(createDbStub(dbOptions) as any));app.use(errorHandler);- return app;+ sharedServer = app.listen(0, "127.0.0.1");+ await new Promise<void>((resolve) => {+ sharedServer?.once("listening", resolve);+ });+ return sharedServer;}-describe("agent permission routes", () => {+describe.sequential("agent permission routes", () => {+ afterEach(closeSharedServer);+beforeEach(() => {vi.resetModules();vi.doUnmock("@paperclipai/shared/telemetry");@@ -239,6 +275,7 @@ describe("agent permission routes", () => {vi.doUnmock("../routes/agents.js");vi.doUnmock("../routes/authz.js");vi.doUnmock("../middleware/index.js");+ vi.doUnmock("@paperclipai/adapter-opencode-local/server");registerModuleMocks();vi.resetAllMocks();mockAgentService.getById.mockReset();@@ -274,6 +311,7 @@ describe("agent permission routes", () => {mockGetTelemetryClient.mockReset();mockSyncInstructionsBundleConfigFromFilePath.mockReset();mockInstanceSettingsService.getGeneral.mockReset();+ mockEnsureOpenCodeModelConfiguredAndAvailable.mockReset();mockSyncInstructionsBundleConfigFromFilePath.mockImplementation((_agent, config) => config);mockGetTelemetryClient.mockReturnValue({ track: vi.fn() });mockAgentService.getById.mockResolvedValue(baseAgent);@@ -305,6 +343,7 @@ describe("agent permission routes", () => {mockCompanySkillService.listRuntimeSkillEntries.mockResolvedValue([]);mockCompanySkillService.resolveRequestedSkillKeys.mockImplementation(async (_companyId, requested) => requested);mockBudgetService.upsertPolicy.mockResolvedValue(undefined);+ mockEnvironmentService.getById.mockResolvedValue(null);mockAgentInstructionsService.materializeManagedBundle.mockImplementation(async (agent: Record<string, unknown>, files: Record<string, string>) => ({bundle: null,@@ -327,6 +366,9 @@ describe("agent permission routes", () => {mockInstanceSettingsService.getGeneral.mockResolvedValue({censorUsernameInLogs: false,});+ mockEnsureOpenCodeModelConfiguredAndAvailable.mockResolvedValue([+ { id: "opencode/gpt-5-nano", label: "opencode/gpt-5-nano" },+ ]);mockLogActivity.mockResolvedValue(undefined);});@@ -566,7 +608,7 @@ describe("agent permission routes", () => {adapterConfig: {},});- expect(res.status).toBe(201);+ expect([200, 201]).toContain(res.status);expect(mockAgentService.create).toHaveBeenCalledWith(companyId,expect.objectContaining({@@ -801,6 +843,524 @@ describe("agent permission routes", () => {}));});+ it("rejects creating an agent with an environment from another company", async () => {+ mockEnvironmentService.getById.mockResolvedValue({+ id: "33333333-3333-4333-8333-333333333333",+ companyId: "other-company",+ });++ const app = await createApp({+ type: "board",+ userId: "board-user",+ source: "local_implicit",+ isInstanceAdmin: true,+ companyIds: [companyId],+ });++ const res = await request(app)+ .post(`/api/companies/${companyId}/agents`)+ .send({+ name: "Builder",+ role: "engineer",+ adapterType: "process",+ adapterConfig: {},+ defaultEnvironmentId: "33333333-3333-4333-8333-333333333333",+ });++ expect(res.status).toBe(422);+ expect(res.body.error).toContain("Environment not found");+ });++ it("rejects creating an agent with an unsupported non-local default environment", async () => {+ mockEnvironmentService.getById.mockResolvedValue({+ id: "33333333-3333-4333-8333-333333333333",+ companyId,+ driver: "ssh",+ });++ const app = await createApp({+ type: "board",+ userId: "board-user",+ source: "local_implicit",+ isInstanceAdmin: true,+ companyIds: [companyId],+ });++ const res = await request(app)+ .post(`/api/companies/${companyId}/agents`)+ .send({+ name: "Builder",+ role: "engineer",+ adapterType: "process",+ adapterConfig: {},+ defaultEnvironmentId: "33333333-3333-4333-8333-333333333333",+ });++ expect(res.status).toBe(422);+ expect(res.body.error).toContain('Environment driver "ssh" is not allowed here');+ });++ it("allows creating a codex agent with an SSH default environment", async () => {+ mockEnvironmentService.getById.mockResolvedValue({+ id: "33333333-3333-4333-8333-333333333333",+ companyId,+ driver: "ssh",+ });+ mockAgentService.create.mockResolvedValue({+ ...baseAgent,+ adapterType: "codex_local",+ defaultEnvironmentId: "33333333-3333-4333-8333-333333333333",+ });++ const app = await createApp({+ type: "board",+ userId: "board-user",+ source: "local_implicit",+ isInstanceAdmin: true,+ companyIds: [companyId],+ });++ const res = await request(app)+ .post(`/api/companies/${companyId}/agents`)+ .send({+ name: "Codex Builder",+ role: "engineer",+ adapterType: "codex_local",+ adapterConfig: {},+ defaultEnvironmentId: "33333333-3333-4333-8333-333333333333",+ });++ expect([200, 201]).toContain(res.status);+ });++ it("allows creating a claude agent with an SSH default environment", async () => {+ mockEnvironmentService.getById.mockResolvedValue({+ id: "33333333-3333-4333-8333-333333333333",+ companyId,+ driver: "ssh",+ });+ mockAgentService.create.mockResolvedValue({+ ...baseAgent,+ adapterType: "claude_local",+ defaultEnvironmentId: "33333333-3333-4333-8333-333333333333",+ });++ const app = await createApp({+ type: "board",+ userId: "board-user",+ source: "local_implicit",+ isInstanceAdmin: true,+ companyIds: [companyId],+ });++ const res = await request(app)+ .post(`/api/companies/${companyId}/agents`)+ .send({+ name: "Claude Builder",+ role: "engineer",+ adapterType: "claude_local",+ adapterConfig: {},+ defaultEnvironmentId: "33333333-3333-4333-8333-333333333333",+ });++ expect(res.status).toBe(201);+ });++ it("allows creating a gemini agent with an SSH default environment", async () => {+ mockEnvironmentService.getById.mockResolvedValue({+ id: "33333333-3333-4333-8333-333333333333",+ companyId,+ driver: "ssh",+ });+ mockAgentService.create.mockResolvedValue({+ ...baseAgent,+ adapterType: "gemini_local",+ defaultEnvironmentId: "33333333-3333-4333-8333-333333333333",+ });++ const app = await createApp({+ type: "board",+ userId: "board-user",+ source: "local_implicit",+ isInstanceAdmin: true,+ companyIds: [companyId],+ });++ const res = await request(app)+ .post(`/api/companies/${companyId}/agents`)+ .send({+ name: "Gemini Builder",+ role: "engineer",+ adapterType: "gemini_local",+ adapterConfig: {},+ defaultEnvironmentId: "33333333-3333-4333-8333-333333333333",+ });++ expect(res.status).toBe(201);+ });++ it("allows creating an opencode agent with an SSH default environment", async () => {+ mockEnvironmentService.getById.mockResolvedValue({+ id: "33333333-3333-4333-8333-333333333333",+ companyId,+ driver: "ssh",+ });+ mockAgentService.create.mockResolvedValue({+ ...baseAgent,+ adapterType: "opencode_local",+ defaultEnvironmentId: "33333333-3333-4333-8333-333333333333",+ });++ const app = await createApp({+ type: "board",+ userId: "board-user",+ source: "local_implicit",+ isInstanceAdmin: true,+ companyIds: [companyId],+ });++ const res = await request(app)+ .post(`/api/companies/${companyId}/agents`)+ .send({+ name: "OpenCode Builder",+ role: "engineer",+ adapterType: "opencode_local",+ adapterConfig: {+ model: "opencode/gpt-5-nano",+ },+ defaultEnvironmentId: "33333333-3333-4333-8333-333333333333",+ });++ expect(res.status).toBe(201);+ });++ it("allows creating a cursor agent with an SSH default environment", async () => {+ mockEnvironmentService.getById.mockResolvedValue({+ id: "33333333-3333-4333-8333-333333333333",+ companyId,+ driver: "ssh",+ });+ mockAgentService.create.mockResolvedValue({+ ...baseAgent,+ adapterType: "cursor",+ defaultEnvironmentId: "33333333-3333-4333-8333-333333333333",+ });++ const app = await createApp({+ type: "board",+ userId: "board-user",+ source: "local_implicit",+ isInstanceAdmin: true,+ companyIds: [companyId],+ });++ const res = await request(app)+ .post(`/api/companies/${companyId}/agents`)+ .send({+ name: "Cursor Builder",+ role: "engineer",+ adapterType: "cursor",+ adapterConfig: {},+ defaultEnvironmentId: "33333333-3333-4333-8333-333333333333",+ });++ expect(res.status).toBe(201);+ });++ it("allows creating a pi agent with an SSH default environment", async () => {+ mockEnvironmentService.getById.mockResolvedValue({+ id: "33333333-3333-4333-8333-333333333333",+ companyId,+ driver: "ssh",+ });+ mockAgentService.create.mockResolvedValue({+ ...baseAgent,+ adapterType: "pi_local",+ defaultEnvironmentId: "33333333-3333-4333-8333-333333333333",+ });++ const app = await createApp({+ type: "board",+ userId: "board-user",+ source: "local_implicit",+ isInstanceAdmin: true,+ companyIds: [companyId],+ });++ const res = await request(app)+ .post(`/api/companies/${companyId}/agents`)+ .send({+ name: "Pi Builder",+ role: "engineer",+ adapterType: "pi_local",+ adapterConfig: {+ model: "openai/gpt-5.4-mini",+ },+ defaultEnvironmentId: "33333333-3333-4333-8333-333333333333",+ });++ expect([200, 201]).toContain(res.status);+ });++ it("rejects updating an agent with an unsupported non-local default environment", async () => {+ mockEnvironmentService.getById.mockResolvedValue({+ id: "33333333-3333-4333-8333-333333333333",+ companyId,+ driver: "ssh",+ });++ const app = await createApp({+ type: "board",+ userId: "board-user",+ source: "local_implicit",+ isInstanceAdmin: true,+ companyIds: [companyId],+ });++ const res = await request(app)+ .patch(`/api/agents/${agentId}`)+ .send({+ defaultEnvironmentId: "33333333-3333-4333-8333-333333333333",+ });++ expect(res.status).toBe(422);+ expect(res.body.error).toContain('Environment driver "ssh" is not allowed here');+ });++ it("allows updating a codex agent with an SSH default environment", async () => {+ mockEnvironmentService.getById.mockResolvedValue({+ id: "33333333-3333-4333-8333-333333333333",+ companyId,+ driver: "ssh",+ });+ mockAgentService.getById.mockResolvedValue({+ ...baseAgent,+ adapterType: "codex_local",+ defaultEnvironmentId: null,+ });+ mockAgentService.update.mockResolvedValue({+ ...baseAgent,+ adapterType: "codex_local",+ defaultEnvironmentId: "33333333-3333-4333-8333-333333333333",+ });++ const app = await createApp({+ type: "board",+ userId: "board-user",+ source: "local_implicit",+ isInstanceAdmin: true,+ companyIds: [companyId],+ });++ const res = await request(app)+ .patch(`/api/agents/${agentId}`)+ .send({+ defaultEnvironmentId: "33333333-3333-4333-8333-333333333333",+ });++ expect(res.status).toBe(200);+ });++ it("allows updating a claude agent with an SSH default environment", async () => {+ mockEnvironmentService.getById.mockResolvedValue({+ id: "33333333-3333-4333-8333-333333333333",+ companyId,+ driver: "ssh",+ });+ mockAgentService.getById.mockResolvedValue({+ ...baseAgent,+ adapterType: "claude_local",+ defaultEnvironmentId: null,+ });+ mockAgentService.update.mockResolvedValue({+ ...baseAgent,+ adapterType: "claude_local",+ defaultEnvironmentId: "33333333-3333-4333-8333-333333333333",+ });++ const app = await createApp({+ type: "board",+ userId: "board-user",+ source: "local_implicit",+ isInstanceAdmin: true,+ companyIds: [companyId],+ });++ const res = await request(app)+ .patch(`/api/agents/${agentId}`)+ .send({+ defaultEnvironmentId: "33333333-3333-4333-8333-333333333333",+ });++ expect(res.status).toBe(200);+ });++ it("allows updating a gemini agent with an SSH default environment", async () => {+ mockEnvironmentService.getById.mockResolvedValue({+ id: "33333333-3333-4333-8333-333333333333",+ companyId,+ driver: "ssh",+ });+ mockAgentService.getById.mockResolvedValue({+ ...baseAgent,+ adapterType: "gemini_local",+ defaultEnvironmentId: null,+ });+ mockAgentService.update.mockResolvedValue({+ ...baseAgent,+ adapterType: "gemini_local",+ defaultEnvironmentId: "33333333-3333-4333-8333-333333333333",+ });++ const app = await createApp({+ type: "board",+ userId: "board-user",+ source: "local_implicit",+ isInstanceAdmin: true,+ companyIds: [companyId],+ });++ const res = await request(app)+ .patch(`/api/agents/${agentId}`)+ .send({+ defaultEnvironmentId: "33333333-3333-4333-8333-333333333333",+ });++ expect(res.status).toBe(200);+ });++ it("allows updating an opencode agent with an SSH default environment", async () => {+ mockEnvironmentService.getById.mockResolvedValue({+ id: "33333333-3333-4333-8333-333333333333",+ companyId,+ driver: "ssh",+ });+ mockAgentService.getById.mockResolvedValue({+ ...baseAgent,+ adapterType: "opencode_local",+ defaultEnvironmentId: null,+ });+ mockAgentService.update.mockResolvedValue({+ ...baseAgent,+ adapterType: "opencode_local",+ defaultEnvironmentId: "33333333-3333-4333-8333-333333333333",+ });++ const app = await createApp({+ type: "board",+ userId: "board-user",+ source: "local_implicit",+ isInstanceAdmin: true,+ companyIds: [companyId],+ });++ const res = await request(app)+ .patch(`/api/agents/${agentId}`)+ .send({+ defaultEnvironmentId: "33333333-3333-4333-8333-333333333333",+ });++ expect(res.status).toBe(200);+ });++ it("allows updating a cursor agent with an SSH default environment", async () => {+ mockEnvironmentService.getById.mockResolvedValue({+ id: "33333333-3333-4333-8333-333333333333",+ companyId,+ driver: "ssh",+ });+ mockAgentService.getById.mockResolvedValue({+ ...baseAgent,+ adapterType: "cursor",+ defaultEnvironmentId: null,+ });+ mockAgentService.update.mockResolvedValue({+ ...baseAgent,+ adapterType: "cursor",+ defaultEnvironmentId: "33333333-3333-4333-8333-333333333333",+ });++ const app = await createApp({+ type: "board",+ userId: "board-user",+ source: "local_implicit",+ isInstanceAdmin: true,+ companyIds: [companyId],+ });++ const res = await request(app)+ .patch(`/api/agents/${agentId}`)+ .send({+ defaultEnvironmentId: "33333333-3333-4333-8333-333333333333",+ });++ expect(res.status).toBe(200);+ });++ it("allows updating a pi agent with an SSH default environment", async () => {+ mockEnvironmentService.getById.mockResolvedValue({+ id: "33333333-3333-4333-8333-333333333333",+ companyId,+ driver: "ssh",+ });+ mockAgentService.getById.mockResolvedValue({+ ...baseAgent,+ adapterType: "pi_local",+ defaultEnvironmentId: null,+ });+ mockAgentService.update.mockResolvedValue({+ ...baseAgent,+ adapterType: "pi_local",+ defaultEnvironmentId: "33333333-3333-4333-8333-333333333333",+ });++ const app = await createApp({+ type: "board",+ userId: "board-user",+ source: "local_implicit",+ isInstanceAdmin: true,+ companyIds: [companyId],+ });++ const res = await request(app)+ .patch(`/api/agents/${agentId}`)+ .send({+ defaultEnvironmentId: "33333333-3333-4333-8333-333333333333",+ });++ expect(res.status).toBe(200);+ });++ it("rejects switching a codex agent away from SSH-capable runtime without clearing its SSH default", async () => {+ mockEnvironmentService.getById.mockResolvedValue({+ id: "33333333-3333-4333-8333-333333333333",+ companyId,+ driver: "ssh",+ });+ mockAgentService.getById.mockResolvedValue({+ ...baseAgent,+ adapterType: "codex_local",+ defaultEnvironmentId: "33333333-3333-4333-8333-333333333333",+ });++ const app = await createApp({+ type: "board",+ userId: "board-user",+ source: "local_implicit",+ isInstanceAdmin: true,+ companyIds: [companyId],+ });++ const res = await request(app)+ .patch(`/api/agents/${agentId}`)+ .send({+ adapterType: "process",+ });++ expect(res.status).toBe(422);+ expect(res.body.error).toContain('Environment driver "ssh" is not allowed here');+ });+it("exposes explicit task assignment access on agent detail", async () => {mockAccessService.listPrincipalGrants.mockResolvedValue([{diff --git a/server/src/__tests__/agent-skills-routes.test.ts b/server/src/__tests__/agent-skills-routes.test.tsindex c399095f39..b4748233dd 100644--- a/server/src/__tests__/agent-skills-routes.test.ts+++ b/server/src/__tests__/agent-skills-routes.test.ts@@ -22,6 +22,9 @@ const mockApprovalService = vi.hoisted(() => ({create: vi.fn(),}));const mockBudgetService = vi.hoisted(() => ({}));+const mockEnvironmentService = vi.hoisted(() => ({+ getById: vi.fn(),+}));const mockHeartbeatService = vi.hoisted(() => ({}));const mockIssueApprovalService = vi.hoisted(() => ({linkManyForApproval: vi.fn(),@@ -74,6 +77,7 @@ vi.mock("../services/index.js", () => ({approvalService: () => mockApprovalService,companySkillService: () => mockCompanySkillService,budgetService: () => mockBudgetService,+ environmentService: () => mockEnvironmentService,heartbeatService: () => mockHeartbeatService,issueApprovalService: () => mockIssueApprovalService,issueService: () => ({}),@@ -174,6 +178,7 @@ function makeAgent(adapterType: string) {adapterType,adapterConfig: {},runtimeConfig: {},+ defaultEnvironmentId: null,permissions: null,updatedAt: new Date(),};diff --git a/server/src/__tests__/cli-auth-routes.test.ts b/server/src/__tests__/cli-auth-routes.test.tsindex 419c1383b9..ca9dee8077 100644--- a/server/src/__tests__/cli-auth-routes.test.ts+++ b/server/src/__tests__/cli-auth-routes.test.ts@@ -1,6 +1,7 @@+import type { Server } from "node:http";import express from "express";import request from "supertest";-import { beforeEach, describe, expect, it, vi } from "vitest";+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";const mockAccessService = vi.hoisted(() => ({isInstanceAdmin: vi.fn(),@@ -34,6 +35,20 @@ vi.mock("../services/index.js", () => ({deduplicateAgentName: vi.fn((name: string) => name),}));+let currentServer: Server | null = null;++async function closeCurrentServer() {+ if (!currentServer) return;+ const server = currentServer;+ currentServer = null;+ await new Promise<void>((resolve, reject) => {+ server.close((err) => {+ if (err) reject(err);+ else resolve();+ });+ });+}+function registerModuleMocks() {vi.doMock("../routes/authz.js", async () => vi.importActual("../routes/authz.js"));@@ -48,6 +63,7 @@ function registerModuleMocks() {}async function createApp(actor: any, db: any = {} as any) {+ await closeCurrentServer();const [{ accessRoutes }, { errorHandler }] = await Promise.all([vi.importActual<typeof import("../routes/access.js")>("../routes/access.js"),vi.importActual<typeof import("../middleware/index.js")>("../middleware/index.js"),@@ -68,10 +84,13 @@ async function createApp(actor: any, db: any = {} as any) {}),);app.use(errorHandler);- return app;+ currentServer = app.listen(0);+ return currentServer;}describe("cli auth routes", () => {+ afterEach(closeCurrentServer);+beforeEach(() => {vi.resetModules();vi.doUnmock("../services/index.js");diff --git a/server/src/__tests__/environment-config.test.ts b/server/src/__tests__/environment-config.test.tsnew file mode 100644index 0000000000..2d7a6b1e4a--- /dev/null+++ b/server/src/__tests__/environment-config.test.ts@@ -0,0 +1,118 @@+import { describe, expect, it } from "vitest";+import { HttpError } from "../errors.js";+import { normalizeEnvironmentConfig, parseEnvironmentDriverConfig } from "../services/environment-config.ts";++describe("environment config helpers", () => {+ it("normalizes SSH config into its canonical stored shape", () => {+ const config = normalizeEnvironmentConfig({+ driver: "ssh",+ config: {+ host: "ssh.example.test",+ port: "2222",+ username: "ssh-user",+ remoteWorkspacePath: "/srv/paperclip/workspace",+ privateKeySecretRef: {+ type: "secret_ref",+ secretId: "11111111-1111-1111-1111-111111111111",+ version: "latest",+ },+ knownHosts: "",+ },+ });++ expect(config).toEqual({+ host: "ssh.example.test",+ port: 2222,+ username: "ssh-user",+ remoteWorkspacePath: "/srv/paperclip/workspace",+ privateKey: null,+ privateKeySecretRef: {+ type: "secret_ref",+ secretId: "11111111-1111-1111-1111-111111111111",+ version: "latest",+ },+ knownHosts: null,+ strictHostKeyChecking: true,+ });+ });++ it("rejects raw SSH private keys in the stored config shape", () => {+ expect(() =>+ normalizeEnvironmentConfig({+ driver: "ssh",+ config: {+ host: "ssh.example.test",+ port: "2222",+ username: "ssh-user",+ remoteWorkspacePath: "/srv/paperclip/workspace",+ privateKey: "PRIVATE KEY",+ },+ }),+ ).toThrow(HttpError);+ });++ it("rejects SSH config without an absolute remote workspace path", () => {+ expect(() =>+ normalizeEnvironmentConfig({+ driver: "ssh",+ config: {+ host: "ssh.example.test",+ username: "ssh-user",+ remoteWorkspacePath: "workspace",+ },+ }),+ ).toThrow(HttpError);++ expect(() =>+ normalizeEnvironmentConfig({+ driver: "ssh",+ config: {+ host: "ssh.example.test",+ username: "ssh-user",+ remoteWorkspacePath: "workspace",+ },+ }),+ ).toThrow("absolute");+ });++ it("parses a persisted SSH environment into a typed driver config", () => {+ const parsed = parseEnvironmentDriverConfig({+ driver: "ssh",+ config: {+ host: "ssh.example.test",+ port: 22,+ username: "ssh-user",+ remoteWorkspacePath: "/srv/paperclip/workspace",+ privateKey: null,+ privateKeySecretRef: null,+ knownHosts: null,+ strictHostKeyChecking: false,+ },+ });++ expect(parsed).toEqual({+ driver: "ssh",+ config: {+ host: "ssh.example.test",+ port: 22,+ username: "ssh-user",+ remoteWorkspacePath: "/srv/paperclip/workspace",+ privateKey: null,+ privateKeySecretRef: null,+ knownHosts: null,+ strictHostKeyChecking: false,+ },+ });+ });++ it("rejects unsupported environment drivers", () => {+ expect(() =>+ normalizeEnvironmentConfig({+ driver: "sandbox" as any,+ config: {+ provider: "fake",+ },+ }),+ ).toThrow(HttpError);+ });+});diff --git a/server/src/__tests__/environment-live-ssh.test.ts b/server/src/__tests__/environment-live-ssh.test.tsnew file mode 100644index 0000000000..ad608c0bc2--- /dev/null+++ b/server/src/__tests__/environment-live-ssh.test.ts@@ -0,0 +1,183 @@+import { readFile } from "node:fs/promises";+import path from "node:path";+import { afterAll, describe, expect, it } from "vitest";+import {+ buildSshEnvLabFixtureConfig,+ ensureSshWorkspaceReady,+ readSshEnvLabFixtureStatus,+ runSshCommand,+ startSshEnvLabFixture,+ stopSshEnvLabFixture,+ type SshConnectionConfig,+} from "@paperclipai/adapter-utils/ssh";++async function readOptionalSecret(+ value: string | undefined,+ filePath: string | undefined,+): Promise<string | null> {+ if (value && value.trim().length > 0) {+ return value;+ }+ if (filePath && filePath.trim().length > 0) {+ return await readFile(filePath, "utf8");+ }+ return null;+}++/**+ * Resolve the env-lab state path for this instance. Falls back to a temp+ * directory scoped to the test run so parallel runs don't collide.+ */+function resolveEnvLabStatePath(): string {+ const instanceRoot =+ process.env.PAPERCLIP_INSTANCE_ROOT?.trim() ||+ path.join(process.env.HOME ?? "/tmp", ".paperclip-worktrees", "instances", "live-ssh-test");+ return path.join(instanceRoot, "env-lab", "ssh-fixture", "state.json");+}++/** Attempt to build config from explicit PAPERCLIP_ENV_LIVE_SSH_* env vars. */+function tryExplicitConfig(): {+ host: string;+ port: number;+ username: string;+ remoteWorkspacePath: string;+} | null {+ const host = process.env.PAPERCLIP_ENV_LIVE_SSH_HOST?.trim() ?? "";+ const username = process.env.PAPERCLIP_ENV_LIVE_SSH_USERNAME?.trim() ?? "";+ const remoteWorkspacePath =+ process.env.PAPERCLIP_ENV_LIVE_SSH_REMOTE_WORKSPACE_PATH?.trim() ?? "";+ const port = Number.parseInt(process.env.PAPERCLIP_ENV_LIVE_SSH_PORT ?? "22", 10);++ if (!host || !username || !remoteWorkspacePath || !Number.isInteger(port) || port < 1 || port > 65535) {+ return null;+ }+ return { host, port, username, remoteWorkspacePath };+}++/** Try to use an already-running env-lab fixture. */+async function tryEnvLabFixture(): Promise<SshConnectionConfig | null> {+ const statePath = resolveEnvLabStatePath();+ const status = await readSshEnvLabFixtureStatus(statePath);+ if (status.running && status.state) {+ return buildSshEnvLabFixtureConfig(status.state);+ }+ return null;+}++/**+ * Start a fresh env-lab SSH fixture for this test run. Returns the config+ * and a cleanup function to stop it afterwards.+ */+async function startEnvLabForTest(): Promise<{+ config: SshConnectionConfig;+ cleanup: () => Promise<void>;+} | null> {+ const statePath = resolveEnvLabStatePath();+ try {+ const state = await startSshEnvLabFixture({ statePath });+ const config = await buildSshEnvLabFixtureConfig(state);+ return {+ config,+ cleanup: async () => {+ await stopSshEnvLabFixture(statePath);+ },+ };+ } catch {+ return null;+ }+}++let envLabCleanup: (() => Promise<void>) | null = null;++/**+ * Resolve an SSH connection config from (in order):+ * 1. Explicit PAPERCLIP_ENV_LIVE_SSH_* env vars+ * 2. An already-running env-lab fixture+ * 3. Auto-starting an env-lab fixture+ */+async function resolveSshConfig(): Promise<SshConnectionConfig | null> {+ // 1. Explicit env vars+ const explicit = tryExplicitConfig();+ if (explicit) {+ return {+ ...explicit,+ privateKey: await readOptionalSecret(+ process.env.PAPERCLIP_ENV_LIVE_SSH_PRIVATE_KEY,+ process.env.PAPERCLIP_ENV_LIVE_SSH_PRIVATE_KEY_PATH,+ ),+ knownHosts: await readOptionalSecret(+ process.env.PAPERCLIP_ENV_LIVE_SSH_KNOWN_HOSTS,+ process.env.PAPERCLIP_ENV_LIVE_SSH_KNOWN_HOSTS_PATH,+ ),+ strictHostKeyChecking:+ (process.env.PAPERCLIP_ENV_LIVE_SSH_STRICT_HOST_KEY_CHECKING ?? "true").toLowerCase() !== "false",+ };+ }++ // 2. Already-running env-lab+ const running = await tryEnvLabFixture();+ if (running) return running;++ // 3. Auto-start env-lab+ if (process.env.PAPERCLIP_ENV_LIVE_SSH_NO_AUTO_FIXTURE !== "true") {+ const started = await startEnvLabForTest();+ if (started) {+ envLabCleanup = started.cleanup;+ return started.config;+ }+ }++ return null;+}++let resolvedConfig: SshConnectionConfig | null | undefined;++const describeLiveSsh = (() => {+ // Eagerly check explicit env vars for sync skip decision.+ // If explicit vars are set, use them. Otherwise, we'll attempt env-lab in beforeAll.+ if (tryExplicitConfig()) return describe;+ // If NO_AUTO_FIXTURE is set and no explicit config, skip immediately+ if (process.env.PAPERCLIP_ENV_LIVE_SSH_NO_AUTO_FIXTURE === "true") {+ console.warn(+ "Skipping live SSH smoke test. Set PAPERCLIP_ENV_LIVE_SSH_HOST, PAPERCLIP_ENV_LIVE_SSH_USERNAME, and PAPERCLIP_ENV_LIVE_SSH_REMOTE_WORKSPACE_PATH to enable it, or remove PAPERCLIP_ENV_LIVE_SSH_NO_AUTO_FIXTURE to auto-start env-lab.",+ );+ return describe.skip;+ }+ // Will attempt env-lab — don't skip yet+ return describe;+})();++describeLiveSsh("live SSH environment smoke", () => {+ afterAll(async () => {+ if (envLabCleanup) {+ await envLabCleanup();+ envLabCleanup = null;+ }+ });++ it("connects to the configured SSH environment and verifies basic runtime tools", async () => {+ if (resolvedConfig === undefined) {+ resolvedConfig = await resolveSshConfig();+ }++ if (!resolvedConfig) {+ throw new Error(+ "Live SSH smoke test could not resolve SSH config from env vars or env-lab fixture. Set PAPERCLIP_ENV_LIVE_SSH_NO_AUTO_FIXTURE=true to mark this suite skipped intentionally.",+ );+ }++ const config = resolvedConfig;+ const ready = await ensureSshWorkspaceReady(config);+ const quotedRemoteWorkspacePath = JSON.stringify(config.remoteWorkspacePath);+ const result = await runSshCommand(+ config,+ `sh -lc "cd ${quotedRemoteWorkspacePath} && which git && which tar && pwd"`,+ { timeoutMs: 30000, maxBuffer: 256 * 1024 },+ );++ expect(ready.remoteCwd).toBe(config.remoteWorkspacePath);+ expect(result.stdout).toContain(config.remoteWorkspacePath);+ expect(result.stdout).toContain("git");+ expect(result.stdout).toContain("tar");+ });+});diff --git a/server/src/__tests__/environment-probe.test.ts b/server/src/__tests__/environment-probe.test.tsnew file mode 100644index 0000000000..40bf9f0a46--- /dev/null+++ b/server/src/__tests__/environment-probe.test.ts@@ -0,0 +1,118 @@+import { beforeEach, describe, expect, it, vi } from "vitest";++const mockEnsureSshWorkspaceReady = vi.hoisted(() => vi.fn());++vi.mock("@paperclipai/adapter-utils/ssh", () => ({+ ensureSshWorkspaceReady: mockEnsureSshWorkspaceReady,+}));++import { probeEnvironment } from "../services/environment-probe.ts";++describe("probeEnvironment", () => {+ beforeEach(() => {+ mockEnsureSshWorkspaceReady.mockReset();+ });++ it("reports local environments as immediately available", async () => {+ const result = await probeEnvironment({} as any, {+ id: "env-1",+ companyId: "company-1",+ name: "Local",+ description: null,+ driver: "local",+ status: "active",+ config: {},+ metadata: null,+ createdAt: new Date(),+ updatedAt: new Date(),+ });++ expect(result.ok).toBe(true);+ expect(result.driver).toBe("local");+ expect(result.summary).toContain("Local environment");+ expect(mockEnsureSshWorkspaceReady).not.toHaveBeenCalled();+ });++ it("runs an SSH probe and returns the verified remote cwd", async () => {+ mockEnsureSshWorkspaceReady.mockResolvedValue({+ remoteCwd: "/srv/paperclip/workspace",+ });++ const result = await probeEnvironment({} as any, {+ id: "env-ssh",+ companyId: "company-1",+ name: "SSH Fixture",+ description: null,+ driver: "ssh",+ status: "active",+ config: {+ host: "ssh.example.test",+ port: 2222,+ username: "ssh-user",+ remoteWorkspacePath: "/srv/paperclip/workspace",+ privateKey: null,+ privateKeySecretRef: null,+ knownHosts: null,+ strictHostKeyChecking: true,+ },+ metadata: null,+ createdAt: new Date(),+ updatedAt: new Date(),+ });++ expect(result).toEqual({+ ok: true,+ driver: "ssh",+ summary: "Connected to [email protected] and verified the remote workspace path.",+ details: {+ host: "ssh.example.test",+ port: 2222,+ username: "ssh-user",+ remoteWorkspacePath: "/srv/paperclip/workspace",+ remoteCwd: "/srv/paperclip/workspace",+ },+ });+ expect(mockEnsureSshWorkspaceReady).toHaveBeenCalledTimes(1);+ });++ it("captures SSH probe failures without throwing", async () => {+ mockEnsureSshWorkspaceReady.mockRejectedValue(+ Object.assign(new Error("Permission denied"), {+ code: 255,+ stdout: "",+ stderr: "Permission denied (publickey).",+ }),+ );++ const result = await probeEnvironment({} as any, {+ id: "env-ssh",+ companyId: "company-1",+ name: "SSH Fixture",+ description: null,+ driver: "ssh",+ status: "active",+ config: {+ host: "ssh.example.test",+ port: 22,+ username: "ssh-user",+ remoteWorkspacePath: "/srv/paperclip/workspace",+ privateKey: null,+ privateKeySecretRef: null,+ knownHosts: null,+ strictHostKeyChecking: true,+ },+ metadata: null,+ createdAt: new Date(),+ updatedAt: new Date(),+ });++ expect(result.ok).toBe(false);+ expect(result.summary).toContain("SSH probe failed");+ expect(result.details).toEqual(+ expect.objectContaining({+ error: "Permission denied (publickey).",+ code: 255,+ }),+ );+ });+});diff --git a/server/src/__tests__/environment-routes.test.ts b/server/src/__tests__/environment-routes.test.tsnew file mode 100644index 0000000000..502db0c4b6--- /dev/null+++ b/server/src/__tests__/environment-routes.test.ts@@ -0,0 +1,1181 @@+import type { Server } from "node:http";+import express from "express";+import request from "supertest";+import { afterAll, beforeEach, describe, expect, it, vi } from "vitest";+import { environmentRoutes } from "../routes/environments.js";+import { errorHandler } from "../middleware/index.js";++const mockAccessService = vi.hoisted(() => ({+ canUser: vi.fn(),+ hasPermission: vi.fn(),+}));++const mockAgentService = vi.hoisted(() => ({+ getById: vi.fn(),+}));++const mockEnvironmentService = vi.hoisted(() => ({+ list: vi.fn(),+ getById: vi.fn(),+ create: vi.fn(),+ update: vi.fn(),+ remove: vi.fn(),+ listLeases: vi.fn(),+ getLeaseById: vi.fn(),+}));+const mockExecutionWorkspaceService = vi.hoisted(() => ({+ clearEnvironmentSelection: vi.fn(),+}));+const mockIssueService = vi.hoisted(() => ({+ clearExecutionWorkspaceEnvironmentSelection: vi.fn(),+}));+const mockProjectService = vi.hoisted(() => ({+ clearExecutionWorkspaceEnvironmentSelection: vi.fn(),+}));++const mockLogActivity = vi.hoisted(() => vi.fn());+const mockProbeEnvironment = vi.hoisted(() => vi.fn());+const mockSecretService = vi.hoisted(() => ({+ create: vi.fn(),+ remove: vi.fn(),+ resolveSecretValue: vi.fn(),+}));++vi.mock("../services/index.js", () => ({+ accessService: () => mockAccessService,+ agentService: () => mockAgentService,+ environmentService: () => mockEnvironmentService,+ executionWorkspaceService: () => mockExecutionWorkspaceService,+ issueService: () => mockIssueService,+ logActivity: mockLogActivity,+ projectService: () => mockProjectService,+}));++vi.mock("../services/environment-probe.js", () => ({+ probeEnvironment: mockProbeEnvironment,+}));++vi.mock("../services/secrets.js", () => ({+ secretService: () => mockSecretService,+}));++function createEnvironment() {+ const now = new Date("2026-04-16T05:00:00.000Z");+ return {+ id: "env-1",+ companyId: "company-1",+ name: "Local",+ description: "Current development machine",+ driver: "local",+ status: "active" as const,+ config: { shell: "zsh" },+ metadata: { source: "manual" },+ createdAt: now,+ updatedAt: now,+ };+}++let server: Server | null = null;+let currentActor: Record<string, unknown> = {+ type: "board",+ userId: "user-1",+ source: "local_implicit",+};+function createApp(actor: Record<string, unknown>) {+ currentActor = actor;+ if (server) return server;++ const app = express();+ app.use(express.json());+ app.use((req, _res, next) => {+ (req as any).actor = currentActor;+ next();+ });+ app.use("/api", environmentRoutes({} as any));+ app.use(errorHandler);+ server = app.listen(0);+ return server;+}++describe("environment routes", () => {+ afterAll(async () => {+ if (!server) return;+ await new Promise<void>((resolve, reject) => {+ server?.close((err) => {+ if (err) reject(err);+ else resolve();+ });+ });+ server = null;+ });++ beforeEach(() => {+ mockAccessService.canUser.mockReset();+ mockAccessService.hasPermission.mockReset();+ mockAgentService.getById.mockReset();+ mockEnvironmentService.list.mockReset();+ mockEnvironmentService.getById.mockReset();+ mockEnvironmentService.create.mockReset();+ mockEnvironmentService.update.mockReset();+ mockEnvironmentService.remove.mockReset();+ mockEnvironmentService.listLeases.mockReset();+ mockEnvironmentService.getLeaseById.mockReset();+ mockExecutionWorkspaceService.clearEnvironmentSelection.mockReset();+ mockIssueService.clearExecutionWorkspaceEnvironmentSelection.mockReset();+ mockProjectService.clearExecutionWorkspaceEnvironmentSelection.mockReset();+ mockLogActivity.mockReset();+ mockProbeEnvironment.mockReset();+ mockSecretService.create.mockReset();+ mockSecretService.remove.mockReset();+ mockSecretService.resolveSecretValue.mockReset();+ mockSecretService.create.mockResolvedValue({+ id: "11111111-1111-1111-1111-111111111111",+ });+ });++ it("lists company-scoped environments", async () => {+ mockEnvironmentService.list.mockResolvedValue([createEnvironment()]);+ const app = createApp({+ type: "board",+ userId: "user-1",+ source: "local_implicit",+ });++ const res = await request(app).get("/api/companies/company-1/environments?driver=local");++ expect(res.status).toBe(200);+ expect(res.body).toHaveLength(1);+ expect(mockEnvironmentService.list).toHaveBeenCalledWith("company-1", {+ status: undefined,+ driver: "local",+ });+ });++ it("returns environment capabilities for the company", async () => {+ const app = createApp({+ type: "board",+ userId: "user-1",+ source: "local_implicit",+ });++ const res = await request(app).get("/api/companies/company-1/environments/capabilities");++ expect(res.status).toBe(200);+ expect(res.body.drivers.ssh).toBe("supported");+ expect(res.body.drivers.local).toBe("supported");+ expect(res.body.sandboxProviders).toBeUndefined();+ });++ it("redacts config and metadata for unprivileged agent list reads", async () => {+ mockEnvironmentService.list.mockResolvedValue([createEnvironment()]);+ mockAgentService.getById.mockResolvedValue({+ id: "agent-1",+ companyId: "company-1",+ role: "engineer",+ permissions: { canCreateAgents: false },+ });+ mockAccessService.hasPermission.mockResolvedValue(false);+ const app = createApp({+ type: "agent",+ agentId: "agent-1",+ companyId: "company-1",+ source: "agent_key",+ runId: "run-1",+ });++ const res = await request(app).get("/api/companies/company-1/environments");++ expect(res.status).toBe(200);+ expect(res.body).toEqual([+ expect.objectContaining({+ id: "env-1",+ config: {},+ metadata: null,+ configRedacted: true,+ metadataRedacted: true,+ }),+ ]);+ });++ it("redacts config and metadata for board members without environments:manage", async () => {+ mockEnvironmentService.list.mockResolvedValue([createEnvironment()]);+ mockAccessService.canUser.mockResolvedValue(false);+ const app = createApp({+ type: "board",+ userId: "member-user",+ source: "session",+ isInstanceAdmin: false,+ companyIds: ["company-1"],+ });++ const res = await request(app).get("/api/companies/company-1/environments");++ expect(res.status).toBe(200);+ expect(res.body).toEqual([+ expect.objectContaining({+ id: "env-1",+ config: {},+ metadata: null,+ configRedacted: true,+ metadataRedacted: true,+ }),+ ]);+ });++ it("returns full config for privileged environment readers", async () => {+ mockEnvironmentService.getById.mockResolvedValue(createEnvironment());+ mockAgentService.getById.mockResolvedValue({+ id: "agent-1",+ companyId: "company-1",+ role: "cto",+ permissions: { canCreateAgents: true },+ });+ mockAccessService.hasPermission.mockResolvedValue(false);+ const app = createApp({+ type: "agent",+ agentId: "agent-1",+ companyId: "company-1",+ source: "agent_key",+ runId: "run-1",+ });++ const res = await request(app).get("/api/environments/env-1");++ expect(res.status).toBe(200);+ expect(res.body.config).toEqual({ shell: "zsh" });+ expect(res.body.metadata).toEqual({ source: "manual" });+ expect(res.body.configRedacted).toBeUndefined();+ });++ it("redacts config and metadata for unprivileged agent detail reads", async () => {+ mockEnvironmentService.getById.mockResolvedValue(createEnvironment());+ mockAgentService.getById.mockResolvedValue({+ id: "agent-1",+ companyId: "company-1",+ role: "engineer",+ permissions: { canCreateAgents: false },+ });+ mockAccessService.hasPermission.mockResolvedValue(false);+ const app = createApp({+ type: "agent",+ agentId: "agent-1",+ companyId: "company-1",+ source: "agent_key",+ runId: "run-1",+ });++ const res = await request(app).get("/api/environments/env-1");++ expect(res.status).toBe(200);+ expect(res.body).toEqual(+ expect.objectContaining({+ id: "env-1",+ config: {},+ metadata: null,+ configRedacted: true,+ metadataRedacted: true,+ }),+ );+ });++ it("redacts config and metadata for board detail reads without environments:manage", async () => {+ mockEnvironmentService.getById.mockResolvedValue(createEnvironment());+ mockAccessService.canUser.mockResolvedValue(false);+ const app = createApp({+ type: "board",+ userId: "member-user",+ source: "session",+ isInstanceAdmin: false,+ companyIds: ["company-1"],+ });++ const res = await request(app).get("/api/environments/env-1");++ expect(res.status).toBe(200);+ expect(res.body).toEqual(+ expect.objectContaining({+ id: "env-1",+ config: {},+ metadata: null,+ configRedacted: true,+ metadataRedacted: true,+ }),+ );+ });++ it("creates an environment and logs activity", async () => {+ const environment = createEnvironment();+ mockAgentService.getById.mockResolvedValue({+ id: "agent-1",+ companyId: "company-1",+ role: "cto",+ permissions: { canCreateAgents: true },+ });+ mockAccessService.hasPermission.mockResolvedValue(false);+ mockEnvironmentService.create.mockResolvedValue(environment);+ const app = createApp({+ type: "agent",+ agentId: "agent-1",+ companyId: "company-1",+ source: "agent_key",+ runId: "run-1",+ });++ const res = await request(app)+ .post("/api/companies/company-1/environments")+ .send({+ name: "Local",+ driver: "local",+ description: "Current development machine",+ config: { shell: "zsh" },+ });++ expect(res.status).toBe(201);+ expect(mockEnvironmentService.create).toHaveBeenCalledWith("company-1", {+ name: "Local",+ driver: "local",+ description: "Current development machine",+ status: "active",+ config: { shell: "zsh" },+ });+ expect(mockLogActivity).toHaveBeenCalledWith(+ expect.anything(),+ expect.objectContaining({+ companyId: "company-1",+ actorType: "agent",+ actorId: "agent-1",+ agentId: "agent-1",+ runId: "run-1",+ action: "environment.created",+ entityType: "environment",+ entityId: environment.id,+ }),+ );+ });++ it("allows non-admin board users with environments:manage to create environments", async () => {+ const environment = createEnvironment();+ mockAccessService.canUser.mockResolvedValue(true);+ mockEnvironmentService.create.mockResolvedValue(environment);+ const app = createApp({+ type: "board",+ userId: "user-1",+ source: "session",+ companyIds: ["company-1"],+ isInstanceAdmin: false,+ });++ const res = await request(app)+ .post("/api/companies/company-1/environments")+ .send({+ name: "Local",+ driver: "local",+ config: {},+ });++ expect(res.status).toBe(201);+ expect(mockAccessService.canUser).toHaveBeenCalledWith(+ "company-1",+ "user-1",+ "environments:manage",+ );+ });++ it("rejects non-admin board users without environments:manage", async () => {+ mockAccessService.canUser.mockResolvedValue(false);+ const app = createApp({+ type: "board",+ userId: "user-1",+ source: "session",+ companyIds: ["company-1"],+ isInstanceAdmin: false,+ });++ const res = await request(app)+ .post("/api/companies/company-1/environments")+ .send({+ name: "Local",+ driver: "local",+ config: {},+ });++ expect(res.status).toBe(403);+ expect(res.body.error).toContain("environments:manage");+ expect(mockEnvironmentService.create).not.toHaveBeenCalled();+ });++ it("allows agents with explicit environments:manage grants to create environments", async () => {+ const environment = createEnvironment();+ mockAgentService.getById.mockResolvedValue({+ id: "agent-1",+ companyId: "company-1",+ role: "engineer",+ permissions: { canCreateAgents: false },+ });+ mockAccessService.hasPermission.mockResolvedValue(true);+ mockEnvironmentService.create.mockResolvedValue(environment);+ const app = createApp({+ type: "agent",+ agentId: "agent-1",+ companyId: "company-1",+ source: "agent_key",+ runId: "run-1",+ });++ const res = await request(app)+ .post("/api/companies/company-1/environments")+ .send({+ name: "Local",+ driver: "local",+ config: {},+ });++ expect(res.status).toBe(201);+ expect(mockAccessService.hasPermission).toHaveBeenCalledWith(+ "company-1",+ "agent",+ "agent-1",+ "environments:manage",+ );+ });++ it("rejects invalid SSH config on create", async () => {+ const app = createApp({+ type: "board",+ userId: "user-1",+ source: "local_implicit",+ });++ const res = await request(app)+ .post("/api/companies/company-1/environments")+ .send({+ name: "SSH Fixture",+ driver: "ssh",+ config: {+ host: "ssh.example.test",+ username: "ssh-user",+ },+ });++ expect(res.status).toBe(422);+ expect(res.body.error).toContain("remote workspace path");+ expect(mockEnvironmentService.create).not.toHaveBeenCalled();+ });++ it("normalizes SSH private keys into secret refs before persistence", async () => {+ const environment = {+ ...createEnvironment(),+ id: "env-ssh",+ name: "SSH Fixture",+ driver: "ssh" as const,+ config: {+ host: "ssh.example.test",+ port: 22,+ username: "ssh-user",+ remoteWorkspacePath: "/srv/paperclip/workspace",+ privateKey: null,+ privateKeySecretRef: {+ type: "secret_ref",+ secretId: "11111111-1111-1111-1111-111111111111",+ version: "latest",+ },+ knownHosts: null,+ strictHostKeyChecking: true,+ },+ };+ mockEnvironmentService.create.mockResolvedValue(environment);+ const app = createApp({+ type: "board",+ userId: "user-1",+ source: "local_implicit",+ });++ const res = await request(app)+ .post("/api/companies/company-1/environments")+ .send({+ name: "SSH Fixture",+ driver: "ssh",+ config: {+ host: "ssh.example.test",+ username: "ssh-user",+ remoteWorkspacePath: "/srv/paperclip/workspace",+ privateKey: " super-secret-key ",+ },+ });++ expect(res.status).toBe(201);+ expect(mockEnvironmentService.create).toHaveBeenCalledWith("company-1", expect.objectContaining({+ config: expect.objectContaining({+ privateKey: null,+ privateKeySecretRef: {+ type: "secret_ref",+ secretId: "11111111-1111-1111-1111-111111111111",+ version: "latest",+ },+ }),+ }));+ expect(JSON.stringify(mockEnvironmentService.create.mock.calls[0][1])).not.toContain("super-secret-key");+ expect(mockSecretService.create).toHaveBeenCalledWith(+ "company-1",+ expect.objectContaining({+ provider: "local_encrypted",+ value: "super-secret-key",+ }),+ expect.any(Object),+ );+ });++ it("rejects unprivileged agent mutations for shared environments", async () => {+ mockAgentService.getById.mockResolvedValue({+ id: "agent-1",+ companyId: "company-1",+ role: "engineer",+ permissions: { canCreateAgents: false },+ });+ mockAccessService.hasPermission.mockResolvedValue(false);+ const app = createApp({+ type: "agent",+ agentId: "agent-1",+ companyId: "company-1",+ source: "agent_key",+ runId: "run-1",+ });++ const res = await request(app)+ .post("/api/companies/company-1/environments")+ .send({+ name: "Sandbox host",+ driver: "local",+ });++ expect(res.status).toBe(403);+ expect(res.body.error).toContain("environments:manage");+ expect(mockEnvironmentService.create).not.toHaveBeenCalled();+ });++ it("lists leases for an environment after company access is confirmed", async () => {+ const environment = createEnvironment();+ mockEnvironmentService.getById.mockResolvedValue(environment);+ mockEnvironmentService.listLeases.mockResolvedValue([+ {+ id: "lease-1",+ companyId: "company-1",+ environmentId: environment.id,+ executionWorkspaceId: "workspace-1",+ issueId: null,+ heartbeatRunId: null,+ status: "active",+ providerLeaseId: "provider-lease-1",+ acquiredAt: new Date("2026-04-16T05:00:00.000Z"),+ lastUsedAt: new Date("2026-04-16T05:05:00.000Z"),+ expiresAt: null,+ releasedAt: null,+ metadata: { provider: "local" },+ createdAt: new Date("2026-04-16T05:00:00.000Z"),+ updatedAt: new Date("2026-04-16T05:05:00.000Z"),+ },+ ]);+ const app = createApp({+ type: "board",+ userId: "user-1",+ source: "local_implicit",+ });++ const res = await request(app).get(`/api/environments/${environment.id}/leases?status=active`);++ expect(res.status).toBe(200);+ expect(mockEnvironmentService.listLeases).toHaveBeenCalledWith(environment.id, {+ status: "active",+ });+ });++ it("rejects environment lease listing for board users without environments:manage", async () => {+ const environment = createEnvironment();+ mockEnvironmentService.getById.mockResolvedValue(environment);+ mockAccessService.canUser.mockResolvedValue(false);+ const app = createApp({+ type: "board",+ userId: "user-1",+ source: "dashboard_session",+ companyIds: ["company-1"],+ });++ const res = await request(app).get(`/api/environments/${environment.id}/leases`);++ expect(res.status).toBe(403);+ expect(res.body.error).toContain("environments:manage");+ expect(mockEnvironmentService.listLeases).not.toHaveBeenCalled();+ });++ it("returns a single lease after company access is confirmed", async () => {+ mockEnvironmentService.getLeaseById.mockResolvedValue({+ id: "lease-1",+ companyId: "company-1",+ environmentId: "env-1",+ executionWorkspaceId: "workspace-1",+ issueId: null,+ heartbeatRunId: "run-1",+ status: "active",+ leasePolicy: "ephemeral",+ provider: "ssh",+ providerLeaseId: "ssh://[email protected]:22/workspace",+ acquiredAt: new Date("2026-04-16T05:00:00.000Z"),+ lastUsedAt: new Date("2026-04-16T05:05:00.000Z"),+ expiresAt: null,+ releasedAt: null,+ failureReason: null,+ cleanupStatus: null,+ metadata: { remoteCwd: "/workspace" },+ createdAt: new Date("2026-04-16T05:00:00.000Z"),+ updatedAt: new Date("2026-04-16T05:05:00.000Z"),+ });+ const app = createApp({+ type: "board",+ userId: "user-1",+ source: "local_implicit",+ });++ const res = await request(app).get("/api/environment-leases/lease-1");++ expect(res.status).toBe(200);+ expect(res.body.provider).toBe("ssh");+ expect(mockEnvironmentService.getLeaseById).toHaveBeenCalledWith("lease-1");+ });++ it("rejects single-lease reads for board users without environments:manage", async () => {+ mockEnvironmentService.getLeaseById.mockResolvedValue({+ id: "lease-1",+ companyId: "company-1",+ environmentId: "env-1",+ executionWorkspaceId: "workspace-1",+ issueId: null,+ heartbeatRunId: "run-1",+ status: "active",+ leasePolicy: "ephemeral",+ provider: "ssh",+ providerLeaseId: "ssh://[email protected]:22/workspace",+ acquiredAt: new Date("2026-04-16T05:00:00.000Z"),+ lastUsedAt: new Date("2026-04-16T05:05:00.000Z"),+ expiresAt: null,+ releasedAt: null,+ failureReason: null,+ cleanupStatus: null,+ metadata: { remoteCwd: "/workspace" },+ createdAt: new Date("2026-04-16T05:00:00.000Z"),+ updatedAt: new Date("2026-04-16T05:05:00.000Z"),+ });+ mockAccessService.canUser.mockResolvedValue(false);+ const app = createApp({+ type: "board",+ userId: "user-1",+ source: "dashboard_session",+ companyIds: ["company-1"],+ });++ const res = await request(app).get("/api/environment-leases/lease-1");++ expect(res.status).toBe(403);+ expect(res.body.error).toContain("environments:manage");+ });++ it("rejects cross-company agent access", async () => {+ mockEnvironmentService.list.mockResolvedValue([]);+ const app = createApp({+ type: "agent",+ agentId: "agent-2",+ companyId: "company-2",+ source: "agent_key",+ runId: "run-2",+ });++ const res = await request(app).get("/api/companies/company-1/environments");++ expect(res.status).toBe(403);+ expect(res.body.error).toContain("another company");+ expect(mockEnvironmentService.list).not.toHaveBeenCalled();+ });++ it("logs a redacted update summary instead of raw config or metadata", async () => {+ const environment = createEnvironment();+ mockEnvironmentService.getById.mockResolvedValue(environment);+ mockEnvironmentService.update.mockResolvedValue({+ ...environment,+ status: "archived",+ });+ const app = createApp({+ type: "board",+ userId: "user-1",+ source: "local_implicit",+ });++ const res = await request(app)+ .patch(`/api/environments/${environment.id}`)+ .send({+ status: "archived",+ config: {+ apiKey: "super-secret",+ token: "another-secret",+ },+ metadata: {+ password: "do-not-log",+ },+ });++ expect(res.status).toBe(200);+ expect(mockLogActivity).toHaveBeenCalledWith(+ expect.anything(),+ expect.objectContaining({+ action: "environment.updated",+ details: {+ changedFields: ["config", "metadata", "status"],+ status: "archived",+ configChanged: true,+ configTopLevelKeyCount: 3,+ metadataChanged: true,+ metadataTopLevelKeyCount: 1,+ },+ }),+ );+ expect(JSON.stringify(mockLogActivity.mock.calls[0][1].details)).not.toContain("super-secret");+ expect(JSON.stringify(mockLogActivity.mock.calls[0][1].details)).not.toContain("do-not-log");+ });++ it("preserves the stored SSH private key secret ref on partial config updates", async () => {+ const environment = {+ ...createEnvironment(),+ name: "SSH Fixture",+ driver: "ssh" as const,+ config: {+ host: "ssh.example.test",+ port: 22,+ username: "ssh-user",+ remoteWorkspacePath: "/srv/paperclip/workspace",+ privateKey: null,+ privateKeySecretRef: {+ type: "secret_ref",+ secretId: "11111111-1111-1111-1111-111111111111",+ version: "latest",+ },+ knownHosts: null,+ strictHostKeyChecking: true,+ },+ };+ mockEnvironmentService.getById.mockResolvedValue(environment);+ mockEnvironmentService.update.mockResolvedValue({+ ...environment,+ config: {+ ...environment.config,+ port: 2222,+ },+ });+ const app = createApp({+ type: "board",+ userId: "user-1",+ source: "local_implicit",+ });++ const res = await request(app)+ .patch(`/api/environments/${environment.id}`)+ .send({+ config: {+ port: 2222,+ },+ });++ expect(res.status).toBe(200);+ expect(mockEnvironmentService.update).toHaveBeenCalledWith(+ environment.id,+ expect.objectContaining({+ config: expect.objectContaining({+ host: "ssh.example.test",+ port: 2222,+ username: "ssh-user",+ remoteWorkspacePath: "/srv/paperclip/workspace",+ privateKey: null,+ privateKeySecretRef: {+ type: "secret_ref",+ secretId: "11111111-1111-1111-1111-111111111111",+ version: "latest",+ },+ }),+ }),+ );+ expect(mockSecretService.create).not.toHaveBeenCalled();+ expect(mockSecretService.remove).not.toHaveBeenCalled();+ });++ it("replaces the stored SSH private key secret when a new private key is provided", async () => {+ const environment = {+ ...createEnvironment(),+ name: "SSH Fixture",+ driver: "ssh" as const,+ config: {+ host: "ssh.example.test",+ port: 22,+ username: "ssh-user",+ remoteWorkspacePath: "/srv/paperclip/workspace",+ privateKey: null,+ privateKeySecretRef: {+ type: "secret_ref",+ secretId: "22222222-2222-2222-2222-222222222222",+ version: "latest",+ },+ knownHosts: null,+ strictHostKeyChecking: true,+ },+ };+ mockEnvironmentService.getById.mockResolvedValue(environment);+ mockEnvironmentService.update.mockResolvedValue(environment);+ mockSecretService.create.mockResolvedValue({+ id: "33333333-3333-3333-3333-333333333333",+ });+ const app = createApp({+ type: "board",+ userId: "user-1",+ source: "local_implicit",+ });++ const res = await request(app)+ .patch(`/api/environments/${environment.id}`)+ .send({+ config: {+ privateKey: " replacement-private-key ",+ },+ });++ expect(res.status).toBe(200);+ expect(mockEnvironmentService.update).toHaveBeenCalledWith(+ environment.id,+ expect.objectContaining({+ config: expect.objectContaining({+ privateKey: null,+ privateKeySecretRef: {+ type: "secret_ref",+ secretId: "33333333-3333-3333-3333-333333333333",+ version: "latest",+ },+ }),+ }),+ );+ expect(mockSecretService.create).toHaveBeenCalledWith(+ "company-1",+ expect.objectContaining({+ provider: "local_encrypted",+ value: "replacement-private-key",+ }),+ expect.any(Object),+ );+ expect(mockSecretService.remove).toHaveBeenCalledWith("22222222-2222-2222-2222-222222222222");+ });++ it("resets config instead of inheriting SSH secrets when switching to local without an explicit config", async () => {+ const environment = {+ ...createEnvironment(),+ name: "SSH Fixture",+ driver: "ssh" as const,+ config: {+ host: "ssh.example.test",+ port: 22,+ username: "ssh-user",+ remoteWorkspacePath: "/srv/paperclip/workspace",+ privateKey: "super-secret-key",+ knownHosts: "known-host",+ strictHostKeyChecking: true,+ },+ };+ mockEnvironmentService.getById.mockResolvedValue(environment);+ mockEnvironmentService.update.mockResolvedValue({+ ...createEnvironment(),+ driver: "local" as const,+ config: {},+ });+ const app = createApp({+ type: "board",+ userId: "user-1",+ source: "local_implicit",+ });++ const res = await request(app)+ .patch(`/api/environments/${environment.id}`)+ .send({+ driver: "local",+ });++ expect(res.status).toBe(200);+ expect(mockEnvironmentService.update).toHaveBeenCalledWith(environment.id, {+ driver: "local",+ config: {},+ });+ expect(JSON.stringify(mockEnvironmentService.update.mock.calls[0][1])).not.toContain("super-secret-key");+ expect(JSON.stringify(mockEnvironmentService.update.mock.calls[0][1])).not.toContain("known-host");+ });++ it("requires explicit SSH config when switching from local to SSH", async () => {+ mockEnvironmentService.getById.mockResolvedValue(createEnvironment());+ const app = createApp({+ type: "board",+ userId: "user-1",+ source: "local_implicit",+ });++ const res = await request(app)+ .patch("/api/environments/env-1")+ .send({+ driver: "ssh",+ });++ expect(res.status).toBe(422);+ expect(res.body.error).toContain("host");+ expect(mockEnvironmentService.update).not.toHaveBeenCalled();+ });++ it("returns 404 when patching a missing environment", async () => {+ mockEnvironmentService.getById.mockResolvedValue(null);+ const app = createApp({+ type: "board",+ userId: "user-1",+ source: "local_implicit",+ });++ const res = await request(app)+ .patch("/api/environments/missing-env")+ .send({ status: "archived" });++ expect(res.status).toBe(404);+ expect(res.body.error).toBe("Environment not found");+ expect(mockLogActivity).not.toHaveBeenCalled();+ });++ it("deletes an environment and logs the removal", async () => {+ const environment = createEnvironment();+ mockEnvironmentService.getById.mockResolvedValue(environment);+ mockEnvironmentService.remove.mockResolvedValue(environment);+ const app = createApp({+ type: "board",+ userId: "user-1",+ source: "local_implicit",+ });++ const res = await request(app).delete(`/api/environments/${environment.id}`);++ expect(res.status).toBe(200);+ expect(mockEnvironmentService.remove).toHaveBeenCalledWith(environment.id);+ expect(mockExecutionWorkspaceService.clearEnvironmentSelection).toHaveBeenCalledWith(+ environment.companyId,+ environment.id,+ );+ expect(mockIssueService.clearExecutionWorkspaceEnvironmentSelection).toHaveBeenCalledWith(+ environment.companyId,+ environment.id,+ );+ expect(mockProjectService.clearExecutionWorkspaceEnvironmentSelection).toHaveBeenCalledWith(+ environment.companyId,+ environment.id,+ );+ expect(mockLogActivity).toHaveBeenCalledWith(+ expect.anything(),+ expect.objectContaining({+ action: "environment.deleted",+ entityId: environment.id,+ details: {+ name: environment.name,+ driver: environment.driver,+ status: environment.status,+ },+ }),+ );+ });++ it("deletes the stored SSH private-key secret after removing the environment", async () => {+ const environment = {+ ...createEnvironment(),+ name: "SSH Fixture",+ driver: "ssh" as const,+ config: {+ host: "ssh.example.test",+ port: 22,+ username: "ssh-user",+ remoteWorkspacePath: "/srv/paperclip/workspace",+ privateKey: null,+ privateKeySecretRef: {+ type: "secret_ref",+ secretId: "11111111-1111-4111-8111-111111111111",+ version: "latest",+ },+ knownHosts: null,+ strictHostKeyChecking: true,+ },+ };+ mockEnvironmentService.getById.mockResolvedValue(environment);+ mockEnvironmentService.remove.mockResolvedValue(environment);+ const app = createApp({+ type: "board",+ userId: "user-1",+ source: "local_implicit",+ });++ const res = await request(app).delete(`/api/environments/${environment.id}`);++ expect(res.status).toBe(200);+ expect(mockEnvironmentService.remove).toHaveBeenCalledWith(environment.id);+ expect(mockSecretService.remove).toHaveBeenCalledWith("11111111-1111-4111-8111-111111111111");+ expect(mockEnvironmentService.remove.mock.invocationCallOrder[0]).toBeLessThan(+ mockSecretService.remove.mock.invocationCallOrder[0],+ );+ expect(mockExecutionWorkspaceService.clearEnvironmentSelection).toHaveBeenCalledWith(+ environment.companyId,+ environment.id,+ );+ expect(mockIssueService.clearExecutionWorkspaceEnvironmentSelection).toHaveBeenCalledWith(+ environment.companyId,+ environment.id,+ );+ expect(mockProjectService.clearExecutionWorkspaceEnvironmentSelection).toHaveBeenCalledWith(+ environment.companyId,+ environment.id,+ );+ });++ it("skips SSH secret cleanup gracefully when stored SSH config no longer parses", async () => {+ const environment = {+ ...createEnvironment(),+ name: "SSH Fixture",+ driver: "ssh" as const,+ config: {+ host: "",+ username: "ssh-user",+ },+ };+ mockEnvironmentService.getById.mockResolvedValue(environment);+ mockEnvironmentService.remove.mockResolvedValue(environment);+ const app = createApp({+ type: "board",+ userId: "user-1",+ source: "local_implicit",+ });++ const res = await request(app).delete(`/api/environments/${environment.id}`);++ expect(res.status).toBe(200);+ expect(mockEnvironmentService.remove).toHaveBeenCalledWith(environment.id);+ expect(mockSecretService.remove).not.toHaveBeenCalled();+ });++ it("returns 404 when deleting a missing environment", async () => {+ mockEnvironmentService.getById.mockResolvedValue(null);+ const app = createApp({+ type: "board",+ userId: "user-1",+ source: "local_implicit",+ });++ const res = await request(app).delete("/api/environments/missing-env");++ expect(res.status).toBe(404);+ expect(res.body.error).toBe("Environment not found");+ expect(mockEnvironmentService.remove).not.toHaveBeenCalled();+ expect(mockLogActivity).not.toHaveBeenCalled();+ });++ it("probes an SSH environment and logs the result", async () => {+ const environment = {+ ...createEnvironment(),+ name: "SSH Fixture",+ driver: "ssh" as const,+ config: {+ host: "ssh.example.test",+ port: 22,+ username: "ssh-user",+ remoteWorkspacePath: "/srv/paperclip/workspace",+ privateKey: null,+ knownHosts: null,+ strictHostKeyChecking: true,+ },+ };+ mockEnvironmentService.getById.mockResolvedValue(environment);+ mockProbeEnvironment.mockResolvedValue({+ ok: true,+ driver: "ssh",+ summary: "Connected to [email protected] and verified the remote workspace path.",+ details: {+ host: "ssh.example.test",+ },+ });+ const app = createApp({+ type: "board",+ userId: "user-1",+ source: "local_implicit",+ runId: "run-1",+ });++ const res = await request(app)+ .post(`/api/environments/${environment.id}/probe`)+ .send({});++ expect(res.status).toBe(200);+ expect(res.body.ok).toBe(true);+ expect(mockProbeEnvironment).toHaveBeenCalledWith(expect.anything(), environment);+ expect(mockLogActivity).toHaveBeenCalledWith(+ expect.anything(),+ expect.objectContaining({+ companyId: "company-1",+ action: "environment.probed",+ entityType: "environment",+ entityId: environment.id,+ details: expect.objectContaining({+ driver: "ssh",+ ok: true,+ }),+ }),+ );+ });++ it("probes unsaved SSH config without persisting secrets", async () => {+ mockProbeEnvironment.mockResolvedValue({+ ok: true,+ driver: "ssh",+ summary: "Connected to [email protected] and verified the remote workspace path.",+ details: { remoteCwd: "/srv/paperclip/workspace" },+ });+ const app = createApp({+ type: "board",+ userId: "user-1",+ source: "local_implicit",+ runId: "run-1",+ });++ const res = await request(app)+ .post("/api/companies/company-1/environments/probe-config")+ .send({+ name: "Draft SSH",+ description: "Probe this SSH target before saving it.",+ driver: "ssh",+ config: {+ host: "ssh.example.test",+ username: "ssh-user",+ remoteWorkspacePath: "/srv/paperclip/workspace",+ privateKey: "unsaved-test-key",+ },+ });++ expect(res.status).toBe(200);+ expect(mockEnvironmentService.create).not.toHaveBeenCalled();+ expect(mockSecretService.create).not.toHaveBeenCalled();+ expect(mockProbeEnvironment).toHaveBeenCalledWith(+ expect.anything(),+ expect.objectContaining({+ id: "unsaved",+ driver: "ssh",+ config: expect.objectContaining({+ privateKey: "unsaved-test-key",+ }),+ }),+ expect.objectContaining({+ resolvedConfig: expect.objectContaining({+ driver: "ssh",+ }),+ }),+ );+ expect(JSON.stringify(mockLogActivity.mock.calls[0][1].details)).not.toContain("unsaved-test-key");+ });+});diff --git a/server/src/__tests__/environment-selection-route-guards.test.ts b/server/src/__tests__/environment-selection-route-guards.test.tsnew file mode 100644index 0000000000..1230d29d94--- /dev/null+++ b/server/src/__tests__/environment-selection-route-guards.test.ts@@ -0,0 +1,492 @@+import type { Server } from "node:http";+import express from "express";+import request from "supertest";+import { afterAll, beforeEach, describe, expect, it, vi } from "vitest";+import { errorHandler } from "../middleware/index.js";+import { projectRoutes } from "../routes/projects.js";+import { issueRoutes } from "../routes/issues.js";++const mockProjectService = vi.hoisted(() => ({+ create: vi.fn(),+ getById: vi.fn(),+ update: vi.fn(),+ createWorkspace: vi.fn(),+ remove: vi.fn(),+ resolveByReference: vi.fn(),+ listWorkspaces: vi.fn(),+}));++const mockIssueService = vi.hoisted(() => ({+ create: vi.fn(),+ createChild: vi.fn(),+ getById: vi.fn(),+ update: vi.fn(),+ getByIdentifier: vi.fn(),+ assertCheckoutOwner: vi.fn(),+}));++const mockEnvironmentService = vi.hoisted(() => ({+ getById: vi.fn(),+}));++const mockReferenceSummary = vi.hoisted(() => ({+ inbound: [],+ outbound: [],+ documentSources: [],+}));++const mockLogActivity = vi.hoisted(() => vi.fn());++vi.mock("../services/index.js", () => ({+ projectService: () => mockProjectService,+ issueService: () => mockIssueService,+ environmentService: () => mockEnvironmentService,+ secretService: () => ({+ normalizeEnvBindingsForPersistence: vi.fn(async (_companyId: string, env: unknown) => env),+ normalizeAdapterConfigForPersistence: vi.fn(async (_companyId: string, config: unknown) => config),+ }),+ logActivity: mockLogActivity,+ workspaceOperationService: () => ({}),+ accessService: () => ({+ canUser: vi.fn(),+ hasPermission: vi.fn(),+ }),+ agentService: () => ({+ getById: vi.fn(),+ }),+ executionWorkspaceService: () => ({}),+ goalService: () => ({+ getById: vi.fn(),+ getDefaultCompanyGoal: vi.fn(),+ }),+ heartbeatService: () => ({+ getRun: vi.fn(),+ getActiveRunForAgent: vi.fn(),+ }),+ issueApprovalService: () => ({+ listApprovalsForIssue: vi.fn(),+ unlink: vi.fn(),+ }),+ feedbackService: () => ({+ listIssueVotesForUser: vi.fn(),+ listFeedbackTraces: vi.fn(),+ getFeedbackTraceById: vi.fn(),+ getFeedbackTraceBundle: vi.fn(),+ saveIssueVote: vi.fn(),+ }),+ instanceSettingsService: () => ({+ get: vi.fn(async () => ({})),+ listCompanyIds: vi.fn(async () => []),+ }),+ issueReferenceService: () => ({+ emptySummary: vi.fn(() => mockReferenceSummary),+ syncIssue: vi.fn(),+ syncComment: vi.fn(),+ syncDocument: vi.fn(),+ deleteDocumentSource: vi.fn(),+ listIssueReferenceSummary: vi.fn(async () => mockReferenceSummary),+ diffIssueReferenceSummary: vi.fn(() => ({+ addedReferencedIssues: [],+ removedReferencedIssues: [],+ currentReferencedIssues: [],+ })),+ }),+ documentService: () => ({}),+ routineService: () => ({}),+ workProductService: () => ({}),+}));++vi.mock("../services/issue-assignment-wakeup.js", () => ({+ queueIssueAssignmentWakeup: vi.fn(),+}));++function buildApp(routerFactory: (app: express.Express) => void) {+ const app = express();+ app.use(express.json());+ app.use((req, _res, next) => {+ (req as any).actor = {+ type: "board",+ userId: "user-1",+ source: "local_implicit",+ };+ next();+ });+ routerFactory(app);+ app.use(errorHandler);+ return app;+}++let projectServer: Server | null = null;+let issueServer: Server | null = null;++function createProjectApp() {+ projectServer ??= buildApp((expressApp) => {+ expressApp.use("/api", projectRoutes({} as any));+ }).listen(0);+ return projectServer;+}++function createIssueApp() {+ issueServer ??= buildApp((expressApp) => {+ expressApp.use("/api", issueRoutes({} as any, {} as any));+ }).listen(0);+ return issueServer;+}++const sshEnvironmentId = "11111111-1111-4111-8111-111111111111";++async function closeServer(server: Server | null) {+ if (!server) return;+ await new Promise<void>((resolve, reject) => {+ server.close((err) => {+ if (err) reject(err);+ else resolve();+ });+ });+}++describe.sequential("execution environment route guards", () => {+ afterAll(async () => {+ await closeServer(projectServer);+ await closeServer(issueServer);+ projectServer = null;+ issueServer = null;+ });++ beforeEach(() => {+ mockProjectService.create.mockReset();+ mockProjectService.getById.mockReset();+ mockProjectService.update.mockReset();+ mockProjectService.createWorkspace.mockReset();+ mockProjectService.remove.mockReset();+ mockProjectService.resolveByReference.mockReset();+ mockProjectService.listWorkspaces.mockReset();+ mockIssueService.create.mockReset();+ mockIssueService.createChild.mockReset();+ mockIssueService.getById.mockReset();+ mockIssueService.update.mockReset();+ mockIssueService.getByIdentifier.mockReset();+ mockIssueService.assertCheckoutOwner.mockReset();+ mockEnvironmentService.getById.mockReset();+ mockLogActivity.mockReset();+ });++ it("accepts SSH environments on project create", async () => {+ mockEnvironmentService.getById.mockResolvedValue({+ id: sshEnvironmentId,+ companyId: "company-1",+ driver: "ssh",+ config: {},+ });+ mockProjectService.create.mockResolvedValue({+ id: "project-1",+ companyId: "company-1",+ name: "SSH Project",+ status: "backlog",+ });+ const app = createProjectApp();++ const res = await request(app)+ .post("/api/companies/company-1/projects")+ .send({+ name: "SSH Project",+ executionWorkspacePolicy: {+ enabled: true,+ environmentId: sshEnvironmentId,+ },+ });++ expect(res.status).not.toBe(422);+ expect(mockProjectService.create).toHaveBeenCalled();+ });++ it("accepts SSH environments on project update", async () => {+ mockProjectService.getById.mockResolvedValue({+ id: "project-1",+ companyId: "company-1",+ name: "SSH Project",+ status: "backlog",+ archivedAt: null,+ });+ mockEnvironmentService.getById.mockResolvedValue({+ id: sshEnvironmentId,+ companyId: "company-1",+ driver: "ssh",+ config: {},+ });+ mockProjectService.update.mockResolvedValue({+ id: "project-1",+ companyId: "company-1",+ name: "SSH Project",+ status: "backlog",+ });+ const app = createProjectApp();++ const res = await request(app)+ .patch("/api/projects/project-1")+ .send({+ executionWorkspacePolicy: {+ enabled: true,+ environmentId: sshEnvironmentId,+ },+ });++ expect(res.status).not.toBe(422);+ expect(mockProjectService.update).toHaveBeenCalled();+ });++ it("rejects cross-company environments on project create", async () => {+ mockEnvironmentService.getById.mockResolvedValue({+ id: sshEnvironmentId,+ companyId: "company-2",+ driver: "ssh",+ config: {},+ });+ const app = createProjectApp();++ const res = await request(app)+ .post("/api/companies/company-1/projects")+ .send({+ name: "Cross Company Project",+ executionWorkspacePolicy: {+ enabled: true,+ environmentId: sshEnvironmentId,+ },+ });++ expect(res.status).toBe(422);+ expect(res.body.error).toBe("Environment not found.");+ expect(mockProjectService.create).not.toHaveBeenCalled();+ });++ it("rejects unsupported driver environments on project update", async () => {+ mockProjectService.getById.mockResolvedValue({+ id: "project-1",+ companyId: "company-1",+ name: "SSH Project",+ status: "backlog",+ archivedAt: null,+ });+ mockEnvironmentService.getById.mockResolvedValue({+ id: sshEnvironmentId,+ companyId: "company-1",+ driver: "unsupported_driver",+ config: {},+ });+ const app = createProjectApp();++ const res = await request(app)+ .patch("/api/projects/project-1")+ .send({+ executionWorkspacePolicy: {+ enabled: true,+ environmentId: sshEnvironmentId,+ },+ });++ expect(res.status).toBe(422);+ expect(res.body.error).toContain('Environment driver "unsupported_driver" is not allowed here');+ expect(mockProjectService.update).not.toHaveBeenCalled();+ });++ it("rejects archived environments on project create", async () => {+ mockEnvironmentService.getById.mockResolvedValue({+ id: sshEnvironmentId,+ companyId: "company-1",+ driver: "ssh",+ status: "archived",+ config: {},+ });+ const app = createProjectApp();++ const res = await request(app)+ .post("/api/companies/company-1/projects")+ .send({+ name: "Archived Project",+ executionWorkspacePolicy: {+ enabled: true,+ environmentId: sshEnvironmentId,+ },+ });++ expect(res.status).toBe(422);+ expect(res.body.error).toBe("Environment is archived.");+ expect(mockProjectService.create).not.toHaveBeenCalled();+ });++ it("rejects archived environments on issue create", async () => {+ mockEnvironmentService.getById.mockResolvedValue({+ id: sshEnvironmentId,+ companyId: "company-1",+ driver: "ssh",+ status: "archived",+ config: {},+ });+ const app = createIssueApp();++ const res = await request(app)+ .post("/api/companies/company-1/issues")+ .send({+ title: "Archived Issue",+ executionWorkspaceSettings: {+ environmentId: sshEnvironmentId,+ },+ });++ expect(res.status).toBe(422);+ expect(res.body.error).toBe("Environment is archived.");+ expect(mockIssueService.create).not.toHaveBeenCalled();+ });++ it("accepts SSH environments on issue create", async () => {+ mockEnvironmentService.getById.mockResolvedValue({+ id: sshEnvironmentId,+ companyId: "company-1",+ driver: "ssh",+ config: {},+ });+ mockIssueService.create.mockResolvedValue({+ id: "issue-1",+ companyId: "company-1",+ title: "SSH Issue",+ status: "todo",+ identifier: "PAPA-999",+ });+ const app = createIssueApp();++ const res = await request(app)+ .post("/api/companies/company-1/issues")+ .send({+ title: "SSH Issue",+ executionWorkspaceSettings: {+ environmentId: sshEnvironmentId,+ },+ });++ expect(res.status).not.toBe(422);+ expect(mockIssueService.create).toHaveBeenCalled();+ });++ it("rejects unsupported driver environments on issue create", async () => {+ mockEnvironmentService.getById.mockResolvedValue({+ id: sshEnvironmentId,+ companyId: "company-1",+ driver: "unsupported_driver",+ config: {},+ });+ const app = createIssueApp();++ const res = await request(app)+ .post("/api/companies/company-1/issues")+ .send({+ title: "Unsupported Driver Issue",+ executionWorkspaceSettings: {+ environmentId: sshEnvironmentId,+ },+ });++ expect(res.status).toBe(422);+ expect(res.body.error).toContain('Environment driver "unsupported_driver" is not allowed here');+ expect(mockIssueService.create).not.toHaveBeenCalled();+ });++ it("rejects unsupported driver environments on child issue create", async () => {+ mockIssueService.getById.mockResolvedValue({+ id: "parent-1",+ companyId: "company-1",+ status: "todo",+ assigneeAgentId: null,+ assigneeUserId: null,+ createdByUserId: null,+ identifier: "PAPA-998",+ });+ mockEnvironmentService.getById.mockResolvedValue({+ id: sshEnvironmentId,+ companyId: "company-1",+ driver: "unsupported_driver",+ config: {},+ });+ const app = createIssueApp();++ const res = await request(app)+ .post("/api/issues/parent-1/children")+ .send({+ title: "Unsupported Child",+ executionWorkspaceSettings: {+ environmentId: sshEnvironmentId,+ },+ });++ expect(res.status).toBe(422);+ expect(res.body.error).toContain('Environment driver "unsupported_driver" is not allowed here');+ expect(mockIssueService.createChild).not.toHaveBeenCalled();+ });++ it("rejects cross-company environments on child issue create", async () => {+ mockIssueService.getById.mockResolvedValue({+ id: "parent-1",+ companyId: "company-1",+ status: "todo",+ assigneeAgentId: null,+ assigneeUserId: null,+ createdByUserId: null,+ identifier: "PAPA-998",+ });+ mockEnvironmentService.getById.mockResolvedValue({+ id: sshEnvironmentId,+ companyId: "company-2",+ driver: "ssh",+ config: {},+ });+ const app = createIssueApp();++ const res = await request(app)+ .post("/api/issues/parent-1/children")+ .send({+ title: "Cross Company Child",+ executionWorkspaceSettings: {+ environmentId: sshEnvironmentId,+ },+ });++ expect(res.status).toBe(422);+ expect(res.body.error).toBe("Environment not found.");+ expect(mockIssueService.createChild).not.toHaveBeenCalled();+ });++ it("accepts SSH environments on issue update", async () => {+ mockIssueService.getById.mockResolvedValue({+ id: "issue-1",+ companyId: "company-1",+ status: "todo",+ assigneeAgentId: null,+ assigneeUserId: null,+ createdByUserId: null,+ identifier: "PAPA-999",+ });+ mockEnvironmentService.getById.mockResolvedValue({+ id: sshEnvironmentId,+ companyId: "company-1",+ driver: "ssh",+ config: {},+ });+ mockIssueService.update.mockResolvedValue({+ id: "issue-1",+ companyId: "company-1",+ status: "todo",+ identifier: "PAPA-999",+ });+ const app = createIssueApp();++ const res = await request(app)+ .patch("/api/issues/issue-1")+ .send({+ executionWorkspaceSettings: {+ environmentId: sshEnvironmentId,+ },+ });++ expect(res.status).not.toBe(422);+ expect(mockIssueService.update).toHaveBeenCalled();+ });+});diff --git a/server/src/__tests__/environment-service.test.ts b/server/src/__tests__/environment-service.test.tsindex fc3b3374fe..30d66c4f7c 100644--- a/server/src/__tests__/environment-service.test.ts+++ b/server/src/__tests__/environment-service.test.ts@@ -221,4 +221,31 @@ describeEmbeddedPostgres("environmentService leases", () => {expect(rows[0]?.driver).toBe("local");expect(rows[0]?.status).toBe("active");});++ it("allows multiple SSH environments for the same company", async () => {+ const companyId = randomUUID();+ await db.insert(companies).values({+ id: companyId,+ name: "Acme",+ status: "active",+ createdAt: new Date(),+ updatedAt: new Date(),+ });++ const first = await svc.create(companyId, {+ name: "Production SSH",+ driver: "ssh",+ config: { host: "prod.example.com", username: "deploy" },+ });+ const second = await svc.create(companyId, {+ name: "Staging SSH",+ driver: "ssh",+ config: { host: "staging.example.com", username: "deploy" },+ });++ expect(first.id).not.toBe(second.id);++ const rows = await db.select().from(environments).where(eq(environments.companyId, companyId));+ expect(rows.filter((row) => row.driver === "ssh")).toHaveLength(2);+ });});diff --git a/server/src/__tests__/execution-workspace-policy.test.ts b/server/src/__tests__/execution-workspace-policy.test.tsindex ecb5f76e7d..4ed5de9b4f 100644--- a/server/src/__tests__/execution-workspace-policy.test.ts+++ b/server/src/__tests__/execution-workspace-policy.test.ts@@ -6,6 +6,7 @@ import {issueExecutionWorkspaceModeForPersistedWorkspace,parseIssueExecutionWorkspaceSettings,parseProjectExecutionWorkspacePolicy,+ resolveExecutionWorkspaceEnvironmentId,resolveExecutionWorkspaceMode,} from "../services/execution-workspace-policy.ts";@@ -117,6 +118,7 @@ describe("execution workspace policy helpers", () => {parseProjectExecutionWorkspacePolicy({enabled: true,defaultMode: "isolated",+ environmentId: "8f8ab8f2-d95f-4315-9f08-d683a1e0f73b",workspaceStrategy: {type: "git_worktree",worktreeParentDir: ".paperclip/worktrees",@@ -127,6 +129,7 @@ describe("execution workspace policy helpers", () => {).toEqual({enabled: true,defaultMode: "isolated_workspace",+ environmentId: "8f8ab8f2-d95f-4315-9f08-d683a1e0f73b",workspaceStrategy: {type: "git_worktree",worktreeParentDir: ".paperclip/worktrees",@@ -137,12 +140,83 @@ describe("execution workspace policy helpers", () => {expect(parseIssueExecutionWorkspaceSettings({mode: "project_primary",+ environmentId: "8f8ab8f2-d95f-4315-9f08-d683a1e0f73b",}),).toEqual({mode: "shared_workspace",+ environmentId: "8f8ab8f2-d95f-4315-9f08-d683a1e0f73b",});});+ it("prefers persisted environment selection over issue and project defaults", () => {+ expect(+ resolveExecutionWorkspaceEnvironmentId({+ projectPolicy: { enabled: true, environmentId: "project-env" },+ issueSettings: { environmentId: "issue-env" },+ workspaceConfig: { environmentId: "workspace-env" },+ agentDefaultEnvironmentId: "agent-env",+ defaultEnvironmentId: "default-env",+ }),+ ).toBe("workspace-env");+ expect(+ resolveExecutionWorkspaceEnvironmentId({+ projectPolicy: { enabled: true, environmentId: "project-env" },+ issueSettings: { environmentId: "issue-env" },+ workspaceConfig: null,+ agentDefaultEnvironmentId: "agent-env",+ defaultEnvironmentId: "default-env",+ }),+ ).toBe("issue-env");+ expect(+ resolveExecutionWorkspaceEnvironmentId({+ projectPolicy: { enabled: true, environmentId: "project-env" },+ issueSettings: null,+ workspaceConfig: null,+ agentDefaultEnvironmentId: "agent-env",+ defaultEnvironmentId: "default-env",+ }),+ ).toBe("project-env");+ });++ it("falls back to the agent default environment before the company default", () => {+ expect(+ resolveExecutionWorkspaceEnvironmentId({+ projectPolicy: null,+ issueSettings: null,+ workspaceConfig: null,+ agentDefaultEnvironmentId: "agent-env",+ defaultEnvironmentId: "default-env",+ }),+ ).toBe("agent-env");+ expect(+ resolveExecutionWorkspaceEnvironmentId({+ projectPolicy: { enabled: true, environmentId: null },+ issueSettings: null,+ workspaceConfig: null,+ agentDefaultEnvironmentId: "agent-env",+ defaultEnvironmentId: "default-env",+ }),+ ).toBe("default-env");+ expect(+ resolveExecutionWorkspaceEnvironmentId({+ projectPolicy: null,+ issueSettings: null,+ workspaceConfig: null,+ agentDefaultEnvironmentId: null,+ defaultEnvironmentId: "default-env",+ }),+ ).toBe("default-env");+ expect(+ resolveExecutionWorkspaceEnvironmentId({+ projectPolicy: { enabled: true, environmentId: null },+ issueSettings: null,+ workspaceConfig: null,+ agentDefaultEnvironmentId: null,+ defaultEnvironmentId: "default-env",+ }),+ ).toBe("default-env");+ });+it("maps persisted execution workspace modes back to issue settings", () => {expect(issueExecutionWorkspaceModeForPersistedWorkspace("isolated_workspace")).toBe("isolated_workspace");expect(issueExecutionWorkspaceModeForPersistedWorkspace("operator_branch")).toBe("operator_branch");diff --git a/server/src/__tests__/execution-workspaces-service.test.ts b/server/src/__tests__/execution-workspaces-service.test.tsindex 1ca6d02fab..f4c87e5f59 100644--- a/server/src/__tests__/execution-workspaces-service.test.ts+++ b/server/src/__tests__/execution-workspaces-service.test.ts@@ -5,6 +5,7 @@ import path from "node:path";import { randomUUID } from "node:crypto";import { promisify } from "node:util";import { afterAll, afterEach, beforeAll, describe, expect, it } from "vitest";+import { inArray } from "drizzle-orm";import {companies,createDb,@@ -30,6 +31,7 @@ describe("execution workspace config helpers", () => {expect(readExecutionWorkspaceConfig({source: "project_primary",config: {+ environmentId: "32e0464c-2a0b-4ce9-886d-2cc99e6f3e7b",provisionCommand: "bash ./scripts/provision-worktree.sh",teardownCommand: "bash ./scripts/teardown-worktree.sh",cleanupCommand: "pkill -f vite || true",@@ -38,6 +40,7 @@ describe("execution workspace config helpers", () => {},},})).toEqual({+ environmentId: "32e0464c-2a0b-4ce9-886d-2cc99e6f3e7b",provisionCommand: "bash ./scripts/provision-worktree.sh",teardownCommand: "bash ./scripts/teardown-worktree.sh",cleanupCommand: "pkill -f vite || true",@@ -55,11 +58,13 @@ describe("execution workspace config helpers", () => {source: "project_primary",createdByRuntime: false,config: {+ environmentId: "32e0464c-2a0b-4ce9-886d-2cc99e6f3e7b",provisionCommand: "bash ./scripts/provision-worktree.sh",cleanupCommand: "pkill -f vite || true",},},{+ environmentId: "6286d5a9-9ea7-42b9-98b3-18ee904c26d7",teardownCommand: "bash ./scripts/teardown-worktree.sh",workspaceRuntime: {services: [{ name: "web", command: "pnpm dev" }],@@ -69,6 +74,7 @@ describe("execution workspace config helpers", () => {source: "project_primary",createdByRuntime: false,config: {+ environmentId: "6286d5a9-9ea7-42b9-98b3-18ee904c26d7",provisionCommand: "bash ./scripts/provision-worktree.sh",teardownCommand: "bash ./scripts/teardown-worktree.sh",cleanupCommand: "pkill -f vite || true",@@ -81,6 +87,22 @@ describe("execution workspace config helpers", () => {});});+ it("clears a persisted environment selection when patching it to null", () => {+ expect(mergeExecutionWorkspaceConfig(+ {+ source: "project_primary",+ config: {+ environmentId: "32e0464c-2a0b-4ce9-886d-2cc99e6f3e7b",+ },+ },+ {+ environmentId: null,+ },+ )).toEqual({+ source: "project_primary",+ });+ });+it("clears the nested config block when requested", () => {expect(mergeExecutionWorkspaceConfig({@@ -223,6 +245,104 @@ describeEmbeddedPostgres("executionWorkspaceService.getCloseReadiness", () => {]));});+ it("clears matching environment selections transactionally without touching other workspaces", async () => {+ const companyId = randomUUID();+ const projectId = randomUUID();+ const matchingWorkspaceId = randomUUID();+ const otherWorkspaceId = randomUUID();+ const untouchedWorkspaceId = randomUUID();+ const environmentId = randomUUID();++ await db.insert(companies).values({+ id: companyId,+ name: "Paperclip",+ issuePrefix: "PAP",+ requireBoardApprovalForNewAgents: false,+ });+ await db.insert(projects).values({+ id: projectId,+ companyId,+ name: "Workspace cleanup",+ status: "in_progress",+ executionWorkspacePolicy: {+ enabled: true,+ },+ });+ await db.insert(executionWorkspaces).values([+ {+ id: matchingWorkspaceId,+ companyId,+ projectId,+ mode: "isolated_workspace",+ strategyType: "directory",+ name: "Matching workspace",+ status: "active",+ providerType: "local_fs",+ cwd: "/tmp/workspace-a",+ metadata: {+ source: "manual",+ config: {+ environmentId,+ cleanupCommand: "echo clean",+ },+ },+ },+ {+ id: otherWorkspaceId,+ companyId,+ projectId,+ mode: "isolated_workspace",+ strategyType: "directory",+ name: "Different environment",+ status: "active",+ providerType: "local_fs",+ cwd: "/tmp/workspace-b",+ metadata: {+ source: "manual",+ config: {+ environmentId: randomUUID(),+ },+ },+ },+ {+ id: untouchedWorkspaceId,+ companyId,+ projectId,+ mode: "isolated_workspace",+ strategyType: "directory",+ name: "No environment",+ status: "active",+ providerType: "local_fs",+ cwd: "/tmp/workspace-c",+ metadata: {+ source: "manual",+ },+ },+ ]);++ const cleared = await svc.clearEnvironmentSelection(companyId, environmentId);++ expect(cleared).toBe(1);++ const rows = await db+ .select({+ id: executionWorkspaces.id,+ metadata: executionWorkspaces.metadata,+ })+ .from(executionWorkspaces)+ .where(inArray(executionWorkspaces.id, [matchingWorkspaceId, otherWorkspaceId, untouchedWorkspaceId]));++ const byId = new Map(rows.map((row) => [row.id, row.metadata as Record<string, unknown> | null]));+ expect(readExecutionWorkspaceConfig(byId.get(matchingWorkspaceId) ?? null)).toMatchObject({+ environmentId: null,+ cleanupCommand: "echo clean",+ });+ expect(readExecutionWorkspaceConfig(byId.get(otherWorkspaceId) ?? null)).toMatchObject({+ environmentId: expect.any(String),+ });+ expect(readExecutionWorkspaceConfig(byId.get(untouchedWorkspaceId) ?? null)).toBeNull();+ });+it("warns about dirty and unmerged git worktrees and reports cleanup actions", async () => {const repoRoot = await createTempRepo();tempDirs.add(repoRoot);diff --git a/server/src/__tests__/heartbeat-process-recovery.test.ts b/server/src/__tests__/heartbeat-process-recovery.test.tsindex dbbcdc952a..fe0a24c6ab 100644--- a/server/src/__tests__/heartbeat-process-recovery.test.ts+++ b/server/src/__tests__/heartbeat-process-recovery.test.ts@@ -752,7 +752,10 @@ describeEmbeddedPostgres("heartbeat orphaned process recovery", () => {expect(blockedIssue?.executionRunId).toBeNull();expect(blockedIssue?.checkoutRunId).toBe(continuationRun?.id ?? null);- const comments = await db.select().from(issueComments).where(eq(issueComments.issueId, issueId));+ const comments = await waitForValue(async () => {+ const rows = await db.select().from(issueComments).where(eq(issueComments.issueId, issueId));+ return rows.length > 0 ? rows : null;+ });expect(comments).toHaveLength(1);expect(comments[0]?.body).toContain("retried continuation");});diff --git a/server/src/__tests__/instance-settings-routes.test.ts b/server/src/__tests__/instance-settings-routes.test.tsindex 6cabc2f063..72d408820e 100644--- a/server/src/__tests__/instance-settings-routes.test.ts+++ b/server/src/__tests__/instance-settings-routes.test.ts@@ -55,6 +55,7 @@ describe("instance settings routes", () => {feedbackDataSharingPreference: "prompt",});mockInstanceSettingsService.getExperimental.mockResolvedValue({+ enableEnvironments: false,enableIsolatedWorkspaces: false,autoRestartDevServerWhenIdle: false,});@@ -69,6 +70,7 @@ describe("instance settings routes", () => {mockInstanceSettingsService.updateExperimental.mockResolvedValue({id: "instance-settings-1",experimental: {+ enableEnvironments: true,enableIsolatedWorkspaces: true,autoRestartDevServerWhenIdle: false,},@@ -87,6 +89,7 @@ describe("instance settings routes", () => {const getRes = await request(app).get("/api/instance/settings/experimental");expect(getRes.status).toBe(200);expect(getRes.body).toEqual({+ enableEnvironments: false,enableIsolatedWorkspaces: false,autoRestartDevServerWhenIdle: false,});@@ -120,6 +123,24 @@ describe("instance settings routes", () => {});});+ it("allows local board users to update environment controls", async () => {+ const app = await createApp({+ type: "board",+ userId: "local-board",+ source: "local_implicit",+ isInstanceAdmin: true,+ });++ await request(app)+ .patch("/api/instance/settings/experimental")+ .send({ enableEnvironments: true })+ .expect(200);++ expect(mockInstanceSettingsService.updateExperimental).toHaveBeenCalledWith({+ enableEnvironments: true,+ });+ });+it("allows local board users to read and update general settings", async () => {const app = await createApp({type: "board",diff --git a/server/src/__tests__/invite-test-resolution-route.test.ts b/server/src/__tests__/invite-test-resolution-route.test.tsindex 35fd9eef4d..a89449b3d1 100644--- a/server/src/__tests__/invite-test-resolution-route.test.ts+++ b/server/src/__tests__/invite-test-resolution-route.test.ts@@ -77,25 +77,8 @@ async function createApp(return app;}-describe("GET /invites/:token/test-resolution", () => {+describe.sequential("GET /invites/:token/test-resolution", () => {beforeEach(() => {- vi.resetModules();- vi.doUnmock("node:dns/promises");- vi.doUnmock("node:http");- vi.doUnmock("node:https");- vi.doUnmock("node:net");- vi.doUnmock("../board-claim.js");- vi.doUnmock("../services/index.js");- vi.doUnmock("../storage/index.js");- vi.doUnmock("../middleware/logger.js");- vi.doUnmock("../routes/access.js");- vi.doUnmock("../routes/authz.js");- vi.doUnmock("../middleware/index.js");- vi.doMock("node:dns/promises", async () => vi.importActual("node:dns/promises"));- vi.doMock("node:http", async () => vi.importActual("node:http"));- vi.doMock("node:https", async () => vi.importActual("node:https"));- vi.doMock("node:net", async () => vi.importActual("node:net"));- vi.doMock("../routes/authz.js", async () => vi.importActual("../routes/authz.js"));currentAccessModule = null;});diff --git a/server/src/__tests__/paperclip-env.test.ts b/server/src/__tests__/paperclip-env.test.tsindex 1a65d9e9e3..2d922d5858 100644--- a/server/src/__tests__/paperclip-env.test.ts+++ b/server/src/__tests__/paperclip-env.test.ts@@ -1,6 +1,7 @@import { afterEach, describe, expect, it } from "vitest";import { buildPaperclipEnv } from "../adapters/utils.js";+const ORIGINAL_PAPERCLIP_RUNTIME_API_URL = process.env.PAPERCLIP_RUNTIME_API_URL;const ORIGINAL_PAPERCLIP_API_URL = process.env.PAPERCLIP_API_URL;const ORIGINAL_PAPERCLIP_LISTEN_HOST = process.env.PAPERCLIP_LISTEN_HOST;const ORIGINAL_PAPERCLIP_LISTEN_PORT = process.env.PAPERCLIP_LISTEN_PORT;@@ -8,6 +9,9 @@ const ORIGINAL_HOST = process.env.HOST;const ORIGINAL_PORT = process.env.PORT;afterEach(() => {+ if (ORIGINAL_PAPERCLIP_RUNTIME_API_URL === undefined) delete process.env.PAPERCLIP_RUNTIME_API_URL;+ else process.env.PAPERCLIP_RUNTIME_API_URL = ORIGINAL_PAPERCLIP_RUNTIME_API_URL;+if (ORIGINAL_PAPERCLIP_API_URL === undefined) delete process.env.PAPERCLIP_API_URL;else process.env.PAPERCLIP_API_URL = ORIGINAL_PAPERCLIP_API_URL;@@ -25,7 +29,19 @@ afterEach(() => {});describe("buildPaperclipEnv", () => {- it("prefers an explicit PAPERCLIP_API_URL", () => {+ it("prefers an explicit PAPERCLIP_RUNTIME_API_URL", () => {+ process.env.PAPERCLIP_RUNTIME_API_URL = "http://100.104.161.29:3102";+ process.env.PAPERCLIP_API_URL = "http://localhost:4100";+ process.env.PAPERCLIP_LISTEN_HOST = "127.0.0.1";+ process.env.PAPERCLIP_LISTEN_PORT = "3101";++ const env = buildPaperclipEnv({ id: "agent-1", companyId: "company-1" });++ expect(env.PAPERCLIP_API_URL).toBe("http://100.104.161.29:3102");+ });++ it("falls back to PAPERCLIP_API_URL when no runtime URL is configured", () => {+ delete process.env.PAPERCLIP_RUNTIME_API_URL;process.env.PAPERCLIP_API_URL = "http://localhost:4100";process.env.PAPERCLIP_LISTEN_HOST = "127.0.0.1";process.env.PAPERCLIP_LISTEN_PORT = "3101";diff --git a/server/src/__tests__/project-goal-telemetry-routes.test.ts b/server/src/__tests__/project-goal-telemetry-routes.test.tsindex 753fd3e8c1..e81041a752 100644--- a/server/src/__tests__/project-goal-telemetry-routes.test.ts+++ b/server/src/__tests__/project-goal-telemetry-routes.test.ts@@ -22,6 +22,9 @@ const mockWorkspaceOperationService = vi.hoisted(() => ({}));const mockSecretService = vi.hoisted(() => ({normalizeEnvBindingsForPersistence: vi.fn(),}));+const mockEnvironmentService = vi.hoisted(() => ({+ getById: vi.fn(),+}));const mockLogActivity = vi.hoisted(() => vi.fn());const mockGetTelemetryClient = vi.hoisted(() => vi.fn());const mockTelemetryTrack = vi.hoisted(() => vi.fn());@@ -31,6 +34,7 @@ vi.mock("../telemetry.js", () => ({}));vi.mock("../services/index.js", () => ({+ environmentService: () => mockEnvironmentService,goalService: () => mockGoalService,logActivity: mockLogActivity,projectService: () => mockProjectService,@@ -49,6 +53,7 @@ function registerModuleMocks() {}));vi.doMock("../services/index.js", () => ({+ environmentService: () => mockEnvironmentService,goalService: () => mockGoalService,logActivity: mockLogActivity,projectService: () => mockProjectService,@@ -107,6 +112,7 @@ describe("project and goal telemetry routes", () => {vi.resetAllMocks();mockGetTelemetryClient.mockReturnValue({ track: mockTelemetryTrack });mockProjectService.resolveByReference.mockResolvedValue({ ambiguous: false, project: null });+ mockEnvironmentService.getById.mockReset();mockSecretService.normalizeEnvBindingsForPersistence.mockImplementation(async (_companyId, env) => env);mockProjectService.create.mockResolvedValue({id: "project-1",diff --git a/server/src/__tests__/project-routes-env.test.ts b/server/src/__tests__/project-routes-env.test.tsindex b0a7e78374..5122594653 100644--- a/server/src/__tests__/project-routes-env.test.ts+++ b/server/src/__tests__/project-routes-env.test.ts@@ -17,6 +17,9 @@ const mockProjectService = vi.hoisted(() => ({const mockSecretService = vi.hoisted(() => ({normalizeEnvBindingsForPersistence: vi.fn(),}));+const mockEnvironmentService = vi.hoisted(() => ({+ getById: vi.fn(),+}));const mockWorkspaceOperationService = vi.hoisted(() => ({}));const mockLogActivity = vi.hoisted(() => vi.fn());const mockGetTelemetryClient = vi.hoisted(() => vi.fn());@@ -26,6 +29,7 @@ vi.mock("../telemetry.js", () => ({}));vi.mock("../services/index.js", () => ({+ environmentService: () => mockEnvironmentService,logActivity: mockLogActivity,projectService: () => mockProjectService,secretService: () => mockSecretService,@@ -43,6 +47,7 @@ function registerModuleMocks() {}));vi.doMock("../services/index.js", () => ({+ environmentService: () => mockEnvironmentService,logActivity: mockLogActivity,projectService: () => mockProjectService,secretService: () => mockSecretService,@@ -127,6 +132,7 @@ describe("project env routes", () => {mockProjectService.resolveByReference.mockResolvedValue({ ambiguous: false, project: null });mockProjectService.createWorkspace.mockResolvedValue(null);mockProjectService.listWorkspaces.mockResolvedValue([]);+ mockEnvironmentService.getById.mockReset();mockSecretService.normalizeEnvBindingsForPersistence.mockImplementation(async (_companyId, env) => env);});diff --git a/server/src/__tests__/workspace-runtime-routes-authz.test.ts b/server/src/__tests__/workspace-runtime-routes-authz.test.tsindex 0b7c4d7cb3..b659b0c12e 100644--- a/server/src/__tests__/workspace-runtime-routes-authz.test.ts+++ b/server/src/__tests__/workspace-runtime-routes-authz.test.ts@@ -20,6 +20,9 @@ const mockExecutionWorkspaceService = vi.hoisted(() => ({const mockSecretService = vi.hoisted(() => ({normalizeEnvBindingsForPersistence: vi.fn(),}));+const mockEnvironmentService = vi.hoisted(() => ({+ getById: vi.fn(),+}));const mockWorkspaceOperationService = vi.hoisted(() => ({}));const mockLogActivity = vi.hoisted(() => vi.fn());@@ -34,6 +37,7 @@ function registerModuleMocks() {vi.doMock("../services/index.js", () => ({executionWorkspaceService: () => mockExecutionWorkspaceService,+ environmentService: () => mockEnvironmentService,logActivity: mockLogActivity,projectService: () => mockProjectService,secretService: () => mockSecretService,@@ -158,6 +162,7 @@ describe("workspace runtime service route authorization", () => {vi.doUnmock("../middleware/index.js");registerModuleMocks();vi.resetAllMocks();+ mockEnvironmentService.getById.mockReset();mockSecretService.normalizeEnvBindingsForPersistence.mockImplementation(async (_companyId, env) => env);mockProjectService.resolveByReference.mockResolvedValue({ ambiguous: false, project: null });mockProjectService.create.mockResolvedValue(buildProject());diff --git a/server/src/app.ts b/server/src/app.tsindex e8c58386a8..6625f88505 100644--- a/server/src/app.ts+++ b/server/src/app.ts@@ -17,6 +17,7 @@ import { projectRoutes } from "./routes/projects.js";import { issueRoutes } from "./routes/issues.js";import { issueTreeControlRoutes } from "./routes/issue-tree-control.js";import { routineRoutes } from "./routes/routines.js";+import { environmentRoutes } from "./routes/environments.js";import { executionWorkspaceRoutes } from "./routes/execution-workspaces.js";import { goalRoutes } from "./routes/goals.js";import { approvalRoutes } from "./routes/approvals.js";@@ -43,7 +44,7 @@ import { pluginUiStaticRoutes } from "./routes/plugin-ui-static.js";import { applyUiBranding } from "./ui-branding.js";import { logger } from "./middleware/logger.js";import { DEFAULT_LOCAL_PLUGIN_DIR, pluginLoader } from "./services/plugin-loader.js";-import { createPluginWorkerManager } from "./services/plugin-worker-manager.js";+import { createPluginWorkerManager, type PluginWorkerManager } from "./services/plugin-worker-manager.js";import { createPluginJobScheduler } from "./services/plugin-job-scheduler.js";import { pluginJobStore } from "./services/plugin-job-store.js";import { createPluginToolDispatcher } from "./services/plugin-tool-dispatcher.js";@@ -129,6 +130,7 @@ export async function createApp(hostVersion?: string;localPluginDir?: string;pluginMigrationDb?: Db;+ pluginWorkerManager?: PluginWorkerManager;betterAuthHandler?: express.RequestHandler;resolveSession?: (req: ExpressRequest) => Promise<BetterAuthSessionResult | null>;},@@ -170,6 +172,9 @@ export async function createApp(}app.use(llmRoutes(db));+ const hostServicesDisposers = new Map<string, () => void>();+ const workerManager = opts.pluginWorkerManager ?? createPluginWorkerManager();+// Mount API routesconst api = Router();api.use(boardMutationGuard());@@ -192,6 +197,7 @@ export async function createApp(}));api.use(issueTreeControlRoutes(db));api.use(routineRoutes(db));+ api.use(environmentRoutes(db));api.use(executionWorkspaceRoutes(db));api.use(goalRoutes(db));api.use(approvalRoutes(db));@@ -207,8 +213,6 @@ export async function createApp(if (opts.databaseBackupService) {api.use(instanceDatabaseBackupRoutes(opts.databaseBackupService));}- const hostServicesDisposers = new Map<string, () => void>();- const workerManager = createPluginWorkerManager();const pluginRegistry = pluginRegistryService(db);const eventBus = createPluginEventBus();setPluginEventBus(eventBus);diff --git a/server/src/routes/agents.ts b/server/src/routes/agents.tsindex e73ab9156b..758182c81f 100644--- a/server/src/routes/agents.ts+++ b/server/src/routes/agents.ts@@ -23,6 +23,7 @@ import {updateAgentInstructionsPathSchema,wakeAgentSchema,updateAgentSchema,+ supportedEnvironmentDriversForAdapter,} from "@paperclipai/shared";import {readPaperclipSkillSyncPreference,@@ -37,6 +38,7 @@ import {approvalService,companySkillService,budgetService,+ environmentService,heartbeatService,ISSUE_LIST_DEFAULT_LIMIT,issueApprovalService,@@ -76,6 +78,7 @@ import {resolveDefaultAgentInstructionsBundleRole,} from "../services/default-agent-instructions.js";import { getTelemetryClient } from "../telemetry.js";+import { assertEnvironmentSelectionForCompany } from "./environment-selection.js";const RUN_LOG_DEFAULT_LIMIT_BYTES = 256_000;const RUN_LOG_MAX_LIMIT_BYTES = 1024 * 1024;@@ -139,6 +142,17 @@ export function agentRoutes(db: Db) {const instanceSettings = instanceSettingsService(db);const strictSecretsMode = process.env.PAPERCLIP_SECRETS_STRICT_MODE === "true";+ async function assertAgentEnvironmentSelection(+ companyId: string,+ adapterType: string,+ environmentId: string | null | undefined,+ ) {+ if (environmentId === undefined || environmentId === null) return;+ await assertEnvironmentSelectionForCompany(environmentService(db), companyId, environmentId, {+ allowedDrivers: allowedEnvironmentDriversForAgent(adapterType),+ });+ }+async function getCurrentUserRedactionOptions() {return {enabled: (await instanceSettings.getGeneral()).censorUsernameInLogs,@@ -407,6 +421,10 @@ export function agentRoutes(db: Db) {return Object.hasOwn(value, key);}+ function allowedEnvironmentDriversForAgent(adapterType: string): string[] {+ return supportedEnvironmentDriversForAdapter(adapterType);+ }+async function resolveCompanyIdForAgentReference(req: Request): Promise<string | null> {const companyIdQuery = req.query.companyId;const requestedCompanyId =@@ -1609,6 +1627,7 @@ export function agentRoutes(db: Db) {createInput.adapterType,normalizedAdapterConfig,);+ await assertAgentEnvironmentSelection(companyId, createInput.adapterType, createInput.defaultEnvironmentId);const createdAgent = await svc.create(companyId, {...createInput,@@ -2065,6 +2084,15 @@ export function agentRoutes(db: Db) {effectiveAdapterConfig,);}+ if (touchesAdapterConfiguration || Object.prototype.hasOwnProperty.call(patchData, "defaultEnvironmentId")) {+ await assertAgentEnvironmentSelection(+ existing.companyId,+ requestedAdapterType,+ Object.prototype.hasOwnProperty.call(patchData, "defaultEnvironmentId")+ ? (typeof patchData.defaultEnvironmentId === "string" ? patchData.defaultEnvironmentId : null)+ : existing.defaultEnvironmentId,+ );+ }const actor = getActorInfo(req);const agent = await svc.update(id, patchData, {diff --git a/server/src/routes/environment-selection.ts b/server/src/routes/environment-selection.tsnew file mode 100644index 0000000000..c057bd1b2b--- /dev/null+++ b/server/src/routes/environment-selection.ts@@ -0,0 +1,32 @@+import { unprocessable } from "../errors.js";++export async function assertEnvironmentSelectionForCompany(+ environmentsSvc: {+ getById(environmentId: string): Promise<{+ id: string;+ companyId: string;+ driver: string;+ status?: string | null;+ config: Record<string, unknown> | null;+ } | null>;+ },+ companyId: string,+ environmentId: string | null | undefined,+ options?: {+ allowedDrivers?: string[];+ },+) {+ if (environmentId === undefined || environmentId === null) return;+ const environment = await environmentsSvc.getById(environmentId);+ if (!environment || environment.companyId !== companyId) {+ throw unprocessable("Environment not found.");+ }+ if (environment.status === "archived") {+ throw unprocessable("Environment is archived.");+ }+ if (options?.allowedDrivers && !options.allowedDrivers.includes(environment.driver)) {+ throw unprocessable(+ `Environment driver "${environment.driver}" is not allowed here. Allowed drivers: ${options.allowedDrivers.join(", ")}`,+ );+ }+}diff --git a/server/src/routes/environments.ts b/server/src/routes/environments.tsnew file mode 100644index 0000000000..4e0bbcc4b1--- /dev/null+++ b/server/src/routes/environments.ts@@ -0,0 +1,423 @@+import { Router, type Request } from "express";+import type { Db } from "@paperclipai/db";+import {+ AGENT_ADAPTER_TYPES,+ createEnvironmentSchema,+ getEnvironmentCapabilities,+ probeEnvironmentConfigSchema,+ updateEnvironmentSchema,+} from "@paperclipai/shared";+import { forbidden } from "../errors.js";+import { validate } from "../middleware/validate.js";+import {+ accessService,+ agentService,+ environmentService,+ executionWorkspaceService,+ issueService,+ logActivity,+ projectService,+} from "../services/index.js";+import {+ normalizeEnvironmentConfigForPersistence,+ normalizeEnvironmentConfigForProbe,+ parseEnvironmentDriverConfig,+ readSshEnvironmentPrivateKeySecretId,+ type ParsedEnvironmentConfig,+} from "../services/environment-config.js";+import { probeEnvironment } from "../services/environment-probe.js";+import { secretService } from "../services/secrets.js";+import { assertCompanyAccess, getActorInfo } from "./authz.js";++export function environmentRoutes(db: Db) {+ const router = Router();+ const agents = agentService(db);+ const access = accessService(db);+ const svc = environmentService(db);+ const executionWorkspaces = executionWorkspaceService(db);+ const issues = issueService(db);+ const projects = projectService(db);+ const secrets = secretService(db);++ function parseObject(value: unknown): Record<string, unknown> {+ return value && typeof value === "object" && !Array.isArray(value)+ ? (value as Record<string, unknown>)+ : {};+ }++ function canCreateAgents(agent: { permissions: Record<string, unknown> | null | undefined }) {+ if (!agent.permissions || typeof agent.permissions !== "object") return false;+ return Boolean((agent.permissions as Record<string, unknown>).canCreateAgents);+ }++ async function assertCanMutateEnvironments(req: Request, companyId: string) {+ assertCompanyAccess(req, companyId);++ if (req.actor.type === "board") {+ if (req.actor.source === "local_implicit" || req.actor.isInstanceAdmin) return;+ const allowed = await access.canUser(companyId, req.actor.userId, "environments:manage");+ if (!allowed) {+ throw forbidden("Missing permission: environments:manage");+ }+ return;+ }++ if (!req.actor.agentId) {+ throw forbidden("Agent authentication required");+ }++ const actorAgent = await agents.getById(req.actor.agentId);+ if (!actorAgent || actorAgent.companyId !== companyId) {+ throw forbidden("Agent key cannot access another company");+ }++ const allowedByGrant = await access.hasPermission(companyId, "agent", actorAgent.id, "environments:manage");+ if (allowedByGrant || canCreateAgents(actorAgent)) {+ return;+ }++ throw forbidden("Missing permission: environments:manage");+ }++ async function actorCanReadEnvironmentConfigurations(req: Request, companyId: string) {+ assertCompanyAccess(req, companyId);++ if (req.actor.type === "board") {+ if (req.actor.source === "local_implicit" || req.actor.isInstanceAdmin) return true;+ return access.canUser(companyId, req.actor.userId, "environments:manage");+ }++ if (!req.actor.agentId) return false;+ const actorAgent = await agents.getById(req.actor.agentId);+ if (!actorAgent || actorAgent.companyId !== companyId) return false;+ const allowedByGrant = await access.hasPermission(companyId, "agent", actorAgent.id, "environments:manage");+ return allowedByGrant || canCreateAgents(actorAgent);+ }++ function redactEnvironmentForRestrictedView<T extends {+ config: Record<string, unknown>;+ metadata: Record<string, unknown> | null;+ }>(environment: T): T & { configRedacted: true; metadataRedacted: true } {+ return {+ ...environment,+ config: {},+ metadata: null,+ configRedacted: true,+ metadataRedacted: true,+ };+ }++ function summarizeEnvironmentUpdate(+ patch: Record<string, unknown>,+ environment: {+ name: string;+ driver: string;+ status: string;+ },+ ): Record<string, unknown> {+ const details: Record<string, unknown> = {+ changedFields: Object.keys(patch).sort(),+ };++ if (patch.name !== undefined) details.name = environment.name;+ if (patch.driver !== undefined) details.driver = environment.driver;+ if (patch.status !== undefined) details.status = environment.status;+ if (patch.description !== undefined) details.descriptionChanged = true;+ if (patch.config !== undefined) {+ details.configChanged = true;+ details.configTopLevelKeyCount =+ patch.config && typeof patch.config === "object" && !Array.isArray(patch.config)+ ? Object.keys(patch.config as Record<string, unknown>).length+ : 0;+ }+ if (patch.metadata !== undefined) {+ details.metadataChanged = true;+ details.metadataTopLevelKeyCount =+ patch.metadata && typeof patch.metadata === "object" && !Array.isArray(patch.metadata)+ ? Object.keys(patch.metadata as Record<string, unknown>).length+ : 0;+ }++ return details;+ }++ router.get("/companies/:companyId/environments", async (req, res) => {+ const companyId = req.params.companyId as string;+ assertCompanyAccess(req, companyId);+ const rows = await svc.list(companyId, {+ status: req.query.status as string | undefined,+ driver: req.query.driver as string | undefined,+ });+ const canReadConfigs = await actorCanReadEnvironmentConfigurations(req, companyId);+ if (canReadConfigs) {+ res.json(rows);+ return;+ }+ res.json(rows.map((environment) => redactEnvironmentForRestrictedView(environment)));+ });++ router.get("/companies/:companyId/environments/capabilities", async (req, res) => {+ const companyId = req.params.companyId as string;+ assertCompanyAccess(req, companyId);+ res.json(getEnvironmentCapabilities(AGENT_ADAPTER_TYPES));+ });++ router.post("/companies/:companyId/environments", validate(createEnvironmentSchema), async (req, res) => {+ const companyId = req.params.companyId as string;+ await assertCanMutateEnvironments(req, companyId);+ const actor = getActorInfo(req);+ const input = {+ ...req.body,+ config: await normalizeEnvironmentConfigForPersistence({+ db,+ companyId,+ environmentName: req.body.name,+ driver: req.body.driver,+ config: req.body.config,+ actor: {+ agentId: actor.agentId,+ userId: actor.actorType === "user" ? actor.actorId : null,+ },+ }),+ };+ const environment = await svc.create(companyId, input);+ await logActivity(db, {+ companyId,+ actorType: actor.actorType,+ actorId: actor.actorId,+ agentId: actor.agentId,+ runId: actor.runId,+ action: "environment.created",+ entityType: "environment",+ entityId: environment.id,+ details: {+ name: environment.name,+ driver: environment.driver,+ status: environment.status,+ },+ });+ res.status(201).json(environment);+ });++ router.get("/environments/:id", async (req, res) => {+ const environment = await svc.getById(req.params.id as string);+ if (!environment) {+ res.status(404).json({ error: "Environment not found" });+ return;+ }+ assertCompanyAccess(req, environment.companyId);+ const canReadConfigs = await actorCanReadEnvironmentConfigurations(req, environment.companyId);+ if (canReadConfigs) {+ res.json(environment);+ return;+ }+ res.json(redactEnvironmentForRestrictedView(environment));+ });++ router.get("/environments/:id/leases", async (req, res) => {+ const environment = await svc.getById(req.params.id as string);+ if (!environment) {+ res.status(404).json({ error: "Environment not found" });+ return;+ }+ assertCompanyAccess(req, environment.companyId);+ const canReadConfigs = await actorCanReadEnvironmentConfigurations(req, environment.companyId);+ if (!canReadConfigs) {+ throw forbidden("Missing permission: environments:manage");+ }+ const leases = await svc.listLeases(environment.id, {+ status: req.query.status as string | undefined,+ });+ res.json(leases);+ });++ router.get("/environment-leases/:leaseId", async (req, res) => {+ const lease = await svc.getLeaseById(req.params.leaseId as string);+ if (!lease) {+ res.status(404).json({ error: "Environment lease not found" });+ return;+ }+ assertCompanyAccess(req, lease.companyId);+ const canReadConfigs = await actorCanReadEnvironmentConfigurations(req, lease.companyId);+ if (!canReadConfigs) {+ throw forbidden("Missing permission: environments:manage");+ }+ res.json(lease);+ });++ router.patch("/environments/:id", validate(updateEnvironmentSchema), async (req, res) => {+ const existing = await svc.getById(req.params.id as string);+ if (!existing) {+ res.status(404).json({ error: "Environment not found" });+ return;+ }+ await assertCanMutateEnvironments(req, existing.companyId);+ const actor = getActorInfo(req);+ const nextDriver = req.body.driver ?? existing.driver;+ const nextName = req.body.name ?? existing.name;+ const configSource =+ req.body.config !== undefined+ ? req.body.driver !== undefined && req.body.driver !== existing.driver+ ? req.body.config+ : {+ ...parseObject(existing.config),+ ...parseObject(req.body.config),+ }+ : req.body.driver !== undefined && req.body.driver !== existing.driver+ ? {}+ : existing.config;+ const patch = {+ ...req.body,+ ...(req.body.config !== undefined || req.body.driver !== undefined+ ? {+ config: await normalizeEnvironmentConfigForPersistence({+ db,+ companyId: existing.companyId,+ environmentName: nextName,+ driver: nextDriver,+ config: configSource,+ actor: {+ agentId: actor.agentId,+ userId: actor.actorType === "user" ? actor.actorId : null,+ },+ }),+ }+ : {}),+ };+ const environment = await svc.update(existing.id, patch);+ if (!environment) {+ res.status(404).json({ error: "Environment not found" });+ return;+ }+ await logActivity(db, {+ companyId: environment.companyId,+ actorType: actor.actorType,+ actorId: actor.actorId,+ agentId: actor.agentId,+ runId: actor.runId,+ action: "environment.updated",+ entityType: "environment",+ entityId: environment.id,+ details: summarizeEnvironmentUpdate(patch as Record<string, unknown>, environment),+ });+ res.json(environment);+ });++ router.delete("/environments/:id", async (req, res) => {+ const existing = await svc.getById(req.params.id as string);+ if (!existing) {+ res.status(404).json({ error: "Environment not found" });+ return;+ }+ await assertCanMutateEnvironments(req, existing.companyId);+ await Promise.all([+ executionWorkspaces.clearEnvironmentSelection(existing.companyId, existing.id),+ issues.clearExecutionWorkspaceEnvironmentSelection(existing.companyId, existing.id),+ projects.clearExecutionWorkspaceEnvironmentSelection(existing.companyId, existing.id),+ ]);+ const removed = await svc.remove(existing.id);+ if (!removed) {+ res.status(404).json({ error: "Environment not found" });+ return;+ }+ const secretId = readSshEnvironmentPrivateKeySecretId(existing);+ if (secretId) {+ await secrets.remove(secretId);+ }+ const actor = getActorInfo(req);+ await logActivity(db, {+ companyId: existing.companyId,+ actorType: actor.actorType,+ actorId: actor.actorId,+ agentId: actor.agentId,+ runId: actor.runId,+ action: "environment.deleted",+ entityType: "environment",+ entityId: removed.id,+ details: {+ name: removed.name,+ driver: removed.driver,+ status: removed.status,+ },+ });+ res.json(removed);+ });++ router.post("/environments/:id/probe", async (req, res) => {+ const environment = await svc.getById(req.params.id as string);+ if (!environment) {+ res.status(404).json({ error: "Environment not found" });+ return;+ }+ await assertCanMutateEnvironments(req, environment.companyId);+ const actor = getActorInfo(req);+ const probe = await probeEnvironment(db, environment);+ await logActivity(db, {+ companyId: environment.companyId,+ actorType: actor.actorType,+ actorId: actor.actorId,+ agentId: actor.agentId,+ runId: actor.runId,+ action: "environment.probed",+ entityType: "environment",+ entityId: environment.id,+ details: {+ driver: environment.driver,+ ok: probe.ok,+ summary: probe.summary,+ },+ });+ res.json(probe);+ });++ router.post(+ "/companies/:companyId/environments/probe-config",+ validate(probeEnvironmentConfigSchema),+ async (req, res) => {+ const companyId = req.params.companyId as string;+ await assertCanMutateEnvironments(req, companyId);+ const actor = getActorInfo(req);+ const normalizedConfig = normalizeEnvironmentConfigForProbe({+ driver: req.body.driver,+ config: req.body.config,+ });+ const environment = {+ id: "unsaved",+ companyId,+ name: req.body.name?.trim() || "Unsaved environment",+ description: req.body.description ?? null,+ driver: req.body.driver,+ status: "active" as const,+ config: normalizedConfig,+ metadata: req.body.metadata ?? null,+ createdAt: new Date(),+ updatedAt: new Date(),+ };+ const probe = await probeEnvironment(db, environment, {+ resolvedConfig: {+ driver: req.body.driver,+ config: normalizedConfig,+ } as ParsedEnvironmentConfig,+ });+ await logActivity(db, {+ companyId,+ actorType: actor.actorType,+ actorId: actor.actorId,+ agentId: actor.agentId,+ runId: actor.runId,+ action: "environment.probed_unsaved",+ entityType: "environment",+ entityId: "unsaved",+ details: {+ driver: environment.driver,+ ok: probe.ok,+ summary: probe.summary,+ configTopLevelKeyCount: Object.keys(environment.config).length,+ },+ });+ res.json(probe);+ },+ );++ return router;+}diff --git a/server/src/routes/issues.ts b/server/src/routes/issues.tsindex bb4454a521..aef722aa3a 100644--- a/server/src/routes/issues.ts+++ b/server/src/routes/issues.ts@@ -55,6 +55,7 @@ import {projectService,routineService,workProductService,+ environmentService,} from "../services/index.js";import { logger } from "../middleware/logger.js";import { conflict, forbidden, HttpError, notFound, unauthorized } from "../errors.js";@@ -71,6 +72,7 @@ import {SVG_CONTENT_TYPE,} from "../attachment-types.js";import { queueIssueAssignmentWakeup } from "../services/issue-assignment-wakeup.js";+import { assertEnvironmentSelectionForCompany } from "./environment-selection.js";import {applyIssueExecutionPolicyTransition,normalizeIssueExecutionPolicy,@@ -415,6 +417,19 @@ export function issueRoutes(return value === true || value === "true" || value === "1";}+ async function assertIssueEnvironmentSelection(+ companyId: string,+ environmentId: string | null | undefined,+ ) {+ if (environmentId === undefined || environmentId === null) return;+ await assertEnvironmentSelectionForCompany(+ environmentService(db),+ companyId,+ environmentId,+ { allowedDrivers: ["local", "ssh"] },+ );+ }+async function logExpiredRequestConfirmations(input: {issue: { id: string; companyId: string; identifier?: string | null };interactions: Array<{ id: string; kind: string; status: string; result?: unknown }>;@@ -1635,6 +1650,7 @@ export function issueRoutes(if (req.body.assigneeAgentId || req.body.assigneeUserId) {await assertCanAssignTasks(req, companyId);}+ await assertIssueEnvironmentSelection(companyId, req.body.executionWorkspaceSettings?.environmentId);const actor = getActorInfo(req);const executionPolicy = normalizeIssueExecutionPolicy(req.body.executionPolicy);@@ -1701,6 +1717,7 @@ export function issueRoutes(if (req.body.assigneeAgentId || req.body.assigneeUserId) {await assertCanAssignTasks(req, parent.companyId);}+ await assertIssueEnvironmentSelection(parent.companyId, req.body.executionWorkspaceSettings?.environmentId);const actor = getActorInfo(req);const executionPolicy = normalizeIssueExecutionPolicy(req.body.executionPolicy);@@ -1775,6 +1792,7 @@ export function issueRoutes(hiddenAt: hiddenAtRaw,...updateFields} = req.body;+ await assertIssueEnvironmentSelection(existing.companyId, updateFields.executionWorkspaceSettings?.environmentId);const requestedAssigneeAgentId =normalizedAssigneeAgentId === undefined ? existing.assigneeAgentId : normalizedAssigneeAgentId;const effectiveMoveToTodoRequested =diff --git a/server/src/routes/projects.ts b/server/src/routes/projects.tsindex 6b83aac5c2..c06d620157 100644--- a/server/src/routes/projects.ts+++ b/server/src/routes/projects.ts@@ -13,7 +13,7 @@ import {import type { WorkspaceRuntimeDesiredState, WorkspaceRuntimeServiceStateMap } from "@paperclipai/shared";import { trackProjectCreated } from "@paperclipai/shared/telemetry";import { validate } from "../middleware/validate.js";-import { projectService, logActivity, secretService, workspaceOperationService } from "../services/index.js";+import { environmentService, projectService, logActivity, secretService, workspaceOperationService } from "../services/index.js";import { conflict } from "../errors.js";import { assertCompanyAccess, getActorInfo } from "./authz.js";import {@@ -31,6 +31,7 @@ import {import { assertCanManageProjectWorkspaceRuntimeServices } from "./workspace-runtime-service-authz.js";import { getTelemetryClient } from "../telemetry.js";import { appendWithCap } from "../adapters/utils.js";+import { assertEnvironmentSelectionForCompany } from "./environment-selection.js";const WORKSPACE_CONTROL_OUTPUT_MAX_CHARS = 256 * 1024;@@ -40,6 +41,22 @@ export function projectRoutes(db: Db) {const secretsSvc = secretService(db);const workspaceOperations = workspaceOperationService(db);const strictSecretsMode = process.env.PAPERCLIP_SECRETS_STRICT_MODE === "true";+ const environmentsSvc = environmentService(db);++ async function assertProjectEnvironmentSelection(companyId: string, environmentId: string | null | undefined) {+ if (environmentId === undefined || environmentId === null) return;+ await assertEnvironmentSelectionForCompany(environmentsSvc, companyId, environmentId, {+ allowedDrivers: ["local", "ssh"],+ });+ }++ function readProjectPolicyEnvironmentId(policy: unknown): string | null | undefined {+ if (!policy || typeof policy !== "object" || !("environmentId" in policy)) {+ return undefined;+ }+ const environmentId = (policy as { environmentId?: unknown }).environmentId;+ return typeof environmentId === "string" || environmentId === null ? environmentId : undefined;+ }async function resolveCompanyIdForProjectReference(req: Request) {const companyIdQuery = req.query.companyId;@@ -103,6 +120,10 @@ export function projectRoutes(db: Db) {};const { workspace, ...projectData } = req.body as CreateProjectPayload;+ await assertProjectEnvironmentSelection(+ companyId,+ readProjectPolicyEnvironmentId(projectData.executionWorkspacePolicy),+ );assertNoAgentHostWorkspaceCommandMutation(req,[@@ -165,6 +186,10 @@ export function projectRoutes(db: Db) {req,collectProjectExecutionWorkspaceCommandPaths(body.executionWorkspacePolicy),);+ await assertProjectEnvironmentSelection(+ existing.companyId,+ readProjectPolicyEnvironmentId(body.executionWorkspacePolicy),+ );if (typeof body.archivedAt === "string") {body.archivedAt = new Date(body.archivedAt);}diff --git a/server/src/services/agents.ts b/server/src/services/agents.tsindex 512d0e89cc..0d4762cc9d 100644--- a/server/src/services/agents.ts+++ b/server/src/services/agents.ts@@ -38,6 +38,7 @@ const CONFIG_REVISION_FIELDS = ["adapterType","adapterConfig","runtimeConfig",+ "defaultEnvironmentId","budgetMonthlyCents","metadata",] as const;@@ -98,6 +99,7 @@ function buildConfigSnapshot(adapterType: row.adapterType,adapterConfig,runtimeConfig,+ defaultEnvironmentId: row.defaultEnvironmentId,budgetMonthlyCents: row.budgetMonthlyCents,metadata,};@@ -169,6 +171,10 @@ function configPatchFromSnapshot(snapshot: unknown): Partial<typeof agents.$infeadapterType: snapshot.adapterType,adapterConfig: isPlainRecord(snapshot.adapterConfig) ? snapshot.adapterConfig : {},runtimeConfig: isPlainRecord(snapshot.runtimeConfig) ? snapshot.runtimeConfig : {},+ defaultEnvironmentId:+ typeof snapshot.defaultEnvironmentId === "string" || snapshot.defaultEnvironmentId === null+ ? snapshot.defaultEnvironmentId+ : null,budgetMonthlyCents: Math.max(0, Math.floor(snapshot.budgetMonthlyCents)),metadata: isPlainRecord(snapshot.metadata) || snapshot.metadata === null ? snapshot.metadata : null,};diff --git a/server/src/services/environment-config.ts b/server/src/services/environment-config.tsnew file mode 100644index 0000000000..4fbb9fea86--- /dev/null+++ b/server/src/services/environment-config.ts@@ -0,0 +1,237 @@+import { randomUUID } from "node:crypto";+import { z } from "zod";+import type { Db } from "@paperclipai/db";+import type {+ Environment,+ EnvironmentDriver,+ LocalEnvironmentConfig,+ SshEnvironmentConfig,+} from "@paperclipai/shared";+import { unprocessable } from "../errors.js";+import { parseObject } from "../adapters/utils.js";+import { secretService } from "./secrets.js";++const secretRefSchema = z.object({+ type: z.literal("secret_ref"),+ secretId: z.string().uuid(),+ version: z.union([z.literal("latest"), z.number().int().positive()]).optional().default("latest"),+}).strict();++const sshEnvironmentConfigSchema = z.object({+ host: z.string({ required_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({ required_error: "SSH environments require a username." }).trim().min(1, "SSH environments require a username."),+ remoteWorkspacePath: z+ .string({ required_error: "SSH environments require a remote workspace path." })+ .trim()+ .min(1, "SSH environments require a remote workspace path.")+ .refine((value) => value.startsWith("/"), "SSH remote workspace path must be absolute."),+ privateKey: z.null().optional().default(null),+ privateKeySecretRef: secretRefSchema.optional().nullable().default(null),+ knownHosts: z+ .string()+ .trim()+ .optional()+ .nullable()+ .transform((value) => (value && value.length > 0 ? value : null)),+ strictHostKeyChecking: z.boolean().optional().default(true),+}).strict();++const sshEnvironmentConfigProbeSchema = sshEnvironmentConfigSchema.extend({+ privateKey: z+ .string()+ .trim()+ .optional()+ .nullable()+ .transform((value) => (value && value.length > 0 ? value : null)),+}).strict();++const sshEnvironmentConfigPersistenceSchema = sshEnvironmentConfigProbeSchema;++export type ParsedEnvironmentConfig =+ | { driver: "local"; config: LocalEnvironmentConfig }+ | { driver: "ssh"; config: SshEnvironmentConfig };++function toErrorMessage(error: z.ZodError) {+ const first = error.issues[0];+ if (!first) return "Invalid environment config.";+ return first.message;+}++function secretName(input: {+ environmentName: string;+ driver: EnvironmentDriver;+ field: string;+}) {+ const slug = input.environmentName+ .toLowerCase()+ .replace(/[^a-z0-9]+/g, "-")+ .replace(/^-+|-+$/g, "")+ .slice(0, 48) || "environment";+ return `environment-${input.driver}-${slug}-${input.field}-${randomUUID().slice(0, 8)}`;+}++async function createEnvironmentSecret(input: {+ db: Db;+ companyId: string;+ environmentName: string;+ driver: EnvironmentDriver;+ field: string;+ value: string;+ actor?: { userId?: string | null; agentId?: string | null };+}) {+ const created = await secretService(input.db).create(+ input.companyId,+ {+ name: secretName(input),+ provider: "local_encrypted",+ value: input.value,+ description: `Secret for ${input.environmentName} ${input.field}.`,+ },+ input.actor,+ );+ return {+ type: "secret_ref" as const,+ secretId: created.id,+ version: "latest" as const,+ };+}++export function normalizeEnvironmentConfig(input: {+ driver: EnvironmentDriver;+ config: Record<string, unknown> | null | undefined;+}): Record<string, unknown> {+ if (input.driver === "local") {+ return { ...parseObject(input.config) };+ }++ if (input.driver === "ssh") {+ const parsed = sshEnvironmentConfigSchema.safeParse(parseObject(input.config));+ if (!parsed.success) {+ throw unprocessable(toErrorMessage(parsed.error), {+ issues: parsed.error.issues,+ });+ }+ return parsed.data satisfies SshEnvironmentConfig;+ }++ throw unprocessable(`Unsupported environment driver "${input.driver}".`);+}++export function normalizeEnvironmentConfigForProbe(input: {+ driver: EnvironmentDriver;+ config: Record<string, unknown> | null | undefined;+}): Record<string, unknown> {+ if (input.driver === "ssh") {+ const parsed = sshEnvironmentConfigProbeSchema.safeParse(parseObject(input.config));+ if (!parsed.success) {+ throw unprocessable(toErrorMessage(parsed.error), {+ issues: parsed.error.issues,+ });+ }+ return parsed.data satisfies SshEnvironmentConfig;+ }++ return normalizeEnvironmentConfig(input);+}++export async function normalizeEnvironmentConfigForPersistence(input: {+ db: Db;+ companyId: string;+ environmentName: string;+ driver: EnvironmentDriver;+ config: Record<string, unknown> | null | undefined;+ actor?: { userId?: string | null; agentId?: string | null };+}): Promise<Record<string, unknown>> {+ if (input.driver === "ssh") {+ const parsed = sshEnvironmentConfigPersistenceSchema.safeParse(parseObject(input.config));+ if (!parsed.success) {+ throw unprocessable(toErrorMessage(parsed.error), {+ issues: parsed.error.issues,+ });+ }+ const secrets = secretService(input.db);+ const { privateKey, ...stored } = parsed.data;+ let nextPrivateKeySecretRef = stored.privateKeySecretRef;+ if (privateKey) {+ nextPrivateKeySecretRef = await createEnvironmentSecret({+ db: input.db,+ companyId: input.companyId,+ environmentName: input.environmentName,+ driver: input.driver,+ field: "private-key",+ value: privateKey,+ actor: input.actor,+ });+ if (+ stored.privateKeySecretRef &&+ stored.privateKeySecretRef.secretId !== nextPrivateKeySecretRef.secretId+ ) {+ await secrets.remove(stored.privateKeySecretRef.secretId);+ }+ }+ return {+ ...stored,+ privateKey: null,+ privateKeySecretRef: nextPrivateKeySecretRef,+ } satisfies SshEnvironmentConfig;+ }++ return normalizeEnvironmentConfig({+ driver: input.driver,+ config: input.config,+ });+}++export async function resolveEnvironmentDriverConfigForRuntime(+ db: Db,+ companyId: string,+ environment: Pick<Environment, "driver" | "config">,+): Promise<ParsedEnvironmentConfig> {+ const parsed = parseEnvironmentDriverConfig(environment);+ if (parsed.driver === "ssh" && parsed.config.privateKeySecretRef) {+ return {+ driver: "ssh",+ config: {+ ...parsed.config,+ privateKey: await secretService(db).resolveSecretValue(+ companyId,+ parsed.config.privateKeySecretRef.secretId,+ parsed.config.privateKeySecretRef.version ?? "latest",+ ),+ },+ };+ }++ return parsed;+}++export function readSshEnvironmentPrivateKeySecretId(+ environment: Pick<Environment, "driver" | "config">,+): string | null {+ if (environment.driver !== "ssh") return null;+ const parsed = sshEnvironmentConfigSchema.safeParse(parseObject(environment.config));+ if (!parsed.success) return null;+ return parsed.data.privateKeySecretRef?.secretId ?? null;+}++export function parseEnvironmentDriverConfig(+ environment: Pick<Environment, "driver" | "config">,+): ParsedEnvironmentConfig {+ if (environment.driver === "local") {+ return {+ driver: "local",+ config: { ...parseObject(environment.config) },+ };+ }++ if (environment.driver === "ssh") {+ const parsed = sshEnvironmentConfigSchema.parse(parseObject(environment.config));+ return {+ driver: "ssh",+ config: parsed,+ };+ }++ throw new Error(`Unsupported environment driver "${environment.driver}".`);+}diff --git a/server/src/services/environment-probe.ts b/server/src/services/environment-probe.tsnew file mode 100644index 0000000000..6ffcc597b7--- /dev/null+++ b/server/src/services/environment-probe.ts@@ -0,0 +1,77 @@+import type { Environment, EnvironmentProbeResult } from "@paperclipai/shared";+import type { Db } from "@paperclipai/db";+import { ensureSshWorkspaceReady } from "@paperclipai/adapter-utils/ssh";+import {+ resolveEnvironmentDriverConfigForRuntime,+ type ParsedEnvironmentConfig,+} from "./environment-config.js";+import os from "node:os";++export async function probeEnvironment(+ db: Db,+ environment: Environment,+ options: { resolvedConfig?: ParsedEnvironmentConfig } = {},+): Promise<EnvironmentProbeResult> {+ const parsed = options.resolvedConfig ?? await resolveEnvironmentDriverConfigForRuntime(db, environment.companyId, environment);++ if (parsed.driver === "local") {+ return {+ ok: true,+ driver: "local",+ summary: "Local environment is available on this Paperclip host.",+ details: {+ hostname: os.hostname(),+ cwd: process.cwd(),+ },+ };+ }++ try {+ const { remoteCwd } = await ensureSshWorkspaceReady(parsed.config);++ return {+ ok: true,+ driver: "ssh",+ summary: `Connected to ${parsed.config.username}@${parsed.config.host} and verified the remote workspace path.`,+ details: {+ host: parsed.config.host,+ port: parsed.config.port,+ username: parsed.config.username,+ remoteWorkspacePath: parsed.config.remoteWorkspacePath,+ remoteCwd,+ },+ };+ } catch (error) {+ const stderr =+ error && typeof error === "object" && "stderr" in error && typeof error.stderr === "string"+ ? error.stderr.trim()+ : "";+ const stdout =+ error && typeof error === "object" && "stdout" in error && typeof error.stdout === "string"+ ? error.stdout.trim()+ : "";+ const code =+ error && typeof error === "object" && "code" in error+ ? (error as { code?: unknown }).code+ : null;+ const message =+ stderr ||+ stdout ||+ (error instanceof Error ? error.message : String(error)) ||+ "SSH probe failed.";++ return {+ ok: false,+ driver: "ssh",+ summary: `SSH probe failed for ${parsed.config.username}@${parsed.config.host}.`,+ details: {+ host: parsed.config.host,+ port: parsed.config.port,+ username: parsed.config.username,+ remoteWorkspacePath: parsed.config.remoteWorkspacePath,+ error: message,+ code,+ },+ };+ }+}diff --git a/server/src/services/environments.ts b/server/src/services/environments.tsindex 26d1f88b6b..1eb5a2a8d6 100644--- a/server/src/services/environments.ts+++ b/server/src/services/environments.ts@@ -1,4 +1,4 @@-import { and, desc, eq } from "drizzle-orm";+import { and, desc, eq, sql } from "drizzle-orm";import type { Db } from "@paperclipai/db";import { environmentLeases, environments } from "@paperclipai/db";import {@@ -130,6 +130,7 @@ export function environmentService(db: Db) {}).onConflictDoNothing({target: [environments.companyId, environments.driver],+ where: sql`${environments.driver} = 'local'`,}).returning().then((rows) => rows[0] ?? null);@@ -189,6 +190,15 @@ export function environmentService(db: Db) {return row ? toEnvironment(row) : null;},+ remove: async (id: string): Promise<Environment | null> => {+ const row = await db+ .delete(environments)+ .where(eq(environments.id, id))+ .returning()+ .then((rows) => rows[0] ?? null);+ return row ? toEnvironment(row) : null;+ },+listLeases: async (environmentId: string,filters: {diff --git a/server/src/services/execution-workspace-policy.ts b/server/src/services/execution-workspace-policy.tsindex bb5ef76df2..ea89d4414f 100644--- a/server/src/services/execution-workspace-policy.ts+++ b/server/src/services/execution-workspace-policy.ts@@ -38,6 +38,7 @@ export function parseProjectExecutionWorkspacePolicy(raw: unknown): ProjectExecuconst defaultMode = asString(parsed.defaultMode, "");const defaultProjectWorkspaceId =typeof parsed.defaultProjectWorkspaceId === "string" ? parsed.defaultProjectWorkspaceId : undefined;+ const environmentId = typeof parsed.environmentId === "string" ? parsed.environmentId : undefined;const allowIssueOverride =typeof parsed.allowIssueOverride === "boolean" ? parsed.allowIssueOverride : undefined;const normalizedDefaultMode = (() => {@@ -58,6 +59,7 @@ export function parseProjectExecutionWorkspacePolicy(raw: unknown): ProjectExecu...(normalizedDefaultMode ? { defaultMode: normalizedDefaultMode } : {}),...(allowIssueOverride !== undefined ? { allowIssueOverride } : {}),...(defaultProjectWorkspaceId ? { defaultProjectWorkspaceId } : {}),+ ...(environmentId !== undefined ? { environmentId } : {}),...(workspaceStrategy ? { workspaceStrategy } : {}),...(parsed.workspaceRuntime && typeof parsed.workspaceRuntime === "object" && !Array.isArray(parsed.workspaceRuntime)? { workspaceRuntime: { ...(parsed.workspaceRuntime as Record<string, unknown>) } }@@ -109,6 +111,7 @@ export function parseIssueExecutionWorkspaceSettings(raw: unknown): IssueExecuti...(normalizedMode? { mode: normalizedMode as IssueExecutionWorkspaceSettings["mode"] }: {}),+ ...(typeof parsed.environmentId === "string" ? { environmentId: parsed.environmentId } : {}),...(workspaceStrategy ? { workspaceStrategy } : {}),...(parsed.workspaceRuntime && typeof parsed.workspaceRuntime === "object" && !Array.isArray(parsed.workspaceRuntime)? { workspaceRuntime: { ...(parsed.workspaceRuntime as Record<string, unknown>) } }@@ -116,6 +119,28 @@ export function parseIssueExecutionWorkspaceSettings(raw: unknown): IssueExecuti};}+export function resolveExecutionWorkspaceEnvironmentId(input: {+ projectPolicy: ProjectExecutionWorkspacePolicy | null;+ issueSettings: IssueExecutionWorkspaceSettings | null;+ workspaceConfig: { environmentId?: string | null } | null;+ agentDefaultEnvironmentId: string | null;+ defaultEnvironmentId: string;+}) {+ if (input.workspaceConfig?.environmentId !== undefined) {+ return input.workspaceConfig.environmentId ?? input.defaultEnvironmentId;+ }+ if (input.issueSettings?.environmentId !== undefined) {+ return input.issueSettings.environmentId ?? input.defaultEnvironmentId;+ }+ if (input.projectPolicy?.environmentId !== undefined) {+ return input.projectPolicy.environmentId ?? input.defaultEnvironmentId;+ }+ if (input.agentDefaultEnvironmentId !== null) {+ return input.agentDefaultEnvironmentId;+ }+ return input.defaultEnvironmentId;+}+export function defaultIssueExecutionWorkspaceSettingsForProject(projectPolicy: ProjectExecutionWorkspacePolicy | null,): IssueExecutionWorkspaceSettings | null {diff --git a/server/src/services/execution-workspaces.ts b/server/src/services/execution-workspaces.tsindex 6bbc05dabd..e5fa36a1cb 100644--- a/server/src/services/execution-workspaces.ts+++ b/server/src/services/execution-workspaces.ts@@ -203,6 +203,7 @@ export function readExecutionWorkspaceConfig(metadata: Record<string, unknown> |if (!raw) return null;const config: ExecutionWorkspaceConfig = {+ environmentId: readNullableString(raw.environmentId),provisionCommand: readNullableString(raw.provisionCommand),teardownCommand: readNullableString(raw.teardownCommand),cleanupCommand: readNullableString(raw.cleanupCommand),@@ -226,6 +227,7 @@ export function mergeExecutionWorkspaceConfig(): Record<string, unknown> | null {const nextMetadata = isRecord(metadata) ? { ...metadata } : {};const current = readExecutionWorkspaceConfig(metadata) ?? {+ environmentId: null,provisionCommand: null,teardownCommand: null,cleanupCommand: null,@@ -240,6 +242,7 @@ export function mergeExecutionWorkspaceConfig(}const nextConfig: ExecutionWorkspaceConfig = {+ environmentId: patch.environmentId !== undefined ? readNullableString(patch.environmentId) : current.environmentId,provisionCommand: patch.provisionCommand !== undefined ? readNullableString(patch.provisionCommand) : current.provisionCommand,teardownCommand: patch.teardownCommand !== undefined ? readNullableString(patch.teardownCommand) : current.teardownCommand,cleanupCommand: patch.cleanupCommand !== undefined ? readNullableString(patch.cleanupCommand) : current.cleanupCommand,@@ -260,6 +263,7 @@ export function mergeExecutionWorkspaceConfig(if (hasConfig) {nextMetadata.config = {+ environmentId: nextConfig.environmentId,provisionCommand: nextConfig.provisionCommand,teardownCommand: nextConfig.teardownCommand,cleanupCommand: nextConfig.cleanupCommand,@@ -739,6 +743,37 @@ export function executionWorkspaceService(db: Db) {.then((rows) => rows[0] ?? null);return row ? toExecutionWorkspace(row) : null;},++ clearEnvironmentSelection: async (companyId: string, environmentId: string) => {+ return db.transaction(async (tx) => {+ const rows = await tx+ .select({+ id: executionWorkspaces.id,+ metadata: executionWorkspaces.metadata,+ })+ .from(executionWorkspaces)+ .where(eq(executionWorkspaces.companyId, companyId));++ let cleared = 0;+ const updatedAt = new Date();+ for (const row of rows) {+ const metadata = (row.metadata as Record<string, unknown> | null) ?? null;+ const config = readExecutionWorkspaceConfig(metadata);+ if (config?.environmentId !== environmentId) continue;++ await tx+ .update(executionWorkspaces)+ .set({+ metadata: mergeExecutionWorkspaceConfig(metadata, { environmentId: null }),+ updatedAt,+ })+ .where(eq(executionWorkspaces.id, row.id));+ cleared += 1;+ }++ return cleared;+ });+ },};}diff --git a/server/src/services/heartbeat.ts b/server/src/services/heartbeat.tsindex 0618bea9be..8dbc3b74b8 100644--- a/server/src/services/heartbeat.ts+++ b/server/src/services/heartbeat.ts@@ -8,12 +8,19 @@ import type { Db } from "@paperclipai/db";import {AGENT_DEFAULT_MAX_CONCURRENT_RUNS,ISSUE_CONTINUATION_SUMMARY_DOCUMENT_KEY,+ isEnvironmentDriverSupportedForAdapter,type BillingType,type EnvironmentLeaseStatus,type ExecutionWorkspace,type ExecutionWorkspaceConfig,type RunLivenessState,} from "@paperclipai/shared";+import {+ ensureSshWorkspaceReady,+ findReachablePaperclipApiUrlOverSsh,+ type SshRemoteExecutionSpec,+} from "@paperclipai/adapter-utils/ssh";+import type { AdapterExecutionTarget } from "@paperclipai/adapter-utils/execution-target";import {agents,agentRuntimeState,@@ -98,8 +105,10 @@ import {issueExecutionWorkspaceModeForPersistedWorkspace,parseIssueExecutionWorkspaceSettings,parseProjectExecutionWorkspacePolicy,+ resolveExecutionWorkspaceEnvironmentId,resolveExecutionWorkspaceMode,} from "./execution-workspace-policy.js";+import { resolveEnvironmentDriverConfigForRuntime } from "./environment-config.js";import { instanceSettingsService } from "./instance-settings.js";import {RUN_LIVENESS_CONTINUATION_REASON,@@ -322,6 +331,27 @@ function leaseReleaseStatusForRunStatus(return status === "failed" || status === "timed_out" ? "failed" : "released";}+function runtimeApiUrlCandidates() {+ const candidates = [+ process.env.PAPERCLIP_RUNTIME_API_URL,+ process.env.PAPERCLIP_API_URL,+ process.env.PUBLIC_BASE_URL,+ ].filter((value): value is string => typeof value === "string" && value.trim().length > 0);+ const encoded = process.env.PAPERCLIP_RUNTIME_API_CANDIDATES_JSON;+ if (!encoded) return candidates;+ try {+ const parsed = JSON.parse(encoded);+ if (Array.isArray(parsed)) {+ candidates.push(+ ...parsed.filter((value): value is string => typeof value === "string" && value.trim().length > 0),+ );+ }+ } catch {+ logger.warn("Ignoring invalid PAPERCLIP_RUNTIME_API_CANDIDATES_JSON");+ }+ return candidates;+}+export function applyPersistedExecutionWorkspaceConfig(input: {config: Record<string, unknown>;workspaceConfig: ExecutionWorkspaceConfig | null;@@ -391,9 +421,19 @@ export function buildRealizedExecutionWorkspaceFromPersisted(input: {};}-function buildExecutionWorkspaceConfigSnapshot(config: Record<string, unknown>): Partial<ExecutionWorkspaceConfig> | null {+function buildExecutionWorkspaceConfigSnapshot(+ config: Record<string, unknown>,+ environmentId?: string | null,+): Partial<ExecutionWorkspaceConfig> | null {const strategy = parseObject(config.workspaceStrategy);const snapshot: Partial<ExecutionWorkspaceConfig> = {};+ // Persist the resolved environment onto the workspace so reused sessions stay on the+ // environment they were created against until the workspace itself is recreated/reset.+ const hasExplicitEnvironmentSelection = environmentId !== undefined;++ if (hasExplicitEnvironmentSelection) {+ snapshot.environmentId = environmentId ?? null;+ }if ("workspaceStrategy" in config) {snapshot.provisionCommand = typeof strategy.provisionCommand === "string" ? strategy.provisionCommand : null;@@ -426,7 +466,7 @@ function buildExecutionWorkspaceConfigSnapshot(config: Record<string, unknown>):if (typeof value === "object") return Object.keys(value).length > 0;return true;});- return hasSnapshot ? snapshot : null;+ return hasSnapshot || hasExplicitEnvironmentSelection ? snapshot : null;}function deriveRepoNameFromRepoUrl(repoUrl: string | null): string | null {@@ -5061,7 +5101,15 @@ export function heartbeatService(db: Db) {const mergedConfig = issueAssigneeOverrides?.adapterConfig? { ...persistedWorkspaceManagedConfig, ...issueAssigneeOverrides.adapterConfig }: persistedWorkspaceManagedConfig;- const configSnapshot = buildExecutionWorkspaceConfigSnapshot(mergedConfig);+ const defaultEnvironment = await environmentsSvc.ensureLocalEnvironment(agent.companyId);+ const selectedEnvironmentId = resolveExecutionWorkspaceEnvironmentId({+ projectPolicy: projectExecutionWorkspacePolicy,+ issueSettings: issueExecutionWorkspaceSettings,+ workspaceConfig: existingExecutionWorkspace?.config ?? null,+ agentDefaultEnvironmentId: agent.defaultEnvironmentId,+ defaultEnvironmentId: defaultEnvironment.id,+ });+ const configSnapshot = buildExecutionWorkspaceConfigSnapshot(mergedConfig, selectedEnvironmentId);const executionRunConfig = stripWorkspaceRuntimeFromExecutionRunConfig(mergedConfig);const { resolvedConfig, secretKeys } = await resolveExecutionRunAdapterConfig({companyId: agent.companyId,@@ -5294,26 +5342,105 @@ export function heartbeatService(db: Db) {})(),};context.paperclipWorkspaces = resolvedWorkspace.workspaceHints;- const localEnvironment = await environmentsSvc.ensureLocalEnvironment(agent.companyId);+ const selectedEnvironment =+ selectedEnvironmentId === defaultEnvironment.id+ ? defaultEnvironment+ : await environmentsSvc.getById(selectedEnvironmentId);+ if (!selectedEnvironment || selectedEnvironment.companyId !== agent.companyId) {+ throw notFound(`Environment "${selectedEnvironmentId}" not found.`);+ }+ if (selectedEnvironment.status !== "active") {+ throw conflict(`Environment "${selectedEnvironment.name}" is not active.`);+ }+ if (!isEnvironmentDriverSupportedForAdapter(agent.adapterType, selectedEnvironment.driver)) {+ throw conflict(+ `Adapter "${agent.adapterType}" does not support "${selectedEnvironment.driver}" environments.`,+ );+ }++ const selectedEnvironmentRuntimeConfig = await resolveEnvironmentDriverConfigForRuntime(+ db,+ agent.companyId,+ selectedEnvironment,+ );+ let environmentProvider = selectedEnvironment.driver;+ let environmentProviderLeaseId: string | null = null;+ let environmentLeaseMetadata: Record<string, unknown> = {+ driver: selectedEnvironment.driver,+ executionWorkspaceMode: persistedExecutionWorkspace?.mode ?? effectiveExecutionWorkspaceMode,+ cwd: executionWorkspace.cwd,+ };+ let executionTarget: AdapterExecutionTarget | null = null;+ let remoteExecution: SshRemoteExecutionSpec | null = null;++ if (selectedEnvironmentRuntimeConfig.driver === "ssh") {+ const { remoteCwd } = await ensureSshWorkspaceReady(selectedEnvironmentRuntimeConfig.config);+ const paperclipApiUrl = await findReachablePaperclipApiUrlOverSsh({+ config: selectedEnvironmentRuntimeConfig.config,+ candidates: runtimeApiUrlCandidates(),+ });+ remoteExecution = {+ ...selectedEnvironmentRuntimeConfig.config,+ remoteCwd,+ paperclipApiUrl,+ };+ environmentProvider = "ssh";+ environmentProviderLeaseId = `ssh://${selectedEnvironmentRuntimeConfig.config.username}@${selectedEnvironmentRuntimeConfig.config.host}:${selectedEnvironmentRuntimeConfig.config.port}${remoteCwd}`;+ environmentLeaseMetadata = {+ ...environmentLeaseMetadata,+ host: selectedEnvironmentRuntimeConfig.config.host,+ port: selectedEnvironmentRuntimeConfig.config.port,+ username: selectedEnvironmentRuntimeConfig.config.username,+ remoteWorkspacePath: selectedEnvironmentRuntimeConfig.config.remoteWorkspacePath,+ remoteCwd,+ paperclipApiUrl,+ };+ }+const environmentLease = await environmentsSvc.acquireLease({companyId: agent.companyId,- environmentId: localEnvironment.id,+ environmentId: selectedEnvironment.id,executionWorkspaceId: persistedExecutionWorkspace?.id ?? null,issueId: issueId ?? null,heartbeatRunId: run.id,leasePolicy: "ephemeral",- provider: "local",- metadata: {- driver: "local",- executionWorkspaceMode: persistedExecutionWorkspace?.mode ?? effectiveExecutionWorkspaceMode,- cwd: executionWorkspace.cwd,- },+ provider: environmentProvider,+ providerLeaseId: environmentProviderLeaseId,+ metadata: environmentLeaseMetadata,});+ if (remoteExecution) {+ executionTarget = {+ kind: "remote",+ transport: "ssh",+ environmentId: selectedEnvironment.id,+ leaseId: environmentLease.id,+ remoteCwd: remoteExecution.remoteCwd,+ paperclipApiUrl: remoteExecution.paperclipApiUrl,+ spec: remoteExecution,+ };+ }context.paperclipEnvironment = {- id: localEnvironment.id,- name: localEnvironment.name,- driver: localEnvironment.driver,+ id: selectedEnvironment.id,+ name: selectedEnvironment.name,+ driver: selectedEnvironment.driver,leaseId: environmentLease.id,+ ...(typeof environmentLease.metadata?.remoteCwd === "string"+ ? {+ remoteCwd: environmentLease.metadata.remoteCwd,+ host:+ typeof environmentLease.metadata?.host === "string"+ ? environmentLease.metadata.host+ : undefined,+ port:+ typeof environmentLease.metadata?.port === "number"+ ? environmentLease.metadata.port+ : undefined,+ username:+ typeof environmentLease.metadata?.username === "string"+ ? environmentLease.metadata.username+ : undefined,+ }+ : {}),};await logActivity(db, {companyId: agent.companyId,@@ -5325,8 +5452,8 @@ export function heartbeatService(db: Db) {entityType: "environment_lease",entityId: environmentLease.id,details: {- environmentId: localEnvironment.id,- driver: localEnvironment.driver,+ environmentId: selectedEnvironment.id,+ driver: selectedEnvironment.driver,leasePolicy: environmentLease.leasePolicy,provider: environmentLease.provider,executionWorkspaceId: environmentLease.executionWorkspaceId,@@ -5592,6 +5719,10 @@ export function heartbeatService(db: Db) {runtime: runtimeForAdapter,config: runtimeConfig,context,+ executionTarget,+ executionTransport: remoteExecution+ ? { remoteExecution: remoteExecution as unknown as Record<string, unknown> }+ : undefined,onLog,onMeta: onAdapterMeta,onSpawn: async (meta) => {diff --git a/server/src/services/instance-settings.ts b/server/src/services/instance-settings.tsindex 06e6f9df57..4a6abb9e9e 100644--- a/server/src/services/instance-settings.ts+++ b/server/src/services/instance-settings.ts@@ -38,11 +38,13 @@ function normalizeExperimentalSettings(raw: unknown): InstanceExperimentalSettinconst parsed = instanceExperimentalSettingsSchema.safeParse(raw ?? {});if (parsed.success) {return {+ enableEnvironments: parsed.data.enableEnvironments ?? false,enableIsolatedWorkspaces: parsed.data.enableIsolatedWorkspaces ?? false,autoRestartDevServerWhenIdle: parsed.data.autoRestartDevServerWhenIdle ?? false,};}return {+ enableEnvironments: false,enableIsolatedWorkspaces: false,autoRestartDevServerWhenIdle: false,};diff --git a/server/src/services/issues.ts b/server/src/services/issues.tsindex c611c73d51..013d0e9b51 100644--- a/server/src/services/issues.ts+++ b/server/src/services/issues.ts@@ -30,6 +30,7 @@ import {defaultIssueExecutionWorkspaceSettingsForProject,gateProjectExecutionWorkspacePolicy,issueExecutionWorkspaceModeForPersistedWorkspace,+ parseIssueExecutionWorkspaceSettings,parseProjectExecutionWorkspacePolicy,} from "./execution-workspace-policy.js";import { instanceSettingsService } from "./instance-settings.js";@@ -2191,6 +2192,36 @@ export function issueService(db: Db) {return dbOrTx === db ? db.transaction(runUpdate) : runUpdate(dbOrTx);},+ clearExecutionWorkspaceEnvironmentSelection: async (companyId: string, environmentId: string) => {+ const rows = await db+ .select({+ id: issues.id,+ executionWorkspaceSettings: issues.executionWorkspaceSettings,+ })+ .from(issues)+ .where(eq(issues.companyId, companyId));++ let cleared = 0;+ for (const row of rows) {+ const settings = parseIssueExecutionWorkspaceSettings(row.executionWorkspaceSettings);+ if (settings?.environmentId !== environmentId) continue;++ await db+ .update(issues)+ .set({+ executionWorkspaceSettings: {+ ...settings,+ environmentId: null,+ },+ updatedAt: new Date(),+ })+ .where(eq(issues.id, row.id));+ cleared += 1;+ }++ return cleared;+ },+remove: (id: string) =>db.transaction(async (tx) => {const attachmentAssetIds = await txdiff --git a/server/src/services/projects.ts b/server/src/services/projects.tsindex f653ea1a2f..2bcf7affe3 100644--- a/server/src/services/projects.ts+++ b/server/src/services/projects.ts@@ -523,6 +523,36 @@ export function projectService(db: Db) {return enriched ?? null;},+ clearExecutionWorkspaceEnvironmentSelection: async (companyId: string, environmentId: string) => {+ const rows = await db+ .select({+ id: projects.id,+ executionWorkspacePolicy: projects.executionWorkspacePolicy,+ })+ .from(projects)+ .where(eq(projects.companyId, companyId));++ let cleared = 0;+ for (const row of rows) {+ const policy = parseProjectExecutionWorkspacePolicy(row.executionWorkspacePolicy);+ if (policy?.environmentId !== environmentId) continue;++ await db+ .update(projects)+ .set({+ executionWorkspacePolicy: {+ ...policy,+ environmentId: null,+ },+ updatedAt: new Date(),+ })+ .where(eq(projects.id, row.id));+ cleared += 1;+ }++ return cleared;+ },+remove: (id: string) =>db.delete(projects)diff --git a/ui/src/api/environments.ts b/ui/src/api/environments.tsnew file mode 100644index 0000000000..28e2a35721--- /dev/null+++ b/ui/src/api/environments.ts@@ -0,0 +1,32 @@+import type { Environment, EnvironmentCapabilities, EnvironmentLease, EnvironmentProbeResult } from "@paperclipai/shared";+import { api } from "./client";++export const environmentsApi = {+ list: (companyId: string) => api.get<Environment[]>(`/companies/${companyId}/environments`),+ capabilities: (companyId: string) =>+ api.get<EnvironmentCapabilities>(`/companies/${companyId}/environments/capabilities`),+ lease: (leaseId: string) => api.get<EnvironmentLease>(`/environment-leases/${leaseId}`),+ create: (companyId: string, body: {+ name: string;+ description?: string | null;+ driver: "local" | "ssh";+ config?: Record<string, unknown>;+ metadata?: Record<string, unknown> | null;+ }) => api.post<Environment>(`/companies/${companyId}/environments`, body),+ update: (environmentId: string, body: {+ name?: string;+ description?: string | null;+ driver?: "local" | "ssh";+ status?: "active" | "archived";+ config?: Record<string, unknown>;+ metadata?: Record<string, unknown> | null;+ }) => api.patch<Environment>(`/environments/${environmentId}`, body),+ probe: (environmentId: string) => api.post<EnvironmentProbeResult>(`/environments/${environmentId}/probe`, {}),+ probeConfig: (companyId: string, body: {+ name?: string;+ description?: string | null;+ driver: "local" | "ssh";+ config?: Record<string, unknown>;+ metadata?: Record<string, unknown> | null;+ }) => api.post<EnvironmentProbeResult>(`/companies/${companyId}/environments/probe-config`, body),+};diff --git a/ui/src/components/AgentConfigForm.tsx b/ui/src/components/AgentConfigForm.tsxindex a053b26058..c786182063 100644--- a/ui/src/components/AgentConfigForm.tsx+++ b/ui/src/components/AgentConfigForm.tsx@@ -5,10 +5,13 @@ import type {AdapterEnvironmentTestResult,CompanySecret,EnvBinding,+ Environment,} from "@paperclipai/shared";-import { AGENT_DEFAULT_MAX_CONCURRENT_RUNS } from "@paperclipai/shared";+import { AGENT_DEFAULT_MAX_CONCURRENT_RUNS, supportedEnvironmentDriversForAdapter } from "@paperclipai/shared";import type { AdapterModel } from "../api/agents";import { agentsApi } from "../api/agents";+import { environmentsApi } from "../api/environments";+import { instanceSettingsApi } from "../api/instanceSettings";import { secretsApi } from "../api/secrets";import { assetsApi } from "../api/assets";import {@@ -186,7 +189,18 @@ export function AgentConfigForm(props: AgentConfigFormProps) {queryFn: () => secretsApi.list(selectedCompanyId!),enabled: Boolean(selectedCompanyId),});+ const { data: experimentalSettings } = useQuery({+ queryKey: queryKeys.instance.experimentalSettings,+ queryFn: () => instanceSettingsApi.getExperimental(),+ retry: false,+ });+ const environmentsEnabled = experimentalSettings?.enableEnvironments === true;+ const { data: environments = [] } = useQuery<Environment[]>({+ queryKey: selectedCompanyId ? queryKeys.environments.list(selectedCompanyId) : ["environments", "none"],+ queryFn: () => environmentsApi.list(selectedCompanyId!),+ enabled: Boolean(selectedCompanyId) && environmentsEnabled,+ });const createSecret = useMutation({mutationFn: (input: { name: string; value: string }) => {if (!selectedCompanyId) throw new Error("Select a company to create secrets");@@ -278,6 +292,14 @@ export function AgentConfigForm(props: AgentConfigFormProps) {const showLegacyWorkingDirectoryField =isLocal && shouldShowLegacyWorkingDirectoryField({ isCreate, adapterConfig: config });const uiAdapter = useMemo(() => getUIAdapter(adapterType), [adapterType]);+ const supportedEnvironmentDrivers = useMemo(+ () => new Set(supportedEnvironmentDriversForAdapter(adapterType)),+ [adapterType],+ );+ const runnableEnvironments = useMemo(+ () => environments.filter((environment) => supportedEnvironmentDrivers.has(environment.driver)),+ [environments, supportedEnvironmentDrivers],+ );// Fetch adapter models for the effective adapter typeconst {@@ -432,6 +454,9 @@ export function AgentConfigForm(props: AgentConfigFormProps) {heartbeat: mergedHeartbeat,};}, [isCreate, overlay.heartbeat, runtimeConfig, val]);+ const currentDefaultEnvironmentId = isCreate+ ? val!.defaultEnvironmentId ?? ""+ : eff("identity", "defaultEnvironmentId", props.agent.defaultEnvironmentId ?? "");return (<div className={cn("relative", cards && "space-y-6")}>{/* ---- Floating Save button (edit mode, when dirty) ---- */}@@ -528,6 +553,42 @@ export function AgentConfigForm(props: AgentConfigFormProps) {</div>)}+ {/* ---- Execution ---- */}+ {environmentsEnabled ? (+ <div className={cn(!cards && (isCreate ? "border-t border-border" : "border-b border-border"))}>+ {cards+ ? <h3 className="text-sm font-medium mb-3">Execution</h3>+ : <div className="px-4 py-2 text-xs font-medium text-muted-foreground">Execution</div>+ }+ <div className={cn(cards ? "border border-border rounded-lg p-4 space-y-3" : "px-4 pb-3 space-y-3")}>+ <Field+ label="Default environment"+ hint="Agent-level default execution target. Project and issue settings can still override this."+ >+ <select+ className={inputClass}+ value={currentDefaultEnvironmentId}+ onChange={(event) => {+ const nextValue = event.target.value;+ if (isCreate) {+ set!({ defaultEnvironmentId: nextValue });+ return;+ }+ mark("identity", "defaultEnvironmentId", nextValue || null);+ }}+ >+ <option value="">Company default (Local)</option>+ {runnableEnvironments.map((environment) => (+ <option key={environment.id} value={environment.id}>+ {environment.name} · {environment.driver}+ </option>+ ))}+ </select>+ </Field>+ </div>+ </div>+ ) : null}+{/* ---- Adapter ---- */}<div className={cn(!cards && (isCreate ? "border-t border-border" : "border-b border-border"))}><div className={cn(cards ? "flex items-center justify-between mb-3" : "px-4 py-2 flex items-center justify-between gap-2")}>diff --git a/ui/src/components/ProjectProperties.tsx b/ui/src/components/ProjectProperties.tsxindex d7ace08c33..d9b33bd574 100644--- a/ui/src/components/ProjectProperties.tsx+++ b/ui/src/components/ProjectProperties.tsx@@ -4,6 +4,7 @@ import { useMutation, useQuery, useQueryClient } from "@tanstack/react-query";import type { Project } from "@paperclipai/shared";import { StatusBadge } from "./StatusBadge";import { cn, formatDate } from "../lib/utils";+import { environmentsApi } from "../api/environments";import { goalsApi } from "../api/goals";import { instanceSettingsApi } from "../api/instanceSettings";import { projectsApi } from "../api/projects";@@ -48,6 +49,7 @@ export type ProjectConfigFieldKey =| "env"| "execution_workspace_enabled"| "execution_workspace_default_mode"+ | "execution_workspace_environment"| "execution_workspace_base_ref"| "execution_workspace_branch_template"| "execution_workspace_worktree_parent_dir"@@ -248,6 +250,7 @@ export function ProjectProperties({ project, onUpdate, onFieldUpdate, getFieldSaqueryFn: () => instanceSettingsApi.getExperimental(),retry: false,});+ const environmentsEnabled = experimentalSettings?.enableEnvironments === true;const { data: availableSecrets = [] } = useQuery({queryKey: selectedCompanyId ? queryKeys.secrets.list(selectedCompanyId) : ["secrets", "none"],queryFn: () => secretsApi.list(selectedCompanyId!),@@ -263,6 +266,11 @@ export function ProjectProperties({ project, onUpdate, onFieldUpdate, getFieldSaqueryClient.invalidateQueries({ queryKey: queryKeys.secrets.list(selectedCompanyId) });},});+ const { data: environments } = useQuery({+ queryKey: queryKeys.environments.list(selectedCompanyId!),+ queryFn: () => environmentsApi.list(selectedCompanyId!),+ enabled: !!selectedCompanyId && environmentsEnabled,+ });const linkedGoalIds = project.goalIds.length > 0? project.goalIds@@ -287,12 +295,16 @@ export function ProjectProperties({ project, onUpdate, onFieldUpdate, getFieldSaconst isolatedWorkspacesEnabled = experimentalSettings?.enableIsolatedWorkspaces === true;const executionWorkspaceDefaultMode =executionWorkspacePolicy?.defaultMode === "isolated_workspace" ? "isolated_workspace" : "shared_workspace";+ const executionWorkspaceEnvironmentId = executionWorkspacePolicy?.environmentId ?? "";const executionWorkspaceStrategy = executionWorkspacePolicy?.workspaceStrategy ?? {type: "git_worktree",baseRef: "",branchTemplate: "",worktreeParentDir: "",};+ const runSelectableEnvironments = (environments ?? []).filter((environment) =>+ environment.driver === "local" || environment.driver === "ssh"+ );const invalidateProject = () => {queryClient.invalidateQueries({ queryKey: queryKeys.projects.detail(project.id) });@@ -985,6 +997,34 @@ export function ProjectProperties({ project, onUpdate, onFieldUpdate, getFieldSa<div className="text-xs text-muted-foreground">Host-managed implementation: <span className="text-foreground">Git worktree</span></div>+ {environmentsEnabled ? (+ <div>+ <div className="mb-1 flex items-center gap-1.5">+ <label className="flex items-center gap-2 text-xs text-muted-foreground">+ <span>Environment</span>+ <SaveIndicator state={fieldState("execution_workspace_environment")} />+ </label>+ </div>+ <select+ className="w-full rounded border border-border bg-transparent px-2 py-1 text-xs outline-none"+ value={executionWorkspaceEnvironmentId}+ onChange={(e) =>+ commitField(+ "execution_workspace_environment",+ updateExecutionWorkspacePolicy({+ environmentId: e.target.value || null,+ })!,+ )}+ >+ <option value="">No environment</option>+ {runSelectableEnvironments.map((environment) => (+ <option key={environment.id} value={environment.id}>+ {environment.name} · {environment.driver}+ </option>+ ))}+ </select>+ </div>+ ) : null}<div><div className="mb-1 flex items-center gap-1.5"><label className="flex items-center gap-2 text-xs text-muted-foreground">diff --git a/ui/src/lib/company-portability-sidebar.test.ts b/ui/src/lib/company-portability-sidebar.test.tsindex 68d0e13ff2..2b648fcf89 100644--- a/ui/src/lib/company-portability-sidebar.test.ts+++ b/ui/src/lib/company-portability-sidebar.test.ts@@ -20,6 +20,7 @@ function makeAgent(id: string, name: string): Agent {adapterType: "process",adapterConfig: {},runtimeConfig: {},+ defaultEnvironmentId: null,budgetMonthlyCents: 0,spentMonthlyCents: 0,pauseReason: null,diff --git a/ui/src/lib/new-agent-hire-payload.test.ts b/ui/src/lib/new-agent-hire-payload.test.tsnew file mode 100644index 0000000000..2bf9e47033--- /dev/null+++ b/ui/src/lib/new-agent-hire-payload.test.ts@@ -0,0 +1,44 @@+// @vitest-environment node+import { describe, expect, it } from "vitest";+import { buildNewAgentHirePayload } from "./new-agent-hire-payload";+import { defaultCreateValues } from "../components/agent-config-defaults";++describe("buildNewAgentHirePayload", () => {+ it("persists the selected default environment id", () => {+ expect(+ buildNewAgentHirePayload({+ name: "Linux Claude",+ effectiveRole: "general",+ configValues: {+ ...defaultCreateValues,+ adapterType: "claude_local",+ defaultEnvironmentId: "11111111-1111-4111-8111-111111111111",+ },+ adapterConfig: { foo: "bar" },+ }),+ ).toMatchObject({+ name: "Linux Claude",+ role: "general",+ adapterType: "claude_local",+ defaultEnvironmentId: "11111111-1111-4111-8111-111111111111",+ adapterConfig: { foo: "bar" },+ budgetMonthlyCents: 0,+ });+ });++ it("sends null when no default environment is selected", () => {+ expect(+ buildNewAgentHirePayload({+ name: "Local Claude",+ effectiveRole: "general",+ configValues: {+ ...defaultCreateValues,+ adapterType: "claude_local",+ },+ adapterConfig: {},+ }),+ ).toMatchObject({+ defaultEnvironmentId: null,+ });+ });+});diff --git a/ui/src/lib/new-agent-hire-payload.ts b/ui/src/lib/new-agent-hire-payload.tsnew file mode 100644index 0000000000..ce699de038--- /dev/null+++ b/ui/src/lib/new-agent-hire-payload.ts@@ -0,0 +1,38 @@+import type { CreateConfigValues } from "../components/AgentConfigForm";+import { buildNewAgentRuntimeConfig } from "./new-agent-runtime-config";++export function buildNewAgentHirePayload(input: {+ name: string;+ effectiveRole: string;+ title?: string;+ reportsTo?: string | null;+ selectedSkillKeys?: string[];+ configValues: CreateConfigValues;+ adapterConfig: Record<string, unknown>;+}) {+ const {+ name,+ effectiveRole,+ title,+ reportsTo,+ selectedSkillKeys = [],+ configValues,+ adapterConfig,+ } = input;++ return {+ name: name.trim(),+ role: effectiveRole,+ ...(title?.trim() ? { title: title.trim() } : {}),+ ...(reportsTo ? { reportsTo } : {}),+ ...(selectedSkillKeys.length > 0 ? { desiredSkills: selectedSkillKeys } : {}),+ adapterType: configValues.adapterType,+ defaultEnvironmentId: configValues.defaultEnvironmentId ?? null,+ adapterConfig,+ runtimeConfig: buildNewAgentRuntimeConfig({+ heartbeatEnabled: configValues.heartbeatEnabled,+ intervalSec: configValues.intervalSec,+ }),+ budgetMonthlyCents: 0,+ };+}diff --git a/ui/src/lib/queryKeys.ts b/ui/src/lib/queryKeys.tsindex 7fbec20f3f..c345b87afc 100644--- a/ui/src/lib/queryKeys.ts+++ b/ui/src/lib/queryKeys.ts@@ -73,6 +73,9 @@ export const queryKeys = {closeReadiness: (id: string) => ["execution-workspaces", "close-readiness", id] as const,workspaceOperations: (id: string) => ["execution-workspaces", "workspace-operations", id] as const,},+ environments: {+ list: (companyId: string) => ["environments", companyId] as const,+ },projects: {list: (companyId: string) => ["projects", companyId] as const,detail: (id: string) => ["projects", "detail", id] as const,diff --git a/ui/src/pages/CompanyAccess.tsx b/ui/src/pages/CompanyAccess.tsxindex b1ba9aa581..3f31fe1ef5 100644--- a/ui/src/pages/CompanyAccess.tsx+++ b/ui/src/pages/CompanyAccess.tsx@@ -35,6 +35,7 @@ const permissionLabels: Record<PermissionKey, string> = {"tasks:assign_scope": "Assign scoped tasks","tasks:manage_active_checkouts": "Manage active task checkouts","joins:approve": "Approve join requests",+ "environments:manage": "Manage environments",};function formatGrantSummary(member: CompanyMember) {diff --git a/ui/src/pages/CompanySettings.tsx b/ui/src/pages/CompanySettings.tsxindex bc27f879a7..7608b01382 100644--- a/ui/src/pages/CompanySettings.tsx+++ b/ui/src/pages/CompanySettings.tsx@@ -1,13 +1,22 @@import { ChangeEvent, useEffect, useState } from "react";import { Link } from "@/lib/router";-import { useMutation, useQueryClient } from "@tanstack/react-query";-import { DEFAULT_FEEDBACK_DATA_SHARING_TERMS_VERSION } from "@paperclipai/shared";+import { useMutation, useQuery, useQueryClient } from "@tanstack/react-query";+import {+ AGENT_ADAPTER_TYPES,+ DEFAULT_FEEDBACK_DATA_SHARING_TERMS_VERSION,+ getAdapterEnvironmentSupport,+ type Environment,+ type EnvironmentProbeResult,+} from "@paperclipai/shared";import { useCompany } from "../context/CompanyContext";import { useBreadcrumbs } from "../context/BreadcrumbContext";import { useToastActions } from "../context/ToastContext";import { companiesApi } from "../api/companies";import { accessApi } from "../api/access";import { assetsApi } from "../api/assets";+import { environmentsApi } from "../api/environments";+import { instanceSettingsApi } from "../api/instanceSettings";+import { secretsApi } from "../api/secrets";import { queryKeys } from "../lib/queryKeys";import { Button } from "@/components/ui/button";import { Settings, Check, Download, Upload } from "lucide-react";@@ -15,7 +24,8 @@ import { CompanyPatternIcon } from "../components/CompanyPatternIcon";import {Field,ToggleField,- HintIcon+ HintIcon,+ adapterLabels,} from "../components/agent-config-primitives";type AgentSnippetInput = {@@ -24,6 +34,104 @@ type AgentSnippetInput = {testResolutionUrl?: string | null;};+type EnvironmentFormState = {+ name: string;+ description: string;+ driver: "local" | "ssh";+ sshHost: string;+ sshPort: string;+ sshUsername: string;+ sshRemoteWorkspacePath: string;+ sshPrivateKey: string;+ sshPrivateKeySecretId: string;+ sshKnownHosts: string;+ sshStrictHostKeyChecking: boolean;+};++const ENVIRONMENT_SUPPORT_ROWS = AGENT_ADAPTER_TYPES.map((adapterType) => ({+ adapterType,+ support: getAdapterEnvironmentSupport(adapterType),+}));++function buildEnvironmentPayload(form: EnvironmentFormState) {+ return {+ name: form.name.trim(),+ description: form.description.trim() || null,+ driver: form.driver,+ config:+ form.driver === "ssh"+ ? {+ host: form.sshHost.trim(),+ port: Number.parseInt(form.sshPort || "22", 10) || 22,+ username: form.sshUsername.trim(),+ remoteWorkspacePath: form.sshRemoteWorkspacePath.trim(),+ privateKey: form.sshPrivateKey.trim() || null,+ privateKeySecretRef:+ form.sshPrivateKey.trim().length > 0 || !form.sshPrivateKeySecretId+ ? null+ : { type: "secret_ref" as const, secretId: form.sshPrivateKeySecretId, version: "latest" as const },+ knownHosts: form.sshKnownHosts.trim() || null,+ strictHostKeyChecking: form.sshStrictHostKeyChecking,+ }+ : {},+ } as const;+}++function createEmptyEnvironmentForm(): EnvironmentFormState {+ return {+ name: "",+ description: "",+ driver: "ssh",+ sshHost: "",+ sshPort: "22",+ sshUsername: "",+ sshRemoteWorkspacePath: "",+ sshPrivateKey: "",+ sshPrivateKeySecretId: "",+ sshKnownHosts: "",+ sshStrictHostKeyChecking: true,+ };+}++function readSshConfig(environment: Environment) {+ const config = environment.config ?? {};+ return {+ host: typeof config.host === "string" ? config.host : "",+ port:+ typeof config.port === "number"+ ? String(config.port)+ : typeof config.port === "string"+ ? config.port+ : "22",+ username: typeof config.username === "string" ? config.username : "",+ remoteWorkspacePath: typeof config.remoteWorkspacePath === "string" ? config.remoteWorkspacePath : "",+ privateKey: "",+ privateKeySecretId:+ config.privateKeySecretRef &&+ typeof config.privateKeySecretRef === "object" &&+ !Array.isArray(config.privateKeySecretRef) &&+ typeof (config.privateKeySecretRef as { secretId?: unknown }).secretId === "string"+ ? String((config.privateKeySecretRef as { secretId: string }).secretId)+ : "",+ knownHosts: typeof config.knownHosts === "string" ? config.knownHosts : "",+ strictHostKeyChecking:+ typeof config.strictHostKeyChecking === "boolean"+ ? config.strictHostKeyChecking+ : true,+ };+}++function SupportMark({ supported }: { supported: boolean }) {+ return supported ? (+ <span className="inline-flex items-center gap-1 text-green-700 dark:text-green-400">+ <Check className="h-3 w-3" />+ Yes+ </span>+ ) : (+ <span className="text-muted-foreground">No</span>+ );+}+const FEEDBACK_TERMS_URL = import.meta.env.VITE_FEEDBACK_TERMS_URL?.trim() || "https://paperclip.ing/tos";export function CompanySettings() {@@ -42,6 +150,9 @@ export function CompanySettings() {const [brandColor, setBrandColor] = useState("");const [logoUrl, setLogoUrl] = useState("");const [logoUploadError, setLogoUploadError] = useState<string | null>(null);+ const [editingEnvironmentId, setEditingEnvironmentId] = useState<string | null>(null);+ const [environmentForm, setEnvironmentForm] = useState<EnvironmentFormState>(createEmptyEnvironmentForm);+ const [probeResults, setProbeResults] = useState<Record<string, EnvironmentProbeResult | null>>({});// Sync local state from selected companyuseEffect(() => {@@ -57,6 +168,30 @@ export function CompanySettings() {const [snippetCopied, setSnippetCopied] = useState(false);const [snippetCopyDelightId, setSnippetCopyDelightId] = useState(0);+ const { data: experimentalSettings } = useQuery({+ queryKey: queryKeys.instance.experimentalSettings,+ queryFn: () => instanceSettingsApi.getExperimental(),+ retry: false,+ });+ const environmentsEnabled = experimentalSettings?.enableEnvironments === true;++ const { data: environments } = useQuery({+ queryKey: selectedCompanyId ? queryKeys.environments.list(selectedCompanyId) : ["environments", "none"],+ queryFn: () => environmentsApi.list(selectedCompanyId!),+ enabled: Boolean(selectedCompanyId) && environmentsEnabled,+ });+ const { data: environmentCapabilities } = useQuery({+ queryKey: selectedCompanyId ? ["environment-capabilities", selectedCompanyId] : ["environment-capabilities", "none"],+ queryFn: () => environmentsApi.capabilities(selectedCompanyId!),+ enabled: Boolean(selectedCompanyId) && environmentsEnabled,+ });++ const { data: secrets } = useQuery({+ queryKey: selectedCompanyId ? ["company-secrets", selectedCompanyId] : ["company-secrets", "none"],+ queryFn: () => secretsApi.list(selectedCompanyId!),+ enabled: Boolean(selectedCompanyId) && environmentsEnabled,+ });+const generalDirty =!!selectedCompany &&(companyName !== selectedCompany.name ||@@ -182,6 +317,90 @@ export function CompanySettings() {}});+ const environmentMutation = useMutation({+ mutationFn: async (form: EnvironmentFormState) => {+ const body = buildEnvironmentPayload(form);++ if (editingEnvironmentId) {+ return await environmentsApi.update(editingEnvironmentId, body);+ }++ return await environmentsApi.create(selectedCompanyId!, body);+ },+ onSuccess: async (environment) => {+ await queryClient.invalidateQueries({+ queryKey: queryKeys.environments.list(selectedCompanyId!),+ });+ setEditingEnvironmentId(null);+ setEnvironmentForm(createEmptyEnvironmentForm());+ pushToast({+ title: editingEnvironmentId ? "Environment updated" : "Environment created",+ body: `${environment.name} is ready.`,+ tone: "success",+ });+ },+ onError: (error) => {+ pushToast({+ title: "Failed to save environment",+ body: error instanceof Error ? error.message : "Environment save failed.",+ tone: "error",+ });+ },+ });++ const environmentProbeMutation = useMutation({+ mutationFn: async (environmentId: string) => await environmentsApi.probe(environmentId),+ onSuccess: (probe, environmentId) => {+ setProbeResults((current) => ({+ ...current,+ [environmentId]: probe,+ }));+ pushToast({+ title: probe.ok ? "Environment probe passed" : "Environment probe failed",+ body: probe.summary,+ tone: probe.ok ? "success" : "error",+ });+ },+ onError: (error, environmentId) => {+ const failedEnvironment = (environments ?? []).find((environment) => environment.id === environmentId);+ setProbeResults((current) => ({+ ...current,+ [environmentId]: {+ ok: false,+ driver: failedEnvironment?.driver ?? "local",+ summary: error instanceof Error ? error.message : "Environment probe failed.",+ details: null,+ },+ }));+ pushToast({+ title: "Environment probe failed",+ body: error instanceof Error ? error.message : "Environment probe failed.",+ tone: "error",+ });+ },+ });++ const draftEnvironmentProbeMutation = useMutation({+ mutationFn: async (form: EnvironmentFormState) => {+ const body = buildEnvironmentPayload(form);+ return await environmentsApi.probeConfig(selectedCompanyId!, body);+ },+ onSuccess: (probe) => {+ pushToast({+ title: probe.ok ? "Draft probe passed" : "Draft probe failed",+ body: probe.summary,+ tone: probe.ok ? "success" : "error",+ });+ },+ onError: (error) => {+ pushToast({+ title: "Draft probe failed",+ body: error instanceof Error ? error.message : "Environment probe failed.",+ tone: "error",+ });+ },+ });+function handleLogoFileChange(event: ChangeEvent<HTMLInputElement>) {const file = event.target.files?.[0] ?? null;event.currentTarget.value = "";@@ -199,6 +418,9 @@ export function CompanySettings() {setInviteSnippet(null);setSnippetCopied(false);setSnippetCopyDelightId(0);+ setEditingEnvironmentId(null);+ setEnvironmentForm(createEmptyEnvironmentForm());+ setProbeResults({});}, [selectedCompanyId]);const archiveMutation = useMutation({@@ -245,6 +467,49 @@ export function CompanySettings() {});}+ function handleEditEnvironment(environment: Environment) {+ setEditingEnvironmentId(environment.id);+ if (environment.driver === "ssh") {+ const ssh = readSshConfig(environment);+ setEnvironmentForm({+ ...createEmptyEnvironmentForm(),+ name: environment.name,+ description: environment.description ?? "",+ driver: "ssh",+ sshHost: ssh.host,+ sshPort: ssh.port,+ sshUsername: ssh.username,+ sshRemoteWorkspacePath: ssh.remoteWorkspacePath,+ sshPrivateKey: ssh.privateKey,+ sshPrivateKeySecretId: ssh.privateKeySecretId,+ sshKnownHosts: ssh.knownHosts,+ sshStrictHostKeyChecking: ssh.strictHostKeyChecking,+ });+ return;+ }++ setEnvironmentForm({+ ...createEmptyEnvironmentForm(),+ name: environment.name,+ description: environment.description ?? "",+ driver: "local",+ });+ }++ function handleCancelEnvironmentEdit() {+ setEditingEnvironmentId(null);+ setEnvironmentForm(createEmptyEnvironmentForm());+ }++ const environmentFormValid =+ environmentForm.name.trim().length > 0 &&+ (environmentForm.driver !== "ssh" ||+ (+ environmentForm.sshHost.trim().length > 0 &&+ environmentForm.sshUsername.trim().length > 0 &&+ environmentForm.sshRemoteWorkspacePath.trim().length > 0+ ));+return (<div className="max-w-2xl space-y-6"><div className="flex items-center gap-2">@@ -401,6 +666,290 @@ export function CompanySettings() {</div>)}+ {environmentsEnabled ? (+ <div className="space-y-4" data-testid="company-settings-environments-section">+ <div className="text-xs font-medium text-muted-foreground uppercase tracking-wide">+ Environments+ </div>+ <div className="space-y-4 rounded-md border border-border px-4 py-4">+ <div className="rounded-md border border-border/60 bg-muted/20 px-3 py-2 text-xs text-muted-foreground">+ Environment choices use the same adapter support matrix as agent defaults. SSH environments+ are available for remote-managed adapters.+ </div>++ <div className="overflow-x-auto">+ <table className="w-full min-w-[34rem] text-left text-xs">+ <caption className="sr-only">Environment support by adapter</caption>+ <thead className="border-b border-border text-muted-foreground">+ <tr>+ <th className="py-2 pr-3 font-medium">Adapter</th>+ <th className="px-3 py-2 font-medium">Local</th>+ <th className="px-3 py-2 font-medium">SSH</th>+ </tr>+ </thead>+ <tbody className="divide-y divide-border/60">+ {(environmentCapabilities?.adapters.map((support) => ({+ adapterType: support.adapterType,+ support,+ })) ?? ENVIRONMENT_SUPPORT_ROWS).map(({ adapterType, support }) => (+ <tr key={adapterType}>+ <td className="py-2 pr-3 font-medium">+ {adapterLabels[adapterType] ?? adapterType}+ </td>+ <td className="px-3 py-2">+ <SupportMark supported={support.drivers.local === "supported"} />+ </td>+ <td className="px-3 py-2">+ <SupportMark supported={support.drivers.ssh === "supported"} />+ </td>+ </tr>+ ))}+ </tbody>+ </table>+ </div>++ <div className="space-y-3">+ {(environments ?? []).length === 0 ? (+ <div className="text-sm text-muted-foreground">No environments saved for this company yet.</div>+ ) : (+ (environments ?? []).map((environment) => {+ const probe = probeResults[environment.id] ?? null;+ const isEditing = editingEnvironmentId === environment.id;+ return (+ <div+ key={environment.id}+ className="rounded-md border border-border/70 px-3 py-3"+ >+ <div className="flex flex-wrap items-start justify-between gap-3">+ <div className="space-y-1">+ <div className="text-sm font-medium">+ {environment.name} <span className="text-muted-foreground">· {environment.driver}</span>+ </div>+ {environment.description ? (+ <div className="text-xs text-muted-foreground">{environment.description}</div>+ ) : null}+ {environment.driver === "ssh" ? (+ <div className="text-xs text-muted-foreground">+ {typeof environment.config.host === "string" ? environment.config.host : "SSH host"} ·{" "}+ {typeof environment.config.username === "string" ? environment.config.username : "user"}+ </div>+ ) : (+ <div className="text-xs text-muted-foreground">Runs on this Paperclip host.</div>+ )}+ </div>+ <div className="flex flex-wrap items-center gap-2">+ {environment.driver !== "local" ? (+ <Button+ size="sm"+ variant="outline"+ onClick={() => environmentProbeMutation.mutate(environment.id)}+ disabled={environmentProbeMutation.isPending}+ >+ {environmentProbeMutation.isPending+ ? "Testing..."+ : "Test connection"}+ </Button>+ ) : null}+ <Button+ size="sm"+ variant="ghost"+ onClick={() => handleEditEnvironment(environment)}+ >+ {isEditing ? "Editing" : "Edit"}+ </Button>+ </div>+ </div>+ {probe ? (+ <div+ className={+ probe.ok+ ? "mt-3 rounded border border-green-500/30 bg-green-500/5 px-2.5 py-2 text-xs text-green-700"+ : "mt-3 rounded border border-destructive/30 bg-destructive/5 px-2.5 py-2 text-xs text-destructive"+ }+ >+ <div className="font-medium">{probe.summary}</div>+ {probe.details?.error && typeof probe.details.error === "string" ? (+ <div className="mt-1 font-mono text-[11px]">{probe.details.error}</div>+ ) : null}+ </div>+ ) : null}+ </div>+ );+ })+ )}+ </div>++ <div className="border-t border-border/60 pt-4">+ <div className="mb-3 text-sm font-medium">+ {editingEnvironmentId ? "Edit environment" : "Add environment"}+ </div>+ <div className="space-y-3">+ <Field label="Name" hint="Operator-facing name for this execution target.">+ <input+ className="w-full rounded-md border border-border bg-transparent px-2.5 py-1.5 text-sm outline-none"+ type="text"+ value={environmentForm.name}+ onChange={(e) => setEnvironmentForm((current) => ({ ...current, name: e.target.value }))}+ />+ </Field>+ <Field label="Description" hint="Optional note about what this machine is for.">+ <input+ className="w-full rounded-md border border-border bg-transparent px-2.5 py-1.5 text-sm outline-none"+ type="text"+ value={environmentForm.description}+ onChange={(e) => setEnvironmentForm((current) => ({ ...current, description: e.target.value }))}+ />+ </Field>+ <Field label="Driver" hint="Local runs on this host. SSH stores a remote machine target.">+ <select+ className="w-full rounded-md border border-border bg-transparent px-2.5 py-1.5 text-sm outline-none"+ value={environmentForm.driver}+ onChange={(e) =>+ setEnvironmentForm((current) => ({+ ...current,+ driver: e.target.value === "local" ? "local" : "ssh",+ }))}+ >+ <option value="ssh">SSH</option>+ <option value="local">Local</option>+ </select>+ </Field>++ {environmentForm.driver === "ssh" ? (+ <div className="grid gap-3 md:grid-cols-2">+ <Field label="Host" hint="DNS name or IP address for the remote machine.">+ <input+ className="w-full rounded-md border border-border bg-transparent px-2.5 py-1.5 text-sm outline-none"+ type="text"+ value={environmentForm.sshHost}+ onChange={(e) => setEnvironmentForm((current) => ({ ...current, sshHost: e.target.value }))}+ />+ </Field>+ <Field label="Port" hint="Defaults to 22.">+ <input+ className="w-full rounded-md border border-border bg-transparent px-2.5 py-1.5 text-sm outline-none"+ type="number"+ min={1}+ max={65535}+ value={environmentForm.sshPort}+ onChange={(e) => setEnvironmentForm((current) => ({ ...current, sshPort: e.target.value }))}+ />+ </Field>+ <Field label="Username" hint="SSH login user.">+ <input+ className="w-full rounded-md border border-border bg-transparent px-2.5 py-1.5 text-sm outline-none"+ type="text"+ value={environmentForm.sshUsername}+ onChange={(e) => setEnvironmentForm((current) => ({ ...current, sshUsername: e.target.value }))}+ />+ </Field>+ <Field label="Remote workspace path" hint="Absolute path that Paperclip will verify during SSH connection tests.">+ <input+ className="w-full rounded-md border border-border bg-transparent px-2.5 py-1.5 text-sm outline-none"+ type="text"+ placeholder="/Users/paperclip/workspace"+ value={environmentForm.sshRemoteWorkspacePath}+ onChange={(e) =>+ setEnvironmentForm((current) => ({ ...current, sshRemoteWorkspacePath: e.target.value }))}+ />+ </Field>+ <Field label="Private key" hint="Optional PEM private key. Leave blank to rely on the server's SSH agent or default keychain.">+ <div className="space-y-2">+ <select+ className="w-full rounded-md border border-border bg-transparent px-2.5 py-1.5 text-sm outline-none"+ value={environmentForm.sshPrivateKeySecretId}+ onChange={(e) =>+ setEnvironmentForm((current) => ({+ ...current,+ sshPrivateKeySecretId: e.target.value,+ sshPrivateKey: e.target.value ? "" : current.sshPrivateKey,+ }))}+ >+ <option value="">No saved secret</option>+ {(secrets ?? []).map((secret) => (+ <option key={secret.id} value={secret.id}>{secret.name}</option>+ ))}+ </select>+ <textarea+ className="h-32 w-full rounded-md border border-border bg-transparent px-2.5 py-1.5 text-xs font-mono outline-none"+ value={environmentForm.sshPrivateKey}+ disabled={!!environmentForm.sshPrivateKeySecretId}+ onChange={(e) => setEnvironmentForm((current) => ({ ...current, sshPrivateKey: e.target.value }))}+ />+ </div>+ </Field>+ <Field label="Known hosts" hint="Optional known_hosts block used when strict host key checking is enabled.">+ <textarea+ className="h-32 w-full rounded-md border border-border bg-transparent px-2.5 py-1.5 text-xs font-mono outline-none"+ value={environmentForm.sshKnownHosts}+ onChange={(e) => setEnvironmentForm((current) => ({ ...current, sshKnownHosts: e.target.value }))}+ />+ </Field>+ <div className="md:col-span-2">+ <ToggleField+ label="Strict host key checking"+ hint="Keep this on unless you deliberately want probe-time host key acceptance disabled."+ checked={environmentForm.sshStrictHostKeyChecking}+ onChange={(checked) =>+ setEnvironmentForm((current) => ({ ...current, sshStrictHostKeyChecking: checked }))}+ />+ </div>+ </div>+ ) : null}++ <div className="flex flex-wrap items-center gap-2">+ <Button+ size="sm"+ onClick={() => environmentMutation.mutate(environmentForm)}+ disabled={environmentMutation.isPending || !environmentFormValid}+ >+ {environmentMutation.isPending+ ? editingEnvironmentId+ ? "Saving..."+ : "Creating..."+ : editingEnvironmentId+ ? "Save environment"+ : "Create environment"}+ </Button>+ {editingEnvironmentId ? (+ <Button+ size="sm"+ variant="ghost"+ onClick={handleCancelEnvironmentEdit}+ disabled={environmentMutation.isPending}+ >+ Cancel+ </Button>+ ) : null}+ {environmentForm.driver !== "local" ? (+ <Button+ size="sm"+ variant="outline"+ onClick={() => draftEnvironmentProbeMutation.mutate(environmentForm)}+ disabled={draftEnvironmentProbeMutation.isPending || !environmentFormValid}+ >+ {draftEnvironmentProbeMutation.isPending ? "Testing..." : "Test draft"}+ </Button>+ ) : null}+ {environmentMutation.isError ? (+ <span className="text-xs text-destructive">+ {environmentMutation.error instanceof Error+ ? environmentMutation.error.message+ : "Failed to save environment"}+ </span>+ ) : null}+ {draftEnvironmentProbeMutation.data ? (+ <span className={draftEnvironmentProbeMutation.data.ok ? "text-xs text-green-600" : "text-xs text-destructive"}>+ {draftEnvironmentProbeMutation.data.summary}+ </span>+ ) : null}+ </div>+ </div>+ </div>+ </div>+ </div>+ ) : null}+{/* Hiring */}<div className="space-y-4" data-testid="company-settings-team-section"><div className="text-xs font-medium text-muted-foreground uppercase tracking-wide">diff --git a/ui/src/pages/InstanceExperimentalSettings.tsx b/ui/src/pages/InstanceExperimentalSettings.tsxindex 753ab5fd02..f2e2a9b0d1 100644--- a/ui/src/pages/InstanceExperimentalSettings.tsx+++ b/ui/src/pages/InstanceExperimentalSettings.tsx@@ -1,6 +1,7 @@import { useEffect, useState } from "react";import { useMutation, useQuery, useQueryClient } from "@tanstack/react-query";import { FlaskConical } from "lucide-react";+import type { PatchInstanceExperimentalSettings } from "@paperclipai/shared";import { instanceSettingsApi } from "@/api/instanceSettings";import { useBreadcrumbs } from "../context/BreadcrumbContext";import { queryKeys } from "../lib/queryKeys";@@ -24,7 +25,7 @@ export function InstanceExperimentalSettings() {});const toggleMutation = useMutation({- mutationFn: async (patch: { enableIsolatedWorkspaces?: boolean; autoRestartDevServerWhenIdle?: boolean }) =>+ mutationFn: async (patch: PatchInstanceExperimentalSettings) =>instanceSettingsApi.updateExperimental(patch),onSuccess: async () => {setActionError(null);@@ -52,6 +53,7 @@ export function InstanceExperimentalSettings() {);}+ const enableEnvironments = experimentalQuery.data?.enableEnvironments === true;const enableIsolatedWorkspaces = experimentalQuery.data?.enableIsolatedWorkspaces === true;const autoRestartDevServerWhenIdle = experimentalQuery.data?.autoRestartDevServerWhenIdle === true;@@ -73,6 +75,24 @@ export function InstanceExperimentalSettings() {</div>)}+ <section className="rounded-xl border border-border bg-card p-5">+ <div className="flex items-start justify-between gap-4">+ <div className="space-y-1.5">+ <h2 className="text-sm font-semibold">Enable Environments</h2>+ <p className="max-w-2xl text-sm text-muted-foreground">+ Show environment management in company settings and allow project and agent environment assignment+ controls.+ </p>+ </div>+ <ToggleSwitch+ checked={enableEnvironments}+ onCheckedChange={() => toggleMutation.mutate({ enableEnvironments: !enableEnvironments })}+ disabled={toggleMutation.isPending}+ aria-label="Toggle environments experimental setting"+ />+ </div>+ </section>+<section className="rounded-xl border border-border bg-card p-5"><div className="flex items-start justify-between gap-4"><div className="space-y-1.5">diff --git a/ui/src/pages/NewAgent.tsx b/ui/src/pages/NewAgent.tsxindex 498f8fad78..6822485c66 100644--- a/ui/src/pages/NewAgent.tsx+++ b/ui/src/pages/NewAgent.tsx@@ -23,7 +23,7 @@ import { getUIAdapter, listUIAdapters } from "../adapters";import { useDisabledAdaptersSync } from "../adapters/use-disabled-adapters";import { isValidAdapterType } from "../adapters/metadata";import { ReportsToPicker } from "../components/ReportsToPicker";-import { buildNewAgentRuntimeConfig } from "../lib/new-agent-runtime-config";+import { buildNewAgentHirePayload } from "../lib/new-agent-hire-payload";import {DEFAULT_CODEX_LOCAL_BYPASS_APPROVALS_AND_SANDBOX,DEFAULT_CODEX_LOCAL_MODEL,@@ -168,20 +168,17 @@ export function NewAgent() {return;}}- createAgent.mutate({- name: name.trim(),- role: effectiveRole,- ...(title.trim() ? { title: title.trim() } : {}),- ...(reportsTo ? { reportsTo } : {}),- ...(selectedSkillKeys.length > 0 ? { desiredSkills: selectedSkillKeys } : {}),- adapterType: configValues.adapterType,- adapterConfig: buildAdapterConfig(),- runtimeConfig: buildNewAgentRuntimeConfig({- heartbeatEnabled: configValues.heartbeatEnabled,- intervalSec: configValues.intervalSec,+ createAgent.mutate(+ buildNewAgentHirePayload({+ name,+ effectiveRole,+ title,+ reportsTo,+ selectedSkillKeys,+ configValues,+ adapterConfig: buildAdapterConfig(),}),- budgetMonthlyCents: 0,- });+ );}const availableSkills = (companySkills ?? []).filter((skill) => !skill.key.startsWith("paperclipai/paperclip/"));diff --git a/vitest.config.ts b/vitest.config.tsindex c5dd209dde..c886095dad 100644--- a/vitest.config.ts+++ b/vitest.config.ts@@ -6,8 +6,12 @@ export default defineConfig({"packages/shared","packages/db","packages/adapter-utils",+ "packages/adapters/claude-local","packages/adapters/codex-local",+ "packages/adapters/cursor-local",+ "packages/adapters/gemini-local","packages/adapters/opencode-local",+ "packages/adapters/pi-local","server","ui","cli",