@case-framework/survey-assistant 0.2.2 → 0.3.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (107) hide show
  1. package/dist/{authoring-references-DYuOAdVx.mjs → authoring-references-yyYC4Ydi.mjs} +9 -3
  2. package/dist/authoring-references-yyYC4Ydi.mjs.map +1 -0
  3. package/dist/{capabilities-DlC1l6qy.d.mts → capabilities-CnsVuJ1k.d.mts} +12 -4
  4. package/dist/capabilities-CnsVuJ1k.d.mts.map +1 -0
  5. package/dist/capabilities-default.d.mts +1 -1
  6. package/dist/capabilities-default.d.mts.map +1 -1
  7. package/dist/capabilities-default.mjs +38 -4
  8. package/dist/capabilities-default.mjs.map +1 -1
  9. package/dist/{constants-D-5m_KGB.d.mts → constants-DrGZXtQf.d.mts} +12 -7
  10. package/dist/constants-DrGZXtQf.d.mts.map +1 -0
  11. package/dist/{controller-proxy-0WJZUZYx.mjs → controller-proxy-CpkQRezb.mjs} +3 -2
  12. package/dist/controller-proxy-CpkQRezb.mjs.map +1 -0
  13. package/dist/{controller-proxy-Hkuub9dt.d.mts → controller-proxy-DmBdzqKs.d.mts} +5 -2
  14. package/dist/controller-proxy-DmBdzqKs.d.mts.map +1 -0
  15. package/dist/{digest-BvXpeWcR.d.mts → digest-Dyjch_sC.d.mts} +2 -2
  16. package/dist/{digest-BvXpeWcR.d.mts.map → digest-Dyjch_sC.d.mts.map} +1 -1
  17. package/dist/digest.d.mts +1 -1
  18. package/dist/{engine-0AJrv0hI.mjs → engine-CWTuN3o2.mjs} +866 -663
  19. package/dist/engine-CWTuN3o2.mjs.map +1 -0
  20. package/dist/engine.d.mts +3 -3
  21. package/dist/engine.mjs +3 -3
  22. package/dist/fair-guidance-CEdJYccK.mjs +21 -0
  23. package/dist/fair-guidance-CEdJYccK.mjs.map +1 -0
  24. package/dist/form-authoring-DCd9XfXf.mjs +155 -0
  25. package/dist/form-authoring-DCd9XfXf.mjs.map +1 -0
  26. package/dist/{index-JXH-t2EJ.d.mts → index-Bo4dHAo8.d.mts} +68 -6
  27. package/dist/index-Bo4dHAo8.d.mts.map +1 -0
  28. package/dist/{index-MEOL9_Gr.d.mts → index-D4OitUg4.d.mts} +5 -430
  29. package/dist/index-D4OitUg4.d.mts.map +1 -0
  30. package/dist/{index-BcyfBeDj.d.mts → index-DZk20e3k.d.mts} +44 -22
  31. package/dist/index-DZk20e3k.d.mts.map +1 -0
  32. package/dist/{index-CneD8ibB.d.mts → index-Dxgg0-D_.d.mts} +12 -3
  33. package/dist/index-Dxgg0-D_.d.mts.map +1 -0
  34. package/dist/lifecycle-DWv5CiSu.d.mts +523 -0
  35. package/dist/lifecycle-DWv5CiSu.d.mts.map +1 -0
  36. package/dist/{memory-thread-repository-1ocPOda8.mjs → memory-thread-repository-acbz6HZJ.mjs} +181 -26
  37. package/dist/memory-thread-repository-acbz6HZJ.mjs.map +1 -0
  38. package/dist/{protocol-DpCYmCjr.mjs → protocol-DATvkr1S.mjs} +125 -6
  39. package/dist/protocol-DATvkr1S.mjs.map +1 -0
  40. package/dist/protocol.d.mts +4 -3
  41. package/dist/protocol.mjs +2 -2
  42. package/dist/{react-DXK5zWNo.mjs → react-Br5YE8H-.mjs} +132 -12
  43. package/dist/react-Br5YE8H-.mjs.map +1 -0
  44. package/dist/react-integration.d.mts +1 -1
  45. package/dist/react-integration.mjs +1 -1
  46. package/dist/react.d.mts +2 -2
  47. package/dist/react.mjs +2 -2
  48. package/dist/references/assistant-operations.md +13 -18
  49. package/dist/references/embedded-forms.md +41 -2
  50. package/dist/references/expressions.md +17 -9
  51. package/dist/references/fair-by-design.md +80 -0
  52. package/dist/references/item-types.md +19 -3
  53. package/dist/references/localization.md +7 -4
  54. package/dist/references/source-material-surveys.md +6 -4
  55. package/dist/{request-context-BBzU3VdG.mjs → request-context-BEjnaaFr.mjs} +10 -5
  56. package/dist/request-context-BEjnaaFr.mjs.map +1 -0
  57. package/dist/server-agent.d.mts +44 -22
  58. package/dist/server-agent.d.mts.map +1 -1
  59. package/dist/server-agent.mjs +71 -14
  60. package/dist/server-agent.mjs.map +1 -1
  61. package/dist/server-runtime.d.mts +22 -11
  62. package/dist/server-runtime.d.mts.map +1 -1
  63. package/dist/server-runtime.mjs +47 -19
  64. package/dist/server-runtime.mjs.map +1 -1
  65. package/dist/server-tasks.d.mts +1 -1
  66. package/dist/server-tasks.mjs +6 -4
  67. package/dist/server-tasks.mjs.map +1 -1
  68. package/dist/server-tools.d.mts +1 -1
  69. package/dist/server-tools.mjs +1 -1
  70. package/dist/server.d.mts +16 -7
  71. package/dist/server.d.mts.map +1 -1
  72. package/dist/server.mjs +4 -4
  73. package/dist/storage-postgres.d.mts +1 -1
  74. package/dist/{tasks-DcfQNJwO.d.mts → tasks-DQgL449A.d.mts} +8 -4
  75. package/dist/tasks-DQgL449A.d.mts.map +1 -0
  76. package/dist/{thread-documents-BlxNjc7S.d.mts → thread-documents-Dvo6XS7o.d.mts} +1 -1
  77. package/dist/{thread-documents-BlxNjc7S.d.mts.map → thread-documents-Dvo6XS7o.d.mts.map} +1 -1
  78. package/dist/{thread-handlers-uddXwQjp.d.mts → thread-handlers-CeYl45xG.d.mts} +9 -4
  79. package/dist/thread-handlers-CeYl45xG.d.mts.map +1 -0
  80. package/dist/{tools-wgLen05n.mjs → tools-Dg9HZrYU.mjs} +404 -78
  81. package/dist/tools-Dg9HZrYU.mjs.map +1 -0
  82. package/dist/ui.css +2 -2
  83. package/dist/ui.d.mts +94 -10
  84. package/dist/ui.d.mts.map +1 -1
  85. package/dist/ui.mjs +343 -112
  86. package/dist/ui.mjs.map +1 -1
  87. package/docs/integration.md +74 -6
  88. package/package.json +25 -19
  89. package/dist/authoring-references-DYuOAdVx.mjs.map +0 -1
  90. package/dist/capabilities-DKbNCnBf.mjs +0 -66
  91. package/dist/capabilities-DKbNCnBf.mjs.map +0 -1
  92. package/dist/capabilities-DlC1l6qy.d.mts.map +0 -1
  93. package/dist/constants-D-5m_KGB.d.mts.map +0 -1
  94. package/dist/controller-proxy-0WJZUZYx.mjs.map +0 -1
  95. package/dist/controller-proxy-Hkuub9dt.d.mts.map +0 -1
  96. package/dist/engine-0AJrv0hI.mjs.map +0 -1
  97. package/dist/index-BcyfBeDj.d.mts.map +0 -1
  98. package/dist/index-CneD8ibB.d.mts.map +0 -1
  99. package/dist/index-JXH-t2EJ.d.mts.map +0 -1
  100. package/dist/index-MEOL9_Gr.d.mts.map +0 -1
  101. package/dist/memory-thread-repository-1ocPOda8.mjs.map +0 -1
  102. package/dist/protocol-DpCYmCjr.mjs.map +0 -1
  103. package/dist/react-DXK5zWNo.mjs.map +0 -1
  104. package/dist/request-context-BBzU3VdG.mjs.map +0 -1
  105. package/dist/tasks-DcfQNJwO.d.mts.map +0 -1
  106. package/dist/thread-handlers-uddXwQjp.d.mts.map +0 -1
  107. package/dist/tools-wgLen05n.mjs.map +0 -1
