@inferencesh/sdk 0.1.3 → 0.2.0

package/dist/tool-builder.js

@@ -0,0 +1,212 @@
+"use strict";
+/**
+ * Tool Builder - Fluent API for defining agent tools
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.internalTools = exports.webhookTool = exports.agentTool = exports.appTool = exports.tool = exports.optional = exports.array = exports.object = exports.enumOf = exports.boolean = exports.integer = exports.number = exports.string = void 0;
+const types_1 = require("./types");
+// =============================================================================
+// Schema Builders
+// =============================================================================
+const string = (description) => ({ type: 'string', description });
+exports.string = string;
+const number = (description) => ({ type: 'number', description });
+exports.number = number;
+const integer = (description) => ({ type: 'integer', description });
+exports.integer = integer;
+const boolean = (description) => ({ type: 'boolean', description });
+exports.boolean = boolean;
+const enumOf = (values, description) => ({ type: 'string', enum: values, description });
+exports.enumOf = enumOf;
+const object = (properties, description) => ({ type: 'object', properties, description });
+exports.object = object;
+const array = (items, description) => ({ type: 'array', items, description });
+exports.array = array;
+const optional = (schema) => ({ ...schema, optional: true });
+exports.optional = optional;
+// =============================================================================
+// JSON Schema Generator
+// =============================================================================
+function toJsonSchema(params) {
+    const properties = {};
+    const required = [];
+    for (const [key, schema] of Object.entries(params)) {
+        const prop = { type: schema.type };
+        if (schema.description)
+            prop.description = schema.description;
+        if (schema.enum)
+            prop.enum = schema.enum;
+        if (schema.properties) {
+            const nested = toJsonSchema(schema.properties);
+            prop.properties = nested.properties;
+        }
+        if (schema.items) {
+            const itemSchema = toJsonSchema({ _item: schema.items });
+            prop.items = itemSchema.properties['_item'];
+        }
+        properties[key] = prop;
+        if (!schema.optional)
+            required.push(key);
+    }
+    return { type: 'object', properties, required };
+}
+// =============================================================================
+// Tool Builders
+// =============================================================================
+class ToolBuilder {
+    constructor(name) {
+        this.desc = '';
+        this.params = {};
+        this.approval = false;
+        this.name = name;
+    }
+    describe(description) {
+        this.desc = description;
+        return this;
+    }
+    display(name) {
+        this.displayName = name;
+        return this;
+    }
+    param(name, schema) {
+        this.params[name] = schema;
+        return this;
+    }
+    requireApproval() {
+        this.approval = true;
+        return this;
+    }
+}
+class ClientToolBuilder extends ToolBuilder {
+    build() {
+        return {
+            name: this.name,
+            display_name: this.displayName || this.name,
+            description: this.desc,
+            type: types_1.ToolTypeClient,
+            require_approval: this.approval || undefined,
+            client: { input_schema: toJsonSchema(this.params) },
+        };
+    }
+}
+class AppToolBuilder extends ToolBuilder {
+    constructor(name, appRef) {
+        super(name);
+        this.appRef = appRef;
+    }
+    build() {
+        const [ns, rest] = this.appRef.split('/');
+        const [appName, version] = rest?.split('@') || [];
+        return {
+            name: this.name,
+            display_name: this.displayName || this.name,
+            description: this.desc,
+            type: types_1.ToolTypeApp,
+            require_approval: this.approval || undefined,
+            app: { id: `${ns}/${appName}`, version_id: version },
+        };
+    }
+}
+class AgentToolBuilder extends ToolBuilder {
+    constructor(name, agentRef) {
+        super(name);
+        this.agentRef = agentRef;
+    }
+    build() {
+        const [ns, rest] = this.agentRef.split('/');
+        const [agentName, version] = rest?.split('@') || [];
+        return {
+            name: this.name,
+            display_name: this.displayName || this.name,
+            description: this.desc,
+            type: types_1.ToolTypeAgent,
+            require_approval: this.approval || undefined,
+            agent: { id: `${ns}/${agentName}`, version_id: version },
+        };
+    }
+}
+class WebhookToolBuilder extends ToolBuilder {
+    constructor(name, url) {
+        super(name);
+        this.url = url;
+    }
+    secret(key) {
+        this.secretKey = key;
+        return this;
+    }
+    build() {
+        return {
+            name: this.name,
+            display_name: this.displayName || this.name,
+            description: this.desc,
+            type: types_1.ToolTypeHook,
+            require_approval: this.approval || undefined,
+            hook: { url: this.url, secret: this.secretKey, input_schema: toJsonSchema(this.params) },
+        };
+    }
+}
+// =============================================================================
+// Public API
+// =============================================================================
+/** Create a client tool (executed by SDK consumer) */
+const tool = (name) => new ClientToolBuilder(name);
+exports.tool = tool;
+/** Create an app tool (runs another inference app) */
+const appTool = (name, appRef) => new AppToolBuilder(name, appRef);
+exports.appTool = appTool;
+/** Create an agent tool (delegates to sub-agent) */
+const agentTool = (name, agentRef) => new AgentToolBuilder(name, agentRef);
+exports.agentTool = agentTool;
+/** Create a webhook tool (calls external URL) */
+const webhookTool = (name, url) => new WebhookToolBuilder(name, url);
+exports.webhookTool = webhookTool;
+// =============================================================================
+// Internal Tools Builder
+// =============================================================================
+class InternalToolsBuilder {
+    constructor() {
+        this.config = {};
+    }
+    /** Enable plan tools (Create, Update, Load) */
+    plan(enabled = true) {
+        this.config.plan = enabled;
+        return this;
+    }
+    /** Enable memory tools (Set, Get, GetAll) */
+    memory(enabled = true) {
+        this.config.memory = enabled;
+        return this;
+    }
+    /** Enable widget tools (UI, HTML) - top-level only */
+    widget(enabled = true) {
+        this.config.widget = enabled;
+        return this;
+    }
+    /** Enable finish tool - sub-agents only */
+    finish(enabled = true) {
+        this.config.finish = enabled;
+        return this;
+    }
+    /** Enable all internal tools */
+    all() {
+        this.config.plan = true;
+        this.config.memory = true;
+        this.config.widget = true;
+        this.config.finish = true;
+        return this;
+    }
+    /** Disable all internal tools */
+    none() {
+        this.config.plan = false;
+        this.config.memory = false;
+        this.config.widget = false;
+        this.config.finish = false;
+        return this;
+    }
+    build() {
+        return this.config;
+    }
+}
+/** Create internal tools configuration */
+const internalTools = () => new InternalToolsBuilder();
+exports.internalTools = internalTools;

