charness 0.0.0-stage → 3.0.0

package/dist/utils/draftId.js

@@ -0,0 +1,46 @@
+"use strict";
+/**
+ * @description Draft-id allocator for the DM-mode live-streaming draft channel
+ * (P3). Telegram's `sendMessageDraft` animates updates that share the SAME
+ * `draft_id` as one in-progress draft; a NEW id starts a fresh draft. So one
+ * streamed response must keep ONE stable id across all its updates, and each new
+ * response (a fresh, non-continuation turn) must get a DISTINCT id so it animates
+ * separately from the previous turn.
+ *
+ * A pure module-scoped monotonic counter gives both: {@link nextDraftId} is
+ * called ONCE per response (at `startDraftTurn`), and the returned id is then
+ * stored on the per-thread draft state and reused for every update of that
+ * response. Two DM topics streaming at once get distinct ids because each pulls
+ * its own value off the shared counter.
+ *
+ * The id is folded into a NON-ZERO 31-bit positive int: Telegram requires a
+ * non-zero draft id, and a small positive int avoids any signedness surprises in
+ * the Bot API. The counter wraps at {@link DRAFT_ID_MODULO} without ever
+ * yielding 0.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DRAFT_ID_MODULO = void 0;
+exports.nextDraftId = nextDraftId;
+/**
+ * Wrap point for the draft-id counter. Kept well inside the 31-bit positive
+ * range (2_147_483_647) so the `+1` fold can never reach a 32-bit boundary.
+ */
+exports.DRAFT_ID_MODULO = 2_000_000_000;
+let draftIdCounter = 0;
+/**
+ * @description Allocate the next draft id. Monotonic per process, folded into a
+ * non-zero positive 31-bit int via `(counter % MODULO) + 1`, so the value is
+ * always in `[1, DRAFT_ID_MODULO]` and never 0 even at the wrap boundary.
+ *
+ * `prevId` is accepted for symmetry with the per-thread state (and to make a
+ * future "derive from previous" tweak local to this module) but is intentionally
+ * unused: uniqueness comes from the shared monotonic counter, not the caller's
+ * last id, so two interleaved per-thread turns can never collide.
+ */
+function nextDraftId(prevId) {
+    void prevId;
+    const id = (draftIdCounter % exports.DRAFT_ID_MODULO) + 1;
+    draftIdCounter += 1;
+    return id;
+}
+//# sourceMappingURL=draftId.js.map

package/dist/utils/draftId.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"draftId.js","sourceRoot":"","sources":["../../src/utils/draftId.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;;GAkBG;;;AAoBH,kCAKC;AAvBD;;;GAGG;AACU,QAAA,eAAe,GAAG,aAAa,CAAC;AAE7C,IAAI,cAAc,GAAG,CAAC,CAAC;AAEvB;;;;;;;;;GASG;AACH,SAAgB,WAAW,CAAC,MAAqB;IAC/C,KAAK,MAAM,CAAC;IACZ,MAAM,EAAE,GAAG,CAAC,cAAc,GAAG,uBAAe,CAAC,GAAG,CAAC,CAAC;IAClD,cAAc,IAAI,CAAC,CAAC;IACpB,OAAO,EAAE,CAAC;AACZ,CAAC"}

package/dist/utils/draftPacer.d.ts