@@ -1,6 +1,7 @@
1
1
  # Expressions, Conditions, Validations, Prefills
2
2
 
3
3
  Use `survey_expression` for expression work. It is the expression capability bundle:
4
+
4
5
  - `action: "context"` returns available response refs and optional existing expression locations.
5
6
  - `action: "prepare"` validates expression refs/return types and registers a candidate change set.
6
7
  - Prefer this tool over hand-written raw JSON Patch for expression-bearing locations.
@@ -21,6 +22,7 @@ Optional `editorConfig` can contain `usedTemplate`, `label`, and `description`.
21
22
  ## Response Values And Variables
22
23
 
23
24
  Response values are typed objects:
25
+
24
26
  - string: `{ "type": "string", "value": "abc" }`
25
27
  - number: `{ "type": "number", "value": 42 }`
26
28
  - boolean: `{ "type": "boolean", "value": true }`
@@ -33,6 +35,7 @@ Response variable refs use this exact string format:
33
35
  `<itemId>...<method>...<slotId>`
34
36
 
35
37
  Methods:
38
+
36
39
  - `get`: returns the current slot value.
37
40
  - `isDefined`: returns boolean true when a response exists.
38
41
 
@@ -40,15 +43,17 @@ Never invent response refs. Use the current context response-slots scope or item
40
43
  This rule is item-type independent: preserve every item id, slot id, component/validation key,
41
44
  prefill id, template key, and reference constant exactly as inspected. Never humanize an identifier
42
45
  for display or explanation; if a coding key exists, show that exact key, otherwise show the exact id.
43
- The live snapshot is immutable for the whole assistant response. `survey_change` validates and
44
- registers a candidate; it does not change what later tools can inspect. The browser applies authorized change sets
45
- only after the response completes successfully. A validated candidate is intended for apply if the turn succeeds;
46
- it is not a dry run. For a
47
- request that creates dependent items, plan the complete structure first, put the source create
48
- operation before its dependents, and embed each dependent expression directly in its
49
- `create-item.item` object in one `survey_change` call. Do not create the items with
50
- `survey_change` and then call `survey_expression`: live inspection cannot see unapplied items
51
- during the same turn.
46
+ The submitted snapshot is the immutable apply baseline, but successful mutation calls materialize
47
+ in one request-scoped draft. Later inspection and mutation tools can see and target items,
48
+ translations, assets, and response slots introduced earlier in the same turn. The browser applies
49
+ the authorized cumulative draft only after the response completes successfully; a validated
50
+ candidate is intended for apply if the turn succeeds and is not a dry run.
51
+
52
+ For a request that creates dependent items, prefer planning the complete structure first, putting
53
+ the source create operation before its dependents, and embedding each dependent expression directly
54
+ in its `create-item.item` object in one `survey_change` call. When a genuine dependency requires
55
+ separate calls, inspect the updated request-scoped draft and use `survey_expression` against the
56
+ newly available ids and response slots.
52
57
 
