@aerostack/sdk-openai 0.10.1

package/README.md

@@ -0,0 +1,73 @@
+# @aerostack/sdk-openai
+
+Use [Aerostack](https://aerostack.dev) workspace tools as OpenAI function-calling tools.
+
+## Install
+
+```bash
+npm install @aerostack/sdk-openai openai
+```
+
+## Quick Start
+
+```typescript
+import OpenAI from 'openai';
+import { getTools, handleToolCalls } from '@aerostack/sdk-openai';
+
+const openai = new OpenAI();
+const config = { workspace: 'my-workspace', token: 'mwt_...' };
+
+// 1. Fetch workspace tools in OpenAI format
+const { tools } = await getTools(config);
+
+// 2. Use them in a chat completion
+const response = await openai.chat.completions.create({
+    model: 'gpt-4o',
+    messages: [{ role: 'user', content: 'Create a GitHub issue for the login bug' }],
+    tools,
+});
+
+// 3. Execute tool calls
+const toolCalls = response.choices[0]?.message.tool_calls;
+if (toolCalls) {
+    const results = await handleToolCalls(toolCalls, config);
+    // results are ChatCompletionToolMessageParam[] — append to messages and continue
+}
+```
+
+## Factory Pattern
+
+For reusable clients that cache tool name mappings:
+
+```typescript
+import { createAerostackOpenAI } from '@aerostack/sdk-openai';
+
+const aero = createAerostackOpenAI({ workspace: 'my-workspace', token: 'mwt_...' });
+
+const { tools } = await aero.tools();
+// ... after getting tool_calls from OpenAI ...
+const results = await aero.handleToolCalls(toolCalls);
+```
+
+## API
+
+### `getTools(config)` → `Promise<ToolSet>`
+
+Fetches tools from the workspace and converts to OpenAI format. Returns `{ tools, nameMap, raw }`.
+
+### `handleToolCall(toolCall, config, nameMap?)` → `Promise<ChatCompletionToolMessageParam>`
+
+Executes a single tool call. Errors are returned as tool messages (not thrown).
+
+### `handleToolCalls(toolCalls, config, nameMap?)` → `Promise<ChatCompletionToolMessageParam[]>`
+
+Executes multiple tool calls in parallel.
+
+### `createAerostackOpenAI(config)` → `AerostackOpenAIClient`
+
+Creates a reusable client with cached name mappings.
+
+## Requirements
+
+- `openai` >= 4.20.0
+- An Aerostack workspace with a token (`mwt_...`)

package/dist/commonjs/__tests__/converter.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=converter.test.d.ts.map

package/dist/commonjs/__tests__/converter.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"converter.test.d.ts","sourceRoot":"","sources":["../../../src/__tests__/converter.test.ts"],"names":[],"mappings":""}

package/dist/commonjs/__tests__/converter.test.js

