@zixt/host 0.0.102 → 0.0.103

package/dist/index.js

@@ -28,7 +28,7 @@ import { homedir as homedir3 } from "node:os";
 // package.json
 var package_default = {
   name: "@zixt/host",
-  version: "0.0.102",
+  version: "0.0.103",
   type: "module",
   exports: {
     ".": "./src/client.ts",
@@ -14672,6 +14672,8 @@ var ID_PREFIXES = {
   managerApiAction: "maa",
   /** One Manager-prepared Webhook Automation setup card (MG-21). */
   managerWebhookAction: "mwa",
+  /** One Manager-authored questionnaire waiting in a Conversation. */
+  managerQuestionnaire: "mqu",
   /** One Manager inference call's token-metering row (MG-8). */
   managerUsage: "mgu",
   /** One ordered Manager reply awaiting Slack delivery. */
@@ -14739,6 +14741,10 @@ var ManagerWebhookActionId = idSchema(
   ID_PREFIXES.managerWebhookAction,
   "Manager webhook action id"
 );
+var ManagerQuestionnaireId = idSchema(
+  ID_PREFIXES.managerQuestionnaire,
+  "Manager questionnaire id"
+);
 var ManagerEmailInboxId = idSchema(
   ID_PREFIXES.managerEmailInbox,
   "Manager email inbox id"
@@ -14982,7 +14988,9 @@ var MemberApprovalRequestContext = ApprovalRequestContext.extend({
 });
 var QuestionChoice = external_exports.object({
   label: external_exports.string().trim().min(1).max(120),
-  description: external_exports.string().trim().min(1).max(500).optional()
+  description: external_exports.string().trim().min(1).max(500).optional(),
+  /** At most one choice per question may carry this visual recommendation. */
+  recommended: external_exports.boolean().optional()
 }).strict();
 var QuestionChoices = external_exports.array(QuestionChoice).min(2).max(5).superRefine((choices, ctx) => {
   const labels = choices.map(({ label }) => label.toLocaleLowerCase());
@@ -14990,6 +14998,38 @@ var QuestionChoices = external_exports.array(QuestionChoice).min(2).max(5).super
     ctx.addIssue({ code: "custom", message: "question choice labels must be unique" });
   }
 });
+var QuestionnaireQuestion = external_exports.object({
+  /** Stable model-authored key used only to pair an answer with this snapshot. */
+  id: external_exports.string().trim().min(1).max(80),
+  question: external_exports.string().trim().min(1).max(500),
+  context: external_exports.string().trim().min(1).max(2e3).optional(),
+  /** False is A/B/C/D radio behavior; true permits several choices plus Other. */
+  allowMultiple: external_exports.boolean(),
+  choices: QuestionChoices
+}).strict().superRefine((question, ctx) => {
+  if (question.choices.filter((choice) => choice.recommended === true).length > 1) {
+    ctx.addIssue({
+      code: "custom",
+      path: ["choices"],
+      message: "a questionnaire question may have at most one recommended choice"
+    });
+  }
+});
+var Questionnaire = external_exports.object({
+  title: external_exports.string().trim().min(1).max(160).optional(),
+  questions: external_exports.array(QuestionnaireQuestion).min(1).max(4)
+}).strict().superRefine((questionnaire, ctx) => {
+  const ids = questionnaire.questions.map(({ id }) => id.toLocaleLowerCase());
+  if (new Set(ids).size !== ids.length) {
+    ctx.addIssue({ code: "custom", path: ["questions"], message: "question ids must be unique" });
+  }
+});
+var QuestionnaireAnswer = external_exports.object({
+  questionId: external_exports.string().trim().min(1).max(80),
+  selectedChoices: external_exports.array(external_exports.string().trim().min(1).max(120)).max(5),
+  other: external_exports.string().trim().min(1).max(1e4).optional()
+}).strict();
+var QuestionnaireAnswers = external_exports.array(QuestionnaireAnswer).min(1).max(4);
 var Approval = external_exports.object({
   id: ApprovalId,
   orgId: OrgId,
@@ -15002,6 +15042,10 @@ var Approval = external_exports.object({
   payload: external_exports.string().max(5e4),
   /** Present only when ask_user supplied a bounded multiple-choice question. */
   questionChoices: QuestionChoices.optional(),
+  /** Present when ask_user supplied one submit-once multi-question questionnaire. */
+  questionnaire: Questionnaire.optional(),
+  /** Exact submitted questionnaire response, once answered. */
+  questionnaireAnswers: QuestionnaireAnswers.optional(),
   status: ApprovalStatus,
   deliveryStatus: ApprovalDeliveryStatus,
   /** Why delivery became impossible; null while pending or after delivery. */
@@ -15038,7 +15082,8 @@ var ApprovalProjection = external_exports.discriminatedUnion("metadataRedacted",
 var ListApprovalsResponse = external_exports.object({ approvals: external_exports.array(ApprovalProjection) });
 var DecideApprovalRequest = external_exports.object({
   decision: external_exports.enum(["approve", "deny"]),
-  guidance: external_exports.string().max(1e4).optional()
+  guidance: external_exports.string().max(1e4).optional(),
+  questionnaireAnswers: QuestionnaireAnswers.optional()
 });
 var UpdateGuardrailsRequest = external_exports.object({ policy: GuardrailPolicy });
 
@@ -17999,7 +18044,9 @@ var ApprovalDecision = external_exports.object({
   /** Echo of the host-minted correlation id from approval.request. */
   requestId: external_exports.string(),
   decision: external_exports.enum(["approve", "deny"]),
-  guidance: external_exports.string().nullable()
+  guidance: external_exports.string().nullable(),
+  /** Exact structured response when the request carried a questionnaire. */
+  questionnaireAnswers: QuestionnaireAnswers.optional()
 });
 var ResolvedConnection = external_exports.object({
   connectionId: external_exports.string(),
@@ -18568,7 +18615,9 @@ var ApprovalRequest = external_exports.object({
   /** Concrete action payload rendered verbatim on the approval card (GR-3). */
   payload: external_exports.string().max(5e4),
   /** Optional structured answers for agent.question; absent means free text. */
-  questionChoices: QuestionChoices.optional()
+  questionChoices: QuestionChoices.optional(),
+  /** Optional submit-once questionnaire for agent.question. */
+  questionnaire: Questionnaire.optional()
 });
 var JournalAppend = external_exports.object({
   type: external_exports.literal("journal.append"),
@@ -19065,7 +19114,9 @@ var ConversationEventProjection = external_exports.discriminatedUnion("kind", [
     /** Present only for a generic API setup/invocation card; never credentials (MG-20). */
     apiActionId: ManagerApiActionId.nullable().optional(),
     /** Present only for a Webhook Automation secure setup card (MG-21). */
-    webhookActionId: ManagerWebhookActionId.nullable().optional()
+    webhookActionId: ManagerWebhookActionId.nullable().optional(),
+    /** Present only for a Manager-authored questionnaire (MG-22). */
+    questionnaireId: ManagerQuestionnaireId.nullable().optional()
   }).strict(),
   /** A mirrored child-Task event: what the teammate wrote or became. */
   external_exports.object({
@@ -19087,7 +19138,9 @@ var ConversationEventProjection = external_exports.discriminatedUnion("kind", [
      * render one outcome when recovery commits those records out of order.
      * Missing on legacy/non-terminal events.
      */
-    terminalGroup: external_exports.string().min(1).max(200).nullable().optional()
+    terminalGroup: external_exports.string().min(1).max(200).nullable().optional(),
+    /** Present when this teammate question has a structured answer card. */
+    approvalId: ApprovalId.nullable().optional()
   }).strict(),
   /** A Manager loop failure a person should see (provider outage, refusal). */
   external_exports.object({
@@ -19310,6 +19363,20 @@ var SubmitManagerWebhookActionRequest = external_exports.object({
   requestId: external_exports.uuid(),
   authentication: WebhookAuthenticationSetup
 }).strict();
+var ConversationQuestionnaireProjection = external_exports.object({
+  id: external_exports.union([ManagerQuestionnaireId, ApprovalId]),
+  conversationId: ConversationId,
+  source: external_exports.enum(["manager", "teammate"]),
+  taskId: TaskId.nullable(),
+  agentId: AgentId.nullable(),
+  questionnaire: Questionnaire,
+  status: external_exports.enum(["pending", "answered", "unavailable"]),
+  answers: QuestionnaireAnswers.nullable(),
+  unavailableReason: external_exports.string().max(2e3).nullable(),
+  createdAt: external_exports.string(),
+  answeredAt: external_exports.string().nullable()
+}).strict();
+var AnswerConversationQuestionnaireRequest = external_exports.object({ answers: QuestionnaireAnswers }).strict();
 var NonEmptyTaskRunnerSelection = TaskRunnerSelection.refine(
   (selection) => selection.type !== void 0 || selection.model !== void 0 || selection.effort !== void 0,
   "choose at least one runtime preference"
@@ -23916,7 +23983,7 @@ var HostClient = class _HostClient {
       const { provider: _provider, ...legacyGrant } = grant;
       return legacyGrant;
     };
-    const requestApproval = (category, summary, payload, questionChoices) => {
+    const requestApproval = (category, summary, payload, questionChoices, questionnaire) => {
       if (authorityController.signal.aborted) {
         return Promise.resolve({ approved: false, guidance: "task was cancelled" });
       }
@@ -23929,7 +23996,8 @@ var HostClient = class _HostClient {
         category: safe(category, 200),
         summary: safe(summary, 500),
         payload: safe(payload, 5e4),
-        ...questionChoices ? { questionChoices: [...questionChoices] } : {}
+        ...questionChoices ? { questionChoices: [...questionChoices] } : {},
+        ...questionnaire ? { questionnaire } : {}
       });
       return new Promise((resolve18) => {
         const waiters = this.approvalWaiters.get(cancelKey) ?? /* @__PURE__ */ new Map();
@@ -35985,7 +36053,7 @@ var CADENCE_PROPS = {
 var TOOLS = [
   {
     name: "ask_user",
-    description: "Ask the human supervising this task a question and wait for their answer. Use it whenever you need a decision, missing context, or plan approval before proceeding. When there are 2-5 concrete alternatives, provide them as choices; the person can still enter another answer. The answer arrives as text. For a credential, ask for the capability rather than the value: a Credential added under Resources reaches your next run as an environment variable and is scrubbed from everything you write, and a website sign-in belongs at the Browser panel. If the person chooses to send you a value here anyway, use it for this task and store it with set_secret if it should persist, but never print it, write it into a file you commit, or repeat it in your report.",
+    description: "Ask the human supervising this task a question and wait for their answer. Use it whenever you need a decision, missing context, or plan approval before proceeding. Use questions whenever there are concrete alternatives, including when there is only one decision: each question needs 2-5 choices, may permit multiple selections, and may mark one choice recommended. Do not ask the questions one at a time. The person can always enter another answer, and all submitted answers arrive together as text. Use question without choices only for a genuinely free-text answer. For a credential, ask for the capability rather than the value: a Credential added under Resources reaches your next run as an environment variable and is scrubbed from everything you write, and a website sign-in belongs at the Browser panel. If the person chooses to send you a value here anyway, use it for this task and store it with set_secret if it should persist, but never print it, write it into a file you commit, or repeat it in your report.",
     inputSchema: {
       type: "object",
       properties: {
@@ -36013,14 +36081,63 @@ var TOOLS = [
                 minLength: 1,
                 maxLength: 500,
                 description: "Optional consequence or detail that helps the person choose."
+              },
+              recommended: {
+                type: "boolean",
+                description: "True for the one choice you recommend; omit for all others."
               }
             },
             required: ["label"],
             additionalProperties: false
           }
+        },
+        title: {
+          type: "string",
+          minLength: 1,
+          maxLength: 160,
+          description: "Optional short heading when using questions."
+        },
+        questions: {
+          type: "array",
+          minItems: 1,
+          maxItems: 4,
+          description: "A submit-once questionnaire. Use instead of question/context/choices when several related answers are needed.",
+          items: {
+            type: "object",
+            properties: {
+              id: {
+                type: "string",
+                minLength: 1,
+                maxLength: 80,
+                description: "A unique stable key such as deployment_target."
+              },
+              question: { type: "string", minLength: 1, maxLength: 500 },
+              context: { type: "string", minLength: 1, maxLength: 2e3 },
+              allow_multiple: {
+                type: "boolean",
+                description: "True when the person may select several choices."
+              },
+              choices: {
+                type: "array",
+                minItems: 2,
+                maxItems: 5,
+                items: {
+                  type: "object",
+                  properties: {
+                    label: { type: "string", minLength: 1, maxLength: 120 },
+                    description: { type: "string", minLength: 1, maxLength: 500 },
+                    recommended: { type: "boolean" }
+                  },
+                  required: ["label"],
+                  additionalProperties: false
+                }
+              }
+            },
+            required: ["id", "question", "allow_multiple", "choices"],
+            additionalProperties: false
+          }
         }
       },
-      required: ["question"],
       additionalProperties: false
     }
   },
@@ -36652,7 +36769,8 @@ function createAskUserServer() {
         const args = rpc.params?.["arguments"] ?? {};
         if (surface.platform && name === "ask_user") {
           const question = typeof args["question"] === "string" ? args["question"] : "";
-          if (!question) {
+          const rawQuestions = args["questions"];
+          if (!question && !Array.isArray(rawQuestions)) {
             reply(200, {
               jsonrpc: "2.0",
               id: rpc.id ?? null,
@@ -36671,11 +36789,37 @@ function createAskUserServer() {
               );
               return;
             }
+            const rawQuestionnaire = Array.isArray(rawQuestions) ? {
+              ...typeof args["title"] === "string" ? { title: args["title"] } : {},
+              questions: rawQuestions.map((entry) => {
+                const candidate = typeof entry === "object" && entry !== null ? entry : {};
+                return {
+                  id: candidate["id"],
+                  question: candidate["question"],
+                  ...candidate["context"] === void 0 ? {} : { context: candidate["context"] },
+                  allowMultiple: candidate["allow_multiple"],
+                  choices: candidate["choices"]
+                };
+              })
+            } : void 0;
+            const parsedQuestionnaire = rawQuestionnaire === void 0 ? void 0 : Questionnaire.safeParse(rawQuestionnaire);
+            if (parsedQuestionnaire && !parsedQuestionnaire.success) {
+              toolText(
+                "Questions must contain 1-4 unique items, each with 2-5 unique choices and at most one recommendation.",
+                true
+              );
+              return;
+            }
+            if (parsedQuestionnaire?.success && (question || rawChoices !== void 0)) {
+              toolText("Use either question/choices or questions, not both.", true);
+              return;
+            }
             toolText(
               await handlers.askUser(
-                question,
+                question || parsedQuestionnaire?.data.title || parsedQuestionnaire?.data.questions[0].question || "A few questions",
                 context,
-                parsedChoices?.success ? parsedChoices.data : void 0
+                parsedChoices?.success ? parsedChoices.data : void 0,
+                parsedQuestionnaire?.success ? parsedQuestionnaire.data : void 0
               )
             );
           } catch (err) {
@@ -38489,14 +38633,15 @@ function createCliRunner(adapter, opts = {}) {
         throw new Error("prepared provider workspace does not match the task assignment");
       }
       const localMcpServers = askUserServer.register(runToken, {
-        askUser: async (question, context, choices) => {
+        askUser: async (question, context, choices, questionnaire) => {
           pendingAsks++;
           try {
             const decision = await task.requestApproval(
               "agent.question",
               question.slice(0, 500),
               (context || question).slice(0, MAX_APPROVAL_PAYLOAD),
-              choices
+              choices,
+              questionnaire
             );
             return decision.guidance ?? (decision.approved ? "Approved. Proceed." : "No. Do not proceed.");
           } finally {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zixt/host",
-  "version": "0.0.102",
+  "version": "0.0.103",
   "type": "module",
   "exports": {
     ".": "./src/client.ts",