@theowlops/boombot 0.0.0-stage → 1.1.0

package/dist/gateway/services/persistent-memory.js

@@ -0,0 +1,196 @@
+/**
+ * Persistent Memory Manager (Hermes-style).
+ *
+ * Reads durable knowledge files (`MEMORY.md` and `USER.md`) from `~/.boombot/data/memory/`
+ * and formats them for injection into the turn's System Prompt.
+ *
+ * Mirrors Hermes Agent architecture:
+ * - `MEMORY.md`: System facts, conventions, tool quirks, and environment notes.
+ * - `USER.md`: User profile, identity, tone rules, and personal preferences.
+ */
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+export const MEMORY_BUDGET_CHARS = 2_200;
+export const USER_BUDGET_CHARS = 1_375;
+export class PersistentMemoryManager {
+    memoryDir;
+    memoryPath;
+    userPath;
+    constructor(dataDir) {
+        this.memoryDir = join(dataDir, 'memory');
+        this.memoryPath = join(this.memoryDir, 'MEMORY.md');
+        this.userPath = join(this.memoryDir, 'USER.md');
+        this.ensureInitialized();
+    }
+    ensureInitialized() {
+        if (!existsSync(this.memoryDir)) {
+            mkdirSync(this.memoryDir, { recursive: true });
+        }
+    }
+    getFilePath(target) {
+        return target === 'user' ? this.userPath : this.memoryPath;
+    }
+    getBudget(target) {
+        return target === 'user' ? USER_BUDGET_CHARS : MEMORY_BUDGET_CHARS;
+    }
+    readRaw(target) {
+        const file = this.getFilePath(target);
+        if (!existsSync(file))
+            return '';
+        try {
+            return readFileSync(file, 'utf8').trim();
+        }
+        catch {
+            return '';
+        }
+    }
+    writeRaw(target, content) {
+        this.ensureInitialized();
+        const file = this.getFilePath(target);
+        writeFileSync(file, content.trim(), 'utf8');
+    }
+    getAtoms(target) {
+        const raw = this.readRaw(target);
+        if (!raw)
+            return [];
+        return raw
+            .split(/\n§\n|\n§\r\n|\r\n§\r\n/)
+            .map((a) => a.trim())
+            .filter(Boolean);
+    }
+    setAtoms(target, atoms) {
+        const maxChars = this.getBudget(target);
+        const combined = atoms.filter(Boolean).join('\n§\n');
+        const currentChars = combined.length;
+        if (currentChars > maxChars) {
+            return {
+                success: false,
+                target,
+                currentChars,
+                maxChars,
+                percentUsed: Math.round((currentChars / maxChars) * 100),
+                message: `Memory update rejected: exceeds character budget (${currentChars}/${maxChars} chars). Remove or consolidate entries first.`,
+            };
+        }
+        this.writeRaw(target, combined);
+        return {
+            success: true,
+            target,
+            currentChars,
+            maxChars,
+            percentUsed: Math.round((currentChars / maxChars) * 100),
+            message: `Memory updated successfully (${currentChars}/${maxChars} chars, ${Math.round((currentChars / maxChars) * 100)}%).`,
+        };
+    }
+    applyOperation(op, defaultTarget = 'memory') {
+        const target = op.target ?? defaultTarget;
+        let atoms = this.getAtoms(target);
+        switch (op.action) {
+            case 'add': {
+                const text = (op.content ?? op.new_text ?? '').trim();
+                if (!text) {
+                    throw new Error("Action 'add' requires non-empty 'content'.");
+                }
+                atoms.push(text);
+                return this.setAtoms(target, atoms);
+            }
+            case 'replace': {
+                const needle = (op.old_text ?? '').trim();
+                const replacement = (op.content ?? op.new_text ?? '').trim();
+                if (!needle) {
+                    throw new Error("Action 'replace' requires 'old_text' to identify existing entry.");
+                }
+                if (!replacement) {
+                    throw new Error("Action 'replace' requires 'content' or 'new_text'.");
+                }
+                const index = atoms.findIndex((a) => a.includes(needle));
+                if (index === -1) {
+                    return {
+                        success: false,
+                        target,
+                        currentChars: this.readRaw(target).length,
+                        maxChars: this.getBudget(target),
+                        percentUsed: Math.round((this.readRaw(target).length / this.getBudget(target)) * 100),
+                        message: `Entry matching '${needle}' not found in ${target}.`,
+                    };
+                }
+                atoms[index] = replacement;
+                return this.setAtoms(target, atoms);
+            }
+            case 'remove': {
+                const needle = (op.old_text ?? '').trim();
+                if (!needle) {
+                    throw new Error("Action 'remove' requires 'old_text'.");
+                }
+                const originalLen = atoms.length;
+                atoms = atoms.filter((a) => !a.includes(needle));
+                if (atoms.length === originalLen) {
+                    return {
+                        success: false,
+                        target,
+                        currentChars: this.readRaw(target).length,
+                        maxChars: this.getBudget(target),
+                        percentUsed: Math.round((this.readRaw(target).length / this.getBudget(target)) * 100),
+                        message: `Entry matching '${needle}' not found in ${target}.`,
+                    };
+                }
+                return this.setAtoms(target, atoms);
+            }
+            default:
+                throw new Error(`Unsupported memory action: ${String(op.action)}`);
+        }
+    }
+    applyBatch(target, operations) {
+        let atoms = this.getAtoms(target);
+        for (const op of operations) {
+            switch (op.action) {
+                case 'add': {
+                    const text = (op.content ?? op.new_text ?? '').trim();
+                    if (text)
+                        atoms.push(text);
+                    break;
+                }
+                case 'replace': {
+                    const needle = (op.old_text ?? '').trim();
+                    const rep = (op.content ?? op.new_text ?? '').trim();
+                    if (needle && rep) {
+                        const idx = atoms.findIndex((a) => a.includes(needle));
+                        if (idx !== -1)
+                            atoms[idx] = rep;
+                    }
+                    break;
+                }
+                case 'remove': {
+                    const needle = (op.old_text ?? '').trim();
+                    if (needle) {
+                        atoms = atoms.filter((a) => !a.includes(needle));
+                    }
+                    break;
+                }
+            }
+        }
+        return this.setAtoms(target, atoms);
+    }
+    formatForSystemPrompt() {
+        const memoryRaw = this.readRaw('memory');
+        const userRaw = this.readRaw('user');
+        const sections = [];
+        if (memoryRaw) {
+            const len = memoryRaw.length;
+            const pct = Math.round((len / MEMORY_BUDGET_CHARS) * 100);
+            sections.push('══════════════════════════════════════════════\n' +
+                `MEMORY (your personal notes) [${pct}% — ${len.toLocaleString()}/${MEMORY_BUDGET_CHARS.toLocaleString()} chars]\n` +
+                '══════════════════════════════════════════════\n' +
+                memoryRaw);
+        }
+        if (userRaw) {
+            const len = userRaw.length;
+            const pct = Math.round((len / USER_BUDGET_CHARS) * 100);
+            sections.push('══════════════════════════════════════════════\n' +
+                `USER PROFILE (who the user is) [${pct}% — ${len.toLocaleString()}/${USER_BUDGET_CHARS.toLocaleString()} chars]\n` +
+                '══════════════════════════════════════════════\n' +
+                userRaw);
+        }
+        return sections.join('\n\n');
+    }
+}

