feat(agency): robust structured output with brace-matched JSON extraction and validation retries

parseStructuredOutput now:
- Tries direct JSON parse (happy path)
- Strips markdown code fences (```json ... ```)
- Falls back to brace-matched extraction that walks the string respecting
  quote and escape state, so nested braces in string values and trailing
  commentary after a valid JSON object no longer break parsing

Agency execute() now retries validation failures:
- New controls.maxValidationRetries field (default 1)
- When opts.output is set and parsed is undefined, retry the generation
  with an error-feedback hint appended to the prompt so the model can
  self-correct

Fixes the class of failures where providers return valid JSON followed
by commentary.

Author: jddunn

dist/api/AgentOS.js

@@ -55,6 +55,30 @@ export interface AgentOptions extends BaseAgentConfig {
     onFallback?: (error: Error, fallbackProvider: string) => void;
     /** Model router for intelligent provider selection per-call. */
     router?: IModelRouter;
+    /**
+     * Optional Zod schema for validating the LLM's structured output.
+     *
+     * When provided, the agent's `generate()` result includes a `parsed` field
+     * with the Zod-validated and typed output. JSON extraction and validation
+     * happen automatically in the `onAfterGeneration` hook. On validation failure,
+     * the agent retries internally (up to `controls.maxValidationRetries ?? 1`).
+     *
+     * When omitted, behavior is unchanged — `result.parsed` is undefined.
+     * This is a non-breaking additive change.
+     *
+     * @example
+     * ```ts
+     * import { z } from 'zod';
+     * const myAgent = agent({
+     *   name: 'Extractor',
+     *   instructions: 'Extract entities as JSON',
+     *   responseSchema: z.object({ entities: z.array(z.string()) }),
+     * });
+     * const result = await myAgent.generate('Find entities in: ...');
+     * console.log(result.parsed?.entities); // string[]
+     * ```
+     */
+    responseSchema?: import('zod').ZodType;
     /** Pre-generation hook, called before each LLM step. */
     onBeforeGeneration?: (context: GenerationHookContext) => Promise<GenerationHookContext | void>;
     /** Post-generation hook, called after each LLM step. */