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
 constEndpoint3_7=(raw: RawClient["server.session"])=>(input: Endpoint3_7Input)=>
 raw["session.compact"]({params: {sessionID: input["sessionID"]}}).pipe(Effect.mapError(mapClientError))
 
-typeEndpoint3_8Request=Parameters<RawClient["server.session"]["session.wait"]>[0]
+typeEndpoint3_8Request=Parameters<RawClient["server.session"]["session.recap"]>[0]
 typeEndpoint3_8Input={readonlysessionID: Endpoint3_8Request["params"]["sessionID"]}
 constEndpoint3_8=(raw: RawClient["server.session"])=>(input: Endpoint3_8Input)=>
+raw["session.recap"]({params: {sessionID: input["sessionID"]}}).pipe(
+Effect.mapError(mapClientError),
+Effect.map((value)=>value.data),
+)
+
+typeEndpoint3_9Request=Parameters<RawClient["server.session"]["session.wait"]>[0]
+typeEndpoint3_9Input={readonlysessionID: Endpoint3_9Request["params"]["sessionID"]}
+constEndpoint3_9=(raw: RawClient["server.session"])=>(input: Endpoint3_9Input)=>
 raw["session.wait"]({params: {sessionID: input["sessionID"]}}).pipe(Effect.mapError(mapClientError))
 
-typeEndpoint3_9Request=Parameters<RawClient["server.session"]["session.revert.stage"]>[0]
-typeEndpoint3_9Input={
-readonlysessionID: Endpoint3_9Request["params"]["sessionID"]
-readonlymessageID: Endpoint3_9Request["payload"]["messageID"]
-readonlyfiles?: Endpoint3_9Request["payload"]["files"]
+typeEndpoint3_10Request=Parameters<RawClient["server.session"]["session.revert.stage"]>[0]
+typeEndpoint3_10Input={
+readonlysessionID: Endpoint3_10Request["params"]["sessionID"]
+readonlymessageID: Endpoint3_10Request["payload"]["messageID"]
+readonlyfiles?: Endpoint3_10Request["payload"]["files"]
 }
-constEndpoint3_9=(raw: RawClient["server.session"])=>(input: Endpoint3_9Input)=>
+constEndpoint3_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),
 )
 
-typeEndpoint3_10Request=Parameters<RawClient["server.session"]["session.revert.clear"]>[0]
-typeEndpoint3_10Input={readonlysessionID: Endpoint3_10Request["params"]["sessionID"]}
-constEndpoint3_10=(raw: RawClient["server.session"])=>(input: Endpoint3_10Input)=>
-raw["session.revert.clear"]({params: {sessionID: input["sessionID"]}}).pipe(Effect.mapError(mapClientError))
-
-typeEndpoint3_11Request=Parameters<RawClient["server.session"]["session.revert.commit"]>[0]
+typeEndpoint3_11Request=Parameters<RawClient["server.session"]["session.revert.clear"]>[0]
 typeEndpoint3_11Input={readonlysessionID: Endpoint3_11Request["params"]["sessionID"]}
 constEndpoint3_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))
 
-typeEndpoint3_12Request=Parameters<RawClient["server.session"]["session.context"]>[0]
+typeEndpoint3_12Request=Parameters<RawClient["server.session"]["session.revert.commit"]>[0]
 typeEndpoint3_12Input={readonlysessionID: Endpoint3_12Request["params"]["sessionID"]}
 constEndpoint3_12=(raw: RawClient["server.session"])=>(input: Endpoint3_12Input)=>
+raw["session.revert.commit"]({params: {sessionID: input["sessionID"]}}).pipe(Effect.mapError(mapClientError))
+
+typeEndpoint3_13Request=Parameters<RawClient["server.session"]["session.context"]>[0]
+typeEndpoint3_13Input={readonlysessionID: Endpoint3_13Request["params"]["sessionID"]}
+constEndpoint3_13=(raw: RawClient["server.session"])=>(input: Endpoint3_13Input)=>
 raw["session.context"]({params: {sessionID: input["sessionID"]}}).pipe(
 Effect.mapError(mapClientError),
 Effect.map((value)=>value.data),
 )
 
