agentfootprint 9.18.0 → 9.19.0

package/dist/core/agent/stages/toolCalls.js

@@ -45,6 +45,7 @@
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.buildToolCallsHandler = void 0;
+const footprintjs_1 = require("footprintjs");
 const types_js_1 = require("../../../adapters/types.js");
 const typedEmit_js_1 = require("../../../recorders/core/typedEmit.js");
 const extractSequence_js_1 = require("../../../security/extractSequence.js");
@@ -60,6 +61,7 @@ const toolArgsValidation_js_1 = require("../toolArgsValidation.js");
 const validators_js_1 = require("../validators.js");
 const toolResultCap_js_1 = require("../toolResultCap.js");
 const skillSteps_js_1 = require("../../../lib/injection-engine/skillSteps.js");
+const toolEffects_js_1 = require("../toolEffects.js");
 /** Declaration order preserved, ids de-duplicated — the shape the gate's re-prompt
  *  and the `skill.rejected` payload both report as "what this gate accepts". */
 function dedupeIds(ids) {
@@ -351,6 +353,195 @@ function buildToolCallsHandler(deps) {
         const plan = deps.stepPlanFor?.(pickedId);
         return plan ? (0, skillSteps_js_1.readSkillStepIntro)(plan) : '';
     };
+    // ── Escalate-on-evidence (9.19.0) — the refusal budget ─────────────────
+    // Called beside BOTH `skill.rejected` emit sites (reachability + posture):
+    // real recorded refusals are the only evidence that counts. At the
+    // declared threshold the flip is committed (`skillEscalated` — the fact
+    // callLLM's brainFor reads) and `skill.escalated` fires ONCE; the counter
+    // keeps counting so the record shows the whole loop. Gated on the policy
+    // being declared — otherwise not one key is read or written.
+    const noteSkillRefusal = (scope, iteration) => {
+        const escalation = deps.escalation;
+        if (!escalation)
+            return;
+        const refusals = (scope.skillRefusalsThisTurn ?? 0) + 1;
+        scope.skillRefusalsThisTurn = refusals;
+        if (refusals >= escalation.afterRefusals && scope.skillEscalated !== true) {
+            scope.skillEscalated = true;
+            (0, typedEmit_js_1.typedEmit)(scope, 'agentfootprint.skill.escalated', {
+                iteration,
+                afterRefusals: escalation.afterRefusals,
+                refusals,
+                from: escalation.describeFrom(scope.currentSkillId, scope.resolvedModel),
+                to: escalation.to,
+            });
+        }
+    };
+    const warnEffect = (toolName, sentence) => {
+        if ((0, footprintjs_1.isDevMode)()) {
+            // eslint-disable-next-line no-console
+            console.warn(`agentfootprint tool-effects: tool '${toolName}' — ${sentence}`);
+        }
+    };
+    /**
+     * Judge one finalized result's effects, in declaration order. Returns the
+     * model-visible NOTE (teaching refusals only — an accepted effect speaks
+     * through what it does: the cursor move, the delivered instruction).
+     * Every judgment is a `tools.effect` event; nothing is half-applied.
+     */
+    const applyToolEffects = (scope, call, envelope, state) => {
+        let note = '';
+        const refuse = (kind, refusalReason, fields = {}) => {
+            (0, typedEmit_js_1.typedEmit)(scope, 'agentfootprint.tools.effect', {
+                kind,
+                outcome: 'refused',
+                toolName: call.toolName,
+                toolCallId: call.toolCallId,
+                iteration: call.iteration,
+                ...(fields.targetSkillId !== undefined && { targetSkillId: fields.targetSkillId }),
+                ...(fields.reason !== undefined && { reason: fields.reason }),
+                ...(fields.instructionId !== undefined && { instructionId: fields.instructionId }),
+                ...(fields.deliveryLease !== undefined && { deliveryLease: fields.deliveryLease }),
+                refusalReason,
+            });
+            note += ` [tool effect refused: ${refusalReason}]`;
+            warnEffect(call.toolName, refusalReason);
+        };
+        for (const bad of envelope.malformed)
+            refuse(bad.kind, bad.refusalReason);
+        for (const effect of envelope.effects) {
+            if (effect.kind === 'propose-transition') {
+                const target = effect.targetSkillId;
+                if (!deps.allowedSkillIds) {
+                    refuse('propose-transition', `propose-transition → '${target}' needs a mounted skill graph: without one there ` +
+                        `is no routing law to check the proposal against and no cursor to move. Mount ` +
+                        `.skillGraph(), or drop the effect.`, { targetSkillId: target, reason: effect.reason });
+                    continue;
+                }
+                const currentSkillId = scope.currentSkillId;
+                const hops = deps.allowedSkillIds(currentSkillId);
+                if (!hops.includes(target)) {
+                    refuse('propose-transition', `propose-transition → '${target}' was refused: '${target}' is not reachable from ` +
+                        `${currentSkillId !== undefined ? `'${currentSkillId}'` : 'the turn start'} per ` +
+                        `the graph's own law${hops.length > 0 ? ` (reachable: ${hops.join(', ')})` : ''}. The graph decides — a proposal is evidence, never authority.`, { targetSkillId: target, reason: effect.reason });
+                    continue;
+                }
+                if (state.winner !== undefined && state.winner.targetSkillId !== target) {
+                    // A later proposal to a DIFFERENT target — suppressed under the
+                    // route_conflict law (first in call order wins), on the record.
+                    state.losers.push({
+                        toolCallId: call.toolCallId,
+                        toolName: call.toolName,
+                        target,
+                    });
+                    (0, typedEmit_js_1.typedEmit)(scope, 'agentfootprint.tools.effect', {
+                        kind: 'propose-transition',
+                        outcome: 'superseded',
+                        toolName: call.toolName,
+                        toolCallId: call.toolCallId,
+                        iteration: call.iteration,
+                        targetSkillId: target,
+                        reason: effect.reason,
+                        supersededBy: 'earlier-proposal',
+                    });
+                    continue;
+                }
+                if (state.winner === undefined) {
+                    state.winner = {
+                        targetSkillId: target,
+                        toolName: call.toolName,
+                        toolCallId: call.toolCallId,
+                        reason: effect.reason,
+                        iteration: call.iteration,
+                    };
+                    // Committed AT ACCEPTANCE (not batch end) so a pause later in the
+                    // batch checkpoints the accepted move instead of dropping it.
+                    scope.pendingToolTransition = state.winner;
+                    // The activation promise a gate-accepted read_skill pick makes,
+                    // made here too: a model-edge-only target keeps its llm-activated
+                    // trigger, so the ledger entry is what makes the body actually
+                    // load when the cursor lands.
+                    const activated = scope.activatedInjectionIds;
+                    if (!activated.includes(target)) {
+                        scope.activatedInjectionIds = [...activated, target];
+                    }
+                }
+                // First acceptance AND a same-target repeat both land here: every
+                // proposal that asked for the move that happens is 'accepted'.
+                (0, typedEmit_js_1.typedEmit)(scope, 'agentfootprint.tools.effect', {
+                    kind: 'propose-transition',
+                    outcome: 'accepted',
+                    toolName: call.toolName,
+                    toolCallId: call.toolCallId,
+                    iteration: call.iteration,
+                    targetSkillId: target,
+                    reason: effect.reason,
+                });
+                continue;
+            }
+            // require-instruction
+            const known = deps.leaseTargets?.get(effect.instructionId);
+            if (known === undefined) {
+                refuse('require-instruction', `require-instruction '${effect.instructionId}' was refused: no registered ` +
+                    `injection carries that id — the push door serves the declared catalog only ` +
+                    `(read_skill stays the pull door).`, { instructionId: effect.instructionId, deliveryLease: effect.deliveryLease });
+                continue;
+            }
+            if (known.surfaceMode === 'tool-only') {
+                refuse('require-instruction', `require-instruction '${effect.instructionId}' was refused: that skill declares ` +
+                    `surfaceMode 'tool-only', whose body travels only as a read_skill result — the ` +
+                    `system slot suppresses it, so the lease would be granted and never delivered. ` +
+                    `Pull it with read_skill, or change the skill's surfaceMode.`, { instructionId: effect.instructionId, deliveryLease: effect.deliveryLease });
+                continue;
+            }
+            const tenant = (0, toolEffects_js_1.tenantOf)(scope.currentSkillId, scope.activatedInjectionIds);
+            const lease = {
+                instructionId: effect.instructionId,
+                deliveryLease: effect.deliveryLease,
+                ...(tenant !== undefined && { skillId: tenant }),
+                toolName: call.toolName,
+                toolCallId: call.toolCallId,
+                iteration: call.iteration,
+            };
+            // Prune-as-we-write: spent grants leave with the same write that adds
+            // the new one, so a long turn never accumulates dead leases.
+            scope.instructionLeases = [
+                ...(0, toolEffects_js_1.pruneLeases)(scope.instructionLeases, call.iteration, tenant),
+                lease,
+            ];
+            (0, typedEmit_js_1.typedEmit)(scope, 'agentfootprint.tools.effect', {
+                kind: 'require-instruction',
+                outcome: 'accepted',
+                toolName: call.toolName,
+                toolCallId: call.toolCallId,
+                iteration: call.iteration,
+                instructionId: effect.instructionId,
+                deliveryLease: effect.deliveryLease,
+            });
+        }
+        return note;
+    };
+    /** The batch-end aggregate for conflicting proposals — the
+     *  `route_conflict` reuse, additive `source` says what conflicted. The
+     *  per-effect `tools.effect` events above already carried every fact;
+     *  this is the one-event-per-batch view the edge law already ships. */
+    const emitTransitionConflict = (scope, iteration, state) => {
+        if (state.winner === undefined || state.losers.length === 0)
+            return;
+        (0, typedEmit_js_1.typedEmit)(scope, 'agentfootprint.skill.route_conflict', {
+            iteration,
+            ...(scope.currentSkillId !== undefined && {
+                fromSkillId: scope.currentSkillId,
+            }),
+            winner: {
+                ...(state.winner.toolCallId !== undefined && { toolCallId: state.winner.toolCallId }),
+                toolName: state.winner.toolName,
+                target: state.winner.targetSkillId,
+            },
+            losers: state.losers.map((l) => ({ ...l })),
+            source: 'tool-proposal',
+        });
+    };
     /**
      * Every teardown scope an Agent run can honour (9.7.0).
      *
@@ -596,6 +787,18 @@ function buildToolCallsHandler(deps) {
                 ...sessionContext(scope, toolName, toolCallId),
             });
             await endCall(toolCallId);
+            // The typed effects channel (9.19.0) — same unwrap as the batch loop,
+            // at this path's own execute boundary, so a resumed call's envelope is
+            // judged exactly as an inline one's.
+            const envelope = (0, toolEffects_js_1.readToolResultEnvelope)(result);
+            if (envelope !== undefined) {
+                return { result: envelope.content, executed: true, envelope };
+            }
+            // A status-only shape missing its `effects: []` marker is DATA (bytes
+            // unchanged) — but never silently: name the dropped marker in dev mode.
+            const nearMiss = (0, toolEffects_js_1.explainStatusOnlyNearMiss)(result);
+            if (nearMiss !== undefined)
+                warnEffect(toolName, nearMiss);
             return { result, executed: true };
         }
         catch (err) {
@@ -678,6 +881,10 @@ function buildToolCallsHandler(deps) {
             // `on-tool-return` triggers and skill-graph routes read the batch.
             const batchResults = [];
             scope.toolResults = [];
+            // ── The batch's transition bookkeeping (9.19.0) ───────────────────
+            // First ACCEPTED `propose-transition` wins (committed at acceptance);
+            // later ones to other targets are suppressed + aggregated at batch end.
+            const transitionState = { losers: [] };
             // Capture run identity from scope for the enriched permission ctx.
             // Same value the Tools slot passes to ToolProvider.list(ctx) so the
             // checker sees consistent identity across both gates.
@@ -694,6 +901,11 @@ function buildToolCallsHandler(deps) {
                 const startMs = Date.now();
                 let result;
                 let error;
+                /** The typed effects channel (9.19.0) — set only when the tool
+                 *  returned a recognized result envelope; everything else keeps
+                 *  today's path byte for byte. */
+                let toolEnvelope;
+                let toolStatus;
                 // Permission gate — when a checker is configured, evaluate BEFORE
                 // executing the tool. Emits `permission.check` with the decision.
                 //
@@ -1166,6 +1378,26 @@ function buildToolCallsHandler(deps) {
                                 ...(resolvedCredential && { credential: resolvedCredential }),
                                 ...sessionContext(scope, tc.name, tc.id),
                             });
