@agentxjs/types 0.0.6 → 0.2.0

package/dist/runtime-internal.js

@@ -0,0 +1 @@
+//# sourceMappingURL=runtime-internal.js.map

package/dist/runtime-internal.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}

package/dist/runtime.cjs

@@ -0,0 +1,19 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/runtime/index.ts
+var runtime_exports = {};
+module.exports = __toCommonJS(runtime_exports);
+//# sourceMappingURL=runtime.cjs.map

package/dist/runtime.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/runtime/index.ts"],"sourcesContent":["/**\n * Runtime Module - Execution environment for AI Agents\n *\n * Runtime manages the complete system: Container lifecycle, Session persistence,\n * Sandbox isolation, and event-driven communication via SystemBus.\n *\n * ## Architecture\n *\n * ```\n * Runtime (extends SystemBus)\n * │\n * ├── Container 1\n * │   ├── Agent A ─── Sandbox A ─── Session A\n * │   └── Agent B ─── Sandbox B ─── Session B\n * │\n * └── Container 2\n *     └── Agent C ─── Sandbox C ─── Session C\n *\n * Environment (LLM connection)\n *     └── Receptor → DriveableEvent → SystemBus → Agent\n * ```\n *\n * ## Two-Domain Relationship\n *\n * ```\n * Runtime Domain                      AgentEngine Domain\n * ─────────────────────────────────────────────────────────\n * Agent (complete entity)             AgentEngine (processing unit)\n *   - lifecycle: stop/resume            - receive/on/react\n *   - LLM + Sandbox + Session           - Driver + MealyMachine + Presenter\n *\n * SystemEvent (full context)          AgentEvent (lightweight)\n *   - source, category, intent          - type, timestamp, data\n *\n * DriveableEvent                      StreamEvent\n *   - from Environment                  - simplified for Engine\n *         │                                    ▲\n *         └──────── Driver converts ───────────┘\n * ```\n *\n * ## Core Components\n *\n * | Component | Responsibility |\n * |-----------|----------------|\n * | Runtime   | Event-driven API, extends SystemBus |\n * | Container | Agent lifecycle, isolation boundary |\n * | Agent     | Complete runtime entity (LLM + Sandbox + Session) |\n * | AgentImage| Snapshot for stop/resume capability |\n * | Session   | Message persistence per Agent |\n * | Sandbox   | Isolated environment (Workdir, MCP tools) |\n *\n * ## Usage\n *\n * ```typescript\n * // Create runtime\n * const runtime = createRuntime({ persistence });\n *\n * // Create container and run agent\n * const containerRes = await runtime.request(\"container_create_request\", {\n *   containerId: \"my-container\"\n * });\n * const agentRes = await runtime.request(\"agent_run_request\", {\n *   containerId: \"my-container\",\n *   config: { name: \"Assistant\", systemPrompt: \"You are helpful.\" }\n * });\n *\n * // Subscribe to events\n * runtime.on(\"text_delta\", (e) => console.log(e.data.text));\n *\n * // Send message\n * await runtime.request(\"agent_receive_request\", {\n *   agentId: agentRes.data.agentId,\n *   content: \"Hello!\"\n * });\n * ```\n *\n * For internal implementation types (Container, LLM, Sandbox, Session, etc.),\n * use `@agentxjs/types/runtime/internal`.\n *\n * @packageDocumentation\n */\n\n// ============================================================================\n// Runtime Entry\n// ============================================================================\n\nexport type { Runtime, Unsubscribe, BusEventHandler } from \"./Runtime\";\n\nexport type { Container } from \"./internal/container/Container\";\n\nexport type { AgentImage, ImageMessage } from \"./AgentImage\";\n\nexport type { LLMProvider, ClaudeLLMConfig, ClaudeLLMProvider } from \"./LLMProvider\";\n\n// ============================================================================\n// Agent Runtime\n// ============================================================================\n\nexport type { Agent } from \"./Agent\";\nexport type { AgentConfig } from \"./AgentConfig\";\nexport type { AgentLifecycle } from \"./AgentLifecycle\";\n\n// ============================================================================\n// Events (Re-exported from @agentxjs/types/event)\n// ============================================================================\n\nexport type {\n  SystemEvent,\n  EventSource,\n  EventIntent,\n  EventCategory,\n  EventContext,\n} from \"~/event/base/SystemEvent\";\n\nexport type {\n  DriveableEvent,\n  DriveableEventType,\n  MessageStartEvent,\n  MessageDeltaEvent,\n  MessageStopEvent,\n  TextContentBlockStartEvent,\n  TextDeltaEvent,\n  TextContentBlockStopEvent,\n  ToolUseContentBlockStartEvent,\n  InputJsonDeltaEvent,\n  ToolUseContentBlockStopEvent,\n  ToolCallEvent,\n  ToolResultEvent,\n  InterruptedEvent,\n  ErrorReceivedEvent,\n} from \"~/event/environment\";\n"],"mappings":";;;;;;;;;;;;;;;;AAAA;AAAA;","names":[]}

