charness 0.0.0-stage → 3.1.0

package/dist/utils/tmuxSessionName.js

@@ -0,0 +1,51 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildTmuxSessionName = buildTmuxSessionName;
+exports.parseTmuxSessionName = parseTmuxSessionName;
+const sessionKey_1 = require("../sessionKey");
+/**
+ * @description What every `:` of the serialized key becomes inside a tmux
+ * session name. `keyToString` joins the key's parts with `:`, which tmux treats
+ * as a window/pane address separator, so the name swaps it for `-`.
+ */
+const tmuxKeySeparator = '-';
+/**
+ * @description Tmux session name for a `SessionKey`, namespaced by a backend
+ * `prefix` so different adapters (Claude `claude-…`, terminal `term-…`) never
+ * collide on one tmux server.
+ *
+ * Format: `<prefix>-<serializedKey with ':' → '-'>`, which for Telegram is the
+ * historical `<prefix>-<chatId>-<threadId>`. Negative chat ids (forum
+ * supergroups are negative) keep their minus sign — tmux session names accept
+ * it. The format is `parse`-able back to `SessionKey` via
+ * {@link parseTmuxSessionName} with the SAME prefix.
+ *
+ * The connector's codec owns the serialized halves, so this helper never looks
+ * at platform-specific fields and the on-disk names stay byte-identical.
+ */
+function buildTmuxSessionName(prefix, key) {
+    return `${prefix}-${(0, sessionKey_1.keyToSlug)(key, tmuxKeySeparator)}`;
+}
+/**
+ * @description Inverse of {@link buildTmuxSessionName} for a given `prefix`.
+ * Returns `null` for names that don't parse back to a key (e.g. an unrelated
+ * tmux session a user started by hand, or one owned by a different backend's
+ * prefix).
+ *
+ * The slug after the prefix is read back by the codec that owns it
+ * ({@link tryKeyFromSlug}): Telegram's `claude--1001234-42` parses to
+ * `-1001234:42` (split on the last `-`, whatever the chat id's sign), Jira's
+ * `claude-jira-PROJ-PROJ-12` to `jira:PROJ:PROJ-12`.
+ *
+ * Strictness lives in the codec (audit S1 / #22): plain `Number(...)` accepts
+ * `1e5`, `0x10`, `1.5`, `" 42 "`. Such values come from a foreign tmux session
+ * whose name happens to share our prefix; treating them as ours would cause an
+ * adopt path to attach to an unrelated session.
+ */
+function parseTmuxSessionName(prefix, name) {
+    const head = `${prefix}-`;
+    if (!name.startsWith(head))
+        return null;
+    return (0, sessionKey_1.tryKeyFromSlug)(name.slice(head.length), tmuxKeySeparator);
+}
+//# sourceMappingURL=tmuxSessionName.js.map

package/dist/utils/tmuxSessionName.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tmuxSessionName.js","sourceRoot":"","sources":["../../src/utils/tmuxSessionName.ts"],"names":[],"mappings":";;AAuBA,oDAEC;AAkBD,oDAIC;AA/CD,8CAA2E;AAE3E;;;;GAIG;AACH,MAAM,gBAAgB,GAAG,GAAG,CAAC;AAE7B;;;;;;;;;;;;;GAaG;AACH,SAAgB,oBAAoB,CAAC,MAAc,EAAE,GAAe;IAClE,OAAO,GAAG,MAAM,IAAI,IAAA,sBAAS,EAAC,GAAG,EAAE,gBAAgB,CAAC,EAAE,CAAC;AACzD,CAAC;AAED;;;;;;;;;;;;;;;GAeG;AACH,SAAgB,oBAAoB,CAAC,MAAc,EAAE,IAAY;IAC/D,MAAM,IAAI,GAAG,GAAG,MAAM,GAAG,CAAC;IAC1B,IAAI,CAAC,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC;QAAE,OAAO,IAAI,CAAC;IACxC,OAAO,IAAA,2BAAc,EAAC,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,MAAM,CAAC,EAAE,gBAAgB,CAAC,CAAC;AACnE,CAAC"}

package/dist/utils/toolResultRender.d.ts

