kernl 0.2.1 → 0.6.1

package/dist/agent/__tests__/run.test.js

@@ -0,0 +1,357 @@
+import { describe, it, expect } from "vitest";
+import { Agent } from "../../agent.js";
+import { Kernl } from "../../kernl.js";
+import { createMockModel } from "../../thread/__tests__/fixtures/mock-model.js";
+import { MisconfiguredError } from "../../lib/error.js";
+import { message } from "@kernl-sdk/protocol";
+import { InMemoryStorage } from "../../storage/in-memory.js";
+describe("Agent.run() lifecycle", () => {
+    describe("Storage wiring", () => {
+        it("should pass storage to new Thread when creating", async () => {
+            const storage = new InMemoryStorage();
+            const model = createMockModel(async () => ({
+                content: [message({ role: "assistant", text: "Done" })],
+                finishReason: "stop",
+                usage: { inputTokens: 2, outputTokens: 2, totalTokens: 4 },
+                warnings: [],
+            }));
+            const agent = new Agent({
+                id: "test-agent",
+                name: "Test",
+                instructions: "Test",
+                model,
+            });
+            const kernl = new Kernl({ storage: { db: storage } });
+            kernl.register(agent);
+            await agent.run("Hello");
+            // Verify storage was used - check that events were appended
+            const threads = await storage.threads.list();
+            expect(threads).toHaveLength(1);
+            const history = await storage.threads.history(threads[0].tid);
+            expect(history.length).toBeGreaterThan(0);
+        });
+        it("should work without storage (persist is no-op)", async () => {
+            const model = createMockModel(async () => ({
+                content: [message({ role: "assistant", text: "Done" })],
+                finishReason: "stop",
+                usage: { inputTokens: 2, outputTokens: 2, totalTokens: 4 },
+                warnings: [],
+            }));
+            const agent = new Agent({
+                id: "test-agent",
+                name: "Test",
+                instructions: "Test",
+                model,
+            });
+            const kernl = new Kernl(); // No storage
+            kernl.register(agent);
+            const result = await agent.run("Hello");
+            // Should complete successfully
+            expect(result.response).toBe("Done");
+            expect(result.state).toBe("stopped");
+        });
+        it("should throw MisconfiguredError when agent not bound to kernl", async () => {
+            const model = createMockModel(async () => ({
+                content: [message({ role: "assistant", text: "Done" })],
+                finishReason: "stop",
+                usage: { inputTokens: 2, outputTokens: 2, totalTokens: 4 },
+                warnings: [],
+            }));
+            const agent = new Agent({
+                id: "test-agent",
+                name: "Test",
+                instructions: "Test",
+                model,
+            });
+            // Don't register with kernl
+            await expect(agent.run("Hello")).rejects.toThrow(MisconfiguredError);
+            await expect(agent.run("Hello")).rejects.toThrow(/not bound to kernl/);
+        });
+    });
+    describe("New thread path", () => {
+        it("should create new thread when no threadId provided", async () => {
+            const model = createMockModel(async () => ({
+                content: [message({ role: "assistant", text: "Done" })],
+                finishReason: "stop",
+                usage: { inputTokens: 2, outputTokens: 2, totalTokens: 4 },
+                warnings: [],
+            }));
+            const agent = new Agent({
+                id: "test-agent",
+                name: "Test",
+                instructions: "Test",
+                model,
+            });
+            const kernl = new Kernl();
+            kernl.register(agent);
+            const result = await agent.run("Hello");
+            expect(result.response).toBe("Done");
+            expect(result.state).toBe("stopped");
+        });
+        it("should create new thread when threadId not found in storage", async () => {
+            const storage = new InMemoryStorage();
+            const model = createMockModel(async () => ({
+                content: [message({ role: "assistant", text: "Done" })],
+                finishReason: "stop",
+                usage: { inputTokens: 2, outputTokens: 2, totalTokens: 4 },
+                warnings: [],
+            }));
+            const agent = new Agent({
+                id: "test-agent",
+                name: "Test",
+                instructions: "Test",
+                model,
+            });
+            const kernl = new Kernl({ storage: { db: storage } });
+            kernl.register(agent);
+            await agent.run("Hello", { threadId: "non-existent" });
+            // Should have created new thread with the specified tid
+            const threads = await storage.threads.list();
+            expect(threads).toHaveLength(1);
+            expect(threads[0].tid).toBe("non-existent");
+        });
+        it("should resume existing thread from storage", async () => {
+            const storage = new InMemoryStorage();
+            const model = createMockModel(async () => ({
+                content: [message({ role: "assistant", text: "Response" })],
+                finishReason: "stop",
+                usage: { inputTokens: 2, outputTokens: 2, totalTokens: 4 },
+                warnings: [],
+            }));
+            const agent = new Agent({
+                id: "test-agent",
+                name: "Test",
+                instructions: "Test",
+                model,
+            });
+            const kernl = new Kernl({ storage: { db: storage } });
+            kernl.register(agent);
+            const tid = "resume-thread";
+            // First run
+            await agent.run("First", { threadId: tid });
+            const firstHistory = await storage.threads.history(tid);
+            const firstEventCount = firstHistory.length;
+            expect(firstEventCount).toBeGreaterThanOrEqual(2); // user + assistant
+            // Second run (resume)
+            await agent.run("Second", { threadId: tid });
+            const secondHistory = await storage.threads.history(tid);
+            const secondEventCount = secondHistory.length;
+            // Should have more events (added user + assistant from second run)
+            expect(secondEventCount).toBeGreaterThanOrEqual(firstEventCount + 2);
+        });
+    });
+    describe("String vs array input", () => {
+        it("should handle string input (converted to message)", async () => {
+            const storage = new InMemoryStorage();
+            const model = createMockModel(async () => ({
+                content: [message({ role: "assistant", text: "Done" })],
+                finishReason: "stop",
+                usage: { inputTokens: 2, outputTokens: 2, totalTokens: 4 },
+                warnings: [],
+            }));
+            const agent = new Agent({
+                id: "test-agent",
+                name: "Test",
+                instructions: "Test",
+                model,
+            });
+            const kernl = new Kernl({ storage: { db: storage } });
+            kernl.register(agent);
+            await agent.run("Hello world");
+            const threads = await storage.threads.list();
+            const events = await storage.threads.history(threads[0].tid);
+            // Find the user message (first event should be user message)
+            const userMessage = events.find((e) => e.role === "user");
+            expect(userMessage).toMatchObject({
+                kind: "message",
+                role: "user",
+                content: [{ kind: "text", text: "Hello world" }],
+            });
+        });
+        it("should handle array input (used as-is)", async () => {
+            const storage = new InMemoryStorage();
+            const model = createMockModel(async () => ({
+                content: [message({ role: "assistant", text: "Done" })],
+                finishReason: "stop",
+                usage: { inputTokens: 2, outputTokens: 2, totalTokens: 4 },
+                warnings: [],
+            }));
+            const agent = new Agent({
+                id: "test-agent",
+                name: "Test",
+                instructions: "Test",
+                model,
+            });
+            const kernl = new Kernl({ storage: { db: storage } });
+            kernl.register(agent);
+            const input = [message({ role: "user", text: "Custom" })];
+            await agent.run(input);
+            const threads = await storage.threads.list();
+            const events = await storage.threads.history(threads[0].tid);
+            // Find the user message
+            const userMessage = events.find((e) => e.role === "user");
+            expect(userMessage).toMatchObject({
+                kind: "message",
+                role: "user",
+                content: [{ kind: "text", text: "Custom" }],
+            });
+        });
+    });
+});
+describe("Agent.stream() lifecycle", () => {
+    it("should yield stream-start event first", async () => {
+        const model = createMockModel(async () => ({
+            content: [message({ role: "assistant", text: "Done" })],
+            finishReason: "stop",
+            usage: { inputTokens: 2, outputTokens: 2, totalTokens: 4 },
+            warnings: [],
+        }));
+        const agent = new Agent({
+            id: "test-agent",
+            name: "Test",
+            instructions: "Test",
+            model,
+        });
+        const kernl = new Kernl();
+        kernl.register(agent);
+        const events = [];
+        for await (const event of agent.stream("Hello")) {
+            events.push(event);
+        }
+        expect(events[0]).toEqual({ kind: "stream-start" });
+    });
+    it("should have same persistence behavior as run()", async () => {
+        const storage = new InMemoryStorage();
+        const model = createMockModel(async () => ({
+            content: [message({ role: "assistant", text: "Done" })],
+            finishReason: "stop",
+            usage: { inputTokens: 2, outputTokens: 2, totalTokens: 4 },
+            warnings: [],
+        }));
+        const agent = new Agent({
+            id: "test-agent",
+            name: "Test",
+            instructions: "Test",
+            model,
+        });
+        const kernl = new Kernl({ storage: { db: storage } });
+        kernl.register(agent);
+        const events = [];
+        for await (const event of agent.stream("Hello")) {
+            events.push(event);
+        }
+        // Should have persisted like run()
+        const threads = await storage.threads.list();
+        expect(threads).toHaveLength(1);
+        const history = await storage.threads.history(threads[0].tid);
+        expect(history.length).toBeGreaterThan(0);
+        // Should have streamed events
+        expect(events).toEqual(expect.arrayContaining([
+            { kind: "stream-start" },
+            expect.objectContaining({ kind: "message" }),
+        ]));
+    });
+});
+describe("Agent.threads helper", () => {
+    it("should throw MisconfiguredError when agent is not bound to kernl", () => {
+        const model = createMockModel(async () => ({
+            content: [message({ role: "assistant", text: "Done" })],
+            finishReason: "stop",
+            usage: { inputTokens: 2, outputTokens: 2, totalTokens: 4 },
+            warnings: [],
+        }));
+        const agent = new Agent({
+            id: "test-agent",
+            name: "Test",
+            instructions: "Test",
+            model,
+        });
+        expect(() => agent.threads).toThrow(MisconfiguredError);
+    });
+    it("should list only threads for this agent", async () => {
+        const storage = new InMemoryStorage();
+        const model = createMockModel(async () => ({
+            content: [message({ role: "assistant", text: "Done" })],
+            finishReason: "stop",
+            usage: { inputTokens: 2, outputTokens: 2, totalTokens: 4 },
+            warnings: [],
+        }));
+        const agentA = new Agent({
+            id: "agent-a",
+            name: "Agent A",
+            instructions: "Test",
+            model,
+        });
+        const agentB = new Agent({
+            id: "agent-b",
+            name: "Agent B",
+            instructions: "Test",
+            model,
+        });
+        const kernl = new Kernl({ storage: { db: storage } });
+        kernl.register(agentA);
+        kernl.register(agentB);
+        await agentA.run("Hello from A");
+        await agentB.run("Hello from B");
+        await agentB.run("Another from B");
+        const threadsAPage = await agentA.threads.list();
+        const threadsBPage = await agentB.threads.list();
+        const threadsA = await threadsAPage.collect();
+        const threadsB = await threadsBPage.collect();
+        expect(threadsA).toHaveLength(1);
+        expect(threadsB.length).toBeGreaterThanOrEqual(2);
+        for (const thread of threadsA) {
+            expect(thread.agentId).toBe("agent-a");
+        }
+        for (const thread of threadsB) {
+            expect(thread.agentId).toBe("agent-b");
+        }
+    });
+    it("should expose thread history via threads.history()", async () => {
+        const storage = new InMemoryStorage();
+        const model = createMockModel(async () => ({
+            content: [message({ role: "assistant", text: "Done" })],
+            finishReason: "stop",
+            usage: { inputTokens: 2, outputTokens: 2, totalTokens: 4 },
+            warnings: [],
+        }));
+        const agent = new Agent({
+            id: "test-agent",
+            name: "Test",
+            instructions: "Test",
+            model,
+        });
+        const kernl = new Kernl({ storage: { db: storage } });
+        kernl.register(agent);
+        await agent.run("Hello");
+        const threadsPage = await agent.threads.list();
+        const threads = await threadsPage.collect();
+        expect(threads).toHaveLength(1);
+        const tid = threads[0].tid;
+        const events = await agent.threads.history(tid, { order: "asc" });
+        // Expect exactly two events: user message then assistant message
+        expect(events).toHaveLength(2);
+        const [userEvent, assistantEvent] = events;
+        // Common headers
+        expect(userEvent.tid).toBe(tid);
+        expect(assistantEvent.tid).toBe(tid);
+        expect(userEvent.seq).toBe(0);
+        expect(assistantEvent.seq).toBe(1);
+        // User message
+        expect(userEvent.kind).toBe("message");
+        // @ts-expect-error ThreadEvent extends LanguageModelItem at runtime
+        expect(userEvent.role).toBe("user");
+        // @ts-expect-error ThreadEvent extends LanguageModelItem at runtime
+        expect(userEvent.content).toEqual([
+            { kind: "text", text: "Hello" },
+        ]);
+        // Assistant message
+        expect(assistantEvent.kind).toBe("message");
+        // @ts-expect-error ThreadEvent extends LanguageModelItem at runtime
+        expect(assistantEvent.role).toBe("assistant");
+        // @ts-expect-error ThreadEvent extends LanguageModelItem at runtime
+        expect(assistantEvent.content).toEqual([
+            { kind: "text", text: "Done" },
+        ]);
+    });
+});

