@better-agent/core 0.1.0-beta.1

package/dist/mcp/tool/types.d.mts

@@ -0,0 +1,230 @@
+//#region src/mcp/tool/types.d.ts
+/**
+ * Model Context Protocol (MCP) type definitions.
+ *
+ * Based on the MCP specification dated `2025-11-25`.
+ */
+/** Latest MCP protocol version. */
+declare const LATEST_PROTOCOL_VERSION = "2025-11-25";
+/** Supported protocol versions. */
+declare const SUPPORTED_PROTOCOL_VERSIONS: readonly ["2025-11-25", "2025-06-18", "2025-03-26", "2024-11-05"];
+/** MCP server capabilities. */
+interface ServerCapabilities {
+  /** Server supports logging notifications. */
+  logging?: Record<string, never>;
+  /** Server supports prompts. */
+  prompts?: {
+    /** Server supports `listChanged` notifications. */listChanged?: boolean;
+  };
+  /** Server supports resources. */
+  resources?: {
+    /** Server supports resource subscription. */subscribe?: boolean; /** Server supports `listChanged` notifications. */
+    listChanged?: boolean;
+  };
+  /** Server supports tools. */
+  tools?: {
+    /** Server supports `listChanged` notifications. */listChanged?: boolean;
+  };
+  /** Experimental capabilities. */
+  experimental?: Record<string, unknown>;
+}
+/** MCP client capabilities. */
+interface ClientCapabilities {
+  /** Client supports receiving roots. */
+  roots?: {
+    /** Client supports `listChanged` notifications. */listChanged?: boolean;
+  };
+  /** Client supports sampling. */
+  sampling?: Record<string, never>;
+  /** Client supports elicitation. */
+  elicitation?: {
+    /** Whether to apply default values from schema. */applyDefaults?: boolean;
+  };
+  /** Experimental capabilities. */
+  experimental?: Record<string, unknown>;
+}
+/** Client or server implementation info. */
+interface MCPImplementationInfo {
+  name: string;
+  version: string;
+}
+/** Initialize request params. */
+interface InitializeParams {
+  protocolVersion: string;
+  capabilities: ClientCapabilities;
+  clientInfo: MCPImplementationInfo;
+}
+/** Initialize result. */
+interface InitializeResult {
+  protocolVersion: string;
+  capabilities: ServerCapabilities;
+  serverInfo: MCPImplementationInfo;
+  /** Instructions for the client. */
+  instructions?: string;
+}
+/** Paginated request params. */
+interface PaginatedRequest {
+  cursor?: string;
+}
+/** Paginated result base. */
+interface PaginatedResult {
+  nextCursor?: string;
+}
+/** MCP tool definition. */
+interface MCPTool {
+  /** Tool name. */
+  name: string;
+  /** Tool description. */
+  description?: string;
+  /** JSON Schema for tool input. */
+  inputSchema: {
+    type: "object";
+    properties?: Record<string, unknown>;
+    required?: string[];
+    $schema?: string;
+  };
+  /** Tool annotations. */
+  annotations?: {
+    /** Human-readable title. */title?: string; /** Whether the tool may perform destructive updates. */
+    destructive?: boolean; /** Whether the tool may return different results for the same input. */
+    idempotent?: boolean; /** Whether the tool may open UI. */
+    openWorld?: boolean; /** Whether the tool may read data. */
+    readOnly?: boolean;
+  };
+  /** Arbitrary metadata. */
+  _meta?: Record<string, unknown>;
+}
+/** List tools result. */
+interface ListToolsResult extends PaginatedResult {
+  tools: MCPTool[];
+}
+/** Tool call request params. */
+interface MCPCallToolParams {
+  /** Tool name. */
+  name: string;
+  /** Tool arguments. */
+  arguments?: Record<string, unknown>;
+  /** Additional metadata. */
+  _meta?: Record<string, unknown>;
+}
+/** Tool result content item. */
+type ToolResultContent = {
+  type: "text";
+  text: string;
+} | {
+  type: "image";
+  data: string;
+  mimeType: string;
+} | {
+  type: "resource";
+  resource: MCPResource;
+};
+/** Tool call result. */
+interface MCPCallToolResult {
+  /** Tool result content. */
+  content: ToolResultContent[];
+  /** Whether the result is an error. */
+  isError?: boolean;
+  /** Structured content, when available. */
+  structuredContent?: unknown;
+}
+/** MCP resource. */
+interface MCPResource {
+  /** Resource URI. */
+  uri: string;
+  /** Resource name. */
+  name: string;
+  /** Resource description. */
+  description?: string;
+  /** MIME type. */
+  mimeType?: string;
+  /** Resource size in bytes, if known. */
+  size?: number;
+  /** Resource content. */
+  text?: string;
+  /** Binary content in base64 form. */
+  blob?: string;
+}
+/** List resources result. */
+interface ListResourcesResult extends PaginatedResult {
+  resources: MCPResource[];
+}
+/** Resource template. */
+interface MCPResourceTemplate {
+  /** URI template. */
+  uriTemplate: string;
+  /** Template name. */
+  name: string;
+  /** Template description. */
+  description?: string;
+  /** MIME type. */
+  mimeType?: string;
+}
+/** List resource templates result. */
+interface ListResourceTemplatesResult extends PaginatedResult {
+  resourceTemplates: MCPResourceTemplate[];
+}
+/** Read resource request. */
+interface MCPReadResourceParams {
+  /** Resource URI. */
+  uri: string;
+}
+/** Read resource result. */
+interface MCPReadResourceResult {
+  contents: MCPResource[];
+}
+/** MCP prompt. */
+interface MCPPrompt {
+  /** Prompt name. */
+  name: string;
+  /** Prompt description. */
+  description?: string;
+  /** Prompt arguments schema. */
+  arguments?: Array<{
+    /** Argument name. */name: string; /** Argument description. */
+    description?: string; /** Whether the argument is required. */
+    required?: boolean;
+  }>;
+}
+/** List prompts result. */
+interface ListPromptsResult extends PaginatedResult {
+  prompts: MCPPrompt[];
+}
+/** Get prompt request. */
+interface MCPGetPromptParams {
+  /** Prompt name. */
+  name: string;
+  /** Prompt arguments. */
+  arguments?: Record<string, string>;
+}
+/** Prompt message */
+type PromptMessage = {
+  role: "user";
+  content: {
+    type: "text";
+    text: string;
+  };
+} | {
+  role: "assistant";
+  content: {
+    type: "text";
+    text: string;
+  };
+};
+/** Get prompt result */
+interface MCPGetPromptResult {
+  /** Prompt description */
+  description?: string;
+  /** Prompt messages */
+  messages: PromptMessage[];
+}
+/** Request options for MCP operations */
+interface RequestOptions {
+  /** Abort signal for cancellation */
+  signal?: AbortSignal;
+  /** Timeout in milliseconds */
+  timeout?: number;
+}
+//#endregion
+export { ClientCapabilities, InitializeParams, InitializeResult, LATEST_PROTOCOL_VERSION, ListPromptsResult, ListResourceTemplatesResult, ListResourcesResult, ListToolsResult, MCPCallToolParams, MCPCallToolResult, MCPGetPromptParams, MCPGetPromptResult, MCPImplementationInfo, MCPPrompt, MCPReadResourceParams, MCPReadResourceResult, MCPResource, MCPResourceTemplate, MCPTool, PaginatedRequest, PaginatedResult, PromptMessage, RequestOptions, SUPPORTED_PROTOCOL_VERSIONS, ServerCapabilities, ToolResultContent };
+//# sourceMappingURL=types.d.mts.map

