@cuylabs/agent-core 4.9.0 → 5.0.0

package/dist/tracking/index.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Tracking Module
+ *
+ * - `turn-tracker` — per-turn file change tracking and diffs
+ * - `file-tracking` — helpers for tool-level file operation capture
+ */
+export { TurnChangeTracker, createTurnTracker, type UndoResult, } from "./turn-tracker/index.js";
+export { extractFilePathsFromArgs, shouldCaptureBaseline, } from "./file-tracking.js";
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/tracking/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EACL,iBAAiB,EACjB,iBAAiB,EACjB,KAAK,UAAU,GAChB,MAAM,yBAAyB,CAAC;AAEjC,OAAO,EACL,wBAAwB,EACxB,qBAAqB,GACtB,MAAM,oBAAoB,CAAC"}

package/dist/tracking/turn-tracker/diff.d.ts

@@ -0,0 +1,11 @@
+import type { FileBaseline, TurnFileChange } from "./types.js";
+export declare function captureTurnFileBaseline(absPath: string): Promise<FileBaseline>;
+export declare function restoreTurnTrackedFile(absPath: string, baseline: FileBaseline): Promise<void>;
+export declare function computeTurnTrackerFileChange(options: {
+    cwd: string;
+    absPath: string;
+    baseline: FileBaseline;
+    preferGitDiff: boolean;
+    canUseGitDiff: boolean;
+}): Promise<TurnFileChange>;
+//# sourceMappingURL=diff.d.ts.map

package/dist/tracking/turn-tracker/diff.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"diff.d.ts","sourceRoot":"","sources":["../../../src/tracking/turn-tracker/diff.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,YAAY,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAE/D,wBAAsB,uBAAuB,CAC3C,OAAO,EAAE,MAAM,GACd,OAAO,CAAC,YAAY,CAAC,CAwBvB;AAED,wBAAsB,sBAAsB,CAC1C,OAAO,EAAE,MAAM,EACf,QAAQ,EAAE,YAAY,GACrB,OAAO,CAAC,IAAI,CAAC,CAgBf;AAED,wBAAsB,4BAA4B,CAAC,OAAO,EAAE;IAC1D,GAAG,EAAE,MAAM,CAAC;IACZ,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,YAAY,CAAC;IACvB,aAAa,EAAE,OAAO,CAAC;IACvB,aAAa,EAAE,OAAO,CAAC;CACxB,GAAG,OAAO,CAAC,cAAc,CAAC,CAsC1B"}

package/dist/tracking/turn-tracker/index.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Turn-tracker module.
+ *
+ * Split by responsibility:
+ * - `types` defines the public turn-tracking contracts
+ * - `diff` owns file baseline/diff helpers
+ * - `tracker` owns the turn lifecycle and undo/diff orchestration
+ */
+export type { FileBaseline, TurnFileChange, TurnSummary, TurnTrackerConfig, UndoResult, } from "./types.js";
+export { TurnChangeTracker, createTurnTracker } from "./tracker.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/tracking/turn-tracker/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/tracking/turn-tracker/index.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,YAAY,EACV,YAAY,EACZ,cAAc,EACd,WAAW,EACX,iBAAiB,EACjB,UAAU,GACX,MAAM,YAAY,CAAC;AAEpB,OAAO,EAAE,iBAAiB,EAAE,iBAAiB,EAAE,MAAM,cAAc,CAAC"}

package/dist/tracking/turn-tracker/tracker.d.ts

@@ -0,0 +1,31 @@
+/**
+ * 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.
+ */
+import type { TurnSummary, TurnTrackerConfig, UndoResult } from "./types.js";
+import type { Logger } from "../../logger/types.js";
+export declare class TurnChangeTracker {
+    private config;
+    private currentTurn;
+    private gitDetected;
+    private readonly log;
+    constructor(config: TurnTrackerConfig, logger?: Logger);
+    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;
+}
+export declare function createTurnTracker(config: TurnTrackerConfig, logger?: Logger): TurnChangeTracker;
+//# sourceMappingURL=tracker.d.ts.map

