@cjhyy/code-shell 0.1.0-alpha.0

package/dist/run/types.d.ts

@@ -0,0 +1,136 @@
+/**
+ * Run — managed lifecycle types for long-running agent tasks.
+ *
+ * A Run wraps one or more Engine executions with queue, state machine,
+ * checkpoint, approval, and artifact tracking.
+ */
+import type { AgentPresetName } from "../preset/index.js";
+export type RunStatus = "queued" | "running" | "waiting_input" | "waiting_approval" | "blocked" | "completed" | "failed" | "cancelled";
+export interface RunSnapshot {
+    runId: string;
+    objective: string;
+    preset: AgentPresetName;
+    cwd: string;
+    status: RunStatus;
+    createdAt: number;
+    updatedAt: number;
+    startedAt: number | null;
+    finishedAt: number | null;
+    parentRunId: string | null;
+    sessionId: string | null;
+    childSessionIds: string[];
+    attemptCount: number;
+    latestCheckpointId: string | null;
+    latestApprovalId: string | null;
+    summary: string | null;
+    error: string | null;
+    tags: string[];
+    metadata: Record<string, unknown>;
+}
+export type RunEventType = "run_created" | "run_queued" | "run_started" | "session_linked" | "checkpoint_written" | "artifact_recorded" | "approval_requested" | "approval_resolved" | "run_blocked" | "run_resumed" | "run_completed" | "run_failed" | "run_cancelled";
+export interface RunEvent {
+    eventId: string;
+    runId: string;
+    type: RunEventType;
+    timestamp: number;
+    data: Record<string, unknown>;
+}
+export interface RunCheckpoint {
+    checkpointId: string;
+    runId: string;
+    createdAt: number;
+    phase: string;
+    objective: string;
+    summary: string;
+    nextAction: string | null;
+    linkedSessionId: string | null;
+    touchedTools: string[];
+    touchedArtifacts: string[];
+    waitingFor: null | {
+        kind: "input";
+        prompt: string;
+    } | {
+        kind: "approval";
+        approvalId: string;
+    };
+    evaluator: null | {
+        status: "pending" | "passed" | "failed";
+        findings: string[];
+    };
+    metadata: Record<string, unknown>;
+}
+export type ApprovalStatus = "pending" | "approved" | "rejected";
+export type ApprovalCategory = "tool" | "artifact_publish" | "workflow_transition" | "custom";
+export interface RunApproval {
+    approvalId: string;
+    runId: string;
+    createdAt: number;
+    resolvedAt: number | null;
+    status: ApprovalStatus;
+    category: ApprovalCategory;
+    title: string;
+    description: string;
+    payload: Record<string, unknown>;
+}
+export type ArtifactKind = "file" | "document" | "diagram" | "prototype" | "resource" | "custom";
+export type ArtifactRole = "input" | "output" | "checkpoint" | "supporting";
+export interface RunArtifactRef {
+    artifactRefId: string;
+    runId: string;
+    kind: ArtifactKind;
+    title: string;
+    locator: string;
+    role: ArtifactRole;
+    version: string | null;
+    metadata: Record<string, unknown>;
+}
+export interface SubmitRunInput {
+    objective: string;
+    preset?: AgentPresetName;
+    cwd?: string;
+    parentRunId?: string;
+    tags?: string[];
+    metadata?: Record<string, unknown>;
+}
+export interface ResumeRunInput {
+    userInput?: string;
+    approvalDecision?: {
+        approvalId: string;
+        approved: boolean;
+        reason?: string;
+    };
+}
+export interface ListRunsQuery {
+    status?: RunStatus | RunStatus[];
+    tag?: string;
+    limit?: number;
+    offset?: number;
+}
+export interface RunExecutionContext {
+    onStream?: import("../types.js").StreamCallback;
+    signal?: AbortSignal;
+    engineConfigOverrides?: Record<string, unknown>;
+}
+export interface RunExecutionResult {
+    text: string;
+    reason: import("../types.js").TerminalReason;
+    sessionId: string;
+    turnCount: number;
+}
+export type RunStreamEvent = {
+    type: "run_status_changed";
+    run: RunSnapshot;
+} | {
+    type: "run_event";
+    event: RunEvent;
+} | {
+    type: "engine_stream";
+    event: import("../types.js").StreamEvent;
+};
+export type RunStreamCallback = (event: RunStreamEvent) => void | Promise<void>;
+export type DetachFn = () => void;
+/**
+ * Valid state transitions for a Run.
+ * Key = current status, Value = allowed next statuses.
+ */
+export declare const VALID_TRANSITIONS: Record<RunStatus, RunStatus[]>;

