@cuylabs/agent-core 0.8.0 → 0.10.0

package/dist/context/index.d.ts

@@ -1,259 +0,0 @@
-import { M as Message } from '../messages-BYWGn8TY.js';
-import { ModelMessage, LanguageModel } from 'ai';
-
-/**
- * Token Estimation Utilities
- *
- * Provides lightweight heuristic-based token counting for messages
- * and conversations. Uses the chars/4 approximation — simple but
- * effective for context-window planning decisions.
- *
- * These are *estimates*, not exact counts. For billing or hard limits,
- * use the provider's native tokeniser instead.
- */
-
-/**
- * Estimate token count for a plain string.
- *
- * Uses the widely-accepted `chars / 4` heuristic.
- *
- * @param text - Text to estimate
- * @returns Estimated token count (always ≥ 1 for non-empty input)
- */
-declare function estimateTokens(text: string): number;
-/**
- * Estimate token count for a single message.
- *
- * Handles:
- * - Plain string content
- * - Multi-part / multimodal arrays (text parts + images)
- *
- * @param message - A `Message` (internal) or `ModelMessage` (AI SDK)
- * @returns Estimated token count
- */
-declare function estimateMessageTokens(message: Message | ModelMessage): number;
-/**
- * Estimate total tokens for an entire conversation.
- *
- * Adds a small per-message overhead (≈ 4 tokens) for message
- * framing (`role`, delimiters, etc.).
- *
- * @param messages - Array of messages to estimate
- * @returns Estimated total token count
- */
-declare function estimateConversationTokens(messages: (Message | ModelMessage)[]): number;
-
-/**
- * Context Overflow Detection & Pruning
- *
- * Detects when a conversation is approaching the model's context-window
- * limit and prunes old / redundant content to stay within bounds.
- *
- * Two pruning strategies are available:
- * 1. **Tool-result pruning** — replaces large, stale tool outputs with
- *    compact placeholders (lightweight, no model call).
- * 2. **Conversation cutting** — identifies a safe cut-point and removes
- *    older messages entirely (optionally summarised by the manager).
- */
-
-/**
- * Context limits configuration.
- *
- * All values are in *estimated* tokens (see {@link estimateTokens}).
- */
-interface ContextLimits {
-    /** Maximum context window size in tokens */
-    contextWindow: number;
-    /** Reserve tokens for output generation */
-    reserveTokens: number;
-    /** Protect this many recent tokens from pruning */
-    protectedTokens: number;
-    /** Minimum tokens to trigger pruning (avoid pruning tiny contexts) */
-    pruneMinimum: number;
-}
-/**
- * Default context limits.
- * Based on typical 128 k context-window models.
- */
-declare const DEFAULT_CONTEXT_LIMITS: ContextLimits;
-/**
- * Check whether the context is overflowing.
- *
- * @param tokens - Current estimated token count
- * @param limits - Context limits (defaults to 128 k window)
- * @returns `true` if context exceeds the safe threshold
- */
-declare function isContextOverflowing(tokens: number, limits?: ContextLimits): boolean;
-/**
- * Check whether pruning should be triggered.
- *
- * Returns `false` when the conversation is still small enough that
- * pruning would be wasteful (below {@link ContextLimits.pruneMinimum}).
- */
-declare function shouldPruneContext(tokens: number, limits?: ContextLimits): boolean;
-/**
- * Result of a pruning operation.
- */
-interface PruneResult {
-    /** Messages after pruning (may include a summary message) */
-    messages: Message[];
-    /** Number of messages removed */
-    removedCount: number;
-    /** Estimated tokens removed */
-    tokensRemoved: number;
-    /** Whether summarisation was used */
-    summarized: boolean;
-    /** The summary content, if generated */
-    summary?: string;
-}
-/**
- * Find a safe index at which the conversation can be "cut".
- *
- * Rules:
- * - Never cut in the middle of a tool-call sequence
- * - Prefer cutting after assistant / user messages
- * - Keep at least {@link protectedTokens} tokens at the end
- *
- * @param messages       - Full message array
- * @param protectedTokens - Tokens to preserve at the end
- * @returns Cut index (exclusive — remove messages *before* this index).
- *          Returns `0` when no safe cut-point exists.
- */
-declare function findCutPoint(messages: Message[], protectedTokens?: number): number;
-/**
- * Prune old, large tool results from the conversation.
- *
- * Prune strategy:
- * - Walks backwards through messages
- * - Protects recent outputs (within {@link protectedTokens})
- * - Skips protected tools (e.g. "skill")
- * - Stamps pruned messages with a `compactedAt` timestamp
- *
- * @param messages       - Messages to prune
- * @param protectedTokens - Don't prune tool results in the last N tokens
- * @param options        - Extra tool names to protect
- * @returns New message array with large tool outputs replaced
- */
-declare function pruneToolResults(messages: Message[], protectedTokens?: number, options?: {
-    /** Additional tools to protect from pruning */
-    protectedTools?: string[];
-}): Message[];
-
-/**
- * Context Summarisation
- *
- * When tool-result pruning alone isn't enough to stay within the
- * context window, the manager can *cut* the conversation and replace
- * the removed portion with an LLM-generated summary.
- *
- * This module provides the summary-generation logic and the
- * top-level `pruneContext()` orchestration function.
- */
-
-/**
- * Options for summary generation.
- */
-interface SummarizationOptions {
-    /** Model used to generate the summary */
-    model: LanguageModel;
-    /** Max tokens for the summary output */
-    maxTokens?: number;
-    /** Custom summarisation system prompt */
-    customPrompt?: string;
-}
-/**
- * Options for {@link pruneContext}.
- */
-interface PruneContextOptions {
-    /** Model for summarisation (omit to skip summary generation) */
-    model?: LanguageModel;
-    /** Context limits to enforce */
-    limits?: ContextLimits;
-    /** Custom summarisation prompt */
-    summaryPrompt?: string;
-}
-/**
- * Generate a natural-language summary of a message sequence.
- *
- * @param messages - Messages to summarise
- * @param options  - Model & prompt configuration
- * @returns Summary text
- */
-declare function generateSummary(messages: Message[], options: SummarizationOptions): Promise<string>;
-/**
- * Prune a conversation to fit within context-window limits.
- *
- * Strategy (in order):
- * 1. Prune old tool outputs (lightweight, no model call)
- * 2. If still overflowing, find a safe cut-point and remove
- *    older messages — optionally generating an LLM summary.
- *
- * @param messages - Current message array
- * @param options  - Limits, model, and prompt overrides
- * @returns A {@link PruneResult} with the trimmed messages
- */
-declare function pruneContext(messages: Message[], options?: PruneContextOptions): Promise<PruneResult>;
-
-/**
- * Context Manager
- *
- * Stateful wrapper around the context-management primitives.
- * Tracks per-session context limits and provides a single entry
- * point for token estimation, overflow detection, and pruning.
- */
-
-/**
- * Per-session context manager.
- *
- * Holds the active context-window limits and provides convenience
- * methods for checking, reporting, and pruning context.
- *
- * @example
- * ```typescript
- * const ctx = new ContextManager({ limits: { contextWindow: 200_000 } });
- *
- * if (ctx.shouldPrune(messages)) {
- *   const result = await ctx.prune(messages);
- *   console.log(`Removed ${result.removedCount} messages`);
- * }
- * ```
- */
-declare class ContextManager {
-    private limits;
-    private model?;
-    private summaryPrompt?;
-    constructor(options?: {
-        limits?: Partial<ContextLimits>;
-        model?: LanguageModel;
-        summaryPrompt?: string;
-    });
-    /** Get a copy of the current context limits. */
-    getLimits(): ContextLimits;
-    /** Update context limits (e.g. when switching models). */
-    setLimits(limits: Partial<ContextLimits>): void;
-    /** Set the model used for summarisation. */
-    setModel(model: LanguageModel): void;
-    /** Estimate total tokens for a message array. */
-    estimateTokens(messages: (Message | ModelMessage)[]): number;
-    /** Check whether the context is overflowing. */
-    isOverflowing(messages: (Message | ModelMessage)[]): boolean;
-    /** Check whether pruning should be triggered. */
-    shouldPrune(messages: (Message | ModelMessage)[]): boolean;
-    /** Prune context to fit within limits. */
-    prune(messages: Message[]): Promise<PruneResult>;
-    /**
-     * Get a snapshot of token statistics.
-     *
-     * Useful for dashboards, logging, or deciding whether to prune.
-     */
-    getStats(messages: (Message | ModelMessage)[]): {
-        tokens: number;
-        limit: number;
-        available: number;
-        utilizationPercent: number;
-        isOverflowing: boolean;
-        shouldPrune: boolean;
-    };
-}
-
-export { type ContextLimits, ContextManager, DEFAULT_CONTEXT_LIMITS, type PruneContextOptions, type PruneResult, type SummarizationOptions, estimateConversationTokens, estimateMessageTokens, estimateTokens, findCutPoint, generateSummary, isContextOverflowing, pruneContext, pruneToolResults, shouldPruneContext };

