@tanstack-ai-browser/apfel 0.0.1 → 0.2.0

package/dist/guided-schema.js

@@ -0,0 +1,136 @@
+/**
+ * Tool schemas in the subset of JSON Schema that apfel's guided generation
+ * enforces, for the tool step's arguments (see adapter.ts, `stepSchema`).
+ * apfel rejects the keywords it can't enforce with HTTP 400.
+ */
+/** Keywords guided generation can enforce; apfel rejects others with 400. */
+const KEPT = ["type", "description", "enum", "const"];
+const isObject = (value) => !!value && typeof value === "object" && !Array.isArray(value);
+/** The schema a local `$ref` (`#/$defs/X`, `#/definitions/X`) points to. */
+function resolveRef(ref, root) {
+    if (!ref.startsWith("#/"))
+        return undefined;
+    let node = root;
+    for (const key of ref.slice(2).split("/")) {
+        node = isObject(node)
+            ? node[key.replace(/~1/g, "/").replace(/~0/g, "~")]
+            : undefined;
+    }
+    return isObject(node) ? node : undefined;
+}
+/**
+ * The schema in the subset guided generation enforces: types, properties,
+ * required, items, enum, const and descriptions. Local `$ref`s are inlined,
+ * `anyOf`/`oneOf`/type unions become their first non-null choice, and
+ * constraints it can't enforce (lengths, patterns, formats…) are dropped.
+ */
+export function toGuidedSchema(schema, root = isObject(schema) ? schema : {}, depth = 0) {
+    if (!isObject(schema) || depth > 12)
+        return { type: "string" };
+    if (typeof schema.$ref === "string") {
+        const target = resolveRef(schema.$ref, root);
+        return target
+            ? toGuidedSchema({ ...target, ...withoutKey(schema, "$ref") }, root, depth + 1)
+            : { type: "string" };
+    }
+    const choices = (schema.anyOf ?? schema.oneOf);
+    if (Array.isArray(choices)) {
+        const choice = choices.find((c) => isObject(c) && c.type !== "null") ?? choices[0];
+        return toGuidedSchema({
+            ...(isObject(choice) ? choice : {}),
+            ...(schema.description !== undefined && {
+                description: schema.description
+            })
+        }, root, depth + 1);
+    }
+    if (Array.isArray(schema.allOf)) {
+        const merged = schema.allOf.reduce((all, part) => (isObject(part) ? mergeSchemas(all, part) : all), withoutKey(schema, "allOf"));
+        return toGuidedSchema(merged, root, depth + 1);
+    }
+    const out = {};
+    for (const key of KEPT) {
+        if (schema[key] !== undefined)
+            out[key] = schema[key];
+    }
+    if (Array.isArray(out.type)) {
+        out.type = out.type.find((t) => t !== "null") ?? "string";
+    }
+    if (out.type === undefined) {
+        if (isObject(schema.properties))
+            out.type = "object";
+        else if (schema.items !== undefined)
+            out.type = "array";
+        else if (Array.isArray(out.enum))
+            out.type = typeof out.enum[0];
+        else if (out.const === undefined)
+            out.type = "string";
+    }
+    if (out.type === "object") {
+        const properties = isObject(schema.properties) ? schema.properties : {};
+        out.properties = Object.fromEntries(Object.entries(properties).map(([key, value]) => [
+            key,
+            toGuidedSchema(value, root, depth + 1)
+        ]));
+        out.required = Array.isArray(schema.required)
+            ? schema.required.filter((key) => typeof key === "string" && key in properties)
+            : [];
+        // An optional field can also be null, as in the Prompt API adapter
+        // (Gemini Nano wrote 0 for coordinates it didn't have). apfel reads a
+        // nullable field as optional, and takes only strings in an enum, so an
+        // enum gets no null of its own. `withoutNulls` drops any null written.
+        const required = new Set(out.required);
+        for (const [key, value] of Object.entries(out.properties)) {
+            if (!required.has(key))
+                value.type = [value.type, "null"];
+        }
+    }
+    if (out.type === "array") {
+        out.items = toGuidedSchema(schema.items ?? {}, root, depth + 1);
+    }
+    return out;
+}
+function withoutKey(schema, key) {
+    const rest = { ...schema };
+    delete rest[key];
+    return rest;
+}
+function mergeSchemas(a, b) {
+    const merged = { ...a, ...b };
+    if (isObject(a.properties) || isObject(b.properties)) {
+        merged.properties = {
+            ...(isObject(a.properties) ? a.properties : {}),
+            ...(isObject(b.properties) ? b.properties : {})
+        };
+    }
+    if (Array.isArray(a.required) || Array.isArray(b.required)) {
+        merged.required = [
+            ...new Set([
+                ...(Array.isArray(a.required) ? a.required : []),
+                ...(Array.isArray(b.required) ? b.required : [])
+            ])
+        ];
+    }
+    return merged;
+}
+/**
+ * Arguments written under `toGuidedSchema`, without the nulls it allows in
+ * optional fields: a null is a field the model left out.
+ */
+export function withoutNulls(value, schema) {
+    if (Array.isArray(value)) {
+        const items = isObject(schema.items) ? schema.items : {};
+        return value.map((item) => withoutNulls(item, items));
+    }
+    if (!isObject(value))
+        return value;
+    const properties = isObject(schema.properties) ? schema.properties : {};
+    const required = Array.isArray(schema.required) ? schema.required : [];
+    return Object.fromEntries(Object.entries(value).flatMap(([key, field]) => field === null && !required.includes(key)
+        ? []
+        : [
+            [
+                key,
+                withoutNulls(field, isObject(properties[key]) ? properties[key] : {})
+            ]
+        ]));
+}

