@cuylabs/agent-core 4.9.0 → 5.0.0

package/dist/prompt/index.d.ts

@@ -1,228 +1,39 @@
-import { bV as ModelFamily, bd as EnvironmentInfo, by as InstructionFile } from '../instance-Bg61WSyz.js';
-export { cc as PromptBuildContext, P as PromptBuilder, cd as PromptConfig, ce as PromptSection, cD as SkillConfig, dT as createPromptBuilder } from '../instance-Bg61WSyz.js';
-import { LanguageModel } from 'ai';
-import '../types-C_LCeYNg.js';
-import '../types-RSCv7nQ4.js';
-import 'zod';
-import '../types-CQaXbRsS.js';
-import '../types-DMjoFKKv.js';
-import '@modelcontextprotocol/sdk/client/auth.js';
-import '@modelcontextprotocol/sdk/types.js';
-import '@ai-sdk/provider-utils';
-import '../sandbox/index.js';
-import '../llm-error-D93FNNLY.js';
-
 /**
- * Prompt Templates — Base system prompts per model family
+ * Prompt Pipeline Module
  *
- * agent-core provides **generic, domain-agnostic** templates.
- * These establish the agent's general approach and tool-use discipline
- * without assuming a specific domain (coding, browsing, etc.).
+ * Composable system prompt architecture for @cuylabs/agent-core.
  *
- * Domain-specific templates belong in consumer packages:
- * - agent-code → coding templates ("read files before editing", etc.)
- * - computer-agent → computer-use templates
- * - your-custom-agent → whatever you need
- *
- * Consumer packages inject their templates via:
- *   createPromptBuilder({ baseTemplate: MY_CODING_TEMPLATE })
- *   builder.addSection({ id: "coding", ... })
- *
- * This file also contains model family detection, which IS infrastructure
- * and belongs here — any consumer benefits from knowing the model family
- * to optimize prompt formatting.
- */
-
-/**
- * Detect which model family a LanguageModel belongs to.
- *
- * Uses the provider string first (most reliable), then falls back
- * to pattern matching on the model ID.
+ * The prompt pipeline builds system prompts from layered sections:
+ *   Base Template → Environment → Instructions → Custom Sections → Per-Turn
  *
  * @example
  * ```typescript
- * import { anthropic } from "@ai-sdk/anthropic";
- * detectModelFamily(anthropic("claude-sonnet-4-20250514")); // "anthropic"
- *
- * import { openai } from "@ai-sdk/openai";
- * detectModelFamily(openai("gpt-4o")); // "openai"
- * ```
- */
-declare function detectModelFamily(model: LanguageModel): ModelFamily;
-/**
- * Get the base template for a model family.
- *
- * @param family - Model family identifier
- * @returns The generic system prompt template
- */
-declare function getTemplate(family: ModelFamily): string;
-/**
- * Get all available template families.
- * Useful for debugging or letting users choose.
- */
-declare function getAvailableFamilies(): ModelFamily[];
-
-/**
- * Environment Block — Runtime context for the system prompt
- *
- * Gathers information about the working environment (cwd, platform,
- * git status, date, shell) and formats it as a structured block
- * that gets injected into the prompt at priority 20.
- *
- * This gives the model awareness of:
- * - Where it's working (directory, project)
- * - What platform it's on (affects path separators, commands)
- * - Current time (useful for time-sensitive tasks)
- * - Git state (branch, clean/dirty)
- */
-
-/**
- * Gather runtime environment information.
- *
- * Collects cwd, platform, git status, date, and shell.
- * Git commands use a short timeout to avoid hanging on slow repos.
- *
- * @param cwd - Working directory to gather info for
- * @returns Environment info object
- */
-declare function gatherEnvironment(cwd: string): EnvironmentInfo;
-/**
- * Format environment info as a prompt-friendly block.
- *
- * Output example:
- * ```
- * <workspace>
- * Directory: /Users/dev/my-project
- * Project: my-project
- * Platform: macOS (darwin arm64)
- * Date: Saturday, February 8, 2026
- * Shell: /bin/zsh
- * Git: main (clean)
- * </workspace>
- * ```
- */
-declare function formatEnvironment(info: EnvironmentInfo): string;
-/**
- * Create a short one-line summary of the environment.
- * Useful for compact contexts or logging.
- */
-declare function summarizeEnvironment(info: EnvironmentInfo): string;
-
-/**
- * Instruction File Discovery — Project rules from the filesystem
- *
- * Discovers instruction files (AGENTS.md, CLAUDE.md, COPILOT.md, etc.)
- * by walking up the directory tree from cwd. These files provide
- * project-specific or workspace-level guidance to the agent.
- *
- * Discovery order (general → specific):
- * 1. Global instruction files (from config)
- * 2. Workspace-level files (found near git root or higher directories)
- * 3. Project-level files (found in or near cwd)
- *
- * All discovered files are included, ordered from most general to most
- * specific. This means project-level instructions appear last and
- * effectively take precedence in case of conflicting guidance.
- *
- * Compatible with:
- * - AGENTS.md convention
- * - CLAUDE.md convention
- * - COPILOT.md convention
- * - CuyLabs' own .cuylabs/instructions.md
- */
-
-/**
- * Default file patterns to search for.
- * Checked in each directory when walking up from cwd.
- */
-declare const DEFAULT_INSTRUCTION_PATTERNS: string[];
-/**
- * Maximum file size for instruction files (50KB).
- * Files larger than this are skipped to prevent prompt bloat.
- */
-declare const DEFAULT_MAX_FILE_SIZE = 51200;
-/**
- * Maximum directories to walk up from cwd.
- */
-declare const DEFAULT_MAX_DEPTH = 10;
-/**
- * Discover instruction files by walking up the directory tree from cwd.
- *
- * Searches for files matching the given patterns in each directory,
- * starting from `cwd` and walking up to the filesystem root (or until
- * `maxDepth` is reached).
- *
- * Results are ordered from **most general** (shallowest/root-level) to
- * **most specific** (deepest/cwd-level), so that specific project rules
- * appear last and take natural precedence.
- *
- * @param cwd - Starting directory for the search
- * @param patterns - File name patterns to look for (e.g. ["AGENTS.md"])
- * @param options - Discovery options
- * @returns Array of discovered instruction files, general → specific
- *
- * @example
- * ```typescript
- * const files = await discoverInstructions("/Users/dev/project/src", [
- *   "AGENTS.md",
- *   "CLAUDE.md",
- * ]);
- *
- * // Might find:
- * // 1. /Users/dev/project/AGENTS.md (depth: 1, workspace)
- * // 2. /Users/dev/project/src/AGENTS.md (depth: 0, project)
- * ```
- */
-declare function discoverInstructions(cwd: string, patterns?: string[], options?: {
-    maxDepth?: number;
-    maxFileSize?: number;
-    stopAtGitRoot?: boolean;
-}): Promise<InstructionFile[]>;
-/**
- * Load global instruction files from explicit paths.
- *
- * Global instructions are always included regardless of cwd.
- * Useful for organization-wide coding standards or team rules.
- *
- * @param paths - Absolute paths to global instruction files
- * @param maxSize - Maximum file size in bytes
- * @returns Array of loaded instruction files
- */
-declare function loadGlobalInstructions(paths: string[], maxSize?: number): Promise<InstructionFile[]>;
-/**
- * Format discovered instruction files into a prompt block.
- *
- * Each file is wrapped in a tagged block with its source path
- * for transparency. Files are already ordered general → specific.
- *
- * Output example:
- * ```
- * <project-instructions>
- *
- * <instructions source="AGENTS.md" scope="workspace">
- * ... workspace-level content ...
- * </instructions>
- *
- * <instructions source="src/AGENTS.md" scope="project">
- * ... project-specific content ...
- * </instructions>
- *
- * </project-instructions>
+ * import { createPromptBuilder } from "@cuylabs/agent-core";
+ *
+ * const builder = createPromptBuilder({
+ *   includeEnvironment: true,
+ *   includeInstructions: true,
+ * });
+ *
+ * // Add custom context
+ * builder.addSection({
+ *   id: "team-rules",
+ *   label: "Team Rules",
+ *   content: "Always use TypeScript strict mode.",
+ *   priority: 40,
+ * });
+ *
+ * // Build the prompt
+ * const prompt = await builder.build({
+ *   cwd: "/path/to/project",
+ *   model: myModel,
+ * });
  * ```
  */
