agent-relay-runner 0.97.0 → 0.98.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-relay-runner",
-  "version": "0.97.0",
+  "version": "0.98.0",
   "description": "Unified provider lifecycle runner for Agent Relay",
   "type": "module",
   "bin": {
@@ -20,7 +20,7 @@
     "directory": "runner"
   },
   "dependencies": {
-    "agent-relay-sdk": "0.2.77"
+    "agent-relay-sdk": "0.2.78"
   },
   "devDependencies": {
     "@types/bun": "latest",

package/plugins/claude/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "agent-relay-runner",
   "description": "Thin Agent Relay runner bridge for Claude Code",
-  "version": "0.97.0",
+  "version": "0.98.0",
   "agentRelayContracts": {
     "providerPluginProtocol": 1
   }

package/src/adapter.ts

@@ -1,5 +1,6 @@
-import type { AgentProfile, Message } from "agent-relay-sdk";
+import type { AgentProfile, LivenessSignal, Message } from "agent-relay-sdk";
 import { isRecord } from "agent-relay-sdk";
+import type { LivenessInputs } from "./liveness";
 import type { SessionEvent } from "./session-insights";
 import { messageBodyMaxCharsFromEnv } from "./config";
 import { relayReplyReminderText } from "./relay-instructions";
@@ -191,6 +192,13 @@ export interface ProviderAdapter {
   // (Codex app-server item events). Claude mirrors via hooks/transcript instead,
   // so it leaves this unimplemented.
   onSessionEvent?(cb: (event: ProviderSessionEvent) => void): void;
+  // §4.1 of the Runner↔provider contract (#725 / #746): fold the runner-tracked raw
+  // transport/timeline/token/work-kind signals into ONE normalized LivenessSignal the
+  // server reads instead of six raw `meta` fields. Each adapter owns what counts as
+  // progress for its provider (Claude #713 timeline transitions; Codex #724 live
+  // subprocess work). Optional so test/mock adapters fall back to the shared
+  // {@link computeLivenessSignal} fold — the runner always has a verdict to ship.
+  liveness?(inputs: LivenessInputs): LivenessSignal;
   // Headless providers with no tmux session (e.g. the Codex app-server) still
   // warrant an automatic restart on unexpected exit. Returning true opts the
   // provider into the runner's restart-with-backoff path.

package/src/adapters/claude.ts

@@ -7,6 +7,8 @@ import { shellEscape as shellQuote } from "agent-relay-sdk/shell-utils";
 import { tmuxCommand, tmuxHasSession } from "agent-relay-sdk/tmux-utils";
 import { sanitizeFsName } from "agent-relay-sdk/fs-name";
 import { profileAllowsRelayFeature, type ManagedProcess, type ProviderAdapter, type ProviderConfig, type ProviderStatusUpdate, type RunnerSpawnConfig, type SemanticStatus, type SpawnArgs } from "../adapter";
+import { computeLivenessSignal, type LivenessInputs } from "../liveness";
+import type { LivenessSignal } from "agent-relay-sdk";
 import { collectClaudeSessionEvents } from "./claude-transcript";
 import type { SessionEvent } from "../session-insights";
 import { prepareClaudeProfileHome, profileUsesClaudeHostProviderGlobals } from "../profile-home";
@@ -31,6 +33,16 @@ export class ClaudeAdapter implements ProviderAdapter {
     this.statusCb = cb;
   }
 
+  // §4.1 contract verdict (#746). Claude reference (#713): Claude is token-silent during
+  // native compaction, but the runner publishes a `compacting` timeline transition while it
+  // runs — so `timelineEvent.timestamp` (folded into lastProgressAt) keeps a compacting Opus
+  // turn reading as progressing instead of wedged. Transport frames/acks + the server's
+  // lastSeen floor cover long token-silent thinking turns. The fold itself is shared; this
+  // override exists to document and own Claude's progress sources behind the contract.
+  liveness(inputs: LivenessInputs): LivenessSignal {
+    return computeLivenessSignal(inputs);
+  }
+
   async spawn(config: RunnerSpawnConfig): Promise<ManagedProcess> {
     const args = this.buildSpawnArgs(config, config.providerConfig as ProviderConfig);
 

package/src/adapters/codex.ts

@@ -1,7 +1,7 @@
 import { accessSync, constants, existsSync, readFileSync, realpathSync, readdirSync } from "node:fs";
 import { homedir } from "node:os";
 import { basename, join, resolve } from "node:path";
-import type { ContextState, Message } from "agent-relay-sdk";
+import type { ContextState, LivenessSignal, Message } from "agent-relay-sdk";
 import { isRecord, stringValue } from "agent-relay-sdk";
 import { isPidAlive, killPid, processTreePids, processTreePidsFromTable, waitForPidsExit } from "agent-relay-sdk/process-utils";
 import { profileAllowsRelayFeature, providerMessageText, RELAY_CONTEXT, type ManagedProcess, type ProviderAdapter, type ProviderConfig, type ProviderPermissionDecisionInput, type ProviderSessionEvent, type ProviderStatusUpdate, type RunnerSpawnConfig, type SpawnArgs, type TerminalAttachSpec } from "../adapter";
@@ -11,6 +11,7 @@ import { assembleLaunch, bundledCodexSkillDirs, bundledSkillConfigArgs, material
 import { logger } from "../logger";
 import type { SessionEvent } from "../session-insights";
 import { CodexAgentMessageCapture } from "./codex-agent-message-capture";
+import { computeLivenessSignal, type LivenessInputs } from "../liveness";
 
 /** Relay context prepended to a Codex agent's first turn: the standard relay
  * blurb plus, when running in an isolated workspace, the deps caveat (#159). */
@@ -68,6 +69,16 @@ export class CodexAdapter implements ProviderAdapter {
     this.statusCb = cb;
   }
 
+  // §4.1 contract verdict (#746). Codex reference (#724): a Codex provider-turn can wedge
+  // while a long-running subprocess child (a `bun test` / build gate) is still alive and
+  // making real progress. That subprocess is tracked as a non-`provider-turn` work-kind, so
+  // `hasLiveWork` stays true and the turn is never mis-read as stuck; app-server item events
+  // also refresh `lastProviderEventAt` → lastProgressAt. The fold is shared; this override
+  // documents and owns Codex's progress sources behind the contract.
+  liveness(inputs: LivenessInputs): LivenessSignal {
+    return computeLivenessSignal(inputs);
+  }
+
   onSessionEvent(cb: (event: ProviderSessionEvent) => void): void {
     this.sessionEventCb = cb;
   }

package/src/liveness.ts

@@ -0,0 +1,50 @@
+import type { LivenessSignal } from "agent-relay-sdk";
+
+// The raw runner-tracked signals an adapter folds into a normalized LivenessSignal.
+// This is the INPUT to the contract computation (#746): the runner owns this state
+// (transport frames, the last provider event, the pending timeline transition, the
+// active-work set), passes it to the adapter's `liveness()` verdict, and ships the
+// resulting LivenessSignal on the agent card. Provider-raw interpretation stops here —
+// nothing above the runner ever reads these fields again.
+export interface LivenessInputs {
+  /** Runner→server transport frame/ack timestamps (sdk BusClient.transportState). */
+  transport?: { lastServerFrameAt?: number; lastHeartbeatAckAt?: number };
+  /** Epoch-ms of the most recent provider status/token event the runner observed. */
+  lastProviderEventAt?: number;
+  /** The most recent lifecycle/timeline transition the runner published (status + ts). */
+  timelineEvent?: { status?: string; timestamp?: number };
+  /** Active work records. The adapter classifies its own kinds; `provider-turn` is the
+   *  bare turn, anything else (subagent, background-script, tool, subprocess) is live work. */
+  activeWork: Array<{ kind?: string; startedAt?: number }>;
+  /** Fallback progress floor when no other progress evidence exists yet (e.g. work start). */
+  fallbackProgressAt?: number;
+}
+
+function num(value: unknown): number {
+  return typeof value === "number" && Number.isFinite(value) ? value : 0;
+}
+
+/**
+ * The shared liveness fold (#725 / #746). Both reference adapters (Claude #713, Codex #724)
+ * route through this so the verdict is computed in ONE place; each adapter's `liveness()`
+ * decides WHICH raw signals it feeds in (Claude surfaces a `compacting` timeline transition
+ * as progress; Codex surfaces live subprocess work-kinds). The fold itself is provider-
+ * agnostic, which is the point of the contract: a new provider only has to feed its signals.
+ */
+export function computeLivenessSignal(inputs: LivenessInputs): LivenessSignal {
+  const transportLiveAt = Math.max(
+    num(inputs.transport?.lastServerFrameAt),
+    num(inputs.transport?.lastHeartbeatAckAt),
+  );
+  // Progress = provider tokens OR a lifecycle/timeline transition (e.g. native compaction,
+  // #713) — whichever is latest, with the caller-supplied floor as the baseline.
+  const lastProgressAt = Math.max(
+    num(inputs.lastProviderEventAt),
+    num(inputs.timelineEvent?.timestamp),
+    num(inputs.fallbackProgressAt),
+  );
+  // Any work-kind that is NOT the bare provider turn is live tool/subprocess work (#724):
+  // a wedged provider turn with a live `bun test` child must read as progressing.
+  const hasLiveWork = inputs.activeWork.some((work) => Boolean(work.kind && work.kind !== "provider-turn"));
+  return { transportLiveAt, lastProgressAt, hasLiveWork };
+}

package/src/quota.ts

@@ -17,6 +17,8 @@ export {
   collectCodexQuotaSample,
   collectCodexQuotaState,
   codexRateLimitsQuotaState,
+  codexWhamResetCredits,
+  codexWhamUsageQuotaState,
   credentialAccountKey,
   defaultClaudeConfigDir,
   defaultClaudeCredentialsPath,

package/src/runner-core.ts

@@ -7,6 +7,7 @@ import { errMessage, RelayBusClient, RelayHttpClient } from "agent-relay-sdk";
 import { contextStateFromProbeMetrics, quotaStateFromProbeMetrics } from "agent-relay-sdk/context-probe";
 import { isPidAlive } from "agent-relay-sdk/process-utils";
 import { providerAttachmentText, providerMessageText } from "./adapter";
+import { computeLivenessSignal, type LivenessInputs } from "./liveness";
 import type { ManagedProcess, ProviderAdapter, ProviderConfig, ProviderPermissionDecision, ProviderPermissionDecisionInput, ProviderSessionEvent, ProviderStatusUpdate, RunnerSpawnConfig, SemanticStatus, TerminalAttachSpec } from "./adapter";
 import { messagesWithCachedAttachments } from "./attachment-cache";
 import { ClaimTracker } from "./claim-tracker";
@@ -1878,6 +1879,19 @@ export class AgentRunner {
     this.bus.setSemanticStatus(status === "offline" || status === "error" ? "idle" : status);
     const timelineEvent = this.pendingTimelineEvent;
     this.pendingTimelineEvent = undefined;
+    // §4.1 Runner↔provider liveness contract (#725 / #746): fold the raw transport/timeline/
+    // token/work-kind signals into ONE normalized verdict the server reads instead of six raw
+    // `meta` fields. The adapter owns what counts as progress for its provider (#713/#724);
+    // mock adapters fall back to the shared fold.
+    const livenessInputs: LivenessInputs = {
+      transport: this.bus.transportState,
+      ...(this.lastProviderEventAt !== undefined ? { lastProviderEventAt: this.lastProviderEventAt } : {}),
+      ...(timelineEvent ? { timelineEvent } : {}),
+      activeWork,
+    };
+    const liveness = this.options.adapter.liveness
+      ? this.options.adapter.liveness(livenessInputs)
+      : computeLivenessSignal(livenessInputs);
     this.bus.status({
       agentStatus,
       ready: agentStatus !== "offline" && !this.stopped,
@@ -1922,6 +1936,9 @@ export class AgentRunner {
         },
         ...(timelineEvent ? { timelineEvent } : {}),
         transport: this.bus.transportState,
+        // #746 — normalized liveness verdict; the server reads ONLY this for stuck-busy.
+        // The raw fields above stay for other consumers (timeline rendering, diagnostics).
+        liveness,
       },
     });
   }