@case-framework/survey-assistant 0.1.0

package/README.md

@@ -0,0 +1,212 @@
+# CASE Survey Assistant
+
+This workspace package exposes isolated protocol, engine, runtime, headless
+React, and optional localized UI entry points:
+
+```ts
+import {
+  surveyChangeSetSchema,
+  surveyAssistantTurnFinalSchema,
+  type SurveyChangeSet,
+} from "@case-framework/survey-assistant/protocol";
+
+import { buildCapabilityDigest } from "@case-framework/survey-assistant/protocol/digest";
+
+import {
+  createSurveyAssistantEngineContext,
+  validateSurveyOperations,
+} from "@case-framework/survey-assistant/engine";
+
+import {
+  defaultSurveyAssistantCapabilities,
+  defaultSurveyAssistantCapabilitySet,
+} from "@case-framework/survey-assistant/capabilities/default";
+
+import {
+  createSurveyAssistantChatHandler,
+  type SurveyAssistantAuthorize,
+} from "@case-framework/survey-assistant/server";
+
+import {
+  createSurveyAssistantAgent,
+  type SurveyAssistantHistoryCompatibility,
+} from "@case-framework/survey-assistant/server/agent";
+
+import {
+  SURVEY_ASSISTANT_TOOL_IDS,
+  surveyAssistantTools,
+} from "@case-framework/survey-assistant/server/tools";
+
+import {
+  createSurveyAssistantTaskAgent,
+  createSurveyAssistantTaskHandler,
+} from "@case-framework/survey-assistant/server/tasks";
+
+import {
+  createSurveyAssistantRuntime,
+  parseSurveyAssistantEnvironment,
+} from "@case-framework/survey-assistant/server/runtime";
+
+import {
+  createSurveyAssistantPostgresRuntime,
+  createSurveyAssistantPostgresThreadDocumentRepository,
+  initializeSurveyAssistantPostgresStorage,
+} from "@case-framework/survey-assistant/storage/postgres";
+
+import {
+  createSurveyAssistantControllerBridge,
+  createSurveyAssistantTaskClient,
+  createSurveyAssistantTaskExecutor,
+} from "@case-framework/survey-assistant/react/integration";
+
+import { useSurveyAssistantModelCatalog } from "@case-framework/survey-assistant/react";
+
+import {
+  ConnectedSurveyAssistantPanel,
+  SurveyAssistantPanel,
+} from "@case-framework/survey-assistant/ui";
+```
+
+`/protocol` is the browser-safe runtime owner for wire schemas and inferred
+types. `/protocol/digest` keeps stable hashing independently tree-shakeable for
+Survey UI consumers. `/engine` derives request-local survey context and owns
+pure inspection, normalization, validation/simulation, expression compilation,
+and turn collection. `/capabilities/default` provides the trusted, versioned
+capabilities for the standard CASE item registry.
+
+`/server` owns the lightweight framework-agnostic Web chat handler, required
+host authorization contract, request guardrails and context, thread-attachment
+repository and model-selected native replay, turn-final stream, error/metrics hooks, and packaged
+Markdown authoring references. `/server/tools` owns the standard
+request-context tools, and `/server/agent` owns their Agent,
+instructions, thread-scoped Observational Memory defaults, and optional
+history-compatibility policy for custom memory setups. `/server/runtime` is the
+high-level composition layer: it parses an injected environment, resolves the
+approved provider/model catalog (including optional Azure deployment
+discovery), exposes standard Mastra agents and gateways, and creates the Web
+handlers. The host still constructs the standard Mastra instance and owns
+credentials, authorization, storage connection lifecycle, logging, and route
+files.
+
+`/react` owns the headless chat session, threads, validated
+model-catalog loading, remembered model selection, and structural controller
+proxy. `/react/integration` is the lightweight controller and one-shot task
+entry for editor packages that do not need chat transport. `/ui` owns the
+reusable panel, transcript, reasoning/tool presentation, prompt and attachment
+controls, model picker, thread history, and complete English and Dutch defaults. `ConnectedSurveyAssistantPanel`
+also owns model-catalog loading and remembered selection for the common case. Import
+`@case-framework/survey-assistant/ui.css` once from the host root layout. The
+stylesheet has no preflight and scopes generated utilities beneath the panel
+root. A host can pass a partial localization catalog to extend or override the
+defaults without supplying a complete catalog.
+
+```tsx
+<ConnectedSurveyAssistantPanel
+  api="/api/survey-assistant/chat"
+  applyPolicy="auto"
+  controller={assistantController}
+  language={language}
+  localizations={assistantLocalizations}
+  onModelChange={setSelectedModelId}
+  resourceId={authenticatedUserId}
+  threadApi="/api/survey-assistant/threads"
+/>
+```
+
+The browser-supplied `resourceId` is request metadata, not authorization. A
+production host must derive user, survey, and thread ownership in the server
+handler's required `authorize` callback.
+
+`/protocol`, `/engine`, and `/capabilities/default` may not import React,
+Next.js, Mastra, AI SDK, `survey-ui`, or Node-only storage. `/protocol` has only
+Zod runtime dependencies; `/engine` may use `survey-core`. `/server` is
+server-only and may import Mastra, AI SDK, and Node APIs, but never React,
+Next.js, or `survey-ui`. The separate server entries prevent handler-only
+consumers from eagerly loading Agent/Memory code. `@case-framework/survey-ui`
+owns the optional live-editor bridge, snapshot/apply functions, and snapshot-backed
+one-shot provider because those functions must operate on its editor instance
+and item registry. The assistant package supplies the standard task Web handler
+and browser executor adapter, so another host does not need to recreate Next
+server actions or repeat the one-shot method mapping. This package never
+imports `survey-ui`.
+
+Custom item packages can define one capability implementation in a server-safe
+module and attach it to the UI entry:
+
+```ts
+// rating-capability.ts (safe to import on the server)
+import type { AssistantItemCapabilityAdapter } from "@case-framework/survey-assistant/engine";
+
+export const ratingAssistantCapability = {
+  manifest: {
+    itemType: "ratingQuestion",
+    capabilityVersion: "1",
+    displayName: "Rating question",
+    create: "deterministic",
+    supportedOperations: [
+      "create-item",
+      "update-item-key",
+      "update-item-translation",
+      "patch-item-config",
+    ],
+    contentSurfaces: [{ key: "title", role: "primary", format: "rich", requiredOnCreate: true }],
+    referenceTopics: ["rating-config"],
+    authoring: { configSummary: "Config has numeric min, max, and step fields." },
+  },
+  references: [
+    {
+      topic: "rating-config",
+      title: "Rating configuration",
+      markdown: "Use min < max and a positive step.",
+    },
+  ],
+} satisfies AssistantItemCapabilityAdapter;
+
+// rating-entry.tsx (client/editor module)
+import type { ItemRegistryEntry } from "@case-framework/survey-ui";
+
+export const ratingQuestionEntry = {
+  itemType: "ratingQuestion",
+  constructor: RatingQuestionItemCore,
+  renderComponent: RatingQuestionRenderer,
+  editorComponent: RatingQuestionEditor,
+  infos: ratingQuestionInfos,
+  getInitialItem: createInitialRatingQuestion,
+  assistantCapability: ratingAssistantCapability,
+} satisfies ItemRegistryEntry;
+```
+
+The composed editor registry validates and caches the attached capabilities
+once. Server configuration imports `ratingAssistantCapability` directly and
+adds it to the trusted capability set; it must not trust capability functions
+received from a browser snapshot.
+
+See [Custom item registration](../../docs/survey-assistant/survey-ui-bridge.md#custom-item-registration)
+for the complete editor and server composition example.
+
+```bash
+pnpm --filter @case-framework/survey-assistant check
+```
+
+This typechecks and builds all entries, copies server references, then verifies
+their source and built import graphs. The optional Postgres entry accepts a
+host-owned `PostgresStore` or store configuration; it does not read environment
+variables, create hidden singletons, or own connection shutdown.
+
+## Integration Levels
+
+Use the highest level that fits the host; the lower layers remain available for
+custom authentication, provider policy, UI, or storage.
+
+- **Standard server:** `parseSurveyAssistantEnvironment` plus
+  `createSurveyAssistantRuntime`, then register its `agents` and `gateways` in a
+  normal `Mastra` instance and call `runtime.createHandlers(...)`.
+- **Custom server:** compose `createSurveyAssistantAgent`, individual chat,
+  task, thread, and model handlers, and a custom `resolveModel` directly.
+- **Standard UI:** `ConnectedSurveyAssistantPanel` plus Survey UI's
+  `useSurveyEditorAssistantIntegration` bridge.
+- **Custom UI:** use `useSurveyAssistantSession`, thread/model clients from
+  `/react`, and controller/task adapters from `/react/integration`.
+
+The high-level APIs are thin composition helpers over the same exported
+primitives. They do not introduce a second runtime or hide Mastra.

package/dist/authoring-references-Cy8J-DWt.d.mts

@@ -0,0 +1,48 @@
+//#region src/server/authoring-references.d.ts
+declare const surveyAuthoringReferenceTopics: readonly ["core-rules", "survey-data-model", "source-material-surveys", "localization", "rich-text-content", "item-types", "embedded-forms", "expressions", "assistant-operations", "survey-quality"];
+type SurveyAuthoringReferenceTopic = (typeof surveyAuthoringReferenceTopics)[number];
+declare const surveyAuthoringReferences: {
+  readonly "core-rules": {
+    readonly title: "Core authoring rules";
+    readonly content: string;
+  };
+  readonly "survey-data-model": {
+    readonly title: "Survey data model";
+    readonly content: string;
+  };
+  readonly "source-material-surveys": {
+    readonly title: "Source-material survey implementation";
+    readonly content: string;
+  };
+  readonly localization: {
+    readonly title: "Survey localization";
+    readonly content: string;
+  };
+  readonly "rich-text-content": {
+    readonly title: "Rich text content";
+    readonly content: string;
+  };
+  readonly "item-types": {
+    readonly title: "Item types";
+    readonly content: string;
+  };
+  readonly "embedded-forms": {
+    readonly title: "Choice option embedded forms";
+    readonly content: string;
+  };
+  readonly expressions: {
+    readonly title: "Expressions";
+    readonly content: string;
+  };
+  readonly "assistant-operations": {
+    readonly title: "Assistant operations";
+    readonly content: string;
+  };
+  readonly "survey-quality": {
+    readonly title: "Survey quality review";
+    readonly content: string;
+  };
+};
+//#endregion
+export { surveyAuthoringReferenceTopics as n, surveyAuthoringReferences as r, SurveyAuthoringReferenceTopic as t };
+//# sourceMappingURL=authoring-references-Cy8J-DWt.d.mts.map

package/dist/authoring-references-Cy8J-DWt.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"authoring-references-Cy8J-DWt.d.mts","names":[],"sources":["../src/server/authoring-references.ts"],"mappings":";cAMa,8BAAA;AAAA,KAaD,6BAAA,WAAwC,8BAAA;AAAA,cAEvC,yBAAA;EAAA"}