@@ -0,0 +1,72 @@
+/**
+ * @description Pure pacing decision for the DM-mode live-draft channel (P3),
+ * mirroring {@link ../utils/statusFlushDecision.ts} in shape: given the latest
+ * accumulated draft text, the last text actually drafted, the clock, and the
+ * draft-channel 429 cooldown, decide what the draft loop should do with this
+ * update.
+ *
+ * The draft channel is SEPARATE from the message channel: it never touches the
+ * rateLimiter TokenBucket / per-chat 429 cooldown, so its own backoff
+ * (`backoffUntilMs`) can never starve real `sendMessage`/`editMessageText`
+ * traffic. Drafts are disposable previews — under congestion it is correct to
+ * defer them rather than spend a draft call on a frame the next one will replace.
+ *
+ * @name DraftPaceAction
+ * @description
+ * - `send`  — text changed, not too soon since the last send, no draft-channel
+ *   cooldown: fire the draft now.
+ * - `skip`  — text is identical to the last drafted text: a draft update would
+ *   only re-send the same preview; don't spend a draft call.
+ * - `defer` — either a draft-channel 429 cooldown is active, or the min interval
+ *   since the last send hasn't elapsed: hold the newest text and re-arm a timer
+ *   for the remainder.
+ */
+export type DraftPaceAction = 'send' | 'skip' | 'defer';
+/**
+ * Min gap between two draft updates of the same in-flight response. ~700ms →
+ * ~1.4 updates/sec — fast enough to read as a live "typing" animation, slow
+ * enough to stay well under the draft budget the P0.5 probe measured.
+ */
+export declare const DRAFT_MIN_INTERVAL_MS = 700;
+/**
+ * Fallback draft-channel backoff when a draft 429 omits `retry_after`. The P0.5
+ * live probe saw ~20s draft cooldowns; the runtime prefers the error's
+ * `retry_after` when present and uses this only as the floor/fallback.
+ */
+export declare const DRAFT_DEFAULT_BACKOFF_MS = 20000;
+export interface DraftPaceInput {
+    /** Latest accumulated draft text the loop wants to show. */
+    nextText: string;
+    /** Last text actually drafted for this thread, or null (nothing sent yet). */
+    lastSentText: string | null;
+    /** Current time, ms. */
+    nowMs: number;
+    /** When the last draft actually went out, ms, or null (nothing sent yet). */
+    lastSentAtMs: number | null;
+    /** Min gap between two draft sends, ms (= {@link DRAFT_MIN_INTERVAL_MS}). */
+    minIntervalMs: number;
+    /** Draft-channel 429 cooldown end, ms. `0` = no cooldown. */
+    backoffUntilMs: number;
+}
+/**
+ * @description Decide what the draft pacer should do with `nextText`.
+ *
+ * Order matters: the 429 cooldown wins over everything (defer even an identical
+ * frame so the loop exits leaving the newest text for the post-cooldown re-arm);
+ * then an unchanged frame is a `skip` (no draft call); then the min-interval
+ * gate `defer`s a too-soon update; otherwise `send`.
+ */
+export declare function getDraftPaceAction(input: DraftPaceInput): DraftPaceAction;
+/**
+ * @description Whether an `output` event should be streamed via the native DM
+ * draft channel. Drafts are for genuinely INCREMENTAL streaming; a COMPLETE
+ * one-shot output (`meta.isComplete`, e.g. the resume context block) is already
+ * whole at emit time — drafting it would make Telegram's native draft "typing"
+ * animation draw static text progressively, so it must post directly. Sub-agent
+ * chunks are never drafted either. Group mode never drafts.
+ */
+export declare function checkShouldStreamAsDraft(isDmMode: boolean, meta?: {
+    isComplete?: boolean;
+    isSubagent?: boolean;
+}): boolean;
+//# sourceMappingURL=draftPacer.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"draftPacer.d.ts","sourceRoot":"","sources":["../../src/utils/draftPacer.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,MAAM,MAAM,eAAe,GAAG,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC;AAExD;;;;GAIG;AACH,eAAO,MAAM,qBAAqB,MAAM,CAAC;AAEzC;;;;GAIG;AACH,eAAO,MAAM,wBAAwB,QAAS,CAAC;AAE/C,MAAM,WAAW,cAAc;IAC7B,4DAA4D;IAC5D,QAAQ,EAAE,MAAM,CAAC;IACjB,8EAA8E;IAC9E,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B,wBAAwB;IACxB,KAAK,EAAE,MAAM,CAAC;IACd,6EAA6E;IAC7E,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B,6EAA6E;IAC7E,aAAa,EAAE,MAAM,CAAC;IACtB,6DAA6D;IAC7D,cAAc,EAAE,MAAM,CAAC;CACxB;AAED;;;;;;;GAOG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,cAAc,GAAG,eAAe,CAOzE;AAED;;;;;;;GAOG;AACH,wBAAgB,wBAAwB,CACtC,QAAQ,EAAE,OAAO,EACjB,IAAI,CAAC,EAAE;IAAE,UAAU,CAAC,EAAE,OAAO,CAAC;IAAC,UAAU,CAAC,EAAE,OAAO,CAAA;CAAE,GACpD,OAAO,CAKT"}

package/dist/utils/draftPacer.js

