@agentxjs/core 1.9.5-dev → 1.9.6-dev

package/dist/index.js

@@ -0,0 +1,67 @@
+import {
+  AgentStateMachine,
+  MealyMachine,
+  agentProcessor,
+  createAgent,
+  createInitialAgentEngineState,
+  createMealyMachine
+} from "./chunk-AT5P47YA.js";
+import {
+  MemoryStore,
+  chainProcessors,
+  combineInitialStates,
+  combineProcessors,
+  filterProcessor,
+  identityProcessor,
+  mapOutput,
+  withLogging
+} from "./chunk-EKHT54KN.js";
+import {
+  createInitialMessageAssemblerState,
+  createInitialStateEventProcessorContext,
+  createInitialTurnTrackerState,
+  messageAssemblerProcessor,
+  messageAssemblerProcessorDef,
+  stateEventProcessor,
+  stateEventProcessorDef,
+  turnTrackerProcessor,
+  turnTrackerProcessorDef
+} from "./chunk-I7GYR3MN.js";
+import "./chunk-7ZDX3O6I.js";
+import {
+  isMessageEvent,
+  isStateEvent,
+  isTurnEvent
+} from "./chunk-K6WXQ2RW.js";
+import "./chunk-E5FPOAPO.js";
+import "./chunk-7D4SUZUM.js";
+import "./chunk-RL3JRNXM.js";
+export {
+  AgentStateMachine,
+  MealyMachine,
+  MemoryStore,
+  agentProcessor,
+  chainProcessors,
+  combineInitialStates,
+  combineProcessors,
+  createAgent,
+  createInitialAgentEngineState,
+  createInitialMessageAssemblerState,
+  createInitialStateEventProcessorContext,
+  createInitialTurnTrackerState,
+  createMealyMachine,
+  filterProcessor,
+  identityProcessor,
+  isMessageEvent,
+  isStateEvent,
+  isTurnEvent,
+  mapOutput,
+  messageAssemblerProcessor,
+  messageAssemblerProcessorDef,
+  stateEventProcessor,
+  stateEventProcessorDef,
+  turnTrackerProcessor,
+  turnTrackerProcessorDef,
+  withLogging
+};
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

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

package/dist/message-BMrMm1pq.d.ts

