march-ai-sdk 0.3.0

package/src/gateway-client.ts

@@ -0,0 +1,420 @@
+/**
+ * March Agent SDK - Gateway Client
+ * Port of Python march_agent/gateway_client.py
+ * 
+ * gRPC client for communicating with the Agent Gateway.
+ */
+
+import * as grpc from '@grpc/grpc-js'
+import * as protoLoader from '@grpc/proto-loader'
+import { fileURLToPath } from 'url'
+import { dirname, join } from 'path'
+import { GatewayError } from './exceptions.js'
+import type { KafkaMessage, ProduceAck } from './types.js'
+
+const __filename = fileURLToPath(import.meta.url)
+const __dirname = dirname(__filename)
+
+// Load proto file
+const PROTO_PATH = join(__dirname, 'proto', 'gateway.proto')
+
+const packageDefinition = protoLoader.loadSync(PROTO_PATH, {
+    keepCase: true,
+    longs: String,
+    enums: String,
+    defaults: true,
+    oneofs: true,
+})
+
+const gatewayProto = grpc.loadPackageDefinition(packageDefinition) as unknown as {
+    gateway: {
+        AgentGateway: new (
+            address: string,
+            credentials: grpc.ChannelCredentials
+        ) => AgentGatewayClient
+    }
+}
+
+interface AgentGatewayClient {
+    AgentStream(): grpc.ClientDuplexStream<ClientMessage, ServerMessage>
+}
+
+interface ClientMessage {
+    auth?: { api_key: string; agent_names: string[] }
+    subscribe?: { agent_name: string }
+    unsubscribe?: { agent_name: string }
+    produce?: {
+        topic: string
+        key: string
+        headers: Record<string, string>
+        body: Buffer
+        correlation_id: string
+    }
+    ping?: { timestamp: string }
+}
+
+interface ServerMessage {
+    auth_response?: { connection_id: string; subscribed_topics: string[] }
+    message?: {
+        topic: string
+        partition: number
+        offset: string
+        key: string
+        headers: Record<string, string>
+        body: Buffer
+        timestamp: string
+    }
+    produce_ack?: {
+        topic: string
+        partition: number
+        offset: string
+        correlation_id: string
+    }
+    subscribe_ack?: { topic: string }
+    unsubscribe_ack?: { agent_name: string }
+    pong?: { client_timestamp: string; server_timestamp: string }
+    error?: { code: string; message: string; correlation_id: string }
+}
+
+/**
+ * Client for communicating with the Agent Gateway.
+ * Provides gRPC bidirectional streaming for Kafka consume/produce.
+ */
+export class GatewayClient {
+    private readonly gatewayUrl: string
+    private readonly apiKey: string
+    private readonly secure: boolean
+
+    private client?: AgentGatewayClient
+    private stream?: grpc.ClientDuplexStream<ClientMessage, ServerMessage>
+    private _connectionId?: string
+    private messageQueue: KafkaMessage[] = []
+    private pendingProduceAcks: Map<string, (ack: ProduceAck) => void> = new Map()
+    private pendingSubscribeAcks: Map<string, (topic: string) => void> = new Map()
+    private messageHandlers: Map<string, (msg: KafkaMessage) => void> = new Map()
+    private correlationCounter: number = 0
+    private connected: boolean = false
+
+    constructor(gatewayUrl: string, apiKey: string, secure: boolean = false) {
+        this.gatewayUrl = gatewayUrl
+        this.apiKey = apiKey
+        this.secure = secure
+    }
+
+    /**
+     * HTTP URL for AI Inventory service via proxy.
+     */
+    get aiInventoryUrl(): string {
+        const protocol = this.secure ? 'https' : 'http'
+        return `${protocol}://${this.gatewayUrl}/s/ai-inventory`
+    }
+
+    /**
+     * HTTP URL for Conversation Store service via proxy.
+     */
+    get conversationStoreUrl(): string {
+        const protocol = this.secure ? 'https' : 'http'
+        return `${protocol}://${this.gatewayUrl}/s/conversation-store`
+    }
+
+    /**
+     * HTTP URL for AI Memory service via proxy.
+     */
+    get aiMemoryUrl(): string {
+        const protocol = this.secure ? 'https' : 'http'
+        return `${protocol}://${this.gatewayUrl}/s/ai-memory`
+    }
+
+    /**
+     * HTTP URL for Attachment service via proxy.
+     */
+    get attachmentUrl(): string {
+        const protocol = this.secure ? 'https' : 'http'
+        return `${protocol}://${this.gatewayUrl}/s/attachment`
+    }
+
+    /**
+     * Register a handler for a topic.
+     */
+    registerHandler(topic: string, handler: (msg: KafkaMessage) => void): void {
+        this.messageHandlers.set(topic, handler)
+    }
+
+    /**
+     * Connect to the gateway and authenticate.
+     */
+    async connect(agentNames: string[]): Promise<string[]> {
+        const credentials = this.secure
+            ? grpc.credentials.createSsl()
+            : grpc.credentials.createInsecure()
+
+        this.client = new gatewayProto.gateway.AgentGateway(
+            this.gatewayUrl,
+            credentials
+        )
+
+        this.stream = this.client.AgentStream()
+
+        // Set up message handling
+        this.stream.on('data', (msg: ServerMessage) => {
+            this.handleServerMessage(msg)
+        })
+
+        this.stream.on('error', (err: Error) => {
+            console.error('Gateway stream error:', err)
+            this.connected = false
+        })
+
+        this.stream.on('end', () => {
+            console.log('Gateway stream ended')
+            this.connected = false
+        })
+
+        // Send auth request
+        return new Promise((resolve, reject) => {
+            const timeout = setTimeout(() => {
+                reject(new GatewayError('Authentication timeout'))
+            }, 10000)
+
+            const authHandler = (msg: ServerMessage) => {
+                if (msg.auth_response) {
+                    clearTimeout(timeout)
+                    this._connectionId = msg.auth_response.connection_id
+                    this.connected = true
+                    resolve(msg.auth_response.subscribed_topics)
+                } else if (msg.error) {
+                    clearTimeout(timeout)
+                    reject(new GatewayError(`Authentication failed: ${msg.error.message}`))
+                }
+            }
+
+            // Temporarily override handler for auth response
+            const originalHandler = this.handleServerMessage.bind(this)
+            this.handleServerMessage = (msg: ServerMessage) => {
+                if (msg.auth_response || msg.error) {
+                    authHandler(msg)
+                    this.handleServerMessage = originalHandler
+                } else {
+                    originalHandler(msg)
+                }
+            }
+
+            this.stream!.write({
+                auth: {
+                    api_key: this.apiKey,
+                    agent_names: agentNames,
+                },
+            })
+        })
+    }
+
+    /**
+     * Handle incoming server messages.
+     */
+    private handleServerMessage(msg: ServerMessage): void {
+        if (msg.message) {
+            const kafkaMsg: KafkaMessage = {
+                topic: msg.message.topic,
+                partition: msg.message.partition,
+                offset: parseInt(msg.message.offset, 10),
+                key: msg.message.key,
+                headers: msg.message.headers,
+                body: JSON.parse(msg.message.body.toString()),
+                timestamp: parseInt(msg.message.timestamp, 10),
+            }
+
+            // Check for registered handler
+            const handler = this.messageHandlers.get(kafkaMsg.topic)
+            if (handler) {
+                handler(kafkaMsg)
+            } else {
+                // Queue message if no handler
+                this.messageQueue.push(kafkaMsg)
+            }
+        } else if (msg.produce_ack) {
+            const callback = this.pendingProduceAcks.get(msg.produce_ack.correlation_id)
+            if (callback) {
+                callback({
+                    topic: msg.produce_ack.topic,
+                    partition: msg.produce_ack.partition,
+                    offset: parseInt(msg.produce_ack.offset, 10),
+                    correlationId: msg.produce_ack.correlation_id,
+                })
+                this.pendingProduceAcks.delete(msg.produce_ack.correlation_id)
+            }
+        } else if (msg.subscribe_ack) {
+            const callback = this.pendingSubscribeAcks.get(msg.subscribe_ack.topic)
+            if (callback) {
+                callback(msg.subscribe_ack.topic)
+                this.pendingSubscribeAcks.delete(msg.subscribe_ack.topic)
+            }
+        } else if (msg.error) {
+            console.error('Gateway error:', msg.error.message)
+        }
+    }
+
+    /**
+     * Subscribe to an additional agent's topic.
+     */
+    async subscribe(agentName: string): Promise<string> {
+        if (!this.stream || !this.connected) {
+            throw new GatewayError('Not connected')
+        }
+
+        return new Promise((resolve, reject) => {
+            const timeout = setTimeout(() => {
+                reject(new GatewayError('Subscribe timeout'))
+            }, 5000)
+
+            const expectedTopic = `${agentName}.inbox`
+            this.pendingSubscribeAcks.set(expectedTopic, (topic) => {
+                clearTimeout(timeout)
+                resolve(topic)
+            })
+
+            this.stream!.write({
+                subscribe: { agent_name: agentName },
+            })
+        })
+    }
+
+    /**
+     * Unsubscribe from an agent's topic.
+     */
+    unsubscribe(agentName: string): void {
+        if (!this.stream || !this.connected) {
+            throw new GatewayError('Not connected')
+        }
+
+        this.stream.write({
+            unsubscribe: { agent_name: agentName },
+        })
+    }
+
+    /**
+     * Produce a message to Kafka via the gateway.
+     */
+    produce(
+        topic: string,
+        key: string,
+        headers: Record<string, string>,
+        body: Record<string, unknown>,
+        correlationId?: string
+    ): void {
+        if (!this.stream || !this.connected) {
+            throw new GatewayError('Not connected')
+        }
+
+        const corrId = correlationId ?? `${++this.correlationCounter}`
+
+        this.stream.write({
+            produce: {
+                topic,
+                key,
+                headers,
+                body: Buffer.from(JSON.stringify(body)),
+                correlation_id: corrId,
+            },
+        })
+    }
+
+    /**
+     * Produce a message and wait for acknowledgment.
+     */
+    async produceAndWait(
+        topic: string,
+        key: string,
+        headers: Record<string, string>,
+        body: Record<string, unknown>
+    ): Promise<ProduceAck> {
+        if (!this.stream || !this.connected) {
+            throw new GatewayError('Not connected')
+        }
+
+        const correlationId = `${++this.correlationCounter}`
+
+        return new Promise((resolve, reject) => {
+            const timeout = setTimeout(() => {
+                this.pendingProduceAcks.delete(correlationId)
+                reject(new GatewayError('Produce timeout'))
+            }, 10000)
+
+            this.pendingProduceAcks.set(correlationId, (ack) => {
+                clearTimeout(timeout)
+                resolve(ack)
+            })
+
+            this.stream!.write({
+                produce: {
+                    topic,
+                    key,
+                    headers,
+                    body: Buffer.from(JSON.stringify(body)),
+                    correlation_id: correlationId,
+                },
+            })
+        })
+    }
+
+    /**
+     * Consume a single message (polling from queue).
+     */
+    consumeOne(_timeout: number = 1000): KafkaMessage | null {
+        if (this.messageQueue.length > 0) {
+            return this.messageQueue.shift()!
+        }
+        return null
+    }
+
+    /**
+     * Send a ping to the gateway.
+     */
+    ping(): void {
+        if (!this.stream || !this.connected) {
+            throw new GatewayError('Not connected')
+        }
+
+        this.stream.write({
+            ping: { timestamp: String(Date.now()) },
+        })
+    }
+
+    /**
+     * Make a sync POST request (used for registration).
+     */
+    async httpPost(
+        service: string,
+        path: string,
+        body: unknown
+    ): Promise<Response> {
+        const protocol = this.secure ? 'https' : 'http'
+        const url = `${protocol}://${this.gatewayUrl}/s/${service}${path}`
+
+        return fetch(url, {
+            method: 'POST',
+            headers: {
+                'Content-Type': 'application/json',
+                'X-API-Key': this.apiKey,
+            },
+            body: JSON.stringify(body),
+        })
+    }
+
+    /**
+     * Check if connected.
+     */
+    isConnected(): boolean {
+        return this.connected
+    }
+
+    /**
+     * Close the gateway connection.
+     */
+    close(): void {
+        if (this.stream) {
+            this.stream.end()
+            this.stream = undefined
+        }
+        this.connected = false
+    }
+}

