@criticalbridge/brain-client 1.0.0

package/dist/types/api.types.d.ts

@@ -0,0 +1,550 @@
+import type { AgentAssignment, EntityUser, PortalAgent } from './agent.types';
+export interface BrainClientConfig {
+    baseUrl: string;
+    entityId: string;
+    getAccessToken?: AccessTokenProvider;
+    fetchImpl?: FetchLike;
+    apiKey?: string;
+    requestTimeoutMs?: number;
+}
+export type FetchLike = (input: string | URL | Request, init?: RequestInit) => Promise<Response>;
+export type AccessTokenProvider = () => Promise<string | null | undefined> | string | null | undefined;
+export interface ListAgentsParams {
+    stages?: AgentStageFilter[];
+}
+export type AgentStageFilter = 'staging' | 'production';
+export interface ListAgentsResponse<T = PortalAgent> {
+    agents: T[];
+    count: number;
+    entityId: string;
+}
+export interface RegisterAgentRequest<TAgent = unknown> {
+    agent: TAgent;
+    seatLicenseId?: string;
+}
+export interface RegisterAgentResponse {
+    success: boolean;
+    agentId: string;
+    agent: PortalAgent;
+    created: boolean;
+}
+export interface ResolveTenantResponse {
+    id: string;
+    externalId: string;
+    slug: string;
+    currentTier: 'L1' | 'L2' | 'L3';
+    resourcePointers: Record<string, unknown>;
+}
+export interface RbacRole {
+    user_id: string;
+    entity_id: string;
+    role_name: string;
+    is_inherited: boolean;
+    granted_at: string;
+    granted_by: string;
+    is_active: boolean;
+    expires_at?: string;
+}
+export interface GetMyRbacRolesResponse {
+    roles: RbacRole[];
+}
+export interface AssignRbacRoleResponse {
+    assignment: RbacRole;
+}
+export interface CreateDelegationResponse {
+    assignment: RbacRole;
+}
+export interface GetDelegationsResponse {
+    roles: RbacRole[];
+}
+export type SuperUserScope = 'full' | 'read_only' | 'emergency';
+export interface SuperUserAccessRecord {
+    user_id: string;
+    granted_by: string;
+    granted_at: string;
+    expires_at?: string;
+    justification: string;
+    scope: SuperUserScope;
+    audit_required: boolean;
+}
+export interface GrantSuperUserRequest {
+    scope: SuperUserScope;
+    justification: string;
+    expiresAt?: string;
+}
+export interface GrantSuperUserResponse {
+    access: SuperUserAccessRecord;
+}
+export interface ListSuperUsersResponse {
+    superUsers: Array<{
+        userId: string;
+        access: SuperUserAccessRecord;
+    }>;
+}
+export interface GetSelfSuperUserResponse {
+    access: SuperUserAccessRecord | null;
+}
+export interface EntityMetadata {
+    id: string;
+    name: string;
+    display_name: string;
+    entity_type: string;
+}
+export interface GetEntityMetadataResponse {
+    metadata: EntityMetadata;
+}
+export interface BootstrapLoginResponse {
+    assigned: boolean;
+    assignment?: RbacRole;
+    alreadyAssigned?: boolean;
+    entityId?: string;
+    reason?: 'no_bootstrap_role';
+}
+export interface GetAgentResponse {
+    agent: PortalAgent;
+}
+export interface DeleteAgentResponse {
+    success: boolean;
+    agentId: string;
+}
+export interface UpdateAgentRequest<TAgent = Record<string, unknown>> {
+    patch: Partial<TAgent>;
+}
+export interface UpdateAgentResponse {
+    success: boolean;
+    agentId: string;
+    agent: PortalAgent;
+}
+export interface ListUsersResponse {
+    users: EntityUser[];
+    count: number;
+    entityId: string;
+    source?: 'auth0' | 'fallback';
+}
+export interface AssignAgentParams {
+    userId: string;
+    userEmail?: string;
+    userName?: string;
+    assignedBy?: string;
+}
+export interface AssignAgentResponse {
+    success: boolean;
+    assignment: AgentAssignment;
+    message: string;
+}
+export interface UnassignAgentResponse {
+    success: boolean;
+    message: string;
+    previousAssignment?: AgentAssignment;
+}
+export interface GetAssignmentResponse {
+    assigned: boolean;
+    agentId: string;
+    entityId: string;
+    assignment?: AgentAssignment;
+}
+export interface ListProcessesParams {
+    status?: string;
+    limit?: number;
+    page?: number;
+}
+export interface AgentActionResponse {
+    success: boolean;
+    message: string;
+    agentId: string;
+    previousStatus?: string;
+    newStatus?: string;
+}
+export interface ListProcessInstancesParams {
+    status?: string;
+}
+export type MonitorEventStatus = 'success' | 'warning' | 'error';
+export interface MonitorEvent {
+    eventId: string;
+    entityId: string;
+    domainPackId: string;
+    eventType: string;
+    timestamp: string;
+    source: string;
+    correlationId?: string;
+    causationId?: string;
+    version: number;
+    payload: Record<string, unknown>;
+    metadata?: Record<string, string>;
+    status: MonitorEventStatus;
+    duration: number;
+}
+export interface ListEventsParams {
+    limit?: number;
+    domainPackId?: string;
+    eventType?: string;
+}
+export interface ListEventsResponse {
+    events: MonitorEvent[];
+    count: number;
+    entityId: string;
+}
+export interface ListProcessInstancesResponse<T = unknown> {
+    processes: T[];
+    count: number;
+    entityId: string;
+}
+export type GetEntityLicenseUsageResponse<T = unknown> = T;
+export type GetSeatLicenseUsageResponse<T = unknown> = T;
+export interface ListAgentGroupsResponse<T = unknown> {
+    groups: T[];
+    count: number;
+    entityId: string;
+}
+export interface LicenseUtilizationPerSeat {
+    id: string;
+    userId: string;
+    eligibleAgentCount: number;
+}
+export interface LicenseUtilizationCursor {
+    agentId: string;
+    cursor: number;
+}
+export interface LicenseUtilizationOversubscribed {
+    agentId: string;
+    pendingItems: number;
+    seatCount: number;
+}
+export interface LicenseUtilizationUnusedSeat {
+    id: string;
+    userId: string;
+}
+export interface LicenseUtilizationSnapshot {
+    entityId: string;
+    perSeat: LicenseUtilizationPerSeat[];
+    cursors: LicenseUtilizationCursor[];
+    oversubscribed: LicenseUtilizationOversubscribed[];
+    unusedSeats: LicenseUtilizationUnusedSeat[];
+}
+export type GetLicenseAwareUtilizationResponse = LicenseUtilizationSnapshot;
+export type DispatchTerminalState = 'succeeded' | 'failed' | 'needs_attention' | 'heartbeat-timeout';
+export interface DispatchSummary {
+    dispatchId: string;
+    dispatchedAt: string;
+    workItemId: string;
+    agentId: string;
+    entityId: string;
+    runnerInstanceId: string | null;
+    lastHeartbeatAt: string | null;
+    terminalState: DispatchTerminalState | null;
+}
+export interface DispatchEvent {
+    kind: 'started' | 'step_completed' | 'succeeded' | 'failed' | 'needs_attention';
+    runnerInstanceId: string;
+    emittedAt: string;
+    stepId?: string;
+    stepName?: string;
+    durationMs?: number;
+}
+export interface ListDispatchesResponse {
+    dispatches: DispatchSummary[];
+    count: number;
+    entityId: string;
+}
+export interface GetDispatchResponse {
+    dispatch: DispatchSummary;
+    events: DispatchEvent[];
+    entityId: string;
+}
+export interface CancelDispatchResponse {
+    cancelled: boolean;
+    dispatchId: string;
+    runnerInstanceId?: string;
+}
+export interface CreateDispatchRequest<TWorkItem = Record<string, unknown>> {
+    dispatchId: string;
+    workItem: {
+        id: string;
+    } & TWorkItem;
+    agent: {
+        id: string;
+        entityId: string;
+        executionMode: string;
+    };
+}
+export interface CreateDispatchResponse {
+    accepted: true;
+    dispatchId: string;
+    runnerInstanceId: string;
+}
+export type MeshSurface = 'slack' | 'teams' | 'google-chat' | 'discord' | 'in-app' | 'a2a-internal' | 'a2a-external';
+export type MeshAdapterState = 'stopped' | 'starting' | 'running' | 'failed';
+export interface MeshAdapterHealth {
+    surface: MeshSurface;
+    state: MeshAdapterState;
+    lastError: string | null;
+    eventsProcessed: number;
+    eventsRejected: number;
+}
+export interface MeshSubscriptionRecord {
+    subscriptionId: string;
+    resource: string;
+    expiresAt: string;
+}
+export interface MeshSurfaceHealth {
+    health: MeshAdapterHealth;
+    subscriptions: MeshSubscriptionRecord[];
+}
+export interface MeshSubscriptionHealthResponse {
+    surfaces: MeshSurfaceHealth[];
+    entityId: string;
+    source?: 'live' | 'mock';
+}
+export type OperatorSignalTier = 'page' | 'investigation' | 'benign';
+export interface OperatorSignal {
+    id: string;
+    tag: string;
+    tier: OperatorSignalTier;
+    emittedAt: string;
+    message: string;
+    dispatchId?: string;
+    runnerInstanceId?: string;
+    context?: Record<string, unknown>;
+}
+export interface ListOperatorSignalsParams {
+    since?: string;
+}
+export interface ListOperatorSignalsResponse {
+    signals: OperatorSignal[];
+    count: number;
+    entityId: string;
+}
+export type SystemHealthStatus = 'healthy' | 'degraded' | 'unconfigured';
+export interface DispatcherHealth {
+    status: SystemHealthStatus;
+    configured: boolean;
+    brainEntityId: string | null;
+}
+export interface HeartbeatReconcilerHealth {
+    status: SystemHealthStatus;
+    enabled: boolean;
+    scanIntervalMs: number | null;
+    heartbeatThresholdMs: number | null;
+    dispatchGracePeriodMs: number | null;
+}
+export interface LedgerSizeHealth {
+    dispatchEntries: number;
+    runnerStatusEntries: number;
+    operatorSignals: number;
+    warnThreshold: number;
+    operatorSignalsCap: number;
+}
+export interface SystemHealthResponse {
+    dispatcher: DispatcherHealth;
+    reconciler: HeartbeatReconcilerHealth;
+    ledgers: LedgerSizeHealth;
+    snapshotAt: string;
+    entityId: string;
+}
+export interface WorkItem {
+    id: string;
+    enqueuedAt: string;
+    slaMinutes?: number;
+    staleFlagged?: boolean;
+    payload: Record<string, unknown>;
+}
+export type WorkAssignmentEventKind = 'enqueued' | 'completed' | 'reassigned-out' | 'reassigned-in' | 'stale-flagged';
+export interface WorkAssignmentEvent {
+    id: string;
+    ts: string;
+    kind: WorkAssignmentEventKind;
+    entityId: string;
+    agentId: string;
+    userSub: string;
+    itemId: string;
+    payload?: Record<string, unknown>;
+}
+export interface EnqueueWorkItemRequest {
+    userSub: string;
+    item: {
+        id: string;
+        slaMinutes?: number;
+        payload?: Record<string, unknown>;
+    };
+    source?: string;
+}
+export interface EnqueueWorkItemResponse {
+    enqueued: boolean;
+    itemId: string;
+    entityId?: string;
+    agentId?: string;
+    event?: WorkAssignmentEvent;
+}
+export interface ReassignWorkItemRequest {
+    targetUserSub?: string;
+    reason?: string;
+}
+export interface ReassignWorkItemResponse {
+    reassigned: boolean;
+    itemId: string;
+    fromUserSub: string;
+    toUserSub: string;
+    event: WorkAssignmentEvent;
+}
+export interface ListAgentWorkItemsParams {
+    limit?: number;
+    offset?: number;
+}
+export interface ListAgentWorkItemsResponse {
+    agentId: string;
+    entityId: string;
+    items: WorkItem[];
+    totalCount: number;
+    pagination: {
+        limit: number;
+        offset: number;
+    };
+    source: 'empty' | 'enabled' | 'stub';
+}
+export interface ListWorkAssignmentEventsParams {
+    agentId?: string;
+    userSub?: string;
+    workItemId?: string;
+    since?: string;
+    limit?: number;
+}
+export interface ListWorkAssignmentEventsResponse {
+    events: WorkAssignmentEvent[];
+    count: number;
+    entityId: string;
+}
+export interface DecisionLineageCitation {
+    source: string;
+    url?: string;
+    excerpt?: string;
+}
+export interface DecisionLineageRecord {
+    signalId: string;
+    signature: string;
+    workItemId: string;
+    agentId: string;
+    skill: string;
+    decidedAt: string;
+    inputs?: Record<string, unknown>;
+    outputs?: Record<string, unknown>;
+    citations: DecisionLineageCitation[];
+}
+export type DecisionLineageRiskTier = 'low' | 'medium' | 'high' | 'critical';
+export type DecisionLineageDataClassification = 'public' | 'internal' | 'confidential' | 'restricted';
+export type DecisionLineageHITLTouchpointType = 'approval_requested' | 'approval_granted' | 'approval_denied' | 'notify';
+export interface DecisionLineageHITLTouchpoint {
+    timestamp: string;
+    type: DecisionLineageHITLTouchpointType;
+    hitlRequestId?: string;
+    userId?: string;
+    reason?: string;
+    resolutionTimeMs?: number;
+}
+export interface DecisionLineageModelInvocation {
+    provider: string;
+    model: string;
+    modelVersion?: string;
+    tokensIn?: number;
+    tokensOut?: number;
+    cachedTokensIn?: number;
+}
+export type DecisionLineageContextSourceType = 'document' | 'database' | 'rules_engine' | 'api';
+export interface DecisionLineageRetrievedContextSource {
+    type: DecisionLineageContextSourceType;
+    sourceId: string;
+    sourceName?: string;
+    excerpt?: string;
+    url?: string;
+    retrievedAt: string;
+    relevanceScore?: number;
+}
+export interface DecisionLineageRecordV2 extends DecisionLineageRecord {
+    schemaVersion: number;
+    decisionId: string;
+    useCase?: string;
+    riskTier?: DecisionLineageRiskTier;
+    consumerRef?: string;
+    skillVersion?: string;
+    promptConfigHash?: string;
+    modelInvocation?: DecisionLineageModelInvocation;
+    retrievedContext?: DecisionLineageRetrievedContextSource[];
+    hitlTouchpoints?: DecisionLineageHITLTouchpoint[];
+    redactedFields?: string[];
+    dataClassification?: DecisionLineageDataClassification;
+    consumerImpacting?: boolean;
+}
+export interface GetDecisionLineageResponse {
+    record: DecisionLineageRecordV2;
+    entityId: string;
+}
+export interface RecordDecisionLineageRequest {
+    workItemId: string;
+    agentId: string;
+    skill: string;
+    inputs?: Record<string, unknown>;
+    outputs?: Record<string, unknown>;
+    citations?: DecisionLineageCitation[];
+    decisionId?: string;
+    useCase?: string;
+    riskTier?: DecisionLineageRiskTier;
+    consumerRef?: string;
+    skillVersion?: string;
+    promptConfigHash?: string;
+    modelInvocation?: DecisionLineageModelInvocation;
+    retrievedContext?: DecisionLineageRetrievedContextSource[];
+    hitlTouchpoints?: DecisionLineageHITLTouchpoint[];
+    dataClassification?: DecisionLineageDataClassification;
+    consumerImpacting?: boolean;
+}
+export interface RecordDecisionLineageResponse {
+    record: DecisionLineageRecordV2;
+    entityId: string;
+}
+export interface ListDecisionLineageParams {
+    decisionId?: string;
+    consumerRef?: string;
+    skill?: string;
+    skillVersion?: string;
+    modelProvider?: string;
+    modelName?: string;
+    riskTier?: DecisionLineageRiskTier;
+    startDate?: string;
+    endDate?: string;
+    hitlApprovalRequired?: boolean;
+    consumerImpacting?: boolean;
+    limit?: number;
+    offset?: number;
+}
+export interface DecisionLineageSummary {
+    signalId: string;
+    decisionId: string;
+    agentId: string;
+    workItemId: string;
+    skill: string;
+    skillVersion?: string;
+    consumerRef?: string;
+    modelProvider?: string;
+    modelName?: string;
+    riskTier?: DecisionLineageRiskTier;
+    decidedAt: string;
+    hitlTouchpointCount: number;
+    hitlApprovalRequired: boolean;
+    schemaVersion: number;
+    consumerImpacting?: boolean;
+}
+export interface ListDecisionLineageResponse {
+    records: DecisionLineageSummary[];
+    count: number;
+    totalCount: number;
+    entityId: string;
+    pagination: {
+        limit: number;
+        offset: number;
+    };
+}
+export interface GetDecisionLineageByConsumerResponse {
+    records: DecisionLineageSummary[];
+    count: number;
+    consumerRef: string;
+    entityId: string;
+}

