@jigs.design/ai-sdk 0.3.3 → 0.3.5

package/dist/changes.d.ts

@@ -0,0 +1,46 @@
+import { JigsErrorCode, JsonValue, MutationResult } from "@jigs.design/protocol";
+//#region src/changes.d.ts
+/**
+ * What the user changed in a jig since the model's last reply: a
+ * `data-jigs-change` part on their next message, which `jigsChat`'s
+ * `convertDataPart` writes as one sentence for the model.
+ */
+export interface JigsChange {
+  /** How many calls it stands for: `addJigsChange` keeps the latest of a run. */
+  count: number;
+  /** Why the last call failed, `DECLINED` when the user said no; null on a success. */
+  error: JigsErrorCode | null;
+  /** What the last call passed, as JSON. */
+  input: JsonValue;
+  /** The block's key, `id@version`. */
+  key: string;
+  /** The mutation. */
+  name: string;
+}
+/**
+ * `changes` with one more settled mutation from the block `key`, as
+ * `JigsView`'s `onMutation` gives it. It replaces an earlier change to the
+ * same block, mutation and input once its number fields are left out, and
+ * counts it, so a field that mutates on every change sends one line. At
+ * most the latest ten are kept.
+ */
+export declare function addJigsChange(changes: ReadonlyArray<JigsChange>, key: string, mutation: {
+  input: unknown;
+  name: string;
+  result: MutationResult;
+}): Array<JigsChange>;
+/**
+ * A change as the model reads it: one sentence for the user's message,
+ * before their text. `jigsChat`'s `convertDataPart` writes each
+ * `data-jigs-change` part with it; a chat on another stack can call it.
+ */
+export declare function jigsChangeText(change: JigsChange): string;
+/**
+ * The parts to send `changes` with, before the message's text:
+ * `sendMessage({ parts: [...jigsChangeParts(changes), { text, type: "text" }] })`.
+ */
+export declare function jigsChangeParts(changes: ReadonlyArray<JigsChange>): Array<{
+  data: JigsChange;
+  type: "data-jigs-change";
+}>;
+//#endregion

package/dist/changes.js

