@humwick/runner 0.0.0-stage → 0.130.0

package/src/turn-reconcile-event.ts

@@ -0,0 +1,88 @@
+import { PROVIDER_TURN_WATCHDOG_TIMELINE_STATUS, RECONCILED_TURN_TIMELINE_STATUS } from "@humwick/sdk";
+
+// Same shape the runner publishes (structurally identical to the local declarations in
+// runner-core.ts / native-self-resume.ts, which is how the other timeline producers do it).
+export interface RunnerTimelineEvent {
+  status: string;
+  id?: string;
+  timestamp: number;
+  title?: string;
+  body?: string;
+  icon?: string;
+  metadata?: Record<string, unknown>;
+}
+
+/**
+ * #1621 — the announcement for a provider-turn claim the busy backstop force-cleared.
+ *
+ * Reconciliation is a real state change, not bookkeeping repair: the turn the coordinator is
+ * waiting on is over and produced no reply, and `busy` is exactly the signal it used to decide
+ * NOT to intervene. So the clear is EMITTED (the relay turns this event into an activity row plus
+ * an `agent.turn_interrupted` notification for the spawn parent) instead of silently correcting
+ * the card — a quietly-fixed card still leaves the coordinator's plan stalled on a turn that
+ * ended. Pure builder so the payload the parent's notice is derived from is unit-testable without
+ * standing up an AgentRunner.
+ */
+export function reconciledTurnTimelineEvent(input: {
+  turnId: string;
+  reason: string;
+  startedAt: number;
+  now?: number;
+}): RunnerTimelineEvent {
+  const now = input.now ?? Date.now();
+  return {
+    status: RECONCILED_TURN_TIMELINE_STATUS,
+    id: `provider-turn-reconciled-${input.turnId}`,
+    timestamp: now,
+    title: "Provider turn cleared by reconciliation",
+    body: `The provider turn ended without a turn-end signal (${input.reason}); the agent was observed idle at its prompt and is no longer busy.`,
+    icon: "ti-alert-triangle",
+    metadata: {
+      eventType: RECONCILED_TURN_TIMELINE_STATUS,
+      reconcileReason: input.reason,
+      turnId: input.turnId,
+      turnStartedAt: input.startedAt,
+      turnAgeMs: Math.max(0, now - input.startedAt),
+    },
+  };
+}
+
+/**
+ * #1980 — the announcement for a live provider turn the busy backstop is HOLDING (not cancelling)
+ * past its prolonged-hold threshold: a frozen-active `shell` gate, or a pane-scrape-only long tool
+ * the runner cannot positively prove idle. In contrast to {@link reconciledTurnTimelineEvent} the
+ * turn is NOT ended and the card stays busy — this only surfaces "still working, held by the
+ * backstop" so a coordinator waiting on the turn knows it is alive rather than wedged-and-idle.
+ * Pure builder so the payload the parent's notice derives from is unit-testable in isolation.
+ */
+export function providerTurnWatchdogTimelineEvent(input: {
+  turnId: string;
+  reason: string;
+  startedAt: number;
+  now?: number;
+}): RunnerTimelineEvent {
+  const now = input.now ?? Date.now();
+  return {
+    status: PROVIDER_TURN_WATCHDOG_TIMELINE_STATUS,
+    id: `provider-turn-watchdog-${input.turnId}`,
+    timestamp: now,
+    title: "Provider turn held by the busy backstop",
+    body: `The provider turn has been held ${describeWatchdogAge(Math.max(0, now - input.startedAt))} without a turn-end signal (${input.reason}); the busy backstop is holding it (NOT cancelling) because it cannot positively confirm the turn ended — most likely a long-running foreground tool. No action needed unless the pane looks genuinely stalled.`,
+    icon: "ti-clock-pause",
+    metadata: {
+      eventType: PROVIDER_TURN_WATCHDOG_TIMELINE_STATUS,
+      watchdogReason: input.reason,
+      turnId: input.turnId,
+      turnStartedAt: input.startedAt,
+      turnAgeMs: Math.max(0, now - input.startedAt),
+    },
+  };
+}
+
+function describeWatchdogAge(ageMs: number): string {
+  const minutes = Math.floor(ageMs / 60_000);
+  if (minutes < 1) return "under a minute";
+  if (minutes < 60) return `${minutes} min`;
+  const hours = Math.floor(minutes / 60);
+  return `${hours}h ${minutes % 60}m`;
+}

