fireworks-ai 0.2.0

package/dist/react/registry.test.js

@@ -0,0 +1,26 @@
+import { describe, expect, it } from "vitest";
+import { getWidget, registerWidget, stripMcpPrefix } from "./registry.js";
+describe("Widget Registry", () => {
+    it("registerWidget + getWidget roundtrip", () => {
+        const component = () => null;
+        registerWidget({ toolName: "test_tool", label: "Test", component });
+        const reg = getWidget("test_tool");
+        expect(reg).toBeDefined();
+        expect(reg?.label).toBe("Test");
+        expect(reg?.component).toBe(component);
+    });
+    it("getWidget returns undefined for unregistered name", () => {
+        expect(getWidget("nonexistent_widget")).toBeUndefined();
+    });
+});
+describe("stripMcpPrefix", () => {
+    it("strips mcp__server__tool prefix", () => {
+        expect(stripMcpPrefix("mcp__myserver__read_file")).toBe("read_file");
+    });
+    it("leaves names without prefix unchanged", () => {
+        expect(stripMcpPrefix("search")).toBe("search");
+    });
+    it("handles multiple underscores in tool name", () => {
+        expect(stripMcpPrefix("mcp__srv__my_long_tool_name")).toBe("my_long_tool_name");
+    });
+});

package/dist/react/store.d.ts

@@ -0,0 +1,28 @@
+import { type StoreApi } from "zustand/vanilla";
+import type { ChatMessage } from "../types.js";
+interface ChatStoreState {
+    sessionId: string | null;
+    messages: ChatMessage[];
+    isStreaming: boolean;
+    isThinking: boolean;
+    streamingText: string;
+}
+interface ChatStoreActions {
+    setSessionId: (id: string) => void;
+    addUserMessage: (text: string) => void;
+    appendStreamingText: (text: string) => void;
+    flushStreamingText: () => void;
+    addSystemMessage: (text: string) => void;
+    startToolCall: (toolUseId: string, name: string) => void;
+    appendToolInput: (toolUseId: string, partialJson: string) => void;
+    finalizeToolCall: (toolUseId: string, name: string, input: Record<string, unknown>) => void;
+    completeToolCall: (toolUseId: string, result: string) => void;
+    errorToolCall: (toolUseId: string, error: string) => void;
+    setStreaming: (v: boolean) => void;
+    setThinking: (v: boolean) => void;
+    reset: () => void;
+}
+export type ChatStoreShape = ChatStoreState & ChatStoreActions;
+export type ChatStore = StoreApi<ChatStoreShape>;
+export declare function createChatStore(): ChatStore;
+export {};

package/dist/react/store.js

@@ -0,0 +1,109 @@
+import { immer } from "zustand/middleware/immer";
+import { createStore } from "zustand/vanilla";
+let nextId = 0;
+function findToolCall(messages, toolUseId) {
+    for (let i = messages.length - 1; i >= 0; i--) {
+        const tc = messages[i].toolCalls;
+        if (tc?.length) {
+            const match = tc.find((t) => t.id === toolUseId);
+            if (match)
+                return match;
+        }
+    }
+    return undefined;
+}
+export function createChatStore() {
+    return createStore()(immer((set) => ({
+        sessionId: null,
+        messages: [],
+        isStreaming: false,
+        isThinking: false,
+        streamingText: "",
+        setSessionId: (id) => set((s) => {
+            s.sessionId = id;
+        }),
+        addUserMessage: (text) => set((s) => {
+            s.messages.push({
+                id: `msg-${++nextId}`,
+                role: "user",
+                content: text,
+            });
+        }),
+        addSystemMessage: (text) => set((s) => {
+            s.messages.push({
+                id: `msg-${++nextId}`,
+                role: "system",
+                content: text,
+            });
+        }),
+        appendStreamingText: (text) => set((s) => {
+            s.streamingText += text;
+        }),
+        flushStreamingText: () => set((s) => {
+            if (s.streamingText) {
+                const last = s.messages[s.messages.length - 1];
+                if (last?.role === "assistant" && !last.toolCalls?.length) {
+                    last.content += s.streamingText;
+                }
+                else {
+                    s.messages.push({
+                        id: `msg-${++nextId}`,
+                        role: "assistant",
+                        content: s.streamingText,
+                    });
+                }
+                s.streamingText = "";
+            }
+        }),
+        startToolCall: (toolUseId, name) => set((s) => {
+            s.messages.push({
+                id: `msg-${++nextId}`,
+                role: "assistant",
+                content: "",
+                toolCalls: [{ id: toolUseId, name, input: {}, status: "pending" }],
+            });
+        }),
+        appendToolInput: (toolUseId, partialJson) => set((s) => {
+            const tc = findToolCall(s.messages, toolUseId);
+            if (tc) {
+                tc.partialInput = (tc.partialInput ?? "") + partialJson;
+                tc.status = "streaming_input";
+            }
+        }),
+        finalizeToolCall: (toolUseId, name, input) => set((s) => {
+            const tc = findToolCall(s.messages, toolUseId);
+            if (tc) {
+                tc.name = name;
+                tc.input = input;
+                tc.status = "running";
+            }
+        }),
+        completeToolCall: (toolUseId, result) => set((s) => {
+            const tc = findToolCall(s.messages, toolUseId);
+            if (tc) {
+                tc.result = result;
+                tc.status = "complete";
+            }
+        }),
+        errorToolCall: (toolUseId, error) => set((s) => {
+            const tc = findToolCall(s.messages, toolUseId);
+            if (tc) {
+                tc.error = error;
+                tc.status = "error";
+            }
+        }),
+        setStreaming: (v) => set((s) => {
+            s.isStreaming = v;
+        }),
+        setThinking: (v) => set((s) => {
+            s.isThinking = v;
+        }),
+        reset: () => set((s) => {
+            s.sessionId = null;
+            s.messages = [];
+            s.isStreaming = false;
+            s.isThinking = false;
+            s.streamingText = "";
+        }),
+    })));
+}

