@dalmasonto/taskflow-mcp 1.0.35 → 2.1.0

package/dist/prompts.js

@@ -0,0 +1,211 @@
+/**
+ * Reading a dashboard-answered prompt back into keystrokes.
+ *
+ * `AskUserQuestion` accepts SEVERAL questions in one call. The agent's terminal
+ * presents them one at a time — question 2's screen only exists once question 1
+ * is answered — so a whole set is stored as ONE prompt row and replayed in order
+ * only when every question has an answer. Replaying half a set would send the
+ * remaining digits at whatever screen the agent had moved on to.
+ *
+ * Two on-the-wire shapes are supported, because rows written before
+ * multi-question support are still in the table:
+ *
+ *   legacy  options_json = [{number, label}, ...]        one question
+ *           answer_json  = [1, 3]                        one flat set
+ *
+ *   set     options_json = [{question, kind, options}]   N questions
+ *           answer_json  = [[1], [2, 3]]                 one set per question
+ *
+ * A prompt that cannot be read yields NO keystrokes. An agent left waiting is
+ * recoverable; digits fired into the wrong screen are not.
+ */
+import { answerKeystrokes } from "./events.js";
+function asOptions(value) {
+    if (!Array.isArray(value))
+        return [];
+    return value.filter((o) => typeof o === "object" && o !== null && typeof o.number === "number");
+}
+/**
+ * The questions a prompt is asking.
+ *
+ * `fallbackKind` and `fallbackQuestion` come from the row's own columns and are
+ * used only for the legacy shape, which stored the question text and kind there
+ * rather than inside the JSON.
+ */
+export function parseQuestions(optionsJson, fallbackKind, fallbackQuestion) {
+    let parsed;
+    try {
+        parsed = JSON.parse(optionsJson);
+    }
+    catch {
+        return [];
+    }
+    if (!Array.isArray(parsed) || parsed.length === 0)
+        return [];
+    // The discriminator is a nested `options` array: the set shape wraps each
+    // question, the legacy shape IS the option list.
+    const isSet = parsed.every((entry) => typeof entry === "object" && entry !== null && "options" in entry);
+    if (!isSet) {
+        const options = asOptions(parsed);
+        return options.length ? [{ question: fallbackQuestion, kind: fallbackKind, options }] : [];
+    }
+    return parsed
+        .map((entry) => {
+        const e = entry;
+        return {
+            question: typeof e.question === "string" ? e.question : fallbackQuestion,
+            kind: typeof e.kind === "string" ? e.kind : "single",
+            options: asOptions(e.options),
+        };
+    })
+        .filter((q) => q.options.length > 0);
+}
+/**
+ * The chosen numbers, one set per question.
+ *
+ * `answer` is the row's single-answer column, kept as a fallback for rows
+ * answered before `answer_json` existed.
+ */
+export function parseAnswerSets(answerJson, answer) {
+    const numeric = (value) => Array.isArray(value) ? value.filter((n) => typeof n === "number") : [];
+    if (answerJson) {
+        try {
+            const parsed = JSON.parse(answerJson);
+            if (Array.isArray(parsed)) {
+                // `[[1],[2]]` is one set per question; `[1,3]` is a single flat set.
+                return parsed.some(Array.isArray)
+                    ? parsed.map(numeric).filter((set) => set.length > 0)
+                    : [numeric(parsed)].filter((set) => set.length > 0);
+            }
+        }
+        catch {
+            // fall through to the single-answer column
+        }
+    }
+    return typeof answer === "number" ? [[answer]] : [];
+}
+/** Whether every question in the set has at least one choice. */
+export function isFullyAnswered(sets, questionCount) {
+    if (questionCount === 0)
+        return false;
+    if (sets.length !== questionCount)
+        return false;
+    return sets.every((set) => set.length > 0);
+}
+/**
+ * The review screen a MULTI-QUESTION set lands on once every question has been
+ * answered:
+ *
+ *     Ready to submit your answers?
+ *     > 1. Submit answers
+ *       2. Cancel
+ *
+ * Verified against a live session on 2026-07-21. Without this stage the agent
+ * answered all three questions and then sat on the review screen forever — the
+ * questions were right, and nothing pressed the final key.
+ *
+ * A numbered choice, so it takes a number AND Enter, matching the single-select
+ * behaviour confirmed the same day.
+ */
+const REVIEW_SUBMIT = ["1", "Enter"];
+const REVIEW_CANCEL = ["2", "Enter"];
+/**
+ * The full keystroke sequence for an answered prompt, or `[]` when it must not
+ * be replayed.
+ *
+ * Each question contributes its own sequence and they run back to back, in the
+ * order the questions were asked — the terminal advances to the next question as
+ * each is submitted. A set then confirms at the review screen.
+ *
+ * A single SINGLE-select question has no review screen (it submits as soon as it
+ * is answered), so nothing is appended and there is no safe "cancel" key. A
+ * single MULTI-select question DOES reach the review screen, so it gets the
+ * submit/cancel like a set does.
+ */
+export function keystrokesForPrompt(optionsJson, kind, question, answerJson, answer, intent = "submit") {
+    const questions = parseQuestions(optionsJson, kind, question);
+    const sets = parseAnswerSets(answerJson, answer);
+    if (!isFullyAnswered(sets, questions.length))
+        return [];
+    // The review screen appears for a question SET *and* for a single
+    // multi-select question — both end on "Ready to submit your answers?".
+    // Gating only on question count (as it did) left a lone multi-select stuck on
+    // that screen with nothing to press it. Verified live 2026-07-21.
+    const hasReviewScreen = questions.length > 1 || questions.some((q) => q.kind === "multi");
+    if (intent === "cancel" && !hasReviewScreen)
+        return [];
+    const answers = questions.flatMap((q, i) => answerKeystrokes(sets[i] ?? [], q.kind));
+    if (!hasReviewScreen)
+        return answers;
+    // Cancel is reached the same way as submit: every answer is replayed first,
+    // because the review screen only exists once the last question is answered.
+    return [...answers, ...(intent === "cancel" ? REVIEW_CANCEL : REVIEW_SUBMIT)];
+}
+/** The Other free-text value per question, parallel to the answer sets. */
+export function parseAnswerTexts(answerTextJson, count) {
+    if (!answerTextJson)
+        return Array(count).fill(null);
+    try {
+        const parsed = JSON.parse(answerTextJson);
+        if (Array.isArray(parsed)) {
+            return Array.from({ length: count }, (_, i) => typeof parsed[i] === "string" ? parsed[i] : null);
+        }
+    }
+    catch { /* fall through */ }
+    return Array(count).fill(null);
+}
+/**
+ * The full ordered steps for an answered prompt. Without any Other text this is
+ * `keystrokesForPrompt` wrapped as `{key}` steps. With Other text on a single
+ * multi-select question, it walks the arrow-based flow the new TUI uses (see the
+ * hypothesis in the test — verified live before this ships).
+ */
+export function stepsForPrompt(optionsJson, kind, question, answerJson, answer, answerTextJson, intent = "submit") {
+    const questions = parseQuestions(optionsJson, kind, question);
+    const sets = parseAnswerSets(answerJson, answer);
+    const texts = parseAnswerTexts(answerTextJson, questions.length);
+    // Only the scoped case gets the Other flow: one multi-select question whose
+    // Other option was picked with text. Everything else uses the proven path.
+    const single = questions.length === 1 ? questions[0] : undefined;
+    const other = single?.options.find((o) => o.isOther);
+    const otherPicked = other && sets[0]?.includes(other.number) && (texts[0] ?? "").length > 0;
+    if (!otherPicked || intent === "cancel") {
+        return keystrokesForPrompt(optionsJson, kind, question, answerJson, answer, intent)
+            .map((key) => ({ key }));
+    }
+    const otherIndex = single.options.findIndex((o) => o.isOther);
+    // SINGLE-select Other (#30): one answer, no toggles, no review screen. Arrow
+    // down from the caret on option 1 to the "Type something" row, type the text
+    // (which fills the field), and Enter submits it — single-select commits on
+    // Enter, unlike multi-select where Enter only toggles. HYPOTHESIS, verified
+    // live before shipping (the choreography is the one thing tests can't prove).
+    if (single.kind !== "multi") {
+        const singleSteps = [];
+        for (let i = 0; i < otherIndex; i++)
+            singleSteps.push({ key: "Down" });
+        singleSteps.push({ text: texts[0] });
+        singleSteps.push({ key: "Enter" });
+        return singleSteps;
+    }
+    const steps = [];
+    // Walk down the list from the caret's start on option 1, toggling picks.
+    for (let i = 0; i < single.options.length; i++) {
+        const opt = single.options[i];
+        if (opt.isOther) {
+            // Typing (which send-keys -l mimics) AUTO-CHECKS the Other option, and
+            // Enter merely TOGGLES it — so NO Enter here, or it would deselect the box
+            // the paste just checked. Verified live 2026-07-21: with an Enter, Other
+            // came back unchecked and dropped from the answer.
+            steps.push({ text: texts[0] });
+        }
+        else if (sets[0].includes(opt.number)) {
+            steps.push({ key: "Enter" }); // toggle this pick
+        }
+        if (i < single.options.length - 1)
+            steps.push({ key: "Down" });
+    }
+    steps.push({ key: "Down" }, { key: "Enter" }); // to Submit, activate -> review
+    steps.push({ key: "1" }, { key: "Enter" }); // Submit answers
+    return steps;
+}
+//# sourceMappingURL=prompts.js.map