@@ -0,0 +1,61 @@
+/**
+ * @description Pure decision + formatting helpers for rendering a completed
+ * tool call's OUTPUT (the OpenCode `toolResult` adapter event, S3). The
+ * adapter emits a mode-AGNOSTIC {@link ToolResultEvent}; the bot's
+ * `handleAgentToolResult` resolves the per-thread tool-results
+ * {@link DisplayVerbosityMode} and
+ * consults {@link getToolResultRenderAction} + {@link getTruncatedToolResult}.
+ * Extracted from `bot.ts` so the mode matrix and the truncation caps are
+ * unit-testable without the Telegraf machinery (same pattern as
+ * `thinkingRender.ts`).
+ */
+import type { DisplayVerbosityMode } from '../types';
+/** `short`-mode line cap — applied BEFORE the char cap. */
+export declare const toolResultMaxLines = 15;
+/** `short`-mode char cap — applied AFTER the line cap. */
+export declare const toolResultMaxChars = 1200;
+/**
+ * @name ToolResultRenderAction
+ * @description What the bot does with a `toolResult` event in a given mode.
+ *
+ * - `full`      — render the whole body, fenced.
+ * - `truncated` — render the body capped by {@link getTruncatedToolResult},
+ *   with a "… (truncated, /tool_results full)" footer when the caps bit.
+ * - `drop`      — render nothing (the transient 🔧 status already showed);
+ *   the `minimal` mode.
+ */
+export type ToolResultRenderAction = 'full' | 'truncated' | 'drop';
+/**
+ * @description Map the per-thread tool-results {@link DisplayVerbosityMode} to
+ * a render action. Pure — the matrix is one line per mode, but keeping it a
+ * named helper makes it unit-testable and keeps `bot.ts` free of mode-string
+ * comparisons (same shape as `getThinkingEventAction`).
+ */
+export declare function getToolResultRenderAction(mode: DisplayVerbosityMode): ToolResultRenderAction;
+/** Result of {@link getTruncatedToolResult}: the (possibly capped) body and
+ * whether any cap actually bit — drives the truncation footer. */
+export interface TruncatedToolResult {
+    text: string;
+    isTruncated: boolean;
+}
+/**
+ * @description Truncate a tool-result body to the `short`-mode caps: first
+ * {@link toolResultMaxLines} lines, then {@link toolResultMaxChars} chars —
+ * whichever cap hits first wins; both may apply. The char cut retreats to the
+ * last newline inside the budget so a line is never split mid-way unless a
+ * single line alone exceeds the whole char budget (then a hard cut is the only
+ * option). A body under both caps is returned unchanged.
+ */
+export declare function getTruncatedToolResult(body: string): TruncatedToolResult;
+/**
+ * @description Wrap a tool-result body in a ```` ``` ```` fence for
+ * `renderAgentHtml` to turn into `<pre><code>`. Any run of 3+ backticks INSIDE
+ * the body (e.g. a read of a markdown file with its own fences) is broken up
+ * with zero-width spaces so it can't prematurely close our fence — the body is
+ * for reading, not byte-exact copy (same approach as the Claude adapter's
+ * `getFenced`). The body is end-trimmed: tool output usually ends with a
+ * newline, which would otherwise render as a stray blank line above the
+ * closing fence.
+ */
+export declare function buildFencedToolResultBody(body: string): string;
+//# sourceMappingURL=toolResultRender.d.ts.map

package/dist/utils/toolResultRender.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"toolResultRender.d.ts","sourceRoot":"","sources":["../../src/utils/toolResultRender.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AACH,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,UAAU,CAAC;AAMrD,2DAA2D;AAC3D,eAAO,MAAM,kBAAkB,KAAK,CAAC;AAErC,0DAA0D;AAC1D,eAAO,MAAM,kBAAkB,OAAO,CAAC;AAEvC;;;;;;;;;GASG;AACH,MAAM,MAAM,sBAAsB,GAAG,MAAM,GAAG,WAAW,GAAG,MAAM,CAAC;AAEnE;;;;;GAKG;AACH,wBAAgB,yBAAyB,CAAC,IAAI,EAAE,oBAAoB,GAAG,sBAAsB,CAG5F;AAED;kEACkE;AAClE,MAAM,WAAW,mBAAmB;IAClC,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,OAAO,CAAC;CACtB;AAED;;;;;;;GAOG;AACH,wBAAgB,sBAAsB,CAAC,IAAI,EAAE,MAAM,GAAG,mBAAmB,CAiBxE;AAED;;;;;;;;;GASG;AACH,wBAAgB,yBAAyB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAG9D"}

package/dist/utils/toolResultRender.js

