@elizaos/core 2.0.0-alpha.21 → 2.0.0-alpha.22

package/dist/services.d.ts

@@ -0,0 +1,61 @@
+import type { IAgentRuntime, ServiceTypeName } from "./types";
+import { Service } from "./types";
+/**
+ * Type for the service class returned by the builder.
+ * This provides the expected interface for dynamically created service classes.
+ * This is a more specific generic version of the base ServiceClass from types/plugin.ts
+ */
+export interface TypedServiceBuilder<TService extends Service = Service> {
+    new (runtime?: IAgentRuntime): TService;
+    serviceType: ServiceTypeName;
+    start(runtime: IAgentRuntime): Promise<TService>;
+}
+/**
+ * Service builder class that provides type-safe service creation
+ * with automatic type inference
+ */
+export declare class ServiceBuilder<TService extends Service = Service> {
+    protected serviceType: ServiceTypeName | string;
+    protected startFn: (runtime: IAgentRuntime) => Promise<TService>;
+    protected stopFn?: () => Promise<void>;
+    protected description: string;
+    constructor(serviceType: ServiceTypeName | string);
+    /**
+     * Set the service description
+     */
+    withDescription(description: string): this;
+    /**
+     * Set the start function for the service
+     */
+    withStart(startFn: (runtime: IAgentRuntime) => Promise<TService>): this;
+    /**
+     * Set the stop function for the service
+     */
+    withStop(stopFn: () => Promise<void>): this;
+    /**
+     * Build the service class with all configured properties.
+     * Returns a properly typed service class constructor.
+     */
+    build(): TypedServiceBuilder<TService>;
+}
+/**
+ * Create a type-safe service builder
+ * @param serviceType - The service type name
+ * @returns A new ServiceBuilder instance
+ */
+export declare function createService<TService extends Service = Service>(serviceType: ServiceTypeName | string): ServiceBuilder<TService>;
+/**
+ * Type-safe service definition helper
+ */
+export interface ServiceDefinition<T extends Service = Service> {
+    serviceType: ServiceTypeName;
+    description: string;
+    start: (runtime: IAgentRuntime) => Promise<T>;
+    stop?: () => Promise<void>;
+}
+/**
+ * Define a service with type safety.
+ * Returns a TypedServiceBuilder that can be instantiated and started.
+ */
+export declare function defineService<T extends Service = Service>(definition: ServiceDefinition<T>): TypedServiceBuilder<T>;
+//# sourceMappingURL=services.d.ts.map

package/dist/services.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"services.d.ts","sourceRoot":"","sources":["../src/services.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,eAAe,EAAE,MAAM,SAAS,CAAC;AAC9D,OAAO,EAAE,OAAO,EAAE,MAAM,SAAS,CAAC;AAKlC;;;;GAIG;AACH,MAAM,WAAW,mBAAmB,CAAC,QAAQ,SAAS,OAAO,GAAG,OAAO;IACtE,KAAK,OAAO,CAAC,EAAE,aAAa,GAAG,QAAQ,CAAC;IACxC,WAAW,EAAE,eAAe,CAAC;IAC7B,KAAK,CAAC,OAAO,EAAE,aAAa,GAAG,OAAO,CAAC,QAAQ,CAAC,CAAC;CACjD;AAED;;;GAGG;AACH,qBAAa,cAAc,CAAC,QAAQ,SAAS,OAAO,GAAG,OAAO;IAC7D,SAAS,CAAC,WAAW,EAAE,eAAe,GAAG,MAAM,CAAC;IAChD,SAAS,CAAC,OAAO,EAAG,CAAC,OAAO,EAAE,aAAa,KAAK,OAAO,CAAC,QAAQ,CAAC,CAAC;IAClE,SAAS,CAAC,MAAM,CAAC,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;IACvC,SAAS,CAAC,WAAW,EAAE,MAAM,CAAC;gBAElB,WAAW,EAAE,eAAe,GAAG,MAAM;IAKjD;;OAEG;IACH,eAAe,CAAC,WAAW,EAAE,MAAM,GAAG,IAAI;IAK1C;;OAEG;IACH,SAAS,CAAC,OAAO,EAAE,CAAC,OAAO,EAAE,aAAa,KAAK,OAAO,CAAC,QAAQ,CAAC,GAAG,IAAI;IAKvE;;OAEG;IACH,QAAQ,CAAC,MAAM,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI;IAK3C;;;OAGG;IACH,KAAK,IAAI,mBAAmB,CAAC,QAAQ,CAAC;CAgDtC;AAED;;;;GAIG;AACH,wBAAgB,aAAa,CAAC,QAAQ,SAAS,OAAO,GAAG,OAAO,EAC/D,WAAW,EAAE,eAAe,GAAG,MAAM,GACnC,cAAc,CAAC,QAAQ,CAAC,CAE1B;AAED;;GAEG;AACH,MAAM,WAAW,iBAAiB,CAAC,CAAC,SAAS,OAAO,GAAG,OAAO;IAC7D,WAAW,EAAE,eAAe,CAAC;IAC7B,WAAW,EAAE,MAAM,CAAC;IACpB,KAAK,EAAE,CAAC,OAAO,EAAE,aAAa,KAAK,OAAO,CAAC,CAAC,CAAC,CAAC;IAC9C,IAAI,CAAC,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;CAC3B;AAED;;;GAGG;AACH,wBAAgB,aAAa,CAAC,CAAC,SAAS,OAAO,GAAG,OAAO,EACxD,UAAU,EAAE,iBAAiB,CAAC,CAAC,CAAC,GAC9B,mBAAmB,CAAC,CAAC,CAAC,CAMxB"}

