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

package/dist/exceptions.d.ts

@@ -0,0 +1,61 @@
+/**
+ * Custom exception hierarchy for the code-shell framework.
+ */
+export declare class FrameworkError extends Error {
+    readonly details?: Record<string, unknown> | undefined;
+    constructor(message: string, details?: Record<string, unknown> | undefined);
+}
+export declare class LLMError extends FrameworkError {
+    readonly provider?: string | undefined;
+    constructor(message: string, provider?: string | undefined, details?: Record<string, unknown>);
+}
+export declare class LLMRateLimitError extends LLMError {
+    readonly retryAfter?: number | undefined;
+    constructor(provider: string, retryAfter?: number | undefined);
+}
+export declare class ContextLimitError extends LLMError {
+    constructor(provider?: string);
+}
+export declare class ToolError extends FrameworkError {
+    readonly toolName?: string | undefined;
+    constructor(message: string, toolName?: string | undefined, details?: Record<string, unknown>);
+}
+export declare class ToolNotFoundError extends ToolError {
+    constructor(toolName: string);
+}
+export declare class ToolExecutionError extends ToolError {
+    constructor(toolName: string, cause: string);
+}
+export declare class ToolTimeoutError extends ToolError {
+    readonly timeoutMs: number;
+    constructor(toolName: string, timeoutMs: number);
+}
+export declare class PermissionDeniedError extends FrameworkError {
+    constructor(toolName: string, reason?: string);
+}
+export declare class SessionError extends FrameworkError {
+    constructor(message: string, details?: Record<string, unknown>);
+}
+export declare class TranscriptError extends FrameworkError {
+    constructor(message: string, details?: Record<string, unknown>);
+}
+export declare class ConfigError extends FrameworkError {
+    constructor(message: string, details?: Record<string, unknown>);
+}
+/**
+ * Thrown by `resolveSandboxBackend` when an explicit sandbox mode is
+ * requested but the corresponding backend is unavailable on this host
+ * (e.g. `mode=seatbelt` on Linux, `mode=bwrap` without bubblewrap
+ * installed). The literal `code` field lets SDK callers narrow without
+ * `instanceof`: `if (err.code === "SANDBOX_UNAVAILABLE") { ... }`.
+ *
+ * Per standard §S4, explicit modes fail closed — only `auto` may
+ * silently downgrade to `off`. `mode` here is always one of the two
+ * explicit modes that can throw; `off` and `auto` never throw.
+ */
+export declare class SandboxUnavailableError extends FrameworkError {
+    readonly mode: "seatbelt" | "bwrap";
+    readonly platform: NodeJS.Platform;
+    readonly code: "SANDBOX_UNAVAILABLE";
+    constructor(mode: "seatbelt" | "bwrap", platform: NodeJS.Platform, message: string);
+}

package/dist/exceptions.js