package/dist/tracking/turn-tracker/tracker.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tracker.d.ts","sourceRoot":"","sources":["../../../src/tracking/turn-tracker/tracker.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AASH,OAAO,KAAK,EAGV,WAAW,EACX,iBAAiB,EACjB,UAAU,EACX,MAAM,YAAY,CAAC;AACpB,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,uBAAuB,CAAC;AAUpD,qBAAa,iBAAiB;IAC5B,OAAO,CAAC,MAAM,CAA8B;IAC5C,OAAO,CAAC,WAAW,CAA0B;IAC7C,OAAO,CAAC,WAAW,CAAwB;IAC3C,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAS;gBAEjB,MAAM,EAAE,iBAAiB,EAAE,MAAM,CAAC,EAAE,MAAM;IAStD,SAAS,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI;IAazB,OAAO,IAAI,OAAO,CAAC,WAAW,CAAC;IA4CrC,QAAQ,IAAI,OAAO;IAInB,gBAAgB,IAAI,MAAM,GAAG,IAAI;IAI3B,WAAW,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAwBrD,eAAe,IAAI,MAAM,EAAE;IAU3B,UAAU,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO;IAS/B,OAAO,IAAI,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC;IAgBjC,WAAW,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC;IAerD,QAAQ,IAAI,OAAO,CAAC,UAAU,CAAC;IAuB/B,SAAS,CAAC,SAAS,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,UAAU,CAAC;YAkC3C,iBAAiB;YAajB,WAAW;CA0B1B;AAED,wBAAgB,iBAAiB,CAC/B,MAAM,EAAE,iBAAiB,EACzB,MAAM,CAAC,EAAE,MAAM,GACd,iBAAiB,CAEnB"}

package/dist/tracking/turn-tracker/types.d.ts