package/dist/sessions/index.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Session management utilities for elizaOS.
+ *
+ * Provides:
+ * - Session key building and parsing
+ * - Session types and data structures
+ * - Session storage with caching and locking
+ * - Session path resolution
+ * - Agent/peer/thread session management
+ * - Identity linking for cross-platform users
+ *
+ * @module sessions
+ */
+export { buildAcpSessionKey, buildAgentMainSessionKey, buildAgentPeerSessionKey, buildAgentSessionKey, buildGroupHistoryKey, buildSubagentSessionKey, DEFAULT_ACCOUNT_ID, DEFAULT_AGENT_ID, DEFAULT_MAIN_KEY, isAcpSessionKey, isSubagentSessionKey, normalizeAccountId, normalizeAgentId, normalizeMainKey, type ParsedAgentSessionKey, parseAgentSessionKey, resolveAgentIdFromSessionKey, resolveThreadParentSessionKey, resolveThreadSessionKeys, sanitizeAgentId, toAgentRequestSessionKey, toAgentStoreSessionKey, } from "./session-key.js";
+export { createSessionEntry, DEFAULT_IDLE_MINUTES, DEFAULT_RESET_TRIGGER, DEFAULT_RESET_TRIGGERS, type GroupKeyResolution, isValidSessionEntry, mergeSessionEntry, type SessionChatType, type SessionDeliveryContext, type SessionEntry, type SessionResolution, type SessionStore, } from "./types.js";
+export { clearSessionStoreCacheForTest, deleteSessionEntry, getSessionEntry, getSessionEntryById, type LoadSessionStoreOptions, listSessionKeys, listSessions, loadSessionStore, readSessionUpdatedAt, saveSessionStore, updateSessionStore, updateSessionStoreEntry, upsertSessionEntry, } from "./store.js";
+export { ensureSafeSessionPath, isWithinStateDir, resolveAgentSessionsDir, resolveDefaultSessionStorePath, resolveSessionFilePath, resolveSessionTranscriptPath, resolveSessionTranscriptsDir, resolveSessionTranscriptsDirForAgent, resolveStateDir, resolveStorePath, } from "./paths.js";
+export { createSendPolicyProvider, createSessionProvider, createSessionSkillsProvider, extractSessionContext, getSessionProviders, SessionStateManager, } from "./provider.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/sessions/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/sessions/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAMH,OAAO,EACN,kBAAkB,EAClB,wBAAwB,EACxB,wBAAwB,EACxB,oBAAoB,EACpB,oBAAoB,EACpB,uBAAuB,EACvB,kBAAkB,EAClB,gBAAgB,EAChB,gBAAgB,EAChB,eAAe,EACf,oBAAoB,EACpB,kBAAkB,EAClB,gBAAgB,EAChB,gBAAgB,EAChB,KAAK,qBAAqB,EAC1B,oBAAoB,EACpB,4BAA4B,EAC5B,6BAA6B,EAC7B,wBAAwB,EACxB,eAAe,EACf,wBAAwB,EACxB,sBAAsB,GACtB,MAAM,kBAAkB,CAAC;AAW1B,OAAO,EACN,kBAAkB,EAClB,oBAAoB,EACpB,qBAAqB,EACrB,sBAAsB,EACtB,KAAK,kBAAkB,EACvB,mBAAmB,EACnB,iBAAiB,EACjB,KAAK,eAAe,EACpB,KAAK,sBAAsB,EAC3B,KAAK,YAAY,EACjB,KAAK,iBAAiB,EACtB,KAAK,YAAY,GACjB,MAAM,YAAY,CAAC;AAMpB,OAAO,EACN,6BAA6B,EAC7B,kBAAkB,EAClB,eAAe,EACf,mBAAmB,EACnB,KAAK,uBAAuB,EAC5B,eAAe,EACf,YAAY,EACZ,gBAAgB,EAChB,oBAAoB,EACpB,gBAAgB,EAChB,kBAAkB,EAClB,uBAAuB,EACvB,kBAAkB,GAClB,MAAM,YAAY,CAAC;AAMpB,OAAO,EACN,qBAAqB,EACrB,gBAAgB,EAChB,uBAAuB,EACvB,8BAA8B,EAC9B,sBAAsB,EACtB,4BAA4B,EAC5B,4BAA4B,EAC5B,oCAAoC,EACpC,eAAe,EACf,gBAAgB,GAChB,MAAM,YAAY,CAAC;AAMpB,OAAO,EACN,wBAAwB,EACxB,qBAAqB,EACrB,2BAA2B,EAC3B,qBAAqB,EACrB,mBAAmB,EACnB,mBAAmB,GACnB,MAAM,eAAe,CAAC"}