package/dist/agent/index.d.ts

@@ -0,0 +1 @@
+//# sourceMappingURL=index.d.ts.map

package/dist/agent/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/agent/index.ts"],"names":[],"mappings":""}

package/dist/agent.d.ts

@@ -1,13 +1,13 @@
-import { LanguageModel, LanguageModelRequestSettings } from "@kernl-sdk/protocol";
-import type { Context, UnknownContext } from "./context";
-import { InputGuardrail, OutputGuardrail } from "./guardrail";
-import { AgentHooks } from "./lifecycle";
-import { BaseToolkit } from "./tool/toolkit";
-import { Tool } from "./tool";
-import type { AgentConfig, AgentResponseType } from "./types/agent";
-import type { TextResponse, ThreadOptions, ThreadExecuteResult, ThreadStreamEvent } from "./types/thread";
-import type { Kernl } from "./kernl";
-import type { ResolvedAgentResponse } from "./guardrail";
+import { LanguageModel, LanguageModelItem, LanguageModelRequestSettings } from "@kernl-sdk/protocol";
+import type { Kernl } from "./kernl.js";
+import type { RThreadsListParams, RThreadCreateParams, RThreadGetOptions, RThreadHistoryParams, RThreadUpdateParams } from "./api/resources/threads/types.js";
+import type { Context, UnknownContext } from "./context.js";
+import { Tool } from "./tool/index.js";
+import { BaseToolkit } from "./tool/toolkit.js";
+import { InputGuardrail, OutputGuardrail, type ResolvedAgentResponse } from "./guardrail.js";
+import { AgentHooks } from "./lifecycle.js";
+import type { AgentConfig, AgentResponseType } from "./types/agent.js";
+import type { TextResponse, ThreadExecuteOptions, ThreadExecuteResult, ThreadStreamEvent } from "./types/thread.js";
 export declare class Agent<TContext = UnknownContext, TResponse extends AgentResponseType = TextResponse> extends AgentHooks<TContext, TResponse> implements AgentConfig<TContext, TResponse> {
     private kernl?;
     id: string;
@@ -29,15 +29,23 @@ export declare class Agent<TContext = UnknownContext, TResponse extends AgentRes
     bind(kernl: Kernl): void;
     /**
      * Blocking execution - spawns or resumes thread and waits for completion
+     *
+     * @throws {RuntimeError} If the specified thread is already running (concurrent execution not allowed)
+     * @throws {MisconfiguredError} If the agent is not bound to a kernl instance
      */
-    run(instructions: string, options?: ThreadOptions<TContext>): Promise<ThreadExecuteResult<ResolvedAgentResponse<TResponse>>>;
+    run(input: string | LanguageModelItem[], options?: ThreadExecuteOptions<TContext>): Promise<ThreadExecuteResult<ResolvedAgentResponse<TResponse>>>;
     /**
      * Streaming execution - spawns or resumes thread and returns async iterator
      *
      * NOTE: streaming probably won't make sense in scheduling contexts so spawnStream etc. won't make sense
+     *
+     * @throws {RuntimeError} If the specified thread is already running (concurrent execution not allowed)
+     * @throws {MisconfiguredError} If the agent is not bound to a kernl instance
      */
-    stream(instructions: string, options?: ThreadOptions<TContext>): AsyncIterable<ThreadStreamEvent>;
+    stream(input: string | LanguageModelItem[], options?: ThreadExecuteOptions<TContext>): AsyncIterable<ThreadStreamEvent>;
     /**
+     * @internal
+     *
      * Get a specific tool by ID from all toolkits.
      *
      * @param id The tool ID to look up
@@ -45,6 +53,8 @@ export declare class Agent<TContext = UnknownContext, TResponse extends AgentRes
      */
     tool(id: string): Tool<TContext> | undefined;
     /**
+     * @internal
+     *
      * Get all tools available from all toolkits for the given context.
      * Checks for duplicate tool IDs across toolkits and throws an error if found.
      *
@@ -56,5 +66,18 @@ export declare class Agent<TContext = UnknownContext, TResponse extends AgentRes
      * @throws {MisconfiguredError} If duplicate tool IDs are found across toolkits
      */
     tools(context: Context<TContext>): Promise<Tool<TContext>[]>;
+    /**
+     * Thread management scoped to this agent.
+     *
+     * Convenience wrapper around kernl.threads that automatically filters to this agent's threads.
+     */
+    get threads(): {
+        get: (tid: string, options?: RThreadGetOptions) => Promise<import("./index.js").Thread | null>;
+        list: (params?: Omit<RThreadsListParams, "agentId">) => Promise<import("./api/pagination/cursor.js").CursorPage<import("./index.js").Thread, RThreadsListParams>>;
+        delete: (tid: string) => Promise<void>;
+        history: (tid: string, params?: RThreadHistoryParams) => Promise<import("./index.js").ThreadEvent[]>;
+        create: (params: Omit<RThreadCreateParams, "agentId" | "model">) => Promise<import("./index.js").Thread>;
+        update: (tid: string, patch: RThreadUpdateParams) => Promise<import("./index.js").Thread | null>;
+    };
 }
 //# sourceMappingURL=agent.d.ts.map

