@botbotgo/agent-harness 0.0.1

package/dist/contracts/types.d.ts

@@ -0,0 +1,359 @@
+export type ExecutionMode = "deepagent" | "langchain-v1";
+export declare const AUTO_AGENT_ID = "auto";
+export type RunState = "running" | "waiting_for_approval" | "resuming" | "completed" | "failed";
+export type ParsedAgentObject = {
+    id: string;
+    executionMode: ExecutionMode;
+    description: string;
+    modelRef: string;
+    runRoot?: string;
+    toolRefs: string[];
+    skillPathRefs: string[];
+    memorySources: string[];
+    subagentRefs: string[];
+    subagentPathRefs: string[];
+    langchainAgentConfig?: Record<string, unknown>;
+    deepAgentConfig?: Record<string, unknown>;
+    sourcePath: string;
+};
+export type WorkspaceObject = {
+    id: string;
+    kind: string;
+    sourcePath: string;
+    value: Record<string, unknown>;
+};
+export type ParsedModelObject = {
+    id: string;
+    provider: string;
+    model: string;
+    init: Record<string, unknown>;
+    clientRef?: string;
+    fallbacks: string[];
+    metadata?: Record<string, unknown>;
+    sourcePath: string;
+};
+export type ParsedEmbeddingModelObject = {
+    id: string;
+    provider: string;
+    model: string;
+    init: Record<string, unknown>;
+    clientRef?: string;
+    metadata?: Record<string, unknown>;
+    sourcePath: string;
+};
+export type ParsedVectorStoreObject = {
+    id: string;
+    kind: string;
+    url?: string;
+    authToken?: string;
+    table?: string;
+    column?: string;
+    embeddingModelRef?: string;
+    metadata?: Record<string, unknown>;
+    sourcePath: string;
+};
+export type ParsedToolObject = {
+    id: string;
+    type: string;
+    name: string;
+    description: string;
+    config?: Record<string, unknown>;
+    inputSchemaRef?: string;
+    backendOperation?: string;
+    mcpRef?: string;
+    bundleRefs: string[];
+    hitl?: {
+        enabled: boolean;
+        allow?: Array<"approve" | "edit" | "reject">;
+    };
+    sourcePath: string;
+};
+export type LangChainAgentParams = {
+    model: CompiledModel;
+    tools: CompiledTool[];
+    systemPrompt?: string;
+    description: string;
+};
+export type CompiledSubAgent = {
+    name: string;
+    description: string;
+    systemPrompt: string;
+    tools?: CompiledTool[];
+    model?: CompiledModel;
+    interruptOn?: Record<string, boolean | object>;
+    skills?: string[];
+    memory?: string[];
+};
+export type DeepAgentParams = {
+    model: CompiledModel;
+    tools: CompiledTool[];
+    systemPrompt?: string;
+    description: string;
+    subagents: CompiledSubAgent[];
+    interruptOn?: Record<string, boolean | object>;
+    backend?: Record<string, unknown>;
+    store?: Record<string, unknown>;
+    name: string;
+    memory: string[];
+    skills: string[];
+};
+export type CompiledModel = {
+    id: string;
+    provider: string;
+    model: string;
+    init: Record<string, unknown>;
+    clientRef?: string;
+    fallbacks: string[];
+    runtimeValue: string;
+};
+export type CompiledEmbeddingModel = {
+    id: string;
+    provider: string;
+    model: string;
+    init: Record<string, unknown>;
+    clientRef?: string;
+    runtimeValue: string;
+};
+export type CompiledVectorStore = {
+    id: string;
+    kind: string;
+    url?: string;
+    authToken?: string;
+    table?: string;
+    column?: string;
+    embeddingModelRef?: string;
+    runtimeValue: string;
+};
+export type CompiledTool = {
+    id: string;
+    type: string;
+    name: string;
+    description: string;
+    config?: Record<string, unknown>;
+    inputSchemaRef?: string;
+    backendOperation?: string;
+    mcpRef?: string;
+    bundleRefs: string[];
+    hitl?: {
+        enabled: boolean;
+        allow: Array<"approve" | "edit" | "reject">;
+    };
+    runtimeValue: {
+        name: string;
+        description: string;
+        type: string;
+    };
+};
+export type CompiledAgentBinding = {
+    agent: ParsedAgentObject;
+    langchainAgentParams?: LangChainAgentParams;
+    directAgentParams?: LangChainAgentParams;
+    deepAgentParams?: DeepAgentParams;
+    harnessRuntime: {
+        runRoot: string;
+        hostFacing: boolean;
+        checkpointer?: Record<string, unknown>;
+        store?: Record<string, unknown>;
+    };
+};
+export type WorkspaceBundle = {
+    workspaceRoot: string;
+    builtinSources: string[];
+    refs: Map<string, WorkspaceObject | ParsedAgentObject>;
+    models: Map<string, ParsedModelObject>;
+    embeddings: Map<string, ParsedEmbeddingModelObject>;
+    vectorStores: Map<string, ParsedVectorStoreObject>;
+    tools: Map<string, ParsedToolObject>;
+    agents: Map<string, ParsedAgentObject>;
+    bindings: Map<string, CompiledAgentBinding>;
+};
+export type WorkspaceLoadOptions = {
+    overlayRoots?: string[];
+    builtinSources?: string[];
+};
+export type SessionRecord = {
+    agentId: string;
+    threadId: string;
+    latestRunId: string;
+    createdAt: string;
+    updatedAt: string;
+    status: RunState;
+};
+export type HarnessEvent = {
+    eventId: string;
+    eventType: string;
+    timestamp: string;
+    threadId: string;
+    runId: string;
+    sequence: number;
+    source: "runtime" | "policy" | "surface" | "worker";
+    payload: Record<string, unknown>;
+};
+export type RunResult = {
+    threadId: string;
+    runId: string;
+    state: RunState;
+    output: string;
+    interruptContent?: string;
+    agentId?: string;
+    approvalId?: string;
+    pendingActionId?: string;
+    delegationId?: string;
+};
+export type RunOptions = {
+    agentId?: string;
+    input: string;
+    threadId?: string;
+};
+export type HarnessStreamItem = {
+    type: "event";
+    event: HarnessEvent;
+} | {
+    type: "content";
+    threadId: string;
+    runId: string;
+    agentId: string;
+    content: string;
+} | {
+    type: "reasoning";
+    threadId: string;
+    runId: string;
+    agentId: string;
+    content: string;
+} | {
+    type: "step";
+    threadId: string;
+    runId: string;
+    agentId: string;
+    content: string;
+} | {
+    type: "tool-result";
+    threadId: string;
+    runId: string;
+    agentId: string;
+    toolName: string;
+    output: unknown;
+};
+export type TranscriptMessage = {
+    role: "user" | "assistant";
+    content: string;
+    runId: string;
+    createdAt: string;
+};
+export type ResumeOptions = {
+    threadId?: string;
+    runId?: string;
+    approvalId?: string;
+    decision?: "approve" | "edit" | "reject";
+    editedInput?: Record<string, unknown>;
+};
+export type RestartConversationOptions = {
+    threadId: string;
+    mode: "restart-in-thread" | "restart-new-thread";
+    input: string;
+};
+export type ApprovalRecord = {
+    approvalId: string;
+    pendingActionId: string;
+    threadId: string;
+    runId: string;
+    toolCallId: string;
+    toolName: string;
+    status: "pending" | "approved" | "edited" | "rejected" | "expired";
+    requestedAt: string;
+    resolvedAt: string | null;
+    allowedDecisions: Array<"approve" | "edit" | "reject">;
+    inputPreview: Record<string, unknown>;
+    checkpointRef: string;
+    eventRefs: string[];
+};
+export type DelegationRecord = {
+    delegationId: string;
+    threadId: string;
+    runId: string;
+    parentRunId: string;
+    specialistAgentId: string;
+    specialistName: string;
+    specialistDescription: string;
+    status: "requested" | "running" | "completed" | "failed" | "cancelled" | "resumable";
+    requestedAt: string;
+    startedAt: string | null;
+    completedAt: string | null;
+    checkpointRef: string | null;
+    inputArtifactRef: string | null;
+    outputArtifactRef: string | null;
+    eventRefs: string[];
+};
+export type ArtifactRecord = {
+    artifactId: string;
+    kind: string;
+    path: string;
+    createdAt: string;
+};
+export type ArtifactListing = {
+    threadId: string;
+    runId: string;
+    items: ArtifactRecord[];
+};
+export type RuntimeToolResolver = (toolIds: string[], binding?: CompiledAgentBinding) => unknown[];
+export type RuntimeModelResolver = (modelId: string) => unknown;
+export type RuntimeEmbeddingModelResolver = (embeddingModelId: string) => unknown;
+export type RuntimeVectorStoreResolver = (vectorStoreId: string) => unknown;
+export type RuntimeMiddlewareResolver = (binding: CompiledAgentBinding) => unknown[];
+export type RuntimeCheckpointerResolver = (binding: CompiledAgentBinding) => unknown;
+export type RuntimeStoreResolver = (binding: CompiledAgentBinding) => unknown;
+export type RuntimeBackendResolver = (binding: CompiledAgentBinding) => unknown;
+export type RuntimeAdapterOptions = {
+    toolResolver?: RuntimeToolResolver;
+    modelResolver?: RuntimeModelResolver;
+    embeddingModelResolver?: RuntimeEmbeddingModelResolver;
+    vectorStoreResolver?: RuntimeVectorStoreResolver;
+    middlewareResolver?: RuntimeMiddlewareResolver;
+    checkpointerResolver?: RuntimeCheckpointerResolver;
+    storeResolver?: RuntimeStoreResolver;
+    backendResolver?: RuntimeBackendResolver;
+};
+export type ToolKindAdapter = {
+    type: string;
+    validate: (tool: ParsedToolObject, tools: Map<string, ParsedToolObject>) => void;
+    compile: (tool: ParsedToolObject, tools: Map<string, ParsedToolObject>) => CompiledTool[];
+};
+export type SkillSourceResolver = {
+    kind: string;
+    resolve: (input: {
+        workspaceRoot: string;
+        skill: {
+            sourcePathRef: string;
+        };
+        packagingRoots: string[];
+    }) => string[];
+};
+export type SkillInheritancePolicy = {
+    kind: string;
+    apply: (input: {
+        agent: ParsedAgentObject;
+        ownSkills: string[];
+        parentSkills: string[];
+    }) => string[];
+};
+export type SkillPackagingConvention = {
+    kind: string;
+    resolve: (input: {
+        workspaceRoot: string;
+        skill: {
+            sourcePathRef: string;
+        };
+    }) => string[];
+};
+export type PolicyDecision = {
+    allowed: boolean;
+    reasons: string[];
+};
+export type PolicyEvaluator = {
+    kind: string;
+    evaluate: (binding: CompiledAgentBinding) => PolicyDecision | null;
+};
+export type EventSubscriber = {
+    kind: string;
+    onEvent: (event: HarnessEvent) => void | Promise<void>;
+};

