openbot 0.4.6 → 0.5.4

package/docs/plugins.md

@@ -39,6 +39,14 @@ same agent into a single map and passes it to every plugin via `context.tools`.
 Runtime plugins read it; tool plugins ignore it. First plugin wins on tool
 name collisions.
 
+### Tool results
+
+When a tool handler finishes, yield `action:<tool>:result` with
+`data.output: string`. The OpenBot runtime feeds that string back into the
+model as the tool result (`history.ts`). Structured fields (e.g. `list`,
+`success`) are fine alongside it, but without `output` the model only sees
+`"No output"`.
+
 ## Built-in plugins
 
 | Id              | Role       | Notes                                                     |
@@ -49,6 +57,7 @@ name collisions.
 | `bash`          | Tool       | `bash` (inbuilt in `openbot`)                             |
 | `storage`       | Tool       | `create_channel`, `patch_*`, ... (inbuilt in `openbot`)   |
 | `memory`        | Tool       | `remember`, `recall`, `forget` (inbuilt in `openbot`)     |
+| `todo`          | Tool       | `todo_write`, `todo_read` (inbuilt in `openbot`)          |
 | `plugin-manager`| Infra      | Marketplace list, npm plugin install/uninstall, agent install |
 
 ## Batteries-included: `openbot` runtime
@@ -58,6 +67,7 @@ to be isolated and self-contained, providing a core ecosystem of inbuilt tools:
 
 - **Bash**: Stateful system tasks and file operations.
 - **Memory**: Long-term durable fact storage.
+- **Todo**: Thread-scoped multi-step task checklist.
 - **Storage**: Channel and thread management.
 - **Delegation**: Calling upon other specialized agents.
 - **Approval**: Gating protected actions behind UI confirmation.
@@ -71,7 +81,7 @@ plugins:
     config:
       model: openai/gpt-4o-mini
       approval:
-        actions: [action:bash, action:create_channel]
+        actions: [action:shell_exec, action:create_channel]
 ```
 
 A community plugin is just an npm package whose default export matches the
@@ -90,11 +100,11 @@ On first use OpenBot installs the package into
 
 ## Approval plugin
 
-The `approval` plugin gates protected tool calls behind a UI confirmation widget. By default, it gates `action:bash`.
+The `approval` plugin gates protected tool calls behind a UI confirmation widget. By default, it gates `action:shell_exec`.
 
 ```yaml
 plugins:
   - id: approval
     config:
