@robota-sdk/agent-tools 3.0.0-beta.60 → 3.0.0-beta.61

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (6) hide show
  1. package/README.md +67 -21
  2. package/dist/node/index.cjs +440 -95
  3. package/dist/node/index.d.cts +170 -15
  4. package/dist/node/index.d.ts +170 -15
  5. package/dist/node/index.js +417 -80
  6. package/package.json +4 -3
package/README.md CHANGED
@@ -1,6 +1,6 @@
1
1
  # @robota-sdk/agent-tools
2
2
 
3
- Tool registry, tool creation infrastructure, and 8 built-in CLI tools for the Robota SDK.
3
+ Tool registry, tool creation infrastructure, 8 built-in CLI tools, sandbox execution ports, and sandbox workspace manifests for the Robota SDK.
4
4
 
5
5
  ## Installation
6
6
 
@@ -46,16 +46,57 @@ const agent = new Robota({
46
46
 
47
47
  ## Built-in Tools (8)
48
48
 
49
- | Export | Tool Name | Description |
50
- | --------------- | --------- | ------------------------------------------------ |
51
- | `bashTool` | Bash | Execute shell commands via `child_process.spawn` |
52
- | `readTool` | Read | Read file contents with line numbers (cat -n) |
53
- | `writeTool` | Write | Write content to a file (creates parent dirs) |
54
- | `editTool` | Edit | Replace a specific string in a file |
55
- | `globTool` | Glob | Find files matching a glob pattern (fast-glob) |
56
- | `grepTool` | Grep | Search file contents with regex patterns |
57
- | `webFetchTool` | WebFetch | Fetch URL content (HTML-to-text conversion) |
58
- | `webSearchTool` | WebSearch | Web search via Brave Search API |
49
+ | Export | Tool Name | Description |
50
+ | --------------- | --------- | --------------------------------------------------------- |
51
+ | `bashTool` | Bash | Execute shell commands via host process or sandbox client |
52
+ | `readTool` | Read | Read file contents with line numbers (cat -n) |
53
+ | `writeTool` | Write | Write content to a file (creates parent dirs) |
54
+ | `editTool` | Edit | Replace a specific string in a file |
55
+ | `globTool` | Glob | Find files matching a glob pattern (fast-glob) |
56
+ | `grepTool` | Grep | Search file contents with regex patterns |
57
+ | `webFetchTool` | WebFetch | Fetch URL content (HTML-to-text conversion) |
58
+ | `webSearchTool` | WebSearch | Web search via Brave Search API |
59
+
60
+ Factory exports (`createBashTool`, `createReadTool`, `createWriteTool`, `createEditTool`) accept an optional `sandboxClient`. The default singleton exports keep host-local behavior.
61
+
62
+ ## Sandbox Execution
63
+
64
+ `ISandboxClient` is the provider-neutral execution-plane port used by sandbox-aware built-in tools:
65
+
66
+ ```typescript
67
+ import { E2BSandboxClient, createBashTool, createReadTool } from '@robota-sdk/agent-tools';
68
+ import { Sandbox } from 'e2b';
69
+
70
+ const e2b = await Sandbox.create();
71
+ const sandboxClient = new E2BSandboxClient({ sandbox: e2b });
72
+
73
+ const bashTool = createBashTool({ sandboxClient });
74
+ const readTool = createReadTool({ sandboxClient });
75
+ ```
76
+
77
+ The package does not depend on E2B directly. `E2BSandboxClient` adapts an E2B-compatible object with `commands.run`, `files.read`, `files.write`, and optional `createSnapshot`, `pause`, `connect`, or factory methods supplied by the application. `snapshot()` returns a provider-owned resumable workspace reference; `restore(snapshotId)` hydrates the adapter from that reference. `InMemorySandboxClient` is available for deterministic tests and contract verification.
78
+
79
+ ### Workspace Manifests
80
+
81
+ `IWorkspaceManifest` declares the fresh sandbox workspace before a session starts. Paths are workspace-relative and cannot escape the target root.
82
+
83
+ ```typescript
84
+ import { applyWorkspaceManifest, E2BSandboxClient } from '@robota-sdk/agent-tools';
85
+ import { Sandbox } from 'e2b';
86
+
87
+ const sandbox = await Sandbox.create();
88
+ const sandboxClient = new E2BSandboxClient({ sandbox });
89
+
90
+ await applyWorkspaceManifest(sandboxClient, {
91
+ entries: {
92
+ 'task.md': { type: 'file', content: 'Analyze this repository.\n' },
93
+ repo: { type: 'gitRepo', url: 'https://github.com/example/project.git', ref: 'main' },
94
+ output: { type: 'dir' },
95
+ },
96
+ });
97
+ ```
98
+
99
+ The generic applicator writes inline/local files, creates directories, and clones Git repositories through `ISandboxClient`. Cloud storage mount entries are part of the contract, but they return `unsupported` until a provider-specific adapter implements native mounting.
59
100
 
60
101
  ## Edit and Write Safety
61
102
 
@@ -63,16 +104,21 @@ Recent file tool updates keep write/edit behavior atomic and make Edit tool resu
63
104
 
64
105
  ## Tool Infrastructure
65
106
 
66
- | Export | Description |
67
- | ----------------------- | ------------------------------------------------------ |
68
- | `ToolRegistry` | Central tool registration and schema lookup |
69
- | `FunctionTool` | JS function tool with Zod schema validation |
70
- | `createFunctionTool` | Factory for creating function tools |
71
- | `createZodFunctionTool` | Factory with Zod validation and JSON Schema conversion |
72
- | `OpenAPITool` | Tool generated from OpenAPI specification |
73
- | `createOpenAPITool` | Factory for creating OpenAPI tools |
74
- | `zodToJsonSchema` | Converts Zod schemas to JSON Schema format |
75
- | `TToolResult` | Result type for built-in CLI tool invocations |
107
+ | Export | Description |
108
+ | ------------------------ | ---------------------------------------------------------- |
109
+ | `ToolRegistry` | Central tool registration and schema lookup |
110
+ | `FunctionTool` | JS function tool with Zod schema validation |
111
+ | `createFunctionTool` | Factory for creating function tools |
112
+ | `createZodFunctionTool` | Factory with Zod validation and JSON Schema conversion |
113
+ | `OpenAPITool` | Tool generated from OpenAPI specification |
114
+ | `createOpenAPITool` | Factory for creating OpenAPI tools |
115
+ | `zodToJsonSchema` | Converts Zod schemas to JSON Schema format |
116
+ | `TToolResult` | Result type for built-in CLI tool invocations |
117
+ | `ISandboxClient` | Provider-neutral sandbox execution port |
118
+ | `IWorkspaceManifest` | Declarative sandbox workspace setup contract |
119
+ | `applyWorkspaceManifest` | Generic manifest applicator for sandbox clients |
120
+ | `E2BSandboxClient` | Adapter for E2B-compatible sandbox instances and snapshots |
121
+ | `InMemorySandboxClient` | Deterministic sandbox client for tests |
76
122
 
77
123
  ## TToolResult Shape
78
124