@sema-agent/client-core 0.97.0 → 0.98.0

package/dist/hitl/toolApprovalWire.d.ts

@@ -1,52 +1,18 @@
-import { type GateCurrentPending, type HitlFailureStage, type HitlSafetyCode, type HitlClientLike, type DecideOperationObserver } from './hitlBridge.js';
-import { type AllowRuleShadowedWireMember, type ApprovalAllowRuleShadow } from './allowRuleShadow.js';
+import { type HitlClientLike, type DecideOperationObserver } from './hitlBridge.js';
+import { type ApprovalAllowRuleShadow } from './allowRuleShadow.js';
+import { type ApprovalCardClaim } from './approvalHolds.js';
+import { type ApprovalResolution } from './approvalResolution.js';
 import { type ApprovalMandateWord } from '../gateVocabulary.js';
 import type { ToolPermissionRequest } from '../seatContract.js';
-import { type DenyAttributionRefusalDetail } from '../wireRefusalCopy.js';
 import { type ApprovalDecidedByReading } from '../approvalDecidedByCapability.js';
-import { type DecideReceiptView } from '../decideReceipt.js';
 import { RULE_OFFER_MATCHES, RULE_OFFER_BATCH_MEMBER_KINDS, RULE_OFFER_UNCOVERED_REASONS, RULE_OFFERS_ABSENCE_REASONS } from '@sema-agent/sdk';
-import type { ApprovalDecidedBy, ApprovalSettleCause, ToolApprovalRespondAck, PersistedRuleAnchor as SdkPersistedRuleAnchor, RuleOfferMatch as SdkRuleOfferMatch, RuleOfferBatchMember as SdkRuleOfferBatchMember, RuleOfferUncoveredDetail as SdkRuleOfferUncoveredDetail, RuleOfferUncoveredReason as SdkRuleOfferUncoveredReason, AskOrigin as SdkAskOrigin, RuleOffersAbsence as SdkRuleOffersAbsence, DenialLimitKind as SdkDenialLimitKind, DenialLimitFallback as SdkDenialLimitFallback, ToolApprovalCardWord } from '@sema-agent/sdk';
+import type { ApprovalDecidedBy, ToolApprovalDecision as SdkToolApprovalDecision, ToolApprovalRespondAck, ToolApprovalRespondReplayed, PersistedRuleAnchor, RuleOfferMatch, RuleOfferBatchMember, RuleOfferUncoveredDetail, RuleOfferUncoveredReason, AskOrigin, RuleOffersAbsence, DenialLimitKind, DenialLimitFallback, ToolApprovalFrame, RuleOffer as SdkRuleOffer, ToolApprovalCardWord } from '@sema-agent/sdk';
 export declare function toolNameIsFsWrite(name: string): boolean;
 export declare function toolNameIsShellExec(name: string): boolean;
 export declare function isToolApprovalGate(gate: {
     kind?: unknown;
     toolName?: unknown;
 } | undefined | null): boolean;
