@agentxjs/types 0.0.9 → 0.2.0

package/dist/StopReason-D4DthB1h.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Reason why the LLM stopped generating
+ *
+ * Based on common stop reasons across multiple LLM providers:
+ * - Anthropic Claude: end_turn, max_tokens, tool_use, stop_sequence
+ * - OpenAI: stop, length, tool_calls, content_filter
+ * - Vercel AI SDK: stop, length, tool-calls, content-filter, error, other
+ */
+type StopReason = 
+/**
+ * Natural completion - model decided to stop
+ */
+"end_turn"
+/**
+ * Reached maximum token limit
+ */
+ | "max_tokens"
+/**
+ * Model requested tool usage
+ */
+ | "tool_use"
+/**
+ * Encountered a custom stop sequence
+ */
+ | "stop_sequence"
+/**
+ * Content filter triggered
+ */
+ | "content_filter"
+/**
+ * Error occurred during generation
+ */
+ | "error"
+/**
+ * Other/unknown reason
+ */
+ | "other";
+
+export type { StopReason as S };

package/dist/SystemEvent-CPvvxdMQ.d.cts

@@ -0,0 +1,159 @@
+/**
+ * SystemEvent - Base interface for all events in the system
+ *
+ * Unified Event Structure:
+ * ```
+ * SystemEvent
+ * │
+ * │  All events have: type, timestamp, data, source, category, intent
+ * │
+ * ├── source: "command"       ← API operations (request/response)
+ * │   ├── category: "request"   → container_create_request, agent_run_request...
+ * │   └── category: "response"  → container_create_response, agent_run_response...
+ * │
+ * ├── source: "environment"   ← External world (Claude API, Network)
+ * │   ├── category: "stream"    → message_start, text_delta, message_stop, tool_call...
+ * │   └── category: "connection"→ connected, disconnected, reconnecting
+ * │
+ * ├── source: "container"     ← Container operations
+ * │   └── category: "lifecycle" → container_created, container_destroyed, agent_registered...
+ * │
+ * ├── source: "session"       ← Session operations
+ * │   ├── category: "lifecycle" → session_created, session_destroyed
+ * │   ├── category: "persist"   → session_saved, message_persisted
+ * │   └── category: "action"    → session_resumed, session_forked
+ * │
+ * ├── source: "sandbox"       ← Sandbox resources
+ * │   ├── category: "workdir"   → file_read, file_written
+ * │   └── category: "mcp"       → tool_execute, mcp_server_connected
+ * │
+ * └── source: "agent"         ← Agent internal
+ *     ├── category: "stream"    → (forwarded from environment)
+ *     ├── category: "state"     → state transitions
+ *     ├── category: "message"   → complete messages
+ *     └── category: "turn"      → conversation turns
+ * ```
+ *
+ * Design Principles:
+ * - Unified: All events share the same base structure
+ * - Self-describing: source/category/intent tell you everything
+ * - Filterable: Easy to subscribe by source, category, or type
+ */
+/**
+ * Event source - where the event originated
+ */
+type EventSource = "environment" | "agent" | "session" | "container" | "sandbox" | "command";
+/**
+ * Event intent - what the event represents
+ */
+type EventIntent = "request" | "result" | "notification";
+/**
+ * Event category - fine-grained classification within source
+ */
+type EventCategory = "stream" | "connection" | "state" | "message" | "turn" | "error" | "lifecycle" | "persist" | "action" | "workdir" | "mcp" | "request" | "response";
+/**
+ * EventContext - Scope information attached to events
+ */
+interface EventContext {
+    /**
+     * Container ID (isolation boundary)
+     */
+    containerId?: string;
+    /**
+     * Image ID (persistent conversation identity)
+     */
+    imageId?: string;
+    /**
+     * Agent ID (if event is agent-scoped)
+     */
+    agentId?: string;
+    /**
+     * Session ID (if event is session-scoped)
+     */
+    sessionId?: string;
+    /**
+     * Turn ID (for correlating events within a single turn)
+     * A turn = one user message + assistant response cycle
+     */
+    turnId?: string;
+    /**
+     * Correlation ID (for request-response tracking)
+     */
+    correlationId?: string;
+}
+/**
+ * SystemEvent - Base interface for ALL events in the system
+ *
+ * Every event has:
+ * - type: What happened (e.g., "text_delta", "session_saved")
+ * - timestamp: When it happened
+ * - data: Event payload
+ * - source: Where it came from
+ * - category: What kind of event
+ * - intent: What it means (notification/request/result)
+ * - context: Optional scope information
+ * - broadcastable: Whether to broadcast to external clients (default: true)
+ */
+interface SystemEvent<T extends string = string, D = unknown, S extends EventSource = EventSource, C extends EventCategory = EventCategory, I extends EventIntent = EventIntent> {
+    /**
+     * Event type identifier (e.g., "text_delta", "session_saved")
+     */
+    readonly type: T;
+    /**
+     * Event timestamp (Unix milliseconds)
+     */
+    readonly timestamp: number;
+    /**
+     * Event payload data
+     */
+    readonly data: D;
+    /**
+     * Event source - where the event originated
+     */
+    readonly source: S;
+    /**
+     * Event category - fine-grained classification
+     */
+    readonly category: C;
+    /**
+     * Event intent - what the event represents
+     */
+    readonly intent: I;
+    /**
+     * Event context - scope information (optional)
+     */
+    readonly context?: EventContext;
+    /**
+     * Whether to broadcast this event to external clients (SSE/WebSocket)
+     *
+     * - true or undefined: Broadcast to all external clients
+     * - false: Only consumed internally, not broadcast
+     *
+     * Used for internal events like DriveableEvent that should be
+     * processed by the engine but not sent directly to clients.
+     * @default true
+     */
+    readonly broadcastable?: boolean;
+}
+/**
+ * Check if event is from a specific source
+ */
+declare function isFromSource<S extends EventSource>(event: SystemEvent, source: S): event is SystemEvent<string, unknown, S>;
+/**
+ * Check if event has a specific intent
+ */
+declare function hasIntent<I extends EventIntent>(event: SystemEvent, intent: I): event is SystemEvent<string, unknown, EventSource, EventCategory, I>;
+/**
+ * Check if event is a request
+ */
+declare function isRequest(event: SystemEvent): boolean;
+/**
+ * Check if event is a result
+ */
+declare function isResult(event: SystemEvent): boolean;
+/**
+ * Check if event is a notification
+ */
+declare function isNotification(event: SystemEvent): boolean;
+
+export { type EventSource as E, type SystemEvent as S, type EventIntent as a, type EventCategory as b, type EventContext as c, isRequest as d, isResult as e, isNotification as f, hasIntent as h, isFromSource as i };

