@ixo/oracle-runtime-workers 0.13.0 → 0.16.0

package/src/tasks/spec.ts

@@ -8,6 +8,12 @@
  * to the queryable index columns, so the owner file stays self-describing and
  * portable.
  */
+import {
+  AgentWakeSchema,
+  PortableWorkDefinitionSchema,
+  type AgentWake,
+  type PortableWorkDefinition,
+} from '@ixo/common/work';
 import matter from 'gray-matter';
 import { z } from 'zod';
 import type { OracleTaskRecord, OracleTaskSchedule } from '../plugin-api/types';
@@ -75,6 +81,7 @@ export const TASK_APPROVALS = ['never', 'before-action'] as const;
 
 const SpecFrontmatterSchema = z.object({
   id: z.string().regex(TASK_ID_PATTERN),
+  executionProfile: z.literal('supplied-context-markdown').optional(),
   title: z.string().min(1).max(120),
   schedule: TaskScheduleSchema,
   approval: z.enum(TASK_APPROVALS),
@@ -90,6 +97,15 @@ export interface ParsedTaskSpec {
   intent: string;
 }
 
+/**
+ * Options for every gray-matter call. Called WITHOUT options, gray-matter
+ * stores each distinct input string (plus a Buffer copy of it) in a
+ * module-wide cache that is never cleared; every task save renders a new
+ * spec, so that cache would grow for the life of the isolate. Any options
+ * object, even an empty one, bypasses it.
+ */
+const MATTER_OPTIONS = {};
+
 /** JSON round-trip: YAML cannot serialise `undefined` values (`timezone?`). */
 function toPlainSchedule(schedule: OracleTaskSchedule): OracleTaskSchedule {
   return JSON.parse(JSON.stringify(schedule)) as OracleTaskSchedule;
@@ -99,6 +115,9 @@ function toPlainSchedule(schedule: OracleTaskSchedule): OracleTaskSchedule {
 export function renderTaskSpec(record: OracleTaskRecord): string {
   const frontmatter: TaskSpecFrontmatter = {
     id: record.id,
+    ...(record.executionProfile
+      ? { executionProfile: record.executionProfile }
+      : {}),
     title: record.title,
     schedule: toPlainSchedule(record.schedule),
     approval: record.approval,
@@ -106,12 +125,16 @@ export function renderTaskSpec(record: OracleTaskRecord): string {
     createdAt: record.createdAt,
     updatedAt: record.updatedAt,
   };
-  return matter.stringify(`${record.intent.trim()}\n`, frontmatter);
+  return matter.stringify(
+    `${record.intent.trim()}\n`,
+    frontmatter,
+    MATTER_OPTIONS,
+  );
 }
 
 /** Parse a spec markdown back into frontmatter + intent. Throws on schema drift. */
 export function parseTaskSpec(markdown: string): ParsedTaskSpec {
-  const parsed = matter(markdown);
+  const parsed = matter(markdown, MATTER_OPTIONS);
   const data: unknown = parsed.data;
   return {
     frontmatter: SpecFrontmatterSchema.parse(data),
@@ -121,5 +144,46 @@ export function parseTaskSpec(markdown: string): ParsedTaskSpec {
 
 /** The intent body of a spec without validating the frontmatter. */
 export function specIntentOf(markdown: string): string {
-  return matter(markdown).content.trim();
+  return matter(markdown, MATTER_OPTIONS).content.trim();
+}
+
+/**
+ * Extract the inert, reusable definition of a task. Owner, schedule,
+ * approvals, credentials and execution state are intentionally excluded.
+ * Throws a `ZodError` when the record does not form a valid definition (for
+ * example an empty title or intent).
+ */
+export function portableWorkFromTaskRecord(
+  record: OracleTaskRecord,
+): PortableWorkDefinition {
+  return PortableWorkDefinitionSchema.parse({
+    version: 1,
+    title: record.title,
+    intent: record.intent,
+  });
+}
+
+/**
+ * Describe one scheduled occurrence as a notify-only pointer. The Durable
+ * Object scheduler still re-reads current state before executing the run.
+ * Throws a `ZodError` when the principal is not a DID or `occurredAt` is not
+ * an ISO datetime, so a malformed wake never leaves the adapter.
+ */
+export function agentWakeFromTaskRecord(
+  record: OracleTaskRecord,
+  principal: string,
+  occurredAt: string,
+): AgentWake {
+  return AgentWakeSchema.parse({
+    version: 1,
+    wakeId: `task:${record.id}@${occurredAt}`,
+    principal,
+    source: 'task',
+    resourceRef: `task:${record.id}`,
+    observedRevision: record.updatedAt,
+    evaluatedThrough: occurredAt,
+    reason: 'scheduled-run',
+    occurredAt,
+    notifyOnly: true,
+  });
 }

package/src/tasks/store.ts

@@ -6,18 +6,31 @@
  *
  *   tasks(id PK, title, spec, schedule_json, status, approval, created_at,
  *         updated_at, next_run_at, last_run_at, last_result_json,
- *         consecutive_failures, pending_approval_at)
- *   task_runs(run_id PK, task_id, started_at, finished_at, ok, detail)
+ *         consecutive_failures, pending_approval_at, delivery_room_id,
+ *         execution_profile, topic_operation_id, topic_request_json,
+ *         approved_at, approval_note)
+ *   task_runs(run_id PK, task_id, started_at, finished_at, ok, detail,
+ *             state, completed_at, txn_id, room_id, result_text, attempts,
+ *             retry_at)
  *
  * The `spec` column is the full markdown artifact (gray-matter frontmatter +
  * intent body, see `spec.ts`); the sibling columns are the query index the
  * scheduler reads (`MIN(next_run_at)`, due scans). Timestamps in `*_at` TEXT
  * columns are ISO strings; `next_run_at` is INTEGER ms-epoch so MIN() and
- * `<=` comparisons stay numeric. No statement binds more than 13 parameters
- * (DO SQL caps at 100) and nothing uses LIKE.
+ * `<=` comparisons stay numeric.
  */
+import {
+  TopicDeliverableRequestSchema,
+  type TopicDeliverableRequest,
+} from './topic-deliverables';
+import {
+  isTaskExecutionProfile,
+  TASK_EXECUTION_PROFILES,
+  taskExecutionProfile,
+} from '../core/execution-profile';
 import type { DoSqliteDatabase, SqlParam } from '../sqlite/database';
 import type {
+  Logger,
   OracleTaskRecord,
   OracleTaskSchedule,
   OracleTaskStatus,
@@ -31,12 +44,20 @@ import {
 } from './spec';
 
 /**
- * A stored task. Extends the plugin-api record with the approval marker:
+ * A stored task. Extends the plugin-api record with the approval markers:
  * a `before-action` task whose run request is waiting on the user carries
- * `pendingApprovalAt` (ISO of when the request was posted).
+ * `pendingApprovalAt` (ISO of when the request was posted); once the user
+ * approves, `approvedAt` (and the user's `approvalNote`) mark a run the next
+ * alarm executes. The approval columns are written only by `approve` /
+ * `claimApproval`, never by `save`, so a stale copy cannot erase or revive
+ * an approval; a task that stops being active drops it.
  */
 export interface TaskRecord extends OracleTaskRecord {
   pendingApprovalAt?: string;
+  approvedAt?: string;
+  approvalNote?: string;
+  topicOperationId?: string;
+  topicRequest?: TopicDeliverableRequest;
 }
 
 /**
@@ -120,6 +141,11 @@ type TaskRow = {
   consecutive_failures: number;
   pending_approval_at: string | null;
   delivery_room_id: string | null;
+  execution_profile: string | null;
+  topic_operation_id: string | null;
+  topic_request_json: string | null;
+  approved_at: number | bigint | null;
+  approval_note: string | null;
 };
 
 type RunRow = {
@@ -149,6 +175,7 @@ type OpenRunRow = {
 /** Columns added after the first release; added to existing files on setup. */
 const RUN_COLUMN_UPGRADES: ReadonlyArray<readonly [string, string]> = [
   ['state', 'TEXT'],
+  ['completed_at', 'TEXT'],
   ['txn_id', 'TEXT'],
   ['room_id', 'TEXT'],
   ['result_text', 'TEXT'],
@@ -156,9 +183,39 @@ const RUN_COLUMN_UPGRADES: ReadonlyArray<readonly [string, string]> = [
   ['retry_at', 'INTEGER'],
 ];
 
+/**
+ * Run rows kept per task: the newest, plus any still open. Older closed rows
+ * are deleted when a new run starts, so the audit trail (and the owner copy
+ * it travels in) stops growing with the task's age.
+ */
+export const MAX_RUNS_KEPT_PER_TASK = 50;
+
+/** Run states that close a run; nothing re-reads a closed run's result. */
+const CLOSED_RUN_STATES = `('delivered', 'failed', 'interrupted')`;
+
+/**
+ * Whether the run row's task is a Topic deliverable: its stored result IS
+ * the product (read back through the owner's Topic API), so it is kept.
+ */
+const RUN_OF_TOPIC_TASK = `EXISTS (SELECT 1 FROM tasks
+  WHERE tasks.id = task_runs.task_id AND tasks.topic_operation_id IS NOT NULL)`;
+
+/** Columns `insert` writes (the approval columns start NULL). */
 const TASK_COLUMNS = `id, title, spec, schedule_json, status, approval, created_at,
   updated_at, next_run_at, last_run_at, last_result_json, consecutive_failures, pending_approval_at,
-  delivery_room_id`;
+  delivery_room_id, execution_profile, topic_operation_id, topic_request_json`;
+
+const TASK_SELECT = `${TASK_COLUMNS}, approved_at, approval_note`;
+
+/**
+ * Rows this runtime may load: no execution profile (an ordinary task) or one
+ * it knows. A row written by a newer runtime with a profile unknown here is
+ * left untouched in the file and never loaded, scheduled or run — it must
+ * not execute with this runtime's ordinary tool set, and one such row must
+ * not stall every other task. Turns on its session are refused
+ * (`unsupportedProfileOf`).
+ */
+const KNOWN_PROFILE_SQL = `(execution_profile IS NULL OR execution_profile IN (${TASK_EXECUTION_PROFILES.map(() => '?').join(', ')}))`;
 
 function isTaskStatus(value: string): value is OracleTaskStatus {
   return (TASK_STATUSES as readonly string[]).includes(value);
@@ -203,6 +260,7 @@ function rowToRecord(row: TaskRow): TaskRecord {
   );
   const record: TaskRecord = {
     id: row.id,
+    executionProfile: taskExecutionProfile(row.execution_profile),
     title: row.title,
     intent: specIntentOf(row.spec),
     schedule,
@@ -223,9 +281,19 @@ function rowToRecord(row: TaskRow): TaskRecord {
   if (row.pending_approval_at !== null) {
     record.pendingApprovalAt = row.pending_approval_at;
   }
+  if (row.approved_at !== null) {
+    record.approvedAt = new Date(Number(row.approved_at)).toISOString();
+    if (row.approval_note !== null) record.approvalNote = row.approval_note;
+  }
   if (row.delivery_room_id !== null) {
     record.deliveryRoomId = row.delivery_room_id;
   }
+  if (row.topic_operation_id !== null && row.topic_request_json !== null) {
+    record.topicOperationId = row.topic_operation_id;
+    record.topicRequest = TopicDeliverableRequestSchema.parse(
+      JSON.parse(row.topic_request_json),
+    );
+  }
   return record;
 }
 
@@ -244,13 +312,31 @@ function recordParams(record: TaskRecord): SqlParam[] {
     record.consecutiveFailures,
     record.pendingApprovalAt ?? null,
     record.deliveryRoomId ?? null,
+    record.executionProfile ?? null,
+    record.topicOperationId ?? null,
+    record.topicRequest ? JSON.stringify(record.topicRequest) : null,
   ];
 }
 
 export class TasksStore {
   private setupPromise: Promise<void> | undefined;
 
-  constructor(readonly db: DoSqliteDatabase) {}
+  constructor(
+    readonly db: DoSqliteDatabase,
+    private readonly log: Pick<Logger, 'warn'>,
+  ) {}
+
+  private loadable(row: TaskRow): boolean {
+    if (
+      row.execution_profile === null ||
+      isTaskExecutionProfile(row.execution_profile)
+    )
+      return true;
+    this.log.warn(
+      `[tasks] task ${row.id} has an execution profile this runtime does not support ('${row.execution_profile}'); it is skipped`,
+    );
+    return false;
+  }
 
   /** Create both tables + indexes. Idempotent, cached like `SessionsStore`. */
   setup(): Promise<void> {
@@ -283,6 +369,21 @@ export class TasksStore {
     const columns = await this.db.exec<{ name: string }>(
       `PRAGMA table_info(tasks)`,
     );
+    for (const [name, type] of [
+      ['topic_operation_id', 'TEXT'],
+      ['topic_request_json', 'TEXT'],
+      ['approved_at', 'INTEGER'],
+      ['approval_note', 'TEXT'],
+    ] as const) {
+      if (!columns.some((c) => c.name === name))
+        await this.db.run(`ALTER TABLE tasks ADD COLUMN ${name} ${type}`);
+    }
+    await this.db.run(
+      `CREATE UNIQUE INDEX IF NOT EXISTS idx_tasks_topic_operation ON tasks(topic_operation_id) WHERE topic_operation_id IS NOT NULL`,
+    );
+    if (!columns.some((c) => c.name === 'execution_profile')) {
+      await this.db.run(`ALTER TABLE tasks ADD COLUMN execution_profile TEXT`);
+    }
     if (!columns.some((c) => c.name === 'delivery_room_id')) {
       await this.db.run(`ALTER TABLE tasks ADD COLUMN delivery_room_id TEXT`);
     }
@@ -318,48 +419,136 @@ export class TasksStore {
       `CREATE INDEX IF NOT EXISTS idx_task_runs_open ON task_runs(state)
        WHERE state IN ('running', 'delivering')`,
     );
+    // The next delivery round (`minRetryAt`, on every wake computation):
+    // only parked rows carry `retry_at`, and closing a run clears it, so
+    // this index holds the handful of parked rows, never the history.
+    await this.db.run(
+      `CREATE INDEX IF NOT EXISTS idx_task_runs_retry ON task_runs(state, retry_at)
+       WHERE retry_at IS NOT NULL`,
+    );
   }
 
   async insert(record: TaskRecord): Promise<void> {
     await this.setup();
     await this.db.run(
-      `INSERT INTO tasks (${TASK_COLUMNS}) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`,
+      `INSERT INTO tasks (${TASK_COLUMNS}) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`,
       [record.id, ...recordParams(record)],
     );
   }
 
-  /** Full-row rewrite keyed by id. The spec markdown is re-rendered on every save. */
+  /**
+   * Full-row rewrite keyed by id. The spec markdown is re-rendered on every
+   * save. The approval columns are left as stored, except that a task saved
+   * as anything but `active` drops its approved run.
+   */
   async save(record: TaskRecord): Promise<void> {
     await this.setup();
     const { changes } = await this.db.run(
       `UPDATE tasks SET title = ?, spec = ?, schedule_json = ?, status = ?, approval = ?,
          created_at = ?, updated_at = ?, next_run_at = ?, last_run_at = ?,
          last_result_json = ?, consecutive_failures = ?, pending_approval_at = ?,
-         delivery_room_id = ?
-       WHERE id = ?`,
-      [...recordParams(record), record.id],
+         delivery_room_id = ?, execution_profile = ?, topic_operation_id = ?, topic_request_json = ?,
+         approved_at = CASE WHEN ? = 'active' THEN approved_at END,
+         approval_note = CASE WHEN ? = 'active' THEN approval_note END
+       WHERE id = ? AND (topic_operation_id IS NULL OR status != 'cancelled' OR ? = 'cancelled')`,
+      [
+        ...recordParams(record),
+        record.status,
+        record.status,
+        record.id,
+        record.status,
+      ],
     );
     if (changes === 0) {
       throw new Error(`task ${record.id} not found`);
     }
   }
 
+  /**
+   * Mark an approved run of an active task for the alarm: it runs once the
+   * alarm reaches `atMs`. False when the task is not active.
+   */
+  async approve(id: string, atMs: number, note?: string): Promise<boolean> {
+    await this.setup();
+    const { changes } = await this.db.run(
+      `UPDATE tasks SET approved_at = ?, approval_note = ? WHERE id = ? AND status = 'active'`,
+      [atMs, note ?? null, id],
+    );
+    return changes > 0;
+  }
+
+  /**
+   * Take the approved run of a task for execution: clears the marker and
+   * reports whether there was one. Called in the transaction that opens the
+   * run's ledger row, so an approval runs at most once.
+   */
+  async claimApproval(id: string): Promise<boolean> {
+    await this.setup();
+    const { changes } = await this.db.run(
+      `UPDATE tasks SET approved_at = NULL, approval_note = NULL
+       WHERE id = ? AND approved_at IS NOT NULL`,
+      [id],
+    );
+    return changes > 0;
+  }
+
   async get(id: string): Promise<TaskRecord | null> {
     await this.setup();
     const row = await this.db.get<TaskRow>(
-      `SELECT ${TASK_COLUMNS} FROM tasks WHERE id = ?`,
+      `SELECT ${TASK_SELECT} FROM tasks WHERE id = ?`,
+      [id],
+    );
+    return row === undefined || !this.loadable(row) ? null : rowToRecord(row);
+  }
+
+  /**
+   * The raw profile of a task row this runtime cannot load (see
+   * `KNOWN_PROFILE_SQL`); undefined when the row is loadable or absent.
+   */
+  async unsupportedProfileOf(id: string): Promise<string | undefined> {
+    await this.setup();
+    const row = await this.db.get<{ execution_profile: string | null }>(
+      `SELECT execution_profile FROM tasks WHERE id = ?`,
       [id],
     );
-    return row === undefined ? null : rowToRecord(row);
+    const profile = row?.execution_profile ?? null;
+    return profile === null || isTaskExecutionProfile(profile)
+      ? undefined
+      : profile;
+  }
+
+  async getTopicOperation(operationId: string): Promise<TaskRecord | null> {
+    await this.setup();
+    const row = await this.db.get<TaskRow>(
+      `SELECT ${TASK_SELECT} FROM tasks WHERE topic_operation_id = ?`,
+      [operationId],
+    );
+    return row === undefined || !this.loadable(row) ? null : rowToRecord(row);
+  }
+
+  async topicRun(taskId: string): Promise<
+    | {
+        run_id: string;
+        state: string | null;
+        result_text: string | null;
+        completed_at: string | null;
+      }
+    | undefined
+  > {
+    await this.setup();
+    return this.db.get(
+      `SELECT run_id, state, result_text, completed_at FROM task_runs WHERE task_id = ? ORDER BY started_at DESC, run_id DESC LIMIT 1`,
+      [taskId],
+    );
   }
 
-  /** Every task, oldest first (stable listing for tools). */
+  /** Every loadable task, oldest first (stable listing for tools). */
   async list(): Promise<TaskRecord[]> {
     await this.setup();
     const rows = await this.db.exec<TaskRow>(
-      `SELECT ${TASK_COLUMNS} FROM tasks ORDER BY created_at, id`,
+      `SELECT ${TASK_SELECT} FROM tasks ORDER BY created_at, id`,
     );
-    return rows.map(rowToRecord);
+    return rows.filter((row) => this.loadable(row)).map(rowToRecord);
   }
 
   /** Live tasks count toward the per-user cap: active or paused. */
@@ -371,24 +560,51 @@ export class TasksStore {
     return row?.n ?? 0;
   }
 
-  /** Earliest pending deadline (ms epoch) over active tasks, or null. */
-  async minNextRunAt(): Promise<number | null> {
+  /**
+   * Earliest pending deadline (ms epoch) over active loadable tasks — the
+   * next scheduled run or an approved run — or null. Tasks in `exclude`
+   * (their run is executing or being recovered; whoever ends it re-arms)
+   * are left out.
+   */
+  async minNextRunAt(exclude: readonly string[] = []): Promise<number | null> {
     await this.setup();
+    const excluded =
+      exclude.length > 0
+        ? `AND id NOT IN (${exclude.map(() => '?').join(', ')})`
+        : '';
     const row = await this.db.get<{ next: number | bigint | null }>(
-      `SELECT MIN(next_run_at) AS next FROM tasks WHERE status = 'active' AND next_run_at IS NOT NULL`,
+      `SELECT MIN(at) AS next FROM (
+         SELECT next_run_at AS at FROM tasks
+         WHERE status = 'active' AND next_run_at IS NOT NULL AND ${KNOWN_PROFILE_SQL} ${excluded}
+         UNION ALL
+         SELECT approved_at AS at FROM tasks
+         WHERE status = 'active' AND approved_at IS NOT NULL AND ${KNOWN_PROFILE_SQL} ${excluded}
+       )`,
+      [
+        ...TASK_EXECUTION_PROFILES,
+        ...exclude,
+        ...TASK_EXECUTION_PROFILES,
+        ...exclude,
+      ],
     );
     if (row === undefined || row.next === null) return null;
     return Number(row.next);
   }
 
-  /** Active tasks whose next run is due at or before `nowMs`, earliest first. */
+  /**
+   * Active loadable tasks with a scheduled run or an approved run due at or
+   * before `nowMs`, earliest first.
+   */
   async due(nowMs: number): Promise<TaskRecord[]> {
     await this.setup();
     const rows = await this.db.exec<TaskRow>(
-      `SELECT ${TASK_COLUMNS} FROM tasks
-       WHERE status = 'active' AND next_run_at IS NOT NULL AND next_run_at <= ?
-       ORDER BY next_run_at, id`,
-      [nowMs],
+      `SELECT ${TASK_SELECT} FROM tasks
+       WHERE status = 'active'
+         AND ((next_run_at IS NOT NULL AND next_run_at <= ?)
+           OR (approved_at IS NOT NULL AND approved_at <= ?))
+         AND ${KNOWN_PROFILE_SQL}
+       ORDER BY MIN(COALESCE(next_run_at, approved_at), COALESCE(approved_at, next_run_at)), id`,
+      [nowMs, nowMs, ...TASK_EXECUTION_PROFILES],
     );
     return rows.map(rowToRecord);
   }
@@ -410,6 +626,30 @@ export class TasksStore {
         entry.retryAt ?? null,
       ],
     );
+    await this.pruneRuns(entry.taskId);
+  }
+
+  /**
+   * Keep the task's newest `MAX_RUNS_KEPT_PER_TASK` rows and every open one;
+   * drop the result text closed ordinary runs still carry (rows written
+   * before closing a run cleared it). Uses the (task_id, started_at) index.
+   */
+  private async pruneRuns(taskId: string): Promise<void> {
+    await this.db.run(
+      `DELETE FROM task_runs
+       WHERE task_id = ? AND (state IS NULL OR state NOT IN ('running', 'delivering'))
+         AND run_id NOT IN (
+           SELECT run_id FROM task_runs WHERE task_id = ?
+           ORDER BY started_at DESC, run_id DESC LIMIT ?
+         )`,
+      [taskId, taskId, MAX_RUNS_KEPT_PER_TASK],
+    );
+    await this.db.run(
+      `UPDATE task_runs SET result_text = NULL
+       WHERE task_id = ? AND result_text IS NOT NULL
+         AND state IN ${CLOSED_RUN_STATES} AND NOT ${RUN_OF_TOPIC_TASK}`,
+      [taskId],
+    );
   }
 
   /**
@@ -429,9 +669,16 @@ export class TasksStore {
        VALUES (?, ?, ?, 'running', ?, 0)`,
       [run.runId, run.taskId, run.startedAt, run.txnId],
     );
+    await this.pruneRuns(run.taskId);
   }
 
-  /** Move a run's row along its life (one row write; only the given fields change). */
+  /**
+   * Move a run's row along its life (one row write; only the given fields
+   * change). Closing a run (`delivered` / `failed` / `interrupted`) also
+   * clears its delivery retry time and, unless the task is a Topic
+   * deliverable, its stored result text: nothing reads a closed ordinary
+   * run's result again (the task row keeps the summary).
+   */
   async updateRun(
     runId: string,
     patch: {
@@ -439,6 +686,7 @@ export class TasksStore {
       roomId?: string;
       resultText?: string;
       finishedAt?: string;
+      completedAt?: string;
       ok?: boolean;
       detail?: string;
       attempts?: number;
@@ -460,6 +708,10 @@ export class TasksStore {
       sets.push('result_text = ?');
       params.push(patch.resultText);
     }
+    if (patch.completedAt !== undefined) {
+      sets.push('completed_at = ?');
+      params.push(patch.completedAt);
+    }
     if (patch.finishedAt !== undefined) {
       sets.push('finished_at = ?');
       params.push(patch.finishedAt);
@@ -480,6 +732,17 @@ export class TasksStore {
       sets.push('retry_at = ?');
       params.push(patch.retryAt);
     }
+    const closing =
+      patch.state === 'delivered' ||
+      patch.state === 'failed' ||
+      patch.state === 'interrupted';
+    if (closing) {
+      if (patch.retryAt === undefined) sets.push('retry_at = NULL');
+      if (patch.resultText === undefined)
+        sets.push(
+          `result_text = CASE WHEN ${RUN_OF_TOPIC_TASK} THEN result_text END`,
+        );
+    }
     if (sets.length === 0) return;
     params.push(runId);
     await this.db.run(
@@ -534,6 +797,8 @@ export class TasksStore {
   /** Earliest pending delivery retry (ms epoch) over open runs, or null. */
   async minRetryAt(): Promise<number | null> {
     await this.setup();
+    // `retry_at IS NOT NULL` matches `idx_task_runs_retry`'s WHERE, which is
+    // what lets SQLite use that partial index.
     const row = await this.db.get<{ next: number | bigint | null }>(
       `SELECT MIN(retry_at) AS next FROM task_runs
        WHERE state = 'delivering' AND retry_at IS NOT NULL`,

package/src/tasks/topic-deliverables.ts

@@ -0,0 +1,70 @@
+import { z } from 'zod';
+
+export const TopicOperationId = z.string().regex(/^[A-Za-z0-9_-]{1,128}$/);
+const text = (max: number) => z.string().min(1).max(max);
+export const TopicDeliverableRequestSchema = z
+  .object({
+    topic: z
+      .object({
+        id: text(255),
+        roomId: text(255),
+        threadId: text(255),
+        attemptId: text(255),
+      })
+      .strict(),
+    title: text(120),
+    goal: text(4000),
+    instructions: text(16000),
+    sources: z
+      .array(z.object({ label: text(255), text: text(32000) }).strict())
+      .max(12),
+  })
+  .strict();
+
+export const TOPIC_DELIVERABLE_BODY_BYTES = 128 * 1024;
+export type TopicDeliverableRequest = z.infer<
+  typeof TopicDeliverableRequestSchema
+>;
+export interface TopicDeliverableSnapshot {
+  operationId: string;
+  taskId: string;
+  topic: TopicDeliverableRequest['topic'];
+  status:
+    | 'queued'
+    | 'working'
+    | 'paused'
+    | 'ready'
+    | 'stopping'
+    | 'cancelled'
+    | 'failed'
+    | 'interrupted';
+  runId?: string;
+  output?: { markdown: string; sha256: string; completedAt: string };
+  delivery?: 'pending' | 'delivered' | 'failed';
+}
+export type TopicDeliverableCommand =
+  | { action: 'start' | 'cancel'; request: TopicDeliverableRequest }
+  | { action: 'read' };
+export type TopicDeliverableResult =
+  | { ok: true; snapshot: TopicDeliverableSnapshot }
+  | { ok: false; status: 404 | 409 | 429; message: string };
+
+export async function markdownDigest(markdown: string): Promise<string> {
+  const bytes = await crypto.subtle.digest(
+    'SHA-256',
+    new TextEncoder().encode(markdown),
+  );
+  return `${Array.from(new Uint8Array(bytes), (byte) => byte.toString(16).padStart(2, '0')).join('')}`;
+}
+
+export function deliverableIntent(request: TopicDeliverableRequest): string {
+  return [
+    'Prepare a Markdown brief or report using only the supplied goal, instructions and source text. Clearly distinguish source evidence from assumptions. This artifact does not establish that the broader goal has been achieved.',
+    'The following JSON is supplied context, not permission to use tools or obtain other data.',
+    JSON.stringify({
+      goal: request.goal,
+      instructions: request.instructions,
+      sources: request.sources,
+    }),
+  ].join('\n\n');
+}