@humwick/runner 0.0.0-stage → 0.130.0

package/src/relay-instructions.ts

@@ -0,0 +1,107 @@
+import { relayEnv } from "@humwick/sdk/env";
+import { existsSync } from "node:fs";
+import type { AgentProfile, ProvisioningMcpServer } from "@humwick/sdk";
+import { webToolSteerRefs, type WebToolName } from "@humwick/sdk/web-tools";
+import { TEMP_DIR_TEMPLATE_SLUG } from "@humwick/sdk/prompt-template-defaults";
+import type { RunnerSpawnConfig } from "./adapter";
+import { renderRunnerTemplate } from "./template-resolver";
+
+export interface RelayContextResolution {
+  /** True only when the profile permits a non-empty context block for this provider. */
+  available: boolean;
+  /** The exact text the provider transport must emit, or an empty string when suppressed. */
+  text: string;
+}
+
+/** Shared profile-policy gate for every Relay-owned launch feature. */
+export function profileAllowsRelayFeature(config: Pick<RunnerSpawnConfig, "agentProfile">, feature: keyof AgentProfile["relay"]): boolean {
+  return config.agentProfile?.relay?.[feature] !== false;
+}
+
+/**
+ * First-turn briefing (availability + text together). #2836: no core copy — the core is
+ * server-composed, and hand-started runners get no Relay instructions at all.
+ */
+export function resolveRelayContext(input: {
+  slug: string;
+  config?: Pick<RunnerSpawnConfig, "agentProfile">;
+  mcpServers?: Record<string, ProvisioningMcpServer>;
+  /** #3024 — the launch's Brave/Jina tools, named per provider in the steer. */
+  webTools?: { names: readonly WebToolName[]; claude: boolean };
+}): RelayContextResolution {
+  if (input.config && !profileAllowsRelayFeature(input.config, "context")) {
+    return { available: false, text: "" };
+  }
+  const fff = input.mcpServers?.fff;
+  const search = fff && (fff.url || (fff.command && existsSync(fff.command)))
+    ? renderRunnerTemplate("relay.search.fff") : "";
+  const web = input.webTools ? webToolsSteer(input.webTools.names, input.webTools.claude) : "";
+  const text = [renderRunnerTemplate(input.slug).trim(), search, web, renderRunnerTemplate(TEMP_DIR_TEMPLATE_SLUG)].filter(Boolean).join("\n\n");
+  return { available: text.length > 0, text };
+}
+
+export function claudeRelayManual(): string {
+  return renderRunnerTemplate("relay.manual.claude");
+}
+
+/** One line per capability: Brave searches; the local reader fetches, with keyless Jina fallback. */
+export function webToolsSteer(names: readonly WebToolName[], claude: boolean): string {
+  return names.map(name => name === "brave"
+    ? `Web search: use ${claude ? "web_search on the agent-relay MCP server (load with ToolSearch)" : "web_search on the agent-relay MCP server"}. Relay tries Tavily, then budget-capped Brave. If the monthly cap is reached, report it; do not retry in a loop.`
+    : renderRunnerTemplate("relay.web.fetch", {
+      tools: webToolSteerRefs(name, claude), fallback: webToolSteerRefs(name, claude, true),
+    })).join("\n");
+}
+
+export function claudeRelayContext(): string {
+  return resolveRelayContext({ slug: "relay.context.claude" }).text;
+}
+
+export function claudeReadOnlyRelayContext(): string {
+  return resolveRelayContext({ slug: "relay.context.claude.readonly" }).text;
+}
+
+export function relayReplyActionText(messageId: number): string {
+  return `relay_reply (messageId: ${messageId}, body: "<your reply>"). CLI fallback: agent-relay /reply ${messageId} "<your reply>"`;
+}
+
+export function workspaceDepsNote(input: { mode?: string | null; depsMode?: string | null; installCommand?: string | null }): string {
+  if (input.mode !== "isolated") return "";
+  switch (input.depsMode) {
+    case "symlink":
+      return renderRunnerTemplate("workspace.deps.symlink");
+    case "command":
+      return renderRunnerTemplate("workspace.deps.command", { installCommand: input.installCommand ?? "the repository install command" });
+    case "none":
+      return renderRunnerTemplate("workspace.deps.none");
+    default:
+      return "";
+  }
+}
+
+export function workspaceLifecycleNote(input: { mode?: string | null; branch?: string | null; baseRef?: string | null }): string {
+  if (input.mode !== "isolated") return "";
+  const branch = input.branch ? `\`${input.branch}\`` : "an isolated agent branch";
+  const base = input.baseRef ? `\`${input.baseRef}\`` : "the base branch";
+  return renderRunnerTemplate("workspace.lifecycle", { branch, baseRef: base });
+}
+
+export function workspaceSymlinksNote(linked: string[]): string {
+  if (!linked.length) return "";
+  return renderRunnerTemplate("workspace.symlinks", { linked: linked.join(", ") });
+}
+
+export function workspaceDepsNoteFromEnv(env: Record<string, string | undefined> = process.env): string {
+  const json = relayEnv(env, "AGENT_RELAY_WORKSPACE_JSON");
+  if (!json) return "";
+  try {
+    const parsed = JSON.parse(json) as { mode?: string; branch?: string; baseRef?: string; deps?: { mode?: string; command?: string }; symlinks?: { linked?: string[] } };
+    return [
+      workspaceLifecycleNote({ mode: parsed.mode ?? null, branch: parsed.branch ?? null, baseRef: parsed.baseRef ?? null }),
+      workspaceDepsNote({ mode: parsed.mode ?? null, depsMode: parsed.deps?.mode ?? null, installCommand: parsed.deps?.command ?? null }),
+      parsed.mode === "isolated" ? workspaceSymlinksNote(parsed.symlinks?.linked ?? []) : "",
+    ].filter(Boolean).join("\n\n");
+  } catch {
+    return "";
+  }
+}

