@matthias-hausberger/beige 0.2.1-beta1 → 1.0.0-beta3

package/config.schema.json

@@ -5,7 +5,6 @@
   "type": "object",
   "required": [
     "llm",
-    "tools",
     "agents"
   ],
   "properties": {
@@ -59,37 +58,28 @@
         }
       }
     },
-    "tools": {
-      "description": "Tool registry. Each key becomes the tool name used in agent configs and /tools/bin/.",
+    "plugins": {
+      "description": "Plugin registry. Each key becomes the plugin name. Plugins can provide tools, channels, hooks, and skills.",
       "type": "object",
       "patternProperties": {
         "^(.*)$": {
-          "title": "ToolConfig",
+          "title": "PluginConfig",
           "type": "object",
           "properties": {
             "path": {
-              "description": "Path to the tool package directory. Resolved relative to the config file unless absolute. Auto-resolved for tools installed via 'beige tools install'.",
+              "description": "Path to the plugin 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. Auto-resolved for tools installed via 'beige tools install'.",
-              "anyOf": [
-                {
-                  "const": "gateway",
-                  "type": "string"
-                },
-                {
-                  "const": "sandbox",
-                  "type": "string"
-                }
-              ]
-            },
             "config": {
-              "description": "Arbitrary config object passed to createHandler(config) at startup",
+              "description": "Arbitrary config object passed to createPlugin(config, ctx) at startup",
               "type": "object",
               "patternProperties": {
                 "^(.*)$": {}
               }
+            },
+            "_source": {
+              "description": "Install source (e.g. 'npm:@scope/package'). Written by 'beige plugins install', used by 'beige plugins update'. Do not edit manually.",
+              "type": "string"
             }
           }
         }
@@ -166,6 +156,11 @@
                       "type": "string"
                     }
                   ]
+                },
+                "compactionThreshold": {
+                  "description": "Context token count at which auto-compaction triggers for this model. Must be less than the model's context window. When set, compaction kicks in earlier than the default (contextWindow − 16384 tokens). Example: set to 100000 on a 200k-window model to compact at 100k tokens.",
+                  "minimum": 1,
+                  "type": "number"
                 }
               }
             },
@@ -212,19 +207,24 @@
                         "type": "string"
                       }
                     ]
+                  },
+                  "compactionThreshold": {
+                    "description": "Context token count at which auto-compaction triggers for this model. Must be less than the model's context window. When set, compaction kicks in earlier than the default (contextWindow − 16384 tokens). Example: set to 100000 on a 200k-window model to compact at 100k tokens.",
+                    "minimum": 1,
+                    "type": "number"
                   }
                 }
               }
             },
             "tools": {
-              "description": "Tool names from the tools registry that this agent can invoke",
+              "description": "Tool names registered by plugins that this agent can invoke",
               "type": "array",
               "items": {
                 "type": "string"
               }
             },
             "skills": {
-              "description": "Skill names from the skills registry mounted into this agent's sandbox",
+              "description": "Skill names (from skills registry or plugin-registered) mounted into this agent's sandbox",
               "type": "array",
               "items": {
                 "type": "string"
@@ -262,8 +262,8 @@
                 }
               }
             },
-            "toolConfigs": {
-              "description": "Per-agent tool config overrides. Keys must reference tools in this agent's tools array. Values are deep-merged with the top-level tool config from config.tools.<name>.config.",
+            "pluginConfigs": {
+              "description": "Per-agent plugin config overrides. Keys must reference plugins in the plugins registry. Values are deep-merged with the top-level plugin config from config.plugins.<name>.config.",
               "type": "object",
               "patternProperties": {
                 "^(.*)$": {
@@ -295,66 +295,6 @@
           "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"
-                }
-              }
-            }
-          }
-        }
-      }
     }
   }
 }

package/dist/cli.d.ts

@@ -12,7 +12,7 @@
  *   beige gateway logs                 Show gateway logs
  *   beige gateway logs -f              Follow gateway logs (tail -f)
  *   beige tui [agent]                  Connect to a running gateway via TUI
