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

package/electron/build.mjs

@@ -0,0 +1,54 @@
+// Builds the Node-API addon serveAfm() loads, electron/afm.node: the Swift bridge
+// (ios/Sources/AfmCore, which the Capacitor plugin uses too), AfmNode.swift (its C
+// functions) and afm.c (Node-API), in one Mach-O bundle for Apple silicon Macs.
+// Node-API is the same in every Node and Electron, so one build loads in all of them.
+// Needs Xcode on macOS.
+//
+//   node electron/build.mjs
+import { execFileSync } from "node:child_process"
+import { readdirSync, writeFileSync } from "node:fs"
+import { createRequire } from "node:module"
+import { dirname, join } from "node:path"
+import { fileURLToPath } from "node:url"
+
+const here = dirname(fileURLToPath(import.meta.url))
+const require = createRequire(import.meta.url)
+const core = join(here, "..", "ios", "Sources", "AfmCore")
+const headers = join(dirname(require.resolve("node-api-headers/package.json")), "include")
+// The oldest macOS the addon loads on; Apple's model needs macOS 26 (checked at run time).
+const target = "arm64-apple-macos13.0"
+
+const run = (command, args) => execFileSync("xcrun", [command, ...args], { stdio: "inherit" })
+
+const object = join(here, "afm.o")
+run("clang", ["-c", "-O2", "-target", target, "-I", headers, join(here, "afm.c"), "-o", object])
+run("swiftc", [
+  "-O",
+  "-emit-library",
+  "-module-name",
+  "AfmNode",
+  "-target",
+  target,
+  ...readdirSync(core)
+    .filter((file) => file.endsWith(".swift"))
+    .map((file) => join(core, file)),
+  join(here, "AfmNode.swift"),
+  object,
+  "-o",
+  join(here, "afm.node"),
+  // Node-API comes from the process that loads the addon.
+  "-Xlinker",
+  "-undefined",
+  "-Xlinker",
+  "dynamic_lookup",
+  // macOS before 26 has no FoundationModels: the addon still loads there.
+  "-Xlinker",
+  "-weak_framework",
+  "-Xlinker",
+  "FoundationModels"
+])
+execFileSync("rm", ["-f", object])
+// Which sources this addon is from: committed with it, and checked by a test.
+const { hashFile, sourcesHash } = await import("./sources-hash.mjs")
+writeFileSync(hashFile, `${sourcesHash()}\n`)
+console.log(`Built ${join(here, "afm.node")}`)

package/electron/preload.cjs

@@ -0,0 +1,35 @@
+// The preload serveAfm() adds to the app's pages: Apple's on-device model as
+// window.afm (the AfmNative interface), which afmText() finds on its own. The main
+// process runs the model; this only talks to it. CommonJS needing nothing but
+// Electron, as a sandboxed preload must.
+"use strict"
+
+const { contextBridge, ipcRenderer } = require("electron")
+
+const call =
+  (method) =>
+  (options = {}) =>
+    ipcRenderer.invoke("afm:call", method, options)
+
+const afm = {
+  availability: call("availability"),
+  createSession: call("createSession"),
+  prewarm: call("prewarm"),
+  respond: call("respond"),
+  submitToolResult: call("submitToolResult"),
+  cancel: call("cancel"),
+  deleteSession: call("deleteSession"),
+  addListener(_name, listener) {
+    const forward = (_event, event) => listener(event)
+    ipcRenderer.on("afm:event", forward)
+    return Promise.resolve({
+      remove: () => {
+        ipcRenderer.removeListener("afm:event", forward)
+        return Promise.resolve()
+      }
+    })
+  }
+}
+
+if (process.contextIsolated) contextBridge.exposeInMainWorld("afm", afm)
+else globalThis.afm = afm

package/electron/sources-hash.mjs

