@game_ryo/lsji 0.1.1 → 1.0.0

package/.github/ISSUE_TEMPLATE/good-first-issue-1.md

@@ -0,0 +1,62 @@
+---
+name: "Good First Issue: Add JSDoc comments to core RL classes"
+about: Improve code documentation for newcomers
+title: "[Docs] Add JSDoc comments to core RL classes (Agent, QLearning, Env)"
+labels: ["good first issue", "documentation", "help wanted"]
+assignees: ""
+---
+
+## Description
+
+The core RL classes (`Agent`, `QLearning`, `Env`) in `src/core/` are missing comprehensive JSDoc comments. This makes it harder for new contributors to understand the codebase.
+
+## Tasks
+
+- [ ] Add JSDoc comments to `src/core/agent.js` - all public methods
+- [ ] Add JSDoc comments to `src/core/qlearning.js` - all public methods  
+- [ ] Add JSDoc comments to `src/core/env.js` - interface and StateEncoder
+- [ ] Follow existing patterns in the codebase (see `src/storage/sqlite.js` for examples)
+
+## Files to Modify
+
+- `src/core/agent.js`
+- `src/core/qlearning.js`
+- `src/core/env.js`
+
+## Acceptance Criteria
+
+- [ ] All public methods have `@param`, `@returns`, and `@description` tags
+- [ ] Class-level `@description` explains purpose
+- [ ] Type annotations match actual implementation
+- [ ] Run `npm test` passes after changes
+
+## Getting Started
+
+```bash
+# 1. Fork and clone the repo
+git clone https://github.com/your-username/LSJI.git
+cd LSJI
+
+# 2. Install dependencies
+npm install
+
+# 3. Run tests to ensure baseline
+npm test
+
+# 4. Make your changes to the three files
+
+# 5. Run tests again
+npm test
+
+# 6. Submit PR!
+```
+
+## Resources
+
+- [JSDoc Guide](https://jsdoc.app/)
+- [TypeScript JSDoc Reference](https://www.typescriptlang.org/docs/handbook/jsdoc-supported-types.html)
+- Existing examples in `src/storage/sqlite.js`
+
+## Mentorship
+
+Happy to guide you through this! Tag @game_ryo in the PR for review.

package/.github/ISSUE_TEMPLATE/good-first-issue-2.md

@@ -0,0 +1,75 @@
+---
+name: "Good First Issue: Add unit tests for Budget Controller"
+about: Increase test coverage for budget control system
+title: "[Test] Add unit tests for TokenCounter, CostTracker, CircuitBreaker"
+labels: ["good first issue", "testing", "help wanted"]
+assignees: ""
+---
+
+## Description
+
+The budget control system (`src/execution/budget/`) has 3 core classes but limited test coverage. We need unit tests to ensure reliability.
+
+## Tasks
+
+- [ ] Create `test/execution/budget/token-counter.test.js`
+- [ ] Create `test/execution/budget/cost-tracker.test.js`
+- [ ] Create `test/execution/budget/circuit-breaker.test.js`
+- [ ] Test edge cases: limit exceeded, circuit breaker states, token counting accuracy
+
+## Files to Create
+
+- `test/execution/budget/token-counter.test.js`
+- `test/execution/budget/cost-tracker.test.js`
+- `test/execution/budget/circuit-breaker.test.js`
+
+## Test Scenarios to Cover
+
+### TokenCounter
+- [ ] Count tokens for different providers (OpenAI, Anthropic, Gemini)
+- [ ] Handle missing usage data gracefully
+- [ ] Aggregate tokens across multiple calls
+
+### CostTracker
+- [ ] Track cost per run, daily, monthly
+- [ ] Enforce limits correctly
+- [ ] Calculate USD costs per model
+- [ ] Reset run budget
+
+### CircuitBreaker
+- [ ] Closed → Open transition on failures
+- [ ] Half-open state behavior
+- [ ] Auto-close after success
+- [ ] Configurable threshold/timeout
+
+## Acceptance Criteria
+
+- [ ] All new tests pass: `npm test`
+- [ ] Coverage increases for budget module
+- [ ] Tests follow existing patterns (see `test/core/qlearning.test.js`)
+- [ ] No flaky tests
+
+## Getting Started
+
+```bash
+# 1. Look at existing test structure
+cat test/core/qlearning.test.js
+
+# 2. Examine the source files
+cat src/execution/budget/token-counter.js
+cat src/execution/budget/cost-tracker.js
+cat src/execution/budget/circuit-breaker.js
+
+# 3. Write tests using vitest
+# 4. Run: npm test
+```
+
+## Resources
+
+- [Vitest Documentation](https://vitest.dev/)
+- Budget system docs: `docs/docs/core-concepts.md#budget-control`
+- Source code in `src/execution/budget/`
+
+## Mentorship
+
+Tag @game_ryo for guidance on test design!

package/.github/ISSUE_TEMPLATE/good-first-issue-3.md

@@ -0,0 +1,101 @@
+---
+name: "Good First Issue: Add example plugin for GitHub integration"
+about: Create a useful example plugin for the community
+title: "[Plugin] Create example GitHub integration plugin"
+labels: ["good first issue", "plugin", "example", "help wanted"]
+assignees: ""
+---
+
+## Description
+
+Create an example plugin that demonstrates how to integrate with GitHub API (create issues, list repos, etc.). This will serve as a reference for plugin developers.
+
+## Tasks
+
+- [ ] Create `lsji-plugins/github.js` with GitHub API tools
+- [ ] Include at least 3 tools: `github_create_issue`, `github_list_repos`, `github_get_file`
+- [ ] Add proper `requiresApproval: true` for mutating operations
+- [ ] Add comprehensive JSDoc comments
+- [ ] Test with `lsji plugin load --path ./lsji-plugins`
+
+## Tools to Implement
+
+| Tool | Description | Approval |
+|------|-------------|----------|
+| `github_create_issue` | Create issue in a repo | Yes |
+| `github_list_repos` | List user/org repositories | No |
+| `github_get_file` | Get file contents from repo | No |
+| `github_search_code` | Search code across repos | No |
+
+## Requirements
+
+- Use `GITHUB_TOKEN` environment variable for auth
+- Handle API errors gracefully (return `{ error: "..." }`)
+- Follow plugin structure from `lsji-plugins/example.js`
+- Include parameter validation with JSON Schema
+
+## Example Structure
+
+```javascript
+// lsji-plugins/github.js
+export default {
+  name: 'github',
+  version: '1.0.0',
+  tools: {
+    github_create_issue: {
+      name: 'github_create_issue',
+      description: 'Create a GitHub issue',
+      category: 'github',
+      parameters: {
+        type: 'object',
+        properties: {
+          owner: { type: 'string' },
+          repo: { type: 'string' },
+          title: { type: 'string' },
+          body: { type: 'string' },
+          labels: { type: 'array', items: { type: 'string' } }
+        },
+        required: ['owner', 'repo', 'title']
+      },
+      requiresApproval: true,
+      async execute({ owner, repo, title, body, labels }) {
+        // Implementation here
+      }
+    }
+    // ... more tools
+  }
+};
+```
+
+## Acceptance Criteria
+
+- [ ] Plugin loads without errors
+- [ ] Tools appear in `lsji plugin list`
+- [ ] Can be used by agent: `lsji agent run --task "Create issue in my/repo" --provider gemini`
+- [ ] Proper error handling for missing token, API errors
+- [ ] Follows existing plugin patterns
+
+## Getting Started
+
+```bash
+# 1. Copy example plugin
+cp lsji-plugins/example.js lsji-plugins/github.js
+
+# 2. Edit with GitHub API calls
+# 3. Test loading
+lsji plugin load --path ./lsji-plugins
+
+# 4. Test with agent (needs GITHUB_TOKEN)
+export GITHUB_TOKEN="your-token"
+lsji agent run --task "Create test issue in my/repo" --provider gemini
+```
+
+## Resources
+
+- [GitHub REST API](https://docs.github.com/en/rest)
+- Plugin system docs: `docs/docs/plugins.md`
+- Example plugin: `lsji-plugins/example.js`
+
+## Mentorship
+
+Will review PR and help with API design! Tag @game_ryo.

package/.github/ISSUE_TEMPLATE/good-first-issue-4.md

@@ -0,0 +1,78 @@
+---
+name: "Good First Issue: Add web UI tests with Playwright"
+about: Add end-to-end tests for the control panel
+title: "[Test] Add Playwright E2E tests for web control panel"
+labels: ["good first issue", "testing", "ui", "help wanted"]
+assignees: ""
+---
+
+## Description
+
+The web control panel (`src/server/ui/`) has no automated tests. Add Playwright tests to verify critical user flows.
+
+## Tasks
+
+- [ ] Set up Playwright in `src/server/ui/` (add to package.json)
+- [ ] Create `test/ui/control-panel.spec.js`
+- [ ] Test critical flows:
+  - [ ] Page loads without errors
+  - [ ] Run list displays correctly
+  - [ ] "New Run" modal opens and submits
+  - [ ] Thought log updates in real-time (mock WebSocket)
+  - [ ] Approval queue shows pending items
+  - [ ] Approve/reject buttons work
+  - [ ] Budget panel displays data
+
+## Files to Create/Modify
+
+- `src/server/ui/package.json` - Add playwright dependency
+- `src/server/ui/playwright.config.js` - Config
+- `test/ui/control-panel.spec.js` - Main test file
+
+## Test Scenarios
+
+```javascript
+// Example test structure
+test('page loads and shows empty state', async ({ page }) => {
+  await page.goto('http://localhost:3456');
+  await expect(page.locator('text=No runs yet')).toBeVisible();
+});
+
+test('can create new run', async ({ page }) => {
+  await page.goto('http://localhost:3456');
+  await page.click('button:has-text("New Run")');
+  await page.fill('textarea', 'Test task');
+  await page.click('button:has-text("Start Run")');
+  await expect(page.locator('.run-item')).toBeVisible();
+});
+```
+
+## Acceptance Criteria
+
+- [ ] Playwright installed and configured
+- [ ] At least 5 meaningful tests
+- [ ] Tests run in CI (GitHub Actions)
+- [ ] Tests pass locally: `npm run test:ui`
+- [ ] No flaky tests
+
+## Getting Started
+
+```bash
+cd src/server/ui
+npm install -D @playwright/test
+npx playwright install chromium
+
+# Create test file and config
+# Run tests
+npx playwright test
+```
+
+## Resources
+
+- [Playwright Documentation](https://playwright.dev/)
+- UI source: `src/server/ui/src/App.jsx`
+- WebSocket events in `src/server/index.js`
+
+## Mentorship
+
+Happy to help with WebSocket mocking! Tag @game_ryo.

package/.github/ISSUE_TEMPLATE/good-first-issue-5.md

@@ -0,0 +1,81 @@
+---
+name: "Good First Issue: Improve CLI output formatting with colors"
+about: Make CLI output more readable with chalk/colors
+title: "[CLI] Add colored output and progress indicators"
+labels: ["good first issue", "cli", "ux", "help wanted"]
+assignees: ""
+---
+
+## Description
+
+The CLI output is currently plain text. Add colors, spinners, and better formatting using a lightweight library like `chalk` or `kleur`.
+
+## Tasks
+
+- [ ] Add `kleur` (zero-dependency, fast) to dependencies
+- [ ] Update `src/cli.js` output functions:
+  - [ ] Success messages → green
+  - [ ] Errors → red
+  - [ ] Warnings → yellow
+  - [ ] Info/debug → blue/cyan
+  - [ ] JSON output → syntax highlighted (optional)
+- [ ] Add spinner for long-running operations (train, agent run)
+- [ ] Add progress bar for training episodes
+
+## Files to Modify
+
+- `package.json` - Add `kleur` dependency
+- `src/cli.js` - Update `output()`, `main()`, and command handlers
+
+## Example Improvements
+
+```javascript
+import kleur from 'kleur';
+
+// Before
+console.log('Training complete:', result);
+
+// After
+console.log(kleur.green('✓ Training complete:'), result);
+
+// Spinner for long operations
+import { createSpinner } from 'kleur/colors';
+// Or use simple animation
+const spinner = ['⠋', '⠙', '⠹', '⠸', '⠼', '⠴', '⠦', '⠧', '⠇', '⠏'];
+```
+
+## Acceptance Criteria
+
+- [ ] `lsji train --episodes 100` shows colored output
+- [ ] Errors are clearly red
+- [ ] Success messages are green
+- [ ] Spinner shows during `agent run` and `train`
+- [ ] No performance regression
+- [ ] Works in CI (no TTY issues)
+- [ ] `npm test` passes
+
+## Getting Started
+
+```bash
+# 1. Add dependency
+npm install kleur
+
+# 2. Import in cli.js
+import kleur from 'kleur';
+
+# 3. Update output() function and command handlers
+# 4. Test each command
+lsji train --episodes 50
+lsji agent run --task "test" --provider local
+lsji status --json
+```
+
+## Resources
+
+- [kleur Documentation](https://github.com/lukeed/kleur) - Zero deps, fast
+- [CLI Best Practices](https://clig.dev/)
+- Current CLI: `src/cli.js`
+
+## Mentorship
+
+Simple but impactful! Tag @game_ryo for review.

package/README.md

@@ -1,102 +1,192 @@
-# LSJI
+# Language Service JavaScript Interface (LSJI)
 
-A general-purpose reinforcement learning agent framework implemented in Node.js.
+> **Antigravity-level agentic autonomy meets the ultimate simplicity of self-hosting.**
 
 [![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)
 [![Node.js](https://img.shields.io/badge/Node.js-%3E%3D22-green.svg)](https://nodejs.org/)
+[![npm](https://img.shields.io/npm/v/@game_ryo/lsji.svg)](https://www.npmjs.com/package/@game_ryo/lsji)
 
 ## Overview
 
-LSJI (Learning System for Just-In-time Intelligence) is a lightweight, dependency-minimal reinforcement learning framework designed to run on Node.js. It provides:
+**LSJI** (Language Service JavaScript Interface) is a production-grade framework for hosting AI agents with **zero infrastructure complexity**. Simply provide a Gemini API key (or OpenAI/Anthropic/local) and deploy autonomous agents with:
 
-- **Q-Learning Engine** with configurable learning rate, discount factor, and exploration rate
-- **Pluggable Storage** abstraction supporting `node:sqlite` (built-in), `better-sqlite3`, and in-memory JSON
-- **Environment Interface** for defining custom RL environments
-- **CLI** for training, playing, and inspecting agents
+- 🧠 **LLM Agent Runtime** — ReAct pattern with tools, memory, and streaming
+- 🛡️ **HITL (Human-in-the-Loop)** — Approval gates for sends, charges, code execution
+- 🔄 **Durability** — Checkpointing & recovery from any failure
+- ♻️ **Idempotency** — Duplicate prevention on retries
+- 💰 **Budget Controls** — Token/cost limits with circuit breaker
+- 🌐 **Web Control Panel** — Real-time thought logs, approval queue, budget monitoring
+- 🔌 **Plugin System** — Drop-in custom tools via `lsji-plugins/`
+- 💾 **Pluggable Storage** — `node:sqlite` (built-in), `better-sqlite3`, or in-memory
 
-Originally developed as a Cloudflare Workers-based Rock-Paper-Scissors AI, LSJI has been completely rearchitected as a platform-agnostic Node.js library suitable for ASF incubation.
+**Perfect for:** Self-hosted AI assistants, autonomous coding agents, research agents, workflow automation.
 
-## Installation
+## Quick Start (30 seconds)
 
 ```bash
+# Install
 npm install lsji
-# or for local development
-npm link
+
+# Set your API key (Gemini, OpenAI, or Anthropic)
+export GEMINI_API_KEY="your-gemini-key"
+# or: export OPENAI_API_KEY="your-openai-key"
+
+# Start the runtime server with web UI
+npx lsji serve
+
+# Open http://localhost:3456 — create runs, watch thought logs, approve actions
 ```
 
-## Quick Start
+## CLI Usage
 
 ```bash
-# Train an agent (200 episodes)
-lsji train --episodes 200
+# Runtime server with control panel
+lsji serve --port 3456              # Start server + UI
+lsji serve --no-ui                  # Headless mode
 
-# Play against the agent (0=Rock, 1=Scissors, 2=Paper)
-lsji play --hand 0
+# Agent operations
+lsji agent run --task "Write a report on AI trends" --provider gemini --model gemini-1.5-flash
+lsji agent run-durable --task "Analyze codebase" --workflow-id my-analysis
+
+# Budget & approvals
+lsji budget status --budgetId my-project
+lsji hitl list                       # Pending approvals
+lsji hitl approve --id <id> --reason "Approved"
 
-# Check status
-lsji status
+# Plugins
+lsji plugin list
+lsji plugin create --name my-tools   # Generate template
 
-# Start/stop the training loop
-lsji start
-lsji stop
+# RL (legacy)
+lsji train --episodes 500
+lsji play --hand 0
 ```
 
 ## Programmatic Usage
 
 ```javascript
-import { Agent, QLearning, MemoryStorage } from 'lsji';
-import { RockPaperScissorsEnv } from 'lsji/envs'; // Next phase
+import { createLLMAgent, startServer } from 'lsji';
+
+// Create an agent with full production features
+const agent = await createLLMAgent({
+  llm: { provider: 'gemini', model: 'gemini-1.5-flash', apiKey: process.env.GEMINI_API_KEY },
+  budget: { maxCostPerRun: 5, maxCostPerDay: 50 },
+  hitl: { enabled: true, defaultTimeout: 300000 }, // 5 min approval timeout
+  memory: { conversation: true, episodic: true, semantic: true },
+});
+
+const result = await agent.run("Research TypeScript best practices and create a summary");
+console.log(result.answer);
+
+// Or start the full runtime server
+const server = await startServer({ port: 3456 });
+// Visit http://localhost:3456 for the web control panel
+```
+
+## Web Control Panel
+
+When you run `lsji serve`, you get a real-time dashboard at **http://localhost:3456**:
+
+| Panel | Features |
+|-------|----------|
+| **Runs** | List active/completed runs, start new ones |
+| **Thought Log** | Stream agent's reasoning (💭 thoughts, ⚡ actions, 👁 observations) |
+| **Approval Queue** | One-click approve/reject for file writes, API calls, emails, code exec |
+| **Budget** | Real-time cost tracking with progress bars & circuit breaker status |
+| **Plugins** | View loaded custom tools |
 
-const storage = new MemoryStorage();
-const qlearning = new QLearning({ alpha: 0.1, gamma: 0.9, epsilon: 0.1, storage });
-const agent = new Agent(qlearning, storage);
+## Tool Plugin System
 
-// Train
-await agent.train({ episodes: 200 });
+Drop `.js` files in `lsji-plugins/` to extend agent capabilities:
 
-// Play
-const result = await agent.play(0); // 0 = Rock
-console.log(result); // { aiHand: 1, outcome: 'AI_WIN', ... }
+```javascript
+// lsji-plugins/my-tools.js
+export default {
+  name: 'my-tools',
+  version: '1.0.0',
+  tools: {
+    my_custom_action: {
+      name: 'my_custom_action',
+      description: 'Do something custom',
+      parameters: { type: 'object', properties: { input: { type: 'string' } }, required: ['input'] },
+      requiresApproval: false,
+      async execute({ input }) { return { result: `Processed: ${input}` }; }
+    }
+  }
+};
+```
+
+```bash
+lsji plugin list  # Shows: my-tools (1 tools)
 ```
 
 ## Architecture
 
 ```
 src/
-├── core/
-│   ├── env.js          # Environment interface
-│   ├── qlearning.js    # Q-Learning (TD) engine
-│   └── agent.js        # High-level agent orchestration
-├── storage/
-│   ├── index.js        # Storage interface
-│   ├── sqlite.js       # node:sqlite implementation
-│   ├── better-sqlite.js # better-sqlite3 implementation
-│   └── memory.js       # In-memory JSON implementation
-├── cli.js              # CLI commands
-└── index.js            # Public API exports
+├── core/              # RL foundations (Env, QLearning, Agent)
+├── storage/           # Pluggable backends (sqlite, better-sqlite3, memory)
+├── execution/         # Production systems
+│   ├── budget/        # TokenCounter, CostTracker, CircuitBreaker
+│   ├── hitl/          # ApprovalGate, ApprovalStore, Notifier
+│   ├── idempotency.js # Duplicate prevention
+│   └── engine.js      # Durable execution with checkpoints
+├── llm/               # LLM Agent Framework
+│   ├── providers/     # OpenAI, Anthropic, Local (Ollama), Gemini
+│   ├── llm-agent.js   # ReAct agent with tools & memory
+│   ├── tools/         # Built-in: web_search, file_read, file_write, code_exec, api_call, send_email, db_query
+│   ├── memory/        # Conversation, Semantic, Episodic
+│   ├── plugins/       # Dynamic plugin system
+│   └── prompt-manager.js
+├── server/            # Runtime server + Web UI
+│   ├── index.js       # Express + Socket.io
+│   └── ui/            # React + Vite control panel
+└── cli.js             # All commands
 ```
 
-## Storage Backends
+## LLM Providers
 
-| Backend | Package | Description |
-|---------|---------|-------------|
-| `sqlite` | `node:sqlite` | Built-in Node.js 22+, zero dependencies (recommended) |
-| `better-sqlite` | `better-sqlite3` | High-performance synchronous API |
-| `memory` | (built-in) | In-memory JSON, ideal for testing |
-
-```javascript
-import { SqliteStorage } from 'lsji/storage';
-const storage = new SqliteStorage('./data.db');
-```
+| Provider | Models | Setup |
+|----------|--------|-------|
+| **Gemini** | gemini-1.5-flash, gemini-1.5-pro, gemini-2.0-flash | `GEMINI_API_KEY` |
+| **OpenAI** | gpt-4o, gpt-4o-mini, gpt-4-turbo | `OPENAI_API_KEY` |
+| **Anthropic** | claude-3-5-sonnet, claude-3-opus, claude-3-haiku | `ANTHROPIC_API_KEY` |
+| **Local** | Any Ollama model | `OLLAMA_HOST` (default: http://localhost:11434) |
 
 ## Configuration
 
 Environment variables:
-- `LSJI_STORAGE` - Storage backend (`sqlite`, `better-sqlite`, `memory`, default: `sqlite`)
-- `LSJI_DB_PATH` - Database file path (default: `./lsji.db`)
+- `GEMINI_API_KEY` / `OPENAI_API_KEY` / `ANTHROPIC_API_KEY` — API keys
+- `LSJI_STORAGE` — Storage backend (`sqlite`, `better-sqlite`, `memory`, default: `sqlite`)
+- `LSJI_DB_PATH` — Database file path (default: `./lsji.db`)
+- `LSJI_SERVER_PORT` — Server port (default: `3456`)
+
+## Why LSJI for AI Agents?
+
+| Feature | Typical Agent Frameworks | LSJI |
+|---------|-------------------------|------|
+| Self-hosted | ❌ Often cloud-only | ✅ Single binary, zero deps |
+| HITL approvals | ❌ Manual or none | ✅ Built-in with web UI |
+| Durability | ❌ Lose state on crash | ✅ Checkpoint & resume |
+| Cost control | ❌ Unlimited spend | ✅ Budget + circuit breaker |
+| Idempotency | ❌ Your problem | ✅ Automatic |
+| Web UI | ❌ Separate project | ✅ Embedded, zero config |
+| Plugins | ❌ Complex SDK | ✅ Drop `.js` files |
+| Gemini support | ⚠️ Often missing | ✅ First-class |
+
+## Roadmap
+
+- [ ] **v0.4** — Multi-agent orchestration, A2A protocol
+- [ ] **v0.5** — WASM sandbox for code_exec, vector memory
+- [ ] **v1.0** — ASF incubation, stability guarantees
 
 ## License
 
-Apache License 2.0 - see [LICENSE](LICENSE) for details.
+Apache License 2.0 — see [LICENSE](LICENSE) for details.
 
 Copyright 2026 ryopc org
+
+---
+
+**Built for engineers who want agentic autonomy without the infrastructure burden.**  
+If you find LSJI useful, ⭐ the repo and consider sponsoring!