notsleep 1.0.0

package/.env.example

@@ -0,0 +1,117 @@
+# ╔══════════════════════════════════════════════════════════╗
+# ║           NotSleep Configuration                        ║
+# ╚══════════════════════════════════════════════════════════╝
+#
+# Copy file ini jadi .env lalu isi sesuai kebutuhan:
+#   copy .env.example .env
+#
+
+# ─── Provider ────────────────────────────────────────────
+# Pilih: "openai" atau "anthropic"
+NOTSLEEP_PROVIDER=openai
+
+# ─── OpenAI ──────────────────────────────────────────────
+OPENAI_API_KEY=sk-...
+OPENAI_MODEL=gpt-4o
+# Custom base URL (untuk Azure, local proxy, LM Studio, Ollama, dll)
+# OPENAI_BASE_URL=https://api.openai.com/v1
+
+# ─── Anthropic ───────────────────────────────────────────
+ANTHROPIC_API_KEY=sk-ant-...
+ANTHROPIC_MODEL=claude-sonnet-4-20250514
+# ANTHROPIC_BASE_URL=https://api.anthropic.com
+
+# ─── Registry model (gaya OpenCode / models.dev) ─────────
+# Alih-alih pilih provider + model terpisah, cukup satu string "provider/model".
+# NotSleep sudah punya baseURL bawaan untuk provider populer di bawah — kamu
+# tinggal isi API key-nya. Aktifkan dengan NOTSLEEP_MODEL atau field "model"
+# di notsleep.json, atau flag --model provider/model.
+# NOTSLEEP_MODEL=groq/llama-3.3-70b-versatile
+#
+# Model murah untuk kerja internal agent (summarize context, generate task).
+# Bisa "provider/model" atau id polos (pakai kredensial provider utama).
+# NOTSLEEP_SMALL_MODEL=groq/llama-3.1-8b-instant
+#
+# Provider bawaan (isi key yang relevan saja):
+#   openai/...       OPENAI_API_KEY
+#   anthropic/...    ANTHROPIC_API_KEY   (SDK native)
+#   openrouter/...   OPENROUTER_API_KEY  (mis. openrouter/anthropic/claude-3.5-sonnet)
+#   groq/...         GROQ_API_KEY
+#   deepseek/...     DEEPSEEK_API_KEY
+#   together/...     TOGETHER_API_KEY
+#   xai/...          XAI_API_KEY
+#   fireworks/...    FIREWORKS_API_KEY
+#   mistral/...      MISTRAL_API_KEY
+#   perplexity/...   PERPLEXITY_API_KEY
+#   gemini/...       GEMINI_API_KEY
+#   ollama/...       (lokal, tanpa key)
+#   limitrouter/...  OPENAI_API_KEY
+# GROQ_API_KEY=gsk-...
+# OPENROUTER_API_KEY=sk-or-...
+
+# ─── Agent Behavior ─────────────────────────────────────
+# Max loop iterations sebelum agent berhenti paksa
+NOTSLEEP_MAX_ITERATIONS=1000
+
+# Continuous mode: setelah 1 task selesai, otomatis lanjut task berikutnya
+# true = agent tidak berhenti sampai queue kosong / kamu stop manual
+# false = agent berhenti setelah 1 task selesai
+NOTSLEEP_CONTINUOUS=false
+
+# ─── Context Window Management ──────────────────────────
+# Batas token context window. KOSONGKAN / 0 = auto-detect dari model.
+# Auto-detect sync live dari models.dev (di-cache 24 jam), fallback ke
+# endpoint /models provider, lalu ke tabel statis. Isi manual hanya kalau
+# mau override.
+# NOTSLEEP_CONTEXT_WINDOW_LIMIT=120000
+#
+# Matikan sync jaringan model metadata (offline / air-gapped): pakai cache
+# atau tabel statis saja.
+# NOTSLEEP_NO_MODEL_SYNC=1
+
+# Kapan mulai summarize (0.75 = kalau context sudah 75% penuh)
+NOTSLEEP_SUMMARIZE_THRESHOLD=0.75
+
+# ─── Error Handling ─────────────────────────────────────
+# Max retry kalau API error (rate limit, server error, network)
+NOTSLEEP_MAX_RETRIES=10
+
+# Base delay untuk exponential backoff (ms)
+NOTSLEEP_RETRY_BASE_DELAY_MS=1000
+
+# Timeout untuk tool execution (ms) - default 2 menit
+NOTSLEEP_TOOL_TIMEOUT_MS=120000
+
+# ─── Web Dashboard ──────────────────────────────────────
+# Aktifkan dashboard otomatis tanpa flag --ui
+# NOTSLEEP_DASHBOARD=true
+# Port untuk web dashboard (aktifkan dengan --ui)
+NOTSLEEP_DASHBOARD_PORT=3120
+
+# ─── Storage ────────────────────────────────────────────
+# Folder untuk simpan checkpoint (crash recovery)
+NOTSLEEP_CHECKPOINT_DIR=.notsleep/checkpoints
+
+# Folder untuk simpan log files
+NOTSLEEP_LOG_DIR=.notsleep/logs
+
+# File yang kalau dibuat, agent akan berhenti
+# Cara stop: echo. > .notsleep/STOP
+NOTSLEEP_STOP_FILE=.notsleep/STOP
+
+# ─── Config File (alternatif .env) ──────────────────────
+# Selain .env, kamu bisa pakai file JSON: notsleep.json (project)
+# atau ~/.notsleep/config.json (global). Bikin dengan wizard:
+#   notsleep init            # bikin notsleep.json di project ini
+#   notsleep init --global   # bikin config global
+#   notsleep config          # lihat config final + sumbernya
+#
+# Prioritas (yang atas menang):
+#   1. CLI flags (--model, --provider, dst)
+#   2. notsleep.json (project)
+#   3. ~/.notsleep/config.json (global)
+#   4. .env / environment
+#   5. default bawaan
+#
+# Di notsleep.json, API key bisa pakai referensi env biar aman:
+#   "apiKey": "{env:OPENAI_API_KEY}"

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 yudarmd
+
+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,341 @@
+# NotSleep
+
+[![CI](https://github.com/yudarmd/notsleep-agent/actions/workflows/ci.yml/badge.svg)](https://github.com/yudarmd/notsleep-agent/actions/workflows/ci.yml)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+[![Node](https://img.shields.io/badge/node-%3E%3D18-brightgreen)](package.json)
+
+**Long-horizon autonomous AI agent - "Do not stop until I woke up"**
+
+An AI agent that runs autonomously for hours or days, managing its own context window, checkpointing progress, retrying on failures, and never stopping until the task is fully complete. Compatible with both OpenAI and Anthropic APIs.
+
+> ### ⚠️ Safety first — read before running
+>
+> NotSleep is **autonomous**: it runs shell commands, reads/writes files, and
+> fetches URLs on its own, in a loop, without asking for approval. In-code
+> guards ([`src/safety.ts`](src/safety.ts)) confine file writes to the workspace
+> and block destructive commands, but they reduce risk rather than eliminate it.
+>
+> - Run untrusted or open-ended tasks in a **sandbox / container / VM**.
+> - Use a **dedicated API key** and a budget (`--max-cost`) — autonomous runs
+>   can be expensive.
+> - Keep the **dashboard local** (it has no auth; binds to `127.0.0.1`).
+>
+> See [SECURITY.md](SECURITY.md) for the full security model and how to report
+> vulnerabilities.
+
+## Features
+
+- **Dual Provider Support** - OpenAI (GPT-4o, o1, etc.) and Anthropic (Claude) with a unified interface
+- **Long-Horizon Execution** - Automatic context window management with summarization when context gets full
+- **Crash Recovery** - Periodic checkpoints to disk; resume from where you left off after a crash
+- **Resilient Retries** - Exponential backoff with jitter, rate-limit awareness, Retry-After header support
+- **Built-in Tools** - Shell execution, file read/write/edit, directory listing, file search, web fetch
+- **Extensible** - Add custom tools via the programmatic API
+- **Progress Tracking** - Real-time progress bar, elapsed time, token usage, iteration count
+- **Full Logging** - Every action logged to disk with timestamps
+
+## Quick Start
+
+```bash
+# Install dependencies
+npm install
+
+# Build
+npm run build
+
+# Configure (copy and edit)
+cp .env.example .env
+# Edit .env with your API keys
+
+# Run with a task
+npm start -- "Build a REST API with Express, add user auth, and write tests"
+
+# Or use dev mode (no build needed)
+npm run dev -- "Refactor all callbacks to async/await in the src directory"
+```
+
+## CLI Usage
+
+```bash
+# Basic usage
+notsleep "Your task description here"
+
+# Use Anthropic instead of OpenAI
+notsleep --provider anthropic "Your task"
+
+# Specify model
+notsleep --model gpt-4o "Your task"
+
+# Resume from last checkpoint
+notsleep --resume
+
+# Read task from a file
+notsleep --task-file task.md
+
+# Custom system prompt
+notsleep --system-prompt-file system.md "Your task"
+
+# Pass API key directly
+notsleep --openai-key sk-... "Your task"
+
+# Custom base URL (Azure, local proxy, etc.)
+notsleep --base-url http://localhost:8080/v1 "Your task"
+
+# Verbose mode
+notsleep --verbose "Your task"
+
+# Set max iterations
+notsleep --max-iterations 500 "Your task"
+
+# ─── Config management ───
+# Create a project config file (interactive wizard)
+notsleep init
+
+# Create a global config (~/.notsleep/config.json)
+notsleep init --global
+
+# Non-interactive: write sensible defaults
+notsleep init --yes
+
+# Show the resolved config and where each value came from
+notsleep config
+```
+
+## Configuration
+
+You can configure NotSleep three ways: a **config file** (`notsleep.json`),
+a **`.env` file**, or **CLI flags**. They merge together, highest priority wins:
+
+```
+1. CLI flags            (--model, --provider, ...)   ← highest
+2. notsleep.json        (project, searched upward)
+3. ~/.notsleep/config.json  (global user defaults)
+4. .env / environment
+5. built-in defaults                                 ← lowest
+```
+
+### Config file (`notsleep.json`)
+
+Run `notsleep init` to generate one. Example:
+
+```json
+{
+  "$schema": "https://notsleep.dev/config-schema.json",
+  "provider": "openai",
+  "openai": {
+    "apiKey": "{env:OPENAI_API_KEY}",
+    "model": "gpt-4o"
+  },
+  "anthropic": {
+    "apiKey": "{env:ANTHROPIC_API_KEY}",
+    "model": "claude-sonnet-4-20250514"
+  },
+  "maxIterations": 1000,
+  "contextWindowLimit": 120000,
+  "continuous": false,
+  "dashboard": { "enabled": false, "port": 3120 }
+}
+```
+
+### Registry models — `provider/model` (OpenCode / models.dev style)
+
+Instead of the separate `provider` + `openai`/`anthropic` blocks, you can pick a
+model with a single unified string. NotSleep ships baseURLs for popular
+providers, so you only supply an API key:
+
+```json
+{
+  "model": "groq/llama-3.3-70b-versatile",
+  "providers": {
+    "groq": { "apiKey": "{env:GROQ_API_KEY}" },
+    "myproxy": {
+      "baseURL": "https://limitrouter.com/v1",
+      "apiKey": "{env:OPENAI_API_KEY}"
+    }
+  }
+}
+```
+
+- `model` is `"<provider>/<modelId>"`. The model id may itself contain slashes
+  (e.g. `"openrouter/anthropic/claude-3.5-sonnet"`).
+- Built-in providers: `openai, anthropic, openrouter, groq, deepseek, together,
+  xai, fireworks, mistral, perplexity, gemini, ollama, limitrouter`. For known
+  ones you only need the key; the key is read from that provider's env var
+  automatically (`GROQ_API_KEY`, `OPENROUTER_API_KEY`, …) unless you set one in
+  `providers`.
+- Define any **new** provider under `providers` with its `baseURL` + `apiKey`
+  (and optional `type`, default `openai`). Almost every provider is
+  OpenAI-compatible; only `anthropic`-type uses the native SDK.
+- Works on the CLI too: `notsleep --model openrouter/anthropic/claude-3.5-sonnet "..."`.
+
+The legacy `provider` + blocks still work; `model` simply takes precedence when
+present.
+
+### A cheaper model for internal work — `small_model`
+
+The agent makes internal calls of its own — summarizing context when it fills
+up, and generating follow-up tasks in continuous mode. Point those at a cheaper
+model so they don't burn your primary one (OpenCode-style):
+
+```json
+{
+  "model": "anthropic/claude-sonnet-4-20250514",
+  "small_model": "anthropic/claude-3-5-haiku"
+}
+```
+
+`small_model` accepts a `provider/model` ref (its own provider/creds) **or** a
+bare model id, which reuses the primary provider's key + base URL (e.g. primary
+`gpt-4o`, `small_model: "gpt-4o-mini"`). CLI: `--small-model`. Unset → internal
+calls use the primary model.
+
+### Config ergonomics — JSONC, file refs, instructions, schema
+
+- **Comments + trailing commas (JSONC):** `notsleep.json` may contain `//` and
+  `/* */` comments and trailing commas.
+- **`{file:./path}` references:** any string value can inline a file's contents,
+  resolved relative to the config, e.g. `"systemPrompt": "{file:./prompt.md}"`.
+- **`instructions` + auto-loaded `AGENTS.md`:** list instruction files whose
+  contents are appended to the system prompt; `AGENTS.md` / `NOTSLEEP.md` in the
+  project root are picked up automatically (the emerging cross-agent standard).
+
+  ```json
+  { "instructions": ["./docs/style.md"] }
+  ```
+- **IDE autocomplete, fully offline:** `notsleep init` writes a local
+  `notsleep.schema.json` beside the config and points `$schema` at it (no hosted
+  URL). Regenerate anytime with `notsleep schema`.
+
+### Context window — live-synced with the API
+
+The agent decides when to summarize from a ratio: **current tokens ÷ window
+limit**. The numerator is already the *real* `prompt_tokens` the API reports on
+every call. The denominator (the model's max window) is resolved live, in three
+layers, so it stays right even for brand-new models:
+
+1. **models.dev** — the `models.dev/api.json` catalog (the same source OpenCode
+   uses) is fetched once, cached to `~/.notsleep/models.dev.json` (24h TTL), and
+   gives the exact context window + pricing for ~all providers/models.
+2. **`/models` endpoint** — for a custom proxy or a model the catalog doesn't
+   list, the provider's own OpenAI-style `GET /models` is queried for
+   `context_length`.
+3. **static table** — a built-in offline fallback (in `cost.ts`) when both are
+   unavailable.
+
+On top of that, if a request is ever rejected for exceeding the window, the
+agent reads the true maximum out of the provider's error, shrinks its limit, and
+summarizes — self-correcting even if every source above was wrong.
+
+`notsleep config` shows the resolved limit and where it came from
+(`models.dev` / `/models endpoint` / `static table` / `set`). Set
+`contextWindowLimit` in config to pin it manually, or `NOTSLEEP_NO_MODEL_SYNC=1`
+to disable the network sync entirely (offline / air-gapped use).
+
+The config file is searched from the current directory **upward**, so it works
+from any subfolder of your project (like `.git` or `package.json`).
+
+**Keep secrets out of the file** with `{env:VAR}` references. `"{env:OPENAI_API_KEY}"`
+reads from your environment / `.env` at runtime, so the config is safe to commit.
+You can also reference a system prompt from disk with `"systemPromptFile": "prompt.md"`.
+
+### `.env` variables
+
+All settings can also be configured via `.env` file or CLI flags:
+
+| Variable | Default | Description |
+|---|---|---|
+| `NOTSLEEP_PROVIDER` | `openai` | LLM provider (`openai` or `anthropic`) |
+| `OPENAI_API_KEY` | - | Your OpenAI API key |
+| `OPENAI_MODEL` | `gpt-4o` | OpenAI model to use |
+| `OPENAI_BASE_URL` | - | Custom base URL for OpenAI-compatible APIs |
+| `ANTHROPIC_API_KEY` | - | Your Anthropic API key |
+| `ANTHROPIC_MODEL` | `claude-sonnet-4-20250514` | Anthropic model to use |
+| `NOTSLEEP_MAX_ITERATIONS` | `1000` | Maximum agent loop iterations |
+| `NOTSLEEP_CONTEXT_WINDOW_LIMIT` | `120000` | Context window size in tokens |
+| `NOTSLEEP_SUMMARIZE_THRESHOLD` | `0.75` | Summarize when context reaches this % |
+| `NOTSLEEP_MAX_RETRIES` | `10` | Max retries on transient errors |
+| `NOTSLEEP_RETRY_BASE_DELAY_MS` | `1000` | Base delay for exponential backoff |
+| `NOTSLEEP_TOOL_TIMEOUT_MS` | `120000` | Timeout for tool execution |
+
+## Programmatic API
+
+```typescript
+import { Agent, loadConfig, Logger, LogLevel } from 'notsleep/api';
+
+const config = loadConfig({
+  provider: 'openai',
+  openai: { apiKey: 'sk-...', model: 'gpt-4o' },
+  maxIterations: 100,
+});
+
+const logger = new Logger('.notsleep/logs', LogLevel.INFO);
+const agent = new Agent(config, logger);
+
+// Add custom tools
+agent.addTool({
+  name: 'my_tool',
+  description: 'Does something custom',
+  parameters: {
+    type: 'object',
+    properties: { input: { type: 'string' } },
+    required: ['input'],
+  },
+  execute: async (args) => {
+    return `Result for ${args.input}`;
+  },
+});
+
+// Run the agent
+const result = await agent.run('Build and deploy the application');
+console.log(result.success, result.summary, result.stats);
+```
+
+## Built-in Tools
+
+| Tool | Description |
+|---|---|
+| `shell` | Execute shell commands (bash/powershell) |
+| `read_file` | Read file contents with line numbers |
+| `write_file` | Create or overwrite files |
+| `edit_file` | Search-and-replace edits in files |
+| `list_dir` | List directory contents |
+| `search_files` | Grep/regex search across files |
+| `web_fetch` | Fetch content from URLs |
+| `think` | Scratchpad for reasoning and planning |
+| `task_complete` | Signal that the task is done |
+
+## How Long-Horizon Works
+
+1. **Iterative Loop**: The agent calls the LLM, processes tool calls, and repeats
+2. **Context Management**: When the conversation approaches the context limit (~75%), the agent summarizes all progress into a compressed report and starts fresh with that summary
+3. **Checkpointing**: Every 5 iterations, the full state is saved to disk. If the process crashes, use `--resume` to continue
+4. **Error Recovery**: Transient API errors (429, 500, network) are retried with exponential backoff. Tool errors are fed back to the agent so it can self-correct
+5. **Completion**: The agent runs until it calls `task_complete` or hits the iteration limit
+
+## Architecture
+
+```
+src/
+  index.ts        - CLI entry point
+  api.ts          - Public programmatic API exports
+  types.ts        - TypeScript type definitions
+  config.ts       - Configuration loader (merges file + .env + CLI args)
+  fileconfig.ts   - notsleep.json loader, env-ref resolver, merge logic
+  init.ts         - `notsleep init` interactive setup wizard
+  provider.ts     - Unified LLM provider (OpenAI + Anthropic)
+  agent.ts        - Core agent loop (the brain)
+  tools.ts        - Built-in tool definitions
+  checkpoint.ts   - Checkpoint save/load for crash recovery
+  logger.ts       - Structured logging with colors
+```
+
+## Contributing
+
+Contributions are welcome! See [CONTRIBUTING.md](CONTRIBUTING.md) for setup,
+build/test commands, and the PR process, and please follow our
+[Code of Conduct](CODE_OF_CONDUCT.md). Changes are tracked in
+[CHANGELOG.md](CHANGELOG.md).
+
+## License
+
+[MIT](LICENSE) © yudarmd