kernl 0.2.1 → 0.6.0

package/dist/thread/thread.js

@@ -1,48 +1,111 @@
 import assert from "assert";
 import { Context } from "../context";
-import { FAILED, RUNNING, STOPPED, } from "@kernl-sdk/protocol";
+import { logger } from "../lib/logger";
+import { FAILED, RUNNING, STOPPED, message, } from "@kernl-sdk/protocol";
 import { randomID, filter } from "@kernl-sdk/shared/lib";
-import { notDelta, getFinalResponse, getIntentions, parseFinalResponse, } from "./utils";
+import { tevent, notDelta, getIntentions, getFinalResponse, parseFinalResponse, } from "./utils";
 /**
  * A thread drives the execution loop for an agent.
+ *
+ * Ground principles:
+ *
+ *   1) Event log is source of truth.
+ *      - Persistent storage (e.g. Postgres) is treated as an append-only per-thread log of `ThreadEvent`s:
+ *        monotonic `seq`, no gaps, no updates/deletes.
+ *      - `Thread.state`, `tick`, etc. are projections of that log, not an alternative source of truth.
+ *
+ *   2) Single writer per thread.
+ *      - At most one executor is allowed for a given `tid` at a time.
+ *      - Callers are responsible for enforcing this (e.g. locking/versioning) so two processes cannot
+ *        interleave or race on `seq` or state.
+ *
+ *   3) Persist before use / observation.
+ *      - Before an event can:
+ *        - influence a future tick (i.e. be part of `history` fed back into the model), or
+ *        - be considered “delivered” to a client,
+ *        it SHOULD be durably written to storage when storage is configured.
+ *
+ *   4) Transaction boundaries match semantic steps.
+ *      - The intended strategy is to buffer within a tick, then atomically persist all new events + state
+ *        at the end of `tick()`.
+ *      - After a crash, you only ever see whole ticks or none, never half a tick, from the store’s
+ *        point of view.
+ *
+ *   5) Recovery is replay.
+ *      - On restart, callers rebuild a `Thread` from the stored event log (plus optional snapshots).
+ *      - Any incomplete tick or pending tool call is handled by a clear, deterministic policy at a
+ *        higher layer (e.g. re-run, mark failed, or require manual intervention).
+ *
+ * On storage failures:
+ *
+ *   “If storage is configured, it is authoritative” → fail hard on persist errors rather than
+ *   treating persistence as best-effort.
+ *
+ *   If a storage implementation is present, `persist(...)` is expected to throw on failure, and
+ *   that error should bubble out of `_execute()` / `stream()` and stop the thread.
  */
 export class Thread {
-    kernl;
-    id;
+    tid;
+    namespace;
     agent;
     context;
     model; /* inherited from the agent unless specified */
     parent; /* parent task which spawned this thread */
-    mode; /* TODO */
-    input; /* the initial input for the thread */
+    createdAt;
+    updatedAt;
+    metadata;
     // readonly stats: ThreadMetrics;
     /* state */
-    _tick;
+    _tick; /* number of LLM roundtrips */
+    _seq; /* monotonic event sequence */
     state;
+    cpbuf; /* checkpoint buffer - events pending persistence */
+    persisted; /* indicates thread was hydrated from storage */
     history;
     abort;
-    constructor(kernl, agent, input, options) {
-        this.id = `tid_${randomID()}`;
-        this.agent = agent;
-        this.context = options?.context ?? new Context();
-        this.kernl = kernl;
-        this.parent = options?.task ?? null;
-        this.model = options?.model ?? agent.model;
-        this.mode = "blocking"; // (TODO): add streaming
-        this.input = input;
-        this._tick = 0;
-        this.state = STOPPED;
-        this.history = input;
+    storage;
+    constructor(options) {
+        this.tid = options.tid ?? `tid_${randomID()}`;
+        this.namespace = options.namespace ?? "kernl";
+        this.agent = options.agent;
+        this.context =
+            options.context ?? new Context(this.namespace, {});
+        this.parent = options.task ?? null;
+        this.model = options.model ?? options.agent.model;
+        this.storage = options.storage;
+        this.createdAt = options.createdAt ?? new Date();
+        this.updatedAt = options.updatedAt ?? new Date();
+        this.metadata = options.metadata ?? null;
+        this._tick = options.tick ?? 0;
+        this._seq = -1;
+        this.state = options.state ?? STOPPED;
+        this.cpbuf = [];
+        this.persisted = options.persisted ?? false;
+        this.history = options.history ?? [];
+        // seek to latest seq (not persisted)
+        if (this.history.length > 0) {
+            this._seq = Math.max(...this.history.map((e) => e.seq));
+        }
+        // append initial input if provided (for new threads)
+        if (options.input && options.input.length > 0) {
+            this.append(...options.input);
+        }
     }
     /**
-     * Blocking execution loop - runs until terminal state or interruption
+     * Blocking execution - runs until terminal state or interruption
      */
     async execute() {
         for await (const _event of this.stream()) {
             // just consume the stream (already in history in _execute())
         }
-        // extract final response from accumulated history
-        const text = getFinalResponse(this.history);
+        // filter for language model items
+        const items = this.history
+            .filter((e) => e.kind !== "system")
+            .map((e) => {
+            const { tid, seq, timestamp, metadata, ...item } = e;
+            return item;
+        });
+        const text = getFinalResponse(items);
         assert(text, "_execute continues until text !== null"); // (TODO): consider preventing infinite loops here
         const parsed = parseFinalResponse(text, this.agent.responseType);
         return { response: parsed, state: this.state };
@@ -56,6 +119,8 @@ export class Thread {
         }
         this.state = RUNNING;
         this.abort = new AbortController();
+        await this.checkpoint(); /* c1: persist RUNNING state + initial input */
+        yield { kind: "stream-start" }; // always yield start immediately
         try {
             yield* this._execute();
         }
@@ -65,57 +130,57 @@ export class Thread {
         finally {
             this.state = STOPPED;
             this.abort = undefined;
+            await this.checkpoint(); /* c4: final checkpoint - persist STOPPED state */
         }
     }
     /**
-     * Cancel the running thread
-     */
-    cancel() {
-        this.abort?.abort();
-    }
-    /**
-     * Append a new event to the thread history
-     */
-    append(event) {
-        this.history.push(event);
-    }
-    /**
-     * Main execution loop - always yields events, callers can propagate or discard (as in execute())
+     * Main execution loop - always yields events, callers can propagate or discard.
      *
      * NOTE: Streaming structured output deferred for now. Prioritizing correctness + simplicity,
      * and unclear what use cases there would actually be for streaming a structured output (other than maybe gen UI).
      */
     async *_execute() {
         for (;;) {
+            let err = false;
             if (this.abort?.signal.aborted) {
                 return;
             }
             const events = [];
             for await (const e of this.tick()) {
+                if (e.kind === "error") {
+                    err = true;
+                    logger.error(e.error); // (TODO): onError callback in options
+                }
                 // we don't want deltas in the history
                 if (notDelta(e)) {
                     events.push(e);
-                    this.history.push(e);
+                    this.append(e);
                 }
                 yield e;
             }
-            // if model returns a message with no action intentions -> terminal state
+            // if an error event occurred → terminate
+            if (err) {
+                return;
+            }
+            // if model returns a message with no action intentions → terminal state
             const intentions = getIntentions(events);
             if (!intentions) {
                 const text = getFinalResponse(events);
                 if (!text)
                     continue; // run again, policy-dependent? (how to ensure no infinite loop here?)
+                await this.checkpoint(); /* c2: terminal tick - no tool calls */
                 // await this.agent.runOutputGuardails(context, state);
                 // this.kernl.emit("thread.terminated", context, output);
                 return;
             }
-            // perform actions intended by the model
+            // perform intended actions
             const { actions, pendingApprovals } = await this.performActions(intentions);
-            // yield action events
+            // append + yield action events
             for (const a of actions) {
-                this.history.push(a);
+                this.append(a);
                 yield a;
             }
+            await this.checkpoint(); /* c3: tick complete */
             if (pendingApprovals.length > 0) {
                 // publish a batch approval request containing all of them
                 //
@@ -138,22 +203,100 @@ export class Thread {
         // (TODO): check limits (if this._tick > this.limits.maxTicks)
         // (TODO): run input guardrails on first tick (if this._tick === 1)
         const req = await this.prepareModelRequest(this.history);
-        // try to stream if model supports it
-        if (this.model.stream) {
-            const stream = this.model.stream(req);
-            for await (const event of stream) {
-                yield event; // [text-delta, tool-call, message, reasoning, ...]
+        try {
+            if (this.model.stream) {
+                const stream = this.model.stream(req);
+                for await (const event of stream) {
+                    yield event; // [text-delta, tool-call, message, reasoning, ...]
+                }
             }
-        }
-        else {
-            // fallback: blocking generate, yield events as batch
-            const res = await this.model.generate(req);
-            for (const event of res.content) {
-                yield event;
+            else {
+                // fallback: blocking generate, yield events as batch
+                const res = await this.model.generate(req);
+                for (const event of res.content) {
+                    yield event;
+                }
+                // (TODO): this.stats.usage.add(res.usage)
             }
-            // (TODO): track usage (this.stats.usage.add(res.usage))
+        }
+        catch (error) {
+            yield {
+                kind: "error",
+                error: error instanceof Error ? error : new Error(String(error)),
+            };
         }
     }
+    /**
+     * Persist current thread state to storage.
+     *
+     * - If storage is configured, it is authoritative - failures throw and halt execution.
+     * - No-op if storage is not configured.
+     */
+    async checkpoint() {
+        if (!this.storage) {
+            logger.warn("thread: storage is not configured, thread will not be persisted");
+            return;
+        }
+        // insert thread record on first persist for new threads
+        if (!this.persisted) {
+            await this.storage.insert({
+                id: this.tid,
+                namespace: this.namespace,
+                agentId: this.agent.id,
+                parentTaskId: this.parent?.id ?? null,
+                model: `${this.model.provider}/${this.model.modelId}`,
+                context: this.context.context,
+                tick: this._tick,
+                state: this.state,
+                metadata: this.metadata,
+            });
+            this.persisted = true;
+        }
+        // append + drain events from checkpoint buffer
+        if (this.cpbuf.length > 0) {
+            await this.storage.append(this.cpbuf);
+            this.cpbuf = [];
+        }
+        // update thread state
+        await this.storage.update(this.tid, {
+            state: this.state,
+            tick: this._tick,
+            context: this.context,
+            metadata: this.metadata,
+        });
+    }
+    /**
+     * Append one or more items to history + enrich w/ runtime headers.
+     *
+     * Core rule:
+     *
+     * > An event becomes a ThreadEvent (and gets seq/timestamp) exactly when it is appended to history. <
+     */
+    append(...items) {
+        const events = [];
+        for (const item of items) {
+            const seq = ++this._seq;
+            const e = tevent({
+                tid: this.tid,
+                seq,
+                kind: item.kind,
+                data: item,
+            });
+            this.history.push(e);
+            this.cpbuf.push(e);
+            events.push(e);
+        }
+        return events;
+    }
+    /**
+     * Cancel the running thread
+     */
+    cancel() {
+        this.abort?.abort();
+    }
+    // ----------------------------
+    // utils
+    // ----------------------------
     /**
      * Perform the actions returned by the model
      */
@@ -179,10 +322,8 @@ export class Thread {
                 e.state === "requires_approval" // (TODO): fix this
             ) {
                 // Find the original tool call for this pending approval
-                const originalCall = intentions.toolCalls.find((call) => call.callId === e.callId);
-                if (originalCall) {
-                    pendingApprovals.push(originalCall);
-                }
+                const call = intentions.toolCalls.find((c) => c.callId === e.callId);
+                call && pendingApprovals.push(call);
             }
             else {
                 actions.push(e);
@@ -209,7 +350,7 @@ export class Thread {
                 assert(tool.type === "function", `Tool ${call.id} is a hosted tool and should not be executed locally`);
                 // (TMP) - passing the approval status through the context until actions system
                 // is refined
-                const ctx = new Context(this.context.context);
+                const ctx = new Context(this.namespace, this.context.context);
                 ctx.approve(call.callId); // mark this call as approved
                 const res = await tool.invoke(ctx, call.arguments, call.callId);
                 return {
@@ -222,7 +363,6 @@ export class Thread {
                 };
             }
             catch (error) {
-                // Handles both tool not found AND any execution errors
                 return {
                     kind: "tool-result",
                     callId: call.callId,
@@ -241,27 +381,25 @@ export class Thread {
         let settings = {
             ...this.agent.modelSettings,
         };
-        // // TODO: what do we want to do with this?
+        // (TODO): what do we want to do with this?
         // settings = maybeResetToolChoice(this.agent, this.state.toolUse, settings);
         const system = await this.agent.instructions(this.context);
+        // filter for model items + strip event headers
+        const items = history
+            .filter((e) => e.kind !== "system") // system events are not sent to model
+            .map((event) => {
+            const { id, tid, seq, timestamp, metadata, ...item } = event;
+            return item;
+        });
         const input = system
-            ? [
-                // (TODO): add message(role, text) helper
-                {
-                    kind: "message",
-                    id: randomID(),
-                    role: "system",
-                    content: [{ kind: "text", text: system }],
-                },
-                ...history, // (TODO): filter for LanguageModelItem specifically - there may be other thread events
-            ]
-            : history;
-        // TODO: apply custom input filters - arguably want global + agent-scoped -> apply in a middleware-like chain
+            ? [message({ role: "system", text: system }), ...items]
+            : items;
+        // (TODO): apply custom input filters - arguably want global + agent-scoped -> apply in a middleware-like chain
         // const filtered = await applyInputFilters(inputWithSystem, context);
         const filtered = input;
         // serialize action repertoire
-        const allTools = await this.agent.tools(this.context);
-        const enabled = await filter(allTools, async (tool) => await tool.isEnabled(this.context, this.agent));
+        const all = await this.agent.tools(this.context);
+        const enabled = await filter(all, async (tool) => await tool.isEnabled(this.context, this.agent));
         const tools = enabled.map((tool) => tool.serialize());
         return {
             input: filtered,

package/dist/thread/utils.d.ts

@@ -1,26 +1,54 @@
 import type { ResolvedAgentResponse } from "../guardrail";
-import { ToolCall } from "@kernl-sdk/protocol";
+import { ToolCall, LanguageModelItem } from "@kernl-sdk/protocol";
 import type { AgentResponseType } from "../types/agent";
-import type { ThreadEvent, ThreadStreamEvent, ActionSet } from "../types/thread";
+import type { ThreadEvent, ThreadStreamEvent, ActionSet, PublicThreadEvent } from "../types/thread";
 /**
- * Check if an event represents an intention (action to be performed)
+ * Create a ThreadEvent from a LanguageModelItem with thread metadata.
+ *
+ * @example
+ * ```typescript
+ * tevent({
+ *   kind: "message",
+ *   seq: 0,
+ *   tid: "tid_123",
+ *   data: message({role: "user", text: "hello"}),
+ * })
+ * // → {kind: "message", role: "user", content: [...], id: "message:msg_xyz", tid: "tid_123", seq: 0, timestamp: Date}
+ * ```
+ */
+export declare function tevent(event: {
+    seq: number;
+    tid: string;
+    kind: ThreadEvent["kind"];
+    data: LanguageModelItem | null;
+    id?: string;
+    timestamp?: Date;
+    metadata?: Record<string, unknown>;
+}): ThreadEvent;
+/**
+ * Check if an event is a tool call
  */
-export declare function isActionIntention(event: ThreadEvent): event is ToolCall;
+export declare function isActionIntention(event: LanguageModelItem): event is ToolCall;
 /**
  * Extract action intentions from a list of events.
  * Returns ActionSet if there are any tool calls, null otherwise.
  */
-export declare function getIntentions(events: ThreadEvent[]): ActionSet | null;
+export declare function getIntentions(events: LanguageModelItem[]): ActionSet | null;
 /**
  * Check if an event is NOT a delta/start/end event (i.e., a complete item).
  * Returns true for complete items: Message, Reasoning, ToolCall, ToolResult
  */
-export declare function notDelta(event: ThreadStreamEvent): event is ThreadEvent;
+export declare function notDelta(event: ThreadStreamEvent): event is LanguageModelItem;
+/**
+ * Check if an event is public/client-facing (not internal).
+ * Filters out internal system events that clients don't need.
+ */
+export declare function isPublicEvent(event: ThreadEvent): event is PublicThreadEvent;
 /**
- * Extract the final text response from a list of events.
+ * Extract the final text response from a list of items.
  * Returns null if no assistant message with text content is found.
  */
-export declare function getFinalResponse(events: ThreadEvent[]): string | null;
+export declare function getFinalResponse(items: LanguageModelItem[]): string | null;
 /**
  * (TODO): This should run through the language model's native structured output (if avail)
  *

package/dist/thread/utils.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"utils.d.ts","sourceRoot":"","sources":["../../src/thread/utils.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,aAAa,CAAC;AAIzD,OAAO,EAAE,QAAQ,EAAE,MAAM,qBAAqB,CAAC;AAI/C,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,eAAe,CAAC;AACvD,OAAO,KAAK,EAAE,WAAW,EAAE,iBAAiB,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAEhF;;GAEG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,WAAW,GAAG,KAAK,IAAI,QAAQ,CAEvE;AAED;;;GAGG;AACH,wBAAgB,aAAa,CAAC,MAAM,EAAE,WAAW,EAAE,GAAG,SAAS,GAAG,IAAI,CAGrE;AAED;;;GAGG;AACH,wBAAgB,QAAQ,CAAC,KAAK,EAAE,iBAAiB,GAAG,KAAK,IAAI,WAAW,CAYvE;AAED;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,WAAW,EAAE,GAAG,MAAM,GAAG,IAAI,CAcrE;AAED;;;;;;;;GAQG;AACH,wBAAgB,kBAAkB,CAAC,SAAS,SAAS,iBAAiB,EACpE,IAAI,EAAE,MAAM,EACZ,YAAY,EAAE,SAAS,GACtB,qBAAqB,CAAC,SAAS,CAAC,CAsBlC"}
+{"version":3,"file":"utils.d.ts","sourceRoot":"","sources":["../../src/thread/utils.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,aAAa,CAAC;AAIzD,OAAO,EAAE,QAAQ,EAAE,iBAAiB,EAAE,MAAM,qBAAqB,CAAC;AAIlE,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,eAAe,CAAC;AACvD,OAAO,KAAK,EACV,WAAW,EAEX,iBAAiB,EACjB,SAAS,EACT,iBAAiB,EAClB,MAAM,gBAAgB,CAAC;AAExB;;;;;;;;;;;;;GAaG;AACH,wBAAgB,MAAM,CAAC,KAAK,EAAE;IAC5B,GAAG,EAAE,MAAM,CAAC;IACZ,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,EAAE,WAAW,CAAC,MAAM,CAAC,CAAC;IAC1B,IAAI,EAAE,iBAAiB,GAAG,IAAI,CAAC;IAC/B,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,SAAS,CAAC,EAAE,IAAI,CAAC;IACjB,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACpC,GAAG,WAAW,CAad;AAED;;GAEG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,iBAAiB,GAAG,KAAK,IAAI,QAAQ,CAE7E;AAED;;;GAGG;AACH,wBAAgB,aAAa,CAAC,MAAM,EAAE,iBAAiB,EAAE,GAAG,SAAS,GAAG,IAAI,CAG3E;AAED;;;GAGG;AACH,wBAAgB,QAAQ,CAAC,KAAK,EAAE,iBAAiB,GAAG,KAAK,IAAI,iBAAiB,CAY7E;AAED;;;GAGG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,WAAW,GAAG,KAAK,IAAI,iBAAiB,CAc5E;AAED;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,iBAAiB,EAAE,GAAG,MAAM,GAAG,IAAI,CAc1E;AAED;;;;;;;;GAQG;AACH,wBAAgB,kBAAkB,CAAC,SAAS,SAAS,iBAAiB,EACpE,IAAI,EAAE,MAAM,EACZ,YAAY,EAAE,SAAS,GACtB,qBAAqB,CAAC,SAAS,CAAC,CAsBlC"}

package/dist/thread/utils.js

@@ -1,8 +1,35 @@
 /* lib */
-import { json } from "@kernl-sdk/shared/lib";
+import { json, randomID } from "@kernl-sdk/shared/lib";
 import { ModelBehaviorError } from "../lib/error";
 /**
- * Check if an event represents an intention (action to be performed)
+ * Create a ThreadEvent from a LanguageModelItem with thread metadata.
+ *
+ * @example
+ * ```typescript
+ * tevent({
+ *   kind: "message",
+ *   seq: 0,
+ *   tid: "tid_123",
+ *   data: message({role: "user", text: "hello"}),
+ * })
+ * // → {kind: "message", role: "user", content: [...], id: "message:msg_xyz", tid: "tid_123", seq: 0, timestamp: Date}
+ * ```
+ */
+export function tevent(event) {
+    const iid = event.data ? event.data.id : undefined;
+    const defaultId = iid ? `${event.kind}:${iid}` : randomID();
+    return {
+        ...(event.data || {}),
+        kind: event.kind,
+        id: event.id ?? defaultId,
+        tid: event.tid,
+        seq: event.seq,
+        timestamp: event.timestamp ?? new Date(),
+        metadata: event.metadata ?? {},
+    };
+}
+/**
+ * Check if an event is a tool call
  */
 export function isActionIntention(event) {
     return event.kind === "tool-call";
@@ -32,16 +59,33 @@ export function notDelta(event) {
     }
 }
 /**
- * Extract the final text response from a list of events.
+ * Check if an event is public/client-facing (not internal).
+ * Filters out internal system events that clients don't need.
+ */
+export function isPublicEvent(event) {
+    switch (event.kind) {
+        case "message":
+        case "reasoning":
+        case "tool-call":
+        case "tool-result":
+            return true;
+        case "system":
+            return false;
+        default:
+            return false;
+    }
+}
+/**
+ * Extract the final text response from a list of items.
  * Returns null if no assistant message with text content is found.
  */
-export function getFinalResponse(events) {
+export function getFinalResponse(items) {
     // Scan backwards for the last assistant message
-    for (let i = events.length - 1; i >= 0; i--) {
-        const event = events[i];
-        if (event.kind === "message" && event.role === "assistant") {
+    for (let i = items.length - 1; i >= 0; i--) {
+        const item = items[i];
+        if (item.kind === "message" && item.role === "assistant") {
             // Extract text from content parts
-            for (const part of event.content) {
+            for (const part of item.content) {
                 if (part.kind === "text") {
                     return part.text;
                 }

package/dist/tool/__tests__/fixtures.js

@@ -5,7 +5,7 @@ import { tool, HostedTool } from "../tool";
  * Create a minimal mock context for testing
  */
 export const mockContext = (data) => {
-    return new Context(data ?? {});
+    return new Context("test-namespace", data ?? {});
 };
 /**
  * Simple string tool with no parameters

package/dist/tool/__tests__/toolkit.test.js

@@ -83,22 +83,22 @@ describe("FunctionToolkit", () => {
             const toolkit = new FunctionToolkit({ id: "test", tools: [simpleStringTool] });
             const serialized = (await toolkit.list()).map((tool) => tool.serialize());
             expect(serialized).toHaveLength(1);
-            expect(serialized[0]).toEqual({
-                type: "function",
-                name: simpleStringTool.name,
+            expect(serialized[0]).toMatchObject({
+                kind: "function",
+                name: simpleStringTool.id,
                 description: simpleStringTool.description,
-                parameters: simpleStringTool.parameters,
             });
+            expect(serialized[0].parameters).toBeDefined();
         });
         it("should serialize hosted tools correctly", async () => {
             const toolkit = new FunctionToolkit({ id: "test", tools: [mockHostedTool] });
             const serialized = (await toolkit.list()).map((tool) => tool.serialize());
             expect(serialized).toHaveLength(1);
             expect(serialized[0]).toEqual({
-                type: "hosted-tool",
+                kind: "provider-defined",
                 id: mockHostedTool.id,
                 name: mockHostedTool.name,
-                providerData: mockHostedTool.providerData,
+                args: mockHostedTool.providerData,
             });
         });
         it("should serialize both function and hosted tools", async () => {
@@ -107,17 +107,20 @@ describe("FunctionToolkit", () => {
             expect(serialized).toHaveLength(2);
             // Check both tools are present (order not guaranteed with Map)
             expect(serialized).toContainEqual({
-                type: "hosted-tool",
+                kind: "provider-defined",
                 id: mockHostedTool.id,
                 name: mockHostedTool.name,
-                providerData: mockHostedTool.providerData,
+                args: mockHostedTool.providerData,
             });
-            expect(serialized).toContainEqual({
-                type: "function",
-                name: simpleStringTool.name,
+            // Check that function tool is present with correct structure
+            const functionTool = serialized.find((t) => t.kind === "function");
+            expect(functionTool).toBeDefined();
+            expect(functionTool).toMatchObject({
+                kind: "function",
+                name: simpleStringTool.id,
                 description: simpleStringTool.description,
-                parameters: simpleStringTool.parameters,
             });
+            expect(functionTool.parameters).toBeDefined();
         });
         it("should handle hosted tools without providerData", async () => {
             const toolkit = new FunctionToolkit({ id: "test", tools: [anotherHostedTool] });

package/dist/tool/tool.js

@@ -120,9 +120,9 @@ export class FunctionTool extends BaseTool {
             kind: "function",
             name: this.id,
             description: this.description,
-            parameters: (this.parameters
-                ? z.toJSONSchema(this.parameters, { target: "draft-7" })
-                : {}), // JSONSchema7 - target: 'draft-7' produces this
+            parameters: z.toJSONSchema(this.parameters ?? z.object({}), {
+                target: "draft-7",
+            }), // Use empty object if no parameters (matches AI SDK)
         };
     }
 }