A local-first multi-agent app development platform, built on PenguinHarness
/**
* The **policy layer** for automatic Session title generation (conversation-page
* extension).
*
* "How to generate" lives in the core SDK (`session.generateTitle`: an out-of-band
* one-shot request on the session's own Model, no tools, thinking disabled, writes no
* history/Trace); this module is only responsible for host-side policy:
* - When: at Task start, from the **user input alone** — the moment a run begins with
* user text, the first words of that text are persisted as an immediate fallback
* title, and the LLM request fires in the background to replace it. Neither step
* waits for any model output.
* - Persistence and notification: writes sessions.title and pushes a `session_title`
* server event to the Session channel (once for the fallback, once more if the LLM
* result replaces it).
* - Manual renames win: the LLM result only ever replaces the fallback this generator
* wrote itself (tracked in memory per session); any other value is left alone.
* - Bookkeeping: the one-shot request's token consumption is converted to token_usage
* and handed to usage-recorder for persistence;
* - Silent failure (logged): the fallback stays in place, and while the stored title
* still equals it the next Task start retries the LLM request.
*/
import {
emptyTokenCounts,
matchAttachedFileLine,
matchAttachedImageLine,
sanitizeTitle,
stripConversationMarkers,
tokenUsage,
truncateTitle,
} from "@adelie/core";
import type { ServerEvent } from "../api/types.js";
import type { ChannelHub } from "./channel.js";
import type { ErrorSink } from "./error-recorder.js";
import type { RuntimeSession } from "./session-manager.js";
import type { UsageContext } from "./usage-recorder.js";
import type { UsageRecording } from "../mechanisms/observability.js";
import type { SessionIndex } from "../mechanisms/sessions.js";
export interface TitleGeneratorDeps {
sessions: SessionIndex;
channels: ChannelHub;
recorder: Pick<UsageRecording, "record">;
/** Error persistence (optional: without it, only logs — same as before this was wired up). */
errors?: ErrorSink;
log?: (line: string) => void;
/**
* Publishes the `session_title` event on the user-level channel of everyone who can see
* the Project (same contract as SessionManager's dep of the same name). This is what
* reaches the session list: titles land at Task start, typically before any tab has
* subscribed to the brand-new Session's own channel — the per-Session publish alone
* would be dropped unheard. Optional: without it only the per-Session channel is served.
*/
notifyProjectUsers?: (projectId: string, event: ServerEvent) => void;
}
/** Host-side parameters for one title-generation request. */
export interface TitleRequest {
/** The user input this run started from: its first words become the immediate fallback title. */
fallbackText: string;
/** Material override (the main session passes its input text, a subagent the prompt that spawned it — assistant material stays empty either way, so the request never waits on model output); defaults to the material self-collected by the core Session. */
material?: { userText: string; assistantText: string };
/** The channel to push the `session_title` event to; defaults to `ctx.sessionId`. A
* subagent has no SSE channel of its own, so its title must reach the frontend via
* the **parent Session's** channel (the list updates in place by sessionId). */
notifyOn?: string;
}
/** session-manager's minimal dependency on the title generator (tests inject a fake implementation). */
export interface TitleNotifier {
maybeGenerate(
ctx: UsageContext,
session: Pick<RuntimeSession, "generateTitle">,
req: TitleRequest,
): void;
}
export class TitleGenerator implements TitleNotifier {
private readonly inflight = new Set<string>();
/**
* sessionId → the fallback title this generator wrote and the LLM may still replace.
* An entry is dropped once the LLM result lands or a differing stored title (a manual
* rename, or a title from before a restart) is observed — from then on the title is
* treated as final. In-memory on purpose: the sessions table stores no auto/manual
* marker, and after a restart an existing title is simply left alone.
*/
private readonly pendingFallbacks = new Map<string, string>();
private readonly log: (line: string) => void;
constructor(private readonly deps: TitleGeneratorDeps) {
this.log = deps.log ?? ((line) => console.error(line));
}
/**
* Runs the title policy for one run start (fire-and-forget): persists the user-input
* fallback if the row has no title yet, then generates the LLM replacement in the
* background. No-ops when the stored title is anything other than NULL or the fallback
* this generator wrote (manual renames and pre-existing titles are final), or when a
* generation is already in flight.
*/
maybeGenerate(
ctx: UsageContext,
session: Pick<RuntimeSession, "generateTitle">,
req: TitleRequest,
): void {
// Bookkeeping must never take down a run: call sites sit on the run's drive path, so
// a DB failure here is logged and swallowed like every other bookkeeping write.
try {
if (!this.prepare(ctx, req)) return;
} catch (err) {
this.log(`[title] Fallback failed: ${err instanceof Error ? err.message : String(err)}`);
this.deps.errors?.record({ source: "title", err, ctx, code: "title_fallback_failed" });
return;
}
if (this.inflight.has(ctx.sessionId)) return;
this.inflight.add(ctx.sessionId);
void this.generate(ctx, session, req)
.catch((err: unknown) => {
this.log(`[title] Generation failed: ${err instanceof Error ? err.message : String(err)}`);
this.deps.errors?.record({ source: "title", err, ctx, code: "title_failed" });
})
.finally(() => {
this.inflight.delete(ctx.sessionId);
});
}
/** Synchronous half of the policy: decides whether the LLM should run, writing the immediate fallback title on the way. */
private prepare(ctx: UsageContext, req: TitleRequest): boolean {
const row = this.deps.sessions.findById(ctx.sessionId);
if (!row) return false;
if (row.title !== null) {
// Only the fallback this generator wrote is still replaceable; anything else
// (manual rename, pre-restart title) is final.
if (row.title !== this.pendingFallbacks.get(ctx.sessionId)) {
this.pendingFallbacks.delete(ctx.sessionId);
return false;
}
return true;
}
// First words of the user input, persisted before the LLM request is even issued —
// the UI shows a title the moment the task starts.
const fallback = fallbackTitle(req.fallbackText);
if (fallback !== null) {
this.pendingFallbacks.set(ctx.sessionId, fallback);
this.persist(ctx, fallback, req.notifyOn);
}
return true;
}
private async generate(
ctx: UsageContext,
session: Pick<RuntimeSession, "generateTitle">,
req: TitleRequest,
): Promise<void> {
let title: string | null = null;
try {
// The material is the run's own user input (assistant material empty); it's absent
// only for callers that rely on the core Session's self-collected material.
const res = await session.generateTitle(
req.material ? { material: req.material } : undefined,
);
title = res.title;
// The one-shot request's real consumption is metered as usual (converted to token_usage and handed to recorder, attributed to this Session).
if (res.usage) {
try {
await this.deps.recorder.record(ctx, tokenUsage(emptyTokenCounts(), res.usage));
} catch (err) {
this.log(
`[title] Usage insert failed: ${err instanceof Error ? err.message : String(err)}`,
);
this.deps.errors?.record({
source: "title",
err,
ctx,
code: "title_usage_insert_failed",
});
}
}
} catch (err) {
// A model request error (rate limit / timeout / network, etc.) leaves the fallback
// title standing; while the stored title still equals it, the next Task start retries.
this.log(`[title] Model request failed: ${err instanceof Error ? err.message : String(err)}`);
this.deps.errors?.record({ source: "title", err, ctx, code: "title_llm_failed" });
}
if (title === null) return;
// The LLM result replaces only the fallback this generator wrote (or fills a still-NULL
// title); a manual rename that landed during generation wins.
const latest = this.deps.sessions.findById(ctx.sessionId);
if (!latest) return;
if (latest.title !== null && latest.title !== this.pendingFallbacks.get(ctx.sessionId)) {
this.pendingFallbacks.delete(ctx.sessionId);
return;
}
this.pendingFallbacks.delete(ctx.sessionId);
this.persist(ctx, title, req.notifyOn);
}
/**
* Writes sessions.title and pushes the `session_title` event — to the given Session
* channel (the session's own unless overridden) for the tab watching the conversation,
* and to the Project's user-level channels for every session list. The latter is the
* delivery that survives the start-of-run timing: a first Task's title fires before the
* new Session's own channel has any subscriber.
*/
private persist(ctx: UsageContext, title: string, notifyOn: string | undefined): void {
this.deps.sessions.updateTitle(ctx.sessionId, title);
const event: ServerEvent = { type: "session_title", sessionId: ctx.sessionId, title };
this.deps.channels.get(notifyOn ?? ctx.sessionId).publish(event, "server_event");
this.deps.notifyProjectUsers?.(ctx.projectId, event);
}
}
/**
* Fallback title: take the material's first non-empty line, truncate it to the first few
* words, and sanitize; if sanitizing empties it out (pure punctuation, etc.) fall back to
* the truncated line itself; returns null if all-whitespace. Exported for the Trace
* listing's title fallback (trace-service derives a title from the first user prompt of
* Sessions the DB has no title for) so both fallbacks stay one algorithm.
*
* The cut and the sanitizing are core's (`truncateTitle` / `sanitizeTitle`), the same pair the
* LLM path runs over the model's output: this line is the user's own text, so it keeps
* anything the model output would have had stripped as prompt residue.
*/
export function fallbackTitle(text: string): string | null {
// Strip machine markers first: a skill invocation prepends a `[use_skills]` block, so the
// raw first non-empty line would otherwise be that marker rather than the user's request.
const firstLine = stripConversationMarkers(text)
.split("\n")
.find((l) => l.trim().length > 0 && !isAttachmentLine(l.trim()));
if (!firstLine) return null;
const collapsed = firstLine.replace(/\s+/g, " ").trim();
// Drop leading punctuation/quotes before truncating, so a decorated line spends the
// length budget on words (a line that is nothing but punctuation is kept as-is).
const lead = collapsed.replace(
/^["'“”‘’「」『』《》〈〉【】()()。..!!??;;,,、::\s]+/,
"",
);
const cut = truncateTitle(lead || collapsed);
// sanitizeTitle strips a pure-punctuation line down to empty — in that case keep the truncated line, guaranteeing "a title is always obtained".
return sanitizeTitle(cut) ?? cut;
}
/**
* A line that is nothing but an `[attached image: …]` / `[attached file: …]` marker. A message
* that carries attachments and no typed text is exactly this line, so a title taken from it
* would be a truncated absolute path out of the sender's home directory. Such a message gets
* no fallback at all — the LLM material still carries the path, so the model can name the
* conversation after the file, and until it answers the UI shows its untitled placeholder.
*/
function isAttachmentLine(line: string): boolean {
return matchAttachedImageLine(line) !== null || matchAttachedFileLine(line) !== null;
}