@illalabs/interfaces 0.3.0-canary.2110efe9 → 0.3.0-canary.3f75ecce

package/dist/schemas/telemetryEvents.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"telemetryEvents.d.ts","sourceRoot":"","sources":["../../src/schemas/telemetryEvents.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,wBAAwB,CAAC;AAC3D,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB;;;GAGG;AACH,eAAO,MAAM,mBAAmB,yLAatB,CAAC;AAEX;;GAEG;AACH,eAAO,MAAM,wBAAwB;;;;;;;;;;;;EAInC,CAAC;AAEH;;GAEG;AACH,eAAO,MAAM,oBAAoB;;;;;;;;;;;;;EAE/B,CAAC;AAEH;;GAEG;AACH,eAAO,MAAM,6BAA6B;;;;;;;;;;;;;EAExC,CAAC;AAEH;;GAEG;AACH,eAAO,MAAM,yBAAyB;;;;;;;;;;;;;;;;;;;;;;;;;;EAKpC,CAAC;AAEH;;GAEG;AACH,eAAO,MAAM,uBAAuB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAOlC,CAAC;AAEH;;GAEG;AACH,eAAO,MAAM,wBAAwB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAWnC,CAAC;AAEH;;GAEG;AACH,eAAO,MAAM,qBAAqB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAoBhC,CAAC;AAEH;;GAEG;AACH,eAAO,MAAM,0BAA0B;;;;;;;;;;;;;;;;;;;;;;;;;;EAKrC,CAAC;AAEH;;GAEG;AACH,eAAO,MAAM,mBAAmB;;;;;;;;;;;;;;;;;;;;;;;;;;EAK9B,CAAC;AAEH;;GAEG;AACH,eAAO,MAAM,iBAAiB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAO5B,CAAC;AAEH;;GAEG;AACH,eAAO,MAAM,oBAAoB;;;;;;;;;;;;;;;;;;;;;;;;;;EAK/B,CAAC;AAEH;;GAEG;AACH,eAAO,MAAM,iBAAiB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAO5B,CAAC;AAEH;;;GAGG;AACH,eAAO,MAAM,yBAAyB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAMpC,CAAC;AAEH;;;GAGG;AACH,eAAO,MAAM,oBAAoB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;IAa/B,CAAC;AAqCH;;;;GAIG;AACH,eAAO,MAAM,qBAAqB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAShC,CAAC;AAEH;;GAEG;AACH,eAAO,MAAM,oBAAoB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAQ/B,CAAC;AAEH;;GAEG;AACH,eAAO,MAAM,wBAAwB;;;;;;;;;;;;EAInC,CAAC;AAEH;;;GAGG;AACH,eAAO,MAAM,qBAAqB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;IAIhC,CAAC"}

package/dist/schemas/telemetryEvents.js

