impel-cli 0.20.41 → 0.20.43

package/src/nativeAgentTransport.js

@@ -1,6 +1,7 @@
 import crypto from "node:crypto";
 import fs from "node:fs";
 import path from "node:path";
+import { fileURLToPath } from "node:url";
 
 import {
   CONFIG_DIR,
@@ -24,9 +25,11 @@ import {
 import { extractAnswerFinalText } from "./directAnswer.js";
 import {
   IMPEL_NATIVE_AGENT_ATTACHMENT_WINDOW_ENV,
+  nativeBenchmarkHeaderValue,
 } from "./selfInvocation.js";
 import { normalizeTenantId } from "./tenants.js";
 import { renameWithWindowsRetry } from "./windowsFs.js";
+import { CURRENT_CONFIG_VERSION } from "./managedProfileVersion.js";
 
 export {
   NATIVE_AGENT_ANSWER_TOOL,
@@ -38,6 +41,10 @@ export {
 export const NATIVE_AGENT_HANDLE_SCHEMA = "impel.native-agent-run.v1";
 export const NATIVE_AGENT_RESULT_SCHEMA = "impel.native-agent-result.v1";
 export const NATIVE_AGENT_RECOVERY_SCHEMA = "impel.native-agent-recovery.v1";
+export const NATIVE_AGENT_BENCHMARK_HEADER = "X-Impel-Client-Benchmark";
+export const NATIVE_AGENT_CLIENT_BUILD = `cli/${JSON.parse(
+  fs.readFileSync(fileURLToPath(new URL("../package.json", import.meta.url)), "utf8"),
+).version}+manifest.v${CURRENT_CONFIG_VERSION}`;
 
 const STATE_SCHEMA = "impel.native-agent-state.v1";
 const DELETION_SCHEMA = "impel.native-agent-deletion.v1";
@@ -47,8 +54,9 @@ const SAFE_FINGERPRINT_RE = /^[a-f0-9]{64}$/u;
 const SAFE_INVOCATION_RE = /^[a-f0-9-]{36}$/u;
 const DEFAULT_WAIT_SECONDS = 20;
 const MAX_WAIT_SECONDS = 35;
-const DEFAULT_ATTACHMENT_WINDOW_MS = 40_000;
-const DEFAULT_UPSTREAM_TIMEOUT_MS = 42_000;
+export const DEFAULT_ATTACHMENT_WINDOW_MS = 40_000;
+export const DEFAULT_UPSTREAM_TIMEOUT_MS = 42_000;
+const DEFAULT_ANSWER_HEDGE_MS = 38_000;
 const DEFAULT_MAX_POLLS = 8;
 const DEFAULT_RETENTION_MS = 30 * 24 * 60 * 60 * 1000;
 const DEFAULT_MAX_RETAINED_RUNS = 500;
@@ -68,6 +76,11 @@ const MANAGED_VIRTUAL_KEY_MISS_RETRY_DELAY_MS = 250;
 const NEXT_AMBIGUOUS_ANSWER_CODE = "native_agent_answer_ambiguous";
 const MCP_TOOL_RESULT_ERROR = Symbol("native-agent MCP tool result error");
 const TERMINAL_STATUSES = new Set(["succeeded", "failed", "cancelled", "canceled"]);
+const SAFE_CLIENT_BUILD_RE = /^[A-Za-z0-9._+/-]{1,128}$/u;
+
+if (!SAFE_CLIENT_BUILD_RE.test(NATIVE_AGENT_CLIENT_BUILD)) {
+  throw new Error("native-agent client build header is invalid");
+}
 
 export function nativeAgentAttachmentWindowMs(environment = process.env) {
   const configured = environment?.[IMPEL_NATIVE_AGENT_ATTACHMENT_WINDOW_ENV];
@@ -82,6 +95,30 @@ export function nativeAgentAttachmentWindowMs(environment = process.env) {
   return parsed;
 }
 
+export function nativeAgentAnswerHedgeMs(environment = process.env, { warn = console.warn } = {}) {
+  const configured = environment?.IMPEL_NATIVE_ANSWER_HEDGE_MS;
+  if (configured === undefined) return DEFAULT_ANSWER_HEDGE_MS;
+  if (!/^\d{1,9}$/u.test(configured)) {
+    warn(`IMPEL_NATIVE_ANSWER_HEDGE_MS must be a non-negative integer; using ${DEFAULT_ANSWER_HEDGE_MS}ms`);
+    return DEFAULT_ANSWER_HEDGE_MS;
+  }
+  const parsed = Number(configured);
+  if (!Number.isSafeInteger(parsed)) {
+    warn(`IMPEL_NATIVE_ANSWER_HEDGE_MS must be a safe integer; using ${DEFAULT_ANSWER_HEDGE_MS}ms`);
+    return DEFAULT_ANSWER_HEDGE_MS;
+  }
+  if (parsed === 0) return 0;
+  const maximum = Math.min(DEFAULT_ATTACHMENT_WINDOW_MS, DEFAULT_UPSTREAM_TIMEOUT_MS) - 1;
+  if (parsed >= DEFAULT_ATTACHMENT_WINDOW_MS || parsed >= DEFAULT_UPSTREAM_TIMEOUT_MS) {
+    warn(
+      `IMPEL_NATIVE_ANSWER_HEDGE_MS must be below ${DEFAULT_ATTACHMENT_WINDOW_MS}ms `
+      + `and ${DEFAULT_UPSTREAM_TIMEOUT_MS}ms; clamping to ${maximum}ms`,
+    );
+    return maximum;
+  }
+  return parsed;
+}
+
 function stableValue(value) {
   if (Array.isArray(value)) return value.map(stableValue);
   if (!value || typeof value !== "object") return value;
@@ -704,6 +741,10 @@ export class NativeAgentUpstreamSession {
     telemetry = () => {},
     now = Date.now,
     requestIdFactory = crypto.randomUUID,
+    answerHedgeMs = nativeAgentAnswerHedgeMs(),
+    setTimeoutImpl = setTimeout,
+    clearTimeoutImpl = clearTimeout,
+    environment = process.env,
   }) {
     this.endpoint = `${normalizeGatewayUrl(gatewayUrl)}/mcp`;
     this.credential = credential;
@@ -714,6 +755,10 @@ export class NativeAgentUpstreamSession {
     this.telemetry = telemetry;
     this.now = now;
     this.requestIdFactory = requestIdFactory;
+    this.answerHedgeMs = Math.max(0, answerHedgeMs);
+    this.setTimeoutImpl = setTimeoutImpl;
+    this.clearTimeoutImpl = clearTimeoutImpl;
+    this.benchmarkHeaderValue = nativeBenchmarkHeaderValue(environment);
     this.sessionId = null;
     this.nextId = 1;
   }
@@ -729,7 +774,7 @@ export class NativeAgentUpstreamSession {
     let timedOut = false;
     const onAbort = () => controller.abort();
     signal?.addEventListener("abort", onAbort, { once: true });
-    const timeout = setTimeout(() => {
+    const timeout = this.setTimeoutImpl(() => {
       timedOut = true;
       controller.abort();
     }, this.timeoutMs);
@@ -743,6 +788,10 @@ export class NativeAgentUpstreamSession {
           "Content-Type": "application/json",
           Accept: "application/json, text/event-stream",
           "X-Impel-Client-Request-Id": correlationId,
+          "X-Impel-Client-Build": NATIVE_AGENT_CLIENT_BUILD,
+          ...(this.benchmarkHeaderValue
+            ? { [NATIVE_AGENT_BENCHMARK_HEADER]: this.benchmarkHeaderValue }
+            : {}),
           ...(this.sessionId ? { "Mcp-Session-Id": this.sessionId } : {}),
         },
         body: JSON.stringify(message),
@@ -760,7 +809,7 @@ export class NativeAgentUpstreamSession {
       const detail = timedOut ? "request timed out" : redactSecretText(error?.message || error);
       throw new NativeAgentUpstreamError(`native-agent MCP request failed: ${detail}`, { ambiguous: true });
     } finally {
-      clearTimeout(timeout);
+      this.clearTimeoutImpl(timeout);
       signal?.removeEventListener("abort", onAbort);
     }
     this.telemetry("upstream_request_completed", {
@@ -814,17 +863,78 @@ export class NativeAgentUpstreamSession {
     return toolsResponse.result.tools;
   }
 
-  async call(name, args, { signal } = {}) {
+  async ping({ signal } = {}) {
+    const id = this.nextId++;
+    const messages = await this.post({ jsonrpc: "2.0", id, method: "ping", params: {} }, { signal });
+    const response = messages.find((message) => message?.id === id);
+    if (response?.error || !response?.result || typeof response.result !== "object") {
+      throw new NativeAgentUpstreamError("native-agent MCP ping failed");
+    }
+  }
+
+  async callAnswerWithHedge(message, { signal, onHedge } = {}) {
+    throwIfAborted(signal);
+    const startedAt = this.now();
+    const controller = new AbortController();
+    let hedgeFired = false;
+    let elapsedMs = 0;
+    let replayTerminal = false;
+    const onAbort = () => controller.abort();
+    signal?.addEventListener("abort", onAbort, { once: true });
+    const timer = this.setTimeoutImpl(() => {
+      if (controller.signal.aborted) return;
+      hedgeFired = true;
+      elapsedMs = Math.max(0, this.now() - startedAt);
+      onHedge?.();
+      controller.abort();
+    }, this.answerHedgeMs);
+    try {
+      try {
+        const messages = await this.post(message, { signal: controller.signal });
+        return toolPayload(messages.find((candidate) => candidate?.id === message.id));
+      } catch (error) {
+        if (!hedgeFired || signal?.aborted) throw error;
+      } finally {
+        this.clearTimeoutImpl(timer);
+        signal?.removeEventListener("abort", onAbort);
+      }
+
+      try {
+        const messages = await this.post(message, { signal });
+        const payload = toolPayload(messages.find((candidate) => candidate?.id === message.id));
+        replayTerminal = TERMINAL_STATUSES.has(payload?.status);
+        return payload;
+      } finally {
+        this.telemetry("hedge_fired", { elapsedMs, replayTerminal });
+      }
+    } finally {
+      this.clearTimeoutImpl(timer);
+      signal?.removeEventListener("abort", onAbort);
+    }
+  }
+
+  async call(name, args, { signal = this.signal, hedge = true } = {}) {
+    let hedgeFiredForCall = false;
     for (let attempt = 0; attempt < 2; attempt += 1) {
       const id = this.nextId++;
+      const message = {
+        jsonrpc: "2.0",
+        id,
+        method: "tools/call",
+        params: { name, arguments: args },
+      };
       try {
-        const messages = await this.post({
-          jsonrpc: "2.0",
-          id,
-          method: "tools/call",
-          params: { name, arguments: args },
-        }, { signal });
-        return toolPayload(messages.find((message) => message?.id === id));
+        if (name === NATIVE_AGENT_UPSTREAM_ANSWER_TOOL
+          && hedge
+          && !hedgeFiredForCall
+          && this.answerHedgeMs > 0) {
+          return await this.callAnswerWithHedge(message, {
+            signal,
+            onHedge: () => { hedgeFiredForCall = true; },
+          });
+        }
+        const messages = await this.post(message, { signal });
+        return toolPayload(messages.find((candidate) => candidate?.id === id));
       } catch (error) {
         if (attempt === 0 && retryableManagedVirtualKeyMiss(error)) {
           // This gateway-authored miss happens before a native run can exist.
@@ -1700,7 +1810,7 @@ export class NativeAgentCompositeTransport {
     }
   }
 
-  async prepareExistingSession(signal) {
+  async prepareExistingSession(signal, { prewarmed = false } = {}) {
     const reused = Boolean(this.preparedSession);
     const startedAt = this.now();
     if (!this.preparedSession) {
@@ -1717,15 +1827,16 @@ export class NativeAgentCompositeTransport {
     this.telemetry("session_prepared", {
       durationMs: this.now() - startedAt,
       handshakeReused: reused,
+      prewarmed,
     });
     return prepared;
   }
 
-  async prepareNewSession(signal) {
-    const prepared = await this.prepareExistingSession(signal);
+  async prepareNewSession(signal, { prewarmed = false } = {}) {
+    const prepared = await this.prepareExistingSession(signal, { prewarmed });
     const startedAt = this.now();
     if (this.preparedAgent) {
-      this.telemetry("binding_completed", { durationMs: 0, bindingReused: true });
+      this.telemetry("binding_completed", { durationMs: 0, bindingReused: true, prewarmed });
       return { ...prepared, agent: this.preparedAgent };
     }
     const catalog = normalizeNativeAgentCatalog(
@@ -1746,10 +1857,29 @@ export class NativeAgentCompositeTransport {
     this.telemetry("binding_completed", {
       durationMs: this.now() - startedAt,
       bindingReused: false,
+      prewarmed,
     });
     return { ...prepared, agent: this.preparedAgent };
   }
 
+  async refreshPreparedSession(signal, { prewarmed = true } = {}) {
+    const prepared = await this.prepareNewSession(signal, { prewarmed });
+    try {
+      await prepared.session.ping({ signal });
+    } catch (error) {
+      const cached = this.preparedSession;
+      if (cached) {
+        try {
+          if ((await cached).session === prepared.session) this.preparedSession = null;
+        } catch {
+          this.preparedSession = null;
+        }
+      }
+      throw error;
+    }
+    return prepared;
+  }
+
   async preparePersistedStartSession(signal, state) {
     const prepared = await this.prepareExistingSession(signal);
     const catalog = normalizeNativeAgentCatalog(
@@ -2189,7 +2319,7 @@ export class NativeAgentCompositeTransport {
             started = await session.call(
               answerMode ? NATIVE_AGENT_UPSTREAM_ANSWER_TOOL : NATIVE_AGENT_START_TOOL,
               outboundArguments,
-              { signal },
+              { signal, hedge: answerMode && attempt === 0 },
             );
             if (answerMode) {
               if (!started?.runId) {

package/src/nativeInterception.js

@@ -0,0 +1,133 @@
+import fs from "node:fs";
+import path from "node:path";
+
+import { impelCliInvocation } from "./selfInvocation.js";
+import { renameWithWindowsRetry } from "./windowsFs.js";
+
+export const IMPEL_NATIVE_INTERCEPT_ENV = "IMPEL_NATIVE_INTERCEPT";
+export const IMPEL_NATIVE_INTERCEPT_TIMEOUT_ENV = "IMPEL_NATIVE_INTERCEPT_TIMEOUT_MS";
+export const DEFAULT_NATIVE_INTERCEPT_TIMEOUT_MS = 100_000;
+export const MANAGED_NATIVE_INTERCEPT_FLAG = "impel-managed-native-intercept-v1";
+
+export function nativeInterceptEnabled(environment = process.env) {
+  return ["1", "true"].includes(
+    String(environment?.[IMPEL_NATIVE_INTERCEPT_ENV] || "").toLowerCase(),
+  );
+}
+
+export function nativeInterceptTimeoutMs(environment = process.env) {
+  const configured = environment?.[IMPEL_NATIVE_INTERCEPT_TIMEOUT_ENV];
+  if (configured === undefined || configured === "") return DEFAULT_NATIVE_INTERCEPT_TIMEOUT_MS;
+  if (!/^\d{1,6}$/u.test(configured)) {
+    throw new Error(`${IMPEL_NATIVE_INTERCEPT_TIMEOUT_ENV} must be an integer from 1000 through 300000`);
+  }
+  const timeoutMs = Number(configured);
+  if (!Number.isSafeInteger(timeoutMs) || timeoutMs < 1_000 || timeoutMs > 300_000) {
+    throw new Error(`${IMPEL_NATIVE_INTERCEPT_TIMEOUT_ENV} must be an integer from 1000 through 300000`);
+  }
+  return timeoutMs;
+}
+
+function readJsonObject(filePath) {
+  if (!fs.existsSync(filePath)) return {};
+  const raw = fs.readFileSync(filePath, "utf8").trim();
+  if (!raw) return {};
+  try {
+    const value = JSON.parse(raw);
+    if (!value || Array.isArray(value) || typeof value !== "object") throw new Error();
+    return value;
+  } catch {
+    throw new Error(`${filePath} exists but isn't a valid JSON object. Fix or remove it, then re-run.`);
+  }
+}
+
+function writePrivateJson(filePath, value) {
+  fs.mkdirSync(path.dirname(filePath), { recursive: true, mode: 0o700 });
+  const temporaryPath = `${filePath}.tmp-${process.pid}`;
+  try {
+    fs.writeFileSync(temporaryPath, `${JSON.stringify(value, null, 2)}\n`, { mode: 0o600 });
+    renameWithWindowsRetry(temporaryPath, filePath);
+    try { fs.chmodSync(filePath, 0o600); } catch { /* Best effort on Windows. */ }
+  } finally {
+    try { fs.rmSync(temporaryPath, { force: true }); } catch { /* Rename removed it. */ }
+  }
+}
+
+function handlerIsManaged(handler) {
+  return handler
+    && typeof handler === "object"
+    && Array.isArray(handler.args)
+    && handler.args.includes(`--${MANAGED_NATIVE_INTERCEPT_FLAG}`);
+}
+
+function removeManagedHandlers(groups) {
+  if (!Array.isArray(groups)) return { groups, changed: false };
+  let changed = false;
+  const preserved = [];
+  for (const group of groups) {
+    if (!group || typeof group !== "object" || !Array.isArray(group.hooks)) {
+      preserved.push(group);
+      continue;
+    }
+    const hooks = group.hooks.filter((handler) => {
+      if (!handlerIsManaged(handler)) return true;
+      changed = true;
+      return false;
+    });
+    if (hooks.length > 0) preserved.push({ ...group, hooks });
+  }
+  return { groups: preserved, changed };
+}
+
+export function claudeNativeInterceptHandler(tenantId, timeoutMs, invocation = null) {
+  const command = invocation || impelCliInvocation([
+    "native", "intercept",
+    "--tenant", tenantId,
+    `--${MANAGED_NATIVE_INTERCEPT_FLAG}`,
+  ]);
+  return {
+    type: "command",
+    command: command.command,
+    args: [...command.args],
+    timeout: Math.ceil(timeoutMs / 1000),
+    async: false,
+  };
+}
+
+/** Install or remove only Impel's synchronous UserPromptSubmit interception hook. */
+export function ensureClaudeNativeInterceptHook(configDir, tenantId, {
+  enabled = false,
+  timeoutMs = DEFAULT_NATIVE_INTERCEPT_TIMEOUT_MS,
+  invocation = null,
+} = {}) {
+  const settingsPath = path.join(configDir, "settings.json");
+  if (!enabled) {
+    try {
+      if (!fs.readFileSync(settingsPath, "utf8").includes(`--${MANAGED_NATIVE_INTERCEPT_FLAG}`)) {
+        return { settingsPath, enabled: false, changed: false };
+      }
+    } catch (error) {
+      if (error?.code === "ENOENT") return { settingsPath, enabled: false, changed: false };
+      throw error;
+    }
+  }
+  const settings = readJsonObject(settingsPath);
+  const hooks = settings.hooks && typeof settings.hooks === "object" && !Array.isArray(settings.hooks)
+    ? { ...settings.hooks }
+    : {};
+  const removed = removeManagedHandlers(hooks.UserPromptSubmit);
+  if (!enabled && !removed.changed) {
+    return { settingsPath, enabled: false, changed: false };
+  }
+  if (enabled) {
+    removed.groups.push({
+      hooks: [claudeNativeInterceptHandler(tenantId, timeoutMs, invocation)],
+    });
+  }
+  if (removed.groups.length > 0) hooks.UserPromptSubmit = removed.groups;
+  else delete hooks.UserPromptSubmit;
+  if (Object.keys(hooks).length > 0) settings.hooks = hooks;
+  else delete settings.hooks;
+  writePrivateJson(settingsPath, settings);
+  return { settingsPath, enabled, changed: true };
+}

package/src/selfInvocation.js

@@ -82,9 +82,23 @@ export const IMPEL_NATIVE_AGENT_TELEMETRY_ENV_NAMES = [
   "IMPEL_NATIVE_HOST",
   "IMPEL_NATIVE_HOST_BUILD",
 ];
+export const IMPEL_NATIVE_BENCHMARK_ENV = "IMPEL_NATIVE_BENCHMARK";
 export const IMPEL_NATIVE_AGENT_ATTACHMENT_WINDOW_ENV = "IMPEL_NATIVE_AGENT_ATTACHMENT_WINDOW_MS";
 export const CODEX_NATIVE_AGENT_ATTACHMENT_WINDOW_MS = 100_000;
 
+const SAFE_NATIVE_BENCHMARK_HEADER_VALUE = /^[\x21-\x7e]{1,128}$/u;
+
+export function nativeBenchmarkHeaderValue(environment = process.env) {
+  const value = environment?.[IMPEL_NATIVE_BENCHMARK_ENV];
+  if (value === undefined) return null;
+  if (typeof value !== "string"
+    || value !== "1"
+    || !SAFE_NATIVE_BENCHMARK_HEADER_VALUE.test(value)) {
+    throw new Error(`${IMPEL_NATIVE_BENCHMARK_ENV} must be exactly 1 using visible ASCII`);
+  }
+  return value;
+}
+
 function managedMcpEnvironment(environment = process.env) {
   const telemetry = Object.fromEntries(
     IMPEL_NATIVE_AGENT_TELEMETRY_ENV_NAMES.flatMap((name) => {
@@ -92,7 +106,12 @@ function managedMcpEnvironment(environment = process.env) {
       return typeof value === "string" && value.length > 0 ? [[name, value]] : [];
     }),
   );
-  return { [IMPEL_MANAGED_MCP_ENV]: "1", ...telemetry };
+  const benchmark = nativeBenchmarkHeaderValue(environment);
+  return {
+    [IMPEL_MANAGED_MCP_ENV]: "1",
+    ...telemetry,
+    ...(benchmark ? { [IMPEL_NATIVE_BENCHMARK_ENV]: benchmark } : {}),
+  };
 }
 
 export function impelMcpInvocation(args = [], options = {}) {