openpond-sdk 0.0.2 → 0.0.4

package/README.md

@@ -1,6 +1,6 @@
 # `openpond-sdk`
 
-The OpenPond SDK is the server-side TypeScript client for running agentic work in OpenPond sandboxes. It gives Node.js applications, Next.js route handlers, workers, and backend services a small API for creating sandboxes, executing commands, managing files and runtimes, and running a model/tool loop in a persistent workspace.
+The OpenPond SDK is the server-side TypeScript client for running agentic work in OpenPond sandboxes. It gives Node.js applications, Next.js route handlers, workers, and backend services a small API for creating sandboxes, executing commands, managing files and runtimes, and running a model/tool loop in an isolated workspace.
 
 OpenPond is an open-source agent orchestration system for doing durable work with any model, provider, or subscription. The desktop app, CLI/TUI, and this SDK live in the same repository and share the sandbox client implementation. Desktop builds use the workspace source directly; installing this package from npm is only for external applications.
 
@@ -27,13 +27,43 @@ const openpond = createOpenPondClient({
 });
 
 export async function POST(request: Request) {
-  const { prompt, sandboxId } = await request.json();
-  const result = await openpond.work.run({ prompt, sandboxId });
+  const { prompt } = await request.json();
+  const result = await openpond.work.run({
+    prompt,
+    cleanup: "delete",
+    persistOutput: async ({ output, download }) => {
+      const response = await download();
+      const bytes = Buffer.from(response.file.contentsBase64, "base64");
+      await durableOutputStore.put({ output, bytes });
+    },
+  });
   return Response.json(result);
 }
 ```
 
-`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. Use `onEvent` to stream sandbox, model, command, persistence, and cleanup progress to a client. Keep API keys and the persistence callback in server code.
+
+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 available when the sandbox is kept. For ephemeral Work, use the lazy `download` function inside `persistOutput`; it verifies that the complete file arrived before deletion can begin.
 
 If sandbox execution is unavailable, the API fails with the stable `sandbox_runner_unavailable` error instead of returning a successful command result.
 
@@ -66,26 +96,43 @@ 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
+## Lifecycle, persistence, and cleanup
 
-Use a server-only environment file while developing:
+The generic SDK defaults to `cleanup: "keep"` for backwards compatibility. Applications can choose one of three explicit terminal policies:
 
-```dotenv
-OPENPOND_API_KEY=opk_...
-OPENPOND_API_URL=https://staging-api.openpond.ai
-```
+- `keep` leaves the sandbox running and makes the caller responsible for cleanup.
+- `stop` releases active compute while retaining the sandbox for deliberate resume.
+- `delete` removes ephemeral compute after output persistence succeeds.
+
+Deleting a turn that produced outputs requires an awaited `persistOutput` callback. If an application intentionally does not need the files, it must say so with `discardOutputs: true`. A persistence failure stops the sandbox instead of deleting recoverable output state. `result.lifecycle` and `persistence`/`cleanup` events expose the ordering and final observed state.
+
+For a follow-up turn on fresh compute, stage selected durable outputs as structured inputs:
 
-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.
+```ts
+await openpond.work.run({
+  prompt: "Revise the report",
+  cleanup: "delete",
+  inputs: [{
+    id: savedOutput.id,
+    name: savedOutput.name,
+    contentsBase64: savedOutput.contentsBase64,
+    mimeType: savedOutput.mimeType,
+    checksumSha256: savedOutput.sha256,
+    revision: savedOutput.revision,
+  }],
+  persistOutput: saveOutput,
+});
+```
 
-## Lifecycle and cleanup
+Inputs are placed under `/workspace/inputs/previous-outputs/` with a structured manifest at `/workspace/inputs/.openpond-context.json`. Arbitrary scratch files are not retained by ephemeral Work.
 
-Work sandboxes remain available so conversations can continue. Delete them when a conversation is removed or expires:
+You can still delete a caller-managed sandbox directly:
 
 ```ts
 await openpond.work.deleteSandbox(sandboxId);
 ```
 
-Use conservative budgets and application-level retention. API keys, provider credentials, and bypass secrets must remain in server-side configuration.
+The sandbox's 15-minute idle timeout is crash protection, not the normal successful-turn cleanup path. Use conservative budgets and application-level retention. API keys, provider credentials, and bypass secrets must remain in server-side configuration.
 
 ## Development
 

package/dist/index.js

