@theowlops/boombot 0.0.0-stage → 1.1.1

package/dist/gateway/static.js

@@ -0,0 +1,239 @@
+/**
+ * Static file serving for the bundled web UI.
+ *
+ * Serves `dist/web/` (the `vite build` output of `@boombot/web`) through the
+ * gateway's plain `node:http` server — zero dependencies, hand-rolled.
+ *
+ * The asset directory is resolved relative to THIS file
+ * (`fileURLToPath(import.meta.url)`), never `process.cwd()`, so a global
+ * `npm i -g @boombot/cli` install serves the UI no matter which
+ * directory the process starts from:
+ * - npm dist layout: `dist/gateway/static.js` → `dist/web/`
+ * - monorepo build:   `agent-worker/dist/static.js` → `apps/web/dist/`
+ * - source dev:       `agent-worker/src/static.ts` → `apps/web/dist/` when built
+ *
+ * Behavior:
+ * - `GET`/`HEAD` only; other methods fall through (the caller answers 404/405).
+ * - Exact file match → served with a content type, `ETag`/`Last-Modified`,
+ *   and cache headers (`immutable` for `/assets/*`, `no-cache` for `index.html`).
+ * - Directory or extensionless miss → SPA fallback to `index.html`
+ *   (client-side routing).
+ * - Missing path WITH an extension → 404 JSON (same error shape as the API),
+ *   so a broken asset reference never returns HTML.
+ * - Path traversal, null bytes and dotfile segments → 404 (no information leak).
+ * - `BOOMBOT_WEB_ROOT` overrides the asset directory. The override is
+ *   authoritative: when set, no other location is probed — a missing path
+ *   means API-only mode (loud and debuggable, never a silent fallback).
+ * - When the asset directory is absent (source checkout without a web build),
+ *   every request falls through and the gateway stays API-only — the dev
+ *   workflow (`vite dev`) keeps working untouched.
+ */
+import { createReadStream, existsSync, statSync } from 'node:fs';
+import { dirname, extname, join, normalize, resolve, sep } from 'node:path';
+import { fileURLToPath } from 'node:url';
+const MIME_TYPES = {
+    '.html': 'text/html; charset=utf-8',
+    '.js': 'text/javascript; charset=utf-8',
+    '.mjs': 'text/javascript; charset=utf-8',
+    '.css': 'text/css; charset=utf-8',
+    '.json': 'application/json; charset=utf-8',
+    '.map': 'application/json; charset=utf-8',
+    '.svg': 'image/svg+xml',
+    '.png': 'image/png',
+    '.jpg': 'image/jpeg',
+    '.jpeg': 'image/jpeg',
+    '.gif': 'image/gif',
+    '.webp': 'image/webp',
+    '.avif': 'image/avif',
+    '.ico': 'image/x-icon',
+    '.woff': 'font/woff',
+    '.woff2': 'font/woff2',
+    '.ttf': 'font/ttf',
+    '.txt': 'text/plain; charset=utf-8',
+};
+/** Cached `resolveWebRoot()` result (`undefined` = not resolved yet). */
+let cachedWebRoot;
+/**
+ * Absolute path of the web asset directory, or `null` when it is absent.
+ * Result is cached for the process lifetime. `BOOMBOT_WEB_ROOT` (when set and
+ * non-empty) is authoritative: no fallback probing happens, so a wrong path
+ * fails loudly instead of silently serving another directory.
+ */
+export function resolveWebRoot() {
+    if (cachedWebRoot !== undefined)
+        return cachedWebRoot;
+    const override = process.env['BOOMBOT_WEB_ROOT'];
+    const here = dirname(fileURLToPath(import.meta.url));
+    const candidates = override !== undefined && override.trim() !== ''
+        ? [resolve(override)]
+        : [
+            resolve(here, '..', 'web'),
+            resolve(here, '..', '..', '..', 'apps', 'web', 'dist'),
+        ];
+    cachedWebRoot =
+        candidates.find((candidate) => existsSync(candidate) && statSync(candidate).isDirectory()) ??
+            null;
+    return cachedWebRoot;
+}
+/** Clear the cached web-root resolution. Test-only: production code never calls this. */
+export function resetWebRootCache() {
+    cachedWebRoot = undefined;
+}
+/** True when the bundled web UI exists and will be served. */
+export function isWebUiEnabled() {
+    return resolveWebRoot() !== null;
+}
+/**
+ * Map a raw request pathname to a file under `webRoot`. Pure apart from
+ * `statSync`: safe to unit-test directly.
+ *
+ * - `..` segments are collapsed against a leading `/` first, so they can
+ *   never climb above `webRoot`; the `startsWith(webRoot + sep)` check is
+ *   defense in depth.
+ * - `blocked` (traversal, null byte, bad encoding, dotfile) and `missing`
+ *   both surface as 404 to the client — never 403, to avoid confirming or
+ *   denying the existence of anything outside the asset tree.
+ */
+export function resolveStaticFile(webRoot, rawPathname) {
+    let pathname;
+    try {
+        pathname = decodeURIComponent(rawPathname);
+    }
+    catch {
+        return { kind: 'blocked' };
+    }
+    if (pathname.includes('\0'))
+        return { kind: 'blocked' };
+    const normalized = normalize(`/${pathname}`);
+    const target = join(webRoot, normalized);
+    if (target !== webRoot && !target.startsWith(webRoot + sep)) {
+        return { kind: 'blocked' };
+    }
+    // A vite build never ships dotfiles; don't serve them (or confirm them).
+    const relative = target.slice(webRoot.length);
+    if (relative.split(sep).some((segment) => segment.startsWith('.') && segment.length > 1)) {
+        return { kind: 'blocked' };
+    }
+    let file = target;
+    let isDir = false;
+    try {
+        isDir = statSync(target).isDirectory();
+    }
+    catch {
+        // Missing path: SPA fallback only for extensionless paths (client routes).
+        // A missing `*.js`/`*.css`/… is a broken asset reference → 404, not index.html.
+        if (extname(normalized) !== '')
+            return { kind: 'missing' };
+        file = join(webRoot, 'index.html');
+    }
+    if (isDir)
+        file = join(target, 'index.html');
+    try {
+        if (!statSync(file).isFile())
+            return { kind: 'missing' };
+    }
+    catch {
+        return { kind: 'missing' };
+    }
+    return { kind: 'file', filePath: file };
+}
+function contentType(filePath) {
+    return MIME_TYPES[extname(filePath).toLowerCase()] ?? 'application/octet-stream';
+}
+function cacheControl(requestPath, filePath) {
+    // `index.html` is the SPA entry: always revalidate so deploys take effect.
+    if (filePath.endsWith(`${sep}index.html`))
+        return 'no-cache';
+    // Vite content-hashes filenames under /assets/: immutable for a year.
+    if (requestPath.startsWith('/assets/'))
+        return 'public, max-age=31536000, immutable';
+    return 'public, max-age=3600';
+}
+function sendJsonError(res, status, code, message) {
+    const text = JSON.stringify({ error: { code, message } });
+    res.writeHead(status, {
+        'Content-Type': 'application/json; charset=utf-8',
+        'Content-Length': Buffer.byteLength(text),
+    });
+    res.end(text);
+}
+/**
+ * Serve one request from the bundled web UI.
+ *
+ * Returns `true` when the request was answered (file, 404, 400 or 304);
+ * `false` when static serving does not apply (no assets, wrong method) and
+ * the caller should keep routing (API routes, then its own 404).
+ */
+export async function serveStatic(req, res, log) {
+    const webRoot = resolveWebRoot();
+    if (webRoot === null)
+        return false;
+    const method = (req.method ?? 'GET').toUpperCase();
+    if (method !== 'GET' && method !== 'HEAD')
+        return false;
+    let pathname;
+    try {
+        pathname = new URL(req.url ?? '/', 'http://localhost').pathname;
+    }
+    catch {
+        sendJsonError(res, 400, 'BAD_REQUEST', 'Malformed request URL');
+        return true;
+    }
+    const resolution = resolveStaticFile(webRoot, pathname);
+    if (resolution.kind !== 'file') {
+        log?.('debug', 'static miss', {
+            method,
+            path: pathname,
+            blocked: resolution.kind === 'blocked',
+        });
+        sendJsonError(res, 404, 'NOT_FOUND', `Unknown path: ${pathname}`);
+        return true;
+    }
+    let stat;
+    try {
+        stat = statSync(resolution.filePath);
+    }
+    catch {
+        sendJsonError(res, 404, 'NOT_FOUND', `Unknown path: ${pathname}`);
+        return true;
+    }
+    const etag = `W/"${stat.size.toString(16)}-${Math.floor(stat.mtimeMs).toString(16)}"`;
+    if (req.headers['if-none-match'] === etag) {
+        res.writeHead(304, { ETag: etag });
+        res.end();
+        log?.('debug', 'static', { method, path: pathname, status: 304 });
+        return true;
+    }
+    const headers = {
+        'Content-Type': contentType(resolution.filePath),
+        'Content-Length': stat.size,
+        'Last-Modified': stat.mtime.toUTCString(),
+        ETag: etag,
+        'Cache-Control': cacheControl(pathname, resolution.filePath),
+    };
+    if (method === 'HEAD') {
+        res.writeHead(200, headers);
+        res.end();
+        log?.('debug', 'static', { method, path: pathname, status: 200 });
+        return true;
+    }
+    await new Promise((done) => {
+        res.writeHead(200, headers);
+        const stream = createReadStream(resolution.filePath);
+        stream.on('error', () => {
+            if (!res.headersSent) {
+                sendJsonError(res, 500, 'INTERNAL_ERROR', 'Failed to read static file');
+            }
+            else {
+                res.destroy();
+            }
+            done();
+        });
+        stream.pipe(res);
+        res.on('finish', () => done());
+        // `close` also fires on aborted connections; `done` is idempotent.
+        res.on('close', () => done());
+    });
+    log?.('debug', 'static', { method, path: pathname, status: 200 });
+    return true;
+}

