@robota-sdk/agent-tools 3.0.0-beta.8 → 3.0.0-beta.81

package/README.md

@@ -1,6 +1,6 @@
 # @robota-sdk/agent-tools
 
-Tool registry, tool creation infrastructure, and 8 built-in CLI tools for the Robota SDK.
+Tool registry, tool creation infrastructure, 9 built-in CLI tools, sandbox execution ports, and sandbox workspace manifests for the Robota SDK.
 
 ## Installation
 
@@ -18,56 +18,165 @@ Peer dependency: `@robota-sdk/agent-core`
 import { createZodFunctionTool } from '@robota-sdk/agent-tools';
 import { z } from 'zod';
 
-const weatherTool = createZodFunctionTool({
-  name: 'get_weather',
-  description: 'Get current weather for a city',
-  schema: z.object({
+const weatherTool = createZodFunctionTool(
+  'get_weather',
+  'Get current weather for a city',
+  z.object({
     city: z.string().describe('City name'),
   }),
-  handler: async ({ city }) => ({
-    data: JSON.stringify({ city, temperature: 22, condition: 'sunny' }),
-  }),
-});
+  async (args) => JSON.stringify({ city: args['city'], temperature: 22, condition: 'sunny' }),
+);
 ```
 
 ### Use Built-in Tools
 
 ```typescript
-import { bashTool, readTool, globTool, grepTool } from '@robota-sdk/agent-tools';
+import {
+  createBashTool,
+  createReadTool,
+  createGlobTool,
+  createGrepTool,
+} from '@robota-sdk/agent-tools';
 import { Robota } from '@robota-sdk/agent-core';
+import type { IAIProvider } from '@robota-sdk/agent-core';
+
+declare const provider: IAIProvider;
+
+// A file tool is built against an explicit containment root and refuses anything outside it
+// (ARCH-010). There is no ready-made instance to import: one bound at import time can carry no root,
+// and a file tool without a root has no boundary.
+const cwd = process.cwd();
 
 const agent = new Robota({
   name: 'DevAgent',
   aiProviders: [provider],
   defaultModel: { provider: 'anthropic', model: 'claude-sonnet-4-6' },
-  tools: [bashTool, readTool, globTool, grepTool],
+  tools: [
+    createBashTool({ cwd }),
+    createReadTool({ cwd }),
+    createGlobTool({ cwd }),
+    createGrepTool({ cwd }),
+  ],
+});
+```
+
+## Built-in Tools
+
+Every tool that touches the filesystem is a FACTORY taking the containment root it operates in
+(`cwd`, required — ARCH-010). There is no ready-made instance to import: one bound at import time can
+carry no root, and a file tool with no root has no boundary.
+
+| Export                | Tool Name       | Description                                                                   |
+| --------------------- | --------------- | ----------------------------------------------------------------------------- |
+| `createShellTool`     | Shell           | Execute host shell commands; OS-aware (POSIX `sh`/`bash`, Windows PowerShell) |
+| `createBashTool`      | Bash            | Model-familiar alias of `Shell` — same OS-aware implementation                |
+| `createReadTool`      | Read            | Read file contents with line numbers (cat -n)                                 |
+| `createWriteTool`     | Write           | Write content to a file (creates parent dirs)                                 |
+| `createEditTool`      | Edit            | Replace a specific string in a file                                           |
+| `createGlobTool`      | Glob            | Find files matching a glob pattern (fast-glob)                                |
+| `createGrepTool`      | Grep            | Search file contents with regex patterns                                      |
+| `createToolSearchTool` | ToolSearch      | Load withheld (deferred) tool schemas by query or exact name; resident so the model can reach it |
+| `webFetchTool`        | WebFetch        | Fetch URL content (HTML-to-text conversion)                                   |
+| `webSearchTool`       | WebSearch       | Web search via Brave Search API                                               |
+| `askUserQuestionTool` | AskUserQuestion | Model asks the user structured questions (options/multi-select/free text)     |
+
+The last three stay instances: they touch no filesystem, so there is no root to contain them by.
+
+`AskUserQuestion` lets the model ask the user 1–4 structured questions mid-turn through the injected
+ask port (CMD-004); each environment renders it its own way (Ink dialog, web modal, programmatic
+pre-answer), and headless runs get a structured `unavailable` result instead of a hang or a guess.
+
+`Shell` and `Bash` are two registered names for one OS-aware implementation: the shell is resolved per-OS and the tool description names the active OS/shell so the model writes the right syntax (e.g. macOS BSD vs Linux GNU utilities differ).
+
+The sandbox-aware factories (`createBashTool`, `createReadTool`, `createWriteTool`, `createEditTool`) also accept an optional `sandboxClient`; without one they run against the host filesystem, contained by `cwd`.
+
+## Sandbox Execution
+
+`ISandboxClient` is the provider-neutral execution-plane port used by sandbox-aware built-in tools:
+
+<!-- doc-example-skip: requires the optional e2b dependency -->
+
+```typescript
+import { E2BSandboxClient, createBashTool, createReadTool } from '@robota-sdk/agent-tools';
+import { Sandbox } from 'e2b';
+
+const e2b = await Sandbox.create();
+const sandboxClient = new E2BSandboxClient({ sandbox: e2b });
+
+// `cwd` is required even with a sandbox client: it is the root inside the sandbox, and the host
+// path guard still applies to any tool that falls through to the host filesystem.
+const cwd = '/workspace';
+const bashTool = createBashTool({ sandboxClient, cwd });
+const readTool = createReadTool({ sandboxClient, cwd });
+```
+
+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.
+
+### Workspace Manifests
+
+`IWorkspaceManifest` declares the fresh sandbox workspace before a session starts. Paths are workspace-relative and cannot escape the target root.
+
+<!-- doc-example-skip: requires the optional e2b dependency -->
+
+```typescript
+import { applyWorkspaceManifest, E2BSandboxClient } from '@robota-sdk/agent-tools';
+import { Sandbox } from 'e2b';
+
+const sandbox = await Sandbox.create();
+const sandboxClient = new E2BSandboxClient({ sandbox });
+
+await applyWorkspaceManifest(sandboxClient, {
+  entries: {
+    'task.md': { type: 'file', content: 'Analyze this repository.\n' },
+    repo: { type: 'gitRepo', url: 'https://github.com/example/project.git', ref: 'main' },
+    output: { type: 'dir' },
+  },
 });
 ```
 
-## Built-in Tools (8)
+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.
+
+## Edit and Write Safety
 
-| Export          | Tool Name | Description                          |
-| --------------- | --------- | ------------------------------------ |
-| `bashTool`      | Bash      | Execute shell commands               |
-| `readTool`      | Read      | Read file contents with line numbers |
-| `writeTool`     | Write     | Write content to a file              |
-| `editTool`      | Edit      | Replace a specific string in a file  |
-| `globTool`      | Glob      | Find files matching a glob pattern   |
-| `grepTool`      | Grep      | Search file contents with regex      |
-| `webFetchTool`  | WebFetch  | Fetch URL content (HTML-to-text)     |
-| `webSearchTool` | WebSearch | Web search via Brave Search API      |
+Recent file tool updates keep write/edit behavior atomic and make Edit tool results easier for higher layers to display. Atomic replacements preserve existing target mode bits, so executable scripts remain executable after Write or Edit updates. The Edit tool returns line metadata for changed regions, allowing the CLI to render concise context hunks instead of dumping full files or opaque summaries.
 
 ## Tool Infrastructure
 
-| Export                  | Description                                            |
-| ----------------------- | ------------------------------------------------------ |
-| `ToolRegistry`          | Central tool registration and schema lookup            |
-| `FunctionTool`          | JS function tool with Zod schema validation            |
-| `createFunctionTool`    | Factory for creating function tools                    |
-| `createZodFunctionTool` | Factory with Zod validation and JSON Schema conversion |
-| `OpenAPITool`           | Tool generated from OpenAPI specification              |
-| `zodToJsonSchema`       | Converts Zod schemas to JSON Schema format             |
+| Export                   | Description                                                |
+| ------------------------ | ---------------------------------------------------------- |
+| `ToolRegistry`           | Central tool registration and schema lookup                |
+| `FunctionTool`           | JS function tool with Zod schema validation                |
+| `createFunctionTool`     | Factory for creating function tools                        |
+| `createZodFunctionTool`  | Factory with Zod validation and JSON Schema conversion     |
+| `IToolInvocationResult`  | Result type for built-in CLI tool invocations              |
+| `ISandboxClient`         | Provider-neutral sandbox execution port                    |
+| `IWorkspaceManifest`     | Declarative sandbox workspace setup contract               |
+| `applyWorkspaceManifest` | Generic manifest applicator for sandbox clients            |
+| `E2BSandboxClient`       | Adapter for E2B-compatible sandbox instances and snapshots |
+| `InMemorySandboxClient`  | Deterministic sandbox client for tests                     |
+
+## IToolInvocationResult Shape
+
+```typescript
+interface IToolInvocationResult {
+  success: boolean;
+  output: string;
+  error?: string;
+  exitCode?: number;
+  startLine?: number; // Start line number of the edit in the original file (Edit tool only)
+}
+```
+
+`IToolInvocationResult` is the inner result type used by built-in tools. It is serialized to JSON and placed inside the `IToolResult.data` field before being returned to the Robota execution loop.
+
+## Dependencies
+
+| Dependency               | Kind | Purpose                                                |
+| ------------------------ | ---- | ------------------------------------------------------ |
+| `@robota-sdk/agent-core` | Peer | Abstract tool base class, tool interfaces, event types |
+| `fast-glob`              | Prod | High-performance glob matching for the Glob tool       |
+| `zod`                    | Prod | Schema validation for function tool parameters         |
 
 ## License
 
-MIT
+Robota is dual-licensed under the [GNU AGPL-3.0](../../LICENSE) or a [commercial license](../../COMMERCIAL.md). See [LICENSING.md](../../LICENSING.md).

package/dist/browser/browser.d.ts

@@ -0,0 +1,67 @@
+import { FunctionTool, IToolSchema, TToolExecutor, TToolParameters, TUniversalValue } from "@robota-sdk/agent-core";
+import { TypeOf, ZodType } from "zod";
+//#region src/types/tool-result.d.ts
+/**
+ * Result returned by a CLI tool invocation
+ */
+interface IToolInvocationResult {
+  success: boolean;
+  output: string;
+  error?: string;
+  exitCode?: number;
+  /** Start line number of the edit in the original file (Edit tool only) */
+  startLine?: number;
+}
+//#endregion
+//#region src/implementations/function-tool.d.ts
+/**
+ * Helper function to create a function tool from a simple function
+ */
+declare function createFunctionTool(name: string, description: string, parameters: IToolSchema['parameters'], fn: TToolExecutor): FunctionTool;
+/**
+ * What a tool declares about itself beyond its callable shape (CLI-1990).
+ *
+ * Optional, and omission is a declaration too: a tool that says nothing is RESIDENT — its schema is
+ * sent on every request, which is what every tool in the tree does today.
+ */
+interface IFunctionToolResidencyOptions {
+  /**
+   * Withhold this tool's schema from the model until it is loaded by `ToolSearch` or forced by a
+   * `toolChoice`. Only honoured while the tool-search policy is engaged, so declaring it on a small
+   * tool set costs nothing.
+   */
+  deferLoading?: boolean;
+}
+/**
+ * Helper function to create a function tool from Zod schema
+ */
+declare function createZodFunctionTool<S extends ZodType>(name: string, description: string, zodSchema: S, fn: TToolExecutor<TypeOf<S>>, residency?: IFunctionToolResidencyOptions): FunctionTool;
+//#endregion
+//#region src/implementations/function-tool/types.d.ts
+/**
+ * Parameter type validation options
+ */
+interface IFunctionToolValidationOptions {
+  strict?: boolean;
+  allowUnknown?: boolean;
+  validateTypes?: boolean;
+}
+/**
+ * Tool execution metadata
+ */
+interface IFunctionToolExecutionMetadata {
+  executionTime: number;
+  toolName: string;
+  parameters: TToolParameters;
+}
+/**
+ * Tool result with metadata
+ */
+interface IFunctionToolResult {
+  success: boolean;
+  data: TUniversalValue;
+  metadata?: IFunctionToolExecutionMetadata;
+}
+//#endregion
+export { type IFunctionToolExecutionMetadata, type IFunctionToolResult, type IFunctionToolValidationOptions, type IToolInvocationResult, createFunctionTool, createZodFunctionTool };
+//# sourceMappingURL=browser.d.ts.map

package/dist/browser/browser.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"browser.d.ts","names":[],"sources":["../../src/types/tool-result.ts","../../src/implementations/function-tool.ts","../../src/implementations/function-tool/types.ts"],"mappings":";;;;;;UAGiB;EACf;EACA;EACA;EACA;;EAEA;;;;;;;iBCKc,mBACd,cACA,qBACA,YAAY,2BACZ,IAAI,gBACH;;;;;;;UAgBc;;;;;;EAMf;;;;;iBAMc,sBAAsB,UAAU,SAC9C,cACA,qBACA,WAAW,GACX,IAAI,cAAc,OAAO,KACzB,YAAW,gCACV;;;;;;UC7Cc;EACf;EACA;EACA;;;;;UAMe;EACf;EACA;EACA,YAAY;;;;;UAMG;EACf;EACA,MAAM;EACN,WAAW"}

package/dist/browser/browser.js

@@ -0,0 +1,2 @@
+import{FunctionTool as e,ValidationError as t,zodToJsonSchema as n}from"@robota-sdk/agent-core";function r(t,n,r,i){return new e({name:t,description:n,parameters:r},i)}function i(r,i,a,o,s={}){return new e({name:r,description:i,parameters:n(a),...s.deferLoading!==void 0&&{deferLoading:s.deferLoading}},async(e,n)=>{let r=a.safeParse(e);if(!r.success)throw new t(`Zod validation failed: ${r.error}`);let i=await o(r.data,n);return typeof i==`string`?i:JSON.stringify(i)})}export{r as createFunctionTool,i as createZodFunctionTool};
+//# sourceMappingURL=browser.js.map

package/dist/browser/browser.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"browser.js","names":[],"sources":["../../src/implementations/function-tool.ts"],"sourcesContent":["import { FunctionTool, ValidationError, zodToJsonSchema } from '@robota-sdk/agent-core';\n\nimport type { IToolExecutionContext, TToolExecutor, TToolParameters } from '@robota-sdk/agent-core';\nimport type { IToolSchema } from '@robota-sdk/agent-core';\nimport type { TUniversalValue } from '@robota-sdk/agent-core';\nimport type { TypeOf, ZodType } from 'zod';\n\n// The concrete `FunctionTool` class is owned by @robota-sdk/agent-core (DATA-005 SSOT).\n// These factories construct core's `FunctionTool`; agent-tools owns only the factories\n// and the Zod-flavored wrapper.\n\n/**\n * Helper function to create a function tool from a simple function\n */\nexport function createFunctionTool(\n  name: string,\n  description: string,\n  parameters: IToolSchema['parameters'],\n  fn: TToolExecutor,\n): FunctionTool {\n  const schema: IToolSchema = {\n    name,\n    description,\n    parameters,\n  };\n\n  return new FunctionTool(schema, fn);\n}\n\n/**\n * What a tool declares about itself beyond its callable shape (CLI-1990).\n *\n * Optional, and omission is a declaration too: a tool that says nothing is RESIDENT — its schema is\n * sent on every request, which is what every tool in the tree does today.\n */\nexport interface IFunctionToolResidencyOptions {\n  /**\n   * Withhold this tool's schema from the model until it is loaded by `ToolSearch` or forced by a\n   * `toolChoice`. Only honoured while the tool-search policy is engaged, so declaring it on a small\n   * tool set costs nothing.\n   */\n  deferLoading?: boolean;\n}\n\n/**\n * Helper function to create a function tool from Zod schema\n */\nexport function createZodFunctionTool<S extends ZodType>(\n  name: string,\n  description: string,\n  zodSchema: S,\n  fn: TToolExecutor<TypeOf<S>>,\n  residency: IFunctionToolResidencyOptions = {},\n): FunctionTool {\n  // Use comprehensive Zod to JSON schema conversion\n  const parameters = zodToJsonSchema(zodSchema);\n\n  const schema: IToolSchema = {\n    name,\n    description,\n    parameters,\n    // Spread rather than assigned: an absent marker must stay ABSENT, not become `undefined`, so a\n    // resident tool's schema is byte-identical to what it was before residency existed.\n    ...(residency.deferLoading !== undefined && { deferLoading: residency.deferLoading }),\n  };\n\n  // Wrap the function with validation and ensure proper parameter handling\n  const wrappedFn: TToolExecutor = async (\n    parameters: TToolParameters,\n    context?: IToolExecutionContext,\n  ): Promise<TUniversalValue> => {\n    // Use Zod for runtime validation — the executor receives the PARSED, schema-typed value\n    // (SDK-009): the runtime guarantee and the compile-time type now flow together.\n    const parseResult = zodSchema.safeParse(parameters);\n    if (!parseResult.success) {\n      throw new ValidationError(`Zod validation failed: ${parseResult.error}`);\n    }\n\n    const result = await fn(parseResult.data as TypeOf<S>, context);\n    // Ensure result is always a string for consistency with core package\n    return typeof result === 'string' ? result : JSON.stringify(result);\n  };\n\n  return new FunctionTool(schema, wrappedFn);\n}\n\n// zodToJsonSchema function moved to Facade pattern schema-converter module\n"],"mappings":"gGAcA,SAAgB,EACd,EACA,EACA,EACA,EACc,CAOd,OAAO,IAAI,EAAa,CALtB,OACA,cACA,YAG2B,EAAG,CAAE,CACpC,CAoBA,SAAgB,EACd,EACA,EACA,EACA,EACA,EAA2C,CAAC,EAC9B,CA8Bd,OAAO,IAAI,EAAa,CAzBtB,OACA,cACA,WALiB,EAAgB,CAKxB,EAGT,GAAI,EAAU,eAAiB,IAAA,IAAa,CAAE,aAAc,EAAU,YAAa,CAoB7D,EAAQ,MAf9B,EACA,IAC6B,CAG7B,IAAM,EAAc,EAAU,UAAU,CAAU,EAClD,GAAI,CAAC,EAAY,QACf,MAAM,IAAI,EAAgB,0BAA0B,EAAY,OAAO,EAGzE,IAAM,EAAS,MAAM,EAAG,EAAY,KAAmB,CAAO,EAE9D,OAAO,OAAO,GAAW,SAAW,EAAS,KAAK,UAAU,CAAM,CACpE,CAEyC,CAC3C"}