Structured Application Output

// Module 21 lab. A loop driver: a plain script that calls the agent over and
// over until a schema-validated object says the work is finished, and stops
// itself when it is not.
//
//   node run.mjs --fake        replay canned results, no API key, no cost
//   node run.mjs               one real session per iteration, costs money
//
// The whole point of structured output is this file. Without it a driver has to
// read the agent's prose and guess whether "I've finished the refactor" means
// finished. With it, the driver reads a boolean.

// The query function comes from sdk.mjs so the test can hand this file a fake
// one. Nothing else in the driver knows whether it is talking to a real model.
import { query as defaultQuery } from "./sdk.mjs";

// The done-check schema. Two fields: a boolean the driver branches on, and the
// list of work the agent believes is left, which becomes the next prompt.
//
// The declaration line matters. The SDK validates against JSON Schema draft-07
// and rejects a schema declaring a newer draft (BUILD_TRACK_PLAN.md module 21,
// verified against the live docs 2026-08-29). If you write this schema with
// Zod instead of by hand, Zod emits draft 2020-12 by default, so the conversion
// call needs its target set:
//
//   z.toJSONSchema(DoneCheck, { target: "draft-7" })
//
// That exact call is the structured-outputs page's own example.
export const DONE_CHECK_SCHEMA = {
$schema: "http://json-schema.org/draft-07/schema#",
type: "object",
properties: {
  done: { type: "boolean" },
  remaining: { type: "array", items: { type: "string" } },
},
required: ["done", "remaining"],
additionalProperties: false,
};

/**
* Run the agent until it reports done, or until one of the three stops fires.
*
* Every argument that limits the run has a default, because a driver with no
* limits is a program that spends money while you are asleep.
*/
export async function runLoop({
prompt,
query = defaultQuery,
schema = DONE_CHECK_SCHEMA,
// Stop 1: the agent says done.
// Stop 2: a dollar figure you set. Checked after each call.
budgetUsd = 1.0,
// Stop 3: a count of iterations of THIS loop. maxTurns caps the round trips
// inside one query() call; it does not cap how many times your own code calls
// query() again. A driver without its own iteration cap is the machine that
// never stops on its own, which is the failure module 33 is built around.
maxIterations = 5,
// The turn cap handed to the first call. On error_max_turns the driver
// resumes the same session with this raised, which is the documented
// recovery: "Agent ran out of turns. Resume with a higher limit."
startMaxTurns = 8,
turnBump = 2,
log = () => {},
} = {}) {
let sessionId = null;
let maxTurns = startMaxTurns;
let nextPrompt = prompt;

// The SDK returns a per-call total only. The cost-tracking page states it
// plainly: "Each query() call returns its own total_cost_usd. The SDK doesn't
// provide a session-level total, so if your application makes multiple
// query() calls ... accumulate the totals yourself." So the driver does.
//
// The same page's warning applies to every number this file prints:
// total_cost_usd is a client-side estimate computed from a price table
// bundled at build time, not authoritative billing data. Use it for
// budgeting, never to bill anyone.
let totalCostUsd = 0;

for (let iteration = 1; iteration <= maxIterations; iteration++) {
  let result = null;

  // A single-shot query() that ends on an error result yields the result
  // message and THEN raises, and the underlying Claude Code process exits
  // nonzero. The agent-loop page calls the raise intentional and says to wrap
  // the loop in a try block if your code needs to continue past it. This
  // driver needs to continue past error_max_turns, so it does.
  try {
    for await (const message of query({
      prompt: nextPrompt,
      options: {
        outputFormat: { type: "json_schema", schema },
        maxTurns,
        // The SDK's own budget cap, set to whatever is left of yours. It
        // stops one call; your running total stops the loop. Subagent spend
        // counts against it too. A /clear starts the running total the cap is
        // compared against over again, so an interactive session cannot be
        // budgeted this way.
        maxBudgetUsd: Math.max(0, budgetUsd - totalCostUsd),
        // Resuming restores the full context of the earlier turns: files
        // read, analysis done, actions taken. Without it, iteration two
        // starts from nothing and redoes iteration one's reading.
        ...(sessionId ? { resume: sessionId } : {}),
      },
    })) {
      if (message.type === "system" && message.subtype === "init") {
        sessionId = message.session_id;
      }
      if (message.type === "result") {
        result = message;
        // Every result subtype carries session_id, so the driver can resume
        // even after an error. Read it here, not only from the init message.
        if (message.session_id) sessionId = message.session_id;
      }
    }
  } catch (err) {
    // The raise carries the failure text, such as "Reached maximum number of
    // turns". If a result message already arrived, that message is the better
    // source of truth and the loop below handles it. If none arrived, the run
    // failed before producing one and there is nothing to branch on.
    if (!result) {
      return finish("error", `query threw before any result: ${err.message}`);
    }
  }

  if (!result) {
    return finish("error", "the stream ended without a result message");
  }

  // total_cost_usd is present on every subtype, including the error ones.
  // In Python it is typed as optional, so a Python port checks for None.
  totalCostUsd += result.total_cost_usd ?? 0;
  log(
    `iteration ${iteration}: ${result.subtype}` +
      `, cost so far $${totalCostUsd.toFixed(4)}`,
  );

  // ---- the branch this whole module is about --------------------------
  //
  // Two conditions, not one. The structured-outputs page: "A result can also
  // end with subtype `success` but no `structured_output` value ... Treat
  // that case as a failure as well." Its own example treats a result as
  // successful only when the subtype is success AND structured_output is
  // present, and handles every other result as a failure.
  if (result.subtype === "success" && result.structured_output) {
    const answer = result.structured_output;
    if (answer.done) {
      return finish("done", "the agent reported done", answer);
    }
    // Not done, and the agent told you what is left. That list is the next
    // prompt, which is what makes this a loop rather than a retry.
    nextPrompt =
      "Continue. Still outstanding:\n" +
      answer.remaining.map((r) => `- ${r}`).join("\n");
  } else if (result.subtype === "success") {
    // Success with nothing in structured_output. The run ended, the exit
    // looked clean, and no validated object exists to read. This is the
    // break the module walks you into: a driver that tested only the subtype
    // stops here and calls the task finished.
    return finish(
      "failed",
      "subtype success with no structured_output: the run ended without " +
        "producing the object, which the docs say to treat as a failure",
    );
  } else if (result.subtype === "error_max_turns") {
    // Ran out of round trips inside one call. The work is not wrong, it is
    // unfinished, so raise the cap and resume the same session.
    maxTurns += turnBump;
    log(`  hit the turn limit; resuming ${sessionId} with maxTurns=${maxTurns}`);
    nextPrompt = "Continue where you left off.";
  } else {
    // error_max_budget_usd, error_during_execution, and
    // error_max_structured_output_retries all land here. None of them carry a
    // `result` field, and none of them are worth retrying blind: the first
    // means you set the cap, the second means the loop was interrupted, the
    // third means validation failed every attempt within the retry limit.
    //
    // After a session crash the result is error_during_execution, its cost
    // fields may be zeroed, and the process exits after emitting it. A zeroed
    // cost is not a free run.
    return finish("failed", `stopped on ${result.subtype}`);
  }

  // Stop 2, checked after the call rather than before it, because you only
  // know what an iteration cost once it has run.
  if (totalCostUsd >= budgetUsd) {
    return finish(
      "budget",
      `spent an estimated $${totalCostUsd.toFixed(4)} against a $${budgetUsd} budget`,
    );
  }
}

// Stop 3. Falling out of the for loop means the agent never said done.
return finish("cap", `stopped after ${maxIterations} iterations without done`);

function finish(outcome, reason, structured = null) {
  return { outcome, reason, structured, totalCostUsd, sessionId };
}
}