package/dist/tool-builder.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/tool-builder.test.js

@@ -0,0 +1,291 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const tool_builder_1 = require("./tool-builder");
+const types_1 = require("./types");
+describe('Schema Helpers', () => {
+    describe('string', () => {
+        it('creates string schema without description', () => {
+            const schema = (0, tool_builder_1.string)();
+            expect(schema).toEqual({ type: 'string' });
+        });
+        it('creates string schema with description', () => {
+            const schema = (0, tool_builder_1.string)('User name');
+            expect(schema).toEqual({ type: 'string', description: 'User name' });
+        });
+    });
+    describe('number', () => {
+        it('creates number schema', () => {
+            expect((0, tool_builder_1.number)()).toEqual({ type: 'number' });
+            expect((0, tool_builder_1.number)('Temperature')).toEqual({ type: 'number', description: 'Temperature' });
+        });
+    });
+    describe('integer', () => {
+        it('creates integer schema', () => {
+            expect((0, tool_builder_1.integer)()).toEqual({ type: 'integer' });
+            expect((0, tool_builder_1.integer)('Age')).toEqual({ type: 'integer', description: 'Age' });
+        });
+    });
+    describe('boolean', () => {
+        it('creates boolean schema', () => {
+            expect((0, tool_builder_1.boolean)()).toEqual({ type: 'boolean' });
+            expect((0, tool_builder_1.boolean)('Is active')).toEqual({ type: 'boolean', description: 'Is active' });
+        });
+    });
+    describe('enumOf', () => {
+        it('creates enum schema', () => {
+            const schema = (0, tool_builder_1.enumOf)(['low', 'medium', 'high']);
+            expect(schema).toEqual({ type: 'string', enum: ['low', 'medium', 'high'] });
+        });
+        it('creates enum schema with description', () => {
+            const schema = (0, tool_builder_1.enumOf)(['a', 'b'], 'Priority level');
+            expect(schema).toEqual({ type: 'string', enum: ['a', 'b'], description: 'Priority level' });
+        });
+    });
+    describe('object', () => {
+        it('creates object schema with nested properties', () => {
+            const schema = (0, tool_builder_1.object)({
+                name: (0, tool_builder_1.string)('Name'),
+                age: (0, tool_builder_1.integer)('Age'),
+            });
+            expect(schema).toEqual({
+                type: 'object',
+                properties: {
+                    name: { type: 'string', description: 'Name' },
+                    age: { type: 'integer', description: 'Age' },
+                },
+            });
+        });
+        it('creates object schema with description', () => {
+            const schema = (0, tool_builder_1.object)({ x: (0, tool_builder_1.number)() }, 'Coordinates');
+            expect(schema.description).toBe('Coordinates');
+        });
+    });
+    describe('array', () => {
+        it('creates array schema', () => {
+            const schema = (0, tool_builder_1.array)((0, tool_builder_1.string)('Tag'));
+            expect(schema).toEqual({
+                type: 'array',
+                items: { type: 'string', description: 'Tag' },
+            });
+        });
+        it('creates array schema with description', () => {
+            const schema = (0, tool_builder_1.array)((0, tool_builder_1.integer)(), 'List of IDs');
+            expect(schema).toEqual({
+                type: 'array',
+                items: { type: 'integer' },
+                description: 'List of IDs',
+            });
+        });
+    });
+    describe('optional', () => {
+        it('marks schema as optional', () => {
+            const schema = (0, tool_builder_1.optional)((0, tool_builder_1.string)('Optional field'));
+            expect(schema).toEqual({ type: 'string', description: 'Optional field', optional: true });
+        });
+        it('preserves original schema properties', () => {
+            const schema = (0, tool_builder_1.optional)((0, tool_builder_1.enumOf)(['a', 'b'], 'Choice'));
+            expect(schema.enum).toEqual(['a', 'b']);
+            expect(schema.optional).toBe(true);
+        });
+    });
+});
+describe('ClientToolBuilder (tool)', () => {
+    it('creates minimal tool', () => {
+        const t = (0, tool_builder_1.tool)('my_tool').build();
+        expect(t).toEqual({
+            name: 'my_tool',
+            display_name: 'my_tool',
+            description: '',
+            type: types_1.ToolTypeClient,
+            require_approval: undefined,
+            client: {
+                input_schema: { type: 'object', properties: {}, required: [] },
+            },
+        });
+    });
+    it('creates tool with description', () => {
+        const t = (0, tool_builder_1.tool)('greet').describe('Says hello').build();
+        expect(t.description).toBe('Says hello');
+    });
+    it('creates tool with display name', () => {
+        const t = (0, tool_builder_1.tool)('get_data').display('Get Data').build();
+        expect(t.display_name).toBe('Get Data');
+    });
+    it('creates tool with parameters', () => {
+        const t = (0, tool_builder_1.tool)('add')
+            .param('a', (0, tool_builder_1.number)('First number'))
+            .param('b', (0, tool_builder_1.number)('Second number'))
+            .build();
+        expect(t.client?.input_schema).toEqual({
+            type: 'object',
+            properties: {
+                a: { type: 'number', description: 'First number' },
+                b: { type: 'number', description: 'Second number' },
+            },
+            required: ['a', 'b'],
+        });
+    });
+    it('handles optional parameters correctly', () => {
+        const t = (0, tool_builder_1.tool)('search')
+            .param('query', (0, tool_builder_1.string)('Search query'))
+            .param('limit', (0, tool_builder_1.optional)((0, tool_builder_1.integer)('Max results')))
+            .build();
+        expect(t.client?.input_schema.required).toEqual(['query']);
+        expect(t.client?.input_schema.properties).toHaveProperty('limit');
+    });
+    it('creates tool with require approval', () => {
+        const t = (0, tool_builder_1.tool)('dangerous').requireApproval().build();
+        expect(t.require_approval).toBe(true);
+    });
+    it('creates tool with nested object parameters', () => {
+        const t = (0, tool_builder_1.tool)('create_user')
+            .param('user', (0, tool_builder_1.object)({
+            name: (0, tool_builder_1.string)('Name'),
+            email: (0, tool_builder_1.string)('Email'),
+        }, 'User data'))
+            .build();
+        const schema = t.client?.input_schema;
+        expect(schema?.properties?.user).toMatchObject({
+            type: 'object',
+            properties: {
+                name: { type: 'string', description: 'Name' },
+                email: { type: 'string', description: 'Email' },
+            },
+        });
+    });
+    it('creates tool with array parameters', () => {
+        const t = (0, tool_builder_1.tool)('process_items')
+            .param('items', (0, tool_builder_1.array)((0, tool_builder_1.string)('Item'), 'List of items'))
+            .build();
+        expect(t.client?.input_schema.properties?.items).toMatchObject({
+            type: 'array',
+            items: { type: 'string', description: 'Item' },
+        });
+    });
+});
+describe('AppToolBuilder (appTool)', () => {
+    it('creates app tool with reference', () => {
+        const t = (0, tool_builder_1.appTool)('generate', 'infsh/flux@v1.0')
+            .describe('Generate image')
+            .build();
+        expect(t.type).toBe(types_1.ToolTypeApp);
+        expect(t.app).toEqual({ id: 'infsh/flux', version_id: 'v1.0' });
+        expect(t.description).toBe('Generate image');
+    });
+    it('handles app reference with latest version', () => {
+        const t = (0, tool_builder_1.appTool)('browse', 'my-org/browser@latest').build();
+        expect(t.app).toEqual({ id: 'my-org/browser', version_id: 'latest' });
+    });
+    it('includes parameters', () => {
+        const t = (0, tool_builder_1.appTool)('fetch', 'infsh/fetch@v1')
+            .param('url', (0, tool_builder_1.string)('URL to fetch'))
+            .build();
+        expect(t.name).toBe('fetch');
+        // Note: App tools don't use client input_schema, params are for documentation
+    });
+});
+describe('AgentToolBuilder (agentTool)', () => {
+    it('creates agent tool with reference', () => {
+        const t = (0, tool_builder_1.agentTool)('research', 'acme/researcher@v2')
+            .describe('Research a topic')
+            .build();
+        expect(t.type).toBe(types_1.ToolTypeAgent);
+        expect(t.agent).toEqual({ id: 'acme/researcher', version_id: 'v2' });
+    });
+    it('supports display name and approval', () => {
+        const t = (0, tool_builder_1.agentTool)('coder', 'infsh/code-agent@latest')
+            .display('Code Assistant')
+            .requireApproval()
+            .build();
+        expect(t.display_name).toBe('Code Assistant');
+        expect(t.require_approval).toBe(true);
+    });
+});
+describe('WebhookToolBuilder (webhookTool)', () => {
+    it('creates webhook tool with URL', () => {
+        const t = (0, tool_builder_1.webhookTool)('notify', 'https://api.example.com/webhook')
+            .describe('Send notification')
+            .build();
+        expect(t.type).toBe(types_1.ToolTypeHook);
+        expect(t.hook?.url).toBe('https://api.example.com/webhook');
+        expect(t.description).toBe('Send notification');
+    });
+    it('includes secret key', () => {
+        const t = (0, tool_builder_1.webhookTool)('slack', 'https://hooks.slack.com/services/xxx')
+            .secret('SLACK_SECRET')
+            .build();
+        expect(t.hook?.secret).toBe('SLACK_SECRET');
+    });
+    it('generates input schema for parameters', () => {
+        const t = (0, tool_builder_1.webhookTool)('send', 'https://api.example.com')
+            .param('message', (0, tool_builder_1.string)('Message'))
+            .param('priority', (0, tool_builder_1.optional)((0, tool_builder_1.enumOf)(['low', 'high'])))
+            .build();
+        expect(t.hook?.input_schema).toEqual({
+            type: 'object',
+            properties: {
+                message: { type: 'string', description: 'Message' },
+                priority: { type: 'string', enum: ['low', 'high'] },
+            },
+            required: ['message'],
+        });
+    });
+});
+describe('InternalToolsBuilder (internalTools)', () => {
+    it('creates empty config by default', () => {
+        const config = (0, tool_builder_1.internalTools)().build();
+        expect(config).toEqual({});
+    });
+    it('enables plan tools', () => {
+        const config = (0, tool_builder_1.internalTools)().plan().build();
+        expect(config).toEqual({ plan: true });
+    });
+    it('enables memory tools', () => {
+        const config = (0, tool_builder_1.internalTools)().memory().build();
+        expect(config).toEqual({ memory: true });
+    });
+    it('enables widget tools', () => {
+        const config = (0, tool_builder_1.internalTools)().widget().build();
+        expect(config).toEqual({ widget: true });
+    });
+    it('enables finish tool', () => {
+        const config = (0, tool_builder_1.internalTools)().finish().build();
+        expect(config).toEqual({ finish: true });
+    });
+    it('chains multiple tool enables', () => {
+        const config = (0, tool_builder_1.internalTools)().plan().memory().widget().build();
+        expect(config).toEqual({ plan: true, memory: true, widget: true });
+    });
+    it('enables all tools with all()', () => {
+        const config = (0, tool_builder_1.internalTools)().all().build();
+        expect(config).toEqual({ plan: true, memory: true, widget: true, finish: true });
+    });
+    it('disables all tools with none()', () => {
+        const config = (0, tool_builder_1.internalTools)().none().build();
+        expect(config).toEqual({ plan: false, memory: false, widget: false, finish: false });
+    });
+    it('allows explicit disable', () => {
+        const config = (0, tool_builder_1.internalTools)().plan(false).memory(true).build();
+        expect(config).toEqual({ plan: false, memory: true });
+    });
+});
+describe('Fluent API chaining', () => {
+    it('supports full fluent chain', () => {
+        const t = (0, tool_builder_1.tool)('complex')
+            .display('Complex Tool')
+            .describe('A complex tool with many params')
+            .param('name', (0, tool_builder_1.string)('Name'))
+            .param('count', (0, tool_builder_1.integer)('Count'))
+            .param('options', (0, tool_builder_1.optional)((0, tool_builder_1.object)({
+            verbose: (0, tool_builder_1.boolean)('Verbose mode'),
+            tags: (0, tool_builder_1.array)((0, tool_builder_1.string)('Tag')),
+        })))
+            .requireApproval()
+            .build();
+        expect(t.name).toBe('complex');
+        expect(t.display_name).toBe('Complex Tool');
+        expect(t.description).toBe('A complex tool with many params');
+        expect(t.require_approval).toBe(true);
+        expect(t.client?.input_schema.required).toEqual(['name', 'count']);
+    });
+});