feat: auto-generate session titles via the managed chat_title tool

.changeset/agent-core-v2-session-title.md

@@ -0,0 +1,5 @@
+---
+"@moonshot-ai/agent-core-v2": minor
+---
+
+Add the Session-scoped `ISessionTitleService` for managed AI session titles: composes the excerpt sent to the platform chat_title tool from the main agent's conversation (the first user prompts, the strict `first_turn` pair, or the head+tail `digest` for multi-turn sessions; assistant segments keep only final text), persists the result with a `titleKind` (`replaceable` / `generated` / `custom`) that never overwrites a user-renamed title unless explicitly forced, and rebroadcasts `session.meta.updated`. Gated by the new experimental `auto_session_title` flag and a managed OAuth login.

.changeset/auto-session-title.md

@@ -0,0 +1,5 @@
+---
+"@moonshot-ai/kimi-code-sdk": minor
+---
+
+Add `generateSessionTitle` (v2 engine) for managed AI session titles: optional `force` regeneration over generated/custom titles and selectable conversation excerpts (`user_prompts` / `first_turn` / `digest`). Gated by the experimental `auto_session_title` flag and a managed OAuth login.

.changeset/kap-server-session-title-route.md

@@ -0,0 +1,5 @@
+---
+"@moonshot-ai/kap-server": patch
+---
+
+Add `POST /api/v1/sessions/{session_id}/title/generate` with an optional `{ "force": true, "source": "user_prompts" | "first_turn" | "digest" }` body; unknown sessions return 40401 and unavailable generation (flag off, no managed login, no prompt yet, backend failure) returns the new 40923 SESSION_TITLE_UNAVAILABLE.

.changeset/klient-session-title.md

@@ -0,0 +1,5 @@
+---
+"@moonshot-ai/klient": patch
+---
+
+Expose `session(id).generateTitle({ force, source })` on the session facade and the matching `sessionTitleService` wire contract.

.changeset/oauth-chat-title.md

@@ -0,0 +1,5 @@
+---
+"@moonshot-ai/kimi-code-oauth": patch
+---
+
+Add `fetchChatTitle` for the managed platform `/tools` `chat_title` method: protocol headers, an 8s timeout, response validation, and structured failures.

packages/agent-core-v2/docs/state-manifest.d.ts

