@botbotgo/agent-harness 0.0.1

package/dist/persistence/file-store.js

@@ -0,0 +1,282 @@
+import path from "node:path";
+import { readdir } from "node:fs/promises";
+import { ensureDir, fileExists, readJson, writeJson } from "../utils/fs.js";
+export class FilePersistence {
+    runRoot;
+    constructor(runRoot) {
+        this.runRoot = runRoot;
+    }
+    async initialize() {
+        await Promise.all([
+            "indexes/threads",
+            "indexes/runs",
+            "indexes/approvals",
+            "indexes/delegations",
+            "threads",
+        ].map((segment) => ensureDir(path.join(this.runRoot, segment))));
+    }
+    threadDir(threadId) {
+        return path.join(this.runRoot, "threads", threadId);
+    }
+    runDir(threadId, runId) {
+        return path.join(this.threadDir(threadId), "runs", runId);
+    }
+    async createThread(input) {
+        const meta = {
+            threadId: input.threadId,
+            workspaceId: "default",
+            entryAgentId: input.agentId,
+            createdAt: input.createdAt,
+            updatedAt: input.createdAt,
+            status: input.status,
+            latestRunId: input.runId,
+        };
+        await writeJson(path.join(this.threadDir(input.threadId), "meta.json"), meta);
+        await writeJson(path.join(this.threadDir(input.threadId), "messages.json"), {
+            threadId: input.threadId,
+            items: [],
+        });
+        await writeJson(path.join(this.runRoot, "indexes", "threads", `${input.threadId}.json`), {
+            threadId: input.threadId,
+            status: input.status,
+            latestRunId: input.runId,
+            updatedAt: input.createdAt,
+        });
+    }
+    async createRun(input) {
+        const runDir = this.runDir(input.threadId, input.runId);
+        await ensureDir(path.join(runDir, "events"));
+        await ensureDir(path.join(runDir, "approvals"));
+        await ensureDir(path.join(runDir, "delegations"));
+        const meta = {
+            runId: input.runId,
+            threadId: input.threadId,
+            agentId: input.agentId,
+            executionMode: input.executionMode,
+            createdAt: input.createdAt,
+            updatedAt: input.createdAt,
+        };
+        const lifecycle = {
+            state: "running",
+            previousState: null,
+            stateEnteredAt: input.createdAt,
+            lastTransitionAt: input.createdAt,
+            resumable: false,
+            checkpointRef: null,
+        };
+        await Promise.all([
+            writeJson(path.join(runDir, "meta.json"), meta),
+            writeJson(path.join(runDir, "lifecycle.json"), lifecycle),
+            writeJson(path.join(runDir, "checkpoint-ref.json"), {
+                threadId: input.threadId,
+                runId: input.runId,
+                checkpointRef: null,
+                savedAt: input.createdAt,
+                kind: "langgraph-checkpoint",
+            }),
+            writeJson(path.join(runDir, "artifacts.json"), {
+                threadId: input.threadId,
+                runId: input.runId,
+                items: [],
+            }),
+            writeJson(path.join(runDir, "error.json"), {
+                hasError: false,
+                lastError: null,
+            }),
+            writeJson(path.join(this.runRoot, "indexes", "runs", `${input.runId}.json`), {
+                runId: input.runId,
+                threadId: input.threadId,
+                state: "running",
+                resumable: false,
+                updatedAt: input.createdAt,
+            }),
+        ]);
+    }
+    async setRunState(threadId, runId, state, checkpointRef) {
+        const lifecyclePath = path.join(this.runDir(threadId, runId), "lifecycle.json");
+        const lifecycle = await readJson(lifecyclePath);
+        const now = new Date().toISOString();
+        const next = {
+            state,
+            previousState: lifecycle.state,
+            stateEnteredAt: now,
+            lastTransitionAt: now,
+            resumable: state === "waiting_for_approval",
+            checkpointRef: checkpointRef ?? lifecycle.checkpointRef,
+        };
+        await writeJson(lifecyclePath, next);
+        if (checkpointRef !== undefined) {
+            await writeJson(path.join(this.runDir(threadId, runId), "checkpoint-ref.json"), {
+                threadId,
+                runId,
+                checkpointRef,
+                savedAt: now,
+                kind: "langgraph-checkpoint",
+            });
+        }
+        await writeJson(path.join(this.runRoot, "indexes", "runs", `${runId}.json`), {
+            runId,
+            threadId,
+            state,
+            resumable: next.resumable,
+            updatedAt: now,
+        });
+        const threadMetaPath = path.join(this.threadDir(threadId), "meta.json");
+        const threadMeta = await readJson(threadMetaPath);
+        threadMeta.status = state;
+        threadMeta.updatedAt = now;
+        threadMeta.latestRunId = runId;
+        await writeJson(threadMetaPath, threadMeta);
+        await writeJson(path.join(this.runRoot, "indexes", "threads", `${threadId}.json`), {
+            threadId,
+            status: state,
+            latestRunId: runId,
+            updatedAt: now,
+        });
+    }
+    async appendEvent(event) {
+        const sequenceId = String(event.sequence).padStart(6, "0");
+        await writeJson(path.join(this.runDir(event.threadId, event.runId), "events", `${sequenceId}.json`), event);
+    }
+    async listSessions() {
+        const threadIndexDir = path.join(this.runRoot, "indexes", "threads");
+        if (!(await fileExists(threadIndexDir))) {
+            return [];
+        }
+        const entries = await readdir(threadIndexDir);
+        const records = await Promise.all(entries.map(async (entry) => {
+            const index = await readJson(path.join(threadIndexDir, entry));
+            const meta = await readJson(path.join(this.threadDir(index.threadId), "meta.json"));
+            return {
+                agentId: meta.entryAgentId,
+                threadId: index.threadId,
+                latestRunId: index.latestRunId,
+                createdAt: meta.createdAt,
+                updatedAt: index.updatedAt,
+                status: index.status,
+            };
+        }));
+        return records.sort((a, b) => b.updatedAt.localeCompare(a.updatedAt));
+    }
+    async getSession(threadId) {
+        const filePath = path.join(this.runRoot, "indexes", "threads", `${threadId}.json`);
+        if (!(await fileExists(filePath))) {
+            return null;
+        }
+        const [index, meta] = await Promise.all([
+            readJson(filePath),
+            readJson(path.join(this.threadDir(threadId), "meta.json")),
+        ]);
+        return {
+            agentId: meta.entryAgentId,
+            threadId,
+            latestRunId: index.latestRunId,
+            createdAt: meta.createdAt,
+            updatedAt: index.updatedAt,
+            status: index.status,
+        };
+    }
+    async listRunEvents(threadId, runId) {
+        const eventsDir = path.join(this.runDir(threadId, runId), "events");
+        if (!(await fileExists(eventsDir))) {
+            return [];
+        }
+        const entries = (await readdir(eventsDir)).sort();
+        return Promise.all(entries.map((entry) => readJson(path.join(eventsDir, entry))));
+    }
+    async listApprovals() {
+        const approvalsDir = path.join(this.runRoot, "indexes", "approvals");
+        if (!(await fileExists(approvalsDir))) {
+            return [];
+        }
+        const entries = (await readdir(approvalsDir)).sort();
+        return Promise.all(entries.map((entry) => readJson(path.join(approvalsDir, entry))));
+    }
+    async getApproval(approvalId) {
+        const approvalPath = path.join(this.runRoot, "indexes", "approvals", `${approvalId}.json`);
+        if (!(await fileExists(approvalPath))) {
+            return null;
+        }
+        return readJson(approvalPath);
+    }
+    async getRunApprovals(threadId, runId) {
+        const approvalsDir = path.join(this.runDir(threadId, runId), "approvals");
+        if (!(await fileExists(approvalsDir))) {
+            return [];
+        }
+        const entries = (await readdir(approvalsDir)).sort();
+        return Promise.all(entries.map((entry) => readJson(path.join(approvalsDir, entry))));
+    }
+    async listDelegations() {
+        const delegationsDir = path.join(this.runRoot, "indexes", "delegations");
+        if (!(await fileExists(delegationsDir))) {
+            return [];
+        }
+        const entries = (await readdir(delegationsDir)).sort();
+        return Promise.all(entries.map((entry) => readJson(path.join(delegationsDir, entry))));
+    }
+    async createApproval(record) {
+        await Promise.all([
+            writeJson(path.join(this.runDir(record.threadId, record.runId), "approvals", `${record.approvalId}.json`), record),
+            writeJson(path.join(this.runRoot, "indexes", "approvals", `${record.approvalId}.json`), record),
+        ]);
+    }
+    async resolveApproval(threadId, runId, approvalId, status) {
+        const approvalPath = path.join(this.runDir(threadId, runId), "approvals", `${approvalId}.json`);
+        const current = await readJson(approvalPath);
+        const updated = {
+            ...current,
+            status,
+            resolvedAt: new Date().toISOString(),
+        };
+        await Promise.all([
+            writeJson(approvalPath, updated),
+            writeJson(path.join(this.runRoot, "indexes", "approvals", `${approvalId}.json`), updated),
+        ]);
+        return updated;
+    }
+    async createDelegation(record) {
+        await Promise.all([
+            writeJson(path.join(this.runDir(record.threadId, record.runId), "delegations", `${record.delegationId}.json`), record),
+            writeJson(path.join(this.runRoot, "indexes", "delegations", `${record.delegationId}.json`), record),
+        ]);
+    }
+    async updateDelegation(threadId, runId, delegationId, patch) {
+        const delegationPath = path.join(this.runDir(threadId, runId), "delegations", `${delegationId}.json`);
+        const current = await readJson(delegationPath);
+        const updated = { ...current, ...patch };
+        await Promise.all([
+            writeJson(delegationPath, updated),
+            writeJson(path.join(this.runRoot, "indexes", "delegations", `${delegationId}.json`), updated),
+        ]);
+        return updated;
+    }
+    async createArtifact(threadId, runId, artifact, content) {
+        const runDir = this.runDir(threadId, runId);
+        await writeJson(path.join(runDir, artifact.path), content);
+        const artifactsPath = path.join(runDir, "artifacts.json");
+        const current = await readJson(artifactsPath);
+        current.items.push(artifact);
+        await writeJson(artifactsPath, current);
+        return artifact;
+    }
+    async listArtifacts(threadId, runId) {
+        return readJson(path.join(this.runDir(threadId, runId), "artifacts.json"));
+    }
+    async appendThreadMessage(threadId, message) {
+        const messagesPath = path.join(this.threadDir(threadId), "messages.json");
+        const current = (await fileExists(messagesPath))
+            ? await readJson(messagesPath)
+            : { threadId, items: [] };
+        current.items.push(message);
+        await writeJson(messagesPath, current);
+    }
+    async listThreadMessages(threadId, limit = 12) {
+        const messagesPath = path.join(this.threadDir(threadId), "messages.json");
+        if (!(await fileExists(messagesPath))) {
+            return [];
+        }
+        const current = await readJson(messagesPath);
+        return current.items.slice(-limit);
+    }
+}

