charness 0.0.0-stage → 3.1.0

package/dist/mcpConfig.d.ts

@@ -0,0 +1,76 @@
+/**
+ * @description MCP-config plumbing for the Claude CLI.
+ *
+ * Claude resolves MCP servers from four places:
+ *   1. `~/.claude/settings.json` — user level, picked up automatically.
+ *   2. `${DATA_DIR}/mcp.json` — group level (this instance), passed via
+ *      `--mcp-config` so two bot instances under the same Linux user can
+ *      have different MCP fleets.
+ *   3. `${workDir}/.mcp.json` — project level, picked up automatically
+ *      from cwd.
+ *   4. `${DATA_DIR}/threads/<key>.json` — optional per-thread override,
+ *      passed via a second `--mcp-config`.
+ *
+ * Plan §19.1 / §19.7 / D25-D33.
+ *
+ * This module owns two responsibilities:
+ *   - **`${VAR}` expansion**. Claude CLI does NOT shell-expand placeholders
+ *     inside `--mcp-config` JSON (plan §13.18, T2), so the bot resolves
+ *     them itself against `process.env` and writes the expanded copy to a
+ *     short-lived tmp file (mode 0600) before passing the tmp path to
+ *     Claude.
+ *   - **Lifecycle**. Tmp files are stable per SessionKey (one for group
+ *     scope, one for thread scope), so multiple `startSession` calls don't
+ *     pile up junk. `cleanupMcpTempFiles` is called from
+ *     `claudeCliAdapter.stopSession` to remove them once the session ends.
+ */
+import type { SessionKey } from './sessionKey';
+export interface PrepareMcpOptions {
+    key: SessionKey;
+    dataDir: string;
+}
+/**
+ * @description Recursively replace `${VAR}` placeholders in every *string*
+ * value of a JSON-shaped value. Unknown env-vars are left as-is — that lets
+ * a half-configured environment surface the placeholder verbatim instead of
+ * silently substituting empty strings (which often pass auth checks).
+ *
+ * Only the `${VAR}` form is supported; `$VAR` is intentionally ignored
+ * because it'd false-match shell substitutions baked into command strings
+ * (e.g. `bash -c '$HOME/...'`).
+ */
+export declare function expandEnvVars<T>(node: T): T;
+/**
+ * @description Build the `--mcp-config <path>` argument pairs to interleave
+ * into the Claude CLI invocation for a fresh or resumed session. Returns
+ * an empty array when neither group nor thread level has a config — claude
+ * will then rely solely on the auto-loaded user + project files, which is
+ * the right default for a bot that hasn't been configured with bespoke
+ * tooling yet.
+ *
+ * The user-config reads are sync (`fs.*Sync`) on purpose — both source files
+ * combined are kept under a few KB by design. The function is async only to
+ * await the bot's scheduler MCP config (plan S6), which mints a scope token via
+ * the persisted HMAC secret. When scheduler injection is inert (S8 not wired)
+ * {@link buildClaudeSchedulerMcpConfig} returns `null`, so the output is
+ * byte-identical to the pre-scheduler behavior — only the user's group/thread
+ * configs are emitted.
+ *
+ * A session of any platform but Telegram starts with `--strict-mcp-config`
+ * (Jira connector plan J2, D17): it gets exactly the configs passed here — the
+ * bot's MCP plus the operator's `DATA_DIR/mcp.json` and
+ * `DATA_DIR/threads/<key>.json` — and nothing from the user or project MCP
+ * config, whose servers reach other tenants under the operator's own keys. It
+ * also drops the claude.ai account connectors (J3b, R8 — probed on Claude Code
+ * 2.1.287: the `system/init` `mcp_servers` listed three `claude.ai …` connectors
+ * without it and none with it), so no further switch is needed.
+ */
+export declare function prepareMcpFlags(opts: PrepareMcpOptions): Promise<string[]>;
+/**
+ * @description Remove the tmp MCP files we wrote for this thread. Called
+ * from `claudeCliAdapter.stopSession` so secrets don't linger after the
+ * session ends. Missing files are silently ignored — `stopSession` may run
+ * for a thread that never had MCP configured.
+ */
+export declare function cleanupMcpTempFiles(opts: PrepareMcpOptions): void;
+//# sourceMappingURL=mcpConfig.d.ts.map

