@h-sandbox/deepagents 0.1.0-rc.0

package/LICENSE

@@ -0,0 +1,204 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.
+
+Copyright 2026 Harakiri Sandbox contributors.

package/README.md

@@ -0,0 +1,209 @@
+# Harakiri Sandbox for Deep Agents
+
+An optional TypeScript backend for [Deep Agents](https://docs.langchain.com/oss/javascript/deepagents/sandboxes).
+The framework owns planning and tool selection. Harakiri owns sandbox execution,
+files, lifecycle and policy. Your application owns identity, checkpoints and
+result verification. No framework dependencies are added to the core SDK.
+
+## Start with Deep Agents
+
+The integration point in an existing Deep Agents application is its `backend`:
+
+```ts
+import { createDeepAgent } from "deepagents";
+import { HarakiriSandboxBackend } from "@h-sandbox/deepagents";
+
+// Supply your model and a ready, application-owned Harakiri sandbox.
+const agent = createDeepAgent({
+  model,
+  backend: new HarakiriSandboxBackend(sandbox)
+});
+```
+
+This is a **sandbox-backed agent**: the agent loop, model calls and checkpoints
+run in your application; the framework's shell and filesystem tools run in the
+sandbox. It does not deploy your entire agent process into the sandbox. Custom
+tools you register yourself are not automatically isolated: local shell or file
+callbacks still run on your application host.
+
+For a complete, executable workflow, start with
+[the single-file repository repair](https://github.com/nabilblk/h-sandbox/blob/main/packages/deepagents/examples/run-repair.ts).
+It imports the real Deep Agents SDK, receives a Harakiri backend, fixes a bug,
+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+.
+
+```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" \
+  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.
+
+## Connect an Existing Sandbox
+
+```ts
+import { HarakiriClient } from "@h-sandbox/sdk";
+import { HarakiriSandboxBackend } from "@h-sandbox/deepagents";
+import { createDeepAgent } from "deepagents";
+import { initChatModel } from "langchain/chat_models/universal";
+
+const client = HarakiriClient.fromEnv();
+const modelName = process.env.HARAKIRI_AGENT_MODEL;
+const sandboxId = process.env.HARAKIRI_SANDBOX_ID;
+if (!modelName || !sandboxId) throw new Error("Select a model and an existing sandbox.");
+
+// Install the selected model provider package in this application first.
+const model = await initChatModel(modelName);
+const sandbox = await client.sandboxes.connect(sandboxId);
+await sandbox.wait({ timeoutMs: 180_000 });
+const backend = new HarakiriSandboxBackend(sandbox, { timeoutMs: 60_000 });
+const agent = createDeepAgent({ model, backend, subagents: [], memory: [], skills: [] });
+const result = await agent.invoke({
+  messages: [{ role: "user", content: "Run python3 --version in the sandbox." }]
+}, { recursionLimit: 20 });
+console.log(result.messages.at(-1)?.content);
+// Borrowed sandbox: its application owner decides when to terminate it.
+```
+
+Set `HARAKIRI_API_URL` to your installation and supply `HARAKIRI_API_KEY` through
+your server's secret configuration. Use `sandboxes:read` and `sandboxes:write`.
+Never send that key to a browser, an LLM, graph state or the sandbox. Model
+credentials stay in the application process, not sandbox environment variables.
+Do not log complete graph state: prompts, tool outputs and files may be sensitive.
+
+## Ownership and Recovery
+
+`new HarakiriSandboxBackend(sandbox)` borrows exactly one sandbox. It does not
+create, resume, change egress or terminate it. `backend.reference` contains only
+`sandboxId`; `execute()` returns an additional `{ sandboxId, commandId }` reference.
+Persist references in a tenant/thread-scoped record, then `backend.observe(ref)`
+to observe an existing command without resubmitting it.
+
+For finite, disposable jobs, `withHarakiriSandbox(client, input, task, options)`
+creates once, waits for readiness, runs the task and confirms termination and
+capacity release. It cleans up even when readiness or the task fails. It rejects
+caller idempotency keys and create-time Git source because they can refer to an
+existing resource or obscure ownership. `HarakiriTaskCleanupError` retains the
+sandbox ID and both workload and cleanup failures. TTL remains a crash safety net.
+
+Do not use that helper across a real human approval pause: a paused graph returns
+control, so the helper would clean up. Use an application-owned sandbox instead.
+After a cleanup timeout, `sandbox.waitForTermination()` observes without another DELETE.
+
+## Examples and Verification
+
+From this reviewed checkout after building:
+
+```bash
+# Requires your explicit API URL/key and installed template, not a maintainer URL.
+export HARAKIRI_TEMPLATE="your-linux-template"
+# Install and configure the chosen LangChain model integration first.
+export HARAKIRI_AGENT_MODEL="provider:your-tool-capable-model"
+pnpm --filter @h-sandbox/deepagents exec tsx examples/run-repair.ts
+
+# Secondary, model-free lifecycle example, not an agent-reasoning demo:
+pnpm --filter @h-sandbox/deepagents exec tsx examples/run-checkpoint.ts
+```
+
+`run-repair.ts` is self-contained: model selection, the `createDeepAgent` call,
+fixture setup, invocation, outcome verification and cleanup live in one file.
+Its exported `repairRepository(client, model, template)` is tested through the
+actual framework with scripted model decisions. The initial invoice tests fail
+because quantity is ignored. Expected success is three passing tests, a nonempty
+implementation diff and a confirmed-cleanup sandbox ID. Model claims alone are
+not accepted; editing the test contract also fails verification.
+
+`run-checkpoint.ts` is model-free: two graph instances share an in-memory
+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 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
+inside the sandbox. A local/self-hosted model is supported through LangChain;
+model availability, tool quality and zero cost are not guaranteed.
+Blocked sandbox egress does not block model calls from the application.
+
+Choose a provider integration that supports the framework's text-block tool
+results. `@langchain/ollama@1.3.0` rejects those blocks before making a model
+request, so it is not a drop-in choice for this example. The disposable
+[Ollama acceptance harness](https://github.com/nabilblk/h-sandbox/blob/main/infra/sdk-acceptance/README.md)
+uses strict text-only normalization and `think: false`; this compatibility
+handling is not installed by the Harakiri adapter. Applications can call the
+exported `repairRepository(client, model, template)` with their configured model.
+
+```bash
+pnpm --filter @h-sandbox/deepagents typecheck
+pnpm --filter @h-sandbox/deepagents test
+pnpm --filter @h-sandbox/deepagents test:package
+
+# Optional: creates and deletes one sandbox on an explicitly selected test system.
+HARAKIRI_DEEPAGENTS_ACCEPTANCE=disposable-runtime \
+  pnpm --filter @h-sandbox/deepagents test:native
+```
+
+Local contract tests use the actual Deep Agents and LangGraph libraries with a
+scripted model and synthetic API, not real inference or a runtime. The native
+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.
+
+## Boundaries
+
+- Linux backend: upstream `BaseSandbox` supplies read/list/glob/grep and edit
+  behavior. A working directory is not a filesystem jail. Do not share one
+  sandbox across untrusted tenants or attach untrusted local tools to the agent.
+- Commands are shell strings. Transport/auth failures throw, while nonzero shell
+  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.
+- 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
+  visible to the agent even with empty logs or a tiny limit, without inventing
+  an exit code. Grep preserves truncation and drops a clipped final match. Narrow
+  the query or increase `maxOutputBytes` for byte-limited searches; the upstream
+  generic incomplete-search note only mentions match counts.
+- Files use checksum-verified **buffered** SDK transfers, not streaming. Batches
+  are sequential, at most 64 paths and 32 MiB decoded by default; runtime
+  per-file limits also apply. Transfers are not transactional. Specific path
+  errors return per-file results; unrepresentable failures throw
+  `HarakiriTransferError` with earlier successful paths and the original cause,
+  including cancellation between files. Cancellation before any work remains a
+  direct abort. Download contents from earlier iterations are not retained in
+  the exception; `completedPaths` identifies completed reads, not local writes.
+- Upstream edits are read/modify/write, not atomic. Serialize conflicting writers.
+- Durable graph state is not durable sandbox storage. Use Harakiri workspaces
+  explicitly when files must survive runtime replacement. Reconnect does not
+  revive an expired sandbox or rebind command IDs to another runtime.
+
+See the [technical integration guide](https://github.com/nabilblk/h-sandbox/blob/main/docs/integrations/deepagents.md)
+for contracts, operations and the release checklist. Apache-2.0 licensed.

package/dist/backend.d.ts

@@ -0,0 +1,24 @@
+import { type HarakiriSandbox } from "@h-sandbox/sdk";
+import { BaseSandbox, type FileDownloadResponse, type FileUploadResponse } from "deepagents";
+import { type CommandReference } from "./errors.js";
+import { type ExecutionOptions } from "./execution.js";
+export type HarakiriSandboxBackendOptions = ExecutionOptions & {
+    /** Total decoded bytes per transfer batch. Default 32 MiB, at most 256 MiB. */
+    maxBatchBytes?: number;
+};
+/** A borrowed, single-sandbox backend. Construction never creates or destroys resources. */
+export declare class HarakiriSandboxBackend extends BaseSandbox {
+    #private;
+    constructor(sandbox: HarakiriSandbox, options?: HarakiriSandboxBackendOptions);
+    get id(): string;
+    /** Persist only this reference, scoped to your application's tenant and thread. */
+    get reference(): {
+        sandboxId: string;
+    };
+    execute(command: string): Promise<import("./execution.js").HarakiriExecuteResponse>;
+    /** Read-only command recovery. Never submits a command or resumes a runtime. */
+    observe(reference: CommandReference): Promise<import("./execution.js").HarakiriExecuteResponse>;
+    grep(pattern: string, path?: string, glob?: string | null, maxCount?: number | null): Promise<import("deepagents").GrepResult>;
+    uploadFiles(files: Array<[string, Uint8Array]>): Promise<FileUploadResponse[]>;
+    downloadFiles(paths: string[]): Promise<FileDownloadResponse[]>;
+}

package/dist/backend.js

@@ -0,0 +1,141 @@
+import { HarakiriApiError } from "@h-sandbox/sdk";
+import { BaseSandbox } from "deepagents";
+import { HarakiriExecutionError, HarakiriTransferError } from "./errors.js";
+import { executionOptions, observeCommand, positiveInteger } from "./execution.js";
+import { grepWithOutputStatus } from "./search.js";
+function fileError(error) {
+    if (!(error instanceof HarakiriApiError))
+        return null;
+    switch (error.code) {
+        case "file_not_found": return "file_not_found";
+        case "file_permission_denied": return "permission_denied";
+        case "invalid_file_path": return "invalid_path";
+        default: return null;
+    }
+}
+/** A borrowed, single-sandbox backend. Construction never creates or destroys resources. */
+export class HarakiriSandboxBackend extends BaseSandbox {
+    #sandbox;
+    #execution;
+    #maxBatchBytes;
+    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.");
+        }
+        this.#sandbox = sandbox;
+        this.#execution = executionOptions(sandbox, options);
+        this.#maxBatchBytes = positiveInteger("maxBatchBytes", options.maxBatchBytes ?? 33_554_432, 268_435_456);
+    }
+    get id() { return this.#sandbox.id; }
+    /** Persist only this reference, scoped to your application's tenant and thread. */
+    get reference() { return { sandboxId: this.id }; }
+    async execute(command) {
+        if (!command.trim())
+            throw new TypeError("A nonempty shell command is required.");
+        this.#execution.signal?.throwIfAborted();
+        let reference;
+        try {
+            const process = await this.#sandbox.processes.start({
+                command, cwd: this.#execution.cwd, timeoutMs: this.#execution.timeoutMs, detached: true
+            });
+            reference = process.reference;
+        }
+        catch (cause) {
+            throw new HarakiriExecutionError("submission", this.id, undefined, cause);
+        }
+        try {
+            await this.#execution.onCommandStarted?.({ ...reference });
+        }
+        catch (cause) {
+            throw new HarakiriExecutionError("checkpoint", this.id, reference, cause);
+        }
+        return this.observe(reference);
+    }
+    /** Read-only command recovery. Never submits a command or resumes a runtime. */
+    observe(reference) {
+        return observeCommand(this.#sandbox, reference, this.#execution);
+    }
+    grep(pattern, path = "/", glob = null, maxCount = null) {
+        return grepWithOutputStatus(this, pattern, path, glob, maxCount);
+    }
+    async uploadFiles(files) {
+        this.#checkBatch(files.length);
+        let bytes = 0;
+        for (const [, content] of files) {
+            if (!(content instanceof Uint8Array))
+                throw new TypeError("File content must be Uint8Array.");
+            bytes += content.byteLength;
+            this.#checkBytes(bytes);
+        }
+        const results = [];
+        for (const [path, content] of files) {
+            try {
+                this.#execution.signal?.throwIfAborted();
+                if (!validPath(path)) {
+                    results.push({ path, error: "invalid_path" });
+                    continue;
+                }
+                await this.#sandbox.files.write(this.#path(path), content, { createParents: true });
+                results.push({ path, error: null });
+            }
+            catch (cause) {
+                const error = this.#execution.signal?.aborted ? null : fileError(cause);
+                if (error)
+                    results.push({ path, error });
+                else
+                    throw new HarakiriTransferError("upload", this.id, path, results.filter(r => !r.error).map(r => r.path), cause);
+            }
+        }
+        return results;
+    }
+    async downloadFiles(paths) {
+        this.#checkBatch(paths.length);
+        const results = [];
+        let bytes = 0;
+        for (const path of paths) {
+            try {
+                this.#execution.signal?.throwIfAborted();
+                if (!validPath(path)) {
+                    results.push({ path, content: null, error: "invalid_path" });
+                    continue;
+                }
+                const absolute = this.#path(path);
+                const { file } = await this.#sandbox.files.stat(absolute);
+                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);
+                bytes += content.byteLength;
+                this.#checkBytes(bytes);
+                results.push({ path, content, error: null });
+            }
+            catch (cause) {
+                const error = this.#execution.signal?.aborted ? null : fileError(cause);
+                if (error)
+                    results.push({ path, content: null, error });
+                else
+                    throw new HarakiriTransferError("download", this.id, path, results.filter(r => !r.error).map(r => r.path), cause);
+            }
+        }
+        return results;
+    }
+    #path(path) {
+        return path.startsWith("/") ? path : `${this.#execution.cwd.replace(/\/+$/, "")}/${path}`;
+    }
+    #checkBatch(count) {
+        this.#execution.signal?.throwIfAborted();
+        if (count > 64)
+            throw new RangeError("Transfer batches are limited to 64 files.");
+    }
+    #checkBytes(bytes) {
+        if (!Number.isSafeInteger(bytes) || bytes < 0 || bytes > this.#maxBatchBytes) {
+            throw new RangeError(`Transfer batch exceeds ${this.#maxBatchBytes} decoded bytes.`);
+        }
+    }
+}
+function validPath(path) {
+    return typeof path === "string" && path.length > 0 && !path.includes("\0");
+}

