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
feat(runner): bind ACPX profile boundary (#12387)
Dotta0834a0c1f7ff
diff --git a/packages/adapter-utils/src/acpx-engine/execute-identity.test.ts b/packages/adapter-utils/src/acpx-engine/execute-identity.test.tsindex b182d61242..365f49cff7 100644--- a/packages/adapter-utils/src/acpx-engine/execute-identity.test.ts+++ b/packages/adapter-utils/src/acpx-engine/execute-identity.test.ts@@ -7,7 +7,11 @@// never runs a synthetic value.import { describe, expect, it } from "vitest";-import { buildSessionFingerprint, finalizeLaunchEnvironment } from "./execute.js";+import {+ buildSessionFingerprint,+ finalizeLaunchEnvironment,+ projectAcpxInheritedHostEnvironment,+} from "./execute.js";import type {LaunchEnvironment,RunScopedContribution,@@ -58,9 +62,15 @@ describe("acpx identity split and launch environment", () => {it("test_finalize_launch_environment_is_sole_constructor_of_branded_environment", () => {// The finalizer merges every contribution and freezes the launch env.const baseEnv: Record<string, string> = { LAUNCH_ENV_TEST_BASE: "base" };- const launchEnvironment = finalizeLaunchEnvironment(baseEnv, [- { scope: "session", env: { LAUNCH_ENV_TEST_CONTRIB: "contrib" } },- ]);+ const launchEnvironment = finalizeLaunchEnvironment(+ baseEnv,+ [{ scope: "session", env: { LAUNCH_ENV_TEST_CONTRIB: "contrib" } }],+ {+ acpxAgent: "claude",+ inheritHostEnvironment: true,+ inheritedEnv: {},+ },+ );expect(launchEnvironment.env.LAUNCH_ENV_TEST_BASE).toBe("base");expect(launchEnvironment.env.LAUNCH_ENV_TEST_CONTRIB).toBe("contrib");expect(Object.isFrozen(launchEnvironment.env)).toBe(true);@@ -92,4 +102,162 @@ describe("acpx identity split and launch environment", () => {void _assertNotReusable;expect(true).toBe(true);});++ it("inherits only safe host context and the selected provider's credentials", () => {+ const inherited = {+ PATH: "/usr/bin",+ LC_ALL: "C.UTF-8",+ HTTPS_PROXY: "https://proxy.example",+ OPENAI_API_KEY: "openai-host-secret",+ ANTHROPIC_API_KEY: "anthropic-host-secret",+ ANTHROPIC_AUTH_TOKEN: "anthropic-auth-host-secret",+ CLAUDE_CODE_OAUTH_TOKEN: "claude-oauth-host-secret",+ ANTHROPIC_BASE_URL: "https://anthropic.example",+ ANTHROPIC_MODEL: "claude-test",+ ANTHROPIC_SMALL_FAST_MODEL: "claude-fast-test",+ CLAUDE_CONFIG_DIR: "/host/claude",+ CLAUDE_CODE_USE_BEDROCK: "true",+ ANTHROPIC_BEDROCK_BASE_URL: "https://bedrock.example",+ AWS_BEARER_TOKEN_BEDROCK: "bedrock-host-secret",+ OPENROUTER_API_KEY: "openrouter-host-secret",+ GOOGLE_GENAI_USE_GCA: "true",+ KIMI_MODEL_NAME: "kimi-code/test",+ KIMI_MODEL_API_KEY: "kimi-host-secret",+ KIMI_MODEL_BASE_URL: "https://kimi.example",+ KIMI_MODEL_PROVIDER_TYPE: "openai_legacy",+ KIMI_CODE_HOME: "/host/kimi",+ PAPERCLIP_NATIVE_MCP_TOKEN: "native-mcp-host-secret",+ PAPERCLIP_ACPX_CODEX_AUTH_JSON_SECRET: "managed-auth-host-secret",+ UNRELATED_SECRET: "unrelated-host-secret",+ NODE_OPTIONS: "--require /tmp/host-hook.cjs",+ };++ expect(projectAcpxInheritedHostEnvironment(inherited, "codex", true)).toEqual({+ PATH: "/usr/bin",+ LC_ALL: "C.UTF-8",+ HTTPS_PROXY: "https://proxy.example",+ OPENAI_API_KEY: "openai-host-secret",+ });+ expect(projectAcpxInheritedHostEnvironment(inherited, "claude", true)).toEqual({+ PATH: "/usr/bin",+ LC_ALL: "C.UTF-8",+ HTTPS_PROXY: "https://proxy.example",+ ANTHROPIC_API_KEY: "anthropic-host-secret",+ ANTHROPIC_AUTH_TOKEN: "anthropic-auth-host-secret",+ CLAUDE_CODE_OAUTH_TOKEN: "claude-oauth-host-secret",+ ANTHROPIC_BASE_URL: "https://anthropic.example",+ ANTHROPIC_MODEL: "claude-test",+ ANTHROPIC_SMALL_FAST_MODEL: "claude-fast-test",+ CLAUDE_CONFIG_DIR: "/host/claude",+ CLAUDE_CODE_USE_BEDROCK: "true",+ ANTHROPIC_BEDROCK_BASE_URL: "https://bedrock.example",+ AWS_BEARER_TOKEN_BEDROCK: "bedrock-host-secret",+ });+ expect(projectAcpxInheritedHostEnvironment(inherited, "pi", true)).toEqual({+ PATH: "/usr/bin",+ LC_ALL: "C.UTF-8",+ HTTPS_PROXY: "https://proxy.example",+ OPENROUTER_API_KEY: "openrouter-host-secret",+ });+ expect(projectAcpxInheritedHostEnvironment(inherited, "gemini", true)).toEqual({+ PATH: "/usr/bin",+ LC_ALL: "C.UTF-8",+ HTTPS_PROXY: "https://proxy.example",+ GOOGLE_GENAI_USE_GCA: "true",+ });+ expect(projectAcpxInheritedHostEnvironment(inherited, "kimi", true)).toEqual({+ PATH: "/usr/bin",+ LC_ALL: "C.UTF-8",+ HTTPS_PROXY: "https://proxy.example",+ KIMI_MODEL_NAME: "kimi-code/test",+ KIMI_MODEL_API_KEY: "kimi-host-secret",+ KIMI_MODEL_BASE_URL: "https://kimi.example",+ KIMI_MODEL_PROVIDER_TYPE: "openai_legacy",+ KIMI_CODE_HOME: "/host/kimi",+ });+ });++ it("does not project any ambient host environment across a remote boundary", () => {+ const inherited = {+ PATH: "/host/bin",+ OPENAI_API_KEY: "ambient-provider-secret",+ PAPERCLIP_NATIVE_MCP_TOKEN: "ambient-native-mcp-secret",+ PAPERCLIP_RUNNER_BOOTSTRAP_TICKET: "ambient-bootstrap-secret",+ };++ expect(projectAcpxInheritedHostEnvironment(inherited, "codex", false)).toEqual({});+ });++ it("keeps explicit remote adapter and run contributions while rejecting ambient authority", () => {+ const launchEnvironment = finalizeLaunchEnvironment(+ {+ OPENAI_API_KEY: "explicit-provider-secret",+ EXPLICIT_ADAPTER_SECRET: "adapter-secret",+ PAPERCLIP_RUNTIME_API_URL: "http://paperclip.internal/api",+ },+ [+ {+ scope: "session",+ env: { PAPERCLIP_NATIVE_MCP_TOKEN: "explicit-run-contribution" },+ },+ ],+ {+ acpxAgent: "codex",+ inheritHostEnvironment: false,+ inheritedEnv: {+ PATH: "/host/bin",+ OPENAI_API_KEY: "ambient-provider-secret",+ PAPERCLIP_NATIVE_MCP_TOKEN: "ambient-native-mcp-secret",+ PAPERCLIP_RUNNER_BOOTSTRAP_TICKET: "ambient-bootstrap-secret",+ },+ },+ );++ expect(launchEnvironment.env).toMatchObject({+ OPENAI_API_KEY: "explicit-provider-secret",+ EXPLICIT_ADAPTER_SECRET: "adapter-secret",+ PAPERCLIP_RUNTIME_API_URL: "http://paperclip.internal/api",+ PAPERCLIP_NATIVE_MCP_TOKEN: "explicit-run-contribution",+ });+ expect(launchEnvironment.env).not.toHaveProperty("PATH");+ expect(launchEnvironment.env).not.toHaveProperty("PAPERCLIP_RUNNER_BOOTSTRAP_TICKET");+ });++ it("preserves an explicit remote PATH instead of synthesizing a host fallback", () => {+ const launchEnvironment = finalizeLaunchEnvironment(+ { PATH: "/sandbox/bin" },+ [],+ {+ acpxAgent: "codex",+ inheritHostEnvironment: false,+ inheritedEnv: { PATH: "/host/bin" },+ },+ );++ expect(launchEnvironment.env).toEqual({ PATH: "/sandbox/bin" });+ });++ it("lets explicit Windows env values suppress differently-cased ambient values", () => {+ const launchEnvironment = finalizeLaunchEnvironment(+ {+ openai_api_key: "",+ Path: "C:\\explicit\\bin",+ },+ [],+ {+ acpxAgent: "codex",+ inheritHostEnvironment: true,+ inheritedEnv: {+ OPENAI_API_KEY: "ambient-provider-secret",+ PATH: "C:\\ambient\\bin",+ },+ platform: "win32",+ },+ );++ expect(launchEnvironment.env).toEqual({+ openai_api_key: "",+ Path: "C:\\explicit\\bin",+ });+ });});diff --git a/packages/adapter-utils/src/acpx-engine/execute.ts b/packages/adapter-utils/src/acpx-engine/execute.tsindex 6ae17d80f1..c1de4487a3 100644--- a/packages/adapter-utils/src/acpx-engine/execute.ts+++ b/packages/adapter-utils/src/acpx-engine/execute.ts@@ -505,6 +505,118 @@ export function buildSessionKey(identity: SessionKeyIdentity, fingerprint: strinreturn `paperclip:${identity.companyId}:${identity.agentId}:${identity.taskKey}:${fingerprint}`;}+// ACPX runs inside the long-lived Paperclip server process. A local child needs+// a small amount of host context (PATH, locale, certificate/proxy settings, and+// provider authentication), but it must not inherit the server's complete+// environment. A runner-backed remote sandbox inherits no ambient host context+// at all. In particular, native-runner bootstrap and MCP credentials are host+// authority, not provider credentials.+const ACPX_INHERITED_HOST_ENV_KEYS = new Set([+ "PATH",+ "PATHEXT",+ "SYSTEMROOT",+ "WINDIR",+ "COMSPEC",+ "HOME",+ "USERPROFILE",+ "HOMEDRIVE",+ "HOMEPATH",+ "USER",+ "USERNAME",+ "LOGNAME",+ "SHELL",+ "LANG",+ "LANGUAGE",+ "TZ",+ "TMPDIR",+ "TEMP",+ "TMP",+ "XDG_CONFIG_HOME",+ "XDG_CACHE_HOME",+ "XDG_DATA_HOME",+ "SSL_CERT_FILE",+ "SSL_CERT_DIR",+ "NODE_EXTRA_CA_CERTS",+ "HTTP_PROXY",+ "HTTPS_PROXY",+ "NO_PROXY",+ "ALL_PROXY",+]);++const ACPX_INHERITED_PROVIDER_ENV_KEYS: Readonly<Record<string, ReadonlySet<string>>> = {+ codex: new Set([+ "OPENAI_API_KEY",+ "CODEX_API_KEY",+ ]),+ claude: new Set([+ "ANTHROPIC_API_KEY",+ "ANTHROPIC_AUTH_TOKEN",+ "CLAUDE_CODE_OAUTH_TOKEN",+ "ANTHROPIC_BASE_URL",+ "ANTHROPIC_MODEL",+ "ANTHROPIC_SMALL_FAST_MODEL",+ "CLAUDE_CONFIG_DIR",+ "CLAUDE_CODE_USE_BEDROCK",+ "ANTHROPIC_BEDROCK_BASE_URL",+ "AWS_BEARER_TOKEN_BEDROCK",+ "AWS_ACCESS_KEY_ID",+ "AWS_SECRET_ACCESS_KEY",+ "AWS_SESSION_TOKEN",+ "AWS_REGION",+ "AWS_DEFAULT_REGION",+ "AWS_PROFILE",+ "AWS_CONFIG_FILE",+ "AWS_SHARED_CREDENTIALS_FILE",+ ]),+ pi: new Set(["OPENROUTER_API_KEY"]),+ gemini: new Set([+ "GEMINI_API_KEY",+ "GOOGLE_API_KEY",+ "GOOGLE_APPLICATION_CREDENTIALS",+ "GOOGLE_GENAI_USE_GCA",+ ]),+ kimi: new Set([+ "KIMI_API_KEY",+ "MOONSHOT_API_KEY",+ "KIMI_MODEL_NAME",+ "KIMI_MODEL_API_KEY",+ "KIMI_MODEL_BASE_URL",+ "KIMI_MODEL_PROVIDER_TYPE",+ "KIMI_CODE_HOME",+ ]),+ grok: new Set(["XAI_API_KEY"]),+};++/**+ * Project the server environment onto the closed set a host ACPX provider may+ * inherit. A runner-backed remote sandbox passes `false` and projects nothing.+ * Explicit adapter/runtime env is merged later and is intentionally not+ * restricted by this host projection.+ */+export function projectAcpxInheritedHostEnvironment(+ inheritedEnv: NodeJS.ProcessEnv,+ acpxAgent: string,+ inheritHostEnvironment: boolean,+): Record<string, string> {+ // A runner-backed remote sandbox crosses a serialization boundary. Ambient+ // server state is never part of that contract: provider auth/config must be+ // supplied through adapter config, resolved runtime env, or a contribution.+ if (!inheritHostEnvironment) return {};++ const providerKeys = ACPX_INHERITED_PROVIDER_ENV_KEYS[acpxAgent];+ const projected: Record<string, string> = {};+ for (const [key, value] of Object.entries(inheritedEnv)) {+ if (typeof value !== "string") continue;+ const normalizedKey = key.toUpperCase();+ const allowed =+ ACPX_INHERITED_HOST_ENV_KEYS.has(normalizedKey) ||+ /^LC_[A-Z0-9_]{1,32}$/.test(normalizedKey) ||+ providerKeys?.has(normalizedKey) === true;+ if (allowed) projected[key] = value;+ }+ return projected;+}+/*** Build the single branded launch environment for a run. This is the sole* constructor of `LaunchEnvironment`. It applies each contribution into the base@@ -519,11 +631,19 @@ export function buildSessionKey(identity: SessionKeyIdentity, fingerprint: strinexport function finalizeLaunchEnvironment(baseEnv: Record<string, string>,contributions: readonly LaunchEnvironmentContribution[],+ options: {+ acpxAgent: string;+ inheritHostEnvironment: boolean;+ inheritedEnv?: NodeJS.ProcessEnv;+ platform?: typeof process.platform;+ },): LaunchEnvironment {for (const contribution of contributions) {Object.assign(baseEnv, contribution.env);}- const env = Object.freeze(resolveRuntimeEnv(baseEnv));+ const env = Object.freeze(+ resolveRuntimeEnv(baseEnv, options.acpxAgent, options),+ );return { env } as unknown as LaunchEnvironment;}@@ -1890,10 +2010,20 @@ async function buildRuntime(input: {});let agentCommand = configuredCommand || builtInCommand?.command || null;let agentCommandShell = configuredCommand || builtInCommand?.shellCommand || "";+ // A runner-backed remote sandbox is the only lane that crosses the staging+ // and serialized-launch-env seam. Runner-less ACP→CLI fallback, SSH, and+ // local runs keep their historical host-provider compatibility behavior.+ const useRemoteProcessSession =+ executionTarget?.kind === "remote" &&+ executionTarget.transport === "sandbox" &&+ Boolean(executionTarget.runner) &&+ Boolean(agentCommandShell);if (acpxAgent === "gemini" && agentCommandShell) {const normalized = await normalizeGeminiAcpCommandShell(agentCommandShell,- ensurePathInEnv({ ...process.env, ...env }),+ resolveRuntimeEnv(env, acpxAgent, {+ inheritHostEnvironment: !useRemoteProcessSession,+ }),);if (normalized !== agentCommandShell) {agentCommandShell = normalized;@@ -1902,15 +2032,6 @@ async function buildRuntime(input: {}const childStderrDir = path.join(stateDir, "run-stderr");const childStderrLogPath = agentCommand ? path.join(childStderrDir, `${runId}.log`) : null;- // A runner-backed remote sandbox is the only lane that crosses the staging- // seam: the runner-less ACP→CLI fallback (no `runner`) and local runs keep- // their historical behavior untouched. This is the single gate shared by the- // workspace stage and both sandbox bridges.- const useRemoteProcessSession =- executionTarget?.kind === "remote" &&- executionTarget.transport === "sandbox" &&- Boolean(executionTarget.runner) &&- Boolean(agentCommandShell);// Stream the agent output through the persistent session log stream instead of// the host output-file poll. The decision comes from the effective capability// snapshot alone: the provider must declare and verify incremental session@@ -2158,7 +2279,11 @@ async function buildRuntime(input: {}),measureBridgeStep: (step, run) =>measureStartupStep(input.ctx, nowMs, step, run, concurrentBridgeStepMetrics),- finalizeLaunchEnv: (contributions) => finalizeLaunchEnvironment(env, contributions).env,+ finalizeLaunchEnv: (contributions) =>+ finalizeLaunchEnvironment(env, contributions, {+ acpxAgent,+ inheritHostEnvironment: !useRemoteProcessSession,+ }).env,onPaperclipBridgeLog: () =>input.ctx.onLog("stdout", "[paperclip] Sandbox ACP API callback bridge enabled for this run.\n"),stopBridges: async ({ controlBridge, agentBridge }) => {@@ -2207,7 +2332,10 @@ async function buildRuntime(input: {// Local / runner-less lanes never start a bridge, so they add no// contribution. `finalizeLaunchEnvironment` still produces the one branded// launch env the prepared runtime and the log builder read.- runtimeEnv = finalizeLaunchEnvironment(env, []).env;+ runtimeEnv = finalizeLaunchEnvironment(env, [], {+ acpxAgent,+ inheritHostEnvironment: !useRemoteProcessSession,+ }).env;}} catch (err) {// On a partial concurrent bring-up failure, ONE bridge may have started while@@ -2270,7 +2398,7 @@ async function buildRuntime(input: {workspaceId,workspaceRepoUrl,workspaceRepoRef,- env,+ env: runtimeEnv,loggedEnv,stateDir,permissionMode,@@ -2360,19 +2488,72 @@ async function applySessionConfigOptions(input: {}/**- * Build the process-session launch env: the host env overlaid with the run's- * `env` (so the merged paperclip bridge vars win) and a guaranteed `PATH`,- * narrowed to string values. Shared by the remote concurrent bring-up and the- * local / runner-less lane so both resolve the runtime env identically.+ * Build the process-session launch env: the target-specific host projection+ * overlaid with the run's explicit `env` (so adapter config, runtime variables,+ * and bridge contributions win), narrowed to string values. Host-side launches+ * get the closed projection plus a default `PATH` when the host did not provide+ * one. Runner-backed remote sandbox launches get no ambient host state or+ * synthesized host `PATH`; omitting `PATH` preserves the sandbox-native value.*/-function resolveRuntimeEnv(env: Record<string, string>): Record<string, string> {+function resolveRuntimeEnv(+ env: Record<string, string>,+ acpxAgent: string,+ options: {+ inheritHostEnvironment: boolean;+ inheritedEnv?: NodeJS.ProcessEnv;+ platform?: typeof process.platform;+ },+): Record<string, string> {+ const inheritedEnv = options.inheritedEnv ?? process.env;+ const projectedHostEnv = projectAcpxInheritedHostEnvironment(+ inheritedEnv,+ acpxAgent,+ options.inheritHostEnvironment,+ );+ const inheritedLaunchEnv = options.inheritHostEnvironment+ ? ensurePathInEnv(projectedHostEnv)+ : projectedHostEnv;+ const mergedEnv = mergeRuntimeEnvironment(+ inheritedLaunchEnv,+ env,+ (options.platform ?? process.platform) === "win32",+ );return Object.fromEntries(- Object.entries(ensurePathInEnv({ ...process.env, ...env })).filter(+ Object.entries(mergedEnv).filter((entry): entry is [string, string] => typeof entry[1] === "string",),);}+function mergeRuntimeEnvironment(+ inheritedEnv: NodeJS.ProcessEnv,+ explicitEnv: Record<string, string>,+ caseInsensitiveKeys: boolean,+): NodeJS.ProcessEnv {+ if (!caseInsensitiveKeys) {+ return { ...inheritedEnv, ...explicitEnv };+ }++ const merged: NodeJS.ProcessEnv = {};+ const keyByCanonicalName = new Map<string, string>();+ const apply = (source: NodeJS.ProcessEnv): void => {+ for (const [key, value] of Object.entries(source)) {+ if (typeof value !== "string") continue;+ const canonicalName = key.toUpperCase();+ const previousKey = keyByCanonicalName.get(canonicalName);+ if (previousKey !== undefined && previousKey !== key) {+ delete merged[previousKey];+ }+ merged[key] = value;+ keyByCanonicalName.set(canonicalName, key);+ }+ };++ apply(inheritedEnv);+ apply(explicitEnv);+ return merged;+}+// Stop both host-side bridges in one `allSettled`. This is the settlement// `stopTransport` effect. The bridge tokens are run-scoped, so they die with the// bridges here (Amendment B).@@ -3857,6 +4038,10 @@ export function createAcpxEngineExecutor(deps: AcpxEngineExecutorOptions = {}) {// and custom agents already emit their own per-tool output and don't// benefit from doubling the log volume.verbose: prepared.acpxAgent === "claude",+ // The engine passes a complete, sanitized launch environment. ACPX+ // must not merge the Paperclip server's ambient environment back in+ // when it spawns the provider child.+ inheritProcessEnv: false,onAgentStderr: prepared.childStderrLogPath? (chunk) => routeChildStderr(childStderrState, chunk): undefined,diff --git a/packages/adapter-utils/src/execution-target-sandbox.test.ts b/packages/adapter-utils/src/execution-target-sandbox.test.tsindex 54dea1c5aa..47e7a276e4 100644--- a/packages/adapter-utils/src/execution-target-sandbox.test.ts+++ b/packages/adapter-utils/src/execution-target-sandbox.test.ts@@ -448,6 +448,75 @@ describe("sandbox adapter execution targets", () => {}});+ it.each([+ { outputMode: "polled", streamOutputViaSession: false },+ { outputMode: "streamed", streamOutputViaSession: true },+ ])(+ "preserves an explicit remote PATH equal to host PATH in $outputMode mode",+ async ({ outputMode, streamOutputViaSession }) => {+ const rootDir = await mkdtemp(+ path.join(os.tmpdir(), `paperclip-process-session-${outputMode}-path-`),+ );+ cleanupDirs.push(rootDir);+ const childPath = path.join(rootDir, "print-path-child.mjs");+ await writeFile(+ childPath,+ 'process.stdout.write(process.env.PATH ?? "<missing>");\n',+ "utf8",+ );++ const nodeBinDir = path.dirname(process.execPath);+ const explicitHostPath = `${nodeBinDir}:/explicit-host-bin`;+ const sandboxNativePath = `/usr/bin:/bin:${nodeBinDir}`;+ vi.stubEnv("PATH", explicitHostPath);++ const delegate = createLocalSandboxRunner();+ const runner = {+ execute: vi.fn(+ async (input: Parameters<typeof delegate.execute>[0]) =>+ delegate.execute({+ ...input,+ // The local fake otherwise inherits the test host PATH. Give the+ // wrapper a distinct sandbox-native PATH so the child proves the+ // explicit equal-to-host value survived payload serialization.+ env: { ...input.env, PATH: sandboxNativePath },+ }),+ ),+ };+ const target: AdapterSandboxExecutionTarget = {+ kind: "remote",+ transport: "sandbox",+ providerKey: "local-test",+ remoteCwd: rootDir,+ timeoutMs: 30_000,+ runner,+ };++ const bridge = await startAdapterExecutionTargetProcessSessionBridge({+ runId: `run-process-session-${outputMode}-path`,+ target,+ runtimeRootDir: path.posix.join(rootDir, ".paperclip-runtime", "acpx"),+ adapterKey: "acpx",+ command: process.execPath,+ args: [childPath],+ cwd: rootDir,+ env: { PATH: explicitHostPath },+ timeoutSec: 5,+ onLog: async () => {},+ streamOutputViaSession,+ });+ expect(bridge).not.toBeNull();++ try {+ const result = await runProxyWithInput(bridge!.agentCommand, "");+ expect(result.code).toBe(0);+ expect(result.stdout).toBe(explicitHostPath);+ } finally {+ await bridge?.stop();+ }+ },+ );+it("test_process_session_poll_exec_parents_to_run_context", async () => {// The poll timer runs run-time execs for the whole run. Its `sandbox.exec`// span must parent to the live run span, not to the ended startup step. Thediff --git a/packages/adapter-utils/src/execution-target.ts b/packages/adapter-utils/src/execution-target.tsindex 5d08f246fc..845c65aed8 100644--- a/packages/adapter-utils/src/execution-target.ts+++ b/packages/adapter-utils/src/execution-target.ts@@ -1712,7 +1712,11 @@ export async function startAdapterExecutionTargetProcessSessionBridge(input: {command: input.command,args: input.args,cwd: input.cwd || target.remoteCwd,- env: sanitizeRemoteExecutionEnv(launchEnv),+ // The ACP engine has already projected this launch env from explicit+ // adapter/runtime inputs and registered contributions. Compare against an+ // empty inherited baseline so an explicit identity value (notably PATH)+ // is not reclassified as ambient merely because it equals the host value.+ env: sanitizeRemoteExecutionEnv(launchEnv, {}),}), "utf8").toString("base64");// Legacy poll path: background the wrapper with `nohup` and read its output@@ -2013,7 +2017,9 @@ export async function startAdapterExecutionTargetProcessSessionBridge(input: {command: input.command,args: input.args,cwd: input.cwd || target.remoteCwd,- env: sanitizeRemoteExecutionEnv(launchEnvForStream),+ // Same provenance-clean contract as the polled payload above. Preserve+ // every explicit identity override even when it equals the host value.+ env: sanitizeRemoteExecutionEnv(launchEnvForStream, {}),}), "utf8").toString("base64");await onLog("stdout",diff --git a/packages/paperclip-runner/runner/crates/runner-core/src/bin/fake-codex-app-server.rs b/packages/paperclip-runner/runner/crates/runner-core/src/bin/fake-codex-app-server.rsindex 3e92e418af..521a5aa86d 100644--- a/packages/paperclip-runner/runner/crates/runner-core/src/bin/fake-codex-app-server.rs+++ b/packages/paperclip-runner/runner/crates/runner-core/src/bin/fake-codex-app-server.rs@@ -288,9 +288,14 @@ fn send_question(state: &FakeState) -> io::Result<()> {}))}-fn send_runtime_request_flood(state: &FakeState, interrupt_count: u64) -> io::Result<()> {+fn send_runtime_request_flood(+ state: &FakeState,+ interrupt_count: u64,+ count: u64,+ question: &str,+) -> io::Result<()> {let turn_id = state.active_turn_id.as_deref().unwrap_or("provider-turn-1");- for index in 0..160_u64 {+ for index in 0..count {send(json!({"id": format!("runtime-flood-{interrupt_count}-{index}"),"method": "item/tool/requestUserInput",@@ -303,7 +308,7 @@ fn send_runtime_request_flood(state: &FakeState, interrupt_count: u64) -> io::Re"questions": [{"id": "environment","header": "Environment",- "question": "Where should we deploy?",+ "question": question,"options": [{"label": "Staging", "description": "Deploy safely."}],}],},@@ -412,6 +417,9 @@ fn run() -> Result<(), Box<dyn std::error::Error>> {let flood_runtime_requests_on_interrupt = args.iter().any(|value| value == "--flood-runtime-requests-on-interrupt");+ let flood_large_runtime_requests_on_interrupt = args+ .iter()+ .any(|value| value == "--flood-large-runtime-requests-on-interrupt");let interrupt_terminal_delay_ms = argument(&args, "--interrupt-terminal-delay-ms").map(|value| value.parse::<u64>()).transpose()?;@@ -884,7 +892,16 @@ fn run() -> Result<(), Box<dyn std::error::Error>> {} else {send(json!({"id": id, "result": {"accepted": true}}))?;if flood_runtime_requests_on_interrupt {- send_runtime_request_flood(&state, interrupt_count)?;+ send_runtime_request_flood(+ &state,+ interrupt_count,+ 160,+ "Where should we deploy?",+ )?;+ }+ if flood_large_runtime_requests_on_interrupt {+ let question = "x".repeat(2 * 1024 * 1024);+ send_runtime_request_flood(&state, interrupt_count, 3, &question)?;}if !accept_interrupt_without_terminal&& !(accept_interrupt_without_terminal_oncediff --git a/packages/paperclip-runner/runner/crates/runner-core/tests/codex_provider.rs b/packages/paperclip-runner/runner/crates/runner-core/tests/codex_provider.rsindex 4e8050f1b1..baacff1e21 100644--- a/packages/paperclip-runner/runner/crates/runner-core/tests/codex_provider.rs+++ b/packages/paperclip-runner/runner/crates/runner-core/tests/codex_provider.rs@@ -1963,19 +1963,27 @@ fn accepted_replacement_turn_revokes_prior_authority_before_idle_crash() {provider.start_turn("Start genuinely new provider work.", &config.cwd).expect("start second provider turn");- let second_exit = (0..64).find_map(|_| match provider.poll().expect("poll second turn") {- Some(CodexProviderEvent::Exited {- success,- completed_turn_authoritative,- completion_reconciles_exit,- ..- }) => Some((- success,- completed_turn_authoritative,- completion_reconciles_exit,- )),- _ => None,- });+ let deadline = std::time::Instant::now() + std::time::Duration::from_secs(5);+ let second_exit = loop {+ if std::time::Instant::now() >= deadline {+ break None;+ }+ match provider.poll().expect("poll second turn") {+ Some(CodexProviderEvent::Exited {+ success,+ completed_turn_authoritative,+ completion_reconciles_exit,+ ..+ }) => {+ break Some((+ success,+ completed_turn_authoritative,+ completion_reconciles_exit,+ ));+ }+ _ => std::thread::sleep(std::time::Duration::from_millis(1)),+ }+ };assert_eq!(second_exit, Some((false, false, false)));fs::remove_dir_all(directory).expect("remove Codex integration-test directory");@@ -3680,6 +3688,55 @@ fn receipt_limit_polls_an_authoritative_terminal_with_unacknowledged_events() {fs::remove_dir_all(directory).expect("remove Codex integration-test directory");}+#[test]+fn pending_runtime_request_count_limit_rejects_the_overflowing_request() {+ let directory = temporary_directory("runtime-request-count-limit");+ let config = provider_config(+ &directory,+ &[+ "--hold-turn",+ "--accept-interrupt-without-terminal",+ "--flood-runtime-requests-on-interrupt",+ ],+ );+ let mut provider = CodexProvider::start(&config, None).expect("start Codex provider");+ provider+ .start_turn("Bound pending runtime requests by count.", &config.cwd)+ .expect("start held provider turn");+ provider+ .interrupt_turn()+ .expect("request the runtime-request flood");++ let deadline = std::time::Instant::now() + std::time::Duration::from_secs(5);+ let mut accepted = 0;+ let mut rejected_at_capacity = false;+ while !rejected_at_capacity && std::time::Instant::now() < deadline {+ match provider+ .poll()+ .expect("the pending runtime-request count remains pollable")+ {+ Some(CodexProviderEvent::RuntimeRequest { .. }) => accepted += 1,+ Some(CodexProviderEvent::Notification { method, params })+ if method == "warning"+ && params["message"]+ == "rejected a Codex runtime request at the bounded pending-input limit" =>+ {+ rejected_at_capacity = true;+ }+ None => std::thread::sleep(std::time::Duration::from_millis(1)),+ _ => {}+ }+ }+ assert_eq!(accepted, 128);+ assert!(+ rejected_at_capacity,+ "production rejects the 129th pending runtime request"+ );++ provider.shutdown().expect("stop Codex provider");+ fs::remove_dir_all(directory).expect("remove Codex integration-test directory");+}+#[test]fn receipt_limit_polling_bounds_and_rejects_runtime_request_floods() {let directory = temporary_directory("receipt-limit-runtime-request-flood");@@ -3690,7 +3747,7 @@ fn receipt_limit_polling_bounds_and_rejects_runtime_request_floods() {"--hold-turn","--emit-tool-call-on-resume","--accept-interrupt-without-terminal",- "--flood-runtime-requests-on-interrupt",+ "--flood-large-runtime-requests-on-interrupt",],);let runner_config = durable_config(&directory);diff --git a/packages/paperclip-runner/src/drivers/acpx/environment.test.ts b/packages/paperclip-runner/src/drivers/acpx/environment.test.tsnew file mode 100644index 0000000000..03e7d00aae--- /dev/null+++ b/packages/paperclip-runner/src/drivers/acpx/environment.test.ts@@ -0,0 +1,61 @@+import { describe, expect, it } from "vitest";++import { createSanitizedAcpxSpawnInput } from "./environment.js";++describe("ACPX launch environment", () => {+ it("projects only the selected agent's credentials and runtime allowlist", () => {+ const source = {+ PATH: "/bin",+ LC_ALL: "C.UTF-8",+ HTTPS_PROXY: "https://proxy.example",+ OPENAI_API_KEY: "openai-secret",+ ANTHROPIC_API_KEY: "anthropic-secret",+ OPENROUTER_API_KEY: "openrouter-secret",+ PAPERCLIP_ACPX_CODEX_AUTH_JSON_SECRET:+ '{"tokens":{"access_token":"managed-secret"}}',+ PAPERCLIP_RUNNER_BOOTSTRAP_TICKET: "transport-secret",+ PAPERCLIP_NATIVE_MCP_TOKEN: "bridge-secret",+ UNRELATED_SECRET: "not-visible",+ };++ const codex = createSanitizedAcpxSpawnInput(source, "codex");+ expect(codex.env).toEqual({+ PATH: "/bin",+ LC_ALL: "C.UTF-8",+ HTTPS_PROXY: "https://proxy.example",+ OPENAI_API_KEY: "openai-secret",+ });+ expect(createSanitizedAcpxSpawnInput(source, "claude").env).toEqual({+ PATH: "/bin",+ LC_ALL: "C.UTF-8",+ HTTPS_PROXY: "https://proxy.example",+ ANTHROPIC_API_KEY: "anthropic-secret",+ });+ expect(createSanitizedAcpxSpawnInput(source, "pi").env).toEqual({+ PATH: "/bin",+ LC_ALL: "C.UTF-8",+ HTTPS_PROXY: "https://proxy.example",+ OPENROUTER_API_KEY: "openrouter-secret",+ });+ expect(codex.env).not.toHaveProperty("PAPERCLIP_NATIVE_MCP_TOKEN");+ expect(codex.env).not.toHaveProperty(+ "PAPERCLIP_ACPX_CODEX_AUTH_JSON_SECRET",+ );+ expect(Object.isFrozen(codex)).toBe(true);+ expect(Object.isFrozen(codex.env)).toBe(true);+ });++ it("rejects unsafe or unbounded retained values", () => {+ expect(() =>+ createSanitizedAcpxSpawnInput({ PATH: "bad\0path" }, "codex"),+ ).toThrow("null byte");+ expect(() =>+ createSanitizedAcpxSpawnInput(+ {+ OPENAI_API_KEY: "x".repeat(64 * 1024),+ },+ "codex",+ ),+ ).toThrow("bounded launch size");+ });+});diff --git a/packages/paperclip-runner/src/drivers/acpx/environment.ts b/packages/paperclip-runner/src/drivers/acpx/environment.tsnew file mode 100644index 0000000000..57fef1b4e3--- /dev/null+++ b/packages/paperclip-runner/src/drivers/acpx/environment.ts@@ -0,0 +1,77 @@+import type { QualifiedAcpxAgent } from "./qualified-profiles.js";++declare const sanitizedAcpxSpawnInputBrand: unique symbol;++/**+ * Opaque child-process input produced only after the host environment crosses+ * the ACPX credential allowlist. Future ACPX launchers accept this boundary+ * object rather than an arbitrary `process.env`-shaped value.+ */+export interface SanitizedAcpxSpawnInput {+ readonly env: Readonly<NodeJS.ProcessEnv>;+ readonly [sanitizedAcpxSpawnInputBrand]: true;+}++/**+ * Build the only host-environment input that may cross an ACPX child-process+ * launch boundary. Agent-specific homes are added by the later runtime sandbox;+ * Paperclip transport and native MCP credentials are never inherited from the+ * host process.+ */+export function createSanitizedAcpxSpawnInput(+ environment: NodeJS.ProcessEnv | undefined,+ agent: QualifiedAcpxAgent,+): SanitizedAcpxSpawnInput {+ const source = environment ?? process.env;+ const result: NodeJS.ProcessEnv = {};+ const credentialNames =+ agent === "pi"+ ? ["OPENROUTER_API_KEY"]+ : agent === "claude"+ ? ["ANTHROPIC_API_KEY", "CLAUDE_CODE_OAUTH_TOKEN"]+ : [+ "OPENAI_API_KEY",+ "CODEX_API_KEY",+ ];+ const allowed = new Set([+ "PATH",+ "LANG",+ "LANGUAGE",+ "TZ",+ "TMPDIR",+ "TEMP",+ "TMP",+ "SSL_CERT_FILE",+ "SSL_CERT_DIR",+ "NODE_EXTRA_CA_CERTS",+ "HTTP_PROXY",+ "HTTPS_PROXY",+ "NO_PROXY",+ "ALL_PROXY",+ "http_proxy",+ "https_proxy",+ "no_proxy",+ "all_proxy",+ "RUST_BACKTRACE",+ "PAPERCLIP_NATIVE_MCP_NAME",+ "PAPERCLIP_NATIVE_MCP_URL",+ ...credentialNames,+ ]);+ let retainedBytes = 0;+ for (const [key, value] of Object.entries(source)) {+ if (typeof value !== "string") continue;+ if (!allowed.has(key) && !/^LC_[A-Z0-9_]{1,32}$/.test(key)) continue;+ if (key.includes("\0") || value.includes("\0")) {+ throw new Error("ACPX environment contains a null byte");+ }+ const entryBytes = Buffer.byteLength(key) + Buffer.byteLength(value);+ if (entryBytes > 64 * 1024 || retainedBytes + entryBytes > 256 * 1024) {+ throw new Error("ACPX environment exceeds its bounded launch size");+ }+ retainedBytes += entryBytes;+ result[key] = value;+ }+ return Object.freeze({+ env: Object.freeze(result),+ }) as SanitizedAcpxSpawnInput;+}diff --git a/packages/paperclip-runner/src/drivers/acpx/qualified-profiles.test.ts b/packages/paperclip-runner/src/drivers/acpx/qualified-profiles.test.tsnew file mode 100644index 0000000000..142115db99--- /dev/null+++ b/packages/paperclip-runner/src/drivers/acpx/qualified-profiles.test.ts@@ -0,0 +1,26 @@+import { describe, expect, it } from "vitest";++import {+ QUALIFIED_ACPX_PROFILES,+ resolveQualifiedAcpxProfile,+} from "./qualified-profiles.js";++describe("qualified ACPX profiles", () => {+ it("binds each agent to one immutable package and model declaration", () => {+ for (const agent of ["pi", "claude", "codex"] as const) {+ const profile = QUALIFIED_ACPX_PROFILES[agent];+ expect(profile.agent).toBe(agent);+ expect(profile.commandDigest).toMatch(/^sha256:[a-f0-9]{64}$/);+ expect(Object.isFrozen(profile)).toBe(true);+ expect(+ resolveQualifiedAcpxProfile(agent, profile.qualificationModel),+ ).toEqual(profile);+ }+ });++ it("rejects unqualified model substitutions", () => {+ expect(() =>+ resolveQualifiedAcpxProfile("codex", "some-other-model"),+ ).toThrow("requires exact model");+ });+});diff --git a/packages/paperclip-runner/src/drivers/acpx/qualified-profiles.ts b/packages/paperclip-runner/src/drivers/acpx/qualified-profiles.tsnew file mode 100644index 0000000000..403a334110--- /dev/null+++ b/packages/paperclip-runner/src/drivers/acpx/qualified-profiles.ts@@ -0,0 +1,110 @@+export const QUALIFIED_ACPX_VERSION = "0.13.1" as const;+export const ACPX_DRIVER_KIND = "acpx_runtime" as const;+export const ACPX_DRIVER_PROTOCOL_VERSION = 1 as const;++import type { NativeAcpxAgent } from "../../contracts/native-execution.js";++export type QualifiedAcpxAgent = NativeAcpxAgent;++export interface QualifiedAcpxProfile {+ readonly driverKind: typeof ACPX_DRIVER_KIND;+ readonly protocolVersion: typeof ACPX_DRIVER_PROTOCOL_VERSION;+ readonly acpxVersion: typeof QUALIFIED_ACPX_VERSION;+ readonly agent: QualifiedAcpxAgent;+ readonly agentProfileVersion: 1;+ readonly agentServerPackage: string;+ readonly agentServerVersion: string;+ readonly agentRuntimePackage: string | null;+ readonly agentRuntimeVersion: string | null;+ readonly commandDigest: string;+ readonly qualificationModel: string;+ /**+ * Model identifier the pinned ACP server reports after accepting the exact+ * qualification model. Most agents echo the requested model. Claude's ACP+ * server deliberately exposes its stable SDK selector (`sonnet`) while the+ * SDK resolves that selector to the canonical wire model+ * (`claude-sonnet-5`). Paperclip verifies the exact request was accepted+ * before treating this identifier as the qualified effective model.+ */+ readonly reportedModelId: string;+ readonly permissionPolicy: "interactive";+}++/**+ * Digests bind the closed profile declaration (package, version, runtime and+ * model), not a caller-controlled executable. The environment probe separately+ * verifies the resolved package files before a billable prompt is admitted.+ */+export const QUALIFIED_ACPX_PROFILES: Readonly<+ Record<QualifiedAcpxAgent, QualifiedAcpxProfile>+> = deepFreeze({+ pi: {+ driverKind: ACPX_DRIVER_KIND,+ protocolVersion: ACPX_DRIVER_PROTOCOL_VERSION,+ acpxVersion: QUALIFIED_ACPX_VERSION,+ agent: "pi",+ agentProfileVersion: 1,+ agentServerPackage: "pi-acp",+ agentServerVersion: "0.0.33",+ agentRuntimePackage: "@earendil-works/pi-coding-agent",+ agentRuntimeVersion: "0.84.2",+ commandDigest:+ "sha256:8c696f38296d53d0061fa11534570c5ddd951b63532aed30e0f1fcc676dc169f",+ qualificationModel: "openrouter/deepseek/deepseek-v4-flash-0731",+ reportedModelId: "openrouter/deepseek/deepseek-v4-flash-0731",+ permissionPolicy: "interactive",+ },+ claude: {+ driverKind: ACPX_DRIVER_KIND,+ protocolVersion: ACPX_DRIVER_PROTOCOL_VERSION,+ acpxVersion: QUALIFIED_ACPX_VERSION,+ agent: "claude",+ agentProfileVersion: 1,+ agentServerPackage: "@agentclientprotocol/claude-agent-acp",+ agentServerVersion: "0.70.0",+ agentRuntimePackage: null,+ agentRuntimeVersion: null,+ commandDigest:+ "sha256:9d73d1f0f121fb96cc8badb28c22d5bff02d8582eb2e40360a81c189e1b9422a",+ qualificationModel: "claude-sonnet-5",+ reportedModelId: "sonnet",+ permissionPolicy: "interactive",+ },+ codex: {+ driverKind: ACPX_DRIVER_KIND,+ protocolVersion: ACPX_DRIVER_PROTOCOL_VERSION,+ acpxVersion: QUALIFIED_ACPX_VERSION,+ agent: "codex",+ agentProfileVersion: 1,+ agentServerPackage: "@agentclientprotocol/codex-acp",+ agentServerVersion: "1.6.2",+ agentRuntimePackage: null,+ agentRuntimeVersion: null,+ commandDigest:+ "sha256:94049b3e3c3aee87de62703786e4fa81d031d7bd979f99bdf516d84f28791a79",+ qualificationModel: "gpt-5.6-sol",+ reportedModelId: "gpt-5.6-sol",+ permissionPolicy: "interactive",+ },+});++export function resolveQualifiedAcpxProfile(+ agent: QualifiedAcpxAgent,+ requestedModel: string,+): QualifiedAcpxProfile {+ const profile = QUALIFIED_ACPX_PROFILES[agent];+ if (requestedModel !== profile.qualificationModel) {+ throw new Error(+ `ACPX ${agent} profile requires exact model ${profile.qualificationModel}; received ${requestedModel}`,+ );+ }+ return structuredClone(profile);+}++function deepFreeze<T>(value: T): T {+ if (typeof value !== "object" || value === null || Object.isFrozen(value))+ return value;+ Object.freeze(value);+ for (const child of Object.values(value)) deepFreeze(child);+ return value;+}diff --git a/packages/paperclip-runner/src/drivers/acpx/sidecar-protocol.test.ts b/packages/paperclip-runner/src/drivers/acpx/sidecar-protocol.test.tsnew file mode 100644index 0000000000..eff7054af1--- /dev/null+++ b/packages/paperclip-runner/src/drivers/acpx/sidecar-protocol.test.ts@@ -0,0 +1,114 @@+import { describe, expect, it } from "vitest";++import {+ ACPX_SIDECAR_MAX_FRAME_BYTES,+ boundedSidecarValue,+ parseAcpxSidecarRequest,+ sanitizeAcpxPlanEntries,+} from "./sidecar-protocol.js";++describe("ACPX sidecar request parsing", () => {+ it("accepts only bounded, versioned, generated commands", () => {+ expect(+ parseAcpxSidecarRequest({+ protocolVersion: 2,+ id: 1,+ command: "session.open",+ params: { cwd: "/workspace" },+ }),+ ).toEqual({+ protocolVersion: 2,+ id: 1,+ command: "session.open",+ params: { cwd: "/workspace" },+ });+ expect(() =>+ parseAcpxSidecarRequest({+ protocolVersion: 3,+ id: 1,+ command: "session.open",+ params: {},+ }),+ ).toThrow("unsupported ACPX sidecar protocol version");+ expect(() =>+ parseAcpxSidecarRequest({+ protocolVersion: 2,+ id: 1,+ command: "session.destroy",+ params: {},+ }),+ ).toThrow("unsupported ACPX sidecar command");+ expect(() =>+ parseAcpxSidecarRequest({+ protocolVersion: 2,+ id: 1,+ command: "session.open",+ params: [],+ }),+ ).toThrow("params must be an object");+ expect(() =>+ parseAcpxSidecarRequest({+ protocolVersion: 2,+ id: 1,+ command: "session.open",+ params: {},+ extra: true,+ }),+ ).toThrow("unknown field");+ });++ it("bounds and safely sanitizes arbitrary values", () => {+ expect(() =>+ parseAcpxSidecarRequest({+ protocolVersion: 2,+ id: 1,+ command: "initialize",+ params: { value: "x".repeat(ACPX_SIDECAR_MAX_FRAME_BYTES) },+ }),+ ).toThrow("frame limit");+ const cyclic: Record<string, unknown> = {};+ cyclic.self = cyclic;+ expect(boundedSidecarValue(cyclic)).toEqual({+ omitted: true,+ reason: "serialization_failed",+ });+ expect(boundedSidecarValue(["not", "an", "object"])).toEqual({+ omitted: true,+ reason: "object_required",+ });+ });+});++describe("ACPX sidecar structured plans", () => {+ it("preserves every valid ordered entry while bounding and sanitizing the snapshot", () => {+ const entries = sanitizeAcpxPlanEntries([+ { content: " Inspect ", status: "completed", priority: "high" },+ { content: "Implement", status: "in_progress", priority: "medium" },+ { content: "Verify", status: "pending", priority: "low" },+ { content: "Invalid status", status: "failed" },+ { content: " ", status: "pending" },+ {+ content: "x".repeat(5_000),+ status: "pending",+ priority: "p".repeat(100),+ },+ ]);++ expect(entries.slice(0, 3)).toEqual([+ { content: "Inspect", status: "completed", priority: "high" },+ { content: "Implement", status: "in_progress", priority: "medium" },+ { content: "Verify", status: "pending", priority: "low" },+ ]);+ expect(entries).toHaveLength(4);+ expect(entries[3]?.content).toHaveLength(4_000);+ expect(entries[3]?.priority).toHaveLength(80);+ expect(+ sanitizeAcpxPlanEntries(+ Array.from({ length: 300 }, (_, index) => ({+ content: `Step ${index}`,+ status: "pending",+ })),+ ),+ ).toHaveLength(256);+ });+});diff --git a/packages/paperclip-runner/src/drivers/acpx/sidecar-protocol.ts b/packages/paperclip-runner/src/drivers/acpx/sidecar-protocol.tsnew file mode 100644index 0000000000..912d076a98--- /dev/null+++ b/packages/paperclip-runner/src/drivers/acpx/sidecar-protocol.ts@@ -0,0 +1,172 @@+import type { QualifiedAcpxAgent } from "./qualified-profiles.js";+import type { NativeRuntimeContextSnapshot } from "../../contracts/runtime-context.js";+import type { NativeAcpxPermissionMode } from "../../contracts/native-execution.js";+import {+ GENERATED_ACPX_SIDECAR_COMMANDS,+ GENERATED_ACPX_SIDECAR_PROTOCOL_VERSION,+ type GeneratedAcpxSidecarCommand,+ type GeneratedAcpxSidecarEventType,+} from "./generated-sidecar-contract.js";++export const ACPX_SIDECAR_PROTOCOL_VERSION =+ GENERATED_ACPX_SIDECAR_PROTOCOL_VERSION;+export const ACPX_SIDECAR_MAX_FRAME_BYTES = 1024 * 1024;++export interface AcpxSidecarRequest {+ protocolVersion: typeof ACPX_SIDECAR_PROTOCOL_VERSION;+ id: number;+ command: GeneratedAcpxSidecarCommand;+ params: Record<string, unknown>;+}++export interface AcpxSidecarResponse {+ protocolVersion: typeof ACPX_SIDECAR_PROTOCOL_VERSION;+ id: number;+ ok: boolean;+ result?: Record<string, unknown>;+ error?: { code: string; message: string; retryable: boolean };+}++export interface AcpxSidecarEvent {+ protocolVersion: typeof ACPX_SIDECAR_PROTOCOL_VERSION;+ sequence: number;+ eventType: GeneratedAcpxSidecarEventType;+ runId: string | null;+ turnId: string | null;+ payload: Record<string, unknown>;+}++export interface AcpxSidecarOpenParams {+ runtimeDirectory: string;+ normalizedSessionId: string;+ workingDirectory: string;+ agent: QualifiedAcpxAgent;+ model: string;+ permissionMode: NativeAcpxPermissionMode;+ permissionModePinned: boolean;+ systemInstructions: string;+ runtimeContext: NativeRuntimeContextSnapshot | null;+ tools: readonly Readonly<Record<string, unknown>>[];+ providerSessionKey?: string;+ expectedIdentity?: AcpxExpectedSessionIdentity;+}++export interface AcpxExpectedSessionIdentity {+ kind: "acpx";+ normalizedSessionId: string;+ acpxRecordId: string;+ backendSessionId: string;+ agentSessionId: string;+ profileDigest: string;+ workspaceDigest: string;+ requestedModel: string;+ effectiveModel: string;+ permissionMode?: NativeAcpxPermissionMode;+}++export function parseAcpxSidecarRequest(value: unknown): AcpxSidecarRequest {+ let serialized: string;+ try {+ serialized = JSON.stringify(value);+ } catch {+ throw new Error("ACPX sidecar request is not JSON serializable");+ }+ if (+ !serialized ||+ Buffer.byteLength(serialized) > ACPX_SIDECAR_MAX_FRAME_BYTES+ ) {+ throw new Error("ACPX sidecar request exceeds the frame limit");+ }+ if (typeof value !== "object" || value === null || Array.isArray(value)) {+ throw new Error("ACPX sidecar request must be an object");+ }+ const request = value as Record<string, unknown>;+ if (+ Object.keys(request).some(+ (key) => !["protocolVersion", "id", "command", "params"].includes(key),+ )+ ) {+ throw new Error("ACPX sidecar request contains an unknown field");+ }+ if (request.protocolVersion !== ACPX_SIDECAR_PROTOCOL_VERSION) {+ throw new Error("unsupported ACPX sidecar protocol version");+ }+ if (!Number.isSafeInteger(request.id) || Number(request.id) < 1)+ throw new Error("sidecar request id must be a positive integer");+ const command = text(request.command);+ if (!(GENERATED_ACPX_SIDECAR_COMMANDS as readonly string[]).includes(command))+ throw new Error("unsupported ACPX sidecar command");+ if (+ typeof request.params !== "object" ||+ request.params === null ||+ Array.isArray(request.params)+ ) {+ throw new Error("ACPX sidecar request params must be an object");+ }+ return {+ protocolVersion: ACPX_SIDECAR_PROTOCOL_VERSION,+ id: Number(request.id),+ command: command as AcpxSidecarRequest["command"],+ params: structuredClone(request.params as Record<string, unknown>),+ };+}++export function boundedSidecarValue(+ value: unknown,+ maxBytes = 64 * 1024,+): Record<string, unknown> {+ if (!Number.isSafeInteger(maxBytes) || maxBytes < 1) {+ throw new Error("ACPX sidecar value limit must be a positive integer");+ }+ try {+ const serialized = JSON.stringify(value);+ if (!serialized || Buffer.byteLength(serialized) > maxBytes) {+ return { omitted: true, reason: "payload_limit" };+ }+ const parsed = JSON.parse(serialized);+ return typeof parsed === "object" &&+ parsed !== null &&+ !Array.isArray(parsed)+ ? (parsed as Record<string, unknown>)+ : { omitted: true, reason: "object_required" };+ } catch {+ return { omitted: true, reason: "serialization_failed" };+ }+}++export function sanitizeAcpxPlanEntries(value: unknown): Array<{+ content: string;+ status: "pending" | "in_progress" | "completed";+ priority: string | null;+}> {+ if (!Array.isArray(value)) return [];+ return value.slice(0, 256).flatMap((candidate) => {+ const entry = record(candidate);+ const content = text(entry.content).trim().slice(0, 4_000);+ const status = text(entry.status);+ if (+ !content ||+ (status !== "pending" &&+ status !== "in_progress" &&+ status !== "completed")+ )+ return [];+ return [+ {+ content,+ status,+ priority: text(entry.priority).slice(0, 80) || null,+ },+ ];+ });+}++export function record(value: unknown): Record<string, unknown> {+ return typeof value === "object" && value !== null && !Array.isArray(value)+ ? (value as Record<string, unknown>)+ : {};+}++export function text(value: unknown, fallback = ""): string {+ return typeof value === "string" ? value : fallback;+}diff --git a/patches/[email protected] b/patches/[email protected]index 8d5500a705..033460fad5 100644--- a/patches/[email protected]+++ b/patches/[email protected]@@ -20,6 +20,62 @@ index 243c9d13bcba520923b63adfddad75cf2d94362d..336a1699b80b9e99416f9da4346ca73ecurrent: state.current,quote: state.quote,escaping: true,+@@ -2914,15 +2914,15 @@+ }+-function buildAgentEnvironment(authCredentials, sessionEnv) {+- const env = { ...process.env };+- const protectedAuthEnvKeys = promotePrefixedAuthEnvironment(env);+- if (authCredentials) for (const [methodId, credential] of Object.entries(authCredentials)) {+- addAuthCredentialEnvKeys(protectedAuthEnvKeys, methodId, credential);+- assignAuthCredentialEnv(env, methodId, credential);+- }+- if (sessionEnv) for (const [key, value] of Object.entries(sessionEnv)) {+- if (typeof value !== "string" || protectedAuthEnvKeys.has(protectedEnvKey(key))) continue;+- assignSessionEnv(env, key, value);+- }+- return env;+-}++function buildAgentEnvironment(authCredentials, sessionEnv, inheritProcessEnv = true) {++ const env = inheritProcessEnv ? { ...process.env } : {};++ const protectedAuthEnvKeys = promotePrefixedAuthEnvironment(env);++ if (authCredentials) for (const [methodId, credential] of Object.entries(authCredentials)) {++ addAuthCredentialEnvKeys(protectedAuthEnvKeys, methodId, credential);++ assignAuthCredentialEnv(env, methodId, credential);++ }++ if (sessionEnv) for (const [key, value] of Object.entries(sessionEnv)) {++ if (typeof value !== "string" || protectedAuthEnvKeys.has(protectedEnvKey(key))) continue;++ assignSessionEnv(env, key, value);++ }++ return env;++}+ function assignSessionEnv(env, key, value) {+@@ -2957,14 +2957,14 @@+ }+-function buildAgentSpawnOptions(cwd, authCredentials, sessionEnv) {+- return {+- cwd,+- env: buildAgentEnvironment(authCredentials, sessionEnv),+- stdio: [+- "pipe",+- "pipe",+- "pipe"+- ],+- windowsHide: true+- };+-}++function buildAgentSpawnOptions(cwd, authCredentials, sessionEnv, inheritProcessEnv) {++ return {++ cwd,++ env: buildAgentEnvironment(authCredentials, sessionEnv, inheritProcessEnv),++ stdio: [++ "pipe",++ "pipe",++ "pipe"++ ],++ windowsHide: true++ };++}+ //#endregion@@ -3959,7 +3959,24 @@ var AcpClient = class {- this.attachAgentLifecycleObservers(child);+ this.attachAgentLifecycleObservers(child);@@ -51,7 +107,7 @@ index 243c9d13bcba520923b63adfddad75cf2d94362d..336a1699b80b9e99416f9da4346ca73ecopilotAcp: isCopilotAcpCommand(spawnCommand, args),claudeAcp: isClaudeAcpCommand(spawnCommand, args),- spawnOptions: buildAgentSpawnOptions(this.options.cwd, this.options.authCredentials, this.options.sessionOptions?.env)-+ spawnOptions: buildAgentSpawnOptions(this.options.spawnCwd ?? this.options.cwd, this.options.authCredentials, this.options.sessionOptions?.env)++ spawnOptions: buildAgentSpawnOptions(this.options.spawnCwd ?? this.options.cwd, this.options.authCredentials, this.options.sessionOptions?.env, this.options.inheritProcessEnv)};}logAgentLaunch(plan) {@@ -59,13 +115,14 @@ diff --git a/dist/runtime.d.ts b/dist/runtime.d.tsindex ccdbe5b032521518022223733049b8b38793473b..3d4e04231e78efeecd8540735b08e1e43547ff2d 100644--- a/dist/runtime.d.ts+++ b/dist/runtime.d.ts-@@ -266,6 +266,9 @@ type AcpRuntimeOptions = {+@@ -266,6 +266,10 @@ type AcpRuntimeOptions = {timeoutMs?: number;probeAgent?: string;verbose?: boolean;+ onAgentStderr?: (chunk: string) => void;+ onAgentSpawn?: (meta: { pid: number; startedAt: string }) => Promise<void>;+ spawnCwd?: string;++ inheritProcessEnv?: boolean;onPermissionRequest?: (req: AcpPermissionRequest, ctx: {signal: AbortSignal;}) => Promise<AcpPermissionDecision | undefined>;@@ -78,7 +135,7 @@ index 6c9cc999e50a11c399c68b3a0f1b7af4bc2317c0..33b5054b2906502d1d4b512bfa259bd2}createClient(options) {- return this.deps.clientFactory?.(options) ?? new AcpClient(options);-+ const clientOptions = { ...options, onAgentStderr: this.options.onAgentStderr, onAgentSpawn: this.options.onAgentSpawn, spawnCwd: this.options.spawnCwd };++ const clientOptions = { ...options, onAgentStderr: this.options.onAgentStderr, onAgentSpawn: this.options.onAgentSpawn, spawnCwd: this.options.spawnCwd, inheritProcessEnv: this.options.inheritProcessEnv };+ return this.deps.clientFactory?.(clientOptions) ?? new AcpClient(clientOptions);}async readPendingPersistentClient(record, options) {@@ -87,13 +144,14 @@ diff --git a/dist/session-options-jkYbBxGE.d.ts b/dist/session-options-jkYbBxGE.index 9d37f377fb6a0828e0d2bc5a48754f3aa71509a4..680bc080fc5d6ffd266ed1b27d3d5056add9d980 100644--- a/dist/session-options-jkYbBxGE.d.ts+++ b/dist/session-options-jkYbBxGE.d.ts-@@ -84,6 +84,9 @@ type AcpClientOptions = {+@@ -84,6 +84,10 @@ type AcpClientOptions = {terminal?: boolean;suppressSdkConsoleErrors?: boolean;verbose?: boolean;+ onAgentStderr?: (chunk: string) => void;+ onAgentSpawn?: (meta: { pid: number; startedAt: string }) => Promise<void>;+ spawnCwd?: string;++ inheritProcessEnv?: boolean;sessionOptions?: {model?: string;allowedTools?: string[];