formagent-sdk 0.3.0 → 0.3.3

package/README.md

@@ -228,6 +228,8 @@ for await (const event of session.receive()) {
 
 ## Session Management
 
+**Default Behavior:** Sessions use in-memory storage by default. Conversation history is lost when the process exits. Use `FileSessionStorage` for persistence across restarts.
+
 ### Persistent Sessions
 
 Enable session persistence with `FileSessionStorage`:

package/dist/cli/index.js

@@ -1735,7 +1735,8 @@ class SessionImpl {
       const toolResult = await tool.execute(toolInput, context);
       let content = typeof toolResult.content === "string" ? toolResult.content : JSON.stringify(toolResult.content);
       if (needsTruncation(content)) {
-        content = await truncateToolOutput(content);
+        const truncationConfig = this.config.tempDir ? { tempDir: this.config.tempDir } : undefined;
+        content = await truncateToolOutput(content, truncationConfig);
       }
       toolResponse = toolResult;
       result = {
@@ -4262,6 +4263,7 @@ function checkDirAccess(dirPath, options) {
 
 // src/tools/builtin/bash.ts
 var DEFAULT_TIMEOUT = 120000;
+var DEFAULT_IDLE_TIMEOUT = 30000;
 var MAX_OUTPUT_LENGTH = 1e5;
 var DEFAULT_BLOCKED_PATTERNS = [
   "\\bsudo\\b",
@@ -4328,21 +4330,39 @@ function createBashTool(options = {}) {
         }
       }
       const actualTimeout = Math.min(timeout, 600000);
+      const idleTimeout = options.idleTimeout ?? DEFAULT_IDLE_TIMEOUT;
       return new Promise((resolve2) => {
         let stdout = "";
         let stderr = "";
         let killed = false;
+        let killedReason = null;
+        let lastOutputTime = Date.now();
         const proc = spawn("bash", ["-c", command], {
           cwd: cwdAccess.resolved,
           env: process.env,
-          shell: false
+          shell: false,
+          stdio: ["ignore", "pipe", "pipe"]
         });
         const timer = setTimeout(() => {
           killed = true;
+          killedReason = "timeout";
           proc.kill("SIGTERM");
           setTimeout(() => proc.kill("SIGKILL"), 1000);
         }, actualTimeout);
+        const idleChecker = setInterval(() => {
+          const idleTime = Date.now() - lastOutputTime;
+          if (idleTime >= idleTimeout && !killed) {
+            killed = true;
+            killedReason = "idle";
+            proc.kill("SIGTERM");
+            setTimeout(() => proc.kill("SIGKILL"), 1000);
+          }
+        }, 1000);
+        const updateLastOutputTime = () => {
+          lastOutputTime = Date.now();
+        };
         proc.stdout?.on("data", (data) => {
+          updateLastOutputTime();
           stdout += data.toString();
           if (stdout.length > MAX_OUTPUT_LENGTH) {
             stdout = stdout.slice(0, MAX_OUTPUT_LENGTH) + `
@@ -4351,6 +4371,7 @@ function createBashTool(options = {}) {
           }
         });
         proc.stderr?.on("data", (data) => {
+          updateLastOutputTime();
           stderr += data.toString();
           if (stderr.length > MAX_OUTPUT_LENGTH) {
             stderr = stderr.slice(0, MAX_OUTPUT_LENGTH) + `
@@ -4359,17 +4380,31 @@ function createBashTool(options = {}) {
         });
         proc.on("close", (code) => {
           clearTimeout(timer);
+          clearInterval(idleChecker);
           if (killed) {
-            resolve2({
-              content: `Command timed out after ${actualTimeout}ms
+            if (killedReason === "idle") {
+              resolve2({
+                content: `Command terminated: no output for ${idleTimeout / 1000} seconds (likely waiting for input)
 
 Partial output:
 ${stdout}
 
 Stderr:
 ${stderr}`,
-              isError: true
-            });
+                isError: true
+              });
+            } else {
+              resolve2({
+                content: `Command timed out after ${actualTimeout}ms
+
+Partial output:
+${stdout}
+
+Stderr:
+${stderr}`,
+                isError: true
+              });
+            }
             return;
           }
           const output = stdout + (stderr ? `
@@ -4390,6 +4425,7 @@ ${output}`,
         });
         proc.on("error", (error) => {
           clearTimeout(timer);
+          clearInterval(idleChecker);
           resolve2({
             content: `Failed to execute command: ${error.message}`,
             isError: true
@@ -6029,7 +6065,7 @@ ${responseText}`;
           metadata: {
             status: response.status,
             statusText: response.statusText,
-            headers: Object.fromEntries(response.headers.entries()),
+            headers: Object.fromEntries(response.headers),
             body: responseBody
           }
         };

package/dist/index.js

@@ -2129,7 +2129,8 @@ class SessionImpl {
       const toolResult = await tool2.execute(toolInput, context);
       let content = typeof toolResult.content === "string" ? toolResult.content : JSON.stringify(toolResult.content);
       if (needsTruncation(content)) {
-        content = await truncateToolOutput(content);
+        const truncationConfig = this.config.tempDir ? { tempDir: this.config.tempDir } : undefined;
+        content = await truncateToolOutput(content, truncationConfig);
       }
       toolResponse = toolResult;
       result = {
@@ -5312,6 +5313,7 @@ function checkDirAccess(dirPath, options2) {
 
 // src/tools/builtin/bash.ts
 var DEFAULT_TIMEOUT = 120000;
+var DEFAULT_IDLE_TIMEOUT = 30000;
 var MAX_OUTPUT_LENGTH = 1e5;
 var DEFAULT_BLOCKED_PATTERNS = [
   "\\bsudo\\b",
@@ -5378,21 +5380,39 @@ function createBashTool(options2 = {}) {
         }
       }
       const actualTimeout = Math.min(timeout, 600000);
+      const idleTimeout = options2.idleTimeout ?? DEFAULT_IDLE_TIMEOUT;
       return new Promise((resolve2) => {
         let stdout = "";
         let stderr = "";
         let killed = false;
+        let killedReason = null;
+        let lastOutputTime = Date.now();
         const proc = spawn("bash", ["-c", command], {
           cwd: cwdAccess.resolved,
           env: process.env,
-          shell: false
+          shell: false,
+          stdio: ["ignore", "pipe", "pipe"]
         });
         const timer = setTimeout(() => {
           killed = true;
+          killedReason = "timeout";
           proc.kill("SIGTERM");
           setTimeout(() => proc.kill("SIGKILL"), 1000);
         }, actualTimeout);
+        const idleChecker = setInterval(() => {
+          const idleTime = Date.now() - lastOutputTime;
+          if (idleTime >= idleTimeout && !killed) {
+            killed = true;
+            killedReason = "idle";
+            proc.kill("SIGTERM");
+            setTimeout(() => proc.kill("SIGKILL"), 1000);
+          }
+        }, 1000);
+        const updateLastOutputTime = () => {
+          lastOutputTime = Date.now();
+        };
         proc.stdout?.on("data", (data) => {
+          updateLastOutputTime();
           stdout += data.toString();
           if (stdout.length > MAX_OUTPUT_LENGTH) {
             stdout = stdout.slice(0, MAX_OUTPUT_LENGTH) + `
@@ -5401,6 +5421,7 @@ function createBashTool(options2 = {}) {
           }
         });
         proc.stderr?.on("data", (data) => {
+          updateLastOutputTime();
           stderr += data.toString();
           if (stderr.length > MAX_OUTPUT_LENGTH) {
             stderr = stderr.slice(0, MAX_OUTPUT_LENGTH) + `
@@ -5409,17 +5430,31 @@ function createBashTool(options2 = {}) {
         });
         proc.on("close", (code) => {
           clearTimeout(timer);
+          clearInterval(idleChecker);
           if (killed) {
-            resolve2({
-              content: `Command timed out after ${actualTimeout}ms
+            if (killedReason === "idle") {
+              resolve2({
+                content: `Command terminated: no output for ${idleTimeout / 1000} seconds (likely waiting for input)
 
 Partial output:
 ${stdout}
 
 Stderr:
 ${stderr}`,
-              isError: true
-            });
+                isError: true
+              });
+            } else {
+              resolve2({
+                content: `Command timed out after ${actualTimeout}ms
+
+Partial output:
+${stdout}
+
+Stderr:
+${stderr}`,
+                isError: true
+              });
+            }
             return;
           }
           const output = stdout + (stderr ? `
@@ -5440,6 +5475,7 @@ ${output}`,
         });
         proc.on("error", (error) => {
           clearTimeout(timer);
+          clearInterval(idleChecker);
           resolve2({
             content: `Failed to execute command: ${error.message}`,
             isError: true
@@ -7091,7 +7127,7 @@ ${responseText}`;
           metadata: {
             status: response.status,
             statusText: response.statusText,
-            headers: Object.fromEntries(response.headers.entries()),
+            headers: Object.fromEntries(response.headers),
             body: responseBody
           }
         };

package/docs/README.md

@@ -0,0 +1,126 @@
+# 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
+- [Session Storage](./session-storage.md) - Persistent session management
+- [Built-in Tools](./tools.md) - File operations, bash, and more
+- [MCP Servers](./mcp-servers.md) - Model Context Protocol integration
+
+## 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
+├── Session Storage      # Persistence layer
+│   ├── MemorySessionStorage  # In-memory (default, non-persistent)
+│   └── FileSessionStorage    # File-based persistence
+├── 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
+    └── GeminiProvider
+```
+
+## Support
+
+- [GitHub Issues](https://github.com/anthropics/claude-code/issues)
+- [Examples](../examples/)