@phnx-labs/agents-cli 1.22.107 → 1.22.110

package/dist/lib/session/parse.js

@@ -12,6 +12,7 @@ import * as path from 'path';
 import Database from '../sqlite.js';
 import { isSyntheticUserMessage, extractSlashCommandName, extractSlashCommandFromToolInput, unwrapUserQuery } from './prompt.js';
 import { structuredToolResult, commandsFromCodexExec } from './tool-calls.js';
+import { isCloudSessionPath } from './cloud.js';
 /**
  * Largest session file we will load into memory. Above this we throw a clean
  * error instead of OOMing or hitting V8's ERR_STRING_TOO_LONG. Aligns with
@@ -143,7 +144,11 @@ const TRANSCRIPT_PARSERS = {
     codex: (filePath) => parseCodex(filePath),
     gemini: (filePath) => parseGemini(filePath),
     antigravity: (filePath) => parseAntigravity(filePath),
-    opencode: (filePath) => parseOpenCode(filePath),
+    // Cloud-captured opencode sessions are normalized JSONL (produced by the
+    // factory at capture time), NOT the local `opencode.db#<session>` SQLite
+    // composite the offline parser reads — route by whether the path is in the
+    // cloud session cache (PHNX-3845).
+    opencode: (filePath) => isCloudSessionPath(filePath) ? parseOpencodeCloud(filePath) : parseOpenCode(filePath),
     grok: (filePath) => parseGrok(filePath),
     rush: (filePath) => parseRush(filePath),
     openclaw: () => [], // OpenClaw sessions don't have parseable files yet
@@ -206,7 +211,7 @@ export function detectAgent(filePath) {
         return 'muse';
     }
     // Cloud convention: cloud-sessions/<id>/session.<format>.jsonl
-    const cloudMatch = filePath.match(/session\.(claude|codex|rush)\.jsonl(?:$|[?#])/);
+    const cloudMatch = filePath.match(/session\.(claude|codex|rush|opencode)\.jsonl(?:$|[?#])/);
     if (cloudMatch)
         return cloudMatch[1];
     if (filePath.includes('opencode.db'))
@@ -1832,6 +1837,135 @@ export function parseOpenCode(filePath) {
     return events;
 }
 // ---------------------------------------------------------------------------
+// OpenCode parser — cloud (normalized JSONL)
+// ---------------------------------------------------------------------------
+//
+// OpenCode stores sessions in a SQLite DB, so the offline path reads a
+// `opencode.db#<session>` composite (parseOpenCode above). The CLOUD path is
+// different: the factory converts that DB into a flat, normalized JSONL
+// transcript at capture time (prix/factory opencode-capture.ts, PHNX-3845), so
+// the whole cloud pipeline stays SQLite-free downstream. This parser reads that
+// JSONL; it's routed from TRANSCRIPT_PARSERS only when the file lives in the
+// cloud session cache (isCloudSessionPath).
+//
+// Each line is one of:
+//   transcript row:
+//     { role: "user"|"assistant", part_type: "text"|"reasoning"|"tool",
+//       part_data: <json string>, time_created: <ms number> }
+//   todo snapshot (at most one, emitted last):
+//     { part_type: "todo", todos: [{content,status}], time_created: <ms> }
+//
+// The per-part logic mirrors parseOpenCode's post-query switch (and prix/api's
+// server-side parseOpencode) so the event stream is identical to the offline
+// path. NOTE: the shell tool is named `bash` on real opencode (>=1.18.x), not
+// `shell` — map `command` for both so a shell step reads by its command line.
+export function parseOpencodeCloud(filePath) {
+    const content = safeReadSessionFile(filePath);
+    const lines = content.split('\n').filter(l => l.trim());
+    const events = [];
+    for (const line of lines) {
+        let raw;
+        try {
+            raw = JSON.parse(line);
+        }
+        catch {
+            /* malformed JSONL line, skip */
+            continue;
+        }
+        const partType = typeof raw.part_type === 'string' ? raw.part_type : '';
+        const timeMs = typeof raw.time_created === 'number'
+            ? raw.time_created
+            : parseInt(String(raw.time_created), 10);
+        const timestamp = Number.isFinite(timeMs)
+            ? new Date(timeMs).toISOString()
+            : new Date().toISOString();
+        // Todo snapshot: emit one `todo_write` tool_use so the shared enrichment
+        // (`extractTodoProgressFromEvents`) derives `todos` the same way it does for
+        // every other harness — the offline parser emits the identical event.
+        if (partType === 'todo') {
+            const todos = Array.isArray(raw.todos) ? raw.todos : [];
+            if (todos.length) {
+                events.push({
+                    type: 'tool_use',
+                    agent: 'opencode',
+                    timestamp,
+                    tool: 'todo_write',
+                    args: { todos },
+                });
+            }
+            continue;
+        }
+        let partData;
+        try {
+            partData = JSON.parse(typeof raw.part_data === 'string' ? raw.part_data : '');
+        }
+        catch {
+            /* malformed part data, skip */
+            continue;
+        }
+        switch (partType) {
+            case 'text': {
+                const text = (partData.text || '').trim();
+                if (text) {
+                    events.push({
+                        type: 'message',
+                        agent: 'opencode',
+                        timestamp,
+                        role: raw.role === 'user' ? 'user' : 'assistant',
+                        content: text,
+                    });
+                }
+                break;
+            }
+            case 'reasoning': {
+                const text = (partData.text || '').trim();
+                if (text) {
+                    events.push({
+                        type: 'thinking',
+                        agent: 'opencode',
+                        timestamp,
+                        content: text,
+                    });
+                }
+                break;
+            }
+            case 'tool': {
+                const toolName = partData.tool || 'unknown';
+                const state = partData.state || {};
+                const input = state.input || {};
+                const output = state.output || '';
+                const callId = typeof partData.callID === 'string' ? partData.callID : undefined;
+                events.push({
+                    type: 'tool_use',
+                    agent: 'opencode',
+                    timestamp,
+                    tool: toolName,
+                    callId,
+                    args: input,
+                    command: toolName === 'bash' || toolName === 'shell' ? input.command : undefined,
+                    path: input.filePath || input.path || undefined,
+                });
+                if (state.status === 'completed' || state.status === 'error') {
+                    const outputStr = typeof output === 'string' ? output : JSON.stringify(output);
+                    events.push({
+                        type: state.status === 'error' ? 'error' : 'tool_result',
+                        agent: 'opencode',
+                        timestamp,
+                        tool: toolName,
+                        callId,
+                        success: state.status === 'completed',
+                        output: outputStr,
+                    });
+                }
+                break;
+            }
+            // step-start / step-finish / patch / file never reach the JSONL (dropped
+            // at capture time) — nothing to handle here.
+        }
+    }
+    return events;
+}
+// ---------------------------------------------------------------------------
 // Rush parser
 //
 // Rush messages.jsonl format is flat: one JSON object per line with

