From d181372b3513a9a6eac08065e2b5c07e6a2c4fe2 Mon Sep 17 00:00:00 2001 From: Kit Langton Date: Wed, 4 Nov 2026 21:03:29 -0800 Subject: [PATCH] feat(core): durable held subagent report storage --- packages/core/schema.json | 48 ++++- packages/core/src/database/migration.gen.ts | 2 + .../migration/20261105050139_held_report.ts | 18 ++ packages/core/src/database/schema.gen.ts | 6 + packages/core/src/session/sql.ts | 9 + packages/core/src/session/store.ts | 88 +++++++++ packages/core/test/database-migration.test.ts | 29 +++ packages/core/test/session-store.test.ts | 179 +++++++++++++++++- packages/core/test/v1-migration.test.ts | 3 + 9 files changed, 378 insertions(+), 4 deletions(-) create mode 100644 packages/core/src/database/migration/20261105050139_held_report.ts diff --git a/packages/core/schema.json b/packages/core/schema.json index 8ce2edd37c7..c1d59af5d98 100644 --- a/packages/core/schema.json +++ b/packages/core/schema.json @@ -1,8 +1,8 @@ { "version": "7", "dialect": "sqlite", - "id": "4f6e16c6-f070-4545-b9d0-19fcb6e5210c", - "prevIds": ["0ac88673-a402-45a0-b931-e694d59ccefa"], + "id": "da17acb7-efae-4660-850f-9d743f22f3cb", + "prevIds": ["4f6e16c6-f070-4545-b9d0-19fcb6e5210c"], "ddl": [ { "name": "account_state", @@ -1916,6 +1916,36 @@ "entityType": "columns", "table": "session_v2" }, + { + "type": "text", + "notNull": false, + "autoincrement": false, + "default": null, + "generated": null, + "name": "held_report_id", + "entityType": "columns", + "table": "session_v2" + }, + { + "type": "integer", + "notNull": false, + "autoincrement": false, + "default": null, + "generated": null, + "name": "held_report_at", + "entityType": "columns", + "table": "session_v2" + }, + { + "type": "text", + "notNull": false, + "autoincrement": false, + "default": null, + "generated": null, + "name": "held_report_answer", + "entityType": "columns", + "table": "session_v2" + }, { "type": "text", "notNull": false, @@ -2689,6 +2719,20 @@ "name": "session_v2_time_suspended_idx", "entityType": "indexes", "table": "session_v2" + }, + { + "columns": [ + { + "value": "held_report_id", + "isExpression": false + } + ], + "isUnique": false, + "where": "\"session_v2\".\"held_report_id\" is not null", + "origin": "manual", + "name": "session_v2_held_report_idx", + "entityType": "indexes", + "table": "session_v2" } ], "renames": [] diff --git a/packages/core/src/database/migration.gen.ts b/packages/core/src/database/migration.gen.ts index cbe0b9b044d..225631a3e8a 100644 --- a/packages/core/src/database/migration.gen.ts +++ b/packages/core/src/database/migration.gen.ts @@ -58,6 +58,7 @@ import m55 from "./migration/20261029002625_session_part.js" import m56 from "./migration/20261029073502_session_time_busy.js" import m57 from "./migration/20261029165540_schedule_checks.js" import m58 from "./migration/20261030054400_job.js" +import m59 from "./migration/20261105050139_held_report.js" export const migrations = [ m00, @@ -119,4 +120,5 @@ export const migrations = [ m56, m57, m58, + m59, ] satisfies DatabaseMigration.Migration[] diff --git a/packages/core/src/database/migration/20261105050139_held_report.ts b/packages/core/src/database/migration/20261105050139_held_report.ts new file mode 100644 index 00000000000..a7dadcd328b --- /dev/null +++ b/packages/core/src/database/migration/20261105050139_held_report.ts @@ -0,0 +1,18 @@ +import { Effect } from "effect" +import type { DatabaseMigration } from "../migration.js" + +const migration: DatabaseMigration.Migration = { + id: "20261105050139_held_report", + up(tx) { + return Effect.gen(function* () { + yield* tx.run(`ALTER TABLE \`session_v2\` ADD \`held_report_id\` text;`) + yield* tx.run(`ALTER TABLE \`session_v2\` ADD \`held_report_at\` integer;`) + yield* tx.run(`ALTER TABLE \`session_v2\` ADD \`held_report_answer\` text;`) + yield* tx.run( + `CREATE INDEX \`session_v2_held_report_idx\` ON \`session_v2\` (\`held_report_id\`) WHERE "session_v2"."held_report_id" is not null;`, + ) + }) + }, +} + +export default migration diff --git a/packages/core/src/database/schema.gen.ts b/packages/core/src/database/schema.gen.ts index 1b15f515691..81878628ce0 100644 --- a/packages/core/src/database/schema.gen.ts +++ b/packages/core/src/database/schema.gen.ts @@ -286,6 +286,9 @@ const schema: Omit = { \`time_archived\` integer, \`time_suspended\` integer, \`resume_attempts\` integer DEFAULT 0 NOT NULL, + \`held_report_id\` text, + \`held_report_at\` integer, + \`held_report_answer\` text, CONSTRAINT \`fk_session_v2_project_id_project_id_fk\` FOREIGN KEY (\`project_id\`) REFERENCES \`project\`(\`id\`) ON DELETE CASCADE ); `) @@ -347,6 +350,9 @@ const schema: Omit = { yield* tx.run( `CREATE INDEX \`session_v2_time_suspended_idx\` ON \`session_v2\` (\`time_suspended\`) WHERE "session_v2"."time_suspended" is not null;`, ) + yield* tx.run( + `CREATE INDEX \`session_v2_held_report_idx\` ON \`session_v2\` (\`held_report_id\`) WHERE "session_v2"."held_report_id" is not null;`, + ) }) }, } diff --git a/packages/core/src/session/sql.ts b/packages/core/src/session/sql.ts index 8684925220d..69925b2f652 100644 --- a/packages/core/src/session/sql.ts +++ b/packages/core/src/session/sql.ts @@ -72,6 +72,12 @@ export const SessionTable = sqliteTable( /** The execution claim timestamp (historical column name; see SessionStore.claim). */ time_suspended: integer(), resume_attempts: integer().notNull().default(0), + /** A non-null notification ID marks a report still owed to the parent. */ + held_report_id: text().$type(), + /** Earliest owed busy-period start; null means an unbounded hold. */ + held_report_at: integer(), + /** Last answer before the held period, meaningful only with a start timestamp. */ + held_report_answer: text().$type(), }, (table) => [ index("session_v2_project_idx").on(table.project_id), @@ -80,6 +86,9 @@ export const SessionTable = sqliteTable( index("session_v2_time_suspended_idx") .on(table.time_suspended) .where(sql`${table.time_suspended} is not null`), + index("session_v2_held_report_idx") + .on(table.held_report_id) + .where(sql`${table.held_report_id} is not null`), ], ) diff --git a/packages/core/src/session/store.ts b/packages/core/src/session/store.ts index a46f5e04816..7395e394ce9 100644 --- a/packages/core/src/session/store.ts +++ b/packages/core/src/session/store.ts @@ -51,6 +51,16 @@ export type MessagesInput = { } } +export type ReportStart = { + readonly at: number + readonly answer: SessionMessage.ID | undefined +} + +export type HeldReport = { + readonly notificationID: SessionMessage.ID + readonly since: ReportStart | undefined +} + export interface Interface { readonly get: (sessionID: Session.ID) => Effect.Effect readonly list: (input?: ListInput) => Effect.Effect @@ -89,6 +99,16 @@ export interface Interface { * total — or undefined when the Session no longer exists. */ readonly countResume: (sessionID: Session.ID) => Effect.Effect + /** Reads report bookkeeping, separate from public Session state and user activity. */ + readonly heldReport: (sessionID: Session.ID) => Effect.Effect + /** Atomically keeps the first hold and returns it; undefined only for a missing Session. Never updates activity. */ + readonly holdReport: (sessionID: Session.ID, report: HeldReport) => Effect.Effect + /** Unconditionally clears report bookkeeping without updating activity or execution claims. */ + readonly releaseReport: (sessionID: Session.ID) => Effect.Effect + /** Held children in ascending Session ID order; excludes top-level Sessions. */ + readonly listHeldChildren: () => Effect.Effect< + ReadonlyArray<{ readonly sessionID: Session.ID; readonly parentID: Session.ID; readonly report: HeldReport }> + > } export class Service extends Context.Service()("@opencode/SessionStore") {} @@ -97,6 +117,11 @@ const layer = Layer.effect( Service, Effect.gen(function* () { const { db } = yield* Database.Service + const heldColumns = { + held_report_id: SessionTable.held_report_id, + held_report_at: SessionTable.held_report_at, + held_report_answer: SessionTable.held_report_answer, + } /** One page of a session's message rows, oldest first within the page when paging backwards. */ const messageRows = Effect.fnUntraced(function* (input: MessagesInput) { @@ -204,6 +229,58 @@ const layer = Layer.effect( const [message] = yield* SessionHistory.decodeMessageRowsWithRefs(db, [row]).pipe(Effect.orDie) return message && { sessionID: row.session_id, message } }), + heldReport: Effect.fn("SessionStore.heldReport")(function* (sessionID) { + const row = yield* db + .select(heldColumns) + .from(SessionTable) + .where(eq(SessionTable.id, sessionID)) + .get() + .pipe(Effect.orDie) + return row ? heldRow(row) : undefined + }), + holdReport: Effect.fn("SessionStore.holdReport")(function* (sessionID, report) { + // SQLite evaluates SET expressions against the old row. The ID guards + // all three fields, including an unbounded first hold (null start). + const row = yield* db + .update(SessionTable) + .set({ + held_report_id: sql`coalesce(${SessionTable.held_report_id}, ${report.notificationID})`, + held_report_at: sql`case when ${SessionTable.held_report_id} is null then ${report.since?.at ?? null} else ${SessionTable.held_report_at} end`, + held_report_answer: sql`case when ${SessionTable.held_report_id} is null then ${report.since?.answer ?? null} else ${SessionTable.held_report_answer} end`, + time_updated: sql`${SessionTable.time_updated}`, + }) + .where(eq(SessionTable.id, sessionID)) + .returning(heldColumns) + .get() + .pipe(Effect.orDie) + return row ? heldRow(row) : undefined + }), + releaseReport: Effect.fn("SessionStore.releaseReport")((sessionID) => + db + .update(SessionTable) + .set({ + held_report_id: null, + held_report_at: null, + held_report_answer: null, + time_updated: sql`${SessionTable.time_updated}`, + }) + .where(eq(SessionTable.id, sessionID)) + .run() + .pipe(Effect.orDie, Effect.asVoid), + ), + listHeldChildren: Effect.fn("SessionStore.listHeldChildren")(function* () { + const rows = yield* db + .select({ sessionID: SessionTable.id, parentID: SessionTable.parent_id, ...heldColumns }) + .from(SessionTable) + .where(and(isNotNull(SessionTable.held_report_id), isNotNull(SessionTable.parent_id))) + .orderBy(asc(SessionTable.id)) + .all() + .pipe(Effect.orDie) + return rows.flatMap((row) => { + const report = heldRow(row) + return row.parentID !== null && report ? [{ sessionID: row.sessionID, parentID: row.parentID, report }] : [] + }) + }), listSuspended: Effect.fn("SessionStore.listSuspended")(function* () { return yield* db .select({ sessionID: SessionTable.id }) @@ -267,3 +344,14 @@ const layer = Layer.effect( ) export const node = makeGlobalNode({ service: Service, layer, deps: [Database.node] }) + +function heldRow( + row: Pick, +): HeldReport | undefined { + if (row.held_report_id === null) return undefined + return { + notificationID: row.held_report_id, + since: + row.held_report_at === null ? undefined : { at: row.held_report_at, answer: row.held_report_answer ?? undefined }, + } +} diff --git a/packages/core/test/database-migration.test.ts b/packages/core/test/database-migration.test.ts index 47171f8d65d..c64877599ae 100644 --- a/packages/core/test/database-migration.test.ts +++ b/packages/core/test/database-migration.test.ts @@ -22,6 +22,7 @@ import sessionInboxMigration from "@opencode/core/database/migration/20260812181 import sessionViewedStateMigration from "@opencode/core/database/migration/20260819222447_session_viewed_state" import azureCliCredentialMigration from "@opencode/core/database/migration/20261007190000_azure_cli_external_credential" import dropSessionPendingMigration from "@opencode/core/database/migration/20261025154125_drop_session_pending" +import heldReportMigration from "@opencode/core/database/migration/20261105050139_held_report" import { Global } from "@opencode/util/global" const run = ( @@ -195,6 +196,34 @@ describe("DatabaseMigration", () => { ) }) + test("adds nullable held-report bookkeeping to existing sessions", async () => { + await run( + Effect.gen(function* () { + const db = yield* makeDb + yield* db.run(sql`CREATE TABLE session_v2 (id text PRIMARY KEY, title text, time_updated integer)`) + yield* db.run(sql`INSERT INTO session_v2 VALUES ('ses_existing', 'Existing', 10)`) + + yield* DatabaseMigration.applyOnly(db, [heldReportMigration]) + yield* DatabaseMigration.applyOnly(db, [heldReportMigration]) + + expect(yield* db.get(sql`SELECT * FROM session_v2`)).toEqual({ + id: "ses_existing", + title: "Existing", + time_updated: 10, + held_report_id: null, + held_report_at: null, + held_report_answer: null, + }) + expect( + yield* db.get( + sql`SELECT name FROM sqlite_master WHERE type = 'index' AND name = 'session_v2_held_report_idx'`, + ), + ).toEqual({ name: "session_v2_held_report_idx" }) + expect(yield* db.get(sql`SELECT count(*) AS count FROM migration`)).toEqual({ count: 1 }) + }), + ) + }) + test("adds nullable attention state to existing sessions", async () => { await run( Effect.gen(function* () { diff --git a/packages/core/test/session-store.test.ts b/packages/core/test/session-store.test.ts index c30369fb935..5072f332238 100644 --- a/packages/core/test/session-store.test.ts +++ b/packages/core/test/session-store.test.ts @@ -7,7 +7,7 @@ import { AppNodeBuilder } from "@opencode/core/effect/app-node-builder" import { ProjectTable } from "@opencode/core/project/sql" import { SessionHistory } from "@opencode/core/session/history" import { SessionProjector } from "@opencode/core/session/projector" -import { SessionMessageTable, SessionPartTable } from "@opencode/core/session/sql" +import { SessionMessageTable, SessionPartTable, SessionTable } from "@opencode/core/session/sql" import { SessionStore } from "@opencode/core/session/store" import { Agent } from "@opencode/schema/agent" import { Event } from "@opencode/schema/event" @@ -27,7 +27,7 @@ const it = testEffect( ]), ) -const seedSessions = (rows: { id: string; updated: number }[]) => +const seedSessions = (rows: { id: string; updated: number; parentID?: Session.ID }[]) => Effect.gen(function* () { const database = yield* Database.Service const bus = yield* Bus.Service @@ -39,6 +39,7 @@ const seedSessions = (rows: { id: string; updated: number }[]) => yield* bus.publish(SessionEvent.Created, { sessionID, projectID: Project.ID.global, + parentID: row.parentID, location: { directory }, slug: "store-test", version: "test", @@ -57,6 +58,180 @@ const seedSessions = (rows: { id: string; updated: number }[]) => }) describe("SessionStore", () => { + describe("held reports", () => { + it.effect("reads unknown and unheld sessions without inserting a missing hold", () => + Effect.gen(function* () { + const sessionID = Session.ID.make("ses_unheld") + const missing = Session.ID.make("ses_missing") + yield* seedSessions([{ id: sessionID, updated: 10 }]) + const store = yield* SessionStore.Service + expect(yield* store.heldReport(sessionID)).toBeUndefined() + expect(yield* store.heldReport(missing)).toBeUndefined() + expect( + yield* store.holdReport(missing, { notificationID: SessionMessage.ID.make("msg_missing"), since: undefined }), + ).toBeUndefined() + yield* store.releaseReport(missing) + expect(yield* store.get(missing)).toBeUndefined() + expect((yield* store.list()).map((session) => session.id)).toEqual([sessionID]) + expect(yield* store.listHeldChildren()).toEqual([]) + }), + ) + + it.effect("preserves the first bounded hold, clears all fields, and accepts a fresh hold", () => + Effect.gen(function* () { + const sessionID = Session.ID.make("ses_bounded") + yield* seedSessions([{ id: sessionID, updated: 10 }]) + const store = yield* SessionStore.Service + const database = yield* Database.Service + const first = { + notificationID: SessionMessage.ID.make("msg_first"), + since: { at: 100, answer: SessionMessage.ID.make("msg_answer") }, + } + const later = { + notificationID: SessionMessage.ID.make("msg_later"), + since: { at: 200, answer: SessionMessage.ID.make("msg_new_answer") }, + } + expect(yield* store.holdReport(sessionID, first)).toEqual(first) + expect(yield* store.holdReport(sessionID, later)).toEqual(first) + expect(yield* store.holdReport(sessionID, { ...later, since: undefined })).toEqual(first) + expect(yield* store.heldReport(sessionID)).toEqual(first) + + yield* store.releaseReport(sessionID) + expect(yield* store.heldReport(sessionID)).toBeUndefined() + expect( + yield* database.db.select().from(SessionTable).where(eq(SessionTable.id, sessionID)).get(), + ).toMatchObject({ held_report_id: null, held_report_at: null, held_report_answer: null }) + expect(yield* store.holdReport(sessionID, later)).toEqual(later) + expect(yield* store.heldReport(sessionID)).toEqual(later) + }), + ) + + it.effect("keeps an unbounded first hold and round-trips a bounded hold without an answer", () => + Effect.gen(function* () { + const sessionID = Session.ID.make("ses_unbounded") + yield* seedSessions([{ id: sessionID, updated: 10 }]) + const store = yield* SessionStore.Service + const first = { notificationID: SessionMessage.ID.make("msg_first"), since: undefined } + const later = { + notificationID: SessionMessage.ID.make("msg_later"), + since: { at: 0, answer: undefined }, + } + expect(yield* store.holdReport(sessionID, first)).toEqual(first) + expect(yield* store.holdReport(sessionID, later)).toEqual(first) + expect(yield* store.heldReport(sessionID)).toEqual(first) + yield* store.releaseReport(sessionID) + expect(yield* store.holdReport(sessionID, later)).toEqual(later) + expect(yield* store.heldReport(sessionID)).toEqual(later) + }), + ) + + it.effect("does not expose an answer cursor without a start timestamp", () => + Effect.gen(function* () { + const parentID = Session.ID.make("ses_parent") + const sessionID = Session.ID.make("ses_child") + yield* seedSessions([ + { id: parentID, updated: 20 }, + { id: sessionID, updated: 10, parentID }, + ]) + const database = yield* Database.Service + const store = yield* SessionStore.Service + const report = { notificationID: SessionMessage.ID.make("msg_held"), since: undefined } + yield* database.db + .update(SessionTable) + .set({ + held_report_id: report.notificationID, + held_report_at: null, + held_report_answer: SessionMessage.ID.make("msg_stray"), + time_updated: 10, + }) + .where(eq(SessionTable.id, sessionID)) + .run() + expect(yield* store.heldReport(sessionID)).toEqual(report) + expect(yield* store.holdReport(sessionID, report)).toEqual(report) + expect(yield* store.listHeldChildren()).toEqual([{ sessionID, parentID, report }]) + }), + ) + + it.effect("keeps bookkeeping out of activity timestamps, list ordering and public Info", () => + Effect.gen(function* () { + const sessionID = Session.ID.make("ses_older") + yield* seedSessions([ + { id: sessionID, updated: 10 }, + { id: "ses_newer", updated: 20 }, + ]) + const store = yield* SessionStore.Service + const database = yield* Database.Service + const before = yield* store.list() + const report = { + notificationID: SessionMessage.ID.make("msg_held"), + since: { at: 100, answer: SessionMessage.ID.make("msg_answer") }, + } + yield* Effect.forEach( + [store.holdReport(sessionID, report), store.holdReport(sessionID, report), store.releaseReport(sessionID)], + (operation) => + Effect.gen(function* () { + yield* operation + expect( + yield* database.db + .select({ updated: SessionTable.time_updated }) + .from(SessionTable) + .where(eq(SessionTable.id, sessionID)) + .get(), + ).toEqual({ updated: 10 }) + expect(yield* store.list()).toEqual(before) + expect(yield* store.get(sessionID)).toEqual(before.find((session) => session.id === sessionID)) + expect( + Object.keys((yield* store.get(sessionID)) ?? {}).filter((key) => /held|report/i.test(key)), + ).toEqual([]) + }), + ) + }), + ) + + it.effect("lists only held children by ID and preserves holds through both claim releases", () => + Effect.gen(function* () { + const parentID = Session.ID.make("ses_parent") + const firstID = Session.ID.make("ses_a") + const lastID = Session.ID.make("ses_z") + yield* seedSessions([ + { id: parentID, updated: 40 }, + { id: lastID, updated: 30, parentID }, + { id: "ses_unheld", updated: 20, parentID }, + { id: firstID, updated: 10, parentID }, + ]) + const store = yield* SessionStore.Service + const database = yield* Database.Service + const first = { notificationID: SessionMessage.ID.make("msg_a"), since: undefined } + const last = { + notificationID: SessionMessage.ID.make("msg_z"), + since: { at: 100, answer: SessionMessage.ID.make("msg_answer") }, + } + yield* store.holdReport(parentID, { notificationID: SessionMessage.ID.make("msg_parent"), since: undefined }) + yield* store.holdReport(lastID, last) + yield* store.holdReport(firstID, first) + yield* store.claim(firstID) + yield* store.countResume(firstID) + yield* store.release(firstID) + expect(yield* store.heldReport(firstID)).toEqual(first) + yield* store.claim(firstID) + yield* store.claim(lastID) + yield* store.countResume(lastID) + yield* store.releaseChildClaims([]) + expect(yield* store.listHeldChildren()).toEqual([ + { sessionID: firstID, parentID, report: first }, + { sessionID: lastID, parentID, report: last }, + ]) + expect( + yield* database.db + .select({ claim: SessionTable.time_suspended, attempts: SessionTable.resume_attempts }) + .from(SessionTable) + .where(eq(SessionTable.id, lastID)) + .get(), + ).toEqual({ claim: null, attempts: 0 }) + }), + ) + }) + it.effect("lists by updated time and ID with exclusive two-item pages in either direction", () => Effect.gen(function* () { yield* seedSessions([ diff --git a/packages/core/test/v1-migration.test.ts b/packages/core/test/v1-migration.test.ts index adf925d076d..bf6488b7d30 100644 --- a/packages/core/test/v1-migration.test.ts +++ b/packages/core/test/v1-migration.test.ts @@ -74,6 +74,9 @@ const session = ( time_archived: null, time_suspended: null, resume_attempts: 0, + held_report_id: null, + held_report_at: null, + held_report_answer: null, ...overrides, })