impel-cli 0.20.2 → 0.20.4

package/src/directAnswer.js

@@ -0,0 +1,44 @@
+import { VERBATIM_FINAL_TEXT_CONSTRAINTS } from "./verbatimRelay.js";
+
+export function usesDirectAnswer(agent) {
+  // Write-capable agents stay on durable start/resume even if a catalog
+  // mistakenly sets directAnswer; Impel's answer_native_agent rejects writers.
+  return agent?.directAnswer === true && agent?.sideEffects !== "writes";
+}
+
+export function extractAnswerFinalText(payload) {
+  if (!payload || typeof payload !== "object" || Array.isArray(payload)) return null;
+  for (const key of ["forUser", "answer"]) {
+    const text = payload[key];
+    if (typeof text === "string" && text.trim()) return text;
+  }
+  return null;
+}
+
+export function claudeAnswerVerbatimCompletionGuidance() {
+  return (
+    `When it succeeds, return forUser if present, otherwise answer, exactly with ${VERBATIM_FINAL_TEXT_CONSTRAINTS}. ` +
+    "When it fails, return the tool error without inventing a replacement result."
+  );
+}
+
+export function claudeAnswerFaithfulCompletionGuidance() {
+  return (
+    "When it succeeds, return forUser if present, otherwise answer, faithfully as the answer. " +
+    "When it fails, return the tool error without inventing a replacement result."
+  );
+}
+
+export function adapterAnswerVerbatimCompletionGuidance() {
+  return (
+    `Return forUser if present, otherwise answer, verbatim with ${VERBATIM_FINAL_TEXT_CONSTRAINTS}. ` +
+    "Return tool failures without inventing a replacement result."
+  );
+}
+
+export function adapterAnswerFaithfulCompletionGuidance() {
+  return (
+    "Return forUser if present, otherwise answer, faithfully as the answer. " +
+    "Return tool failures without inventing a replacement result."
+  );
+}

package/src/nativeAgentTransport.js

@@ -9,19 +9,27 @@ import {
   redactSecretText,
 } from "./config.js";
 import {
+  NATIVE_AGENT_ANSWER_TOOL,
   NATIVE_AGENT_LIST_TOOL,
   NATIVE_AGENT_READ_TOOL,
   NATIVE_AGENT_RECOVER_TOOL,
   NATIVE_AGENT_RESUME_TOOL,
   NATIVE_AGENT_RUN_TOOL,
   NATIVE_AGENT_START_TOOL,
+  NATIVE_AGENT_UPSTREAM_ANSWER_TOOL,
   nativeAgentPolicyFingerprint,
   normalizeNativeAgentCatalog,
 } from "./agents.js";
+import { extractAnswerFinalText } from "./directAnswer.js";
 import { normalizeTenantId } from "./tenants.js";
 import { renameWithWindowsRetry } from "./windowsFs.js";
 
-export { NATIVE_AGENT_RECOVER_TOOL, NATIVE_AGENT_RESUME_TOOL, NATIVE_AGENT_RUN_TOOL };
+export {
+  NATIVE_AGENT_ANSWER_TOOL,
+  NATIVE_AGENT_RECOVER_TOOL,
+  NATIVE_AGENT_RESUME_TOOL,
+  NATIVE_AGENT_RUN_TOOL,
+};
 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";