package/src/heartbeat.ts

@@ -0,0 +1,89 @@
+/**
+ * March Agent SDK - Heartbeat Manager
+ * Port of Python march_agent/heartbeat.py
+ */
+
+import type { GatewayClient } from './gateway-client.js'
+import { AI_INVENTORY_PATHS, SERVICES } from './api-paths.js'
+
+/**
+ * Manages periodic heartbeats to keep the agent status active.
+ * Sends heartbeats via HTTP to the AI Inventory service.
+ */
+export class HeartbeatManager {
+    private readonly gatewayClient: GatewayClient
+    private readonly agentName: string
+    private readonly intervalMs: number
+    private timer?: ReturnType<typeof setInterval>
+    private running: boolean = false
+
+    constructor(
+        gatewayClient: GatewayClient,
+        agentName: string,
+        intervalSeconds: number = 60
+    ) {
+        this.gatewayClient = gatewayClient
+        this.agentName = agentName
+        this.intervalMs = intervalSeconds * 1000
+    }
+
+    /**
+     * Start sending heartbeats.
+     */
+    start(): void {
+        if (this.running) {
+            return
+        }
+
+        this.running = true
+        this.timer = setInterval(() => {
+            this.sendHeartbeat()
+        }, this.intervalMs)
+
+        // Send first heartbeat immediately
+        this.sendHeartbeat()
+    }
+
+    /**
+     * Stop sending heartbeats.
+     */
+    stop(): void {
+        this.running = false
+        if (this.timer) {
+            clearInterval(this.timer)
+            this.timer = undefined
+        }
+    }
+
+    /**
+     * Send a single heartbeat via HTTP to AI Inventory.
+     */
+    private async sendHeartbeat(): Promise<void> {
+        if (!this.running) {
+            return
+        }
+
+        try {
+            const response = await this.gatewayClient.httpPost(
+                SERVICES.AI_INVENTORY,
+                AI_INVENTORY_PATHS.HEALTH_HEARTBEAT,
+                { name: this.agentName }
+            )
+
+            if (response.status === 404) {
+                console.warn(`Agent '${this.agentName}' not found. Re-registration may be needed.`)
+            } else if (!response.ok) {
+                console.warn(`Heartbeat returned status ${response.status}`)
+            }
+        } catch (error) {
+            console.error('Heartbeat failed:', error)
+        }
+    }
+
+    /**
+     * Check if heartbeat is running.
+     */
+    isRunning(): boolean {
+        return this.running
+    }
+}