@@ -0,0 +1,53 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DRAFT_DEFAULT_BACKOFF_MS = exports.DRAFT_MIN_INTERVAL_MS = void 0;
+exports.getDraftPaceAction = getDraftPaceAction;
+exports.checkShouldStreamAsDraft = checkShouldStreamAsDraft;
+/**
+ * Min gap between two draft updates of the same in-flight response. ~700ms →
+ * ~1.4 updates/sec — fast enough to read as a live "typing" animation, slow
+ * enough to stay well under the draft budget the P0.5 probe measured.
+ */
+exports.DRAFT_MIN_INTERVAL_MS = 700;
+/**
+ * Fallback draft-channel backoff when a draft 429 omits `retry_after`. The P0.5
+ * live probe saw ~20s draft cooldowns; the runtime prefers the error's
+ * `retry_after` when present and uses this only as the floor/fallback.
+ */
+exports.DRAFT_DEFAULT_BACKOFF_MS = 20_000;
+/**
+ * @description Decide what the draft pacer should do with `nextText`.
+ *
+ * Order matters: the 429 cooldown wins over everything (defer even an identical
+ * frame so the loop exits leaving the newest text for the post-cooldown re-arm);
+ * then an unchanged frame is a `skip` (no draft call); then the min-interval
+ * gate `defer`s a too-soon update; otherwise `send`.
+ */
+function getDraftPaceAction(input) {
+    if (input.nowMs < input.backoffUntilMs)
+        return 'defer';
+    if (input.nextText === input.lastSentText)
+        return 'skip';
+    if (input.lastSentAtMs !== null && input.nowMs - input.lastSentAtMs < input.minIntervalMs) {
+        return 'defer';
+    }
+    return 'send';
+}
+/**
+ * @description Whether an `output` event should be streamed via the native DM
+ * draft channel. Drafts are for genuinely INCREMENTAL streaming; a COMPLETE
+ * one-shot output (`meta.isComplete`, e.g. the resume context block) is already
+ * whole at emit time — drafting it would make Telegram's native draft "typing"
+ * animation draw static text progressively, so it must post directly. Sub-agent
+ * chunks are never drafted either. Group mode never drafts.
+ */
+function checkShouldStreamAsDraft(isDmMode, meta) {
+    if (!isDmMode)
+        return false;
+    if (meta?.isComplete === true)
+        return false;
+    if (meta?.isSubagent === true)
+        return false;
+    return true;
+}
+//# sourceMappingURL=draftPacer.js.map

package/dist/utils/draftPacer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"draftPacer.js","sourceRoot":"","sources":["../../src/utils/draftPacer.ts"],"names":[],"mappings":";;;AA8DA,gDAOC;AAUD,4DAQC;AA9DD;;;;GAIG;AACU,QAAA,qBAAqB,GAAG,GAAG,CAAC;AAEzC;;;;GAIG;AACU,QAAA,wBAAwB,GAAG,MAAM,CAAC;AAiB/C;;;;;;;GAOG;AACH,SAAgB,kBAAkB,CAAC,KAAqB;IACtD,IAAI,KAAK,CAAC,KAAK,GAAG,KAAK,CAAC,cAAc;QAAE,OAAO,OAAO,CAAC;IACvD,IAAI,KAAK,CAAC,QAAQ,KAAK,KAAK,CAAC,YAAY;QAAE,OAAO,MAAM,CAAC;IACzD,IAAI,KAAK,CAAC,YAAY,KAAK,IAAI,IAAI,KAAK,CAAC,KAAK,GAAG,KAAK,CAAC,YAAY,GAAG,KAAK,CAAC,aAAa,EAAE,CAAC;QAC1F,OAAO,OAAO,CAAC;IACjB,CAAC;IACD,OAAO,MAAM,CAAC;AAChB,CAAC;AAED;;;;;;;GAOG;AACH,SAAgB,wBAAwB,CACtC,QAAiB,EACjB,IAAqD;IAErD,IAAI,CAAC,QAAQ;QAAE,OAAO,KAAK,CAAC;IAC5B,IAAI,IAAI,EAAE,UAAU,KAAK,IAAI;QAAE,OAAO,KAAK,CAAC;IAC5C,IAAI,IAAI,EAAE,UAAU,KAAK,IAAI;QAAE,OAAO,KAAK,CAAC;IAC5C,OAAO,IAAI,CAAC;AACd,CAAC"}

package/dist/utils/effortStartupKeystroke.d.ts

@@ -0,0 +1,20 @@
+/**
+ * @description Decide the `/effort` slash-command keystroke to replay into a
+ * freshly spawned Claude TUI, given the thread's stored effort pref.
+ *
+ * WHY: claude persists effort GLOBALLY in its own settings.json, so a fresh
+ * TUI (start / `/new` / resume) comes up with the LAST globally-set level —
+ * possibly chosen in another topic. The bot keeps the real per-thread choice
+ * in `.claude-effort-prefs.json`; on every fresh spawn it must re-apply that
+ * choice by typing claude's native `/effort <level>` once the TUI is ready,
+ * BEFORE any buffered user prompt is replayed. This pure helper owns the tiny
+ * decision (which keystroke, or none) so it is unit-testable without driving
+ * a real tmux pane.
+ *
+ * No stored pref → `null` → type nothing (claude's own default stands). A
+ * stored level claude can't honour for the current model is returned as-is:
+ * claude clamps unsupported levels per model (documented behavior), so the
+ * adapter does NOT validate here — same contract as a manual `/effort`.
+ */
+export declare function getEffortStartupKeystroke(storedLevel: string | null): string | null;
+//# sourceMappingURL=effortStartupKeystroke.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"effortStartupKeystroke.d.ts","sourceRoot":"","sources":["../../src/utils/effortStartupKeystroke.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,yBAAyB,CAAC,WAAW,EAAE,MAAM,GAAG,IAAI,GAAG,MAAM,GAAG,IAAI,CAInF"}

