@h-sandbox/deepagents 0.1.0-rc.0 → 0.1.0-rc.2

package/README.md

@@ -33,28 +33,33 @@ verifies the original tests and returns a diff after confirmed cleanup.
 
 ## Availability
 
-**Unpublished release candidate.** Native tools and an independently verified
-model repair have passed; final release checks and npm publication are pending.
-Evaluate the adapter archive with the exact published SDK below. Node 20+ is
-the consumer target; repository tooling uses Node 22+.
+**Developer preview on npm.** Install `@h-sandbox/deepagents@next` with the exact
+SDK and framework peers below. Native tools and an independently verified model
+repair have passed. Use Node 22 or 24 LTS. Node 20 remains a legacy compatibility target, not a supported
+Node.js production line. This optional package has its
+own release cycle, separate from the SDK.
+
+Minimal backend installation:
+
+```bash
+npm install --save-exact @h-sandbox/deepagents@next @h-sandbox/sdk@0.5.0-rc.12 deepagents@1.14.0
+```
+
+For the complete model and checkpoint examples, start with the full direct
+dependency set together. Adding older framework pins after auto-installed peers
+can leave duplicate LangGraph types in a pnpm lockfile.
 
 ```bash
-# In a reviewed Harakiri checkout:
-pnpm install --frozen-lockfile
-pnpm --filter @h-sandbox/deepagents build
-mkdir -p /tmp/harakiri-framework-candidate
-pnpm --filter @h-sandbox/deepagents pack --pack-destination /tmp/harakiri-framework-candidate
-
-# In your server-side application, using the resulting adapter archive path:
-npm install --save-exact @h-sandbox/sdk@0.5.0-rc.11 "$DEEPAGENTS_TARBALL" \
+# In your server-side application:
+npm install --save-exact @h-sandbox/deepagents@next @h-sandbox/sdk@0.5.0-rc.12 \
   deepagents@1.14.0 langchain@1.5.11 @langchain/core@1.2.12 \
   @langchain/langgraph@1.4.17 langsmith@0.9.0 zod@4.4.3
 ```
 
-The tested peers are **SDK 0.5.0-rc.11 and Deep Agents 1.14.0**, both exact because
-these preview contracts are evolving. The reviewed archive identifies this
-adapter candidate. Commit your application's lockfile. Other framework or SDK
-versions need a fresh compatibility run.
+The tested peers are **SDK 0.5.0-rc.12 and Deep Agents 1.14.0**, both exact because
+these preview contracts are evolving. `--save-exact` resolves the moving `next`
+channel to a concrete version; commit your application's lockfile. Other
+framework or SDK versions need a fresh compatibility run.
 
 ## Connect an Existing Sandbox
 
@@ -135,6 +140,13 @@ checkpointer, pause for approval and retrieve one command's result. It does not
 claim process-restart durability. Production applications supply a persistent
 checkpointer and their own authorized sandbox lookup.
 
