@matthias-hausberger/beige 0.0.1

package/package.json

@@ -0,0 +1,76 @@
+{
+  "name": "@matthias-hausberger/beige",
+  "version": "0.0.1",
+  "description": "Secure sandboxed agent system",
+  "publishConfig": {
+    "access": "public"
+  },
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "bin": {
+    "beige": "dist/cli.js"
+  },
+  "files": [
+    "dist",
+    "tools"
+  ],
+  "scripts": {
+    "beige": "tsx src/cli.ts",
+    "build": "tsc",
+    "start": "node dist/cli.js",
+    "build:sandbox": "docker build -t beige-sandbox:latest ./sandbox",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:coverage": "vitest run --coverage",
+    "docs:dev": "cd docs && mintlify dev --port 3333",
+    "docs:build": "cd docs && mintlify build",
+    "docs:deploy": "cd docs && mintlify deploy"
+  },
+  "dependencies": {
+    "@mariozechner/pi-ai": "^0.56.1",
+    "@mariozechner/pi-coding-agent": "latest",
+    "@sinclair/typebox": "^0.34.0",
+    "dockerode": "^4.0.5",
+    "grammy": "^1.35.0",
+    "json5": "^2.2.3",
+    "tar": "^7.5.11"
+  },
+  "devDependencies": {
+    "@types/dockerode": "^3.3.38",
+    "@types/node": "^22.0.0",
+    "@types/tar": "^7.0.87",
+    "@vitest/coverage-v8": "^4.0.18",
+    "mintlify": "^4.2.417",
+    "tsx": "^4.19.0",
+    "typescript": "^5.7.0",
+    "vitest": "^4.0.18"
+  },
+  "engines": {
+    "node": ">=22.0.0"
+  },
+  "keywords": [
+    "ai",
+    "agent",
+    "sandbox",
+    "docker",
+    "llm",
+    "claude",
+    "anthropic"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/matthias-hausberger/beige.git"
+  },
+  "bugs": {
+    "url": "https://github.com/matthias-hausberger/beige/issues"
+  },
+  "homepage": "https://github.com/matthias-hausberger/beige#readme",
+  "license": "MIT"
+}

package/tools/README.md

@@ -0,0 +1 @@
+This folder showcases examples for tools. They are NOT added to an agent by default and NOT used.

package/tools/kv/README.md