@@ -0,0 +1,250 @@
+import { z } from "zod";
+/**
+ * Telemetry event type enum values.
+ * Used to infer TelemetryEventType in types/telemetry.ts
+ */
+export const telemetryEventTypes = [
+    "iteration_start",
+    "iteration_end",
+    "tool_call_batch",
+    "tool_result",
+    "scratchpad_reset",
+    "llm_start",
+    "llm_end",
+    "text_delta",
+    "finish",
+    "error",
+    "connected",
+    "stream_end",
+];
+/**
+ * Base telemetry event schema with common fields
+ */
+export const baseTelemetryEventSchema = z.object({
+    requestId: z.string(),
+    type: z.enum(telemetryEventTypes),
+    timestamp: z.number().optional(),
+});
+/**
+ * Connected event schema - emitted when connected to telemetry stream
+ */
+export const connectedEventSchema = baseTelemetryEventSchema.extend({
+    type: z.literal("connected"),
+});
+/**
+ * Stream end telemetry event schema - emitted when stream ends
+ */
+export const streamEndTelemetryEventSchema = baseTelemetryEventSchema.extend({
+    type: z.literal("stream_end"),
+});
+/**
+ * Iteration start event schema - emitted when an iteration starts
+ */
+export const iterationStartEventSchema = baseTelemetryEventSchema.extend({
+    type: z.literal("iteration_start"),
+    data: z.object({
+        iteration: z.number(),
+    }),
+});
+/**
+ * Iteration end event schema - emitted when an iteration ends
+ */
+export const iterationEndEventSchema = baseTelemetryEventSchema.extend({
+    type: z.literal("iteration_end"),
+    data: z.object({
+        iteration: z.number(),
+        hasToolCalls: z.boolean(),
+        shouldContinue: z.boolean(),
+    }),
+});
+/**
+ * Tool call batch event schema - emitted when tool calls are batched for execution
+ */
+export const toolCallBatchEventSchema = baseTelemetryEventSchema.extend({
+    type: z.literal("tool_call_batch"),
+    data: z.object({
+        iteration: z.number(),
+        tools: z.array(z.object({
+            toolCallId: z.string(),
+            toolName: z.string(),
+        })),
+    }),
+});
+/**
+ * Tool result event schema - emitted when a tool execution completes
+ */
+export const toolResultEventSchema = baseTelemetryEventSchema.extend({
+    type: z.literal("tool_result"),
+    data: z.discriminatedUnion("status", [
+        z.object({
+            toolCallId: z.string(),
+            toolName: z.string(),
+            status: z.literal("pending"),
+        }),
+        z.object({
+            toolCallId: z.string(),
+            toolName: z.string(),
+            status: z.literal("success"),
+        }),
+        z.object({
+            toolCallId: z.string(),
+            toolName: z.string(),
+            status: z.literal("failure"),
+            error: z.string(),
+        }),
+    ]),
+});
+/**
+ * Scratchpad reset event schema - emitted when the scratchpad is reset
+ */
+export const scratchpadResetEventSchema = baseTelemetryEventSchema.extend({
+    type: z.literal("scratchpad_reset"),
+    data: z.object({
+        reason: z.string(),
+    }),
+});
+/**
+ * LLM start event schema - emitted when LLM generation starts
+ */
+export const llmStartEventSchema = baseTelemetryEventSchema.extend({
+    type: z.literal("llm_start"),
+    data: z.object({
+        iteration: z.number(),
+    }),
+});
+/**
+ * LLM end event schema - emitted when LLM generation ends
+ */
+export const llmEndEventSchema = baseTelemetryEventSchema.extend({
+    type: z.literal("llm_end"),
+    data: z.object({
+        iteration: z.number(),
+        hasText: z.boolean(),
+        toolCallCount: z.number(),
+    }),
+});
+/**
+ * Text delta event schema - emitted when a text chunk is received from LLM
+ */
+export const textDeltaEventSchema = baseTelemetryEventSchema.extend({
+    type: z.literal("text_delta"),
+    data: z.object({
+        delta: z.string(),
+    }),
+});
+/**
+ * Finish event schema - emitted when orchestration finishes
+ */
+export const finishEventSchema = baseTelemetryEventSchema.extend({
+    type: z.literal("finish"),
+    data: z.object({
+        totalIterations: z.number(),
+        hasPendingTools: z.boolean(),
+        hasToolErrors: z.boolean(),
+    }),
+});
+/**
+ * Error telemetry event schema - emitted when an error occurs.
+ * The data field is always present per the ErrorEvent type definition.
+ */
+export const errorTelemetryEventSchema = baseTelemetryEventSchema.extend({
+    type: z.literal("error"),
+    data: z.object({
+        message: z.string(),
+        code: z.string().optional(),
+    }),
+});
+/**
+ * Schema for validating telemetry events.
+ * Discriminated union using the "type" field.
+ */
+export const telemetryEventSchema = z.discriminatedUnion("type", [
+    connectedEventSchema,
+    streamEndTelemetryEventSchema,
+    iterationStartEventSchema,
+    iterationEndEventSchema,
+    toolCallBatchEventSchema,
+    toolResultEventSchema,
+    scratchpadResetEventSchema,
+    llmStartEventSchema,
+    llmEndEventSchema,
+    textDeltaEventSchema,
+    finishEventSchema,
+    errorTelemetryEventSchema,
+]);
+/**
+ * Message schema for result events.
+ * Uses z.custom<ModelMessage>() to ensure type compatibility with the AI SDK's
+ * ModelMessage type. Runtime validation of the message structure happens at the
+ * API layer; this schema trusts the structure and preserves the correct TypeScript type.
+ */
+const messageSchema = z.custom();
+/**
+ * Pending tool call schema for result events
+ */
+const pendingToolCallSchema = z.object({
+    toolCallId: z.string(),
+    toolName: z.string(),
+    toolInput: z.unknown(),
+});
+/**
+ * Tool error schema for result events
+ */
+const toolErrorSchema = z.object({
+    toolCallId: z.string(),
+    toolName: z.string(),
+    error: z.string(),
+});
+/**
+ * Incomplete tool call schema for result events
+ */
+const incompleteToolCallSchema = z.object({
+    toolCallId: z.string(),
+    toolName: z.string(),
+    toolInput: z.unknown().optional(),
+});
+/**
+ * Schema for validating result events from the streaming endpoint.
+ * Uses type: "result" as discriminator for consistency with other event schemas.
+ * Also includes status: 200 for backward compatibility with CoreApiChatSuccessResponse.
+ */
+export const resultEventDataSchema = z.object({
+    type: z.literal("result"),
+    status: z.literal(200),
+    messages: z.array(messageSchema),
+    text: z.string(),
+    pendingTools: z.array(pendingToolCallSchema).optional(),
+    incompleteTools: z.array(incompleteToolCallSchema).optional(),
+    toolErrors: z.array(toolErrorSchema).optional(),
+    requestId: z.string(),
+});
+/**
+ * Schema for validating error events from the streaming endpoint
+ */
+export const errorEventDataSchema = z.object({
+    type: z.literal("error"),
+    requestId: z.string(),
+    timestamp: z.number().optional(),
+    data: z.object({
+        message: z.string(),
+        code: z.string().optional(),
+    }),
+});
+/**
+ * Schema for validating stream_end events from the streaming endpoint
+ */
+export const streamEndEventDataSchema = z.object({
+    type: z.literal("stream_end"),
+    requestId: z.string(),
+    timestamp: z.number().optional(),
+});
+/**
+ * Unified discriminated union for all stream event data types.
+ * Uses "type" as the discriminator field for runtime validation.
+ */
+export const streamEventDataSchema = z.discriminatedUnion("type", [
+    resultEventDataSchema,
+    errorEventDataSchema,
+    streamEndEventDataSchema,
+]);
+//# sourceMappingURL=telemetryEvents.js.map

