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

package/dist/hooks/registry.js

@@ -0,0 +1,84 @@
+/**
+ * Hook registry with priority-based chain-of-responsibility execution.
+ */
+export class HookRegistry {
+    hooks = new Map();
+    register(eventName, handler, priority = 0, name) {
+        if (!this.hooks.has(eventName)) {
+            this.hooks.set(eventName, []);
+        }
+        this.hooks.get(eventName).push({ handler, priority, name });
+        // Sort by priority descending (highest first)
+        this.hooks.get(eventName).sort((a, b) => b.priority - a.priority);
+    }
+    async emit(eventName, data = {}) {
+        const handlers = this.hooks.get(eventName);
+        if (!handlers?.length)
+            return {};
+        const ctx = { eventName, data: { ...data } };
+        let aggregated = {};
+        for (const { handler } of handlers) {
+            try {
+                const result = await handler(ctx);
+                if (result.data) {
+                    ctx.data = { ...ctx.data, ...result.data };
+                    aggregated.data = { ...aggregated.data, ...result.data };
+                }
+                if (result.messages) {
+                    aggregated.messages = [...(aggregated.messages ?? []), ...result.messages];
+                }
+                if (result.decision) {
+                    aggregated.decision = result.decision;
+                }
+                // Last-write-wins for input/prompt rewrites — the priority order
+                // already determined which handler "owns" the override.
+                if (result.updatedInput !== undefined) {
+                    aggregated.updatedInput = result.updatedInput;
+                }
+                if (result.updatedPrompt !== undefined) {
+                    aggregated.updatedPrompt = result.updatedPrompt;
+                }
+                // additionalContext is appended (multiple handlers' contributions
+                // are visible to the model with blank-line separators).
+                if (result.additionalContext !== undefined) {
+                    aggregated.additionalContext = aggregated.additionalContext
+                        ? `${aggregated.additionalContext}\n\n${result.additionalContext}`
+                        : result.additionalContext;
+                }
+                if (result.stop) {
+                    aggregated.stop = true;
+                    break;
+                }
+            }
+            catch (err) {
+                // Hook errors should not crash the main loop
+                console.error(`Hook error in ${eventName}:`, err);
+            }
+        }
+        return aggregated;
+    }
+    hasHooks(eventName) {
+        return (this.hooks.get(eventName)?.length ?? 0) > 0;
+    }
+    clear(eventName) {
+        if (eventName) {
+            this.hooks.delete(eventName);
+        }
+        else {
+            this.hooks.clear();
+        }
+    }
+    listHooks() {
+        const result = new Map();
+        for (const [name, handlers] of this.hooks) {
+            result.set(name, handlers.map((h) => h.name ?? "(anonymous)"));
+        }
+        return result;
+    }
+    listEvents() {
+        return [...this.hooks.keys()];
+    }
+    countHandlers(eventName) {
+        return this.hooks.get(eventName)?.length ?? 0;
+    }
+}

package/dist/hooks/shell-runner.d.ts

@@ -0,0 +1,45 @@
+/**
+ * shell-runner — execute a user-configured shell command as a hook handler.
+ *
+ * Protocol (matches Claude Code's shell-hook contract):
+ *
+ *   stdin       JSON.stringify({ eventName, data }) — the full HookContext
+ *               envelope, including ctx.data fields like toolName / args /
+ *               sessionId / isSubAgent.
+ *
+ *   stdout      Either ignored (when exit 0 with no/blank output) or parsed
+ *               as a HookResult JSON document. Unparseable stdout on exit 0
+ *               is logged at warn level and dropped — we do NOT crash the
+ *               turn loop on malformed handler output.
+ *
+ *   exit  0     Normal return. Stdout (if any) becomes the HookResult.
+ *   exit  2     Deny / block. Stderr becomes the human-readable reason and
+ *               is surfaced to the model via HookResult.messages so the LLM
+ *               sees why the action was rejected.
+ *   exit  *     Any other non-zero code = handler error. Logged at error
+ *               level; we return {} (no effect) so a buggy hook never wedges
+ *               the engine.
+ *
+ *   ENV (passed to child):
+ *               CODESHELL_HOOK_EVENT   — event name, also in stdin
+ *               CODESHELL_HOOK_CWD     — repo root for context-aware hooks
+ *               (callers may add more by reading process.env directly)
+ *
+ *   timeout     Defaults to 60_000 ms; settings.timeout_ms overrides.
+ *               On timeout we SIGTERM then SIGKILL, log, and return {}.
+ */
+import type { HookContext, HookResult } from "./events.js";
+import type { SettingsHookConfig } from "../types.js";
+/**
+ * Run one shell-hook command and return the parsed HookResult. Catches
+ * every failure mode (spawn error, timeout, malformed JSON) and
+ * returns an empty result so the registry's chain keeps going.
+ */
+export declare function runShellHook(config: SettingsHookConfig, ctx: HookContext): Promise<HookResult>;
+/**
+ * Check whether the hook should fire for the current ctx, respecting
+ * the optional `matcher` regex. Returns false for non-tool events
+ * when matcher is set (matcher only makes sense when ctx.data has a
+ * toolName field).
+ */
+export declare function shellHookMatches(config: SettingsHookConfig, ctx: HookContext): boolean;

