@cuylabs/agent-core 4.8.1 → 4.10.0

package/dist/skill/tools.d.ts

@@ -0,0 +1,77 @@
+/**
+ * Skill Tools — built-in tools for agent-initiated skill loading
+ *
+ * Provides two tools that enable the agent to activate skills on demand:
+ *
+ * 1. **`skill`** — Load a skill's full instructions (L2).
+ *    The agent calls this when it recognizes a task matching a skill's
+ *    description. Returns the complete skill body with resource listings.
+ *
+ * 2. **`skill_resource`** — Read a specific bundled resource (L3).
+ *    After loading a skill, the agent can read scripts, references,
+ *    examples, or assets bundled with it.
+ *
+ * These tools expose skills as regular tools the agent can call,
+ * using progressive disclosure so context is used efficiently.
+ *
+ * The tool descriptions are dynamic — they list all available skill names
+ * and descriptions so the agent knows what's available without needing
+ * a separate discovery step.
+ *
+ * @example
+ * ```typescript
+ * import { createSkillTools, createSkillRegistry } from "@cuylabs/agent-core";
+ *
+ * const registry = await createSkillRegistry(cwd, skillConfig);
+ * const tools = createSkillTools(registry);
+ *
+ * const agent = createAgent({
+ *   model: anthropic("claude-sonnet-4-20250514"),
+ *   tools: [...myTools, ...tools],
+ * });
+ * ```
+ */
+import { Tool } from "../tool/tool.js";
+import type { SkillRegistry } from "./registry.js";
+/**
+ * Create the built-in `skill` tool that lets the agent load skill instructions.
+ *
+ * The tool's description is dynamically generated to include all available
+ * skill names and summaries, so the agent knows exactly what's available.
+ *
+ * @param registry The skill registry to load from
+ * @returns A Tool.Info for the `skill` tool
+ */
+export declare function createSkillTool(registry: SkillRegistry): Tool.AnyInfo;
+/**
+ * Create the built-in `skill_resource` tool for reading bundled files.
+ *
+ * This is the L3 layer — the agent calls this to read specific scripts,
+ * references, examples, or assets bundled with a skill.
+ *
+ * @param registry The skill registry to load from
+ * @returns A Tool.Info for the `skill_resource` tool
+ */
+export declare function createSkillResourceTool(registry: SkillRegistry): Tool.AnyInfo;
+/**
+ * Create both skill tools (skill + skill_resource) for an agent.
+ *
+ * Returns an empty array if the registry has no skills, so the tools
+ * don't clutter the agent's tool list when skills aren't in use.
+ *
+ * @param registry The skill registry
+ * @returns Array of Tool.AnyInfo (0 or 2 tools)
+ *
+ * @example
+ * ```typescript
+ * const registry = await createSkillRegistry(cwd, config);
+ * const skillTools = createSkillTools(registry);
+ *
+ * const agent = createAgent({
+ *   model: myModel,
+ *   tools: [...codeTools, ...skillTools],
+ * });
+ * ```
+ */
+export declare function createSkillTools(registry: SkillRegistry): Tool.AnyInfo[];
+//# sourceMappingURL=tools.d.ts.map

package/dist/skill/tools.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tools.d.ts","sourceRoot":"","sources":["../../src/skill/tools.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AAGH,OAAO,EAAE,IAAI,EAAE,MAAM,iBAAiB,CAAC;AACvC,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,eAAe,CAAC;AAMnD;;;;;;;;GAQG;AACH,wBAAgB,eAAe,CAAC,QAAQ,EAAE,aAAa,GAAG,IAAI,CAAC,OAAO,CA4DrE;AAMD;;;;;;;;GAQG;AACH,wBAAgB,uBAAuB,CAAC,QAAQ,EAAE,aAAa,GAAG,IAAI,CAAC,OAAO,CA4B7E;AAMD;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,aAAa,GAAG,IAAI,CAAC,OAAO,EAAE,CAIxE"}

package/dist/skill/types.d.ts

