@cuylabs/agent-core 0.7.0 → 0.9.0

package/dist/{index-C33hlD6H.d.ts → index-DQuTZ8xL.d.ts}

@@ -1,15 +1,19 @@
 import { LanguageModel } from 'ai';
-import { R as ReasoningLevel } from './types-CQaXbRsS.js';
-import { T as Tool } from './tool-Db1Ue-1U.js';
-import { h as AgentMiddleware, d as StreamProvider, P as PromptConfig, A as AgentEvent, M as MiddlewareRunner } from './runner-DSKaEz3z.js';
-import { S as SessionManager, f as SessionContext, i as SessionInfo } from './session-manager-B_CWGTsl.js';
+import { P as Preset } from './types-BlZwmnuW.js';
+import { T as Tool } from './tool-CZWN3KbO.js';
+import { A as AgentMiddleware, f as StreamProvider, d as PromptConfig } from './types-DTSkxakL.js';
+import { S as SessionManager, f as SessionContext, i as SessionInfo } from './session-manager-KbYt2WUh.js';
 import { T as ToolHost } from './types-CHiPh8U2.js';
 import { T as TokenUsage, M as Message } from './messages-BYWGn8TY.js';
+import { A as AgentEvent } from './events-CE72w8W4.js';
+import { R as ReasoningLevel } from './types-CQaXbRsS.js';
 import { a as MCPManager } from './types-VQgymC1N.js';
+import { A as AgentSignal } from './types-YuWV4ag7.js';
 import { U as UndoResult, T as TurnChangeTracker } from './tracker-DClqYqTj.js';
-import { P as PromptBuilder } from './builder-BRvqCcIk.js';
-import { P as PendingIntervention, g as InterventionController } from './types-FRpzzg_9.js';
-import { s as DoomLoopHandler, o as AgentTurnStepRuntimeConfig } from './types-CqDZTh4d.js';
+import { P as PromptBuilder } from './builder-BgZ_j4Vs.js';
+import { P as PendingIntervention, n as InterventionController } from './types-BlOKk-Bb.js';
+import { M as MiddlewareRunner } from './runner-CI-XeR16.js';
+import { s as DoomLoopHandler, o as AgentTurnStepRuntimeConfig } from './types-DmDwi2zI.js';
 
 /**
  * Tools whose outputs should never be pruned automatically.
@@ -156,51 +160,17 @@ interface AgentConfig {
      * Simplest way to enable tracing.
      */
     tracing?: TracingConfig;
