@cjhyy/code-shell-core 0.5.0-rc.0

package/dist/preset/index.js

@@ -0,0 +1,159 @@
+/**
+ * Built-in agent presets.
+ *
+ * Presets keep the core engine domain-agnostic while letting callers choose
+ * a default prompt, default tools, and safe permission shortcuts.
+ *
+ * System prompts are assembled from reusable markdown sections in
+ * src/prompt/sections/*.md — each preset declares which sections to include.
+ */
+import { loadSections } from "../prompt/section-loader.js";
+export const AGENT_PRESET_NAMES = ["general", "terminal-coding"];
+// ─── Tool sets ───────────────────────────────────────────────────
+const GENERAL_BUILTIN_TOOLS = [
+    "Read",
+    "Write",
+    "Edit",
+    "ApplyPatch",
+    "Glob",
+    "Grep",
+    "Bash",
+    "WebSearch",
+    "WebFetch",
+    "AskUserQuestion",
+    "Agent",
+    // AgentStatus removed: background agents now write to ~/.code-shell/agents/
+    // <id>.txt — the parent agent can Read/Bash tail that file for live progress.
+    // The implementation is still in the registry for SDK consumers if needed.
+    "AgentCancel",
+    "EnterPlanMode",
+    "ExitPlanMode",
+    "ToolSearch",
+    "TodoWrite",
+    "Sleep",
+    "Config",
+    "CronCreate",
+    "CronDelete",
+    "CronList",
+    "Skill",
+    "MCPTool",
+    "ListMcpResources",
+    "ReadMcpResource",
+    "RemoteTrigger",
+    "REPL",
+    "PowerShell",
+];
+const TERMINAL_CODING_EXTRA_TOOLS = [
+    "EnterWorktree",
+    "ExitWorktree",
+    "NotebookEdit",
+    "LSP",
+    "Brief",
+    "Arena",
+];
+// ─── Permission rules ────────────────────────────────────────────
+const GENERAL_PERMISSION_RULES = [
+    { tool: "Read", decision: "allow" },
+    { tool: "Glob", decision: "allow" },
+    { tool: "Grep", decision: "allow" },
+    { tool: "WebSearch", decision: "allow" },
+    { tool: "WebFetch", decision: "allow" },
+    { tool: "AskUserQuestion", decision: "allow" },
+    { tool: "Agent", decision: "allow" },
+    { tool: "AgentStatus", decision: "allow" },
+    { tool: "AgentCancel", decision: "allow" },
+    { tool: "EnterPlanMode", decision: "allow" },
+    { tool: "ExitPlanMode", decision: "allow" },
+    { tool: "ToolSearch", decision: "allow" },
+    { tool: "TodoWrite", decision: "allow" },
+    { tool: "Sleep", decision: "allow" },
+    { tool: "CronList", decision: "allow" },
+    { tool: "Skill", decision: "allow" },
+    { tool: "ListMcpResources", decision: "allow" },
+    { tool: "ReadMcpResource", decision: "allow" },
+];
+// ─── Preset definitions ──────────────────────────────────────────
+export const BUILTIN_AGENT_PRESETS = {
+    general: {
+        name: "general",
+        label: "General Orchestrator",
+        description: "Domain-agnostic orchestration for research, operations, automation, and long-running tasks.",
+        promptSections: ["base", "orchestration", "tone"],
+        injectGitStatus: false,
+        builtinTools: [...GENERAL_BUILTIN_TOOLS],
+        defaultPermissionRules: GENERAL_PERMISSION_RULES,
+    },
+    "terminal-coding": {
+        name: "terminal-coding",
+        label: "Terminal Coding Assistant",
+        description: "General orchestration plus coding-focused guidance and code-navigation tools.",
+        promptSections: ["base", "orchestration", "coding", "tone"],
+        injectGitStatus: true,
+        builtinTools: [...GENERAL_BUILTIN_TOOLS, ...TERMINAL_CODING_EXTRA_TOOLS],
+        defaultPermissionRules: [
+            ...GENERAL_PERMISSION_RULES,
+            { tool: "LSP", decision: "allow" },
+            { tool: "Brief", decision: "allow" },
+        ],
+    },
+};
+export const DEFAULT_AGENT_PRESET = "general";
+export const DEFAULT_CLI_PRESET = "terminal-coding";
+/** Registry of custom presets registered by external consumers. */
+const _customPresets = new Map();
+/**
+ * Register a custom agent preset.
+ *
+ * External repos can call this to add their own presets:
+ * ```ts
+ * import { registerPreset } from "code-shell";
+ *
+ * registerPreset({
+ *   name: "data-pipeline" as AgentPresetName,
+ *   label: "Data Pipeline Orchestrator",
+ *   description: "Manages ETL workflows and data quality checks.",
+ *   promptSections: ["base", "orchestration"],
+ *   injectGitStatus: false,
+ *   builtinTools: ["Read", "Write", "Bash", "Glob", "Grep", "Agent"],
+ *   defaultPermissionRules: [{ tool: "Read", decision: "allow" }],
+ * });
+ * ```
+ */
+export function registerPreset(preset) {
+    _customPresets.set(preset.name, preset);
+}
+/** List all available preset names (built-in + custom). */
+export function listPresetNames() {
+    return [...AGENT_PRESET_NAMES, ..._customPresets.keys()];
+}
+export function resolveAgentPreset(name) {
+    if (!name)
+        return BUILTIN_AGENT_PRESETS[DEFAULT_AGENT_PRESET];
+    // Check built-in first
+    const builtin = BUILTIN_AGENT_PRESETS[name];
+    if (builtin)
+        return builtin;
+    // Check custom presets
+    const custom = _customPresets.get(name);
+    if (custom)
+        return custom;
+    const allowed = listPresetNames().join(", ");
+    throw new Error(`Unknown agent preset "${name}". Available presets: ${allowed}`);
+}
+/**
+ * Build the full system prompt for a preset by loading and joining its sections.
+ */
+export function buildPresetSystemPrompt(preset) {
+    return loadSections(preset.promptSections);
+}
+export function resolveBuiltinToolNames(options) {
+    const preset = resolveAgentPreset(options?.preset);
+    const names = new Set(preset.builtinTools);
+    for (const name of options?.enabledBuiltinTools ?? []) {
+        names.add(name);
+    }
+    for (const name of options?.disabledBuiltinTools ?? []) {
+        names.delete(name);
+    }
+    return [...names];
+}

