@anvia/studio 0.7.32 → 0.7.34

package/dist/index.js

@@ -634,6 +634,11 @@ function registerStudioUi(app, options) {
   app.get(`${options.path}/tools`, (c) => redirectWithQuery(c, "/tools"));
   app.get(`${options.path}/mcps`, (c) => redirectWithQuery(c, "/mcps"));
   app.get(`${options.path}/pipelines`, (c) => redirectWithQuery(c, "/pipelines"));
+  app.get(`${options.path}/sandboxes`, (c) => redirectWithQuery(c, "/sandboxes"));
+  app.get(
+    `${options.path}/sandboxes/:sandboxRef`,
+    (c) => redirectWithQuery(c, `/sandboxes/${encodeURIComponent(c.req.param("sandboxRef"))}`)
+  );
   app.get(`${options.path}/evals`, (c) => redirectWithQuery(c, "/evals"));
   app.get(`${options.path}/memory`, (c) => redirectWithQuery(c, "/memory"));
   app.get(`${options.path}/status`, (c) => redirectWithQuery(c, "/status"));
@@ -654,6 +659,8 @@ function registerStudioUi(app, options) {
     app.get("/tools", async (c) => c.html(await renderShell()));
     app.get("/mcps", async (c) => c.html(await renderShell()));
     app.get("/pipelines", shellWhenHtml(renderShell));
+    app.get("/sandboxes", shellWhenHtml(renderShell));
+    app.get("/sandboxes/:sandboxRef", shellWhenHtml(renderShell));
     app.get("/evals", shellWhenHtml(renderShell));
     app.get("/memory", async (c) => c.html(await renderShell()));
     app.get("/status", shellWhenHtml(renderShell));
@@ -764,8 +771,8 @@ function renderLegacyStudioUiShell(props) {
     "</html>"
   ].join("");
 }
-function normalizeUiPath(path) {
-  const trimmed = path.trim();
+function normalizeUiPath(path2) {
+  const trimmed = path2.trim();
   const withSlash = trimmed.startsWith("/") ? trimmed : `/${trimmed}`;
   const withoutTrailingSlash = withSlash.length > 1 ? withSlash.replace(/\/+$/, "") : withSlash;
   if (withoutTrailingSlash.length === 0 || withoutTrailingSlash === "/") {
@@ -1808,8 +1815,69 @@ async function* mergeRunAndApprovalEvents(runEvents, approvalEvents) {
     approvalEvents.close();
   }
 }
-function streamAgentRunEvents(_c, events) {
-  return streamStudioJsonl(events);
+function streamAgentRunEvents(_c, events, options = {}) {
+  return streamStudioJsonl(withAgentRunCancellation(events, options.onCancel));
+}
+function withAgentRunCancellation(events, onCancel) {
+  const iterator = events[Symbol.asyncIterator]();
+  let done = false;
+  let terminal = false;
+  let cancellationHandled = false;
+  const handleCancellation = async () => {
+    if (cancellationHandled) {
+      return;
+    }
+    cancellationHandled = true;
+    await onCancel?.();
+  };
+  return {
+    [Symbol.asyncIterator]() {
+      return {
+        async next() {
+          if (done) {
+            return { done: true, value: void 0 };
+          }
+          try {
+            const next = await iterator.next();
+            if (next.done === true) {
+              done = true;
+              if (!terminal) {
+                await handleCancellation();
+              }
+              return next;
+            }
+            if (next.value.type === "final" || next.value.type === "error") {
+              terminal = true;
+            }
+            return next;
+          } catch (error) {
+            done = true;
+            terminal = true;
+            throw error;
+          }
+        },
+        async return() {
+          if (done) {
+            return { done: true, value: void 0 };
+          }
+          done = true;
+          let closeError;
+          const closePromise = iterator.return?.().catch((error) => {
+            closeError = error;
+            return { done: true, value: void 0 };
+          });
+          if (!terminal) {
+            await handleCancellation();
+          }
+          await closePromise;
+          if (closeError !== void 0) {
+            throw closeError;
+          }
+          return { done: true, value: void 0 };
+        }
+      };
+    }
+  };
 }
 function traceForRun(trace, agentId, session) {
   const options = {};
@@ -1822,53 +1890,144 @@ function traceForRun(trace, agentId, session) {
   else if (session !== void 0) options.sessionId = session.id;
   return options;
 }
-async function* persistStreamingSessionTranscript(props) {
+function createPersistedStreamingSessionTranscript(props) {
   const transcript = [messageToTranscriptEntry(props.message, 0)];
   const title = optionalTitle(props.message);
-  await props.store.saveSessionRunTranscript({
-    id: props.session.id,
-    runId: props.runId,
-    ...title,
-    transcript,
-    status: "running"
-  });
-  try {
-    for await (const event of props.stream) {
-      acceptTranscriptStreamEvent(transcript, event);
-      const saveInput = {
-        id: props.session.id,
-        runId: props.runId,
-        ...title,
-        transcript,
-        status: event.type === "final" ? "success" : event.type === "error" ? "error" : "running"
-      };
-      if (event.type === "error") saveInput.error = serializeError(event.error);
-      const nextSession = await props.store.saveSessionRunTranscript(saveInput);
+  let status = "running";
+  let saveTail = Promise.resolve();
+  const isCancelled = () => status === "cancelled";
+  const saveTranscript = (input) => {
+    const operation = saveTail.then(async () => {
+      const nextSession = await props.store.saveSessionRunTranscript(input);
       if (nextSession === void 0) {
         throw new Error("Session not found");
       }
-      const generatedMessages = event.type === "final" ? event.messages.slice(1) : [];
-      if (props.persistGeneratedMessages === true && generatedMessages.length > 0) {
-        await props.store.append({
-          context: { sessionId: props.session.id },
-          runId: props.runId,
-          turn: 1,
-          messages: generatedMessages
-        });
-      }
-      yield event;
-    }
-  } catch (error) {
-    appendTranscriptAssistantError(transcript, errorText(error));
-    await props.store.saveSessionRunTranscript({
+    });
+    saveTail = operation.catch(() => void 0);
+    return operation;
+  };
+  const events = (async function* () {
+    await saveTranscript({
       id: props.session.id,
       runId: props.runId,
       ...title,
       transcript,
-      status: "error",
-      error: serializeError(error)
+      status: "running"
     });
-    throw error;
+    if (isCancelled()) {
+      return;
+    }
+    try {
+      for await (const event of props.stream) {
+        if (isCancelled()) {
+          return;
+        }
+        acceptTranscriptStreamEvent(transcript, event);
+        if (event.type === "final" || event.type === "error") {
+          assignTranscriptRunDuration(transcript, Date.now() - props.startedAt);
+        }
+        const eventStatus = event.type === "final" ? "success" : event.type === "error" ? "error" : "running";
+        const saveInput = {
+          id: props.session.id,
+          runId: props.runId,
+          ...title,
+          transcript,
+          status: eventStatus
+        };
+        if (event.type === "error") saveInput.error = serializeError(event.error);
+        await saveTranscript(saveInput);
+        const generatedMessages = event.type === "final" ? event.messages.slice(1) : [];
+        if (props.persistGeneratedMessages === true && generatedMessages.length > 0) {
+          await props.store.append({
+            context: { sessionId: props.session.id },
+            runId: props.runId,
+            turn: 1,
+            messages: generatedMessages
+          });
+        }
+        if (isCancelled()) {
+          return;
+        }
+        status = eventStatus;
+        yield event;
+      }
+    } catch (error) {
+      if (status !== "running") {
+        throw error;
+      }
+      status = "error";
+      appendTranscriptAssistantError(transcript, errorText(error));
+      assignTranscriptRunDuration(transcript, Date.now() - props.startedAt);
+      await saveTranscript({
+        id: props.session.id,
+        runId: props.runId,
+        ...title,
+        transcript,
+        status: "error",
+        error: serializeError(error)
+      });
+      throw error;
+    }
+  })();
+  return {
+    events,
+    async cancel() {
+      if (status !== "running") {
+        return;
+      }
+      status = "cancelled";
+      cancelPendingTranscriptInputs(transcript, (/* @__PURE__ */ new Date()).toISOString());
+      assignTranscriptRunDuration(transcript, Date.now() - props.startedAt);
+      await saveTranscript({
+        id: props.session.id,
+        runId: props.runId,
+        ...title,
+        transcript,
+        status: "cancelled"
+      });
+    }
+  };
+}
+function assignTranscriptRunDuration(transcript, durationMs2) {
+  const normalizedDurationMs = Math.max(0, durationMs2);
+  for (let index = transcript.length - 1; index >= 0; index -= 1) {
+    const entry = transcript[index];
+    if (entry?.kind === "message" && entry.role === "assistant") {
+      entry.durationMs = normalizedDurationMs;
+      return;
+    }
+    if (entry?.kind === "message" && entry.role === "user") {
+      break;
+    }
+  }
+  transcript.push({
+    entryId: transcript.length,
+    kind: "message",
+    role: "assistant",
+    text: "",
+    durationMs: normalizedDurationMs
+  });
+}
+function cancelPendingTranscriptInputs(transcript, cancelledAt) {
+  for (const entry of transcript) {
+    if (entry.kind !== "tool") {
+      continue;
+    }
+    if (entry.approval?.status === "pending") {
+      entry.approval = {
+        ...entry.approval,
+        status: "cancelled",
+        resolvedAt: cancelledAt,
+        reason: "Run cancelled in Anvia Studio."
+      };
+    }
+    if (entry.question?.status === "pending") {
+      entry.question = {
+        ...entry.question,
+        status: "cancelled",
+        cancelledAt
+      };
+    }
   }
 }
 function acceptTranscriptStreamEvent(transcript, event) {
@@ -1985,6 +2144,9 @@ function acceptTranscriptStreamEvent(transcript, event) {
         questions: event.question.questions
       };
       if (event.question.answeredAt !== void 0) question.answeredAt = event.question.answeredAt;
+      if (event.question.cancelledAt !== void 0) {
+        question.cancelledAt = event.question.cancelledAt;
+      }
       if (event.question.answers !== void 0) question.answers = event.question.answers;
       matched.question = question;
     }
@@ -2476,6 +2638,19 @@ function runCompletedLog(props) {
     metadata
   };
 }
+function runCancelledLog(sessionId, runId, startedAt) {
+  return {
+    sessionId,
+    runId,
+    level: "info",
+    category: "run",
+    event: "run.cancelled",
+    message: "Run cancelled",
+    metadata: {
+      durationMs: Date.now() - startedAt
+    }
+  };
+}
 function memorySavedLog(props) {
   const metadata = {};
   if (props.messageCount !== void 0) metadata.messageCount = props.messageCount;
@@ -2662,6 +2837,7 @@ function logsFromStreamEvent(props) {
     ];
   }
   if (event.type === "tool_question_result") {
+    const cancelled = event.question.status === "cancelled";
     const metadata = {
       questionId: event.question.id,
       toolName: event.question.toolName,
@@ -2677,8 +2853,8 @@ function logsFromStreamEvent(props) {
         runId,
         level: "info",
         category: "question",
-        event: "question.answered",
-        message: `Question answered for ${event.question.toolName}`,
+        event: cancelled ? "question.cancelled" : "question.answered",
+        message: cancelled ? `Question cancelled for ${event.question.toolName}` : `Question answered for ${event.question.toolName}`,
         metadata
       }
     ];
@@ -3055,21 +3231,45 @@ function handleStreamingAgentRun(c, run, props) {
     run.request.requestHook(effectiveHook);
   }
   const runStream = mergeRunAndApprovalEvents(run.request.stream(), runtimeEvents);
-  const stream = run.session === void 0 || run.sessionStore === void 0 ? runStream : persistStreamingSessionTranscript({
-    stream: streamSessionRunLogs({
-      stream: runStream,
+  let stream = runStream;
+  let persistedRun;
+  if (run.session !== void 0 && run.sessionStore !== void 0) {
+    persistedRun = createPersistedStreamingSessionTranscript({
+      stream: streamSessionRunLogs({
+        stream: runStream,
+        store: run.sessionStore,
+        session: run.session,
+        runId: run.runId,
+        startedAt: run.runStartedAt
+      }),
       store: run.sessionStore,
       session: run.session,
+      message: run.body.message,
       runId: run.runId,
-      startedAt: run.runStartedAt
-    }),
-    store: run.sessionStore,
-    session: run.session,
-    message: run.body.message,
-    runId: run.runId,
-    persistGeneratedMessages: run.shouldPersistSessionMessages
+      startedAt: run.runStartedAt,
+      persistGeneratedMessages: run.shouldPersistSessionMessages
+    });
+    stream = persistedRun.events;
+  }
+  return streamAgentRunEvents(c, stream, {
+    onCancel: async () => {
+      props.approvalRuntime.cancelRun(run.runId);
+      props.questionRuntime.cancelRun(run.runId);
+      const persistence = [];
+      if (persistedRun !== void 0) {
+        persistence.push(persistedRun.cancel());
+      }
+      if (run.session !== void 0 && run.sessionStore !== void 0) {
+        persistence.push(
+          appendSessionLog(
+            run.sessionStore,
+            runCancelledLog(run.session.id, run.runId, run.runStartedAt)
+          )
+        );
+      }
+      await Promise.all(persistence);
+    }
   });
-  return streamAgentRunEvents(c, stream);
 }
 async function handleBufferedAgentRun(c, run, props) {
   try {
@@ -3123,11 +3323,14 @@ async function completeBufferedSessionRun(run, response) {
       });
     }
   }
+  const durationMs2 = Date.now() - run.runStartedAt;
+  const transcript = transcriptFromMessages(response.messages);
+  assignTranscriptRunDuration(transcript, durationMs2);
   await run.sessionStore.saveSessionRunTranscript({
     id: run.session.id,
     runId: run.runId,
     ...optionalTitle(run.body.message),
-    transcript: transcriptFromMessages(response.messages),
+    transcript,
     status: "success"
   });
   await appendSessionLog(
@@ -3135,7 +3338,7 @@ async function completeBufferedSessionRun(run, response) {
     runCompletedLog({
       sessionId: run.session.id,
       runId: run.runId,
-      durationMs: Date.now() - run.runStartedAt,
+      durationMs: durationMs2,
       usage: response.usage,
       output: response.output,
       messageCount: response.messages.length
@@ -3158,11 +3361,14 @@ async function failBufferedSessionRun(run, error) {
     sessionId: run.session.id,
     metadata: run.memoryMetadata
   });
+  const durationMs2 = Date.now() - run.runStartedAt;
+  const transcript = transcriptFromMessages(messages.slice(run.session.messageCount));
+  assignTranscriptRunDuration(transcript, durationMs2);
   await run.sessionStore.saveSessionRunTranscript({
     id: run.session.id,
     runId: run.runId,
     ...optionalTitle(run.body.message),
-    transcript: transcriptFromMessages(messages.slice(run.session.messageCount)),
+    transcript,
     status: "error",
     error: serializeError(error)
   });
@@ -3322,6 +3528,22 @@ function createApprovalRuntime() {
         return true;
       }).map(publicApproval);
     },
+    cancelRun(runId) {
+      const cancelled = [];
+      for (const approval of approvals.values()) {
+        if (!isPendingApproval(approval) || approval.runId !== runId) {
+          continue;
+        }
+        const resolved = resolveApproval(approval, "cancelled", {
+          reason: "Run cancelled in Anvia Studio."
+        });
+        approvals.set(approval.id, resolved);
+        approval.emit?.({ type: "tool_approval_result", approval: resolved });
+        approval.resolve(approvalDecision(false, resolved.reason));
+        cancelled.push(resolved);
+      }
+      return cancelled;
+    },
     decide(id, decision) {
       const approval = approvals.get(id);
       if (approval === void 0) {
@@ -3581,7 +3803,7 @@ function pipelineConfig(pipeline) {
   if (pipeline.metadata !== void 0) config.metadata = pipeline.metadata;
   return config;
 }
-function buildConfig(options, agents, pipelines, stores) {
+function buildConfig(options, agents, pipelines, stores, sandboxCount = 0) {
   const models = options.models === void 0 ? void 0 : studioModelsConfig(createStudioModelRegistry(options.models), agents);
   const config = {
     id: runnerId(options),
@@ -3591,7 +3813,7 @@ function buildConfig(options, agents, pipelines, stores) {
     chat: {
       quickPrompts: Object.fromEntries(agents.map((agent) => [agent.id, agent.quickPrompts ?? []]))
     },
-    capabilities: capabilityConfig(options, agents, pipelines, stores),
+    capabilities: capabilityConfig(options, agents, pipelines, stores, sandboxCount),
     unsupportedCapabilities: unsupportedCapabilities(stores)
   };
   if (options.name !== void 0) config.name = options.name;
@@ -3600,7 +3822,7 @@ function buildConfig(options, agents, pipelines, stores) {
   if (models !== void 0) config.models = models;
   return config;
 }
-function capabilityConfig(_options, agents, pipelines, stores) {
+function capabilityConfig(_options, agents, pipelines, stores, sandboxCount = 0) {
   const capabilities = {
     agents: { enabled: true },
     observability: { enabled: true },
@@ -3627,6 +3849,9 @@ function capabilityConfig(_options, agents, pipelines, stores) {
   if (agents.some(agentHasMcpTools)) {
     capabilities.mcps = { enabled: true };
   }
+  if (sandboxCount > 0) {
+    capabilities.sandboxes = { enabled: true };
+  }
   if (agents.some(
     (agent) => agent.agent.hook !== void 0 || agent.agent.toolSet.values().some((tool) => tool.approval)
   )) {
@@ -4910,6 +5135,20 @@ function createQuestionRuntime() {
         return true;
       }).map(publicQuestion);
     },
+    cancelRun(runId) {
+      const cancelled = [];
+      for (const question of questions.values()) {
+        if (!isPendingQuestion(question) || question.runId !== runId) {
+          continue;
+        }
+        const resolved = cancelQuestion(question);
+        questions.set(question.id, resolved);
+        question.emit?.({ type: "tool_question_result", question: resolved });
+        question.resolve([]);
+        cancelled.push(resolved);
+      }
+      return cancelled;
+    },
     answer(id, answers) {
       const question = questions.get(id);
       if (question === void 0) {
@@ -5010,6 +5249,13 @@ function resolveQuestion(question, answers) {
     answers
   });
 }
+function cancelQuestion(question) {
+  return publicQuestion({
+    ...question,
+    status: "cancelled",
+    cancelledAt: (/* @__PURE__ */ new Date()).toISOString()
+  });
+}
 function publicQuestion(question) {
   const { emit, resolve: resolve2, ...rest } = question;
   void emit;
@@ -5017,6 +5263,446 @@ function publicQuestion(question) {
   return rest;
 }
 
+// src/runtime/sandboxes.ts
+import path from "path";
+var sandboxToolMetadataKey = /* @__PURE__ */ Symbol.for("anvia.sandbox.tool.metadata");
+var maxFileResponseBytes = 10 * 1024 * 1024;
+var defaultProcessLogBytes = 64 * 1024;
+var maxProcessLogBytes = 1024 * 1024;
+var StudioSandboxRegistry = class {
+  entries;
+  constructor(entries) {
+    this.entries = new Map(entries.map((entry) => [entry.summary.ref, entry]));
+  }
+  get size() {
+    return this.entries.size;
+  }
+  list() {
+    return [...this.entries.values()].map((entry) => copySummary(entry.summary));
+  }
+  get(ref) {
+    return this.entries.get(ref);
+  }
+};
+function createStudioSandboxRegistry(agents) {
+  const drafts = /* @__PURE__ */ new Map();
+  for (const agent of agents) {
+    for (const { tool } of agentToolItems(agent)) {
+      const session = sandboxSessionFromTool(tool);
+      if (session === void 0) {
+        continue;
+      }
+      const draft = drafts.get(session) ?? {
+        session,
+        agentIds: /* @__PURE__ */ new Set(),
+        toolNames: /* @__PURE__ */ new Set()
+      };
+      draft.agentIds.add(agent.id);
+      draft.toolNames.add(tool.name);
+      drafts.set(session, draft);
+    }
+  }
+  const refCounts = /* @__PURE__ */ new Map();
+  const entries = [...drafts.values()].sort(
+    (left, right) => `${left.session.provider}\0${left.session.id}`.localeCompare(
+      `${right.session.provider}\0${right.session.id}`
+    )
+  ).map((draft) => {
+    const baseRef = sandboxRef(draft.session.provider, draft.session.id);
+    const occurrence = (refCounts.get(baseRef) ?? 0) + 1;
+    refCounts.set(baseRef, occurrence);
+    const ref = occurrence === 1 ? baseRef : `${baseRef}.${occurrence}`;
+    return {
+      session: draft.session,
+      summary: {
+        ref,
+        id: draft.session.id,
+        provider: draft.session.provider,
+        workdir: draft.session.workdir,
+        agentIds: [...draft.agentIds].sort(),
+        toolNames: [...draft.toolNames].sort(),
+        capabilities: {
+          files: true,
+          ports: supportsPorts(draft.session),
+          processes: supportsProcesses(draft.session)
+        }
+      }
+    };
+  });
+  return new StudioSandboxRegistry(entries);
+}
+function registerSandboxRoutes(app, registry) {
+  app.use("/sandboxes", sandboxNoStore);
+  app.use("/sandboxes/*", sandboxNoStore);
+  app.get("/sandboxes", (c) => c.json({ sandboxes: registry.list() }));
+  app.get("/sandboxes/:sandboxRef", (c) => {
+    const entry = registry.get(c.req.param("sandboxRef"));
+    if (entry === void 0) {
+      return errorResponse(c, 404, "not_found", "Sandbox not found");
+    }
+    return c.json(copySummary(entry.summary));
+  });
+  app.get("/sandboxes/:sandboxRef/files", async (c) => {
+    const entry = registry.get(c.req.param("sandboxRef"));
+    if (entry === void 0) {
+      return errorResponse(c, 404, "not_found", "Sandbox not found");
+    }
+    try {
+      const requestedPath = c.req.query("path") ?? ".";
+      const normalizedPath = normalizeSandboxPath(requestedPath, true);
+      const entries = await listSandboxFiles(entry.session, normalizedPath);
+      return c.json({
+        sandboxRef: entry.summary.ref,
+        path: normalizedPath,
+        entries
+      });
+    } catch (error) {
+      return sandboxErrorResponse(c, error);
+    }
+  });
+  app.get("/sandboxes/:sandboxRef/files/content", async (c) => {
+    const entry = registry.get(c.req.param("sandboxRef"));
+    if (entry === void 0) {
+      return errorResponse(c, 404, "not_found", "Sandbox not found");
+    }
+    try {
+      const requestedPath = c.req.query("path");
+      if (requestedPath === void 0) {
+        throw new SandboxRouteError(400, "bad_request", "path query parameter is required");
+      }
+      const download = c.req.query("download");
+      if (download !== void 0 && download !== "1") {
+        throw new SandboxRouteError(400, "bad_request", "download must be 1 when provided");
+      }
+      const normalizedPath = normalizeSandboxPath(requestedPath, false);
+      const parentPath = path.posix.dirname(normalizedPath);
+      const siblings = await listSandboxFiles(entry.session, parentPath);
+      const file = siblings.find((candidate) => candidate.path === normalizedPath);
+      if (file === void 0) {
+        throw new SandboxRouteError(404, "not_found", "Sandbox file not found");
+      }
+      if (file.type !== "file") {
+        throw new SandboxRouteError(
+          400,
+          "bad_request",
+          "Sandbox content path must refer to a regular file"
+        );
+      }
+      if (file.size !== void 0 && file.size > maxFileResponseBytes) {
+        throw fileTooLarge(file.size);
+      }
+      const rawBytes = await entry.session.readFile(normalizedPath);
+      if (!(rawBytes instanceof Uint8Array)) {
+        throw new TypeError("Sandbox readFile returned an invalid byte payload");
+      }
+      if (rawBytes.byteLength > maxFileResponseBytes) {
+        throw fileTooLarge(rawBytes.byteLength);
+      }
+      const bytes = new Uint8Array(rawBytes.byteLength);
+      bytes.set(rawBytes);
+      const disposition = download === "1" ? "attachment" : "inline";
+      const filename = encodeURIComponent(path.posix.basename(normalizedPath));
+      return new Response(bytes, {
+        headers: {
+          "cache-control": "no-store",
+          "content-disposition": `${disposition}; filename*=UTF-8''${filename}`,
+          "content-length": String(bytes.byteLength),
+          "content-type": "application/octet-stream",
+          "x-content-type-options": "nosniff"
+        }
+      });
+    } catch (error) {
+      return sandboxErrorResponse(c, error);
+    }
+  });
+  app.get("/sandboxes/:sandboxRef/ports", (c) => {
+    const entry = registry.get(c.req.param("sandboxRef"));
+    if (entry === void 0) {
+      return errorResponse(c, 404, "not_found", "Sandbox not found");
+    }
+    if (!supportsPorts(entry.session)) {
+      return unsupportedSandboxOperation(c, "ports");
+    }
+    try {
+      return c.json({
+        sandboxRef: entry.summary.ref,
+        ports: normalizePorts(entry.session.publishedPorts)
+      });
+    } catch (error) {
+      return sandboxErrorResponse(c, error);
+    }
+  });
+  app.get("/sandboxes/:sandboxRef/processes", async (c) => {
+    const entry = registry.get(c.req.param("sandboxRef"));
+    if (entry === void 0) {
+      return errorResponse(c, 404, "not_found", "Sandbox not found");
+    }
+    if (!supportsProcesses(entry.session)) {
+      return unsupportedSandboxOperation(c, "processes");
+    }
+    try {
+      return c.json({
+        sandboxRef: entry.summary.ref,
+        processes: normalizeProcesses(await entry.session.listProcesses())
+      });
+    } catch (error) {
+      return sandboxErrorResponse(c, error);
+    }
+  });
+  app.get("/sandboxes/:sandboxRef/processes/:processId/logs", async (c) => {
+    const entry = registry.get(c.req.param("sandboxRef"));
+    if (entry === void 0) {
+      return errorResponse(c, 404, "not_found", "Sandbox not found");
+    }
+    if (!supportsProcesses(entry.session)) {
+      return unsupportedSandboxOperation(c, "processes.logs");
+    }
+    try {
+      const tailBytes = parseTailBytes(c.req.query("tailBytes"));
+      const processId = c.req.param("processId");
+      const processes = normalizeProcesses(await entry.session.listProcesses());
+      if (!processes.some((process2) => process2.id === processId)) {
+        throw new SandboxRouteError(404, "not_found", "Sandbox process not found");
+      }
+      const logs = normalizeProcessLogs(
+        await entry.session.readProcessLogs(processId, { tailBytes }),
+        tailBytes
+      );
+      return c.json({
+        sandboxRef: entry.summary.ref,
+        processId,
+        ...logs
+      });
+    } catch (error) {
+      return sandboxErrorResponse(c, error);
+    }
+  });
+}
+async function sandboxNoStore(c, next) {
+  c.header("cache-control", "no-store");
+  await next();
+}
+function sandboxSessionFromTool(tool) {
+  const metadata = tool[sandboxToolMetadataKey];
+  if (!isRecord4(metadata)) {
+    return void 0;
+  }
+  return isSandboxSession(metadata.session) ? metadata.session : void 0;
+}
+function isSandboxSession(value) {
+  return isRecord4(value) && typeof value.id === "string" && value.id.length > 0 && typeof value.provider === "string" && value.provider.length > 0 && typeof value.workdir === "string" && value.workdir.length > 0 && typeof value.listFiles === "function" && typeof value.readFile === "function";
+}
+function supportsPorts(session) {
+  return Array.isArray(session.publishedPorts);
+}
+function supportsProcesses(session) {
+  return typeof session.listProcesses === "function" && typeof session.readProcessLogs === "function";
+}
+function sandboxRef(provider, id) {
+  return Buffer.from(JSON.stringify([provider, id]), "utf8").toString("base64url");
+}
+function copySummary(summary) {
+  return {
+    ...summary,
+    agentIds: [...summary.agentIds],
+    toolNames: [...summary.toolNames],
+    capabilities: { ...summary.capabilities }
+  };
+}
+async function listSandboxFiles(session, filePath) {
+  return normalizeFileEntries(await session.listFiles(filePath)).sort((left, right) => {
+    if (left.type === "directory" && right.type !== "directory") return -1;
+    if (left.type !== "directory" && right.type === "directory") return 1;
+    return left.path.localeCompare(right.path);
+  });
+}
+function normalizeFileEntries(value) {
+  if (!Array.isArray(value)) {
+    throw new TypeError("Sandbox listFiles returned an invalid payload");
+  }
+  return value.map((item) => {
+    if (!isRecord4(item) || typeof item.path !== "string" || !isFileType(item.type)) {
+      throw new TypeError("Sandbox listFiles returned an invalid entry");
+    }
+    let entryPath;
+    try {
+      entryPath = normalizeSandboxPath(item.path, false);
+    } catch {
+      throw new TypeError("Sandbox listFiles returned an invalid entry path");
+    }
+    const entry = { path: entryPath, type: item.type };
+    if (item.size !== void 0) {
+      if (typeof item.size !== "number" || !Number.isFinite(item.size) || item.size < 0) {
+        throw new TypeError("Sandbox listFiles returned an invalid file size");
+      }
+      entry.size = item.size;
+    }
+    return entry;
+  });
+}
+function normalizePorts(value) {
+  if (!Array.isArray(value)) {
+    throw new TypeError("Sandbox publishedPorts returned an invalid payload");
+  }
+  return value.map((item) => {
+    if (!isRecord4(item) || !isPort(item.containerPort) || typeof item.host !== "string" || !isPort(item.hostPort) || typeof item.protocol !== "string") {
+      throw new TypeError("Sandbox publishedPorts returned an invalid entry");
+    }
+    return {
+      containerPort: item.containerPort,
+      host: item.host,
+      hostPort: item.hostPort,
+      protocol: item.protocol
+    };
+  });
+}
+function normalizeProcesses(value) {
+  if (!Array.isArray(value)) {
+    throw new TypeError("Sandbox listProcesses returned an invalid payload");
+  }
+  return value.map((item) => {
+    if (!isRecord4(item) || typeof item.id !== "string" || typeof item.command !== "string" || !Array.isArray(item.args) || !item.args.every((arg) => typeof arg === "string") || !isProcessStatus(item.status) || typeof item.startedAt !== "string") {
+      throw new TypeError("Sandbox listProcesses returned an invalid entry");
+    }
+    const process2 = {
+      id: item.id,
+      command: item.command,
+      args: item.args,
+      status: item.status,
+      startedAt: item.startedAt
+    };
+    if (typeof item.cwd === "string") process2.cwd = item.cwd;
+    if (typeof item.exitCode === "number") process2.exitCode = item.exitCode;
+    if (typeof item.endedAt === "string") process2.endedAt = item.endedAt;
+    return process2;
+  });
+}
+function normalizeProcessLogs(value, maxBytes) {
+  if (!isRecord4(value) || typeof value.stdout !== "string" || typeof value.stderr !== "string" || typeof value.stdoutTruncated !== "boolean" || typeof value.stderrTruncated !== "boolean") {
+    throw new TypeError("Sandbox readProcessLogs returned an invalid payload");
+  }
+  const stdout = boundedLogText(value.stdout, maxBytes);
+  const stderr = boundedLogText(value.stderr, maxBytes);
+  return {
+    stdout: stdout.text,
+    stderr: stderr.text,
+    stdoutTruncated: value.stdoutTruncated || stdout.truncated,
+    stderrTruncated: value.stderrTruncated || stderr.truncated
+  };
+}
+function boundedLogText(value, maxBytes) {
+  const bytes = new TextEncoder().encode(value);
+  if (bytes.byteLength <= maxBytes) {
+    return { text: value, truncated: false };
+  }
+  if (maxBytes === 0) {
+    return { text: "", truncated: true };
+  }
+  let start = bytes.byteLength - maxBytes;
+  while (start < bytes.byteLength && (bytes[start] ?? 0) >> 6 === 2) {
+    start += 1;
+  }
+  return {
+    text: new TextDecoder().decode(bytes.subarray(start)),
+    truncated: true
+  };
+}
+function normalizeSandboxPath(input, allowRoot) {
+  if (input.length === 0) {
+    throw new SandboxRouteError(400, "bad_request", "Sandbox path cannot be empty");
+  }
+  if (input.includes("\0")) {
+    throw new SandboxRouteError(400, "bad_request", "Sandbox path cannot contain null bytes");
+  }
+  const normalized = path.posix.normalize(input.replaceAll("\\", "/"));
+  if (path.posix.isAbsolute(normalized)) {
+    throw new SandboxRouteError(400, "bad_request", "Sandbox path must be relative");
+  }
+  if (normalized === ".." || normalized.startsWith("../")) {
+    throw new SandboxRouteError(400, "bad_request", "Sandbox path cannot leave the workspace");
+  }
+  if (normalized === "." && !allowRoot) {
+    throw new SandboxRouteError(400, "bad_request", "Sandbox path must refer to a file");
+  }
+  return normalized;
+}
+function parseTailBytes(value) {
+  if (value === void 0) {
+    return defaultProcessLogBytes;
+  }
+  const parsed = Number(value);
+  if (!Number.isInteger(parsed) || parsed < 0 || parsed > maxProcessLogBytes) {
+    throw new SandboxRouteError(
+      400,
+      "bad_request",
+      `tailBytes must be an integer from 0 through ${maxProcessLogBytes}`
+    );
+  }
+  return parsed;
+}
+function unsupportedSandboxOperation(c, operation) {
+  return errorResponse(c, 501, "unsupported_capability", `Sandbox does not support ${operation}`, {
+    capability: "sandboxes",
+    operation
+  });
+}
+function sandboxErrorResponse(c, error) {
+  if (error instanceof SandboxRouteError) {
+    return errorResponse(c, error.status, error.code, error.message);
+  }
+  const name = errorName(error);
+  if (name === "SandboxPathError") {
+    return errorResponse(c, 400, "bad_request", errorMessage(error));
+  }
+  if (name === "SandboxFileSizeError") {
+    return errorResponse(c, 413, "payload_too_large", errorMessage(error));
+  }
+  if (name === "SandboxSessionDestroyedError") {
+    return errorResponse(c, 409, "conflict", "Sandbox session is no longer available");
+  }
+  return errorResponse(
+    c,
+    500,
+    "internal_error",
+    "Sandbox inspection failed",
+    serializeError(error)
+  );
+}
+function fileTooLarge(size) {
+  return new SandboxRouteError(
+    413,
+    "payload_too_large",
+    `Sandbox file exceeds the ${maxFileResponseBytes}-byte response limit (${size} bytes)`
+  );
+}
+var SandboxRouteError = class extends Error {
+  constructor(status, code, message) {
+    super(message);
+    this.status = status;
+    this.code = code;
+  }
+  status;
+  code;
+};
+function isFileType(value) {
+  return value === "file" || value === "directory" || value === "symlink" || value === "other";
+}
+function isProcessStatus(value) {
+  return value === "running" || value === "exited" || value === "stopped";
+}
+function isPort(value) {
+  return Number.isInteger(value) && Number(value) >= 1 && Number(value) <= 65535;
+}
+function isRecord4(value) {
+  return typeof value === "object" && value !== null;
+}
+function errorName(error) {
+  return isRecord4(error) && typeof error.name === "string" ? error.name : "";
+}
+function errorMessage(error) {
+  return isRecord4(error) && typeof error.message === "string" ? error.message : String(error);
+}
+
 // src/runtime/sessions.ts
 function registerSessionRoutes(app, props) {
   app.get("/sessions", async (c) => {
@@ -5505,6 +6191,7 @@ function registerStatusRoutes(app, props) {
       agents: props.agents.length,
       pipelines: props.pipelines.length
     };
+    if (props.sandboxCount > 0) counts.sandboxes = props.sandboxCount;
     if (props.stores.sessions !== void 0) {
       counts.sessions = (await props.stores.sessions.listSessions({ limit: 100 })).length;
     }
@@ -5525,7 +6212,13 @@ function registerStatusRoutes(app, props) {
       runner,
       storage,
       counts,
-      capabilities: capabilityConfig(props.options, props.agents, props.pipelines, props.stores),
+      capabilities: capabilityConfig(
+        props.options,
+        props.agents,
+        props.pipelines,
+        props.stores,
+        props.sandboxCount
+      ),
       generatedAt: (/* @__PURE__ */ new Date()).toISOString()
     };
     return c.json(summary);
@@ -5734,20 +6427,38 @@ var Studio = class {
     const log = serveOptions.log ?? true;
     if (log) {
       const host = serveOptions.hostname ?? "localhost";
-      if (isStudioUiEnabled(this.options.ui)) {
-        const uiPath = studioUiEntryPath(resolveStudioUiOptions(this.options.ui));
-        console.log(`Studio UI: http://${host}:${port}${uiPath}`);
-      } else {
-        console.log(`Studio API: http://${host}:${port}`);
-      }
+      this.logAddress(host, port);
+    }
+    if (serveOptions.handleSignals ?? true) {
+      this.sigintHandler = () => {
+        this.close();
+        process.exit(0);
+      };
+      process.once("SIGINT", this.sigintHandler);
     }
-    this.sigintHandler = () => {
-      this.close();
-      process.exit(0);
-    };
-    process.once("SIGINT", this.sigintHandler);
     return this;
   }
+  async serve(serveOptions = {}) {
+    const { onShutdown, signal, ...startOptions } = serveOptions;
+    try {
+      this.start({ ...startOptions, log: false, handleSignals: false });
+      const server = this.server;
+      if (server === void 0) {
+        throw new Error("Studio server did not start");
+      }
+      await waitForServerListening(server);
+      if (startOptions.log ?? true) {
+        const requestedPort = startOptions.port ?? Number(process.env.RUNNER_PORT ?? 4021);
+        const address = server.address();
+        const port = typeof address === "object" && address !== null ? address.port : requestedPort;
+        this.logAddress(startOptions.hostname ?? "localhost", port);
+      }
+      await waitForShutdown(signal);
+    } finally {
+      this.close();
+      await onShutdown?.();
+    }
+  }
   close() {
     if (this.sigintHandler !== void 0) {
       process.off("SIGINT", this.sigintHandler);
@@ -5757,7 +6468,68 @@ var Studio = class {
     this.server = void 0;
     this.studio.close();
   }
+  logAddress(host, port) {
+    if (isStudioUiEnabled(this.options.ui)) {
+      const uiPath = studioUiEntryPath(resolveStudioUiOptions(this.options.ui));
+      console.log(`Studio UI: http://${host}:${port}${uiPath}`);
+    } else {
+      console.log(`Studio API: http://${host}:${port}`);
+    }
+  }
 };
+function waitForServerListening(server) {
+  if (server.listening) return Promise.resolve();
+  return new Promise((resolve2, reject) => {
+    const cleanup = () => {
+      server.off("listening", onListening);
+      server.off("error", onError);
+    };
+    const onListening = () => {
+      cleanup();
+      resolve2();
+    };
+    const onError = (error) => {
+      cleanup();
+      reject(error);
+    };
+    server.once("listening", onListening);
+    server.once("error", onError);
+  });
+}
+function waitForShutdown(signal) {
+  if (signal?.aborted) return Promise.resolve();
+  return new Promise((resolve2) => {
+    const useRawInput = process.stdin.isTTY === true;
+    const wasRaw = process.stdin.isRaw;
+    const wasFlowing = process.stdin.readableFlowing;
+    const cleanup = () => {
+      process.off("SIGINT", finish);
+      process.off("SIGTERM", finish);
+      signal?.removeEventListener("abort", finish);
+      if (useRawInput) {
+        process.stdin.off("data", onInput);
+        if (!wasRaw && process.stdin.isRaw) process.stdin.setRawMode(false);
+        if (wasFlowing !== true) process.stdin.pause();
+      }
+    };
+    const finish = () => {
+      cleanup();
+      resolve2();
+    };
+    const onInput = (chunk) => {
+      const interrupted = typeof chunk === "string" ? chunk.includes("") : chunk.includes(3);
+      if (interrupted) finish();
+    };
+    process.once("SIGINT", finish);
+    process.once("SIGTERM", finish);
+    signal?.addEventListener("abort", finish, { once: true });
+    if (useRawInput) {
+      if (!wasRaw) process.stdin.setRawMode(true);
+      process.stdin.resume();
+      process.stdin.on("data", onInput);
+    }
+  });
+}
 function studioOptionsFromTargets(targets, options) {
   const agents = targets.filter((target) => target instanceof Agent2);
   const pipelines = targets.filter(
@@ -5836,6 +6608,7 @@ function createStudioApp(options) {
   const evalMap = new Map(options.evals.map((suite) => [suite.id ?? suite.name, suite]));
   const approvalRuntime = createApprovalRuntime();
   const questionRuntime = createQuestionRuntime();
+  const sandboxRegistry = createStudioSandboxRegistry(agents);
   const app = new HonoApp();
   const uiOptions = isStudioUiEnabled(options.ui) ? resolveStudioUiOptions(options.ui) : void 0;
   if (uiOptions !== void 0 && !uiOptions.protectShell) {
@@ -5855,8 +6628,17 @@ function createStudioApp(options) {
       }
     })
   );
-  app.get("/config", (c) => c.json(buildConfig(options, agents, pipelines, stores)));
-  registerStatusRoutes(app, { options, agents, pipelines, stores });
+  app.get(
+    "/config",
+    (c) => c.json(buildConfig(options, agents, pipelines, stores, sandboxRegistry.size))
+  );
+  registerStatusRoutes(app, {
+    options,
+    agents,
+    pipelines,
+    stores,
+    sandboxCount: sandboxRegistry.size
+  });
   app.get("/agents", (c) => c.json({ agents: agents.map(agentConfig) }));
   app.get("/agents/:agentId", (c) => {
     const agent = agentMap.get(c.req.param("agentId"));
@@ -5875,6 +6657,7 @@ function createStudioApp(options) {
   registerModelRoutes(app, { registry: modelRegistry, agentMap });
   registerMcpRoutes(app, { agentMap });
   registerToolRoutes(app, { agentMap });
+  registerSandboxRoutes(app, sandboxRegistry);
   registerApprovalRoutes(app, approvalRuntime);
   registerQuestionRoutes(app, questionRuntime);
   registerObservabilityRoutes(app, observabilityHub);
@@ -5923,7 +6706,7 @@ function createStudioApp(options) {
       return app.fetch(request);
     },
     config() {
-      return buildConfig(options, agents, pipelines, stores);
+      return buildConfig(options, agents, pipelines, stores, sandboxRegistry.size);
     },
     close() {
     }
@@ -5962,8 +6745,8 @@ function createSqliteSessionStore(options = {}) {
   return new SqliteSessionStore(options.path ?? ":memory:");
 }
 var SqliteSessionStore = class {
-  constructor(path) {
-    this.path = path;
+  constructor(path2) {
+    this.path = path2;
   }
   path;
   kind = "sqlite";