@looopy-ai/core 1.0.1

package/dist/tools/artifact-tools.js

@@ -0,0 +1,277 @@
+import { z } from 'zod';
+import { ArtifactScheduler } from '../stores';
+import { localTools, tool } from './local-tools';
+async function trackArtifactInState(taskId, artifactId, taskStateStore) {
+    const state = await taskStateStore.load(taskId);
+    if (!state)
+        return;
+    if (!state.artifactIds.includes(artifactId)) {
+        state.artifactIds.push(artifactId);
+        await taskStateStore.save(taskId, state);
+    }
+}
+export function createArtifactTools(artifactStore, taskStateStore) {
+    const scheduledStore = new ArtifactScheduler(artifactStore);
+    return localTools([
+        tool('create_file_artifact', 'Create a new file artifact for streaming text or binary content. Use append_file_chunk to add content. Set override=true to replace existing artifact.', z.object({
+            artifactId: z
+                .string()
+                .describe('Unique identifier for the artifact (e.g., "report-2025", "analysis-results")'),
+            name: z.string().optional().describe('Human-readable name for the artifact'),
+            description: z.string().optional().describe('Description of the artifact content'),
+            mimeType: z
+                .string()
+                .optional()
+                .default('text/plain')
+                .describe('MIME type of the content (e.g., "text/plain", "text/markdown")'),
+            encoding: z
+                .enum(['utf-8', 'base64'])
+                .optional()
+                .default('utf-8')
+                .describe('Content encoding'),
+            override: z
+                .boolean()
+                .optional()
+                .default(false)
+                .describe('Set to true to replace an existing artifact with the same ID'),
+        }), async (params, context) => {
+            await scheduledStore.createFileArtifact({
+                artifactId: params.artifactId,
+                taskId: context.taskId,
+                contextId: context.contextId,
+                name: params.name,
+                description: params.description,
+                mimeType: params.mimeType,
+                encoding: params.encoding,
+                override: params.override,
+            });
+            await trackArtifactInState(context.taskId, params.artifactId, taskStateStore);
+            return {
+                artifactId: params.artifactId,
+                type: 'file',
+                status: 'building',
+                message: params.override
+                    ? 'File artifact reset. Use append_file_chunk to add content.'
+                    : 'File artifact created. Use append_file_chunk to add content.',
+            };
+        }),
+        tool('append_file_chunk', 'Append a chunk of content to a file artifact. Call multiple times to stream content.', z.object({
+            artifactId: z.string().describe('The artifact ID to append to'),
+            content_chunk: z.string().describe('Content chunk to append to the file'),
+            isLastChunk: z
+                .boolean()
+                .optional()
+                .default(false)
+                .describe('Set to true on the final chunk to mark artifact as complete'),
+        }), async (params, context) => {
+            await scheduledStore.appendFileChunk(context.contextId, params.artifactId, params.content_chunk, {
+                isLastChunk: params.isLastChunk,
+            });
+            return {
+                artifactId: params.artifactId,
+                chunkAdded: true,
+                complete: params.isLastChunk,
+                message: params.isLastChunk
+                    ? 'Final chunk appended. Artifact is complete.'
+                    : 'Chunk appended successfully.',
+            };
+        }),
+        tool('get_file_content', 'Get the complete content of a file artifact', z.object({
+            artifactId: z.string().describe('The artifact ID to retrieve'),
+        }), async (params, context) => {
+            const content = await scheduledStore.getFileContent(context.contextId, params.artifactId);
+            return {
+                artifactId: params.artifactId,
+                content,
+            };
+        }),
+        tool('create_data_artifact', 'Create a data artifact with structured JSON data. Set override=true to replace existing artifact.', z.object({
+            artifactId: z.string().describe('Unique identifier for the artifact'),
+            name: z.string().optional().describe('Human-readable name'),
+            description: z.string().optional().describe('Description of the data'),
+            data: z.record(z.string(), z.unknown()).describe('The structured data object'),
+            override: z
+                .boolean()
+                .optional()
+                .default(false)
+                .describe('Set to true to replace an existing artifact with the same ID'),
+        }), async (params, context) => {
+            await scheduledStore.createDataArtifact({
+                artifactId: params.artifactId,
+                taskId: context.taskId,
+                contextId: context.contextId,
+                name: params.name,
+                description: params.description,
+                override: params.override,
+            });
+            await scheduledStore.writeData(context.contextId, params.artifactId, params.data);
+            await trackArtifactInState(context.taskId, params.artifactId, taskStateStore);
+            return {
+                artifactId: params.artifactId,
+                type: 'data',
+                status: 'complete',
+                message: params.override
+                    ? 'Data artifact reset successfully.'
+                    : 'Data artifact created successfully.',
+            };
+        }),
+        tool('update_data_artifact', 'Update the data content of an existing data artifact', z.object({
+            artifactId: z.string().describe('The artifact ID to update'),
+            data: z.record(z.string(), z.unknown()).describe('The new data object'),
+        }), async (params, context) => {
+            await scheduledStore.writeData(context.contextId, params.artifactId, params.data);
+            return {
+                artifactId: params.artifactId,
+                type: 'data',
+                status: 'complete',
+                message: 'Data artifact updated successfully.',
+            };
+        }),
+        tool('get_data_content', 'Get the content of a data artifact', z.object({
+            artifactId: z.string().describe('The artifact ID to retrieve'),
+        }), async (params, context) => {
+            const data = await scheduledStore.getDataContent(context.contextId, params.artifactId);
+            return {
+                artifactId: params.artifactId,
+                data,
+            };
+        }),
+        tool('get_data_artifact', 'Get the data content of a data artifact', z.object({
+            artifactId: z.string().describe('The artifact ID to retrieve'),
+        }), async (params, context) => {
+            const data = await scheduledStore.getDataContent(context.contextId, params.artifactId);
+            return {
+                artifactId: params.artifactId,
+                data,
+            };
+        }),
+        tool('create_dataset_artifact', 'Create a dataset artifact for tabular data with a schema. Set override=true to replace existing artifact.', z.object({
+            artifactId: z.string().describe('Unique identifier for the dataset'),
+            name: z.string().optional().describe('Human-readable name'),
+            description: z.string().optional().describe('Description of the dataset'),
+            schema: z.object({
+                columns: z.array(z.object({
+                    name: z.string(),
+                    type: z.enum(['string', 'number', 'boolean', 'date', 'json']),
+                    description: z.string().optional(),
+                })),
+            }),
+            override: z
+                .boolean()
+                .optional()
+                .default(false)
+                .describe('Set to true to replace an existing artifact with the same ID'),
+        }), async (params, context) => {
+            await scheduledStore.createDatasetArtifact({
+                artifactId: params.artifactId,
+                taskId: context.taskId,
+                contextId: context.contextId,
+                name: params.name,
+                description: params.description,
+                schema: params.schema,
+                override: params.override,
+            });
+            await trackArtifactInState(context.taskId, params.artifactId, taskStateStore);
+            return {
+                artifactId: params.artifactId,
+                type: 'dataset',
+                status: 'building',
+                message: params.override
+                    ? 'Dataset artifact reset. Use append_dataset_row(s) to add data.'
+                    : 'Dataset artifact created. Use append_dataset_row(s) to add data.',
+            };
+        }),
+        tool('append_dataset_row', 'Append a single row to a dataset artifact', z.object({
+            artifactId: z.string().describe('The dataset artifact ID'),
+            row: z.record(z.string(), z.unknown()).describe('Row data matching the dataset schema'),
+        }), async (params, context) => {
+            await scheduledStore.appendDatasetBatch(context.contextId, params.artifactId, [params.row]);
+            return {
+                artifactId: params.artifactId,
+                rowAdded: true,
+                message: 'Row appended to dataset.',
+            };
+        }),
+        tool('append_dataset_rows', 'Append multiple rows to a dataset artifact', z.object({
+            artifactId: z.string().describe('The dataset artifact ID'),
+            rows: z.array(z.record(z.string(), z.unknown())).describe('Array of rows to append'),
+            isLastBatch: z.boolean().optional().describe('Set to true on the final batch'),
+        }), async (params, context) => {
+            await scheduledStore.appendDatasetBatch(context.contextId, params.artifactId, params.rows, {
+                isLastBatch: params.isLastBatch,
+            });
+            return {
+                artifactId: params.artifactId,
+                rowsAdded: params.rows.length,
+                message: `${params.rows.length} rows appended to dataset.`,
+            };
+        }),
+        tool('get_dataset_rows', 'Get all rows from a dataset artifact', z.object({
+            artifactId: z.string().describe('The dataset artifact ID'),
+        }), async (params, context) => {
+            const rows = await scheduledStore.getDatasetRows(context.contextId, params.artifactId);
+            return {
+                artifactId: params.artifactId,
+                rows,
+                totalRows: rows.length,
+            };
+        }),
+        tool('list_artifacts', 'List all artifacts in the current context, optionally filtered by task', z.object({
+            taskId: z.string().optional().describe('Filter artifacts by task ID'),
+        }), async (params, context) => {
+            const artifactIds = await scheduledStore.listArtifacts(context.contextId, params.taskId);
+            const artifacts = await Promise.all(artifactIds.map((id) => scheduledStore.getArtifact(context.contextId, id)));
+            const validArtifacts = artifacts.filter((a) => a !== null);
+            return {
+                artifacts: validArtifacts.map((a) => ({
+                    artifactId: a.artifactId,
+                    type: a.type,
+                    name: a.name,
+                    taskId: a.taskId,
+                    contextId: a.contextId,
+                    createdAt: a.createdAt,
+                })),
+                totalCount: validArtifacts.length,
+            };
+        }),
+        tool('get_artifact', 'Get metadata for a specific artifact by ID', z.object({
+            artifactId: z.string().describe('The artifact ID to retrieve'),
+        }), async (params, context) => {
+            const artifact = await scheduledStore.getArtifact(context.contextId, params.artifactId);
+            if (!artifact) {
+                throw new Error(`Artifact not found: ${params.artifactId}`);
+            }
+            return {
+                artifactId: artifact.artifactId,
+                type: artifact.type,
+                taskId: artifact.taskId,
+                contextId: artifact.contextId,
+                name: artifact.name,
+                description: artifact.description,
+                status: artifact.status,
+                createdAt: artifact.createdAt,
+                updatedAt: artifact.updatedAt,
+                ...(artifact.type === 'file' && {
+                    mimeType: artifact.mimeType,
+                    encoding: artifact.encoding,
+                    totalChunks: artifact.totalChunks,
+                    totalSize: artifact.totalSize,
+                }),
+                ...(artifact.type === 'dataset' && {
+                    totalRows: artifact.totalSize,
+                    schema: artifact.schema,
+                }),
+            };
+        }),
+        tool('delete_artifact', 'Delete an artifact by ID', z.object({
+            artifactId: z.string().describe('The artifact ID to delete'),
+        }), async (params, context) => {
+            await scheduledStore.deleteArtifact(context.contextId, params.artifactId);
+            return {
+                artifactId: params.artifactId,
+                deleted: true,
+                message: 'Artifact deleted successfully.',
+            };
+        }),
+    ]);
+}