package/dist/mcp/tool/types.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.mts","names":[],"sources":["../../../src/mcp/tool/types.ts"],"mappings":";;AAOA;;;;;cAAa,uBAAA;;cAGA,2BAAA;;UAQI,kBAAA;EAAA;EAEb,OAAA,GAAU,MAAA;;EAGV,OAAA;IAHA,mDAKI,WAAA;EAAA;EAAA;EAIJ,SAAA;IAEI,6CAAA,SAAA,YAMJ;IAJI,WAAA;EAAA;EAUW;EANf,KAAA;IAMqB,mDAJjB,WAAA;EAAA;;EAIJ,YAAA,GAAe,MAAA;AAAA;;UAIF,kBAAA;EAQF;EANX,KAAA;IAWI,mDATA,WAAA;EAAA;EAaiB;EATrB,QAAA,GAAW,MAAA;EAaE;EAVb,WAAA;IAUkC,mDAR9B,aAAA;EAAA;EAcS;EAVb,YAAA,GAAe,MAAA;AAAA;;UAIF,qBAAA;EACb,IAAA;EACA,OAAA;AAAA;;UAIa,gBAAA;EACb,eAAA;EACA,YAAA,EAAc,kBAAA;EACd,UAAA,EAAY,qBAAA;AAAA;;UAIC,gBAAA;EACb,eAAA;EACA,YAAA,EAAc,kBAAA;EACd,UAAA,EAAY,qBAAA;EAAA;EAEZ,YAAA;AAAA;;UAIa,gBAAA;EACb,MAAA;AAAA;;UAIa,eAAA;EACb,UAAA;AAAA;;UAIa,OAAA;EAJH;EAMV,IAAA;EAFoB;EAKpB,WAAA;EAyBc;EAtBd,WAAA;IACI,IAAA;IACA,UAAA,GAAa,MAAA;IACb,QAAA;IACA,OAAA;EAAA;EADA;EAKJ,WAAA;IAAA,4BAEI,KAAA,WAEA;IAAA,WAAA,YAIA;IAFA,UAAA,YAQJ;IANI,SAAA,YAMU;IAJV,QAAA;EAAA;EAQyB;EAJ7B,KAAA,GAAQ,MAAA;AAAA;;UAIK,eAAA,SAAwB,eAAA;EACrC,KAAA,EAAO,OAAA;AAAA;;UAIM,iBAAA;EAAiB;EAE9B,IAAA;EAMc;EAHd,SAAA,GAAY,MAAA;EAAZ;EAGA,KAAA,GAAQ,MAAA;AAAA;;KAIA,iBAAA;EACJ,IAAA;EAAc,IAAA;AAAA;EACd,IAAA;EAAe,IAAA;EAAc,QAAA;AAAA;EAC7B,IAAA;EAAkB,QAAA,EAAU,WAAA;AAAA;;UAGnB,iBAAA;EAHmB;EAKhC,OAAA,EAAS,iBAAA;EALkC;EAQ3C,OAAA;EAL8B;EAQ9B,iBAAA;AAAA;;UAIa,WAAA;EAPb;EASA,GAAA;EANiB;EASjB,IAAA;EALa;EAQb,WAAA;;EAGA,QAAA;EATA;EAYA,IAAA;EANA;EASA,IAAA;EAHA;EAMA,IAAA;AAAA;;UAIa,mBAAA,SAA4B,eAAA;EACzC,SAAA,EAAW,WAAA;AAAA;;UAIE,mBAAA;EAL4B;EAOzC,WAAA;EANW;EASX,IAAA;EATsB;EAYtB,WAAA;EARgC;EAWhC,QAAA;AAAA;;UAIa,2BAAA,SAAoC,eAAA;EACjD,iBAAA,EAAmB,mBAAA;AAAA;;UAIN,qBAAA;EALA;EAOb,GAAA;AAAA;;UAIa,qBAAA;EACb,QAAA,EAAU,WAAA;AAAA;;UAIG,SAAA;EAXA;EAab,IAAA;;EAGA,WAAA;EAdG;EAiBH,SAAA,GAAY,KAAA;IAbsB,qBAe9B,IAAA,UAdM;IAgBN,WAAA,WAZS;IAcT,QAAA;EAAA;AAAA;;UAKS,iBAAA,SAA0B,eAAA;EACvC,OAAA,EAAS,SAAA;AAAA;;UAII,kBAAA;EAVT;EAYJ,IAAA;EAZY;EAeZ,SAAA,GAAY,MAAA;AAAA;;KAIJ,aAAA;EACJ,IAAA;EAAc,OAAA;IAAW,IAAA;IAAc,IAAA;EAAA;AAAA;EACvC,IAAA;EAAmB,OAAA;IAAW,IAAA;IAAc,IAAA;EAAA;AAAA;;UAGnC,kBAAA;EALL;EAOR,WAAA;;EAGA,QAAA,EAAU,aAAA;AAAA;;UAIG,cAAA;EAb8B;EAe3C,MAAA,GAAS,WAAA;EAdc;EAiBvB,OAAA;AAAA"}