package/dist/react/store.test.d.ts

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

package/dist/react/store.test.js

@@ -0,0 +1,113 @@
+import { describe, expect, it } from "vitest";
+import { createChatStore } from "./store.js";
+function firstToolCall(store) {
+    const tc = store.getState().messages[0].toolCalls?.[0];
+    expect(tc).toBeDefined();
+    return tc;
+}
+describe("ChatStore", () => {
+    it("addUserMessage appends a user message", () => {
+        const store = createChatStore();
+        store.getState().addUserMessage("hello");
+        const { messages } = store.getState();
+        expect(messages).toHaveLength(1);
+        expect(messages[0].role).toBe("user");
+        expect(messages[0].content).toBe("hello");
+        expect(messages[0].id).toMatch(/^msg-/);
+    });
+    it("appendStreamingText + flushStreamingText creates assistant message", () => {
+        const store = createChatStore();
+        store.getState().appendStreamingText("hel");
+        store.getState().appendStreamingText("lo");
+        expect(store.getState().streamingText).toBe("hello");
+        store.getState().flushStreamingText();
+        const { messages, streamingText } = store.getState();
+        expect(streamingText).toBe("");
+        expect(messages).toHaveLength(1);
+        expect(messages[0].role).toBe("assistant");
+        expect(messages[0].content).toBe("hello");
+    });
+    it("flushStreamingText appends to existing assistant message without tool calls", () => {
+        const store = createChatStore();
+        store.getState().appendStreamingText("first ");
+        store.getState().flushStreamingText();
+        store.getState().appendStreamingText("second");
+        store.getState().flushStreamingText();
+        const { messages } = store.getState();
+        expect(messages).toHaveLength(1);
+        expect(messages[0].content).toBe("first second");
+    });
+    it("flushStreamingText is a no-op when streamingText is empty", () => {
+        const store = createChatStore();
+        store.getState().flushStreamingText();
+        expect(store.getState().messages).toHaveLength(0);
+    });
+    it("startToolCall creates assistant message with pending tool call", () => {
+        const store = createChatStore();
+        store.getState().startToolCall("tc-1", "search");
+        const { messages } = store.getState();
+        expect(messages).toHaveLength(1);
+        expect(messages[0].role).toBe("assistant");
+        expect(messages[0].toolCalls).toHaveLength(1);
+        expect(messages[0].toolCalls?.[0]).toMatchObject({
+            id: "tc-1",
+            name: "search",
+            status: "pending",
+        });
+    });
+    it("appendToolInput accumulates partialInput and sets streaming_input status", () => {
+        const store = createChatStore();
+        store.getState().startToolCall("tc-1", "search");
+        store.getState().appendToolInput("tc-1", '{"q":');
+        store.getState().appendToolInput("tc-1", '"test"}');
+        const tc = firstToolCall(store);
+        expect(tc.partialInput).toBe('{"q":"test"}');
+        expect(tc.status).toBe("streaming_input");
+    });
+    it("finalizeToolCall sets input and running status", () => {
+        const store = createChatStore();
+        store.getState().startToolCall("tc-1", "search");
+        store.getState().finalizeToolCall("tc-1", "search", { q: "test" });
+        const tc = firstToolCall(store);
+        expect(tc.input).toEqual({ q: "test" });
+        expect(tc.status).toBe("running");
+    });
+    it("completeToolCall sets result and complete status", () => {
+        const store = createChatStore();
+        store.getState().startToolCall("tc-1", "search");
+        store.getState().completeToolCall("tc-1", '{"results":[]}');
+        const tc = firstToolCall(store);
+        expect(tc.result).toBe('{"results":[]}');
+        expect(tc.status).toBe("complete");
+    });
+    it("errorToolCall sets error and error status", () => {
+        const store = createChatStore();
+        store.getState().startToolCall("tc-1", "search");
+        store.getState().errorToolCall("tc-1", "timeout");
+        const tc = firstToolCall(store);
+        expect(tc.error).toBe("timeout");
+        expect(tc.status).toBe("error");
+    });
+    it("reset clears all state", () => {
+        const store = createChatStore();
+        store.getState().setSessionId("sess-1");
+        store.getState().addUserMessage("hi");
+        store.getState().setStreaming(true);
+        store.getState().setThinking(true);
+        store.getState().reset();
+        const s = store.getState();
+        expect(s.sessionId).toBeNull();
+        expect(s.messages).toHaveLength(0);
+        expect(s.isStreaming).toBe(false);
+        expect(s.isThinking).toBe(false);
+        expect(s.streamingText).toBe("");
+    });
+    it("addSystemMessage appends a system message", () => {
+        const store = createChatStore();
+        store.getState().addSystemMessage("Session ended");
+        const { messages } = store.getState();
+        expect(messages).toHaveLength(1);
+        expect(messages[0].role).toBe("system");
+        expect(messages[0].content).toBe("Session ended");
+    });
+});

