@botbotgo/agent-harness 0.0.1

package/dist/runtime/index.d.ts

@@ -0,0 +1,10 @@
+export { AgentRuntimeAdapter, AGENT_INTERRUPT_SENTINEL_PREFIX } from "./agent-runtime-adapter.js";
+export { EventBus } from "./event-bus.js";
+export { FileCheckpointSaver } from "./file-checkpoint-saver.js";
+export { AgentHarness } from "./harness.js";
+export { describeWorkspaceInventory, findAgentBinding, listAgentSkills, listAgentTools, listAvailableAgents, listSpecialists, } from "./inventory.js";
+export * from "./parsing/index.js";
+export { PolicyEngine } from "./policy-engine.js";
+export { createInMemoryStore, FileBackedStore } from "./store.js";
+export * from "./support/index.js";
+export { ThreadMemorySync } from "./thread-memory-sync.js";

package/dist/runtime/index.js

@@ -0,0 +1,10 @@
+export { AgentRuntimeAdapter, AGENT_INTERRUPT_SENTINEL_PREFIX } from "./agent-runtime-adapter.js";
+export { EventBus } from "./event-bus.js";
+export { FileCheckpointSaver } from "./file-checkpoint-saver.js";
+export { AgentHarness } from "./harness.js";
+export { describeWorkspaceInventory, findAgentBinding, listAgentSkills, listAgentTools, listAvailableAgents, listSpecialists, } from "./inventory.js";
+export * from "./parsing/index.js";
+export { PolicyEngine } from "./policy-engine.js";
+export { createInMemoryStore, FileBackedStore } from "./store.js";
+export * from "./support/index.js";
+export { ThreadMemorySync } from "./thread-memory-sync.js";

package/dist/runtime/inventory.d.ts

@@ -0,0 +1,25 @@
+import type { CompiledAgentBinding, WorkspaceBundle } from "../contracts/types.js";
+export type InventoryToolRecord = {
+    name: string;
+    description: string;
+};
+export type InventorySkillRecord = {
+    name: string;
+    path: string;
+};
+export type InventoryAgentRecord = {
+    id: string;
+    description: string;
+    role: "host" | "specialist";
+    tools: InventoryToolRecord[];
+    skills: InventorySkillRecord[];
+};
+export declare function findAgentBinding(workspace: WorkspaceBundle, agentId: string): CompiledAgentBinding | undefined;
+export declare function listAgentTools(workspace: WorkspaceBundle, agentId: string): InventoryToolRecord[];
+export declare function listAgentSkills(workspace: WorkspaceBundle, agentId: string): InventorySkillRecord[];
+export declare function listSpecialists(workspace: WorkspaceBundle): InventoryAgentRecord[];
+export declare function listAvailableAgents(workspace: WorkspaceBundle): InventoryAgentRecord[];
+export declare function describeWorkspaceInventory(workspace: WorkspaceBundle): {
+    workspaceRoot: string;
+    agents: InventoryAgentRecord[];
+};

package/dist/runtime/inventory.js