package/dist/sessions/paths.d.ts

@@ -0,0 +1,106 @@
+/**
+ * Session path utilities for elizaOS.
+ *
+ * Provides functions for resolving session-related file paths including
+ * session stores, transcripts, and agent-specific directories.
+ *
+ * @module sessions/paths
+ */
+import type { SessionEntry } from "./types.js";
+/**
+ * Resolve the Eliza state directory.
+ *
+ * Uses ELIZA_STATE_DIR env var, falling back to ~/.eliza
+ *
+ * @param env - Environment variables (defaults to process.env)
+ * @param homedir - Homedir function (defaults to os.homedir)
+ * @returns Absolute path to state directory
+ */
+export declare function resolveStateDir(env?: NodeJS.ProcessEnv, homedir?: () => string): string;
+/**
+ * Resolve the sessions directory for an agent.
+ *
+ * @param agentId - Agent identifier (defaults to "main")
+ * @param env - Environment variables
+ * @param homedir - Homedir function
+ * @returns Absolute path to agent sessions directory
+ */
+export declare function resolveAgentSessionsDir(agentId?: string, env?: NodeJS.ProcessEnv, homedir?: () => string): string;
+/**
+ * Resolve the transcripts directory for the default agent.
+ *
+ * @param env - Environment variables
+ * @param homedir - Homedir function
+ * @returns Absolute path to transcripts directory
+ */
+export declare function resolveSessionTranscriptsDir(env?: NodeJS.ProcessEnv, homedir?: () => string): string;
+/**
+ * Resolve the transcripts directory for a specific agent.
+ *
+ * @param agentId - Agent identifier
+ * @param env - Environment variables
+ * @param homedir - Homedir function
+ * @returns Absolute path to agent transcripts directory
+ */
+export declare function resolveSessionTranscriptsDirForAgent(agentId?: string, env?: NodeJS.ProcessEnv, homedir?: () => string): string;
+/**
+ * Resolve the default session store path for an agent.
+ *
+ * @param agentId - Agent identifier (defaults to "main")
+ * @returns Absolute path to sessions.json
+ */
+export declare function resolveDefaultSessionStorePath(agentId?: string): string;
+/**
+ * Resolve a session store path with optional template expansion.
+ *
+ * Supports:
+ * - `{agentId}` placeholder in path
+ * - `~` expansion for home directory
+ * - Defaults to standard sessions.json location
+ *
+ * @param store - Custom store path (optional)
+ * @param opts - Options including agentId
+ * @returns Resolved absolute path
+ */
+export declare function resolveStorePath(store?: string, opts?: {
+    agentId?: string;
+}): string;
+/**
+ * Resolve the path to a session transcript file.
+ *
+ * @param sessionId - Session identifier
+ * @param agentId - Agent identifier (defaults to "main")
+ * @param topicId - Optional topic ID for topic-specific transcripts
+ * @returns Absolute path to transcript .jsonl file
+ */
+export declare function resolveSessionTranscriptPath(sessionId: string, agentId?: string, topicId?: string | number): string;
+/**
+ * Resolve the path to a session file.
+ *
+ * Uses the entry's sessionFile if set, otherwise falls back to
+ * the default transcript path.
+ *
+ * @param sessionId - Session identifier
+ * @param entry - Optional session entry with sessionFile
+ * @param opts - Options including agentId
+ * @returns Absolute path to session file
+ */
+export declare function resolveSessionFilePath(sessionId: string, entry?: SessionEntry, opts?: {
+    agentId?: string;
+}): string;
+/**
+ * Check if a path is within the Eliza state directory.
+ *
+ * @param filePath - Path to check
+ * @returns True if path is within state directory
+ */
+export declare function isWithinStateDir(filePath: string): boolean;
+/**
+ * Ensure a path is safe to use for session storage.
+ *
+ * @param filePath - Path to validate
+ * @returns Resolved path if safe
+ * @throws Error if path is outside state directory
+ */
+export declare function ensureSafeSessionPath(filePath: string): string;
+//# sourceMappingURL=paths.d.ts.map