package/dist/schemas/telemetryEvents.js.map

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

package/dist/tools/IllaToolError.d.ts

@@ -0,0 +1,113 @@
+import type { IllaToolErrorData, IllaToolExecutionErrorData, IllaToolInputErrorData } from "../internal.js";
+/**
+ * Represents an error that occurred during tool call validation or execution.
+ * This is a structured error class that distinguishes between input validation
+ * errors and execution errors.
+ *
+ * @example
+ * ```ts
+ * // Create an input validation error
+ * const inputError = IllaToolError.input('call-123', 'tokenTransfer', [
+ *   { path: 'amount', message: 'Amount is required' }
+ * ]);
+ *
+ * // Create an execution error
+ * const execError = IllaToolError.execution('call-123', 'tokenTransfer', 'Network timeout');
+ * ```
+ */
+export declare class IllaToolError {
+    readonly id: string;
+    readonly name: string;
+    readonly data: IllaToolErrorData;
+    /**
+     * Creates a new IllaToolError instance
+     * @param id - The tool call ID this error is associated with
+     * @param name - The name of the tool/action that errored
+     * @param data - The structured error data
+     */
+    private constructor();
+    /**
+     * The type of error ("input" or "execution")
+     */
+    get type(): "input" | "execution";
+    /**
+     * Creates an input validation error
+     * @param id - The tool call ID
+     * @param name - The tool/action name
+     * @param errors - Array of validation errors with path and message
+     * @returns A new IllaToolError representing input validation failure
+     */
+    static input(id: string, name: string, errors: Array<{
+        path: string;
+        message: string;
+    }>): IllaToolError;
+    /**
+     * Creates an execution error
+     * @param id - The tool call ID
+     * @param name - The tool/action name
+     * @param message - Human-readable error message
+     * @param details - Optional additional error details
+     * @returns A new IllaToolError representing execution failure
+     */
+    static execution(id: string, name: string, message: string, details?: unknown): IllaToolError;
+    /**
+     * Parses and validates unknown input to create an IllaToolError instance.
+     * Expects an object with id, name, and data properties.
+     *
+     * @param input - Unknown input to parse
+     * @returns A new IllaToolError instance
+     * @throws ZodError if the input doesn't match the expected schema
+     *
+     * @example
+     * ```ts
+     * const error = IllaToolError.parse({
+     *   id: 'call-123',
+     *   name: 'tokenTransfer',
+     *   data: { type: 'execution', message: 'Failed' }
+     * });
+     * ```
+     */
+    static parse(input: unknown): IllaToolError;
+    /**
+     * Parses error data and creates an IllaToolError with the provided id and name.
+     * Useful when reconstructing from IllaToolOutcome where id/name are separate.
+     *
+     * @param id - The tool call ID
+     * @param name - The tool/action name
+     * @param data - Unknown error data to parse
+     * @returns A new IllaToolError instance
+     * @throws ZodError if the data doesn't match the expected schema
+     */
+    static parseData(id: string, name: string, data: unknown): IllaToolError;
+    /**
+     * Check if this is an input validation error
+     */
+    isInputError(): this is IllaToolError & {
+        data: IllaToolInputErrorData;
+    };
+    /**
+     * Check if this is an execution error
+     */
+    isExecutionError(): this is IllaToolError & {
+        data: IllaToolExecutionErrorData;
+    };
+    /**
+     * Get the validation errors if this is an input error
+     * @returns Array of validation errors or undefined if not an input error
+     */
+    getValidationErrors(): Array<{
+        path: string;
+        message: string;
+    }> | undefined;
+    /**
+     * Get the error message
+     * @returns The error message (for execution errors) or a summary of validation errors
+     */
+    getMessage(): string;
+    /**
+     * Convert to a plain JSON object for serialization
+     * @returns The error data object
+     */
+    toJSON(): IllaToolErrorData;
+}
+//# sourceMappingURL=IllaToolError.d.ts.map

