@tanstack-ai-browser/afm 0.2.1 → 0.2.2

package/README.md

@@ -24,7 +24,8 @@ import { afmText } from "@tanstack-ai-browser/afm"
 
 const adapter = afmText()
 if ((await adapter.availability()) === "available") {
-  const stream = chat({ adapter, messages, tools })
+  // One threadId per conversation: its follow-ups reuse the same native session.
+  const stream = chat({ adapter, threadId, messages, tools })
 }
 ```
 
@@ -32,6 +33,18 @@ if ((await adapter.availability()) === "available") {
 
 Each thread (`threadId`) keeps a native session, so a follow-up message only sends that message. Structured output (`chat({ outputSchema })`) is held to the schema by the framework.
 
+### Guardrails
+
+Apple's default guardrails can block ordinary text that sounds unsafe out of context, such as a card game's card names ("add 2 Searing Blood", "swap the Shocks for Play with Fire"), with a `guardrailViolation` error. `guardrails: "permissiveContentTransformations"` relaxes them:
+
+```ts
+const adapter = afmText({ guardrails: "permissiveContentTransformations" })
+```
+
+A request's `modelOptions.guardrails` overrides the adapter's, and in Electron `serveAfm({ guardrails })` sets them for every page that names none. `"default"` is the default.
+
+Apple's permissive guardrails cover text responses only: anything else, such as structured output (`chat({ outputSchema })`), gets the default guardrails. So when a permissive session's structured answer is blocked, the adapter asks for it again as text: a JSON value to the schema. The framework doesn't hold that answer to the schema while it's written, so the adapter parses the whole answer (or everything inside a code fence) and checks it against the schema before returning it; one that doesn't fit fails with the code `schemaMismatch`, and one that isn't JSON with `invalidJson`. (`chat()` itself validates only schemas that come with a Standard Schema validator, not plain JSON Schema.) Tool calls' arguments keep the default guardrails. A guardrail violation that still happens is reported with the code `guardrailViolation`.
+
 ### Electron (macOS)
 
 The page is the same as on iOS: `afmText()`. The main process runs the model, with one call before opening windows:

package/dist/adapter.d.ts

@@ -2,7 +2,7 @@ import type { AdapterYieldChunk, TextOptions } from "@tanstack/ai";
 import { BaseTextAdapter } from "@tanstack/ai/adapters";
 import type { StructuredOutputOptions, StructuredOutputResult } from "@tanstack/ai/adapters";
 import type { AfmChatModel } from "./model-meta.js";
-import type { AfmNative } from "./native.js";
+import type { AfmGuardrails, AfmNative } from "./native.js";
 export type AfmConfig = {
     /**
      * The native side. By default `window.afm` where a host put it there
@@ -10,12 +10,20 @@ export type AfmConfig = {
      * plugin (`Afm`).
      */
     native?: AfmNative;
+    /**
+     * Apple's guardrails: "default" (the default), or "permissiveContentTransformations",
+     * for text the default ones block out of context, such as a card game's card
+     * names. A request's `modelOptions.guardrails` overrides it.
+     */
+    guardrails?: AfmGuardrails;
 };
-/** Per-call `modelOptions`: the response's sampling and length. */
+/** Per-call `modelOptions`: the response's sampling and length, and the guardrails. */
 export type AfmTextModelOptions = {
     temperature?: number;
     /** Most tokens to generate. */
     maximumResponseTokens?: number;
+    /** Apple's guardrails for this request's session, over the adapter's `guardrails`. */
+    guardrails?: AfmGuardrails;
 };
 export type Availability = "unavailable" | "downloadable" | "downloading" | "available";
 type MetadataByModality = {
@@ -41,6 +49,9 @@ export declare class AfmTextAdapter extends BaseTextAdapter<AfmChatModel, AfmTex
     private readonly paused;
     private listening;
     constructor(config: AfmConfig, model: AfmChatModel);
+    private readonly guardrails;
+    /** A request's guardrails: its own, else the adapter's (left out: the host's, else Apple's default). */
+    private guardrailsOf;
     /** Whether Apple's model can run here: "downloading" while Apple Intelligence gets it. */
     availability(): Promise<Availability>;
     /** Tokens a session holds, where the OS says (26.4 and later). */

package/dist/adapter.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"adapter.d.ts","sourceRoot":"","sources":["../src/adapter.ts"],"names":[],"mappings":"AAmBA,OAAO,KAAK,EAAE,iBAAiB,EAAgB,WAAW,EAAoB,MAAM,cAAc,CAAA;AAClG,OAAO,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAA;AACvD,OAAO,KAAK,EAAE,uBAAuB,EAAE,sBAAsB,EAAE,MAAM,uBAAuB,CAAA;AAG5F,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAA;AAEnD,OAAO,KAAK,EAAE,SAAS,EAA8D,MAAM,aAAa,CAAA;AAGxG,MAAM,MAAM,SAAS,GAAG;IACtB;;;;OAIG;IACH,MAAM,CAAC,EAAE,SAAS,CAAA;CACnB,CAAA;AAED,mEAAmE;AACnE,MAAM,MAAM,mBAAmB,GAAG;IAChC,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,+BAA+B;IAC/B,qBAAqB,CAAC,EAAE,MAAM,CAAA;CAC/B,CAAA;AAED,MAAM,MAAM,YAAY,GAAG,aAAa,GAAG,cAAc,GAAG,aAAa,GAAG,WAAW,CAAA;AAEvF,KAAK,kBAAkB,GAAG;IACxB,IAAI,EAAE,OAAO,CAAA;IACb,KAAK,EAAE,OAAO,CAAA;IACd,KAAK,EAAE,OAAO,CAAA;IACd,KAAK,EAAE,OAAO,CAAA;IACd,QAAQ,EAAE,OAAO,CAAA;CAClB,CAAA;AA4HD,qBAAa,cAAe,SAAQ,eAAe,CACjD,YAAY,EACZ,mBAAmB,EACnB,SAAS,CAAC,MAAM,CAAC,EACjB,kBAAkB,CACnB;IACC,SAAkB,IAAI,EAAG,MAAM,CAAS;IACxC,QAAQ,CAAC,IAAI,EAAG,KAAK,CAAS;IAC9B,SAAkB,QAAQ,EAAG,KAAK,CAAS;IAC3C,SAAkB,GAAG,EAAG,KAAK,CAAS;IACtC,SAAkB,eAAe,YAAI,MAAM,EAAU;IACrD,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAW;IAClC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAA4B;IACpD,OAAO,CAAC,QAAQ,CAAC,MAAM,CAA4B;IACnD;;;OAGG;IACH,OAAO,CAAC,QAAQ,CAAC,MAAM,CAA4B;IACnD,OAAO,CAAC,SAAS,CAA8B;IAE/C,YAAY,MAAM,EAAE,SAAS,EAAE,KAAK,EAAE,YAAY,EAGjD;IAED,0FAA0F;IACpF,YAAY,IAAI,OAAO,CAAC,YAAY,CAAC,CAO1C;IAED,kEAAkE;IAC5D,WAAW,IAAI,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAM/C;IAED,wEAAwE;IAClE,MAAM,CAAC,OAAO,GAAE;QAAE,MAAM,CAAC,EAAE,WAAW,CAAA;KAAO,GAAG,OAAO,CAAC,IAAI,CAAC,CAMlE;IAED;;;;OAIG;IACG,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC,CAK7B;IAED,yEAAyE;IACzE,OAAO,CAAC,MAAM;IAQd,6EAA6E;IAC7E,OAAO,CAAC,KAAK;IAOb,+EAA+E;IAC/E,OAAO,CAAC,IAAI;IAWZ,6DAA6D;YAC/C,IAAI;IA8BlB;;;;OAIG;YACW,KAAK;IAmDZ,UAAU,CAAC,OAAO,EAAE,WAAW,CAAC,mBAAmB,CAAC,GAAG,aAAa,CAAC,iBAAiB,CAAC,CAiJ7F;IAED;;;;OAIG;IACG,gBAAgB,CACpB,OAAO,EAAE,uBAAuB,CAAC,mBAAmB,CAAC,GACpD,OAAO,CAAC,sBAAsB,CAAC,OAAO,CAAC,CAAC,CAmC1C;CACF;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,OAAO,CAAC,MAAM,CAAC,EAAE,SAAS,GAAG,cAAc,CAAA;AAC3D,wBAAgB,OAAO,CAAC,KAAK,EAAE,YAAY,EAAE,MAAM,CAAC,EAAE,SAAS,GAAG,cAAc,CAAA"}
+{"version":3,"file":"adapter.d.ts","sourceRoot":"","sources":["../src/adapter.ts"],"names":[],"mappings":"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"}

package/dist/adapter.js

@@ -21,6 +21,8 @@ import { BaseTextAdapter } from "@tanstack/ai/adapters";
 import { contentText, toNativeMessages } from "./messages.js";
 import { Afm } from "./native.js";
 import { toNativeSchema } from "./schema.js";
+import { parseJsonValue } from "./json-value.js";
+import { schemaErrors } from "./validate.js";
 /** Events of one native response, as they come. */
 class EventQueue {
     events = [];
@@ -102,6 +104,26 @@ const usageOf = (usage) => usage && {
 let ids = 0;
 const nextId = (prefix) => `${prefix}_${Date.now().toString(36)}_${(ids++).toString(36)}`;
 const signalOf = (options) => options.abortController?.signal ?? options.request?.signal ?? undefined;
+/**
+ * A structured answer the model wrote as text (permissive guardrails' fallback,
+ * which the framework didn't hold to the schema): its JSON value, if it fits the
+ * schema. chat() validates only schemas with a Standard Schema validator, not
+ * plain JSON Schema, so the adapter checks it here.
+ */
+function checkedAnswer(text, schema) {
+    let data;
+    try {
+        data = parseJsonValue(text);
+    }
+    catch (error) {
+        throw Object.assign(new Error(`Apple's model wrote no JSON for the schema (its answer, written as text past its guardrails, was ${JSON.stringify(text.slice(0, 120))})`, { cause: error }), { code: "invalidJson" });
+    }
+    const problems = schemaErrors(schema, data);
+    if (problems.length > 0) {
+        throw Object.assign(new Error(`Apple's model's answer, written as text past its guardrails, doesn't fit the schema: ${problems.slice(0, 5).join("; ")}`), { code: "schemaMismatch" });
+    }
+    return data;
+}
 const parse = (json) => {
     try {
         return JSON.parse(json);
@@ -128,11 +150,17 @@ export class AfmTextAdapter extends BaseTextAdapter {
     constructor(config, model) {
         super({}, model);
         this.native = config.native ?? globalThis.afm ?? Afm;
+        this.guardrails = config.guardrails;
+    }
+    guardrails;
+    /** A request's guardrails: its own, else the adapter's (left out: the host's, else Apple's default). */
+    guardrailsOf(options) {
+        return options.modelOptions?.guardrails ?? this.guardrails;
     }
     /** Whether Apple's model can run here: "downloading" while Apple Intelligence gets it. */
     async availability() {
         try {
-            const answer = await this.native.availability();
+            const answer = await this.native.availability(this.guardrails ? { guardrails: this.guardrails } : undefined);
             return answer.available ? "available" : AVAILABILITY[answer.reason ?? "unavailable"];
         }
         catch {
@@ -142,7 +170,7 @@ export class AfmTextAdapter extends BaseTextAdapter {
     /** Tokens a session holds, where the OS says (26.4 and later). */
     async contextSize() {
         try {
-            return (await this.native.availability()).contextSize;
+            return (await this.native.availability(this.guardrails ? { guardrails: this.guardrails } : undefined)).contextSize;
         }
         catch {
             return undefined;
@@ -219,7 +247,8 @@ export class AfmTextAdapter extends BaseTextAdapter {
                 description: tool.description ?? "",
                 parameters: toNativeSchema(tool.inputSchema ?? { type: "object", properties: {} }, tool.name)
             })),
-            messages
+            messages,
+            ...(this.guardrailsOf(options) && { guardrails: this.guardrailsOf(options) })
         });
         return thread;
     }
@@ -241,7 +270,10 @@ export class AfmTextAdapter extends BaseTextAdapter {
             maximumResponseTokens,
             // A response keeps the mode it started with: a step with another mode
             // (required, then auto) can't resume it, and starts a new session.
-            toolCallingModeOf(options)
+            toolCallingModeOf(options),
+            // A session's guardrails are its model's: other guardrails, another session.
+            // None named isn't "default": the host's (serveAfm's) may be permissive.
+            this.guardrailsOf(options) ?? "inherited"
         ]);
         const keys = options.messages.map(messageKey);
         // A kept session, or one whose response waits for tool results.
@@ -472,7 +504,7 @@ export class AfmTextAdapter extends BaseTextAdapter {
                 const event = await thread.queue.next(signal);
                 if (event.type === "done") {
                     const usage = usageOf(event.usage);
-                    return { data: JSON.parse(event.text), rawText: event.text, model: this.model, ...(usage && { usage }) };
+                    return { data: event.asText ? checkedAnswer(event.text, outputSchema) : JSON.parse(event.text), rawText: event.text, model: this.model, ...(usage && { usage }) };
                 }
                 if (event.type === "error")
                     throw Object.assign(new Error(event.message), { code: event.code });

package/dist/electron.d.ts

@@ -1,3 +1,4 @@
+import type { AfmGuardrails } from "./native.js";
 export type ServeAfmOptions = {
     /**
      * The folder with the package's Electron files (afm.node and preload.cjs):
@@ -12,6 +13,12 @@ export type ServeAfmOptions = {
      * but an http(s) one on another host than localhost.
      */
     allow?: (url: string) => boolean;
+    /**
+     * Apple's guardrails for every page's sessions that don't name their own
+     * (`afmText({ guardrails })` or a request's `modelOptions.guardrails`):
+     * "default" (the default), or "permissiveContentTransformations".
+     */
+    guardrails?: AfmGuardrails;
 };
 /**
  * Runs Apple's on-device model for the app's pages, where `afmText()` finds it.

package/dist/electron.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"electron.d.ts","sourceRoot":"","sources":["../src/electron.ts"],"names":[],"mappings":"AA6CA,MAAM,MAAM,eAAe,GAAG;IAC5B;;;;;;OAMG;IACH,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB;;;OAGG;IACH,KAAK,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,OAAO,CAAA;CACjC,CAAA;AAgBD;;;;GAIG;AACH,wBAAgB,QAAQ,CAAC,OAAO,GAAE,eAAoB,GAAG,IAAI,CAmG5D"}
+{"version":3,"file":"electron.d.ts","sourceRoot":"","sources":["../src/electron.ts"],"names":[],"mappings":"AAiBA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,aAAa,CAAA;AA8BhD,MAAM,MAAM,eAAe,GAAG;IAC5B;;;;;;OAMG;IACH,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB;;;OAGG;IACH,KAAK,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,OAAO,CAAA;IAChC;;;;OAIG;IACH,UAAU,CAAC,EAAE,aAAa,CAAA;CAC3B,CAAA;AAgBD;;;;GAIG;AACH,wBAAgB,QAAQ,CAAC,OAAO,GAAE,eAAoB,GAAG,IAAI,CAwG5D"}

package/dist/electron.js

@@ -20,6 +20,7 @@ let served = false;
  * macOS 26, or elsewhere, the pages hear the model is unavailable.
  */
 export function serveAfm(options = {}) {
+    const appGuardrails = options.guardrails;
     if (served)
         return;
     served = true;
@@ -85,6 +86,10 @@ export function serveAfm(options = {}) {
             throw new Error("Apple's on-device model needs macOS 26 on a Mac with Apple silicon");
         }
         const options = { ...(typeof args === "object" && args !== null ? args : {}) };
+        // The app's guardrails, where the page names none.
+        if ((method === "createSession" || method === "availability") && options.guardrails === undefined && appGuardrails) {
+            options.guardrails = appGuardrails;
+        }
         // The frame's own session: another frame's can't be reached.
         if (typeof options.sessionId === "string") {
             const frameId = frameIdOf(frame);

package/dist/index.d.ts

@@ -10,7 +10,7 @@ export type { Availability, AfmConfig, AfmTextModelOptions } from "./adapter.js"
 export { Afm } from "./native.js";
 export { serveAfm } from "./electron.js";
 export type { ServeAfmOptions } from "./electron.js";
-export type { AfmNative, NativeAvailability, NativeEvent, NativeGenerationSchema, NativeMessage, NativeProperty, NativeSchema, NativeTool, NativeUsage, UnavailableReason } from "./native.js";
+export type { AfmGuardrails, AfmNative, NativeAvailability, NativeEvent, NativeGenerationSchema, NativeMessage, NativeProperty, NativeSchema, NativeTool, NativeUsage, UnavailableReason } from "./native.js";
 export { toNativeSchema } from "./schema.js";
 export { AFM_CHAT_MODELS, AFM_MODEL_META } from "./model-meta.js";
 export type { AfmChatModel, AfmModelMeta } from "./model-meta.js";

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,OAAO,EAAE,cAAc,EAAE,OAAO,EAAE,MAAM,cAAc,CAAA;AACtD,YAAY,EAAE,YAAY,EAAE,SAAS,EAAE,mBAAmB,EAAE,MAAM,cAAc,CAAA;AAChF,OAAO,EAAE,GAAG,EAAE,MAAM,aAAa,CAAA;AACjC,OAAO,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAA;AACxC,YAAY,EAAE,eAAe,EAAE,MAAM,eAAe,CAAA;AACpD,YAAY,EACV,SAAS,EACT,kBAAkB,EAClB,WAAW,EACX,sBAAsB,EACtB,aAAa,EACb,cAAc,EACd,YAAY,EACZ,UAAU,EACV,WAAW,EACX,iBAAiB,EAClB,MAAM,aAAa,CAAA;AACpB,OAAO,EAAE,cAAc,EAAE,MAAM,aAAa,CAAA;AAC5C,OAAO,EAAE,eAAe,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAA;AACjE,YAAY,EAAE,YAAY,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,OAAO,EAAE,cAAc,EAAE,OAAO,EAAE,MAAM,cAAc,CAAA;AACtD,YAAY,EAAE,YAAY,EAAE,SAAS,EAAE,mBAAmB,EAAE,MAAM,cAAc,CAAA;AAChF,OAAO,EAAE,GAAG,EAAE,MAAM,aAAa,CAAA;AACjC,OAAO,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAA;AACxC,YAAY,EAAE,eAAe,EAAE,MAAM,eAAe,CAAA;AACpD,YAAY,EACV,aAAa,EACb,SAAS,EACT,kBAAkB,EAClB,WAAW,EACX,sBAAsB,EACtB,aAAa,EACb,cAAc,EACd,YAAY,EACZ,UAAU,EACV,WAAW,EACX,iBAAiB,EAClB,MAAM,aAAa,CAAA;AACpB,OAAO,EAAE,cAAc,EAAE,MAAM,aAAa,CAAA;AAC5C,OAAO,EAAE,eAAe,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAA;AACjE,YAAY,EAAE,YAAY,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAA"}

package/dist/json-value.d.ts

@@ -0,0 +1,9 @@
+/**
+ * The JSON value in a model's text answer: the whole trimmed text, or, when the
+ * model wrapped it in a Markdown code fence, everything inside the fence. Any
+ * value: an object, an array, a string, a number, a boolean or null. Never by
+ * brace positions, which would cut an array down to one of its objects, or a
+ * string that contains braces out of its quotes.
+ */
+export declare function parseJsonValue(text: string): unknown;
+//# sourceMappingURL=json-value.d.ts.map

package/dist/json-value.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"json-value.d.ts","sourceRoot":"","sources":["../src/json-value.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CASpD"}

package/dist/json-value.js

@@ -0,0 +1,19 @@
+/**
+ * The JSON value in a model's text answer: the whole trimmed text, or, when the
+ * model wrapped it in a Markdown code fence, everything inside the fence. Any
+ * value: an object, an array, a string, a number, a boolean or null. Never by
+ * brace positions, which would cut an array down to one of its objects, or a
+ * string that contains braces out of its quotes.
+ */
+export function parseJsonValue(text) {
+    const trimmed = text.trim();
+    try {
+        return JSON.parse(trimmed);
+    }
+    catch (error) {
+        const fenced = /^```[\w-]*[^\S\n]*\n([\s\S]*?)\n?```$/.exec(trimmed);
+        if (fenced)
+            return JSON.parse(fenced[1].trim());
+        throw error;
+    }
+}

package/dist/native.d.ts

@@ -107,22 +107,34 @@ export type NativeEvent = {
         name: string;
         arguments: string;
     }>;
-} | {
+}
+/** `asText`: a schema's answer written as text (permissive guardrails' fallback), not held to the schema. */
+ | {
     type: "done";
     text: string;
     usage?: NativeUsage;
+    asText?: boolean;
 } | {
     type: "error";
     code: string;
     message: string;
 });
+/**
+ * Apple's guardrails for the model: "default", or "permissiveContentTransformations",
+ * which lets through text the default ones can block out of context (a card game's
+ * "Searing Blood" or "Play with Fire").
+ */
+export type AfmGuardrails = "default" | "permissiveContentTransformations";
 export interface AfmNative {
-    availability(): Promise<NativeAvailability>;
+    availability(options?: {
+        guardrails?: AfmGuardrails;
+    }): Promise<NativeAvailability>;
     createSession(options: {
         sessionId: string;
         instructions?: string;
         tools: Array<NativeTool>;
         messages: Array<NativeMessage>;
+        guardrails?: AfmGuardrails;
     }): Promise<void>;
     prewarm(options: {
         sessionId: string;

package/dist/native.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"native.d.ts","sourceRoot":"","sources":["../src/native.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"native.d.ts","sourceRoot":"","sources":["../src/native.ts"],"names":[],"mappings":"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"}

package/dist/native.js

@@ -10,7 +10,7 @@ const capacitor = () => (loading ??= import("@capacitor/core").then(({ registerP
  * its calls reject: Capacitor has no web version of it.
  */
 export const Afm = {
-    availability: async () => (await capacitor()).plugin.availability(),
+    availability: async (options) => (await capacitor()).plugin.availability(options),
     createSession: async (options) => (await capacitor()).plugin.createSession(options),
     prewarm: async (options) => (await capacitor()).plugin.prewarm(options),
     respond: async (options) => (await capacitor()).plugin.respond(options),

package/dist/validate.d.ts

@@ -0,0 +1,2 @@
+export declare function schemaErrors(schema: unknown, value: unknown): Array<string>;
+//# sourceMappingURL=validate.d.ts.map

package/dist/validate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"validate.d.ts","sourceRoot":"","sources":["../src/validate.ts"],"names":[],"mappings":"AAiCA,wBAAgB,YAAY,CAAC,MAAM,EAAE,OAAO,EAAE,KAAK,EAAE,OAAO,GAAG,KAAK,CAAC,MAAM,CAAC,CA8E3E"}

package/dist/validate.js

@@ -0,0 +1,124 @@
+const isObject = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+const typeOf = (value) => (value === null ? "null" : Array.isArray(value) ? "array" : typeof value);
+function equal(a, b) {
+    if (a === b)
+        return true;
+    if (Array.isArray(a) && Array.isArray(b))
+        return a.length === b.length && a.every((v, i) => equal(v, b[i]));
+    if (isObject(a) && isObject(b)) {
+        const keys = Object.keys(a);
+        return keys.length === Object.keys(b).length && keys.every((k) => Object.hasOwn(b, k) && equal(a[k], b[k]));
+    }
+    return false;
+}
+function fitsType(type, value) {
+    if (type === "integer")
+        return typeof value === "number" && Number.isInteger(value);
+    if (type === "number")
+        return typeof value === "number" && Number.isFinite(value);
+    return typeOf(value) === type;
+}
+const show = (value) => JSON.stringify(value);
+export function schemaErrors(schema, value) {
+    const root = isObject(schema) ? schema : {};
+    const errors = [];
+    const resolve = (ref) => {
+        const match = /^#\/(\$defs|definitions)\/(.+)$/.exec(ref);
+        const defs = match ? root[match[1]] : undefined;
+        return match && isObject(defs) ? defs[decodeURIComponent(match[2])] : undefined;
+    };
+    const check = (s, v, path, out) => {
+        if (s === true || s === undefined)
+            return;
+        if (s === false)
+            return void out.push(`${path || "/"}: not allowed`);
+        if (!isObject(s))
+            return;
+        if (typeof s.$ref === "string") {
+            const target = resolve(s.$ref);
+            if (target === undefined)
+                return void out.push(`${path || "/"}: unknown $ref ${s.$ref}`);
+            check(target, v, path, out);
+        }
+        const at = path || "/";
+        if ("const" in s && !equal(s.const, v))
+            out.push(`${at}: should be ${show(s.const)}, not ${show(v)}`);
+        if (Array.isArray(s.enum) && !s.enum.some((e) => equal(e, v)))
+            out.push(`${at}: ${show(v)} is not one of ${s.enum.map(show).join(", ")}`);
+        if (s.type !== undefined) {
+            const types = (Array.isArray(s.type) ? s.type : [s.type]).filter((t) => typeof t === "string");
+            if (types.length > 0 && !types.some((t) => fitsType(t, v))) {
+                out.push(`${at}: should be ${types.join(" or ")}, not ${typeOf(v)}`);
+                return;
+            }
+        }
+        if (Array.isArray(s.allOf))
+            for (const part of s.allOf)
+                check(part, v, path, out);
+        for (const key of ["anyOf", "oneOf"]) {
+            const choices = s[key];
+            if (!Array.isArray(choices))
+                continue;
+            const fitting = choices.filter((choice) => {
+                const sub = [];
+                check(choice, v, path, sub);
+                return sub.length === 0;
+            }).length;
+            if (key === "anyOf" ? fitting === 0 : fitting !== 1)
+                out.push(`${at}: fits ${fitting} of its ${key} choices`);
+        }
+        if (isObject(v)) {
+            const properties = isObject(s.properties) ? s.properties : {};
+            if (Array.isArray(s.required)) {
+                for (const key of s.required)
+                    if (typeof key === "string" && !Object.hasOwn(v, key))
+                        out.push(`${path}/${key}: missing`);
+            }
+            for (const [key, item] of Object.entries(v)) {
+                if (Object.hasOwn(properties, key))
+                    check(properties[key], item, `${path}/${key}`, out);
+                else if (s.additionalProperties === false)
+                    out.push(`${path}/${key}: not a property of the schema`);
+                else if (isObject(s.additionalProperties))
+                    check(s.additionalProperties, item, `${path}/${key}`, out);
+            }
+        }
+        if (Array.isArray(v)) {
+            if (typeof s.minItems === "number" && v.length < s.minItems)
+                out.push(`${at}: fewer than ${s.minItems} items`);
+            if (typeof s.maxItems === "number" && v.length > s.maxItems)
+                out.push(`${at}: more than ${s.maxItems} items`);
+            if (Array.isArray(s.items))
+                s.items.forEach((item, i) => i < v.length && check(item, v[i], `${path}/${i}`, out));
+            else if (s.items !== undefined)
+                v.forEach((item, i) => check(s.items, item, `${path}/${i}`, out));
+        }
+        if (typeof v === "string") {
+            if (typeof s.minLength === "number" && [...v].length < s.minLength)
+                out.push(`${at}: shorter than ${s.minLength}`);
+            if (typeof s.maxLength === "number" && [...v].length > s.maxLength)
+                out.push(`${at}: longer than ${s.maxLength}`);
+            if (typeof s.pattern === "string") {
+                try {
+                    if (!new RegExp(s.pattern, "u").test(v))
+                        out.push(`${at}: doesn't match ${s.pattern}`);
+                }
+                catch {
+                    // A pattern JavaScript can't read isn't checked.
+                }
+            }
+        }
+        if (typeof v === "number") {
+            if (typeof s.minimum === "number" && v < s.minimum)
+                out.push(`${at}: less than ${s.minimum}`);
+            if (typeof s.maximum === "number" && v > s.maximum)
+                out.push(`${at}: more than ${s.maximum}`);
+            if (typeof s.exclusiveMinimum === "number" && v <= s.exclusiveMinimum)
+                out.push(`${at}: not more than ${s.exclusiveMinimum}`);
+            if (typeof s.exclusiveMaximum === "number" && v >= s.exclusiveMaximum)
+                out.push(`${at}: not less than ${s.exclusiveMaximum}`);
+        }
+    };
+    check(root, value, "", errors);
+    return errors;
+}

package/electron/AfmNode.swift

@@ -52,7 +52,7 @@ public func afm_call(_ method: UnsafePointer<CChar>, _ options: UnsafePointer<CC
     if #available(macOS 26.0, *) {
         do {
             switch name {
-            case "availability": reply = ["result": AfmBridge.availability()]
+            case "availability": reply = ["result": AfmBridge.availability(object)]
             case "createSession": try bridge().createSession(object); reply = ["result": NSNull()]
             case "prewarm": try bridge().prewarm(object); reply = ["result": NSNull()]
             case "respond": try bridge().respond(object); reply = ["result": NSNull()]

package/electron/afm.node.sha256

@@ -1 +1 @@
-2e804dcb3921aad737e0924db1975955882393feff18f01dddd48bb5a7855ad3
+7242528a429eafaaa0928604d5ca0130429ded1465d72e765876097777d1f9e1

package/ios/Sources/AfmCore/Bridge.swift

@@ -15,9 +15,11 @@ import FoundationModels
 /// Events, each with the `sessionId` and the `turn` of the `respond` call:
 /// - `{ type: "delta", text }`: more of the response.
 /// - `{ type: "toolCalls", calls: [{ id, name, arguments }] }`: `arguments` in JSON.
-/// - `{ type: "done", text, usage }`: the response, and its tokens (iOS/macOS 27):
+/// - `{ type: "done", text, usage, asText }`: the response, and its tokens (iOS/macOS 27):
 ///   `inputTokens` and `outputTokens` over every pass of the model (a tool call's
 ///   too), and `cachedTokens` only for a session without tools (see `usage()`).
+///   `asText` when a schema's answer was written as text (a permissive session's
+///   fallback, see `run`): not held to the schema, so the caller checks it.
 /// - `{ type: "error", code, message }`.
 @available(iOS 26.0, macOS 26.0, *)
 public final class AfmBridge: @unchecked Sendable {
@@ -31,9 +33,20 @@ public final class AfmBridge: @unchecked Sendable {
         self.emit = emit
     }
 
-    /// Whether the model can run here, why not, and the tokens a session holds.
-    public static func availability() -> [String: Any] {
-        let model = SystemLanguageModel.default
+    /// The model with the guardrails `options` names: "permissiveContentTransformations",
+    /// or the default ones. Apple's default guardrails can block ordinary text that
+    /// sounds unsafe out of context (a card game's "Searing Blood", "Play with Fire").
+    static func model(_ options: [String: Any]) -> SystemLanguageModel {
+        switch options["guardrails"] as? String {
+        case "permissiveContentTransformations": return SystemLanguageModel(guardrails: .permissiveContentTransformations)
+        default: return .default
+        }
+    }
+
+    /// Whether the model can run here, why not, and the tokens a session holds:
+    /// the model with the guardrails `options` names.
+    public static func availability(_ options: [String: Any] = [:]) -> [String: Any] {
+        let model = model(options)
         var result: [String: Any]
         switch model.availability {
         case .available:
@@ -55,8 +68,9 @@ public final class AfmBridge: @unchecked Sendable {
     }
 
     /// Starts a session: `sessionId`, `instructions`, `tools` ([{ name, description,
-    /// parameters }]) and `messages`, the conversation it starts from. A session with
-    /// the same id is ended first.
+    /// parameters }]), `messages`, the conversation it starts from, and `guardrails`
+    /// ("default" or "permissiveContentTransformations"). A session with the same id
+    /// is ended first.
     public func createSession(_ options: [String: Any]) throws {
         let id = try Self.string(options, "sessionId")
         deleteSession(id)
@@ -75,8 +89,9 @@ public final class AfmBridge: @unchecked Sendable {
             tools: tools.map { Transcript.ToolDefinition(tool: $0) },
             messages: options["messages"] as? [Any] ?? []
         )
-        state.session = LanguageModelSession(model: .default, tools: tools, transcript: transcript)
+        state.session = LanguageModelSession(model: Self.model(options), tools: tools, transcript: transcript)
         state.hasTools = !tools.isEmpty
+        state.permissive = (options["guardrails"] as? String) == "permissiveContentTransformations"
         lock.withLock { sessions[id] = state }
     }
 
@@ -143,6 +158,8 @@ final class BridgeSession: @unchecked Sendable {
     let id: String
     var session: LanguageModelSession!
     var hasTools = false
+    /// Permissive guardrails: structured answers come as text (see `AfmBridge.respond`).
+    var permissive = false
 
     private let emit: AfmBridge.Emit
     private let lock = NSLock()
@@ -173,12 +190,30 @@ final class BridgeSession: @unchecked Sendable {
         }
     }
 
+    /// What a prompt adds to ask for a schema's answer as text: a JSON value (an object,
+    /// an array or a primitive, as the schema says) that matches it.
+    static func asJSON(_ schema: GenerationSchema) -> String {
+        let json = (try? JSONEncoder().encode(schema)).flatMap { String(data: $0, encoding: .utf8) } ?? ""
+        return "\n\nAnswer with only a JSON value, and no other text, that matches this JSON Schema:\n\(json)"
+    }
+
     private func run(_ prompt: String, _ options: GenerationOptions, _ schema: GenerationSchema?) async {
         let before = usage()
         var text = ""
+        var asText = false
         do {
             if let schema {
-                text = try await session.respond(to: prompt, schema: schema, options: options).content.jsonString
+                do {
+                    text = try await session.respond(to: prompt, schema: schema, options: options).content.jsonString
+                } catch where permissive && Self.code(error) == "guardrailViolation" {
+                    // Permissive guardrails cover String responses only: Apple documents that
+                    // any other response (a schema's) gets the default guardrails, which block
+                    // text such as "add 2 Searing Blood". So a blocked answer is asked for again
+                    // as text, a JSON value to the schema in JSON Schema. `done` says so
+                    // (`asText`): the framework didn't hold it to the schema, the caller checks it.
+                    text = try await session.respond(to: prompt + Self.asJSON(schema), options: options).content
+                    asText = true
+                }
             } else {
                 for try await snapshot in session.streamResponse(to: prompt, options: options) {
                     let content = snapshot.content
@@ -190,6 +225,7 @@ final class BridgeSession: @unchecked Sendable {
             // A stopped response's stream may just end.
             try Task.checkCancellation()
             var done: [String: Any] = ["type": "done", "text": text]
+            if asText { done["asText"] = true }
             if let before, let after = usage() {
                 var usage: [String: Any] = [
                     "inputTokens": after.input - before.input,
@@ -293,6 +329,9 @@ final class BridgeSession: @unchecked Sendable {
 
     /// An error's case name (`exceededContextWindowSize`, `guardrailViolation`, …).
     static func code(_ error: Error) -> String {
+        // An enum error's case: LanguageModelError (iOS/macOS 27) describes itself with its
+        // message ("Response may contain sensitive or unsafe content"), not its case.
+        if let label = Mirror(reflecting: error).children.first?.label { return label }
         let text = String(describing: error)
         return String(text.prefix { $0 != "(" && $0 != ":" && $0 != " " })
     }

package/ios/Sources/AfmPlugin/AfmPlugin.swift

@@ -36,7 +36,7 @@ public class AfmPlugin: CAPPlugin, CAPBridgedPlugin {
             call.resolve(["available": false, "reason": "unsupportedOS"])
             return
         }
-        call.resolve(AfmBridge.availability())
+        call.resolve(AfmBridge.availability(call.options as? [String: Any] ?? [:]))
     }
 
     @objc func createSession(_ call: CAPPluginCall) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tanstack-ai-browser/afm",
-  "version": "0.2.1",
+  "version": "0.2.2",
   "description": "TanStack AI adapter for Apple's on-device Foundation Model (AFM), through Apple's framework itself, with native tool calling: a Capacitor plugin for iOS, and serveAfm() for Electron on macOS",
   "license": "MIT",
   "author": "daveycodez",
@@ -84,9 +84,6 @@
       }
     }
   },
-  "scripts": {
-    "test": "node --import @swc-node/register/esm-register --test \"src/**/*.test.ts\""
-  },
   "peerDependencies": {
     "@capacitor/core": "^8.0.0",
     "@tanstack/ai": "^1.2.0"
@@ -96,5 +93,8 @@
     "@tanstack/ai": "1.4.0",
     "electron": "^45.3.1",
     "node-api-headers": "1.9.0"
+  },
+  "scripts": {
+    "test": "node --import @swc-node/register/esm-register --test \"src/**/*.test.ts\""
   }
-}
+}

package/src/adapter.test.ts

@@ -1,6 +1,7 @@
 import assert from "node:assert/strict"
 import { beforeEach, test } from "node:test"
 
+import { chat } from "@tanstack/ai"
 import type { TextOptions } from "@tanstack/ai"
 
 import { afmText } from "./adapter.js"
@@ -24,7 +25,8 @@ class FakeNative implements AfmNative {
   private turns = new Map<string, number>()
   private waiting = new Map<string, Set<string>>()
 
-  async availability() {
+  async availability(options?: Record<string, unknown>) {
+    this.calls.push(["availability", options ?? {}])
     return this.answer
   }
   async addListener(_name: "event", listener: (event: NativeEvent) => void) {
@@ -378,3 +380,49 @@ test("a request already stopped starts no native work, even when the bridge woul
   assert.equal(native.named("respond").length, 0)
   assert.equal(textIn(chunks), "")
 })
+
+test("guardrails reach the native side: the adapter's for every session and the availability check, a request's over it", async () => {
+  const adapter = afmText({ native, guardrails: "permissiveContentTransformations" })
+  assert.equal(await adapter.availability(), "available")
+  assert.deepEqual(native.named("availability").at(-1), { guardrails: "permissiveContentTransformations" })
+  await run(adapter, { threadId: "permissive" })
+  assert.equal(native.named("createSession").at(-1)?.guardrails, "permissiveContentTransformations")
+  await run(adapter, { threadId: "own", modelOptions: { guardrails: "default" } })
+  assert.equal(native.named("createSession").at(-1)?.guardrails, "default")
+  // None named: none sent, so the host's (serveAfm's) or Apple's default applies.
+  await run(afmText({ native }), { threadId: "none" })
+  assert.equal("guardrails" in (native.named("createSession").at(-1) ?? {}), false)
+})
+
+test("a thread whose guardrails change starts a new session: a session's guardrails are its model's", async () => {
+  const adapter = afmText({ native })
+  native.replies = [[{ type: "done", text: "Hi." }], [{ type: "done", text: "Hi again." }]]
+  await run(adapter, { messages: [user("Hi")] })
+  await run(adapter, { messages: [user("Hi"), { role: "assistant", content: "Hi." }, user("Again")], modelOptions: { guardrails: "permissiveContentTransformations" } })
+  assert.equal(native.named("createSession").length, 2)
+})
+
+test("a thread moving between inherited guardrails and an explicit default starts a new session, both ways", async () => {
+  for (const [first, second] of [[undefined, "default"], ["default", undefined]] as const) {
+    native = new FakeNative()
+    const adapter = afmText({ native })
+    native.replies = [[{ type: "done", text: "Hi." }], [{ type: "done", text: "Hi again." }]]
+    await run(adapter, { messages: [user("Hi")], ...(first && { modelOptions: { guardrails: first } }) })
+    await run(adapter, { messages: [user("Hi"), { role: "assistant", content: "Hi." }, user("Again")], ...(second && { modelOptions: { guardrails: second } }) })
+    assert.equal(native.named("createSession").length, 2, `${first ?? "inherited"} then ${second ?? "inherited"}`)
+  }
+})
+
+test("a structured answer written as text (asText) must fit the schema: chat() alone doesn't check plain JSON Schema", async () => {
+  const outputSchema = { type: "object", properties: { city: { type: "string" }, unit: { type: "string", enum: ["c", "f"] } }, required: ["city", "unit"] }
+  const ask = (text: string) => {
+    native = new FakeNative()
+    native.replies = [[{ type: "done", text, asText: true }]]
+    return chat({ adapter: afmText({ native }), threadId: "structured", messages: [user("Weather?")], outputSchema, stream: false } as never) as unknown as Promise<unknown>
+  }
+  assert.deepEqual(await ask('```json\n{"city":"Paris","unit":"c"}\n```'), { city: "Paris", unit: "c" })
+  await assert.rejects(ask('{"city":123,"unit":"c"}'), /\/city: should be string, not number/)
+  await assert.rejects(ask('{"unit":"c"}'), /\/city: missing/)
+  await assert.rejects(ask('{"city":"Paris","unit":"kelvin"}'), /\/unit: "kelvin" is not one of "c", "f"/)
+  await assert.rejects(ask("Sorry, I can't help with that."), /wrote no JSON for the schema/)
+})

package/src/adapter.ts

@@ -24,8 +24,10 @@ import type { StructuredOutputOptions, StructuredOutputResult } from "@tanstack/
 import { contentText, toNativeMessages } from "./messages.js"
 import type { AfmChatModel } from "./model-meta.js"
 import { Afm } from "./native.js"
-import type { AfmNative, NativeEvent, NativeMessage, NativeUsage, UnavailableReason } from "./native.js"
+import type { AfmGuardrails, AfmNative, NativeEvent, NativeMessage, NativeUsage, UnavailableReason } from "./native.js"
 import { toNativeSchema } from "./schema.js"
+import { parseJsonValue } from "./json-value.js"
+import { schemaErrors } from "./validate.js"
 
 export type AfmConfig = {
   /**
@@ -34,13 +36,21 @@ export type AfmConfig = {
    * plugin (`Afm`).
    */
   native?: AfmNative
+  /**
+   * Apple's guardrails: "default" (the default), or "permissiveContentTransformations",
+   * for text the default ones block out of context, such as a card game's card
+   * names. A request's `modelOptions.guardrails` overrides it.
+   */
+  guardrails?: AfmGuardrails
 }
 
-/** Per-call `modelOptions`: the response's sampling and length. */
+/** Per-call `modelOptions`: the response's sampling and length, and the guardrails. */
 export type AfmTextModelOptions = {
   temperature?: number
   /** Most tokens to generate. */
   maximumResponseTokens?: number
+  /** Apple's guardrails for this request's session, over the adapter's `guardrails`. */
+  guardrails?: AfmGuardrails
 }
 
 export type Availability = "unavailable" | "downloadable" | "downloading" | "available"
@@ -167,6 +177,26 @@ const nextId = (prefix: string) => `${prefix}_${Date.now().toString(36)}_${(ids+
 const signalOf = (options: TextOptions<AfmTextModelOptions>) =>
   options.abortController?.signal ?? (options.request as RequestInit | undefined)?.signal ?? undefined
 
+/**
+ * A structured answer the model wrote as text (permissive guardrails' fallback,
+ * which the framework didn't hold to the schema): its JSON value, if it fits the
+ * schema. chat() validates only schemas with a Standard Schema validator, not
+ * plain JSON Schema, so the adapter checks it here.
+ */
+function checkedAnswer(text: string, schema: unknown): unknown {
+  let data: unknown
+  try {
+    data = parseJsonValue(text)
+  } catch (error) {
+    throw Object.assign(new Error(`Apple's model wrote no JSON for the schema (its answer, written as text past its guardrails, was ${JSON.stringify(text.slice(0, 120))})`, { cause: error }), { code: "invalidJson" })
+  }
+  const problems = schemaErrors(schema, data)
+  if (problems.length > 0) {
+    throw Object.assign(new Error(`Apple's model's answer, written as text past its guardrails, doesn't fit the schema: ${problems.slice(0, 5).join("; ")}`), { code: "schemaMismatch" })
+  }
+  return data
+}
+
 const parse = (json: string): unknown => {
   try {
     return JSON.parse(json)
@@ -199,12 +229,20 @@ export class AfmTextAdapter extends BaseTextAdapter<
   constructor(config: AfmConfig, model: AfmChatModel) {
     super({}, model)
     this.native = config.native ?? (globalThis as { afm?: AfmNative }).afm ?? Afm
+    this.guardrails = config.guardrails
+  }
+
+  private readonly guardrails: AfmGuardrails | undefined
+
+  /** A request's guardrails: its own, else the adapter's (left out: the host's, else Apple's default). */
+  private guardrailsOf(options: TextOptions<AfmTextModelOptions>) {
+    return options.modelOptions?.guardrails ?? this.guardrails
   }
 
   /** Whether Apple's model can run here: "downloading" while Apple Intelligence gets it. */
   async availability(): Promise<Availability> {
     try {
-      const answer = await this.native.availability()
+      const answer = await this.native.availability(this.guardrails ? { guardrails: this.guardrails } : undefined)
       return answer.available ? "available" : AVAILABILITY[answer.reason ?? "unavailable"]
     } catch {
       return "unavailable"
@@ -214,7 +252,7 @@ export class AfmTextAdapter extends BaseTextAdapter<
   /** Tokens a session holds, where the OS says (26.4 and later). */
   async contextSize(): Promise<number | undefined> {
     try {
-      return (await this.native.availability()).contextSize
+      return (await this.native.availability(this.guardrails ? { guardrails: this.guardrails } : undefined)).contextSize
     } catch {
       return undefined
     }
@@ -296,7 +334,8 @@ export class AfmTextAdapter extends BaseTextAdapter<
         description: tool.description ?? "",
         parameters: toNativeSchema(tool.inputSchema ?? { type: "object", properties: {} }, tool.name)
       })),
-      messages
+      messages,
+      ...(this.guardrailsOf(options) && { guardrails: this.guardrailsOf(options) })
     })
     return thread
   }
@@ -319,7 +358,10 @@ export class AfmTextAdapter extends BaseTextAdapter<
       maximumResponseTokens,
       // A response keeps the mode it started with: a step with another mode
       // (required, then auto) can't resume it, and starts a new session.
-      toolCallingModeOf(options)
+      toolCallingModeOf(options),
+      // A session's guardrails are its model's: other guardrails, another session.
+      // None named isn't "default": the host's (serveAfm's) may be permissive.
+      this.guardrailsOf(options) ?? "inherited"
     ])
     const keys = options.messages.map(messageKey)
     // A kept session, or one whose response waits for tool results.
@@ -539,7 +581,7 @@ export class AfmTextAdapter extends BaseTextAdapter<
         const event = await thread.queue.next(signal)
         if (event.type === "done") {
           const usage = usageOf(event.usage)
-          return { data: JSON.parse(event.text) as unknown, rawText: event.text, model: this.model, ...(usage && { usage }) }
+          return { data: event.asText ? checkedAnswer(event.text, outputSchema) : (JSON.parse(event.text) as unknown), rawText: event.text, model: this.model, ...(usage && { usage }) }
         }
         if (event.type === "error") throw Object.assign(new Error(event.message), { code: event.code })
       }

package/src/electron.ts

@@ -15,6 +15,8 @@
  */
 import type { App, IpcMain, Session, WebContents, WebFrameMain } from "electron"
 
+import type { AfmGuardrails } from "./native.js"
+
 const PACKAGE = "@tanstack-ai-browser/afm"
 const CALL = "afm:call"
 const EVENT = "afm:event"
@@ -57,6 +59,12 @@ export type ServeAfmOptions = {
    * but an http(s) one on another host than localhost.
    */
   allow?: (url: string) => boolean
+  /**
+   * Apple's guardrails for every page's sessions that don't name their own
+   * (`afmText({ guardrails })` or a request's `modelOptions.guardrails`):
+   * "default" (the default), or "permissiveContentTransformations".
+   */
+  guardrails?: AfmGuardrails
 }
 
 const appPages = (url: string) => {
@@ -79,6 +87,7 @@ let served = false
  * macOS 26, or elsewhere, the pages hear the model is unavailable.
  */
 export function serveAfm(options: ServeAfmOptions = {}): void {
+  const appGuardrails = options.guardrails
   if (served) return
   served = true
   const node = (globalThis as unknown as { process: NodeProcess }).process
@@ -140,6 +149,10 @@ export function serveAfm(options: ServeAfmOptions = {}): void {
       throw new Error("Apple's on-device model needs macOS 26 on a Mac with Apple silicon")
     }
     const options = { ...(typeof args === "object" && args !== null ? args : {}) } as Record<string, unknown>
+    // The app's guardrails, where the page names none.
+    if ((method === "createSession" || method === "availability") && options.guardrails === undefined && appGuardrails) {
+      options.guardrails = appGuardrails
+    }
     // The frame's own session: another frame's can't be reached.
     if (typeof options.sessionId === "string") {
       const frameId = frameIdOf(frame)

package/src/index.ts

@@ -11,6 +11,7 @@ export { Afm } from "./native.js"
 export { serveAfm } from "./electron.js"
 export type { ServeAfmOptions } from "./electron.js"
 export type {
+  AfmGuardrails,
   AfmNative,
   NativeAvailability,
   NativeEvent,

package/src/json-value.test.ts

@@ -0,0 +1,26 @@
+import assert from "node:assert/strict"
+import { test } from "node:test"
+
+import { parseJsonValue } from "./json-value.js"
+
+test("a text answer's JSON value comes whole: arrays, primitives, and strings with braces in them", () => {
+  assert.deepEqual(parseJsonValue('[{"name":"Searing Blood"}]'), [{ name: "Searing Blood" }])
+  assert.deepEqual(parseJsonValue('  [{"a":1},{"b":2}]\n'), [{ a: 1 }, { b: 2 }])
+  assert.equal(parseJsonValue("42"), 42)
+  assert.equal(parseJsonValue("true"), true)
+  assert.equal(parseJsonValue("null"), null)
+  assert.equal(parseJsonValue('"a {b} c"'), "a {b} c")
+  assert.deepEqual(parseJsonValue('{"text":"} {"}'), { text: "} {" })
+})
+
+test("a fenced answer gives everything inside its fence", () => {
+  assert.deepEqual(parseJsonValue('```json\n[{"a":1},{"b":2}]\n```'), [{ a: 1 }, { b: 2 }])
+  assert.equal(parseJsonValue('```\n"a {b} c"\n```'), "a {b} c")
+  assert.deepEqual(parseJsonValue('\n```json\n{\n  "x": [1, 2]\n}\n```\n'), { x: [1, 2] })
+})
+
+test("text that isn't a JSON value, or more than one, fails", () => {
+  assert.throws(() => parseJsonValue("Here you go: {\"a\":1}"))
+  assert.throws(() => parseJsonValue('{"a":1} {"b":2}'))
+  assert.throws(() => parseJsonValue("```json\nnot json\n```"))
+})

package/src/json-value.ts

@@ -0,0 +1,17 @@
+/**
+ * The JSON value in a model's text answer: the whole trimmed text, or, when the
+ * model wrapped it in a Markdown code fence, everything inside the fence. Any
+ * value: an object, an array, a string, a number, a boolean or null. Never by
+ * brace positions, which would cut an array down to one of its objects, or a
+ * string that contains braces out of its quotes.
+ */
+export function parseJsonValue(text: string): unknown {
+  const trimmed = text.trim()
+  try {
+    return JSON.parse(trimmed)
+  } catch (error) {
+    const fenced = /^```[\w-]*[^\S\n]*\n([\s\S]*?)\n?```$/.exec(trimmed)
+    if (fenced) return JSON.parse(fenced[1].trim())
+    throw error
+  }
+}

package/src/native.ts

@@ -60,17 +60,26 @@ export type NativeUsage = { inputTokens: number; cachedTokens?: number; outputTo
 export type NativeEvent = { sessionId: string; turn: number } & (
   | { type: "delta"; text: string }
   | { type: "toolCalls"; calls: Array<{ id: string; name: string; arguments: string }> }
-  | { type: "done"; text: string; usage?: NativeUsage }
+  /** `asText`: a schema's answer written as text (permissive guardrails' fallback), not held to the schema. */
+  | { type: "done"; text: string; usage?: NativeUsage; asText?: boolean }
   | { type: "error"; code: string; message: string }
 )
 
+/**
+ * Apple's guardrails for the model: "default", or "permissiveContentTransformations",
+ * which lets through text the default ones can block out of context (a card game's
+ * "Searing Blood" or "Play with Fire").
+ */
+export type AfmGuardrails = "default" | "permissiveContentTransformations"
+
 export interface AfmNative {
-  availability(): Promise<NativeAvailability>
+  availability(options?: { guardrails?: AfmGuardrails }): Promise<NativeAvailability>
   createSession(options: {
     sessionId: string
     instructions?: string
     tools: Array<NativeTool>
     messages: Array<NativeMessage>
+    guardrails?: AfmGuardrails
   }): Promise<void>
   prewarm(options: { sessionId: string }): Promise<void>
   /** Prompts a session; the response comes as events. A `schema` holds the answer to it (JSON in `done`). */
@@ -108,7 +117,7 @@ const capacitor = () =>
  * its calls reject: Capacitor has no web version of it.
  */
 export const Afm: AfmNative = {
-  availability: async () => (await capacitor()).plugin.availability(),
+  availability: async (options) => (await capacitor()).plugin.availability(options),
   createSession: async (options) => (await capacitor()).plugin.createSession(options),
   prewarm: async (options) => (await capacitor()).plugin.prewarm(options),
   respond: async (options) => (await capacitor()).plugin.respond(options),

package/src/validate.test.ts

@@ -0,0 +1,38 @@
+import assert from "node:assert/strict"
+import { test } from "node:test"
+
+import { schemaErrors } from "./validate.js"
+
+const city = { type: "object", properties: { city: { type: "string" } }, required: ["city"] }
+
+test("a value that fits its schema has no errors", () => {
+  assert.deepEqual(schemaErrors(city, { city: "Paris" }), [])
+  assert.deepEqual(schemaErrors({ type: "array", items: { type: "integer" }, minItems: 1 }, [1, 2]), [])
+  assert.deepEqual(schemaErrors({ type: ["string", "null"] }, null), [])
+})
+
+test("missing required fields, wrong types and values outside an enum are errors, with their paths", () => {
+  assert.deepEqual(schemaErrors(city, {}), ["/city: missing"])
+  assert.deepEqual(schemaErrors(city, { city: 123 }), ["/city: should be string, not number"])
+  assert.deepEqual(schemaErrors(city, "Paris"), ["/: should be object, not string"])
+  const action = { type: "object", properties: { operation: { type: "string", enum: ["add", "remove"] } }, required: ["operation"] }
+  assert.deepEqual(schemaErrors(action, { operation: "burn" }), ['/operation: "burn" is not one of "add", "remove"'])
+  assert.deepEqual(schemaErrors({ type: "integer" }, 1.5), ["/: should be integer, not number"])
+})
+
+test("nested arrays, $refs, choices, extra properties and bounds are checked", () => {
+  const schema = {
+    type: "object",
+    properties: { actions: { type: "array", items: { $ref: "#/$defs/Action" }, maxItems: 2 } },
+    required: ["actions"],
+    $defs: { Action: { type: "object", properties: { n: { type: "integer", minimum: 1, maximum: 4 } }, required: ["n"], additionalProperties: false } }
+  }
+  assert.deepEqual(schemaErrors(schema, { actions: [{ n: 2 }] }), [])
+  assert.deepEqual(schemaErrors(schema, { actions: [{ n: 0 }, { n: 2, x: 1 }, { n: 3 }] }), [
+    "/actions: more than 2 items",
+    "/actions/0/n: less than 1",
+    "/actions/1/x: not a property of the schema"
+  ])
+  assert.deepEqual(schemaErrors({ anyOf: [{ type: "string" }, { type: "integer" }] }, true), ["/: fits 0 of its anyOf choices"])
+  assert.deepEqual(schemaErrors({ const: "a" }, "b"), ['/: should be "a", not "b"'])
+})

package/src/validate.ts

@@ -0,0 +1,112 @@
+/**
+ * Where a value doesn't fit a JSON Schema: each mismatch with its path
+ * ("/actions/0/operation: not one of add, remove"). Empty when it fits. It reads
+ * what afm converts for Apple's framework and the framework holds answers to:
+ * types (with null), objects (properties, required, additionalProperties),
+ * arrays (items, minItems, maxItems), enum, const, anyOf, oneOf, allOf, $ref to
+ * $defs or definitions, string lengths and patterns, and numeric bounds. Other
+ * keywords are left unchecked.
+ */
+type Json = Record<string, unknown>
+
+const isObject = (value: unknown): value is Json => typeof value === "object" && value !== null && !Array.isArray(value)
+
+const typeOf = (value: unknown) => (value === null ? "null" : Array.isArray(value) ? "array" : typeof value)
+
+function equal(a: unknown, b: unknown): boolean {
+  if (a === b) return true
+  if (Array.isArray(a) && Array.isArray(b)) return a.length === b.length && a.every((v, i) => equal(v, b[i]))
+  if (isObject(a) && isObject(b)) {
+    const keys = Object.keys(a)
+    return keys.length === Object.keys(b).length && keys.every((k) => Object.hasOwn(b, k) && equal(a[k], b[k]))
+  }
+  return false
+}
+
+function fitsType(type: string, value: unknown) {
+  if (type === "integer") return typeof value === "number" && Number.isInteger(value)
+  if (type === "number") return typeof value === "number" && Number.isFinite(value)
+  return typeOf(value) === type
+}
+
+const show = (value: unknown) => JSON.stringify(value)
+
+export function schemaErrors(schema: unknown, value: unknown): Array<string> {
+  const root = isObject(schema) ? schema : {}
+  const errors: Array<string> = []
+
+  const resolve = (ref: string): unknown => {
+    const match = /^#\/(\$defs|definitions)\/(.+)$/.exec(ref)
+    const defs = match ? root[match[1]] : undefined
+    return match && isObject(defs) ? defs[decodeURIComponent(match[2])] : undefined
+  }
+
+  const check = (s: unknown, v: unknown, path: string, out: Array<string>) => {
+    if (s === true || s === undefined) return
+    if (s === false) return void out.push(`${path || "/"}: not allowed`)
+    if (!isObject(s)) return
+    if (typeof s.$ref === "string") {
+      const target = resolve(s.$ref)
+      if (target === undefined) return void out.push(`${path || "/"}: unknown $ref ${s.$ref}`)
+      check(target, v, path, out)
+    }
+    const at = path || "/"
+    if ("const" in s && !equal(s.const, v)) out.push(`${at}: should be ${show(s.const)}, not ${show(v)}`)
+    if (Array.isArray(s.enum) && !s.enum.some((e) => equal(e, v))) out.push(`${at}: ${show(v)} is not one of ${s.enum.map(show).join(", ")}`)
+    if (s.type !== undefined) {
+      const types = (Array.isArray(s.type) ? s.type : [s.type]).filter((t): t is string => typeof t === "string")
+      if (types.length > 0 && !types.some((t) => fitsType(t, v))) {
+        out.push(`${at}: should be ${types.join(" or ")}, not ${typeOf(v)}`)
+        return
+      }
+    }
+    if (Array.isArray(s.allOf)) for (const part of s.allOf) check(part, v, path, out)
+    for (const key of ["anyOf", "oneOf"] as const) {
+      const choices = s[key]
+      if (!Array.isArray(choices)) continue
+      const fitting = choices.filter((choice) => {
+        const sub: Array<string> = []
+        check(choice, v, path, sub)
+        return sub.length === 0
+      }).length
+      if (key === "anyOf" ? fitting === 0 : fitting !== 1) out.push(`${at}: fits ${fitting} of its ${key} choices`)
+    }
+    if (isObject(v)) {
+      const properties = isObject(s.properties) ? s.properties : {}
+      if (Array.isArray(s.required)) {
+        for (const key of s.required) if (typeof key === "string" && !Object.hasOwn(v, key)) out.push(`${path}/${key}: missing`)
+      }
+      for (const [key, item] of Object.entries(v)) {
+        if (Object.hasOwn(properties, key)) check(properties[key], item, `${path}/${key}`, out)
+        else if (s.additionalProperties === false) out.push(`${path}/${key}: not a property of the schema`)
+        else if (isObject(s.additionalProperties)) check(s.additionalProperties, item, `${path}/${key}`, out)
+      }
+    }
+    if (Array.isArray(v)) {
+      if (typeof s.minItems === "number" && v.length < s.minItems) out.push(`${at}: fewer than ${s.minItems} items`)
+      if (typeof s.maxItems === "number" && v.length > s.maxItems) out.push(`${at}: more than ${s.maxItems} items`)
+      if (Array.isArray(s.items)) s.items.forEach((item, i) => i < v.length && check(item, v[i], `${path}/${i}`, out))
+      else if (s.items !== undefined) v.forEach((item, i) => check(s.items, item, `${path}/${i}`, out))
+    }
+    if (typeof v === "string") {
+      if (typeof s.minLength === "number" && [...v].length < s.minLength) out.push(`${at}: shorter than ${s.minLength}`)
+      if (typeof s.maxLength === "number" && [...v].length > s.maxLength) out.push(`${at}: longer than ${s.maxLength}`)
+      if (typeof s.pattern === "string") {
+        try {
+          if (!new RegExp(s.pattern, "u").test(v)) out.push(`${at}: doesn't match ${s.pattern}`)
+        } catch {
+          // A pattern JavaScript can't read isn't checked.
+        }
+      }
+    }
+    if (typeof v === "number") {
+      if (typeof s.minimum === "number" && v < s.minimum) out.push(`${at}: less than ${s.minimum}`)
+      if (typeof s.maximum === "number" && v > s.maximum) out.push(`${at}: more than ${s.maximum}`)
+      if (typeof s.exclusiveMinimum === "number" && v <= s.exclusiveMinimum) out.push(`${at}: not more than ${s.exclusiveMinimum}`)
+      if (typeof s.exclusiveMaximum === "number" && v >= s.exclusiveMaximum) out.push(`${at}: not less than ${s.exclusiveMaximum}`)
+    }
+  }
+
+  check(root, value, "", errors)
+  return errors
+}