@smthrs/harness 0.0.0-stage → 1.0.0-rc.3

package/dist/esm/StructuredOutput.js

@@ -0,0 +1,430 @@
+/**
+ * Turning one agent's final text into a value the declared output schema
+ * accepts, or into a typed failure.
+ *
+ * A model may answer with a bare JSON document, prose wrapped around a JSON
+ * document, a fenced block, or JSON of the wrong shape. Downstream nodes must
+ * never receive that ambiguity, so this module implements the recovery
+ * contract in `../docs/concepts.md#structured-output`:
+ *
+ * 1. parse the complete, BOM-stripped response and decode it;
+ * 2. otherwise scan once for balanced JSON containers, take the container
+ *    whose matching close ends last, and decode that;
+ * 3. otherwise report a typed {@link StructuredOutputFailure} carrying bounded
+ *    diagnostics, which is what a caller re-prompts with when it still holds a
+ *    correction slot.
+ *
+ * Every candidate is decoded by the declared schema. Extraction never relaxes
+ * validation: it only decides which bytes are offered to it, and the schema may
+ * accept any JSON root rather than silently requiring an object.
+ *
+ * The prompt half is {@link instructions}. It renders the declared schema as a
+ * JSON Schema document placed in the run's system teaching, which is BAML's
+ * `ctx.output_format` injection reached through the seam the vault note
+ * specifies — the model is told the shape before it answers, and the answer is
+ * still validated locally. Provider acceptance is not a cast.
+ *
+ * Reference consulted: the `generateObject` function from Effect's
+ * `effect/unstable/ai/LanguageModel` module, which
+ * sends `responseFormat: { type: "json", schema }` and then decodes the result
+ * with the same schema, failing `AiError.InvalidOutputError` on mismatch. The
+ * decode-and-fail-typed half is copied. The provider `responseFormat` half is
+ * not reachable here: `@smthrs/model`'s `ModelRequest.GenerationParams` has no
+ * response-format field, and the cell loop's final answer is a `Cell.Complete`
+ * `output` string rather than a provider-decoded value, so the schema is
+ * carried in the prompt and enforced at this boundary.
+ *
+ * @since 0.1.0
+ */
+import * as Digest from "@smthrs/core/Digest";
+import * as Fault from "@smthrs/flow/Fault";
+import * as Effect from "effect/Effect";
+import * as Schema from "effect/Schema";
+import * as SchemaIssue from "effect/SchemaIssue";
+import * as elide from "./internal/elide.js";
+/**
+ * Stable reasons a structured-output boundary failed.
+ *
+ * `invalid_json` means candidate text was not JSON. `schema_mismatch` means
+ * JSON parsed but the declared schema refused it. `no_candidate` means the
+ * answer contained no candidate text. `correction_exhausted` means the
+ * boundary had already spent its correction budget.
+ *
+ * @category models
+ * @since 1.0.0-rc.0
+ * @slop
+ */
+export const StructuredOutputFailureCode = Schema.Literals([
+    "invalid_json",
+    "schema_mismatch",
+    "no_candidate",
+    "correction_exhausted"
+]);
+/**
+ * Stable reasons an individual structured-output issue was reported.
+ *
+ * `invalid_json` means candidate text was not JSON. `no_candidate` means the
+ * answer contained no candidate text. `invalid_type` means a decoded value had
+ * the wrong type. `invalid_value` means a value of the expected type was still
+ * invalid. `missing_key` means a required property was absent.
+ * `unexpected_key` means a prohibited extra property was present. `forbidden`
+ * means decoding attempted an operation the schema forbids. `one_of` means
+ * more than one exclusive union member matched. `constraint` means a schema
+ * check or empty-union fallback failed.
+ *
+ * @category models
+ * @since 1.0.0-rc.0
+ * @slop
+ */
+export const OutputIssueCode = Schema.Literals([
+    "invalid_json",
+    "no_candidate",
+    "invalid_type",
+    "invalid_value",
+    "missing_key",
+    "unexpected_key",
+    "forbidden",
+    "one_of",
+    "constraint"
+]);
+/**
+ * One bounded issue raised while decoding structured output.
+ *
+ * @category models
+ * @since 1.0.0-rc.0
+ * @slop
+ */
+export class OutputIssue extends Schema.Class("flows/harness/StructuredOutput/OutputIssue")({
+    /** The stable reason this issue was reported. */
+    code: OutputIssueCode,
+    /** The JSON path of the offending value, dot/bracket joined; empty for the root. */
+    path: Schema.String,
+    /** What the decoder wanted there. */
+    message: Schema.String
+}) {
+    /** Renders the issue for existing prose-oriented consumers. */
+    toString() {
+        return this.path === "" ? this.message : `${this.path}: ${this.message}`;
+    }
+}
+/**
+ * The terminal failure of one structured-output boundary.
+ *
+ * It carries what an operator needs to tell two identical-looking refusals
+ * apart: which schema was demanded, how many correction slots the attempt
+ * consumed out of its budget, the digest of the last candidate that was
+ * offered to the decoder, and the bounded issue list.
+ *
+ * @category errors
+ * @since 0.1.0
+ * @slop
+ */
+export class StructuredOutputFailure extends Schema.TaggedError()("/harness/StructuredOutputFailure", {
+    /** The stable reason this boundary failed. */
+    code: StructuredOutputFailureCode,
+    /** The declared output schema's canonical digest. */
+    schema: Schema.String,
+    /** SHA-256 of the text the decoder was last offered. */
+    candidate: Schema.String,
+    /** Correction attempts already spent on this boundary. */
+    corrections: Schema.Number,
+    /** The correction budget the boundary was declared with. */
+    limit: Schema.Number,
+    /** At most {@link maxIssues} structured validation issues. */
+    issues: Schema.Array(OutputIssue),
+    message: Schema.String
+}) {
+}
+// The model's answer did not fit the declared shape: another model may answer it.
+Fault.register("/harness/StructuredOutputFailure", "dependency");
+/**
+ * The most validation issues a failure or a correction prompt carries.
+ *
+ * Bounded for the same reason smithers bounds its own validation summary: a
+ * wide struct that mismatched everywhere would otherwise spend the correction
+ * prompt's whole budget restating the schema back to the model.
+ *
+ * @category constants
+ * @since 0.1.0
+ * @slop
+ */
+export const maxIssues = 5;
+/**
+ * The JSON Schema document for a declared output schema.
+ *
+ * @category conversions
+ * @since 0.1.0
+ * @slop
+ */
+export const jsonSchema = (schema) => {
+    const document = Schema.toJsonSchemaDocument(schema, { onExcessProperty: "error" });
+    return Object.keys(document.definitions).length > 0
+        ? { ...document.schema, $defs: document.definitions }
+        : document.schema;
+};
+/**
+ * The canonical digest of a declared output schema.
+ *
+ * Two declarations that render the same JSON Schema name the same boundary, so
+ * this is what a step key folds in rather than the schema value itself.
+ *
+ * @category identity
+ * @since 0.1.0
+ * @slop
+ */
+export const digest = (schema) => Digest.digest(Digest.canonical(jsonSchema(schema)));
+/**
+ * The system teaching that tells a run what its final `output` must be.
+ *
+ * Written against the cell contract: a cell finishes by calling
+ * `ctx.done(output)`, and the sandbox rejects a returned transition, so the
+ * instruction is about the argument of that call and not about the assistant
+ * message around it. The run passes the value itself: a structured value
+ * reaches {@link decode} as canonical JSON, and a string as its own text.
+ *
+ * @category prompts
+ * @since 0.1.0
+ * @slop
+ */
+export const instructions = (schema) => `## Required output shape
+
+Finish by calling \`ctx.done(output)\` with the value itself: a JavaScript
+value that validates against this JSON Schema, such as
+\`ctx.done({ ...fields })\`. Do not stringify it, and add no prose around it.
+
+\`\`\`json
+${JSON.stringify(jsonSchema(schema), null, 2)}
+\`\`\``;
+/**
+ * The digest of one failure's rendered validation issues.
+ *
+ * Two rejections that raised the same issues share this digest, which is what a
+ * record carries instead of the issues themselves: a journal that repeated the
+ * validator's prose for every correction would grow with the model's verbosity,
+ * and what an operator actually asks is whether the second answer was wrong the
+ * same way as the first.
+ *
+ * @category identity
+ * @since 0.1.0
+ */
+export const issuesDigest = (failure) => Digest.digest(Digest.canonical(failure.issues.map((issue) => ({ path: issue.path, message: issue.message }))));
+/**
+ * The correction teaching appended when a candidate failed to decode.
+ *
+ * It restates the schema and the bounded diagnostics and nothing else: a
+ * correction does not reinterpret the task, so the original prompt is repeated
+ * verbatim by the caller and only this section is new.
+ *
+ * @category prompts
+ * @since 0.1.0
+ * @slop
+ */
+export const correction = (failure) => `## Your previous answer did not validate
+
+The output you passed to \`ctx.done\` could not be decoded against the required
+schema. Call \`ctx.done(output)\` again with the same information as a value
+that validates.
+
+Validation issues:
+${failure.issues.map((issue) => `- ${issue}`).join("\n")}`;
+const stripBom = (text) => text.charCodeAt(0) === 0xfeff ? text.slice(1) : text;
+/**
+ * The balanced JSON container whose matching close ends last.
+ *
+ * Scans once, left to right, tracking object and array delimiters, quoted
+ * strings, and escapes. A mismatched close abandons the open container rather
+ * than pairing it with the wrong opener, so a truncated prefix cannot be
+ * reported as a complete document. `undefined` means the text holds no
+ * balanced container at all.
+ *
+ * This is the array-capable form of smithers' `extractLastBalancedJson`, which
+ * is object-only.
+ *
+ * @category extraction
+ * @since 0.1.0
+ * @slop
+ */
+export const lastBalanced = (text) => {
+    const stack = [];
+    let start = -1;
+    let found = undefined;
+    let quoted = false;
+    let escaped = false;
+    for (let index = 0; index < text.length; index++) {
+        const char = text[index];
+        if (quoted) {
+            if (escaped)
+                escaped = false;
+            else if (char === "\\")
+                escaped = true;
+            else if (char === "\"")
+                quoted = false;
+            continue;
+        }
+        if (char === "\"") {
+            if (stack.length > 0)
+                quoted = true;
+            continue;
+        }
+        if (char === "{" || char === "[") {
+            if (stack.length === 0)
+                start = index;
+            stack.push(char);
+            continue;
+        }
+        if (char === "}" || char === "]") {
+            const opener = stack.pop();
+            if (opener === undefined)
+                continue;
+            if ((char === "}") !== (opener === "{")) {
+                // Mismatched close: abandon the whole open container rather than
+                // reporting a pairing the text does not contain.
+                stack.length = 0;
+                start = -1;
+                continue;
+            }
+            if (stack.length === 0 && start >= 0)
+                found = text.slice(start, index + 1);
+        }
+    }
+    return found;
+};
+/**
+ * The candidates offered to the decoder, in the declared recovery order.
+ *
+ * @category extraction
+ * @since 0.1.0
+ * @slop
+ */
+export const candidates = (text) => {
+    const stripped = stripBom(text).trim();
+    const balanced = lastBalanced(stripped);
+    return balanced === undefined || balanced === stripped ? [stripped] : [stripped, balanced];
+};
+const issueMessage = (message) => elide.head(message, 240, "reissue the answer to see the whole issue");
+const issuePath = (path) => path.map((segment, index) => typeof segment === "number" ? `[${segment}]` : `${index === 0 ? "" : "."}${String(segment)}`).join("");
+const issueCodeSeparator = "\u0000";
+const leafCodes = {
+    InvalidType: "invalid_type",
+    InvalidValue: "invalid_value",
+    MissingKey: "missing_key",
+    UnexpectedKey: "unexpected_key",
+    Forbidden: "forbidden",
+    OneOf: "one_of"
+};
+const formatSchemaIssues = SchemaIssue.makeFormatterStandardSchemaV1({
+    leafHook: (issue) => `${issue._tag}${issueCodeSeparator}${SchemaIssue.defaultLeafHook(issue)}`
+});
+const schemaIssuesOf = (error) => formatSchemaIssues(error.issue).issues.slice(0, maxIssues).map((issue) => {
+    const separator = issue.message.indexOf(issueCodeSeparator);
+    const tagged = separator >= 0;
+    return new OutputIssue({
+        code: tagged ? leafCodes[issue.message.slice(0, separator)] : "constraint",
+        path: issuePath(issue.path),
+        message: issueMessage(tagged ? issue.message.slice(separator + issueCodeSeparator.length) : issue.message)
+    });
+});
+const textIssuesOf = (code, message) => message.split("\n").map((line) => line.trim()).filter((line) => line.length > 0).slice(0, maxIssues).map((line) => new OutputIssue({ code, path: "", message: issueMessage(line) }));
+const quoted = (text) => {
+    try {
+        return typeof JSON.parse(text) === "string";
+    }
+    catch {
+        return false;
+    }
+};
+/**
+ * Decodes one agent answer with the declared output schema.
+ *
+ * Decodes an original completion value first when supplied. Only a string
+ * refused for its type proceeds to legacy text extraction; refinements and
+ * nonstring failures retain the original value's diagnostics.
+ * Tries every {@link candidates} entry in order and returns the first the
+ * schema accepts, then the answer itself, untrimmed, as a string unless it is
+ * a JSON string literal, which is how a `ctx.done("text")` answer reaches a
+ * string schema. When none does, the failure reports the issues raised by the
+ * LAST candidate, which is the narrowest text the extractor could isolate and
+ * therefore the one a correction prompt should be about.
+ *
+ * @category decoding
+ * @since 0.1.0
+ * @slop
+ */
+export const decode = (schema, text, attempt, value) => Effect.gen(function* () {
+    const offered = candidates(text);
+    const decoder = Schema.decodeUnknownEffect(schema);
+    let code = "no_candidate";
+    let issues = [
+        new OutputIssue({ code: "no_candidate", path: "", message: "the answer held no JSON document" })
+    ];
+    if (value !== undefined) {
+        const result = yield* Effect.result(decoder(value));
+        if (result._tag === "Success")
+            return result.success;
+        const rawIssues = schemaIssuesOf(result.failure);
+        // Extraction is only for text offered to a schema expecting another type.
+        // Preserve string refinements and nonstring type failures on the value.
+        if (typeof value !== "string" || !rawIssues.every((issue) => issue.code === "invalid_type")) {
+            return yield* new StructuredOutputFailure({
+                code: attempt.corrections >= attempt.limit ? "correction_exhausted" : "schema_mismatch",
+                schema: digest(schema),
+                candidate: Digest.digest(JSON.stringify(value)),
+                corrections: attempt.corrections,
+                limit: attempt.limit,
+                issues: rawIssues,
+                message: `The agent's answer did not validate against its declared output schema after ${attempt.corrections} of ${attempt.limit} corrections`
+            });
+        }
+    }
+    for (const candidate of offered) {
+        if (candidate.length === 0)
+            continue;
+        let parsed;
+        try {
+            parsed = JSON.parse(candidate);
+        }
+        catch (error) {
+            code = "invalid_json";
+            // The ECMAScript JSON parser throws a SyntaxError with a message.
+            issues = textIssuesOf("invalid_json", error.message);
+            continue;
+        }
+        const result = yield* Effect.result(decoder(parsed));
+        if (result._tag === "Success")
+            return result.success;
+        code = "schema_mismatch";
+        issues = schemaIssuesOf(result.failure);
+    }
+    // `ctx.done("text")` reaches the boundary as the text itself, not as a
+    // JSON string, so a schema that accepts the raw answer takes it as it is.
+    // An answer that is a whole JSON string literal already said which string
+    // it meant, and its quotes are not part of it.
+    // Untrimmed, so an empty or whitespace-bearing string arrives as written.
+    const raw = stripBom(text);
+    if (!quoted(offered[0])) {
+        const result = yield* Effect.result(decoder(raw));
+        if (result._tag === "Success")
+            return result.success;
+        // A string the schema read and refused on its merits (too short, not
+        // one of the literals) is the issue to correct, not the JSON parse. A
+        // schema that wanted no string at all keeps the JSON diagnosis.
+        const rawIssues = schemaIssuesOf(result.failure);
+        if (code === "invalid_json" && rawIssues[0]?.code !== "invalid_type") {
+            code = "schema_mismatch";
+            issues = rawIssues;
+        }
+    }
+    return yield* new StructuredOutputFailure({
+        // Once the budget is spent, exhaustion is the actionable classification;
+        // the issue records retain whether the last candidate was invalid JSON or
+        // failed schema decoding.
+        code: attempt.corrections >= attempt.limit ? "correction_exhausted" : code,
+        schema: digest(schema),
+        candidate: Digest.digest(offered[offered.length - 1]),
+        corrections: attempt.corrections,
+        limit: attempt.limit,
+        issues,
+        message: `The agent's answer did not validate against its declared output schema after ${attempt.corrections} of ${attempt.limit} corrections`
+    });
+});
+//# sourceMappingURL=StructuredOutput.js.map