package/src/vault-proxy-hop.ts

@@ -0,0 +1,99 @@
+import { randomBytes, timingSafeEqual } from "node:crypto";
+import { createServer, connect as netConnect, type Socket } from "node:net";
+import { connect as tlsConnect } from "node:tls";
+
+const MAX_HEAD_BYTES = 64 * 1024;
+
+export interface VaultProxyHop {
+  /** Loopback proxy origin the provider is launched with; fixed for the launch. */
+  url: string;
+  /** Local credential the provider presents as proxy username; never valid at the Vault proxy. */
+  secret: string;
+  /** Swap the upstream session token; new connections use it, open tunnels keep theirs. */
+  setToken(token: string): void;
+  close(): void;
+}
+
+function basic(user: string, password: string): string {
+  return `Basic ${Buffer.from(`${user}:${password}`).toString("base64")}`;
+}
+
+/**
+ * #3577: a running provider cannot take a new proxy URL, and Agent Vault sessions cannot be extended.
+ * The provider therefore talks to this loopback hop, which forwards each request to the Vault proxy with
+ * the current session token. Agent Vault authenticates at CONNECT, so rotation never touches open tunnels.
+ */
+export async function startVaultProxyHop(upstreamUrl: string, vault: string, token: string, ca?: string[]): Promise<VaultProxyHop> {
+  const upstream = new URL(upstreamUrl);
+  const tls = upstream.protocol === "https:";
+  const port = Number(upstream.port || (tls ? 443 : 80));
+  const secret = randomBytes(24).toString("hex");
+  const expected = Buffer.from(basic(secret, vault));
+  let upstreamAuth = basic(token, vault);
+  const sockets = new Set<Socket>();
+
+  const forward = (client: Socket, head: string, rest: Buffer) => {
+    const [requestLine = "", ...headers] = head.split("\r\n");
+    const presented = Buffer.from(headers.find((line) => /^proxy-authorization:/i.test(line))?.slice(20).trim() ?? "");
+    if (presented.length !== expected.length || !timingSafeEqual(presented, expected)) {
+      client.end("HTTP/1.1 407 Proxy Authentication Required\r\nProxy-Authenticate: Basic realm=\"agent-relay\"\r\nContent-Length: 0\r\nConnection: close\r\n\r\n");
+      return;
+    }
+    const tunnel = /^CONNECT\s/i.test(requestLine);
+    // A forwarded plain request closes after its response, so a reused socket never reaches the Vault
+    // proxy without the rewritten credential.
+    const kept = headers.filter((line) => !/^proxy-authorization:/i.test(line) && (tunnel || !/^(?:proxy-)?connection:/i.test(line)));
+    const rewritten = [requestLine, ...kept, `Proxy-Authorization: ${upstreamAuth}`, ...(tunnel ? [] : ["Connection: close"]), "", ""].join("\r\n");
+    const target = tls
+      ? tlsConnect({ host: upstream.hostname, port, servername: upstream.hostname, ...(ca ? { ca } : {}) })
+      : netConnect({ host: upstream.hostname, port });
+    sockets.add(target);
+    target.once(tls ? "secureConnect" : "connect", () => {
+      target.write(rewritten, "latin1");
+      if (rest.length) target.write(rest);
+      client.pipe(target);
+      target.pipe(client);
+      client.resume();
+    });
+    target.on("error", () => client.destroy());
+    target.on("close", () => { sockets.delete(target); client.destroy(); });
+    client.on("close", () => target.destroy());
+  };
+
+  const server = createServer((client) => {
+    sockets.add(client);
+    client.on("close", () => sockets.delete(client));
+    client.on("error", () => client.destroy());
+    let head = Buffer.alloc(0);
+    const onData = (chunk: Buffer) => {
+      head = Buffer.concat([head, chunk]);
+      const end = head.indexOf("\r\n\r\n");
+      if (end < 0) {
+        if (head.length > MAX_HEAD_BYTES) client.destroy();
+        return;
+      }
+      client.off("data", onData);
+      client.pause();
+      forward(client, head.subarray(0, end).toString("latin1"), head.subarray(end + 4));
+    };
+    client.on("data", onData);
+  });
+  await new Promise<void>((resolve, reject) => {
+    server.once("error", reject);
+    server.listen(0, "127.0.0.1", () => resolve());
+  });
+  // The provider's lifetime, not this listener, keeps the runner alive.
+  server.unref();
+  const address = server.address();
+  if (!address || typeof address === "string") throw new Error("vault_proxy_hop_unavailable");
+  return {
+    url: `http://127.0.0.1:${address.port}`,
+    secret,
+    setToken(next) { upstreamAuth = basic(next, vault); },
+    close() {
+      server.close();
+      for (const socket of sockets) socket.destroy();
+      sockets.clear();
+    },
+  };
+}