package/dist/context/index.js

@@ -1,26 +0,0 @@
-import {
-  ContextManager,
-  DEFAULT_CONTEXT_LIMITS,
-  estimateConversationTokens,
-  estimateMessageTokens,
-  estimateTokens,
-  findCutPoint,
-  generateSummary,
-  isContextOverflowing,
-  pruneContext,
-  pruneToolResults,
-  shouldPruneContext
-} from "../chunk-WWYYNWEW.js";
-export {
-  ContextManager,
-  DEFAULT_CONTEXT_LIMITS,
-  estimateConversationTokens,
-  estimateMessageTokens,
-  estimateTokens,
-  findCutPoint,
-  generateSummary,
-  isContextOverflowing,
-  pruneContext,
-  pruneToolResults,
-  shouldPruneContext
-};

package/dist/events-CE72w8W4.d.ts

@@ -1,149 +0,0 @@
-import * as ai from 'ai';
-import { T as TokenUsage, M as Message } from './messages-BYWGn8TY.js';
-
-/** Agent status for UI display */
-type AgentStatus = "idle" | "processing" | "thinking" | "reasoning" | "calling-tool" | "waiting-approval" | "error";
-/** Approval request for UI */
-interface ApprovalEvent {
-    id: string;
-    tool: string;
-    args: unknown;
-    description: string;
-    risk: "safe" | "moderate" | "dangerous";
-}
-/** Neutral turn-commit boundaries for runtime/durability integrations */
-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";
-/**
- * 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
- */
-type AgentEvent = {
-    type: "status";
-    status: AgentStatus;
-} | {
-    type: "approval-request";
-    request: ApprovalEvent;
-} | {
-    type: "approval-resolved";
-    id: string;
-    action: "allow" | "deny" | "remember";
-} | {
-    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;
-} | {
-    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: "doom-loop";
-    toolName: string;
-    repeatCount: number;
-} | {
-    type: "context-overflow";
-    inputTokens: number;
-    limit: 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;
-};
-/**
- * Step-processing result - what happens after reducing one streamed step
- */
-type StepProcessingResult = "continue" | "stop" | "compact";
-/**
- * @deprecated Use `StepProcessingResult`.
- */
-type ProcessorResult = StepProcessingResult;
-/**
- * Stream input for model inference
- */
-interface StreamInput {
-    sessionID: string;
-    model: ai.LanguageModel;
-    system: string[];
-    messages: ai.ModelMessage[];
-    abort: AbortSignal;
-    tools: Record<string, unknown>;
-}
-
-export type { AgentEvent as A, ProcessorResult as P, StepProcessingResult as S, AgentStatus as a, AgentTurnBoundaryKind as b, ApprovalEvent as c, StreamInput as d };