@@ -0,0 +1,291 @@
+/**
+ * Skill System Types
+ *
+ * Skills are modular, on-demand knowledge packs that extend an agent's
+ * capabilities with specialized instructions, workflows, and resources.
+ *
+ * Design principles:
+ *
+ * 1. **Progressive disclosure** — summaries always in context,
+ *    full content loaded only when needed. Minimizes baseline token cost.
+ *
+ * 2. **Scoped priority** — project skills override user skills
+ *    override global skills. Closest scope wins on name collision.
+ *
+ * 3. **Agent-initiated loading** — the agent decides when to
+ *    activate a skill by calling the `skill` tool. No guesswork.
+ *
+ * 4. **Bundled resources** — skills can ship scripts,
+ *    references, assets, and examples alongside instructions.
+ *
+ * 5. **Remote sources** — skills can be fetched from URLs,
+ *    enabling shared skill repositories across teams.
+ *
+ * The lifecycle:
+ *
+ *   Discovery → Registry → Summary injection → Agent tool call → Full load
+ *
+ * @packageDocumentation
+ */
+/**
+ * Where a skill was discovered, determining its override priority.
+ *
+ * When two skills share the same name, the narrower scope wins:
+ *   project > user > global > builtin
+ *
+ * Uses a 4-tier hierarchy with names that are intuitive for
+ * library consumers.
+ */
+export type SkillScope = "project" | "user" | "global" | "builtin";
+/**
+ * How a skill was obtained — local filesystem or remote URL.
+ */
+export type SkillSourceType = "local" | "remote";
+/**
+ * Where a skill came from, for provenance tracking.
+ */
+export interface SkillSource {
+    /** Local or remote origin */
+    type: SkillSourceType;
+    /** Root directory or URL this skill was discovered under */
+    root: string;
+}
+/**
+ * Classification of bundled resources within a skill directory.
+ *
+ * Resource taxonomy:
+ * - `script`    — executable code for deterministic tasks (can be run without reading)
+ * - `reference` — documentation loaded into context on demand
+ * - `asset`     — templates, images, fonts used in output (not read into context)
+ * - `example`   — working code samples for the agent to learn from
+ */
+export type SkillResourceType = "script" | "reference" | "asset" | "example";
+/**
+ * A file bundled with a skill.
+ *
+ * Resources are discovered but NOT loaded into memory until the agent
+ * explicitly requests them. This is the L3 layer of progressive disclosure.
+ */
+export interface SkillResource {
+    /** Path relative to the skill's base directory */
+    relativePath: string;
+    /** Classified resource type */
+    type: SkillResourceType;
+    /**
+     * Absolute path on disk.
+     *
+     * Undefined for pack-contributed resources that carry inline content.
+     * Either `absolutePath` or `content` must be set.
+     */
+    absolutePath?: string;
+    /**
+     * Inline resource content.
+     *
+     * Set for pack-contributed resources that have no file on disk.
+     * Takes precedence over `absolutePath` when both are present.
+     */
+    content?: string;
+}
+/**
+ * Lightweight skill metadata parsed from SKILL.md YAML frontmatter.
+ *
+ * This is the **L1 layer** — always present in the system prompt so the
+ * agent knows which skills exist. Kept intentionally small (~100 words each)
+ * to minimize baseline context cost.
+ *
+ * Uses YAML frontmatter in a SKILL.md file — the widely-adopted
+ * canonical format for skill definitions.
+ */
+export interface SkillMetadata {
+    /** Unique skill identifier (from frontmatter `name`) */
+    name: string;
+    /**
+     * When to use this skill — the single most important field.
+     *
+     * This description is what the agent reads to decide whether to
+     * activate the skill. Should contain trigger phrases that match
+     * task types. Written for another LLM to consume, not humans.
+     */
+    description: string;
+    /** Semantic version (from frontmatter, optional) */
+    version?: string;
+    /** Scope that determines override priority */
+    scope: SkillScope;
+    /** How this skill was obtained */
+    source: SkillSource;
+    /**
+     * Absolute path to the SKILL.md file.
+     *
+     * Undefined for pack-contributed skills that have no file on disk.
+     * When undefined, content must be pre-cached — use `SkillRegistry.register()`
+     * with a pre-built `SkillContent`.
+     */
+    filePath?: string;
+    /**
+     * Directory containing the skill (parent of SKILL.md).
+     *
+     * Undefined for pack-contributed skills with no file on disk.
+     */
+    baseDir?: string;
+    /** Optional tags for categorization */
+    tags?: string[];
+    /**
+     * Names of skills this skill depends on.
+     * When this skill is loaded, its dependencies are suggested to be loaded too.
+     */
+    dependencies?: string[];
+}
+/**
+ * Full skill content including the markdown body and resource listing.
+ *
+ * This is the **L2 layer** — loaded only when the agent calls the skill
+ * tool. Contains the actual instructions plus awareness of bundled resources.
+ */
+export interface SkillContent extends SkillMetadata {
+    /**
+     * The full markdown body of SKILL.md (everything below the frontmatter).
+     * This is the core instructional content injected into the conversation.
+     */
+    body: string;
+    /**
+     * Bundled resources discovered in the skill directory.
+     * Listed so the agent knows what's available but not yet loaded.
+     */
+    resources: SkillResource[];
+}
+/**
+ * Configuration for skill discovery and loading.
+ *
+ * Controls where skills are found, how deep to scan, and which
+ * external conventions to support.
+ *
+ * @example
+ * ```typescript
+ * const skillConfig: SkillConfig = {
+ *   // Scan standard locations
+ *   externalDirs: [".agents", ".claude"],
+ *   // Add custom skill roots
+ *   roots: ["./company-skills"],
+ *   // Limit scan depth for performance
+ *   maxScanDepth: 4,
+ * };
+ * ```
+ */
+export interface SkillConfig {
+    /**
+     * Additional directories to scan for skills (absolute or relative to cwd).
+     * Each directory is scanned recursively for SKILL.md files.
+     */
+    roots?: string[];
+    /**
+     * External skill directory names to scan in project and home directories.
+     *
+     * These are checked as `<project>/<dir>/skills/` and `~/<dir>/skills/`.
+     * Supports `.claude` and `.agents` directory conventions.
+     *
+     * @default [".agents", ".claude"]
+     */
+    externalDirs?: string[];
+    /**
+     * Maximum directory depth to scan within each root.
+     * Higher values find more deeply nested skills but take longer.
+     *
+     * @default 4
+     */
+    maxScanDepth?: number;
+    /**
+     * Maximum file size for SKILL.md files in bytes.
+     * Skills larger than this are skipped with a warning.
+     *
+     * @default 102400 (100KB)
+     */
+    maxFileSize?: number;
+    /**
+     * Enable fetching skills from remote URLs.
+     * When false, `remoteUrls` is ignored.
+     *
+     * @default false
+     */
+    enableRemote?: boolean;
+    /**
+     * Remote skill index URLs to fetch.
+     *
+     * Each URL should serve a JSON index listing available skills.
+     * See `RemoteSkillIndex` for the expected format.
+     *
+     * @example
+     * ```typescript
+     * remoteUrls: ["https://skills.example.com/index.json"]
+     * ```
+     */
+    remoteUrls?: string[];
+    /**
+     * Cache directory for remote skills.
+     * Defaults to `~/.cache/cuylabs/skills/`.
+     */
+    remoteCacheDir?: string;
+    /**
+     * Include built-in skills bundled with agent-core.
+     * Currently reserved for future use.
+     *
+     * @default true
+     */
+    includeBuiltin?: boolean;
+}
+/**
+ * Schema for remote skill index JSON files.
+ *
+ * Hosted at a URL like `https://skills.example.com/index.json`.
+ * Enables team-wide or organization-wide skill sharing.
+ *
+ * @example
+ * ```json
+ * {
+ *   "version": 1,
+ *   "skills": [
+ *     {
+ *       "name": "testing",
+ *       "files": ["SKILL.md", "scripts/run-tests.sh", "references/patterns.md"]
+ *     }
+ *   ]
+ * }
+ * ```
+ */
+export interface RemoteSkillIndex {
+    /** Schema version (currently 1) */
+    version: number;
+    /** List of available skills */
+    skills: RemoteSkillEntry[];
+}
+/**
+ * A single skill listing in a remote index.
+ */
+export interface RemoteSkillEntry {
+    /** Skill name (must match the `name` in SKILL.md frontmatter) */
+    name: string;
+    /** Relative file paths to download (SKILL.md is required) */
+    files: string[];
+}
+/**
+ * Result of a full skill discovery pass.
+ */
+export interface SkillDiscoveryResult {
+    /** All discovered skills (deduplicated, scope-prioritized) */
+    skills: SkillMetadata[];
+    /** Skills that failed to load with reasons */
+    errors: SkillDiscoveryError[];
+    /** Total directories scanned */
+    dirsScanned: number;
+    /** Discovery duration in milliseconds */
+    durationMs: number;
+}
+/**
+ * An error encountered during skill discovery.
+ */
+export interface SkillDiscoveryError {
+    /** Path that caused the error */
+    path: string;
+    /** What went wrong */
+    reason: string;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/skill/types.d.ts.map

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

package/dist/storage/file/helpers.d.ts

@@ -0,0 +1,16 @@
+import type { FileEntry } from "../types.js";
+export declare function ensureStorageDirectory(directory: string): Promise<void>;
+export declare function getSessionFilePath(directory: string, extension: string, sessionId: string): string;
+export declare function loadEntriesFromDisk(filePath: string, sessionId: string): Promise<FileEntry[]>;
+export declare function createSessionFile(filePath: string, header: FileEntry): Promise<void>;
+export declare function appendSessionEntry(filePath: string, entry: FileEntry): Promise<void>;
+export declare function appendSessionEntries(filePath: string, entries: FileEntry[]): Promise<void>;
+export declare function sessionFileExists(filePath: string): boolean;
+export declare function deleteSessionFile(filePath: string): Promise<boolean>;
+export declare function listSessionIds(directory: string, extension: string): Promise<string[]>;
+export declare function clearSessionFiles(directory: string, extension: string): Promise<void>;
+export declare function getSessionFileStats(filePath: string): Promise<{
+    size: number;
+    mtime: Date;
+} | null>;
+//# sourceMappingURL=helpers.d.ts.map

package/dist/storage/file/helpers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"helpers.d.ts","sourceRoot":"","sources":["../../../src/storage/file/helpers.ts"],"names":[],"mappings":"AAWA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAG7C,wBAAsB,sBAAsB,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAI7E;AAED,wBAAgB,kBAAkB,CAChC,SAAS,EAAE,MAAM,EACjB,SAAS,EAAE,MAAM,EACjB,SAAS,EAAE,MAAM,GAChB,MAAM,CAiBR;AAED,wBAAsB,mBAAmB,CACvC,QAAQ,EAAE,MAAM,EAChB,SAAS,EAAE,MAAM,GAChB,OAAO,CAAC,SAAS,EAAE,CAAC,CAUtB;AAED,wBAAsB,iBAAiB,CACrC,QAAQ,EAAE,MAAM,EAChB,MAAM,EAAE,SAAS,GAChB,OAAO,CAAC,IAAI,CAAC,CAEf;AAED,wBAAsB,kBAAkB,CACtC,QAAQ,EAAE,MAAM,EAChB,KAAK,EAAE,SAAS,GACf,OAAO,CAAC,IAAI,CAAC,CAEf;AAED,wBAAsB,oBAAoB,CACxC,QAAQ,EAAE,MAAM,EAChB,OAAO,EAAE,SAAS,EAAE,GACnB,OAAO,CAAC,IAAI,CAAC,CAEf;AAED,wBAAgB,iBAAiB,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAE3D;AAED,wBAAsB,iBAAiB,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAW1E;AAED,wBAAsB,cAAc,CAClC,SAAS,EAAE,MAAM,EACjB,SAAS,EAAE,MAAM,GAChB,OAAO,CAAC,MAAM,EAAE,CAAC,CASnB;AAED,wBAAsB,iBAAiB,CACrC,SAAS,EAAE,MAAM,EACjB,SAAS,EAAE,MAAM,GAChB,OAAO,CAAC,IAAI,CAAC,CAWf;AAED,wBAAsB,mBAAmB,CACvC,QAAQ,EAAE,MAAM,GACf,OAAO,CAAC;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,IAAI,CAAA;CAAE,GAAG,IAAI,CAAC,CAU/C"}