@@ -0,0 +1,62 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.toolResultMaxChars = exports.toolResultMaxLines = void 0;
+exports.getToolResultRenderAction = getToolResultRenderAction;
+exports.getTruncatedToolResult = getTruncatedToolResult;
+exports.buildFencedToolResultBody = buildFencedToolResultBody;
+// Mode options / type guard / normalization live in the shared
+// `utils/displayVerbosity.ts` — the vocabulary is unified across the three
+// display commands; this module owns only the tool-result-specific semantics.
+/** `short`-mode line cap — applied BEFORE the char cap. */
+exports.toolResultMaxLines = 15;
+/** `short`-mode char cap — applied AFTER the line cap. */
+exports.toolResultMaxChars = 1200;
+/**
+ * @description Map the per-thread tool-results {@link DisplayVerbosityMode} to
+ * a render action. Pure — the matrix is one line per mode, but keeping it a
+ * named helper makes it unit-testable and keeps `bot.ts` free of mode-string
+ * comparisons (same shape as `getThinkingEventAction`).
+ */
+function getToolResultRenderAction(mode) {
+    if (mode === 'minimal')
+        return 'drop';
+    return mode === 'short' ? 'truncated' : 'full';
+}
+/**
+ * @description Truncate a tool-result body to the `short`-mode caps: first
+ * {@link toolResultMaxLines} lines, then {@link toolResultMaxChars} chars —
+ * whichever cap hits first wins; both may apply. The char cut retreats to the
+ * last newline inside the budget so a line is never split mid-way unless a
+ * single line alone exceeds the whole char budget (then a hard cut is the only
+ * option). A body under both caps is returned unchanged.
+ */
+function getTruncatedToolResult(body) {
+    let text = body;
+    let isTruncated = false;
+    const lines = text.split('\n');
+    if (lines.length > exports.toolResultMaxLines) {
+        text = lines.slice(0, exports.toolResultMaxLines).join('\n');
+        isTruncated = true;
+    }
+    if (text.length > exports.toolResultMaxChars) {
+        const lastNewlineInBudget = text.lastIndexOf('\n', exports.toolResultMaxChars);
+        text = lastNewlineInBudget > 0 ? text.slice(0, lastNewlineInBudget) : text.slice(0, exports.toolResultMaxChars);
+        isTruncated = true;
+    }
+    return { text, isTruncated };
+}
+/**
+ * @description Wrap a tool-result body in a ```` ``` ```` fence for
+ * `renderAgentHtml` to turn into `<pre><code>`. Any run of 3+ backticks INSIDE
+ * the body (e.g. a read of a markdown file with its own fences) is broken up
+ * with zero-width spaces so it can't prematurely close our fence — the body is
+ * for reading, not byte-exact copy (same approach as the Claude adapter's
+ * `getFenced`). The body is end-trimmed: tool output usually ends with a
+ * newline, which would otherwise render as a stray blank line above the
+ * closing fence.
+ */
+function buildFencedToolResultBody(body) {
+    const safeBody = body.trimEnd().replace(/`{3,}/g, run => run.split('').join('​'));
+    return `\`\`\`\n${safeBody}\n\`\`\``;
+}
+//# sourceMappingURL=toolResultRender.js.map

package/dist/utils/toolResultRender.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"toolResultRender.js","sourceRoot":"","sources":["../../src/utils/toolResultRender.ts"],"names":[],"mappings":";;;AAyCA,8DAGC;AAiBD,wDAiBC;AAYD,8DAGC;AAhFD,+DAA+D;AAC/D,2EAA2E;AAC3E,8EAA8E;AAE9E,2DAA2D;AAC9C,QAAA,kBAAkB,GAAG,EAAE,CAAC;AAErC,0DAA0D;AAC7C,QAAA,kBAAkB,GAAG,IAAI,CAAC;AAcvC;;;;;GAKG;AACH,SAAgB,yBAAyB,CAAC,IAA0B;IAClE,IAAI,IAAI,KAAK,SAAS;QAAE,OAAO,MAAM,CAAC;IACtC,OAAO,IAAI,KAAK,OAAO,CAAC,CAAC,CAAC,WAAW,CAAC,CAAC,CAAC,MAAM,CAAC;AACjD,CAAC;AASD;;;;;;;GAOG;AACH,SAAgB,sBAAsB,CAAC,IAAY;IACjD,IAAI,IAAI,GAAG,IAAI,CAAC;IAChB,IAAI,WAAW,GAAG,KAAK,CAAC;IAExB,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;IAC/B,IAAI,KAAK,CAAC,MAAM,GAAG,0BAAkB,EAAE,CAAC;QACtC,IAAI,GAAG,KAAK,CAAC,KAAK,CAAC,CAAC,EAAE,0BAAkB,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QACrD,WAAW,GAAG,IAAI,CAAC;IACrB,CAAC;IAED,IAAI,IAAI,CAAC,MAAM,GAAG,0BAAkB,EAAE,CAAC;QACrC,MAAM,mBAAmB,GAAG,IAAI,CAAC,WAAW,CAAC,IAAI,EAAE,0BAAkB,CAAC,CAAC;QACvE,IAAI,GAAG,mBAAmB,GAAG,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,mBAAmB,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,0BAAkB,CAAC,CAAC;QACxG,WAAW,GAAG,IAAI,CAAC;IACrB,CAAC;IAED,OAAO,EAAE,IAAI,EAAE,WAAW,EAAE,CAAC;AAC/B,CAAC;AAED;;;;;;;;;GASG;AACH,SAAgB,yBAAyB,CAAC,IAAY;IACpD,MAAM,QAAQ,GAAG,IAAI,CAAC,OAAO,EAAE,CAAC,OAAO,CAAC,QAAQ,EAAE,GAAG,CAAC,EAAE,CAAC,GAAG,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC;IAClF,OAAO,WAAW,QAAQ,UAAU,CAAC;AACvC,CAAC"}

package/dist/utils/topicRequest.d.ts

