agent-relay-server 0.121.5 → 0.122.1

package/runner/src/provisioning.ts

@@ -0,0 +1,314 @@
+import { existsSync, mkdirSync, readFileSync, readdirSync, rmSync, symlinkSync, writeFileSync } from "node:fs";
+import { dirname, isAbsolute, join, resolve } from "node:path";
+import { sanitizeFsName } from "agent-relay-sdk/fs-name";
+import type { ProvisioningAssetFile, ProvisioningMcpServer, ResolvedProvisioning } from "agent-relay-sdk";
+import type { RunnerSpawnConfig } from "./adapter";
+import { profileAllowsHostAssets, providerSourceHome } from "./profile-home";
+
+// Runner-side materialization of the relay-resolved provisioning bundle
+// (#554/#555/#556). The relay resolves a profile's refs against the DB registry and
+// attaches the concrete definitions to profile.provisioning; here we turn those into
+// real on-disk dirs (skills/plugins). MCP is handled in relay-mcp.ts.
+//
+// #557 — split into PURE RESOLUTION (resolve* → where each asset lands, no writes) and
+// MATERIALIZATION (materialize* → the disk writes). The single launch assembler
+// (launch-assembly.ts) calls the resolvers to build BOTH the launch args and the
+// projection report, so what's reported can never drift from what's written; the
+// materialize* writers consume the same resolved entries, so what's written can never
+// drift from what's reported either. One resolution, three consumers.
+
+const EMPTY: ResolvedProvisioning = { skills: [], plugins: [], mcpServers: {} };
+
+export function profileProvisioning(config: Pick<RunnerSpawnConfig, "agentProfile">): ResolvedProvisioning {
+  const p = config.agentProfile?.provisioning;
+  if (!p) return EMPTY;
+  return { skills: p.skills ?? [], plugins: p.plugins ?? [], mcpServers: p.mcpServers ?? {}, ...(p.skipped?.length ? { skipped: p.skipped } : {}) };
+}
+
+// The `mcpServers` keys a Claude `.mcp.json` entry may carry; coerced into the
+// provider-neutral ProvisioningMcpServer shape so the launch assembler projects them the
+// same way it does relay-provisioned servers (Claude `--mcp-config`, Codex `-c mcp_servers.*`).
+function coerceProjectMcpServer(raw: unknown): ProvisioningMcpServer | null {
+  if (!raw || typeof raw !== "object") return null;
+  const r = raw as Record<string, unknown>;
+  const server: ProvisioningMcpServer = {};
+  if (r.type === "stdio" || r.type === "http" || r.type === "sse") server.type = r.type;
+  if (typeof r.command === "string") server.command = r.command;
+  if (Array.isArray(r.args) && r.args.every((a) => typeof a === "string")) server.args = r.args as string[];
+  if (r.env && typeof r.env === "object") server.env = r.env as Record<string, string>;
+  if (r.configEnv && typeof r.configEnv === "object") server.configEnv = r.configEnv as Record<string, string>;
+  if (typeof r.url === "string") server.url = r.url;
+  if (r.headers && typeof r.headers === "object") server.headers = r.headers as Record<string, string>;
+  // Drop an entry that names no transport (neither a command nor a url) — nothing to launch.
+  return server.command || server.url ? server : null;
+}
+
+// #667 — project `.mcp.json` MCP projection. OPT-IN via the resolved profile's `projectMcp`
+// (set per-spawn or by profile, relay-side). Reads the spawn cwd's COMMITTED `.mcp.json` and
+// returns its `mcpServers` as a provider-neutral record, so the launch assembler injects them
+// through the CONTROLLED `--mcp-config` (Claude) / `-c mcp_servers.*` (Codex) path that
+// survives `--strict-mcp-config` — the project's own servers travel with the repo like they do
+// for a human who clones it, WITHOUT enabling Claude's ambient project-discovery trust modal
+// (which wedges headless agents, the reason #662 made every managed launch strict). The runner
+// is the filesystem authority for the spawn cwd (relay may run on another host), so the read
+// lands here. Best-effort: a missing/malformed file (or one with no `mcpServers`) yields {} and
+// never aborts the launch. Returns {} when projection is OFF.
+export function resolveProjectMcpServers(
+  config: Pick<RunnerSpawnConfig, "agentProfile" | "cwd">,
+): Record<string, ProvisioningMcpServer> {
+  if (!config.agentProfile?.projectMcp) return {};
+  const file = join(config.cwd, ".mcp.json");
+  if (!existsSync(file)) return {};
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(readFileSync(file, "utf8"));
+  } catch (err) {
+    console.warn(`project .mcp.json projection: failed to parse ${file}: ${(err as Error).message}`);
+    return {};
+  }
+  const servers = (parsed as { mcpServers?: unknown } | null)?.mcpServers;
+  if (!servers || typeof servers !== "object") return {};
+  const out: Record<string, ProvisioningMcpServer> = {};
+  for (const [name, raw] of Object.entries(servers as Record<string, unknown>)) {
+    const server = coerceProjectMcpServer(raw);
+    if (server) out[name] = server;
+  }
+  return out;
+}
+
+export function resolveClaudeProjectSkills(
+  claudeHome: string,
+  config: Pick<RunnerSpawnConfig, "agentProfile" | "cwd">,
+  reservedNames: ReadonlySet<string> = new Set(),
+): ResolvedAsset[] {
+  if (!config.agentProfile?.projectSkills) return [];
+  const skillsRoot = join(config.cwd, ".claude", "skills");
+  if (!existsSync(skillsRoot)) return [];
+  const targetRoot = join(claudeHome, "skills");
+  const resolved: ResolvedAsset[] = [];
+  for (const entry of readdirSync(skillsRoot, { withFileTypes: true })) {
+    if (!entry.isDirectory() || reservedNames.has(entry.name)) continue;
+    const source = join(skillsRoot, entry.name);
+    if (!existsSync(join(source, "SKILL.md"))) continue;
+    resolved.push({
+      name: entry.name,
+      dir: join(targetRoot, assetDirName(entry.name)),
+      source: { kind: "link", source },
+    });
+  }
+  return resolved.sort((a, b) => a.name.localeCompare(b.name));
+}
+
+export function resolveClaudeHostSkills(
+  claudeHome: string,
+  config: Pick<RunnerSpawnConfig, "agentProfile">,
+  reservedNames: ReadonlySet<string> = new Set(),
+): ResolvedAsset[] {
+  if (!profileAllowsHostAssets(config, "skills")) return [];
+  const skillsRoot = join(providerSourceHome("claude"), "skills");
+  if (!existsSync(skillsRoot)) return [];
+  const targetRoot = join(claudeHome, "skills");
+  const resolved: ResolvedAsset[] = [];
+  for (const entry of readdirSync(skillsRoot, { withFileTypes: true })) {
+    if (!entry.isDirectory() || reservedNames.has(entry.name)) continue;
+    const source = join(skillsRoot, entry.name);
+    if (!existsSync(join(source, "SKILL.md"))) continue;
+    resolved.push({
+      name: entry.name,
+      dir: join(targetRoot, assetDirName(entry.name)),
+      source: { kind: "link", source },
+    });
+  }
+  return resolved.sort((a, b) => a.name.localeCompare(b.name));
+}
+
+const UNSAFE_PROJECT_CLAUDE_SETTINGS = new Set([
+  "apiKeyHelper",
+  "allowDangerouslySkipPermissions",
+  "allowedTools",
+  "disabledMcpjsonServers",
+  "disallowedTools",
+  "enableAllProjectMcpServers",
+  "enabledMcpjsonServers",
+  "env",
+  "hooks",
+  "mcpServers",
+  "permissionMode",
+  "permissions",
+  "statusLine",
+  "tools",
+]);
+
+export interface ResolvedProjectClaudeSettings {
+  applied: boolean;
+  settings: Record<string, unknown>;
+  keys: string[];
+  ignoredKeys: string[];
+  file?: string;
+}
+
+export function resolveProjectClaudeSettings(
+  config: Pick<RunnerSpawnConfig, "agentProfile" | "cwd">,
+): ResolvedProjectClaudeSettings {
+  if (!config.agentProfile?.projectSettings) return { applied: false, settings: {}, keys: [], ignoredKeys: [] };
+  const file = join(config.cwd, ".claude", "settings.json");
+  if (!existsSync(file)) return { applied: true, settings: {}, keys: [], ignoredKeys: [], file };
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(readFileSync(file, "utf8"));
+  } catch (err) {
+    console.warn(`project .claude/settings.json projection: failed to parse ${file}: ${(err as Error).message}`);
+    return { applied: true, settings: {}, keys: [], ignoredKeys: [], file };
+  }
+  if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+    return { applied: true, settings: {}, keys: [], ignoredKeys: [], file };
+  }
+  const settings: Record<string, unknown> = {};
+  const ignoredKeys: string[] = [];
+  for (const [key, value] of Object.entries(parsed as Record<string, unknown>)) {
+    if (UNSAFE_PROJECT_CLAUDE_SETTINGS.has(key)) {
+      ignoredKeys.push(key);
+      continue;
+    }
+    settings[key] = value;
+  }
+  return {
+    applied: true,
+    settings,
+    keys: Object.keys(settings).sort(),
+    ignoredKeys: ignoredKeys.sort(),
+    file,
+  };
+}
+
+// A resolved provisioning asset: WHERE it lands (`dir`) and HOW it materializes
+// (`source`). `files` writes the inline set into `dir`; `link` symlinks a pre-existing
+// source dir at `dir`; `inPlace` uses the source dir as-is (no write, dir IS the source).
+export type ResolvedAssetSource =
+  | { kind: "files"; files: ProvisioningAssetFile[] }
+  | { kind: "link"; source: string }
+  | { kind: "inPlace" };
+export interface ResolvedAsset {
+  name: string;
+  dir: string;
+  source: ResolvedAssetSource;
+}
+
+function assetDirName(name: string): string {
+  return sanitizeFsName(name, { replacement: "-", collapse: false, maxLen: 120, fallback: "asset" });
+}
+
+function resolveExistingDir(dir: string, cwd: string): string | null {
+  const abs = isAbsolute(dir) ? dir : resolve(cwd, dir);
+  return existsSync(abs) ? abs : null;
+}
+
+function hasRootSkillManifest(files: ProvisioningAssetFile[]): boolean {
+  return files.some((f) => f.path === "SKILL.md");
+}
+
+// Write an inline file set into <dir>, guarding against path escapes from a malformed
+// registry entry. Shared by every files-source materialization.
+function writeInlineFiles(dir: string, files: ProvisioningAssetFile[]): void {
+  mkdirSync(dir, { recursive: true });
+  for (const file of files) {
+    const dest = resolve(dir, file.path);
+    if (!dest.startsWith(resolve(dir))) continue;
+    mkdirSync(dirname(dest), { recursive: true });
+    writeFileSync(dest, file.content, { mode: 0o600 });
+  }
+}
+
+// Perform the disk write a resolved asset describes. files → write inline; link →
+// (re)create the symlink; inPlace → nothing (the dir already exists at the source).
+// Best-effort for links: a failed link must not abort the launch.
+function materializeAsset(asset: ResolvedAsset): boolean {
+  if (asset.source.kind === "files") {
+    writeInlineFiles(asset.dir, asset.source.files);
+    return true;
+  }
+  if (asset.source.kind === "link") {
+    try {
+      mkdirSync(dirname(asset.dir), { recursive: true });
+      if (existsSync(asset.dir)) rmSync(asset.dir, { recursive: true, force: true });
+      symlinkSync(asset.source.source, asset.dir);
+      return true;
+    } catch {
+      return false;
+    }
+  }
+  return existsSync(asset.dir);
+}
+
+// #554 (Claude) — each provisioned skill lands at <claudeHome>/skills/<name> so it's
+// auto-discovered under the launch's `--setting-sources "user"` scope (host skills
+// never bleed). Inline files are written there; a pre-existing dir is symlinked in.
+export function resolveClaudeProvisionedSkills(claudeHome: string, config: RunnerSpawnConfig): ResolvedAsset[] {
+  const { skills } = profileProvisioning(config);
+  const skillsRoot = join(claudeHome, "skills");
+  const resolved: ResolvedAsset[] = [];
+  for (const skill of skills) {
+    const dir = join(skillsRoot, assetDirName(skill.name));
+    if (skill.files?.length) {
+      resolved.push({ name: skill.name, dir, source: { kind: "files", files: skill.files } });
+      continue;
+    }
+    if (skill.dir) {
+      const source = resolveExistingDir(skill.dir, config.cwd);
+      if (source) resolved.push({ name: skill.name, dir, source: { kind: "link", source } });
+    }
+  }
+  return resolved;
+}
+
+// #556 (Claude) — each provisioned plugin resolves to a --plugin-dir. Inline plugins
+// materialize under <claudeHome>/relay-provisioned-plugins/<name>; declared dirs are
+// used in place. The resolved `dir` is appended to the launch's --plugin-dir set.
+export function resolveClaudeProvisionedPlugins(claudeHome: string, config: RunnerSpawnConfig): ResolvedAsset[] {
+  const { plugins } = profileProvisioning(config);
+  const parent = join(claudeHome, "relay-provisioned-plugins");
+  const resolved: ResolvedAsset[] = [];
+  for (const plugin of plugins) {
+    if (plugin.files?.length) {
+      resolved.push({ name: plugin.name, dir: join(parent, assetDirName(plugin.name)), source: { kind: "files", files: plugin.files } });
+      continue;
+    }
+    if (plugin.dir) {
+      const source = resolveExistingDir(plugin.dir, config.cwd);
+      if (source) resolved.push({ name: plugin.name, dir: source, source: { kind: "inPlace" } });
+    }
+  }
+  return resolved;
+}
+
+// #554 (Codex) — each provisioned skill resolves to a dir for `-c skills.config`.
+// Inline skills materialize under <codexHome>/relay-provisioned-skills/<name>; declared
+// dirs are used in place. Codex requires a SKILL.md at the dir root to register it, so
+// inline sets without one and dirs missing it are dropped at resolution time.
+export function resolveCodexProvisionedSkills(codexHome: string, config: RunnerSpawnConfig): ResolvedAsset[] {
+  const { skills } = profileProvisioning(config);
+  const parent = join(codexHome, "relay-provisioned-skills");
+  const resolved: ResolvedAsset[] = [];
+  for (const skill of skills) {
+    if (skill.files?.length) {
+      if (!hasRootSkillManifest(skill.files)) continue;
+      resolved.push({ name: skill.name, dir: join(parent, assetDirName(skill.name)), source: { kind: "files", files: skill.files } });
+      continue;
+    }
+    if (skill.dir) {
+      const source = resolveExistingDir(skill.dir, config.cwd);
+      if (source && existsSync(join(source, "SKILL.md"))) resolved.push({ name: skill.name, dir: source, source: { kind: "inPlace" } });
+    }
+  }
+  return resolved;
+}
+
+// Write the resolved assets to disk; returns the dirs that materialized successfully,
+// in resolution order. Idempotent — safe to re-run against an existing home.
+export function materializeResolvedAssets(assets: ResolvedAsset[]): string[] {
+  const dirs: string[] = [];
+  for (const asset of assets) {
+    if (materializeAsset(asset)) dirs.push(asset.dir);
+  }
+  return dirs;
+}