package/dist/gateway/turns/clarify-tool.js

@@ -0,0 +1,57 @@
+export const CLARIFY_TOOL_NAME = 'clarify';
+export const clarifyDefinition = {
+    name: CLARIFY_TOOL_NAME,
+    description: 'Ask the user one or more questions when you need a decision, clarification, or feedback before proceeding. ' +
+        'Pass every question in `questions` (1-5 entries). Each question can have single-select choices, ' +
+        'multi-select choices, or open-ended free text.',
+    parameters: {
+        type: 'object',
+        properties: {
+            questions: {
+                type: 'array',
+                description: 'The questions to ask the user.',
+                items: {
+                    type: 'object',
+                    properties: {
+                        question: { type: 'string', description: 'Question text.' },
+                        choices: {
+                            type: 'array',
+                            items: { type: 'string' },
+                            description: 'Optional selectable options (recommended first).',
+                        },
+                        multi_select: { type: 'boolean', description: 'Allow multiple selections.' },
+                    },
+                    required: ['question'],
+                },
+            },
+        },
+        required: ['questions'],
+        additionalProperties: false,
+    },
+};
+export function registerClarifyTool(registry) {
+    registry.registerTool(clarifyDefinition, async (call) => {
+        const args = (call.arguments ?? {});
+        const questions = args.questions ?? [];
+        if (!questions.length) {
+            return { callId: call.id, name: call.name, output: 'No questions provided.', error: true };
+        }
+        const outputLines = ['[CLARIFY REQUEST TO USER]'];
+        questions.forEach((q, i) => {
+            outputLines.push(`Question ${i + 1}: ${q.question}`);
+            if (q.choices?.length) {
+                outputLines.push(`Choices (${q.multi_select ? 'Multi-select' : 'Single-select'}):`);
+                q.choices.forEach((c, ci) => outputLines.push(`  [${ci + 1}] ${c}`));
+            }
+            else {
+                outputLines.push('  (Free-text response)');
+            }
+        });
+        return {
+            callId: call.id,
+            name: call.name,
+            output: outputLines.join('\n'),
+            error: false,
+        };
+    });
+}