package/dist/mcp/tool/types.mjs

@@ -0,0 +1,19 @@
+//#region src/mcp/tool/types.ts
+/**
+* Model Context Protocol (MCP) type definitions.
+*
+* Based on the MCP specification dated `2025-11-25`.
+*/
+/** Latest MCP protocol version. */
+const LATEST_PROTOCOL_VERSION = "2025-11-25";
+/** Supported protocol versions. */
+const SUPPORTED_PROTOCOL_VERSIONS = [
+	LATEST_PROTOCOL_VERSION,
+	"2025-06-18",
+	"2025-03-26",
+	"2024-11-05"
+];
+
+//#endregion
+export { LATEST_PROTOCOL_VERSION, SUPPORTED_PROTOCOL_VERSIONS };
+//# sourceMappingURL=types.mjs.map

package/dist/mcp/tool/types.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.mjs","names":[],"sources":["../../../src/mcp/tool/types.ts"],"sourcesContent":["/**\n * Model Context Protocol (MCP) type definitions.\n *\n * Based on the MCP specification dated `2025-11-25`.\n */\n\n/** Latest MCP protocol version. */\nexport const LATEST_PROTOCOL_VERSION = \"2025-11-25\";\n\n/** Supported protocol versions. */\nexport const SUPPORTED_PROTOCOL_VERSIONS = [\n    LATEST_PROTOCOL_VERSION,\n    \"2025-06-18\",\n    \"2025-03-26\",\n    \"2024-11-05\",\n] as const;\n\n/** MCP server capabilities. */\nexport interface ServerCapabilities {\n    /** Server supports logging notifications. */\n    logging?: Record<string, never>;\n\n    /** Server supports prompts. */\n    prompts?: {\n        /** Server supports `listChanged` notifications. */\n        listChanged?: boolean;\n    };\n\n    /** Server supports resources. */\n    resources?: {\n        /** Server supports resource subscription. */\n        subscribe?: boolean;\n        /** Server supports `listChanged` notifications. */\n        listChanged?: boolean;\n    };\n\n    /** Server supports tools. */\n    tools?: {\n        /** Server supports `listChanged` notifications. */\n        listChanged?: boolean;\n    };\n\n    /** Experimental capabilities. */\n    experimental?: Record<string, unknown>;\n}\n\n/** MCP client capabilities. */\nexport interface ClientCapabilities {\n    /** Client supports receiving roots. */\n    roots?: {\n        /** Client supports `listChanged` notifications. */\n        listChanged?: boolean;\n    };\n\n    /** Client supports sampling. */\n    sampling?: Record<string, never>;\n\n    /** Client supports elicitation. */\n    elicitation?: {\n        /** Whether to apply default values from schema. */\n        applyDefaults?: boolean;\n    };\n\n    /** Experimental capabilities. */\n    experimental?: Record<string, unknown>;\n}\n\n/** Client or server implementation info. */\nexport interface MCPImplementationInfo {\n    name: string;\n    version: string;\n}\n\n/** Initialize request params. */\nexport interface InitializeParams {\n    protocolVersion: string;\n    capabilities: ClientCapabilities;\n    clientInfo: MCPImplementationInfo;\n}\n\n/** Initialize result. */\nexport interface InitializeResult {\n    protocolVersion: string;\n    capabilities: ServerCapabilities;\n    serverInfo: MCPImplementationInfo;\n    /** Instructions for the client. */\n    instructions?: string;\n}\n\n/** Paginated request params. */\nexport interface PaginatedRequest {\n    cursor?: string;\n}\n\n/** Paginated result base. */\nexport interface PaginatedResult {\n    nextCursor?: string;\n}\n\n/** MCP tool definition. */\nexport interface MCPTool {\n    /** Tool name. */\n    name: string;\n\n    /** Tool description. */\n    description?: string;\n\n    /** JSON Schema for tool input. */\n    inputSchema: {\n        type: \"object\";\n        properties?: Record<string, unknown>;\n        required?: string[];\n        $schema?: string;\n    };\n\n    /** Tool annotations. */\n    annotations?: {\n        /** Human-readable title. */\n        title?: string;\n        /** Whether the tool may perform destructive updates. */\n        destructive?: boolean;\n        /** Whether the tool may return different results for the same input. */\n        idempotent?: boolean;\n        /** Whether the tool may open UI. */\n        openWorld?: boolean;\n        /** Whether the tool may read data. */\n        readOnly?: boolean;\n    };\n\n    /** Arbitrary metadata. */\n    _meta?: Record<string, unknown>;\n}\n\n/** List tools result. */\nexport interface ListToolsResult extends PaginatedResult {\n    tools: MCPTool[];\n}\n\n/** Tool call request params. */\nexport interface MCPCallToolParams {\n    /** Tool name. */\n    name: string;\n\n    /** Tool arguments. */\n    arguments?: Record<string, unknown>;\n\n    /** Additional metadata. */\n    _meta?: Record<string, unknown>;\n}\n\n/** Tool result content item. */\nexport type ToolResultContent =\n    | { type: \"text\"; text: string }\n    | { type: \"image\"; data: string; mimeType: string }\n    | { type: \"resource\"; resource: MCPResource };\n\n/** Tool call result. */\nexport interface MCPCallToolResult {\n    /** Tool result content. */\n    content: ToolResultContent[];\n\n    /** Whether the result is an error. */\n    isError?: boolean;\n\n    /** Structured content, when available. */\n    structuredContent?: unknown;\n}\n\n/** MCP resource. */\nexport interface MCPResource {\n    /** Resource URI. */\n    uri: string;\n\n    /** Resource name. */\n    name: string;\n\n    /** Resource description. */\n    description?: string;\n\n    /** MIME type. */\n    mimeType?: string;\n\n    /** Resource size in bytes, if known. */\n    size?: number;\n\n    /** Resource content. */\n    text?: string;\n\n    /** Binary content in base64 form. */\n    blob?: string;\n}\n\n/** List resources result. */\nexport interface ListResourcesResult extends PaginatedResult {\n    resources: MCPResource[];\n}\n\n/** Resource template. */\nexport interface MCPResourceTemplate {\n    /** URI template. */\n    uriTemplate: string;\n\n    /** Template name. */\n    name: string;\n\n    /** Template description. */\n    description?: string;\n\n    /** MIME type. */\n    mimeType?: string;\n}\n\n/** List resource templates result. */\nexport interface ListResourceTemplatesResult extends PaginatedResult {\n    resourceTemplates: MCPResourceTemplate[];\n}\n\n/** Read resource request. */\nexport interface MCPReadResourceParams {\n    /** Resource URI. */\n    uri: string;\n}\n\n/** Read resource result. */\nexport interface MCPReadResourceResult {\n    contents: MCPResource[];\n}\n\n/** MCP prompt. */\nexport interface MCPPrompt {\n    /** Prompt name. */\n    name: string;\n\n    /** Prompt description. */\n    description?: string;\n\n    /** Prompt arguments schema. */\n    arguments?: Array<{\n        /** Argument name. */\n        name: string;\n        /** Argument description. */\n        description?: string;\n        /** Whether the argument is required. */\n        required?: boolean;\n    }>;\n}\n\n/** List prompts result. */\nexport interface ListPromptsResult extends PaginatedResult {\n    prompts: MCPPrompt[];\n}\n\n/** Get prompt request. */\nexport interface MCPGetPromptParams {\n    /** Prompt name. */\n    name: string;\n\n    /** Prompt arguments. */\n    arguments?: Record<string, string>;\n}\n\n/** Prompt message */\nexport type PromptMessage =\n    | { role: \"user\"; content: { type: \"text\"; text: string } }\n    | { role: \"assistant\"; content: { type: \"text\"; text: string } };\n\n/** Get prompt result */\nexport interface MCPGetPromptResult {\n    /** Prompt description */\n    description?: string;\n\n    /** Prompt messages */\n    messages: PromptMessage[];\n}\n\n/** Request options for MCP operations */\nexport interface RequestOptions {\n    /** Abort signal for cancellation */\n    signal?: AbortSignal;\n\n    /** Timeout in milliseconds */\n    timeout?: number;\n}\n"],"mappings":";;;;;;;AAOA,MAAa,0BAA0B;;AAGvC,MAAa,8BAA8B;CACvC;CACA;CACA;CACA;CACH"}

