experimental-agent 0.0.0

package/README.md

@@ -0,0 +1,243 @@
+# Agent
+
+An LLM running in a loop, with access to a sandbox, tools, and session management. Nothing more.
+
+## 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.
+- **Managed sandbox** — Auto-provisions on first use, auto-snapshots when idle, auto-resumes. You don't manage the VM.
+- **Built-in tools** — Read, Grep, List, Bash. No setup.
+
+## Quick Start
+
+```ts
+// lib/agent.ts
+import { agent } from "experimental-agent";
+
+export const myAgent = agent({
+  model: "anthropic/claude-sonnet-4",
+  instructions: "You are a helpful coding assistant.",
+});
+```
+
+```ts
+// app/api/chat/[chatId]/route.ts
+import { myAgent } from "@/lib/agent";
+
+export async function POST(req: Request, { params }: { params: { chatId: string } }) {
+  const { chatId } = await params;
+  const { message } = await req.json();
+
+  const session = await myAgent.session(chatId);
+  await session.send({ input: message });
+  const stream = await session.stream();
+
+  return new Response(stream);
+}
+
+export async function GET(req: Request, { params }: { params: { chatId: string } }) {
+  const { chatId } = await params;
+  const session = await myAgent.session(chatId);
+  const { messages, streamingMessageId } = await session.ui();
+
+  return Response.json({ messages, streamingMessageId });
+}
+```
+
+## 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
+agent({
+  model: "anthropic/claude-sonnet-4",  // Required
+  instructions: "...",                  // System prompt
+  sandbox: { type: "vercel" },          // or "local"
+  storage: { type: "vercel" },          // or "local" or "custom"
+  skillsDir: ".agent/skills",           // Skills location
+  mcp: { ... },                         // Custom tools
+})
+```
+
+## Sessions
+
+```ts
+const session = await myAgent.session(sessionId);
+
+await session.send({ input: "Hello" });
+const stream = await session.stream();
+
+// Tags for your app's metadata
+await session.tag.set("category", "support");
+```
+
+## 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)
+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 { messages, streamingMessageId } = await session.ui();
+
+  return (
+    <>
+      {messages.map((m) => (
+        <MessageView key={m.id} message={m} />
+      ))}
+      <Chat chatId={chatId} streamingMessageId={streamingMessageId} />
+    </>
+  );
+}
+```
+
+```tsx
+// chat-client.tsx
+"use client";
+
+import { useChat } from "@ai-sdk/react";
+
+export function Chat({ chatId, streamingMessageId }) {
+  const { messages, input, handleInputChange, handleSubmit, status } = useChat({
+    id: chatId,
+    api: `/api/chat/${chatId}`,
+    initialMessages: [], // hydrate from server if needed
+  });
+
+  return (
+    <>
+      {messages.map((m) => (
+        <MessageView key={m.id} message={m} />
+      ))}
+      <form onSubmit={handleSubmit}>
+        <input value={input} onChange={handleInputChange} />
+        <button type="submit" disabled={status !== "ready"}>Send</button>
+      </form>
+    </>
+  );
+}
+```
+
+### 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)
+agent({ sandbox: { type: "local" } })
+
+// Vercel (prod)
+agent({ sandbox: { type: "vercel", resources: { vcpus: 2 }, ports: [3000] } })
+
+// Direct access
+await session.sandbox.exec({ command: "npm", args: ["install"] });
+
+// Share across sessions
+await myAgent.session("s1", { sandbox: "shared_id" });
+await myAgent.session("s2", { sandbox: "shared_id" });
+```
+
+## Skills
+
+Skills are `SKILL.md` files discovered from the sandbox:
+
+```yaml
+---
+name: deploy
+description: Deploy to Vercel
+---
+
+Run `vercel deploy` in the project root.
+```
+
+```ts
+agent({ skillsDir: ".agent/skills" })
+```
+
+## MCP (this api will change soon)
+
+Custom tools with type-safe schemas:
+
+```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() }),
+        },
+      },
+    }),
+  },
+});
+
+// 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);
+  },
+});
+```
+
+## 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.
+
+### 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
+
+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`.

package/dist/agent-workflow.d.mts

@@ -0,0 +1,21 @@
+import * as workflow from 'workflow';
+import { a as StorageConfig } from './types-vRxN1Qz1.mjs';
+import 'ai';
+import 'zod';
+import 'errore';
+
+type AgentInput = {
+    sessionId: string;
+    storageConfig: StorageConfig;
+};
+type AgentMessageInput = {
+    assistantMessageId: string;
+    hookToken: string;
+};
+declare const agentMessageHook: workflow.TypedHook<AgentMessageInput, AgentMessageInput>;
+declare function agentWorkflow({ input, event, }: {
+    input: AgentInput;
+    event: AgentMessageInput;
+}): Promise<void>;
+
+export { type AgentInput, type AgentMessageInput, agentMessageHook, agentWorkflow };

package/dist/agent-workflow.d.ts

@@ -0,0 +1,21 @@
+import * as workflow from 'workflow';
+import { a as StorageConfig } from './types-vRxN1Qz1.js';
+import 'ai';
+import 'zod';
+import 'errore';
+
+type AgentInput = {
+    sessionId: string;
+    storageConfig: StorageConfig;
+};
+type AgentMessageInput = {
+    assistantMessageId: string;
+    hookToken: string;
+};
+declare const agentMessageHook: workflow.TypedHook<AgentMessageInput, AgentMessageInput>;
+declare function agentWorkflow({ input, event, }: {
+    input: AgentInput;
+    event: AgentMessageInput;
+}): Promise<void>;
+
+export { type AgentInput, type AgentMessageInput, agentMessageHook, agentWorkflow };