package/dist/gateway/turns/cronjob-tool.js

@@ -0,0 +1,96 @@
+export const CRONJOB_TOOL_NAME = 'cronjob_manage';
+export const cronjobDefinition = {
+    name: CRONJOB_TOOL_NAME,
+    description: 'Manage scheduled cron jobs. The bot can automatically run prompts on a schedule (e.g., daily summaries). ' +
+        'Actions: "list" (show all), "create" (needs name, cron, prompt; timezone is optional), "update" (needs id, and fields to update), ' +
+        '"toggle" (needs id, enabled: boolean), "delete" (needs id), "run_now" (needs id).',
+    parameters: {
+        type: 'object',
+        properties: {
+            action: {
+                type: 'string',
+                enum: ['list', 'create', 'update', 'toggle', 'delete', 'run_now'],
+                description: 'The action to perform.',
+            },
+            id: { type: 'string', description: 'Job ID (required for update, toggle, delete, run_now).' },
+            name: { type: 'string', description: 'Job name (required for create).' },
+            cron: { type: 'string', description: 'Cron expression (e.g. "0 9 * * *", required for create).' },
+            timezone: { type: 'string', description: 'IANA timezone (e.g. "Asia/Ho_Chi_Minh").' },
+            prompt: { type: 'string', description: 'The prompt text to execute when the job fires.' },
+            enabled: { type: 'boolean', description: 'Enable or disable the job.' },
+        },
+        required: ['action'],
+        additionalProperties: false,
+    },
+};
+export function registerCronjobTool(registry, schedulerService) {
+    registry.registerTool(cronjobDefinition, async (call) => {
+        const { registry: schedRegistry, authContext } = schedulerService.internals;
+        const args = (call.arguments ?? {});
+        try {
+            switch (args.action) {
+                case 'list': {
+                    const list = await schedRegistry.list(authContext);
+                    return { callId: call.id, name: call.name, output: JSON.stringify(list, null, 2), error: false };
+                }
+                case 'create': {
+                    if (!args.name || !args.cron || !args.prompt) {
+                        throw new Error('create requires name, cron, and prompt');
+                    }
+                    const job = await schedRegistry.create(authContext, {
+                        name: args.name,
+                        cron: args.cron,
+                        timezone: args.timezone ?? 'Asia/Ho_Chi_Minh',
+                        promptText: args.prompt,
+                        enabled: args.enabled !== false,
+                        concurrencyPolicy: 'forbid',
+                        missedRunPolicy: 'skip',
+                        maxCatchUp: 3,
+                    });
+                    return { callId: call.id, name: call.name, output: `Created job ${job.id}`, error: false };
+                }
+                case 'update': {
+                    if (!args.id)
+                        throw new Error('update requires id');
+                    const updates = {
+                        ...(args.name === undefined ? {} : { name: args.name }),
+                        ...(args.cron === undefined ? {} : { cron: args.cron }),
+                        ...(args.timezone === undefined ? {} : { timezone: args.timezone }),
+                        ...(args.prompt === undefined ? {} : { promptText: args.prompt }),
+                        ...(args.enabled === undefined ? {} : { enabled: args.enabled }),
+                    };
+                    await schedRegistry.update(authContext, args.id, updates);
+                    return { callId: call.id, name: call.name, output: `Updated job ${args.id}`, error: false };
+                }
+                case 'toggle': {
+                    if (!args.id || typeof args.enabled !== 'boolean')
+                        throw new Error('toggle requires id and enabled boolean');
+                    await schedRegistry.update(authContext, args.id, { enabled: args.enabled });
+                    return { callId: call.id, name: call.name, output: `Toggled job ${args.id} to ${args.enabled}`, error: false };
+                }
+                case 'delete': {
+                    if (!args.id)
+                        throw new Error('delete requires id');
+                    await schedRegistry.remove(authContext, args.id);
+                    return { callId: call.id, name: call.name, output: `Deleted job ${args.id}`, error: false };
+                }
+                case 'run_now': {
+                    if (!args.id)
+                        throw new Error('run_now requires id');
+                    const res = await schedulerService.fireNow(args.id);
+                    return { callId: call.id, name: call.name, output: `Fired job ${args.id}, Turn ID: ${res.turnId}`, error: false };
+                }
+                default:
+                    throw new Error(`Unknown action: ${args.action}`);
+            }
+        }
+        catch (err) {
+            return {
+                callId: call.id,
+                name: call.name,
+                output: `cronjob_manage error: ${err instanceof Error ? err.message : String(err)}`,
+                error: true,
+            };
+        }
+    });
+}

