agent-relay-runner 0.62.3 → 0.63.0

package/src/runner-helpers.ts

@@ -0,0 +1,317 @@
+import { closeSync, openSync, readSync, statSync } from "node:fs";
+import type { AgentProfile, ContextState, Message, ProviderCapabilities } from "agent-relay-sdk";
+import { errMessage } from "agent-relay-sdk";
+import { targetMatchesAgentIdentity } from "agent-relay-sdk/agent-target";
+import type { ProviderAdapter, SemanticStatus } from "./adapter";
+import { agentProfileProjectionReport } from "./profile-projection";
+
+const MAX_TIMER_DELAY_MS = 2_147_483_647;
+const LOG_TAIL_BYTES = 128 * 1024;
+const CLAUDE_RESUME_RE = /\bclaude\s+--resume\s+([0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12})\b/gi;
+const RUNNER_CLAIMED_GUIDANCE_RE = /\s*Claim this task before working it, then update task status when finished\.\s*$/;
+
+interface RuntimeProviderOptions {
+  provider: string;
+  model?: string;
+  effort?: string;
+  approvalMode: string;
+  headless: boolean;
+  startedAt: number;
+  adapter: ProviderAdapter;
+}
+
+export interface ProbeModelInfo {
+  model?: string;
+  effort?: string;
+}
+
+export function runnerMessageMatches(message: Pick<Message, "to" | "resolvedToAgent">, target: {
+  agentId: string;
+  label?: string;
+  provider: string;
+  tags: string[];
+  capabilities: string[];
+  defaultTags: string[];
+  defaultCapabilities: string[];
+  allowBroadTargets?: boolean;
+}): boolean {
+  if (message.resolvedToAgent === target.agentId) return true;
+  if (message.to === target.agentId) return true;
+  if (target.label && message.to === `label:${target.label}`) return true;
+  if (target.allowBroadTargets === false) return false;
+  return targetMatchesAgentIdentity(message.to, {
+    id: target.agentId,
+    label: target.label,
+    tags: [...target.tags, ...target.defaultTags, target.provider],
+    capabilities: [...target.capabilities, ...target.defaultCapabilities],
+  });
+}
+
+export function taskIdFromMessage(message: Pick<Message, "payload">): number | undefined {
+  const taskId = message.payload?.taskId;
+  return Number.isSafeInteger(taskId) ? taskId as number : undefined;
+}
+
+export function stripRunnerClaimedGuidance(body: string): string {
+  return body.replace(RUNNER_CLAIMED_GUIDANCE_RE, "");
+}
+
+export function csvTags(raw: string | undefined): string[] {
+  return (raw || "").split(",").map((tag) => tag.trim()).filter(Boolean);
+}
+
+export function relayBusUrl(relayUrl: string): string {
+  const url = new URL(relayUrl);
+  url.protocol = url.protocol === "https:" ? "wss:" : "ws:";
+  url.pathname = `${url.pathname.replace(/\/+$/, "")}/bus`;
+  url.search = "";
+  return url.toString();
+}
+
+export function runnerAgentStatus(status: "idle" | "busy" | "offline" | "error"): "idle" | "busy" | "offline" {
+  return status === "error" ? "offline" : status;
+}
+
+export function runnerBusErrorAction(code: string, stopped: boolean): "ignore" | "log" | "stop" {
+  if (code === "STALE_SESSION") return stopped ? "ignore" : "stop";
+  return "log";
+}
+
+export function runnerShouldResolveProviderExit(status: SemanticStatus, exitCommandInProgress: boolean): boolean {
+  return !exitCommandInProgress && (status === "offline" || status === "error");
+}
+
+export function runnerShouldRestartUnexpectedProviderExit(
+  status: SemanticStatus,
+  input: {
+    exitCommandInProgress: boolean;
+    stopped: boolean;
+    restartInProgress: boolean;
+    provider?: string;
+    headless: boolean;
+    hasTerminalSession: boolean;
+  },
+): boolean {
+  return status === "offline"
+    && !input.exitCommandInProgress
+    && !input.stopped
+    && !input.restartInProgress
+    && input.headless
+    && input.hasTerminalSession;
+}
+
+export function latestClaudeResumeIdFromText(text: string): string | undefined {
+  let latest: string | undefined;
+  CLAUDE_RESUME_RE.lastIndex = 0;
+  for (let match = CLAUDE_RESUME_RE.exec(text); match; match = CLAUDE_RESUME_RE.exec(text)) {
+    latest = match[1];
+  }
+  return latest;
+}
+
+export function latestClaudeResumeIdFromLogFile(path: string): string | undefined {
+  let fd: number | undefined;
+  try {
+    const stat = statSync(path);
+    const length = Math.min(stat.size, LOG_TAIL_BYTES);
+    const offset = Math.max(0, stat.size - length);
+    const buffer = Buffer.alloc(length);
+    fd = openSync(path, "r");
+    readSync(fd, buffer, 0, length, offset);
+    return latestClaudeResumeIdFromText(buffer.toString("utf8"));
+  } catch {
+    return undefined;
+  } finally {
+    if (fd !== undefined) closeSync(fd);
+  }
+}
+
+export function commandTimeoutMs(params: Record<string, unknown>, fallback = 10_000): number {
+  const raw = params.timeoutMs;
+  if (typeof raw !== "number" || !Number.isSafeInteger(raw) || raw <= 0) return fallback;
+  return Math.min(raw, 60_000);
+}
+
+export function shouldLogDeliveryFailure(error: unknown): boolean {
+  const message = errMessage(error);
+  return message !== "no Claude monitor connected";
+}
+
+export function runtimeTokenRenewDelayMs(expiresAtSeconds: number, nowMs = Date.now()): number | undefined {
+  const expiresAtMs = expiresAtSeconds * 1000;
+  const ttlMs = expiresAtMs - nowMs;
+  if (!Number.isFinite(ttlMs) || ttlMs <= 0) return undefined;
+  const leadMs = Math.min(60 * 60 * 1000, Math.max(60_000, Math.floor(ttlMs * 0.2)));
+  const jitterMs = Math.floor(Math.random() * Math.min(30_000, Math.max(0, leadMs / 2)));
+  return Math.max(1_000, ttlMs - leadMs - jitterMs);
+}
+
+export function runtimeTokenRenewTimerSchedule(delayMs: number): { delayMs: number; renew: boolean } | undefined {
+  if (!Number.isFinite(delayMs) || delayMs <= 0) return undefined;
+  if (delayMs > MAX_TIMER_DELAY_MS) return { delayMs: MAX_TIMER_DELAY_MS, renew: false };
+  return { delayMs, renew: true };
+}
+
+export function lifecycleCapabilities(): Record<string, true> {
+  return {
+    shutdownHard: true,
+    restartHard: true,
+    semanticStatus: true,
+    transportReconnect: true,
+  };
+}
+
+export function runtimeProviderCapabilities(options: RuntimeProviderOptions, contextState?: ContextState, probeModel?: ProbeModelInfo): ProviderCapabilities {
+  const model = options.model ?? probeModel?.model;
+  const effort = options.effort ?? probeModel?.effort;
+  const modelSource = options.model ? "runtime" as const : probeModel?.model ? "provider" as const : "runtime" as const;
+  const shellMode = runtimeShellMode(options);
+  return {
+    lifecycle: {
+      managed: true,
+      shutdownHard: options.provider === "claude" ? options.headless : true,
+      restartHard: options.provider === "claude" ? options.headless : true,
+      semanticStatus: true,
+      reconnect: true,
+    },
+    model: {
+      provider: options.provider,
+      alias: model,
+      id: model,
+      effort,
+      source: modelSource,
+      confidence: options.model ? "reported" : probeModel?.model ? "reported" : "unknown",
+      lastUpdatedAt: options.startedAt,
+    },
+    session: {
+      approvalMode: options.approvalMode,
+      fileRead: true,
+      fileWrite: options.approvalMode !== "read-only",
+      shell: shellMode !== "none",
+      shellMode,
+      source: "runtime",
+      confidence: "reported",
+      lastUpdatedAt: options.startedAt,
+    },
+    ...runtimeProviderContextCapabilities(options, contextState),
+    ...runtimeProviderTerminalCapabilities(options),
+    liveSession: {
+      capture: true,
+      inject: Boolean(options.adapter.deliverInitialPrompt),
+      interrupt: Boolean(options.adapter.interrupt),
+      promptEcho: true,
+      reasoning: true,
+      slashCommands: options.provider === "claude" || options.provider === "codex",
+    },
+    source: "runtime",
+    confidence: "reported",
+    lastUpdatedAt: options.startedAt,
+  };
+}
+
+function runtimeShellMode(options: RuntimeProviderOptions): NonNullable<NonNullable<ProviderCapabilities["session"]>["shellMode"]> {
+  if (options.approvalMode === "read-only") {
+    return options.provider === "claude" ? "read-only-guarded" : "none";
+  }
+  return options.approvalMode === "open" ? "unrestricted" : "guarded";
+}
+
+function runtimeProviderTerminalCapabilities(options: RuntimeProviderOptions): Pick<ProviderCapabilities, "terminal"> {
+  if (options.provider === "claude" && options.headless) {
+    return {
+      terminal: {
+        live: {
+          read: true,
+          write: true,
+        },
+      },
+    };
+  }
+  if (options.provider === "codex") {
+    return {
+      terminal: {
+        attach: {
+          create: true,
+          read: true,
+          write: true,
+          detach: true,
+        },
+      },
+    };
+  }
+  return {};
+}
+
+export function appliedAgentProfileMetadata(provider: string, profile: AgentProfile): Record<string, unknown> {
+  const projection = provider === "claude" || provider === "codex"
+    ? agentProfileProjectionReport({ provider, profile })
+    : undefined;
+  return {
+    name: profile.name,
+    base: profile.base,
+    provider: profile.provider ?? "any",
+    relay: profile.relay,
+    instructions: {
+      repoInstructions: profile.instructions.repoInstructions,
+      globalInstructions: profile.instructions.globalInstructions,
+      appendCount: profile.instructions.append.length,
+      hasSystem: Boolean(profile.instructions.system),
+    },
+    skills: profile.skills.filter((item) => item.enabled).length,
+    plugins: profile.plugins.filter((item) => item.enabled).length,
+    mcp: { mode: profile.mcp.mode },
+    hooks: { mode: profile.hooks.mode },
+    permissions: profile.permissions,
+    projection,
+  };
+}
+
+function runtimeProviderContextCapabilities(options: RuntimeProviderOptions, contextState?: ContextState): Pick<ProviderCapabilities, "context"> {
+  const context: NonNullable<ProviderCapabilities["context"]> = { resume: "none" };
+  const supportsManagedContext = options.provider === "codex" || (options.provider === "claude" && options.headless);
+  if (contextState) {
+    context.stats = { source: contextState.source, confidence: contextState.confidence };
+    if (typeof contextState.tokensMax === "number" && Number.isFinite(contextState.tokensMax)) {
+      context.windowTokens = contextState.tokensMax;
+    }
+  }
+  if (supportsManagedContext) {
+    context.compact = true;
+    context.clear = true;
+  }
+  context.inject = true;
+  if (supportsManagedContext && options.adapter.compact && options.adapter.compactSupportsInstructions) context.resume = "native";
+  else if (supportsManagedContext && options.adapter.clearContext) context.resume = "clear-inject";
+  return Object.keys(context).length ? { context } : {};
+}
+
+export function providerStateFromActiveWork(activeWork: Array<{ kind: string; metadata?: Record<string, unknown> }>): Record<string, unknown> | null {
+  const providerTurn = activeWork.find((item) => item.kind === "provider-turn");
+  const state = providerTurn?.metadata?.providerState;
+  return state && typeof state === "object" && !Array.isArray(state) ? state as Record<string, unknown> : null;
+}
+
+export function isHttpAuthError(error: unknown): boolean {
+  const status = typeof error === "object" && error !== null ? (error as { status?: unknown }).status : undefined;
+  return status === 401 || status === 403;
+}
+
+export function isHttpStatusError(error: unknown, code: number): boolean {
+  const status = typeof error === "object" && error !== null ? (error as { status?: unknown }).status : undefined;
+  return status === code;
+}
+
+export function httpErrorKey(error: unknown): string {
+  const status = typeof error === "object" && error !== null ? (error as { status?: unknown }).status : undefined;
+  if (typeof status === "number") return `status:${status}`;
+  return String(error);
+}
+
+export function isContextState(value: unknown): value is ContextState {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return false;
+  const state = value as Record<string, unknown>;
+  return typeof state.utilization === "number" &&
+    typeof state.lifecycleState === "string" &&
+    typeof state.source === "string" &&
+    typeof state.confidence === "string";
+}