package/dist/utils/effortStartupKeystroke.js

@@ -0,0 +1,28 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getEffortStartupKeystroke = getEffortStartupKeystroke;
+/**
+ * @description Decide the `/effort` slash-command keystroke to replay into a
+ * freshly spawned Claude TUI, given the thread's stored effort pref.
+ *
+ * WHY: claude persists effort GLOBALLY in its own settings.json, so a fresh
+ * TUI (start / `/new` / resume) comes up with the LAST globally-set level —
+ * possibly chosen in another topic. The bot keeps the real per-thread choice
+ * in `.claude-effort-prefs.json`; on every fresh spawn it must re-apply that
+ * choice by typing claude's native `/effort <level>` once the TUI is ready,
+ * BEFORE any buffered user prompt is replayed. This pure helper owns the tiny
+ * decision (which keystroke, or none) so it is unit-testable without driving
+ * a real tmux pane.
+ *
+ * No stored pref → `null` → type nothing (claude's own default stands). A
+ * stored level claude can't honour for the current model is returned as-is:
+ * claude clamps unsupported levels per model (documented behavior), so the
+ * adapter does NOT validate here — same contract as a manual `/effort`.
+ */
+function getEffortStartupKeystroke(storedLevel) {
+    const level = storedLevel?.trim();
+    if (!level)
+        return null;
+    return `/effort ${level}`;
+}
+//# sourceMappingURL=effortStartupKeystroke.js.map

package/dist/utils/effortStartupKeystroke.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"effortStartupKeystroke.js","sourceRoot":"","sources":["../../src/utils/effortStartupKeystroke.ts"],"names":[],"mappings":";;AAkBA,8DAIC;AAtBD;;;;;;;;;;;;;;;;;GAiBG;AACH,SAAgB,yBAAyB,CAAC,WAA0B;IAClE,MAAM,KAAK,GAAG,WAAW,EAAE,IAAI,EAAE,CAAC;IAClC,IAAI,CAAC,KAAK;QAAE,OAAO,IAAI,CAAC;IACxB,OAAO,WAAW,KAAK,EAAE,CAAC;AAC5B,CAAC"}

package/dist/utils/ensureSessionPlan.d.ts

