@oar-sh/oar 0.9.14 → 0.9.16

package/server/claude-worker/claude-remote-relay-tool.mjs

@@ -13,7 +13,9 @@ import {
   REMOTE_RELAY_MODES,
   REMOTE_RELAY_PROVIDERS,
   REMOTE_RELAY_SESSION_SCOPES,
+  REMOTE_RELAY_THINKING_DISPLAYS,
 } from '../../shared/remote-relay-contract.mjs';
+import { RELAY_ASK_URGENCIES } from '../../shared/relay-asks.mjs';
 import {
   REMOTE_RELAY_CALL_FAILED,
   REMOTE_RELAY_TOOL_DESCRIPTION,
@@ -67,7 +69,21 @@ export const REMOTE_RELAY_TOOL_ZOD_SHAPE = {
   mode: choice('mode', REMOTE_RELAY_MODES),
   effort: text('effort'),
   title: text('title'),
+  // The one exception to the parity with the JSON schema: Claude may send
+  // null for update_session's group (out of the group), as "none" does on
+  // the providers whose strict schemas take a string only.
+  group: z.string().nullable().optional().describe(FIELDS.group.description),
+  auto_compact_window: number('auto_compact_window'),
+  thinking_enabled: z.boolean().optional().describe(FIELDS.thinking_enabled.description),
+  thinking_display: choice('thinking_display', REMOTE_RELAY_THINKING_DISPLAYS),
   question_id: text('question_id'),
+  // ask: the contract's validator refuses a question or detail that is too
+  // long, or more than eight options, with a message the model can act on.
+  question: text('question'),
+  options: z.array(z.string()).optional().describe(FIELDS.options.description),
+  recommendation: text('recommendation'),
+  detail: text('detail'),
+  urgency: choice('urgency', RELAY_ASK_URGENCIES),
   answer: text('answer'),
   choices: z.array(z.string()).optional().describe(FIELDS.choices.description),
   if_busy: choice('if_busy', REMOTE_RELAY_IF_BUSY),
@@ -78,18 +94,37 @@ export const REMOTE_RELAY_TOOL_ZOD_SHAPE = {
   match: text('match'),
   stalled_minutes: number('stalled_minutes'),
   heartbeat_minutes: number('heartbeat_minutes'),
+  digest_minutes: number('digest_minutes'),
+  // Loose and every field optional: the contract's validator checks the
+  // times and the zone and says what is wrong; an empty one is no option.
+  quiet_hours: z.looseObject({
+    from: z.string().optional().describe(FIELDS.quiet_hours.properties.from.description),
+    to: z.string().optional().describe(FIELDS.quiet_hours.properties.to.description),
+    tz: z.string().optional().describe(FIELDS.quiet_hours.properties.tz.description),
+  }).optional().describe(FIELDS.quiet_hours.description),
+  // A list, or the comma-separated text the contract takes as well.
+  exclude: z.union([z.array(z.string()), z.string()]).optional().describe(FIELDS.exclude.description),
   subscription_id: text('subscription_id'),
   watcher: text('watcher'),
   from: text('from'),
+  at: text('at'),
+  every_minutes: number('every_minutes'),
+  schedule_id: text('schedule_id'),
   task_id: text('task_id'),
   lines: number('lines'),
 };
 
+// What the tool registers: the shape as a loose object. A raw shape becomes a
+// strict-stripping object in the SDK's MCP layer, which would drop a key the
+// schema lacks before the contract's validator could refuse it (create_session)
+// or name it in `ignored` (the other actions). The loose object lets it through.
+export const REMOTE_RELAY_TOOL_ZOD_SCHEMA = z.looseObject(REMOTE_RELAY_TOOL_ZOD_SHAPE);
+
 export function createRemoteRelayToolDefinition({ api, getConversationId = () => '', dbg = () => {} } = {}) {
   return {
     name: REMOTE_RELAY_TOOL_NAME,
     description: REMOTE_RELAY_TOOL_DESCRIPTION,
-    inputSchema: REMOTE_RELAY_TOOL_ZOD_SHAPE,
+    inputSchema: REMOTE_RELAY_TOOL_ZOD_SCHEMA,
     // `extra.signal` is the MCP request's: the SDK aborts it when the CLI
     // cancels the call (a Stop interrupting the turn) or the process's MCP
     // transport closes, and the pending relay request goes with it.

package/server/claude-worker/claude-session-process.mjs

@@ -53,7 +53,7 @@ import {
   STEER_STOPPED_TEXT,
 } from '../../shared/steer-settle-markers.mjs';
 import { stripSteerNote, withSteerNoteContent } from '../../shared/steer-note.mjs';
-import { isRelayEventDelivery } from '../../shared/relay-events.mjs';
+import { isRelayAutomatedDelivery } from '../../shared/relay-events.mjs';
 import {
   stripSlashCommandGuard,
   stripSlashCommandGuardContent,
@@ -4209,9 +4209,9 @@ export function createClaudeSessionRunner({
         // noted steer no longer starts with "/" and is pushed as noted. The
         // replay signatures strip the guard too, so expectedText stays the
         // user's own text here as well.
-        // Nor into an event message the relay wrote: the note speaks as the
-        // user, the event must not (shared/relay-events.mjs).
-        const pushedContent = withSlashCommandGuardContent(steered && procRef.activeCtx?.kind !== 'continuation' && !isRelayEventDelivery(message)
+        // Nor into a message the relay wrote (an event, a scheduled prompt):
+        // the note speaks as the user, that message must not (shared/relay-events.mjs).
+        const pushedContent = withSlashCommandGuardContent(steered && procRef.activeCtx?.kind !== 'continuation' && !isRelayAutomatedDelivery(message)
           ? withSteerNoteContent(content)
           : content);
         procRef.pendingDelivered.push({ ctx, expectedText: contentText(content), pushedAt: Date.now(), steered });

package/server/copilot-worker/copilot-sdk-session-process.mjs

@@ -112,7 +112,7 @@ import { STEER_FOLDED_TEXT, STEER_STOPPED_TEXT, STEER_TURN_FAILED_TEXT } from '.
 import { buildSteerSettleFailure } from '../../shared/steer-settle-failure.mjs';
 import { shouldEmitStreamUpdate } from '../../shared/stream-emit-gating.mjs';
 import { withSteerNote } from '../../shared/steer-note.mjs';
-import { isRelayEventDelivery } from '../../shared/relay-events.mjs';
+import { isRelayAutomatedDelivery } from '../../shared/relay-events.mjs';
 import { isTransientRelayError } from '../../shared/worker-runtime/relay-errors.mjs';
 import {
   createTurnLiveness,
@@ -4456,7 +4456,7 @@ export function createCopilotSdkSessionRunner({
     // Not in a continuation: there the running work is the runtime's own
     // follow-up, not a request of the user's to keep going with.
     // Nor in an event message the relay wrote: the note speaks as the user.
-    const prompt = withRelayContext(context?.prefix, turn.kind === 'continuation' || isRelayEventDelivery(message) ? body : withSteerNote(body));
+    const prompt = withRelayContext(context?.prefix, turn.kind === 'continuation' || isRelayAutomatedDelivery(message) ? body : withSteerNote(body));
     // Re-checked AFTER the awaits and before anything is sent or registered.
     // Nothing has been sent yet, so handing the row back to the normal path is
     // free.

package/server/db-schema.mjs

@@ -24,6 +24,11 @@ import { migrateConversationGroupPosition } from './migrations/0015-conversation
 import { migrateShareAccessLog } from './migrations/0016-share-access-log.mjs';
 import { migrateConversationHistoryIndexes } from './migrations/0017-conversation-history-indexes.mjs';
 import { migrateBackgroundTaskRows } from './migrations/0018-background-task-rows.mjs';
+import { migrateRelayEventSubscriptionOptions } from './migrations/0019-relay-event-subscription-options.mjs';
+import { migrateConversationMayCreateSessions } from './migrations/0020-conversation-may-create-sessions.mjs';
+import { migrateConversationGroupAgentMarks } from './migrations/0021-conversation-group-agent-marks.mjs';
+import { migrateRelaySchedules } from './migrations/0022-relay-schedules.mjs';
+import { migrateRelayAsks } from './migrations/0023-relay-asks.mjs';
 import { migrateImageConversationSchema } from './repositories/image-conversation-repository.mjs';
 
 // Mirrors DEFAULT_RELAY_MODE in server-runtime.mjs; used only by the one-time
@@ -855,6 +860,53 @@ try {
   console.warn(`[background-tasks] migration 0018 failed; retrying on next boot: ${error?.message || error}`);
 }
 
+// Options of relay event subscriptions (digest, quiet hours, exclude) and the
+// watcher's own prompts: columns on 0011's table and one table. The event
+// service checks for them and refuses the options without them, so a failure
+// is logged and retried next boot like 0018.
+try {
+  migrateRelayEventSubscriptionOptions(db);
+} catch (error) {
+  console.warn(`[relay-events] migration 0019 failed; retrying on next boot: ${error?.message || error}`);
+}
+
+// The owner's "agents in this conversation may start sessions": one column.
+// Without it nobody can turn the switch on (the preferences route refuses
+// it) and the one-level rule holds for every session, so a failure is logged
+// and retried next boot like 0019.
+try {
+  migrateConversationMayCreateSessions(db);
+} catch (error) {
+  console.warn(`[remote-relays] migration 0020 failed; retrying on next boot: ${error?.message || error}`);
+}
+
+// What an agent's update_session may do to a group: two columns. Without
+// them an owner's group an agent emptied is kept until the next boot repair
+// only, so a failure is logged and retried next boot like 0020.
+try {
+  migrateConversationGroupAgentMarks(db);
+} catch (error) {
+  console.warn(`[session-groups] migration 0021 failed; retrying on next boot: ${error?.message || error}`);
+}
+
+// Relay schedules: one new table. The schedule service checks for it and
+// refuses the schedule actions without it, so a failure is logged and
+// retried next boot like 0021.
+try {
+  migrateRelaySchedules(db);
+} catch (error) {
+  console.warn(`[relay-schedules] migration 0022 failed; retrying on next boot: ${error?.message || error}`);
+}
+
+// Questions that don't block (remote_relay ask): one new table. The ask
+// service checks for it and refuses the ask actions without it, so a failure
+// is logged and retried next boot like 0022.
+try {
+  migrateRelayAsks(db);
+} catch (error) {
+  console.warn(`[relay-asks] migration 0023 failed; retrying on next boot: ${error?.message || error}`);
+}
+
 const runtimeSessionColumns = db.prepare(`PRAGMA table_info(runtime_sessions)`).all().map((c) => c.name);
 if (runtimeSessionColumns.length) {
   if (!runtimeSessionColumns.includes('strategy')) {

package/server/migrations/0019-relay-event-subscription-options.mjs

@@ -0,0 +1,106 @@
+'use strict';
+
+/**
+ * Migration: options of relay event subscriptions.
+ *
+ * Columns on `relay_event_subscriptions` (all NULL = off, as before):
+ *
+ * - `digest_minutes`: the subscription's non-urgent events are held and
+ *   delivered as one row every N minutes; `digest_last_at` is when its last
+ *   such row went out (the next one is due N minutes after it).
+ * - `quiet_hours_json`: `{ from, to, tz }`; non-urgent events in the window
+ *   are held until it ends.
+ * - `exclude_json`: session ids an "all" subscription leaves out.
+ *
+ * `relay_event_own_prompts`: the prompts a watcher sent through send or
+ * create_session (`message_id` is the prompt's), and when it received the
+ * finished reply (`received_at`): the turn_end of such a turn is not
+ * delivered to it again. Rows go after a day.
+ *
+ * Held events are ordinary undelivered `relay_events` rows: they and the
+ * timers rebuilt from them survive a restart without anything more here.
+ *
+ * Additive and idempotent. Safe to run on every boot.
+ *
+ * Usage: node server/migrations/0019-relay-event-subscription-options.mjs [path/to/copilot.db]
+ */
+
+import { fileURLToPath } from 'url';
+import path from 'path';
+import process from 'process';
+import Database from 'better-sqlite3';
+
+export const RELAY_EVENT_OPTION_COLUMNS = Object.freeze([
+  ['digest_minutes', 'INTEGER'],
+  ['digest_last_at', 'TEXT'],
+  ['quiet_hours_json', 'TEXT'],
+  ['exclude_json', 'TEXT'],
+]);
+
+function tableExists(db, name) {
+  return !!db
+    .prepare(`SELECT name FROM sqlite_master WHERE type = 'table' AND name = ?`)
+    .get(name);
+}
+
+export function migrateRelayEventSubscriptionOptions(db) {
+  if (!tableExists(db, 'relay_event_subscriptions')) {
+    throw new Error('relay_event_subscriptions is missing (migration 0011 has not run)');
+  }
+  const present = new Set(db.prepare(`PRAGMA table_info(relay_event_subscriptions)`).all().map((column) => column.name));
+  let columnsAdded = 0;
+  for (const [name, type] of RELAY_EVENT_OPTION_COLUMNS) {
+    if (present.has(name)) continue;
+    db.exec(`ALTER TABLE relay_event_subscriptions ADD COLUMN ${name} ${type}`);
+    columnsAdded += 1;
+  }
+  let tablesAdded = 0;
+  if (!tableExists(db, 'relay_event_own_prompts')) {
+    db.exec(`
+      CREATE TABLE relay_event_own_prompts (
+        message_id              TEXT PRIMARY KEY,
+        watcher_conversation_id TEXT NOT NULL,
+        relay_id                TEXT NOT NULL DEFAULT 'self',
+        session_id              TEXT NOT NULL,
+        created_at              TEXT NOT NULL,
+        received_at             TEXT
+      )
+    `);
+    tablesAdded += 1;
+  }
+  db.exec(`
+    CREATE INDEX IF NOT EXISTS idx_relay_event_own_prompts_created
+    ON relay_event_own_prompts(created_at)
+  `);
+  return { applied: columnsAdded > 0 || tablesAdded > 0, columnsAdded, tablesAdded };
+}
+
+function defaultDbPath() {
+  const here = path.dirname(fileURLToPath(import.meta.url));
+  return path.resolve(here, '..', 'data', 'copilot.db');
+}
+
+export function migrate(dbPath, options = {}) {
+  const db = new Database(dbPath, options);
+  try {
+    return migrateRelayEventSubscriptionOptions(db);
+  } finally {
+    db.close();
+  }
+}
+
+const isMain = process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url);
+if (isMain) {
+  const dbPath = process.argv[2] ? path.resolve(process.argv[2]) : defaultDbPath();
+  try {
+    const result = migrate(dbPath);
+    console.log(`Migration 0019 on ${dbPath}`);
+    console.log(result.applied
+      ? `  relay event subscription options: columns added ${result.columnsAdded}, tables added ${result.tablesAdded}`
+      : '  skipped: nothing to change');
+    process.exit(0);
+  } catch (err) {
+    console.error(`Migration 0019 failed: ${err?.message || err}`);
+    process.exit(1);
+  }
+}

package/server/migrations/0020-conversation-may-create-sessions.mjs

@@ -0,0 +1,67 @@
+'use strict';
+
+/**
+ * Migration: the owner's "agents in this conversation may start sessions".
+ *
+ * `may_create_sessions` is 1 when the owner allowed the agents of a session
+ * that an agent started to start sessions on this relay themselves (the
+ * remote_relay tool's one-level rule is lifted for it); NULL or 0 otherwise.
+ * Only the owner sets it, in the conversation's settings or through the
+ * preferences route; no agent can.
+ *
+ * Additive and idempotent. Safe to run on every boot. Rolling back needs no
+ * data change: older code ignores the column and keeps the one-level rule.
+ *
+ * Usage: node server/migrations/0020-conversation-may-create-sessions.mjs [path/to/copilot.db]
+ */
+
+import { fileURLToPath } from 'url';
+import path from 'path';
+import process from 'process';
+import Database from 'better-sqlite3';
+
+function tableExists(db, name) {
+  return !!db
+    .prepare(`SELECT name FROM sqlite_master WHERE type = 'table' AND name = ?`)
+    .get(name);
+}
+
+export function migrateConversationMayCreateSessions(db) {
+  if (!tableExists(db, 'conversations')) {
+    throw new Error('conversations is missing (the base schema has not run)');
+  }
+  const present = new Set(db.prepare(`PRAGMA table_info(conversations)`).all().map((column) => column.name));
+  if (present.has('may_create_sessions')) return { applied: false, columnsAdded: 0 };
+  db.exec(`ALTER TABLE conversations ADD COLUMN may_create_sessions INTEGER`);
+  return { applied: true, columnsAdded: 1 };
+}
+
+function defaultDbPath() {
+  const here = path.dirname(fileURLToPath(import.meta.url));
+  return path.resolve(here, '..', 'data', 'copilot.db');
+}
+
+export function migrate(dbPath, options = {}) {
+  const db = new Database(dbPath, options);
+  try {
+    return migrateConversationMayCreateSessions(db);
+  } finally {
+    db.close();
+  }
+}
+
+const isMain = process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url);
+if (isMain) {
+  const dbPath = process.argv[2] ? path.resolve(process.argv[2]) : defaultDbPath();
+  try {
+    const result = migrate(dbPath);
+    console.log(`Migration 0020 on ${dbPath}`);
+    console.log(result.applied
+      ? `  may create sessions: columns added ${result.columnsAdded}`
+      : '  skipped: nothing to change');
+    process.exit(0);
+  } catch (err) {
+    console.error(`Migration 0020 failed: ${err?.message || err}`);
+    process.exit(1);
+  }
+}

package/server/migrations/0021-conversation-group-agent-marks.mjs

@@ -0,0 +1,77 @@
+'use strict';
+
+/**
+ * Migration: what an agent's update_session may do to a session group.
+ *
+ * - `conversation_groups.agent_made` is 1 for a group update_session made
+ *   (a name the relay did not have). Only such a group goes once an agent
+ *   takes its last member out.
+ * - `conversation_groups.kept_empty_at` is set when an agent took the last
+ *   member out of a group the owner made: the group stays (empty), the boot
+ *   repair and the sweep leave it alone, and agents can still name it. The
+ *   mark goes as soon as a member joins again.
+ *
+ * Additive and idempotent. Safe to run on every boot. Rolling back needs no
+ * data change: older code ignores both columns (its boot repair removes an
+ * empty group, as it always did).
+ *
+ * Usage: node server/migrations/0021-conversation-group-agent-marks.mjs [path/to/copilot.db]
+ */
+
+import { fileURLToPath } from 'url';
+import path from 'path';
+import process from 'process';
+import Database from 'better-sqlite3';
+
+function tableExists(db, name) {
+  return !!db
+    .prepare(`SELECT name FROM sqlite_master WHERE type = 'table' AND name = ?`)
+    .get(name);
+}
+
+export function migrateConversationGroupAgentMarks(db) {
+  if (!tableExists(db, 'conversation_groups')) {
+    throw new Error('conversation_groups is missing (migration 0014 has not run)');
+  }
+  const present = new Set(db.prepare(`PRAGMA table_info(conversation_groups)`).all().map((column) => column.name));
+  let columnsAdded = 0;
+  if (!present.has('agent_made')) {
+    db.exec(`ALTER TABLE conversation_groups ADD COLUMN agent_made INTEGER`);
+    columnsAdded += 1;
+  }
+  if (!present.has('kept_empty_at')) {
+    db.exec(`ALTER TABLE conversation_groups ADD COLUMN kept_empty_at TEXT`);
+    columnsAdded += 1;
+  }
+  return { applied: columnsAdded > 0, columnsAdded };
+}
+
+function defaultDbPath() {
+  const here = path.dirname(fileURLToPath(import.meta.url));
+  return path.resolve(here, '..', 'data', 'copilot.db');
+}
+
+export function migrate(dbPath, options = {}) {
+  const db = new Database(dbPath, options);
+  try {
+    return migrateConversationGroupAgentMarks(db);
+  } finally {
+    db.close();
+  }
+}
+
+const isMain = process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url);
+if (isMain) {
+  const dbPath = process.argv[2] ? path.resolve(process.argv[2]) : defaultDbPath();
+  try {
+    const result = migrate(dbPath);
+    console.log(`Migration 0021 on ${dbPath}`);
+    console.log(result.applied
+      ? `  group agent marks: columns added ${result.columnsAdded}`
+      : '  skipped: nothing to change');
+    process.exit(0);
+  } catch (err) {
+    console.error(`Migration 0021 failed: ${err?.message || err}`);
+    process.exit(1);
+  }
+}

package/server/migrations/0022-relay-schedules.mjs

@@ -0,0 +1,142 @@
+'use strict';
+
+/**
+ * Migration: relay schedules (services/relay-schedule-service.mjs).
+ *
+ * `relay_schedules`: one row per schedule an agent set with remote_relay's
+ * `schedule`.
+ *
+ * - `conversation_id`: the session the prompt goes to.
+ * - `created_by_conversation_id`: the conversation whose agent set it (the
+ *   same one for a schedule of its own).
+ * - `at`: the first time asked for, or NULL; `every_minutes`: the interval
+ *   of a repeating schedule, or NULL; `once`: 1 when it ends after firing.
+ * - `next_fire_at`: when it fires next. Written in the same transaction as
+ *   the queue row a firing creates, so a restart neither loses a firing nor
+ *   repeats it; the timers are rebuilt from it at boot.
+ * - `last_fired_at`, `fired_count`, `last_message_id` (the message its last
+ *   firing queued: a repeat waits while that one is still pending),
+ *   `skipped_count`.
+ * - `origin_json`: the provenance its messages carry (the turn that set it,
+ *   with that turn's hops), so a schedule cannot reset the hop count;
+ *   NULL when a user's own turn set it for its own conversation.
+ * - `held_since`: a firing into another session waits for the user (the
+ *   agents' loop guard of the conversation that set it is used up).
+ * - `ended_at`, `end_reason`: unscheduled, fired (once), archived, deleted.
+ *
+ * Additive and idempotent. Safe to run on every boot.
+ *
+ * Usage: node server/migrations/0022-relay-schedules.mjs [path/to/copilot.db]
+ */
+
+import { fileURLToPath } from 'url';
+import path from 'path';
+import process from 'process';
+import Database from 'better-sqlite3';
+
+export const RELAY_SCHEDULE_COLUMNS = Object.freeze([
+  'id',
+  'conversation_id',
+  'created_by_conversation_id',
+  'title',
+  'text',
+  'at',
+  'every_minutes',
+  'once',
+  'next_fire_at',
+  'last_fired_at',
+  'fired_count',
+  'skipped_count',
+  'last_message_id',
+  'created_at',
+  'ended_at',
+  'end_reason',
+  'origin_json',
+  'held_since',
+]);
+
+// Added after the table's first form: added by ALTER where it lacks them.
+const LATER_COLUMNS = Object.freeze([['origin_json', 'TEXT'], ['held_since', 'TEXT']]);
+
+function tableExists(db, name) {
+  return !!db
+    .prepare(`SELECT name FROM sqlite_master WHERE type = 'table' AND name = ?`)
+    .get(name);
+}
+
+/** What keeps the service from using the table: '' when nothing does. */
+export function relaySchedulesTableProblem(db) {
+  if (!tableExists(db, 'relay_schedules')) return 'no relay_schedules table';
+  const present = new Set(db.prepare(`PRAGMA table_info(relay_schedules)`).all().map((column) => column.name));
+  const missing = RELAY_SCHEDULE_COLUMNS.filter((name) => !present.has(name));
+  return missing.length ? `relay_schedules lacks ${missing.join(', ')}` : '';
+}
+
+export function migrateRelaySchedules(db) {
+  let tablesAdded = 0;
+  if (!tableExists(db, 'relay_schedules')) {
+    db.exec(`
+      CREATE TABLE relay_schedules (
+        id                          TEXT PRIMARY KEY,
+        conversation_id             TEXT NOT NULL,
+        created_by_conversation_id  TEXT NOT NULL,
+        title                       TEXT,
+        text                        TEXT NOT NULL,
+        at                          TEXT,
+        every_minutes               INTEGER CHECK (every_minutes IS NULL OR every_minutes > 0),
+        once                        INTEGER NOT NULL DEFAULT 1 CHECK (once IN (0, 1)),
+        next_fire_at                TEXT,
+        last_fired_at               TEXT,
+        fired_count                 INTEGER NOT NULL DEFAULT 0,
+        skipped_count               INTEGER NOT NULL DEFAULT 0,
+        last_message_id             TEXT,
+        created_at                  TEXT NOT NULL,
+        ended_at                    TEXT,
+        end_reason                  TEXT,
+        origin_json                 TEXT,
+        held_since                  TEXT,
+        CHECK (once = 1 OR every_minutes IS NOT NULL)
+      )
+    `);
+    tablesAdded += 1;
+  }
+  const present = new Set(db.prepare(`PRAGMA table_info(relay_schedules)`).all().map((column) => column.name));
+  let columnsAdded = 0;
+  for (const [name, type] of LATER_COLUMNS) {
+    if (present.has(name)) continue;
+    db.exec(`ALTER TABLE relay_schedules ADD COLUMN ${name} ${type}`);
+    columnsAdded += 1;
+  }
+  db.exec(`CREATE INDEX IF NOT EXISTS idx_relay_schedules_active ON relay_schedules(ended_at, next_fire_at)`);
+  db.exec(`CREATE INDEX IF NOT EXISTS idx_relay_schedules_conversation ON relay_schedules(conversation_id, ended_at)`);
+  db.exec(`CREATE INDEX IF NOT EXISTS idx_relay_schedules_creator ON relay_schedules(created_by_conversation_id, ended_at)`);
+  return { applied: tablesAdded > 0 || columnsAdded > 0, tablesAdded, columnsAdded };
+}
+
+function defaultDbPath() {
+  const here = path.dirname(fileURLToPath(import.meta.url));
+  return path.resolve(here, '..', 'data', 'copilot.db');
+}
+
+export function migrate(dbPath, options = {}) {
+  const db = new Database(dbPath, options);
+  try {
+    return migrateRelaySchedules(db);
+  } finally {
+    db.close();
+  }
+}
+
+const isMain = process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url);
+if (isMain) {
+  const dbPath = process.argv[2] ? path.resolve(process.argv[2]) : defaultDbPath();
+  try {
+    const result = migrate(dbPath);
+    console.log(`Migration 0022 on ${dbPath}`);
+    console.log(result.applied ? `  relay schedules: tables added ${result.tablesAdded}, columns added ${result.columnsAdded}` : '  skipped: nothing to change');
+    process.exit(0);
+  } catch (err) {
+    console.error(`Migration 0022 failed: ${err?.message || err}`);
+    process.exit(1);
+  }
+}