-declare function formatInstructions(files: InstructionFile[], basePath?: string): string;
-
-/** Priority for the base template section. */
-declare const PRIORITY_BASE = 10;
-/** Priority for the environment block section. */
-declare const PRIORITY_ENVIRONMENT = 20;
-/** Priority for instruction files. */
-declare const PRIORITY_INSTRUCTIONS = 30;
-/** Priority for custom user-defined sections. */
-declare const PRIORITY_CUSTOM = 50;
-/** Priority for skill summary injection. */
-declare const PRIORITY_SKILLS = 70;
-/** Priority for per-turn override content. */
-declare const PRIORITY_OVERRIDE = 90;
-
-export { DEFAULT_INSTRUCTION_PATTERNS, DEFAULT_MAX_DEPTH, DEFAULT_MAX_FILE_SIZE, EnvironmentInfo, InstructionFile, ModelFamily, PRIORITY_BASE, PRIORITY_CUSTOM, PRIORITY_ENVIRONMENT, PRIORITY_INSTRUCTIONS, PRIORITY_OVERRIDE, PRIORITY_SKILLS, detectModelFamily, discoverInstructions, formatEnvironment, formatInstructions, gatherEnvironment, getAvailableFamilies, getTemplate, loadGlobalInstructions, summarizeEnvironment };
+export type { ModelFamily, EnvironmentInfo, InstructionFile, PromptSection, PromptBuildContext, PromptConfig, } from "./types.js";
+export { DEFAULT_SYSTEM_PROMPT, detectModelFamily, getTemplate, getAvailableFamilies, } from "./templates.js";
+export { gatherEnvironment, formatEnvironment, summarizeEnvironment, } from "./environment.js";
+export { discoverInstructions, loadGlobalInstructions, formatInstructions, DEFAULT_INSTRUCTION_PATTERNS, DEFAULT_MAX_FILE_SIZE, DEFAULT_MAX_DEPTH, } from "./instructions.js";
+export { PromptBuilder, createPromptBuilder, PRIORITY_BASE, PRIORITY_ENVIRONMENT, PRIORITY_INSTRUCTIONS, PRIORITY_CUSTOM, PRIORITY_SKILLS, PRIORITY_OVERRIDE, } from "./builder/index.js";
+export type { SkillConfig } from "../skill/types.js";
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/prompt/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AAGH,YAAY,EACV,WAAW,EACX,eAAe,EACf,eAAe,EACf,aAAa,EACb,kBAAkB,EAClB,YAAY,GACb,MAAM,YAAY,CAAC;AAGpB,OAAO,EACL,qBAAqB,EACrB,iBAAiB,EACjB,WAAW,EACX,oBAAoB,GACrB,MAAM,gBAAgB,CAAC;AAGxB,OAAO,EACL,iBAAiB,EACjB,iBAAiB,EACjB,oBAAoB,GACrB,MAAM,kBAAkB,CAAC;AAG1B,OAAO,EACL,oBAAoB,EACpB,sBAAsB,EACtB,kBAAkB,EAClB,4BAA4B,EAC5B,qBAAqB,EACrB,iBAAiB,GAClB,MAAM,mBAAmB,CAAC;AAG3B,OAAO,EACL,aAAa,EACb,mBAAmB,EACnB,aAAa,EACb,oBAAoB,EACpB,qBAAqB,EACrB,eAAe,EACf,eAAe,EACf,iBAAiB,GAClB,MAAM,oBAAoB,CAAC;AAG5B,YAAY,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC"}