package/dist/services/analytics.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Analytics service — event tracking and telemetry.
+ *
+ * Provides a lightweight analytics pipeline that queues events
+ * and flushes them to configured sinks (file, console, or remote).
+ */
+export interface AnalyticsEvent {
+    name: string;
+    properties?: Record<string, unknown>;
+    timestamp?: string;
+}
+type AnalyticsSink = (events: AnalyticsEvent[]) => void;
+declare class AnalyticsService {
+    private queue;
+    private sinks;
+    private flushTimer;
+    private initialized;
+    /**
+     * Initialize the analytics service with default file sink.
+     */
+    init(): void;
+    addSink(sink: AnalyticsSink): void;
+    track(name: string, properties?: Record<string, unknown>): void;
+    flush(): void;
+    shutdown(): void;
+}
+export declare const analytics: AnalyticsService;
+export declare function trackEvent(name: string, properties?: Record<string, unknown>): void;
+export {};

package/dist/services/auto-dream.d.ts

@@ -0,0 +1,35 @@
+/**
+ * AutoDream service — background memory consolidation.
+ *
+ * Periodically consolidates and organizes memories using the LLM,
+ * similar to the /dream command but running automatically.
+ */
+export interface AutoDreamConfig {
+    /** Minimum sessions between dream runs */
+    minSessionsBetween: number;
+    /** Minimum time between dream runs (ms) */
+    minTimeBetween: number;
+    /** Whether auto-dream is enabled */
+    enabled: boolean;
+}
+/**
+ * Check if auto-dream should run.
+ */
+export declare function shouldAutoDream(config?: AutoDreamConfig): boolean;
+/**
+ * Record that a session was completed (increment counter).
+ */
+export declare function recordSession(): void;
+/**
+ * Record that a dream run completed.
+ */
+export declare function recordDreamComplete(): void;
+/**
+ * Build the consolidation prompt for auto-dream.
+ */
+export declare function buildDreamPrompt(memories: Array<{
+    name: string;
+    type: string;
+    description: string;
+    content: string;
+}>): string;

package/dist/services/compact.d.ts

@@ -0,0 +1,56 @@
+/**
+ * Compaction service — context window management and auto-compaction.
+ *
+ * Provides microcompact (inline trimming), autocompact (threshold-based),
+ * and full compaction (LLM-based summarization) strategies.
+ */
+export interface CompactionConfig {
+    /** Max context tokens before triggering auto-compaction */
+    autoCompactThreshold: number;
+    /** Percentage of context to retain after compaction (0-1) */
+    retentionRatio: number;
+    /** Whether to preserve system messages during compaction */
+    preserveSystemMessages: boolean;
+    /** Whether auto-compaction is enabled */
+    autoCompactEnabled: boolean;
+}
+export interface CompactionResult {
+    /** Summary text that replaces the compacted content */
+    summary: string;
+    /** Number of messages removed */
+    messagesRemoved: number;
+    /** Tokens freed */
+    tokensFreed: number;
+    /** Strategy used */
+    strategy: "micro" | "auto" | "full";
+}
+export interface Message {
+    role: string;
+    content: string | unknown[];
+    tokenEstimate?: number;
+}
+/**
+ * Micro-compaction: trim tool results and long messages inline.
+ */
+export declare function microCompact(messages: Message[], maxTokensPerMessage?: number): Message[];
+/**
+ * Check if auto-compaction should be triggered.
+ */
+export declare function shouldAutoCompact(currentTokens: number, config?: CompactionConfig): boolean;
+/**
+ * Build a compaction prompt for LLM-based summarization.
+ */
+export declare function buildCompactionPrompt(messages: Message[], customInstructions?: string): string;
+/**
+ * Apply compaction by removing old messages and inserting a summary.
+ */
+export declare function applyCompaction(messages: Message[], summary: string, config?: CompactionConfig): {
+    messages: Message[];
+    result: CompactionResult;
+};
+export declare const compactionService: {
+    microCompact: typeof microCompact;
+    shouldAutoCompact: typeof shouldAutoCompact;
+    buildCompactionPrompt: typeof buildCompactionPrompt;
+    applyCompaction: typeof applyCompaction;
+};