package/dist/contracts/types.js

@@ -0,0 +1 @@
+export const AUTO_AGENT_ID = "auto";

package/dist/extensions.d.ts

@@ -0,0 +1,16 @@
+import type { CompiledTool, EventSubscriber, ParsedToolObject, PolicyEvaluator, SkillInheritancePolicy, SkillPackagingConvention, SkillSourceResolver, ToolKindAdapter } from "./contracts/types.js";
+export declare function resolveToolTargets(tools: Map<string, ParsedToolObject>, ref: string): ParsedToolObject[];
+export declare function registerToolKind(adapter: ToolKindAdapter): void;
+export declare function getToolKindAdapter(type: string): ToolKindAdapter | undefined;
+export declare function registerSkillSourceResolver(resolver: SkillSourceResolver): void;
+export declare function getSkillSourceResolver(kind: string): SkillSourceResolver | undefined;
+export declare function registerSkillInheritancePolicy(policy: SkillInheritancePolicy): void;
+export declare function getSkillInheritancePolicy(kind: string): SkillInheritancePolicy | undefined;
+export declare function registerSkillPackagingConvention(convention: SkillPackagingConvention): void;
+export declare function getSkillPackagingConvention(kind: string): SkillPackagingConvention | undefined;
+export declare function registerPolicyEvaluator(evaluator: PolicyEvaluator): void;
+export declare function getPolicyEvaluators(): PolicyEvaluator[];
+export declare function registerEventSubscriber(subscriber: EventSubscriber): void;
+export declare function getEventSubscribers(): EventSubscriber[];
+export declare function compileToolWithRegistry(tool: ParsedToolObject, tools: Map<string, ParsedToolObject>): CompiledTool[];
+export declare function validateToolWithRegistry(tool: ParsedToolObject, tools: Map<string, ParsedToolObject>): void;

