@jigs.design/prompt 0.3.0 → 0.3.2

package/dist/index.d.ts

@@ -1,5 +1,6 @@
 import { askOf, documentOf, withDocument } from "./document.js";
 import { editRepairText, fullDocumentText, needsRepair, repairText } from "./repair.js";
 import { PromptMode, PromptOptions, SystemPromptParts, systemPrompt, systemPromptParts } from "./system-prompt.js";
+import { TOOL_RESULTS, toolResultsSlot } from "./tool-results.js";
 import { typeText } from "./types.js";
-export { type PromptMode, type PromptOptions, type SystemPromptParts, askOf, documentOf, editRepairText, fullDocumentText, needsRepair, repairText, systemPrompt, systemPromptParts, typeText, withDocument };
+export { type PromptMode, type PromptOptions, type SystemPromptParts, TOOL_RESULTS, askOf, documentOf, editRepairText, fullDocumentText, needsRepair, repairText, systemPrompt, systemPromptParts, toolResultsSlot, typeText, withDocument };

package/dist/index.js

@@ -1,5 +1,6 @@
 import { askOf, documentOf, withDocument } from "./document.js";
 import { editRepairText, fullDocumentText, needsRepair, repairText } from "./repair.js";
 import { typeText } from "./types.js";
+import { TOOL_RESULTS, toolResultsSlot } from "./tool-results.js";
 import { systemPrompt, systemPromptParts } from "./system-prompt.js";
-export { askOf, documentOf, editRepairText, fullDocumentText, needsRepair, repairText, systemPrompt, systemPromptParts, typeText, withDocument };
+export { TOOL_RESULTS, askOf, documentOf, editRepairText, fullDocumentText, needsRepair, repairText, systemPrompt, systemPromptParts, toolResultsSlot, typeText, withDocument };

package/dist/system-prompt.d.ts

@@ -11,6 +11,12 @@ export interface PromptOptions {
   instructions?: string;
   /** Default "document". */
   mode?: PromptMode;
+  /**
+   * The host carries the `toolResults` slot (`toolResultsSlot`): add the
+   * rules on reading a tool's results instead of copying them. The slot
+   * itself is listed as any provided slot is.
+   */
+  toolResults?: boolean;
 }
 /**
  * The system prompt for writing Jigs against `host`. In document mode
@@ -22,10 +28,10 @@ export interface PromptOptions {
  * cache it as a prefix: the output rules, the language, the catalog's
  * types and components, the app's tags, the design guidance and situations.
  * What a turn may change comes last: the app's `instructions`, the
- * procedures' own types, the queries, mutations and actions, and images. A
- * procedure enum the catalog already names keeps that name; the others are
- * named among the procedures alone, so changing them never changes the
- * prefix.
+ * procedures' own types, the queries, provided data, mutations and actions,
+ * and images. A procedure enum the catalog already names keeps that name;
+ * the others are named among the procedures alone, so changing them never
+ * changes the prefix.
  */
 export declare function systemPrompt(host: Host, options?: PromptOptions): string;
 /** The system prompt in two parts: what stays the same from turn to turn, and the rest. */

package/dist/system-prompt.js

@@ -1,5 +1,6 @@
 import { enumKey, enumUses, objectUses, typeText } from "./types.js";
 import { sharedObjects, sharedTypes } from "./shared-types.js";
+import { CHAT_TOOL_RULE, HOOKS_TOOL_RULE } from "./tool-results.js";
 import { jigSignature } from "@jigs.design/compiler";
 import { dataSchema } from "@jigs.design/host";
 //#region src/system-prompt.ts