package/dist/persistence/index.d.mts

@@ -0,0 +1,3 @@
+import { ConversationCursor, ConversationRunStatus, ConversationRuntimeState, ConversationRuntimeStateStore, ConversationStore, InMemoryStreamStoreOptions, LoadConversationParams, LoadedConversation, SaveConversationParams, SaveConversationResult, StreamEvent, StreamStore } from "./types.mjs";
+import { createMemoryConversationRuntimeStateStore, createMemoryConversationStore, createMemoryStreamStore } from "./memory.mjs";
+export { ConversationCursor, ConversationRunStatus, ConversationRuntimeState, ConversationRuntimeStateStore, ConversationStore, InMemoryStreamStoreOptions, LoadConversationParams, LoadedConversation, SaveConversationParams, SaveConversationResult, StreamEvent, StreamStore, createMemoryConversationRuntimeStateStore, createMemoryConversationStore, createMemoryStreamStore };

package/dist/persistence/index.mjs

@@ -0,0 +1,3 @@
+import { createMemoryConversationRuntimeStateStore, createMemoryConversationStore, createMemoryStreamStore } from "./memory.mjs";
+
+export { createMemoryConversationRuntimeStateStore, createMemoryConversationStore, createMemoryStreamStore };

package/dist/persistence/memory.d.mts

@@ -0,0 +1,21 @@
+import { ConversationRuntimeStateStore, ConversationStore, InMemoryStreamStoreOptions, StreamStore } from "./types.mjs";
+
+//#region src/persistence/memory.d.ts
+/**
+ * Creates an in-memory stream store.
+ */
+declare function createMemoryStreamStore(options?: InMemoryStreamStoreOptions): StreamStore;
+/**
+ * Creates an in-memory conversation runtime-state store.
+ */
+declare function createMemoryConversationRuntimeStateStore(): ConversationRuntimeStateStore;
+/**
+ * Creates an in-memory conversation store with optimistic concurrency cursors.
+ *
+ * Useful for local development, tests, and simple single-process deployments.
+ * Data is not persisted across process restarts.
+ */
+declare function createMemoryConversationStore(): ConversationStore<number>;
+//#endregion
+export { createMemoryConversationRuntimeStateStore, createMemoryConversationStore, createMemoryStreamStore };
+//# sourceMappingURL=memory.d.mts.map