package/runner/src/quota.ts

@@ -0,0 +1,40 @@
+export {
+  CLAUDE_OAUTH_BETA,
+  CLAUDE_API_VERSION,
+  CLAUDE_MESSAGES_URL,
+  CLAUDE_QUOTA_PROBE_MODEL,
+  CLAUDE_USAGE_URL,
+  DEFAULT_PROVIDER_QUOTA_CONFIG,
+  QUOTA_FAILURE_LOG_INTERVAL_MS,
+  QUOTA_FAST_RETRY_MS,
+  QUOTA_POLL_INTERVAL_MS,
+  QuotaCollectionError,
+  QuotaRetryAfterError,
+  claudeRateLimitHeadersQuotaState,
+  claudeUsageQuotaState,
+  collectClaudeQuotaSample,
+  collectClaudeQuotaState,
+  collectCodexQuotaSample,
+  collectCodexQuotaState,
+  codexRateLimitsQuotaState,
+  codexWhamResetCredits,
+  codexWhamUsageQuotaState,
+  credentialAccountKey,
+  defaultClaudeConfigDir,
+  defaultClaudeCredentialsPath,
+  hostProviderAccountKey,
+  normalizeProviderQuotaConfig,
+  providerPayloadAccountKey,
+  providerQuotaErrorFromCollectorError,
+  quotaRetryAfterMs,
+  readClaudeOAuthAccessToken,
+  resolveClaudeQuotaIdentity,
+  resolveClaudeStatuslineQuotaIdentity,
+  resolveCodexQuotaIdentity,
+  resolveCodexQuotaIdentityFromHome,
+  resolveStableClaudeQuotaIdentity,
+  resolveStableCodexQuotaIdentity,
+  resolveStableCodexQuotaIdentityFromHome,
+  type ProviderQuotaIdentity,
+  type ProviderQuotaSample,
+} from "agent-relay-sdk/provider-quota";