package/dist/storage/file/index.d.ts

@@ -0,0 +1,6 @@
+/**
+ * JSONL-backed session storage and filesystem helpers.
+ */
+export type { FileStorageOptions } from "./types.js";
+export { FileStorage } from "./storage.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/storage/file/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/storage/file/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,YAAY,EAAE,kBAAkB,EAAE,MAAM,YAAY,CAAC;AACrD,OAAO,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC"}

package/dist/storage/file/storage.d.ts

@@ -0,0 +1,29 @@
+import type { FileEntry, SessionEntry, SessionHeader, SessionInfo, SessionStorage } from "../types.js";
+import type { FileStorageOptions } from "./types.js";
+export declare class FileStorage implements SessionStorage {
+    private readonly directory;
+    private readonly extension;
+    private readonly useCache;
+    private cache;
+    private initialized;
+    constructor(options: FileStorageOptions);
+    private ensureDir;
+    private getPath;
+    private getEntries;
+    create(header: SessionHeader): Promise<void>;
+    append(sessionId: string, entry: SessionEntry): Promise<void>;
+    appendBatch(sessionId: string, entries: SessionEntry[]): Promise<void>;
+    read(sessionId: string): Promise<FileEntry[]>;
+    delete(sessionId: string): Promise<boolean>;
+    exists(sessionId: string): Promise<boolean>;
+    list(): Promise<SessionInfo[]>;
+    clear(): Promise<void>;
+    flushCache(): void;
+    reload(sessionId: string): Promise<FileEntry[]>;
+    listIds(): Promise<string[]>;
+    getStats(sessionId: string): Promise<{
+        size: number;
+        mtime: Date;
+    } | null>;
+}
+//# sourceMappingURL=storage.d.ts.map