-export type FsApprovalOutcome = {
-    kind: 'decided';
-    gatedCallId?: string | undefined;
-    denied?: boolean | undefined;
-    denySettledBy?: ApprovalDenySettledBy | undefined;
-    denyReason?: string | undefined;
-    denyAttributionDropped?: true;
-    denyAttributionRenamed?: true;
-    receipt?: DecideReceiptView | undefined;
-    joinedInFlight?: true;
-} | {
-    kind: 'aborted';
-    gatedCallId?: string | undefined;
-    joinedInFlight?: true;
-} | {
-    kind: 'retracted';
-    gatedCallId?: string | undefined;
-    joinedInFlight?: true;
-} | {
-    kind: 'failed';
-    stage: HitlFailureStage;
-    gatedCallId?: string | undefined;
-    reason: string;
-    code?: 'no_pending' | 'wrong_gate' | undefined;
-    errorCode?: string | undefined;
-    blockedBy?: string | undefined;
-    retriable?: true;
-    safetyCode?: HitlSafetyCode | undefined;
-    retryExhausted?: true;
-    currentPending?: GateCurrentPending | undefined;
-    denyAttributionRefusal?: DenyAttributionRefusalDetail | undefined;
-    editRefused?: true;
-    joinedInFlight?: true;
-};
 export interface FsApprovalWireDeps {
     client: HitlClientLike;
     onPresented?: () => void;
@@ -54,41 +20,27 @@ export interface FsApprovalWireDeps {
     approvalDecidedBy?: ApprovalDecidedByReading | undefined;
 }
 export declare function structurallyEqual(a: unknown, b: unknown): boolean;
-export type RuleOfferMatch = SdkRuleOfferMatch;
-export type RuleOfferBatchMember = SdkRuleOfferBatchMember;
-export type RuleOfferUncoveredDetail = SdkRuleOfferUncoveredDetail;
-export type RuleOfferUncoveredReason = SdkRuleOfferUncoveredReason;
+export type { RuleOfferMatch };
+export type { RuleOfferBatchMember };
+export type { RuleOfferUncoveredDetail };
+export type { RuleOfferUncoveredReason };
 export { RULE_OFFER_MATCHES, RULE_OFFER_BATCH_MEMBER_KINDS, RULE_OFFER_UNCOVERED_REASONS };
-export type AskOrigin = SdkAskOrigin;
-export type RuleOffersAbsence = SdkRuleOffersAbsence;
-export type DenialLimitKind = SdkDenialLimitKind;
-export type DenialLimitFallback = SdkDenialLimitFallback;
+export type { AskOrigin };
+export type { RuleOffersAbsence };
+export type { DenialLimitKind };
+export type { DenialLimitFallback };
 export { RULE_OFFERS_ABSENCE_REASONS };
 export declare const ASK_ORIGIN_WORDS: readonly string[];
-export type WireRuleOffer = {
-    kind: 'single';
-    rule: string;
-    match: RuleOfferMatch;
-    command: string;
-} | {
-    kind: 'batch';
-    rules: readonly RuleOfferBatchMember[];
-    uncoveredSegments: number;
-    uncoveredDetail?: readonly RuleOfferUncoveredDetail[];
-};
-export type RuleOffer = {
+export type RuleOfferReading = (Extract<SdkRuleOffer, {
     kind: 'single';
+}> & {
     offerIndex: number;
-    rule: string;
-    match: RuleOfferMatch;
-    command: string;
-} | {
+}) | (Omit<Extract<SdkRuleOffer, {
     kind: 'batch';
+}>, 'uncoveredDetail'> & {
     offerIndex: number;
-    rules: RuleOfferBatchMember[];
-    uncoveredSegments: number;
     uncoveredDetail?: readonly RuleOfferUncoveredDetail[];
-};
+});
 export interface ApprovalCardAllowDecision {
     kind: 'allow';
     allowSession: boolean;
@@ -96,6 +48,7 @@ export interface ApprovalCardAllowDecision {
     persistRule?: string;
     persistRuleEdited?: true;
     persistRuleBatchOfferIndex?: number;
+    note?: string;
 }
 export interface ApprovalCardDenyDecision {
     kind: 'deny';
@@ -129,8 +82,8 @@ export interface ApprovalCardRequest {
     argsUnavailable?: true;
     governanceForced?: true;
     delegation?: ToolApprovalDelegation;
-    ruleOffers?: RuleOffer[];
-    ruleOffersReadOnly?: RuleOffer[];
+    ruleOffers?: RuleOfferReading[];
+    ruleOffersReadOnly?: RuleOfferReading[];
     inputHasBidi?: true;
     hasBidiControls?: true;
     allowRuleShadow?: ApprovalAllowRuleShadow;
@@ -159,6 +112,21 @@ export interface ApprovalCardRequest {
     unreadableEvidence?: readonly string[];
     classifierNoRuling?: string;
     priorCardsForCall?: readonly ApprovalPriorCard[];
+    message?: string;
+    cardPayloadUnreadable?: true;
+    supersedes?: ApprovalCardSupersedes;
+    parkRow?: ApprovalCardParkRow;
+}
+export interface ApprovalCardSupersedes {
+    readonly approvalId?: string;
+    readonly parked?: true;
+    readonly priorAnswer?: ToolApprovalRespondDecision;
+    readonly priorAnswerOutcome?: 'not_sent' | 'not_accepted' | 'unconfirmed';
+}
+export interface ApprovalCardParkRow {
+    readonly taskId: string;
+    readonly gatedCallId?: string;
+    readonly deadlineMs?: number;
 }
 export interface ApprovalPriorCard {
     readonly approvalId?: string;
@@ -180,53 +148,13 @@ export declare function surfaceApprovalCard(req: ApprovalCardRequest): Promise<A
 declare const REMEMBER_REFUSAL_CODES: readonly ["remember_not_in_proof", "remember_requires_binding", "capability.store_required", "decide.workflow_remember_unsupported", "decide.parked_remember_unsupported"];
 export type RememberRefusalCode = (typeof REMEMBER_REFUSAL_CODES)[number];
 export declare function rememberRefusalOf(error: unknown): RememberRefusalCode | undefined;
-export declare function surfaceFsApprovalAndDecide(deps: FsApprovalWireDeps, taskId: string, argsByCall: Map<string, unknown>, signal?: AbortSignal, parkGatedCallId?: string, parkToolName?: string): Promise<FsApprovalOutcome>;
+export declare function surfaceFsApprovalAndDecide(deps: FsApprovalWireDeps, taskId: string, argsByCall: Map<string, unknown>, signal?: AbortSignal, parkGatedCallId?: string, parkToolName?: string): Promise<ApprovalResolution>;
 export interface BoundSkillGrantsWire {
     readonly skill: string | null;
     readonly allowedTools: readonly string[];
     readonly disallowedTools: readonly string[];
 }
-export interface ToolApprovalFrame {
-    type: 'tool_approval' | 'tool_approval_complete';
-    approvalId: string;
-    toolName?: string;
-    toolCallId?: string;
-    message?: string;
-    args?: unknown;
-    argsOmitted?: boolean;
-    outcome?: 'allowed' | 'denied' | 'expired';
-    cause?: ApprovalSettleCause;
-    sourceTaskId?: string;
-    fromSubagent?: true;
-    sourceAgentName?: string;
-    governanceForced?: true;
-    delegation?: ToolApprovalDelegation;
-    ruleOffers?: readonly WireRuleOffer[];
-    ruleOffersAbsence?: string;
-    denialLimitFallback?: DenialLimitFallback;
-    persistedRuleShadowed?: string;
-    allowRuleShadowed?: readonly AllowRuleShadowedWireMember[];
-    boundGrantDigest?: string;
-    boundGrants?: BoundSkillGrantsWire;
-    classifierNoRuling?: string;
-    probeCause?: unknown;
-    probeReason?: string;
-    rememberRefused?: true;
-    ruleEvidence?: unknown;
-    requiresRealApproval?: true;
-    mandated?: true;
-    mandate?: string;
-    origin?: string;
-    approvalCard?: string;
-    askClass?: string;
-    classes?: readonly string[];
-    inputHasBidi?: true;
-    parked?: true;
-    expiresInMs?: number;
-    expiresAtMs?: number;
-    serverNowMs?: number;
-    readRootCandidate?: ReadRootCandidateView;
-}
+export type { ToolApprovalFrame };
 export interface ReadRootCandidateView {
     dir: string;
     clearsThisAsk: true;
@@ -237,7 +165,7 @@ export interface ToolApprovalDelegation {
     depth: number;
     agentName?: string;
 }
-export declare const TOOL_APPROVAL_FRAME_KEYS_MIRROR: readonly ["type", "approvalId", "toolCallId", "toolName", "sourceTaskId", "fromSubagent", "sourceAgentName", "message", "args", "argsOmitted", "governanceForced", "ruleOffers", "ruleOffersAbsence", "denialLimitFallback", "readRootCandidate", "mandated", "mandate", "origin", "approvalCard", "askClass", "classes", "inputHasBidi", "parked", "persistedRuleShadowed", "allowRuleShadowed", "probeCause", "probeReason", "rememberRefused", "boundGrantDigest", "boundGrants", "classifierNoRuling", "ruleEvidence", "requiresRealApproval", "expiresInMs", "expiresAtMs", "serverNowMs", "delegation", "outcome", "cause"];
+export declare const TOOL_APPROVAL_FRAME_KEYS_MIRROR: readonly ["type", "approvalId", "toolCallId", "toolName", "sourceTaskId", "fromSubagent", "sourceAgentName", "message", "args", "argsOmitted", "governanceForced", "ruleOffers", "ruleOffersAbsence", "denialLimitFallback", "readRootCandidate", "mandated", "mandate", "origin", "approvalCard", "askClass", "classes", "inputHasBidi", "parked", "persistedRuleShadowed", "allowRuleShadowed", "probeCause", "probeReason", "rememberRefused", "boundGrantDigest", "boundGrantAbsence", "boundGrants", "classifierNoRuling", "ruleEvidence", "requiresRealApproval", "expiresInMs", "expiresAtMs", "serverNowMs", "delegation", "outcome", "cause"];
 export interface ApprovalMandatedFacts {
     readonly mandated?: true;
     readonly ruleOffersAbsence?: string;
@@ -250,7 +178,37 @@ export declare function readApprovalMandate(v: {
 export declare function readApprovalCardWord(carrier: unknown): ToolApprovalCardWord | undefined;
 export declare function toolPermissionRequestAskBits(card: object | null | undefined, requestId?: string): Pick<ToolPermissionRequest, 'mandated' | 'mandate' | 'origin' | 'ruleOffersAbsence' | 'askClass' | 'classes' | 'sessionRow'>;
 export declare function isFromSubagent(frame: ToolApprovalFrame): boolean;
-export type ToolApprovalRespondDecision = 'allow' | 'allow_session' | 'deny';
+export type ToolApprovalRespondDecision = SdkToolApprovalDecision;
+export declare const RESPOND_DECISIONS: readonly ["allow", "allow_session", "deny"];
+export type AnswerPayloadLane = 'respond' | 'decide';
+export interface AnswerPayloadCaps {
+    readonly approvalDecisionNoteCapable?: boolean;
+}
+export interface RespondAnswerPayload extends Pick<RespondToolApprovalOpts, 'updatedInput' | 'note'> {
+    readonly decision: ToolApprovalRespondDecision;
+}
+export interface DecideApprovePayload extends Pick<ApprovalCardAllowDecision, 'updatedInput'> {
+    readonly decision: 'approve';
+    readonly remember?: 'session';
+}
+export interface DecideDenyPayload {
+    readonly decision: 'deny';
+    readonly reason: string;
+}
+export type DecideAnswerPayload = DecideApprovePayload | DecideDenyPayload;
+export declare function answerPayloadFor(answer: ApprovalCardDecision, lane: 'respond', caps?: AnswerPayloadCaps | null): RespondAnswerPayload | undefined;
+export declare function answerPayloadFor(answer: ApprovalCardDecision, lane: 'decide', caps?: AnswerPayloadCaps | null): DecideAnswerPayload | undefined;
+export interface AnswerCarriage {
+    readonly allowNote: 'model' | 'none';
+}
+export declare function answerCarriage(card: Pick<ApprovalCardRequest, 'callKey'> | null | undefined): AnswerCarriage;
+export interface ApprovalAnswerCommitted {
+    readonly callKey: string;
+    readonly lane: AnswerPayloadLane;
+    readonly answer: ApprovalCardDecision;
+    readonly payload: RespondAnswerPayload | DecideAnswerPayload;
+}
+export declare function observeApprovalAnswerCommitted(listener: (event: ApprovalAnswerCommitted) => void): () => void;
 export interface RespondToolApprovalOpts {
     signal?: AbortSignal;
     updatedInput?: unknown;
@@ -263,7 +221,8 @@ export interface RespondToolApprovalOpts {
 }
 export type RespondToolApprovalFn = (approvalId: string, decision: ToolApprovalRespondDecision, opts?: RespondToolApprovalOpts) => Promise<ToolApprovalRespondAck | void>;
 export type ToolApprovalRespondAckView = ToolApprovalRespondAck;
-export type PersistedRuleAnchor = SdkPersistedRuleAnchor;
+export declare function isToolApprovalRespondReplayed(ack: ToolApprovalRespondAckView): ack is ToolApprovalRespondReplayed;
+export type { PersistedRuleAnchor };
 export declare function readToolApprovalRespondAck(v: unknown): ToolApprovalRespondAckView | undefined;
 export interface ToolApprovalRespondParkingView {
     readonly approvalId: string;
@@ -283,40 +242,6 @@ export declare function decisionAttributionKeyOf(reading: ApprovalDecidedByReadi
 } | {
     settledBy: 'policy';
 } | Record<never, never>;
-export interface ToolApprovalFrameOutcome {
-    decision: ToolApprovalRespondDecision | 'unresolved';
-    ack?: ToolApprovalRespondAckView;
-    respondRefusal?: ToolApprovalRespondRefusal;
-    editRefused?: true;
-    retracted?: true;
-    aborted?: true;
-    joinedInFlight?: true;
-    denySettledBy?: ApprovalDenySettledBy;
-    denyReason?: string;
-    denyAttributionRefusal?: DenyAttributionRefusalDetail;
-    denyAttributionDropped?: true;
-    denyAttributionRenamed?: true;
-    parking?: ToolApprovalRespondParkingView;
-}
-interface ToolApprovalRespondRefusalFields {
-    status?: number;
-    errorCode?: string;
-    message?: string;
-    retriable?: true;
-    extra?: {
-        readonly cause?: string;
-        readonly field?: string;
-    };
-    unreadable?: true;
-}
-export type ToolApprovalRespondRefusal = (ToolApprovalRespondRefusalFields & {
-    status: number;
-}) | (ToolApprovalRespondRefusalFields & {
-    errorCode: string;
-}) | (ToolApprovalRespondRefusalFields & {
-    message: string;
-});
-export declare function readToolApprovalRespondRefusal(err: unknown): ToolApprovalRespondRefusal | undefined;
 export declare function isToolApprovalFrame(ev: unknown): ev is ToolApprovalFrame;
 export declare function askProbeReasonDetail(card: Pick<ApprovalCardRequest, 'probeReason' | 'probeCause'> | null | undefined): string | undefined;
 export declare function readApprovalRememberRefused(v: unknown): boolean;
@@ -326,11 +251,19 @@ export declare function readApprovalClassifierNoRuling(v: unknown): string | und
 export declare function classifierNoRulingDetail(word: string | undefined): string;
 export declare function approvalBoundGrantsDetail(grants: BoundSkillGrantsWire | null | undefined): string | undefined;
 export declare function approvalPriorCardsDetail(card: Pick<ApprovalCardRequest, 'priorCardsForCall' | 'origin'> | null | undefined): string | undefined;
+export declare function approvalSupersedesDetail(card: Pick<ApprovalCardRequest, 'supersedes'> | null | undefined): string | undefined;
 export declare function readDenialLimitFallback(v: unknown): DenialLimitFallback | undefined;
-export declare function readRuleOffers(v: unknown): RuleOffer[] | undefined;
-export declare function readRuleOfferSupply(offers: unknown): RuleOffer[] | undefined;
-export type ApprovalCardV1Facts = Pick<ApprovalCardRequest, 'toolName' | 'args'> & Pick<ApprovalCardRequest, 'toolCallId' | 'workerBadge' | 'wireNote' | 'argsUnavailable' | 'governanceForced' | 'delegation' | 'ruleOffersReadOnly' | 'inputHasBidi' | 'allowRuleShadow' | 'probeCause' | 'rememberRefused' | 'ruleEvidence' | 'requiresRealApproval' | 'ruleOffersAbsence' | 'denialLimitFallback' | 'askClass' | 'classes' | 'grantBinding' | 'unreadableEvidence'>;
+export declare function readRuleOffers(v: unknown): RuleOfferReading[] | undefined;
+export declare function readRuleOfferSupply(offers: unknown): RuleOfferReading[] | undefined;
+export type ApprovalCardV1Facts = Pick<ApprovalCardRequest, 'toolName' | 'args'> & Pick<ApprovalCardRequest, 'toolCallId' | 'workerBadge' | 'wireNote' | 'argsUnavailable' | 'governanceForced' | 'delegation' | 'ruleOffersReadOnly' | 'inputHasBidi' | 'allowRuleShadow' | 'probeCause' | 'rememberRefused' | 'ruleEvidence' | 'requiresRealApproval' | 'ruleOffersAbsence' | 'denialLimitFallback' | 'askClass' | 'classes' | 'grantBinding' | 'unreadableEvidence' | 'message'>;
+export type ApprovalCardFacts = ApprovalCardV1Facts & Pick<ApprovalCardRequest, 'ruleOffers' | 'probeReason' | 'mandated' | 'mandate' | 'readRootCandidate' | 'origin' | 'approvalCard' | 'boundGrants' | 'classifierNoRuling' | 'allowSessionCarried' | 'cardPayloadUnreadable'>;
+export interface ApprovalCardFrameFactsOptions {
+    readonly streamArgs?: object;
+    readonly argsUnavailable?: true;
+}
 export declare function approvalCardFactsOfV1(card: object | null | undefined): Readonly<ApprovalCardV1Facts> | undefined;
+export declare function approvalCardFactsOfFrame(frame: object | null | undefined, opts?: ApprovalCardFrameFactsOptions | null): Readonly<ApprovalCardFacts> | undefined;
+export declare function approvalCardFactsOfGeneric(card: object | null | undefined): Readonly<ApprovalCardFacts> | undefined;
 export interface ToolApprovalFrameLaneOpts {
     approvalDecisionNoteCapable?: boolean;
     respondFreeFormRulesCapable?: boolean;
@@ -342,7 +275,7 @@ export interface ToolApprovalFrameLaneOpts {
 export declare function surfaceToolApprovalFrameAndRespond(frame: ToolApprovalFrame, respond: RespondToolApprovalFn, streamArgs: unknown | undefined, signal?: AbortSignal, lane?: ToolApprovalFrameLaneOpts, run?: {
     readonly taskId?: string;
     readonly sessionId?: string;
-}): Promise<ToolApprovalFrameOutcome>;
+}): Promise<ApprovalResolution>;
 export interface ApprovalHolderIdentity {
     readonly approvalId?: string;
     readonly taskId?: string;
@@ -351,8 +284,10 @@ export interface ApprovalHolderIdentity {
 }
 export type ApprovalHolderJoin = {
     readonly kind: 'joined';
-    readonly outcome: ToolApprovalFrameOutcome;
+    readonly outcome: ApprovalResolution;
 } | {
     readonly kind: 'free';
 };
 export declare function joinApprovalHolder(identity: ApprovalHolderIdentity, signal?: AbortSignal): Promise<ApprovalHolderJoin>;
+export declare function claimApprovalCard(identity: ApprovalHolderIdentity, signal?: AbortSignal): Promise<ApprovalCardClaim>;
+export type { ApprovalCardClaim, HostApprovalCardHold } from './approvalHolds.js';