package/dist/runtime.d.cts

@@ -0,0 +1,217 @@
+import { S as SystemBus, A as Agent } from './Container-dBDOcjhk.cjs';
+export { a as AgentLifecycle, B as BusEventHandler, C as Container, U as Unsubscribe } from './Container-dBDOcjhk.cjs';
+import { U as UserMessage, A as AssistantMessage, T as ToolCallMessage, a as ToolResultMessage } from './ToolResultMessage-CRKMSf5d.cjs';
+export { b as EventCategory, c as EventContext, a as EventIntent, E as EventSource, S as SystemEvent } from './SystemEvent-CPvvxdMQ.cjs';
+export { D as DriveableEvent, a as DriveableEventType, E as ErrorReceivedEvent, I as InputJsonDeltaEvent, j as InterruptedEvent, b as MessageDeltaEvent, M as MessageStartEvent, c as MessageStopEvent, T as TextContentBlockStartEvent, e as TextContentBlockStopEvent, d as TextDeltaEvent, h as ToolCallEvent, i as ToolResultEvent, f as ToolUseContentBlockStartEvent, g as ToolUseContentBlockStopEvent } from './DriveableEvent-CCMC1h_C.cjs';
+import './CommandEvent-DCdk7lzX.cjs';
+import './ImageRecord-Cn0VcJWk.cjs';
+import './StopReason-D4DthB1h.cjs';
+
+/**
+ * Runtime - Event-driven API for managing Containers and Agents
+ *
+ * All operations are performed through command events.
+ *
+ * @example
+ * ```typescript
+ * const runtime = createRuntime({ persistence });
+ *
+ * // Using request() - convenient async/await
+ * const containerRes = await runtime.request("container_create_request", {
+ *   containerId: "my-container"
+ * });
+ *
+ * const agentRes = await runtime.request("agent_run_request", {
+ *   containerId: "my-container",
+ *   config: { name: "Assistant" }
+ * });
+ *
+ * // Using emitCommand/onCommand - fine-grained control
+ * runtime.emitCommand("agent_receive_request", {
+ *   requestId: "req_123",
+ *   agentId: agentRes.data.agentId,
+ *   content: "Hello!"
+ * });
+ *
+ * // Subscribe to stream events
+ * runtime.on("text_delta", (e) => console.log(e.data.text));
+ *
+ * // Cleanup
+ * await runtime.dispose();
+ * ```
+ */
+
+/**
+ * Runtime interface - event-driven API for AI Agents
+ *
+ * Extends SystemBus to provide all event operations.
+ */
+interface Runtime extends SystemBus {
+    /**
+     * Dispose runtime and all resources
+     */
+    dispose(): Promise<void>;
+}
+
+/**
+ * AgentImage - Agent runtime snapshot (persisted state)
+ *
+ * AgentImage is a complete snapshot of an Agent's state at a point in time.
+ * It contains all information needed to fully restore an Agent:
+ * - Runtime context (containerId, agentId)
+ * - Configuration (name, systemPrompt)
+ * - Conversation history (messages)
+ *
+ * AgentImage is an object with behavior - it can restore itself to a running Agent.
+ *
+ * Workflow:
+ * ```
+ * Agent → runtime.images.snapshot(agent) → AgentImage
+ *                                              ↓
+ *                                         image.resume()
+ *                                              ↓
+ *                                         New Agent (restored)
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Create and use agent
+ * const agent = await runtime.agents.run(containerId, config);
+ * await agent.receive("Hello!");
+ *
+ * // Snapshot
+ * const image = await runtime.images.snapshot(agent);
+ *
+ * // Later: restore from image
+ * const restoredAgent = await image.resume();
+ * ```
+ */
+
+/**
+ * Union type of all message types that can be stored in an Image
+ */
+type ImageMessage = UserMessage | AssistantMessage | ToolCallMessage | ToolResultMessage;
+/**
+ * AgentImage - Complete snapshot of Agent state with behavior
+ */
+interface AgentImage {
+    /**
+     * Unique image identifier
+     * Pattern: `img_${nanoid()}`
+     */
+    readonly imageId: string;
+    /**
+     * Container ID where this agent was running
+     */
+    readonly containerId: string;
+    /**
+     * Original agent ID (for traceability)
+     */
+    readonly agentId: string;
+    /**
+     * Agent name
+     */
+    readonly name: string;
+    /**
+     * Agent description (optional)
+     */
+    readonly description?: string;
+    /**
+     * System prompt - controls agent behavior
+     */
+    readonly systemPrompt?: string;
+    /**
+     * Conversation history snapshot
+     */
+    readonly messages: ImageMessage[];
+    /**
+     * Parent image ID (if this image was derived from another)
+     */
+    readonly parentImageId?: string;
+    /**
+     * When this image was created (Unix milliseconds)
+     */
+    readonly createdAt: number;
+    /**
+     * Resume an agent from this image
+     *
+     * Creates a new Agent instance with the saved configuration
+     * and conversation history restored.
+     *
+     * @throws Error if container not found
+     * @returns New Agent instance
+     */
+    resume(): Promise<Agent>;
+}
+
+/**
+ * LLMProvider - Large Language Model Supply Service
+ *
+ * Provides LLM configuration at Runtime level.
+ * All Agents in the Runtime share the same LLMProvider.
+ */
+/**
+ * LLMProvider - Large Language Model supply service
+ *
+ * @typeParam TSupply - Supply type (config, client, token, etc.)
+ */
+interface LLMProvider<TSupply = unknown> {
+    /**
+     * Provider identifier (e.g., "claude", "openai")
+     */
+    readonly name: string;
+    /**
+     * Provide LLM configuration
+     */
+    provide(): TSupply;
+}
+/**
+ * ClaudeLLMConfig - Configuration for Claude LLM
+ */
+interface ClaudeLLMConfig {
+    /**
+     * Anthropic API key
+     */
+    apiKey: string;
+    /**
+     * API base URL (optional, for custom endpoints)
+     */
+    baseUrl?: string;
+    /**
+     * Model name (e.g., "claude-sonnet-4-20250514")
+     */
+    model?: string;
+}
+/**
+ * Type alias for Claude LLM Provider
+ */
+type ClaudeLLMProvider = LLMProvider<ClaudeLLMConfig>;
+
+/**
+ * AgentConfig - Runtime configuration for Agent instance
+ *
+ * Contains the configuration needed to run an Agent.
+ * Copied from AgentDefinition when Agent is created.
+ *
+ * Separation of concerns:
+ * - AgentDefinition (application layer) = static template
+ * - AgentConfig (runtime layer) = runtime configuration
+ *
+ * This keeps runtime layer independent of application layer.
+ */
+interface AgentConfig {
+    /**
+     * Agent name
+     */
+    name: string;
+    /**
+     * Agent description (optional)
+     */
+    description?: string;
+    /**
+     * System prompt - controls agent behavior
+     */
+    systemPrompt?: string;
+}
+
+export { Agent, type AgentConfig, type AgentImage, type ClaudeLLMConfig, type ClaudeLLMProvider, type ImageMessage, type LLMProvider, type Runtime };

