@sema-agent/server 7.150.0 → 7.151.0

package/dist/tool-approval.js

@@ -27,6 +27,7 @@ import { APPROVAL_EXEMPTED_EVENT } from "./plugins/approval-exemption-store.js";
 import { refusalBody } from "./http/refusal-body.js";
 import { withoutSettlementEvidence } from "./gate-settlement.js";
 import { extensionRequesterOf } from "./trace/extension-call-face.js";
+import { boundedRotation } from "./bounded-rotation.js";
 const defaultLogger = createLogger();
 const MAX_APPROVAL_ARGS_BYTES = 16384;
 const DEFAULT_APPROVAL_TTL_MS = 5 * 60_000;
@@ -69,7 +70,7 @@ function durableRuleMaterial(material) {
 }
 export const NOT_PENDING_UNKNOWN_CAUSE = "unknown_or_other_replica";
 export const TOOL_APPROVAL_READ_STATES = ["pending", "decided", "parked", "void"];
-function decidedRowFacts(row) {
+export function decidedRowFacts(row) {
     if (row.state !== "DECIDED" || (row.decision !== "approve" && row.decision !== "deny") || row.provisional || row.decidedAtMs === null)
         return undefined;
     return { decision: row.decision === "approve" ? "allow" : "deny", decidedAtMs: row.decidedAtMs, ...(row.decisionNote !== null ? { decisionNote: row.decisionNote } : {}) };
@@ -85,6 +86,22 @@ function buildAskRowReadProjection(row, nowMs) {
     };
 }
 export const ASK_DECISION_CONSUMER_ABSENT = "absent";
+function standingParkedDecision(gate, row, idempotencyKey) {
+    if (gate?.kind !== "decided")
+        return undefined;
+    const decision = gate.decision === "allow" ? "approve" : "deny";
+    if (row.decision === decision && row.decidedAtMs !== null && row.decidedAtMs >= gate.decidedAtMs) {
+        return {
+            kind: "standing",
+            decision,
+            decidedAtMs: row.decidedAtMs,
+            ...(row.decisionNote !== null ? { decisionNote: row.decisionNote } : {}),
+            ...(row.decisionActor !== null ? { actor: row.decisionActor } : {}),
+            byThisRequest: idempotencyKey !== undefined && row.idempotencyKey === idempotencyKey,
+        };
+    }
+    return { kind: "standing", decision, decidedAtMs: gate.decidedAtMs, ...(gate.decisionNote !== undefined ? { decisionNote: gate.decisionNote } : {}), byThisRequest: false };
+}
 const MAX_INFLIGHT_TERMINAL_CLAIMS = 2;
 const DURABLE_CONVERGE_BACKOFF_MS = [50, 100, 200, 400, 800, 1600];
 export const DURABLE_CONVERGE_READ_TIMEOUT_MS = 2_000;
@@ -378,6 +395,18 @@ function parseToolApprovalFields(body, retired) {
     }
     return { ok: false, error: 'decision must be one of "allow" | "allow_session" | "deny"' };
 }
+export function askDecisionRecordOf(write) {
+    return {
+        decision: write.decision,
+        ...(write.actor !== undefined ? { decisionActor: write.actor } : {}),
+        decisionNote: write.note ?? null,
+        idempotencyKey: write.idempotencyKey ?? null,
+        ...liveHostSource(write.decider),
+    };
+}
+function liveDecideInputOf(write) {
+    return { ...askDecisionRecordOf(write), ...(write.decision === "approve" && write.updatedInput !== undefined ? { updatedInput: write.updatedInput } : {}) };
+}
 export function buildUnattendedPolicyRefusal(reason) {
     return { allow: false, settledBy: POLICY_REFUSAL_DECISION.settledBy, reason };
 }
