toolpack-sdk 3.2.0 → 3.4.0

package/README.md

@@ -574,6 +574,30 @@ await sdk.loadToolProjects([myToolProject]);
 | `tools` | ToolDefinition[] | ✓ | Array of tool definitions |
 | `dependencies` | Record<string, string> | | npm dependencies (validated at load) |
 
+### Tool Context and `actor`
+
+Every tool's `execute` receives a context as its second argument. Besides `workspaceRoot` and `config`, it carries `ctx.actor`: who the run acts for (for example the signed-in user). The host sets it with the `actor` init option; the model never sees or sets it, so a tool can trust it for per-user data.
+
+```typescript
+const sdk = await Toolpack.init({
+  provider: 'openai',
+  tools: true,
+  actor: { id: 'user_123', kind: 'user' },
+});
+
+// In a tool:
+execute: async (args, ctx) => {
+  const userId = ctx.actor?.id; // undefined when no actor was set
+  // load only this user's data
+}
+```
+
+When one instance serves several people, pass a function (read on every tool call), for example `actor: () => requestStore.getStore() ?? null`.
+
+### Returning files from tools
+
+A tool can return a file by URL with `{ "type": "file", "mimeType": "application/pdf", "url": "https://..." }`. Anthropic and Vertex AI receive it as a native file part, and OpenAI receives images (other files get a placeholder). `data:` URIs keep working as before.
+
 ## Knowledge & RAG (Retrieval-Augmented Generation)
 
 For AI applications that need to search and reference documentation, use the companion `@toolpack-sdk/knowledge` package:
@@ -1176,7 +1200,7 @@ const sdk = await Toolpack.init({
 |--------|------|---------|-------------|
 | `enabled` | boolean | `true` | Enable/disable the tool system entirely |
 | `autoExecute` | boolean | `true` | Auto-execute tool calls from AI |
-| `maxToolRounds` | number | `5` | Max tool execution rounds per request |
+| `maxToolRounds` | number | `5` | Max tool execution rounds per request. When the cap is hit with tools still pending, the model gets one final text-only round to wrap up |
 | `toolChoicePolicy` | string | `"auto"` | `"auto"`, `"required"`, or `"required_for_actions"` |
 | `resultMaxChars` | number | `20000` | Max characters in a tool result |
 | `enabledTools` | string[] | `[]` | Whitelist specific tools (empty = all) |
@@ -1250,7 +1274,7 @@ import { Toolpack } from 'toolpack-sdk';
 //   modeOverrides → configure modes directly via registerMode()
 //   configPath    → configuration is now passed inline to Toolpack.init()
 //
-// Fields: logging, hitl, toolsConfig, toolOverrides (v3.1.0)
+// Fields: logging, hitl, toolsConfig, toolOverrides (v3.1.0), actor and disableToolGuidance (v3.4.0)
 const sdk = await Toolpack.init(config: ToolpackInitConfig): Promise<Toolpack>
 
 // Completions (routes through workflow engine if mode has workflow enabled)