@@ -0,0 +1,40 @@
+// The addon's sources, hashed: electron/afm.node is committed (so packages build
+// without Xcode), and electron/afm.node.sha256 records which sources it was built
+// from. build.mjs writes it; a test fails when the sources no longer match, so a
+// change to the Swift or C can't ship with a stale addon.
+import { createHash } from "node:crypto"
+import { readdirSync, readFileSync } from "node:fs"
+import { dirname, join, relative } from "node:path"
+import { fileURLToPath } from "node:url"
+
+const here = dirname(fileURLToPath(import.meta.url))
+const root = join(here, "..")
+
+/** The files afm.node is built from, in a fixed order. */
+export function sourceFiles() {
+  const core = join(root, "ios", "Sources", "AfmCore")
+  return [
+    ...readdirSync(core)
+      .filter((file) => file.endsWith(".swift"))
+      .sort()
+      .map((file) => join(core, file)),
+    join(here, "AfmNode.swift"),
+    join(here, "afm.c"),
+    join(here, "build.mjs")
+  ]
+}
+
+/** A SHA-256 of the sources: each file's path (from the package) and contents. */
+export function sourcesHash() {
+  const hash = createHash("sha256")
+  for (const file of sourceFiles()) {
+    hash.update(relative(root, file))
+    hash.update("\0")
+    hash.update(readFileSync(file))
+    hash.update("\0")
+  }
+  return hash.digest("hex")
+}
+
+/** Where the hash of the sources the committed addon was built from is kept. */
+export const hashFile = join(here, "afm.node.sha256")

package/ios/Sources/AfmCore/Bridge.swift