@@ -562,8 +591,8 @@ export class ToolApprovalCoordinator {
     admitMaxPerOwner;
     admitByTask = new Map();
     admitByOwner = new Map();
-    suspendedPollOffset = 0;
-    adoptedPollOffset = 0;
+    suspendedPollCursor = { offset: 0 };
+    adoptedPollCursor = { offset: 0 };
     editedDecisionsInFlight = new Map();
     storeErrorWarned = false;
     storeErrorTally = 0;
@@ -2460,21 +2489,50 @@ export class ToolApprovalCoordinator {
         const openGenerationNow = this.lookupParkRedemption(row.askId) !== undefined ? await this.openGateGeneration(row) : undefined;
         const prior = this.lookupParkRedemption(row.askId);
         if (prior?.redeemed !== undefined && receiptAnswersNow(prior.redeemed.gateGeneration, openGenerationNow))
-            return this.replayRedeemReceipt(id, prior, row, prior.redeemed, parsed);
+            return this.replayRedeemReceipt(id, prior, row, prior.redeemed, parsed, row);
         if (prior?.inflight !== undefined) {
             const shared = await prior.inflight;
             if (shared.status < 200 || shared.status >= 300)
                 return shared;
             if (!receiptAnswersNow(shared.gateGeneration, openGenerationNow))
                 return this.redeemParkedAsk(id, row, parsed, httpReq, principal);
-            return this.replayRedeemReceipt(id, prior, row, { decision: shared.decision, body: shared.body, gateGeneration: shared.gateGeneration, ...(shared.rule?.terminal === true ? { rule: shared.rule.body } : {}) }, parsed);
+            return this.replayRedeemReceipt(id, prior, row, { decision: shared.decision, body: shared.body, gateGeneration: shared.gateGeneration, ...(shared.rule?.terminal === true ? { rule: shared.rule.body } : {}) }, parsed, shared.recorded ?? { decisionNote: null });
         }
+        const store = this.askStore;
+        if (store === undefined)
+            return this.notPending();
+        const request = {
+            write: { decision: parsed.value === "deny" ? "deny" : "approve", decider: parsed.decider, ...(parsed.note !== undefined ? { note: parsed.note } : {}) },
+            ...(parsed.value === "allow_session" ? { remember: "session" } : {}),
+            ...(parsed.persistRule !== undefined ? { persistRule: parsed.persistRule } : {}),
+            ...(parsed.updatedInput !== undefined && parsed.value !== "deny" ? { updatedInput: parsed.updatedInput } : {}),
+            ...(principal !== undefined ? { principal } : {}),
+            operator: false,
+            ...(httpReq !== undefined ? { httpReq } : {}),
+        };
+        const out = await this.runParkedFlight(redeem, store, row, row.gateToken, request);
+        if (out.status < 200 || out.status >= 300)
+            return { status: out.status, body: out.body };
+        const rule = out.rule;
+        return {
+            status: out.status,
+            body: {
+                ...out.body,
+                approvalId: id,
+                askId: row.askId,
+                accepted: "parked_redeemed",
+                ...(parsed.value === "allow_session" ? { rememberApplied: out.rememberApplied === true } : {}),
+                ...noteRecordedReceipt(parsed.note, noteLandedOnRow(parsed.note, out.recorded?.decisionNote ?? null)),
+                ...(rule?.body ?? {}),
+            },
+        };
+    }
+    async runParkedFlight(redeem, store, row, gateToken, request) {
+        const decision = request.write.decision;
         const admission = this.parkRedemptionAdmission(row.owner);
         if (admission !== undefined)
-            return admission;
+            return { ...admission, body: admission.body, decision };
         const memo = this.openParkRedemption(row.askId, row.owner);
-        const decision = parsed.value === "deny" ? "deny" : "approve";
-        const gateToken = row.gateToken;
         const flight = (async () => {
             let res;
             try {
@@ -2484,12 +2542,13 @@ export class ToolApprovalCoordinator {
                     gateBoundCallId: row.gateBoundCallId,
                     gateBoundInputHash: row.gateBoundInputHash,
                     decision,
-                    ...(parsed.note !== undefined ? { note: parsed.note } : {}),
-                    decider: parsed.decider,
-                    ...(parsed.updatedInput !== undefined && parsed.value !== "deny" ? { updatedInput: parsed.updatedInput } : {}),
-                    ...(parsed.value === "allow_session" ? { remember: "session" } : {}),
-                    ...(principal !== undefined ? { principal } : {}),
-                    ...(httpReq !== undefined ? { httpReq } : {}),
+                    ...(request.write.note !== undefined ? { note: request.write.note } : {}),
+                    decider: request.write.decider,
+                    ...(request.updatedInput !== undefined && decision === "approve" ? { updatedInput: request.updatedInput } : {}),
+                    ...(request.remember !== undefined ? { remember: request.remember } : {}),
+                    ...(request.principal !== undefined ? { principal: request.principal } : {}),
+                    operator: request.operator,
+                    ...(request.httpReq !== undefined ? { httpReq: request.httpReq } : {}),
                 });
             }
             catch (err) {
@@ -2498,8 +2557,9 @@ export class ToolApprovalCoordinator {
             }
             if (res.status < 200 || res.status >= 300)
                 return { ...res, decision };
-            const rule = await this.persistRuleFromRow(row, parsed);
-            return { ...res, decision, ...(rule !== undefined ? { rule } : {}) };
+            const recorded = await this.recordParkedOutcome(store, row, request.write);
+            const rule = await this.persistRuleFromRow(row, request.persistRule, request.updatedInput !== undefined);
+            return { ...res, decision, ...(recorded !== undefined ? { recorded } : {}), ...(rule !== undefined ? { rule } : {}) };
         })();
         memo.inflight = flight;
         let out;
@@ -2512,25 +2572,57 @@ export class ToolApprovalCoordinator {
         if (out.status < 200 || out.status >= 300) {
             if (this.parkRedemptions.get(row.askId) === memo)
                 this.parkRedemptions.delete(row.askId);
-            return { status: out.status, body: out.body };
+            return out;
         }
-        const rule = out.rule;
         if (this.retainParkRedemption(row.askId, memo))
-            memo.redeemed = { decision, body: out.body, gateGeneration: out.gateGeneration, ...(rule?.terminal === true ? { rule: rule.body } : {}) };
-        return {
-            status: out.status,
-            body: {
-                ...out.body,
-                approvalId: id,
-                askId: row.askId,
-                accepted: "parked_redeemed",
-                ...(parsed.value === "allow_session" ? { rememberApplied: out.rememberApplied === true } : {}),
-                ...(rule?.body ?? {}),
-            },
-        };
+            memo.redeemed = { decision, body: out.body, gateGeneration: out.gateGeneration, ...(out.rule?.terminal === true ? { rule: out.rule.body } : {}) };
+        return out;
     }
-    async persistRuleFromRow(row, parsed) {
-        const persistRule = parsed.persistRule;
+    async recordParkedOutcome(store, row, write) {
+        try {
+            const out = await this.writeAskDecision(store, row.askId, { kind: "parked" }, row.owner, write);
+            if (out.ok)
+                return out.row;
+            recordFailOpen("server.approval.parked-decision-not-recorded", `askId=${row.askId} reason=${out.reason}`);
+            return undefined;
+        }
+        catch (err) {
+            this.noteStoreError(err, "recordParkedDecision");
+            recordFailOpen("server.approval.parked-decision-not-recorded", `askId=${row.askId} reason=store_error`);
+            return undefined;
+        }
+    }
+    async decideParkedAsk(store, row, request, idempotencyKey) {
+        for (;;) {
+            const gate = await this.readParkedGate(row);
+            const current = await this.askRowFor(store, row.askId, "getAsk(parked-decision)");
+            if (current === null || current.state !== "PARKED" || !askRowCarriesOwner(current, row.owner))
+                return { kind: "gone" };
+            const inflight = this.lookupParkRedemption(row.askId)?.inflight;
+            if (inflight !== undefined) {
+                await inflight;
+                continue;
+            }
+            const standing = standingParkedDecision(gate, current, idempotencyKey);
+            if (standing !== undefined)
+                return standing;
+            if (request.write.decision === "approve" && request.policyMayNotApprove === true)
+                return { kind: "policy_refused" };
+            const redeem = this.parkedRedeem?.();
+            if (redeem === undefined || row.gateToken === null) {
+                if (row.gateToken === null)
+                    defaultLogger.error("tool approval parked row carries no gate token — nothing to redeem", { askId: row.askId });
+                return { kind: "gate_only" };
+            }
+            const out = await this.runParkedFlight(redeem, store, current, row.gateToken, request);
+            if (out.status === 200)
+                return { kind: "accepted", body: out.body, ...(out.recorded !== undefined ? { recorded: out.recorded } : {}) };
+            if ((await this.readParkedGate(row))?.kind === "decided")
+                continue;
+            return { kind: "refused", status: out.status, body: out.body };
+        }
+    }
+    async persistRuleFromRow(row, persistRule, inputWasEdited) {
         if (persistRule === undefined)
             return undefined;
         const flag = (rulePersisted, ruleRefusal, echo) => ({
@@ -2550,7 +2642,7 @@ export class ToolApprovalCoordinator {
         const command = row.ruleCommand;
         if (command === null)
             return flag(false, "rule_material_absent");
-        if (parsed.updatedInput !== undefined)
+        if (inputWasEdited)
             return flag(false, "rule_input_edited");
         const offers = card.ruleOffers ?? [];
         const scope = row.ruleScopeRoot !== null ? { kind: "project", root: row.ruleScopeRoot } : undefined;
@@ -2607,10 +2699,10 @@ export class ToolApprovalCoordinator {
             return { ...flag(false, "rule_store_error"), terminal: false };
         }
     }
-    async replayRedeemReceipt(id, memo, row, receipt, parsed) {
+    async replayRedeemReceipt(id, memo, row, receipt, parsed, recordedNote) {
         let rule = receipt.decision === "approve" ? receipt.rule : this.lateRuleRefusal(parsed);
         if (receipt.decision === "approve" && rule === undefined && parsed.persistRule !== undefined) {
-            const flight = memo.ruleInflight ?? this.persistRuleFromRow(row, parsed);
+            const flight = memo.ruleInflight ?? this.persistRuleFromRow(row, parsed.persistRule, parsed.updatedInput !== undefined);
             const isOwner = memo.ruleInflight === undefined;
             if (isOwner)
                 memo.ruleInflight = flight;
@@ -2636,6 +2728,7 @@ export class ToolApprovalCoordinator {
                 accepted: "parked_redeemed",
                 idempotent: true,
                 decision: receipt.decision === "approve" ? "allow" : "deny",
+                ...noteRecordedReceipt(parsed.note, noteLandedOnRow(parsed.note, recordedNote.decisionNote)),
                 ...(rule ?? {}),
             },
         };
@@ -2719,19 +2812,36 @@ export class ToolApprovalCoordinator {
             return withFlag(false, "rule_store_error");
         }
     }
+    writeAskDecision(store, askId, form, owner, write) {
+        switch (form.kind) {
+            case "live":
+                return this.withStoreDeadline(store.decideAsk(askId, form.batchId, owner, liveDecideInputOf(write)), "decideAsk", DURABLE_CALL_TIMEOUT_MS, (late) => {
+                    if (!late.ok)
+                        return;
+                    if (decidedRowFacts(late.row) === undefined) {
+                        defaultLogger.error("ask decision landed after its deadline on a row that is not an authoritative human decision — not settled", { askId, state: late.row.state, provisional: late.row.provisional });
+                        return;
+                    }
+                    this.notifyExternalDecision(askId, outcomeOfDecidedRow(late.row));
+                });
+            case "parked":
+                return this.withStoreDeadline(store.recordParkedDecision(askId, owner, askDecisionRecordOf(write)), "recordParkedDecision", DURABLE_CALL_TIMEOUT_MS);
+            default: {
+                const unhandled = form;
+                throw new Error(`writeAskDecision: unhandled form ${JSON.stringify(unhandled)}`);
+            }
+        }
+    }
     async respondWithCas(askStore, askId, batchId, owner, entry, parsed, ruleEligibility) {
         let winnerRow;
         let ambiguousConfirmedRow;
         let noteLanded = false;
         try {
-            const decided = await this.withStoreDeadline(askStore.decideAsk(askId, batchId, owner, {
+            const decided = await this.writeAskDecision(askStore, askId, { kind: "live", batchId }, owner, {
                 decision: parsed.value === "deny" ? "deny" : "approve",
-                ...(parsed.note !== undefined ? { decisionNote: parsed.note } : {}),
-                ...(parsed.value !== "deny" && parsed.updatedInput !== undefined ? { updatedInput: parsed.updatedInput } : {}),
-                ...liveHostSource(parsed.decider),
-            }), "decideAsk", DURABLE_CALL_TIMEOUT_MS, (late) => {
-                if (late.ok)
-                    this.notifyExternalDecision(askId, outcomeOfDecidedRow(late.row));
+                decider: parsed.decider,
+                ...(parsed.note !== undefined ? { note: parsed.note } : {}),
+                ...(parsed.updatedInput !== undefined ? { updatedInput: parsed.updatedInput } : {}),
             });
             if (decided.ok) {
                 winnerRow = decided.row;
@@ -3046,28 +3156,11 @@ export class ToolApprovalCoordinator {
                 continue;
             seen.add(entry.askId);
         }
-        const waitingStart = waiting.length > 0 ? this.suspendedPollOffset % waiting.length : 0;
-        const adoptedStart = adopted.length > 0 ? this.adoptedPollOffset % adopted.length : 0;
-        const ordered = [
-            ...[...waiting.slice(waitingStart), ...waiting.slice(0, waitingStart)].map((askId) => ({ askId, tier: "waiting" })),
-            ...[...adopted.slice(adoptedStart), ...adopted.slice(0, adoptedStart)].map((askId) => ({ askId, tier: "adopted" })),
-        ];
-        const deadlineMs = Date.now() + SUSPENDED_POLL_BUDGET_MS;
         let settled = 0;
-        let polled = 0;
-        let polledWaiting = 0;
-        let polledAdopted = 0;
-        let truncated = false;
-        for (const { askId, tier } of ordered) {
-            if (polled >= SUSPENDED_POLL_MAX_PER_TICK || Date.now() >= deadlineMs) {
-                truncated = true;
-                break;
-            }
-            polled++;
-            if (tier === "waiting")
-                this.suspendedPollOffset = waitingStart + ++polledWaiting;
-            else
-                this.adoptedPollOffset = adoptedStart + ++polledAdopted;
+        const { visited: polled, truncated } = await boundedRotation([
+            { items: waiting, cursor: this.suspendedPollCursor },
+            { items: adopted, cursor: this.adoptedPollCursor },
+        ], { maxPerTick: SUSPENDED_POLL_MAX_PER_TICK, budgetMs: SUSPENDED_POLL_BUDGET_MS }, async (askId) => {
             let row;
             const readSeq = this.nextRowReadSeq();
             try {
@@ -3075,24 +3168,24 @@ export class ToolApprovalCoordinator {
             }
             catch (err) {
                 this.noteStoreError(err, "getAsk(poll-suspended)");
-                continue;
+                return;
             }
             if (row === null) {
                 this.forgetAdoptedAsk(askId);
-                continue;
+                return;
             }
             if (row.state === "STREAM_PENDING") {
                 this.followRowOwner(askId, row.owner, readSeq);
-                continue;
+                return;
             }
             if (this.editedDecisionInFlight(askId))
-                continue;
+                return;
             const endingCause = askRowEndingCause(row);
             if (endingCause !== undefined) {
                 const before = this.waitingRegistrationCount(askId);
                 this.settleVoidedSiblings([askId], endingCause);
                 settled += before;
-                continue;
+                return;
             }
             const outcome = replayTerminalAskRow(row);
             if (outcome === "unavailable") {
@@ -3100,11 +3193,11 @@ export class ToolApprovalCoordinator {
                 const parkCause = askRowParkTrigger(row) ?? (Date.now() >= row.expiresAtMs ? APPROVAL_ENDING_CAUSES.TTL_EXPIRED : APPROVAL_ENDING_CAUSES.SHUTDOWN_BEFORE_PARK);
                 this.settleSameAskIdParkRoute(askId, parkCause);
                 settled += before;
-                continue;
+                return;
             }
             const delivered = this.notifyExternalDecision(askId, outcome).settled;
             settled += delivered;
-        }
+        });
         const backlog = Math.max(0, waiting.length + adopted.length - polled);
         if (truncated) {
             defaultLogger.warn("approval_suspended_poll_truncated", {
@@ -3113,8 +3206,8 @@ export class ToolApprovalCoordinator {
                 backlog,
                 maxPerTick: SUSPENDED_POLL_MAX_PER_TICK,
                 budgetMs: SUSPENDED_POLL_BUDGET_MS,
-                resumeFromOffset: this.suspendedPollOffset,
-                resumeAdoptedFromOffset: this.adoptedPollOffset,
+                resumeFromOffset: this.suspendedPollCursor.offset,
+                resumeAdoptedFromOffset: this.adoptedPollCursor.offset,
             });
         }
         return { polled, settled, backlog, truncated };