package/dist/mcpConfig.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mcpConfig.d.ts","sourceRoot":"","sources":["../src/mcpConfig.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAIH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAS/C,MAAM,WAAW,iBAAiB;IAChC,GAAG,EAAE,UAAU,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;CACjB;AAED;;;;;;;;;GASG;AACH,wBAAgB,aAAa,CAAC,CAAC,EAAE,IAAI,EAAE,CAAC,GAAG,CAAC,CAqB3C;AAiGD;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,wBAAsB,eAAe,CAAC,IAAI,EAAE,iBAAiB,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CA4BhF;AAED;;;;;GAKG;AACH,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,iBAAiB,GAAG,IAAI,CAajE"}

package/dist/mcpConfig.js

@@ -0,0 +1,270 @@
+"use strict";
+/**
+ * @description MCP-config plumbing for the Claude CLI.
+ *
+ * Claude resolves MCP servers from four places:
+ *   1. `~/.claude/settings.json` — user level, picked up automatically.
+ *   2. `${DATA_DIR}/mcp.json` — group level (this instance), passed via
+ *      `--mcp-config` so two bot instances under the same Linux user can
+ *      have different MCP fleets.
+ *   3. `${workDir}/.mcp.json` — project level, picked up automatically
+ *      from cwd.
+ *   4. `${DATA_DIR}/threads/<key>.json` — optional per-thread override,
+ *      passed via a second `--mcp-config`.
+ *
+ * Plan §19.1 / §19.7 / D25-D33.
+ *
+ * This module owns two responsibilities:
+ *   - **`${VAR}` expansion**. Claude CLI does NOT shell-expand placeholders
+ *     inside `--mcp-config` JSON (plan §13.18, T2), so the bot resolves
+ *     them itself against `process.env` and writes the expanded copy to a
+ *     short-lived tmp file (mode 0600) before passing the tmp path to
+ *     Claude.
+ *   - **Lifecycle**. Tmp files are stable per SessionKey (one for group
+ *     scope, one for thread scope), so multiple `startSession` calls don't
+ *     pile up junk. `cleanupMcpTempFiles` is called from
+ *     `claudeCliAdapter.stopSession` to remove them once the session ends.
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.expandEnvVars = expandEnvVars;
+exports.prepareMcpFlags = prepareMcpFlags;
+exports.cleanupMcpTempFiles = cleanupMcpTempFiles;
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+const sessionKey_1 = require("./sessionKey");
+const injection_1 = require("./scheduler/injection");
+/** The platform whose sessions keep the user's and project's own MCP servers. */
+const telegramPlatform = 'telegram';
+/** Claude Code: use only the `--mcp-config` files, ignore every other MCP configuration. */
+const strictMcpConfigFlag = '--strict-mcp-config';
+/**
+ * @description Recursively replace `${VAR}` placeholders in every *string*
+ * value of a JSON-shaped value. Unknown env-vars are left as-is — that lets
+ * a half-configured environment surface the placeholder verbatim instead of
+ * silently substituting empty strings (which often pass auth checks).
+ *
+ * Only the `${VAR}` form is supported; `$VAR` is intentionally ignored
+ * because it'd false-match shell substitutions baked into command strings
+ * (e.g. `bash -c '$HOME/...'`).
+ */
+function expandEnvVars(node) {
+    if (typeof node === 'string') {
+        // Only the uppercase `${VAR}` form is recognised — matches POSIX env-var
+        // convention and dodges false matches inside command strings that
+        // happen to contain `${path}`-shaped placeholders for downstream tools.
+        return node.replace(/\$\{([A-Z_][A-Z0-9_]*)\}/g, (m, name) => {
+            const value = process.env[name];
+            return value !== undefined ? value : m;
+        });
+    }
+    if (Array.isArray(node)) {
+        return node.map(expandEnvVars);
+    }
+    if (node !== null && typeof node === 'object') {
+        const out = {};
+        for (const [k, v] of Object.entries(node)) {
+            out[k] = expandEnvVars(v);
+        }
+        return out;
+    }
+    return node;
+}
+/**
+ * @description Read a JSON file, apply `${VAR}` expansion and write the
+ * expanded copy to a sibling tmp path with `0600` perms. The tmp directory
+ * is created with `0700` so other users on the same host can't sniff
+ * secrets even briefly.
+ *
+ * Returns the absolute tmp path on success, `null` if the source file
+ * doesn't exist (legitimate — the operator just hasn't configured this
+ * level), or if parsing failed (we surface a console warning rather than
+ * propagating, so a broken config can't gate the whole agent start).
+ */
+function writeExpandedTmp(sourcePath, tmpPath) {
+    let raw;
+    try {
+        raw = fs.readFileSync(sourcePath, 'utf8');
+    }
+    catch (e) {
+        if (e.code === 'ENOENT')
+            return null;
+        console.warn(`[mcp] cannot read ${sourcePath}:`, e);
+        return null;
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch (e) {
+        console.warn(`[mcp] invalid JSON in ${sourcePath}, skipping:`, e);
+        return null;
+    }
+    const expanded = expandEnvVars(parsed);
+    fs.mkdirSync(path.dirname(tmpPath), { recursive: true, mode: 0o700 });
+    // Truncating write into a fixed per-key path: one tmp file per (key,
+    // scope) means a second startSession overwrites the previous one rather
+    // than piling up junk. `chmodSync` immediately after the write tightens
+    // perms in case the umask widened the openSync mode.
+    try {
+        const fd = fs.openSync(tmpPath, 'w', 0o600);
+        try {
+            fs.writeFileSync(fd, JSON.stringify(expanded));
+        }
+        finally {
+            fs.closeSync(fd);
+        }
+        fs.chmodSync(tmpPath, 0o600);
+    }
+    catch (e) {
+        console.warn(`[mcp] cannot write tmp ${tmpPath}:`, e);
+        return null;
+    }
+    return tmpPath;
+}
+function groupMcpSource(dataDir) {
+    return path.join(dataDir, 'mcp.json');
+}
+function threadMcpSource(dataDir, key) {
+    return path.join(dataDir, 'threads', `${(0, sessionKey_1.keyToString)(key)}.json`);
+}
+function groupMcpTmp(dataDir, key) {
+    return path.join(dataDir, 'tmp', `mcp-${(0, sessionKey_1.keyToString)(key)}-group.json`);
+}
+function threadMcpTmp(dataDir, key) {
+    return path.join(dataDir, 'tmp', `mcp-${(0, sessionKey_1.keyToString)(key)}-thread.json`);
+}
+/**
+ * Bot-OWNED scheduler MCP config tmp (plan S6). A third `--mcp-config` whose
+ * contents the bot generates from {@link buildClaudeSchedulerMcpConfig} — it
+ * never touches the user's group/thread files. Distinct per-key filename so a
+ * second startSession overwrites rather than piling up, matching the group/
+ * thread tmp convention.
+ */
+function schedulerMcpTmp(dataDir, key) {
+    return path.join(dataDir, 'tmp', `mcp-${(0, sessionKey_1.keyToString)(key)}-scheduler.json`);
+}
+/**
+ * @description Write an already-built JSON config object to a bot-owned tmp with
+ * the same `0700` dir / `0600` file conventions as {@link writeExpandedTmp}. No
+ * `${VAR}` expansion: the bot generated this object itself (the only `${VAR}`
+ * concern is user-authored configs). Returns the tmp path, or `null` if the write
+ * failed (a broken scheduler config must never gate the agent start).
+ */
+function writeGeneratedTmp(config, tmpPath) {
+    fs.mkdirSync(path.dirname(tmpPath), { recursive: true, mode: 0o700 });
+    try {
+        const fd = fs.openSync(tmpPath, 'w', 0o600);
+        try {
+            fs.writeFileSync(fd, JSON.stringify(config));
+        }
+        finally {
+            fs.closeSync(fd);
+        }
+        fs.chmodSync(tmpPath, 0o600);
+    }
+    catch (e) {
+        console.warn(`[mcp] cannot write tmp ${tmpPath}:`, e);
+        return null;
+    }
+    return tmpPath;
+}
+/**
+ * @description Build the `--mcp-config <path>` argument pairs to interleave
+ * into the Claude CLI invocation for a fresh or resumed session. Returns
+ * an empty array when neither group nor thread level has a config — claude
+ * will then rely solely on the auto-loaded user + project files, which is
+ * the right default for a bot that hasn't been configured with bespoke
+ * tooling yet.
+ *
+ * The user-config reads are sync (`fs.*Sync`) on purpose — both source files
+ * combined are kept under a few KB by design. The function is async only to
+ * await the bot's scheduler MCP config (plan S6), which mints a scope token via
+ * the persisted HMAC secret. When scheduler injection is inert (S8 not wired)
+ * {@link buildClaudeSchedulerMcpConfig} returns `null`, so the output is
+ * byte-identical to the pre-scheduler behavior — only the user's group/thread
+ * configs are emitted.
+ *
+ * A session of any platform but Telegram starts with `--strict-mcp-config`
+ * (Jira connector plan J2, D17): it gets exactly the configs passed here — the
+ * bot's MCP plus the operator's `DATA_DIR/mcp.json` and
+ * `DATA_DIR/threads/<key>.json` — and nothing from the user or project MCP
+ * config, whose servers reach other tenants under the operator's own keys. It
+ * also drops the claude.ai account connectors (J3b, R8 — probed on Claude Code
+ * 2.1.287: the `system/init` `mcp_servers` listed three `claude.ai …` connectors
+ * without it and none with it), so no further switch is needed.
+ */
+async function prepareMcpFlags(opts) {
+    const flags = opts.key.platform === telegramPlatform ? [] : [strictMcpConfigFlag];
+    const groupPath = writeExpandedTmp(groupMcpSource(opts.dataDir), groupMcpTmp(opts.dataDir, opts.key));
+    if (groupPath)
+        flags.push('--mcp-config', groupPath);
+    const threadPath = writeExpandedTmp(threadMcpSource(opts.dataDir, opts.key), threadMcpTmp(opts.dataDir, opts.key));
+    if (threadPath)
+        flags.push('--mcp-config', threadPath);
+    // Bot-generated scheduler MCP config: NEVER touches the user's files. Inert
+    // (null) until S8 configures injection — then a third `--mcp-config` carrying
+    // the thread-scoped token reaches Claude.
+    const schedulerConfig = await (0, injection_1.buildClaudeSchedulerMcpConfig)(opts.key);
+    if (schedulerConfig) {
+        const schedulerPath = writeGeneratedTmp(schedulerConfig, schedulerMcpTmp(opts.dataDir, opts.key));
+        if (schedulerPath)
+            flags.push('--mcp-config', schedulerPath);
+    }
+    return flags;
+}
+/**
+ * @description Remove the tmp MCP files we wrote for this thread. Called
+ * from `claudeCliAdapter.stopSession` so secrets don't linger after the
+ * session ends. Missing files are silently ignored — `stopSession` may run
+ * for a thread that never had MCP configured.
+ */
+function cleanupMcpTempFiles(opts) {
+    for (const tmp of [
+        groupMcpTmp(opts.dataDir, opts.key),
+        threadMcpTmp(opts.dataDir, opts.key),
+        schedulerMcpTmp(opts.dataDir, opts.key),
+    ]) {
+        try {
+            fs.unlinkSync(tmp);
+        }
+        catch (e) {
+            if (e.code !== 'ENOENT') {
+                console.warn(`[mcp] failed to remove ${tmp}:`, e);
+            }
+        }
+    }
+}
+//# sourceMappingURL=mcpConfig.js.map

package/dist/mcpConfig.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"mcpConfig.js","sourceRoot":"","sources":["../src/mcpConfig.ts"],"names":[],"mappings":"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"}