package/dist/errors.d.ts

@@ -0,0 +1,27 @@
+export type CommandReference = Readonly<{
+    sandboxId: string;
+    commandId: string;
+}>;
+/** A failed observation is not permission to submit the command again. */
+export declare class HarakiriExecutionError extends Error {
+    readonly stage: "submission" | "checkpoint" | "observation";
+    readonly sandboxId: string;
+    readonly reference: CommandReference | undefined;
+    readonly name = "HarakiriExecutionError";
+    constructor(stage: "submission" | "checkpoint" | "observation", sandboxId: string, reference: CommandReference | undefined, cause: unknown);
+}
+/** Includes no file contents. Earlier successful uploads must not be replayed blindly. */
+export declare class HarakiriTransferError extends Error {
+    readonly operation: "upload" | "download";
+    readonly sandboxId: string;
+    readonly path: string;
+    readonly completedPaths: readonly string[];
+    readonly name = "HarakiriTransferError";
+    constructor(operation: "upload" | "download", sandboxId: string, path: string, completedPaths: readonly string[], cause: unknown);
+}
+/** Workload and cleanup failures are both retained, including non-Error throws. */
+export declare class HarakiriTaskCleanupError extends AggregateError {
+    readonly sandboxId: string;
+    readonly name = "HarakiriTaskCleanupError";
+    constructor(sandboxId: string, errors: unknown[]);
+}