@@ -0,0 +1,62 @@
+import { readSkillName } from "./support/skill-metadata.js";
+function listHostBindings(workspace) {
+    return Array.from(workspace.bindings.values()).filter((binding) => binding.harnessRuntime.hostFacing);
+}
+export function findAgentBinding(workspace, agentId) {
+    return workspace.bindings.get(agentId);
+}
+function dedupeTools(tools) {
+    const deduped = new Map();
+    for (const tool of tools) {
+        deduped.set(tool.name, { name: tool.name, description: tool.description });
+    }
+    return Array.from(deduped.values());
+}
+function toSkillRecords(skillPaths) {
+    return Array.from(new Set(skillPaths)).map((skillPath) => ({
+        name: readSkillName(skillPath),
+        path: skillPath,
+    }));
+}
+export function listAgentTools(workspace, agentId) {
+    const binding = findAgentBinding(workspace, agentId);
+    if (!binding) {
+        return [];
+    }
+    return dedupeTools(binding.langchainAgentParams?.tools ?? binding.deepAgentParams?.tools ?? []);
+}
+export function listAgentSkills(workspace, agentId) {
+    const binding = findAgentBinding(workspace, agentId);
+    if (!binding) {
+        return [];
+    }
+    return toSkillRecords(binding.deepAgentParams?.skills ?? []);
+}
+function describeSubagent(subagent) {
+    return {
+        id: subagent.name,
+        description: subagent.description,
+        role: "specialist",
+        tools: dedupeTools(subagent.tools ?? []),
+        skills: toSkillRecords(subagent.skills ?? []),
+    };
+}
+export function listSpecialists(workspace) {
+    return listHostBindings(workspace).flatMap((binding) => (binding.deepAgentParams?.subagents ?? []).map(describeSubagent));
+}
+export function listAvailableAgents(workspace) {
+    const topLevel = listHostBindings(workspace).map((binding) => ({
+        id: binding.agent.id,
+        description: binding.agent.description,
+        role: "host",
+        tools: listAgentTools(workspace, binding.agent.id),
+        skills: listAgentSkills(workspace, binding.agent.id),
+    }));
+    return [...topLevel, ...listSpecialists(workspace)];
+}
+export function describeWorkspaceInventory(workspace) {
+    return {
+        workspaceRoot: workspace.workspaceRoot,
+        agents: listAvailableAgents(workspace),
+    };
+}

package/dist/runtime/parsing/index.d.ts

@@ -0,0 +1,2 @@
+export { extractReasoningText, extractToolFallbackContext, extractVisibleOutput, hasToolCalls, isLikelyToolArgsObject, readTextContent, sanitizeVisibleText, tryParseJson, wrapResolvedModel, } from "./output-parsing.js";
+export { extractAgentStep, extractInterruptPayload, extractReasoningStreamOutput, extractTerminalStreamOutput, extractToolResult, normalizeTerminalOutputKey, readStreamDelta, type RuntimeStreamChunk, } from "./stream-event-parsing.js";

package/dist/runtime/parsing/index.js

@@ -0,0 +1,2 @@
+export { extractReasoningText, extractToolFallbackContext, extractVisibleOutput, hasToolCalls, isLikelyToolArgsObject, readTextContent, sanitizeVisibleText, tryParseJson, wrapResolvedModel, } from "./output-parsing.js";
+export { extractAgentStep, extractInterruptPayload, extractReasoningStreamOutput, extractTerminalStreamOutput, extractToolResult, normalizeTerminalOutputKey, readStreamDelta, } from "./stream-event-parsing.js";

package/dist/runtime/parsing/output-parsing.d.ts

@@ -0,0 +1,12 @@
+export declare function sanitizeVisibleText(value: string): string;
+export declare function tryParseJson(value: string): unknown | null;
+export declare function salvageToolArgs(value: unknown): Record<string, unknown> | null;
+export declare function isLikelyToolArgsObject(value: unknown): boolean;
+export declare function readTextContent(value: unknown): string;
+export declare function hasToolCalls(value: unknown): boolean;
+export declare function extractToolFallbackContext(value: unknown): string;
+export declare function extractVisibleOutput(value: unknown): string;
+export declare function isToolCallParseFailure(error: unknown): boolean;
+export declare const STRICT_TOOL_JSON_INSTRUCTION = "When calling tools, return only the tool call itself. The arguments must be a pure JSON object with no explanatory text before or after it.";
+export declare function wrapResolvedModel<T>(value: T): T;
+export declare function extractReasoningText(value: unknown): string;

package/dist/runtime/parsing/output-parsing.js