package/dist/sessions/paths.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"paths.d.ts","sourceRoot":"","sources":["../../src/sessions/paths.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAKH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAM/C;;;;;;;;GAQG;AACH,wBAAgB,eAAe,CAC9B,GAAG,GAAE,MAAM,CAAC,UAAwB,EACpC,OAAO,GAAE,MAAM,MAAmB,GAChC,MAAM,CASR;AAMD;;;;;;;GAOG;AACH,wBAAgB,uBAAuB,CACtC,OAAO,CAAC,EAAE,MAAM,EAChB,GAAG,GAAE,MAAM,CAAC,UAAwB,EACpC,OAAO,GAAE,MAAM,MAAmB,GAChC,MAAM,CAIR;AAED;;;;;;GAMG;AACH,wBAAgB,4BAA4B,CAC3C,GAAG,GAAE,MAAM,CAAC,UAAwB,EACpC,OAAO,GAAE,MAAM,MAAmB,GAChC,MAAM,CAER;AAED;;;;;;;GAOG;AACH,wBAAgB,oCAAoC,CACnD,OAAO,CAAC,EAAE,MAAM,EAChB,GAAG,GAAE,MAAM,CAAC,UAAwB,EACpC,OAAO,GAAE,MAAM,MAAmB,GAChC,MAAM,CAER;AAMD;;;;;GAKG;AACH,wBAAgB,8BAA8B,CAAC,OAAO,CAAC,EAAE,MAAM,GAAG,MAAM,CAEvE;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,gBAAgB,CAC/B,KAAK,CAAC,EAAE,MAAM,EACd,IAAI,CAAC,EAAE;IAAE,OAAO,CAAC,EAAE,MAAM,CAAA;CAAE,GACzB,MAAM,CAoBR;AAMD;;;;;;;GAOG;AACH,wBAAgB,4BAA4B,CAC3C,SAAS,EAAE,MAAM,EACjB,OAAO,CAAC,EAAE,MAAM,EAChB,OAAO,CAAC,EAAE,MAAM,GAAG,MAAM,GACvB,MAAM,CAcR;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,sBAAsB,CACrC,SAAS,EAAE,MAAM,EACjB,KAAK,CAAC,EAAE,YAAY,EACpB,IAAI,CAAC,EAAE;IAAE,OAAO,CAAC,EAAE,MAAM,CAAA;CAAE,GACzB,MAAM,CAKR;AAMD;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAI1D;AAED;;;;;;GAMG;AACH,wBAAgB,qBAAqB,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAiB9D"}

package/dist/sessions/provider.d.ts

@@ -0,0 +1,102 @@
+/**
+ * Session provider for elizaOS runtime.
+ *
+ * Exposes session context to agents during message processing.
+ *
+ * @module sessions/provider
+ */
+import type { Provider } from "../types/components.js";
+import type { Memory } from "../types/memory.js";
+import type { SessionEntry, SessionStore } from "./types.js";
+/**
+ * Extract session context from a memory object.
+ *
+ * Looks for session information in:
+ * 1. memory.sessionId / memory.sessionKey
+ * 2. memory.metadata.session
+ * 3. memory.metadata.sessionId / memory.metadata.sessionKey
+ *
+ * @param memory - Memory to extract session from
+ * @returns Session context or null
+ */
+export declare function extractSessionContext(memory: Memory): {
+    sessionId?: string;
+    sessionKey?: string;
+    entry?: SessionEntry;
+} | null;
+/**
+ * Create a session provider that exposes session context.
+ *
+ * @param options - Provider options
+ * @returns Provider instance
+ */
+export declare function createSessionProvider(options?: {
+    /** Path to session store (defaults to runtime's configured store) */
+    storePath?: string;
+    /** Custom name for the provider */
+    name?: string;
+}): Provider;
+/**
+ * Create a provider that exposes session skills.
+ *
+ * @param options - Provider options
+ * @returns Provider instance
+ */
+export declare function createSessionSkillsProvider(options?: {
+    storePath?: string;
+    name?: string;
+}): Provider;
+/**
+ * Create a provider that enforces session send policy.
+ *
+ * When sendPolicy is "deny", adds strong guidance to prevent
+ * the agent from sending external messages.
+ *
+ * @param options - Provider options
+ * @returns Provider instance
+ */
+export declare function createSendPolicyProvider(options?: {
+    storePath?: string;
+    name?: string;
+}): Provider;
+/**
+ * Get all default session providers.
+ *
+ * @param options - Provider options
+ * @returns Array of session providers
+ */
+export declare function getSessionProviders(options?: {
+    storePath?: string;
+}): Provider[];
+/**
+ * Session state manager for runtime integration.
+ *
+ * Provides methods to access and update session state
+ * during message processing.
+ */
+export declare class SessionStateManager {
+    private readonly storePath;
+    private store;
+    private lastLoadTime;
+    private readonly cacheTtlMs;
+    constructor(storePath: string, options?: {
+        cacheTtlMs?: number;
+    });
+    /**
+     * Get the session store, loading if necessary.
+     */
+    getStore(): SessionStore;
+    /**
+     * Get a session entry by key.
+     */
+    getEntry(sessionKey: string): SessionEntry | undefined;
+    /**
+     * Get a session entry by ID.
+     */
+    getEntryById(sessionId: string): SessionEntry | undefined;
+    /**
+     * Invalidate the cached store.
+     */
+    invalidate(): void;
+}
+//# sourceMappingURL=provider.d.ts.map

