@frockbot/kernel-contracts 0.3.16 → 0.3.18

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@frockbot/kernel-contracts",
-  "version": "0.3.16",
+  "version": "0.3.18",
   "private": false,
   "type": "module",
   "exports": {

package/src/applets.test.ts

@@ -71,6 +71,13 @@ describe("Applet directory entry v1", () => {
     expect(() =>
       decodeAppletDirectoryEntryV1({ ...entry, appletId: "todo" }),
     ).toThrow("appletId is invalid");
+    // The owner half is a real User id, which Better Auth mints in mixed case.
+    expect(
+      decodeAppletDirectoryEntryV1({
+        ...entry,
+        appletId: "vgpqfaCcwnPlzjYdb2mIfNcOW1YV0SkG.todo",
+      }).appletId,
+    ).toBe("vgpqfaCcwnPlzjYdb2mIfNcOW1YV0SkG.todo");
     expect(() =>
       decodeAppletDirectoryEntryV1({ ...entry, status: "archived" }),
     ).toThrow("status is invalid");

package/src/applets.ts

@@ -206,7 +206,14 @@ export const APPLET_SOURCE_MAX_BYTES_V1 = 512 * 1024;
 export const APPLET_SOURCE_MAX_FILES_V1 = 256;
 export const APPLET_SOURCE_MAX_DIAGNOSTICS_V1 = 64;
 
-export const APPLET_ID_V1 = /^[a-z0-9][a-z0-9-]{0,63}\.[a-z0-9-]{1,64}$/;
+/**
+ * `<ownerUserId>.<random>`. The owner half is a User id exactly as the auth
+ * layer mints it — Better Auth ids are mixed case (`vgpqfaCcwnPlzjYdb2mI…`),
+ * so the pattern matches `templateShareIdV1`'s owner half rather than a slug.
+ * A lowercase-only owner half locked every real account out of Applets
+ * while the lowercase test ids sailed through (Bob, 2026-09-04).
+ */
+export const APPLET_ID_V1 = /^[a-zA-Z0-9][a-zA-Z0-9_-]{0,95}\.[a-z0-9-]{1,64}$/;
 export const APPLET_TOOL_NAME_V1 = /^[a-z][a-z0-9_]{0,63}$/;
 export const APPLET_MAX_TOOLS_V1 = 64;
 export const APPLET_MAX_GENERATIONS_PAGE_V1 = 64;

package/src/index.ts

@@ -11,6 +11,7 @@ export * from "./remote.js";
 export * from "./send-to-user.js";
 export * from "./session.js";
 export * from "./skills.js";
+export * from "./structured-output.js";
 export * from "./tool-execution.js";
 export * from "./turn-deadline.js";
 export * from "./turn-history.js";

package/src/isolate.ts

@@ -31,6 +31,7 @@ import {
   type NormalizedModelRequest,
   type ToolSchema,
 } from "./types.js";
+import { STRUCTURED_OUTPUT_ISSUE_LIMIT_V1 } from "./structured-output.js";
 
 /**
  * The wire contract version the kernel wrapper emits. Version 2 added
@@ -1038,7 +1039,9 @@ export function decodeIsolateScheduleRequestV1(
   };
 }
 
-const APPLET_CAPABILITY_ID = /^[a-z0-9][a-z0-9-]{0,63}\.[a-z0-9-]{1,64}$/;
+// Same shape as `APPLET_ID_V1`: a mixed-case User id, then the random half.
+const APPLET_CAPABILITY_ID =
+  /^[a-zA-Z0-9][a-zA-Z0-9_-]{0,95}\.[a-z0-9-]{1,64}$/;
 
 export function decodeIsolateAppletsRequestV1(
   input: unknown,
@@ -1343,6 +1346,98 @@ export function decodeIsolateModelEventV1(
       },
     };
   }
+  if (value.type === "response-format-note") {
+    exactKeys(value, ["type", "note"], label);
+    const note = record(value.note, `${label}.note`);
+    exactKeys(
+      note,
+      ["code", "requested", "effective", "message"],
+      `${label}.note`,
+    );
+    if (
+      note.code !== "structured-output-downgraded" ||
+      (note.requested !== "json_schema" && note.requested !== "json") ||
+      (note.effective !== "json" && note.effective !== "prompt")
+    ) {
+      throw new Error(`${label}.note is invalid`);
+    }
+    return {
+      type: "response-format-note",
+      note: {
+        code: note.code,
+        requested: note.requested,
+        effective: note.effective,
+        message: boundedString(note.message, `${label}.note.message`, 1_024),
+      },
+    };
+  }
+  if (value.type === "structured-output-failure") {
+    exactKeys(value, ["type", "failure"], label);
+    const failure = record(value.failure, `${label}.failure`);
+    if (failure.code === "invalid-json") {
+      exactKeys(failure, ["code", "message"], `${label}.failure`);
+      return {
+        type: "structured-output-failure",
+        failure: {
+          code: "invalid-json",
+          message: boundedString(
+            failure.message,
+            `${label}.failure.message`,
+            1_024,
+          ),
+        },
+      };
+    }
+    exactKeys(failure, ["code", "message", "issues"], `${label}.failure`);
+    if (failure.code !== "schema-mismatch" || !Array.isArray(failure.issues)) {
+      throw new Error(`${label}.failure is invalid`);
+    }
+    if (failure.issues.length > STRUCTURED_OUTPUT_ISSUE_LIMIT_V1) {
+      throw new Error(`${label}.failure.issues exceeds its limit`);
+    }
+    return {
+      type: "structured-output-failure",
+      failure: {
+        code: "schema-mismatch",
+        message: boundedString(
+          failure.message,
+          `${label}.failure.message`,
+          1_024,
+        ),
+        issues: failure.issues.map((candidate, index) => {
+          const issue = record(candidate, `${label}.failure.issues[${index}]`);
+          exactKeys(
+            issue,
+            ["path", "code", "message"],
+            `${label}.failure.issues[${index}]`,
+          );
+          if (
+            issue.code !== "type" &&
+            issue.code !== "enum" &&
+            issue.code !== "required" &&
+            issue.code !== "additional-property"
+          ) {
+            throw new Error(
+              `${label}.failure.issues[${index}].code is invalid`,
+            );
+          }
+          return {
+            path: boundedString(
+              issue.path,
+              `${label}.failure.issues[${index}].path`,
+              1_024,
+            ),
+            code: issue.code,
+            message: boundedString(
+              issue.message,
+              `${label}.failure.issues[${index}].message`,
+              1_024,
+            ),
+          };
+        }),
+      },
+    };
+  }
   throw new Error(`${label}.type is invalid`);
 }
 

package/src/model-invocation.ts

@@ -1,6 +1,19 @@
 // Importing the augmented module is what merges these declarations into cordis.
 import type {} from "cordis";
 import type { LlmStreamEvent, NormalizedModelRequest } from "./types.js";
+import type {
+  JsonSchemaResponseFormatV1,
+  ModelProviderSupportsV1,
+  StructuredOutputFailureV1,
+  StructuredModelResultV1,
+} from "./structured-output.js";
+
+export class StructuredOutputValidationError extends Error {
+  constructor(readonly failure: StructuredOutputFailureV1) {
+    super(failure.message);
+    this.name = "StructuredOutputValidationError";
+  }
+}
 
 export interface DurableModelEffect {
   providerEffectId: string;
@@ -160,6 +173,8 @@ export interface LlmReconciliationCapability {
 
 export interface LlmProvider {
   id: string;
+  /** Legacy/test adapters that omit this are treated as supporting nothing. */
+  supports?: ModelProviderSupportsV1;
   stream(
     request: NormalizedModelRequest,
     signal: AbortSignal,
@@ -173,6 +188,11 @@ export interface ModelInvocation {
     request: NormalizedModelRequest,
     signal: AbortSignal,
   ): AsyncIterable<LlmStreamEvent>;
+  structured<T>(
+    request: NormalizedModelRequest,
+    format: Omit<JsonSchemaResponseFormatV1, "type">,
+    signal: AbortSignal,
+  ): Promise<StructuredModelResultV1<T>>;
   reconcile(
     request: NormalizedModelRequest,
     signal: AbortSignal,

package/src/prompt-assembly.ts

@@ -14,6 +14,14 @@ export interface PromptAssemblyContext {
    * what an absent turn type meant.
    */
   turnType: TurnTypeV1;
+  /**
+   * Where this request sits in the Turn's step budget: `current` is the step
+   * being assembled (1-based) and `max` the last step the loop will run. A
+   * section can tell the model it is about to be stopped, which is how a
+   * long tool-driven reply learns to send a status instead of going silent.
+   * Absent when the assembler is not inside a Turn.
+   */
+  step?: { current: number; max: number };
 }
 
 /** What a host assembles as when it is not running an admitted Turn. */

package/src/session.test.ts

@@ -75,6 +75,38 @@ test("a Bot-isolate hook failure is an exact durable session event", () => {
   );
 });
 
+test("a degraded Computer sync records bounded exclusions and decodes legacy rows", () => {
+  const legacy = {
+    type: "computer/sync",
+    turn: 1,
+    reason: "open",
+    status: "ok",
+    detail: "",
+    pulled: 1,
+    pushed: 0,
+    restored: 0,
+    removed: 0,
+    adopted: 0,
+    conflicts: 0,
+    failures: 0,
+    seq: 0,
+    timestamp,
+  } as const;
+  expect(decodeSessionEvent(legacy)).toEqual(legacy);
+
+  const degraded = {
+    ...legacy,
+    status: "degraded",
+    detail: "Excluded 1 reproducible Workspace item from sync.",
+    ignored: 1,
+    omitted: 0,
+  } as const;
+  expect(decodeSessionEvent(degraded)).toEqual(degraded);
+  expect(() => decodeSessionEvent({ ...degraded, ignored: -1 })).toThrow(
+    /ignored/,
+  );
+});
+
 test("a compaction is an exact durable session event", () => {
   const intent = {
     type: "conversation/compaction-intent",

package/src/session.ts

@@ -399,6 +399,9 @@ export class Session {
       if (event.type === "model/effect-not-started") {
         unresolvedModelRequests.delete(event.requestId);
       }
+      if (event.type === "model/response-failed") {
+        unresolvedModelRequests.delete(event.requestId);
+      }
       if (event.type === "assistant/message") {
         unresolvedModelRequests.delete(event.requestId);
         if (openStep?.turn === event.turn && openStep.step === event.step) {

package/src/structured-output.test.ts

@@ -0,0 +1,117 @@
+import { describe, expect, test } from "bun:test";
+import {
+  decodeModelResponseFormatV1,
+  decodeStructuredOutputSchemaV1,
+  parseStructuredOutputJsonV1,
+  validateStructuredOutputV1,
+} from "./structured-output.js";
+
+const schema = decodeStructuredOutputSchemaV1({
+  type: "object",
+  properties: {
+    name: { type: "string" },
+    scores: { type: "array", items: { type: "number" } },
+    active: { type: "boolean", enum: [true] },
+  },
+  required: ["name", "scores", "active"],
+  additionalProperties: false,
+});
+
+describe("the structured-output schema subset", () => {
+  test("accepts nested objects, arrays, primitives and enums", () => {
+    expect(
+      validateStructuredOutputV1(
+        '{"name":"Ada","scores":[1,2.5],"active":true}',
+        schema,
+      ),
+    ).toEqual({
+      status: "completed",
+      value: { name: "Ada", scores: [1, 2.5], active: true },
+      raw: '{"name":"Ada","scores":[1,2.5],"active":true}',
+    });
+  });
+
+  test("returns a typed JSON failure without throwing", () => {
+    expect(validateStructuredOutputV1("not json", schema)).toEqual({
+      status: "failed",
+      failure: {
+        code: "invalid-json",
+        message: "The model response was not valid JSON",
+      },
+      raw: "not json",
+    });
+  });
+
+  test("validates schema-free JSON mode", () => {
+    expect(parseStructuredOutputJsonV1('[1,"two",true]')).toEqual({
+      status: "completed",
+      value: [1, "two", true],
+      raw: '[1,"two",true]',
+    });
+    expect(parseStructuredOutputJsonV1("not json")).toMatchObject({
+      status: "failed",
+      failure: { code: "invalid-json" },
+    });
+  });
+
+  test("compares object enum members as JSON values, independent of key order", () => {
+    const enumSchema = decodeStructuredOutputSchemaV1({
+      type: "object",
+      enum: [{ first: 1, second: 2 }],
+    });
+    expect(
+      validateStructuredOutputV1('{"second":2,"first":1}', enumSchema),
+    ).toMatchObject({ status: "completed" });
+  });
+
+  test("reports required, type, enum and additional-property failures", () => {
+    const result = validateStructuredOutputV1(
+      '{"scores":[1,"two"],"active":false,"extra":1}',
+      schema,
+    );
+    expect(result.status).toBe("failed");
+    if (result.status === "completed") return;
+    expect(result.failure.code).toBe("schema-mismatch");
+    if (result.failure.code === "invalid-json") return;
+    expect(result.failure.issues.map((issue) => issue.code)).toEqual([
+      "required",
+      "type",
+      "enum",
+      "additional-property",
+    ]);
+  });
+
+  test("refuses unsupported schema dialect at the seam", () => {
+    expect(() =>
+      decodeStructuredOutputSchemaV1({ type: "string", minLength: 1 }),
+    ).toThrow("minLength is not supported");
+    expect(() =>
+      decodeStructuredOutputSchemaV1({
+        type: "object",
+        properties: {},
+        required: ["missing"],
+      }),
+    ).toThrow('required names unknown property "missing"');
+  });
+
+  test("strictly decodes the normalized response format", () => {
+    expect(
+      decodeModelResponseFormatV1({
+        type: "json_schema",
+        name: "answer_v1",
+        schema: { type: "string" },
+      }),
+    ).toEqual({
+      type: "json_schema",
+      name: "answer_v1",
+      schema: { type: "string" },
+    });
+    expect(() =>
+      decodeModelResponseFormatV1({
+        type: "json_schema",
+        name: "answer v1",
+        schema: { type: "string" },
+      }),
+    ).toThrow("1-64 letters");
+  });
+});

package/src/structured-output.ts

@@ -0,0 +1,415 @@
+/** The JSON Schema subset accepted by the model contract (ADR 0034). */
+export type StructuredOutputSchemaV1 =
+  | {
+      type: "object";
+      properties?: Record<string, StructuredOutputSchemaV1>;
+      required?: string[];
+      additionalProperties?: boolean;
+      enum?: unknown[];
+      title?: string;
+      description?: string;
+    }
+  | {
+      type: "array";
+      items: StructuredOutputSchemaV1;
+      enum?: unknown[];
+      title?: string;
+      description?: string;
+    }
+  | {
+      type: "string" | "number" | "boolean";
+      enum?: unknown[];
+      title?: string;
+      description?: string;
+    };
+
+export interface JsonSchemaResponseFormatV1 {
+  type: "json_schema";
+  /** Provider-safe identifier for the schema, not a display label. */
+  name: string;
+  schema: StructuredOutputSchemaV1;
+}
+
+export interface JsonResponseFormatV1 {
+  type: "json";
+}
+
+export type ModelResponseFormatV1 =
+  JsonSchemaResponseFormatV1 | JsonResponseFormatV1;
+
+export type StructuredOutputSupportV1 = "json_schema" | "json" | "none";
+
+export interface ModelProviderSupportsV1 {
+  structuredOutput: StructuredOutputSupportV1;
+}
+
+export interface StructuredOutputIssueV1 {
+  path: string;
+  code: "type" | "enum" | "required" | "additional-property";
+  message: string;
+}
+
+/** A validation failure is durable, so its diagnostics cannot grow unbounded. */
+export const STRUCTURED_OUTPUT_ISSUE_LIMIT_V1 = 100;
+
+export type StructuredOutputFailureV1 =
+  | {
+      code: "invalid-json";
+      message: string;
+    }
+  | {
+      code: "schema-mismatch";
+      message: string;
+      issues: StructuredOutputIssueV1[];
+    };
+
+export interface ResponseFormatNoteV1 {
+  code: "structured-output-downgraded";
+  requested: "json_schema" | "json";
+  effective: "json" | "prompt";
+  message: string;
+}
+
+export type StructuredModelResultV1<T> =
+  | { status: "completed"; value: T; raw: string }
+  | { status: "failed"; failure: StructuredOutputFailureV1; raw: string };
+
+const SCHEMA_KEYS = new Set([
+  "type",
+  "properties",
+  "items",
+  "enum",
+  "required",
+  "additionalProperties",
+  "title",
+  "description",
+]);
+
+/**
+ * Strictly decodes the deliberately small, dependency-free schema dialect.
+ * Unsupported JSON Schema keywords fail at admission instead of being
+ * interpreted differently by different providers.
+ */
+export function decodeStructuredOutputSchemaV1(
+  value: unknown,
+  label = "structured output schema",
+): StructuredOutputSchemaV1 {
+  if (!isRecord(value)) throw new Error(`${label} must be an object`);
+  for (const key of Object.keys(value)) {
+    if (!SCHEMA_KEYS.has(key)) {
+      throw new Error(`${label}.${key} is not supported`);
+    }
+  }
+  if (
+    value.type !== "object" &&
+    value.type !== "array" &&
+    value.type !== "string" &&
+    value.type !== "number" &&
+    value.type !== "boolean"
+  ) {
+    throw new Error(
+      `${label}.type must be object, array, string, number, or boolean`,
+    );
+  }
+  requireOptionalString(value.title, `${label}.title`);
+  requireOptionalString(value.description, `${label}.description`);
+  if (value.enum !== undefined) {
+    if (!Array.isArray(value.enum) || value.enum.length === 0) {
+      throw new Error(`${label}.enum must be a non-empty array`);
+    }
+    for (const member of value.enum) requireJsonValue(member, `${label}.enum`);
+  }
+
+  if (value.type === "object") {
+    if (value.items !== undefined) {
+      throw new Error(`${label}.items is only valid for arrays`);
+    }
+    if (
+      value.additionalProperties !== undefined &&
+      typeof value.additionalProperties !== "boolean"
+    ) {
+      throw new Error(`${label}.additionalProperties must be a boolean`);
+    }
+    const properties: Record<string, StructuredOutputSchemaV1> = {};
+    if (value.properties !== undefined) {
+      if (!isRecord(value.properties)) {
+        throw new Error(`${label}.properties must be an object`);
+      }
+      for (const [name, schema] of Object.entries(value.properties)) {
+        properties[name] = decodeStructuredOutputSchemaV1(
+          schema,
+          `${label}.properties.${name}`,
+        );
+      }
+    }
+    let required: string[] | undefined;
+    if (value.required !== undefined) {
+      if (
+        !Array.isArray(value.required) ||
+        !value.required.every((entry) => typeof entry === "string")
+      ) {
+        throw new Error(`${label}.required must be an array of strings`);
+      }
+      required = [...value.required];
+      for (const name of required) {
+        if (!(name in properties)) {
+          throw new Error(`${label}.required names unknown property "${name}"`);
+        }
+      }
+    }
+    return {
+      type: "object",
+      ...(Object.keys(properties).length > 0 ? { properties } : {}),
+      ...(required ? { required } : {}),
+      ...(value.additionalProperties !== undefined
+        ? { additionalProperties: value.additionalProperties }
+        : {}),
+      ...(value.enum !== undefined ? { enum: value.enum } : {}),
+      ...(value.title !== undefined ? { title: value.title } : {}),
+      ...(value.description !== undefined
+        ? { description: value.description }
+        : {}),
+    };
+  }
+
+  if (
+    value.properties !== undefined ||
+    value.required !== undefined ||
+    value.additionalProperties !== undefined
+  ) {
+    throw new Error(`${label} contains object-only keywords`);
+  }
+  if (value.type === "array") {
+    if (value.items === undefined) {
+      throw new Error(`${label}.items is required for arrays`);
+    }
+    return {
+      type: "array",
+      items: decodeStructuredOutputSchemaV1(value.items, `${label}.items`),
+      ...(value.enum !== undefined ? { enum: value.enum } : {}),
+      ...(value.title !== undefined ? { title: value.title } : {}),
+      ...(value.description !== undefined
+        ? { description: value.description }
+        : {}),
+    };
+  }
+  if (value.items !== undefined) {
+    throw new Error(`${label}.items is only valid for arrays`);
+  }
+  return {
+    type: value.type,
+    ...(value.enum !== undefined ? { enum: value.enum } : {}),
+    ...(value.title !== undefined ? { title: value.title } : {}),
+    ...(value.description !== undefined
+      ? { description: value.description }
+      : {}),
+  };
+}
+
+export function decodeModelResponseFormatV1(
+  value: unknown,
+  label = "responseFormat",
+): ModelResponseFormatV1 {
+  if (!isRecord(value)) throw new Error(`${label} must be an object`);
+  if (value.type === "json") {
+    requireExactKeys(value, ["type"], label);
+    return { type: "json" };
+  }
+  if (value.type !== "json_schema") {
+    throw new Error(`${label}.type must be json_schema or json`);
+  }
+  requireExactKeys(value, ["type", "name", "schema"], label);
+  if (
+    typeof value.name !== "string" ||
+    !/^[A-Za-z0-9_-]{1,64}$/.test(value.name)
+  ) {
+    throw new Error(`${label}.name must be 1-64 letters, digits, _ or -`);
+  }
+  return {
+    type: "json_schema",
+    name: value.name,
+    schema: decodeStructuredOutputSchemaV1(value.schema, `${label}.schema`),
+  };
+}
+
+export function validateStructuredOutputV1(
+  text: string,
+  schema: StructuredOutputSchemaV1,
+): StructuredModelResultV1<unknown> {
+  const parsed = parseStructuredOutputJsonV1(text);
+  if (parsed.status === "failed") return parsed;
+  const value = parsed.value;
+  const issues: StructuredOutputIssueV1[] = [];
+  validateValue(value, schema, "$", issues);
+  return issues.length === 0
+    ? { status: "completed", value, raw: text }
+    : {
+        status: "failed",
+        failure: {
+          code: "schema-mismatch",
+          message: "The model response did not match the requested schema",
+          issues,
+        },
+        raw: text,
+      };
+}
+
+/** Parse-only validation for a request that asks for JSON without a schema. */
+export function parseStructuredOutputJsonV1(
+  text: string,
+): StructuredModelResultV1<unknown> {
+  try {
+    return { status: "completed", value: JSON.parse(text), raw: text };
+  } catch {
+    return {
+      status: "failed",
+      failure: {
+        code: "invalid-json",
+        message: "The model response was not valid JSON",
+      },
+      raw: text,
+    };
+  }
+}
+
+function validateValue(
+  value: unknown,
+  schema: StructuredOutputSchemaV1,
+  path: string,
+  issues: StructuredOutputIssueV1[],
+): void {
+  if (issues.length >= STRUCTURED_OUTPUT_ISSUE_LIMIT_V1) return;
+  if (schema.enum && !schema.enum.some((member) => jsonEqual(member, value))) {
+    pushIssue(issues, {
+      path,
+      code: "enum",
+      message: `${path} is not one of the allowed values`,
+    });
+    return;
+  }
+  if (schema.type === "object") {
+    if (!isRecord(value)) return typeIssue(path, "object", issues);
+    for (const required of schema.required ?? []) {
+      if (!Object.hasOwn(value, required)) {
+        pushIssue(issues, {
+          path: `${path}.${required}`,
+          code: "required",
+          message: `${path}.${required} is required`,
+        });
+      }
+    }
+    for (const [name, member] of Object.entries(value)) {
+      const memberSchema = schema.properties?.[name];
+      if (memberSchema) {
+        validateValue(member, memberSchema, `${path}.${name}`, issues);
+      } else if (schema.additionalProperties === false) {
+        pushIssue(issues, {
+          path: `${path}.${name}`,
+          code: "additional-property",
+          message: `${path}.${name} is not allowed`,
+        });
+      }
+    }
+    return;
+  }
+  if (schema.type === "array") {
+    if (!Array.isArray(value)) return typeIssue(path, "array", issues);
+    value.forEach((member, index) =>
+      validateValue(member, schema.items, `${path}[${index}]`, issues),
+    );
+    return;
+  }
+  if (typeof value !== schema.type) typeIssue(path, schema.type, issues);
+}
+
+function typeIssue(
+  path: string,
+  expected: string,
+  issues: StructuredOutputIssueV1[],
+): void {
+  pushIssue(issues, {
+    path,
+    code: "type",
+    message: `${path} must be a ${expected}`,
+  });
+}
+
+function pushIssue(
+  issues: StructuredOutputIssueV1[],
+  issue: StructuredOutputIssueV1,
+): void {
+  if (issues.length < STRUCTURED_OUTPUT_ISSUE_LIMIT_V1) issues.push(issue);
+}
+
+function jsonEqual(left: unknown, right: unknown): boolean {
+  if (Object.is(left, right)) return true;
+  if (Array.isArray(left) || Array.isArray(right)) {
+    return (
+      Array.isArray(left) &&
+      Array.isArray(right) &&
+      left.length === right.length &&
+      left.every((member, index) => jsonEqual(member, right[index]))
+    );
+  }
+  if (isRecord(left) || isRecord(right)) {
+    if (!isRecord(left) || !isRecord(right)) return false;
+    const leftKeys = Object.keys(left).sort();
+    const rightKeys = Object.keys(right).sort();
+    return (
+      leftKeys.length === rightKeys.length &&
+      leftKeys.every(
+        (key, index) =>
+          key === rightKeys[index] && jsonEqual(left[key], right[key]),
+      )
+    );
+  }
+  return false;
+}
+
+function requireExactKeys(
+  value: Record<string, unknown>,
+  keys: readonly string[],
+  label: string,
+): void {
+  const allowed = new Set(keys);
+  for (const key of Object.keys(value)) {
+    if (!allowed.has(key)) throw new Error(`${label}.${key} is not supported`);
+  }
+  for (const key of keys) {
+    if (!Object.hasOwn(value, key))
+      throw new Error(`${label}.${key} is required`);
+  }
+}
+
+function requireOptionalString(
+  value: unknown,
+  label: string,
+): asserts value is string | undefined {
+  if (value !== undefined && typeof value !== "string") {
+    throw new Error(`${label} must be a string`);
+  }
+}
+
+function requireJsonValue(value: unknown, label: string): void {
+  if (
+    value === null ||
+    typeof value === "string" ||
+    typeof value === "boolean" ||
+    (typeof value === "number" && Number.isFinite(value))
+  ) {
+    return;
+  }
+  if (Array.isArray(value)) {
+    value.forEach((member) => requireJsonValue(member, label));
+    return;
+  }
+  if (isRecord(value)) {
+    Object.values(value).forEach((member) => requireJsonValue(member, label));
+    return;
+  }
+  throw new Error(`${label} must contain only JSON values`);
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}

package/src/turn-type.test.ts

@@ -15,7 +15,12 @@ function durable(event: Record<string, unknown>): unknown {
 
 describe("TurnTypeV1", () => {
   test("names every turn type the admission vocabulary declares", () => {
-    expect([...TURN_TYPES_V1]).toEqual(["chat", "automation", "subagent"]);
+    expect([...TURN_TYPES_V1]).toEqual([
+      "chat",
+      "agent",
+      "automation",
+      "subagent",
+    ]);
     for (const turnType of TURN_TYPES_V1) {
       expect(decodeTurnTypeV1(turnType)).toBe(turnType);
     }

package/src/types.ts

@@ -8,6 +8,13 @@ import {
   decodeSkillRefsV1,
   type SkillRefV1,
 } from "./skills.js";
+import {
+  decodeModelResponseFormatV1,
+  STRUCTURED_OUTPUT_ISSUE_LIMIT_V1,
+  type ModelResponseFormatV1,
+  type ResponseFormatNoteV1,
+  type StructuredOutputFailureV1,
+} from "./structured-output.js";
 
 export interface ToolCall {
   id: string;
@@ -134,12 +141,29 @@ export interface NormalizedModelRequest {
   system: string;
   messages: LlmMessage[];
   tools: ToolSchema[];
+  responseFormat?: ModelResponseFormatV1;
   modelBinding?: ModelBindingSnapshot;
 }
 
+/** Provider-reported token accounting for one normalized model request. */
+export interface LlmUsageV1 {
+  inputTokens: number;
+  outputTokens: number;
+  /** Input tokens served from a provider cache; included in `inputTokens`. */
+  cachedInputTokens?: number;
+  /** Reasoning tokens; included in `outputTokens`. */
+  reasoningTokens?: number;
+}
+
 export type LlmStreamEvent =
   | { type: "text-delta"; text: string }
   | { type: "tool-call"; call: ToolCall }
+  | { type: "usage"; usage: LlmUsageV1 }
+  | { type: "response-format-note"; note: ResponseFormatNoteV1 }
+  | {
+      type: "structured-output-failure";
+      failure: StructuredOutputFailureV1;
+    }
   | { type: "finish"; reason: "completed" | "tool-calls" | "max-tokens" };
 
 export type StepOutcome =
@@ -206,11 +230,12 @@ export function turnFailureMessage(
  * isolate contract, and the durable run record: adding one later is a wire
  * change in three places.
  */
-export type TurnTypeV1 = "chat" | "automation" | "subagent";
+export type TurnTypeV1 = "chat" | "agent" | "automation" | "subagent";
 
 /** The declared turn types, in their canonical order. */
 export const TURN_TYPES_V1: readonly TurnTypeV1[] = [
   "chat",
+  "agent",
   "automation",
   "subagent",
 ];
@@ -302,6 +327,25 @@ export interface SessionEventMap {
     step: number;
     request: NormalizedModelRequest;
   };
+  /**
+   * Bounded accounting for one model request. Providers report tokens when
+   * they can; otherwise the loop estimates from the exact durable request and
+   * response sizes. It deliberately carries no prompt or response content.
+   */
+  "model/usage": {
+    turn: number;
+    step: number;
+    requestId: string;
+    provider: string;
+    model: string;
+    modelBinding?: ModelBindingSnapshot;
+    inputTokens: number;
+    outputTokens: number;
+    cachedInputTokens?: number;
+    reasoningTokens?: number;
+    latencyMs: number;
+    estimated: boolean;
+  };
   "model/effect-not-started": {
     turn: number;
     step: number;
@@ -322,6 +366,18 @@ export interface SessionEventMap {
     requestId: string;
     reason: string;
   };
+  "model/response-format-note": {
+    turn: number;
+    step: number;
+    requestId: string;
+    note: ResponseFormatNoteV1;
+  };
+  "model/response-failed": {
+    turn: number;
+    step: number;
+    requestId: string;
+    failure: StructuredOutputFailureV1;
+  };
   "assistant/chunk": {
     turn: number;
     step: number;
@@ -693,13 +749,17 @@ export interface SessionEventMap {
   "computer/sync": {
     turn: number;
     reason: "open" | "signal" | "turn-end" | "publish";
-    status: "ok" | "unavailable" | "refused" | "skipped";
+    status: "ok" | "degraded" | "unavailable" | "refused" | "skipped";
     detail: string;
     pulled: number;
     pushed: number;
     restored: number;
     removed: number;
     adopted: number;
+    /** Absent only on records written before bounded manifests shipped. */
+    ignored?: number;
+    /** Absent only on records written before bounded manifests shipped. */
+    omitted?: number;
     conflicts: number;
     failures: number;
   };
@@ -1083,6 +1143,44 @@ function requireToolSchema(value: unknown, label: string): void {
   requireJsonValue(schema, `${label}.inputSchema`);
 }
 
+function requireStructuredOutputFailureV1(value: unknown, label: string): void {
+  const failure = eventRecord(value, label);
+  if (failure.code === "invalid-json") {
+    requireEventKeys(failure, ["code", "message"], label);
+    eventString(failure.message, `${label}.message`);
+    return;
+  }
+  if (failure.code !== "schema-mismatch") {
+    throw new Error(`${label}.code is invalid`);
+  }
+  requireEventKeys(failure, ["code", "message", "issues"], label);
+  eventString(failure.message, `${label}.message`);
+  if (!Array.isArray(failure.issues)) {
+    throw new Error(`${label}.issues must be an array`);
+  }
+  if (failure.issues.length > STRUCTURED_OUTPUT_ISSUE_LIMIT_V1) {
+    throw new Error(`${label}.issues exceeds its limit`);
+  }
+  for (const [index, candidate] of failure.issues.entries()) {
+    const issue = eventRecord(candidate, `${label}.issues[${index}]`);
+    requireEventKeys(
+      issue,
+      ["path", "code", "message"],
+      `${label}.issues[${index}]`,
+    );
+    eventString(issue.path, `${label}.issues[${index}].path`);
+    eventString(issue.message, `${label}.issues[${index}].message`);
+    if (
+      issue.code !== "type" &&
+      issue.code !== "enum" &&
+      issue.code !== "required" &&
+      issue.code !== "additional-property"
+    ) {
+      throw new Error(`${label}.issues[${index}].code is invalid`);
+    }
+  }
+}
+
 /**
  * The exact v1 decoder for a normalized model request. Exported because the
  * request crosses the Bot isolate boundary inbound — a Bot-authored model
@@ -1108,6 +1206,7 @@ function requireNormalizedModelRequest(value: unknown, label: string): void {
       "system",
       "messages",
       "tools",
+      ...(Object.hasOwn(request, "responseFormat") ? ["responseFormat"] : []),
       ...(Object.hasOwn(request, "modelBinding") ? ["modelBinding"] : []),
     ],
     label,
@@ -1125,6 +1224,12 @@ function requireNormalizedModelRequest(value: unknown, label: string): void {
   request.tools.forEach((tool, index) =>
     requireToolSchema(tool, `${label}.tools[${index}]`),
   );
+  if (request.responseFormat !== undefined) {
+    decodeModelResponseFormatV1(
+      request.responseFormat,
+      `${label}.responseFormat`,
+    );
+  }
   if (request.modelBinding !== undefined) {
     const binding = eventRecord(request.modelBinding, `${label}.modelBinding`);
     requireEventKeys(
@@ -1268,6 +1373,88 @@ export function decodeSessionEvent(input: unknown): SessionEvent {
       step();
       requireNormalizedModelRequest(event.request, "session event.request");
       break;
+    case "model/usage": {
+      requireEventKeys(
+        event,
+        keys(
+          "turn",
+          "step",
+          "requestId",
+          "provider",
+          "model",
+          ...(Object.hasOwn(event, "modelBinding") ? ["modelBinding"] : []),
+          "inputTokens",
+          "outputTokens",
+          ...(Object.hasOwn(event, "cachedInputTokens")
+            ? ["cachedInputTokens"]
+            : []),
+          ...(Object.hasOwn(event, "reasoningTokens")
+            ? ["reasoningTokens"]
+            : []),
+          "latencyMs",
+          "estimated",
+        ),
+        "session event",
+      );
+      turn();
+      step();
+      requestId();
+      eventString(event.provider, "session event.provider");
+      eventString(event.model, "session event.model");
+      if (event.modelBinding !== undefined) {
+        requireNormalizedModelRequest(
+          {
+            requestId: event.requestId,
+            provider: event.provider,
+            model: event.model,
+            system: "",
+            messages: [],
+            tools: [],
+            modelBinding: event.modelBinding,
+          },
+          "session event usage binding",
+        );
+      }
+      const inputTokens = eventInteger(
+        event.inputTokens,
+        "session event.inputTokens",
+        0,
+      );
+      const outputTokens = eventInteger(
+        event.outputTokens,
+        "session event.outputTokens",
+        0,
+      );
+      if (event.cachedInputTokens !== undefined) {
+        const cached = eventInteger(
+          event.cachedInputTokens,
+          "session event.cachedInputTokens",
+          0,
+        );
+        if (cached > inputTokens) {
+          throw new Error(
+            "session event.cachedInputTokens cannot exceed inputTokens",
+          );
+        }
+      }
+      if (event.reasoningTokens !== undefined) {
+        const reasoning = eventInteger(
+          event.reasoningTokens,
+          "session event.reasoningTokens",
+          0,
+        );
+        if (reasoning > outputTokens) {
+          throw new Error(
+            "session event.reasoningTokens cannot exceed outputTokens",
+          );
+        }
+      }
+      eventInteger(event.latencyMs, "session event.latencyMs", 0);
+      if (typeof event.estimated !== "boolean") {
+        throw new Error("session event.estimated must be a boolean");
+      }
+      break;
+    }
     case "model/effect-not-started":
     case "model/reconciliation-required":
       requireEventKeys(
@@ -1280,6 +1467,45 @@ export function decodeSessionEvent(input: unknown): SessionEvent {
       requestId();
       eventString(event.reason, "session event.reason");
       break;
+    case "model/response-format-note": {
+      requireEventKeys(
+        event,
+        keys("turn", "step", "requestId", "note"),
+        "session event",
+      );
+      turn();
+      step();
+      requestId();
+      const note = eventRecord(event.note, "session event.note");
+      requireEventKeys(
+        note,
+        keys("code", "requested", "effective", "message"),
+        "session event.note",
+      );
+      if (note.code !== "structured-output-downgraded") {
+        throw new Error("session event.note.code is invalid");
+      }
+      if (note.requested !== "json_schema" && note.requested !== "json") {
+        throw new Error("session event.note.requested is invalid");
+      }
+      if (note.effective !== "json" && note.effective !== "prompt") {
+        throw new Error("session event.note.effective is invalid");
+      }
+      eventString(note.message, "session event.note.message");
+      break;
+    }
+    case "model/response-failed": {
+      requireEventKeys(
+        event,
+        keys("turn", "step", "requestId", "failure"),
+        "session event",
+      );
+      turn();
+      step();
+      requestId();
+      requireStructuredOutputFailureV1(event.failure, "session event.failure");
+      break;
+    }
     case "model/retry":
       requireEventKeys(
         event,
@@ -2035,6 +2261,8 @@ export function decodeSessionEvent(input: unknown): SessionEvent {
           "restored",
           "removed",
           "adopted",
+          ...(Object.hasOwn(event, "ignored") ? ["ignored"] : []),
+          ...(Object.hasOwn(event, "omitted") ? ["omitted"] : []),
           "conflicts",
           "failures",
         ),
@@ -2049,7 +2277,7 @@ export function decodeSessionEvent(input: unknown): SessionEvent {
         throw new Error("session event.reason is invalid");
       }
       if (
-        !["ok", "unavailable", "refused", "skipped"].includes(
+        !["ok", "degraded", "unavailable", "refused", "skipped"].includes(
           event.status as string,
         )
       ) {
@@ -2067,6 +2295,12 @@ export function decodeSessionEvent(input: unknown): SessionEvent {
       ] as const) {
         eventInteger(event[field], `session event.${field}`, 0);
       }
+      if (event.ignored !== undefined) {
+        eventInteger(event.ignored, "session event.ignored", 0);
+      }
+      if (event.omitted !== undefined) {
+        eventInteger(event.omitted, "session event.omitted", 0);
+      }
       break;
     }
     case "bot/renamed": {