package/dist/gateway/turns/deferred-tools.js

@@ -0,0 +1,154 @@
+export const TOOL_SEARCH_NAME = 'tool_search';
+export const TOOL_DESCRIBE_NAME = 'tool_describe';
+export const TOOL_CALL_NAME = 'tool_call';
+export const toolSearchDefinition = {
+    name: TOOL_SEARCH_NAME,
+    description: 'Search the catalog of deferred on-demand tools by keywords (e.g. ["github issue", "slack message"]). ' +
+        'Returns matching tool names and brief summaries. Use `tool_describe` to inspect parameters before calling.',
+    parameters: {
+        type: 'object',
+        properties: {
+            queries: {
+                type: 'array',
+                items: { type: 'string' },
+                description: 'Keyword search queries to run against tool names and descriptions.',
+            },
+            limit: {
+                type: 'number',
+                description: 'Maximum matches per query (default 5).',
+            },
+        },
+        required: ['queries'],
+        additionalProperties: false,
+    },
+};
+export const toolDescribeDefinition = {
+    name: TOOL_DESCRIBE_NAME,
+    description: 'Load the full parameter JSON schema for deferred tools returned by `tool_search`. ' +
+        'Call before `tool_call` to understand required parameters.',
+    parameters: {
+        type: 'object',
+        properties: {
+            names: {
+                type: 'array',
+                items: { type: 'string' },
+                description: 'Exact tool names to inspect schemas for.',
+            },
+        },
+        required: ['names'],
+        additionalProperties: false,
+    },
+};
+export const toolCallDefinition = {
+    name: TOOL_CALL_NAME,
+    description: 'Invoke one or more deferred tools loaded via `tool_search` and `tool_describe`. ' +
+        'Takes an array of {name, arguments} invocations and runs them in parallel.',
+    parameters: {
+        type: 'object',
+        properties: {
+            calls: {
+                type: 'array',
+                description: 'One or more tool calls to execute.',
+                items: {
+                    type: 'object',
+                    properties: {
+                        name: { type: 'string', description: 'Exact tool name to call.' },
+                        arguments: { type: 'object', description: 'Arguments matching the tool parameter schema.' },
+                    },
+                    required: ['name', 'arguments'],
+                },
+            },
+        },
+        required: ['calls'],
+        additionalProperties: false,
+    },
+};
+export class DeferredToolManager {
+    catalog = new Map();
+    registerDeferred(definition, handler) {
+        this.catalog.set(definition.name, { definition, handler });
+    }
+    registerTo(registry) {
+        // 1. tool_search
+        registry.registerTool(toolSearchDefinition, async (call) => {
+            const args = (call.arguments ?? {});
+            const queries = args.queries ?? [];
+            const limit = args.limit ?? 5;
+            const results = {};
+            for (const query of queries) {
+                const terms = query.toLowerCase().split(/\s+/).filter(Boolean);
+                const matches = [];
+                for (const [name, entry] of this.catalog.entries()) {
+                    const text = `${name} ${entry.definition.description}`.toLowerCase();
+                    const score = terms.reduce((acc, t) => acc + (text.includes(t) ? 1 : 0), 0);
+                    if (score > 0) {
+                        matches.push({
+                            name,
+                            description: entry.definition.description.slice(0, 160),
+                        });
+                    }
+                    if (matches.length >= limit)
+                        break;
+                }
+                results[query] = matches;
+            }
+            return {
+                callId: call.id,
+                name: call.name,
+                output: JSON.stringify(results, null, 2),
+                error: false,
+            };
+        });
+        // 2. tool_describe
+        registry.registerTool(toolDescribeDefinition, async (call) => {
+            const args = (call.arguments ?? {});
+            const names = args.names ?? [];
+            const schemas = {};
+            for (const name of names) {
+                const entry = this.catalog.get(name);
+                if (entry) {
+                    schemas[name] = {
+                        description: entry.definition.description,
+                        parameters: entry.definition.parameters,
+                    };
+                }
+                else {
+                    schemas[name] = { error: `Tool '${name}' not found in deferred catalog.` };
+                }
+            }
+            return {
+                callId: call.id,
+                name: call.name,
+                output: JSON.stringify(schemas, null, 2),
+                error: false,
+            };
+        });
+        // 3. tool_call
+        registry.registerTool(toolCallDefinition, async (call, signal) => {
+            const args = (call.arguments ?? {});
+            const calls = args.calls ?? [];
+            if (!calls.length) {
+                return { callId: call.id, name: call.name, output: 'No calls provided.', error: true };
+            }
+            const results = await Promise.all(calls.map(async (subCall) => {
+                const entry = this.catalog.get(subCall.name);
+                if (!entry) {
+                    return { name: subCall.name, error: `Tool '${subCall.name}' not found in deferred catalog.` };
+                }
+                try {
+                    const res = await entry.handler({ id: `deferred_${Date.now()}`, name: subCall.name, arguments: subCall.arguments }, signal);
+                    return { name: subCall.name, output: res.output, error: res.error };
+                }
+                catch (err) {
+                    return { name: subCall.name, error: err instanceof Error ? err.message : String(err) };
+                }
+            }));
+            return {
+                callId: call.id,
+                name: call.name,
+                output: JSON.stringify(results, null, 2),
+                error: results.some((r) => r.error),
+            };
+        });
+    }
+}

