@cuylabs/agent-core 0.3.0 → 0.5.0

package/dist/skill/index.d.ts

@@ -0,0 +1,103 @@
+import { h as SkillScope, i as SkillSource, a as SkillMetadata, g as SkillResourceType, c as SkillResource, b as SkillContent, d as SkillConfig, S as SkillDiscoveryResult, T as Tool } from '../tool-pFAnJc5Y.js';
+export { R as RemoteSkillEntry, e as RemoteSkillIndex, f as SkillDiscoveryError, j as SkillSourceType } from '../tool-pFAnJc5Y.js';
+import { S as SkillRegistry } from '../registry-CuRWWtcT.js';
+export { c as createSkillRegistry, e as emptySkillRegistry } from '../registry-CuRWWtcT.js';
+import 'zod';
+import '../tool-DYp6-cC3.js';
+
+declare const SKILL_FILENAME = "SKILL.md";
+declare const DEFAULT_SKILL_MAX_SIZE = 102400;
+
+declare function parseFrontmatter(raw: string): {
+    data: Record<string, unknown>;
+    body: string;
+};
+
+declare function loadSkillMetadata(filePath: string, scope: SkillScope, source: SkillSource, maxSize: number): Promise<SkillMetadata | null>;
+
+declare function loadSkillContent(metadata: SkillMetadata): Promise<SkillContent>;
+declare function loadResourceContent(resource: SkillResource): Promise<string>;
+declare function inferResourceType(filePath: string): SkillResourceType;
+
+declare const DEFAULT_EXTERNAL_DIRS: string[];
+declare const DEFAULT_MAX_SCAN_DEPTH = 4;
+
+declare function discoverSkills(cwd: string, config?: SkillConfig): Promise<SkillDiscoveryResult>;
+
+/**
+ * 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],
+ * });
+ * ```
+ */
+
+/**
+ * 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
+ */
+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
+ */
+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],
+ * });
+ * ```
+ */
+declare function createSkillTools(registry: SkillRegistry): Tool.AnyInfo[];
+
+export { DEFAULT_EXTERNAL_DIRS, DEFAULT_MAX_SCAN_DEPTH, DEFAULT_SKILL_MAX_SIZE, SKILL_FILENAME, SkillConfig, SkillContent, SkillDiscoveryResult, SkillMetadata, SkillRegistry, SkillResource, SkillResourceType, SkillScope, SkillSource, createSkillResourceTool, createSkillTool, createSkillTools, discoverSkills, inferResourceType, loadResourceContent, loadSkillContent, loadSkillMetadata, parseFrontmatter };

package/dist/skill/index.js

@@ -0,0 +1,39 @@
+import {
+  createSkillResourceTool,
+  createSkillTool,
+  createSkillTools
+} from "../chunk-YUUJK53A.js";
+import "../chunk-P6YF7USR.js";
+import {
+  DEFAULT_EXTERNAL_DIRS,
+  DEFAULT_MAX_SCAN_DEPTH,
+  DEFAULT_SKILL_MAX_SIZE,
+  SKILL_FILENAME,
+  SkillRegistry,
+  createSkillRegistry,
+  discoverSkills,
+  emptySkillRegistry,
+  inferResourceType,
+  loadResourceContent,
+  loadSkillContent,
+  loadSkillMetadata,
+  parseFrontmatter
+} from "../chunk-LRHOS4ZN.js";
+export {
+  DEFAULT_EXTERNAL_DIRS,
+  DEFAULT_MAX_SCAN_DEPTH,
+  DEFAULT_SKILL_MAX_SIZE,
+  SKILL_FILENAME,
+  SkillRegistry,
+  createSkillRegistry,
+  createSkillResourceTool,
+  createSkillTool,
+  createSkillTools,
+  discoverSkills,
+  emptySkillRegistry,
+  inferResourceType,
+  loadResourceContent,
+  loadSkillContent,
+  loadSkillMetadata,
+  parseFrontmatter
+};

package/dist/storage/index.d.ts

@@ -0,0 +1,167 @@
+import { F as FileEntry, i as SerializedMessage, d as SessionEntry, M as MessageEntry, b as MetadataEntry, f as SessionInfo, h as SessionStorage, e as SessionHeader, g as SessionManager } from '../session-manager-Uawm2Le7.js';
+export { B as BranchEntry, C as CompactionEntry, j as ConfigChangeEntry, a as CreateSessionOptions, E as EntryBase, S as STORAGE_VERSION, c as SessionContext } from '../session-manager-Uawm2Le7.js';
+import { M as Message } from '../messages-BYWGn8TY.js';
+
+/**
+ * Storage Utilities
+ *
+ * Helper functions for session storage operations.
+ */
+
+/**
+ * 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): 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[];
+
+/**
+ * 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 { FileEntry, FileStorage, type FileStorageOptions, MemoryStorage, MessageEntry, MetadataEntry, SerializedMessage, SessionEntry, SessionHeader, SessionInfo, SessionManager, SessionStorage, buildEntryPath, buildMessagesFromEntries, configureDefaultSessionManager, createMessageEntry, createMetadataEntry, deserializeMessage, extractSessionInfo, generateEntryId, getDataDir, getDefaultSessionManager, getGitRootHash, getLeafId, getProjectId, getProjectSessionsDir, getSessionsDir, parseJSONL, serializeMessage, toJSONL, toJSONLBatch };

package/dist/storage/index.js

@@ -0,0 +1,50 @@
+import {
+  FileStorage,
+  MemoryStorage,
+  STORAGE_VERSION,
+  SessionManager,
+  buildEntryPath,
+  buildMessagesFromEntries,
+  configureDefaultSessionManager,
+  createMessageEntry,
+  createMetadataEntry,
+  deserializeMessage,
+  extractSessionInfo,
+  generateEntryId,
+  getDataDir,
+  getDefaultSessionManager,
+  getGitRootHash,
+  getLeafId,
+  getProjectId,
+  getProjectSessionsDir,
+  getSessionsDir,
+  parseJSONL,
+  serializeMessage,
+  toJSONL,
+  toJSONLBatch
+} from "../chunk-BDBZ3SLK.js";
+export {
+  FileStorage,
+  MemoryStorage,
+  STORAGE_VERSION,
+  SessionManager,
+  buildEntryPath,
+  buildMessagesFromEntries,
+  configureDefaultSessionManager,
+  createMessageEntry,
+  createMetadataEntry,
+  deserializeMessage,
+  extractSessionInfo,
+  generateEntryId,
+  getDataDir,
+  getDefaultSessionManager,
+  getGitRootHash,
+  getLeafId,
+  getProjectId,
+  getProjectSessionsDir,
+  getSessionsDir,
+  parseJSONL,
+  serializeMessage,
+  toJSONL,
+  toJSONLBatch
+};

package/dist/sub-agent/index.d.ts

@@ -0,0 +1,14 @@
+export { c as AgentProfile, D as DEFAULT_MAX_CONCURRENT, d as DEFAULT_MAX_SPAWN_DEPTH, e as DEFAULT_SESSION_TITLE_PREFIX, S as SubAgentCompletedResult, f as SubAgentHandle, g as SubAgentStatus, h as SubAgentToolConfig, i as SubAgentTracker, j as SubAgentUsage, l as createSubAgentTools } from '../index-p0kOsVsE.js';
+import 'ai';
+import '../types-CQaXbRsS.js';
+import '../tool-pFAnJc5Y.js';
+import 'zod';
+import '../tool-DYp6-cC3.js';
+import '../runner-C7aMP_x3.js';
+import '../messages-BYWGn8TY.js';
+import '../session-manager-Uawm2Le7.js';
+import '../types-VQgymC1N.js';
+import '../tracker-DClqYqTj.js';
+import '../builder-RcTZuYnO.js';
+import '../registry-CuRWWtcT.js';
+import '../types-MM1JoX5T.js';

package/dist/sub-agent/index.js

@@ -0,0 +1,15 @@
+import {
+  DEFAULT_MAX_CONCURRENT,
+  DEFAULT_MAX_SPAWN_DEPTH,
+  DEFAULT_SESSION_TITLE_PREFIX,
+  SubAgentTracker,
+  createSubAgentTools
+} from "../chunk-7MUFEN4K.js";
+import "../chunk-P6YF7USR.js";
+export {
+  DEFAULT_MAX_CONCURRENT,
+  DEFAULT_MAX_SPAWN_DEPTH,
+  DEFAULT_SESSION_TITLE_PREFIX,
+  SubAgentTracker,
+  createSubAgentTools
+};

package/dist/tool/index.d.ts

@@ -1,2 +1,174 @@
-export { C as CompatibleSchema, I as InferSchemaOutput, M as MAX_BYTES, e as MAX_LINES, f as TRUNCATE_DIR, g as TRUNCATE_GLOB, a as Tool, j as ToolRegistry, l as ToolSpec, m as TruncateResult, n as defaultRegistry, o as defineTool, p as formatSize, t as truncateOutput } from '../index-QR704uRr.js';
+import { T as Tool } from '../tool-pFAnJc5Y.js';
+export { C as CompatibleSchema, I as InferSchemaOutput, k as defineTool } from '../tool-pFAnJc5Y.js';
+import { a as ToolReplayPolicy, F as FileOperationMeta, N as NormalizedToolReplayPolicy, d as ToolHost, e as TurnTrackerContext } from '../tool-DYp6-cC3.js';
+import { M as MiddlewareRunner } from '../runner-C7aMP_x3.js';
 import 'zod';
+import 'ai';
+import '../messages-BYWGn8TY.js';
+
+/**
+ * Normalize a tool replay policy into explicit, infrastructure-agnostic
+ * recovery semantics.
+ *
+ * The defaults are intentionally conservative:
+ * - read-only tools default to `replay`
+ * - mutating or unknown tools default to `manual`
+ */
+declare function normalizeToolReplayPolicy(policy?: ToolReplayPolicy, fileOps?: FileOperationMeta): NormalizedToolReplayPolicy;
+
+/**
+ * Tool registry for @cuylabs/agent-core
+ *
+ * Manages available tools, named groups, and resolution from specs.
+ */
+
+/**
+ * A tool spec that can be resolved to an array of tools.
+ *
+ * - `string`   — group name (`"read-only"`), single tool ID (`"bash"`),
+ *                or comma-separated list (`"read,grep,glob"`).
+ *                Prefix with `-` to exclude: `"all,-bash"`.
+ * - `string[]` — array of tool IDs and/or group names.
+ * - `Tool.AnyInfo[]` — pass-through (already resolved).
+ * - `true`     — all registered tools.
+ * - `false`    — no tools.
+ */
+type ToolSpec = string | string[] | Tool.AnyInfo[] | boolean;
+/**
+ * Tool registry — manages available tools and named groups.
+ *
+ * Tools are registered individually. Groups are named collections of tool IDs
+ * that resolve against the registry at lookup time.
+ *
+ * @example
+ * ```typescript
+ * const reg = new ToolRegistry();
+ * reg.registerAll([readTool, grepTool, bashTool]);
+ * reg.registerGroup("read-only", ["read", "grep", "glob"]);
+ *
+ * // Resolve a spec to a tool array
+ * reg.resolve("read-only");             // → [readTool, grepTool]
+ * reg.resolve("all,-bash");             // → [readTool, grepTool]
+ * reg.resolve(["read", "grep"]);        // → [readTool, grepTool]
+ * reg.resolve(true);                    // → all tools
+ * ```
+ */
+declare class ToolRegistry {
+    private tools;
+    private groups;
+    /**
+     * Register a tool. Throws if a tool with the same ID is already registered.
+     * Use `set()` for upsert semantics.
+     */
+    register(tool: Tool.AnyInfo): void;
+    /** Register multiple tools (throws on duplicates). */
+    registerAll(tools: Tool.AnyInfo[]): void;
+    /** Register or replace a tool (upsert). */
+    set(tool: Tool.AnyInfo): void;
+    /** Unregister a tool by ID. Returns `true` if it existed. */
+    unregister(id: string): boolean;
+    /** Get a tool by ID. */
+    get(id: string): Tool.AnyInfo | undefined;
+    /** Check if a tool is registered. */
+    has(id: string): boolean;
+    /** Get all tool IDs. */
+    ids(): string[];
+    /** Get all tools. */
+    all(): Tool.AnyInfo[];
+    /** Clear all tools and groups. */
+    clear(): void;
+    /** Number of registered tools. */
+    get size(): number;
+    /**
+     * Register a named group of tool IDs.
+     * The group name can be used in `resolve()` specs.
+     * Tool IDs don't need to be registered yet — resolution is lazy.
+     */
+    registerGroup(name: string, toolIds: string[]): void;
+    /** Get tools in a group (only returns registered tools). */
+    getGroup(name: string): Tool.AnyInfo[] | undefined;
+    /** Check if a group is registered. */
+    hasGroup(name: string): boolean;
+    /** List all group names. */
+    listGroups(): string[];
+    /**
+     * Resolve a `ToolSpec` to an array of tools.
+     *
+     * Supports group names, individual tool IDs, comma-separated strings,
+     * exclusions with `-` prefix, booleans, and pass-through arrays.
+     *
+     * @example
+     * ```typescript
+     * registry.resolve("read-only");          // group name
+     * registry.resolve("read,grep,glob");     // comma-separated IDs
+     * registry.resolve("all,-bash");          // all except bash
+     * registry.resolve(["read", "grep"]);     // array of IDs
+     * registry.resolve(true);                 // all registered tools
+     * registry.resolve(false);                // empty array
+     * ```
+     */
+    resolve(spec: ToolSpec): Tool.AnyInfo[];
+}
+/**
+ * Default tool registry instance.
+ * Shared across the application — register tools here for global access.
+ */
+declare const defaultRegistry: ToolRegistry;
+
+/**
+ * Output truncation utilities for @cuylabs/agent-core
+ */
+/** Maximum lines before truncation */
+declare const MAX_LINES = 2000;
+/** Maximum bytes before truncation */
+declare const MAX_BYTES = 100000;
+/** Directory for storing truncated outputs */
+declare const TRUNCATE_DIR: string;
+/** Glob pattern for truncation directory */
+declare const TRUNCATE_GLOB: string;
+interface TruncateResult {
+    /** The (possibly truncated) content */
+    content: string;
+    /** Whether the content was truncated */
+    truncated: boolean;
+    /** Path to full output if truncated */
+    outputPath?: string;
+}
+/**
+ * Truncate output if it exceeds limits
+ */
+declare function truncateOutput(output: string, options?: {
+    maxLines?: number;
+    maxBytes?: number;
+}): TruncateResult;
+/**
+ * Format file size for display
+ */
+declare function formatSize(bytes: number): string;
+
+interface ExecuteAgentToolCallOptions {
+    toolName: string;
+    tool: Tool.Info;
+    params: unknown;
+    cwd: string;
+    abort: AbortSignal;
+    sessionID: string;
+    messageID: string;
+    agent?: string;
+    host?: ToolHost;
+    turnTracker?: TurnTrackerContext;
+    middleware?: MiddlewareRunner;
+}
+interface ExecuteAgentToolCallResult {
+    output: string;
+}
+/**
+ * Execute one initialized framework tool with the same semantics used by the
+ * standard AI SDK path.
+ *
+ * This keeps middleware, baseline capture, and output normalization in one
+ * place so resumable runtimes do not need a second tool execution stack.
+ */
+declare function executeAgentToolCall(options: ExecuteAgentToolCallOptions): Promise<ExecuteAgentToolCallResult>;
+
+export { type ExecuteAgentToolCallOptions, type ExecuteAgentToolCallResult, MAX_BYTES, MAX_LINES, TRUNCATE_DIR, TRUNCATE_GLOB, Tool, ToolRegistry, type ToolSpec, type TruncateResult, defaultRegistry, executeAgentToolCall, formatSize, normalizeToolReplayPolicy, truncateOutput };

package/dist/tool/index.js

@@ -1,15 +1,22 @@
+import {
+  ToolRegistry,
+  defaultRegistry
+} from "../chunk-SDSBEQXG.js";
+import {
+  executeAgentToolCall
+} from "../chunk-FG4MD5MU.js";
 import {
   MAX_BYTES,
   MAX_LINES,
   TRUNCATE_DIR,
   TRUNCATE_GLOB,
   Tool,
-  ToolRegistry,
-  defaultRegistry,
   defineTool,
   formatSize,
+  normalizeToolReplayPolicy,
   truncateOutput
-} from "../chunk-6VKLWNRE.js";
+} from "../chunk-P6YF7USR.js";
+import "../chunk-VEKUXUVF.js";
 export {
   MAX_BYTES,
   MAX_LINES,
@@ -19,6 +26,8 @@ export {
   ToolRegistry,
   defaultRegistry,
   defineTool,
+  executeAgentToolCall,
   formatSize,
+  normalizeToolReplayPolicy,
   truncateOutput
 };