feat(agent-core-v2): persist the last turn outcome into session metadata for cold listings

.changeset/cold-session-last-turn-outcome.md

@@ -0,0 +1,5 @@
+---
+"@moonshot-ai/kimi-code": patch
+---
+
+Session listings keep how the last turn ended (completed, cancelled, or failed) across server restarts, so clients can mark previously failed sessions before they are opened.

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

@@ -465,6 +465,7 @@ export interface SessionStateSnapshot {
       readonly swarmItem?: string;
     }>>;
     readonly custom?: Record<string, unknown>;
+    readonly lastTurnOutcome?: 'completed' | 'cancelled' | 'failed';
   } | undefined;
   // src/session/sessionSkillCatalog/skillCatalogService.ts
   'sessionSkillCatalog.contributions': Map<string, {

packages/agent-core-v2/src/app/sessionIndex/sessionIndex.ts

@@ -50,6 +50,7 @@ export interface SessionSummary {
   readonly updatedAt: number;
   readonly archived: boolean;
   readonly custom?: Record<string, unknown>;
+  readonly lastTurnReason?: 'completed' | 'cancelled' | 'failed';
 }
 
 export interface SessionListQuery {

packages/agent-core-v2/src/app/sessionIndex/sessionIndexSource.ts

@@ -37,6 +37,10 @@ export function parseTime(value: unknown): number {
   return 0;
 }
 
+export function parseTurnOutcome(value: unknown): 'completed' | 'cancelled' | 'failed' | undefined {
+  return value === 'completed' || value === 'cancelled' || value === 'failed' ? value : undefined;
+}
+
 export function recoverCwd(meta: Record<string, unknown>): string | undefined {
   if (typeof meta['cwd'] === 'string' && meta['cwd'].length > 0) return meta['cwd'];
   if (typeof meta['workDir'] === 'string' && meta['workDir'].length > 0) {
@@ -63,6 +67,7 @@ export function buildSessionSummary(fields: {
   updatedAt: number;
   archived: boolean;
   custom?: Record<string, unknown>;
+  lastTurnReason?: 'completed' | 'cancelled' | 'failed';
 }): SessionSummary {
   return {
     id: fields.id,
@@ -74,6 +79,7 @@ export function buildSessionSummary(fields: {
     updatedAt: fields.updatedAt,
     archived: fields.archived,
     custom: fields.custom,
+    lastTurnReason: fields.lastTurnReason,
   };
 }
 
@@ -102,6 +108,7 @@ export function summaryEquals(a: SessionSummary, b: SessionSummary): boolean {
     a.createdAt === b.createdAt &&
     a.updatedAt === b.updatedAt &&
     a.archived === b.archived &&
+    a.lastTurnReason === b.lastTurnReason &&
     JSON.stringify(a.custom) === JSON.stringify(b.custom)
   );
 }
@@ -153,6 +160,7 @@ export async function readSessionSummary(
     updatedAt: parseTime(meta['updatedAt']),
     archived: meta['archived'] === true,
     custom,
+    lastTurnReason: parseTurnOutcome(meta['lastTurnOutcome']),
   });
 }
 

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

@@ -98,6 +98,8 @@ export * from '#/session/sessionMetadata/sessionMetadata';
 export * from '#/session/sessionMetadata/sessionMetadataService';
 export * from '#/session/sessionActivity/sessionActivity';
 export * from '#/session/sessionActivity/sessionActivityService';
+export * from '#/session/sessionActivity/sessionOutcomeRecorder';
+export * from '#/session/sessionActivity/sessionOutcomeRecorderService';
 export * from '#/session/sessionToolPolicy/sessionToolPolicy';
 export * from '#/session/sessionToolPolicy/sessionToolPolicyService';
 export * from '#/app/config/config';

packages/agent-core-v2/src/session/sessionActivity/sessionOutcomeRecorder.ts

@@ -0,0 +1,19 @@
+/**
+ * `sessionActivity` domain — `ISessionOutcomeRecorder` contract: persist the
+ * latest main-turn outcome into durable session metadata.
+ *
+ * The activity aggregate's `lastTurnReason` is live fold state, rebuilt per
+ * process; this recorder is the write side that lands terminal outcomes in
+ * the session's metadata document, so the session index (and therefore cold
+ * listings after a restart) keep reporting them. Session-scoped — one
+ * instance per session.
+ */
+
+import { createDecorator, type ServiceIdentifier } from '#/_base/di/instantiation';
+
+export interface ISessionOutcomeRecorder {
+  readonly _serviceBrand: undefined;
+}
+
+export const ISessionOutcomeRecorder: ServiceIdentifier<ISessionOutcomeRecorder> =
+  createDecorator<ISessionOutcomeRecorder>('sessionOutcomeRecorder');

packages/agent-core-v2/src/session/sessionActivity/sessionOutcomeRecorderService.ts

@@ -0,0 +1,83 @@
+/**
+ * `sessionActivity` domain — `ISessionOutcomeRecorder` implementation.
+ *
+ * Persists the main agent's terminal turn outcomes through `ISessionMetadata`
+ * (observed via `agentLifecycle` and the main agent's `eventBus`), so the
+ * session index keeps reporting them across restarts. Programmatic aborts —
+ * including scope-teardown cancels — are deliberately not persisted. Bound at
+ * Session scope.
+ */
+
+import { Disposable, type IDisposable } from '#/_base/di/lifecycle';
+import { LifecycleScope, ScopeActivation, registerScopedService } from '#/_base/di/scope';
+import { IEventBus } from '#/app/event/eventBus';
+import {
+  IAgentLifecycleService,
+  MAIN_AGENT_ID,
+} from '#/session/agentLifecycle/agentLifecycle';
+import { ISessionMetadata } from '#/session/sessionMetadata/sessionMetadata';
+
+import type { SessionTurnOutcome } from './sessionActivity';
+import { ISessionOutcomeRecorder } from './sessionOutcomeRecorder';
+
+export class SessionOutcomeRecorder extends Disposable implements ISessionOutcomeRecorder {
+  declare readonly _serviceBrand: undefined;
+
+  private lastPersisted: SessionTurnOutcome | undefined;
+  private mainSubscription: IDisposable | undefined;
+
+  constructor(
+    @IAgentLifecycleService private readonly agents: IAgentLifecycleService,
+    @ISessionMetadata private readonly metadata: ISessionMetadata,
+  ) {
+    super();
+    this.attachMain();
+    this._register(this.agents.onDidCreate((handle) => {
+      if (handle.id === MAIN_AGENT_ID) this.attachMain();
+    }));
+    this._register({
+      dispose: () => {
+        this.mainSubscription?.dispose();
+        this.mainSubscription = undefined;
+      },
+    });
+  }
+
+  private attachMain(): void {
+    if (this.mainSubscription !== undefined) return;
+    const bus = this.agents.get(MAIN_AGENT_ID)?.accessor.get(IEventBus) as IEventBus | undefined;
+    if (bus === undefined) return;
+    this.mainSubscription = bus.subscribe('turn.ended', (event) => {
+      if (event.type !== 'turn.ended') return;
+      const reason = (event as { reason?: unknown }).reason;
+      const interruptReason = (event as { interruptReason?: unknown }).interruptReason;
+      if (reason === 'completed') {
+        this.persist('completed');
+        return;
+      }
+      if (reason === 'failed' || reason === 'blocked') {
+        this.persist('failed');
+        return;
+      }
+      if (reason === 'cancelled' && interruptReason === 'user_cancelled') {
+        this.persist('cancelled');
+      }
+    });
+  }
+
+  private persist(outcome: SessionTurnOutcome): void {
+    if (outcome === this.lastPersisted) return;
+    this.lastPersisted = outcome;
+    void this.metadata
+      .update({ lastTurnOutcome: outcome })
+      .catch(() => {});
+  }
+}
+
+registerScopedService(
+  LifecycleScope.Session,
+  ISessionOutcomeRecorder,
+  SessionOutcomeRecorder,
+  ScopeActivation.OnScopeCreated,
+  'sessionActivity',
+);

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

@@ -3,7 +3,8 @@
  *
  * Defines the `SessionMeta` model and the `ISessionMetadata` used by upper
  * layers to read and update the session's durable metadata (title, timestamps,
- * archived flag, fork provenance). Owns the in-memory copy, persists it as a
+ * archived flag, fork provenance, the latest main turn's terminal outcome).
+ * Owns the in-memory copy, persists it as a
  * single atomic document through `storage`, and notifies changes via
  * `onDidChangeMetadata`. Session-scoped — one instance per session. The initial
  * document is materialized when the session is created.
@@ -36,6 +37,7 @@ export interface SessionMeta {
   readonly forkedFrom?: string;
   readonly agents?: Readonly<Record<string, AgentMeta>>;
   readonly custom?: Record<string, unknown>;
+  readonly lastTurnOutcome?: 'completed' | 'cancelled' | 'failed';
 }
 
 export type SessionMetaPatch = Partial<Omit<SessionMeta, 'id' | 'createdAt'>>;

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

@@ -141,6 +141,7 @@ export class SessionMetadata extends Disposable implements ISessionMetadata {
         updatedAt: this.data.updatedAt,
         archived: this.data.archived === true,
         custom: this.data.custom,
+        lastTurnReason: this.data.lastTurnOutcome,
       }),
     );
   }