- *   beige tools <command>              Manage tools (install, list, update, remove)
+ *   beige plugins <command>             Manage plugins (install, list, update, remove)
  *   beige --config <path>              Use a specific config file
  *
  *   Shell 1:  beige                    ← starts gateway daemon

package/dist/cli.js

@@ -12,7 +12,7 @@
  *   beige gateway logs                 Show gateway logs
  *   beige gateway logs -f              Follow gateway logs (tail -f)
  *   beige tui [agent]                  Connect to a running gateway via TUI
- *   beige tools <command>              Manage tools (install, list, update, remove)
+ *   beige plugins <command>             Manage plugins (install, list, update, remove)
  *   beige --config <path>              Use a specific config file
  *
  *   Shell 1:  beige                    ← starts gateway daemon
@@ -24,7 +24,7 @@ import { spawn } from "child_process";
 import { watch } from "fs";
 import { runSetup } from "./install.js";
 import { beigeDir } from "./paths.js";
-import { installTools, removeTool, updateTool, updateAllTools, listInstalledTools, readMetaFile, } from "./tools/installer.js";
+import { installPlugins, removePlugin, updatePlugin, updateAllPlugins, listPluginsFromConfig, } from "./plugins/installer.js";
 // ── Timestamp helpers ────────────────────────────────────────────────
 /** Returns a local-time HH:MM:SS prefix, e.g. "14:03:07". */
 function timestampPrefix() {
@@ -34,6 +34,8 @@ function timestampPrefix() {
     const ss = String(d.getSeconds()).padStart(2, "0");
     return `${hh}:${mm}:${ss}`;
 }
+// Save original stderr.write before wrapping (for immediate flush on shutdown)
+const originalStderrWrite = process.stderr.write.bind(process.stderr);
 /**
  * Wraps process.stdout.write / process.stderr.write so that every line
  * written by the gateway process is prefixed with an HH:MM:SS timestamp.
@@ -300,13 +302,40 @@ async function cmdGatewayStart(configPath, foreground, timeoutMs) {
     const config = loadConfig(configPath);
     const { Gateway } = await import("./gateway/gateway.js");
     const gateway = new Gateway(config, configPath);
-    const shutdown = async () => {
-        console.log("\n[BEIGE] Shutting down...");
-        await gateway.stop();
-        process.exit(0);
+    let isShuttingDown = false;
+    const shutdown = async (signal) => {
+        // Prevent duplicate shutdowns
+        if (isShuttingDown)
+            return;
+        isShuttingDown = true;
+        // Use original stderr.write to bypass timestamp buffering for immediate feedback
+        originalStderrWrite(`\n[BEIGE] Received ${signal} - Shutting down...\n`);
+        // Force exit after 10 seconds if shutdown hangs
+        const timeout = setTimeout(() => {
+            originalStderrWrite("[BEIGE] Shutdown timed out, forcing exit...\n");
+            process.exit(1);
+        }, 10000);
+        try {
+            await gateway.stop();
+            clearTimeout(timeout);
+            originalStderrWrite("[BEIGE] Shutdown complete\n");
+            process.exit(0);
+        }
+        catch (err) {
+            clearTimeout(timeout);
+            originalStderrWrite(`[BEIGE] Shutdown error: ${err.message}\n`);
+            process.exit(1);
+        }
     };
-    process.on("SIGINT", shutdown);
-    process.on("SIGTERM", shutdown);
+    // Log that signal handlers are being registered (helps debug signal issues)
+    originalStderrWrite("[BEIGE] Registering signal handlers...\n");
+    // Register handlers with explicit listener count check
+    process.on("SIGINT", () => shutdown("SIGINT"));
+    process.on("SIGTERM", () => shutdown("SIGTERM"));
+    // Verify handlers are registered
+    const sigintListeners = process.listenerCount("SIGINT");
+    const sigtermListeners = process.listenerCount("SIGTERM");
+    originalStderrWrite(`[BEIGE] Signal handlers registered (SIGINT: ${sigintListeners}, SIGTERM: ${sigtermListeners})\n`);
     // SIGHUP → graceful in-place restart (reload config, recreate sandboxes)
     process.on("SIGHUP", () => {
         console.log("[BEIGE] Received SIGHUP — restarting gateway...");
@@ -341,27 +370,84 @@ function cmdGatewayStop() {
         process.exit(1);
     }
 }
-function cmdGatewayRestart() {
+async function cmdGatewayRestart(configPath, timeoutMs) {
     const pid = readPid();
-    if (pid === null) {
-        console.log("[BEIGE] No PID file found — gateway is not running");
-        console.log("[BEIGE] Run 'beige gateway start' to start it");
-        process.exit(1);
-    }
-    if (!isRunning(pid)) {
-        console.log(`[BEIGE] Gateway (PID ${pid}) is not running`);
-        console.log("[BEIGE] Run 'beige gateway start' to start it");
-        process.exit(1);
+    // If not running, just start it
+    if (pid === null || !isRunning(pid)) {
+        console.log("[BEIGE] Gateway is not running — starting it...");
+        await cmdGatewayStart(configPath, false, timeoutMs);
+        return;
     }
+    // Gateway is running — perform graceful restart
+    console.log(`[BEIGE] Restarting gateway (PID ${pid})...`);
+    const { loadConfig } = await import("./config/loader.js");
+    const config = loadConfig(configPath);
+    const port = config.gateway?.port ?? 7433;
+    const host = config.gateway?.host ?? "127.0.0.1";
+    const healthUrl = `http://${host}:${port}/api/health`;
+    // Send SIGHUP to trigger restart
     try {
         process.kill(pid, "SIGHUP");
-        console.log(`[BEIGE] Sent SIGHUP to gateway (PID ${pid}) — graceful restart initiated`);
-        console.log(`[BEIGE] Follow progress with: beige gateway logs -f`);
     }
     catch (err) {
         console.error(`[BEIGE] Failed to signal gateway (PID ${pid}):`, err);
         process.exit(1);
     }
+    // Wait for restart to complete
+    const success = await waitForGatewayRestart(pid, healthUrl, timeoutMs);
+    if (success) {
+        console.log(`[BEIGE] Gateway restarted successfully`);
+    }
+    else {
+        console.error(`[BEIGE] Gateway restart timed out after ${timeoutMs / 1000}s`);
+        console.error(`[BEIGE] Check logs: ${getLogFile()}`);
+        process.exit(1);
+    }
+}
+/**
+ * Wait for gateway restart to complete.
+ *
+ * The restart cycle is: healthy → unhealthy (teardown) → healthy (startup)
+ * We need to see it go from healthy to unhealthy and back to healthy.
+ */
+async function waitForGatewayRestart(childPid, healthUrl, timeoutMs) {
+    const startTime = Date.now();
+    const pollIntervalMs = 500;
+    let seenHealthy = false;
+    let seenUnhealthy = false;
+    const checkHealth = async () => {
+        try {
+            const res = await fetch(healthUrl, { method: "GET", signal: AbortSignal.timeout(2000) });
+            return res.ok;
+        }
+        catch {
+            return false;
+        }
+    };
+    while (Date.now() - startTime < timeoutMs) {
+        // Check if child process exited unexpectedly
+        if (!isRunning(childPid)) {
+            console.log("[BEIGE] Gateway process exited during restart");
+            return false;
+        }
+        const healthy = await checkHealth();
+        if (healthy) {
+            if (seenUnhealthy) {
+                // We saw it go down and come back up - restart complete!
+                return true;
+            }
+            seenHealthy = true;
+        }
+        else {
+            if (seenHealthy) {
+                // We saw it go down after being up - restart in progress
+                seenUnhealthy = true;
+                console.log("[BEIGE] Gateway tearing down...");
+            }
+        }
+        await new Promise((r) => setTimeout(r, pollIntervalMs));
+    }
+    return false;
 }
 function cmdGatewayStatus() {
     const pid = readPid();
@@ -419,7 +505,7 @@ Usage:
   beige setup                            First-time setup (copies tools, writes default config)
   beige gateway <command>                Manage the gateway daemon
   beige tui [agent]                      Connect TUI to running gateway
-  beige tools <command>                  Manage tools (install, list, update, remove)
+  beige plugins <command>                Manage plugins (install, list, update, remove)
 
 Options:
   -c, --config <path>        Config file (default: ~/.beige/config.json5)
@@ -428,26 +514,26 @@ Options:
   -h, --help                 Show this help
 
 Run 'beige gateway' for gateway-specific commands.
-Run 'beige tools' for tool management commands.
+Run 'beige plugins' for plugin management commands.
 `);
 }
-function printToolsHelp() {
+function printPluginsHelp() {
     console.log(`
-Beige — Tool commands
+Beige — Plugin commands
 
 Usage:
-  beige tools install <source>           Install tools from a source
-  beige tools list                       List installed tools
-  beige tools remove <name>              Remove an installed tool
-  beige tools update [name]              Update a tool (or all tools)
+  beige plugins install <source>         Install plugins from a source
+  beige plugins list                     List installed plugins
+  beige plugins remove <name>            Remove an installed plugin
+  beige plugins update [name]            Update a plugin (or all plugins)
 
 Install sources:
   npm:@scope/package                     NPM package (latest)
   npm:@scope/package@1.2.3              NPM package (specific version)
-  github:owner/repo                      GitHub repository (all tools)
-  github:owner/repo/path/to/tool        Single tool from a GitHub subfolder
+  github:owner/repo                      GitHub repository (all plugins)
+  github:owner/repo/path/to/plugin      Single plugin from a GitHub subfolder
   github:owner/repo#tag                  GitHub repository at a tag/branch
-  ./path/to/tool                         Local directory
+  ./path/to/plugin                       Local directory
 
 Options:
   --force, -f                Force install even with conflicts
@@ -462,14 +548,14 @@ Usage:
   beige gateway start                    Start the gateway daemon
   beige gateway start --foreground       Start the gateway in the foreground
   beige gateway stop                     Stop the gateway daemon
-  beige gateway restart                  Gracefully restart the gateway (drain, reload config, recreate sandboxes)
+  beige gateway restart                  Gracefully restart the gateway (or start if not running)
   beige gateway status                   Show gateway daemon status
   beige gateway logs                     Show gateway logs
   beige gateway logs -f                  Follow gateway logs
 
 Options:
   -c, --config <path>        Config file (default: ~/.beige/config.json5)
-  --timeout <seconds>        Startup wait timeout in seconds (default: 60, 0 = indefinite)
+  --timeout <seconds>        Startup/restart wait timeout in seconds (default: 60, 0 = indefinite)
   -h, --help                 Show this help
 `);
 }
@@ -527,8 +613,21 @@ function parseArgs() {
         }
         if (sub === "stop")
             return { kind: "gateway-stop" };
-        if (sub === "restart")
-            return { kind: "gateway-restart" };
+        if (sub === "restart") {
+            let timeoutMs = 60000;
+            const timeoutIdx = rest.findIndex((a) => a.startsWith("--timeout"));
+            if (timeoutIdx !== -1) {
+                const arg = rest[timeoutIdx];
+                const raw = arg.includes("=") ? arg.split("=")[1] : rest[timeoutIdx + 1];
+                const parsed = Number(raw);
+                if (isNaN(parsed) || parsed < 0) {
+                    console.error(`[BEIGE] Invalid --timeout value: ${raw}. Must be a non-negative number (0 = indefinite).`);
+                    process.exit(1);
+                }
+                timeoutMs = parsed * 1000;
+            }
+            return { kind: "gateway-restart", timeoutMs };
+        }
         if (sub === "status")
             return { kind: "gateway-status" };
         if (sub === "logs") {
@@ -546,37 +645,37 @@ function parseArgs() {
         const force = args.includes("--force") || args.includes("-f");
         return { kind: "setup", force };
     }
-    if (cmd === "tools") {
+    if (cmd === "plugins") {
         if (!sub || sub === "--help" || sub === "-h") {
-            printToolsHelp();
+            printPluginsHelp();
             process.exit(0);
         }
         if (sub === "install") {
             const source = rest[0];
             if (!source || source === "--help" || source === "-h") {
-                printToolsHelp();
+                printPluginsHelp();
                 process.exit(source === "--help" || source === "-h" ? 0 : 1);
             }
             const force = rest.includes("--force") || rest.includes("-f");
             return { kind: "install", source, force };
         }
         if (sub === "list") {
-            return { kind: "tools-list" };
+            return { kind: "plugins-list" };
         }
         if (sub === "remove") {
             const name = rest[0];
             if (!name) {
-                console.error("[BEIGE] Missing tool name. Usage: beige tools remove <name>");
+                console.error("[BEIGE] Missing plugin name. Usage: beige plugins remove <name>");
                 process.exit(1);
             }
-            return { kind: "tools-remove", name };
+            return { kind: "plugins-remove", name };
         }
         if (sub === "update") {
-            const name = rest[0]; // optional — if omitted, update all
-            return { kind: "tools-update", name };
+            const name = rest[0];
+            return { kind: "plugins-update", name };
         }
-        console.error(`[BEIGE] Unknown tools subcommand: ${sub}`);
-        printToolsHelp();
+        console.error(`[BEIGE] Unknown plugins subcommand: ${sub}`);
+        printPluginsHelp();
         process.exit(1);
     }
     console.error(`[BEIGE] Unknown command: ${cmd}`);
@@ -602,7 +701,7 @@ else if (mode.kind === "gateway-stop") {
     cmdGatewayStop();
 }
 else if (mode.kind === "gateway-restart") {
-    cmdGatewayRestart();
+    await cmdGatewayRestart(configPath, mode.timeoutMs);
 }
 else if (mode.kind === "gateway-status") {
     cmdGatewayStatus();
@@ -645,21 +744,21 @@ else if (mode.kind === "tui") {
 else if (mode.kind === "install") {
     await cmdInstall(mode.source, mode.force);
 }
-else if (mode.kind === "tools-list") {
-    cmdToolsList();
+else if (mode.kind === "plugins-list") {
+    cmdPluginsList();
 }
-else if (mode.kind === "tools-remove") {
-    cmdToolsRemove(mode.name);
+else if (mode.kind === "plugins-remove") {
+    cmdPluginsRemove(mode.name);
 }
-else if (mode.kind === "tools-update") {
-    await cmdToolsUpdate(mode.name);
+else if (mode.kind === "plugins-update") {
+    await cmdPluginsUpdate(mode.name);
 }
 async function cmdInstall(source, force) {
     console.log(`[BEIGE] Installing from: ${source}`);
-    const result = await installTools(source, { force });
+    const result = await installPlugins(source, { force });
     if (!result.success) {
         if (result.conflicts && result.conflicts.length > 0) {
-            console.error("[BEIGE] Tool name conflicts detected:");
+            console.error("[BEIGE] Plugin name conflicts detected:");
             for (const conflict of result.conflicts) {
                 console.error(`  - ${conflict}`);
             }
@@ -670,48 +769,48 @@ async function cmdInstall(source, force) {
         }
         process.exit(1);
     }
-    if (result.tools && result.tools.length > 0) {
-        console.log(`[BEIGE] Installed ${result.tools.length} tool(s):`);
-        for (const tool of result.tools) {
-            console.log(`  - ${tool.name}: ${tool.manifest.description}`);
+    if (result.plugins && result.plugins.length > 0) {
+        console.log(`[BEIGE] Installed ${result.plugins.length} plugin(s) and added to config.json5:`);
+        for (const plugin of result.plugins) {
+            console.log(`  - ${plugin.name}: ${plugin.manifest.description}`);
         }
-        console.log(`\n[BEIGE] Add tools to your agent's 'tools' array to enable them.`);
+        console.log(`\n[BEIGE] Add plugin tools to your agent's 'tools' array and restart the gateway.`);
+        console.log(`[BEIGE] Review config.json5 to fill in any required config values (e.g. API keys).`);
     }
 }
