experimental-agent 0.2.1 → 0.3.0

package/README.md

@@ -9,10 +9,10 @@ pnpm i experimental-agent
 ## Why
 
 - **AI SDK compatible** — Built on `ai`. Uses `UIMessage`, `GatewayModelId`, streams the same way. If you know AI SDK, you know this.
-- **Managed workflow** — Runs inside Vercel Workflow. Retries, timeouts, resumption handled for you.
+- **Opt-in durability** — Works in-process by default. Add a `"use workflow"` wrapper for full durability that survives crashes, timeouts, and deploys.
+- **Bring your own storage** — Implement a flat handler map backed by any database. Built-in `localStorage()` for dev.
 - **Managed sandbox** — Auto-starts on first use, auto-snapshots when idle, auto-resumes. You don't manage the VM.
-- **Built-in storage** — Messages, tool calls, and sandbox state persisted automatically. Survives refreshes, crashes, reconnects.
-- **Built-in tools** — Read, Grep, List, Bash. No setup.
+- **Built-in tools** — Read, Grep, List, Bash, Write, Edit, Skill, JavaScript. No setup.
 
 ## Quick Start
 
@@ -20,8 +20,8 @@ pnpm i experimental-agent
 // lib/agent.ts
 import { agent } from "experimental-agent";
 