package/dist/presentation.d.ts

@@ -0,0 +1,4 @@
+export declare function escapeHtml(value: string): string;
+export declare function markdownToHtml(markdown: string): string;
+export declare function markdownToConsole(markdown: string): string;
+export declare function renderTemplate(data: Record<string, unknown>, template: string): string;

package/dist/presentation.js

@@ -0,0 +1,175 @@
+import { existsSync, readFileSync } from "node:fs";
+import Mustache from "mustache";
+export function escapeHtml(value) {
+    return value
+        .replaceAll("&", "&")
+        .replaceAll("<", "&lt;")
+        .replaceAll(">", "&gt;")
+        .replaceAll('"', "&quot;")
+        .replaceAll("'", "&#39;");
+}
+function renderInlineMarkdown(text) {
+    const escaped = escapeHtml(text);
+    return escaped
+        .replace(/\*\*(.+?)\*\*/g, "<strong>$1</strong>")
+        .replace(/\*(.+?)\*/g, "<em>$1</em>")
+        .replace(/`([^`]+)`/g, "<code>$1</code>");
+}
+function renderInlineConsoleMarkdown(text) {
+    return text
+        .replace(/`([^`]+)`/g, "\u001b[100m $1 \u001b[0m")
+        .replace(/\*\*([^*]+)\*\*/g, "\u001b[1m$1\u001b[0m")
+        .replace(/\*([^*]+)\*/g, "\u001b[3m$1\u001b[0m")
+        .replace(/\[([^\]]+)\]\(([^)]+)\)/g, "$1 ($2)");
+}
+function stripAnsi(text) {
+    return text.replace(/\u001b\[[0-9;]*m/g, "");
+}
+function parseMarkdownTableRow(line) {
+    const normalized = line.trim().replace(/^\|/, "").replace(/\|$/, "");
+    return normalized.split("|").map((cell) => cell.trim());
+}
+function isMarkdownTableSeparator(line) {
+    const cells = parseMarkdownTableRow(line);
+    return cells.length > 0 && cells.every((cell) => /^:?-{3,}:?$/.test(cell));
+}
+function renderMarkdownTable(block) {
+    const lines = block
+        .split("\n")
+        .map((line) => line.trimEnd())
+        .filter((line) => line.trim().length > 0);
+    if (lines.length < 2 || !lines.every((line) => line.includes("|")) || !isMarkdownTableSeparator(lines[1] ?? "")) {
+        return undefined;
+    }
+    const rows = lines.map(parseMarkdownTableRow);
+    const header = rows[0] ?? [];
+    const body = rows.slice(2);
+    const columnCount = Math.max(header.length, ...body.map((row) => row.length));
+    const normalizedRows = [header, ...body].map((row) => Array.from({ length: columnCount }, (_, index) => renderInlineConsoleMarkdown(row[index] ?? "")));
+    const widths = Array.from({ length: columnCount }, (_, index) => Math.max(...normalizedRows.map((row) => stripAnsi(row[index] ?? "").length), 0));
+    const renderRow = (row) => `| ${row
+        .map((cell, index) => cell.padEnd(widths[index] + (cell.length - stripAnsi(cell).length)))
+        .join(" | ")} |`;
+    const separator = `|-${widths.map((width) => "-".repeat(Math.max(3, width))).join("-|-")}-|`;
+    return [renderRow(normalizedRows[0] ?? []), separator, ...normalizedRows.slice(1).map(renderRow)].join("\n");
+}
+export function markdownToHtml(markdown) {
+    const normalized = markdown.replace(/\r\n/g, "\n");
+    const blocks = normalized.split(/\n\n+/);
+    const html = [];
+    for (const block of blocks) {
+        const trimmed = block.trim();
+        if (!trimmed) {
+            continue;
+        }
+        if (trimmed.startsWith("```") && trimmed.endsWith("```")) {
+            const lines = trimmed.split("\n");
+            const language = lines[0]?.slice(3).trim();
+            const code = lines.slice(1, -1).join("\n");
+            html.push(`<pre class="ah-code"><code${language ? ` data-language="${escapeHtml(language)}"` : ""}>${escapeHtml(code)}</code></pre>`);
+            continue;
+        }
+        if (/^#{1,6}\s/.test(trimmed)) {
+            const match = trimmed.match(/^(#{1,6})\s+(.*)$/);
+            const level = match?.[1].length ?? 1;
+            const content = renderInlineMarkdown(match?.[2] ?? trimmed);
+            html.push(`<h${level}>${content}</h${level}>`);
+            continue;
+        }
+        if (trimmed.split("\n").every((line) => /^[-*]\s+/.test(line))) {
+            const items = trimmed
+                .split("\n")
+                .map((line) => line.replace(/^[-*]\s+/, ""))
+                .map((line) => `<li>${renderInlineMarkdown(line)}</li>`)
+                .join("");
+            html.push(`<ul>${items}</ul>`);
+            continue;
+        }
+        html.push(`<p>${trimmed
+            .split("\n")
+            .map((line) => renderInlineMarkdown(line))
+            .join("<br />")}</p>`);
+    }
+    return html.join("");
+}
+export function markdownToConsole(markdown) {
+    if (!markdown.includes("\n")) {
+        return renderInlineConsoleMarkdown(markdown);
+    }
+    const normalized = markdown.replace(/\r\n/g, "\n");
+    const blocks = normalized.split(/\n\n+/);
+    const rendered = [];
+    for (const block of blocks) {
+        const trimmed = block.trim();
+        if (!trimmed) {
+            continue;
+        }
+        const table = renderMarkdownTable(trimmed);
+        if (table) {
+            rendered.push(table);
+            continue;
+        }
+        if (trimmed.startsWith("```") && trimmed.endsWith("```")) {
+            const lines = trimmed.split("\n");
+            const language = lines[0]?.slice(3).trim();
+            const code = lines.slice(1, -1);
+            const label = language ? ` ${language} ` : " code ";
+            rendered.push([
+                `\u001b[2m┌${"─".repeat(Math.max(label.length, 6))}\u001b[0m`,
+                `\u001b[2m│\u001b[0m${label}`,
+                ...code.map((line) => `  ${line}`),
+                "\u001b[2m└──────\u001b[0m",
+            ].join("\n"));
+            continue;
+        }
+        if (/^#{1,6}\s/.test(trimmed)) {
+            const match = trimmed.match(/^(#{1,6})\s+(.*)$/);
+            const level = match?.[1].length ?? 1;
+            const title = renderInlineConsoleMarkdown(match?.[2] ?? trimmed);
+            const underline = level === 1 ? "=" : "-";
+            rendered.push(`\u001b[1m${title}\u001b[0m\n\u001b[2m${underline.repeat(Math.max(3, title.replace(/\u001b\[[0-9;]*m/g, "").length))}\u001b[0m`);
+            continue;
+        }
+        if (trimmed.split("\n").every((line) => /^[-*]\s+/.test(line))) {
+            rendered.push(trimmed
+                .split("\n")
+                .map((line) => line.replace(/^[-*]\s+/, "• "))
+                .map((line) => renderInlineConsoleMarkdown(line))
+                .join("\n"));
+            continue;
+        }
+        if (trimmed.split("\n").every((line) => /^\d+\.\s+/.test(line))) {
+            rendered.push(trimmed
+                .split("\n")
+                .map((line) => renderInlineConsoleMarkdown(line))
+                .join("\n"));
+            continue;
+        }
+        if (trimmed.split("\n").every((line) => /^>\s?/.test(line))) {
+            rendered.push(trimmed
+                .split("\n")
+                .map((line) => line.replace(/^>\s?/, ""))
+                .map((line) => `\u001b[2m│\u001b[0m ${renderInlineConsoleMarkdown(line)}`)
+                .join("\n"));
+            continue;
+        }
+        if (/^([-*_])(?:\s*\1){2,}$/.test(trimmed)) {
+            rendered.push(`\u001b[2m${"─".repeat(24)}\u001b[0m`);
+            continue;
+        }
+        rendered.push(trimmed
+            .split("\n")
+            .map((line) => renderInlineConsoleMarkdown(line))
+            .join("\n"));
+    }
+    return rendered.join("\n\n");
+}
+function resolveTemplateSource(template) {
+    if (existsSync(template)) {
+        return readFileSync(template, "utf8");
+    }
+    return template;
+}
+export function renderTemplate(data, template) {
+    return Mustache.render(resolveTemplateSource(template), data);
+}

package/dist/runtime/agent-runtime-adapter.d.ts

@@ -0,0 +1,33 @@
+import type { CompiledAgentBinding, RunResult, RuntimeAdapterOptions, TranscriptMessage } from "../contracts/types.js";
+import { type RuntimeStreamChunk } from "./parsing/stream-event-parsing.js";
+type RunnableLike = {
+    invoke: (input: unknown, config?: Record<string, unknown>) => Promise<unknown>;
+    stream?: (input: unknown, config?: Record<string, unknown>) => Promise<AsyncIterable<unknown>>;
+    streamEvents?: (input: unknown, config?: Record<string, unknown>) => Promise<AsyncIterable<unknown>>;
+};
+declare const AGENT_INTERRUPT_SENTINEL_PREFIX = "__agent_harness_interrupt__:";
+export declare class AgentRuntimeAdapter {
+    private readonly options;
+    constructor(options?: RuntimeAdapterOptions);
+    private materializeModelStream;
+    private createModelFallbackRunnable;
+    private applyStrictToolJsonInstruction;
+    private synthesizeDeepAgentAnswer;
+    private resolveModel;
+    private resolveTools;
+    private normalizeInterruptPolicy;
+    private compileInterruptOn;
+    private resolveInterruptOn;
+    private resolveMiddleware;
+    private resolveCheckpointer;
+    private buildRouteSystemPrompt;
+    private resolveSubagents;
+    private buildConversation;
+    create(binding: CompiledAgentBinding): Promise<RunnableLike>;
+    route(input: string, primaryBinding: CompiledAgentBinding, secondaryBinding: CompiledAgentBinding, options?: {
+        systemPrompt?: string;
+    }): Promise<string>;
+    invoke(binding: CompiledAgentBinding, input: string, threadId: string, runId: string, resumePayload?: unknown, history?: TranscriptMessage[]): Promise<RunResult>;
+    stream(binding: CompiledAgentBinding, input: string, threadId: string, history?: TranscriptMessage[]): AsyncGenerator<RuntimeStreamChunk | string>;
+}
+export { AgentRuntimeAdapter as RuntimeAdapter, AGENT_INTERRUPT_SENTINEL_PREFIX, AGENT_INTERRUPT_SENTINEL_PREFIX as INTERRUPT_SENTINEL_PREFIX, };