charness 0.0.0-stage → 3.1.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/fallbackBridge.d.ts

@@ -0,0 +1,32 @@
+/**
+ * @description The CONTEXT BRIDGE a cross-backend fallback switch hands the new agent (`utils/fallbackChain.ts`):
+ * when a topic moves between Claude Code and OpenCode the adapter changes, the new session cannot read the
+ * old transcript, and the only thing it knows is what its first prompt tells it. That prompt is built here:
+ * why it takes over, the folder it shares with its predecessor, the predecessor's last turns verbatim
+ * (user and assistant), and the instruction to establish the state of the work from the project itself
+ * before carrying on — then to say in one short message what the task is, what is done and what remains.
+ *
+ * English on purpose (an agent-facing template, like the thread-context preamble) with a baked reply-language
+ * directive. Pure: the turns and labels come from the caller, so the shape is unit-tested.
+ */
+import type { RecentTurn } from '../types';
+/** How many of the previous agent's last turns the bridge carries (user and assistant turns alike). */
+export declare const fallbackBridgeTurnLimit = 6;
+/** A single turn longer than this is cut in the middle — the bridge is a hand-over, not a transcript copy. */
+export declare const fallbackBridgeTurnMaxChars = 2500;
+/**
+ * @description The bridge prompt. `turns` are chronological (oldest first), already capped by the caller;
+ * `resetsAtText` names when the exhausted account comes back (omitted when unknown).
+ */
+export declare function buildFallbackBridgePrompt(input: {
+    fromLabel: string;
+    toLabel: string;
+    turns: readonly RecentTurn[];
+    resetsAtText: string | null;
+    replyLanguage: string;
+}): string;
+/** Cut the middle of an over-long turn, keeping its head and tail (the ask and the outcome are at the ends). */
+export declare function truncateTurnText(text: string, maxChars?: number): string;
+/** Whether a prompt is a bridge (the request ledger and the trace must not read it as the user's own text). */
+export declare function checkIsFallbackBridgePrompt(text: string): boolean;
+//# sourceMappingURL=fallbackBridge.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"fallbackBridge.d.ts","sourceRoot":"","sources":["../../src/utils/fallbackBridge.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAGH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,UAAU,CAAC;AAE3C,uGAAuG;AACvG,eAAO,MAAM,uBAAuB,IAAI,CAAC;AAEzC,8GAA8G;AAC9G,eAAO,MAAM,0BAA0B,OAAO,CAAC;AAI/C;;;GAGG;AACH,wBAAgB,yBAAyB,CAAC,KAAK,EAAE;IAC/C,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,SAAS,UAAU,EAAE,CAAC;IAC7B,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B,aAAa,EAAE,MAAM,CAAC;CACvB,GAAG,MAAM,CAsBT;AAED,gHAAgH;AAChH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,GAAE,MAAmC,GAAG,MAAM,CAIpG;AAED,+GAA+G;AAC/G,wBAAgB,2BAA2B,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAEjE"}

package/dist/utils/fallbackBridge.js

@@ -0,0 +1,62 @@
+"use strict";
+/**
+ * @description The CONTEXT BRIDGE a cross-backend fallback switch hands the new agent (`utils/fallbackChain.ts`):
+ * when a topic moves between Claude Code and OpenCode the adapter changes, the new session cannot read the
+ * old transcript, and the only thing it knows is what its first prompt tells it. That prompt is built here:
+ * why it takes over, the folder it shares with its predecessor, the predecessor's last turns verbatim
+ * (user and assistant), and the instruction to establish the state of the work from the project itself
+ * before carrying on — then to say in one short message what the task is, what is done and what remains.
+ *
+ * English on purpose (an agent-facing template, like the thread-context preamble) with a baked reply-language
+ * directive. Pure: the turns and labels come from the caller, so the shape is unit-tested.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.fallbackBridgeTurnMaxChars = exports.fallbackBridgeTurnLimit = void 0;
+exports.buildFallbackBridgePrompt = buildFallbackBridgePrompt;
+exports.truncateTurnText = truncateTurnText;
+exports.checkIsFallbackBridgePrompt = checkIsFallbackBridgePrompt;
+const threadContextPreamble_1 = require("../threadContextPreamble");
+/** How many of the previous agent's last turns the bridge carries (user and assistant turns alike). */
+exports.fallbackBridgeTurnLimit = 6;
+/** A single turn longer than this is cut in the middle — the bridge is a hand-over, not a transcript copy. */
+exports.fallbackBridgeTurnMaxChars = 2500;
+const bridgeMarker = '[Backend switch]';
+/**
+ * @description The bridge prompt. `turns` are chronological (oldest first), already capped by the caller;
+ * `resetsAtText` names when the exhausted account comes back (omitted when unknown).
+ */
+function buildFallbackBridgePrompt(input) {
+    const lines = [
+        `${bridgeMarker} You (${input.toLabel}) are taking this conversation over from ${input.fromLabel}, which hit a usage limit${input.resetsAtText ? ` (it resets at ${input.resetsAtText})` : ''}. You work in the same project folder, but you cannot see its transcript.`,
+        '',
+        'Do this now:',
+        '1. Read the recent turns below to understand the task and where it stopped.',
+        '2. Establish the real state of the work from the project itself (git status, git diff, git log, the files mentioned) — trust the folder over the transcript when they disagree.',
+        `3. Reply IN ${input.replyLanguage} with ONE short message: the task as you understand it, what is already done, what remains.`,
+        '4. Then continue the work from where it stopped, without redoing what is done.',
+    ];
+    if (input.turns.length === 0) {
+        lines.push('', 'No turns of the previous agent are available: start from the project state and ask the user what the task is if it is not evident.');
+        return lines.join('\n');
+    }
+    lines.push('', `--- Last ${input.turns.length} turn(s) of ${input.fromLabel} (oldest first) ---`);
+    for (const turn of input.turns) {
+        const label = turn.role === 'user' ? 'User' : 'Assistant';
+        const text = turn.role === 'user' ? (0, threadContextPreamble_1.stripThreadContextPreamble)(turn.text) : turn.text;
+        lines.push('', `${label}:`, truncateTurnText(text.trim()));
+    }
+    lines.push('', '--- End of the previous agent\'s turns ---');
+    return lines.join('\n');
+}
+/** Cut the middle of an over-long turn, keeping its head and tail (the ask and the outcome are at the ends). */
+function truncateTurnText(text, maxChars = exports.fallbackBridgeTurnMaxChars) {
+    if (text.length <= maxChars)
+        return text;
+    const half = Math.floor((maxChars - 20) / 2);
+    return `${text.slice(0, half)}\n[… ${text.length - 2 * half} characters cut …]\n${text.slice(-half)}`;
+}
+/** Whether a prompt is a bridge (the request ledger and the trace must not read it as the user's own text). */
+function checkIsFallbackBridgePrompt(text) {
+    return text.startsWith(bridgeMarker);
+}
+//# sourceMappingURL=fallbackBridge.js.map

