openbot 0.4.6 → 0.5.4

package/dist/plugins/openbot/index.js

@@ -1,10 +1,13 @@
+import { isCloudSystemAgent, resolveCloudSystemModel } from '../../app/cloud-mode.js';
 import { openbotRuntime } from './runtime.js';
 import { bashPlugin } from '../bash/index.js';
 import { memoryPlugin } from '../memory/index.js';
+import { todoPlugin } from '../todo/index.js';
 import { approvalPlugin } from '../approval/index.js';
 import { storagePlugin } from '../storage/index.js';
 import { delegationPlugin } from '../delegation/index.js';
 import { uiPlugin } from '../ui/index.js';
+import { previewPlugin } from '../preview/index.js';
 /**
  * `openbot` — the standard, opinionated OpenBot agent runtime.
  *
@@ -12,20 +15,19 @@ import { uiPlugin } from '../ui/index.js';
  * `agent:invoke`, manages short-term memory, assembles context, and
  * orchestrates tool calls.
  *
- * It comes with a "batteries-included" set of inbuilt tools: bash, memory,
- * storage, delegation, and approval.
+ * It comes with a "batteries-included" set of inbuilt tools: shell, memory,
+ * todo, storage, delegation, and approval.
  */
 export const openbotPlugin = {
     id: 'openbot',
     name: 'OpenBot Agent',
-    description: 'The standard OpenBot agent runtime with inbuilt tools (bash, memory, storage, delegation, and approval).',
+    description: 'The standard OpenBot agent runtime with inbuilt tools (shell, memory, todo, storage, delegation, and approval).',
     configSchema: {
         type: 'object',
         properties: {
             model: {
                 type: 'string',
-                description: 'Provider model string, e.g. openai/gpt-4o-mini, anthropic/claude-3-5-sonnet-20240620',
-                default: 'openai/gpt-4o-mini',
+                description: 'Model from the hosted marketplace registry.',
             },
             approval: {
                 type: 'object',
@@ -43,25 +45,39 @@ export const openbotPlugin = {
     toolDefinitions: {
         ...bashPlugin.toolDefinitions,
         ...memoryPlugin.toolDefinitions,
+        ...todoPlugin.toolDefinitions,
         ...storagePlugin.toolDefinitions,
         ...delegationPlugin.toolDefinitions,
-        ...uiPlugin.toolDefinitions,
+        ...previewPlugin.toolDefinitions,
+        // this is the capability to render UI widgets to the user. We dont need it for now.
+        // ...uiPlugin.toolDefinitions,
     },
     factory: (context) => (builder) => {
-        const { config, storage, tools, abortSignal } = context;
+        const { agentId, config, storage, tools, abortSignal } = context;
         // Register inbuilt plugins
         bashPlugin.factory(context)(builder);
         memoryPlugin.factory(context)(builder);
+        todoPlugin.factory(context)(builder);
         storagePlugin.factory(context)(builder);
         delegationPlugin.factory(context)(builder);
         uiPlugin.factory(context)(builder);
+        previewPlugin.factory(context)(builder);
         // Approval plugin configuration
         const approvalConfig = config?.approval || {
-            actions: ['action:bash', 'action:create_channel', 'action:delete_channel'],
+            actions: [
+                'action:shell_exec',
+                'action:expose_port',
+                'action:create_channel',
+                'action:delete_channel',
+            ],
         };
         approvalPlugin.factory({ ...context, config: approvalConfig })(builder);
+        const model = isCloudSystemAgent(agentId)
+            ? resolveCloudSystemModel(config?.model)
+            : config?.model;
         return openbotRuntime({
-            model: config?.model,
+            model,
+            agentId,
             storage,
             toolDefinitions: tools,
             abortSignal,

package/dist/plugins/openbot/model.js

@@ -0,0 +1,59 @@
+import { createOpenAI, 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) {
+    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':
+            return anthropic(modelId);
+        case 'google':
+            return google(modelId);
+        default:
+            throw new Error(`Unsupported AI provider: "${provider}"`);
+    }
+}

package/dist/plugins/openbot/runtime.js

@@ -1,44 +1,11 @@
 import { generateText } from 'ai';
-import { openai } from '@ai-sdk/openai';
-import { anthropic } from '@ai-sdk/anthropic';
-import { google } from '@ai-sdk/google';
 import { eventsToModelMessages } from './history.js';
-import { buildContext, } from './context.js';
-import { saveConfig, DEFAULT_MARKETPLACE_REGISTRY_URL } from '../../app/config.js';
+import { buildContext } from './context.js';
+import { saveConfig } from '../../app/config.js';
+import { isCloudSystemAgent } from '../../app/cloud-mode.js';
 import { OPENBOT_SYSTEM_PROMPT } from './system-prompt.js';
-let cachedRegistry = null;
-async function fetchRegistry() {
-    if (cachedRegistry)
-        return cachedRegistry;
-    try {
-        const response = await fetch(DEFAULT_MARKETPLACE_REGISTRY_URL);
-        if (!response.ok)
-            throw new Error(`Failed to fetch registry: ${response.statusText}`);
-        cachedRegistry = (await response.json());
-        return cachedRegistry;
-    }
-    catch (error) {
-        console.error('[openbot] Failed to fetch model registry:', error);
-        return null;
-    }
-}
-function resolveModel(modelString) {
-    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 'openai':
-            return openai(modelId);
-        case 'anthropic':
-            return anthropic(modelId);
-        case 'google':
-            return google(modelId);
-        default:
-            throw new Error(`Unsupported AI provider: "${provider}"`);
-    }
-}
+import { resolveModel } from './model.js';
+import { listApiKeyProvidersFromRegistry, resolveModelRegistry, } from '../../services/plugins/model-registry.js';
 async function buildSystemPrompt(state, storage) {
     const context = await buildContext(state, storage);
     const sections = [OPENBOT_SYSTEM_PROMPT, '', context];
@@ -102,9 +69,9 @@ 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', storage, toolDefinitions = {}, abortSignal, } = options;
+    const { model: modelString = 'openai/gpt-4o-mini', agentId, storage, toolDefinitions = {}, abortSignal, } = options;
     let currentModelString = modelString;
-    let model = resolveModel(currentModelString);
+    let model = resolveModel(currentModelString, agentId);
     const runLLM = async function* (context, threadId, trigger) {
         if (!storage)
             return;
@@ -200,7 +167,13 @@ export const openbotRuntime = (options) => (builder) => {
                 errorMessage.includes('401') ||
                 errorMessage.includes('Unauthorized') ||
                 errorMessage.includes('authentication');
-            if (isApiKeyError) {
+            if (isApiKeyError && !isCloudSystemAgent(context.state.agentId)) {
+                const registry = await resolveModelRegistry();
+                const providerActions = listApiKeyProvidersFromRegistry(registry).map((provider) => ({
+                    id: provider.id,
+                    label: provider.label,
+                    variant: 'primary',
+                }));
                 yield {
                     type: 'client:ui:widget',
                     data: {
@@ -208,11 +181,13 @@ export const openbotRuntime = (options) => (builder) => {
                         widgetId: `api_provider_selection_${Date.now()}`,
                         title: `Setup AI Provider`,
                         description: `Select a provider to continue.`,
-                        actions: [
-                            { id: 'openai', label: 'OpenAI', variant: 'primary' },
-                            { id: 'anthropic', label: 'Anthropic', variant: 'primary' },
-                            { id: 'google', label: 'Google', variant: 'primary' },
-                        ],
+                        actions: providerActions.length > 0
+                            ? providerActions
+                            : [
+                                { id: 'openai', label: 'OpenAI', variant: 'primary' },
+                                { id: 'anthropic', label: 'Anthropic', variant: 'primary' },
+                                { id: 'google', label: 'Google', variant: 'primary' },
+                            ],
                         metadata: {
                             type: 'api_provider_selection',
                         },
@@ -259,12 +234,14 @@ 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))
+            return;
         if (metadata?.type === 'api_provider_selection') {
             const provider = actionId;
             const [_, ...rest] = currentModelString.split('/');
             const currentModelId = rest.join('/');
-            const registry = await fetchRegistry();
-            const providerData = registry?.providers[provider];
+            const registry = await resolveModelRegistry();
+            const providerData = registry.providers?.[provider];
             const providerLinks = {
                 openai: 'https://platform.openai.com/api-keys',
                 anthropic: 'https://console.anthropic.com/settings/keys',
@@ -276,10 +253,18 @@ export const openbotRuntime = (options) => (builder) => {
                 label: m.label,
                 value: m.id,
             }));
-            const defaultModel = modelOptions?.[0]?.value || 'gpt-4o-mini';
-            const defaultValue = modelOptions?.find((m) => m.value === currentModelId)?.value ||
-                currentModelId ||
-                defaultModel;
+            if (!modelOptions || modelOptions.length === 0) {
+                yield {
+                    type: 'agent:output',
+                    data: {
+                        content: `No models are listed for **${label}** in the marketplace registry.`,
+                    },
+                    meta: { agentId: context.state.agentId },
+                };
+                return;
+            }
+            const defaultModel = modelOptions[0].value;
+            const defaultValue = modelOptions.find((m) => m.value === currentModelId)?.value || defaultModel;
             yield {
                 type: 'client:ui:widget',
                 data: {
@@ -305,10 +290,8 @@ export const openbotRuntime = (options) => (builder) => {
                         {
                             id: 'model',
                             label: 'Model',
-                            type: modelOptions ? 'select' : 'text',
-                            description: modelOptions ? undefined : `Model name (e.g. \`${defaultModel}\`).`,
+                            type: 'select',
                             options: modelOptions,
-                            placeholder: defaultModel,
                             required: true,
                             defaultValue,
                         },
@@ -358,7 +341,7 @@ export const openbotRuntime = (options) => (builder) => {
             await storage.createVariable({ key: envVar, value: apiKey, secret: true });
             process.env[envVar] = apiKey;
             currentModelString = newModelString;
-            model = resolveModel(currentModelString);
+            model = resolveModel(currentModelString, agentId);
             try {
                 saveConfig({ model: currentModelString });
                 // Also update the agent's AGENT.md if it has an openbot plugin config

package/dist/plugins/openbot/system-prompt.js

@@ -1,22 +1,57 @@
 export const OPENBOT_SYSTEM_PROMPT = [
     '# ROLE',
-    'You are an OpenBot, the main coordinator and router agent. Your primary role is to orchestrate specialized agents to help the human achieve their goals.',
+    'You are an OpenBot, the main coordinator and router agent. Your primary role is to orchestrate specialized agents and manage tasks methodically to help the human achieve their goals.',
     '',
     '# SECURITY POLICY',
     '- **CRITICAL**: Never request API keys, passwords, or sensitive credentials via text or UI widgets; these are managed deterministically via secure forms and must never enter your context.',
     '- **Credential Guidance**: If an agent or tool requires credentials, inform the user they can be managed under "Settings > Variables".',
     '',
     '# CORE MISSION',
-    'You almost never execute tasks yourself. Instead, you delegate tasks to specialized agents. You act as a high-level manager, ensuring the right agent is working on the right task.',
+    'You act as a high-level manager, ensuring the right specialized agent is working on the right task. However, when orchestrating or when specialized agents are not available, you are capable of executing complex steps yourself using a highly structured, stateful, and disciplined approach.',
+    '',
+    '# THE AGENT LOOP',
+    'You operate in an iterative agent loop to complete user-assigned tasks step-by-step:',
+    '1. **Analyze Events**: Understand user needs and the current state through the chronological event stream (focusing on latest user messages and execution/observation results).',
+    '2. **Select Tools**: Choose the next tool call based on current state, todos, and environment constraints. To maximize precision, choose only one tool call per iteration for complex tasks, or parallel calls if they are independent.',
+    '3. **Wait for Execution**: Let the system execute the tool action and add observations/results back into the event stream.',
+    '4. **Iterate**: Patiently repeat the above steps, analyzing results at each turn, until all steps of the task are completed.',
+    '5. **Submit Results**: Message the human with clear, polished, and detailed outcomes, attaching any relevant files or deliverables.',
+    '6. **Enter Standby**: Enter an idle state and wait for new tasks.',
+    '',
+    '# TASK TRACKING (TODOS)',
+    '- For any complex multi-step task (3+ steps), you **MUST** maintain a todo list with `todo_write`.',
+    '- Write the full intended list at task start. Each call replaces the previous list (not a partial patch).',
+    '- Keep exactly one item `in_progress` while working. Mark items `completed` immediately after finishing them.',
+    '- Use `cancelled` for steps that are no longer needed. When the overall task is done, mark all items `completed` and leave the list intact (do not clear with empty `items`).',
+    '- The current list is injected into context each turn as `## TODOS`; call `todo_read` only if you need an explicit refresh.',
+    '- Do not stop with open `pending` or `in_progress` items unless you are blocked and have told the user why.',
     '',
     '# OPERATIONAL GUIDELINES',
-    '- **Channel and Threads**: The main and only way to communicate and act is through channels and threads. There might be a channel called "uncategorized" for general purpose communication.',
-    '- **Delegation**: You can delegate tasks to any specialized agent in the `INSTALLED AGENTS` list.',
-    '- **Bash Tool Usage**: You should use the `bash` tool very rarely. Only use it when the user explicitly requests a command to be run or when it is absolutely necessary for a task that no other agent can handle.',
-    '- **Context Awareness**: Use the provided ENVIRONMENT, CHANNEL SPECIFICATION, and MEMORIES to maintain continuity. Do not ask for information already present in these sections.',
+    '- **Channel and Threads**: The main way to communicate and act is through channels and threads. There might be a channel called "uncategorized" for general purpose communication.',
+    '- **Delegation**: You can delegate tasks to any specialized agent in the `INSTALLED AGENTS` list using the `delegate` tool.',
     '- **Durable Memory**: Use the `remember` tool to store important facts, preferences, or project details that should persist across sessions.',
-    '- **Structured Interaction**: Use the `render_widget` tool to collect information via forms, offer choices, or display lists. This is preferred over asking multiple separate questions in plain text.',
+    '- **Hub-and-Spoke**: Specialized agents cannot communicate directly; as coordinator, you must pass relevant data from one agent to another.',
+    '',
+    '# SHELL & FILE EXECUTION RULES',
+    '- **Stateful Sessions**: Use `shell_exec` with a session `id` (e.g. `default`, `server`). Reuse the same id to keep shell state (cwd, env) across commands.',
+    '- **Working Directory**: Always pass an absolute `exec_dir` (use the channel workspace path from ENVIRONMENT).',
+    '- **Command Discipline**: Avoid interactive prompts when possible; use `-y`, `-f`, or non-interactive flags. For prompts, use `shell_write_to_process`.',
+    '- **Long-Running Processes**: Start dev servers with `shell_exec` using `&` at the end (e.g. `pnpm dev &`). If you forget `&`, `shell_exec` returns after ~15s with partial logs — the server may still be running.',
+    '- **Polling dev servers**: After starting (or after a timeout), poll with `shell_wait` (2–5s) then `shell_view` until logs show ready (URL/port). Do not start a duplicate server; reuse the same session id.',
+    '- **Stop dev servers**: Use `shell_kill_process` before restarting or when finished.',
+    '- **Preview URLs**: After a dev server is ready, use `expose_port` with its port to generate a public preview URL (stored on channel details as `previewUrl`). Expose tunnels are temporary; close with `unexpose_port`.',
+    '- **Calculations**: Use `bc` or Python for math. Do not calculate complex math mentally.',
+    '- **Chaining**: Chain related commands with `&&` in a single `shell_exec` when they must run sequentially.',
+    '',
+    '# COMMUNICATION & WRITING STYLE',
+    '- Be concise, professional, proactive, and polite.',
+    '- Confirm receipt of user messages quickly and outline your high-level strategy brief before executing a long series of steps.',
+    '- Inform the user via messages when you change methods or find strategic issues.',
+    '- Write in clean, continuous prose. Avoid excessive bullet points or lists in final responses unless explicitly requested.',
+    '- All major deliverables and documents must be highly detailed and complete; do not summarize or truncate final outputs unless specified.',
     '',
-    '# COMMUNICATION STYLE',
-    '- Be always concise, professional, and proactive.',
+    '# ERROR HANDLING',
+    '- Tool failures are provided as events. When an error occurs, do not panic or immediately ask the user for help.',
+    '- Carefully analyze the stderr or failure logs, verify tool/argument names, and attempt alternative approaches or parameter fixes.',
+    '- Only report failure reasons and ask the human for help after multiple alternative approaches have failed.',
 ].join('\n');

package/dist/plugins/preview/index.js

@@ -0,0 +1,267 @@
+import { z } from 'zod';
+import { spawn } from 'node:child_process';
+import { randomUUID } from 'node:crypto';
+const TUNNEL_URL_PATTERN = /https:\/\/[a-z0-9-]+\.trycloudflare\.com/i;
+const TUNNEL_READY_TIMEOUT_MS = 60000;
+const MAX_LOG_CHARS = 8000;
+const previewToolDefinitions = {
+    expose_port: {
+        description: 'Expose a local dev server port via a temporary public Cloudflare quick tunnel. Returns a previewUrl stored on the channel. Dev servers must listen on 0.0.0.0 or 127.0.0.1. Call after shell_exec when the server is ready.',
+        inputSchema: z.object({
+            port: z
+                .number()
+                .int()
+                .min(1024)
+                .max(65535)
+                .describe('Local port of the running dev server (e.g. 5173).'),
+        }),
+    },
+    unexpose_port: {
+        description: 'Stop the active Cloudflare preview tunnel for this channel and clear previewUrl from channel state.',
+        inputSchema: z.object({}),
+    },
+};
+const tunnels = new Map();
+const tunnelByChannel = new Map();
+const blockedPorts = () => {
+    const openbotPort = Number(process.env.PORT ?? 4132);
+    return new Set([22, 80, 443, openbotPort]);
+};
+const appendLog = (tunnel, chunk) => {
+    tunnel.logs += chunk;
+    if (tunnel.logs.length > MAX_LOG_CHARS) {
+        tunnel.logs = tunnel.logs.slice(-MAX_LOG_CHARS);
+    }
+};
+const killTunnelProcess = (tunnel) => {
+    const { process: child } = tunnel;
+    if (!child.pid) {
+        try {
+            child.kill();
+        }
+        catch {
+            /* ignore */
+        }
+        return;
+    }
+    try {
+        child.kill('SIGTERM');
+    }
+    catch {
+        try {
+            child.kill();
+        }
+        catch {
+            /* ignore */
+        }
+    }
+};
+const removeTunnel = (tunnelId) => {
+    const tunnel = tunnels.get(tunnelId);
+    if (!tunnel)
+        return;
+    killTunnelProcess(tunnel);
+    tunnels.delete(tunnelId);
+    if (tunnelByChannel.get(tunnel.channelId) === tunnelId) {
+        tunnelByChannel.delete(tunnel.channelId);
+    }
+};
+export const stopPreviewForChannel = (channelId) => {
+    const tunnelId = tunnelByChannel.get(channelId);
+    if (tunnelId) {
+        removeTunnel(tunnelId);
+    }
+};
+const waitForTunnelUrl = (child, timeoutMs) => new Promise((resolve, reject) => {
+    let buffer = '';
+    let settled = false;
+    const cleanup = () => {
+        clearTimeout(timer);
+        child.stdout?.off('data', onData);
+        child.stderr?.off('data', onData);
+        child.off('exit', onExit);
+        child.off('error', onError);
+    };
+    const tryParse = () => {
+        const match = buffer.match(TUNNEL_URL_PATTERN);
+        if (match) {
+            settled = true;
+            cleanup();
+            resolve(match[0]);
+        }
+    };
+    const onData = (chunk) => {
+        buffer += chunk.toString();
+        if (buffer.length > 16000) {
+            buffer = buffer.slice(-16000);
+        }
+        tryParse();
+    };
+    const onExit = (code) => {
+        if (settled)
+            return;
+        settled = true;
+        cleanup();
+        reject(new Error(`cloudflared exited before providing a tunnel URL (code ${code ?? 'unknown'})`));
+    };
+    const onError = (err) => {
+        if (settled)
+            return;
+        settled = true;
+        cleanup();
+        reject(err);
+    };
+    const timer = setTimeout(() => {
+        if (settled)
+            return;
+        settled = true;
+        cleanup();
+        reject(new Error('Timed out waiting for Cloudflare tunnel URL'));
+    }, timeoutMs);
+    child.stdout?.on('data', onData);
+    child.stderr?.on('data', onData);
+    child.on('exit', onExit);
+    child.on('error', onError);
+    tryParse();
+});
+const startCloudflaredTunnel = async (channelId, port) => {
+    const child = spawn('cloudflared', ['tunnel', '--url', `http://127.0.0.1:${port}`, '--no-autoupdate'], {
+        env: process.env,
+        stdio: ['ignore', 'pipe', 'pipe'],
+    });
+    const tunnel = {
+        id: randomUUID(),
+        channelId,
+        port,
+        url: '',
+        process: child,
+        startedAt: Date.now(),
+        logs: '',
+    };
+    child.stdout?.on('data', (data) => appendLog(tunnel, data.toString()));
+    child.stderr?.on('data', (data) => appendLog(tunnel, data.toString()));
+    child.on('exit', () => {
+        tunnels.delete(tunnel.id);
+        if (tunnelByChannel.get(channelId) === tunnel.id) {
+            tunnelByChannel.delete(channelId);
+        }
+    });
+    const url = await waitForTunnelUrl(child, TUNNEL_READY_TIMEOUT_MS);
+    tunnel.url = url;
+    tunnels.set(tunnel.id, tunnel);
+    tunnelByChannel.set(channelId, tunnel.id);
+    return tunnel;
+};
+const clearPreviewChannelState = async (storage, channelId) => {
+    await storage.patchChannelState({
+        channelId,
+        state: {
+            previewUrl: null,
+            previewPort: null,
+            previewExposedAt: null,
+        },
+    });
+};
+const previewPluginRuntime = (storage) => (builder) => {
+    builder.on('action:expose_port', async function* (event, context) {
+        const channelId = context.state.channelId;
+        const port = event.data?.port;
+        if (!Number.isInteger(port)) {
+            yield {
+                type: 'action:expose_port:result',
+                data: {
+                    success: false,
+                    output: 'port must be an integer between 1024 and 65535.',
+                },
+                meta: event.meta,
+            };
+            return;
+        }
+        if (blockedPorts().has(port)) {
+            yield {
+                type: 'action:expose_port:result',
+                data: {
+                    success: false,
+                    output: `Port ${port} is reserved and cannot be exposed.`,
+                },
+                meta: event.meta,
+            };
+            return;
+        }
+        const existingTunnelId = tunnelByChannel.get(channelId);
+        if (existingTunnelId) {
+            removeTunnel(existingTunnelId);
+        }
+        try {
+            const tunnel = await startCloudflaredTunnel(channelId, port);
+            await storage.patchChannelState({
+                channelId,
+                state: {
+                    previewUrl: tunnel.url,
+                    previewPort: port,
+                    previewExposedAt: tunnel.startedAt,
+                },
+            });
+            if (context.state.channelDetails) {
+                context.state.channelDetails = await storage.getChannelDetails({ channelId });
+            }
+            yield {
+                type: 'action:expose_port:result',
+                data: {
+                    success: true,
+                    previewUrl: tunnel.url,
+                    port,
+                    temporary: true,
+                    output: `Preview available at ${tunnel.url} (temporary Cloudflare quick tunnel).`,
+                },
+                meta: event.meta,
+            };
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : 'Failed to start Cloudflare tunnel';
+            const needsCloudflared = message.includes('ENOENT') || message.toLowerCase().includes('cloudflared');
+            const hint = needsCloudflared
+                ? ' Install cloudflared and ensure it is on PATH (https://developers.cloudflare.com/cloudflare-one/connections/connect-apps/downloads/).'
+                : '';
+            yield {
+                type: 'action:expose_port:result',
+                data: {
+                    success: false,
+                    error: message,
+                    output: `${message}${hint}`,
+                },
+                meta: event.meta,
+            };
+        }
+    });
+    builder.on('action:unexpose_port', async function* (event, context) {
+        const channelId = context.state.channelId;
+        stopPreviewForChannel(channelId);
+        await clearPreviewChannelState(storage, channelId);
+        if (context.state.channelDetails) {
+            context.state.channelDetails = await storage.getChannelDetails({ channelId });
+        }
+        yield {
+            type: 'action:unexpose_port:result',
+            data: {
+                success: true,
+                output: 'Preview tunnel stopped and previewUrl cleared from channel state.',
+            },
+            meta: event.meta,
+        };
+    });
+    builder.on('action:delete_channel', async function* (event) {
+        const channelId = event.data?.channelId;
+        if (channelId) {
+            stopPreviewForChannel(channelId);
+        }
+    });
+};
+export const previewPlugin = {
+    id: 'preview',
+    name: 'Preview',
+    description: 'Temporary public preview URLs via Cloudflare quick tunnels.',
+    toolDefinitions: previewToolDefinitions,
+    factory: ({ storage }) => previewPluginRuntime(storage),
+};
+export default previewPlugin;

package/dist/plugins/storage/index.js

@@ -32,7 +32,7 @@ const storageToolDefinitions = {
             state: z
                 .record(z.string(), z.unknown())
                 .optional()
-                .describe('JSON state object for the channel. Use for structured metadata.'),
+                .describe('JSON state object for the channel.'),
             spec: z
                 .string()
                 .optional()
@@ -44,11 +44,11 @@ const storageToolDefinitions = {
             value.cwd !== undefined, { message: 'Provide at least one of state, spec, or cwd.' }),
     },
     patch_thread_details: {
-        description: 'Patch current thread details (state).',
+        description: 'Patch current thread details (state). Use for thread metadata such as `name` or `isSmartNamed`. For multi-step task tracking, use `todo_write` instead.',
         inputSchema: z.object({
             state: z
                 .record(z.string(), z.unknown())
-                .describe('JSON state object for the thread. Use for structured progress or metadata.'),
+                .describe('JSON state object for the thread. Merges with existing state.'),
         }),
     },
     create_variable: {