package/dist/types/api.types.js

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=api.types.js.map

package/dist/types/api.types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"api.types.js","sourceRoot":"","sources":["../../src/types/api.types.ts"],"names":[],"mappings":""}

package/dist/types/approval-events.types.d.ts

@@ -0,0 +1,43 @@
+export type ApprovalEventKind = 'approval.pending' | 'approval.decided' | 'approval.escalated' | 'approval.resumed' | 'work.assigned' | 'work.completed';
+export interface ApprovalEventEnvelope {
+    entityId: string;
+    kind: ApprovalEventKind;
+    at: string;
+}
+export interface ApprovalPendingEvent extends ApprovalEventEnvelope {
+    kind: 'approval.pending';
+    actionId: string;
+    agentId?: string;
+}
+export interface ApprovalDecidedEvent extends ApprovalEventEnvelope {
+    kind: 'approval.decided';
+    actionId: string;
+    agentId?: string;
+    decision: 'approved' | 'rejected';
+    approverId?: string;
+}
+export interface ApprovalEscalatedEvent extends ApprovalEventEnvelope {
+    kind: 'approval.escalated';
+    actionId: string;
+    agentId?: string;
+    level: number;
+}
+export interface ApprovalResumedEvent extends ApprovalEventEnvelope {
+    kind: 'approval.resumed';
+    actionId: string;
+    agentId?: string;
+}
+export interface WorkAssignedEvent extends ApprovalEventEnvelope {
+    kind: 'work.assigned';
+    itemId: string;
+    agentId: string;
+    ownerSub: string;
+}
+export interface WorkCompletedEvent extends ApprovalEventEnvelope {
+    kind: 'work.completed';
+    itemId: string;
+    agentId: string;
+    ownerSub: string;
+}
+export type ApprovalEvent = ApprovalPendingEvent | ApprovalDecidedEvent | ApprovalEscalatedEvent | ApprovalResumedEvent | WorkAssignedEvent | WorkCompletedEvent;
+export declare function brainEventsTopicName(entityId: string): string;

package/dist/types/approval-events.types.js

@@ -0,0 +1,7 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.brainEventsTopicName = brainEventsTopicName;
+function brainEventsTopicName(entityId) {
+    return `brain-events-${entityId}`;
+}
+//# sourceMappingURL=approval-events.types.js.map

package/dist/types/approval-events.types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"approval-events.types.js","sourceRoot":"","sources":["../../src/types/approval-events.types.ts"],"names":[],"mappings":";;AA4DA,oDAEC;AAFD,SAAgB,oBAAoB,CAAC,QAAgB;IACnD,OAAO,gBAAgB,QAAQ,EAAE,CAAC;AACpC,CAAC"}