@@ -0,0 +1,149 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const vitest_1 = require("vitest");
+const converter_js_1 = require("../converter.js");
+(0, vitest_1.describe)('convertTool', () => {
+    (0, vitest_1.it)('converts a standard MCP tool to OpenAI format', () => {
+        const mcpTool = {
+            name: 'github__create_issue',
+            description: 'Create a GitHub issue',
+            inputSchema: {
+                type: 'object',
+                properties: {
+                    title: { type: 'string' },
+                    body: { type: 'string' },
+                },
+                required: ['title'],
+            },
+        };
+        const result = (0, converter_js_1.convertTool)(mcpTool);
+        (0, vitest_1.expect)(result).toEqual({
+            type: 'function',
+            function: {
+                name: 'github__create_issue',
+                description: 'Create a GitHub issue',
+                parameters: {
+                    type: 'object',
+                    properties: {
+                        title: { type: 'string' },
+                        body: { type: 'string' },
+                    },
+                    required: ['title'],
+                },
+            },
+        });
+    });
+    (0, vitest_1.it)('handles undefined inputSchema with empty object schema', () => {
+        const mcpTool = {
+            name: 'slack__ping',
+            description: 'Ping Slack',
+        };
+        const result = (0, converter_js_1.convertTool)(mcpTool);
+        (0, vitest_1.expect)(result.function.parameters).toEqual({
+            type: 'object',
+            properties: {},
+        });
+    });
+    (0, vitest_1.it)('handles undefined description', () => {
+        const mcpTool = {
+            name: 'my_tool',
+            inputSchema: { type: 'object', properties: {} },
+        };
+        const result = (0, converter_js_1.convertTool)(mcpTool);
+        (0, vitest_1.expect)(result.function.description).toBeUndefined();
+        (0, vitest_1.expect)(result.function.name).toBe('my_tool');
+    });
+    (0, vitest_1.it)('handles tool with empty description', () => {
+        const mcpTool = {
+            name: 'my_tool',
+            description: '',
+            inputSchema: { type: 'object', properties: {} },
+        };
+        const result = (0, converter_js_1.convertTool)(mcpTool);
+        // Empty string is falsy, so description should be omitted
+        (0, vitest_1.expect)(result.function).not.toHaveProperty('description');
+    });
+});
+(0, vitest_1.describe)('convertTools', () => {
+    (0, vitest_1.it)('converts an array of tools', () => {
+        const tools = [
+            { name: 'tool_a', description: 'A' },
+            { name: 'tool_b', description: 'B' },
+        ];
+        const result = (0, converter_js_1.convertTools)(tools);
+        (0, vitest_1.expect)(result).toHaveLength(2);
+        (0, vitest_1.expect)(result[0].function.name).toBe('tool_a');
+        (0, vitest_1.expect)(result[1].function.name).toBe('tool_b');
+    });
+    (0, vitest_1.it)('handles empty array', () => {
+        (0, vitest_1.expect)((0, converter_js_1.convertTools)([])).toEqual([]);
+    });
+});
+(0, vitest_1.describe)('sanitizeToolName', () => {
+    (0, vitest_1.it)('passes through valid names unchanged', () => {
+        (0, vitest_1.expect)((0, converter_js_1.sanitizeToolName)('github__create_issue')).toBe('github__create_issue');
+        (0, vitest_1.expect)((0, converter_js_1.sanitizeToolName)('my-tool-123')).toBe('my-tool-123');
+    });
+    (0, vitest_1.it)('replaces invalid characters with underscores', () => {
+        (0, vitest_1.expect)((0, converter_js_1.sanitizeToolName)('my.tool.name')).toBe('my_tool_name');
+        (0, vitest_1.expect)((0, converter_js_1.sanitizeToolName)('tool with spaces')).toBe('tool_with_spaces');
+    });
+    (0, vitest_1.it)('throws on empty name', () => {
+        (0, vitest_1.expect)(() => (0, converter_js_1.sanitizeToolName)('')).toThrow(/empty/i);
+    });
+    (0, vitest_1.it)('truncates names over 64 characters', () => {
+        const longName = 'a'.repeat(100);
+        const result = (0, converter_js_1.sanitizeToolName)(longName);
+        (0, vitest_1.expect)(result.length).toBeLessThanOrEqual(64);
+    });
+    (0, vitest_1.it)('produces different truncated names for different long inputs', () => {
+        const name1 = 'server_one__' + 'a'.repeat(100);
+        const name2 = 'server_two__' + 'b'.repeat(100);
+        const result1 = (0, converter_js_1.sanitizeToolName)(name1);
+        const result2 = (0, converter_js_1.sanitizeToolName)(name2);
+        (0, vitest_1.expect)(result1).not.toBe(result2);
+    });
+});
+(0, vitest_1.describe)('buildNameMap', () => {
+    (0, vitest_1.it)('maps sanitized names back to originals', () => {
+        const tools = [
+            { name: 'github__create_issue' },
+            { name: 'slack.post.message' },
+        ];
+        const map = (0, converter_js_1.buildNameMap)(tools);
+        (0, vitest_1.expect)(map.get('github__create_issue')).toBe('github__create_issue');
+        (0, vitest_1.expect)(map.get('slack_post_message')).toBe('slack.post.message');
+    });
+    (0, vitest_1.it)('throws on name collision', () => {
+        const tools = [
+            { name: 'server.create' },
+            { name: 'server_create' },
+        ];
+        (0, vitest_1.expect)(() => (0, converter_js_1.buildNameMap)(tools)).toThrow(/collision/i);
+    });
+    (0, vitest_1.it)('allows duplicate identical names', () => {
+        const tools = [
+            { name: 'my_tool' },
+            { name: 'my_tool' },
+        ];
+        (0, vitest_1.expect)(() => (0, converter_js_1.buildNameMap)(tools)).not.toThrow();
+    });
+});
+(0, vitest_1.describe)('isValidOpenAIName', () => {
+    (0, vitest_1.it)('accepts valid names', () => {
+        (0, vitest_1.expect)((0, converter_js_1.isValidOpenAIName)('my_tool')).toBe(true);
+        (0, vitest_1.expect)((0, converter_js_1.isValidOpenAIName)('github__create_issue')).toBe(true);
+        (0, vitest_1.expect)((0, converter_js_1.isValidOpenAIName)('a-b-c')).toBe(true);
+    });
+    (0, vitest_1.it)('rejects names with invalid characters', () => {
+        (0, vitest_1.expect)((0, converter_js_1.isValidOpenAIName)('my.tool')).toBe(false);
+        (0, vitest_1.expect)((0, converter_js_1.isValidOpenAIName)('tool name')).toBe(false);
+    });
+    (0, vitest_1.it)('rejects names over 64 characters', () => {
+        (0, vitest_1.expect)((0, converter_js_1.isValidOpenAIName)('a'.repeat(65))).toBe(false);
+    });
+    (0, vitest_1.it)('rejects empty string', () => {
+        (0, vitest_1.expect)((0, converter_js_1.isValidOpenAIName)('')).toBe(false);
+    });
+});
+//# sourceMappingURL=converter.test.js.map