@@ -76,7 +77,8 @@ const LANGUAGE = `## Rules
 - The body sees only its props, its own \`{@body}\` lines and other components. It does not see the document's state; pass values in as props, with a setter if the component should change them.
 - In a list, give each instance a \`key\` (\`<stat key={item.id}/>\`), on the component inside \`<each>\`, not on \`<each>\`, or repeat items that have an \`id\`, so that state stays put when the list changes.`;
 const NO_PROCEDURES = `## Data and actions
-- This app registered no queries or mutations. Do not call \`useQuery\` or \`useMutation\`; keep everything in state.`;
+- This app registered no queries or mutations. Do not call \`useQuery\` or \`useMutation\`; keep everything in state.
+- Data given in the request itself: write it in \`{@body}\` as literal values and show it. No data given, and the ask is about the user's own records (their accounts, orders, balances): show the UI with placeholders and say what is missing; never invent their numbers, names or records. Content the ask asks you to make, such as a recipe, a quiz, an FAQ or example rows, is yours to write.`;
 const HOOKS = `## Data and actions
 - \`{@body const orders = useQuery("orders", { status: "open" })}\` reads a query listed below while rendering. It returns \`{ status, data, error }\`: status is "pending", "success" or "error"; \`data\` is null until "success"; \`error\` is \`{ code, message }\`. Show each status with \`<if>\`. There is no \`isLoading\` and no \`refetch\`.
 - Calls with the same name and input share one request. Pass submitted values, not live keystrokes: keep a text field in state and copy it into the query's input on Enter or a button.
@@ -86,7 +88,7 @@ const HOOKS = `## Data and actions
 - After a mutation succeeds, the queries listed under "Refreshes" reload by themselves. Write nothing to make that happen.
 - An action listed below is called the same way, with \`useMutation("name")\` and \`mutate(input)\` in a handler. The page handles it instead of the server, for example by sending a message; its handle has the same \`status\`, \`data\` and \`error\`.
 - The first argument is always the name as a string literal. Never write \`useQuery({ queryKey, queryFn })\`.
-- Only use the queries and mutations listed below. When one returns data the ask needs, read it with \`useQuery\` and show what it returns. Never write those values into the UI yourself, not even as an example.
+- Where a UI's data comes from, in this order. A query or provided slot listed below that covers the ask: read it with \`useQuery\` and show what it returns, and never write its values into the UI yourself, not even as an example. Data given in the request itself that no listed name covers: write it in \`{@body}\` as literal values and show it. Neither, and the ask is about the user's own records (their accounts, orders, balances): show the UI with placeholders and say what is missing; never invent their numbers, names or records. Content the ask asks you to make, such as a recipe, a quiz, an FAQ or example rows, is yours to write.
 - Inputs and data are TypeScript-like types. A \`//\` comment gives a field's meaning and limits; follow them when you build an input.`;
 const COMPONENTS_INTRO = `## Components
 Each prop is \`name: type = default\`, then what it does. Leave a prop out to get its default.
@@ -203,6 +205,27 @@ function actionSection(name, procedure, names) {
 		"Handled by the page, not the server. Refreshes nothing."
 	].join("\n");
 }
+const PROVIDED_INTRO = `## Provided data
+The app supplies these when it shows the UI. Read one with \`useQuery("name")\`; it takes no input and is never stale on your side.`;
+function slotSection(name, procedure, names) {
+	return [
+		`### ${name}`,
+		procedure.description,
+		`Call: useQuery("${name}")`,
+		`Data: ${procedure.dataText ?? typeText(procedure.output, "output", names)}`
+	].join("\n");
+}
+/** `text` with `line` after its line that starts with `after`. */
+function insertAfter(text, after, line) {
+	const lines = text.split("\n");
+	const index = lines.findIndex((entry) => entry.startsWith(after));
+	if (index === -1) throw new Error(`The prompt has no line starting "${after}"`);
+	return [
+		...lines.slice(0, index + 1),
+		line,
+		...lines.slice(index + 1)
+	].join("\n");
+}
 const TAGS_INTRO = `## App tags
 Tags this app wrote in Jigs. Use them like any tag, with the props shown; a bare prop is required. They are already defined: never write their <define>. Prefer one over building the same thing from components. When one of them alone answers the ask, the UI is that one tag and nothing else.`;
 function tagSection(entry) {
@@ -291,10 +314,10 @@ function typesSection(heading, intro, declarations) {
 * cache it as a prefix: the output rules, the language, the catalog's
 * types and components, the app's tags, the design guidance and situations.
 * What a turn may change comes last: the app's `instructions`, the
-* procedures' own types, the queries, mutations and actions, and images. A
-* procedure enum the catalog already names keeps that name; the others are
-* named among the procedures alone, so changing them never changes the
-* prefix.
+* procedures' own types, the queries, provided data, mutations and actions,
+* and images. A procedure enum the catalog already names keeps that name;
+* the others are named among the procedures alone, so changing them never
+* changes the prefix.
 */
 function systemPrompt(host, options) {
 	const parts = systemPromptParts(host, options);
@@ -315,10 +338,12 @@ function systemPromptParts(host, options) {
 	const objectTypes = sharedObjects(procedureObjects(host), enumNames, new Set([...catalogTypes.declarations, ...dataTypes.declarations].map((declaration) => declaration.name)));
 	const names = objectTypes.names;
 	const mode = options?.mode ?? "document";
+	const tools = options?.toolResults === true;
+	const hooks = tools ? insertAfter(HOOKS, "- Where a UI's data comes from", HOOKS_TOOL_RULE) : HOOKS;
 	const sections = [
-		OUTPUT[mode],
+		tools && mode === "chat" ? insertAfter(OUTPUT.chat, "- You never see what a query returns", CHAT_TOOL_RULE) : OUTPUT[mode],
 		LANGUAGE,
-		entries.length === 0 ? NO_PROCEDURES : HOOKS,
+		entries.length === 0 ? NO_PROCEDURES : hooks,
 		...typesSection("## Types", "Named lists of values, used by the props below and by the data the queries return.", catalogTypes.declarations),
 		[COMPONENTS_INTRO, ...componentSections(host.components.components, catalogTypes.names)].join("\n\n")
 	];
@@ -332,6 +357,8 @@ function systemPromptParts(host, options) {
 	if (instructions !== "") variable.push(`## App instructions\n${instructions}`);
 	variable.push(...typesSection("## Data types", "Named lists of values and objects, used by the queries and mutations below.", [...dataTypes.declarations, ...objectTypes.declarations]));
 	if (queries.length > 0) variable.push(["## Queries", ...queries.map(([name, procedure]) => procedureSection(name, procedure, names))].join("\n\n"));
+	const slots = entries.flatMap(([name, procedure]) => procedure.kind === "data" ? [slotSection(name, procedure, names)] : []);
+	if (slots.length > 0) variable.push([PROVIDED_INTRO, ...slots].join("\n\n"));
 	if (mutations.length > 0) variable.push(["## Mutations", ...mutations.map(([name, procedure]) => procedureSection(name, procedure, names))].join("\n\n"));
 	const actions = entries.flatMap(([name, procedure]) => procedure.kind === "action" ? [actionSection(name, procedure, names)] : []);
 	if (actions.length > 0) variable.push(["## Actions", ...actions].join("\n\n"));

package/dist/tool-results.d.ts

@@ -0,0 +1,12 @@
+import { z } from "zod";
+//#region src/tool-results.d.ts
+/** The provided slot that holds a chat's tool results, by tool name. */
+export declare const TOOL_RESULTS = "toolResults";
+/**
+ * The `toolResults` slot as a server with `toolResults: true` adds it: the
+ * page passes each block the results of the tools called before it in the
+ * conversation, keyed by tool name. Its words are the prompt's, so they
+ * live here with the rules that name it.
+ */
+export declare const toolResultsSlot: import("@jigs.design/host").DataDefinition<z.ZodRecord<z.ZodString, z.ZodJSONSchema>>;
+//#endregion

package/dist/tool-results.js

@@ -0,0 +1,22 @@
+import { data } from "@jigs.design/host";
+import { z } from "zod";
+//#region src/tool-results.ts
+/** The provided slot that holds a chat's tool results, by tool name. */
+const TOOL_RESULTS = "toolResults";
+/**
+* The `toolResults` slot as a server with `toolResults: true` adds it: the
+* page passes each block the results of the tools called before it in the
+* conversation, keyed by tool name. Its words are the prompt's, so they
+* live here with the rules that name it.
+*/
+const toolResultsSlot = data({
+	dataText: `{ [toolName: string]: the tool's latest result, as you were shown it }. A tool not yet called, or whose call failed or was refused, has no entry. Read one as \`results.data?.["searchFlights"]?.flights\`, with the tool's name as a quoted key and \`?.\` at each step.`,
+	description: "The results of the tools called in this conversation, by tool name. A page opened from a block keeps the results it had.",
+	schema: z.record(z.string(), z.json())
+});
+/** Added after the chat rule that the model never sees what a query returns. */
+const CHAT_TOOL_RULE = `- You have seen what a tool returned. You may state a figure or a conclusion from it in prose, in a sentence. A UI that shows it reads \`${TOOL_RESULTS}\`, never a copy of its values.`;
+/** Added after the rule on where a UI's data comes from. */
+const HOOKS_TOOL_RULE = `- A listed query that covers the ask comes before \`${TOOL_RESULTS}\`: its data stays live. If you call a tool more than once before a block, the block sees only the last result. To show each result, write its block right after its call, and call again after the block.`;
+//#endregion
+export { CHAT_TOOL_RULE, HOOKS_TOOL_RULE, TOOL_RESULTS, toolResultsSlot };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jigs.design/prompt",
-  "version": "0.3.0",
+  "version": "0.3.2",
   "description": "The system prompt and the repair text, rendered from a host and from diagnostics.",
   "license": "MIT",
   "repository": {
@@ -25,9 +25,9 @@
     "access": "public"
   },
   "dependencies": {
-    "@jigs.design/compiler": "0.3.0",
-    "@jigs.design/host": "0.3.0",
-    "@jigs.design/protocol": "0.3.0"
+    "@jigs.design/host": "0.3.2",
+    "@jigs.design/compiler": "0.3.2",
+    "@jigs.design/protocol": "0.3.2"
   },
   "peerDependencies": {
     "zod": "^4.0.0"