-}
-
-/**
- * Agent preset - a reusable configuration profile.
- */
-interface Preset {
-    /** Unique identifier for this preset */
-    name: string;
-    /** Human-readable description */
-    description: string;
     /**
-     * Tool allow patterns (glob-like).
-     * If provided, only tools matching these patterns are candidates.
-     */
-    allowTools?: string[];
-    /**
-     * Tool deny patterns (glob-like).
-     * Deny patterns apply only after allow matching, so explicit allows win.
-     */
-    denyTools?: string[];
-    /**
-     * Override system prompt.
-     * Use `{basePrompt}` to include the parent's system prompt.
+     * Event signal for multi-consumer dispatch.
+     *
+     * Every event yielded by `chat()` is also emitted here, enabling
+     * passive observers (SSE routes, TUI renderers, plugins) to
+     * subscribe without consuming the primary generator.
+     *
+     * Defaults to an in-process `LocalSignal`.  A distributed runtime
+     * can supply its own implementation to bridge events externally.
      */
-    systemPrompt?: string;
-    /** Override temperature (0-1). */
-    temperature?: number;
-    /** Override max steps. */
-    maxSteps?: number;
-    /** Override reasoning level. */
-    reasoningLevel?: ReasoningLevel;
-    /** Override model. */
-    model?: LanguageModel;
-}
-/**
- * Result of applying a preset - ready for `fork()`.
- */
-interface AppliedPreset {
-    name: string;
-    systemPrompt?: string;
-    tools?: Tool.AnyInfo[];
-    temperature?: number;
-    maxSteps?: number;
-    reasoningLevel?: ReasoningLevel;
-    model?: LanguageModel;
+    signal?: AgentSignal;
 }
 
 interface AgentForkOptions {
@@ -261,7 +231,6 @@ declare class Agent {
     private config;
     private tools;
     private sessions;
-    private loadedSessions;
     private state;
     /** Context manager for overflow detection and compaction */
     private contextManager;
@@ -275,6 +244,8 @@ declare class Agent {
     private mcpManager?;
     /** Whether MCP has been connected (lazy init) */
     private mcpConnected;
+    /** Whether skill tools have been resolved (lazy init) */
+    private skillToolsResolved;
     /** Cached MCP tools (refreshed on connect) */
     private mcpToolsCache?;
     /** Prompt pipeline builder (when using layered prompt mode) */
@@ -283,13 +254,31 @@ declare class Agent {
     private interventionCtrl;
     /** Execution environment for tool operations */
     private host;
+    /** Whether the agent owns the host and can safely recreate it on cwd changes */
+    private ownsHost;
     /** Middleware runner for lifecycle hooks */
     private middlewareRunner;
     /** AI SDK telemetry settings (auto-created from `tracing` config) */
     private telemetrySettings?;
     /** Tracing shutdown function (from `tracing` config auto-setup) */
     private tracingShutdown?;
+    /** Multi-consumer event dispatch */
+    private readonly _signal;
+    /** Number of active turns across all sessions */
+    private activeTurnCount;
+    /** Active turn intervention controllers, keyed by turn id */
+    private readonly activeTurns;
+    /** Per-session turn queue to prevent concurrent writes to the same history */
+    private readonly sessionLocks;
     constructor(config: AgentConstructionOptions);
+    /**
+     * Event signal — subscribe to events without consuming the generator.
+     *
+     * Every event yielded by `chat()` is also dispatched here, allowing
+     * multiple passive observers (SSE routes, TUI, plugins) to listen
+     * concurrently.
+     */
+    get signal(): AgentSignal;
     /** Agent name (identity for spans, Dapr workflows, etc.) */
     get name(): string;
     /** Working directory for file operations */
@@ -315,6 +304,20 @@ declare class Agent {
      * Check if current model supports reasoning
      */
     supportsReasoning(): boolean;
+    /**
+     * Ensure skill tools are registered when `prompt.skills` is configured.
+     * Lazy initialization — resolves the registry and adds tools on first use.
+     */
+    private ensureSkillTools;
+    private resetPromptScopedTools;
+    private createSessionManager;
+    private acquireSessionLock;
+    private getActiveInterventionController;
+    private getInterventionControllerForTurn;
+    private createTurnInterventionController;
+    private releaseTurnInterventions;
+    private syncStreamingState;
+    private syncSessionView;
     /**
      * Ensure MCP is connected and return tools
      * Lazy initialization - only connects on first use
@@ -355,10 +358,6 @@ declare class Agent {
         abort?: AbortSignal;
         system?: string;
     }): AsyncGenerator<AgentEvent>;
-    /**
-     * Ensure a session is loaded or created
-     */
-    private ensureSession;
     /**
      * Send a message and wait for the complete response (non-streaming).
      *
@@ -465,6 +464,8 @@ declare class Agent {
      *
      * If called when no turn is active, the message will be picked up
      * by the first step of the next `chat()` call.
+     * If multiple turns are active concurrently, this throws because the
+     * target turn would be ambiguous.
      *
      * @param message - The user message to inject mid-turn
      * @returns Intervention ID for tracking
@@ -494,6 +495,9 @@ declare class Agent {
      * `chat()` finishes. The consumer decides whether to send it as a
      * new turn.
      *
+     * If multiple turns are active concurrently, this throws because the
+     * target turn would be ambiguous.
+     *
      * @param message - The message to queue
      * @returns Intervention ID for tracking
      *
@@ -1069,4 +1073,263 @@ declare class SubAgentTracker {
  */
 declare function createSubAgentTools(parent: Agent, config: SubAgentToolConfig): Tool.AnyInfo[];
 
-export { type AppliedPreset as A, type CompactionConfig as C, DEFAULT_MAX_CONCURRENT as D, type Preset as P, type SubAgentCompletedResult as S, type TracingConfig as T, type AgentConfig as a, Agent as b, type AgentProfile as c, DEFAULT_MAX_SPAWN_DEPTH as d, DEFAULT_SESSION_TITLE_PREFIX as e, PRUNE_PROTECTED_TOOLS as f, type SubAgentHandle as g, type SubAgentStatus as h, type SubAgentToolConfig as i, SubAgentTracker as j, type SubAgentUsage as k, createAgent as l, createSubAgentTools as m };
+/**
+ * Markdown Agent Profile Parser
+ *
+ * Parses `.md` files into `AgentProfile` objects using a hybrid approach:
+ *
+ * - **Frontmatter** (YAML between `---` fences) maps to profile config
+ * - **Body** (everything after frontmatter) becomes the system prompt
+ * - **Preset references** compose with the existing TypeScript preset system
+ * - **Tool modifiers** (`+tool`, `-tool*`) extend or restrict preset tool lists
+ * - **Inheritance** (`extends: parent-name`) layers on top of another profile
+ *
+ * No external YAML library required — the frontmatter grammar is deliberately
+ * restricted to flat key-value pairs and comma-separated lists.
+ *
+ * @packageDocumentation
+ */
+
+/**
+ * Raw frontmatter fields extracted from a markdown agent file.
+ *
+ * All values are strings at this stage — conversion to typed config
+ * happens in {@link toAgentProfile}.
+ */
+interface MarkdownAgentFrontmatter {
+    /** Agent name (required). Lowercase, no spaces. */
+    name: string;
+    /** LLM-facing description of when to use this agent (required). */
+    description: string;
+    /** Built-in preset to inherit from (e.g. "explore", "code", "plan"). */
+    preset?: string;
+    /** Parent agent name to extend. */
+    extends?: string;
+    /** Model identifier (e.g. "anthropic/claude-sonnet-4-6"). */
+    model?: string;
+    /** Maximum agentic loop steps. */
+    maxSteps?: string;
+    /** LLM temperature (0–1). */
+    temperature?: string;
+    /** Reasoning level: off, minimal, low, medium, high, xhigh. */
+    reasoning?: string;
+    /**
+     * Tool modifiers or explicit tool list.
+     *
+     * Three modes:
+     * - **Additive/subtractive**: `"+bash, -delete*, +fetch"` — patch the preset
+     * - **Explicit list**: `"read, grep, bash"` — ONLY these tools
+     * - **Absent**: inherit preset filtering unchanged
+     */
+    tools?: string;
+    /** Comma-separated skill names to activate for this agent. */
+    skills?: string;
+    /** Whether this agent can spawn further sub-agents. */
+    canSpawn?: string;
+}
+/**
+ * Result of parsing a markdown agent file.
+ */
+interface ParsedMarkdownAgent {
+    /** Parsed frontmatter fields. */
+    frontmatter: MarkdownAgentFrontmatter;
+    /** Markdown body — becomes the system prompt. */
+    body: string;
+    /** Original file path (for error messages). */
+    filePath: string;
+}
+/**
+ * Parsed tool modifier from frontmatter `tools` field.
+ */
+type ToolModifier = {
+    kind: "add";
+    pattern: string;
+} | {
+    kind: "remove";
+    pattern: string;
+};
+/**
+ * Parsed tool specification from frontmatter.
+ */
+type ParsedToolSpec = {
+    mode: "explicit";
+    patterns: string[];
+} | {
+    mode: "modifiers";
+    modifiers: ToolModifier[];
+} | {
+    mode: "inherit";
+};
+/**
+ * Resolvers needed to convert parsed frontmatter into a full `AgentProfile`.
+ *
+ * These are injected by the caller so the parser stays pure (no I/O, no
+ * global lookups).
+ */
+interface ProfileResolvers {
+    /** Look up a built-in preset by name. Returns undefined if not found. */
+    resolvePreset?: (name: string) => Preset | undefined;
+    /** Look up a parent profile by name (for `extends`). */
+    resolveParent?: (name: string) => AgentProfile | undefined;
+}
+/**
+ * Parse a YAML-like frontmatter block.
+ *
+ * Supports:
+ * - `key: value` (string values, trimmed)
+ * - `key: "quoted value"` (double-quoted, quotes stripped)
+ * - `key: 'quoted value'` (single-quoted, quotes stripped)
+ * - Multi-line values via `key: |` (indented block)
+ * - Comments (`# ...`)
+ * - Empty lines (skipped)
+ *
+ * Does NOT support nested objects, arrays, or advanced YAML features.
+ * This is intentional — agent definitions should stay flat and readable.
+ */
+declare function parseAgentFrontmatter(raw: string): Record<string, string>;
+/**
+ * Parse a markdown agent file into structured frontmatter + body.
+ *
+ * @param content   File content (UTF-8 string)
+ * @param filePath  Source file path (for error context)
+ * @returns Parsed result, or null if the file lacks valid frontmatter
+ */
+declare function parseMarkdownAgent(content: string, filePath: string): ParsedMarkdownAgent | null;
+/**
+ * Parse the `tools` frontmatter field into a structured spec.
+ *
+ * - `"+bash, -delete*, +fetch"` → `{ mode: "modifiers", modifiers: [...] }`
+ * - `"read, grep, bash"` → `{ mode: "explicit", patterns: ["read", "grep", "bash"] }`
+ * - `undefined` → `{ mode: "inherit" }`
+ */
+declare function parseToolSpec(raw: string | undefined): ParsedToolSpec;
+/**
+ * Convert a parsed markdown agent into an `AgentProfile`.
+ *
+ * Resolution order for each field:
+ * 1. Explicit frontmatter value (highest priority)
+ * 2. Parent profile (via `extends`)
+ * 3. Preset defaults
+ * 4. Built-in defaults
+ *
+ * @param parsed    Parsed markdown agent
+ * @param resolvers Injected lookup functions
+ * @returns A fully-resolved `AgentProfile`
+ */
+declare function toAgentProfile(parsed: ParsedMarkdownAgent, resolvers?: ProfileResolvers): AgentProfile;
+/**
+ * An `AgentProfile` that originated from a markdown file.
+ *
+ * Carries extra metadata that the discovery/wiring layer can use
+ * to resolve model strings and activate skills.
+ */
+interface MarkdownAgentProfile extends AgentProfile {
+    /** Model identifier string (e.g. "anthropic/claude-sonnet-4-6"). */
+    _modelId?: string;
+    /** Skill names to activate for this agent. */
+    _skillNames?: string[];
+    /** Source file path. */
+    _source?: string;
+}
+/**
+ * Type guard for markdown-sourced profiles.
+ */
+declare function isMarkdownProfile(profile: AgentProfile): profile is MarkdownAgentProfile;
+
+/**
+ * Agent Profile Discovery
+ *
+ * Discovers agent profiles from markdown files across multiple locations
+ * and merges them with built-in TypeScript profiles.
+ *
+ * Discovery order (later wins by name):
+ * 1. Built-in TypeScript profiles (e.g. explorer, coder, planner, runner)
+ * 2. User global agents: `~/.cuylabs/agents/*.md`
+ * 3. Project local agents: `.cuylabs/agents/*.md`
+ * 4. Config-specified paths: `config.agents` array
+ *
+ * @packageDocumentation
+ */
+
+/** Source tier for an agent profile. */
+type AgentSource = "builtin" | "user" | "project" | "config";
+/** Metadata attached to discovered profiles for debugging/logging. */
+interface DiscoveredProfile {
+    profile: AgentProfile;
+    source: AgentSource;
+    filePath?: string;
+}
+/**
+ * Options for agent profile discovery.
+ */
+interface AgentDiscoveryOptions {
+    /** Project working directory. Used to find `.cuylabs/agents/`. */
+    cwd: string;
+    /**
+     * User-global agents directory.
+     * @default `~/.cuylabs/agents`
+     */
+    userDir?: string;
+    /**
+     * Project-local agents directory name (relative to cwd).
+     * @default `.cuylabs/agents`
+     */
+    projectDir?: string;
+    /**
+     * Additional file paths from config.json `agents` array.
+     * Resolved relative to cwd.
+     */
+    configPaths?: string[];
+    /** Built-in TypeScript profiles to merge with. */
+    builtInProfiles?: AgentProfile[];
+    /**
+     * Custom preset resolver. Defaults to the built-in `Presets` map.
+     */
+    resolvePreset?: (name: string) => Preset | undefined;
+}
+/**
+ * Result of agent profile discovery.
+ */
+interface AgentDiscoveryResult {
+    /** Merged profiles (ready for `SubAgentToolConfig.profiles`). */
+    profiles: AgentProfile[];
+    /** All discovered entries with source metadata (for logging). */
+    discovered: DiscoveredProfile[];
+    /** Errors encountered during loading (non-fatal). */
+    errors: Array<{
+        path: string;
+        error: string;
+    }>;
+}
+/**
+ * Discover agent profiles from markdown files and merge with built-in profiles.
+ *
+ * Merge strategy: later sources override earlier ones by profile name.
+ * Within the same source tier, later files (alphabetical) override earlier ones.
+ *
+ * This means a project `.cuylabs/agents/explorer.md` overrides the built-in
+ * `explorer` profile, and a user `~/.cuylabs/agents/explorer.md` overrides it
+ * for all projects.
+ *
+ * @example
+ * ```typescript
+ * const { profiles } = discoverAgentProfiles({
+ *   cwd: "/path/to/project",
+ *   builtInProfiles: defaultCodingProfiles,
+ * });
+ *
+ * // profiles now includes built-ins + user + project markdown agents
+ * const config: SubAgentToolConfig = { profiles };
+ * ```
+ */
+declare function discoverAgentProfiles(options: AgentDiscoveryOptions): AgentDiscoveryResult;
+/**
+ * Get the default user agents directory path.
+ */
+declare function getUserAgentsDir(): string;
+/**
+ * Get the project agents directory path for a given cwd.
+ */
+declare function getProjectAgentsDir(cwd: string): string;
+
+export { type AgentConfig as A, parseToolSpec as B, type CompactionConfig as C, DEFAULT_MAX_CONCURRENT as D, toAgentProfile as E, type MarkdownAgentFrontmatter as M, PRUNE_PROTECTED_TOOLS as P, type SubAgentCompletedResult as S, type ToolModifier as T, Agent as a, type AgentDiscoveryOptions as b, type AgentDiscoveryResult as c, type AgentProfile as d, type AgentSource as e, DEFAULT_MAX_SPAWN_DEPTH as f, DEFAULT_SESSION_TITLE_PREFIX as g, type DiscoveredProfile as h, type MarkdownAgentProfile as i, type ParsedMarkdownAgent as j, type ParsedToolSpec as k, type ProfileResolvers as l, type SubAgentHandle as m, type SubAgentStatus as n, type SubAgentToolConfig as o, SubAgentTracker as p, type SubAgentUsage as q, type TracingConfig as r, createAgent as s, createSubAgentTools as t, discoverAgentProfiles as u, getProjectAgentsDir as v, getUserAgentsDir as w, isMarkdownProfile as x, parseAgentFrontmatter as y, parseMarkdownAgent as z };