@@ -0,0 +1,150 @@
+# KV Tool
+
+Simple key-value store. Data persists on the gateway host at `~/.beige/data/kv.json` across sessions and gateway restarts.
+
+## Usage
+
+```sh
+/tools/bin/kv set <key> <value>   # Store a value
+/tools/bin/kv get <key>           # Retrieve a value
+/tools/bin/kv del <key>           # Delete a key
+/tools/bin/kv list                # List all keys with their values
+```
+
+## Examples
+
+### Basic Operations
+
+```sh
+# Store a travel note
+/tools/bin/kv set trip:paris "Flying March 15, Hotel Lumiere"
+
+# Retrieve it
+/tools/bin/kv get trip:paris
+# → Flying March 15, Hotel Lumiere
+
+# List all stored keys
+/tools/bin/kv list
+# → trip:paris = Flying March 15, Hotel Lumiere
+
+# Delete
+/tools/bin/kv del trip:paris
+# → Deleted: trip:paris
+```
+
+### Using Keys with Namespaces
+
+```sh
+# Organize with colon-separated namespaces
+/tools/bin/kv set user:alice:email "alice@example.com"
+/tools/bin/kv set user:bob:email "bob@example.com"
+/tools/bin/kv set config:timezone "Europe/Berlin"
+
+# List shows all keys
+/tools/bin/kv list
+# → user:alice:email = alice@example.com
+# → user:bob:email = bob@example.com
+# → config:timezone = Europe/Berlin
+```
+
+### Storing JSON Data
+
+```sh
+# Store structured data as JSON string
+/tools/bin/kv set project:config '{"name": "beige", "version": "0.1.0"}'
+
+# Retrieve and parse with jq
+/tools/bin/kv get project:config | jq -r '.name'
+# → beige
+```
+
+### Error Handling
+
+```sh
+# Getting a non-existent key
+/tools/bin/kv get nonexistent
+# → Key not found: nonexistent
+# (exit code: 1)
+
+# Deleting a non-existent key
+/tools/bin/kv del nonexistent
+# → Key not found: nonexistent
+# (exit code: 1)
+```
+
+## Access Control
+
+The commands available to an agent are controlled via the tool's `config` block in `config.json5`.
+Two optional fields let you allowlist and/or denylist specific commands:
+
+| Config field | Type | Default | Description |
+|---|---|---|---|
+| `allowCommands` | `string \| string[]` | all commands | Only these commands are permitted. |
+| `denyCommands` | `string \| string[]` | *(none)* | These commands are always blocked. Deny beats allow. |
+
+**Example — read-only agent** (can only `get` and `list`):
+
+```json5
+tools: {
+  "kv-readonly": {
+    path: "./tools/kv",
+    target: "gateway",
+    config: {
+      allowCommands: ["get", "list"],
+    },
+  },
+},
+agents: {
+  reader: { tools: ["kv-readonly"] },
+},
+```
+
+**Example — write-only agent** (can `set` and `del`, cannot read):
+
+```json5
+tools: {
+  "kv-writeonly": {
+    path: "./tools/kv",
+    target: "gateway",
+    config: {
+      allowCommands: ["set", "del"],
+    },
+  },
+},
+```
+
+**Example — deny a single command on an otherwise full-access tool** (no `del`):
+
+```json5
+tools: {
+  "kv-nodelete": {
+    path: "./tools/kv",
+    target: "gateway",
+    config: {
+      denyCommands: ["del"],
+    },
+  },
+},
+```
+
+When a denied command is called, the tool exits with code `1` and prints a clear error:
+
+```
+Permission denied: command 'del' is not allowed for this agent.
+Permitted commands: set, get, list
+```
+
+## Notes
+
+- Keys and values are strings.
+- Values with spaces must be passed as a single argument (the tool joins all args after the key).
+- Data is stored as JSON on the gateway host at `~/.beige/data/kv.json`. Agents cannot access the raw storage file directly — they must use the tool commands.
+- The same physical KV store is shared across all agents. Use `allowCommands` / `denyCommands` to restrict which operations each agent can perform, not which keys it can see.
+- If you need key-level isolation between agents, create multiple tool instances with different configs (future enhancement).
+
+## Implementation Details
+
+- **Target**: Gateway (runs on the host, not in the sandbox)
+- **Storage**: `~/.beige/data/kv.json`
+- **Protocol**: Tool launcher calls back to gateway via Unix socket
+- **Type**: See `tools/kv/index.ts` for the handler implementation

package/tools/kv/index.ts