package/dist/prompts.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"prompts.js","sourceRoot":"","sources":["../src/prompts.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,OAAO,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAiB/C,SAAS,SAAS,CAAC,KAAc;IAC/B,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC;QAAE,OAAO,EAAE,CAAC;IACrC,OAAO,KAAK,CAAC,MAAM,CACjB,CAAC,CAAC,EAAqB,EAAE,CACvB,OAAO,CAAC,KAAK,QAAQ,IAAI,CAAC,KAAK,IAAI,IAAI,OAAQ,CAAkB,CAAC,MAAM,KAAK,QAAQ,CACxF,CAAC;AACJ,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,cAAc,CAC5B,WAAmB,EACnB,YAAoB,EACpB,gBAAwB;IAExB,IAAI,MAAe,CAAC;IACpB,IAAI,CAAC;QACH,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,WAAW,CAAC,CAAC;IACnC,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,EAAE,CAAC;IACZ,CAAC;IACD,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC,IAAI,MAAM,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,EAAE,CAAC;IAE7D,0EAA0E;IAC1E,iDAAiD;IACjD,MAAM,KAAK,GAAG,MAAM,CAAC,KAAK,CACxB,CAAC,KAAK,EAAE,EAAE,CAAC,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,KAAK,IAAI,IAAI,SAAS,IAAI,KAAK,CAC7E,CAAC;IAEF,IAAI,CAAC,KAAK,EAAE,CAAC;QACX,MAAM,OAAO,GAAG,SAAS,CAAC,MAAM,CAAC,CAAC;QAClC,OAAO,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,EAAE,QAAQ,EAAE,gBAAgB,EAAE,IAAI,EAAE,YAAY,EAAE,OAAO,EAAE,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;IAC7F,CAAC;IAED,OAAO,MAAM;SACV,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE;QACb,MAAM,CAAC,GAAG,KAAkE,CAAC;QAC7E,OAAO;YACL,QAAQ,EAAE,OAAO,CAAC,CAAC,QAAQ,KAAK,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,gBAAgB;YACxE,IAAI,EAAE,OAAO,CAAC,CAAC,IAAI,KAAK,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,QAAQ;YACpD,OAAO,EAAE,SAAS,CAAC,CAAC,CAAC,OAAO,CAAC;SAC9B,CAAC;IACJ,CAAC,CAAC;SACD,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,OAAO,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC;AACzC,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,eAAe,CAAC,UAAyB,EAAE,MAAqB;IAC9E,MAAM,OAAO,GAAG,CAAC,KAAc,EAAY,EAAE,CAC3C,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC,EAAe,EAAE,CAAC,OAAO,CAAC,KAAK,QAAQ,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;IAEtF,IAAI,UAAU,EAAE,CAAC;QACf,IAAI,CAAC;YACH,MAAM,MAAM,GAAY,IAAI,CAAC,KAAK,CAAC,UAAU,CAAC,CAAC;YAC/C,IAAI,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC,EAAE,CAAC;gBAC1B,qEAAqE;gBACrE,OAAO,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC;oBAC/B,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,MAAM,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,GAAG,CAAC,MAAM,GAAG,CAAC,CAAC;oBACrD,CAAC,CAAC,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,GAAG,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC;YACxD,CAAC;QACH,CAAC;QAAC,MAAM,CAAC;YACP,2CAA2C;QAC7C,CAAC;IACH,CAAC;IACD,OAAO,OAAO,MAAM,KAAK,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;AACtD,CAAC;AAED,iEAAiE;AACjE,MAAM,UAAU,eAAe,CAAC,IAAgB,EAAE,aAAqB;IACrE,IAAI,aAAa,KAAK,CAAC;QAAE,OAAO,KAAK,CAAC;IACtC,IAAI,IAAI,CAAC,MAAM,KAAK,aAAa;QAAE,OAAO,KAAK,CAAC;IAChD,OAAO,IAAI,CAAC,KAAK,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,GAAG,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC;AAC7C,CAAC;AAKD;;;;;;;;;;;;;;GAcG;AACH,MAAM,aAAa,GAAG,CAAC,GAAG,EAAE,OAAO,CAAC,CAAC;AACrC,MAAM,aAAa,GAAG,CAAC,GAAG,EAAE,OAAO,CAAC,CAAC;AAErC;;;;;;;;;;;;GAYG;AACH,MAAM,UAAU,mBAAmB,CACjC,WAAmB,EACnB,IAAY,EACZ,QAAgB,EAChB,UAAyB,EACzB,MAAqB,EACrB,SAAuB,QAAQ;IAE/B,MAAM,SAAS,GAAG,cAAc,CAAC,WAAW,EAAE,IAAI,EAAE,QAAQ,CAAC,CAAC;IAC9D,MAAM,IAAI,GAAG,eAAe,CAAC,UAAU,EAAE,MAAM,CAAC,CAAC;IACjD,IAAI,CAAC,eAAe,CAAC,IAAI,EAAE,SAAS,CAAC,MAAM,CAAC;QAAE,OAAO,EAAE,CAAC;IAExD,kEAAkE;IAClE,uEAAuE;IACvE,8EAA8E;IAC9E,kEAAkE;IAClE,MAAM,eAAe,GAAG,SAAS,CAAC,MAAM,GAAG,CAAC,IAAI,SAAS,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,KAAK,OAAO,CAAC,CAAC;IAC1F,IAAI,MAAM,KAAK,QAAQ,IAAI,CAAC,eAAe;QAAE,OAAO,EAAE,CAAC;IAEvD,MAAM,OAAO,GAAG,SAAS,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,gBAAgB,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC;IACrF,IAAI,CAAC,eAAe;QAAE,OAAO,OAAO,CAAC;IACrC,4EAA4E;IAC5E,4EAA4E;IAC5E,OAAO,CAAC,GAAG,OAAO,EAAE,GAAG,CAAC,MAAM,KAAK,QAAQ,CAAC,CAAC,CAAC,aAAa,CAAC,CAAC,CAAC,aAAa,CAAC,CAAC,CAAC;AAChF,CAAC;AAED,2EAA2E;AAC3E,MAAM,UAAU,gBAAgB,CAAC,cAA6B,EAAE,KAAa;IAC3E,IAAI,CAAC,cAAc;QAAE,OAAO,KAAK,CAAC,KAAK,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IACpD,IAAI,CAAC;QACH,MAAM,MAAM,GAAY,IAAI,CAAC,KAAK,CAAC,cAAc,CAAC,CAAC;QACnD,IAAI,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC,EAAE,CAAC;YAC1B,OAAO,KAAK,CAAC,IAAI,CAAC,EAAE,MAAM,EAAE,KAAK,EAAE,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAC5C,OAAO,MAAM,CAAC,CAAC,CAAC,KAAK,QAAQ,CAAC,CAAC,CAAE,MAAM,CAAC,CAAC,CAAY,CAAC,CAAC,CAAC,IAAI,CAC7D,CAAC;QACJ,CAAC;IACH,CAAC;IAAC,MAAM,CAAC,CAAC,kBAAkB,CAAC,CAAC;IAC9B,OAAO,KAAK,CAAC,KAAK,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AACjC,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,cAAc,CAC5B,WAAmB,EACnB,IAAY,EACZ,QAAgB,EAChB,UAAyB,EACzB,MAAqB,EACrB,cAA6B,EAC7B,SAAuB,QAAQ;IAE/B,MAAM,SAAS,GAAG,cAAc,CAAC,WAAW,EAAE,IAAI,EAAE,QAAQ,CAAC,CAAC;IAC9D,MAAM,IAAI,GAAG,eAAe,CAAC,UAAU,EAAE,MAAM,CAAC,CAAC;IACjD,MAAM,KAAK,GAAG,gBAAgB,CAAC,cAAc,EAAE,SAAS,CAAC,MAAM,CAAC,CAAC;IAEjE,4EAA4E;IAC5E,2EAA2E;IAC3E,MAAM,MAAM,GAAG,SAAS,CAAC,MAAM,KAAK,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC;IACjE,MAAM,KAAK,GAAG,MAAM,EAAE,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC;IACrD,MAAM,WAAW,GACf,KAAK,IAAI,IAAI,CAAC,CAAC,CAAC,EAAE,QAAQ,CAAC,KAAK,CAAC,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC,MAAM,GAAG,CAAC,CAAC;IAE1E,IAAI,CAAC,WAAW,IAAI,MAAM,KAAK,QAAQ,EAAE,CAAC;QACxC,OAAO,mBAAmB,CAAC,WAAW,EAAE,IAAI,EAAE,QAAQ,EAAE,UAAU,EAAE,MAAM,EAAE,MAAM,CAAC;aAChF,GAAG,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,CAAC,EAAE,GAAG,EAAE,CAAC,CAAC,CAAC;IAC7B,CAAC;IAED,MAAM,UAAU,GAAG,MAAO,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC;IAE/D,6EAA6E;IAC7E,6EAA6E;IAC7E,2EAA2E;IAC3E,4EAA4E;IAC5E,8EAA8E;IAC9E,IAAI,MAAO,CAAC,IAAI,KAAK,OAAO,EAAE,CAAC;QAC7B,MAAM,WAAW,GAAc,EAAE,CAAC;QAClC,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,UAAU,EAAE,CAAC,EAAE;YAAE,WAAW,CAAC,IAAI,CAAC,EAAE,GAAG,EAAE,MAAM,EAAE,CAAC,CAAC;QACvE,WAAW,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,KAAK,CAAC,CAAC,CAAE,EAAE,CAAC,CAAC;QACtC,WAAW,CAAC,IAAI,CAAC,EAAE,GAAG,EAAE,OAAO,EAAE,CAAC,CAAC;QACnC,OAAO,WAAW,CAAC;IACrB,CAAC;IAED,MAAM,KAAK,GAAc,EAAE,CAAC;IAC5B,yEAAyE;IACzE,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,MAAO,CAAC,OAAO,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;QAChD,MAAM,GAAG,GAAG,MAAO,CAAC,OAAO,CAAC,CAAC,CAAE,CAAC;QAChC,IAAI,GAAG,CAAC,OAAO,EAAE,CAAC;YAChB,uEAAuE;YACvE,2EAA2E;YAC3E,yEAAyE;YACzE,mDAAmD;YACnD,KAAK,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,KAAK,CAAC,CAAC,CAAE,EAAE,CAAC,CAAC;QAClC,CAAC;aAAM,IAAI,IAAI,CAAC,CAAC,CAAE,CAAC,QAAQ,CAAC,GAAG,CAAC,MAAM,CAAC,EAAE,CAAC;YACzC,KAAK,CAAC,IAAI,CAAC,EAAE,GAAG,EAAE,OAAO,EAAE,CAAC,CAAC,CAAC,mBAAmB;QACnD,CAAC;QACD,IAAI,CAAC,GAAG,MAAO,CAAC,OAAO,CAAC,MAAM,GAAG,CAAC;YAAE,KAAK,CAAC,IAAI,CAAC,EAAE,GAAG,EAAE,MAAM,EAAE,CAAC,CAAC;IAClE,CAAC;IACD,KAAK,CAAC,IAAI,CAAC,EAAE,GAAG,EAAE,MAAM,EAAE,EAAE,EAAE,GAAG,EAAE,OAAO,EAAE,CAAC,CAAC,CAAC,gCAAgC;IAC/E,KAAK,CAAC,IAAI,CAAC,EAAE,GAAG,EAAE,GAAG,EAAE,EAAE,EAAE,GAAG,EAAE,OAAO,EAAE,CAAC,CAAC,CAAI,iBAAiB;IAChE,OAAO,KAAK,CAAC;AACf,CAAC"}

