openbot 0.5.4 → 0.5.6

package/CLAUDE.md

@@ -20,6 +20,7 @@ OpenBot is a local-first, event-driven harness for running AI agents, built on t
 ### 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).
@@ -28,13 +29,13 @@ OpenBot is a local-first, event-driven harness for running AI agents, built on t
 
 ### Plugins (`src/plugins/*`, registered in `src/services/plugins/registry.ts`)
 
-Built-ins: `openbot` (batteries-included runtime: bash, memory, todo, storage, delegation, approval all bundled in), `bash`, `storage`, `approval` (gates protected tool calls behind UI confirmation), `memory` (`remember`/`recall`/`forget`, append-only JSONL, scoped `global`/`agent`/`channel`), `todo` (`todo_write`/`todo_read`, thread-scoped checklist in `todos.json`), `delegation` (calling other agents), `ui`, `plugin-manager` (marketplace + npm plugin install), `preview`. Community plugins are npm packages installed on demand into `~/.openbot/plugins/<name>/dist/index.js` and loaded dynamically via `resolvePlugin`; they export a `Plugin`-shaped object as `plugin` or `default` (see `parsePluginModule`).
+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`, and the run's `abortSignal`.
+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. `claude-code` and `gemini-cli` runtime plugins own their entire tool loop (attaching tool plugins like `bash` to them is a no-op) — only the `openbot` runtime plugin consumes the merged `tools` map. Two built-in agent ids are hardcoded in `src/app/agent-ids.ts` and can be overridden by an on-disk `AGENT.md` overlay merged on top of code defaults: `system` (`ORCHESTRATOR_AGENT_ID`, the default orchestrator, listed) and `state` (`STATE_AGENT_ID`, hidden, backs `/api/state` and deterministic storage/marketplace actions).
+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`)
 
@@ -42,7 +43,7 @@ Agents are markdown files with YAML frontmatter (`~/.openbot/agents/<agentId>/AG
 
 ### Cloud mode (`src/app/cloud-mode.ts`)
 
-Set via `OPENBOT_CLOUD_MODE=1` for platform-managed (Fly.io) deployments: the `system` agent is forced onto a coordinator model (`openbot/coordinator-1`) and LLM/integration calls proxy through `OPENBOT_INTEGRATIONS_BASE_URL` with an HMAC `OPENBOT_INTEGRATIONS_TOKEN`. `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.
+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
 

package/deploy/README.md

@@ -39,9 +39,7 @@ Copy `deploy/fly.toml`, set `app` to your tenant id, and ensure the volume name
 | `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 uses integrations proxy) |
-| `OPENBOT_INTEGRATIONS_BASE_URL` | Yes (cloud) | Integrations gateway base URL, e.g. `https://integrations.openbot.one/abc123` |
-| `OPENBOT_INTEGRATIONS_TOKEN` | Yes (cloud) | Per-workspace HMAC token for `x-openbot-integrations-token` on LLM proxy 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
@@ -54,7 +52,7 @@ 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 OPENBOT_INTEGRATIONS_BASE_URL=... OPENBOT_INTEGRATIONS_TOKEN=...`
+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'`
 

package/dist/app/cli.js

@@ -1,6 +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';
@@ -17,13 +18,14 @@ function checkNodeVersion() {
     }
 }
 checkNodeVersion();
-program.name('openbot').description('OpenBot CLI').version('0.5.4');
+program.name('openbot').description('OpenBot CLI').version('0.5.6');
 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

@@ -1,24 +1,13 @@
 import { ORCHESTRATOR_AGENT_ID } from './agent-ids.js';