package/dist/storage/file/storage.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"storage.d.ts","sourceRoot":"","sources":["../../../src/storage/file/storage.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,SAAS,EACT,YAAY,EACZ,aAAa,EACb,WAAW,EACX,cAAc,EACf,MAAM,aAAa,CAAC;AAerB,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,YAAY,CAAC;AAErD,qBAAa,WAAY,YAAW,cAAc;IAChD,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAS;IACnC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAS;IACnC,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAU;IACnC,OAAO,CAAC,KAAK,CAAkC;IAC/C,OAAO,CAAC,WAAW,CAAS;gBAEhB,OAAO,EAAE,kBAAkB;YAMzB,SAAS;IAMvB,OAAO,CAAC,OAAO;YAID,UAAU;IAgBlB,MAAM,CAAC,MAAM,EAAE,aAAa,GAAG,OAAO,CAAC,IAAI,CAAC;IAc5C,MAAM,CAAC,SAAS,EAAE,MAAM,EAAE,KAAK,EAAE,YAAY,GAAG,OAAO,CAAC,IAAI,CAAC;IAe7D,WAAW,CAAC,SAAS,EAAE,MAAM,EAAE,OAAO,EAAE,YAAY,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC;IAiBtE,IAAI,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,SAAS,EAAE,CAAC;IAK7C,MAAM,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAK3C,MAAM,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAO3C,IAAI,IAAI,OAAO,CAAC,WAAW,EAAE,CAAC;IAyB9B,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAK5B,UAAU,IAAI,IAAI;IAIZ,MAAM,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,SAAS,EAAE,CAAC;IAK/C,OAAO,IAAI,OAAO,CAAC,MAAM,EAAE,CAAC;IAK5B,QAAQ,CACZ,SAAS,EAAE,MAAM,GAChB,OAAO,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,IAAI,CAAA;KAAE,GAAG,IAAI,CAAC;CAGjD"}

