@staix/agent-hub 0.24.0 → 0.25.0

package/src/hub/schedules.ts

@@ -15,7 +15,12 @@ export const SCHEDULE_MARKER = "Schedule key: ";
 
 export interface ScheduleEntry {
   id: string;
-  every: string;
+  /** Exactly one of `every` and `cron` (#1017). */
+  every?: string;
+  /** The five cron fields, single-spaced (`parseCron` checked them). */
+  cron?: string;
+  /** An IANA zone for `cron`; without it the machine's own zone (`scheduleZone`). */
+  tz?: string;
   class: string;
   title: string;
   detail?: string;
@@ -26,7 +31,7 @@ export interface ScheduleEntry {
 
 /** The source id form of `src/hub/sources.ts` (`validSourceId`), repeated here because that module reaches the file system and the converters and this one is bundled into the Claude channel server through the config schema; `test/schedules.test.ts` pins that the two agree. */
 export const SOURCE_ID = /^src:[0-9a-f]{16}$/;
-const ID = /^[a-z0-9][a-z0-9_-]{0,47}$/, PEER = /^[a-z][a-z0-9-]{0,31}$/, CLASS = /^[a-z][a-z0-9_]{0,47}$/, KEYS = new Set(["id", "every", "cron", "class", "title", "detail", "sources", "owner", "queue"]);
+const ID = /^[a-z0-9][a-z0-9_-]{0,47}$/, PEER = /^[a-z][a-z0-9-]{0,31}$/, CLASS = /^[a-z][a-z0-9_]{0,47}$/, KEYS = new Set(["id", "every", "cron", "tz", "class", "title", "detail", "sources", "owner", "queue"]);
 const control = /[\x00-\x1f\x7f]/;
 
 /** `<n>m|h|d` to milliseconds; a thrown reason otherwise. The 15-minute floor keeps a typo from flooding the board. */
@@ -39,6 +44,185 @@ export function parseEvery(value: unknown): number {
   return ms;
 }
 
+// agent-hub #1017: calendar-anchored schedules. Spec: "Calendar-anchored schedules (#1017)". Pure: a cron expression and a zone in, instants out, on `Intl` and `Date` only (zero runtime
+// dependencies). Every function takes the time it works from, so a test pins a fixed clock.
+
+/** The five fields, each as the sorted values it allows. `domStar` and `dowStar`: the field began with `*`, which the day rule below reads. */
+export interface CronSpec { minutes: number[]; hours: number[]; doms: number[]; months: number[]; dows: number[]; domStar: boolean; dowStar: boolean }
+const CRON_FIELDS = [{ name: "minute", min: 0, max: 59 }, { name: "hour", min: 0, max: 23 }, { name: "day of month", min: 1, max: 31 }, { name: "month", min: 1, max: 12 }, { name: "day of week", min: 0, max: 7 }] as const;
+export const MAX_CRON_LENGTH = 100;
+/**
+ * One Gregorian cycle: the calendar, and so every day-of-month, month and weekday pattern, repeats exactly every 146097 days (400 years, a whole number of weeks). Scanning that far makes
+ * both questions complete: an expression that never fires has no matching day in it, and one that fires at all fires inside it from any start (a Feb 29 that is a Sunday recurs
+ * 28 to 40 years apart). The cost is only paid by a sparse expression: a common one stops at its first match.
+ */
+const CRON_HORIZON_DAYS = 146_097;
+const DAY_MS = 86_400_000, MIN_MS = 60_000;
+
+function cronField(text: string, name: string, min: number, max: number): number[] {
+  const values = new Set<number>();
+  for (const part of text.split(",")) {
+    const match = /^(?:(\*)|(\d{1,2})(?:-(\d{1,2}))?)(?:\/(\d{1,2}))?$/.exec(part);
+    if (!match || (match[2] !== undefined && match[3] === undefined && match[4] !== undefined)) throw new Error(`cron ${name} must be numbers, ranges (a-b), lists (a,b) and steps (*/n or a-b/n)`);
+    const from = match[1] ? min : Number(match[2]), to = match[1] ? max : match[3] !== undefined ? Number(match[3]) : from, step = match[4] === undefined ? 1 : Number(match[4]);
+    if (from < min || to > max || from > to) throw new Error(`cron ${name} is ${min} to ${max}, and a range runs upward`);
+    if (step < 1) throw new Error(`cron ${name} step must be at least 1`);
+    for (let value = from; value <= to; value += step) values.add(name === "day of week" && value === 7 ? 0 : value);
+  }
+  return [...values].sort((a, b) => a - b);
+}
+
+/**
+ * The standard five fields (minute, hour, day of month, month, day of week): numbers, lists, ranges and steps; day of week 0 and 7 are Sunday. No seconds, no year, no `@` macro, no names.
+ * A day matches when both day fields are restricted and EITHER matches, or when one of them begins with `*` and BOTH match (the classic cron rule); month always has to match.
+ */
+export function parseCron(expression: unknown): CronSpec {
+  if (typeof expression !== "string" || !expression.trim()) throw new Error("cron is five fields: minute hour day-of-month month day-of-week");
+  if (expression.length > MAX_CRON_LENGTH || /[^\x20-\x7e]/.test(expression)) throw new Error(`cron is at most ${MAX_CRON_LENGTH} printable characters`);
+  if (expression.trim().startsWith("@")) throw new Error("cron takes the five fields, not an @ macro");
+  const fields = expression.trim().split(/\s+/);
+  if (fields.length !== 5) throw new Error(`cron is exactly five fields (minute hour day-of-month month day-of-week), not ${fields.length}; seconds and a year are not supported`);
+  const [minutes, hours, doms, months, dows] = CRON_FIELDS.map((field, index) => cronField(fields[index]!, field.name, field.min, field.max)) as [number[], number[], number[], number[], number[]];
+  return { minutes, hours, doms, months, dows, domStar: fields[2]!.startsWith("*"), dowStar: fields[4]!.startsWith("*") };
+}
+/** The expression as stored: the same five fields, single-spaced. */
+export const cronText = (expression: string): string => expression.trim().split(/\s+/).join(" ");
+
+function dayMatches(spec: CronSpec, dayMs: number): boolean {
+  const date = new Date(dayMs);
+  if (!spec.months.includes(date.getUTCMonth() + 1)) return false;
+  const dom = spec.doms.includes(date.getUTCDate()), dow = spec.dows.includes(date.getUTCDay());
+  return spec.domStar || spec.dowStar ? dom && dow : dom || dow;
+}
+
+/**
+ * The smallest gap, in minutes, between two fires of the expression on the calendar itself (a wall clock with no zone), or undefined when no day of a full 400-year Gregorian cycle matches (`0 0 31 2 *`).
+ * Daylight saving can still move two fires closer on its one change day (a skipped time runs at the first valid minute); a schedule proposes at most one task per pass and none while its
+ * previous task is open, so that costs no flood.
+ */
+export function cronMinGapMinutes(spec: CronSpec): number | undefined {
+  const times = spec.hours.flatMap(hour => spec.minutes.map(minute => hour * 60 + minute));
+  let gap = Infinity;
+  for (let i = 1; i < times.length; i++) gap = Math.min(gap, times[i]! - times[i - 1]!);
+  const start = Date.UTC(2024, 0, 1);
+  let any = false, consecutive = false, before = false;
+  for (let day = 0; day < CRON_HORIZON_DAYS; day++) {
+    const now = dayMatches(spec, start + day * DAY_MS);
+    any ||= now;
+    if (now && before) consecutive = true;
+    before = now;
+  }
+  if (!any) return undefined;
+  return Math.min(gap, consecutive ? 1440 - times[times.length - 1]! + times[0]! : Infinity);
+}
+
+const zoneFormats = new Map<string, Intl.DateTimeFormat>();
+function zoneFormat(zone: string): Intl.DateTimeFormat {
+  let format = zoneFormats.get(zone);
+  if (!format) {
+    format = new Intl.DateTimeFormat("en-US", { timeZone: zone, hourCycle: "h23", year: "numeric", month: "numeric", day: "numeric", hour: "numeric", minute: "numeric", second: "numeric" });
+    if (zoneFormats.size >= 64) zoneFormats.clear();
+    zoneFormats.set(zone, format);
+  }
+  return format;
+}
+/** An IANA zone name the runtime knows, as it spells it (`utc` is `UTC`), or a thrown reason. */
+export function checkZone(value: unknown): string {
+  if (typeof value !== "string" || value.length > 64 || !/^[A-Za-z][A-Za-z0-9_+-]*(?:\/[A-Za-z0-9_+-]+)*$/.test(value)) throw new Error("tz is an IANA zone name such as Asia/Seoul or America/New_York");
+  try { return zoneFormat(value).resolvedOptions().timeZone; } catch { throw new Error("tz is not a zone this machine knows; use an IANA name such as Asia/Seoul or America/New_York"); }
+}
+/** The zone a schedule's `cron` is read in: its `tz`, else this machine's own. */
+export function scheduleZone(entry: Pick<ScheduleEntry, "tz">): string {
+  if (entry.tz) return entry.tz;
+  try { return new Intl.DateTimeFormat().resolvedOptions().timeZone || "UTC"; } catch { return "UTC"; }
+}
+
+/** The wall clock of an instant in a zone, as milliseconds on a zone-less calendar (the calendar read as UTC). */
+function wallOf(zone: string, instant: number): number {
+  const parts: Record<string, number> = {};
+  for (const part of zoneFormat(zone).formatToParts(instant)) if (part.type !== "literal") parts[part.type] = Number(part.value);
+  return Date.UTC(parts.year!, parts.month! - 1, parts.day!, parts.hour! % 24, parts.minute!, parts.second!);
+}
+/**
+ * The instant a wall-clock minute happens in a zone. A time that happens twice (the clock went back) is its first occurrence, so a repeated time runs once; a time that never happens
+ * (the clock jumped forward) is the first minute that does, so a skipped time still runs.
+ */
+function instantOf(zone: string, wall: number): number {
+  const offset = (instant: number) => wallOf(zone, instant) - Math.floor(instant / 1000) * 1000;
+  const tried = new Set<number>(), found: number[] = [];
+  for (const guess of [offset(wall - DAY_MS), offset(wall + DAY_MS), offset(wall)]) {
+    if (tried.has(guess)) continue;
+    tried.add(guess);
+    if (wallOf(zone, wall - guess) === wall) found.push(wall - guess);
+  }
+  if (found.length) return Math.min(...found);
+  // A gap: the first minute whose wall clock has reached the skipped time. No zone's offset moves by 30 hours, so this window holds the one change.
+  let low = Math.floor((wall - 30 * 3_600_000) / MIN_MS), high = Math.ceil((wall + 30 * 3_600_000) / MIN_MS);
+  while (high - low > 1) {
+    const middle = Math.floor((low + high) / 2);
+    if (wallOf(zone, middle * MIN_MS) >= wall) high = middle; else low = middle;
+  }
+  return high * MIN_MS;
+}
+
+/** The first wall-clock minute strictly after `wall` that the expression allows, or undefined when no day of a full cycle matches. */
+function nextWall(spec: CronSpec, wall: number): number | undefined {
+  const from = wall - (wall % MIN_MS) + MIN_MS, firstDay = from - (from % DAY_MS), floor = (from - firstDay) / MIN_MS;
+  for (let day = 0; day < CRON_HORIZON_DAYS; day++) {
+    const dayMs = firstDay + day * DAY_MS;
+    if (!dayMatches(spec, dayMs)) continue;
+    for (const hour of spec.hours) for (const minute of spec.minutes) if (hour * 60 + minute >= (day === 0 ? floor : 0)) return dayMs + (hour * 60 + minute) * MIN_MS;
+  }
+  return undefined;
+}
+
+/**
+ * The next fire strictly after `after` (epoch ms), or undefined when none exists (no day of a full 400-year cycle matches). Fires are found on the zone's wall clock and then placed on the timeline by
+ * `instantOf`: a repeated wall time fires once, and a fire the clock skipped fires at the first valid minute.
+ */
+export function cronNext(spec: CronSpec, zone: string, after: number): number | undefined {
+  let wall = wallOf(zone, after);
+  wall -= wall % MIN_MS;
+  for (let guard = 0; guard < 2000; guard++) {
+    const next = nextWall(spec, wall);
+    if (next === undefined) return undefined;
+    const instant = instantOf(zone, next);
+    if (instant > after) return instant;
+    wall = next;
+  }
+  return undefined;
+}
+
+/** `YYYY-MM-DD HH:mm` in a zone: how a person reads the next run of a calendar schedule. */
+export function formatInZone(instant: number, zone: string): string {
+  const iso = new Date(wallOf(zone, instant)).toISOString();
+  return `${iso.slice(0, 10)} ${iso.slice(11, 16)}`;
+}
+
+/** How a view's period reads: `every 6h`, or `cron 30 7 * * 1-5 (Asia/Seoul)`. */
+export const schedulePeriodText = (view: { every?: string; cron?: string; zone?: string }): string => view.cron !== undefined ? `cron ${view.cron}${view.zone ? ` (${view.zone})` : ""}` : `every ${view.every ?? "?"}`;
+/** An instant as a person reads a schedule's next run: in the zone of a `cron` (`2026-11-02 07:30 Asia/Seoul`), else UTC like every other time in the CLI. */
+export function scheduleWhen(view: { zone?: string }, instant: number): string {
+  if (view.zone) { try { return `${formatInZone(instant, view.zone)} ${view.zone}`; } catch { /* an unknown zone falls through to UTC */ } }
+  return `${new Date(instant).toISOString().replace("T", " ").slice(0, 16)} UTC`;
+}
+
+const parsedCrons = new Map<string, CronSpec>();
+function cronSpec(expression: string): CronSpec {
+  let spec = parsedCrons.get(expression);
+  if (!spec) {
+    spec = parseCron(expression);
+    if (parsedCrons.size >= 256) parsedCrons.clear();
+    parsedCrons.set(expression, spec);
+  }
+  return spec;
+}
+/** The next time a schedule is due, given the start of its period: `every` after the anchor, or the next calendar fire of its `cron` after it. Far in the future when a cron has none. */
+export function scheduleNext(entry: Pick<ScheduleEntry, "every" | "cron" | "tz">, anchor: number): number {
+  if (entry.cron !== undefined) return cronNext(cronSpec(entry.cron), scheduleZone(entry), anchor) ?? Number.MAX_SAFE_INTEGER;
+  return anchor + parseEvery(entry.every);
+}
+
 /** The checked `schedules` list. Every refusal names the entry; nothing here reads the board, a clock or a file. */
 export function schedulesConfig(input: unknown): ScheduleEntry[] {
   if (input === undefined) return [];
@@ -54,8 +238,21 @@ export function schedulesConfig(input: unknown): ScheduleEntry[] {
     if (typeof row.id !== "string" || !ID.test(row.id)) bad("id is 1 to 48 lower-case letters, digits, - or _");
     if (seen.has(row.id as string)) bad("duplicate id");
     seen.add(row.id as string);
-    if (row.cron !== undefined) bad("cron not supported yet; use every");
-    try { parseEvery(row.every); } catch (error) { bad((error as Error).message); }
+    if (row.every !== undefined && row.cron !== undefined) bad("give every or cron, not both");
+    if (row.every === undefined && row.cron === undefined) bad("every must be <n>m, <n>h or <n>d, or give cron (five fields)");
+    if (row.tz !== undefined && row.cron === undefined) bad("tz applies to cron only");
+    let cron: string | undefined, tz: string | undefined;
+    if (row.cron !== undefined) {
+      try {
+        const spec = parseCron(row.cron), gap = cronMinGapMinutes(spec);
+        if (gap === undefined) bad("cron never fires: no calendar day matches it");
+        if (gap! < MIN_EVERY_MS / MIN_MS) bad(`cron can fire every ${gap} minute${gap === 1 ? "" : "s"}; the minimum is ${MIN_EVERY_MS / MIN_MS} minutes`);
+        cron = cronText(row.cron as string);
+        if (row.tz !== undefined) tz = checkZone(row.tz);
+      } catch (error) { bad((error as Error).message.replace(/^schedules[.[][^:]*: /, "")); }
+    } else {
+      try { parseEvery(row.every); } catch (error) { bad((error as Error).message); }
+    }
     if (typeof row.class !== "string" || !CLASS.test(row.class)) bad("class is required");
     if (typeof row.title !== "string" || !row.title.trim() || row.title.length > 300 || control.test(row.title)) bad("title is 1 to 300 printable characters on one line");
     if (row.detail !== undefined && (typeof row.detail !== "string" || row.detail.length > MAX_SCHEDULE_DETAIL || /[\x00-\x08\x0b\x0c\x0e-\x1f\x7f]/.test(row.detail))) bad(`detail is text of at most ${MAX_SCHEDULE_DETAIL} characters`);
@@ -65,7 +262,7 @@ export function schedulesConfig(input: unknown): ScheduleEntry[] {
       if (!Array.isArray(row.sources) || row.sources.length > MAX_SCHEDULE_SOURCES || !row.sources.every(id => typeof id === "string" && SOURCE_ID.test(id))) bad(`sources is a list of at most ${MAX_SCHEDULE_SOURCES} source ids (src:<16 hex>)`);
     }
     out.push({
-      id: row.id as string, every: row.every as string, class: row.class as string, title: (row.title as string).replace(/\s+/g, " ").trim(),
+      id: row.id as string, ...(cron !== undefined ? { cron, ...(tz !== undefined ? { tz } : {}) } : { every: row.every as string }), class: row.class as string, title: (row.title as string).replace(/\s+/g, " ").trim(),
       ...(row.detail !== undefined ? { detail: row.detail as string } : {}), ...(row.sources !== undefined ? { sources: [...(row.sources as string[])] } : {}),
       ...(row.owner !== undefined ? { owner: row.owner as string } : {}), queue: (row.queue as "backlog" | "ready" | undefined) ?? "backlog",
     });
@@ -229,7 +426,10 @@ export interface ScheduleRunResult { id: string; outcome: ScheduleOutcome; task?
 export type ScheduleState = "scheduled" | "due" | "waiting" | "held" | "paused";
 export interface ScheduleView {
   id: string;
-  every: string;
+  /** `every` or `cron`, never both; `zone` is the zone a `cron` is read in (its `tz`, else the machine's), so a person reads the next run with it (#1017). */
+  every?: string;
+  cron?: string;
+  zone?: string;
   class: string;
   queue: "backlog" | "ready";
   next: number;
@@ -247,10 +447,10 @@ export interface ScheduleView {
 export function scheduleViews(entries: readonly ScheduleEntry[], rows: readonly ScheduleRow[], now: number, open: ReadonlyMap<string, number>, held: boolean): ScheduleView[] {
   const byId = new Map(rows.map(row => [row.id, row]));
   return entries.map(entry => {
-    const row = byId.get(entry.id), anchor = row?.anchor ?? now, next = anchor + parseEvery(entry.every), openTask = open.get(entry.id);
+    const row = byId.get(entry.id), anchor = row?.anchor ?? now, next = scheduleNext(entry, anchor), openTask = open.get(entry.id);
     const state: ScheduleState = row?.paused ? "paused" : now < next ? "scheduled" : held ? "held" : openTask !== undefined ? "waiting" : "due";
     return {
-      id: entry.id, every: entry.every, class: entry.class, queue: entry.queue, next, state,
+      id: entry.id, ...(entry.cron !== undefined ? { cron: entry.cron, zone: scheduleZone(entry) } : { every: entry.every }), class: entry.class, queue: entry.queue, next, state,
       ...(row?.last_run != null ? { last: row.last_run } : {}), ...(openTask !== undefined ? { task: openTask } : row?.last_task != null ? { task: row.last_task } : {}),
       ...(row?.coalesced ? { coalesced: row.coalesced } : {}), ...(row?.last_error ? { error: row.last_error } : {}),
     };
@@ -259,7 +459,8 @@ export function scheduleViews(entries: readonly ScheduleEntry[], rows: readonly
 
 /** The detail of a scheduled task: the marker line first, then the person's text and the sources it names, all fixed words around config text. */
 export function scheduledDetail(entry: ScheduleEntry): string {
-  return [`${SCHEDULE_MARKER}${entry.id}`, `Scheduled every ${entry.every} by the machine-local schedule "${entry.id}".`, ...(entry.detail ? ["", entry.detail] : []),
+  const when = entry.cron !== undefined ? `on the calendar "${entry.cron}" (${scheduleZone(entry)})` : `every ${entry.every}`;
+  return [`${SCHEDULE_MARKER}${entry.id}`, `Scheduled ${when} by the machine-local schedule "${entry.id}".`, ...(entry.detail ? ["", entry.detail] : []),
     ...(entry.sources?.length ? ["", ...entry.sources.map(id => `Source: ${id}`)] : [])].join("\n");
 }
 

package/src/hub/session-identity.ts

@@ -0,0 +1,49 @@
+// Distinguishable sessions, not authentication (agent-hub#1036, board #606). A connection that names a peer id but is not that id's current session is bound to an id the DAEMON mints,
+// `<peer>~<origin>` (for example `claude~agent-console`), instead of becoming that peer. The id has no `@`, so it never reaches the remote-room paths (`isRemotePeerId`,
+// `membershipAllowed`, `remoteEnvelope`), and `PEER_ID` is not widened: only the daemon makes these ids, and it keeps them in its own Set.
+//
+// What such a session may do: send, and read through the tools below. It is never a WsPeer, never receives a delivery or a push, and holds none of the peer's board roles.
+//
+// Limit, stated plainly: this makes sessions distinguishable and traceable. It does not authenticate them. A same-user process can always act as the user; the point is that a mix-up
+// between two sessions of one person is visible in the header a recipient reads and in events.jsonl.
+
+/** The task ops a distinct session may run: reads that need no role. Everything else is refused with `sessionRefusal`. */
+export const SESSION_READ_OPS: ReadonlySet<string> = new Set([
+  "hub_task_show", "hub_task_list", "hub_status", "hub_capabilities", "hub_study_show", "hub_backlog_list", "hub_release_list",
+]);
+
+/** The control messages a distinct session may send besides task ops. `task` is gated again by `SESSION_READ_OPS`. */
+export const SESSION_MESSAGES: ReadonlySet<string> = new Set(["send", "status", "task"]);
+
+const LABEL = /^[a-z][a-z0-9-]{0,23}$/;
+
+/**
+ * A label is the other project's name or a short session id, and it ends up in a header another agent reads. It is kept only when it already IS a plain lowercase token: nothing is cleaned up into
+ * one, so a path, a sentence or an instruction cannot leave a fragment of itself in a sender name. Anything else is dropped, and the hub mints a random short id instead.
+ */
+export function sessionLabel(value: unknown): string | undefined {
+  return typeof value === "string" && LABEL.test(value) && !value.endsWith("-") ? value : undefined;
+}
+
+/** `taken(id)` says whether a live session already has the id. A second session from the same origin gets a short suffix, so no two live sessions share an id. */
+export function mintSessionId(peer: string, label: unknown, taken: (id: string) => boolean, random: () => string): string {
+  const base = `${peer.slice(0, 32)}~${sessionLabel(label) ?? random()}`;
+  let id = base;
+  for (let n = 0; taken(id) && n < 8; n++) id = `${base}-${random().slice(0, 4)}`;
+  return id;
+}
+
+export const isSessionId = (id: unknown): id is string => typeof id === "string" && id.includes("~");
+
+/** The one refusal a distinct session meets, so a person reading it learns which session it is and which one holds the role. */
+export function sessionRefusal(id: string): string {
+  const peer = id.slice(0, id.indexOf("~"));
+  return `this session is ${id}, not this project's ${peer}: it can send and read, and holds none of ${peer}'s board roles`;
+}
+
+/** The gate the daemon applies to every message of a distinct session. Returns the refusal text, or undefined when the message may proceed. */
+export function sessionGate(id: string, msg: { t?: unknown; op?: unknown }): string | undefined {
+  if (typeof msg.t !== "string" || !SESSION_MESSAGES.has(msg.t)) return sessionRefusal(id);
+  if (msg.t === "task" && !(typeof msg.op === "string" && SESSION_READ_OPS.has(msg.op))) return sessionRefusal(id);
+  return undefined;
+}