arki 0.0.8 → 0.0.9

package/README.md

@@ -68,6 +68,7 @@ arki -p /path/to/project --debug
 - `/exit` or `/quit` - Exit program
 - `/clear` - Clear conversation history
 - `/debug` - Toggle debug mode
+- `/lowcost` - Toggle lowcost mode (e.g., OpenAI flex)
 - `/help` - Show help
 
 ### Debug Mode
@@ -97,9 +98,13 @@ On first run, Arki copies the default configuration template to this location.
 Each project can have its own configuration in `.arki/` directory:
 
 - `.arki/config.json` - Project-specific settings (overrides global config)
-- `.arki/state.json` - Project state and cache
+- `.arki/state.json` - Project state (`initialized` flag)
+- `.arki/project_structure.md` - Auto-generated file tree structure
+- `.arki/architecture.xml` - Auto-generated modular architecture graph
 
 On first run in a new project, Arki will ask if you trust the project before initializing the `.arki/` directory.
+When you trust a project, the Init agent automatically analyzes the codebase and generates documentation files.
+To regenerate the architecture files, set `initialized` to `false` in `state.json`.
 Use `--init` to skip the prompt in non-interactive environments.
 
 ### Reset to Factory Defaults

package/dist/config/.arki/state.json

@@ -1,4 +1,3 @@
 {
-  "initialized": true,
-  "createdAt": ""
+  "initialized": false
 }

package/dist/config/arki/config.json

@@ -2,13 +2,18 @@
   "agents": {
     "Arki": {
       "model": "gpt-5.1",
-      "flex": true,
+      "lowcost": false,
       "reasoningEffort": "medium"
     },
     "Coder": {
       "model": "gpt-5.2",
-      "flex": true,
+      "lowcost": false,
       "reasoningEffort": "high"
+    },
+    "Init": {
+      "model": "gpt-5.1",
+      "lowcost": false,
+      "reasoningEffort": "medium"
     }
   }
 }

package/dist/index.d.ts

