noumen 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,551 @@
+type UUID = string & {
+    readonly __brand: unique symbol;
+};
+
+interface ToolCallContent {
+    id: string;
+    type: "function";
+    function: {
+        name: string;
+        arguments: string;
+    };
+}
+interface UserMessage {
+    role: "user";
+    content: string;
+}
+interface AssistantMessage {
+    role: "assistant";
+    content: string | null;
+    tool_calls?: ToolCallContent[];
+}
+interface ToolResultMessage {
+    role: "tool";
+    tool_call_id: string;
+    content: string;
+}
+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;
+}
+type Entry = MessageEntry | CompactBoundaryEntry | SummaryEntry | CustomTitleEntry | MetadataEntry;
+interface SessionInfo {
+    sessionId: string;
+    createdAt: string;
+    lastMessageAt: string;
+    title?: string;
+    messageCount: number;
+}
+interface ToolResult$1 {
+    content: string;
+    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$1;
+} | {
+    type: "message_complete";
+    message: AssistantMessage;
+} | {
+    type: "compact_start";
+} | {
+    type: "compact_complete";
+} | {
+    type: "error";
+    error: Error;
+};
+interface RunOptions {
+    signal?: AbortSignal;
+}
+
+interface ToolParameterProperty$1 {
+    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$1>;
+            required?: string[];
+        };
+    };
+}
+interface ChatStreamDelta {
+    role?: "assistant";
+    content?: 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;
+    };
+}
+interface ChatCompletionUsage {
+    prompt_tokens: number;
+    completion_tokens: number;
+    total_tokens: number;
+}
+interface ChatParams {
+    model: string;
+    messages: ChatMessage[];
+    tools?: ToolDefinition[];
+    max_tokens?: number;
+    system?: string;
+    temperature?: number;
+}
+interface AIProvider {
+    chat(params: ChatParams): AsyncIterable<ChatStreamChunk>;
+}
+
+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;
+}
+interface VirtualFs {
+    readFile(path: string, opts?: ReadOptions): Promise<string>;
+    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;
+}
+interface VirtualComputer {
+    executeCommand(command: string, opts?: ExecOptions): Promise<CommandResult>;
+}
+
+interface SkillDefinition {
+    name: string;
+    content: string;
+    path?: string;
+    description?: string;
+    /** Glob patterns for files this skill applies to */
+    globs?: string[];
+}
+
+interface AutoCompactConfig {
+    enabled: boolean;
+    /** Token threshold at which to trigger compaction */
+    threshold: number;
+}
+declare function createAutoCompactConfig(opts?: {
+    enabled?: boolean;
+    threshold?: number;
+}): AutoCompactConfig;
+declare function shouldAutoCompact(messages: ChatMessage[], config: AutoCompactConfig): boolean;
+
+interface ThreadOptions {
+    sessionId?: string;
+    resume?: boolean;
+    cwd?: string;
+    model?: string;
+}
+interface ThreadConfig {
+    aiProvider: AIProvider;
+    fs: VirtualFs;
+    computer: VirtualComputer;
+    sessionDir: string;
+    skills?: SkillDefinition[];
+    systemPrompt?: string;
+    model?: string;
+    maxTokens?: number;
+    autoCompact?: AutoCompactConfig;
+}
+declare class Thread {
+    readonly sessionId: string;
+    private config;
+    private storage;
+    private toolRegistry;
+    private messages;
+    private loaded;
+    private abortController;
+    private cwd;
+    private model;
+    constructor(config: ThreadConfig, opts?: ThreadOptions);
+    run(prompt: string, opts?: RunOptions): AsyncGenerator<StreamEvent, void, unknown>;
+    getMessages(): Promise<ChatMessage[]>;
+    compact(opts?: {
+        instructions?: string;
+    }): Promise<void>;
+    abort(): void;
+}
+
+interface CodeOptions {
+    aiProvider: AIProvider;
+    virtualFs: VirtualFs;
+    virtualComputer: VirtualComputer;
+    options?: {
+        sessionDir?: string;
+        skills?: SkillDefinition[];
+        skillsPaths?: string[];
+        systemPrompt?: string;
+        model?: string;
+        maxTokens?: number;
+        autoCompact?: boolean;
+        autoCompactThreshold?: number;
+        cwd?: string;
+    };
+}
+declare class Code {
+    private aiProvider;
+    private fs;
+    private computer;
+    private sessionDir;
+    private skills;
+    private skillsPaths;
+    private systemPrompt?;
+    private model?;
+    private maxTokens?;
+    private autoCompactEnabled;
+    private autoCompactThreshold?;
+    private cwd;
+    private storage;
+    private resolvedSkills;
+    constructor(opts: CodeOptions);
+    private getSkills;
+    createThread(opts?: ThreadOptions): Thread;
+    listSessions(): Promise<SessionInfo[]>;
+    /**
+     * Pre-resolve skills from paths. Call this once after construction if using
+     * skillsPaths, so that createThread() has skills available synchronously.
+     */
+    init(): Promise<void>;
+}
+
+interface OpenAIProviderOptions {
+    apiKey: string;
+    baseURL?: string;
+    model?: string;
+}
+declare class OpenAIProvider implements AIProvider {
+    private client;
+    private defaultModel;
+    constructor(opts: OpenAIProviderOptions);
+    chat(params: ChatParams): AsyncIterable<ChatStreamChunk>;
+    private buildMessages;
+}
+
+interface AnthropicProviderOptions {
+    apiKey: string;
+    baseURL?: string;
+    model?: string;
+}
+declare class AnthropicProvider implements AIProvider {
+    private client;
+    private defaultModel;
+    constructor(opts: AnthropicProviderOptions);
+    chat(params: ChatParams): AsyncIterable<ChatStreamChunk>;
+    private makeChunk;
+    private convertMessages;
+}
+
+interface GeminiProviderOptions {
+    apiKey: string;
+    model?: string;
+}
+declare class GeminiProvider implements AIProvider {
+    private client;
+    private defaultModel;
+    constructor(opts: GeminiProviderOptions);
+    chat(params: ChatParams): AsyncIterable<ChatStreamChunk>;
+    private convertMessages;
+}
+
+interface LocalFsOptions {
+    basePath?: string;
+}
+declare class LocalFs implements VirtualFs {
+    private basePath;
+    constructor(opts?: LocalFsOptions);
+    private resolve;
+    readFile(filePath: string, opts?: ReadOptions): Promise<string>;
+    writeFile(filePath: string, content: string): Promise<void>;
+    appendFile(filePath: string, content: string): Promise<void>;
+    deleteFile(filePath: string, opts?: {
+        recursive?: boolean;
+    }): Promise<void>;
+    mkdir(dirPath: string, opts?: {
+        recursive?: boolean;
+    }): Promise<void>;
+    readdir(dirPath: string, opts?: {
+        recursive?: boolean;
+    }): Promise<FileEntry[]>;
+    exists(filePath: string): Promise<boolean>;
+    stat(filePath: string): Promise<FileStat>;
+}
+
+interface LocalComputerOptions {
+    defaultCwd?: string;
+    defaultTimeout?: number;
+}
+declare class LocalComputer implements VirtualComputer {
+    private defaultCwd;
+    private defaultTimeout;
+    constructor(opts?: LocalComputerOptions);
+    executeCommand(command: string, opts?: ExecOptions): Promise<CommandResult>;
+}
+
+interface SpritesFsOptions {
+    /** sprites.dev API token */
+    token: string;
+    /** Name of the sprite container */
+    spriteName: string;
+    /** Base URL for sprites API (default: https://api.sprites.dev) */
+    baseURL?: string;
+    /** Working directory inside the sprite (default: /home/sprite) */
+    workingDir?: string;
+}
+declare class SpritesFs implements VirtualFs {
+    private token;
+    private spriteName;
+    private baseURL;
+    private workingDir;
+    constructor(opts: SpritesFsOptions);
+    private fsUrl;
+    private resolvePath;
+    private headers;
+    readFile(filePath: string, _opts?: ReadOptions): Promise<string>;
+    writeFile(filePath: string, content: string): Promise<void>;
+    appendFile(filePath: string, content: string): Promise<void>;
+    deleteFile(filePath: string, opts?: {
+        recursive?: boolean;
+    }): Promise<void>;
+    mkdir(dirPath: string, opts?: {
+        recursive?: boolean;
+    }): Promise<void>;
+    readdir(dirPath: string, _opts?: {
+        recursive?: boolean;
+    }): Promise<FileEntry[]>;
+    exists(filePath: string): Promise<boolean>;
+    stat(filePath: string): Promise<FileStat>;
+}
+
+interface SpritesComputerOptions {
+    /** sprites.dev API token */
+    token: string;
+    /** Name of the sprite container */
+    spriteName: string;
+    /** Base URL for sprites API (default: https://api.sprites.dev) */
+    baseURL?: string;
+    /** Working directory inside the sprite (default: /home/sprite) */
+    workingDir?: string;
+}
+/**
+ * Executes commands inside a sprites.dev container via the exec REST endpoint.
+ *
+ * Uses the non-interactive exec mode: POST a command and get back
+ * stdout/stderr/exit_code. For more complex use cases (streaming, TTY),
+ * the WebSocket exec endpoint would be used, but for tool-call purposes
+ * the REST endpoint is sufficient.
+ */
+declare class SpritesComputer implements VirtualComputer {
+    private token;
+    private spriteName;
+    private baseURL;
+    private workingDir;
+    constructor(opts: SpritesComputerOptions);
+    private headers;
+    executeCommand(command: string, opts?: ExecOptions): Promise<CommandResult>;
+    private shellEscape;
+}
+
+interface ToolResult {
+    content: string;
+    isError?: boolean;
+}
+interface ToolContext {
+    fs: VirtualFs;
+    computer: VirtualComputer;
+    cwd: string;
+}
+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;
+    parameters: ToolParameters;
+    call(args: Record<string, unknown>, ctx: ToolContext): Promise<ToolResult>;
+}
+
+declare class ToolRegistry {
+    private tools;
+    constructor(additionalTools?: Tool[]);
+    get(name: string): Tool | undefined;
+    execute(name: string, args: Record<string, unknown>, ctx: ToolContext): Promise<{
+        content: string;
+        isError?: boolean;
+    }>;
+    toToolDefinitions(): ToolDefinition[];
+    listTools(): Tool[];
+}
+
+declare const readFileTool: Tool;
+
+declare const writeFileTool: Tool;
+
+declare const editFileTool: Tool;
+
+declare const bashTool: Tool;
+
+declare const globTool: Tool;
+
+declare const grepTool: Tool;
+
+/**
+ * Load skill definitions from SKILL.md files found at the given paths on the VirtualFs.
+ * Each path can be a directory (scanned for SKILL.md files) or a direct file.
+ */
+declare function loadSkills(fs: VirtualFs, paths: string[]): Promise<SkillDefinition[]>;
+
+declare class SessionStorage {
+    private fs;
+    private sessionDir;
+    constructor(fs: VirtualFs, sessionDir: string);
+    private getTranscriptPath;
+    ensureDir(): Promise<void>;
+    appendEntry(sessionId: string, entry: Entry): Promise<void>;
+    appendMessage(sessionId: string, message: ChatMessage, parentUuid?: UUID | null): Promise<UUID>;
+    appendCompactBoundary(sessionId: string): Promise<UUID>;
+    appendSummary(sessionId: string, summaryMessage: ChatMessage, parentUuid?: UUID | null): Promise<UUID>;
+    loadMessages(sessionId: string): Promise<ChatMessage[]>;
+    loadAllEntries(sessionId: string): Promise<Entry[]>;
+    sessionExists(sessionId: string): Promise<boolean>;
+    listSessions(): Promise<SessionInfo[]>;
+}
+
+interface CompactOptions {
+    customInstructions?: string;
+}
+declare function compactConversation(aiProvider: AIProvider, model: string, messages: ChatMessage[], storage: SessionStorage, sessionId: string, opts?: CompactOptions): Promise<ChatMessage[]>;
+
+declare function buildSystemPrompt(opts: {
+    customPrompt?: string;
+    skills?: SkillDefinition[];
+    tools?: Tool[];
+    date?: string;
+}): string;
+
+export { type AIProvider, AnthropicProvider, type AnthropicProviderOptions, type AssistantMessage, type AutoCompactConfig, type ChatCompletionUsage, type ChatMessage, type ChatParams, type ChatStreamChoice, type ChatStreamChunk, type ChatStreamDelta, Code, type CodeOptions, type CommandResult, type CompactBoundaryEntry, type CustomTitleEntry, type Entry, type ExecOptions, type FileEntry, type FileStat, GeminiProvider, type GeminiProviderOptions, LocalComputer, type LocalComputerOptions, LocalFs, type LocalFsOptions, type MessageEntry, type MetadataEntry, OpenAIProvider, type OpenAIProviderOptions, type ReadOptions, type RunOptions, type SerializedMessage, type SessionInfo, type SkillDefinition, SpritesComputer, type SpritesComputerOptions, SpritesFs, type SpritesFsOptions, type StreamEvent, type SummaryEntry, type SystemMessage, Thread, type ThreadConfig, type ThreadOptions, type Tool, type ToolCallContent, type ToolResult as ToolCallResult, type ToolContext, type ToolParameterProperty$1 as ToolDefParameterProperty, type ToolDefinition, type ToolParameters, ToolRegistry, type ToolResult$1 as ToolResult, type ToolResultMessage, type UserMessage, type VirtualComputer, type VirtualFs, bashTool, buildSystemPrompt, compactConversation, createAutoCompactConfig, editFileTool, globTool, grepTool, loadSkills, readFileTool, shouldAutoCompact, writeFileTool };