-      actions: [action:bash]
+      actions: [action:shell_exec]
 ```

package/docs/templates/AGENT.example.md

@@ -28,7 +28,7 @@ plugins:
   - id: storage
   - id: approval
     config:
-      actions: [action:bash]
+      actions: [action:shell_exec]
 ---
 
 <!--

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "openbot",
-  "version": "0.4.6",
+  "version": "0.5.4",
   "private": false,
   "type": "module",
   "engines": {
@@ -9,7 +9,9 @@
   "scripts": {
     "dev": "tsx watch src/app/cli.ts start",
     "build": "tsc && mkdir -p dist/assets && cp src/assets/icon.svg dist/assets/icon.svg",
-    "start": "node dist/app/cli.js start"
+    "start": "node dist/app/cli.js start",
+    "format": "prettier --write .",
+    "push": "fly deploy --build-only --push --config deploy/fly.toml -a openbot-runtime --image-label v0.5.4"
   },
   "bin": {
     "openbot": "./dist/app/cli.js"
@@ -34,6 +36,7 @@
     "@types/express": "^4.17.21",
     "@types/js-yaml": "^4.0.9",
     "@types/node": "^20.10.1",
+    "prettier": "^3.4.2",
     "tsx": "^4.21.0",
     "typescript": "^5.9.3"
   }

package/pnpm-workspace.yaml

@@ -0,0 +1,2 @@
+allowBuilds:
+  esbuild: true

package/src/app/bootstrap.ts

@@ -0,0 +1,43 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import {
+  CONFIG_FILE,
+  DEFAULT_AGENTS_DIR,
+  DEFAULT_CHANNELS_DIR,
+  DEFAULT_PLUGINS_DIR,
+  getBaseDir,
+  getChannelsWorkspaceRoot,
+  getConfigDir,
+  type OpenBotconfig,
+} from './config.js';
+
+/** Ensure data directories and a minimal config exist (first boot on a Fly volume). */
+export async function bootstrap(): Promise<void> {
+  const baseDir = getBaseDir();
+  const configDir = getConfigDir();
+
+  await fs.mkdir(path.join(baseDir, DEFAULT_AGENTS_DIR), { recursive: true });
+  await fs.mkdir(path.join(baseDir, DEFAULT_PLUGINS_DIR), { recursive: true });
+  await fs.mkdir(path.join(baseDir, DEFAULT_CHANNELS_DIR), { recursive: true });
+  await fs.mkdir(getChannelsWorkspaceRoot(), { recursive: true });
+  await fs.mkdir(configDir, { recursive: true, mode: 0o700 });
+
+  const configPath = path.join(configDir, CONFIG_FILE);
+  try {
+    await fs.access(configPath);
+  } catch {
+    const initial: OpenBotconfig = { baseDir };
+
+    const publicUrl = process.env.OPENBOT_PUBLIC_URL?.trim();
+    if (publicUrl) {
+      initial.publicUrl = publicUrl.replace(/\/$/, '');
+    }
+
+    const workspaceDir = process.env.OPENBOT_CHANNELS_WORKSPACE_DIR?.trim();
+    if (workspaceDir) {
+      initial.channelsWorkspaceDir = getChannelsWorkspaceRoot();
+    }
+
+    await fs.writeFile(configPath, JSON.stringify(initial, null, 2), { mode: 0o600 });
+  }
+}

package/src/app/cli.ts

@@ -1,5 +1,6 @@
 #!/usr/bin/env node
 import { Command } from 'commander';
+import { bootstrap } from './bootstrap.js';
 import { startServer } from './server.js';
 
 const program = new Command();
@@ -25,13 +26,14 @@ function checkNodeVersion() {
 
 checkNodeVersion();
 
-program.name('openbot').description('OpenBot CLI').version('0.4.6');
+program.name('openbot').description('OpenBot CLI').version('0.5.4');
 
 program
   .command('start')
   .description('Start the OpenBot harness')
   .option('-p, --port <number>', 'Port to listen on')
   .action(async (options) => {
+    await bootstrap();
     await startServer(options);
   });
 

package/src/app/cloud-mode.ts

@@ -0,0 +1,41 @@
+import { ORCHESTRATOR_AGENT_ID } from './agent-ids.js';
+
+/** Platform-managed OpenBot (Fly + integrations proxy). Self-hosted when unset. */
+export const isCloudMode = (): boolean => process.env.OPENBOT_CLOUD_MODE === '1';
+
+/** Platform-managed coordinator model for cloud workspaces. */
+export const COORDINATOR_MODEL = 'openbot/coordinator-1';
+
+/** Default cloud system agent model. */
+export const CLOUD_SYSTEM_MODEL = COORDINATOR_MODEL;
+
+export interface CloudIntegrationsConfig {
+  baseUrl: string;
+  token: string;
+}
+
+export function getCloudIntegrationsConfig(): CloudIntegrationsConfig | null {
+  if (!isCloudMode()) return null;
+
+  const baseUrl = process.env.OPENBOT_INTEGRATIONS_BASE_URL?.trim();
+  const token = process.env.OPENBOT_INTEGRATIONS_TOKEN?.trim();
+  if (!baseUrl || !token) return null;
+
+  return { baseUrl: baseUrl.replace(/\/$/, ''), token };
+}
+
+export function isCloudSystemAgent(agentId: string): boolean {
+  return isCloudMode() && agentId === ORCHESTRATOR_AGENT_ID;
+}
+
+export function resolveCloudSystemModel(configModel: string | undefined): string {
+  return configModel?.trim() || COORDINATOR_MODEL;
+}
+
+export function assertCloudSystemAgentPluginsMutable(
+  agentId: string,
+  plugins: unknown,
+): void {
+  void agentId;
+  void plugins;
+}

package/src/app/config.ts

@@ -8,6 +8,8 @@ export interface OpenBotconfig {
   model?: string;
   image?: string;
   baseDir?: string;
+  /** Parent directory for per-channel working directories (user-facing workspace). */
+  channelsWorkspaceDir?: string;
   port?: number;
   /**
    * Overrides the default public marketplace registry URL. If omitted or blank,
@@ -41,52 +43,102 @@ export function resolvePath(p: string) {
   return p.startsWith('~/') ? path.join(os.homedir(), p.slice(2)) : path.resolve(p);
 }
 
+function readConfigFile(configDir: string): OpenBotconfig {
+  const configPath = path.join(configDir, CONFIG_FILE);
+  if (fs.existsSync(configPath)) {
+    try {
+      return JSON.parse(fs.readFileSync(configPath, 'utf-8')) as OpenBotconfig;
+    } catch (error) {
+      console.error(`Warning: Failed to parse config at ${configPath}`, error);
+    }
+  }
+  return {};
+}
+
+/** Directory that holds `config.json` (env `OPENBOT_BASE_DIR` or `~/.openbot`). */
+export function getConfigDir(): string {
+  const envBase = process.env.OPENBOT_BASE_DIR?.trim();
+  if (envBase) {
+    return resolvePath(envBase);
+  }
+  return path.join(os.homedir(), '.openbot');
+}
+
+/** Resolved OpenBot data root (agents, channels, plugins, variables). */
+export function getBaseDir(): string {
+  const envBase = process.env.OPENBOT_BASE_DIR?.trim();
+  if (envBase) {
+    return resolvePath(envBase);
+  }
+  const fileConfig = readConfigFile(getConfigDir());
+  return resolvePath(fileConfig.baseDir || DEFAULT_BASE_DIR);
+}
+
+/** Resolved parent directory for per-channel workspace folders. */
+export function getChannelsWorkspaceRoot(): string {
+  const env = process.env.OPENBOT_CHANNELS_WORKSPACE_DIR?.trim();
+  if (env) {
+    return resolvePath(env);
+  }
+  const fileConfig = readConfigFile(getConfigDir());
+  if (fileConfig.channelsWorkspaceDir) {
+    return resolvePath(fileConfig.channelsWorkspaceDir);
+  }
+  return resolvePath(DEFAULT_CHANNELS_WORKSPACE_DIR);
+}
+
 /** Default absolute cwd for a channel when none is provided at creation time. */
 export function getDefaultChannelCwd(channelId: string): string {
   const id = channelId.trim();
   if (!id) {
     throw new Error('channelId is required');
   }
-  return resolvePath(`${DEFAULT_CHANNELS_WORKSPACE_DIR}/${id}`);
+  return path.join(getChannelsWorkspaceRoot(), id);
 }
 
 export function loadConfig(): OpenBotconfig {
-  const configPath = path.join(os.homedir(), '.openbot', CONFIG_FILE);
-  if (fs.existsSync(configPath)) {
-    try {
-      return JSON.parse(fs.readFileSync(configPath, 'utf-8'));
-    } catch (error) {
-      console.error(`Warning: Failed to parse config at ${configPath}`, error);
-    }
+  const fileConfig = readConfigFile(getConfigDir());
+  const merged: OpenBotconfig = { ...fileConfig };
+
+  merged.baseDir = getBaseDir();
+
+  const envPublicUrl = process.env.OPENBOT_PUBLIC_URL?.trim();
+  if (envPublicUrl) {
+    merged.publicUrl = envPublicUrl.replace(/\/$/, '');
+  } else if (merged.publicUrl) {
+    merged.publicUrl = merged.publicUrl.replace(/\/$/, '');
   }
-  return {};
+
+  merged.channelsWorkspaceDir = getChannelsWorkspaceRoot();
+
+  const envPort = process.env.PORT?.trim();
+  if (envPort && !Number.isNaN(Number(envPort))) {
+    merged.port = Number(envPort);
+  }
+
+  return merged;
 }
 
 export function saveConfig(config: Partial<OpenBotconfig>) {
-  const configDir = resolvePath(DEFAULT_BASE_DIR);
+  const configDir = getConfigDir();
   const configPath = path.join(configDir, CONFIG_FILE);
 
   if (!fs.existsSync(configDir)) {
     fs.mkdirSync(configDir, { recursive: true, mode: 0o700 });
   }
 
-  const currentConfig = loadConfig();
+  const currentConfig = readConfigFile(configDir);
   const newConfig = { ...currentConfig, ...config };
 
   fs.writeFileSync(configPath, JSON.stringify(newConfig, null, 2), { mode: 0o600 });
 }
 
 export function isConfigured(): boolean {
-  const configPath = path.join(resolvePath(DEFAULT_BASE_DIR), CONFIG_FILE);
-  return fs.existsSync(configPath);
+  return fs.existsSync(path.join(getConfigDir(), CONFIG_FILE));
 }
 
 export function loadVariables(): { version: number; variables: StoredVariable[] } {
-  const config = loadConfig();
-  const variablesPath = path.join(
-    resolvePath(config.baseDir || DEFAULT_BASE_DIR),
-    VARIABLES_FILE,
-  );
+  const variablesPath = path.join(getBaseDir(), VARIABLES_FILE);
   if (fs.existsSync(variablesPath)) {
     return JSON.parse(fs.readFileSync(variablesPath, 'utf-8')) as {
       version: number;
@@ -94,4 +146,4 @@ export function loadVariables(): { version: number; variables: StoredVariable[]
     };
   }
   return { version: 1, variables: [] };
-}
+}

package/src/app/responding-agent.ts

@@ -4,6 +4,9 @@ import { storageService } from '../plugins/storage/service.js';
 /** Thread `state.json` key for the sticky responding agent id. */
 export const THREAD_RESPONDING_AGENT_ID_KEY = 'respondingAgentId';
 
+/** Publish events that continue a pending UI interaction rather than a new user turn. */
+export const CONTINUATION_EVENT_TYPES = new Set(['client:ui:widget:response']);
+
 export type ResolveRespondingAgentOptions = {
   channelId: string;
   threadId?: string;
@@ -20,6 +23,14 @@ export type ResolveRespondingAgentResult = {
   overridden: boolean;
 };
 
+const readMetaAgentId = (meta: unknown): string | undefined => {
+  if (!meta || typeof meta !== 'object') return undefined;
+  const value = (meta as Record<string, unknown>).agentId;
+  if (typeof value !== 'string') return undefined;
+  const trimmed = value.trim();
+  return trimmed || undefined;
+};
+
 const readBoundAgentId = (state: unknown): string | undefined => {
   if (!state || typeof state !== 'object') return undefined;
   const value = (state as Record<string, unknown>)[THREAD_RESPONDING_AGENT_ID_KEY];
@@ -72,3 +83,38 @@ export async function resolveRespondingAgentId(
 
   return { agentId: fallback, bound: true, overridden: false };
 }
+
+export type ResolvePublishTargetAgentOptions = {
+  eventType: string;
+  channelId: string;
+  threadId?: string;
+  requestedAgentId?: string;
+  eventMeta?: unknown;
+  bindIfUnbound?: boolean;
+};
+
+/**
+ * Resolves the agent that should handle a publish event.
+ * UI continuations route to the widget origin agent; everything else uses sticky thread binding.
+ */
+export async function resolvePublishTargetAgentId(
+  options: ResolvePublishTargetAgentOptions,
+): Promise<{ agentId: string } | { error: 'agentId_required' }> {
+  const { eventType, channelId, threadId, requestedAgentId, eventMeta, bindIfUnbound } = options;
+
+  if (CONTINUATION_EVENT_TYPES.has(eventType)) {
+    const originAgentId = readMetaAgentId(eventMeta) || requestedAgentId?.trim();
+    if (!originAgentId) {
+      return { error: 'agentId_required' };
+    }
+    return { agentId: originAgentId };
+  }
+
+  const resolved = await resolveRespondingAgentId({
+    channelId,
+    threadId,
+    requestedAgentId,
+    bindIfUnbound,
+  });
+  return { agentId: resolved.agentId };
+}

package/src/app/server.ts

@@ -8,7 +8,8 @@ import { createRequire } from 'module';
 const require = createRequire(import.meta.url);
 const pkg = require('../../package.json');
 import { generateId } from 'melony';
-import { DEFAULT_BASE_DIR, loadConfig, resolvePath } from '../app/config.js';
+import { getBaseDir, loadConfig } from '../app/config.js';
+import { isCloudMode, getCloudIntegrationsConfig } from './cloud-mode.js';
 import { ActiveRunsSnapshotEvent, OpenBotEvent, OpenBotState } from './types.js';
 import { processService } from '../services/process.js';
 import { runAgent, STATE_AGENT_ID, ORCHESTRATOR_AGENT_ID } from '../harness/index.js';
@@ -21,7 +22,7 @@ import {
 } from '../plugins/storage/files.js';
 import { ensureEventId, openBotEventFromQuery } from './utils.js';
 import { abortRegistry, abortKey } from '../services/abort.js';
-import { resolveRespondingAgentId } from './responding-agent.js';
+import { resolvePublishTargetAgentId, resolveRespondingAgentId } from './responding-agent.js';
 import {
   DEFAULT_UNCATEGORIZED_SPEC,
   UNCATEGORIZED_CHANNEL_ID,
@@ -46,8 +47,14 @@ export async function startServer(options: ServerOptions = {}) {
   const config = loadConfig();
   processService.syncWorkspaceVariablesToProcessEnv();
 
-  const baseDir = config.baseDir || DEFAULT_BASE_DIR;
-  const openBotDir = resolvePath(baseDir);
+  if (isCloudMode()) {
+    const integrations = getCloudIntegrationsConfig();
+    console.log(
+      `[server] Cloud mode enabled${integrations ? '' : ' (integrations proxy env not set)'}`,
+    );
+  }
+
+  const openBotDir = getBaseDir();
   const PORT = Number(options.port ?? config.port ?? process.env.PORT ?? 4132);
   const app = express();
   const clients: Map<string, express.Response[]> = new Map();
@@ -247,6 +254,23 @@ export async function startServer(options: ServerOptions = {}) {
 
   app.use(cors());
 
+  const gatewayToken = process.env.OPENBOT_GATEWAY_TOKEN?.trim();
+  if (gatewayToken) {
+    app.use((req, res, next) => {
+      if (req.path === '/api/health' || req.method === 'OPTIONS') {
+        next();
+        return;
+      }
+
+      const got = req.get('x-openbot-gateway-token');
+      if (got !== gatewayToken) {
+        res.status(401).json({ error: 'unauthorized' });
+        return;
+      }
+      next();
+    });
+  }
+
   const resolvePublicBaseUrl = () => getPublicBaseUrl(PORT, config.publicUrl);
 
   app.use((req, res, next) => {
@@ -264,7 +288,7 @@ export async function startServer(options: ServerOptions = {}) {
   });
 
   app.get('/api/health', (req, res) => {
-    res.json({ status: 'ok', version: pkg.version });
+    res.json({ status: 'ok', version: pkg.version, apiVersion: 1 });
   });
 
   app.get('/api/events', (req, res) => {
@@ -561,16 +585,23 @@ export async function startServer(options: ServerOptions = {}) {
       }
 
       const bindIfUnbound = event.type === 'agent:invoke';
-      const resolved = await resolveRespondingAgentId({
+      const target = await resolvePublishTargetAgentId({
+        eventType: event.type,
         channelId,
         threadId,
         requestedAgentId: agentId,
+        eventMeta: event.meta,
         bindIfUnbound,
       });
 
+      if ('error' in target) {
+        res.status(400).json({ error: 'agentId is required for widget response' });
+        return;
+      }
+
       await runAgent({
         runId,
-        agentId: resolved.agentId,
+        agentId: target.agentId,
         event,
         channelId,
         threadId,
@@ -676,10 +707,25 @@ export async function startServer(options: ServerOptions = {}) {
     }
   });
 
-  app.listen(PORT, () => {
-    console.log(`\x1b[32mOpenBot server listening at http://localhost:${PORT}\x1b[0m`);
+  const HOST = process.env.HOST || '0.0.0.0';
+  const server = app.listen(PORT, HOST, () => {
+    console.log(`\x1b[32mOpenBot server listening at http://${HOST}:${PORT}\x1b[0m`);
     console.log(
       `🌐 Visit \x1b[96m\x1b[1mhttps://openbot.one\x1b[0m to connect to this runtime and manage everything from there. ✨`,
     );
   });
+
+  const shutdown = (signal: string) => {
+    console.log(`\n[server] Received ${signal}, shutting down...`);
+    server.close(() => {
+      process.exit(0);
+    });
+    setTimeout(() => {
+      console.error('[server] Forced shutdown after timeout');
+      process.exit(1);
+    }, 10_000).unref();
+  };
+
+  process.on('SIGTERM', () => shutdown('SIGTERM'));
+  process.on('SIGINT', () => shutdown('SIGINT'));
 }