feat(server): add transcript path groundwork

Author: pallyoung

packages/core/src/domain/types.test.ts

@@ -1,5 +1,6 @@
 import { describe, expect, expectTypeOf, it } from "vitest";
-import type { SessionState } from "./types";
+import type { ProviderDefinition } from "../provider/definition";
+import type { Session, SessionState } from "./types";
 import { deriveSessionTitle, SESSION_TITLE_MAX_LENGTH } from "./types";
 
 describe("deriveSessionTitle", () => {
@@ -42,3 +43,30 @@ describe("SessionState", () => {
     >();
   });
 });
+
+describe("notify-hook groundwork types", () => {
+  it("allows sessions to carry an optional transcript path", () => {
+    expectTypeOf<Session>().toMatchTypeOf<{
+      transcriptPath?: string;
+    }>();
+  });
+
+  it("allows provider definitions to opt into future resume and transcript helpers", () => {
+    expectTypeOf<ProviderDefinition>().toMatchTypeOf<{
+      buildResumeCommand?: (
+        config: unknown,
+        ctx: { sessionId: string; workspacePath: string; bridgeScriptPath?: string },
+        resumeId: string
+      ) => {
+        argv: string[];
+        env: Record<string, string>;
+        cwd: string;
+      };
+      resolveTranscriptPath?: (session: {
+        id: string;
+        transcriptPath?: string;
+        providerSessionId?: string;
+      }) => Promise<string | undefined> | string | undefined;
+    }>();
+  });
+});

packages/core/src/domain/types.ts

@@ -66,6 +66,7 @@ export interface Session {
   endedAt?: number;
   completionPercent?: number;
   errorReason?: string;
+  transcriptPath?: string;
   /**
    * Human-friendly title derived from the user's first submitted instruction
    * (trimmed/truncated to SESSION_TITLE_MAX_LENGTH). Assigned once on first

packages/core/src/provider/definition.ts

@@ -49,6 +49,16 @@ export interface ProviderDefinition {
     cwd: string;
   };
 
+  buildResumeCommand?(
+    config: ProviderConfig,
+    ctx: LaunchContext,
+    resumeId: string
+  ): {
+    argv: string[];
+    env: Record<string, string>;
+    cwd: string;
+  };
+
   buildSupervisorEvalCommand?(
     config: ProviderConfig,
     req: SupervisorEvalCommandRequest
@@ -66,11 +76,18 @@ export interface ProviderDefinition {
   // Runtime requirements
   requiredCommands: string[];
 
+  resolveTranscriptPath?(session: {
+    id: string;
+    transcriptPath?: string;
+    providerSessionId?: string;
+  }): Promise<string | undefined> | string | undefined;
+
   /** PTY-output-based idle detection used by the session manager. */
   idleHeuristics?: IdleHeuristics;
 }
 
 export interface LaunchContext {
   sessionId: string;
   workspacePath: string;
+  bridgeScriptPath?: string;
 }

packages/server/src/__tests__/session-integration.test.ts

@@ -934,6 +934,32 @@ describe("Session Integration", () => {
       );
     });
 