packages/agent-core-v2/test/session/sessionActivity/sessionOutcomeRecorder.test.ts

@@ -0,0 +1,101 @@
+import { describe, expect, it } from 'vitest';
+
+import { Emitter } from '#/_base/event';
+import type { DomainEvent } from '#/app/event/eventBus';
+import { IEventBus } from '#/app/event/eventBus';
+import type { IAgentScopeHandle } from '#/_base/di/scope';
+import type { SessionMeta } from '#/session/sessionMetadata/sessionMetadata';
+import { ISessionMetadata } from '#/session/sessionMetadata/sessionMetadata';
+import {
+  IAgentLifecycleService,
+  MAIN_AGENT_ID,
+} from '#/session/agentLifecycle/agentLifecycle';
+import { SessionOutcomeRecorder } from '#/session/sessionActivity/sessionOutcomeRecorderService';
+
+class FakeBus {
+  private readonly handlers = new Map<string, Array<(e: DomainEvent) => void>>();
+
+  publish(event: DomainEvent): void {
+    for (const h of this.handlers.get(event.type) ?? []) h(event);
+  }
+
+  subscribe(type: unknown, handler?: unknown) {
+    const list = this.handlers.get(type as string) ?? [];
+    const fn = handler as (e: DomainEvent) => void;
+    list.push(fn);
+    this.handlers.set(type as string, list);
+    return { dispose: () => this.handlers.set(type as string, list.filter((h) => h !== fn)) };
+  }
+}
+
+describe('SessionOutcomeRecorder', () => {
+  function harness(opts?: { withMain?: boolean }) {
+    const withMain = opts?.withMain ?? true;
+    const bus = new FakeBus();
+    const mainHandle = {
+      id: MAIN_AGENT_ID,
+      accessor: { get: (token: unknown) => (token === IEventBus ? bus : undefined) },
+    } as unknown as IAgentScopeHandle;
+    const onDidCreate = new Emitter<IAgentScopeHandle>();
+    let mainPresent = withMain;
+    const agents = {
+      get: (id: string) => (id === MAIN_AGENT_ID && mainPresent ? mainHandle : undefined),
+      onDidCreate: onDidCreate.event,
+    } as unknown as IAgentLifecycleService;
+    const writes: SessionMeta['lastTurnOutcome'][] = [];
+    const metadata = {
+      update: async (patch: { lastTurnOutcome?: SessionMeta['lastTurnOutcome'] }) => {
+        writes.push(patch.lastTurnOutcome);
+      },
+    } as unknown as ISessionMetadata;
+    const recorder = new SessionOutcomeRecorder(agents, metadata);
+    return {
+      writes,
+      ended: (reason: string, interruptReason?: string) =>
+        bus.publish({ type: 'turn.ended', reason, interruptReason } as unknown as DomainEvent),
+      arriveMain: () => {
+        mainPresent = true;
+        onDidCreate.fire(mainHandle);
+      },
+      dispose: () => {
+        recorder.dispose();
+      },
+    };
+  }
+
+  it('persists completed and failed outcomes from the main agent', () => {
+    const { writes, ended, dispose } = harness();
+    ended('completed');
+    ended('failed');
+    ended('blocked'); // folds to 'failed', which the dedup then collapses
+    expect(writes).toEqual(['completed', 'failed']);
+    dispose();
+  });
+
+  it('persists a user stop but never a programmatic abort', () => {
+    const { writes, ended, dispose } = harness();
+    ended('cancelled', 'user_cancelled');
+    ended('cancelled', 'aborted');
+    ended('cancelled', undefined);
+    expect(writes).toEqual(['cancelled']);
+    dispose();
+  });
+
+  it('dedupes repeated outcomes within the process', () => {
+    const { writes, ended, dispose } = harness();
+    ended('failed');
+    ended('failed');
+    expect(writes).toEqual(['failed']);
+    dispose();
+  });
+
+  it('subscribes when the main agent appears after construction', () => {
+    const { writes, ended, arriveMain, dispose } = harness({ withMain: false });
+    ended('failed');
+    expect(writes).toEqual([]);
+    arriveMain();
+    ended('failed');
+    expect(writes).toEqual(['failed']);
+    dispose();
+  });
+});