package/dist/openCodeOpenQuestion.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Pure helpers for recovering an OpenCode question that the bot lost track of.
+ *
+ * An OpenCode `question` tool blocks its assistant turn (`state.status =
+ * "running"`) until answered via `POST /question/:requestId/reply`. The bot
+ * only treats a free-form user message as the ANSWER when its in-memory
+ * `pendingQuestions` map holds an entry. Two situations leave the map empty
+ * while a question is still open on the server — a bot restart (the reattach
+ * path rebuilds the session with `pendingQuestion: null`) and an
+ * `question.asked` event that was dropped at ask time — and then the topic
+ * hangs forever (answers can't break out; a fresh prompt queues behind the
+ * blocked turn).
+ *
+ * `GET /question?directory=<workDir>` exposes the server's live open questions
+ * for an instance as a JSON array; this module turns that array into the same
+ * {@link OpenCodePendingQuestion} the live `question.asked` path produces, so a
+ * reattach can re-surface it and a wedged-turn check can detect it. Kept PURE
+ * (no network) so it is unit-testable; the adapter owns the `GET`.
+ */
+import type { OpenCodePendingQuestion, OpenCodeQuestion } from './types';
+/**
+ * @description One entry of the `GET /question` response array. The reply id is
+ * the top-level `id` (`que_…`) — NOT `tool.callID` (`toolu_…`). Only the fields
+ * the bot needs are declared; the server may send more.
+ */
+export interface OpenCodeOpenQuestionEntry {
+    id: string;
+    sessionID: string;
+    questions: OpenCodeQuestion[];
+}
+/**
+ * @description Find the open question owned by `sessionId` in a `GET /question`
+ * response and rebuild it into the {@link OpenCodePendingQuestion} shape the
+ * rest of the bot already understands (`requestId` = the entry's `id`, the
+ * `questions` array, and the owning `directory` so the eventual reply targets
+ * the right project instance).
+ *
+ * Returns `null` when the response is not an array, holds no entry for this
+ * session, or the matching entry is malformed — i.e. "there is no open question
+ * to recover for this session". Pure: the adapter does the `GET` and passes the
+ * already-parsed JSON in here.
+ */
+export declare function getOpenQuestionForSession(response: unknown, sessionId: string, workDir: string): OpenCodePendingQuestion | null;
+//# sourceMappingURL=openCodeOpenQuestion.d.ts.map

