openbot 0.4.7 → 0.5.5

package/.claude/agents/runtime-security-reviewer.md

@@ -0,0 +1,32 @@
+---
+name: runtime-security-reviewer
+description: Use proactively after changes touching server.ts, harness/index.ts, storage/service.ts, storage/files.ts, cloud-mode.ts, or plugin loading (services/plugins/registry.ts). Reviews for auth-boundary regressions, path traversal in channel/workspace file access, abort-signal correctness, and risks from dynamically loaded community plugins. Not a substitute for the general PR reviewer (pr-review-toolkit) — this agent is scoped to this repo's specific trust boundaries.
+tools: Read, Grep, Glob, Bash
+model: inherit
+---
+
+You are reviewing changes to OpenBot's runtime — a local-first, event-driven agent harness (Express + `melony`). Your job is to catch regressions in this codebase's specific trust boundaries, not general code quality (that's covered elsewhere).
+
+## What to check
+
+1. **Gateway/integrations auth** (`src/app/server.ts`, `src/app/cloud-mode.ts`)
+   - Every route except `/api/health` must stay behind the `x-openbot-gateway-token` check when `OPENBOT_GATEWAY_TOKEN` is set. Flag any new route added before that middleware, or any code path that could bypass it.
+   - `OPENBOT_INTEGRATIONS_TOKEN` / `OPENBOT_GATEWAY_TOKEN` must never be logged, echoed in error responses, or forwarded to a client.
+
+2. **Path traversal in file/workspace access** (`src/plugins/storage/files.ts`, `src/plugins/storage/service.ts`)
+   - Any `channelId` or `path` value that originates from a request (query, body, header) and is joined into a filesystem path must be validated to stay within `getChannelsWorkspaceRoot()` / the channel's directory. Look for `path.join`/`path.resolve` calls on user-controlled input without a containment check (e.g. resolved path still starting with the expected root).
+   - This applies to upload, write, serve-file, and stat code paths in `server.ts` and the storage service.
+
+3. **Abort-signal correctness** (`src/harness/index.ts`, `src/services/abort.ts`)
+   - A run's `abortSignal` must be acquired and released symmetrically (`abortRegistry.acquire`/`release`) even on thrown errors.
+   - Delegated sub-agent runs sharing a `channelId:threadId` key must observe the same abort signal — check that new delegation paths don't spin up runs outside `runAgent` (which would miss abort wiring).
+
+4. **Dynamic plugin loading** (`src/services/plugins/registry.ts`)
+   - `resolvePlugin` imports and executes arbitrary code from `~/.openbot/plugins/<id>/dist/index.js`. Flag any change that widens what ids/paths can be resolved (e.g. accepting an absolute path or `..` in `id`) without equivalent validation to the existing built-in/npm-name assumption.
+
+5. **Event persistence & injection**
+   - Events written via `storageService.storeEvent` / echoed over SSE should not allow arbitrary control characters or unbounded payloads to break the `data: ...\n\n` SSE framing (check any code constructing SSE payloads outside the existing `sendToClientKey` helper).
+
+## Output
+
+For each finding: file:line, what invariant it breaks, and a concrete input/request that would exploit it. If nothing in the diff touches these boundaries, say so briefly — don't invent findings.

package/.claude/hooks/format.sh

@@ -0,0 +1,18 @@
+#!/usr/bin/env bash
+# PostToolUse: format the edited file with Prettier if it's a type Prettier handles.
+set -euo pipefail
+
+file_path=$(jq -r '.tool_input.file_path // empty')
+[ -z "$file_path" ] && exit 0
+[ -f "$file_path" ] || exit 0
+
+case "$file_path" in
+  *.ts|*.tsx|*.js|*.jsx|*.json|*.md|*.yml|*.yaml)
+    ;;
+  *)
+    exit 0
+    ;;
+esac
+
+npx --no-install prettier --write "$file_path" >/dev/null 2>&1 || true
+exit 0

package/.claude/hooks/protect-secrets.sh