package/dist/react/use-agent.d.ts

@@ -0,0 +1,11 @@
+import type { CustomEvent } from "../types.js";
+import type { ChatStore } from "./store.js";
+export interface UseAgentConfig {
+    endpoint?: string;
+    onCustomEvent?: (event: CustomEvent) => void;
+}
+export interface UseAgentReturn {
+    sessionId: string | null;
+    sendMessage: (text: string) => Promise<void>;
+}
+export declare function useAgent(store: ChatStore, config?: UseAgentConfig): UseAgentReturn;

package/dist/react/use-agent.js

@@ -0,0 +1,96 @@
+import { useCallback, useEffect, useRef, useSyncExternalStore } from "react";
+export function useAgent(store, config) {
+    const endpoint = config?.endpoint ?? "/api";
+    const onCustomEvent = config?.onCustomEvent;
+    const eventSourceRef = useRef(null);
+    const sessionId = useSyncExternalStore(store.subscribe, () => store.getState().sessionId);
+    useEffect(() => {
+        let cancelled = false;
+        async function init() {
+            const res = await fetch(`${endpoint}/sessions`, { method: "POST" });
+            const data = await res.json();
+            if (!cancelled)
+                store.getState().setSessionId(data.sessionId);
+        }
+        init();
+        return () => {
+            cancelled = true;
+        };
+    }, [endpoint, store]);
+    useEffect(() => {
+        if (!sessionId)
+            return;
+        const es = new EventSource(`${endpoint}/sessions/${sessionId}/events`);
+        eventSourceRef.current = es;
+        es.addEventListener("message_start", () => {
+            store.getState().setThinking(true);
+        });
+        es.addEventListener("text_delta", (e) => {
+            store.getState().setThinking(false);
+            const { text } = JSON.parse(e.data);
+            store.getState().appendStreamingText(text);
+        });
+        es.addEventListener("tool_start", (e) => {
+            store.getState().setThinking(false);
+            store.getState().flushStreamingText();
+            const { id, name } = JSON.parse(e.data);
+            store.getState().startToolCall(id, name);
+        });
+        es.addEventListener("tool_input_delta", (e) => {
+            const { id, partialJson } = JSON.parse(e.data);
+            store.getState().appendToolInput(id, partialJson);
+        });
+        es.addEventListener("tool_call", (e) => {
+            store.getState().flushStreamingText();
+            const { id, name, input } = JSON.parse(e.data);
+            store.getState().finalizeToolCall(id, name, input);
+        });
+        es.addEventListener("tool_result", (e) => {
+            const { toolUseId, result } = JSON.parse(e.data);
+            store.getState().completeToolCall(toolUseId, result);
+            if (store.getState().isStreaming) {
+                store.getState().setThinking(true);
+            }
+        });
+        es.addEventListener("session_error", (e) => {
+            store.getState().flushStreamingText();
+            store.getState().setThinking(false);
+            const { subtype } = JSON.parse(e.data);
+            store.getState().addSystemMessage(`Session ended: ${subtype}`);
+            store.getState().setStreaming(false);
+        });
+        es.addEventListener("turn_complete", () => {
+            store.getState().flushStreamingText();
+            store.getState().setThinking(false);
+            store.getState().setStreaming(false);
+        });
+        es.addEventListener("error", () => {
+            if (es.readyState === EventSource.CLOSED) {
+                store.getState().flushStreamingText();
+                store.getState().setStreaming(false);
+            }
+        });
+        if (onCustomEvent) {
+            es.addEventListener("custom", (e) => {
+                onCustomEvent(JSON.parse(e.data));
+            });
+        }
+        return () => {
+            es.close();
+            eventSourceRef.current = null;
+        };
+    }, [sessionId, endpoint, store, onCustomEvent]);
+    const sendMessage = useCallback(async (text) => {
+        if (!sessionId)
+            return;
+        store.getState().addUserMessage(text);
+        store.getState().setStreaming(true);
+        store.getState().setThinking(true);
+        await fetch(`${endpoint}/sessions/${sessionId}/messages`, {
+            method: "POST",
+            headers: { "Content-Type": "application/json" },
+            body: JSON.stringify({ text }),
+        });
+    }, [sessionId, endpoint, store]);
+    return { sessionId, sendMessage };
+}

