agent-relay-server 0.99.0 → 0.100.0

package/runner/src/adapter.ts

@@ -1,4 +1,4 @@
-import type { AgentProfile, LivenessSignal, Message } from "agent-relay-sdk";
+import type { AgentProfile, LivenessSignal, Message, ProviderState } from "agent-relay-sdk";
 import { isRecord } from "agent-relay-sdk";
 import type { LivenessInputs } from "./liveness";
 import type { SessionEvent } from "./session-insights";
@@ -30,7 +30,7 @@ export interface ProviderStatusEvent {
   // runner reconciles them against actual liveness and clears the busy marker if
   // every pid is dead — recovering from a tracked process killed out-of-band.
   pids?: number[];
-  providerState?: Record<string, unknown>;
+  providerState?: ProviderState;
   metadata?: Record<string, unknown>;
 }
 

package/src/agent-death-diagnosis.ts

@@ -6,7 +6,6 @@
 // deterministic and unit-testable per failure mode. The output rides the #633 terminal event and
 // is persisted as a CrashReport so the WHY survives the reaper.
 
-import { extractClaudeModelUnavailableMessage } from "agent-relay-sdk";
 import type { AgentCard, AgentDeathCause, AgentDeathDiagnosis, CrashReport, ManagedSessionExitDiagnostics } from "./types";
 
 export interface DeathEvidence {
@@ -87,6 +86,16 @@ function haystack(ev: DeathEvidence): string {
   return parts.join("\n");
 }
 
+function terminalModelUnavailableMessage(meta: Record<string, unknown> | undefined): string | undefined {
+  const terminalReason = str(meta?.terminalFailureReason);
+  const terminalMessage = str(meta?.terminalFailureMessage);
+  if (terminalReason === "model-unavailable" && terminalMessage) return terminalMessage;
+  const providerState = record(meta, "providerState");
+  const stateReason = str(providerState?.reason);
+  const stateMessage = str(providerState?.message);
+  return stateReason === "model-unavailable" && stateMessage ? stateMessage : undefined;
+}
+
 function logTailOf(ev: DeathEvidence): string[] | undefined {
   if (ev.exit?.logTail?.length) return ev.exit.logTail;
   const lastExit = record(ev.agentMeta, "lastExit");
@@ -159,8 +168,8 @@ export function classifyAgentDeath(ev: DeathEvidence): AgentDeathDiagnosis {
     return verdict("onboarding-gate", fast ? "high" : "medium", "Stuck at a first-run onboarding/trust gate");
   }
 
-  // 4) provider-crash — CLI panic/segfault/model-unavailable, or a crash signal.
-  const modelUnavailable = extractClaudeModelUnavailableMessage(text);
+  // 4) provider-crash — CLI panic/segfault/adapter-classified model-unavailable, or a crash signal.
+  const modelUnavailable = terminalModelUnavailableMessage(ev.agentMeta);
   if (modelUnavailable) {
     pushUnique(evidence, modelUnavailable);
     return verdict("provider-crash", "high", "Provider unavailable (model/CLI error)");

package/src/bus.ts

@@ -1,5 +1,5 @@
 import type { Server, ServerWebSocket } from "bun";
-import { ValidationError, createActivityEvent, getAgent, getDb, heartbeat, markReady, mergeAgentMeta, orphanTasksForAgent, revokeRuntimeTokensForAgent, setStatus, validateAgentSession } from "./db";
+import { ValidationError, getAgent, getDb, heartbeat, markReady, mergeAgentMeta, orphanTasksForAgent, revokeRuntimeTokensForAgent, setStatus, validateAgentSession } from "./db";
 import { getOldestOutboxCursor, getOutboxCursor, replayEvents, type BusEvent } from "./bus-outbox";
 import { projectAgentStatusData } from "./agent-card-projection";
 import { emitRelayEvent, subscribeRelayEvents, type RelayEvent } from "./events";
@@ -11,6 +11,7 @@ import { registerAgent } from "./services/register-agent";
 import { authContextFromBus } from "./services/auth-context";
 import { commandAuthorizationResource, dispatchCommand } from "./services/dispatch-command";
 import { auditProviderStateTransition } from "./services/provider-state-audit";
+import { agentProviderTimelineEvent, auditRunnerTimelineEvent } from "./provider-timeline-event";
 import { ServiceAuthError } from "./services/errors";
 import { ShutdownAuthError, ShutdownTargetError, shutdownAgent, shutdownInputFromBusFrame } from "./services/shutdown-agent";
 import { flushQueuedDirectMessages } from "./services/managed-running";
@@ -28,7 +29,7 @@ import {
   type BusFrame,
   type RegisterFrame,
 } from "agent-relay-sdk/protocol";
-import { errMessage, isRecord, stringValue } from "agent-relay-sdk";
+import { errMessage, isRecord } from "agent-relay-sdk";
 import { getComponentAuth, isComponentAuthorizedFor, isAuthorized, isOriginAllowed, unauthorized } from "./security";
 import type { Command, ComponentToken, ContextState, Message, ProviderCapabilities, QuotaState, RegisterAgentInput, Task } from "./types";
 
@@ -189,10 +190,11 @@ function handleFrame(ws: BusWebSocket, frame: ReturnType<typeof validateClientFr
         }
         const after = getAgent(conn.agentId);
         auditProviderStateTransition(conn.agentId, before, after);
-        auditRunnerTimelineEvent(conn.agentId, after?.meta?.timelineEvent);
+        const timelineEvent = agentProviderTimelineEvent(after);
+        auditRunnerTimelineEvent(conn.agentId, timelineEvent);
         // A real PreCompact/SessionStart hook arrives as a timelineEvent in the
         // merged meta — clears any pending stall watch (stale events ignored).
-        noteAgentTimelineEvent(conn.agentId, after?.meta?.timelineEvent);
+        noteAgentTimelineEvent(conn.agentId, timelineEvent);
         emitAgentStatusEvent(conn.agentId);
         // #237 stop-hook → instant ⚪↔🟡 changes detection on the turn-end edge.
         probeWorkspaceOnTurnEnd(before, after);
@@ -568,47 +570,6 @@ function emitAgentStatusEvent(agentId: string): void {
   });
 }
 
-function auditRunnerTimelineEvent(agentId: string, timelineEvent: unknown): void {
-  if (!isRecord(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 bus status updates.
-  }
-}
-
 function sendCommandResult(
   ws: BusWebSocket,
   commandId: string,

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,3 +1,4 @@
+import { 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;
@@ -78,7 +79,7 @@ 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));

package/src/db/provider-quotas.ts

@@ -403,11 +403,12 @@ function mergeQuotaWindows(existing: StoredQuotaState | undefined, incoming: Quo
       mergedTimes.set(key, incoming.updatedAt); mergedSources.set(key, incoming.source);
       return incomingWindow;
     }
-    // Same-priority sources: prefer the newer reading and guard against an improbable regression.
+    // Same-priority sources: prefer the newer reading. Keep the regression guard for noisy
+    // self-reports, but let authoritative API ingest correct a stale/maxed WHAM sample (#750).
     if (incoming.updatedAt < existingUpdatedAt) {
       mergedTimes.set(key, existingUpdatedAt); mergedSources.set(key, existingSource); return window;
     }
-    if (quotaWindowUtilizationRegressed(window, incomingWindow)) {
+    if (incoming.source !== "ingest" && quotaWindowUtilizationRegressed(window, incomingWindow)) {
       mergedTimes.set(key, existingUpdatedAt); mergedSources.set(key, existingSource); return window;
     }
     acceptedIncomingWindow = true;

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);
 }

package/src/routes/agent-sessions.ts

@@ -13,6 +13,7 @@ import { emitAgentStatus, emitDashboardPresence, emitNewMessage } from "../sse";
 import { getAgentProfile, getSpawnPolicy } from "../config-store";
 import { listManagedOrchestratorsForAgent } from "../orchestrator-lookup";
 import { runnerRuntimeTokenEnv } from "../runtime-tokens";
+import { agentProviderState } from "../provider-state";
 import { authContextFromRequest } from "../services/auth-context";
 import { ShutdownAuthError, ShutdownTargetError, shutdownAgent } from "../services/shutdown-agent";
 import { type AgentCard, type SpawnApprovalMode } from "../types";
@@ -414,8 +415,9 @@ export const postAgentPermissionDecision: Handler = async (req, params) => {
     const arb = arbitrateDrive(requestUserId(req), agent.id);
     if (!arb.allowed) return driveBlockedResponse(arb);
     if (!agentIsControlEligible(agent)) return error("agent cannot receive permission decisions", 400);
-    const pendingApproval = isRecord(agent.meta?.providerState) && isRecord(agent.meta.providerState.pendingApproval)
-      ? agent.meta.providerState.pendingApproval
+    const providerState = agentProviderState(agent);
+    const pendingApproval = isRecord(providerState?.pendingApproval)
+      ? providerState.pendingApproval
       : null;
     const pendingId = typeof pendingApproval?.id === "string" ? pendingApproval.id : "";
     if (pendingId && pendingId !== approvalId) return error("approval request is no longer current", 409);