Skip to content

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:

  • onOutput judges a structured output: a __finish__ submission or a finishWith tool's result. It can accept it, replace it with your own output, send the model back with feedback, or fail the run.
  • onReply judges 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".

typescript
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:

  1. The candidate. A __finish__ submission is parsed against the agent's outputSchema; one that fails goes back to the model with the issues, without a guard call. A finishWith call runs its execute (a throw, or input that fails the tool's inputSchema, goes back to the model), and its result is parsed against outputSchema, giving a valid or an invalid candidate.
  2. The guard. onOutput judges the candidate, at most once per step.
  3. The output contract. An accept keeps the candidate's parsed output (never parsed again, so your schema's transforms and defaults run once). An accept_with output is parsed against outputSchema.

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 finishWith result that fails outputSchema, with no onOutput (or with one that did not handle it);
  • an accept_with output that fails outputSchema.

To send an invalid finishWith result back to the model instead, say so:

typescript
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.

typescript
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):

ReturnWhat 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:

StepWhy
A step that calls __finish__ or a finishWith toolAn explicit finish: onOutput judges it
A forced-completion callThat phase has its own bounded attempts (maxCompletionRetries)
A reply cut at its token limit, a content filter, a refusal, an errorThese already fail or enter forced completion; a correction would hide the cause
The step that reaches maxStepsRevising would turn a completion into a max-steps failure
A run that was stopped or supersededThe stop wins
typescript
interface ReplyGuardContext<TState> extends CompletionGuardBase<TState> {
  reply: { text: string; stopReason: 'end_turn' | 'stop_sequence' };
  handsOverToForcedCompletion: boolean; // an outputSchema agent: `accept` lets forced completion begin
}
ReturnWhat 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 ​

typescript
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 updateState writes are kept, and the run records the completion reason completion_guard_exhausted. On an outputSchema agent the reply hands over to forced completion, as an accept would.
  • 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 for onOutput): the run fails with framework_completion_guard_failed. It is retryable when the error your guard threw is (for example your database was down), so retry() can take it. A timeout or an invalid verdict is not retryable.
  • 'accept' (the default for onReply): a reply stands; a valid output candidate is accepted (an invalid one fails as a contract violation). The error is reported: the log event core.completion_guard.errored, the span, and the completion reason completion_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 ​

WhereLive resultReconnect, getHandle().result(), the DO's /status
completionReason: 'completion_guard_exhausted' / 'completion_guard_error'yesyes (the run record's reason)
errorDetail of a failyesyes (the session's persisted detail)
completionGuard: { revisionsUsed, exhausted?, error?, outputAdjusted? }yesyes (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 ​

  • execute runs before the guard. A finishWith tool'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).
  • onAgentComplete is at-least-once and runs before the run's terminal commit. An onAgentFail or onAgentSuperseded can still follow it, and a recovery can call it again. Its argument's completionKey names 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:
typescript
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.

Released under the MIT License.