@oneuptime/common 14.0.7 → 14.0.9

package/Server/Types/Markdown.ts

@@ -1,6 +1,7 @@
 import { Renderer, marked } from "marked";
 import CaptureSpan from "../Utils/Telemetry/CaptureSpan";
 import markdownSlugify from "./MarkdownSlugify";
+import SafeHtml from "../../Types/SafeHtml";
 
 export type MarkdownRenderer = Renderer;
 
@@ -50,6 +51,26 @@ const HTML_ENTITIES: Record<string, string> = {
   nbsp: " ",
 };
 
+// The named references getEmailUrl decodes in a link destination.
+const URL_NAMED_CHARACTER_REFERENCES: Record<string, string> = {
+  amp: "&",
+  lt: "<",
+  gt: ">",
+  quot: '"',
+  apos: "'",
+};
+
+/*
+ * The schemes an email may link to, and load an image from. A destination
+ * with no scheme is also allowed (see Markdown.getEmailUrl).
+ */
+export const EMAIL_LINK_SCHEMES: ReadonlyArray<string> = [
+  "http",
+  "https",
+  "mailto",
+];
+export const EMAIL_IMAGE_SCHEMES: ReadonlyArray<string> = ["http", "https"];
+
 type HoldFunction = (value: string) => string;
 
 interface BacktickRuns {
@@ -603,12 +624,93 @@ export default class Markdown {
    * a second implementation is a second thing to get wrong.
    */
   public static escapeHtml(text: string): string {
-    return text
-      .replace(/&/g, "&amp;")
-      .replace(/</g, "&lt;")
-      .replace(/>/g, "&gt;")
-      .replace(/"/g, "&quot;")
-      .replace(/'/g, "&#39;");
+    return SafeHtml.escape(text);
+  }
+
+  /**
+   * The URL a link or image in an EMAIL may point at, ready to go between
+   * the double quotes of an href or src attribute - or null when it may not
+   * be emitted at all.
+   *
+   * An email's Markdown comes from people outside the recipient's control: a
+   * public note, an incident description, a root cause built from telemetry.
+   * marked emits any destination it is given, so `[Details](javascript:...)`
+   * or `(data:text/html;base64,...)` became a live link in a status update
+   * the subscriber trusts. Only the schemes listed are kept; a destination
+   * with no scheme (a relative link or "#anchor") is kept too, as it was
+   * before, and cannot run anything.
+   *
+   * The scheme is judged on exactly the URL the recipient's mail client will
+   * see:
+   * - The character references marked leaves in a destination
+   *   ("&#x6A;avascript:") are decoded first, and the result is percent-
+   *   encoded the way marked does it (encodeURI), which also encodes every
+   *   space and control character a browser would strip out of a scheme.
+   * - The URL is then HTML-escaped into the attribute, so the client's own
+   *   decoding of the attribute gives back exactly the string that was
+   *   checked. A character reference this does not decode ("&colon;")
+   *   therefore reaches the client as literal text, never as a ":".
+   */
+  public static getEmailUrl(
+    href: string | null | undefined,
+    allowedSchemes: ReadonlyArray<string>,
+  ): string | null {
+    if (!href) {
+      return null;
+    }
+
+    let url: string;
+
+    try {
+      url = encodeURI(Markdown.decodeUrlCharacterReferences(href)).replace(
+        /%25/g,
+        "%",
+      );
+    } catch {
+      // A lone surrogate, which encodeURI refuses: no usable URL.
+      return null;
+    }
+
+    const scheme: RegExpMatchArray | null = url.match(
+      /^([a-zA-Z][a-zA-Z0-9+.-]*):/,
+    );
+
+    if (scheme && !allowedSchemes.includes(scheme[1]!.toLowerCase())) {
+      return null;
+    }
+
+    return Markdown.escapeHtml(url);
+  }
+
+  /*
+   * Numeric character references, and the named ones for the characters
+   * escapeHtml writes. Anything else is left as written, and getEmailUrl's
+   * escaping makes it inert.
+   */
+  private static decodeUrlCharacterReferences(text: string): string {
+    return text.replace(
+      /&(#[xX][0-9a-fA-F]+|#[0-9]+|amp|lt|gt|quot|apos);/g,
+      (match: string, reference: string): string => {
+        if (reference.startsWith("#")) {
+          const codePoint: number =
+            reference[1] === "x" || reference[1] === "X"
+              ? parseInt(reference.slice(2), 16)
+              : parseInt(reference.slice(1), 10);
+
+          if (
+            !Number.isFinite(codePoint) ||
+            codePoint <= 0 ||
+            codePoint > 0x10ffff
+          ) {
+            return match;
+          }
+
+          return String.fromCodePoint(codePoint);
+        }
+
+        return URL_NAMED_CHARACTER_REFERENCES[reference] ?? match;
+      },
+    );
   }
 
   /*
@@ -743,6 +845,51 @@ export default class Markdown {
       );
     };
 
+    /*
+     * Links and images keep only http, https and mailto destinations (http
+     * and https for an image), plus relative ones: see getEmailUrl. Any
+     * other link renders as its text alone, and any other image as its alt
+     * text, so the words the author wrote still read in place.
+     *
+     * The markup is marked's own. `text` is the link's rendered inline
+     * content, and `title` and an image's alt text arrive already escaped by
+     * marked's tokenizer, so escaping them again would show "&amp;".
+     */
+    renderer.link = function (
+      href: string,
+      title: string | null | undefined,
+      text: string,
+    ): string {
+      const url: string | null = Markdown.getEmailUrl(href, EMAIL_LINK_SCHEMES);
+
+      if (url === null) {
+        return text;
+      }
+
+      const titleAttribute: string = title ? ` title="${title}"` : "";
+
+      return `<a href="${url}"${titleAttribute}>${text}</a>`;
+    };
+
+    renderer.image = function (
+      href: string,
+      title: string | null,
+      text: string,
+    ): string {
+      const url: string | null = Markdown.getEmailUrl(
+        href,
+        EMAIL_IMAGE_SCHEMES,
+      );
+
+      if (url === null) {
+        return text;
+      }
+
+      const titleAttribute: string = title ? ` title="${title}"` : "";
+
+      return `<img src="${url}" alt="${text}"${titleAttribute}>`;
+    };
+
     this.emailRenderer = renderer;
 
     return renderer;

package/Server/Types/Workflow/Components/Email.ts

@@ -6,9 +6,18 @@ import ComponentID from "../../../../Types/Workflow/ComponentID";
 import Components from "../../../../Types/Workflow/Components/Email";
 import nodemailer, { Transporter } from "nodemailer";
 import SMTPTransport from "nodemailer/lib/smtp-transport";
+import DataSourceEgressGuard, {
+  ResolvedAddress,
+} from "../../../Utils/DataSource/EgressGuard";
+import PinnedSmtpSocket, {
+  SmtpSocketCallback,
+} from "../../../Utils/Mail/PinnedSmtpSocket";
 import CaptureSpan from "../../../Utils/Telemetry/CaptureSpan";
 
 export default class Email extends ComponentCode {
+  // nodemailer's own default connection timeout.
+  private static readonly CONNECTION_TIMEOUT_IN_MS: number = 2 * 60 * 1000;
+
   public constructor() {
     super();
 
@@ -123,10 +132,60 @@ export default class Email extends ComponentCode {
       };
     }
 
+    const smtpHost: string = args["smtp-host"].toString().trim();
+    // "[fd00::25]" is how an IPv6 literal is usually written next to a port.
+    const bareSmtpHost: string = smtpHost.replace(/^\[|\]$/g, "");
+    const smtpPort: number = args["smtp-port"] as number;
+
     try {
+      /*
+       * The SMTP host is free text typed into the workflow node by any
+       * project member who can edit workflows, and nodemailer's failures
+       * ("Invalid greeting. response=<banner>", refused vs timed out) come
+       * back through the Error port into the workflow log. Unchecked, this
+       * step is a port scanner with banner disclosure for whatever network
+       * the workflow worker runs in.
+       *
+       * Same guard and label as a project's own SMTP server in MailService,
+       * so the same policy: loopback, link-local and cloud metadata are
+       * refused everywhere; private ranges are refused on SaaS and allowed on
+       * self-hosted installs unless DATA_SOURCE_BLOCK_PRIVATE_ADDRESSES=true.
+       * A refusal is thrown inside this try, so it takes the Error port like
+       * any other failure to send, before a socket is opened.
+       */
+      const validatedAddresses: Array<ResolvedAddress> =
+        await DataSourceEgressGuard.assertHostnameAllowed(bareSmtpHost, {
+          targetLabel: "SMTP server",
+        });
+
       const smtpTransport: SMTPTransport.Options = {
-        host: args["smtp-host"]?.toString(),
-        port: args["smtp-port"] as number,
+        /*
+         * nodemailer still needs the name the user typed: it is what TLS
+         * sends as SNI and checks the certificate against, on implicit TLS
+         * and on the STARTTLS upgrade alike. It is never dialed; see
+         * getSocket.
+         */
+        host: bareSmtpHost,
+        port: smtpPort,
+        /*
+         * Connect here, to the addresses just validated, and hand nodemailer
+         * the open socket. Given the name instead, nodemailer resolves it
+         * again on its own (dns.resolve4/6, then a process-wide five-minute
+         * cache), so a DNS answer that changed after the check would choose
+         * the address actually connected to.
+         */
+        getSocket: (
+          _options: SMTPTransport.Options,
+          callback: SmtpSocketCallback,
+        ): void => {
+          PinnedSmtpSocket.connect({
+            host: bareSmtpHost,
+            port: smtpPort,
+            addresses: validatedAddresses,
+            timeoutInMs: Email.CONNECTION_TIMEOUT_IN_MS,
+            onDone: callback,
+          });
+        },
       };
 
       if (

package/Server/Utils/AI/ClusterAccess/ClusterAccessContext.ts

@@ -2,6 +2,7 @@ import {
   KubernetesAiAccessGap,
   KubernetesAiRemediationMode,
   KubernetesClusterAiAccessStatus,
+  getKubernetesAiAccessTargetKind,
 } from "../../../../Types/Kubernetes/KubernetesClusterAiAccess";
 import { KUBECTL_ALWAYS_ASKS_SUMMARY } from "../../../../Types/AutoRemediation/AiRemediationCommandPlan";
 
@@ -20,6 +21,46 @@ function capitalizeFirst(text: string): string {
   return text.charAt(0).toUpperCase() + text.slice(1);
 }
 
+/*
+ * Who runs kubectl for a cluster, by name, for copy the model and humans
+ * read: "the Kubernetes AI agent", or `Runner "<name>"`. Told apart by
+ * runner.kind only — accessMethod is "in_cluster" for both the agent and
+ * the chart's previous in-cluster Runner.
+ */
+export function describeClusterAccessTarget(
+  status: Pick<KubernetesClusterAiAccessStatus, "runner">,
+): string {
+  if (getKubernetesAiAccessTargetKind(status.runner) === "ai_agent") {
+    return "the Kubernetes AI agent";
+  }
+
+  return `Runner "${status.runner?.name || "Runner"}"`;
+}
+
+/*
+ * The same with "its" ("its Kubernetes AI agent", "its Runner"), for copy
+ * that has already named the cluster.
+ */
+export function describeClusterAccessTargetOfCluster(
+  status: Pick<KubernetesClusterAiAccessStatus, "runner">,
+): string {
+  return getKubernetesAiAccessTargetKind(status.runner) === "ai_agent"
+    ? "its Kubernetes AI agent"
+    : "its Runner";
+}
+
+/*
+ * The same as a role, for copy about the cluster in general: "the
+ * cluster's Kubernetes AI agent" or "the cluster's Runner".
+ */
+export function describeClusterAccessTargetRole(
+  status: Pick<KubernetesClusterAiAccessStatus, "runner">,
+): string {
+  return getKubernetesAiAccessTargetKind(status.runner) === "ai_agent"
+    ? "the cluster's Kubernetes AI agent"
+    : "the cluster's Runner";
+}
+
 /*
  * The prompt-side view of cluster access.
  *
@@ -55,7 +96,7 @@ export default class ClusterAccessContext {
           })
           .join(
             ", ",
-          )}. Use run_kubectl for READ-ONLY inspection — kubectl get/describe/events/logs/top/rollout status — the way an on-call engineer would open a terminal: describe the failing pod, read its recent events, check node capacity and pending-pod reasons, tail the crashing container's logs. Prefer direct cluster inspection over guessing from metrics when the two disagree. Every kubectl command that ran is cited like any other tool result; a command that could not run comes back as an error, is not evidence, and must never be described as inspected. The Runner that runs kubectl lives in the cluster and can itself be down: if run_kubectl says a cluster's Runner did not pick up a command, that cluster is unreachable for the rest of this investigation — do not call run_kubectl on it again, continue with OneUptime telemetry, and say so in your report. Reading Secrets is refused and credential-looking values (Secret data, passwords, tokens, keys) are redacted from every output before you see it — never ask for them and never treat a redaction marker as a finding.`,
+          )}. Use run_kubectl for READ-ONLY inspection — kubectl get/describe/events/logs/top/rollout status — the way an on-call engineer would open a terminal: describe the failing pod, read its recent events, check node capacity and pending-pod reasons, tail the crashing container's logs. Prefer direct cluster inspection over guessing from metrics when the two disagree. Every kubectl command that ran is cited like any other tool result; a command that could not run comes back as an error, is not evidence, and must never be described as inspected. The agent (or Runner) that runs kubectl lives in the cluster and can itself be down: if run_kubectl says a cluster's agent or Runner did not pick up a command, that cluster is unreachable for the rest of this investigation — do not call run_kubectl on it again, continue with OneUptime telemetry, and say so in your report. Reading Secrets is refused and credential-looking values (Secret data, passwords, tokens, keys) are redacted from every output before you see it — never ask for them and never treat a redaction marker as a finding.`,
       );
     }
 
@@ -78,7 +119,7 @@ export default class ClusterAccessContext {
     }
 
     lines.push(
-      `Add a section **${ClusterAccessContext.REPORT_SECTION_HEADING}** before Suggested next steps: one or two sentences on what you inspected directly on the cluster (or that you could not — access not set up, or the cluster's Runner not responding — and that the human should check the cluster's AI page).`,
+      `Add a section **${ClusterAccessContext.REPORT_SECTION_HEADING}** before Suggested next steps: one or two sentences on what you inspected directly on the cluster (or that you could not — access not set up, or the cluster's AI agent or Runner not responding — and that the human should check the cluster's AI agent page (AI → Agent)).`,
     );
 
     return lines.join("\n");
@@ -97,13 +138,9 @@ export default class ClusterAccessContext {
     for (const status of statuses) {
       if (status.isInvestigationReady) {
         lines.push(
-          `- Cluster "${status.clusterName}" (clusterId: ${status.clusterId}): kubectl READ access available via run_kubectl${
-            status.accessMethod === "in_cluster"
-              ? " (in-cluster Runner)"
-              : status.credentialName
-                ? ` (Runner "${status.runner?.name}" with credential "${status.credentialName}")`
-                : ""
-          }. Remediation: ${ClusterAccessContext.describeRemediationMode(status)}.`,
+          `- Cluster "${status.clusterName}" (clusterId: ${status.clusterId}): kubectl READ access available via run_kubectl${ClusterAccessContext.describeAccessPath(
+            status,
+          )}. Remediation: ${ClusterAccessContext.describeRemediationMode(status)}.`,
         );
         continue;
       }
@@ -126,6 +163,27 @@ export default class ClusterAccessContext {
     return lines.join("\n");
   }
 
+  /*
+   * How kubectl reaches a ready cluster, as a parenthetical: the Kubernetes
+   * AI agent, the chart's previous in-cluster Runner, or a Runner with a
+   * credential.
+   */
+  private static describeAccessPath(
+    status: KubernetesClusterAiAccessStatus,
+  ): string {
+    if (getKubernetesAiAccessTargetKind(status.runner) === "ai_agent") {
+      return " (via the in-cluster Kubernetes AI agent)";
+    }
+
+    if (status.accessMethod === "in_cluster") {
+      return " (in-cluster Runner)";
+    }
+
+    return status.credentialName
+      ? ` (Runner "${status.runner?.name}" with credential "${status.credentialName}")`
+      : "";
+  }
+
   /*
    * The sentence the investigation panel shows humans when AI investigated
    * with OneUptime data only. Deterministic so it reads the same on every

package/Server/Utils/AI/ClusterAccess/KubectlInvestigationToolkit.ts

@@ -7,6 +7,7 @@ import {
   KubernetesClusterAiAccessStatus,
   MAX_KUBECTL_COMMANDS_PER_INVESTIGATION,
   MAX_KUBECTL_TIMEOUT_MS,
+  getKubernetesAiAccessTargetKind,
 } from "../../../../Types/Kubernetes/KubernetesClusterAiAccess";
 import KubectlPolicy, {
   KubectlPolicyResult,
@@ -30,6 +31,11 @@ import {
   LIST_CLUSTER_ACCESS_TOOL_NAME,
   RUN_KUBECTL_TOOL_NAME,
 } from "../../../../Types/Kubernetes/KubernetesClusterAiAccessToolNames";
+import {
+  describeClusterAccessTarget,
+  describeClusterAccessTargetOfCluster,
+  describeClusterAccessTargetRole,
+} from "./ClusterAccessContext";
 
 /*
  * The run-scoped, READ-ONLY kubectl toolkit for an investigation.
@@ -227,8 +233,13 @@ export default class KubectlInvestigationToolkit {
                 : ""
             } — ${
               this.isClusterUnreachable(cluster.clusterId)
-                ? `UNREACHABLE for the rest of this investigation: its Runner "${cluster.runner?.name}" did not pick up an earlier command. Do not call run_kubectl on it again.`
-                : `read-only kubectl via Runner "${cluster.runner?.name}"`
+                ? `UNREACHABLE for the rest of this investigation: its ${describeClusterAccessTarget(
+                    cluster,
+                  ).replace(
+                    /^the /,
+                    "",
+                  )} did not pick up an earlier command. Do not call run_kubectl on it again.`
+                : `read-only kubectl via ${describeClusterAccessTarget(cluster)}`
             }`;
           })
           .join("\n");
@@ -345,15 +356,20 @@ export default class KubectlInvestigationToolkit {
     );
 
     if (tripped !== undefined) {
+      const target: string = describeClusterAccessTarget(cluster);
+      const role: string = describeClusterAccessTargetRole(cluster);
+
       return this.failure(
-        `Runner "${cluster.runner.name}", which serves cluster "${cluster.clusterName}", did not pick up an earlier command${
+        `${target.charAt(0).toUpperCase()}${target.slice(1)}, which serves cluster "${cluster.clusterName}", did not pick up an earlier command${
           tripped.clusterName !== cluster.clusterName
             ? ` (for cluster "${tripped.clusterName}")`
             : ""
         } within ${KubectlInvestigationToolkit.describeSeconds(
           tripped.claimWindowMs,
-        )}, so the cluster is treated as unreachable for the rest of this investigation. Nothing was run. Do not call run_kubectl on this cluster again: continue with OneUptime telemetry and say in **Cluster access** that the cluster's Runner did not respond.`,
-        `kubectl was not run on cluster "${cluster.clusterName}": its Runner did not pick up an earlier command, so the cluster was unreachable for the rest of this investigation.`,
+        )}, so the cluster is treated as unreachable for the rest of this investigation. Nothing was run. Do not call run_kubectl on this cluster again: continue with OneUptime telemetry and say in **Cluster access** that ${role} did not respond.`,
+        `kubectl was not run on cluster "${cluster.clusterName}": ${describeClusterAccessTargetOfCluster(
+          cluster,
+        )} did not pick up an earlier command, so the cluster was unreachable for the rest of this investigation.`,
       );
     }
 
@@ -427,8 +443,12 @@ export default class KubectlInvestigationToolkit {
       const alsoUnreachable: Array<KubernetesClusterAiAccessStatus> =
         this.getOtherClustersOnRunner(cluster);
 
+      const role: string = describeClusterAccessTargetRole(cluster);
+
       return this.failure(
-        `kubectl was NOT run on cluster "${cluster.clusterName}": its Runner did not pick up "${outcome.displayCommand}" within ${KubectlInvestigationToolkit.describeSeconds(
+        `kubectl was NOT run on cluster "${cluster.clusterName}": ${describeClusterAccessTargetOfCluster(
+          cluster,
+        )} did not pick up "${outcome.displayCommand}" within ${KubectlInvestigationToolkit.describeSeconds(
           budget.plan.claimTimeoutInMs,
         )} (it may be offline, restarting or busy). The cluster is treated as unreachable for the rest of this investigation — do not call run_kubectl on it again.${
           alsoUnreachable.length > 0
@@ -440,8 +460,10 @@ export default class KubectlInvestigationToolkit {
                   ", ",
                 )}, so ${alsoUnreachable.length === 1 ? "that cluster is" : "those clusters are"} unreachable too.`
             : ""
-        } Continue with OneUptime telemetry and say in **Cluster access** that the cluster's Runner did not respond.`,
-        `kubectl was not run on cluster "${cluster.clusterName}": its Runner did not pick up the command in time.`,
+        } Continue with OneUptime telemetry and say in **Cluster access** that ${role} did not respond.`,
+        `kubectl was not run on cluster "${cluster.clusterName}": ${describeClusterAccessTargetOfCluster(
+          cluster,
+        )} did not pick up the command in time.`,
       );
     }
 
@@ -460,9 +482,16 @@ export default class KubectlInvestigationToolkit {
         ? redactedReason
         : `${redactedReason}.`;
 
+      const isAgent: boolean =
+        getKubernetesAiAccessTargetKind(cluster.runner) === "ai_agent";
+
       return this.failure(
-        `No kubectl result came back from cluster "${cluster.clusterName}" for "${outcome.displayCommand}": ${reason} Nothing from this command is evidence. Continue with OneUptime telemetry and mention in **Cluster access** that the cluster's Runner stopped responding.`,
-        `${KUBECTL_RESULT_UNKNOWN_EVENT_PREFIX} the Runner of cluster "${cluster.clusterName}" took the command, but no result came back, so whether it ran is unknown.`,
+        `No kubectl result came back from cluster "${cluster.clusterName}" for "${outcome.displayCommand}": ${reason} Nothing from this command is evidence. Continue with OneUptime telemetry and mention in **Cluster access** that ${describeClusterAccessTargetRole(
+          cluster,
+        )} stopped responding.`,
+        `${KUBECTL_RESULT_UNKNOWN_EVENT_PREFIX} the ${
+          isAgent ? "Kubernetes AI agent" : "Runner"
+        } of cluster "${cluster.clusterName}" took the command, but no result came back, so whether it ran is unknown.`,
       );
     }
 

package/Server/Utils/AI/ClusterAccess/KubectlJobRunner.ts

@@ -392,6 +392,9 @@ export default class KubectlJobRunner {
                   wasClaimed: claimState.wasClaimed,
                   claimTimeoutInMs: data.claimTimeoutInMs,
                   executionTimeoutInMs: data.executionTimeoutInMs,
+                  isForKubernetesAiAgent: Boolean(
+                    job.targetKubernetesAiAgentId,
+                  ),
                 })
               : terminalJob.errorMessage ||
                   `Command ended with status ${terminalJob.status}.`,
@@ -612,18 +615,26 @@ export default class KubectlJobRunner {
     wasClaimed: boolean | undefined;
     claimTimeoutInMs: number;
     executionTimeoutInMs: number;
+    // The job was for the cluster's Kubernetes AI agent, not a Runner.
+    isForKubernetesAiAgent?: boolean | undefined;
   }): string {
+    const executor: string = data.isForKubernetesAiAgent
+      ? "Kubernetes AI agent"
+      : "Runner";
+
     if (data.wasClaimed === false) {
-      return `The cluster's Runner did not pick up this kubectl command within ${KubectlJobRunner.describeSeconds(
+      return `The cluster's ${executor} did not pick up this kubectl command within ${KubectlJobRunner.describeSeconds(
         data.claimTimeoutInMs,
       )} — it may be offline, restarting or busy with other work. Nothing was run on the cluster.`;
     }
 
     if (data.wasClaimed === undefined) {
-      return "No result came back for this kubectl command in time, and whether a Runner picked it up could not be read. What the command did is unknown.";
+      return `No result came back for this kubectl command in time, and whether ${
+        data.isForKubernetesAiAgent ? "the Kubernetes AI agent" : "a Runner"
+      } picked it up could not be read. What the command did is unknown.`;
     }
 
-    return `The Runner took this kubectl command but did not report a result in time — it stopped responding, or kubectl outlived its ${KubectlJobRunner.describeSeconds(
+    return `The ${executor} took this kubectl command but did not report a result in time — it stopped responding, or kubectl outlived its ${KubectlJobRunner.describeSeconds(
       data.executionTimeoutInMs,
     )} timeout. Whether it ran, and what it did, is unknown.`;
   }

package/Server/Utils/AI/Remediation/RemediationCommandTools.ts

@@ -38,6 +38,7 @@ import {
   KubernetesRunnerPosture,
   isKubernetesAgentRunnerName,
   isKubernetesAgentRunnerPosture,
+  getKubernetesAiAccessTargetKind,
   isUnattendedRemediationMode,
   parseKubernetesRunnerPosture,
 } from "../../../../Types/Kubernetes/KubernetesClusterAiAccess";
@@ -82,7 +83,10 @@ import KubectlJobRunner, {
   RedactedKubectlOutput,
 } from "../ClusterAccess/KubectlJobRunner";
 import KubectlOutputRedactor from "../../../../Utils/AiRemediation/KubectlOutputRedactor";
-import { UNATTENDED_ROUND_BECOMES_PROPOSAL_SUMMARY } from "../ClusterAccess/ClusterAccessContext";
+import {
+  UNATTENDED_ROUND_BECOMES_PROPOSAL_SUMMARY,
+  describeClusterAccessTarget,
+} from "../ClusterAccess/ClusterAccessContext";
 import logger from "../../Logger";
 
 /*
@@ -404,7 +408,7 @@ export default class RemediationCommandToolkit {
       definition: {
         name: "list_command_targets",
         description:
-          "List where this remediation may run commands: Runners (Bash runs on the Runner's host; SSH runs on an assigned credential's host) and Kubernetes clusters (Kubectl runs through the cluster's Runner). Call this before composing any command.",
+          "List where this remediation may run commands: Runners (Bash runs on the Runner's host; SSH runs on an assigned credential's host) and Kubernetes clusters (Kubectl runs through the cluster's Kubernetes AI agent or Runner). Call this before composing any command.",
         inputSchema: {
           type: "object",
           properties: {},
@@ -497,7 +501,7 @@ export default class RemediationCommandToolkit {
         kubernetesClusterId: cluster.clusterId,
         name: cluster.clusterName,
         stepTypes: "Kubectl",
-        via: `Runner "${cluster.runner?.name}"${
+        via: `${describeClusterAccessTarget(cluster)}${
           cluster.accessMethod === "in_cluster" ? " (in-cluster)" : ""
         }`,
         /*
@@ -785,7 +789,10 @@ export default class RemediationCommandToolkit {
     return refusal
       ? RemediationCommandToolkit.describeRunnerScopeRefusal({
           refusal,
-          runnerLabel: `the Runner of cluster "${data.cluster.clusterName}"`,
+          runnerLabel:
+            getKubernetesAiAccessTargetKind(data.cluster.runner) === "ai_agent"
+              ? `the Kubernetes AI agent of cluster "${data.cluster.clusterName}"`
+              : `the Runner of cluster "${data.cluster.clusterName}"`,
           settings: RemediationCommandToolkit.getRunnerScopeSettings(
             data.cluster,
           ),
@@ -794,14 +801,29 @@ export default class RemediationCommandToolkit {
   }
 
   /*
-   * Where the bound Runner's write scope is set, for a refusal to name: the
-   * Kubernetes agent chart's values for the agent's in-cluster Runner (by
-   * its server-owned name, or its posture), the Runner's own environment
-   * for any other — a credential Runner, which no chart configures.
+   * Where the target's write scope is set, for a refusal to name — three
+   * ways, by who runs kubectl for the cluster:
+   *
+   * - the Kubernetes AI agent (runner.kind "ai_agent"): the chart's
+   *   aiAgent.remediation.* values;
+   * - the chart's previous in-cluster Runner (by its server-owned name, or
+   *   its posture): its values are aiAccess.remediation.*, and changing
+   *   them now means upgrading the chart to the AI agent, which replaces it;
+   * - any other Runner — a credential Runner, which no chart configures:
+   *   its own environment.
    */
-  private static getRunnerScopeSettings(
-    cluster: KubernetesClusterAiAccessStatus,
+  public static getRunnerScopeSettings(
+    cluster: Pick<KubernetesClusterAiAccessStatus, "runner">,
   ): { namespaces: string; nodeOperations: string } {
+    if (getKubernetesAiAccessTargetKind(cluster.runner) === "ai_agent") {
+      return {
+        namespaces:
+          "aiAgent.remediation.namespaces on the Kubernetes agent chart",
+        nodeOperations:
+          "aiAgent.remediation.nodeOperations=false on the Kubernetes agent chart",
+      };
+    }
+
     const isAgentRunner: boolean =
       isKubernetesAgentRunnerName(cluster.runner?.name) ||
       isKubernetesAgentRunnerPosture(cluster.runner?.posture);
@@ -809,9 +831,9 @@ export default class RemediationCommandToolkit {
     if (isAgentRunner) {
       return {
         namespaces:
-          "aiAccess.remediation.namespaces on the Kubernetes agent chart",
+          "aiAccess.remediation.namespaces on the Kubernetes agent chart; after upgrading to the Kubernetes AI agent, aiAgent.remediation.namespaces",
         nodeOperations:
-          "aiAccess.remediation.nodeOperations=false on the Kubernetes agent chart",
+          "aiAccess.remediation.nodeOperations=false on the Kubernetes agent chart; after upgrading to the Kubernetes AI agent, aiAgent.remediation.nodeOperations",
       };
     }
 
@@ -1783,7 +1805,7 @@ export default class RemediationCommandToolkit {
       return {
         text: `Cluster "${status.clusterName}" no longer allows AI remediation${
           gap ? ` (${gap.title})` : ""
-        } — its AI page changed during this run. ${stopText}`,
+        } — its AI agent page changed during this run. ${stopText}`,
       };
     }
 
@@ -1794,7 +1816,7 @@ export default class RemediationCommandToolkit {
     ) {
       this.revokeCluster(clusterId);
       return {
-        text: `Cluster "${status.clusterName}" was re-bound to a different Runner or credential during this run. ${stopText}`,
+        text: `Cluster "${status.clusterName}" was re-bound to a different Runner or credential during this run (or its Kubernetes AI agent took over from its Runner). ${stopText}`,
       };
     }
 
@@ -2001,7 +2023,7 @@ export default class RemediationCommandToolkit {
     return {
       definition: {
         name: "propose_remediation_commands",
-        description: `Propose an ordered plan of at most ${MAX_PLAN_COMMANDS} remediation commands for one-click human approval. Nothing executes until a human approves the whole plan. Call this at most once with your final plan (a later call replaces the earlier one). Provide a rollbackCommand for every state-changing command that has an undo (for Kubectl, e.g. kubectl rollout undo deployment/<name> -n <namespace>). Kubectl commands run through the cluster's Runner, and a write outside its writeScope (list_command_targets) is refused; ${KUBECTL_NEVER_RUNS_SUMMARY}.`,
+        description: `Propose an ordered plan of at most ${MAX_PLAN_COMMANDS} remediation commands for one-click human approval. Nothing executes until a human approves the whole plan. Call this at most once with your final plan (a later call replaces the earlier one). Provide a rollbackCommand for every state-changing command that has an undo (for Kubectl, e.g. kubectl rollout undo deployment/<name> -n <namespace>). Kubectl commands run through the cluster's Kubernetes AI agent or Runner, and a write outside its writeScope (list_command_targets) is refused; ${KUBECTL_NEVER_RUNS_SUMMARY}.`,
         inputSchema: {
           type: "object",
           properties: {