noumen 0.1.0 → 0.2.0

package/dist/types-3c88cRKH.d.ts

@@ -0,0 +1,547 @@
+/**
+ * USD cost per 1 million tokens for a given model.
+ */
+interface ModelPricing {
+    inputTokens: number;
+    outputTokens: number;
+    cacheReadTokens?: number;
+    cacheWriteTokens?: number;
+}
+/**
+ * Token usage from a single API call, extending the base ChatCompletionUsage
+ * with cache and thinking token counts.
+ */
+interface UsageRecord {
+    prompt_tokens: number;
+    completion_tokens: number;
+    total_tokens: number;
+    cache_read_tokens?: number;
+    cache_creation_tokens?: number;
+    thinking_tokens?: number;
+}
+/**
+ * Accumulated usage and cost for a single model.
+ */
+interface ModelUsageSummary {
+    inputTokens: number;
+    outputTokens: number;
+    cacheReadTokens: number;
+    cacheCreationTokens: number;
+    costUSD: number;
+}
+/**
+ * Complete cost summary across all models in the session.
+ */
+interface CostSummary {
+    totalCostUSD: number;
+    totalInputTokens: number;
+    totalOutputTokens: number;
+    totalCacheReadTokens: number;
+    totalCacheCreationTokens: number;
+    byModel: Record<string, ModelUsageSummary>;
+    duration: {
+        apiMs: number;
+        wallMs: number;
+    };
+}
+
+type UUID = string & {
+    readonly __brand: unique symbol;
+};
+
+type MemoryType = "user" | "project" | "feedback" | "reference";
+interface MemoryEntry {
+    /** Short identifier used as the basis for the filename. */
+    name: string;
+    /** One-line summary of what this memory contains. */
+    description: string;
+    type: MemoryType;
+    /** Full markdown content of the memory (excluding frontmatter). */
+    content: string;
+    /** Relative path within the memory directory (e.g. `"user_prefs.md"`). */
+    path?: string;
+    updatedAt?: string;
+}
+interface MemoryProvider {
+    /** Load the MEMORY.md index content for system-prompt injection. */
+    loadIndex(): Promise<string>;
+    /** Load a single memory entry by its path within the memory directory. */
+    loadEntry(path: string): Promise<MemoryEntry | null>;
+    /** Write or update a memory entry and refresh the index. */
+    saveEntry(entry: MemoryEntry): Promise<void>;
+    /** Delete a memory entry and refresh the index. */
+    removeEntry(path: string): Promise<void>;
+    /** List all memory entries in the directory. */
+    listEntries(): Promise<MemoryEntry[]>;
+    /** Simple keyword search across entry names and content. */
+    search(query: string): Promise<MemoryEntry[]>;
+}
+interface MemoryConfig {
+    provider: MemoryProvider;
+    /** Run LLM-driven memory extraction after each turn (default: false). */
+    autoExtract?: boolean;
+    /** Maximum number of lines in the MEMORY.md index before truncation (default: 200). */
+    maxIndexLines?: number;
+    /** Inject the memory index into the system prompt (default: true). */
+    injectIntoSystemPrompt?: boolean;
+}
+
+/**
+ * File checkpointing types.
+ *
+ * Adapted from claude-code's fileHistory system. Key difference: all I/O
+ * routes through VirtualFs so checkpointing works in any sandbox (Docker,
+ * E2B, Sprites, local).
+ */
+interface FileCheckpointBackup {
+    /** Backup filename under the session backup dir, or null if the file did not exist at this version. */
+    backupFileName: string | null;
+    version: number;
+    backupTime: string;
+}
+interface FileCheckpointSnapshot {
+    messageId: string;
+    /** Map of tracked file paths → their backup at this snapshot. */
+    trackedFileBackups: Record<string, FileCheckpointBackup>;
+    timestamp: string;
+}
+interface FileCheckpointState {
+    snapshots: FileCheckpointSnapshot[];
+    trackedFiles: Set<string>;
+    /**
+     * Monotonically-increasing counter incremented on every snapshot, even when
+     * old snapshots are evicted. Useful as an activity signal (snapshots.length
+     * plateaus once the cap is reached).
+     */
+    snapshotSequence: number;
+}
+interface CheckpointConfig {
+    enabled: boolean;
+    /** Maximum number of snapshots to retain before evicting oldest. Default: 100. */
+    maxSnapshots?: number;
+    /** Base directory for backup files. Default: ".noumen/checkpoints". */
+    backupDir?: string;
+}
+type DiffStats = {
+    filesChanged?: string[];
+    insertions: number;
+    deletions: number;
+} | undefined;
+declare function createCheckpointState(): FileCheckpointState;
+
+interface TextContent {
+    type: "text";
+    text: string;
+}
+interface ImageContent {
+    type: "image";
+    /** base64-encoded image data */
+    data: string;
+    /** MIME type: "image/png", "image/jpeg", "image/gif", "image/webp" */
+    media_type: string;
+}
+interface ImageUrlContent {
+    type: "image_url";
+    /** URL pointing to an image */
+    url: string;
+}
+type ContentPart = TextContent | ImageContent | ImageUrlContent;
+interface ToolCallContent {
+    id: string;
+    type: "function";
+    function: {
+        name: string;
+        arguments: string;
+    };
+}
+interface UserMessage {
+    role: "user";
+    content: string | ContentPart[];
+}
+interface AssistantMessage {
+    role: "assistant";
+    content: string | null;
+    tool_calls?: ToolCallContent[];
+}
+interface ToolResultMessage {
+    role: "tool";
+    tool_call_id: string;
+    content: string | ContentPart[];
+}
+interface SystemMessage {
+    role: "system";
+    content: string;
+}
+type ChatMessage = UserMessage | AssistantMessage | ToolResultMessage | SystemMessage;
+interface SerializedMessage {
+    uuid: UUID;
+    parentUuid: UUID | null;
+    sessionId: string;
+    timestamp: string;
+    message: ChatMessage;
+}
+interface MessageEntry {
+    type: "message";
+    uuid: UUID;
+    parentUuid: UUID | null;
+    sessionId: string;
+    timestamp: string;
+    message: ChatMessage;
+}
+interface CompactBoundaryEntry {
+    type: "compact-boundary";
+    uuid: UUID;
+    sessionId: string;
+    timestamp: string;
+}
+interface SummaryEntry {
+    type: "summary";
+    uuid: UUID;
+    parentUuid: UUID | null;
+    sessionId: string;
+    timestamp: string;
+    message: ChatMessage;
+}
+interface CustomTitleEntry {
+    type: "custom-title";
+    sessionId: string;
+    title: string;
+    timestamp: string;
+}
+interface MetadataEntry {
+    type: "metadata";
+    sessionId: string;
+    timestamp: string;
+    key: string;
+    value: unknown;
+}
+interface ToolResultOverflowEntry {
+    type: "tool-result-overflow";
+    sessionId: string;
+    timestamp: string;
+    toolCallId: string;
+    originalContent: string;
+}
+interface FileCheckpointEntry {
+    type: "file-checkpoint";
+    sessionId: string;
+    timestamp: string;
+    messageId: string;
+    snapshot: FileCheckpointSnapshot;
+    isSnapshotUpdate: boolean;
+}
+interface SnipBoundaryEntry {
+    type: "snip-boundary";
+    sessionId: string;
+    timestamp: string;
+    snipMetadata: {
+        removedUuids: string[];
+    };
+}
+interface ContentReplacementRecord {
+    toolUseId: string;
+    replacement: string;
+}
+interface ContentReplacementEntry {
+    type: "content-replacement";
+    sessionId: string;
+    timestamp: string;
+    replacements: ContentReplacementRecord[];
+}
+type Entry = MessageEntry | CompactBoundaryEntry | SummaryEntry | CustomTitleEntry | MetadataEntry | ToolResultOverflowEntry | FileCheckpointEntry | ContentReplacementEntry | SnipBoundaryEntry;
+interface SessionInfo {
+    sessionId: string;
+    createdAt: string;
+    lastMessageAt: string;
+    title?: string;
+    messageCount: number;
+}
+interface ToolResult {
+    content: string | ContentPart[];
+    isError?: boolean;
+}
+type StreamEvent = {
+    type: "text_delta";
+    text: string;
+} | {
+    type: "tool_use_start";
+    toolName: string;
+    toolUseId: string;
+} | {
+    type: "tool_use_delta";
+    input: string;
+} | {
+    type: "tool_result";
+    toolUseId: string;
+    toolName: string;
+    result: ToolResult;
+} | {
+    type: "message_complete";
+    message: AssistantMessage;
+} | {
+    type: "usage";
+    usage: ChatCompletionUsage;
+    model: string;
+} | {
+    type: "turn_complete";
+    usage: ChatCompletionUsage;
+    model: string;
+    callCount: number;
+} | {
+    type: "compact_start";
+} | {
+    type: "compact_complete";
+} | {
+    type: "microcompact_complete";
+    tokensFreed: number;
+} | {
+    type: "tool_result_truncated";
+    toolCallId: string;
+    originalChars: number;
+    truncatedChars: number;
+} | {
+    type: "error";
+    error: Error;
+} | {
+    type: "permission_request";
+    toolName: string;
+    input: Record<string, unknown>;
+    message: string;
+} | {
+    type: "permission_granted";
+    toolName: string;
+    input: Record<string, unknown>;
+} | {
+    type: "permission_denied";
+    toolName: string;
+    input: Record<string, unknown>;
+    message: string;
+} | {
+    type: "thinking_delta";
+    text: string;
+} | {
+    type: "cost_update";
+    summary: CostSummary;
+} | {
+    type: "retry_attempt";
+    attempt: number;
+    maxRetries: number;
+    delayMs: number;
+    error: Error;
+} | {
+    type: "retry_exhausted";
+    attempts: number;
+    error: Error;
+} | {
+    type: "subagent_start";
+    toolUseId: string;
+    prompt: string;
+} | {
+    type: "subagent_end";
+    toolUseId: string;
+    result: string;
+} | {
+    type: "user_input_request";
+    toolUseId: string;
+    question: string;
+} | {
+    type: "denial_limit_exceeded";
+    consecutiveDenials: number;
+    totalDenials: number;
+} | {
+    type: "span_start";
+    name: string;
+    spanId: string;
+} | {
+    type: "span_end";
+    name: string;
+    spanId: string;
+    durationMs: number;
+    error?: string;
+} | {
+    type: "memory_update";
+    created: MemoryEntry[];
+    updated: MemoryEntry[];
+    deleted: string[];
+} | {
+    type: "session_resumed";
+    sessionId: string;
+    messageCount: number;
+} | {
+    type: "checkpoint_snapshot";
+    messageId: string;
+} | {
+    type: "recovery_filtered";
+    filterName: string;
+    removedCount: number;
+} | {
+    type: "interrupted_turn_detected";
+    kind: "interrupted_tool" | "interrupted_prompt";
+} | {
+    type: "git_operation";
+    operation: "commit" | "push" | "pr_create" | "merge" | "rebase";
+    details: string;
+} | {
+    type: "structured_output";
+    data: unknown;
+    schema: OutputFormat;
+} | {
+    type: "max_turns_reached";
+    maxTurns: number;
+    turnCount: number;
+};
+interface RunOptions {
+    signal?: AbortSignal;
+    /**
+     * Maximum number of model-to-tool turns before the loop terminates.
+     * When exceeded, the thread yields a `max_turns_reached` event and stops.
+     */
+    maxTurns?: number;
+    /**
+     * Constrain the model to produce structured output.
+     *
+     * In `"alongside_tools"` mode (default), the outputFormat is passed
+     * directly to the provider on every model call — the model may still
+     * use tools alongside its structured response.
+     *
+     * In `"final_response"` mode, a synthetic `StructuredOutput` tool is
+     * injected. The agent loop continues using tools normally until the
+     * model calls StructuredOutput with the schema-conforming data. This
+     * is the recommended mode when the agent needs to reason and use
+     * tools before producing the final structured answer.
+     */
+    outputFormat?: OutputFormat;
+    /**
+     * Controls how structured output interacts with the tool loop.
+     * - `"alongside_tools"` (default): pass outputFormat to the provider;
+     *   the model response itself is structured JSON.
+     * - `"final_response"`: inject a synthetic StructuredOutput tool; the
+     *   model calls it to signal completion with structured data.
+     */
+    structuredOutputMode?: "alongside_tools" | "final_response";
+}
+
+type ThinkingConfig = {
+    type: "enabled";
+    budgetTokens: number;
+} | {
+    type: "disabled";
+};
+
+interface ToolParameterProperty {
+    type: string;
+    description?: string;
+    enum?: string[];
+    default?: unknown;
+    minimum?: number;
+    maximum?: number;
+}
+interface ToolDefinition {
+    type: "function";
+    function: {
+        name: string;
+        description: string;
+        parameters: {
+            type: "object";
+            properties: Record<string, ToolParameterProperty>;
+            required?: string[];
+        };
+    };
+}
+interface ChatStreamDelta {
+    role?: "assistant";
+    content?: string | null;
+    thinking_content?: string | null;
+    thinking_signature?: string | null;
+    tool_calls?: Array<{
+        index: number;
+        id?: string;
+        type?: "function";
+        function?: {
+            name?: string;
+            arguments?: string;
+        };
+    }>;
+}
+interface ChatStreamChoice {
+    index: number;
+    delta: ChatStreamDelta;
+    finish_reason: string | null;
+}
+interface ChatStreamChunk {
+    id: string;
+    choices: ChatStreamChoice[];
+    model: string;
+    usage?: {
+        prompt_tokens: number;
+        completion_tokens: number;
+        total_tokens: number;
+        cache_read_tokens?: number;
+        cache_creation_tokens?: number;
+        thinking_tokens?: number;
+    };
+}
+interface ChatCompletionUsage {
+    prompt_tokens: number;
+    completion_tokens: number;
+    total_tokens: number;
+    cache_read_tokens?: number;
+    cache_creation_tokens?: number;
+    thinking_tokens?: number;
+}
+/**
+ * Structured output format. When provided, the model is constrained to
+ * produce a response matching the given JSON schema.
+ *
+ * - `json_schema`: the model must produce JSON conforming to the given schema.
+ * - `json_object`: the model must produce valid JSON (no specific schema).
+ */
+type OutputFormat = JsonSchemaOutputFormat | JsonObjectOutputFormat;
+interface JsonSchemaOutputFormat {
+    type: "json_schema";
+    /** JSON Schema object describing the expected output shape. */
+    schema: Record<string, unknown>;
+    /** Optional name for the schema (required by some providers). */
+    name?: string;
+    /** When true, the provider enforces strict schema adherence. */
+    strict?: boolean;
+}
+interface JsonObjectOutputFormat {
+    type: "json_object";
+}
+interface ChatParams {
+    model: string;
+    messages: ChatMessage[];
+    tools?: ToolDefinition[];
+    max_tokens?: number;
+    system?: string;
+    temperature?: number;
+    thinking?: ThinkingConfig;
+    /** Constrain the model to produce structured output matching this schema. */
+    outputFormat?: OutputFormat;
+    /**
+     * When true, the provider should place the cache breakpoint on the
+     * second-to-last message instead of the last. Used by subagent forks
+     * to avoid writing fork-only tails into the shared prompt cache.
+     */
+    skipCacheWrite?: boolean;
+}
+interface AIProvider {
+    chat(params: ChatParams): AsyncIterable<ChatStreamChunk>;
+}
+/**
+ * Extended error type that providers can throw to convey retry-relevant metadata.
+ * Consumers (like the retry engine) can inspect these fields without knowing
+ * provider-specific SDK error types.
+ */
+declare class ChatStreamError extends Error {
+    status?: number;
+    retryAfter?: string;
+    constructor(message: string, opts?: {
+        status?: number;
+        retryAfter?: string;
+        cause?: unknown;
+    });
+}
+
+export { createCheckpointState as $, type AIProvider as A, type FileCheckpointBackup as B, type ChatParams as C, type DiffStats as D, type Entry as E, type FileCheckpointState as F, type FileCheckpointEntry as G, type ImageUrlContent as H, type ImageContent as I, type JsonSchemaOutputFormat as J, type JsonObjectOutputFormat as K, type MemoryType as L, type ModelPricing as M, type MessageEntry as N, type OutputFormat as O, type MetadataEntry as P, type SerializedMessage as Q, type RunOptions as R, type StreamEvent as S, type ToolDefinition as T, type UUID as U, type SnipBoundaryEntry as V, type SummaryEntry as W, type SystemMessage as X, type TextContent as Y, type ToolParameterProperty as Z, type UserMessage as _, type ChatStreamChunk as a, type ChatMessage as b, type CheckpointConfig as c, type FileCheckpointSnapshot as d, type ContentPart as e, type ContentReplacementRecord as f, type SessionInfo as g, type UsageRecord as h, type CostSummary as i, type ModelUsageSummary as j, type ChatCompletionUsage as k, type ThinkingConfig as l, type MemoryConfig as m, type ToolResult as n, type ToolCallContent as o, type MemoryProvider as p, type MemoryEntry as q, type AssistantMessage as r, type ToolResultMessage as s, type ToolResultOverflowEntry as t, type ChatStreamChoice as u, type ChatStreamDelta as v, ChatStreamError as w, type CompactBoundaryEntry as x, type ContentReplacementEntry as y, type CustomTitleEntry as z };