package/dist/openCodeOpenQuestion.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"openCodeOpenQuestion.d.ts","sourceRoot":"","sources":["../src/openCodeOpenQuestion.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,OAAO,KAAK,EAAE,uBAAuB,EAAE,gBAAgB,EAAE,MAAM,SAAS,CAAC;AAEzE;;;;GAIG;AACH,MAAM,WAAW,yBAAyB;IACxC,EAAE,EAAE,MAAM,CAAC;IACX,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,gBAAgB,EAAE,CAAC;CAC/B;AAiBD;;;;;;;;;;;GAWG;AACH,wBAAgB,yBAAyB,CACvC,QAAQ,EAAE,OAAO,EACjB,SAAS,EAAE,MAAM,EACjB,OAAO,EAAE,MAAM,GACd,uBAAuB,GAAG,IAAI,CAWhC"}

package/dist/openCodeOpenQuestion.js

@@ -0,0 +1,64 @@
+"use strict";
+/**
+ * Pure helpers for recovering an OpenCode question that the bot lost track of.
+ *
+ * An OpenCode `question` tool blocks its assistant turn (`state.status =
+ * "running"`) until answered via `POST /question/:requestId/reply`. The bot
+ * only treats a free-form user message as the ANSWER when its in-memory
+ * `pendingQuestions` map holds an entry. Two situations leave the map empty
+ * while a question is still open on the server — a bot restart (the reattach
+ * path rebuilds the session with `pendingQuestion: null`) and an
+ * `question.asked` event that was dropped at ask time — and then the topic
+ * hangs forever (answers can't break out; a fresh prompt queues behind the
+ * blocked turn).
+ *
+ * `GET /question?directory=<workDir>` exposes the server's live open questions
+ * for an instance as a JSON array; this module turns that array into the same
+ * {@link OpenCodePendingQuestion} the live `question.asked` path produces, so a
+ * reattach can re-surface it and a wedged-turn check can detect it. Kept PURE
+ * (no network) so it is unit-testable; the adapter owns the `GET`.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getOpenQuestionForSession = getOpenQuestionForSession;
+/**
+ * @description Narrow an unknown `GET /question` array element to a usable open
+ * question entry. Guards every field the rebuild reads so a malformed element
+ * (missing id / sessionID / non-array questions) is skipped rather than crashing
+ * the reattach. Returns `null` for anything that does not match the shape.
+ */
+function getOpenQuestionEntry(value) {
+    if (!value || typeof value !== 'object')
+        return null;
+    const entry = value;
+    if (typeof entry.id !== 'string' || entry.id.length === 0)
+        return null;
+    if (typeof entry.sessionID !== 'string' || entry.sessionID.length === 0)
+        return null;
+    if (!Array.isArray(entry.questions) || entry.questions.length === 0)
+        return null;
+    return { id: entry.id, sessionID: entry.sessionID, questions: entry.questions };
+}
+/**
+ * @description Find the open question owned by `sessionId` in a `GET /question`
+ * response and rebuild it into the {@link OpenCodePendingQuestion} shape the
+ * rest of the bot already understands (`requestId` = the entry's `id`, the
+ * `questions` array, and the owning `directory` so the eventual reply targets
+ * the right project instance).
+ *
+ * Returns `null` when the response is not an array, holds no entry for this
+ * session, or the matching entry is malformed — i.e. "there is no open question
+ * to recover for this session". Pure: the adapter does the `GET` and passes the
+ * already-parsed JSON in here.
+ */
+function getOpenQuestionForSession(response, sessionId, workDir) {
+    if (!Array.isArray(response))
+        return null;
+    for (const element of response) {
+        const entry = getOpenQuestionEntry(element);
+        if (entry && entry.sessionID === sessionId) {
+            return { requestId: entry.id, questions: entry.questions, directory: workDir };
+        }
+    }
+    return null;
+}
+//# sourceMappingURL=openCodeOpenQuestion.js.map