package/dist/authoring-references-X6uRaWuf.mjs

@@ -0,0 +1,68 @@
+import path, { resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { readFileSync } from "node:fs";
+//#region ../../node_modules/.pnpm/tsdown@0.21.10_synckit@0.11.12_typescript@6.0.3/node_modules/tsdown/esm-shims.js
+const getFilename = () => fileURLToPath(import.meta.url);
+const getDirname = () => path.dirname(getFilename());
+const __dirname = /* @__PURE__ */ getDirname();
+//#endregion
+//#region src/server/authoring-references.ts
+const loadReference = (fileName) => readFileSync(resolve(__dirname, "references", fileName), "utf8").trim();
+const surveyAuthoringReferenceTopics = [
+	"core-rules",
+	"survey-data-model",
+	"source-material-surveys",
+	"localization",
+	"rich-text-content",
+	"item-types",
+	"embedded-forms",
+	"expressions",
+	"assistant-operations",
+	"survey-quality"
+];
+const surveyAuthoringReferences = {
+	"core-rules": {
+		title: "Core authoring rules",
+		content: loadReference("core-rules.md")
+	},
+	"survey-data-model": {
+		title: "Survey data model",
+		content: loadReference("survey-data-model.md")
+	},
+	"source-material-surveys": {
+		title: "Source-material survey implementation",
+		content: loadReference("source-material-surveys.md")
+	},
+	localization: {
+		title: "Survey localization",
+		content: loadReference("localization.md")
+	},
+	"rich-text-content": {
+		title: "Rich text content",
+		content: loadReference("rich-text-content.md")
+	},
+	"item-types": {
+		title: "Item types",
+		content: loadReference("item-types.md")
+	},
+	"embedded-forms": {
+		title: "Choice option embedded forms",
+		content: loadReference("embedded-forms.md")
+	},
+	expressions: {
+		title: "Expressions",
+		content: loadReference("expressions.md")
+	},
+	"assistant-operations": {
+		title: "Assistant operations",
+		content: loadReference("assistant-operations.md")
+	},
+	"survey-quality": {
+		title: "Survey quality review",
+		content: loadReference("survey-quality.md")
+	}
+};
+//#endregion
+export { surveyAuthoringReferences as n, surveyAuthoringReferenceTopics as t };
+
+//# sourceMappingURL=authoring-references-X6uRaWuf.mjs.map

package/dist/authoring-references-X6uRaWuf.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"authoring-references-X6uRaWuf.mjs","names":[],"sources":["../../../node_modules/.pnpm/tsdown@0.21.10_synckit@0.11.12_typescript@6.0.3/node_modules/tsdown/esm-shims.js","../src/server/authoring-references.ts"],"sourcesContent":["// Shim globals in esm bundle\nimport path from 'node:path'\nimport { fileURLToPath } from 'node:url'\n\nconst getFilename = () => fileURLToPath(import.meta.url)\nconst getDirname = () => path.dirname(getFilename())\n\nexport const __dirname = /* @__PURE__ */ getDirname()\nexport const __filename = /* @__PURE__ */ getFilename()\n","import { readFileSync } from \"node:fs\";\nimport { resolve } from \"node:path\";\n\nconst loadReference = (fileName: string) =>\n  readFileSync(resolve(__dirname, \"references\", fileName), \"utf8\").trim();\n\nexport const surveyAuthoringReferenceTopics = [\n  \"core-rules\",\n  \"survey-data-model\",\n  \"source-material-surveys\",\n  \"localization\",\n  \"rich-text-content\",\n  \"item-types\",\n  \"embedded-forms\",\n  \"expressions\",\n  \"assistant-operations\",\n  \"survey-quality\",\n] as const;\n\nexport type SurveyAuthoringReferenceTopic = (typeof surveyAuthoringReferenceTopics)[number];\n\nexport const surveyAuthoringReferences = {\n  \"core-rules\": {\n    title: \"Core authoring rules\",\n    content: loadReference(\"core-rules.md\"),\n  },\n  \"survey-data-model\": {\n    title: \"Survey data model\",\n    content: loadReference(\"survey-data-model.md\"),\n  },\n  \"source-material-surveys\": {\n    title: \"Source-material survey implementation\",\n    content: loadReference(\"source-material-surveys.md\"),\n  },\n  localization: {\n    title: \"Survey localization\",\n    content: loadReference(\"localization.md\"),\n  },\n  \"rich-text-content\": {\n    title: \"Rich text content\",\n    content: loadReference(\"rich-text-content.md\"),\n  },\n  \"item-types\": {\n    title: \"Item types\",\n    content: loadReference(\"item-types.md\"),\n  },\n  \"embedded-forms\": {\n    title: \"Choice option embedded forms\",\n    content: loadReference(\"embedded-forms.md\"),\n  },\n  expressions: {\n    title: \"Expressions\",\n    content: loadReference(\"expressions.md\"),\n  },\n  \"assistant-operations\": {\n    title: \"Assistant operations\",\n    content: loadReference(\"assistant-operations.md\"),\n  },\n  \"survey-quality\": {\n    title: \"Survey quality review\",\n    content: loadReference(\"survey-quality.md\"),\n  },\n} as const satisfies Record<SurveyAuthoringReferenceTopic, { title: string; content: string }>;\n"],"x_google_ignoreList":[0],"mappings":";;;;AAIA,MAAM,oBAAoB,cAAc,OAAO,KAAK,IAAI;AACxD,MAAM,mBAAmB,KAAK,QAAQ,aAAa,CAAC;AAEpD,MAAa,YAA4B,4BAAY;;;ACJrD,MAAM,iBAAiB,aACrB,aAAa,QAAQ,WAAW,cAAc,SAAS,EAAE,OAAO,CAAC,MAAM;AAEzE,MAAa,iCAAiC;CAC5C;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACD;AAID,MAAa,4BAA4B;CACvC,cAAc;EACZ,OAAO;EACP,SAAS,cAAc,gBAAgB;EACxC;CACD,qBAAqB;EACnB,OAAO;EACP,SAAS,cAAc,uBAAuB;EAC/C;CACD,2BAA2B;EACzB,OAAO;EACP,SAAS,cAAc,6BAA6B;EACrD;CACD,cAAc;EACZ,OAAO;EACP,SAAS,cAAc,kBAAkB;EAC1C;CACD,qBAAqB;EACnB,OAAO;EACP,SAAS,cAAc,uBAAuB;EAC/C;CACD,cAAc;EACZ,OAAO;EACP,SAAS,cAAc,gBAAgB;EACxC;CACD,kBAAkB;EAChB,OAAO;EACP,SAAS,cAAc,oBAAoB;EAC5C;CACD,aAAa;EACX,OAAO;EACP,SAAS,cAAc,iBAAiB;EACzC;CACD,wBAAwB;EACtB,OAAO;EACP,SAAS,cAAc,0BAA0B;EAClD;CACD,kBAAkB;EAChB,OAAO;EACP,SAAS,cAAc,oBAAoB;EAC5C;CACF"}