package/dist/SystemEvent-CPvvxdMQ.d.ts

@@ -0,0 +1,159 @@
+/**
+ * SystemEvent - Base interface for all events in the system
+ *
+ * Unified Event Structure:
+ * ```
+ * SystemEvent
+ * │
+ * │  All events have: type, timestamp, data, source, category, intent
+ * │
+ * ├── source: "command"       ← API operations (request/response)
+ * │   ├── category: "request"   → container_create_request, agent_run_request...
+ * │   └── category: "response"  → container_create_response, agent_run_response...
+ * │
+ * ├── source: "environment"   ← External world (Claude API, Network)
+ * │   ├── category: "stream"    → message_start, text_delta, message_stop, tool_call...
+ * │   └── category: "connection"→ connected, disconnected, reconnecting
+ * │
+ * ├── source: "container"     ← Container operations
+ * │   └── category: "lifecycle" → container_created, container_destroyed, agent_registered...
+ * │
+ * ├── source: "session"       ← Session operations
+ * │   ├── category: "lifecycle" → session_created, session_destroyed
+ * │   ├── category: "persist"   → session_saved, message_persisted
+ * │   └── category: "action"    → session_resumed, session_forked
+ * │
+ * ├── source: "sandbox"       ← Sandbox resources
+ * │   ├── category: "workdir"   → file_read, file_written
+ * │   └── category: "mcp"       → tool_execute, mcp_server_connected
+ * │
+ * └── source: "agent"         ← Agent internal
+ *     ├── category: "stream"    → (forwarded from environment)
+ *     ├── category: "state"     → state transitions
+ *     ├── category: "message"   → complete messages
+ *     └── category: "turn"      → conversation turns
+ * ```
+ *
+ * Design Principles:
+ * - Unified: All events share the same base structure
+ * - Self-describing: source/category/intent tell you everything
+ * - Filterable: Easy to subscribe by source, category, or type
+ */
+/**
+ * Event source - where the event originated
+ */
+type EventSource = "environment" | "agent" | "session" | "container" | "sandbox" | "command";
+/**
+ * Event intent - what the event represents
+ */
+type EventIntent = "request" | "result" | "notification";
+/**
+ * Event category - fine-grained classification within source
+ */
+type EventCategory = "stream" | "connection" | "state" | "message" | "turn" | "error" | "lifecycle" | "persist" | "action" | "workdir" | "mcp" | "request" | "response";
+/**
+ * EventContext - Scope information attached to events
+ */
+interface EventContext {
+    /**
+     * Container ID (isolation boundary)
+     */
+    containerId?: string;
+    /**
+     * Image ID (persistent conversation identity)
+     */
+    imageId?: string;
+    /**
+     * Agent ID (if event is agent-scoped)
+     */
+    agentId?: string;
+    /**
+     * Session ID (if event is session-scoped)
+     */
+    sessionId?: string;
+    /**
+     * Turn ID (for correlating events within a single turn)
+     * A turn = one user message + assistant response cycle
+     */
+    turnId?: string;
+    /**
+     * Correlation ID (for request-response tracking)
+     */
+    correlationId?: string;
+}
+/**
+ * SystemEvent - Base interface for ALL events in the system
+ *
+ * Every event has:
+ * - type: What happened (e.g., "text_delta", "session_saved")
+ * - timestamp: When it happened
+ * - data: Event payload
+ * - source: Where it came from
+ * - category: What kind of event
+ * - intent: What it means (notification/request/result)
+ * - context: Optional scope information
+ * - broadcastable: Whether to broadcast to external clients (default: true)
+ */
+interface SystemEvent<T extends string = string, D = unknown, S extends EventSource = EventSource, C extends EventCategory = EventCategory, I extends EventIntent = EventIntent> {
+    /**
+     * Event type identifier (e.g., "text_delta", "session_saved")
+     */
+    readonly type: T;
+    /**
+     * Event timestamp (Unix milliseconds)
+     */
+    readonly timestamp: number;
+    /**
+     * Event payload data
+     */
+    readonly data: D;
+    /**
+     * Event source - where the event originated
+     */
+    readonly source: S;
+    /**
+     * Event category - fine-grained classification
+     */
+    readonly category: C;
+    /**
+     * Event intent - what the event represents
+     */
+    readonly intent: I;
+    /**
+     * Event context - scope information (optional)
+     */
+    readonly context?: EventContext;
+    /**
+     * Whether to broadcast this event to external clients (SSE/WebSocket)
+     *
+     * - true or undefined: Broadcast to all external clients
+     * - false: Only consumed internally, not broadcast
+     *
+     * Used for internal events like DriveableEvent that should be
+     * processed by the engine but not sent directly to clients.
+     * @default true
+     */
+    readonly broadcastable?: boolean;
+}
+/**
+ * Check if event is from a specific source
+ */
+declare function isFromSource<S extends EventSource>(event: SystemEvent, source: S): event is SystemEvent<string, unknown, S>;
+/**
+ * Check if event has a specific intent
+ */
+declare function hasIntent<I extends EventIntent>(event: SystemEvent, intent: I): event is SystemEvent<string, unknown, EventSource, EventCategory, I>;
+/**
+ * Check if event is a request
+ */
+declare function isRequest(event: SystemEvent): boolean;
+/**
+ * Check if event is a result
+ */
+declare function isResult(event: SystemEvent): boolean;
+/**
+ * Check if event is a notification
+ */
+declare function isNotification(event: SystemEvent): boolean;
+
+export { type EventSource as E, type SystemEvent as S, type EventIntent as a, type EventCategory as b, type EventContext as c, isRequest as d, isResult as e, isNotification as f, hasIntent as h, isFromSource as i };