@@ -0,0 +1,23 @@
+#!/usr/bin/env bash
+# PreToolUse: block edits to env files and local git config (which can hold credentials).
+set -euo pipefail
+
+file_path=$(jq -r '.tool_input.file_path // empty')
+[ -z "$file_path" ] && exit 0
+
+base=$(basename "$file_path")
+case "$base" in
+  .env|.env.*)
+    echo "Blocked: editing $file_path is not allowed (env file may contain secrets)." >&2
+    exit 2
+    ;;
+esac
+
+case "$file_path" in
+  */.git/config|.git/config)
+    echo "Blocked: editing .git/config is not allowed (may contain credentials in the remote URL)." >&2
+    exit 2
+    ;;
+esac
+
+exit 0

package/.claude/settings.json

@@ -0,0 +1,26 @@
+{
+  "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "Edit|Write",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bash .claude/hooks/protect-secrets.sh"
+          }
+        ]
+      }
+    ],
+    "PostToolUse": [
+      {
+        "matcher": "Edit|Write",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bash .claude/hooks/format.sh"
+          }
+        ]
+      }
+    ]
+  }
+}

package/.claude/skills/deploy/SKILL.md

@@ -0,0 +1,26 @@
+---
+name: deploy
+description: Build and push a new OpenBot runtime image to Fly.io, following this repo's release process.
+disable-model-invocation: true
+---
+
+# Deploy
+
+Releases a new OpenBot runtime image for the `openbot-runtime` Fly.io app.
+
+## Steps
+
+1. Confirm the working tree is clean and on the intended branch (`git status`).
+2. Bump the version in [package.json](../../../package.json) if this is a real release (the CLI reports this version via `--version` and `/api/health`).
+3. Update the `--image-label` in the `push` script in [package.json](../../../package.json) to match, and update the version string in [src/app/cli.ts](../../../src/app/cli.ts).
+4. Run the build + push:
+   ```bash
+   npm run push
+   ```
+   This runs `fly deploy --build-only --push --config deploy/fly.toml -a openbot-runtime --image-label v<version>` — it builds and pushes the image but does **not** deploy it to a running app (`--build-only`). Actually rolling a tenant onto the new image is a control-plane action outside this repo (see [deploy/README.md](../../../deploy/README.md) for the tenant deploy sequence).
+5. Confirm the push succeeded and note the image label for whoever triggers the control-plane rollout.
+
+## Notes
+
+- This is a shared image used across tenant Fly apps (one app per tenant, one persistent volume each) — pushing here does not affect any running instance until a control-plane deploy references the new label.
+- Never run `fly deploy` without `--build-only` from this repo; a bare deploy would need an `-a <app>` targeting a specific tenant app, which isn't this repo's job.

package/.claude/skills/new-plugin/SKILL.md

@@ -0,0 +1,46 @@
+---
+name: new-plugin
+description: Scaffold a new built-in OpenBot plugin (a Plugin-shaped module under src/plugins/<name>) and register it in the built-in plugin registry.
+disable-model-invocation: true
+---
+
+# New plugin
+
+Scaffolds a new **built-in** plugin — for a community (npm-distributed) plugin, this skill doesn't apply; see [docs/plugins.md](../../../docs/plugins.md) instead.
+
+A plugin is the single extension unit on the OpenBot bus (see [docs/plugins.md](../../../docs/plugins.md)). It's just an object matching `Plugin` from [src/services/plugins/types.ts](../../../src/services/plugins/types.ts): `id`, `name`, `description`, optional `toolDefinitions`, and a `factory(context)` that returns a `MelonyPlugin`. Whether it acts as a "runtime" (handles `agent:invoke`), a "tool" (handles `action:<tool>` events, contributes `toolDefinitions`), or "middleware" (intercepts/re-emits events, like `approval`) is defined entirely by which events it subscribes to.
+
+## Steps
+
+1. Ask the user for: plugin id (kebab-case, becomes the folder name and registry key), a one-line description, and its role (tool / middleware / runtime).
+2. Create `src/plugins/<id>/index.ts`. Minimal tool-plugin shape (adapt from [src/plugins/approval/index.ts](../../../src/plugins/approval/index.ts) for middleware, or [src/plugins/bash/index.ts](../../../src/plugins/bash/index.ts) for a fuller tool example with widgets):
+
+   ```ts
+   import type { Plugin } from '../../services/plugins/types.js';
+   import { OpenBotEvent } from '../../app/types.js';
+
+   export const myPlugin: Plugin = {
+     id: 'my-plugin',
+     name: 'My Plugin',
+     description: 'One-line description of what this plugin does.',
+     toolDefinitions: {
+       my_tool: {
+         description: 'What this tool does, written for the LLM.',
+         inputSchema: {
+           /* zod schema, e.g. z.object({ foo: z.string() }) */
+         },
+       },
+     },
+     factory: ({ config, storage }) => (builder) => {
+       builder.on('action:my_tool', async function* (event, context) {
+         // handle the tool call, yield OpenBotEvent(s)
+       });
+     },
+   };
+
+   export default myPlugin;
+   ```
+
+3. Register it in [src/services/plugins/registry.ts](../../../src/services/plugins/registry.ts): import it and add `[myPlugin.id]: myPlugin` to the `BUILT_IN` map.
+4. If the plugin exposes tools, note in the description whether it's meant to be attached alongside the `openbot` runtime plugin (which merges `toolDefinitions` from every attached plugin) or is self-contained.
+5. Build (`npm run build`) to catch type errors, since there's no test suite to lean on.