package/dist/tools/IllaToolError.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"IllaToolError.d.ts","sourceRoot":"","sources":["../../src/tools/IllaToolError.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACR,iBAAiB,EACjB,0BAA0B,EAC1B,sBAAsB,EACzB,MAAM,gBAAgB,CAAC;AAGxB;;;;;;;;;;;;;;;GAeG;AACH,qBAAa,aAAa;aAQF,EAAE,EAAE,MAAM;aACV,IAAI,EAAE,MAAM;aACZ,IAAI,EAAE,iBAAiB;IAT3C;;;;;OAKG;IACH,OAAO;IAMP;;OAEG;IACH,IAAW,IAAI,IAAI,OAAO,GAAG,WAAW,CAEvC;IAED;;;;;;OAMG;WACW,KAAK,CACf,EAAE,EAAE,MAAM,EACV,IAAI,EAAE,MAAM,EACZ,MAAM,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,CAAC,GACjD,aAAa;IAOhB;;;;;;;OAOG;WACW,SAAS,CACnB,EAAE,EAAE,MAAM,EACV,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,MAAM,EACf,OAAO,CAAC,EAAE,OAAO,GAClB,aAAa;IAQhB;;;;;;;;;;;;;;;;OAgBG;WACW,KAAK,CAAC,KAAK,EAAE,OAAO,GAAG,aAAa;IAKlD;;;;;;;;;OASG;WACW,SAAS,CAAC,EAAE,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,OAAO,GAAG,aAAa;IAK/E;;OAEG;IACI,YAAY,IAAI,IAAI,IAAI,aAAa,GAAG;QAAE,IAAI,EAAE,sBAAsB,CAAA;KAAE;IAI/E;;OAEG;IACI,gBAAgB,IAAI,IAAI,IAAI,aAAa,GAAG;QAAE,IAAI,EAAE,0BAA0B,CAAA;KAAE;IAIvF;;;OAGG;IACI,mBAAmB,IAAI,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,CAAC,GAAG,SAAS;IAOlF;;;OAGG;IACI,UAAU,IAAI,MAAM;IAQ3B;;;OAGG;IACI,MAAM,IAAI,iBAAiB;CAGrC"}