package/dist/esm/StructuredOutput.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"StructuredOutput.js","sourceRoot":"","sources":["../../src/StructuredOutput.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Turning one agent's final text into a value the declared output schema\n * accepts, or into a typed failure.\n *\n * A model may answer with a bare JSON document, prose wrapped around a JSON\n * document, a fenced block, or JSON of the wrong shape. Downstream nodes must\n * never receive that ambiguity, so this module implements the recovery\n * contract in `../docs/concepts.md#structured-output`:\n *\n * 1. parse the complete, BOM-stripped response and decode it;\n * 2. otherwise scan once for balanced JSON containers, take the container\n *    whose matching close ends last, and decode that;\n * 3. otherwise report a typed {@link StructuredOutputFailure} carrying bounded\n *    diagnostics, which is what a caller re-prompts with when it still holds a\n *    correction slot.\n *\n * Every candidate is decoded by the declared schema. Extraction never relaxes\n * validation: it only decides which bytes are offered to it, and the schema may\n * accept any JSON root rather than silently requiring an object.\n *\n * The prompt half is {@link instructions}. It renders the declared schema as a\n * JSON Schema document placed in the run's system teaching, which is BAML's\n * `ctx.output_format` injection reached through the seam the vault note\n * specifies — the model is told the shape before it answers, and the answer is\n * still validated locally. Provider acceptance is not a cast.\n *\n * Reference consulted: the `generateObject` function from Effect's\n * `effect/unstable/ai/LanguageModel` module, which\n * sends `responseFormat: { type: \"json\", schema }` and then decodes the result\n * with the same schema, failing `AiError.InvalidOutputError` on mismatch. The\n * decode-and-fail-typed half is copied. The provider `responseFormat` half is\n * not reachable here: `@smthrs/model`'s `ModelRequest.GenerationParams` has no\n * response-format field, and the cell loop's final answer is a `Cell.Complete`\n * `output` string rather than a provider-decoded value, so the schema is\n * carried in the prompt and enforced at this boundary.\n *\n * @since 0.1.0\n */\n\nimport * as Digest from \"@smthrs/core/Digest\"\nimport * as Fault from \"@smthrs/flow/Fault\"\nimport * as Effect from \"effect/Effect\"\nimport * as Schema from \"effect/Schema\"\nimport * as SchemaIssue from \"effect/SchemaIssue\"\nimport * as elide from \"./internal/elide.ts\"\n\n/**\n * Stable reasons a structured-output boundary failed.\n *\n * `invalid_json` means candidate text was not JSON. `schema_mismatch` means\n * JSON parsed but the declared schema refused it. `no_candidate` means the\n * answer contained no candidate text. `correction_exhausted` means the\n * boundary had already spent its correction budget.\n *\n * @category models\n * @since 1.0.0-rc.0\n * @slop\n */\nexport const StructuredOutputFailureCode = Schema.Literals([\n  \"invalid_json\",\n  \"schema_mismatch\",\n  \"no_candidate\",\n  \"correction_exhausted\"\n])\n\n/**\n * Stable reasons a structured-output boundary failed.\n *\n * @category models\n * @since 1.0.0-rc.0\n * @slop\n */\nexport type StructuredOutputFailureCode = typeof StructuredOutputFailureCode.Type\n\n/**\n * Stable reasons an individual structured-output issue was reported.\n *\n * `invalid_json` means candidate text was not JSON. `no_candidate` means the\n * answer contained no candidate text. `invalid_type` means a decoded value had\n * the wrong type. `invalid_value` means a value of the expected type was still\n * invalid. `missing_key` means a required property was absent.\n * `unexpected_key` means a prohibited extra property was present. `forbidden`\n * means decoding attempted an operation the schema forbids. `one_of` means\n * more than one exclusive union member matched. `constraint` means a schema\n * check or empty-union fallback failed.\n *\n * @category models\n * @since 1.0.0-rc.0\n * @slop\n */\nexport const OutputIssueCode = Schema.Literals([\n  \"invalid_json\",\n  \"no_candidate\",\n  \"invalid_type\",\n  \"invalid_value\",\n  \"missing_key\",\n  \"unexpected_key\",\n  \"forbidden\",\n  \"one_of\",\n  \"constraint\"\n])\n\n/**\n * Stable reasons an individual structured-output issue was reported.\n *\n * @category models\n * @since 1.0.0-rc.0\n * @slop\n */\nexport type OutputIssueCode = typeof OutputIssueCode.Type\n\n/**\n * One bounded issue raised while decoding structured output.\n *\n * @category models\n * @since 1.0.0-rc.0\n * @slop\n */\nexport class OutputIssue extends Schema.Class<OutputIssue>(\"flows/harness/StructuredOutput/OutputIssue\")({\n  /** The stable reason this issue was reported. */\n  code: OutputIssueCode,\n  /** The JSON path of the offending value, dot/bracket joined; empty for the root. */\n  path: Schema.String,\n  /** What the decoder wanted there. */\n  message: Schema.String\n}) {\n  /** Renders the issue for existing prose-oriented consumers. */\n  override toString(): string {\n    return this.path === \"\" ? this.message : `${this.path}: ${this.message}`\n  }\n}\n\n/**\n * The terminal failure of one structured-output boundary.\n *\n * It carries what an operator needs to tell two identical-looking refusals\n * apart: which schema was demanded, how many correction slots the attempt\n * consumed out of its budget, the digest of the last candidate that was\n * offered to the decoder, and the bounded issue list.\n *\n * @category errors\n * @since 0.1.0\n * @slop\n */\nexport class StructuredOutputFailure extends Schema.TaggedError<StructuredOutputFailure>()(\n  \"/harness/StructuredOutputFailure\",\n  {\n    /** The stable reason this boundary failed. */\n    code: StructuredOutputFailureCode,\n    /** The declared output schema's canonical digest. */\n    schema: Schema.String,\n    /** SHA-256 of the text the decoder was last offered. */\n    candidate: Schema.String,\n    /** Correction attempts already spent on this boundary. */\n    corrections: Schema.Number,\n    /** The correction budget the boundary was declared with. */\n    limit: Schema.Number,\n    /** At most {@link maxIssues} structured validation issues. */\n    issues: Schema.Array(OutputIssue),\n    message: Schema.String\n  }\n) {}\n// The model's answer did not fit the declared shape: another model may answer it.\nFault.register(\"/harness/StructuredOutputFailure\", \"dependency\")\n\n/**\n * The most validation issues a failure or a correction prompt carries.\n *\n * Bounded for the same reason smithers bounds its own validation summary: a\n * wide struct that mismatched everywhere would otherwise spend the correction\n * prompt's whole budget restating the schema back to the model.\n *\n * @category constants\n * @since 0.1.0\n * @slop\n */\nexport const maxIssues = 5\n\n/**\n * The JSON Schema document for a declared output schema.\n *\n * @category conversions\n * @since 0.1.0\n * @slop\n */\nexport const jsonSchema = (schema: Schema.Top): unknown => {\n  const document = Schema.toJsonSchemaDocument(schema, { onExcessProperty: \"error\" })\n  return Object.keys(document.definitions).length > 0\n    ? { ...document.schema, $defs: document.definitions }\n    : document.schema\n}\n\n/**\n * The canonical digest of a declared output schema.\n *\n * Two declarations that render the same JSON Schema name the same boundary, so\n * this is what a step key folds in rather than the schema value itself.\n *\n * @category identity\n * @since 0.1.0\n * @slop\n */\nexport const digest = (schema: Schema.Top): string => Digest.digest(Digest.canonical(jsonSchema(schema)))\n\n/**\n * The system teaching that tells a run what its final `output` must be.\n *\n * Written against the cell contract: a cell finishes by calling\n * `ctx.done(output)`, and the sandbox rejects a returned transition, so the\n * instruction is about the argument of that call and not about the assistant\n * message around it. The run passes the value itself: a structured value\n * reaches {@link decode} as canonical JSON, and a string as its own text.\n *\n * @category prompts\n * @since 0.1.0\n * @slop\n */\nexport const instructions = (schema: Schema.Top): string =>\n  `## Required output shape\n\nFinish by calling \\`ctx.done(output)\\` with the value itself: a JavaScript\nvalue that validates against this JSON Schema, such as\n\\`ctx.done({ ...fields })\\`. Do not stringify it, and add no prose around it.\n\n\\`\\`\\`json\n${JSON.stringify(jsonSchema(schema), null, 2)}\n\\`\\`\\``\n\n/**\n * The digest of one failure's rendered validation issues.\n *\n * Two rejections that raised the same issues share this digest, which is what a\n * record carries instead of the issues themselves: a journal that repeated the\n * validator's prose for every correction would grow with the model's verbosity,\n * and what an operator actually asks is whether the second answer was wrong the\n * same way as the first.\n *\n * @category identity\n * @since 0.1.0\n */\nexport const issuesDigest = (failure: StructuredOutputFailure): string =>\n  Digest.digest(\n    Digest.canonical(failure.issues.map((issue) => ({ path: issue.path, message: issue.message })))\n  )\n\n/**\n * The correction teaching appended when a candidate failed to decode.\n *\n * It restates the schema and the bounded diagnostics and nothing else: a\n * correction does not reinterpret the task, so the original prompt is repeated\n * verbatim by the caller and only this section is new.\n *\n * @category prompts\n * @since 0.1.0\n * @slop\n */\nexport const correction = (failure: StructuredOutputFailure): string =>\n  `## Your previous answer did not validate\n\nThe output you passed to \\`ctx.done\\` could not be decoded against the required\nschema. Call \\`ctx.done(output)\\` again with the same information as a value\nthat validates.\n\nValidation issues:\n${failure.issues.map((issue) => `- ${issue}`).join(\"\\n\")}`\n\nconst stripBom = (text: string): string => text.charCodeAt(0) === 0xfeff ? text.slice(1) : text\n\n/**\n * The balanced JSON container whose matching close ends last.\n *\n * Scans once, left to right, tracking object and array delimiters, quoted\n * strings, and escapes. A mismatched close abandons the open container rather\n * than pairing it with the wrong opener, so a truncated prefix cannot be\n * reported as a complete document. `undefined` means the text holds no\n * balanced container at all.\n *\n * This is the array-capable form of smithers' `extractLastBalancedJson`, which\n * is object-only.\n *\n * @category extraction\n * @since 0.1.0\n * @slop\n */\nexport const lastBalanced = (text: string): string | undefined => {\n  const stack: Array<string> = []\n  let start = -1\n  let found: string | undefined = undefined\n  let quoted = false\n  let escaped = false\n  for (let index = 0; index < text.length; index++) {\n    const char = text[index]!\n    if (quoted) {\n      if (escaped) escaped = false\n      else if (char === \"\\\\\") escaped = true\n      else if (char === \"\\\"\") quoted = false\n      continue\n    }\n    if (char === \"\\\"\") {\n      if (stack.length > 0) quoted = true\n      continue\n    }\n    if (char === \"{\" || char === \"[\") {\n      if (stack.length === 0) start = index\n      stack.push(char)\n      continue\n    }\n    if (char === \"}\" || char === \"]\") {\n      const opener = stack.pop()\n      if (opener === undefined) continue\n      if ((char === \"}\") !== (opener === \"{\")) {\n        // Mismatched close: abandon the whole open container rather than\n        // reporting a pairing the text does not contain.\n        stack.length = 0\n        start = -1\n        continue\n      }\n      if (stack.length === 0 && start >= 0) found = text.slice(start, index + 1)\n    }\n  }\n  return found\n}\n\n/**\n * The candidates offered to the decoder, in the declared recovery order.\n *\n * @category extraction\n * @since 0.1.0\n * @slop\n */\nexport const candidates = (text: string): ReadonlyArray<string> => {\n  const stripped = stripBom(text).trim()\n  const balanced = lastBalanced(stripped)\n  return balanced === undefined || balanced === stripped ? [stripped] : [stripped, balanced]\n}\n\nconst issueMessage = (message: string): string => elide.head(message, 240, \"reissue the answer to see the whole issue\")\n\nconst issuePath = (path: ReadonlyArray<PropertyKey>): string =>\n  path.map((segment, index) =>\n    typeof segment === \"number\" ? `[${segment}]` : `${index === 0 ? \"\" : \".\"}${String(segment)}`\n  ).join(\"\")\n\ntype FormattedIssue = {\n  readonly message: string\n  readonly path: ReadonlyArray<PropertyKey>\n}\n\nconst issueCodeSeparator = \"\\u0000\"\n\nconst leafCodes: Record<SchemaIssue.Leaf[\"_tag\"], OutputIssueCode> = {\n  InvalidType: \"invalid_type\",\n  InvalidValue: \"invalid_value\",\n  MissingKey: \"missing_key\",\n  UnexpectedKey: \"unexpected_key\",\n  Forbidden: \"forbidden\",\n  OneOf: \"one_of\"\n}\n\nconst formatSchemaIssues = SchemaIssue.makeFormatterStandardSchemaV1({\n  leafHook: (issue) => `${issue._tag}${issueCodeSeparator}${SchemaIssue.defaultLeafHook(issue)}`\n})\n\nconst schemaIssuesOf = (error: Schema.SchemaError): ReadonlyArray<OutputIssue> =>\n  (formatSchemaIssues(error.issue).issues as ReadonlyArray<FormattedIssue>).slice(0, maxIssues).map((issue) => {\n    const separator = issue.message.indexOf(issueCodeSeparator)\n    const tagged = separator >= 0\n    return new OutputIssue({\n      code: tagged ? leafCodes[issue.message.slice(0, separator) as SchemaIssue.Leaf[\"_tag\"]] : \"constraint\",\n      path: issuePath(issue.path),\n      message: issueMessage(tagged ? issue.message.slice(separator + issueCodeSeparator.length) : issue.message)\n    })\n  })\n\nconst textIssuesOf = (code: OutputIssueCode, message: string): ReadonlyArray<OutputIssue> =>\n  message.split(\"\\n\").map((line) => line.trim()).filter((line) => line.length > 0).slice(0, maxIssues).map((line) =>\n    new OutputIssue({ code, path: \"\", message: issueMessage(line) })\n  )\n\nconst quoted = (text: string): boolean => {\n  try {\n    return typeof JSON.parse(text) === \"string\"\n  } catch {\n    return false\n  }\n}\n\n/**\n * Decodes one agent answer with the declared output schema.\n *\n * Decodes an original completion value first when supplied. Only a string\n * refused for its type proceeds to legacy text extraction; refinements and\n * nonstring failures retain the original value's diagnostics.\n * Tries every {@link candidates} entry in order and returns the first the\n * schema accepts, then the answer itself, untrimmed, as a string unless it is\n * a JSON string literal, which is how a `ctx.done(\"text\")` answer reaches a\n * string schema. When none does, the failure reports the issues raised by the\n * LAST candidate, which is the narrowest text the extractor could isolate and\n * therefore the one a correction prompt should be about.\n *\n * @category decoding\n * @since 0.1.0\n * @slop\n */\nexport const decode = <S extends Schema.Top>(\n  schema: S,\n  text: string,\n  attempt: { readonly corrections: number; readonly limit: number },\n  value?: Schema.Json | undefined\n): Effect.Effect<S[\"Type\"], StructuredOutputFailure, S[\"DecodingServices\"]> =>\n  Effect.gen(function*() {\n    const offered = candidates(text)\n    const decoder = Schema.decodeUnknownEffect(schema)\n    let code: StructuredOutputFailureCode = \"no_candidate\"\n    let issues: ReadonlyArray<OutputIssue> = [\n      new OutputIssue({ code: \"no_candidate\", path: \"\", message: \"the answer held no JSON document\" })\n    ]\n    if (value !== undefined) {\n      const result = yield* Effect.result(decoder(value))\n      if (result._tag === \"Success\") return result.success\n      const rawIssues = schemaIssuesOf(result.failure)\n      // Extraction is only for text offered to a schema expecting another type.\n      // Preserve string refinements and nonstring type failures on the value.\n      if (typeof value !== \"string\" || !rawIssues.every((issue) => issue.code === \"invalid_type\")) {\n        return yield* new StructuredOutputFailure({\n          code: attempt.corrections >= attempt.limit ? \"correction_exhausted\" : \"schema_mismatch\",\n          schema: digest(schema),\n          candidate: Digest.digest(JSON.stringify(value)),\n          corrections: attempt.corrections,\n          limit: attempt.limit,\n          issues: rawIssues,\n          message:\n            `The agent's answer did not validate against its declared output schema after ${attempt.corrections} of ${attempt.limit} corrections`\n        })\n      }\n    }\n    for (const candidate of offered) {\n      if (candidate.length === 0) continue\n      let parsed: unknown\n      try {\n        parsed = JSON.parse(candidate)\n      } catch (error) {\n        code = \"invalid_json\"\n        // The ECMAScript JSON parser throws a SyntaxError with a message.\n        issues = textIssuesOf(\"invalid_json\", (error as SyntaxError).message)\n        continue\n      }\n      const result = yield* Effect.result(decoder(parsed))\n      if (result._tag === \"Success\") return result.success\n      code = \"schema_mismatch\"\n      issues = schemaIssuesOf(result.failure)\n    }\n    // `ctx.done(\"text\")` reaches the boundary as the text itself, not as a\n    // JSON string, so a schema that accepts the raw answer takes it as it is.\n    // An answer that is a whole JSON string literal already said which string\n    // it meant, and its quotes are not part of it.\n    // Untrimmed, so an empty or whitespace-bearing string arrives as written.\n    const raw = stripBom(text)\n    if (!quoted(offered[0]!)) {\n      const result = yield* Effect.result(decoder(raw))\n      if (result._tag === \"Success\") return result.success\n      // A string the schema read and refused on its merits (too short, not\n      // one of the literals) is the issue to correct, not the JSON parse. A\n      // schema that wanted no string at all keeps the JSON diagnosis.\n      const rawIssues = schemaIssuesOf(result.failure)\n      if (code === \"invalid_json\" && rawIssues[0]?.code !== \"invalid_type\") {\n        code = \"schema_mismatch\"\n        issues = rawIssues\n      }\n    }\n    return yield* new StructuredOutputFailure({\n      // Once the budget is spent, exhaustion is the actionable classification;\n      // the issue records retain whether the last candidate was invalid JSON or\n      // failed schema decoding.\n      code: attempt.corrections >= attempt.limit ? \"correction_exhausted\" : code,\n      schema: digest(schema),\n      candidate: Digest.digest(offered[offered.length - 1]!),\n      corrections: attempt.corrections,\n      limit: attempt.limit,\n      issues,\n      message:\n        `The agent's answer did not validate against its declared output schema after ${attempt.corrections} of ${attempt.limit} corrections`\n    })\n  })\n"]}