53
58
  Each response slot defined by a source item's config is available as
54
59
  `<sourceItemId>...get...<slotId>`, with a boolean presence check at
@@ -56,6 +61,7 @@ Each response slot defined by a source item's config is available as
56
61
  function and constant. For example, a single-choice `reference` slot uses `eq` with a
57
62
  `reference` const; this is only one typed case, not a restriction on source item types.
58
63
  Always check the response slot value type before choosing a function:
64
+
59
65
  - Single-choice choice items return `reference`; compare them with `eq` and a `reference` const.
60
66
  - Multiple-choice choice items return `reference[]`; check selected options with `list_contains` and a `reference` const.
61
67
  - `list_contains` must receive `string[]` + `string` or `reference[]` + `reference`. Never use it with a single `reference` response.
@@ -279,11 +285,13 @@ Prefill shape:
279
285
  ```
280
286
 
281
287
  Targets:
288
+
282
289
  - `{ "type": "itemResponse" }`
283
290
  - `{ "type": "field", "fieldId": "<fieldId>" }`
284
291
  - `{ "type": "embeddedField", "optionId": "<optionId>", "fieldId": "<fieldId>" }`
285
292
 
286
293
  Sources:
294
+
287
295
  - `static`: direct ResponseValue.
288
296
  - `expression`: JsonExpression.
289
297
  - `templateValue`: `{ "key": "<templateValueKey>" }`.
@@ -0,0 +1,80 @@
1
+ # FAIR-by-design survey authoring
2
+
3
+ Use this reference when a request concerns FAIR or born-FAIR data, interoperability, reuse,
4
+ standardization, harmonization, comparability across studies or waves, codebooks or export,
5
+ stable identifiers and codes, missing-value semantics, metadata or provenance, standard
6
+ instruments, or controlled vocabularies and formats.
7
+
8
+ FAIR means Findable, Accessible, Interoperable, and Reusable. In Survey Editor authoring, the
9
+ most relevant concerns are machine-readable identifiers and codes, sufficient metadata, and
10
+ stable semantics that survive translation, rewording, export, and reuse. FAIR is decision context,
11
+ not a universal override of the user's request or an established survey convention.
12
+
13
+ ## Keep the three layers separate
14
+
15
+ 1. **Presentation:** respondent-visible questions, instructions, and answer labels. These are
16
+ localized content and may be reworded.
17
+ 2. **Stored identifiers and codes:** stable item and option identifiers, coding keys, typed values,
18
+ and standard formats. These are for machines and should not depend on display language.
19
+ 3. **Metadata:** definitions, labels for codes, units, data types, missing-value meanings, versions,
20
+ provenance, and mappings to standards. Meaning belongs here rather than being packed into a
21
+ short identifier.
22
+
23
+ Do not use a respondent-visible label as though it were a stable stored code. Do not expose a raw
24
+ identifier as respondent wording. In CASE, visible item, option, field, and validation text belongs
25
+ in locale translations; ids, keys, option values, and response-slot references remain exact data.
26
+
27
+ ## Identifiers and coding keys
28
+
29
+ - Preserve stable internal ids and existing keys unless the user asks to change them. Never
30
+ silently repurpose an existing identifier when meaning changes.
31
+ - When FAIR item-key naming is relevant, start with a letter; use lowercase ASCII letters, digits,
32
+ and underscores; use `snake_case`; stay at or below 32 characters; avoid programming and
33
+ database reserved words; prefer a stable, language-neutral English concept name; reuse the same
34
+ concept name across waves and studies; use established instrument prefixes and sortable item
35
+ numbers when applicable; and distinguish raw from derived variables.
36
+ - A name is a stable handle, not a sentence. Put the complete question meaning in content and
37
+ metadata.
38
+ - For a standard instrument, preserve its established identity and predictable structure, such as
39
+ an instrument prefix plus a zero-padded item number, rather than inventing unrelated names.
40
+ - Choice option ids, keys, and values should be stable and coding-friendly. Their localized labels
41
+ remain separate translations.
42
+ - Follow an explicit user-supplied identifier or established local convention when FAIR naming was
43
+ not requested. If a FAIR alternative would materially help, explain the tradeoff rather than
44
+ silently imposing it.
45
+
46
+ ## Answers, value sets, and missingness
47
+
48
+ - Prefer defined coded value sets over storing localized display text as the primary answer.
49
+ - Keep the coding scheme consistent across equivalent questions. Every code needs a documented
50
+ label and meaning.
51
+ - Reuse established code lists and formats when the task calls for interoperability: ISO 8601 for
52
+ dates, ISO 3166 for countries, ISO 639 for languages, UCUM for units, and appropriate domain
53
+ vocabularies such as LOINC or SNOMED CT when supported and relevant.
54
+ - Treat not applicable, skipped by routing, do not know, refused, and not asked as distinct missing
55
+ reasons. Never invent an ordinary numeric value such as `99` or `-9` that could be analyzed as a
56
+ real response unless the surrounding data model explicitly declares and documents it as missing.
57
+ - Do not invent CASE fields or ad hoc codes to simulate missing-value semantics that the installed
58
+ editor capabilities do not support. Explain the capability gap instead.
59
+
60
+ ## Metadata, reuse, and versioning
61
+
62
+ - Capture useful metadata already implied by authoring: question text, localized labels, answer
63
+ choices, types, constraints, units, definitions, provenance, and standard mappings.
64
+ - Reuse a validated standard question or instrument definition when available instead of creating a
65
+ near-duplicate merely from wording.
66
+ - Keep raw collected values separate from derived values and document how derivations are made.
67
+ - Treat content changes, mappings, and instrument updates as versioned changes. Do not rename or
68
+ repurpose an existing identifier merely to change its meaning.
69
+ - Dataset-level persistent identifiers, licences, publication metadata, DDI/FHIR exports, and other
70
+ repository or export guarantees are platform concerns unless the current capability manifest
71
+ exposes them. Explain that boundary rather than claiming the survey edit alone makes the final
72
+ dataset FAIR.
73
+
74
+ ## Applying this reference
75
+
76
+ Use only supported survey structures and operations. Inspect the current survey and relevant
77
+ capabilities before changing existing identifiers, codes, values, or metadata. Do not proactively
78
+ rewrite a survey merely because this reference was loaded. Apply the parts material to the user's
79
+ goal, state important tradeoffs, and identify platform-level FAIR requirements that remain outside
80
+ the editor.
@@ -83,9 +83,10 @@ Embedded option forms:
83
83
  - There is no `allowOther` flag in the current choice item model. Do not use `allowOther` to create free-text "Other" inputs.
84
84
  - CRITICAL — exact key name: the field on the option object is `embeddedForm` (singular, one object). It is NEVER `embeddedForms` (plural) and NEVER an array. The option's recognized keys are only: `id`, `key`, `label`, `hasDisplayCondition`, `embeddedFormItemId`, `embeddedForm`. Any other key (including a typo'd/pluralized `embeddedForms`) is silently dropped during validation — no error is raised, the field simply never appears, and you must not report the change as successful if you are not certain you used the exact singular key.
85
85
  - CRITICAL — exact shape: `embeddedForm` fields are never listed directly as `embeddedForm.fields`. They must be nested inside `embeddedForm.fieldGroups`, an array of groups, each with its own `fields` array: `{ "id": "...", "fieldGroups": [ { "id": "...", "fields": [ { "id": "...", "type": "input", "controller": { "type": "input", ... } } ] } ] }`. A top-level `fields` array with no `fieldGroups` wrapper will not render anything.
86
- - CRITICAL — `embeddedForm` is a FLAT object with exactly two meaningful keys: `id` and `fieldGroups`. Do NOT invent an envelope like `{ "itemType": "formItem", "config": { "fields": [...] } }` — that is not a real shape, it is not schema-validated so it fails silently (no error, no visible field, the option just behaves as if it had no embedded form at all). There is no `itemType`/`config` wrapper anywhere inside `embeddedForm`; `fieldGroups` sits directly on the `embeddedForm` object itself.
86
+ - CRITICAL — `embeddedForm` is a FLAT object with `id`, `authoringMode`, and `fieldGroups`. Do NOT invent an envelope like `{ "itemType": "formItem", "config": { "fields": [...] } }`. There is no `itemType`/`config` wrapper anywhere inside `embeddedForm`; `fieldGroups` sits directly on the `embeddedForm` object itself.
87
87
  - CRITICAL — always set an explicit `id` on any option that will have an `embeddedForm` (e.g. `"id": "other"`, lowercase, coding-friendly). If you omit `id`, one is auto-generated from `label` and PRESERVES THE EXACT CASE of the label text (e.g. label "Other" auto-generates id "Other", not "other") — you cannot reliably predict it, and every embedded-form translation content key (`embeddedForms.<optionId>...`) and response slot (`embedded.<optionId>...`) must match that exact generated id, including case. Setting an explicit lowercase `id` yourself removes this guesswork entirely.
88
- - To attach input controls to a choice option, put an `embeddedForm` on that option. It uses the same `FormItemConfig` shape as a `formItem` (`id` + `fieldGroups`), but it is embedded directly on the option object — it is never a separate `formItem` sibling and never uses `embeddedFormItemId` unless you are intentionally referencing a shared/reusable form item defined elsewhere (rare; prefer inline `embeddedForm`).
88
+ - To attach input controls to a choice option, put an `embeddedForm` on that option. It uses the same `FormItemConfig` shape as a `formItem` (`id` + `authoringMode` + `fieldGroups`), but it is embedded directly on the option object — it is never a separate `formItem` sibling and never uses `embeddedFormItemId` unless you are intentionally referencing a shared/reusable form item defined elsewhere (rare; prefer inline `embeddedForm`).
89
+ - Use `authoringMode: "simple"` only for one internal group containing exactly one field. Use `custom` for a blank or multi-field follow-up. Adding, removing, moving, retyping, or rekeying fields, or changing groups/layouts, is a one-way transition to `custom`; preserve the existing field and translations during that transition.
89
90
  - The embedded form renders only while that option is selected. When the option is deselected, existing embedded responses are cleared after user confirmation.
90
91
  - Embedded form translation keys are prefixed with `embeddedForms.<optionId>`; for example `embeddedForms.other.fields.other_text.label`. Note this translation content-key prefix IS plural (`embeddedForms`) even though the config field on the option is singular (`embeddedForm`) — these are two different things; do not confuse them.
91
92
  - Embedded form response slots are `embedded.<optionId>.<fieldKey>`; for example `embedded.other.other_text`.
@@ -100,6 +101,7 @@ Example "Other, please specify" option:
100
101
  "key": "other",
101
102
  "embeddedForm": {
102
103
  "id": "other",
104
+ "authoringMode": "simple",
103
105
  "fieldGroups": [
104
106
  {
105
107
  "id": "other_details",
@@ -160,6 +162,7 @@ One `create-item` operation carries the whole item plus every translation it nee
160
162
  "key": "other",
161
163
  "embeddedForm": {
162
164
  "id": "other",
165
+ "authoringMode": "simple",
163
166
  "fieldGroups": [
164
167
  {
165
168
  "id": "other_details",
@@ -242,6 +245,7 @@ Interactive form question:
242
245
  "itemType": "formItem",
243
246
  "config": {
244
247
  "id": "<itemId>",
248
+ "authoringMode": "custom",
245
249
  "fieldGroups": [
246
250
  {
247
251
  "id": "main",
@@ -253,7 +257,18 @@ Interactive form question:
253
257
  }
254
258
  ```
