@cuylabs/agent-core 0.9.0 → 0.11.0

package/dist/tracker-DClqYqTj.d.ts

@@ -1,96 +0,0 @@
-/**
- * Turn-tracker contracts for @cuylabs/agent-core.
- */
-/** Configuration for turn tracking. */
-interface TurnTrackerConfig {
-    /** Working directory (absolute path) - all paths resolve relative to this */
-    cwd: string;
-    /** Whether to try git-aware diffs when available. Default: auto-detect */
-    useGit?: boolean;
-    /** Maximum files to track per turn. Default: 100 */
-    maxTrackedFiles?: number;
-}
-/** File baseline captured before modification. */
-interface FileBaseline {
-    /** Absolute path */
-    path: string;
-    /** Content before modification (null if file did not exist) */
-    content: string | null;
-    /** File mode (permissions) */
-    mode: number | null;
-    /** Hash of original content for quick comparison */
-    hash: string | null;
-    /** When baseline was captured */
-    capturedAt: Date;
-}
-/** Single file change within a turn. */
-interface TurnFileChange {
-    /** Relative path (from cwd) */
-    path: string;
-    /** Type of change */
-    type: "created" | "modified" | "deleted" | "unchanged";
-    /** Lines added */
-    additions: number;
-    /** Lines removed */
-    deletions: number;
-    /** Unified diff for this file */
-    diff?: string;
-}
-/** Summary of a completed turn. */
-interface TurnSummary {
-    /** Turn identifier */
-    turnId: string;
-    /** Files changed */
-    files: TurnFileChange[];
-    /** Total files tracked */
-    totalTracked: number;
-    /** Total additions across all files */
-    additions: number;
-    /** Total deletions across all files */
-    deletions: number;
-    /** Combined unified diff for all changes */
-    diff: string | null;
-    /** Turn duration in ms */
-    duration: number;
-}
-/** Result of undo operation. */
-interface UndoResult {
-    /** Files restored */
-    restored: string[];
-    /** Files that could not be restored */
-    failed: Array<{
-        path: string;
-        reason: string;
-    }>;
-}
-
-/**
- * Turn Change Tracker - Per-turn file modification tracking.
- *
- * Tracks file changes within a single agent turn for undo/diff capabilities.
- * Unlike checkpoints (session-level snapshots), this only captures files that
- * were actually touched during the active turn.
- */
-
-declare class TurnChangeTracker {
-    private config;
-    private currentTurn;
-    private gitDetected;
-    constructor(config: TurnTrackerConfig);
-    startTurn(turnId: string): void;
-    endTurn(): Promise<TurnSummary>;
-    isInTurn(): boolean;
-    getCurrentTurnId(): string | null;
-    beforeWrite(filePath: string): Promise<boolean>;
-    getTrackedFiles(): string[];
-    isTracking(filePath: string): boolean;
-    getDiff(): Promise<string | null>;
-    getFileDiff(filePath: string): Promise<string | null>;
-    undoTurn(): Promise<UndoResult>;
-    undoFiles(filePaths: string[]): Promise<UndoResult>;
-    private computeFileChange;
-    private isInGitRepo;
-}
-declare function createTurnTracker(config: TurnTrackerConfig): TurnChangeTracker;
-
-export { type FileBaseline as F, TurnChangeTracker as T, type UndoResult as U, type TurnFileChange as a, type TurnSummary as b, type TurnTrackerConfig as c, createTurnTracker as d };

package/dist/tracking/index.d.ts

