@agentic-kit/run-log 0.2.0 → 0.3.0

package/projectors/tool-state.js

@@ -10,17 +10,31 @@
  * same — the cloud already treats the conversation as the approval UI.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.approvalResolutionMessage = exports.approvalRequestMessage = exports.APPROVAL_RESOLUTION_TYPE = exports.APPROVAL_REQUEST_TYPE = void 0;
+exports.approvalResolutionMessage = exports.gateDecisionMessage = exports.approvalRequestMessage = exports.GATE_DECISION_TYPE = exports.APPROVAL_RESOLUTION_TYPE = exports.APPROVAL_REQUEST_TYPE = void 0;
 exports.projectToolState = projectToolState;
+exports.assertGateDecisionDetails = assertGateDecisionDetails;
+exports.assertApprovalRequestDetails = assertApprovalRequestDetails;
+exports.assertApprovalResolutionDetails = assertApprovalResolutionDetails;
 const pi_entry_1 = require("../pi-entry");
 /** `customType` of an approval request written by the gate extension. */
 exports.APPROVAL_REQUEST_TYPE = 'constructive.approval.request';
 /** `customType` of the human's answer to a request. */
 exports.APPROVAL_RESOLUTION_TYPE = 'constructive.approval.resolution';
+/**
+ * `customType` of a settled gate decision.
+ *
+ * Unlike an approval, this is written for *every* decision including the ones
+ * no human saw: a policy rule that denies a tool call is otherwise invisible in
+ * the log, leaving "which tool calls did the gate block" unanswerable.
+ */
+exports.GATE_DECISION_TYPE = 'constructive.gate.decision';
+/** Where a bad entry is, when the caller is projecting a log rather than validating one value. */
+const at = (seq) => (seq === undefined ? '' : ` at seq ${String(seq)}`);
 const details = (value) => typeof value === 'object' && value !== null ? value : {};
 function projectToolState(records) {
     const tools = {};
     const approvals = new Map();
+    const gateDecisions = {};
     for (const { entry, seq } of records) {
         if (!(0, pi_entry_1.isPiMessageEntry)(entry))
             continue;
@@ -60,11 +74,7 @@ function projectToolState(records) {
         if (message.role !== 'custom')
             continue;
         if (message.customType === exports.APPROVAL_REQUEST_TYPE) {
-            const info = details(message.details);
-            const toolCallId = typeof info.toolCallId === 'string' ? info.toolCallId : null;
-            if (!toolCallId) {
-                throw new Error(`approval request at seq ${String(seq)} carries no toolCallId; the run log cannot attribute it`);
-            }
+            const { toolCallId } = assertApprovalRequestDetails(message.details, seq);
             const approval = {
                 toolCallId,
                 requestedSeq: seq,
@@ -77,19 +87,16 @@ function projectToolState(records) {
             continue;
         }
         if (message.customType === exports.APPROVAL_RESOLUTION_TYPE) {
-            const info = details(message.details);
-            const toolCallId = typeof info.toolCallId === 'string' ? info.toolCallId : null;
-            if (!toolCallId) {
-                throw new Error(`approval resolution at seq ${String(seq)} carries no toolCallId; the run log cannot attribute it`);
-            }
+            const info = assertApprovalResolutionDetails(message.details, seq);
+            const toolCallId = info.toolCallId;
             const approved = info.decision === 'approved';
             const existing = approvals.get(toolCallId);
             const approval = {
                 ...(existing ?? { toolCallId, requestedSeq: seq, prompt: '' }),
                 resolvedSeq: seq,
-                decision: approved ? 'approved' : 'rejected',
-                ...(typeof info.reason === 'string' ? { reason: info.reason } : {}),
-                ...(typeof info.actorId === 'string' ? { actorId: info.actorId } : {})
+                decision: info.decision,
+                ...(info.reason === undefined ? {} : { reason: info.reason }),
+                ...(info.actorId === undefined ? {} : { actorId: info.actorId })
             };
             approvals.set(toolCallId, approval);
             const state = tools[toolCallId];
@@ -99,12 +106,72 @@ function projectToolState(records) {
             else if (state) {
                 tools[toolCallId] = { ...state, approval };
             }
+            continue;
+        }
+        if (message.customType === exports.GATE_DECISION_TYPE) {
+            const decision = assertGateDecisionDetails(message.details, seq);
+            gateDecisions[decision.toolCallId] = { ...decision, seq };
+            const state = tools[decision.toolCallId];
+            // A blocked call never produces a tool result, so the gate's `deny` is the
+            // only thing that will ever settle it.
+            if (state && decision.decision === 'deny' && state.settledSeq === undefined) {
+                tools[decision.toolCallId] = {
+                    ...state,
+                    status: 'rejected',
+                    settledSeq: seq,
+                    ...(decision.reason === undefined ? {} : { output: decision.reason })
+                };
+            }
         }
     }
     const pendingApprovals = Array.from(approvals.values())
         .filter((approval) => approval.resolvedSeq === undefined)
         .sort((a, b) => a.requestedSeq - b.requestedSeq);
-    return { tools, pendingApprovals };
+    return { tools, gateDecisions, pendingApprovals };
+}
+/** Narrow the `details` of a `constructive.gate.decision` entry. */
+function assertGateDecisionDetails(value, seq) {
+    const info = details(value);
+    const toolCallId = typeof info.toolCallId === 'string' ? info.toolCallId : null;
+    if (!toolCallId) {
+        throw new TypeError(`gate decision${at(seq)} carries no toolCallId; the run log cannot attribute it`);
+    }
+    if (info.decision !== 'allow' && info.decision !== 'deny') {
+        throw new TypeError(`gate decision${at(seq)} must settle to "allow" or "deny"`);
+    }
+    return {
+        toolCallId,
+        toolName: typeof info.toolName === 'string' ? info.toolName : '',
+        verdict: typeof info.verdict === 'string' ? info.verdict : info.decision,
+        decision: info.decision,
+        ...(typeof info.reason === 'string' ? { reason: info.reason } : {}),
+        ...(typeof info.actorId === 'string' ? { actorId: info.actorId } : {}),
+        ...(typeof info.decidedAt === 'string' ? { decidedAt: info.decidedAt } : {})
+    };
+}
+/** Narrow the `details` of a `constructive.approval.request` entry. */
+function assertApprovalRequestDetails(value, seq) {
+    const info = details(value);
+    if (typeof info.toolCallId !== 'string' || info.toolCallId.length === 0) {
+        throw new TypeError(`approval request${at(seq)} carries no toolCallId; the run log cannot attribute it`);
+    }
+    return { toolCallId: info.toolCallId };
+}
+/** Narrow the `details` of a `constructive.approval.resolution` entry. */
+function assertApprovalResolutionDetails(value, seq) {
+    const info = details(value);
+    if (typeof info.toolCallId !== 'string' || info.toolCallId.length === 0) {
+        throw new TypeError(`approval resolution${at(seq)} carries no toolCallId; the run log cannot attribute it`);
+    }
+    if (info.decision !== 'approved' && info.decision !== 'rejected') {
+        throw new TypeError(`approval resolution${at(seq)} must decide "approved" or "rejected"`);
+    }
+    return {
+        toolCallId: info.toolCallId,
+        decision: info.decision,
+        ...(typeof info.reason === 'string' ? { reason: info.reason } : {}),
+        ...(typeof info.actorId === 'string' ? { actorId: info.actorId } : {})
+    };
 }
 /** Build the pi `custom` message an approval request is carried in. */
 const approvalRequestMessage = (input) => ({
@@ -116,6 +183,26 @@ const approvalRequestMessage = (input) => ({
     timestamp: Date.now()
 });
 exports.approvalRequestMessage = approvalRequestMessage;
+/** Build the pi `custom` message a settled gate decision is carried in. */
+const gateDecisionMessage = (input) => ({
+    role: 'custom',
+    customType: exports.GATE_DECISION_TYPE,
+    content: `gate ${input.decision}: ${input.toolName}${input.reason ? ` — ${input.reason}` : ''}`,
+    // The model already learned of a denial through the blocked call's error; a
+    // second telling would only spend context.
+    display: false,
+    details: {
+        toolCallId: input.toolCallId,
+        toolName: input.toolName,
+        verdict: input.verdict,
+        decision: input.decision,
+        ...(input.reason ? { reason: input.reason } : {}),
+        ...(input.actorId ? { actorId: input.actorId } : {}),
+        ...(input.decidedAt ? { decidedAt: input.decidedAt } : {})
+    },
+    timestamp: Date.now()
+});
+exports.gateDecisionMessage = gateDecisionMessage;
 /** Build the pi `custom` message a human's answer is carried in. */
 const approvalResolutionMessage = (input) => ({
     role: 'custom',