@projectaria/cf-agents 0.1.0

package/README.md

@@ -0,0 +1,345 @@
+# @projectaria/cf-agents
+
+ARIA integration for Cloudflare Workers with Durable Objects. Build stateful AI agents with persistent memory, session management, and multi-turn conversations.
+
+## Installation
+
+```bash
+npm install @projectaria/cf-agents agents @cloudflare/ai-chat ai
+```
+
+## Quick Start
+
+### 1. Create Your Agent
+
+```typescript
+// src/agent.ts
+import { AriaAgent } from "@projectaria/cf-agents";
+import { createAgent } from "@projectaria/aria-agents";
+import { openai } from "@ai-sdk/openai";
+
+export class MyAssistant extends AriaAgent {
+  // Create an ARIA agent with your configuration
+  private ariaAgent = createAgent({
+    id: "assistant",
+    name: "My Assistant",
+    instructions: "You are a helpful assistant that remembers user preferences.",
+    model: openai("gpt-4o"),
+  });
+
+  // Handle incoming chat messages
+  async onChatMessage(onFinish: () => void) {
+    // Get the current session with message history
+    const session = this.getSession();
+    const lastMessage = session.messages[session.messages.length - 1];
+
+    if (!lastMessage) {
+      return;
+    }
+
+    // Run the ARIA agent with automatic memory persistence
+    const result = await this.runAriaAgent(this.ariaAgent, lastMessage.content);
+
+    // Call onFinish to signal completion
+    onFinish();
+
+    // Return response (for HTTP) or it's already sent via WebSocket
+    return new Response(result.text);
+  }
+}
+```
+
+### 2. Configure Your Worker
+
+```typescript
+// src/index.ts
+import { routeAgentRequest } from "agents";
+import { MyAssistant } from "./agent";
+
+export { MyAssistant };
+
+export default {
+  async fetch(request: Request, env: Env): Promise<Response> {
+    // Route requests to your agent
+    return (
+      (await routeAgentRequest(request, env)) ||
+      new Response("Not found", { status: 404 })
+    );
+  },
+};
+```
+
+### 3. Configure Wrangler
+
+```jsonc
+// wrangler.jsonc
+{
+  "name": "my-assistant",
+  "main": "src/index.ts",
+  "compatibility_date": "2025-02-11",
+  "compatibility_flags": ["nodejs_compat"],
+  "durable_objects": {
+    "bindings": [
+      {
+        "name": "MyAssistant",
+        "class_name": "MyAssistant"
+      }
+    ]
+  },
+  "migrations": [
+    {
+      "tag": "v1",
+      "new_sqlite_classes": ["MyAssistant"]
+    }
+  ]
+}
+```
+
+### 4. Deploy
+
+```bash
+npx wrangler deploy
+```
+
+## Features
+
+### Memory Primitives
+
+AriaAgent provides three levels of memory:
+
+| Memory Type | Scope | Use Case |
+|-------------|-------|----------|
+| **Session** | Current conversation | Message history, flow state |
+| **State** | Working memory | Shopping cart, form data |
+| **Memory** | Cross-session | User preferences, learned facts |
+
+### Working Memory (Session-scoped)
+
+```typescript
+class MyAgent extends AriaAgent {
+  async onChatMessage(onFinish) {
+    // Store data for current session
+    this.setWorkingMemory("cart", { items: ["item1", "item2"] });
+    
+    // Retrieve working memory
+    const memory = this.getWorkingMemory();
+    console.log(memory.cart); // { items: ["item1", "item2"] }
+  }
+}
+```
+
+### Cross-Session Memory
+
+```typescript
+class MyAgent extends AriaAgent {
+  async onChatMessage(onFinish) {
+    // Store a preference that persists across sessions
+    this.storeMemory({
+      key: "user:theme",
+      value: { theme: "dark", fontSize: "large" },
+      type: "preference",
+    });
+
+    // Search memories
+    const results = this.searchMemories({
+      query: "theme",
+      types: ["preference"],
+      limit: 5,
+    });
+  }
+}
+```
+
+### Flow Orchestration
+
+```typescript
+import { createFlow } from "@projectaria/aria-agents";
+
+class MyAgent extends AriaAgent {
+  private orderFlow = createFlow({
+    id: "order-flow",
+    nodes: [
+      { id: "collect-items", ... },
+      { id: "confirm-order", ... },
+      { id: "payment", ... },
+    ],
+  });
+
+  constructor(ctx, env) {
+    super(ctx, env);
+    this.registerFlow(this.orderFlow);
+  }
+}
+```
+
+## API Reference
+
+### AriaAgent Class
+
+```typescript
+class AriaAgent extends AIChatAgent<AriaEnv, AriaSessionState> {
+  // Session Management
+  getSession(): AriaSession
+  
+  // Working Memory
+  getWorkingMemory(): WorkingMemory
+  setWorkingMemory(key: string, value: unknown): void
+  clearWorkingMemory(): void
+  
+  // Cross-Session Memory
+  storeMemory(memory: Omit<AriaMemory, "id" | ...>): string
+  searchMemories(query: MemorySearchQuery): MemorySearchResult[]
+  
+  // ARIA Integration
+  runAriaAgent(agent, input, options?): Promise<{ text: string; session: AgentSession }>
+  streamAriaAgent(agent, input, options?): AsyncIterable<string>
+  
+  // Flow Orchestration
+  registerFlow(flow: FlowDefinition): void
+  transitionFlow(flowId: string, toNodeId: string): void
+}
+```
+
+## Connecting from Client
+
+### Using React
+
+```tsx
+import { useAgentChat } from "@cloudflare/ai-chat/react";
+
+function Chat() {
+  const { messages, input, handleInputChange, handleSubmit } = useAgentChat({
+    agent: "my-assistant",
+  });
+
+  return (
+    <div>
+      {messages.map((m) => (
+        <div key={m.id}>{m.content}</div>
+      ))}
+      <form onSubmit={handleSubmit}>
+        <input value={input} onChange={handleInputChange} />
+        <button type="submit">Send</button>
+      </form>
+    </div>
+  );
+}
+```
+
+### Using WebSocket
+
+```typescript
+const ws = new WebSocket("wss://your-worker.workers.dev/agents/my-assistant/session-123");
+
+ws.onopen = () => {
+  ws.send(JSON.stringify({
+    type: "cf.agent.chat.request",
+    init: {
+      method: "POST",
+      body: JSON.stringify({
+        messages: [{ role: "user", content: "Hello!" }]
+      })
+    }
+  }));
+};
+
+ws.onmessage = (event) => {
+  const data = JSON.parse(event.data);
+  console.log("Response:", data);
+};
+```
+
+### Using HTTP
+
+```typescript
+const response = await fetch("https://your-worker.workers.dev/agents/my-assistant/session-123", {
+  method: "POST",
+  headers: { "Content-Type": "application/json" },
+  body: JSON.stringify({
+    messages: [{ role: "user", content: "Hello!" }]
+  })
+});
+```
+
+## Environment Configuration
+
+```typescript
+// src/types.ts
+interface Env {
+  MyAssistant: DurableObjectNamespace;
+  OPENAI_API_KEY: string;
+}
+```
+
+```toml
+# wrangler.toml (secrets)
+[vars]
+# Set via: npx wrangler secret put OPENAI_API_KEY
+```
+
+## Complete Example
+
+```typescript
+// src/shopping-assistant.ts
+import { AriaAgent } from "@projectaria/cf-agents";
+import { createAgent } from "@projectaria/aria-agents";
+import { openai } from "@ai-sdk/openai";
+import { tool } from "ai";
+import { z } from "zod";
+
+export class ShoppingAssistant extends AriaAgent {
+  private agent = createAgent({
+    id: "shopping-assistant",
+    name: "Shopping Assistant",
+    instructions: `You are a helpful shopping assistant.
+You remember user preferences and can help them find products.
+Use the cart tools to manage their shopping cart.`,
+    model: openai("gpt-4o"),
+    tools: {
+      addToCart: tool({
+        description: "Add an item to the cart",
+        parameters: z.object({
+          item: z.string(),
+          quantity: z.number().default(1),
+        }),
+        execute: async ({ item, quantity }) => {
+          const cart = this.getWorkingMemory().cart || [];
+          cart.push({ item, quantity });
+          this.setWorkingMemory("cart", cart);
+          return { success: true, cart };
+        },
+      }),
+      viewCart: tool({
+        description: "View the current cart",
+        parameters: z.object({}),
+        execute: async () => {
+          return this.getWorkingMemory().cart || [];
+        },
+      }),
+    },
+  });
+
+  async onChatMessage(onFinish: () => void) {
+    const session = this.getSession();
+    const lastMessage = session.messages[session.messages.length - 1];
+
+    if (!lastMessage) return;
+
+    // Check for returning user preferences
+    const prefs = this.searchMemories({
+      types: ["preference"],
+      limit: 5,
+    });
+
+    // Run agent with context
+    const result = await this.runAriaAgent(this.agent, lastMessage.content);
+
+    onFinish();
+    return new Response(result.text);
+  }
+}
+```
+
+## License
+
+MIT