package/dist/resolve.d.ts

@@ -0,0 +1,72 @@
+/**
+ * Turn an id-only realtime message event into the message itself.
+ *
+ * ## Why this exists
+ *
+ * Chat rows are CHANNEL-scoped but the realtime group is per-PROJECT, so
+ * anything projected onto the wire reaches every member of the project. That is
+ * why chat events carry the row id and nothing else — projecting the fields
+ * broadcast every DM's body, roster and attachment key to the whole project
+ * (`backend/tests/realtime_dm_privacy.rs`).
+ *
+ * The id alone is safe to broadcast and useless without authorization: the
+ * message is fetched back over the agent read API, which re-checks the channel
+ * roster. An agent that is not on the channel resolves nothing.
+ *
+ * The event carries no channel either, so the lookup fans out across the
+ * channels this agent is on — the same shape `check_messages` already uses. That
+ * roster is small (a project room plus a handful of DMs), and the per-channel
+ * fetch is a one-row window rather than a page.
+ */
+import type { MessageTarget } from "./events.js";
+/** A message as the agent read API returns it. */
+export interface ResolvedMessage {
+    id: number;
+    channel: number;
+    sender_kind: string;
+    sender_label: string;
+    body_markdown: string;
+    sender_agent: number | null;
+    /** Present on the read row (the backend serializes them); the agent notice
+     *  surfaces them so a delivered message carries its own context. */
+    project?: number | null;
+    task?: number | null;
+    sender_user?: number | null;
+    /** #29: the one agent a directed group message is for; null = broadcast. */
+    target_agent?: number | null;
+    /** #29: the full directed-target set (agents + users). The backend stores it
+     *  as a JSON STRING column, so the read row carries a string here; this module
+     *  parses it into an array before delivery. Supersedes `target_agent`. */
+    targets?: MessageTarget[];
+    attachments?: Array<{
+        name: string;
+        size_bytes: number;
+        url: string;
+    }>;
+}
+/** Parse the message's `targets` column — a JSON string like
+ *  `[{"kind":"agent","id":1}]` on the read row — into a validated array.
+ *  Anything malformed (bad JSON, wrong shape) degrades to undefined, i.e. a
+ *  broadcast, rather than throwing on the delivery path. */
+export declare function parseTargets(raw: unknown): MessageTarget[] | undefined;
+/** The slice of the client this module needs; narrowed so tests need no HTTP. */
+export interface MessageSource {
+    listChannels(): Promise<Array<{
+        id: number;
+    }>>;
+    listMessages(params: {
+        channel: number;
+        since?: number;
+        limit?: number;
+    }): Promise<{
+        messages: ResolvedMessage[];
+    }>;
+}
+/**
+ * Fetch message `id`, or `null` when this agent cannot see it.
+ *
+ * Never throws. A failure to resolve must degrade to "nothing delivered" — the
+ * message is still stored and `check_messages` will surface it — rather than
+ * taking down the event stream that carries every other message.
+ */
+export declare function resolveMessage(source: MessageSource, id: number): Promise<ResolvedMessage | null>;