@@ -0,0 +1,66 @@
+/**
+ * Turn-tracker contracts for @cuylabs/agent-core.
+ */
+/** Configuration for turn tracking. */
+export 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. */
+export 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. */
+export 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. */
+export 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. */
+export interface UndoResult {
+    /** Files restored */
+    restored: string[];
+    /** Files that could not be restored */
+    failed: Array<{
+        path: string;
+        reason: string;
+    }>;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/tracking/turn-tracker/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/tracking/turn-tracker/types.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,uCAAuC;AACvC,MAAM,WAAW,iBAAiB;IAChC,6EAA6E;IAC7E,GAAG,EAAE,MAAM,CAAC;IACZ,0EAA0E;IAC1E,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,oDAAoD;IACpD,eAAe,CAAC,EAAE,MAAM,CAAC;CAC1B;AAED,kDAAkD;AAClD,MAAM,WAAW,YAAY;IAC3B,oBAAoB;IACpB,IAAI,EAAE,MAAM,CAAC;IACb,+DAA+D;IAC/D,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB,8BAA8B;IAC9B,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IACpB,oDAAoD;IACpD,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IACpB,iCAAiC;IACjC,UAAU,EAAE,IAAI,CAAC;CAClB;AAED,wCAAwC;AACxC,MAAM,WAAW,cAAc;IAC7B,+BAA+B;IAC/B,IAAI,EAAE,MAAM,CAAC;IACb,qBAAqB;IACrB,IAAI,EAAE,SAAS,GAAG,UAAU,GAAG,SAAS,GAAG,WAAW,CAAC;IACvD,kBAAkB;IAClB,SAAS,EAAE,MAAM,CAAC;IAClB,oBAAoB;IACpB,SAAS,EAAE,MAAM,CAAC;IAClB,iCAAiC;IACjC,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED,mCAAmC;AACnC,MAAM,WAAW,WAAW;IAC1B,sBAAsB;IACtB,MAAM,EAAE,MAAM,CAAC;IACf,oBAAoB;IACpB,KAAK,EAAE,cAAc,EAAE,CAAC;IACxB,0BAA0B;IAC1B,YAAY,EAAE,MAAM,CAAC;IACrB,uCAAuC;IACvC,SAAS,EAAE,MAAM,CAAC;IAClB,uCAAuC;IACvC,SAAS,EAAE,MAAM,CAAC;IAClB,4CAA4C;IAC5C,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IACpB,0BAA0B;IAC1B,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED,gCAAgC;AAChC,MAAM,WAAW,UAAU;IACzB,qBAAqB;IACrB,QAAQ,EAAE,MAAM,EAAE,CAAC;IACnB,uCAAuC;IACvC,MAAM,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;CACjD"}

package/dist/types/compaction.d.ts

@@ -0,0 +1,191 @@
+import type { LanguageModel } from "ai";
+export type ContextSummaryMode = "required" | "best-effort" | "disabled";
+export type CompactionTrigger = "auto" | "manual" | "recovery";
+export type CompactionReason = "context-limit" | "provider-overflow" | "manual-request";
+/**
+ * Tools whose outputs should never be pruned automatically.
+ */
+export declare const PRUNE_PROTECTED_TOOLS: readonly ["skill"];
+export interface ToolContextPrunePolicy {
+    /** Compact tool outputs larger than this estimated token count. */
+    outputThresholdTokens?: number;
+    /** Compact tool-call arguments larger than this estimated token count. */
+    argumentThresholdTokens?: number;
+    /** Short argument preview included in compacted tool-output placeholders. */
+    argumentPreviewChars?: number;
+    /** Maximum characters retained for a large string argument. */
+    argumentMaxStringChars?: number;
+    /** Characters retained from the beginning of a large string argument. */
+    argumentStringHeadChars?: number;
+    /** Characters retained from the end of a large string argument. */
+    argumentStringTailChars?: number;
+    /** Array items retained from the beginning of large argument arrays. */
+    argumentArrayHeadItems?: number;
+    /** Array items retained from the end of large argument arrays. */
+    argumentArrayTailItems?: number;
+    /** Object keys retained before replacing the rest with an omission marker. */
+    argumentObjectMaxKeys?: number;
+    /** Maximum argument traversal depth before replacing a nested value. */
+    argumentMaxDepth?: number;
+}
+/**
+ * Measured result of a context-window compaction pass.
+ */
+export interface CompactionEffectiveness {
+    /** Estimated tokens before compaction. */
+    tokensBefore: number;
+    /** Estimated tokens after compaction. */
+    tokensAfter: number;
+    /** Estimated tokens removed. */
+    tokensRemoved: number;
+    /** Fraction of the original context removed, from 0 to 1. */
+    savingsRatio: number;
+    /**
+     * Whether the pass saved enough context to be operationally meaningful.
+     *
+     * A pass can still be marked as applied while not effective, for example
+     * when only a tiny duplicated tool output was compacted.
+     */
+    effective: boolean;
+}
+/**
+ * Why a compaction cut boundary was chosen.
+ */
+export type CompactionCutReason = "protected-window" | "latest-user" | "tool-boundary" | "turn-boundary" | "split-turn-prefix" | "no-safe-cut";
+/**
+ * Recovery settings for automatic context compaction.
+ */
+export interface CompactionRecoveryConfig {
+    /**
+     * Enable recovery around model steps.
+     *
+     * When enabled, the chat loop can compact before a model call and retry
+     * after a provider reports context overflow.
+     *
+     * Default: follows `compaction.auto`
+     */
+    enabled?: boolean;
+    /**
+     * Compact before each model step when the session is already over the
+     * usable context limit.
+     *
+     * Default: true
+     */
+    compactBeforeStep?: boolean;
+    /**
+     * Number of times to compact and retry the same model step after a provider
+     * context-overflow error.
+     *
+     * Default: 2
+     */
+    maxRetries?: number;
+}
+/**
+ * Configuration for automatic context compaction.
+ */
+export interface CompactionConfig {
+    /**
+     * Enable automatic compaction when context overflows.
+     * Default: true
+     */
+    auto?: boolean;
+    /**
+     * Enable pruning of old tool context before summarization.
+     * Default: true
+     */
+    prune?: boolean;
+    /**
+     * Tune the cheap tool-context pruning pass.
+     *
+     * This only affects deterministic replacement of old large tool outputs and
+     * large tool-call arguments. It does not change conversation cutting or
+     * summary generation.
+     */
+    toolPruning?: ToolContextPrunePolicy;
+    /**
+     * Percentage of the model context window considered usable for input.
+     *
+     * This gives context management a named safety margin for provider/tool
+     * overhead and token-estimation error. The output reserve is still applied
+     * after this margin.
+     *
+     * Default: 95
+     */
+    effectiveContextWindowPercent?: number;
+    /**
+     * Estimated token threshold that triggers automatic compaction.
+     *
+     * When unset, compaction starts at the usable input limit. When set, the
+     * threshold is clamped to that usable limit.
+     */
+    autoCompactTokenLimit?: number;
+    /**
+     * Protect this many recent tokens from pruning.
+     * Default: 40,000
+     */
+    protectedTokens?: number;
+    /**
+     * Minimum tokens to trigger pruning.
+     * Default: 20,000
+     */
+    pruneMinimum?: number;
+    /**
+     * Custom summarization prompt for compaction.
+     */
+    summaryPrompt?: string;
+    /**
+     * Maximum output tokens requested when generating a compaction summary.
+     *
+     * This acts as the model output cap for summary calls. The runtime also
+     * clamps the request to the reserved output budget.
+     *
+     * Default: 2,000
+     */
+    summaryMaxOutputTokens?: number;
+    /**
+     * Maximum estimated input tokens sent to the summary model.
+     *
+     * Removed history is serialized with per-message and total caps before the
+     * summary call. This prevents compaction itself from creating an oversized
+     * model request when old tool context or file contents are very large.
+     *
+     * Default: 24,000
+     */
+    summaryMaxInputTokens?: number;
+    /**
+     * Optional proportional target for summary size based on removed content.
+     *
+     * When unset, summaries use `summaryMaxOutputTokens`. When set, the target
+     * is `removedTokens * summaryTargetRatio`, clamped by
+     * `summaryMaxOutputTokens` and the reserved output budget.
+     */
+    summaryTargetRatio?: number;
+    /**
+     * Summary behavior when conversation history must be cut.
+     *
+     * `required` uses the summary model and fails the compaction if the summary
+     * cannot be produced. `best-effort` can fall back to a deterministic handoff
+     * summary. `disabled` cuts history without an LLM summary.
+     *
+     * Default: `required`
+     */
+    summaryMode?: ContextSummaryMode;
+    /**
+     * Model to use for summarization. Defaults to the agent model.
+     */
+    summaryModel?: LanguageModel;
+    /**
+     * Auto-continue after compaction with a continuation prompt.
+     *
+     * When `recovery.enabled` is unset, this also controls whether
+     * context-overflow recovery is enabled.
+     *
+     * Default: true
+     */
+    autoContinue?: boolean;
+    /**
+     * Model-step compaction and context-overflow recovery behavior.
+     */
+    recovery?: CompactionRecoveryConfig;
+}
+//# sourceMappingURL=compaction.d.ts.map

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

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

package/dist/types/doom-loop.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Doom-loop handling contracts for repeated tool invocations.
+ */
+/**
+ * Response from a doom-loop handler.
+ */
+export type DoomLoopAction = "allow" | "deny" | "remember";
+/**
+ * Doom-loop detection request.
+ */
+export interface DoomLoopRequest {
+    /** The tool being called repeatedly */
+    tool: string;
+    /** How many times it has been called with the same input */
+    repeatCount: number;
+    /** The repeated input */
+    input: unknown;
+    /** Session ID */
+    sessionId: string;
+}
+/**
+ * Handler for doom-loop situations.
+ */
+export type DoomLoopHandler = (request: DoomLoopRequest) => Promise<DoomLoopAction>;
+//# sourceMappingURL=doom-loop.d.ts.map

package/dist/types/doom-loop.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"doom-loop.d.ts","sourceRoot":"","sources":["../../src/types/doom-loop.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH;;GAEG;AACH,MAAM,MAAM,cAAc,GAAG,OAAO,GAAG,MAAM,GAAG,UAAU,CAAC;AAE3D;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B,uCAAuC;IACvC,IAAI,EAAE,MAAM,CAAC;IACb,4DAA4D;IAC5D,WAAW,EAAE,MAAM,CAAC;IACpB,yBAAyB;IACzB,KAAK,EAAE,OAAO,CAAC;IACf,iBAAiB;IACjB,SAAS,EAAE,MAAM,CAAC;CACnB;AAED;;GAEG;AACH,MAAM,MAAM,eAAe,GAAG,CAC5B,OAAO,EAAE,eAAe,KACrB,OAAO,CAAC,cAAc,CAAC,CAAC"}

package/dist/types/events.d.ts

@@ -0,0 +1,196 @@
+/**
+ * Event types for @cuylabs/agent-core
+ *
+ * Defines the event model emitted during agent execution,
+ * including status updates, tool events, and streaming events.
+ */
+import type { TokenUsage, Message } from "./messages.js";
+import type { CompactionCutReason, CompactionEffectiveness, CompactionReason, CompactionTrigger } from "./compaction.js";
+import type { ContextCompactionDecision } from "../context/window/decision.js";
+import type { ToolMetadata } from "./tool.js";
+import type { TeamEvent } from "../team/events.js";
+import type { ApprovalDecision, ApprovalRememberScope } from "../safety/types.js";
+import type { HumanInputRequest, HumanInputResponse } from "../human/index.js";
+/** Agent status for UI display */
+export type AgentStatus = "idle" | "processing" | "thinking" | "reasoning" | "calling-tool" | "waiting-approval" | "waiting-input" | "error";
+/** Approval request for UI */
+export interface ApprovalEvent {
+    id: string;
+    tool: string;
+    args: unknown;
+    description: string;
+    risk: "safe" | "moderate" | "dangerous";
+    rememberScopes?: ApprovalRememberScope[];
+    defaultRememberScope?: ApprovalRememberScope;
+}
+export interface HumanInputEvent {
+    id: string;
+    kind: HumanInputRequest["kind"];
+    title: string;
+    question: string;
+    options?: HumanInputRequest["options"];
+    allowMultiple?: boolean;
+    placeholder?: string;
+    confirmLabel?: string;
+    denyLabel?: string;
+}
+/** Neutral turn-commit boundaries for runtime/durability integrations */
+export type AgentTurnBoundaryKind = "input-commit-start" | "input-commit-finish" | "intervention-commit-start" | "intervention-commit-finish" | "step-commit-start" | "step-commit-finish" | "output-commit-start" | "output-commit-finish";
+export type AgentContextCompactionPhase = "pre-step" | "recovery" | "post-turn" | "manual";
+/**
+ * Events emitted during agent execution
+ *
+ * These events are designed for UI consumption:
+ * - status: Overall agent state for status indicators
+ * - approval-request: User confirmation needed
+ * - progress: Step counts for progress bars
+ */
+export type AgentEvent = {
+    type: "status";
+    status: AgentStatus;
+} | {
+    type: "approval-request";
+    request: ApprovalEvent;
+} | {
+    type: "approval-resolved";
+    id: string;
+    action: ApprovalDecision["action"];
+    feedback?: string;
+    rememberScope?: ApprovalRememberScope;
+} | {
+    type: "human-input-request";
+    request: HumanInputEvent;
+} | {
+    type: "human-input-resolved";
+    id: string;
+    response: HumanInputResponse;
+} | {
+    type: "step-start";
+    step: number;
+    maxSteps: number;
+} | {
+    type: "step-finish";
+    step: number;
+    usage?: TokenUsage;
+    finishReason?: string;
+} | {
+    type: "turn-boundary";
+    boundary: AgentTurnBoundaryKind;
+    step?: number;
+    messageRole?: Message["role"];
+    pendingToolCallCount?: number;
+} | {
+    type: "message";
+    message: Message;
+} | {
+    type: "text-start";
+} | {
+    type: "text-delta";
+    text: string;
+} | {
+    type: "text-end";
+} | {
+    type: "reasoning-start";
+    id: string;
+} | {
+    type: "reasoning-delta";
+    id: string;
+    text: string;
+} | {
+    type: "reasoning-end";
+    id: string;
+} | {
+    type: "tool-start";
+    toolName: string;
+    toolCallId: string;
+    input: unknown;
+} | {
+    type: "tool-result";
+    toolName: string;
+    toolCallId: string;
+    result: unknown;
+    metadata?: ToolMetadata;
+} | {
+    type: "tool-error";
+    toolName: string;
+    toolCallId: string;
+    error: string;
+} | {
+    type: "computer-call";
+    callId: string;
+    action: unknown;
+    pendingSafetyChecks?: unknown[];
+} | {
+    type: "computer-result";
+    callId: string;
+    result: unknown;
+} | {
+    type: "intervention-applied";
+    id: string;
+    message: string;
+} | {
+    type: "follow-up-queued";
+    id: string;
+    message: string;
+} | {
+    type: "doom-loop";
+    toolName: string;
+    repeatCount: number;
+} | {
+    type: "context-overflow";
+    inputTokens: number;
+    limit: number;
+} | {
+    type: "context-compaction";
+    phase: AgentContextCompactionPhase;
+    trigger?: CompactionTrigger;
+    reason?: CompactionReason;
+    inputTokens: number;
+    limit: number;
+    decision: ContextCompactionDecision;
+    effectiveness: CompactionEffectiveness;
+    removedCount: number;
+    tokensRemoved: number;
+    summarized: boolean;
+    cutReason?: CompactionCutReason;
+    retryAttempt?: number;
+} | {
+    type: "turn-summary";
+    turnId: string;
+    files: Array<{
+        path: string;
+        type: "created" | "modified" | "deleted" | "unchanged";
+        additions: number;
+        deletions: number;
+    }>;
+    additions: number;
+    deletions: number;
+} | {
+    type: "retry";
+    attempt: number;
+    delayMs: number;
+    error: Error;
+} | {
+    type: "error";
+    error: Error;
+} | {
+    type: "complete";
+    usage?: TokenUsage;
+    output?: string;
+} | TeamEvent;
+/**
+ * Step-processing result - what happens after reducing one streamed step
+ */
+export type StepProcessingResult = "continue" | "stop" | "compact";
+/**
+ * Stream input for model inference
+ */
+export interface StreamInput {
+    sessionID: string;
+    model: import("ai").LanguageModel;
+    system: string[];
+    messages: import("ai").ModelMessage[];
+    abort: AbortSignal;
+    tools: Record<string, unknown>;
+}
+//# sourceMappingURL=events.d.ts.map

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

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

package/dist/types/index.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Core types barrel for @cuylabs/agent-core
+ *
+ * Re-exports all shared type modules in a single entry point.
+ * Internal modules import from "./types/index.js".
+ */
+export type { TurnTrackerContext, ToolContext, ToolResult, FileOperationMeta, ToolHostRequirements, ToolMetadata, ToolReplayMode, ToolSideEffectLevel, ToolReplayPolicy, NormalizedToolReplayPolicy, ToolCapabilities, InputCheckResult, } from "./tool.js";
+export { resolveCapability, requiresToolHost, getRequiredToolHost, } from "./tool.js";
+export type { MessageRole, MessageBase, UserMessage, AssistantMessage, ToolMessage, SystemMessage, Message, MessageError, TokenUsage, Session, } from "./messages.js";
+export { accumulateUsage } from "./messages.js";
+export type { StreamChunk, StreamProvider, StreamProviderInput, StreamProviderResult, StreamProviderConfig, StreamProviderFactory, EnhancedTools, } from "./stream.js";
+export type { AgentStatus, ApprovalEvent, AgentEvent, AgentTurnBoundaryKind, StepProcessingResult, StreamInput, } from "./events.js";
+export type { AgentTurnSource, AgentTurnSourceChatOptions, } from "./turn-source.js";
+export { PRUNE_PROTECTED_TOOLS } from "./compaction.js";
+export type { CompactionConfig, CompactionCutReason, CompactionEffectiveness, CompactionReason, CompactionTrigger, ToolContextPrunePolicy, } from "./compaction.js";
+export type { DoomLoopAction, DoomLoopRequest, DoomLoopHandler, } from "./doom-loop.js";
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/types/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAGH,YAAY,EACV,kBAAkB,EAClB,WAAW,EACX,UAAU,EACV,iBAAiB,EACjB,oBAAoB,EACpB,YAAY,EACZ,cAAc,EACd,mBAAmB,EACnB,gBAAgB,EAChB,0BAA0B,EAC1B,gBAAgB,EAChB,gBAAgB,GACjB,MAAM,WAAW,CAAC;AAEnB,OAAO,EACL,iBAAiB,EACjB,gBAAgB,EAChB,mBAAmB,GACpB,MAAM,WAAW,CAAC;AAGnB,YAAY,EACV,WAAW,EACX,WAAW,EACX,WAAW,EACX,gBAAgB,EAChB,WAAW,EACX,aAAa,EACb,OAAO,EACP,YAAY,EACZ,UAAU,EACV,OAAO,GACR,MAAM,eAAe,CAAC;AACvB,OAAO,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AAGhD,YAAY,EACV,WAAW,EACX,cAAc,EACd,mBAAmB,EACnB,oBAAoB,EACpB,oBAAoB,EACpB,qBAAqB,EACrB,aAAa,GACd,MAAM,aAAa,CAAC;AAGrB,YAAY,EACV,WAAW,EACX,aAAa,EACb,UAAU,EACV,qBAAqB,EACrB,oBAAoB,EACpB,WAAW,GACZ,MAAM,aAAa,CAAC;AAGrB,YAAY,EACV,eAAe,EACf,0BAA0B,GAC3B,MAAM,kBAAkB,CAAC;AAG1B,OAAO,EAAE,qBAAqB,EAAE,MAAM,iBAAiB,CAAC;AACxD,YAAY,EACV,gBAAgB,EAChB,mBAAmB,EACnB,uBAAuB,EACvB,gBAAgB,EAChB,iBAAiB,EACjB,sBAAsB,GACvB,MAAM,iBAAiB,CAAC;AACzB,YAAY,EACV,cAAc,EACd,eAAe,EACf,eAAe,GAChB,MAAM,gBAAgB,CAAC"}