march-ai-sdk 0.3.0

package/src/extensions/langgraph.ts

@@ -0,0 +1,351 @@
+/**
+ * March Agent SDK - LangGraph Extension
+ * 
+ * HTTPCheckpointSaver for LangGraph that stores state via HTTP API.
+ * 
+ * @packageDocumentation
+ */
+
+import type { MarchAgentApp } from '../app.js'
+import { CheckpointClient } from '../checkpoint-client.js'
+import type {
+    CheckpointConfig,
+    CheckpointData,
+    CheckpointMetadata as APICheckpointMetadata,
+    CheckpointTuple as APICheckpointTuple,
+} from '../checkpoint-client.js'
+
+// Type definitions for LangGraph (optional peer dependency)
+// These are compatible with @langchain/langgraph-checkpoint
+interface RunnableConfig {
+    configurable?: {
+        thread_id?: string
+        checkpoint_ns?: string
+        checkpoint_id?: string
+    }
+}
+
+interface Checkpoint {
+    v?: number
+    id?: string
+    ts?: string
+    channel_values?: Record<string, unknown>
+    channel_versions?: Record<string, string>
+    versions_seen?: Record<string, Record<string, string>>
+    pending_sends?: unknown[]
+}
+
+interface CheckpointMetadata {
+    source?: string
+    step?: number
+    writes?: unknown
+    parents?: Record<string, string>
+}
+
+interface CheckpointTuple {
+    config: RunnableConfig
+    checkpoint: Checkpoint
+    metadata: CheckpointMetadata
+    parent_config?: RunnableConfig
+    pending_writes?: unknown[]
+}
+
+interface PendingWrite {
+    [key: string]: unknown
+}
+
+/**
+ * HTTP-based checkpoint saver for LangGraph.
+ * 
+ * Stores graph state via HTTP calls to the conversation-store checkpoint API,
+ * enabling distributed checkpoint storage without direct database access.
+ * 
+ * @example
+ * ```typescript
+ * import { MarchAgentApp } from 'march-ai-sdk'
+ * import { HTTPCheckpointSaver } from 'march-ai-sdk/extensions/langgraph'
+ * import { StateGraph } from '@langchain/langgraph'
+ * 
+ * const app = new MarchAgentApp({
+ *   gatewayUrl: 'agent-gateway:8080',
+ *   apiKey: 'your-key',
+ * })
+ * 
+ * const checkpointer = new HTTPCheckpointSaver(app)
+ * 
+ * const graph = new StateGraph(MyState)
+ * // ... define graph ...
+ * const compiled = graph.compile({ checkpointer })
+ * 
+ * const config = { configurable: { thread_id: 'my-thread' } }
+ * const result = await compiled.invoke({ messages: [...] }, config)
+ * ```
+ */
+export class HTTPCheckpointSaver {
+    private readonly client: CheckpointClient
+
+    constructor(app: MarchAgentApp) {
+        this.client = new CheckpointClient(app.gatewayClient.conversationStoreUrl)
+    }
+
+    /**
+     * Get thread_id from config.
+     */
+    private getThreadId(config: RunnableConfig): string {
+        const threadId = config.configurable?.thread_id
+        if (!threadId) {
+            throw new Error('Config must contain configurable.thread_id')
+        }
+        return threadId
+    }
+
+    /**
+     * Get checkpoint_ns from config.
+     */
+    private getCheckpointNs(config: RunnableConfig): string {
+        return config.configurable?.checkpoint_ns ?? ''
+    }
+
+    /**
+     * Get checkpoint_id from config.
+     */
+    private getCheckpointId(config: RunnableConfig): string | undefined {
+        return config.configurable?.checkpoint_id
+    }
+
+    /**
+     * Generate a unique checkpoint ID.
+     */
+    private generateCheckpointId(): string {
+        return new Date().toISOString()
+    }
+
+    /**
+     * Fetch a checkpoint tuple asynchronously.
+     */
+    async getTuple(config: RunnableConfig): Promise<CheckpointTuple | undefined> {
+        const threadId = this.getThreadId(config)
+        const checkpointNs = this.getCheckpointNs(config)
+        const checkpointId = this.getCheckpointId(config)
+
+        const result = await this.client.getTuple(threadId, checkpointNs, checkpointId)
+
+        if (!result) {
+            return undefined
+        }
+
+        return this.responseToTuple(result)
+    }
+
+    /**
+     * List checkpoints asynchronously.
+     */
+    async *list(
+        config: RunnableConfig | undefined,
+        options?: {
+            filter?: Record<string, unknown>
+            before?: RunnableConfig
+            limit?: number
+        }
+    ): AsyncGenerator<CheckpointTuple> {
+        const threadId = config?.configurable?.thread_id
+        const checkpointNs = config?.configurable?.checkpoint_ns
+        const beforeId = options?.before?.configurable?.checkpoint_id
+
+        const results = await this.client.list({
+            threadId,
+            checkpointNs,
+            before: beforeId,
+            limit: options?.limit,
+        })
+
+        for (const result of results) {
+            const tuple = this.responseToTuple(result)
+            if (tuple) {
+                yield tuple
+            }
+        }
+    }
+
+    /**
+     * Store a checkpoint asynchronously.
+     */
+    async put(
+        config: RunnableConfig,
+        checkpoint: Checkpoint,
+        metadata: CheckpointMetadata,
+        newVersions?: Record<string, unknown>
+    ): Promise<RunnableConfig> {
+        const threadId = this.getThreadId(config)
+        const checkpointNs = this.getCheckpointNs(config)
+
+        let checkpointId = this.getCheckpointId(config)
+        if (!checkpointId) {
+            checkpointId = checkpoint.id ?? this.generateCheckpointId()
+        }
+
+        const apiConfig: CheckpointConfig = {
+            configurable: {
+                thread_id: threadId,
+                checkpoint_ns: checkpointNs,
+                checkpoint_id: checkpointId,
+            },
+        }
+
+        const checkpointData = this.checkpointToApi(checkpoint)
+        const metadataData = this.metadataToApi(metadata)
+
+        const result = await this.client.put(
+            apiConfig,
+            checkpointData,
+            metadataData,
+            newVersions ?? {}
+        )
+
+        return result.config as RunnableConfig
+    }
+
+    /**
+     * Store intermediate writes asynchronously.
+     */
+    async putWrites(
+        _config: RunnableConfig,
+        _writes: PendingWrite[],
+        _taskId: string
+    ): Promise<void> {
+        // Stub - writes are not persisted separately
+        // They are included in the checkpoint metadata
+    }
+
+    /**
+     * Delete all checkpoints for a thread.
+     */
+    async deleteThread(threadId: string): Promise<void> {
+        await this.client.deleteThread(threadId)
+    }
+
+    /**
+     * Convert checkpoint to API format.
+     */
+    private checkpointToApi(checkpoint: Checkpoint): CheckpointData {
+        return {
+            v: checkpoint.v ?? 1,
+            id: checkpoint.id ?? this.generateCheckpointId(),
+            ts: checkpoint.ts ?? new Date().toISOString(),
+            channel_values: this.serializeChannelValues(checkpoint.channel_values ?? {}),
+            channel_versions: checkpoint.channel_versions ?? {},
+            versions_seen: checkpoint.versions_seen ?? {},
+            pending_sends: checkpoint.pending_sends ?? [],
+        }
+    }
+
+    /**
+     * Convert metadata to API format.
+     */
+    private metadataToApi(metadata: CheckpointMetadata): APICheckpointMetadata {
+        return {
+            source: metadata.source ?? 'input',
+            step: metadata.step ?? -1,
+            writes: metadata.writes,
+            parents: metadata.parents ?? {},
+        }
+    }
+
+    /**
+     * Convert API response to CheckpointTuple.
+     */
+    private responseToTuple(response: APICheckpointTuple): CheckpointTuple {
+        return {
+            config: response.config as RunnableConfig,
+            checkpoint: this.deserializeCheckpoint(response.checkpoint),
+            metadata: response.metadata,
+            parent_config: response.parent_config as RunnableConfig | undefined,
+            pending_writes: response.pending_writes ?? [],
+        }
+    }
+
+    /**
+     * Serialize channel values for transmission.
+     */
+    private serializeChannelValues(values: Record<string, unknown>): Record<string, unknown> {
+        return this.serializeValue(values) as Record<string, unknown>
+    }
+
+    /**
+     * Serialize a value for JSON transmission.
+     */
+    private serializeValue(value: unknown, depth: number = 0): unknown {
+        const MAX_DEPTH = 100
+        if (depth > MAX_DEPTH) {
+            return { __max_depth_exceeded__: true }
+        }
+
+        if (value === null || value === undefined) {
+            return value
+        }
+
+        // Handle Buffer/Uint8Array
+        if (Buffer.isBuffer(value) || value instanceof Uint8Array) {
+            return { __bytes__: Buffer.from(value).toString('base64') }
+        }
+
+        // Handle arrays
+        if (Array.isArray(value)) {
+            return value.map(item => this.serializeValue(item, depth + 1))
+        }
+
+        // Handle objects
+        if (typeof value === 'object') {
+            const result: Record<string, unknown> = {}
+            for (const [key, val] of Object.entries(value)) {
+                result[key] = this.serializeValue(val, depth + 1)
+            }
+            return result
+        }
+
+        return value
+    }
+
+    /**
+     * Deserialize checkpoint data.
+     */
+    private deserializeCheckpoint(data: CheckpointData): Checkpoint {
+        return {
+            ...data,
+            channel_values: this.deserializeValue(data.channel_values) as Record<string, unknown>,
+        }
+    }
+
+    /**
+     * Deserialize a value.
+     */
+    private deserializeValue(value: unknown): unknown {
+        if (value === null || value === undefined) {
+            return value
+        }
+
+        if (typeof value === 'object' && !Array.isArray(value)) {
+            const obj = value as Record<string, unknown>
+
+            // Decode base64 bytes
+            if ('__bytes__' in obj && typeof obj.__bytes__ === 'string') {
+                return Buffer.from(obj.__bytes__, 'base64')
+            }
+
+            // Recurse into object
+            const result: Record<string, unknown> = {}
+            for (const [key, val] of Object.entries(obj)) {
+                result[key] = this.deserializeValue(val)
+            }
+            return result
+        }
+
+        if (Array.isArray(value)) {
+            return value.map(item => this.deserializeValue(item))
+        }
+
+        return value
+    }
+}
+
+export type { RunnableConfig, Checkpoint, CheckpointMetadata, CheckpointTuple, PendingWrite }

