formagent-sdk 0.1.1 → 0.1.3

package/README.md

@@ -8,6 +8,7 @@ A powerful AI Agent framework for building intelligent assistants with streaming
 ## Features
 
 - **Session-Based API**: Multi-turn conversations with state management
+- **Persistent Sessions**: File-based storage for session persistence across restarts
 - **Streaming Support**: Real-time streaming of LLM responses with event-based notifications
 - **Built-in Tools**: File operations, bash execution, web fetch, and task management
 - **Tool System**: Flexible tool registration with Zod schema support
@@ -227,20 +228,68 @@ for await (const event of session.receive()) {
 
 ## Session Management
 
-Resume and fork sessions:
+### Persistent Sessions
+
+Enable session persistence with `FileSessionStorage`:
 
 ```typescript
-import { createSession, resumeSession, forkSession } from "formagent-sdk"
+import { createSession, FileSessionStorage, builtinTools } from "formagent-sdk"
+
+// Create persistent storage
+const storage = new FileSessionStorage("./sessions")
+
+// Create session with persistence
+const session = await createSession({
+  model: "claude-sonnet-4-20250514",
+  tools: builtinTools,
+  sessionStorage: storage,
+})
+
+console.log(`Session ID: ${session.id}`)  // Save this for later
+await session.close()
+```
+
+### Resume Sessions
+
+Resume a previous session with full conversation context:
+
+```typescript
+import { createSession, FileSessionStorage } from "formagent-sdk"
+
+const storage = new FileSessionStorage("./sessions")
 
-// Create a session
+// Resume from saved session ID
+const session = await createSession({
+  sessionStorage: storage,
+  resume: "previous-session-id",
+})
+
+await session.send("Continue where we left off")
+```
+
+### Global Storage Configuration
+
+Set a default storage for all sessions:
+
+```typescript
+import { setDefaultStorage, FileSessionStorage, createSession } from "formagent-sdk"
+
+// Set once at startup
+setDefaultStorage(new FileSessionStorage("./sessions"))
+
+// All sessions now persist automatically
 const session = await createSession({ model: "claude-sonnet-4-20250514" })
-const sessionId = session.id
+```
 
-// Later: Resume the session
-const resumed = await resumeSession(sessionId)
+### Fork Sessions
+
+Create a branch from an existing session:
+
+```typescript
+import { forkSession } from "formagent-sdk"
 
-// Or: Fork the session (create a branch)
-const forked = await forkSession(sessionId)
+// Fork creates a new session with copied conversation history
+const forked = await forkSession("original-session-id")
 ```
 
 ## Event Types
@@ -272,6 +321,7 @@ See the [examples](./examples) directory for complete examples:
 
 - [Getting Started](./docs/getting-started.md)
 - [API Reference](./docs/api-reference.md)
+- [Session Storage](./docs/session-storage.md)
 - [Built-in Tools](./docs/tools.md)
 - [MCP Servers](./docs/mcp-servers.md)
 

package/dist/cli/index.js

@@ -2630,6 +2630,7 @@ class OpenAIProvider {
 // src/api.ts
 var globalManager = null;
 var defaultProvider = null;
+var defaultStorage = null;
 function getGlobalManager() {
   if (!globalManager) {
     if (!defaultProvider) {
@@ -2646,16 +2647,29 @@ function getGlobalManager() {
     }
     globalManager = new SessionManagerImpl({
       provider: defaultProvider,
-      storage: new MemorySessionStorage
+      storage: defaultStorage ?? new MemorySessionStorage
     });
   }
   return globalManager;
 }
 async function createSession(options) {
-  if (options?.provider) {
+  if (options?.provider || options?.sessionStorage) {
+    let provider = options?.provider ?? defaultProvider;
+    if (!provider) {
+      if (process.env.ANTHROPIC_API_KEY) {
+        provider = new AnthropicProvider;
+      } else if (process.env.OPENAI_API_KEY) {
+        provider = new OpenAIProvider({
+          apiKey: process.env.OPENAI_API_KEY,
+          baseUrl: process.env.OPENAI_BASE_URL
+        });
+      } else {
+        throw new Error("No provider available. Set ANTHROPIC_API_KEY or OPENAI_API_KEY environment variable, " + "call setDefaultProvider(), or pass a provider in the options.");
+      }
+    }
     const customManager = new SessionManagerImpl({
-      provider: options.provider,
-      storage: new MemorySessionStorage
+      provider,
+      storage: options?.sessionStorage ?? defaultStorage ?? new MemorySessionStorage
     });
     return customManager.create(options);
   }

package/dist/index.js

@@ -3014,10 +3014,15 @@ function createOpenAIProvider(config) {
 // src/api.ts
 var globalManager = null;
 var defaultProvider = null;
+var defaultStorage = null;
 function setDefaultProvider(provider2) {
   defaultProvider = provider2;
   globalManager = null;
 }
+function setDefaultStorage(storage) {
+  defaultStorage = storage;
+  globalManager = null;
+}
 function getGlobalManager() {
   if (!globalManager) {
     if (!defaultProvider) {
@@ -3034,16 +3039,29 @@ function getGlobalManager() {
     }
     globalManager = new SessionManagerImpl({
       provider: defaultProvider,
-      storage: new MemorySessionStorage
+      storage: defaultStorage ?? new MemorySessionStorage
     });
   }
   return globalManager;
 }
 async function createSession(options2) {
-  if (options2?.provider) {
+  if (options2?.provider || options2?.sessionStorage) {
+    let provider2 = options2?.provider ?? defaultProvider;
+    if (!provider2) {
+      if (process.env.ANTHROPIC_API_KEY) {
+        provider2 = new AnthropicProvider;
+      } else if (process.env.OPENAI_API_KEY) {
+        provider2 = new OpenAIProvider({
+          apiKey: process.env.OPENAI_API_KEY,
+          baseUrl: process.env.OPENAI_BASE_URL
+        });
+      } else {
+        throw new Error("No provider available. Set ANTHROPIC_API_KEY or OPENAI_API_KEY environment variable, " + "call setDefaultProvider(), or pass a provider in the options.");
+      }
+    }
     const customManager = new SessionManagerImpl({
-      provider: options2.provider,
-      storage: new MemorySessionStorage
+      provider: provider2,
+      storage: options2?.sessionStorage ?? defaultStorage ?? new MemorySessionStorage
     });
     return customManager.create(options2);
   }
@@ -5588,6 +5606,7 @@ export {
   skillTool,
   simpleTool,
   setTodoChangeCallback,
+  setDefaultStorage,
   setDefaultProvider,
   serializeFrontmatter,
   resumeSession,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "formagent-sdk",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "description": "FormAgent SDK - AI Agent framework with streaming support, tool execution, skill management, and hooks system",
   "type": "module",
   "main": "./dist/index.js",
@@ -26,9 +26,6 @@
   },
   "files": [
     "dist",
-    "src",
-    "examples",
-    "docs/*.md",
     "README.md",
     "LICENSE"
   ],

package/docs/README.md

@@ -1,122 +0,0 @@
-# formagent-sdk Documentation
-
-Welcome to the documentation for `formagent-sdk`, a Claude Agent SDK compatible framework for building AI agents with streaming support, tool execution, and skill management.
-
-## Table of Contents
-
-- [Getting Started](./getting-started.md) - Quick start guide
-- [API Reference](./api-reference.md) - Complete API documentation
-- [Built-in Tools](./tools.md) - File operations, bash, and more
-- [MCP Servers](./mcp-servers.md) - Model Context Protocol integration
-- [Examples](./examples.md) - Code examples and tutorials
-
-## Quick Links
-
-### Installation
-
-```bash
-npm install formagent-sdk
-# or
-bun add formagent-sdk
-```
-
-### Environment Setup
-
-```bash
-export ANTHROPIC_API_KEY=your-api-key
-# Optional: Custom endpoint
-export ANTHROPIC_BASE_URL=https://your-proxy.com
-```
-
-### Minimal Example
-
-```typescript
-import { createSession, builtinTools } from "formagent-sdk"
-
-const session = await createSession({
-  model: "claude-sonnet-4-20250514",
-  tools: builtinTools,
-})
-
-await session.send("List files in the current directory")
-
-for await (const event of session.receive()) {
-  if (event.type === "text") {
-    process.stdout.write(event.text)
-  }
-}
-
-await session.close()
-```
-
-## Core Concepts
-
-### Sessions
-
-Sessions manage conversations with Claude. They handle message history, tool execution, and streaming responses.
-
-```typescript
-const session = await createSession({ model: "claude-sonnet-4-20250514" })
-await session.send("Hello!")
-for await (const event of session.receive()) { /* ... */ }
-await session.close()
-```
-
-### Tools
-
-Tools extend Claude's capabilities. The SDK provides built-in tools and supports custom tool definitions.
-
-```typescript
-import { builtinTools, tool } from "formagent-sdk"
-import { z } from "zod"
-
-// Use built-in tools
-const session = await createSession({ tools: builtinTools })
-
-// Or create custom tools
-const myTool = tool({
-  name: "my_tool",
-  description: "Does something useful",
-  schema: z.object({ input: z.string() }),
-  execute: async ({ input }) => `Result: ${input}`,
-})
-```
-
-### MCP Servers
-
-MCP (Model Context Protocol) servers provide a standardized way to expose tools.
-
-```typescript
-import { createSdkMcpServer, tool } from "formagent-sdk"
-
-const server = createSdkMcpServer({
-  name: "my-server",
-  version: "1.0.0",
-  tools: [myTool],
-})
-```
-
-## Architecture
-
-```
-formagent-sdk
-├── Session API          # Conversation management
-│   ├── createSession()  # Create new sessions
-│   ├── send()          # Send messages
-│   └── receive()       # Stream responses
-├── Tool System          # Tool execution
-│   ├── builtinTools    # Built-in tools (Bash, Read, Write, etc.)
-│   ├── tool()          # Tool definition helper
-│   └── ToolManager     # Tool registration and execution
-├── MCP Integration      # Model Context Protocol
-│   ├── createSdkMcpServer()
-│   └── MCPServerManager
-└── Providers            # LLM providers
-    ├── AnthropicProvider
-    └── OpenAIProvider
-```
-
-## Support
-
-- [GitHub Issues](https://github.com/anthropics/claude-code/issues)
-- [Examples](../examples/)