feat(session): add session recap card

Generate a read-only LLM summary of a session and surface it in the TUI as
a recap card on open, after idle, or on demand via /recap.

Recap builds its transcript from the legacy V1 message/part tables where
sessions actually persist their history, falling back to the V2 projected
message store, so summaries reflect real conversations instead of always
reporting no context. Model resolution falls back to the default model when
the session's own model is unavailable, keeping recap best-effort so it
never blocks the run. Adds the /api/session/:sessionID/recap endpoint across
protocol, server, core execution/runner, and the generated SDK/client.

Author: Integralist

packages/client/src/generated-effect/client.ts

@@ -128,18 +128,26 @@ type Endpoint3_7Input = { readonly sessionID: Endpoint3_7Request["params"]["sess
 const Endpoint3_7 = (raw: RawClient["server.session"]) => (input: Endpoint3_7Input) =>
   raw["session.compact"]({ params: { sessionID: input["sessionID"] } }).pipe(Effect.mapError(mapClientError))
 
-type Endpoint3_8Request = Parameters<RawClient["server.session"]["session.wait"]>[0]
+type Endpoint3_8Request = Parameters<RawClient["server.session"]["session.recap"]>[0]
 type Endpoint3_8Input = { readonly sessionID: Endpoint3_8Request["params"]["sessionID"] }
 const Endpoint3_8 = (raw: RawClient["server.session"]) => (input: Endpoint3_8Input) =>
+  raw["session.recap"]({ params: { sessionID: input["sessionID"] } }).pipe(
+    Effect.mapError(mapClientError),
+    Effect.map((value) => value.data),
+  )
+
+type Endpoint3_9Request = Parameters<RawClient["server.session"]["session.wait"]>[0]
+type Endpoint3_9Input = { readonly sessionID: Endpoint3_9Request["params"]["sessionID"] }
+const Endpoint3_9 = (raw: RawClient["server.session"]) => (input: Endpoint3_9Input) =>
   raw["session.wait"]({ params: { sessionID: input["sessionID"] } }).pipe(Effect.mapError(mapClientError))
 
-type Endpoint3_9Request = Parameters<RawClient["server.session"]["session.revert.stage"]>[0]
-type Endpoint3_9Input = {
-  readonly sessionID: Endpoint3_9Request["params"]["sessionID"]
-  readonly messageID: Endpoint3_9Request["payload"]["messageID"]
-  readonly files?: Endpoint3_9Request["payload"]["files"]
+type Endpoint3_10Request = Parameters<RawClient["server.session"]["session.revert.stage"]>[0]
+type Endpoint3_10Input = {
+  readonly sessionID: Endpoint3_10Request["params"]["sessionID"]
+  readonly messageID: Endpoint3_10Request["payload"]["messageID"]
+  readonly files?: Endpoint3_10Request["payload"]["files"]
 }
-const Endpoint3_9 = (raw: RawClient["server.session"]) => (input: Endpoint3_9Input) =>
+const Endpoint3_10 = (raw: RawClient["server.session"]) => (input: Endpoint3_10Input) =>
   raw["session.revert.stage"]({
     params: { sessionID: input["sessionID"] },
     payload: { messageID: input["messageID"], files: input["files"] },
@@ -148,60 +156,60 @@ const Endpoint3_9 = (raw: RawClient["server.session"]) => (input: Endpoint3_9Inp
     Effect.map((value) => value.data),
   )
 
-type Endpoint3_10Request = Parameters<RawClient["server.session"]["session.revert.clear"]>[0]
-type Endpoint3_10Input = { readonly sessionID: Endpoint3_10Request["params"]["sessionID"] }
-const Endpoint3_10 = (raw: RawClient["server.session"]) => (input: Endpoint3_10Input) =>
-  raw["session.revert.clear"]({ params: { sessionID: input["sessionID"] } }).pipe(Effect.mapError(mapClientError))
-
-type Endpoint3_11Request = Parameters<RawClient["server.session"]["session.revert.commit"]>[0]
+type Endpoint3_11Request = Parameters<RawClient["server.session"]["session.revert.clear"]>[0]
 type Endpoint3_11Input = { readonly sessionID: Endpoint3_11Request["params"]["sessionID"] }
 const Endpoint3_11 = (raw: RawClient["server.session"]) => (input: Endpoint3_11Input) =>
-  raw["session.revert.commit"]({ params: { sessionID: input["sessionID"] } }).pipe(Effect.mapError(mapClientError))
+  raw["session.revert.clear"]({ params: { sessionID: input["sessionID"] } }).pipe(Effect.mapError(mapClientError))
 
-type Endpoint3_12Request = Parameters<RawClient["server.session"]["session.context"]>[0]
+type Endpoint3_12Request = Parameters<RawClient["server.session"]["session.revert.commit"]>[0]
 type Endpoint3_12Input = { readonly sessionID: Endpoint3_12Request["params"]["sessionID"] }
 const Endpoint3_12 = (raw: RawClient["server.session"]) => (input: Endpoint3_12Input) =>
+  raw["session.revert.commit"]({ params: { sessionID: input["sessionID"] } }).pipe(Effect.mapError(mapClientError))
+
+type Endpoint3_13Request = Parameters<RawClient["server.session"]["session.context"]>[0]
+type Endpoint3_13Input = { readonly sessionID: Endpoint3_13Request["params"]["sessionID"] }
+const Endpoint3_13 = (raw: RawClient["server.session"]) => (input: Endpoint3_13Input) =>
   raw["session.context"]({ params: { sessionID: input["sessionID"] } }).pipe(
     Effect.mapError(mapClientError),
     Effect.map((value) => value.data),
   )
 
-type Endpoint3_13Request = Parameters<RawClient["server.session"]["session.history"]>[0]
-type Endpoint3_13Input = {
-  readonly sessionID: Endpoint3_13Request["params"]["sessionID"]
-  readonly limit?: Endpoint3_13Request["query"]["limit"]
-  readonly after?: Endpoint3_13Request["query"]["after"]
+type Endpoint3_14Request = Parameters<RawClient["server.session"]["session.history"]>[0]
+type Endpoint3_14Input = {
+  readonly sessionID: Endpoint3_14Request["params"]["sessionID"]
+  readonly limit?: Endpoint3_14Request["query"]["limit"]
+  readonly after?: Endpoint3_14Request["query"]["after"]
 }
-const Endpoint3_13 = (raw: RawClient["server.session"]) => (input: Endpoint3_13Input) =>
+const Endpoint3_14 = (raw: RawClient["server.session"]) => (input: Endpoint3_14Input) =>
   raw["session.history"]({
     params: { sessionID: input["sessionID"] },
     query: { limit: input["limit"], after: input["after"] },
   }).pipe(Effect.mapError(mapClientError))
 
-type Endpoint3_14Request = Parameters<RawClient["server.session"]["session.events"]>[0]
-type Endpoint3_14Input = {
-  readonly sessionID: Endpoint3_14Request["params"]["sessionID"]
-  readonly after?: Endpoint3_14Request["query"]["after"]
+type Endpoint3_15Request = Parameters<RawClient["server.session"]["session.events"]>[0]
+type Endpoint3_15Input = {
+  readonly sessionID: Endpoint3_15Request["params"]["sessionID"]
+  readonly after?: Endpoint3_15Request["query"]["after"]
 }
-const Endpoint3_14 = (raw: RawClient["server.session"]) => (input: Endpoint3_14Input) =>
+const Endpoint3_15 = (raw: RawClient["server.session"]) => (input: Endpoint3_15Input) =>
   Stream.unwrap(
     raw["session.events"]({ params: { sessionID: input["sessionID"] }, query: { after: input["after"] } }).pipe(
       Effect.mapError(mapClientError),
       Effect.map((stream) => stream.pipe(Stream.mapError(mapClientError))),
     ),
   )
 
-type Endpoint3_15Request = Parameters<RawClient["server.session"]["session.interrupt"]>[0]
-type Endpoint3_15Input = { readonly sessionID: Endpoint3_15Request["params"]["sessionID"] }
-const Endpoint3_15 = (raw: RawClient["server.session"]) => (input: Endpoint3_15Input) =>
+type Endpoint3_16Request = Parameters<RawClient["server.session"]["session.interrupt"]>[0]
+type Endpoint3_16Input = { readonly sessionID: Endpoint3_16Request["params"]["sessionID"] }
+const Endpoint3_16 = (raw: RawClient["server.session"]) => (input: Endpoint3_16Input) =>
   raw["session.interrupt"]({ params: { sessionID: input["sessionID"] } }).pipe(Effect.mapError(mapClientError))
 
-type Endpoint3_16Request = Parameters<RawClient["server.session"]["session.message"]>[0]
-type Endpoint3_16Input = {
-  readonly sessionID: Endpoint3_16Request["params"]["sessionID"]
-  readonly messageID: Endpoint3_16Request["params"]["messageID"]
+type Endpoint3_17Request = Parameters<RawClient["server.session"]["session.message"]>[0]
+type Endpoint3_17Input = {
+  readonly sessionID: Endpoint3_17Request["params"]["sessionID"]
+  readonly messageID: Endpoint3_17Request["params"]["messageID"]
 }
-const Endpoint3_16 = (raw: RawClient["server.session"]) => (input: Endpoint3_16Input) =>
+const Endpoint3_17 = (raw: RawClient["server.session"]) => (input: Endpoint3_17Input) =>
   raw["session.message"]({ params: { sessionID: input["sessionID"], messageID: input["messageID"] } }).pipe(
     Effect.mapError(mapClientError),
     Effect.map((value) => value.data),
@@ -216,15 +224,16 @@ const adaptGroup3 = (raw: RawClient["server.session"]) => ({
   switchModel: Endpoint3_5(raw),
   prompt: Endpoint3_6(raw),
   compact: Endpoint3_7(raw),
-  wait: Endpoint3_8(raw),
-  stage: Endpoint3_9(raw),
-  clear: Endpoint3_10(raw),
-  commit: Endpoint3_11(raw),
-  context: Endpoint3_12(raw),
-  history: Endpoint3_13(raw),
-  events: Endpoint3_14(raw),
-  interrupt: Endpoint3_15(raw),
-  message: Endpoint3_16(raw),
+  recap: Endpoint3_8(raw),
+  wait: Endpoint3_9(raw),
+  stage: Endpoint3_10(raw),
+  clear: Endpoint3_11(raw),
+  commit: Endpoint3_12(raw),
+  context: Endpoint3_13(raw),
+  history: Endpoint3_14(raw),
+  events: Endpoint3_15(raw),
+  interrupt: Endpoint3_16(raw),
+  message: Endpoint3_17(raw),
 })
 
 type Endpoint4_0Request = Parameters<RawClient["server.message"]["session.messages"]>[0]

packages/client/src/generated/client.ts

@@ -19,6 +19,8 @@ import type {
   SessionsPromptOutput,
   SessionsCompactInput,
   SessionsCompactOutput,
+  SessionsRecapInput,
+  SessionsRecapOutput,
   SessionsWaitInput,
   SessionsWaitOutput,
   SessionsStageInput,
@@ -390,6 +392,17 @@ export function make(options: ClientOptions) {
           },
           requestOptions,
         ),
+      recap: (input: SessionsRecapInput, requestOptions?: RequestOptions) =>
+        request<{ readonly data: SessionsRecapOutput }>(
+          {
+            method: "POST",
+            path: `/api/session/${encodeURIComponent(input.sessionID)}/recap`,
+            successStatus: 200,
+            declaredStatuses: [404, 503, 400, 401],
+            empty: false,
+          },
+          requestOptions,
+        ).then((value) => value.data),
       wait: (input: SessionsWaitInput, requestOptions?: RequestOptions) =>
         request<SessionsWaitOutput>(
           {

packages/client/src/generated/types.ts

@@ -486,6 +486,10 @@ export type SessionsCompactInput = { readonly sessionID: { readonly sessionID: s
 
 export type SessionsCompactOutput = void
 
+export type SessionsRecapInput = { readonly sessionID: { readonly sessionID: string }["sessionID"] }
+
+export type SessionsRecapOutput = { readonly data: string }["data"]
+
 export type SessionsWaitInput = { readonly sessionID: { readonly sessionID: string }["sessionID"] }
 
 export type SessionsWaitOutput = void

packages/core/src/session.ts

@@ -95,7 +95,7 @@ export class NotFoundError extends Schema.TaggedErrorClass<NotFoundError>()("Ses
 export class OperationUnavailableError extends Schema.TaggedErrorClass<OperationUnavailableError>()(
   "Session.OperationUnavailableError",
   {
-    operation: Schema.Literals(["move", "shell", "skill", "switchAgent", "compact", "wait"]),
+    operation: Schema.Literals(["move", "shell", "skill", "switchAgent", "compact", "recap", "wait"]),
   },
 ) {}
 
@@ -164,6 +164,7 @@ export interface Interface {
     resume?: boolean
   }) => Effect.Effect<void, OperationUnavailableError>
   readonly compact: (input: CompactInput) => Effect.Effect<void, NotFoundError | OperationUnavailableError>
+  readonly recap: (sessionID: SessionSchema.ID) => Effect.Effect<string, NotFoundError | OperationUnavailableError>
   readonly wait: (id: SessionSchema.ID) => Effect.Effect<void, NotFoundError | OperationUnavailableError>
   readonly active: Effect.Effect<ReadonlySet<SessionSchema.ID>>
   readonly resume: (sessionID: SessionSchema.ID) => Effect.Effect<void, NotFoundError | SessionRunner.RunError>
@@ -418,6 +419,12 @@ const layer = Layer.effect(
         yield* result.get(input.sessionID)
         return yield* new OperationUnavailableError({ operation: "compact" })
       }),
+      recap: Effect.fn("V2Session.recap")(function* (sessionID) {
+        yield* result.get(sessionID)
+        return yield* execution.recap(sessionID).pipe(
+          Effect.catchCause((defect) => Effect.logError("RECAP ERROR", defect).pipe(Effect.andThen(Effect.fail(new OperationUnavailableError({ operation: "recap" })))))
+        )
+      }),
       wait: Effect.fn("V2Session.wait")(function* (sessionID) {
         yield* result.get(sessionID)
         return yield* new OperationUnavailableError({ operation: "wait" })

packages/core/src/session/compaction.ts

@@ -234,8 +234,53 @@ export const make = (dependencies: Dependencies) => {
       return false
     return yield* compactAfterOverflow(input)
   })
+  const generateSummaryFromText = Effect.fn("SessionCompaction.generateSummaryFromText")(function* (input: {
+    readonly contextText: string
+    readonly model: Model
+  }) {
+    if (!input.contextText.trim()) return "No sufficient context for a summary."
+    const summaryPrompt = `Based on the following conversation history, please write a brief, 1-2 sentence conversational summary of what the user is asking or trying to accomplish, and why (if deducible). Phrase it directly to the user (e.g., "You've been asking about..."). Do not include any other markdown or headers, just the short summary.\n\n<history>\n${input.contextText}\n</history>`
+    const summaryOutput = Math.min(input.model.route.defaults.limits?.output || SUMMARY_OUTPUT_TOKENS, SUMMARY_OUTPUT_TOKENS)
+
+    const chunks: string[] = []
+    let failed = false
+    yield* dependencies.llm
+      .stream(
+        LLM.request({
+          model: input.model,
+          messages: [Message.user(summaryPrompt)],
+          tools: [],
+          generation: { maxTokens: summaryOutput },
+        }),
+      )
+      .pipe(
+        Stream.runForEach((event) => {
+          if (LLMEvent.is.providerError(event)) failed = true
+          if (LLMEvent.is.textDelta(event)) chunks.push(event.text)
+          return Effect.void
+        }),
+        Effect.catchTag("LLM.Error", () => Effect.void),
+      )
+    const summary = chunks.join("")
+    if (failed || !summary.trim()) return "Failed to generate summary."
+    return summary
+  })
+  const generateSummaryString = Effect.fn("SessionCompaction.generateSummaryString")(function* (input: {
+    readonly sessionID: SessionSchema.ID
+    readonly entries: readonly Entry[]
+    readonly model: Model
+  }) {
+    const selected = select(input.entries, config.tokens)
+    const previousSummary = input.entries.find((entry) => entry.message.type === "compaction")?.message
+    if (!selected || (selected.head.length === 0 && selected.recent.length === 0 && previousSummary?.type !== "compaction")) return "No sufficient context for a summary."
+    const contextText = [previousSummary?.type === "compaction" ? previousSummary.recent : "", selected.head, selected.recent].filter(Boolean).join("\n\n")
+    return yield* generateSummaryFromText({ contextText, model: input.model })
+  })
+
   return {
     compactIfNeeded,
     compactAfterOverflow,
+    generateSummaryString,
+    generateSummaryFromText,
   }
 }

packages/core/src/session/execution.ts

@@ -15,6 +15,8 @@ export interface Interface {
   readonly wake: (sessionID: SessionSchema.ID) => Effect.Effect<void>
   /** Interrupt active work owned by this process. Idle interruption is a no-op. */
   readonly interrupt: (sessionID: SessionSchema.ID) => Effect.Effect<void>
+  /** Generates a read-only recap summary of the session using the LLM. */
+  readonly recap: (sessionID: SessionSchema.ID) => Effect.Effect<string, SessionRunner.RunError>
 }
 
 /** Routes execution from a Session ID to the runner owned by that Session's Location. */
@@ -30,5 +32,6 @@ export const noopLayer = Layer.succeed(
     resume: () => Effect.void,
     wake: () => Effect.void,
     interrupt: () => Effect.void,
+    recap: () => Effect.succeed(""),
   }),
 )

packages/core/src/session/execution/local.ts

@@ -33,6 +33,14 @@ const layer = Layer.effect(
       interrupt: coordinator.interrupt,
       resume: coordinator.run,
       wake: coordinator.wake,
+      recap: Effect.fnUntraced(function* (sessionID: SessionSchema.ID) {
+        const session = yield* store.get(sessionID)
+        if (!session) return yield* Effect.die(`Session not found: ${sessionID}`)
+        return yield* SessionRunner.Service.use((runner) => runner.recap(sessionID)).pipe(
+          Effect.provide(locations.get(session.location)),
+          Effect.tapCause((cause) => Effect.logError("Failed to recap Session", cause)),
+        )
+      }),
     })
   }),
 )

packages/core/src/session/runner/index.ts

@@ -23,6 +23,8 @@ export interface Interface {
     readonly sessionID: SessionSchema.ID
     readonly force: boolean
   }) => Effect.Effect<void, RunError>
+  /** Generates a summary string of the session's current context without mutating anything. */
+  readonly recap: (sessionID: SessionSchema.ID) => Effect.Effect<string, RunError>
 }
 
 export class Service extends Context.Service<Service, Interface>()("@opencode/v2/SessionRunner") {}