-function cmdToolsList() {
-    const tools = listInstalledTools();
-    if (tools.length === 0) {
-        console.log("[BEIGE] No tools installed.");
-        console.log("\n[BEIGE] Install tools with: beige tools install <source>");
+function cmdPluginsList() {
+    const plugins = listPluginsFromConfig();
+    if (plugins.length === 0) {
+        console.log("[BEIGE] No plugins in config.");
+        console.log("\n[BEIGE] Install plugins with: beige plugins install <source>");
         return;
     }
-    console.log("[BEIGE] Installed tools:\n");
-    for (const tool of tools) {
-        const meta = readMetaFile(tool.name);
-        const source = meta?.source ?? "unknown";
-        console.log(`  ${tool.name}`);
-        console.log(`    ${tool.manifest.description}`);
-        console.log(`    Source: ${source}`);
-        if (meta?.package) {
-            console.log(`    Package: ${meta.package}`);
-        }
+    console.log("[BEIGE] Plugins in config.json5:\n");
+    for (const plugin of plugins) {
+        console.log(`  ${plugin.name}`);
+        if (plugin.path)
+            console.log(`    Path: ${plugin.path}`);
+        if (plugin.source)
+            console.log(`    Source: ${plugin.source}`);
+        if (plugin.hasConfig)
+            console.log(`    Config: ✓ (has config values)`);
         console.log();
     }
 }
-function cmdToolsRemove(name) {
-    const result = removeTool(name);
+function cmdPluginsRemove(name) {
+    const result = removePlugin(name);
     if (!result.success) {
         console.error(`[BEIGE] ${result.error}`);
         process.exit(1);
     }
-    console.log(`[BEIGE] Removed tool: ${name}`);
+    console.log(`[BEIGE] Removed plugin '${name}' from config.json5 and disk.`);
 }
-async function cmdToolsUpdate(name) {
+async function cmdPluginsUpdate(name) {
     if (name) {
-        console.log(`[BEIGE] Updating tool: ${name}`);
-        const result = await updateTool(name);
+        console.log(`[BEIGE] Updating plugin: ${name}`);
+        const result = await updatePlugin(name);
         if (result.success) {
-            console.log(`[BEIGE] Updated ${result.tools?.length ?? 0} tool(s) from same source.`);
+            console.log(`[BEIGE] Updated ${result.plugins?.length ?? 0} plugin(s) from same source.`);
         }
         else {
             console.error(`[BEIGE] Failed to update: ${result.error}`);
@@ -719,14 +818,13 @@ async function cmdToolsUpdate(name) {
         }
         return;
     }
-    // Update all
-    const tools = listInstalledTools();
-    if (tools.length === 0) {
-        console.log("[BEIGE] No tools installed.");
+    const plugins = listPluginsFromConfig();
+    if (plugins.length === 0) {
+        console.log("[BEIGE] No plugins in config.");
         return;
     }
-    console.log(`[BEIGE] Updating all installed tools...\n`);
-    const result = await updateAllTools();
+    console.log(`[BEIGE] Updating all plugins with _source...\n`);
+    const result = await updateAllPlugins();
     console.log(`\n[BEIGE] Update complete: ${result.updated.length} updated, ${result.failed.length} failed.`);
     for (const f of result.failed) {
         console.error(`  Failed: ${f.source} — ${f.error}`);