package/dist/storage/file/types.d.ts

@@ -0,0 +1,6 @@
+export interface FileStorageOptions {
+    directory: string;
+    extension?: string;
+    cache?: boolean;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/storage/file/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/storage/file/types.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,kBAAkB;IACjC,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB"}

package/dist/storage/index.d.ts

@@ -1,191 +1,14 @@
-import { bQ as MessageRole, bf as FileEntry, ct as SessionEntry, M as Message, bK as MessageEntry, bS as MetadataEntry, cq as SerializedMessage, cv as SessionInfo, cw as SessionStorage, cu as SessionHeader, S as SessionManager } from '../instance-Bg61WSyz.js';
-export { aA as BranchEntry, aF as CompactionEntry, aH as ConfigChangeEntry, aN as CreateSessionOptions, bc as EntryBase, bA as LocalSessionTurnLock, cg as RecentMessagesOptions, ch as ReleaseSessionTurnLock, cp as STORAGE_VERSION, cs as SessionContext, cx as SessionTurnLock, cy as SessionTurnLockAcquireOptions } from '../instance-Bg61WSyz.js';
-import { L as Logger } from '../types-RSCv7nQ4.js';
-import '../types-C_LCeYNg.js';
-import 'ai';
-import 'zod';
-import '../types-CQaXbRsS.js';
-import '../types-DMjoFKKv.js';
-import '@modelcontextprotocol/sdk/client/auth.js';
-import '@modelcontextprotocol/sdk/types.js';
-import '@ai-sdk/provider-utils';
-import '../sandbox/index.js';
-import '../llm-error-D93FNNLY.js';
-
 /**
- * Storage Utilities
+ * Storage Module
  *
- * Helper functions for session storage operations.
+ * Session storage with tree structure, async I/O, and pluggable backends.
  */
-
-/**
- * Generate a unique 8-character hex ID
- * Collision-checked against existing IDs
- */
-declare function generateEntryId(existingIds?: Set<string>): string;
-/**
- * Parse JSONL content into entries
- * Handles malformed lines gracefully
- */
-declare function parseJSONL<T>(content: string, logger?: Logger): T[];
-/**
- * Serialize entry to JSONL line
- */
-declare function toJSONL(entry: FileEntry): string;
-/**
- * Serialize multiple entries to JSONL
- */
-declare function toJSONLBatch(entries: FileEntry[]): string;
-/**
- * Serialize a Message to storage format
- */
-declare function serializeMessage(message: Message): SerializedMessage;
-/**
- * Deserialize a stored message back to Message
- */
-declare function deserializeMessage(serialized: SerializedMessage): Message;
-/**
- * Create a message entry from a Message
- */
-declare function createMessageEntry(message: Message, parentId: string | null, existingIds?: Set<string>): MessageEntry;
-/**
- * Create a metadata entry
- */
-declare function createMetadataEntry(updates: {
-    title?: string;
-    name?: string;
-}, parentId: string | null, existingIds?: Set<string>): MetadataEntry;
-/**
- * Extract SessionInfo from entries (for listing)
- */
-declare function extractSessionInfo(entries: FileEntry[], path: string): SessionInfo | null;
-/**
- * Get leaf entry ID (last entry in the chain)
- */
-declare function getLeafId(entries: FileEntry[]): string | null;
-/**
- * Build path from root to a specific entry
- */
-declare function buildEntryPath(entries: FileEntry[], targetId: string): SessionEntry[];
-/**
- * Build messages array from entries for a specific leaf
- * Handles compaction summaries
- */
-declare function buildMessagesFromEntries(entries: FileEntry[], leafId?: string): Message[];
-interface BuildRecentMessagesOptions {
-    leafId?: string;
-    limit?: number;
-    roles?: readonly MessageRole[];
-}
-/**
- * Build the last N visible messages from a session path without materializing
- * the full message list when only a bounded suffix is needed.
- */
-declare function buildRecentMessagesFromEntries(entries: FileEntry[], options?: BuildRecentMessagesOptions): Message[];
-/**
- * Build the last N visible messages from an existing entry index.
- */
-declare function buildRecentMessagesFromEntryMap(entriesById: ReadonlyMap<string, SessionEntry>, leafId: string | undefined, options?: Omit<BuildRecentMessagesOptions, "leafId">): Message[];
-
-/**
- * Memory Session Storage
- *
- * In-memory implementation of SessionStorage.
- * Useful for testing and ephemeral sessions.
- */
-
-/**
- * In-memory session storage
- */
-declare class MemoryStorage implements SessionStorage {
-    private sessions;
-    create(header: SessionHeader): Promise<void>;
-    append(sessionId: string, entry: SessionEntry): Promise<void>;
-    appendBatch(sessionId: string, entries: SessionEntry[]): Promise<void>;
-    read(sessionId: string): Promise<FileEntry[]>;
-    delete(sessionId: string): Promise<boolean>;
-    exists(sessionId: string): Promise<boolean>;
-    list(): Promise<SessionInfo[]>;
-    clear(): Promise<void>;
-}
-
-interface FileStorageOptions {
-    directory: string;
-    extension?: string;
-    cache?: boolean;
-}
-
-declare class FileStorage implements SessionStorage {
-    private readonly directory;
-    private readonly extension;
-    private readonly useCache;
-    private cache;
-    private initialized;
-    constructor(options: FileStorageOptions);
-    private ensureDir;
-    private getPath;
-    private getEntries;
-    create(header: SessionHeader): Promise<void>;
-    append(sessionId: string, entry: SessionEntry): Promise<void>;
-    appendBatch(sessionId: string, entries: SessionEntry[]): Promise<void>;
-    read(sessionId: string): Promise<FileEntry[]>;
-    delete(sessionId: string): Promise<boolean>;
-    exists(sessionId: string): Promise<boolean>;
-    list(): Promise<SessionInfo[]>;
-    clear(): Promise<void>;
-    flushCache(): void;
-    reload(sessionId: string): Promise<FileEntry[]>;
-    listIds(): Promise<string[]>;
-    getStats(sessionId: string): Promise<{
-        size: number;
-        mtime: Date;
-    } | null>;
-}
-
-/**
- * Default paths for storage
- *
- * Follows platform conventions:
- * - macOS: ~/.cuylabs/
- * - Linux: $XDG_DATA_HOME/cuylabs/ or ~/.local/share/cuylabs/
- * - Windows: %APPDATA%/cuylabs/
- *
- * Project identification:
- * - Uses git root commit hash for git repos
- * - Falls back to encoded path for non-git directories
- */
-/**
- * Get the default data directory for cuylabs
- */
-declare function getDataDir(appName?: string): string;
-/**
- * Get the default sessions directory
- */
-declare function getSessionsDir(appName?: string): string;
-/**
- * Get the git root commit hash for a directory.
- * This is stable across machines and identifies the project uniquely.
- * Returns null if not a git repo.
- */
-declare function getGitRootHash(cwd: string): string | null;
-/**
- * Get a short project ID for a directory.
- * - For git repos: uses first 12 chars of root commit hash
- * - For non-git: uses encoded path
- */
-declare function getProjectId(cwd: string): string;
-/**
- * Get sessions directory for a specific project/cwd
- */
-declare function getProjectSessionsDir(cwd: string, appName?: string): string;
-
-/**
- * Get the default session-manager instance.
- */
-declare function getDefaultSessionManager(): SessionManager;
-/**
- * Replace the default session-manager instance with one backed by custom storage.
- */
-declare function configureDefaultSessionManager(storage: SessionStorage): SessionManager;
-
-export { type BuildRecentMessagesOptions, FileEntry, FileStorage, type FileStorageOptions, MemoryStorage, MessageEntry, MetadataEntry, SerializedMessage, SessionEntry, SessionHeader, SessionInfo, SessionManager, SessionStorage, buildEntryPath, buildMessagesFromEntries, buildRecentMessagesFromEntries, buildRecentMessagesFromEntryMap, configureDefaultSessionManager, createMessageEntry, createMetadataEntry, deserializeMessage, extractSessionInfo, generateEntryId, getDataDir, getDefaultSessionManager, getGitRootHash, getLeafId, getProjectId, getProjectSessionsDir, getSessionsDir, parseJSONL, serializeMessage, toJSONL, toJSONLBatch };
+export type { EntryBase, SessionHeader, SerializedMessage, MessageEntry, CompactionEntry, MetadataEntry, BranchEntry, ConfigChangeEntry, SessionEntry, FileEntry, SessionInfo, SessionStorage, } from "./types.js";
+export { STORAGE_VERSION } from "./types.js";
+export { generateEntryId, parseJSONL, toJSONL, toJSONLBatch, serializeMessage, deserializeMessage, createMessageEntry, createMetadataEntry, extractSessionInfo, getLeafId, buildEntryPath, buildMessagesFromEntries, buildRecentMessagesFromEntries, buildRecentMessagesFromEntryMap, type BuildRecentMessagesOptions, } from "./utils.js";
+export { MemoryStorage } from "./memory.js";
+export { FileStorage, type FileStorageOptions } from "./file/index.js";
+export { LocalSessionTurnLock, type ReleaseSessionTurnLock, type SessionTurnLock, type SessionTurnLockAcquireOptions, } from "./lock.js";
+export { getDataDir, getSessionsDir, getProjectSessionsDir, getProjectId, getGitRootHash, } from "./paths.js";
+export { SessionManager, getDefaultSessionManager, configureDefaultSessionManager, type CreateSessionOptions, type RecentMessagesOptions, type SessionContext, } from "./manager/index.js";
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/storage/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAGH,YAAY,EAEV,SAAS,EACT,aAAa,EACb,iBAAiB,EAEjB,YAAY,EACZ,eAAe,EACf,aAAa,EACb,WAAW,EACX,iBAAiB,EACjB,YAAY,EACZ,SAAS,EAET,WAAW,EAEX,cAAc,GACf,MAAM,YAAY,CAAC;AAEpB,OAAO,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAG7C,OAAO,EACL,eAAe,EACf,UAAU,EACV,OAAO,EACP,YAAY,EACZ,gBAAgB,EAChB,kBAAkB,EAClB,kBAAkB,EAClB,mBAAmB,EACnB,kBAAkB,EAClB,SAAS,EACT,cAAc,EACd,wBAAwB,EACxB,8BAA8B,EAC9B,+BAA+B,EAC/B,KAAK,0BAA0B,GAChC,MAAM,YAAY,CAAC;AAGpB,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAC5C,OAAO,EAAE,WAAW,EAAE,KAAK,kBAAkB,EAAE,MAAM,iBAAiB,CAAC;AACvE,OAAO,EACL,oBAAoB,EACpB,KAAK,sBAAsB,EAC3B,KAAK,eAAe,EACpB,KAAK,6BAA6B,GACnC,MAAM,WAAW,CAAC;AAGnB,OAAO,EACL,UAAU,EACV,cAAc,EACd,qBAAqB,EACrB,YAAY,EACZ,cAAc,GACf,MAAM,YAAY,CAAC;AAGpB,OAAO,EACL,cAAc,EACd,wBAAwB,EACxB,8BAA8B,EAC9B,KAAK,oBAAoB,EACzB,KAAK,qBAAqB,EAC1B,KAAK,cAAc,GACpB,MAAM,oBAAoB,CAAC"}

package/dist/storage/index.js

@@ -25,7 +25,8 @@ import {
   serializeMessage,
   toJSONL,
   toJSONLBatch
-} from "../chunk-H3GRHFFG.js";
+} from "../chunk-VMGZKIFT.js";
+import "../chunk-AAGKWUXR.js";
 export {
   FileStorage,
   LocalSessionTurnLock,