package/dist/errors.js

@@ -0,0 +1,37 @@
+/** A failed observation is not permission to submit the command again. */
+export class HarakiriExecutionError extends Error {
+    stage;
+    sandboxId;
+    reference;
+    name = "HarakiriExecutionError";
+    constructor(stage, sandboxId, reference, cause) {
+        super(`Sandbox command ${stage} failed. Inspect or reconnect; do not automatically replay the command.`, { cause });
+        this.stage = stage;
+        this.sandboxId = sandboxId;
+        this.reference = reference;
+    }
+}
+/** Includes no file contents. Earlier successful uploads must not be replayed blindly. */
+export class HarakiriTransferError extends Error {
+    operation;
+    sandboxId;
+    path;
+    completedPaths;
+    name = "HarakiriTransferError";
+    constructor(operation, sandboxId, path, completedPaths, cause) {
+        super(`Sandbox file ${operation} failed. Earlier transfers may have completed.`, { cause });
+        this.operation = operation;
+        this.sandboxId = sandboxId;
+        this.path = path;
+        this.completedPaths = completedPaths;
+    }
+}
+/** Workload and cleanup failures are both retained, including non-Error throws. */
+export class HarakiriTaskCleanupError extends AggregateError {
+    sandboxId;
+    name = "HarakiriTaskCleanupError";
+    constructor(sandboxId, errors) {
+        super(errors, "Sandbox cleanup was not confirmed. Retain the sandbox ID for recovery.");
+        this.sandboxId = sandboxId;
+    }
+}