package/src/runner-insights.ts

@@ -0,0 +1,106 @@
+import type { WorkspaceMetadata } from "agent-relay-sdk";
+import type { ManagedProcess, ProviderAdapter } from "./adapter";
+import type { Outbox } from "./outbox";
+import { resolveProjectName } from "./config";
+import { computeContextRatio } from "./session-insights";
+import { boundContinuationArchiveSegment } from "./continuation-archive";
+
+type SessionDestroyReason = "compact" | "clear" | "restart" | "shutdown" | "kill" | "crash";
+
+interface RunnerInsightsDeps {
+  agentId: string;
+  cwd: string;
+  workspace?: WorkspaceMetadata;
+  getOutbox(): Outbox;
+  getProviderSessionId(): string;
+  getProcess(): ManagedProcess | undefined;
+  getAdapter(): ProviderAdapter;
+  getLastTranscriptPath(): string | undefined;
+  sessionLog(message: string): void;
+}
+
+export class RunnerInsights {
+  private insightsObserved = 0;
+  private insightsCursorKey = "";
+  private archiveObservedChars = 0;
+  private archiveCursorKey = "";
+  private projectName?: string;
+
+  constructor(private readonly deps: RunnerInsightsDeps) {}
+
+  project(): string {
+    return (this.projectName ??= resolveProjectName(this.deps.cwd, this.deps.workspace));
+  }
+
+  queueHookFatal(report: { hook: string; error: string }): void {
+    this.deps.getOutbox().enqueue({
+      kind: "insight",
+      payload: {
+        sessionId: this.deps.getProviderSessionId(),
+        project: this.project(),
+        agentId: this.deps.agentId,
+        signal: "hook_fatal",
+        value: { hook: report.hook, error: report.error },
+        source: "server",
+      },
+    });
+  }
+
+  async captureContinuationArchive(reason: SessionDestroyReason, opts?: { transcriptPath?: string }): Promise<void> {
+    const adapter = this.deps.getAdapter();
+    const process = this.deps.getProcess();
+    if (!adapter.collectSessionArchiveSegment || !process) return;
+    const transcriptPath = opts?.transcriptPath ?? this.deps.getLastTranscriptPath();
+    const archive = await adapter.collectSessionArchiveSegment(process, { transcriptPath });
+    if (!archive) return;
+    const key = transcriptPath ?? `session:${this.deps.getProviderSessionId()}`;
+    if (key !== this.archiveCursorKey || archive.length < this.archiveObservedChars) {
+      this.archiveCursorKey = key;
+      this.archiveObservedChars = 0;
+    }
+    const segment = archive.slice(this.archiveObservedChars).trim();
+    this.archiveObservedChars = archive.length;
+    if (!segment) return;
+    const bounded = boundContinuationArchiveSegment(segment);
+    if (bounded.droppedBytes > 0) this.deps.sessionLog(`continuation archive truncated at ${bounded.keptBytes} bytes; dropped ${bounded.droppedBytes} bytes (${reason})`);
+    this.deps.getOutbox().enqueue({
+      kind: "continuation-archive",
+      payload: {
+        agentId: this.deps.agentId,
+        segment: bounded.segment,
+      },
+    });
+    this.deps.sessionLog(`continuation archive queued (${bounded.segment.length} chars, ${reason})`);
+  }
+
+  async captureContextRatio(reason: SessionDestroyReason, opts?: { transcriptPath?: string }): Promise<void> {
+    const adapter = this.deps.getAdapter();
+    const process = this.deps.getProcess();
+    if (!adapter.collectSessionEvents || !process) return;
+    const transcriptPath = opts?.transcriptPath ?? this.deps.getLastTranscriptPath();
+    const events = await adapter.collectSessionEvents(process, { transcriptPath });
+    if (!events) return;
+    const key = transcriptPath ?? `session:${this.deps.getProviderSessionId()}`;
+    if (key !== this.insightsCursorKey || events.length < this.insightsObserved) {
+      this.insightsCursorKey = key;
+      this.insightsObserved = 0;
+    }
+    const segment = events.slice(this.insightsObserved);
+    this.insightsObserved = events.length;
+    const analysis = computeContextRatio(segment);
+    if (!analysis) return;
+    this.deps.getOutbox().enqueue({
+      kind: "insight",
+      payload: {
+        sessionId: this.deps.getProviderSessionId(),
+        project: this.project(),
+        agentId: this.deps.agentId,
+        signal: "context_ratio",
+        value: { ...analysis.metric, endReason: reason },
+        outcome: { ...analysis.outcome },
+        source: "server",
+      },
+    });
+    this.deps.sessionLog(`insights: context_ratio ${analysis.metric.ratio.toFixed(2)} (${analysis.metric.gatheringCalls}/${analysis.metric.totalToolCalls} gathering, ${reason}) queued`);
+  }
+}