@@ -448,7 +448,7 @@ export interface SessionStateSnapshot {
     readonly id: string;
     readonly version?: number;
     readonly title?: string;
-    readonly isCustomTitle?: boolean;
+    readonly titleKind?: 'replaceable' | 'generated' | 'custom';
     readonly lastPrompt?: string;
     readonly createdAt: number;
     readonly updatedAt: number;

packages/agent-core-v2/src/index.ts

@@ -129,6 +129,11 @@ export * from '#/session/sessionActivity/sessionActivity';
 export * from '#/session/sessionActivity/sessionActivityService';
 export * from '#/session/sessionActivity/sessionOutcomeMirror';
 export * from '#/session/sessionActivity/sessionOutcomeMirrorService';
+export * from '#/session/sessionTitle/agentTitlePromptSource';
+import '#/session/sessionTitle/agentTitlePromptSourceService';
+export * from '#/session/sessionTitle/sessionTitle';
+export * from '#/session/sessionTitle/sessionTitleService';
+import '#/session/sessionTitle/flag';
 export * from '#/session/sessionToolPolicy/sessionToolPolicy';
 export * from '#/session/sessionToolPolicy/sessionToolPolicyService';
 export * from '#/app/config/config';

packages/agent-core-v2/src/session/sessionMetadata/promptMetadata.ts

@@ -14,7 +14,7 @@ import type { IEventService } from '#/app/event/event';
 
 import { titleFromPromptMetadataText } from '#/agent/prompt/promptMetadataText';
 
-import type { ISessionMetadata } from './sessionMetadata';
+import type { ISessionMetadata, SessionTitleKind } from './sessionMetadata';
 
 export function isUntitled(title: string | undefined): boolean {
   return title === undefined || title.trim().length === 0 || title === 'New Session';
@@ -32,12 +32,12 @@ export async function applyPromptMetadataUpdate(
 ): Promise<void> {
   if (text === undefined) return;
   const current = await target.metadata.read();
-  const patch: { lastPrompt: string; title?: string; isCustomTitle?: boolean } = {
+  const patch: { lastPrompt: string; title?: string; titleKind?: SessionTitleKind } = {
     lastPrompt: text,
   };
-  if (!current.isCustomTitle && isUntitled(current.title)) {
+  if (current.titleKind !== 'custom' && isUntitled(current.title)) {
     patch.title = titleFromPromptMetadataText(text);
-    patch.isCustomTitle = false;
+    patch.titleKind = 'replaceable';
   }
   await target.metadata.update(patch);
   target.eventService.publish({
@@ -48,7 +48,7 @@ export async function applyPromptMetadataUpdate(
       title: patch.title,
       patch: {
         title: patch.title,
-        isCustomTitle: patch.isCustomTitle,
+        isCustomTitle: patch.titleKind === undefined ? undefined : false,
         lastPrompt: text,
       },
     },

packages/agent-core-v2/src/session/sessionMetadata/sessionMetadata.ts

@@ -25,11 +25,13 @@ export interface AgentMeta {
 
 export const SESSION_META_VERSION = 2;
 
+export type SessionTitleKind = 'replaceable' | 'generated' | 'custom';
+
 export interface SessionMeta {
   readonly id: string;
   readonly version?: number;
   readonly title?: string;
-  readonly isCustomTitle?: boolean;
+  readonly titleKind?: SessionTitleKind;
   readonly lastPrompt?: string;
   readonly createdAt: number;
   readonly updatedAt: number;
@@ -56,6 +58,17 @@ export interface ISessionMetadata {
   read(): Promise<SessionMeta>;
   update(patch: SessionMetaPatch, opts?: { readonly touchUpdatedAt?: boolean }): Promise<void>;
   setTitle(title: string): Promise<void>;
+  /**
+   * Applies a generated title unless the user customized theirs; the title
+   * kind is re-checked inside the serialized update, right before the write,
+   * so a custom title set while a generation was in flight still wins.
+   * `force` skips the kind check entirely (explicit user-requested
+   * regeneration — last writer wins).
+   */
+  setGeneratedTitleIfUncustomized(
+    title: string,
+    opts?: { force?: boolean },
+  ): Promise<boolean>;
   setArchived(archived: boolean): Promise<void>;
   registerAgent(agentId: string, meta: AgentMeta): Promise<void>;
 }

packages/agent-core-v2/src/session/sessionMetadata/sessionMetadataService.ts

@@ -11,13 +11,23 @@
  * backfilled and persisted on load for documents written before the seeding
  * existed (without touching `updatedAt`, so a format heal never reorders
  * session listings). `updatedAt` tracks content activity only: management
- * writes (rename via `setTitle`, archive/restore via `setArchived`) keep the
- * persisted value through `touchUpdatedAt: false`, an explicit
- * `patch.updatedAt` always wins (fork restores the source's recency), and
- * agent registration is a structural write that never touches it — neither
- * when resume materializes a cold session's agents, nor when a runtime
- * subagent registers mid-turn (the turn's own submit/end moments carry
- * recency). Bound at Session scope.
+ * writes (rename via `setTitle`, archive/restore via `setArchived`, the
+ * generated-title write-back) keep the persisted value through
+ * `touchUpdatedAt: false`, an explicit `patch.updatedAt` always wins (fork
+ * restores the source's recency), and agent registration is a structural
+ * write that never touches it — neither when resume materializes a cold
+ * session's agents, nor when a runtime subagent registers mid-turn (the
+ * turn's own submit/end moments carry recency). The canonical title state
+ * is `titleKind`; every persist additionally double-writes the v1-readable
+ * `isCustomTitle` marker derived from it, and on load an explicit
+ * `isCustomTitle: true` outranks a stale `titleKind` (a v1 rename spreads
+ * the original document, so the two can disagree) while a `false` marker
+ * never downgrades a modern generated/custom state. The generated-title
+ * write path (`setGeneratedTitleIfUncustomized`) serializes through the same
+ * update queue as everything else and re-checks the title kind inside the
+ * queued write, so a custom title set while a generation was in flight is
+ * never overwritten — unless the caller passes `force` (explicit
+ * regeneration, last writer wins). Bound at Session scope.
  *
  * Read-model mirroring (flag `persistence_minidb_readmodel`): after a metadata
  * update is persisted, the fresh summary is recorded into the App-scoped
@@ -55,6 +65,7 @@ import {
   type SessionMeta,
   type SessionMetadataChangedEvent,
   type SessionMetaPatch,
+  type SessionTitleKind,
 } from './sessionMetadata';
 
 const META_KEY = 'state.json';
@@ -119,28 +130,42 @@ export class SessionMetadata extends Service implements ISessionMetadata {
     patch: SessionMetaPatch,
     opts?: { readonly touchUpdatedAt?: boolean },
   ): Promise<void> {
-    return this.enqueueUpdate(() => this.applyUpdate(patch, opts));
+    return this.enqueueUpdate(async () => {
+      await this.applyUpdate(patch, opts);
+    });
   }
 
   private async applyUpdate(
     patch: SessionMetaPatch,
     opts?: { readonly touchUpdatedAt?: boolean },
-  ): Promise<void> {
+  ): Promise<boolean> {
     await this.ready;
-    if (this.disposed) return;
+    if (this.disposed) return false;
     const updatedAt =
       patch.updatedAt ?? (opts?.touchUpdatedAt === false ? this.data.updatedAt : Date.now());
     this.data = { ...this.data, ...patch, updatedAt };
-    await this.store.set(this.scope, META_KEY, this.data);
-    if (this.disposed) return;
+    await this.store.set(this.scope, META_KEY, encodeSessionMeta(this.data));
+    if (this.disposed) return false;
     this.mirrorToReadModel();
     this._onDidChangeMetadata.fire({
       changed: Object.keys(patch) as (keyof SessionMeta)[],
     });
+    return true;
   }
 
   async setTitle(title: string): Promise<void> {
-    await this.update({ title, isCustomTitle: true }, { touchUpdatedAt: false });
+    await this.update({ title, titleKind: 'custom' }, { touchUpdatedAt: false });
+  }
+
+  async setGeneratedTitleIfUncustomized(
+    title: string,
+    opts?: { force?: boolean },
+  ): Promise<boolean> {
+    return this.enqueueUpdate(async () => {
+      await this.ready;
+      if (opts?.force !== true && this.data.titleKind === 'custom') return false;
+      return this.applyUpdate({ title, titleKind: 'generated' }, { touchUpdatedAt: false });
+    });
   }
 
   async setArchived(archived: boolean): Promise<void> {
@@ -160,9 +185,12 @@ export class SessionMetadata extends Service implements ISessionMetadata {
     });
   }
 
-  private enqueueUpdate(work: () => Promise<void>): Promise<void> {
+  private enqueueUpdate<T>(work: () => Promise<T>): Promise<T> {
     const run = this.updateQueue.then(work, work);
-    const tracked = run.catch(() => {});
+    const tracked: Promise<void> = run.then(
+      () => undefined,
+      () => undefined,
+    );
     this.updateQueue = tracked;
     pendingWrites.add(tracked);
     void tracked.finally(() => pendingWrites.delete(tracked));
@@ -201,13 +229,17 @@ export class SessionMetadata extends Service implements ISessionMetadata {
     const existing = await this.store.get<SessionMeta>(this.scope, META_KEY);
     if (existing !== undefined) {
       this.data = normalizeSessionMeta(existing, this.ctx.sessionId);
-      if (this.data.agents === undefined || this.data.custom === undefined) {
+      if (
+        this.data.agents === undefined ||
+        this.data.custom === undefined ||
+        sessionMetaTitleNeedsMigration(existing, this.data)
+      ) {
         this.data = {
           ...this.data,
           agents: this.data.agents ?? {},
           custom: this.data.custom ?? {},
         };
-        await this.store.set(this.scope, META_KEY, this.data);
+        await this.store.set(this.scope, META_KEY, encodeSessionMeta(this.data));
       }
       return;
     }
@@ -222,7 +254,7 @@ export class SessionMetadata extends Service implements ISessionMetadata {
       agents: {},
       custom: {},
     };
-    await this.store.set(this.scope, META_KEY, this.data);
+    await this.store.set(this.scope, META_KEY, encodeSessionMeta(this.data));
     this.mirrorToReadModel();
     this.log.debug('session metadata created', { sessionId: this.ctx.sessionId });
   }
@@ -248,28 +280,83 @@ function recordEquals(a: AgentMeta['labels'], b: AgentMeta['labels']): boolean {
 }
 
 export function normalizeSessionMeta(raw: SessionMeta, sessionId: string): SessionMeta {
-  const legacy = raw as unknown as {
-    createdAt?: unknown;
-    updatedAt?: unknown;
-    workDir?: unknown;
-  };
+  const legacy = raw as unknown as LegacySessionMeta;
+  const normalizedTitle = normalizeSessionTitle(legacy);
+  const {
+    createdAt: legacyCreatedAt,
+    updatedAt: legacyUpdatedAt,
+    workDir: legacyWorkDir,
+    titleSource: _legacyTitleSource,
+    isCustomTitle: _legacyIsCustomTitle,
+    customTitle: _legacyCustomTitle,
+    ...clean
+  } = legacy;
   const cwd =
-    raw.cwd ?? (typeof legacy.workDir === 'string' && legacy.workDir.length > 0
-      ? legacy.workDir
+    clean.cwd ?? (typeof legacyWorkDir === 'string' && legacyWorkDir.length > 0
+      ? legacyWorkDir
       : undefined);
-  if (raw.version === SESSION_META_VERSION) {
-    return cwd === raw.cwd ? raw : { ...raw, cwd };
-  }
+  const { title, titleKind } = normalizedTitle;
   return {
-    ...raw,
-    id: sessionId,
+    ...clean,
+    id: clean.version === SESSION_META_VERSION ? clean.id : sessionId,
     version: SESSION_META_VERSION,
     cwd,
-    createdAt: toEpochMs(legacy.createdAt),
-    updatedAt: toEpochMs(legacy.updatedAt),
+    title,
+    titleKind,
+    createdAt: toEpochMs(legacyCreatedAt),
+    updatedAt: toEpochMs(legacyUpdatedAt),
   };
 }
 
+type LegacySessionMeta = Omit<SessionMeta, 'createdAt' | 'updatedAt'> & {
+  readonly createdAt?: unknown;
+  readonly updatedAt?: unknown;
+  readonly workDir?: unknown;
+  readonly titleSource?: unknown;
+  readonly isCustomTitle?: unknown;
+  readonly customTitle?: unknown;
+};
+
+function normalizeSessionTitle(
+  raw: LegacySessionMeta,
+): Pick<SessionMeta, 'title' | 'titleKind'> {
+  const title = typeof raw.title === 'string' ? raw.title : undefined;
+  if (title !== undefined && raw.isCustomTitle === true) {
+    return { title, titleKind: 'custom' };
+  }
+  if (title !== undefined && isSessionTitleKind(raw.titleKind)) {
+    return { title, titleKind: raw.titleKind };
+  }
+  if (title !== undefined && raw.isCustomTitle === false) {
+    return { title, titleKind: 'replaceable' };
+  }
+  if (typeof raw.customTitle === 'string') {
+    return { title: raw.customTitle, titleKind: 'custom' };
+  }
+  return title === undefined ? {} : { title, titleKind: 'replaceable' };
+}
+
+function isSessionTitleKind(value: unknown): value is SessionTitleKind {
+  return value === 'replaceable' || value === 'generated' || value === 'custom';
+}
+
+type PersistedSessionMeta = SessionMeta & { readonly isCustomTitle: boolean };
+
+function encodeSessionMeta(meta: SessionMeta): PersistedSessionMeta {
+  return { ...meta, isCustomTitle: meta.titleKind === 'custom' };
+}
+
+function sessionMetaTitleNeedsMigration(raw: SessionMeta, normalized: SessionMeta): boolean {
+  const record = raw as unknown as Record<string, unknown>;
+  return (
+    raw.title !== normalized.title ||
+    raw.titleKind !== normalized.titleKind ||
+    record['isCustomTitle'] !== (normalized.titleKind === 'custom') ||
+    Object.hasOwn(record, 'titleSource') ||
+    Object.hasOwn(record, 'customTitle')
+  );
+}
+
 export function toEpochMs(value: unknown): number {
   if (typeof value === 'number' && Number.isFinite(value)) return value;
   if (typeof value === 'string') {

packages/agent-core-v2/src/session/sessionTitle/agentTitlePromptSource.ts

@@ -0,0 +1,44 @@
+/**
+ * `sessionTitle` domain (L6) — title prompt projection contract.
+ *
+ * Defines the Agent-scoped `IAgentTitlePromptSource` used to read the first
+ * active natural-language prompts from the live conversation context, plus
+ * the turn excerpts behind the `first_turn` / `digest` title sources.
+ */
+
+import { createDecorator, type ServiceIdentifier } from '#/_base/di/instantiation';
+
+/**
+ * The first turn's excerpt: the opening natural-language user prompt and the
+ * final assistant text of that turn. Either side is `undefined` when the
+ * live window does not (yet) hold it — `first_turn` generation stays strict
+ * and reports unavailability instead of degrading.
+ */
+export interface TitleTurnExcerpt {
+  readonly user?: string | undefined;
+  readonly assistant?: string | undefined;
+}
+
+/**
+ * The whole-conversation digest excerpt: the first and last natural-language
+ * user prompts (collapsed into one when the conversation has a single
+ * prompt) and the final assistant text of the latest turn.
+ */
+export interface TitleDigestExcerpt {
+  readonly firstUser?: string | undefined;
+  readonly lastUser?: string | undefined;
+  readonly assistant?: string | undefined;
+}
+
+export interface IAgentTitlePromptSource {
+  readonly _serviceBrand: undefined;
+
+  firstUserPrompts(limit: number): Promise<readonly string[]>;
+
+  firstTurnExcerpt(): Promise<TitleTurnExcerpt>;
+
+  digestExcerpt(): Promise<TitleDigestExcerpt>;
+}
+
+export const IAgentTitlePromptSource: ServiceIdentifier<IAgentTitlePromptSource> =
+  createDecorator<IAgentTitlePromptSource>('agentTitlePromptSource');