@@ -0,0 +1,72 @@
+//#region src/changes.ts
+function isObject(value) {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function isNumber(value) {
+	return typeof value === "number";
+}
+/**
+* What makes two calls the same change: the input with its number fields
+* left out, so a field stepped from 300 to 340 is one change and another
+* category or row is its own.
+*/
+function identity(input) {
+	if (isNumber(input)) return "";
+	if (!isObject(input)) return JSON.stringify(input);
+	return JSON.stringify(Object.keys(input).toSorted().flatMap((name) => {
+		const value = input[name];
+		return value === void 0 || isNumber(value) ? [] : [[name, value]];
+	}));
+}
+/**
+* `changes` with one more settled mutation from the block `key`, as
+* `JigsView`'s `onMutation` gives it. It replaces an earlier change to the
+* same block, mutation and input once its number fields are left out, and
+* counts it, so a field that mutates on every change sends one line. At
+* most the latest ten are kept.
+*/
+function addJigsChange(changes, key, mutation) {
+	let input = null;
+	try {
+		const text = JSON.stringify(mutation.input ?? null);
+		if (text !== void 0) input = JSON.parse(text);
+	} catch {
+		input = null;
+	}
+	const same = (change) => change.key === key && change.name === mutation.name && identity(change.input) === identity(input);
+	const change = {
+		count: (changes.find(same)?.count ?? 0) + 1,
+		error: mutation.result.status === "success" ? null : mutation.result.error.code,
+		input,
+		key,
+		name: mutation.name
+	};
+	return [...changes.filter((entry) => !same(entry)), change].slice(-10);
+}
+/** The most of a change's input the model reads, in characters of JSON. */
+const MAX_CHANGE_INPUT_CHARS = 500;
+/**
+* A change as the model reads it: one sentence for the user's message,
+* before their text. `jigsChat`'s `convertDataPart` writes each
+* `data-jigs-change` part with it; a chat on another stack can call it.
+*/
+function jigsChangeText(change) {
+	const json = JSON.stringify(change.input);
+	const input = json.length > MAX_CHANGE_INPUT_CHARS ? `${json.slice(0, MAX_CHANGE_INPUT_CHARS)}… (cut at ${MAX_CHANGE_INPUT_CHARS} characters)` : json;
+	const ran = change.count > 1 ? `ran \`${change.name}\` ${change.count} times, the last with ${input}` : `ran \`${change.name}\` with ${input}`;
+	const call = change.count > 1 ? "the last call" : "it";
+	const outcome = change.error === null ? `${call} succeeded` : change.error === "DECLINED" ? `they declined ${call} when asked to confirm` : `${call} failed with ${change.error}`;
+	return `Since your last reply, in the \`${change.key}\` UI the user ${ran}: ${outcome}.`;
+}
+/**
+* The parts to send `changes` with, before the message's text:
+* `sendMessage({ parts: [...jigsChangeParts(changes), { text, type: "text" }] })`.
+*/
+function jigsChangeParts(changes) {
+	return changes.map((data) => ({
+		data,
+		type: "data-jigs-change"
+	}));
+}
+//#endregion
+export { addJigsChange, jigsChangeParts, jigsChangeText };

package/dist/chat.d.ts

@@ -5,7 +5,8 @@ import { InferUIMessageChunk, UIMessage, UIMessageChunk } from "ai";
 export interface JigsChat {
   /**
    * For `convertToModelMessages(messages, { convertDataPart })`: writes each
-   * jigs back as the fenced block the model wrote, so it sees its UIs.
+   * jigs back as the fenced block the model wrote, so it sees its UIs, and
+   * each `data-jigs-change` as one sentence saying what the user changed.
    * Returns `undefined` for other data parts; chain your own after it.
    */
   convertDataPart: (part: {

package/dist/chat.js

@@ -1,4 +1,5 @@
-import { storedBlock } from "./schemas.js";
+import { jigsChangeText } from "./changes.js";
+import { storedBlock, storedChange } from "./schemas.js";
 import { chatBlockText } from "@jigs.design/server";
 import { z } from "zod";
 //#region src/chat.ts
@@ -40,6 +41,13 @@ async function jigsChat(jigs, input) {
 	});
 	return {
 		convertDataPart: (part) => {
+			if (part.type === "data-jigs-change") {
+				const change = storedChange.safeParse(part.data);
+				return change.success ? {
+					text: jigsChangeText(change.data),
+					type: "text"
+				} : void 0;
+			}
 			if (part.type !== "data-jigs") return;
 			const parsed = blockSource.safeParse(part.data);
 			return parsed.success ? {

package/dist/client.d.ts

@@ -1,3 +1,4 @@
+import { JigsChange, addJigsChange, jigsChangeParts, jigsChangeText } from "./changes.js";
 import { JigsBlockData, JigsDataTypes, JigsUIMessage, StoredJigsBlock, StoredJigsUIMessage, recentMessages, withoutPrograms } from "./stored.js";
 import { ToolDataOptions, ToolPart, toolData, toolValue } from "./tool-data.js";
-export { type JigsBlockData, type JigsDataTypes, type JigsUIMessage, type StoredJigsBlock, type StoredJigsUIMessage, type ToolDataOptions, type ToolPart, recentMessages, toolData, toolValue, withoutPrograms };
+export { type JigsBlockData, type JigsChange, type JigsDataTypes, type JigsUIMessage, type StoredJigsBlock, type StoredJigsUIMessage, type ToolDataOptions, type ToolPart, addJigsChange, jigsChangeParts, jigsChangeText, recentMessages, toolData, toolValue, withoutPrograms };

package/dist/client.js

@@ -1,3 +1,4 @@
+import { addJigsChange, jigsChangeParts, jigsChangeText } from "./changes.js";
 import { recentMessages, withoutPrograms } from "./stored.js";
 import { toolData, toolValue } from "./tool-data.js";
-export { recentMessages, toolData, toolValue, withoutPrograms };
+export { addJigsChange, jigsChangeParts, jigsChangeText, recentMessages, toolData, toolValue, withoutPrograms };

package/dist/index.d.ts

@@ -1,6 +1,7 @@
+import { JigsChange, addJigsChange, jigsChangeParts, jigsChangeText } from "./changes.js";
 import { JigsBlockData, JigsDataTypes, JigsUIMessage, StoredJigsBlock, StoredJigsUIMessage, recentMessages, withoutPrograms } from "./stored.js";
 import { ToolDataOptions, ToolPart, toolData, toolValue } from "./tool-data.js";
 import { JigsChat, jigsChat, reviveJigs } from "./chat.js";
 import { ModelSettings, aiSdkModel, cachedInstructions } from "./model.js";
 import { jigsDataSchemas } from "./schemas.js";
-export { type JigsBlockData, type JigsChat, type JigsDataTypes, type JigsUIMessage, type ModelSettings, type StoredJigsBlock, type StoredJigsUIMessage, type ToolDataOptions, type ToolPart, aiSdkModel, cachedInstructions, jigsChat, jigsDataSchemas, recentMessages, reviveJigs, toolData, toolValue, withoutPrograms };
+export { type JigsBlockData, type JigsChange, type JigsChat, type JigsDataTypes, type JigsUIMessage, type ModelSettings, type StoredJigsBlock, type StoredJigsUIMessage, type ToolDataOptions, type ToolPart, addJigsChange, aiSdkModel, cachedInstructions, jigsChangeParts, jigsChangeText, jigsChat, jigsDataSchemas, recentMessages, reviveJigs, toolData, toolValue, withoutPrograms };

package/dist/index.js

@@ -1,6 +1,7 @@
+import { addJigsChange, jigsChangeParts, jigsChangeText } from "./changes.js";
 import { jigsDataSchemas } from "./schemas.js";
 import { jigsChat, reviveJigs } from "./chat.js";
 import { aiSdkModel, cachedInstructions } from "./model.js";
 import { recentMessages, withoutPrograms } from "./stored.js";
 import { toolData, toolValue } from "./tool-data.js";
-export { aiSdkModel, cachedInstructions, jigsChat, jigsDataSchemas, recentMessages, reviveJigs, toolData, toolValue, withoutPrograms };
+export { addJigsChange, aiSdkModel, cachedInstructions, jigsChangeParts, jigsChangeText, jigsChat, jigsDataSchemas, recentMessages, reviveJigs, toolData, toolValue, withoutPrograms };

package/dist/model.d.ts

@@ -4,18 +4,22 @@ import { Instructions, LanguageModel, streamText } from "ai";
 /** `streamText` settings that apply to every call, such as `temperature`. */
 export type ModelSettings = Omit<Parameters<typeof streamText>[0], "abortSignal" | "instructions" | "messages" | "model" | "prompt" | "system">;
 /**
- * `system` as instructions whose first part, `prefix`, a provider may cache:
- * two system messages, the first marked as a cache breakpoint for providers
- * that need one (Anthropic). Providers that cache a repeated prefix on their
- * own (OpenAI, DeepSeek, Google) read the two as one. Without a prefix that
- * `system` starts with, `system` alone.
+ * `system` as instructions a provider may cache: two system messages, its
+ * first part `prefix` and the rest, each marked as a cache breakpoint for
+ * providers that need one (Anthropic). The first mark keeps the prefix
+ * cached when the rest changes; the second caches the rest too while it
+ * does not, as it does not for a host whose procedures and instructions
+ * are fixed, so a turn reads the whole prompt from the cache. Two of
+ * Anthropic's four breakpoints. Providers that cache a repeated prefix on
+ * their own (OpenAI, DeepSeek, Google) read the two as one. Without a
+ * prefix that `system` starts with, `system` alone.
  */
 export declare function cachedInstructions(system: string, prefix: string): Instructions;
 /**
  * A `model` for `withModel` from an AI SDK model: document-mode
  * sessions and chat repairs stream through `streamText`, and token usage
- * reaches `onTurn`. The prompt's stable start is marked for the provider's
- * cache (`cachedInstructions`).
+ * reaches `onTurn`. The prompt's stable start and its end are marked for
+ * the provider's cache (`cachedInstructions`).
  */
 export declare function aiSdkModel(model: LanguageModel, settings?: ModelSettings): ModelFunction<unknown, unknown>;
 //#endregion

package/dist/model.js

@@ -1,28 +1,32 @@
 import { streamText } from "ai";
 //#region src/model.ts
+/** A system message marked as an Anthropic cache breakpoint. */
+const cachedMessage = (content) => ({
+	content,
+	providerOptions: { anthropic: { cacheControl: { type: "ephemeral" } } },
+	role: "system"
+});
 /**
-* `system` as instructions whose first part, `prefix`, a provider may cache:
-* two system messages, the first marked as a cache breakpoint for providers
-* that need one (Anthropic). Providers that cache a repeated prefix on their
-* own (OpenAI, DeepSeek, Google) read the two as one. Without a prefix that
-* `system` starts with, `system` alone.
+* `system` as instructions a provider may cache: two system messages, its
+* first part `prefix` and the rest, each marked as a cache breakpoint for
+* providers that need one (Anthropic). The first mark keeps the prefix
+* cached when the rest changes; the second caches the rest too while it
+* does not, as it does not for a host whose procedures and instructions
+* are fixed, so a turn reads the whole prompt from the cache. Two of
+* Anthropic's four breakpoints. Providers that cache a repeated prefix on
+* their own (OpenAI, DeepSeek, Google) read the two as one. Without a
+* prefix that `system` starts with, `system` alone.
 */
 function cachedInstructions(system, prefix) {
 	if (prefix === "" || !system.startsWith(prefix)) return system;
-	return [{
-		content: prefix,
-		providerOptions: { anthropic: { cacheControl: { type: "ephemeral" } } },
-		role: "system"
-	}, {
-		content: system.slice(prefix.length),
-		role: "system"
-	}];
+	const rest = system.slice(prefix.length);
+	return rest === "" ? [cachedMessage(prefix)] : [cachedMessage(prefix), cachedMessage(rest)];
 }
 /**
 * A `model` for `withModel` from an AI SDK model: document-mode
 * sessions and chat repairs stream through `streamText`, and token usage
-* reaches `onTurn`. The prompt's stable start is marked for the provider's
-* cache (`cachedInstructions`).
+* reaches `onTurn`. The prompt's stable start and its end are marked for
+* the provider's cache (`cachedInstructions`).
 */
 function aiSdkModel(model, settings = {}) {
 	return async function* (request) {

package/dist/schemas.d.ts

@@ -66,5 +66,24 @@ export declare const jigsDataSchemas: {
     toolKeys: z.ZodExactOptional<z.ZodUnion<readonly [z.ZodArray<z.ZodString>, z.ZodLiteral<"all">]>>;
     version: z.ZodNumber;
   }, z.core.$strip>;
+  "jigs-change": z.ZodObject<{
+    count: z.ZodNumber;
+    error: z.ZodNullable<z.ZodEnum<{
+      BAD_INPUT: "BAD_INPUT";
+      CONFLICT: "CONFLICT";
+      DECLINED: "DECLINED";
+      FORBIDDEN: "FORBIDDEN";
+      INTERNAL: "INTERNAL";
+      NETWORK: "NETWORK";
+      NOT_FOUND: "NOT_FOUND";
+      RATE_LIMITED: "RATE_LIMITED";
+      UNAUTHORIZED: "UNAUTHORIZED";
+      UNAVAILABLE: "UNAVAILABLE";
+      UNKNOWN_PROCEDURE: "UNKNOWN_PROCEDURE";
+    }>>;
+    input: z.ZodJSONSchema;
+    key: z.ZodString;
+    name: z.ZodString;
+  }, z.core.$strip>;
 };
 //#endregion

package/dist/schemas.js

@@ -44,12 +44,23 @@ const storedBlock = z.object({
 	toolKeys: z.union([z.array(z.string()), z.literal("all")]).exactOptional(),
 	version: z.number()
 });
+/** A `data-jigs-change` part: what the user changed in a jig. */
+const storedChange = z.object({
+	count: z.number().int().min(1),
+	error: z.enum(jigsErrorCodes).nullable(),
+	input: z.json(),
+	key: z.string(),
+	name: z.string()
+});
 /**
 * Schemas for `validateUIMessages<StoredJigsUIMessage>({ messages,
 * dataSchemas })`, to check a conversation the browser sent or one read
 * from storage. A jig's program is dropped, never checked: the server
 * reads only `name` and `source`, and a source is only ever compiled.
 */
-const jigsDataSchemas = { jigs: storedBlock };
+const jigsDataSchemas = {
+	jigs: storedBlock,
+	"jigs-change": storedChange
+};
 //#endregion
-export { jigsDataSchemas, storedBlock };
+export { jigsDataSchemas, storedBlock, storedChange };

package/dist/stored.d.ts

@@ -1,3 +1,4 @@
+import { JigsChange } from "./changes.js";
 import { ChatBlock } from "@jigs.design/protocol";
 import { UIMessage } from "ai";
 //#region src/stored.d.ts
@@ -10,11 +11,13 @@ export type JigsBlockData = ChatBlock;
  */
 export type StoredJigsBlock = Omit<JigsBlockData, "program">;
 /**
- * The data parts chat mode adds to a message. A type, not an interface: the
- * AI SDK's data types need an implicit index signature.
+ * The data parts chat mode adds to a message: jigs on a reply, and what the
+ * user changed in them on the next user message. A type, not an interface:
+ * the AI SDK's data types need an implicit index signature.
  */
 export type JigsDataTypes = {
   jigs: JigsBlockData;
+  "jigs-change": JigsChange;
 };
 /** A `useChat` message whose replies may hold jigs. */
 export type JigsUIMessage<TMetadata = unknown> = UIMessage<TMetadata, JigsDataTypes>;
@@ -25,6 +28,7 @@ export type JigsUIMessage<TMetadata = unknown> = UIMessage<TMetadata, JigsDataTy
  */
 export type StoredJigsUIMessage<TMetadata = unknown> = UIMessage<TMetadata, {
   jigs: StoredJigsBlock;
+  "jigs-change": JigsChange;
 }>;
 /** A message part, with a `data-jigs` part's data replaced by `TBlock`. */
 type WithBlock<TPart, TBlock> = TPart extends {

package/dist/tool-data.d.ts

@@ -37,7 +37,9 @@ export interface ToolDataOptions {
  * reply that wrote it; else its previous version's value; else the latest
  * value earlier in the conversation. A failed or refused call in that reply
  * removes the tool's entry, so the block shows its empty state rather than
- * an older result. A tool called twice in one step leaves the last result.
+ * an older result. Each call is also under its number among that tool's
+ * calls in the latest reply that called it, `searchFlights#2` for the
+ * second, so blocks of a reply that called a tool twice read one each.
  * While a block's results are the same, it gets the same object, so the view
  * does not compare them again.
  */

package/dist/tool-data.js

@@ -76,13 +76,20 @@ function toolValue(part) {
 	values.set(part, value ?? null);
 	return value;
 }
-/** What a finished tool part does to a snapshot: sets its tool's value, or removes it. */
-function apply(snapshot, part, value) {
-	const name = toolNameOf(part) ?? "";
-	if (value === void 0) snapshot.delete(name);
-	else snapshot.set(name, {
-		id: `${part.toolCallId}:${part.state}`,
-		value
+/**
+* What a settled call does to a snapshot: sets or removes its tool's
+* latest value and that of its numbered key, `name#n`. The first to settle
+* of a message's calls of a tool drops the numbered keys an earlier reply
+* left, so `name#n` is always the latest reply's.
+*/
+function apply(snapshot, call) {
+	if (call.first) {
+		for (const key of snapshot.keys()) if (key.startsWith(`${call.name}#`)) snapshot.delete(key);
+	}
+	for (const key of [call.name, `${call.name}#${call.ordinal}`]) if (call.value === void 0) snapshot.delete(key);
+	else snapshot.set(key, {
+		id: `${call.part.toolCallId}:${call.part.state}`,
+		value: call.value
 	});
 }
 /** Whether a part settles its tool's value: a final output, an error or a refusal. */
@@ -118,7 +125,9 @@ const DEFAULT_VALUE = {};
 * reply that wrote it; else its previous version's value; else the latest
 * value earlier in the conversation. A failed or refused call in that reply
 * removes the tool's entry, so the block shows its empty state rather than
-* an older result. A tool called twice in one step leaves the last result.
+* an older result. Each call is also under its number among that tool's
+* calls in the latest reply that called it, `searchFlights#2` for the
+* second, so blocks of a reply that called a tool twice read one each.
 * While a block's results are the same, it gets the same object, so the view
 * does not compare them again.
 */
@@ -134,21 +143,26 @@ function toolData(messages, options = {}) {
 		const before = new Map(conversation);
 		/** The settled tool calls of this message so far, in order. */
 		const settled = [];
+		/** The calls of each tool in this message so far, settled or not. */
+		const counts = /* @__PURE__ */ new Map();
 		for (const part of message.parts) {
 			if (isToolPart(part)) {
-				if (settles(part)) {
-					const value = valueOf === void 0 ? toolValue(part) : valueOf(toolNameOf(part) ?? "", part);
-					settled.push({
-						part,
-						value
-					});
-				}
+				const name = toolNameOf(part) ?? "";
+				const ordinal = (counts.get(name) ?? 0) + 1;
+				counts.set(name, ordinal);
+				if (settles(part)) settled.push({
+					first: !settled.some((call) => call.name === name),
+					name,
+					ordinal,
+					part,
+					value: valueOf === void 0 ? toolValue(part) : valueOf(name, part)
+				});
 				continue;
 			}
 			if (!isBlockPart(part)) continue;
 			const block = part.data;
 			const snapshot = new Map(versions.get(block.name) ?? before);
-			for (const entry of settled) apply(snapshot, entry.part, entry.value);
+			for (const call of settled) apply(snapshot, call);
 			versions.set(block.name, snapshot);
 			if (block.toolKeys === void 0) continue;
 			const projected = project(snapshot, block.toolKeys);
@@ -164,7 +178,7 @@ function toolData(messages, options = {}) {
 			});
 			result.set(block.key, data);
 		}
-		for (const entry of settled) apply(conversation, entry.part, entry.value);
+		for (const call of settled) apply(conversation, call);
 	}
 	return result;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jigs.design/ai-sdk",
-  "version": "0.3.3",
+  "version": "0.3.5",
   "description": "Jigs on the AI SDK: a model function for createJigsServer, and chat mode for useChat.",
   "license": "MIT",
   "repository": {
@@ -29,8 +29,8 @@
     "access": "public"
   },
   "dependencies": {
-    "@jigs.design/protocol": "0.3.3",
-    "@jigs.design/server": "0.3.3"
+    "@jigs.design/protocol": "0.3.5",
+    "@jigs.design/server": "0.3.5"
   },
   "peerDependencies": {
     "ai": "^7.0.0",
@@ -40,7 +40,7 @@
     "@ai-sdk/provider": "4.0.27",
     "ai": "7.0.140",
     "zod": "4.6.7",
-    "@jigs.design/catalog": "0.3.3",
-    "@jigs.design/host": "0.3.3"
+    "@jigs.design/catalog": "0.3.5",
+    "@jigs.design/host": "0.3.5"
   }
 }