@@ -0,0 +1,305 @@
+/**
+ * Message Types - Content Parts and Message Types
+ *
+ * This file defines:
+ * - Content Parts: TextPart, ThinkingPart, ImagePart, FilePart, ToolCallPart, ToolResultPart
+ * - Message Types: UserMessage, AssistantMessage, ToolCallMessage, ToolResultMessage, ErrorMessage
+ * - Message Role and Subtype discriminators
+ *
+ * @packageDocumentation
+ */
+/**
+ * Text Part
+ *
+ * Plain text content in a message.
+ */
+interface TextPart {
+    /** Content type discriminator */
+    type: "text";
+    /** The text content (supports Markdown) */
+    text: string;
+}
+/**
+ * Thinking Part
+ *
+ * AI's reasoning/thinking process (extended thinking).
+ */
+interface ThinkingPart {
+    /** Content type discriminator */
+    type: "thinking";
+    /** The reasoning text */
+    reasoning: string;
+    /** Tokens used for thinking (optional) */
+    tokenCount?: number;
+}
+/**
+ * Image Part
+ *
+ * Image content in a message.
+ */
+interface ImagePart {
+    /** Content type discriminator */
+    type: "image";
+    /** Image data (base64-encoded string or URL) */
+    data: string;
+    /** Image MIME type */
+    mediaType: "image/png" | "image/jpeg" | "image/gif" | "image/webp";
+    /** Optional image name/filename */
+    name?: string;
+}
+/**
+ * File Part
+ *
+ * File attachment in a message (PDF, documents, etc.).
+ */
+interface FilePart {
+    /** Content type discriminator */
+    type: "file";
+    /** File data (base64-encoded string or URL) */
+    data: string;
+    /** File MIME type (IANA media type) */
+    mediaType: string;
+    /** Optional filename */
+    filename?: string;
+}
+/**
+ * Tool Call Part
+ *
+ * AI's request to invoke a tool.
+ */
+interface ToolCallPart {
+    /** Content type discriminator */
+    type: "tool-call";
+    /** Unique identifier for this tool call */
+    id: string;
+    /** Tool name */
+    name: string;
+    /** Tool input parameters */
+    input: Record<string, unknown>;
+}
+/**
+ * Tool Result Output
+ *
+ * Enhanced tool result format supporting multiple output types.
+ * Based on Vercel AI SDK and industry best practices.
+ */
+type ToolResultOutput = 
+/**
+ * Plain text result
+ */
+{
+    type: "text";
+    value: string;
+}
+/**
+ * JSON result
+ */
+ | {
+    type: "json";
+    value: unknown;
+}
+/**
+ * Text error
+ */
+ | {
+    type: "error-text";
+    value: string;
+}
+/**
+ * JSON error
+ */
+ | {
+    type: "error-json";
+    value: unknown;
+}
+/**
+ * User denied tool execution
+ */
+ | {
+    type: "execution-denied";
+    reason?: string;
+}
+/**
+ * Rich content (multiple parts)
+ */
+ | {
+    type: "content";
+    value: Array<TextPart | ImagePart | FilePart>;
+};
+/**
+ * Tool Result Part
+ *
+ * Result of tool execution.
+ */
+interface ToolResultPart {
+    /** Content type discriminator */
+    type: "tool-result";
+    /** Tool call ID this result corresponds to */
+    id: string;
+    /** Tool name */
+    name: string;
+    /** Tool execution output */
+    output: ToolResultOutput;
+}
+/**
+ * Content Part
+ *
+ * Discriminated union of all content part types.
+ * Used in messages to support multi-modal and complex content.
+ */
+type ContentPart = TextPart | ThinkingPart | ImagePart | FilePart | ToolCallPart | ToolResultPart;
+/**
+ * User Content Part
+ *
+ * Subset of ContentPart types that users can send in messages.
+ * - TextPart: Plain text content
+ * - ImagePart: Image attachments (JPEG, PNG, GIF, WebP)
+ * - FilePart: File attachments (PDF, documents, etc.)
+ */
+type UserContentPart = TextPart | ImagePart | FilePart;
+/**
+ * Message Role
+ *
+ * Represents who sent the message in the conversation.
+ * Five fundamental roles in the conversation.
+ */
+type MessageRole = "user" | "assistant" | "tool" | "system" | "error";
+/**
+ * Message Subtype
+ *
+ * Represents the specific type/category of the message.
+ * Used together with role for serialization and type discrimination.
+ */
+type MessageSubtype = "user" | "assistant" | "tool-call" | "tool-result" | "error";
+/**
+ * Token usage information
+ */
+interface TokenUsage {
+    inputTokens: number;
+    outputTokens: number;
+    totalTokens?: number;
+}
+/**
+ * User Message
+ *
+ * Message sent by the user.
+ * Can contain simple text or rich content (text, images, files).
+ */
+interface UserMessage {
+    /** Unique identifier */
+    id: string;
+    /** Message role */
+    role: "user";
+    /** Message subtype for serialization */
+    subtype: "user";
+    /** Message content - can be simple string or array of parts */
+    content: string | UserContentPart[];
+    /** When this message was created (Unix timestamp in milliseconds) */
+    timestamp: number;
+    /** Parent message ID for threading (optional) */
+    parentId?: string;
+}
+/**
+ * Assistant Message
+ *
+ * Message generated by the AI assistant.
+ * Contains text, thinking process, or files.
+ *
+ * Note: Tool calls are separate - use ToolCallMessage for tool invocations.
+ */
+interface AssistantMessage {
+    /** Unique identifier */
+    id: string;
+    /** Message role */
+    role: "assistant";
+    /** Message subtype for serialization */
+    subtype: "assistant";
+    /** Message content - can be simple string or array of parts */
+    content: string | Array<TextPart | ThinkingPart | FilePart>;
+    /** When this message was created (Unix timestamp in milliseconds) */
+    timestamp: number;
+    /** Parent message ID for threading (optional) */
+    parentId?: string;
+    /** Token usage for this AI response (optional) */
+    usage?: TokenUsage;
+}
+/**
+ * Tool Call Message
+ *
+ * Represents AI's request to invoke a tool.
+ * Emitted when tool call parameters are fully assembled.
+ *
+ * Subject: Assistant (AI decided to call a tool)
+ * Timing: At tool_use_content_block_stop
+ */
+interface ToolCallMessage {
+    /** Unique message identifier */
+    id: string;
+    /** Message role - assistant initiates tool calls */
+    role: "assistant";
+    /** Message subtype for serialization */
+    subtype: "tool-call";
+    /** Tool call details */
+    toolCall: ToolCallPart;
+    /** When this message was created (Unix timestamp in milliseconds) */
+    timestamp: number;
+    /** Parent message ID (the assistant message that triggered this) */
+    parentId?: string;
+}
+/**
+ * Tool Result Message
+ *
+ * Represents the result of tool execution.
+ * Emitted after tool execution completes.
+ *
+ * Subject: Tool (execution completed with result)
+ * Timing: At tool_result event
+ */
+interface ToolResultMessage {
+    /** Unique message identifier */
+    id: string;
+    /** Message role - tool returns results */
+    role: "tool";
+    /** Message subtype for serialization */
+    subtype: "tool-result";
+    /** Tool result details */
+    toolResult: ToolResultPart;
+    /** ID of the corresponding tool call */
+    toolCallId: string;
+    /** When this message was created (Unix timestamp in milliseconds) */
+    timestamp: number;
+}
+/**
+ * Error Message
+ *
+ * Message representing an error that occurred during conversation.
+ * Displayed in the chat history so users can see what went wrong.
+ */
+interface ErrorMessage {
+    /** Unique identifier */
+    id: string;
+    /** Message role */
+    role: "error";
+    /** Message subtype for serialization */
+    subtype: "error";
+    /** Error message content (human-readable) */
+    content: string;
+    /** Error code (e.g., "rate_limit_error", "api_error") */
+    errorCode?: string;
+    /** When this error occurred (Unix timestamp in milliseconds) */
+    timestamp: number;
+    /** Parent message ID for threading (optional) */
+    parentId?: string;
+}
+/**
+ * Message
+ *
+ * Discriminated union of all message types.
+ * Use `subtype` field for precise type discrimination.
+ *
+ * Role: Who sent it (user, assistant, tool, system, error)
+ * Subtype: What type of message (user, assistant, tool-call, tool-result, error)
+ */
+type Message = UserMessage | AssistantMessage | ToolCallMessage | ToolResultMessage | ErrorMessage;
+
+export type { AssistantMessage as A, ContentPart as C, ErrorMessage as E, FilePart as F, ImagePart as I, Message as M, ToolCallMessage as T, UserMessage as U, ToolResultMessage as a, TokenUsage as b, UserContentPart as c, TextPart as d, ThinkingPart as e, ToolCallPart as f, ToolResultOutput as g, ToolResultPart as h, MessageRole as i, MessageSubtype as j };

