@agentprojectcontext/apx 1.31.2 → 1.32.2

package/src/host/daemon/api/telegram.js

@@ -37,7 +37,7 @@ import {
   listRoles,
   setRole,
   removeRole,
-} from "../../../core/config.js";
+} from "#core/config/index.js";
 
 function redactChannel(channel) {
   if (!channel?.bot_token) return channel;

package/src/host/daemon/api/tools.js

@@ -4,12 +4,12 @@
 //   search / glob / grep                    → filesystem-bounded
 //   registry                                → /:name wildcard, MOUNT LAST so it
 //                                             doesn't shadow the specific paths
-import { buildBrowserRouter } from "../../../core/tools/browser.js";
-import { buildFetchRouter } from "../../../core/tools/fetch.js";
-import { buildSearchRouter } from "../../../core/tools/search.js";
-import { buildRegistryRouter } from "../../../core/tools/registry.js";
-import { buildGlobRouter } from "../../../core/tools/glob.js";
-import { buildGrepRouter } from "../../../core/tools/grep.js";
+import { buildBrowserRouter } from "#core/tools/browser.js";
+import { buildFetchRouter } from "#core/tools/fetch.js";
+import { buildSearchRouter } from "#core/tools/search.js";
+import { buildRegistryRouter } from "#core/tools/registry.js";
+import { buildGlobRouter } from "#core/tools/glob.js";
+import { buildGrepRouter } from "#core/tools/grep.js";
 
 export function register(app, { express, projects, registries }) {
   app.use("/tools/fetch", buildFetchRouter(express));

package/src/host/daemon/api/tts.js

@@ -8,8 +8,8 @@
 //
 // Audio files land under ~/.apx/tmp/tts/<uuid>.<ext>. The caller (CLI,
 // Telegram plugin, overlay) is responsible for picking them up.
-import { synthesize, listProviders } from "../../../core/voice/tts.js";
-import { readConfig } from "../../../core/config.js";
+import { synthesize, listProviders } from "#core/voice/tts.js";
+import { readConfig } from "#core/config/index.js";
 
 export function register(app) {
   app.post("/tts/say", async (req, res) => {

package/src/host/daemon/api/voice.js

@@ -1,3 +1,5 @@
+// eslint-disable-next-line -- import below
+import { CHANNELS } from "#core/constants/channels.js";
 // Daemon HTTP routes for the unified "voice" channel.
 //
 //   POST /voice/turn  { audio?: <base64 or path>, format?, text?, agent?,
@@ -19,12 +21,12 @@ import fs from "node:fs";
 import path from "node:path";
 import os from "node:os";
 import { randomUUID } from "node:crypto";
-import { readConfig } from "../../../core/config.js";
-import { synthesize } from "../../../core/voice/tts.js";
+import { readConfig } from "#core/config/index.js";
+import { synthesize } from "#core/voice/tts.js";
 import { transcribe } from "../transcription.js";
-import { runSuperAgent, isSuperAgentEnabled } from "../super-agent.js";
-import { appendGlobalMessage } from "../../../core/messages-store.js";
-import { appendErrorTrace, previewText } from "../../../core/logging.js";
+import { runSuperAgent, isSuperAgentEnabled } from "#core/agent/super-agent.js";
+import { appendGlobalMessage } from "#core/stores/messages.js";
+import { appendErrorTrace, previewText } from "#core/logging.js";
 
 // ── Channel-aware pre-processor ────────────────────────────────────
 //
@@ -84,14 +86,14 @@ function buildChannelContext(channel, { projectId, language = "es" } = {}) {
   const dynamicNote = `${langDirective}${projectHint}`;
   switch (channel) {
     case "voice":
-      return { ...base, contextNote: dynamicNote, systemSuffix: SUGGESTIONS_INSTRUCTION, wantsSuggestions: true, channel: "deck", channelMeta: { voice: true } };
+      return { ...base, contextNote: dynamicNote, systemSuffix: SUGGESTIONS_INSTRUCTION, wantsSuggestions: true, channel: CHANNELS.DECK, channelMeta: { voice: true } };
     case "deck":
-      return { ...base, contextNote: dynamicNote, systemSuffix: SUGGESTIONS_INSTRUCTION, wantsSuggestions: true, channel: "deck", channelMeta: {} };
+      return { ...base, contextNote: dynamicNote, systemSuffix: SUGGESTIONS_INSTRUCTION, wantsSuggestions: true, channel: CHANNELS.DECK, channelMeta: {} };
     case "desktop":
-      return { ...base, contextNote: dynamicNote, systemSuffix: SUGGESTIONS_INSTRUCTION, wantsSuggestions: true, channel: "desktop", channelMeta: { voice: true } };
+      return { ...base, contextNote: dynamicNote, systemSuffix: SUGGESTIONS_INSTRUCTION, wantsSuggestions: true, channel: CHANNELS.DESKTOP, channelMeta: { voice: true } };
     case "telegram":
       // Format rules live in channels/telegram.md; keep only the dynamic note.
-      return { ...base, contextNote: dynamicNote, channel: "telegram", channelMeta: {} };
+      return { ...base, contextNote: dynamicNote, channel: CHANNELS.TELEGRAM, channelMeta: {} };
     default:
       return { ...base, contextNote: dynamicNote, channel: channel || "api", channelMeta: {} };
   }
@@ -232,7 +234,7 @@ async function tryVoiceTaskIntent({ projects, userText, hintProjectId }) {
     };
   }
   try {
-    const { createTask } = await import("../../../core/tasks-store.js");
+    const { createTask } = await import("#core/stores/tasks.js");
     const task = createTask(project.storagePath, {
       title,
       source: "voice",
@@ -511,8 +513,8 @@ export function register(app, { projects, plugins, registries }) {
 }
 
 // Note for plugin authors:
-//   Desktop (src/host/daemon/plugins/desktop.js) and Telegram
-//   (src/host/daemon/plugins/telegram.js) currently implement their own
+//   Desktop (src/host/daemon/plugins/desktop/index.js) and Telegram
+//   (src/host/daemon/plugins/telegram/index.js) currently implement their own
 //   STT → agent → render pipelines. To get spoken replies via APX they can
 //   POST to /voice/turn (or call `synthesize()` directly) instead of
 //   re-implementing TTS. This module intentionally does NOT migrate them —

package/src/host/daemon/api.js

@@ -22,6 +22,7 @@ import { register as registerMessages } from "./api/messages.js";
 import { register as registerTelegram } from "./api/telegram.js";
 import { register as registerPlugins } from "./api/plugins.js";
 import { register as registerEngines } from "./api/engines.js";
+import { register as registerSkills } from "./api/skills.js";
 import { register as registerExec } from "./api/exec.js";
 import { register as registerSuperAgent } from "./api/super-agent.js";
 import { register as registerCode } from "./api/code.js";
@@ -107,6 +108,7 @@ export function buildApi({
   registerMcps(app, ctx);
   registerMessages(app, ctx);
   registerEngines(app, ctx);
+  registerSkills(app, ctx);
   registerExec(app, ctx);
   registerSuperAgent(app, ctx);
   registerConfirm(app, ctx);

package/src/host/daemon/compact.js

@@ -25,7 +25,7 @@
 import fs from "node:fs";
 import path from "node:path";
 import { parseConversation } from "./conversations.js";
-import { callEngine } from "../../core/engines/index.js";
+import { callEngine } from "#core/engines/index.js";
 
 const KEEP_LAST = 6;
 

package/src/host/daemon/db.js

@@ -2,15 +2,15 @@
 // Projects are identified by path; no SQLite — filesystem is the source of truth.
 import fs from "node:fs";
 import path from "node:path";
-import { appendMessageToFs } from "../../core/messages-store.js";
+import { appendMessageToFs } from "#core/stores/messages.js";
 import { effectiveConfig } from "./project-config.js";
-import { readAgents } from "../../core/parser.js";
-import { getOrCreateApxId } from "../../core/scaffold.js";
+import { readAgents } from "#core/apc/parser.js";
+import { getOrCreateApxId } from "#core/apc/scaffold.js";
 import {
   ensureProjectStorage,
   DEFAULT_PROJECT_ID,
   DEFAULT_PROJECT_STORE,
-} from "../../core/config.js";
+} from "#core/config/index.js";
 
 export class ProjectManager {
   constructor(globalConfig = {}) {

package/src/host/daemon/desktop-ws.js

@@ -1,5 +1,5 @@
 // Singleton WebSocket hub for the desktop channel.
-// Imported by api.js (to register connections) and by plugins/desktop.js (to broadcast).
+// Imported by api.js (to register connections) and by plugins/desktop/index.js (to broadcast).
 
 const _clients = new Set(); // Set<WebSocket>
 let _messageHandler = null; // (ws, data) => void — set by desktop plugin

package/src/host/daemon/index.js

@@ -14,17 +14,17 @@ import {
   LOG_PATH,
   APX_HOME,
   TOKEN_PATH,
-} from "../../core/config.js";
+} from "#core/config/index.js";
 import { ProjectManager } from "./db.js";
-import { McpRegistry } from "../../core/mcp/runner.js";
+import { McpRegistry } from "#core/mcp/runner.js";
 import { PluginManager } from "./plugins/index.js";
 import { RoutineScheduler } from "./routines.js";
 import { buildApi } from "./api.js";
 import { createTokenStore } from "./token-store.js";
 import { triggerWakeup } from "./wakeup.js";
 import { registerDesktopClient } from "./desktop-ws.js";
-import { log as logToUnified } from "../../core/logging.js";
-import { initMemory, stopMemory } from "../../core/memory/index.js";
+import { log as logToUnified } from "#core/logging.js";
+import { initMemory, stopMemory } from "#core/memory/index.js";
 
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = path.dirname(__filename);

package/src/host/daemon/plugins/{desktop.js → desktop/index.js}

@@ -21,11 +21,13 @@ import {
   broadcastDesktop,
   sendToClient,
   setDesktopMessageHandler,
-} from "../desktop-ws.js";
-import { runSuperAgent, isSuperAgentEnabled } from "../super-agent.js";
-import { appendGlobalMessage } from "../../../core/messages-store.js";
+} from "../../desktop-ws.js";
+import { runSuperAgent, isSuperAgentEnabled } from "#core/agent/super-agent.js";
+import { appendGlobalMessage } from "#core/stores/messages.js";
+import { CHANNELS } from "#core/constants/channels.js";
+import { tryResolveSkillCommand } from "#core/agent/skills/trigger.js";
 
-const CHANNEL = "desktop";
+const CHANNEL = CHANNELS.DESKTOP;
 
 export default {
   id: "desktop",
@@ -128,12 +130,15 @@ async function _handleMessage({ ws, text, previousMessages }, { projects, config
 
     log(`desktop: super-agent turn start — model=${cfg.model || config?.super_agent?.model || "(default)"} text="${text.slice(0, 60)}"`);
     const t0 = Date.now();
+    const slashed = tryResolveSkillCommand(text);
+    const slashedPrompt = slashed.handled ? slashed.prompt : text;
     const result = await runSuperAgent({
       globalConfig: config,
       projects,
       plugins,
-      prompt: text,
-      channel: "desktop",
+      prompt: slashedPrompt,
+      channel: CHANNELS.DESKTOP,
+      ...(slashed.handled ? { contextNote: slashed.contextNote } : {}),
       channelMeta: { voice: true }, // desktop module is voice-first → spoken mode
       previousMessages: history.slice(0, -1),
       overrideModel: cfg.model || null,
@@ -146,6 +151,15 @@ async function _handleMessage({ ws, text, previousMessages }, { projects, config
           _send(ws, { type: "tool_start", name: t.tool, args: t.args });
         } else if (event.type === "tool_result") {
           _send(ws, { type: "tool_done", name: event.trace.tool });
+          // ask_questions on desktop is voice-first: there's no inline-keyboard
+          // UI to render, so we turn the structured questions into a spoken
+          // segment. The user voice-replies on the next turn and the super-agent
+          // sees that reply in its history. Each option is announced inline so
+          // TTS reads them aloud naturally.
+          if (event.trace?.tool === "ask_questions") {
+            const segments = formatAskQuestionsForVoice(event.trace.args?.questions);
+            if (segments) emitSegment(segments);
+          }
         } else if (event.type === "assistant_text" && event.text) {
           // A complete assistant text segment (e.g. the "I'll check…" intro
           // emitted right before a tool runs). Ship it as its own message.
@@ -193,6 +207,31 @@ async function _handleMessage({ ws, text, previousMessages }, { projects, config
   }
 }
 
+// Build a voice-friendly transcript of an ask_questions tool call so the
+// desktop's TTS reads the prompt aloud and the bubble shows what was asked.
+// Single question + options reads as "<question> Opciones: A; B; C."
+// Multiple questions are numbered. Free-text questions just speak the prompt.
+function formatAskQuestionsForVoice(raw) {
+  if (!Array.isArray(raw) || raw.length === 0) return null;
+  const lines = [];
+  raw.forEach((rawQ, idx) => {
+    const q = typeof rawQ === "string" ? { question: rawQ } : (rawQ || {});
+    const text = typeof q.question === "string" ? q.question.trim() : "";
+    if (!text) return;
+    const prefix = raw.length > 1 ? `${idx + 1}. ` : "";
+    const opts = Array.isArray(q.options) ? q.options : [];
+    const optLabels = opts
+      .map((o) => (typeof o === "string" ? o : (o && typeof o.label === "string" ? o.label : "")))
+      .filter(Boolean);
+    let line = `${prefix}${text}`;
+    if (optLabels.length > 0) {
+      line += ` Opciones: ${optLabels.join("; ")}.`;
+    }
+    lines.push(line);
+  });
+  return lines.length > 0 ? lines.join("\n") : null;
+}
+
 function _send(ws, msg) {
   if (ws) {
     sendToClient(ws, msg);

package/src/host/daemon/plugins/index.js

@@ -12,8 +12,8 @@
 //
 // Plugins are discovered by static import here. Adding a new plugin = importing
 // it and pushing into PLUGINS.
-import telegramPlugin from "./telegram.js";
-import desktopPlugin from "./desktop.js";
+import telegramPlugin from "./telegram/index.js";
+import desktopPlugin from "./desktop/index.js";
 
 export const PLUGINS = [telegramPlugin, desktopPlugin];
 

package/src/host/daemon/plugins/telegram/ask.js

@@ -0,0 +1,309 @@
+// Telegram ask_questions integration.
+//
+// When the super-agent ends a turn with an `ask_questions` tool call, the
+// telegram plugin calls into this module instead of sending the bare reply
+// text. We render each question as a Telegram message with an inline keyboard
+// (one button per option, plus skip/cancel), keep the in-flight state in
+// memory keyed by chat_id, and resume by feeding the compiled answers back
+// to the super-agent as a synthetic user prompt.
+//
+// State is intentionally process-local: an ask flow that started before a
+// daemon restart simply dies; the user can re-issue the original prompt.
+
+import { performance } from "node:perf_hooks";
+
+const ASK_TTL_MS = 30 * 60_000; // 30 min — abandoned flows GC'd after this
+
+const STORE = new Map(); // chat_id (string) → AskState
+
+// AskState shape:
+// {
+//   chatId, projectId, authorId,
+//   correlationId,         // short id used in callback_data to dedupe restarts
+//   questions: AskQuestion[],
+//   answers: { picked: Set<number>, text: string, skipped: boolean }[],
+//   index: number,
+//   messageId: number|null, // last sent question message (for edit/disable)
+//   createdAt, lastTouchedAt,
+//   resume: (compiled: string) => Promise<void>, // called when flow completes
+// }
+
+function emptyAnswer() {
+  return { picked: new Set(), text: "", skipped: false };
+}
+
+function genCorrelationId() {
+  // Time-derived monotonically-ish id, kept short for Telegram's 64-byte
+  // callback_data limit. No Date.now() in workflows but we're in normal Node.
+  return Math.floor(performance.now() * 1000).toString(36) + Math.floor(Math.random() * 36 ** 4).toString(36);
+}
+
+// Normalize whatever shape the model passed (strings or {question,...} objs)
+// into the canonical question record. Identical contract to the web side
+// (InlineAskPanel.tsx normalizeQuestionClient).
+export function normalizeQuestion(q) {
+  if (typeof q === "string") {
+    return { question: q, options: [], multiSelect: false, allowText: true };
+  }
+  if (!q || typeof q !== "object") return null;
+  const text = typeof q.question === "string" ? q.question : "";
+  if (!text) return null;
+  const rawOptions = Array.isArray(q.options) ? q.options : [];
+  const options = rawOptions
+    .map((o) => {
+      if (typeof o === "string") return { label: o };
+      if (o && typeof o === "object" && typeof o.label === "string") {
+        return {
+          label: o.label,
+          description: typeof o.description === "string" ? o.description : undefined,
+        };
+      }
+      return null;
+    })
+    .filter(Boolean);
+  return {
+    question: text,
+    header: typeof q.header === "string" ? q.header : undefined,
+    options,
+    multiSelect: q.multiSelect === true,
+    allowText: q.allowText === false ? false : true,
+  };
+}
+
+// Pull the most recent ask_questions tool call out of a super-agent trace.
+// Returns the normalized question list, or null when the turn didn't ask.
+export function extractAskQuestionsFromTrace(trace) {
+  if (!Array.isArray(trace)) return null;
+  for (let i = trace.length - 1; i >= 0; i--) {
+    const t = trace[i];
+    if (t && t.tool === "ask_questions") {
+      const raw = (t.args && Array.isArray(t.args.questions)) ? t.args.questions : [];
+      const normalized = raw.map(normalizeQuestion).filter(Boolean);
+      return normalized.length > 0 ? normalized : null;
+    }
+  }
+  return null;
+}
+
+// Compile collected answers into a single user-message string. Mirrors the
+// shape produced by the web InlineAskPanel.compileAnswers so the super-agent
+// sees consistent input across surfaces.
+export function compileAnswers(state) {
+  const lines = [];
+  state.questions.forEach((q, i) => {
+    const a = state.answers[i] || emptyAnswer();
+    if (a.skipped) {
+      lines.push(`- ${q.question}\n  → (omitido)`);
+      return;
+    }
+    const parts = [];
+    if (q.options && q.options.length > 0) {
+      const labels = [...a.picked]
+        .sort((x, y) => x - y)
+        .map((idx) => q.options[idx]?.label)
+        .filter(Boolean);
+      if (labels.length > 0) parts.push(labels.join(", "));
+    }
+    const text = (a.text || "").trim();
+    if (text) {
+      parts.push(q.options && q.options.length > 0 ? `(Otro: ${text})` : text);
+    }
+    const answerText = parts.length > 0 ? parts.join(" ") : "(sin respuesta)";
+    lines.push(`- ${q.question}\n  → ${answerText}`);
+  });
+  return lines.join("\n");
+}
+
+// Build the Telegram InlineKeyboardMarkup for one question. Single-select:
+// pressing an option commits immediately; the keyboard disappears via
+// editMessageReplyMarkup. Multi-select: each press toggles a check on the
+// label; a "✓ Confirmar" row commits. No options: keyboard has only a Saltar
+// row, and the user is expected to reply with text.
+export function buildKeyboard(state) {
+  const cid = state.correlationId;
+  const q = state.questions[state.index];
+  const a = state.answers[state.index] || emptyAnswer();
+  const rows = [];
+
+  if (Array.isArray(q.options) && q.options.length > 0) {
+    q.options.forEach((opt, i) => {
+      const picked = a.picked.has(i);
+      const label = q.multiSelect
+        ? `${picked ? "☑" : "☐"} ${opt.label}`
+        : opt.label;
+      rows.push([
+        { text: label, callback_data: `apx:ask:${cid}:opt:${i}` },
+      ]);
+    });
+    if (q.multiSelect) {
+      rows.push([{ text: "✓ Confirmar", callback_data: `apx:ask:${cid}:next` }]);
+    }
+  }
+
+  // Control row: skip + cancel. Plus a back arrow when we're past Q1.
+  const controls = [];
+  if (state.index > 0) controls.push({ text: "◀︎ Atrás", callback_data: `apx:ask:${cid}:back` });
+  controls.push({ text: "Omitir", callback_data: `apx:ask:${cid}:skip` });
+  controls.push({ text: "Cerrar", callback_data: `apx:ask:${cid}:cancel` });
+  rows.push(controls);
+
+  return { inline_keyboard: rows };
+}
+
+// Plain-text body of the question message: header (N/M) + question + a hint
+// for free-text questions.
+export function formatQuestionText(state) {
+  const q = state.questions[state.index];
+  const total = state.questions.length;
+  const head = total > 1 ? `[${state.index + 1}/${total}] ` : "";
+  const hasOptions = Array.isArray(q.options) && q.options.length > 0;
+  const hint = hasOptions
+    ? (q.multiSelect
+        ? "\n\n_Multi-selección: tocá las opciones que quieras y después Confirmar._"
+        : "\n\n_Tocá una opción para responder._")
+    : "\n\n_Respondé con un mensaje de texto._";
+  return `❓ ${head}${q.question}${hint}`;
+}
+
+// ---- Store API ------------------------------------------------------------
+
+export function saveState(chatId, state) {
+  STORE.set(String(chatId), { ...state, lastTouchedAt: Date.now() });
+}
+
+export function getState(chatId) {
+  const s = STORE.get(String(chatId));
+  if (!s) return null;
+  if (Date.now() - s.lastTouchedAt > ASK_TTL_MS) {
+    STORE.delete(String(chatId));
+    return null;
+  }
+  return s;
+}
+
+export function clearState(chatId) {
+  STORE.delete(String(chatId));
+}
+
+export function hasPendingFreeText(chatId) {
+  const s = getState(chatId);
+  if (!s) return false;
+  const q = s.questions[s.index];
+  if (!q) return false;
+  return !(Array.isArray(q.options) && q.options.length > 0);
+}
+
+// Apply a user text reply to the currently-pending free-text question.
+// Returns the updated state (caller decides whether to advance) or null if
+// there was no pending free-text question.
+export function applyTextAnswer(chatId, text) {
+  const s = getState(chatId);
+  if (!s) return null;
+  const q = s.questions[s.index];
+  const hasOptions = Array.isArray(q.options) && q.options.length > 0;
+  if (hasOptions) return null; // multi/single-select questions are answered via callback only
+  const ans = s.answers[s.index] || emptyAnswer();
+  ans.text = (text || "").trim();
+  ans.skipped = false;
+  s.answers[s.index] = ans;
+  saveState(chatId, s);
+  return s;
+}
+
+// Apply a callback_query button press. Returns one of:
+//   { action: "advance", state }   — render the next question
+//   { action: "redraw",  state }   — same question, refresh the keyboard (toggle)
+//   { action: "done",    state, compiled } — last question answered
+//   { action: "cancel",  state }   — user closed the panel
+//   null — callback wasn't ours
+//
+// callback_data scheme: apx:ask:<correlationId>:<verb>[:<arg>]
+//   verbs: opt:<i>, next, back, skip, cancel
+export function applyCallback(chatId, data) {
+  const s = getState(chatId);
+  if (!s) return null;
+  if (typeof data !== "string" || !data.startsWith("apx:ask:")) return null;
+  const rest = data.slice("apx:ask:".length); // <corr>:<verb>[:<arg>]
+  const [corr, verb, arg] = rest.split(":");
+  if (corr !== s.correlationId) {
+    // Stale button from a previous flow.
+    return null;
+  }
+  const q = s.questions[s.index];
+  const ans = s.answers[s.index] || emptyAnswer();
+
+  if (verb === "opt") {
+    const optIdx = Number.parseInt(arg, 10);
+    if (!Number.isFinite(optIdx) || optIdx < 0 || optIdx >= (q.options?.length || 0)) {
+      return null;
+    }
+    if (q.multiSelect) {
+      // Toggle and stay on the same question.
+      if (ans.picked.has(optIdx)) ans.picked.delete(optIdx);
+      else ans.picked.add(optIdx);
+      ans.skipped = false;
+      s.answers[s.index] = ans;
+      saveState(chatId, s);
+      return { action: "redraw", state: s };
+    }
+    // Single-select: commit + advance.
+    ans.picked = new Set([optIdx]);
+    ans.skipped = false;
+    s.answers[s.index] = ans;
+    return advance(s);
+  }
+
+  if (verb === "next") return advance(s);
+  if (verb === "back") {
+    if (s.index > 0) {
+      s.index -= 1;
+      saveState(chatId, s);
+    }
+    return { action: "advance", state: s };
+  }
+  if (verb === "skip") {
+    s.answers[s.index] = { picked: new Set(), text: "", skipped: true };
+    return advance(s);
+  }
+  if (verb === "cancel") {
+    clearState(chatId);
+    return { action: "cancel", state: s };
+  }
+  return null;
+}
+
+function advance(s) {
+  if (s.index >= s.questions.length - 1) {
+    const compiled = compileAnswers(s);
+    clearState(s.chatId);
+    return { action: "done", state: s, compiled };
+  }
+  s.index += 1;
+  saveState(s.chatId, s);
+  return { action: "advance", state: s };
+}
+
+// Build the initial state and persist it. Caller must follow up with the
+// first sendMessage (use formatQuestionText + buildKeyboard).
+export function startFlow({ chatId, projectId, authorId, questions, resume }) {
+  const state = {
+    chatId: String(chatId),
+    projectId: projectId != null ? String(projectId) : null,
+    authorId: authorId != null ? String(authorId) : null,
+    correlationId: genCorrelationId(),
+    questions,
+    answers: questions.map(() => emptyAnswer()),
+    index: 0,
+    messageId: null,
+    createdAt: Date.now(),
+    lastTouchedAt: Date.now(),
+    resume,
+  };
+  saveState(chatId, state);
+  return state;
+}
+
+// Test-only: clear the global store between unit tests.
+export function _reset() {
+  STORE.clear();
+}