@@ -0,0 +1,315 @@
+import Foundation
+import FoundationModels
+
+/// Apple's on-device model for a JavaScript host: the Capacitor plugin on iOS, the
+/// Electron addon on macOS. Calls and events are JSON-shaped dictionaries, so each host
+/// only passes them through.
+///
+/// Tools are the framework's own: a session calls them in the middle of a response.
+/// Each tool here stands in for one the JavaScript side runs. When the model calls
+/// tools, the bridge sends a `toolCalls` event once every call of the model's batch
+/// has started (the session's transcript lists the batch), and each call waits for
+/// `submitToolResult`. The response then goes on where it was: the session keeps
+/// everything it has read, and nothing is sent to it again.
+///
+/// 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):
+///   `inputTokens` and `outputTokens` over every pass of the model (a tool call's
+///   too), and `cachedTokens` only for a session without tools (see `usage()`).
+/// - `{ type: "error", code, message }`.
+@available(iOS 26.0, macOS 26.0, *)
+public final class AfmBridge: @unchecked Sendable {
+    public typealias Emit = @Sendable ([String: Any]) -> Void
+
+    private let emit: Emit
+    private let lock = NSLock()
+    private var sessions: [String: BridgeSession] = [:]
+
+    public init(emit: @escaping Emit) {
+        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
+        var result: [String: Any]
+        switch model.availability {
+        case .available:
+            result = ["available": true]
+        case .unavailable(let reason):
+            let name: String
+            switch reason {
+            case .deviceNotEligible: name = "deviceNotEligible"
+            case .appleIntelligenceNotEnabled: name = "appleIntelligenceNotEnabled"
+            case .modelNotReady: name = "modelNotReady"
+            @unknown default: name = "unavailable"
+            }
+            result = ["available": false, "reason": name]
+        }
+        if #available(iOS 26.4, macOS 26.4, *) {
+            result["contextSize"] = model.contextSize
+        }
+        return result
+    }
+
+    /// 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.
+    public func createSession(_ options: [String: Any]) throws {
+        let id = try Self.string(options, "sessionId")
+        deleteSession(id)
+        let state = BridgeSession(id: id, emit: emit)
+        let tools = try (options["tools"] as? [Any] ?? []).map { item -> BridgedTool in
+            let spec = try Schema.object(item, "tool")
+            return BridgedTool(
+                name: spec["name"] as? String ?? "",
+                description: spec["description"] as? String ?? "",
+                parameters: try Schema.generationSchema(spec["parameters"]),
+                state: state
+            )
+        }
+        let transcript = try Conversation.transcript(
+            instructions: options["instructions"] as? String,
+            tools: tools.map { Transcript.ToolDefinition(tool: $0) },
+            messages: options["messages"] as? [Any] ?? []
+        )
+        state.session = LanguageModelSession(model: .default, tools: tools, transcript: transcript)
+        state.hasTools = !tools.isEmpty
+        lock.withLock { sessions[id] = state }
+    }
+
+    /// Loads the session's model ahead of its first prompt.
+    public func prewarm(_ options: [String: Any]) throws {
+        try session(options).session.prewarm()
+    }
+
+    /// Prompts a session (`sessionId`, `prompt`, `turn`, `options`: `temperature`,
+    /// `maximumResponseTokens`). The response comes as events. With a `schema` (as
+    /// tools' parameters take it), the answer is held to it, and `done` has it in JSON.
+    public func respond(_ options: [String: Any]) throws {
+        let state = try session(options)
+        let settings = options["options"] as? [String: Any] ?? [:]
+        var generation = GenerationOptions(
+            temperature: (settings["temperature"] as? NSNumber)?.doubleValue,
+            maximumResponseTokens: (settings["maximumResponseTokens"] as? NSNumber)?.intValue
+        )
+        // Whether the model may call tools ("allowed"), must ("required") or
+        // mustn't ("disallowed"): iOS/macOS 27. Left out, the framework decides.
+        if #available(iOS 27.0, macOS 27.0, *), let mode = settings["toolCallingMode"] as? String {
+            switch mode {
+            case "required": generation.toolCallingMode = .required
+            case "disallowed": generation.toolCallingMode = .disallowed
+            default: generation.toolCallingMode = .allowed
+            }
+        }
+        let schema = try options["schema"].map(Schema.generationSchema)
+        try state.respond(prompt: options["prompt"] as? String ?? "", turn: options["turn"] as? Int ?? 0, options: generation, schema: schema)
+    }
+
+    /// A tool's result (`sessionId`, `callId`, `output`): the waiting call returns it.
+    public func submitToolResult(_ options: [String: Any]) throws {
+        try session(options).resolve(callId: try Self.string(options, "callId"), output: options["output"] as? String ?? "")
+    }
+
+    /// Stops a session's response; the session stays.
+    public func cancel(_ options: [String: Any]) throws {
+        try session(options).cancel()
+    }
+
+    /// Ends a session.
+    public func deleteSession(_ id: String) {
+        lock.withLock { sessions.removeValue(forKey: id) }?.cancel()
+    }
+
+    private func session(_ options: [String: Any]) throws -> BridgeSession {
+        let id = try Self.string(options, "sessionId")
+        guard let state = lock.withLock({ sessions[id] }) else {
+            throw Schema.Unsupported(description: "No session \(id)")
+        }
+        return state
+    }
+
+    private static func string(_ options: [String: Any], _ key: String) throws -> String {
+        guard let value = options[key] as? String else { throw Schema.Unsupported(description: "Missing \(key)") }
+        return value
+    }
+}
+
+/// A session and its response in progress, with the tool calls waiting for results.
+@available(iOS 26.0, macOS 26.0, *)
+final class BridgeSession: @unchecked Sendable {
+    let id: String
+    var session: LanguageModelSession!
+    var hasTools = false
+
+    private let emit: AfmBridge.Emit
+    private let lock = NSLock()
+    private var task: Task<Void, Never>?
+    private var turn = 0
+    private var waiting: [Call] = []
+    private var answered: Set<String> = []
+
+    private struct Call {
+        let id: String
+        let name: String
+        let arguments: String
+        var reported: Bool
+        let continuation: CheckedContinuation<String, Error>
+    }
+
+    init(id: String, emit: @escaping AfmBridge.Emit) {
+        self.id = id
+        self.emit = emit
+    }
+
+    func respond(prompt: String, turn: Int, options: GenerationOptions, schema: GenerationSchema?) throws {
+        try lock.withLock {
+            guard task == nil else { throw Schema.Unsupported(description: "Session \(id) is responding") }
+            self.turn = turn
+            answered = []
+            task = Task { [self] in await run(prompt, options, schema) }
+        }
+    }
+
+    private func run(_ prompt: String, _ options: GenerationOptions, _ schema: GenerationSchema?) async {
+        let before = usage()
+        var text = ""
+        do {
+            if let schema {
+                text = try await session.respond(to: prompt, schema: schema, options: options).content.jsonString
+            } else {
+                for try await snapshot in session.streamResponse(to: prompt, options: options) {
+                    let content = snapshot.content
+                    let delta = content.hasPrefix(text) ? String(content.dropFirst(text.count)) : content
+                    text = content
+                    if !delta.isEmpty { send(["type": "delta", "text": delta]) }
+                }
+            }
+            // A stopped response's stream may just end.
+            try Task.checkCancellation()
+            var done: [String: Any] = ["type": "done", "text": text]
+            if let before, let after = usage() {
+                var usage: [String: Any] = [
+                    "inputTokens": after.input - before.input,
+                    "outputTokens": after.output - before.output
+                ]
+                if !hasTools { usage["cachedTokens"] = after.cached - before.cached }
+                done["usage"] = usage
+            }
+            send(done)
+        } catch is CancellationError {
+            send(["type": "error", "code": "cancelled", "message": "The response was stopped"])
+        } catch {
+            send(["type": "error", "code": Self.code(error), "message": String(describing: error)])
+        }
+        lock.withLock { task = nil }
+    }
+
+    /// A tool call: waits for its result, reporting the model's batch once it's whole.
+    func call(name: String, arguments: GeneratedContent) async throws -> String {
+        let json = arguments.jsonString
+        return try await withTaskCancellationHandler {
+            try await withCheckedThrowingContinuation { continuation in
+                lock.withLock {
+                    // Cancelled before this registers: the cancellation handler has
+                    // already run (under this lock), so it would never see this call.
+                    if Task.isCancelled {
+                        continuation.resume(throwing: CancellationError())
+                        return
+                    }
+                    // The model's batch of calls, from the transcript: its ids, and its size.
+                    var batch: [Transcript.ToolCall] = []
+                    if case .toolCalls(let calls) = session.transcript.last { batch = Array(calls) }
+                    let taken = Set(waiting.map(\.id)).union(answered)
+                    let match = batch.first { !taken.contains($0.id) && $0.toolName == name && $0.arguments.jsonString == json }
+                        ?? batch.first { !taken.contains($0.id) && $0.toolName == name }
+                    waiting.append(Call(id: match?.id ?? UUID().uuidString, name: name, arguments: json, reported: false, continuation: continuation))
+                    // Every call of the batch has started (or the batch can't be read).
+                    let started = Set(waiting.map(\.id)).union(answered)
+                    if match == nil || batch.allSatisfy({ started.contains($0.id) }) { reportWaiting() }
+                }
+            }
+        } onCancel: {
+            self.failWaiting(CancellationError())
+        }
+    }
+
+    /// Sends the waiting calls not sent yet. Called holding the lock.
+    private func reportWaiting() {
+        let calls = waiting.indices.filter { !waiting[$0].reported }
+        guard !calls.isEmpty else { return }
+        for index in calls { waiting[index].reported = true }
+        send(["type": "toolCalls", "calls": calls.map { ["id": waiting[$0].id, "name": waiting[$0].name, "arguments": waiting[$0].arguments] }])
+    }
+
+    func resolve(callId: String, output: String) throws {
+        let continuation = try lock.withLock { () -> CheckedContinuation<String, Error> in
+            guard let index = waiting.firstIndex(where: { $0.id == callId }) else {
+                throw Schema.Unsupported(description: "No tool call \(callId) is waiting")
+            }
+            answered.insert(callId)
+            return waiting.remove(at: index).continuation
+        }
+        continuation.resume(returning: output)
+    }
+
+    func cancel() {
+        let task = lock.withLock { self.task }
+        task?.cancel()
+        failWaiting(CancellationError())
+    }
+
+    private func failWaiting(_ error: Error) {
+        let calls = lock.withLock { () -> [Call] in
+            defer { waiting = [] }
+            return waiting
+        }
+        for call in calls { call.continuation.resume(throwing: error) }
+    }
+
+    private func send(_ event: [String: Any]) {
+        var event = event
+        event["sessionId"] = id
+        event["turn"] = turn
+        emit(event)
+    }
+
+    /// The session's tokens so far (iOS/macOS 27), over every pass of the model:
+    /// `respond`'s usage is the difference, a tool call's pass included, which the
+    /// response's own usage leaves out.
+    ///
+    /// The cached count is right for a session without tools: 0 for a cold
+    /// prompt, the new message's tokens fewer for a follow-up, and 0 again once
+    /// the framework has dropped the cache (a few seconds idle). With tools, the
+    /// framework counts every token but one as cached, whether the cache was
+    /// used (TTFT 1.5 s) or had been dropped (5.9 s), so it isn't reported.
+    private func usage() -> (input: Int, cached: Int, output: Int)? {
+        guard #available(iOS 27.0, macOS 27.0, *) else { return nil }
+        let usage = session.usage
+        return (usage.input.totalTokenCount, usage.input.cachedTokenCount, usage.output.totalTokenCount)
+    }
+
+    /// An error's case name (`exceededContextWindowSize`, `guardrailViolation`, …).
+    static func code(_ error: Error) -> String {
+        let text = String(describing: error)
+        return String(text.prefix { $0 != "(" && $0 != ":" && $0 != " " })
+    }
+}
+
+/// A tool the JavaScript side runs, as the framework sees it.
+@available(iOS 26.0, macOS 26.0, *)
+struct BridgedTool: Tool {
+    let name: String
+    let description: String
+    let parameters: GenerationSchema
+    /// Weak: the session's `LanguageModelSession` holds its tools, so a strong
+    /// reference back would keep a deleted session alive.
+    weak let state: BridgeSession?
+
+    func call(arguments: GeneratedContent) async throws -> String {
+        guard let state else { throw CancellationError() }
+        return try await state.call(name: name, arguments: arguments)
+    }
+}

