@botbotgo/agent-harness 0.0.309 → 0.0.311

package/dist/contracts/runtime-observability.d.ts

@@ -0,0 +1,248 @@
+import type { RequestState } from "./core.js";
+export type SessionSummary = {
+    agentId: string;
+    sessionId: string;
+    latestRequestId: string;
+    createdAt: string;
+    updatedAt: string;
+    status: RequestState;
+    currentAgentId?: string;
+};
+export type SessionListSummary = SessionSummary & {
+    entryAgentId: string;
+    messageCount: number;
+    hasVisibleMessages: boolean;
+    lastMessageRole?: import("./runtime-requests.js").TranscriptMessage["role"];
+    title?: string;
+    snippet?: string;
+};
+export type KnownHarnessEventType = "request.created" | "request.queued" | "request.dequeued" | "request.state.changed" | "request.resumed" | "approval.requested" | "approval.resolved" | "artifact.created" | "output.delta" | "runtime.health.changed" | "runtime.synthetic_fallback";
+export type HarnessEventType = KnownHarnessEventType | (string & {});
+export type HarnessEvent = {
+    eventId: string;
+    eventType: HarnessEventType;
+    timestamp: string;
+    sessionId: string;
+    requestId: 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 RuntimeTimelineItem = {
+    eventId: string;
+    sessionId: string;
+    requestId: string;
+    eventType: HarnessEventType;
+    timestamp: string;
+    sequence: number;
+    source: HarnessEvent["source"];
+    kind: "request" | "queue" | "approval" | "recovery" | "artifact" | "other";
+    payload: Record<string, unknown>;
+};
+export type RuntimeTimelineProjectionOptions = {
+    sessionId?: string;
+    requestId?: string;
+};
+export type RuntimeHistoryItem = {
+    type: "thinking";
+    text: string;
+} | {
+    type: "step";
+    step: string;
+    category: "llm" | "tool" | "skill" | "memory" | "chain" | "approval";
+    status: "started" | "completed" | "failed";
+    key: string;
+} | {
+    type: "tool-result";
+    toolName: string;
+    output: unknown;
+    isError?: boolean;
+    key: string;
+};
+export type RuntimeSurfaceKind = "agent" | "llm" | "memory" | "skill" | "tool";
+export type RuntimeSurfaceItem = {
+    kind: RuntimeSurfaceKind;
+    id: string;
+    name: string;
+    action: string;
+    status: "started" | "completed" | "failed";
+    agentId?: string;
+    agentName?: string;
+    ownerAgentId?: string;
+    ownerAgentName?: string;
+    sourceEventId?: string;
+    detail?: Record<string, unknown>;
+};
+export type AgentReference = {
+    id: string;
+    name: string;
+};
+export type HealthStatus = "healthy" | "degraded" | "unhealthy";
+export type RuntimeQueueDiagnostics = {
+    status: HealthStatus;
+    activeRequestSlots: number;
+    pendingRequestSlots: number;
+    stuckRequests: number;
+    queueEvents: RuntimeTimelineItem[];
+    summary: string;
+};
+export type RuntimeGovernanceDiagnostics = {
+    runsWithGovernance: number;
+    highRiskTools: number;
+    approvalRequiredTools: number;
+    autoApprovedTools: number;
+    autoRejectedTools: number;
+    untrustedMcpTools: number;
+    crossTenantTools: number;
+    writeAccessMcpTools: number;
+    summary: string;
+};
+export type RuntimeOperatorOverview = {
+    updatedAt: string;
+    summary: string;
+    health: RuntimeHealthSnapshot;
+    queue: RuntimeQueueDiagnostics;
+    approvals: {
+        total: number;
+        items: import("./runtime-requests.js").ApprovalRecord[];
+    };
+    requests: {
+        total: number;
+        states: Partial<Record<RequestState, number>>;
+        items: import("./runtime-requests.js").RequestSummary[];
+    };
+    governance: RuntimeGovernanceDiagnostics;
+};
+export type RuntimeToolExecutionToolPolicy = {
+    toolId: string;
+    name: string;
+    retryable: boolean;
+    hasInputSchema: boolean;
+    requiresApproval: boolean;
+};
+export type RuntimeSnapshotModel = {
+    id: string;
+    provider: string;
+    model: string;
+    baseUrl?: string;
+};
+export type RuntimeSnapshotTool = {
+    name: string;
+    description: string;
+};
+export type RuntimeSnapshotSkill = {
+    name: string;
+    path: string;
+    description?: string;
+};
+export type RuntimeSnapshotTracing = {
+    enabled: boolean;
+    correlationId: string;
+    tags?: string[];
+    metadata?: Record<string, unknown>;
+};
+export type RuntimeGovernanceRiskLevel = "low" | "medium" | "high";
+export type RuntimeGovernanceDecisionMode = "none" | "manual" | "auto-approve" | "auto-reject" | "deny-and-continue";
+export type RuntimeGovernanceToolPolicy = {
+    toolName: string;
+    toolId: string;
+    toolType: string;
+    category: "local" | "backend" | "mcp" | "provider-native";
+    mcpServerRef?: string;
+    mcpTransport?: string;
+    mcpTrustTier?: "trusted" | "reviewed" | "untrusted";
+    mcpAccess?: "read-only" | "read-write";
+    tenantScope?: "workspace" | "project" | "tenant" | "cross-tenant";
+    approvalReason?: string;
+    promptInjectionRisk?: RuntimeGovernanceRiskLevel;
+    oauthScopes?: string[];
+    risk: RuntimeGovernanceRiskLevel;
+    requiresApproval: boolean;
+    approvalPolicy: "explicit-hitl" | "runtime-default" | "none";
+    decisionMode: RuntimeGovernanceDecisionMode;
+    hasInputSchema: boolean;
+    inputRiskHints: string[];
+};
+export type RuntimeGovernanceBundle = {
+    bundleId: string;
+    title: string;
+    summary: string;
+    toolPolicies: RuntimeGovernanceToolPolicy[];
+};
+export type RuntimeSnapshot = {
+    agentId: string;
+    model?: RuntimeSnapshotModel;
+    tools: RuntimeSnapshotTool[];
+    skills: RuntimeSnapshotSkill[];
+    memory: string[];
+    tracing?: RuntimeSnapshotTracing;
+    governance?: {
+        bundles: RuntimeGovernanceBundle[];
+    };
+};
+export type RuntimeToolExecutionPolicy = {
+    agentId: string;
+    invokeTimeoutMs?: number;
+    streamIdleTimeoutMs: number;
+    providerRetries: {
+        maxAttempts: number;
+        backoffMs: number;
+        retryableMessages: string[];
+    };
+    validation: {
+        schemaBoundToolCount: number;
+        allToolsHaveSchemas: boolean;
+    };
+    idempotencyHints: {
+        replayEligible: boolean;
+        retryableToolCount: number;
+        nonRetryableToolCount: number;
+    };
+    tools: RuntimeToolExecutionToolPolicy[];
+};
+export type RuntimeEventSink = {
+    publish: (event: HarnessEvent) => void;
+    subscribe: (listener: HarnessEventListener) => () => void;
+    registerProjection: (projection: HarnessEventProjection) => () => void;
+};
+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: {
+        activeRequestSlots: number;
+        pendingRequestSlots: number;
+        pendingApprovals: number;
+        stuckRequests: number;
+        checkpointBytes?: number;
+        runtimeDbBytes?: number;
+        artifactBytes?: number;
+        llmSuccessRate1m?: number;
+        llmP95LatencyMs1m?: number;
+    };
+};