-typeEndpoint3_13Request=Parameters<RawClient["server.session"]["session.history"]>[0]
-typeEndpoint3_13Input={
-readonlysessionID: Endpoint3_13Request["params"]["sessionID"]
-readonlylimit?: Endpoint3_13Request["query"]["limit"]
-readonlyafter?: Endpoint3_13Request["query"]["after"]
+typeEndpoint3_14Request=Parameters<RawClient["server.session"]["session.history"]>[0]
+typeEndpoint3_14Input={
+readonlysessionID: Endpoint3_14Request["params"]["sessionID"]
+readonlylimit?: Endpoint3_14Request["query"]["limit"]
+readonlyafter?: Endpoint3_14Request["query"]["after"]
 }
-constEndpoint3_13=(raw: RawClient["server.session"])=>(input: Endpoint3_13Input)=>
+constEndpoint3_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))
 
-typeEndpoint3_14Request=Parameters<RawClient["server.session"]["session.events"]>[0]
-typeEndpoint3_14Input={
-readonlysessionID: Endpoint3_14Request["params"]["sessionID"]
-readonlyafter?: Endpoint3_14Request["query"]["after"]
+typeEndpoint3_15Request=Parameters<RawClient["server.session"]["session.events"]>[0]
+typeEndpoint3_15Input={
+readonlysessionID: Endpoint3_15Request["params"]["sessionID"]
+readonlyafter?: Endpoint3_15Request["query"]["after"]
 }
-constEndpoint3_14=(raw: RawClient["server.session"])=>(input: Endpoint3_14Input)=>
+constEndpoint3_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))),
 ),
 )
 
-typeEndpoint3_15Request=Parameters<RawClient["server.session"]["session.interrupt"]>[0]
-typeEndpoint3_15Input={readonlysessionID: Endpoint3_15Request["params"]["sessionID"]}
-constEndpoint3_15=(raw: RawClient["server.session"])=>(input: Endpoint3_15Input)=>
+typeEndpoint3_16Request=Parameters<RawClient["server.session"]["session.interrupt"]>[0]
+typeEndpoint3_16Input={readonlysessionID: Endpoint3_16Request["params"]["sessionID"]}
+constEndpoint3_16=(raw: RawClient["server.session"])=>(input: Endpoint3_16Input)=>
 raw["session.interrupt"]({params: {sessionID: input["sessionID"]}}).pipe(Effect.mapError(mapClientError))
 