package/dist/product/define.d.ts

@@ -0,0 +1,60 @@
+/**
+ * defineProduct — assemble a domain-specific agent product from preset + adapter + contract.
+ *
+ * This is the primary entry point for external repos. One call produces a
+ * ready-to-use RunManager that embodies the product's behavior.
+ *
+ * Example (in an external repo):
+ * ```ts
+ * import { defineProduct } from "code-shell";
+ *
+ * const { manager, preset } = defineProduct({
+ *   preset: {
+ *     name: "security-audit",
+ *     label: "Security Audit Agent",
+ *     description: "Scans repos for OWASP top 10 vulnerabilities.",
+ *     sections: ["base", "orchestration"],
+ *     appendPrompt: "You are a security expert. Focus on...",
+ *   },
+ *   adapter: {
+ *     tools: [myCustomScanTool],
+ *     enableTools: ["Read", "Glob", "Grep", "Bash"],
+ *     permissionRules: [{ tool: "Bash", decision: "ask" }],
+ *   },
+ *   contract: {
+ *     evaluator: new SecurityEvaluator(),
+ *     defaultTags: ["security"],
+ *     maxTurns: 50,
+ *   },
+ * }, {
+ *   llm: { provider: "openai", model: "...", apiKey: "..." },
+ * });
+ *
+ * await manager.submit({ objective: "Audit auth module for SQL injection" });
+ * ```
+ */
+import type { LLMConfig, PermissionMode } from "../types.js";
+import type { AgentPreset } from "../preset/index.js";
+import { RunManager } from "../run/RunManager.js";
+import type { ProductDefinition, CustomTool } from "./types.js";
+export interface ProductRuntimeOptions {
+    /** LLM configuration (required). */
+    llm: LLMConfig;
+    /** Permission mode. Default: "acceptEdits" */
+    permissionMode?: PermissionMode;
+    /** Working directory. Default: process.cwd() */
+    cwd?: string;
+    /** Storage directory for runs. Default: ~/.code-shell/runs */
+    runsDir?: string;
+    /** Storage directory for sessions. */
+    sessionStorageDir?: string;
+}
+export interface ProductInstance {
+    /** The configured RunManager, ready for submit/resume/cancel. */
+    manager: RunManager;
+    /** The registered preset (can be used to create Engine directly). */
+    preset: AgentPreset;
+    /** Custom tools registered by the adapter (for reference). */
+    customTools: CustomTool[];
+}
+export declare function defineProduct(definition: ProductDefinition, runtime: ProductRuntimeOptions): ProductInstance;

