impel-cli 0.20.41 → 0.20.42

package/src/commands/launch.js

@@ -99,6 +99,32 @@ export function impelLaunchArguments(tool, argv, {
   if (!RUNTIME_BRAND.features.agents) return [...argv];
   if (tool === "claude") {
     if (claudeManagedAgent) {
+      if (claudeManagedAgent.parentDirect === true) {
+        const { parentLaunchDefinition, parentMcpConfigJson } = claudeManagedAgent;
+        if (!parentLaunchDefinition
+          || typeof parentLaunchDefinition.prompt !== "string"
+          || !parentLaunchDefinition.prompt
+          || !Array.isArray(parentLaunchDefinition.tools)
+          || parentLaunchDefinition.tools.length !== 2
+          || typeof parentMcpConfigJson !== "string"
+          || !parentMcpConfigJson) {
+          throw new Error("managed Claude parent-direct launch configuration is invalid");
+        }
+        const tools = parentLaunchDefinition.tools.join(",");
+        return [
+          ...IMPEL_CLAUDE_MANAGED_AGENT_ARGUMENTS,
+          "--mcp-config",
+          parentMcpConfigJson,
+          "--strict-mcp-config",
+          "--tools",
+          tools,
+          "--allowedTools",
+          tools,
+          "--append-system-prompt",
+          parentLaunchDefinition.prompt,
+          ...argv,
+        ];
+      }
       const { launchName, launchAgentsJson } = claudeManagedAgent;
       if (typeof launchName !== "string"
         || !launchName

package/src/commands/mcp.js

@@ -198,14 +198,73 @@ export function runNativeAgentMcpServer({
   output = process.stdout,
   mode = "durable",
   telemetry = () => {},
+  environment = process.env,
+  random = Math.random,
+  answerToolDescription = null,
 }) {
   if (!["durable", "recovery", "answer"].includes(mode)) throw new Error("invalid native-agent MCP mode");
   const lines = readline.createInterface({ input, crlfDelay: Infinity });
   const active = new Map();
   const pending = new Set();
+  const needsUpstream = mode === "durable" || mode === "answer";
+  const prewarmController = new AbortController();
+  let prewarmTimer = null;
+  let prewarmStarted = false;
+  let refreshTimer = null;
+  let refreshInFlight = false;
   let progress = 0;
   const write = (value) => output.write(`${value}\n`);
 
+  function startPrewarm() {
+    if (!needsUpstream || prewarmStarted) return;
+    prewarmStarted = true;
+    if (prewarmTimer) {
+      clearTimeout(prewarmTimer);
+      prewarmTimer = null;
+    }
+    Promise.resolve()
+      .then(() => transport.prepareNewSession(prewarmController.signal, { prewarmed: true }))
+      .catch(() => {});
+  }
+
+  function schedulePrewarm() {
+    if (!needsUpstream || prewarmStarted || prewarmTimer) return;
+    const jitterMs = 50 + Math.min(
+      200,
+      Math.floor(Math.max(0, Math.min(1, random())) * 201),
+    );
+    prewarmTimer = setTimeout(() => {
+      prewarmTimer = null;
+      startPrewarm();
+    }, jitterMs);
+    prewarmTimer.unref?.();
+  }
+
+  function refreshIntervalMs() {
+    const configured = environment?.IMPEL_NATIVE_PREWARM_REFRESH_MS;
+    if (configured === undefined || configured === "0") return 0;
+    if (!/^\d{1,9}$/u.test(configured)) return 0;
+    const parsed = Number(configured);
+    return Number.isSafeInteger(parsed) && parsed > 0 ? parsed : 0;
+  }
+
+  telemetry("local_server_started");
+  schedulePrewarm();
+  const refreshMs = needsUpstream ? refreshIntervalMs() : 0;
+  if (refreshMs > 0) {
+    refreshTimer = setInterval(() => {
+      if (refreshInFlight || prewarmController.signal.aborted) return;
+      refreshInFlight = true;
+      Promise.resolve()
+        .then(() => typeof transport.refreshPreparedSession === "function"
+          ? transport.refreshPreparedSession(prewarmController.signal, { prewarmed: true })
+          : transport.prepareNewSession(prewarmController.signal, { prewarmed: true }))
+        .catch(() => {})
+        .finally(() => { refreshInFlight = false; });
+    }, refreshMs);
+    refreshTimer.unref?.();
+  }
+
   function schedule(message) {
     const request = tasksJsonRpcRequestId(message);
     if (!request.valid) {
@@ -227,6 +286,7 @@ export function runNativeAgentMcpServer({
       let telemetryTool;
       try {
         if (message.method === "initialize") {
+          startPrewarm();
           write(nativeRpcResult(message.id, {
             protocolVersion: "2025-06-18",
             capabilities: { tools: {} },
@@ -239,8 +299,13 @@ export function runNativeAgentMcpServer({
           return;
         }
         if (message.method === "tools/list") {
+          const tools = nativeAgentCompositeTools({ mode });
+          if (mode === "answer" && typeof answerToolDescription === "string") {
+            const answerTool = tools.find(({ name }) => name === NATIVE_AGENT_ANSWER_TOOL);
+            if (answerTool) answerTool.description = answerToolDescription;
+          }
           write(nativeRpcResult(message.id, {
-            tools: nativeAgentCompositeTools({ mode }),
+            tools,
           }));
           return;
         }
@@ -326,6 +391,9 @@ export function runNativeAgentMcpServer({
   });
   return new Promise((resolve) => {
     lines.on("close", async () => {
+      if (prewarmTimer) clearTimeout(prewarmTimer);
+      if (refreshTimer) clearInterval(refreshTimer);
+      prewarmController.abort();
       for (const controller of active.values()) controller.abort();
       await Promise.allSettled([...pending]);
       resolve();
@@ -340,6 +408,7 @@ export async function cmdMcp(argv = []) {
     "agent-id": { type: "string" },
     "scope-param": { type: "string" },
     "policy-fingerprint": { type: "string" },
+    "agent-title": { type: "string" },
     "recovery-only": { type: "boolean" },
     "answer-only": { type: "boolean" },
   });
@@ -361,7 +430,7 @@ export async function cmdMcp(argv = []) {
   if (nativeAgentTarget) {
     const expectedFlags = [
       "target", "tenant", "agent-id", "scope-param", "policy-fingerprint",
-      "recovery-only", "answer-only",
+      "agent-title", "recovery-only", "answer-only",
     ];
     const unsupportedFlags = Object.keys(flags).filter((name) => !expectedFlags.includes(name));
     if (unsupportedFlags.length > 0 || positionals.length > 0) {
@@ -375,9 +444,18 @@ export async function cmdMcp(argv = []) {
     if (flags["recovery-only"] === true && flags["answer-only"] === true) {
       throw new Error("native-agent MCP cannot be both recovery-only and answer-only");
     }
+    if (Object.hasOwn(flags, "agent-title") && (
+      flags["answer-only"] !== true
+      || typeof flags["agent-title"] !== "string"
+      || !flags["agent-title"].trim()
+      || flags["agent-title"].length > 160
+    )) {
+      throw new Error("native-agent MCP --agent-title requires an answer-only binding");
+    }
   } else if (!tasksTarget && (Object.hasOwn(flags, "agent-id")
     || Object.hasOwn(flags, "scope-param")
     || Object.hasOwn(flags, "policy-fingerprint")
+    || Object.hasOwn(flags, "agent-title")
     || Object.hasOwn(flags, "recovery-only")
     || Object.hasOwn(flags, "answer-only"))) {
     throw new Error("native-agent binding flags require `--target native-agent`");
@@ -400,7 +478,6 @@ export async function cmdMcp(argv = []) {
         ? "recovery"
         : (flags["answer-only"] === true ? "answer" : "durable"),
     });
-    telemetry("local_server_started");
     return runNativeAgentMcpServer({
       transport: new NativeAgentCompositeTransport({
         tenantId,
@@ -415,6 +492,12 @@ export async function cmdMcp(argv = []) {
         ? "recovery"
         : (flags["answer-only"] === true ? "answer" : "durable"),
       telemetry,
+      ...(flags["agent-title"] ? {
+        answerToolDescription: [
+          `Ask the managed agent ${JSON.stringify(flags["agent-title"])} (${flags["agent-id"]}) exactly once through this fixed binding.`,
+          `On success, present the returned finalText verbatim and explicitly attribute it to managed agent ${JSON.stringify(flags["agent-title"])}; do not spawn a relay subagent.`,
+        ].join(" "),
+      } : {}),
     });
   }
   const endpoint = tasksTarget ? null : `${gatewayUrl}/mcp`;

package/src/commands/native.js

@@ -0,0 +1,285 @@
+import crypto from "node:crypto";
+
+import { parseFlags } from "../args.js";
+import {
+  agentProfileRoot,
+  managedClaudeAnswerBindings,
+  resolveManagedClaudeAnswerBinding,
+} from "../agents.js";
+import {
+  loadConfig,
+  redactSecretText,
+  resolveDefaultGateway,
+} from "../config.js";
+import { extractAnswerFinalText } from "../directAnswer.js";
+import { createNativeAgentTelemetry } from "../nativeAgentTelemetry.js";
+import {
+  MANAGED_NATIVE_INTERCEPT_FLAG,
+  nativeInterceptTimeoutMs,
+} from "../nativeInterception.js";
+import {
+  NATIVE_AGENT_CONTINUATION_SCHEMA,
+  NATIVE_AGENT_HANDLE_SCHEMA,
+  NATIVE_AGENT_RESULT_SCHEMA,
+  NativeAgentCompositeTransport,
+} from "../nativeAgentTransport.js";
+import { normalizeTenantId, tenantCredential } from "../tenants.js";
+import { readHookInput } from "../sessionCollector.js";
+
+const ANSWER_SPEC = {
+  tenant: { type: "string" },
+  agent: { type: "string" },
+  prompt: { type: "string" },
+  json: { type: "boolean" },
+};
+const INTERCEPT_SPEC = {
+  tenant: { type: "string" },
+  [MANAGED_NATIVE_INTERCEPT_FLAG]: { type: "boolean" },
+};
+
+function abortError() {
+  const error = new Error("native-agent answer timed out or was cancelled");
+  error.name = "AbortError";
+  return error;
+}
+
+function throwIfAborted(signal) {
+  if (signal?.aborted) throw abortError();
+}
+
+function terminalAnswer(value) {
+  const direct = extractAnswerFinalText(value);
+  if (direct !== null) {
+    return { ok: true, finalText: direct, ...(value.runId ? { runId: value.runId } : {}) };
+  }
+  if (value?.schema === NATIVE_AGENT_RESULT_SCHEMA) {
+    if (value.status === "succeeded" && typeof value.finalText === "string") {
+      return { ok: true, finalText: value.finalText, ...(value.runId ? { runId: value.runId } : {}) };
+    }
+    return {
+      ok: false,
+      finalText: typeof value.output === "string" ? value.output : "",
+      ...(value.runId ? { runId: value.runId } : {}),
+      error: redactSecretText(
+        typeof value.error === "string"
+          ? value.error
+          : value.error?.message || "managed agent answer failed",
+      ),
+    };
+  }
+  return null;
+}
+
+/**
+ * Execute the same fixed-binding, idempotent transport used by the managed
+ * MCP adapter, including continuation/resume handling and telemetry.
+ */
+export async function answerManagedNativeAgent({
+  tenantId,
+  agent,
+  prompt,
+  signal,
+}, {
+  config = loadConfig(),
+  gatewayUrl = null,
+  createTransport = (options) => new NativeAgentCompositeTransport(options),
+  createTelemetry = createNativeAgentTelemetry,
+} = {}) {
+  if (!config?.pat) {
+    throw new Error("not authenticated; run `impel setup` (or `impel auth`) first");
+  }
+  if (!agent || typeof agent !== "object") throw new Error("managed agent binding is invalid");
+  if (typeof prompt !== "string" || !prompt.trim() || prompt.length > 40_000) {
+    throw new Error("--prompt must contain between 1 and 40000 characters");
+  }
+  const normalizedTenant = normalizeTenantId(tenantId);
+  const telemetry = createTelemetry({
+    tenantId: normalizedTenant,
+    agentId: agent.agentId,
+    scopeParam: agent.scopeParam,
+    mode: "answer",
+  });
+  const transport = createTransport({
+    tenantId: normalizedTenant,
+    agentId: agent.agentId,
+    scopeParam: agent.scopeParam,
+    policyFingerprint: agent.policyFingerprint,
+    gatewayUrl: gatewayUrl || config.gatewayUrl || resolveDefaultGateway(),
+    credential: tenantCredential(config.pat, normalizedTenant),
+    telemetry,
+  });
+  const correlationId = crypto.randomUUID();
+  const startedAt = Date.now();
+  telemetry("local_tool_received", { correlationId, tool: "answer_native_agent" });
+  try {
+    throwIfAborted(signal);
+    let value = await transport.answer({ question: prompt, contextKeys: [] }, { signal });
+    for (;;) {
+      throwIfAborted(signal);
+      const terminal = terminalAnswer(value);
+      if (terminal) {
+        telemetry("local_tool_completed", {
+          correlationId,
+          tool: "answer_native_agent",
+          outcome: terminal.ok ? "succeeded" : "failed",
+          durationMs: Date.now() - startedAt,
+          durableRunCreated: Boolean(terminal.runId),
+        });
+        return terminal;
+      }
+      if (![NATIVE_AGENT_CONTINUATION_SCHEMA, NATIVE_AGENT_HANDLE_SCHEMA].includes(value?.schema)) {
+        throw new Error("managed agent answer returned an invalid transport result");
+      }
+      value = await transport.resume({ handle: value }, { signal });
+    }
+  } catch (error) {
+    telemetry("local_tool_completed", {
+      correlationId,
+      tool: "answer_native_agent",
+      outcome: error?.name === "AbortError" ? "cancelled" : "failed",
+      durationMs: Date.now() - startedAt,
+    });
+    throw error;
+  }
+}
+
+function answerJson(result) {
+  return JSON.stringify({
+    ok: result.ok === true,
+    finalText: typeof result.finalText === "string" ? result.finalText : "",
+    ...(result.runId ? { runId: result.runId } : {}),
+    ...(result.error ? { error: redactSecretText(result.error) } : {}),
+  });
+}
+
+function escapeRegex(value) {
+  return String(value).replace(/[.*+?^${}()|[\]\\]/gu, "\\$&");
+}
+
+export function matchManagedNativeMention(prompt, bindings) {
+  if (typeof prompt !== "string" || !Array.isArray(bindings)) return null;
+  // Reject every prompt containing a second @mention, managed or otherwise.
+  // This keeps implicit/mixed delegation on the model-mediated path.
+  const mentions = prompt.match(/@[a-z0-9][a-z0-9_.:-]*/giu) || [];
+  if (mentions.length !== 1) return null;
+  for (const binding of bindings) {
+    if (!/^[a-z0-9][a-z0-9-]{0,62}$/u.test(binding?.name || "")) continue;
+    const match = new RegExp(`^@${escapeRegex(binding.name)}\\s+([\\s\\S]+)$`, "u").exec(prompt);
+    if (!match || !match[1].trim()) continue;
+    return { binding, task: match[1] };
+  }
+  return null;
+}
+
+export async function cmdNativeIntercept(argv, {
+  environment = process.env,
+  profileRoot = null,
+  readInput = readHookInput,
+  resolveBindings = managedClaudeAnswerBindings,
+  answer = answerManagedNativeAgent,
+  timeoutMs = null,
+  stdout = (line) => process.stdout.write(`${line}\n`),
+} = {}) {
+  try {
+    const { flags, positionals } = parseFlags(argv, INTERCEPT_SPEC);
+    if (positionals.length > 0
+      || Object.keys(flags).some((name) => !Object.hasOwn(INTERCEPT_SPEC, name))
+      || flags[MANAGED_NATIVE_INTERCEPT_FLAG] !== true
+      || typeof flags.tenant !== "string"
+      || !flags.tenant.trim()) {
+      return null;
+    }
+    const tenantId = normalizeTenantId(flags.tenant);
+    const input = await readInput();
+    if (input.hook_event_name !== "UserPromptSubmit") return null;
+    const root = profileRoot || agentProfileRoot("claude", { environment });
+    const matched = matchManagedNativeMention(
+      input.prompt,
+      resolveBindings(root, tenantId),
+    );
+    if (!matched) return null;
+
+    const controller = new AbortController();
+    const hardTimeoutMs = timeoutMs ?? nativeInterceptTimeoutMs(environment);
+    let timeout;
+    const deadline = new Promise((resolve) => {
+      timeout = setTimeout(() => {
+        controller.abort();
+        resolve(null);
+      }, hardTimeoutMs);
+    });
+    let result;
+    try {
+      const answered = Promise.resolve(answer({
+        tenantId,
+        agent: matched.binding,
+        prompt: matched.task,
+        signal: controller.signal,
+      })).catch(() => null);
+      result = await Promise.race([answered, deadline]);
+    } finally {
+      clearTimeout(timeout);
+    }
+    if (!result?.ok || typeof result.finalText !== "string") return null;
+    stdout(JSON.stringify({
+      decision: "block",
+      reason: `Response from managed agent ${JSON.stringify(matched.binding.title)} (${matched.binding.agentId}):\n\n${result.finalText}`,
+      suppressOriginalPrompt: true,
+    }));
+    return result;
+  } catch {
+    // Interception is an optimization only. Invalid input, stale profiles,
+    // transport failures, and timeouts all fall through to Claude unchanged.
+    return null;
+  }
+}
+
+export async function cmdNative(argv, {
+  environment = process.env,
+  profileRoot = null,
+  resolveBinding = resolveManagedClaudeAnswerBinding,
+  answer = answerManagedNativeAgent,
+  stdout = (line) => console.log(line),
+  stderr = (line) => console.error(line),
+} = {}) {
+  const [action, ...rest] = argv;
+  if (action === "intercept") {
+    return cmdNativeIntercept(rest, {
+      environment,
+      profileRoot,
+      stdout,
+    });
+  }
+  if (action !== "answer") {
+    throw new Error("native command expects `answer --tenant <tenant> --agent <id> --prompt <task> [--json]`");
+  }
+  const { flags, positionals } = parseFlags(rest, ANSWER_SPEC);
+  if (positionals.length > 0) throw new Error("native answer does not accept positional arguments");
+  for (const flag of ["tenant", "agent", "prompt"]) {
+    if (typeof flags[flag] !== "string" || !flags[flag].trim()) {
+      throw new Error(`native answer requires --${flag}`);
+    }
+  }
+  const tenantId = normalizeTenantId(flags.tenant);
+  const root = profileRoot || agentProfileRoot("claude", { environment });
+  let binding;
+  try {
+    binding = resolveBinding(root, tenantId, flags.agent);
+    const result = await answer({ tenantId, agent: binding, prompt: flags.prompt });
+    if (flags.json === true) stdout(answerJson(result));
+    else if (result.ok) {
+      stdout(`Response from managed agent ${JSON.stringify(binding.title)} (${binding.agentId}):\n\n${result.finalText}`);
+    } else {
+      stderr(`Managed agent ${JSON.stringify(binding.title)} (${binding.agentId}) failed: ${result.error}`);
+    }
+    if (!result.ok) process.exitCode = 1;
+    return result;
+  } catch (error) {
+    const message = redactSecretText(error?.message || error);
+    const result = { ok: false, finalText: "", error: message };
+    if (flags.json === true) stdout(answerJson(result));
+    else stderr(`Managed agent ${JSON.stringify(binding?.title || flags.agent)} failed: ${message}`);
+    process.exitCode = 1;
+    return result;
+  }
+}

package/src/managedProfileVersion.js

@@ -0,0 +1,4 @@
+// Fleet generation shared by managed-profile writers and upstream clients.
+// Keep this isolated from apps.js so latency-sensitive transports do not load
+// desktop bundle machinery just to identify their managed config contract.
+export const CURRENT_CONFIG_VERSION = 35;

package/src/nativeAgentTelemetry.js

@@ -12,6 +12,7 @@ const SAFE_EVENTS = new Set([
   "local_tool_completed",
   "session_prepared",
   "upstream_request_completed",
+  "hedge_fired",
   "binding_completed",
 ]);
 const SAFE_TOOLS = new Set([
@@ -94,9 +95,12 @@ export function createNativeAgentTelemetry({
       outcome: SAFE_OUTCOMES.has(fields.outcome) ? fields.outcome : undefined,
       status: safeId(fields.status),
       durationMs: safeInteger(fields.durationMs),
+      elapsedMs: safeInteger(fields.elapsedMs),
       pollCount: safeInteger(fields.pollCount),
       handshakeReused: typeof fields.handshakeReused === "boolean" ? fields.handshakeReused : undefined,
       bindingReused: typeof fields.bindingReused === "boolean" ? fields.bindingReused : undefined,
+      prewarmed: typeof fields.prewarmed === "boolean" ? fields.prewarmed : undefined,
+      replayTerminal: typeof fields.replayTerminal === "boolean" ? fields.replayTerminal : undefined,
       durableRunCreated: typeof fields.durableRunCreated === "boolean" ? fields.durableRunCreated : undefined,
     };
     try {