@@ -0,0 +1,70 @@
+/**
+ * @description The pure decision behind `ensureAgentSession` (plan
+ * 2026-10-04-claude-process-lifecycle, L-D4): what to do so a conversation has a
+ * live agent session. A conversation whose process is gone but whose session id
+ * is still persisted is SLEEPING — it is resumed, never replaced by a fresh
+ * session; only `/quit`, `/new` and leaving the folder release the id. Every
+ * trigger (a message, a Jira request, a limit resume, a wake-up, a schedule) and
+ * every command that needs a live agent goes through the one choke point that
+ * acts on this plan, so no path can start a fresh conversation over a sleeping one.
+ */
+/** The persisted ids a conversation's agent row carries (one per backend family). */
+export interface PersistedSessionIds {
+    claudeSessionId?: string;
+    opencodeSessionId?: string;
+}
+export type EnsureSessionPlan = 
+/** A live session, or a start already under way (prompts buffer and replay). */
+{
+    kind: 'ready';
+}
+/** No folder bound — nothing can start. */
+ | {
+    kind: 'unbound';
+}
+/** Bound, but no adapter resolves and the caller gave no fallback — refuse. */
+ | {
+    kind: 'noAdapter';
+}
+/** A sleeping conversation: resume `sessionId` on `adapterName` (silently). */
+ | {
+    kind: 'resume';
+    adapterName: string;
+    sessionId: string;
+}
+/** Nothing to resume and the caller allows a fresh start. */
+ | {
+    kind: 'start';
+    adapterName: string;
+}
+/** Nothing to resume and the caller allows NO fresh start (a reminder, a topic's wake-up). */
+ | {
+    kind: 'nothingToResume';
+};
+export interface EnsureSessionPlanInput {
+    isActive: boolean;
+    isStarting: boolean;
+    hasBinding: boolean;
+    /** The adapter the session would run on, already resolved (explicit pick → in-memory → persisted → fallback). */
+    adapterName: string | null;
+    /** Whether `adapterName` is one of the two Claude backends (they share the on-disk transcript and its id). */
+    isClaudeBackend: boolean;
+    persistedIds: PersistedSessionIds | null;
+    /** Resume a sleeping session but never start a fresh one. */
+    isResumeOnly: boolean;
+}
+/**
+ * @description The persisted session id that belongs to `adapterName`: the Claude
+ * id for either Claude backend, the OpenCode id for OpenCode, none for a shell or
+ * an unknown adapter. Mirrors the id-wiping rule of the adapter switch, so an id
+ * of another family is never resumed on the wrong backend.
+ */
+export declare function getPersistedSessionIdForAdapter(persistedIds: PersistedSessionIds | null, adapterName: string, isClaudeBackend: boolean): string | null;
+export declare function getEnsureSessionPlan(input: EnsureSessionPlanInput): EnsureSessionPlan;
+/**
+ * @description What follows a resume that FAILED (the CLI refused the id, the
+ * process did not come up): a caller that may start fresh does — the conversation
+ * is told its previous one could not be resumed; a resume-only caller stops.
+ */
+export declare function getResumeFailureAction(isResumeOnly: boolean): 'startFresh' | 'fail';
+//# sourceMappingURL=ensureSessionPlan.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"ensureSessionPlan.d.ts","sourceRoot":"","sources":["../../src/utils/ensureSessionPlan.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAIH,qFAAqF;AACrF,MAAM,WAAW,mBAAmB;IAClC,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,iBAAiB,CAAC,EAAE,MAAM,CAAC;CAC5B;AAED,MAAM,MAAM,iBAAiB;AAC3B,gFAAgF;AAC9E;IAAE,IAAI,EAAE,OAAO,CAAA;CAAE;AACnB,2CAA2C;GACzC;IAAE,IAAI,EAAE,SAAS,CAAA;CAAE;AACrB,+EAA+E;GAC7E;IAAE,IAAI,EAAE,WAAW,CAAA;CAAE;AACvB,+EAA+E;GAC7E;IAAE,IAAI,EAAE,QAAQ,CAAC;IAAC,WAAW,EAAE,MAAM,CAAC;IAAC,SAAS,EAAE,MAAM,CAAA;CAAE;AAC5D,6DAA6D;GAC3D;IAAE,IAAI,EAAE,OAAO,CAAC;IAAC,WAAW,EAAE,MAAM,CAAA;CAAE;AACxC,8FAA8F;GAC5F;IAAE,IAAI,EAAE,iBAAiB,CAAA;CAAE,CAAC;AAEhC,MAAM,WAAW,sBAAsB;IACrC,QAAQ,EAAE,OAAO,CAAC;IAClB,UAAU,EAAE,OAAO,CAAC;IACpB,UAAU,EAAE,OAAO,CAAC;IACpB,iHAAiH;IACjH,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,8GAA8G;IAC9G,eAAe,EAAE,OAAO,CAAC;IACzB,YAAY,EAAE,mBAAmB,GAAG,IAAI,CAAC;IACzC,6DAA6D;IAC7D,YAAY,EAAE,OAAO,CAAC;CACvB;AAED;;;;;GAKG;AACH,wBAAgB,+BAA+B,CAC7C,YAAY,EAAE,mBAAmB,GAAG,IAAI,EACxC,WAAW,EAAE,MAAM,EACnB,eAAe,EAAE,OAAO,GACvB,MAAM,GAAG,IAAI,CAKf;AAED,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,sBAAsB,GAAG,iBAAiB,CAQrF;AAED;;;;GAIG;AACH,wBAAgB,sBAAsB,CAAC,YAAY,EAAE,OAAO,GAAG,YAAY,GAAG,MAAM,CAEnF"}

package/dist/utils/ensureSessionPlan.js

@@ -0,0 +1,54 @@
+"use strict";
+/**
+ * @description The pure decision behind `ensureAgentSession` (plan
+ * 2026-10-04-claude-process-lifecycle, L-D4): what to do so a conversation has a
+ * live agent session. A conversation whose process is gone but whose session id
+ * is still persisted is SLEEPING — it is resumed, never replaced by a fresh
+ * session; only `/quit`, `/new` and leaving the folder release the id. Every
+ * trigger (a message, a Jira request, a limit resume, a wake-up, a schedule) and
+ * every command that needs a live agent goes through the one choke point that
+ * acts on this plan, so no path can start a fresh conversation over a sleeping one.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getPersistedSessionIdForAdapter = getPersistedSessionIdForAdapter;
+exports.getEnsureSessionPlan = getEnsureSessionPlan;
+exports.getResumeFailureAction = getResumeFailureAction;
+const adapterNames_1 = require("../adapters/adapterNames");
+/**
+ * @description The persisted session id that belongs to `adapterName`: the Claude
+ * id for either Claude backend, the OpenCode id for OpenCode, none for a shell or
+ * an unknown adapter. Mirrors the id-wiping rule of the adapter switch, so an id
+ * of another family is never resumed on the wrong backend.
+ */
+function getPersistedSessionIdForAdapter(persistedIds, adapterName, isClaudeBackend) {
+    if (!persistedIds)
+        return null;
+    if (isClaudeBackend)
+        return persistedIds.claudeSessionId ?? null;
+    if (adapterName === adapterNames_1.openCodeAdapterName)
+        return persistedIds.opencodeSessionId ?? null;
+    return null;
+}
+function getEnsureSessionPlan(input) {
+    if (input.isActive || input.isStarting)
+        return { kind: 'ready' };
+    if (!input.hasBinding)
+        return { kind: 'unbound' };
+    if (!input.adapterName)
+        return { kind: 'noAdapter' };
+    const sessionId = getPersistedSessionIdForAdapter(input.persistedIds, input.adapterName, input.isClaudeBackend);
+    if (sessionId)
+        return { kind: 'resume', adapterName: input.adapterName, sessionId };
+    if (input.isResumeOnly)
+        return { kind: 'nothingToResume' };
+    return { kind: 'start', adapterName: input.adapterName };
+}
+/**
+ * @description What follows a resume that FAILED (the CLI refused the id, the
+ * process did not come up): a caller that may start fresh does — the conversation
+ * is told its previous one could not be resumed; a resume-only caller stops.
+ */
+function getResumeFailureAction(isResumeOnly) {
+    return isResumeOnly ? 'fail' : 'startFresh';
+}
+//# sourceMappingURL=ensureSessionPlan.js.map