package/dist/persistence/memory.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"memory.d.mts","names":[],"sources":["../../src/persistence/memory.ts"],"mappings":";;;;;AAqBA;iBAAgB,uBAAA,CAAwB,OAAA,GAAU,0BAAA,GAA6B,WAAA;;;;iBAqE/D,yCAAA,CAAA,GAA6C,6BAAA;;;;AAA7D;;;iBAuBgB,6BAAA,CAAA,GAAiC,iBAAA"}

package/dist/persistence/memory.mjs

@@ -0,0 +1,107 @@
+import { BetterAgentError } from "@better-agent/shared/errors";
+
+//#region src/persistence/memory.ts
+/**
+* Creates an in-memory stream store.
+*/
+function createMemoryStreamStore(options) {
+	const streams = /* @__PURE__ */ new Map();
+	const wait = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+	const resumePollMs = options?.advanced?.resumePollMs ?? 25;
+	if (!Number.isFinite(resumePollMs) || resumePollMs <= 0) throw BetterAgentError.fromCode("VALIDATION_FAILED", "advanced.resumePollMs must be a positive number.", {
+		context: { resumePollMs },
+		trace: [{ at: "core.persistence.createMemoryStreamStore" }]
+	});
+	return {
+		async open(streamId, meta) {
+			streams.set(streamId, {
+				meta,
+				events: [],
+				active: true
+			});
+		},
+		async append(streamId, event) {
+			const stream = streams.get(streamId);
+			if (!stream) throw new Error(`Stream ${streamId} not found`);
+			stream.events.push(event);
+		},
+		async close(streamId) {
+			const stream = streams.get(streamId);
+			if (stream) stream.active = false;
+		},
+		async *resume(streamId, afterSeq = -1) {
+			let nextSeq = afterSeq;
+			while (true) {
+				const stream = streams.get(streamId);
+				if (!stream) return;
+				let yielded = false;
+				for (const event of stream.events) {
+					if (event.seq <= nextSeq) continue;
+					yielded = true;
+					nextSeq = event.seq;
+					yield event;
+				}
+				if (!stream.active) return;
+				if (!yielded) await wait(resumePollMs);
+			}
+		}
+	};
+}
+/**
+* Creates an in-memory conversation runtime-state store.
+*/
+function createMemoryConversationRuntimeStateStore() {
+	const states = /* @__PURE__ */ new Map();
+	const getKey = (conversationId, agentName) => `${agentName}:${conversationId}`;
+	return {
+		async get({ conversationId, agentName }) {
+			return states.get(getKey(conversationId, agentName)) ?? null;
+		},
+		async set(state) {
+			states.set(getKey(state.conversationId, state.agentName), { ...state });
+		},
+		async clear({ conversationId, agentName }) {
+			states.delete(getKey(conversationId, agentName));
+		}
+	};
+}
+/**
+* Creates an in-memory conversation store with optimistic concurrency cursors.
+*
+* Useful for local development, tests, and simple single-process deployments.
+* Data is not persisted across process restarts.
+*/
+function createMemoryConversationStore() {
+	const conversations = /* @__PURE__ */ new Map();
+	const getConversationKey = (conversationId, agentName) => `${agentName}:${conversationId}`;
+	return {
+		async load({ conversationId, agentName }) {
+			const entry = conversations.get(getConversationKey(conversationId, agentName));
+			return entry ? {
+				items: [...entry.items],
+				cursor: entry.version
+			} : null;
+		},
+		async save({ conversationId, agentName, items, expectedCursor }) {
+			const key = getConversationKey(conversationId, agentName);
+			const entry = conversations.get(key);
+			if (entry && expectedCursor !== void 0 && entry.version !== expectedCursor) throw BetterAgentError.fromCode("CONFLICT", "Conversation was updated in another session.", {
+				context: {
+					conversationId,
+					agentName
+				},
+				trace: [{ at: "core.persistence.createMemoryConversationStore.save" }]
+			});
+			const version = (entry?.version ?? 0) + 1;
+			conversations.set(key, {
+				items: [...items],
+				version
+			});
+			return { cursor: version };
+		}
+	};
+}
+
+//#endregion
+export { createMemoryConversationRuntimeStateStore, createMemoryConversationStore, createMemoryStreamStore };
+//# sourceMappingURL=memory.mjs.map