package/dist/index.d.ts

@@ -1,6 +1,9 @@
 /**
  * TanStack AI adapter for Apple's on-device Foundation Model, served by apfel.
+ * The model catalog (model-meta.ts) is exported here too.
  */
-export { APFEL_BASE_URL, APFEL_MODEL, ApfelTextAdapter, apfel, isApfelAvailable } from "./adapter.js";
-export type { ApfelModelOptions, ApfelOptions, ApfelStats } from "./adapter.js";
+export { apfelText } from "./adapter.js";
+export type { ApfelConfig, ApfelModel, ApfelTextAdapter, ApfelTextModelOptions, Availability } from "./adapter.js";
+export { APFEL_CHAT_MODELS, APFEL_MODEL_META } from "./model-meta.js";
+export type { ApfelChatModel, ApfelModelMeta } from "./model-meta.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,OAAO,EACL,cAAc,EACd,WAAW,EACX,gBAAgB,EAChB,KAAK,EACL,gBAAgB,EACjB,MAAM,cAAc,CAAA;AACrB,YAAY,EAAE,iBAAiB,EAAE,YAAY,EAAE,UAAU,EAAE,MAAM,cAAc,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,OAAO,EAAE,SAAS,EAAE,MAAM,cAAc,CAAA;AACxC,YAAY,EAAE,WAAW,EAAE,UAAU,EAAE,gBAAgB,EAAE,qBAAqB,EAAE,YAAY,EAAE,MAAM,cAAc,CAAA;AAClH,OAAO,EAAE,iBAAiB,EAAE,gBAAgB,EAAE,MAAM,iBAAiB,CAAA;AACrE,YAAY,EAAE,cAAc,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAA"}

package/dist/index.js

@@ -1,4 +1,6 @@
 /**
  * TanStack AI adapter for Apple's on-device Foundation Model, served by apfel.
+ * The model catalog (model-meta.ts) is exported here too.
  */
-export { APFEL_BASE_URL, APFEL_MODEL, ApfelTextAdapter, apfel, isApfelAvailable } from "./adapter.js";
+export { apfelText } from "./adapter.js";
+export { APFEL_CHAT_MODELS, APFEL_MODEL_META } from "./model-meta.js";

package/dist/model-meta.d.ts