package/dist/runtime.d.ts

@@ -0,0 +1,217 @@
+import { S as SystemBus, A as Agent } from './Container-DR-1g44i.js';
+export { a as AgentLifecycle, B as BusEventHandler, C as Container, U as Unsubscribe } from './Container-DR-1g44i.js';
+import { U as UserMessage, A as AssistantMessage, T as ToolCallMessage, a as ToolResultMessage } from './ToolResultMessage-CDG2L7Zv.js';
+export { b as EventCategory, c as EventContext, a as EventIntent, E as EventSource, S as SystemEvent } from './SystemEvent-CPvvxdMQ.js';
+export { D as DriveableEvent, a as DriveableEventType, E as ErrorReceivedEvent, I as InputJsonDeltaEvent, j as InterruptedEvent, b as MessageDeltaEvent, M as MessageStartEvent, c as MessageStopEvent, T as TextContentBlockStartEvent, e as TextContentBlockStopEvent, d as TextDeltaEvent, h as ToolCallEvent, i as ToolResultEvent, f as ToolUseContentBlockStartEvent, g as ToolUseContentBlockStopEvent } from './DriveableEvent-Bj7nn-Uk.js';
+import './CommandEvent-CbXzPolX.js';
+import './ImageRecord-Cn0VcJWk.js';
+import './StopReason-D4DthB1h.js';
+
+/**
+ * Runtime - Event-driven API for managing Containers and Agents
+ *
+ * All operations are performed through command events.
+ *
+ * @example
+ * ```typescript
+ * const runtime = createRuntime({ persistence });
+ *
+ * // Using request() - convenient async/await
+ * const containerRes = await runtime.request("container_create_request", {
+ *   containerId: "my-container"
+ * });
+ *
+ * const agentRes = await runtime.request("agent_run_request", {
+ *   containerId: "my-container",
+ *   config: { name: "Assistant" }
+ * });
+ *
+ * // Using emitCommand/onCommand - fine-grained control
+ * runtime.emitCommand("agent_receive_request", {
+ *   requestId: "req_123",
+ *   agentId: agentRes.data.agentId,
+ *   content: "Hello!"
+ * });
+ *
+ * // Subscribe to stream events
+ * runtime.on("text_delta", (e) => console.log(e.data.text));
+ *
+ * // Cleanup
+ * await runtime.dispose();
+ * ```
+ */
+
+/**
+ * Runtime interface - event-driven API for AI Agents
+ *
+ * Extends SystemBus to provide all event operations.
+ */
+interface Runtime extends SystemBus {
+    /**
+     * Dispose runtime and all resources
+     */
+    dispose(): Promise<void>;
+}
+
+/**
+ * AgentImage - Agent runtime snapshot (persisted state)
+ *
+ * AgentImage is a complete snapshot of an Agent's state at a point in time.
+ * It contains all information needed to fully restore an Agent:
+ * - Runtime context (containerId, agentId)
+ * - Configuration (name, systemPrompt)
+ * - Conversation history (messages)
+ *
+ * AgentImage is an object with behavior - it can restore itself to a running Agent.
+ *
+ * Workflow:
+ * ```
+ * Agent → runtime.images.snapshot(agent) → AgentImage
+ *                                              ↓
+ *                                         image.resume()
+ *                                              ↓
+ *                                         New Agent (restored)
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Create and use agent
+ * const agent = await runtime.agents.run(containerId, config);
+ * await agent.receive("Hello!");
+ *
+ * // Snapshot
+ * const image = await runtime.images.snapshot(agent);
+ *
+ * // Later: restore from image
+ * const restoredAgent = await image.resume();
+ * ```
+ */
+
+/**
+ * Union type of all message types that can be stored in an Image
+ */
+type ImageMessage = UserMessage | AssistantMessage | ToolCallMessage | ToolResultMessage;
+/**
+ * AgentImage - Complete snapshot of Agent state with behavior
+ */
+interface AgentImage {
+    /**
+     * Unique image identifier
+     * Pattern: `img_${nanoid()}`
+     */
+    readonly imageId: string;
+    /**
+     * Container ID where this agent was running
+     */
+    readonly containerId: string;
+    /**
+     * Original agent ID (for traceability)
+     */
+    readonly agentId: string;
+    /**
+     * Agent name
+     */
+    readonly name: string;
+    /**
+     * Agent description (optional)
+     */
+    readonly description?: string;
+    /**
+     * System prompt - controls agent behavior
+     */
+    readonly systemPrompt?: string;
+    /**
+     * Conversation history snapshot
+     */
+    readonly messages: ImageMessage[];
+    /**
+     * Parent image ID (if this image was derived from another)
+     */
+    readonly parentImageId?: string;
+    /**
+     * When this image was created (Unix milliseconds)
+     */
+    readonly createdAt: number;
+    /**
+     * Resume an agent from this image
+     *
+     * Creates a new Agent instance with the saved configuration
+     * and conversation history restored.
+     *
+     * @throws Error if container not found
+     * @returns New Agent instance
+     */
+    resume(): Promise<Agent>;
+}
+
+/**
+ * LLMProvider - Large Language Model Supply Service
+ *
+ * Provides LLM configuration at Runtime level.
+ * All Agents in the Runtime share the same LLMProvider.
+ */
+/**
+ * LLMProvider - Large Language Model supply service
+ *
+ * @typeParam TSupply - Supply type (config, client, token, etc.)
+ */
+interface LLMProvider<TSupply = unknown> {
+    /**
+     * Provider identifier (e.g., "claude", "openai")
+     */
+    readonly name: string;
+    /**
+     * Provide LLM configuration
+     */
+    provide(): TSupply;
+}
+/**
+ * ClaudeLLMConfig - Configuration for Claude LLM
+ */
+interface ClaudeLLMConfig {
+    /**
+     * Anthropic API key
+     */
+    apiKey: string;
+    /**
+     * API base URL (optional, for custom endpoints)
+     */
+    baseUrl?: string;
+    /**
+     * Model name (e.g., "claude-sonnet-4-20250514")
+     */
+    model?: string;
+}
+/**
+ * Type alias for Claude LLM Provider
+ */
+type ClaudeLLMProvider = LLMProvider<ClaudeLLMConfig>;
+
+/**
+ * AgentConfig - Runtime configuration for Agent instance
+ *
+ * Contains the configuration needed to run an Agent.
+ * Copied from AgentDefinition when Agent is created.
+ *
+ * Separation of concerns:
+ * - AgentDefinition (application layer) = static template
+ * - AgentConfig (runtime layer) = runtime configuration
+ *
+ * This keeps runtime layer independent of application layer.
+ */
+interface AgentConfig {
+    /**
+     * Agent name
+     */
+    name: string;
+    /**
+     * Agent description (optional)
+     */
+    description?: string;
+    /**
+     * System prompt - controls agent behavior
+     */
+    systemPrompt?: string;
+}
+
+export { Agent, type AgentConfig, type AgentImage, type ClaudeLLMConfig, type ClaudeLLMProvider, type ImageMessage, type LLMProvider, type Runtime };