package/dist/tools/client-tool-provider.d.ts

@@ -0,0 +1,25 @@
+import type { ExecutionContext } from '../types/context';
+import { type ToolCall, type ToolDefinition, type ToolProvider, type ToolResult } from '../types/tools';
+export interface ClientToolConfig {
+    tools: unknown;
+    onInputRequired: (toolCall: ToolCall, context: ExecutionContext) => Promise<ToolResult>;
+}
+export declare class ClientToolProvider implements ToolProvider {
+    private readonly tools;
+    private readonly toolNames;
+    private readonly onInputRequired;
+    constructor(config: ClientToolConfig);
+    getTools(): Promise<ToolDefinition[]>;
+    canHandle(toolName: string): boolean;
+    execute(toolCall: ToolCall, context: ExecutionContext): Promise<ToolResult>;
+    getTool(name: string): ToolDefinition | undefined;
+    validateToolArguments(toolCall: ToolCall): {
+        valid: boolean;
+        errors?: string[];
+    };
+    private validateRequiredParams;
+    private validateUnknownParams;
+    private validateParamTypes;
+    private checkParamType;
+    private getJsonSchemaType;
+}

package/dist/tools/client-tool-provider.js

@@ -0,0 +1,139 @@
+import { validateToolDefinitions, } from '../types/tools';
+export class ClientToolProvider {
+    tools;
+    toolNames;
+    onInputRequired;
+    constructor(config) {
+        try {
+            this.tools = validateToolDefinitions(config.tools);
+        }
+        catch (error) {
+            if (error instanceof Error) {
+                throw new Error(`Invalid client tool definitions: ${error.message}`);
+            }
+            throw error;
+        }
+        this.toolNames = new Set(this.tools.map((t) => t.name));
+        if (this.toolNames.size !== this.tools.length) {
+            const names = this.tools.map((t) => t.name);
+            const duplicates = names.filter((name, index) => names.indexOf(name) !== index);
+            throw new Error(`Duplicate tool names: ${duplicates.join(', ')}`);
+        }
+        this.onInputRequired = config.onInputRequired;
+    }
+    async getTools() {
+        return [...this.tools];
+    }
+    canHandle(toolName) {
+        return this.toolNames.has(toolName);
+    }
+    async execute(toolCall, context) {
+        if (!this.canHandle(toolCall.function.name)) {
+            return {
+                toolCallId: toolCall.id,
+                toolName: toolCall.function.name,
+                success: false,
+                result: null,
+                error: `Tool ${toolCall.function.name} not found in client tools`,
+            };
+        }
+        try {
+            if (typeof toolCall.function.arguments !== 'object' || toolCall.function.arguments === null) {
+                return {
+                    toolCallId: toolCall.id,
+                    toolName: toolCall.function.name,
+                    success: false,
+                    result: null,
+                    error: `Invalid tool arguments: must be an object.`,
+                };
+            }
+            const result = await this.onInputRequired(toolCall, context);
+            return result;
+        }
+        catch (error) {
+            return {
+                toolCallId: toolCall.id,
+                toolName: toolCall.function.name,
+                success: false,
+                result: null,
+                error: error instanceof Error ? error.message : String(error),
+            };
+        }
+    }
+    getTool(name) {
+        return this.tools.find((t) => t.name === name);
+    }
+    validateToolArguments(toolCall) {
+        const tool = this.getTool(toolCall.function.name);
+        if (!tool) {
+            return { valid: false, errors: [`Tool ${toolCall.function.name} not found`] };
+        }
+        if (typeof toolCall.function.arguments !== 'object' || toolCall.function.arguments === null) {
+            return {
+                valid: false,
+                errors: ['Arguments are not valid: must be an object.'],
+            };
+        }
+        const args = toolCall.function.arguments;
+        const errors = [];
+        this.validateRequiredParams(tool, args, errors);
+        this.validateUnknownParams(tool, args, errors);
+        this.validateParamTypes(tool, args, errors);
+        return errors.length > 0 ? { valid: false, errors } : { valid: true };
+    }
+    validateRequiredParams(tool, args, errors) {
+        const required = tool.parameters.required || [];
+        for (const param of required) {
+            if (!(param in args)) {
+                errors.push(`Missing required parameter: ${param}`);
+            }
+        }
+    }
+    validateUnknownParams(tool, args, errors) {
+        if (tool.parameters.additionalProperties === false) {
+            const allowedParams = new Set(Object.keys(tool.parameters.properties));
+            for (const param of Object.keys(args)) {
+                if (!allowedParams.has(param)) {
+                    errors.push(`Unknown parameter: ${param}`);
+                }
+            }
+        }
+    }
+    validateParamTypes(tool, args, errors) {
+        for (const [paramName, paramValue] of Object.entries(args)) {
+            const schema = tool.parameters.properties[paramName];
+            if (!schema)
+                continue;
+            const type = schema.type;
+            if (!type)
+                continue;
+            const typeError = this.checkParamType(paramName, paramValue, type);
+            if (typeError) {
+                errors.push(typeError);
+            }
+        }
+    }
+    checkParamType(paramName, paramValue, expectedType) {
+        const actualType = this.getJsonSchemaType(paramValue);
+        if (expectedType === 'integer') {
+            if (actualType !== 'number') {
+                return `Parameter ${paramName} has wrong type: expected integer, got ${actualType}`;
+            }
+            if (!Number.isInteger(paramValue)) {
+                return `Parameter ${paramName} must be an integer, got: ${paramValue}`;
+            }
+            return null;
+        }
+        if (actualType !== expectedType) {
+            return `Parameter ${paramName} has wrong type: expected ${expectedType}, got ${actualType}`;
+        }
+        return null;
+    }
+    getJsonSchemaType(value) {
+        if (Array.isArray(value))
+            return 'array';
+        if (value === null)
+            return 'null';
+        return typeof value;
+    }
+}