package/.dockerignore

@@ -0,0 +1,9 @@
+node_modules
+dist
+.git
+.jules
+.pnpm-store
+*.md
+!deploy/*.md
+.env
+.env.*

package/.mcp.json

@@ -0,0 +1,8 @@
+{
+  "mcpServers": {
+    "context7": {
+      "type": "http",
+      "url": "https://mcp.context7.com/mcp"
+    }
+  }
+}

package/AGENTS.md

@@ -15,7 +15,7 @@ OpenBot is a local-first platform for multi-agent orchestration and coordination
 
 - `src/`: event-driven orchestration engine built on Melony.
 - Persistence is local-file based (no mandatory cloud datastore by default).
-- API surface is intentionally minimal: only `GET /api/events`, `POST /api/publish`, and `GET /api/state`.
+- API surface is intentionally minimal: `GET /api/events`, `POST /api/publish`, `GET /api/state`.
 
 ## Product Mental Model
 
@@ -34,7 +34,7 @@ OpenBot is a local-first platform for multi-agent orchestration and coordination
 
 - The server is event-first: treat HTTP routes as entry points into the event pipeline.
 - Follow Melony's event flow: `Event -> Handler -> Events`.
-- Keep the public API constrained to the three existing endpoints: `GET /api/events`, `POST /api/publish`, `GET /api/state`. Never introduce new endpoints; all functionality must be modeled through the event system.
+- Keep orchestration on `GET /api/events`, `POST /api/publish`, and `GET /api/state`.
 - Plugin changes belong in `src/plugins/*`.
 - Agent behavior and orchestration belong in agent/runtime layers, not UI code.
 - For tool-calling flows, ensure completion/result events are emitted consistently.

package/CLAUDE.md

@@ -0,0 +1,51 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+@AGENTS.md
+
+## Commands
+
+- `npm run dev` — run the CLI (`start` command) via `tsx watch`, hot-reloading on change.
+- `npm run build` — `tsc` compile to `dist/` + copy `src/assets/icon.svg` to `dist/assets`.
+- `npm run start` — run the built server (`node dist/app/cli.js start`).
+- No test suite and no lint script exist in this repo. Prettier config is `.prettierrc` (single quotes, semicolons, trailing commas, 100 print width) but there's no `format`/`lint` script — format via editor integration.
+- Package manager is pnpm (`pnpm-lock.yaml`, `pnpm-workspace.yaml`), even though `README`/`CONTRIBUTING` reference `npm`. Use `pnpm install`.
+- `npm run push` builds and pushes a Fly.io image (`deploy/fly.toml`, app `openbot-runtime`) — this is a release action, not a dev command.
+
+## Architecture
+
+OpenBot is a local-first, event-driven harness for running AI agents, built on the `melony` event-bus library. Almost everything flows through one abstraction: an **agent** is a named stack of **plugins**, and the bus doesn't distinguish "runtime" plugins from "tool" plugins — that role is defined purely by which events a plugin subscribes to / emits (see `docs/plugins.md`, `docs/agents.md`).
+
+### Request flow
+
+`src/app/server.ts` is the only HTTP surface, with three routes:
+
+- `GET /api/events` — opens an SSE stream for a `channelId`(+`threadId`), or the special `__global__` channel for active-run snapshots across all channels.
+- `POST /api/publish` — publishes an event; the common case is `agent:invoke`, which resolves a target agent and calls `runAgent` (fire-and-forget, streamed back over SSE + persisted). Also special-cased inline for file upload/write and `action:agent_run_stop`.
+- `GET /api/state` — same dispatch as `/api/publish` but synchronous (collects emitted events into a JSON response instead of streaming) and defaults to the hidden `state` agent; used for deterministic, non-LLM reads (storage plugin actions).
+
+`src/harness/index.ts` (`runAgent`) is the core execution loop for **one agent turn**: it loads `AgentDetails` and `OpenBotState` from storage, resolves every plugin referenced by the agent (`resolvePlugin`), merges their `toolDefinitions` into a shared `tools` map, builds a `melony<OpenBotState, OpenBotEvent>()` runtime by calling each plugin's `factory(context)`, and drains the resulting async generator, emitting `agent:run:start`/`agent:run:end` around it. Each run acquires a per-`channelId:threadId` `AbortSignal` from `abortRegistry` so a stop request (`action:agent_run_stop`) can cancel a parent run and any of its delegated sub-agent runs together.
+
+### Plugins (`src/plugins/*`, registered in `src/services/plugins/registry.ts`)
+
+Core built-ins: `storage` (infra handlers for `/api/state`), `plugin-manager` (marketplace + npm plugin install). The default agent runtime is **`@meetopenbot/openbot`**, a community npm package installed to `~/.openbot/plugins/@meetopenbot/openbot/` on first boot (`ensureDefaultStack`). Disk-installed plugins take precedence over built-ins in `resolvePlugin`.
+
+A `Plugin`'s `factory(context)` returns a `MelonyPlugin`; `PluginContext` carries `agentId`, `agentDetails`, per-agent `config` (from `AGENT.md` frontmatter), the shared `storage` service, the merged `tools` map, `publicBaseUrl`, the run's `abortSignal`, and `host` (platform hooks: `runAgent`, cloud auth, model registry, config).
+
+### Agents
+
+Agents are markdown files with YAML frontmatter (`~/.openbot/agents/<agentId>/AGENT.md`) listing `plugins: [{id, config}]`; the body is the system prompt. The default **`system`** orchestrator references `@meetopenbot/openbot` (materialized on first boot). Built-in agent ids in `src/app/agent-ids.ts`: `system` (orchestrator, listed) and `state` (hidden, backs `/api/state`). `system` may be customized via `agents/system/AGENT.md`; deleting that file reverts to bootstrap defaults on next start.
+
+### Storage (`src/plugins/storage/service.ts`, `src/services/plugins/domain.ts`)
+
+`storageService` is the single source of truth for agents, channels, threads, events, and files — all local-file-based under `getBaseDir()` (`~/.openbot`, or `OPENBOT_BASE_DIR`). Per-channel working directories for bash/file tools live separately under `getChannelsWorkspaceRoot()` (`~/openbot`, or `OPENBOT_CHANNELS_WORKSPACE_DIR`) — don't conflate the two roots.
+
+### Cloud mode (`src/app/cloud-mode.ts`)
+
+Set via `OPENBOT_CLOUD_MODE=1` for platform-managed (Fly.io) deployments. The `system` agent openbot plugin defaults to **credits** mode and can be switched to **BYOK** in agent config. `OPENBOT_GATEWAY_TOKEN`, when set, gates every route except `/api/health` behind an `x-openbot-gateway-token` header check (see `server.ts`) — this is how the control plane's proxy authenticates to a per-tenant instance. See `deploy/README.md` for the full env var contract and control-plane integration sequence.
+
+## Conventions
+
+- ESM throughout (`"type": "module"`, `NodeNext` module resolution) — internal imports must use `.js` extensions even though source is `.ts`.
+- Node >=20.12.0 required (enforced at CLI startup with a warning, not a hard fail).

package/Dockerfile

@@ -0,0 +1,41 @@
+# syntax=docker/dockerfile:1
+
+FROM node:22-alpine AS builder
+
+WORKDIR /app
+
+RUN corepack enable && corepack prepare pnpm@9.15.9 --activate
+
+COPY package.json pnpm-lock.yaml ./
+RUN pnpm install --frozen-lockfile
+
+COPY tsconfig.json ./
+COPY src ./src
+RUN pnpm run build
+
+FROM node:22-alpine AS runner
+
+WORKDIR /app
+
+ENV OPENBOT_BASE_DIR=/data/.openbot
+ENV OPENBOT_CHANNELS_WORKSPACE_DIR=/data/workspace
+
+RUN apk add --no-cache bash git su-exec curl \
+  && ARCH="$(uname -m)" \
+  && case "$ARCH" in x86_64) CF_ARCH=amd64 ;; aarch64) CF_ARCH=arm64 ;; *) CF_ARCH=amd64 ;; esac \
+  && curl -fsSL "https://github.com/cloudflare/cloudflared/releases/latest/download/cloudflared-linux-${CF_ARCH}" -o /usr/local/bin/cloudflared \
+  && chmod +x /usr/local/bin/cloudflared \
+  && corepack enable && corepack prepare pnpm@9.15.9 --activate
+
+COPY package.json pnpm-lock.yaml ./
+RUN pnpm install --frozen-lockfile --prod
+
+COPY --from=builder /app/dist ./dist
+COPY deploy/entrypoint.sh /entrypoint.sh
+RUN chmod +x /entrypoint.sh
+
+EXPOSE 8080
+
+USER root
+ENTRYPOINT ["/entrypoint.sh"]
+CMD ["node", "dist/app/cli.js", "start"]

package/deploy/README.md

@@ -0,0 +1,59 @@
+# Fly.io deployment
+
+One OpenBot instance per Fly app, with a persistent volume at `/data`.
+
+## Layout
+
+```
+/data/
+  .openbot/      ← OPENBOT_BASE_DIR (config, channels, agents, plugins)
+  workspace/     ← OPENBOT_CHANNELS_WORKSPACE_DIR (per-channel cwd)
+```
+
+On boot, `deploy/entrypoint.sh` runs as root to `chown -R node:node /data`, then starts OpenBot as the `node` user. The image also includes `git`, `bash`, and `cloudflared` for the bash and preview plugins.
+
+## First deploy (manual)
+
+```bash
+# From repo root
+fly apps create openbot-my-tenant
+fly volumes create openbot_data --region ord --size 1 -a openbot-my-tenant
+
+fly secrets set \
+  OPENBOT_PUBLIC_URL=https://openbot-my-tenant.fly.dev \
+  -a openbot-my-tenant
+
+# Optional: LLM API keys via Fly secrets or set later in the UI
+# fly secrets set OPENAI_API_KEY=sk-... -a openbot-my-tenant
+
+fly deploy --config deploy/fly.toml -a openbot-my-tenant
+```
+
+Copy `deploy/fly.toml`, set `app` to your tenant id, and ensure the volume name matches `openbot_data`.
+
+## Environment variables
+
+| Variable | Required | Description |
+|----------|----------|-------------|
+| `OPENBOT_BASE_DIR` | Yes (cloud) | Data root on the volume, e.g. `/data/.openbot` |
+| `OPENBOT_CHANNELS_WORKSPACE_DIR` | Yes (cloud) | Channel workspace parent, e.g. `/data/workspace` |
+| `OPENBOT_PUBLIC_URL` | Yes (cloud) | Public HTTPS URL for file links |
+| `OPENBOT_GATEWAY_TOKEN` | Yes (cloud) | Per-workspace HMAC token; gateway sends `x-openbot-gateway-token` on proxied requests |
+| `OPENBOT_CLOUD_MODE` | Yes (cloud) | Set to `1` for platform-managed OpenBot (system agent defaults to credits mode) |
+| `PORT` | Auto | Set by Fly (`8080`) |
+
+## Health check
+
+`GET /api/health` returns `{ status, version, apiVersion }`.
+
+## Control plane integration
+
+Your control plane should:
+
+1. `fly apps create openbot-{tenantId}`
+2. `fly volumes create openbot_data --region {region} --size {gb}`
+3. `fly secrets set OPENBOT_PUBLIC_URL=... OPENBOT_CLOUD_MODE=1`
+4. `fly deploy` with a pinned image tag
+5. Poll `/api/health` until `status === 'ok'`
+
+Set `OPENBOT_GATEWAY_TOKEN` via Fly secrets (derived per workspace). The gateway appends `x-openbot-gateway-token` on proxied requests; when the env var is unset (local dev), the check is skipped. `GET /api/health` is exempt for Fly health checks.

package/deploy/entrypoint.sh

@@ -0,0 +1,6 @@
+#!/bin/sh
+# Fly mounts the volume at /data as root; chown so the node user can write workspaces.
+if [ -d /data ]; then
+  chown -R node:node /data
+fi
+exec su-exec node "$@"

package/deploy/fly.toml

@@ -0,0 +1,36 @@
+# Fly.io template — copy per tenant and set `app` + secrets from your control plane.
+# Provision: fly volumes create openbot_data --region ord --size 1
+
+app = "openbot-tenant-example"
+primary_region = "ord"
+
+[build]
+  dockerfile = "../Dockerfile"
+
+[env]
+  OPENBOT_BASE_DIR = "/data/.openbot"
+  OPENBOT_CHANNELS_WORKSPACE_DIR = "/data/workspace"
+  PORT = "8080"
+
+[mounts]
+  source = "openbot_data"
+  destination = "/data"
+
+[http_service]
+  internal_port = 8080
+  force_https = true
+  auto_stop_machines = "off"
+  auto_start_machines = true
+  min_machines_running = 1
+
+  [[http_service.checks]]
+    grace_period = "15s"
+    interval = "15s"
+    method = "GET"
+    path = "/api/health"
+    timeout = "5s"
+
+[[vm]]
+  memory = "1gb"
+  cpu_kind = "shared"
+  cpus = 1

package/dist/app/bootstrap.js

@@ -0,0 +1,29 @@
+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, } from './config.js';
+/** Ensure data directories and a minimal config exist (first boot on a Fly volume). */
+export async function bootstrap() {
+    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 = { 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/dist/app/cli.js

@@ -1,5 +1,7 @@
 #!/usr/bin/env node
 import { Command } from 'commander';
+import { bootstrap } from './bootstrap.js';
+import { ensureDefaultStack } from './ensure-default-stack.js';
 import { startServer } from './server.js';
 const program = new Command();
 const REQUIRED_NODE_VERSION = '20.12.0';
@@ -16,12 +18,14 @@ function checkNodeVersion() {
     }
 }
 checkNodeVersion();
-program.name('openbot').description('OpenBot CLI').version('0.4.7');
+program.name('openbot').description('OpenBot CLI').version('0.5.5');
 program
     .command('start')
     .description('Start the OpenBot harness')
     .option('-p, --port <number>', 'Port to listen on')
     .action(async (options) => {
+    await bootstrap();
+    await ensureDefaultStack();
     await startServer(options);
 });
 program.parse();

package/dist/app/cloud-mode.js

@@ -0,0 +1,15 @@
+import { ORCHESTRATOR_AGENT_ID } from './agent-ids.js';
+/** Platform-managed OpenBot (Fly). Self-hosted when unset. */
+export const isCloudMode = () => process.env.OPENBOT_CLOUD_MODE === '1';
+/** Default cloud openbot plugin auth mode. */
+export const DEFAULT_CLOUD_OPENBOT_AUTH_MODE = 'credits';
+export function isCloudSystemAgent(agentId) {
+    return isCloudMode() && agentId === ORCHESTRATOR_AGENT_ID;
+}
+export function parseOpenbotAuthMode(value) {
+    return value === 'byok' ? 'byok' : 'credits';
+}
+export function assertCloudSystemAgentPluginsMutable(agentId, plugins) {
+    void agentId;
+    void plugins;
+}

package/dist/app/config.js

@@ -14,16 +14,8 @@ export const DEFAULT_MARKETPLACE_REGISTRY_URL = 'https://raw.githubusercontent.c
 export function resolvePath(p) {
     return p.startsWith('~/') ? path.join(os.homedir(), p.slice(2)) : path.resolve(p);
 }
-/** Default absolute cwd for a channel when none is provided at creation time. */
-export function getDefaultChannelCwd(channelId) {
-    const id = channelId.trim();
-    if (!id) {
-        throw new Error('channelId is required');
-    }
-    return resolvePath(`${DEFAULT_CHANNELS_WORKSPACE_DIR}/${id}`);
-}
-export function loadConfig() {
-    const configPath = path.join(os.homedir(), '.openbot', CONFIG_FILE);
+function readConfigFile(configDir) {
+    const configPath = path.join(configDir, CONFIG_FILE);
     if (fs.existsSync(configPath)) {
         try {
             return JSON.parse(fs.readFileSync(configPath, 'utf-8'));
@@ -34,23 +26,76 @@ export function loadConfig() {
     }
     return {};
 }
+/** Directory that holds `config.json` (env `OPENBOT_BASE_DIR` or `~/.openbot`). */
+export function getConfigDir() {
+    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() {
+    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() {
+    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) {
+    const id = channelId.trim();
+    if (!id) {
+        throw new Error('channelId is required');
+    }
+    return path.join(getChannelsWorkspaceRoot(), id);
+}
+export function loadConfig() {
+    const fileConfig = readConfigFile(getConfigDir());
+    const merged = { ...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(/\/$/, '');
+    }
+    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) {
-    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() {
-    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() {
-    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'));
     }

package/dist/app/ensure-default-stack.js

@@ -0,0 +1,54 @@
+import fs from 'node:fs/promises';
+import { existsSync } from 'node:fs';
+import path from 'node:path';
+import matter from 'gray-matter';
+import { ORCHESTRATOR_AGENT_ID } from './agent-ids.js';
+import { DEFAULT_SYSTEM_AGENT_MODEL, OPENBOT_PLUGIN_ID } from './openbot-plugin.js';
+import { DEFAULT_CLOUD_OPENBOT_AUTH_MODE, isCloudMode } from './cloud-mode.js';
+import { DEFAULT_AGENTS_DIR, getBaseDir } from './config.js';
+import { pluginService } from '../services/plugins/service.js';
+function systemAgentMdPath() {
+    return path.join(getBaseDir(), DEFAULT_AGENTS_DIR, ORCHESTRATOR_AGENT_ID, 'AGENT.md');
+}
+function defaultSystemPluginConfig() {
+    const config = {
+        model: DEFAULT_SYSTEM_AGENT_MODEL,
+    };
+    if (isCloudMode()) {
+        config.authMode = DEFAULT_CLOUD_OPENBOT_AUTH_MODE;
+    }
+    return config;
+}
+async function ensureOpenbotPluginInstalled() {
+    if (await pluginService.isInstalled(OPENBOT_PLUGIN_ID)) {
+        return;
+    }
+    console.log(`[bootstrap] Installing ${OPENBOT_PLUGIN_ID} from npm`);
+    await pluginService.install({ packageName: OPENBOT_PLUGIN_ID });
+}
+async function ensureSystemAgentMaterialized() {
+    const agentMdPath = systemAgentMdPath();
+    if (existsSync(agentMdPath)) {
+        return;
+    }
+    const agentDir = path.dirname(agentMdPath);
+    await fs.mkdir(agentDir, { recursive: true });
+    const frontmatter = {
+        name: 'OpenBot',
+        description: 'First-party orchestration agent for OpenBot.',
+        plugins: [
+            {
+                id: OPENBOT_PLUGIN_ID,
+                config: defaultSystemPluginConfig(),
+            },
+        ],
+    };
+    const content = matter.stringify('', frontmatter);
+    await fs.writeFile(agentMdPath, content, 'utf-8');
+    console.log(`[bootstrap] Materialized system agent at ${agentMdPath}`);
+}
+/** Install the default agent plugin from npm and materialize the system agent on first boot. */
+export async function ensureDefaultStack() {
+    await ensureOpenbotPluginInstalled();
+    await ensureSystemAgentMaterialized();
+}

package/dist/app/openbot-plugin.js

@@ -0,0 +1,4 @@
+/** npm package id for the monolithic OpenBot agent runtime plugin. */
+export const OPENBOT_PLUGIN_ID = '@meetopenbot/openbot';
+/** Default model for the materialized system agent. */
+export const DEFAULT_SYSTEM_AGENT_MODEL = 'openai/gpt-5.4-mini';