package/dist/commonjs/__tests__/converter.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"converter.test.js","sourceRoot":"","sources":["../../../src/__tests__/converter.test.ts"],"names":[],"mappings":"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"}

package/dist/commonjs/__tests__/executor.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=executor.test.d.ts.map

package/dist/commonjs/__tests__/executor.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"executor.test.d.ts","sourceRoot":"","sources":["../../../src/__tests__/executor.test.ts"],"names":[],"mappings":""}

package/dist/commonjs/__tests__/executor.test.js

@@ -0,0 +1,141 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const vitest_1 = require("vitest");
+const executor_js_1 = require("../executor.js");
+const core_1 = require("@aerostack/core");
+function mockClient(callToolResult, shouldThrow = false) {
+    return {
+        callTool: shouldThrow
+            ? vitest_1.vi.fn().mockRejectedValue(callToolResult)
+            : vitest_1.vi.fn().mockResolvedValue(callToolResult),
+    };
+}
+function makeToolCall(overrides = {}) {
+    return {
+        id: 'call_abc123',
+        type: 'function',
+        function: {
+            name: 'github__create_issue',
+            arguments: JSON.stringify({ title: 'Bug fix' }),
+        },
+        ...overrides,
+    };
+}
+(0, vitest_1.describe)('executeToolCall', () => {
+    (0, vitest_1.it)('executes a tool call and returns a tool message', async () => {
+        const client = mockClient({
+            content: [{ type: 'text', text: 'Issue #42 created' }],
+        });
+        const result = await (0, executor_js_1.executeToolCall)(client, makeToolCall());
+        (0, vitest_1.expect)(result).toEqual({
+            role: 'tool',
+            tool_call_id: 'call_abc123',
+            content: 'Issue #42 created',
+        });
+        (0, vitest_1.expect)(client.callTool).toHaveBeenCalledWith('github__create_issue', { title: 'Bug fix' });
+    });
+    (0, vitest_1.it)('uses nameMap to resolve sanitized names', async () => {
+        const client = mockClient({
+            content: [{ type: 'text', text: 'done' }],
+        });
+        const nameMap = new Map([['slack_post_message', 'slack.post.message']]);
+        const tc = makeToolCall({
+            function: { name: 'slack_post_message', arguments: '{}' },
+        });
+        await (0, executor_js_1.executeToolCall)(client, tc, nameMap);
+        (0, vitest_1.expect)(client.callTool).toHaveBeenCalledWith('slack.post.message', {});
+    });
+    (0, vitest_1.it)('returns error message when AerostackError is thrown', async () => {
+        const err = new core_1.AerostackError('MCP server down', 503, -32603, 'req-123');
+        const client = mockClient(err, true);
+        const result = await (0, executor_js_1.executeToolCall)(client, makeToolCall());
+        (0, vitest_1.expect)(result.role).toBe('tool');
+        (0, vitest_1.expect)(result.content).toContain('Error (-32603)');
+        (0, vitest_1.expect)(result.content).toContain('MCP server down');
+    });
+    (0, vitest_1.it)('returns error message for generic errors', async () => {
+        const err = new Error('Network timeout');
+        const client = mockClient(err, true);
+        const result = await (0, executor_js_1.executeToolCall)(client, makeToolCall());
+        (0, vitest_1.expect)(result.content).toBe('Error: Network timeout');
+    });
+    (0, vitest_1.it)('returns error for malformed JSON arguments', async () => {
+        const client = mockClient({});
+        const tc = makeToolCall({
+            function: { name: 'test', arguments: 'not json{' },
+        });
+        const result = await (0, executor_js_1.executeToolCall)(client, tc);
+        (0, vitest_1.expect)(result.content).toContain('Failed to parse tool arguments');
+    });
+    (0, vitest_1.it)('handles empty arguments string', async () => {
+        const client = mockClient({
+            content: [{ type: 'text', text: 'ok' }],
+        });
+        const tc = makeToolCall({
+            function: { name: 'test', arguments: '' },
+        });
+        await (0, executor_js_1.executeToolCall)(client, tc);
+        (0, vitest_1.expect)(client.callTool).toHaveBeenCalledWith('test', {});
+    });
+});
+(0, vitest_1.describe)('executeToolCalls', () => {
+    (0, vitest_1.it)('executes multiple tool calls in parallel', async () => {
+        const client = mockClient({
+            content: [{ type: 'text', text: 'done' }],
+        });
+        const toolCalls = [
+            makeToolCall({ id: 'call_1' }),
+            makeToolCall({ id: 'call_2' }),
+        ];
+        const results = await (0, executor_js_1.executeToolCalls)(client, toolCalls);
+        (0, vitest_1.expect)(results).toHaveLength(2);
+        (0, vitest_1.expect)(results[0].tool_call_id).toBe('call_1');
+        (0, vitest_1.expect)(results[1].tool_call_id).toBe('call_2');
+    });
+    (0, vitest_1.it)('handles empty array', async () => {
+        const client = mockClient({});
+        const results = await (0, executor_js_1.executeToolCalls)(client, []);
+        (0, vitest_1.expect)(results).toEqual([]);
+    });
+});
+(0, vitest_1.describe)('formatToolResult', () => {
+    (0, vitest_1.it)('formats single text content', () => {
+        const result = (0, executor_js_1.formatToolResult)({
+            content: [{ type: 'text', text: 'Hello world' }],
+        });
+        (0, vitest_1.expect)(result).toBe('Hello world');
+    });
+    (0, vitest_1.it)('concatenates multiple text blocks', () => {
+        const result = (0, executor_js_1.formatToolResult)({
+            content: [
+                { type: 'text', text: 'Line 1' },
+                { type: 'text', text: 'Line 2' },
+            ],
+        });
+        (0, vitest_1.expect)(result).toBe('Line 1\nLine 2');
+    });
+    (0, vitest_1.it)('handles binary data blocks', () => {
+        const result = (0, executor_js_1.formatToolResult)({
+            content: [{ type: 'image', data: 'base64data...', mimeType: 'image/png' }],
+        });
+        (0, vitest_1.expect)(result).toContain('image/png');
+        (0, vitest_1.expect)(result).toContain('base64');
+    });
+    (0, vitest_1.it)('prefixes error results', () => {
+        const result = (0, executor_js_1.formatToolResult)({
+            content: [{ type: 'text', text: 'Something failed' }],
+            isError: true,
+        });
+        (0, vitest_1.expect)(result).toBe('Error: Something failed');
+    });
+    (0, vitest_1.it)('handles empty content array', () => {
+        (0, vitest_1.expect)((0, executor_js_1.formatToolResult)({ content: [] })).toBe('Success (no output)');
+    });
+    (0, vitest_1.it)('handles undefined content', () => {
+        (0, vitest_1.expect)((0, executor_js_1.formatToolResult)({})).toBe('Success (no output)');
+    });
+    (0, vitest_1.it)('handles empty content with isError', () => {
+        (0, vitest_1.expect)((0, executor_js_1.formatToolResult)({ content: [], isError: true })).toBe('Error: Tool returned no content');
+    });
+});
+//# sourceMappingURL=executor.test.js.map