package/dist/sessions/provider.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"provider.d.ts","sourceRoot":"","sources":["../../src/sessions/provider.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,QAAQ,EAAkB,MAAM,wBAAwB,CAAC;AACvE,OAAO,KAAK,EAAE,MAAM,EAAkB,MAAM,oBAAoB,CAAC;AAIjE,OAAO,KAAK,EAAE,YAAY,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAM7D;;;;;;;;;;GAUG;AACH,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,MAAM,GAAG;IACtD,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,KAAK,CAAC,EAAE,YAAY,CAAC;CACrB,GAAG,IAAI,CA0BP;AAMD;;;;;GAKG;AACH,wBAAgB,qBAAqB,CAAC,OAAO,CAAC,EAAE;IAC/C,qEAAqE;IACrE,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,mCAAmC;IACnC,IAAI,CAAC,EAAE,MAAM,CAAC;CACd,GAAG,QAAQ,CA0EX;AAMD;;;;;GAKG;AACH,wBAAgB,2BAA2B,CAAC,OAAO,CAAC,EAAE;IACrD,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,IAAI,CAAC,EAAE,MAAM,CAAC;CACd,GAAG,QAAQ,CAqDX;AAMD;;;;;;;;GAQG;AACH,wBAAgB,wBAAwB,CAAC,OAAO,CAAC,EAAE;IAClD,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,IAAI,CAAC,EAAE,MAAM,CAAC;CACd,GAAG,QAAQ,CA8DX;AAMD;;;;;GAKG;AACH,wBAAgB,mBAAmB,CAAC,OAAO,CAAC,EAAE;IAC7C,SAAS,CAAC,EAAE,MAAM,CAAC;CACnB,GAAG,QAAQ,EAAE,CAMb;AAMD;;;;;GAKG;AACH,qBAAa,mBAAmB;IAM9B,OAAO,CAAC,QAAQ,CAAC,SAAS;IAL3B,OAAO,CAAC,KAAK,CAA6B;IAC1C,OAAO,CAAC,YAAY,CAAK;IACzB,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAS;gBAGlB,SAAS,EAAE,MAAM,EAClC,OAAO,CAAC,EAAE;QAAE,UAAU,CAAC,EAAE,MAAM,CAAA;KAAE;IAKlC;;OAEG;IACH,QAAQ,IAAI,YAAY;IASxB;;OAEG;IACH,QAAQ,CAAC,UAAU,EAAE,MAAM,GAAG,YAAY,GAAG,SAAS;IAItD;;OAEG;IACH,YAAY,CAAC,SAAS,EAAE,MAAM,GAAG,YAAY,GAAG,SAAS;IAKzD;;OAEG;IACH,UAAU,IAAI,IAAI;CAIlB"}

package/dist/sessions/session-key.d.ts