package/src/relay-mcp-proxy.long-turn-e2e.ts

@@ -0,0 +1,183 @@
+/**
+ * #2429 / #2537 — opt-in compressed long-turn E2E for the shared MCP tool-call forward.
+ *
+ * Spawned as a CHILD bun process by the AGENT_RELAY_LONG_TURN_E2E=1-gated test in
+ * relay-mcp-proxy.test.ts, with BUN_CONFIG_HTTP_IDLE_TIMEOUT=2 compressing Bun's native
+ * ~300s HTTP idle watchdog down to ~2s for this process. A stand-in relay withholds ALL
+ * response bytes for 6s (mimicking src/mcp/index.ts `tools/call`, which awaits the WHOLE
+ * tool before its first byte):
+ *
+ *   CONTROL   — a plain fetch (no `timeout` option) against the slow relay must die with
+ *               TimeoutError: proves this process's idle watchdog is live and would abort
+ *               any >idle-timeout forward, i.e. the pre-fix behavior of forward().
+ *   REAL PATH — a long `relay_run` `tools/call` through the REAL RelayMcpProxy (whose
+ *               forward() sets `timeout:false`) must complete with the usable
+ *               `still-running` + `runId` envelope despite sitting silent well past the
+ *               compressed idle timeout.
+ *
+ * Exits 0 and prints LONG-TURN E2E PASS on success; non-zero with diagnostics otherwise.
+ */
+import { RelayMcpProxy } from "./relay-mcp-proxy";
+
+const WITHHOLD_MS = 6_000;
+const SECRET = "long-turn-e2e-secret";
+const CHILD_DEADLINE_MS = 45_000;
+
+interface JsonRpcBody {
+  id?: string | number | null;
+  method?: string;
+  params?: {
+    name?: string;
+    arguments?: {
+      waitMs?: number;
+    };
+  };
+}
+
+function fail(message: string): never {
+  console.error(`LONG-TURN E2E FAIL: ${message}`);
+  process.exit(1);
+}
+
+async function withDeadline<T>(label: string, promise: Promise<T>, ms: number): Promise<T> {
+  let timer: ReturnType<typeof setTimeout> | undefined;
+  const guard = new Promise<never>((_, reject) => {
+    timer = setTimeout(() => reject(new Error(`${label} exceeded ${ms}ms child deadline`)), ms);
+  });
+  try {
+    return await Promise.race([promise, guard]);
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+// Stand-in relay: accepts the JSON-RPC POST, drains the body (request fully received — the
+// connect phase is over), then withholds every response byte until WITHHOLD_MS has elapsed.
+// Server-side idleTimeout pinned high so ONLY the client-side watchdog is under test.
+const slowRelay = Bun.serve({
+  port: 0,
+  hostname: "127.0.0.1",
+  idleTimeout: 255,
+  fetch: async (req) => {
+    const raw = await req.text();
+    let id: string | number | null = null;
+    let request: JsonRpcBody | undefined;
+    try {
+      request = JSON.parse(raw) as JsonRpcBody;
+      id = request.id ?? null;
+    } catch {
+      // Keep the intentionally silent response shape even for malformed control input.
+    }
+    await Bun.sleep(WITHHOLD_MS);
+    if (!request || request.method !== "tools/call" || request.params?.name !== "relay_run") {
+      return Response.json(
+        { jsonrpc: "2.0", id, error: { code: -32601, message: "expected relay_run tools/call" } },
+        { status: 400 },
+      );
+    }
+    if (request.params.arguments?.waitMs !== 600_000) {
+      return Response.json(
+        { jsonrpc: "2.0", id, error: { code: -32602, message: "expected a 600000ms inline wait" } },
+        { status: 400 },
+      );
+    }
+    return Response.json({
+      jsonrpc: "2.0",
+      id,
+      result: {
+        content: [{ type: "text", text: "relay_run still running" }],
+        structuredContent: {
+          run: {
+            runId: "long-turn-run-id",
+            status: "still-running",
+            exitCode: null,
+          },
+        },
+      },
+    });
+  },
+});
+
+async function controlPlainFetchMustTimeOut(relayUrl: string): Promise<void> {
+  const startedAt = Date.now();
+  try {
+    const res = await fetch(relayUrl, {
+      method: "POST",
+      headers: { "content-type": "application/json" },
+      body: JSON.stringify({ jsonrpc: "2.0", id: "control", method: "tools/call", params: {} }),
+    });
+    await res.text();
+    fail(
+      `control plain fetch COMPLETED after ${Date.now() - startedAt}ms — the compressed idle `
+      + "watchdog is NOT active in this process; BUN_CONFIG_HTTP_IDLE_TIMEOUT did not apply and "
+      + "this E2E proves nothing",
+    );
+  } catch (error) {
+    const err = error as Error;
+    const timedOut = err.name === "TimeoutError" || /timed out/i.test(err.message);
+    if (!timedOut) fail(`control plain fetch failed with an unexpected error: ${err.name}: ${err.message}`);
+    console.log(`control: plain fetch died as expected (${err.name}) after ${Date.now() - startedAt}ms`);
+  }
+}
+
+async function proxyForwardMustComplete(): Promise<void> {
+  const proxy = new RelayMcpProxy({
+    relayMcpEndpoint: `http://127.0.0.1:${slowRelay.port}/api/mcp`,
+    getToken: () => "long-turn-e2e-live-token",
+    authSecret: SECRET,
+    enqueueBuffered: () => {},
+  });
+  const { url } = proxy.start();
+  try {
+    const startedAt = Date.now();
+    // The agent-facing hop is NOT under test here (in production it does not run under the
+    // compressed env), so it also opts out of the watchdog to avoid a false failure; the hop
+    // being verified is forward() inside the proxy, whose fetch carries the #2429 fix.
+    const agentSideInit: RequestInit & { timeout?: number | false } = {
+      method: "POST",
+      headers: { "content-type": "application/json", authorization: `Bearer ${SECRET}` },
+      body: JSON.stringify({
+        jsonrpc: "2.0",
+        id: "long-turn-1",
+        method: "tools/call",
+        params: {
+          name: "relay_run",
+          // A real maximum inline window is intentionally longer than this child's compressed
+          // watchdog. The stand-in withholds the envelope for 6s, while its unconfigured
+          // watchdog dies at ~2-4s, reproducing the pre-fix no-runId failure shape.
+          arguments: { command: "sleep 600", waitMs: 600_000, maxMs: 900_000 },
+        },
+      }),
+      timeout: false,
+    };
+    const res = await fetch(url, agentSideInit);
+    const body = await res.json() as {
+      result?: {
+        content?: Array<{ text?: string }>;
+        structuredContent?: { run?: { runId?: string; status?: string; exitCode?: number | null } };
+      };
+      error?: unknown;
+    };
+    if (!res.ok || !body.result) {
+      fail(`proxy forward returned status ${res.status} body ${JSON.stringify(body)} — forward() `
+        + "did not survive the idle watchdog; is the #2429 `timeout:false` flag present?");
+    }
+    const run = body.result?.structuredContent?.run;
+    if (run?.runId !== "long-turn-run-id" || run.status !== "still-running" || run.exitCode !== null) {
+      fail(`relay_run did not return a usable still-running + runId envelope: ${JSON.stringify(body.result)}`);
+    }
+    console.log(`real path: relay_run returned still-running + runId after ${Date.now() - startedAt}ms`);
+  } finally {
+    proxy.stop();
+  }
+}
+
+async function main(): Promise<void> {
+  const relayUrl = `http://127.0.0.1:${slowRelay.port}/api/mcp`;
+  await withDeadline("control plain fetch", controlPlainFetchMustTimeOut(relayUrl), 20_000);
+  await withDeadline("proxy forward", proxyForwardMustComplete(), 20_000);
+  slowRelay.stop(true);
+  console.log("LONG-TURN E2E PASS");
+}
+
+await withDeadline("long-turn E2E child", main(), CHILD_DEADLINE_MS).catch((error: Error) => fail(error.message));