@@ -1543,6 +1551,28 @@ export class NativeAgentCompositeTransport {
   normalizeRunArguments(args, agent) {
     exactObject(args, ["task", "context", "contextKeys"], "run_native_agent arguments");
     const task = boundedString(args.task, "task", 40_000);
+    const context = this.normalizeContextArguments(args, agent);
+    return {
+      agentId: this.agentId,
+      scopeParam: this.scopeParam,
+      task,
+      ...context,
+      ...(agent.sideEffects === "writes" ? { confirmedSideEffects: true } : {}),
+    };
+  }
+
+  normalizeAnswerArguments(args, agent) {
+    exactObject(args, ["question", "task", "context", "contextKeys"], "answer_native_agent arguments");
+    const supplied = ["question", "task"].filter((key) => Object.hasOwn(args, key));
+    if (supplied.length !== 1) {
+      throw new Error("answer_native_agent requires exactly one of question or task");
+    }
+    const question = boundedString(args[supplied[0]], supplied[0], 40_000);
+    const context = this.normalizeContextArguments(args, agent);
+    return { agentId: this.agentId, scopeParam: this.scopeParam, question, ...context };
+  }
+
+  normalizeContextArguments(args, agent) {
     const keys = contextKeys(args.contextKeys);
     const missing = agent.requiredContext.filter((key) => !keys.includes(key));
     if (missing.length) throw new Error(`missing required context: ${missing.join(", ")}`);
@@ -1551,12 +1581,37 @@ export class NativeAgentCompositeTransport {
       throw new Error("nonblank context is required for this native agent");
     }
     return {
-      agentId: this.agentId,
-      scopeParam: this.scopeParam,
-      task,
       ...(args.context !== undefined ? { context: args.context } : {}),
       contextKeys: keys,
-      ...(agent.sideEffects === "writes" ? { confirmedSideEffects: true } : {}),
+    };
+  }
+
+  async answer(args, { signal } = {}) {
+    throwIfAborted(signal);
+    const prepared = await this.prepareNewSession(signal);
+    if (prepared.agent.directAnswer !== true) {
+      throw new Error("native-agent binding is not configured for direct answers");
+    }
+    if (prepared.agent.sideEffects === "writes") {
+      throw new Error(
+        "write-capable native agents must use start/resume instead of answer_native_agent",
+      );
+    }
+    const payload = await prepared.session.call(
+      NATIVE_AGENT_UPSTREAM_ANSWER_TOOL,
+      this.normalizeAnswerArguments(args, prepared.agent),
+    );
+    const finalText = extractAnswerFinalText(payload);
+    if (finalText === null) throw new Error("native-agent answer returned no forUser or answer");
+    return {
+      ...(typeof payload.forUser === "string" && payload.forUser.trim()
+        ? { forUser: payload.forUser }
+        : {}),
+      ...(typeof payload.answer === "string" && payload.answer.trim()
+        ? { answer: payload.answer }
+        : {}),
+      agentId: this.agentId,
+      scopeParam: this.scopeParam,
     };
   }
 
@@ -1923,7 +1978,33 @@ const HANDLE_SCHEMA = {
   },
 };
 
