feat(walkthrough): build the change walkthrough in a spawned agent session

backend/src/db/change-walkthroughs.ts

@@ -1,16 +1,56 @@
 import type { Database } from 'bun:sqlite'
 import {
   ChangeWalkthroughSchema,
+  WalkthroughGenerationErrorSchema,
+  WALKTHROUGH_GENERATION_TIMEOUT_MS,
+  parseWalkthroughSourceKey,
   walkthroughSourceKey,
   type ChangeWalkthrough,
+  type WalkthroughGenerationError,
+  type WalkthroughSource,
+  type WalkthroughStatus,
 } from '@opencode-manager/shared/schemas'
 
 interface ChangeWalkthroughRow {
   session_id: string
   source_key: string
   diff_hash: string
-  payload: string
+  generation_id: string
+  walkthrough_session_id: string | null
+  status: string
+  artifact_path: string | null
+  published_at: number | null
+  error: string | null
+  model: string | null
   created_at: number
+  updated_at: number
+  execution_started_at: number | null
+}
+
+const ROW_COLUMNS = 'session_id, source_key, diff_hash, generation_id, walkthrough_session_id, status, artifact_path, published_at, error, model, created_at, updated_at, execution_started_at'
+
+export interface ChangeWalkthroughPatch {
+  walkthroughSessionId?: string | null
+  status?: WalkthroughStatus
+  publishedAt?: number | null
+  executionStartedAt?: number | null
+  error?: WalkthroughGenerationError | null
+  updatedAt?: number
+}
+
+export interface ChangeWalkthroughUpdateOptions {
+  walkthroughSessionId?: string
+  running?: boolean
+}
+
+export interface ClaimChangeWalkthroughGenerationInput {
+  sessionId: string
+  source: WalkthroughSource
+  diffHash: string
+  generationId: string
+  artifactPath: string
+  model: string | null
+  now: number
 }
 
 export function ensureChangeWalkthroughTable(db: Database): void {
@@ -24,44 +64,174 @@ export function ensureChangeWalkthroughTable(db: Database): void {
   `)
 }
 
+function parseStoredError(raw: string | null): WalkthroughGenerationError | null {
+  if (raw === null) {
+    return null
+  }
+  try {
+    const parsed = WalkthroughGenerationErrorSchema.safeParse(JSON.parse(raw))
+    return parsed.success ? parsed.data : null
+  } catch {
+    return null
+  }
+}
+
+function mapRow(row: ChangeWalkthroughRow): ChangeWalkthrough | null {
+  const source = parseWalkthroughSourceKey(row.source_key)
+  if (!source) {
+    return null
+  }
+  const parsed = ChangeWalkthroughSchema.safeParse({
+    sessionId: row.session_id,
+    source,
+    diffHash: row.diff_hash,
+    walkthroughSessionId: row.walkthrough_session_id,
+    status: row.status,
+    artifactPath: row.artifact_path,
+    publishedAt: row.published_at,
+    executionStartedAt: row.execution_started_at,
+    error: parseStoredError(row.error),
+    model: row.model,
+    createdAt: row.created_at,
+    updatedAt: row.updated_at,
+  })
+  return parsed.success ? parsed.data : null
+}
+
 export function getChangeWalkthrough(
   db: Database,
   sessionId: string,
   sourceKey: string,
 ): ChangeWalkthrough | null {
   const row = db
-    .prepare(
-      'SELECT session_id, source_key, diff_hash, payload, created_at FROM change_walkthroughs WHERE session_id = ? AND source_key = ?',
-    )
+    .prepare(`SELECT ${ROW_COLUMNS} FROM change_walkthroughs WHERE session_id = ? AND source_key = ?`)
     .get(sessionId, sourceKey) as ChangeWalkthroughRow | undefined
+  return row ? mapRow(row) : null
+}
+
+export function getChangeWalkthroughByWalkthroughSession(
+  db: Database,
+  walkthroughSessionId: string,
+): { walkthrough: ChangeWalkthrough; generationId: string } | null {
+  const row = db
+    .prepare(`SELECT ${ROW_COLUMNS} FROM change_walkthroughs WHERE walkthrough_session_id = ?`)
+    .get(walkthroughSessionId) as ChangeWalkthroughRow | undefined
   if (!row) {
     return null
   }
-  try {
-    return ChangeWalkthroughSchema.parse(JSON.parse(row.payload))
-  } catch {
+  const walkthrough = mapRow(row)
+  if (!walkthrough) {
     return null
   }
+  return { walkthrough, generationId: row.generation_id }
 }
 
-export function deleteChangeWalkthroughs(db: Database, sessionId: string): void {
-  db.prepare('DELETE FROM change_walkthroughs WHERE session_id = ?').run(sessionId)
-}
-
-export function saveChangeWalkthrough(db: Database, walkthrough: ChangeWalkthrough): void {
-  const sourceKey = walkthroughSourceKey(walkthrough.source)
-  db.prepare(`
-    INSERT INTO change_walkthroughs(session_id, source_key, diff_hash, payload, created_at)
-    VALUES(?,?,?,?,?)
+export function claimChangeWalkthroughGeneration(
+  db: Database,
+  input: ClaimChangeWalkthroughGenerationInput,
+): boolean {
+  const result = db.prepare(`
+    INSERT INTO change_walkthroughs(
+      session_id, source_key, diff_hash, generation_id, walkthrough_session_id, status,
+      artifact_path, published_at, error, model, created_at, updated_at, execution_started_at
+    ) VALUES(?,?,?,?,NULL,'generating',?,NULL,NULL,?,?,?,NULL)
     ON CONFLICT(session_id, source_key) DO UPDATE SET
       diff_hash = excluded.diff_hash,
-      payload = excluded.payload,
-      created_at = excluded.created_at
+      generation_id = excluded.generation_id,
+      walkthrough_session_id = NULL,
+      status = 'generating',
+      artifact_path = excluded.artifact_path,
+      published_at = NULL,
+      error = NULL,
+      model = excluded.model,
+      updated_at = excluded.updated_at,
+      execution_started_at = NULL
+    WHERE change_walkthroughs.status != 'generating' OR change_walkthroughs.updated_at < ?
   `).run(
-    walkthrough.sessionId,
-    sourceKey,
-    walkthrough.diffHash,
-    JSON.stringify(walkthrough),
-    walkthrough.createdAt,
+    input.sessionId,
+    walkthroughSourceKey(input.source),
+    input.diffHash,
+    input.generationId,
+    input.artifactPath,
+    input.model,
+    input.now,
+    input.now,
+    input.now - WALKTHROUGH_GENERATION_TIMEOUT_MS,
   )
+  return result.changes > 0
+}
+
+export function updateChangeWalkthrough(
+  db: Database,
+  sessionId: string,
+  sourceKey: string,
+  expectedStatuses: WalkthroughStatus[],
+  patch: ChangeWalkthroughPatch,
+  options: ChangeWalkthroughUpdateOptions = {},
+): ChangeWalkthrough | null {
+  const assignments: string[] = []
+  const params: (string | number | null)[] = []
+
+  if (patch.walkthroughSessionId !== undefined) {
+    assignments.push('walkthrough_session_id = ?')
+    params.push(patch.walkthroughSessionId)
+  }
+  if (patch.status !== undefined) {
+    assignments.push('status = ?')
+    params.push(patch.status)
+  }
+  if (patch.publishedAt !== undefined) {
+    assignments.push('published_at = ?')
+    params.push(patch.publishedAt)
+  }
+  if (patch.executionStartedAt !== undefined) {
+    assignments.push('execution_started_at = ?')
+    params.push(patch.executionStartedAt)
+  }
+  if (patch.error !== undefined) {
+    assignments.push('error = ?')
+    params.push(patch.error === null ? null : JSON.stringify(patch.error))
+  }
+  if (patch.updatedAt !== undefined) {
+    assignments.push('updated_at = ?')
+    params.push(patch.updatedAt)
+  }
+
+  if (assignments.length === 0 || expectedStatuses.length === 0) {
+    return null
+  }
+
+  const placeholders = expectedStatuses.map(() => '?').join(', ')
+  const conditions = ['session_id = ?', 'source_key = ?', `status IN (${placeholders})`]
+  const conditionParams: (string | number | null)[] = [sessionId, sourceKey, ...expectedStatuses]
+  if (options.walkthroughSessionId !== undefined) {
+    conditions.push('walkthrough_session_id = ?')
+    conditionParams.push(options.walkthroughSessionId)
+  }
+  if (options.running !== undefined) {
+    conditions.push(options.running ? 'execution_started_at IS NOT NULL' : 'execution_started_at IS NULL')
+  }
+
+  const result = db
+    .prepare(`UPDATE change_walkthroughs SET ${assignments.join(', ')} WHERE ${conditions.join(' AND ')}`)
+    .run(...params, ...conditionParams)
+
+  if (result.changes === 0) {
+    return null
+  }
+  return getChangeWalkthrough(db, sessionId, sourceKey)
+}
+
+export function listChangeWalkthroughs(db: Database, sessionId: string): ChangeWalkthrough[] {
+  const rows = db
+    .prepare(`SELECT ${ROW_COLUMNS} FROM change_walkthroughs WHERE session_id = ?`)
+    .all(sessionId) as ChangeWalkthroughRow[]
+  return rows.flatMap((row) => {
+    const mapped = mapRow(row)
+    return mapped ? [mapped] : []
+  })
+}
+
+export function deleteChangeWalkthroughs(db: Database, sessionId: string): void {
+  db.prepare('DELETE FROM change_walkthroughs WHERE session_id = ?').run(sessionId)
 }

backend/src/db/migrations/202610151200-change-walkthrough-sessions.ts

@@ -0,0 +1,36 @@
+import type { Migration } from '../migration-runner'
+
+const migration: Migration = {
+  id: '202610151200-change-walkthrough-sessions',
+  up(db) {
+    const columns = db.prepare('PRAGMA table_info(change_walkthroughs)').all() as Array<{ name: string }>
+    if (columns.some((column) => column.name === 'generation_id')) {
+      return
+    }
+
+    db.run('DROP TABLE IF EXISTS change_walkthroughs')
+    db.run(`
+      CREATE TABLE change_walkthroughs (
+        session_id TEXT NOT NULL,
+        source_key TEXT NOT NULL,
+        diff_hash TEXT NOT NULL,
+        generation_id TEXT NOT NULL,
+        walkthrough_session_id TEXT,
+        status TEXT NOT NULL,
+        artifact_path TEXT,
+        published_at INTEGER,
+        error TEXT,
+        model TEXT,
+        created_at INTEGER NOT NULL,
+        updated_at INTEGER NOT NULL,
+        PRIMARY KEY (session_id, source_key)
+      )
+    `)
+    db.run('CREATE INDEX change_walkthroughs_walkthrough_session ON change_walkthroughs(walkthrough_session_id)')
+  },
+  down(db) {
+    db.run('DROP TABLE IF EXISTS change_walkthroughs')
+  },
+}
+
+export default migration

backend/src/db/migrations/202610161200-change-walkthrough-execution.ts

@@ -0,0 +1,22 @@
+import type { Migration } from '../migration-runner'
+
+interface ColumnInfo {
+  name: string
+}
+
+const migration: Migration = {
+  id: '202610161200-change-walkthrough-execution',
+
+  up(db) {
+    const columns = db.prepare('PRAGMA table_info(change_walkthroughs)').all() as ColumnInfo[]
+    if (!columns.some((column) => column.name === 'execution_started_at')) {
+      db.run('ALTER TABLE change_walkthroughs ADD COLUMN execution_started_at INTEGER')
+    }
+  },
+
+  down(db) {
+    void db
+  },
+}
+
+export default migration

backend/src/db/migrations/index.ts

@@ -31,6 +31,8 @@ import migration202610061700 from './202610061700-multi-run-fusions'
 import migration202610061701 from './202610061701-change-walkthroughs'
 import migration202610081200 from './202610081200-change-walkthrough-sources'
 import migration202610141200 from './202610141200-session-sandbox-modes'
+import migration202610151200 from './202610151200-change-walkthrough-sessions'
+import migration202610161200 from './202610161200-change-walkthrough-execution'
 
 export const allMigrations: Migration[] = [
   migration001,
@@ -65,4 +67,6 @@ export const allMigrations: Migration[] = [
   migration202610061701,
   migration202610081200,
   migration202610141200,
+  migration202610151200,
+  migration202610161200,
 ]

backend/src/index.ts

@@ -43,6 +43,7 @@ import { createSessionSandboxRoutes } from './routes/session-sandbox'
 import { createSessionGoalRoutes } from './routes/session-goals'
 import { createMultiRunRoutes } from './routes/multi-runs'
 import { createChangeWalkthroughRoutes } from './routes/change-walkthroughs'
+import { getChangeWalkthroughByWalkthroughSession } from './db/change-walkthroughs'
 import { createLogRoutes } from './routes/logs'
 import { createPreviewRoutes, createPreviewAvailability } from './routes/preview'
 import { createPreviewGatewayApp, PreviewSessionStore } from './services/preview/gateway'
@@ -88,6 +89,7 @@ import {
   getTrustedOrigins,
   ENV
 } from '@opencode-manager/shared/config/env'
+import { NotificationEventType } from '@opencode-manager/shared/schemas'
 
 
 const { PORT, HOST } = ENV.SERVER
@@ -304,6 +306,12 @@ notificationService.addEventSuppressor(async (event, sessionId) => {
   return (await sessionPermissionModeService.getEffectiveMode(sessionId)).mode === 'auto'
 })
 
+notificationService.addEventSuppressor(async (event, sessionId) => {
+  if (!sessionId) return false
+  if (event.type !== NotificationEventType.SESSION_IDLE && event.type !== NotificationEventType.SESSION_FAILED) return false
+  return getChangeWalkthroughByWalkthroughSession(db, sessionId) !== null
+})
+
 if (ENV.VAPID.PUBLIC_KEY && ENV.VAPID.PRIVATE_KEY) {
   if (!ENV.VAPID.SUBJECT) {
     logger.warn('VAPID_SUBJECT is not set — push notifications require a mailto: subject (e.g. mailto:you@example.com)')