sparkecoder 0.1.3

package/README.md

@@ -0,0 +1,353 @@
+# Sparkecoder
+
+A powerful coding agent CLI with HTTP API. Built with the [Vercel AI SDK](https://sdk.vercel.ai).
+
+## Features
+
+- 🤖 **Multi-Agent Sessions** - Run multiple agents simultaneously with isolated contexts
+- 🔄 **Streaming Responses** - Real-time SSE streaming following Vercel AI SDK data stream protocol
+- 🔧 **Powerful Tools** - Bash execution, file operations, planning, and skill loading
+- ✅ **Tool Approvals** - Configurable approval requirements for dangerous operations
+- 📚 **Skills System** - Load specialized knowledge documents into context
+- 💾 **SQLite Persistence** - Full session and message history storage
+- 🌐 **HTTP API** - RESTful API with auto-generated OpenAPI specification via hono-openapi
+- 🎯 **Context Management** - Automatic summarization for long conversations
+
+## Installation
+
+### From GitHub Packages
+
+```bash
+# Configure npm to use GitHub Packages for @gostudyfetchgo scope
+npm config set @gostudyfetchgo:registry https://npm.pkg.github.com
+
+# Install the package (no auth required - it's public!)
+npm install @gostudyfetchgo/sparkecoder
+
+# Or with pnpm
+pnpm add @gostudyfetchgo/sparkecoder
+```
+
+### From Source
+
+```bash
+# Clone the repository
+git clone https://github.com/gostudyfetchgo/sparkecoder.git
+cd sparkecoder
+
+# Install dependencies
+pnpm install
+
+# Set up environment variables
+export AI_GATEWAY_API_KEY=your_api_key_here
+
+# Start the server
+pnpm dev
+```
+
+### Global CLI Installation
+
+```bash
+npm install -g @gostudyfetchgo/sparkecoder
+sparkecoder start
+```
+
+## Quick Start
+
+### Initialize Configuration
+
+```bash
+sparkecoder init
+```
+
+This creates a `sparkecoder.config.json` file with default settings.
+
+### Start the Server
+
+```bash
+sparkecoder start
+```
+
+The server runs at `http://localhost:3141` by default.
+
+### Make Your First Request
+
+```bash
+# Create a session and run a prompt
+curl -X POST http://localhost:3141/agents/quick \
+  -H "Content-Type: application/json" \
+  -d '{"prompt": "List the files in the current directory"}'
+```
+
+## API Reference
+
+### Sessions
+
+| Endpoint | Method | Description |
+|----------|--------|-------------|
+| `/sessions` | GET | List all sessions |
+| `/sessions` | POST | Create a new session |
+| `/sessions/:id` | GET | Get session details |
+| `/sessions/:id` | DELETE | Delete a session |
+| `/sessions/:id/messages` | GET | Get session messages |
+| `/sessions/:id/clear` | POST | Clear session context |
+
+### Agents
+
+| Endpoint | Method | Description |
+|----------|--------|-------------|
+| `/agents/:id/run` | POST | Run agent with streaming (SSE) |
+| `/agents/:id/generate` | POST | Run agent without streaming |
+| `/agents/:id/approve/:toolCallId` | POST | Approve pending tool |
+| `/agents/:id/reject/:toolCallId` | POST | Reject pending tool |
+| `/agents/:id/approvals` | GET | Get pending approvals |
+| `/agents/quick` | POST | Create session and run in one request |
+
+### OpenAPI
+
+Full OpenAPI specification available at `/openapi.json`.
+
+## Configuration
+
+Create a `sparkecoder.config.json` file:
+
+```json
+{
+  "defaultModel": "anthropic/claude-sonnet-4-20250514",
+  "workingDirectory": ".",
+  "toolApprovals": {
+    "bash": true,
+    "write_file": false,
+    "read_file": false
+  },
+  "skills": {
+    "directory": "./skills"
+  },
+  "context": {
+    "maxChars": 200000,
+    "autoSummarize": true
+  },
+  "server": {
+    "port": 3141,
+    "host": "127.0.0.1"
+  }
+}
+```
+
+### Configuration Options
+
+| Option | Description | Default |
+|--------|-------------|---------|
+| `defaultModel` | Vercel AI Gateway model string | `anthropic/claude-opus-4-5` |
+| `workingDirectory` | Base directory for file operations | Current directory |
+| `toolApprovals` | Which tools require user approval | `{ bash: true }` |
+| `skills.directory` | Directory containing skill files | `./skills` |
+| `context.maxChars` | Max context size before summarization | `200000` |
+| `context.autoSummarize` | Enable automatic summarization | `true` |
+| `server.port` | HTTP server port | `3141` |
+| `server.host` | HTTP server host | `127.0.0.1` |
+
+## Tools
+
+### bash
+Execute shell commands in the working directory.
+
+```json
+{
+  "command": "ls -la"
+}
+```
+
+### read_file
+Read file contents with optional line range.
+
+```json
+{
+  "path": "src/index.ts",
+  "startLine": 1,
+  "endLine": 50
+}
+```
+
+### write_file
+Write or edit files. Supports two modes:
+
+**Full write:**
+```json
+{
+  "path": "new-file.ts",
+  "mode": "full",
+  "content": "// New file content"
+}
+```
+
+**String replacement:**
+```json
+{
+  "path": "existing-file.ts",
+  "mode": "str_replace",
+  "old_string": "const x = 1;",
+  "new_string": "const x = 2;"
+}
+```
+
+### todo
+Manage task lists for complex operations.
+
+```json
+{
+  "action": "add",
+  "items": [
+    { "content": "Step 1: Analyze code" },
+    { "content": "Step 2: Implement fix" }
+  ]
+}
+```
+
+### load_skill
+Load specialized knowledge into context.
+
+```json
+{
+  "action": "load",
+  "skillName": "Debugging"
+}
+```
+
+## Skills
+
+Skills are markdown files with specialized knowledge. Place them in your skills directory:
+
+```markdown
+---
+name: My Custom Skill
+description: Description of what this skill provides
+---
+
+# My Custom Skill
+
+Detailed content that will be loaded into context...
+```
+
+Built-in skills:
+- **Debugging** - Systematic debugging approaches
+- **Code Review** - Code review checklists and best practices
+- **Refactoring** - Safe refactoring patterns and techniques
+
+## CLI Commands
+
+```bash
+sparkecoder start     # Start the HTTP server
+sparkecoder chat      # Interactive chat with the agent
+sparkecoder init      # Create config file
+sparkecoder sessions  # List all sessions
+sparkecoder status    # Check if server is running
+sparkecoder config    # Show current configuration
+sparkecoder info      # Show version and environment
+```
+
+### Interactive Chat
+
+Start an interactive chat session with the agent:
+
+```bash
+# Start a new chat session
+sparkecoder chat
+
+# Resume an existing session
+sparkecoder chat --session <session-id>
+
+# Start with custom options
+sparkecoder chat --name "My Project" --model "anthropic/claude-sonnet-4-20250514"
+```
+
+**In-chat commands:**
+- `/quit` or `/exit` - Exit the chat
+- `/clear` - Clear conversation history
+- `/session` - Show current session info
+- `/tools` - List available tools
+
+## Streaming Protocol
+
+The API uses Server-Sent Events (SSE) following the [Vercel AI SDK data stream protocol](https://sdk.vercel.ai/docs/ai-sdk-ui/stream-protocol).
+
+Compatible with `useChat` from `@ai-sdk/react`:
+
+```tsx
+import { useChat } from '@ai-sdk/react';
+
+const { messages, sendMessage } = useChat({
+  api: 'http://localhost:3141/agents/SESSION_ID/run',
+});
+```
+
+## Tool Approvals
+
+Configure which tools require approval:
+
+```json
+{
+  "toolApprovals": {
+    "bash": true,      // Requires approval
+    "write_file": true // Requires approval
+  }
+}
+```
+
+When approval is required:
+1. The agent pauses and streams an `approval-required` event
+2. Call `/agents/:id/approve/:toolCallId` to approve
+3. Call `/agents/:id/reject/:toolCallId` to reject
+
+## Environment Variables
+
+| Variable | Description |
+|----------|-------------|
+| `AI_GATEWAY_API_KEY` | Vercel AI Gateway API key (required) |
+| `SPARKECODER_MODEL` | Override default model |
+| `SPARKECODER_PORT` | Override server port |
+| `DATABASE_PATH` | Override database path |
+
+## Development
+
+```bash
+# Run in development mode with hot reload
+pnpm dev
+
+# Type check
+pnpm typecheck
+
+# Build for production
+pnpm build
+
+# Run production build
+pnpm start
+```
+
+## Testing
+
+Sparkecoder includes comprehensive end-to-end tests that make actual API calls to the LLM.
+
+```bash
+# Run all E2E tests (requires AI_GATEWAY_API_KEY)
+pnpm test:e2e
+
+# Run tests in watch mode
+pnpm test:watch
+```
+
+The tests cover:
+- Health & server endpoints
+- Session management (CRUD operations)
+- Agent text generation (streaming & non-streaming)
+- File operations (create, read, edit)
+- Bash command execution
+- Todo management
+- Multi-turn conversations with context
+- Tool approvals workflow
+
+**Note:** E2E tests require a valid `AI_GATEWAY_API_KEY` and will make real LLM calls. They create a temporary `.test-workspace` directory that is cleaned up after tests complete.
+
+## License
+
+Proprietary - All rights reserved.

package/dist/agent/index.d.ts

@@ -0,0 +1,5 @@
+import 'ai';
+import '../schema-EPbMMFza.js';
+export { A as Agent, a as AgentOptions, b as AgentRunOptions, c as AgentStreamResult, C as ContextManager, d as buildSystemPrompt } from '../index-BxpkHy7X.js';
+import 'drizzle-orm/sqlite-core';
+import 'zod';