@@ -0,0 +1,61 @@
+/**
+ * @description Pure decisions for Telegram request intake (request/answer plan
+ * S7): WHEN an operator message or a scheduled run in a topic opens a request,
+ * and WHAT the request's origin and prompt header say. `bot.ts` applies them at
+ * the user entry points (text, voice, file, album, `/schedule`, the scheduler's
+ * forward) — never inside the shared prompt choke point, which also carries
+ * non-requests (the API-retry "continue" nudge, wake-up reminders, replays).
+ */
+import type { RequestOrigin } from '../requests/types';
+import type { TopicView } from '../types';
+/**
+ * @name TopicRequestSource
+ * @description The entry point a topic request came through. It is recorded in
+ * the origin's attributes and names the request to the agent.
+ */
+export type TopicRequestSource = 'text' | 'voice' | 'file' | 'album' | 'schedule' | 'scheduledRun';
+/** The attribute name the source is stored under in a topic request's origin. */
+export declare const topicRequestSourceAttribute = "source";
+/**
+ * The requester a scheduled run is filed under (`requestGroup.ts`): the
+ * scheduler, not a person — so a run never merges with, nor is merged into, an
+ * operator's open request in the same topic.
+ */
+export declare const scheduledRunRequester = "scheduler";
+/**
+ * @name TopicRequestIntake
+ * @description One prompt entering a topic as a request: the entry point it came
+ * through and who raised it — the Telegram user id for an operator entry point
+ * ({@link getTopicRequesterId}), {@link scheduledRunRequester} for a scheduled run.
+ */
+export interface TopicRequestIntake {
+    source: TopicRequestSource;
+    requesterId: string;
+}
+/** @description The requester of an operator entry point: the sending Telegram user, by id. */
+export declare function getTopicRequesterId(from: {
+    id: number;
+} | undefined): string;
+/**
+ * @description Whether a prompt in a topic opens a request: its view has
+ * requests on, and the text is not a slash command forwarded to the agent
+ * (`/clear`, `/compact`, … are control tokens, not work the agent owes an answer
+ * to). Answers to the agent's own native questions never reach this decision —
+ * their routes return before the prompt path.
+ */
+export declare function checkShouldOpenTopicRequest(view: TopicView, isSlashCommand: boolean): boolean;
+/**
+ * @description The origin a topic request is opened with. The requester rides in
+ * the attributes: the ledger's merge rule (`requestGroup.ts`) reads it, so two
+ * people's messages in one topic never supersede each other.
+ */
+export declare function getTopicRequestOrigin(intake: TopicRequestIntake): RequestOrigin;
+/**
+ * @description The header that rides the request's prompt. In the answers-only
+ * view the agent is told its plain text and thinking are not shown; in the stream
+ * views they are.
+ * `supersededRequestIds` are the requester's still-open requests this one
+ * replaced — the header asks for only what this one adds.
+ */
+export declare function buildTopicRequestHeader(requestId: string, source: TopicRequestSource, view: TopicView, supersededRequestIds?: readonly string[]): string;
+//# sourceMappingURL=topicRequest.d.ts.map

package/dist/utils/topicRequest.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"topicRequest.d.ts","sourceRoot":"","sources":["../../src/utils/topicRequest.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAC;AAGvD,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,UAAU,CAAC;AAG1C;;;;GAIG;AACH,MAAM,MAAM,kBAAkB,GAAG,MAAM,GAAG,OAAO,GAAG,MAAM,GAAG,OAAO,GAAG,UAAU,GAAG,cAAc,CAAC;AAEnG,iFAAiF;AACjF,eAAO,MAAM,2BAA2B,WAAW,CAAC;AAEpD;;;;GAIG;AACH,eAAO,MAAM,qBAAqB,cAAc,CAAC;AAEjD;;;;;GAKG;AACH,MAAM,WAAW,kBAAkB;IACjC,MAAM,EAAE,kBAAkB,CAAC;IAC3B,WAAW,EAAE,MAAM,CAAC;CACrB;AAED,+FAA+F;AAC/F,wBAAgB,mBAAmB,CAAC,IAAI,EAAE;IAAE,EAAE,EAAE,MAAM,CAAA;CAAE,GAAG,SAAS,GAAG,MAAM,CAE5E;AAYD;;;;;;GAMG;AACH,wBAAgB,2BAA2B,CAAC,IAAI,EAAE,SAAS,EAAE,cAAc,EAAE,OAAO,GAAG,OAAO,CAE7F;AAED;;;;GAIG;AACH,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,kBAAkB,GAAG,aAAa,CAK/E;AAED;;;;;;GAMG;AACH,wBAAgB,uBAAuB,CACrC,SAAS,EAAE,MAAM,EACjB,MAAM,EAAE,kBAAkB,EAC1B,IAAI,EAAE,SAAS,EACf,oBAAoB,GAAE,SAAS,MAAM,EAAO,GAC3C,MAAM,CAOR"}

package/dist/utils/topicRequest.js