package/dist/openCodeOpenQuestion.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"openCodeOpenQuestion.js","sourceRoot":"","sources":["../src/openCodeOpenQuestion.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;;GAkBG;;AA0CH,8DAeC;AA1CD;;;;;GAKG;AACH,SAAS,oBAAoB,CAAC,KAAc;IAC1C,IAAI,CAAC,KAAK,IAAI,OAAO,KAAK,KAAK,QAAQ;QAAE,OAAO,IAAI,CAAC;IACrD,MAAM,KAAK,GAAG,KAAgC,CAAC;IAC/C,IAAI,OAAO,KAAK,CAAC,EAAE,KAAK,QAAQ,IAAI,KAAK,CAAC,EAAE,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,IAAI,CAAC;IACvE,IAAI,OAAO,KAAK,CAAC,SAAS,KAAK,QAAQ,IAAI,KAAK,CAAC,SAAS,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,IAAI,CAAC;IACrF,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,SAAS,CAAC,IAAI,KAAK,CAAC,SAAS,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,IAAI,CAAC;IACjF,OAAO,EAAE,EAAE,EAAE,KAAK,CAAC,EAAE,EAAE,SAAS,EAAE,KAAK,CAAC,SAAS,EAAE,SAAS,EAAE,KAAK,CAAC,SAA+B,EAAE,CAAC;AACxG,CAAC;AAED;;;;;;;;;;;GAWG;AACH,SAAgB,yBAAyB,CACvC,QAAiB,EACjB,SAAiB,EACjB,OAAe;IAEf,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,QAAQ,CAAC;QAAE,OAAO,IAAI,CAAC;IAE1C,KAAK,MAAM,OAAO,IAAI,QAAQ,EAAE,CAAC;QAC/B,MAAM,KAAK,GAAG,oBAAoB,CAAC,OAAO,CAAC,CAAC;QAC5C,IAAI,KAAK,IAAI,KAAK,CAAC,SAAS,KAAK,SAAS,EAAE,CAAC;YAC3C,OAAO,EAAE,SAAS,EAAE,KAAK,CAAC,EAAE,EAAE,SAAS,EAAE,KAAK,CAAC,SAAS,EAAE,SAAS,EAAE,OAAO,EAAE,CAAC;QACjF,CAAC;IACH,CAAC;IAED,OAAO,IAAI,CAAC;AACd,CAAC"}