-typeEndpoint3_16Request=Parameters<RawClient["server.session"]["session.message"]>[0]
-typeEndpoint3_16Input={
-readonlysessionID: Endpoint3_16Request["params"]["sessionID"]
-readonlymessageID: Endpoint3_16Request["params"]["messageID"]
+typeEndpoint3_17Request=Parameters<RawClient["server.session"]["session.message"]>[0]
+typeEndpoint3_17Input={
+readonlysessionID: Endpoint3_17Request["params"]["sessionID"]
+readonlymessageID: Endpoint3_17Request["params"]["messageID"]
 }
-constEndpoint3_16=(raw: RawClient["server.session"])=>(input: Endpoint3_16Input)=>
+constEndpoint3_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),
 })
 
 typeEndpoint4_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<{readonlydata: 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
 
 exporttypeSessionsCompactOutput=void
 
+exporttypeSessionsRecapInput={readonlysessionID: {readonlysessionID: string}["sessionID"]}
+
+exporttypeSessionsRecapOutput={readonlydata: string}["data"]
+
 exporttypeSessionsWaitInput={readonlysessionID: {readonlysessionID: string}["sessionID"]}
 
 exporttypeSessionsWaitOutput=void

packages/core/src/session.ts

@@ -95,7 +95,7 @@ export class NotFoundError extends Schema.TaggedErrorClass<NotFoundError>()("Ses
 exportclassOperationUnavailableErrorextendsSchema.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>
 readonlycompact: (input: CompactInput)=>Effect.Effect<void,NotFoundError|OperationUnavailableError>
+readonlyrecap: (sessionID: SessionSchema.ID)=>Effect.Effect<string,NotFoundError|OperationUnavailableError>
 readonlywait: (id: SessionSchema.ID)=>Effect.Effect<void,NotFoundError|OperationUnavailableError>
 readonlyactive: Effect.Effect<ReadonlySet<SessionSchema.ID>>
 readonlyresume: (sessionID: SessionSchema.ID)=>Effect.Effect<void,NotFoundError|SessionRunner.RunError>
@@ -418,6 +419,12 @@ const layer = Layer.effect(
 yield*result.get(input.sessionID)
 returnyield*newOperationUnavailableError({operation: "compact"})
 }),
+recap: Effect.fn("V2Session.recap")(function*(sessionID){
+yield*result.get(sessionID)
+returnyield*execution.recap(sessionID).pipe(
+Effect.catchCause((defect)=>Effect.logError("RECAP ERROR",defect).pipe(Effect.andThen(Effect.fail(newOperationUnavailableError({operation: "recap"})))))
+)
+}),
 wait: Effect.fn("V2Session.wait")(function*(sessionID){
 yield*result.get(sessionID)
 returnyield*newOperationUnavailableError({operation: "wait"})

packages/core/src/session/compaction.ts

@@ -234,8 +234,53 @@ export const make = (dependencies: Dependencies) => {
 returnfalse
 returnyield*compactAfterOverflow(input)
 })
+constgenerateSummaryFromText=Effect.fn("SessionCompaction.generateSummaryFromText")(function*(input: {
+readonlycontextText: string
+readonlymodel: Model
+}){
+if(!input.contextText.trim())return"No sufficient context for a summary."
+constsummaryPrompt=`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>`
+constsummaryOutput=Math.min(input.model.route.defaults.limits?.output||SUMMARY_OUTPUT_TOKENS,SUMMARY_OUTPUT_TOKENS)
+
+constchunks: string[]=[]
+letfailed=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)
+returnEffect.void
+}),
+Effect.catchTag("LLM.Error",()=>Effect.void),
+)
+constsummary=chunks.join("")
+if(failed||!summary.trim())return"Failed to generate summary."
+returnsummary
+})
+constgenerateSummaryString=Effect.fn("SessionCompaction.generateSummaryString")(function*(input: {
+readonlysessionID: SessionSchema.ID
+readonlyentries: readonlyEntry[]
+readonlymodel: Model
+}){
+constselected=select(input.entries,config.tokens)
+constpreviousSummary=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."
+constcontextText=[previousSummary?.type==="compaction" ? previousSummary.recent : "",selected.head,selected.recent].filter(Boolean).join("\n\n")
+returnyield*generateSummaryFromText({ contextText,model: input.model})
+})
+
 return{
  compactIfNeeded,
  compactAfterOverflow,
+ generateSummaryString,
+ generateSummaryFromText,
 }
 }

packages/core/src/session/execution.ts

@@ -15,6 +15,8 @@ export interface Interface {
 readonlywake: (sessionID: SessionSchema.ID)=>Effect.Effect<void>
 /** Interrupt active work owned by this process. Idle interruption is a no-op. */
 readonlyinterrupt: (sessionID: SessionSchema.ID)=>Effect.Effect<void>
+/** Generates a read-only recap summary of the session using the LLM. */
+readonlyrecap: (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){
+constsession=yield*store.get(sessionID)
+if(!session)returnyield*Effect.die(`Session not found: ${sessionID}`)
+returnyield*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 {
 readonlysessionID: SessionSchema.ID
 readonlyforce: boolean
 })=>Effect.Effect<void,RunError>
+/** Generates a summary string of the session's current context without mutating anything. */
+readonlyrecap: (sessionID: SessionSchema.ID)=>Effect.Effect<string,RunError>
 }
 
 exportclassServiceextendsContext.Service<Service,Interface>()("@opencode/v2/SessionRunner"){}