package/dist/commonjs/__tests__/executor.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"executor.test.js","sourceRoot":"","sources":["../../../src/__tests__/executor.test.ts"],"names":[],"mappings":"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"}

package/dist/commonjs/converter.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Converts Aerostack McpTool definitions to OpenAI ChatCompletionTool format.
+ */
+import type { ChatCompletionTool } from 'openai/resources/chat/completions';
+import type { McpTool } from '@aerostack/core';
+/**
+ * Convert an array of McpTool definitions to OpenAI ChatCompletionTool format.
+ *
+ * Handles edge cases:
+ * - Undefined inputSchema → empty object schema
+ * - Tool names exceeding 64 chars → truncated with hash suffix
+ * - Invalid characters in tool names → sanitized
+ */
+export declare function convertTools(mcpTools: McpTool[]): ChatCompletionTool[];
+/**
+ * Convert a single McpTool to OpenAI ChatCompletionTool format.
+ */
+export declare function convertTool(tool: McpTool): ChatCompletionTool;
+/**
+ * Sanitize a tool name to comply with OpenAI's function name constraints.
+ * - Replace invalid characters with underscores
+ * - Truncate to 64 characters (keeping a short hash suffix for uniqueness)
+ */
+export declare function sanitizeToolName(name: string): string;
+/**
+ * Build a reverse mapping from sanitized OpenAI tool names back to original MCP tool names.
+ * Needed when tool names are truncated/sanitized.
+ *
+ * Throws if two distinct MCP tool names sanitize to the same OpenAI name,
+ * since that would cause silent wrong-dispatch.
+ */
+export declare function buildNameMap(mcpTools: McpTool[]): Map<string, string>;
+/** Check if a tool name is valid for OpenAI without modification. */
+export declare function isValidOpenAIName(name: string): boolean;
+//# sourceMappingURL=converter.d.ts.map

