@sema-agent/client-core 0.99.0 → 0.101.0

package/dist/hitl/decisionSend.d.ts

@@ -0,0 +1,116 @@
+import type { AgentClient, ElicitResponse } from '@sema-agent/sdk';
+import type { UiLanguage } from '../env/uiLanguage.js';
+import { type AskGoneDetail } from '../decideReceipt.js';
+import type { ApprovalDecidedByReading } from '../approvalDecidedByCapability.js';
+import { type DecisionNoteAudit } from './approvalDecisionNoteAudit.js';
+import { type DecisionRefusalClassified, type LiveAskPendingReading } from './decisionRefusal.js';
+import { type HostApprovalCardHold } from './approvalHolds.js';
+import { type ApprovalCardDecision, type ToolApprovalRespondAckView, type ToolApprovalRespondParkingView } from './toolApprovalWire.js';
+export declare const HITL_DECISION_FAMILIES: readonly ["approval", "ask", "elicitation"];
+export type HitlDecisionFamily = (typeof HITL_DECISION_FAMILIES)[number];
+export declare const HITL_DECISION_NOT_APPLIED_CAUSES: readonly ["gone", "parked", "parking", "lane_disabled", "refused", "idempotency_crossed"];
+export type HitlDecisionNotAppliedCause = (typeof HITL_DECISION_NOT_APPLIED_CAUSES)[number];
+export declare const HITL_DECISION_UNCONFIRMED_CAUSES: readonly ["transport", "server_error", "local_error", "aborted", "gone_after_retry"];
+export type HitlDecisionUnconfirmedCause = (typeof HITL_DECISION_UNCONFIRMED_CAUSES)[number];
+export declare const HITL_DECISION_NOT_SENT_CAUSES: readonly ["aborted", "duplicate_in_flight", "invalid_request", "no_verb", "not_an_answer"];
+export type HitlDecisionNotSentCause = (typeof HITL_DECISION_NOT_SENT_CAUSES)[number];
+export interface HitlApprovalDecisionRequest {
+    readonly family: 'approval';
+    readonly approvalId: string;
+    readonly taskId?: string;
+    readonly toolCallId?: string;
+    readonly answer: ApprovalCardDecision;
+}
+export interface HitlAskDecisionRequest {
+    readonly family: 'ask';
+    readonly taskId: string;
+    readonly askId: string;
+    readonly approvalId?: string;
+    readonly toolCallId?: string;
+    readonly answer: ApprovalCardDecision;
+}
+export interface HitlElicitationDecisionRequest {
+    readonly family: 'elicitation';
+    readonly elicitationId: string;
+    readonly taskId?: string;
+    readonly response: ElicitResponse;
+}
+export type HitlDecisionSendRequest = HitlApprovalDecisionRequest | HitlAskDecisionRequest | HitlElicitationDecisionRequest;
+export interface HitlDecisionSendClient {
+    readonly toolApprovals?: Partial<Pick<AgentClient['toolApprovals'], 'respond' | 'decideAsk'>>;
+    readonly elicitations?: Partial<Pick<AgentClient['elicitations'], 'respond'>>;
+}
+export interface HitlDecisionGate {
+    readonly family: HitlDecisionFamily;
+    readonly approvalId?: string;
+    readonly askId?: string;
+    readonly taskId?: string;
+    readonly elicitationId?: string;
+}
+export interface HitlDecisionSendDeps {
+    readonly client: HitlDecisionSendClient;
+    readonly signal?: AbortSignal;
+    readonly approvalDecisionNoteCapable?: boolean;
+    readonly approvalDecidedBy?: ApprovalDecidedByReading;
+    readonly readPending?: (gate: HitlDecisionGate, opts: {
+        readonly signal: AbortSignal;
+    }) => Promise<LiveAskPendingReading>;
+    readonly hold?: HostApprovalCardHold;
+}
+interface HitlDecisionOutcomeBase {
+    readonly family: HitlDecisionFamily;
+    readonly attempts: number;
+    readonly fallback?: 'approval';
+    readonly noteDropped?: true;
+    readonly rememberDropped?: true;
+    readonly attributionDropped?: true;
+    readonly attributionRenamed?: true;
+    readonly pending?: LiveAskPendingReading;
+    readonly parkingRetried?: true;
+}
+export interface HitlDecisionApplied extends HitlDecisionOutcomeBase {
+    readonly kind: 'applied';
+    readonly ack?: ToolApprovalRespondAckView;
+    readonly noteAudit?: DecisionNoteAudit;
+}
+export interface HitlDecisionSettledElsewhere extends HitlDecisionOutcomeBase {
+    readonly kind: 'settled_elsewhere';
+    readonly firstDecision?: 'approve' | 'deny';
+    readonly contrary?: true;
+    readonly decidedAtMs?: number;
+    readonly actorLabel?: string;
+    readonly noteAudit?: DecisionNoteAudit;
+}
+export interface HitlDecisionNotApplied extends HitlDecisionOutcomeBase {
+    readonly kind: 'not_applied';
+    readonly cause: HitlDecisionNotAppliedCause;
+    readonly errorCode?: string;
+    readonly status?: number;
+    readonly sessionId?: string;
+    readonly gone?: AskGoneDetail;
+    readonly retryAfterMs?: number;
+    readonly parking?: ToolApprovalRespondParkingView;
+    readonly refusal?: DecisionRefusalClassified;
+    readonly closesOut?: true;
+}
+export interface HitlDecisionUnconfirmed extends HitlDecisionOutcomeBase {
+    readonly kind: 'unconfirmed';
+    readonly cause: HitlDecisionUnconfirmedCause;
+    readonly status?: number;
+}
+export interface HitlDecisionNotSent extends HitlDecisionOutcomeBase {
+    readonly kind: 'not_sent';
+    readonly cause: HitlDecisionNotSentCause;
+}
+export type HitlDecisionSendOutcome = HitlDecisionApplied | HitlDecisionSettledElsewhere | HitlDecisionNotApplied | HitlDecisionUnconfirmed | HitlDecisionNotSent;
+export declare const HITL_DECISION_READBACK_BUDGET_MS = 4000;
+export interface HitlDecisionSendTiming {
+    readonly delays?: readonly number[];
+    readonly budgetMs?: number;
+    readonly parkingDelayMs?: number;
+}
+export declare function __setHitlDecisionSendTimingForTests(t?: HitlDecisionSendTiming): void;
+export declare function hitlAskIdempotencyKey(askId: string, verdict: 'approve' | 'deny'): string;
+export declare function sendHitlDecision(request: HitlDecisionSendRequest, deps: HitlDecisionSendDeps): Promise<HitlDecisionSendOutcome>;
+export declare function hitlDecisionOutcomeContent(outcome: HitlDecisionSendOutcome, lang?: UiLanguage): string | undefined;
+export {};