package/dist/execution.d.ts

@@ -0,0 +1,37 @@
+import type { HarakiriSandbox, SandboxCommandLogsResponse, SandboxCommandSummary } from "@h-sandbox/sdk";
+import type { ExecuteResponse } from "deepagents";
+import { type CommandReference } from "./errors.js";
+export type ExecutionOptions = {
+    /** Remote execution budget. Defaults to the runtime's advertised command timeout. */
+    timeoutMs?: number;
+    /** Command-status polling budget, excluding 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. */
+    signal?: AbortSignal;
+    /** Persist the acknowledged reference before waiting. Never receives credentials. */
+    onCommandStarted?: (reference: CommandReference) => void | Promise<void>;
+};
+export type HarakiriExecuteResponse = ExecuteResponse & {
+    reference: CommandReference;
+    finishReason: SandboxCommandSummary["finishReason"];
+};
+export declare function positiveInteger(name: string, value: number, maximum?: number): number;
+export declare function executionOptions(sandbox: HarakiriSandbox, options: ExecutionOptions): {
+    cwd: string;
+    timeoutMs: number;
+    observationTimeoutMs: number;
+    maxOutputBytes: number;
+    /** Stops 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>;
+};
+export declare function commandOutput(logs: SandboxCommandLogsResponse, maxBytes: number): {
+    output: string;
+    truncated: boolean;
+};
+export declare function observeCommand(sandbox: HarakiriSandbox, reference: CommandReference, options: ReturnType<typeof executionOptions>): Promise<HarakiriExecuteResponse>;

package/dist/execution.js

@@ -0,0 +1,78 @@
+import { HarakiriExecutionError } from "./errors.js";
+export function positiveInteger(name, value, maximum = Number.MAX_SAFE_INTEGER) {
+    if (!Number.isSafeInteger(value) || value < 1 || value > maximum) {
+        throw new RangeError(`${name} must be a positive integer no greater than ${maximum}.`);
+    }
+    return value;
+}
+export function executionOptions(sandbox, options) {
+    const cwd = options.cwd ?? sandbox.runtimeMetadata.workdir;
+    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);
+    return {
+        ...options, cwd, timeoutMs,
+        observationTimeoutMs: positiveInteger("observationTimeoutMs", options.observationTimeoutMs ?? timeoutMs + 10_000),
+        maxOutputBytes: positiveInteger("maxOutputBytes", options.maxOutputBytes ?? 65_536, 1_048_576)
+    };
+}
+export function commandOutput(logs, maxBytes) {
+    const separator = logs.stdout && logs.stderr && !logs.stdout.endsWith("\n") ? "\n" : "";
+    let remaining = maxBytes;
+    let output = "";
+    let truncated = Boolean(logs.stdoutTruncated || logs.stderrTruncated);
+    for (const part of [logs.stdout, separator, logs.stderr]) {
+        if (Buffer.byteLength(part) <= remaining) {
+            output += part;
+            remaining -= Buffer.byteLength(part);
+            continue;
+        }
+        truncated = true;
+        // Bound allocation first, then avoid splitting a UTF-8 sequence at the limit.
+        const bytes = Buffer.from(part.slice(0, remaining));
+        let end = Math.min(bytes.length, remaining);
+        while (end > 0 && end < bytes.length && (bytes[end] & 0xc0) === 0x80)
+            end--;
+        output += bytes.subarray(0, end).toString("utf8");
+        remaining = 0;
+    }
+    return { output, truncated };
+}
+function terminationNotice(command) {
+    // Deep Agents displays output and numeric exit codes, not our finishReason field.
+    switch (command.finishReason) {
+        case "timeout": return "[Command timed out; execution did not complete normally.]";
+        case "killed": return "[Command was killed; execution did not complete normally.]";
+        case "error": return "[Command ended with a runtime error; execution did not complete normally.]";
+        default: return command.exitCode === null
+            ? "[Command ended without an exit code; normal completion is unconfirmed.]" : "";
+    }
+}
+export async function observeCommand(sandbox, reference, options) {
+    if (reference.sandboxId !== sandbox.id || !/^cmd_[A-Za-z0-9_-]+$/.test(reference.commandId)) {
+        throw new TypeError("The command reference must belong to this sandbox.");
+    }
+    try {
+        options.signal?.throwIfAborted();
+        const { command } = await sandbox.processes.wait(reference.commandId, {
+            statuses: ["succeeded", "failed", "killed"],
+            timeoutMs: options.observationTimeoutMs,
+            signal: options.signal
+        });
+        options.signal?.throwIfAborted();
+        const logs = await sandbox.processes.logs(reference.commandId);
+        options.signal?.throwIfAborted();
+        const result = commandOutput(logs, options.maxOutputBytes);
+        const notice = terminationNotice(command);
+        return {
+            ...result,
+            output: notice ? `${notice}${result.output ? `\n${result.output}` : ""}` : result.output,
+            exitCode: command.exitCode,
+            finishReason: command.finishReason,
+            reference: { ...reference }
+        };
+    }
+    catch (cause) {
+        throw new HarakiriExecutionError("observation", sandbox.id, { ...reference }, cause);
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1,4 @@
+export { HarakiriSandboxBackend, type HarakiriSandboxBackendOptions } from "./backend.js";
+export { withHarakiriSandbox, type OwnedSandboxInput, type OwnedSandboxOptions } from "./lifecycle.js";
+export { HarakiriExecutionError, HarakiriTransferError, HarakiriTaskCleanupError, type CommandReference } from "./errors.js";
+export type { HarakiriExecuteResponse } from "./execution.js";

package/dist/index.js

@@ -0,0 +1,3 @@
+export { HarakiriSandboxBackend } from "./backend.js";
+export { withHarakiriSandbox } from "./lifecycle.js";
+export { HarakiriExecutionError, HarakiriTransferError, HarakiriTaskCleanupError } from "./errors.js";

package/dist/lifecycle.d.ts

@@ -0,0 +1,13 @@
+import type { CreateSandboxInput, HarakiriClient, HarakiriSandbox } from "@h-sandbox/sdk";
+import { HarakiriSandboxBackend, type HarakiriSandboxBackendOptions } from "./backend.js";
+export type OwnedSandboxInput = Omit<CreateSandboxInput, "idempotencyKey" | "source" | "cleanupOnSourceError" | "wait" | "waitTimeoutMs">;
+export type OwnedSandboxOptions = {
+    backend?: HarakiriSandboxBackendOptions;
+    readinessTimeoutMs?: number;
+    cleanupTimeoutMs?: number;
+};
+/** For one-shot jobs only. Checkpointed applications should manage a borrowed sandbox explicitly. */
+export declare function withHarakiriSandbox<T>(client: HarakiriClient, input: OwnedSandboxInput, task: (context: {
+    sandbox: HarakiriSandbox;
+    backend: HarakiriSandboxBackend;
+}) => Promise<T>, options?: OwnedSandboxOptions): Promise<T>;

package/dist/lifecycle.js

@@ -0,0 +1,35 @@
+import { HarakiriSandboxBackend } from "./backend.js";
+import { HarakiriTaskCleanupError } from "./errors.js";
+import { positiveInteger } from "./execution.js";
+/** For one-shot jobs only. Checkpointed applications should manage a borrowed sandbox explicitly. */
+export async function withHarakiriSandbox(client, input, task, options = {}) {
+    for (const field of ["idempotencyKey", "source", "cleanupOnSourceError", "wait", "waitTimeoutMs"]) {
+        if (field in input)
+            throw new TypeError(`${field} is not supported by the owned-task helper. Use an application-owned sandbox.`);
+    }
+    const readinessTimeoutMs = positiveInteger("readinessTimeoutMs", options.readinessTimeoutMs ?? 180_000);
+    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 });
+    let result;
+    const failures = [];
+    try {
+        await sandbox.wait({ timeoutMs: readinessTimeoutMs, signal: options.backend?.signal });
+        const backend = new HarakiriSandboxBackend(sandbox, options.backend);
+        result = await task({ sandbox, backend });
+    }
+    catch (error) {
+        failures.push(error);
+    }
+    try {
+        // Caller cancellation must not cancel confirmation of the owned runtime's cleanup.
+        await sandbox.kill({ wait: true, timeoutMs: cleanupTimeoutMs });
+    }
+    catch (error) {
+        throw new HarakiriTaskCleanupError(sandbox.id, [...failures, error]);
+    }
+    if (failures.length)
+        throw failures[0];
+    return result;
+}