package/dist/capabilities-B6tvE7fK.mjs

@@ -0,0 +1,66 @@
+import { W as assistantItemTypeManifestSchema } from "./protocol-DV0ka9WT.mjs";
+import { buildCapabilityDigest } from "./digest.mjs";
+//#region src/engine/capabilities.ts
+const resolveAssistantCapabilityReference = ({ capabilities, itemType, topic }) => capabilities?.byItemType.get(itemType)?.references?.find((reference) => reference.topic === topic);
+const inspectAssistantItem = ({ capabilities, item }) => capabilities?.byItemType.get(item.itemType)?.inspectItem?.(item);
+const createSurveyAssistantCapabilities = (capabilities) => {
+	const byItemType = /* @__PURE__ */ new Map();
+	for (const capability of capabilities) {
+		const manifest = assistantItemTypeManifestSchema.parse(capability.manifest);
+		const itemType = manifest.itemType;
+		if (byItemType.has(itemType)) throw new Error(`Duplicate survey assistant capability for item type "${itemType}".`);
+		if (manifest.create === "deterministic" && !manifest.supportedOperations.includes("create-item")) throw new Error(`Deterministically creatable item type "${itemType}" must support "create-item".`);
+		const declaredReferenceTopics = new Set(manifest.referenceTopics ?? []);
+		for (const reference of capability.references ?? []) if (!declaredReferenceTopics.has(reference.topic)) throw new Error(`Capability reference "${reference.topic}" for item type "${itemType}" is missing from manifest.referenceTopics.`);
+		byItemType.set(itemType, capability);
+	}
+	const manifestWithoutDigest = { itemTypes: Array.from(byItemType.values()).map((capability) => capability.manifest).sort((left, right) => left.itemType.localeCompare(right.itemType)) };
+	return {
+		manifest: {
+			...manifestWithoutDigest,
+			digest: buildCapabilityDigest(manifestWithoutDigest)
+		},
+		byItemType
+	};
+};
+const getDeterministicCreateItemTypes = (manifest) => manifest.itemTypes.filter((entry) => entry.create === "deterministic").map((entry) => entry.itemType);
+const resolveAssistantItemCreation = ({ itemType, manifest, parentItemId }) => {
+	const capability = manifest.itemTypes.find((entry) => entry.itemType === itemType);
+	if (capability?.create === "deterministic") return { kind: "deterministic" };
+	if (capability?.create === "interactive-only") return {
+		kind: "ui-intent",
+		intent: {
+			kind: "open-create-item",
+			itemType,
+			parentItemId
+		}
+	};
+	return {
+		kind: "unsupported",
+		reason: capability ? `Item type "${itemType}" does not support assistant creation.` : `Item type "${itemType}" is not installed.`
+	};
+};
+const createUnsupportedItemCapability = ({ displayName, itemType }) => ({ manifest: {
+	itemType,
+	capabilityVersion: "unsupported-v1",
+	displayName,
+	create: "unsupported",
+	supportedOperations: [],
+	contentSurfaces: []
+} });
+var SurveyAssistantCapabilityMismatchError = class extends Error {
+	code = "survey-assistant-capability-mismatch";
+	constructor(message = "Survey assistant capabilities changed; start a fresh turn and retry.") {
+		super(message);
+		this.name = "SurveyAssistantCapabilityMismatchError";
+	}
+};
+const assertSurveyAssistantCapabilities = ({ manifest, trustedCapabilities, versionDigest }) => {
+	const { digest: claimedDigest, ...manifestWithoutDigest } = manifest;
+	if (claimedDigest !== buildCapabilityDigest(manifestWithoutDigest) || versionDigest !== claimedDigest) throw new SurveyAssistantCapabilityMismatchError();
+	if (trustedCapabilities && trustedCapabilities.manifest.digest !== claimedDigest) throw new SurveyAssistantCapabilityMismatchError("The editor and server use different survey assistant capabilities; refresh and retry.");
+};
+//#endregion
+export { getDeterministicCreateItemTypes as a, resolveAssistantItemCreation as c, createUnsupportedItemCapability as i, assertSurveyAssistantCapabilities as n, inspectAssistantItem as o, createSurveyAssistantCapabilities as r, resolveAssistantCapabilityReference as s, SurveyAssistantCapabilityMismatchError as t };
+
+//# sourceMappingURL=capabilities-B6tvE7fK.mjs.map