package/dist/tools/IllaToolError.js

@@ -0,0 +1,143 @@
+import { IllaToolErrorDataSchema, IllaToolErrorSchema } from "../internal.js";
+/**
+ * Represents an error that occurred during tool call validation or execution.
+ * This is a structured error class that distinguishes between input validation
+ * errors and execution errors.
+ *
+ * @example
+ * ```ts
+ * // Create an input validation error
+ * const inputError = IllaToolError.input('call-123', 'tokenTransfer', [
+ *   { path: 'amount', message: 'Amount is required' }
+ * ]);
+ *
+ * // Create an execution error
+ * const execError = IllaToolError.execution('call-123', 'tokenTransfer', 'Network timeout');
+ * ```
+ */
+export class IllaToolError {
+    id;
+    name;
+    data;
+    /**
+     * Creates a new IllaToolError instance
+     * @param id - The tool call ID this error is associated with
+     * @param name - The name of the tool/action that errored
+     * @param data - The structured error data
+     */
+    constructor(id, name, data) {
+        this.id = id;
+        this.name = name;
+        this.data = data;
+    }
+    /**
+     * The type of error ("input" or "execution")
+     */
+    get type() {
+        return this.data.type;
+    }
+    /**
+     * Creates an input validation error
+     * @param id - The tool call ID
+     * @param name - The tool/action name
+     * @param errors - Array of validation errors with path and message
+     * @returns A new IllaToolError representing input validation failure
+     */
+    static input(id, name, errors) {
+        return new IllaToolError(id, name, {
+            type: "input",
+            errors,
+        });
+    }
+    /**
+     * Creates an execution error
+     * @param id - The tool call ID
+     * @param name - The tool/action name
+     * @param message - Human-readable error message
+     * @param details - Optional additional error details
+     * @returns A new IllaToolError representing execution failure
+     */
+    static execution(id, name, message, details) {
+        return new IllaToolError(id, name, {
+            type: "execution",
+            message,
+            details,
+        });
+    }
+    /**
+     * Parses and validates unknown input to create an IllaToolError instance.
+     * Expects an object with id, name, and data properties.
+     *
+     * @param input - Unknown input to parse
+     * @returns A new IllaToolError instance
+     * @throws ZodError if the input doesn't match the expected schema
+     *
+     * @example
+     * ```ts
+     * const error = IllaToolError.parse({
+     *   id: 'call-123',
+     *   name: 'tokenTransfer',
+     *   data: { type: 'execution', message: 'Failed' }
+     * });
+     * ```
+     */
+    static parse(input) {
+        const parsed = IllaToolErrorSchema.parse(input);
+        return new IllaToolError(parsed.id, parsed.name, parsed.data);
+    }
+    /**
+     * Parses error data and creates an IllaToolError with the provided id and name.
+     * Useful when reconstructing from IllaToolOutcome where id/name are separate.
+     *
+     * @param id - The tool call ID
+     * @param name - The tool/action name
+     * @param data - Unknown error data to parse
+     * @returns A new IllaToolError instance
+     * @throws ZodError if the data doesn't match the expected schema
+     */
+    static parseData(id, name, data) {
+        const parsedData = IllaToolErrorDataSchema.parse(data);
+        return new IllaToolError(id, name, parsedData);
+    }
+    /**
+     * Check if this is an input validation error
+     */
+    isInputError() {
+        return this.data.type === "input";
+    }
+    /**
+     * Check if this is an execution error
+     */
+    isExecutionError() {
+        return this.data.type === "execution";
+    }
+    /**
+     * Get the validation errors if this is an input error
+     * @returns Array of validation errors or undefined if not an input error
+     */
+    getValidationErrors() {
+        if (this.isInputError()) {
+            return this.data.errors;
+        }
+        return undefined;
+    }
+    /**
+     * Get the error message
+     * @returns The error message (for execution errors) or a summary of validation errors
+     */
+    getMessage() {
+        if (this.data.type === "execution") {
+            return this.data.message;
+        }
+        const errors = this.data.errors;
+        return errors.map((error) => `${error.path}: ${error.message}`).join(", ");
+    }
+    /**
+     * Convert to a plain JSON object for serialization
+     * @returns The error data object
+     */
+    toJSON() {
+        return this.data;
+    }
+}
+//# sourceMappingURL=IllaToolError.js.map