package/dist/services/diagnostics.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Diagnostics service — error tracking and system health monitoring.
+ *
+ * Collects and reports diagnostic information for debugging.
+ */
+export interface DiagnosticEntry {
+    timestamp: string;
+    level: "error" | "warn" | "info";
+    category: string;
+    message: string;
+    metadata?: Record<string, unknown>;
+    stack?: string;
+}
+declare class DiagnosticsTracker {
+    private logDir;
+    private entries;
+    constructor();
+    /**
+     * Record a diagnostic event.
+     */
+    record(level: DiagnosticEntry["level"], category: string, message: string, metadata?: Record<string, unknown>): void;
+    /**
+     * Record an error with stack trace.
+     */
+    recordError(category: string, error: Error, metadata?: Record<string, unknown>): void;
+    /**
+     * Get recent diagnostic entries.
+     */
+    getRecent(count?: number): DiagnosticEntry[];
+    /**
+     * Get entries by category.
+     */
+    getByCategory(category: string): DiagnosticEntry[];
+    /**
+     * Generate a diagnostic report for troubleshooting.
+     */
+    generateReport(): string;
+    private persist;
+}
+export declare const diagnostics: DiagnosticsTracker;
+export {};

package/dist/services/extract-memories.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Extract Memories service — extract durable memories from session transcripts.
+ *
+ * Runs at the end of a query loop to identify important information
+ * worth persisting across sessions.
+ */
+export interface ExtractedMemory {
+    type: "user" | "feedback" | "project" | "reference";
+    name: string;
+    description: string;
+    content: string;
+}
+/**
+ * Build the prompt for extracting memories from a conversation.
+ */
+export declare function buildExtractionPrompt(transcript: Array<{
+    role: string;
+    content: string;
+}>, existingMemories: Array<{
+    name: string;
+    type: string;
+    description: string;
+}>): string;
+/**
+ * Parse extracted memories from LLM response.
+ */
+export declare function parseExtractionResponse(response: string): ExtractedMemory[];

package/dist/services/index.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Services index — re-exports all service modules.
+ */
+export { analytics, trackEvent } from "./analytics.js";
+export { compactionService, microCompact, shouldAutoCompact, buildCompactionPrompt, applyCompaction, type CompactionConfig, type CompactionResult, } from "./compact.js";
+export { authorize, refreshToken, type OAuthConfig, type OAuthTokens } from "./oauth.js";
+export { notify, notifyComplete, notifyError } from "./notifier.js";
+export { diagnostics } from "./diagnostics.js";
+export { buildExtractionPrompt, parseExtractionResponse, type ExtractedMemory, } from "./extract-memories.js";
+export { shouldAutoDream, recordSession, recordDreamComplete, buildDreamPrompt, } from "./auto-dream.js";
+export { saveSessionMemory, loadSessionMemory, listSessionMemories, searchSessionMemories, buildSessionMemoryPrompt, } from "./session-memory.js";

package/dist/services/notifier.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Notifier service — desktop/system notifications.
+ *
+ * Sends notifications when tasks complete, agents finish, or errors occur.
+ * Falls back gracefully when no notification system is available.
+ */
+export interface NotificationOptions {
+    title: string;
+    message: string;
+    sound?: boolean;
+    /** Urgency level: low, normal, critical */
+    urgency?: "low" | "normal" | "critical";
+}
+/**
+ * Send a desktop notification.
+ */
+export declare function notify(options: NotificationOptions): void;
+/**
+ * Send a notification that a task/agent has completed.
+ */
+export declare function notifyComplete(taskName: string, duration?: number): void;
+/**
+ * Send an error notification.
+ */
+export declare function notifyError(context: string, error: string): void;

package/dist/services/oauth.d.ts

