openpond-sdk 0.0.1 → 0.0.3

package/README.md

@@ -33,9 +33,33 @@ export async function POST(request: Request) {
 }
 ```
 
-`work.run` creates a sandbox when `sandboxId` is omitted. Pass the returned ID into the next turn to continue in the same filesystem. Use `onEvent` to stream sandbox, model, and command progress to a client.
+`work.run` creates a sandbox when `sandboxId` is omitted. Pass the returned ID into the next turn to continue in the same filesystem. Use `onEvent` to stream sandbox, model, command, and output progress to a client.
 
-Work requires a real `remote-firecracker` runtime. It fails closed if an environment returns the simulator or a nominal remote sandbox responds with a non-executing command marker, so an accepted command can never be mistaken for actual filesystem work.
+Completed files written under `/workspace/outputs` are collected automatically. The model does not need to publish or register them. Each detected file is emitted as an `output` event and returned in `result.outputs`:
+
+```ts
+const result = await openpond.work.run({
+  prompt: "Create a DOCX summary",
+  onEvent(event) {
+    if (event.type === "output") console.log(event.output.name);
+  },
+});
+
+for (const output of result.outputs) {
+  const downloaded = await openpond.work.downloadOutput(
+    result.sandboxId,
+    output,
+  );
+  const bytes = Buffer.from(downloaded.file.contentsBase64, "base64");
+  // Stream bytes from your authenticated server route.
+}
+```
+
+Output descriptors include the sandbox path, filename, MIME type, size, modification time, and preview hints. `downloadOutput` remains a separate deterministic file operation, so downloading a result never starts another model turn.
+
+If sandbox execution is unavailable, the API fails with the stable `sandbox_runner_unavailable` error instead of returning a successful command result.
+
+API failures are exposed as `OpenPondApiError`, with `status` and stable `code` fields for server-side handling. `work.run` propagates these failures instead of asking the model to interpret infrastructure errors.
 
 ## Raw sandbox API
 
@@ -64,17 +88,6 @@ console.log(result.command.output);
 
 The package also exports `createOpenPondSandboxClient`, all public sandbox input and response types, and the OpChat helpers used by the Work loop.
 
-## Staging
-
-Use a server-only environment file while developing:
-
-```dotenv
-OPENPOND_API_KEY=opk_...
-OPENPOND_API_URL=https://staging-api.openpond.ai
-```
-
-If the staging deployment has Vercel protection enabled, also set `VERCEL_AUTOMATION_BYPASS_SECRET`. The SDK only sends that bypass header to OpenPond staging hosts.
-
 ## Lifecycle and cleanup
 
 Work sandboxes remain available so conversations can continue. Delete them when a conversation is removed or expires:

package/dist/index.js

@@ -252,12 +252,6 @@ async function runSandboxSmoke(client, options = {}) {
       )
     );
     sandboxId = sandbox.id;
-    const expectedRuntimeDriver = options.expectedRuntimeDriver ?? "remote-firecracker";
-    if (sandbox.runtimeDriver !== expectedRuntimeDriver) {
-      throw new Error(
-        `expected ${expectedRuntimeDriver}, got ${sandbox.runtimeDriver}`
-      );
-    }
     const expectedMppMode = options.expectedMppMode;
     if (expectedMppMode && sandbox.reservation.mpp?.mode !== expectedMppMode) {
       throw new Error(
@@ -608,6 +602,19 @@ var ApiResponseTooLargeError = class extends Error {
   requestUrl;
   code = "OPENPOND_API_RESPONSE_TOO_LARGE";
 };
+var OpenPondApiError = class extends Error {
+  constructor(status, errorCode, label, apiMessage = null) {
+    const detail = apiMessage || errorCode;
+    super(`${label} failed: ${status}${detail ? ` ${detail}` : ""}`);
+    this.status = status;
+    this.apiMessage = apiMessage;
+    this.name = "OpenPondApiError";
+    this.code = errorCode || "OPENPOND_API_ERROR";
+  }
+  status;
+  apiMessage;
+  code;
+};
 async function apiFetch(baseUrl, token, requestPath, options = {}) {
   const { timeoutMs = DEFAULT_API_TIMEOUT_MS, maxResponseBytes = DEFAULT_API_RESPONSE_BYTES, ...init } = options;
   const requestUrl = `${baseUrl}${requestPath}`;
@@ -656,8 +663,9 @@ async function readApiJson(response, label) {
     payload = {};
   }
   if (!response.ok) {
-    const message = typeof payload.message === "string" ? payload.message : typeof payload.error === "string" ? payload.error : "";
-    throw new Error(`${label} failed: ${response.status}${message ? ` ${message}` : ""}`);
+    const errorCode = typeof payload.error === "string" ? payload.error : null;
+    const apiMessage = typeof payload.message === "string" ? payload.message : null;
+    throw new OpenPondApiError(response.status, errorCode, label, apiMessage);
   }
   return payload;
 }
@@ -2313,17 +2321,8 @@ async function* streamHostedChatTurn(options) {
 var DEFAULT_MODEL = "openpond-chat";
 var DEFAULT_MAX_STEPS = 24;
 var MAX_TOOL_OUTPUT_CHARS = 4e4;
-var OpenPondNonExecutingSandboxError = class extends Error {
-  constructor(sandboxId) {
-    super(
-      `Sandbox ${sandboxId} accepted a command without executing it. A real remote runner is required for OpenPond Work.`
-    );
-    this.sandboxId = sandboxId;
-    this.name = "OpenPondNonExecutingSandboxError";
-  }
-  sandboxId;
-  code = "OPENPOND_NON_EXECUTING_SANDBOX";
-};
+var WORK_OUTPUT_DIRECTORY = "/workspace/outputs";
+var MAX_WORK_OUTPUTS = 100;
 var OpenPondWorkClient = class {
   #apiKey;
   #apiBaseUrl;
@@ -2342,20 +2341,12 @@ var OpenPondWorkClient = class {
     const emit = async (event) => input.onEvent?.(event);
     await emit({ type: "status", message: "Preparing sandbox" });
     const sandbox = await this.#resolveSandbox(input);
-    if (sandbox.runtimeDriver === "simulated-firecracker" && !input.allowSimulated) {
-      if (!input.sandboxId) {
-        await this.#sandboxes.delete(sandbox.id, { async: true }).catch(() => void 0);
-      }
-      throw new Error(
-        "OpenPond Work requires a remote-firecracker sandbox, but this environment returned the non-executing simulated-firecracker driver."
-      );
-    }
     await emit({
       type: "sandbox",
       sandboxId: sandbox.id,
-      state: sandbox.state,
-      runtimeDriver: sandbox.runtimeDriver
+      state: sandbox.state
     });
+    const outputBaseline = await this.#prepareOutputDirectory(sandbox.id);
     const messages = [
       { role: "system", content: systemPrompt(sandbox.id) },
       ...(input.history ?? []).map((message) => ({ ...message })),
@@ -2394,7 +2385,14 @@ var OpenPondWorkClient = class {
         await emit({ type: "assistant", text: assistantText });
       }
       if (toolCalls.length === 0) {
-        const result = { sandboxId: sandbox.id, text: finalText, steps: step };
+        const outputs = await this.#collectOutputs(sandbox.id, outputBaseline);
+        for (const output of outputs) await emit({ type: "output", output });
+        const result = {
+          sandboxId: sandbox.id,
+          text: finalText,
+          steps: step,
+          outputs
+        };
         await emit({ type: "done", ...result });
         return result;
       }
@@ -2416,6 +2414,33 @@ var OpenPondWorkClient = class {
     if (sandbox.state === "deleted") return;
     await this.#sandboxes.delete(sandboxId, { async: true });
   }
+  downloadOutput(sandboxId, output) {
+    return this.#sandboxes.downloadFileResponse(
+      sandboxId,
+      typeof output === "string" ? output : output.path
+    );
+  }
+  async #prepareOutputDirectory(sandboxId) {
+    await this.#sandboxes.mkdir(sandboxId, {
+      path: WORK_OUTPUT_DIRECTORY,
+      recursive: true
+    });
+    return outputSignatures(await this.#listOutputFiles(sandboxId));
+  }
+  async #collectOutputs(sandboxId, baseline) {
+    const files = await this.#listOutputFiles(sandboxId);
+    return files.filter((file) => baseline.get(file.path) !== outputSignature(file)).sort((left, right) => left.path.localeCompare(right.path)).slice(0, MAX_WORK_OUTPUTS).map(workOutputFromFile);
+  }
+  async #listOutputFiles(sandboxId) {
+    const listed = await this.#sandboxes.listFiles(sandboxId, {
+      path: WORK_OUTPUT_DIRECTORY,
+      recursive: true,
+      maxEntries: 500
+    });
+    return listed.files.filter(
+      (file) => file.type === "file" && !normalizedOutputPath(file.path).includes("/.openpond-")
+    );
+  }
   async #resolveSandbox(input) {
     if (input.sandboxId) {
       const existing = await this.#sandboxes.get(input.sandboxId);
@@ -2484,18 +2509,6 @@ var OpenPondWorkClient = class {
         timeoutSeconds: boundedInteger(timeoutSeconds, 1, 900, 180)
       });
       const output = truncate(response.command.output, MAX_TOOL_OUTPUT_CHARS);
-      if (isNonExecutingSandboxOutput(output)) {
-        await emit({
-          type: "tool",
-          toolCallId,
-          command,
-          status: "failed",
-          output: "Staging accepted the command but did not execute it.",
-          exitCode: response.command.exitCode
-        });
-        await this.#sandboxes.delete(sandboxId, { async: true }).catch(() => void 0);
-        throw new OpenPondNonExecutingSandboxError(sandboxId);
-      }
       const status = response.command.status === "succeeded" ? "succeeded" : "failed";
       await emit({
         type: "tool",
@@ -2511,7 +2524,7 @@ var OpenPondWorkClient = class {
         output
       });
     } catch (error) {
-      if (error instanceof OpenPondNonExecutingSandboxError) throw error;
+      if (error instanceof OpenPondApiError) throw error;
       const output = errorMessage(error);
       await emit({ type: "tool", toolCallId, command, status: "failed", output });
       return toolMessage(toolCallId, { status: "failed", error: output });
@@ -2540,11 +2553,63 @@ function systemPrompt(sandboxId) {
     "You are OpenPond Work, a careful coding agent operating in a persistent Linux sandbox.",
     `The active sandbox is ${sandboxId}.`,
     "Use run_command to inspect the workspace, edit files, and validate your work.",
+    `Place completed user-facing files in ${WORK_OUTPUT_DIRECTORY}. The runtime collects new and revised files there automatically when the turn completes.`,
     "Do the requested work completely. Preserve existing user changes and avoid destructive commands.",
     "Keep the user informed with concise prose, but call tools whenever verification or file changes are needed.",
     "Before finishing, run relevant tests and summarize the concrete result."
   ].join("\n");
 }
+function outputSignatures(files) {
+  return new Map(files.map((file) => [file.path, outputSignature(file)]));
+}
+function outputSignature(file) {
+  return `${file.sizeBytes}:${file.updatedAt}`;
+}
+function workOutputFromFile(file) {
+  const name = normalizedOutputPath(file.path).split("/").at(-1) || file.path;
+  const mimeType = workOutputMimeType(name);
+  return {
+    path: file.path,
+    name,
+    mimeType,
+    sizeBytes: file.sizeBytes,
+    updatedAt: file.updatedAt,
+    isBinary: file.isBinary ?? null,
+    previewable: file.previewable ?? (mimeType.startsWith("image/") || mimeType === "application/pdf" || mimeType.startsWith("text/"))
+  };
+}
+function normalizedOutputPath(value) {
+  return value.replaceAll("\\", "/");
+}
+function workOutputMimeType(name) {
+  const extension = name.toLowerCase().match(/\.[^.]+$/)?.[0] ?? "";
+  return WORK_OUTPUT_MIME_TYPES[extension] ?? "application/octet-stream";
+}
+var WORK_OUTPUT_MIME_TYPES = Object.freeze({
+  ".avif": "image/avif",
+  ".csv": "text/csv",
+  ".docx": "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
+  ".gif": "image/gif",
+  ".html": "text/html",
+  ".jpeg": "image/jpeg",
+  ".jpg": "image/jpeg",
+  ".json": "application/json",
+  ".m4a": "audio/mp4",
+  ".md": "text/markdown",
+  ".mov": "video/quicktime",
+  ".mp3": "audio/mpeg",
+  ".mp4": "video/mp4",
+  ".pdf": "application/pdf",
+  ".png": "image/png",
+  ".pptx": "application/vnd.openxmlformats-officedocument.presentationml.presentation",
+  ".svg": "image/svg+xml",
+  ".tsv": "text/tab-separated-values",
+  ".txt": "text/plain",
+  ".wav": "audio/wav",
+  ".webm": "video/webm",
+  ".webp": "image/webp",
+  ".xlsx": "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet"
+});
 function toolMessage(toolCallId, payload) {
   return { role: "tool", tool_call_id: toolCallId, content: JSON.stringify(payload) };
 }
@@ -2560,10 +2625,6 @@ function truncate(value, maximum) {
 function errorMessage(error) {
   return error instanceof Error ? error.message : String(error);
 }
-function isNonExecutingSandboxOutput(output) {
-  const normalized = output.toLowerCase();
-  return normalized.includes("command accepted by simulated-firecracker driver") || normalized.includes("no host command was executed");
-}
 function sleep2(milliseconds, signal) {
   return new Promise((resolve, reject) => {
     if (signal?.aborted) {
@@ -2585,7 +2646,7 @@ function sleep2(milliseconds, signal) {
 
 // ../cloud/src/sandbox/types/runtime-profiles.ts
 var SANDBOX_RUNTIME_PROFILE_IDS = [
-  "openpond-generic-firecracker-v1",
+  "openpond-generic-v1",
   "openpond-work-v1",
   "openpond-coding-core-v1",
   "openpond-agent-harness-v1"
@@ -2616,8 +2677,8 @@ function createOpenPondClient(options) {
   return new OpenPondClient(options);
 }
 export {
+  OpenPondApiError,
   OpenPondClient,
-  OpenPondNonExecutingSandboxError,
   OpenPondSandboxClient,
   OpenPondWorkClient,
   SANDBOX_RUNTIME_PROFILE_IDS,