255
259
 
256
- CRITICAL — the item's `config` object has exactly two meaningful keys: `id` and `fieldGroups`. `fieldGroups` sits directly on `config` — never nest it under another wrapper, and never put a top-level `fields` array directly on `config` (fields must be inside a `fieldGroups` entry). Fields need at least one non-empty `fieldGroups` entry with an actual `fields` array to be useful; an empty `fieldGroups: [{ "fields": [] }]` is only a starting scaffold, not a finished item.
260
+ The item's config has `id`, `authoringMode`, and `fieldGroups`. `fieldGroups` sits directly on config — never nest it under another wrapper, and never put a top-level `fields` array directly on config.
261
+
262
+ Authoring modes and Add item presets:
263
+
264
+ - `Text` → `input`, `Long text` → `textarea`, `Number` → `number`, `Slider` → `slider`, `Dropdown` → `select`, `Date` → `datepicker`, and `Switch` → `switch`.
265
+ - These seven presets use `authoringMode: "simple"` with exactly one internal field group containing exactly one field. The field group remains part of persisted/runtime data; hiding it is only an editor abstraction.
266
+ - `Blank form` uses `authoringMode: "custom"`. Any finished multi-field/group form also uses custom mode.
267
+ - Simple mode exposes the existing field's label, description, required state, and compatible controller settings. It does not expose groups, layouts, field reordering, field keys, or field-type switching.
268
+ - Adding/removing/moving fields or groups, changing layout, or changing the sole field's key/type is a one-way transition to custom. Preserve the existing field and every translation. Never leave a multi-field, empty, or multi-group structure marked simple.
269
+ - If a stored simple form lacks its sole first field, treat it as custom without deleting any remaining data.
270
+
271
+ Fields normally need at least one non-empty group to be useful. An explicit `authoringMode: "custom"` with one empty group is the supported Blank form starting preset.
257
272
 
