arki 0.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 arki.moe
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,125 @@
+# Arki - AI Agent Programming Assistant
+
+Arki is an AI agent programming tool.
+
+## Installation
+
+### Via npm
+
+```bash
+npm install -g arki
+```
+
+### Via pnpm
+
+```bash
+pnpm install -g arki
+```
+
+### From source
+
+```bash
+git clone https://github.com/your-username/arki.git
+cd arki
+pnpm install
+pnpm build
+```
+
+## Usage
+
+```bash
+export OPENAI_API_KEY="your-api-key"
+arki
+```
+
+### Command Line Arguments
+
+```bash
+arki [options]
+
+Options:
+  -p <path>      Specify working directory
+  --debug, -d    Enable debug mode, show detailed logs
+  --help, -h     Show help information
+```
+
+Example:
+```bash
+# Start in specified directory with debug mode enabled
+arki -p /path/to/project --debug
+```
+
+### Supported Models
+
+- `gpt-5.2` - GPT-5.2
+- `gpt-5.1` - GPT-5.1
+- `gpt-5` - GPT-5
+- `gpt-5-nano` - GPT-5 Nano
+
+### Interactive Commands
+
+- `/exit` or `/quit` - Exit program
+- `/clear` - Clear conversation history
+- `/debug` - Toggle debug mode
+- `/help` - Show help
+
+### Debug Mode
+
+Debug mode outputs detailed runtime logs, including:
+- API request/response information (model, message count, elapsed time, tokens)
+- Agent run loop (rounds, message count)
+- Tool execution details (parameters, elapsed time, results)
+
+Ways to enable:
+1. Add `--debug` or `-d` parameter at startup
+2. Type `/debug` during runtime to toggle
+
+## Configuration File
+
+Configuration file is located at `~/.config/arki/config.json`:
+
+```json
+{
+  "agents": {
+    "main": {
+      "model": "gpt-5.1",
+      "flex": false,
+      "reasoningEffort": "medium"
+    },
+    "coder": {
+      "model": "gpt-5.2",
+      "flex": false,
+      "reasoningEffort": "high"
+    }
+  }
+}
+```
+
+Each Agent configuration:
+- `model` - Model ID to use
+- `flex` - Use Flex API (low priority, low cost)
+- `reasoningEffort` - Reasoning effort, optional values: `low`, `medium`, `high` (for models that support thinking mode)
+
+Default configuration is automatically copied from the package on first run.
+
+## Built-in Tools
+
+Arki includes the following built-in tools that the AI assistant can automatically call:
+
+- `read_file` - Read file content
+- `write_file` - Write to file
+- `list_directory` - List directory contents
+- `run_command` - Execute shell commands
+- `get_tool_info` - View detailed usage instructions for tools
+
+## Development
+
+```bash
+pnpm dev           # Development mode
+pnpm build         # Build
+pnpm typecheck     # Type checking
+pnpm test          # Run tests
+pnpm test:watch    # Watch mode testing
+pnpm test:coverage # Test coverage
+pnpm test:e2e      # E2E tests
+```

package/bin/arki.js

@@ -0,0 +1,4 @@
+#!/usr/bin/env node
+
+import('../dist/index.js');
+

package/dist/config/config.json

@@ -0,0 +1,14 @@
+{
+  "agents": {
+    "main": {
+      "model": "gpt-5.1",
+      "flex": true,
+      "reasoningEffort": "medium"
+    },
+    "coder": {
+      "model": "gpt-5.2",
+      "flex": true,
+      "reasoningEffort": "high"
+    }
+  }
+}

package/dist/index.d.ts