package/src/version.ts

@@ -0,0 +1,44 @@
+import { readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { CONTRACT_VERSIONS } from "@humwick/sdk";
+import { getManifest } from "@humwick/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 || "@humwick/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 } : {}),
+      ...(manifest?.provisioning?.bundledHooks?.length ? { bundledHooks: true } : {}),
+    },
+  };
+}

package/src/web-tool-call-proxy.ts

@@ -0,0 +1,128 @@
+import { errMessage, isRecord, sharedCallmuxToolCallTimeoutMsFromEnv, type WebToolCallObservation } from "@humwick/sdk";
+
+export interface WebToolLogOptions {
+  upstreamUrl: string;
+  search?(args: Record<string, unknown>, id: unknown, signal?: AbortSignal): Promise<Response>;
+  record(row: WebToolCallObservation): Promise<void>;
+}
+
+const WEB_CALLS: Record<string, { tool: "search" | "fetch"; backend: string; input: string }> = {
+  brave__brave_web_search: { tool: "search", backend: "brave", input: "query" },
+  brave__brave_llm_context: { tool: "search", backend: "brave", input: "query" },
+  fetch__fetch: { tool: "fetch", backend: "fetch", input: "url" },
+  jina__read_url: { tool: "fetch", backend: "jina", input: "url" },
+};
+const MAX_RESULT_BYTES = 8 * 1024 * 1024;
+
+async function boundedBody(response: Response): Promise<Uint8Array<ArrayBuffer>> {
+  const reader = response.body?.getReader();
+  if (!reader) return new Uint8Array();
+  const chunks: Uint8Array[] = [];
+  let size = 0;
+  try {
+    for (;;) {
+      const { value, done } = await reader.read();
+      if (done) break;
+      size += value.length;
+      if (size > MAX_RESULT_BYTES) throw new Error("WEB_RESULT_TOO_LARGE");
+      chunks.push(value);
+    }
+  } catch (error) { await reader.cancel().catch(() => {}); throw error; }
+  finally { reader.releaseLock(); }
+  const body = new Uint8Array(size);
+  let offset = 0;
+  for (const chunk of chunks) { body.set(chunk, offset); offset += chunk.length; }
+  return body;
+}
+
+function rpcOutcome(body: Uint8Array, sse: boolean): { status: string; error: string | null; resultSize: number; cacheHit: boolean | null } {
+  const text = new TextDecoder().decode(body);
+  const frames = sse ? text.split(/\r?\n\r?\n/).map(frame => frame.split(/\r?\n/).filter(line => line.startsWith("data:")).map(line => line.slice(5).trimStart()).join("\n")).filter(Boolean) : [text];
+  let rpc: Record<string, unknown> | undefined;
+  for (const frame of frames) {
+    const parsed: unknown = JSON.parse(frame);
+    if (isRecord(parsed) && ("result" in parsed || "error" in parsed)) rpc = parsed;
+  }
+  if (!rpc) throw new Error("INVALID_MCP_RESPONSE");
+  const result = isRecord(rpc.result) ? rpc.result : {};
+  const structured = isRecord(result.structuredContent) ? result.structuredContent : {};
+  const failure = isRecord(rpc.error) ? rpc.error : result.isError ? isRecord(structured.error) ? structured.error : result : undefined;
+  const meta = isRecord(result._meta) ? result._meta : {};
+  const error = failure ? (typeof failure.message === "string" ? failure.message : JSON.stringify(failure.content ?? failure)).slice(0, 1000) : null;
+  return {
+    status: failure ? typeof failure.code === "number" || typeof failure.code === "string" ? String(failure.code) : "TOOL_ERROR" : "success",
+    error, resultSize: new TextEncoder().encode(JSON.stringify(rpc.result ?? rpc.error)).length,
+    cacheHit: typeof meta.cacheHit === "boolean" ? meta.cacheHit : null,
+  };
+}
+
+/** The shared bridge and meta-only downstream both cross this per-agent seam. */
+export async function forwardSharedMcp(req: Request, options: WebToolLogOptions): Promise<Response> {
+  const text = req.method === "POST" ? await req.text() : undefined;
+  let rpc: Record<string, unknown> | undefined;
+  let call: Record<string, unknown> | undefined;
+  try { const parsed = JSON.parse(text ?? "null"); if (isRecord(parsed)) rpc = parsed; if (rpc?.method === "tools/call" && isRecord(rpc.params)) call = rpc.params; } catch {}
+  const spec = typeof call?.name === "string" ? WEB_CALLS[call.name] : undefined;
+  const args = isRecord(call?.arguments) ? call.arguments : {};
+  if (call?.name === "web_search" || spec?.tool === "search") {
+    if (!options.search) return Response.json({ jsonrpc: "2.0", id: rpc?.id, error: { code: -32000, message: "Relay web_search is unavailable" } });
+    return options.search({ query: args.query, ...(args.count !== undefined ? { count: args.count } : {}) }, rpc?.id, req.signal);
+  }
+  const time = Date.now();
+  const started = performance.now();
+  const row: WebToolCallObservation | undefined = spec ? {
+    id: crypto.randomUUID(), time, tool: spec.tool, backend: spec.backend,
+    input: String(args[spec.input] ?? "").slice(0, 16_000), status: "success", error: null,
+    durationMs: 0, resultSize: 0, cacheHit: null, fallbackChain: [spec.backend],
+  } : undefined;
+  let response: Response;
+  try {
+    const headers = new Headers();
+    for (const key of ["accept", "content-type", "mcp-session-id", "mcp-protocol-version", "x-callmux-cwd", "last-event-id"]) {
+      const value = req.headers.get(key); if (value) headers.set(key, value);
+    }
+    response = await fetch(options.upstreamUrl, {
+      method: req.method, headers, body: text,
+      signal: AbortSignal.any([req.signal, AbortSignal.timeout(sharedCallmuxToolCallTimeoutMsFromEnv())]),
+      // Bun's idle watchdog must not preempt the shared MCP call budget.
+      timeout: false,
+    } as RequestInit & { timeout: false });
+    if (!row) {
+      if (rpc?.method === "tools/list" && response.ok) return neutralSearchManifest(response);
+      return response;
+    }
+    const body = await boundedBody(response);
+    Object.assign(row, response.ok ? rpcOutcome(body, response.headers.get("content-type")?.includes("text/event-stream") ?? false)
+      : { status: `HTTP_${response.status}`, error: new TextDecoder().decode(body).slice(0, 1000), resultSize: body.length });
+    const outputHeaders = new Headers(response.headers);
+    outputHeaders.delete("content-encoding"); outputHeaders.delete("content-length");
+    response = new Response(body, { status: response.status, headers: outputHeaders });
+  } catch (error) {
+    if (!row) throw error;
+    row.status = isRecord(error) && typeof error.code === "string" ? error.code : error instanceof Error && error.name === "TimeoutError" ? "TIMEOUT" : "TRANSPORT_ERROR";
+    row.error = errMessage(error).slice(0, 1000);
+    response = Response.json({ jsonrpc: "2.0", id: null, error: { code: -32000, message: row.error } }, { status: 502 });
+  }
+  row!.durationMs = Math.max(0, Math.round(performance.now() - started));
+  try { await options.record(row!); }
+  catch (error) {
+    return Response.json({ jsonrpc: "2.0", id: null, error: { code: -32000, message: `WEB_CALL_LOG_FAILED: ${errMessage(error)}` } }, { status: 503 });
+  }
+  return response;
+}
+
+async function neutralSearchManifest(response: Response): Promise<Response> {
+  const body = new TextDecoder().decode(await boundedBody(response));
+  const rewrite = (text: string) => {
+    const rpc = JSON.parse(text);
+    if (isRecord(rpc.result) && Array.isArray(rpc.result.tools)) {
+      rpc.result.tools = rpc.result.tools.filter((tool: { name?: string }) => !tool.name?.startsWith("brave__") && tool.name !== "web_search");
+    }
+    return JSON.stringify(rpc);
+  };
+  const output = response.headers.get("content-type")?.includes("text/event-stream")
+    ? body.replace(/^data: (.+)$/gm, (_, text) => `data: ${rewrite(text)}`) : rewrite(body);
+  const headers = new Headers(response.headers);
+  headers.delete("content-encoding"); headers.delete("content-length");
+  return new Response(output, { status: response.status, headers });
+}