package/dist/tools/IllaToolError.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"IllaToolError.js","sourceRoot":"","sources":["../../src/tools/IllaToolError.ts"],"names":[],"mappings":"AAKA,OAAO,EAAE,uBAAuB,EAAE,mBAAmB,EAAE,MAAM,gBAAgB,CAAC;AAE9E;;;;;;;;;;;;;;;GAeG;AACH,MAAM,OAAO,aAAa;IAQF;IACA;IACA;IATpB;;;;;OAKG;IACH,YACoB,EAAU,EACV,IAAY,EACZ,IAAuB;QAFvB,OAAE,GAAF,EAAE,CAAQ;QACV,SAAI,GAAJ,IAAI,CAAQ;QACZ,SAAI,GAAJ,IAAI,CAAmB;IACxC,CAAC;IAEJ;;OAEG;IACH,IAAW,IAAI;QACX,OAAO,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC;IAC1B,CAAC;IAED;;;;;;OAMG;IACI,MAAM,CAAC,KAAK,CACf,EAAU,EACV,IAAY,EACZ,MAAgD;QAEhD,OAAO,IAAI,aAAa,CAAC,EAAE,EAAE,IAAI,EAAE;YAC/B,IAAI,EAAE,OAAO;YACb,MAAM;SACT,CAAC,CAAC;IACP,CAAC;IAED;;;;;;;OAOG;IACI,MAAM,CAAC,SAAS,CACnB,EAAU,EACV,IAAY,EACZ,OAAe,EACf,OAAiB;QAEjB,OAAO,IAAI,aAAa,CAAC,EAAE,EAAE,IAAI,EAAE;YAC/B,IAAI,EAAE,WAAW;YACjB,OAAO;YACP,OAAO;SACV,CAAC,CAAC;IACP,CAAC;IAED;;;;;;;;;;;;;;;;OAgBG;IACI,MAAM,CAAC,KAAK,CAAC,KAAc;QAC9B,MAAM,MAAM,GAAG,mBAAmB,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC;QAChD,OAAO,IAAI,aAAa,CAAC,MAAM,CAAC,EAAE,EAAE,MAAM,CAAC,IAAI,EAAE,MAAM,CAAC,IAAI,CAAC,CAAC;IAClE,CAAC;IAED;;;;;;;;;OASG;IACI,MAAM,CAAC,SAAS,CAAC,EAAU,EAAE,IAAY,EAAE,IAAa;QAC3D,MAAM,UAAU,GAAG,uBAAuB,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;QACvD,OAAO,IAAI,aAAa,CAAC,EAAE,EAAE,IAAI,EAAE,UAAU,CAAC,CAAC;IACnD,CAAC;IAED;;OAEG;IACI,YAAY;QACf,OAAO,IAAI,CAAC,IAAI,CAAC,IAAI,KAAK,OAAO,CAAC;IACtC,CAAC;IAED;;OAEG;IACI,gBAAgB;QACnB,OAAO,IAAI,CAAC,IAAI,CAAC,IAAI,KAAK,WAAW,CAAC;IAC1C,CAAC;IAED;;;OAGG;IACI,mBAAmB;QACtB,IAAI,IAAI,CAAC,YAAY,EAAE,EAAE,CAAC;YACtB,OAAO,IAAI,CAAC,IAAI,CAAC,MAAM,CAAC;QAC5B,CAAC;QACD,OAAO,SAAS,CAAC;IACrB,CAAC;IAED;;;OAGG;IACI,UAAU;QACb,IAAI,IAAI,CAAC,IAAI,CAAC,IAAI,KAAK,WAAW,EAAE,CAAC;YACjC,OAAO,IAAI,CAAC,IAAI,CAAC,OAAO,CAAC;QAC7B,CAAC;QACD,MAAM,MAAM,GAAG,IAAI,CAAC,IAAI,CAAC,MAAM,CAAC;QAChC,OAAO,MAAM,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,GAAG,KAAK,CAAC,IAAI,KAAK,KAAK,CAAC,OAAO,EAAE,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IAC/E,CAAC;IAED;;;OAGG;IACI,MAAM;QACT,OAAO,IAAI,CAAC,IAAI,CAAC;IACrB,CAAC;CACJ"}