package/src/index.ts

@@ -0,0 +1,70 @@
+/**
+ * March Agent SDK - TypeScript framework for building AI agents
+ * 
+ * @packageDocumentation
+ */
+
+// Main classes
+export { MarchAgentApp } from './app.js'
+export { Agent, SenderFilter } from './agent.js'
+export { Message } from './message.js'
+export { Streamer } from './streamer.js'
+export { Conversation } from './conversation.js'
+export { Memory } from './memory.js'
+
+// Message types
+export { ConversationMessage } from './conversation-message.js'
+export { type Artifact, type ArtifactType, type ArtifactInput, toArtifact } from './artifact.js'
+
+// Clients
+export { GatewayClient } from './gateway-client.js'
+export { ConversationClient } from './conversation-client.js'
+export { CheckpointClient, type CheckpointConfig, type CheckpointData, type CheckpointMetadata, type CheckpointTuple } from './checkpoint-client.js'
+export { AgentStateClient, type AgentStateResponse } from './agent-state-client.js'
+export { MemoryClient } from './memory-client.js'
+export { AttachmentClient, createAttachmentInfo, type AttachmentInfo } from './attachment-client.js'
+
+// Helpers
+export { HeartbeatManager } from './heartbeat.js'
+
+// API Paths Configuration
+export {
+    AI_INVENTORY_PATHS,
+    CONVERSATION_STORE_PATHS,
+    MEMORY_PATHS,
+    SERVICES,
+    type ServiceName,
+} from './api-paths.js'
+
+// Types
+export type {
+    KafkaMessage,
+    KafkaHeaders,
+    AgentRegistrationData,
+    RegisterOptions,
+    MessageHandler,
+    SenderFilterOptions,
+    StreamOptions,
+    StreamerOptions,
+    AppOptions,
+    ConversationData,
+    GetMessagesOptions,
+    MemoryMessage,
+    MemorySearchResult,
+    UserSummary,
+    ProduceAck,
+} from './types.js'
+
+// Exceptions
+export {
+    MarchAgentError,
+    RegistrationError,
+    KafkaError,
+    ConfigurationError,
+    APIException,
+    HeartbeatError,
+    GatewayError,
+} from './exceptions.js'
+
+// Version
+export const VERSION = '0.3.0'

