agent-relay-server 0.122.0 → 0.122.1

package/runner/src/session-insights.ts

@@ -0,0 +1,118 @@
+// Provider-agnostic core for the #184 context-gathering signal (epic #183).
+//
+// The transcript *format* is provider-specific (Claude JSONL, Codex app-server items,
+// future providers), so each adapter normalizes its session into the same `SessionEvent`
+// stream via `collectSessionEvents`. Everything downstream — the gathering/action
+// classifier and the ratio math — lives here once and is shared, so a tool reclassified
+// for one provider is reclassified for all, and a new provider only implements the
+// normalization.
+//
+// The classifier is model-free and runs in the runner, so it costs zero agent tokens and
+// the agent can't game it.
+
+// A normalized, ordered session event. Order is significant: `leadingGather` counts the
+// run of gathering tools before the first action.
+export type SessionEvent =
+  // A tool invocation. Gathering-vs-action is decided here by `isGatheringTool(name)`.
+  | { type: "tool"; name: string }
+  // A failed tool result (paired outcome proxy — failures/workarounds the agent hit).
+  | { type: "tool_error" }
+  // A real user prompt (paired outcome proxy — more back-and-forth ~ clarification/correction).
+  | { type: "user_prompt" }
+  // A substantive assistant turn (one that produced text or a tool call).
+  | { type: "turn" };
+
+// Tools that acquire context without changing anything. Anything not matched here is
+// treated as an action (mutation, execution, or a delegation/direction decision) — Bash
+// counts as an action because it executes (a conservative, documented choice for v0;
+// `cat`/`ls` via Bash are misclassified, refine later if the data warrants it).
+const GATHERING_TOOLS = new Set([
+  "Read", "Grep", "Glob", "LS", "NotebookRead", "WebFetch", "WebSearch",
+]);
+const GATHERING_NAME = /(?:^|[._-])(read|get|list|search|grep|glob|find|fetch|query|browse|view|show|cat|status|inspect|lookup|symbols|snippet)/i;
+
+export function isGatheringTool(name: string): boolean {
+  if (GATHERING_TOOLS.has(name)) return true;
+  // MCP / custom tools: classify by name shape (e.g. mcp__callmux__searxng_web_search).
+  return GATHERING_NAME.test(name);
+}
+
+interface ContextRatioMetric {
+  /** Session-wide gathering fraction: gatheringCalls / totalToolCalls. The headline metric. */
+  ratio: number;
+  gatheringCalls: number;
+  actionCalls: number;
+  totalToolCalls: number;
+  /** Consecutive gathering calls before the first action — the "read N files before moving" signal. */
+  leadingGather: number;
+  /** Substantive assistant turns (turns that produced text or a tool call). */
+  turns: number;
+}
+
+interface SessionOutcomeProxy {
+  /** Real user prompts in the session — more back-and-forth ~ more clarification/correction. */
+  userPrompts: number;
+  /** tool_result blocks flagged is_error — failures/workarounds the agent hit. */
+  toolErrors: number;
+}
+
+export interface SessionAnalysis {
+  metric: ContextRatioMetric;
+  outcome: SessionOutcomeProxy;
+}
+
+/**
+ * Reduce a normalized event stream to the context-gathering ratio plus paired outcome
+ * proxies. Returns null when there's nothing substantive to measure (no tool calls) —
+ * trivial segments have nothing to learn from and shouldn't pollute the baselines.
+ *
+ * Per-segment by construction: callers pass only the events since the last capture
+ * boundary (compact/clear/restart/shutdown), so each result describes one work chunk.
+ */
+export function computeContextRatio(events: SessionEvent[]): SessionAnalysis | null {
+  let gatheringCalls = 0;
+  let actionCalls = 0;
+  let leadingGather = 0;
+  let sawAction = false;
+  let userPrompts = 0;
+  let toolErrors = 0;
+  let turns = 0;
+
+  for (const event of events) {
+    switch (event.type) {
+      case "user_prompt":
+        userPrompts++;
+        break;
+      case "tool_error":
+        toolErrors++;
+        break;
+      case "turn":
+        turns++;
+        break;
+      case "tool":
+        if (isGatheringTool(event.name)) {
+          gatheringCalls++;
+          if (!sawAction) leadingGather++;
+        } else {
+          actionCalls++;
+          sawAction = true;
+        }
+        break;
+    }
+  }
+
+  const totalToolCalls = gatheringCalls + actionCalls;
+  if (totalToolCalls === 0) return null;
+
+  return {
+    metric: {
+      ratio: gatheringCalls / totalToolCalls,
+      gatheringCalls,
+      actionCalls,
+      totalToolCalls,
+      leadingGather,
+      turns,
+    },
+    outcome: { userPrompts, toolErrors },
+  };
+}