-/** Platform-managed OpenBot (Fly + integrations proxy). Self-hosted when unset. */
+/** Platform-managed OpenBot (Fly). Self-hosted when unset. */
 export const isCloudMode = () => 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 function getCloudIntegrationsConfig() {
-    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 };
-}
+/** 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 resolveCloudSystemModel(configModel) {
-    return configModel?.trim() || COORDINATOR_MODEL;
+export function parseOpenbotAuthMode(value) {
+    return value === 'byok' ? 'byok' : 'credits';
 }
 export function assertCloudSystemAgentPluginsMutable(agentId, plugins) {
     void agentId;

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';

package/dist/app/server.js

@@ -9,7 +9,7 @@ const require = createRequire(import.meta.url);
 const pkg = require('../../package.json');
 import { generateId } from 'melony';
 import { getBaseDir, loadConfig } from '../app/config.js';
-import { isCloudMode, getCloudIntegrationsConfig } from './cloud-mode.js';
+import { isCloudMode } from './cloud-mode.js';
 import { processService } from '../services/process.js';
 import { runAgent, STATE_AGENT_ID, ORCHESTRATOR_AGENT_ID } from '../harness/index.js';
 import { initPlugins } from '../services/plugins/registry.js';
@@ -31,8 +31,7 @@ export async function startServer(options = {}) {
     const config = loadConfig();
     processService.syncWorkspaceVariablesToProcessEnv();
     if (isCloudMode()) {
-        const integrations = getCloudIntegrationsConfig();
-        console.log(`[server] Cloud mode enabled${integrations ? '' : ' (integrations proxy env not set)'}`);
+        console.log('[server] Cloud mode enabled');
     }
     const openBotDir = getBaseDir();
     const PORT = Number(options.port ?? config.port ?? process.env.PORT ?? 4132);

package/dist/harness/index.js

@@ -6,6 +6,7 @@ import { resolvePlugin } from '../services/plugins/registry.js';
 import { abortRegistry, abortKey } from '../services/abort.js';
 import { loadConfig } from '../app/config.js';
 import { getPublicBaseUrl } from '../plugins/storage/files.js';
+import { createPluginHost } from '../services/plugins/host.js';
 export { STATE_AGENT_ID, ORCHESTRATOR_AGENT_ID };
 async function emitEvent(chunk, state, { persistEvents, channelId, threadId, onEvent, parentAgentId, parentToolCallId, }) {
     ensureEventId(chunk);
@@ -67,6 +68,7 @@ export async function runAgent(options) {
             }
         }
         const builder = melony().initialState(state);
+        const pluginHost = createPluginHost(runAgent);
         for (const ref of pluginRefs) {
             const plugin = await resolvePlugin(ref.id);
             if (!plugin)
@@ -79,6 +81,7 @@ export async function runAgent(options) {
                 tools,
                 publicBaseUrl,
                 abortSignal,
+                host: pluginHost,
             }));
         }
         const runtime = builder.build();

package/dist/plugins/openbot/index.js

@@ -1,4 +1,4 @@
-import { isCloudSystemAgent, resolveCloudSystemModel } from '../../app/cloud-mode.js';
+import { isCloudSystemAgent, parseOpenbotAuthMode } from '../../app/cloud-mode.js';
 import { openbotRuntime } from './runtime.js';
 import { bashPlugin } from '../bash/index.js';
 import { memoryPlugin } from '../memory/index.js';
@@ -72,11 +72,12 @@ export const openbotPlugin = {
             ],
         };
         approvalPlugin.factory({ ...context, config: approvalConfig })(builder);
-        const model = isCloudSystemAgent(agentId)
-            ? resolveCloudSystemModel(config?.model)
-            : config?.model;
+        const authMode = isCloudSystemAgent(agentId)
+            ? parseOpenbotAuthMode(config?.authMode)
+            : 'byok';
         return openbotRuntime({
-            model,
+            model: config?.model,
+            authMode,
             agentId,
             storage,
             toolDefinitions: tools,

package/dist/plugins/openbot/model.js

@@ -1,52 +1,13 @@
-import { createOpenAI, openai as defaultOpenai } from '@ai-sdk/openai';
+import { openai as defaultOpenai } from '@ai-sdk/openai';
 import { anthropic } from '@ai-sdk/anthropic';
 import { google } from '@ai-sdk/google';
-import { getCloudIntegrationsConfig, isCloudSystemAgent, } from '../../app/cloud-mode.js';
-let cloudOpenAIProvider;
-/** Strip credentials — the integrations gateway injects the provider master key. */
-const integrationsFetch = async (input, init) => {
-    const headers = new Headers(init?.headers);
-    headers.delete('Authorization');
-    headers.delete('x-api-key');
-    return globalThis.fetch(input, { ...init, headers });
-};
-function getCloudOpenAIProvider() {
-    if (cloudOpenAIProvider !== undefined)
-        return cloudOpenAIProvider;
-    const config = getCloudIntegrationsConfig();
-    if (!config) {
-        cloudOpenAIProvider = null;
-        return null;
-    }
-    cloudOpenAIProvider = createOpenAI({
-        baseURL: `${config.baseUrl}/openai/v1`,
-        apiKey: 'unused',
-        headers: {
-            'x-openbot-integrations-token': config.token,
-        },
-        fetch: integrationsFetch,
-    });
-    return cloudOpenAIProvider;
-}
-function resolveOpenbotModel(modelId, agentId) {
-    if (!agentId || !isCloudSystemAgent(agentId)) {
-        throw new Error(`OpenBot models are only available for the cloud system agent. Use openai/..., anthropic/..., etc.`);
-    }
-    const cloudOpenai = getCloudOpenAIProvider();
-    if (!cloudOpenai) {
-        throw new Error('OpenBot cloud model requires OPENBOT_INTEGRATIONS_BASE_URL and OPENBOT_INTEGRATIONS_TOKEN.');
-    }
-    return cloudOpenai.chat(modelId);
-}
-export function resolveModel(modelString, agentId) {
+export function resolveModel(modelString, _agentId) {
     const [provider, ...rest] = modelString.split('/');
     const modelId = rest.join('/');
     if (!modelId) {
         throw new Error(`Invalid model string: "${modelString}". Expected "provider/model-id".`);
     }
     switch (provider) {
-        case 'openbot':
-            return resolveOpenbotModel(modelId, agentId);
         case 'openai':
             return defaultOpenai(modelId);
         case 'anthropic':

package/dist/plugins/openbot/runtime.js

@@ -69,9 +69,10 @@ function createToolBatchTracker(state, storage, channelId, threadId) {
  * - When a full batch of results is in, `runLLM` runs again with updated history.
  */
 export const openbotRuntime = (options) => (builder) => {
-    const { model: modelString = 'openai/gpt-4o-mini', agentId, storage, toolDefinitions = {}, abortSignal, } = options;
+    const { model: modelString = 'openai/gpt-4o-mini', authMode = 'byok', agentId, storage, toolDefinitions = {}, abortSignal, } = options;
     let currentModelString = modelString;
     let model = resolveModel(currentModelString, agentId);
+    const isCreditsCloudAgent = (id) => isCloudSystemAgent(id ?? '') && authMode === 'credits';
     const runLLM = async function* (context, threadId, trigger) {
         if (!storage)
             return;
@@ -167,7 +168,7 @@ export const openbotRuntime = (options) => (builder) => {
                 errorMessage.includes('401') ||
                 errorMessage.includes('Unauthorized') ||
                 errorMessage.includes('authentication');
-            if (isApiKeyError && !isCloudSystemAgent(context.state.agentId)) {
+            if (isApiKeyError && !isCreditsCloudAgent(context.state.agentId)) {
                 const registry = await resolveModelRegistry();
                 const providerActions = listApiKeyProvidersFromRegistry(registry).map((provider) => ({
                     id: provider.id,
@@ -234,7 +235,7 @@ export const openbotRuntime = (options) => (builder) => {
     builder.on('client:ui:widget:response', async function* (event, context) {
         const { metadata, values, actionId } = event.data;
         const threadId = event.meta?.threadId || context.state.threadId;
-        if (isCloudSystemAgent(context.state.agentId))
+        if (isCreditsCloudAgent(context.state.agentId))
             return;
         if (metadata?.type === 'api_provider_selection') {
             const provider = actionId;
@@ -350,7 +351,11 @@ export const openbotRuntime = (options) => (builder) => {
                     if (ref.id === 'openbot') {
                         return {
                             ...ref,
-                            config: { ...ref.config, model: currentModelString },
+                            config: {
+                                ...ref.config,
+                                model: currentModelString,
+                                ...(isCloudSystemAgent(context.state.agentId) ? { authMode: 'byok' } : {}),
+                            },
                         };
                     }
                     return ref;