@@ -0,0 +1,23 @@
+/**
+ * The models apfel serves: Apple's on-device Foundation Model, with what it
+ * supports. It doesn't reason, so `chat()` offers no `reasoning` option for it.
+ * It reads images on macOS 27 and later; on older macOS apfel gives it only
+ * text read from the image.
+ */
+/** What a model apfel serves supports. */
+export type ApfelModelMeta = {
+    /** The model's id, as apfel lists it. */
+    name: string;
+    supports: {
+        input: ReadonlyArray<"text" | "image">;
+        output: ReadonlyArray<"text">;
+        capabilities: ReadonlyArray<"tools">;
+    };
+};
+/** The models apfel serves: Apple's on-device Foundation Model. */
+export declare const APFEL_CHAT_MODELS: readonly ["apple-foundationmodel"];
+/** A model apfel serves. */
+export type ApfelChatModel = (typeof APFEL_CHAT_MODELS)[number];
+/** Each model's metadata, by name. */
+export declare const APFEL_MODEL_META: Readonly<Record<ApfelChatModel, ApfelModelMeta>>;
+//# sourceMappingURL=model-meta.d.ts.map

package/dist/model-meta.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"model-meta.d.ts","sourceRoot":"","sources":["../src/model-meta.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,0CAA0C;AAC1C,MAAM,MAAM,cAAc,GAAG;IAC3B,yCAAyC;IACzC,IAAI,EAAE,MAAM,CAAA;IACZ,QAAQ,EAAE;QACR,KAAK,EAAE,aAAa,CAAC,MAAM,GAAG,OAAO,CAAC,CAAA;QACtC,MAAM,EAAE,aAAa,CAAC,MAAM,CAAC,CAAA;QAC7B,YAAY,EAAE,aAAa,CAAC,OAAO,CAAC,CAAA;KACrC,CAAA;CACF,CAAA;AAWD,mEAAmE;AACnE,eAAO,MAAM,iBAAiB,oCAAyC,CAAA;AAEvE,4BAA4B;AAC5B,MAAM,MAAM,cAAc,GAAG,CAAC,OAAO,iBAAiB,CAAC,CAAC,MAAM,CAAC,CAAA;AAE/D,sCAAsC;AACtC,eAAO,MAAM,gBAAgB,EAAE,QAAQ,CAAC,MAAM,CAAC,cAAc,EAAE,cAAc,CAAC,CAE7E,CAAA"}

package/dist/model-meta.js

@@ -0,0 +1,20 @@
+/**
+ * The models apfel serves: Apple's on-device Foundation Model, with what it
+ * supports. It doesn't reason, so `chat()` offers no `reasoning` option for it.
+ * It reads images on macOS 27 and later; on older macOS apfel gives it only
+ * text read from the image.
+ */
+const APPLE_FOUNDATION_MODEL = {
+    name: "apple-foundationmodel",
+    supports: {
+        input: ["text", "image"],
+        output: ["text"],
+        capabilities: ["tools"]
+    }
+};
+/** The models apfel serves: Apple's on-device Foundation Model. */
+export const APFEL_CHAT_MODELS = [APPLE_FOUNDATION_MODEL.name];
+/** Each model's metadata, by name. */
+export const APFEL_MODEL_META = {
+    [APPLE_FOUNDATION_MODEL.name]: APPLE_FOUNDATION_MODEL
+};

package/dist/tool-repair.d.ts

