@botbotgo/agent-harness 0.0.156 → 0.0.158

package/dist/flow/export-mermaid.d.ts

@@ -0,0 +1,2 @@
+import type { FlowGraph, FlowGraphMermaidOptions } from "./types.js";
+export declare function exportFlowGraphToMermaid(graph: FlowGraph, options?: FlowGraphMermaidOptions): string;

package/dist/flow/export-mermaid.js

@@ -0,0 +1,96 @@
+const PRODUCT_VIEW_KINDS = new Set(["agent", "llm", "tool", "skill"]);
+function sanitizeMermaidId(value) {
+    return value.replace(/[^A-Za-z0-9_]/g, "_");
+}
+function escapeMermaidLabel(value) {
+    return value.replace(/"/g, '\\"');
+}
+function renderNode(node, mermaidId) {
+    const label = escapeMermaidLabel(`${node.label} [${node.status}]`);
+    switch (node.kind) {
+        case "approval":
+            return `  ${mermaidId}{"${label}"}`;
+        case "queue":
+            return `  ${mermaidId}[/"${label}"/]`;
+        case "recovery":
+            return `  ${mermaidId}{{"${label}"}}`;
+        case "artifact":
+            return `  ${mermaidId}[("${label}")]`;
+        case "skill":
+            return `  ${mermaidId}[["${label}"]]`;
+        case "memory":
+            return `  ${mermaidId}[("${label}")]`;
+        default:
+            return `  ${mermaidId}["${label}"]`;
+    }
+}
+function renderEdge(edge, fromId, toId) {
+    const connector = edge.kind === "retry" || edge.kind === "fallback" ? "-.->" : edge.kind === "resume" ? "==>" : "-->";
+    const label = edge.label ?? edge.condition ?? (edge.kind !== "sequence" && edge.kind !== "contains" ? edge.kind : "");
+    return label
+        ? `  ${fromId} ${connector}|"${escapeMermaidLabel(label)}"| ${toId}`
+        : `  ${fromId} ${connector} ${toId}`;
+}
+export function exportFlowGraphToMermaid(graph, options = {}) {
+    const direction = options.direction ?? "TD";
+    const view = options.view ?? "product";
+    const includedKinds = options.includeKinds
+        ? new Set(options.includeKinds)
+        : view === "debug"
+            ? null
+            : PRODUCT_VIEW_KINDS;
+    const includedEdgeKinds = options.includeEdgeKinds ? new Set(options.includeEdgeKinds) : null;
+    const includeGroups = options.includeGroups ?? true;
+    const includeDetails = options.includeDetails ?? false;
+    const nodes = graph.nodes.filter((node) => {
+        if (!includeDetails && node.layer === "detail") {
+            return false;
+        }
+        return includedKinds ? includedKinds.has(node.kind) : true;
+    });
+    const nodeIdSet = new Set(nodes.map((node) => node.id));
+    const edges = graph.edges.filter((edge) => {
+        if (!nodeIdSet.has(edge.from) || !nodeIdSet.has(edge.to)) {
+            return false;
+        }
+        return includedEdgeKinds ? includedEdgeKinds.has(edge.kind) : true;
+    });
+    const lines = [`flowchart ${direction}`];
+    const mermaidIdByNodeId = new Map();
+    for (const node of nodes) {
+        mermaidIdByNodeId.set(node.id, sanitizeMermaidId(node.id));
+    }
+    if (includeGroups) {
+        const groupedNodeIds = new Set();
+        for (const group of graph.groups) {
+            const groupNodes = group.nodeIds.filter((nodeId) => nodeIdSet.has(nodeId));
+            if (groupNodes.length === 0) {
+                continue;
+            }
+            lines.push(`  subgraph ${sanitizeMermaidId(group.id)}["${escapeMermaidLabel(group.label)}"]`);
+            for (const nodeId of groupNodes) {
+                groupedNodeIds.add(nodeId);
+                const node = nodes.find((candidate) => candidate.id === nodeId);
+                if (!node) {
+                    continue;
+                }
+                lines.push(renderNode(node, mermaidIdByNodeId.get(node.id)));
+            }
+            lines.push("  end");
+        }
+        for (const node of nodes) {
+            if (!groupedNodeIds.has(node.id)) {
+                lines.push(renderNode(node, mermaidIdByNodeId.get(node.id)));
+            }
+        }
+    }
+    else {
+        for (const node of nodes) {
+            lines.push(renderNode(node, mermaidIdByNodeId.get(node.id)));
+        }
+    }
+    for (const edge of edges) {
+        lines.push(renderEdge(edge, mermaidIdByNodeId.get(edge.from), mermaidIdByNodeId.get(edge.to)));
+    }
+    return lines.join("\n");
+}

package/dist/flow/export-sequence-mermaid.d.ts

@@ -0,0 +1,3 @@
+import type { FlowGraph } from "./types.js";
+import type { FlowGraphSequenceMermaidOptions } from "./types.js";
+export declare function exportFlowGraphToSequenceMermaid(graph: FlowGraph, options?: FlowGraphSequenceMermaidOptions): string;

package/dist/flow/export-sequence-mermaid.js

@@ -0,0 +1,169 @@
+const PRODUCT_VIEW_KINDS = new Set(["agent", "llm", "tool", "skill"]);
+function sanitizeAlias(value) {
+    return value.replace(/[^A-Za-z0-9_]/g, "_");
+}
+function escapeLabel(value) {
+    return value.replace(/"/g, '\\"');
+}
+function selectNodes(graph, options) {
+    const includedKinds = options.includeKinds
+        ? new Set(options.includeKinds)
+        : options.view === "debug"
+            ? null
+            : PRODUCT_VIEW_KINDS;
+    return graph.nodes.filter((node) => {
+        if (node.layer === "detail") {
+            return false;
+        }
+        if (includedKinds) {
+            return includedKinds.has(node.kind);
+        }
+        return node.kind === "run"
+            || node.kind === "agent"
+            || node.kind === "approval"
+            || node.kind === "recovery"
+            || node.kind === "llm"
+            || node.kind === "tool"
+            || node.kind === "skill"
+            || node.kind === "artifact";
+    });
+}
+function getParticipantsForNode(node) {
+    const runtimeParticipant = { id: "runtime", alias: "Runtime", label: "Runtime" };
+    const agentParticipant = {
+        id: `agent:${node.agentId ?? "agent"}`,
+        alias: sanitizeAlias(`Agent_${node.agentId ?? "agent"}`),
+        label: `Agent${node.agentId ? `:${node.agentId}` : ""}`,
+    };
+    if (node.kind === "run") {
+        return [
+            { id: "user", alias: "User", label: "User" },
+            runtimeParticipant,
+            agentParticipant,
+        ];
+    }
+    if (node.kind === "agent") {
+        const fromAgentId = typeof node.detail.fromAgentId === "string" ? node.detail.fromAgentId : "agent";
+        return [
+            {
+                id: `agent:${fromAgentId}`,
+                alias: sanitizeAlias(`Agent_${fromAgentId}`),
+                label: `Agent:${fromAgentId}`,
+            },
+            agentParticipant,
+        ];
+    }
+    if (node.kind === "approval") {
+        return [
+            runtimeParticipant,
+            { id: "operator", alias: "Operator", label: "Operator" },
+        ];
+    }
+    if (node.kind === "llm") {
+        return [
+            agentParticipant,
+            { id: "model", alias: "Model", label: "Model" },
+        ];
+    }
+    if (node.kind === "tool") {
+        return [
+            agentParticipant,
+            {
+                id: `tool:${node.label}`,
+                alias: sanitizeAlias(`Tool_${node.label}`),
+                label: `Tool:${node.label.replace(/\s+\[[^\]]+\]$/, "")}`,
+            },
+        ];
+    }
+    if (node.kind === "skill") {
+        return [
+            agentParticipant,
+            { id: "skill", alias: "Skill", label: "Skill" },
+        ];
+    }
+    if (node.kind === "recovery") {
+        return [
+            runtimeParticipant,
+            agentParticipant,
+        ];
+    }
+    if (node.kind === "artifact") {
+        return [
+            runtimeParticipant,
+            { id: "artifact", alias: "ArtifactStore", label: "ArtifactStore" },
+        ];
+    }
+    return [runtimeParticipant, agentParticipant];
+}
+function renderArrowForNode(node) {
+    if (node.kind === "run" && node.status === "started") {
+        return { from: "User", to: "Runtime", text: node.label };
+    }
+    if (node.kind === "run" && (node.status === "completed" || node.status === "failed")) {
+        return { from: "Runtime", to: "User", text: node.label };
+    }
+    if (node.kind === "agent") {
+        const fromAgentId = typeof node.detail.fromAgentId === "string" ? node.detail.fromAgentId : "agent";
+        return {
+            from: sanitizeAlias(`Agent_${fromAgentId}`),
+            to: sanitizeAlias(`Agent_${node.agentId ?? "agent"}`),
+            text: node.label,
+        };
+    }
+    if (node.kind === "approval" && node.status === "waiting") {
+        return { from: "Runtime", to: "Operator", text: node.label };
+    }
+    if (node.kind === "approval" && node.status === "resolved") {
+        return { from: "Operator", to: "Runtime", text: node.label };
+    }
+    if (node.kind === "recovery") {
+        return { from: "Runtime", to: sanitizeAlias(`Agent_${node.agentId ?? "agent"}`), text: node.label };
+    }
+    if (node.kind === "llm") {
+        return {
+            from: sanitizeAlias(`Agent_${node.agentId ?? "agent"}`),
+            to: "Model",
+            text: node.label,
+            dashed: node.status === "completed" || node.status === "failed",
+        };
+    }
+    if (node.kind === "tool") {
+        return {
+            from: sanitizeAlias(`Agent_${node.agentId ?? "agent"}`),
+            to: sanitizeAlias(`Tool_${node.label}`),
+            text: node.label,
+            dashed: node.status === "completed" || node.status === "failed",
+        };
+    }
+    if (node.kind === "skill") {
+        return {
+            from: sanitizeAlias(`Agent_${node.agentId ?? "agent"}`),
+            to: "Skill",
+            text: node.label,
+            dashed: node.status === "completed" || node.status === "failed",
+        };
+    }
+    if (node.kind === "artifact") {
+        return { from: "Runtime", to: "ArtifactStore", text: node.label };
+    }
+    return { from: "Runtime", to: sanitizeAlias(`Agent_${node.agentId ?? "agent"}`), text: node.label };
+}
+export function exportFlowGraphToSequenceMermaid(graph, options = {}) {
+    const nodes = selectNodes(graph, options);
+    const lines = ["sequenceDiagram"];
+    const participants = new Map();
+    for (const node of nodes) {
+        for (const participant of getParticipantsForNode(node)) {
+            participants.set(participant.id, participant);
+        }
+    }
+    for (const participant of participants.values()) {
+        lines.push(`  participant ${participant.alias} as ${escapeLabel(participant.label)}`);
+    }
+    for (const node of nodes) {
+        const arrow = renderArrowForNode(node);
+        const connector = arrow.dashed ? "-->>" : "->>";
+        lines.push(`  ${arrow.from}${connector}${arrow.to}: ${escapeLabel(node.label)}`);
+    }
+    return lines.join("\n");
+}

package/dist/flow/index.d.ts

@@ -0,0 +1,4 @@
+export { buildFlowGraph } from "./build-flow-graph.js";
+export { exportFlowGraphToMermaid } from "./export-mermaid.js";
+export { exportFlowGraphToSequenceMermaid } from "./export-sequence-mermaid.js";
+export type { BuildFlowGraphInput, FlowEdge, FlowEdgeKind, FlowGraph, FlowGraphMermaidOptions, FlowGraphSequenceMermaidOptions, FlowGroup, FlowGroupKind, FlowNode, FlowNodeKind, FlowNodeLayer, FlowNodeStatus, } from "./types.js";

package/dist/flow/index.js

@@ -0,0 +1,3 @@
+export { buildFlowGraph } from "./build-flow-graph.js";
+export { exportFlowGraphToMermaid } from "./export-mermaid.js";
+export { exportFlowGraphToSequenceMermaid } from "./export-sequence-mermaid.js";

package/dist/flow/types.d.ts

@@ -0,0 +1,75 @@
+import type { HarnessEvent, RuntimeTimelineItem } from "../contracts/types.js";
+import type { UpstreamTimelineProjection } from "../upstream-events.js";
+export type FlowNodeLayer = "runtime" | "execution" | "attempt" | "detail";
+export type FlowNodeKind = "run" | "agent" | "queue" | "approval" | "recovery" | "artifact" | "llm" | "tool" | "skill" | "memory" | "chain" | "result" | "thinking" | "other";
+export type FlowNodeStatus = "pending" | "started" | "completed" | "failed" | "waiting" | "resolved" | "skipped";
+export type FlowEdgeKind = "sequence" | "contains" | "approval" | "resume" | "retry" | "fallback" | "result" | "spawn";
+export type FlowGroupKind = "segment" | "approval-window" | "attempt-set" | "agent-scope";
+export type FlowNode = {
+    id: string;
+    layer: FlowNodeLayer;
+    kind: FlowNodeKind;
+    label: string;
+    status: FlowNodeStatus;
+    threadId: string;
+    runId: string;
+    agentId?: string;
+    startedAt?: string;
+    endedAt?: string;
+    sequenceStart?: number;
+    sequenceEnd?: number;
+    parentNodeId?: string;
+    groupId?: string;
+    sourceEventIds: string[];
+    detail: Record<string, unknown>;
+};
+export type FlowEdge = {
+    id: string;
+    from: string;
+    to: string;
+    kind: FlowEdgeKind;
+    label?: string;
+    condition?: string;
+    sourceEventIds: string[];
+    confidence?: number;
+};
+export type FlowGroup = {
+    id: string;
+    kind: FlowGroupKind;
+    label: string;
+    nodeIds: string[];
+    startedAt?: string;
+    endedAt?: string;
+};
+export type FlowGraph = {
+    graphId: string;
+    scope: "run" | "thread";
+    threadId: string;
+    runId: string;
+    nodes: FlowNode[];
+    edges: FlowEdge[];
+    groups: FlowGroup[];
+    metadata: Record<string, unknown>;
+};
+export type BuildFlowGraphInput = {
+    threadId?: string;
+    runId?: string;
+    scope?: FlowGraph["scope"];
+    runtimeEvents?: readonly HarnessEvent[];
+    runtimeTimeline?: readonly RuntimeTimelineItem[];
+    upstreamEvents?: readonly unknown[];
+    upstreamProjections?: readonly UpstreamTimelineProjection[];
+    metadata?: Record<string, unknown>;
+};
+export type FlowGraphMermaidOptions = {
+    view?: "product" | "debug";
+    direction?: "TD" | "LR";
+    includeGroups?: boolean;
+    includeDetails?: boolean;
+    includeKinds?: readonly FlowNodeKind[];
+    includeEdgeKinds?: readonly FlowEdgeKind[];
+};
+export type FlowGraphSequenceMermaidOptions = {
+    view?: "product" | "debug";
+    includeKinds?: readonly FlowNodeKind[];
+};

package/dist/flow/types.js

@@ -0,0 +1 @@
+export {};

package/dist/index.d.ts

@@ -1,5 +1,7 @@
-export { AgentHarnessRuntime, cancelRun, createAgentHarness, createUpstreamTimelineReducer, createToolMcpServer, deleteSession, describeInventory, getAgent, getApproval, getRequest, getHealth, listMemories, getSession, listAgentSkills, listApprovals, listRequests, listSessions, memorize, normalizeUserChatInput, recall, removeMemory, resolveApproval, run, serveToolsOverStdio, subscribe, stop, updateMemory, } from "./api.js";
-export type { ListMemoriesInput, ListMemoriesResult, MemoryDecision, MemoryKind, MemoryRecord, MemoryScope, MemorizeInput, MemorizeResult, NormalizeUserChatInputOptions, RecallInput, RecallResult, RemoveMemoryInput, UpdateMemoryInput, UserChatInput, UserChatMessage, } from "./api.js";
+export { AgentHarnessAcpServer, AgentHarnessRuntime, buildFlowGraph, cancelRun, createAgentHarness, createAcpServer, createUpstreamTimelineReducer, createToolMcpServer, deleteSession, describeInventory, exportEvaluationBundle, getArtifact, getAgent, getApproval, getRequest, getHealth, listMemories, getSession, listAgentSkills, listArtifacts, listApprovals, listRequests, listSessions, memorize, normalizeUserChatInput, recall, removeMemory, resolveApproval, run, serveToolsOverStdio, subscribe, stop, updateMemory, exportFlowGraphToMermaid, exportFlowGraphToSequenceMermaid, } from "./api.js";
+export type { AcpApproval, AcpArtifact, AcpEventNotification, AcpJsonRpcError, AcpJsonRpcRequest, AcpJsonRpcResponse, AcpJsonRpcSuccess, AcpRequestRecord, AcpRunRequestParams, AcpServerCapabilities, AcpSessionRecord, } from "./acp.js";
+export type { ListMemoriesInput, ListMemoriesResult, MemoryDecision, MemoryKind, MemoryRecord, MemoryScope, MemorizeInput, MemorizeResult, NormalizeUserChatInputOptions, RecallInput, RecallResult, RemoveMemoryInput, RuntimeEvaluationExport, RuntimeEvaluationExportInput, UpdateMemoryInput, UserChatInput, UserChatMessage, } from "./api.js";
+export type { BuildFlowGraphInput, FlowEdge, FlowEdgeKind, FlowGraph, FlowGraphMermaidOptions, FlowGraphSequenceMermaidOptions, FlowGroup, FlowGroupKind, FlowNode, FlowNodeKind, FlowNodeLayer, FlowNodeStatus, } from "./flow/index.js";
 export type { ToolMcpServerOptions } from "./mcp.js";
 export { tool } from "./tools.js";
 export type { UpstreamTimelineProjection, UpstreamTimelineReducer } from "./upstream-events.js";

package/dist/index.js

@@ -1,2 +1,2 @@
-export { AgentHarnessRuntime, cancelRun, createAgentHarness, createUpstreamTimelineReducer, createToolMcpServer, deleteSession, describeInventory, getAgent, getApproval, getRequest, getHealth, listMemories, getSession, listAgentSkills, listApprovals, listRequests, listSessions, memorize, normalizeUserChatInput, recall, removeMemory, resolveApproval, run, serveToolsOverStdio, subscribe, stop, updateMemory, } from "./api.js";
+export { AgentHarnessAcpServer, AgentHarnessRuntime, buildFlowGraph, cancelRun, createAgentHarness, createAcpServer, createUpstreamTimelineReducer, createToolMcpServer, deleteSession, describeInventory, exportEvaluationBundle, getArtifact, getAgent, getApproval, getRequest, getHealth, listMemories, getSession, listAgentSkills, listArtifacts, listApprovals, listRequests, listSessions, memorize, normalizeUserChatInput, recall, removeMemory, resolveApproval, run, serveToolsOverStdio, subscribe, stop, updateMemory, exportFlowGraphToMermaid, exportFlowGraphToSequenceMermaid, } from "./api.js";
 export { tool } from "./tools.js";

package/dist/package-version.d.ts

@@ -1 +1 @@
-export declare const AGENT_HARNESS_VERSION = "0.0.155";
+export declare const AGENT_HARNESS_VERSION = "0.0.157";

package/dist/package-version.js

@@ -1 +1 @@
-export const AGENT_HARNESS_VERSION = "0.0.155";
+export const AGENT_HARNESS_VERSION = "0.0.157";

package/dist/persistence/file-store.d.ts

@@ -69,6 +69,7 @@ export declare class FilePersistence implements RuntimePersistence {
     resolveApproval(threadId: string, runId: string, approvalId: string, status: InternalApprovalRecord["status"]): Promise<InternalApprovalRecord>;
     createArtifact(threadId: string, runId: string, artifact: ArtifactRecord, content: unknown): Promise<ArtifactRecord>;
     listArtifacts(threadId: string, runId: string): Promise<ArtifactListing>;
+    readArtifact(threadId: string, runId: string, artifactPath: string): Promise<unknown>;
     appendThreadMessage(threadId: string, message: TranscriptMessage): Promise<void>;
     listThreadMessages(threadId: string, limit?: number): Promise<TranscriptMessage[]>;
     saveRecoveryIntent(threadId: string, runId: string, intent: RecoveryIntent): Promise<void>;

package/dist/persistence/file-store.js

@@ -328,7 +328,9 @@ export class FilePersistence {
         if (!(await fileExists(eventsDir))) {
             return [];
         }
-        const entries = (await readdir(eventsDir)).sort();
+        const entries = (await readdir(eventsDir))
+            .filter((entry) => entry.endsWith(".json"))
+            .sort((left, right) => left.localeCompare(right));
         return Promise.all(entries.map((entry) => readJson(path.join(eventsDir, entry))));
     }
     async listApprovals(filter = {}) {
@@ -460,6 +462,13 @@ export class FilePersistence {
     async listArtifacts(threadId, runId) {
         return readJson(path.join(this.runDir(threadId, runId), "artifacts.json"));
     }
+    async readArtifact(threadId, runId, artifactPath) {
+        const filePath = path.join(this.runDir(threadId, runId), artifactPath);
+        if (!(await fileExists(filePath))) {
+            return null;
+        }
+        return readJson(filePath);
+    }
     async appendThreadMessage(threadId, message) {
         const messagesPath = path.join(this.threadDir(threadId), "messages.json");
         const current = (await fileExists(messagesPath))

package/dist/persistence/types.d.ts

@@ -120,6 +120,7 @@ export interface RuntimePersistence {
     }): Promise<void>;
     setRunState(threadId: string, runId: string, state: RunState, checkpointRef?: string | null): Promise<void>;
     appendEvent(event: HarnessEvent): Promise<void>;
+    listRunEvents(threadId: string, runId: string): Promise<HarnessEvent[]>;
     listSessions(filter?: ThreadSummaryFilter): Promise<ThreadSummary[]>;
     listRuns(filter?: RunSummaryFilter): Promise<RunSummary[]>;
     getRun(runId: string): Promise<RunSummary | null>;
@@ -147,6 +148,7 @@ export interface RuntimePersistence {
     resolveApproval(threadId: string, runId: string, approvalId: string, status: InternalApprovalRecord["status"]): Promise<InternalApprovalRecord>;
     createArtifact(threadId: string, runId: string, artifact: ArtifactRecord, content: unknown): Promise<ArtifactRecord>;
     listArtifacts(threadId: string, runId: string): Promise<ArtifactListing>;
+    readArtifact(threadId: string, runId: string, artifactPath: string): Promise<unknown>;
     appendThreadMessage(threadId: string, message: TranscriptMessage): Promise<void>;
     listThreadMessages(threadId: string, limit?: number): Promise<TranscriptMessage[]>;
     saveRecoveryIntent(threadId: string, runId: string, intent: RecoveryIntent): Promise<void>;

package/dist/runtime/adapter/tool/resolved-tool.d.ts

@@ -14,5 +14,5 @@ export declare function wrapResolvedToolWithModelFacingName<T>(resolvedTool: T,
 export declare function hasCallableToolHandler(value: unknown): value is ResolvedToolLike;
 export declare function normalizeResolvedToolSchema(resolvedTool: ResolvedToolLike): Record<string, unknown> | {
     parse?: (input: unknown) => unknown;
-} | z.ZodObject<{}, "passthrough", z.ZodTypeAny, z.objectOutputType<{}, z.ZodTypeAny, "passthrough">, z.objectInputType<{}, z.ZodTypeAny, "passthrough">> | undefined;
+} | z.ZodObject<{}, z.core.$loose> | undefined;
 export declare function asStructuredExecutableTool(resolvedTool: unknown, modelFacingName: string, description: string): unknown;

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

@@ -63,6 +63,7 @@ export declare class AgentRuntimeAdapter {
     private resolveTools;
     private getToolNameMapping;
     private resolveFilesystemBackend;
+    private resolveFilesystemRootDir;
     private resolveBuiltinMiddlewareBackend;
     private createDeclaredMiddlewareResolverOptions;
     private createAssemblyResolvers;
@@ -75,7 +76,10 @@ export declare class AgentRuntimeAdapter {
     private createLangChainRunnable;
     private createRunnable;
     private createDeepAgentRunnable;
-    create(binding: CompiledAgentBinding): Promise<RunnableLike>;
+    private buildRunnableCacheKey;
+    create(binding: CompiledAgentBinding, options?: {
+        threadId?: string;
+    }): Promise<RunnableLike>;
     invoke(binding: CompiledAgentBinding, input: MessageContent, threadId: string, runId: string, resumePayload?: unknown, history?: TranscriptMessage[], options?: {
         context?: Record<string, unknown>;
         state?: Record<string, unknown>;