package/dist/persistence/memory.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"memory.mjs","names":[],"sources":["../../src/persistence/memory.ts"],"sourcesContent":["import { BetterAgentError } from \"@better-agent/shared/errors\";\nimport type { ConversationItem } from \"../providers\";\nimport type {\n    ConversationRuntimeState,\n    ConversationRuntimeStateStore,\n    ConversationStore,\n    InMemoryStreamStoreOptions,\n    StreamEvent,\n    StreamStore,\n} from \"./types\";\n\n// Internal state for one in-memory stream.\ninterface MemoryStreamState {\n    meta: { runId: string };\n    events: StreamEvent[];\n    active: boolean;\n}\n\n/**\n * Creates an in-memory stream store.\n */\nexport function createMemoryStreamStore(options?: InMemoryStreamStoreOptions): StreamStore {\n    const streams = new Map<string, MemoryStreamState>();\n\n    const wait = (ms: number) => new Promise<void>((resolve) => setTimeout(resolve, ms));\n\n    const resumePollMs = options?.advanced?.resumePollMs ?? 25;\n    if (!Number.isFinite(resumePollMs) || resumePollMs <= 0) {\n        throw BetterAgentError.fromCode(\n            \"VALIDATION_FAILED\",\n            \"advanced.resumePollMs must be a positive number.\",\n            {\n                context: { resumePollMs },\n                trace: [{ at: \"core.persistence.createMemoryStreamStore\" }],\n            },\n        );\n    }\n\n    return {\n        async open(streamId: string, meta: { runId: string }): Promise<void> {\n            streams.set(streamId, {\n                meta,\n                events: [],\n                active: true,\n            });\n        },\n\n        async append(streamId: string, event: StreamEvent): Promise<void> {\n            const stream = streams.get(streamId);\n            if (!stream) throw new Error(`Stream ${streamId} not found`);\n            stream.events.push(event);\n        },\n\n        async close(streamId: string): Promise<void> {\n            const stream = streams.get(streamId);\n            if (stream) stream.active = false;\n        },\n\n        async *resume(streamId: string, afterSeq = -1): AsyncIterable<StreamEvent> {\n            let nextSeq = afterSeq;\n\n            while (true) {\n                const stream = streams.get(streamId);\n                if (!stream) {\n                    return;\n                }\n\n                let yielded = false;\n                for (const event of stream.events) {\n                    if (event.seq <= nextSeq) continue;\n                    yielded = true;\n                    nextSeq = event.seq;\n                    yield event;\n                }\n\n                if (!stream.active) {\n                    return;\n                }\n\n                if (!yielded) {\n                    await wait(resumePollMs);\n                }\n            }\n        },\n    };\n}\n\n/**\n * Creates an in-memory conversation runtime-state store.\n */\nexport function createMemoryConversationRuntimeStateStore(): ConversationRuntimeStateStore {\n    const states = new Map<string, ConversationRuntimeState>();\n    const getKey = (conversationId: string, agentName: string) => `${agentName}:${conversationId}`;\n\n    return {\n        async get({ conversationId, agentName }) {\n            return states.get(getKey(conversationId, agentName)) ?? null;\n        },\n        async set(state) {\n            states.set(getKey(state.conversationId, state.agentName), { ...state });\n        },\n        async clear({ conversationId, agentName }) {\n            states.delete(getKey(conversationId, agentName));\n        },\n    };\n}\n\n/**\n * Creates an in-memory conversation store with optimistic concurrency cursors.\n *\n * Useful for local development, tests, and simple single-process deployments.\n * Data is not persisted across process restarts.\n */\nexport function createMemoryConversationStore(): ConversationStore<number> {\n    const conversations = new Map<string, { items: ConversationItem[]; version: number }>();\n    const getConversationKey = (conversationId: string, agentName: string) =>\n        `${agentName}:${conversationId}`;\n\n    return {\n        async load({ conversationId, agentName }) {\n            const entry = conversations.get(getConversationKey(conversationId, agentName));\n            return entry ? { items: [...entry.items], cursor: entry.version } : null;\n        },\n        async save({ conversationId, agentName, items, expectedCursor }) {\n            const key = getConversationKey(conversationId, agentName);\n            const entry = conversations.get(key);\n            if (entry && expectedCursor !== undefined && entry.version !== expectedCursor) {\n                throw BetterAgentError.fromCode(\n                    \"CONFLICT\",\n                    \"Conversation was updated in another session.\",\n                    {\n                        context: { conversationId, agentName },\n                        trace: [{ at: \"core.persistence.createMemoryConversationStore.save\" }],\n                    },\n                );\n            }\n\n            const version = (entry?.version ?? 0) + 1;\n            conversations.set(key, {\n                items: [...items],\n                version,\n            });\n            return { cursor: version };\n        },\n    };\n}\n"],"mappings":";;;;;;AAqBA,SAAgB,wBAAwB,SAAmD;CACvF,MAAM,0BAAU,IAAI,KAAgC;CAEpD,MAAM,QAAQ,OAAe,IAAI,SAAe,YAAY,WAAW,SAAS,GAAG,CAAC;CAEpF,MAAM,eAAe,SAAS,UAAU,gBAAgB;AACxD,KAAI,CAAC,OAAO,SAAS,aAAa,IAAI,gBAAgB,EAClD,OAAM,iBAAiB,SACnB,qBACA,oDACA;EACI,SAAS,EAAE,cAAc;EACzB,OAAO,CAAC,EAAE,IAAI,4CAA4C,CAAC;EAC9D,CACJ;AAGL,QAAO;EACH,MAAM,KAAK,UAAkB,MAAwC;AACjE,WAAQ,IAAI,UAAU;IAClB;IACA,QAAQ,EAAE;IACV,QAAQ;IACX,CAAC;;EAGN,MAAM,OAAO,UAAkB,OAAmC;GAC9D,MAAM,SAAS,QAAQ,IAAI,SAAS;AACpC,OAAI,CAAC,OAAQ,OAAM,IAAI,MAAM,UAAU,SAAS,YAAY;AAC5D,UAAO,OAAO,KAAK,MAAM;;EAG7B,MAAM,MAAM,UAAiC;GACzC,MAAM,SAAS,QAAQ,IAAI,SAAS;AACpC,OAAI,OAAQ,QAAO,SAAS;;EAGhC,OAAO,OAAO,UAAkB,WAAW,IAAgC;GACvE,IAAI,UAAU;AAEd,UAAO,MAAM;IACT,MAAM,SAAS,QAAQ,IAAI,SAAS;AACpC,QAAI,CAAC,OACD;IAGJ,IAAI,UAAU;AACd,SAAK,MAAM,SAAS,OAAO,QAAQ;AAC/B,SAAI,MAAM,OAAO,QAAS;AAC1B,eAAU;AACV,eAAU,MAAM;AAChB,WAAM;;AAGV,QAAI,CAAC,OAAO,OACR;AAGJ,QAAI,CAAC,QACD,OAAM,KAAK,aAAa;;;EAIvC;;;;;AAML,SAAgB,4CAA2E;CACvF,MAAM,yBAAS,IAAI,KAAuC;CAC1D,MAAM,UAAU,gBAAwB,cAAsB,GAAG,UAAU,GAAG;AAE9E,QAAO;EACH,MAAM,IAAI,EAAE,gBAAgB,aAAa;AACrC,UAAO,OAAO,IAAI,OAAO,gBAAgB,UAAU,CAAC,IAAI;;EAE5D,MAAM,IAAI,OAAO;AACb,UAAO,IAAI,OAAO,MAAM,gBAAgB,MAAM,UAAU,EAAE,EAAE,GAAG,OAAO,CAAC;;EAE3E,MAAM,MAAM,EAAE,gBAAgB,aAAa;AACvC,UAAO,OAAO,OAAO,gBAAgB,UAAU,CAAC;;EAEvD;;;;;;;;AASL,SAAgB,gCAA2D;CACvE,MAAM,gCAAgB,IAAI,KAA6D;CACvF,MAAM,sBAAsB,gBAAwB,cAChD,GAAG,UAAU,GAAG;AAEpB,QAAO;EACH,MAAM,KAAK,EAAE,gBAAgB,aAAa;GACtC,MAAM,QAAQ,cAAc,IAAI,mBAAmB,gBAAgB,UAAU,CAAC;AAC9E,UAAO,QAAQ;IAAE,OAAO,CAAC,GAAG,MAAM,MAAM;IAAE,QAAQ,MAAM;IAAS,GAAG;;EAExE,MAAM,KAAK,EAAE,gBAAgB,WAAW,OAAO,kBAAkB;GAC7D,MAAM,MAAM,mBAAmB,gBAAgB,UAAU;GACzD,MAAM,QAAQ,cAAc,IAAI,IAAI;AACpC,OAAI,SAAS,mBAAmB,UAAa,MAAM,YAAY,eAC3D,OAAM,iBAAiB,SACnB,YACA,gDACA;IACI,SAAS;KAAE;KAAgB;KAAW;IACtC,OAAO,CAAC,EAAE,IAAI,uDAAuD,CAAC;IACzE,CACJ;GAGL,MAAM,WAAW,OAAO,WAAW,KAAK;AACxC,iBAAc,IAAI,KAAK;IACnB,OAAO,CAAC,GAAG,MAAM;IACjB;IACH,CAAC;AACF,UAAO,EAAE,QAAQ,SAAS;;EAEjC"}