package/dist/product/define.js

@@ -0,0 +1,123 @@
+/**
+ * defineProduct — assemble a domain-specific agent product from preset + adapter + contract.
+ *
+ * This is the primary entry point for external repos. One call produces a
+ * ready-to-use RunManager that embodies the product's behavior.
+ *
+ * Example (in an external repo):
+ * ```ts
+ * import { defineProduct } from "code-shell";
+ *
+ * const { manager, preset } = defineProduct({
+ *   preset: {
+ *     name: "security-audit",
+ *     label: "Security Audit Agent",
+ *     description: "Scans repos for OWASP top 10 vulnerabilities.",
+ *     sections: ["base", "orchestration"],
+ *     appendPrompt: "You are a security expert. Focus on...",
+ *   },
+ *   adapter: {
+ *     tools: [myCustomScanTool],
+ *     enableTools: ["Read", "Glob", "Grep", "Bash"],
+ *     permissionRules: [{ tool: "Bash", decision: "ask" }],
+ *   },
+ *   contract: {
+ *     evaluator: new SecurityEvaluator(),
+ *     defaultTags: ["security"],
+ *     maxTurns: 50,
+ *   },
+ * }, {
+ *   llm: { provider: "openai", model: "...", apiKey: "..." },
+ * });
+ *
+ * await manager.submit({ objective: "Audit auth module for SQL injection" });
+ * ```
+ */
+import { registerPreset } from "../preset/index.js";
+import { CompositeEvaluator, NoopEvaluator } from "../run/Evaluator.js";
+import { RunManager } from "../run/RunManager.js";
+import { FileRunStore } from "../run/FileRunStore.js";
+import { join } from "node:path";
+import { homedir } from "node:os";
+// ─── Main function ─────────────────────────────────────��─────────
+export function defineProduct(definition, runtime) {
+    const { preset: presetDef, adapter, contract } = definition;
+    // ── 1. Build and register preset ──────────────────────────────
+    const presetName = presetDef.name;
+    // Determine builtin tools: start from a base set, apply adapter overrides
+    const baseTools = [
+        "Read", "Write", "Edit", "Glob", "Grep", "Bash",
+        "AskUserQuestion", "Agent", "ToolSearch",
+        "TodoWrite",
+    ];
+    const enabledSet = new Set([...baseTools, ...(adapter?.enableTools ?? [])]);
+    for (const t of adapter?.disableTools ?? []) {
+        enabledSet.delete(t);
+    }
+    // Combine permission rules
+    const permissionRules = [
+        // Default safe rules
+        { tool: "Read", decision: "allow" },
+        { tool: "Glob", decision: "allow" },
+        { tool: "Grep", decision: "allow" },
+        { tool: "AskUserQuestion", decision: "allow" },
+        { tool: "ToolSearch", decision: "allow" },
+        { tool: "TodoWrite", decision: "allow" },
+        // Product-specific rules (higher priority)
+        ...(adapter?.permissionRules ?? []),
+    ];
+    const agentPreset = {
+        name: presetName,
+        label: presetDef.label,
+        description: presetDef.description,
+        promptSections: presetDef.sections ?? ["base", "orchestration"],
+        injectGitStatus: presetDef.injectGitStatus ?? false,
+        builtinTools: [...enabledSet],
+        defaultPermissionRules: permissionRules,
+    };
+    registerPreset(agentPreset);
+    // ── 2. Build evaluator from contract ──────────────────────────
+    let evaluator;
+    if (!contract?.evaluator) {
+        evaluator = new NoopEvaluator();
+    }
+    else if (Array.isArray(contract.evaluator)) {
+        evaluator = new CompositeEvaluator(contract.evaluator);
+    }
+    else {
+        evaluator = contract.evaluator;
+    }
+    // ── 3. Collect custom tools ────────────────────────────────────
+    const customTools = adapter?.tools ?? [];
+    // Convert product CustomTool[] to EngineRunner's CustomToolEntry[]
+    const customToolEntries = customTools.map((ct) => ({
+        definition: ct.definition,
+        execute: ct.execute,
+    }));
+    // ── 4. Build RunManager ───────────────────────────────────────
+    const runsDir = runtime.runsDir ?? join(homedir(), ".code-shell", "runs");
+    const store = new FileRunStore(runsDir);
+    const manager = new RunManager({
+        store,
+        executor: {
+            llm: runtime.llm,
+            maxTurns: contract?.maxTurns ?? 30,
+            maxContextTokens: contract?.maxContextTokens ?? 200_000,
+            permissionMode: runtime.permissionMode ?? "acceptEdits",
+            sessionStorageDir: runtime.sessionStorageDir,
+            mcpServers: adapter?.mcpServers,
+            enabledBuiltinTools: [...enabledSet],
+            disabledBuiltinTools: adapter?.disableTools,
+            customSystemPrompt: presetDef.customPrompt,
+            appendSystemPrompt: presetDef.appendPrompt,
+            hooks: adapter?.hooks,
+            customTools: customToolEntries.length > 0 ? customToolEntries : undefined,
+        },
+        concurrency: contract?.concurrency ?? 1,
+        runsDir,
+        evaluator,
+        defaultTags: contract?.defaultTags,
+        defaultMetadata: contract?.defaultMetadata,
+    });
+    return { manager, preset: agentPreset, customTools };
+}