packages/kap-server/src/routes/sessions.ts

@@ -1109,6 +1109,7 @@ export interface SessionWireFields {
   readonly updatedAt: number;
   readonly archived: boolean;
   readonly custom?: Record<string, unknown>;
+  readonly lastTurnReason?: 'completed' | 'cancelled' | 'failed';
 }
 
 export function toWireSession(
@@ -1125,7 +1126,11 @@ export function toWireSession(
     busy: facts.busy,
     main_turn_active: facts.mainTurnActive,
     pending_interaction: facts.pendingInteraction,
-    last_turn_reason: facts.lastTurnReason,
+    // Live facts win for warm sessions; only a cold session (no live handle)
+    // falls back to the persisted outcome — a warm session mid-turn must not
+    // report a stale earlier outcome.
+    last_turn_reason:
+      facts.lastTurnReason ?? (facts.live === false ? fields.lastTurnReason : undefined),
     archived: fields.archived,
     last_prompt: fields.lastPrompt,
     metadata: buildWireMetadata(fields.custom, cwd),
@@ -1143,6 +1148,9 @@ export interface SessionFacts {
   readonly mainTurnActive: boolean;
   readonly pendingInteraction: SessionPendingInteraction;
   readonly lastTurnReason?: 'completed' | 'cancelled' | 'failed';
+  /** False when no live handle exists (cold session); live warm sessions
+   *  always report their own outcome, never the persisted fallback. */
+  readonly live?: boolean;
 }
 
 /**
@@ -1159,9 +1167,10 @@ export function resolveSessionFacts(core: Scope, sessionId: string): SessionFact
       busy: false,
       mainTurnActive: false,
       pendingInteraction: 'none',
+      live: false,
     };
   }
-  return handle.accessor.get(ISessionActivityView).state();
+  return { ...handle.accessor.get(ISessionActivityView).state(), live: true };
 }
 
 /**