@@ -0,0 +1,56 @@
+/**
+ * Tool-call repair. Apple's model picks the right tool but often gets its
+ * arguments wrong: it renames fields (`limit` for `numResults`, `site` for
+ * `includeDomains`) and drops optional ones it was asked to set. So after the
+ * model calls a tool, its arguments are written again with apfel's guided
+ * generation, which holds the model to the tool's JSON Schema:
+ *
+ * 1. For each optional field, a yes/no answer: does the request give it a
+ *    value? (Asked for the arguments directly, the model leaves out optional
+ *    numbers and arrays even when the request states them.)
+ * 2. The arguments, with the fields from step 1 required and the rest left
+ *    out. Fields the model already got right (schema name, right type) are
+ *    kept as it wrote them.
+ *
+ * Works from the schema alone, for any tool, MCP tools included. Through
+ * `chat()` with search, calendar, file and weather tools, the calls came out
+ * right 27 times in 32 with this, against 18 without; the misses left are
+ * the model not calling a tool at all, which this can't fix.
+ */
+type JsonSchema = Record<string, unknown>;
+/**
+ * The schema in the subset guided generation enforces: types, properties,
+ * required, items, enum, const and descriptions. Local `$ref`s are inlined,
+ * `anyOf`/`oneOf`/type unions become their first non-null choice, and
+ * constraints it can't enforce (lengths, patterns, formats…) are dropped.
+ */
+export declare function toGuidedSchema(schema: unknown, root?: JsonSchema, depth?: number): JsonSchema;
+/**
+ * The name of the tool the model meant, when it got the name slightly wrong
+ * (case, `-` for `_`…). Undefined if no tool matches.
+ */
+export declare function matchToolName(name: string, toolNames: Iterable<string>): string | undefined;
+/** A chat completion request apfel answers with JSON matching `schema`. */
+export type GuidedRequest = {
+    /** Instructions, sent before the conversation. */
+    instructions: string;
+    schema: JsonSchema;
+    name: string;
+};
+/** Sends a guided request; resolves to the model's JSON, parsed. */
+export type GuidedComplete = (request: GuidedRequest) => Promise<unknown>;
+export type RepairableTool = {
+    name: string;
+    description: string;
+    inputSchema?: unknown;
+};
+/**
+ * The tool call's arguments, written again under the tool's schema.
+ * Undefined if the tool takes no arguments or its schema isn't an object
+ * (the model's own arguments are used then).
+ */
+export declare function repairToolArguments(tool: RepairableTool, complete: GuidedComplete, 
+/** The model's own arguments, which may use the wrong field names. */
+draft?: string): Promise<Record<string, unknown> | undefined>;
+export {};
+//# sourceMappingURL=tool-repair.d.ts.map

package/dist/tool-repair.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tool-repair.d.ts","sourceRoot":"","sources":["../src/tool-repair.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,KAAK,UAAU,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;AAoBzC;;;;;GAKG;AACH,wBAAgB,cAAc,CAC5B,MAAM,EAAE,OAAO,EACf,IAAI,GAAE,UAA2C,EACjD,KAAK,SAAI,GACR,UAAU,CAkEZ;AA4FD;;;GAGG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,EAAE,SAAS,EAAE,QAAQ,CAAC,MAAM,CAAC,sBAMtE;AAED,2EAA2E;AAC3E,MAAM,MAAM,aAAa,GAAG;IAC1B,kDAAkD;IAClD,YAAY,EAAE,MAAM,CAAA;IACpB,MAAM,EAAE,UAAU,CAAA;IAClB,IAAI,EAAE,MAAM,CAAA;CACb,CAAA;AAED,oEAAoE;AACpE,MAAM,MAAM,cAAc,GAAG,CAAC,OAAO,EAAE,aAAa,KAAK,OAAO,CAAC,OAAO,CAAC,CAAA;AAEzE,MAAM,MAAM,cAAc,GAAG;IAC3B,IAAI,EAAE,MAAM,CAAA;IACZ,WAAW,EAAE,MAAM,CAAA;IACnB,WAAW,CAAC,EAAE,OAAO,CAAA;CACtB,CAAA;AAED;;;;GAIG;AACH,wBAAsB,mBAAmB,CACvC,IAAI,EAAE,cAAc,EACpB,QAAQ,EAAE,cAAc;AACxB,sEAAsE;AACtE,KAAK,CAAC,EAAE,MAAM,GACb,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,CAAC,CAyE9C"}

package/dist/tool-repair.js