package/dist/agent.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"agent.d.ts","sourceRoot":"","sources":["../src/agent.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,aAAa,EACb,4BAA4B,EAE7B,MAAM,qBAAqB,CAAC;AAE7B,OAAO,KAAK,EAAE,OAAO,EAAE,cAAc,EAAE,MAAM,WAAW,CAAC;AACzD,OAAO,EAAE,cAAc,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAC9D,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AACzC,OAAO,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAC;AAC7C,OAAO,EAAE,IAAI,EAAE,MAAM,QAAQ,CAAC;AAK9B,OAAO,KAAK,EAAE,WAAW,EAAE,iBAAiB,EAAE,MAAM,eAAe,CAAC;AACpE,OAAO,KAAK,EACV,YAAY,EACZ,aAAa,EACb,mBAAmB,EACnB,iBAAiB,EAClB,MAAM,gBAAgB,CAAC;AACxB,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,SAAS,CAAC;AACrC,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,aAAa,CAAC;AAEzD,qBAAa,KAAK,CACd,QAAQ,GAAG,cAAc,EACzB,SAAS,SAAS,iBAAiB,GAAG,YAAY,CAEpD,SAAQ,UAAU,CAAC,QAAQ,EAAE,SAAS,CACtC,YAAW,WAAW,CAAC,QAAQ,EAAE,SAAS,CAAC;IAE3C,OAAO,CAAC,KAAK,CAAC,CAAQ;IAEtB,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,YAAY,EAAE,CAAC,OAAO,EAAE,OAAO,CAAC,QAAQ,CAAC,KAAK,OAAO,CAAC,MAAM,CAAC,GAAG,MAAM,CAAC;IAEvE,KAAK,EAAE,aAAa,CAAC;IACrB,aAAa,EAAE,4BAA4B,CAAC;IAC5C,QAAQ,EAAE,WAAW,CAAC,QAAQ,CAAC,EAAE,CAAC;IAGlC,UAAU,EAAE;QACV,KAAK,EAAE,cAAc,EAAE,CAAC;QACxB,MAAM,EAAE,eAAe,CAAC,iBAAiB,CAAC,EAAE,CAAC;KAC9C,CAAC;IACF,YAAY,EAAE,SAAS,CAAuB;IAC9C,eAAe,EAAE,OAAO,CAAC;gBAgBb,MAAM,EAAE,WAAW,CAAC,QAAQ,EAAE,SAAS,CAAC;IA0CpD;;OAEG;IACH,IAAI,CAAC,KAAK,EAAE,KAAK,GAAG,IAAI;IAIxB;;OAEG;IACG,GAAG,CACP,YAAY,EAAE,MAAM,EACpB,OAAO,CAAC,EAAE,aAAa,CAAC,QAAQ,CAAC,GAChC,OAAO,CAAC,mBAAmB,CAAC,qBAAqB,CAAC,SAAS,CAAC,CAAC,CAAC;IAqBjE;;;;OAIG;IACI,MAAM,CACX,YAAY,EAAE,MAAM,EACpB,OAAO,CAAC,EAAE,aAAa,CAAC,QAAQ,CAAC,GAChC,aAAa,CAAC,iBAAiB,CAAC;IAsBnC;;;;;OAKG;IACH,IAAI,CAAC,EAAE,EAAE,MAAM,GAAG,IAAI,CAAC,QAAQ,CAAC,GAAG,SAAS;IAQ5C;;;;;;;;;;OAUG;IACG,KAAK,CAAC,OAAO,EAAE,OAAO,CAAC,QAAQ,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC,QAAQ,CAAC,EAAE,CAAC;CAoBnE"}
+{"version":3,"file":"agent.d.ts","sourceRoot":"","sources":["../src/agent.ts"],"names":[],"mappings":"AAAA,OAAO,EAEL,aAAa,EACb,iBAAiB,EACjB,4BAA4B,EAC7B,MAAM,qBAAqB,CAAC;AAG7B,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,SAAS,CAAC;AACrC,OAAO,KAAK,EACV,kBAAkB,EAClB,mBAAmB,EACnB,iBAAiB,EACjB,oBAAoB,EACpB,mBAAmB,EACpB,MAAM,+BAA+B,CAAC;AACvC,OAAO,KAAK,EAAE,OAAO,EAAE,cAAc,EAAE,MAAM,WAAW,CAAC;AACzD,OAAO,EAAE,IAAI,EAAE,MAAM,QAAQ,CAAC;AAC9B,OAAO,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAC;AAC7C,OAAO,EACL,cAAc,EACd,eAAe,EACf,KAAK,qBAAqB,EAC3B,MAAM,aAAa,CAAC;AACrB,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAGzC,OAAO,KAAK,EAAE,WAAW,EAAE,iBAAiB,EAAE,MAAM,eAAe,CAAC;AACpE,OAAO,KAAK,EACV,YAAY,EACZ,oBAAoB,EACpB,mBAAmB,EACnB,iBAAiB,EAClB,MAAM,gBAAgB,CAAC;AAExB,qBAAa,KAAK,CACd,QAAQ,GAAG,cAAc,EACzB,SAAS,SAAS,iBAAiB,GAAG,YAAY,CAEpD,SAAQ,UAAU,CAAC,QAAQ,EAAE,SAAS,CACtC,YAAW,WAAW,CAAC,QAAQ,EAAE,SAAS,CAAC;IAE3C,OAAO,CAAC,KAAK,CAAC,CAAQ;IAEtB,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,YAAY,EAAE,CAAC,OAAO,EAAE,OAAO,CAAC,QAAQ,CAAC,KAAK,OAAO,CAAC,MAAM,CAAC,GAAG,MAAM,CAAC;IAEvE,KAAK,EAAE,aAAa,CAAC;IACrB,aAAa,EAAE,4BAA4B,CAAC;IAC5C,QAAQ,EAAE,WAAW,CAAC,QAAQ,CAAC,EAAE,CAAC;IAGlC,UAAU,EAAE;QACV,KAAK,EAAE,cAAc,EAAE,CAAC;QACxB,MAAM,EAAE,eAAe,CAAC,iBAAiB,CAAC,EAAE,CAAC;KAC9C,CAAC;IACF,YAAY,EAAE,SAAS,CAAuB;IAC9C,eAAe,EAAE,OAAO,CAAC;gBAgBb,MAAM,EAAE,WAAW,CAAC,QAAQ,EAAE,SAAS,CAAC;IA0CpD;;OAEG;IACH,IAAI,CAAC,KAAK,EAAE,KAAK,GAAG,IAAI;IAIxB;;;;;OAKG;IACG,GAAG,CACP,KAAK,EAAE,MAAM,GAAG,iBAAiB,EAAE,EACnC,OAAO,CAAC,EAAE,oBAAoB,CAAC,QAAQ,CAAC,GACvC,OAAO,CAAC,mBAAmB,CAAC,qBAAqB,CAAC,SAAS,CAAC,CAAC,CAAC;IAkDjE;;;;;;;OAOG;IACI,MAAM,CACX,KAAK,EAAE,MAAM,GAAG,iBAAiB,EAAE,EACnC,OAAO,CAAC,EAAE,oBAAoB,CAAC,QAAQ,CAAC,GACvC,aAAa,CAAC,iBAAiB,CAAC;IAmDnC;;;;;;;OAOG;IACH,IAAI,CAAC,EAAE,EAAE,MAAM,GAAG,IAAI,CAAC,QAAQ,CAAC,GAAG,SAAS;IAQ5C;;;;;;;;;;;;OAYG;IACG,KAAK,CAAC,OAAO,EAAE,OAAO,CAAC,QAAQ,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC,QAAQ,CAAC,EAAE,CAAC;IAqBlE;;;;OAIG;IACH,IAAI,OAAO;mBAWI,MAAM,YAAY,iBAAiB;wBAE/B,IAAI,CAAC,kBAAkB,EAAE,SAAS,CAAC;sBAEpC,MAAM;uBACL,MAAM,WAAW,oBAAoB;yBAEnC,IAAI,CAAC,mBAAmB,EAAE,SAAS,GAAG,OAAO,CAAC;sBASjD,MAAM,SAAS,mBAAmB;MAGnD;CACF"}