@@ -0,0 +1,201 @@
+/**
+ * Session key utilities for elizaOS.
+ *
+ * Provides functions for building, parsing, and normalizing session keys
+ * used to identify agent sessions, threads, and peer connections.
+ *
+ * Session keys follow the format: agent:{agentId}:{rest}
+ *
+ * @module sessions/session-key
+ */
+export declare const DEFAULT_AGENT_ID = "main";
+export declare const DEFAULT_MAIN_KEY = "main";
+export declare const DEFAULT_ACCOUNT_ID = "default";
+/**
+ * Parsed agent session key components.
+ */
+export type ParsedAgentSessionKey = {
+    /** The full original session key */
+    raw: string;
+    /** Agent ID extracted from the key */
+    agentId: string;
+    /** The remainder of the key after agent:{agentId}: */
+    rest: string;
+    /** Whether this is an ACP (Agent Communication Protocol) session */
+    isAcp: boolean;
+    /** Whether this is a subagent session */
+    isSubagent: boolean;
+    /** Thread ID if present */
+    threadId?: string;
+    /** Parent session key if this is a thread */
+    parentKey?: string;
+};
+/**
+ * Parse an agent session key into its components.
+ *
+ * Session keys follow the format:
+ * - agent:{agentId}:{rest}
+ * - agent:{agentId}:acp:{...}
+ * - agent:{agentId}:subagent:{subagentId}:{...}
+ * - agent:{agentId}:{...}:thread:{threadId}
+ *
+ * @param sessionKey - The session key to parse
+ * @returns Parsed components or null if invalid
+ */
+export declare function parseAgentSessionKey(sessionKey: string | undefined | null): ParsedAgentSessionKey | null;
+/**
+ * Check if a session key is an ACP session.
+ *
+ * @param sessionKey - The session key to check
+ * @returns True if this is an ACP session
+ */
+export declare function isAcpSessionKey(sessionKey: string | undefined | null): boolean;
+/**
+ * Check if a session key is a subagent session.
+ *
+ * @param sessionKey - The session key to check
+ * @returns True if this is a subagent session
+ */
+export declare function isSubagentSessionKey(sessionKey: string | undefined | null): boolean;
+/**
+ * Resolve the parent session key for a thread session.
+ *
+ * @param sessionKey - The session key to resolve
+ * @returns Parent session key or the original key if not a thread
+ */
+export declare function resolveThreadParentSessionKey(sessionKey: string | undefined | null): string | null;
+/**
+ * Normalize a main key value.
+ *
+ * @param value - Value to normalize
+ * @returns Normalized main key
+ */
+export declare function normalizeMainKey(value: string | undefined | null): string;
+/**
+ * Normalize an agent ID.
+ *
+ * Ensures the ID is path-safe and shell-friendly.
+ *
+ * @param value - Value to normalize
+ * @returns Normalized agent ID
+ */
+export declare function normalizeAgentId(value: string | undefined | null): string;
+/**
+ * Sanitize an agent ID (alias for normalizeAgentId).
+ *
+ * @param value - Value to sanitize
+ * @returns Sanitized agent ID
+ */
+export declare function sanitizeAgentId(value: string | undefined | null): string;
+/**
+ * Normalize an account ID.
+ *
+ * @param value - Value to normalize
+ * @returns Normalized account ID
+ */
+export declare function normalizeAccountId(value: string | undefined | null): string;
+/**
+ * Build an agent session key from components.
+ *
+ * @param agentId - The agent ID
+ * @param rest - The rest of the key
+ * @returns Formatted session key
+ */
+export declare function buildAgentSessionKey(agentId: string, rest: string): string;
+/**
+ * Build the main session key for an agent.
+ *
+ * @param params - Session key parameters
+ * @returns Main session key
+ */
+export declare function buildAgentMainSessionKey(params: {
+    agentId: string;
+    mainKey?: string | undefined;
+}): string;
+/**
+ * Build an ACP session key.
+ *
+ * @param agentId - The agent ID
+ * @param acpKey - The ACP-specific key portion
+ * @returns Formatted ACP session key
+ */
+export declare function buildAcpSessionKey(agentId: string, acpKey: string): string;
+/**
+ * Build a subagent session key.
+ *
+ * @param agentId - The parent agent ID
+ * @param subagentId - The subagent ID
+ * @param rest - Additional key portion
+ * @returns Formatted subagent session key
+ */
+export declare function buildSubagentSessionKey(agentId: string, subagentId: string, rest?: string): string;
+/**
+ * Build a peer session key for an agent.
+ *
+ * @param params - Peer session parameters
+ * @returns Peer session key
+ */
+export declare function buildAgentPeerSessionKey(params: {
+    agentId: string;
+    mainKey?: string | undefined;
+    channel: string;
+    accountId?: string | null;
+    peerKind?: "dm" | "group" | "channel" | null;
+    peerId?: string | null;
+    identityLinks?: Record<string, string[]>;
+    /** DM session scope. */
+    dmScope?: "main" | "per-peer" | "per-channel-peer" | "per-account-channel-peer";
+}): string;
+/**
+ * Convert a store session key to a request session key.
+ *
+ * @param storeKey - Store session key
+ * @returns Request session key or undefined
+ */
+export declare function toAgentRequestSessionKey(storeKey: string | undefined | null): string | undefined;
+/**
+ * Convert a request session key to a store session key.
+ *
+ * @param params - Conversion parameters
+ * @returns Store session key
+ */
+export declare function toAgentStoreSessionKey(params: {
+    agentId: string;
+    requestKey: string | undefined | null;
+    mainKey?: string | undefined;
+}): string;
+/**
+ * Resolve the agent ID from a session key.
+ *
+ * @param sessionKey - Session key to parse
+ * @returns Resolved agent ID
+ */
+export declare function resolveAgentIdFromSessionKey(sessionKey: string | undefined | null): string;
+/**
+ * Build a group history key.
+ *
+ * @param params - History key parameters
+ * @returns Group history key
+ */
+export declare function buildGroupHistoryKey(params: {
+    channel: string;
+    accountId?: string | null;
+    peerKind: "group" | "channel";
+    peerId: string;
+}): string;
+/**
+ * Resolve thread session keys.
+ *
+ * @param params - Thread resolution parameters
+ * @returns Session key and optional parent session key
+ */
+export declare function resolveThreadSessionKeys(params: {
+    baseSessionKey: string;
+    threadId?: string | null;
+    parentSessionKey?: string;
+    useSuffix?: boolean;
+}): {
+    sessionKey: string;
+    parentSessionKey?: string;
+};
+//# sourceMappingURL=session-key.d.ts.map