package/dist/gateway/services/providers.js

@@ -0,0 +1,44 @@
+/**
+ * Gateway boot wiring for `@boombot/protocol`.
+ *
+ * Reads the master key from `BOOMBOT_MASTER_KEY` (boot fails loudly when it is
+ * missing, with instructions to generate one) and attaches a ready
+ * `ProviderService` to `ctx.providerService`. The gateway's command handlers
+ * (`handlers/providers.ts`) and the agent turn wiring consume it from there.
+ */
+import { join } from "node:path";
+import { createProviderService } from "@boombot/protocol";
+import { resolveEmbeddingClient, resolveLlmClient } from "./llm-client.js";
+/**
+ * Boot the provider service. Returns a shutdown function (file-backed store:
+ * nothing to close, kept for a uniform service lifecycle).
+ */
+export async function startProvidersService(ctx) {
+    const masterKey = process.env["BOOMBOT_MASTER_KEY"];
+    if (!masterKey) {
+        throw new Error("[boombot-gateway] BOOMBOT_MASTER_KEY is not set — provider API keys are " +
+            "stored encrypted at rest and require a master key to boot.\n" +
+            "Generate one with:\n" +
+            '  node -e "console.log(require(\'node:crypto\').randomBytes(32).toString(\'hex\'))"\n' +
+            "Then start the gateway with:\n" +
+            "  BOOMBOT_MASTER_KEY=<hex> pnpm --filter @boombot/gateway start");
+    }
+    const service = createProviderService({
+        storagePath: join(ctx.dataDir, "providers.json"),
+        masterKey,
+    });
+    await service.load();
+    // Attach the real LLM resolver: the turn loop's `LazyLlmClient` calls
+    // `resolveLlm()` through the structural `ProviderServiceLike` contract
+    // (turns/runtime-deps.ts). It stays off the `@boombot/protocol`
+    // interface on purpose — that package is a leaf and must not import
+    // `@boombot/core` for the `LlmClient` type.
+    ctx.providerService = {
+        ...service,
+        resolveLlm: () => resolveLlmClient(service),
+        resolveEmbeddings: () => resolveEmbeddingClient(service),
+    };
+    return async () => {
+        // File-backed store: no connections to close.
+    };
+}