+                            // The typed effects channel (9.19.0): a recognized envelope is
+                            // unwrapped HERE, at the one boundary the raw return crosses —
+                            // everything downstream (governance rules, the cap, history,
+                            // `tool_end`) sees the CONTENT, exactly what a bare return
+                            // would have shown. The effects are judged below, after the
+                            // gates, in call order.
+                            const envelope = (0, toolEffects_js_1.readToolResultEnvelope)(result);
+                            if (envelope !== undefined) {
+                                toolEnvelope = envelope;
+                                result = envelope.content;
+                                toolStatus = envelope.status;
+                            }
+                            else {
+                                // A status-only shape missing its `effects: []` marker is
+                                // DATA (bytes unchanged) — but never silently: name the
+                                // dropped marker in dev mode.
+                                const nearMiss = (0, toolEffects_js_1.explainStatusOnlyNearMiss)(result);
+                                if (nearMiss !== undefined)
+                                    warnEffect(tc.name, nearMiss);
+                            }
                             await endCall(tc.id);
                         }
                         catch (err) {
@@ -1235,6 +1467,7 @@ function buildToolCallsHandler(deps) {
                                 allowed,
                                 iteration,
                             });
+                            noteSkillRefusal(scope, iteration);
                         }
                         else if (deps.skillStrictness !== undefined && skillHop) {
                             // ── The POSTURE arm (SG-C) — after reachability, hops only. ──
@@ -1256,6 +1489,7 @@ function buildToolCallsHandler(deps) {
                                     iteration,
                                     posture: deps.skillStrictness,
                                 });
