@matthias-hausberger/beige 0.0.1

package/LICENSE.md

@@ -0,0 +1,8 @@
+Copyright 2026 Matthias Hausberger
+
+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,183 @@
+# Beige
+
+Secure, sandboxed agent system. Let agents write and execute code — safely.
+
+## 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.
+
+**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.
+
+## Quick Start
+
+Beige has two install modes. Pick the one that fits you.
+
+### Option A — npm global (recommended for most users)
+
+**Prerequisites:** Node.js 22+, Docker
+
+```bash
+npm install -g matthias-hausberger/beige
+```
+
+On first run, beige automatically creates `~/.beige/` with a default config and the bundled KV tool:
+
+```bash
+export ANTHROPIC_API_KEY="sk-ant-..."
+
+# Shell 1 — start the gateway
+beige gateway start
+
+# Shell 2 — open the TUI
+beige tui
+```
+
+You can also run setup explicitly:
+
+```bash
+beige setup
+```
+
+### Option B — Source install (contributors / power users)
+
+**Prerequisites:** Node.js 22+, Docker
+
+```bash
+git clone https://github.com/matthias-hausberger/beige.git
+cd beige
+npm install
+npm run build:sandbox       # build the sandbox Docker image
+```
+
+No files are written outside the repo. Configure manually:
+
+```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
+
+# Shell 2
+npx tsx src/cli.ts tui
+```
+
+See [docs/installation.md](docs/installation.md) for a full comparison of both modes.
+
+### TUI Commands
+
+Once inside the TUI, these slash commands are available:
+
+| 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) |
+
+## Architecture
+
+```
+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
+```
+
+See [docs/](docs/) for full documentation:
+- [Installation](docs/installation.md) — npm vs source install, setup flow, detection logic
+- [System Overview](docs/system-overview.md) — architecture diagrams
+- [Request Flows](docs/request-flows.md) — sequence diagrams for every request type
+- [Security Model](docs/security-model.md) — sandboxing, identity, threat model
+- [Tools](docs/tools.md) — how to write and use tools
+- [Configuration](docs/configuration.md) — full config reference
+
+## 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" },
+    },
+  },
+}
+```
+
+## Tools
+
+Tools are simple packages:
+
+```
+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
+
+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
+
+## Project Status
+
+**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

package/dist/channels/registry.d.ts

@@ -0,0 +1,14 @@
+export interface SendMessageOptions {
+    parseMode?: "html" | "markdown";
+}
+export interface ChannelAdapter {
+    sendMessage(chatId: string, threadId: string | undefined, text: string, options?: SendMessageOptions): Promise<void>;
+    supportsMessaging(): boolean;
+}
+export declare class ChannelRegistry {
+    private channels;
+    register(channel: string, adapter: ChannelAdapter): void;
+    get(channel: string): ChannelAdapter | undefined;
+    has(channel: string): boolean;
+}
+//# sourceMappingURL=registry.d.ts.map

package/dist/channels/registry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"registry.d.ts","sourceRoot":"","sources":["../../src/channels/registry.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,kBAAkB;IACjC,SAAS,CAAC,EAAE,MAAM,GAAG,UAAU,CAAC;CACjC;AAED,MAAM,WAAW,cAAc;IAC7B,WAAW,CACT,MAAM,EAAE,MAAM,EACd,QAAQ,EAAE,MAAM,GAAG,SAAS,EAC5B,IAAI,EAAE,MAAM,EACZ,OAAO,CAAC,EAAE,kBAAkB,GAC3B,OAAO,CAAC,IAAI,CAAC,CAAC;IAEjB,iBAAiB,IAAI,OAAO,CAAC;CAC9B;AAED,qBAAa,eAAe;IAC1B,OAAO,CAAC,QAAQ,CAAqC;IAErD,QAAQ,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,cAAc,GAAG,IAAI;IAKxD,GAAG,CAAC,OAAO,EAAE,MAAM,GAAG,cAAc,GAAG,SAAS;IAIhD,GAAG,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO;CAG9B"}

