march-ai-sdk 0.3.0

package/dist/extensions/vercel-ai.js

@@ -0,0 +1,177 @@
+// src/exceptions.ts
+var MarchAgentError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "MarchAgentError";
+    Error.captureStackTrace?.(this, this.constructor);
+  }
+};
+var APIException = class extends MarchAgentError {
+  statusCode;
+  constructor(message, statusCode) {
+    super(message);
+    this.name = "APIException";
+    this.statusCode = statusCode;
+  }
+};
+
+// src/agent-state-client.ts
+var AgentStateClient = class {
+  baseUrl;
+  constructor(baseUrl) {
+    this.baseUrl = baseUrl.replace(/\/$/, "");
+  }
+  /**
+   * Store or update agent state.
+   */
+  async put(conversationId, namespace, state) {
+    const url = `${this.baseUrl}/agent-state/${conversationId}`;
+    const payload = {
+      namespace,
+      state
+    };
+    try {
+      const response = await fetch(url, {
+        method: "PUT",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify(payload)
+      });
+      if (!response.ok) {
+        const errorText = await response.text();
+        throw new APIException(`Failed to store agent state: ${response.status} - ${errorText}`, response.status);
+      }
+      return await response.json();
+    } catch (error) {
+      if (error instanceof APIException) throw error;
+      throw new APIException(`Failed to store agent state: ${error}`);
+    }
+  }
+  /**
+   * Get agent state.
+   */
+  async get(conversationId, namespace) {
+    const url = new URL(`${this.baseUrl}/agent-state/${conversationId}`);
+    url.searchParams.set("namespace", namespace);
+    try {
+      const response = await fetch(url.toString());
+      if (response.status === 404) {
+        return null;
+      }
+      if (!response.ok) {
+        const errorText = await response.text();
+        throw new APIException(`Failed to get agent state: ${response.status} - ${errorText}`, response.status);
+      }
+      return await response.json();
+    } catch (error) {
+      if (error instanceof APIException) throw error;
+      throw new APIException(`Failed to get agent state: ${error}`);
+    }
+  }
+  /**
+   * Delete agent state.
+   */
+  async delete(conversationId, namespace) {
+    const url = new URL(`${this.baseUrl}/agent-state/${conversationId}`);
+    if (namespace) {
+      url.searchParams.set("namespace", namespace);
+    }
+    try {
+      const response = await fetch(url.toString(), { method: "DELETE" });
+      if (!response.ok) {
+        const errorText = await response.text();
+        throw new APIException(`Failed to delete agent state: ${response.status} - ${errorText}`, response.status);
+      }
+      return await response.json();
+    } catch (error) {
+      if (error instanceof APIException) throw error;
+      throw new APIException(`Failed to delete agent state: ${error}`);
+    }
+  }
+};
+
+// src/extensions/vercel-ai.ts
+var VercelAIMessageStore = class _VercelAIMessageStore {
+  static NAMESPACE = "vercel_ai";
+  client;
+  constructor(app) {
+    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) {
+    const result = await this.client.get(conversationId, _VercelAIMessageStore.NAMESPACE);
+    if (!result) {
+      return [];
+    }
+    const state = result.state ?? {};
+    const messages = state.messages;
+    if (!Array.isArray(messages)) {
+      return [];
+    }
+    return messages.filter(this.isValidMessage);
+  }
+  /**
+   * 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, messages) {
+    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) {
+    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, newMessages) {
+    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, count) {
+    const history = await this.load(conversationId);
+    return history.slice(-count);
+  }
+  /**
+   * Validate that an object is a valid message.
+   */
+  isValidMessage(msg) {
+    if (typeof msg !== "object" || msg === null) {
+      return false;
+    }
+    const m = msg;
+    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.
+   */
+  serializeMessage(msg) {
+    return { ...msg };
+  }
+};
+
+export { VercelAIMessageStore };
+//# sourceMappingURL=vercel-ai.js.map
+//# sourceMappingURL=vercel-ai.js.map

package/dist/extensions/vercel-ai.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/exceptions.ts","../../src/agent-state-client.ts","../../src/extensions/vercel-ai.ts"],"names":[],"mappings":"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","file":"vercel-ai.js","sourcesContent":["/**\n * March Agent SDK - Custom Errors\n * Port of Python march_agent/exceptions.py\n */\n\n/**\n * Base error class for March Agent SDK\n */\nexport class MarchAgentError extends Error {\n    constructor(message: string) {\n        super(message)\n        this.name = 'MarchAgentError'\n        Error.captureStackTrace?.(this, this.constructor)\n    }\n}\n\n/**\n * Error during agent registration with AI Inventory\n */\nexport class RegistrationError extends MarchAgentError {\n    constructor(message: string) {\n        super(message)\n        this.name = 'RegistrationError'\n    }\n}\n\n/**\n * Error during Kafka operations (produce/consume)\n */\nexport class KafkaError extends MarchAgentError {\n    constructor(message: string) {\n        super(message)\n        this.name = 'KafkaError'\n    }\n}\n\n/**\n * Error in SDK configuration\n */\nexport class ConfigurationError extends MarchAgentError {\n    constructor(message: string) {\n        super(message)\n        this.name = 'ConfigurationError'\n    }\n}\n\n/**\n * Error from API calls to backend services\n */\nexport class APIException extends MarchAgentError {\n    statusCode?: number\n\n    constructor(message: string, statusCode?: number) {\n        super(message)\n        this.name = 'APIException'\n        this.statusCode = statusCode\n    }\n}\n\n/**\n * Error during heartbeat operations\n */\nexport class HeartbeatError extends MarchAgentError {\n    constructor(message: string) {\n        super(message)\n        this.name = 'HeartbeatError'\n    }\n}\n\n/**\n * Error during gRPC connection/communication\n */\nexport class GatewayError extends MarchAgentError {\n    constructor(message: string) {\n        super(message)\n        this.name = 'GatewayError'\n    }\n}\n","/**\n * March Agent SDK - Agent State Client\n * Port of Python march_agent/agent_state_client.py\n */\n\nimport { APIException } from './exceptions.js'\n\nexport interface AgentStateResponse {\n    conversationId: string\n    namespace: string\n    state: Record<string, unknown>\n    createdAt?: string\n    updatedAt?: string\n}\n\n/**\n * Async HTTP client for agent-state API.\n * Used for storing framework-specific state (e.g., Pydantic AI messages).\n */\nexport class AgentStateClient {\n    private readonly baseUrl: string\n\n    constructor(baseUrl: string) {\n        this.baseUrl = baseUrl.replace(/\\/$/, '')\n    }\n\n    /**\n     * Store or update agent state.\n     */\n    async put(\n        conversationId: string,\n        namespace: string,\n        state: Record<string, unknown>\n    ): Promise<{ conversationId: string; namespace: string; created: boolean }> {\n        const url = `${this.baseUrl}/agent-state/${conversationId}`\n        const payload = {\n            namespace,\n            state,\n        }\n\n        try {\n            const response = await fetch(url, {\n                method: 'PUT',\n                headers: { 'Content-Type': 'application/json' },\n                body: JSON.stringify(payload),\n            })\n\n            if (!response.ok) {\n                const errorText = await response.text()\n                throw new APIException(`Failed to store agent state: ${response.status} - ${errorText}`, response.status)\n            }\n\n            return await response.json() as { conversationId: string; namespace: string; created: boolean }\n        } catch (error) {\n            if (error instanceof APIException) throw error\n            throw new APIException(`Failed to store agent state: ${error}`)\n        }\n    }\n\n    /**\n     * Get agent state.\n     */\n    async get(\n        conversationId: string,\n        namespace: string\n    ): Promise<AgentStateResponse | null> {\n        const url = new URL(`${this.baseUrl}/agent-state/${conversationId}`)\n        url.searchParams.set('namespace', namespace)\n\n        try {\n            const response = await fetch(url.toString())\n\n            if (response.status === 404) {\n                return null\n            }\n\n            if (!response.ok) {\n                const errorText = await response.text()\n                throw new APIException(`Failed to get agent state: ${response.status} - ${errorText}`, response.status)\n            }\n\n            return await response.json() as AgentStateResponse\n        } catch (error) {\n            if (error instanceof APIException) throw error\n            throw new APIException(`Failed to get agent state: ${error}`)\n        }\n    }\n\n    /**\n     * Delete agent state.\n     */\n    async delete(\n        conversationId: string,\n        namespace?: string\n    ): Promise<{ conversationId: string; namespace?: string; deleted: number }> {\n        const url = new URL(`${this.baseUrl}/agent-state/${conversationId}`)\n        if (namespace) {\n            url.searchParams.set('namespace', namespace)\n        }\n\n        try {\n            const response = await fetch(url.toString(), { method: 'DELETE' })\n\n            if (!response.ok) {\n                const errorText = await response.text()\n                throw new APIException(`Failed to delete agent state: ${response.status} - ${errorText}`, response.status)\n            }\n\n            return await response.json() as { conversationId: string; namespace?: string; deleted: number }\n        } catch (error) {\n            if (error instanceof APIException) throw error\n            throw new APIException(`Failed to delete agent state: ${error}`)\n        }\n    }\n}\n","/**\n * March Agent SDK - Vercel AI SDK Extension\n * \n * VercelAIMessageStore for persistent message history with Vercel AI SDK.\n * \n * @packageDocumentation\n */\n\nimport type { MarchAgentApp } from '../app.js'\nimport { AgentStateClient } from '../agent-state-client.js'\n\n// Type definitions compatible with Vercel AI SDK's CoreMessage\ninterface CoreMessage {\n    role: 'system' | 'user' | 'assistant' | 'tool'\n    content: string | Array<{ type: string;[key: string]: unknown }>\n    [key: string]: unknown\n}\n\n/**\n * Persistent message store for Vercel AI SDK.\n * \n * Stores and retrieves AI SDK message history using the agent-state API.\n * Messages are serialized as JSON for full fidelity.\n * \n * @example\n * ```typescript\n * import { MarchAgentApp } from 'march-ai-sdk'\n * import { VercelAIMessageStore } from 'march-ai-sdk/extensions/vercel-ai'\n * import { streamText } from 'ai'\n * import { openai } from '@ai-sdk/openai'\n * \n * const app = new MarchAgentApp({\n *   gatewayUrl: 'agent-gateway:8080',\n *   apiKey: 'your-key',\n * })\n * \n * const store = new VercelAIMessageStore(app)\n * const agent = app.registerMe({ ... })\n * \n * agent.onMessage(async (message, sender) => {\n *   // Load message history\n *   const history = await store.load(message.conversationId)\n *   \n *   // Add user message\n *   const messages: CoreMessage[] = [\n *     ...history,\n *     { role: 'user', content: message.content }\n *   ]\n *   \n *   // Stream response\n *   const streamer = agent.streamer(message)\n *   \n *   const result = await streamText({\n *     model: openai('gpt-4o'),\n *     messages,\n *     onChunk: ({ chunk }) => {\n *       if (chunk.type === 'text-delta') {\n *         streamer.stream(chunk.textDelta)\n *       }\n *     }\n *   })\n *   \n *   await streamer.finish()\n *   \n *   // Save updated history\n *   await store.save(message.conversationId, [\n *     ...messages,\n *     { role: 'assistant', content: result.text }\n *   ])\n * })\n * \n * app.run()\n * ```\n */\nexport class VercelAIMessageStore {\n    private static readonly NAMESPACE = 'vercel_ai'\n    private readonly client: AgentStateClient\n\n    constructor(app: MarchAgentApp) {\n        this.client = new AgentStateClient(app.gatewayClient.conversationStoreUrl)\n    }\n\n    /**\n     * Load message history for a conversation.\n     * \n     * @param conversationId - The conversation ID to load history for\n     * @returns Array of CoreMessage objects (empty array if no history)\n     */\n    async load(conversationId: string): Promise<CoreMessage[]> {\n        const result = await this.client.get(conversationId, VercelAIMessageStore.NAMESPACE)\n\n        if (!result) {\n            return []\n        }\n\n        const state = result.state ?? {}\n        const messages = state.messages as unknown[]\n\n        if (!Array.isArray(messages)) {\n            return []\n        }\n\n        // Validate and return messages\n        return messages.filter(this.isValidMessage) as CoreMessage[]\n    }\n\n    /**\n     * Save message history for a conversation.\n     * \n     * @param conversationId - The conversation ID to save history for\n     * @param messages - Array of CoreMessage objects to save\n     */\n    async save(conversationId: string, messages: CoreMessage[]): Promise<void> {\n        await this.client.put(conversationId, VercelAIMessageStore.NAMESPACE, {\n            messages: messages.map(this.serializeMessage),\n        })\n    }\n\n    /**\n     * Clear message history for a conversation.\n     * \n     * @param conversationId - The conversation ID to clear history for\n     */\n    async clear(conversationId: string): Promise<void> {\n        await this.client.delete(conversationId, VercelAIMessageStore.NAMESPACE)\n    }\n\n    /**\n     * Append messages to existing history.\n     * \n     * @param conversationId - The conversation ID\n     * @param newMessages - Messages to append\n     */\n    async append(conversationId: string, newMessages: CoreMessage[]): Promise<void> {\n        const existing = await this.load(conversationId)\n        await this.save(conversationId, [...existing, ...newMessages])\n    }\n\n    /**\n     * Get the last N messages from history.\n     * \n     * @param conversationId - The conversation ID\n     * @param count - Number of messages to retrieve\n     */\n    async getLastMessages(conversationId: string, count: number): Promise<CoreMessage[]> {\n        const history = await this.load(conversationId)\n        return history.slice(-count)\n    }\n\n    /**\n     * Validate that an object is a valid message.\n     */\n    private isValidMessage(msg: unknown): msg is CoreMessage {\n        if (typeof msg !== 'object' || msg === null) {\n            return false\n        }\n\n        const m = msg as Record<string, unknown>\n        const validRoles = ['system', 'user', 'assistant', 'tool']\n\n        return (\n            typeof m.role === 'string' &&\n            validRoles.includes(m.role) &&\n            (typeof m.content === 'string' || Array.isArray(m.content))\n        )\n    }\n\n    /**\n     * Serialize a message for storage.\n     */\n    private serializeMessage(msg: CoreMessage): Record<string, unknown> {\n        // Return a plain object copy\n        return { ...msg }\n    }\n}\n\nexport type { CoreMessage }\n"]}

package/dist/index.d.ts

@@ -0,0 +1,260 @@
+import { G as GatewayClient } from './app-C_umwZXh.js';
+export { A as Agent, a as AgentRegistrationData, b as AppOptions, c as Artifact, d as ArtifactInput, e as ArtifactType, f as AttachmentClient, g as AttachmentInfo, C as Conversation, h as ConversationClient, i as ConversationData, j as ConversationMessage, k as GetMessagesOptions, K as KafkaHeaders, l as KafkaMessage, M as MarchAgentApp, m as Memory, n as MemoryClient, o as MemoryMessage, p as MemorySearchResult, q as Message, r as MessageHandler, P as ProduceAck, R as RegisterOptions, S as SenderFilter, s as SenderFilterOptions, t as StreamOptions, u as Streamer, v as StreamerOptions, U as UserSummary, w as createAttachmentInfo, x as toArtifact } from './app-C_umwZXh.js';
+import 'zod';
+
+/**
+ * March Agent SDK - Checkpoint Client
+ * Port of Python march_agent/checkpoint_client.py
+ */
+interface CheckpointConfig {
+    configurable: {
+        thread_id: string;
+        checkpoint_ns?: string;
+        checkpoint_id?: string;
+    };
+}
+interface CheckpointData {
+    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: CheckpointConfig;
+    checkpoint: CheckpointData;
+    metadata: CheckpointMetadata;
+    parent_config?: CheckpointConfig;
+    pending_writes?: unknown[];
+}
+interface CheckpointListOptions {
+    threadId?: string;
+    checkpointNs?: string;
+    before?: string;
+    limit?: number;
+}
+/**
+ * Async HTTP client for checkpoint-store API.
+ * Used by LangGraph integration for persisting graph state.
+ */
+declare class CheckpointClient {
+    private readonly baseUrl;
+    constructor(baseUrl: string);
+    /**
+     * Store a checkpoint.
+     */
+    put(config: CheckpointConfig, checkpoint: CheckpointData, metadata: CheckpointMetadata, newVersions?: Record<string, unknown>): Promise<{
+        config: CheckpointConfig;
+    }>;
+    /**
+     * Get a checkpoint tuple.
+     */
+    getTuple(threadId: string, checkpointNs?: string, checkpointId?: string): Promise<CheckpointTuple | null>;
+    /**
+     * List checkpoints.
+     */
+    list(options?: CheckpointListOptions): Promise<CheckpointTuple[]>;
+    /**
+     * Delete all checkpoints for a thread.
+     */
+    deleteThread(threadId: string): Promise<{
+        thread_id: string;
+        deleted: number;
+    }>;
+}
+
+/**
+ * March Agent SDK - Agent State Client
+ * Port of Python march_agent/agent_state_client.py
+ */
+interface AgentStateResponse {
+    conversationId: string;
+    namespace: string;
+    state: Record<string, unknown>;
+    createdAt?: string;
+    updatedAt?: string;
+}
+/**
+ * Async HTTP client for agent-state API.
+ * Used for storing framework-specific state (e.g., Pydantic AI messages).
+ */
+declare class AgentStateClient {
+    private readonly baseUrl;
+    constructor(baseUrl: string);
+    /**
+     * Store or update agent state.
+     */
+    put(conversationId: string, namespace: string, state: Record<string, unknown>): Promise<{
+        conversationId: string;
+        namespace: string;
+        created: boolean;
+    }>;
+    /**
+     * Get agent state.
+     */
+    get(conversationId: string, namespace: string): Promise<AgentStateResponse | null>;
+    /**
+     * Delete agent state.
+     */
+    delete(conversationId: string, namespace?: string): Promise<{
+        conversationId: string;
+        namespace?: string;
+        deleted: number;
+    }>;
+}
+
+/**
+ * March Agent SDK - Heartbeat Manager
+ * Port of Python march_agent/heartbeat.py
+ */
+
+/**
+ * Manages periodic heartbeats to keep the agent status active.
+ * Sends heartbeats via HTTP to the AI Inventory service.
+ */
+declare class HeartbeatManager {
+    private readonly gatewayClient;
+    private readonly agentName;
+    private readonly intervalMs;
+    private timer?;
+    private running;
+    constructor(gatewayClient: GatewayClient, agentName: string, intervalSeconds?: number);
+    /**
+     * Start sending heartbeats.
+     */
+    start(): void;
+    /**
+     * Stop sending heartbeats.
+     */
+    stop(): void;
+    /**
+     * Send a single heartbeat via HTTP to AI Inventory.
+     */
+    private sendHeartbeat;
+    /**
+     * Check if heartbeat is running.
+     */
+    isRunning(): boolean;
+}
+
+/**
+ * March Agent SDK - API Paths Configuration
+ *
+ * Centralized configuration for all API endpoint paths.
+ * This allows easy configuration if API versions or paths change.
+ */
+/**
+ * API paths for AI Inventory service.
+ */
+declare const AI_INVENTORY_PATHS: {
+    /** Register a new agent */
+    readonly AGENT_REGISTER: "/api/v1/agents/register";
+    /** Send heartbeat */
+    readonly HEALTH_HEARTBEAT: "/api/v1/health/heartbeat";
+};
+/**
+ * API paths for Conversation Store service.
+ * Note: These paths don't have /api/v1/ prefix.
+ */
+declare const CONVERSATION_STORE_PATHS: {
+    /** Get/update conversation by ID */
+    readonly CONVERSATION: (conversationId: string) => string;
+    /** Get messages for a conversation */
+    readonly CONVERSATION_MESSAGES: (conversationId: string) => string;
+    /** Checkpoints base path */
+    readonly CHECKPOINTS: "/checkpoints/";
+    /** Checkpoint by thread ID */
+    readonly CHECKPOINT_THREAD: (threadId: string) => string;
+    /** Agent state by conversation ID */
+    readonly AGENT_STATE: (conversationId: string) => string;
+};
+/**
+ * API paths for AI Memory service.
+ * Note: These paths don't have /api/v1/ prefix.
+ */
+declare const MEMORY_PATHS: {
+    /** User memory base */
+    readonly USER_MEMORY: (userId: string) => string;
+    /** Add messages to memory */
+    readonly USER_MESSAGES: (userId: string) => string;
+    /** Search user memory */
+    readonly USER_SEARCH: (userId: string) => string;
+    /** Get user summary */
+    readonly USER_SUMMARY: (userId: string) => string;
+};
+/**
+ * Service names for gateway proxy routing.
+ */
+declare const SERVICES: {
+    readonly AI_INVENTORY: "ai-inventory";
+    readonly CONVERSATION_STORE: "conversation-store";
+    readonly AI_MEMORY: "ai-memory";
+    readonly ATTACHMENT: "attachment";
+};
+type ServiceName = typeof SERVICES[keyof typeof SERVICES];
+
+/**
+ * March Agent SDK - Custom Errors
+ * Port of Python march_agent/exceptions.py
+ */
+/**
+ * Base error class for March Agent SDK
+ */
+declare class MarchAgentError extends Error {
+    constructor(message: string);
+}
+/**
+ * Error during agent registration with AI Inventory
+ */
+declare class RegistrationError extends MarchAgentError {
+    constructor(message: string);
+}
+/**
+ * Error during Kafka operations (produce/consume)
+ */
+declare class KafkaError extends MarchAgentError {
+    constructor(message: string);
+}
+/**
+ * Error in SDK configuration
+ */
+declare class ConfigurationError extends MarchAgentError {
+    constructor(message: string);
+}
+/**
+ * Error from API calls to backend services
+ */
+declare class APIException extends MarchAgentError {
+    statusCode?: number;
+    constructor(message: string, statusCode?: number);
+}
+/**
+ * Error during heartbeat operations
+ */
+declare class HeartbeatError extends MarchAgentError {
+    constructor(message: string);
+}
+/**
+ * Error during gRPC connection/communication
+ */
+declare class GatewayError extends MarchAgentError {
+    constructor(message: string);
+}
+
+/**
+ * March Agent SDK - TypeScript framework for building AI agents
+ *
+ * @packageDocumentation
+ */
+
+declare const VERSION = "0.3.0";
+
+export { AI_INVENTORY_PATHS, APIException, AgentStateClient, type AgentStateResponse, CONVERSATION_STORE_PATHS, CheckpointClient, type CheckpointConfig, type CheckpointData, type CheckpointMetadata, type CheckpointTuple, ConfigurationError, GatewayClient, GatewayError, HeartbeatError, HeartbeatManager, KafkaError, MEMORY_PATHS, MarchAgentError, RegistrationError, SERVICES, type ServiceName, VERSION };