package/dist/prompt/index.js

@@ -2,6 +2,7 @@ import {
   DEFAULT_INSTRUCTION_PATTERNS,
   DEFAULT_MAX_DEPTH,
   DEFAULT_MAX_FILE_SIZE,
+  DEFAULT_SYSTEM_PROMPT,
   PRIORITY_BASE,
   PRIORITY_CUSTOM,
   PRIORITY_ENVIRONMENT,
@@ -19,13 +20,14 @@ import {
   getTemplate,
   loadGlobalInstructions,
   summarizeEnvironment
-} from "../chunk-BGG2HVIR.js";
+} from "../chunk-V4MIDL5B.js";
 import "../chunk-I7EJGKUP.js";
 import "../chunk-I6PKJ7XQ.js";
 export {
   DEFAULT_INSTRUCTION_PATTERNS,
   DEFAULT_MAX_DEPTH,
   DEFAULT_MAX_FILE_SIZE,
+  DEFAULT_SYSTEM_PROMPT,
   PRIORITY_BASE,
   PRIORITY_CUSTOM,
   PRIORITY_ENVIRONMENT,

package/dist/prompt/instructions.d.ts

@@ -0,0 +1,104 @@
+/**
+ * Instruction File Discovery — Project rules from the filesystem
+ *
+ * Discovers instruction files (AGENTS.md, CLAUDE.md, COPILOT.md, etc.)
+ * by walking up the directory tree from cwd. These files provide
+ * project-specific or workspace-level guidance to the agent.
+ *
+ * Discovery order (general → specific):
+ * 1. Global instruction files (from config)
+ * 2. Workspace-level files (found near git root or higher directories)
+ * 3. Project-level files (found in or near cwd)
+ *
+ * All discovered files are included, ordered from most general to most
+ * specific. This means project-level instructions appear last and
+ * effectively take precedence in case of conflicting guidance.
+ *
+ * Compatible with:
+ * - AGENTS.md convention
+ * - CLAUDE.md convention
+ * - COPILOT.md convention
+ * - CuyLabs' own .cuylabs/instructions.md
+ */
+import type { InstructionFile } from "./types.js";
+/**
+ * Default file patterns to search for.
+ * Checked in each directory when walking up from cwd.
+ */
+export declare const DEFAULT_INSTRUCTION_PATTERNS: string[];
+/**
+ * Maximum file size for instruction files (50KB).
+ * Files larger than this are skipped to prevent prompt bloat.
+ */
+export declare const DEFAULT_MAX_FILE_SIZE = 51200;
+/**
+ * Maximum directories to walk up from cwd.
+ */
+export declare const DEFAULT_MAX_DEPTH = 10;
+/**
+ * Discover instruction files by walking up the directory tree from cwd.
+ *
+ * Searches for files matching the given patterns in each directory,
+ * starting from `cwd` and walking up to the filesystem root (or until
+ * `maxDepth` is reached).
+ *
+ * Results are ordered from **most general** (shallowest/root-level) to
+ * **most specific** (deepest/cwd-level), so that specific project rules
+ * appear last and take natural precedence.
+ *
+ * @param cwd - Starting directory for the search
+ * @param patterns - File name patterns to look for (e.g. ["AGENTS.md"])
+ * @param options - Discovery options
+ * @returns Array of discovered instruction files, general → specific
+ *
+ * @example
+ * ```typescript
+ * const files = await discoverInstructions("/Users/dev/project/src", [
+ *   "AGENTS.md",
+ *   "CLAUDE.md",
+ * ]);
+ *
+ * // Might find:
+ * // 1. /Users/dev/project/AGENTS.md (depth: 1, workspace)
+ * // 2. /Users/dev/project/src/AGENTS.md (depth: 0, project)
+ * ```
+ */
+export declare function discoverInstructions(cwd: string, patterns?: string[], options?: {
+    maxDepth?: number;
+    maxFileSize?: number;
+    stopAtGitRoot?: boolean;
+}): Promise<InstructionFile[]>;
+/**
+ * Load global instruction files from explicit paths.
+ *
+ * Global instructions are always included regardless of cwd.
+ * Useful for organization-wide coding standards or team rules.
+ *
+ * @param paths - Absolute paths to global instruction files
+ * @param maxSize - Maximum file size in bytes
+ * @returns Array of loaded instruction files
+ */
+export declare function loadGlobalInstructions(paths: string[], maxSize?: number): Promise<InstructionFile[]>;
+/**
+ * Format discovered instruction files into a prompt block.
+ *
+ * Each file is wrapped in a tagged block with its source path
+ * for transparency. Files are already ordered general → specific.
+ *
+ * Output example:
+ * ```
+ * <project-instructions>
+ *
+ * <instructions source="AGENTS.md" scope="workspace">
+ * ... workspace-level content ...
+ * </instructions>
+ *
+ * <instructions source="src/AGENTS.md" scope="project">
+ * ... project-specific content ...
+ * </instructions>
+ *
+ * </project-instructions>
+ * ```
+ */
+export declare function formatInstructions(files: InstructionFile[], basePath?: string): string;
+//# sourceMappingURL=instructions.d.ts.map

package/dist/prompt/instructions.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"instructions.d.ts","sourceRoot":"","sources":["../../src/prompt/instructions.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAKH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAMlD;;;GAGG;AACH,eAAO,MAAM,4BAA4B,UAKxC,CAAC;AAEF;;;GAGG;AACH,eAAO,MAAM,qBAAqB,QAAS,CAAC;AAE5C;;GAEG;AACH,eAAO,MAAM,iBAAiB,KAAK,CAAC;AAwDpC;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,wBAAsB,oBAAoB,CACxC,GAAG,EAAE,MAAM,EACX,QAAQ,GAAE,MAAM,EAAiC,EACjD,OAAO,CAAC,EAAE;IACR,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,aAAa,CAAC,EAAE,OAAO,CAAC;CACzB,GACA,OAAO,CAAC,eAAe,EAAE,CAAC,CAuD5B;AAED;;;;;;;;;GASG;AACH,wBAAsB,sBAAsB,CAC1C,KAAK,EAAE,MAAM,EAAE,EACf,OAAO,GAAE,MAA8B,GACtC,OAAO,CAAC,eAAe,EAAE,CAAC,CAgB5B;AAMD;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,kBAAkB,CAChC,KAAK,EAAE,eAAe,EAAE,EACxB,QAAQ,CAAC,EAAE,MAAM,GAChB,MAAM,CAwBR"}

package/dist/prompt/templates.d.ts

@@ -0,0 +1,56 @@
+/**
+ * Prompt Templates — Base system prompts per model family
+ *
+ * agent-core provides **generic, domain-agnostic** templates.
+ * These establish the agent's general approach and tool-use discipline
+ * without assuming a specific domain (coding, browsing, etc.).
+ *
+ * Domain-specific templates belong in consumer packages:
+ * - agent-code → coding templates ("read files before editing", etc.)
+ * - computer-agent → computer-use templates
+ * - your-custom-agent → whatever you need
+ *
+ * Consumer packages inject their templates via:
+ *   createPromptBuilder({ baseTemplate: MY_CODING_TEMPLATE })
+ *   builder.addSection({ id: "coding", ... })
+ *
+ * This file also contains model family detection, which IS infrastructure
+ * and belongs here — any consumer benefits from knowing the model family
+ * to optimize prompt formatting.
+ */
+import type { LanguageModel } from "ai";
+import type { ModelFamily } from "./types.js";
+/**
+ * Detect which model family a LanguageModel belongs to.
+ *
+ * Uses the provider string first (most reliable), then falls back
+ * to pattern matching on the model ID.
+ *
+ * @example
+ * ```typescript
+ * import { anthropic } from "@ai-sdk/anthropic";
+ * detectModelFamily(anthropic("claude-sonnet-4-20250514")); // "anthropic"
+ *
+ * import { openai } from "@ai-sdk/openai";
+ * detectModelFamily(openai("gpt-4o")); // "openai"
+ * ```
+ */
+export declare function detectModelFamily(model: LanguageModel): ModelFamily;
+/**
+ * Generic flat system-prompt fallback for callers that bypass the prompt
+ * pipeline and use `systemPrompt` directly.
+ */
+export declare const DEFAULT_SYSTEM_PROMPT = "You are a capable AI assistant with access to tools.\n\nThink step by step about what you need to do.\nUse the available tools to accomplish tasks.\nVerify your results after each action.\n\nIf a tool fails, try an alternative approach \u2014 do not give up after a single error.\nKeep working until the task is fully resolved or you have exhausted all options.";
+/**
+ * Get the base template for a model family.
+ *
+ * @param family - Model family identifier
+ * @returns The generic system prompt template
+ */
+export declare function getTemplate(family: ModelFamily): string;
+/**
+ * Get all available template families.
+ * Useful for debugging or letting users choose.
+ */
+export declare function getAvailableFamilies(): ModelFamily[];
+//# sourceMappingURL=templates.d.ts.map

package/dist/prompt/templates.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"templates.d.ts","sourceRoot":"","sources":["../../src/prompt/templates.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,IAAI,CAAC;AACxC,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAO9C;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,aAAa,GAAG,WAAW,CAuBnE;AAMD;;;GAGG;AACH,eAAO,MAAM,qBAAqB,8WAO+C,CAAC;AAgIlF;;;;;GAKG;AACH,wBAAgB,WAAW,CAAC,MAAM,EAAE,WAAW,GAAG,MAAM,CAEvD;AAED;;;GAGG;AACH,wBAAgB,oBAAoB,IAAI,WAAW,EAAE,CAEpD"}

package/dist/prompt/types.d.ts

@@ -0,0 +1,218 @@
+/**
+ * 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.
+ */
+import type { LanguageModel } from "ai";
+import type { SkillConfig } from "../skill/types.js";
+/**
+ * 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
+ */
+export type ModelFamily = "anthropic" | "openai" | "google" | "deepseek" | "default";
+/**
+ * Runtime environment information injected into the system prompt.
+ * Gives the model awareness of the working context.
+ */
+export 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.
+ */
+export 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
+ */
+export 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.
+ */
+export 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 },
+ *   ],
+ * });
+ * ```
+ */
+export 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;
+}
+//# sourceMappingURL=types.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/prompt/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,IAAI,CAAC;AACxC,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAMrD;;;;;;;;;GASG;AACH,MAAM,MAAM,WAAW,GACnB,WAAW,GACX,QAAQ,GACR,QAAQ,GACR,UAAU,GACV,SAAS,CAAC;AAMd;;;GAGG;AACH,MAAM,WAAW,eAAe;IAC9B,gCAAgC;IAChC,GAAG,EAAE,MAAM,CAAC;IACZ,qDAAqD;IACrD,QAAQ,EAAE,MAAM,CAAC;IACjB,yCAAyC;IACzC,IAAI,EAAE,MAAM,CAAC;IACb,qCAAqC;IACrC,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,0CAA0C;IAC1C,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,wCAAwC;IACxC,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,yBAAyB;IACzB,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAMD;;;;;;GAMG;AACH,MAAM,WAAW,eAAe;IAC9B,gCAAgC;IAChC,IAAI,EAAE,MAAM,CAAC;IACb,6BAA6B;IAC7B,OAAO,EAAE,MAAM,CAAC;IAChB,kCAAkC;IAClC,MAAM,EAAE,SAAS,GAAG,WAAW,GAAG,QAAQ,CAAC;IAC3C,0CAA0C;IAC1C,KAAK,EAAE,MAAM,CAAC;CACf;AAMD;;;;;;;;;;;;;GAaG;AACH,MAAM,WAAW,aAAa;IAC5B,yCAAyC;IACzC,EAAE,EAAE,MAAM,CAAC;IACX,0DAA0D;IAC1D,KAAK,EAAE,MAAM,CAAC;IACd,uCAAuC;IACvC,OAAO,EAAE,MAAM,CAAC;IAChB,gEAAgE;IAChE,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,qDAAqD;IACrD,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB;AAMD;;;;;GAKG;AACH,MAAM,WAAW,kBAAkB;IACjC,gCAAgC;IAChC,GAAG,EAAE,MAAM,CAAC;IACZ,oCAAoC;IACpC,KAAK,EAAE,aAAa,CAAC;IACrB,4DAA4D;IAC5D,SAAS,CAAC,EAAE,MAAM,EAAE,CAAC;IACrB,2DAA2D;IAC3D,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,yBAAyB;IACzB,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAMD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,MAAM,WAAW,YAAY;IAC3B;;;OAGG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC;IAEtB;;;OAGG;IACH,WAAW,CAAC,EAAE,WAAW,CAAC;IAE1B;;;OAGG;IACH,kBAAkB,CAAC,EAAE,OAAO,CAAC;IAE7B;;;OAGG;IACH,mBAAmB,CAAC,EAAE,OAAO,CAAC;IAE9B;;;;;OAKG;IACH,mBAAmB,CAAC,EAAE,MAAM,EAAE,CAAC;IAE/B;;;OAGG;IACH,kBAAkB,CAAC,EAAE,MAAM,EAAE,CAAC;IAE9B;;;;OAIG;IACH,mBAAmB,CAAC,EAAE,MAAM,CAAC;IAE7B;;;;OAIG;IACH,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAE5B;;;OAGG;IACH,QAAQ,CAAC,EAAE,aAAa,EAAE,CAAC;IAE3B;;;OAGG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;IAEnB;;;;;;;;;;;;;;;;;;;;;;;;;OAyBG;IACH,MAAM,CAAC,EAAE,WAAW,CAAC;CACtB"}