package/dist/product/index.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Product module — build domain-specific agents on CodeShell.
+ */
+export type { ProductDefinition, ProductPreset, ProductAdapter, ProductContract, CustomTool, } from "./types.js";
+export { defineProduct, type ProductRuntimeOptions, type ProductInstance, } from "./define.js";

package/dist/product/index.js

@@ -0,0 +1,4 @@
+/**
+ * Product module — build domain-specific agents on CodeShell.
+ */
+export { defineProduct, } from "./define.js";

package/dist/product/types.d.ts

@@ -0,0 +1,111 @@
+/**
+ * Product Adapter — the contract for turning CodeShell into a domain-specific agent.
+ *
+ * A "product" is a concrete agent application built on top of CodeShell.
+ * Examples:
+ *   - Code reviewer agent
+ *   - Data pipeline orchestrator
+ *   - DevOps deployment agent
+ *   - Documentation writer
+ *   - Security audit agent
+ *
+ * To build a product, an external repo provides:
+ *
+ *   1. **Preset** (brain)     — system prompt, tool set, permission rules
+ *   2. **Adapter** (hands)    — custom tools, MCP servers, domain-specific IO
+ *   3. **Contract** (quality) — evaluator, completion criteria, artifact specs
+ *
+ * These three layers compose into a ProductDefinition that CodeShell's
+ * `defineProduct()` function turns into a fully configured RunManager.
+ */
+import type { PermissionRule, MCPServerConfig } from "../types.js";
+import type { Evaluator } from "../run/Evaluator.js";
+import type { RegisteredTool } from "../types.js";
+import type { EngineHookConfig } from "../engine/engine.js";
+export interface ProductPreset {
+    /** Unique name for this product's preset. */
+    name: string;
+    /** Human-readable label. */
+    label: string;
+    /** One-line description. */
+    description: string;
+    /**
+     * System prompt for the agent. Two options:
+     *   - `sections`: reuse CodeShell's built-in markdown sections (e.g. ["base", "orchestration"])
+     *   - `customPrompt`: provide a full custom system prompt string
+     * If both are provided, customPrompt takes precedence.
+     */
+    sections?: string[];
+    customPrompt?: string;
+    /** Additional text appended after the main system prompt. */
+    appendPrompt?: string;
+    /** Whether to inject git status into system context. Default: false */
+    injectGitStatus?: boolean;
+}
+export interface CustomTool {
+    /** Tool definition (name, description, inputSchema). */
+    definition: RegisteredTool;
+    /** Tool executor function. */
+    execute: (args: Record<string, unknown>) => Promise<string>;
+}
+export interface ProductAdapter {
+    /**
+     * Custom tools specific to this product domain.
+     * These are registered in addition to the preset's builtin tools.
+     */
+    tools?: CustomTool[];
+    /**
+     * MCP servers to connect (external tool providers).
+     */
+    mcpServers?: Record<string, MCPServerConfig>;
+    /**
+     * Builtin tools to explicitly enable (add to preset defaults).
+     */
+    enableTools?: string[];
+    /**
+     * Builtin tools to explicitly disable (remove from preset defaults).
+     */
+    disableTools?: string[];
+    /**
+     * Permission rules specific to this product.
+     * Applied on top of the preset's default rules.
+     */
+    permissionRules?: PermissionRule[];
+    /**
+     * Hooks to register for this product.
+     * Key: hook event name, Value: handler function.
+     */
+    hooks?: EngineHookConfig[];
+}
+export interface ProductContract {
+    /**
+     * Evaluator(s) to run on completion.
+     * Can be a single Evaluator or an array (composed automatically).
+     */
+    evaluator?: Evaluator | Evaluator[];
+    /**
+     * Default tags applied to every run submitted through this product.
+     */
+    defaultTags?: string[];
+    /**
+     * Default metadata attached to every run.
+     */
+    defaultMetadata?: Record<string, unknown>;
+    /**
+     * Maximum turns per run. Overrides the default 30.
+     */
+    maxTurns?: number;
+    /**
+     * Maximum context tokens. Overrides the default 200_000.
+     */
+    maxContextTokens?: number;
+    /**
+     * Queue concurrency. Default: 1.
+     */
+    concurrency?: number;
+}
+export interface ProductDefinition {
+    preset: ProductPreset;
+    adapter?: ProductAdapter;
+    contract?: ProductContract;
+}