package/dist/search.d.ts

@@ -0,0 +1,2 @@
+import { BaseSandbox, type GrepResult } from "deepagents";
+export declare function grepWithOutputStatus(backend: BaseSandbox, pattern: string, path: string, glob: string | null, maxCount: number | null): Promise<GrepResult>;

package/dist/search.js

@@ -0,0 +1,42 @@
+import { BaseSandbox } from "deepagents";
+/** Request-local wrapper for 1.14.0, whose BaseSandbox.grep drops execute metadata. */
+class GrepSandbox extends BaseSandbox {
+    backend;
+    truncated = false;
+    error;
+    constructor(backend) {
+        super();
+        this.backend = backend;
+    }
+    get id() { return this.backend.id; }
+    uploadFiles(files) { return this.backend.uploadFiles(files); }
+    downloadFiles(paths) { return this.backend.downloadFiles(paths); }
+    async execute(command) {
+        const result = await this.backend.execute(command);
+        if (result.exitCode !== 0 && result.exitCode !== 1) {
+            this.error = "Search did not complete normally. Inspect the command before relying on its results.";
+            return { ...result, output: "" };
+        }
+        this.truncated ||= result.truncated === true;
+        // Grep emits newline-terminated records. Never parse a clipped tail as a match.
+        return this.truncated
+            ? { ...result, output: result.output.slice(0, result.output.lastIndexOf("\n") + 1) }
+            : result;
+    }
+}
+export async function grepWithOutputStatus(backend, pattern, path, glob, maxCount) {
+    const search = new GrepSandbox(backend);
+    // Reuse upstream quoting, shell construction, match parsing and count limits.
+    const result = await search.grep(pattern, path, glob, maxCount);
+    if (search.error)
+        return { error: search.error };
+    if (!search.truncated)
+        return result;
+    return {
+        ...result, truncated: true,
+        // The pinned framework ignores truncated when there are no matches.
+        ...(!result.matches?.length ? {
+            error: "Search output was truncated before a complete match could be returned. Narrow the pattern or path."
+        } : {})
+    };
+}