package/dist/resolve.js

@@ -0,0 +1,89 @@
+/**
+ * Turn an id-only realtime message event into the message itself.
+ *
+ * ## Why this exists
+ *
+ * Chat rows are CHANNEL-scoped but the realtime group is per-PROJECT, so
+ * anything projected onto the wire reaches every member of the project. That is
+ * why chat events carry the row id and nothing else — projecting the fields
+ * broadcast every DM's body, roster and attachment key to the whole project
+ * (`backend/tests/realtime_dm_privacy.rs`).
+ *
+ * The id alone is safe to broadcast and useless without authorization: the
+ * message is fetched back over the agent read API, which re-checks the channel
+ * roster. An agent that is not on the channel resolves nothing.
+ *
+ * The event carries no channel either, so the lookup fans out across the
+ * channels this agent is on — the same shape `check_messages` already uses. That
+ * roster is small (a project room plus a handful of DMs), and the per-channel
+ * fetch is a one-row window rather than a page.
+ */
+/** Parse the message's `targets` column — a JSON string like
+ *  `[{"kind":"agent","id":1}]` on the read row — into a validated array.
+ *  Anything malformed (bad JSON, wrong shape) degrades to undefined, i.e. a
+ *  broadcast, rather than throwing on the delivery path. */
+export function parseTargets(raw) {
+    let value = raw;
+    if (typeof raw === "string") {
+        if (raw.trim() === "")
+            return undefined;
+        try {
+            value = JSON.parse(raw);
+        }
+        catch {
+            return undefined;
+        }
+    }
+    if (!Array.isArray(value))
+        return undefined;
+    const out = [];
+    for (const entry of value) {
+        if (entry && typeof entry === "object") {
+            const kind = entry.kind;
+            const id = entry.id;
+            if (typeof kind === "string" && typeof id === "number")
+                out.push({ kind, id });
+        }
+    }
+    return out.length ? out : undefined;
+}
+/**
+ * Fetch message `id`, or `null` when this agent cannot see it.
+ *
+ * Never throws. A failure to resolve must degrade to "nothing delivered" — the
+ * message is still stored and `check_messages` will surface it — rather than
+ * taking down the event stream that carries every other message.
+ */
+export async function resolveMessage(source, id) {
+    let channels;
+    try {
+        channels = await source.listChannels();
+    }
+    catch {
+        return null;
+    }
+    const found = await Promise.all(channels.map(async (channel) => {
+        try {
+            // `since` is exclusive, so `id - 1` asks for exactly this row onward and
+            // `limit: 1` keeps it to one. A per-event page fetch would be wasteful on
+            // a busy project.
+            const page = await source.listMessages({ channel: channel.id, since: id - 1, limit: 1 });
+            // The window can return a NEIGHBOURING row when this id is not in that
+            // channel, so match the id explicitly — delivering the wrong message
+            // would be worse than delivering none.
+            return page.messages.find((m) => m.id === id) ?? null;
+        }
+        catch {
+            // One unreachable channel must not hide a message sitting in another.
+            return null;
+        }
+    }));
+    const message = found.find((m) => m !== null) ?? null;
+    // The read row carries `targets` as a JSON string; parse it to the array
+    // `shouldDeliver` gates on. Done here so both the live push and the reconnect
+    // catch-up (which resolve through this function) see the same parsed shape.
+    if (message)
+        message.targets = parseTargets(message.targets);
+    return message;
+}
+//# sourceMappingURL=resolve.js.map