@@ -0,0 +1,355 @@
+#!/usr/bin/env node
+/**
+ * Message type enum (for type narrowing)
+ */
+declare enum MsgType {
+    System = "system",
+    User = "user",
+    AI = "ai",
+    ToolCall = "tool_call",
+    ToolResult = "tool_result"
+}
+/**
+ * Base message class
+ */
+declare abstract class Msg {
+    abstract readonly type: MsgType;
+    readonly timestamp: number;
+    readonly content: string;
+    constructor(content: string);
+}
+/**
+ * System message constructor
+ */
+declare class SystemMsg extends Msg {
+    readonly type = MsgType.System;
+    constructor(content: string);
+}
+/**
+ * User message constructor
+ */
+declare class UserMsg extends Msg {
+    readonly type = MsgType.User;
+    constructor(content: string);
+}
+/**
+ * AI message constructor
+ */
+declare class AIMsg extends Msg {
+    readonly type = MsgType.AI;
+    constructor(content: string);
+}
+/**
+ * Tool call message constructor
+ */
+declare class ToolCallMsg extends Msg {
+    readonly type = MsgType.ToolCall;
+    readonly toolCalls: Array<{
+        name: string;
+        arguments: Record<string, unknown>;
+    }>;
+    constructor(content: string, toolCalls: Array<{
+        name: string;
+        arguments: Record<string, unknown>;
+    }>);
+}
+/**
+ * Tool result message constructor
+ */
+declare class ToolResultMsg extends Msg {
+    readonly type = MsgType.ToolResult;
+    readonly toolName: string;
+    readonly result: string;
+    readonly isError?: boolean;
+    constructor(toolName: string, result: string, isError?: boolean);
+}
+
+/**
+ * Tool class
+ */
+declare class Tool {
+    readonly name: string;
+    readonly description: string;
+    readonly parameters: Record<string, unknown>;
+    readonly required: string[];
+    readonly manual: string;
+    private readonly _execute;
+    constructor(config: {
+        name: string;
+        parameters: Record<string, unknown>;
+        required: string[];
+        manualContent: string;
+        execute: (args: Record<string, unknown>) => Promise<string | {
+            content: string;
+            isError?: boolean;
+        }>;
+    });
+    /**
+     * Parse manual.md content
+     * First line format: "tool_name: description", extract description
+     * Remaining content is the manual
+     */
+    static parseManual(content: string): {
+        description: string;
+        manual: string;
+    };
+    /**
+     * Execute tool (with error handling and logging)
+     */
+    run(args: Record<string, unknown>): Promise<ToolResultMsg>;
+}
+
+/**
+ * Fixed parameters
+ */
+declare const TEMPERATURE = 0.2;
+declare const MAX_COMPLETION_TOKENS = 4096;
+/**
+ * Reasoning effort
+ */
+type ReasoningEffort$1 = 'low' | 'medium' | 'high';
+/**
+ * LLM response result
+ */
+interface AdapterResponse {
+    message: Msg;
+    hasToolCalls: boolean;
+    usage?: {
+        promptTokens: number;
+        completionTokens: number;
+        totalTokens: number;
+        cachedTokens?: number;
+    };
+}
+/**
+ * LLM adapter base class
+ */
+declare abstract class Adapter {
+    protected apiKey: string;
+    protected model: string;
+    /** Use Flex API (OpenAI) - low priority, low cost */
+    protected flex?: boolean;
+    /** Reasoning effort (thinking mode) */
+    protected reasoningEffort?: ReasoningEffort$1;
+    /** Available tools list */
+    protected tools?: Tool[];
+    constructor(config: {
+        apiKey: string;
+        model: string;
+        /** Use Flex API (OpenAI) - low priority, low cost */
+        flex?: boolean;
+        /** Reasoning effort (thinking mode) */
+        reasoningEffort?: ReasoningEffort$1;
+        /** Available tools list */
+        tools?: Tool[];
+    });
+    abstract chat(messages: Msg[], onChunk?: (chunk: string) => void): Promise<AdapterResponse>;
+    getModel(): string;
+}
+
+/**
+ * Agent type
+ */
+type AgentType = 'main' | 'coder';
+/**
+ * Reasoning effort
+ */
+type ReasoningEffort = 'low' | 'medium' | 'high';
+/**
+ * Agent model configuration
+ */
+interface AgentModelConfig {
+    /** Model ID */
+    model: string;
+    /** Use Flex API (low priority, low cost) */
+    flex?: boolean;
+    /** Reasoning effort (thinking mode) */
+    reasoningEffort?: ReasoningEffort;
+}
+/**
+ * Global configuration
+ */
+interface GlobalConfig {
+    apiKeys?: {
+        openai?: string;
+        anthropic?: string;
+        google?: string;
+        [key: string]: string | undefined;
+    };
+    agents: {
+        [K in AgentType]?: AgentModelConfig;
+    };
+}
+/**
+ * Global configuration manager
+ */
+declare class ConfigManager {
+    private config;
+    private loaded;
+    /**
+     * Load configuration (called at program startup)
+     */
+    load(): Promise<GlobalConfig>;
+    /**
+     * Save configuration
+     */
+    save(): Promise<void>;
+    get(): GlobalConfig;
+    getApiKey(provider: string): string | undefined;
+    getAgentConfig(agentType: AgentType): AgentModelConfig;
+    private loadEnvApiKeys;
+}
+declare const config: ConfigManager;
+
+/** Working directory */
+declare let workingDir: string;
+/** Set working directory (for testing) */
+declare function setWorkingDir(dir: string): void;
+/** Global tool registry */
+declare const TOOLS: Record<string, Tool>;
+/** Global Adapter instance */
+declare let adapter: Adapter | null;
+/** Initialize global state */
+declare function init(cwd?: string): Promise<void>;
+
+/**
+ * Debug logging module
+ */
+/** Get debug mode status */
+declare function isDebugMode(): boolean;
+/** Set debug mode */
+declare function setDebugMode(enabled: boolean): void;
+/**
+ * Debug log function
+ * @param category Log category (e.g., 'API', 'Agent', 'Tool')
+ * @param message Log message
+ * @param data Optional additional data
+ */
+declare function debug(category: string, message: string, data?: unknown): void;
+
+/**
+ * General logging module
+ */
+
+/**
+ * Colored log output
+ * @param color Color name
+ * @param args Content to output
+ */
+declare function log(color: ColorName, ...args: unknown[]): void;
+/**
+ * Info log
+ */
+declare function info(message: string): void;
+/**
+ * Success log
+ */
+declare function success(message: string): void;
+/**
+ * Warning log
+ */
+declare function warn(message: string): void;
+/**
+ * Error log
+ */
+declare function error(message: string): void;
+
+/**
+ * Logging module
+ * Provides debug mode and logging functionality
+ */
+/**
+ * Terminal colors and style definitions
+ */
+declare const colors: {
+    reset: string;
+    bold: string;
+    dim: string;
+    italic: string;
+    underline: string;
+    inverse: string;
+    strikethrough: string;
+    red: string;
+    green: string;
+    yellow: string;
+    blue: string;
+    magenta: string;
+    cyan: string;
+    gray: string;
+};
+/** Color name type */
+type ColorName = keyof typeof colors;
+
+declare class OpenAIAdapter extends Adapter {
+    private client;
+    constructor(config: {
+        apiKey: string;
+        model: string;
+        flex?: boolean;
+        reasoningEffort?: 'low' | 'medium' | 'high';
+        tools?: Tool[];
+    });
+    private toOpenAIMessages;
+    private getTools;
+    chat(messages: Msg[], 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;
+    };
+}
+declare class Agent {
+    private config;
+    private messages;
+    constructor(config: {
+        adapter: Adapter;
+        messages: Msg[];
+        onStream?: (chunk: string) => void;
+        onToolCallMsg?: (msg: ToolCallMsg) => void;
+        onToolResult?: (name: string, result: string) => void;
+    });
+    /**
+     * Render template string, replacing {{variable}} style variables
+     */
+    static renderTemplate(template: string, variables: Record<string, string | number | boolean>): string;
+    run(userInput: string): Promise<AgentResponse>;
+    reset(): this;
+}
+
+/**
+ * All available model configurations (keyed by ID)
+ */
+declare const MODELS: Record<string, Model>;
+
+/**
+ * Model provider type
+ */
+type ModelProvider = 'openai' | 'anthropic' | 'google' | 'deepseek' | 'custom';
+/**
+ * Model capabilities
+ */
+interface ModelCapabilities {
+    streaming: boolean;
+    vision: boolean;
+    contextWindow: number;
+}
+/**
+ * Model interface
+ */
+interface Model {
+    readonly name: string;
+    readonly provider: ModelProvider;
+    readonly capabilities: ModelCapabilities;
+}
+
+export { AIMsg, Adapter, type AdapterResponse, Agent, type AgentResponse, type ColorName, MAX_COMPLETION_TOKENS, MODELS, type Model, type ModelCapabilities, type ModelProvider, Msg, MsgType, OpenAIAdapter, type ReasoningEffort$1 as ReasoningEffort, SystemMsg, TEMPERATURE, TOOLS, Tool, ToolCallMsg, ToolResultMsg, UserMsg, adapter, colors, config, debug, error, info, init, isDebugMode, log, setDebugMode, setWorkingDir, success, warn, workingDir };