@@ -0,0 +1,252 @@
+/**
+ * Tool-call repair. Apple's model picks the right tool but often gets its
+ * arguments wrong: it renames fields (`limit` for `numResults`, `site` for
+ * `includeDomains`) and drops optional ones it was asked to set. So after the
+ * model calls a tool, its arguments are written again with apfel's guided
+ * generation, which holds the model to the tool's JSON Schema:
+ *
+ * 1. For each optional field, a yes/no answer: does the request give it a
+ *    value? (Asked for the arguments directly, the model leaves out optional
+ *    numbers and arrays even when the request states them.)
+ * 2. The arguments, with the fields from step 1 required and the rest left
+ *    out. Fields the model already got right (schema name, right type) are
+ *    kept as it wrote them.
+ *
+ * Works from the schema alone, for any tool, MCP tools included. Through
+ * `chat()` with search, calendar, file and weather tools, the calls came out
+ * right 27 times in 32 with this, against 18 without; the misses left are
+ * the model not calling a tool at all, which this can't fix.
+ */
+/** Keywords guided generation can enforce; apfel rejects others with 400. */
+const KEPT = ["type", "description", "enum", "const"];
+const isObject = (value) => !!value && typeof value === "object" && !Array.isArray(value);
+/** The schema a local `$ref` (`#/$defs/X`, `#/definitions/X`) points to. */
+function resolveRef(ref, root) {
+    if (!ref.startsWith("#/"))
+        return undefined;
+    let node = root;
+    for (const key of ref.slice(2).split("/")) {
+        node = isObject(node)
+            ? node[key.replace(/~1/g, "/").replace(/~0/g, "~")]
+            : undefined;
+    }
+    return isObject(node) ? node : undefined;
+}
+/**
+ * The schema in the subset guided generation enforces: types, properties,
+ * required, items, enum, const and descriptions. Local `$ref`s are inlined,
+ * `anyOf`/`oneOf`/type unions become their first non-null choice, and
+ * constraints it can't enforce (lengths, patterns, formats…) are dropped.
+ */
+export function toGuidedSchema(schema, root = isObject(schema) ? schema : {}, depth = 0) {
+    if (!isObject(schema) || depth > 12)
+        return { type: "string" };
+    if (typeof schema.$ref === "string") {
+        const target = resolveRef(schema.$ref, root);
+        return target
+            ? toGuidedSchema({ ...target, ...withoutKey(schema, "$ref") }, root, depth + 1)
+            : { type: "string" };
+    }
+    const choices = (schema.anyOf ?? schema.oneOf);
+    if (Array.isArray(choices)) {
+        const choice = choices.find((c) => isObject(c) && c.type !== "null") ?? choices[0];
+        return toGuidedSchema({
+            ...(isObject(choice) ? choice : {}),
+            ...(schema.description !== undefined && {
+                description: schema.description
+            })
+        }, root, depth + 1);
+    }
+    if (Array.isArray(schema.allOf)) {
+        const merged = schema.allOf.reduce((all, part) => (isObject(part) ? mergeSchemas(all, part) : all), withoutKey(schema, "allOf"));
+        return toGuidedSchema(merged, root, depth + 1);
+    }
+    const out = {};
+    for (const key of KEPT) {
+        if (schema[key] !== undefined)
+            out[key] = schema[key];
+    }
+    if (Array.isArray(out.type)) {
+        out.type = out.type.find((t) => t !== "null") ?? "string";
+    }
+    if (out.type === undefined) {
+        if (isObject(schema.properties))
+            out.type = "object";
+        else if (schema.items !== undefined)
+            out.type = "array";
+        else if (Array.isArray(out.enum))
+            out.type = typeof out.enum[0];
+        else if (out.const === undefined)
+            out.type = "string";
+    }
+    if (out.type === "object") {
+        const properties = isObject(schema.properties) ? schema.properties : {};
+        out.properties = Object.fromEntries(Object.entries(properties).map(([key, value]) => [
+            key,
+            toGuidedSchema(value, root, depth + 1)
+        ]));
+        out.required = Array.isArray(schema.required)
+            ? schema.required.filter((key) => typeof key === "string" && key in properties)
+            : [];
+    }
+    if (out.type === "array") {
+        out.items = toGuidedSchema(schema.items ?? {}, root, depth + 1);
+    }
+    return out;
+}
+function withoutKey(schema, key) {
+    const rest = { ...schema };
+    delete rest[key];
+    return rest;
+}
+function mergeSchemas(a, b) {
+    const merged = { ...a, ...b };
+    if (isObject(a.properties) || isObject(b.properties)) {
+        merged.properties = {
+            ...(isObject(a.properties) ? a.properties : {}),
+            ...(isObject(b.properties) ? b.properties : {})
+        };
+    }
+    if (Array.isArray(a.required) || Array.isArray(b.required)) {
+        merged.required = [
+            ...new Set([
+                ...(Array.isArray(a.required) ? a.required : []),
+                ...(Array.isArray(b.required) ? b.required : [])
+            ])
+        ];
+    }
+    return merged;
+}
+/** Whether `value` fits a guided schema's type and choices. */
+function fits(value, schema) {
+    if (Array.isArray(schema.enum) && !schema.enum.includes(value))
+        return false;
+    if (schema.const !== undefined)
+        return value === schema.const;
+    switch (schema.type) {
+        case "string":
+            return typeof value === "string";
+        case "integer":
+            return Number.isInteger(value);
+        case "number":
+            return typeof value === "number" && Number.isFinite(value);
+        case "boolean":
+            return typeof value === "boolean";
+        case "array":
+            return (Array.isArray(value) &&
+                value.every((item) => fits(item, (schema.items ?? {}))));
+        case "object":
+            return isObject(value);
+        default:
+            return true;
+    }
+}
+/**
+ * The fields of the model's own arguments that already have a schema's
+ * name and a value of the right type. They're kept as they are: with several
+ * calls to one tool in a reply, they're what tells the calls apart.
+ */
+function validDraftFields(draft, properties) {
+    let parsed;
+    try {
+        parsed = draft ? JSON.parse(draft) : undefined;
+    }
+    catch {
+        return {};
+    }
+    if (!isObject(parsed))
+        return {};
+    return Object.fromEntries(Object.entries(parsed).filter(([key, value]) => Object.hasOwn(properties, key) &&
+        value !== null &&
+        fits(value, properties[key])));
+}
+/** One line per field: name, type or choices, and description. */
+function describeFields(properties) {
+    return Object.entries(properties)
+        .map(([key, field]) => {
+        const kind = Array.isArray(field.enum)
+            ? field.enum.map((v) => JSON.stringify(v)).join(" | ")
+            : String(field.type ?? "any");
+        const about = typeof field.description === "string" ? `: ${field.description}` : "";
+        return `- ${key} (${kind})${about}`;
+    })
+        .join("\n");
+}
+/**
+ * The name of the tool the model meant, when it got the name slightly wrong
+ * (case, `-` for `_`…). Undefined if no tool matches.
+ */
+export function matchToolName(name, toolNames) {
+    const names = [...toolNames];
+    if (names.includes(name))
+        return name;
+    const plain = (s) => s.toLowerCase().replace(/[^a-z0-9]/g, "");
+    const matches = names.filter((n) => plain(n) === plain(name));
+    return matches.length === 1 ? matches[0] : undefined;
+}
+/**
+ * The tool call's arguments, written again under the tool's schema.
+ * Undefined if the tool takes no arguments or its schema isn't an object
+ * (the model's own arguments are used then).
+ */
+export async function repairToolArguments(tool, complete, 
+/** The model's own arguments, which may use the wrong field names. */
+draft) {
+    const schema = toGuidedSchema(tool.inputSchema);
+    const properties = (schema.properties ?? {});
+    if (schema.type !== "object" || Object.keys(properties).length === 0) {
+        return undefined;
+    }
+    const required = schema.required;
+    const optional = Object.keys(properties).filter((key) => !required.includes(key));
+    const about = `the tool ${tool.name}${tool.description ? ` (${tool.description})` : ""}`;
+    // With several calls in one reply, the draft says which one this is.
+    const attempt = draft && draft !== "{}"
+        ? `\nThe assistant's first attempt at this call, which may use wrong field names: ${draft.slice(0, 1000)}`
+        : "";
+    let chosen = [];
+    if (optional.length > 0) {
+        const answer = await complete({
+            name: "fields",
+            instructions: `You are deciding the arguments of a call to ${about}, for the user's latest request. Its fields:\n${describeFields(properties)}\nFor each optional field, answer true only if the conversation states a value for it, otherwise false.`,
+            schema: {
+                type: "object",
+                properties: Object.fromEntries(optional.map((key) => [
+                    key,
+                    {
+                        type: "boolean",
+                        description: `Does the request state a value for ${key}?`
+                    }
+                ])),
+                required: optional
+            }
+        });
+        if (isObject(answer))
+            chosen = optional.filter((key) => answer[key] === true);
+    }
+    const kept = validDraftFields(draft, properties);
+    const fields = [
+        ...new Set([
+            ...required,
+            ...chosen,
+            ...optional.filter((key) => key in kept)
+        ])
+    ];
+    const args = await complete({
+        name: tool.name,
+        instructions: `Write the arguments for a call to ${about} that does what the user asks in their latest request.${attempt}`,
+        schema: {
+            type: "object",
+            properties: Object.fromEntries(fields.map((key) => [key, properties[key]])),
+            required: fields
+        }
+    });
+    if (!isObject(args))
+        return undefined;
+    // Optional fields left empty weren't really set.
+    const written = Object.fromEntries(Object.entries(args).filter(([key, value]) => required.includes(key) ||
+        !(value === "" ||
+            value === null ||
+            (Array.isArray(value) && value.length === 0))));
+    return { ...written, ...kept };
+}