package/dist/resolve.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"resolve.js","sourceRoot":"","sources":["../src/resolve.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AA0BH;;;4DAG4D;AAC5D,MAAM,UAAU,YAAY,CAAC,GAAY;IACvC,IAAI,KAAK,GAAY,GAAG,CAAC;IACzB,IAAI,OAAO,GAAG,KAAK,QAAQ,EAAE,CAAC;QAC5B,IAAI,GAAG,CAAC,IAAI,EAAE,KAAK,EAAE;YAAE,OAAO,SAAS,CAAC;QACxC,IAAI,CAAC;YACH,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;QAC1B,CAAC;QAAC,MAAM,CAAC;YACP,OAAO,SAAS,CAAC;QACnB,CAAC;IACH,CAAC;IACD,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC;QAAE,OAAO,SAAS,CAAC;IAC5C,MAAM,GAAG,GAAoB,EAAE,CAAC;IAChC,KAAK,MAAM,KAAK,IAAI,KAAK,EAAE,CAAC;QAC1B,IAAI,KAAK,IAAI,OAAO,KAAK,KAAK,QAAQ,EAAE,CAAC;YACvC,MAAM,IAAI,GAAI,KAAiC,CAAC,IAAI,CAAC;YACrD,MAAM,EAAE,GAAI,KAAiC,CAAC,EAAE,CAAC;YACjD,IAAI,OAAO,IAAI,KAAK,QAAQ,IAAI,OAAO,EAAE,KAAK,QAAQ;gBAAE,GAAG,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,EAAE,EAAE,CAAC,CAAC;QACjF,CAAC;IACH,CAAC;IACD,OAAO,GAAG,CAAC,MAAM,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,SAAS,CAAC;AACtC,CAAC;AAYD;;;;;;GAMG;AACH,MAAM,CAAC,KAAK,UAAU,cAAc,CAClC,MAAqB,EACrB,EAAU;IAEV,IAAI,QAA+B,CAAC;IACpC,IAAI,CAAC;QACH,QAAQ,GAAG,MAAM,MAAM,CAAC,YAAY,EAAE,CAAC;IACzC,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,IAAI,CAAC;IACd,CAAC;IAED,MAAM,KAAK,GAAG,MAAM,OAAO,CAAC,GAAG,CAC7B,QAAQ,CAAC,GAAG,CAAC,KAAK,EAAE,OAAO,EAAE,EAAE;QAC7B,IAAI,CAAC;YACH,yEAAyE;YACzE,0EAA0E;YAC1E,kBAAkB;YAClB,MAAM,IAAI,GAAG,MAAM,MAAM,CAAC,YAAY,CAAC,EAAE,OAAO,EAAE,OAAO,CAAC,EAAE,EAAE,KAAK,EAAE,EAAE,GAAG,CAAC,EAAE,KAAK,EAAE,CAAC,EAAE,CAAC,CAAC;YACzF,uEAAuE;YACvE,qEAAqE;YACrE,uCAAuC;YACvC,OAAO,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,IAAI,IAAI,CAAC;QACxD,CAAC;QAAC,MAAM,CAAC;YACP,sEAAsE;YACtE,OAAO,IAAI,CAAC;QACd,CAAC;IACH,CAAC,CAAC,CACH,CAAC;IAEF,MAAM,OAAO,GAAG,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,EAAwB,EAAE,CAAC,CAAC,KAAK,IAAI,CAAC,IAAI,IAAI,CAAC;IAC5E,yEAAyE;IACzE,8EAA8E;IAC9E,4EAA4E;IAC5E,IAAI,OAAO;QAAE,OAAO,CAAC,OAAO,GAAG,YAAY,CAAE,OAAiC,CAAC,OAAO,CAAC,CAAC;IACxF,OAAO,OAAO,CAAC;AACjB,CAAC"}