package/dist/channels/registry.js

@@ -0,0 +1,14 @@
+export class ChannelRegistry {
+    channels = new Map();
+    register(channel, adapter) {
+        this.channels.set(channel, adapter);
+        console.log(`[CHANNELS] Registered channel adapter: ${channel}`);
+    }
+    get(channel) {
+        return this.channels.get(channel);
+    }
+    has(channel) {
+        return this.channels.has(channel);
+    }
+}
+//# sourceMappingURL=registry.js.map

package/dist/channels/registry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"registry.js","sourceRoot":"","sources":["../../src/channels/registry.ts"],"names":[],"mappings":"AAeA,MAAM,OAAO,eAAe;IAClB,QAAQ,GAAG,IAAI,GAAG,EAA0B,CAAC;IAErD,QAAQ,CAAC,OAAe,EAAE,OAAuB;QAC/C,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;QACpC,OAAO,CAAC,GAAG,CAAC,0CAA0C,OAAO,EAAE,CAAC,CAAC;IACnE,CAAC;IAED,GAAG,CAAC,OAAe;QACjB,OAAO,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC;IACpC,CAAC;IAED,GAAG,CAAC,OAAe;QACjB,OAAO,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC;IACpC,CAAC;CACF"}

package/dist/channels/telegram.d.ts

@@ -0,0 +1,92 @@
+import type { TelegramChannelConfig } from "../config/schema.js";
+import type { AgentManager } from "../gateway/agent-manager.js";
+import { BeigeSessionStore } from "../gateway/sessions.js";
+import type { SessionSettingsStore } from "../gateway/session-settings.js";
+import type { ChannelRegistry, ChannelAdapter, SendMessageOptions } from "./registry.js";
+/**
+ * Telegram channel adapter using GrammY.
+ *
+ * Session model:
+ * - Each chat gets a persistent session (survives gateway restarts).
+ * - If a chat has threads (forum topics), each thread gets its own session.
+ * - /new starts a fresh session in the current chat/thread.
+ * - /start shows a welcome message.
+ *
+ * Channel commands (handled locally, NOT forwarded to the LLM):
+ * - /start         — welcome message + command overview
+ * - /new           — start a new conversation session
+ * - /status        — show session info + current settings
+ * - /v on|off      — toggle verbose mode for this session (shorthand)
+ * - /verbose on|off — toggle verbose mode for this session
+ * - /s on|off      — toggle streaming mode for this session (shorthand)
+ * - /streaming on|off — toggle streaming mode for this session
+ *
+ * Verbose mode:
+ * - When ON, the bot sends a small notification whenever the agent calls a tool.
+ * - Default is OFF (configurable via channels.telegram.defaults.verbose in config.json5).
+ * - Persisted per-session in ~/.beige/sessions/session-settings.json.
+ *
+ * Streaming mode:
+ * - When ON (default), responses are streamed in real-time (message edits as LLM generates).
+ * - When OFF, the full response is sent once the LLM finishes.
+ * - Default is ON (configurable via channels.telegram.defaults.streaming in config.json5).
+ * - Persisted per-session in ~/.beige/sessions/session-settings.json.
+ *
+ * Bot command registration:
+ * - On startup, the bot deletes all old commands and registers the current set.
+ */
+export declare class TelegramChannel implements ChannelAdapter {
+    private agentManager;
+    private sessionStore;
+    private settingsStore;
+    private channelRegistry?;
+    private bot;
+    private config;
+    constructor(telegramConfig: TelegramChannelConfig, agentManager: AgentManager, sessionStore: BeigeSessionStore, settingsStore: SessionSettingsStore, channelRegistry?: ChannelRegistry | undefined);
+    private setupHandlers;
+    /**
+     * Handle /verbose and /v commands.
+     * Parses "on"/"off" argument and persists the setting for this session.
+     */
+    private handleVerboseCommand;
+    /**
+     * Resolve the effective verbose setting for a session (layered: default → config → override).
+     */
+    private resolveVerbose;
+    /**
+     * Handle /streaming and /s commands.
+     * Parses "on"/"off" argument and persists the setting for this session.
+     */
+    private handleStreamingCommand;
+    /**
+     * Resolve the effective streaming setting for a session (layered: default → config → override).
+     */
+    private resolveStreaming;
+    /**
+     * Create an OnToolStart callback that sends a Telegram notification.
+     * Uses a GrammY context for thread-aware replies.
+     */
+    private makeToolStartHandler;
+    /**
+     * Create an OnToolStart callback using raw chat/thread IDs.
+     * Used when toggling verbose on mid-session (no fresh ctx available).
+     */
+    private makeToolStartHandlerForKey;
+    private buildToolStartHandler;
+    /**
+     * Resolve which agent to use for a given user.
+     */
+    private resolveAgent;
+    private sessionKeyFromCtx;
+    supportsMessaging(): boolean;
+    sendMessage(chatId: string, threadId: string | undefined, text: string, options?: SendMessageOptions): Promise<void>;
+    start(): Promise<void>;
+    stop(): Promise<void>;
+    /**
+     * Register the bot's command list with Telegram.
+     * First deletes all existing commands, then sets the current ones.
+     * This ensures stale commands from old bot versions are removed.
+     */
+    private registerBotCommands;
+}
+//# sourceMappingURL=telegram.d.ts.map