@@ -0,0 +1,68 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.scheduledRunRequester = exports.topicRequestSourceAttribute = void 0;
+exports.getTopicRequesterId = getTopicRequesterId;
+exports.checkShouldOpenTopicRequest = checkShouldOpenTopicRequest;
+exports.getTopicRequestOrigin = getTopicRequestOrigin;
+exports.buildTopicRequestHeader = buildTopicRequestHeader;
+const requestHeader_1 = require("../requests/requestHeader");
+const requestGroup_1 = require("../requests/requestGroup");
+const topicView_1 = require("./topicView");
+/** The attribute name the source is stored under in a topic request's origin. */
+exports.topicRequestSourceAttribute = 'source';
+/**
+ * The requester a scheduled run is filed under (`requestGroup.ts`): the
+ * scheduler, not a person — so a run never merges with, nor is merged into, an
+ * operator's open request in the same topic.
+ */
+exports.scheduledRunRequester = 'scheduler';
+/** @description The requester of an operator entry point: the sending Telegram user, by id. */
+function getTopicRequesterId(from) {
+    return from?.id.toString() ?? '';
+}
+/** What the agent is told the request came from, per entry point. */
+const topicRequestOriginDescriptions = {
+    text: 'a message in this topic',
+    voice: 'a voice message in this topic',
+    file: 'a file sent to this topic',
+    album: 'an album sent to this topic',
+    schedule: 'a /schedule request in this topic',
+    scheduledRun: 'a scheduled run in this topic',
+};
+/**
+ * @description Whether a prompt in a topic opens a request: its view has
+ * requests on, and the text is not a slash command forwarded to the agent
+ * (`/clear`, `/compact`, … are control tokens, not work the agent owes an answer
+ * to). Answers to the agent's own native questions never reach this decision —
+ * their routes return before the prompt path.
+ */
+function checkShouldOpenTopicRequest(view, isSlashCommand) {
+    return (0, topicView_1.checkAreRequestsEnabled)(view) && !isSlashCommand;
+}
+/**
+ * @description The origin a topic request is opened with. The requester rides in
+ * the attributes: the ledger's merge rule (`requestGroup.ts`) reads it, so two
+ * people's messages in one topic never supersede each other.
+ */
+function getTopicRequestOrigin(intake) {
+    return {
+        kind: intake.source === 'scheduledRun' ? 'scheduledRun' : 'message',
+        attributes: { [exports.topicRequestSourceAttribute]: intake.source, [requestGroup_1.requestRequesterAttribute]: intake.requesterId },
+    };
+}
+/**
+ * @description The header that rides the request's prompt. In the answers-only
+ * view the agent is told its plain text and thinking are not shown; in the stream
+ * views they are.
+ * `supersededRequestIds` are the requester's still-open requests this one
+ * replaced — the header asks for only what this one adds.
+ */
+function buildTopicRequestHeader(requestId, source, view, supersededRequestIds = []) {
+    return (0, requestHeader_1.buildRequestHeader)({
+        requestId,
+        originDescription: topicRequestOriginDescriptions[source],
+        isPlainTextHidden: !(0, topicView_1.checkIsStreamShown)(view),
+        supersededRequestIds,
+    });
+}
+//# sourceMappingURL=topicRequest.js.map

package/dist/utils/topicRequest.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"topicRequest.js","sourceRoot":"","sources":["../../src/utils/topicRequest.ts"],"names":[],"mappings":";;;AA2CA,kDAEC;AAmBD,kEAEC;AAOD,sDAKC;AASD,0DAYC;AA1FD,6DAA+D;AAC/D,2DAAqE;AAErE,2CAA0E;AAS1E,iFAAiF;AACpE,QAAA,2BAA2B,GAAG,QAAQ,CAAC;AAEpD;;;;GAIG;AACU,QAAA,qBAAqB,GAAG,WAAW,CAAC;AAajD,+FAA+F;AAC/F,SAAgB,mBAAmB,CAAC,IAAgC;IAClE,OAAO,IAAI,EAAE,EAAE,CAAC,QAAQ,EAAE,IAAI,EAAE,CAAC;AACnC,CAAC;AAED,qEAAqE;AACrE,MAAM,8BAA8B,GAAiD;IACnF,IAAI,EAAE,yBAAyB;IAC/B,KAAK,EAAE,+BAA+B;IACtC,IAAI,EAAE,2BAA2B;IACjC,KAAK,EAAE,6BAA6B;IACpC,QAAQ,EAAE,mCAAmC;IAC7C,YAAY,EAAE,+BAA+B;CAC9C,CAAC;AAEF;;;;;;GAMG;AACH,SAAgB,2BAA2B,CAAC,IAAe,EAAE,cAAuB;IAClF,OAAO,IAAA,mCAAuB,EAAC,IAAI,CAAC,IAAI,CAAC,cAAc,CAAC;AAC1D,CAAC;AAED;;;;GAIG;AACH,SAAgB,qBAAqB,CAAC,MAA0B;IAC9D,OAAO;QACL,IAAI,EAAE,MAAM,CAAC,MAAM,KAAK,cAAc,CAAC,CAAC,CAAC,cAAc,CAAC,CAAC,CAAC,SAAS;QACnE,UAAU,EAAE,EAAE,CAAC,mCAA2B,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,CAAC,wCAAyB,CAAC,EAAE,MAAM,CAAC,WAAW,EAAE;KAC9G,CAAC;AACJ,CAAC;AAED;;;;;;GAMG;AACH,SAAgB,uBAAuB,CACrC,SAAiB,EACjB,MAA0B,EAC1B,IAAe,EACf,uBAA0C,EAAE;IAE5C,OAAO,IAAA,kCAAkB,EAAC;QACxB,SAAS;QACT,iBAAiB,EAAE,8BAA8B,CAAC,MAAM,CAAC;QACzD,iBAAiB,EAAE,CAAC,IAAA,8BAAkB,EAAC,IAAI,CAAC;QAC5C,oBAAoB;KACrB,CAAC,CAAC;AACL,CAAC"}

package/dist/utils/topicView.d.ts