+    it("preserves persisted transcript path when hydrating a stale session", async () => {
+      sessionDb.listHydratable = vi.fn().mockReturnValue([
+        {
+          id: "sess-hydrate-transcript",
+          workspaceId: "ws-1",
+          terminalId: "term-stale",
+          providerId: "claude",
+          state: "running",
+          capability: "full",
+          startedAt: 100,
+          lastActiveAt: 200,
+          transcriptPath: "/tmp/transcripts/sess-hydrate-transcript.jsonl",
+        },
+      ]);
+
+      await sessionMgr.hydrate();
+
+      expect(sessionMgr.get("sess-hydrate-transcript")).toEqual(
+        expect.objectContaining({
+          id: "sess-hydrate-transcript",
+          state: "ended",
+          transcriptPath: "/tmp/transcripts/sess-hydrate-transcript.jsonl",
+        })
+      );
+    });
+
     it("marks persisted non-resumable sessions as ended when hydrating without a live terminal", async () => {
       sessionDb.listHydratable = vi.fn().mockReturnValue([
         {

packages/server/src/__tests__/session-repo.test.ts

@@ -100,6 +100,24 @@ describe("SessionRepo", () => {
 
       expect(result.completionPercent).toBe(50);
     });
+
+    it("should persist and read transcript path", () => {
+      const newSession: NewSession = {
+        id: "s-transcript",
+        workspaceId: "ws-1",
+        terminalId: "t-1",
+        providerId: "claude-cli",
+        state: "running",
+        capability: "full",
+        startedAt: Date.now(),
+        lastActiveAt: Date.now(),
+        transcriptPath: "/tmp/transcripts/s-transcript.jsonl",
+      };
+
+      const result = repo.create(newSession);
+
+      expect(result.transcriptPath).toBe("/tmp/transcripts/s-transcript.jsonl");
+    });
   });
 
   describe("listByWorkspace", () => {

packages/server/src/server.ts

@@ -296,8 +296,21 @@ function createSessionDatabase(db: Database) {
   return {
     insert: (session: SessionRow) => {
       db.prepare(`
-        INSERT INTO sessions (id, workspace_id, terminal_id, provider_id, state, capability, started_at, last_active_at)
-        VALUES (?, ?, ?, ?, ?, ?, ?, ?)
+        INSERT INTO sessions (
+          id,
+          workspace_id,
+          terminal_id,
+          provider_id,
+          state,
+          capability,
+          started_at,
+          last_active_at,
+          completion_percent,
+          error_reason,
+          transcript_path,
+          title
+        )
+        VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
       `).run(
         session.id,
         session.workspace_id,
@@ -306,7 +319,11 @@ function createSessionDatabase(db: Database) {
         session.state,
         session.capability,
         session.started_at,
-        session.last_active_at
+        session.last_active_at,
+        session.completion_percent,
+        session.error_reason,
+        session.transcript_path,
+        session.title
       );
     },
     update: (id: string, patch: Record<string, unknown>) => {
@@ -320,6 +337,7 @@ function createSessionDatabase(db: Database) {
         "ended_at",
         "completion_percent",
         "error_reason",
+        "transcript_path",
         "last_active_at",
         "title",
       ]);

packages/server/src/session/manager.ts

@@ -190,6 +190,7 @@ export class SessionManager {
         endedAt: session.endedAt,
         completionPercent: session.completionPercent,
         errorReason: session.errorReason,
+        transcriptPath: session.transcriptPath,
       });
 
       this.sessions.set(session.id, hydrated);
@@ -668,6 +669,7 @@ class ActiveSession {
   endedAt?: number;
   completionPercent?: number;
   errorReason?: string;
+  transcriptPath?: string;
   exitCode?: number;
   draft?: string;
   title?: string;
@@ -689,6 +691,7 @@ class ActiveSession {
     endedAt?: number;
     completionPercent?: number;
     errorReason?: string;
+    transcriptPath?: string;
   }) {
     this.id = data.id;
     this.workspaceId = data.workspaceId;
@@ -703,6 +706,7 @@ class ActiveSession {
     this.endedAt = data.endedAt;
     this.completionPercent = data.completionPercent;
     this.errorReason = data.errorReason;
+    this.transcriptPath = data.transcriptPath;
   }
 
   toDTO(): Session {
@@ -718,6 +722,7 @@ class ActiveSession {
       endedAt: this.endedAt,
       completionPercent: this.completionPercent,
       errorReason: this.errorReason,
+      transcriptPath: this.transcriptPath,
       title: this.title,
     };
   }

packages/server/src/session/types.ts

@@ -15,6 +15,7 @@ export interface SessionUpdatePatch {
   endedAt?: number;
   completionPercent?: number;
   errorReason?: string;
+  transcriptPath?: string;
   lastActiveAt?: number;
   title?: string;
 }

packages/server/src/storage/db.test.ts

@@ -49,7 +49,7 @@ describe("database schema baseline", () => {
       name: string;
     }>;
     expect(sessionColumns.find((column) => column.name === "resume_id")).toBeUndefined();
-    expect(sessionColumns.find((column) => column.name === "transcript_path")).toBeUndefined();
+    expect(sessionColumns.find((column) => column.name === "transcript_path")).toBeDefined();
     expect(sessionColumns.find((column) => column.name === "title")).toBeDefined();
 
     const indexNames = (
@@ -120,32 +120,6 @@ describe("database schema baseline", () => {
     expect(() => openDatabase(dbPath)).toThrow(/Legacy database schema detected/);
   });
 
-  it("rejects a legacy database schema that still contains transcript_path", async () => {
-    const { openDatabase } = await import("./db");
-
-    const db = new DatabaseSync(dbPath);
-    db.exec(`
-      CREATE TABLE sessions (
-        id TEXT PRIMARY KEY,
-        workspace_id TEXT NOT NULL,
-        terminal_id TEXT NOT NULL,
-        provider_id TEXT NOT NULL,
-        capability TEXT NOT NULL,
-        state TEXT NOT NULL,
-        started_at INTEGER NOT NULL,
-        ended_at INTEGER,
-        last_active_at INTEGER NOT NULL,
-        completion_percent INTEGER,
-        error_reason TEXT,
-        archived BOOLEAN DEFAULT 0,
-        transcript_path TEXT
-      );
-    `);
-    db.close();
-
-    expect(() => openDatabase(dbPath)).toThrow(/Legacy database schema detected/);
-  });
-
   it("rejects a legacy database schema that still contains _migrations", async () => {
     const { openDatabase } = await import("./db");
 
@@ -207,6 +181,7 @@ describe("database schema baseline", () => {
         last_active_at INTEGER NOT NULL,
         completion_percent INTEGER,
         error_reason TEXT,
+        transcript_path TEXT,
         archived BOOLEAN DEFAULT 0
       );
 
@@ -289,6 +264,7 @@ describe("database schema baseline", () => {
         last_active_at INTEGER NOT NULL,
         completion_percent INTEGER,
         error_reason TEXT,
+        transcript_path TEXT,
         archived BOOLEAN DEFAULT 0
       );
     `);

packages/server/src/storage/db.ts

@@ -33,7 +33,7 @@ const SCHEMA_PATH = join(import.meta.dirname, "migrations", "001_init.sql");
 const SCHEMA_SQL = readFileSync(SCHEMA_PATH, "utf-8");
 
 const LEGACY_TABLES = ["hook_registrations", "_migrations"] as const;
-const LEGACY_SESSION_COLUMNS = ["resume_id", "transcript_path"] as const;
+const LEGACY_SESSION_COLUMNS = ["resume_id"] as const;
 
 function normalizeSql(sql: string | null): string {
   return (sql ?? "").replace(/\s+/g, " ").trim();