@primusclaw/personal-agent 0.5.0 → 0.6.0

package/dist/index.js

@@ -4029,7 +4029,18 @@ var assistantCardText = defineCatalog({
     minutesAgo: (p) => `${String(p.n)} min ago`,
     hoursAgo: (p) => `${String(p.n)} h ago`,
     daysAgo: (p) => `${String(p.n)} d ago`,
-    askedTitle: (p) => `Asked of others \xB7 ${String(p.n)}`
+    askedTitle: (p) => `Asked of others \xB7 ${String(p.n)}`,
+    choiceTitle: "Pick one",
+    choiceTitleMany: "Pick any that apply",
+    choiceSend: "Send",
+    choiceTyped: "You can also just reply in the chat.",
+    choiceNone: "Pick an option first, then press Send.",
+    choiceSent: (p) => `You picked: ${p.answer}`,
+    choiceGone: "This choice is no longer open. Reply in the chat instead.",
+    choiceSending: (p) => `Sending: ${p.answer}. If nothing comes back, reply in the chat instead.`,
+    choiceFailed: "That did not go through. Press Send again.",
+    /** How the options picked are joined into the person's message. */
+    choiceJoin: ", "
   },
   zh: {
     ...english2,
@@ -4066,7 +4077,17 @@ var assistantCardText = defineCatalog({
     minutesAgo: (p) => `${String(p.n)} \u5206\u949F\u524D`,
     hoursAgo: (p) => `${String(p.n)} \u5C0F\u65F6\u524D`,
     daysAgo: (p) => `${String(p.n)} \u5929\u524D`,
-    askedTitle: (p) => `\u8BF7\u522B\u4EBA\u505A\u7684\u4EE3\u5BA1 \xB7 ${String(p.n)}`
+    askedTitle: (p) => `\u8BF7\u522B\u4EBA\u505A\u7684\u4EE3\u5BA1 \xB7 ${String(p.n)}`,
+    choiceTitle: "\u8BF7\u9009\u62E9\u4E00\u9879",
+    choiceTitleMany: "\u53EF\u591A\u9009",
+    choiceSend: "\u53D1\u9001",
+    choiceTyped: "\u4E5F\u53EF\u4EE5\u76F4\u63A5\u5728\u804A\u5929\u91CC\u56DE\u590D\u3002",
+    choiceNone: "\u8BF7\u5148\u9009\u4E00\u9879\uFF0C\u518D\u70B9\u53D1\u9001\u3002",
+    choiceSent: (p) => `\u4F60\u9009\u4E86\uFF1A${p.answer}`,
+    choiceGone: "\u8FD9\u4E2A\u9009\u62E9\u5DF2\u7ECF\u5931\u6548\uFF0C\u8BF7\u76F4\u63A5\u5728\u804A\u5929\u91CC\u56DE\u590D\u3002",
+    choiceSending: (p) => `\u6B63\u5728\u53D1\u9001\uFF1A${p.answer}\u3002\u5982\u679C\u4E00\u76F4\u6CA1\u6709\u56DE\u5E94\uFF0C\u8BF7\u76F4\u63A5\u5728\u804A\u5929\u91CC\u56DE\u590D\u3002`,
+    choiceFailed: "\u6CA1\u6709\u53D1\u51FA\u53BB\uFF0C\u8BF7\u518D\u70B9\u4E00\u6B21\u53D1\u9001\u3002",
+    choiceJoin: "\u3001"
   }
 });
 var ASKED_VERDICT = {
@@ -6076,6 +6097,19 @@ function deliveryLine(delivery, url) {
   return turnEnglish.deliveryLine(plain(delivery.name), sizeText(delivery.size), caption, url);
 }
 
+// packages/core/src/language/chosen.ts
+function chosenLang(prefs) {
+  if (!prefs.langSet) return void 0;
+  return prefs.lang === "zh" || prefs.lang === "en" ? prefs.lang : void 0;
+}
+function replyLanguageContext(prefs) {
+  const lang = chosenLang(prefs);
+  return lang === void 0 ? {} : { reply_language: lang };
+}
+function replyLanguageLine(lang) {
+  return `[Reply language: ${lang === "zh" ? "Chinese" : "English"}]`;
+}
+
 // packages/core/src/language/detect.ts
 var CJK2 = /[㐀-䶿一-鿿豈-﫿]/u;
 function hasCjk2(text8) {
@@ -6209,9 +6243,13 @@ ${text8}` : quote || text8;
 function messageOf(ctx) {
   const said2 = withQuote(ctx.request.sent || ctx.request.text, ctx.request.quote ?? "");
   const note = ctx.record.filesNote;
-  return said2 && note ? `${said2}
+  const message = said2 && note ? `${said2}
 
 ${note}` : said2 || note;
+  const chosen = ctx.request.replyLang;
+  return message && chosen !== void 0 ? `${message}
+
+${replyLanguageLine(chosen)}` : message;
 }
 
 // packages/core/src/locales/claw.ts
@@ -8837,6 +8875,7 @@ var TurnEngine = class {
       quote: run.quote,
       sent: run.sent,
       lang: run.lang,
+      ...run.replyLang === void 0 ? {} : { replyLang: run.replyLang },
       files: run.files,
       ...review ? reviewRequest(review) : {}
     };
@@ -10275,7 +10314,7 @@ var CHAT_ENTRIES = [
     category: "chat",
     zh: "\u8981\u4F60\u62CD\u677F\u65F6\u6211\u53D1\u5361\u7247\uFF1A\u70B9\u6309\u94AE\u56DE\u7B54\u3001\u6279\u51C6\u6216\u62D2\u7EDD",
     en: "When I need you, I send a card: tap to answer, approve or deny",
-    covers: ["card:decision", "card:answer", "card:assistant_action"],
+    covers: ["card:decision", "card:answer", "card:assistant_action", "card:assistant_choice"],
     where: "both"
   }),
   capability({
@@ -13206,11 +13245,12 @@ var PersonalRouter = class {
     const { assistant, remote } = this.ctx.deps;
     const userId = chat.sender.id;
     const understood = assistant.understands(userId);
-    const switching = understood && remote.enabled && switchCommand(message.text) !== null;
-    const forAssistant = understood && !exactCommand(message.text, { menuCommand, isKnownCommand }) && !switching;
-    const text8 = understood ? menuCommand(message.text) : this.text.textOf(message);
+    const choice = message.choice === true;
+    const switching = understood && !choice && remote.enabled && switchCommand(message.text) !== null;
+    const forAssistant = understood && (choice || !exactCommand(message.text, { menuCommand, isKnownCommand })) && !switching;
+    const text8 = understood && !choice ? menuCommand(message.text) : this.text.textOf(message);
     learnLang(this.ctx.deps.store, userId, message.text);
-    if (await this.beforeCredential(message, chat, text8, forAssistant)) return;
+    if (!choice && await this.beforeCredential(message, chat, text8, forAssistant)) return;
     const key = await this.ctx.credentials.credential(chat, true);
     if (key === void 0) return;
     if (forAssistant && !this.text.talksToAgent(message)) await this.text.understand(message, chat, key);
@@ -13306,7 +13346,7 @@ var GroupRemote = class {
     const { remote } = this.ctx.deps;
     const bound = this.chatOf(chat);
     const attached = remote.attached(bound.id);
-    const args = this.agentArgs(words3.text, attached);
+    const args = message.choice === true ? null : this.agentArgs(words3.text, attached);
     const provider = this.ctx.credentials.provider(chat.sender.id, key);
     if (args !== null) {
       const parsed = parseAgentCommand(args);
@@ -13327,11 +13367,12 @@ var GroupRemote = class {
     const { remote } = this.ctx.deps;
     const bound = this.chatOf(chat);
     const provider = this.ctx.credentials.provider(chat.sender.id, key);
-    if (naturalCommand(words3.text) === "/stop" || parseCommand(words3.text) === "stop") {
+    const choice = message.choice === true;
+    if (!choice && (naturalCommand(words3.text) === "/stop" || parseCommand(words3.text) === "stop")) {
       await remote.stop(bound, key, chat.conversation);
       return true;
     }
-    if (parseCommand(words3.text) !== null) return false;
+    if (!choice && parseCommand(words3.text) !== null) return false;
     let quote = words3.quote;
     if (remote.windowMode(bound.id) === "card") {
       if (!remote.quotesWindow(bound.id, message)) return false;
@@ -13552,7 +13593,8 @@ async function answerWaitingQuestion(ctx, reply) {
     questions: questions.length,
     card: pending.cardId ? "edited" : "not editable"
   });
-  await settleCard(ctx, chat, pending.cardId, [...answers.answers], pickLang2(reply.text, questions[0]?.question));
+  const lang = answerLang(store.prefs.getPrefs(chat.sender.id).lang, chat.locale, questions[0]?.question, reply.text);
+  await settleCard(ctx, chat, pending.cardId, [...answers.answers], lang);
   return true;
 }
 function waitingQuestion(ctx, reply) {
@@ -13621,7 +13663,8 @@ var TurnStarter = class {
     return Promise.all([...this.running]).then(() => void 0);
   }
   /** The turn that runs (its end is `done`), or undefined when none was started (the person was told why). */
-  async start(request) {
+  async start(started) {
+    const request = { ...started, ...this.replyLang(started) };
     const { chat, review } = request;
     if (await this.answersQuestion(request)) return void 0;
     const key = review ? reviewTurnKey(chat.sender.id, chat.scope, review.itemId, review.pull) : chatTurnKey(chat.sender.id, chat.scope);
@@ -13778,11 +13821,18 @@ var TurnStarter = class {
       sent: request.sent ?? "",
       files: request.files ?? [],
       lang: review?.lang ?? chat.lang(),
+      ...request.replyLang === void 0 ? {} : { replyLang: request.replyLang },
       ownThumbs: this.ownThumbs(request),
       notifies: this.ctx.deps.subscriptions !== void 0 && store.notifySubs.getNotifySub(chat.sender.id) !== null,
       review: review?.fields
     };
   }
+  /** The language the sender chose to be answered in, for a chat turn (a review's answer follows its request's language). */
+  replyLang(request) {
+    if (request.review !== void 0) return {};
+    const lang = chosenLang(this.ctx.deps.store.prefs.getPrefs(request.chat.sender.id));
+    return lang === void 0 ? {} : { replyLang: lang };
+  }
   hooks(request, run, turn, turnId) {
     const { review, chat } = request;
     const store = this.ctx.deps.store;
@@ -13866,9 +13916,11 @@ var PersonalText = class {
   starter;
   /**
    * What the person wrote, with a word of the commands menu read as its command and a sentence help teaches read as the
-   * command it means; a sentence for what this chat cannot do right now stays words.
+   * command it means; a sentence for what this chat cannot do right now stays words. A choice picked on the assistant's card
+   * is the words picked, never a command.
    */
   textOf(message, group = false) {
+    if (message.choice === true) return message.text;
     const { github, assistant, remote, config } = this.ctx.deps;
     const userId = group ? void 0 : message.sender.id;
     const on = (test) => userId !== void 0 && test(userId);
@@ -13894,6 +13946,10 @@ var PersonalText = class {
   }
   async onText(message, chat, key) {
     const text8 = this.textOf(message);
+    if (message.choice === true) {
+      await this.sentOn(message, chat, key);
+      return;
+    }
     if (parseCommand(text8) === "unlink" && !message.text.startsWith("/")) {
       await chat.say(routingText.in(chat.lang()).unlinkAsk);
       return;
@@ -13945,7 +14001,7 @@ var PersonalText = class {
     const sent = messageText.withLinks(text8, message);
     const prompt = messageText.withQuote(sent, quote);
     const files = await this.attachments(message, chat, toAgent);
-    const control = this.sessionControl(userId, prompt, toAgent, quote, files, text8);
+    const control = message.choice !== true && this.sessionControl(userId, prompt, toAgent, quote, files, text8);
     if (control && assistant.understands(userId)) {
       await this.understand(message, chat, key);
     } else if (prompt && toAgent && !control) {
@@ -14158,7 +14214,8 @@ var GroupRouter = class {
   async message(message, chat) {
     const words3 = this.words(message);
     learnLang(this.ctx.deps.store, chat.sender.id, message.text);
-    if (await this.groupOwn(message, chat, words3)) return;
+    const choice = message.choice === true;
+    if (!choice && await this.groupOwn(message, chat, words3)) return;
     const route = {
       sender: chat.sender,
       conversation: chat.conversation,
@@ -14167,10 +14224,13 @@ var GroupRouter = class {
       message,
       text: words3.text
     };
-    for (const interceptor of this.ctx.deps.handlers.groupInterceptors) if (await interceptor.intercept(route)) return;
+    if (!choice) {
+      for (const interceptor of this.ctx.deps.handlers.groupInterceptors)
+        if (await interceptor.intercept(route)) return;
+    }
     const key = await this.ctx.credentials.credential(chat, false);
     if (key === void 0) {
-      const keep = parseCommand(words3.text) === null;
+      const keep = choice || parseCommand(words3.text) === null;
       await this.onboarding.member(message, chat, { ...words3, keep, identity: false });
       return;
     }
@@ -14213,7 +14273,7 @@ var GroupRouter = class {
     return !(word2 === "/agent" && remoteOn && (verb === "attach" || verb === "detach"));
   }
   async withKey(message, chat, key, words3) {
-    const command = parseCommand(words3.text);
+    const command = message.choice === true ? null : parseCommand(words3.text);
     if (command === "new") await this.sessions.new(chat, chat.scope);
     else if (command === "stop") await this.sessions.stop(chat, key, chat.scope);
     else if (command === "whoami") await this.whoami(chat, key);
@@ -14517,7 +14577,7 @@ var Router = class _Router {
    */
   async withinRate(message, chat) {
     const group = message.conversation.kind === "group";
-    if (group && !message.mentioned || _Router.isStop(message.text, group)) return true;
+    if (group && !message.mentioned || message.choice !== true && _Router.isStop(message.text, group)) return true;
     const { limits, securityEvent, metrics } = this.ctx.deps;
     const verdict = limits.checkMessage(chat.sender.id);
     if (verdict.allowed) return true;
@@ -15539,6 +15599,10 @@ var AssistantChat = class {
   filesOnly(lang) {
     return assistantChatText.in(lang).filesOnly;
   }
+  /** The language the person chose to be answered in, as the message's `channel_context` carries it (none: nothing is sent). */
+  chosenLanguage(userId) {
+    return replyLanguageContext(this.o.store.prefs.getPrefs(userId));
+  }
   langOf(userId, text8) {
     return answerLang(this.o.store.prefs.getPrefs(userId).lang, this.o.clientLocale?.() ?? "", text8);
   }
@@ -15558,10 +15622,11 @@ var AssistantChat = class {
     const handing = { ...request };
     const sent = await this.handTo(handing, async (sessionId, ready) => {
       const folderId = typeof request.context["channel_message_id"] === "string" ? request.context["channel_message_id"] : "";
-      const context2 = request.files.length ? {
+      const context2 = {
         ...request.context,
-        files: await this.handOverFiles(handing, sessionId, folderId || this.o.random.hexId(), request.files)
-      } : request.context;
+        ...request.files.length ? { files: await this.handOverFiles(handing, sessionId, folderId || this.o.random.hexId(), request.files) } : {},
+        ...this.chosenLanguage(request.userId)
+      };
       await ready();
       return this.o.claw.assistant.send(request.credential, sessionId, request.prompt, {
         ...request.modelKey ? { modelKey: request.modelKey } : {},
@@ -15633,7 +15698,7 @@ var AssistantChat = class {
       async (_sessionId, ready) => {
         const files = request.files.length ? { files: await this.handOverFiles(handing, sessionId, this.o.random.hexId(), request.files) } : {};
         const attached = request.attached === void 0 ? {} : { attached: attachedOf(request.attached) };
-        const context2 = { ...files, ...attached };
+        const context2 = { ...files, ...attached, ...this.chosenLanguage(request.userId) };
         await ready();
         return this.o.claw.assistant.send(request.credential, sessionId, request.prompt, {
           ...Object.keys(context2).length ? { context: context2 } : {},
@@ -16134,6 +16199,117 @@ var AssistantActions = class {
   }
 };
 
+// packages/core/src/assistant/choice-clicks.ts
+var CHOICE_VERB = "assistant_choice";
+var CHOICE_INPUT = "choice";
+function pickedOn(card, value) {
+  const places = new Set(
+    pyStr(value).split(",").map((p) => p.trim()).filter((p) => /^\d{1,2}$/.test(p)).map(Number)
+  );
+  return card.options.filter((_, i) => places.has(i));
+}
+function typedMessage(click, text8, id) {
+  const { action } = click;
+  return {
+    type: "message",
+    id,
+    sender: click.sender,
+    conversation: action.conversation,
+    locale: action.locale,
+    clientPlatform: action.clientPlatform,
+    text: text8,
+    mentioned: action.conversation.kind !== "personal",
+    targeted: false,
+    namesBotFirst: false,
+    conversationName: "",
+    mentions: [],
+    links: [],
+    quotes: [],
+    files: [],
+    unreadableFiles: [],
+    provenance: "typed",
+    choice: true
+    // (an option that is a menu word or a help phrase is an answer, never that command)
+  };
+}
+function langOf3(card, click) {
+  if (card?.lang === "zh" || card?.lang === "en") return card.lang;
+  return click.lang();
+}
+var AssistantChoiceClicks = class {
+  constructor(deps) {
+    this.deps = deps;
+  }
+  deps;
+  verbs = [CHOICE_VERB];
+  /** A 1:1 chat: answered with no Claw key (the message it sends is checked as any typed one is). */
+  async beforeCredential(click) {
+    await this.press(click);
+    return true;
+  }
+  async inGroup(click) {
+    await this.press(click);
+    return true;
+  }
+  async press(click) {
+    const buttons2 = this.deps.store.assistantButtons;
+    const card = buttons2.getChoiceCard(pyStr(click.action.data["card"]));
+    const lang = langOf3(card, click);
+    const t4 = assistantCardText.in(lang);
+    if (card === null || click.conversation.ref.kind === "personal" && card.userId !== click.sender.id) {
+      await finish(click, t4.choiceGone);
+      return;
+    }
+    if (card.state === "done") {
+      await this.sent(click, card, card.chosen, lang, false);
+      return;
+    }
+    if (card.state !== "open") {
+      await click.settle(t4.choiceSending({ answer: card.chosen.join(t4.choiceJoin) }), { announce: false });
+      return;
+    }
+    const chosen = pickedOn(card, click.action.data[CHOICE_INPUT]);
+    if (!chosen.length || !card.multiple && chosen.length > 1) {
+      await this.again(click, card, lang, t4.choiceNone);
+      return;
+    }
+    if (!buttons2.claimChoiceCard(card.cardId, chosen)) {
+      const now = buttons2.getChoiceCard(card.cardId) ?? card;
+      if (now.state === "done") await this.sent(click, now, now.chosen, lang, false);
+      else await click.settle(t4.choiceSending({ answer: now.chosen.join(t4.choiceJoin) }), { announce: false });
+      return;
+    }
+    const text8 = chosen.join(t4.choiceJoin);
+    try {
+      await this.deps.deliver(typedMessage(click, text8, `${CHOICE_VERB}:${card.cardId}`));
+    } catch (error) {
+      buttons2.moveChoiceCard(card.cardId, "open", { onlyFrom: "busy" });
+      this.deps.logger.warn("a choice could not be sent; its card is given back", { error: errorName(error) });
+      await this.again(click, card, lang, t4.choiceFailed);
+      return;
+    }
+    buttons2.moveChoiceCard(card.cardId, "done", { onlyFrom: "busy" });
+    await this.sent(click, card, chosen, lang, true);
+  }
+  /** The card back, open, with `note` under its options. */
+  async again(click, card, lang, note) {
+    const model = { ...this.model(card, lang), note };
+    await click.settle(viewMessage2({ name: "choiceCard", model }), { announce: false });
+  }
+  /** The card replaced by what was picked and sent (said as a line too when `announce`). */
+  async sent(click, card, chosen, lang, announce) {
+    const t4 = assistantCardText.in(lang);
+    const view7 = viewMessage2({ name: "choiceChosen", model: { text: card.text, chosen, lang } });
+    await click.settle(
+      view7,
+      announce ? { fallback: t4.choiceSent({ answer: chosen.join(t4.choiceJoin) }) } : { announce: false }
+    );
+  }
+  model(card, lang) {
+    return { text: card.text, cardId: card.cardId, options: card.options, multiple: card.multiple, note: "", lang };
+  }
+};
+
 // packages/core/src/assistant/auto-reply.ts
 function answersUnasked(watch) {
   return watch["state"] === "active" && watch["reply_allowed"] === true;
@@ -17142,6 +17318,24 @@ function suggestedRepliesOf(event, text8, styleOn, lang) {
   if (replies.length) return replies.slice(0, SUGGESTIONS_MAX);
   return [...ASSISTANT_SUGGESTED_REPLIES[lang ?? pickLang2(text8)]];
 }
+var CHOICE_OPTIONS_MIN = 2;
+var CHOICE_OPTIONS_MAX = 10;
+var CHOICE_OPTION_MAX = 80;
+function choiceOf(event) {
+  const choice = record2(event["choices"]);
+  if (event["type"] !== "assistant.say" || choice === void 0) return void 0;
+  const raw = choice["options"];
+  if (!Array.isArray(raw)) return void 0;
+  const options = [];
+  for (const entry of raw) {
+    if (typeof entry !== "string" || /[\u0000-\u001f\u007f\u2028\u2029]/u.test(entry)) return void 0;
+    const option = pySplit(entry).join(" ");
+    if (!option || cpLength(option) > CHOICE_OPTION_MAX) return void 0;
+    if (!options.includes(option)) options.push(option);
+  }
+  if (options.length < CHOICE_OPTIONS_MIN || options.length > CHOICE_OPTIONS_MAX) return void 0;
+  return { options, multiple: choice["multiple"] === true };
+}
 var REMOTE_KINDS = /* @__PURE__ */ new Set(["done", "needs_you", "error", "resolved"]);
 function resolvedOf(remote) {
   const resolved = record2(remote["resolved"]);
@@ -17278,14 +17472,19 @@ ${text8}`;
     return all.length ? [...said2.slice(0, -1), { ...last, suggestions: toReplies(all.slice(0, SUGGESTIONS_MAX)) }] : said2;
   }
   /**
-   * The card with buttons the event asks for, recorded first: a result that waits, a write Claw holds, or a command put to the
-   * person; undefined for none. `holdsWords`: the card shows the words, which are then not said apart.
+   * The card with buttons the event asks for, recorded first: a result that waits, a write Claw holds, a command or a choice put
+   * to the person; undefined for none. `holdsWords`: the card shows the words, which are then not said apart.
    */
   card(userId, event, item, said2) {
     const inCard = said2.inCard ? said2.text : "";
     if (item?.canAccept)
       return { message: this.workCard(userId, item, said2.text, inCard, said2.lang), holdsWords: said2.inCard };
-    if (item !== null) return void 0;
+    const asked3 = item === null ? this.askCard(userId, event, inCard, said2.lang) : void 0;
+    if (asked3 !== void 0) return { message: asked3, holdsWords: said2.inCard };
+    return this.choiceCard(userId, event, inCard, said2.lang, said2.inCard);
+  }
+  /** A write Claw holds for the person (Allow, Deny) or a command put to them (Run, Cancel), recorded first; undefined for none. */
+  askCard(userId, event, inCard, lang) {
     const held = confirmWriteOf(event);
     if (held !== void 0) {
       const cardId2 = this.deps.store.assistantButtons.addConfirmCard(
@@ -17294,8 +17493,8 @@ ${text8}`;
         held.kind,
         held.allowLabel
       );
-      const model = { text: inCard || held.allowLabel, cardId: cardId2, allowLabel: held.allowLabel, lang: said2.lang };
-      return { message: view3({ name: "confirmWrite", model }), holdsWords: said2.inCard };
+      const model = { text: inCard || held.allowLabel, cardId: cardId2, allowLabel: held.allowLabel, lang };
+      return view3({ name: "confirmWrite", model });
     }
     const confirm = confirmActionOf(event, this.deps.exactCommand);
     if (confirm === void 0) return void 0;
@@ -17306,10 +17505,19 @@ ${text8}`;
       confirm.name,
       confirm.args
     );
-    return {
-      message: view3({ name: "actionCard", model: { text: inCard || command, cardId, command, lang: said2.lang } }),
-      holdsWords: said2.inCard
-    };
+    return view3({ name: "actionCard", model: { text: inCard || command, cardId, command, lang } });
+  }
+  /**
+   * A choice put to the person (`choices`): its options and Send, recorded first (what a press sends is read from the record).
+   * Its Send sends what was picked as the person's own message.
+   */
+  choiceCard(userId, event, inCard, lang, holdsWords) {
+    const choice = choiceOf(event);
+    if (choice === void 0) return void 0;
+    const { options, multiple } = choice;
+    const cardId = this.deps.store.assistantButtons.addChoiceCard(userId, { text: inCard, options, multiple, lang });
+    const model = { text: inCard, cardId, options, multiple, note: "", lang };
+    return { message: view3({ name: "choiceCard", model }, inCard), holdsWords };
   }
   /** What was said, as AI answers with thumbs, each with the citations its own words cite (when the whole text cites at all). */
   said(event, text8, parts2) {
@@ -32756,6 +32964,7 @@ export {
   AssistantActionClicks,
   AssistantActions,
   AssistantChat as AssistantChatService,
+  AssistantChoiceClicks,
   BOARD_CARDS,
   BOARD_LINES,
   BOARD_RETRY_MAX,

package/dist/types/assistant/chat.d.ts

@@ -89,6 +89,8 @@ export declare class AssistantChat {
     forget(userId: string): void;
     /** What a message of files and no words says to the assistant. */
     filesOnly(lang: Lang): string;
+    /** The language the person chose to be answered in, as the message's `channel_context` carries it (none: nothing is sent). */
+    private chosenLanguage;
     private langOf;
     /**
      * A message of a person the assistant understands, with the chat's context. True when the assistant has it; otherwise the

package/dist/types/assistant/choice-clicks.d.ts

@@ -0,0 +1,35 @@
+import type { ClickHandler, ClickRoute } from "../ports/routing.js";
+import type { ChoiceCard } from "../ports/store/assistant.js";
+import type { StorePort } from "../ports/store/index.js";
+import type { Logger } from "../ports/logger.js";
+import type { InboundMessage } from "../ports/surface.js";
+export declare const CHOICE_VERB = "assistant_choice";
+/** The id of a choice card's input, whose value is the picked options' places on the card ("0", "0,2"). */
+export declare const CHOICE_INPUT = "choice";
+export interface ChoiceClickDeps {
+    readonly store: Pick<StorePort, "assistantButtons">;
+    /** Handles `message` as the router handles one the person typed (`Router.handle`); throws when it was not handled. */
+    readonly deliver: (message: InboundMessage) => Promise<void>;
+    readonly logger: Logger;
+}
+/** The options `value` picks on `card` (each named by its place), in the card's order; a place it never had is no pick. */
+export declare function pickedOn(card: Pick<ChoiceCard, "options">, value: unknown): string[];
+/**
+ * The message a press sends: the presser's, in the chat it was pressed in, saying `text`, as a typed one is (to the bot, in a
+ * group), but marked `choice`, so no word of it is read as a command.
+ */
+export declare function typedMessage(click: Pick<ClickRoute, "action" | "sender">, text: string, id: string): InboundMessage;
+export declare class AssistantChoiceClicks implements ClickHandler {
+    private readonly deps;
+    readonly verbs: readonly ["assistant_choice"];
+    constructor(deps: ChoiceClickDeps);
+    /** A 1:1 chat: answered with no Claw key (the message it sends is checked as any typed one is). */
+    beforeCredential(click: ClickRoute): Promise<boolean>;
+    inGroup(click: ClickRoute): Promise<boolean>;
+    press(click: ClickRoute): Promise<void>;
+    /** The card back, open, with `note` under its options. */
+    private again;
+    /** The card replaced by what was picked and sent (said as a line too when `announce`). */
+    private sent;
+    private model;
+}

package/dist/types/assistant/events.d.ts

@@ -41,6 +41,23 @@ export declare function confirmWriteOf(event: Event): ConfirmWrite | undefined;
  * line that is no command, else the defaults in the person's language (`lang`; without it, the language of `text`).
  */
 export declare function suggestedRepliesOf(event: Event, text: string, styleOn: boolean, lang?: Lang): SuggestedReply[];
+/** The fewest options a choice card shows (Claw sends from 2). */
+export declare const CHOICE_OPTIONS_MIN = 2;
+/** The most options a choice card shows (Claw sends at most 10). */
+export declare const CHOICE_OPTIONS_MAX = 10;
+/** Code points of one option (Claw sends at most 80): one line beside a radio button or a check box. */
+export declare const CHOICE_OPTION_MAX = 80;
+/** A choice an `assistant.say` puts to the person: the options, and whether several may be picked. */
+export interface SayChoice {
+    readonly options: readonly string[];
+    readonly multiple: boolean;
+}
+/**
+ * The choice an `assistant.say` puts to the person (`choices`); undefined when it carries none this worker draws. Read whole or not
+ * at all: an option that is not one plain line of text, or too many or too few of them, and there is no card (the words still name
+ * the options, for the person to type).
+ */
+export declare function choiceOf(event: Event): SayChoice | undefined;
 export interface RemoteNotice {
     /** `resolved`: a question a terminal asked no longer waits here (answered there, or given up); `resolved` says which. */
     readonly kind: "done" | "needs_you" | "error" | "resolved";

package/dist/types/assistant/index.d.ts

@@ -1,6 +1,7 @@
 /** What the assembly wires of the assistant (one line each; the views and work-item text are exported from the package root). */
 export { AssistantActionClicks } from "./action-handler.js";
 export { AssistantActions } from "./actions.js";
+export { AssistantChoiceClicks } from "./choice-clicks.js";
 export { Board } from "./board.js";
 export { AssistantChat as AssistantChatService } from "./chat.js";
 export type { AssistantChatOptions } from "./chat.js";

package/dist/types/assistant/say.d.ts

@@ -5,8 +5,9 @@
  *   receipt already shows of it (`shown`). It is an AI answer: the AI label and the thumbs under it, a citation for each source it
  *   cites as [n], and the replies to tap under the last of its messages when no card follows.
  * - When the event's item holds a result that waits, a card with Accept and Stop; when it holds a write for the person, a card
- *   that lets it through or not; when it puts a command to the person, a card with Run and Cancel (each recorded first, so its
- *   buttons mean something). A card holds the words only when they are short and not shown already.
+ *   that lets it through or not; when it puts a command to the person, a card with Run and Cancel; when it puts a choice to the
+ *   person, a card with the options and Send (each recorded first, so its buttons mean something). A card holds the words only
+ *   when they are short and not shown already.
  * - Then a card for each file the item's worker delivered, with Claw's own download link.
  *
  * Every word of this worker's own is in the person's language, never in that of what was said.
@@ -51,10 +52,17 @@ export declare class SayPlanner {
     /** The replies to tap, under the last of what was said, when no card follows. */
     private withReplies;
     /**
-     * The card with buttons the event asks for, recorded first: a result that waits, a write Claw holds, or a command put to the
-     * person; undefined for none. `holdsWords`: the card shows the words, which are then not said apart.
+     * The card with buttons the event asks for, recorded first: a result that waits, a write Claw holds, a command or a choice put
+     * to the person; undefined for none. `holdsWords`: the card shows the words, which are then not said apart.
      */
     private card;
+    /** A write Claw holds for the person (Allow, Deny) or a command put to them (Run, Cancel), recorded first; undefined for none. */
+    private askCard;
+    /**
+     * A choice put to the person (`choices`): its options and Send, recorded first (what a press sends is read from the record).
+     * Its Send sends what was picked as the person's own message.
+     */
+    private choiceCard;
     /** What was said, as AI answers with thumbs, each with the citations its own words cite (when the whole text cites at all). */
     private said;
     /** A result that waits: Accept and Stop, and (a task whose result names a pull request) auto-reply on or off. */

package/dist/types/assistant/views.d.ts

@@ -68,9 +68,31 @@ export interface ConfirmWriteModel {
     readonly allowLabel: string;
     readonly lang: string;
 }
+/** A choice the assistant put to the person: its options as radio buttons (or check boxes) and Send. */
+export interface ChoiceCardModel {
+    /** The words, when the card holds them ("" when they were said apart). */
+    readonly text: string;
+    readonly cardId: string;
+    readonly options: readonly string[];
+    /** Several may be picked (check boxes); else one (radio buttons). */
+    readonly multiple: boolean;
+    /** One line under the options when the card comes back unanswered ("" none). */
+    readonly note: string;
+    /** "zh" or "en"; null to follow what was said. */
+    readonly lang: string | null;
+}
+/** What replaces a choice card once the person sent what they picked: what they sent, under the words it answered. */
+export interface ChoiceChosenModel {
+    readonly text: string;
+    /** The options picked, in the card's order. */
+    readonly chosen: readonly string[];
+    readonly lang: string | null;
+}
 declare module "../ports/surface.js" {
     interface ViewMap {
         actionCard: ActionCardModel;
+        choiceCard: ChoiceCardModel;
+        choiceChosen: ChoiceChosenModel;
         board: BoardModel;
         confirmWrite: ConfirmWriteModel;
         workCard: WorkCardModel;

package/dist/types/language/chosen.d.ts

@@ -0,0 +1,23 @@
+/**
+ * The language a person chose to be answered in (`/lang zh|en`), as it goes to Claw with each of their messages, so that the
+ * model's answer is in it as well as the agent's own texts.
+ *
+ * Only a choice the person said counts: a language learnt from what they write (`learnLang`), and `/lang auto`, are no
+ * choice, nothing is sent, and Claw reads the language from the message as before. To the assistant the choice goes in the
+ * message's `channel_context` (`reply_language`); to a plain session (a group's turn, or a 1:1 chat without the assistant) as
+ * the line Claw's assistant uses for it, after the message (`replyLanguageLine`).
+ */
+import type { Lang } from "../locales/lang.js";
+/** What of a person's preferences says the choice (`Prefs.lang`, `Prefs.langSet`). */
+export interface LangPrefs {
+    readonly lang: string;
+    readonly langSet: boolean;
+}
+/** The language the person chose, or undefined when they chose none. */
+export declare function chosenLang(prefs: LangPrefs): Lang | undefined;
+/** The choice as `channel_context` carries it (`{ reply_language: "zh" }`); empty when there is none. */
+export declare function replyLanguageContext(prefs: LangPrefs): {
+    reply_language?: Lang;
+};
+/** The line after a message to a plain session that names the language to answer in: `[Reply language: English]`. */
+export declare function replyLanguageLine(lang: Lang): string;

package/dist/types/locales/assistant-cards.d.ts

@@ -67,6 +67,21 @@ export declare const assistantCardText: import("./catalog.js").Catalog<{
     askedTitle: (p: {
         n: number;
     }) => string;
+    choiceTitle: string;
+    choiceTitleMany: string;
+    choiceSend: string;
+    choiceTyped: string;
+    choiceNone: string;
+    choiceSent: (p: {
+        answer: string;
+    }) => string;
+    choiceGone: string;
+    choiceSending: (p: {
+        answer: string;
+    }) => string;
+    choiceFailed: string;
+    /** How the options picked are joined into the person's message. */
+    choiceJoin: string;
     version: (p: {
         version: number;
     }) => string;

package/dist/types/ports/store/assistant.d.ts

@@ -1,6 +1,6 @@
 /**
  * Cards and messages of the assistant (tables `assistant_cards`, `auto_replies`, `assistant_action_cards`,
- * `assistant_confirm_cards`, `assistant_messages`). A card's buttons carry only its id; what a press means is read
+ * `assistant_confirm_cards`, `assistant_choice_cards`, `assistant_messages`). A card's buttons carry only its id; what a press means is read
  * from here, so a forged, old or someone else's card changes nothing.
  */
 import type { JsonObject } from "./json.js";
@@ -56,6 +56,21 @@ export interface ConfirmCard {
     readonly state: CardState;
     readonly createdAt: number;
 }
+/** A choice the assistant put to the person: what was asked, the options, and (once sent) what was picked. */
+export interface ChoiceCard {
+    readonly cardId: string;
+    readonly userId: string;
+    /** The words the card holds ("" when they were said apart). */
+    readonly text: string;
+    readonly options: readonly string[];
+    readonly multiple: boolean;
+    /** What was picked, in the card's order: being sent ('busy') or sent ('done'); empty before the first press. */
+    readonly chosen: readonly string[];
+    /** 'open'; 'busy' while a press sends it; 'done' once the router took it. */
+    readonly state: CardState;
+    readonly lang: string;
+    readonly createdAt: number;
+}
 export interface AssistantMessage {
     readonly userId: string;
     /** The actions (and handoffs) the message declared. */
@@ -94,6 +109,17 @@ export interface AssistantButtonRepository {
     /** Null once it is older than CONFIRM_CARD_KEEP_SECONDS. */
     getConfirmCard(cardId: string): ConfirmCard | null;
     moveConfirmCard(cardId: string, state: CardState, options?: MoveOptions): boolean;
+    addChoiceCard(userId: string, choice: {
+        readonly text: string;
+        readonly options: readonly string[];
+        readonly multiple: boolean;
+        readonly lang: string;
+    }): string;
+    /** Null once it is older than ASSISTANT_MESSAGE_KEEP_SECONDS. */
+    getChoiceCard(cardId: string): ChoiceCard | null;
+    /** An open card is claimed by a press to send `chosen` (it moves to 'busy'); true if this call claimed it, so of two presses exactly one sends. */
+    claimChoiceCard(cardId: string, chosen: readonly string[]): boolean;
+    moveChoiceCard(cardId: string, state: CardState, options?: MoveOptions): boolean;
 }
 export interface AssistantMessageRepository {
     /** A message this worker sent to the person's assistant, with the actions it declared and the Claw users it named. */

package/dist/types/ports/surface.d.ts

@@ -134,6 +134,12 @@ export interface InboundMessage extends InboundBase {
      */
     readonly unreadableFiles: readonly string[];
     readonly provenance: Provenance;
+    /**
+     * What was picked on a choice card the assistant put (`assistant_choice`): an answer, never read as a command. The menu's
+     * words and help's phrases ("New", "重新开始", "Stop", "关闭记忆") stay the words picked; it goes where a typed message that
+     * is no command goes (the assistant, or the agent a 1:1 chat is attached to).
+     */
+    readonly choice?: true;
 }
 /** A button pressed on a card the bot posted. */
 export interface InboundAction extends InboundBase {

package/dist/types/protocol/claw-api/assistant-events.d.ts

@@ -140,6 +140,11 @@ export interface AssistantRemoteAsk {
     question_index?: number;
     question_count?: number;
 }
+/** A choice a say puts to the person: from 2 to 10 options, one plain line each; `multiple` when several may be picked. */
+export interface AssistantSayChoice {
+    options: string[];
+    multiple: boolean;
+}
 /** Something the assistant chose to say to the user. */
 export interface AssistantSayPayload extends AssistantEventBase {
     type: "assistant.say";
@@ -151,6 +156,12 @@ export interface AssistantSayPayload extends AssistantEventBase {
      * next, each one plain line. A channel shows them as buttons that send the words as the user's message; one that cannot ignores them.
      */
     suggested_replies?: string[];
+    /**
+     * Present only when the router put a choice to the person (`CLAW_ASSISTANT_CHOICES`): the options they pick from, each one plain
+     * line, and whether they may pick several. A channel shows them as a card whose Send sends the picked options as the person's own
+     * message (their words, joined); one that cannot ignores it, and the text still names the options.
+     */
+    choices?: AssistantSayChoice;
     confirm_write?: AssistantConfirmWrite;
     /** Files the user gets with the message (a worker's deliveries, `deliveries.ts`): one download each. */
     files?: AssistantFile[];

package/dist/types/routing/personal-text.d.ts

@@ -15,7 +15,8 @@ export declare class PersonalText {
     constructor(ctx: RouterContext, commands: CommandTable, starter: TurnStarter);
     /**
      * What the person wrote, with a word of the commands menu read as its command and a sentence help teaches read as the
-     * command it means; a sentence for what this chat cannot do right now stays words.
+     * command it means; a sentence for what this chat cannot do right now stays words. A choice picked on the assistant's card
+     * is the words picked, never a command.
      */
     textOf(message: InboundMessage, group?: boolean): string;
     onText(message: InboundMessage, chat: Chat, key: string): Promise<void>;

package/dist/types/routing/turn-runner.d.ts

@@ -43,6 +43,11 @@ export interface TurnRun {
     readonly sent: string;
     readonly files: readonly InboundFile[];
     readonly lang: Lang;
+    /**
+     * The language the person chose to be answered in (`/lang zh|en`, `chosenLang`), told to Claw after the message; undefined: they
+     * chose none, and the answer is in the language of what they wrote. A chat turn's only: a group's is the sender's.
+     */
+    readonly replyLang?: Lang;
     /** The answer gets thumbs of the worker's own (a phone, whose own thumbs never reach the worker). */
     readonly ownThumbs: boolean;
     /** Claw pushes this person a run's end and its approvals. */

package/dist/types/routing/turn-start.d.ts

@@ -72,7 +72,7 @@ export declare class TurnStarter {
     /** The turns that run now (a test waits for them). */
     settled(): Promise<void>;
     /** The turn that runs (its end is `done`), or undefined when none was started (the person was told why). */
-    start(request: StartTurn): Promise<RunningTurn | undefined>;
+    start(started: StartTurn): Promise<RunningTurn | undefined>;
     /** A typed message the waiting question card of the chat's session took as its answer (`question-reply.ts`). */
     private answersQuestion;
     private track;
@@ -97,6 +97,8 @@ export declare class TurnStarter {
     /** What the run reads of the chat's session: its id, the model it has, the repository a new one is bound to. */
     private sessionPart;
     private runOf;
+    /** The language the sender chose to be answered in, for a chat turn (a review's answer follows its request's language). */
+    private replyLang;
     private hooks;
     private guarded;
     private tell;

package/dist/types/turn/engine/context.d.ts

@@ -1,4 +1,3 @@
-/** Everything one turn runs with: who it acts for, what it sends, where it answers, and what it reports back. */
 import type { Lang } from "../../locales/lang.js";
 import type { PullRef } from "../../claw/model.js";
 import type { Integrations } from "../../plugins/integrations.js";
@@ -60,6 +59,8 @@ export interface TurnRequest {
     readonly sent?: string;
     /** The language the person is answered in (undefined: the language of `text`). */
     readonly lang?: Lang;
+    /** The language the person chose to be answered in, told to Claw after the message (`replyLanguageLine`); undefined: none chosen. */
+    readonly replyLang?: Lang;
     /** What the user sent with the message. */
     readonly files?: readonly InboundFile[];
 }
@@ -154,6 +155,7 @@ export declare function credential(ctx: TurnContext): Promise<string>;
 export declare function langOf(ctx: TurnContext): Lang;
 /**
  * What Claw is sent: the quoted messages, then what the user wrote (with the addresses behind its links), then where the
- * files they sent are. `text` stays the words alone: the session's title, the language of the answer.
+ * files they sent are, then the language they chose to be answered in (`replyLanguageLine`), when they chose one. `text` stays the
+ * words alone: the session's title, the language of the answer.
  */
 export declare function messageOf(ctx: TurnContext): string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@primusclaw/personal-agent",
-  "version": "0.5.0",
+  "version": "0.6.0",
   "description": "The personal agent's channel-neutral core: domain logic, ports and plugin interfaces.",
   "license": "MIT",
   "repository": {