package/dist/tools/index.d.ts

@@ -0,0 +1,4 @@
+export * from './artifact-tools';
+export * from './client-tool-provider';
+export * from './local-tools';
+export * from './mcp-tool-provider';

package/dist/tools/index.js

@@ -0,0 +1,4 @@
+export * from './artifact-tools';
+export * from './client-tool-provider';
+export * from './local-tools';
+export * from './mcp-tool-provider';

package/dist/tools/local-tools.d.ts

@@ -0,0 +1,13 @@
+import { z } from 'zod';
+import type { ExecutionContext } from '../types/context';
+import type { ToolProvider } from '../types/tools';
+type ToolHandler<TParams> = (params: TParams, context: ExecutionContext) => Promise<unknown> | unknown;
+interface LocalToolDefinition<TSchema extends z.ZodObject> {
+    name: string;
+    description: string;
+    schema: TSchema;
+    handler: ToolHandler<z.infer<TSchema>>;
+}
+export declare function tool<TSchema extends z.ZodObject>(name: string, description: string, schema: TSchema, handler: ToolHandler<z.infer<TSchema>>): LocalToolDefinition<TSchema>;
+export declare function localTools(tools: LocalToolDefinition<z.ZodObject>[]): ToolProvider;
+export {};

package/dist/tools/local-tools.js