258
273
  Field group config:
259
274
 
@@ -357,6 +372,7 @@ MANDATORY: every `select` option needs a matching `fields.<fieldId>.options.<opt
357
372
  "itemType": "formItem",
358
373
  "config": {
359
374
  "id": "form_1",
375
+ "authoringMode": "custom",
360
376
  "fieldGroups": [
361
377
  {
362
378
  "id": "main",
@@ -5,17 +5,19 @@ Use this reference when the user asks to translate, localize, add a language, or
5
5
  ## Locale Lifecycle
6
6
 
7
7
  - A target locale may be absent. That is a normal starting state, not an error and not a reason to inspect a nonexistent translation branch.
8
+ - 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. Registering an empty locale does not complete that request.
9
+ - Use `add-survey-locale` only when the user explicitly wants the language registered before it has translated content. It rejects blank and already-present locale codes.
8
10
  - Use the target locale code directly in typed translation operations. The first applied translation creates the locale branch while preserving every existing locale.
9
11
  - To remove an existing survey language, load the `remove-survey-locale` operation contract and use that typed operation with the exact locale code. Do not delete translations one item at a time or remove the locale branch with raw JSON Patch.
10
- - Removing a locale deletes all respondent-facing survey and item translations stored under it. The final remaining locale cannot be removed.
12
+ - Removing a locale deletes all respondent-facing survey and item translations stored under it.
11
13
  - Never create a temporary item, placeholder text, blank title, or dummy translation merely to introduce a locale. Introduce it only through the real respondent-visible translations requested by the user.
12
14
  - Never put target-language respondent text into an existing source-language locale just because that locale already exists.
13
15
  - Coding keys and editor-only item labels are not respondent translations. Translate them only when the user explicitly asks.
14
16
 
15
17
  ## Scope A Complete Localization Correctly
16
18
 
17
- 1. Inspect the complete outline. Page it when needed; do not assume a compact outline is the entire survey.
18
- 2. Inspect each relevant item type/configuration to discover every respondent-visible content key. This includes question titles/subtitles/info copy, choice-option labels, form-field labels, select-option labels, embedded-form labels, validation copy, and respondent-facing navigation/card copy when present.
19
+ 1. Use `survey_inspect` with `action: "localization"`, the source locale, and the target locale. Page until `nextCursor` is absent; this covers existing respondent-visible item and survey translation surfaces without one item-details call per item.
20
+ 2. Inspect item configuration separately only when the localization surface result or an audit indicates that the source survey itself is missing a visible content key. This includes choice-option labels, form-field labels, select-option labels, embedded-form labels, and validation copy.
19
21
  3. Preserve the source language while writing each target-language value under the target locale. Do not replace source content or translation containers.
20
22
  4. Use `update-item-translation` for ordinary item content. Use typed choice operations only when also changing the choice structure. Use a focused raw patch only for a supported survey-level translation surface that has no typed operation.
21
23
  5. Before proposing, check that every visible label implied by the inspected item configuration has a target-locale translation. A title alone is not a complete localization of a choice or form item.
@@ -23,5 +25,6 @@ Use this reference when the user asks to translate, localize, add a language, or
23
25
  ## Bounded Execution
24
26
 
25
27
  - Prefer one atomic proposal for a coherent localization when it fits the advertised operation limit. The limit is a hard safety bound, not a target chunk size.
26
- - Split only an oversized localization into independent, coherent chunks by section or item set. Independent localization chunks may be prepared in the same turn; do not make a later chunk depend on an unapplied structural change.
28
+ - Split only an oversized localization into independent, coherent chunks by section or item set. Each successful chunk updates the request-scoped draft for the next inspection.
29
+ - After each chunk, call the localization inspection again with `missingOnly: true` and no cursor, because a draft change invalidates offsets into the previous missing-only result. Completion means it returns no remaining source surfaces for the target locale.
27
30
  - If live inspection or a source translation cannot determine a phrase accurately, ask a focused clarification rather than inventing domain-specific wording.
@@ -18,16 +18,17 @@ Use this reference when the user asks to implement, recreate, convert, import, o
18
18
  - Empty lines, blanks, underscores, table cells intended for handwriting, parenthetical "specify" prompts, and inline write-in areas in actual questions imply an input field. Model them as form fields or embedded option forms as appropriate.
19
19
  - Do not create respondent questions for front-cover study identifiers, barcodes, prefilled participant names, prefilled dates of birth, page numbers, institutional logos, or duplicate administrative fields when those values should come from digital participant metadata or are asked later as real survey questions.
20
20
  - Printed examples that demonstrate how to fill in a paper form should be preserved as instructional text when useful, not converted into real inputs.
21
- - Preserve question order, numbering intent, and section structure. For long sources, use multiple bounded mutation calls rather than omitting details. Each successful call automatically extends the same turn draft.
21
+ - Preserve question order, numbering intent, and section structure. For long sources, use multiple bounded mutation calls rather than omitting details. Bounded applies to each call, not the whole assistant turn; each successful call automatically extends the same turn draft.
22
22
  - Do not use representative sampling, "and similar items", broad paraphrase, or shortened tables for source-derived surveys unless the user explicitly asks for an abbreviated version. Repeated rows, repeated follow-ups, and long option sets still need to be modeled.
23
23
  - If the source is too long to hold comfortably in context, work by source/page/section chunks. For each chunk, make a complete implementation decision for every respondent-facing element before moving on.
24
- - Keep each source-import `survey_change` payload bounded. A good chunk is one source page/section or about 4-8 respondent items, including their options, fields, footnotes, and conditions. Continue with additional chunks instead of constructing one very large tool call.
24
+ - On a later continuation turn, load the original stored attachment before conversational recall. When the relevant location is known, request the exact one-based PDF page range and a short section/question focus; the complete original remains authoritative.
25
+ - Keep each source-import `survey_change` payload bounded. A good chunk is one source page/section or about 4-8 respondent items, including their options, fields, footnotes, and conditions. Continue with additional chunks in the same assistant turn while capacity remains instead of constructing one very large call or stopping to restate the plan. Task size alone is not a blocker.
25
26
 
26
27
  ## Item Mapping
27
28
 
28
29
  - Map supported item types directly. Use `choiceItem` for single choice, multiple choice, and scale-like questions until a dedicated scale item exists.
29
30
  - For scale questions, create an ordered `choiceItem` with stable option ids/keys and labels that preserve the endpoints and intermediate labels. Include the scale instruction in `subtitle` or `topContent` when it is not part of the actual question.
30
- - Use `formItem` for grouped personal data, tables of fields, repeated short inputs, dates, numbers, contact details, or unsupported compound controls.
31
+ - Use a simple `formItem` preset for a single text, long-text, number, slider, dropdown, date, or switch response. Use custom form mode for grouped personal data, tables, repeated inputs, contact details, or unsupported compound controls.
31
32
  - Prefer the supported semantic field type for the respondent value instead of copying the paper
32
33
  form's box layout. Use one `datepicker` with mode `year-month-day` for an ordinary full calendar
33
34
  date; use separate day/month/year fields only when the source measures those components
@@ -65,4 +66,5 @@ Use this reference when the user asks to implement, recreate, convert, import, o
65
66
  - 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.
66
67
  - 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.
67
68
  - 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.
68
- - 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 say what remains to continue.
69
+ - 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.
70
+ - 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.
@@ -1,5 +1,5 @@
1
- import { B as surveyDocumentVersionSchema, L as surveyAssistantSnapshotPayloadSchema } from "./protocol-DpCYmCjr.mjs";
2
- import { Q as createSurveyAssistantEngineContext } from "./engine-0AJrv0hI.mjs";
1
+ import { H as surveyDocumentVersionSchema, o as surveyAssistantApplyOutcomeSchema, z as surveyAssistantSnapshotPayloadSchema } from "./protocol-DATvkr1S.mjs";
2
+ import { Q as createSurveyAssistantEngineContext } from "./engine-CWTuN3o2.mjs";
3
3
  import { defaultSurveyAssistantCapabilitySet } from "./capabilities-default.mjs";
4
4
  import { MASTRA_RESOURCE_ID_KEY, MASTRA_THREAD_ID_KEY, RequestContext } from "@mastra/core/request-context";
5
5
  //#region src/server/request-context.ts
@@ -11,6 +11,10 @@ const parseSurveyAssistantPreviousSettledVersion = (value) => {
11
11
  if (value === void 0 || value === null) return null;
12
12
  return surveyDocumentVersionSchema.parse(value);
13
13
  };
14
+ const parseSurveyAssistantPreviousApplyOutcome = (value) => {
15
+ if (value === void 0 || value === null) return null;
16
+ return surveyAssistantApplyOutcomeSchema.parse(value);
17
+ };
14
18
  const deriveSurveyAssistantDocumentTransition = ({ current, previous }) => {
15
19
  if (!current) return void 0;
16
20
  if (!previous) return { status: "no-baseline" };
@@ -38,7 +42,7 @@ const deriveSurveyAssistantDocumentTransition = ({ current, previous }) => {
38
42
  capabilitiesChanged
39
43
  };
40
44
  };
41
- const buildSurveyAssistantRequestContext = ({ turnDraft, identity, snapshot, previousSettledVersion = null, trustedCapabilities = defaultSurveyAssistantCapabilitySet, attachmentAccess, modelAttachments = [], modelSelection }) => {
45
+ const buildSurveyAssistantRequestContext = ({ turnDraft, identity, snapshot, previousSettledVersion = null, trustedCapabilities = defaultSurveyAssistantCapabilitySet, attachmentAccess, modelAttachments = [], modelSelection, previousApplyOutcome }) => {
42
46
  const requestContext = new RequestContext();
43
47
  requestContext.set("invocation", { kind: "chat" });
44
48
  requestContext.set("turnId", turnDraft.turnId);
@@ -58,6 +62,7 @@ const buildSurveyAssistantRequestContext = ({ turnDraft, identity, snapshot, pre
58
62
  if (attachmentAccess && attachmentAccess.documents.length > 0) requestContext.set("attachmentAccess", attachmentAccess);
59
63
  if (modelAttachments.length > 0) requestContext.set("modelAttachments", modelAttachments);
60
64
  if (modelSelection) requestContext.set("modelSelection", modelSelection);
65
+ if (previousApplyOutcome) requestContext.set("previousApplyOutcome", previousApplyOutcome);
61
66
  if (!snapshot) return requestContext;
62
67
  const engineContext = createSurveyAssistantEngineContext(snapshot, trustedCapabilities);
63
68
  turnDraft.initialize(engineContext);
@@ -81,6 +86,6 @@ const requireSurveyAssistantTurnState = (requestContext) => {
81
86
  };
82
87
  };
83
88
  //#endregion
84
- export { parseSurveyAssistantSnapshot as a, parseSurveyAssistantPreviousSettledVersion as i, deriveSurveyAssistantDocumentTransition as n, requireSurveyAssistantTurnState as o, getSurveyAssistantEngineContext as r, buildSurveyAssistantRequestContext as t };
89
+ export { parseSurveyAssistantPreviousSettledVersion as a, parseSurveyAssistantPreviousApplyOutcome as i, deriveSurveyAssistantDocumentTransition as n, parseSurveyAssistantSnapshot as o, getSurveyAssistantEngineContext as r, requireSurveyAssistantTurnState as s, buildSurveyAssistantRequestContext as t };
85
90
 
86
- //# sourceMappingURL=request-context-BBzU3VdG.mjs.map
91
+ //# sourceMappingURL=request-context-BEjnaaFr.mjs.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"request-context-BEjnaaFr.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 {\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}\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":";;;;;AAmFA,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"}
@@ -1,5 +1,6 @@
1
- import { o as SurveyAssistantRequestContext, t as SURVEY_ASSISTANT_AGENT_ID } from "./constants-D-5m_KGB.mjs";
2
- import { n as surveyAssistantTools } from "./index-BcyfBeDj.mjs";
1
+ import { g as SurveyChangeSetShape } from "./lifecycle-DWv5CiSu.mjs";
2
+ import { o as SurveyAssistantRequestContext, t as SURVEY_ASSISTANT_AGENT_ID } from "./constants-DrGZXtQf.mjs";
3
+ import { n as surveyAssistantTools } from "./index-DZk20e3k.mjs";
3
4
  import * as _$_mastra_core_agent0 from "@mastra/core/agent";
4
5
  import { Agent, AgentConfig } from "@mastra/core/agent";
5
6
  import { Memory } from "@mastra/memory";
@@ -36,22 +37,13 @@ declare const createSurveyAssistantAgent: ({
36
37
  observationalMemory
37
38
  }: CreateSurveyAssistantAgentOptions) => Agent<"survey-assistant-agent", Readonly<{
38
39
  survey_inspect: _$_mastra_core_tools0.Tool<{
39
- action: "current-context" | "search-items" | "item-details" | "assets" | "raw-json";
40
- reason: unknown;
41
- scopes: unknown;
42
- query: unknown;
43
- itemRef: unknown;
44
- cursor: unknown;
45
- outlineMode: unknown;
46
- paths: unknown;
47
- includeChildren: unknown;
48
- includeItemConfig: unknown;
49
- limit: unknown;
50
- } | {
51
- action: "current-context" | "search-items" | "item-details" | "assets" | "raw-json";
40
+ action: "current-context" | "search-items" | "item-details" | "localization" | "assets" | "raw-json";
52
41
  reason?: string | undefined;
53
42
  scopes?: ("summary" | "selected-item" | "outline" | "response-slots" | "ui-context" | "history")[] | undefined;
54
43
  query?: string | undefined;
44
+ sourceLocale?: string | undefined;
45
+ targetLocale?: string | undefined;
46
+ missingOnly?: boolean | undefined;
55
47
  itemRef?: string | undefined;
56
48
  cursor?: string | undefined;
57
49
  outlineMode?: "full" | "focused" | "children" | undefined;
@@ -61,7 +53,7 @@ declare const createSurveyAssistantAgent: ({
61
53
  limit?: number | undefined;
62
54
  }, {
63
55
  ok: boolean;
64
- action: "current-context" | "search-items" | "item-details" | "assets" | "raw-json";
56
+ action: "current-context" | "search-items" | "item-details" | "localization" | "assets" | "raw-json";
65
57
  modelSummary: string;
66
58
  reason?: string | undefined;
67
59
  result?: unknown;
@@ -69,12 +61,12 @@ declare const createSurveyAssistantAgent: ({
69
61
  survey_change: _$_mastra_core_tools0.Tool<{
70
62
  summary: string;
71
63
  operations: unknown[];
72
- }, unknown, unknown, unknown, _$_mastra_core_tools0.ToolExecutionContext<unknown, unknown, unknown>, "survey_change", unknown>;
64
+ }, SurveyChangeSetShape, unknown, unknown, _$_mastra_core_tools0.ToolExecutionContext<unknown, unknown, unknown>, "survey_change", unknown>;
73
65
  survey_authoring_reference: _$_mastra_core_tools0.Tool<{
74
66
  topic: string;
75
67
  itemType?: string | undefined;
76
68
  operationKind?: string | undefined;
77
- detail?: "compact" | "full" | undefined;
69
+ detail?: "full" | "compact" | undefined;
78
70
  reason?: string | undefined;
79
71
  }, {
80
72
  ok: boolean;
@@ -83,7 +75,7 @@ declare const createSurveyAssistantAgent: ({
83
75
  content: string;
84
76
  itemType?: string | undefined;
85
77
  operationKind?: string | undefined;
86
- detail?: "compact" | "full" | undefined;
78
+ detail?: "full" | "compact" | undefined;
87
79
  }, unknown, unknown, _$_mastra_core_tools0.ToolExecutionContext<unknown, unknown, unknown>, "survey_authoring_reference", unknown>;
88
80
  survey_expression: _$_mastra_core_tools0.Tool<{
89
81
  action: "context" | "prepare";
@@ -92,15 +84,45 @@ declare const createSurveyAssistantAgent: ({
92
84
  includeRawLocations?: boolean | undefined;
93
85
  summary?: string | undefined;
94
86
  mutations?: Record<string, unknown>[] | undefined;
95
- }, unknown, unknown, unknown, _$_mastra_core_tools0.ToolExecutionContext<unknown, unknown, unknown>, "survey_expression", unknown>;
87
+ }, SurveyChangeSetShape | {
88
+ ok: boolean;
89
+ action: "context";
90
+ modelSummary: string;
91
+ listOrdering: Record<string, string>;
92
+ responseSlots: {
93
+ ref: string;
94
+ valueType?: string | undefined;
95
+ }[];
96
+ expressionLocations?: {
97
+ itemId: string;
98
+ key: string;
99
+ itemType: string;
100
+ rawIndex: number;
101
+ locations: string[];
102
+ }[] | undefined;
103
+ }, unknown, unknown, _$_mastra_core_tools0.ToolExecutionContext<unknown, unknown, unknown>, "survey_expression", unknown>;
96
104
  survey_attachment: _$_mastra_core_tools0.Tool<{
97
- documentIds: string[];
105
+ documentIds?: string[] | undefined;
106
+ documentRequests?: {
107
+ documentId: string;
108
+ pages?: {
109
+ start: number;
110
+ end: number;
111
+ } | undefined;
112
+ focus?: string | undefined;
113
+ }[] | undefined;
98
114
  }, {
99
115
  loaded: {
100
116
  id: string;
101
117
  filename: string;
102
118
  mediaType: string;
119
+ pages?: {
120
+ start: number;
121
+ end: number;
122
+ } | undefined;
123
+ focus?: string | undefined;
103
124
  }[];
125
+ warnings?: string[] | undefined;
104
126
  }, unknown, unknown, _$_mastra_core_tools0.ToolExecutionContext<unknown, unknown, unknown>, "survey_attachment", unknown>;
105
127
  survey_audit: _$_mastra_core_tools0.Tool<{
106
128
  sourceLocale?: string | undefined;
@@ -120,7 +142,7 @@ declare const createSurveyAssistantAgent: ({
120
142
  name?: string | null | undefined;
121
143
  filename?: string | null | undefined;
122
144
  alt?: string | null | undefined;
123
- }, unknown, unknown, unknown, _$_mastra_core_tools0.ToolExecutionContext<unknown, unknown, unknown>, "survey_asset", unknown>;
145
+ }, SurveyChangeSetShape, unknown, unknown, _$_mastra_core_tools0.ToolExecutionContext<unknown, unknown, unknown>, "survey_asset", unknown>;
124
146
  }>, undefined, SurveyAssistantRequestContext, _$_mastra_core_agent0.AgentEditorConfig | undefined>;
125
147
  //#endregion
126
148
  export { CreateSurveyAssistantAgentOptions, SURVEY_ASSISTANT_OBSERVATIONAL_MEMORY_DEFAULTS, SurveyAssistantObservationalMemoryOptions, createSurveyAssistantAgent, createSurveyAssistantObservationalMemoryOptions, surveyAssistantThreadAttachmentProcessor };
@@ -1 +1 @@
1
- {"version":3,"file":"server-agent.d.mts","names":[],"sources":["../src/server/agent.ts"],"mappings":";;;;;;;;;cAuBa,wCAAA,EAA0C,cAAA;AAAA,KAqPlD,0BAAA,GAA6B,WAAA,QACzB,yBAAA,SACA,oBAAA,aAEP,6BAAA;AAAA,KAGG,4BAAA,GAA+B,WAAA,CAClC,WAAA,CAAY,qBAAA,QAA6B,MAAA;AAAA,KAyC/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"}
1
+ {"version":3,"file":"server-agent.d.mts","names":[],"sources":["../src/server/agent.ts"],"mappings":";;;;;;;;;;cAwBa,wCAAA,EAA0C,cAAA;AAAA,KA4SlD,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"}