omp-conductor 0.13.0 → 0.14.0

package/src/plugin.ts

@@ -83,10 +83,14 @@ import {
   DEFAULT_CAPS,
   DRAFT_POLICIES,
   RELEASE_REQUIREMENTS,
+  INTERRUPT_CATEGORIES,
   RELEASE_SHAPES,
+  WEEKDAYS,
   type Caps,
   type ConductorConfig,
   type OrchestratorMode,
+  type InterruptCategory,
+  type Weekday,
   type ProjectConfig,
   type ProjectPolicy,
   type ReleaseRequirement,
@@ -230,6 +234,7 @@ async function askValid(
   throw new Cancelled();
 }
 
+
 /** A cap. Unparseable input keeps the current value rather than writing a NaN
  *  the validator would later reject — the operator sees why, immediately. */
 async function askNumber(ctx: CommandContext, title: string, fallback: number): Promise<number> {
@@ -924,22 +929,143 @@ const askEscalation: AreaAsker = async (ctx, a) => {
   return next;
 };
 
-/** How loud the orchestrator is when nobody asked it anything. */
+/** How loud the orchestrator is and when the operator permits interruptions. */
 const askReporting: AreaAsker = async (ctx, a) => {
   const reportScope = await askReportScope(ctx, a.reportScope);
-  if (reportScope !== "quiet") return { ...a, reportScope };
-  // `quiet` picks the explicit form, whose only free parameter is when the
-  // daily rollup happens. Blank = whenever the orchestrator composes it.
-  const at = await ctx.ui.input(
-    "Daily rollup time, 24h HH:MM (blank = whenever the orchestrator composes it):",
-    a.quietDigestAt,
+  const continuous = "Continuous (24-hour interrupts)";
+  const weekly = "Weekly availability window";
+  const mode = await ctx.ui.select(
+    "Operator availability",
+    [
+      {
+        label: continuous,
+        description: "preserve legacy behavior: configured interrupt categories may page at any hour",
+      },
+      {
+        label: weekly,
+        description: "hold non-bypass interruptions outside selected local working hours",
+      },
+    ],
+    { initialIndex: a.availability === undefined ? 0 : 1 },
   );
-  const trimmed = at?.trim() ?? "";
-  if (trimmed !== "" && !/^([01]\d|2[0-3]):[0-5]\d$/.test(trimmed)) {
-    ctx.ui.notify(`"${trimmed}" is not a 24h HH:MM time — leaving the digest model-timed.`, "warning");
-    return { ...a, reportScope };
+  if (mode === undefined) throw new Cancelled();
+
+  const next: SetupAnswers = { ...a, reportScope };
+  delete next.preservedReporting;
+  delete next.availability;
+  const applyDigestSchedule = (raw: string): SetupAnswers => {
+    const updated = { ...next };
+    delete updated.dailyDigestAt;
+    const value = raw.trim().toLowerCase();
+    if (value === "per-tick") {
+      updated.digestCadence = "per-tick";
+    } else if (value === "off" || value === "disabled" || value === "none") {
+      updated.digestCadence = "none";
+    } else if (value === "model-timed" || value === "daily") {
+      updated.digestCadence = "daily";
+    } else {
+      updated.digestCadence = "daily";
+      updated.dailyDigestAt = raw;
+    }
+    return updated;
+  };
+  const askDigestSchedule = async (fallback: string): Promise<SetupAnswers> => {
+    const shown =
+      a.digestCadence === "per-tick"
+        ? "per-tick"
+        : a.digestCadence === "none"
+          ? "off"
+          : a.dailyDigestAt ?? (a.digestCadence === "daily" ? "model-timed" : fallback);
+    const schedule = await askValid(
+      ctx,
+      'Daily rollup time in that timezone / digest cadence ("per-tick", "model-timed", "off", or 24h HH:MM)',
+      shown,
+      (value) =>
+        ["per-tick", "model-timed", "daily", "none", "off", "disabled"].includes(
+          value.toLowerCase(),
+        ) || /^([01]\d|2[0-3]):[0-5]\d$/.test(value)
+          ? undefined
+          : 'Use "per-tick", "model-timed", "off", or a 24h HH:MM time.',
+    );
+    return applyDigestSchedule(schedule);
+  };
+
+  if (mode !== weekly) {
+    if (mode !== continuous) {
+      ctx.ui.notify(`Unrecognised availability choice "${mode}" — keeping 24-hour interrupts.`, "warning");
+    }
+    if (reportScope !== "quiet") return next;
+    return await askDigestSchedule("model-timed");
   }
-  return { ...a, reportScope, ...(trimmed === "" ? {} : { quietDigestAt: trimmed }) };
+
+  const defaultZone =
+    a.reportingTimezone ?? Intl.DateTimeFormat().resolvedOptions().timeZone ?? "UTC";
+  const reportingTimezone = await askValid(
+    ctx,
+    "Operator timezone (IANA, for example Europe/London)",
+    defaultZone,
+    (value) => {
+      try {
+        new Intl.DateTimeFormat("en", { timeZone: value }).format();
+        return undefined;
+      } catch {
+        return `"${value}" is not a known IANA timezone.`;
+      }
+    },
+  );
+  const daysText = await askValid(
+    ctx,
+    "Working weekdays (comma-separated: mon,tue,wed,thu,fri,sat,sun)",
+    a.availability?.days.join(",") ?? "mon,tue,wed,thu,fri",
+    (value) => {
+      const days = value.split(",").map((day) => day.trim().toLowerCase());
+      if (days.length === 0 || days.some((day) => !WEEKDAYS.includes(day as Weekday))) {
+        return `Use only: ${WEEKDAYS.join(",")}.`;
+      }
+      return new Set(days).size === days.length ? undefined : "List each weekday only once.";
+    },
+  );
+  const days = daysText.split(",").map((day) => day.trim().toLowerCase() as Weekday);
+  const start = await askValid(
+    ctx,
+    "Availability starts (24h HH:MM)",
+    a.availability?.start ?? "09:00",
+    (value) => (/^([01]\d|2[0-3]):[0-5]\d$/.test(value) ? undefined : "Use 24h HH:MM."),
+  );
+  const end = await askValid(
+    ctx,
+    "Availability ends (24h HH:MM)",
+    a.availability?.end ?? "17:00",
+    (value) =>
+      !/^([01]\d|2[0-3]):[0-5]\d$/.test(value)
+        ? "Use 24h HH:MM."
+        : value === start
+          ? "Start and end must differ."
+          : undefined,
+  );
+  const bypassText = await askValid(
+    ctx,
+    `Quiet-hours bypass categories (comma-separated; "none" = none; choices: ${INTERRUPT_CATEGORIES.join(",")})`,
+    a.availability === undefined ? "fleet-stopped" : a.availability.bypass.join(",") || "none",
+    (value) => {
+      if (value.toLowerCase() === "none") return undefined;
+      const categories = value.split(",").map((category) => category.trim().toLowerCase());
+      if (categories.some((category) => !INTERRUPT_CATEGORIES.includes(category as InterruptCategory))) {
+        return `Use only: ${INTERRUPT_CATEGORIES.join(",")}, or "none".`;
+      }
+      return new Set(categories).size === categories.length ? undefined : "List each category only once.";
+    },
+  );
+  const bypass =
+    bypassText.toLowerCase() === "none"
+      ? []
+      : bypassText.split(",").map((category) => category.trim().toLowerCase() as InterruptCategory);
+  const scheduled = await askDigestSchedule(end);
+  return {
+    ...scheduled,
+    reportingTimezone,
+    availability: { days, start, end, bypass },
+  };
 };
 
 /** The operator's own brief. Asked last in the full interview, because the

package/src/reports.ts

@@ -36,9 +36,21 @@
  * conclusion leaves something for the next pass to pick up.
  */
 
+import { availabilityDisposition, interruptDisposition } from "./availability.ts";
 import { readTelegramToken, sendTelegram, TelegramSendError } from "./escalate.ts";
 import { localDayKey } from "./digest-schedule.ts";
-import type { Escalation, ProjectConfig, ReportRecord, Store } from "./types.ts";
+import {
+  DIGEST_BACKLOG_LIMIT,
+  INTERRUPT_CATEGORIES,
+  type DigestBacklog,
+  type Escalation,
+  type HeldNotice,
+  type InterruptCategory,
+  type ProjectConfig,
+  type ReportEnqueue,
+  type ReportRecord,
+  type Store,
+} from "./types.ts";
 
 /**
  * Attempts before a report is written off. Six attempts across the backoff
@@ -85,6 +97,8 @@ export type ReportSend = (text: string) => Promise<number | undefined>;
 /** What one pass did, by report id. Returned for the daemon's log and the tests. */
 export interface ReportDeliveryPass {
   delivered: string[];
+  /** Material reports preserved without sending after policy or availability changed. */
+  deferred: string[];
   /** Known-failed, back in `pending` behind a backoff. */
   requeued: string[];
   /** The attempt ended without an answer. Left `sending` and flagged as a
@@ -108,7 +122,8 @@ export interface ReportOutbox {
 }
 
 export interface ReportOutboxDeps {
-  project: ProjectConfig;
+  /** A provider lets a resident daemon apply config edits at the next tick. */
+  project: ProjectConfig | (() => ProjectConfig);
   store: Store;
   /** A report nobody can deliver escalates through this. Optional so a unit
    *  test can exercise delivery without wiring an escalator. */
@@ -116,6 +131,8 @@ export interface ReportOutboxDeps {
   send?: ReportSend;
   now?: () => number;
   log?: (msg: string) => void;
+  /** False while the resident daemon cannot validate live delivery policy. */
+  deliveryAllowed?: () => boolean;
 }
 
 /**
@@ -200,6 +217,20 @@ export function formatOpenReports(
   return lines;
 }
 
+/** Durable rows still owed to a future digest. Always rendered in `status`: a
+ * quiet line proves the accumulator is empty, while a non-zero line makes loss
+ * or backlog visible without asking the session what it remembers. */
+export function formatDigestBacklog(backlog: DigestBacklog, now: number = Date.now()): string[] {
+  const age = (at: number | undefined): string =>
+    at === undefined ? "" : ` (oldest ${humanAge(Math.max(0, now - at))})`;
+  return [
+    "",
+    "digest backlog",
+    `  material events    ${backlog.materialCount}${age(backlog.materialOldestAt)}`,
+    `  held escalations   ${backlog.heldNoticeCount}${age(backlog.heldNoticeOldestAt)}`,
+  ];
+}
+
 function openReportDetail(r: ReportRecord, now: number): string {
   const flat = r.lastError?.replace(/\s+/g, " ").trim() ?? "";
   const error =
@@ -257,10 +288,115 @@ export function telegramReportSend(p: ProjectConfig): ReportSend {
   };
 }
 
+/** Keep the mechanical catch-up comfortably inside Telegram's report wrapper. */
+const AVAILABILITY_REPORT_BODY_LIMIT = 3_200;
+const AVAILABILITY_REPORT_KEY_PREFIX = "availability/";
+
+interface AvailabilityReportMarker {
+  categories: InterruptCategory[];
+  urgent: boolean;
+}
+
+function availabilityReportMarker(report: ReportRecord): AvailabilityReportMarker | undefined {
+  const key = report.dedupeKey;
+  if (key === undefined || !key.startsWith(AVAILABILITY_REPORT_KEY_PREFIX)) return undefined;
+  const parts = key.slice(AVAILABILITY_REPORT_KEY_PREFIX.length).split("/");
+  const urgent = parts[0] === "urgent";
+  const encoded = (urgent ? parts[1] : parts[0]) ?? "";
+  return {
+    urgent,
+    categories: encoded
+      .split(",")
+      .filter((category): category is InterruptCategory =>
+        INTERRUPT_CATEGORIES.includes(category as InterruptCategory),
+      ),
+  };
+}
+
+function availabilityNoticeLine(notice: HeldNotice): string {
+  const flat = (text: string, limit: number): string => {
+    const value = text.replace(/\s+/g, " ").trim();
+    return value.length <= limit ? value : `${value.slice(0, limit - 1)}…`;
+  };
+  return (
+    `- [${notice.category}] ${flat(notice.summary, 180)} ` +
+    `(${new Date(notice.createdAt).toISOString()}) — ${flat(notice.detail, 240)}`
+  );
+}
+
+/**
+ * Hand availability-held notices to the existing durable outbox when the live
+ * policy permits them again. Association and report creation are one SQLite
+ * transaction, so daemon downtime or a send failure cannot lose a notice.
+ */
+export function enqueueAvailableHeldNotices(
+  project: ProjectConfig,
+  store: Store,
+  now: number,
+): ReportEnqueue | undefined {
+  // The Store arbitrates the due-digest lease and this catch-up in the same
+  // SQLite transaction. A preflight here would reopen the snapshot race.
+  const categories = INTERRUPT_CATEGORIES.filter(
+    (category) => interruptDisposition(project.reporting, category, now) === "interrupt",
+  );
+  const urgentCategories = INTERRUPT_CATEGORIES.filter(
+    (category) =>
+      availabilityDisposition(project.reporting?.availability, category, now) === "interrupt",
+  );
+  const urgent = store.undigestedNotices(
+    project.name,
+    DIGEST_BACKLOG_LIMIT,
+    true,
+    urgentCategories,
+    true,
+  );
+  const eligible =
+    urgent.length > 0
+      ? urgent
+      : store.undigestedNotices(
+          project.name,
+          DIGEST_BACKLOG_LIMIT,
+          true,
+          categories,
+          false,
+        );
+  if (eligible.length === 0) return undefined;
+
+  const lines = [
+    "Working-hours catch-up",
+    "These interruptions were held durably while the operator was outside the configured availability window:",
+  ];
+  const selected: HeldNotice[] = [];
+  for (const notice of eligible) {
+    const line = availabilityNoticeLine(notice);
+    const next = [...lines, line].join("\n");
+    if (selected.length > 0 && next.length > AVAILABILITY_REPORT_BODY_LIMIT) break;
+    lines.push(line);
+    selected.push(notice);
+  }
+
+  const selectedCategories = INTERRUPT_CATEGORIES.filter((category) =>
+    selected.some((notice) => notice.category === category),
+  );
+  const urgentMarker = selected[0]?.urgent === true ? "urgent/" : "";
+  return store.enqueueAvailabilityReport(
+    {
+      project: project.name,
+      kind: "digest",
+      body: lines.join("\n"),
+      dedupeKey: `${AVAILABILITY_REPORT_KEY_PREFIX}${urgentMarker}${selectedCategories.join(",")}/${selected[0]!.id}`,
+      at: now,
+    },
+    selected.map((notice) => notice.id),
+  );
+}
+
 export function createReportOutbox(deps: ReportOutboxDeps): ReportOutbox {
-  const { project, store } = deps;
+  const { store } = deps;
+  const currentProject =
+    typeof deps.project === "function" ? deps.project : (): ProjectConfig => deps.project as ProjectConfig;
   const now = deps.now ?? Date.now;
-  const send = deps.send ?? telegramReportSend(project);
+  const injectedSend = deps.send;
   const log = deps.log ?? ((): void => {});
 
   /**
@@ -279,6 +415,7 @@ export function createReportOutbox(deps: ReportOutboxDeps): ReportOutbox {
    * undeliverable report pages exactly once and never every five minutes.
    */
   const pageUndeliverable = async (r: ReportRecord, error: string): Promise<void> => {
+    const project = currentProject();
     if (deps.escalate === undefined) return;
     try {
       await deps.escalate({
@@ -318,6 +455,64 @@ export function createReportOutbox(deps: ReportOutboxDeps): ReportOutbox {
   };
 
   const attempt = async (r: ReportRecord, pass: ReportDeliveryPass): Promise<void> => {
+    const project = currentProject();
+    if (deps.deliveryAllowed?.() === false) {
+      pass.deferred.push(r.id);
+      return;
+    }
+    const availabilityMarker = availabilityReportMarker(r);
+    if (availabilityMarker !== undefined) {
+      if (availabilityMarker.categories.length === 0) {
+        pass.deferred.push(r.id);
+        log(`availability catch-up ${r.id} has no valid category marker and was held fail-closed`);
+        return;
+      }
+      const dispositions = availabilityMarker.categories.map((category) =>
+        availabilityMarker.urgent
+          ? availabilityDisposition(project.reporting?.availability, category, now())
+          : interruptDisposition(project.reporting, category, now()),
+      );
+      if (dispositions.some((disposition) => disposition !== "interrupt")) {
+        if (store.releasePendingAvailabilityReport(r.id, project.name, r.ambiguous)) {
+          const reason = dispositions.includes("digest")
+            ? "reporting policy changed"
+            : "the availability window closed";
+          log(`availability catch-up ${r.id} returned to the digest because ${reason}`);
+        }
+        pass.deferred.push(r.id);
+        return;
+      }
+    }
+    if (r.kind === "material") {
+      const at = now();
+      const disposition = interruptDisposition(project.reporting, "material", at);
+      if (disposition !== "interrupt") {
+        const firstLine = r.body.split("\n", 1)[0]!;
+        const deferred = store.deferPendingReportToNotice(r.id, {
+          id: r.id,
+          project: project.name,
+          category: "material",
+          summary: (
+            r.ambiguous ? `POSSIBLE REPEAT of report ${r.id}: ${firstLine}` : firstLine
+          ).slice(0, 240),
+          detail: r.ambiguous
+            ? `This report may already have reached Telegram before its outcome was lost.\n\n${r.body}`
+            : r.body,
+          createdAt: at,
+          ...(disposition === "availability" ? { releaseOnAvailable: true } : {}),
+        });
+        if (deferred) {
+          pass.deferred.push(r.id);
+          log(
+            `report ${r.id} preserved for ${
+              disposition === "availability" ? "the next availability window" : "a digest"
+            } after reporting policy changed`,
+          );
+          return;
+        }
+      }
+    }
+    const send = injectedSend ?? telegramReportSend(project);
     const attemptId = crypto.randomUUID();
     // Losing this race is ordinary: another pass, or another daemon, already
     // owns the attempt. Returning is what keeps one report from being in flight
@@ -400,12 +595,14 @@ export function createReportOutbox(deps: ReportOutboxDeps): ReportOutbox {
 
   return {
     recover(staleAt: number): ReportRecord[] {
-      return store.recoverSendingReports(project.name, staleAt, now());
+      return store.recoverSendingReports(currentProject().name, staleAt, now());
     },
 
     async deliverDue(): Promise<ReportDeliveryPass> {
+      const project = currentProject();
       const pass: ReportDeliveryPass = {
         delivered: [],
+        deferred: [],
         requeued: [],
         uncertain: [],
         failed: [],