@@ -0,0 +1,27 @@
+/**
+ * OAuth service — OAuth 2.0 authorization code flow with PKCE.
+ *
+ * Supports browser-based login flow for API authentication.
+ */
+export interface OAuthConfig {
+    clientId: string;
+    authorizationEndpoint: string;
+    tokenEndpoint: string;
+    redirectUri?: string;
+    scopes?: string[];
+}
+export interface OAuthTokens {
+    accessToken: string;
+    refreshToken?: string;
+    expiresAt?: number;
+    tokenType: string;
+}
+/**
+ * Run the OAuth authorization code flow.
+ * Opens a browser for user login and waits for the callback.
+ */
+export declare function authorize(config: OAuthConfig): Promise<OAuthTokens>;
+/**
+ * Refresh an access token using a refresh token.
+ */
+export declare function refreshToken(config: OAuthConfig, refreshTokenValue: string): Promise<OAuthTokens>;

package/dist/services/session-memory.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Session Memory service — automatic session memory maintenance.
+ *
+ * Extracts and maintains conversation context as persistent memory
+ * entries that survive across sessions.
+ */
+export interface SessionMemoryEntry {
+    sessionId: string;
+    summary: string;
+    keyTopics: string[];
+    decisions: string[];
+    createdAt: string;
+    tokenCount?: number;
+}
+/**
+ * Save a session memory entry.
+ */
+export declare function saveSessionMemory(entry: SessionMemoryEntry): void;
+/**
+ * Load a session memory by session ID.
+ */
+export declare function loadSessionMemory(sessionId: string): SessionMemoryEntry | null;
+/**
+ * List all session memories, most recent first.
+ */
+export declare function listSessionMemories(limit?: number): SessionMemoryEntry[];
+/**
+ * Search session memories by keyword.
+ */
+export declare function searchSessionMemories(query: string): SessionMemoryEntry[];
+/**
+ * Build a prompt for extracting session memory from a conversation.
+ */
+export declare function buildSessionMemoryPrompt(messages: Array<{
+    role: string;
+    content: string;
+}>): string;

package/dist/session/file-history.d.ts

@@ -0,0 +1,41 @@
+/**
+ * File history — automatic backup of files before modifications.
+ *
+ * Stores snapshots in the session directory under file-history/.
+ * Supports restoring files to a previous state.
+ */
+export interface FileSnapshot {
+    filePath: string;
+    timestamp: number;
+    backupPath: string;
+    hash: string;
+    size: number;
+}
+export declare class FileHistory {
+    private readonly historyDir;
+    private snapshots;
+    constructor(sessionDir: string);
+    /**
+     * Save a snapshot of a file before it is modified.
+     * Returns the snapshot record, or null if the file doesn't exist.
+     */
+    saveSnapshot(filePath: string): FileSnapshot | null;
+    /**
+     * Get all snapshots for a specific file.
+     */
+    getSnapshots(filePath: string): FileSnapshot[];
+    /**
+     * Restore a file to a specific snapshot.
+     */
+    restore(snapshot: FileSnapshot): boolean;
+    /**
+     * Restore a file to its most recent snapshot.
+     */
+    restoreLatest(filePath: string): boolean;
+    /**
+     * Get all tracked files.
+     */
+    getTrackedFiles(): string[];
+    private saveIndex;
+    static loadFromDir(sessionDir: string): FileHistory;
+}

package/dist/session/memory.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Memory system — persistent cross-session memory.
+ *
+ * Stores structured memory entries in ~/.code-shell/memory/ as individual markdown files.
+ * MEMORY.md is the index file.
+ */
+export interface MemoryEntry {
+    name: string;
+    description: string;
+    type: "user" | "feedback" | "project" | "reference";
+    content: string;
+    fileName: string;
+}
+export declare class MemoryManager {
+    private readonly memoryDir;
+    private readonly indexPath;
+    constructor(projectDir?: string);
+    getMemoryDir(): string;
+    /**
+     * Save a memory entry. Creates the file and updates the index.
+     */
+    save(entry: Omit<MemoryEntry, "fileName">): string;
+    /**
+     * Load all memory entries.
+     */
+    loadAll(): MemoryEntry[];
+    /**
+     * Load a single memory file.
+     */
+    private loadFile;
+    /**
+     * Delete a memory by name or filename.
+     */
+    delete(nameOrFile: string): boolean;
+    /**
+     * Get the MEMORY.md index content for injection into prompts.
+     */
+    getIndex(): string;
+    /**
+     * Build a prompt-friendly summary of all memories.
+     */
+    buildMemoryContext(): string;
+    private updateIndex;
+    private slugify;
+}