package/runner/src/rate-limit.ts

@@ -0,0 +1,189 @@
+// #286 — shared rate-limit hold construction + Claude pane detection.
+//
+// Two detection arms feed the SAME provider-neutral `blocked` hold:
+//   1. The StopFailure hook (clean API-error turn-end: API-429/auth/billing) → control-server.
+//   2. Pane-scrape of the subscription "session/weekly limit" modal (no hook exists for it —
+//      anthropics/claude-code#34817 was closed not-planned) → the Claude adapter.
+// Both build the hold here so the shape stays identical, and the relay's resume sweep
+// (services/rate-limit-resume.ts) lifts either once the window resets.
+
+import type { ProviderState } from "agent-relay-sdk";
+
+export const RATE_LIMIT_BLOCK_REASON = "rate_limit";
+
+// Reject a parsed reset that's in the past or implausibly far out — a bad parse would
+// otherwise resume too early (thrash) or hold for days. Beyond this we drop resetAt and
+// fall back to the resume sweep's poll window.
+const MAX_RESET_AHEAD_MS = 7 * 24 * 60 * 60 * 1000;
+
+interface RateLimitHoldInput {
+  errorType?: string;
+  kind?: "usage_limit" | "transient_overload";
+  /** Unix ms the limit window resets, when known. */
+  resetAt?: number;
+  message?: string;
+  source?: string;
+}
+
+/** The blocked providerState a rate-limit hold carries. Shared by both detection arms. */
+export function buildRateLimitProviderState(input: RateLimitHoldInput): ProviderState {
+  const now = Date.now();
+  const resetAt = typeof input.resetAt === "number" && Number.isFinite(input.resetAt) ? input.resetAt : undefined;
+  const kind = input.kind ?? rateLimitKindForError(input.errorType);
+  const label = kind === "transient_overload"
+    ? "provider overloaded"
+    : resetAt ? `usage limit · resets ${formatResetClock(resetAt)}` : "usage limit reached";
+  return {
+    state: "blocked",
+    reason: RATE_LIMIT_BLOCK_REASON,
+    label,
+    recommendedAction: kind === "transient_overload"
+      ? "Holding briefly for provider overload; agent-relay will retry with bounded backoff."
+      : "Holding until the usage window resets; agent-relay auto-resumes the agent.",
+    kind,
+    source: input.source ?? "claude",
+    errorType: input.errorType ?? RATE_LIMIT_BLOCK_REASON,
+    enteredAt: now,
+    ...(resetAt ? { resetAt } : {}),
+    ...(input.message ? { message: input.message } : {}),
+    updatedAt: now,
+  };
+}
+
+function rateLimitKindForError(errorType: string | undefined): "usage_limit" | "transient_overload" {
+  return /^(overloaded|server_error|api_error|unknown|529|5\d\d)$/i.test(errorType ?? "") ? "transient_overload" : "usage_limit";
+}
+
+/** Host-local HH:MM for the chat notice / badge label (matches how the CLI shows "resets 3:45pm"). */
+function formatResetClock(resetAtMs: number): string {
+  try {
+    return new Date(resetAtMs).toLocaleTimeString([], { hour: "2-digit", minute: "2-digit" });
+  } catch {
+    return new Date(resetAtMs).toISOString().slice(11, 16);
+  }
+}
+
+// The subscription limit line wordings seen in the wild (claude-auto-retry patterns +
+// claude-auto-retry#15: "session"/"weekly limit" slipped past older regexes). We REQUIRE a
+// limit phrase AND a reset/retry phrase on the same line so normal output mentioning
+// "rate limit" can't false-positive the hold.
+const LIMIT_PHRASE_RE = /(?:hit (?:your|the)\s*(?:[\w-]+\s+)*limit|usage limit|\d+-hour limit|limit reached|out of (?:extra )?usage|rate limit(?:\s+(?:hit|reached|exceeded))?|weekly limit|session limit)/i;
+const RESET_AT_RE = /\bresets?\b(?:\s+at)?\s+(\d{1,2})(?::(\d{2}))?\s*(am|pm)?\s*(?:\(([^)]+)\))?/i;
+const TRY_AGAIN_RE = /\btry again in\s+(\d+)\s*(second|minute|hour|day)s?/i;
+
+interface PaneRateLimit {
+  /** The matched limit line, for the chat notice / observability. */
+  message: string;
+  /** Unix ms reset, when parseable from the pane (else undefined → resume falls back to poll). */
+  resetAt?: number;
+  /** Usage limits wait for reset; transient provider overloads retry quickly. */
+  kind?: "usage_limit" | "transient_overload";
+  errorType?: string;
+}
+
+/**
+ * Detect a Claude usage/rate-limit modal in a captured tmux pane and parse its reset time.
+ * Requires BOTH a limit phrase and a reset/retry phrase (anywhere in the pane, so it's robust
+ * to a modal that wraps the two onto separate lines) — that pairing is what distinguishes the
+ * real modal from normal output mentioning "rate limit". Returns null otherwise. `nowMs` is
+ * injectable for tests.
+ */
+export function parseClaudeRateLimitPane(text: string, nowMs: number = Date.now()): PaneRateLimit | null {
+  if (!text) return null;
+  const overload = parseClaudeTransientOverloadPane(text);
+  if (overload) return overload;
+  const limit = LIMIT_PHRASE_RE.exec(text);
+  if (!limit) return null;
+  const message = limitLineAt(text, limit.index);
+
+  const relative = TRY_AGAIN_RE.exec(text);
+  if (relative) {
+    const unitMs = { second: 1000, minute: 60_000, hour: 3_600_000, day: 86_400_000 }[relative[2]!.toLowerCase()] ?? 0;
+    const resetAt = clampReset(nowMs + Number(relative[1]) * unitMs, nowMs);
+    return { message, ...(resetAt ? { resetAt } : {}) };
+  }
+  const reset = RESET_AT_RE.exec(text);
+  if (reset) {
+    const resetAt = clampReset(parseClockReset(reset, nowMs), nowMs);
+    return { message, ...(resetAt ? { resetAt } : {}) };
+  }
+  // Limit phrase but no reset/retry anywhere — not confident it's the modal; skip to
+  // avoid false-positiving on normal output (docs, the agent's own text) that says "limit".
+  return null;
+}
+
+const TRANSIENT_API_ERROR_RE = /\bAPI Error:\s*((?:5\d\d)|529)\b[^\n]*(?:overload|server-side|temporar|try again|status\.claude\.com)?[^\n]*/i;
+const TRANSIENT_5XX_RE = /\b(?:5(?:00|02|03|04|20|29)|529)\b[^\n]*(?:overload|server-side|temporar|try again|status\.claude\.com)\b[^\n]*/i;
+
+function parseClaudeTransientOverloadPane(text: string): PaneRateLimit | null {
+  const match = TRANSIENT_API_ERROR_RE.exec(text) ?? TRANSIENT_5XX_RE.exec(text);
+  if (!match) return null;
+  const message = limitLineAt(text, match.index);
+  const code = match[1] ?? /\b(5\d\d|529)\b/.exec(match[0])?.[1];
+  return {
+    message: message || match[0].trim(),
+    kind: "transient_overload",
+    errorType: code === "529" ? "overloaded" : "server_error",
+  };
+}
+
+// The clean limit line containing the match offset, stripped of box-drawing chrome.
+function limitLineAt(text: string, index: number): string {
+  const start = text.lastIndexOf("\n", index) + 1;
+  const endNl = text.indexOf("\n", index);
+  const end = endNl === -1 ? text.length : endNl;
+  return text.slice(start, end).replace(/[│┌┐└┘─┤├╭╮╯╰]/g, " ").replace(/\s+/g, " ").trim();
+}
+
+function clampReset(resetAt: number | undefined, nowMs: number): number | undefined {
+  if (resetAt === undefined || !Number.isFinite(resetAt)) return undefined;
+  if (resetAt <= nowMs || resetAt - nowMs > MAX_RESET_AHEAD_MS) return undefined;
+  return resetAt;
+}
+
+// Next occurrence of a wall-clock "H[:MM] am/pm" in the message's IANA timezone (if given
+// and valid) or host-local. Timezone-aware so "resets 4:50pm (Asia/Shanghai)" is correct
+// regardless of where the runner host sits.
+function parseClockReset(match: RegExpExecArray, nowMs: number): number | undefined {
+  let hour = Number(match[1]);
+  const minute = match[2] ? Number(match[2]) : 0;
+  const meridiem = match[3]?.toLowerCase();
+  const tz = match[4]?.trim();
+  if (!Number.isFinite(hour) || hour > 23 || minute > 59) return undefined;
+  if (meridiem === "pm" && hour < 12) hour += 12;
+  if (meridiem === "am" && hour === 12) hour = 0;
+
+  if (tz && isValidTimeZone(tz)) {
+    const { y, mo, d, offsetMs } = tzWallAndOffset(tz, nowMs);
+    let target = Date.UTC(y, mo - 1, d, hour, minute, 0) - offsetMs;
+    if (target <= nowMs) target += 86_400_000;
+    return target;
+  }
+  const d = new Date(nowMs);
+  d.setHours(hour, minute, 0, 0);
+  let target = d.getTime();
+  if (target <= nowMs) target += 86_400_000;
+  return target;
+}
+
+function isValidTimeZone(tz: string): boolean {
+  try {
+    new Intl.DateTimeFormat("en-US", { timeZone: tz });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+// The target TZ's wall-clock date and UTC offset at `atMs`, via Intl (no deps).
+function tzWallAndOffset(tz: string, atMs: number): { y: number; mo: number; d: number; offsetMs: number } {
+  const dtf = new Intl.DateTimeFormat("en-US", {
+    timeZone: tz, hour12: false,
+    year: "numeric", month: "2-digit", day: "2-digit", hour: "2-digit", minute: "2-digit", second: "2-digit",
+  });
+  const parts = Object.fromEntries(dtf.formatToParts(new Date(atMs)).map((p) => [p.type, p.value])) as Record<string, string>;
+  const y = Number(parts.year), mo = Number(parts.month), d = Number(parts.day);
+  const h = Number(parts.hour) % 24, mi = Number(parts.minute), s = Number(parts.second);
+  const asUtc = Date.UTC(y, mo - 1, d, h, mi, s);
+  return { y, mo, d, offsetMs: asUtc - atMs };
+}

package/runner/src/relay-injection-events.ts

@@ -0,0 +1,102 @@
+import type { MessageSessionMeta, RelayInjectionCategory } from "agent-relay-sdk";
+import { isSpawnProvider } from "agent-relay-sdk";
+import type { ProviderConfig, RunnerSpawnConfig } from "./adapter";
+import { assembleLaunch } from "./launch-assembly";
+
+export interface RunnerRelayInjectionEvent {
+  category: RelayInjectionCategory;
+  summary: string;
+  detail: Record<string, unknown>;
+}
+
+interface RunnerRelayInjectionSessionEvent {
+  from: string;
+  to: string;
+  body: string;
+  session: MessageSessionMeta;
+}
+
+interface KeyedRelayInjectionEvent {
+  key: string;
+  event: RunnerRelayInjectionEvent;
+}
+
+interface RunnerLaunchInjectionInput {
+  carried?: RunnerRelayInjectionEvent[];
+  provider: string;
+  config: RunnerSpawnConfig;
+  providerConfig: ProviderConfig;
+  agentId: string;
+  providerSessionId: string;
+  timestamp?: number;
+}
+
+function launchInjectionEvents(input: RunnerLaunchInjectionInput): KeyedRelayInjectionEvent[] {
+  const events: KeyedRelayInjectionEvent[] = (input.carried ?? []).map((event, index) => ({ key: `spawn-${index}`, event }));
+  if (!isSpawnProvider(input.provider)) return events;
+  const assembled = assembleLaunch(input.provider, input.config, input.providerConfig);
+  const toolCount = assembled.skills.length + assembled.plugins.length + assembled.mcp.servers.length
+    + assembled.projectSkills.length
+    + assembled.mcp.projectServers.length
+    + (assembled.projectSettings.applied ? 1 : 0)
+    + (assembled.relaySkills ? 1 : 0)
+    + (assembled.relayPlugin ? 1 : 0)
+    + (assembled.mcp.relayEndpoint ? 1 : 0)
+    + (assembled.statusLine ? 1 : 0);
+  if (toolCount === 0) return events;
+  const parts = [
+    assembled.relaySkills ? "relay skills" : "",
+    assembled.relayPlugin ? "relay plugin" : "",
+    assembled.statusLine ? "status line" : "",
+    assembled.mcp.relayEndpoint ? "relay MCP" : "",
+    assembled.skills.length ? `${assembled.skills.length} skill${assembled.skills.length === 1 ? "" : "s"}` : "",
+    assembled.projectSkills.length ? `${assembled.projectSkills.length} project skill${assembled.projectSkills.length === 1 ? "" : "s"}` : "",
+    assembled.projectSettings.applied ? "project settings" : "",
+    assembled.plugins.length ? `${assembled.plugins.length} plugin${assembled.plugins.length === 1 ? "" : "s"}` : "",
+    assembled.mcp.servers.length ? `${assembled.mcp.servers.length} MCP server${assembled.mcp.servers.length === 1 ? "" : "s"}` : "",
+    assembled.mcp.projectServers.length ? `${assembled.mcp.projectServers.length} project MCP server${assembled.mcp.projectServers.length === 1 ? "" : "s"}` : "",
+  ].filter(Boolean);
+  events.push({
+    key: "tools",
+    event: {
+      category: "tools",
+      summary: `provisioned ${parts.join(", ")}`,
+      detail: {
+        source: "launch-assembly",
+        provider: assembled.provider,
+        base: assembled.base,
+        vanilla: assembled.vanilla,
+        relayContext: assembled.relayContext,
+        relaySkills: assembled.relaySkills,
+        relayPlugin: assembled.relayPlugin,
+        statusLine: assembled.statusLine,
+        skills: assembled.skills,
+        projectSkills: assembled.projectSkills,
+        projectSettings: assembled.projectSettings,
+        plugins: assembled.plugins,
+        mcp: assembled.mcp,
+      },
+    },
+  });
+  return events;
+}
+
+export function runnerLaunchInjectionSessionEvents(input: RunnerLaunchInjectionInput): RunnerRelayInjectionSessionEvent[] {
+  const timestamp = input.timestamp ?? Date.now();
+  return launchInjectionEvents(input).map(({ event, key }) => ({
+    from: input.agentId,
+    to: "user",
+    body: event.summary,
+    session: {
+      type: "relay-injection",
+      stepId: `relay-injection:${input.providerSessionId}:${key}`,
+      relayInjection: {
+        category: event.category,
+        summary: event.summary,
+        detail: event.detail,
+        agentId: input.agentId,
+        timestamp,
+      },
+    },
+  }));
+}