package/dist/gateway/services/tasks.js

@@ -0,0 +1,237 @@
+/**
+ * Gateway boot wiring for `@boombot/core`.
+ *
+ * Starts the background task runner: a file-backed store at
+ * `<dataDir>/tasks.json`, a `TurnRunner` adapter over the real turn service
+ * (one turn per task step), and a `TaskEvent` -> `StreamEvent` bridge onto
+ * the gateway event bus. Attaches the ready `TaskRunner` to
+ * `ctx.taskService` for the `task.*` command handlers.
+ *
+ * Requires the turn service: without it the starter throws and `services.ts`
+ * boots degraded (`task.*` commands report unavailable).
+ */
+import { join } from 'node:path';
+import { createTaskRunner, createTaskStore, } from '@boombot/core';
+import { subscribeEvent, subscribeTurnDone } from '../events.js';
+/**
+ * Boot the task runner service. `recover()` reaps tasks left
+ * running/paused/awaiting-approval by a previous process as `interrupted`.
+ * Returns a shutdown function that cancels every in-flight task (running or
+ * awaiting approval) so step turns do not outlive the gateway.
+ */
+export async function startTasksService(ctx) {
+    const turnService = ctx.turnService;
+    if (turnService === undefined) {
+        // services.ts catches this and boots degraded (task.* unavailable).
+        throw new Error('turn service is not running: cannot start the task runner');
+    }
+    const store = createTaskStore({ storagePath: join(ctx.dataDir, 'tasks.json') });
+    await store.load();
+    const runner = createTaskRunner({
+        store,
+        turnRunner: adaptTurnService(turnService),
+        onEvent: (event) => {
+            ctx.events.publish(toStreamEvent(event));
+        },
+    });
+    await runner.recover();
+    ctx.taskService = runner;
+    const tasks = await runner.list();
+    const interrupted = tasks.filter((task) => task.status === 'interrupted').length;
+    ctx.log('info', 'task runner ready', { tasks: tasks.length, interrupted });
+    return async () => {
+        const current = await runner.list();
+        const inFlight = current.filter((task) => task.status === 'running' || task.status === 'awaiting_approval');
+        await Promise.all(inFlight.map(async (task) => {
+            try {
+                await runner.cancel(task.id);
+            }
+            catch (error) {
+                ctx.log('warn', `failed to cancel in-flight task on shutdown: ${task.id}`, {
+                    error: error instanceof Error ? error.message : String(error),
+                });
+            }
+        }));
+    };
+}
+/**
+ * Adapt the gateway turn service to the task runner's `TurnRunner` port.
+ * Each step submits a turn in the task's shared session and waits for its
+ * terminal stream event.
+ */
+function adaptTurnService(turnService) {
+    return {
+        runTurn: (input) => runStepTurn(turnService, input),
+        approveTurn: async (runId, approved, editedArgs) => {
+            const result = await turnService.approveTurn?.(runId, approved, editedArgs);
+            return result?.resumed ?? false;
+        },
+    };
+}
+async function runStepTurn(turnService, input) {
+    const { turnId, sessionId } = await turnService.submit({
+        input: input.prompt,
+        ...(input.sessionId !== undefined ? { sessionId: input.sessionId } : {}),
+    });
+    if (input.signal.aborted) {
+        await turnService.cancel(turnId).catch(() => false);
+        throw new Error('turn aborted');
+    }
+    return new Promise((resolve, reject) => {
+        const cleanup = () => {
+            unsubscribeDone();
+            unsubscribeError();
+            unsubscribeApproval();
+            input.signal.removeEventListener('abort', onAbort);
+        };
+        const settle = (result) => {
+            cleanup();
+            resolve(result);
+        };
+        const onTurnDone = (payload) => {
+            if (payload.turnId !== turnId)
+                return;
+            if (payload.status === 'completed') {
+                settle({
+                    status: 'completed',
+                    sessionId,
+                    ...(payload.output !== undefined ? { output: payload.output } : {}),
+                });
+            }
+            else {
+                // A non-completed terminal status ('cancelled', ...) is a failed step.
+                settle({ status: 'failed', sessionId, error: `turn ${payload.status}` });
+            }
+        };
+        const onTurnError = (event) => {
+            const payload = readTurnErrorPayload(event);
+            if (payload === undefined || payload.turnId !== turnId)
+                return;
+            settle({ status: 'failed', sessionId, error: payload.error });
+        };
+        const onAbort = () => {
+            // Best effort: the turn may already be gone. Either way the step
+            // reports the abort; a racing terminal event is ignored because
+            // cleanup() unsubscribed us first.
+            void (async () => {
+                try {
+                    await turnService.cancel(turnId);
+                }
+                catch {
+                    // The turn is gone or already settled; still report the abort.
+                }
+                cleanup();
+                reject(new Error('turn aborted'));
+            })();
+        };
+        const unsubscribeDone = subscribeTurnDone(onTurnDone);
+        const unsubscribeError = subscribeEvent('agent.turn.error', onTurnError);
+        const unsubscribeApproval = subscribeEvent('turn.approval_required', (event) => {
+            const payload = readApprovalPayload(event);
+            if (payload === undefined || payload.turnId !== turnId)
+                return;
+            input.onEvent?.({
+                type: 'approval_required',
+                runId: payload.runId,
+                toolName: payload.toolName,
+                args: payload.args,
+                reason: payload.reason,
+            });
+        });
+        input.signal.addEventListener('abort', onAbort, { once: true });
+        // Replay a retained terminal event: a fail-fast turn can settle between
+        // submit() resolving and the subscriptions above attaching. The turn
+        // service retains terminal events for exactly this late-subscriber case
+        // (see `handleTurnSSE` in events.ts).
+        const replay = turnService.getTerminalEvent?.(turnId);
+        if (replay !== undefined) {
+            const donePayload = readTurnDonePayload(replay);
+            if (donePayload !== undefined) {
+                onTurnDone(donePayload);
+            }
+            else {
+                onTurnError(replay);
+            }
+        }
+    });
+}
+/** Read `{ turnId, status, output? }` from an `agent.turn.done` stream event. */
+function readTurnDonePayload(event) {
+    if (event.type !== 'agent.turn.done')
+        return undefined;
+    const payload = event.payload;
+    if (typeof payload !== 'object' || payload === null)
+        return undefined;
+    const record = payload;
+    const { turnId, status, output } = record;
+    if (typeof turnId !== 'string' || typeof status !== 'string')
+        return undefined;
+    if (output !== undefined && typeof output !== 'string')
+        return undefined;
+    return { turnId, status, output };
+}
+/** Read `{ turnId, error }` from an `agent.turn.error` stream event. */
+function readTurnErrorPayload(event) {
+    const payload = event.payload;
+    if (typeof payload !== 'object' || payload === null)
+        return undefined;
+    const { turnId, error } = payload;
+    if (typeof turnId !== 'string' || typeof error !== 'string')
+        return undefined;
+    return { turnId, error };
+}
+/** Read the `turn.approval_required` payload (turnId + run correlation). */
+function readApprovalPayload(event) {
+    const payload = event.payload;
+    if (typeof payload !== 'object' || payload === null)
+        return undefined;
+    const record = payload;
+    const { turnId, runId, toolName, args, reason } = record;
+    if (typeof turnId !== 'string' ||
+        typeof runId !== 'string' ||
+        typeof toolName !== 'string' ||
+        typeof reason !== 'string' ||
+        typeof args !== 'object' ||
+        args === null) {
+        return undefined;
+    }
+    return { turnId, runId, toolName, args: args, reason };
+}
+// ---------------------------------------------------------------------------
+// TaskEvent -> StreamEvent bridge.
+// ---------------------------------------------------------------------------
+/**
+ * Map a task-runner `TaskEvent` onto the wire `task.*` stream event shape.
+ * Built directly (no `parseEvent`): the payload mirrors the `TaskEvent`
+ * fields 1:1 so it validates against the `task.*` schemas once they land
+ * in `@boombot/protocol`.
+ */
+function toStreamEvent(event) {
+    switch (event.type) {
+        case 'task.progress':
+            return streamEvent(event.type, {
+                taskId: event.taskId,
+                stepIndex: event.stepIndex,
+                totalSteps: event.totalSteps,
+                ...(event.detail !== undefined ? { detail: event.detail } : {}),
+            });
+        case 'task.checkpoint':
+            return streamEvent(event.type, { taskId: event.taskId, stepIndex: event.stepIndex });
+        case 'task.awaiting_approval':
+            return streamEvent(event.type, {
+                taskId: event.taskId,
+                runId: event.runId,
+                toolName: event.toolName,
+                reason: event.reason,
+            });
+        case 'task.failed':
+            return streamEvent(event.type, { taskId: event.taskId, error: event.error });
+        default:
+            return streamEvent(event.type, { taskId: event.taskId });
+    }
+}
+function streamEvent(type, payload) {
+    // The `task.*` schemas are additive to the protocol union; cast across the
+    // currently closed union so this compiles on both sides of that change.
+    return { type, payload };
+}