package/ios/Sources/AfmCore/Conversation.swift

@@ -0,0 +1,49 @@
+import Foundation
+import FoundationModels
+
+/// A session's starting transcript: its instructions, its tools' definitions, and the
+/// conversation before the prompt, as the adapter sends it (src/messages.ts):
+///
+/// - `{ role: "user", text }`
+/// - `{ role: "assistant", text, toolCalls: [{ id, name, arguments }] }`, `arguments` in JSON
+/// - `{ role: "tool", toolCallId, name, text }`
+@available(iOS 26.0, macOS 26.0, *)
+enum Conversation {
+    static func transcript(instructions: String?, tools: [Transcript.ToolDefinition], messages: [Any]) throws -> Transcript {
+        var entries: [Transcript.Entry] = []
+        if (instructions?.isEmpty == false) || !tools.isEmpty {
+            entries.append(.instructions(Transcript.Instructions(segments: segments(instructions ?? ""), toolDefinitions: tools)))
+        }
+        for item in messages {
+            let message = try Schema.object(item, "message")
+            let text = message["text"] as? String ?? ""
+            switch message["role"] as? String {
+            case "user":
+                entries.append(.prompt(Transcript.Prompt(segments: segments(text))))
+            case "assistant":
+                if !text.isEmpty {
+                    entries.append(.response(Transcript.Response(assetIDs: [], segments: segments(text))))
+                }
+                let calls = try (message["toolCalls"] as? [Any] ?? []).map { item -> Transcript.ToolCall in
+                    let call = try Schema.object(item, "tool call")
+                    let arguments = try GeneratedContent(json: call["arguments"] as? String ?? "{}")
+                    return Transcript.ToolCall(id: call["id"] as? String ?? UUID().uuidString, toolName: call["name"] as? String ?? "", arguments: arguments)
+                }
+                if !calls.isEmpty { entries.append(.toolCalls(Transcript.ToolCalls(calls))) }
+            case "tool":
+                entries.append(.toolOutput(Transcript.ToolOutput(
+                    id: message["toolCallId"] as? String ?? "",
+                    toolName: message["name"] as? String ?? "",
+                    segments: segments(text)
+                )))
+            default:
+                throw Schema.Unsupported(description: "Unknown message role")
+            }
+        }
+        return Transcript(entries: entries)
+    }
+
+    static func segments(_ text: String) -> [Transcript.Segment] {
+        [.text(Transcript.TextSegment(content: text))]
+    }
+}