package/dist/tools/IllaToolOutcome.d.ts

@@ -0,0 +1,131 @@
+import type { IllaToolOutcomeJSON } from "../internal.js";
+import { IllaToolError } from "./IllaToolError.js";
+/**
+ * Represents the outcome of a tool execution, which can be either a success or an error.
+ * This implements the Result/Either pattern for explicit error handling.
+ *
+ * @template T - The type of the successful result
+ *
+ * @example
+ * ```ts
+ * // Create a successful outcome
+ * const success = IllaToolOutcome.success('call-123', 'tokenTransfer', { txHash: '0x...' });
+ *
+ * // Create an error outcome
+ * const error = IllaToolOutcome.error('call-123', 'tokenTransfer',
+ *   IllaToolError.execution('call-123', 'tokenTransfer', 'Transaction failed')
+ * );
+ *
+ * // Handle the outcome
+ * if (outcome.isSuccess()) {
+ *   console.log('Result:', outcome.getResult());
+ * } else {
+ *   console.error('Error:', outcome.getError()?.getMessage());
+ * }
+ * ```
+ */
+export declare class IllaToolOutcome<T = unknown> {
+    readonly id: string;
+    readonly name: string;
+    private readonly _result?;
+    private readonly _error?;
+    private readonly _isError;
+    private constructor();
+    /**
+     * Creates a successful outcome
+     * @param id - The tool call ID
+     * @param name - The tool/action name
+     * @param result - The successful result value
+     * @returns A new IllaToolOutcome representing success
+     */
+    static success<T>(id: string, name: string, result: T): IllaToolOutcome<T>;
+    /**
+     * Creates an error outcome
+     * @param id - The tool call ID
+     * @param name - The tool/action name
+     * @param error - The error that occurred
+     * @returns A new IllaToolOutcome representing failure
+     */
+    static error(id: string, name: string, error: IllaToolError): IllaToolOutcome<never>;
+    /**
+     * Parses and validates unknown input to create an IllaToolOutcome instance.
+     * Expects an object with id, name, and either result or error properties.
+     *
+     * @template T - The expected type of the result (defaults to unknown)
+     * @param input - Unknown input to parse
+     * @returns A new IllaToolOutcome instance
+     * @throws ZodError if the input doesn't match the expected schema
+     *
+     * @example
+     * ```ts
+     * // Parse a success outcome
+     * const success = IllaToolOutcome.parse<{ txHash: string }>({
+     *   id: 'call-123',
+     *   name: 'tokenTransfer',
+     *   result: { txHash: '0x...' }
+     * });
+     *
+     * // Parse an error outcome
+     * const error = IllaToolOutcome.parse({
+     *   id: 'call-456',
+     *   name: 'swap',
+     *   error: { type: 'execution', message: 'Failed' }
+     * });
+     * ```
+     */
+    static parse<T = unknown>(input: unknown): IllaToolOutcome<T>;
+    /**
+     * Check if this outcome represents a successful execution
+     */
+    isSuccess(): boolean;
+    /**
+     * Check if this outcome represents an error
+     */
+    isError(): boolean;
+    /**
+     * Get the successful result value
+     * @returns The result value or undefined if this is an error outcome
+     */
+    getResult(): T | undefined;
+    /**
+     * Get the error
+     * @returns The error or undefined if this is a success outcome
+     */
+    getError(): IllaToolError | undefined;
+    /**
+     * Get the result or throw if this is an error
+     * @returns The result value
+     * @throws Error if this is an error outcome
+     */
+    getResultOrThrow(): T;
+    /**
+     * Map the result value to a new type
+     * @param fn - Function to transform the result
+     * @returns A new IllaToolOutcome with the transformed result, or the same error
+     */
+    map<U>(fn: (result: T) => U): IllaToolOutcome<U>;
+    /**
+     * Chain another operation that returns an IllaToolOutcome
+     * @param fn - Function that takes the result and returns a new IllaToolOutcome
+     * @returns The result of fn if successful, or the original error
+     */
+    flatMap<U>(fn: (result: T) => IllaToolOutcome<U>): IllaToolOutcome<U>;
+    /**
+     * Execute a function if this is a success
+     * @param fn - Function to execute with the result
+     * @returns This outcome (for chaining)
+     */
+    onSuccess(fn: (result: T) => void): this;
+    /**
+     * Execute a function if this is an error
+     * @param fn - Function to execute with the error
+     * @returns This outcome (for chaining)
+     */
+    onError(fn: (error: IllaToolError) => void): this;
+    /**
+     * Convert to a plain JSON object for serialization
+     * @returns An object with either result or error
+     */
+    toJSON(): IllaToolOutcomeJSON;
+}
+//# sourceMappingURL=IllaToolOutcome.d.ts.map