-export function nativeAgentCompositeTools({ recoveryOnly = false } = {}) {
+export function nativeAgentCompositeTools({ mode = "durable" } = {}) {
+  if (!["durable", "recovery", "answer"].includes(mode)) throw new Error("invalid native-agent MCP mode");
+  if (mode === "answer") {
+    return [{
+      name: NATIVE_AGENT_ANSWER_TOOL,
+      description: "Answer once through the direct-answer native agent fixed by this MCP server.",
+      inputSchema: {
+        type: "object",
+        additionalProperties: false,
+        anyOf: [
+          { required: ["question"], not: { required: ["task"] } },
+          { required: ["task"], not: { required: ["question"] } },
+        ],
+        properties: {
+          question: { type: "string", minLength: 1, maxLength: 40_000 },
+          task: { type: "string", minLength: 1, maxLength: 40_000 },
+          context: { type: "string", maxLength: 40_000 },
+          contextKeys: {
+            type: "array",
+            maxItems: 30,
+            uniqueItems: true,
+            items: { type: "string", minLength: 1, maxLength: 160 },
+          },
+        },
+      },
+    }];
+  }
   const tools = [
     {
       name: NATIVE_AGENT_RUN_TOOL,
@@ -1964,10 +2045,17 @@ export function nativeAgentCompositeTools({ recoveryOnly = false } = {}) {
       },
     },
   ];
-  return recoveryOnly ? tools.filter(({ name }) => name !== NATIVE_AGENT_RUN_TOOL) : tools;
+  return mode === "recovery" ? tools.filter(({ name }) => name !== NATIVE_AGENT_RUN_TOOL) : tools;
 }
 
 export function nativeAgentToolCallResult(value) {
+  const answerText = extractAnswerFinalText(value);
+  if (answerText !== null) {
+    return {
+      content: [{ type: "text", text: answerText }],
+      structuredContent: value,
+    };
+  }
   if (value?.schema === NATIVE_AGENT_RESULT_SCHEMA && value.status === "succeeded") {
     return {
       content: [{ type: "text", text: value.finalText }],

package/src/remote/aws.js

@@ -1,5 +1,9 @@
 import { runCapture, runInteractive, sleep } from "./process.js";
 
+// LEGACY ONLY: direct end-user AWS/ECS/SSM access exists solely for the
+// explicitly flagged portable-legacy rollback path. New modes use the broker.
+export const LEGACY_DIRECT_AWS_ONLY = true;
+
 function awsPrefix({ region, profile }) {
   return [
     ...(region ? ["--region", region] : []),
@@ -133,6 +137,40 @@ export function startSshProxy(context, state, port) {
   ], { allowFailure: true });
 }
 
+export function startBrokerSshProxy(connection) {
+  if (connection?.transport !== "aws-ssm-start-session") {
+    throw new Error(`unsupported broker connection transport ${JSON.stringify(connection?.transport || null)}`);
+  }
+  const payload = connection.payload;
+  if (
+    !payload || typeof payload !== "object"
+    || typeof payload.sessionId !== "string" || !payload.sessionId
+    || typeof payload.streamUrl !== "string" || !payload.streamUrl.startsWith("wss://")
+    || typeof payload.tokenValue !== "string" || !payload.tokenValue
+    || typeof payload.target !== "string" || !payload.target
+    || typeof payload.documentName !== "string" || !payload.documentName
+    || !payload.parameters || typeof payload.parameters !== "object"
+    || typeof payload.region !== "string" || !payload.region
+  ) throw new Error("broker returned an invalid AWS SSM connection descriptor");
+  // The plugin receives only this single-use broker lease. `allowFailure`
+  // prevents its token-bearing argv from ever being rendered in an error.
+  return runInteractive(process.env.IMPEL_REMOTE_SESSION_PLUGIN_BIN || "session-manager-plugin", [
+    JSON.stringify({
+      SessionId: payload.sessionId,
+      StreamUrl: payload.streamUrl,
+      TokenValue: payload.tokenValue,
+    }),
+    payload.region,
+    "StartSession",
+    "",
+    JSON.stringify({
+      Target: payload.target,
+      DocumentName: payload.documentName,
+      Parameters: payload.parameters,
+    }),
+  ], { allowFailure: true });
+}
+
 export function awsContext(stateOrOptions) {
   return {
     region: stateOrOptions?.region || stateOrOptions?.aws?.region || "eu-west-2",

package/src/remote/broker.js

@@ -0,0 +1,296 @@
+import crypto from "node:crypto";
+import fs from "node:fs";
+import http from "node:http";
+import https from "node:https";
+
+import { normalizeGatewayUrl, redactSecretText } from "../config.js";
+import { fetchHttp1 } from "../http1.js";
+import { normalizeCapabilityResponse } from "./contracts.js";
+
+const DEFAULT_TIMEOUT_MS = 15_000;
+const MAX_RESPONSE_BYTES = 2 * 1024 * 1024;
+const RUN_ID_RE = /^run_[A-Za-z0-9_-]{8,128}$/u;
+const SESSIONS_UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/u;
+const LOOPBACK_HOSTS = new Set(["127.0.0.1", "[::1]", "localhost"]);
+
+function secureHttpUrl(url) {
+  return url.protocol === "https:" || (url.protocol === "http:" && LOOPBACK_HOSTS.has(url.hostname));
+}
+
+export function isSessionsUUID(value) {
+  return SESSIONS_UUID_RE.test(String(value || ""));
+}
+
+export function uploadTimeoutMs(length, baseTimeout) {
+  const bytes = Number(length);
+  const transferBudget = Number.isFinite(bytes) && bytes > 0 ? Math.ceil(bytes / (256 * 1024)) * 1000 : 0;
+  return Math.min(6 * 60 * 60 * 1000, Math.max(baseTimeout, 120_000, transferBudget + 60_000));
+}
+
+export function newMutationKey(label = "mutation") {
+  const safeLabel = String(label).toLowerCase().replace(/[^a-z0-9_-]+/gu, "-").slice(0, 32) || "mutation";
+  return `impel-remote-${safeLabel}-${crypto.randomBytes(18).toString("hex")}`;
+}
+
+function responseError(status, payload) {
+  const code = typeof payload?.error?.code === "string" ? payload.error.code : `HTTP_${status}`;
+  const message = typeof payload?.error?.message === "string"
+    ? payload.error.message
+    : `broker returned HTTP ${status}`;
+  const error = new Error(`${code}: ${redactSecretText(message)}`);
+  error.code = code;
+  error.status = status;
+  return error;
+}
+
+async function parsedResponse(response) {
+  const text = await response.text();
+  let payload = null;
+  try { payload = text ? JSON.parse(text) : null; } catch { /* Report the HTTP status below. */ }
+  if (!response.ok) throw responseError(response.status, payload);
+  return payload;
+}
+
+function sendFile(urlValue, { method = "PUT", headers = {}, filePath, signal }) {
+  const url = new URL(urlValue);
+  if (!secureHttpUrl(url) || url.username || url.password || url.hash) {
+    throw new Error("workspace upload returned an insecure or malformed URL");
+  }
+  const transport = url.protocol === "https:" ? https : http;
+  const length = fs.statSync(filePath).size;
+  return new Promise((resolve, reject) => {
+    const request = transport.request(url, {
+      method,
+      headers: { ...headers, "content-length": String(length) },
+      signal,
+      ...(url.protocol === "https:" ? { ALPNProtocols: ["http/1.1"] } : {}),
+    }, (response) => {
+      const chunks = [];
+      let size = 0;
+      response.on("data", (chunk) => {
+        size += chunk.length;
+        if (size > MAX_RESPONSE_BYTES) request.destroy(new Error("upload response exceeded 2 MiB"));
+        else chunks.push(chunk);
+      });
+      response.on("error", reject);
+      response.on("end", () => {
+        const body = Buffer.concat(chunks).toString("utf8");
+        resolve({
+          ok: (response.statusCode || 0) >= 200 && (response.statusCode || 0) < 300,
+          status: response.statusCode || 0,
+          async text() { return body; },
+        });
+      });
+    });
+    request.on("error", reject);
+    fs.createReadStream(filePath).on("error", reject).pipe(request);
+  });
+}
+
+function normalizeRun(value) {
+  const run = value?.run || value;
+  if (!run || typeof run !== "object" || !RUN_ID_RE.test(String(run.runId || ""))) {
+    throw new Error("broker returned an invalid remote run");
+  }
+  const state = String(run.state || run.status || "");
+  if (!state) throw new Error("broker returned a remote run without state");
+  return { ...run, runId: String(run.runId), state };
+}
+
+export class RemoteBrokerClient {
+  constructor({ baseUrl, pat, fetchImpl = fetchHttp1, uploadImpl = sendFile, timeoutMs = DEFAULT_TIMEOUT_MS }) {
+    if (!pat) throw new Error("a PAT is required for the remote broker");
+    this.baseUrl = normalizeGatewayUrl(baseUrl);
+    const parsedBase = new URL(this.baseUrl);
+    if (
+      !secureHttpUrl(parsedBase)
+      || parsedBase.username || parsedBase.password || parsedBase.search || parsedBase.hash
+      || parsedBase.pathname !== "/"
+    ) {
+      throw new Error("remote broker URL must be an HTTPS origin (or loopback HTTP for development) without a path, userinfo, query, or fragment");
+    }
+    this.pat = pat;
+    this.fetchImpl = fetchImpl;
+    this.uploadImpl = uploadImpl;
+    this.timeoutMs = timeoutMs;
+  }
+
+  async request(path, { method = "GET", body, headers = {}, idempotencyKey, retry = true } = {}) {
+    const request = async () => {
+      const controller = new AbortController();
+      const timer = setTimeout(() => controller.abort(), this.timeoutMs);
+      try {
+        const response = await this.fetchImpl(new URL(path, this.baseUrl), {
+          method,
+          headers: {
+            accept: "application/json",
+            authorization: `Bearer ${this.pat}`,
+            ...(body === undefined || Buffer.isBuffer(body) ? {} : { "content-type": "application/json" }),
+            ...(Buffer.isBuffer(body) ? { "content-type": "application/octet-stream" } : {}),
+            ...(idempotencyKey ? { "idempotency-key": idempotencyKey } : {}),
+            ...headers,
+          },
+          body: body === undefined ? undefined : Buffer.isBuffer(body) ? body : JSON.stringify(body),
+          signal: controller.signal,
+        });
+        return parsedResponse(response);
+      } finally {
+        clearTimeout(timer);
+      }
+    };
+    try {
+      return await request();
+    } catch (error) {
+      const retryable = retry && idempotencyKey && (error?.name === "AbortError" || !error?.status || error.status >= 500);
+      if (!retryable) throw error;
+      return request();
+    }
+  }
+
+  async capability(expected) {
+    const url = new URL("/v1/remote-capabilities", this.baseUrl);
+    url.searchParams.set("provider", expected.provider);
+    url.searchParams.set("sourceSurface", expected.sourceSurface);
+    url.searchParams.set("requestedMode", expected.mode);
+    const payload = await this.request(`${url.pathname}${url.search}`);
+    return normalizeCapabilityResponse(payload, expected);
+  }
+
+  async createRun(body, idempotencyKey = newMutationKey("create")) {
+    if (!isSessionsUUID(body?.sessionId)) {
+      throw new Error("remote broker create requires a lowercase Sessions UUID");
+    }
+    return normalizeRun(await this.request("/v1/remote-runs", { method: "POST", body, idempotencyKey }));
+  }
+
+  async getRun(runId) {
+    return normalizeRun(await this.request(`/v1/remote-runs/${encodeURIComponent(runId)}`));
+  }
+
+  async cancelRun(runId, body = {}, idempotencyKey = newMutationKey("cancel")) {
+    return normalizeRun(await this.request(`/v1/remote-runs/${encodeURIComponent(runId)}/cancel`, {
+      method: "POST", body, idempotencyKey,
+    }));
+  }
+
+  async stopRun(runId, body = {}, idempotencyKey = newMutationKey("stop")) {
+    return normalizeRun(await this.request(`/v1/remote-runs/${encodeURIComponent(runId)}/stop`, {
+      method: "POST", body, idempotencyKey,
+    }));
+  }
+
+  async handbackRun(runId, idempotencyKey = newMutationKey("handback")) {
+    return normalizeRun(await this.request(`/v1/remote-runs/${encodeURIComponent(runId)}/handback`, {
+      method: "POST", body: {}, idempotencyKey,
+    }));
+  }
+
+  async createConnection(runId, idempotencyKey = newMutationKey("connection")) {
+    const payload = await this.request(`/v1/remote-runs/${encodeURIComponent(runId)}/connections`, {
+      method: "POST", body: {}, idempotencyKey,
+    });
+    if (
+      !payload || typeof payload !== "object"
+      || typeof payload.leaseId !== "string"
+      || typeof payload.transport !== "string"
+      || typeof payload.expiresAt !== "string"
+      || !payload.payload || typeof payload.payload !== "object"
+    ) throw new Error("broker returned an invalid connection lease");
+    return payload;
+  }
+
+  async createViewerLink(runId, idempotencyKey = newMutationKey("viewer-link")) {
+    const payload = await this.request(`/v1/remote-runs/${encodeURIComponent(runId)}/viewer-links`, {
+      method: "POST", body: {}, idempotencyKey, retry: false,
+    });
+    if (
+      !payload || typeof payload !== "object"
+      || typeof payload.fragment !== "string"
+      || !/^exchange=run_[A-Za-z0-9_-]{8,128}\.[A-Za-z0-9_-]{24,256}$/u.test(payload.fragment)
+      || typeof payload.expiresAt !== "string"
+      || !Number.isFinite(Date.parse(payload.expiresAt))
+    ) throw new Error("broker returned an invalid viewer link");
+    const url = new URL(`/runs/${encodeURIComponent(runId)}`, this.baseUrl);
+    url.hash = payload.fragment;
+    return { url: url.toString(), expiresAt: payload.expiresAt };
+  }
+
+  async closeConnection(runId, leaseId, idempotencyKey = newMutationKey("connection-close")) {
+    return normalizeRun(await this.request(`/v1/remote-runs/${encodeURIComponent(runId)}/connections/${encodeURIComponent(leaseId)}/close`, {
+      method: "POST", body: {}, idempotencyKey,
+    }));
+  }
+
+  async uploadWorkspace(runId, artifact, idempotencyKey = newMutationKey("workspace-upload")) {
+    const capability = await this.request(`/v1/remote-runs/${encodeURIComponent(runId)}/workspace-upload`, {
+      method: "POST",
+      idempotencyKey,
+      body: {
+        length: artifact.length,
+        sha256: artifact.sha256,
+        manifestHash: artifact.manifestHash,
+        contentType: "application/vnd.impel.workspace.v1+tar",
+      },
+    });
+    if (
+      !capability || !new Set(["PUT"]).has(capability.method)
+      || typeof capability.url !== "string"
+      || typeof capability.objectKey !== "string"
+      || !capability.headers || typeof capability.headers !== "object"
+    ) throw new Error("broker returned an invalid workspace upload capability");
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), uploadTimeoutMs(artifact.length, this.timeoutMs));
+    try {
+      const response = await this.uploadImpl(capability.url, {
+        method: capability.method,
+        headers: capability.headers,
+        filePath: artifact.path,
+        signal: controller.signal,
+      });
+      if (!response.ok) throw responseError(response.status, null);
+    } finally {
+      clearTimeout(timer);
+    }
+    return normalizeRun(await this.request(`/v1/remote-runs/${encodeURIComponent(runId)}/workspace-complete`, {
+      method: "POST",
+      idempotencyKey: newMutationKey("workspace-complete"),
+      body: {
+        objectKey: capability.objectKey,
+        length: artifact.length,
+        sha256: artifact.sha256,
+        manifestHash: artifact.manifestHash,
+      },
+    }));
+  }
+
+  async uploadProviderCheckpoint(runId, checkpoint, idempotencyKey = newMutationKey("checkpoint")) {
+    const url = new URL(`/v1/remote-runs/${encodeURIComponent(runId)}/provider-checkpoints/input`, this.baseUrl);
+    const upload = () => {
+      const controller = new AbortController();
+      const timer = setTimeout(() => controller.abort(), uploadTimeoutMs(checkpoint.length, this.timeoutMs));
+      return this.uploadImpl(url, {
+        method: "POST",
+        filePath: checkpoint.path,
+        signal: controller.signal,
+        headers: {
+          accept: "application/json",
+          authorization: `Bearer ${this.pat}`,
+          "content-length": String(checkpoint.length),
+          "content-type": "application/vnd.impel.provider-checkpoint.v1+tar",
+          "idempotency-key": idempotencyKey,
+          "x-impel-content-sha256": checkpoint.sha256,
+          "x-impel-manifest-sha256": checkpoint.manifestHash,
+        },
+      }).finally(() => clearTimeout(timer));
+    };
+    let response;
+    try { response = await upload(); }
+    catch { response = await upload(); }
+    if (!response.ok && response.status >= 500) response = await upload();
+    const text = await response.text();
+    let payload = null;
+    try { payload = text ? JSON.parse(text) : null; } catch { /* handled below */ }
+    if (!response.ok) throw responseError(response.status, payload);
+    return normalizeRun(payload);
+  }
+}