package/dist/agent.js

@@ -1,7 +1,7 @@
 import { message, } from "@kernl-sdk/protocol";
-import { AgentHooks } from "./lifecycle";
-import { Thread } from "./thread";
-import { MisconfiguredError } from "./lib/error";
+import { Thread } from "./thread/index.js";
+import { AgentHooks } from "./lifecycle.js";
+import { MisconfiguredError, RuntimeError } from "./lib/error.js";
 export class Agent extends AgentHooks {
     kernl;
     id;
@@ -71,44 +71,102 @@ export class Agent extends AgentHooks {
     }
     /**
      * Blocking execution - spawns or resumes thread and waits for completion
+     *
+     * @throws {RuntimeError} If the specified thread is already running (concurrent execution not allowed)
+     * @throws {MisconfiguredError} If the agent is not bound to a kernl instance
      */
-    async run(instructions, options) {
+    async run(input, options) {
         if (!this.kernl) {
             throw new MisconfiguredError(`Agent ${this.id} not bound to kernl. Call kernl.register(agent) first.`);
         }
-        const m = message({ role: "user", text: instructions });
+        const items = typeof input === "string"
+            ? [message({ role: "user", text: input })]
+            : input;
         const tid = options?.threadId;
-        // NOTE: may end up moving this to the kernl
-        let thread = tid ? this.kernl.threads.get(tid) : null;
+        let thread = null;
+        if (tid) {
+            // no concurrent execution of same thread - correctness contract
+            // TODO: race condition - need to check again after async storage.get()
+            if (this.kernl.athreads.has(tid)) {
+                throw new RuntimeError(`Thread ${tid} is already running.`);
+            }
+            // try to resume from storage if available
+            if (this.kernl.storage?.threads) {
+                thread = (await this.kernl.storage.threads.get(tid, {
+                    history: true,
+                }));
+            }
+        }
+        // create new thread if not found in storage or no tid provided
         if (!thread) {
-            thread = new Thread(this.kernl, this, [m], options);
+            thread = new Thread({
+                agent: this,
+                input: items,
+                context: options?.context,
+                model: options?.model,
+                task: options?.task,
+                tid: options?.threadId,
+                namespace: options?.namespace,
+                storage: this.kernl.storage?.threads,
+            });
             return this.kernl.spawn(thread);
         }
-        thread.append(m);
+        // resume existing thread from storage
+        thread.append(...items);
         return this.kernl.schedule(thread);
     }
     /**
      * Streaming execution - spawns or resumes thread and returns async iterator
      *
      * NOTE: streaming probably won't make sense in scheduling contexts so spawnStream etc. won't make sense
+     *
+     * @throws {RuntimeError} If the specified thread is already running (concurrent execution not allowed)
+     * @throws {MisconfiguredError} If the agent is not bound to a kernl instance
      */
-    async *stream(instructions, options) {
+    async *stream(input, options) {
         if (!this.kernl) {
             throw new MisconfiguredError(`Agent ${this.id} not bound to kernl. Call kernl.register(agent) first.`);
         }
-        const m = message({ role: "user", text: instructions });
+        const items = typeof input === "string"
+            ? [message({ role: "user", text: input })]
+            : input;
         const tid = options?.threadId;
-        // NOTE: may end up moving this to the kernl
-        let thread = tid ? this.kernl.threads.get(tid) : null;
+        let thread = null;
+        if (tid) {
+            // no concurrent execution of same thread - correctness contract
+            // TODO: race condition - need to check again after async storage.get()
+            if (this.kernl.athreads.has(tid)) {
+                throw new RuntimeError(`Thread ${tid} is already running.`);
+            }
+            // try to resume from storage if available
+            if (this.kernl.storage?.threads) {
+                thread = (await this.kernl.storage.threads.get(tid, {
+                    history: true,
+                }));
+            }
+        }
+        // create new thread if not found in storage or no tid provided
         if (!thread) {
-            thread = new Thread(this.kernl, this, [m], options);
+            thread = new Thread({
+                agent: this,
+                input: items,
+                context: options?.context,
+                model: options?.model,
+                task: options?.task,
+                tid: options?.threadId,
+                namespace: options?.namespace,
+                storage: this.kernl.storage?.threads,
+            });
             yield* this.kernl.spawnStream(thread);
             return;
         }
-        thread.append(m);
+        // resume existing thread from storage
+        thread.append(...items);
         yield* this.kernl.scheduleStream(thread);
     }
     /**
+     * @internal
+     *
      * Get a specific tool by ID from all toolkits.
      *
      * @param id The tool ID to look up
@@ -123,6 +181,8 @@ export class Agent extends AgentHooks {
         return undefined;
     }
     /**
+     * @internal
+     *
      * Get all tools available from all toolkits for the given context.
      * Checks for duplicate tool IDs across toolkits and throws an error if found.
      *
@@ -147,4 +207,31 @@ export class Agent extends AgentHooks {
         }
         return allTools;
     }
+    /**
+     * Thread management scoped to this agent.
+     *
+     * Convenience wrapper around kernl.threads that automatically filters to this agent's threads.
+     */
+    get threads() {
+        if (!this.kernl) {
+            throw new MisconfiguredError(`Agent ${this.id} not bound to kernl. Call kernl.register(agent) first.`);
+        }
+        const agentId = this.id;
+        const kthreads = this.kernl.threads;
+        return {
+            get: (tid, options) => kthreads.get(tid, options),
+            list: (params = {}) => kthreads.list({ ...params, agentId }),
+            delete: (tid) => kthreads.delete(tid),
+            history: (tid, params) => kthreads.history(tid, params),
+            create: (params) => kthreads.create({
+                ...params,
+                agentId,
+                model: {
+                    provider: this.model.provider,
+                    modelId: this.model.modelId,
+                },
+            }),
+            update: (tid, patch) => kthreads.update(tid, patch),
+        };
+    }
 }

package/dist/api/__tests__/cursor-page.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=cursor-page.test.d.ts.map

package/dist/api/__tests__/cursor-page.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cursor-page.test.d.ts","sourceRoot":"","sources":["../../../src/api/__tests__/cursor-page.test.ts"],"names":[],"mappings":""}