@@ -0,0 +1,149 @@
+import { readFileSync, writeFileSync, mkdirSync } from "fs";
+import { resolve } from "path";
+import { homedir } from "os";
+
+// ToolHandler type is defined here inline so this file is self-contained.
+// It can be installed anywhere (e.g. ~/.beige/tools/kv/) without needing the
+// beige source tree.
+type ToolHandler = (args: string[], config?: Record<string, unknown>) => Promise<{ output: string; exitCode: number }>;
+
+/** All commands the KV tool exposes. */
+const ALL_COMMANDS = ["set", "get", "del", "list"] as const;
+type KVCommand = (typeof ALL_COMMANDS)[number];
+
+/**
+ * Resolve which commands are permitted given the tool config.
+ *
+ * Config fields (both optional, strings or arrays of strings):
+ *   allowCommands  — whitelist; only these commands are permitted.
+ *                    Defaults to all commands when absent.
+ *   denyCommands   — blacklist; these commands are always blocked,
+ *                    even if present in allowCommands.
+ *
+ * Precedence: deny beats allow.
+ */
+function resolveAllowedCommands(config: Record<string, unknown>): Set<KVCommand> {
+  const toArray = (value: unknown): string[] => {
+    if (Array.isArray(value)) return value.map(String);
+    if (typeof value === "string") return [value];
+    return [];
+  };
+
+  const allowed = new Set<KVCommand>(
+    config.allowCommands !== undefined
+      ? (toArray(config.allowCommands).filter((c) =>
+          (ALL_COMMANDS as readonly string[]).includes(c)
+        ) as KVCommand[])
+      : ALL_COMMANDS
+  );
+
+  for (const cmd of toArray(config.denyCommands)) {
+    allowed.delete(cmd as KVCommand);
+  }
+
+  return allowed;
+}
+
+/**
+ * KV Tool — Simple key-value store that persists to disk.
+ * Executes on the gateway host.
+ *
+ * Commands:
+ *   set <key> <value>  — Store a value
+ *   get <key>          — Retrieve a value
+ *   del <key>          — Delete a key
+ *   list               — List all keys
+ *
+ * Config:
+ *   allowCommands  — only permit these commands (default: all)
+ *   denyCommands   — always block these commands (deny beats allow)
+ */
+export function createHandler(config: Record<string, unknown>): ToolHandler {
+  const storePath = resolve(homedir(), ".beige", "data", "kv.json");
+  mkdirSync(resolve(homedir(), ".beige", "data"), { recursive: true });
+
+  const allowedCommands = resolveAllowedCommands(config);
+
+  function loadStore(): Record<string, string> {
+    try {
+      return JSON.parse(readFileSync(storePath, "utf-8"));
+    } catch {
+      return {};
+    }
+  }
+
+  function saveStore(store: Record<string, string>): void {
+    writeFileSync(storePath, JSON.stringify(store, null, 2));
+  }
+
+  return async (args: string[]) => {
+    const command = args[0];
+
+    // Access-control check — runs before any business logic.
+    if (command && !allowedCommands.has(command as KVCommand)) {
+      const permitted = [...allowedCommands].join(", ") || "(none)";
+      return {
+        output: `Permission denied: command '${command}' is not allowed for this agent.\nPermitted commands: ${permitted}`,
+        exitCode: 1,
+      };
+    }
+
+    switch (command) {
+      case "set": {
+        const key = args[1];
+        const value = args.slice(2).join(" ");
+        if (!key || !value) {
+          return { output: "Usage: kv set <key> <value>", exitCode: 1 };
+        }
+        const store = loadStore();
+        store[key] = value;
+        saveStore(store);
+        return { output: `OK: ${key} = ${value}`, exitCode: 0 };
+      }
+
+      case "get": {
+        const key = args[1];
+        if (!key) {
+          return { output: "Usage: kv get <key>", exitCode: 1 };
+        }
+        const store = loadStore();
+        if (key in store) {
+          return { output: store[key], exitCode: 0 };
+        }
+        return { output: `Key not found: ${key}`, exitCode: 1 };
+      }
+
+      case "del": {
+        const key = args[1];
+        if (!key) {
+          return { output: "Usage: kv del <key>", exitCode: 1 };
+        }
+        const store = loadStore();
+        if (key in store) {
+          delete store[key];
+          saveStore(store);
+          return { output: `Deleted: ${key}`, exitCode: 0 };
+        }
+        return { output: `Key not found: ${key}`, exitCode: 1 };
+      }
+
+      case "list": {
+        const store = loadStore();
+        const keys = Object.keys(store);
+        if (keys.length === 0) {
+          return { output: "(empty)", exitCode: 0 };
+        }
+        return {
+          output: keys.map((k) => `${k} = ${store[k]}`).join("\n"),
+          exitCode: 0,
+        };
+      }
+
+      default:
+        return {
+          output: `Unknown command: ${command}\nUsage: kv <set|get|del|list> [args...]`,
+          exitCode: 1,
+        };
+    }
+  };
+}

package/tools/kv/tool.json

@@ -0,0 +1,23 @@
+{
+  "name": "kv",
+  "description": "Simple key-value store. Store and retrieve values by key. Data persists across sessions.",
+  "commands": [
+    "set <key> <value>  — Store a value",
+    "get <key>          — Retrieve a value",
+    "del <key>          — Delete a key",
+    "list               — List all keys"
+  ],
+  "target": "gateway",
+  "config": {
+    "allowCommands": {
+      "type": "string | string[]",
+      "description": "Whitelist of permitted commands. Defaults to all commands when absent.",
+      "example": ["get", "list"]
+    },
+    "denyCommands": {
+      "type": "string | string[]",
+      "description": "Blacklist of blocked commands. Takes precedence over allowCommands.",
+      "example": ["del"]
+    }
+  }
+}

package/tools/message/README.md

