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(observability): rename sandbox provider spans and add run-time wrapper spans (#10999)
Nicky Leach9ace548fd215
diff --git a/packages/adapter-utils/src/acpx-engine/execute.ts b/packages/adapter-utils/src/acpx-engine/execute.tsindex 868df3897f..a43c2543e1 100644--- a/packages/adapter-utils/src/acpx-engine/execute.ts+++ b/packages/adapter-utils/src/acpx-engine/execute.ts@@ -84,12 +84,14 @@ import {DEFAULT_ACP_ENGINE_WARM_HANDLE_IDLE_MS,} from "./constants.js";import {+ createRuntimeSpanRunner,emitSkippedStartupStep,measureStartupStep,NOOP_STARTUP_SPAN,NOOP_STARTUP_TRACE_CONTEXT,runWithRuntimeParent,setSandboxRootSpanAttributes,+ type RuntimeSpanRunner,type SandboxRootSpanContext,type StartupSpan,type StartupSpanContext,@@ -1367,6 +1369,12 @@ async function buildRuntime(input: {// run closure passes the run-scoped getter here; when it is absent, each// bridge site keeps its earlier unparented run-time behavior.getRuntimeParentContext?: () => StartupSpanContext | undefined;+ // Wrap each unit of bridge run-time work in its own named span.+ // `buildRuntime` threads it into the two remote bridge factories, so the+ // socket handler, the poll loop, and the callback worker each open a wrapper+ // span per unit of work. The run closure passes the run-scoped runner here;+ // when it is absent, each bridge site opens no wrapper span.+ runtimeSpan?: RuntimeSpanRunner;}): Promise<AcpxPreparedRuntime> {const { runId, agent, config, context, authToken } = input.ctx;// Injectable monotonic clock for per-step startup timing. Hoisted above the@@ -1963,6 +1971,7 @@ async function buildRuntime(input: {hostApiToken: env.PAPERCLIP_API_KEY,onLog: input.ctx.onLog,getRuntimeParentContext: input.getRuntimeParentContext,+ runtimeSpan: input.runtimeSpan,}),concurrentBridgeStepMetrics,);@@ -1994,6 +2003,7 @@ async function buildRuntime(input: {timeoutSec,onLog: input.ctx.onLog,getRuntimeParentContext: input.getRuntimeParentContext,+ runtimeSpan: input.runtimeSpan,}),concurrentBridgeStepMetrics,);@@ -3131,6 +3141,12 @@ export function createAcpxEngineExecutor(deps: AcpxEngineExecutorOptions = {}) {// reads it through `getRuntimeParentContext` to parent to the live span.let currentRunParentContext: StartupSpanContext | undefined = runRootSpan.parentContext;const getRuntimeParentContext = (): StartupSpanContext | undefined => currentRunParentContext;+ // Wrap each unit of bridge run-time work (one outbound ACP message, one poll+ // tick, one callback request) in its own named span, parented to the live run+ // span. The runner reads the run parent per call through+ // `getRuntimeParentContext`, so a wrapper span always parents to the current+ // run span. On a no-op trace context the runner opens no real span.+ const runRuntimeSpan = createRuntimeSpanRunner(tracing, getRuntimeParentContext);// `runFailed` marks the run root span status at end time. It stays `true`// until the run reaches a clean completed turn, so every failure and every// early exit closes the span with error status.@@ -3190,7 +3206,7 @@ export function createAcpxEngineExecutor(deps: AcpxEngineExecutorOptions = {}) {// parents to its step span. On a local or SSH target// `spanParent.parentContext` is a no-op token, so the wrap is inert.prepared = await runWithRuntimeParent(spanParent.parentContext, () =>- buildRuntime({ ctx, engine, deps, spanParent, getRuntimeParentContext }),+ buildRuntime({ ctx, engine, deps, spanParent, getRuntimeParentContext, runtimeSpan: runRuntimeSpan }),);} catch (err) {rootSpan.end(true);diff --git a/packages/adapter-utils/src/acpx-engine/startup-timing.test.ts b/packages/adapter-utils/src/acpx-engine/startup-timing.test.tsindex 1678282143..14c7e0bfe2 100644--- a/packages/adapter-utils/src/acpx-engine/startup-timing.test.ts+++ b/packages/adapter-utils/src/acpx-engine/startup-timing.test.ts@@ -1,12 +1,14 @@import { describe, expect, it, vi } from "vitest";import type { AdapterRuntimeEvent } from "../types.js";-import type { StartupSpan, StartupTracer } from "./startup-timing.js";+import type { StartupSpan, StartupTraceContext, StartupTracer } from "./startup-timing.js";import {clampSpanLabel,+ createRuntimeSpanRunner,emitSkippedStartupStep,getActiveStepContext,measureStartupStep,NOOP_STARTUP_SPAN,+ NOOP_STARTUP_TRACE_CONTEXT,normalizeProviderFamily,runWithoutActiveStep,runWithRuntimeParent,@@ -653,3 +655,60 @@ describe("clampSpanLabel", () => {expect(clampSpanLabel("stdout", "secret output")).toBeUndefined();});});++describe("createRuntimeSpanRunner", () => {+ it("opens a named wrapper span and parents the wrapped work to it", async () => {+ const { tracer, spans } = makeMockTracer();+ const runParent = { marker: "run-parent" };+ const traceContext: StartupTraceContext = {+ tracer,+ contextWithSpan: (span) => ({ span }),+ };+ const run = createRuntimeSpanRunner(traceContext, () => runParent);++ let childParent: unknown = "unset";+ const result = await run("sandbox.agentSession.sendInput", async () => {+ childParent = getActiveStepContext()?.parentContext;+ return "ok";+ });++ expect(result).toBe("ok");+ expect(spans).toHaveLength(1);+ expect(spans[0]!.name).toBe("sandbox.agentSession.sendInput");+ expect(spans[0]!.endCount).toBe(1);+ // The wrapped work parents to the wrapper span, not straight to the run+ // parent, so the inner exec spans group under the wrapper span.+ expect((childParent as { span?: unknown }).span).toBe(spans[0]);+ });++ it("marks the wrapper span failed and ends it when the work throws", async () => {+ const { tracer, spans } = makeMockTracer();+ const traceContext: StartupTraceContext = {+ tracer,+ contextWithSpan: (span) => ({ span }),+ };+ const run = createRuntimeSpanRunner(traceContext, () => ({ marker: "run-parent" }));++ await expect(+ run("sandbox.callbackBridge.relayRequest", async () => {+ throw new Error("boom");+ }),+ ).rejects.toThrow(/boom/);+ expect(spans).toHaveLength(1);+ expect(spans[0]!.status?.code).toBe(2);+ expect(spans[0]!.endCount).toBe(1);+ });++ it("runs the work unwrapped under a no-op trace context", async () => {+ const run = createRuntimeSpanRunner(NOOP_STARTUP_TRACE_CONTEXT, () => ({ marker: "run-parent" }));+ // The no-op `contextWithSpan` yields no child token, so the store empties for+ // the work, exactly like the earlier unparented run-time behavior.+ let childStep: unknown = "unset";+ const result = await run("sandbox.agentSession.pollOutput", async () => {+ childStep = getActiveStepContext();+ return 7;+ });+ expect(result).toBe(7);+ expect(childStep).toBeNull();+ });+});diff --git a/packages/adapter-utils/src/acpx-engine/startup-timing.ts b/packages/adapter-utils/src/acpx-engine/startup-timing.tsindex f49f3ccfd6..ce91ca6a5b 100644--- a/packages/adapter-utils/src/acpx-engine/startup-timing.ts+++ b/packages/adapter-utils/src/acpx-engine/startup-timing.ts@@ -402,6 +402,66 @@ export function runWithRuntimeParent<T>(return activeStepContextStorage.run(activeStep, work);}+/**+ * Run one run-time operation inside its own wrapper span. The runner opens a+ * wrapper span parented to the current run span, publishes the wrapper span as+ * the runtime parent while `work` runs, and ends the span when `work` settles.+ * A child `sandbox.exec` span inside `work` parents to the wrapper span, so the+ * trace groups the operation's execs under one named span. A throwing `work`+ * sets the wrapper span error status before the span ends.+ *+ * The runner reads the run parent per call, so it always parents to the live+ * span (`agent.turn` during the turn, `task.run` otherwise). The default runner+ * opens no real span; it only runs `work` under the current run parent, so the+ * span path stays a no-op until the server injects a real tracer.+ */+export type RuntimeSpanRunner = <T>(name: string, work: () => Promise<T>) => Promise<T>;++/**+ * Build a {@link RuntimeSpanRunner} from a trace context and the run-parent+ * getter. The runner opens the wrapper span through `traceContext.tracer`, and+ * it derives the wrapper span's child parent token through+ * `traceContext.contextWithSpan`. A no-op trace context yields a runner that+ * opens no real span and runs `work` under the current run parent, so the span+ * path stays inert until the server injects a real tracer. Every tracer call+ * sits inside an error swallow, so a throwing tracer never changes control flow.+ */+export function createRuntimeSpanRunner(+ traceContext: StartupTraceContext,+ getRuntimeParentContext: () => StartupSpanContext | undefined,+): RuntimeSpanRunner {+ return async <T>(name: string, work: () => Promise<T>): Promise<T> => {+ const parentContext = getRuntimeParentContext();+ let span: StartupSpan;+ try {+ span = traceContext.tracer.startSpan(name, undefined, parentContext);+ } catch {+ // A throwing tracer must not change control flow; run `work` unwrapped.+ return runWithRuntimeParent(parentContext, work);+ }+ let childContext: StartupSpanContext;+ try {+ childContext = traceContext.contextWithSpan(span);+ } catch {+ childContext = parentContext;+ }+ let failed = false;+ try {+ return await runWithRuntimeParent(childContext, work);+ } catch (err) {+ failed = true;+ throw err;+ } finally {+ try {+ if (failed) span.setStatus({ code: SPAN_STATUS_CODE_ERROR });+ span.end();+ } catch {+ // Observability must not change control flow.+ }+ }+ };+}+/*** Set a numeric span attribute only when the value is a finite number. A reader* that returns `undefined` (the counter is unavailable) yields no attribute,diff --git a/packages/adapter-utils/src/execution-target-sandbox.test.ts b/packages/adapter-utils/src/execution-target-sandbox.test.tsindex 321e88cb15..d4425a6ddf 100644--- a/packages/adapter-utils/src/execution-target-sandbox.test.ts+++ b/packages/adapter-utils/src/execution-target-sandbox.test.ts@@ -481,6 +481,131 @@ describe("sandbox adapter execution targets", () => {}});+ it("wraps a stdin write in a sandbox.agentSession.sendInput span", async () => {+ // With a span runner injected, the socket handler wraps one outbound ACP+ // message to the agent in a `sandbox.agentSession.sendInput` span. This test+ // connects a socket, sends one stdin line, and proves the handler opens that+ // wrapper span around the write.+ const rootDir = await mkdtemp(path.join(os.tmpdir(), "paperclip-process-session-sendinput-span-"));+ cleanupDirs.push(rootDir);+ const childPath = path.join(rootDir, "noop-acp-child.mjs");+ await writeFile(childPath, "process.stdin.on('data', () => {});\n", "utf8");++ const spanNames: string[] = [];+ let resolveSendInput: () => void = () => {};+ const sendInputObserved = new Promise<void>((resolve) => {+ resolveSendInput = resolve;+ });++ const target: AdapterSandboxExecutionTarget = {+ kind: "remote",+ transport: "sandbox",+ providerKey: "local-test",+ remoteCwd: rootDir,+ timeoutMs: 30_000,+ runner: createLocalSandboxRunner(),+ };++ const bridge = await startAdapterExecutionTargetProcessSessionBridge({+ runId: "run-process-session-sendinput-span",+ target,+ runtimeRootDir: path.posix.join(rootDir, ".paperclip-runtime", "acpx"),+ adapterKey: "acpx",+ command: process.execPath,+ args: [childPath],+ cwd: rootDir,+ env: {},+ timeoutSec: 5,+ onLog: async () => {},+ // Record each wrapper span name, then run the wrapped work.+ runtimeSpan: async (name, work) => {+ spanNames.push(name);+ if (name === "sandbox.agentSession.sendInput") resolveSendInput();+ return work();+ },+ });+ expect(bridge).not.toBeNull();++ let peer: net.Socket | null = null;+ try {+ const proxySource = await readFile(bridge!.agentCommand, "utf8");+ const port = Number(/port: (\d+)/.exec(proxySource)?.[1] ?? Number.NaN);+ const tokenLiteral = /const token = (".*?");/.exec(proxySource)?.[1];+ const token = JSON.parse(tokenLiteral as string) as string;++ const peerSocket = net.createConnection({ host: "127.0.0.1", port });+ peer = peerSocket;+ peerSocket.on("error", () => undefined);+ await new Promise<void>((resolve, reject) => {+ peerSocket.once("connect", () => resolve());+ peerSocket.once("error", reject);+ });++ // The first token-bearing message authenticates and writes the stdin file.+ peerSocket.write(+ `${JSON.stringify({ token, type: "stdin", data: Buffer.from("hi").toString("base64") })}\n`,+ );++ await sendInputObserved;+ expect(spanNames).toContain("sandbox.agentSession.sendInput");+ } finally {+ peer?.destroy();+ await bridge?.stop();+ }+ });++ it("wraps each poll tick in a sandbox.agentSession.pollOutput span", async () => {+ // With a span runner injected, the poll timer wraps each 100 ms poll tick in+ // a `sandbox.agentSession.pollOutput` span. This test lets the first poll tick+ // fire and proves the timer opens that wrapper span.+ const rootDir = await mkdtemp(path.join(os.tmpdir(), "paperclip-process-session-poll-span-"));+ cleanupDirs.push(rootDir);+ const childPath = path.join(rootDir, "noop-acp-child.mjs");+ await writeFile(childPath, "process.stdin.on('data', () => {});\n", "utf8");++ const spanNames: string[] = [];+ let resolvePoll: () => void = () => {};+ const pollObserved = new Promise<void>((resolve) => {+ resolvePoll = resolve;+ });++ const target: AdapterSandboxExecutionTarget = {+ kind: "remote",+ transport: "sandbox",+ providerKey: "local-test",+ remoteCwd: rootDir,+ timeoutMs: 30_000,+ runner: createLocalSandboxRunner(),+ };++ const bridge = await startAdapterExecutionTargetProcessSessionBridge({+ runId: "run-process-session-poll-span",+ target,+ runtimeRootDir: path.posix.join(rootDir, ".paperclip-runtime", "acpx"),+ adapterKey: "acpx",+ command: process.execPath,+ args: [childPath],+ cwd: rootDir,+ env: {},+ timeoutSec: 5,+ onLog: async () => {},+ // Record each wrapper span name, then run the wrapped work.+ runtimeSpan: async (name, work) => {+ spanNames.push(name);+ if (name === "sandbox.agentSession.pollOutput") resolvePoll();+ return work();+ },+ });+ expect(bridge).not.toBeNull();++ try {+ await pollObserved;+ expect(spanNames).toContain("sandbox.agentSession.pollOutput");+ } finally {+ await bridge?.stop();+ }+ });+it("bridges bidirectional sandbox process sessions through a local ACPX-spawnable proxy", async () => {const rootDir = await mkdtemp(path.join(os.tmpdir(), "paperclip-process-session-"));cleanupDirs.push(rootDir);diff --git a/packages/adapter-utils/src/execution-target.ts b/packages/adapter-utils/src/execution-target.tsindex 0eb776e8cd..5e7aa5719f 100644--- a/packages/adapter-utils/src/execution-target.ts+++ b/packages/adapter-utils/src/execution-target.ts@@ -48,6 +48,7 @@ import { sanitizeRemoteExecutionEnv } from "./remote-execution-env.js";import { preferredShellForSandbox, shellCommandArgs } from "./sandbox-shell.js";import {runWithRuntimeParent,+ type RuntimeSpanRunner,type StartupSpanContext,} from "./acpx-engine/startup-timing.js";import type { RuntimeProgressSink, RuntimeStatusSink } from "./runtime-progress.js";@@ -1354,6 +1355,14 @@ async function waitForLocalServerListen(server: net.Server): Promise<number> {return address.port;}+/** Span name that wraps the socket handler's one `writeTextFile` exec — one+ * outbound ACP message to the agent. */+const AGENT_SESSION_SEND_INPUT_SPAN = "sandbox.agentSession.sendInput";++/** Span name that wraps one 100 ms poll tick — `list`, then `read`+`remove` per+ * file found (`1 + 2n` execs). */+const AGENT_SESSION_POLL_OUTPUT_SPAN = "sandbox.agentSession.pollOutput";+export async function startAdapterExecutionTargetProcessSessionBridge(input: {runId: string;target: AdapterExecutionTarget | null | undefined;@@ -1376,6 +1385,12 @@ export async function startAdapterExecutionTargetProcessSessionBridge(input: {// turn, `task.run` otherwise). When it is absent, the work runs with an empty// store, exactly like the earlier `runWithoutActiveStep` behavior.getRuntimeParentContext?: () => StartupSpanContext | undefined;+ // Wrap each unit of run-time work in its own named span. The socket handler+ // uses it for `sandbox.agentSession.sendInput` and the poll timer for+ // `sandbox.agentSession.pollOutput`, so each unit's inner `sandbox.exec` spans+ // group under one wrapper span. When it is absent, the work runs under the run+ // parent with no wrapper span, exactly like the earlier behavior.+ runtimeSpan?: RuntimeSpanRunner;}): Promise<AdapterExecutionTargetProcessSessionBridgeHandle | null> {if (!input.target || input.target.kind !== "remote" || input.target.transport !== "sandbox") {return null;@@ -1384,6 +1399,14 @@ export async function startAdapterExecutionTargetProcessSessionBridge(input: {const target = input.target;const onLog = input.onLog ?? (async () => {});const runner = requireSandboxRunner(target);+ // Run one unit of run-time work under its named wrapper span when a span+ // runner is injected. Without a runner, run the work under the current run+ // parent, so the inner `sandbox.exec` spans parent to the live run span,+ // exactly like the earlier behavior.+ const runRuntimeWork = <T>(name: string, work: () => Promise<T>): Promise<T> =>+ input.runtimeSpan+ ? input.runtimeSpan(name, work)+ : runWithRuntimeParent(input.getRuntimeParentContext?.(), work);const shellCommand = preferredSandboxShell(target);const timeoutMs =typeof input.timeoutSec === "number" && Number.isFinite(input.timeoutSec) && input.timeoutSec > 0@@ -1548,26 +1571,28 @@ export async function startAdapterExecutionTargetProcessSessionBridge(input: {socket = nextSocket;flushPendingRemoteEvents();}- // Read the current-run parent now, at send time. The live parent- // switches to `agent.turn` during the turn and back to `task.run`- // after it. With no getter the store stays empty, exactly like the- // earlier unparented behavior.- runWithRuntimeParent(input.getRuntimeParentContext?.(), () => {- void (async () => {- if (message.type === "stdin" && typeof message.data === "string") {- stdinSeq += 1;- const name = `${String(stdinSeq).padStart(12, "0")}.json`;- await client.writeTextFile(path.posix.join(stdinDir, name), jsonLine({ type: "stdin", data: message.data }));- } else if (message.type === "stdinEnd") {- stdinSeq += 1;- const name = `${String(stdinSeq).padStart(12, "0")}.json`;- await client.writeTextFile(path.posix.join(stdinDir, name), jsonLine({ type: "stdinEnd" }));- }- })().catch((error) => {+ // Wrap one outbound ACP message to the agent in a+ // `sandbox.agentSession.sendInput` span, so its one `writeTextFile` exec+ // groups under one named span. The span runner reads the current-run+ // parent at send time: the live parent switches to `agent.turn` during+ // the turn and back to `task.run` after it. A message that is neither+ // `stdin` nor `stdinEnd` writes nothing, so it opens no span.+ const stdinPayload =+ message.type === "stdin" && typeof message.data === "string"+ ? { type: "stdin", data: message.data }+ : message.type === "stdinEnd"+ ? { type: "stdinEnd" }+ : null;+ if (stdinPayload) {+ stdinSeq += 1;+ const name = `${String(stdinSeq).padStart(12, "0")}.json`;+ void runRuntimeWork(AGENT_SESSION_SEND_INPUT_SPAN, () =>+ client.writeTextFile(path.posix.join(stdinDir, name), jsonLine(stdinPayload)),+ ).catch((error) => {nextSocket.write(jsonLine({ type: "error", message: error instanceof Error ? error.message : String(error) }));nextSocket.destroy();});- });+ }}});});@@ -1600,15 +1625,16 @@ export async function startAdapterExecutionTargetProcessSessionBridge(input: {}};- // Schedule the long-lived poll timer under the current-run parent context.- // The poll loop reads remote event files with run-time execs, not startup- // work, so a poll `sandbox.exec` span parents to the live run span, not to the- // ended bridge step. Read the getter per tick, because the re-arm timer that- // the poll body schedules reads it again: the live parent switches to- // `agent.turn` during the turn and back to `task.run` after it. With no getter- // the store stays empty, exactly like the earlier unparented behavior.+ // Schedule the long-lived poll timer. Wrap each 100 ms poll tick in a+ // `sandbox.agentSession.pollOutput` span, so the tick's `list` plus per-file+ // `read`/`remove` execs group under one named span. The poll loop reads remote+ // event files with run-time execs, not startup work, so the wrapper span and+ // its child execs parent to the live run span, not to the ended bridge step.+ // The span runner reads the run parent per tick, because the re-arm timer that+ // the poll body schedules opens a new tick span: the live parent switches to+ // `agent.turn` during the turn and back to `task.run` after it.const schedulePoll = () => {- pollTimer = setTimeout(() => runWithRuntimeParent(input.getRuntimeParentContext?.(), () => void poll()), 100);+ pollTimer = setTimeout(() => void runRuntimeWork(AGENT_SESSION_POLL_OUTPUT_SPAN, poll), 100);pollTimer.unref?.();};@@ -1764,6 +1790,11 @@ export async function startAdapterExecutionTargetPaperclipBridge(input: {// `sandbox.exec` span parents to the live run span. When it is absent, the// request work runs with an empty store, exactly like the earlier behavior.getRuntimeParentContext?: () => StartupSpanContext | undefined;+ // Wrap each callback request in a `sandbox.callbackBridge.relayRequest` span.+ // The factory threads it into the worker, which uses it per request so each+ // request's execs group under one wrapper span. When it is absent, the request+ // work runs under the run parent with no wrapper span.+ runtimeSpan?: RuntimeSpanRunner;}): Promise<AdapterExecutionTargetPaperclipBridgeHandle | null> {if (!adapterExecutionTargetUsesPaperclipBridge(input.target)) {return null;@@ -1835,6 +1866,7 @@ export async function startAdapterExecutionTargetPaperclipBridge(input: {queueDir,maxBodyBytes,getRuntimeParentContext: input.getRuntimeParentContext,+ runtimeSpan: input.runtimeSpan,handleRequest: async (request) => {const method = request.method.trim().toUpperCase() || "GET";if (bridgeDebugEnabled) {diff --git a/packages/adapter-utils/src/sandbox-callback-bridge.test.ts b/packages/adapter-utils/src/sandbox-callback-bridge.test.tsindex 85a361f431..e69fef32c8 100644--- a/packages/adapter-utils/src/sandbox-callback-bridge.test.ts+++ b/packages/adapter-utils/src/sandbox-callback-bridge.test.ts@@ -611,6 +611,54 @@ describe("sandbox callback bridge", () => {expect((requestStep as { criticalPath?: boolean }).criticalPath).toBe(false);});+ it("wraps each request in a sandbox.callbackBridge.relayRequest span", async () => {+ // With a span runner injected, the worker wraps each request in one+ // `sandbox.callbackBridge.relayRequest` span, so the request's read, write,+ // and remove execs group under one named span. This test drives the worker+ // with a recording runner and proves it opens the wrapper span around the+ // request work.+ const wrapped: string[] = [];+ let served = false;+ let resolveServed: () => void = () => {};+ const requestServed = new Promise<void>((resolve) => {+ resolveServed = resolve;+ });++ const rootDir = await mkdtemp(path.join(os.tmpdir(), "paperclip-bridge-relay-span-"));+ cleanupDirs.push(rootDir);+ const queueDir = path.posix.join(rootDir, "queue");++ const worker = await startSandboxCallbackBridgeWorker({+ client: {+ makeDir: async () => {},+ makeDirs: async () => {},+ listJsonFiles: async () => (served ? [] : ["000000000001.json"]),+ readTextFile: async () =>+ JSON.stringify({ id: "req-1", method: "GET", path: "/", query: "", headers: {}, body: "" }),+ writeTextFile: async () => {},+ rename: async () => {},+ remove: async () => {},+ },+ queueDir,+ authorizeRequest: async () => null,+ handleRequest: async () => {+ served = true;+ resolveServed();+ return { status: 200, body: "ok" };+ },+ // Record each wrapper span name, then run the wrapped work.+ runtimeSpan: async (name, work) => {+ wrapped.push(name);+ return work();+ },+ });++ await requestServed;+ await worker.stop();++ expect(wrapped).toContain("sandbox.callbackBridge.relayRequest");+ });+it("test_paperclip_loop_exec_stays_unparented_without_getter", async () => {// With no `getRuntimeParentContext`, a request runs with an empty active// step store, exactly like the earlier `runWithoutActiveStep` behavior. So adiff --git a/packages/adapter-utils/src/sandbox-callback-bridge.ts b/packages/adapter-utils/src/sandbox-callback-bridge.tsindex 48f64211d7..bd5a83ab5f 100644--- a/packages/adapter-utils/src/sandbox-callback-bridge.ts+++ b/packages/adapter-utils/src/sandbox-callback-bridge.ts@@ -6,6 +6,7 @@ import path from "node:path";import {runWithoutActiveStep,runWithRuntimeParent,+ type RuntimeSpanRunner,type StartupSpanContext,} from "./acpx-engine/startup-timing.js";import type { CommandManagedRuntimeRunner } from "./command-managed-runtime.js";@@ -23,6 +24,10 @@ const SANDBOX_CALLBACK_BRIDGE_ENTRYPOINT = "paperclip-bridge-server.mjs";const SANDBOX_EXEC_CHANNEL_ENV = "PAPERCLIP_SANDBOX_EXEC_CHANNEL";const SANDBOX_EXEC_CHANNEL_BRIDGE = "bridge";+/** Span name that wraps one Paperclip-API callback request — read the request,+ * write the response, and remove the request file. */+const CALLBACK_BRIDGE_RELAY_REQUEST_SPAN = "sandbox.callbackBridge.relayRequest";+export const DEFAULT_SANDBOX_CALLBACK_BRIDGE_MAX_BODY_BYTES = DEFAULT_BRIDGE_MAX_BODY_BYTES;export interface SandboxCallbackBridgeRouteRule {@@ -630,6 +635,12 @@ export async function startSandboxCallbackBridgeWorker(input: {// otherwise). When it is absent, the request work runs with an empty store,// exactly like the earlier `runWithoutActiveStep` behavior.getRuntimeParentContext?: () => StartupSpanContext | undefined;+ // Wrap each Paperclip-API callback request in a+ // `sandbox.callbackBridge.relayRequest` span, so the request's read, write, and+ // remove execs group under one named span. When it is absent, the request work+ // runs under the run parent with no wrapper span, exactly like the earlier+ // behavior.+ runtimeSpan?: RuntimeSpanRunner;}): Promise<SandboxCallbackBridgeWorkerHandle> {const pollIntervalMs = normalizeTimeoutMs(input.pollIntervalMs, DEFAULT_BRIDGE_POLL_INTERVAL_MS);const maxBodyBytes = normalizeTimeoutMs(input.maxBodyBytes, DEFAULT_BRIDGE_MAX_BODY_BYTES);@@ -777,15 +788,20 @@ export async function startSandboxCallbackBridgeWorker(input: {if (stopping && Date.now() >= stopDeadline) break;inFlight += 1;try {- // A request is run-time work, not startup work. Read the run parent- // context now and run the request under it, so the request- // `sandbox.exec` span parents to the live run span. Read the getter- // per request: the live parent switches to `agent.turn` during the- // turn and back to `task.run` after it. With no getter the store- // stays empty, exactly like the earlier unparented behavior.- await runWithRuntimeParent(input.getRuntimeParentContext?.(), () =>- processRequestFile(fileName),- );+ // A request is run-time work, not startup work. Wrap it in a+ // `sandbox.callbackBridge.relayRequest` span, so its read, write, and+ // remove execs group under one named span that parents to the live+ // run span. The span runner reads the run parent per request: the+ // live parent switches to `agent.turn` during the turn and back to+ // `task.run` after it. Without a runner, the request runs under the+ // run parent with no wrapper span, exactly like the earlier behavior.+ await (input.runtimeSpan+ ? input.runtimeSpan(CALLBACK_BRIDGE_RELAY_REQUEST_SPAN, () =>+ processRequestFile(fileName),+ )+ : runWithRuntimeParent(input.getRuntimeParentContext?.(), () =>+ processRequestFile(fileName),+ ));} finally {inFlight -= 1;}diff --git a/packages/plugins/sandbox-providers/daytona/src/file-sync.ts b/packages/plugins/sandbox-providers/daytona/src/file-sync.tsindex be9e51547d..2e3a192caa 100644--- a/packages/plugins/sandbox-providers/daytona/src/file-sync.ts+++ b/packages/plugins/sandbox-providers/daytona/src/file-sync.ts@@ -460,8 +460,9 @@ async function syncInFileMappings(input: {// Ensure every target directory exists before the bulk upload writes its temp.const mkdirCommand = [...parentDirs].map((dir) => `mkdir -p ${shellQuote(dir)}`).join(" && ");+ // `ensureDirectory` span: `mkdir -p` — ensure a directory exists before a write.await withProviderSpan({- name: "mkdir",+ name: "ensureDirectory",run: () => assertSandboxCommandOk(sandbox, mkdirCommand, timeoutSeconds, "syncIn mkdir"),});guardRoundTrips += 1;@@ -470,8 +471,10 @@ async function syncInFileMappings(input: {// can replace a target parent with a symlink to `/etc` so the string check// passes but the upload + `mv -f` resolve through it. Canonicalize every parent// dir (now materialized) and fail closed if any escapes, BEFORE any bytes land.+ // `checkSymlinkEscape` span: re-check a path resolves inside the workspace root+ // before use.await withProviderSpan({- name: "guard",+ name: "checkSymlinkEscape",run: () =>assertSandboxPathsConfined({sandbox,@@ -488,6 +491,7 @@ async function syncInFileMappings(input: {// retry never accumulates stale `.paperclip-upload-*` scratch.try {// One batched bulk upload (single /files/bulk-upload) for all file mappings.+ // `transfer` span: the real byte upload — `sandbox.fs.uploadFiles`.await withProviderSpan({name: "transfer",wallMsAttr: SPAN_ATTR.transferWallMs,@@ -534,8 +538,10 @@ async function syncInFileMappings(input: {`exec 8>&-;`,);}+ // `promote` span: atomically move the staged temp onto its target via a+ // pinned dir handle.await withProviderSpan({- name: "rename",+ name: "promote",run: () =>assertSandboxCommandOk(sandbox,@@ -564,6 +570,7 @@ async function syncInDirectoryMapping(input: {const archivePath = path.join(tmp, "sync-in.tar");// The pack step is host-local: it builds the tarball and makes no sandbox// round trip. The `pack` span records its wall time.+ // `pack` span: build a tarball on the host — no sandbox round trip.await withProviderSpan({name: "pack",wallMsAttr: SPAN_ATTR.packWallMs,@@ -585,8 +592,9 @@ async function syncInDirectoryMapping(input: {// components, then confirm it (and any existing parent) canonicalizes inside// the remote dir — `tar -C` would otherwise follow a sandbox-planted symlink// and extract our archive outside the workspace root.+ // `ensureDirectory` span: `mkdir -p` — ensure a directory exists before a write.await withProviderSpan({- name: "mkdir",+ name: "ensureDirectory",run: () =>assertSandboxCommandOk(sandbox,@@ -596,8 +604,10 @@ async function syncInDirectoryMapping(input: {),});guardRoundTrips += 1;+ // `checkSymlinkEscape` span: re-check a path resolves inside the workspace+ // root before use.await withProviderSpan({- name: "guard",+ name: "checkSymlinkEscape",run: () =>assertSandboxPathsConfined({sandbox,@@ -608,6 +618,7 @@ async function syncInDirectoryMapping(input: {}),});guardRoundTrips += 1;+ // `transfer` span: the real byte upload — `sandbox.fs.uploadFiles`.await withProviderSpan({name: "transfer",wallMsAttr: SPAN_ATTR.transferWallMs,@@ -641,8 +652,10 @@ async function syncInDirectoryMapping(input: {`exec 9>&-;`,`rm -f ${shellQuote(remoteTar)};`,].join("\n");+ // `extractTarball` span: one round trip — re-check the path, `tar -xf`, and+ // remove the scratch tarball.await withProviderSpan({- name: "extract",+ name: "extractTarball",run: () =>assertSandboxCommandOk(sandbox,@@ -687,8 +700,10 @@ async function runPostUploadCommands(input: {let cwd = remoteDir;if (command.cwd != null) {assertConfinedSandboxPath(remoteDir, command.cwd, "post-upload command cwd");+ // `checkSymlinkEscape` span: re-check a path resolves inside the workspace+ // root before use.await withProviderSpan({- name: "guard",+ name: "checkSymlinkEscape",run: () =>assertSandboxPathsConfined({sandbox,@@ -704,8 +719,9 @@ async function runPostUploadCommands(input: {// C4: first non-zero exit or timeout throws and aborts the remaining commands.const commandTimeoutSeconds =command.timeoutMs != null ? toTimeoutSeconds(command.timeoutMs) : timeoutSeconds;+ // `postUploadCommand` span: run one caller-supplied post-upload command.const result = await withProviderSpan({- name: "provision",+ name: "postUploadCommand",run: () =>sandbox.process.executeCommand(command.command, cwd, undefined, commandTimeoutSeconds),});diff --git a/packages/plugins/sandbox-providers/daytona/src/plugin.test.ts b/packages/plugins/sandbox-providers/daytona/src/plugin.test.tsindex 7e3d04d9c9..e37d2b348f 100644--- a/packages/plugins/sandbox-providers/daytona/src/plugin.test.ts+++ b/packages/plugins/sandbox-providers/daytona/src/plugin.test.ts@@ -1202,7 +1202,7 @@ describe("Daytona sandbox provider plugin", () => {// The provision command runs before the run opens its trace root, so the// host marks it `bypassSession`. The provider must not open the session for- // it, or the `session.setup` span loses its run parent.+ // it, or the `session.open` span loses its run parent.await plugin.definition.onEnvironmentExecute?.(sessionExecParams({ bypassSession: true }),);@@ -1406,7 +1406,7 @@ describe("Daytona sandbox provider plugin", () => {expect(sandbox.process.deleteSession).toHaveBeenCalledWith(sessionId);});- it("emits a session.setup span on create and a session.teardown span on delete", async () => {+ it("emits a session.open span on create and a session.close span on delete", async () => {process.env.DAYTONA_API_KEY = "host-key";const sandbox = createMockSandbox();mockGet.mockResolvedValue(sandbox);@@ -1414,7 +1414,7 @@ describe("Daytona sandbox provider plugin", () => {const restore = __setDaytonaPluginContextForTest({ tracer } as unknown as PluginContext);try {await plugin.definition.onEnvironmentExecute?.(sessionExecParams());- const setup = spans.find((span) => span.name === "session.setup");+ const setup = spans.find((span) => span.name === "session.open");expect(setup).toBeDefined();expect(setup!.ended).toBe(true);expect(setup!.attributes["paperclip.sandbox.startup.provider"]).toBe("daytona");@@ -1426,7 +1426,7 @@ describe("Daytona sandbox provider plugin", () => {providerLeaseId: "sandbox-123",config: { timeoutMs: 300000, reuseLease: false, useSessions: true },});- const teardown = spans.find((span) => span.name === "session.teardown");+ const teardown = spans.find((span) => span.name === "session.close");expect(teardown).toBeDefined();expect(teardown!.ended).toBe(true);expect(teardown!.attributes["paperclip.sandbox.startup.provider"]).toBe("daytona");@@ -1435,7 +1435,7 @@ describe("Daytona sandbox provider plugin", () => {}});- it("marks the session.setup span failed when the session create throws", async () => {+ it("marks the session.open span failed when the session create throws", async () => {process.env.DAYTONA_API_KEY = "host-key";const sandbox = createMockSandbox();sandbox.process.createSession.mockRejectedValueOnce(new Error("create boom"));@@ -1446,7 +1446,7 @@ describe("Daytona sandbox provider plugin", () => {await expect(plugin.definition.onEnvironmentExecute?.(sessionExecParams()),).rejects.toThrow(/create boom/);- const setup = spans.find((span) => span.name === "session.setup");+ const setup = spans.find((span) => span.name === "session.open");expect(setup).toBeDefined();expect(setup!.ended).toBe(true);expect(setup!.status?.code).toBe(2);@@ -3028,7 +3028,7 @@ describe("daytona native file-sync hooks", () => {expect(transfer!.attributes["paperclip.sandbox.startup.transfer.guard.count"]).toBe(2);});- it("opens mkdir, guard, transfer, rename spans in call order for a file-mapping sync", async () => {+ it("opens ensureDirectory, checkSymlinkEscape, transfer, promote spans in call order for a file-mapping sync", async () => {const hostDir = await makeHostDir();const source = path.join(hostDir, "config.txt");await fs.writeFile(source, "plain");@@ -3055,21 +3055,26 @@ describe("daytona native file-sync hooks", () => {restore();}- expect(spans.map((span) => span.name)).toEqual(["mkdir", "guard", "transfer", "rename"]);+ expect(spans.map((span) => span.name)).toEqual([+ "ensureDirectory",+ "checkSymlinkEscape",+ "transfer",+ "promote",+ ]);for (const span of spans) {expect(span.ended).toBe(true);expect(span.attributes["paperclip.sandbox.startup.provider"]).toBe("daytona");// A per-round-trip span carries no `*.wall_ms` attribute; the native span// width carries its time. Only `pack` and `transfer` keep a wall_ms value.if (span.name !== "transfer") {- expect(span.attributes["paperclip.sandbox.startup.mkdir.wall_ms"]).toBeUndefined();- expect(span.attributes["paperclip.sandbox.startup.rename.wall_ms"]).toBeUndefined();- expect(span.attributes["paperclip.sandbox.startup.guard.wall_ms"]).toBeUndefined();+ expect(span.attributes["paperclip.sandbox.startup.ensureDirectory.wall_ms"]).toBeUndefined();+ expect(span.attributes["paperclip.sandbox.startup.promote.wall_ms"]).toBeUndefined();+ expect(span.attributes["paperclip.sandbox.startup.checkSymlinkEscape.wall_ms"]).toBeUndefined();}}});- it("opens pack, mkdir, guard, transfer, extract spans in call order for a directory-mapping sync", async () => {+ it("opens pack, ensureDirectory, checkSymlinkEscape, transfer, extractTarball spans in call order for a directory-mapping sync", async () => {const hostDir = await makeHostDir();const sourceDir = path.join(hostDir, "assets");await fs.mkdir(sourceDir, { recursive: true });@@ -3099,7 +3104,13 @@ describe("daytona native file-sync hooks", () => {restore();}- expect(spans.map((span) => span.name)).toEqual(["pack", "mkdir", "guard", "transfer", "extract"]);+ expect(spans.map((span) => span.name)).toEqual([+ "pack",+ "ensureDirectory",+ "checkSymlinkEscape",+ "transfer",+ "extractTarball",+ ]);for (const span of spans) {expect(span.attributes["paperclip.sandbox.startup.provider"]).toBe("daytona");}@@ -3141,7 +3152,7 @@ describe("daytona native file-sync hooks", () => {expect(pack!.attributes["paperclip.sandbox.startup.provider"]).toBe("daytona");});- it("opens a guard span and a provision span in call order for a post-upload command with a working directory", async () => {+ it("opens a checkSymlinkEscape span and a postUploadCommand span in call order for a post-upload command with a working directory", async () => {const hostDir = await makeHostDir();const source = path.join(hostDir, "config.txt");await fs.writeFile(source, "plain");@@ -3169,17 +3180,18 @@ describe("daytona native file-sync hooks", () => {restore();}- // The full order: the file mapping opens mkdir, guard, transfer, rename; the- // post-upload command then opens its own cwd guard and the provision span.+ // The full order: the file mapping opens ensureDirectory, checkSymlinkEscape,+ // transfer, promote; the post-upload command then opens its own cwd+ // checkSymlinkEscape and the postUploadCommand span.expect(spans.map((span) => span.name)).toEqual([- "mkdir",- "guard",+ "ensureDirectory",+ "checkSymlinkEscape","transfer",- "rename",- "guard",- "provision",+ "promote",+ "checkSymlinkEscape",+ "postUploadCommand",]);- const provision = spans.find((span) => span.name === "provision");+ const provision = spans.find((span) => span.name === "postUploadCommand");expect(provision!.ended).toBe(true);expect(provision!.attributes["paperclip.sandbox.startup.provider"]).toBe("daytona");});diff --git a/packages/plugins/sandbox-providers/daytona/src/plugin.ts b/packages/plugins/sandbox-providers/daytona/src/plugin.tsindex e00c0a2ca0..18306045b3 100644--- a/packages/plugins/sandbox-providers/daytona/src/plugin.ts+++ b/packages/plugins/sandbox-providers/daytona/src/plugin.ts@@ -1336,11 +1336,13 @@ async function getOrCreateSession(sandbox: Sandbox, scope: SandboxScope): Promis// no second command can slip in between the store read and the create start.return sandboxHandleSessionStore.runSingle(scope, async () => {const sessionId = `paperclip-${randomUUID()}`;- // Wrap the session create in a short `session.setup` provider span. The span+ // Wrap the session create in a short `session.open` provider span. The span// carries no session id and no command text, only the provider family. The- // host maps the name to `sandbox.provider.session.setup`.+ // host maps the name to `sandbox.daytona.session.open`.+ // `session.open` span: create the one persistent Daytona session for a lease,+ // on the first in-run command — `sandbox.process.createSession`.await withProviderSpan({- name: "session.setup",+ name: "session.open",run: () => sandbox.process.createSession(sessionId),});sandboxHandleSessionStore.set(scope, sessionId);@@ -1360,10 +1362,12 @@ async function teardownSession(sandbox: Sandbox, scope: SandboxScope): Promise<vconst sessionId = sandboxHandleSessionStore.get(scope);if (!sessionId) return;try {- // Wrap the session delete in a short `session.teardown` provider span. The- // host maps the name to `sandbox.provider.session.teardown`.+ // Wrap the session delete in a short `session.close` provider span. The+ // host maps the name to `sandbox.daytona.session.close`.+ // `session.close` span: delete that persistent session on lease release —+ // `sandbox.process.deleteSession`.await withProviderSpan({- name: "session.teardown",+ name: "session.close",run: () => sandbox.process.deleteSession(sessionId),});} catch (error) {@@ -2255,9 +2259,9 @@ const plugin = definePlugin({// on, and it does NOT open the session. The host sets this flag on a// pre-run command (the workspace provision command) that runs before the// run opens its trace root. Opening the session there would emit a- // `session.setup` span with no run parent, and the span backend would drop+ // `session.open` span with no run parent, and the span backend would drop// it. With the bypass the session opens on the first in-run command, whose- // setup span parents to the run trace.+ // open span parents to the run trace.let result: PluginEnvironmentExecuteResult;if (config.useSessions && !params.bypassSession) {const sessionId = await getOrCreateSession(sandbox, scope);diff --git a/packages/shared/src/telemetry/README.md b/packages/shared/src/telemetry/README.mdindex b86c7ea09d..79ae3e2581 100644--- a/packages/shared/src/telemetry/README.md+++ b/packages/shared/src/telemetry/README.md@@ -93,10 +93,17 @@ absent, never a misleading `0`.| `bridge.paperclip` | Paperclip bridge start step. | `sandbox.startup` || `bridge.process-session` | Process-session bridge start step. | `sandbox.startup` || `acp.handshake` | ACP session handshake step. | `sandbox.startup` |-| `sandbox.exec` | One host-to-sandbox execution. | the active step span |+| `sandbox.agentSession.sendInput` | One outbound ACP message to the agent — the socket handler's one `writeTextFile` exec. | the active run span |+| `sandbox.agentSession.pollOutput` | One 100 ms poll tick — `list`, then `read`+`remove` per file found (`1 + 2n` execs). | the active run span |+| `sandbox.callbackBridge.relayRequest` | One Paperclip-API callback request — read the request, write the response, remove it. | the active run span |+| `sandbox.exec` | One host-to-sandbox execution. | the active step or wrapper span |A step span name is the step name. The `sandbox.exec` span parents to the step-span that runs the execution, so each execution nests under its step. With no+span that runs the execution, so each execution nests under its step. A run-time+`sandbox.exec` span parents instead to the run-time wrapper span that runs it+(`sandbox.agentSession.sendInput`, `sandbox.agentSession.pollOutput`, or+`sandbox.callbackBridge.relayRequest`). Each run-time wrapper span parents to the+live run span (`agent.turn` during the turn, `task.run` otherwise). With noactive trace context the exec span opens unparented.The root span sets the error status when the bring-up fails. Each step span sets@@ -172,7 +179,7 @@ the code first. Keep the attribute low-cardinality and free of user content.### Provider spansA sandbox provider plugin also opens spans for its own sync steps. These spans-use the `sandbox.provider.` name prefix. They share the+use the `sandbox.daytona.` name prefix. They share the`paperclip.sandbox.startup.` attribute prefix and obey the same opt-in andno-user-content rules as the startup spans above.@@ -183,15 +190,26 @@ before it records the span.| Span | Scope | Parent || --- | --- | --- |-| `sandbox.provider.pack` | The host-local pack step that builds the upload tarball. It makes no sandbox round trip. | the active startup step span |-| `sandbox.provider.transfer` | The transfer step that uploads the files to the sandbox. | the active startup step span |-| `sandbox.provider.other` | Any span name outside the known set. | the active startup step span |--The host clamps the span name to the closed set `pack` and `transfer`. The host-maps a known name to `sandbox.provider.<name>`. The host maps any other value to-`sandbox.provider.other`, so a span name never carries free-form data.--The `sandbox.provider.*` spans use this closed attribute allowlist. The host+| `sandbox.daytona.pack` | The host-local pack step that builds the upload tarball. It makes no sandbox round trip. | the active startup step span |+| `sandbox.daytona.transfer` | The transfer step that uploads the files to the sandbox. | the active startup step span |+| `sandbox.daytona.ensureDirectory` | The `mkdir -p` step that ensures a directory exists before a write. | the active startup step span |+| `sandbox.daytona.checkSymlinkEscape` | The re-check step that a path resolves inside the workspace root before use. | the active startup step span |+| `sandbox.daytona.promote` | The atomic move of a staged temp onto its target via a pinned dir handle. | the active startup step span |+| `sandbox.daytona.extractTarball` | The one round trip that re-checks the path, runs `tar -xf`, and removes the scratch tarball. | the active startup step span |+| `sandbox.daytona.postUploadCommand` | One caller-supplied post-upload command. | the active startup step span |+| `sandbox.daytona.session.open` | The create of the one persistent session for a lease, on the first in-run command. | the active run span |+| `sandbox.daytona.session.close` | The delete of that persistent session on lease release. | the active run span |+| `sandbox.daytona.other` | Any span name outside the known set. | the active startup step span |++The host clamps the span name to the closed set of leaf names above (`pack`,+`transfer`, `ensureDirectory`, `checkSymlinkEscape`, `promote`, `extractTarball`,+`postUploadCommand`, `session.open`, and `session.close`). The host maps a known+name to `sandbox.daytona.<name>`. The host maps any other value to+`sandbox.daytona.other`, so a span name never carries free-form data. Only the+daytona provider emits these spans today, so the segment is the literal+`daytona`.++The `sandbox.daytona.*` spans use this closed attribute allowlist. The hostdrops every other key, so a command, an argument, a path, an id, a standardoutput, or a standard error never rides a provider span. The host records onlythe attributes that the producer sends for one span.@@ -200,9 +218,9 @@ the attributes that the producer sends for one span.| --- | --- | --- | --- || `paperclip.sandbox.startup.provider` | string | no | The normalized provider family. || `paperclip.sandbox.startup.outcome` | string | yes | The step outcome (`ok`, `skipped`, or `failed`). |-| `paperclip.sandbox.startup.pack.wall_ms` | number | yes | The host-local wall time of the pack step. It rides the `sandbox.provider.pack` span. |-| `paperclip.sandbox.startup.transfer.wall_ms` | number | yes | The wall time of the transfer step. It rides the `sandbox.provider.transfer` span. |-| `paperclip.sandbox.startup.transfer.guard.count` | number | yes | The number of serial guard round trips before one transfer. It rides the `sandbox.provider.transfer` span. |+| `paperclip.sandbox.startup.pack.wall_ms` | number | yes | The host-local wall time of the pack step. It rides the `sandbox.daytona.pack` span. |+| `paperclip.sandbox.startup.transfer.wall_ms` | number | yes | The wall time of the transfer step. It rides the `sandbox.daytona.transfer` span. |+| `paperclip.sandbox.startup.transfer.guard.count` | number | yes | The number of serial guard round trips before one transfer. It rides the `sandbox.daytona.transfer` span. |The `span.record` host handler enforces the allowlist. It re-maps `provider`through the provider-family normalizer. It keeps `outcome` only when the valuediff --git a/server/src/__tests__/environment-runtime.test.ts b/server/src/__tests__/environment-runtime.test.tsindex 5c13b76f52..7397b99732 100644--- a/server/src/__tests__/environment-runtime.test.ts+++ b/server/src/__tests__/environment-runtime.test.ts@@ -709,7 +709,7 @@ describeEmbeddedPostgres("environmentRuntimeService", () => {// Build the fake plugin fixture for the run-parent release tests below. A// plugin sandbox provider can open a persistent session on the first command// and delete it on lease release; the delete emits a provider- // `session.teardown` span. The host mints that span's parent from the active+ // `session.close` span. The host mints that span's parent from the active// step context at the release RPC. So the release must run under the run// parent, or the span loses its traceparent and the backend drops it.async function seedFakePluginSandbox() {diff --git a/server/src/__tests__/instrumentation.test.ts b/server/src/__tests__/instrumentation.test.tsindex b0b94e07a3..e2a3937ceb 100644--- a/server/src/__tests__/instrumentation.test.ts+++ b/server/src/__tests__/instrumentation.test.ts@@ -178,7 +178,7 @@ describe.skipIf(!otelSdk)("recordProviderPluginSpan native duration", () => {const startTimeMs = Date.now() - 4500;const endTimeMs = startTimeMs + 4500;recordProviderPluginSpan({- name: "sandbox.provider.mkdir",+ name: "sandbox.daytona.ensureDirectory",parent: {traceId: "0af7651916cd43dd8448eb211c80319c",spanId: "b7ad6b7169203331",@@ -191,7 +191,7 @@ describe.skipIf(!otelSdk)("recordProviderPluginSpan native duration", () => {const finished = exporter.getFinishedSpans();expect(finished).toHaveLength(1);const span = finished[0]!;- expect(span.name).toBe("sandbox.provider.mkdir");+ expect(span.name).toBe("sandbox.daytona.ensureDirectory");expect(Math.round(hrTimeToMs(span.startTime as [number, number]))).toBe(startTimeMs);expect(Math.round(hrTimeToMs(span.endTime as [number, number]))).toBe(endTimeMs);// The native width equals the true wall-clock difference, not near zero.@@ -211,7 +211,7 @@ describe.skipIf(!otelSdk)("recordProviderPluginSpan native duration", () => {try {const { recordProviderPluginSpan } = await import("../instrumentation.js");recordProviderPluginSpan({- name: "sandbox.provider.pack",+ name: "sandbox.daytona.pack",parent: {traceId: "0af7651916cd43dd8448eb211c80319c",spanId: "b7ad6b7169203331",diff --git a/server/src/__tests__/plugin-host-services-span.test.ts b/server/src/__tests__/plugin-host-services-span.test.tsindex 110d06a0b6..bb2a72bb56 100644--- a/server/src/__tests__/plugin-host-services-span.test.ts+++ b/server/src/__tests__/plugin-host-services-span.test.ts@@ -63,7 +63,7 @@ describe("plugin provider span host handler", () => {parent: { traceId: string; spanId: string; traceFlags: number };attributes: Record<string, unknown>;};- expect(call.name).toBe("sandbox.provider.pack");+ expect(call.name).toBe("sandbox.daytona.pack");expect(call.parent).toEqual({traceId: "0af7651916cd43dd8448eb211c80319c",spanId: "b7ad6b7169203331",@@ -114,20 +114,26 @@ describe("plugin provider span host handler", () => {expect(call.status).not.toHaveProperty("message");});- it("clamps an unknown span name to sandbox.provider.other", async () => {+ it("clamps an unknown span name to sandbox.daytona.other", async () => {const services = servicesFor();await services.tracer.record({ name: "rm -rf / --no-preserve-root" },{ traceparent: VALID_TRACEPARENT } as WorkerHostCallContext,);expect((mockRecordSpan.mock.calls[0]![0] as { name: string }).name).toBe(- "sandbox.provider.other",+ "sandbox.daytona.other",);});- it("admits each per-round-trip span name to sandbox.provider.<name>", async () => {+ it("admits each per-round-trip span name to sandbox.daytona.<name>", async () => {const services = servicesFor();- for (const name of ["mkdir", "guard", "rename", "extract", "provision"]) {+ for (const name of [+ "ensureDirectory",+ "checkSymlinkEscape",+ "promote",+ "extractTarball",+ "postUploadCommand",+ ]) {await services.tracer.record({ name },{ traceparent: VALID_TRACEPARENT } as WorkerHostCallContext,@@ -135,17 +141,17 @@ describe("plugin provider span host handler", () => {}const recorded = mockRecordSpan.mock.calls.map((c) => (c[0] as { name: string }).name);expect(recorded).toEqual([- "sandbox.provider.mkdir",- "sandbox.provider.guard",- "sandbox.provider.rename",- "sandbox.provider.extract",- "sandbox.provider.provision",+ "sandbox.daytona.ensureDirectory",+ "sandbox.daytona.checkSymlinkEscape",+ "sandbox.daytona.promote",+ "sandbox.daytona.extractTarball",+ "sandbox.daytona.postUploadCommand",]);});- it("admits the session setup and teardown span names", async () => {+ it("admits the session open and close span names", async () => {const services = servicesFor();- for (const name of ["session.setup", "session.teardown"]) {+ for (const name of ["session.open", "session.close"]) {await services.tracer.record({ name },{ traceparent: VALID_TRACEPARENT } as WorkerHostCallContext,@@ -153,8 +159,8 @@ describe("plugin provider span host handler", () => {}const recorded = mockRecordSpan.mock.calls.map((c) => (c[0] as { name: string }).name);expect(recorded).toEqual([- "sandbox.provider.session.setup",- "sandbox.provider.session.teardown",+ "sandbox.daytona.session.open",+ "sandbox.daytona.session.close",]);});@@ -163,7 +169,7 @@ describe("plugin provider span host handler", () => {const startTimeMs = Date.now() - 4500;const endTimeMs = startTimeMs + 4500;await services.tracer.record(- { name: "mkdir", startTimeMs, endTimeMs },+ { name: "ensureDirectory", startTimeMs, endTimeMs },{ traceparent: VALID_TRACEPARENT } as WorkerHostCallContext,);const call = mockRecordSpan.mock.calls[0]![0] as {@@ -181,7 +187,7 @@ describe("plugin provider span host handler", () => {const startTimeMs = Date.now() + 5000;const endTimeMs = startTimeMs + 1000;await services.tracer.record(- { name: "mkdir", startTimeMs, endTimeMs },+ { name: "ensureDirectory", startTimeMs, endTimeMs },{ traceparent: VALID_TRACEPARENT } as WorkerHostCallContext,);const call = mockRecordSpan.mock.calls[0]![0] as {@@ -207,7 +213,7 @@ describe("plugin provider span host handler", () => {for (const pair of invalidPairs) {mockRecordSpan.mockReset();await services.tracer.record(- { name: "mkdir", startTimeMs: pair.startTimeMs, endTimeMs: pair.endTimeMs } as never,+ { name: "ensureDirectory", startTimeMs: pair.startTimeMs, endTimeMs: pair.endTimeMs } as never,{ traceparent: VALID_TRACEPARENT } as WorkerHostCallContext,);// The span still records (the synchronous path), but without a timestamp.diff --git a/server/src/services/plugin-host-services.ts b/server/src/services/plugin-host-services.tsindex 1eb3b8a01a..1428f42fd4 100644--- a/server/src/services/plugin-host-services.ts+++ b/server/src/services/plugin-host-services.ts@@ -507,29 +507,33 @@ const SESSION_EVENT_SUBSCRIPTION_TIMEOUT_MS = 30 * 60 * 1_000; // 30 minutesconst SPAN_ATTRS = SANDBOX_STARTUP_SPAN_ATTRS;-/** The closed set of provider span names a plugin may emit. `pack` and- * `transfer` are the host-local build and the byte upload. `mkdir`, `guard`,- * `rename`, `extract`, and `provision` are the per-round-trip command spans in- * the inbound sync path. `session.setup` and `session.teardown` are the short- * spans that wrap a persistent-session create and delete. */+/** The closed set of provider span leaf names a plugin may emit. `pack` and+ * `transfer` are the host-local build and the byte upload. `ensureDirectory`,+ * `checkSymlinkEscape`, `promote`, `extractTarball`, and `postUploadCommand`+ * are the per-round-trip command spans in the inbound sync path. `session.open`+ * and `session.close` are the short spans that wrap a persistent-session create+ * and delete. */const KNOWN_PROVIDER_SPAN_NAMES: ReadonlySet<string> = new Set(["pack","transfer",- "mkdir",- "guard",- "rename",- "extract",- "provision",- "session.setup",- "session.teardown",+ "ensureDirectory",+ "checkSymlinkEscape",+ "promote",+ "extractTarball",+ "postUploadCommand",+ "session.open",+ "session.close",]);/** Clamp the span name to a closed, namespaced set. A known name maps to- * `sandbox.provider.<name>`; any other value maps to `sandbox.provider.other`,- * so a span name never carries free-form data. */+ * `sandbox.daytona.<name>`; any other value maps to `sandbox.daytona.other`, so+ * a span name never carries free-form data. Only the daytona provider emits+ * these spans today, so the segment is the literal `daytona`. When a second+ * provider emits provider spans, derive the segment from the normalized+ * `provider` family attribute on the span instead of this literal. */function clampProviderSpanName(raw: unknown): string {const name = typeof raw === "string" && KNOWN_PROVIDER_SPAN_NAMES.has(raw) ? raw : "other";- return `sandbox.provider.${name}`;+ return `sandbox.daytona.${name}`;}/** The closed allowlist of attribute keys a provider span may carry. The host