@case-framework/survey-assistant 0.6.0 → 0.7.0

package/dist/references/rich-text-content.md

@@ -3,9 +3,9 @@
 Formatted survey text uses `{ "type": "richText", "version": 1, "doc": ... }`.
 Do not use markdown syntax for formatting; `md` content is displayed as plain text.
 
-Use typed `update-item-translation` and `create-item.translations[].content` for formatted text. Prefer `plainText` for all unformatted text, including a simple title, label, or one-paragraph info item. Use richText only when formatting carries meaning or structure. Use `survey-json-patch` for rich text only when you need to edit raw paths that typed translation operations cannot address.
+Use typed translation operations for formatted text. Prefer `plainText` for all unformatted text, including a simple title, label, or one-paragraph info item. Use richText only when formatting carries meaning or structure. In canonical operation payloads, a complete structured value belongs in `content`. Use `survey-json-patch` for rich text only when you need to edit raw paths that typed translation operations cannot address.
 
-For `survey_change`, compact `richTextBlocks` shorthand is accepted and normalized before validation. This is useful for source-document imports:
+For `survey_change`, compact `richTextBlocks` shorthand is accepted wherever a typed translation accepts structured `content`. This includes translation entries on `create-item`, `upsert-form-field-group`, `upsert-form-field`, and `set-embedded-form`, plus the top level of `update-item-translation` and `update-survey-translation`. It is normalized to canonical `content` before validation. This is an input convenience, not evidence that every accepting surface renders formatting. For an item surface whose capability profile marks `format=rich`, prefer the shorthand when creating or replacing its complete formatted value because it avoids unnecessary deeply nested payloads. It is especially useful for source-document imports:
 
 ```json
 {
@@ -14,12 +14,32 @@ For `survey_change`, compact `richTextBlocks` shorthand is accepted and normaliz
   "richTextBlocks": [
     { "type": "heading", "level": 2, "text": "How should I complete this survey?" },
     { "type": "paragraph", "text": "Read each question carefully before answering." },
-    { "type": "bulletList", "items": ["Select the answer that applies to you.", "Enter the requested information."] },
-    { "type": "footnote", "text": "* Complete the survey using the information for the intended participant." }
+    {
+      "type": "bulletList",
+      "items": ["Select the answer that applies to you.", "Enter the requested information."]
+    },
+    {
+      "type": "footnote",
+      "text": "* Complete the survey using the information for the intended participant."
+    }
   ]
 }
 ```
 
+The compact forms support paragraphs, headings, bullet lists, info boxes (including the `note` and `footnote` aliases), separators, and the inline runs described below. Already-canonical blocks may be mixed into the same array. For an image, use its canonical block shape, for example `{ "type": "image", "source": { "type": "asset", "assetId": "..." }, "alt": "..." }`. Unknown or invalid block and inline node types are rejected by validation rather than omitted.
+
+Provide exactly one representation for a translation: `plainText`, canonical `content`, or the
+model-facing `richTextBlocks` shorthand. Never combine them. `richTextBlocks` must contain at least
+one block. Put it at the same level where the canonical `content` property would appear: inside a
+translation entry for operations with a `translations` array, or at the operation top level for
+`update-item-translation` and `update-survey-translation`. Do not nest shorthand nodes inside a
+canonical `content.doc` tree. The shorter `blocks` property is accepted as a compatibility alias at
+the same locations, but prefer `richTextBlocks` in new operations.
+
+For a simple info box, use `{ "type": "infoBox", "tone": "info", "title": "Note", "text": "Helpful detail." }`. For multiple paragraphs or inline formatting inside a box, use `children` with paragraph blocks, as in the canonical example below. A box title may be a string or inline-node array. `blocks` is a translation-level compatibility alias, not a nested node body.
+
+Within a node, provide one body representation: text (including its `content`/`label` aliases), `children`, or list `items`. Do not combine these. Preserve the requested structure when repairing a rejected call; a plain paragraph does not satisfy a request for an info box or list. Unsupported nested structures must be corrected, not dropped to make validation pass.
+
 The shorthand also supports inline runs through `children`. Use it when a paragraph or question title contains a link, bold/italic/underlined words, or a mix of styles:
 
 ```json
@@ -57,10 +77,12 @@ For an email address, use `href: "mailto:contact@example.org"`. Do not put a vis
 ```
 
 Important:
+
 - `template` inline nodes render template-variable tokens such as `{participantName}`. They are not respondent inputs and must not be used to simulate cloze blanks or inline answer fields.
 - The current editor/player path ignores generic `inlineExtension` nodes. Do not invent custom inline node types unless the registry explicitly supports them.
 
 Style values:
+
 - `weight`: `strong` or `normal`
 - `italic`: `italic` or `normal`
 - `underline`: `underline` or `none`