package/dist/commonjs/converter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"converter.d.ts","sourceRoot":"","sources":["../../src/converter.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,mCAAmC,CAAC;AAC5E,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,iBAAiB,CAAC;AAK/C;;;;;;;GAOG;AACH,wBAAgB,YAAY,CAAC,QAAQ,EAAE,OAAO,EAAE,GAAG,kBAAkB,EAAE,CAEtE;AAED;;GAEG;AACH,wBAAgB,WAAW,CAAC,IAAI,EAAE,OAAO,GAAG,kBAAkB,CAc7D;AAED;;;;GAIG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAerD;AAYD;;;;;;GAMG;AACH,wBAAgB,YAAY,CAAC,QAAQ,EAAE,OAAO,EAAE,GAAG,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAcrE;AAED,qEAAqE;AACrE,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAEvD"}

package/dist/commonjs/converter.js

@@ -0,0 +1,89 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.convertTools = convertTools;
+exports.convertTool = convertTool;
+exports.sanitizeToolName = sanitizeToolName;
+exports.buildNameMap = buildNameMap;
+exports.isValidOpenAIName = isValidOpenAIName;
+/** OpenAI function names must match: ^[a-zA-Z0-9_-]{1,64}$ */
+const OPENAI_FUNCTION_NAME_RE = /^[a-zA-Z0-9_-]{1,64}$/;
+/**
+ * Convert an array of McpTool definitions to OpenAI ChatCompletionTool format.
+ *
+ * Handles edge cases:
+ * - Undefined inputSchema → empty object schema
+ * - Tool names exceeding 64 chars → truncated with hash suffix
+ * - Invalid characters in tool names → sanitized
+ */
+function convertTools(mcpTools) {
+    return mcpTools.map(convertTool);
+}
+/**
+ * Convert a single McpTool to OpenAI ChatCompletionTool format.
+ */
+function convertTool(tool) {
+    const name = sanitizeToolName(tool.name);
+    const parameters = tool.inputSchema
+        ? tool.inputSchema
+        : { type: 'object', properties: {} };
+    return {
+        type: 'function',
+        function: {
+            name,
+            ...(tool.description ? { description: tool.description } : {}),
+            parameters,
+        },
+    };
+}
+/**
+ * Sanitize a tool name to comply with OpenAI's function name constraints.
+ * - Replace invalid characters with underscores
+ * - Truncate to 64 characters (keeping a short hash suffix for uniqueness)
+ */
+function sanitizeToolName(name) {
+    if (!name) {
+        throw new Error('Tool name cannot be empty');
+    }
+    // Replace any character not in [a-zA-Z0-9_-] with underscore
+    let sanitized = name.replace(/[^a-zA-Z0-9_-]/g, '_');
+    // Truncate if over 64 chars — use last 8 chars as hash-like suffix
+    if (sanitized.length > 64) {
+        const hash = simpleHash(name);
+        sanitized = sanitized.slice(0, 55) + '_' + hash;
+    }
+    return sanitized;
+}
+/** Simple string hash producing an 8-char hex string. */
+function simpleHash(str) {
+    let hash = 0;
+    for (let i = 0; i < str.length; i++) {
+        const char = str.charCodeAt(i);
+        hash = ((hash << 5) - hash + char) | 0;
+    }
+    return Math.abs(hash).toString(16).padStart(8, '0').slice(0, 8);
+}
+/**
+ * Build a reverse mapping from sanitized OpenAI tool names back to original MCP tool names.
+ * Needed when tool names are truncated/sanitized.
+ *
+ * Throws if two distinct MCP tool names sanitize to the same OpenAI name,
+ * since that would cause silent wrong-dispatch.
+ */
+function buildNameMap(mcpTools) {
+    const map = new Map();
+    for (const tool of mcpTools) {
+        const sanitized = sanitizeToolName(tool.name);
+        const existing = map.get(sanitized);
+        if (existing && existing !== tool.name) {
+            throw new Error(`Tool name collision: "${tool.name}" and "${existing}" both sanitize to "${sanitized}". ` +
+                `Rename one of the tools in your workspace to avoid ambiguity.`);
+        }
+        map.set(sanitized, tool.name);
+    }
+    return map;
+}
+/** Check if a tool name is valid for OpenAI without modification. */
+function isValidOpenAIName(name) {
+    return OPENAI_FUNCTION_NAME_RE.test(name);
+}
+//# sourceMappingURL=converter.js.map