package/dist/tools.d.ts

@@ -0,0 +1,68 @@
+/**
+ * Tool calls by prompt, a copy of the Prompt API adapter's
+ * (`@tanstack-ai-browser/prompt-api`'s `tools.ts`): keep the two
+ * identical. Apple's model writes malformed
+ * native tool calls that apfel can't parse, so the system prompt lists the
+ * tools as JSON and asks for a call as JSON in a ```tool_call fence; results
+ * go back in a ```tool_result fence. The adapter reads calls out of the
+ * streamed text.
+ */
+import type { ModelMessage, Tool } from "@tanstack/ai";
+/** A tool call read from the model's text. */
+export type ParsedToolCall = {
+    name: string;
+    arguments: Record<string, unknown>;
+};
+/**
+ * The system prompt with the tools and how to call them; unchanged without
+ * tools.
+ */
+export declare function toolSystemPrompt(system: string, tools: ReadonlyArray<Tool>): string;
+/** Earlier tool calls in the conversation, as the model would have written them. */
+export declare function toolCallFence(calls: NonNullable<ModelMessage["toolCalls"]>): string;
+/** A tool's result line for a ```tool_result fence. */
+export declare function toolResultLine(id: string, name: string, content: string, error?: string): string;
+/** Tool results as the model reads them. */
+export declare const toolResultFence: (lines: ReadonlyArray<string>) => string;
+/**
+ * The first tool call in a fence's body: a JSON object (or an array of them,
+ * or one per line) with `name` (or `tool`, `tool_name`) and `arguments` (or
+ * `parameters`), the arguments possibly a JSON string, maybe wrapped in a
+ * `tool_call` or `function` key; or a Python-style call, `[name(key="v")]`;
+ * or `call:name{key:value}`.
+ */
+export declare function parseToolCall(body: string): ParsedToolCall | undefined;
+/**
+ * Reads a streamed reply: `push` each piece and get back the text that can
+ * be shown now; text inside a ```tool_call fence (or another call's
+ * delimiters: `<tool_call>`, `<|tool_call>`, `<|tool_call_start|>`, or a
+ * Python-style `[name(…)]`) is held back. The first
+ * fence that closes ends the reply (stop generating then): `fence` is its
+ * text, `call` the call in it, if it holds one (else the fence is a failed
+ * call, for `repairToolCall`), and `trailing` the text after it. Other code
+ * fences are text. `end` gives the rest, reading an unclosed fence as the
+ * reply's last.
+ */
+export declare function toolCallReader(): {
+    readonly call: ParsedToolCall | undefined;
+    readonly fence: string | undefined;
+    /** Text that came after the fence: shown after the call. */
+    readonly trailing: string;
+    push(piece: string): string;
+    end(): string;
+};
+/** Why a call doesn't fit the tools (an unknown tool, or arguments that fail its schema), if it doesn't. */
+export declare function invalidToolCall(call: ParsedToolCall, tools: ReadonlyArray<Tool>): string | undefined;
+/** Why a reply's ```tool_call fence isn't a valid call, if it isn't. */
+export declare const toolCallError: (call: ParsedToolCall | undefined, tools: ReadonlyArray<Tool>) => string | undefined;
+/** The message after a failed call, asking for it again. */
+export declare const repairPrompt: (reason: string) => string;
+/**
+ * One repair of a failed tool call, with output held to a schema (as webgllm
+ * repairs): the tool's arguments if `name` is a tool, else first the tool's
+ * name, then its arguments. `generate(schema)` asks the model, with the
+ * conversation, its failed attempt and `repairPrompt`, for JSON that fits
+ * `schema`, and returns it parsed. Undefined if the repair fails too.
+ */
+export declare function repairToolCall(tools: ReadonlyArray<Tool>, name: string | undefined, generate: (schema: Record<string, unknown>) => Promise<unknown>): Promise<ParsedToolCall | undefined>;
+//# sourceMappingURL=tools.d.ts.map