package/dist/channels/telegram.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"telegram.d.ts","sourceRoot":"","sources":["../../src/channels/telegram.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,qBAAqB,CAAC;AACjE,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,6BAA6B,CAAC;AAChE,OAAO,EAAE,iBAAiB,EAAE,MAAM,wBAAwB,CAAC;AAC3D,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,gCAAgC,CAAC;AAE3E,OAAO,KAAK,EAAE,eAAe,EAAE,cAAc,EAAE,kBAAkB,EAAE,MAAM,eAAe,CAAC;AAEzF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,qBAAa,eAAgB,YAAW,cAAc;IAMlD,OAAO,CAAC,YAAY;IACpB,OAAO,CAAC,YAAY;IACpB,OAAO,CAAC,aAAa;IACrB,OAAO,CAAC,eAAe,CAAC;IAR1B,OAAO,CAAC,GAAG,CAAM;IACjB,OAAO,CAAC,MAAM,CAAwB;gBAGpC,cAAc,EAAE,qBAAqB,EAC7B,YAAY,EAAE,YAAY,EAC1B,YAAY,EAAE,iBAAiB,EAC/B,aAAa,EAAE,oBAAoB,EACnC,eAAe,CAAC,EAAE,eAAe,YAAA;IAQ3C,OAAO,CAAC,aAAa;IAiMrB;;;OAGG;YACW,oBAAoB;IA0ClC;;OAEG;IACH,OAAO,CAAC,cAAc;IAQtB;;;OAGG;YACW,sBAAsB;IAgCpC;;OAEG;IACH,OAAO,CAAC,gBAAgB;IAMxB;;;OAGG;IACH,OAAO,CAAC,oBAAoB;IAS5B;;;OAGG;IACH,OAAO,CAAC,0BAA0B;IASlC,OAAO,CAAC,qBAAqB;IAoB7B;;OAEG;IACH,OAAO,CAAC,YAAY;IAIpB,OAAO,CAAC,iBAAiB;IAQzB,iBAAiB,IAAI,OAAO;IAItB,WAAW,CACf,MAAM,EAAE,MAAM,EACd,QAAQ,EAAE,MAAM,GAAG,SAAS,EAC5B,IAAI,EAAE,MAAM,EACZ,OAAO,CAAC,EAAE,kBAAkB,GAC3B,OAAO,CAAC,IAAI,CAAC;IA2BV,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAiBtB,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;IAK3B;;;;OAIG;YACW,mBAAmB;CAmClC"}