Completion Guard
A completion guard is your code that judges what would end a run, before the run commits it. It has two handlers, and an agent may set either or both:
onOutputjudges a structured output: a__finish__submission or afinishWithtool's result. It can accept it, replace it with your own output, send the model back with feedback, or fail the run.onReplyjudges a natural text reply that would end the turn. It can let the reply stand, send the model back for another step with feedback, or fail the run.
Before a handler decides, it can do whatever your app needs: read and change the run's state, add context rows, or call your own services and database.
Use it for "the report must cite a source", "the order must be confirmed before the turn ends", "the totals must match our ledger", or "if the model stopped early, nudge it once".
import { defineAgent } from '@helix-agents/core';
const agent = defineAgent({
name: 'sourced-report',
systemPrompt: 'You write short, sourced reports.',
llmConfig: { model },
outputSchema: Report,
completionGuard: {
onOutput: async (ctx) => {
if (!ctx.candidate.valid)
return { action: 'revise', feedback: ctx.candidate.issues.join('; ') };
if (ctx.candidate.output.sources.length === 0) {
return { action: 'revise', feedback: 'Cite at least one source before you submit.' };
}
return { action: 'accept' };
},
onReply: async (ctx) => {
if (ctx.revisionsLeft > 0 && ctx.reply.text.length < 20) {
return { action: 'revise', feedback: 'Keep working: submit the report when it is ready.' };
}
},
},
});Runs on runtime-js and the Cloudflare Durable Object. CF Workflows, Temporal and DBOS refuse an agent that declares completionGuard at every entry, with a typed framework_not_supported, until they run it.
The pipeline
Every structured output goes through three stages:
- The candidate. A
__finish__submission is parsed against the agent'soutputSchema; one that fails goes back to the model with the issues, without a guard call. AfinishWithcall runs itsexecute(a throw, or input that fails the tool'sinputSchema, goes back to the model), and its result is parsed againstoutputSchema, giving a valid or an invalid candidate. - The guard.
onOutputjudges the candidate, at most once per step. - The output contract. An
acceptkeeps the candidate's parsed output (never parsed again, so your schema's transforms and defaults run once). Anaccept_withoutput is parsed againstoutputSchema.
Only an explicit signal from your app reaches the model. Data the model produced that breaks a declared contract is the model's to fix, and it sees the issues. Data your app produced that breaks the output contract, with no signal from your app, is a bug in your app and fails the run loudly with framework_completion_output_contract_violation:
- a
finishWithresult that failsoutputSchema, with noonOutput(or with one that did not handle it); - an
accept_withoutput that failsoutputSchema.
To send an invalid finishWith result back to the model instead, say so:
onOutput: async (ctx) =>
ctx.candidate.valid ? { action: 'accept' } : { action: 'revise', feedback: ctx.candidate.issues.join('; ') },onOutput
onOutput needs the agent's outputSchema (defineAgent refuses it otherwise, with a typed validation_error). It runs on every output candidate: on an ordinary step, in forced completion and in Final Step, and on a finishWith call deferred by a same-step client tool or a suspending sub-agent.
interface OutputGuardContext<TState, TOutput> extends CompletionGuardBase<TState> {
candidate:
| { valid: true; output: TOutput }
| { valid: false; value: unknown; issues: readonly string[] }; // only a finishWith result can be invalid
source:
| { kind: 'finish_tool'; toolCall: { id: string } }
| {
kind: 'finish_with';
toolCall: { id: string; name: string; input: unknown };
toolResult: unknown;
};
forced:
| false
| {
mode: 'forced_tool' | 'native_output' | 'final_step';
attempt: number;
attemptsLeft: number;
};
}It must return a verdict (the type requires one):
| Return | What happens |
|---|---|
{ action: 'accept' } | The candidate's output is the run's output. Only for a valid candidate (else it is an invalid verdict, below) |
{ action: 'accept_with', output } | Your own output, parsed against outputSchema; a failure is framework_completion_output_contract_violation |
{ action: 'revise', feedback?: string } | The model tries again. It needs feedback or at least one addContext item |
{ action: 'fail', message: string, code?: string, details?: {...} } | The run fails, non-retryable, with your code (else framework_completion_guard_rejected); details reaches errorDetail.cause |
A revise turns the finish call's result into a failed result carrying your feedback, so the model reads it next to its own call. On a finishWith call, the model reads your feedback in place of the tool's result. The tool has run: its state writes stay, and its result is in ctx.source.toolResult and the span. When you give only context items, the call's result says The application did not accept this output yet. See the notes that follow.
onReply
onReply runs only where the run would otherwise end on a natural text reply: the model's stop reason is end_turn or stop_sequence. It never runs:
| Step | Why |
|---|---|
A step that calls __finish__ or a finishWith tool | An explicit finish: onOutput judges it |
| A forced-completion call | That phase has its own bounded attempts (maxCompletionRetries) |
| A reply cut at its token limit, a content filter, a refusal, an error | These already fail or enter forced completion; a correction would hide the cause |
The step that reaches maxSteps | Revising would turn a completion into a max-steps failure |
| A run that was stopped or superseded | The stop wins |
interface ReplyGuardContext<TState> extends CompletionGuardBase<TState> {
reply: { text: string; stopReason: 'end_turn' | 'stop_sequence' };
handsOverToForcedCompletion: boolean; // an outputSchema agent: `accept` lets forced completion begin
}| Return | What happens |
|---|---|
nothing, or { action: 'accept' } | The run ends as it would have without a guard |
{ action: 'revise', feedback?: string } | The run takes another step. It needs feedback or at least one addContext item |
{ action: 'fail', message: string, code?: string, details?: {...} } | The run fails, as for onOutput |
On an outputSchema agent a text reply is not an output: onReply runs before forced completion. A revise sends your correction instead of the generic forced-completion message; an accept enters forced completion as it would without a guard.
What both handlers receive
interface CompletionGuardBase<TState> {
sessionId: string;
runId: string;
stepCount: number; // the step being judged
guardKey: string; // `${runId}:${stepCount}:${attemptId}`, for your own idempotency
messages: readonly Message[]; // the session's log, including the step being judged
getState(): Readonly<TState>;
updateState(updater: (draft: TState) => void): void; // like a tool's
addContext(items: ContextItem[]): void; // text and tools items, placed as your app's are
revisionsUsed: number; // in this turn
revisionsLeft: number;
abortSignal: AbortSignal; // its time limit, or the run's stop
}The guard is ordinary async code. Your services and database come from your own closure, as a tool's do. It does not call the agent's tools: if it needs what a tool does, call your own function, and record what changed through updateState and addContext, so the model sees it on its next call.
Your writes and rows commit with the step you judged, in that step's own commit, whatever you decide. A crash cannot leave the step committed without them. So "settle and accept" is just an accept after updateState / addContext.
feedback is written by the agent's context format (the kind is completion_guard, with on: 'output' | 'reply'). The default puts it behind a fixed label, Automated feedback from the application (this is not from the user): , so the model never reads your correction as the user's words, and sends a reply's feedback as a user turn. An output's feedback is the finish call's own failed result. Your addContext items are placed as your app's are (an item may declare placement). Their tools items may switch a tool back on, as your app's and hooks' rows may (a tool's rows may only switch tools off).
The budget
maxRevisions (default 3) bounds the revisions per turn, shared by both handlers on the ordinary path. The count comes from the log (the guard's own rows and revised finish results), so a client-tool suspension, a crash or a retry() in between keeps it, a rewind refunds what it removes, and a new turn starts from zero. Each revision also costs a step of maxSteps. maxRevisions: 0 never revises on the ordinary path.
When the budget is spent, the guard is still called, so it can choose fail. A revise then does what the run would have done without the objection:
- A reply stands. The run ends normally: the revision's rows are dropped (a correction nobody acts on would otherwise reach the next turn's model), its
updateStatewrites are kept, and the run records the completion reasoncompletion_guard_exhausted. On anoutputSchemaagent the reply hands over to forced completion, as anacceptwould. - An output enters forced completion, its correction message carrying your last feedback (the forced trigger
completion_guard).
In forced completion (and Final Step), an onOutput revise is a miss under maxCompletionRetries and never spends maxRevisions. When those attempts run out, the run fails with framework_forced_completion_exhausted, its cause your last feedback. Besides fail, that is the only way an outputSchema agent fails on its guard.
Counting revisions in state
If your guard keeps its own count in state, derive it from revisionsUsed instead of adding one on every call. The guard is also called once the budget is spent, and its writes from that call are kept, so a += 1 there counts a revision that never happened.
One guard call per step
A revise ends the step's finishing. If the model calls two finishWith tools in one step and the guard revises the first, the second is not executed: it gets a not-executed result (superseded_by_revision), so the model reads your feedback before it tries another finish. A finishWith call whose execute throws is not a guard decision: the next one in the step is still tried. So the guard runs at most once per step, and guardKey is unique per call.
A fail ends the run at the step, and the step's other unanswered calls get not-executed results. Regular calls beside the finish run before the guard, and their results stay whatever it decides.
When the guard itself fails
A guard that throws, exceeds timeoutMs (default 30 s) or returns an invalid verdict commits nothing of itself: no rows, no writes. Then onError decides:
'fail'(the default foronOutput): the run fails withframework_completion_guard_failed. It is retryable when the error your guard threw is (for example your database was down), soretry()can take it. A timeout or an invalid verdict is not retryable.'accept'(the default foronReply): a reply stands; a valid output candidate is accepted (an invalid one fails as a contract violation). The error is reported: the log eventcore.completion_guard.errored, the span, and the completion reasoncompletion_guard_error.
The time limit runs inside the step's commit window, and on the Cloudflare Durable Object inside a request's lifetime: keep guards short, and do slow work after the run completes.
What a client sees on a fail
The run fails with your code (or framework_completion_guard_rejected) and your message. The chat stream ends failed: the failed stream's info carries the error detail (as for any framework failure, such as running out of maxSteps), and no error chunk is written, since that chunk is reserved for a model failure. The client reads the error from the snapshot and the run's status (AgentResult.errorDetail and the session's persisted errorDetail, on a reconnect too), and onAgentFail fires with the same typed error.
Seeing what the guard did
| Where | Live result | Reconnect, getHandle().result(), the DO's /status |
|---|---|---|
completionReason: 'completion_guard_exhausted' / 'completion_guard_error' | yes | yes (the run record's reason) |
errorDetail of a fail | yes | yes (the session's persisted detail) |
completionGuard: { revisionsUsed, exhausted?, error?, outputAdjusted? } | yes | yes (the run record's report) |
AgentResult.completionGuard (and the onAgentComplete / onAgentFail argument's completionGuard) is also written on the run record with the run's terminal status (RunMetadata.completionGuard), so a reconnect's result and every caller of a Durable Object (which reads results through /status, field completionGuard) see what the live result does. When the guard's step entered the forced completion that ended the run, the report travels with the forced-completion phase, so a crash and a retry() keep it. outputAdjusted says the output is your accept_with output.
The log events core.completion_guard.{accepted, accepted_with, revised, exhausted, errored, failed} and core.completion.output_contract_violation, and the span, record every decision. A completed session never carries an errorDetail.
The chat stream needs no change: a revision is one more step (finish-step, start-step), the guard's rows are hidden context rows, its writes are a state_patch, and a revised finish call's result is an ordinary failed tool result.
Side effects
executeruns before the guard. AfinishWithtool's effects happen on every attempt, including the ones the guard then revises, and the call id changes per attempt. Key the tool's writes on your business id, or do the work after the run completes.- The guard's own effects can key on
guardKey: a lost step runs again, and so does its guard (its rows and writes land once, since they ride the commit, but a database write or an email may run twice). onAgentCompleteis at-least-once and runs before the run's terminal commit. AnonAgentFailoronAgentSupersededcan still follow it, and a recovery can call it again. Its argument'scompletionKeynames the committed row that carries the acceptance; treat it as opaque (runtime-js and the CF Durable Object key an output by its call, CF Workflows, Temporal and DBOS by its reply row). It is the same on a call after a recovery, so record it with the effect, atomically:
hooks: {
onAgentComplete: async ({ output, completionKey }) => {
await db.tx(async (tx) => {
if (await tx.processed.exists(completionKey)) return;
await tx.processed.insert(completionKey);
await tx.reports.insert(output);
});
},
},The key is read from the committed log on every runtime, never made up: a key read that keeps failing fails the run (typed, retry()-able); the hook never fires with a substitute key.
Hook order
For a reply: beforeLLMCall → the model → afterLLMCall → onReply → then:
- revise: the step commit → the next step (its context pass,
beforeLLMCall, …); - accept: the terminal commit →
onAgentComplete→ the run ends; - fail: the step commit →
onAgentFail→ the run fails.
For a finishWith call, onOutput runs after the tool's execute and before its tool_end and afterTool, so the stream, the stored row and afterTool all see the decided result. For __finish__, it runs after the step's other calls. onAgentComplete fires once, after the accepted output; a revision fires no lifecycle hook of its own.
Recovery
An accepted output is recorded on the accepted call's result row, in the same step commit as the decision. A run that recovers after that commit (for example a Durable Object evicted while onAgentComplete runs) completes with the recorded output: the guard does not run again, nothing is parsed again, and the model is not called. A revised step holds no output, so a recovery from it calls the model again.
Several finishWith tools
Forced completion and Final Step offer every finishWith tool, on every runtime, so an agent with more than one can finish through any of them once forced, as on an ordinary step. onOutput judges the result of whichever one the model called (ctx.source.toolCall.name names it). See Finishing Agents for the request each strategy sends.