noumen 0.4.0 → 0.6.0

package/README.md

@@ -375,6 +375,17 @@ The CLI auto-detects a running Ollama server when no cloud API keys are set, so
 
 A `Sandbox` bundles a `VirtualFs` (filesystem) and `VirtualComputer` (shell execution) into one object. Every file read/write and shell command the agent executes goes through these interfaces — swap the sandbox to control what the agent can access.
 
+Local factories live on the root barrel; each remote backend ships on its own subpath so its optional peer dep only enters the module graph when you opt in:
+
+| Factory | Import | Peer dep |
+| --- | --- | --- |
+| `LocalSandbox`, `UnsandboxedLocal` | `noumen` | `@anthropic-ai/sandbox-runtime` (bundled) |
+| `SpritesSandbox` | `noumen/sprites` | — |
+| `DockerSandbox` | `noumen/docker` | `dockerode` |
+| `E2BSandbox` | `noumen/e2b` | `e2b` |
+| `FreestyleSandbox` | `noumen/freestyle` | `freestyle-sandboxes` |
+| `SshSandbox` | `noumen/ssh` | `ssh2` |
+
 ### Local — OS-level sandboxing
 
 Backed by `@anthropic-ai/sandbox-runtime`. Uses macOS Seatbelt or Linux bubblewrap to restrict filesystem and network access at the OS level — no containers needed:
