noumen 0.1.0 → 0.2.0

package/dist/types-CwKKucOF.d.ts

@@ -0,0 +1,620 @@
+import { c as CheckpointConfig, F as FileCheckpointState, D as DiffStats, d as FileCheckpointSnapshot, S as StreamEvent, e as ContentPart } from './types-3c88cRKH.js';
+import { a as PermissionMode, b as PermissionResult } from './types-DwdzmXfs.js';
+
+interface FileEntry {
+    name: string;
+    path: string;
+    isDirectory: boolean;
+    isFile: boolean;
+    size?: number;
+}
+interface FileStat {
+    size: number;
+    isDirectory: boolean;
+    isFile: boolean;
+    createdAt?: Date;
+    modifiedAt?: Date;
+}
+interface ReadOptions {
+    encoding?: BufferEncoding;
+}
+/**
+ * Sandboxed filesystem interface.
+ *
+ * `VirtualFs` is noumen's primary isolation boundary for file I/O. Every
+ * built-in tool that touches the filesystem (ReadFile, WriteFile, EditFile)
+ * delegates to this interface — the agent never accesses `node:fs` directly.
+ *
+ * Swap implementations to control where files live and what the agent can reach:
+ * - `LocalFs`   — reads/writes on the host filesystem (no isolation, for local dev)
+ * - `SpritesFs` — reads/writes inside a remote sprites.dev container (full sandbox)
+ * - Custom      — implement this interface for Docker volumes, E2B, S3, in-memory, etc.
+ */
+interface VirtualFs {
+    readFile(path: string, opts?: ReadOptions): Promise<string>;
+    /**
+     * Read raw bytes from a file. Used for binary content (images, PDFs).
+     * Implementations SHOULD cap the read at `maxBytes` to prevent OOM on
+     * very large files. When `maxBytes` is omitted, the entire file is read.
+     *
+     * Returns a Buffer (Node.js) or Uint8Array.
+     */
+    readFileBytes?(path: string, maxBytes?: number): Promise<Buffer>;
+    writeFile(path: string, content: string): Promise<void>;
+    appendFile(path: string, content: string): Promise<void>;
+    deleteFile(path: string, opts?: {
+        recursive?: boolean;
+    }): Promise<void>;
+    mkdir(path: string, opts?: {
+        recursive?: boolean;
+    }): Promise<void>;
+    readdir(path: string, opts?: {
+        recursive?: boolean;
+    }): Promise<FileEntry[]>;
+    exists(path: string): Promise<boolean>;
+    stat(path: string): Promise<FileStat>;
+}
+
+interface ExecOptions {
+    timeout?: number;
+    cwd?: string;
+    env?: Record<string, string>;
+}
+interface CommandResult {
+    exitCode: number;
+    stdout: string;
+    stderr: string;
+}
+/**
+ * Sandboxed shell execution interface.
+ *
+ * `VirtualComputer` is noumen's primary isolation boundary for command
+ * execution. Every built-in tool that runs shell commands (Bash, Glob, Grep)
+ * delegates to this interface — the agent never spawns processes directly.
+ *
+ * Swap implementations to control where and how commands run:
+ * - `LocalComputer`   — runs on the host machine (no isolation, for local dev)
+ * - `SpritesComputer`  — runs in a remote sprites.dev container (full sandbox)
+ * - Custom             — implement this interface for Docker, E2B, Daytona, etc.
+ */
+interface VirtualComputer {
+    executeCommand(command: string, opts?: ExecOptions): Promise<CommandResult>;
+}
+
+/**
+ * Zod integration utilities. Users bring their own `zod` dependency — these
+ * helpers accept duck-typed schemas so we don't force a hard dependency.
+ */
+type JsonSchemaType = Record<string, unknown>;
+/**
+ * Minimal interface matching Zod v4's safeParse return. Allows noumen to
+ * validate tool input without depending on zod directly.
+ */
+interface SafeParseResult {
+    success: boolean;
+    data?: unknown;
+    error?: {
+        issues: Array<{
+            code: string;
+            path: (string | number)[];
+            message: string;
+        }>;
+    };
+}
+interface ZodLikeSchema {
+    safeParse(data: unknown): SafeParseResult;
+}
+/**
+ * Convert a Zod v4 schema to JSON Schema. Caches by schema identity.
+ * Requires `zod/v4` to be installed — calls its native `toJSONSchema`.
+ */
+declare function zodToJsonSchema(schema: ZodLikeSchema): JsonSchemaType;
+/**
+ * Register the `toJSONSchema` function from `zod/v4` so `zodToJsonSchema` can use it.
+ *
+ * ```ts
+ * import { toJSONSchema } from "zod/v4";
+ * import { registerZodToJsonSchema } from "noumen";
+ * registerZodToJsonSchema(toJSONSchema);
+ * ```
+ */
+declare function registerZodToJsonSchema(fn: (schema: unknown) => JsonSchemaType): void;
+/**
+ * Format a Zod validation error into a human-readable string suitable
+ * for feeding back to the model as a tool_result error.
+ */
+declare function formatZodValidationError(toolName: string, issues: SafeParseResult["error"]): string;
+
+type HookEvent = "PreToolUse" | "PostToolUse" | "PostToolUseFailure" | "PreCompact" | "PostCompact" | "TurnStart" | "TurnEnd" | "SubagentStart" | "SubagentStop" | "SessionStart" | "SessionEnd" | "PermissionRequest" | "PermissionDenied" | "FileWrite" | "ModelSwitch" | "RetryAttempt" | "MemoryUpdate" | "Error";
+interface PreToolUseHookInput {
+    event: "PreToolUse";
+    toolName: string;
+    toolInput: Record<string, unknown>;
+    toolUseId: string;
+    sessionId: string;
+}
+interface PreToolUseHookOutput {
+    decision?: "allow" | "deny" | "passthrough";
+    updatedInput?: Record<string, unknown>;
+    message?: string;
+    preventContinuation?: boolean;
+}
+interface PostToolUseHookInput {
+    event: "PostToolUse";
+    toolName: string;
+    toolInput: Record<string, unknown>;
+    toolUseId: string;
+    toolOutput: string;
+    isError: boolean;
+    sessionId: string;
+}
+interface PostToolUseHookOutput {
+    updatedOutput?: string;
+    preventContinuation?: boolean;
+}
+interface PostToolUseFailureHookInput {
+    event: "PostToolUseFailure";
+    toolName: string;
+    toolInput: Record<string, unknown>;
+    toolUseId: string;
+    toolOutput: string;
+    errorMessage: string;
+    sessionId: string;
+}
+type PostToolUseFailureHookOutput = PostToolUseHookOutput;
+interface SubagentStartHookInput {
+    event: "SubagentStart";
+    sessionId: string;
+    parentSessionId: string;
+    prompt: string;
+}
+interface SubagentStopHookInput {
+    event: "SubagentStop";
+    sessionId: string;
+    parentSessionId: string;
+    result: string;
+}
+interface SessionStartHookInput {
+    event: "SessionStart";
+    sessionId: string;
+    prompt: string | unknown[];
+    isResume: boolean;
+}
+interface SessionEndHookInput {
+    event: "SessionEnd";
+    sessionId: string;
+    reason: "complete" | "abort" | "maxTurns" | "error";
+}
+interface PermissionRequestHookInput {
+    event: "PermissionRequest";
+    sessionId: string;
+    toolName: string;
+    input: Record<string, unknown>;
+    mode: string;
+}
+interface PermissionDeniedHookInput {
+    event: "PermissionDenied";
+    sessionId: string;
+    toolName: string;
+    input: Record<string, unknown>;
+    reason: string;
+}
+interface FileWriteHookInput {
+    event: "FileWrite";
+    sessionId: string;
+    toolName: string;
+    filePath: string;
+    isNew: boolean;
+}
+interface ModelSwitchHookInput {
+    event: "ModelSwitch";
+    sessionId: string;
+    previousModel: string | undefined;
+    newModel: string;
+}
+interface RetryAttemptHookInput {
+    event: "RetryAttempt";
+    sessionId: string;
+    attempt: number;
+    maxAttempts: number;
+    error: string;
+    delay: number;
+}
+interface MemoryUpdateHookInput {
+    event: "MemoryUpdate";
+    sessionId: string;
+    entries: Array<{
+        type: string;
+        content: string;
+    }>;
+}
+interface NotificationHookInput {
+    event: "TurnStart" | "TurnEnd" | "Error" | "PreCompact" | "PostCompact";
+    sessionId: string;
+    [key: string]: unknown;
+}
+type HookInput = PreToolUseHookInput | PostToolUseHookInput | PostToolUseFailureHookInput | SubagentStartHookInput | SubagentStopHookInput | SessionStartHookInput | SessionEndHookInput | PermissionRequestHookInput | PermissionDeniedHookInput | FileWriteHookInput | ModelSwitchHookInput | RetryAttemptHookInput | MemoryUpdateHookInput | NotificationHookInput;
+type HookOutput = PreToolUseHookOutput | PostToolUseHookOutput | PostToolUseFailureHookOutput | void;
+interface HookDefinition {
+    event: HookEvent;
+    /** Optional tool name glob filter (e.g. "Bash", "mcp__*") */
+    matcher?: string;
+    handler: (input: HookInput) => Promise<HookOutput> | HookOutput;
+}
+
+type TaskStatus = "pending" | "in_progress" | "completed";
+interface Task {
+    id: string;
+    subject: string;
+    description?: string;
+    status: TaskStatus;
+    owner?: string;
+    /** Task IDs that this task blocks (downstream dependents). */
+    blocks: string[];
+    /** Task IDs that must complete before this task can start. */
+    blockedBy: string[];
+    createdAt: string;
+    updatedAt: string;
+}
+interface TaskCreateInput {
+    subject: string;
+    description?: string;
+}
+interface TaskUpdateInput {
+    status?: TaskStatus;
+    description?: string;
+    owner?: string;
+    blockedBy?: string[];
+}
+
+/**
+ * File-backed task store persisted on a VirtualFs instance.
+ * Tasks are stored as individual JSON files under a configurable directory.
+ */
+declare class TaskStore {
+    private dir;
+    private fs;
+    private nextId;
+    private initialized;
+    constructor(fs: VirtualFs, dir: string);
+    private ensureDir;
+    private taskPath;
+    create(input: TaskCreateInput): Promise<Task>;
+    get(id: string): Promise<Task | null>;
+    list(): Promise<Task[]>;
+    update(id: string, input: TaskUpdateInput): Promise<Task | null>;
+    delete(id: string): Promise<boolean>;
+}
+
+interface LspServerConfig {
+    /** Command to start the LSP server. */
+    command: string;
+    /** Arguments to pass to the command. */
+    args?: string[];
+    /** Root URI for the workspace. */
+    rootUri?: string;
+    /** File extensions this server handles (e.g., [".ts", ".tsx", ".js"]). */
+    fileExtensions: string[];
+    /** Environment variables for the server process. */
+    env?: Record<string, string>;
+}
+type LspServerState = "stopped" | "starting" | "running" | "error";
+interface LspDiagnostic {
+    filePath: string;
+    line: number;
+    character: number;
+    severity: "error" | "warning" | "info" | "hint";
+    message: string;
+    source?: string;
+}
+type LspOperation = "goToDefinition" | "findReferences" | "hover" | "documentSymbol" | "workspaceSymbol";
+interface LspLocation {
+    filePath: string;
+    line: number;
+    character: number;
+}
+interface LspSymbol {
+    name: string;
+    kind: string;
+    location: LspLocation;
+    containerName?: string;
+}
+
+/**
+ * Accumulates LSP diagnostics and provides them for injection into the agent context.
+ */
+declare class DiagnosticRegistry {
+    private pending;
+    /**
+     * Register diagnostics from an LSP server's publishDiagnostics notification.
+     * Replaces all diagnostics for the given file.
+     */
+    register(diagnostics: LspDiagnostic[]): void;
+    /**
+     * Clear diagnostics for a specific file (e.g., after a write/edit).
+     */
+    clearForFile(filePath: string): void;
+    /**
+     * Get all pending diagnostics and clear them.
+     */
+    flush(): LspDiagnostic[];
+    /**
+     * Get pending diagnostics without clearing.
+     */
+    peek(): LspDiagnostic[];
+    hasPending(): boolean;
+}
+
+/**
+ * Manages multiple LSP servers, maps file extensions to servers,
+ * and handles lifecycle (lazy start, file sync, shutdown).
+ */
+declare class LspServerManager {
+    private servers;
+    private extensionMap;
+    private diagnostics;
+    private rootUri;
+    constructor(configs: Record<string, LspServerConfig>, rootUri: string);
+    /**
+     * Get the server that handles a given file path.
+     */
+    private getServerForFile;
+    /**
+     * Ensure a server is started, starting it lazily if needed.
+     */
+    private ensureStarted;
+    /**
+     * Send a request to the appropriate server for a file.
+     */
+    sendRequest<T>(filePath: string, method: string, params: unknown): Promise<T | null>;
+    /**
+     * Notify LSP servers that a file was opened or changed.
+     */
+    notifyFileChanged(filePath: string, content: string, version: number): Promise<void>;
+    /**
+     * Notify LSP servers that a file was saved.
+     */
+    notifyFileSaved(filePath: string): void;
+    private ensureFileOpen;
+    /**
+     * Get the diagnostic registry for reading pending diagnostics.
+     */
+    getDiagnostics(): DiagnosticRegistry;
+    /**
+     * Check if any LSP server is connected and running.
+     */
+    isConnected(): boolean;
+    /**
+     * Return the name and state of every configured LSP server.
+     */
+    getServerStatus(): Array<{
+        name: string;
+        state: string;
+    }>;
+    /**
+     * Shut down all LSP servers.
+     */
+    shutdown(): Promise<void>;
+}
+
+declare class FileCheckpointManager {
+    private fs;
+    private maxSnapshots;
+    private backupDir;
+    private state;
+    constructor(fs: VirtualFs, config: CheckpointConfig);
+    getState(): FileCheckpointState;
+    private sessionBackupDir;
+    private resolveBackupPath;
+    private ensureBackupDir;
+    private createBackup;
+    private restoreBackup;
+    private hasFileChanged;
+    /**
+     * Create a new snapshot at the start of a user turn.
+     * For each tracked file, checks if it changed since the last backup and
+     * creates a new versioned backup if so.
+     */
+    makeSnapshot(messageId: string, sessionId: string): Promise<void>;
+    /**
+     * Track a file before it is edited. Creates the v1 backup (pre-edit state)
+     * and attaches it to the current (latest) snapshot.
+     * Called by write/edit tools before mutation.
+     */
+    trackEdit(filePath: string, messageId: string, sessionId: string): Promise<void>;
+    /**
+     * Restore all tracked files to the state captured in the snapshot
+     * matching the given messageId. Files that didn't exist at that point
+     * are deleted; files that existed are restored from backups.
+     */
+    rewind(messageId: string, sessionId: string): Promise<void>;
+    canRestore(messageId: string): boolean;
+    getDiffStats(messageId: string, sessionId: string): Promise<DiffStats>;
+    /**
+     * Rebuild checkpoint state from persisted JSONL entries (for session resume).
+     * Mirrors claude-code's buildFileHistorySnapshotChain + fileHistoryRestoreStateFromLog.
+     */
+    restoreStateFromEntries(snapshots: FileCheckpointSnapshot[]): void;
+}
+
+interface FileState {
+    /** The content the model saw (may be a line slice, not the full file). */
+    content: string;
+    /** File mtime at the time of read (ms since epoch). */
+    timestamp: number;
+    /** 1-based start line of the read window (undefined = full file or post-edit snapshot). */
+    offset?: number;
+    /** Line count of the read window (undefined = full file or post-edit snapshot). */
+    limit?: number;
+    /**
+     * When true, the model saw a transformed/truncated view (e.g. injected memory).
+     * Edit/Write tools still require an explicit Read when this is set.
+     */
+    isPartialView?: boolean;
+}
+interface FileStateCacheConfig {
+    enabled?: boolean;
+    /** Maximum number of cached file entries. Default: 100. */
+    maxEntries?: number;
+    /** Maximum total cached content in bytes. Default: 25 * 1024 * 1024 (25 MB). */
+    maxBytes?: number;
+}
+
+/**
+ * LRU cache tracking which files the model has read and at what mtime.
+ *
+ * Used by ReadFile to record reads and by EditFile/WriteFile to enforce
+ * "read-before-edit" — the model cannot edit a file it hasn't seen,
+ * preventing hallucinated edits on unseen content.
+ */
+declare class FileStateCache {
+    private entries;
+    private maxEntries;
+    private maxBytes;
+    private currentBytes;
+    constructor(config?: FileStateCacheConfig);
+    private key;
+    private byteSize;
+    set(path: string, state: FileState): void;
+    get(path: string): FileState | undefined;
+    has(path: string): boolean;
+    delete(path: string): void;
+    get size(): number;
+    get totalBytes(): number;
+    clear(): void;
+}
+
+interface ToolResult {
+    content: string | ContentPart[];
+    isError?: boolean;
+    /** Opaque metadata bag for tool-specific information (e.g. git operations). */
+    metadata?: Record<string, unknown>;
+}
+interface SubagentConfig {
+    prompt: string;
+    systemPrompt?: string;
+    /** Tool name allowlist. When set, only these tools are available. */
+    allowedTools?: string[];
+    permissionMode?: PermissionMode;
+    maxTurns?: number;
+    model?: string;
+}
+/** Async generator of stream events from a subagent run. */
+interface SubagentRun {
+    sessionId: string;
+    events: AsyncGenerator<StreamEvent, void, unknown>;
+}
+/**
+ * Execution context passed to every tool call. All file and shell access
+ * goes through `fs` and `computer`, which are the sandboxing boundary —
+ * tools never touch `node:fs` or `child_process` directly. The isolation
+ * level is determined by which VirtualFs/VirtualComputer implementations
+ * the consumer provides (e.g. `LocalFs` for local dev, `SpritesFs` for
+ * remote sandboxed containers).
+ */
+interface ToolContext {
+    fs: VirtualFs;
+    computer: VirtualComputer;
+    cwd: string;
+    /** The session ID of the current thread (used by Agent tool for hook events). */
+    sessionId?: string;
+    /** Hook definitions from the parent thread (used by Agent tool for subagent lifecycle hooks). */
+    hooks?: HookDefinition[];
+    /** Factory for spawning isolated subagent threads. */
+    spawnSubagent?: (config: SubagentConfig) => SubagentRun;
+    /** Handler for user input requests from the AskUser tool. */
+    userInputHandler?: (question: string) => Promise<string>;
+    /** Task store for TaskCreate/List/Get/Update tools. */
+    taskStore?: TaskStore;
+    /** Set the current permission mode (used by PlanMode tools). */
+    setPermissionMode?: (mode: PermissionMode) => void;
+    /** Get the current permission mode. */
+    getPermissionMode?: () => PermissionMode;
+    /** Set the thread's working directory (used by Worktree tools). */
+    setCwd?: (cwd: string) => void;
+    /** LSP server manager for the LSP tool. */
+    lspManager?: LspServerManager;
+    /** File checkpoint manager for pre-edit backup tracking. */
+    checkpointManager?: FileCheckpointManager;
+    /** Current message ID for checkpoint tracking (set per user turn). */
+    currentMessageId?: string;
+    /** File state cache for read-before-edit enforcement and dedup. */
+    fileStateCache?: FileStateCache;
+    /** Fire a notification hook from within a tool (populated by Thread). */
+    notifyHook?: (event: string, input: Record<string, unknown>) => Promise<void>;
+}
+interface ToolParameterProperty {
+    type: string;
+    description?: string;
+    enum?: string[];
+    default?: unknown;
+    minimum?: number;
+    maximum?: number;
+}
+interface ToolParameters {
+    type: "object";
+    properties: Record<string, ToolParameterProperty>;
+    required?: string[];
+}
+interface Tool {
+    name: string;
+    description: string;
+    /**
+     * Long model-facing instructions sent as the tool's API description.
+     * When omitted, `description` is used instead. This allows a short
+     * `description` for UI/permission prompts while sending detailed
+     * usage guidance to the model.
+     */
+    prompt?: string | (() => string);
+    parameters: ToolParameters;
+    /**
+     * Optional Zod schema for input validation. When present, tool input is
+     * validated via `safeParse` before execution. Validation errors are returned
+     * to the model as tool_result errors so it can self-correct.
+     */
+    inputSchema?: ZodLikeSchema;
+    /**
+     * Raw JSON Schema for tool input — sent directly to providers that support
+     * strict mode. When omitted, `parameters` is used as the JSON schema.
+     */
+    inputJSONSchema?: Record<string, unknown>;
+    /** Present on tools sourced from an MCP server */
+    mcpInfo?: {
+        serverName: string;
+        toolName: string;
+    };
+    /**
+     * Whether this tool only reads state and never mutates it.
+     * When `true`, the tool is auto-allowed in `default` mode for working directories
+     * and is permitted in `plan` mode. Can be a static boolean or a function of the input.
+     * Defaults to `false` when omitted.
+     */
+    isReadOnly?: boolean | ((args: Record<string, unknown>) => boolean);
+    /**
+     * Whether this tool performs irreversible/destructive operations.
+     * Used as metadata in permission requests so handlers can make informed decisions.
+     * Defaults to `false` when omitted.
+     */
+    isDestructive?: boolean | ((args: Record<string, unknown>) => boolean);
+    /**
+     * Whether this tool can safely run concurrently with other concurrency-safe
+     * tools. Read-only tools are typically safe; tools that mutate shared state
+     * (filesystem writes, shell commands) are not. Can be a static boolean or a
+     * function of the input. Defaults to `false` when omitted.
+     */
+    isConcurrencySafe?: boolean | ((args: Record<string, unknown>) => boolean);
+    /**
+     * Tool-specific permission check, called by the permission pipeline before
+     * global rules and mode-based decisions. Return `passthrough` to delegate
+     * to the global pipeline, or `allow`/`deny`/`ask` for tool-specific logic.
+     */
+    checkPermissions?: (args: Record<string, unknown>, ctx: ToolContext) => Promise<PermissionResult> | PermissionResult;
+    /**
+     * When true, this tool always requires interactive user input and must
+     * prompt even in bypassPermissions mode (e.g. AskUser).
+     */
+    requiresUserInteraction?: boolean;
+    call(args: Record<string, unknown>, ctx: ToolContext): Promise<ToolResult>;
+}
+
+export { type ZodLikeSchema as $, type PermissionDeniedHookInput as A, type PermissionRequestHookInput as B, type CommandResult as C, DiagnosticRegistry as D, type ExecOptions as E, type FileEntry as F, type RetryAttemptHookInput as G, type HookDefinition as H, type SafeParseResult as I, type JsonSchemaType as J, type SessionEndHookInput as K, type LspServerConfig as L, type MemoryUpdateHookInput as M, type NotificationHookInput as N, type SessionStartHookInput as O, type PostToolUseFailureHookInput as P, type SubagentStartHookInput as Q, type ReadOptions as R, type SubagentConfig as S, type Tool as T, type SubagentStopHookInput as U, type VirtualFs as V, type Task as W, type TaskCreateInput as X, type TaskStatus as Y, type TaskUpdateInput as Z, type ToolParameters as _, type LspServerState as a, formatZodValidationError as a0, registerZodToJsonSchema as a1, zodToJsonSchema as a2, type LspDiagnostic as b, type LspLocation as c, type LspOperation as d, LspServerManager as e, type LspSymbol as f, type ToolResult as g, type ToolContext as h, type FileStat as i, type VirtualComputer as j, type SubagentRun as k, TaskStore as l, FileCheckpointManager as m, type FileStateCacheConfig as n, type HookEvent as o, type HookInput as p, type PostToolUseFailureHookOutput as q, type PostToolUseHookInput as r, type PostToolUseHookOutput as s, type PreToolUseHookInput as t, type PreToolUseHookOutput as u, type FileState as v, FileStateCache as w, type FileWriteHookInput as x, type HookOutput as y, type ModelSwitchHookInput as z };