package/dist/capabilities-B6tvE7fK.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"capabilities-B6tvE7fK.mjs","names":[],"sources":["../src/engine/capabilities.ts"],"sourcesContent":["import type { RawSurveyItem, ValueType } from \"@case-framework/survey-core\";\nimport type {\n  AssistantItemTypeManifest,\n  JsonValue,\n  SurveyAssistantCapabilityManifest,\n  SurveyOperation,\n  SurveyValidationIssue,\n} from \"../protocol\";\nimport { assistantItemTypeManifestSchema } from \"../protocol\";\nimport { buildCapabilityDigest } from \"../protocol/digest\";\n\nexport interface AssistantCapabilityReference {\n  topic: string;\n  title?: string;\n  markdown: string;\n}\n\nexport interface AssistantItemInspection {\n  summary: string;\n  details?: JsonValue;\n}\n\nexport interface AssistantItemCapabilityAdapter {\n  manifest: AssistantItemTypeManifest;\n  references?: AssistantCapabilityReference[];\n  normalizeCreate?: (item: RawSurveyItem) => RawSurveyItem;\n  validateItem?: (item: RawSurveyItem) => SurveyValidationIssue[];\n  supportsOperation?: (operation: SurveyOperation) => boolean;\n  deriveResponseSlots?: (item: RawSurveyItem) => Record<string, ValueType>;\n  inspectItem?: (item: RawSurveyItem) => AssistantItemInspection;\n}\n\nexport interface SurveyAssistantCapabilitySet {\n  manifest: SurveyAssistantCapabilityManifest;\n  byItemType: ReadonlyMap<string, AssistantItemCapabilityAdapter>;\n}\n\nexport const resolveAssistantCapabilityReference = ({\n  capabilities,\n  itemType,\n  topic,\n}: {\n  capabilities: SurveyAssistantCapabilitySet | undefined;\n  itemType: string;\n  topic: string;\n}): AssistantCapabilityReference | undefined =>\n  capabilities?.byItemType\n    .get(itemType)\n    ?.references?.find((reference) => reference.topic === topic);\n\nexport const inspectAssistantItem = ({\n  capabilities,\n  item,\n}: {\n  capabilities: SurveyAssistantCapabilitySet | undefined;\n  item: RawSurveyItem;\n}): AssistantItemInspection | undefined =>\n  capabilities?.byItemType.get(item.itemType)?.inspectItem?.(item);\n\nexport type AssistantItemCreationResolution =\n  | { kind: \"deterministic\" }\n  | {\n      kind: \"ui-intent\";\n      intent: { kind: \"open-create-item\"; itemType: string; parentItemId?: string };\n    }\n  | { kind: \"unsupported\"; reason: string };\n\nexport const createSurveyAssistantCapabilities = (\n  capabilities: readonly AssistantItemCapabilityAdapter[],\n): SurveyAssistantCapabilitySet => {\n  const byItemType = new Map<string, AssistantItemCapabilityAdapter>();\n\n  for (const capability of capabilities) {\n    const manifest = assistantItemTypeManifestSchema.parse(capability.manifest);\n    const itemType = manifest.itemType;\n    if (byItemType.has(itemType)) {\n      throw new Error(`Duplicate survey assistant capability for item type \"${itemType}\".`);\n    }\n    if (\n      manifest.create === \"deterministic\" &&\n      !manifest.supportedOperations.includes(\"create-item\")\n    ) {\n      throw new Error(\n        `Deterministically creatable item type \"${itemType}\" must support \"create-item\".`,\n      );\n    }\n    const declaredReferenceTopics = new Set(manifest.referenceTopics ?? []);\n    for (const reference of capability.references ?? []) {\n      if (!declaredReferenceTopics.has(reference.topic)) {\n        throw new Error(\n          `Capability reference \"${reference.topic}\" for item type \"${itemType}\" is missing from manifest.referenceTopics.`,\n        );\n      }\n    }\n    byItemType.set(itemType, capability);\n  }\n\n  const itemTypes = Array.from(byItemType.values())\n    .map((capability) => capability.manifest)\n    .sort((left, right) => left.itemType.localeCompare(right.itemType));\n  const manifestWithoutDigest = { itemTypes };\n\n  return {\n    manifest: {\n      ...manifestWithoutDigest,\n      digest: buildCapabilityDigest(manifestWithoutDigest),\n    },\n    byItemType,\n  };\n};\n\nexport const getDeterministicCreateItemTypes = (\n  manifest: SurveyAssistantCapabilityManifest,\n): string[] =>\n  manifest.itemTypes\n    .filter((entry) => entry.create === \"deterministic\")\n    .map((entry) => entry.itemType);\n\nexport const resolveAssistantItemCreation = ({\n  itemType,\n  manifest,\n  parentItemId,\n}: {\n  itemType: string;\n  manifest: SurveyAssistantCapabilityManifest;\n  parentItemId?: string;\n}): AssistantItemCreationResolution => {\n  const capability = manifest.itemTypes.find((entry) => entry.itemType === itemType);\n  if (capability?.create === \"deterministic\") {\n    return { kind: \"deterministic\" };\n  }\n  if (capability?.create === \"interactive-only\") {\n    return {\n      kind: \"ui-intent\",\n      intent: { kind: \"open-create-item\", itemType, parentItemId },\n    };\n  }\n  return {\n    kind: \"unsupported\",\n    reason: capability\n      ? `Item type \"${itemType}\" does not support assistant creation.`\n      : `Item type \"${itemType}\" is not installed.`,\n  };\n};\n\nexport const createUnsupportedItemCapability = ({\n  displayName,\n  itemType,\n}: {\n  displayName: string;\n  itemType: string;\n}): AssistantItemCapabilityAdapter => ({\n  manifest: {\n    itemType,\n    capabilityVersion: \"unsupported-v1\",\n    displayName,\n    create: \"unsupported\",\n    supportedOperations: [],\n    contentSurfaces: [],\n  },\n});\n\nexport class SurveyAssistantCapabilityMismatchError extends Error {\n  readonly code = \"survey-assistant-capability-mismatch\";\n\n  constructor(message = \"Survey assistant capabilities changed; start a fresh turn and retry.\") {\n    super(message);\n    this.name = \"SurveyAssistantCapabilityMismatchError\";\n  }\n}\n\nexport const assertSurveyAssistantCapabilities = ({\n  manifest,\n  trustedCapabilities,\n  versionDigest,\n}: {\n  manifest: SurveyAssistantCapabilityManifest;\n  trustedCapabilities?: SurveyAssistantCapabilitySet;\n  versionDigest: string;\n}): void => {\n  const { digest: claimedDigest, ...manifestWithoutDigest } = manifest;\n  const computedDigest = buildCapabilityDigest(manifestWithoutDigest);\n  if (claimedDigest !== computedDigest || versionDigest !== claimedDigest) {\n    throw new SurveyAssistantCapabilityMismatchError();\n  }\n\n  if (trustedCapabilities && trustedCapabilities.manifest.digest !== claimedDigest) {\n    throw new SurveyAssistantCapabilityMismatchError(\n      \"The editor and server use different survey assistant capabilities; refresh and retry.\",\n    );\n  }\n};\n"],"mappings":";;;AAqCA,MAAa,uCAAuC,EAClD,cACA,UACA,YAMA,cAAc,WACX,IAAI,SAAS,EACZ,YAAY,MAAM,cAAc,UAAU,UAAU,MAAM;AAEhE,MAAa,wBAAwB,EACnC,cACA,WAKA,cAAc,WAAW,IAAI,KAAK,SAAS,EAAE,cAAc,KAAK;AAUlE,MAAa,qCACX,iBACiC;CACjC,MAAM,6BAAa,IAAI,KAA6C;AAEpE,MAAK,MAAM,cAAc,cAAc;EACrC,MAAM,WAAW,gCAAgC,MAAM,WAAW,SAAS;EAC3E,MAAM,WAAW,SAAS;AAC1B,MAAI,WAAW,IAAI,SAAS,CAC1B,OAAM,IAAI,MAAM,wDAAwD,SAAS,IAAI;AAEvF,MACE,SAAS,WAAW,mBACpB,CAAC,SAAS,oBAAoB,SAAS,cAAc,CAErD,OAAM,IAAI,MACR,0CAA0C,SAAS,+BACpD;EAEH,MAAM,0BAA0B,IAAI,IAAI,SAAS,mBAAmB,EAAE,CAAC;AACvE,OAAK,MAAM,aAAa,WAAW,cAAc,EAAE,CACjD,KAAI,CAAC,wBAAwB,IAAI,UAAU,MAAM,CAC/C,OAAM,IAAI,MACR,yBAAyB,UAAU,MAAM,mBAAmB,SAAS,6CACtE;AAGL,aAAW,IAAI,UAAU,WAAW;;CAMtC,MAAM,wBAAwB,EAAE,WAHd,MAAM,KAAK,WAAW,QAAQ,CAAC,CAC9C,KAAK,eAAe,WAAW,SAAS,CACxC,MAAM,MAAM,UAAU,KAAK,SAAS,cAAc,MAAM,SAAS,CAC3B,EAAE;AAE3C,QAAO;EACL,UAAU;GACR,GAAG;GACH,QAAQ,sBAAsB,sBAAsB;GACrD;EACD;EACD;;AAGH,MAAa,mCACX,aAEA,SAAS,UACN,QAAQ,UAAU,MAAM,WAAW,gBAAgB,CACnD,KAAK,UAAU,MAAM,SAAS;AAEnC,MAAa,gCAAgC,EAC3C,UACA,UACA,mBAKqC;CACrC,MAAM,aAAa,SAAS,UAAU,MAAM,UAAU,MAAM,aAAa,SAAS;AAClF,KAAI,YAAY,WAAW,gBACzB,QAAO,EAAE,MAAM,iBAAiB;AAElC,KAAI,YAAY,WAAW,mBACzB,QAAO;EACL,MAAM;EACN,QAAQ;GAAE,MAAM;GAAoB;GAAU;GAAc;EAC7D;AAEH,QAAO;EACL,MAAM;EACN,QAAQ,aACJ,cAAc,SAAS,0CACvB,cAAc,SAAS;EAC5B;;AAGH,MAAa,mCAAmC,EAC9C,aACA,gBAIqC,EACrC,UAAU;CACR;CACA,mBAAmB;CACnB;CACA,QAAQ;CACR,qBAAqB,EAAE;CACvB,iBAAiB,EAAE;CACpB,EACF;AAED,IAAa,yCAAb,cAA4D,MAAM;CAChE,OAAgB;CAEhB,YAAY,UAAU,wEAAwE;AAC5F,QAAM,QAAQ;AACd,OAAK,OAAO;;;AAIhB,MAAa,qCAAqC,EAChD,UACA,qBACA,oBAKU;CACV,MAAM,EAAE,QAAQ,eAAe,GAAG,0BAA0B;AAE5D,KAAI,kBADmB,sBAAsB,sBACT,IAAI,kBAAkB,cACxD,OAAM,IAAI,wCAAwC;AAGpD,KAAI,uBAAuB,oBAAoB,SAAS,WAAW,cACjE,OAAM,IAAI,uCACR,wFACD"}

