@cuylabs/agent-core 0.3.0 → 0.5.0

package/dist/tracker-DClqYqTj.d.ts

@@ -0,0 +1,96 @@
+/**
+ * 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

@@ -0,0 +1,109 @@
+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-DYp6-cC3.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

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

package/dist/types-CQaXbRsS.d.ts

@@ -0,0 +1,47 @@
+/**
+ * Reasoning Types & Constants
+ *
+ * Shared type definitions, level constants, and small helpers
+ * used across the reasoning subsystem.
+ */
+/**
+ * Standard reasoning / thinking levels.
+ *
+ * | Level      | Description                        |
+ * |------------|------------------------------------|
+ * | `"off"`    | No reasoning (fastest)             |
+ * | `"minimal"`| Very light reasoning               |
+ * | `"low"`    | Light reasoning                    |
+ * | `"medium"` | Balanced reasoning                 |
+ * | `"high"`   | Deep reasoning                     |
+ * | `"xhigh"`  | Maximum reasoning (where supported)|
+ */
+type ReasoningLevel = "off" | "minimal" | "low" | "medium" | "high" | "xhigh";
+/**
+ * Provider-specific reasoning configuration returned by
+ * {@link getReasoningConfig} / {@link getReasoningConfigSync}.
+ */
+interface ReasoningConfig {
+    /** Whether the model supports reasoning at all */
+    supportsReasoning: boolean;
+    /** Reasoning levels available for this model */
+    availableLevels: ReasoningLevel[];
+    /** Build provider options for a given level */
+    getProviderOptions: (level: ReasoningLevel) => Record<string, unknown> | undefined;
+}
+/** Standard four-level set used by most providers. */
+declare const STANDARD_LEVELS: ReasoningLevel[];
+/** Extended set for advanced models (e.g. o3, o4, GPT-5). */
+declare const EXTENDED_LEVELS: ReasoningLevel[];
+/** Fixed set for models whose reasoning level is not adjustable. */
+declare const FIXED_LEVELS: ReasoningLevel[];
+/**
+ * Check whether reasoning summaries should be included in responses.
+ *
+ * Controlled by the `CODE_AGENT_DISABLE_REASONING_SUMMARY` environment
+ * variable. Summaries require a verified OpenAI organisation — set the
+ * env var to `"true"` to disable them.
+ */
+declare function shouldIncludeReasoningSummary(): boolean;
+
+export { EXTENDED_LEVELS as E, FIXED_LEVELS as F, type ReasoningLevel as R, STANDARD_LEVELS as S, type ReasoningConfig as a, shouldIncludeReasoningSummary as s };