package/dist/gateway/services/verification.js

@@ -0,0 +1,124 @@
+import { DEFAULT_GUARD_CONFIG, EvidenceLedger, verifyTurnWithClaims, } from '@boombot/security';
+/** A per-turn verification middleware for the agent-core turn pipeline. */
+export function createVerificationMiddleware(deps) {
+    const config = { ...DEFAULT_GUARD_CONFIG, ...deps.config };
+    const ledger = new EvidenceLedger(config.maxExcerptChars);
+    // callId -> the model's original arguments for that call, captured from
+    // the `modelRound` phase so `toolRound` evidence keeps the args the
+    // model actually sent (the phase result only carries the call id).
+    const callArgs = new Map();
+    return {
+        name: 'reasoning-guard',
+        afterPhase(phase, _ctx, result) {
+            if (phase === 'modelRound') {
+                const round = result;
+                for (const call of round?.toolCalls ?? []) {
+                    callArgs.set(call.id, call.arguments);
+                }
+                return;
+            }
+            if (phase === 'toolRound') {
+                const outcome = result;
+                for (const toolResult of outcome?.results ?? []) {
+                    // Only executed calls become evidence. Policy denials and
+                    // approver rejections never reach a handler, so they are skipped.
+                    if (toolResult.deniedByPolicy === true ||
+                        toolResult.rejectedByApprover === true) {
+                        continue;
+                    }
+                    ledger.record({
+                        tool: toolResult.name,
+                        args: callArgs.get(toolResult.callId) ?? {
+                            callId: toolResult.callId,
+                        },
+                        output: toolResult.output,
+                        error: toolResult.error,
+                    });
+                }
+            }
+        },
+        wrapPhase(phase, next) {
+            if (phase !== 'finalize') {
+                return next();
+            }
+            return (async () => {
+                const result = (await next());
+                if (config.mode === 'off') {
+                    return result;
+                }
+                let verified;
+                let draft;
+                try {
+                    draft = lastAssistantText(result.messages);
+                    verified = verifyTurnWithClaims(draft, ledger, config);
+                }
+                catch {
+                    // Verification must never break a turn: fall back to the
+                    // unmodified finalizer result.
+                    return result;
+                }
+                try {
+                    deps.onVerified?.(verified);
+                }
+                catch {
+                    // A broken listener must never break the turn.
+                }
+                try {
+                    deps.publish(buildVerificationEvent(deps, verified));
+                }
+                catch {
+                    // A broken SSE stream must never break the turn.
+                }
+                if (verified.text === draft) {
+                    return result;
+                }
+                // Strict mode rewrote ungrounded spans: persist the verified text.
+                return {
+                    ...result,
+                    messages: replaceLastAssistantText(result.messages, verified.text),
+                };
+            })();
+        },
+    };
+}
+/** Build the schema-valid `turn.verification` stream event. */
+function buildVerificationEvent(deps, verified) {
+    const claimById = new Map();
+    for (const claim of verified.claims) {
+        claimById.set(claim.id, claim.text);
+    }
+    const payload = {
+        turnId: deps.turnId,
+        runId: deps.runId,
+        report: {
+            verdicts: verified.report.verdicts.map((verdict) => {
+                const claim = claimById.get(verdict.claimId);
+                return claim === undefined
+                    ? { verdict: verdict.verdict }
+                    : { verdict: verdict.verdict, claim };
+            }),
+            ungroundedCount: verified.report.ungroundedCount,
+        },
+    };
+    return { type: 'turn.verification', payload };
+}
+/** Content of the last assistant message, or '' when there is none. */
+function lastAssistantText(messages) {
+    for (let i = messages.length - 1; i >= 0; i -= 1) {
+        const m = messages[i];
+        if (m !== undefined && m.role === 'assistant') {
+            return m.content;
+        }
+    }
+    return '';
+}
+/** Replace the content of the last assistant message, keeping other fields. */
+function replaceLastAssistantText(messages, text) {
+    for (let i = messages.length - 1; i >= 0; i -= 1) {
+        const m = messages[i];
+        if (m !== undefined && m.role === 'assistant') {
+            return [...messages.slice(0, i), { ...m, content: text }, ...messages.slice(i + 1)];
+        }
+    }
+    return [...messages];
+}