+The [persistent workflow guide](https://github.com/nabilblk/h-sandbox/blob/main/docs/integrations/reliable-framework-workflows.md)
+adds a real `createDeepAgent`/PostgresSaver application with separate worker
+processes, checkpoint-bound approval, acknowledged-command observation and
+explicit retained-file recovery. Use adapter `0.1.0-rc.2` and SDK `0.5.0-rc.12`.
+The application example is versioned source, not a database service in the package;
+the guide shows how to run it against the published dependencies.
+
 The repair example requires **Node.js, Git,
 bash and GNU file tools** in the selected template. Its blocked egress policy
 requires enforcement support in your installation. It downloads no dependencies
@@ -166,11 +178,12 @@ command exercises remote shell/file operations with scripted decisions. Real
 model acceptance and publication are separate gates. On September 24, the
 digest-pinned Qwen3 4B Instruct model completed this repair on an isolated amd64
 runner: five responses, no truncated responses or invalid tool calls, unchanged
-original tests, a verified patch and confirmed cleanup. The overall run then
-failed its final operator-key revocation check after the captured browser token
-expired. See [the qualification run](https://github.com/nabilblk/h-sandbox/actions/runs/36004058904).
-The full suite must pass before publication. This is one small repair, not a
-model-quality or production reliability benchmark.
+original tests, a verified patch and confirmed cleanup. The
+[full qualification run](https://github.com/nabilblk/h-sandbox/actions/runs/36007730164)
+passed all 15 gates, including operator-key revocation. This is one small repair,
+not a model-quality or production reliability benchmark. The
+[delivery receipt](https://github.com/nabilblk/h-sandbox/blob/main/docs/release-notes/deepagents-0.1.0-delivery.md)
+distinguishes native qualification from package publication and deployment.
 
 ## Boundaries
 
@@ -181,10 +194,13 @@ model-quality or production reliability benchmark.
   exits are ordinary tool results. The adapter never retries a mutation.
   A framework or model can still request the same action again; approval and
   idempotent application operations are required where repeat effects matter.
-- Execution timeout, status-polling timeout and sandbox TTL are separate.
-  Cancellation stops polling/between-file work, not a running remote command.
-  Submission, file and log HTTP requests use the SDK transport; supply bounded
-  `fetch` in client configuration if you need per-request transport deadlines.
+- HTTP `requestTimeoutMs`, execution timeout,
+  observation timeout and sandbox TTL are separate. JSON HTTP requests default
+  to 120 seconds, including body reads. Per-call options and caller cancellation
+  also cover submissions, logs and transfers; the adapter's observation budget
+  includes final logs. None of these kill a remote command or authorize a retry.
+  Earlier rc.1 instead requires a bounded custom `fetch` for per-request
+  deadlines and its observation budget excludes final logs.
 - Output is stdout followed by stderr, not a chronological merge. The default
   combined UTF-8 log limit is 64 KiB; provider truncation flags remain visible.
   A fixed-size termination notice is outside that limit so timeouts/kills are

package/dist/backend.js

@@ -21,7 +21,7 @@ export class HarakiriSandboxBackend extends BaseSandbox {
     constructor(sandbox, options = {}) {
         super();
         if (typeof sandbox.files.readBytes !== "function" || typeof sandbox.processes.connect !== "function") {
-            throw new TypeError("This adapter requires Harakiri SDK 0.5.0-rc.11 or newer, not npm rc.10.");
+            throw new TypeError("This adapter requires its tested Harakiri SDK peer, 0.5.0-rc.12.");
         }
         this.#sandbox = sandbox;
         this.#execution = executionOptions(sandbox, options);
@@ -38,7 +38,7 @@ export class HarakiriSandboxBackend extends BaseSandbox {
         try {
             const process = await this.#sandbox.processes.start({
                 command, cwd: this.#execution.cwd, timeoutMs: this.#execution.timeoutMs, detached: true
-            });
+            }, { signal: this.#execution.signal, requestTimeoutMs: this.#execution.requestTimeoutMs });
             reference = process.reference;
         }
         catch (cause) {
@@ -76,7 +76,9 @@ export class HarakiriSandboxBackend extends BaseSandbox {
                     results.push({ path, error: "invalid_path" });
                     continue;
                 }
-                await this.#sandbox.files.write(this.#path(path), content, { createParents: true });
+                await this.#sandbox.files.write(this.#path(path), content, {
+                    createParents: true, signal: this.#execution.signal, requestTimeoutMs: this.#execution.requestTimeoutMs
+                });
                 results.push({ path, error: null });
             }
             catch (cause) {
@@ -101,13 +103,14 @@ export class HarakiriSandboxBackend extends BaseSandbox {
                     continue;
                 }
                 const absolute = this.#path(path);
-                const { file } = await this.#sandbox.files.stat(absolute);
+                const request = { signal: this.#execution.signal, requestTimeoutMs: this.#execution.requestTimeoutMs };
+                const { file } = await this.#sandbox.files.stat(absolute, request);
                 if (file.type === "directory" || file.type === "dir") {
                     results.push({ path, content: null, error: "is_directory" });
                     continue;
                 }
                 this.#checkBytes(bytes + file.size);
-                const content = await this.#sandbox.files.readBytes(absolute);
+                const content = await this.#sandbox.files.readBytes(absolute, request);
                 bytes += content.byteLength;
                 this.#checkBytes(bytes);
                 results.push({ path, content, error: null });

package/dist/execution.d.ts

@@ -1,16 +1,16 @@
-import type { HarakiriSandbox, SandboxCommandLogsResponse, SandboxCommandSummary } from "@h-sandbox/sdk";
+import type { HarakiriSandbox, RequestOptions, SandboxCommandLogsResponse, SandboxCommandSummary } from "@h-sandbox/sdk";
 import type { ExecuteResponse } from "deepagents";
 import { type CommandReference } from "./errors.js";
-export type ExecutionOptions = {
+export type ExecutionOptions = RequestOptions & {
     /** Remote execution budget. Defaults to the runtime's advertised command timeout. */
     timeoutMs?: number;
-    /** Command-status polling budget, excluding log download; never extends TTL. */
+    /** Total observation budget, including final log download; never extends TTL. */
     observationTimeoutMs?: number;
     /** Combined UTF-8 log limit, excluding a fixed termination notice. Default 64 KiB; at most 1 MiB. */
     maxOutputBytes?: number;
     /** Must be absolute. This is a working directory, not a security boundary. */
     cwd?: string;
-    /** Stops observation. It does not kill the remote command. */
+    /** Cancels local requests/observation. It does not kill the remote command. */
     signal?: AbortSignal;
     /** Persist the acknowledged reference before waiting. Never receives credentials. */
     onCommandStarted?: (reference: CommandReference) => void | Promise<void>;
@@ -25,8 +25,8 @@ export declare function executionOptions(sandbox: HarakiriSandbox, options: Exec
     timeoutMs: number;
     observationTimeoutMs: number;
     maxOutputBytes: number;
-    /** Stops observation. It does not kill the remote command. */
     signal?: AbortSignal;
+    requestTimeoutMs?: number;
     /** Persist the acknowledged reference before waiting. Never receives credentials. */
     onCommandStarted?: (reference: CommandReference) => void | Promise<void>;
 };

package/dist/execution.js

@@ -1,3 +1,4 @@
+import { HarakiriWaitTimeoutError } from "@h-sandbox/sdk";
 import { HarakiriExecutionError } from "./errors.js";
 export function positiveInteger(name, value, maximum = Number.MAX_SAFE_INTEGER) {
     if (!Number.isSafeInteger(value) || value < 1 || value > maximum) {
@@ -10,9 +11,11 @@ export function executionOptions(sandbox, options) {
     if (!cwd.startsWith("/") || cwd.includes("\0"))
         throw new TypeError("cwd must be an absolute path without NUL characters.");
     const timeoutMs = positiveInteger("timeoutMs", options.timeoutMs ?? sandbox.runtimeMetadata.limits.commandTimeoutMs);
+    if (options.requestTimeoutMs !== undefined)
+        positiveInteger("requestTimeoutMs", options.requestTimeoutMs, 2_147_483_647);
     return {
         ...options, cwd, timeoutMs,
-        observationTimeoutMs: positiveInteger("observationTimeoutMs", options.observationTimeoutMs ?? timeoutMs + 10_000),
+        observationTimeoutMs: positiveInteger("observationTimeoutMs", options.observationTimeoutMs ?? timeoutMs + 10_000, 2_147_483_647),
         maxOutputBytes: positiveInteger("maxOutputBytes", options.maxOutputBytes ?? 65_536, 1_048_576)
     };
 }
@@ -54,13 +57,33 @@ export async function observeCommand(sandbox, reference, options) {
     }
     try {
         options.signal?.throwIfAborted();
+        const deadline = Date.now() + options.observationTimeoutMs;
         const { command } = await sandbox.processes.wait(reference.commandId, {
             statuses: ["succeeded", "failed", "killed"],
             timeoutMs: options.observationTimeoutMs,
+            requestTimeoutMs: options.requestTimeoutMs,
             signal: options.signal
         });
         options.signal?.throwIfAborted();
-        const logs = await sandbox.processes.logs(reference.commandId);
+        const remainingMs = deadline - Date.now();
+        const timeout = () => new HarakiriWaitTimeoutError("Observation deadline elapsed during log retrieval. Reconnect using the command reference.", "command", reference.commandId, command.status);
+        if (remainingMs <= 0)
+            throw timeout();
+        const controller = new AbortController();
+        const signal = options.signal ? AbortSignal.any([options.signal, controller.signal]) : controller.signal;
+        const timer = setTimeout(() => controller.abort(timeout()), remainingMs);
+        let logs;
+        try {
+            logs = await sandbox.processes.logs(reference.commandId, {
+                signal, requestTimeoutMs: options.requestTimeoutMs
+            });
+            signal.throwIfAborted();
+            if (Date.now() >= deadline)
+                throw timeout();
+        }
+        finally {
+            clearTimeout(timer);
+        }
         options.signal?.throwIfAborted();
         const result = commandOutput(logs, options.maxOutputBytes);
         const notice = terminationNotice(command);

package/dist/lifecycle.js

@@ -11,11 +11,13 @@ export async function withHarakiriSandbox(client, input, task, options = {}) {
     const cleanupTimeoutMs = positiveInteger("cleanupTimeoutMs", options.cleanupTimeoutMs ?? 90_000);
     options.backend?.signal?.throwIfAborted();
     // Retain the accepted handle before readiness so failures still enter cleanup.
-    const sandbox = await client.sandboxes.create({ ...input, wait: false });
+    const sandbox = await client.sandboxes.create({ ...input, wait: false }, {
+        signal: options.backend?.signal, requestTimeoutMs: options.backend?.requestTimeoutMs
+    });
     let result;
     const failures = [];
     try {
-        await sandbox.wait({ timeoutMs: readinessTimeoutMs, signal: options.backend?.signal });
+        await sandbox.wait({ timeoutMs: readinessTimeoutMs, signal: options.backend?.signal, requestTimeoutMs: options.backend?.requestTimeoutMs });
         const backend = new HarakiriSandboxBackend(sandbox, options.backend);
         result = await task({ sandbox, backend });
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@h-sandbox/deepagents",
-  "version": "0.1.0-rc.0",
+  "version": "0.1.0-rc.2",
   "description": "Deep Agents sandbox backend for the Harakiri control plane.",
   "license": "Apache-2.0",
   "type": "module",
@@ -30,18 +30,21 @@
     "LICENSE"
   ],
   "peerDependencies": {
-    "@h-sandbox/sdk": "0.5.0-rc.11",
+    "@h-sandbox/sdk": "0.5.0-rc.12",
     "deepagents": "1.14.0"
   },
   "devDependencies": {
     "deepagents": "1.14.0",
     "@langchain/core": "1.2.12",
     "@langchain/langgraph": "1.4.17",
+    "@langchain/langgraph-checkpoint-postgres": "1.0.5",
+    "@types/pg": "8.20.0",
     "langchain": "1.5.11",
     "langsmith": "0.9.0",
+    "pg": "8.21.0",
     "zod": "4.4.3",
     "tsx": "^4.23.13",
-    "@h-sandbox/sdk": "0.5.0-rc.11"
+    "@h-sandbox/sdk": "0.5.0-rc.12"
   },
   "scripts": {
     "clean": "rm -rf dist",