package/dist/product/types.js

@@ -0,0 +1,21 @@
+/**
+ * Product Adapter — the contract for turning CodeShell into a domain-specific agent.
+ *
+ * A "product" is a concrete agent application built on top of CodeShell.
+ * Examples:
+ *   - Code reviewer agent
+ *   - Data pipeline orchestrator
+ *   - DevOps deployment agent
+ *   - Documentation writer
+ *   - Security audit agent
+ *
+ * To build a product, an external repo provides:
+ *
+ *   1. **Preset** (brain)     — system prompt, tool set, permission rules
+ *   2. **Adapter** (hands)    — custom tools, MCP servers, domain-specific IO
+ *   3. **Contract** (quality) — evaluator, completion criteria, artifact specs
+ *
+ * These three layers compose into a ProductDefinition that CodeShell's
+ * `defineProduct()` function turns into a fully configured RunManager.
+ */
+export {};

package/dist/prompt/composer.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Prompt composer — assembles system prompt from sections.
+ *
+ * Following Claude Code's dual-chain architecture:
+ *   system chain → API request "system" field
+ *   messages chain → API request "messages" field (userContext prepended)
+ */
+import type { ToolDefinition, Message } from "../types.js";
+import { type ScanOptions } from "./instruction-scanner.js";
+import { type AgentPreset } from "../preset/index.js";
+export interface ComposerOptions {
+    cwd: string;
+    model: string;
+    instructionOptions?: ScanOptions;
+    /** Resolved preset — used to load section-based prompt. */
+    preset?: AgentPreset;
+    customSystemPrompt?: string;
+    appendSystemPrompt?: string;
+    /**
+     * Skill names (full names including any "<plugin>:" prefix) the user
+     * has disabled in settings. Filtered out of the LLM's skills listing
+     * so the prompt matches what the skill builtin tool will actually
+     * dispatch — see scanSkills(opts.disabledSkills) and skillTool.
+     */
+    disabledSkills?: string[];
+}
+export declare class PromptComposer {
+    private readonly options;
+    private sectionCache;
+    private cachedInstructions;
+    constructor(options: ComposerOptions);
+    /**
+     * Build the system prompt from sections.
+     */
+    buildSystemPrompt(tools: ToolDefinition[]): Promise<string>;
+    /**
+     * Build the userContext prefix message (CLAUDE.md content as <system-reminder>).
+     */
+    buildUserContextMessage(): Message | null;
+    /**
+     * Build the systemContext (gitStatus etc.) to append to system prompt.
+     * Only injects git status if the resolved preset opts in.
+     */
+    buildSystemContext(): Promise<string>;
+    invalidateCache(sectionName?: string): void;
+    private getSections;
+    private getInstructions;
+    private getMemoryContext;
+}