package/dist/lib/session/recovery.d.ts

@@ -68,7 +68,15 @@ export declare function sessionMatchesAccount(session: Pick<SessionMeta, 'agent'
 export declare function inspectNativeResumeSession(session: SessionMeta, versionHome: string): NativeResumeInspection;
 /** Keep the native conversation where possible; replay remains a separate choice. */
 export declare function resolveSessionRecoveryFromCandidates(session: SessionMeta, candidates: RotateCandidate[], supportsNative?: (agent: AgentId, version?: string) => boolean, nativeInspection?: NativeResumeInspection, options?: SessionRecoverySelection): SessionRecoveryTarget;
-/** A mirror digest or live registry entry is not conversation content. */
+/**
+ * Whether recovery has conversation content to replay for this session: a
+ * non-empty transcript file, or archived content in the index for a row this
+ * device owns. A mirror digest or live registry entry is not conversation
+ * content. The picker consults this before spending a terminal tab on a pick
+ * that {@link assertRecoverableTranscript} would refuse one hop later.
+ */
+export declare function sessionTranscriptReadable(session: SessionMeta): boolean;
+/** Refuse recovery for a session with nothing to replay (PHNX-4080). */
 export declare function assertRecoverableTranscript(session: SessionMeta): void;
 /**
  * Resolve recovery for a durable session, reading the live account pool.

package/dist/lib/session/recovery.js

@@ -365,16 +365,26 @@ export function resolveSessionRecoveryFromCandidates(session, candidates, suppor
         reason: `${sourceReason(session, source, options.model ?? session.model)}; continuing with ${continueWith}`,
     };
 }
-/** A mirror digest or live registry entry is not conversation content. */
-export function assertRecoverableTranscript(session) {
+/**
+ * Whether recovery has conversation content to replay for this session: a
+ * non-empty transcript file, or archived content in the index for a row this
+ * device owns. A mirror digest or live registry entry is not conversation
+ * content. The picker consults this before spending a terminal tab on a pick
+ * that {@link assertRecoverableTranscript} would refuse one hop later.
+ */
+export function sessionTranscriptReadable(session) {
     const file = splitSessionFilePath(session.filePath).container;
     try {
         if (file && fs.statSync(file).isFile() && fs.statSync(file).size > 0
             && (session.agent !== 'opencode' || parseOpenCode(session.filePath).length > 0))
-            return;
+            return true;
     }
     catch { /* The canonical scan already tried to repair this path. */ }
-    if (!session.mirrorSyncedAt && !session.mirrorSource && readSessionContent(session.id)?.trim())
+    return !session.mirrorSyncedAt && !session.mirrorSource && Boolean(readSessionContent(session.id)?.trim());
+}
+/** Refuse recovery for a session with nothing to replay (PHNX-4080). */
+export function assertRecoverableTranscript(session) {
+    if (sessionTranscriptReadable(session))
         return;
     throw new SessionRecoveryError(`Session ${session.shortId} has no readable transcript after checking its account homes and index. ` +
         `No agent was started. Start a new conversation with: agents run ${session.agent}`);

package/dist/lib/session/remote/watch.js

@@ -60,6 +60,16 @@ function epochMs(value) {
 export function previousSessionWatchRowKey(scope, sessionId) {
     return createHash('sha256').update(`${scope}\0previous\0${sessionId}`).digest('base64url').slice(0, 22);
 }
+/**
+ * The headline for a durable history row, on the same ladder a live row uses
+ * ({@link deriveSessionRecap}): an explicit `/rename` label, then the
+ * daemon-generated title (PHNX-3797), then the daemon-folded request headline
+ * (`request.headline` — the user's own sentence with attachment noise pulled
+ * out, PHNX-3939) when the transcript cache has one, else the raw `topic`.
+ */
+function previousRowTitle(session, foldedHeadline) {
+    return session.label || session.generatedTitle || foldedHeadline || session.topic || undefined;
+}
 /** Project one durable indexed session into the same canonical watch contract
  * as live sessions. This is the only history backfill consumed by AGI EXT. */
 export function toPreviousSessionWatchRow(scope, session) {
@@ -86,6 +96,7 @@ export function toPreviousSessionWatchRow(scope, session) {
     // transcript-keyed cache the live merge reads (PHNX-3939), so a closed session
     // still shows the request it was given and what the agent did — no re-parse.
     const folded = readSessionTimelineAny(session.id);
+    const title = previousRowTitle(session, folded?.request?.headline);
     return {
         context: 'recent',
         kind: session.agent,
@@ -93,14 +104,13 @@ export function toPreviousSessionWatchRow(scope, session) {
         sessionId: session.id,
         ...(session.cwd ? { cwd: session.cwd } : {}),
         ...(session.project ? { project: session.project } : {}),
-        // `request.headline` is the user's own sentence with the attachment noise
-        // pulled out, so it beats the raw `topic` for the row title — a `/model` echo
-        // or a skill body can no longer become a session's name (PHNX-3939).
-        ...(session.label
-            ? { label: session.label, title: session.label }
-            : folded?.request?.headline
-                ? { title: folded.request.headline }
-                : session.topic ? { title: session.topic } : {}),
+        // Same headline ladder as a live row (`deriveSessionRecap`, PHNX-3797):
+        // `/rename` label → the daemon-generated title → `request.headline` (the
+        // user's own sentence with attachment noise pulled out, PHNX-3939) →
+        // the raw `topic`. See {@link previousRowTitle}.
+        ...(session.label ? { label: session.label } : {}),
+        ...(session.generatedTitle ? { generatedTitle: session.generatedTitle } : {}),
+        ...(title ? { title } : {}),
         ...(session.topic ? { topic: session.topic } : {}),
         ...(session.firstUserMessage ? { firstUserMessage: session.firstUserMessage } : {}),
         ...(session.version ? { version: session.version } : {}),

package/dist/lib/session/title.d.ts

@@ -0,0 +1,256 @@
+/**
+ * Daemon-generated session TITLES (PHNX-3797).
+ *
+ * The headline on a session row answers "what is this session about?", so it has
+ * to be anchored in what the USER asked for. It used to be the agent's latest
+ * transcript line — verbose, rolling, and unrecognizable to the person who
+ * started the run. The fix is a two-rung answer:
+ *
+ *  1. INSTANT, free: the user's own first message (already in the index) is the
+ *     honest fallback shown from the moment the session appears.
+ *  2. UPGRADED, once: this module asks a CHEAP model (via a swappable
+ *     {@link SessionTitleProvider}; the default {@link CloudSessionTitleProvider}
+ *     uses the `cheap` tier — haiku on Claude — through the same
+ *     `agents run --model <tier>` resolution every other call uses) for a short
+ *     ACTION + OBJECT headline of what the session is doing, and persists it in
+ *     the session index.
+ *
+ * Generation happens ONCE per session, in the daemon, and is keyed by
+ * {@link sessionTitleSourceKey} — a hash of the user text the title was derived
+ * from — so a sweep that sees a stored key matching the row's current text skips
+ * it (the cache hit) and regenerates only when that first user message actually
+ * changed, or when an operator asks explicitly
+ * (`agents sessions backfill titles --refresh`). There is no per-tick model call
+ * and no per-client generation: the daemon writes one value, every consumer
+ * (local list, picker, `sessions watch --json`, the fleet mirror, AGI EXT) reads
+ * it off the row.
+ *
+ * Everything here except {@link runSessionTitleTick} is pure, and the tick takes
+ * an injectable runner seam, so the whole path is testable without spawning a
+ * harness.
+ */
+import type { SessionTitleCandidateRow } from './db.js';
+/**
+ * The phrase every generated-title prompt carries. Load-bearing twice over:
+ * `traces/sync.ts` classifies a session whose topic matches it as internal
+ * `utility` plumbing rather than agent work, and {@link isSessionTitlePrompt}
+ * uses it to keep the titler from titling its OWN spawned sessions — which
+ * would otherwise be a runaway loop, since each generation creates one more
+ * untitled session.
+ *
+ * It is a STABLE sentinel, not the human-readable instruction: keep it exact and
+ * keep `traces/sync.ts`'s matching regex in sync when it changes. The surrounding
+ * prompt (see {@link renderSessionTitlePrompt}) asks for an action+object headline
+ * of 4–8 words; the sentinel deliberately carries no word budget so the two never
+ * drift.
+ */
+export declare const SESSION_TITLE_PROMPT_MARKER = "Generate a concise session headline";
+/** Hard ceiling on a stored title; the prompt asks for far less. */
+export declare const SESSION_TITLE_MAX_CHARS = 60;
+/** Hard ceiling on words kept from a model reply that ignored the word budget. */
+export declare const SESSION_TITLE_MAX_WORDS = 8;
+/** How much user text the prompt carries — enough to be specific, bounded for cost. */
+export declare const SESSION_TITLE_INPUT_MAX_CHARS = 2000;
+/** How many sessions one periodic sweep may generate for. */
+export declare const SESSION_TITLE_MAX_PER_TICK = 2;
+/** How many recent rows a sweep inspects before picking that batch. */
+export declare const SESSION_TITLE_CANDIDATE_SCAN = 200;
+/** Only sessions active within this window are titled — older rows are not shown. */
+export declare const SESSION_TITLE_MAX_AGE_MS: number;
+/** Per-generation subprocess ceiling. A title is not worth waiting on. */
+export declare const SESSION_TITLE_TIMEOUT_MS = 45000;
+/** The harnesses the titler will run as, best first. The first installed one wins. */
+export declare const SESSION_TITLE_AGENTS: readonly ["claude", "codex", "grok", "kimi", "opencode"];
+/** The user text a title is derived from, plus the context that makes it technical. */
+export interface SessionTitleInput {
+    firstUserMessage?: string | null;
+    topic?: string | null;
+    project?: string | null;
+    ticketId?: string | null;
+    gitBranch?: string | null;
+}
+/** The user text itself — the ONLY thing the source key is computed over. */
+export declare function sessionTitleSourceText(input: SessionTitleInput): string;
+/**
+ * Stable identity of the text a title was generated from. Storing this beside
+ * the title is what makes "already titled" distinguishable from "the user's
+ * first message changed" without keeping a second copy of that text.
+ * Empty text yields `null`: there is nothing to title.
+ */
+export declare function sessionTitleSourceKey(input: SessionTitleInput): string | null;
+/**
+ * True when this text is one of the titler's OWN prompts. The titler runs a real
+ * harness, which writes a real transcript, which lands in the index as another
+ * untitled session — so without this guard every title generated would create
+ * work for the next sweep, forever.
+ */
+export declare function isSessionTitlePrompt(...values: Array<string | null | undefined>): boolean;
+/**
+ * The one-shot prompt handed to the cheap model.
+ *
+ * It asks for a descriptive ACTION + OBJECT headline (a verb phrase naming the
+ * concrete task, "Triage the AGI board", "Rename browser profile — default
+ * confusion"), not a single terse noun ("Triage") and not a full sentence — the
+ * headline slot has to tell the person who started the run what the session is
+ * doing at a glance. The word budget is soft in the prompt and hard-enforced by
+ * {@link sanitizeGeneratedTitle}'s {@link SESSION_TITLE_MAX_WORDS} ceiling.
+ */
+export declare function renderSessionTitlePrompt(input: SessionTitleInput): string;
+/**
+ * Reduce a model reply to a storable title, or `undefined` when it produced
+ * nothing usable. Takes the first non-empty line (a chatty model puts the title
+ * first), strips wrapping quotes/backticks and trailing punctuation, and applies
+ * the word + character ceilings. A reply that is really a refusal or an
+ * explanation fails the ceilings and is dropped rather than shown.
+ */
+export declare function sanitizeGeneratedTitle(raw: string | null | undefined): string | undefined;
+/**
+ * Compile-time guard: resolves to `T` only when `T` actually declares a
+ * `generatedTitle` key, and to `never` otherwise.
+ *
+ * This exists because structural typing makes the obvious signature useless. A
+ * parameter typed `{ generatedTitle?: string }` is satisfied by an object type
+ * that has no such property at all, so passing a projection that DROPPED the
+ * field — the watchdog's `SessionOutcome`, which copied `label`/`name`/`topic`
+ * off the session and left `generatedTitle` behind — compiles cleanly and
+ * silently degrades {@link sessionHeadline} back to `label || topic`. That is a
+ * real bug this feature shipped once and a lexical lint cannot see, since the
+ * call site looks correct. `keyof` includes optional keys, so every legitimate
+ * carrier (`SessionMeta`, `ActiveSession`, a `Pick<>` that names it) still
+ * passes; only a type that never modelled the rung is rejected.
+ */
+type CarriesTitleRung<T> = 'generatedTitle' extends keyof T ? T : never;
+/**
+ * The headline for an INDEXED session row, on the same ladder the live path uses
+ * (`deriveSessionRecap`, active.ts): `/rename` label → daemon-generated title →
+ * first-prompt topic. Every `agents sessions` surface that shows "what this
+ * session is" reads it from here, so the CLI and the watch stream can never
+ * disagree about a session's name (PHNX-3797).
+ *
+ * A caller whose row type does not carry `generatedTitle` fails to compile
+ * (see {@link CarriesTitleRung}) — fix the projection to carry the field rather
+ * than casting past this.
+ */
+export declare function sessionHeadline<T extends {
+    label?: string | null;
+    generatedTitle?: string | null;
+    topic?: string | null;
+}>(row: CarriesTitleRung<T>): string | undefined;
+/**
+ * Runs the cheap model once and returns its raw stdout. Injectable so tests
+ * exercise the whole tick — candidate selection, key comparison, persistence —
+ * without spawning a harness.
+ */
+export type SessionTitleRunner = (prompt: string, signal?: AbortSignal) => Promise<string>;
+/** The harness the titler runs as on this box, or null when none is installed. */
+export declare function resolveSessionTitleAgent(): Promise<string | null>;
+/**
+ * The real runner: ONE `agents run <agent> --mode plan --model cheap <prompt>`
+ * subprocess. `--mode plan` keeps it read-only (it must never touch a repo), and
+ * `--model cheap` goes through the same tier resolution every other run uses, so
+ * the box's own catalog picks haiku (or its per-harness equivalent) rather than
+ * this module hardcoding a model id that ages out.
+ */
+export declare function defaultSessionTitleRunner(prompt: string, signal?: AbortSignal): Promise<string>;
+/**
+ * A pluggable backend that turns a session's user text into a raw headline reply
+ * — the ONE part of title generation that varies by model host (PHNX-3797).
+ *
+ * The tick decides WHICH sessions need a title, caches by source key, sanitizes,
+ * and persists — none of that is provider-specific, so only the model call itself
+ * sits behind this interface. The shipped default is
+ * {@link CloudSessionTitleProvider} (one cheap cloud-model subprocess). A LOCAL
+ * backend — e.g. an ollama 1–3B instruct model over HTTP — is a drop-in: implement
+ * `generate` and hand the instance to {@link runSessionTitleTick} (or construct
+ * {@link SessionTitleService} with it). No call site inside the tick changes, and
+ * the shared {@link sanitizeGeneratedTitle} still enforces the word/character
+ * ceilings on whatever text the backend returns.
+ *
+ * `generate` returns the model's RAW reply (the tick owns sanitizing). It MAY
+ * throw — harness missing, signed out, timed out — and the tick treats a throw as
+ * "no title this sweep", leaving the row on the user's own words and backing off.
+ */
+export interface SessionTitleProvider {
+    /** Stable id for logs/diagnostics (e.g. `'cloud'`, `'ollama'`). */
+    readonly name: string;
+    /** Produce a raw headline reply for one session's user text, or throw. */
+    generate(input: SessionTitleInput, signal?: AbortSignal): Promise<string>;
+}
+/**
+ * The default, shipped provider: render the shared prompt and run it through a
+ * {@link SessionTitleRunner} — by default {@link defaultSessionTitleRunner}, the
+ * one cheap `agents run --model cheap` subprocess. Tests inject a fake runner (or
+ * a whole fake provider) to exercise the tick without spawning a harness.
+ */
+export declare class CloudSessionTitleProvider implements SessionTitleProvider {
+    private readonly runner;
+    readonly name = "cloud";
+    constructor(runner?: SessionTitleRunner);
+    generate(input: SessionTitleInput, signal?: AbortSignal): Promise<string>;
+}
+/** The provider used when a caller injects neither a `provider` nor a `run`. */
+export declare function defaultSessionTitleProvider(): SessionTitleProvider;
+export interface SessionTitleTickOptions {
+    /** Max sessions generated for in this sweep. */
+    limit?: number;
+    /** Title this session specifically (an explicit refresh), ignoring the recency window. */
+    id?: string;
+    /** Regenerate even when the stored key still matches the row's user text. */
+    force?: boolean;
+    /**
+     * The generation backend. Defaults to {@link defaultSessionTitleProvider}
+     * (the cheap cloud model). Swap this for a local model without touching the
+     * tick. Takes precedence over {@link SessionTitleTickOptions.run}.
+     */
+    provider?: SessionTitleProvider;
+    /**
+     * Shortcut seam for the cloud provider's raw model call — wrapped in a
+     * {@link CloudSessionTitleProvider} when no {@link provider} is given. Kept for
+     * the daemon service and the tests that inject only the subprocess.
+     */
+    run?: SessionTitleRunner;
+    signal?: AbortSignal;
+    nowMs?: number;
+    maxAgeMs?: number;
+}
+export interface SessionTitleTickResult {
+    /** Rows inspected. */
+    scanned: number;
+    /** Rows already carrying a title for their current user text (the cache hit). */
+    cached: number;
+    /** Titles generated and persisted this sweep. */
+    generated: number;
+    /** Generation attempts that produced nothing usable (model unavailable, empty reply). */
+    failed: number;
+    titles: Array<{
+        id: string;
+        title: string;
+    }>;
+}
+/**
+ * Decide what one sweep should do, without touching the model. Pure over its
+ * inputs so the "generate once, then cache-hit" property is directly testable:
+ * a candidate is work only when its user text yields a key AND that key differs
+ * from the one stored beside its title (or `force`).
+ */
+export declare function selectSessionsNeedingTitle(rows: SessionTitleCandidateRow[], opts?: {
+    limit: number;
+    force?: boolean;
+}): {
+    pending: Array<{
+        row: SessionTitleCandidateRow;
+        sourceKey: string;
+    }>;
+    cached: number;
+};
+/**
+ * One titling sweep: pick the sessions whose headline is still the raw user
+ * message, generate a title for at most {@link SessionTitleTickOptions.limit} of
+ * them, and persist each. Best-effort by contract — a failed generation leaves
+ * the row untitled, which the ladder renders as the user's own first message.
+ *
+ * Throws only for an explicit {@link SessionTitleTickOptions.id} that matches no
+ * indexed session (a caller error); the periodic sweep never throws.
+ */
+export declare function runSessionTitleTick(options?: SessionTitleTickOptions): Promise<SessionTitleTickResult>;
+export {};