@@ -2321,6 +2321,12 @@ async function* streamHostedChatTurn(options) {
 var DEFAULT_MODEL = "openpond-chat";
 var DEFAULT_MAX_STEPS = 24;
 var MAX_TOOL_OUTPUT_CHARS = 4e4;
+var WORK_OUTPUT_DIRECTORY = "/workspace/outputs";
+var WORK_INPUT_DIRECTORY = "/workspace/inputs/previous-outputs";
+var WORK_INPUT_MANIFEST = "/workspace/inputs/.openpond-context.json";
+var MAX_WORK_OUTPUTS = 100;
+var MAX_WORK_INPUTS = 100;
+var MAX_WORK_INPUT_BYTES = 100 * 1024 * 1024;
 var OpenPondWorkClient = class {
   #apiKey;
   #apiBaseUrl;
@@ -2337,72 +2343,242 @@ var OpenPondWorkClient = class {
     if (!prompt) throw new Error("Work prompt is required");
     input.signal?.throwIfAborted();
     const emit = async (event) => input.onEvent?.(event);
-    await emit({ type: "status", message: "Preparing sandbox" });
-    const sandbox = await this.#resolveSandbox(input);
-    await emit({
-      type: "sandbox",
-      sandboxId: sandbox.id,
-      state: sandbox.state
-    });
-    const messages = [
-      { role: "system", content: systemPrompt(sandbox.id) },
-      ...(input.history ?? []).map((message) => ({ ...message })),
-      { role: "user", content: prompt }
-    ];
+    const cleanupPolicy = input.cleanup ?? "keep";
+    const lifecycle = initialLifecycle(cleanupPolicy);
+    let sandbox = null;
+    let outputBaseline = null;
+    let finalizationAttempted = false;
     const maxSteps = boundedInteger(input.maxSteps, 1, 100, DEFAULT_MAX_STEPS);
     let finalText = "";
-    for (let step = 1; step <= maxSteps; step += 1) {
-      input.signal?.throwIfAborted();
-      await emit({ type: "status", message: `Thinking \xB7 step ${step}` });
-      const completion = await sendHostedChatTurn({
-        apiBaseUrl: this.#chatApiBaseUrl,
-        token: this.#apiKey,
-        model: input.model?.trim() || DEFAULT_MODEL,
-        messages,
-        tools: WORK_TOOLS,
-        toolChoice: "auto",
-        signal: input.signal,
-        metadata: {
-          source: "openpond-sdk-work",
-          sandboxId: sandbox.id,
-          apiBaseUrl: this.#apiBaseUrl,
-          ...input.metadata
-        }
-      });
-      const choice = completion.choices?.[0];
-      const assistantText = choice?.message?.content?.trim() ?? "";
-      const toolCalls = choice?.message?.tool_calls ?? [];
-      messages.push({
-        role: "assistant",
-        content: assistantText || null,
-        ...toolCalls.length > 0 ? { tool_calls: toolCalls } : {}
+    try {
+      await emit({ type: "status", message: "Preparing sandbox" });
+      sandbox = await this.#resolveSandbox(input);
+      await emit({
+        type: "sandbox",
+        sandboxId: sandbox.id,
+        state: sandbox.state
       });
-      if (assistantText) {
-        finalText = assistantText;
-        await emit({ type: "assistant", text: assistantText });
-      }
-      if (toolCalls.length === 0) {
-        const result = { sandboxId: sandbox.id, text: finalText, steps: step };
-        await emit({ type: "done", ...result });
-        return result;
-      }
-      for (const [index, toolCall] of toolCalls.entries()) {
-        const result = await this.#executeTool(
-          sandbox.id,
-          toolCall,
-          index,
-          input.timeoutSeconds,
-          emit
-        );
-        messages.push(result);
+      await this.#stageInputs(sandbox.id, input.inputs ?? []);
+      outputBaseline = await this.#prepareOutputDirectory(sandbox.id);
+      const messages = [
+        {
+          role: "system",
+          content: systemPrompt(sandbox.id, (input.inputs?.length ?? 0) > 0)
+        },
+        ...(input.history ?? []).map((message) => ({ ...message })),
+        { role: "user", content: prompt }
+      ];
+      for (let step = 1; step <= maxSteps; step += 1) {
+        input.signal?.throwIfAborted();
+        await emit({ type: "status", message: `Thinking \xB7 step ${step}` });
+        const completion = await sendHostedChatTurn({
+          apiBaseUrl: this.#chatApiBaseUrl,
+          token: this.#apiKey,
+          model: input.model?.trim() || DEFAULT_MODEL,
+          messages,
+          tools: WORK_TOOLS,
+          toolChoice: "auto",
+          signal: input.signal,
+          metadata: {
+            source: "openpond-sdk-work",
+            sandboxId: sandbox.id,
+            apiBaseUrl: this.#apiBaseUrl,
+            ...input.metadata
+          }
+        });
+        const choice = completion.choices?.[0];
+        const assistantText = choice?.message?.content?.trim() ?? "";
+        const toolCalls = choice?.message?.tool_calls ?? [];
+        messages.push({
+          role: "assistant",
+          content: assistantText || null,
+          ...toolCalls.length > 0 ? { tool_calls: toolCalls } : {}
+        });
+        if (assistantText) {
+          finalText = assistantText;
+          await emit({ type: "assistant", text: assistantText });
+        }
+        if (toolCalls.length === 0) {
+          const outputs = await this.#collectOutputs(sandbox.id, outputBaseline);
+          for (const output of outputs) await emit({ type: "output", output });
+          finalizationAttempted = true;
+          await this.#finalizeSandbox(sandbox.id, outputs, input, lifecycle, emit);
+          const result = {
+            sandboxId: sandbox.id,
+            text: finalText,
+            steps: step,
+            outputs,
+            lifecycle
+          };
+          await emit({ type: "done", ...result });
+          return result;
+        }
+        for (const [index, toolCall] of toolCalls.entries()) {
+          const result = await this.#executeTool(
+            sandbox.id,
+            toolCall,
+            index,
+            input.timeoutSeconds,
+            emit
+          );
+          messages.push(result);
+        }
+      }
+      throw new Error(`Work did not finish within ${maxSteps} steps`);
+    } catch (error) {
+      if (sandbox && outputBaseline && !finalizationAttempted) {
+        try {
+          const outputs = await this.#collectOutputs(sandbox.id, outputBaseline);
+          for (const output of outputs) await emit({ type: "output", output });
+          await this.#finalizeSandbox(sandbox.id, outputs, input, lifecycle, emit);
+        } catch (finalizationError) {
+          attachWorkFailure(error, lifecycle, finalizationError);
+        }
       }
+      attachWorkFailure(error, lifecycle);
+      throw error;
     }
-    throw new Error(`Work did not finish within ${maxSteps} steps`);
   }
   async deleteSandbox(sandboxId) {
     const sandbox = await this.#sandboxes.get(sandboxId);
     if (sandbox.state === "deleted") return;
-    await this.#sandboxes.delete(sandboxId, { async: true });
+    await this.#sandboxes.delete(sandboxId);
+  }
+  async #stageInputs(sandboxId, inputs) {
+    if (inputs.length === 0) return;
+    if (inputs.length > MAX_WORK_INPUTS) {
+      throw new Error(`Work inputs exceed the ${MAX_WORK_INPUTS} file limit`);
+    }
+    const decodedBytes = inputs.reduce(
+      (total, input) => total + Buffer.byteLength(input.contentsBase64, "base64"),
+      0
+    );
+    if (decodedBytes > MAX_WORK_INPUT_BYTES) {
+      throw new Error(`Work inputs exceed the ${MAX_WORK_INPUT_BYTES} byte limit`);
+    }
+    await this.#sandboxes.mkdir(sandboxId, {
+      path: WORK_INPUT_DIRECTORY,
+      recursive: true
+    });
+    const usedNames = /* @__PURE__ */ new Set();
+    const manifest = [];
+    for (const [index, input] of inputs.entries()) {
+      const name = uniqueInputName(input, index, usedNames);
+      const stagedPath = `${WORK_INPUT_DIRECTORY}/${name}`;
+      await this.#sandboxes.uploadFileBase64(
+        sandboxId,
+        stagedPath,
+        input.contentsBase64
+      );
+      manifest.push({
+        id: input.id,
+        path: stagedPath,
+        name: input.name,
+        mimeType: input.mimeType ?? null,
+        checksumSha256: input.checksumSha256 ?? null,
+        revision: input.revision ?? null,
+        metadata: input.metadata ?? {}
+      });
+    }
+    await this.#sandboxes.uploadFile(
+      sandboxId,
+      WORK_INPUT_MANIFEST,
+      JSON.stringify({ version: 1, files: manifest }, null, 2)
+    );
+  }
+  async #finalizeSandbox(sandboxId, outputs, input, lifecycle, emit) {
+    lifecycle.persistence.outputCount = outputs.length;
+    if (outputs.length === 0) {
+      lifecycle.persistence.status = "not_needed";
+    } else if (input.persistOutput) {
+      lifecycle.persistence.status = "running";
+      for (const output of outputs) {
+        await emit({ type: "persistence", output, status: "started" });
+        try {
+          const download = lazyOutputDownload(this.#sandboxes, sandboxId, output);
+          await input.persistOutput({ output, download });
+          lifecycle.persistence.persistedCount += 1;
+          await emit({ type: "persistence", output, status: "succeeded" });
+        } catch (error) {
+          const message = errorMessage(error);
+          lifecycle.persistence.status = "failed";
+          lifecycle.persistence.error = message;
+          await emit({
+            type: "persistence",
+            output,
+            status: "failed",
+            error: message
+          });
+          if ((input.cleanup ?? "keep") !== "keep") {
+            await this.#cleanupSandbox(sandboxId, "stop", lifecycle, emit);
+          }
+          throw error;
+        }
+      }
+      lifecycle.persistence.status = "complete";
+    } else if ((input.cleanup ?? "keep") === "delete" && !input.discardOutputs) {
+      lifecycle.persistence.status = "failed";
+      lifecycle.persistence.error = "Deleting a Work sandbox with outputs requires persistOutput or discardOutputs: true";
+      await this.#cleanupSandbox(sandboxId, "stop", lifecycle, emit);
+      throw new Error(lifecycle.persistence.error);
+    } else {
+      lifecycle.persistence.status = "not_requested";
+    }
+    await this.#cleanupSandbox(
+      sandboxId,
+      input.cleanup ?? "keep",
+      lifecycle,
+      emit
+    );
+  }
+  async #cleanupSandbox(sandboxId, policy, lifecycle, emit) {
+    if (policy === "keep") return;
+    lifecycle.cleanup.status = "running";
+    await emit({ type: "cleanup", policy, status: "started" });
+    try {
+      const sandbox = policy === "delete" ? await this.#sandboxes.delete(sandboxId) : (await this.#sandboxes.stop(sandboxId)).sandbox;
+      lifecycle.cleanup.finalSandboxState = sandbox.state;
+      lifecycle.cleanup.status = policy === "delete" && sandbox.state === "deleted" || policy === "stop" && sandbox.state === "stopped" ? "complete" : "pending";
+      await emit({
+        type: "cleanup",
+        policy,
+        status: lifecycle.cleanup.status,
+        sandboxState: sandbox.state
+      });
+    } catch (error) {
+      const message = errorMessage(error);
+      lifecycle.cleanup.status = "failed";
+      lifecycle.cleanup.error = message;
+      await emit({ type: "cleanup", policy, status: "failed", error: message });
+      throw error;
+    }
+  }
+  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) {
@@ -2511,16 +2687,121 @@ var WORK_TOOLS = [
     }
   }
 ];