package/dist/openCodeQuestionFlow.d.ts

@@ -0,0 +1,105 @@
+/**
+ * @description Pure logic for the OpenCode interactive-question UX (plan
+ * `2026-06-09-question-ux.md`, scopes S1 + S2). Kept side-effect-free so the
+ * tricky parts — rendering option descriptions and the sequential
+ * multi-question answer collection — are exhaustively unit-testable without a
+ * live Telegram round-trip (the answer path real topics depend on; a bug here
+ * silently breaks question answering and can't be force-triggered on demand).
+ *
+ * The bot (`bot.ts`) owns all I/O: it calls {@link buildQuestionBodyLines} to
+ * render a question's text body, and drives the answer state machine via
+ * {@link recordAnswerAndAdvance}, then performs the resulting Telegram send /
+ * agent reply.
+ */
+import type { OpenCodeQuestion, PendingQuestionState } from './types';
+/**
+ * @description Build the message-BODY text lines for ONE question: the header,
+ * the question text (only when it differs from the header), then the numbered
+ * option labels each followed by its description (S1 — descriptions were
+ * previously discarded even though OpenCode delivers them).
+ *
+ * The numbering is 1-based and lines up with the inline option buttons
+ * (`qa_<qIdx>_<optIdx>`), so a user can answer by tapping a button OR by typing
+ * the digit. Descriptions go ONLY in the body (indented under the label), never
+ * on the button — buttons stay label-only under Telegram's 40-char cap.
+ *
+ * `escape` is injected (Markdown or HTML escaper) so this stays pure and
+ * backend-agnostic; the bot passes its own `escapeMarkdown`.
+ */
+export declare function buildQuestionBodyLines(question: OpenCodeQuestion, escape: (text: string) => string): string[];
+/**
+ * @description Build the same body as {@link buildQuestionBodyLines} but with NO
+ * escaping and no bold markers — the plain-text fallback used when Telegram
+ * rejects the Markdown render of a question.
+ */
+export declare function buildQuestionBodyLinesPlain(question: OpenCodeQuestion): string[];
+/**
+ * @description How to route a user's free-form reply that arrives WHILE an
+ * OpenCode interactive question is pending. Mirrors `getClaudeReplyRoute`:
+ *  - `answer` — the reply is a bare digit in range of the current question's
+ *    options, so it PICKS that option (`labels` are the chosen option labels,
+ *    the same a button tap would send);
+ *  - `cancel` — any other free-form input (prose, an out-of-range digit, a voice
+ *    transcript): the user means "move on", so the bot cancels the question and
+ *    delivers the text as a fresh prompt instead of treating it as the answer.
+ */
+export type QuestionReplyRoute = {
+    kind: 'answer';
+    labels: string[];
+} | {
+    kind: 'cancel';
+};
+/**
+ * @description Decide how to route a user's reply for a thread that has an
+ * OpenCode question on screen. Pure so the digit-in-range precedence is
+ * unit-testable without a live session.
+ *
+ * Only a bare 1-based digit in range of `currentQuestion.options` answers; any
+ * other text (out-of-range digit, prose, empty) cancels. A digit answer carries
+ * the chosen option label(s) so the caller never re-parses the digit (single
+ * source of truth for the digit→label mapping).
+ */
+export declare function getQuestionReplyRoute(text: string, currentQuestion: OpenCodeQuestion | undefined): QuestionReplyRoute;
+/**
+ * @description Outcome of recording one answer into the pending-question state.
+ * Either the bot must SHOW the next unanswered question (`showQuestion`, with
+ * the new `currentIndex`), or every question is now answered and the bot must
+ * SUBMIT the full answer matrix to the agent (`submit`).
+ */
+export type AnswerAdvanceAction = {
+    kind: 'showQuestion';
+    index: number;
+} | {
+    kind: 'submit';
+    matrix: string[][];
+};
+/**
+ * @description Record the user's answer for the CURRENTLY shown question and
+ * decide what happens next (S2 — sequential multi-question + local answer
+ * collection). Pure: returns the mutated-copy state plus the action; the bot
+ * performs the side effect (post the next question OR reply to the agent).
+ *
+ * The bug this fixes: the old handler closed the whole request on the first
+ * answer, sending EMPTY answers for every other question. Here we only submit
+ * once NO slot is left `null`.
+ *
+ * `answerForCurrent` is the chosen option label(s) or the typed text, wrapped
+ * as a one-element array per OpenCode's `string[][]` matrix shape.
+ */
+export declare function recordAnswerAndAdvance(state: PendingQuestionState, answerForCurrent: string[]): {
+    nextState: PendingQuestionState;
+    action: AnswerAdvanceAction;
+};
+/**
+ * @description Restore-compat guard for {@link PendingQuestionState} (S2). The
+ * persisted shape grew `answers` + `currentIndex`; an OLD `state.json` entry
+ * written before this change has only `{ data, messageId }`. Returning it raw
+ * would leave `answers`/`currentIndex` undefined and crash the answer handlers
+ * at boot. This normalises any restored entry to the new shape:
+ *  - missing/mismatched-length `answers` → rebuilt as `[null…]` sized to the
+ *    question count (the user must re-answer — the in-progress local answers
+ *    were never sent to the agent anyway);
+ *  - missing/out-of-range `currentIndex` → `0`.
+ */
+export declare function migratePendingQuestionState(raw: PendingQuestionState): PendingQuestionState;
+//# sourceMappingURL=openCodeQuestionFlow.d.ts.map