@@ -0,0 +1,55 @@
+/**
+ * @description THE single source of truth for the per-topic VIEW vocabulary
+ * (request/answer plan S6): what a Telegram topic SHOWS of the agent's work.
+ * The view never changes how the agent works — only what reaches the topic
+ * and whether the operator's messages open requests the agent answers through
+ * `answer_request`:
+ *
+ *   view             agent's stream   MCP answers        requests + wake-ups
+ *   stream           shown            —                  off   (DEFAULT, today)
+ *   streamAnswers    shown            shown, pinned      on
+ *   answers          hidden           shown, pinned      on
+ *
+ * Mirrors `displayVerbosity.ts`: the option order, the locked default, the type
+ * guard and the typed-argument parser live here; the rendering decisions that
+ * READ a view (`checkIsStreamShown`, `checkAreRequestsEnabled`) live here too so
+ * the stream gates and the request intake can never disagree on a view.
+ */
+import type { TopicView } from '../types';
+/** Every selectable view, in picker-button order (loudest → quietest). */
+export declare const topicViewOptions: readonly TopicView[];
+/** Locked default: nothing changes for a topic until it is switched. */
+export declare const defaultTopicView: TopicView;
+/**
+ * @description The typed `/verbosity` spelling of each view — the words the
+ * public README documents (`/verbosity stream|stream_answers|answers`).
+ */
+export declare const topicViewArguments: Readonly<Record<TopicView, string>>;
+/** @description Type guard over the persisted spelling (a `state.json` value or a callback payload). */
+export declare function checkIsTopicView(value: string): value is TopicView;
+/**
+ * @description Parse a typed `/verbosity` argument or a picker payload into a
+ * view: the documented typed spellings and the persisted spelling are both
+ * accepted (a picker button carries the persisted one); anything else, including
+ * `undefined`, is `null` so the caller can tell "use the default" from "reject".
+ */
+export declare function parseTopicView(value: string | undefined): TopicView | null;
+/** @description Whether the agent's own stream (text, status, thinking, tool results, sub-agents) reaches the topic. */
+export declare function checkIsStreamShown(view: TopicView): boolean;
+/**
+ * @name AgentStreamEvent
+ * @description The kinds of agent event the bot renders into a topic. All but
+ * `question` are the agent's STREAM; a native question is kept in every view —
+ * hidden, the agent would hang on it.
+ */
+export type AgentStreamEvent = 'output' | 'question' | 'status' | 'thinking' | 'toolResult' | 'subagentStatus';
+/**
+ * @description Whether an agent event is rendered in a topic with `view` (plan
+ * S9): the stream is dropped in the answers-only view, a native question never
+ * is. What is NOT an agent event — the typing indicator, files the agent sends
+ * through the bot MCP, the bot's own notices, the pinned answers — is not gated.
+ */
+export declare function checkIsAgentEventShown(view: TopicView, event: AgentStreamEvent): boolean;
+/** @description Whether operator messages and scheduled runs in the topic open requests (and so get wake-ups and pinned answers). */
+export declare function checkAreRequestsEnabled(view: TopicView): boolean;
+//# sourceMappingURL=topicView.d.ts.map

package/dist/utils/topicView.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"topicView.d.ts","sourceRoot":"","sources":["../../src/utils/topicView.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AACH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,UAAU,CAAC;AAE1C,0EAA0E;AAC1E,eAAO,MAAM,gBAAgB,EAAE,SAAS,SAAS,EAA2C,CAAC;AAE7F,wEAAwE;AACxE,eAAO,MAAM,gBAAgB,EAAE,SAAoB,CAAC;AAEpD;;;GAGG;AACH,eAAO,MAAM,kBAAkB,EAAE,QAAQ,CAAC,MAAM,CAAC,SAAS,EAAE,MAAM,CAAC,CAIlE,CAAC;AAEF,wGAAwG;AACxG,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,MAAM,GAAG,KAAK,IAAI,SAAS,CAElE;AAED;;;;;GAKG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,MAAM,GAAG,SAAS,GAAG,SAAS,GAAG,IAAI,CAI1E;AAED,wHAAwH;AACxH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,SAAS,GAAG,OAAO,CAE3D;AAED;;;;;GAKG;AACH,MAAM,MAAM,gBAAgB,GAAG,QAAQ,GAAG,UAAU,GAAG,QAAQ,GAAG,UAAU,GAAG,YAAY,GAAG,gBAAgB,CAAC;AAE/G;;;;;GAKG;AACH,wBAAgB,sBAAsB,CAAC,IAAI,EAAE,SAAS,EAAE,KAAK,EAAE,gBAAgB,GAAG,OAAO,CAExF;AAED,qIAAqI;AACrI,wBAAgB,uBAAuB,CAAC,IAAI,EAAE,SAAS,GAAG,OAAO,CAEhE"}

package/dist/utils/topicView.js