package/dist/sessions/session-key.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"session-key.d.ts","sourceRoot":"","sources":["../../src/sessions/session-key.ts"],"names":[],"mappings":"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"}

package/dist/sessions/store.d.ts

@@ -0,0 +1,116 @@
+/**
+ * Session store for elizaOS.
+ *
+ * Provides file-based session storage with caching, locking, and
+ * atomic updates. Designed to be used as the primary session
+ * persistence layer.
+ *
+ * @module sessions/store
+ */
+import { type SessionEntry, type SessionStore } from "./types.js";
+/**
+ * Clear all session store caches (for testing).
+ */
+export declare function clearSessionStoreCacheForTest(): void;
+export type LoadSessionStoreOptions = {
+    /** Skip cache and read directly from disk */
+    skipCache?: boolean;
+};
+/**
+ * Load a session store from disk.
+ *
+ * @param storePath - Path to the store file
+ * @param opts - Load options
+ * @returns Session store (empty object if file doesn't exist)
+ */
+export declare function loadSessionStore(storePath: string, opts?: LoadSessionStoreOptions): SessionStore;
+/**
+ * Save a session store to disk with locking.
+ *
+ * @param storePath - Path to the store file
+ * @param store - Store to save
+ */
+export declare function saveSessionStore(storePath: string, store: SessionStore): Promise<void>;
+/**
+ * Update a session store with a mutator function.
+ *
+ * Acquires a lock, reads the store, applies mutations, and saves.
+ *
+ * @param storePath - Path to the store file
+ * @param mutator - Function to mutate the store
+ * @returns Result of the mutator function
+ */
+export declare function updateSessionStore<T>(storePath: string, mutator: (store: SessionStore) => Promise<T> | T): Promise<T>;
+/**
+ * Update a single session entry.
+ *
+ * @param params - Update parameters
+ * @returns Updated entry or null if not found
+ */
+export declare function updateSessionStoreEntry(params: {
+    storePath: string;
+    sessionKey: string;
+    update: (entry: SessionEntry) => Promise<Partial<SessionEntry> | null>;
+}): Promise<SessionEntry | null>;
+/**
+ * Get a session entry from the store.
+ *
+ * @param storePath - Path to the store file
+ * @param sessionKey - Session key to look up
+ * @returns Session entry or undefined
+ */
+export declare function getSessionEntry(storePath: string, sessionKey: string): SessionEntry | undefined;
+/**
+ * Get a session entry by session ID.
+ *
+ * @param storePath - Path to the store file
+ * @param sessionId - Session ID to look up
+ * @returns Session entry or undefined
+ */
+export declare function getSessionEntryById(storePath: string, sessionId: string): SessionEntry | undefined;
+/**
+ * Get the updated timestamp for a session.
+ *
+ * @param params - Query parameters
+ * @returns Timestamp or undefined
+ */
+export declare function readSessionUpdatedAt(params: {
+    storePath: string;
+    sessionKey: string;
+}): number | undefined;
+/**
+ * Create or update a session entry.
+ *
+ * @param params - Upsert parameters
+ * @returns The created/updated entry
+ */
+export declare function upsertSessionEntry(params: {
+    storePath: string;
+    sessionKey: string;
+    patch: Partial<SessionEntry>;
+}): Promise<SessionEntry>;
+/**
+ * Delete a session entry.
+ *
+ * @param params - Delete parameters
+ * @returns True if entry was deleted
+ */
+export declare function deleteSessionEntry(params: {
+    storePath: string;
+    sessionKey: string;
+}): Promise<boolean>;
+/**
+ * List all session keys in a store.
+ *
+ * @param storePath - Path to the store file
+ * @returns Array of session keys
+ */
+export declare function listSessionKeys(storePath: string): string[];
+/**
+ * List all sessions with their entries.
+ *
+ * @param storePath - Path to the store file
+ * @returns Array of [key, entry] tuples
+ */
+export declare function listSessions(storePath: string): Array<[string, SessionEntry]>;
+//# sourceMappingURL=store.d.ts.map