package/dist/openCodeQuestionFlow.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"openCodeQuestionFlow.d.ts","sourceRoot":"","sources":["../src/openCodeQuestionFlow.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,KAAK,EAAE,gBAAgB,EAAE,oBAAoB,EAAE,MAAM,SAAS,CAAC;AAEtE;;;;;;;;;;;;;GAaG;AACH,wBAAgB,sBAAsB,CACpC,QAAQ,EAAE,gBAAgB,EAC1B,MAAM,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,MAAM,GAC/B,MAAM,EAAE,CAcV;AAED;;;;GAIG;AACH,wBAAgB,2BAA2B,CAAC,QAAQ,EAAE,gBAAgB,GAAG,MAAM,EAAE,CAWhF;AAED;;;;;;;;;GASG;AACH,MAAM,MAAM,kBAAkB,GAC1B;IAAE,IAAI,EAAE,QAAQ,CAAC;IAAC,MAAM,EAAE,MAAM,EAAE,CAAA;CAAE,GACpC;IAAE,IAAI,EAAE,QAAQ,CAAA;CAAE,CAAC;AAEvB;;;;;;;;;GASG;AACH,wBAAgB,qBAAqB,CACnC,IAAI,EAAE,MAAM,EACZ,eAAe,EAAE,gBAAgB,GAAG,SAAS,GAC5C,kBAAkB,CAQpB;AAED;;;;;GAKG;AACH,MAAM,MAAM,mBAAmB,GAC3B;IAAE,IAAI,EAAE,cAAc,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,GACvC;IAAE,IAAI,EAAE,QAAQ,CAAC;IAAC,MAAM,EAAE,MAAM,EAAE,EAAE,CAAA;CAAE,CAAC;AAE3C;;;;;;;;;;;;GAYG;AACH,wBAAgB,sBAAsB,CACpC,KAAK,EAAE,oBAAoB,EAC3B,gBAAgB,EAAE,MAAM,EAAE,GACzB;IAAE,SAAS,EAAE,oBAAoB,CAAC;IAAC,MAAM,EAAE,mBAAmB,CAAA;CAAE,CAoBlE;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,2BAA2B,CAAC,GAAG,EAAE,oBAAoB,GAAG,oBAAoB,CAe3F"}