package/dist/extensions.js

@@ -0,0 +1,251 @@
+import path from "node:path";
+import { builtinSkillsRoot } from "./vendor/builtins.js";
+import { isExternalSourceLocator, resolveExternalSourcePath } from "./vendor/sources.js";
+const toolKindAdapters = new Map();
+const skillSourceResolvers = new Map();
+const skillInheritancePolicies = new Map();
+const skillPackagingConventions = new Map();
+const policyEvaluators = new Map();
+const eventSubscribers = new Map();
+function resolveToolRefId(ref) {
+    if (isExternalSourceLocator(ref)) {
+        return ref;
+    }
+    if (ref.startsWith("builtin/")) {
+        return ref;
+    }
+    return ref.split("/").slice(1).join("/");
+}
+export function resolveToolTargets(tools, ref) {
+    const resolved = resolveToolRefId(ref);
+    if (resolved === "builtin/*") {
+        return Array.from(tools.entries())
+            .filter(([id]) => id.startsWith("builtin/"))
+            .map(([, tool]) => tool);
+    }
+    const exact = tools.get(resolved);
+    if (exact) {
+        return [exact];
+    }
+    if (!resolved.startsWith("builtin/")) {
+        return [];
+    }
+    const prefix = `${resolved}/`;
+    return Array.from(tools.entries())
+        .filter(([id]) => id.startsWith(prefix))
+        .map(([, tool]) => tool);
+}
+export function registerToolKind(adapter) {
+    toolKindAdapters.set(adapter.type, adapter);
+}
+export function getToolKindAdapter(type) {
+    return toolKindAdapters.get(type);
+}
+export function registerSkillSourceResolver(resolver) {
+    skillSourceResolvers.set(resolver.kind, resolver);
+}
+export function getSkillSourceResolver(kind) {
+    return skillSourceResolvers.get(kind);
+}
+export function registerSkillInheritancePolicy(policy) {
+    skillInheritancePolicies.set(policy.kind, policy);
+}
+export function getSkillInheritancePolicy(kind) {
+    return skillInheritancePolicies.get(kind);
+}
+export function registerSkillPackagingConvention(convention) {
+    skillPackagingConventions.set(convention.kind, convention);
+}
+export function getSkillPackagingConvention(kind) {
+    return skillPackagingConventions.get(kind);
+}
+export function registerPolicyEvaluator(evaluator) {
+    policyEvaluators.set(evaluator.kind, evaluator);
+}
+export function getPolicyEvaluators() {
+    return Array.from(policyEvaluators.values());
+}
+export function registerEventSubscriber(subscriber) {
+    eventSubscribers.set(subscriber.kind, subscriber);
+}
+export function getEventSubscribers() {
+    return Array.from(eventSubscribers.values());
+}
+function compileBundleTool(tool, tools) {
+    const compiled = tool.bundleRefs.flatMap((ref) => {
+        const nested = resolveToolTargets(tools, ref);
+        if (nested.length === 0) {
+            throw new Error(`Tool bundle target ${ref} not found`);
+        }
+        return nested.flatMap((item) => compileToolWithRegistry(item, tools));
+    });
+    const deduped = new Map();
+    for (const item of compiled) {
+        deduped.set(item.name, item);
+    }
+    return Array.from(deduped.values());
+}
+export function compileToolWithRegistry(tool, tools) {
+    const adapter = getToolKindAdapter(tool.type);
+    if (!adapter) {
+        throw new Error(`No tool kind adapter registered for ${tool.type}`);
+    }
+    return adapter.compile(tool, tools);
+}
+export function validateToolWithRegistry(tool, tools) {
+    const adapter = getToolKindAdapter(tool.type);
+    if (!adapter) {
+        throw new Error(`No tool kind adapter registered for ${tool.type}`);
+    }
+    adapter.validate(tool, tools);
+}
+registerToolKind({
+    type: "function",
+    validate(tool) {
+        if (!tool.name) {
+            throw new Error(`Tool ${tool.id} name must not be empty`);
+        }
+        if (!tool.description) {
+            throw new Error(`Tool ${tool.id} description must not be empty`);
+        }
+    },
+    compile(tool) {
+        return [
+            {
+                id: tool.id,
+                type: "function",
+                name: tool.name,
+                description: tool.description,
+                config: tool.config,
+                inputSchemaRef: tool.inputSchemaRef,
+                bundleRefs: [],
+                hitl: tool.hitl
+                    ? {
+                        enabled: tool.hitl.enabled,
+                        allow: tool.hitl.allow ?? ["approve", "edit", "reject"],
+                    }
+                    : undefined,
+                runtimeValue: { name: tool.name, description: tool.description, type: "function" },
+            },
+        ];
+    },
+});
+registerToolKind({
+    type: "backend",
+    validate(tool) {
+        if (!tool.name || !tool.description) {
+            throw new Error(`Tool ${tool.id} backend tool requires name and description`);
+        }
+        if (!tool.backendOperation) {
+            throw new Error(`Tool ${tool.id} backend tool must define operation`);
+        }
+    },
+    compile(tool) {
+        return [
+            {
+                id: tool.id,
+                type: "backend",
+                name: tool.name,
+                description: tool.description,
+                config: tool.config,
+                inputSchemaRef: tool.inputSchemaRef,
+                backendOperation: tool.backendOperation,
+                bundleRefs: [],
+                hitl: tool.hitl
+                    ? {
+                        enabled: tool.hitl.enabled,
+                        allow: tool.hitl.allow ?? ["approve", "edit", "reject"],
+                    }
+                    : undefined,
+                runtimeValue: { name: tool.name, description: tool.description, type: "backend" },
+            },
+        ];
+    },
+});
+registerToolKind({
+    type: "mcp",
+    validate(tool) {
+        if (!tool.name || !tool.description) {
+            throw new Error(`Tool ${tool.id} mcp tool requires name and description`);
+        }
+        if (!tool.mcpRef) {
+            throw new Error(`Tool ${tool.id} mcp tool must define mcp.ref`);
+        }
+    },
+    compile(tool) {
+        return [
+            {
+                id: tool.id,
+                type: "mcp",
+                name: tool.name,
+                description: tool.description,
+                config: tool.config,
+                inputSchemaRef: tool.inputSchemaRef,
+                mcpRef: tool.mcpRef,
+                bundleRefs: [],
+                hitl: tool.hitl
+                    ? {
+                        enabled: tool.hitl.enabled,
+                        allow: tool.hitl.allow ?? ["approve", "edit", "reject"],
+                    }
+                    : undefined,
+                runtimeValue: { name: tool.name, description: tool.description, type: "mcp" },
+            },
+        ];
+    },
+});
+registerToolKind({
+    type: "bundle",
+    validate(tool, tools) {
+        if (tool.bundleRefs.length === 0) {
+            throw new Error(`Tool ${tool.id} bundle must contain nested refs`);
+        }
+        for (const ref of tool.bundleRefs) {
+            const target = resolveToolTargets(tools, ref);
+            if (target.length === 0) {
+                throw new Error(`Tool ${tool.id} bundle ref ${ref} does not exist`);
+            }
+        }
+    },
+    compile: compileBundleTool,
+});
+registerSkillSourceResolver({
+    kind: "path",
+    resolve({ workspaceRoot, skill, packagingRoots }) {
+        if (packagingRoots.length > 0) {
+            return packagingRoots;
+        }
+        const candidate = String(skill.sourcePathRef);
+        if (isExternalSourceLocator(candidate)) {
+            return [resolveExternalSourcePath(candidate, workspaceRoot)];
+        }
+        return [candidate.startsWith("/") ? candidate : `${workspaceRoot}/${candidate}`];
+    },
+});
+registerSkillSourceResolver({
+    kind: "builtin",
+    resolve({ skill }) {
+        return [path.join(builtinSkillsRoot(), skill.sourcePathRef)];
+    },
+});
+registerSkillInheritancePolicy({
+    kind: "default",
+    apply({ agent, ownSkills, parentSkills }) {
+        const systemPrompt = agent.deepAgentConfig?.systemPrompt;
+        const hasSystemPrompt = typeof systemPrompt === "string" && systemPrompt.trim().length > 0;
+        if (hasSystemPrompt && agent.id.includes(".")) {
+            return ownSkills;
+        }
+        return Array.from(new Set([...parentSkills, ...ownSkills]));
+    },
+});
+registerSkillPackagingConvention({
+    kind: "path",
+    resolve({ workspaceRoot, skill }) {
+        const candidate = String(skill.sourcePathRef);
+        if (isExternalSourceLocator(candidate)) {
+            return [resolveExternalSourcePath(candidate, workspaceRoot)];
+        }
+        return [candidate.startsWith("/") ? candidate : `${workspaceRoot}/${candidate}`];
+    },
+});

