toolpack-sdk 3.3.0 → 3.5.0

package/README.md

@@ -574,6 +574,48 @@ 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`.
+
+### Stopping a request
+
+Pass an `AbortSignal` as `signal` on a request. A stop takes effect at once, also in the middle of a provider call, a rate limit wait, or a tool.
+
+```typescript
+const controller = new AbortController();
+stopButton.onclick = () => controller.abort(); // or a timeout, a newer message
+
+for await (const chunk of sdk.stream({ model, messages, signal: controller.signal })) {
+  if (chunk.finish_reason === 'aborted') break; // stopped: what arrived before is kept
+  process.stdout.write(chunk.delta);
+}
+```
+
+- `stream()` ends without throwing; its last chunk has `finish_reason: 'aborted'`
+- `generate()` rejects with an `AbortedError` (`name` is `'AbortError'`, exported from the package root)
+- Tools that have not started are not run. A tool can read `ctx.signal` to end its own long work early, for example `fetch(url, { signal: ctx.signal })`
+
+### 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 +1218,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 +1292,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)
@@ -1316,7 +1358,7 @@ interface CompletionResponse {
 interface CompletionChunk {
   delta: string;
   usage?: Usage;
-  finish_reason?: 'stop' | 'length' | 'tool_calls' | 'content_filter' | 'error';
+  finish_reason?: 'stop' | 'length' | 'tool_calls' | 'content_filter' | 'error' | 'aborted'; // 'aborted': stopped by the request's signal
   tool_calls?: ToolCallResult[];
 }