// The seam. driver.mjs imports its query function from here and from nowhere
// else, so the same driver runs against the real SDK or against a script of
// canned results with no API key in the room.
//
// The import of the real package is deferred to the first call. That is what
// keeps `node test.mjs` working on a machine that never ran `npm install`.

let realQuery = null;

/**
* Same signature as the SDK's own query(): takes { prompt, options } and
* returns an async iterator of messages.
*/
export function query(args) {
// An async generator, so the caller's `for await` works before the dynamic
// import has resolved.
return (async function* () {
  if (!realQuery) {
    const mod = await import("@anthropic-ai/claude-agent-sdk");
    realQuery = mod.query;
  }
  yield* realQuery(args);
})();
}

// A stand-in for the SDK's query(), so the driver's branching can be certified
// without an API key and without a model in the loop.
//
// What this certifies: that the driver takes the branch the docs say it should
// take for each result shape. What it does NOT certify: that a real model
// produces those shapes for your prompt. Those are different claims and the
// README says so out loud.
//
// The result shapes below are copied from the agent-loop and structured-outputs
// pages as quoted in curriculum/research/15-loops-plans-and-goals.md. If the
// real result shape changes, this file is wrong and the driver's tests will
// keep passing, which is the standing cost of any fake.

/**
* Build a fake query() from a script of results, one per expected call.
*
* Each entry is the ResultMessage the call should end on. The returned function
* also records what it was called with, so a test can assert on the resume id
* and the raised turn cap rather than on printed output.
*/
export function makeFakeQuery(script, { sessionId = "sess-fake-1" } = {}) {
const calls = [];
let i = 0;

function fakeQuery(args) {
  const index = i++;
  calls.push(args);
  const canned = script[index];
  if (!canned) {
    throw new Error(
      `fake query() called ${index + 1} times but the script has ${script.length} results`,
    );
  }

  return (async function* () {
    // Every session opens with a system init message carrying the id the
    // driver resumes by.
    yield {
      type: "system",
      subtype: "init",
      session_id: sessionId,
      model: "fake-model",
      tools: [],
    };

    const result = {
      type: "result",
      session_id: sessionId,
      num_turns: 1,
      total_cost_usd: 0,
      ...canned,
    };
    yield result;

    // A single-shot query() that ends on an error result yields the result
    // and then raises, per the agent-loop page's note. The fake raises too,
    // because a driver that only works against a fake that never throws is
    // not a driver that works.
    if (result.subtype !== "success") {
      throw new Error(errorTextFor(result.subtype));
    }
  })();
}

fakeQuery.calls = calls;
return fakeQuery;
}