package/dist/tools/IllaToolOutcome.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"IllaToolOutcome.d.ts","sourceRoot":"","sources":["../../src/tools/IllaToolOutcome.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,gBAAgB,CAAC;AAE1D,OAAO,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AAEnD;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,qBAAa,eAAe,CAAC,CAAC,GAAG,OAAO;aAEhB,EAAE,EAAE,MAAM;aACV,IAAI,EAAE,MAAM;IAC5B,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAC;IACzB,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAC;IACxB,OAAO,CAAC,QAAQ,CAAC,QAAQ;IAL7B,OAAO;IAQP;;;;;;OAMG;WACW,OAAO,CAAC,CAAC,EAAE,EAAE,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,CAAC,GAAG,eAAe,CAAC,CAAC,CAAC;IAIjF;;;;;;OAMG;WACW,KAAK,CAAC,EAAE,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,aAAa,GAAG,eAAe,CAAC,KAAK,CAAC;IAI3F;;;;;;;;;;;;;;;;;;;;;;;;;OAyBG;WACW,KAAK,CAAC,CAAC,GAAG,OAAO,EAAE,KAAK,EAAE,OAAO,GAAG,eAAe,CAAC,CAAC,CAAC;IAWpE;;OAEG;IACI,SAAS,IAAI,OAAO;IAI3B;;OAEG;IACI,OAAO,IAAI,OAAO;IAIzB;;;OAGG;IACI,SAAS,IAAI,CAAC,GAAG,SAAS;IAIjC;;;OAGG;IACI,QAAQ,IAAI,aAAa,GAAG,SAAS;IAI5C;;;;OAIG;IACI,gBAAgB,IAAI,CAAC;IAU5B;;;;OAIG;IACI,GAAG,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,MAAM,EAAE,CAAC,KAAK,CAAC,GAAG,eAAe,CAAC,CAAC,CAAC;IAOvD;;;;OAIG;IACI,OAAO,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,MAAM,EAAE,CAAC,KAAK,eAAe,CAAC,CAAC,CAAC,GAAG,eAAe,CAAC,CAAC,CAAC;IAO5E;;;;OAIG;IACI,SAAS,CAAC,EAAE,EAAE,CAAC,MAAM,EAAE,CAAC,KAAK,IAAI,GAAG,IAAI;IAO/C;;;;OAIG;IACI,OAAO,CAAC,EAAE,EAAE,CAAC,KAAK,EAAE,aAAa,KAAK,IAAI,GAAG,IAAI;IAOxD;;;OAGG;IACI,MAAM,IAAI,mBAAmB;CAQvC"}