@@ -417,7 +428,7 @@ Run inside a remote [sprites.dev](https://docs.sprites.dev) container. The agent
 **Auto-create** — omit `spriteName` and the sprite is provisioned on first use. The sandbox ID is persisted so sessions can reconnect on resume. `Agent.close()` tears the sprite down automatically:
 
 ```typescript
-import { SpritesSandbox } from "noumen";
+import { SpritesSandbox } from "noumen/sprites";
 
 const sandbox = SpritesSandbox({ token: process.env.SPRITE_TOKEN });
 ```
@@ -442,7 +453,7 @@ pnpm add dockerode
 **Auto-create** — pass `image` instead of `container` and the container is created and started on first use. `Agent.close()` stops and removes it:
 
 ```typescript
-import { DockerSandbox } from "noumen";
+import { DockerSandbox } from "noumen/docker";
 
 const sandbox = DockerSandbox({ image: "node:22", cwd: "/workspace" });
 const agent = new Agent({ provider, sandbox });
@@ -455,7 +466,7 @@ await agent.close();
 
 ```typescript
 import Docker from "dockerode";
-import { DockerSandbox } from "noumen";
+import { DockerSandbox } from "noumen/docker";
 
 const docker = new Docker();
 const container = await docker.createContainer({
@@ -483,7 +494,7 @@ pnpm add e2b
 **Auto-create** — omit `sandbox` and the E2B sandbox is provisioned on first use via the `e2b` SDK. `Agent.close()` kills it:
 
 ```typescript
-import { E2BSandbox } from "noumen";
+import { E2BSandbox } from "noumen/e2b";
 
 const sandbox = E2BSandbox({ template: "base" });
 const agent = new Agent({ provider, sandbox });
@@ -495,7 +506,7 @@ await agent.close(); // kills the E2B sandbox
 
 ```typescript
 import { Sandbox as E2BSandboxSDK } from "e2b";
-import { E2BSandbox } from "noumen";
+import { E2BSandbox } from "noumen/e2b";
 
 const e2b = await E2BSandboxSDK.create();
 
@@ -520,7 +531,7 @@ pnpm add freestyle-sandboxes
 **Auto-create** — omit `vm` and a Freestyle VM is provisioned on first use. `Agent.close()` **suspends** (not deletes) the VM so it can resume instantly later:
 
 ```typescript
-import { FreestyleSandbox } from "noumen";
+import { FreestyleSandbox } from "noumen/freestyle";
 
 const sandbox = FreestyleSandbox({ cwd: "/workspace" });
 const agent = new Agent({ provider, sandbox });
@@ -541,7 +552,7 @@ const sandbox = FreestyleSandbox({
 
 ```typescript
 import { freestyle } from "freestyle-sandboxes";
-import { FreestyleSandbox } from "noumen";
+import { FreestyleSandbox } from "noumen/freestyle";
 
 const { vm } = await freestyle.vms.create({ workdir: "/workspace" });
 
@@ -549,9 +560,53 @@ const sandbox = FreestyleSandbox({ vm, cwd: "/workspace" });
 const agent = new Agent({ provider, sandbox });
 ```
 
+### SSH — remote hosts
+
+Connect to any remote machine over SSH. Uses `ssh2` for command execution (exec channels) and file I/O (SFTP):
+
+```bash
+pnpm add ssh2
+```
+
+**Auto-connect** — provide credentials and the connection is established lazily on `init()`:
+
+```typescript
+import { Agent } from "noumen";
+import { SshSandbox } from "noumen/ssh";
+import fs from "node:fs";
+
+const agent = new Agent({
+  provider,
+  sandbox: SshSandbox({
+    host: "dev.example.com",
+    username: "deploy",
+    privateKey: fs.readFileSync("/home/deploy/.ssh/id_ed25519"),
+    cwd: "/home/deploy/project",
+  }),
+});
+```
+
+Password auth is also supported — pass `password` instead of `privateKey`.
+
+**Explicit** — pass a pre-connected ssh2 Client. The caller owns its lifecycle:
+
+```typescript
+import { Client } from "ssh2";
+import { SshSandbox } from "noumen/ssh";
+
+const client = new Client();
+await new Promise<void>((resolve) => {
+  client.on("ready", resolve);
+  client.connect({ host: "10.0.0.5", username: "root", privateKey: key });
+});
+
+const sandbox = SshSandbox({ client, cwd: "/workspace" });
+const agent = new Agent({ provider, sandbox });
+```
+
 ### Sandbox auto-creation lifecycle
 
-All four remote backends (Sprites, Docker, E2B, Freestyle) support on-demand provisioning. When you omit the container/instance and let the factory auto-create:
+All five remote backends (Sprites, Docker, E2B, Freestyle, SSH) support on-demand provisioning. When you omit the container/instance and let the factory auto-create:
 
 1. **First `createThread()`** calls `sandbox.init()` which provisions the resource
 2. The sandbox ID is persisted locally (`.noumen/sessions/.sandbox-index.json`) so `resumeThread()` can reconnect to the same resource

package/dist/a2a/index.d.ts

@@ -1,10 +1,12 @@
-import { A as Agent } from '../agent-1nFVUP9E.js';
+import { A as Agent } from '../agent-DWE4_P5X.js';
 import { A as AgentSkill, a as AgentCard, T as TaskSendParams, b as Task, c as TaskStreamEvent } from '../types-NIyVwQ4h.js';
 export { d as A2A_METHODS, e as Artifact, D as DataPart, F as FilePart, M as Message, P as Part, f as TaskState, g as TaskStatus, h as TextPart } from '../types-NIyVwQ4h.js';
-import '../types-LrU4LRmX.js';
-import '../types-RPKUTu1k.js';
+import '../types-kiGBF35b.js';
+import '../sandbox-9qeMTNrD.js';
+import '../computer-BPdxSo6X.js';
+import '../types-DhXwOQwD.js';
 import '../types-CD0rUKKT.js';
-import '../cache-DsRqxx6v.js';
+import '../cache-BlBwXXPS.js';
 import '../types-2kTLUCnD.js';
 import '@modelcontextprotocol/sdk/client/index.js';
 import '@modelcontextprotocol/sdk/client/auth.js';

package/dist/acp/index.d.ts

@@ -1,14 +1,16 @@
-import { A as Agent } from '../agent-1nFVUP9E.js';
+import { A as Agent } from '../agent-DWE4_P5X.js';
 import { A as AcpTransport } from '../types-QwfylltH.js';
 export { a as ACP_METHODS, b as AcpCapabilities, c as AcpInitializeParams, d as AcpInitializeResult, e as AcpSessionNewParams, f as AcpSessionPromptParams } from '../types-QwfylltH.js';
-import { V as VirtualFs, R as ReadOptions, F as FileEntry, i as FileStat, j as VirtualComputer, E as ExecOptions, C as CommandResult } from '../types-RPKUTu1k.js';
-import '../types-LrU4LRmX.js';
-import '../cache-DsRqxx6v.js';
+import { a as VirtualFs, R as ReadOptions, F as FileEntry, b as FileStat, V as VirtualComputer, E as ExecOptions, C as CommandResult } from '../computer-BPdxSo6X.js';
+import '../types-kiGBF35b.js';
+import '../sandbox-9qeMTNrD.js';
+import '../types-DhXwOQwD.js';
+import '../types-CD0rUKKT.js';
+import '../cache-BlBwXXPS.js';
 import '../types-2kTLUCnD.js';
 import '@modelcontextprotocol/sdk/client/index.js';
 import '@modelcontextprotocol/sdk/client/auth.js';
 import '@modelcontextprotocol/sdk/shared/auth.js';
-import '../types-CD0rUKKT.js';
 
 /**
  * ACP protocol handler: maps ACP JSON-RPC methods to Agent/Thread APIs.