package/dist/contracts/runtime-observability.js

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

package/dist/contracts/runtime-requests.d.ts

@@ -0,0 +1,342 @@
+import type { RequestState } from "./core.js";
+import type { HarnessEvent, RuntimeGovernanceBundle, RuntimeSnapshot, RuntimeSurfaceItem, RuntimeSurfaceKind, RuntimeTimelineItem } from "./runtime-observability.js";
+export type RequestResult = {
+    sessionId: string;
+    requestId: string;
+    state: RequestState;
+    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 UpstreamRuntimeEvent = unknown;
+export type UpstreamRuntimeEventItem = {
+    sessionId: string;
+    requestId: string;
+    surfaceItem: RuntimeSurfaceItem;
+    event: UpstreamRuntimeEvent;
+};
+export type RuntimeListeners = {
+    onEvent?: (event: HarnessEvent) => void | Promise<void>;
+    onUpstreamEvent?: (event: UpstreamRuntimeEvent) => void | Promise<void>;
+    onTraceItem?: (item: UpstreamRuntimeEventItem) => void | Promise<void>;
+    onPlanState?: (planState: RequestPlanState) => void | Promise<void>;
+};
+export type RequestExecutionStepKind = RuntimeSurfaceKind | "approval";
+export type RequestExecutionStep = {
+    id: string;
+    kind: RequestExecutionStepKind;
+    name: string;
+    action: string;
+    status: "started" | "completed" | "failed";
+    occurredAt?: string;
+    startedAt?: string;
+    endedAt?: string;
+    agentId?: string;
+    agentName?: string;
+    ownerAgentId?: string;
+    ownerAgentName?: string;
+    sourceEventId?: string;
+    detail?: Record<string, unknown>;
+    output?: unknown;
+    isError?: boolean;
+};
+export type RequestPlanItemStatus = "pending" | "in_progress" | "completed" | "failed" | "cancelled" | "blocked" | (string & {});
+export type RequestPlanItem = {
+    id?: string;
+    content: string;
+    status: RequestPlanItemStatus;
+    ownerAgentId?: string;
+    startedAt?: string;
+    endedAt?: string;
+    result?: unknown;
+    metadata?: Record<string, unknown>;
+};
+export type RequestPlanSummary = {
+    total: number;
+    pending: number;
+    inProgress: number;
+    completed: number;
+    failed: number;
+    cancelled: number;
+    blocked: number;
+};
+export type RequestPlanState = {
+    sessionId: string;
+    requestId: string;
+    version: number;
+    updatedAt: string;
+    items: RequestPlanItem[];
+    summary: RequestPlanSummary;
+};
+export type RequestTodoSnapshot = RequestPlanItem & {
+    key: string;
+    events: RequestExecutionStep[];
+};
+export type RequestApprovalSnapshot = {
+    approvalId?: string;
+    pendingActionId?: string;
+    toolName?: string;
+    status?: ApprovalRecord["status"];
+    allowedDecisions?: Array<"approve" | "edit" | "reject">;
+};
+export type RequestEventSnapshot = {
+    sessionId: string;
+    requestId: string;
+    updatedAt: string;
+    state: RequestResult["state"];
+    agentId?: string;
+    plan: {
+        version: number;
+        updatedAt: string;
+        summary: RequestPlanSummary;
+        items: RequestTodoSnapshot[];
+    };
+    activeTodoKey?: string;
+    activeEventId?: string;
+    approval?: RequestApprovalSnapshot;
+    output: string;
+    contentBlocks?: unknown[];
+    structuredResponse?: unknown;
+    interruptContent?: string;
+    events: RequestExecutionStep[];
+};
+export type RequestDataEvent = {
+    type: "output.text.delta";
+    sessionId: string;
+    requestId: string;
+    agentId: string;
+    text: string;
+} | {
+    type: "progress.commentary";
+    sessionId: string;
+    requestId: string;
+    agentId: string;
+    text: string;
+} | {
+    type: "output.content-blocks";
+    sessionId: string;
+    requestId: string;
+    agentId: string;
+    contentBlocks: unknown[];
+} | {
+    type: "tool.result";
+    sessionId: string;
+    requestId: string;
+    agentId: string;
+    toolName: string;
+    output: unknown;
+    isError?: boolean;
+} | {
+    type: "debug.upstream";
+    sessionId: string;
+    requestId: string;
+    surfaceItem?: RuntimeSurfaceItem;
+    event: UpstreamRuntimeEvent;
+} | {
+    type: "debug.profile";
+    sessionId: string;
+    requestId: string;
+    step: RequestExecutionStep;
+};
+export type RequestListeners = RuntimeListeners & {
+    eventListener?: (snapshot: RequestEventSnapshot) => void | Promise<void>;
+    dataListener?: (event: RequestDataEvent) => void | Promise<void>;
+};
+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 RequestStartOptions = {
+    agentId?: string;
+    input: MessageContent;
+    sessionId?: string;
+    priority?: number;
+    invocation?: InvocationEnvelope;
+    listeners?: RequestListeners;
+};
+export type RequestDecisionOptions = {
+    sessionId: string;
+    requestId?: string;
+    approvalId?: string;
+    decision: "approve" | "edit" | "reject";
+    editedInput?: Record<string, unknown>;
+    listeners?: RequestListeners;
+};
+export type RequestOptions = RequestStartOptions | RequestDecisionOptions;
+export type HarnessStreamItem = {
+    type: "event";
+    event: HarnessEvent;
+} | {
+    type: "commentary";
+    sessionId: string;
+    requestId: string;
+    agentId: string;
+    content: string;
+} | {
+    type: "content";
+    sessionId: string;
+    requestId: string;
+    agentId: string;
+    content: string;
+} | {
+    type: "content-blocks";
+    sessionId: string;
+    requestId: string;
+    agentId: string;
+    contentBlocks: unknown[];
+} | {
+    type: "tool-result";
+    sessionId: string;
+    requestId: string;
+    agentId: string;
+    toolName: string;
+    output: unknown;
+    isError?: boolean;
+} | {
+    type: "plan-state";
+    sessionId: string;
+    requestId: string;
+    agentId: string;
+    planState: RequestPlanState;
+} | {
+    type: "upstream-event";
+    sessionId: string;
+    requestId: string;
+    surfaceItem?: RuntimeSurfaceItem;
+    event: UpstreamRuntimeEvent;
+} | {
+    type: "profile-step";
+    sessionId: string;
+    requestId: string;
+    step: RequestExecutionStep;
+} | {
+    type: "result";
+    result: RequestResult;
+};
+export type TranscriptMessage = {
+    role: "user" | "assistant";
+    content: MessageContent;
+    requestId: string;
+    createdAt: string;
+};
+export type SessionRequestRecord = {
+    requestId: string;
+    sessionId: string;
+    agentId: string;
+    parentRequestId?: string;
+    executionMode: string;
+    adapterKind?: string;
+    createdAt: string;
+    updatedAt: string;
+    state: RequestState;
+    checkpointRef: string | null;
+    resumable: boolean;
+    startedAt: string;
+    endedAt?: string;
+    lastActivityAt: string;
+    currentAgentId?: string;
+    delegationChain: string[];
+    runtimeSnapshot?: RuntimeSnapshot;
+};
+export type RequestSummary = SessionRequestRecord;
+export type RequestRecord = RequestSummary & {
+    traceItems?: unknown[];
+    runtimeTimeline?: RuntimeTimelineItem[];
+};
+export type SessionRecord = {
+    sessionId: string;
+    entryAgentId: string;
+    currentAgentId?: string;
+    currentState: RequestState;
+    latestRequestId: string;
+    createdAt: string;
+    updatedAt: string;
+    messages: TranscriptMessage[];
+    requests: RequestRecord[];
+    pendingDecision?: {
+        approvalId: string;
+        pendingActionId: string;
+        toolName: string;
+        allowedDecisions: Array<"approve" | "edit" | "reject">;
+        requestedAt: string;
+    };
+};
+export type ResumeOptions = {
+    sessionId?: string;
+    requestId?: string;
+    approvalId?: string;
+    decision?: "approve" | "edit" | "reject";
+    editedInput?: Record<string, unknown>;
+};
+export type CancelOptions = {
+    requestId: string;
+    reason?: string;
+};
+export type RestartConversationOptions = {
+    sessionId: string;
+    mode: "restart-in-session" | "restart-new-session";
+    input: string;
+};
+export type ApprovalRecord = {
+    approvalId: string;
+    pendingActionId: string;
+    sessionId: string;
+    requestId: string;
+    toolName: string;
+    approvalReason?: 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 ArtifactRecord = {
+    artifactId: string;
+    kind: string;
+    path: string;
+    createdAt: string;
+};
+export type ArtifactListing = {
+    sessionId: string;
+    requestId: string;
+    items: ArtifactRecord[];
+};
+export type RuntimeApprovalSummary = {
+    total: number;
+    pending: number;
+    approved: number;
+    edited: number;
+    rejected: number;
+    expired: number;
+    toolNames: string[];
+    approvalReasons: string[];
+};
+export type RuntimeGovernanceEvidence = {
+    bundles: RuntimeGovernanceBundle[];
+    approvalSummary: RuntimeApprovalSummary;
+    summary: string;
+};

package/dist/contracts/runtime-requests.js

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