package/dist/hooks/shell-runner.js

@@ -0,0 +1,173 @@
+/**
+ * shell-runner — execute a user-configured shell command as a hook handler.
+ *
+ * Protocol (matches Claude Code's shell-hook contract):
+ *
+ *   stdin       JSON.stringify({ eventName, data }) — the full HookContext
+ *               envelope, including ctx.data fields like toolName / args /
+ *               sessionId / isSubAgent.
+ *
+ *   stdout      Either ignored (when exit 0 with no/blank output) or parsed
+ *               as a HookResult JSON document. Unparseable stdout on exit 0
+ *               is logged at warn level and dropped — we do NOT crash the
+ *               turn loop on malformed handler output.
+ *
+ *   exit  0     Normal return. Stdout (if any) becomes the HookResult.
+ *   exit  2     Deny / block. Stderr becomes the human-readable reason and
+ *               is surfaced to the model via HookResult.messages so the LLM
+ *               sees why the action was rejected.
+ *   exit  *     Any other non-zero code = handler error. Logged at error
+ *               level; we return {} (no effect) so a buggy hook never wedges
+ *               the engine.
+ *
+ *   ENV (passed to child):
+ *               CODESHELL_HOOK_EVENT   — event name, also in stdin
+ *               CODESHELL_HOOK_CWD     — repo root for context-aware hooks
+ *               (callers may add more by reading process.env directly)
+ *
+ *   timeout     Defaults to 60_000 ms; settings.timeout_ms overrides.
+ *               On timeout we SIGTERM then SIGKILL, log, and return {}.
+ */
+import { spawn } from "node:child_process";
+const DEFAULT_TIMEOUT_MS = 60_000;
+/**
+ * Run one shell-hook command and return the parsed HookResult. Catches
+ * every failure mode (spawn error, timeout, malformed JSON) and
+ * returns an empty result so the registry's chain keeps going.
+ */
+export async function runShellHook(config, ctx) {
+    const timeoutMs = config.timeout_ms ?? DEFAULT_TIMEOUT_MS;
+    return new Promise((resolve) => {
+        let child;
+        try {
+            child = spawn(config.command, [], {
+                shell: true,
+                cwd: config.cwd,
+                env: {
+                    ...process.env,
+                    CODESHELL_HOOK_EVENT: ctx.eventName,
+                    CODESHELL_HOOK_CWD: config.cwd ?? process.cwd(),
+                },
+            });
+        }
+        catch (err) {
+            // eslint-disable-next-line no-console
+            console.error(`[hooks] spawn failed for ${config.event} command "${config.command}":`, err.message);
+            resolve({});
+            return;
+        }
+        let stdout = "";
+        let stderr = "";
+        let settled = false;
+        const settle = (value) => {
+            if (settled)
+                return;
+            settled = true;
+            resolve(value);
+        };
+        const timer = setTimeout(() => {
+            // eslint-disable-next-line no-console
+            console.warn(`[hooks] ${config.event} hook timed out after ${timeoutMs}ms: ${config.command}`);
+            try {
+                child.kill("SIGTERM");
+                // SIGKILL fallback if the process ignores SIGTERM. Short delay so
+                // a graceful-shutdown handler in the child has a moment to flush.
+                setTimeout(() => {
+                    try {
+                        child.kill("SIGKILL");
+                    }
+                    catch {
+                        /* already exited */
+                    }
+                }, 1000);
+            }
+            catch {
+                /* already exited */
+            }
+            settle({});
+        }, timeoutMs);
+        child.stdout?.on("data", (chunk) => {
+            stdout += chunk.toString("utf8");
+        });
+        child.stderr?.on("data", (chunk) => {
+            stderr += chunk.toString("utf8");
+        });
+        child.on("error", (err) => {
+            clearTimeout(timer);
+            // eslint-disable-next-line no-console
+            console.error(`[hooks] ${config.event} hook failed: ${config.command}`, err.message);
+            settle({});
+        });
+        child.on("close", (code) => {
+            clearTimeout(timer);
+            if (code === 0) {
+                const trimmed = stdout.trim();
+                if (trimmed.length === 0) {
+                    settle({});
+                    return;
+                }
+                try {
+                    const parsed = JSON.parse(trimmed);
+                    if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) {
+                        settle(parsed);
+                    }
+                    else {
+                        settle({});
+                    }
+                }
+                catch (err) {
+                    // eslint-disable-next-line no-console
+                    console.warn(`[hooks] ${config.event} hook returned malformed JSON, ignoring:`, err.message, "\nstdout:", trimmed.slice(0, 200));
+                    settle({});
+                }
+                return;
+            }
+            if (code === 2) {
+                const reason = stderr.trim() || "denied (exit 2)";
+                settle({
+                    decision: "deny",
+                    messages: [reason],
+                });
+                return;
+            }
+            // Other non-zero codes: handler error. Log and treat as no-op so
+            // the chain continues. Per CC: stderr is surfaced to the user but
+            // doesn't block execution.
+            // eslint-disable-next-line no-console
+            console.error(`[hooks] ${config.event} hook exited with code ${code}:`, stderr.slice(0, 500));
+            settle({});
+        });
+        // Write the context envelope on stdin then close.
+        try {
+            child.stdin?.write(JSON.stringify({ eventName: ctx.eventName, data: ctx.data }));
+            child.stdin?.end();
+        }
+        catch (err) {
+            // eslint-disable-next-line no-console
+            console.error(`[hooks] failed to write stdin for ${config.event}:`, err.message);
+            settle({});
+        }
+    });
+}
+/**
+ * Check whether the hook should fire for the current ctx, respecting
+ * the optional `matcher` regex. Returns false for non-tool events
+ * when matcher is set (matcher only makes sense when ctx.data has a
+ * toolName field).
+ */
+export function shellHookMatches(config, ctx) {
+    if (!config.matcher)
+        return true;
+    const toolName = ctx.data.toolName;
+    if (typeof toolName !== "string")
+        return false;
+    try {
+        return new RegExp(config.matcher).test(toolName);
+    }
+    catch {
+        // Bad regex in user config — log once, treat as non-matching.
+        // eslint-disable-next-line no-console
+        console.warn(`[hooks] invalid matcher "${config.matcher}" for ${config.event}; skipping`);
+        return false;
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1,117 @@
+/**
+ * code-shell — general-purpose agent orchestration framework
+ *
+ * Public API exports.
+ */
+export declare const VERSION = "0.5.0-rc.0";
+export type { Message, ContentBlock, ToolDefinition, ToolCall, ToolResult, RegisteredTool, TranscriptEvent, TranscriptEventType, SessionState, SessionStatus, TokenUsage, CompiledInput, PermissionDecision, PermissionMode, PermissionRule, TurnPhase, TurnResult, TerminalReason, StreamEvent, StreamCallback, LLMConfig, LLMResponse, Settings, MCPServerConfig, } from "./types.js";
+export { FrameworkError, LLMError, LLMRateLimitError, ContextLimitError, ToolError, ToolNotFoundError, ToolExecutionError, ToolTimeoutError, PermissionDeniedError, SessionError, TranscriptError, ConfigError, SandboxUnavailableError, } from "./exceptions.js";
+export { Engine } from "./engine/engine.js";
+export type { EngineConfig, EngineHookConfig, EngineResult } from "./engine/engine.js";
+export type { CostStateStore, CostStateSnapshot } from "./engine/cost-store.js";
+export { EngineRuntime } from "./engine/runtime.js";
+export type { EngineRuntimeOptions } from "./engine/runtime.js";
+export { ChatSessionManager } from "./protocol/chat-session-manager.js";
+export type { ChatSessionManagerOptions } from "./protocol/chat-session-manager.js";
+export { LLMClientBase } from "./llm/client-base.js";
+export { createLLMClient, registerProvider } from "./llm/client-factory.js";
+export { AnthropicClient } from "./llm/providers/anthropic.js";
+export { OpenAIClient } from "./llm/providers/openai.js";
+export { ModelPool, type ModelEntry } from "./llm/model-pool.js";
+export { ToolRegistry } from "./tool-system/registry.js";
+export { ToolExecutor } from "./tool-system/executor.js";
+export { PermissionClassifier, HeadlessApprovalBackend, AutoApprovalBackend } from "./tool-system/permission.js";
+export type { ApprovalBackend } from "./tool-system/permission.js";
+export { BUILTIN_TOOLS } from "./tool-system/builtin/index.js";
+export { MCPManager } from "./tool-system/mcp-manager.js";
+export type { AskUserFn } from "./tool-system/builtin/ask-user.js";
+export type { Task, TaskStatus } from "./tool-system/builtin/task.js";
+export { HookRegistry } from "./hooks/registry.js";
+export type { HookEventName, HookContext, HookResult } from "./hooks/events.js";
+export { wrapHookMessages } from "./hooks/inject.js";
+export { AgentServer, type AgentServerOptions } from "./protocol/server.js";
+export { AgentClient, type BackgroundAgentCompletedHandler } from "./protocol/client.js";
+export { createInProcessTransport, StdioTransport, type Transport, } from "./protocol/transport.js";
+export { createServer, createClient, type CreateServerOptions, type CreateClientOptions, type ServerHandle, } from "./protocol/factories.js";
+export { Methods, ErrorCodes, type RpcMessage, type RunResult, } from "./protocol/types.js";
+export { Transcript } from "./session/transcript.js";
+export { SessionManager } from "./session/session-manager.js";
+export { FileHistory } from "./session/file-history.js";
+export { MemoryManager } from "./session/memory.js";
+export type { MemoryEntry } from "./session/memory.js";
+export type { FileSnapshot } from "./session/file-history.js";
+export { PromptComposer } from "./prompt/composer.js";
+export { SectionCache } from "./prompt/section-cache.js";
+export { scanInstructions, combineInstructions } from "./prompt/instruction-scanner.js";
+export { BUILTIN_AGENT_PRESETS, DEFAULT_AGENT_PRESET, DEFAULT_CLI_PRESET, resolveAgentPreset, resolveBuiltinToolNames, buildPresetSystemPrompt, registerPreset, listPresetNames, } from "./preset/index.js";
+export type { AgentPreset, AgentPresetName } from "./preset/index.js";
+export { loadSection, loadSections, availableSections, registerSection } from "./prompt/section-loader.js";
+export { ContextManager } from "./context/manager.js";
+export { estimateTokens, microcompact, windowCompact, truncateToolResult, buildSummarizationPrompt, applySummaryCompaction, COMPACTABLE_TOOL_NAMES, } from "./context/compaction.js";
+export type { MicrocompactOptions } from "./context/compaction.js";
+export type { SummarizeFn, CompactStrategy, OnCompactFn, ContextManagerConfig, } from "./context/manager.js";
+export { applyToolResultPersistence, createContentReplacementState, reconstructContentReplacementState, resolveToolResultsDir, isPersistedReplacement, DEFAULT_PERSIST_THRESHOLD, PER_MESSAGE_AGGREGATE_CAP, PREVIEW_SIZE, } from "./context/tool-result-storage.js";
+export type { ContentReplacementState } from "./context/tool-result-storage.js";
+export { scanSkills, invalidateSkillCache } from "./skills/index.js";
+export type { SkillDefinition } from "./skills/index.js";
+export { Arena } from "./arena/arena.js";
+export { MODEL_PRESETS, getMaxOutputTokens } from "./arena/model-presets.js";
+export type { ModelPreset } from "./arena/model-presets.js";
+export { detectArenaMode } from "./arena/detect-mode.js";
+export { getStrategy, getStrategyForPlan, ReviewStrategy, DiscussionStrategy, PlanningStrategy } from "./arena/strategies/index.js";
+export { planArena } from "./arena/planner.js";
+export { collectEvidence } from "./arena/providers/index.js";
+export { selectTools, hasTools } from "./arena/tools/selector.js";
+export { ArenaLedger } from "./arena/ledger.js";
+export { registerClaims, selectClaimsForReview } from "./arena/phases/claim-registry.js";
+export { buildDigest, formatDigest } from "./arena/digest-builder.js";
+export { transitionClaim, resolveClaimStatus, markUnderReview, applyReviewResult, markUnresolved, isTerminal, validTransitions } from "./arena/transitions.js";
+export type { ArenaConfig, ArenaMode, ArenaResultV2, ArenaStrategy, ArenaParticipant, ArenaBaseContext, ArenaFinding, FindingReview, ParticipantReport, ArenaConsensus, ArenaConsensusItem, ArenaRoadmapPhase, ArenaProgressEvent, ArenaPlan, ArenaLens, ArenaLensName, ArenaSourceKind, ArenaArtifact, ArenaQuickFact, FindingKind, PeerVerdict, ToolTrace, EvidencePacket, FindingEvidenceLink, ResearchDossier, ClaimStatus, ClaimRecord, ClaimChallenge, ClaimAdjudication, RequestedCheck, DebateRound, DebateTurn, TargetedCheckTask, SharedResearchLedger, RoundResearchDigest, ArenaExecutionLimits, } from "./arena/types.js";
+export { IterativeArena, defaultIterateConvergence, iterateDiffRatio, iterateCodeFormat, iterateDocumentFormat, getIterateFormat, } from "./arena/index.js";
+export type { IterateConfig, IterateResult, IterateSubject, IterateFormat, IterateProgressEvent, IterateFormatPack, Draft, DraftCandidate, Critique, CritiqueCategory, CritiqueEvidence, CritiqueSeverity, ConvergenceSignal, Round, AuthorRotation, StoppedReason, CheckpointFn, CheckpointContext, CheckpointAction, } from "./arena/index.js";
+export { RunManager, type RunManagerConfig, type RunStore, FileRunStore, RunQueue, EngineRunner, type EngineRunnerConfig, type RunExecutionHandle, type RunExecutor, type CustomToolEntry, RunApprovalBackend, createRunAskUserFn, type RunLifecycleHooks, CheckpointWriter, ArtifactTracker, RunLock, Heartbeat, NoopEvaluator, CompositeEvaluator, type Evaluator, type EvaluatorResult, type EvaluatorContext, type RunStatus, type RunSnapshot, type RunEvent, type RunCheckpoint, type RunApproval, type RunArtifactRef, type SubmitRunInput, type ResumeRunInput, type ListRunsQuery, type RunStreamEvent, type RunStreamCallback, type DetachFn, VALID_TRANSITIONS, createRunManager, type CreateRunManagerOptions, } from "./run/index.js";
+export { defineProduct, type ProductDefinition, type ProductPreset, type ProductAdapter, type ProductContract, type CustomTool, type ProductRuntimeOptions, type ProductInstance, } from "./product/index.js";
+export { logger } from "./logging/logger.js";
+export { SettingsManager } from "./settings/manager.js";
+export { SettingsSchema, validateSettings } from "./settings/schema.js";
+export { getSessionId, switchSession, getOriginalCwd, setOriginalCwd, getProjectRoot, setProjectRoot, getCwdState, getIsInteractive, updateLastInteractionTime, flushInteractionTime, markScrollActivity, type AttributedCounter, type ChannelEntry, } from "./state.js";
+export { getGraphemeSegmenter, firstGrapheme, lastGrapheme, getWordSegmenter, getRelativeTimeFormat, getTimeZone, getSystemLocaleLanguage, } from "./utils/intl.js";
+export { env } from "./utils/env.js";
+export { default as sliceAnsi } from "./utils/sliceAnsi.js";
+export { execFileNoThrow } from "./utils/execFileNoThrow.js";
+export { gte } from "./utils/semver.js";
+export { logForDebugging } from "./utils/debug.js";
+export { isEnvTruthy, isEnvDefinedFalsy, getClaudeConfigHomeDir, isBareMode, parseEnvVars, shouldMaintainProjectWorkingDir, isRunningOnHomespace, getAWSRegion, getDefaultVertexRegion, getVertexRegionForModel, isInProtectedNamespace, } from "./utils/envUtils.js";
+export { startCapturingEarlyInput, stopCapturingEarlyInput, consumeEarlyInput, hasEarlyInput, seedEarlyInput, isCapturingEarlyInput, } from "./utils/earlyInput.js";
+export { formatBytes, formatToolArgs, singleLine, MAX_LINE_WIDTH, TOOL_DOT_COLORS, } from "./utils/toolDisplay.js";
+export { formatDuration, formatTokens } from "./utils/format.js";
+export { getTheme, type Theme, type ThemeName, type ThemeSetting, } from "./utils/theme.js";
+export { resolveThemeSetting, type SystemTheme } from "./utils/systemTheme.js";
+export { rotateLogs } from "./logging/logger.js";
+export { recordUIEvent } from "./logging/session-recorder.js";
+export { CostTracker, costTracker, installCostTracking } from "./cost-tracker.js";
+export { NOOP_COLORIZER, type Colorizer } from "./colorizer.js";
+export { hasApiKey, resolveApiKey, appendOnboardingResult, detectEnvKeys, saveArenaSettingsByKeys, type OnboardingResult, } from "./onboarding.js";
+export { getCurrentVersion, checkForUpdate, scheduleAutoInstallOnExit, getUpdateAvailable, getAutoUpdateDisabledReason, type UpdateInfo, } from "./updater.js";
+export { isGitRepo, getCurrentBranch, getGitStatus, getGitDiff, getGitDiffStat, getGitLog, gitAdd, gitCommit, gitListBranches, gitCheckout, ghAvailable, ghPrComments, } from "./git/utils.js";
+export { getInteractiveApprovalBackend } from "./tool-system/permission.js";
+export { defaultSandboxConfig, type SandboxConfig, } from "./tool-system/sandbox/index.js";
+export { buildNotificationMessage, buildNotificationSummary, notificationQueue, agentNotificationBus, notificationItemToStreamEvent, } from "./tool-system/builtin/agent-notifications.js";
+export type { BackgroundAgentCompletedEvent } from "./types.js";
+export { asyncAgentRegistry, type AsyncAgentEntry, } from "./tool-system/builtin/agent-registry.js";
+export { createInProcessClient } from "./protocol/helpers.js";
+export type { ProtocolModelEntry } from "./protocol/types.js";
+export { formatArenaResult, printArenaResult, renderProgress, createProgressRenderer, type OutputSink, } from "./arena/render/terminal.js";
+export { formatArenaResultForSession } from "./arena/render/session.js";
+export { installPlugin, uninstallPlugin, listInstalled, } from "./plugins/pluginInstaller.js";
+export { addMarketplace, removeMarketplace, listMarketplaces, } from "./plugins/marketplaceManager.js";
+export { parseMarketplaceInput, deriveMarketplaceName, } from "./plugins/parseMarketplaceInput.js";
+export { scanPluginCommands, type PluginCommand, } from "./plugins/pluginCommandsLoader.js";
+export { type CachedModel, defaultCacheDir, } from "./llm/model-cache.js";
+export { fetchModelList, type FetchResult, } from "./llm/model-fetcher.js";
+export { sanitizeApiKey, hasNonAsciiPrintable, } from "./llm/api-key-sanitize.js";
+export { PROVIDER_KINDS, type ProviderKindName, } from "./llm/provider-kinds.js";
+export { capabilitiesFor, type Capability, } from "./llm/capabilities/index.js";
+export { type ProviderConfig } from "./llm/provider-catalog.js";
+export { syncOpenRouterCatalog, getOpenRouterSnapshot, } from "./data/openrouter-sync.js";
+export type { ApprovalRequest, ApprovalResult, ApprovalScope, TaskInfo, } from "./types.js";

package/dist/index.js

@@ -0,0 +1,145 @@
+/**
+ * code-shell — general-purpose agent orchestration framework
+ *
+ * Public API exports.
+ */
+export const VERSION = "0.5.0-rc.0";
+// ─── Exceptions ──────────────────────────────────────────────────
+export { FrameworkError, LLMError, LLMRateLimitError, ContextLimitError, ToolError, ToolNotFoundError, ToolExecutionError, ToolTimeoutError, PermissionDeniedError, SessionError, TranscriptError, ConfigError, SandboxUnavailableError, } from "./exceptions.js";
+// ─── Engine (primary API) ────────────────────────────────────────
+export { Engine } from "./engine/engine.js";
+export { EngineRuntime } from "./engine/runtime.js";
+export { ChatSessionManager } from "./protocol/chat-session-manager.js";
+// ─── LLM ─────────────────────────────────────────────────────────
+export { LLMClientBase } from "./llm/client-base.js";
+export { createLLMClient, registerProvider } from "./llm/client-factory.js";
+export { AnthropicClient } from "./llm/providers/anthropic.js";
+export { OpenAIClient } from "./llm/providers/openai.js";
+export { ModelPool } from "./llm/model-pool.js";
+// ─── Tools ───────────────────────────────────────────────────────
+export { ToolRegistry } from "./tool-system/registry.js";
+export { ToolExecutor } from "./tool-system/executor.js";
+export { PermissionClassifier, HeadlessApprovalBackend, AutoApprovalBackend } from "./tool-system/permission.js";
+export { BUILTIN_TOOLS } from "./tool-system/builtin/index.js";
+export { MCPManager } from "./tool-system/mcp-manager.js";
+// ─── Hooks ───────────────────────────────────────────────────────
+export { HookRegistry } from "./hooks/registry.js";
+export { wrapHookMessages } from "./hooks/inject.js";
+// ─── Protocol (client/server + transports) ──────────────────────
+export { AgentServer } from "./protocol/server.js";
+export { AgentClient } from "./protocol/client.js";
+export { createInProcessTransport, StdioTransport, } from "./protocol/transport.js";
+// Recommended public factories — see protocol/factories.ts for the
+// stable construction contract referenced by standard §7.
+export { createServer, createClient, } from "./protocol/factories.js";
+export { Methods, ErrorCodes, } from "./protocol/types.js";
+// ─── Session ─────────────────────────────────────────────────────
+export { Transcript } from "./session/transcript.js";
+export { SessionManager } from "./session/session-manager.js";
+export { FileHistory } from "./session/file-history.js";
+export { MemoryManager } from "./session/memory.js";
+// ─── Prompt ──────────────────────────────────────────────────────
+export { PromptComposer } from "./prompt/composer.js";
+export { SectionCache } from "./prompt/section-cache.js";
+export { scanInstructions, combineInstructions } from "./prompt/instruction-scanner.js";
+// ─── Presets ─────────────────────────────────────────────────────
+export { BUILTIN_AGENT_PRESETS, DEFAULT_AGENT_PRESET, DEFAULT_CLI_PRESET, resolveAgentPreset, resolveBuiltinToolNames, buildPresetSystemPrompt, registerPreset, listPresetNames, } from "./preset/index.js";
+export { loadSection, loadSections, availableSections, registerSection } from "./prompt/section-loader.js";
+// ─── Context ─────────────────────────────────────────────────────
+export { ContextManager } from "./context/manager.js";
+export { estimateTokens, microcompact, windowCompact, truncateToolResult, buildSummarizationPrompt, applySummaryCompaction, COMPACTABLE_TOOL_NAMES, } from "./context/compaction.js";
+export { applyToolResultPersistence, createContentReplacementState, reconstructContentReplacementState, resolveToolResultsDir, isPersistedReplacement, DEFAULT_PERSIST_THRESHOLD, PER_MESSAGE_AGGREGATE_CAP, PREVIEW_SIZE, } from "./context/tool-result-storage.js";
+// ─── Skills ──────────────────────────────────────────────────────
+export { scanSkills, invalidateSkillCache } from "./skills/index.js";
+// ─── Arena ───────────────────────────────────────────────────────
+export { Arena } from "./arena/arena.js";
+export { MODEL_PRESETS, getMaxOutputTokens } from "./arena/model-presets.js";
+export { detectArenaMode } from "./arena/detect-mode.js";
+export { getStrategy, getStrategyForPlan, ReviewStrategy, DiscussionStrategy, PlanningStrategy } from "./arena/strategies/index.js";
+export { planArena } from "./arena/planner.js";
+export { collectEvidence } from "./arena/providers/index.js";
+export { selectTools, hasTools } from "./arena/tools/selector.js";
+export { ArenaLedger } from "./arena/ledger.js";
+export { registerClaims, selectClaimsForReview } from "./arena/phases/claim-registry.js";
+export { buildDigest, formatDigest } from "./arena/digest-builder.js";
+export { transitionClaim, resolveClaimStatus, markUnderReview, applyReviewResult, markUnresolved, isTerminal, validTransitions } from "./arena/transitions.js";
+// ─── Arena: Iterate mode ────────────────────────────────────────
+// Multi-model authoring loop (tournament v1 → critique-revise rounds).
+// Use IterativeArena to produce a draft from scratch (code, PRD, design doc);
+// use Arena (above) to review an existing artifact.
+export { IterativeArena, defaultIterateConvergence, iterateDiffRatio, iterateCodeFormat, iterateDocumentFormat, getIterateFormat, } from "./arena/index.js";
+// ─── Run (Managed Agent Lifecycle) ──────────────────────────────
+export { 
+// Manager
+RunManager, FileRunStore, 
+// Queue
+RunQueue, 
+// Runner
+EngineRunner, 
+// Approval / Input adapters
+RunApprovalBackend, createRunAskUserFn, 
+// Checkpoint & Artifacts
+CheckpointWriter, ArtifactTracker, 
+// Hardening
+RunLock, Heartbeat, 
+// Evaluator
+NoopEvaluator, CompositeEvaluator, VALID_TRANSITIONS, 
+// Factory
+createRunManager, } from "./run/index.js";
+// ─── Product (Domain-Specific Agents) ────────────────────────────
+export { defineProduct, } from "./product/index.js";
+// ─── Logging ─────────────────────────────────────────────────────
+export { logger } from "./logging/logger.js";
+// ─── Settings ────────────────────────────────────────────────────
+export { SettingsManager } from "./settings/manager.js";
+export { SettingsSchema, validateSettings } from "./settings/schema.js";
+// ─── State (runtime singletons shared with TUI) ──────────────────
+export { getSessionId, switchSession, getOriginalCwd, setOriginalCwd, getProjectRoot, setProjectRoot, getCwdState, getIsInteractive, updateLastInteractionTime, flushInteractionTime, markScrollActivity, } from "./state.js";
+// ─── Utils (shared primitives used by TUI) ───────────────────────
+export { getGraphemeSegmenter, firstGrapheme, lastGrapheme, getWordSegmenter, getRelativeTimeFormat, getTimeZone, getSystemLocaleLanguage, } from "./utils/intl.js";
+export { env } from "./utils/env.js";
+export { default as sliceAnsi } from "./utils/sliceAnsi.js";
+export { execFileNoThrow } from "./utils/execFileNoThrow.js";
+export { gte } from "./utils/semver.js";
+export { logForDebugging } from "./utils/debug.js";
+export { isEnvTruthy, isEnvDefinedFalsy, getClaudeConfigHomeDir, isBareMode, parseEnvVars, shouldMaintainProjectWorkingDir, isRunningOnHomespace, getAWSRegion, getDefaultVertexRegion, getVertexRegionForModel, isInProtectedNamespace, } from "./utils/envUtils.js";
+export { startCapturingEarlyInput, stopCapturingEarlyInput, consumeEarlyInput, hasEarlyInput, seedEarlyInput, isCapturingEarlyInput, } from "./utils/earlyInput.js";
+export { formatBytes, formatToolArgs, singleLine, MAX_LINE_WIDTH, TOOL_DOT_COLORS, } from "./utils/toolDisplay.js";
+export { formatDuration, formatTokens } from "./utils/format.js";
+export { getTheme, } from "./utils/theme.js";
+export { resolveThemeSetting } from "./utils/systemTheme.js";
+// ─── Logging (extended) ──────────────────────────────────────────
+export { rotateLogs } from "./logging/logger.js";
+export { recordUIEvent } from "./logging/session-recorder.js";
+// ─── Cost Tracker ────────────────────────────────────────────────
+export { CostTracker, costTracker, installCostTracking } from "./cost-tracker.js";
+export { NOOP_COLORIZER } from "./colorizer.js";
+// ─── Onboarding ──────────────────────────────────────────────────
+export { hasApiKey, resolveApiKey, appendOnboardingResult, detectEnvKeys, saveArenaSettingsByKeys, } from "./onboarding.js";
+// ─── Updater ─────────────────────────────────────────────────────
+export { getCurrentVersion, checkForUpdate, scheduleAutoInstallOnExit, getUpdateAvailable, getAutoUpdateDisabledReason, } from "./updater.js";
+// ─── Git Utilities ───────────────────────────────────────────────
+export { isGitRepo, getCurrentBranch, getGitStatus, getGitDiff, getGitDiffStat, getGitLog, gitAdd, gitCommit, gitListBranches, gitCheckout, ghAvailable, ghPrComments, } from "./git/utils.js";
+// ─── Tool-system (extended for TUI) ─────────────────────────────
+export { getInteractiveApprovalBackend } from "./tool-system/permission.js";
+export { defaultSandboxConfig, } from "./tool-system/sandbox/index.js";
+export { buildNotificationMessage, buildNotificationSummary, notificationQueue, agentNotificationBus, notificationItemToStreamEvent, } from "./tool-system/builtin/agent-notifications.js";
+export { asyncAgentRegistry, } from "./tool-system/builtin/agent-registry.js";
+// ─── Protocol (extended for TUI) ────────────────────────────────
+export { createInProcessClient } from "./protocol/helpers.js";
+// ─── Arena (extended for TUI) ───────────────────────────────────
+export { formatArenaResult, printArenaResult, renderProgress, createProgressRenderer, } from "./arena/render/terminal.js";
+export { formatArenaResultForSession } from "./arena/render/session.js";
+// ─── Plugins ─────────────────────────────────────────────────────
+export { installPlugin, uninstallPlugin, listInstalled, } from "./plugins/pluginInstaller.js";
+export { addMarketplace, removeMarketplace, listMarketplaces, } from "./plugins/marketplaceManager.js";
+export { parseMarketplaceInput, deriveMarketplaceName, } from "./plugins/parseMarketplaceInput.js";
+export { scanPluginCommands, } from "./plugins/pluginCommandsLoader.js";
+// ─── LLM (extended for TUI) ─────────────────────────────────────
+export { defaultCacheDir, } from "./llm/model-cache.js";
+export { fetchModelList, } from "./llm/model-fetcher.js";
+export { sanitizeApiKey, hasNonAsciiPrintable, } from "./llm/api-key-sanitize.js";
+export { PROVIDER_KINDS, } from "./llm/provider-kinds.js";
+export { capabilitiesFor, } from "./llm/capabilities/index.js";
+// ─── Data ────────────────────────────────────────────────────────
+export { syncOpenRouterCatalog, getOpenRouterSnapshot, } from "./data/openrouter-sync.js";

package/dist/llm/api-key-sanitize.d.ts

@@ -0,0 +1,22 @@
+/**
+ * sanitizeApiKey — defensive cleanup for API keys pasted via the wizard.
+ *
+ * Windows terminals (ConPTY, legacy cmd.exe, IME-active states) are the main
+ * source of breakage: bracketed-paste residue, CR endings, zero-width chars
+ * pulled in from rich-text sources (Notion / OneNote / web pages), full-width
+ * spaces from CJK IME, smart quotes from word processors. None of these are
+ * valid in any real provider's API key, so we strip them and warn.
+ */
+export type SanitizeResult = {
+    value: string;
+    changed: boolean;
+    warnings: string[];
+};
+export declare function sanitizeApiKey(raw: string): SanitizeResult;
+/**
+ * Returns true when the sanitized key contains any non-ASCII-printable
+ * character. Real provider keys are uniformly ASCII (`[A-Za-z0-9_\-.]`-ish),
+ * so a stray non-ASCII char almost certainly means the user pasted the wrong
+ * thing (e.g. the surrounding sentence in Chinese).
+ */
+export declare function hasNonAsciiPrintable(s: string): boolean;