package/src/memory-client.ts

@@ -0,0 +1,125 @@
+/**
+ * March Agent SDK - Memory Client
+ * Port of Python march_agent/memory_client.py
+ */
+
+import { APIException } from './exceptions.js'
+import type { MemoryMessage, MemorySearchResult, UserSummary } from './types.js'
+
+/**
+ * Async HTTP client for AI memory API.
+ * Provides long-term memory storage and semantic search.
+ */
+export class MemoryClient {
+    private readonly baseUrl: string
+
+    constructor(baseUrl: string) {
+        this.baseUrl = baseUrl.replace(/\/$/, '')
+    }
+
+    /**
+     * Add messages to memory for a user/conversation.
+     */
+    async addMessages(
+        userId: string,
+        conversationId: string,
+        messages: MemoryMessage[]
+    ): Promise<{ added: number }> {
+        const url = `${this.baseUrl}/memory/${userId}/messages`
+        const payload = {
+            conversation_id: conversationId,
+            messages,
+        }
+
+        try {
+            const response = await fetch(url, {
+                method: 'POST',
+                headers: { 'Content-Type': 'application/json' },
+                body: JSON.stringify(payload),
+            })
+
+            if (!response.ok) {
+                const errorText = await response.text()
+                throw new APIException(`Failed to add messages to memory: ${response.status} - ${errorText}`, response.status)
+            }
+
+            return await response.json() as { added: number }
+        } catch (error) {
+            if (error instanceof APIException) throw error
+            throw new APIException(`Failed to add messages to memory: ${error}`)
+        }
+    }
+
+    /**
+     * Search memory for relevant content.
+     */
+    async search(
+        userId: string,
+        query: string,
+        limit: number = 10
+    ): Promise<MemorySearchResult[]> {
+        const url = new URL(`${this.baseUrl}/memory/${userId}/search`)
+        url.searchParams.set('query', query)
+        url.searchParams.set('limit', String(limit))
+
+        try {
+            const response = await fetch(url.toString())
+
+            if (!response.ok) {
+                const errorText = await response.text()
+                throw new APIException(`Failed to search memory: ${response.status} - ${errorText}`, response.status)
+            }
+
+            return await response.json() as MemorySearchResult[]
+        } catch (error) {
+            if (error instanceof APIException) throw error
+            throw new APIException(`Failed to search memory: ${error}`)
+        }
+    }
+
+    /**
+     * Get user summary.
+     */
+    async getUserSummary(userId: string): Promise<UserSummary | null> {
+        const url = `${this.baseUrl}/memory/${userId}/summary`
+
+        try {
+            const response = await fetch(url)
+
+            if (response.status === 404) {
+                return null
+            }
+
+            if (!response.ok) {
+                const errorText = await response.text()
+                throw new APIException(`Failed to get user summary: ${response.status} - ${errorText}`, response.status)
+            }
+
+            return await response.json() as UserSummary
+        } catch (error) {
+            if (error instanceof APIException) throw error
+            throw new APIException(`Failed to get user summary: ${error}`)
+        }
+    }
+
+    /**
+     * Clear user's memory.
+     */
+    async clearMemory(userId: string): Promise<{ deleted: number }> {
+        const url = `${this.baseUrl}/memory/${userId}`
+
+        try {
+            const response = await fetch(url, { method: 'DELETE' })
+
+            if (!response.ok) {
+                const errorText = await response.text()
+                throw new APIException(`Failed to clear memory: ${response.status} - ${errorText}`, response.status)
+            }
+
+            return await response.json() as { deleted: number }
+        } catch (error) {
+            if (error instanceof APIException) throw error
+            throw new APIException(`Failed to clear memory: ${error}`)
+        }
+    }
+}