+                                noteSkillRefusal(scope, iteration);
                             }
                         }
                     }
@@ -1300,6 +1534,9 @@ function buildToolCallsHandler(deps) {
                     result: capped.result,
                     durationMs,
                     ...(error === true && { error: true }),
+                    // The tool's own declared outcome (9.19.0) — additive, envelope
+                    // tools only.
+                    ...(toolStatus !== undefined && { status: toolStatus }),
                 });
                 let resultStr = typeof modelResult === 'string' ? modelResult : (0, validators_js_1.safeStringify)(modelResult);
                 // ── Step boundary (9.18.0): advance decided, then decorate, THEN
@@ -1327,6 +1564,15 @@ function buildToolCallsHandler(deps) {
                         });
                     }
                 }
+                // ── Typed tool effects (9.19.0) — judged in call order ──────────
+                // Only for a call that RAN clean and returned an envelope. Refusal
+                // notes join the model-visible result AFTER the cap (framework
+                // truth, the step-suffix precedent); accepted effects speak through
+                // what they do — the cursor move, the delivered instruction — and
+                // through `tools.effect` on the record.
+                if (toolEnvelope !== undefined && executed && !error && !denied) {
+                    resultStr += applyToolEffects(scope, { toolName: tc.name, toolCallId: tc.id, iteration }, toolEnvelope, transitionState);
+                }
                 newHistory.push({
                     role: 'tool',
                     content: resultStr,
@@ -1342,8 +1588,17 @@ function buildToolCallsHandler(deps) {
                 //     (call order preserved), so an earlier parallel call's
                 //     routing implication is no longer overwritten by a
                 //     later sibling's.
-                scope.lastToolResult = { toolName: tc.name, result: resultStr };
-                batchResults.push({ toolName: tc.name, result: resultStr, toolCallId: tc.id });
+                scope.lastToolResult = {
+                    toolName: tc.name,
+                    result: resultStr,
+                    ...(toolStatus !== undefined && { status: toolStatus }),
+                };
+                batchResults.push({
+                    toolName: tc.name,
+                    result: resultStr,
+                    toolCallId: tc.id,
+                    ...(toolStatus !== undefined && { status: toolStatus }),
+                });
                 scope.toolResults = [...batchResults];
                 // (2) `read_skill` is the auto-attached activation tool.
                 //     When the LLM calls it with a valid Skill id, append
@@ -1408,6 +1663,10 @@ function buildToolCallsHandler(deps) {
                 }
             }
             scope.history = newHistory;
+            // The batch-end aggregate for conflicting transition proposals
+            // (9.19.0) — fires only when ≥2 accepted proposals named different
+            // targets; the per-effect events above already told each story.
+            emitTransitionConflict(scope, iteration, transitionState);
             (0, typedEmit_js_1.typedEmit)(scope, 'agentfootprint.agent.iteration_end', {
                 turnIndex: 0,
                 iterIndex: iteration,
@@ -1464,6 +1723,8 @@ function buildToolCallsHandler(deps) {
                 /** The call REALLY ran, clean — the step-advance eligibility this
                  *  path knows about itself (a decline or a chain-deny never ran). */
                 let stepToolRan = false;
+                /** The effects envelope the resumed call returned (9.19.0). */
+                let resumeEnvelope;
                 if (!decision.approved) {
                     result = decision.note ? `declined by human: ${decision.note}` : 'declined by human';
                     (0, ledger_js_1.recordDecisions)(scope, [
@@ -1571,6 +1832,8 @@ function buildToolCallsHandler(deps) {
                         result = dispatched.result;
                         error = dispatched.error;
                         stepToolRan = dispatched.executed === true && error !== true;
+                        if (stepToolRan)
+                            resumeEnvelope = dispatched.envelope;
                         // skip_step behind a middleware ask, approved (9.18.0): the
                         // placeholder just landed — replace it with the authoritative
                         // sentence BEFORE the chain's last word, the execute loop's
@@ -1610,18 +1873,35 @@ function buildToolCallsHandler(deps) {
                 if (deps.stepPlanFor && stepToolRan) {
                     askResultStr += applyStepReturn(scope, { toolName, toolCallId, iteration });
                 }
+                // Typed tool effects (9.19.0) — a resumed call's envelope is judged
+                // exactly as an inline one's (fresh single-call batch state).
+                if (resumeEnvelope !== undefined) {
+                    const askTransition = { losers: [] };
+                    askResultStr += applyToolEffects(scope, { toolName, toolCallId, iteration }, resumeEnvelope, askTransition);
+                    emitTransitionConflict(scope, iteration, askTransition);
+                }
                 const askHistory = [
                     ...scope.history,
                     { role: 'tool', content: askResultStr, toolCallId, toolName },
                 ];
                 scope.history = askHistory;
-                scope.lastToolResult = { toolName, result: askResultStr };
-                appendBatchResult(scope, { toolName, result: askResultStr, toolCallId });
+                scope.lastToolResult = {
+                    toolName,
+                    result: askResultStr,
+                    ...(resumeEnvelope?.status !== undefined && { status: resumeEnvelope.status }),
+                };
+                appendBatchResult(scope, {
+                    toolName,
+                    result: askResultStr,
+                    toolCallId,
+                    ...(resumeEnvelope?.status !== undefined && { status: resumeEnvelope.status }),
+                });
                 (0, typedEmit_js_1.typedEmit)(scope, 'agentfootprint.stream.tool_end', {
                     toolCallId,
                     result: askCapped.result,
                     durationMs: Date.now() - startMs,
                     ...(error === true && { error: true }),
+                    ...(resumeEnvelope?.status !== undefined && { status: resumeEnvelope.status }),
                 });
                 (0, typedEmit_js_1.typedEmit)(scope, 'agentfootprint.agent.iteration_end', {
                     turnIndex: 0,
@@ -1669,6 +1949,8 @@ function buildToolCallsHandler(deps) {
                 let error;
                 /** Step-advance eligibility, judged by this path (a decline ran nothing). */
                 let stepToolRan = false;
+                /** The effects envelope the approved call returned (9.19.0). */
+                let resumeEnvelope;
                 if (decision.approved) {
                     const env = scope.$getEnv();
                     const tool = lookupTool(toolName);
@@ -1676,6 +1958,8 @@ function buildToolCallsHandler(deps) {
                     result = dispatched.result;
                     error = dispatched.error;
                     stepToolRan = dispatched.executed === true && error !== true;
+                    if (stepToolRan)
+                        resumeEnvelope = dispatched.envelope;
                     // Consent moved the execution to this side of the pause; the rules
                     // about results move with it.
                     if (dispatched.executed === true) {
@@ -1706,19 +1990,36 @@ function buildToolCallsHandler(deps) {
                 if (deps.stepPlanFor && stepToolRan) {
                     decisionResultStr += applyStepReturn(scope, { toolName, toolCallId, iteration });
                 }
+                // Typed tool effects (9.19.0) — an approved consequential call may
+                // carry them too; judged exactly as inline.
+                if (resumeEnvelope !== undefined) {
+                    const decisionTransition = { losers: [] };
+                    decisionResultStr += applyToolEffects(scope, { toolName, toolCallId, iteration }, resumeEnvelope, decisionTransition);
+                    emitTransitionConflict(scope, iteration, decisionTransition);
+                }
                 const decisionHistory = [
                     ...scope.history,
                     { role: 'tool', content: decisionResultStr, toolCallId, toolName },
                 ];
                 scope.history = decisionHistory;
                 // Drives `on-tool-return` triggers, same as the execute path.
-                scope.lastToolResult = { toolName, result: decisionResultStr };
-                appendBatchResult(scope, { toolName, result: decisionResultStr, toolCallId });
+                scope.lastToolResult = {
+                    toolName,
+                    result: decisionResultStr,
+                    ...(resumeEnvelope?.status !== undefined && { status: resumeEnvelope.status }),
+                };
+                appendBatchResult(scope, {
+                    toolName,
+                    result: decisionResultStr,
+                    toolCallId,
+                    ...(resumeEnvelope?.status !== undefined && { status: resumeEnvelope.status }),
+                });
                 (0, typedEmit_js_1.typedEmit)(scope, 'agentfootprint.stream.tool_end', {
                     toolCallId,
                     result: decisionCapped.result,
                     durationMs: Date.now() - startMs,
                     ...(error === true && { error: true }),
+                    ...(resumeEnvelope?.status !== undefined && { status: resumeEnvelope.status }),
                 });
                 (0, typedEmit_js_1.typedEmit)(scope, 'agentfootprint.agent.iteration_end', {
                     turnIndex: 0,
@@ -1781,18 +2082,35 @@ function buildToolCallsHandler(deps) {
                 if (deps.stepPlanFor && dispatched.executed === true && error !== true) {
                     consentResultStr += applyStepReturn(scope, { toolName, toolCallId, iteration });
                 }
+                // Typed tool effects (9.19.0) — same judge as every other path.
+                const consentEnvelope = dispatched.executed === true && error !== true ? dispatched.envelope : undefined;
+                if (consentEnvelope !== undefined) {
+                    const consentTransition = { losers: [] };
+                    consentResultStr += applyToolEffects(scope, { toolName, toolCallId, iteration }, consentEnvelope, consentTransition);
+                    emitTransitionConflict(scope, iteration, consentTransition);
+                }
                 const consentHistory = [
                     ...scope.history,
                     { role: 'tool', content: consentResultStr, toolCallId, toolName },
                 ];
                 scope.history = consentHistory;
-                scope.lastToolResult = { toolName, result: consentResultStr };
-                appendBatchResult(scope, { toolName, result: consentResultStr, toolCallId });
+                scope.lastToolResult = {
+                    toolName,
+                    result: consentResultStr,
+                    ...(consentEnvelope?.status !== undefined && { status: consentEnvelope.status }),
+                };
+                appendBatchResult(scope, {
+                    toolName,
+                    result: consentResultStr,
+                    toolCallId,
+                    ...(consentEnvelope?.status !== undefined && { status: consentEnvelope.status }),
+                });
                 (0, typedEmit_js_1.typedEmit)(scope, 'agentfootprint.stream.tool_end', {
                     toolCallId,
                     result: consentCapped.result,
                     durationMs: Date.now() - startMs,
                     ...(error === true && { error: true }),
+                    ...(consentEnvelope?.status !== undefined && { status: consentEnvelope.status }),
                 });
                 (0, typedEmit_js_1.typedEmit)(scope, 'agentfootprint.agent.iteration_end', {
                     turnIndex: 0,