@cjhyy/code-shell 0.1.0-alpha.0

package/dist/engine/query.d.ts

@@ -0,0 +1,50 @@
+/**
+ * High-level query API — async generator wrapping TurnLoop.
+ *
+ * Callers consume events via `for await (const event of query(params))`.
+ * This is the public entry point for running agentic queries; TurnLoop
+ * is the internal state machine.
+ *
+ * Adapted from restored-src/src/query.ts, simplified for Code Shell.
+ */
+import type { Message, StreamEvent, ToolDefinition, TerminalReason } from "../types.js";
+import { type TurnLoopDeps } from "./turn-loop.js";
+export interface QueryParams {
+    /** Initial message history (including the new user message). */
+    messages: Message[];
+    /** System prompt text. */
+    systemPrompt: string;
+    /** Available tool definitions. */
+    tools: ToolDefinition[];
+    /** Max turns before forced stop. */
+    maxTurns?: number;
+    /** Max tool calls per turn (default 20). */
+    maxToolCallsPerTurn?: number;
+    /** Abort signal for cancellation. */
+    signal?: AbortSignal;
+    /** Dependencies injected by the caller (engine). */
+    deps: QueryDeps;
+}
+export interface QueryDeps {
+    model: TurnLoopDeps["model"];
+    toolExecutor: TurnLoopDeps["toolExecutor"];
+    contextManager: TurnLoopDeps["contextManager"];
+    hooks: TurnLoopDeps["hooks"];
+    transcript: TurnLoopDeps["transcript"];
+}
+export interface QueryResult {
+    text: string;
+    reason: TerminalReason;
+    turnCount: number;
+}
+/**
+ * Run an agentic query and yield stream events as they occur.
+ *
+ * Usage:
+ *   const events: StreamEvent[] = [];
+ *   for await (const event of query(params)) {
+ *     events.push(event);
+ *   }
+ *   // last event contains the final result
+ */
+export declare function query(params: QueryParams): AsyncGenerator<StreamEvent, QueryResult, undefined>;

package/dist/engine/streaming-tool-queue.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Streaming tool queue — enqueues tools for execution during streaming,
+ * starts concurrency-safe tools immediately, queues unsafe tools for
+ * sequential execution.
+ *
+ * Usage:
+ *   const queue = new StreamingToolQueue(executor);
+ *   // During streaming, as tool_use blocks arrive:
+ *   queue.enqueue(toolCall);
+ *   // After streaming completes:
+ *   const results = await queue.drain();
+ */
+import type { ToolCall, ToolResult } from "../types.js";
+import type { ToolExecutor } from "../tool-system/executor.js";
+export declare class StreamingToolQueue {
+    private readonly executor;
+    private readonly pending;
+    private readonly unsafeQueue;
+    private readonly callOrder;
+    private draining;
+    constructor(executor: ToolExecutor);
+    /**
+     * Enqueue a tool for execution. Concurrency-safe tools start immediately;
+     * unsafe tools are queued for sequential execution during drain().
+     */
+    enqueue(call: ToolCall): void;
+    /**
+     * Execute all remaining unsafe tools sequentially, then await all results.
+     * Returns results in original enqueue order.
+     */
+    drain(): Promise<ToolResult[]>;
+    /** Number of tools currently enqueued or executing. */
+    get size(): number;
+}

package/dist/engine/token-budget.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Token budget — decides whether the agent loop should continue, nudge, or stop.
+ *
+ * - "continue": keep going normally
+ * - "nudge": inject a "please wrap up" message, but continue
+ * - "stop": terminate the loop gracefully
+ */
+export interface BudgetTracker {
+    continuationCount: number;
+    lastDeltaTokens: number;
+    prevTurnTokens: number;
+}
+export declare function createBudgetTracker(): BudgetTracker;
+export type BudgetDecision = "continue" | "nudge" | "stop";
+/**
+ * Check if the turn loop should continue based on token output budget.
+ *
+ * @param turnOutputTokens - tokens output so far this turn
+ * @param budget - max tokens allowed for this turn (Infinity = no limit)
+ * @param tracker - mutable tracker state (updated in place)
+ */
+export declare function checkTokenBudget(turnOutputTokens: number, budget: number, tracker: BudgetTracker): BudgetDecision;

package/dist/engine/tool-summary.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Tool use summary — generates a 1-line progress label after tool batch execution.
+ *
+ * Runs async (fire-and-forget) so it doesn't block the next model call.
+ * Returns a short commit-subject-style string like "Read 3 files, fixed NPE in auth.ts"
+ */
+import type { ToolCall, ToolResult } from "../types.js";
+export type SummarizeFn = (systemPrompt: string, userMessage: string) => Promise<string>;
+/**
+ * Generate a 1-line summary of completed tool executions.
+ * Returns null on failure (non-critical).
+ */
+export declare function generateToolUseSummary(toolCalls: ToolCall[], results: ToolResult[], summarize: SummarizeFn): Promise<string | null>;

