@agentick/ai-sdk 0.0.1

package/dist/compiler.js

@@ -0,0 +1,704 @@
+/**
+ * ============================================================================
+ * AI SDK Compiler Adapter
+ * ============================================================================
+ *
+ * This adapter provides progressive adoption for AI SDK users who want to use
+ * our JSX compilation without fully committing to our Engine.
+ *
+ * Direction of adaptation: Engine → ai-sdk
+ * (For ai-sdk → Engine direction, use adapter.ts directly)
+ *
+ * ============================================================================
+ * PROGRESSIVE ADOPTION LEVELS
+ * ============================================================================
+ *
+ * Level 1: compile() only
+ * Returns library-native input. User calls generateText themselves.
+ *
+ * @example
+ * ```typescript
+ * import { compile } from '@tentickle/ai-sdk';
+ * import { generateText } from 'ai';
+ * import { openai } from '@ai-sdk/openai';
+ *
+ * const compiled = await compile(<MyAgent />);
+ *
+ * const result = await generateText({
+ *   model: compiled.model ?? openai('gpt-4o'),
+ *   messages: compiled.messages,
+ *   tools: compiled.tools,
+ *   system: compiled.system,
+ * });
+ * ```
+ *
+ * Level 2: run() with executor
+ * User controls model execution, we handle the tick loop.
+ *
+ * @example
+ * ```typescript
+ * import { createCompiler } from '@tentickle/ai-sdk';
+ * import { generateText } from 'ai';
+ * import { openai } from '@ai-sdk/openai';
+ *
+ * const compiler = createCompiler();
+ *
+ * const result = await compiler.run(<MyAgent />, async (input) => {
+ *   return await generateText({
+ *     model: openai('gpt-4o'),
+ *     ...input,
+ *   });
+ * });
+ * ```
+ *
+ * Level 3: run() / stream() - managed execution
+ * We handle everything. Model comes from <Model> component or config.
+ *
+ * @example
+ * ```typescript
+ * import { createCompiler } from '@tentickle/ai-sdk';
+ * import { openai } from '@ai-sdk/openai';
+ *
+ * const compiler = createCompiler({ model: openai('gpt-4o') });
+ *
+ * const result = await compiler.run(<MyAgent />);
+ *
+ * // Or streaming:
+ * for await (const chunk of compiler.stream(<MyAgent />)) {
+ *   process.stdout.write(chunk.textDelta ?? '');
+ * }
+ * ```
+ *
+ * Level 4: generateText() / streamText() - mirror library API
+ * Same API as ai-sdk, but with JSX as the first argument.
+ *
+ * @example
+ * ```typescript
+ * import { generateText, streamText } from '@tentickle/ai-sdk';
+ * import { openai } from '@ai-sdk/openai';
+ *
+ * // createCompiler run internally
+ *
+ * // Exact same return type as ai-sdk's generateText
+ * const result = await generateText(<MyAgent />, {
+ *   temperature: 0.8,
+ * });
+ *
+ * // Exact same return type as ai-sdk's streamText
+ * const { fullStream, text } = streamText(<MyAgent />);
+ * for await (const chunk of fullStream) {
+ *   // Native ai-sdk chunks
+ * }
+ * ```
+ *
+ * ============================================================================
+ * COMPONENT PORTABILITY
+ * ============================================================================
+ *
+ * All adapter packages export the same component names:
+ * - Model: Configure the model declaratively
+ * - Tool: Define tools in JSX
+ * - Message, System, User, Assistant: Message components
+ *
+ * Switch adapters without changing agent code.
+ *
+ * ============================================================================
+ */
+import { Runtime, } from "@tentickle/core";
+import { generateText as aiSdkGenerateText, streamText as aiSdkStreamText } from "ai";
+import { EventEmitter } from "node:events";
+import { randomUUID } from "node:crypto";
+import { createAiSdkModel, aiSdkMessagesToEngineInput, toAiSdkCompiledInput, fromAiSdkMessages, } from "./adapter";
+import { AbortError, ValidationError } from "@tentickle/shared";
+// ============================================================================
+// Conversion Utilities
+// ============================================================================
+// Use adapter functions for conversions - see adapter.ts for implementations:
+// - aiSdkMessagesToEngineInput: AI SDK messages → EngineInput
+// - toAiSdkCompiledInput: TickResult → CompiledInput
+/**
+ * Convert compiled output to library-native CompiledInput.
+ * Wraps the adapter function with the CompiledInput interface.
+ */
+function toCompiledInput(compiled, tick, extractedModel) {
+    const result = toAiSdkCompiledInput(compiled.formatted, compiled.tools, tick, extractedModel);
+    return result;
+}
+/**
+ * Convert ai-sdk result to TickResultInput for state ingestion.
+ * Uses adapter's fromAiSdkMessages for content conversion.
+ */
+function toTickResultInput(result) {
+    // Use adapter's conversion for response messages
+    const messages = fromAiSdkMessages(result.response?.messages);
+    // Find the assistant message
+    const assistantMessage = messages.find((m) => m.role === "assistant");
+    // Build timeline entries from converted messages
+    const newTimelineEntries = assistantMessage
+        ? [
+            {
+                kind: "message",
+                message: assistantMessage,
+            },
+        ]
+        : undefined;
+    const response = {
+        shouldStop: !result.toolCalls || result.toolCalls.length === 0,
+        newTimelineEntries: newTimelineEntries,
+        toolCalls: result.toolCalls?.map((tc) => ({
+            id: tc.toolCallId,
+            name: tc.toolName,
+            input: tc.args || {},
+        })),
+    };
+    return { response };
+}
+// ============================================================================
+// Process Handle (for Fork/Spawn support)
+// ============================================================================
+class ProcessHandle {
+    pid;
+    rootPid;
+    type;
+    parentPid;
+    _status = "pending";
+    _result;
+    _events = new EventEmitter();
+    _completionPromise;
+    _resolve;
+    _reject;
+    _abortController = new AbortController();
+    constructor(type, parentPid, rootPid) {
+        this.pid = `aisdk-${type}-${randomUUID().slice(0, 8)}`;
+        this.type = type;
+        this.parentPid = parentPid;
+        this.rootPid = rootPid || this.pid;
+        this._completionPromise = new Promise((resolve, reject) => {
+            this._resolve = resolve;
+            this._reject = reject;
+        });
+    }
+    get status() {
+        return this._status;
+    }
+    get result() {
+        return this._result;
+    }
+    get tick() {
+        return 0;
+    }
+    start() {
+        this._status = "running";
+        this._events.emit("start");
+    }
+    complete(result) {
+        this._status = "completed";
+        this._result = result;
+        this._events.emit("complete", result);
+        this._resolve(result);
+    }
+    fail(error) {
+        this._status = "failed";
+        this._events.emit("error", error);
+        this._reject(error);
+    }
+    cancel() {
+        if (this._status === "running" || this._status === "pending") {
+            this._status = "cancelled";
+            this._abortController.abort();
+            this._events.emit("cancelled");
+            this._reject(new AbortError("Execution cancelled"));
+        }
+    }
+    getCancelSignal() {
+        return this._abortController.signal;
+    }
+    waitForCompletion() {
+        return this._completionPromise;
+    }
+    on(event, handler) {
+        this._events.on(event, handler);
+        return this;
+    }
+    off(event, handler) {
+        this._events.off(event, handler);
+        return this;
+    }
+}
+// ============================================================================
+// Standalone compile() function (Level 1)
+// ============================================================================
+/**
+ * Compile JSX to library-native input.
+ *
+ * This is the simplest entry point. You get back messages, tools, and system
+ * in ai-sdk format, ready to pass to generateText/streamText.
+ *
+ * @example
+ * ```typescript
+ * import { compile } from '@tentickle/ai-sdk';
+ * import { generateText } from 'ai';
+ * import { openai } from '@ai-sdk/openai';
+ *
+ * const { messages, tools, system, model } = await compile(<MyAgent />);
+ *
+ * const result = await generateText({
+ *   model: model ?? openai('gpt-4o'),
+ *   messages,
+ *   tools,
+ *   system,
+ * });
+ * ```
+ */
+export async function compile(jsx, initialMessages) {
+    const service = new Runtime();
+    const engineInput = aiSdkMessagesToEngineInput(initialMessages);
+    const { formatted } = await service.compile(jsx, engineInput);
+    // Extract model from COM if <Model> component was used
+    // TODO: Need to expose model extraction from COM
+    const extractedModel = undefined; // com.getModel()?.raw as LanguageModel | undefined;
+    const compiled = {
+        compiled: {},
+        formatted,
+        tools: service.getTools(),
+        shouldStop: false,
+    };
+    return toCompiledInput(compiled, 1, extractedModel);
+}
+// ============================================================================
+// Compiler Class (Levels 2-4)
+// ============================================================================
+/**
+ * AI SDK Compiler.
+ *
+ * Provides progressive adoption from simple compilation to full execution management.
+ *
+ * @example Level 2: User-controlled execution
+ * ```typescript
+ * const compiler = createCompiler();
+ *
+ * const result = await compiler.run(<MyAgent />, async (input) => {
+ *   return await generateText({ model: openai('gpt-4o'), ...input });
+ * });
+ * ```
+ *
+ * @example Level 3: Managed execution
+ * ```typescript
+ * const compiler = createCompiler({ model: openai('gpt-4o') });
+ * const result = await compiler.run(<MyAgent />);
+ * ```
+ *
+ * @example Level 4: Library-mirroring API
+ * ```typescript
+ * const compiler = createCompiler({ model: openai('gpt-4o') });
+ * const result = await compiler.generateText(<MyAgent />, { temperature: 0.8 });
+ * ```
+ */
+export class AiSdkCompiler {
+    service;
+    defaultModel;
+    defaultOptions;
+    maxTicks;
+    executions = new Map();
+    currentExecutor;
+    constructor(config = {}) {
+        this.defaultModel = config.model;
+        this.defaultOptions = {
+            temperature: config.temperature,
+            maxOutputTokens: config.maxTokens,
+        };
+        this.maxTicks = config.maxTicks ?? 10;
+        // Create process methods for Fork/Spawn
+        const processMethods = this.createProcessMethods();
+        // Create service with model getter
+        const modelGetter = this.defaultModel
+            ? () => createAiSdkModel({ model: this.defaultModel })
+            : undefined;
+        this.service = new Runtime({
+            ...config.serviceConfig,
+            modelGetter,
+            processMethods,
+        });
+    }
+    createProcessMethods() {
+        return {
+            fork: (input, root, options) => {
+                const parentHandle = options?.parentPid
+                    ? this.executions.get(options.parentPid)
+                    : undefined;
+                const handle = new ProcessHandle("fork", options?.parentPid, parentHandle?.rootPid);
+                this.executions.set(handle.pid, handle);
+                if (root && this.currentExecutor) {
+                    const element = typeof root === "function" ? { type: root, props: {}, key: null } : root;
+                    const messages = this.engineInputToMessages(input);
+                    this.runInternal(element, messages, this.currentExecutor)
+                        .then((result) => handle.complete(result))
+                        .catch((error) => handle.fail(error instanceof Error ? error : new Error(String(error))));
+                }
+                return handle;
+            },
+            spawn: (input, root, _options) => {
+                const handle = new ProcessHandle("spawn");
+                this.executions.set(handle.pid, handle);
+                if (root && this.currentExecutor) {
+                    const element = typeof root === "function" ? { type: root, props: {}, key: null } : root;
+                    const messages = this.engineInputToMessages(input);
+                    this.runInternal(element, messages, this.currentExecutor)
+                        .then((result) => handle.complete(result))
+                        .catch((error) => handle.fail(error instanceof Error ? error : new Error(String(error))));
+                }
+                return handle;
+            },
+            signal: (pid, signal) => {
+                const handle = this.executions.get(pid);
+                if (handle && signal === "abort") {
+                    handle.cancel();
+                }
+            },
+            kill: (pid) => {
+                this.executions.get(pid)?.cancel();
+            },
+            // Clean Process interface methods
+            all: () => {
+                return Array.from(this.executions.values()).filter((h) => h.status === "running");
+            },
+            get: (pid) => {
+                return this.executions.get(pid);
+            },
+            // Deprecated COMProcess methods (backwards compat)
+            list: () => {
+                return Array.from(this.executions.values()).filter((h) => h.status === "running");
+            },
+        };
+    }
+    engineInputToMessages(input) {
+        return (input.timeline || [])
+            .filter((entry) => entry.kind === "message")
+            .map((entry) => {
+            const msg = entry.message;
+            const content = msg.content.map((c) => {
+                if (c.type === "text")
+                    return { type: "text", text: c.text };
+                return { type: "text", text: JSON.stringify(c) };
+            });
+            return { role: msg.role, content };
+        });
+    }
+    // ============================================================================
+    // Level 2-3: run() - with or without executor
+    // ============================================================================
+    /**
+     * Execute a JSX program.
+     *
+     * If executor is provided (Level 2), user controls model execution.
+     * If not provided (Level 3), we manage execution using configured model.
+     *
+     * @param jsx Root JSX element
+     * @param executorOrMessages Optional executor function OR initial messages
+     * @param maybeExecutor Optional executor (if second arg was messages)
+     */
+    async run(jsx, executorOrMessages, maybeExecutor) {
+        // Parse overloaded arguments
+        let initialMessages;
+        let executor;
+        if (typeof executorOrMessages === "function") {
+            executor = executorOrMessages;
+        }
+        else if (Array.isArray(executorOrMessages)) {
+            initialMessages = executorOrMessages;
+            executor = maybeExecutor;
+        }
+        // If no executor, use managed execution
+        if (!executor) {
+            executor = this.createManagedExecutor();
+        }
+        return this.runInternal(jsx, initialMessages, executor);
+    }
+    async runInternal(jsx, initialMessages, executor) {
+        // Store executor for fork/spawn
+        this.currentExecutor = executor;
+        const engineInput = aiSdkMessagesToEngineInput(initialMessages);
+        const config = {
+            input: engineInput,
+            rootElement: jsx,
+            maxTicks: this.maxTicks,
+        };
+        let tick = 1;
+        let lastResult;
+        await this.service._run(config, async (compiled) => {
+            const input = toCompiledInput(compiled, tick);
+            const result = await executor(input);
+            lastResult = result;
+            tick++;
+            return toTickResultInput(result);
+        });
+        return lastResult;
+    }
+    createManagedExecutor() {
+        if (!this.defaultModel) {
+            throw new ValidationError("model", "No model configured. Either pass an executor function, " +
+                "configure a model in createCompiler(), or use a <Model> component.");
+        }
+        return async (input) => {
+            return await aiSdkGenerateText({
+                model: input.model ?? this.defaultModel,
+                messages: input.messages,
+                system: input.system,
+                ...this.defaultOptions,
+                tools: Object.assign({}, input.tools, this.defaultOptions?.tools || {}),
+            });
+        };
+    }
+    // ============================================================================
+    // Level 2-3: stream() - with or without executor
+    // ============================================================================
+    /**
+     * Execute a JSX program with streaming.
+     *
+     * @param jsx Root JSX element
+     * @param executorOrMessages Optional executor function OR initial messages
+     * @param maybeExecutor Optional executor (if second arg was messages)
+     */
+    async *stream(jsx, executorOrMessages, maybeExecutor) {
+        // Parse overloaded arguments
+        let initialMessages;
+        let executor;
+        if (typeof executorOrMessages === "function") {
+            executor = executorOrMessages;
+        }
+        else if (Array.isArray(executorOrMessages)) {
+            initialMessages = executorOrMessages;
+            executor = maybeExecutor;
+        }
+        // If no executor, use managed execution
+        if (!executor) {
+            executor = this.createManagedStreamExecutor();
+        }
+        yield* this.streamInternal(jsx, initialMessages, executor);
+    }
+    async *streamInternal(jsx, initialMessages, executor) {
+        const engineInput = aiSdkMessagesToEngineInput(initialMessages);
+        const config = {
+            input: engineInput,
+            rootElement: jsx,
+            maxTicks: this.maxTicks,
+        };
+        for await (const event of this.service._runStream(config, {
+            onTick: async function* (compiled, tick) {
+                const input = toCompiledInput(compiled, tick);
+                yield { type: "compiled", tick, input };
+                const streamResult = executor(input);
+                for await (const chunk of streamResult.fullStream) {
+                    yield chunk;
+                }
+                // Mark end with the accumulated result
+                const result = await streamResult;
+                yield { __result: result };
+            },
+            finalizeChunks: (chunks) => {
+                // Find the result marker
+                const resultMarker = chunks.find((c) => c?.__result);
+                if (resultMarker) {
+                    return toTickResultInput(resultMarker.__result);
+                }
+                // Fallback: aggregate chunks
+                let text = "";
+                const toolCalls = [];
+                for (const chunk of chunks) {
+                    if (chunk?.type === "text-delta") {
+                        text += chunk.textDelta ?? "";
+                    }
+                    if (chunk?.type === "tool-call") {
+                        toolCalls.push({
+                            toolCallId: chunk.toolCallId,
+                            toolName: chunk.toolName,
+                            args: chunk.args,
+                        });
+                    }
+                }
+                const response = {
+                    shouldStop: toolCalls.length === 0,
+                    newTimelineEntries: text
+                        ? [
+                            {
+                                kind: "message",
+                                message: {
+                                    role: "assistant",
+                                    content: [{ type: "text", text }],
+                                },
+                            },
+                        ]
+                        : undefined,
+                    toolCalls: toolCalls.length > 0
+                        ? toolCalls.map((tc) => ({
+                            id: tc.toolCallId,
+                            name: tc.toolName,
+                            input: tc.args,
+                        }))
+                        : undefined,
+                };
+                return { response };
+            },
+        })) {
+            // Transform internal events to our public event type
+            if (event.type === "tick_start") {
+                yield { type: "tick_start", tick: event.tick };
+            }
+            else if (event.type === "chunk") {
+                yield { type: "chunk", tick: event.tick, chunk: event.chunk };
+            }
+            else if (event.type === "tick_end") {
+                yield { type: "tick_end", tick: event.tick };
+            }
+            else if (event.type === "complete") {
+                yield { type: "complete", result: event.output };
+            }
+        }
+    }
+    createManagedStreamExecutor() {
+        if (!this.defaultModel) {
+            throw new ValidationError("model", "No model configured. Either pass an executor function, " +
+                "configure a model in createCompiler(), or use a <Model> component.");
+        }
+        return (input) => {
+            return aiSdkStreamText({
+                model: input.model ?? this.defaultModel,
+                messages: input.messages,
+                system: input.system,
+                ...this.defaultOptions,
+                tools: Object.assign({}, input.tools, this.defaultOptions?.tools || {}),
+            });
+        };
+    }
+    // ============================================================================
+    // Cleanup
+    // ============================================================================
+    async destroy() {
+        for (const handle of this.executions.values()) {
+            if (handle.status === "running") {
+                handle.cancel();
+            }
+        }
+        this.executions.clear();
+    }
+}
+// ============================================================================
+// Level 4: generateText() / streamText() - mirror library API
+// ============================================================================
+/**
+ * Generate text using JSX.
+ *
+ * Mirrors ai-sdk's generateText API exactly.
+ * Returns the same type for seamless integration.
+ *
+ * @param jsx Root JSX element
+ * @param options Additional options (merged with defaults and JSX config)
+ */
+export async function generateText(jsx, options) {
+    const compiled = await compile(jsx);
+    const model = compiled.model ?? options?.model;
+    if (!model) {
+        throw new ValidationError("model", "No model available. Configure via createCompiler({ model }), " +
+            "<Model> component, or options.model parameter.");
+    }
+    return await aiSdkGenerateText({
+        model,
+        messages: compiled.messages,
+        system: compiled.system,
+        ...options,
+        tools: Object.assign({}, compiled.tools, options?.tools || {}),
+    });
+}
+/**
+ * Stream text using JSX.
+ *
+ * Mirrors ai-sdk's streamText API exactly.
+ * Returns the same type for seamless integration.
+ *
+ * @param jsx Root JSX element
+ * @param options Additional options (merged with defaults and JSX config)
+ */
+export function streamText(jsx, options) {
+    // We need to compile synchronously to return the stream immediately
+    // This is a limitation - compile() is async but streamText expects sync
+    // Solution: Return a proxy that starts compilation
+    // Create a deferred stream that compiles first
+    const streamPromise = (async () => {
+        const compiled = await compile(jsx);
+        const model = compiled.model ?? options?.model;
+        if (!model) {
+            throw new ValidationError("model", "No model available. Configure via createCompiler({ model }), " +
+                "<Model> component, or options.model parameter.");
+        }
+        return aiSdkStreamText({
+            model,
+            messages: compiled.messages,
+            system: compiled.system,
+            ...options,
+            tools: Object.assign({}, compiled.tools, options?.tools || {}),
+        });
+    })();
+    // Return a proxy object that looks like StreamTextResult
+    // but waits for compilation before accessing properties
+    return {
+        get fullStream() {
+            return (async function* () {
+                const stream = await streamPromise;
+                for await (const chunk of stream.fullStream) {
+                    yield chunk;
+                }
+            })();
+        },
+        get text() {
+            return streamPromise.then((s) => s.text);
+        },
+        get toolCalls() {
+            return streamPromise.then((s) => s.toolCalls);
+        },
+        get toolResults() {
+            return streamPromise.then((s) => s.toolResults);
+        },
+        get usage() {
+            return streamPromise.then((s) => s.usage);
+        },
+        get finishReason() {
+            return streamPromise.then((s) => s.finishReason);
+        },
+        get response() {
+            return streamPromise.then((s) => s.response);
+        },
+        get steps() {
+            return streamPromise.then((s) => s.steps);
+        },
+        // ... other StreamTextResult properties
+    };
+}
+// ============================================================================
+// Factory Function
+// ============================================================================
+/**
+ * Create an AI SDK compiler.
+ *
+ * @example Without model (requires executor or <Model> component)
+ * ```typescript
+ * const compiler = createCompiler();
+ *
+ * // Use with executor
+ * const result = await compiler.run(<MyAgent />, async (input) => {
+ *   return await generateText({ model: openai('gpt-4o'), ...input });
+ * });
+ * ```
+ *
+ * @example With model (managed execution)
+ * ```typescript
+ * const compiler = createCompiler({ model: openai('gpt-4o') });
+ *
+ * const result = await compiler.run(<MyAgent />);
+ * ```
+ */
+export function createCompiler(config) {
+    return new AiSdkCompiler(config);
+}
+// Also export as createAiSdkCompiler for backward compatibility
+export { createCompiler as createAiSdkCompiler };
+//# sourceMappingURL=compiler.js.map