package/dist/utils/fallbackBridge.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"fallbackBridge.js","sourceRoot":"","sources":["../../src/utils/fallbackBridge.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;GAUG;;;AAiBH,8DA4BC;AAGD,4CAIC;AAGD,kEAEC;AAvDD,oEAAsE;AAGtE,uGAAuG;AAC1F,QAAA,uBAAuB,GAAG,CAAC,CAAC;AAEzC,8GAA8G;AACjG,QAAA,0BAA0B,GAAG,IAAI,CAAC;AAE/C,MAAM,YAAY,GAAG,kBAAkB,CAAC;AAExC;;;GAGG;AACH,SAAgB,yBAAyB,CAAC,KAMzC;IACC,MAAM,KAAK,GAAa;QACtB,GAAG,YAAY,SAAS,KAAK,CAAC,OAAO,4CAA4C,KAAK,CAAC,SAAS,4BAA4B,KAAK,CAAC,YAAY,CAAC,CAAC,CAAC,kBAAkB,KAAK,CAAC,YAAY,GAAG,CAAC,CAAC,CAAC,EAAE,2EAA2E;QACxQ,EAAE;QACF,cAAc;QACd,6EAA6E;QAC7E,iLAAiL;QACjL,eAAe,KAAK,CAAC,aAAa,6FAA6F;QAC/H,gFAAgF;KACjF,CAAC;IACF,IAAI,KAAK,CAAC,KAAK,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAC7B,KAAK,CAAC,IAAI,CAAC,EAAE,EAAE,oIAAoI,CAAC,CAAC;QACrJ,OAAO,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IAC1B,CAAC;IACD,KAAK,CAAC,IAAI,CAAC,EAAE,EAAE,YAAY,KAAK,CAAC,KAAK,CAAC,MAAM,eAAe,KAAK,CAAC,SAAS,qBAAqB,CAAC,CAAC;IAClG,KAAK,MAAM,IAAI,IAAI,KAAK,CAAC,KAAK,EAAE,CAAC;QAC/B,MAAM,KAAK,GAAG,IAAI,CAAC,IAAI,KAAK,MAAM,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,WAAW,CAAC;QAC1D,MAAM,IAAI,GAAG,IAAI,CAAC,IAAI,KAAK,MAAM,CAAC,CAAC,CAAC,IAAA,kDAA0B,EAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC;QACtF,KAAK,CAAC,IAAI,CAAC,EAAE,EAAE,GAAG,KAAK,GAAG,EAAE,gBAAgB,CAAC,IAAI,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC;IAC7D,CAAC;IACD,KAAK,CAAC,IAAI,CAAC,EAAE,EAAE,4CAA4C,CAAC,CAAC;IAC7D,OAAO,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AAC1B,CAAC;AAED,gHAAgH;AAChH,SAAgB,gBAAgB,CAAC,IAAY,EAAE,WAAmB,kCAA0B;IAC1F,IAAI,IAAI,CAAC,MAAM,IAAI,QAAQ;QAAE,OAAO,IAAI,CAAC;IACzC,MAAM,IAAI,GAAG,IAAI,CAAC,KAAK,CAAC,CAAC,QAAQ,GAAG,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;IAC7C,OAAO,GAAG,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,IAAI,CAAC,QAAQ,IAAI,CAAC,MAAM,GAAG,CAAC,GAAG,IAAI,uBAAuB,IAAI,CAAC,KAAK,CAAC,CAAC,IAAI,CAAC,EAAE,CAAC;AACxG,CAAC;AAED,+GAA+G;AAC/G,SAAgB,2BAA2B,CAAC,IAAY;IACtD,OAAO,IAAI,CAAC,UAAU,CAAC,YAAY,CAAC,CAAC;AACvC,CAAC"}