-function systemPrompt(sandboxId) {
+function systemPrompt(sandboxId, hasInputs) {
   return [
-    "You are OpenPond Work, a careful coding agent operating in a persistent Linux sandbox.",
+    "You are OpenPond Work, a careful coding agent operating in an isolated Linux sandbox.",
     `The active sandbox is ${sandboxId}.`,
+    ...hasInputs ? [
+      `Caller-provided durable files are staged under ${WORK_INPUT_DIRECTORY}; structured metadata is in ${WORK_INPUT_MANIFEST}.`
+    ] : [],
     "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 initialLifecycle(cleanupPolicy) {
+  return {
+    cleanupPolicy,
+    persistence: {
+      status: "not_requested",
+      outputCount: 0,
+      persistedCount: 0
+    },
+    cleanup: { status: "not_requested" }
+  };
+}
+function lazyOutputDownload(sandboxes, sandboxId, output) {
+  let pending = null;
+  return () => {
+    pending ??= sandboxes.downloadFileResponse(sandboxId, {
+      path: output.path,
+      maxBytes: Math.max(1, output.sizeBytes)
+    }).then((response) => {
+      const decodedBytes = Buffer.byteLength(
+        response.file.contentsBase64,
+        "base64"
+      );
+      if (response.file.truncated || response.file.returnedBytes !== response.file.totalSizeBytes || decodedBytes !== output.sizeBytes) {
+        throw new Error(`Output download was incomplete for ${output.name}`);
+      }
+      return response;
+    });
+    return pending;
+  };
+}
+function uniqueInputName(input, index, usedNames) {
+  const safeId = input.id.replace(/[^a-zA-Z0-9._-]+/g, "-").slice(0, 80) || `input-${index + 1}`;
+  const safeName = input.name.replace(/[^a-zA-Z0-9._-]+/g, "-").slice(-120) || "file";
+  const base = `${safeId}-${safeName}`;
+  let candidate = base;
+  let collision = 1;
+  while (usedNames.has(candidate)) {
+    collision += 1;
+    candidate = `${base}-${collision}`;
+  }
+  usedNames.add(candidate);
+  return candidate;
+}
+function attachWorkFailure(error, lifecycle, finalizationError) {
+  if (!error || typeof error !== "object") return;
+  Object.assign(error, {
+    workLifecycle: lifecycle,
+    ...finalizationError ? { workFinalizationError: errorMessage(finalizationError) } : {}
+  });
+}
+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) };
 }