@@ -0,0 +1,70 @@
+import { z } from 'zod';
+export function tool(name, description, schema, handler) {
+    return { name, description, schema, handler };
+}
+const zodToJsonSchema = (schema) => {
+    const fullSchema = z.toJSONSchema(schema);
+    const { $schema: _$schema, ...jsonSchema } = fullSchema;
+    if (jsonSchema.type !== 'object' || !jsonSchema.properties) {
+        throw new Error('Tool parameters schema must be a Zod object schema');
+    }
+    return jsonSchema;
+};
+export function localTools(tools) {
+    const toolMap = new Map();
+    for (const tool of tools) {
+        if (toolMap.has(tool.name)) {
+            throw new Error(`Duplicate tool name: ${tool.name}`);
+        }
+        toolMap.set(tool.name, tool);
+    }
+    return {
+        getTools: async () => tools.map((t) => ({
+            name: t.name,
+            description: t.description,
+            parameters: zodToJsonSchema(t.schema),
+        })),
+        canHandle: (toolName) => toolMap.has(toolName),
+        execute: async (toolCall, context) => {
+            const toolDef = toolMap.get(toolCall.function.name);
+            if (!toolDef) {
+                return {
+                    toolCallId: toolCall.id,
+                    toolName: toolCall.function.name,
+                    success: false,
+                    result: null,
+                    error: `Tool ${toolCall.function.name} not found`,
+                };
+            }
+            try {
+                const validatedParams = toolDef.schema.parse(toolCall.function.arguments);
+                const result = await toolDef.handler(validatedParams, context);
+                return {
+                    toolCallId: toolCall.id,
+                    toolName: toolCall.function.name,
+                    success: true,
+                    result,
+                };
+            }
+            catch (error) {
+                if (error instanceof z.ZodError) {
+                    return {
+                        toolCallId: toolCall.id,
+                        toolName: toolCall.function.name,
+                        success: false,
+                        result: null,
+                        error: `Invalid arguments: ${error.issues.map((e) => `${e.path.join('.')}: ${e.message}`).join(', ')}`,
+                    };
+                }
+                const err = error instanceof Error ? error : new Error(String(error));
+                return {
+                    toolCallId: toolCall.id,
+                    toolName: toolCall.function.name,
+                    success: false,
+                    result: null,
+                    error: err.message,
+                };
+            }
+        },
+    };
+}