package/dist/index.d.ts

@@ -0,0 +1,7 @@
+export * from "./contracts/types.js";
+export * from "./extensions.js";
+export * from "./api.js";
+export * from "./presentation.js";
+export * from "./runtime/index.js";
+export * from "./workspace/index.js";
+export { createBuiltinBackendResolver, createBuiltinToolResolver } from "./vendor/builtins.js";

package/dist/index.js

@@ -0,0 +1,7 @@
+export * from "./contracts/types.js";
+export * from "./extensions.js";
+export * from "./api.js";
+export * from "./presentation.js";
+export * from "./runtime/index.js";
+export * from "./workspace/index.js";
+export { createBuiltinBackendResolver, createBuiltinToolResolver } from "./vendor/builtins.js";

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

@@ -0,0 +1,39 @@
+import type { ApprovalRecord, ArtifactListing, ArtifactRecord, DelegationRecord, HarnessEvent, RunState, SessionRecord, TranscriptMessage } from "../contracts/types.js";
+export declare class FilePersistence {
+    private readonly runRoot;
+    constructor(runRoot: string);
+    initialize(): Promise<void>;
+    threadDir(threadId: string): string;
+    runDir(threadId: string, runId: string): string;
+    createThread(input: {
+        threadId: string;
+        agentId: string;
+        runId: string;
+        status: RunState;
+        createdAt: string;
+    }): Promise<void>;
+    createRun(input: {
+        threadId: string;
+        runId: string;
+        agentId: string;
+        executionMode: string;
+        createdAt: string;
+    }): Promise<void>;
+    setRunState(threadId: string, runId: string, state: RunState, checkpointRef?: string | null): Promise<void>;
+    appendEvent(event: HarnessEvent): Promise<void>;
+    listSessions(): Promise<SessionRecord[]>;
+    getSession(threadId: string): Promise<SessionRecord | null>;
+    listRunEvents(threadId: string, runId: string): Promise<HarnessEvent[]>;
+    listApprovals(): Promise<ApprovalRecord[]>;
+    getApproval(approvalId: string): Promise<ApprovalRecord | null>;
+    getRunApprovals(threadId: string, runId: string): Promise<ApprovalRecord[]>;
+    listDelegations(): Promise<DelegationRecord[]>;
+    createApproval(record: ApprovalRecord): Promise<void>;
+    resolveApproval(threadId: string, runId: string, approvalId: string, status: ApprovalRecord["status"]): Promise<ApprovalRecord>;
+    createDelegation(record: DelegationRecord): Promise<void>;
+    updateDelegation(threadId: string, runId: string, delegationId: string, patch: Partial<DelegationRecord>): Promise<DelegationRecord>;
+    createArtifact(threadId: string, runId: string, artifact: ArtifactRecord, content: unknown): Promise<ArtifactRecord>;
+    listArtifacts(threadId: string, runId: string): Promise<ArtifactListing>;
+    appendThreadMessage(threadId: string, message: TranscriptMessage): Promise<void>;
+    listThreadMessages(threadId: string, limit?: number): Promise<TranscriptMessage[]>;
+}