package/dist/runtime.js

@@ -0,0 +1 @@
+//# sourceMappingURL=runtime.js.map

package/dist/runtime.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agentxjs/types",
-  "version": "0.0.6",
+  "version": "0.2.0",
   "description": "Type definitions for AgentX ecosystem",
   "license": "MIT",
   "repository": {
@@ -17,11 +17,89 @@
       "types": "./dist/index.d.ts",
       "import": "./dist/index.js",
       "require": "./dist/index.cjs"
+    },
+    "./agent": {
+      "types": "./dist/agent.d.ts",
+      "import": "./dist/agent.js",
+      "require": "./dist/agent.cjs"
+    },
+    "./agent/internal": {
+      "types": "./dist/agent-internal.d.ts",
+      "import": "./dist/agent-internal.js",
+      "require": "./dist/agent-internal.cjs"
+    },
+    "./runtime": {
+      "types": "./dist/runtime.d.ts",
+      "import": "./dist/runtime.js",
+      "require": "./dist/runtime.cjs"
+    },
+    "./runtime/internal": {
+      "types": "./dist/runtime-internal.d.ts",
+      "import": "./dist/runtime-internal.js",
+      "require": "./dist/runtime-internal.cjs"
+    },
+    "./event": {
+      "types": "./dist/event.d.ts",
+      "import": "./dist/event.js",
+      "require": "./dist/event.cjs"
+    },
+    "./common": {
+      "types": "./dist/common.d.ts",
+      "import": "./dist/common.js",
+      "require": "./dist/common.cjs"
+    },
+    "./agentx": {
+      "types": "./dist/agentx.d.ts",
+      "import": "./dist/agentx.js",
+      "require": "./dist/agentx.cjs"
+    },
+    "./network": {
+      "types": "./dist/network.d.ts",
+      "import": "./dist/network.js",
+      "require": "./dist/network.cjs"
+    }
+  },
+  "typesVersions": {
+    "*": {
+      "agent": [
+        "./dist/agent.d.ts"
+      ],
+      "agent/internal": [
+        "./dist/agent-internal.d.ts"
+      ],
+      "runtime": [
+        "./dist/runtime.d.ts"
+      ],
+      "runtime/internal": [
+        "./dist/runtime-internal.d.ts"
+      ],
+      "event": [
+        "./dist/event.d.ts"
+      ],
+      "common": [
+        "./dist/common.d.ts"
+      ],
+      "agentx": [
+        "./dist/agentx.d.ts"
+      ],
+      "network": [
+        "./dist/network.d.ts"
+      ]
     }
   },
   "files": [
     "dist"
   ],
+  "scripts": {
+    "build": "tsup",
+    "clean": "rm -rf dist",
+    "lint": "eslint .",
+    "typecheck": "tsc --noEmit",
+    "dev": "tsup --watch",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:update": "vitest run --update"
+  },
   "keywords": [
     "agentx",
     "agent",
@@ -32,16 +110,10 @@
   "author": "Deepractice AI",
   "devDependencies": {
     "tsup": "^8.0.1",
-    "typescript": "^5.3.3"
+    "typescript": "^5.3.3",
+    "vitest": "^3.2.4"
   },
   "publishConfig": {
     "access": "public"
-  },
-  "scripts": {
-    "build": "tsup",
-    "clean": "rm -rf dist",
-    "lint": "eslint .",
-    "typecheck": "tsc --noEmit",
-    "dev": "tsup --watch"
   }
-}
+}

package/LICENSE

@@ -1,21 +0,0 @@
-MIT License
-
-Copyright (c) 2025 Deepractice
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.