@coreplane/switchboard 1.242.0 → 1.244.0

package/dist/assets/src/core/runRecord.ts

@@ -209,6 +209,14 @@ export interface RunRecord {
    *  (docs/reference/specs/resident-repos.md item 29) — read off the record,
    *  never off the reply's text. */
   pr?: RunPullRequest;
+  /** The run's lease as the harness started it (item 2; decision 0046): the
+   *  `lease` event, folded at the assembly. Present only on a run whose
+   *  harness started a loop; a record written before the event lacks it. */
+  lease?: RunLease;
+  /** The heads the run pushed (item 2; decision 0046): one per branch, the
+   *  last `pushed_head` event's sha winning — the fact a renewal reads to know
+   *  the run made progress. Present only on a run that pushed. */
+  pushed?: PushedHead[];
   /** What the run cost in tokens, per model, summed from its `model.turn`
    *  spans at finish (`usageOfEvents`; docs/reference/specs/costs.md, cost by user).
    *  Every record written since carries it (zero turns included); one written
@@ -225,6 +233,39 @@ export interface RunPullRequest {
   head?: string;
 }
 
+/** A run's lease as the record names it (item 2): when the wall clock
+ *  began, when the lease ends, and where the loop was cut so the write-up
+ *  and the post-step run inside it. */
+export interface RunLease {
+  startedAt: number;
+  endsAt: number;
+  loopEndsAt: number;
+}
+
+/** A head a run pushed, as the record names it (item 2): the branch and the sha. */
+export interface PushedHead {
+  ref: string;
+  sha: string;
+}
+
+/** The heads a run's events say it pushed — one per branch, the last event's
+ *  sha winning, in first-seen order — or nothing when it pushed none. */
+export function pushedHeadsOf(events: readonly RunEvent[]): PushedHead[] | undefined {
+  const byRef = new Map<string, string>();
+  for (const e of events) if (e.type === "pushed_head") byRef.set(e.ref, e.sha);
+  if (byRef.size === 0) return undefined;
+  return [...byRef].map(([ref, sha]) => ({ ref, sha }));
+}
+
+/** The lease a run's events say its harness started — the first `lease`
+ *  event; a resumed run's later generations publish none — or nothing. */
+export function leaseOfEvents(events: readonly RunEvent[]): RunLease | undefined {
+  for (const e of events) {
+    if (e.type === "lease") return { startedAt: e.startedAt, endsAt: e.endsAt, loopEndsAt: e.loopEndsAt };
+  }
+  return undefined;
+}
+
 /** The pull request a run's events say it opened or edited — the last
  *  `pr_opened` wins, as an edit after an open names the same PR — or nothing. */
 export function prOfEvents(events: readonly RunEvent[]): RunPullRequest | undefined {
@@ -465,6 +506,10 @@ export interface RunListOptions {
   /** The runs one run spawned or that continue a thread it opened
    *  (`RunRecord.parentRunId`, item 46) — a conductor's children as one listing. */
   parentRunId?: string;
+  /** The runs that name one pull request (`namesPullRequest`, item 58): the
+   *  coding runs whose post-step opened or edited it and the review runs that
+   *  posted to it — the findings ledger's runs as one listing. */
+  pr?: { repo: string; number: number };
   /** What the ACTOR may see (authorization): the store predicate compiled
    *  from the policy, pushed down so no surface loads rows and filters after.
    *  Absent = no visibility constraint — only a caller that has already decided
@@ -577,6 +622,27 @@ export function matchesVisibility(
   }
 }
 
+/** The pull request number a stored row names (item 58): the one its coding
+ *  post-step opened or edited (`pr`), else the one its review posted to
+ *  (`reviewPost.target`). Undefined for a run that named none — a review whose
+ *  post was skipped included. The Worker's `pr_number` column is this value,
+ *  written at `put` and backfilled from `summary_json` with the same rule. */
+export function pullRequestNumberOf(row: Pick<RunListItem, "pr" | "reviewPost">): number | undefined {
+  if (row.pr !== undefined) return row.pr.number;
+  if (row.reviewPost?.posted) return row.reviewPost.target.number;
+  return undefined;
+}
+
+/** The one truth table for `RunListOptions.pr`: the row's repository is the
+ *  pull request's and the number it names is the pull request's. The Worker
+ *  applies the same test in SQL (`repo = ? AND pr_number = ?`). */
+export function namesPullRequest(
+  row: Pick<RunListItem, "repo" | "pr" | "reviewPost">,
+  pr: { repo: string; number: number },
+): boolean {
+  return row.repo === pr.repo && pullRequestNumberOf(row) === pr.number;
+}
+
 /** The list order (`finishedAt` desc, `id` desc) as a cursor predicate: true
  *  when `row` comes strictly after the cursor. Shared by `selectListItems`;
  *  the Worker applies the same predicate in SQL. */
@@ -751,6 +817,18 @@ export function isRunRecord(v: unknown): v is RunRecord {
   if (r.profile !== undefined && !isRunProfileRecord(r.profile)) return false;
   // The pull request the run reached (item 2): a positive integer and a URL, or absent.
   if (r.pr !== undefined && !isRunPullRequestShape(r.pr)) return false;
+  if (
+    r.pushed !== undefined &&
+    !(
+      Array.isArray(r.pushed) &&
+      r.pushed.every((h) => {
+        if (typeof h !== "object" || h === null) return false;
+        const { ref, sha } = h as Record<string, unknown>;
+        return typeof ref === "string" && ref.length > 0 && typeof sha === "string" && /^[0-9a-f]{7,40}$/.test(sha);
+      })
+    )
+  )
+    return false;
   // A parent is named by a run id (item 46): the same shape as the record's own.
   if (r.parentRunId !== undefined && (typeof r.parentRunId !== "string" || !RUN_ID_PATTERN.test(r.parentRunId)))
     return false;

package/dist/assets/src/core/runUsage.ts

@@ -1,15 +1,21 @@
 import type { RunEvent } from "./runEvents.js";
 
-// What a run cost in tokens, and who it belongs to — the data behind "cost by
-// user" on the costs page (docs/reference/specs/costs.md). Every provider call a
-// run makes is one `model.turn` span with the provider's own token counts as
-// attrs (metered by the model proxy or the runner; docs/reference/specs/tracing.md), so a
-// run's usage is the sum of those spans, per model. It is computed ONCE, at
-// finish, from the events still in memory (`assembleRunRecord`), and rides the
-// record — a record's events may be cut to fit the byte budget, so an aggregate
-// taken then is more faithful than one re-read later. A record written before
-// the field existed has none; the store fills it in from the run's stored
-// events on demand (the lazy backfill), and reports how many still wait.
+// What a run cost in tokens, and who it belongs to — the data behind the cost
+// dimensions of the costs page (docs/reference/specs/costs.md items 10–10a) and
+// the dollars on a run's own page. Every provider call a run makes is one
+// `model.turn` span with the provider's own token counts as attrs (metered by
+// the model proxy or the runner; docs/reference/specs/tracing.md), so a run's
+// usage is the sum of those spans, per model. It is computed ONCE, at finish,
+// from the events still in memory (`assembleRunRecord`), and rides the record —
+// a record's events may be cut to fit the byte budget, so an aggregate taken
+// then is more faithful than one re-read later. A record written before the
+// field existed has none; the store fills it in from the run's stored events
+// on demand (the lazy backfill), and reports how many still wait.
+//
+// The store answers one row per run (`RunUsageRows`); the bot folds them into
+// cells (`aggregateUsage`) — one per requester, thread, channel, agent and UTC
+// day of finish — so a snapshot holds the cube every dimension is read from
+// and never a row per run.
 
 export interface ModelUsage {
   turns: number;
@@ -28,6 +34,9 @@ export interface RunUsage {
 
 export const UNKNOWN_MODEL = "unknown";
 
+/** The agent of a cell whose record names none (a record written before the field, a hand-built one). */
+export const UNKNOWN_AGENT = "unknown";
+
 const MODEL_TURN = "model.turn";
 
 const num = (v: unknown): number => (typeof v === "number" && Number.isFinite(v) && v >= 0 ? v : 0);
@@ -96,7 +105,7 @@ export function isRunUsage(v: unknown): v is RunUsage {
   return Object.values(u.byModel).every(isModelUsage);
 }
 
-// ---- the aggregate: who spent what, per UTC day ---------------------------------------
+// ---- the store's answer: one row per run -------------------------------------------------
 
 /** One finished run as the aggregate sees it — the record's identity fields and its usage. */
 export interface UsageRun {
@@ -105,22 +114,19 @@ export interface UsageRun {
   userName?: string;
   /** A child run is billed to whoever started its parent (run-history item 46). */
   parentRunId?: string;
+  /** The thread the run ran in and the channel it belongs to (platform-namespaced, invariant 4). */
+  threadKey: string;
+  channelId: string;
+  /** The agent the run resolved to; absent on a record that names none. */
+  agent?: string;
   startedAt: number;
   finishedAt: number;
   /** Absent on a record written before usage existed and not yet backfilled. */
   usage?: RunUsage;
 }
 
-export interface UserDayUsage {
-  userId: string;
-  userName?: string;
-  /** The UTC day the run finished, `YYYY-MM-DD`. */
-  day: string;
-  runs: number;
-  /** Summed wall-clock of the runs (finish − start), for allocating shared cloud spend. */
-  wallMs: number;
-  usage: RunUsage;
-}
+/** Whose run it is, as far as billing goes. */
+export type UsageIdentity = Pick<UsageRun, "userId" | "userName">;
 
 export interface RunUsageQuery {
   /** Runs that finished at or after this epoch ms … */
@@ -129,8 +135,43 @@ export interface RunUsageQuery {
   untilMs: number;
 }
 
+/** What the store answers (`POST /runs/usage`): the runs that finished in the
+ *  range, oldest finish first, and the identity of every parent a child names
+ *  that is outside the batch and known to the store — so the bot can bill the
+ *  child without a second read. */
+export interface RunUsageRows {
+  runs: UsageRun[];
+  parents: Record<string, UsageIdentity>;
+  /** Runs in range whose usage is not known yet (written before the field; backfill outstanding). */
+  pending: number;
+  /** The oldest finish the store still holds, so a page can bound its range to the data. */
+  earliestFinishedAt?: number;
+  retentionDays: number;
+}
+
+// ---- the aggregate: the usage cube --------------------------------------------------------
+
+/** One cell: the runs one requester was billed for in one thread, one channel,
+ *  on one agent, finishing on one UTC day. Every cost dimension is a sum over
+ *  these — by user, thread, channel or agent along a key, by model inside `usage`. */
+export interface UsageRow {
+  /** The UTC day the runs finished, `YYYY-MM-DD`. */
+  day: string;
+  /** The requester billed (a child's parent's). */
+  userId: string;
+  userName?: string;
+  threadKey: string;
+  channelId: string;
+  /** The agent, or `unknown` when the record names none. */
+  agent: string;
+  runs: number;
+  /** Summed wall-clock of the runs (finish − start), for allocating shared cloud spend. */
+  wallMs: number;
+  usage: RunUsage;
+}
+
 export interface RunUsageReport {
-  rows: UserDayUsage[];
+  rows: UsageRow[];
   /** Runs in range whose usage is not known yet (written before the field; backfill outstanding). */
   pending: number;
   /** The oldest finish the store still holds, so a page can bound its range to the data. */
@@ -140,34 +181,51 @@ export interface RunUsageReport {
 
 export const dayOf = (epochMs: number): string => new Date(epochMs).toISOString().slice(0, 10);
 
+const identityOf = (who: UsageIdentity): UsageIdentity => ({
+  userId: who.userId,
+  ...(who.userName ? { userName: who.userName } : {}),
+});
+
 /** Who a run is billed to: its parent's requester when it is a child and the
  *  parent is known (in the batch, or through `lookupParent`), else its own. */
 export function billedTo(
   run: UsageRun,
   batch: ReadonlyMap<string, UsageRun>,
-  lookupParent: (id: string) => Pick<UsageRun, "userId" | "userName"> | undefined,
-): Pick<UsageRun, "userId" | "userName"> {
-  if (!run.parentRunId) return { userId: run.userId, ...(run.userName ? { userName: run.userName } : {}) };
+  lookupParent: (id: string) => UsageIdentity | undefined,
+): UsageIdentity {
+  if (!run.parentRunId) return identityOf(run);
   const parent = batch.get(run.parentRunId) ?? lookupParent(run.parentRunId);
-  if (!parent) return { userId: run.userId, ...(run.userName ? { userName: run.userName } : {}) };
-  return { userId: parent.userId, ...(parent.userName ? { userName: parent.userName } : {}) };
+  return identityOf(parent ?? run);
 }
 
-/** Pure: the runs summed per (billed user, UTC day of finish). A run without
- *  usage counts as pending and contributes its run and wall-clock only. Rows
- *  come out oldest day first, then by user id. */
-export function aggregateUsageByUser(
+const CELL_ORDER = ["day", "userId", "threadKey", "channelId", "agent"] as const;
+
+/** Pure: the runs summed into cells — per (billed user, thread, channel, agent,
+ *  UTC day of finish). A run without usage counts as pending and contributes its
+ *  run and wall-clock only. Rows come out oldest day first, then by user id,
+ *  thread, channel and agent. */
+export function aggregateUsage(
   runs: readonly UsageRun[],
-  lookupParent: (id: string) => Pick<UsageRun, "userId" | "userName"> | undefined = () => undefined,
-): { rows: UserDayUsage[]; pending: number } {
+  lookupParent: (id: string) => UsageIdentity | undefined = () => undefined,
+): { rows: UsageRow[]; pending: number } {
   const batch = new Map(runs.map((r) => [r.id, r]));
-  const rows = new Map<string, UserDayUsage>();
+  const rows = new Map<string, UsageRow>();
   let pending = 0;
   for (const run of runs) {
     const who = billedTo(run, batch, lookupParent);
     const day = dayOf(run.finishedAt);
-    const key = `${day} ${who.userId}`;
-    const row = rows.get(key) ?? { userId: who.userId, day, runs: 0, wallMs: 0, usage: emptyUsage() };
+    const agent = run.agent ?? UNKNOWN_AGENT;
+    const key = JSON.stringify([day, who.userId, run.threadKey, run.channelId, agent]);
+    const row = rows.get(key) ?? {
+      day,
+      userId: who.userId,
+      threadKey: run.threadKey,
+      channelId: run.channelId,
+      agent,
+      runs: 0,
+      wallMs: 0,
+      usage: emptyUsage(),
+    };
     if (who.userName && !row.userName) row.userName = who.userName;
     row.runs += 1;
     row.wallMs += Math.max(0, run.finishedAt - run.startedAt);
@@ -175,25 +233,78 @@ export function aggregateUsageByUser(
     else pending += 1;
     rows.set(key, row);
   }
+  const sorted = [...rows.values()].sort((a, b) => {
+    for (const k of CELL_ORDER) {
+      if (a[k] < b[k]) return -1;
+      if (a[k] > b[k]) return 1;
+    }
+    return 0;
+  });
+  return { rows: sorted, pending };
+}
+
+/** The bot's fold over the store's answer: the cells, the parents outside the batch consulted. */
+export function reportOfUsageRows(rows: RunUsageRows): RunUsageReport {
+  const { rows: cells, pending } = aggregateUsage(rows.runs, (id) => rows.parents[id]);
   return {
-    rows: [...rows.values()].sort((a, b) => (a.day < b.day ? -1 : a.day > b.day ? 1 : a.userId < b.userId ? -1 : 1)),
-    pending,
+    rows: cells,
+    // The store counts what it could not price; the fold sees the same runs without `usage`.
+    pending: Math.max(pending, rows.pending),
+    ...(rows.earliestFinishedAt !== undefined ? { earliestFinishedAt: rows.earliestFinishedAt } : {}),
+    retentionDays: rows.retentionDays,
   };
 }
 
+const isIdentity = (v: unknown): v is UsageIdentity =>
+  typeof v === "object" &&
+  v !== null &&
+  typeof (v as UsageIdentity).userId === "string" &&
+  ((v as UsageIdentity).userName === undefined || typeof (v as UsageIdentity).userName === "string");
+
+function isUsageRun(v: unknown): v is UsageRun {
+  if (!isIdentity(v)) return false;
+  const r = v as UsageRun;
+  return (
+    typeof r.id === "string" &&
+    typeof r.threadKey === "string" &&
+    typeof r.channelId === "string" &&
+    (r.agent === undefined || typeof r.agent === "string") &&
+    (r.parentRunId === undefined || typeof r.parentRunId === "string") &&
+    typeof r.startedAt === "number" &&
+    typeof r.finishedAt === "number" &&
+    (r.usage === undefined || isRunUsage(r.usage))
+  );
+}
+
+function hasReportTail(r: Record<string, unknown>): boolean {
+  if (typeof r.pending !== "number" || typeof r.retentionDays !== "number") return false;
+  return r.earliestFinishedAt === undefined || typeof r.earliestFinishedAt === "number";
+}
+
+/** The store's wire shape, as the Worker client re-validates it. */
+export function isRunUsageRows(v: unknown): v is RunUsageRows {
+  if (typeof v !== "object" || v === null) return false;
+  const r = v as Record<string, unknown>;
+  if (!Array.isArray(r.runs) || !r.runs.every(isUsageRun)) return false;
+  if (typeof r.parents !== "object" || r.parents === null || Array.isArray(r.parents)) return false;
+  if (!Object.values(r.parents).every(isIdentity)) return false;
+  return hasReportTail(r);
+}
+
+/** The cells' wire shape, as the snapshot guard re-validates it. */
 export function isRunUsageReport(v: unknown): v is RunUsageReport {
   if (typeof v !== "object" || v === null) return false;
   const r = v as Record<string, unknown>;
-  if (!Array.isArray(r.rows) || typeof r.pending !== "number" || typeof r.retentionDays !== "number") return false;
-  if (r.earliestFinishedAt !== undefined && typeof r.earliestFinishedAt !== "number") return false;
+  if (!Array.isArray(r.rows) || !hasReportTail(r)) return false;
   return r.rows.every(
     (row) =>
-      typeof row === "object" &&
-      row !== null &&
-      typeof (row as UserDayUsage).userId === "string" &&
-      typeof (row as UserDayUsage).day === "string" &&
-      typeof (row as UserDayUsage).runs === "number" &&
-      typeof (row as UserDayUsage).wallMs === "number" &&
-      isRunUsage((row as UserDayUsage).usage),
+      isIdentity(row) &&
+      typeof (row as UsageRow).day === "string" &&
+      typeof (row as UsageRow).threadKey === "string" &&
+      typeof (row as UsageRow).channelId === "string" &&
+      typeof (row as UsageRow).agent === "string" &&
+      typeof (row as UsageRow).runs === "number" &&
+      typeof (row as UsageRow).wallMs === "number" &&
+      isRunUsage((row as UsageRow).usage),
   );
 }

package/dist/assets/src/core/schedules.ts

@@ -7,6 +7,9 @@ import { parseIngressTokenMap, tokenForSubject } from "./ingressTokens.js";
 // worker), and each Worker's `scheduled()` looks its firing up HERE — so a
 // schedule can never exist in one place and not the other.
 //
+// Schedules a person adds at runtime, and the hand-over of a firing to the
+// `schedule:<name>` actor declared below, are docs/decisions/0049-a-stored-schedule-is-a-turn-the-minute-tick-fires.md.
+//
 // A schedule has three independent facets:
 //   worker   — whose wrangler.jsonc carries the cron and whose `scheduled()` fires it
 //   action   — what a firing does: `run` (the bot shim POSTs the generic /ingress as

package/dist/assets/src/core/ship/contract.ts

@@ -431,7 +431,8 @@ function renderFirstInstruction(rebase: ChildContract["rebase"]): string {
     `Push the branch as soon as the change exists and its cheapest proving checks pass — before the project's ` +
     `full verification, which runs after that push with any fix as a further commit; an unpushed tree does not ` +
     `survive the run's end. Right before each push, fetch ${onto} again and rebase once more if it moved while ` +
-    `you worked, so the pull request is not born conflicting.`
+    `you worked, so the pull request is not born conflicting. At the wind-down note, commit and push what compiles, ` +
+    `say what does not, then answer.`
   );
 }