@botbotgo/agent-harness 0.0.95 → 0.0.97

package/dist/config/workflows/runtime-profiles.yaml

@@ -0,0 +1,94 @@
+# agent-harness feature: schema version for this declarative config object.
+apiVersion: agent-harness/v1alpha1
+# agent-harness feature: catalog of reusable runtime entry profiles layered on workflow resources.
+kind: RuntimeProfiles
+spec:
+  - id: coding-runtime
+    workflowRef: langgraph-workflow/coding-loop
+    defaults:
+      approvalPolicy: safe-default
+      memoryPolicy: project-facts-only
+      directAnswerFirst: false
+      watchGithubActionsAfterPush: true
+      allowPushToMaster: false
+      closeGithubIssueOnSuccess: false
+    requiredAgents:
+      - coderAgent
+    optionalAgents:
+      - verifierAgent
+  - id: personal-assistant
+    workflowRef: langgraph-workflow/assistant-loop
+    defaults:
+      approvalPolicy: human-before-side-effects
+      memoryPolicy: user-preferences-and-routines
+      directAnswerFirst: true
+      persistDurableMemory: true
+    optionalAgents:
+      - defaultResearchAgent
+      - defaultWritingAgent
+      - defaultSchedulingAgent
+      - defaultWorkerAgent
+  - id: research-runtime
+    workflowRef: langgraph-workflow/research-loop
+    defaults:
+      approvalPolicy: minimal
+      memoryPolicy: report-summary-only
+      requireSourceGrounding: true
+      requireCoverageReview: true
+    requiredAgents:
+      - gathererAgent
+      - analystAgent
+    optionalAgents:
+      - synthesizerAgent
+  - id: approval-review-runtime
+    workflowRef: langgraph-workflow/approval-review-loop
+    defaults:
+      approvalPolicy: always-required
+      memoryPolicy: none
+      executeAfterApproval: true
+      auditTrail: full
+    requiredAgents:
+      - preparerAgent
+    optionalAgents:
+      - reviewerAgent
+  - id: claw-style-assistant
+    workflowRef: langgraph-workflow/assistant-loop
+    defaults:
+      approvalPolicy: human-before-side-effects
+      memoryPolicy: user-preferences-and-stable-context
+      channelFirst: true
+      attachmentAware: true
+      sessionMemory: thread-scoped
+    optionalAgents:
+      - defaultWorkerAgent
+  - id: chat-operator
+    workflowRef: langgraph-workflow/chat-router-loop
+    defaults:
+      approvalPolicy: route-dependent
+      memoryPolicy: thread-only
+      directAnswerFirst: true
+    optionalAgents:
+      - codingAgent
+      - researchAgent
+      - assistantAgent
+      - approvalAgent
+  - id: copilot-sidecar
+    workflowRef: langgraph-workflow/coding-lite-loop
+    defaults:
+      approvalPolicy: no-push
+      memoryPolicy: repo-context-only
+      directAnswerFirst: false
+      allowRepositoryEdits: true
+      allowPushToMaster: false
+      runIntegrationVerification: false
+    requiredAgents:
+      - coderAgent
+  - id: task-delegation-hub
+    workflowRef: langgraph-workflow/delegation-loop
+    defaults:
+      approvalPolicy: worker-dependent
+      memoryPolicy: task-summary-only
+      routingStrategy: planner-first
+      reviewerEnabled: true
+    optionalAgents:
+      - defaultWorkerFallback

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 {};