@matthias-hausberger/beige 0.1.0 → 0.1.1

package/README.md

@@ -1,210 +1,146 @@
-# Beige
-
 Secure, sandboxed agent system. Let agents write and execute code — safely.
 
-**📚 [Documentation](https://beige.mintlify.app)** — Full docs at beige.mintlify.app
+**[Documentation](https://beige.mintlify.app)** — Full docs at beige.mintlify.app
 
-## What is Beige?
+---
 
-Beige is an open-source agent gateway that runs AI agents inside Docker sandboxes. Agents have 4 core tools (`read`, `write`, `patch`, `exec`) and can use additional tools exposed as executables. All tool calls route through the gateway for policy enforcement and audit logging.
+## Why Beige?
 
-**Key principles:**
-- 🔒 **Sandboxed** — Every agent runs in its own Docker container. No access to host env vars, secrets, or files.
-- 📋 **Audited** — Every tool call is logged with agent identity, args, timing, and permission decision.
-- 🛡️ **Policy-enforced** — Deny by default. Agents can only use tools explicitly granted in config.
-- 🔌 **Extensible** — Add tools as simple packages. They mount into sandboxes read-only.
-- 🤖 **LLM-agnostic** — Uses [pi SDK](https://pi.dev) for LLM interaction. Supports Anthropic, OpenAI, ZAI, and more.
+Traditional tool-calling requires the LLM to invoke tools one at a time. Each result goes back through the model, wasting tokens and time. Complex workflows require dozens of individual tool calls.
 
-## Quick Start
+**Beige agents can write and run code.** Instead of calling a tool 20 times, the agent writes a script that does it in a loop. The LLM only sees the final result.
 
-Beige has two install modes. Pick the one that fits you.
 
-### Option A — npm global (recommended for most users)
+| Beige                                                              | Traditional LLM                                            |
+| ------------------------------------------------------------------ | ---------------------------------------------------------- |
+| **1 round-trip** — agent writes a script, runs it, gets one result | **20 round-trips** — each tool call goes through the model |
+| 20 KV lookups happen inside the sandbox                            | 20× the latency, 20× the token overhead                    |
 
-**Prerequisites:** Node.js 22+, Docker
+
+### Beige — write then exec
+
+The agent writes a TypeScript file, then executes it. One round-trip to the LLM.
+
+```typescript fetch-users.ts
+const users = [];
+for (let i = 1; i <= 20; i++) {
+  const result = await exec(`/tools/bin/kv get user:${i}`);
+  users.push(JSON.parse(result));
+}
+console.log(JSON.stringify(users));
+```
 
 ```bash
-npm install -g matthias-hausberger/beige
+write /workspace/fetch-users.ts
+exec deno run /workspace/fetch-users.ts
 ```
 
-On first run, beige automatically creates `~/.beige/` with a default config and the bundled KV tool:
+**Result returned to LLM:** one JSON array — done.
 
-```bash
-export ANTHROPIC_API_KEY="sk-ant-..."
+**Every tool call — including the ones called by a script — is routed through the gateway.** The gateway checks permissions, enforces policy, and ensures secrets never reach the sandbox.
 
-# Shell 1 — start the gateway
-beige gateway start
+### Traditional LLM
 
-# Shell 2 — open the TUI
-beige tui
+Without a code runtime the LLM must call the tool once per item. Slow, unsafe, error-prone, not easily reproducible:
+
+```
+→ tool_call: kv get user:1
+← result: {"id":1,"name":"Alice"}
+→ tool_call: kv get user:2
+← result: {"id":2,"name":"Bob"}
+... 18 more calls ...
 ```
 
-You can also run setup explicitly:
+---
 
-```bash
-beige setup
-```
+## Key Principles
+
+- **Sandboxed** — Every agent runs in its own Docker container. No access to host env vars, secrets, or files.
+- **Audited** — Every tool call is logged with agent identity, args, timing, and permission decision.
+- **Policy-enforced** — Deny by default. Agents can only use tools explicitly granted in config.
+- **Extensible** — Add tools as simple packages. They mount into sandboxes read-only.
+- **LLM-agnostic** — Uses [pi SDK](https://pi.dev) for LLM interaction. Supports Anthropic, OpenAI, ZAI, and more.
 
-### Option B — Source install (contributors / power users)
+---
+
+## Quick Start
 
 **Prerequisites:** Node.js 22+, Docker
 
+Install Beige globally:
+
 ```bash
-git clone https://github.com/matthias-hausberger/beige.git
-cd beige
-npm install
-npm run build:sandbox       # build the sandbox Docker image
+npm install -g matthias-hausberger/beige
 ```
 
-No files are written outside the repo. Configure manually:
+Set your Anthropic API key (you can also set this in your `~/.beige/config.json5` config after you started the gateway for the first time):
 
 ```bash
-cp examples/config.json5 ~/.beige/config.json5
-# Edit ~/.beige/config.json5: set your API key and adjust tool paths
 export ANTHROPIC_API_KEY="sk-ant-..."
+```
 
-# Shell 1
-npx tsx src/cli.ts gateway start --foreground
+Start the gateway:
 
-# Shell 2
-npx tsx src/cli.ts tui
+```bash
+beige gateway start
 ```
 
-See [docs/installation.md](docs/installation.md) for a full comparison of both modes.
+Open the TUI. Alternatively you can also use [Telegram](https://beige.mintlify.app/channels/telegram) or add your own channel plugin:
 
-### TUI Commands
+```bash
+beige tui
+```
 
-Once inside the TUI, these slash commands are available:
+On first run, Beige creates `~/.beige/` with a default config and the bundled KV tool.
 
-| Command | Description |
-|---------|-------------|
-| `/new` | Start a fresh conversation session |
-| `/resume` | Pick a previous session to continue |
-| `/sessions` | List saved sessions for the current agent |
-| `/agent [name]` | Switch to a different beige agent (with tab-completion) |
+You can also use **[any other LLM Provider](https://beige.mintlify.app/agents/providers)**.
 
-## Architecture
+See the [installation guide](https://beige.mintlify.app/installation) for details.
 
-```
-Channels
-  ├── TUI (pi interactive mode)
-  └── Telegram bot
-        │
-        ▼
-  Gateway (always running)
-  ├── Agent Manager → LLM (via pi SDK) → Core Tools
-  │                                            │
-  │                                            ▼
-  │                                      Docker Sandbox
-  │                                      ├── /workspace (rw)
-  │                                      ├── /tools/bin (ro)
-  │                                      └── /tools/packages (ro)
-  │
-  └── Unix Socket ← Tool launchers call back to gateway
-        │
-        ▼
-  Policy Engine → Audit Logger → Tool Runner
-```
+---
 
 ## Documentation
 
-Full documentation is available at **[beige.mintlify.app](https://beige.mintlify.app)**:
-
-| Section | Description |
-|---------|-------------|
-| [**Introduction**](https://beige.mintlify.app/introduction) | What Beige is, why we built it, and how it works |
-| [**Getting Started**](https://beige.mintlify.app/getting-started) | Install and run your first agent |
-| [**The Gateway**](https://beige.mintlify.app/gateway) | Deep dive into architecture and security |
-| [**Agents**](https://beige.mintlify.app/agents) | Configure providers, models, tools, and skills |
-| [**Channels & Tools**](https://beige.mintlify.app/channels-and-tools) | TUI, Telegram, HTTP API, and extensibility |
-
-### Reference Documentation
-
-- [Configuration Reference](docs/configuration.mdx) — Complete config file reference
-- [Tools Reference](docs/tools.mdx) — Tool packages, launchers, socket protocol
-- [Toolkits Reference](docs/toolkits.mdx) — Installing and creating toolkits
-- [Skills Reference](docs/skills.mdx) — Creating knowledge packages
-- [HTTP API Reference](docs/api.mdx) — Full REST API reference
-- [Security Model](docs/security-model.mdx) — Threat model and defense in depth
-
-### Design Documents
-
-- [Vision](docs/design/vision.md) — Original design goals
-- [Use Cases](docs/design/usecases.md) — Personal use cases that motivated the project
-
-### External Resources
-
-- [pi SDK](https://pi.dev) — The LLM SDK that powers Beige
-- [OpenClaw](https://openclaw.ai) — Inspiration for personal agents
-- ["What if you don't need MCP?"](https://mariozechner.at/posts/2025-11-02-what-if-you-dont-need-mcp/) — Why CLI tools beat MCP bloat
-- ["Code Mode"](https://blog.cloudflare.com/code-mode/) — Why LLMs are better at writing code than calling tools
-
-## Configuration
-
-Config is a single JSON5 file (JSON with comments) at `~/.beige/config.json5`. See [examples/config.json5](examples/config.json5) for a template.
-
-```json5
-{
-  llm: {
-    providers: {
-      anthropic: { apiKey: "${ANTHROPIC_API_KEY}" },
-    },
-  },
-  tools: {
-    kv: { path: "./tools/kv", target: "gateway" },
-  },
-  agents: {
-    assistant: {
-      model: { provider: "anthropic", model: "claude-sonnet-4-20250514" },
-      tools: ["kv"],
-    },
-  },
-  channels: {
-    telegram: {
-      enabled: true,
-      token: "${TELEGRAM_BOT_TOKEN}",
-      allowedUsers: [123456789],
-      agentMapping: { default: "assistant" },
-    },
-  },
-}
-```
+Full documentation at **[beige.mintlify.app](https://beige.mintlify.app)**:
 
-## Tools
 
-Tools are simple packages:
+| Section                                                             | Description                                 |
+| ------------------------------------------------------------------- | ------------------------------------------- |
+| [Getting Started](https://beige.mintlify.app/installation)          | Install and run your first agent            |
+| [Gateway](https://beige.mintlify.app/gateway)                       | Core concepts, tool calls, operations       |
+| [Agents](https://beige.mintlify.app/agents)                         | Configure providers, models, tools, skills  |
+| [Channels](https://beige.mintlify.app/channels)                     | TUI, Telegram, HTTP API                     |
+| [Tools](https://beige.mintlify.app/tools)                           | Core tools, building custom tools, toolkits |
+| [Config Reference](https://beige.mintlify.app/agents/configuration) | Complete config file reference              |
+| [CLI Reference](https://beige.mintlify.app/cli)                     | All CLI commands and flags                  |
 
-```
-tools/my-tool/
-├── tool.json     # Name, description, commands
-├── index.ts      # Handler (gateway-targeted) or logic (sandbox-targeted)
-└── README.md     # Documentation (mounted into sandbox for agent context)
-```
 
-The agent calls tools via `exec /tools/bin/my-tool <args>`. The launcher routes through the gateway socket for policy checks and execution.
+---
 
-## Security Model
+## Contributing
 
-1. **Sandbox isolation**: Agents run in Docker containers with no host env access
-2. **Read-only mounts**: Tool code and launchers are mounted read-only
-3. **Socket identity**: Agent identity derived from Unix socket (not payload)
-4. **Policy engine**: Deny by default, explicit allow per agent per tool
-5. **Audit log**: Every tool invocation logged as JSONL
+All contributions are welcome. See [CONTRIBUTING.md](CONTRIBUTING.md) for development setup.
+
+For source installs, Beige runs entirely inside the repo — no files are written to your home directory.
+
+Clone and install:
+
+```bash
+git clone https://github.com/matthias-hausberger/beige.git
+cd beige
+pnpm install
+```
+
+Run setup:
+
+```bash
+pnpm run beige setup
+```
 
-## Project Status
+This sets `BEIGE_HOME=./.beige` automatically, so the repo is self-contained.
 
-**Phase 1 (current):** Core gateway + KV tool MVP
-- [x] Config system
-- [x] Docker sandbox manager
-- [x] Core tools (read, write, patch, exec)
-- [x] Unix socket server for tool routing
-- [x] Policy engine
-- [x] Audit logging
-- [x] KV tool (gateway-hosted)
-- [x] Telegram channel (GrammY)
-- [x] Interactive TUI (via pi SDK InteractiveMode)
-- [x] LLM integration via pi SDK
+---
 
 ## License
 
-MIT
+MIT

package/config.schema.json

@@ -0,0 +1,352 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "BeigeConfig",
+  "description": "Beige configuration file (config.json5). JSON5 format — comments and trailing commas are allowed.",
+  "type": "object",
+  "required": [
+    "llm",
+    "tools",
+    "agents"
+  ],
+  "properties": {
+    "llm": {
+      "title": "LLMConfig",
+      "type": "object",
+      "required": [
+        "providers"
+      ],
+      "properties": {
+        "providers": {
+          "description": "Named LLM providers. Each key becomes a provider name agents can reference.",
+          "type": "object",
+          "patternProperties": {
+            "^(.*)$": {
+              "title": "LLMProviderConfig",
+              "type": "object",
+              "properties": {
+                "apiKey": {
+                  "description": "API key. Use \"${VAR_NAME}\" to read from environment. Not required for local providers (e.g. Ollama).",
+                  "type": "string"
+                },
+                "baseUrl": {
+                  "description": "Custom API endpoint URL. Required for non-built-in providers (ZAI, Groq, Ollama, etc.).",
+                  "type": "string"
+                },
+                "api": {
+                  "description": "API protocol. Auto-set for built-in providers (anthropic, openai, google). Required for custom providers.",
+                  "anyOf": [
+                    {
+                      "const": "anthropic-messages",
+                      "type": "string"
+                    },
+                    {
+                      "const": "openai-completions",
+                      "type": "string"
+                    },
+                    {
+                      "const": "openai-responses",
+                      "type": "string"
+                    },
+                    {
+                      "const": "google-generative-ai",
+                      "type": "string"
+                    }
+                  ]
+                }
+              }
+            }
+          }
+        }
+      }
+    },
+    "tools": {
+      "description": "Tool registry. Each key becomes the tool name used in agent configs and /tools/bin/.",
+      "type": "object",
+      "patternProperties": {
+        "^(.*)$": {
+          "title": "ToolConfig",
+          "type": "object",
+          "required": [
+            "path",
+            "target"
+          ],
+          "properties": {
+            "path": {
+              "description": "Path to the tool package directory. Resolved relative to the config file unless absolute.",
+              "type": "string"
+            },
+            "target": {
+              "description": "\"gateway\" runs the handler on the host process. \"sandbox\" is planned.",
+              "anyOf": [
+                {
+                  "const": "gateway",
+                  "type": "string"
+                },
+                {
+                  "const": "sandbox",
+                  "type": "string"
+                }
+              ]
+            },
+            "config": {
+              "description": "Arbitrary config object passed to createHandler(config) at startup",
+              "type": "object",
+              "patternProperties": {
+                "^(.*)$": {}
+              }
+            },
+            "_toolkit": {
+              "description": "Internal: set by the loader for tools auto-discovered from toolkits",
+              "type": "string"
+            }
+          }
+        }
+      }
+    },
+    "skills": {
+      "description": "Skill registry. Each key becomes the skill name used in agent configs.",
+      "type": "object",
+      "patternProperties": {
+        "^(.*)$": {
+          "title": "SkillConfig",
+          "type": "object",
+          "required": [
+            "path"
+          ],
+          "properties": {
+            "path": {
+              "description": "Path to the skill package directory. Resolved relative to the config file unless absolute.",
+              "type": "string"
+            }
+          }
+        }
+      }
+    },
+    "agents": {
+      "description": "Agent definitions. Each agent gets its own Docker sandbox, Unix socket, and LLM session.",
+      "type": "object",
+      "patternProperties": {
+        "^(.*)$": {
+          "title": "AgentConfig",
+          "type": "object",
+          "required": [
+            "model",
+            "tools"
+          ],
+          "properties": {
+            "model": {
+              "title": "ModelRef",
+              "type": "object",
+              "required": [
+                "provider",
+                "model"
+              ],
+              "properties": {
+                "provider": {
+                  "description": "Provider name — must match a key in llm.providers",
+                  "type": "string"
+                },
+                "model": {
+                  "description": "Model ID as the provider expects it",
+                  "type": "string"
+                },
+                "thinkingLevel": {
+                  "description": "Extended thinking budget. Only affects models that support it.",
+                  "anyOf": [
+                    {
+                      "const": "off",
+                      "type": "string"
+                    },
+                    {
+                      "const": "minimal",
+                      "type": "string"
+                    },
+                    {
+                      "const": "low",
+                      "type": "string"
+                    },
+                    {
+                      "const": "medium",
+                      "type": "string"
+                    },
+                    {
+                      "const": "high",
+                      "type": "string"
+                    }
+                  ]
+                }
+              }
+            },
+            "fallbackModels": {
+              "description": "Fallback models tried in order when the primary model fails or is rate-limited",
+              "type": "array",
+              "items": {
+                "title": "ModelRef",
+                "type": "object",
+                "required": [
+                  "provider",
+                  "model"
+                ],
+                "properties": {
+                  "provider": {
+                    "description": "Provider name — must match a key in llm.providers",
+                    "type": "string"
+                  },
+                  "model": {
+                    "description": "Model ID as the provider expects it",
+                    "type": "string"
+                  },
+                  "thinkingLevel": {
+                    "description": "Extended thinking budget. Only affects models that support it.",
+                    "anyOf": [
+                      {
+                        "const": "off",
+                        "type": "string"
+                      },
+                      {
+                        "const": "minimal",
+                        "type": "string"
+                      },
+                      {
+                        "const": "low",
+                        "type": "string"
+                      },
+                      {
+                        "const": "medium",
+                        "type": "string"
+                      },
+                      {
+                        "const": "high",
+                        "type": "string"
+                      }
+                    ]
+                  }
+                }
+              }
+            },
+            "tools": {
+              "description": "Tool names from the tools registry that this agent can invoke",
+              "type": "array",
+              "items": {
+                "type": "string"
+              }
+            },
+            "skills": {
+              "description": "Skill names from the skills registry mounted into this agent's sandbox",
+              "type": "array",
+              "items": {
+                "type": "string"
+              }
+            },
+            "sandbox": {
+              "title": "SandboxConfig",
+              "type": "object",
+              "properties": {
+                "image": {
+                  "description": "Docker image name. Default: \"beige-sandbox:latest\"",
+                  "type": "string"
+                },
+                "extraMounts": {
+                  "description": "Additional host→container bind mounts. Reduces isolation — use carefully.",
+                  "type": "object",
+                  "patternProperties": {
+                    "^(.*)$": {
+                      "type": "string"
+                    }
+                  }
+                },
+                "extraEnv": {
+                  "description": "Environment variables passed to the container. Visible to the agent — never use for secrets.",
+                  "type": "object",
+                  "patternProperties": {
+                    "^(.*)$": {
+                      "type": "string"
+                    }
+                  }
+                }
+              }
+            }
+          }
+        }
+      }
+    },
+    "gateway": {
+      "title": "GatewayServerConfig",
+      "type": "object",
+      "properties": {
+        "host": {
+          "description": "HTTP API bind address. Default: \"127.0.0.1\"",
+          "type": "string"
+        },
+        "port": {
+          "description": "HTTP API port. Default: 7433",
+          "type": "number"
+        },
+        "logFile": {
+          "description": "Daemon stdout/stderr log file. Default: ~/.beige/logs/gateway.log",
+          "type": "string"
+        }
+      }
+    },
+    "channels": {
+      "title": "ChannelsConfig",
+      "type": "object",
+      "properties": {
+        "telegram": {
+          "title": "TelegramChannelConfig",
+          "type": "object",
+          "required": [
+            "enabled",
+            "token",
+            "allowedUsers",
+            "agentMapping"
+          ],
+          "properties": {
+            "enabled": {
+              "description": "Set to true to activate the Telegram bot",
+              "type": "boolean"
+            },
+            "token": {
+              "description": "Telegram bot token from @BotFather. Use \"${TELEGRAM_BOT_TOKEN}\".",
+              "type": "string"
+            },
+            "allowedUsers": {
+              "description": "Telegram user IDs permitted to interact with the bot. All others are silently ignored.",
+              "type": "array",
+              "items": {
+                "type": "number"
+              }
+            },
+            "agentMapping": {
+              "description": "Maps Telegram chats to agents",
+              "type": "object",
+              "required": [
+                "default"
+              ],
+              "properties": {
+                "default": {
+                  "description": "Agent name that handles all incoming messages",
+                  "type": "string"
+                }
+              }
+            },
+            "defaults": {
+              "title": "ChannelDefaultSettings",
+              "type": "object",
+              "properties": {
+                "verbose": {
+                  "description": "Send a notification for every tool call the agent makes (e.g. 🔧 exec: ls). Default: false",
+                  "type": "boolean"
+                },
+                "streaming": {
+                  "description": "Stream responses to the user in real-time. Default: true",
+                  "type": "boolean"
+                }
+              }
+            }
+          }
+        }
+      }
+    }
+  }
+}