package/dist/mq/index.d.ts

@@ -0,0 +1,165 @@
+/**
+ * MessageQueue - Reliable message delivery with persistence guarantee
+ *
+ * Standard interface for message queue implementations:
+ * - In-memory pub/sub for real-time delivery (RxJS)
+ * - Persistence for recovery guarantee (platform-specific)
+ * - Consumer offset tracking for at-least-once delivery
+ *
+ * Platform implementations:
+ * - Node.js: SQLite
+ * - Cloudflare Workers: Durable Objects Storage
+ * - Browser: IndexedDB
+ */
+/**
+ * QueueEntry - A single entry in the message queue
+ */
+interface QueueEntry {
+    /**
+     * Unique offset for this entry (monotonically increasing)
+     * Format: "{timestamp_base36}-{sequence}"
+     * Example: "lq5x4g2-0001"
+     */
+    readonly offset: string;
+    /**
+     * Topic this entry belongs to (e.g., sessionId, agentId)
+     */
+    readonly topic: string;
+    /**
+     * The actual event payload
+     */
+    readonly event: unknown;
+    /**
+     * Timestamp when the event was published (Unix milliseconds)
+     */
+    readonly timestamp: number;
+}
+/**
+ * QueueConfig - Platform-agnostic configuration
+ *
+ * Platform-specific options (path, namespace, etc.) are handled by Provider.
+ */
+interface QueueConfig {
+    /**
+     * Message retention timeout (milliseconds)
+     * Messages older than this may be deleted during cleanup
+     * @default 86400000 (24 hours)
+     */
+    retentionMs?: number;
+    /**
+     * Maximum entries per topic (optional)
+     * When exceeded, oldest entries may be removed
+     */
+    maxEntriesPerTopic?: number;
+}
+/**
+ * Unsubscribe function - call to stop receiving messages
+ */
+type Unsubscribe = () => void;
+/**
+ * MessageQueue - Standard interface for message queue
+ *
+ * All methods that involve storage are async to support all platforms.
+ */
+interface MessageQueue {
+    /**
+     * Publish an event to a topic
+     *
+     * - Persists to storage (async)
+     * - Broadcasts to all subscribers (in-memory, sync)
+     *
+     * @param topic - Topic identifier (e.g., sessionId)
+     * @param event - Event payload
+     * @returns Offset of the published entry
+     */
+    publish(topic: string, event: unknown): Promise<string>;
+    /**
+     * Subscribe to real-time events on a topic
+     *
+     * Receives events published after subscription (in-memory pub/sub).
+     * For historical events, use recover() first.
+     *
+     * @param topic - Topic identifier
+     * @param handler - Callback for each event entry
+     * @returns Unsubscribe function
+     */
+    subscribe(topic: string, handler: (entry: QueueEntry) => void): Unsubscribe;
+    /**
+     * Acknowledge consumption (update consumer offset)
+     *
+     * Call this after successfully processing an event.
+     * The offset is persisted for recovery.
+     *
+     * @param consumerId - Consumer identifier (e.g., connectionId)
+     * @param topic - Topic identifier
+     * @param offset - Offset of the consumed entry
+     */
+    ack(consumerId: string, topic: string, offset: string): Promise<void>;
+    /**
+     * Get consumer's current offset
+     *
+     * @param consumerId - Consumer identifier
+     * @param topic - Topic identifier
+     * @returns Offset or null if consumer not found
+     */
+    getOffset(consumerId: string, topic: string): Promise<string | null>;
+    /**
+     * Recover historical events from persistence
+     *
+     * Used for reconnection recovery - fetches events after an offset.
+     *
+     * @param topic - Topic identifier
+     * @param afterOffset - Start offset (exclusive), omit for all history
+     * @param limit - Maximum entries to return (default: 1000)
+     * @returns Array of event entries
+     */
+    recover(topic: string, afterOffset?: string, limit?: number): Promise<QueueEntry[]>;
+    /**
+     * Close the message queue and release resources
+     */
+    close(): Promise<void>;
+}
+/**
+ * MessageQueueProvider - Factory for creating MessageQueue instances
+ *
+ * Each platform implements its own provider:
+ * - SqliteMessageQueueProvider (Node.js)
+ * - DurableMessageQueueProvider (Cloudflare Workers)
+ * - IndexedDBMessageQueueProvider (Browser)
+ */
+interface MessageQueueProvider {
+    /**
+     * Create a MessageQueue instance
+     *
+     * @param config - Platform-agnostic configuration
+     * @returns MessageQueue instance
+     */
+    createQueue(config?: QueueConfig): Promise<MessageQueue>;
+}
+
+/**
+ * OffsetGenerator - Generates monotonically increasing offsets
+ *
+ * Format: "{timestamp_base36}-{sequence_padded}"
+ * Example: "lq5x4g2-0001"
+ *
+ * This format ensures:
+ * - Lexicographic ordering matches temporal ordering
+ * - Multiple events in same millisecond get unique offsets
+ * - Human-readable and compact
+ */
+declare class OffsetGenerator {
+    private lastTimestamp;
+    private sequence;
+    /**
+     * Generate a new offset
+     */
+    generate(): string;
+    /**
+     * Compare two offsets
+     * @returns negative if a < b, 0 if a == b, positive if a > b
+     */
+    static compare(a: string, b: string): number;
+}
+
+export { type MessageQueue, type MessageQueueProvider, OffsetGenerator, type QueueConfig, type QueueEntry, type Unsubscribe };