package/src/web-tools.ts

@@ -0,0 +1,59 @@
+import { writeChildEnv } from "@humwick/sdk/env";
+import { profileWebToolEnabled, sharedWebToolNames, WEB_TOOL_NAMES, WEB_TOOLS_ENV, type WebToolName } from "@humwick/sdk/web-tools";
+import { webSearchEnabledFromEnv, SHARED_MCP_SERVER_NAME, type ProvisioningMcpServer } from "@humwick/sdk";
+import type { RunnerSpawnConfig } from "./adapter";
+import { profileAllowsRelayFeature, webToolsSteer } from "./relay-instructions";
+
+// The legacy webTools.brave switch controls Relay search; credentials stay on the hub.
+
+type WebToolsConfig = Pick<RunnerSpawnConfig, "agentProfile">;
+
+/** Search uses Relay MCP; readers use the shared bridge. */
+export function launchWebTools(config: WebToolsConfig, env: Record<string, string | undefined> = process.env): WebToolName[] {
+  return WEB_TOOL_NAMES.filter((name) => profileWebToolEnabled(config.agentProfile, name)
+    && (name === "brave" ? profileAllowsRelayFeature(config, "mcp") && webSearchEnabledFromEnv(env) : Boolean(config.agentProfile?.sharedMcp)));
+}
+
+/** Shared-listener tool names the profile switched off. */
+export function disabledSharedWebTools(config: WebToolsConfig): string[] {
+  if (!config.agentProfile?.sharedMcp) return [];
+  const disabled = WEB_TOOL_NAMES.filter((name) => !profileWebToolEnabled(config.agentProfile, name)).flatMap(sharedWebToolNames);
+  return disabled;
+}
+
+export function claudeDisallowedWebTools(config: WebToolsConfig): string[] {
+  return disabledSharedWebTools(config).map((tool) => `mcp__${SHARED_MCP_SERVER_NAME}__${tool}`);
+}
+
+/** Claude reads its steer from the launch system prompt: the monitor's context only arrives with a Relay message. */
+export function claudeWebToolsSteer(config: WebToolsConfig): string {
+  return profileAllowsRelayFeature(config, "context") ? webToolsSteer(launchWebTools(config), true) : "";
+}
+
+/** Always set, so a launch never inherits a parent agent's list. */
+export function webToolsEnv(config: WebToolsConfig): Record<string, string> {
+  return writeChildEnv({}, { [WEB_TOOLS_ENV]: launchWebTools(config).join(","), AGENT_RELAY_WEB_SEARCH: webSearchEnabledFromEnv() ? "1" : "0" });
+}
+
+/** Codex hides switched-off tools on the flat bridge with its native per-server denylist. */
+export function withDisabledWebTools(server: ProvisioningMcpServer, config: WebToolsConfig): ProvisioningMcpServer {
+  const disabled = disabledSharedWebTools(config);
+  return disabled.length ? { ...server, disabled_tools: disabled } : server;
+}
+
+/** OpenCode names an MCP tool `<server>_<tool>`; its config `tools` map turns one off. */
+export function openCodeWebToolsConfig(config: WebToolsConfig): { tools?: Record<string, false> } {
+  const disabled = disabledSharedWebTools(config);
+  return disabled.length ? { tools: Object.fromEntries(disabled.map((tool) => [`${SHARED_MCP_SERVER_NAME}_${tool}`, false])) } : {};
+}
+
+/** #3250: Codex's one web_search tool also owns open/find; it cannot disable search and fetch separately. */
+export function codexWebToolsConfigArgs(config: WebToolsConfig): string[] {
+  return launchWebTools(config).length ? ["-c", 'web_search="disabled"'] : [];
+}
+
+/** OpenCode 1.19.0: explicit permission rules follow the wildcard allow (tools=false is legacy). */
+export function openCodeNativeWebPermissions(config: WebToolsConfig): Record<string, "deny"> {
+  const tools = launchWebTools(config);
+  return { ...(tools.includes("brave") ? { websearch: "deny" as const } : {}), ...(tools.includes("jina") ? { webfetch: "deny" as const } : {}) };
+}

package/README.md

@@ -1,3 +0,0 @@
-# Temporary Holding Version
-
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.