package/dist/runtime.d.ts

@@ -0,0 +1,54 @@
+/**
+ * Everything that runs ONCE THERE IS A LIVE SESSION: the agent event stream
+ * (message delivery, prompt replay, terminal keys) and the tmux pane mirror.
+ *
+ * Extracted from `index.ts` because two callers need it — the bin entry at
+ * startup, and `select_profile` once a human has chosen an identity — and
+ * because a 170-line closure inside a bin entry is not a unit anyone can
+ * reason about.
+ *
+ * The pane is optional. Without one there is nothing to mirror and nowhere to
+ * type a message, so only the parts that need a pane are skipped; the session
+ * itself is already live and `check_messages` still works.
+ *
+ * It also holds the STARTUP entry (`startAgent`) and the two ways in — the bin
+ * entry at boot, and `select_profile` once a human has chosen an identity — so
+ * both take exactly the same path to a live agent.
+ */
+import type { ConnectedContext } from "./connect.js";
+import { type ResolvedProfile } from "./config.js";
+/**
+ * Attach the event stream (and, with a pane, the terminal mirror) to a live
+ * session.
+ *
+ * Returns a teardown that detaches BOTH. A profile switch must be able to call
+ * it: the mirror keeps calling `appendFrame(oldSession, …)` every couple of
+ * seconds and the backend reads a frame as proof of life, so an abandoned
+ * runtime keeps the OLD identity online in the dashboard however thoroughly its
+ * heartbeat was stopped — and its SSE stream keeps delivering that identity's
+ * DMs into this pane and marking them read as it. Idempotent.
+ */
+export declare function startAgentRuntime(ctx: ConnectedContext, log: (line: string) => void): () => void;
+/**
+ * Bring this agent online: resolve which identity this terminal is, then
+ * connect and start the runtime. When the repo defines several identities and
+ * nothing says which one this is, connect NOTHING and record `needs_profile` —
+ * guessing would silently collapse two terminals into one agent.
+ *
+ * Deliberately NOT conditional on tmux: registering a session is what makes the
+ * agent visible and reachable, and that must happen whether or not there is a
+ * pane to mirror.
+ */
+export declare function startAgent(options?: {
+    configPath?: string;
+}): Promise<void>;
+/**
+ * Connect as a known profile and start the runtime. Used by `select_profile`.
+ *
+ * Nothing is awaited: `startConnection`'s `settled` stays pending for as long as
+ * the backend is down, so awaiting it here would keep the MCP server from
+ * serving a single tool call until the backend came up.
+ */
+export declare function connectAs(profile: ResolvedProfile, pane: string | null): void;
+/** Persist a human's pick for this terminal, then connect as it. */
+export declare function selectProfile(profile: ResolvedProfile): Promise<void>;