package/dist/utils/ensureSessionPlan.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ensureSessionPlan.js","sourceRoot":"","sources":["../../src/utils/ensureSessionPlan.ts"],"names":[],"mappings":";AAAA;;;;;;;;;GASG;;AA2CH,0EASC;AAED,oDAQC;AAOD,wDAEC;AArED,2DAA+D;AAmC/D;;;;;GAKG;AACH,SAAgB,+BAA+B,CAC7C,YAAwC,EACxC,WAAmB,EACnB,eAAwB;IAExB,IAAI,CAAC,YAAY;QAAE,OAAO,IAAI,CAAC;IAC/B,IAAI,eAAe;QAAE,OAAO,YAAY,CAAC,eAAe,IAAI,IAAI,CAAC;IACjE,IAAI,WAAW,KAAK,kCAAmB;QAAE,OAAO,YAAY,CAAC,iBAAiB,IAAI,IAAI,CAAC;IACvF,OAAO,IAAI,CAAC;AACd,CAAC;AAED,SAAgB,oBAAoB,CAAC,KAA6B;IAChE,IAAI,KAAK,CAAC,QAAQ,IAAI,KAAK,CAAC,UAAU;QAAE,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,CAAC;IACjE,IAAI,CAAC,KAAK,CAAC,UAAU;QAAE,OAAO,EAAE,IAAI,EAAE,SAAS,EAAE,CAAC;IAClD,IAAI,CAAC,KAAK,CAAC,WAAW;QAAE,OAAO,EAAE,IAAI,EAAE,WAAW,EAAE,CAAC;IACrD,MAAM,SAAS,GAAG,+BAA+B,CAAC,KAAK,CAAC,YAAY,EAAE,KAAK,CAAC,WAAW,EAAE,KAAK,CAAC,eAAe,CAAC,CAAC;IAChH,IAAI,SAAS;QAAE,OAAO,EAAE,IAAI,EAAE,QAAQ,EAAE,WAAW,EAAE,KAAK,CAAC,WAAW,EAAE,SAAS,EAAE,CAAC;IACpF,IAAI,KAAK,CAAC,YAAY;QAAE,OAAO,EAAE,IAAI,EAAE,iBAAiB,EAAE,CAAC;IAC3D,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,WAAW,EAAE,KAAK,CAAC,WAAW,EAAE,CAAC;AAC3D,CAAC;AAED;;;;GAIG;AACH,SAAgB,sBAAsB,CAAC,YAAqB;IAC1D,OAAO,YAAY,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,YAAY,CAAC;AAC9C,CAAC"}

package/dist/utils/fileSendPlan.d.ts