@@ -1,111 +0,0 @@
-import { T as TurnChangeTracker } from '../tracker-DClqYqTj.js';
-export { F as FileBaseline, a as TurnFileChange, b as TurnSummary, c as TurnTrackerConfig, U as UndoResult, d as createTurnTracker } from '../tracker-DClqYqTj.js';
-import { F as FileOperationMeta } from '../tool-DkhSCV2Y.js';
-import '../types-CHiPh8U2.js';
-import '../types-CQL-SvTn.js';
-
-/**
- * Checkpoint system contracts for @cuylabs/agent-core.
- */
-/** Configuration for creating a checkpoint manager. */
-interface CheckpointConfig {
-    /** Working directory to track (absolute path) */
-    workDir: string;
-    /** Optional custom storage directory */
-    storageDir?: string;
-    /** Whether to track file contents (enables restore). Default: true */
-    trackContent?: boolean;
-    /** Patterns to exclude from tracking (gitignore format) */
-    exclude?: string[];
-    /** Maximum number of checkpoints to retain. Default: 100 */
-    maxCheckpoints?: number;
-}
-/** A saved checkpoint representing a point-in-time state. */
-interface Checkpoint {
-    /** Unique checkpoint identifier (git tree hash) */
-    id: string;
-    /** Human-readable label */
-    label: string;
-    /** When the checkpoint was created */
-    createdAt: Date;
-    /** Optional metadata */
-    metadata?: Record<string, unknown>;
-}
-/** File change information between checkpoints. */
-interface FileChange {
-    /** Relative file path */
-    path: string;
-    /** Type of change */
-    type: "added" | "modified" | "deleted";
-    /** Lines added (for text files) */
-    additions?: number;
-    /** Lines removed (for text files) */
-    deletions?: number;
-}
-/** Changes detected between a checkpoint and current state. */
-interface ChangeSet {
-    /** Checkpoint being compared from */
-    fromCheckpoint: string;
-    /** List of changed files */
-    files: FileChange[];
-    /** Unified diff output */
-    diff: string;
-}
-/** Checkpoint manager interface. */
-interface CheckpointManager {
-    /** Save current state as a checkpoint */
-    save(label?: string, metadata?: Record<string, unknown>): Promise<Checkpoint>;
-    /** Restore all files to a checkpoint state */
-    restore(checkpointId: string): Promise<void>;
-    /** Get changes since a checkpoint */
-    changes(checkpointId: string): Promise<ChangeSet>;
-    /** Undo changes to specific files (restore them from checkpoint) */
-    undoFiles(checkpointId: string, files: string[]): Promise<void>;
-    /** List all checkpoints (newest first) */
-    list(): Promise<Checkpoint[]>;
-    /** Delete a specific checkpoint */
-    remove(checkpointId: string): Promise<void>;
-    /** Prune old checkpoints beyond maxCheckpoints limit */
-    prune(): Promise<number>;
-    /** Get the latest checkpoint */
-    latest(): Promise<Checkpoint | null>;
-    /** Get file content at a specific checkpoint */
-    getFileAt(checkpointId: string, filePath: string): Promise<string | null>;
-    /** Check if manager is initialized */
-    isInitialized(): boolean;
-    /** Close and cleanup resources */
-    close(): Promise<void>;
-}
-
-/**
- * Creates a checkpoint manager for tracking file state changes.
- */
-declare function createCheckpointManager(config: CheckpointConfig): Promise<CheckpointManager>;
-/**
- * Clear all checkpoint data for a working directory.
- */
-declare function clearCheckpoints(workDir: string): Promise<void>;
-
-/**
- * Extended tool metadata with file operation info.
- */
-interface TrackedToolMetadata {
-    /** File operation metadata for auto-tracking */
-    fileOps?: FileOperationMeta;
-    /** Other metadata */
-    [key: string]: unknown;
-}
-/**
- * Extract file paths from tool arguments based on metadata.
- */
-declare function extractFilePathsFromArgs(args: Record<string, unknown>, meta: FileOperationMeta): string[];
-/**
- * Check whether a tool operation should trigger baseline capture.
- */
-declare function shouldCaptureBaseline(meta: FileOperationMeta): boolean;
-/**
- * Wrap a tool execute function with automatic file tracking.
- */
-declare function withFileTracking<T extends (...args: unknown[]) => Promise<unknown>>(tracker: TurnChangeTracker, meta: FileOperationMeta, execute: T): T;
-
-export { type ChangeSet, type Checkpoint, type CheckpointConfig, type CheckpointManager, type FileChange, type TrackedToolMetadata, TurnChangeTracker, clearCheckpoints, createCheckpointManager, extractFilePathsFromArgs, shouldCaptureBaseline, withFileTracking };

package/dist/tracking/index.js

@@ -1,20 +0,0 @@
-import {
-  TurnChangeTracker,
-  clearCheckpoints,
-  createCheckpointManager,
-  createTurnTracker
-} from "../chunk-OFDKHNCX.js";
-import {
-  extractFilePathsFromArgs,
-  shouldCaptureBaseline,
-  withFileTracking
-} from "../chunk-VEKUXUVF.js";
-export {
-  TurnChangeTracker,
-  clearCheckpoints,
-  createCheckpointManager,
-  createTurnTracker,
-  extractFilePathsFromArgs,
-  shouldCaptureBaseline,
-  withFileTracking
-};

package/dist/types-BfNpU8NS.d.ts

@@ -1,270 +0,0 @@
-/**
- * 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.
- */
-type SkillScope = "project" | "user" | "global" | "builtin";
-/**
- * How a skill was obtained — local filesystem or remote URL.
- */
-type SkillSourceType = "local" | "remote";
-/**
- * Where a skill came from, for provenance tracking.
- */
-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
- */
-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.
- */
-interface SkillResource {
-    /** Path relative to the skill's base directory */
-    relativePath: string;
-    /** Classified resource type */
-    type: SkillResourceType;
-    /** Absolute path on disk (for local resources) */
-    absolutePath: 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.
- */
-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 */
-    filePath: string;
-    /** Directory containing the skill (parent of SKILL.md) */
-    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.
- */
-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,
- * };
- * ```
- */
-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"]
- *     }
- *   ]
- * }
- * ```
- */
-interface RemoteSkillIndex {
-    /** Schema version (currently 1) */
-    version: number;
-    /** List of available skills */
-    skills: RemoteSkillEntry[];
-}
-/**
- * A single skill listing in a remote index.
- */
-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.
- */
-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.
- */
-interface SkillDiscoveryError {
-    /** Path that caused the error */
-    path: string;
-    /** What went wrong */
-    reason: string;
-}
-
-export type { RemoteSkillEntry as R, SkillDiscoveryResult as S, SkillMetadata as a, SkillContent as b, SkillResource as c, SkillConfig as d, RemoteSkillIndex as e, SkillDiscoveryError as f, SkillResourceType as g, SkillScope as h, SkillSource as i, SkillSourceType as j };