@sema-agent/client-core 0.79.1 → 0.80.0

package/dist/hitl/toolApprovalWire.d.ts

@@ -1,5 +1,6 @@
 import { type GateCurrentPending, type HitlFailureStage, type HitlSafetyCode, type HitlClientLike } from './hitlBridge.js';
 import { type RuleStoreUnreadableKind } from '../gateVocabulary.js';
+import { type DenyAttributionRefusalDetail } from '../wireRefusalCopy.js';
 import { type DecideReceiptView } from '../decideReceipt.js';
 import { RULE_OFFER_MATCHES, RULE_OFFER_BATCH_MEMBER_KINDS, RULE_OFFER_UNCOVERED_REASONS, RULE_OFFERS_ABSENCE_REASONS, DENIAL_LIMIT_KINDS } from '@sema-agent/sdk';
 import type { RuleSuggestion, 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 } from '@sema-agent/sdk';
@@ -19,6 +20,7 @@ export type FsApprovalOutcome = {
     denied?: boolean | undefined;
     denySettledBy?: ApprovalDenySettledBy | undefined;
     denyReason?: string | undefined;
+    denyAttributionDropped?: true;
     receipt?: DecideReceiptView | undefined;
 } | {
     kind: 'aborted';
@@ -36,6 +38,7 @@ export type FsApprovalOutcome = {
     safetyCode?: HitlSafetyCode | undefined;
     retryExhausted?: true;
     currentPending?: GateCurrentPending | undefined;
+    denyAttributionRefusal?: DenyAttributionRefusalDetail | undefined;
 };
 export interface FsApprovalWireDeps {
     client: HitlClientLike;
@@ -202,6 +205,7 @@ export interface RespondToolApprovalOpts {
     persistRuleEdited?: true;
     persistRuleBatchOfferIndex?: number;
     note?: string;
+    settledBy?: 'policy';
 }
 export type RespondToolApprovalFn = (approvalId: string, decision: ToolApprovalRespondDecision, opts?: RespondToolApprovalOpts) => Promise<ToolApprovalRespondAck | void>;
 export type ToolApprovalRespondAckView = ToolApprovalRespondAck;
@@ -215,6 +219,8 @@ export interface ToolApprovalFrameOutcome {
     retracted?: true;
     denySettledBy?: ApprovalDenySettledBy;
     denyReason?: string;
+    denyAttributionRefusal?: DenyAttributionRefusalDetail;
+    denyAttributionDropped?: true;
 }
 interface ToolApprovalRespondRefusalFields {
     status?: number;

package/dist/hitl/toolApprovalWire.js

@@ -6,6 +6,7 @@ import { readEngineActiveBgTasks } from '../fleet/fleetLedger.js';
 import { observeCancelByDeny, surfaceRememberNotApplied, surfaceEditNotForwarded, surfaceEditRefusedOnBlindAsk, surfaceRuleArmNotSent, surfaceRuleArmRejected } from './hitlHostSurface.js';
 import { approvalCallKey, liveFrameCallKey } from './gateIdentity.js';
 import { isRuleStoreUnreadableKind } from '../gateVocabulary.js';
+import { denyAttributionRefusalFromError } from '../wireRefusalCopy.js';
 import { readDecideReceipt } from '../decideReceipt.js';
 import { RULE_OFFER_MATCHES, RULE_OFFER_BATCH_MEMBER_KINDS, RULE_OFFER_UNCOVERED_REASONS, RULE_OFFERS_ABSENCE_REASONS, DENIAL_LIMIT_KINDS, } from '@sema-agent/sdk';
 export function isFsApprovalGate(gate) {
@@ -205,18 +206,44 @@ export async function surfaceFsApprovalAndDecide(deps, taskId, argsByCall, signa
                     ...(safetyCode !== undefined ? { safetyCode } : {}),
                 };
             }
-        case 'deny':
+        case 'deny': {
+            const denySettledByForWire = readApprovalDenySettledBy(card);
+            const denyReasonSnapshot = typeof card.reason === 'string' ? card.reason : undefined;
+            let lastSendCarriedAttribution = false;
             try {
-                const raw = await bridge.decideTool({ decision: 'deny', reason: denyReasonForWire(card.reason, `task ${taskId}`) ?? DEFAULT_DENY_REASON }, gatedCallId, signal ? { signal } : undefined, pending);
+                const denyBody = {
+                    decision: 'deny',
+                    reason: denyReasonForWire(denyReasonSnapshot, `task ${taskId}`) ?? DEFAULT_DENY_REASON,
+                    ...(denySettledByForWire === 'policy' ? { settledBy: 'policy' } : {}),
+                };
+                let attributionDropped = false;
+                let raw;
+                lastSendCarriedAttribution = denySettledByForWire === 'policy';
+                try {
+                    raw = await bridge.decideTool(denyBody, gatedCallId, signal ? { signal } : undefined, pending);
+                }
+                catch (first) {
+                    if (!shouldResendWithoutAttribution(first, lastSendCarriedAttribution, signal))
+                        throw first;
+                    const { settledBy: _droppedKey, ...withoutAttribution } = denyBody;
+                    void _droppedKey;
+                    lastSendCarriedAttribution = false;
+                    hostLog('debug', `liveToolApprovalWire: decide(deny) for task ${taskId} was refused because the settlement note is not part of ` +
+                        'what this deployment signs — re-sending the SAME decision exactly once with that one key removed ' +
+                        '(the refusal happened before the approval was judged, so nothing was consumed and this is a re-delivery, not a second act)');
+                    raw = await bridge.decideTool(withoutAttribution, gatedCallId, signal ? { signal } : undefined, pending);
+                    attributionDropped = true;
+                }
                 const receipt = readDecideReceipt(raw);
-                const denySettledBy = readApprovalDenySettledBy(card);
-                const denyReason = typeof card.reason === 'string' && card.reason.trim() !== '' ? card.reason : undefined;
+                const denySettledBy = denySettledByForWire;
+                const denyReason = denyReasonSnapshot !== undefined && denyReasonSnapshot.trim() !== '' ? denyReasonSnapshot : undefined;
                 return {
                     kind: 'decided',
                     gatedCallId,
                     denied: true,
                     ...(denySettledBy !== undefined ? { denySettledBy } : {}),
                     ...(denyReason !== undefined ? { denyReason } : {}),
+                    ...(attributionDropped ? { denyAttributionDropped: true } : {}),
                     ...(receipt !== undefined ? { receipt } : {}),
                 };
             }
@@ -224,6 +251,7 @@ export async function surfaceFsApprovalAndDecide(deps, taskId, argsByCall, signa
                 const currentPending = readDecideCurrentPending(e);
                 const wireCode = readWireErrorCode(e);
                 const safetyCode = e instanceof HitlSafetyError ? e.code : undefined;
+                const attributionRefusal = denyAttributionRefusalFromError(e, lastSendCarriedAttribution);
                 return {
                     kind: 'failed',
                     stage: 'decide',
@@ -233,8 +261,10 @@ export async function surfaceFsApprovalAndDecide(deps, taskId, argsByCall, signa
                     ...(currentPending !== undefined ? { currentPending } : {}),
                     ...(wireCode !== undefined ? { errorCode: wireCode } : {}),
                     ...(safetyCode !== undefined ? { safetyCode } : {}),
+                    ...(attributionRefusal !== null ? { denyAttributionRefusal: attributionRefusal } : {}),
                 };
             }
+        }
     }
 }
 function readReadRootCandidate(v) {
@@ -392,6 +422,13 @@ function readPersistedRuleAnchors(v) {
 function isNonNegativeSafeInt(v) {
     return typeof v === 'number' && Number.isSafeInteger(v) && v >= 0;
 }
+function shouldResendWithoutAttribution(e, sentSettledBy, signal) {
+    if (!sentSettledBy)
+        return false;
+    if (signal?.aborted === true)
+        return false;
+    return denyAttributionRefusalFromError(e, true)?.kind === 'not_in_proof';
+}
 export function readToolApprovalRespondRefusal(err) {
     const pick = (key) => {
         try {
@@ -647,6 +684,8 @@ function subagentBadgeFor(frame) {
 }
 const MAX_RESPOND_NOTE_CHARS = 2048;
 export async function surfaceToolApprovalFrameAndRespond(frame, respond, streamArgs, signal, lane) {
+    const approvalId = frame.approvalId;
+    const frameToolCallId = typeof frame.toolCallId === 'string' && frame.toolCallId !== '' ? frame.toolCallId : undefined;
     const toolName = typeof frame.toolName === 'string' ? frame.toolName : 'Write';
     let args = streamArgs !== undefined && streamArgs !== null
         ? streamArgs
@@ -657,7 +696,7 @@ export async function surfaceToolApprovalFrameAndRespond(frame, respond, streamA
     if (typeof args !== 'object' || args === null) {
         if (frame.argsOmitted === true) {
             wireNote = 'tool arguments exceeded the wire cap and were omitted — the diff below is reconstructed from the gate message, not the full payload';
-            hostLog('debug', `liveToolApprovalWire: frame ${frame.approvalId} args omitted (>16KiB wire cap) — card falls back to message-derived path`);
+            hostLog('debug', `liveToolApprovalWire: frame ${approvalId} args omitted (>16KiB wire cap) — card falls back to message-derived path`);
         }
         if (lane?.argsUnavailable === true) {
             wireNote =
@@ -673,9 +712,9 @@ export async function surfaceToolApprovalFrameAndRespond(frame, respond, streamA
     const card = await surfaceApprovalCard({
         toolName,
         args: args,
-        callKey: liveFrameCallKey(frame.approvalId),
-        ...(typeof frame.toolCallId === 'string' && frame.toolCallId !== ''
-            ? { toolCallId: frame.toolCallId }
+        callKey: liveFrameCallKey(approvalId),
+        ...(frameToolCallId !== undefined
+            ? { toolCallId: frameToolCallId }
             : {}),
         ...(signal ? { signal } : {}),
         ...(isFromSubagent(frame) ? { workerBadge: subagentBadgeFor(frame) } : {}),
@@ -713,32 +752,36 @@ export async function surfaceToolApprovalFrameAndRespond(frame, respond, streamA
         ...(typeof frame.origin === 'string' && frame.origin !== '' ? { origin: frame.origin } : {}),
     });
     if (lane?.argsUnavailable === true && card.kind === 'allow' && card.updatedInput !== undefined) {
-        hostLog('error', `liveToolApprovalWire: ${frame.approvalId} card returned an edited approval on an args-unavailable ask — nothing sent (the ask stays pending)`);
+        hostLog('error', `liveToolApprovalWire: ${approvalId} card returned an edited approval on an args-unavailable ask — nothing sent (the ask stays pending)`);
         surfaceEditRefusedOnBlindAsk();
         return { decision: 'unresolved', editRefused: true };
     }
     if (card.kind === RETRACTED_CARD_DECISION_KIND) {
-        hostLog('debug', `liveToolApprovalWire: ${frame.approvalId} card retracted without a decision${card.reason ? ` (${card.reason})` : ''} — nothing sent`);
+        hostLog('debug', `liveToolApprovalWire: ${approvalId} card retracted without a decision${card.reason ? ` (${card.reason})` : ''} — nothing sent`);
         return { decision: 'unresolved', retracted: true };
     }
     const decision = card.kind === 'allow' ? (card.allowSession ? 'allow_session' : 'allow') : 'deny';
+    const denySettledByForWire = card.kind === 'deny' ? readApprovalDenySettledBy(card) : undefined;
+    const sentSettledBy = decision === 'deny' && denySettledByForWire === 'policy';
+    let lastSendCarriedAttribution = sentSettledBy;
+    const denyReasonSnapshot = card.kind === 'deny' && typeof card.reason === 'string' ? card.reason : undefined;
     if (card.kind === 'failed') {
-        hostLog('debug', `liveToolApprovalWire: approval card unavailable (${card.reason}) — fail-closed deny for ${frame.approvalId}`);
+        hostLog('debug', `liveToolApprovalWire: approval card unavailable (${card.reason}) — fail-closed deny for ${approvalId}`);
     }
     let note;
-    if (card.kind === 'deny' && typeof card.reason === 'string' && card.reason.trim() !== '') {
+    if (denyReasonSnapshot !== undefined && denyReasonSnapshot.trim() !== '') {
         if (lane?.approvalDecisionNoteCapable !== true) {
-            hostLog('debug', `liveToolApprovalWire: ${frame.approvalId} card supplied a deny reason (len=${card.reason.length}) but the ` +
+            hostLog('debug', `liveToolApprovalWire: ${approvalId} card supplied a deny reason (len=${denyReasonSnapshot.length}) but the ` +
                 'approvalDecisionNote capability is not confirmed for this engine — note not sent (an unknown key would be ' +
                 'silently swallowed by an older server while still acking 200)');
         }
-        else if (card.reason.length > MAX_RESPOND_NOTE_CHARS) {
-            hostLog('debug', `liveToolApprovalWire: ${frame.approvalId} deny reason exceeds the decision_note cap ` +
-                `(len=${card.reason.length} > ${MAX_RESPOND_NOTE_CHARS}) — note not sent at all (the server rejects the WHOLE ` +
+        else if (denyReasonSnapshot.length > MAX_RESPOND_NOTE_CHARS) {
+            hostLog('debug', `liveToolApprovalWire: ${approvalId} deny reason exceeds the decision_note cap ` +
+                `(len=${denyReasonSnapshot.length} > ${MAX_RESPOND_NOTE_CHARS}) — note not sent at all (the server rejects the WHOLE ` +
                 'respond with 400 over an oversize note, and a silently halved audit reason is worse than none)');
         }
         else {
-            note = card.reason;
+            note = denyReasonSnapshot;
         }
     }
     try {
@@ -751,7 +794,7 @@ export async function surfaceToolApprovalFrameAndRespond(frame, respond, streamA
         const wantsTextArm = card.kind === 'allow' && typeof card.persistRule === 'string' && card.persistRule !== '';
         const wantsBatchArm = card.kind === 'allow' && card.persistRuleBatchOfferIndex !== undefined;
         if (wantsTextArm && wantsBatchArm) {
-            hostLog('error', `liveToolApprovalWire: DROPPING the whole persistRule arm for ${frame.approvalId} — the card returned BOTH a rule ` +
+            hostLog('error', `liveToolApprovalWire: DROPPING the whole persistRule arm for ${approvalId} — the card returned BOTH a rule ` +
                 'text and a batchOfferIndex; the server rejects that combination with a 400 that would take the decision down ' +
                 'with it, and picking one arm here would be deciding on the user\'s behalf (the decision itself still goes through)');
             ruleArmDroppedForCheck = true;
@@ -769,14 +812,14 @@ export async function surfaceToolApprovalFrameAndRespond(frame, respond, streamA
                     batchArmTarget = target;
                 }
                 else {
-                    hostLog('debug', `liveToolApprovalWire: DROPPING persistRuleBatchOfferIndex(${idx}) for ${frame.approvalId} — the ` +
+                    hostLog('debug', `liveToolApprovalWire: DROPPING persistRuleBatchOfferIndex(${idx}) for ${approvalId} — the ` +
                         'respondBatchRuleOffers capability is not confirmed for this engine, so the batch arm is not sent at all ' +
                         '(the decision itself still goes through unchanged; the offer stays on the card for local/display use)');
                     ruleArmDroppedForCaps = true;
                 }
             }
             else {
-                hostLog('error', `liveToolApprovalWire: DROPPING persistRuleBatchOfferIndex(${String(idx)}) for ${frame.approvalId} — that wire ` +
+                hostLog('error', `liveToolApprovalWire: DROPPING persistRuleBatchOfferIndex(${String(idx)}) for ${approvalId} — that wire ` +
                     'index is not a batch offer on this frame (out of range, a single offer, or not a non-negative integer); ' +
                     'never redeeming an index the engine did not offer as a batch');
                 ruleArmDroppedForCheck = true;
@@ -790,7 +833,7 @@ export async function surfaceToolApprovalFrameAndRespond(frame, respond, streamA
                     persistRuleEdited = true;
                 }
                 else {
-                    hostLog('debug', `liveToolApprovalWire: DROPPING edited persistRule for ${frame.approvalId} (len=${card.persistRule.length}) — the ` +
+                    hostLog('debug', `liveToolApprovalWire: DROPPING edited persistRule for ${approvalId} (len=${card.persistRule.length}) — the ` +
                         'respondFreeFormRules capability is not confirmed for this engine, so the free-form arm is not sent at all ' +
                         '(the decision itself still goes through unchanged)');
                     ruleArmDroppedForCaps = true;
@@ -800,22 +843,40 @@ export async function surfaceToolApprovalFrameAndRespond(frame, respond, streamA
                 persistRule = card.persistRule;
             }
             else {
-                hostLog('error', `liveToolApprovalWire: DROPPING persistRule for ${frame.approvalId} — the card returned a rule that is not among the frame's SINGLE offers (a batch member's text is not a selectable candidate either: a conjunction batch is redeemed by index, all-or-nothing) — never sending un-offered text to the rule store`);
+                hostLog('error', `liveToolApprovalWire: DROPPING persistRule for ${approvalId} — the card returned a rule that is not among the frame's SINGLE offers (a batch member's text is not a selectable candidate either: a conjunction batch is redeemed by index, all-or-nothing) — never sending un-offered text to the rule store`);
                 ruleArmDroppedForCheck = true;
             }
         }
-        const raw = await respond(frame.approvalId, decision, {
+        const respondOpts = {
             ...(signal && !signal.aborted ? { signal } : {}),
             ...(card.kind === 'allow' && card.updatedInput !== undefined ? { updatedInput: card.updatedInput } : {}),
             ...(persistRule !== undefined ? { persistRule } : {}),
             ...(persistRuleEdited !== undefined ? { persistRuleEdited } : {}),
             ...(persistRuleBatchOfferIndex !== undefined ? { persistRuleBatchOfferIndex } : {}),
             ...(note !== undefined ? { note } : {}),
-        });
+            ...(sentSettledBy ? { settledBy: 'policy' } : {}),
+        };
+        let attributionDropped = false;
+        let raw;
+        try {
+            raw = await respond(approvalId, decision, respondOpts);
+        }
+        catch (first) {
+            if (!shouldResendWithoutAttribution(first, lastSendCarriedAttribution, signal))
+                throw first;
+            const { settledBy: _droppedKey, ...withoutAttribution } = respondOpts;
+            void _droppedKey;
+            lastSendCarriedAttribution = false;
+            hostLog('debug', `liveToolApprovalWire: respond(deny) for ${approvalId} was refused because the settlement note is not part of ` +
+                'what this deployment signs — re-sending the SAME decision exactly once with that one key removed ' +
+                '(the refusal happened before the approval was judged, so nothing was consumed and this is a re-delivery, not a second act)');
+            raw = await respond(approvalId, decision, withoutAttribution);
+            attributionDropped = true;
+        }
         const parsed = readToolApprovalRespondAck(raw);
         let ack = parsed;
-        if (parsed !== undefined && (parsed.approvalId !== frame.approvalId || parsed.decision !== decision)) {
-            hostLog('error', `liveToolApprovalWire: DISCARDING respond ack for ${frame.approvalId} — it does not correlate ` +
+        if (parsed !== undefined && (parsed.approvalId !== approvalId || parsed.decision !== decision)) {
+            hostLog('error', `liveToolApprovalWire: DISCARDING respond ack for ${approvalId} — it does not correlate ` +
                 `(ack.approvalId=${parsed.approvalId} ack.decision=${parsed.decision}, sent decision=${decision}); ` +
                 'treating as "no ack" (unknown) — never surfacing a safety notice off an unrelated receipt');
             ack = undefined;
@@ -846,7 +907,7 @@ export async function surfaceToolApprovalFrameAndRespond(frame, respond, streamA
                 strayEchoes.push('persistedRuleAnchors');
             if (strayEchoes.length > 0) {
                 hostLog('error', `liveToolApprovalWire: DISCARDING persisted-rule echo(es) [${strayEchoes.join(', ')}] on the ack for ` +
-                    `${frame.approvalId} — they do not correlate with the persistence arm actually sent ` +
+                    `${approvalId} — they do not correlate with the persistence arm actually sent ` +
                     `(editedArm=${String(sentEditedArm)} batchArmMembers=${String(expectedBatchCount ?? 'none')} ` +
                     `sentOfferIndex=${String(persistRuleBatchOfferIndex ?? 'none')} ` +
                     `echoedRules=${String(ack.persistedRules?.length ?? 'none')} ` +
@@ -869,31 +930,39 @@ export async function surfaceToolApprovalFrameAndRespond(frame, respond, streamA
         if (ruleArmDroppedForCheck)
             surfaceRuleArmRejected();
         if (decision === 'allow_session' && ack?.rememberApplied === false) {
-            hostLog('debug', `liveToolApprovalWire: ${frame.approvalId} allow_session ack rememberApplied=false — grant not stored, surfacing honest notice`);
+            hostLog('debug', `liveToolApprovalWire: ${approvalId} allow_session ack rememberApplied=false — grant not stored, surfacing honest notice`);
             surfaceRememberNotApplied();
         }
-        if (card.kind === 'allow' && card.updatedInput !== undefined && ack?.updatedInputForwarded === false) {
-            hostLog('debug', `liveToolApprovalWire: ${frame.approvalId} edited args were NOT forwarded (ack.updatedInputForwarded=false) — the tool runs on the ORIGINAL input`);
+        if (respondOpts.updatedInput !== undefined && ack?.updatedInputForwarded === false) {
+            hostLog('debug', `liveToolApprovalWire: ${approvalId} edited args were NOT forwarded (ack.updatedInputForwarded=false) — the tool runs on the ORIGINAL input`);
             surfaceEditNotForwarded();
         }
         if (note !== undefined && ack !== undefined && ack.noteRecorded !== true) {
-            hostLog('debug', `liveToolApprovalWire: ${frame.approvalId} decision note was sent but not persisted ` +
+            hostLog('debug', `liveToolApprovalWire: ${approvalId} decision note was sent but not persisted ` +
                 `(ack.noteRecorded=${String(ack.noteRecorded)}) — decision stood; the audit note did not land on the ask row`);
         }
-        const denyAttribution = card.kind === 'deny'
+        const denyAttribution = decision === 'deny'
             ? {
-                ...((o) => (o !== undefined ? { denySettledBy: o } : {}))(readApprovalDenySettledBy(card)),
-                ...(typeof card.reason === 'string' && card.reason.trim() !== '' ? { denyReason: card.reason } : {}),
+                ...(attributionDropped ? { denyAttributionDropped: true } : {}),
+                ...(denySettledByForWire !== undefined ? { denySettledBy: denySettledByForWire } : {}),
+                ...(denyReasonSnapshot !== undefined && denyReasonSnapshot.trim() !== ''
+                    ? { denyReason: denyReasonSnapshot }
+                    : {}),
             }
             : {};
         return ack !== undefined ? { decision, ack, ...denyAttribution } : { decision, ...denyAttribution };
     }
     catch (e) {
         const respondRefusal = readToolApprovalRespondRefusal(e);
-        hostLog('debug', `liveToolApprovalWire: respond(${decision}) failed for ${frame.approvalId} ` +
+        const attributionRefusal = denyAttributionRefusalFromError(e, lastSendCarriedAttribution);
+        hostLog('debug', `liveToolApprovalWire: respond(${decision}) failed for ${approvalId} ` +
             `(status=${respondRefusal?.status ?? 'none'} errorCode=${logSafeErrorCode(respondRefusal?.errorCode)} ` +
             `messageLen=${respondRefusal?.message?.length ?? 0}) — engine self-settles (TTL/abort); ` +
             'the refusal text is handed back on outcome.respondRefusal for the host to surface');
-        return respondRefusal !== undefined ? { decision: 'unresolved', respondRefusal } : { decision: 'unresolved' };
+        return {
+            decision: 'unresolved',
+            ...(respondRefusal !== undefined ? { respondRefusal } : {}),
+            ...(attributionRefusal !== null ? { denyAttributionRefusal: attributionRefusal } : {}),
+        };
     }
 }

package/dist/index.d.ts

@@ -40,6 +40,7 @@ export * from './argvFlagValue.js';
 export * from './readFacePosture.js';
 export * from './mcpPanel.js';
 export * from './mcpLiveness.js';
+export * from './mcpEngineLeg.js';
 export * from './mcpProbeCapability.js';
 export * from './mcpProbeWire.js';
 export * from './effectiveFacts.js';
@@ -174,3 +175,4 @@ export * from './env/localeGeo.js';
 export * from './env/localeTag.js';
 export * from './env/uiLanguage.js';
 export type { PendingCheckpoint, RuleSuggestion } from '@sema-agent/sdk';
+export * from './ruleRemovalConsequence.js';

package/dist/index.js

@@ -40,6 +40,7 @@ export * from './argvFlagValue.js';
 export * from './readFacePosture.js';
 export * from './mcpPanel.js';
 export * from './mcpLiveness.js';
+export * from './mcpEngineLeg.js';
 export * from './mcpProbeCapability.js';
 export * from './mcpProbeWire.js';
 export * from './effectiveFacts.js';
@@ -171,3 +172,4 @@ export * from './websearch/searchProviderPresets.js';
 export * from './env/localeGeo.js';
 export * from './env/localeTag.js';
 export * from './env/uiLanguage.js';
+export * from './ruleRemovalConsequence.js';

package/dist/mcpEngineLeg.d.ts

@@ -0,0 +1,23 @@
+import type { WiringManifestMcpEntryView } from './adapter/downstream/eventToSdkMessage.js';
+export type McpEngineLegLiveness = {
+    kind: 'unobserved';
+} | {
+    kind: 'not-listed';
+} | {
+    kind: 'ambiguous';
+    rows: number;
+} | {
+    kind: 'unreadable';
+} | {
+    kind: 'absent';
+} | {
+    kind: 'observed';
+    state: string;
+};
+export declare function mcpEngineLegLivenessOf(serverName: string, rows: readonly WiringManifestMcpEntryView[] | null | undefined): McpEngineLegLiveness;
+export interface McpDetailLegNoteInput {
+    localClientFailed: boolean;
+    engineHostedToolCount: number | undefined;
+    liveness: McpEngineLegLiveness;
+}
+export declare function mcpDetailLegNote(input: McpDetailLegNoteInput): string | undefined;

package/dist/mcpEngineLeg.js

@@ -0,0 +1,135 @@
+import { isMcpLivenessState } from './mcpLiveness.js';
+void true;
+void true;
+void true;
+const MCP_LEG_ROSTER_SCAN_LIMIT = 4096;
+const ABSENT_CELL = Symbol('mcpEngineLeg.absent');
+const UNREADABLE_CELL = Symbol('mcpEngineLeg.unreadable');
+const readKey = (o, k) => {
+    if (o === null || typeof o !== 'object')
+        return ABSENT_CELL;
+    try {
+        if (!Object.hasOwn(o, k))
+            return ABSENT_CELL;
+        return o[k];
+    }
+    catch {
+        return UNREADABLE_CELL;
+    }
+};
+export function mcpEngineLegLivenessOf(serverName, rows) {
+    let isArray = false;
+    try {
+        isArray = Array.isArray(rows);
+    }
+    catch {
+        return { kind: 'unobserved' };
+    }
+    if (!isArray)
+        return { kind: 'unobserved' };
+    const len = readKey(rows, 'length');
+    if (typeof len !== 'number' || !Number.isInteger(len) || len < 0)
+        return { kind: 'unobserved' };
+    if (len > MCP_LEG_ROSTER_SCAN_LIMIT)
+        return { kind: 'unobserved' };
+    let first;
+    let matches = 0;
+    let incomplete = false;
+    for (let i = 0; i < len; i++) {
+        const r = readKey(rows, i);
+        if (r === UNREADABLE_CELL) {
+            incomplete = true;
+            continue;
+        }
+        if (r === null || typeof r !== 'object')
+            continue;
+        const nm = readKey(r, 'name');
+        if (nm === UNREADABLE_CELL) {
+            incomplete = true;
+            continue;
+        }
+        if (nm !== serverName)
+            continue;
+        matches++;
+        if (matches === 1)
+            first = r;
+    }
+    if (incomplete)
+        return { kind: 'unobserved' };
+    if (matches >= 2)
+        return { kind: 'ambiguous', rows: matches };
+    if (matches === 0)
+        return { kind: 'not-listed' };
+    const flag = readKey(first, 'livenessUnreadable');
+    if (flag === UNREADABLE_CELL || flag === true)
+        return { kind: 'unreadable' };
+    const cell = readKey(first, 'liveness');
+    if (cell === ABSENT_CELL)
+        return { kind: 'absent' };
+    if (cell === UNREADABLE_CELL || cell === null || typeof cell !== 'object')
+        return { kind: 'unreadable' };
+    const state = readKey(cell, 'state');
+    if (typeof state !== 'string' || state === '')
+        return { kind: 'unreadable' };
+    return { kind: 'observed', state };
+}
+const rosterReadingOf = (v) => {
+    if (v === UNREADABLE_CELL)
+        return 'unreadable';
+    if (v === ABSENT_CELL || v === undefined)
+        return 'silent';
+    if (typeof v !== 'number' || !Number.isInteger(v) || v < 0)
+        return 'unreadable';
+    return v > 0 ? 'listed' : 'zero';
+};
+const NOTE_ENGINE_REACHES = "This client's own connection is down; the engine still reaches it.";
+const NOTE_ENGINE_UNREACHABLE = "This client's own connection is down, and the engine could not reach it when it last looked.";
+const NOTE_ENGINE_CANNOT_TELL = "This client's own connection is down; the engine could not tell whether it reaches this server.";
+const NOTE_ENGINE_WORD_UNRECOGNISED = "This client's own connection is down; the engine reported a liveness state this client does not recognise.";
+const NOTE_LIVENESS_UNREADABLE = "This client's own connection is down; the engine sent a liveness record for this server that this client could not read.";
+const NOTE_ROSTER_LISTS_TOOLS = "This client's own connection is down; the engine listed this server's tools for the last run.";
+const NOTE_ENGINE_SILENT = "This status is this client's own connection. This client has neither a liveness reading nor a tool count from the engine for this server.";
+const NOTE_ROSTER_ZERO = "This status is this client's own connection. The engine reported no tools from this server either.";
+const NOTE_ROSTER_UNREADABLE = "This status is this client's own connection. The engine's tool roster for this server could not be read.";
+export function mcpDetailLegNote(input) {
+    const raw = input;
+    if (raw === null || typeof raw !== 'object')
+        return undefined;
+    if (readKey(raw, 'localClientFailed') !== true)
+        return undefined;
+    const lv = readKey(raw, 'liveness');
+    const kind = lv !== null && typeof lv === 'object' ? readKey(lv, 'kind') : undefined;
+    if (lv !== null && typeof lv === 'object' && kind === 'observed') {
+        const state = readKey(lv, 'state');
+        if (isMcpLivenessState(state)) {
+            switch (state) {
+                case 'reachable':
+                    return NOTE_ENGINE_REACHES;
+                case 'unreachable':
+                    return NOTE_ENGINE_UNREACHABLE;
+                case 'unknown':
+                    return NOTE_ENGINE_CANNOT_TELL;
+                default: {
+                    const exhaustive = state;
+                    void exhaustive;
+                    return NOTE_ENGINE_WORD_UNRECOGNISED;
+                }
+            }
+        }
+        if (typeof state === 'string' && state !== '')
+            return NOTE_ENGINE_WORD_UNRECOGNISED;
+        return NOTE_LIVENESS_UNREADABLE;
+    }
+    if (kind === 'unreadable')
+        return NOTE_LIVENESS_UNREADABLE;
+    switch (rosterReadingOf(readKey(raw, 'engineHostedToolCount'))) {
+        case 'listed':
+            return NOTE_ROSTER_LISTS_TOOLS;
+        case 'zero':
+            return NOTE_ROSTER_ZERO;
+        case 'unreadable':
+            return NOTE_ROSTER_UNREADABLE;
+        default:
+            return NOTE_ENGINE_SILENT;
+    }
+}

package/dist/mcpLiveness.d.ts

@@ -1,5 +1,6 @@
 export declare const MCP_LIVENESS_STATES: readonly ["reachable", "unreachable", "unknown"];
 export type McpLivenessState = (typeof MCP_LIVENESS_STATES)[number];
+export declare const isMcpLivenessState: (v: unknown) => v is McpLivenessState;
 export interface McpLivenessView {
     state: McpLivenessState;
     observedAt: number;

package/dist/mcpLiveness.js

@@ -2,7 +2,8 @@ export const MCP_LIVENESS_STATES = Object.freeze(['reachable', 'unreachable', 'u
 void MCP_LIVENESS_STATES;
 void true;
 void true;
-const isLivenessState = (v) => typeof v === 'string' && MCP_LIVENESS_STATES.includes(v);
+export const isMcpLivenessState = (v) => typeof v === 'string' && MCP_LIVENESS_STATES.includes(v);
+const isLivenessState = isMcpLivenessState;
 const isRecord = (v) => typeof v === 'object' && v !== null && !Array.isArray(v);
 export function readMcpLiveness(row) {
     if (!isRecord(row))

package/dist/ruleRemovalConsequence.d.ts

@@ -0,0 +1,3 @@
+export type RuleRemovalBehavior = 'allow' | 'deny' | 'ask' | undefined;
+export declare function removalConsequenceLineForBehavior(behavior: RuleRemovalBehavior): string;
+export declare function ruleRemovalBehaviorOf(raw: unknown): RuleRemovalBehavior;

package/dist/ruleRemovalConsequence.js

@@ -0,0 +1,15 @@
+export function removalConsequenceLineForBehavior(behavior) {
+    switch (behavior) {
+        case 'allow':
+            return 'Commands it covers will be asked about again.';
+        case 'deny':
+            return 'Commands it covers will no longer be refused by this rule — removing it widens what can run; it does not tighten anything.';
+        case 'ask':
+            return 'Commands it covers will no longer be held for approval by this rule.';
+        default:
+            return 'Whatever this rule does for the commands it covers will stop applying.';
+    }
+}
+export function ruleRemovalBehaviorOf(raw) {
+    return raw === 'allow' || raw === 'deny' || raw === 'ask' ? raw : undefined;
+}

package/dist/wireRefusalCopy.d.ts

@@ -14,3 +14,12 @@ export interface UsageWindowExhaustedDetail {
 }
 export declare function usageWindowExhaustedFromError(err: unknown): UsageWindowExhaustedDetail | null;
 export declare function usageWindowExhaustedContent(detail: UsageWindowExhaustedDetail): string;
+export type DenyAttributionRefusalKind = 'not_in_proof' | 'decision_conflict' | 'attribution_rejected';
+export interface DenyAttributionRefusalDetail {
+    kind: DenyAttributionRefusalKind;
+    code: string;
+    status: number;
+    field?: string;
+}
+export declare function denyAttributionRefusalFromError(err: unknown, sentSettledBy: boolean): DenyAttributionRefusalDetail | null;
+export declare function denyAttributionRefusalContent(detail: Pick<DenyAttributionRefusalDetail, 'kind' | 'field'>): string;