@@ -0,0 +1,53 @@
+# Message Tool
+
+Send messages to users through configured channels (currently Telegram only).
+
+## Commands
+
+### Send to Current Session
+
+Send a message to the current session's channel/chat/thread:
+
+```bash
+/tools/bin/message --to-current-session -- Hello! This is a reply.
+```
+
+This only works when called from within an active LLM session. If called from a standalone script, you'll get an error and should use explicit targeting instead.
+
+### Send to Specific Telegram Chat
+
+Send to a specific chat (proactive messaging):
+
+```bash
+/tools/bin/message telegram 123456789 -- Hello! This is a proactive message.
+```
+
+Send to a specific thread in a Telegram forum:
+
+```bash
+/tools/bin/message telegram 123456789 42 -- Hello from the thread!
+```
+
+### With Formatting
+
+Use `--parse-mode` for formatted messages (Markdown or HTML):
+
+```bash
+# Markdown
+/tools/bin/message telegram 123456789 -- --parse-mode markdown -- **Bold** and _italic_ text
+
+# HTML
+/tools/bin/message telegram 123456789 -- --parse-mode html -- <b>Bold</b> and <i>italic</i> text
+```
+
+Note: Telegram uses MarkdownV2 syntax. See [Telegram's formatting docs](https://core.telegram.org/bots/api#markdownv2-style) for details.
+
+## Error Handling
+
+- **No session context**: When using `--to-current-session` from a script, you'll get an error with guidance to use explicit targeting.
+- **Unsupported channel**: If the current session's channel doesn't support messaging (e.g., TUI), you'll get an error.
+- **Channel not available**: If Telegram isn't enabled in the gateway config, explicit Telegram commands will fail.
+
+## Long Messages
+
+Messages longer than Telegram's 4096 character limit are automatically split into multiple messages.

package/tools/message/index.ts

@@ -0,0 +1,183 @@
+type ToolHandler = (
+  args: string[],
+  config?: Record<string, unknown>,
+  sessionContext?: SessionContext
+) => Promise<{ output: string; exitCode: number }>;
+
+interface SessionContext {
+  sessionKey: string;
+  channel: string;
+  chatId?: string;
+  threadId?: string;
+}
+
+interface ToolHandlerContext {
+  channelRegistry?: ChannelRegistry;
+}
+
+interface ChannelRegistry {
+  get(channel: string): ChannelAdapter | undefined;
+  has(channel: string): boolean;
+}
+
+interface ChannelAdapter {
+  sendMessage(
+    chatId: string,
+    threadId: string | undefined,
+    text: string,
+    options?: { parseMode?: "html" | "markdown" }
+  ): Promise<void>;
+  supportsMessaging(): boolean;
+}
+
+interface ParsedCommand {
+  action: "current" | "telegram";
+  chatId?: string;
+  threadId?: string;
+  parseMode?: "html" | "markdown";
+  text: string;
+}
+
+function parseArgs(args: string[]): ParsedCommand | { error: string } {
+  if (args.length === 0) {
+    return { error: "No arguments provided. Usage: message --to-current-session -- <text> | message telegram <chatId> [-- <threadId>] -- [--parse-mode <mode>] -- <text>" };
+  }
+
+  if (args[0] === "--to-current-session") {
+    const doubleDashIndex = args.indexOf("--");
+    if (doubleDashIndex === -1 || doubleDashIndex === args.length - 1) {
+      return { error: "Missing message text after --. Usage: message --to-current-session -- <text>" };
+    }
+    const textParts: string[] = [];
+    let i = doubleDashIndex + 1;
+    while (i < args.length) {
+      textParts.push(args[i]);
+      i++;
+    }
+    return {
+      action: "current",
+      text: textParts.join(" "),
+    };
+  }
+
+  if (args[0] === "telegram") {
+    if (args.length < 3) {
+      return { error: "Missing arguments. Usage: message telegram <chatId> [-- <threadId>] -- [--parse-mode <mode>] -- <text>" };
+    }
+
+    const chatId = args[1];
+    let threadId: string | undefined;
+    let parseMode: "html" | "markdown" | undefined;
+    let textStartIndex = 2;
+
+    // Look for threadId (must be before the final --)
+    const lastDoubleDash = args.lastIndexOf("--");
+    if (lastDoubleDash === -1 || lastDoubleDash === args.length - 1) {
+      return { error: "Missing message text after --. Usage: message telegram <chatId> [-- <threadId>] -- [--parse-mode <mode>] -- <text>" };
+    }
+
+    // Check for --parse-mode before the final --
+    for (let i = 2; i < lastDoubleDash; i++) {
+      if (args[i] === "--parse-mode" && i + 1 < lastDoubleDash) {
+        const mode = args[i + 1];
+        if (mode === "html" || mode === "markdown") {
+          parseMode = mode;
+        } else {
+          return { error: `Invalid parse mode: ${mode}. Must be 'html' or 'markdown'.` };
+        }
+      } else if (!isNaN(Number(args[i])) && !threadId && args[i - 1] !== "--parse-mode") {
+        // If it's a number and we haven't set threadId yet, it might be threadId
+        threadId = args[i];
+      }
+    }
+
+    const text = args.slice(lastDoubleDash + 1).join(" ");
+    if (!text) {
+      return { error: "Missing message text after --" };
+    }
+
+    return {
+      action: "telegram",
+      chatId,
+      threadId,
+      parseMode,
+      text,
+    };
+  }
+
+  return { error: `Unknown action: ${args[0]}. Use '--to-current-session' or 'telegram'.` };
+}
+
+export function createHandler(config: Record<string, unknown>, context: ToolHandlerContext): ToolHandler {
+  const channelRegistry = context.channelRegistry;
+
+  return async (args: string[], _config?: Record<string, unknown>, sessionContext?: SessionContext) => {
+    const parsed = parseArgs(args);
+    if ("error" in parsed) {
+      return { output: `Error: ${parsed.error}`, exitCode: 1 };
+    }
+
+    if (parsed.action === "current") {
+      if (!sessionContext) {
+        return {
+          output: "Error: No session context available. This command must be run from within an active LLM session, not from a standalone script.\n\nUse explicit targeting instead: message telegram <chatId> -- <text>",
+          exitCode: 1,
+        };
+      }
+
+      const adapter = channelRegistry?.get(sessionContext.channel);
+      if (!adapter) {
+        return {
+          output: `Error: Channel '${sessionContext.channel}' is not available or not registered.`,
+          exitCode: 1,
+        };
+      }
+
+      if (!adapter.supportsMessaging()) {
+        return {
+          output: `Error: The current session's channel ('${sessionContext.channel}') doesn't support messaging.`,
+          exitCode: 1,
+        };
+      }
+
+      if (!sessionContext.chatId) {
+        return {
+          output: `Error: The current session does not have a chat ID. Cannot send message.`,
+          exitCode: 1,
+        };
+      }
+
+      try {
+        await adapter.sendMessage(sessionContext.chatId, sessionContext.threadId, parsed.text);
+        return { output: "Message sent successfully.", exitCode: 0 };
+      } catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        return { output: `Error sending message: ${msg}`, exitCode: 1 };
+      }
+    }
+
+    if (parsed.action === "telegram") {
+      if (!parsed.chatId) {
+        return { output: "Error: Missing chat ID for Telegram message.", exitCode: 1 };
+      }
+
+      const adapter = channelRegistry?.get("telegram");
+      if (!adapter) {
+        return {
+          output: "Error: Telegram channel is not available. Make sure Telegram is enabled in the gateway config.",
+          exitCode: 1,
+        };
+      }
+
+      try {
+        await adapter.sendMessage(parsed.chatId, parsed.threadId, parsed.text, { parseMode: parsed.parseMode });
+        return { output: "Message sent successfully to Telegram.", exitCode: 0 };
+      } catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        return { output: `Error sending message to Telegram: ${msg}`, exitCode: 1 };
+      }
+    }
+
+    return { output: "Error: Unknown action.", exitCode: 1 };
+  };
+}

package/tools/message/tool.json

@@ -0,0 +1,11 @@
+{
+  "name": "message",
+  "description": "Send messages to users through configured channels (Telegram). Can reply to the current session or send proactively to any chat.",
+  "commands": [
+    "--to-current-session -- <text>              — Send to the current session's channel/chat/thread",
+    "telegram <chatId> -- <text>                 — Send to a specific Telegram chat",
+    "telegram <chatId> <threadId> -- <text>      — Send to a specific Telegram thread",
+    "telegram <chatId> -- --parse-mode <mode> -- <text> — Send with formatting (html|markdown)"
+  ],
+  "target": "gateway"
+}