package/dist/server/index.d.ts

@@ -0,0 +1,5 @@
+export type { CustomEvent, SSEEvent } from "../types.js";
+export { PushChannel } from "./push-channel.js";
+export { createAgentRouter } from "./router.js";
+export { type Session, type SessionInit, SessionManager } from "./session.js";
+export { MessageTranslator, sseEncode, streamSession, type TranslatorConfig, } from "./translator.js";

package/dist/server/index.js

@@ -0,0 +1,4 @@
+export { PushChannel } from "./push-channel.js";
+export { createAgentRouter } from "./router.js";
+export { SessionManager } from "./session.js";
+export { MessageTranslator, sseEncode, streamSession, } from "./translator.js";

package/dist/server/push-channel.d.ts

@@ -0,0 +1,8 @@
+export declare class PushChannel<T> implements AsyncIterable<T> {
+    private queue;
+    private resolve;
+    private done;
+    push(value: T): void;
+    close(): void;
+    [Symbol.asyncIterator](): AsyncIterator<T>;
+}

package/dist/server/push-channel.js

@@ -0,0 +1,40 @@
+export class PushChannel {
+    queue = [];
+    resolve = null;
+    done = false;
+    push(value) {
+        if (this.done)
+            return;
+        if (this.resolve) {
+            const r = this.resolve;
+            this.resolve = null;
+            r({ value, done: false });
+        }
+        else {
+            this.queue.push(value);
+        }
+    }
+    close() {
+        this.done = true;
+        if (this.resolve) {
+            const r = this.resolve;
+            this.resolve = null;
+            r({ value: undefined, done: true });
+        }
+    }
+    [Symbol.asyncIterator]() {
+        return {
+            next: () => {
+                if (this.queue.length > 0) {
+                    return Promise.resolve({ value: this.queue.shift(), done: false });
+                }
+                if (this.done) {
+                    return Promise.resolve({ value: undefined, done: true });
+                }
+                return new Promise((resolve) => {
+                    this.resolve = resolve;
+                });
+            },
+        };
+    }
+}

package/dist/server/push-channel.test.d.ts

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

package/dist/server/push-channel.test.js