package/dist/sessions/store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"store.d.ts","sourceRoot":"","sources":["../../src/sessions/store.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAKH,OAAO,EAEN,KAAK,YAAY,EACjB,KAAK,YAAY,EACjB,MAAM,YAAY,CAAC;AAiDpB;;GAEG;AACH,wBAAgB,6BAA6B,IAAI,IAAI,CAEpD;AA0FD,MAAM,MAAM,uBAAuB,GAAG;IACrC,6CAA6C;IAC7C,SAAS,CAAC,EAAE,OAAO,CAAC;CACpB,CAAC;AAEF;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAC/B,SAAS,EAAE,MAAM,EACjB,IAAI,GAAE,uBAA4B,GAChC,YAAY,CA0Dd;AAiKD;;;;;GAKG;AACH,wBAAsB,gBAAgB,CACrC,SAAS,EAAE,MAAM,EACjB,KAAK,EAAE,YAAY,GACjB,OAAO,CAAC,IAAI,CAAC,CAIf;AAED;;;;;;;;GAQG;AACH,wBAAsB,kBAAkB,CAAC,CAAC,EACzC,SAAS,EAAE,MAAM,EACjB,OAAO,EAAE,CAAC,KAAK,EAAE,YAAY,KAAK,OAAO,CAAC,CAAC,CAAC,GAAG,CAAC,GAC9C,OAAO,CAAC,CAAC,CAAC,CAOZ;AAED;;;;;GAKG;AACH,wBAAsB,uBAAuB,CAAC,MAAM,EAAE;IACrD,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,EAAE,MAAM,CAAC;IACnB,MAAM,EAAE,CAAC,KAAK,EAAE,YAAY,KAAK,OAAO,CAAC,OAAO,CAAC,YAAY,CAAC,GAAG,IAAI,CAAC,CAAC;CACvE,GAAG,OAAO,CAAC,YAAY,GAAG,IAAI,CAAC,CAsB/B;AAED;;;;;;GAMG;AACH,wBAAgB,eAAe,CAC9B,SAAS,EAAE,MAAM,EACjB,UAAU,EAAE,MAAM,GAChB,YAAY,GAAG,SAAS,CAG1B;AAED;;;;;;GAMG;AACH,wBAAgB,mBAAmB,CAClC,SAAS,EAAE,MAAM,EACjB,SAAS,EAAE,MAAM,GACf,YAAY,GAAG,SAAS,CAG1B;AAED;;;;;GAKG;AACH,wBAAgB,oBAAoB,CAAC,MAAM,EAAE;IAC5C,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,EAAE,MAAM,CAAC;CACnB,GAAG,MAAM,GAAG,SAAS,CAOrB;AAED;;;;;GAKG;AACH,wBAAsB,kBAAkB,CAAC,MAAM,EAAE;IAChD,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,EAAE,MAAM,CAAC;IACnB,KAAK,EAAE,OAAO,CAAC,YAAY,CAAC,CAAC;CAC7B,GAAG,OAAO,CAAC,YAAY,CAAC,CASxB;AAED;;;;;GAKG;AACH,wBAAsB,kBAAkB,CAAC,MAAM,EAAE;IAChD,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,EAAE,MAAM,CAAC;CACnB,GAAG,OAAO,CAAC,OAAO,CAAC,CAUnB;AAED;;;;;GAKG;AACH,wBAAgB,eAAe,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,EAAE,CAG3D;AAED;;;;;GAKG;AACH,wBAAgB,YAAY,CAAC,SAAS,EAAE,MAAM,GAAG,KAAK,CAAC,CAAC,MAAM,EAAE,YAAY,CAAC,CAAC,CAK7E"}