@@ -0,0 +1,116 @@
+/**
+ * Custom exception hierarchy for the code-shell framework.
+ */
+export class FrameworkError extends Error {
+    details;
+    constructor(message, details) {
+        super(message);
+        this.details = details;
+        this.name = "FrameworkError";
+    }
+}
+// ─── LLM Errors ───────────────────────────────────────────────────
+export class LLMError extends FrameworkError {
+    provider;
+    constructor(message, provider, details) {
+        super(message, details);
+        this.provider = provider;
+        this.name = "LLMError";
+    }
+}
+export class LLMRateLimitError extends LLMError {
+    retryAfter;
+    constructor(provider, retryAfter) {
+        super(`Rate limit exceeded for ${provider}`, provider, { retryAfter });
+        this.retryAfter = retryAfter;
+        this.name = "LLMRateLimitError";
+    }
+}
+export class ContextLimitError extends LLMError {
+    constructor(provider) {
+        super("Context limit exceeded", provider);
+        this.name = "ContextLimitError";
+    }
+}
+// ─── Tool Errors ──────────────────────────────────────────────────
+export class ToolError extends FrameworkError {
+    toolName;
+    constructor(message, toolName, details) {
+        super(message, details);
+        this.toolName = toolName;
+        this.name = "ToolError";
+    }
+}
+export class ToolNotFoundError extends ToolError {
+    constructor(toolName) {
+        super(`Tool not found: ${toolName}`, toolName);
+        this.name = "ToolNotFoundError";
+    }
+}
+export class ToolExecutionError extends ToolError {
+    constructor(toolName, cause) {
+        super(`Tool execution failed: ${toolName} - ${cause}`, toolName, { cause });
+        this.name = "ToolExecutionError";
+    }
+}
+export class ToolTimeoutError extends ToolError {
+    timeoutMs;
+    constructor(toolName, timeoutMs) {
+        super(`Tool timed out after ${timeoutMs}ms: ${toolName}`, toolName, { timeoutMs });
+        this.timeoutMs = timeoutMs;
+        this.name = "ToolTimeoutError";
+    }
+}
+// ─── Permission Errors ────────────────────────────────────────────
+export class PermissionDeniedError extends FrameworkError {
+    constructor(toolName, reason) {
+        super(`Permission denied for tool: ${toolName}${reason ? ` - ${reason}` : ""}`, {
+            toolName,
+            reason,
+        });
+        this.name = "PermissionDeniedError";
+    }
+}
+// ─── Session Errors ───────────────────────────────────────────────
+export class SessionError extends FrameworkError {
+    constructor(message, details) {
+        super(message, details);
+        this.name = "SessionError";
+    }
+}
+export class TranscriptError extends FrameworkError {
+    constructor(message, details) {
+        super(message, details);
+        this.name = "TranscriptError";
+    }
+}
+// ─── Config Errors ────────────────────────────────────────────────
+export class ConfigError extends FrameworkError {
+    constructor(message, details) {
+        super(message, details);
+        this.name = "ConfigError";
+    }
+}
+// ─── Sandbox Errors ───────────────────────────────────────────────
+/**
+ * Thrown by `resolveSandboxBackend` when an explicit sandbox mode is
+ * requested but the corresponding backend is unavailable on this host
+ * (e.g. `mode=seatbelt` on Linux, `mode=bwrap` without bubblewrap
+ * installed). The literal `code` field lets SDK callers narrow without
+ * `instanceof`: `if (err.code === "SANDBOX_UNAVAILABLE") { ... }`.
+ *
+ * Per standard §S4, explicit modes fail closed — only `auto` may
+ * silently downgrade to `off`. `mode` here is always one of the two
+ * explicit modes that can throw; `off` and `auto` never throw.
+ */
+export class SandboxUnavailableError extends FrameworkError {
+    mode;
+    platform;
+    code = "SANDBOX_UNAVAILABLE";
+    constructor(mode, platform, message) {
+        super(message, { code: "SANDBOX_UNAVAILABLE", mode, platform });
+        this.mode = mode;
+        this.platform = platform;
+        this.name = "SandboxUnavailableError";
+    }
+}

package/dist/git/utils.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Git utility functions for the git workflow commands.
+ */
+export interface GitStatusEntry {
+    status: string;
+    path: string;
+}
+export interface GitLogEntry {
+    hash: string;
+    message: string;
+    author: string;
+    date: string;
+}
+export declare function isGitRepo(cwd: string): boolean;
+export declare function getCurrentBranch(cwd: string): string;
+export declare function getGitStatus(cwd: string): GitStatusEntry[];
+export declare function getGitDiff(cwd: string, opts?: {
+    staged?: boolean;
+    file?: string;
+}): string;
+export declare function getGitDiffStat(cwd: string, opts?: {
+    staged?: boolean;
+    file?: string;
+}): string;
+export declare function getGitLog(cwd: string, n?: number): GitLogEntry[];
+export declare function getRemoteUrl(cwd: string): string | undefined;
+export declare function gitAdd(cwd: string, files?: string[]): void;
+export declare function gitCommit(cwd: string, message: string): string;
+export declare function gitListBranches(cwd: string): {
+    name: string;
+    current: boolean;
+}[];
+export declare function gitCheckout(cwd: string, branch: string, create?: boolean): void;
+export declare function ghAvailable(): boolean;
+export declare function ghPrComments(cwd: string, prUrl: string): string;

package/dist/git/utils.js