package/dist/AriaAgent.d.ts

@@ -0,0 +1,173 @@
+/**
+ * ARIA Agent - Cloudflare Agents integration with proper memory primitives
+ *
+ * Memory Architecture:
+ * 1. Session: Current conversation thread with chronological messages
+ * 2. State: Temporary data within the current conversation (working memory)
+ * 3. Memory: Searchable, cross-session information (knowledge base)
+ *
+ * AI SDK 6.0 Message Types (matching agents@0.3.3):
+ * - UIMessage: Format with UI metadata (id, role, parts)
+ * - ModelMessage: Format expected by LLM models
+ * - convertToModelMessages: Converts UIMessage[] to ModelMessage[]
+ */
+import { AIChatAgent } from "agents/ai-chat-agent";
+import { type AgentContext } from "agents";
+import type { StreamTextOnFinishCallback, ToolSet } from "ai";
+import type { AriaEnv, AriaMemory, AriaSession, AriaSessionState, FlowTransition, MemorySearchQuery, MemorySearchResult, WorkingMemory } from "./types";
+/**
+ * ARIA Agent extending AIChatAgent
+ *
+ * Provides:
+ * - Session management with conversation history
+ * - State management (working memory) for session-local data
+ * - Memory layer for cross-session knowledge
+ * - Flow orchestration integration
+ * - Multi-turn conversation support
+ */
+export declare class AriaAgent extends AIChatAgent<AriaEnv, AriaSessionState> {
+    private config;
+    private flowDefinitions;
+    constructor(ctx: AgentContext, env: AriaEnv);
+    /**
+     * Initialize ARIA-specific database tables
+     */
+    private initializeTables;
+    /**
+     * Initial state when no session exists
+     */
+    initialState: AriaSessionState;
+    /**
+     * Get the current session
+     * Session = Current conversation thread with chronological messages
+     */
+    getSession(): AriaSession;
+    /**
+     * Get session creation time from storage
+     */
+    private getCreatedAt;
+    /**
+     * Record a session event for tracking
+     */
+    private recordSessionEvent;
+    /**
+     * Get working memory (state within current conversation)
+     * Examples: shopping cart items, user preferences mentioned in this session
+     */
+    getWorkingMemory(): WorkingMemory;
+    /**
+     * Set a value in working memory
+     */
+    setWorkingMemory(key: string, value: unknown): void;
+    /**
+     * Clear all working memory
+     */
+    clearWorkingMemory(): void;
+    /**
+     * Store a memory for cross-session retrieval
+     * Memory = Searchable, cross-session information (knowledge base)
+     */
+    storeMemory(memory: Omit<AriaMemory, "id" | "createdAt" | "lastAccessedAt" | "accessCount">): string;
+    /**
+     * Search memory by query
+     * Returns relevant memories across all sessions
+     */
+    searchMemories(query: MemorySearchQuery): MemorySearchResult[];
+    /**
+     * Get a specific memory by key
+     */
+    getMemory(key: string): AriaMemory | null;
+    /**
+     * Update memory access (increments access count and updates timestamp)
+     */
+    private updateMemoryAccess;
+    /**
+     * Clean up old memories based on retention policy
+     */
+    cleanupOldMemories(): void;
+    /**
+     * Register a flow definition
+     */
+    registerFlow(flow: import("@projectaria/aria-agents").FlowDefinition): void;
+    /**
+     * Record a flow transition
+     */
+    recordFlowTransition(flowId: string, fromNodeId: string | null, toNodeId: string, metadata?: Record<string, unknown>): void;
+    /**
+     * Get flow transition history
+     */
+    getFlowHistory(flowId?: string, limit?: number): FlowTransition[];
+    /**
+     * Handle incoming chat messages
+     * This is where ARIA's flow orchestration would be integrated
+     */
+    onChatMessage(onFinish: StreamTextOnFinishCallback<ToolSet>, options?: {
+        abortSignal?: AbortSignal;
+        clientTools?: Array<{
+            name: string;
+            description?: string;
+            parameters?: import("ai").JSONSchema7;
+        }>;
+    }): Promise<Response | undefined>;
+    /**
+     * Build system prompt with conversation context
+     */
+    private buildSystemPrompt;
+    /**
+     * Run an ARIA agent with persistence
+     * This method allows you to use ARIA's createAgent() with persistent memory
+     *
+     * @param agent - The ARIA agent created via createAgent()
+     * @param input - The user input
+     * @returns The agent response with persisted session state
+     */
+    runAriaAgent(agent: import("@projectaria/aria-agents").Agent, input: string): Promise<{
+        text: string;
+        session: import("@projectaria/aria-agents").AgentSession;
+    }>;
+    /**
+     * Stream an ARIA agent response with persistence
+     *
+     * @param agent - The ARIA agent created via createAgent()
+     * @param input - The user input
+     * @returns Stream result with session
+     */
+    streamAriaAgent(agent: import("@projectaria/aria-agents").Agent, input: string): Promise<{
+        fullStream: AsyncIterable<import("@projectaria/aria-agents").AriaStreamPart>;
+        textStream: AsyncIterable<string>;
+        usage?: Promise<import("ai").LanguageModelUsage | undefined>;
+    }>;
+    /**
+     * Build ARIA agent prompt with context from session and memories
+     */
+    private buildAriaAgentPrompt;
+    /**
+     * Extract and store memories from ARIA agent conversation
+     */
+    private extractAndStoreMemories;
+    /**
+     * Extract preference key from message content
+     */
+    private extractPreferenceKey;
+    /**
+     * Extract fact key from message content
+     */
+    private extractFactKey;
+    /**
+     * Called when agent starts
+     */
+    onStart(): Promise<void>;
+    /**
+     * Called when a client connects
+     */
+    onConnect(connection: import("agents").Connection, ctx: import("agents").ConnectionContext): Promise<void>;
+    /**
+     * Cleanup when destroyed
+     */
+    destroy(): Promise<void>;
+    /**
+     * Handle HTTP requests
+     */
+    onRequest(request: Request): Promise<Response>;
+}
+//# sourceMappingURL=AriaAgent.d.ts.map

package/dist/AriaAgent.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"AriaAgent.d.ts","sourceRoot":"","sources":["../src/AriaAgent.ts"],"names":[],"mappings":"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"}