package/dist/persistence/types.d.mts

@@ -0,0 +1,124 @@
+import { ConversationItem } from "../providers/types/conversation.mjs";
+import { Event } from "../events/types.mjs";
+//#region src/persistence/types.d.ts
+/**
+ * Stores stream events so they can be resumed later.
+ */
+interface StreamStore {
+  /** Start a new stream. */
+  open(streamId: string, meta: {
+    runId: string;
+  }): Promise<void>;
+  /** Save one event into the stream. */
+  append(streamId: string, event: StreamEvent): Promise<void>;
+  /** Mark the stream as finished. */
+  close(streamId: string): Promise<void>;
+  /**
+   * Resume a stream after a given event number.
+   *
+   * Yields historical events after `afterSeq`, then continues live if the
+   * stream is still active. If the stream is already closed, iteration ends
+   * once the stored events are exhausted.
+   */
+  resume(streamId: string, afterSeq?: number): AsyncIterable<StreamEvent>;
+}
+/**
+ * Options for the built-in in-memory stream store.
+ */
+interface InMemoryStreamStoreOptions {
+  advanced?: {
+    /** Poll interval used while waiting for new events during resume. */resumePollMs?: number;
+  };
+}
+/**
+ * One saved event with a stream sequence number.
+ */
+type StreamEvent = Event & {
+  /** Event number inside this stream. */seq: number;
+};
+/**
+ * Loads and saves durable conversation history.
+ */
+interface ConversationStore<TCursor = ConversationCursor> {
+  /** Load saved items for one conversation. */
+  load(params: LoadConversationParams): Promise<LoadedConversation<TCursor> | null>;
+  /** Save updated items back to the conversation store. */
+  save(params: SaveConversationParams<TCursor>): Promise<SaveConversationResult<TCursor>>;
+}
+/**
+ * Opaque cursor used for optimistic concurrency in conversation stores.
+ */
+type ConversationCursor = string | number;
+/**
+ * Saved conversation items plus an optional cursor.
+ */
+interface LoadedConversation<TCursor = ConversationCursor> {
+  /** Saved conversation items. */
+  items: ConversationItem[];
+  /** Cursor used for optimistic concurrency. */
+  cursor?: TCursor;
+}
+/**
+ * Data needed to load a saved conversation.
+ */
+interface LoadConversationParams {
+  /** Conversation to load. */
+  conversationId: string;
+  /** Agent that owns this conversation history. */
+  agentName: string;
+}
+/**
+ * Data needed to save a conversation safely.
+ */
+interface SaveConversationParams<TCursor = ConversationCursor> {
+  /** Conversation to update. */
+  conversationId: string;
+  /** Agent that owns this conversation history. */
+  agentName: string;
+  /** Full durable item list to save. */
+  items: ConversationItem[];
+  /** Expected current cursor. Save should fail if it changed. */
+  expectedCursor?: TCursor;
+}
+/**
+ * Result returned after a successful save.
+ */
+interface SaveConversationResult<TCursor = ConversationCursor> {
+  /** New cursor after the save. */
+  cursor: TCursor;
+}
+/**
+ * Runtime status for a conversation-scoped run.
+ */
+type ConversationRunStatus = "running" | "finished" | "failed" | "aborted";
+/**
+ * App-owned runtime state used to look up the active stream for a conversation.
+ */
+interface ConversationRuntimeState {
+  /** Conversation this state belongs to. */
+  conversationId: string;
+  /** Agent that owns this conversation. */
+  agentName: string;
+  /** Currently active run id, when one exists. */
+  activeRunId?: string;
+  /** Currently active stream id, when one exists. */
+  activeStreamId?: string;
+  /** Last known runtime status for the conversation. */
+  status: ConversationRunStatus;
+  /** Millisecond timestamp of the latest state update. */
+  updatedAt: number;
+}
+/**
+ * Optional store for active run or active stream lookup by conversation.
+ */
+interface ConversationRuntimeStateStore {
+  /** Load the latest runtime state for a conversation. */
+  get(params: LoadConversationParams): Promise<ConversationRuntimeState | null>;
+  /** Save the latest runtime state for a conversation. */
+  set(state: ConversationRuntimeState): Promise<void>;
+  /** Clear any active runtime state for a conversation. */
+  clear(params: LoadConversationParams): Promise<void>;
+}
+//#endregion
+export { ConversationCursor, ConversationRunStatus, ConversationRuntimeState, ConversationRuntimeStateStore, ConversationStore, InMemoryStreamStoreOptions, LoadConversationParams, LoadedConversation, SaveConversationParams, SaveConversationResult, StreamEvent, StreamStore };
+//# sourceMappingURL=types.d.mts.map