package/dist/session/session-manager.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Session lifecycle manager.
+ */
+import type { SessionState } from "../types.js";
+import { Transcript } from "./transcript.js";
+export interface SessionBundle {
+    state: SessionState;
+    transcript: Transcript;
+}
+export declare class SessionManager {
+    private readonly sessionsDir;
+    constructor(storageDir?: string);
+    create(cwd: string, model: string, provider: string): SessionBundle;
+    resume(sessionId: string): SessionBundle;
+    saveState(state: SessionState): void;
+    /**
+     * Fork a session from a specific point.
+     * Creates a new session that shares events up to the given turn,
+     * then diverges independently.
+     */
+    fork(sourceSessionId: string, forkAtTurn?: number): SessionBundle;
+    list(limit?: number): SessionState[];
+}

package/dist/session/transcript.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Transcript — JSONL event log (NOT chat history).
+ * toMessages() derives Message[] from events for sending to LLM.
+ */
+import type { TranscriptEvent, TranscriptEventType, Message, ContentBlock } from "../types.js";
+export declare class Transcript {
+    private events;
+    private filePath;
+    private currentTurn;
+    getFilePath(): string;
+    constructor(filePath: string);
+    append(type: TranscriptEventType, data: Record<string, unknown>): TranscriptEvent;
+    appendMessage(role: string, content: string | ContentBlock[]): TranscriptEvent;
+    appendToolUse(toolName: string, toolCallId: string, args: Record<string, unknown>): TranscriptEvent;
+    appendToolResult(toolCallId: string, toolName: string, result?: string, error?: string): TranscriptEvent;
+    appendTurnBoundary(): TranscriptEvent;
+    appendSummary(summary: string, compactedRange: {
+        fromTurn: number;
+        toTurn: number;
+        eventCount: number;
+    }): TranscriptEvent;
+    appendError(error: string, details?: Record<string, unknown>): TranscriptEvent;
+    /**
+     * Derive Message[] from transcript events for sending to the LLM.
+     * This is the critical boundary: the LLM never sees the event log directly.
+     */
+    toMessages(): Message[];
+    getEvents(type?: TranscriptEventType): TranscriptEvent[];
+    get turnNumber(): number;
+    get eventCount(): number;
+    private flush;
+    /**
+     * Repair tool_result pairing issues:
+     * - Orphaned tool_results (no matching tool_use) get removed
+     * - Missing tool_results (tool_use with no result) get synthetic error results
+     */
+    repairToolResultPairs(): void;
+    static loadFromFile(filePath: string): Transcript;
+}

package/dist/session-manager-JIIBCFTC.js

@@ -0,0 +1,8 @@
+import {
+  SessionManager
+} from "./chunk-S74VVJBF.js";
+import "./chunk-FUOKLKR2.js";
+import "./chunk-DI7RDLOS.js";
+export {
+  SessionManager
+};

package/dist/session-manager-UQKB564H.cjs

@@ -0,0 +1,8 @@
+"use strict";Object.defineProperty(exports, "__esModule", {value: true});
+
+var _chunkNG73UR3Lcjs = require('./chunk-NG73UR3L.cjs');
+require('./chunk-EL2RL5DG.cjs');
+require('./chunk-IJSHQGMP.cjs');
+
+
+exports.SessionManager = _chunkNG73UR3Lcjs.SessionManager;

package/dist/settings/manager.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Settings manager — multi-source loading and merge.
+ *
+ * Priority: CLI flags > local > project > user > managed
+ */
+import { type ValidatedSettings } from "./schema.js";
+export type SettingsSourceName = "managed" | "user" | "project" | "local" | "flag";
+export declare class SettingsManager {
+    private readonly cwd;
+    private sources;
+    private merged;
+    constructor(cwd?: string);
+    /**
+     * Load settings from all sources.
+     */
+    load(flagOverrides?: Record<string, unknown>): ValidatedSettings;
+    /**
+     * Get current effective settings.
+     */
+    get(): ValidatedSettings;
+    /**
+     * Invalidate cached merge.
+     */
+    invalidate(): void;
+    private loadJsonFile;
+    private deepMerge;
+}