package/dist/commonjs/converter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"converter.js","sourceRoot":"","sources":["../../src/converter.ts"],"names":[],"mappings":"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"}

package/dist/commonjs/executor.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Executes OpenAI tool calls by proxying them through WorkspaceClient.
+ */
+import type { ChatCompletionMessageToolCall } from 'openai/resources/chat/completions';
+import type { ChatCompletionToolMessageParam } from 'openai/resources/chat/completions';
+import { WorkspaceClient } from '@aerostack/core';
+import type { McpToolResult } from '@aerostack/core';
+export interface WorkspaceConfig {
+    /** Workspace slug */
+    workspace: string;
+    /** Workspace token (mwt_...) */
+    token: string;
+    /** Override gateway base URL */
+    baseUrl?: string;
+}
+/**
+ * Execute a single OpenAI tool call against the Aerostack workspace.
+ *
+ * Returns a ChatCompletionToolMessageParam ready to append to messages.
+ * Errors from the workspace are returned as tool error messages (not thrown),
+ * because OpenAI expects a tool message back even when tools fail.
+ *
+ * @param nameMap - Optional reverse map from sanitized→original tool names
+ */
+export declare function executeToolCall(client: WorkspaceClient, toolCall: ChatCompletionMessageToolCall, nameMap?: Map<string, string>): Promise<ChatCompletionToolMessageParam>;
+/**
+ * Execute multiple tool calls in parallel.
+ *
+ * Returns an array of ChatCompletionToolMessageParam in the same order as input.
+ */
+export declare function executeToolCalls(client: WorkspaceClient, toolCalls: ChatCompletionMessageToolCall[], nameMap?: Map<string, string>): Promise<ChatCompletionToolMessageParam[]>;
+/**
+ * Flatten McpToolResult content array into a single string for OpenAI.
+ *
+ * McpToolResult.content is an array of content blocks (text, base64 data, etc.).
+ * OpenAI tool messages expect a single string. We concatenate text blocks and
+ * JSON-serialize any non-text content.
+ */
+export declare function formatToolResult(result: McpToolResult): string;
+//# sourceMappingURL=executor.d.ts.map