function errorTextFor(subtype) {
if (subtype === "error_max_turns") return "Reached maximum number of turns";
if (subtype === "error_max_budget_usd") return "Budget limit reached";
return `Run ended with ${subtype}`;
}

// ---- the three canned results the module turns on -----------------------

/** Success with a validated object. The only shape that can mean "done". */
export function successWithOutput({ done, remaining = [], cost = 0.01 }) {
return {
  subtype: "success",
  result: done ? "All finished." : "Made progress.",
  structured_output: { done, remaining },
  total_cost_usd: cost,
};
}

/**
* Success with no structured_output. The break. The run ended, the subtype
* reads success, the `result` field carries confident prose, and no validated
* object exists.
*/
export function successWithoutOutput({ cost = 0.01 } = {}) {
return {
  subtype: "success",
  result: "I've finished the refactor and everything looks good.",
  total_cost_usd: cost,
};
}

/** Ran out of round trips. No `result` field, and the session id still works. */
export function maxTurnsError({ cost = 0.02 } = {}) {
return { subtype: "error_max_turns", total_cost_usd: cost };
}

// The break, shown failing. Same canned result, two done-checks.
//
//   node break-demo.mjs
//
// The naive check is the one almost everyone writes first: the subtype says
// success, so the task is finished. The canned result it runs against is the
// one the structured-outputs page warns about, a success that carries no
// structured_output. Nothing errors. Nothing warns. The naive driver stops and
// reports the work done.

import { makeFakeQuery, successWithoutOutput } from "./fake-sdk.mjs";
import { runLoop } from "./driver.mjs";

const canned = [successWithoutOutput({ cost: 0.03 })];

// ---- the naive driver ----------------------------------------------------
const naiveQuery = makeFakeQuery(canned);
let naive = "no result";
for await (const message of naiveQuery({ prompt: "Refactor the auth module.", options: {} })) {
if (message.type === "result") {
  // One condition. This is the bug.
  naive = message.subtype === "success" ? "DONE" : `stopped on ${message.subtype}`;
}
}
console.log("naive check  (subtype only)        ->", naive);
console.log("             what it read as proof ->", JSON.stringify(canned[0].result));
console.log("             structured_output     ->", canned[0].structured_output);

// ---- the driver from driver.mjs -----------------------------------------
const run = await runLoop({
prompt: "Refactor the auth module.",
query: makeFakeQuery(canned),
});
console.log("\ntwo-condition check               ->", run.outcome.toUpperCase());
console.log("             reason                ->", run.reason);

// Run the driver for real: one live session per iteration, against whatever
// directory you start it in.
//
//   ANTHROPIC_API_KEY=sk-ant-... node run.mjs "Add a test for parseArgs, then stop."
//
// Cost is unknown until you run it. It depends on the task, the model, and how
// many iterations the driver takes before something stops it. Watch the running
// total the driver prints and set --budget low the first time.

import { runLoop } from "./driver.mjs";

const prompt =
process.argv[2] ??
"Summarise what this project does, then report done with nothing remaining.";

const budgetIndex = process.argv.indexOf("--budget");
const budgetUsd =
budgetIndex === -1 ? 0.25 : Number(process.argv[budgetIndex + 1]);

console.log(`prompt: ${prompt}`);
console.log(`budget: $${budgetUsd} (estimate, not billing)\n`);

const run = await runLoop({
prompt,
budgetUsd,
maxIterations: 4,
log: (line) => console.log(line),
});

console.log(`\noutcome        ${run.outcome}`);
console.log(`reason         ${run.reason}`);
console.log(`estimated cost $${run.totalCostUsd.toFixed(4)}`);
console.log(`session        ${run.sessionId ?? "(none)"}`);
if (run.structured) console.log(`object         ${JSON.stringify(run.structured)}`);

// Four outcomes reach here: done, failed, budget, cap. Only one of them is the
// task being finished, and the exit code says which.
process.exit(run.outcome === "done" ? 0 : 1);