package/dist/tools.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tools.d.ts","sourceRoot":"","sources":["../src/tools.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AACH,OAAO,KAAK,EAAE,YAAY,EAAE,IAAI,EAAE,MAAM,cAAc,CAAA;AAEtD,8CAA8C;AAC9C,MAAM,MAAM,cAAc,GAAG;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;CAAE,CAAA;AAiBjF;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,aAAa,CAAC,IAAI,CAAC,GAAG,MAAM,CAiCnF;AAED,oFAAoF;AACpF,wBAAgB,aAAa,CAAC,KAAK,EAAE,WAAW,CAAC,YAAY,CAAC,WAAW,CAAC,CAAC,GAAG,MAAM,CAWnF;AAED,uDAAuD;AACvD,wBAAgB,cAAc,CAAC,EAAE,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,MAAM,GAAG,MAAM,CAUhG;AAED,4CAA4C;AAC5C,eAAO,MAAM,eAAe,UAAW,aAAa,CAAC,MAAM,CAAC,WAAqD,CAAA;AAEjH;;;;;;GAMG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,GAAG,cAAc,GAAG,SAAS,CA0CtE;AAyHD;;;;;;;;;;GAUG;AACH,wBAAgB,cAAc;aA4CtB,IAAI;aAGJ,KAAK;IAGT,4DAA4D;aACxD,QAAQ;IAGZ,IAAI,QAAQ,MAAM,GAAG,MAAM;IAI3B,GAAG,IAAI,MAAM;EAkBhB;AA2DD,4GAA4G;AAC5G,wBAAgB,eAAe,CAC7B,IAAI,EAAE,cAAc,EACpB,KAAK,EAAE,aAAa,CAAC,IAAI,CAAC,GACzB,MAAM,GAAG,SAAS,CAKpB;AAED,wEAAwE;AACxE,eAAO,MAAM,aAAa,SAClB,cAAc,GAAG,SAAS,SACzB,aAAa,CAAC,IAAI,CAAC,uBAIsB,CAAA;AAElD,4DAA4D;AAC5D,eAAO,MAAM,YAAY,WAAY,MAAM,WACgB,CAAA;AAE3D;;;;;;GAMG;AACH,wBAAsB,cAAc,CAClC,KAAK,EAAE,aAAa,CAAC,IAAI,CAAC,EAC1B,IAAI,EAAE,MAAM,GAAG,SAAS,EACxB,QAAQ,EAAE,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,OAAO,CAAC,OAAO,CAAC,GAC9D,OAAO,CAAC,cAAc,GAAG,SAAS,CAAC,CA2BrC"}