@@ -0,0 +1,217 @@
+/**
+ * @description Pure decision layer for the agent→Telegram file/image send
+ * (`send_file_to_user` MCP tool). Four concerns, all side-effect-free enough to
+ * unit-test without booting Telegraf:
+ *   1. {@link resolveSendFileWithinDir} — path-safety: resolve a caller-supplied
+ *      path against the topic's bound folder and confirm (realpath + containment)
+ *      it points at a REGULAR FILE inside it. Modeled on
+ *      `validation.ts:validateSubdir`, but for a file (not a directory) and
+ *      returning a discriminated result instead of throwing (the caller surfaces
+ *      the error to the agent as an MCP tool error).
+ *   2. {@link classifyFileSendKind} — map an extension to how Telegram should
+ *      render it (inline photo / autoplay animation / inline video / plain document).
+ *   3. {@link planFileSend} — decide the single Telegram send method (or album
+ *      shape) for 1..10 items, applying the `as_file` override, the photo size
+ *      downgrade, and the album photo/video-vs-document rule. Returns the
+ *      over-cap / count violations as an error variant rather than throwing.
+ *   4. {@link buildTelegramFileSendRequest} — turn a non-error plan into the
+ *      exact typed Bot API request shape, including caption placement.
+ *
+ * The only fs touch is the bigint `statSync` inside
+ * {@link resolveSendFileWithinDir} (unavoidable for the regular-file and
+ * identity gates). The caller supplies owned descriptor snapshots, so planning
+ * and request construction never carry workspace paths into Telegraf.
+ */
+/** Telegram's inline-photo size cap; a photo-eligible file over this downgrades to a document. */
+export declare const telegramPhotoMaxBytes: number;
+/** Bot API hard send cap per file; anything over this is rejected, never sent. */
+export declare const telegramSendMaxBytes: number;
+/** Minimum item count that forms a media-group album (below ⇒ single send). */
+export declare const mediaGroupMin = 2;
+/** Maximum item count Telegram accepts in one media-group album. */
+export declare const mediaGroupMax = 10;
+/** Telegram caption length cap (characters); longer captions are trimmed. */
+export declare const captionMaxLength = 1024;
+/** Extensions rendered as inline photos (lowercased, leading dot). */
+export declare const photoExtensions: readonly string[];
+/** Extensions rendered as looping animations (lowercased, leading dot). */
+export declare const animationExtensions: readonly string[];
+/** Extensions rendered with Telegram's native streaming video player. */
+export declare const videoExtensions: readonly string[];
+/**
+ * @name FileSendKind
+ * @description How Telegram should render a file: inline `photo`, autoplay
+ * `animation` (gif), native `video`, or plain `document`.
+ */
+export type FileSendKind = 'photo' | 'animation' | 'video' | 'document';
+/**
+ * @name ResolveSendFileCode
+ * @description Stable failure code for {@link resolveSendFileWithinDir}, so the
+ * caller can build a readable, path-naming tool error per case.
+ */
+export type ResolveSendFileCode = 'INVALID_CHARS' | 'OUTSIDE_FOLDER' | 'NOT_FOUND' | 'NOT_A_FILE';
+/** Device/inode identity captured during canonical-path validation. */
+export interface FileIdentity {
+    dev: bigint;
+    ino: bigint;
+}
+/**
+ * @name ResolveSendFileResult
+ * @description Discriminated outcome of resolving a single send path. `ok` carries
+ * the safe absolute path, its canonical root, and file identity; the failure
+ * carries a readable message + a stable code.
+ */
+export type ResolveSendFileResult = {
+    ok: true;
+    absPath: string;
+    rootPath: string;
+    identity: FileIdentity;
+} | {
+    ok: false;
+    error: string;
+    code: ResolveSendFileCode;
+};
+/**
+ * @description Resolve `rawPath` against the topic's bound `workDir` and confirm
+ * it points at a regular file living inside it. A multi-file caller supplies
+ * `pinnedRootPath` after the first item so a replaced binding cannot become a
+ * new trusted root between album items. Defence-in-depth mirrors
+ * `validateSubdir`: reject control chars, NFC-normalise, canonicalize the root,
+ * then use the shared canonical candidate containment gate. The final gate differs: this is for a
+ * FILE, so `statSync` must report a regular file (a directory or socket is
+ * rejected, not accepted).
+ */
+export declare function resolveSendFileWithinDir(workDir: string, rawPath: string, pinnedRootPath?: string): ResolveSendFileResult;
+/**
+ * @description Classify a path by its lowercased extension into the Telegram
+ * render kind. `.png/.jpg/.jpeg/.webp` → photo; `.gif` → animation; `.mp4` →
+ * video; anything else → document.
+ */
+export declare function classifyFileSendKind(filePath: string): FileSendKind;
+/** Derive a multipart-safe filename from a canonical file path. */
+export declare function getTelegramUploadFilename(filePath: string): string;
+/**
+ * @description Trim a caption to Telegram's {@link captionMaxLength} cap. Returns
+ * `undefined` for an absent/blank caption so callers can omit the field entirely.
+ */
+export declare function trimCaption(caption: string | undefined): string | undefined;
+/**
+ * @name FileSendItem
+ * @description One resolved file the planner reasons about: its safe absolute
+ * path, pinned descriptor snapshot, and render kind.
+ */
+export interface FileSendItem {
+    absPath: string;
+    source: FileDescriptorSnapshot;
+    kind: FileSendKind;
+}
+/**
+ * @name FileSendPlan
+ * @description Discriminated send plan:
+ *  - `kind: 'send'` — one file via a single Telegram method (`mode`).
+ *  - `kind: 'album'` — 2..10 files via `sendMediaGroup`, either native photos /
+ *    videos or all documents (`mode`).
+ *  - `kind: 'error'` — a count/size violation; `error` names the offending file.
+ */
+export type FileSendPlan = {
+    kind: 'send';
+    mode: FileSendKind;
+    item: FileSendItem;
+} | {
+    kind: 'album';
+    mode: 'albumPhotoVideo' | 'albumDocument';
+    items: FileSendItem[];
+} | {
+    kind: 'error';
+    error: string;
+};
+/** A validated plan that can be converted into a Telegram request. */
+export type NonErrorFileSendPlan = Exclude<FileSendPlan, {
+    kind: 'error';
+    error: string;
+}>;
+/** Exact Bot API methods used for one-file sends. */
+export type TelegramSingleFileSendMethod = 'sendPhoto' | 'sendAnimation' | 'sendVideo' | 'sendDocument';
+/** Owned descriptor snapshot transferred from the reader to the send service. */
+export interface FileDescriptorSnapshot {
+    fd: number;
+    filename: string;
+    sizeBytes: number;
+}
+export interface FileSendPhotoMedia {
+    type: 'photo';
+    media: FileDescriptorSnapshot;
+    caption?: string;
+}
+export interface FileSendVideoMedia {
+    type: 'video';
+    media: FileDescriptorSnapshot;
+    caption?: string;
+}
+export interface FileSendDocumentMedia {
+    type: 'document';
+    media: FileDescriptorSnapshot;
+    caption?: string;
+}
+/** Native photo/video group accepted by the file-send gateway. */
+export interface FileSendPhotoVideoMediaGroup {
+    kind: 'photoVideo';
+    media: Array<FileSendPhotoMedia | FileSendVideoMedia>;
+}
+/** Homogeneous document group accepted by the file-send gateway. */
+export interface FileSendDocumentMediaGroup {
+    kind: 'document';
+    media: FileSendDocumentMedia[];
+}
+/** Project-owned media group; the discriminant preserves Bot API homogeneity. */
+export type FileSendMediaGroup = FileSendPhotoVideoMediaGroup | FileSendDocumentMediaGroup;
+/** One-file request ready for `bot.telegram[method]`, apart from thread routing. */
+export interface TelegramSingleFileSendRequest {
+    method: TelegramSingleFileSendMethod;
+    source: FileDescriptorSnapshot;
+    caption?: string;
+}
+/** Photo/video media-group request preserving each eligible item's native type. */
+export interface TelegramPhotoVideoAlbumRequest {
+    method: 'sendMediaGroup';
+    mediaGroup: FileSendPhotoVideoMediaGroup;
+}
+/** Document media-group request used for every whole-album fallback. */
+export interface TelegramDocumentAlbumRequest {
+    method: 'sendMediaGroup';
+    mediaGroup: FileSendDocumentMediaGroup;
+}
+/** Exact Telegram request built from a non-error file-send plan. */
+export type TelegramFileSendRequest = TelegramSingleFileSendRequest | TelegramPhotoVideoAlbumRequest | TelegramDocumentAlbumRequest;
+/**
+ * @description Convert a non-error plan into the exact Telegram request the bot
+ * executes. Captions are trimmed here and included on a single request or only
+ * the first media-group entry. `albumPhotoVideo` accepts only photo/video items;
+ * an impossible hand-built plan throws a path-naming error instead of silently
+ * sending another kind as a photo.
+ */
+export declare function buildTelegramFileSendRequest(plan: NonErrorFileSendPlan, caption?: string): TelegramFileSendRequest;
+/** Existing user-facing hard-cap error shared by planning and snapshot reads. */
+export declare function getTelegramFileOversizeError(absPath: string): string;
+/** Existing user-facing item-count validation shared by planning and the reader. */
+export declare function getFileSendCountError(itemCount: number): string | null;
+/**
+ * @description Decide how to deliver 1..10 resolved files.
+ *
+ * Single file: the method is the item's kind, with two overrides —
+ *  - `asFile` forces `document` for every kind, and
+ *  - a photo over {@link telegramPhotoMaxBytes} downgrades to `document` so it
+ *    still goes through (just not inline).
+ *
+ * Album (2..10): `albumPhotoVideo` when `!asFile` and EVERY item is either a
+ * video or a photo within the photo cap, preserving each item's native media
+ * type in all-photo, all-video, and mixed photo/video groups. Otherwise use
+ * `albumDocument` (animations/documents and over-cap photos included — a media
+ * group cannot carry animation items, so a gif rides as a document in an album
+ * and only autoplays when sent alone).
+ *
+ * Returns an `error` plan for 0 items, >{@link mediaGroupMax}, or any item over
+ * {@link telegramSendMaxBytes}.
+ */
+export declare function planFileSend(items: FileSendItem[], asFile: boolean): FileSendPlan;
+//# sourceMappingURL=fileSendPlan.d.ts.map

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

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