experimental-agent 0.2.3 → 0.4.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,9 +20,25 @@ 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.",
+  skills: [
+    { type: "sandbox", path: ".agent/skills/project" },
+    { type: "host", path: "./skills/company" },
+    {
+      type: "git",
+      repo: "https://github.com/acme/agent-skills.git",
+      ref: "v1.2.0",
+      path: "skills",
+    },
+    {
+      type: "inline",
+      name: "incident-triage",
+      description: "Triage incidents safely",
+      instructions: "1. Gather context\n2. Confirm blast radius\n3. Propose mitigations",
+    },
+  ],
 });
 ```
 
@@ -33,10 +49,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 +60,120 @@ 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" }] } });
+// route.ts
+import { start } from "workflow/api";
+import { agentWorkflow } from "./workflow";
 
-const stream = await session.stream();
-
-// Tags for your app's metadata
-await session.tag.set("category", "support");
+const result = await start(agentWorkflow, [chatId, message, opts]);
+const stream = await session.stream(result);
+return createUIMessageStreamResponse({ stream });
 ```
 
-### 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
+## Storage
 
 ```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")
+// 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
+    });
+  },
+})
 
-// Direct access
-await session.sandbox.exec({ command: "npm", args: ["install"] });
+// 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 */ });
+  },
+})
 ```
 
-### 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 });
-```
+The SDK stores `Session`, `Message`, `Part`, `Sandbox`. Everything else — users, titles, access control — belongs in your database. Session ID is your join key.
 
 ## Skills
 
-Skills are `SKILL.md` files discovered from the sandbox:
+`skills` is the canonical skills API for both `agent(...)` defaults and `session.update(...)` overrides.
 
-```yaml
----
-name: deploy
-description: Deploy to Vercel
----
-
-Run `vercel deploy` in the project root.
-```
+- `{ type: "sandbox", path: "..." }` reads skills already present in sandbox
+- `{ type: "host", path: "..." }` copies skills from host filesystem into sandbox materialized dirs
+- `{ type: "git", ... }` clones a git repo into sandbox materialized dirs (optionally with `ref`, `path`, `name`)
+- `{ type: "inline", ... }` writes an inline `SKILL.md` into sandbox materialized dirs
 
 ```ts
-agent({ skillsDir: ".agent/skills" })
+const session = myAgent.session("chat-123");
+
+await session.update({
+  skills: [
+    {
+      type: "git",
+      repo: "https://github.com/acme/agent-skills.git",
+      ref: "main",
+      path: "skills",
+      name: "release-playbook",
+    },
+  ],
+});
 ```
 
-## MCP (this api will change soon)
+### Migration
 
-Custom tools with type-safe schemas:
+Legacy `skillsDir` configuration is deprecated. Migrate to `skills`:
 
 ```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() }),
-        },
-      },
-    }),
-  },
+// before
+agent("my-agent", {
+  skillsDir: [".agent/skills", ".agent/skills/shared"],
 });
 
-// Send with auth
-await session.send({
-  input: "List my projects",
-  mcpContext: { vercel: { headers: { authorization: `Bearer ${token}` } } },
+// after
+agent("my-agent", {
+  skills: [
+    { type: "sandbox", path: ".agent/skills" },
+    { type: "sandbox", path: ".agent/skills/shared" },
+  ],
 });
-
-// Handle in your API
-await myAgent.handleMcpToolCall(body, {
-  "vercel/listProjects": async ({ input, headers }) => {
-    return fetchProjects(input.teamId, headers.authorization);
-  },
-});
-```
-
-## 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
+## Documentation
 
-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
-
-Just deploy to Vercel and it works. No database setup, no connection strings.
-
-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
 
@@ -324,3 +185,4 @@ pnpm test         # vitest run
 pnpm test:watch   # vitest watch
 pnpm typecheck    # tsc --noEmit
 ```
+

package/dist/adapter-zgOel4wW.d.mts

@@ -0,0 +1,256 @@
+import { WORKFLOW_SERIALIZE, WORKFLOW_DESERIALIZE } from '@workflow/serde';
+import { NetworkPolicy } from '@vercel/sandbox';
+import { UIMessage } from 'ai';
+
+type SkillSourceType = "sandbox" | "host" | "git" | "inline";
+type SandboxSkillInput = {
+    type: "sandbox";
+    path: string;
+};
+type HostSkillInput = {
+    type: "host";
+    path: string;
+};
+type GitSkillInput = {
+    type: "git";
+    repo: string;
+    ref?: string;
+    path?: string;
+    /**
+     * Skill directory name under `path`.
+     */
+    name?: string;
+};
+type InlineSkillInput = {
+    type: "inline";
+    name: string;
+    description: string;
+    instructions: string;
+};
+type SkillInput = SandboxSkillInput | HostSkillInput | GitSkillInput | InlineSkillInput;
+type SandboxSkillEntry = {
+    type: "sandbox";
+    path: string;
+};
+type HostSkillEntry = {
+    type: "host";
+    path: string;
+};
+type GitSkillEntry = {
+    type: "git";
+    repo: string;
+    ref?: string;
+    path?: string;
+    /**
+     * Skill directory name under `path`.
+     */
+    name?: string;
+};
+type InlineSkillEntry = {
+    type: "inline";
+    name: string;
+    description: string;
+    instructions: string;
+};
+type SkillEntry = SandboxSkillEntry | HostSkillEntry | GitSkillEntry | InlineSkillEntry;
+
+type GenerationOptions = {
+    maxSteps?: number;
+    temperature?: number;
+    topK?: number;
+    topP?: number;
+    frequencyPenalty?: number;
+    presencePenalty?: number;
+    maxOutputTokens?: number;
+    headers?: Record<string, string>;
+};
+type Session = {
+    id: string;
+    createdAt: number;
+    updatedAt: number;
+    model: string | null;
+    system: string | null;
+    sandboxId: string | null;
+    lastMessageId: string | null;
+    activeTools: string[] | null;
+    skills: SkillInput[] | null;
+    generation: GenerationOptions | null;
+};
+type MessageUsage = {
+    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;
+    };
+};
+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: MessageUsage | null;
+    workflowRunId?: string | null;
+    metadata?: Record<string, unknown> | 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 GenerationOptions as G, type HostSkillEntry as H, type InlineSkillEntry as I, type Message as M, type Part as P, type StorageHandlers as S, type MessageUsage as a, type Sandbox as b, type Session as c, type Setup as d, type SetupSnapshot as e, type Storage as f, type StorageCall as g, StorageStep as h, type StorageStepFunction as i, type SkillInput as j, type StorageInput as k, type GitSkillEntry as l, type GitSkillInput as m, type HostSkillInput as n, type InlineSkillInput as o, type SandboxSkillEntry as p, type SandboxSkillInput as q, type SkillEntry as r, type SkillSourceType as s, toStorage as t };