agent-relay-server 0.99.1 → 0.101.0

package/src/config-store.ts

@@ -72,15 +72,15 @@ const BUILT_IN_AGENT_PROFILE_NAMES = new Set([DEFAULT_SPAWN_PROFILE_NAME, "minim
 const WORKER_TOOL_GROUPS = ["core", "workspace", "memory", "artifacts", "blackboard", "subscriptions"];
 
 const BUILT_IN_AGENT_PROFILES: AgentProfile[] = [
-  agentProfileDefaults({ name: DEFAULT_SPAWN_PROFILE_NAME, description: "Relay-aware spawned agent with bundled Relay context, skills, plugins, and status integration.", base: "host", mcp: { mode: "none" }, relay: { tools: { groups: WORKER_TOOL_GROUPS } } }),
-  agentProfileDefaults({ name: "minimal", description: "Repo-focused spawned agent with Relay affordances disabled and host/global extras avoided where supported.", base: "minimal" }),
-  agentProfileDefaults({ name: "isolated-research", description: "Strict profile for autonomous research runs: repo context only, no Relay prompt surface, no global extras where supported.", base: "isolated" }),
-  agentProfileDefaults({ name: "vanilla", description: "Zero host bleed (#552): isolated provider home with host plugins, skills, hooks, MCP, and the CLAUDE.md/AGENTS.md cascade (repo + global) all suppressed at launch. Relay provisions any surface explicitly per profile.", base: "vanilla" }),
-  agentProfileDefaults({ name: "lean-worker", description: "Lean worker profile (#570): vanilla host-dependency drop with only Relay context/MCP restored and Project knowledge injected from the spawn cwd.", base: "vanilla", relay: { context: true, skills: false, plugins: false, statusLine: false, mcp: true, tools: { groups: WORKER_TOOL_GROUPS } }, projectInstructions: { policy: "all" } }),
-  agentProfileDefaults({ name: "coordinator", description: "Relay-aware coordination lead for spawning worker teams, maintaining shared state, and driving review and release.", base: "host", instructions: { append: [COORDINATION_CHARTER], repoInstructions: "allow", globalInstructions: "allow" }, maxSpawnedAgents: 8 }),
-  agentProfileDefaults({ name: "ops-assistant", description: "Relay-aware ops lieutenant for a coordinator: runs tests, releases, smoke probes, gates, and host checks, then reports crisp outcomes back up.", provider: "codex", base: "host", instructions: { append: [OPS_ASSISTANT_BRIEF], repoInstructions: "allow", globalInstructions: "allow" }, permissions: { mode: "open", filesystem: "host" } }),
-  agentProfileDefaults({ name: "worker", description: "Relay-aware focused implementer with open approval posture and no delegated spawn capability.", base: "host", mcp: { mode: "none" }, permissions: { mode: "open", filesystem: "host" }, relay: { tools: { groups: WORKER_TOOL_GROUPS } } }),
-  agentProfileDefaults({ name: "reviewer", description: "Relay-aware read-only reviewer for audit and review passes without file writes.", base: "host", mcp: { mode: "none" }, permissions: { mode: "read-only", filesystem: "host" }, relay: { tools: { groups: WORKER_TOOL_GROUPS } } }),
+  agentProfileDefaults({ name: DEFAULT_SPAWN_PROFILE_NAME, icon: "🤖", description: "Relay-aware spawned agent with bundled Relay context, skills, plugins, and status integration.", base: "host", mcp: { mode: "none" }, relay: { tools: { groups: WORKER_TOOL_GROUPS } } }),
+  agentProfileDefaults({ name: "minimal", icon: "▫️", description: "Repo-focused spawned agent with Relay affordances disabled and host/global extras avoided where supported.", base: "minimal" }),
+  agentProfileDefaults({ name: "isolated-research", icon: "🔬", description: "Strict profile for autonomous research runs: repo context only, no Relay prompt surface, no global extras where supported.", base: "isolated" }),
+  agentProfileDefaults({ name: "vanilla", icon: "🫥", description: "Zero host bleed (#552): isolated provider home with host plugins, skills, hooks, MCP, and the CLAUDE.md/AGENTS.md cascade (repo + global) all suppressed at launch. Relay provisions any surface explicitly per profile.", base: "vanilla" }),
+  agentProfileDefaults({ name: "lean-worker", icon: "🪶", description: "Lean worker profile (#570): vanilla host-dependency drop with only Relay context/MCP restored and Project knowledge injected from the spawn cwd.", base: "vanilla", relay: { context: true, skills: false, plugins: false, statusLine: false, mcp: true, tools: { groups: WORKER_TOOL_GROUPS } }, projectInstructions: { policy: "all" } }),
+  agentProfileDefaults({ name: "coordinator", icon: "🧭", description: "Relay-aware coordination lead for spawning worker teams, maintaining shared state, and driving review and release.", base: "host", instructions: { append: [COORDINATION_CHARTER], repoInstructions: "allow", globalInstructions: "allow" }, maxSpawnedAgents: 8 }),
+  agentProfileDefaults({ name: "ops-assistant", icon: "🛠️", description: "Relay-aware ops lieutenant for a coordinator: runs tests, releases, smoke probes, gates, and host checks, then reports crisp outcomes back up.", provider: "codex", base: "host", instructions: { append: [OPS_ASSISTANT_BRIEF], repoInstructions: "allow", globalInstructions: "allow" }, permissions: { mode: "open", filesystem: "host" } }),
+  agentProfileDefaults({ name: "worker", icon: "🔨", description: "Relay-aware focused implementer with open approval posture and no delegated spawn capability.", base: "host", mcp: { mode: "none" }, permissions: { mode: "open", filesystem: "host" }, relay: { tools: { groups: WORKER_TOOL_GROUPS } } }),
+  agentProfileDefaults({ name: "reviewer", icon: "🔍", description: "Relay-aware read-only reviewer for audit and review passes without file writes.", base: "host", mcp: { mode: "none" }, permissions: { mode: "read-only", filesystem: "host" }, relay: { tools: { groups: WORKER_TOOL_GROUPS } } }),
 ].map((profile) => ({ ...profile, builtIn: true }));
 
 interface ConfigRow {
@@ -286,6 +286,7 @@ function agentProfileDefaults(input: Pick<AgentProfile, "name" | "base"> & Omit<
   return {
     name: input.name,
     description: input.description,
+    ...(input.icon === undefined ? {} : { icon: input.icon }),
     provider: input.provider ?? "any",
     base: input.base,
     builtIn: input.builtIn,
@@ -361,6 +362,9 @@ function validateAgentProfile(key: string, value: unknown, opts: { allowBuiltIn?
   return agentProfileDefaults({
     ...defaults,
     description: cleanString(value.description, "description", { max: 1000 }),
+    // #751: per-profile emoji icon. Short free string (single emoji incl. ZWJ
+    // sequences); cap length so it can't smuggle arbitrary text. Empty → undefined.
+    icon: cleanString(value.icon, "icon", { max: 8 }) || undefined,
     provider: value.provider === undefined || value.provider === null
       ? defaults.provider
       : cleanEnum(value.provider, "provider", VALID_PROFILE_PROVIDERS),

package/src/db/provider-quota-burn.ts

@@ -1,7 +1,20 @@
+import { DEFAULT_QUOTA_TARGET_UTILIZATION, quotaPaceMetrics, quotaWindowMetrics } from "agent-relay-sdk/provider-quota";
 import type { ProviderQuotaBurn, ProviderQuotaBurnRole, ProviderQuotaBurnWindow, ProviderQuotaSnapshot, QuotaState } from "../types";
 
 const QUOTA_BURN_MIN_SAMPLE_SPAN_MS = 10 * 60_000;
 
+// #760 — nominal window length per role, used to scale the recency half-life.
+const WINDOW_NOMINAL_MS: Record<ProviderQuotaBurnRole, number> = {
+  "5h": 5 * 3_600_000,
+  "7d": 7 * 24 * 3_600_000,
+};
+
+// #760 — recency half-life as a fraction of the window length. 0.25 → ~75min for the 5h
+// window (within the issue's ~60–90min trailing-window guidance) and ~42h for the 7d window.
+// A burst at the START of the history span decays out as it ages, so an idle stretch pulls the
+// observed rate (and burnRatio) back toward 0 instead of freezing the endpoint slope.
+const RECENCY_HALFLIFE_FRACTION = 0.25;
+
 type QuotaWindow = QuotaState["windows"][number];
 
 // Provider-agnostic: window role is expressed by name only. Each adapter uses the
@@ -35,9 +48,38 @@ function lowConfidenceBurnWindow(role: ProviderQuotaBurnRole, window: QuotaWindo
     timeToWallMs: null,
     projectedWallAt: null,
     earlyWallMs: null,
+    observedRatePerMs: null,
+    projectedUtilAtReset: null,
+    slack: null,
+    target: null,
   };
 }
 
+// #760 — recency-weighted consumption rate (utilization-fraction per ms). A weighted slope:
+// each consecutive interval contributes its actual Δutilization and Δt, decayed by the age of
+// its midpoint with the given half-life. A recent idle interval (large Δt, ~0 Δutil, high
+// weight) dominates the denominator and drives the rate toward 0; an old burst is down-weighted.
+function recencyWeightedRatePerMs(
+  samples: Array<{ capturedAt: number; utilization: number }>,
+  now: number,
+  halfLifeMs: number,
+): number {
+  let weightedDelta = 0;
+  let weightedDt = 0;
+  for (let i = 1; i < samples.length; i++) {
+    const prev = samples[i - 1]!;
+    const cur = samples[i]!;
+    const dt = cur.capturedAt - prev.capturedAt;
+    if (dt <= 0) continue;
+    const midAge = Math.max(0, now - (prev.capturedAt + cur.capturedAt) / 2);
+    const weight = Math.pow(0.5, midAge / halfLifeMs);
+    weightedDelta += weight * (cur.utilization - prev.utilization);
+    weightedDt += weight * dt;
+  }
+  if (weightedDt <= 0) return 0;
+  return Math.max(0, weightedDelta / weightedDt);
+}
+
 function deriveProviderQuotaBurnWindow(input: {
   provider: string;
   currentWindow: QuotaWindow;
@@ -78,16 +120,42 @@ function deriveProviderQuotaBurnWindow(input: {
     return low;
   }
 
-  const remainingQuota = Math.max(0, 1 - utilizationNow);
+  const remainingQuota = quotaWindowMetrics(input.currentWindow).remaining;
   const timeToResetMs = resetAt - input.now;
   if (remainingQuota <= 0 || timeToResetMs <= 0) return low;
-  const observedRatePerMs = Math.max(0, (utilizationNow - oldest.utilization) / (current.capturedAt - oldest.capturedAt));
-  const optimalRatePerMs = remainingQuota / timeToResetMs;
-  if (observedRatePerMs <= 0 || optimalRatePerMs <= 0) {
+
+  // #760 (Defect 1) — recency-weighted rate so an old burst decays and idle relaxes toward 0,
+  // instead of a frozen two-point endpoint slope over the whole span.
+  //
+  // Idle is invisible in the raw samples: identical utilization snapshots are deduped, so during
+  // an idle stretch no new rows arrive and the latest sample stays frozen at the last CHANGE
+  // (this is why codex sat at burn×6.3 — a stale burst slope). We make idle observable by
+  // appending a synthetic "utilization is still X as of now" point, which adds a recent
+  // zero-delta interval [lastSample, now] that the recency weighting lets dominate as it grows.
+  const halfLifeMs = WINDOW_NOMINAL_MS[role] * RECENCY_HALFLIFE_FRACTION;
+  const rateSamples = input.now > current.capturedAt
+    ? [...samples, { capturedAt: input.now, utilization: utilizationNow }]
+    : samples;
+  const observedRatePerMs = recencyWeightedRatePerMs(rateSamples, input.now, halfLifeMs);
+  // #760 (Defect 2) — pace against a configurable target (<100%); slack carries the underburn
+  // signal. The query layer (spawn-targets) may re-derive these against a per-provider target;
+  // the ingest-time values use the default so direct burn consumers (dashboard) have a number.
+  const pace = quotaPaceMetrics({
+    utilization: utilizationNow,
+    observedRatePerMs,
+    timeToResetMs,
+    target: DEFAULT_QUOTA_TARGET_UTILIZATION,
+  });
+  if (observedRatePerMs <= 0) {
+    // Idle (or decayed-to-idle): no projected wall, but slack still flags the headroom.
     return {
       ...low,
       confidence: "high",
       burnRatio: 0,
+      observedRatePerMs: 0,
+      projectedUtilAtReset: pace.projectedUtilAtReset,
+      slack: pace.slack,
+      target: pace.target,
     };
   }
   const timeToWallMs = remainingQuota / observedRatePerMs;
@@ -95,10 +163,15 @@ function deriveProviderQuotaBurnWindow(input: {
   return {
     ...low,
     confidence: "high",
-    burnRatio: observedRatePerMs / optimalRatePerMs,
+    burnRatio: pace.burnRatio,
+    observedRatePerMs,
     timeToWallMs,
     projectedWallAt,
-    earlyWallMs: Math.max(0, resetAt - projectedWallAt),
+    // #760 (Defect 2) — symmetric: negative means the wall lands AFTER reset (headroom left).
+    earlyWallMs: resetAt - projectedWallAt,
+    projectedUtilAtReset: pace.projectedUtilAtReset,
+    slack: pace.slack,
+    target: pace.target,
   };
 }
 

package/src/issue-tracker/adapter.ts

@@ -1,4 +1,4 @@
-import type { IssueRef, IssueRefStatus } from "../types";
+import type { IssueProvider, IssueRef, IssueRefStatus } from "../types";
 
 export interface IssueTrackerStatus {
   status: IssueRefStatus;
@@ -14,9 +14,19 @@ export interface IssueTrackerReopenOptions {
   comment?: string;
 }
 
+export interface IssueTrackerIssueSummary {
+  provider: IssueProvider;
+  repo: string;
+  externalKey: string;
+  url?: string;
+  title?: string;
+  status: IssueRefStatus;
+}
+
 export interface IssueTrackerAdapter {
   resolveLink(ref: IssueRef): string;
   getStatus(ref: IssueRef): Promise<IssueTrackerStatus>;
+  listOpenSubIssues?(ref: IssueRef): Promise<IssueTrackerIssueSummary[]>;
   close(ref: IssueRef, options?: IssueTrackerCloseOptions): Promise<void>;
   reopen(ref: IssueRef, options?: IssueTrackerReopenOptions): Promise<void>;
   comment(ref: IssueRef, body: string): Promise<void>;

package/src/issue-tracker/github.ts

@@ -1,5 +1,5 @@
 import type { IssueRef, IssueRefStatus } from "../types";
-import type { IssueTrackerAdapter, IssueTrackerCloseOptions, IssueTrackerReopenOptions, IssueTrackerStatus } from "./adapter";
+import type { IssueTrackerAdapter, IssueTrackerCloseOptions, IssueTrackerIssueSummary, IssueTrackerReopenOptions, IssueTrackerStatus } from "./adapter";
 
 export const GITHUB_FIXED_LABEL = "fixed";
 const GITHUB_CREDENTIAL_REQUIREMENT = "GitHub issue tracker adapter requires gh authenticated with a token that has issues:write scope";
@@ -20,6 +20,50 @@ interface GitHubIssuePayload {
   html_url?: unknown;
 }
 
+interface GitHubSubIssueNode {
+  number?: unknown;
+  title?: unknown;
+  state?: unknown;
+  url?: unknown;
+}
+
+interface GitHubSubIssuesPayload {
+  data?: {
+    repository?: {
+      issue?: {
+        subIssues?: {
+          nodes?: GitHubSubIssueNode[];
+          pageInfo?: {
+            hasNextPage?: unknown;
+            endCursor?: unknown;
+          };
+        };
+      };
+    };
+  };
+}
+
+const SUB_ISSUES_QUERY = `
+  query($owner: String!, $repo: String!, $number: Int!, $after: String) {
+    repository(owner: $owner, name: $repo) {
+      issue(number: $number) {
+        subIssues(first: 100, after: $after) {
+          nodes {
+            number
+            title
+            state
+            url
+          }
+          pageInfo {
+            hasNextPage
+            endCursor
+          }
+        }
+      }
+    }
+  }
+`;
+
 function textFromBytes(value: unknown): string {
   if (!value) return "";
   if (typeof value === "string") return value;
@@ -78,7 +122,10 @@ function assertGitHubIssueRef(ref: IssueRef): void {
 }
 
 function statusFromState(state: unknown): IssueRefStatus {
-  if (state === "open" || state === "closed") return state;
+  if (typeof state === "string") {
+    const normalized = state.toLowerCase();
+    if (normalized === "open" || normalized === "closed") return normalized;
+  }
   return "unknown";
 }
 
@@ -105,6 +152,40 @@ class GitHubIssueTrackerAdapter implements IssueTrackerAdapter {
     return { status: statusFromState(issue.state), title: titleFromIssue(issue) };
   }
 
+  async listOpenSubIssues(ref: IssueRef): Promise<IssueTrackerIssueSummary[]> {
+    assertGitHubIssueRef(ref);
+    const [owner, repo] = ref.repo.split("/") as [string, string];
+    const open: IssueTrackerIssueSummary[] = [];
+    let after: string | undefined;
+
+    do {
+      const response = await this.api({
+        method: "POST",
+        path: "graphql",
+        body: {
+          query: SUB_ISSUES_QUERY,
+          owner,
+          repo,
+          number: Number(ref.externalKey),
+          after,
+        },
+      }) as GitHubSubIssuesPayload;
+      const subIssues = response.data?.repository?.issue?.subIssues;
+      for (const node of subIssues?.nodes ?? []) {
+        if (statusFromState(node.state) !== "open") continue;
+        const number = typeof node.number === "number" || typeof node.number === "string" ? String(node.number) : "";
+        if (!number) continue;
+        const title = typeof node.title === "string" ? node.title : undefined;
+        const url = typeof node.url === "string" ? node.url : `https://github.com/${ref.repo}/issues/${number}`;
+        open.push({ provider: "github", repo: ref.repo, externalKey: number, url, title, status: "open" });
+      }
+      const pageInfo = subIssues?.pageInfo;
+      after = pageInfo?.hasNextPage === true && typeof pageInfo.endCursor === "string" ? pageInfo.endCursor : undefined;
+    } while (after);
+
+    return open;
+  }
+
   async close(ref: IssueRef, options: IssueTrackerCloseOptions = {}): Promise<void> {
     await this.api({ method: "PATCH", path: githubIssuePath(ref), body: { state: "closed" } });
     await this.applyLabels(ref, [GITHUB_FIXED_LABEL, ...(options.labels ?? [])]);

package/src/issue-tracker/index.ts

@@ -1,6 +1,7 @@
 export type {
   IssueTrackerAdapter,
   IssueTrackerCloseOptions,
+  IssueTrackerIssueSummary,
   IssueTrackerReopenOptions,
   IssueTrackerStatus,
 } from "./adapter";

package/src/lifecycle-manager.ts

@@ -1,6 +1,6 @@
 import { createCommand } from "./commands-db";
-import { extractClaudeModelUnavailableMessage } from "agent-relay-sdk";
 import { isPathWithinBase } from "./utils";
+import { agentProviderState } from "./provider-state";
 import { createActivityEvent, deleteWorkspace, getAgent, getDb, getOrchestrator, listOrchestrators, listWorkspaces } from "./db";
 import {
   getManagedAgentState,
@@ -413,7 +413,10 @@ export class LifecycleManager {
 
   private markPolicyFailure(policy: SpawnPolicy, state: ManagedAgentState, error: string, exited?: ManagedSessionExitDiagnostics): void {
     if (state.status === "stopping") return;
-    const modelUnavailable = managedModelUnavailableMessage(policy, error, exited);
+    // Read the terminal reason from the adapter-surfaced typed provider state rather
+    // than re-parsing raw provider log text (#745 / #725 §4.4 leak #13).
+    const agentId = state.agentId || exited?.agentId;
+    const modelUnavailable = agentId ? agentTerminalFailureMessage(getAgent(agentId)) : null;
     if (modelUnavailable) {
       this.markFailed(policy, state, modelUnavailable);
       return;
@@ -622,34 +625,18 @@ export function __resetLifecycleManager(): void {
   singleton = null;
 }
 
-function managedModelUnavailableMessage(_policy: SpawnPolicy, error: string, exited?: ManagedSessionExitDiagnostics): string | null {
-  // extractClaudeModelUnavailableMessage returns null for text that doesn't match
-  // the Claude-specific error pattern, so this is safe to call unconditionally —
-  // no provider=== branch needed here; the parser is the gate (#743).
-  return extractClaudeModelUnavailableMessage([
-    error,
-    exited?.lastError,
-    ...(exited?.logTail ?? []),
-    ...(exited?.unavailable ?? []),
-  ].join("\n"));
-}
-
 function isFastFailStorm(failures: number, exited?: ManagedSessionExitDiagnostics): boolean {
   return failures >= MAX_FAST_FAILURES && exited !== undefined && exited.runtimeMs < FAST_FAIL_RUNTIME_MS;
 }
 
+// Returns the model-unavailable message when the agent's adapter-surfaced typed provider
+// state indicates a terminal model-unavailable failure (#745 / #725 §4.4 leak #13).
 function agentTerminalFailureMessage(agent: ReturnType<typeof getAgent> | null): string | null {
   if (!agent?.meta) return null;
   const reason = typeof agent.meta.terminalFailureReason === "string" ? agent.meta.terminalFailureReason : undefined;
   const message = typeof agent.meta.terminalFailureMessage === "string" ? agent.meta.terminalFailureMessage : undefined;
   if (reason === "model-unavailable" && message) return message;
-  const providerState = isPlainRecord(agent.meta.providerState) ? agent.meta.providerState : undefined;
-  const stateReason = typeof providerState?.reason === "string" ? providerState.reason : undefined;
-  const stateMessage = typeof providerState?.message === "string" ? providerState.message : undefined;
-  if (stateReason === "model-unavailable" && stateMessage) return stateMessage;
+  const ps = agentProviderState(agent);
+  if (ps?.reason === "model-unavailable" && ps.message) return ps.message;
   return null;
 }
-
-function isPlainRecord(value: unknown): value is Record<string, unknown> {
-  return Boolean(value) && typeof value === "object" && !Array.isArray(value);
-}

package/src/provider-state.ts

@@ -1,4 +1,5 @@
 import { isRecord } from "agent-relay-sdk";
+import type { ProviderState } from "agent-relay-sdk";
 import { rateLimitFallbackMs } from "./config";
 
 // One server-side home for reading an agent's provider runtime state (the
@@ -7,28 +8,18 @@ import { rateLimitFallbackMs } from "./config";
 // the transient-agent reaper (don't reap a held agent), and the rate-limit
 // resume sweep. The dashboard has its own client-side copy in display.ts.
 
-interface ProviderStateView {
-  state: string;
-  reason?: string;
-  label?: string;
-  /** Unix ms the provider's limit window resets (rate-limit holds). */
-  resetAt?: number;
-  /** Unix ms the hold was entered (used for the resume fallback when resetAt is absent). */
-  enteredAt?: number;
-  /** Raw provider error_type, kept for empirical observation of which type a real limit fires. */
-  errorType?: string;
-  [key: string]: unknown;
-}
+// Re-export so callers don't need to import from two places.
+export type { ProviderState };
 
 interface HasMeta {
   meta?: Record<string, unknown> | null;
 }
 
 /** The agent's provider runtime state, or null when none is set / malformed. */
-export function agentProviderState(agent: HasMeta | null | undefined): ProviderStateView | null {
+export function agentProviderState(agent: HasMeta | null | undefined): ProviderState | null {
   const value = agent?.meta?.providerState;
   if (!isRecord(value) || typeof value.state !== "string") return null;
-  return value as ProviderStateView;
+  return value as ProviderState;
 }
 
 /** True when the agent is in any blocked provider state (rate-limit, approval, model-unavailable). */
@@ -47,16 +38,16 @@ export function isRateLimitHold(agent: HasMeta | null | undefined): boolean {
   return state?.state === "blocked" && state.reason === RATE_LIMIT_BLOCK_REASON;
 }
 
-export function isTransientRateLimitHold(state: ProviderStateView | null): boolean {
+export function isTransientRateLimitHold(state: ProviderState | null): boolean {
   return state?.kind === TRANSIENT_RATE_LIMIT_KIND;
 }
 
-export function transientRateLimitAttempt(state: ProviderStateView | null): number {
+export function transientRateLimitAttempt(state: ProviderState | null): number {
   const raw = state?.resumeAttempt;
   return typeof raw === "number" && Number.isFinite(raw) && raw > 0 ? Math.floor(raw) : 0;
 }
 
-export function transientRateLimitExhausted(state: ProviderStateView | null): boolean {
+export function transientRateLimitExhausted(state: ProviderState | null): boolean {
   return isTransientRateLimitHold(state) && transientRateLimitAttempt(state) >= TRANSIENT_RATE_LIMIT_BACKOFF_MS.length;
 }
 
@@ -69,7 +60,7 @@ export function transientRateLimitExhausted(state: ProviderStateView | null): bo
  * authoritative; otherwise fall back to `enteredAt + fallback window`. Null only
  * when neither is known (shouldn't happen — the runner always stamps enteredAt).
  */
-export function rateLimitResumeAt(state: ProviderStateView | null): number | null {
+export function rateLimitResumeAt(state: ProviderState | null): number | null {
   if (!state) return null;
   if (isTransientRateLimitHold(state)) {
     if (typeof state.nextResumeAt === "number" && Number.isFinite(state.nextResumeAt)) return state.nextResumeAt;

package/src/provider-timeline-event.ts

@@ -0,0 +1,70 @@
+import { isRecord, stringValue } from "agent-relay-sdk";
+import { createActivityEvent } from "./db";
+import { emitRelayEvent } from "./events";
+
+interface HasMeta {
+  meta?: Record<string, unknown> | null;
+}
+
+export interface ProviderTimelineEvent extends Record<string, unknown> {
+  status?: string;
+  timestamp?: number;
+  metadata?: Record<string, unknown>;
+}
+
+/** The provider timeline event latched on the agent card, or null when absent/malformed. */
+export function agentProviderTimelineEvent(agent: HasMeta | null | undefined): ProviderTimelineEvent | null {
+  const value = agent?.meta?.timelineEvent;
+  if (!isRecord(value)) return null;
+  return {
+    ...value,
+    ...(typeof value.status === "string" ? { status: value.status } : {}),
+    ...(typeof value.timestamp === "number" && Number.isFinite(value.timestamp) ? { timestamp: value.timestamp } : {}),
+    ...(isRecord(value.metadata) ? { metadata: value.metadata } : {}),
+  };
+}
+
+function numberValue(value: unknown): number | undefined {
+  return typeof value === "number" && Number.isFinite(value) ? value : undefined;
+}
+
+export function auditRunnerTimelineEvent(agentId: string, timelineEvent: ProviderTimelineEvent | null): void {
+  if (!timelineEvent) return;
+  const metadata = isRecord(timelineEvent.metadata) ? timelineEvent.metadata : {};
+  if (metadata.source !== "runner") return;
+  const status = stringValue(timelineEvent.status);
+  if (!status) return;
+  const eventType = stringValue(metadata.eventType) ?? status;
+  const timestamp = numberValue(timelineEvent.timestamp) ?? Date.now();
+  const id = stringValue(timelineEvent.id) ?? `${eventType}-${timestamp}`;
+  const title = stringValue(timelineEvent.title) ?? status.replace(/[._-]+/g, " ");
+  const body = stringValue(timelineEvent.body);
+  const icon = stringValue(timelineEvent.icon) ?? "ti-activity";
+  try {
+    const event = createActivityEvent({
+      clientId: `runner-timeline-${agentId}-${id}`,
+      kind: "state",
+      title,
+      body,
+      meta: agentId,
+      icon,
+      view: "agents",
+      agentId,
+      metadata: {
+        ...metadata,
+        eventType,
+        timelineStatus: status,
+        timelineId: id,
+        timelineTimestamp: timestamp,
+      },
+    });
+    emitRelayEvent({
+      type: "activity.created",
+      source: "server",
+      subject: String(event.id),
+      data: event as unknown as Record<string, unknown>,
+    });
+  } catch {
+    // Timeline writes must never block status updates.
+  }
+}

package/src/quota-advisory.ts

@@ -1,4 +1,5 @@
 import { isRecord } from "agent-relay-sdk";
+import { quotaWindowMetrics } from "agent-relay-sdk/provider-quota";
 import { getDb } from "./db/connection.ts";
 import { emitRelayEvent } from "./events";
 import { routeNotification } from "./notification-router";
@@ -46,7 +47,7 @@ function handleProviderQuotaAdvisory(input: ProviderQuotaAdvisoryInput): string
 
   for (const window of input.quota.windows) {
     const previousWindow = input.previousQuota?.windows.find((candidate) => candidate.name === window.name);
-    const remaining = quotaRemaining(window.utilization);
+    const remaining = quotaWindowMetrics(window).remaining;
     const remainingPercent = percent(remaining);
     let previous = nextState[window.name];
     const reset = hasLastQuotaAdvisory(previous) && isQuotaReset(remaining, previousWindow, window, config.resetRemaining);
@@ -279,7 +280,7 @@ function crossProviderHeadroomHint(provider: string): string {
     return quota.windows.map((window) => ({
       provider: row.provider,
       window: window.name,
-      remainingPercent: percent(quotaRemaining(window.utilization)),
+      remainingPercent: percent(quotaWindowMetrics(window).remaining),
     }));
   }).sort((a, b) => b.remainingPercent - a.remainingPercent);
   const best = options[0];
@@ -295,17 +296,13 @@ function isQuotaReset(
 ): boolean {
   if (remaining >= resetRemaining) return true;
   if (!previousWindow?.resetsAt || !window.resetsAt || window.resetsAt <= previousWindow.resetsAt) return false;
-  return remaining - quotaRemaining(previousWindow.utilization) >= 0.5 && remaining >= 0.8;
+  return remaining - quotaWindowMetrics(previousWindow).remaining >= 0.5 && remaining >= 0.8;
 }
 
 function quotaRemainingBand(remaining: number, bandSize: number): number {
   return Math.min(100, Math.max(0, percent(Math.ceil((remaining / bandSize) - 1e-9) * bandSize)));
 }
 
-function quotaRemaining(utilization: number): number {
-  return Math.max(0, Math.min(1, 1 - utilization));
-}
-
 function percent(value: number): number {
   return Math.round(value * 100);
 }