@@ -115,6 +137,7 @@ Style values:
 ```
 
 Supported block types:
+
 - `paragraph`
 - `heading` with `level` 1 for section headings or `level` 2 for subsection headings. Do not author levels 3 through 6; the player offsets/clamps these stored levels to semantic page headings.
 - `bulletList` with `listItem` entries
@@ -124,16 +147,32 @@ Supported block types:
 
 ## Where Rich Text Is Used
 
+For item translations, the installed item capability manifest is authoritative. Load
+`assistant-operations` with both `operationKind` and `itemType`; its item capability profile labels
+every fixed and dynamic content surface as `format=rich` or `format=plain`. Use rich text only for a
+surface marked `format=rich`. This covers custom item capabilities and avoids maintaining a second
+hardcoded surface list in guidance.
+
+For the built-in item types, these additional rendering constraints apply:
+
 - Info items: content key `content`; full block editor with paragraphs, headings, bullet lists, images, separators, and info boxes.
 - Choice item `topContent` / `bottomContent`: block rich text with paragraphs, headings, bullet lists, images, separators, and info boxes.
 - Form item `topContent` / `bottomContent`: block rich text with paragraphs, bullet lists, images, and separators only. Do not use headings or info boxes there.
 - Question `title` and `cardFooter`: compact rich text with paragraph blocks only. Inline styles may use bold, italic, underline, and color.
 - Question `subtitle`: compact rich text with paragraph blocks only. Inline styles may use bold, underline, and color. Do not rely on italic in subtitles.
-- If the user asks for unsupported formatting on a surface, explain the limitation briefly and use the nearest supported representation.
+
+Survey-level `surveyCardContent`, `navigationContent`, and `validationMessages` are not item
+capability surfaces. Use `plainText` for them. They are metadata and interface-copy surfaces rather
+than documented rich-text surfaces. Navigation rendering explicitly flattens structured content,
+and formatting must not be inferred for another surface merely because its data field accepts
+`Content`.
+
+If the user asks for unsupported formatting on a surface, explain the limitation briefly and use
+the nearest supported representation.
 
 ## Updating Existing Rich Text
 
-Inspect the item first, then use `update-item-translation` with a rich text `content` value:
+Inspect the item first, then use `update-item-translation`. When replacing the complete surface with the common structures above, prefer `richTextBlocks`:
 
 ```json
 {
@@ -141,17 +180,15 @@ Inspect the item first, then use `update-item-translation` with a rich text `con
   "itemId": "info_1",
   "locale": "en",
   "contentKey": "content",
-  "content": {
-    "type": "richText",
-    "version": 1,
-    "doc": {
-      "type": "doc",
-      "blocks": [
-        { "type": "heading", "level": 2, "children": [{ "type": "text", "text": "Instructions" }] },
-        { "type": "paragraph", "children": [{ "type": "text", "text": "Please read carefully.", "style": { "weight": "strong" } }] }
+  "richTextBlocks": [
+    { "type": "heading", "level": 2, "text": "Instructions" },
+    {
+      "type": "paragraph",
+      "children": [
+        { "type": "text", "text": "Please read carefully.", "style": { "weight": "strong" } }
       ]
     }
-  }
+  ]
 }
 ```
 
@@ -159,7 +196,7 @@ This replaces that translation key for the target locale. Preserve existing bloc
 
 ## Creating A Formatted Info Item
 
-For a new formatted info item, use one typed `create-item` operation with a rich text `content` translation:
+For a new formatted info item, use one typed `create-item` operation with a compact `richTextBlocks` translation:
 
 ```json
 {
@@ -170,22 +207,18 @@ For a new formatted info item, use one typed `create-item` operation with a rich
     {
       "locale": "en",
       "contentKey": "content",
-      "content": {
-        "type": "richText",
-        "version": 1,
-        "doc": {
-          "type": "doc",
-          "blocks": [
-            { "type": "heading", "level": 2, "children": [{ "type": "text", "text": "Before you start" }] },
-            { "type": "paragraph", "children": [{ "type": "text", "text": "This survey asks about your preferences." }] }
-          ]
-        }
-      }
+      "richTextBlocks": [
+        { "type": "heading", "level": 2, "text": "Before you start" },
+        { "type": "paragraph", "text": "This survey asks about your preferences." }
+      ]
     }
   ]
 }
 ```
 
+Use the full `content.doc` form from the Block Nodes section only when you need a
+structure that the compact forms above do not cover.
+
 The raw item can still be minimal:
 
 ```json

package/dist/references/source-material-surveys.md

@@ -40,6 +40,13 @@ Use this reference when the user asks to implement, recreate, convert, import, o
 - Preserve major chapters/sections as survey structure. If page boundaries matter, use available page-break structure and/or a heading info item so respondents see the section break.
 - Include respondent-facing "before you begin", "how to complete this survey", consent, eligibility, safety, and contact/help sections as info items when still relevant digitally. Rewrite or omit paper-only return/postage instructions unless the user wants a literal reproduction.
 
+## Layout And Grouping
+
+- Treat source layout as meaningful when it communicates that fields belong together, form a repeated row or table, or have labels and inputs that must stay associated. Preserve that relationship with an appropriate form item, field groups, field order, and responsive group layout. Do not reproduce spacing or columns that are only decorative or optimized for paper.
+- For adjacent related fields, choose responsive column counts according to their semantic grouping and the space their labels and controls need. Prefer one column in narrow containers and use two to four columns at wider breakpoints when the fields remain clear and usable.
+- Form field-group layouts support one to four columns. Never attempt a larger column count. When a source places more than four fields in one row, use the closest clear supported arrangement; for example, six similarly sized fields can use three columns and flow into two rows. Do not ask a follow-up question only because the exact printed column count is unsupported.
+- Follow an explicit user layout request when the supported responsive layout can represent it. When it cannot, apply the closest clear supported arrangement and briefly disclose the adaptation after completing the work.
+
 ## Conditions And Follow-Ups
 
 - Implement implied conditions, branching, conditional follow-up questions, conditional option visibility, and skip logic when the source text clearly implies them. Do not skip conditions just because they require extra work.
@@ -52,7 +59,7 @@ Use this reference when the user asks to implement, recreate, convert, import, o
 - Split source text into the right visible content keys: concise question in `title`; instructions like "multiple answers possible" or recall-period guidance in `subtitle` or `topContent`; explanations after the control in `bottomContent`; non-question prose in info item `content`.
 - Use plainText for ordinary unformatted prose. Use richText, not plainText, only when info item content has headings, subheadings, boxed sections, bullet/list structure, examples, emphasized phrases, separators, footnotes, URLs, email links, or mixed inline formatting. Preserve the hierarchy with heading blocks, paragraph blocks, bullet lists, info boxes, or separators as supported.
 - Preserve meaningful inline source formatting, not only block layout. A URL or email address that is intended as a destination must be a richText `link` node with a canonical `href`; do not rely on automatic link detection. If source text emphasizes or highlights individual words in a question title, subtitle, option, or info text, author that content key as richText with styled inline runs instead of flattening it to plainText. Use emphasis only where it carries source meaning or scanning value.
-- For source-import info items, you may use the compact `richTextBlocks` shorthand in a translation; `survey_change` normalizes it to strict richText. A paragraph or heading can use `children` for mixed inline text, links, and styles. Example blocks: `{ "type": "heading", "level": 2, "text": "Before you begin" }`, `{ "type": "paragraph", "children": [{ "type": "text", "text": "More information: " }, { "type": "link", "href": "https://example.org/help", "text": "example.org/help" }] }`, `{ "type": "paragraph", "children": [{ "type": "text", "text": "Important", "bold": true }, { "type": "text", "text": " wording" }] }`, `{ "type": "bulletList", "items": ["...", "..."] }`, `{ "type": "footnote", "text": "* ..." }`, `{ "type": "separator" }`.
+- For source-import surfaces documented as rendering rich text, prefer the compact `richTextBlocks` shorthand; `survey_change` normalizes it to strict richText. Do not infer formatting support merely because a typed field accepts structured content. Load `rich-text-content` for supported surfaces, compact and canonical nodes, and examples. Invalid or unknown nodes are rejected rather than silently omitted.
 - Preserve footnote markers and footnote text when they change interpretation, eligibility, instructions, privacy, or coding. If a question/option has `*`, keep the marker in the visible title/option text and place the note in `subtitle`, `topContent`, `bottomContent`, or a following info item close to the referenced question. Do not silently drop source footnotes.
 - Do not put respondent-visible option labels, form field labels, dropdown option labels, validation messages, or embedded-form labels only in config. They need translation entries.
 
@@ -64,7 +71,7 @@ Use this reference when the user asks to implement, recreate, convert, import, o
   several types. Load rich-text-content before formatted info items and expressions before complex
   branching.
 - Use survey_inspect for the root group and long-survey insertion points. Use full outline paging or children lookup; do not guess append indexes from truncated context.
-- Before calling survey_change for a source-derived chunk, do a quick fidelity pass against the source: every question title, option label, option parenthetical, blank/input, section heading, footnote marker, and footnote text in that chunk should either be represented digitally or intentionally omitted as print-only/admin material.
+- Before calling survey_change for a source-derived chunk, do a quick fidelity pass against the source: every question title, option label, option parenthetical, blank/input, meaningful field grouping/layout, section heading, footnote marker, and footnote text in that chunk should either be represented digitally or intentionally omitted or adapted as print-only/admin material.
 - If the fidelity pass finds missing details, fix the operations before calling survey_change. Do not knowingly leave cleanup for the user when the source gives enough information to implement it now.
 - Prefer complete, coherent chunks over one enormous proposal. Each chunk should be valid, ordered, and usable on its own. If a page/section is too large for one bounded chunk, split it at a natural subsection boundary and continue with the next chunk in the same turn. State what remains only if a concrete blocker or reported execution limit prevents further work.
 - When a successful change says verification is required, inspect the exact affected targets or run the deterministic audit before claiming completion. Validation proves the operation contract, not complete fidelity to the supplied source.

package/dist/references/survey-data-model.md

@@ -17,10 +17,12 @@ A survey JSON object has this shape:
 ```
 
 Required fields:
+
 - `$schema`: keep the current schema string; never remove or edit it.
 - `surveyItems`: array of raw survey items.
 
 Optional fields:
+
 - `maxItemsPerPage`: object with numeric `large` and `small` page-size limits.
 - `metadata`: survey-level string map.
 - `templateValues`: reusable expression values; see expressions.md.
@@ -40,11 +42,13 @@ Minimal item shape:
 ```
 
 Conventions:
+
 - `id` is globally unique and is the durable reference used by groups, translations, response slots, expressions, and patches.
 - `key` is the coding key shown in fullKey paths. Sibling keys must be unique and use letters, numbers, underscores, or hyphens.
 - `itemType` must exist in the current editor registry.
 
 Identifier rules apply to every built-in and custom item type:
+
 - Keep inspected identifiers byte-for-byte exact when displaying, explaining, comparing, or
   reusing them. Do not replace separators, split camelCase, change capitalization, or substitute
   visible labels.
@@ -58,6 +62,7 @@ Identifier rules apply to every built-in and custom item type:
   slot ids just like built-in slots.
 
 Optional fields:
+
 - `metadata`: string map. `metadata.itemLabel` is the internal editor label, not respondent-visible text. `metadata.editorItemColor` stores the editor item color as a hex string such as `#0369a1`.
 - `config`: item-type-specific configuration. Many item types need config; simple structural/content items can be sparse.
 - `validations`: map of validation key to `JsonExpression`.
@@ -100,17 +105,20 @@ Visible text is stored under translations, not usually in item config:
 ```
 
 Content values may be:
+
 - `{ "type": "md", "content": "Text" }`
 - `{ "type": "plain", "content": "Plain text" }`
 - `{ "type": "richText", "version": 1, "doc": { "type": "doc", "blocks": [...] } }`
 
 Important:
+
 - `md` and `plain` content are rendered as plain text with line breaks. Markdown syntax such as `# Heading`, `**bold**`, or `- item` is not parsed into formatting.
 - For unformatted text, use typed translation operations with `plainText`.
-- For formatted content, use typed translation operations with a `content` value whose type is `richText`; see rich-text-content.md.
+- For formatted content on a surface documented as rendering rich text, use typed translation operations. The model-facing `richTextBlocks` shorthand normalizes to canonical richText `content` wherever the typed translation accepts structured `content`, but structural acceptance alone does not guarantee formatted rendering. See rich-text-content.md.
 - If the user asks for another language or the source material is clearly in another language, write respondent-visible translations under that locale code. A translation operation may introduce a missing locale; do not store Dutch, German, French, etc. text under `en` just because `en` exists.
 
 Common item content keys:
+
 - `title`: question title or group/page title.
 - `subtitle`: question subtitle.
 - `topContent`: content before the response controls.

package/dist/{request-context-BjTHNcDd.mjs → request-context-CG4SWijt.mjs}

@@ -1,5 +1,5 @@
-import { H as surveyDocumentVersionSchema, o as surveyAssistantApplyOutcomeSchema, z as surveyAssistantSnapshotPayloadSchema } from "./protocol-DJUP4gc0.mjs";
-import { tt as createSurveyAssistantEngineContext } from "./engine-CQwOAcwK.mjs";
+import { H as surveyDocumentVersionSchema, o as surveyAssistantApplyOutcomeSchema, z as surveyAssistantSnapshotPayloadSchema } from "./protocol-BhzQbx81.mjs";
+import { pt as createSurveyAssistantEngineContext } from "./engine-Bo85Oyj0.mjs";
 import { defaultSurveyAssistantCapabilitySet } from "./capabilities-default.mjs";
 import { MASTRA_RESOURCE_ID_KEY, MASTRA_THREAD_ID_KEY, RequestContext } from "@mastra/core/request-context";
 //#region src/server/request-context.ts
@@ -88,4 +88,4 @@ const requireSurveyAssistantTurnState = (requestContext) => {
 //#endregion
 export { parseSurveyAssistantPreviousSettledVersion as a, parseSurveyAssistantPreviousApplyOutcome as i, deriveSurveyAssistantDocumentTransition as n, parseSurveyAssistantSnapshot as o, getSurveyAssistantEngineContext as r, requireSurveyAssistantTurnState as s, buildSurveyAssistantRequestContext as t };
 
-//# sourceMappingURL=request-context-BjTHNcDd.mjs.map
+//# sourceMappingURL=request-context-CG4SWijt.mjs.map

package/dist/{request-context-BjTHNcDd.mjs.map → request-context-CG4SWijt.mjs.map}

@@ -1 +1 @@
-{"version":3,"file":"request-context-BjTHNcDd.mjs","names":[],"sources":["../src/server/request-context.ts"],"sourcesContent":["import {\n  MASTRA_RESOURCE_ID_KEY,\n  MASTRA_THREAD_ID_KEY,\n  RequestContext,\n} from \"@mastra/core/request-context\";\nimport type { OpenAICompatibleConfig } from \"@mastra/core/llm\";\nimport type { AgentExecutionOptions } from \"@mastra/core/agent\";\nimport {\n  surveyAssistantSnapshotPayloadSchema,\n  surveyAssistantApplyOutcomeSchema,\n  surveyDocumentVersionSchema,\n  type SurveyAssistantApplyOutcome,\n  type SurveyDocumentSnapshot,\n  type SurveyDocumentVersion,\n} from \"../protocol\";\nimport {\n  createSurveyAssistantEngineContext,\n  TurnSurveyDraft,\n  type SurveyAssistantCapabilitySet,\n  type SurveyAssistantEngineContext,\n} from \"../engine\";\nimport { defaultSurveyAssistantCapabilitySet } from \"../capabilities/default\";\nimport type {\n  SurveyAssistantAttachmentAccess,\n  SurveyAssistantModelAttachment,\n} from \"./thread-documents\";\n\nexport interface SurveyAssistantInvocationContext {\n  kind: \"chat\";\n}\n\nexport interface SurveyAssistantIdentityContext {\n  authority: \"experimental-client-request\" | \"authenticated-host\";\n  resourceId: string;\n  surveyId?: string;\n  threadId: string;\n}\n\nexport interface SurveyAssistantModelSelection {\n  id: string;\n  model: string | OpenAICompatibleConfig;\n  providerName?: string;\n  providerOptions?: AgentExecutionOptions[\"providerOptions\"];\n}\n\nexport type SurveyAssistantDocumentTransition =\n  | { status: \"no-baseline\" }\n  | {\n      status: \"session-changed\";\n      previousHistoryIndex: number;\n      currentHistoryIndex: number;\n    }\n  | {\n      status: \"unchanged\";\n      previousHistoryIndex: number;\n      currentHistoryIndex: number;\n      capabilitiesChanged: boolean;\n    }\n  | {\n      status: \"changed\";\n      previousHistoryIndex: number;\n      currentHistoryIndex: number;\n      historyDirection: \"backward\" | \"forward\" | \"same-index\";\n      recordedSources: Array<\"user\" | \"system\" | \"assistant\">;\n      capabilitiesChanged: boolean;\n    };\n\nexport interface SurveyAssistantRequestContext {\n  invocation: SurveyAssistantInvocationContext;\n  turnId: string;\n  turnDraft: TurnSurveyDraft;\n  identity: SurveyAssistantIdentityContext;\n  authenticatedResourceId?: string;\n  authorizedThreadId?: string;\n  applyPolicy?: \"auto\" | \"review\" | \"deny\";\n  mastra__resourceId?: string;\n  mastra__threadId?: string;\n  documentTransition?: SurveyAssistantDocumentTransition;\n  engineContext?: SurveyAssistantEngineContext;\n  documentSnapshot?: SurveyDocumentSnapshot;\n  modelAttachments?: SurveyAssistantModelAttachment[];\n  attachmentAccess?: SurveyAssistantAttachmentAccess;\n  modelSelection?: SurveyAssistantModelSelection;\n  previousApplyOutcome?: SurveyAssistantApplyOutcome;\n}\n\nexport const parseSurveyAssistantSnapshot = (value: unknown): SurveyDocumentSnapshot | null => {\n  if (value === undefined || value === null) {\n    return null;\n  }\n\n  return surveyAssistantSnapshotPayloadSchema.parse(value);\n};\n\nexport const parseSurveyAssistantPreviousSettledVersion = (\n  value: unknown,\n): SurveyDocumentVersion | null => {\n  if (value === undefined || value === null) {\n    return null;\n  }\n\n  return surveyDocumentVersionSchema.parse(value);\n};\n\nexport const parseSurveyAssistantPreviousApplyOutcome = (\n  value: unknown,\n): SurveyAssistantApplyOutcome | null => {\n  if (value === undefined || value === null) {\n    return null;\n  }\n\n  return surveyAssistantApplyOutcomeSchema.parse(value);\n};\n\nexport const deriveSurveyAssistantDocumentTransition = ({\n  current,\n  previous,\n}: {\n  current: SurveyDocumentSnapshot | null;\n  previous: SurveyDocumentVersion | null;\n}): SurveyAssistantDocumentTransition | undefined => {\n  if (!current) return undefined;\n  if (!previous) return { status: \"no-baseline\" };\n\n  const previousHistoryIndex = previous.historyIndex;\n  const currentHistoryIndex = current.version.historyIndex;\n  if (previous.sessionId !== current.version.sessionId) {\n    return {\n      status: \"session-changed\",\n      previousHistoryIndex,\n      currentHistoryIndex,\n    };\n  }\n\n  const capabilitiesChanged = previous.capabilityDigest !== current.version.capabilityDigest;\n  if (previous.contentHash === current.version.contentHash) {\n    return {\n      status: \"unchanged\",\n      previousHistoryIndex,\n      currentHistoryIndex,\n      capabilitiesChanged,\n    };\n  }\n\n  const historyDirection =\n    currentHistoryIndex > previousHistoryIndex\n      ? \"forward\"\n      : currentHistoryIndex < previousHistoryIndex\n        ? \"backward\"\n        : \"same-index\";\n  const recordedSources =\n    historyDirection === \"forward\"\n      ? [\n          ...new Set(\n            (current.ui.history?.recent ?? [])\n              .filter(\n                (entry) => entry.index > previousHistoryIndex && entry.index <= currentHistoryIndex,\n              )\n              .flatMap((entry) => (entry.source ? [entry.source] : [])),\n          ),\n        ]\n      : [];\n\n  return {\n    status: \"changed\",\n    previousHistoryIndex,\n    currentHistoryIndex,\n    historyDirection,\n    recordedSources,\n    capabilitiesChanged,\n  };\n};\n\nexport const buildSurveyAssistantRequestContext = ({\n  turnDraft,\n  identity,\n  snapshot,\n  previousSettledVersion = null,\n  trustedCapabilities = defaultSurveyAssistantCapabilitySet,\n  attachmentAccess,\n  modelAttachments = [],\n  modelSelection,\n  previousApplyOutcome,\n}: {\n  turnDraft: TurnSurveyDraft;\n  identity: SurveyAssistantIdentityContext;\n  snapshot: SurveyDocumentSnapshot | null;\n  previousSettledVersion?: SurveyDocumentVersion | null;\n  trustedCapabilities?: SurveyAssistantCapabilitySet;\n  attachmentAccess?: SurveyAssistantAttachmentAccess;\n  modelAttachments?: SurveyAssistantModelAttachment[];\n  modelSelection?: SurveyAssistantModelSelection;\n  previousApplyOutcome?: SurveyAssistantApplyOutcome | null;\n}): RequestContext<SurveyAssistantRequestContext> => {\n  const requestContext = new RequestContext<SurveyAssistantRequestContext>();\n\n  requestContext.set(\"invocation\", { kind: \"chat\" });\n  requestContext.set(\"turnId\", turnDraft.turnId);\n  requestContext.set(\"turnDraft\", turnDraft);\n  requestContext.set(\"identity\", identity);\n  if (identity.authority === \"authenticated-host\") {\n    requestContext.set(\"authenticatedResourceId\", identity.resourceId);\n    requestContext.set(\"authorizedThreadId\", identity.threadId);\n  }\n  requestContext.set(MASTRA_RESOURCE_ID_KEY, identity.resourceId);\n  requestContext.set(MASTRA_THREAD_ID_KEY, identity.threadId);\n  const documentTransition = deriveSurveyAssistantDocumentTransition({\n    current: snapshot,\n    previous: previousSettledVersion,\n  });\n  if (documentTransition) {\n    requestContext.set(\"documentTransition\", documentTransition);\n  }\n  if (attachmentAccess && attachmentAccess.documents.length > 0) {\n    requestContext.set(\"attachmentAccess\", attachmentAccess);\n  }\n  if (modelAttachments.length > 0) {\n    requestContext.set(\"modelAttachments\", modelAttachments);\n  }\n  if (modelSelection) {\n    requestContext.set(\"modelSelection\", modelSelection);\n  }\n  if (previousApplyOutcome) {\n    requestContext.set(\"previousApplyOutcome\", previousApplyOutcome);\n  }\n\n  if (!snapshot) {\n    return requestContext;\n  }\n\n  const engineContext = createSurveyAssistantEngineContext(snapshot, trustedCapabilities);\n  turnDraft.initialize(engineContext);\n  requestContext.set(\"documentSnapshot\", snapshot);\n  requestContext.set(\"engineContext\", engineContext);\n\n  return requestContext;\n};\n\n/**\n * Returns the materialized request-local survey state. The immutable\n * engineContext remains available as the turn baseline, while every tool uses\n * this accessor so successful same-turn mutations are immediately visible.\n */\nexport const getSurveyAssistantEngineContext = (\n  requestContext: RequestContext<SurveyAssistantRequestContext> | undefined,\n): SurveyAssistantEngineContext | undefined =>\n  requestContext?.get(\"turnDraft\")?.context ?? requestContext?.get(\"engineContext\");\n\nexport const requireSurveyAssistantTurnState = (\n  requestContext: RequestContext<SurveyAssistantRequestContext> | undefined,\n) => {\n  const turnId = requestContext?.get(\"turnId\");\n  const turnDraft = requestContext?.get(\"turnDraft\");\n  if (!turnId || !turnDraft || turnDraft.turnId !== turnId) {\n    throw new Error(\"Survey assistant turn context is unavailable or inconsistent.\");\n  }\n\n  return { turnId, turnDraft };\n};\n"],"mappings":"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"}
+{"version":3,"file":"request-context-CG4SWijt.mjs","names":[],"sources":["../src/server/request-context.ts"],"sourcesContent":["import {\n  MASTRA_RESOURCE_ID_KEY,\n  MASTRA_THREAD_ID_KEY,\n  RequestContext,\n} from \"@mastra/core/request-context\";\nimport type { OpenAICompatibleConfig } from \"@mastra/core/llm\";\nimport type { AgentExecutionOptions } from \"@mastra/core/agent\";\nimport {\n  surveyAssistantSnapshotPayloadSchema,\n  surveyAssistantApplyOutcomeSchema,\n  surveyDocumentVersionSchema,\n  type SurveyAssistantApplyOutcome,\n  type SurveyDocumentSnapshot,\n  type SurveyDocumentVersion,\n} from \"../protocol\";\nimport {\n  createSurveyAssistantEngineContext,\n  TurnSurveyDraft,\n  type SurveyAssistantCapabilitySet,\n  type SurveyAssistantEngineContext,\n} from \"../engine\";\nimport { defaultSurveyAssistantCapabilitySet } from \"../capabilities/default\";\nimport type {\n  SurveyAssistantAttachmentAccess,\n  SurveyAssistantModelAttachment,\n} from \"./thread-documents\";\n\nexport interface SurveyAssistantInvocationContext {\n  kind: \"chat\";\n}\n\nexport interface SurveyAssistantIdentityContext {\n  authority: \"experimental-client-request\" | \"authenticated-host\";\n  resourceId: string;\n  surveyId?: string;\n  threadId: string;\n}\n\nexport interface SurveyAssistantModelSelection {\n  id: string;\n  model: string | OpenAICompatibleConfig;\n  providerName?: string;\n  providerOptions?: AgentExecutionOptions[\"providerOptions\"];\n}\n\nexport type SurveyAssistantDocumentTransition =\n  | { status: \"no-baseline\" }\n  | {\n      status: \"session-changed\";\n      previousHistoryIndex: number;\n      currentHistoryIndex: number;\n    }\n  | {\n      status: \"unchanged\";\n      previousHistoryIndex: number;\n      currentHistoryIndex: number;\n      capabilitiesChanged: boolean;\n    }\n  | {\n      status: \"changed\";\n      previousHistoryIndex: number;\n      currentHistoryIndex: number;\n      historyDirection: \"backward\" | \"forward\" | \"same-index\";\n      recordedSources: Array<\"user\" | \"system\" | \"assistant\">;\n      capabilitiesChanged: boolean;\n    };\n\nexport interface SurveyAssistantRequestContext {\n  invocation: SurveyAssistantInvocationContext;\n  turnId: string;\n  turnDraft: TurnSurveyDraft;\n  identity: SurveyAssistantIdentityContext;\n  authenticatedResourceId?: string;\n  authorizedThreadId?: string;\n  applyPolicy?: \"auto\" | \"review\" | \"deny\";\n  mastra__resourceId?: string;\n  mastra__threadId?: string;\n  documentTransition?: SurveyAssistantDocumentTransition;\n  engineContext?: SurveyAssistantEngineContext;\n  documentSnapshot?: SurveyDocumentSnapshot;\n  modelAttachments?: SurveyAssistantModelAttachment[];\n  attachmentAccess?: SurveyAssistantAttachmentAccess;\n  modelSelection?: SurveyAssistantModelSelection;\n  previousApplyOutcome?: SurveyAssistantApplyOutcome;\n}\n\nexport const parseSurveyAssistantSnapshot = (value: unknown): SurveyDocumentSnapshot | null => {\n  if (value === undefined || value === null) {\n    return null;\n  }\n\n  return surveyAssistantSnapshotPayloadSchema.parse(value);\n};\n\nexport const parseSurveyAssistantPreviousSettledVersion = (\n  value: unknown,\n): SurveyDocumentVersion | null => {\n  if (value === undefined || value === null) {\n    return null;\n  }\n\n  return surveyDocumentVersionSchema.parse(value);\n};\n\nexport const parseSurveyAssistantPreviousApplyOutcome = (\n  value: unknown,\n): SurveyAssistantApplyOutcome | null => {\n  if (value === undefined || value === null) {\n    return null;\n  }\n\n  return surveyAssistantApplyOutcomeSchema.parse(value);\n};\n\nexport const deriveSurveyAssistantDocumentTransition = ({\n  current,\n  previous,\n}: {\n  current: SurveyDocumentSnapshot | null;\n  previous: SurveyDocumentVersion | null;\n}): SurveyAssistantDocumentTransition | undefined => {\n  if (!current) return undefined;\n  if (!previous) return { status: \"no-baseline\" };\n\n  const previousHistoryIndex = previous.historyIndex;\n  const currentHistoryIndex = current.version.historyIndex;\n  if (previous.sessionId !== current.version.sessionId) {\n    return {\n      status: \"session-changed\",\n      previousHistoryIndex,\n      currentHistoryIndex,\n    };\n  }\n\n  const capabilitiesChanged = previous.capabilityDigest !== current.version.capabilityDigest;\n  if (previous.contentHash === current.version.contentHash) {\n    return {\n      status: \"unchanged\",\n      previousHistoryIndex,\n      currentHistoryIndex,\n      capabilitiesChanged,\n    };\n  }\n\n  const historyDirection =\n    currentHistoryIndex > previousHistoryIndex\n      ? \"forward\"\n      : currentHistoryIndex < previousHistoryIndex\n        ? \"backward\"\n        : \"same-index\";\n  const recordedSources =\n    historyDirection === \"forward\"\n      ? [\n          ...new Set(\n            (current.ui.history?.recent ?? [])\n              .filter(\n                (entry) => entry.index > previousHistoryIndex && entry.index <= currentHistoryIndex,\n              )\n              .flatMap((entry) => (entry.source ? [entry.source] : [])),\n          ),\n        ]\n      : [];\n\n  return {\n    status: \"changed\",\n    previousHistoryIndex,\n    currentHistoryIndex,\n    historyDirection,\n    recordedSources,\n    capabilitiesChanged,\n  };\n};\n\nexport const buildSurveyAssistantRequestContext = ({\n  turnDraft,\n  identity,\n  snapshot,\n  previousSettledVersion = null,\n  trustedCapabilities = defaultSurveyAssistantCapabilitySet,\n  attachmentAccess,\n  modelAttachments = [],\n  modelSelection,\n  previousApplyOutcome,\n}: {\n  turnDraft: TurnSurveyDraft;\n  identity: SurveyAssistantIdentityContext;\n  snapshot: SurveyDocumentSnapshot | null;\n  previousSettledVersion?: SurveyDocumentVersion | null;\n  trustedCapabilities?: SurveyAssistantCapabilitySet;\n  attachmentAccess?: SurveyAssistantAttachmentAccess;\n  modelAttachments?: SurveyAssistantModelAttachment[];\n  modelSelection?: SurveyAssistantModelSelection;\n  previousApplyOutcome?: SurveyAssistantApplyOutcome | null;\n}): RequestContext<SurveyAssistantRequestContext> => {\n  const requestContext = new RequestContext<SurveyAssistantRequestContext>();\n\n  requestContext.set(\"invocation\", { kind: \"chat\" });\n  requestContext.set(\"turnId\", turnDraft.turnId);\n  requestContext.set(\"turnDraft\", turnDraft);\n  requestContext.set(\"identity\", identity);\n  if (identity.authority === \"authenticated-host\") {\n    requestContext.set(\"authenticatedResourceId\", identity.resourceId);\n    requestContext.set(\"authorizedThreadId\", identity.threadId);\n  }\n  requestContext.set(MASTRA_RESOURCE_ID_KEY, identity.resourceId);\n  requestContext.set(MASTRA_THREAD_ID_KEY, identity.threadId);\n  const documentTransition = deriveSurveyAssistantDocumentTransition({\n    current: snapshot,\n    previous: previousSettledVersion,\n  });\n  if (documentTransition) {\n    requestContext.set(\"documentTransition\", documentTransition);\n  }\n  if (attachmentAccess && attachmentAccess.documents.length > 0) {\n    requestContext.set(\"attachmentAccess\", attachmentAccess);\n  }\n  if (modelAttachments.length > 0) {\n    requestContext.set(\"modelAttachments\", modelAttachments);\n  }\n  if (modelSelection) {\n    requestContext.set(\"modelSelection\", modelSelection);\n  }\n  if (previousApplyOutcome) {\n    requestContext.set(\"previousApplyOutcome\", previousApplyOutcome);\n  }\n\n  if (!snapshot) {\n    return requestContext;\n  }\n\n  const engineContext = createSurveyAssistantEngineContext(snapshot, trustedCapabilities);\n  turnDraft.initialize(engineContext);\n  requestContext.set(\"documentSnapshot\", snapshot);\n  requestContext.set(\"engineContext\", engineContext);\n\n  return requestContext;\n};\n\n/**\n * Returns the materialized request-local survey state. The immutable\n * engineContext remains available as the turn baseline, while every tool uses\n * this accessor so successful same-turn mutations are immediately visible.\n */\nexport const getSurveyAssistantEngineContext = (\n  requestContext: RequestContext<SurveyAssistantRequestContext> | undefined,\n): SurveyAssistantEngineContext | undefined =>\n  requestContext?.get(\"turnDraft\")?.context ?? requestContext?.get(\"engineContext\");\n\nexport const requireSurveyAssistantTurnState = (\n  requestContext: RequestContext<SurveyAssistantRequestContext> | undefined,\n) => {\n  const turnId = requestContext?.get(\"turnId\");\n  const turnDraft = requestContext?.get(\"turnDraft\");\n  if (!turnId || !turnDraft || turnDraft.turnId !== turnId) {\n    throw new Error(\"Survey assistant turn context is unavailable or inconsistent.\");\n  }\n\n  return { turnId, turnDraft };\n};\n"],"mappings":";;;;;AAsFA,MAAa,gCAAgC,UAAkD;AAC7F,KAAI,UAAU,KAAA,KAAa,UAAU,KACnC,QAAO;AAGT,QAAO,qCAAqC,MAAM,MAAM;;AAG1D,MAAa,8CACX,UACiC;AACjC,KAAI,UAAU,KAAA,KAAa,UAAU,KACnC,QAAO;AAGT,QAAO,4BAA4B,MAAM,MAAM;;AAGjD,MAAa,4CACX,UACuC;AACvC,KAAI,UAAU,KAAA,KAAa,UAAU,KACnC,QAAO;AAGT,QAAO,kCAAkC,MAAM,MAAM;;AAGvD,MAAa,2CAA2C,EACtD,SACA,eAImD;AACnD,KAAI,CAAC,QAAS,QAAO,KAAA;AACrB,KAAI,CAAC,SAAU,QAAO,EAAE,QAAQ,eAAe;CAE/C,MAAM,uBAAuB,SAAS;CACtC,MAAM,sBAAsB,QAAQ,QAAQ;AAC5C,KAAI,SAAS,cAAc,QAAQ,QAAQ,UACzC,QAAO;EACL,QAAQ;EACR;EACA;EACD;CAGH,MAAM,sBAAsB,SAAS,qBAAqB,QAAQ,QAAQ;AAC1E,KAAI,SAAS,gBAAgB,QAAQ,QAAQ,YAC3C,QAAO;EACL,QAAQ;EACR;EACA;EACA;EACD;CAGH,MAAM,mBACJ,sBAAsB,uBAClB,YACA,sBAAsB,uBACpB,aACA;AAcR,QAAO;EACL,QAAQ;EACR;EACA;EACA;EACA,iBAjBA,qBAAqB,YACjB,CACE,GAAG,IAAI,KACJ,QAAQ,GAAG,SAAS,UAAU,EAAE,EAC9B,QACE,UAAU,MAAM,QAAQ,wBAAwB,MAAM,SAAS,oBACjE,CACA,SAAS,UAAW,MAAM,SAAS,CAAC,MAAM,OAAO,GAAG,EAAE,CAAE,CAC5D,CACF,GACD,EAAE;EAQN;EACD;;AAGH,MAAa,sCAAsC,EACjD,WACA,UACA,UACA,yBAAyB,MACzB,sBAAsB,qCACtB,kBACA,mBAAmB,EAAE,EACrB,gBACA,2BAWmD;CACnD,MAAM,iBAAiB,IAAI,gBAA+C;AAE1E,gBAAe,IAAI,cAAc,EAAE,MAAM,QAAQ,CAAC;AAClD,gBAAe,IAAI,UAAU,UAAU,OAAO;AAC9C,gBAAe,IAAI,aAAa,UAAU;AAC1C,gBAAe,IAAI,YAAY,SAAS;AACxC,KAAI,SAAS,cAAc,sBAAsB;AAC/C,iBAAe,IAAI,2BAA2B,SAAS,WAAW;AAClE,iBAAe,IAAI,sBAAsB,SAAS,SAAS;;AAE7D,gBAAe,IAAI,wBAAwB,SAAS,WAAW;AAC/D,gBAAe,IAAI,sBAAsB,SAAS,SAAS;CAC3D,MAAM,qBAAqB,wCAAwC;EACjE,SAAS;EACT,UAAU;EACX,CAAC;AACF,KAAI,mBACF,gBAAe,IAAI,sBAAsB,mBAAmB;AAE9D,KAAI,oBAAoB,iBAAiB,UAAU,SAAS,EAC1D,gBAAe,IAAI,oBAAoB,iBAAiB;AAE1D,KAAI,iBAAiB,SAAS,EAC5B,gBAAe,IAAI,oBAAoB,iBAAiB;AAE1D,KAAI,eACF,gBAAe,IAAI,kBAAkB,eAAe;AAEtD,KAAI,qBACF,gBAAe,IAAI,wBAAwB,qBAAqB;AAGlE,KAAI,CAAC,SACH,QAAO;CAGT,MAAM,gBAAgB,mCAAmC,UAAU,oBAAoB;AACvF,WAAU,WAAW,cAAc;AACnC,gBAAe,IAAI,oBAAoB,SAAS;AAChD,gBAAe,IAAI,iBAAiB,cAAc;AAElD,QAAO;;;;;;;AAQT,MAAa,mCACX,mBAEA,gBAAgB,IAAI,YAAY,EAAE,WAAW,gBAAgB,IAAI,gBAAgB;AAEnF,MAAa,mCACX,mBACG;CACH,MAAM,SAAS,gBAAgB,IAAI,SAAS;CAC5C,MAAM,YAAY,gBAAgB,IAAI,YAAY;AAClD,KAAI,CAAC,UAAU,CAAC,aAAa,UAAU,WAAW,OAChD,OAAM,IAAI,MAAM,gEAAgE;AAGlF,QAAO;EAAE;EAAQ;EAAW"}

package/dist/server-agent.d.mts

@@ -1,6 +1,6 @@
-import { g as SurveyChangeSetShape } from "./lifecycle-BmGAIUlv.mjs";
-import { o as SurveyAssistantRequestContext, t as SURVEY_ASSISTANT_AGENT_ID } from "./constants-BMGTgfjv.mjs";
-import { n as surveyAssistantTools } from "./index-B0lxsAzx.mjs";
+import { g as SurveyChangeSetShape } from "./lifecycle-Bx0aq_4S.mjs";
+import { o as SurveyAssistantRequestContext, t as SURVEY_ASSISTANT_AGENT_ID } from "./constants-Be91Gay9.mjs";
+import { n as surveyAssistantTools } from "./index-x0qprHgK.mjs";
 import * as _$_mastra_core_agent0 from "@mastra/core/agent";
 import { Agent, AgentConfig } from "@mastra/core/agent";
 import { Memory } from "@mastra/memory";
@@ -37,7 +37,7 @@ declare const createSurveyAssistantAgent: ({
   observationalMemory
 }: CreateSurveyAssistantAgentOptions) => Agent<"survey-assistant-agent", Readonly<{
   survey_inspect: _$_mastra_core_tools0.Tool<{
-    action: "localization" | "current-context" | "search-items" | "item-details" | "assets" | "expression-diagnostics" | "raw-json";
+    action: "current-context" | "search-items" | "item-details" | "localization" | "assets" | "expression-diagnostics" | "raw-json";
     reason?: string | undefined;
     scopes?: ("summary" | "selected-item" | "outline" | "response-slots" | "ui-context" | "history")[] | undefined;
     query?: string | undefined;
@@ -48,12 +48,13 @@ declare const createSurveyAssistantAgent: ({
     cursor?: string | undefined;
     outlineMode?: "full" | "focused" | "children" | undefined;
     paths?: string[] | undefined;
+    textOffset?: number | undefined;
     includeChildren?: boolean | undefined;
     includeItemConfig?: boolean | undefined;
     limit?: number | undefined;
   }, {
     ok: boolean;
-    action: "localization" | "current-context" | "search-items" | "item-details" | "assets" | "expression-diagnostics" | "raw-json";
+    action: "current-context" | "search-items" | "item-details" | "localization" | "assets" | "expression-diagnostics" | "raw-json";
     modelSummary: string;
     reason?: string | undefined;
     result?: unknown;
@@ -61,12 +62,13 @@ declare const createSurveyAssistantAgent: ({
   survey_change: _$_mastra_core_tools0.Tool<{
     summary: string;
     operations: unknown[];
+    retryOfChangeIds?: string[] | undefined;
   }, SurveyChangeSetShape, unknown, unknown, _$_mastra_core_tools0.ToolExecutionContext<unknown, unknown, unknown>, "survey_change", unknown>;
   survey_authoring_reference: _$_mastra_core_tools0.Tool<{
     topic: string;
     itemType?: string | undefined;
     operationKind?: string | undefined;
-    detail?: "compact" | "full" | undefined;
+    detail?: "full" | "compact" | undefined;
     reason?: string | undefined;
   }, {
     ok: boolean;
@@ -75,15 +77,18 @@ declare const createSurveyAssistantAgent: ({
     content: string;
     itemType?: string | undefined;
     operationKind?: string | undefined;
-    detail?: "compact" | "full" | undefined;
+    detail?: "full" | "compact" | undefined;
   }, unknown, unknown, _$_mastra_core_tools0.ToolExecutionContext<unknown, unknown, unknown>, "survey_authoring_reference", unknown>;
   survey_expression: _$_mastra_core_tools0.Tool<{
     action: "context" | "prepare";
+    retryOfChangeIds?: string[] | undefined;
     reason?: string | undefined;
     itemIds?: string[] | undefined;
+    cursor?: string | undefined;
+    limit?: number | undefined;
     includeRawLocations?: boolean | undefined;
     summary?: string | undefined;
-    mutations?: Record<string, unknown>[] | undefined;
+    mutations?: unknown[] | undefined;
   }, SurveyChangeSetShape | {
     ok: boolean;
     action: "context";
@@ -93,6 +98,11 @@ declare const createSurveyAssistantAgent: ({
       ref: string;
       valueType?: string | undefined;
     }[];
+    nextCursor?: string | undefined;
+    totalResponseSlots?: number | undefined;
+    surveyResponseSlotCount?: number | undefined;
+    totalExpressionLocations?: number | undefined;
+    unresolvedItemIds?: string[] | undefined;
     expressionLocations?: {
       itemId: string;
       key: string;
@@ -139,6 +149,7 @@ declare const createSurveyAssistantAgent: ({
   survey_asset: _$_mastra_core_tools0.Tool<{
     action: "import-attachment" | "update-metadata" | "remove";
     summary: string;
+    retryOfChangeIds?: string[] | undefined;
     documentId?: string | undefined;
     assetId?: string | undefined;
     name?: string | null | undefined;

package/dist/server-agent.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"server-agent.d.mts","names":[],"sources":["../src/server/agent.ts"],"mappings":";;;;;;;;;;cAyBa,wCAAA,EAA0C,cAAA;AAAA,KA8SlD,0BAAA,GAA6B,WAAA,QACzB,yBAAA,SACA,oBAAA,aAEP,6BAAA;AAAA,KAGG,4BAAA,GAA+B,WAAA,CAClC,WAAA,CAAY,qBAAA,QAA6B,MAAA;AAAA,KA8E/B,yCAAA,GAA4C,OAAA,CACtD,4BAAA;AAAA,KAIG,8CAAA,GAAiD,OAAA,CACpD,IAAA,CAAK,yCAAA;EAEL,KAAA,EAAO,WAAA,CAAY,yCAAA;AAAA;AAAA,cAGR,8CAAA;EAAA;;;;cAMA,+CAAA;EAAmD,KAAA;EAAA,WAAA;EAAA,UAAA;EAAA,GAAA;AAAA,GAK7D,8CAAA,KAAiD,yCAAA;AAAA,UAkCnC,iCAAA;EACf,KAAA,EAAO,0BAAA;EACP,MAAA,GAAS,0BAAA;EACT,mBAAA,GAAsB,yCAAA;AAAA;AAAA,cAGX,0BAAA;EAA8B,MAAA;EAAA,KAAA;EAAA;AAAA,GAIxC,iCAAA,KAAiC,KAAA,2BAAA,QAAA;;;;;;;;;;;;;;;;;;;;;;uBAAA,qBAAA,CAAA,oBAAA"}
+{"version":3,"file":"server-agent.d.mts","names":[],"sources":["../src/server/agent.ts"],"mappings":";;;;;;;;;;cAyBa,wCAAA,EAA0C,cAAA;AAAA,KA0SlD,0BAAA,GAA6B,WAAA,QACzB,yBAAA,SACA,oBAAA,aAEP,6BAAA;AAAA,KAGG,4BAAA,GAA+B,WAAA,CAClC,WAAA,CAAY,qBAAA,QAA6B,MAAA;AAAA,KA8E/B,yCAAA,GAA4C,OAAA,CACtD,4BAAA;AAAA,KAIG,8CAAA,GAAiD,OAAA,CACpD,IAAA,CAAK,yCAAA;EAEL,KAAA,EAAO,WAAA,CAAY,yCAAA;AAAA;AAAA,cAGR,8CAAA;EAAA;;;;cAMA,+CAAA;EAAmD,KAAA;EAAA,WAAA;EAAA,UAAA;EAAA,GAAA;AAAA,GAK7D,8CAAA,KAAiD,yCAAA;AAAA,UAkCnC,iCAAA;EACf,KAAA,EAAO,0BAAA;EACP,MAAA,GAAS,0BAAA;EACT,mBAAA,GAAsB,yCAAA;AAAA;AAAA,cAGX,0BAAA;EAA8B,MAAA;EAAA,KAAA;EAAA;AAAA,GAIxC,iCAAA,KAAiC,KAAA,2BAAA,QAAA;;;;;;;;;;;;;;;;;;;;;;;uBAAA,qBAAA,CAAA,oBAAA"}

package/dist/server-agent.mjs

@@ -1,8 +1,8 @@
-import { d as getDeterministicCreateItemTypes } from "./form-authoring-kQDgC5oz.mjs";
+import { a as getDeterministicCreateItemTypes } from "./capabilities-1KNnNO1_.mjs";
 import { t as SURVEY_ASSISTANT_AGENT_ID } from "./constants-0UHGFcRJ.mjs";
-import { n as formatSurveyAuthoringReferenceRoutingInstructions } from "./authoring-references-CW38pYzK.mjs";
+import { n as formatSurveyAuthoringReferenceRoutingInstructions } from "./authoring-references-BJQ_1nMX.mjs";
 import { t as FAIR_BY_DESIGN_REFERENCE_ROUTING_INSTRUCTION } from "./fair-guidance-CRYCRxQm.mjs";
-import { n as surveyAssistantTools, t as SURVEY_ASSISTANT_TOOL_IDS } from "./tools-CFh35R4d.mjs";
+import { n as surveyAssistantTools, t as SURVEY_ASSISTANT_TOOL_IDS } from "./tools-BvSovehT.mjs";
 import { createHash } from "node:crypto";
 import { Agent } from "@mastra/core/agent";
 import { Memory } from "@mastra/memory";
@@ -155,24 +155,20 @@ const buildInstructions = ({ requestContext }) => {
 		"The capability manifest is authoritative for available item types, create modes, supported operations, content surfaces, response slots, and capability-owned references. Never guess unsupported item behavior.",
 		"Never claim that an item type, field type, controller, operation, or other editor capability is unavailable unless the current capability manifest or a loaded authoring reference explicitly excludes it. For a capability question, inspect or load the focused reference before answering; if support remains unclear, say that it is unverified rather than unsupported.",
 		"For an installed custom item type, use survey_authoring_reference with both itemType and one of its advertised reference topics before creating or changing unfamiliar config. Use survey_inspect item-details to obtain capability-provided inspection details for existing items.",
-		`Use ${INSPECT_TOOL_NAME} to inspect current draft context, UI context/highlights, recent editor history, search, item details, localization surfaces, image assets, expression-reference diagnostics, complete paged outlines, response slots, and exact raw JSON paths. Successful same-turn edits are immediately visible there. Use action "expression-diagnostics" before and after a survey-wide reference repair; it returns exact owning items, expression locations, invalid refs or option values, and bounded replacement candidates. Use action "localization" to page source-locale respondent content and see which target-locale surfaces are missing; it covers survey-level and item-level translation maps without one item-details call per item. Use action "assets" to obtain explicit assetId values, metadata, and usage locations before asset changes; the key of /assets/<key> is the asset ID even though the stored asset object does not repeat it. Never guess what "this", "here", or "the highlighted part" refers to when the draft can resolve it. History explains recent actions but the current draft remains authoritative within the turn.`,
-		"For any survey review, audit, defect check, or request to spot issues, run survey_audit before answering. Apply its key-semantic-consistency principle to the returned key/content evidence; for a comprehensive audit, page keyReviewOffset until all key-review evidence has been reviewed. Its deterministic logic findings include broken expression references. When it reports an expression-reference finding, use survey_inspect action expression-diagnostics for exact locations and current replacement candidates; do not describe the audit as clean while any such finding remains.",
+		`Use ${INSPECT_TOOL_NAME} to inspect current draft context, UI context/highlights, recent editor history, search, item details, localization surfaces, image assets, expression-reference diagnostics, complete paged outlines, response slots, and exact raw JSON paths. Successful same-turn edits are immediately visible there. Use action "expression-diagnostics" before and after a survey-wide reference repair; it returns exact owning items, expression locations, invalid refs or option values, bounded replacement candidates, and each diagnostic's blocking or advisory disposition, category, and guidance. Repair blocking diagnostics. Review advisory diagnostics according to their category-specific guidance without changing them automatically. Use action "localization" to page source-locale respondent content and see which target-locale surfaces are missing; it covers survey-level and item-level translation maps without one item-details call per item. Use action "assets" to obtain explicit assetId values, metadata, and usage locations before asset changes; the key of /assets/<key> is the asset ID even though the stored asset object does not repeat it. Never guess what "this", "here", or "the highlighted part" refers to when the draft can resolve it. History explains recent actions but the current draft remains authoritative within the turn.`,
+		"For any survey review, audit, defect check, or request to spot issues, run survey_audit before answering. Apply its key-semantic-consistency principle to the returned key/content evidence; for a comprehensive audit, page keyReviewOffset until all key-review evidence has been reviewed. Its deterministic logic findings distinguish blocking expression defects from advisory diagnostics. When it reports an expression-reference finding, use survey_inspect action expression-diagnostics for exact locations, disposition, category, guidance, and current replacement candidates. Do not describe blocking defects as resolved while they remain; report advisories separately and follow their category-specific guidance.",
 		`Use ${AUTHORING_REFERENCE_TOOL_NAME} to load focused stable authoring conventions and payload contracts.`,
 		formatSurveyAuthoringReferenceRoutingInstructions(),
 		FAIR_BY_DESIGN_REFERENCE_ROUTING_INSTRUCTION,
 		`Use ${AUDIT_TOOL_NAME} for read-only deterministic technical checks and a structured questionnaire-quality review rubric. For quality feedback, combine its exact findings with survey-quality and inspect the relevant wording and flow. Clearly distinguish technical defects, design recommendations, and claims that would require cognitive testing or psychometric evidence.`,
 		`Use ${CHANGE_TOOL_NAME} for typed survey operations and ${EXPRESSION_TOOL_NAME} for expressions. Prefer typed operations; use one inspected survey-json-patch operation only when no typed operation covers the requested field.`,
 		`The typed ${CHANGE_TOOL_NAME} operations cover item structure/content/config, choices, forms, survey content, and assets. For an unfamiliar operation shape, load assistant-operations with operationKind and, when targeting an item type, itemType to receive a compact composed contract. Request full contract detail only for protocol debugging. Omit operationKind only when broader conventions are needed. Reorders replace the complete inspected list and use optionIds, groupIds, or itemIds as documented by the tool.`,
-		"Canonical create-item shape: put parentItemId and optional index in target; put id, key, itemType, config, and any creation-time expressions in item; put respondent-visible plainText or structured content in top-level translations. Put choice maxSelection and options inside item.config. For top-level creation, target the root group identified by the snapshot or inspection.",
-		"Use update-item-translation with itemId, locale, contentKey, and plainText for ordinary respondent-visible text. Use content only for a complete structured Content value when formatting carries meaning. Item title, subtitle, topContent, bottomContent, cardFooter, info content, option labels, and field labels are translations, not item labels.",
 		"Survey languages are locale branches. An unqualified request to \"add a German localization\", \"add German\", or translate/localize the survey means make the existing respondent-facing content available in that language; an empty locale registration alone is incomplete. Inspect action \"localization\", translate every requested surface, and let the first real typed translation introduce an absent locale. Use add-survey-locale only when the user explicitly asks to register an empty language before content exists. When the user asks to remove or delete a survey language, use remove-survey-locale with the exact existing locale code; it destructively removes every survey-level and item-level translation stored for that locale. Load the focused assistant-operations contract before an explicit locale lifecycle change. Never substitute dummy translations, translation-by-translation deletion, or a raw patch.",
-		"Use update-placed-image only for an image already embedded in rich text in the live survey or validated turn draft. It can switch the placement between a local asset and an external URL and update its rendered ALT text, caption, width, height, maximum dimensions, and alignment. For a new item, prefer putting the complete richText value with the image block directly in create-item.translations[].content. Do not use image asset metadata when the user asked to change one placed image.",
 		"An unqualified request to add or change a survey item or question label means the editor-only item label and uses update-item-label. A question title/text, option label, or field label is respondent-visible translated content.",
 		"A group is a hierarchy/container, not a decorative heading. Use a group for meaningful nested structure, an info item for standalone explanatory content, and a page break when only a respondent page boundary is needed. Create a non-root group empty, then create its children in parent-before-child order.",
 		"Write respondent-visible content under its actual locale. A real typed translation may introduce a missing locale; never place target-language text under an existing wrong locale or create dummy content merely to introduce a locale.",
-		"Use plainText for ordinary unformatted copy. Load rich-text-content and use structured richText only for meaningful headings, lists, emphasis, links, images, info boxes, or other formatting. Markdown syntax inside md/plain content is not rendered as rich formatting.",
+		"Use plainText for ordinary unformatted copy. Load rich-text-content and use structured richText only for meaningful headings, lists, emphasis, links, images, info boxes, or other formatting on a surface documented as rendering rich text. For complete formatted values on those surfaces, prefer the compact richTextBlocks shorthand described there; use a full content.doc tree for structures the shorthand does not cover. A typed field accepting structured content does not by itself guarantee that its renderer preserves formatting. Markdown syntax inside md/plain content is not rendered as rich formatting.",
 		"Do not refuse an edit merely because no narrow typed operation exists. Inspect the exact current raw item/path and use survey-json-patch for assistant-editable survey fields that have no typed or expression helper.",
-		"A survey-json-patch proposal contains exactly one operation with kind survey-json-patch and one plural patches array containing every related raw edit. It must be the only operation in that survey_change call. Paths are rooted at the survey document, such as /surveyItems/<index>/config or /translations/<locale>; never start at /config or modify /$schema. Patch translation leaves rather than replacing existing locale or item-translation containers.",
 		"A choice free-text follow-up such as Other, please specify is an option embeddedForm, not allowOther. For a newly created choiceItem, put the option and its embeddedForm directly in create-item. Default authoringMode to simple when the embedded form has exactly one supported field in one ordinary single-column group; use custom only for blank, multi-field, multi-group, conditional, or layout-customized follow-ups. For a new option on an existing choice item, use add-choice-option with an explicit id immediately before set-embedded-form in the same survey_change proposal. Load embedded-forms and use set-embedded-form with relative translations for existing choice options. Use a raw patch only when the typed operations cannot express the requested change.",
 		"For choiceItem, maxSelection 1 is single choice, null is unlimited multiple choice, and a positive number is capped multiple choice. Choice config options use ids/keys/configuration; respondent-visible option labels belong in translations at options.<optionId>.label.",
 		"Every form or embedded-form select option needs a visible translation. Do not rely on raw controller values as respondent labels.",
@@ -186,7 +182,7 @@ const buildInstructions = ({ requestContext }) => {
 		"When a recoverable rejection has a known repair and the user still requests the edit, inspect the current target and attempt the corrected mutation before explaining the failure again. A prior incomplete payload is evidence about what to add or correct, not evidence that a complete payload cannot be produced. Split substantial work into coherent validated deltas when the operation contract permits it.",
 		"Prefer one mutation call for an ordinary request. For substantial work, use successive coherent deltas in the same turn. Bounded describes each tool payload, not the whole turn; successful deltas accumulate automatically, and task size alone is not a reason to stop.",
 		"Before answering, reconcile every requested target against the latest validated draft. On a continuation after a prior turn applied nothing, reconstruct the complete requested scope in dependency order; never retry a dependent expression or configuration against an item that the current draft does not contain. When survey_change reports verification.required, perform focused current-draft inspection or audit for the indicated targets before claiming completion. Never claim rejected, missing, partial, or failed work was completed. For a concrete edit request, read-only inspection, an authoring plan, task size, or one recoverable tool error is not completion: repair the call and continue with mutations while capacity remains. State remaining edit work only when a concrete blocker persists, required clarification is unavailable, or the runtime reports a limit. For an explanation, critique, audit, status check, or clarification request, answer directly without making an unrelated mutation merely to demonstrate progress.",
-		"When required structure or behavior is clear but ordinary respondent wording is open, choose concise, neutral, internally consistent wording. Ask only when ambiguity materially affects purpose, domain, language, or compliance.",
+		"When required structure or behavior is clear but ordinary respondent wording or a reversible layout or presentation choice is open, make a reasonable, internally consistent assumption and continue. Ask only when ambiguity materially affects purpose, domain, language, compliance, or another consequence that is costly to reverse. Briefly disclose consequential assumptions in the final summary after completing the work instead of asking about them beforehand.",
 		"For concrete supported edits, inspect the relevant live state, load every reference explicitly required above before the first mutation attempt, then execute the requested change. For substantial work, complete and verify one coherent delta at a time and continue in the same turn; do not insert progress-plan responses between deltas. Summarize only the final validated candidates concisely. Do not ask the user to choose an output mode.",
 		"Do not write tool syntax, hidden chain-of-thought, or invented validation results in normal text. Never claim persistence outside the editor.",
 		`Attachment document ids available for explicit loading or asset import:\n${attachmentManifest}`,