package/ios/Sources/AfmCore/Schema.swift

@@ -0,0 +1,90 @@
+import Foundation
+import FoundationModels
+
+/// A tool's parameters, or a structured answer's shape, as the adapter sends it: JSON
+/// Schema already read into an ordered form (src/schema.ts), so a property keeps its
+/// place (the model writes properties in the order it's given them). The kinds:
+///
+/// - `object`: `name`, `description`, `properties` ([{ name, description, optional, schema }])
+/// - `array`: `items`, `minimumElements`, `maximumElements`
+/// - `string`: `choices` (an enum), `constant`
+/// - `integer`, `number`: `minimum`, `maximum`
+/// - `boolean`, `null`
+/// - `anyOf`: `name`, `description`, `choices` (schemas)
+/// - `reference`: `name`, one of the definitions
+@available(iOS 26.0, macOS 26.0, *)
+enum Schema {
+    struct Unsupported: Error, CustomStringConvertible {
+        let description: String
+    }
+
+    /// A generation schema from a root and its definitions (the `reference` targets).
+    static func generationSchema(_ value: Any?) throws -> GenerationSchema {
+        let json = try object(value, "schema")
+        let definitions = try (json["definitions"] as? [Any] ?? []).map(dynamicSchema)
+        return try GenerationSchema(root: dynamicSchema(json["root"]), dependencies: definitions)
+    }
+
+    static func dynamicSchema(_ value: Any?) throws -> DynamicGenerationSchema {
+        let json = try object(value, "schema")
+        let kind = json["kind"] as? String ?? ""
+        switch kind {
+        case "object":
+            let properties = try (json["properties"] as? [Any] ?? []).map { item -> DynamicGenerationSchema.Property in
+                let property = try object(item, "property")
+                return DynamicGenerationSchema.Property(
+                    name: property["name"] as? String ?? "",
+                    description: property["description"] as? String,
+                    schema: try dynamicSchema(property["schema"]),
+                    isOptional: property["optional"] as? Bool ?? false
+                )
+            }
+            return DynamicGenerationSchema(name: json["name"] as? String ?? "object", description: json["description"] as? String, properties: properties)
+        case "array":
+            return DynamicGenerationSchema(
+                arrayOf: try dynamicSchema(json["items"]),
+                minimumElements: json["minimumElements"] as? Int,
+                maximumElements: json["maximumElements"] as? Int
+            )
+        case "string":
+            if let constant = json["constant"] as? String {
+                return DynamicGenerationSchema(type: String.self, guides: [.constant(constant)])
+            }
+            if let choices = json["choices"] as? [String], !choices.isEmpty {
+                return DynamicGenerationSchema(type: String.self, guides: [.anyOf(choices)])
+            }
+            return DynamicGenerationSchema(type: String.self)
+        case "integer":
+            let minimum = (json["minimum"] as? NSNumber)?.intValue, maximum = (json["maximum"] as? NSNumber)?.intValue
+            var guides: [GenerationGuide<Int>] = []
+            if let minimum, let maximum { guides.append(.range(minimum...max(minimum, maximum))) }
+            else if let minimum { guides.append(.minimum(minimum)) }
+            else if let maximum { guides.append(.maximum(maximum)) }
+            return DynamicGenerationSchema(type: Int.self, guides: guides)
+        case "number":
+            let minimum = (json["minimum"] as? NSNumber)?.doubleValue, maximum = (json["maximum"] as? NSNumber)?.doubleValue
+            var guides: [GenerationGuide<Double>] = []
+            if let minimum, let maximum { guides.append(.range(minimum...max(minimum, maximum))) }
+            else if let minimum { guides.append(.minimum(minimum)) }
+            else if let maximum { guides.append(.maximum(maximum)) }
+            return DynamicGenerationSchema(type: Double.self, guides: guides)
+        case "boolean":
+            return DynamicGenerationSchema(type: Bool.self)
+        case "null":
+            if #available(iOS 26.4, macOS 26.4, *) { return .null }
+            throw Unsupported(description: "A null schema needs iOS 26.4 or macOS 26.4")
+        case "anyOf":
+            let choices = try (json["choices"] as? [Any] ?? []).map(dynamicSchema)
+            return DynamicGenerationSchema(name: json["name"] as? String ?? "choice", description: json["description"] as? String, anyOf: choices)
+        case "reference":
+            return DynamicGenerationSchema(referenceTo: json["name"] as? String ?? "")
+        default:
+            throw Unsupported(description: "Unknown schema kind \"\(kind)\"")
+        }
+    }
+
+    static func object(_ value: Any?, _ what: String) throws -> [String: Any] {
+        guard let object = value as? [String: Any] else { throw Unsupported(description: "Expected a \(what) object") }
+        return object
+    }
+}