package/dist/tools/mcp-client.d.ts

@@ -0,0 +1,29 @@
+import type { AuthContext } from '../types/context';
+import type { FunctionParameters } from '../types/tools';
+export interface MCPTool {
+    name: string;
+    description: string;
+    inputSchema: FunctionParameters;
+    version?: string;
+}
+export interface MCPToolResponse {
+    result: unknown;
+    executionTime: number;
+}
+export interface MCPClientConfig {
+    baseUrl: string;
+    getHeaders: (authContext?: AuthContext) => Record<string, string>;
+    timeout?: number;
+}
+export declare class MCPClient {
+    private readonly baseUrl;
+    private readonly timeout;
+    private readonly getHeaders;
+    constructor(config: MCPClientConfig);
+    listTools(): Promise<MCPTool[]>;
+    callTool(params: {
+        name: string;
+        arguments: Record<string, unknown>;
+    }, authContext?: AuthContext): Promise<MCPToolResponse>;
+    private request;
+}

package/dist/tools/mcp-client.js

@@ -0,0 +1,62 @@
+const generateId = () => Math.random().toString(36).substring(2);
+export class MCPClient {
+    baseUrl;
+    timeout;
+    getHeaders;
+    constructor(config) {
+        this.baseUrl = config.baseUrl;
+        this.timeout = config.timeout || 30000;
+        this.getHeaders = config.getHeaders;
+    }
+    async listTools() {
+        const response = await this.request({
+            method: 'tools/list',
+            params: {},
+        });
+        return response.tools;
+    }
+    async callTool(params, authContext) {
+        return await this.request({
+            method: 'tools/call',
+            params,
+        }, authContext);
+    }
+    async request(req, authContext) {
+        const controller = new AbortController();
+        const timeoutId = setTimeout(() => controller.abort(), this.timeout);
+        try {
+            const response = await fetch(`${this.baseUrl}/rpc`, {
+                method: 'POST',
+                headers: {
+                    'Content-Type': 'application/json',
+                    ...this.getHeaders(authContext),
+                },
+                body: JSON.stringify({
+                    jsonrpc: '2.0',
+                    id: generateId(),
+                    ...req,
+                }),
+                signal: controller.signal,
+            });
+            clearTimeout(timeoutId);
+            if (!response.ok) {
+                throw new Error(`MCP request failed with status ${response.status}: ${response.statusText}`);
+            }
+            const json = (await response.json());
+            if (json.error) {
+                throw new Error(`MCP error: ${json.error.message} (code: ${json.error.code})`);
+            }
+            if (json.result === undefined) {
+                throw new Error('Invalid MCP response: missing result');
+            }
+            return json.result;
+        }
+        catch (error) {
+            clearTimeout(timeoutId);
+            if (error instanceof Error && error.name === 'AbortError') {
+                throw new Error(`MCP request timed out after ${this.timeout}ms`);
+            }
+            throw error;
+        }
+    }
+}

package/dist/tools/mcp-tool-provider.d.ts

@@ -0,0 +1,22 @@
+import type { AuthContext, ExecutionContext } from '../types/context';
+import type { ToolCall, ToolDefinition, ToolProvider, ToolResult } from '../types/tools';
+export interface MCPProviderConfig {
+    serverId: string;
+    serverUrl: string;
+    timeout?: number;
+    getHeaders: (authContext?: AuthContext) => Record<string, string>;
+}
+export declare const mcp: (config: MCPProviderConfig) => McpToolProvider;
+export declare class McpToolProvider implements ToolProvider {
+    readonly id: string;
+    private readonly client;
+    private toolCache;
+    private cacheExpiry;
+    private readonly cacheTTL;
+    private ongoingRequest;
+    constructor(config: MCPProviderConfig);
+    getTools(): Promise<ToolDefinition[]>;
+    canHandle(toolName: string): boolean;
+    execute(toolCall: ToolCall, context: ExecutionContext): Promise<ToolResult>;
+    private convertMCPTool;
+}