@@ -0,0 +1,57 @@
+import { describe, expect, it } from "vitest";
+import { PushChannel } from "./push-channel.js";
+describe("PushChannel", () => {
+    it("queues values pushed before consuming", async () => {
+        const ch = new PushChannel();
+        ch.push(1);
+        ch.push(2);
+        ch.push(3);
+        ch.close();
+        const values = [];
+        for await (const v of ch) {
+            values.push(v);
+        }
+        expect(values).toEqual([1, 2, 3]);
+    });
+    it("resolves immediately when push is called while awaiting", async () => {
+        const ch = new PushChannel();
+        const promise = (async () => {
+            const iter = ch[Symbol.asyncIterator]();
+            const result = await iter.next();
+            return result.value;
+        })();
+        // Allow the iterator to set up its pending promise
+        await new Promise((r) => setTimeout(r, 0));
+        ch.push("hello");
+        expect(await promise).toBe("hello");
+        ch.close();
+    });
+    it("ends iteration on close", async () => {
+        const ch = new PushChannel();
+        ch.close();
+        const iter = ch[Symbol.asyncIterator]();
+        const result = await iter.next();
+        expect(result.done).toBe(true);
+    });
+    it("ignores pushes after close", async () => {
+        const ch = new PushChannel();
+        ch.push(1);
+        ch.close();
+        ch.push(2);
+        const values = [];
+        for await (const v of ch) {
+            values.push(v);
+        }
+        expect(values).toEqual([1]);
+    });
+    it("yields all queued values then ends on close", async () => {
+        const ch = new PushChannel();
+        ch.push("a");
+        ch.push("b");
+        const iter = ch[Symbol.asyncIterator]();
+        expect((await iter.next()).value).toBe("a");
+        expect((await iter.next()).value).toBe("b");
+        ch.close();
+        expect((await iter.next()).done).toBe(true);
+    });
+});

package/dist/server/router.d.ts

@@ -0,0 +1,8 @@
+import { Hono } from "hono";
+import type { SessionManager } from "./session.js";
+import { type MessageTranslator } from "./translator.js";
+export declare function createAgentRouter<TCtx>(config: {
+    sessions: SessionManager<TCtx>;
+    translator: MessageTranslator<TCtx>;
+    basePath?: string;
+}): Hono;

package/dist/server/router.js

@@ -0,0 +1,52 @@
+import { Hono } from "hono";
+import { cors } from "hono/cors";
+import { sseEncode, streamSession } from "./translator.js";
+export function createAgentRouter(config) {
+    const { sessions, translator, basePath = "/api" } = config;
+    const app = new Hono();
+    app.use(`${basePath}/*`, cors({ origin: "*" }));
+    app.post(`${basePath}/sessions`, (c) => {
+        const session = sessions.create();
+        return c.json({ sessionId: session.id });
+    });
+    app.post(`${basePath}/sessions/:id/messages`, async (c) => {
+        const session = sessions.get(c.req.param("id"));
+        if (!session)
+            return c.json({ error: "Session not found" }, 404);
+        const body = await c.req.json();
+        if (!body.text?.trim())
+            return c.json({ error: "Message text required" }, 400);
+        session.pushMessage(body.text.trim());
+        return c.json({ ok: true });
+    });
+    app.get(`${basePath}/sessions/:id/events`, (c) => {
+        const session = sessions.get(c.req.param("id"));
+        if (!session)
+            return c.json({ error: "Session not found" }, 404);
+        const stream = new ReadableStream({
+            async start(controller) {
+                const encoder = new TextEncoder();
+                try {
+                    for await (const evt of streamSession(session, translator)) {
+                        controller.enqueue(encoder.encode(sseEncode(evt)));
+                    }
+                }
+                catch (err) {
+                    const message = err instanceof Error ? err.message : "Unknown error";
+                    controller.enqueue(encoder.encode(sseEncode({ event: "error", data: JSON.stringify({ message }) })));
+                }
+                finally {
+                    controller.close();
+                }
+            },
+        });
+        return new Response(stream, {
+            headers: {
+                "Content-Type": "text/event-stream",
+                "Cache-Control": "no-cache",
+                Connection: "keep-alive",
+            },
+        });
+    });
+    return app;
+}

package/dist/server/session.d.ts

@@ -0,0 +1,32 @@
+import { query } from "@anthropic-ai/claude-agent-sdk";
+type SDKMessage = ReturnType<typeof query> extends AsyncGenerator<infer T> ? T : never;
+export interface SessionInit<TCtx> {
+    context: TCtx;
+    model: string;
+    systemPrompt: string;
+    mcpServers?: Record<string, unknown>;
+    tools?: unknown[];
+    allowedTools?: string[];
+    maxTurns?: number;
+    permissionMode?: "default" | "plan" | "bypassPermissions";
+}
+export interface Session<TCtx> {
+    id: string;
+    context: TCtx;
+    pushMessage(text: string): void;
+    messageIterator: AsyncIterable<SDKMessage>;
+    abort(): void;
+    createdAt: number;
+    lastActivityAt: number;
+}
+export declare class SessionManager<TCtx> {
+    private sessions;
+    private factory;
+    private idleTimeoutMs;
+    constructor(factory: () => SessionInit<TCtx>, idleTimeoutMs?: number);
+    create(): Session<TCtx>;
+    get(id: string): Session<TCtx> | undefined;
+    delete(id: string): void;
+    cleanup(): void;
+}
+export {};