@jigs.design/ai-sdk 0.3.4 → 0.3.6

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: {
@@ -15,13 +16,21 @@ export interface JigsChat {
     text: string;
     type: "text";
   } | undefined;
-  /** The chat-mode prompt for the server's host. Add your instructions to it. */
+  /**
+   * The chat-mode prompt for this request: the server's host, then the
+   * caller's saved tags (`systemTail`). Add your instructions to it.
+   */
   system: string;
   /**
-   * The start of `system` that is the same on every turn. Pass both to
-   * `cachedInstructions` so the provider caches it.
+   * The start of `system` that is the same on every turn. Pass it, with
+   * `systemTail`, to `cachedInstructions` so the provider caches it.
    */
   systemPrefix: string;
+  /**
+   * The end of `system` that differs per user: the `## Saved tags` section
+   * when the server's `resolveTags` returned any, or "".
+   */
+  systemTail: string;
   /**
    * Turns a UI message stream, e.g. `result.toUIMessageStream()`, into one
    * where jigs are `data-jigs` parts. Prose stays in text parts, in the
@@ -53,6 +62,8 @@ export declare function jigsChat<TContext, TPageName extends string>(jigs: JigsM
  * back from storage. Other parts and the metadata pass through as they are,
  * so a `StoredJigsUIMessage<Metadata>`, or the stored form of your own
  * message type, comes back with `JigsBlockData` in its `data-jigs` parts.
+ * Pass `jigs.forUser({ ctx })` rather than the server to compile in the
+ * caller's scope, so blocks that use their saved tags draw them.
  */
 export declare function reviveJigs<TMessage extends UIMessage>(jigs: Pick<JigsServer<unknown>, "compile">, messages: ReadonlyArray<TMessage>): Promise<Array<WithJigsBlocks<TMessage, JigsBlockData>>>;
 //#endregion

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 ? {
@@ -49,6 +57,7 @@ async function jigsChat(jigs, input) {
 		},
 		system: turn.system,
 		systemPrefix: turn.systemPrefix,
+		systemTail: turn.systemTail,
 		toUIMessageStream: (stream) => transform(turn, stream, stop),
 		turn
 	};
@@ -198,6 +207,8 @@ function transform(turn, stream, stop) {
 * back from storage. Other parts and the metadata pass through as they are,
 * so a `StoredJigsUIMessage<Metadata>`, or the stored form of your own
 * message type, comes back with `JigsBlockData` in its `data-jigs` parts.
+* Pass `jigs.forUser({ ctx })` rather than the server to compile in the
+* caller's scope, so blocks that use their saved tags draw them.
 */
 async function reviveJigs(jigs, messages) {
 	return await Promise.all(messages.map(async (message) => ({

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,22 +4,25 @@ 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 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.
+ * `system` as instructions a provider may cache: its first part `prefix`,
+ * the rest, and with a `tail` the end that differs per user, each a system
+ * message 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; the third,
+ * one user's saved tags (`systemTail`), keeps the host's part before it the
+ * same for every user. Two of Anthropic's four breakpoints, or three with a
+ * tail. Providers that cache a repeated prefix on their own (OpenAI,
+ * DeepSeek, Google) read them as one. Without a prefix that `system` starts
+ * with, `system` alone; a tail it does not end with is part of the rest.
  */
-export declare function cachedInstructions(system: string, prefix: string): Instructions;
+export declare function cachedInstructions(system: string, prefix: string, tail?: 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 and its end are marked for
- * the provider's cache (`cachedInstructions`).
+ * reaches `onTurn`. The prompt's stable start, the host's rest and the
+ * caller's saved tags are marked for the provider's cache
+ * (`cachedInstructions`).
  */
 export declare function aiSdkModel(model: LanguageModel, settings?: ModelSettings): ModelFunction<unknown, unknown>;
 //#endregion

package/dist/model.js

@@ -7,33 +7,42 @@ const cachedMessage = (content) => ({
 	role: "system"
 });
 /**
-* `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.
+* `system` as instructions a provider may cache: its first part `prefix`,
+* the rest, and with a `tail` the end that differs per user, each a system
+* message 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; the third,
+* one user's saved tags (`systemTail`), keeps the host's part before it the
+* same for every user. Two of Anthropic's four breakpoints, or three with a
+* tail. Providers that cache a repeated prefix on their own (OpenAI,
+* DeepSeek, Google) read them as one. Without a prefix that `system` starts
+* with, `system` alone; a tail it does not end with is part of the rest.
 */
-function cachedInstructions(system, prefix) {
+function cachedInstructions(system, prefix, tail = "") {
 	if (prefix === "" || !system.startsWith(prefix)) return system;
-	const rest = system.slice(prefix.length);
-	return rest === "" ? [cachedMessage(prefix)] : [cachedMessage(prefix), cachedMessage(rest)];
+	const ending = tail === "" ? "" : `\n\n${tail}`;
+	const tailed = ending !== "" && system.endsWith(ending) && system.length >= prefix.length + ending.length;
+	const rest = system.slice(prefix.length, tailed ? system.length - ending.length : system.length);
+	return [
+		cachedMessage(prefix),
+		...rest === "" ? [] : [cachedMessage(rest)],
+		...tailed ? [cachedMessage(ending)] : []
+	];
 }
 /**
 * 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 and its end are marked for
-* the provider's cache (`cachedInstructions`).
+* reaches `onTurn`. The prompt's stable start, the host's rest and the
+* caller's saved tags are marked for the provider's cache
+* (`cachedInstructions`).
 */
 function aiSdkModel(model, settings = {}) {
 	return async function* (request) {
 		const result = streamText({
 			...settings,
 			abortSignal: request.signal,
-			instructions: cachedInstructions(request.system, request.systemPrefix),
+			instructions: cachedInstructions(request.system, request.systemPrefix, request.systemTail),
 			messages: request.messages.map((message) => ({
 				content: message.content,
 				role: message.role

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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jigs.design/ai-sdk",
-  "version": "0.3.4",
+  "version": "0.3.6",
   "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.4",
-    "@jigs.design/server": "0.3.4"
+    "@jigs.design/protocol": "0.3.6",
+    "@jigs.design/server": "0.3.6"
   },
   "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.4",
-    "@jigs.design/host": "0.3.4"
+    "@jigs.design/catalog": "0.3.6",
+    "@jigs.design/host": "0.3.6"
   }
 }