package/dist/gateway/services/vision-payload.js

@@ -0,0 +1,48 @@
+const DATA_URL = /^data:(image\/(?:png|jpeg|gif|webp));base64,([A-Za-z0-9+/]+={0,2})$/i;
+/** Validate image references; only remote HTTP(S) or supported base64 image data URLs are accepted. */
+export function validateImageSource(source) {
+    if (/^https?:\/\//i.test(source))
+        return 'remote';
+    const match = DATA_URL.exec(source);
+    if (match) {
+        const data = match[2] ?? '';
+        if (data.length % 4 === 1)
+            throw new Error('Invalid image base64 payload.');
+        return 'data';
+    }
+    if (source.startsWith('data:'))
+        throw new Error('Image data URL must use a supported image media type and base64 encoding.');
+    throw new Error('Image source must use https://, http://, or a supported data:image/*;base64 URL.');
+}
+export function toOpenAiVisionContent(text, images) {
+    const content = [{ type: 'text', text }];
+    for (const image of images) {
+        validateImageSource(image.url);
+        content.push({
+            type: 'image_url',
+            image_url: { url: image.url, detail: image.detail ?? 'auto' },
+        });
+    }
+    return content;
+}
+export function toAnthropicVisionContent(text, images) {
+    const content = [{ type: 'text', text }];
+    for (const image of images) {
+        const sourceType = validateImageSource(image.url);
+        if (sourceType === 'remote') {
+            content.push({
+                type: 'image',
+                source: { type: 'url', url: image.url },
+            });
+            continue;
+        }
+        const match = DATA_URL.exec(image.url);
+        if (!match)
+            throw new Error('Invalid image data URL.');
+        content.push({
+            type: 'image',
+            source: { type: 'base64', media_type: match[1], data: match[2] },
+        });
+    }
+    return content;
+}