@@ -0,0 +1,424 @@
+import { AIMessage } from "langchain";
+export function sanitizeVisibleText(value) {
+    return value
+        .replace(/[A-Za-z0-9_]*Middleware\.after_model/g, "")
+        .replace(/todoListMiddleware\.after_model/g, "")
+        .replace(/__end__+/g, "")
+        .trim();
+}
+export function tryParseJson(value) {
+    try {
+        return JSON.parse(value);
+    }
+    catch {
+        return null;
+    }
+}
+function extractBalancedJsonObject(value) {
+    const start = value.indexOf("{");
+    if (start < 0)
+        return null;
+    let depth = 0;
+    let inString = false;
+    let escaping = false;
+    for (let index = start; index < value.length; index += 1) {
+        const char = value[index];
+        if (inString) {
+            if (escaping) {
+                escaping = false;
+                continue;
+            }
+            if (char === "\\") {
+                escaping = true;
+                continue;
+            }
+            if (char === "\"") {
+                inString = false;
+            }
+            continue;
+        }
+        if (char === "\"") {
+            inString = true;
+            continue;
+        }
+        if (char === "{") {
+            depth += 1;
+            continue;
+        }
+        if (char === "}") {
+            depth -= 1;
+            if (depth === 0) {
+                return value.slice(start, index + 1);
+            }
+        }
+    }
+    return null;
+}
+export function salvageToolArgs(value) {
+    if (typeof value === "object" && value && !Array.isArray(value)) {
+        return value;
+    }
+    if (typeof value !== "string") {
+        return null;
+    }
+    const trimmed = value.trim();
+    if (!trimmed) {
+        return {};
+    }
+    const direct = tryParseJson(trimmed);
+    if (typeof direct === "object" && direct && !Array.isArray(direct)) {
+        return direct;
+    }
+    const embedded = extractBalancedJsonObject(trimmed);
+    if (!embedded) {
+        return null;
+    }
+    const parsed = tryParseJson(embedded);
+    return typeof parsed === "object" && parsed && !Array.isArray(parsed) ? parsed : null;
+}
+function normalizeWriteTodosArgs(args) {
+    if (!Array.isArray(args.todos)) {
+        return args;
+    }
+    return {
+        ...args,
+        todos: args.todos.map((todo) => {
+            if (typeof todo !== "object" || !todo || Array.isArray(todo)) {
+                return todo;
+            }
+            const record = todo;
+            const content = typeof record.content === "string" && record.content.trim().length > 0
+                ? record.content
+                : typeof record.description === "string" && record.description.trim().length > 0
+                    ? record.description
+                    : undefined;
+            const normalized = {};
+            if (content !== undefined)
+                normalized.content = content;
+            if (typeof record.status === "string")
+                normalized.status = record.status;
+            return Object.keys(normalized).length > 0 ? normalized : todo;
+        }),
+    };
+}
+function normalizeKnownToolArgs(toolName, args) {
+    if (toolName === "write_todos") {
+        return normalizeWriteTodosArgs(args);
+    }
+    return args;
+}
+export function isLikelyToolArgsObject(value) {
+    if (typeof value !== "object" || !value || Array.isArray(value)) {
+        return false;
+    }
+    const keys = Object.keys(value);
+    if (keys.length === 0 || keys.length > 8) {
+        return false;
+    }
+    if (keys.some((key) => ["messages", "output", "content", "todos", "files", "skillsMetadata", "memoryContents"].includes(key))) {
+        return false;
+    }
+    return Object.values(value).every((item) => {
+        if (item == null)
+            return true;
+        if (typeof item === "string" || typeof item === "number" || typeof item === "boolean")
+            return true;
+        return Array.isArray(item) && item.every((entry) => typeof entry === "string" || typeof entry === "number" || typeof entry === "boolean");
+    });
+}
+function isLikelyMemoryWriteArgsObject(value) {
+    if (typeof value !== "object" || !value || Array.isArray(value)) {
+        return false;
+    }
+    const typed = value;
+    const target = typeof typed.file_path === "string"
+        ? typed.file_path
+        : typeof typed.path === "string"
+            ? typed.path
+            : "";
+    return target.startsWith("/memories/") && typeof typed.content === "string";
+}
+export function readTextContent(value) {
+    if (typeof value === "string")
+        return value;
+    if (Array.isArray(value))
+        return value.map((item) => readTextContent(item)).join("");
+    if (typeof value === "object" && value) {
+        if (isLikelyMemoryWriteArgsObject(value)) {
+            return "";
+        }
+        if ("text" in value && typeof value.text === "string") {
+            return value.text;
+        }
+        if ("content" in value) {
+            return readTextContent(value.content);
+        }
+        if ("lc_kwargs" in value && typeof value.lc_kwargs === "object") {
+            return readTextContent((value.lc_kwargs).content);
+        }
+        if ("kwargs" in value && typeof value.kwargs === "object") {
+            return readTextContent((value.kwargs).content);
+        }
+    }
+    return "";
+}
+function extractMessageContent(message) {
+    if (typeof message !== "object" || !message)
+        return "";
+    const typed = message;
+    if (typeof typed.content === "string")
+        return typed.content;
+    if (typeof typed.kwargs === "object" && typed.kwargs) {
+        return readTextContent(typed.kwargs.content);
+    }
+    return "";
+}
+function isToolMessageLike(message) {
+    if (typeof message !== "object" || !message)
+        return false;
+    const typed = message;
+    const ids = Array.isArray(typed.id) ? typed.id.filter((item) => typeof item === "string") : [];
+    const typeName = ids.at(-1);
+    const runtimeType = typeof typed._getType === "function"
+        ? typed._getType()
+        : typeof typed.getType === "function"
+            ? typed.getType()
+            : undefined;
+    return typeName === "ToolMessage" || runtimeType === "tool";
+}
+function extractToolMessageContents(messages) {
+    if (!Array.isArray(messages))
+        return [];
+    const results = [];
+    for (const message of messages) {
+        if (!isToolMessageLike(message))
+            continue;
+        const content = extractMessageContent(message);
+        if (content)
+            results.push(content);
+    }
+    return results;
+}
+export function hasToolCalls(value) {
+    if (typeof value !== "object" || !value)
+        return false;
+    const typed = value;
+    if (Array.isArray(typed.tool_calls) && typed.tool_calls.length > 0)
+        return true;
+    if (typeof typed.kwargs === "object" && typed.kwargs) {
+        return Array.isArray(typed.kwargs.tool_calls) && typed.kwargs.tool_calls.length > 0;
+    }
+    return false;
+}
+function extractAssistantTextFromMessages(messages) {
+    if (!Array.isArray(messages))
+        return "";
+    for (let index = messages.length - 1; index >= 0; index -= 1) {
+        const message = messages[index];
+        if (typeof message !== "object" || !message)
+            continue;
+        const typed = message;
+        const ids = Array.isArray(typed.id) ? typed.id.filter((item) => typeof item === "string") : [];
+        const typeName = ids.at(-1);
+        const runtimeType = typeof message._getType === "function"
+            ? message._getType()
+            : typeof message.getType === "function"
+                ? message.getType()
+                : undefined;
+        const kwargs = typeof typed.kwargs === "object" && typed.kwargs ? typed.kwargs : undefined;
+        if (typeName === "AIMessage" || runtimeType === "ai" || kwargs?.content !== undefined) {
+            if (hasToolCalls(message))
+                continue;
+            if (Array.isArray(kwargs?.tool_calls) && kwargs.tool_calls.length > 0)
+                continue;
+            const content = extractMessageContent(message);
+            if (content)
+                return content;
+        }
+    }
+    return "";
+}
+function extractStructuredOutputText(value) {
+    if (typeof value !== "object" || !value)
+        return "";
+    if (isLikelyMemoryWriteArgsObject(value))
+        return "";
+    const typed = value;
+    const fromMessages = extractAssistantTextFromMessages(typed.messages);
+    if (fromMessages)
+        return fromMessages;
+    if (typed.output && typeof typed.output === "object") {
+        const outputRecord = typed.output;
+        const nestedMessages = extractAssistantTextFromMessages(outputRecord.messages);
+        if (nestedMessages)
+            return nestedMessages;
+        const nestedContent = readTextContent(outputRecord.content);
+        if (nestedContent)
+            return nestedContent;
+    }
+    return readTextContent(typed.content);
+}
+export function extractToolFallbackContext(value) {
+    if (typeof value !== "object" || !value)
+        return "";
+    const typed = value;
+    const messages = extractToolMessageContents(typed.messages);
+    if (messages.length > 0)
+        return messages.slice(-3).join("\n\n");
+    if (typed.output && typeof typed.output === "object") {
+        const nested = extractToolFallbackContext(typed.output);
+        if (nested)
+            return nested;
+    }
+    return "";
+}
+export function extractVisibleOutput(value) {
+    const structured = extractStructuredOutputText(value);
+    if (structured)
+        return structured;
+    if (typeof value === "string") {
+        const parsed = tryParseJson(value);
+        if (parsed) {
+            if (isLikelyMemoryWriteArgsObject(parsed))
+                return "";
+            const parsedStructured = extractStructuredOutputText(parsed);
+            if (parsedStructured)
+                return parsedStructured;
+            if (isLikelyToolArgsObject(parsed))
+                return "";
+        }
+        return value;
+    }
+    if (typeof value === "object" && value) {
+        const typed = value;
+        if (typed.output !== undefined) {
+            const nested = extractVisibleOutput(typed.output);
+            if (nested)
+                return nested;
+        }
+        if (typed.content !== undefined) {
+            const nested = extractVisibleOutput(typed.content);
+            if (nested)
+                return nested;
+        }
+    }
+    return "";
+}
+function isAiMessageLike(value) {
+    if (typeof value !== "object" || !value)
+        return false;
+    const typed = value;
+    return typeof typed._getType === "function" && typed._getType() === "ai" && ("content" in typed || "tool_calls" in typed);
+}
+function normalizeAgentMessage(value) {
+    if (!AIMessage.isInstance(value) && !isAiMessageLike(value))
+        return value;
+    const typed = value;
+    const normalizedToolCalls = Array.isArray(typed.tool_calls)
+        ? typed.tool_calls.map((toolCall) => {
+            if (typeof toolCall !== "object" || !toolCall)
+                return toolCall;
+            const parsedArgs = salvageToolArgs(toolCall.args);
+            return parsedArgs ? { ...toolCall, args: normalizeKnownToolArgs(toolCall.name, parsedArgs) } : toolCall;
+        })
+        : [];
+    const normalizedInvalidToolCalls = Array.isArray(typed.invalid_tool_calls)
+        ? typed.invalid_tool_calls
+            .map((toolCall) => {
+            if (typeof toolCall !== "object" || !toolCall)
+                return null;
+            const parsedArgs = salvageToolArgs(toolCall.args);
+            if (!parsedArgs)
+                return toolCall;
+            return {
+                ...toolCall,
+                args: normalizeKnownToolArgs(toolCall.name, parsedArgs),
+                type: "tool_call",
+                error: undefined,
+            };
+        })
+            .filter((toolCall) => toolCall !== null)
+        : [];
+    const recoveredToolCalls = normalizedInvalidToolCalls.filter((toolCall) => typeof toolCall.args === "object" && !!toolCall.args && !Array.isArray(toolCall.args));
+    const normalizedContent = typeof typed.content === "string" || Array.isArray(typed.content)
+        ? typed.content
+        : typeof typed.content === "object" && typed.content
+            ? readTextContent(typed.content)
+            : "";
+    return new AIMessage({
+        content: normalizedContent,
+        name: typeof typed.name === "string" ? typed.name : undefined,
+        additional_kwargs: typeof typed.additional_kwargs === "object" && typed.additional_kwargs ? typed.additional_kwargs : {},
+        response_metadata: typeof typed.response_metadata === "object" && typed.response_metadata ? typed.response_metadata : {},
+        id: typeof typed.id === "string" ? typed.id : undefined,
+        tool_calls: [...normalizedToolCalls, ...recoveredToolCalls],
+        invalid_tool_calls: normalizedInvalidToolCalls.filter((toolCall) => toolCall.type !== "tool_call"),
+        usage_metadata: typeof typed.usage_metadata === "object" && typed.usage_metadata ? typed.usage_metadata : undefined,
+    });
+}
+export function isToolCallParseFailure(error) {
+    if (!(error instanceof Error))
+        return false;
+    return /error parsing tool call:/i.test(error.message);
+}
+export const STRICT_TOOL_JSON_INSTRUCTION = "When calling tools, return only the tool call itself. The arguments must be a pure JSON object with no explanatory text before or after it.";
+function appendStrictToolInstruction(input) {
+    if (Array.isArray(input)) {
+        return [...input, { role: "system", content: STRICT_TOOL_JSON_INSTRUCTION }];
+    }
+    if (typeof input === "object" && input && Array.isArray(input.messages)) {
+        return {
+            ...input,
+            messages: [...(input.messages), { role: "system", content: STRICT_TOOL_JSON_INSTRUCTION }],
+        };
+    }
+    return input;
+}
+export function wrapResolvedModel(value) {
+    if (typeof value !== "object" || value === null)
+        return value;
+    const target = value;
+    return new Proxy(target, {
+        get(currentTarget, prop, receiver) {
+            const member = Reflect.get(currentTarget, prop, receiver);
+            if (prop === "invoke" && typeof member === "function") {
+                return async (...args) => {
+                    try {
+                        return normalizeAgentMessage(await member.apply(currentTarget, args));
+                    }
+                    catch (error) {
+                        if (!isToolCallParseFailure(error)) {
+                            throw error;
+                        }
+                        const retryArgs = [...args];
+                        retryArgs[0] = appendStrictToolInstruction(retryArgs[0]);
+                        return normalizeAgentMessage(await member.apply(currentTarget, retryArgs));
+                    }
+                };
+            }
+            if ((prop === "bindTools" || prop === "withConfig" || prop === "withStructuredOutput") && typeof member === "function") {
+                return (...args) => wrapResolvedModel(member.apply(currentTarget, args));
+            }
+            if (typeof member === "function")
+                return member.bind(currentTarget);
+            return member;
+        },
+    });
+}
+export function extractReasoningText(value) {
+    if (typeof value !== "object" || !value)
+        return "";
+    const typed = value;
+    const chunk = typed.data?.chunk ?? value;
+    if (typeof chunk !== "object" || !chunk)
+        return "";
+    if ("additional_kwargs" in chunk && typeof chunk.additional_kwargs === "object") {
+        const kwargs = chunk.additional_kwargs;
+        return typeof kwargs?.reasoning === "string" ? kwargs.reasoning : "";
+    }
+    if ("kwargs" in chunk && typeof chunk.kwargs === "object") {
+        const kwargs = chunk.kwargs;
+        return typeof kwargs?.additional_kwargs?.reasoning === "string" ? kwargs.additional_kwargs.reasoning : "";
+    }
+    return "";
+}

package/dist/runtime/parsing/stream-event-parsing.d.ts

@@ -0,0 +1,27 @@
+export type RuntimeStreamChunk = {
+    kind: "content";
+    content: string;
+} | {
+    kind: "reasoning";
+    content: string;
+} | {
+    kind: "interrupt";
+    content: string;
+} | {
+    kind: "step";
+    content: string;
+} | {
+    kind: "tool-result";
+    toolName: string;
+    output: unknown;
+};
+export declare function extractTerminalStreamOutput(event: unknown): string;
+export declare function extractReasoningStreamOutput(event: unknown): string;
+export declare function extractAgentStep(event: unknown): string | null;
+export declare function extractToolResult(event: unknown): {
+    toolName: string;
+    output: unknown;
+} | null;
+export declare function extractInterruptPayload(event: unknown): string | null;
+export declare function normalizeTerminalOutputKey(value: string): string;
+export declare function readStreamDelta(chunk: unknown): string;