package/package.json

@@ -0,0 +1,55 @@
+{
+  "name": "@h-sandbox/deepagents",
+  "version": "0.1.0-rc.0",
+  "description": "Deep Agents sandbox backend for the Harakiri control plane.",
+  "license": "Apache-2.0",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/nabilblk/h-sandbox.git",
+    "directory": "packages/deepagents"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "sideEffects": false,
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "peerDependencies": {
+    "@h-sandbox/sdk": "0.5.0-rc.11",
+    "deepagents": "1.14.0"
+  },
+  "devDependencies": {
+    "deepagents": "1.14.0",
+    "@langchain/core": "1.2.12",
+    "@langchain/langgraph": "1.4.17",
+    "langchain": "1.5.11",
+    "langsmith": "0.9.0",
+    "zod": "4.4.3",
+    "tsx": "^4.23.13",
+    "@h-sandbox/sdk": "0.5.0-rc.11"
+  },
+  "scripts": {
+    "clean": "rm -rf dist",
+    "build": "pnpm --filter @h-sandbox/sdk build && pnpm clean && tsc -p tsconfig.json",
+    "typecheck": "pnpm build && tsc -p tsconfig.tests.json",
+    "lint": "tsc -p tsconfig.json --noEmit",
+    "test": "pnpm build && node --test --import tsx test/*.test.ts",
+    "test:package": "node ../../scripts/test-deepagents-package.mjs",
+    "test:native": "pnpm build && tsx test/native.mts"
+  }
+}