package/dist/engine/turn-loop.d.ts

@@ -0,0 +1,62 @@
+/**
+ * Turn loop — state machine implementation.
+ *
+ * Following Claude Code's po_() pattern:
+ * pre_check → model_call → post_check → tool_exec → context_mgmt → hook_notify → next turn
+ */
+import type { Message, StreamCallback, TerminalReason } from "../types.js";
+import { ModelFacade } from "./model-facade.js";
+import { ToolExecutor } from "../tool-system/executor.js";
+import { ContextManager } from "../context/manager.js";
+import { HookRegistry } from "../hooks/registry.js";
+import { Transcript } from "../session/transcript.js";
+export interface TurnLoopConfig {
+    maxTurns: number;
+    maxToolCallsPerTurn: number;
+    tokenBudget?: number;
+    onStream?: StreamCallback;
+    signal?: AbortSignal;
+}
+export interface TurnLoopDeps {
+    model: ModelFacade;
+    toolExecutor: ToolExecutor;
+    contextManager: ContextManager;
+    hooks: HookRegistry;
+    transcript: Transcript;
+    systemPrompt: string;
+    tools: import("../types.js").ToolDefinition[];
+}
+export declare class TurnLoop {
+    private readonly deps;
+    private readonly config;
+    private turnCount;
+    /** Tool IDs already emitted as tool_use_start during streaming (to avoid duplicates). */
+    private streamedToolIds;
+    constructor(deps: TurnLoopDeps, config: TurnLoopConfig);
+    /**
+     * Run the multi-turn agent loop until completion.
+     */
+    run(initialMessages: Message[]): Promise<{
+        text: string;
+        reason: TerminalReason;
+    }>;
+    /**
+     * Call model with streaming fallback.
+     * If streaming fails, emit tombstone and retry non-streaming.
+     */
+    private callModelWithFallback;
+    /**
+     * Execute tools with overlap: start concurrent-safe (read-only) tools
+     * immediately in parallel while sequential (write) tools run one-by-one.
+     * Both groups run simultaneously — we don't wait for safe tools to finish
+     * before starting unsafe ones.
+     */
+    private executeToolsOverlapped;
+    get currentTurn(): number;
+    /**
+     * Generate synthetic error tool_results for any dangling tool_use blocks
+     * that never received results (e.g. because the API call failed).
+     * Prevents model confusion on the next turn.
+     */
+    private patchOrphanedToolUses;
+}

package/dist/engine/turn-state.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Turn loop state definitions.
+ */
+import type { TurnPhase, ToolCall, LLMResponse, TerminalReason } from "../types.js";
+export interface TurnState {
+    phase: TurnPhase;
+    turnNumber: number;
+    modelResponse?: LLMResponse;
+    toolCalls?: ToolCall[];
+    finalText?: string;
+    error?: Error;
+    terminalReason?: TerminalReason;
+}
+export declare function initialTurnState(turnNumber: number): TurnState;

package/dist/exceptions.d.ts

@@ -0,0 +1,44 @@
+/**
+ * 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>);
+}

package/dist/file-history-HZWO2WQ5.js

@@ -0,0 +1,7 @@
+import {
+  FileHistory
+} from "./chunk-SK62UVS6.js";
+import "./chunk-DI7RDLOS.js";
+export {
+  FileHistory
+};

package/dist/file-history-UQQILIY7.cjs

@@ -0,0 +1,7 @@
+"use strict";Object.defineProperty(exports, "__esModule", {value: true});
+
+var _chunk3QR52LL5cjs = require('./chunk-3QR52LL5.cjs');
+require('./chunk-IJSHQGMP.cjs');
+
+
+exports.FileHistory = _chunk3QR52LL5cjs.FileHistory;

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/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/hooks/events.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Hook event type definitions.
+ */
+/**
+ * Lifecycle hooks the engine emits.
+ *
+ * **Currently emitted** (handlers registered here will actually fire):
+ *   - on_agent_start / on_agent_end        (engine.ts)
+ *   - on_turn_start / on_turn_end          (turn-loop.ts)
+ *   - pre_tool_use / post_tool_use         (executor.ts)
+ *   - on_tool_start / on_tool_end          (executor.ts)
+ *   - file_changed                         (executor.ts, Write/Edit only)
+ *
+ * **Reserved / not-yet-emitted** (defined so downstream can register handlers
+ * in anticipation; wire the emitter before relying on them):
+ *   - on_permission_check / on_session_start / on_session_end
+ *   - user_prompt_submit / pre_compact / post_compact / notification
+ */
+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";
+}

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;
+}