@tanstack-ai-browser/afm 0.0.0-stage → 0.2.2

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 daveycodez
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/Package.swift

@@ -0,0 +1,33 @@
+// swift-tools-version: 5.9
+
+import PackageDescription
+
+// AfmCore is the Swift side of the adapter (AfmBridge), with no Capacitor in it, so
+// other hosts (an Electron addon, Tauri) build it too. AfmPlugin wraps it for
+// Capacitor; `cap sync` adds this package to the iOS app.
+let package = Package(
+    name: "TanstackAiBrowserAfm",
+    platforms: [.iOS(.v15), .macOS(.v14)],
+    products: [
+        .library(name: "TanstackAiBrowserAfm", targets: ["AfmPlugin"]),
+        .library(name: "AfmCore", targets: ["AfmCore"])
+    ],
+    dependencies: [
+        .package(url: "https://github.com/ionic-team/capacitor-swift-pm.git", from: "8.0.0")
+    ],
+    targets: [
+        .target(
+            name: "AfmCore",
+            path: "ios/Sources/AfmCore"
+        ),
+        .target(
+            name: "AfmPlugin",
+            dependencies: [
+                "AfmCore",
+                .product(name: "Capacitor", package: "capacitor-swift-pm"),
+                .product(name: "Cordova", package: "capacitor-swift-pm")
+            ],
+            path: "ios/Sources/AfmPlugin"
+        )
+    ]
+)

package/README.md