package/src/extensions/vercel-ai.ts

@@ -0,0 +1,177 @@
+/**
+ * March Agent SDK - Vercel AI SDK Extension
+ * 
+ * VercelAIMessageStore for persistent message history with Vercel AI SDK.
+ * 
+ * @packageDocumentation
+ */
+
+import type { MarchAgentApp } from '../app.js'
+import { AgentStateClient } from '../agent-state-client.js'
+
+// Type definitions compatible with Vercel AI SDK's CoreMessage
+interface CoreMessage {
+    role: 'system' | 'user' | 'assistant' | 'tool'
+    content: string | Array<{ type: string;[key: string]: unknown }>
+    [key: string]: unknown
+}
+
+/**
+ * Persistent message store for Vercel AI SDK.
+ * 
+ * Stores and retrieves AI SDK message history using the agent-state API.
+ * Messages are serialized as JSON for full fidelity.
+ * 
+ * @example
+ * ```typescript
+ * import { MarchAgentApp } from 'march-ai-sdk'
+ * import { VercelAIMessageStore } from 'march-ai-sdk/extensions/vercel-ai'
+ * import { streamText } from 'ai'
+ * import { openai } from '@ai-sdk/openai'
+ * 
+ * const app = new MarchAgentApp({
+ *   gatewayUrl: 'agent-gateway:8080',
+ *   apiKey: 'your-key',
+ * })
+ * 
+ * const store = new VercelAIMessageStore(app)
+ * const agent = app.registerMe({ ... })
+ * 
+ * agent.onMessage(async (message, sender) => {
+ *   // Load message history
+ *   const history = await store.load(message.conversationId)
+ *   
+ *   // Add user message
+ *   const messages: CoreMessage[] = [
+ *     ...history,
+ *     { role: 'user', content: message.content }
+ *   ]
+ *   
+ *   // Stream response
+ *   const streamer = agent.streamer(message)
+ *   
+ *   const result = await streamText({
+ *     model: openai('gpt-4o'),
+ *     messages,
+ *     onChunk: ({ chunk }) => {
+ *       if (chunk.type === 'text-delta') {
+ *         streamer.stream(chunk.textDelta)
+ *       }
+ *     }
+ *   })
+ *   
+ *   await streamer.finish()
+ *   
+ *   // Save updated history
+ *   await store.save(message.conversationId, [
+ *     ...messages,
+ *     { role: 'assistant', content: result.text }
+ *   ])
+ * })
+ * 
+ * app.run()
+ * ```
+ */
+export class VercelAIMessageStore {
+    private static readonly NAMESPACE = 'vercel_ai'
+    private readonly client: AgentStateClient
+
+    constructor(app: MarchAgentApp) {
+        this.client = new AgentStateClient(app.gatewayClient.conversationStoreUrl)
+    }
+
+    /**
+     * Load message history for a conversation.
+     * 
+     * @param conversationId - The conversation ID to load history for
+     * @returns Array of CoreMessage objects (empty array if no history)
+     */
+    async load(conversationId: string): Promise<CoreMessage[]> {
+        const result = await this.client.get(conversationId, VercelAIMessageStore.NAMESPACE)
+
+        if (!result) {
+            return []
+        }
+
+        const state = result.state ?? {}
+        const messages = state.messages as unknown[]
+
+        if (!Array.isArray(messages)) {
+            return []
+        }
+
+        // Validate and return messages
+        return messages.filter(this.isValidMessage) as CoreMessage[]
+    }
+
+    /**
+     * Save message history for a conversation.
+     * 
+     * @param conversationId - The conversation ID to save history for
+     * @param messages - Array of CoreMessage objects to save
+     */
+    async save(conversationId: string, messages: CoreMessage[]): Promise<void> {
+        await this.client.put(conversationId, VercelAIMessageStore.NAMESPACE, {
+            messages: messages.map(this.serializeMessage),
+        })
+    }
+
+    /**
+     * Clear message history for a conversation.
+     * 
+     * @param conversationId - The conversation ID to clear history for
+     */
+    async clear(conversationId: string): Promise<void> {
+        await this.client.delete(conversationId, VercelAIMessageStore.NAMESPACE)
+    }
+
+    /**
+     * Append messages to existing history.
+     * 
+     * @param conversationId - The conversation ID
+     * @param newMessages - Messages to append
+     */
+    async append(conversationId: string, newMessages: CoreMessage[]): Promise<void> {
+        const existing = await this.load(conversationId)
+        await this.save(conversationId, [...existing, ...newMessages])
+    }
+
+    /**
+     * Get the last N messages from history.
+     * 
+     * @param conversationId - The conversation ID
+     * @param count - Number of messages to retrieve
+     */
+    async getLastMessages(conversationId: string, count: number): Promise<CoreMessage[]> {
+        const history = await this.load(conversationId)
+        return history.slice(-count)
+    }
+
+    /**
+     * Validate that an object is a valid message.
+     */
+    private isValidMessage(msg: unknown): msg is CoreMessage {
+        if (typeof msg !== 'object' || msg === null) {
+            return false
+        }
+
+        const m = msg as Record<string, unknown>
+        const validRoles = ['system', 'user', 'assistant', 'tool']
+
+        return (
+            typeof m.role === 'string' &&
+            validRoles.includes(m.role) &&
+            (typeof m.content === 'string' || Array.isArray(m.content))
+        )
+    }
+
+    /**
+     * Serialize a message for storage.
+     */
+    private serializeMessage(msg: CoreMessage): Record<string, unknown> {
+        // Return a plain object copy
+        return { ...msg }
+    }
+}
+
+export type { CoreMessage }