@botbotgo/agent-harness 0.0.96 → 0.0.97

package/dist/api.d.ts

@@ -1,7 +1,7 @@
 import type { ApprovalRecord, CancelOptions, RunRecord, RunOptions, RunSummary, ResumeOptions, RuntimeHealthSnapshot, RuntimeAdapterOptions, ThreadSummary, ThreadRecord, WorkspaceLoadOptions } from "./contracts/types.js";
 import { AgentHarnessRuntime } from "./runtime/harness.js";
-import type { InventoryAgentRecord, InventorySkillRecord } from "./runtime/inventory.js";
-import type { RequirementAssessmentOptions } from "./runtime/skill-requirements.js";
+import type { InventoryAgentRecord, InventorySkillRecord } from "./runtime/harness/system/inventory.js";
+import type { RequirementAssessmentOptions } from "./runtime/harness/system/skill-requirements.js";
 import type { ToolMcpServerOptions } from "./mcp.js";
 export { AgentHarnessRuntime } from "./runtime/harness.js";
 type CreateAgentHarnessOptions = {
@@ -14,7 +14,7 @@ type CreateAgentHarnessOptions = {
 };
 export declare function createAgentHarness(): Promise<AgentHarnessRuntime>;
 export declare function createAgentHarness(workspaceRoot: string, options?: CreateAgentHarnessOptions): Promise<AgentHarnessRuntime>;
-export declare function run(runtime: AgentHarnessRuntime, options: RunOptions): Promise<import("./contracts/types.js").RunResult>;
+export declare function run(runtime: AgentHarnessRuntime, options: RunOptions): Promise<import("./contracts/runtime.js").RunResult>;
 export declare function subscribe(runtime: AgentHarnessRuntime, listener: Parameters<AgentHarnessRuntime["subscribe"]>[0]): () => void;
 export declare function listThreads(runtime: AgentHarnessRuntime, filter?: Parameters<AgentHarnessRuntime["listThreads"]>[0]): Promise<ThreadSummary[]>;
 export declare function listRuns(runtime: AgentHarnessRuntime, filter?: Parameters<AgentHarnessRuntime["listRuns"]>[0]): Promise<RunSummary[]>;
@@ -29,8 +29,8 @@ export declare function describeInventory(runtime: AgentHarnessRuntime, options?
     workspaceRoot: string;
     agents: InventoryAgentRecord[];
 };
-export declare function resolveApproval(runtime: AgentHarnessRuntime, options: ResumeOptions): Promise<import("./contracts/types.js").RunResult>;
-export declare function cancelRun(runtime: AgentHarnessRuntime, options: CancelOptions): Promise<import("./contracts/types.js").RunResult>;
+export declare function resolveApproval(runtime: AgentHarnessRuntime, options: ResumeOptions): Promise<import("./contracts/runtime.js").RunResult>;
+export declare function cancelRun(runtime: AgentHarnessRuntime, options: CancelOptions): Promise<import("./contracts/runtime.js").RunResult>;
 export declare function stop(runtime: AgentHarnessRuntime): Promise<void>;
 export declare function createToolMcpServer(runtime: AgentHarnessRuntime, options: ToolMcpServerOptions): Promise<import("@modelcontextprotocol/sdk/server/mcp.js").McpServer>;
 export declare function serveToolsOverStdio(runtime: AgentHarnessRuntime, options: ToolMcpServerOptions): Promise<import("@modelcontextprotocol/sdk/server/mcp.js").McpServer>;

package/dist/contracts/core.d.ts

@@ -0,0 +1,9 @@
+export type ExecutionMode = "deepagent" | "langchain-v1" | "langgraph";
+export declare const AUTO_AGENT_ID = "auto";
+export type RuntimeModelSlot = "routing" | "planning" | "execution" | "review" | "final";
+export type RuntimeModelRefMap = Partial<Record<RuntimeModelSlot, string>>;
+export type RuntimeCapabilities = {
+    delegation?: boolean;
+    memory?: boolean;
+};
+export type RunState = "queued" | "claimed" | "running" | "waiting_for_approval" | "resuming" | "cancelling" | "cancelled" | "completed" | "failed";

package/dist/contracts/core.js

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

package/dist/contracts/runtime.d.ts

@@ -0,0 +1,421 @@
+import type { RunState } from "./core.js";
+import type { CompiledAgentBinding, CompiledModel, CompiledTool, ParsedAgentObject, ParsedToolObject, WorkspaceBundle } from "./workspace.js";
+export type ThreadSummary = {
+    agentId: string;
+    threadId: string;
+    latestRunId: string;
+    createdAt: string;
+    updatedAt: string;
+    status: RunState;
+};
+export type SessionRecord = ThreadSummary;
+export type KnownHarnessEventType = "run.created" | "run.queued" | "run.dequeued" | "run.state.changed" | "run.reviewed" | "run.resumed" | "approval.requested" | "approval.resolved" | "artifact.created" | "output.delta" | "reasoning.delta" | "runtime.health.changed" | "runtime.synthetic_fallback";
+export type HarnessEventType = KnownHarnessEventType | (string & {});
+export type HarnessEvent = {
+    eventId: string;
+    eventType: HarnessEventType;
+    timestamp: string;
+    threadId: string;
+    runId: string;
+    sequence: number;
+    source: "runtime" | "policy" | "surface" | "worker";
+    payload: Record<string, unknown>;
+};
+export type HarnessEventListener = (event: HarnessEvent) => void | Promise<void>;
+export type HarnessEventProjection = {
+    name?: string;
+    shouldHandle?: (event: HarnessEvent) => boolean;
+    handleEvent: HarnessEventListener;
+};
+export type RuntimeEventSink = {
+    publish: (event: HarnessEvent) => void;
+    subscribe: (listener: HarnessEventListener) => () => void;
+    registerProjection: (projection: HarnessEventProjection) => () => void;
+};
+export type HealthStatus = "healthy" | "degraded" | "unhealthy";
+export type RuntimeHealthCheck = {
+    status: HealthStatus;
+    updatedAt: string;
+    reason?: string;
+};
+export type RuntimeHealthSymptom = {
+    code: string;
+    severity: "info" | "warn" | "error";
+    message: string;
+    firstSeenAt: string;
+    lastSeenAt: string;
+};
+export type RuntimeHealthSnapshot = {
+    status: HealthStatus;
+    updatedAt: string;
+    checks: {
+        runtime: RuntimeHealthCheck;
+        llm: RuntimeHealthCheck;
+        persistence: RuntimeHealthCheck;
+        capacity: RuntimeHealthCheck;
+        workload: RuntimeHealthCheck;
+    };
+    symptoms: RuntimeHealthSymptom[];
+    stats: {
+        activeRunSlots: number;
+        pendingRunSlots: number;
+        pendingApprovals: number;
+        stuckRuns: number;
+        checkpointBytes?: number;
+        runtimeDbBytes?: number;
+        artifactBytes?: number;
+        llmSuccessRate1m?: number;
+        llmP95LatencyMs1m?: number;
+    };
+};
+export type RunResult = {
+    threadId: string;
+    runId: string;
+    state: RunState;
+    output: string;
+    finalMessageText?: string;
+    outputContent?: unknown;
+    contentBlocks?: unknown[];
+    structuredResponse?: unknown;
+    interruptContent?: string;
+    agentId?: string;
+    approvalId?: string;
+    pendingActionId?: string;
+    delegationId?: string;
+    artifacts?: ArtifactRecord[];
+    metadata?: Record<string, unknown>;
+};
+export type NormalizedUpstreamEvent = {
+    kind: "text-delta";
+    source: "model" | "state";
+    text: string;
+    ns?: string[];
+    nodeName?: string;
+} | {
+    kind: "reasoning-delta";
+    text: string;
+    ns?: string[];
+    nodeName?: string;
+} | {
+    kind: "tool-start";
+    toolName: string;
+    input?: unknown;
+    ns?: string[];
+    nodeName?: string;
+} | {
+    kind: "tool-end";
+    toolName: string;
+    output?: unknown;
+    isError?: boolean;
+    ns?: string[];
+    nodeName?: string;
+} | {
+    kind: "agent-step";
+    label: string;
+    ns?: string[];
+    nodeName?: string;
+} | {
+    kind: "interrupt";
+    interrupt: unknown;
+    ns?: string[];
+    nodeName?: string;
+} | {
+    kind: "run-event";
+    eventName: string;
+    data?: Record<string, unknown>;
+    ns?: string[];
+    nodeName?: string;
+};
+export type CompatibleStreamPart = {
+    type: "messages";
+    ns: string[];
+    data: [unknown, Record<string, unknown>];
+} | {
+    type: "updates";
+    ns: string[];
+    data: Record<string, unknown>;
+} | {
+    type: "custom";
+    ns: string[];
+    data: unknown;
+};
+export type UpstreamRuntimeEvent = {
+    format: "langgraph-v2";
+    /** @deprecated Prefer streamPart plus raw/event/name/data/ns for upstream-aligned consumption. */
+    normalized: NormalizedUpstreamEvent;
+    streamPart: CompatibleStreamPart;
+    raw: unknown;
+    event?: string;
+    name?: string;
+    runType?: string;
+    data?: Record<string, unknown>;
+    metadata?: Record<string, unknown>;
+    tags?: string[];
+    ns?: string[];
+};
+export type RuntimeListeners = {
+    onEvent?: (event: HarnessEvent) => void | Promise<void>;
+};
+export type FrontendStreamListeners = {
+    onChunk?: (chunk: string) => void | Promise<void>;
+    onContentBlocks?: (blocks: unknown[]) => void | Promise<void>;
+    onUpstreamEvent?: (event: UpstreamRuntimeEvent) => void | Promise<void>;
+    onReasoning?: (chunk: string) => void | Promise<void>;
+    onStep?: (step: string) => void | Promise<void>;
+    onToolResult?: (item: {
+        toolName: string;
+        output: unknown;
+        isError?: boolean;
+    }) => void | Promise<void>;
+};
+export type RunListeners = RuntimeListeners & FrontendStreamListeners;
+export type MessageContentPart = {
+    type: "text";
+    text: string;
+} | {
+    type: "image_url";
+    image_url: string;
+};
+export type MessageContent = string | MessageContentPart[];
+export type InvocationEnvelope = {
+    context?: Record<string, unknown>;
+    inputs?: Record<string, unknown>;
+    attachments?: Record<string, unknown>;
+    capabilities?: Record<string, unknown>;
+};
+export type RunStartOptions = {
+    agentId?: string;
+    input: MessageContent;
+    threadId?: string;
+    priority?: number;
+    invocation?: InvocationEnvelope;
+    listeners?: RunListeners;
+    runtimeListeners?: RuntimeListeners;
+    frontendListeners?: FrontendStreamListeners;
+};
+export type RunDecisionOptions = {
+    threadId: string;
+    runId?: string;
+    approvalId?: string;
+    decision: "approve" | "edit" | "reject";
+    editedInput?: Record<string, unknown>;
+    listeners?: RunListeners;
+    runtimeListeners?: RuntimeListeners;
+    frontendListeners?: FrontendStreamListeners;
+};
+export type RunOptions = RunStartOptions | RunDecisionOptions;
+export type HarnessStreamItem = {
+    type: "event";
+    event: HarnessEvent;
+} | {
+    type: "upstream-event";
+    threadId: string;
+    runId: string;
+    agentId: string;
+    event: UpstreamRuntimeEvent;
+} | {
+    type: "result";
+    result: RunResult;
+} | {
+    type: "content";
+    threadId: string;
+    runId: string;
+    agentId: string;
+    content: string;
+} | {
+    type: "content-blocks";
+    threadId: string;
+    runId: string;
+    agentId: string;
+    contentBlocks: unknown[];
+} | {
+    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;
+    isError?: boolean;
+};
+export type TranscriptMessage = {
+    role: "user" | "assistant";
+    content: MessageContent;
+    runId: string;
+    createdAt: string;
+};
+export type ThreadRunRecord = {
+    runId: string;
+    threadId: string;
+    agentId: string;
+    executionMode: string;
+    adapterKind?: string;
+    createdAt: string;
+    updatedAt: string;
+    state: RunState;
+    checkpointRef: string | null;
+    resumable: boolean;
+};
+export type RunSummary = ThreadRunRecord;
+export type RunRecord = RunSummary;
+export type ThreadRecord = {
+    threadId: string;
+    entryAgentId: string;
+    currentState: RunState;
+    latestRunId: string;
+    createdAt: string;
+    updatedAt: string;
+    messages: TranscriptMessage[];
+    runs: ThreadRunRecord[];
+    pendingDecision?: {
+        approvalId: string;
+        pendingActionId: string;
+        toolName: string;
+        allowedDecisions: Array<"approve" | "edit" | "reject">;
+        requestedAt: string;
+    };
+};
+export type ResumeOptions = {
+    threadId?: string;
+    runId?: string;
+    approvalId?: string;
+    decision?: "approve" | "edit" | "reject";
+    editedInput?: Record<string, unknown>;
+};
+export type CancelOptions = {
+    runId: string;
+    reason?: string;
+};
+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;
+    toolName: string;
+    status: "pending" | "approved" | "edited" | "rejected" | "expired";
+    requestedAt: string;
+    resolvedAt: string | null;
+    allowedDecisions: Array<"approve" | "edit" | "reject">;
+    inputPreview: Record<string, unknown>;
+};
+export type InternalApprovalRecord = ApprovalRecord & {
+    toolCallId: string;
+    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 RuntimeDeclaredMiddlewareResolver = (input: {
+    kind: string;
+    config: Record<string, unknown>;
+    binding?: CompiledAgentBinding;
+    resolveModel: (model: CompiledModel) => Promise<unknown>;
+}) => unknown | unknown[] | null | undefined | Promise<unknown | unknown[] | null | undefined>;
+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;
+    declaredMiddlewareResolver?: RuntimeDeclaredMiddlewareResolver;
+    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: HarnessEventListener;
+};
+export type RuntimeInventoryContext = {
+    workspace: WorkspaceBundle;
+};

package/dist/contracts/runtime.js

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