@@ -1,3 +1,76 @@
-# Temporary Holding Version
+# @tanstack-ai-browser/afm
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+A [TanStack AI](https://tanstack.com/ai) adapter for Apple's on-device Foundation Model (AFM), the model behind Apple Intelligence, through Apple's Foundation Models framework itself. It ships as a Capacitor plugin for iOS and as `serveAfm()` for Electron on macOS; any other host (Tauri, say) can stand in.
+
+Tool calling is the framework's own. The model's arguments always fit each tool's schema, and it can call several tools at once. A session with tools gets a sentence in its instructions on when to call them: without one, Apple's model on an iPhone calls a tool for every prompt, greetings included. `toolChoice: "required"` (or a named tool) makes the model call one. When it calls a tool, the native response waits; `chat()` runs the tool (approvals included) and the adapter hands the result back to the same response, without the model reading the conversation again.
+
+## Requirements
+
+- iOS 26 or later on a device with Apple Intelligence (iPhone 15 Pro and later), with Apple Intelligence turned on. The iOS Simulator uses the Mac's model.
+- Capacitor 8 with Swift Package Manager.
+
+## Install
+
+```sh
+npm install @tanstack-ai-browser/afm @tanstack/ai @capacitor/core
+npx cap sync ios
+```
+
+## Use
+
+```ts
+import { chat } from "@tanstack/ai"
+import { afmText } from "@tanstack-ai-browser/afm"
+
+const adapter = afmText()
+if ((await adapter.availability()) === "available") {
+  // One threadId per conversation: its follow-ups reuse the same native session.
+  const stream = chat({ adapter, threadId, messages, tools })
+}
+```
+
+`availability()` is `"available"`, `"downloading"` while Apple Intelligence gets its model, or `"unavailable"` (an older OS, an ineligible device, or Apple Intelligence turned off). `contextSize()` is the tokens a session holds, on iOS 26.4 and later.
+
+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:
+
+```ts
+// electron/main.js
+import { app, BrowserWindow } from "electron"
+import { serveAfm } from "@tanstack-ai-browser/afm"
+
+serveAfm()
+app.whenReady().then(() => new BrowserWindow().loadFile("index.html"))
+```
+
+`serveAfm()` loads the package's Node-API addon (`electron/afm.node`, built from the same Swift as the Capacitor plugin) and adds the package's preload to the app's pages, which puts the model at `window.afm`, where `afmText()` finds it. It runs in the main process, the app's own with its window, so the framework treats it as a foreground app. It needs macOS 26 on Apple silicon; elsewhere the model reports itself unavailable.
+
+`serveAfm({ directory, allow })`:
+
+- `directory`: the folder with `afm.node` and `preload.cjs`, by default the package's `electron` folder, found from the app's `node_modules`. An app that leaves `node_modules` out of its package copies the two files in and passes their folder. Keep `afm.node` out of the asar archive (electron-builder unpacks `.node` files; otherwise list it in `asarUnpack`).
+- `allow(url)`: which pages may use the model. By default the app's own: any page but an http(s) one on a host other than localhost.
+
+Each frame's sessions are its own: a frame's calls reach only the sessions it created, their events go to that frame only (while `allow()` still allows its page), and they end when the frame navigates or closes.
+
+`electron/afm.node` is committed, so the package builds and publishes without Xcode. After changing the Swift or C it's built from, rebuild it on a Mac with Xcode (`node electron/build.mjs`) and commit it with `electron/afm.node.sha256`: a test fails while the committed addon is older than its sources.
+
+### Another host
+
+Pass any implementation of `AfmNative` (the plugin's methods and its `event` listener) as `native`, or put it at `window.afm`.
+
+The Swift side is in `ios/Sources`: `AfmCore` (the bridge, with no Capacitor in it) and `AfmPlugin` (the Capacitor plugin). Electron's addon is in `electron`: `AfmNode.swift` (C functions over the bridge) and `afm.c` (Node-API).

package/dist/adapter.d.ts

@@ -0,0 +1,107 @@
+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 { AfmGuardrails, AfmNative } from "./native.js";
+export type AfmConfig = {
+    /**
+     * The native side. By default `window.afm` where a host put it there
+     * (Electron, with `serveAfm()` in the main process), else the Capacitor
+     * 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, 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 = {
+    text: unknown;
+    image: unknown;
+    audio: unknown;
+    video: unknown;
+    document: unknown;
+};
+export declare class AfmTextAdapter extends BaseTextAdapter<AfmChatModel, AfmTextModelOptions, readonly ["text"], MetadataByModality> {
+    readonly kind: "text";
+    readonly name: "afm";
+    readonly provider: "afm";
+    readonly api: "afm";
+    readonly inputModalities: readonly ["text"];
+    private readonly native;
+    private readonly threads;
+    private readonly queues;
+    /**
+     * Responses waiting for tool results in sessions no thread keeps (prompt
+     * cache retention "none"), by thread: the next step resumes them.
+     */
+    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). */
+    contextSize(): Promise<number | undefined>;
+    /** Resolves to this adapter if the model can run here, else rejects. */
+    create(options?: {
+        signal?: AbortSignal;
+    }): Promise<this>;
+    /**
+     * Ends every session: the threads', responses waiting for tool results, and
+     * responses streaming now (structured output's, and those of sessions no
+     * thread keeps), each once.
+     */
+    destroy(): Promise<void>;
+    /** Routes the native events to their thread's response. Listens once. */
+    private listen;
+    /** Ends a session. A response still streaming from it ends with an error. */
+    private close;
+    /** Keeps a thread's session, ending the least recently used past the limit. */
+    private keep;
+    /** A new native session for a thread, holding `messages`. */
+    private open;
+    /**
+     * The step's thread, and what it sends: the results of the tool calls its
+     * response waits on, a new prompt to its session, or (for a conversation the
+     * session doesn't hold) a new session and the last message as its prompt.
+     */
+    private begin;
+    chatStream(options: TextOptions<AfmTextModelOptions>): AsyncIterable<AdapterYieldChunk>;
+    /**
+     * A JSON answer for `chat({ outputSchema })`: a session holding the
+     * conversation answers its last message, held to the schema by the
+     * framework. `chat()` validates the result.
+     */
+    structuredOutput(options: StructuredOutputOptions<AfmTextModelOptions>): Promise<StructuredOutputResult<unknown>>;
+}
+/**
+ * A TanStack AI text adapter for Apple's on-device model, through the
+ * Foundation Models framework (the Capacitor plugin on iOS, by default).
+ * The model is Apple's system model ("system"), so naming it is optional.
+ *
+ * @example
+ * ```ts
+ * const adapter = afmText()
+ * if ((await adapter.availability()) === "available") {
+ *   chat({ adapter, messages, tools })
+ * }
+ * ```
+ */
+export declare function afmText(config?: AfmConfig): AfmTextAdapter;
+export declare function afmText(model: AfmChatModel, config?: AfmConfig): AfmTextAdapter;
+export {};
+//# sourceMappingURL=adapter.d.ts.map

package/dist/adapter.d.ts.map

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