package/runner/src/session-scratch.ts

@@ -0,0 +1,271 @@
+import { execFileSync } from "node:child_process";
+import { accessSync, appendFileSync, constants, mkdirSync, readdirSync, readFileSync, rmSync, statSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { dirname, isAbsolute, join, resolve } from "node:path";
+import { sanitizeFsName } from "agent-relay-sdk/fs-name";
+
+const SCRATCH_DIR_NAME = ".agent-relay";
+// The local-ignore entry. Leading + trailing slash scopes it to the dir at the
+// base, matching git's gitignore semantics.
+const EXCLUDE_ENTRY = "/.agent-relay/";
+const LAUNCHER_DIR = join(tmpdir(), `agent-relay-launchers-${typeof process.getuid === "function" ? process.getuid() : "user"}`);
+const DEFAULT_LAUNCHER_SWEEP_MIN_AGE_MS = 24 * 60 * 60 * 1000;
+
+export interface SessionScratchLayout {
+  baseDir: string; // dir that contains .agent-relay (cwd, or fallback base dir)
+  rootDir: string; // <base>/.agent-relay
+  sessionsDir: string; // <base>/.agent-relay/sessions
+  sessionDir: string; // <base>/.agent-relay/sessions/<id>
+  tmpDir: string; // <base>/.agent-relay/sessions/<id>/tmp
+  replyFile: string; // <tmp>/reply.md
+}
+
+interface SessionScratchTarget {
+  agentId: string;
+  cwd: string;
+  // Orchestrator base dir, used only when cwd is not writable. NEVER home — a
+  // home fallback would place scratch above the orchestrator base dir and break
+  // cwd containment.
+  fallbackBaseDir?: string;
+}
+
+interface SessionLauncherTarget {
+  launcherScript?: string;
+  launcherDir?: string;
+  tmuxSession?: string;
+}
+
+function isWritableDir(dir: string): boolean {
+  try {
+    if (!statSync(dir).isDirectory()) return false;
+    accessSync(dir, constants.W_OK);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+// Prefer cwd; fall back to the orchestrator base dir only when cwd is not a
+// writable dir. Returns cwd as a last resort so callers can still attempt mkdir
+// (and surface the real error) rather than silently picking an unrelated path.
+export function resolveScratchBase(cwd: string, fallbackBaseDir?: string): string {
+  if (isWritableDir(cwd)) return cwd;
+  if (fallbackBaseDir && isWritableDir(fallbackBaseDir)) return fallbackBaseDir;
+  return cwd;
+}
+
+function sessionScratchLayout(baseDir: string, agentId: string): SessionScratchLayout {
+  const rootDir = join(baseDir, SCRATCH_DIR_NAME);
+  const sessionsDir = join(rootDir, "sessions");
+  const sessionDir = join(sessionsDir, agentId);
+  const tmpDir = join(sessionDir, "tmp");
+  return { baseDir, rootDir, sessionsDir, sessionDir, tmpDir, replyFile: join(tmpDir, "reply.md") };
+}
+
+// Resolve git's exclude file for baseDir, correctly handling plain repos,
+// worktrees, and submodules (git rev-parse returns the shared commondir's
+// info/exclude). Returns null when baseDir is not inside a git work tree.
+function gitExcludePath(baseDir: string): string | null {
+  try {
+    const out = execFileSync("git", ["-C", baseDir, "rev-parse", "--git-path", "info/exclude"], {
+      encoding: "utf8",
+      stdio: ["ignore", "pipe", "ignore"],
+    }).trim();
+    if (!out) return null;
+    return isAbsolute(out) ? out : resolve(baseDir, out);
+  } catch {
+    return null;
+  }
+}
+
+// Idempotently append EXCLUDE_ENTRY to an ignore file (grep-before-write).
+function appendIgnoreEntry(file: string): void {
+  let existing = "";
+  try {
+    existing = readFileSync(file, "utf8");
+  } catch {}
+  const wanted = EXCLUDE_ENTRY.trim();
+  if (existing.split("\n").some((line) => line.trim() === wanted)) return;
+  mkdirSync(dirname(file), { recursive: true });
+  const prefix = existing.length > 0 && !existing.endsWith("\n") ? "\n" : "";
+  appendFileSync(file, `${prefix}${EXCLUDE_ENTRY}\n`);
+}
+
+// Ensure `.agent-relay/` is locally ignored. Prefers .git/info/exclude (git's
+// local, uncommitted ignore list) so no tracked file is ever modified; falls
+// back to .gitignore only when baseDir is not a git repo. Returns which file was
+// used (for logging/tests).
+export function ensureScratchIgnored(baseDir: string): "exclude" | "gitignore" {
+  const excludePath = gitExcludePath(baseDir);
+  if (excludePath) {
+    appendIgnoreEntry(excludePath);
+    return "exclude";
+  }
+  appendIgnoreEntry(join(baseDir, ".gitignore"));
+  return "gitignore";
+}
+
+// SessionStart: create the session tmp dir and ensure local ignore. Dir
+// creation is the load-bearing part; ignore setup is best-effort.
+export function ensureSessionScratch(target: SessionScratchTarget): SessionScratchLayout {
+  const base = resolveScratchBase(target.cwd, target.fallbackBaseDir);
+  const layout = sessionScratchLayout(base, target.agentId);
+  mkdirSync(layout.tmpDir, { recursive: true });
+  try {
+    ensureScratchIgnored(base);
+  } catch {
+    // best-effort: a missing ignore entry never pollutes git because the dir is
+    // already created and the entry is the only thing at risk.
+  }
+  return layout;
+}
+
+function resolveLauncherDir(launcherDir?: string): string {
+  return launcherDir ?? LAUNCHER_DIR;
+}
+
+export function launcherScriptPathForSession(sessionName: string, launcherDir?: string): string {
+  const sanitized = sanitizeFsName(sessionName, { replacement: "-", collapse: false });
+  return join(resolveLauncherDir(launcherDir), `${sanitized}.sh`);
+}
+
+function dedupeBases(bases: Array<string | undefined>): string[] {
+  const seen = new Set<string>();
+  const out: string[] = [];
+  for (const b of bases) {
+    if (!b || seen.has(b)) continue;
+    seen.add(b);
+    out.push(b);
+  }
+  return out;
+}
+
+function dedupePaths(paths: Array<string | undefined>): string[] {
+  const seen = new Set<string>();
+  const out: string[] = [];
+  for (const path of paths) {
+    if (!path || seen.has(path)) continue;
+    seen.add(path);
+    out.push(path);
+  }
+  return out;
+}
+
+// SessionEnd: remove this session's dir from every candidate base.
+export function reapSessionScratch(target: SessionScratchTarget): void {
+  for (const base of dedupeBases([target.cwd, target.fallbackBaseDir])) {
+    const { sessionDir } = sessionScratchLayout(base, target.agentId);
+    try {
+      rmSync(sessionDir, { recursive: true, force: true });
+    } catch {}
+  }
+}
+
+// Claude headless sessions externalize their provider launch command into a
+// per-session script under /tmp. Remove it on runner shutdown alongside the
+// scratch dir reap to avoid leaking one file per spawn.
+export function reapSessionLauncher(target: SessionLauncherTarget): string[] {
+  const removed: string[] = [];
+  for (const path of dedupePaths([
+    target.launcherScript,
+    target.tmuxSession ? launcherScriptPathForSession(target.tmuxSession, target.launcherDir) : undefined,
+  ])) {
+    try {
+      const exists = statSync(path).isFile();
+      rmSync(path, { force: true });
+      if (exists) removed.push(path);
+    } catch {}
+  }
+  return removed;
+}
+
+interface SweepOptions {
+  cwd: string;
+  fallbackBaseDir?: string;
+  // Agent ids to keep (currently-known agents + self). Any session dir whose id
+  // is not in this set AND older than minAgeMs is removed.
+  keepAgentIds: Set<string>;
+  now: number;
+  minAgeMs?: number;
+}
+
+interface LauncherSweepOptions {
+  // Agent ids to keep (currently-known agents + self). Launcher scripts embed
+  // AGENT_RELAY_ID, so a stale sweep can safely remove only scripts whose agent
+  // is no longer live.
+  keepAgentIds: Set<string>;
+  launcherDir?: string;
+  now: number;
+  minAgeMs?: number;
+}
+
+function maybeShellUnquote(value: string): string {
+  const trimmed = value.trim();
+  if (!trimmed.startsWith("'") || !trimmed.endsWith("'")) return trimmed;
+  return trimmed.slice(1, -1).replace(/'\\''/g, "'");
+}
+
+function launcherAgentId(scriptPath: string): string | null {
+  try {
+    const match = readFileSync(scriptPath, "utf8").match(/^export AGENT_RELAY_ID=(.+)$/m);
+    if (!match) return null;
+    const agentId = maybeShellUnquote(match[1] ?? "");
+    return agentId || null;
+  } catch {
+    return null;
+  }
+}
+
+// Periodic sweep of leftover session dirs from agents no longer known to the
+// relay. The minAgeMs grace avoids racing a peer that just created its dir but
+// has not yet appeared in the agent list.
+export function sweepStaleSessions(opts: SweepOptions): string[] {
+  const minAge = opts.minAgeMs ?? 60 * 60 * 1000;
+  const removed: string[] = [];
+  for (const base of dedupeBases([opts.cwd, opts.fallbackBaseDir])) {
+    const sessionsDir = join(base, SCRATCH_DIR_NAME, "sessions");
+    let ids: string[];
+    try {
+      ids = readdirSync(sessionsDir);
+    } catch {
+      continue;
+    }
+    for (const id of ids) {
+      if (opts.keepAgentIds.has(id)) continue;
+      const dir = join(sessionsDir, id);
+      try {
+        if (opts.now - statSync(dir).mtimeMs < minAge) continue;
+        rmSync(dir, { recursive: true, force: true });
+        removed.push(dir);
+      } catch {}
+    }
+  }
+  return removed;
+}
+
+// Periodic sweep of leaked per-spawn launcher scripts. Old scripts whose agent
+// id is no longer live are safe to prune; old unparsable files are treated as
+// stale too so the next run clears historical buildup without manual cleanup.
+export function sweepStaleLaunchers(opts: LauncherSweepOptions): string[] {
+  const minAge = opts.minAgeMs ?? DEFAULT_LAUNCHER_SWEEP_MIN_AGE_MS;
+  const removed: string[] = [];
+  const launcherDir = resolveLauncherDir(opts.launcherDir);
+  let entries: string[];
+  try {
+    entries = readdirSync(launcherDir);
+  } catch {
+    return removed;
+  }
+  for (const entry of entries) {
+    const scriptPath = join(launcherDir, entry);
+    try {
+      if (!statSync(scriptPath).isFile()) continue;
+      if (opts.now - statSync(scriptPath).mtimeMs < minAge) continue;
+      const agentId = launcherAgentId(scriptPath);
+      if (agentId && opts.keepAgentIds.has(agentId)) continue;
+      rmSync(scriptPath, { force: true });
+      removed.push(scriptPath);
+    } catch {}
+  }
+  return removed;
+}

package/runner/src/template-resolver.ts

@@ -0,0 +1,29 @@
+import type { RelayHttpClient } from "agent-relay-sdk";
+import { RUNNER_PROMPT_TEMPLATE_DEFAULTS } from "agent-relay-sdk/prompt-template-defaults";
+
+const RUNNER_DEFAULTS = new Map<string, string>(RUNNER_PROMPT_TEMPLATE_DEFAULTS.map((template) => [template.slug, template.defaultTemplate]));
+const templateCache = new Map<string, string>();
+
+function renderValue(value: string | undefined): string {
+  return value ?? "";
+}
+
+function applyVariables(template: string, vars: Record<string, string>): string {
+  return template.replace(/\{\{(\w+)\}\}/g, (_, key: string) => renderValue(vars[key]));
+}
+
+export async function initializeRunnerTemplates(http: RelayHttpClient): Promise<void> {
+  try {
+    const templates = await http.listPromptTemplates();
+    templateCache.clear();
+    for (const template of templates) templateCache.set(template.slug, template.template);
+  } catch {
+    templateCache.clear();
+  }
+}
+
+export function renderRunnerTemplate(slug: string, vars: Record<string, string> = {}): string {
+  const template = templateCache.get(slug) ?? RUNNER_DEFAULTS.get(slug);
+  if (template === undefined) throw new Error(`unknown runner prompt template slug: ${slug}`);
+  return applyVariables(template, vars);
+}

package/runner/src/version.ts

@@ -0,0 +1,43 @@
+import { readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { CONTRACT_VERSIONS } from "agent-relay-sdk";
+import { getManifest } from "agent-relay-providers";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const pkg = JSON.parse(readFileSync(join(__dirname, "../package.json"), "utf8")) as { name?: string; version?: string };
+
+export const PACKAGE_NAME = pkg.name || "agent-relay-runner";
+export const VERSION = pkg.version || "0.0.0";
+// Protocol versions are owned by the SDK (CONTRACT_VERSIONS) — derive, never redeclare.
+export const RUNNER_PROTOCOL_VERSION = CONTRACT_VERSIONS.runnerProtocol;
+export const PROVIDER_PLUGIN_PROTOCOL_VERSION = CONTRACT_VERSIONS.providerPluginProtocol;
+
+export const CONTRACTS = {
+  runnerProtocol: RUNNER_PROTOCOL_VERSION,
+  providerPluginProtocol: PROVIDER_PLUGIN_PROTOCOL_VERSION,
+} as const;
+
+export const RUNTIME_CAPABILITIES = {
+  relayCommandBus: true,
+  managedRegistration: true,
+  lifecycleCommands: true,
+  claimRenewal: true,
+  deliveryRetry: true,
+} as const;
+
+export function runtimeMetadata(provider?: string) {
+  const manifest = provider ? getManifest(provider) : undefined;
+  return {
+    package: {
+      name: PACKAGE_NAME,
+      version: VERSION,
+    },
+    contracts: CONTRACTS,
+    capabilities: {
+      ...RUNTIME_CAPABILITIES,
+      ...(manifest?.provisioning?.bundledPlugin ? { bundledPlugin: true } : {}),
+      ...(manifest?.provisioning?.bundledSkills ? { bundledSkills: true } : {}),
+    },
+  };
+}

package/src/gate-resolver.ts

@@ -11,10 +11,9 @@
 //      package manager (from `packageManager` field or lockfile). A repo whose
 //      `scripts.test` is `jest` gets `<pm> run test`, never `bun test`. When the repo
 //      declares a full-gate script (`ci:land` preferred, else `ci`), that IS its gate
-//      (the set the release enforces): the steward runs it wholesale so land gates ==
-//      release gates (#1044), instead of a file-relevance subset that would let
-//      drift/lint/doc breakage land. `ci:land` exists for the worktree-safe subset — see
-//      the note at the derivation for why land gates can't run every release check.
+//      (the set the repo wants enforced before land/release): the steward runs it
+//      wholesale so land gates == release gates (#1044/#1089), instead of a
+//      file-relevance subset that would let drift/lint/doc breakage land.
 //   3. Default — the legacy bun heuristic, only when there's nothing to derive from
 //      (no repo path, or no readable package.json).
 import { existsSync, readFileSync } from "node:fs";
@@ -109,14 +108,10 @@ export function resolveStewardChecks(files: string[], repoRoot?: string): Stewar
     // drift/lint/doc breakage that only a narrower gate misses and that would otherwise
     // surface at release time (failing `*:check`/lint gates).
     //
-    // Prefer a `ci:land` script when the repo declares one: land gates run inside a git
-    // WORKTREE, and some release checks are not worktree-safe. agent-relay's own
-    // `build:claude-monitor:check` bundles provider modules whose resolution depends on
-    // checkout topology — a worktree's symlinked `node_modules` double-inlines them, so
-    // that check false-fails in every worktree (its topology-determinism root fix is
-    // tracked in #1045). `ci:land` is the worktree-safe subset of `ci` (ci == the two
-    // bundle steps + ci:land), so the steward and the release share ONE source of truth
-    // for the land-relevant gates without the steward hitting a structural false failure.
+    // Prefer an explicit `ci:land` script when the repo declares one: it is the repo's
+    // named pre-land full gate, so the steward should respect that contract over a more
+    // generic `ci`. Repos that want exact parity can make `ci` delegate to `ci:land`;
+    // repos that need a different land-safe full gate still have a first-class name for it.
     const fullGate = pkg.scripts["ci:land"] ? "ci:land" : pkg.scripts.ci ? "ci" : undefined;
     if (fullGate && files.length) {
       return [{ command: runScript(fullGate), reason: `repo declares a full "${fullGate}" gate (land==release parity)` }];