-export const myAgent = agent({
-  model: "anthropic/claude-opus-4.5",
+export const myAgent = agent("my-agent", {
+  model: "anthropic/claude-opus-4.6",
   system: "You are a helpful coding assistant.",
 });
 ```
@@ -33,10 +33,10 @@ import { createUIMessageStreamResponse } from "ai";
 
 export async function POST(req: Request, { params }: { params: { chatId: string } }) {
   const { chatId } = await params;
-  const { message } = await req.json(); // string or UIMessage
+  const { message } = await req.json();
 
-  const session = await myAgent.session(chatId);
-  await session.send({ input: message }); // accepts string, UIMessage, or parts array
+  const session = myAgent.session(chatId);
+  await session.send(message);
   const stream = await session.stream();
 
   return createUIMessageStreamResponse({ stream });
@@ -44,275 +44,76 @@ export async function POST(req: Request, { params }: { params: { chatId: string
 
 export async function GET(req: Request, { params }: { params: { chatId: string } }) {
   const { chatId } = await params;
-  const session = await myAgent.session(chatId);
-  const stream = await session.stream();
-  if (stream instanceof Error) {
-    console.error(stream);
-    if (stream instanceof SessionNotFoundError) {
-      return new Response("Session not found", { status: 404 });
-    }
-    return new Response("Internal server error", { status: 500 });
+  const session = myAgent.session(chatId);
+  try {
+    const stream = await session.stream();
+    return createUIMessageStreamResponse({ stream });
+  } catch {
+    return Response.json(await session.history());
   }
-
-  return createUIMessageStreamResponse({ stream });
 }
 ```
 
+## Adding Workflow
 
+Everything works without workflow. To add durability:
 
-## Rendering Messages
-
-`session.ui()` returns `UIMessage[]` — the same format `useChat` uses.
-
-### RSC Pattern
-
-Server component fetches initial state, client component handles streaming:
-
-```tsx
-// app/chat/[chatId]/page.tsx (server component)
+```ts
+// workflow.ts
 import { myAgent } from "@/lib/agent";
-import { Chat } from "./chat-client";
-
-export default async function ChatPage({ params }) {
-  const { chatId } = await params;
-  const session = await myAgent.session(chatId);
-  const ui = await session.ui();
-  if (ui instanceof Error) {
-    console.error(ui);
-    throw new Error("Failed to get messages");
-  }
-
-  return (
-    <>
-      {ui.messages.map((m) => (
-        <MessageView key={m.id} message={m} />
-      ))}
-      <Chat chatId={chatId} streamingMessageId={ui.streamingMessageId} />
-    </>
-  );
-}
-```
-
-```tsx
-// chat-client.tsx
-"use client";
-
-import { useEffect } from "react";
-import { useChat, DefaultChatTransport } from "@ai-sdk/react";
-
-export function Chat({ chatId, streamingMessageId }) {
-  const { messages, resumeStream, sendMessage, status } = useChat({
-    id: chatId,
-    transport: new DefaultChatTransport({
-      api: `/api/chat/${chatId}`,
-      prepareSendMessagesRequest: ({ messages }) => ({
-        body: { message: messages.at(-1) },
-      }),
-      prepareReconnectToStreamRequest: (request) => ({
-        ...request,
-        api: `/api/chat/${chatId}`,
-      }),
-    }),
-  });
-
-  useEffect(() => {
-    if (streamingMessageId) {
-      resumeStream();
-    }
-  }, [streamingMessageId, resumeStream]);
-
-  return (
-    <>
-      {messages.map((m) => (
-        <MessageView key={m.id} message={m} />
-      ))}
-      <form
-        onSubmit={async (e) => {
-          e.preventDefault();
-          const form = e.currentTarget;
-          const textarea = form.elements.namedItem("composer") as HTMLTextAreaElement | null;
-          const text = textarea ? textarea.value : "";
-          if (text.trim()) {
-            await sendMessage({ parts: [{ type: "text", text }] });
-            textarea.value = "";
-          }
-        }}
-      >
-        <textarea name="composer" />
-        <button type="submit" disabled={status !== "ready"}>
-          Send
-        </button>
-      </form>
-    </>
-  );
+import type { SessionSendArgs } from "experimental-agent";
+
+export async function agentWorkflow(
+  sessionId: string,
+  ...args: SessionSendArgs<typeof myAgent>
+) {
+  "use workflow";
+  return await myAgent.session(sessionId).send(...args);
 }
 ```
 
-
-## Tools
-
-| Tool | Description |
-|------|-------------|
-| **Read** | Read files. Large files (>200 lines) paginate automatically. |
-| **Grep** | ripgrep-powered search. Regex, file types, context lines. |
-| **List** | Directory listing with depth control and glob filtering. |
-| **Bash** | Shell commands. Background processes via `waitUntil: 0`. Persistent CWD. |
-
-## Configuration
-
-```ts
-const myAgent = agent({
-  model: "anthropic/claude-haiku-4.5",  // Required
-  system: "...",                         // System prompt
-  sandbox: { type: "vercel" },          // or "local"
-  storage: { type: "vercel" },          // or "local" or "custom"
-  skillsDir: ".agent/skills",           // Skills location
-  mcp: { ... },                         // Custom tools
-})
-
-// overrides per session
-myAgent.session("<session-id>", {
-  model: "anthropic/claude-opus-4.5"
-})
-```
-
-## Sessions
-
-```ts
-const session = await myAgent.session(sessionId);
-
-// input can be a string, UIMessage, or parts array
-await session.send({ input: "Hello" });
-await session.send({ input: { role: "user", parts: [{ type: "text", text: "Hello" }] } });
-
-const stream = await session.stream();
-
-// Tags for your app's metadata
-await session.tag.set("category", "support");
-```
-
-### Handles vs Records
-
-- `myAgent.session(id)` and `myAgent.sandbox(id)` return orchestration handles.
-- Handles are use-case APIs (send, stream, run tools, resume sandbox lifecycle).
-- `myAgent.storage.*` is the raw record API (`Session`, `SandboxRecord`, `Message`, `Part`, `Command`, `SetupSnapshot`).
-- Use `storage` for record lookups and filters (for example existence checks and list queries).
-
-### Durable UI
-
-Unlike `useChat` alone, messages survive refresh. They're persisted to storage.
-
-- Close laptop, open tomorrow — conversation is there
-- Browser crashes mid-stream — reload, partial response preserved
-- Share a session URL — another user sees the same conversation
-
-The server component renders completed messages from `session.ui()`. The client component handles new input and streaming. State lives in storage, not browser memory.
-
-## Sandbox
-
-```ts
-// Local (dev)
-const myAgent = agent({ sandbox: { type: "local" } })
-
-// Vercel (prod)
-const myAgent = agent({ sandbox: { type: "vercel", resources: { vcpus: 2 }, ports: [3000] } })
-
-const session = await myAgent.session("some-session")
-
-// Direct access
-await session.sandbox.exec({ command: "npm", args: ["install"] });
-```
-
-### Share a sandbox
-
 ```ts
-const sharedBox = await myAgent.sandbox("some-sandbox")
-
-await myAgent.session("s1", { sandbox: sharedBox.id });
-await myAgent.session("s2", { sandbox: sharedBox.id });
-```
-
-## Skills
-
-Skills are `SKILL.md` files discovered from the sandbox:
+// route.ts
+import { start } from "workflow/api";
+import { agentWorkflow } from "./workflow";
 
-```yaml
----
-name: deploy
-description: Deploy to Vercel
----
-
-Run `vercel deploy` in the project root.
+const result = await start(agentWorkflow, [chatId, message, opts]);
+const stream = await session.stream(result);
+return createUIMessageStreamResponse({ stream });
 ```
 
-```ts
-agent({ skillsDir: ".agent/skills" })
-```
-
-## MCP (this api will change soon)
-
-Custom tools with type-safe schemas:
+## Storage
 
 ```ts
-import { agent, mcp } from "experimental-agent";
-import { z } from "zod";
-
-const myAgent = agent({
-  mcp: {
-    vercel: mcp({
-      url: "/api/mcp",
-      headersSchema: z.object({ authorization: z.string() }),
-      tools: {
-        listProjects: {
-          description: "List Vercel projects",
-          inputSchema: z.object({ teamId: z.string().optional() }),
-        },
-      },
-    }),
+// Dev — built-in filesystem storage
+import { localStorage } from "experimental-agent/storage";
+agent("my-agent", { storage: localStorage() })
+
+// Prod — your own database
+agent("my-agent", {
+  async storage(store) {
+    return await store.on({
+      "session.get": async ({ id }) => await db.sessions.findById(id),
+      "session.set": async ({ id, value }) => await db.sessions.upsert(id, value),
+      // ... all handlers
+    });
   },
-});
-
-// Send with auth
-await session.send({
-  input: "List my projects",
-  mcpContext: { vercel: { headers: { authorization: `Bearer ${token}` } } },
-});
+})
 
-// Handle in your API
-await myAgent.handleMcpToolCall(body, {
-  "vercel/listProjects": async ({ input, headers }) => {
-    return fetchProjects(input.teamId, headers.authorization);
+// To add workflow durability, just add "use step" at the top:
+agent("my-agent", {
+  async storage(store) {
+    "use step";
+    return await store.on({ /* same handlers */ });
   },
-});
-```
-
-## Storage
-
-HTTP-based (workflow inputs must be serializable).
-
-```ts
-agent({ storage: { type: "vercel" } })  // default — hosted service
-agent({ storage: { type: "local" } })   // dev — filesystem
-agent({ storage: { type: "custom", url: "https://...", headers: {} } })
+})
 ```
 
-The SDK stores: `Session`, `Message`, `Part`, `SandboxRecord`.
-
-Everything else—users, titles, access control—belongs in your database. Session ID is your join key.
-
-For session queries scoped to a sandbox, use `storage.session.listBySandbox({ sandboxId, ... })`.
-
-### Vercel Agent Storage
-
-The default `{ type: "vercel" }` uses the hosted Vercel Agent Storage service:
-
-- **Zero config** — authenticates via Vercel OIDC, no API keys needed
-- **Multi-tenant** — data isolated by owner, project, and environment
-- **Postgres-backed** — reliable, queryable, scales with you
+The SDK stores `Session`, `Message`, `Part`, `Sandbox`. Everything else — users, titles, access control — belongs in your database. Session ID is your join key.
 
-Just deploy to Vercel and it works. No database setup, no connection strings.
+## Documentation
 
-For self-hosting or custom backends, see [apps/storage](../../apps/storage/) for a reference implementation using `handleStorageRpc`.
+Full docs at [packages/agent/docs](./docs/).
 
 ## Development
 

package/dist/adapter-BigchkkI.d.mts

@@ -0,0 +1,201 @@
+import { WORKFLOW_SERIALIZE, WORKFLOW_DESERIALIZE } from '@workflow/serde';
+import { NetworkPolicy } from '@vercel/sandbox';
+import { UIMessage } from 'ai';
+
+type Session = {
+    id: string;
+    createdAt: number;
+    updatedAt: number;
+    model: string | null;
+    system: string | null;
+    sandboxId: string | null;
+    lastMessageId: string | null;
+    activeTools: string[] | null;
+    skillsDir: string[] | null;
+    generation: {
+        maxSteps?: number;
+        temperature?: number;
+        topK?: number;
+        topP?: number;
+        frequencyPenalty?: number;
+        presencePenalty?: number;
+        maxOutputTokens?: number;
+        headers?: Record<string, string>;
+    } | null;
+};
+type Message = {
+    id: string;
+    sessionId: string;
+    role: "user" | "assistant" | "system";
+    createdAt: number;
+    startedAt: number | null;
+    completedAt: number | null;
+    interruptedAt: number | null;
+    interruptedLastPart: {
+        index: number;
+        part: unknown;
+    } | null;
+    usage: {
+        steps: {
+            stepIndex: number;
+            model: string;
+            inputTokens: number;
+            outputTokens: number;
+            totalTokens: number;
+            cacheReadTokens: number;
+            cacheWriteTokens: number;
+            reasoningTokens: number;
+        }[];
+        summary: {
+            model: string;
+            inputTokens: number;
+            outputTokens: number;
+            totalTokens: number;
+            cacheReadTokens: number;
+            cacheWriteTokens: number;
+            reasoningTokens: number;
+            stepCount: number;
+        };
+    } | null;
+    workflowRunId?: string | null;
+};
+type Part = {
+    id: string;
+    messageId: string;
+    sessionId: string;
+    index: number;
+    part: UIMessage["parts"][number];
+};
+type Sandbox = {
+    id: string;
+    setup: {
+        binding: string;
+        version: string | null;
+        completedAt: number | null;
+        metadata: Record<string, unknown> | null;
+        networkPolicy: NetworkPolicy | null;
+    };
+    createdAt: number | null;
+    lastActiveAt: number | null;
+};
+type Setup = {
+    version: string;
+    snapshotId: string | null;
+    createdAt: number;
+    lastUsedAt: number | null;
+};
+type SetupSnapshot = Setup;
+
+type StorageHandlers = {
+    "session.get"(p: {
+        id: string;
+    }): Promise<Session | null>;
+    "session.set"(p: {
+        id: string;
+        value: Session;
+    }): Promise<void>;
+    "session.update"(p: {
+        id: string;
+        updates: Partial<Session>;
+    }): Promise<Session>;
+    "message.get"(p: {
+        id: string;
+    }): Promise<Message | null>;
+    "message.set"(p: {
+        id: string;
+        value: Message;
+    }): Promise<void>;
+    "message.update"(p: {
+        id: string;
+        updates: Partial<Message>;
+    }): Promise<Message>;
+    "message.listBySession"(p: {
+        sessionId: string;
+    }): Promise<Message[]>;
+    "part.get"(p: {
+        id: string;
+    }): Promise<Part | null>;
+    "part.set"(p: {
+        id: string;
+        value: Part;
+    }): Promise<void>;
+    "part.listBySession"(p: {
+        sessionId: string;
+    }): Promise<Part[]>;
+    "sandbox.get"(p: {
+        id: string;
+    }): Promise<Sandbox | null>;
+    "sandbox.set"(p: {
+        id: string;
+        value: Sandbox;
+    }): Promise<void>;
+    "sandbox.update"(p: {
+        id: string;
+        updates: Partial<Sandbox>;
+    }): Promise<Sandbox>;
+    "setup.get"(p: {
+        id: string;
+    }): Promise<Setup | null>;
+    "setup.set"(p: {
+        id: string;
+        value: Setup;
+    }): Promise<void>;
+};
+type StorageCall = {
+    [K in keyof StorageHandlers]: {
+        method: K;
+    } & Parameters<StorageHandlers[K]>[0];
+}[keyof StorageHandlers];
+declare class StorageStep {
+    event: StorageCall;
+    constructor(event: StorageCall);
+    static [WORKFLOW_SERIALIZE](instance: StorageStep): {
+        event: StorageCall;
+    };
+    static [WORKFLOW_DESERIALIZE](data: {
+        event: StorageCall;
+    }): StorageStep;
+    on(handlers: StorageHandlers): Promise<any>;
+}
+/**
+ * A single function that handles all storage operations. Intended to be
+ * marked with `"use step"` so that its body (and Node.js-dependent
+ * imports like database clients) is extracted by the workflow bundler
+ * and runs server-side.
+ *
+ * The step receives a `StorageStep` instance (serializable via
+ * `@workflow/serde`) and should call `step.handle({ ... })` with a
+ * `StorageHandlers` map.
+ */
+type StorageStepFunction = (store: StorageStep) => Promise<any>;
+interface Storage {
+    session: {
+        get(key: string): Promise<Session | null>;
+        set(key: string, value: Session): Promise<void>;
+        update(key: string, updates: Partial<Session>): Promise<Session>;
+    };
+    message: {
+        get(key: string): Promise<Message | null>;
+        set(key: string, value: Message): Promise<void>;
+        update(key: string, updates: Partial<Message>): Promise<Message>;
+        listBySession(sessionId: string): Promise<Message[]>;
+    };
+    part: {
+        get(key: string): Promise<Part | null>;
+        set(key: string, value: Part): Promise<void>;
+        listBySession(sessionId: string): Promise<Part[]>;
+    };
+    sandbox: {
+        get(key: string): Promise<Sandbox | null>;
+        set(key: string, value: Sandbox): Promise<void>;
+        update(key: string, updates: Partial<Sandbox>): Promise<Sandbox>;
+    };
+    setup: {
+        get(key: string): Promise<Setup | null>;
+        set(key: string, value: Setup): Promise<void>;
+    };
+}
+type StorageInput = StorageHandlers | StorageStepFunction;
+declare function toStorage(h: StorageInput): Storage;
+
+export { type Message as M, type Part as P, type StorageHandlers as S, type Sandbox as a, type Session as b, type Setup as c, type SetupSnapshot as d, type Storage as e, type StorageCall as f, StorageStep as g, type StorageStepFunction as h, type StorageInput as i, toStorage as t };