package/dist/persistence/types.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.mts","names":[],"sources":["../../src/persistence/types.ts"],"mappings":";;;;;;UAMiB,WAAA;EAAA;EAEb,IAAA,CAAK,QAAA,UAAkB,IAAA;IAAQ,KAAA;EAAA,IAAkB,OAAA;EAEjB;EAAhC,MAAA,CAAO,QAAA,UAAkB,KAAA,EAAO,WAAA,GAAc,OAAA;EAErB;EAAzB,KAAA,CAAM,QAAA,WAAmB,OAAA;EAQoB;;;;;;;EAA7C,MAAA,CAAO,QAAA,UAAkB,QAAA,YAAoB,aAAA,CAAc,WAAA;AAAA;;;;UAM9C,0BAAA;EACb,QAAA;IAfM,qEAiBF,YAAA;EAAA;AAAA;;;;KAOI,WAAA,GAAc,KAAA;EAhBgD,uCAkBtE,GAAA;AAAA;;;;UAMa,iBAAA,WAA4B,kBAAA;EARtB;EAUnB,IAAA,CAAK,MAAA,EAAQ,sBAAA,GAAyB,OAAA,CAAQ,kBAAA,CAAmB,OAAA;EAV3C;EAYtB,IAAA,CAAK,MAAA,EAAQ,sBAAA,CAAuB,OAAA,IAAW,OAAA,CAAQ,sBAAA,CAAuB,OAAA;AAAA;;;;KAMtE,kBAAA;;;;UAKK,kBAAA,WAA6B,kBAAA;EAX7B;EAab,KAAA,EAAO,gBAAA;EAbgD;EAevD,MAAA,GAAS,OAAA;AAAA;;;;UAMI,sBAAA;EAvBA;EAyBb,cAAA;EAzBsC;EA2BtC,SAAA;AAAA;;;;UAMa,sBAAA,WAAiC,kBAAA;EA/BC;EAiC/C,cAAA;EAjC8E;EAmC9E,SAAA;EAnCqF;EAqCrF,KAAA,EAAO,gBAAA;EA/BmB;EAiC1B,cAAA,GAAiB,OAAA;AAAA;;AA5BrB;;UAkCiB,sBAAA,WAAiC,kBAAA;EAlCJ;EAoC1C,MAAA,EAAQ,OAAA;AAAA;;;;KAMA,qBAAA;;;;UAKK,wBAAA;EA3CG;EA6ChB,cAAA;EAvCa;EAyCb,SAAA;;EAEA,WAAA;EAvCS;EAyCT,cAAA;EAnCmC;EAqCnC,MAAA,EAAQ,qBAAA;EArCsC;EAuC9C,SAAA;AAAA;;;;UAMa,6BAAA;EA3Cb;EA6CA,GAAA,CAAI,MAAA,EAAQ,sBAAA,GAAyB,OAAA,CAAQ,wBAAA;EAzC7C;EA2CA,GAAA,CAAI,KAAA,EAAO,wBAAA,GAA2B,OAAA;EAzCtC;EA2CA,KAAA,CAAM,MAAA,EAAQ,sBAAA,GAAyB,OAAA;AAAA"}

package/dist/plugins/index.d.mts

@@ -0,0 +1,2 @@
+import { Plugin, PluginBaseContext, PluginEndpoint, PluginEndpointHandler, PluginEventContext, PluginEventMiddleware, PluginGuard, PluginGuardMode, PluginModelCallContext, PluginModelResponseContext, PluginOnStepContext, PluginRunContext, PluginRuntime, PluginRuntimeEndpoint, PluginSaveContext, PluginToolCallContext, PluginToolCallDecision, PluginToolResultContext } from "./types.mjs";
+import { definePlugin } from "./runtime.mjs";

package/dist/plugins/runtime.d.mts

@@ -0,0 +1,17 @@
+import { Plugin } from "./types.mjs";
+
+//#region src/plugins/runtime.d.ts
+/**
+ * Defines a plugin.
+ *
+ * Plugin hook contexts are intentionally broad at authoring time. Some
+ * capability-sensitive controls may be omitted at runtime for models that do
+ * not support them.
+ *
+ * @param config Plugin configuration.
+ * @returns The plugin definition with preserved literal types.
+ */
+declare function definePlugin<const T extends Plugin>(config: T): T;
+//#endregion
+export { definePlugin };
+//# sourceMappingURL=runtime.d.mts.map

package/dist/plugins/runtime.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"runtime.d.mts","names":[],"sources":["../../src/plugins/runtime.ts"],"mappings":";;;;;AAsCA;;;;;;;;iBAAgB,YAAA,iBAA6B,MAAA,CAAA,CAAQ,MAAA,EAAQ,CAAA,GAAI,CAAA"}