@cuylabs/agent-core 0.4.0 → 0.5.0

package/dist/runner-C7aMP_x3.d.ts

@@ -0,0 +1,596 @@
+import * as ai from 'ai';
+import { LanguageModel } from 'ai';
+import { T as TokenUsage, M as Message } from './messages-BYWGn8TY.js';
+import { d as SkillConfig, T as Tool } from './tool-pFAnJc5Y.js';
+import { b as ToolContext } from './tool-DYp6-cC3.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;
+};
+/**
+ * Processor result - what happens after processing a turn
+ */
+type ProcessorResult = "continue" | "stop" | "compact";
+/**
+ * Stream input for the LLM
+ */
+interface StreamInput {
+    sessionID: string;
+    model: ai.LanguageModel;
+    system: string[];
+    messages: ai.ModelMessage[];
+    abort: AbortSignal;
+    tools: Record<string, unknown>;
+}
+
+/**
+ * Prompt Pipeline Types
+ *
+ * Types for the layered system prompt architecture.
+ * The prompt pipeline composes a system prompt from multiple sources:
+ *
+ *   Base Template → Environment → Instructions → Custom Sections → Per-Turn
+ *
+ * Each layer is optional, composable, and can be toggled on/off.
+ */
+
+/**
+ * Model family identifier for prompt template selection.
+ *
+ * Each family gets a base template optimized for its strengths:
+ * - `anthropic`: Claude models — structured sections with XML tags
+ * - `openai`: GPT/o-series models — clear directives with markdown
+ * - `google`: Gemini models — balanced approach
+ * - `deepseek`: DeepSeek models — code-focused emphasis
+ * - `default`: Generic template for any model
+ */
+type ModelFamily = "anthropic" | "openai" | "google" | "deepseek" | "default";
+/**
+ * Runtime environment information injected into the system prompt.
+ * Gives the model awareness of the working context.
+ */
+interface EnvironmentInfo {
+    /** Current working directory */
+    cwd: string;
+    /** Operating system (e.g. "macOS (darwin arm64)") */
+    platform: string;
+    /** Current date/time formatted string */
+    date: string;
+    /** User's shell (e.g. "/bin/zsh") */
+    shell?: string;
+    /** Active git branch, if inside a repo */
+    gitBranch?: string;
+    /** Whether the working tree is clean */
+    gitClean?: boolean;
+    /** Git repo root path */
+    gitRoot?: string;
+}
+/**
+ * An instruction file discovered on disk (e.g. AGENTS.md).
+ *
+ * Instruction files provide project-specific or workspace-level guidance
+ * that gets injected into every prompt. They're discovered by walking up
+ * the directory tree from cwd.
+ */
+interface InstructionFile {
+    /** Absolute path to the file */
+    path: string;
+    /** File content (trimmed) */
+    content: string;
+    /** How the file was discovered */
+    source: "project" | "workspace" | "global";
+    /** Depth from cwd (0 = same directory) */
+    depth: number;
+}
+/**
+ * A composable section in the prompt pipeline.
+ *
+ * Sections are the building blocks of the final system prompt.
+ * Each section has a priority that determines its position in the output.
+ *
+ * Default priority ranges:
+ * - 10: Base template
+ * - 20: Environment block
+ * - 30: Instruction files
+ * - 50: Custom sections (default for user-added)
+ * - 70: Reserved for future use (e.g. Skills)
+ * - 90: Per-turn overrides
+ */
+interface PromptSection {
+    /** Unique identifier for this section */
+    id: string;
+    /** Human-readable label (useful for debugging/logging) */
+    label: string;
+    /** The text content of this section */
+    content: string;
+    /** Sort priority — lower values appear earlier (default: 50) */
+    priority?: number;
+    /** Whether this section is active (default: true) */
+    enabled?: boolean;
+}
+/**
+ * Context passed to the builder for each prompt build.
+ *
+ * This provides the runtime information needed to compose
+ * the system prompt for a specific conversation turn.
+ */
+interface PromptBuildContext {
+    /** Current working directory */
+    cwd: string;
+    /** The language model being used */
+    model: LanguageModel;
+    /** Names of available tools (for template customization) */
+    toolNames?: string[];
+    /** Per-turn additional instructions (from chat options) */
+    override?: string;
+    /** Current session ID */
+    sessionId?: string;
+}
+/**
+ * Configuration for the prompt pipeline.
+ *
+ * Controls which layers are active and how they behave.
+ * All options have sensible defaults — an empty config `{}` gives you
+ * the full pipeline with auto-detection.
+ *
+ * @example
+ * ```typescript
+ * // Minimal — use all defaults
+ * const builder = createPromptBuilder();
+ *
+ * // Custom base template but keep environment + instructions
+ * const builder = createPromptBuilder({
+ *   baseTemplate: "You are a security auditor...",
+ *   includeEnvironment: true,
+ *   includeInstructions: true,
+ * });
+ *
+ * // Fully custom — disable auto features, add your own sections
+ * const builder = createPromptBuilder({
+ *   includeEnvironment: false,
+ *   includeInstructions: false,
+ *   sections: [
+ *     { id: "role", label: "Role", content: "You audit code.", priority: 10 },
+ *     { id: "rules", label: "Rules", content: "Never modify files.", priority: 20 },
+ *   ],
+ * });
+ * ```
+ */
+interface PromptConfig {
+    /**
+     * Override the base template entirely.
+     * If set, replaces the model-family-specific template.
+     */
+    baseTemplate?: string;
+    /**
+     * Force a specific model family for template selection.
+     * Auto-detected from the model if not provided.
+     */
+    modelFamily?: ModelFamily;
+    /**
+     * Inject runtime environment info (cwd, platform, git, date).
+     * @default true
+     */
+    includeEnvironment?: boolean;
+    /**
+     * Discover and include instruction files (AGENTS.md, etc.).
+     * @default true
+     */
+    includeInstructions?: boolean;
+    /**
+     * File name patterns to search for when discovering instructions.
+     * Searched in each directory walking up from cwd.
+     *
+     * @default ["AGENTS.md", "CLAUDE.md", "COPILOT.md", ".cuylabs/instructions.md"]
+     */
+    instructionPatterns?: string[];
+    /**
+     * Absolute paths to global instruction files (always included
+     * regardless of cwd). Useful for organization-wide rules.
+     */
+    globalInstructions?: string[];
+    /**
+     * Maximum depth to walk up from cwd when searching for instructions.
+     * Prevents scanning the entire filesystem.
+     * @default 10
+     */
+    instructionMaxDepth?: number;
+    /**
+     * Maximum file size in bytes for instruction files.
+     * Files larger than this are skipped to avoid bloating the prompt.
+     * @default 51200 (50KB)
+     */
+    instructionMaxSize?: number;
+    /**
+     * Pre-defined sections to include in every prompt build.
+     * These are merged with auto-generated sections (template, environment, etc.).
+     */
+    sections?: PromptSection[];
+    /**
+     * Separator between sections in the final composed prompt.
+     * @default "\n\n"
+     */
+    separator?: string;
+    /**
+     * Skill discovery and loading configuration.
+     *
+     * When provided, the prompt pipeline will:
+     * 1. Discover SKILL.md files from project, user, and global directories
+     * 2. Inject skill summaries at PRIORITY_SKILLS (70) in the system prompt
+     * 3. Make `skill` and `skill_resource` tools available to the agent
+     *
+     * Skills use progressive disclosure:
+     * - L1 (summary): always in system prompt — names + descriptions
+     * - L2 (content): loaded on demand via `skill` tool
+     * - L3 (resources): loaded on demand via `skill_resource` tool
+     *
+     * @example
+     * ```typescript
+     * const agent = createAgent({
+     *   model: anthropic("claude-sonnet-4-20250514"),
+     *   prompt: {
+     *     skills: {
+     *       externalDirs: [".agents", ".claude"],
+     *       roots: ["./company-skills"],
+     *     },
+     *   },
+     * });
+     * ```
+     */
+    skills?: SkillConfig;
+}
+
+/**
+ * Middleware Types
+ *
+ * Defines the composable middleware interface for agent lifecycle hooks.
+ *
+ * Middleware is just a plain object with optional hook methods — no
+ * base classes, no discovery, no installation. Pass it in code:
+ *
+ * ```typescript
+ * const agent = createAgent({
+ *   middleware: [myLoggerMiddleware, myApprovalMiddleware],
+ * });
+ * ```
+ *
+ * Hooks run in array order for "before" operations and reverse order
+ * for "after" operations (like middleware stacks everywhere).
+ */
+
+/**
+ * Action returned by `beforeToolCall` — determines whether
+ * the tool call proceeds or is blocked.
+ */
+interface ToolCallDecision {
+    /** Whether to allow or deny the tool call */
+    action: "allow" | "deny";
+    /** Reason for denial — returned to the model as the tool output */
+    reason?: string;
+}
+/**
+ * Agent middleware — composable lifecycle hooks.
+ *
+ * All methods are optional. Implement only what you need.
+ *
+ * Ordering:
+ * - `beforeToolCall`: runs in array order, first "deny" wins
+ * - `afterToolCall`: runs in reverse order (innermost first)
+ * - `promptSections`: all run, sections merged
+ * - `onEvent`: all run in parallel (non-blocking)
+ * - `onChatStart` / `onChatEnd`: run in array order, awaited sequentially
+ *
+ * @example
+ * ```typescript
+ * // A simple logging middleware
+ * const logger: AgentMiddleware = {
+ *   name: "logger",
+ *   beforeToolCall: async (tool, args) => {
+ *     console.log(`→ ${tool}`, args);
+ *     return { action: "allow" };
+ *   },
+ *   afterToolCall: async (tool, args, result) => {
+ *     console.log(`← ${tool}`, result.title);
+ *     return result;
+ *   },
+ * };
+ * ```
+ */
+interface AgentMiddleware {
+    /** Middleware name (for logging and debugging) */
+    name: string;
+    /**
+     * Intercept a tool call before execution.
+     *
+     * Return `{ action: "allow" }` to proceed, or `{ action: "deny", reason }` to
+     * block the call. When denied, `reason` is returned to the model as the tool
+     * output so it can adjust its approach.
+     *
+     * Runs in array order. The first middleware that returns "deny" short-circuits
+     * the chain — remaining middleware and the tool itself are skipped.
+     *
+     * @param tool   - Tool name (e.g. "bash", "write_file")
+     * @param args   - Parsed tool arguments
+     * @param ctx    - Tool execution context (cwd, sessionID, host, etc.)
+     */
+    beforeToolCall?(tool: string, args: unknown, ctx: ToolContext): Promise<ToolCallDecision>;
+    /**
+     * Transform or observe a tool result after execution.
+     *
+     * Receives the result and must return a result (can be the same object
+     * or a modified copy). Runs in reverse array order so the outermost
+     * middleware sees the final transformed result.
+     *
+     * @param tool   - Tool name
+     * @param args   - Original tool arguments
+     * @param result - Tool execution result
+     * @param ctx    - Tool execution context
+     */
+    afterToolCall?(tool: string, args: unknown, result: Tool.ExecuteResult, ctx: ToolContext): Promise<Tool.ExecuteResult>;
+    /**
+     * Inject dynamic prompt sections at build time.
+     *
+     * Called during `PromptBuilder.build()` for each middleware. Return one
+     * or more sections to inject into the system prompt. Return `undefined`
+     * or an empty array to inject nothing.
+     *
+     * Sections follow the same priority system as static sections — use
+     * `priority` to control placement relative to base template (10),
+     * environment (20), instructions (30), custom (50), skills (70),
+     * and per-turn overrides (90).
+     *
+     * @param ctx - Build context with cwd, model, toolNames, sessionId
+     */
+    promptSections?(ctx: PromptBuildContext): PromptSection | PromptSection[] | undefined;
+    /**
+     * Observe agent events (read-only, non-blocking).
+     *
+     * Fires for every event emitted during `chat()`. Errors thrown by
+     * handlers are caught and logged — they never interrupt the stream.
+     *
+     * This is intentionally synchronous (void return) to prevent
+     * event observers from blocking the streaming pipeline.
+     *
+     * @param event - The agent event
+     */
+    onEvent?(event: AgentEvent): void;
+    /**
+     * Called when `chat()` starts, before the LLM stream is created.
+     *
+     * Use this for setup: initializing loggers, recording start time,
+     * resetting per-turn state, etc. Runs in array order, awaited
+     * sequentially.
+     *
+     * @param sessionId - Session identifier
+     * @param message   - The user message being sent
+     */
+    onChatStart?(sessionId: string, message: string): Promise<void>;
+    /**
+     * Called when `chat()` completes (or errors), after all events
+     * have been yielded.
+     *
+     * Use this for teardown: flushing logs, recording metrics, etc.
+     * Runs in array order, awaited sequentially. Always called, even
+     * if the stream errored.
+     *
+     * @param sessionId - Session identifier
+     * @param result    - Completion info (usage stats and optional error)
+     */
+    onChatEnd?(sessionId: string, result: {
+        usage?: TokenUsage;
+        error?: Error;
+        output?: string;
+    }): Promise<void>;
+    /**
+     * Get the active OTel context for a session.
+     *
+     * Used internally by the LLM layer to wrap `streamText()` so that
+     * AI SDK spans are nested under the middleware's parent span.
+     * Only implemented by the `otelMiddleware`.
+     */
+    getOtelContext?(sessionId: string): unknown;
+}
+
+/**
+ * Middleware Runner
+ *
+ * Executes middleware hooks in the correct order with proper
+ * error handling and short-circuit semantics.
+ *
+ * This is the internal engine — consumers never see it.
+ * They interact with middleware through AgentConfig.middleware.
+ */
+
+/**
+ * Middleware runner — holds an ordered list of middleware and
+ * exposes methods to run each hook type with correct semantics.
+ *
+ * Immutable after construction. Fork creates a new runner
+ * (with inherited + additional middleware).
+ */
+declare class MiddlewareRunner {
+    private readonly stack;
+    constructor(middleware?: AgentMiddleware[]);
+    /** Number of registered middleware */
+    get count(): number;
+    /** Whether any middleware is registered */
+    get hasMiddleware(): boolean;
+    /** Get the middleware list (for fork inheritance) */
+    getMiddleware(): readonly AgentMiddleware[];
+    /**
+     * Run all `beforeToolCall` hooks in order.
+     *
+     * Returns `{ action: "allow" }` if all middleware allow (or have no hook).
+     * Returns `{ action: "deny", reason }` on first denial — remaining
+     * middleware are skipped.
+     */
+    runBeforeToolCall(tool: string, args: unknown, ctx: ToolContext): Promise<ToolCallDecision>;
+    /**
+     * Run all `afterToolCall` hooks in reverse order.
+     *
+     * Each hook receives the result from the previous hook (or the
+     * original tool result for the first hook). Errors are caught
+     * and logged — the original result passes through.
+     */
+    runAfterToolCall(tool: string, args: unknown, result: Tool.ExecuteResult, ctx: ToolContext): Promise<Tool.ExecuteResult>;
+    /**
+     * Collect prompt sections from all middleware.
+     *
+     * Returns a flat array of sections. Each middleware can return a single
+     * section, an array of sections, or undefined/empty.
+     */
+    collectPromptSections(ctx: PromptBuildContext): PromptSection[];
+    /**
+     * Broadcast an event to all middleware observers.
+     *
+     * Non-blocking — errors are caught and logged. This never
+     * slows down the streaming pipeline.
+     */
+    emitEvent(event: AgentEvent): void;
+    /**
+     * Get the OTel context for a session from the telemetry middleware.
+     * Returns undefined if no telemetry middleware is registered.
+     */
+    getOtelContext(sessionId: string): unknown | undefined;
+    /**
+     * Run all `onChatStart` hooks in order.
+     *
+     * Errors are caught and logged — a broken logger should not
+     * prevent the chat from starting.
+     */
+    runChatStart(sessionId: string, message: string): Promise<void>;
+    /**
+     * Run all `onChatEnd` hooks in order.
+     *
+     * Always called, even when the stream errored. Errors in handlers
+     * are caught and logged.
+     */
+    runChatEnd(sessionId: string, result: {
+        usage?: TokenUsage;
+        error?: Error;
+        output?: string;
+    }): Promise<void>;
+}
+
+export { type AgentEvent as A, type EnvironmentInfo as E, type InstructionFile as I, MiddlewareRunner as M, type PromptConfig as P, type StreamInput as S, type ToolCallDecision as T, type PromptBuildContext as a, type PromptSection as b, type ModelFamily as c, type ProcessorResult as d, type AgentTurnBoundaryKind as e, type AgentMiddleware as f, type AgentStatus as g, type ApprovalEvent as h };