@@ -95,6 +95,13 @@ declare class AsyncToolResultMsg extends Msg {
  * Symbol indicating tool has detailed manual (needs to call read_tool_manual before use)
  */
 declare const HAS_MANUAL = "\uD83D\uDCD8";
+/**
+ * Context passed to tool execution
+ */
+interface ToolContext {
+    /** ID of the agent calling the tool */
+    agentId: string;
+}
 /**
  * Tool class
  */
@@ -112,7 +119,7 @@ declare class Tool {
         parameters: Record<string, unknown>;
         required: string[];
         manualContent: string;
-        execute: (args: Record<string, unknown>) => Promise<string | {
+        execute: (args: Record<string, unknown>, context: ToolContext) => Promise<string | {
             content: string;
             isError?: boolean;
         }>;
@@ -132,7 +139,7 @@ declare class Tool {
     /**
      * Execute tool (with error handling and logging)
      */
-    run(args: Record<string, unknown>): Promise<ToolResult>;
+    run(args: Record<string, unknown>, context: ToolContext): Promise<ToolResult>;
 }
 
 /**
@@ -157,35 +164,10 @@ declare class Procedure {
     };
 }
 
-/** OS type definition */
-interface OS_TYPE {
-    /** Operating system name: 'windows' | 'mac' | 'linux' | 'other' */
-    name: 'windows' | 'mac' | 'linux' | 'other';
-    /** Operating system version */
-    version: string;
-}
-/** Global OS information */
-declare const OS: OS_TYPE;
-/** Working directory */
-declare let workingDir: string;
-/** Set working directory (for testing) */
-declare function setWorkingDir(dir: string): void;
-/** Global paths configuration */
-declare const PATHS: {
-    /** Global config directory (~/.config/arki or %APPDATA%\arki) */
-    globalConfig: string;
-    /** Project config directory (.arki/) - returns path based on current workingDir */
-    readonly projectConfig: string;
-    /** Package's global config template directory */
-    globalTemplate: string;
-    /** Package's project config template directory */
-    projectTemplate: string;
-};
-
 /**
  * Reasoning effort
  */
-type ReasoningEffort$1 = 'low' | 'medium' | 'high';
+type ReasoningEffort = 'low' | 'medium' | 'high';
 /**
  * Platform-specific options for adapter
  */
@@ -213,6 +195,109 @@ declare abstract class Adapter {
     protected apiKey: string;
     constructor(apiKey: string);
     abstract chat(model: string, messages: Msg[], tools: Tool[], options: AdapterOptions, onChunk?: (chunk: string) => void): Promise<AdapterResponse>;
+    /**
+     * Count tokens for a complete request (messages + tools)
+     * @param model Model identifier
+     * @param messages Array of messages
+     * @param tools Array of tools
+     * @returns Estimated token count
+     */
+    abstract countTokens(model: string, messages: Msg[], tools: Tool[]): number;
+    /**
+     * Count tokens for plain text
+     * @param model Model identifier
+     * @param text Plain text to count tokens for
+     * @returns Token count
+     */
+    abstract countTextTokens(model: string, text: string): number;
+}
+
+interface AgentResponse {
+    response: string;
+    toolCalls: Array<{
+        name: string;
+        arguments: Record<string, unknown>;
+        result: string;
+    }>;
+    usage?: {
+        promptTokens: number;
+        completionTokens: number;
+        totalTokens: number;
+        cachedTokens?: number;
+    };
+}
+interface AgentConfig {
+    /** Agent name for display */
+    name: string;
+    adapter: Adapter;
+    model: string;
+    tools: Tool[];
+    platformOptions?: AdapterOptions;
+    messages: Msg[];
+    /** Maximum completion tokens for LLM response */
+    maxCompletionTokens?: number;
+    /** Context compression threshold (0.0-1.0), triggers compression when exceeded. Default: 0.9 */
+    contextCompressionThreshold?: number;
+}
+declare class Agent {
+    private config;
+    private messages;
+    private toolsMap;
+    /** Pending async tools: asyncCallId -> info */
+    private pendingAsyncTools;
+    constructor(config: AgentConfig);
+    /** Get agent name */
+    get name(): string;
+    /**
+     * Render template string, replacing {{variable}} style variables
+     */
+    static renderTemplate(template: string, variables: Record<string, string | number | boolean>): string;
+    /**
+     * Check and add placeholder results for pending async tools
+     * Called before appending new user message
+     */
+    private insertAsyncPlaceholders;
+    /**
+     * Handle async tool completion
+     */
+    private handleAsyncToolComplete;
+    run(userInput: string): Promise<AgentResponse>;
+    reset(): this;
+    /**
+     * Set a platform option at runtime
+     */
+    setPlatformOption(key: string, value: unknown): this;
+    /**
+     * Get a platform option value
+     */
+    getPlatformOption(key: string): unknown;
+    /**
+     * Get model's context window size
+     */
+    getContextWindow(): number;
+    /**
+     * Get compression threshold
+     */
+    getCompressionThreshold(): number;
+    /**
+     * Count current context tokens (messages + tools)
+     */
+    getContextTokens(): number;
+    /**
+     * Compress tool results by replacing long outputs with placeholders
+     * Returns the number of tool results compressed
+     */
+    compressToolResults(): number;
+    /**
+     * Summarize the conversation using LLM
+     * Keeps system messages and replaces conversation with summary
+     */
+    summarizeConversation(): Promise<void>;
+    /**
+     * Check context size and manage if threshold exceeded
+     * Called before each LLM call
+     */
+    checkAndManageContext(): Promise<void>;
 }
 
 /** Global tool registry */
@@ -220,30 +305,104 @@ declare const TOOLS: Record<string, Tool>;
 /** Global procedure registry */
 declare const PROCEDURES: Record<string, Procedure>;
 /** Global adapter registry by platform */
-declare const adapters: Record<string, Adapter>;
+declare const ADAPTERS: Record<string, Adapter>;
+/** Global agent registry by name */
+declare const AGENTS: Record<string, Agent>;
+
+/**
+ * FileSystem class provides unified file and directory operations
+ */
+declare class FileSystem {
+    /**
+     * Check if file exists (returns false for directories)
+     */
+    fileExists(filePath: string): Promise<boolean>;
+    /**
+     * Read file content as string
+     * Returns null if file doesn't exist
+     */
+    readFile(filePath: string): Promise<string | null>;
+    /**
+     * Write string content to file
+     */
+    writeFile(filePath: string, content: string): Promise<void>;
+    /**
+     * Read JSON file safely
+     * Returns null if file doesn't exist or is invalid JSON
+     */
+    readJsonFile<T>(filePath: string): Promise<T | null>;
+    /**
+     * Write JSON file with pretty formatting
+     */
+    writeJsonFile(filePath: string, data: unknown): Promise<void>;
+    /**
+     * Check if directory exists (returns false for files)
+     */
+    dirExists(dirPath: string): Promise<boolean>;
+    /**
+     * Create directory recursively (no error if exists)
+     */
+    mkdir(dirPath: string): Promise<void>;
+    /**
+     * Copy directory recursively (creates dest if not exists)
+     */
+    copyDir(src: string, dest: string): Promise<void>;
+}
+/** Global FileSystem instance for all file/directory operations */
+declare const fileSystem: FileSystem;
+
+/** OS type definition */
+interface OS_TYPE {
+    /** Operating system name: 'windows' | 'mac' | 'linux' | 'other' */
+    name: 'windows' | 'mac' | 'linux' | 'other';
+    /** Operating system version */
+    version: string;
+}
+/** Global OS information */
+declare const OS: OS_TYPE;
+/** Working directory */
+declare let workingDir: string;
+/** Set working directory (for testing) */
+declare function setWorkingDir(dir: string): void;
+/** Global paths configuration */
+declare const PATHS: {
+    /** Global config directory (~/.config/arki or %APPDATA%\arki) */
+    globalConfig: string;
+    /** Project config directory (.arki/) - returns path based on current workingDir */
+    readonly projectConfig: string;
+    /** Package's global config template directory */
+    globalTemplate: string;
+    /** Package's project config template directory */
+    projectTemplate: string;
+};
+/**
+ * Path variable definitions
+ * Format: $VAR or ${VAR}
+ */
+declare const PATH_VARS: Record<string, () => string>;
 /**
- * Get adapter by platform name
+ * Expand path variables in a string
+ * Supports: $VAR and ${VAR} formats
+ * @param inputPath Path string that may contain variables
+ * @returns Path with variables expanded
  */
-declare function getAdapter(platform: string): Adapter;
+declare function expandPathVars(inputPath: string): string;
+
 /** Initialize global state */
 declare function init(cwd?: string, forceInit?: boolean): Promise<void>;
 
 /**
  * Agent type
  */
-type AgentType = 'Arki' | 'Coder';
-/**
- * Reasoning effort
- */
-type ReasoningEffort = 'low' | 'medium' | 'high';
+type AgentType = 'Arki' | 'Coder' | 'Init';
 /**
  * Agent model configuration
  */
 interface AgentModelConfig {
     /** Model ID (provider is derived from MODELS) */
     model: string;
-    /** Use Flex API (low priority, low cost) - OpenAI specific */
-    flex?: boolean;
+    /** Low cost mode - adapter specific (e.g., OpenAI flex mode) */
+    lowcost?: boolean;
     /** Reasoning effort (thinking mode) */
     reasoningEffort?: ReasoningEffort;
 }
@@ -255,6 +414,13 @@ interface GlobalConfig {
         [K in AgentType]?: AgentModelConfig;
     };
 }
+/**
+ * Load and merge configurations
+ * - Loads global config from ~/.config/arki/config.json
+ * - Loads project config from .arki/config.json (if exists)
+ * - Merges them (project config overrides global)
+ */
+declare function loadConfigs(): Promise<GlobalConfig>;
 /**
  * Get loaded configuration
  */
@@ -377,7 +543,7 @@ interface OpenAIOptions extends AdapterOptions {
     /** Use Flex API - low priority, low cost */
     flex?: boolean;
     /** Reasoning effort (thinking mode) */
-    reasoningEffort?: ReasoningEffort$1;
+    reasoningEffort?: ReasoningEffort;
     /** Maximum completion tokens for LLM response */
     maxCompletionTokens?: number;
 }
@@ -387,59 +553,33 @@ declare class OpenAIAdapter extends Adapter {
     private toOpenAIMessages;
     private formatTools;
     chat(model: string, messages: Msg[], tools: Tool[], options: OpenAIOptions, onChunk?: (chunk: string) => void): Promise<AdapterResponse>;
-}
-
-interface AgentResponse {
-    response: string;
-    toolCalls: Array<{
-        name: string;
-        arguments: Record<string, unknown>;
-        result: string;
-    }>;
-    usage?: {
-        promptTokens: number;
-        completionTokens: number;
-        totalTokens: number;
-        cachedTokens?: number;
-    };
-}
-interface AgentConfig {
-    /** Agent name for display */
-    name: string;
-    adapter: Adapter;
-    model: string;
-    tools: Tool[];
-    platformOptions?: AdapterOptions;
-    messages: Msg[];
-    /** Maximum completion tokens for LLM response */
-    maxCompletionTokens?: number;
-}
-declare class Agent {
-    private config;
-    private messages;
-    private toolsMap;
-    /** Pending async tools: asyncCallId -> info */
-    private pendingAsyncTools;
-    constructor(config: AgentConfig);
-    /** Get agent name */
-    get name(): string;
-    /**
-     * Render template string, replacing {{variable}} style variables
-     */
-    static renderTemplate(template: string, variables: Record<string, string | number | boolean>): string;
     /**
-     * Check and add placeholder results for pending async tools
-     * Called before appending new user message
+     * Count tokens for a complete request (messages + tools)
+     * Uses openai-chat-tokens for accurate estimation
      */
-    private insertAsyncPlaceholders;
+    countTokens(_model: string, messages: Msg[], tools: Tool[]): number;
     /**
-     * Handle async tool completion
+     * Count tokens for plain text
+     * Uses tiktoken internally via openai-chat-tokens
      */
-    private handleAsyncToolComplete;
-    run(userInput: string): Promise<AgentResponse>;
-    reset(): this;
+    countTextTokens(_model: string, text: string): number;
 }
 
+/**
+ * Format messages array into text for summarization
+ * @param messages Array of messages to format
+ * @returns Formatted conversation text
+ */
+declare function formatMessagesForSummary(messages: Msg[]): string;
+/**
+ * Summarize messages using LLM
+ * @param adapter The adapter to use for LLM call
+ * @param model The model to use
+ * @param messages Messages to summarize (excluding system messages)
+ * @returns Summary string
+ */
+declare function summarizeMessages(adapter: Adapter, model: string, messages: Msg[]): Promise<string>;
+
 /**
  * All available model configurations (keyed by ID)
  */
@@ -466,4 +606,4 @@ interface Model {
     readonly capabilities: ModelCapabilities;
 }
 
-export { AIMsg, Adapter, type AdapterOptions, type AdapterResponse, Agent, type AgentModelConfig, type AgentResponse, type AgentType, AsyncToolResultMsg, type ColorName, type GlobalConfig, HAS_MANUAL, MODELS, type Model, type ModelCapabilities, type ModelProvider, Msg, MsgType, OS, type OS_TYPE, OpenAIAdapter, type OpenAIOptions, PATHS, PROCEDURES, type ReasoningEffort$1 as ReasoningEffort, SystemMsg, TOOLS, Tool, type ToolCall, ToolCallMsg, type ToolResult, ToolResultMsg, UserMsg, adapters, colors, convertColorTags, createColorConverter, debug, error, formatNumber, getAdapter, getAgentConfig, getApiKey, getConfig, getTimestamp, info, init, isDebugMode, log, print, saveConfig, setDebugMode, setWorkingDir, success, warn, workingDir };
+export { ADAPTERS, AGENTS, AIMsg, Adapter, type AdapterOptions, type AdapterResponse, Agent, type AgentConfig, type AgentModelConfig, type AgentResponse, type AgentType, AsyncToolResultMsg, type ColorName, type GlobalConfig, HAS_MANUAL, MODELS, type Model, type ModelCapabilities, type ModelProvider, Msg, MsgType, OS, type OS_TYPE, OpenAIAdapter, type OpenAIOptions, PATHS, PATH_VARS, PROCEDURES, type ReasoningEffort, SystemMsg, TOOLS, Tool, type ToolCall, ToolCallMsg, type ToolContext, type ToolResult, ToolResultMsg, UserMsg, colors, convertColorTags, createColorConverter, debug, error, expandPathVars, fileSystem, formatMessagesForSummary, formatNumber, getAgentConfig, getApiKey, getConfig, getTimestamp, info, init, isDebugMode, loadConfigs, log, print, saveConfig, setDebugMode, setWorkingDir, success, summarizeMessages, warn, workingDir };