@@ -0,0 +1,56 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.topicViewArguments = exports.defaultTopicView = exports.topicViewOptions = void 0;
+exports.checkIsTopicView = checkIsTopicView;
+exports.parseTopicView = parseTopicView;
+exports.checkIsStreamShown = checkIsStreamShown;
+exports.checkIsAgentEventShown = checkIsAgentEventShown;
+exports.checkAreRequestsEnabled = checkAreRequestsEnabled;
+/** Every selectable view, in picker-button order (loudest → quietest). */
+exports.topicViewOptions = ['stream', 'streamAnswers', 'answers'];
+/** Locked default: nothing changes for a topic until it is switched. */
+exports.defaultTopicView = 'stream';
+/**
+ * @description The typed `/verbosity` spelling of each view — the words the
+ * public README documents (`/verbosity stream|stream_answers|answers`).
+ */
+exports.topicViewArguments = {
+    stream: 'stream',
+    streamAnswers: 'stream_answers',
+    answers: 'answers',
+};
+/** @description Type guard over the persisted spelling (a `state.json` value or a callback payload). */
+function checkIsTopicView(value) {
+    return exports.topicViewOptions.includes(value);
+}
+/**
+ * @description Parse a typed `/verbosity` argument or a picker payload into a
+ * view: the documented typed spellings and the persisted spelling are both
+ * accepted (a picker button carries the persisted one); anything else, including
+ * `undefined`, is `null` so the caller can tell "use the default" from "reject".
+ */
+function parseTopicView(value) {
+    if (value === undefined)
+        return null;
+    if (checkIsTopicView(value))
+        return value;
+    return exports.topicViewOptions.find((view) => exports.topicViewArguments[view] === value) ?? null;
+}
+/** @description Whether the agent's own stream (text, status, thinking, tool results, sub-agents) reaches the topic. */
+function checkIsStreamShown(view) {
+    return view !== 'answers';
+}
+/**
+ * @description Whether an agent event is rendered in a topic with `view` (plan
+ * S9): the stream is dropped in the answers-only view, a native question never
+ * is. What is NOT an agent event — the typing indicator, files the agent sends
+ * through the bot MCP, the bot's own notices, the pinned answers — is not gated.
+ */
+function checkIsAgentEventShown(view, event) {
+    return event === 'question' || checkIsStreamShown(view);
+}
+/** @description Whether operator messages and scheduled runs in the topic open requests (and so get wake-ups and pinned answers). */
+function checkAreRequestsEnabled(view) {
+    return view !== 'stream';
+}
+//# sourceMappingURL=topicView.js.map

package/dist/utils/topicView.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"topicView.js","sourceRoot":"","sources":["../../src/utils/topicView.ts"],"names":[],"mappings":";;;AAoCA,4CAEC;AAQD,wCAIC;AAGD,gDAEC;AAgBD,wDAEC;AAGD,0DAEC;AA3DD,0EAA0E;AAC7D,QAAA,gBAAgB,GAAyB,CAAC,QAAQ,EAAE,eAAe,EAAE,SAAS,CAAC,CAAC;AAE7F,wEAAwE;AAC3D,QAAA,gBAAgB,GAAc,QAAQ,CAAC;AAEpD;;;GAGG;AACU,QAAA,kBAAkB,GAAwC;IACrE,MAAM,EAAE,QAAQ;IAChB,aAAa,EAAE,gBAAgB;IAC/B,OAAO,EAAE,SAAS;CACnB,CAAC;AAEF,wGAAwG;AACxG,SAAgB,gBAAgB,CAAC,KAAa;IAC5C,OAAQ,wBAAsC,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC;AACjE,CAAC;AAED;;;;;GAKG;AACH,SAAgB,cAAc,CAAC,KAAyB;IACtD,IAAI,KAAK,KAAK,SAAS;QAAE,OAAO,IAAI,CAAC;IACrC,IAAI,gBAAgB,CAAC,KAAK,CAAC;QAAE,OAAO,KAAK,CAAC;IAC1C,OAAO,wBAAgB,CAAC,IAAI,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,0BAAkB,CAAC,IAAI,CAAC,KAAK,KAAK,CAAC,IAAI,IAAI,CAAC;AACrF,CAAC;AAED,wHAAwH;AACxH,SAAgB,kBAAkB,CAAC,IAAe;IAChD,OAAO,IAAI,KAAK,SAAS,CAAC;AAC5B,CAAC;AAUD;;;;;GAKG;AACH,SAAgB,sBAAsB,CAAC,IAAe,EAAE,KAAuB;IAC7E,OAAO,KAAK,KAAK,UAAU,IAAI,kBAAkB,CAAC,IAAI,CAAC,CAAC;AAC1D,CAAC;AAED,qIAAqI;AACrI,SAAgB,uBAAuB,CAAC,IAAe;IACrD,OAAO,IAAI,KAAK,QAAQ,CAAC;AAC3B,CAAC"}

package/dist/utils/transcribeAudio.d.ts