package/dist/gateway/turns/execute-code-tool.js

@@ -0,0 +1,84 @@
+import { randomUUID } from 'node:crypto';
+import { mkdirSync, rmSync, writeFileSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+import { DEFAULT_PREVIEW_BYTES, formatSpilledOutput, previewStreams, writeSpillover, } from './spillover.js';
+export const EXECUTE_CODE_TOOL_NAME = 'execute_code';
+export const executeCodeDefinition = {
+    name: EXECUTE_CODE_TOOL_NAME,
+    description: 'Run Python code programmatically. Use when you need filtering, data processing, ' +
+        'loops, or programmatic logic. Each call runs in a fresh Python process. ' +
+        'Print your final result to stdout.',
+    parameters: {
+        type: 'object',
+        properties: {
+            code: {
+                type: 'string',
+                description: 'Python code to execute.',
+            },
+        },
+        required: ['code'],
+        additionalProperties: false,
+    },
+};
+export function registerExecuteCodeTool(registry, options) {
+    const { sandbox, workspaceRoot } = options;
+    registry.registerTool(executeCodeDefinition, async (call) => {
+        const args = (call.arguments ?? {});
+        const code = args.code ?? '';
+        if (!code.trim()) {
+            return {
+                callId: call.id,
+                name: call.name,
+                output: 'execute_code error: empty code provided',
+                error: true,
+            };
+        }
+        const scratchDir = resolve(workspaceRoot, '.execute-code');
+        mkdirSync(scratchDir, { recursive: true });
+        const scriptPath = join(scratchDir, `${randomUUID()}.py`);
+        writeFileSync(scriptPath, code, 'utf-8');
+        let result;
+        try {
+            result = await sandbox.run(['python', scriptPath], {
+                cwd: scratchDir,
+                timeoutMs: 300_000,
+                envAllowlist: ['PATH', 'PYTHONPATH', 'TEMP', 'TMP', 'PYTHONUTF8', 'PYTHONIOENCODING'],
+            });
+        }
+        catch (err) {
+            return {
+                callId: call.id,
+                name: call.name,
+                output: `execute_code failed: ${err instanceof Error ? err.message : String(err)}`,
+                error: true,
+            };
+        }
+        finally {
+            rmSync(scriptPath, { force: true });
+        }
+        const spillover = options.spillover;
+        let output;
+        if (result.truncated && spillover !== undefined) {
+            const info = writeSpillover(spillover.dir, call.id, result.stdout, result.stderr, {
+                exitCode: result.exitCode,
+                timedOut: result.timedOut,
+                truncated: result.truncated,
+            }, {
+                maxAgeMs: spillover.maxAgeMs,
+                maxTotalBytes: spillover.maxTotalBytes,
+            });
+            output = formatSpilledOutput(previewStreams(result.stdout, result.stderr, spillover.previewBytes ?? DEFAULT_PREVIEW_BYTES), info);
+        }
+        else {
+            output =
+                [result.stdout, result.stderr].filter(Boolean).join('\n') ||
+                    'Executed successfully with no output.';
+        }
+        return {
+            callId: call.id,
+            name: call.name,
+            output,
+            error: result.timedOut || result.exitCode !== 0,
+        };
+    });
+}