@@ -0,0 +1,98 @@
+/**
+ * Git utility functions for the git workflow commands.
+ */
+import { execSync } from "node:child_process";
+export function isGitRepo(cwd) {
+    try {
+        execSync("git rev-parse --is-inside-work-tree", { cwd, encoding: "utf-8", timeout: 5000 });
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+export function getCurrentBranch(cwd) {
+    return execSync("git branch --show-current", { cwd, encoding: "utf-8", timeout: 5000 }).trim();
+}
+export function getGitStatus(cwd) {
+    const raw = execSync("git status --porcelain", { cwd, encoding: "utf-8", timeout: 10000 }).trim();
+    if (!raw)
+        return [];
+    return raw.split("\n").map((line) => ({
+        status: line.slice(0, 2).trim(),
+        path: line.slice(3),
+    }));
+}
+export function getGitDiff(cwd, opts) {
+    const args = ["git", "diff", "--no-color"];
+    if (opts?.staged)
+        args.push("--staged");
+    if (opts?.file)
+        args.push("--", opts.file);
+    return execSync(args.join(" "), { cwd, encoding: "utf-8", timeout: 30000 }).trim();
+}
+export function getGitDiffStat(cwd, opts) {
+    const args = ["git", "diff", "--stat", "--no-color"];
+    if (opts?.staged)
+        args.push("--staged");
+    if (opts?.file)
+        args.push("--", opts.file);
+    return execSync(args.join(" "), { cwd, encoding: "utf-8", timeout: 10000 }).trim();
+}
+export function getGitLog(cwd, n = 10) {
+    const raw = execSync(`git log --oneline --format="%H|%s|%an|%ci" -${n}`, { cwd, encoding: "utf-8", timeout: 10000 }).trim();
+    if (!raw)
+        return [];
+    return raw.split("\n").map((line) => {
+        const [hash, message, author, date] = line.split("|");
+        return { hash: hash.slice(0, 8), message, author, date };
+    });
+}
+export function getRemoteUrl(cwd) {
+    try {
+        return execSync("git remote get-url origin", { cwd, encoding: "utf-8", timeout: 5000 }).trim();
+    }
+    catch {
+        return undefined;
+    }
+}
+export function gitAdd(cwd, files = ["."]) {
+    const fileArgs = files.map((f) => `"${f}"`).join(" ");
+    execSync(`git add ${fileArgs}`, { cwd, timeout: 10000 });
+}
+export function gitCommit(cwd, message) {
+    return execSync(`git commit -m ${JSON.stringify(message)}`, {
+        cwd,
+        encoding: "utf-8",
+        timeout: 30000,
+    }).trim();
+}
+export function gitListBranches(cwd) {
+    const raw = execSync("git branch --no-color", { cwd, encoding: "utf-8", timeout: 5000 }).trim();
+    if (!raw)
+        return [];
+    return raw.split("\n").map((line) => ({
+        current: line.startsWith("*"),
+        name: line.replace(/^\*?\s+/, "").trim(),
+    }));
+}
+export function gitCheckout(cwd, branch, create = false) {
+    const flag = create ? "-b" : "";
+    execSync(`git checkout ${flag} ${branch}`, { cwd, timeout: 10000 });
+}
+export function ghAvailable() {
+    try {
+        execSync("gh --version", { encoding: "utf-8", timeout: 5000 });
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+export function ghPrComments(cwd, prUrl) {
+    return execSync(`gh pr view ${prUrl} --comments --json comments -q ".comments[].body"`, {
+        cwd,
+        encoding: "utf-8",
+        timeout: 30000,
+    }).trim();
+}

package/dist/git/worktree.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Git worktree management — create/remove isolated worktrees for agents.
+ */
+export interface WorktreeSession {
+    originalCwd: string;
+    worktreePath: string;
+    worktreeName: string;
+    worktreeBranch: string;
+    originalBranch?: string;
+    sessionId: string;
+    createdAt: number;
+}
+/**
+ * Validate worktree slug to prevent path traversal attacks.
+ */
+export declare function validateWorktreeSlug(slug: string): void;
+/**
+ * Find the canonical git root (resolves worktree → main repo).
+ */
+export declare function findGitRoot(cwd: string): string;
+/**
+ * Create an isolated git worktree for an agent session.
+ */
+export declare function createWorktree(cwd: string, slug: string, sessionId: string): WorktreeSession;
+/**
+ * Remove a worktree and optionally its branch.
+ */
+export declare function removeWorktree(worktreePath: string, removeBranch?: boolean): void;
+/**
+ * List active worktrees.
+ */
+export declare function listWorktrees(cwd: string): Array<{
+    path: string;
+    branch: string;
+    head: string;
+}>;

package/dist/git/worktree.js

@@ -0,0 +1,139 @@
+/**
+ * Git worktree management — create/remove isolated worktrees for agents.
+ */
+import { execSync } from "node:child_process";
+import { existsSync, symlinkSync, lstatSync } from "node:fs";
+import { join, resolve } from "node:path";
+/**
+ * Validate worktree slug to prevent path traversal attacks.
+ */
+export function validateWorktreeSlug(slug) {
+    if (slug.length > 64)
+        throw new Error("Worktree slug too long (max 64 chars)");
+    if (/[^a-zA-Z0-9._-]/.test(slug))
+        throw new Error("Worktree slug contains invalid characters");
+    if (slug.startsWith(".") || slug.includes(".."))
+        throw new Error("Worktree slug cannot start with '.' or contain '..'");
+}
+/**
+ * Find the canonical git root (resolves worktree → main repo).
+ */
+export function findGitRoot(cwd) {
+    return execSync("git rev-parse --show-toplevel", { cwd, encoding: "utf-8", timeout: 5000 }).trim();
+}
+/**
+ * Create an isolated git worktree for an agent session.
+ */
+export function createWorktree(cwd, slug, sessionId) {
+    validateWorktreeSlug(slug);
+    const gitRoot = findGitRoot(cwd);
+    const branchName = `worktree/${slug}-${sessionId.slice(0, 8)}`;
+    const worktreePath = resolve(gitRoot, "..", `.worktrees/${slug}-${sessionId.slice(0, 8)}`);
+    // Get current branch for later reference
+    let originalBranch;
+    try {
+        originalBranch = execSync("git branch --show-current", {
+            cwd: gitRoot,
+            encoding: "utf-8",
+            timeout: 5000,
+        }).trim();
+    }
+    catch {
+        // Detached HEAD
+    }
+    // Create the worktree
+    execSync(`git worktree add -b "${branchName}" "${worktreePath}"`, {
+        cwd: gitRoot,
+        timeout: 30000,
+    });
+    // Symlink large directories to avoid disk bloat
+    symlinkLargeDirectories(gitRoot, worktreePath);
+    return {
+        originalCwd: cwd,
+        worktreePath,
+        worktreeName: slug,
+        worktreeBranch: branchName,
+        originalBranch,
+        sessionId,
+        createdAt: Date.now(),
+    };
+}
+/**
+ * Remove a worktree and optionally its branch.
+ */
+export function removeWorktree(worktreePath, removeBranch = false) {
+    try {
+        const gitRoot = findGitRoot(worktreePath);
+        execSync(`git worktree remove "${worktreePath}" --force`, {
+            cwd: gitRoot,
+            timeout: 30000,
+        });
+        if (removeBranch) {
+            // Extract branch name from worktree
+            try {
+                const branch = execSync("git branch --show-current", {
+                    cwd: worktreePath,
+                    encoding: "utf-8",
+                    timeout: 5000,
+                }).trim();
+                if (branch.startsWith("worktree/")) {
+                    execSync(`git branch -D "${branch}"`, { cwd: gitRoot, timeout: 10000 });
+                }
+            }
+            catch {
+                // Branch might already be removed
+            }
+        }
+    }
+    catch {
+        // Worktree might already be removed
+    }
+}
+/**
+ * List active worktrees.
+ */
+export function listWorktrees(cwd) {
+    const raw = execSync("git worktree list --porcelain", {
+        cwd,
+        encoding: "utf-8",
+        timeout: 10000,
+    }).trim();
+    if (!raw)
+        return [];
+    const entries = [];
+    let current = { path: "", branch: "", head: "" };
+    for (const line of raw.split("\n")) {
+        if (line.startsWith("worktree ")) {
+            if (current.path)
+                entries.push(current);
+            current = { path: line.slice(9), branch: "", head: "" };
+        }
+        else if (line.startsWith("HEAD ")) {
+            current.head = line.slice(5, 13);
+        }
+        else if (line.startsWith("branch ")) {
+            current.branch = line.slice(7).replace("refs/heads/", "");
+        }
+    }
+    if (current.path)
+        entries.push(current);
+    return entries;
+}
+/**
+ * Symlink large directories (node_modules, .venv, etc.) from main repo to worktree.
+ */
+function symlinkLargeDirectories(sourceRoot, worktreePath) {
+    const largeDirs = ["node_modules", ".venv", "vendor", ".pnpm-store"];
+    for (const dir of largeDirs) {
+        const source = join(sourceRoot, dir);
+        const target = join(worktreePath, dir);
+        if (existsSync(source) && lstatSync(source).isDirectory() && !existsSync(target)) {
+            try {
+                symlinkSync(source, target, "dir");
+            }
+            catch {
+                // Symlink might fail on some systems
+            }
+        }
+    }
+}

package/dist/hooks/events.d.ts

@@ -0,0 +1,114 @@
+/**
+ * Hook event type definitions.
+ */
+/**
+ * Lifecycle hooks the engine emits.
+ *
+ * **Currently emitted** (handlers registered here will actually fire):
+ *   - on_session_start / on_session_end    (engine.ts) — fires once per Engine.run().
+ *                                          on_session_start handlers may return
+ *                                          `messages` to inject a <system-reminder>
+ *                                          at the head of the conversation, before
+ *                                          the current user prompt.
+ *   - on_agent_start / on_agent_end        (engine.ts) — notify-only; returned
+ *                                          messages are NOT consumed (the loop
+ *                                          is already armed by the time these
+ *                                          fire). Use on_session_start instead.
+ *   - user_prompt_submit                   (engine.ts) — fires once per run() for
+ *                                          every new user prompt (cold-start and
+ *                                          resume both qualify). Returned messages
+ *                                          are merged into the same lifecycle
+ *                                          <system-reminder> as on_session_start.
+ *   - on_turn_start / on_turn_end          (turn-loop.ts) — on_turn_start handlers
+ *                                          may return `messages` to inject a
+ *                                          per-turn reminder appended to the
+ *                                          conversation right before the model call.
+ *   - pre_tool_use / post_tool_use         (executor.ts) — pre_tool_use honors
+ *                                          `decision: "deny"` to short-circuit
+ *                                          the call (executor.ts:131).
+ *   - on_tool_start / on_tool_end          (executor.ts)
+ *   - file_changed                         (executor.ts, Write/Edit only)
+ *   - on_permission_check                  (executor.ts) — fires after the
+ *                                          classifier runs and before its
+ *                                          decision is acted on. Handler can
+ *                                          override via `decision`; the
+ *                                          override is logged as
+ *                                          `permission.hook_override`. ctx.data
+ *                                          carries `classifierDecision` so
+ *                                          handlers can branch on the rule
+ *                                          set's verdict.
+ *   - post_compact                         (turn-loop.ts) — fires after
+ *                                          ContextManager.manageAsync() runs
+ *                                          a non-micro compaction. Handlers
+ *                                          may return `messages` to inject a
+ *                                          <system-reminder> into the same
+ *                                          turn before the model call. ctx.data
+ *                                          carries `strategy` (summary/snip/
+ *                                          window/emergency), `beforeTokens`,
+ *                                          `afterTokens`. Microcompact is
+ *                                          intentionally suppressed.
+ *   - notification                         (agent.ts) — fired when a background
+ *                                          sub-agent transitions to a terminal
+ *                                          state. ctx.data carries `kind`
+ *                                          ("agent_completed" / "agent_failed" /
+ *                                          "agent_cancelled"), `agentId`,
+ *                                          `name`, `description`, plus
+ *                                          `finalText` (completed) or `error`
+ *                                          (failed). Fired void — handler
+ *                                          latency does not block the main
+ *                                          loop. Not consumed by the engine
+ *                                          (bg-agent feed renders the same
+ *                                          info via notificationQueue);
+ *                                          intended for shell hooks (osascript
+ *                                          / desktop notifications).
+ *
+ * All Engine-side emits run through Engine.emitHook / TurnLoop.emitHook, which
+ * auto-merge `isSubAgent` (and sessionId, for turn-loop) into ctx.data so
+ * handlers can skip noisy injections for spawned children.
+ *
+ * **Reserved / not-yet-emitted** (defined so downstream can register handlers
+ * in anticipation; wire the emitter before relying on them):
+ *   - pre_compact   — would require pre-flight prediction inside
+ *                     ContextManager; current implementation only knows
+ *                     after-the-fact (use post_compact instead).
+ */
+export type HookEventName = "on_agent_start" | "on_agent_end" | "on_turn_start" | "on_turn_end" | "on_tool_start" | "on_tool_end" | "on_permission_check" | "on_session_start" | "on_session_end" | "pre_tool_use" | "post_tool_use" | "user_prompt_submit" | "pre_compact" | "post_compact" | "file_changed" | "notification";
+export interface HookContext {
+    eventName: HookEventName;
+    data: Record<string, unknown>;
+    sessionId?: string;
+    turnNumber?: number;
+}
+export interface HookResult {
+    /** If true, stop the hook chain */
+    stop?: boolean;
+    /** Modified data to pass along */
+    data?: Record<string, unknown>;
+    /** Additional messages to inject */
+    messages?: string[];
+    /** Allow/deny/ask override for permission hooks */
+    decision?: "allow" | "deny" | "ask";
+    /**
+     * For pre_tool_use: replace the tool's args before execution. Used by
+     * "sanitizer" handlers (e.g. redact secrets in Bash commands, normalize
+     * file paths, inject a default flag). Last handler in the chain wins.
+     * Args are re-validated against the tool's input schema before the
+     * tool runs, so a malformed updatedInput still surfaces as an
+     * "Invalid input" error rather than silently passing through.
+     */
+    updatedInput?: Record<string, unknown>;
+    /**
+     * For post_tool_use: text appended to the tool's content (visible to
+     * the model on the next LLM call). Used by linter/typecheck handlers
+     * to surface results without re-running the tool. Multiple handlers'
+     * additionalContext entries are joined with two newlines.
+     */
+    additionalContext?: string;
+    /**
+     * For user_prompt_submit: replace the most recent user message text
+     * with this string. Last handler wins. Used to auto-prepend project
+     * context, mask secrets, or rewrite shorthand prompts. The original
+     * prompt is logged at info level for audit purposes.
+     */
+    updatedPrompt?: string;
+}

package/dist/hooks/events.js

@@ -0,0 +1,4 @@
+/**
+ * Hook event type definitions.
+ */
+export {};

package/dist/hooks/inject.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Hook message injection helper.
+ *
+ * Handlers return raw markdown strings via HookResult.messages. The emit
+ * site uses wrapHookMessages() to package them into a single user-role
+ * <system-reminder> Message so the model sees them as one block instead
+ * of a noisy sequence of separate user turns.
+ *
+ * Contract:
+ *   - Handlers do NOT wrap their own <system-reminder>; emit-site owns the
+ *     wrapper. Keeps formatting consistent and lets us evolve it (e.g. add
+ *     a trailing close-tag, tag attributes) without touching every handler.
+ *   - Empty / whitespace-only messages are dropped before wrapping; if
+ *     nothing remains, returns null (caller skips the injection).
+ *   - Multiple handlers' messages are joined with a blank line between
+ *     blocks so each is visually distinct inside the reminder.
+ */
+import type { Message } from "../types.js";
+export declare function wrapHookMessages(messages: string[] | undefined): Message | null;

package/dist/hooks/inject.js

@@ -0,0 +1,29 @@
+/**
+ * Hook message injection helper.
+ *
+ * Handlers return raw markdown strings via HookResult.messages. The emit
+ * site uses wrapHookMessages() to package them into a single user-role
+ * <system-reminder> Message so the model sees them as one block instead
+ * of a noisy sequence of separate user turns.
+ *
+ * Contract:
+ *   - Handlers do NOT wrap their own <system-reminder>; emit-site owns the
+ *     wrapper. Keeps formatting consistent and lets us evolve it (e.g. add
+ *     a trailing close-tag, tag attributes) without touching every handler.
+ *   - Empty / whitespace-only messages are dropped before wrapping; if
+ *     nothing remains, returns null (caller skips the injection).
+ *   - Multiple handlers' messages are joined with a blank line between
+ *     blocks so each is visually distinct inside the reminder.
+ */
+export function wrapHookMessages(messages) {
+    if (!messages?.length)
+        return null;
+    const cleaned = messages.map((m) => m.trim()).filter((m) => m.length > 0);
+    if (cleaned.length === 0)
+        return null;
+    const body = cleaned.join("\n\n");
+    return {
+        role: "user",
+        content: `<system-reminder>\n${body}\n</system-reminder>`,
+    };
+}

package/dist/hooks/registry.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Hook registry with priority-based chain-of-responsibility execution.
+ */
+import type { HookEventName, HookContext, HookResult } from "./events.js";
+export type HookHandler = (ctx: HookContext) => HookResult | Promise<HookResult>;
+export declare class HookRegistry {
+    private hooks;
+    register(eventName: HookEventName, handler: HookHandler, priority?: number, name?: string): void;
+    emit(eventName: HookEventName, data?: Record<string, unknown>): Promise<HookResult>;
+    hasHooks(eventName: HookEventName): boolean;
+    clear(eventName?: HookEventName): void;
+    listHooks(): Map<HookEventName, string[]>;
+    listEvents(): HookEventName[];
+    countHandlers(eventName: HookEventName): number;
+}