package/dist/capabilities-DvSKtjAw.d.mts

@@ -0,0 +1,182 @@
+import { z } from "zod";
+
+//#region src/protocol/capabilities.d.ts
+declare const assistantItemCreateModeSchema: z.ZodEnum<{
+  deterministic: "deterministic";
+  "interactive-only": "interactive-only";
+  unsupported: "unsupported";
+}>;
+declare const assistantContentSurfaceSchema: z.ZodObject<{
+  key: z.ZodString;
+  role: z.ZodEnum<{
+    validation: "validation";
+    primary: "primary";
+    secondary: "secondary";
+    option: "option";
+    field: "field";
+  }>;
+  format: z.ZodEnum<{
+    plain: "plain";
+    rich: "rich";
+  }>;
+  requiredOnCreate: z.ZodOptional<z.ZodBoolean>;
+  pattern: z.ZodOptional<z.ZodBoolean>;
+  aliases: z.ZodOptional<z.ZodArray<z.ZodString>>;
+}, z.core.$strip>;
+declare const assistantResponseSlotSchema: z.ZodObject<{
+  key: z.ZodString;
+  valueType: z.ZodString;
+}, z.core.$strip>;
+declare const assistantItemAuthoringSchema: z.ZodObject<{
+  configSummary: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+declare const assistantItemTypeManifestSchema: z.ZodObject<{
+  itemType: z.ZodString;
+  capabilityVersion: z.ZodString;
+  displayName: z.ZodString;
+  description: z.ZodOptional<z.ZodString>;
+  defaultItemKeyPrefix: z.ZodOptional<z.ZodString>;
+  create: z.ZodEnum<{
+    deterministic: "deterministic";
+    "interactive-only": "interactive-only";
+    unsupported: "unsupported";
+  }>;
+  supportedOperations: z.ZodArray<z.ZodEnum<{
+    "create-item": "create-item";
+    "update-item-key": "update-item-key";
+    "update-item-label": "update-item-label";
+    "update-item-color": "update-item-color";
+    "update-item-translation": "update-item-translation";
+    "update-placed-image": "update-placed-image";
+    "patch-item-config": "patch-item-config";
+    "upsert-form-field-group": "upsert-form-field-group";
+    "remove-form-field-group": "remove-form-field-group";
+    "reorder-form-field-groups": "reorder-form-field-groups";
+    "upsert-form-field": "upsert-form-field";
+    "remove-form-field": "remove-form-field";
+    "move-form-field": "move-form-field";
+    "set-embedded-form": "set-embedded-form";
+    "remove-embedded-form": "remove-embedded-form";
+    "add-choice-option": "add-choice-option";
+    "update-choice-option-label": "update-choice-option-label";
+    "remove-choice-option": "remove-choice-option";
+    "reorder-choice-options": "reorder-choice-options";
+    "remove-item": "remove-item";
+    "move-item": "move-item";
+    "reorder-items": "reorder-items";
+    "update-survey-metadata": "update-survey-metadata";
+    "update-survey-pagination": "update-survey-pagination";
+    "update-survey-translation": "update-survey-translation";
+    "remove-survey-locale": "remove-survey-locale";
+    "set-image-asset": "set-image-asset";
+    "update-image-asset-metadata": "update-image-asset-metadata";
+    "remove-image-asset": "remove-image-asset";
+    "survey-json-patch": "survey-json-patch";
+  }>>;
+  contentSurfaces: z.ZodArray<z.ZodObject<{
+    key: z.ZodString;
+    role: z.ZodEnum<{
+      validation: "validation";
+      primary: "primary";
+      secondary: "secondary";
+      option: "option";
+      field: "field";
+    }>;
+    format: z.ZodEnum<{
+      plain: "plain";
+      rich: "rich";
+    }>;
+    requiredOnCreate: z.ZodOptional<z.ZodBoolean>;
+    pattern: z.ZodOptional<z.ZodBoolean>;
+    aliases: z.ZodOptional<z.ZodArray<z.ZodString>>;
+  }, z.core.$strip>>;
+  responseSlots: z.ZodOptional<z.ZodArray<z.ZodObject<{
+    key: z.ZodString;
+    valueType: z.ZodString;
+  }, z.core.$strip>>>;
+  referenceTopics: z.ZodOptional<z.ZodArray<z.ZodString>>;
+  authoring: z.ZodOptional<z.ZodObject<{
+    configSummary: z.ZodOptional<z.ZodString>;
+  }, z.core.$strip>>;
+}, z.core.$strip>;
+declare const surveyAssistantCapabilityManifestSchema: z.ZodObject<{
+  digest: z.ZodString;
+  itemTypes: z.ZodArray<z.ZodObject<{
+    itemType: z.ZodString;
+    capabilityVersion: z.ZodString;
+    displayName: z.ZodString;
+    description: z.ZodOptional<z.ZodString>;
+    defaultItemKeyPrefix: z.ZodOptional<z.ZodString>;
+    create: z.ZodEnum<{
+      deterministic: "deterministic";
+      "interactive-only": "interactive-only";
+      unsupported: "unsupported";
+    }>;
+    supportedOperations: z.ZodArray<z.ZodEnum<{
+      "create-item": "create-item";
+      "update-item-key": "update-item-key";
+      "update-item-label": "update-item-label";
+      "update-item-color": "update-item-color";
+      "update-item-translation": "update-item-translation";
+      "update-placed-image": "update-placed-image";
+      "patch-item-config": "patch-item-config";
+      "upsert-form-field-group": "upsert-form-field-group";
+      "remove-form-field-group": "remove-form-field-group";
+      "reorder-form-field-groups": "reorder-form-field-groups";
+      "upsert-form-field": "upsert-form-field";
+      "remove-form-field": "remove-form-field";
+      "move-form-field": "move-form-field";
+      "set-embedded-form": "set-embedded-form";
+      "remove-embedded-form": "remove-embedded-form";
+      "add-choice-option": "add-choice-option";
+      "update-choice-option-label": "update-choice-option-label";
+      "remove-choice-option": "remove-choice-option";
+      "reorder-choice-options": "reorder-choice-options";
+      "remove-item": "remove-item";
+      "move-item": "move-item";
+      "reorder-items": "reorder-items";
+      "update-survey-metadata": "update-survey-metadata";
+      "update-survey-pagination": "update-survey-pagination";
+      "update-survey-translation": "update-survey-translation";
+      "remove-survey-locale": "remove-survey-locale";
+      "set-image-asset": "set-image-asset";
+      "update-image-asset-metadata": "update-image-asset-metadata";
+      "remove-image-asset": "remove-image-asset";
+      "survey-json-patch": "survey-json-patch";
+    }>>;
+    contentSurfaces: z.ZodArray<z.ZodObject<{
+      key: z.ZodString;
+      role: z.ZodEnum<{
+        validation: "validation";
+        primary: "primary";
+        secondary: "secondary";
+        option: "option";
+        field: "field";
+      }>;
+      format: z.ZodEnum<{
+        plain: "plain";
+        rich: "rich";
+      }>;
+      requiredOnCreate: z.ZodOptional<z.ZodBoolean>;
+      pattern: z.ZodOptional<z.ZodBoolean>;
+      aliases: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    }, z.core.$strip>>;
+    responseSlots: z.ZodOptional<z.ZodArray<z.ZodObject<{
+      key: z.ZodString;
+      valueType: z.ZodString;
+    }, z.core.$strip>>>;
+    referenceTopics: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    authoring: z.ZodOptional<z.ZodObject<{
+      configSummary: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+  }, z.core.$strip>>;
+}, z.core.$strip>;
+type AssistantItemCreateMode = z.infer<typeof assistantItemCreateModeSchema>;
+type AssistantContentSurface = z.infer<typeof assistantContentSurfaceSchema>;
+type AssistantResponseSlot = z.infer<typeof assistantResponseSlotSchema>;
+type AssistantItemAuthoring = z.infer<typeof assistantItemAuthoringSchema>;
+type AssistantItemTypeManifest = z.infer<typeof assistantItemTypeManifestSchema>;
+type SurveyAssistantCapabilityManifest = z.infer<typeof surveyAssistantCapabilityManifestSchema>;
+//#endregion
+export { AssistantResponseSlot as a, assistantItemAuthoringSchema as c, assistantResponseSlotSchema as d, surveyAssistantCapabilityManifestSchema as f, AssistantItemTypeManifest as i, assistantItemCreateModeSchema as l, AssistantItemAuthoring as n, SurveyAssistantCapabilityManifest as o, AssistantItemCreateMode as r, assistantContentSurfaceSchema as s, AssistantContentSurface as t, assistantItemTypeManifestSchema as u };
+//# sourceMappingURL=capabilities-DvSKtjAw.d.mts.map

package/dist/capabilities-DvSKtjAw.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"capabilities-DvSKtjAw.d.mts","names":[],"sources":["../src/protocol/capabilities.ts"],"mappings":";;;cAGa,6BAAA,EAA6B,CAAA,CAAA,OAAA;;;;;cAM7B,6BAAA,EAA6B,CAAA,CAAA,SAAA;;;;;;;;;;;;;;;;;cAS7B,2BAAA,EAA2B,CAAA,CAAA,SAAA;;;;cAK3B,4BAAA,EAA4B,CAAA,CAAA,SAAA;;;cAI5B,+BAAA,EAA+B,CAAA,CAAA,SAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;cAc/B,uCAAA,EAAuC,CAAA,CAAA,SAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;KAKxC,uBAAA,GAA0B,CAAA,CAAE,KAAA,QAAa,6BAAA;AAAA,KACzC,uBAAA,GAA0B,CAAA,CAAE,KAAA,QAAa,6BAAA;AAAA,KACzC,qBAAA,GAAwB,CAAA,CAAE,KAAA,QAAa,2BAAA;AAAA,KACvC,sBAAA,GAAyB,CAAA,CAAE,KAAA,QAAa,4BAAA;AAAA,KACxC,yBAAA,GAA4B,CAAA,CAAE,KAAA,QAAa,+BAAA;AAAA,KAC3C,iCAAA,GAAoC,CAAA,CAAE,KAAA,QACzC,uCAAA"}

package/dist/capabilities-default.d.mts

@@ -0,0 +1,15 @@
+import { Ft as SurveyAssistantCapabilitySet, jt as AssistantItemCapabilityAdapter } from "./index-CUqbBjkc.mjs";
+
+//#region src/capabilities/default.d.ts
+declare const rootItemAssistantCapability: AssistantItemCapabilityAdapter;
+declare const groupItemAssistantCapability: AssistantItemCapabilityAdapter;
+declare const pageBreakItemAssistantCapability: AssistantItemCapabilityAdapter;
+declare const infoItemAssistantCapability: AssistantItemCapabilityAdapter;
+declare const choiceItemAssistantCapability: AssistantItemCapabilityAdapter;
+declare const formItemAssistantCapability: AssistantItemCapabilityAdapter;
+declare const defaultSurveyAssistantCapabilities: readonly [AssistantItemCapabilityAdapter, AssistantItemCapabilityAdapter, AssistantItemCapabilityAdapter, AssistantItemCapabilityAdapter, AssistantItemCapabilityAdapter, AssistantItemCapabilityAdapter];
+declare const defaultSurveyAssistantCapabilitySet: SurveyAssistantCapabilitySet;
+declare const getDefaultSurveyAssistantCapability: (itemType: string) => AssistantItemCapabilityAdapter | undefined;
+//#endregion
+export { choiceItemAssistantCapability, defaultSurveyAssistantCapabilities, defaultSurveyAssistantCapabilitySet, formItemAssistantCapability, getDefaultSurveyAssistantCapability, groupItemAssistantCapability, infoItemAssistantCapability, pageBreakItemAssistantCapability, rootItemAssistantCapability };
+//# sourceMappingURL=capabilities-default.d.mts.map

package/dist/capabilities-default.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"capabilities-default.d.mts","names":[],"sources":["../src/capabilities/default.ts"],"mappings":";;;cAqIa,2BAAA,EAA6B,8BAAA;AAAA,cAY7B,4BAAA,EAA8B,8BAAA;AAAA,cAqB9B,gCAAA,EAAkC,8BAAA;AAAA,cAqBlC,2BAAA,EAA6B,8BAAA;AAAA,cA4B7B,6BAAA,EAA+B,8BAAA;AAAA,cA4E/B,2BAAA,EAA6B,8BAAA;AAAA,cAuD7B,kCAAA,YAAkC,8BAAA,EAAA,8BAAA,EAAA,8BAAA,EAAA,8BAAA,EAAA,8BAAA,EAAA,8BAAA;AAAA,cASlC,mCAAA,EAEZ,4BAAA;AAAA,cAEY,mCAAA,GACX,QAAA,aACC,8BAAA"}