203 lines
7.6 KiB
TypeScript
203 lines
7.6 KiB
TypeScript
/**
|
|
* Completion-time gates for the agent loop.
|
|
*
|
|
* Extracted from agent-loop.ts (PR-D, 2026-05-27). Two gates fire from the
|
|
* no-tool-calls branch when the model returns a "final" answer:
|
|
*
|
|
* D3 verification gate — if the model claims verified/passing/working
|
|
* completion but ran no verification-class tool, inject ONE corrective
|
|
* directive and continue the loop. One-shot: a re-asserted unverified
|
|
* claim on the corrective turn is accepted (loop-guard / maxTurns
|
|
* still bound the loop).
|
|
*
|
|
* D1 skill distillation gate — on a qualifying ≥5-tool, R2-gated
|
|
* successful turn, mechanically inject the planSkillDistillation
|
|
* directive so the model authors a skill in its NEXT turn. One-shot.
|
|
* The user's "real" answer (current `content`) is preserved in state
|
|
* so it surfaces in the final return — the distillation turn's output
|
|
* is the skill summary, NOT the answer (issue #4).
|
|
*
|
|
* Both gates were inlined as ~50 lines in runAgentLoop. Lifting them as a
|
|
* single composable `maybeFireCompletionGate` call leaves the agent loop
|
|
* reading as the conversation loop it conceptually is.
|
|
*/
|
|
|
|
import {
|
|
assertsUnverifiedCompletion,
|
|
isVerificationToolName,
|
|
VERIFICATION_GATE_DIRECTIVE,
|
|
VERIFICATION_NO_TOOL_DISCLOSURE,
|
|
} from './verification-gate.js';
|
|
import { planSkillDistillation } from './skill-distillation.js';
|
|
import { logTurnEvent } from './turn-context.js';
|
|
|
|
/**
|
|
* One-shot flags + preserved-answer state for the two completion gates.
|
|
* Created once per `runAgentLoop` invocation; threaded through subsequent
|
|
* `maybeFireCompletionGate` calls so each gate fires AT MOST ONCE per run.
|
|
*/
|
|
export interface GateState {
|
|
/** True after the D3 verification gate has fired (one-shot) */
|
|
verificationCorrectionUsed: boolean;
|
|
/** True after the D1 skill-distillation gate has fired (one-shot) */
|
|
skillDistillationUsed: boolean;
|
|
/**
|
|
* The user-facing answer captured at D1 fire time. The distillation turn
|
|
* that follows is a side-effect (author the skill via create_skill); its
|
|
* own output is the skill summary, not the user's answer. Any return path
|
|
* reached after D1 fires MUST surface this preserved value instead of the
|
|
* distillation turn's content — otherwise "I saved a skill…" overwrites
|
|
* the real answer (issue #4).
|
|
*/
|
|
preservedAnswerForDistillation: string | null;
|
|
}
|
|
|
|
export function initialGateState(): GateState {
|
|
return {
|
|
verificationCorrectionUsed: false,
|
|
skillDistillationUsed: false,
|
|
preservedAnswerForDistillation: null,
|
|
};
|
|
}
|
|
|
|
/**
|
|
* Structural shape of the messages array the agent loop pushes to. Kept
|
|
* local to avoid a circular import with agent-loop.ts; structurally
|
|
* compatible with `AgentMessage`.
|
|
*/
|
|
type GateMessage = {
|
|
role: 'system' | 'user' | 'assistant' | 'tool';
|
|
content: string | null;
|
|
tool_calls?: unknown;
|
|
tool_call_id?: string;
|
|
};
|
|
|
|
export interface MaybeFireCompletionGateArgs {
|
|
/** Current turn's final assistant content (concatenated from streaming or non-streaming) */
|
|
content: string;
|
|
/** Names of tools used so far in this run (D1 reads length+set; D3 reads set for verification-class) */
|
|
toolsUsed: readonly string[];
|
|
/** Names of tools the model can actually call in this run. */
|
|
availableToolNames?: readonly string[];
|
|
/** Caller's message history — pushed to in-place when a gate fires */
|
|
messages: GateMessage[];
|
|
/** Current user-authored request, captured before internal directives are added. */
|
|
userRequest?: string;
|
|
/** Current gate state (returned with one-shot flags flipped if a gate fires) */
|
|
state: GateState;
|
|
/** Default true — set false to opt out of D3 */
|
|
enableVerification?: boolean;
|
|
/** Default true — set false to opt out of D1 */
|
|
enableSkillDistillation?: boolean;
|
|
/**
|
|
* AI-OS Phase 3 — skill diffusion observer. Invoked the moment D1 fires
|
|
* (right before the distillation directive is injected). Failures are
|
|
* swallowed — diffusion is observability, not a precondition.
|
|
*/
|
|
onSkillDistillationFire?: (info: {
|
|
patternKey: string;
|
|
toolsUsed: readonly string[];
|
|
directive: string;
|
|
}) => void | Promise<void>;
|
|
/** H-AUDIT-1: per-turn trace ID for structured event logging */
|
|
turnId?: string;
|
|
}
|
|
|
|
export interface GateResult {
|
|
/** True if a gate fired AND injected a corrective directive (caller should `continue`). */
|
|
fired: boolean;
|
|
/** New state object — copy of input state with one-shot flags + preserved answer updated. */
|
|
state: GateState;
|
|
/** Deterministic local suffix used when a claim cannot be verified by any available tool. */
|
|
contentSuffix?: string;
|
|
}
|
|
|
|
/**
|
|
* Try the completion-time gates in declared order (D3 first, then D1).
|
|
* At most one gate fires per call. Returns { fired, state } — caller
|
|
* continues the loop iff `fired` is true.
|
|
*/
|
|
export async function maybeFireCompletionGate(args: MaybeFireCompletionGateArgs): Promise<GateResult> {
|
|
const {
|
|
content,
|
|
toolsUsed,
|
|
availableToolNames = [],
|
|
messages,
|
|
userRequest = '',
|
|
state,
|
|
enableVerification = true,
|
|
enableSkillDistillation = true,
|
|
onSkillDistillationFire,
|
|
turnId,
|
|
} = args;
|
|
let nextState = state;
|
|
let contentSuffix: string | undefined;
|
|
|
|
// ── D3 verification-before-completion gate ──
|
|
if (
|
|
enableVerification &&
|
|
!state.verificationCorrectionUsed &&
|
|
assertsUnverifiedCompletion(content, toolsUsed, userRequest)
|
|
) {
|
|
if (!availableToolNames.some(isVerificationToolName)) {
|
|
logTurnEvent(turnId, {
|
|
stage: 'agent-loop.verification-gate.disclosed',
|
|
contentChars: content.length,
|
|
});
|
|
contentSuffix = VERIFICATION_NO_TOOL_DISCLOSURE;
|
|
nextState = { ...state, verificationCorrectionUsed: true };
|
|
} else {
|
|
const systemMessage = messages.find(message => message.role === 'system');
|
|
const internalDirective = `\n\n# Internal verification correction\n${VERIFICATION_GATE_DIRECTIVE}`;
|
|
if (systemMessage && typeof systemMessage.content === 'string') {
|
|
systemMessage.content += internalDirective;
|
|
} else {
|
|
messages.unshift({ role: 'system', content: internalDirective.trim() });
|
|
}
|
|
logTurnEvent(turnId, { stage: 'agent-loop.verification-gate.fired', contentChars: content.length });
|
|
return {
|
|
fired: true,
|
|
state: { ...state, verificationCorrectionUsed: true },
|
|
};
|
|
}
|
|
}
|
|
|
|
// ── D1 Hermes-parity closed learning loop (mechanical closure) ──
|
|
if (enableSkillDistillation && !nextState.skillDistillationUsed) {
|
|
const acceptedContent = `${content}${contentSuffix ?? ''}`;
|
|
const distillPlan = planSkillDistillation(toolsUsed, acceptedContent);
|
|
if (distillPlan) {
|
|
messages.push({ role: 'assistant', content: acceptedContent });
|
|
messages.push({ role: 'user', content: distillPlan.directive });
|
|
logTurnEvent(turnId, { stage: 'agent-loop.skill-distillation.fired', toolCalls: toolsUsed.length });
|
|
|
|
// AI-OS Phase 3 — skill diffusion observer. Swallow any error so the
|
|
// distillation loop is never blocked by a diffusion-side failure.
|
|
if (onSkillDistillationFire) {
|
|
try {
|
|
await onSkillDistillationFire({
|
|
patternKey: distillPlan.patternKey,
|
|
toolsUsed: [...toolsUsed],
|
|
directive: distillPlan.directive,
|
|
});
|
|
} catch {
|
|
/* observer failures must never block the loop */
|
|
}
|
|
}
|
|
|
|
return {
|
|
fired: true,
|
|
contentSuffix,
|
|
state: {
|
|
...nextState,
|
|
skillDistillationUsed: true,
|
|
preservedAnswerForDistillation: acceptedContent,
|
|
},
|
|
};
|
|
}
|
|
}
|
|
|
|
// No gate fired — caller can accept completion.
|
|
return { fired: false, state: nextState, contentSuffix };
|
|
}
|