// The lab's certification. Drives driver.mjs against the fake and asserts the
// four behaviours the module claims. No API key, no network, no cost.
//
//   node test.mjs
//
// The last line prints the counts. Exit 0 with failed=0 is the only passing
// outcome; a run that exits 0 and prints nothing proved nothing, which is the
// mistake this whole module is about.

import { runLoop } from "./driver.mjs";
import {
makeFakeQuery,
successWithOutput,
successWithoutOutput,
maxTurnsError,
} from "./fake-sdk.mjs";

let passed = 0;
let failed = 0;

function check(name, condition, detail = "") {
if (condition) {
  passed++;
  console.log(`  ok    ${name}`);
} else {
  failed++;
  console.log(`  FAIL  ${name}${detail ? `  (${detail})` : ""}`);
}
}

// ---- 1. success without structured_output takes the failure branch -------
{
console.log("\n1. success with no structured_output");
const query = makeFakeQuery([successWithoutOutput({ cost: 0.03 })]);
const run = await runLoop({ prompt: "Refactor the auth module.", query });

console.log(`  outcome=${run.outcome}  reason=${run.reason}`);
check("does not report done", run.outcome !== "done", `outcome=${run.outcome}`);
check("reports failed", run.outcome === "failed");
check("no structured object is handed back", run.structured === null);
check("the fake was called once", query.calls.length === 1);
}

// ---- 2. error_max_turns resumes the session with a raised cap ------------
{
console.log("\n2. error_max_turns resumes with a higher turn cap");
const query = makeFakeQuery([
  maxTurnsError({ cost: 0.02 }),
  successWithOutput({ done: true, cost: 0.02 }),
]);
const run = await runLoop({
  prompt: "Fix the failing tests.",
  query,
  startMaxTurns: 8,
  turnBump: 2,
});

const first = query.calls[0].options;
const second = query.calls[1].options;
console.log(
  `  call 1: maxTurns=${first.maxTurns} resume=${first.resume ?? "(none)"}`,
);
console.log(
  `  call 2: maxTurns=${second.maxTurns} resume=${second.resume ?? "(none)"}`,
);
check("the loop survives the raise that follows an error result", run.outcome === "done");
check("the first call starts a new session", first.resume === undefined);
check("the second call resumes by session id", second.resume === "sess-fake-1");
check("the turn cap went up", second.maxTurns > first.maxTurns,
  `${first.maxTurns} -> ${second.maxTurns}`);
}

// ---- 3. the iteration cap stops a sequence that is never done ------------
{
console.log("\n3. never-done sequence hits the driver's own cap");
const never = Array.from({ length: 10 }, () =>
  successWithOutput({ done: false, remaining: ["still going"], cost: 0.01 }),
);
const query = makeFakeQuery(never);
const run = await runLoop({
  prompt: "Improve this codebase.",
  query,
  maxIterations: 3,
  budgetUsd: 100,
});

console.log(`  outcome=${run.outcome}  calls=${query.calls.length}`);
check("stops on the cap", run.outcome === "cap");
check("makes exactly maxIterations calls", query.calls.length === 3,
  `calls=${query.calls.length}`);
check("each continuation carries the outstanding work",
  String(query.calls[1].prompt).includes("still going"));
}

// ---- 4. cost accumulates across calls ------------------------------------
{
console.log("\n4. cost accumulates across calls, and the budget stops the loop");
const query = makeFakeQuery([
  successWithOutput({ done: false, remaining: ["a"], cost: 0.04 }),
  successWithOutput({ done: false, remaining: ["b"], cost: 0.04 }),
  successWithOutput({ done: true, cost: 0.04 }),
]);
const run = await runLoop({
  prompt: "Do the thing.",
  query,
  maxIterations: 5,
  budgetUsd: 0.07,
});

console.log(
  `  outcome=${run.outcome}  totalCostUsd=${run.totalCostUsd.toFixed(4)}  calls=${query.calls.length}`,
);
check("the driver's total is the sum of the per-call totals",
  Math.abs(run.totalCostUsd - 0.08) < 1e-9, `got ${run.totalCostUsd}`);
check("the budget stops the loop before the third call", run.outcome === "budget");
check("the remaining budget is passed down to the call",
  Math.abs(query.calls[1].options.maxBudgetUsd - 0.03) < 1e-9,
  `got ${query.calls[1].options.maxBudgetUsd}`);
}

console.log(`\npassed=${passed} failed=${failed}`);
process.exit(failed === 0 ? 0 : 1);

{
"name": "loop-driver",
"private": true,
"type": "module",
"description": "Module 21 lab: a loop driver that stops on a schema-validated done-check, resumes on error_max_turns, and caps itself in iterations and dollars.",
"scripts": {
  "test": "node test.mjs",
  "start": "node run.mjs"
},
"dependencies": {
  "@anthropic-ai/claude-agent-sdk": "0.3.251"
}
}