package/dist/mq/index.js

@@ -0,0 +1,37 @@
+import "../chunk-7D4SUZUM.js";
+
+// src/mq/OffsetGenerator.ts
+var OffsetGenerator = class {
+  lastTimestamp = 0;
+  sequence = 0;
+  /**
+   * Generate a new offset
+   */
+  generate() {
+    const now = Date.now();
+    if (now === this.lastTimestamp) {
+      this.sequence++;
+    } else {
+      this.lastTimestamp = now;
+      this.sequence = 0;
+    }
+    const timestampPart = now.toString(36);
+    const sequencePart = this.sequence.toString().padStart(4, "0");
+    return `${timestampPart}-${sequencePart}`;
+  }
+  /**
+   * Compare two offsets
+   * @returns negative if a < b, 0 if a == b, positive if a > b
+   */
+  static compare(a, b) {
+    const [aTime, aSeq] = a.split("-");
+    const [bTime, bSeq] = b.split("-");
+    const timeDiff = parseInt(aTime, 36) - parseInt(bTime, 36);
+    if (timeDiff !== 0) return timeDiff;
+    return parseInt(aSeq) - parseInt(bSeq);
+  }
+};
+export {
+  OffsetGenerator
+};
+//# sourceMappingURL=index.js.map

package/dist/mq/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/mq/OffsetGenerator.ts"],"sourcesContent":["/**\n * OffsetGenerator - Generates monotonically increasing offsets\n *\n * Format: \"{timestamp_base36}-{sequence_padded}\"\n * Example: \"lq5x4g2-0001\"\n *\n * This format ensures:\n * - Lexicographic ordering matches temporal ordering\n * - Multiple events in same millisecond get unique offsets\n * - Human-readable and compact\n */\nexport class OffsetGenerator {\n  private lastTimestamp = 0;\n  private sequence = 0;\n\n  /**\n   * Generate a new offset\n   */\n  generate(): string {\n    const now = Date.now();\n\n    if (now === this.lastTimestamp) {\n      this.sequence++;\n    } else {\n      this.lastTimestamp = now;\n      this.sequence = 0;\n    }\n\n    const timestampPart = now.toString(36);\n    const sequencePart = this.sequence.toString().padStart(4, \"0\");\n\n    return `${timestampPart}-${sequencePart}`;\n  }\n\n  /**\n   * Compare two offsets\n   * @returns negative if a < b, 0 if a == b, positive if a > b\n   */\n  static compare(a: string, b: string): number {\n    const [aTime, aSeq] = a.split(\"-\");\n    const [bTime, bSeq] = b.split(\"-\");\n\n    const timeDiff = parseInt(aTime, 36) - parseInt(bTime, 36);\n    if (timeDiff !== 0) return timeDiff;\n\n    return parseInt(aSeq) - parseInt(bSeq);\n  }\n}\n"],"mappings":";;;AAWO,IAAM,kBAAN,MAAsB;AAAA,EACnB,gBAAgB;AAAA,EAChB,WAAW;AAAA;AAAA;AAAA;AAAA,EAKnB,WAAmB;AACjB,UAAM,MAAM,KAAK,IAAI;AAErB,QAAI,QAAQ,KAAK,eAAe;AAC9B,WAAK;AAAA,IACP,OAAO;AACL,WAAK,gBAAgB;AACrB,WAAK,WAAW;AAAA,IAClB;AAEA,UAAM,gBAAgB,IAAI,SAAS,EAAE;AACrC,UAAM,eAAe,KAAK,SAAS,SAAS,EAAE,SAAS,GAAG,GAAG;AAE7D,WAAO,GAAG,aAAa,IAAI,YAAY;AAAA,EACzC;AAAA;AAAA;AAAA;AAAA;AAAA,EAMA,OAAO,QAAQ,GAAW,GAAmB;AAC3C,UAAM,CAAC,OAAO,IAAI,IAAI,EAAE,MAAM,GAAG;AACjC,UAAM,CAAC,OAAO,IAAI,IAAI,EAAE,MAAM,GAAG;AAEjC,UAAM,WAAW,SAAS,OAAO,EAAE,IAAI,SAAS,OAAO,EAAE;AACzD,QAAI,aAAa,EAAG,QAAO;AAE3B,WAAO,SAAS,IAAI,IAAI,SAAS,IAAI;AAAA,EACvC;AACF;","names":[]}