package/dist/commonjs/executor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"executor.d.ts","sourceRoot":"","sources":["../../src/executor.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,OAAO,KAAK,EAAE,6BAA6B,EAAE,MAAM,mCAAmC,CAAC;AACvF,OAAO,KAAK,EAAE,8BAA8B,EAAE,MAAM,mCAAmC,CAAC;AACxF,OAAO,EAAE,eAAe,EAAkB,MAAM,iBAAiB,CAAC;AAClE,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AAErD,MAAM,WAAW,eAAe;IAC5B,qBAAqB;IACrB,SAAS,EAAE,MAAM,CAAC;IAClB,gCAAgC;IAChC,KAAK,EAAE,MAAM,CAAC;IACd,gCAAgC;IAChC,OAAO,CAAC,EAAE,MAAM,CAAC;CACpB;AAED;;;;;;;;GAQG;AACH,wBAAsB,eAAe,CACjC,MAAM,EAAE,eAAe,EACvB,QAAQ,EAAE,6BAA6B,EACvC,OAAO,CAAC,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,GAC9B,OAAO,CAAC,8BAA8B,CAAC,CAkCzC;AAED;;;;GAIG;AACH,wBAAsB,gBAAgB,CAClC,MAAM,EAAE,eAAe,EACvB,SAAS,EAAE,6BAA6B,EAAE,EAC1C,OAAO,CAAC,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,GAC9B,OAAO,CAAC,8BAA8B,EAAE,CAAC,CAI3C;AAED;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,aAAa,GAAG,MAAM,CAkB9D"}