package/dist/host/index.d.ts

@@ -1,45 +0,0 @@
-import { T as ToolHost } from '../types-CHiPh8U2.js';
-export { D as DirEntry, E as ExecOptions, a as ExecResult, F as FileStat } from '../types-CHiPh8U2.js';
-
-/**
- * LocalHost — executes tools on the local machine.
- *
- * Default ToolHost implementation. Uses Node's `child_process.spawn`
- * for commands and `node:fs/promises` for file operations.
- */
-
-/**
- * Create a ToolHost that runs everything on the local machine.
- *
- * @param defaultCwd  Working directory for commands when none is specified.
- *                    Defaults to `process.cwd()`.
- */
-declare function localHost(defaultCwd?: string): ToolHost;
-
-/**
- * Configuration for creating a Docker-backed `ToolHost`.
- */
-interface DockerHostOptions {
-    /**
-     * The container to connect to. Either:
-     * - A string container name or ID
-     * - A Dockerode `Container`-like object
-     */
-    container: string | {
-        id: string;
-        modem?: unknown;
-    };
-    /** User to run commands as inside the container. */
-    user?: string;
-    /** Default working directory inside the container. */
-    workdir?: string;
-    /**
-     * Dockerode constructor options.
-     * Only used when `container` is a string.
-     */
-    dockerOptions?: Record<string, unknown>;
-}
-
-declare function dockerHost(options: DockerHostOptions): Promise<ToolHost>;
-
-export { type DockerHostOptions, ToolHost, dockerHost, localHost };

package/dist/host/index.js

@@ -1,8 +0,0 @@
-import {
-  dockerHost,
-  localHost
-} from "../chunk-VNQBHPCT.js";
-export {
-  dockerHost,
-  localHost
-};