package/ios/Sources/AfmPlugin/AfmPlugin.swift

@@ -0,0 +1,89 @@
+import Capacitor
+import Foundation
+import AfmCore
+
+/// The Capacitor plugin: AfmBridge's calls, with its events sent to
+/// JavaScript as `event`. Below iOS 26 the model is unavailable.
+@objc(AfmPlugin)
+public class AfmPlugin: CAPPlugin, CAPBridgedPlugin {
+    public let identifier = "AfmPlugin"
+    public let jsName = "Afm"
+    public let pluginMethods: [CAPPluginMethod] = [
+        CAPPluginMethod(name: "availability", returnType: CAPPluginReturnPromise),
+        CAPPluginMethod(name: "createSession", returnType: CAPPluginReturnPromise),
+        CAPPluginMethod(name: "prewarm", returnType: CAPPluginReturnPromise),
+        CAPPluginMethod(name: "respond", returnType: CAPPluginReturnPromise),
+        CAPPluginMethod(name: "submitToolResult", returnType: CAPPluginReturnPromise),
+        CAPPluginMethod(name: "cancel", returnType: CAPPluginReturnPromise),
+        CAPPluginMethod(name: "deleteSession", returnType: CAPPluginReturnPromise)
+    ]
+
+    /// The AfmBridge, made on first use.
+    private var afmObject: AnyObject?
+
+    @available(iOS 26.0, *)
+    private var afm: AfmBridge {
+        if let bridge = afmObject as? AfmBridge { return bridge }
+        let bridge = AfmBridge { [weak self] event in
+            self?.notifyListeners("event", data: event)
+        }
+        afmObject = bridge
+        return bridge
+    }
+
+    @objc func availability(_ call: CAPPluginCall) {
+        guard #available(iOS 26.0, *) else {
+            call.resolve(["available": false, "reason": "unsupportedOS"])
+            return
+        }
+        call.resolve(AfmBridge.availability())
+    }
+
+    @objc func createSession(_ call: CAPPluginCall) {
+        guard #available(iOS 26.0, *) else { return unsupported(call) }
+        perform(call) { try self.afm.createSession($0) }
+    }
+
+    @objc func prewarm(_ call: CAPPluginCall) {
+        guard #available(iOS 26.0, *) else { return unsupported(call) }
+        perform(call) { try self.afm.prewarm($0) }
+    }
+
+    @objc func respond(_ call: CAPPluginCall) {
+        guard #available(iOS 26.0, *) else { return unsupported(call) }
+        perform(call) { try self.afm.respond($0) }
+    }
+
+    @objc func submitToolResult(_ call: CAPPluginCall) {
+        guard #available(iOS 26.0, *) else { return unsupported(call) }
+        perform(call) { try self.afm.submitToolResult($0) }
+    }
+
+    @objc func cancel(_ call: CAPPluginCall) {
+        guard #available(iOS 26.0, *) else { return unsupported(call) }
+        perform(call) { try self.afm.cancel($0) }
+    }
+
+    @objc func deleteSession(_ call: CAPPluginCall) {
+        guard #available(iOS 26.0, *) else { return unsupported(call) }
+        perform(call) { self.afm.deleteSession($0["sessionId"] as? String ?? "") }
+    }
+
+    private func unsupported(_ call: CAPPluginCall) {
+        call.reject("Apple's on-device model needs iOS 26 or later", "unsupportedOS")
+    }
+
+    /// Runs a bridge call with the call's options, resolving or rejecting it.
+    private func perform(_ call: CAPPluginCall, _ body: ([String: Any]) throws -> Void) {
+        var options: [String: Any] = [:]
+        for (key, value) in call.options {
+            if let key = key as? String { options[key] = value }
+        }
+        do {
+            try body(options)
+            call.resolve()
+        } catch {
+            call.reject(String(describing: error))
+        }
+    }
+}