package/dist/ToolResultMessage-CDG2L7Zv.d.ts

@@ -0,0 +1,332 @@
+import { S as SystemEvent, c as EventContext } from './SystemEvent-CPvvxdMQ.js';
+
+/**
+ * Text Part
+ *
+ * Plain text content in a message.
+ */
+interface TextPart {
+    /** Content type discriminator */
+    type: "text";
+    /** The text content (supports Markdown) */
+    text: string;
+}
+
+/**
+ * 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;
+}
+
+/**
+ * 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 | Array<TextPart | ImagePart | FilePart>;
+    /** When this message was created (Unix timestamp in milliseconds) */
+    timestamp: number;
+    /** Parent message ID for threading (optional) */
+    parentId?: 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;
+}
+
+/**
+ * BaseAgentEvent - Base type for all Agent domain events
+ *
+ * All Agent events have:
+ * - source: "agent"
+ * - category: stream | state | message | turn
+ * - intent: "notification"
+ */
+
+/**
+ * Agent event categories
+ */
+type AgentEventCategory = "stream" | "state" | "message" | "turn";
+/**
+ * BaseAgentEvent - Base interface for all Agent events
+ *
+ * Extends SystemEvent with fixed source and intent.
+ */
+interface BaseAgentEvent<T extends string, D, C extends AgentEventCategory> extends SystemEvent<T, D, "agent", C, "notification"> {
+    /**
+     * Runtime context (optional, added by Presenter)
+     */
+    readonly context?: EventContext;
+}
+
+/**
+ * Agent Turn Events
+ *
+ * Turn-level events for analytics and billing.
+ * A turn = one user message + assistant response cycle.
+ * - source: "agent"
+ * - category: "turn"
+ * - intent: "notification"
+ */
+
+/**
+ * Base type for turn events
+ */
+interface AgentTurnEventBase<T extends string, D> extends BaseAgentEvent<T, D, "turn"> {
+}
+/**
+ * Token usage information
+ */
+interface TokenUsage {
+    inputTokens: number;
+    outputTokens: number;
+    totalTokens?: number;
+}
+/**
+ * TurnRequestEvent - Turn started (user message received)
+ */
+interface TurnRequestEvent extends AgentTurnEventBase<"turn_request", {
+    turnId: string;
+    messageId: string;
+    content: string;
+    timestamp: number;
+}> {
+}
+/**
+ * TurnResponseEvent - Turn completed (assistant response finished)
+ */
+interface TurnResponseEvent extends AgentTurnEventBase<"turn_response", {
+    turnId: string;
+    messageId: string;
+    duration: number;
+    usage?: TokenUsage;
+    model?: string;
+    stopReason?: string;
+    timestamp: number;
+}> {
+}
+/**
+ * AgentTurnEvent - All turn events
+ */
+type AgentTurnEvent = TurnRequestEvent | TurnResponseEvent;
+/**
+ * AgentTurnEventType - String literal union
+ */
+type AgentTurnEventType = AgentTurnEvent["type"];
+/**
+ * Type guard: is this a turn event?
+ */
+declare function isAgentTurnEvent(event: {
+    source?: string;
+    category?: string;
+}): event is AgentTurnEvent;
+
+/**
+ * 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 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 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
+ */
+
+/**
+ * Tool Call Message
+ */
+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 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;
+}
+
+/**
+ * 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
+ */
+
+/**
+ * Tool Result Message
+ */
+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;
+}
+
+export { type AssistantMessage as A, type BaseAgentEvent as B, type FilePart as F, type ImagePart as I, type ToolCallMessage as T, type UserMessage as U, type ToolResultMessage as a, type TextPart as b, type ThinkingPart as c, type ToolCallPart as d, type ToolResultPart as e, type ToolResultOutput as f, type TokenUsage as g, type AgentTurnEvent as h, type TurnRequestEvent as i, type TurnResponseEvent as j, type AgentEventCategory as k, type AgentTurnEventBase as l, type AgentTurnEventType as m, isAgentTurnEvent as n };