@@ -0,0 +1,89 @@
+/**
+ * @description Voice-note transcription against a Whisper-compatible HTTP API
+ * (Groq when its key is set, else OpenAI), with automatic retries on transient
+ * failures.
+ *
+ * Extracted from `bot.ts` so it is side-effect-free and testable against a
+ * local HTTP server (importing `bot.ts` would construct a Telegraf instance and
+ * read ENV at module load) — the same reasoning as `./download`.
+ *
+ * Why retries: Groq normally answers in well under a second, yet a request
+ * occasionally stalls past the timeout. Without a retry that voice note was
+ * simply lost and the user had to re-record it. A timeout, a network error, an
+ * HTTP 408 / 409 and a 5xx are retried after a pause (5 s, then 15 s); a 429
+ * waits at least as long as the provider's `Retry-After`; any other 4xx fails
+ * at once, since resending the same request would fail the same way.
+ */
+/** Pauses before the automatic retries: the 1st after 5 s, the 2nd after 15 s. */
+export declare const transcribeRetryDelaysMs: readonly number[];
+/**
+ * @description Where and how a voice note is transcribed.
+ */
+export interface TranscriptionEndpoint {
+    url: string;
+    apiKey: string;
+    model: string;
+}
+/**
+ * @description Whether a failed attempt is worth repeating: `transient`
+ * (timeout / network error / 408 / 409 / 5xx), `rateLimited` (429 — honour
+ * `Retry-After`), or `permanent` (any other failure — a retry would fail the
+ * same way).
+ */
+export type TranscribeFailureKind = 'transient' | 'rateLimited' | 'permanent';
+export type TranscribeResult = {
+    ok: true;
+    text: string;
+} | {
+    ok: false;
+    error: string;
+};
+/**
+ * @description Details of a failed attempt that is about to be retried.
+ */
+export interface TranscribeRetryInfo {
+    /** 1-based number of the attempt that just failed. */
+    attemptNumber: number;
+    error: string;
+    /** Pause before the next attempt. */
+    delayMs: number;
+}
+export interface TranscribeAudioOptions {
+    /** Per-attempt socket inactivity timeout. */
+    timeoutMs: number;
+    /** Pause before each retry; its length is the retry count. Defaults to {@link transcribeRetryDelaysMs}. */
+    retryDelaysMs?: readonly number[];
+    /** Fired before each retry, e.g. to tell the user a retry is coming. */
+    onRetry?: (info: TranscribeRetryInfo) => void;
+}
+/**
+ * @description Pick the transcription provider from the configured API keys:
+ * Groq wins when both are set; `null` when neither is.
+ */
+export declare function getTranscriptionEndpoint(apiKeys: {
+    groqApiKey?: string;
+    openaiApiKey?: string;
+}): TranscriptionEndpoint | null;
+/**
+ * @description Classify a non-2xx HTTP status of the transcription API.
+ */
+export declare function getTranscribeFailureKind(status: number): TranscribeFailureKind;
+/**
+ * @description Pause before retry number `retryIndex` (0-based), or `null`
+ * when the failure must not be retried (permanent, or the schedule is used
+ * up). A 429 never retries sooner than the schedule NOR sooner than the
+ * provider's `Retry-After` asks.
+ */
+export declare function getTranscribeRetryDelayMs(input: {
+    failureKind: TranscribeFailureKind;
+    retryIndex: number;
+    retryAfterSec?: number;
+    retryDelaysMs?: readonly number[];
+}): number | null;
+/**
+ * @description Transcribe a voice note, retrying transient failures on the
+ * {@link transcribeRetryDelaysMs} schedule. Resolves with the text, or with
+ * the LAST error (annotated with the attempt count once a retry happened).
+ */
+export declare function transcribeAudio(filePath: string, endpoint: TranscriptionEndpoint, options: TranscribeAudioOptions): Promise<TranscribeResult>;
+//# sourceMappingURL=transcribeAudio.d.ts.map

package/dist/utils/transcribeAudio.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"transcribeAudio.d.ts","sourceRoot":"","sources":["../../src/utils/transcribeAudio.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAUH,kFAAkF;AAClF,eAAO,MAAM,uBAAuB,EAAE,SAAS,MAAM,EAAoB,CAAC;AAe1E;;GAEG;AACH,MAAM,WAAW,qBAAqB;IACpC,GAAG,EAAE,MAAM,CAAC;IACZ,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,MAAM,CAAC;CACf;AAED;;;;;GAKG;AACH,MAAM,MAAM,qBAAqB,GAAG,WAAW,GAAG,aAAa,GAAG,WAAW,CAAC;AAE9E,MAAM,MAAM,gBAAgB,GACxB;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,GAC1B;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CAAC;AAMjC;;GAEG;AACH,MAAM,WAAW,mBAAmB;IAClC,sDAAsD;IACtD,aAAa,EAAE,MAAM,CAAC;IACtB,KAAK,EAAE,MAAM,CAAC;IACd,qCAAqC;IACrC,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,sBAAsB;IACrC,6CAA6C;IAC7C,SAAS,EAAE,MAAM,CAAC;IAClB,2GAA2G;IAC3G,aAAa,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAClC,wEAAwE;IACxE,OAAO,CAAC,EAAE,CAAC,IAAI,EAAE,mBAAmB,KAAK,IAAI,CAAC;CAC/C;AAED;;;GAGG;AACH,wBAAgB,wBAAwB,CAAC,OAAO,EAAE;IAChD,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB,GAAG,qBAAqB,GAAG,IAAI,CAQ/B;AAED;;GAEG;AACH,wBAAgB,wBAAwB,CAAC,MAAM,EAAE,MAAM,GAAG,qBAAqB,CAI9E;AAED;;;;;GAKG;AACH,wBAAgB,yBAAyB,CAAC,KAAK,EAAE;IAC/C,WAAW,EAAE,qBAAqB,CAAC;IACnC,UAAU,EAAE,MAAM,CAAC;IACnB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,aAAa,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CACnC,GAAG,MAAM,GAAG,IAAI,CAQhB;AA6GD;;;;GAIG;AACH,wBAAsB,eAAe,CACnC,QAAQ,EAAE,MAAM,EAChB,QAAQ,EAAE,qBAAqB,EAC/B,OAAO,EAAE,sBAAsB,GAC9B,OAAO,CAAC,gBAAgB,CAAC,CAqB3B"}