@compforge/harness-toolbox 0.3.11 → 0.4.1

package/README.md

@@ -58,6 +58,40 @@ a UID fence; callers needing incarnation guarantees must verify discovery around
 sources borrow Kubernetes access from the root manager and never close it themselves. Unsupported
 commands, missing paths and denied reads fail explicitly; they are not empty file results.
 
+## Kubernetes resources
+
+Borrow a root `KubernetesClient` through `KubernetesEnvironment` and `ClientManager`. Use
+`get(ref)` and `list(query)` for resource reads; `inNamespace(namespace)` binds a borrowed view
+to a namespace without creating a second client or pool:
+
+```ts
+const kube = await clients.get(environment);
+const ns = kube.inNamespace("app");
+const service = await ns.get({ apiVersion: "v1", resource: "services", name: "api" });
+const pods = await ns.list({ apiVersion: "v1", resource: "pods", labelSelector: "app=api" },
+  { timeoutMs: 15_000, signal });
+```
+
+`resource` is the plural REST resource name, not a Kind or kubectl alias. Explicit API versions
+support built-in resources and custom resources without a discovery request or local allowlist.
+The root uses its configured namespace unless the query overrides it; namespace views enforce
+their bound namespace. Resource objects and list metadata are returned intact. List requests
+accept label/field selectors and explicit `limit`/`continue` pages; they do not silently read all pages.
+Errors are `KubernetesError` objects carrying a stable kind and the HTTP status when available.
+Callers retain the query with their evidence; resource operations do not produce shell command results.
+
+The root owns one HTTP transport with keep-alive connections shared across namespaces and resource
+kinds. Authentication refreshes on each request. TLS/proxy identity changes select a new pool and
+retire the previous one after its active reads finish. Requests have bounded bytes and a deadline
+covering queueing, authentication and body consumption. `dispose()` cancels work, waits for tracked
+operations, and closes connections. Views and injected borrowed resource readers have no ownership
+of that lifecycle. No query results are cached and failures are never replayed through another transport.
+
+Native resource access uses kubeconfig authentication, TLS and explicit `proxy-url`. It does not
+select transports based on shell proxy environment variables. `exec` and `forward` are separate
+streaming operations; their implementation does not intercept resource reads. `KubernetesClient`
+has no `run(argv)` method. Concurrency remains caller-configured rather than inferred from pool size.
+
 ## Workload discovery
 
 Borrow a KubernetesClient through KubernetesEnvironment and the shared ClientManager lifecycle, then call
@@ -69,7 +103,23 @@ selectorless Services and failed access raise KubernetesError.
 
 The resource path uses client-node kubeconfig authentication/TLS and bounded native JSON reads,
 not kubectl error text. Configure request timeout, concurrency and response bytes with the
-client's ResourceLimits constructor argument. Existing exec/port-forward operations remain unchanged.
+client's ResourceLimits constructor argument. Native exec uses the same root capacity/byte policy
+with a separate slot pool; its per-call timeout defaults to that policy and covers queueing,
+authentication, upgrade and execution. Explicit per-call timeouts support longer commands.
+
+Exec requires `get pods/exec` permission for the WebSocket upgrade (kubectl/SPDY paths may use
+`create pods/exec`). It connects directly to the Pod exec WebSocket endpoint without a preliminary Pod GET or
+kubectl subprocess. Each command owns a stream session; failures are never retried or replayed.
+Kubeconfig controls authentication, TLS and proxy access. stdout/stderr and remote exit status
+remain separate; retained output and individual messages are bounded. Streaming callers may
+set `collectStdout: false` and enforce their own total byte budget. Root disposal cancels active
+and queued sessions. Protocol v4 is accepted for output-only commands; stdin requires v5 to
+close input without losing remaining output/status. Bun does not expose HTTP upgrade rejection
+status, so those failures retain an unknown connection error. Native exec with a kubeconfig
+proxy requires Node: Bun cannot reliably release proxy sockets or preserve TLS name overrides.
+It fails before opening a session on Bun; use Node or explicitly provide an Executor adapter.
+The transport never bypasses the proxy or TLS checks.
+Port-forward still uses kubectl.
 See [the shared Workload model](../../../docs/workload.md).
 
 ```ts

package/dist/{chunk-8axd2y2m.js → chunk-0s27bgga.js}

@@ -48,7 +48,7 @@ async function resolveWorkload(access, workload, namespace, environment) {
     if (!Object.keys(location.labels).length)
       return failure("Pod labels must be nonempty", "invalid_argument");
     selected = selector(location.labels, true);
-    const result = await access.get(namespace, "pods", undefined, selected);
+    const result = await access.list({ namespace, apiVersion: "v1", resource: "pods", labelSelector: selected });
     if (!Array.isArray(result.items))
       return failure("Pod list lacks items", "invalid_response");
     pods = result.items;
@@ -63,12 +63,17 @@ async function resolveWorkload(access, workload, namespace, environment) {
       return failure("Unsupported workload resource", "unsupported_operation");
     if (!location.name.trim())
       return failure("Resource name is required", "invalid_argument");
-    const item = await access.get(namespace, resource, location.name);
+    const item = await access.get({
+      namespace,
+      resource,
+      name: location.name,
+      apiVersion: resource === "pods" || resource === "services" ? "v1" : "apps/v1"
+    });
     if (resource === "pods")
       pods = [item];
     else {
       selected = selector(item.spec?.selector, resource === "services");
-      const result = await access.get(namespace, "pods", undefined, selected);
+      const result = await access.list({ namespace, apiVersion: "v1", resource: "pods", labelSelector: selected });
       if (!Array.isArray(result.items))
         return failure("Pod list lacks items", "invalid_response");
       pods = result.items;

package/dist/chunk-4ms037k2.js

@@ -0,0 +1,210 @@
+import {
+  resourcePath
+} from "./chunk-ftkrjqkc.js";
+import {
+  clientKey
+} from "./chunk-a9htb6cr.js";
+import {
+  KubernetesError,
+  ToolboxError,
+  kubernetesHttpError
+} from "./chunk-20kv4wc3.js";
+import {
+  ConcurrencyPool
+} from "./chunk-v3hxvnrc.js";
+
+// src/kubernetes/resource-transport.ts
+import { KubeConfig } from "@kubernetes/client-node";
+import fetch from "node-fetch/lib/index.js";
+import { Headers } from "node-fetch";
+class KubernetesResourceTransport {
+  limits;
+  #config = new KubeConfig;
+  #controller = new AbortController;
+  #pool;
+  #agents = new Set;
+  #server;
+  #signal;
+  #current;
+  constructor(options, signal, limits) {
+    this.limits = limits;
+    if (![limits.timeoutMs, limits.concurrency, limits.maxBytes].every((value) => Number.isSafeInteger(value) && value > 0)) {
+      throw new KubernetesError("Resource limits must be positive integers", { kind: "invalid_argument" });
+    }
+    try {
+      if (options.kubeconfig)
+        this.#config.loadFromFile(options.kubeconfig);
+      else
+        this.#config.loadFromDefault();
+      if (options.context)
+        this.#config.setCurrentContext(options.context);
+    } catch (cause) {
+      throw new KubernetesError("Cannot load Kubernetes access configuration", { kind: "connection_failed", cause });
+    }
+    const cluster = this.#config.getCurrentCluster();
+    if (!cluster)
+      throw new KubernetesError("Kubernetes context has no cluster", { kind: "invalid_argument" });
+    this.#server = cluster.server.replace(/\/$/, "");
+    if (new URL(cluster.server).protocol === "http:") {
+      this.#config.clusters = this.#config.clusters.map((item) => item === cluster ? { ...item, skipTLSVerify: true } : item);
+    }
+    this.#signal = AbortSignal.any([signal, this.#controller.signal]);
+    this.#pool = new ConcurrencyPool(limits.concurrency);
+  }
+  async get(ref, options) {
+    if (!ref.name)
+      throw new KubernetesError("Resource name is required", { kind: "invalid_argument" });
+    return this.#read(resourcePath(ref, ref.name), undefined, options);
+  }
+  async list(query, options) {
+    const params = new URLSearchParams;
+    if (query.labelSelector)
+      params.set("labelSelector", query.labelSelector);
+    if (query.fieldSelector)
+      params.set("fieldSelector", query.fieldSelector);
+    if (query.continue)
+      params.set("continue", query.continue);
+    if (query.limit !== undefined) {
+      if (!Number.isSafeInteger(query.limit) || query.limit <= 0) {
+        throw new KubernetesError("Resource page limit must be a positive integer", { kind: "invalid_argument" });
+      }
+      params.set("limit", String(query.limit));
+    }
+    const value = await this.#read(resourcePath(query), params, options);
+    if (!Array.isArray(value.items) || value.items.some((item) => !isObject(item))) {
+      throw new KubernetesError("Resource list lacks object items", { kind: "invalid_response" });
+    }
+    return value;
+  }
+  dispose() {
+    this.#controller.abort(new Error("Kubernetes resource transport disposed"));
+    for (const entry of this.#agents)
+      entry.agent.destroy();
+    this.#agents.clear();
+    this.#current = undefined;
+  }
+  async#read(path, params, options) {
+    const timeoutMs = options?.timeoutMs ?? this.limits.timeoutMs;
+    if (!Number.isSafeInteger(timeoutMs) || timeoutMs <= 0) {
+      throw new KubernetesError("Resource timeout must be a positive integer", { kind: "invalid_argument" });
+    }
+    const caller = options?.signal ? AbortSignal.any([this.#signal, options.signal]) : this.#signal;
+    const deadline = new AbortController;
+    const signal = AbortSignal.any([caller, deadline.signal]);
+    const timer = setTimeout(() => deadline.abort(), Math.min(timeoutMs, this.limits.timeoutMs));
+    try {
+      return await this.#pool.run(async () => {
+        const request = await this.#authenticate(signal);
+        if (signal.aborted) {
+          request.agent.destroy();
+          signal.throwIfAborted();
+        }
+        const entry = this.#acquireAgent(request);
+        try {
+          const url = new URL(this.#server + path);
+          if (params)
+            url.search = params.toString();
+          const headers = new Headers;
+          for (const [name, value2] of Object.entries(request.headers ?? {})) {
+            for (const entry2 of Array.isArray(value2) ? value2 : [value2]) {
+              if (entry2 !== undefined)
+                headers.append(name, String(entry2));
+            }
+          }
+          if (request.auth)
+            headers.set("Authorization", "Basic " + Buffer.from(request.auth).toString("base64"));
+          const response = await fetch(url.href, { agent: entry.agent, headers, signal, size: this.limits.maxBytes });
+          if (!response.ok) {
+            response.body.destroy();
+            const error = kubernetesHttpError(response.status);
+            throw new KubernetesError("Read Kubernetes resource " + path + " failed", { kind: error.kind, code: error.code });
+          }
+          const value = await response.json();
+          signal.throwIfAborted();
+          if (!isObject(value))
+            throw new KubernetesError("Resource response is not an object", { kind: "invalid_response" });
+          return value;
+        } finally {
+          entry.users--;
+          this.#retire(entry);
+        }
+      }, signal);
+    } catch (cause) {
+      if (caller.aborted)
+        throw caller.reason;
+      if (cause instanceof ToolboxError)
+        throw cause;
+      const type = cause && typeof cause === "object" && "type" in cause ? cause.type : undefined;
+      const code = cause && typeof cause === "object" && "code" in cause && typeof cause.code === "string" ? cause.code : undefined;
+      const tls = code !== undefined && [
+        "CERT_HAS_EXPIRED",
+        "DEPTH_ZERO_SELF_SIGNED_CERT",
+        "SELF_SIGNED_CERT_IN_CHAIN",
+        "UNABLE_TO_VERIFY_LEAF_SIGNATURE",
+        "UNABLE_TO_GET_ISSUER_CERT_LOCALLY",
+        "ERR_TLS_CERT_ALTNAME_INVALID"
+      ].includes(code);
+      throw new KubernetesError("Read Kubernetes resource " + path + " failed", {
+        kind: deadline.signal.aborted ? "timeout" : type === "max-size" ? "limit_exceeded" : type === "invalid-json" ? "invalid_response" : tls ? "tls_verification_failed" : code === "ECONNRESET" ? "connection_lost" : "connection_failed",
+        cause,
+        code
+      });
+    } finally {
+      clearTimeout(timer);
+    }
+  }
+  #authenticate(signal) {
+    return new Promise((resolve, reject) => {
+      if (signal.aborted) {
+        reject(signal.reason);
+        return;
+      }
+      const abort = () => reject(signal.reason);
+      signal.addEventListener("abort", abort, { once: true });
+      const options = { headers: {} };
+      this.#config.applyToHTTPSOptions(options).then(() => {
+        signal.removeEventListener("abort", abort);
+        if (signal.aborted) {
+          options.agent.destroy();
+          reject(signal.reason);
+        } else
+          resolve(options);
+      }, (error) => {
+        signal.removeEventListener("abort", abort);
+        reject(error);
+      });
+    });
+  }
+  #acquireAgent(options) {
+    const fresh = options.agent;
+    const cluster = this.#config.getCurrentCluster();
+    const tls = { ...options, agent: undefined, headers: undefined, auth: undefined };
+    const key = clientKey("kubernetes-agent", { server: this.#server, proxy: cluster?.proxyUrl, tls });
+    if (this.#current?.key === key) {
+      fresh.destroy();
+    } else {
+      fresh.keepAlive = true;
+      fresh.maxSockets = this.limits.concurrency;
+      fresh.maxTotalSockets = this.limits.concurrency;
+      fresh.maxFreeSockets = this.limits.concurrency;
+      const previous = this.#current;
+      this.#current = { key, agent: fresh, users: 0 };
+      this.#agents.add(this.#current);
+      if (previous)
+        this.#retire(previous);
+    }
+    this.#current.users++;
+    return this.#current;
+  }
+  #retire(entry) {
+    if (entry !== this.#current && entry.users === 0) {
+      entry.agent.destroy();
+      this.#agents.delete(entry);
+    }
+  }
+}
+function isObject(value) {
+  return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+
+export { KubernetesResourceTransport };

package/dist/{chunk-a1cb44ga.js → chunk-8kts470p.js}

@@ -1,12 +1,15 @@
+import {
+  KubernetesResourceTransport
+} from "./chunk-4ms037k2.js";
 import {
   resolveWorkload
-} from "./chunk-8axd2y2m.js";
+} from "./chunk-0s27bgga.js";
 import {
   ServicePortForwarder
 } from "./chunk-2171tajs.js";
 import {
-  resourceAccess
-} from "./chunk-9n9z2pty.js";
+  KubernetesExecTransport
+} from "./chunk-shsabpc1.js";
 import {
   KubernetesError
 } from "./chunk-20kv4wc3.js";
@@ -24,10 +27,14 @@ class KubernetesClient {
   #forwarders = new Map;
   #operations = new Set;
   #disposal;
+  #exec;
+  #injectedExecutor;
   #resources;
+  #transport;
   constructor(kube, signal, executor, resourceLimits = { timeoutMs: 30000, concurrency: 4, maxBytes: 8 * 1024 * 1024 }, resources) {
     this.kube = kube;
     this.resourceLimits = resourceLimits;
+    this.#injectedExecutor = executor;
     this.signal = signal ? AbortSignal.any([signal, this.#controller.signal]) : this.#controller.signal;
     if (executor)
       this.#executors.set(kube.namespace, executor);
@@ -43,10 +50,12 @@ class KubernetesClient {
         throw new KubernetesError("Workload namespace is required", { kind: "invalid_argument" });
       if (!environment.trim())
         throw new KubernetesError("Environment identity is required", { kind: "invalid_argument" });
-      this.#resources ??= resourceAccess(this.kube, this.signal, this.resourceLimits);
-      return resolveWorkload(this.#resources, workload, namespace, environment);
+      return resolveWorkload(this, workload, namespace, environment);
     });
   }
+  #resourceAccess() {
+    return this.#resources ??= this.#transport = new KubernetesResourceTransport(this.kube, this.signal, this.resourceLimits);
+  }
   #executor(namespace) {
     let executor = this.#executors.get(namespace);
     if (!executor) {
@@ -68,11 +77,22 @@ class KubernetesClient {
   #options(options) {
     return { ...options, signal: options?.signal ? AbortSignal.any([this.signal, options.signal]) : this.signal };
   }
-  run(namespace, command, options) {
-    return this.#track(() => this.#executor(namespace).run(command, this.#options(options)));
+  get(ref, options) {
+    return this.#track(() => this.#resourceAccess().get({ ...ref, namespace: ref.namespace ?? this.kube.namespace }, this.#options(options)));
+  }
+  list(query, options) {
+    return this.#track(() => this.#resourceAccess().list({ ...query, namespace: query.namespace ?? this.kube.namespace }, this.#options(options)));
+  }
+  inNamespace(namespace) {
+    if (!namespace.trim())
+      throw new KubernetesError("Namespace is required", { kind: "invalid_argument" });
+    return {
+      get: (ref, options) => this.get({ ...ref, namespace }, options),
+      list: (query, options) => this.list({ ...query, namespace }, options)
+    };
   }
   exec(namespace, target, command, options) {
-    return this.#track(() => this.#executor(namespace).exec(target, command, this.#options(options)));
+    return this.#track(() => this.#injectedExecutor && namespace === this.kube.namespace ? this.#injectedExecutor.exec(target, command, this.#options(options)) : (this.#exec ??= new KubernetesExecTransport(this.kube, this.signal, this.resourceLimits)).exec(namespace, target, command, this.#options(options)));
   }
   forward(namespace, target) {
     return this.#track(async () => {
@@ -101,6 +121,7 @@ class KubernetesClient {
         forwarder?.stop();
       }));
       this.#forwarders.clear();
+      this.#transport?.dispose();
       const errors = results.flatMap((result) => result.status === "rejected" ? [result.reason] : []);
       if (errors.length)
         throw new AggregateError(errors, "Kubernetes client cleanup failed");

package/dist/chunk-ftkrjqkc.js

@@ -0,0 +1,15 @@
+import {
+  KubernetesError
+} from "./chunk-20kv4wc3.js";
+
+// src/kubernetes/resources.ts
+function resourcePath(query, name) {
+  const parts = query.apiVersion.split("/");
+  if (parts.length > 2 || parts.some((part) => !/^[a-z0-9][a-z0-9.-]*$/.test(part)) || !/^[a-z][a-z0-9-]*$/.test(query.resource) || query.namespace !== undefined && !/^[a-z0-9][a-z0-9-]*$/.test(query.namespace) || name !== undefined && !/^[a-z0-9][a-z0-9.-]*$/.test(name)) {
+    throw new KubernetesError("Invalid Kubernetes resource identity", { kind: "invalid_argument" });
+  }
+  const prefix = parts.length === 1 ? "/api/" : "/apis/";
+  return prefix + parts.join("/") + (query.namespace === undefined ? "" : "/namespaces/" + query.namespace) + "/" + query.resource + (name === undefined ? "" : "/" + name);
+}
+
+export { resourcePath };

package/dist/chunk-shsabpc1.js

@@ -0,0 +1,267 @@
+import {
+  KubernetesError,
+  kubernetesHttpError
+} from "./chunk-20kv4wc3.js";
+import {
+  ConcurrencyPool
+} from "./chunk-v3hxvnrc.js";
+
+// src/kubernetes/exec-transport.ts
+import { KubeConfig } from "@kubernetes/client-node";
+import WebSocket from "ws";
+class KubernetesExecTransport {
+  signal;
+  limits;
+  #config = new KubeConfig;
+  #capacity;
+  #server;
+  constructor(options, signal, limits) {
+    this.signal = signal;
+    this.limits = limits;
+    if (!Object.values(limits).every((value) => Number.isSafeInteger(value) && value > 0)) {
+      throw new KubernetesError("Exec limits must be positive integers", { kind: "invalid_argument" });
+    }
+    if (options.kubeconfig)
+      this.#config.loadFromFile(options.kubeconfig);
+    else
+      this.#config.loadFromDefault();
+    if (options.context)
+      this.#config.setCurrentContext(options.context);
+    const cluster = this.#config.getCurrentCluster();
+    if (!cluster)
+      throw new KubernetesError("Kubernetes context has no cluster", { kind: "invalid_argument" });
+    if (process.versions.bun && cluster.proxyUrl) {
+      throw new KubernetesError("Native exec through a kubeconfig proxy requires a Node host", { kind: "unsupported_operation" });
+    }
+    this.#server = cluster.server.replace(/\/$/, "");
+    if (new URL(cluster.server).protocol === "http:")
+      this.#config.clusters = this.#config.clusters.map((item) => item === cluster ? { ...item, skipTLSVerify: true } : item);
+    this.#capacity = new ConcurrencyPool(limits.concurrency);
+  }
+  async exec(namespace, target, command, options = {}) {
+    const started = performance.now();
+    const timeoutMs = options.timeoutMs ?? this.limits.timeoutMs;
+    if (!Number.isSafeInteger(timeoutMs) || timeoutMs <= 0 || !namespace || !target.pod || !command.length) {
+      throw new KubernetesError("Exec requires a namespace, Pod, command and positive timeout", { kind: "invalid_argument" });
+    }
+    const caller = options.signal ? AbortSignal.any([this.signal, options.signal]) : this.signal;
+    const deadline = new AbortController;
+    const signal = AbortSignal.any([caller, deadline.signal]);
+    const timer = setTimeout(() => deadline.abort(), timeoutMs);
+    try {
+      return await this.#capacity.run(() => this.#session(namespace, target, command, options, signal, started, deadline.signal), signal);
+    } catch (error) {
+      if (caller.aborted)
+        throw caller.reason;
+      if (deadline.signal.aborted)
+        return this.#result(namespace, target, command, started, null, "", "Exec deadline exceeded", true);
+      throw error;
+    } finally {
+      clearTimeout(timer);
+    }
+  }
+  #result(namespace, target, command, started, exitCode, stdout, stderr, timedOut = false) {
+    return {
+      ok: exitCode === 0 && !timedOut,
+      exitCode,
+      stdout,
+      stderr,
+      timedOut,
+      durationMs: performance.now() - started,
+      command: [
+        "kubernetes-api",
+        "exec",
+        "-n",
+        namespace,
+        target.pod,
+        ...target.container ? ["-c", target.container] : [],
+        "--",
+        ...command
+      ]
+    };
+  }
+  #session(namespace, target, command, options, signal, started, deadline) {
+    return new Promise((resolve, reject) => {
+      let socket;
+      let agent;
+      let input;
+      let settled = false;
+      let stdout = "", stderr = "", retained = 0;
+      const outDecoder = new TextDecoder, errDecoder = new TextDecoder;
+      const finish = (exitCode, error) => {
+        if (settled)
+          return;
+        settled = true;
+        signal.removeEventListener("abort", abort);
+        socket?.terminate();
+        agent?.destroy();
+        input?.cancel().catch(() => {});
+        const tail = outDecoder.decode(), errTail = errDecoder.decode();
+        if (options.collectStdout !== false)
+          stdout += tail;
+        stderr += errTail;
+        try {
+          if (tail)
+            options.onStdout?.(tail);
+          if (errTail)
+            options.onStderr?.(errTail);
+        } catch (cause) {
+          error ??= cause instanceof Error ? cause : new Error("Exec output callback failed");
+        }
+        if (error)
+          reject(error);
+        else
+          resolve(this.#result(namespace, target, command, started, exitCode, stdout, stderr, deadline.aborted));
+      };
+      const abort = () => {
+        if (deadline.aborted) {
+          stderr += `
+Exec deadline exceeded`;
+          finish(null);
+        } else
+          finish(null, signal.reason instanceof Error ? signal.reason : new Error("Exec aborted"));
+      };
+      const fail = (kind, cause) => finish(null, new KubernetesError(`Kubernetes exec ${namespace}/${target.pod} failed`, { kind, cause }));
+      if (signal.aborted) {
+        abort();
+        return;
+      }
+      signal.addEventListener("abort", abort, { once: true });
+      const request = { headers: {} };
+      this.#config.applyToHTTPSOptions(request).then(() => {
+        agent = request.agent;
+        if (settled || signal.aborted) {
+          agent?.destroy();
+          return;
+        }
+        const url = new URL(`${this.#server}/api/v1/namespaces/${encodeURIComponent(namespace)}/pods/${encodeURIComponent(target.pod)}/exec`);
+        url.protocol = url.protocol === "https:" ? "wss:" : "ws:";
+        for (const arg of command)
+          url.searchParams.append("command", arg);
+        url.searchParams.set("stdout", "true");
+        url.searchParams.set("stderr", "true");
+        url.searchParams.set("stdin", String(options.stdin !== undefined));
+        url.searchParams.set("tty", "false");
+        if (target.container)
+          url.searchParams.set("container", target.container);
+        socket = new WebSocket(url, options.stdin === undefined ? ["v5.channel.k8s.io", "v4.channel.k8s.io"] : ["v5.channel.k8s.io"], { ...request, ...process.versions.bun ? { tls: {
+          ca: request.ca,
+          cert: request.cert,
+          key: request.key,
+          pfx: request.pfx,
+          passphrase: request.passphrase,
+          rejectUnauthorized: request.rejectUnauthorized,
+          serverName: request.servername
+        } } : {}, maxPayload: this.limits.maxBytes, handshakeTimeout: this.limits.timeoutMs });
+        if (!process.versions.bun)
+          socket.on("unexpected-response", (request2, response) => {
+            const status = response.statusCode ?? 500;
+            response.destroy();
+            request2.destroy();
+            const failure = kubernetesHttpError(status);
+            finish(null, new KubernetesError(`Kubernetes exec ${namespace}/${target.pod} HTTP ${status}`, {
+              kind: failure.kind,
+              code: status
+            }));
+          });
+        socket.on("error", (error) => fail("connection_failed", error));
+        socket.on("close", () => {
+          if (!settled)
+            fail("connection_lost");
+        });
+        socket.on("message", (data, binary) => {
+          if (settled)
+            return;
+          try {
+            if (!binary)
+              throw new Error("Exec frame must be binary");
+            const frame = Buffer.isBuffer(data) ? data : Array.isArray(data) ? Buffer.concat(data) : Buffer.from(data);
+            if (!frame.length)
+              throw new Error("Empty exec frame");
+            if (frame.length > this.limits.maxBytes) {
+              fail("limit_exceeded");
+              return;
+            }
+            const channel = frame[0], payload = frame.subarray(1);
+            if (channel === 255) {
+              if (payload.length !== 1 || ![0, 1, 2].includes(payload[0]))
+                throw new Error("Invalid channel close");
+              return;
+            }
+            if (channel === 3) {
+              const status = JSON.parse(payload.toString("utf8"));
+              if (status.status === "Success") {
+                finish(0);
+                return;
+              }
+              const code = status.details?.causes?.find((cause) => cause.reason === "ExitCode")?.message;
+              if (status.status !== "Failure" || !/^\d+$/.test(code ?? ""))
+                throw new Error("Exec status lacks exit code");
+              if (!Number.isSafeInteger(Number(code)))
+                throw new Error("Invalid exit code");
+              finish(Number(code));
+              return;
+            }
+            if (channel !== 1 && channel !== 2)
+              throw new Error("Invalid exec channel");
+            if (channel === 2 || options.collectStdout !== false)
+              retained += payload.length;
+            if (retained > this.limits.maxBytes) {
+              fail("limit_exceeded");
+              return;
+            }
+            if (channel === 1) {
+              options.onStdoutBytes?.(payload);
+              const text = outDecoder.decode(payload, { stream: true });
+              if (options.collectStdout !== false)
+                stdout += text;
+              options.onStdout?.(text);
+            } else {
+              const text = errDecoder.decode(payload, { stream: true });
+              stderr += text;
+              options.onStderr?.(text);
+            }
+          } catch (error) {
+            fail("invalid_response", error);
+          }
+        });
+        socket.on("open", () => {
+          if (options.stdin === undefined || settled)
+            return;
+          const send = (bytes) => new Promise((done, failed) => {
+            if (settled) {
+              failed(new Error("Exec closed"));
+              return;
+            }
+            socket.send(Buffer.concat([Buffer.from([0]), bytes]), (error) => error ? failed(error) : done());
+          });
+          (async () => {
+            const stdin = options.stdin;
+            if (typeof stdin === "string" || stdin instanceof Uint8Array)
+              await send(typeof stdin === "string" ? new TextEncoder().encode(stdin) : stdin);
+            else {
+              const reader = stdin.getReader();
+              input = reader;
+              while (!settled) {
+                const chunk = await reader.read();
+                if (chunk.done)
+                  break;
+                await send(chunk.value);
+              }
+            }
+            if (!settled)
+              socket.send(Buffer.from([255, 0]));
+          })().catch((error) => {
+            if (!settled)
+              fail("connection_failed", error);
+          });
+        });
+      }).catch((error) => {
+        if (!settled)
+          fail("connection_failed", error);
+      });
+    });
+  }
+}
+
+export { KubernetesExecTransport };

package/dist/kubernetes/client.d.ts

@@ -1,21 +1,29 @@
 import type { Client } from "../client";
-import { type Executor, type KubectlOptions, type ExecTarget, type RunOptions } from "./executor";
+import { type Executor, type ExecTarget, type RunOptions } from "./executor";
 import type { KubernetesEndpoint } from "./endpoint";
 import type { Workload, WorkloadInstance } from "@compforge/harness-common";
-import { type ResourceAccess, type ResourceLimits } from "./resources";
+import type { ResourceAccess, ResourceLimits, ResourceRef, ResourceListQuery, ResourceRequestOptions, NamespaceResources } from "./resources";
+import { type KubernetesConnectionOptions } from "./resource-transport";
 /** Owns cluster transports; protocol callers borrow this client without closing it. */
 export declare class KubernetesClient implements Client {
     #private;
     private readonly kube;
     private readonly resourceLimits;
     readonly signal: AbortSignal;
-    constructor(kube: KubectlOptions & {
+    constructor(kube: KubernetesConnectionOptions & {
         namespace: string;
     }, signal?: AbortSignal, executor?: Executor, resourceLimits?: ResourceLimits, resources?: ResourceAccess);
     initialize(): Promise<void>;
     /** environment is a stable target ID from the caller's registry, not access configuration. */
     resolveWorkload(workload: Workload, environment: string): Promise<WorkloadInstance[]>;
-    run(namespace: string, command: string[], options?: RunOptions): Promise<import("./executor").ExecResult>;
+    /**
+     * @spec Resource operations return API objects and structured errors, sharing one root HTTP transport.
+     * @rule Namespace views borrow the root lifecycle; reads never fall back to command execution.
+     * @see {@link docs/toolbox.md}
+     */
+    get(ref: ResourceRef, options?: ResourceRequestOptions): Promise<import("./resources").Resource>;
+    list(query: ResourceListQuery, options?: ResourceRequestOptions): Promise<import("./resources").ResourceList>;
+    inNamespace(namespace: string): NamespaceResources;
     exec(namespace: string, target: ExecTarget, command: string[], options?: RunOptions): Promise<import("./executor").ExecResult>;
     forward(namespace: string, target: KubernetesEndpoint): Promise<import("./service-port-forward").ForwardedEndpoint>;
     dispose(): Promise<void>;

package/dist/kubernetes/client.js

@@ -1,11 +1,14 @@
 import {
   KubernetesClient
-} from "../chunk-a1cb44ga.js";
-import"../chunk-8axd2y2m.js";
+} from "../chunk-8kts470p.js";
+import"../chunk-4ms037k2.js";
+import"../chunk-0s27bgga.js";
 import"../chunk-2171tajs.js";
 import"../chunk-j46x7j7c.js";
 import"../chunk-6fnhzhdb.js";
-import"../chunk-9n9z2pty.js";
+import"../chunk-ftkrjqkc.js";
+import"../chunk-shsabpc1.js";
+import"../chunk-a9htb6cr.js";
 import"../chunk-20kv4wc3.js";
 import"../chunk-v3hxvnrc.js";
 import"../chunk-631vce5z.js";

package/dist/kubernetes/environment.d.ts

@@ -1,7 +1,7 @@
 import { type ClientProvider, type ClientManager } from "../client";
 import type { Environment } from "@compforge/harness-common";
 import { KubernetesClient } from "./client";
-import type { KubectlOptions } from "./executor";
+import type { KubernetesConnectionOptions } from "./resource-transport";
 import type { ResourceLimits } from "./resources";
 /** Cluster access is a client provider; the execution owns client lifetime. */
 export declare class KubernetesEnvironment implements Environment, ClientProvider<KubernetesClient> {
@@ -11,7 +11,7 @@ export declare class KubernetesEnvironment implements Environment, ClientProvide
     readonly clientKey: string;
     /** Deployment metadata only; not part of client reuse or access configuration. */
     readonly imageRegistry?: string;
-    constructor(name: string, kube: KubectlOptions & {
+    constructor(name: string, kube: KubernetesConnectionOptions & {
         namespace: string;
         imageRegistry?: string;
     }, limits: ResourceLimits);

package/dist/kubernetes/environment.js

@@ -1,11 +1,13 @@
 import {
   KubernetesClient
-} from "../chunk-a1cb44ga.js";
-import"../chunk-8axd2y2m.js";
+} from "../chunk-8kts470p.js";
+import"../chunk-4ms037k2.js";
+import"../chunk-0s27bgga.js";
 import"../chunk-2171tajs.js";
 import"../chunk-j46x7j7c.js";
 import"../chunk-6fnhzhdb.js";
-import"../chunk-9n9z2pty.js";
+import"../chunk-ftkrjqkc.js";
+import"../chunk-shsabpc1.js";
 import {
   clientKey
 } from "../chunk-a9htb6cr.js";

package/dist/kubernetes/exec-transport.d.ts

@@ -0,0 +1,19 @@
+import type { ExecTarget, ExecResult, RunOptions } from "./executor";
+import type { KubernetesConnectionOptions } from "./resource-transport";
+export interface KubernetesExecLimits {
+    timeoutMs: number;
+    concurrency: number;
+    maxBytes: number;
+}
+/**
+ * @spec Each exec owns one channel session; it is never retried or replayed.
+ * @rule The root owns configuration and capacity. Deadlines cover queueing, auth, upgrade and execution.
+ * @why A WebSocket upgrade cannot reuse an ordinary HTTP request connection as another exec session.
+ */
+export declare class KubernetesExecTransport {
+    #private;
+    private readonly signal;
+    private readonly limits;
+    constructor(options: KubernetesConnectionOptions, signal: AbortSignal, limits: KubernetesExecLimits);
+    exec(namespace: string, target: ExecTarget, command: string[], options?: RunOptions): Promise<ExecResult>;
+}

package/dist/kubernetes/exec-transport.js

@@ -0,0 +1,8 @@
+import {
+  KubernetesExecTransport
+} from "../chunk-shsabpc1.js";
+import"../chunk-20kv4wc3.js";
+import"../chunk-v3hxvnrc.js";
+export {
+  KubernetesExecTransport
+};

package/dist/kubernetes/resource-transport.d.ts

@@ -0,0 +1,19 @@
+import { type Resource, type ResourceAccess, type ResourceList, type ResourceListQuery, type ResourceRef, type ResourceRequestOptions, type ResourceLimits } from "./resources";
+export interface KubernetesConnectionOptions {
+    kubeconfig?: string;
+    context?: string;
+}
+/**
+ * @spec One root transport owns HTTP connections across resource kinds and namespaces.
+ * @rule Credentials refresh per request; TLS/proxy changes retire the old pool after its active reads finish.
+ * @rule Deadlines cover queueing, authentication and response consumption; failed requests are never replayed.
+ * @see {@link docs/toolbox.md}
+ */
+export declare class KubernetesResourceTransport implements ResourceAccess {
+    #private;
+    private readonly limits;
+    constructor(options: KubernetesConnectionOptions, signal: AbortSignal, limits: ResourceLimits);
+    get(ref: ResourceRef, options?: ResourceRequestOptions): Promise<Resource>;
+    list(query: ResourceListQuery, options?: ResourceRequestOptions): Promise<ResourceList>;
+    dispose(): void;
+}

package/dist/kubernetes/resource-transport.js

@@ -0,0 +1,10 @@
+import {
+  KubernetesResourceTransport
+} from "../chunk-4ms037k2.js";
+import"../chunk-ftkrjqkc.js";
+import"../chunk-a9htb6cr.js";
+import"../chunk-20kv4wc3.js";
+import"../chunk-v3hxvnrc.js";
+export {
+  KubernetesResourceTransport
+};

package/dist/kubernetes/resources.d.ts

@@ -1,23 +1,63 @@
-import type { KubectlOptions } from "./executor";
+/** API resource names are plural REST names, not Kind names or kubectl aliases. */
+export interface ResourceQuery {
+    apiVersion: string;
+    resource: string;
+    namespace?: string;
+}
+export interface ResourceRef extends ResourceQuery {
+    name: string;
+}
+export interface ResourceListQuery extends ResourceQuery {
+    labelSelector?: string;
+    fieldSelector?: string;
+    limit?: number;
+    continue?: string;
+}
+/** Preserve the server manifest; consumers own projections into domain models. */
 export interface Resource {
+    [field: string]: unknown;
+    apiVersion?: string;
+    kind?: string;
     metadata?: {
         name?: string;
         namespace?: string;
         uid?: string;
+        [field: string]: unknown;
     };
     spec?: {
         selector?: unknown;
+        [field: string]: unknown;
     };
-    items?: Resource[];
+}
+export interface ResourceList {
+    apiVersion?: string;
     kind?: string;
+    metadata?: {
+        continue?: string;
+        resourceVersion?: string;
+        [field: string]: unknown;
+    };
+    items: Resource[];
+    [field: string]: unknown;
+}
+export interface ResourceRequestOptions {
+    signal?: AbortSignal;
+    /** Total budget, including capacity wait, authentication and response consumption. */
+    timeoutMs?: number;
 }
 export interface ResourceAccess {
-    get(namespace: string, resource: string, name?: string, selector?: string): Promise<Resource>;
+    get(ref: ResourceRef, options?: ResourceRequestOptions): Promise<Resource>;
+    list(query: ResourceListQuery, options?: ResourceRequestOptions): Promise<ResourceList>;
 }
 export interface ResourceLimits {
     timeoutMs: number;
     concurrency: number;
     maxBytes: number;
 }
-/** Native JSON reads use the same client-node auth/TLS path as native Pod logs. */
-export declare function resourceAccess(options: KubectlOptions, signal: AbortSignal, limits: ResourceLimits): ResourceAccess;
+/** Namespace views borrow the root client and cannot close it or override their scope. */
+export interface NamespaceResources {
+    get(ref: Omit<ResourceRef, "namespace">, options?: ResourceRequestOptions): Promise<Resource>;
+    list(query: Omit<ResourceListQuery, "namespace">, options?: ResourceRequestOptions): Promise<ResourceList>;
+}
+/** Explicit scope avoids interpreting an omitted namespace as a cluster-wide list. */
+export declare function resourcePath(query: ResourceQuery, name?: string): string;

package/dist/kubernetes/resources.js

@@ -1,8 +1,7 @@
 import {
-  resourceAccess
-} from "../chunk-9n9z2pty.js";
+  resourcePath
+} from "../chunk-ftkrjqkc.js";
 import"../chunk-20kv4wc3.js";
-import"../chunk-v3hxvnrc.js";
 export {
-  resourceAccess
+  resourcePath
 };

package/dist/kubernetes/workload.js

@@ -1,6 +1,6 @@
 import {
   resolveWorkload
-} from "../chunk-8axd2y2m.js";
+} from "../chunk-0s27bgga.js";
 import"../chunk-20kv4wc3.js";
 export {
   resolveWorkload

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@compforge/harness-toolbox",
-  "version": "0.3.11",
+  "version": "0.4.1",
   "description": "Shared infrastructure clients, transports and bounded data capture",
   "type": "module",
   "scripts": {
@@ -106,13 +106,15 @@
     "@redis/client": "6.1.0",
     "@smithy/node-http-handler": "4.12.1",
     "mysql2": "3.23.1",
-    "node-fetch": "2.7.0"
+    "node-fetch": "2.7.0",
+    "ws": "8.21.3"
   },
   "devDependencies": {
     "@types/bun": "latest",
     "typescript": "^5.6.0",
     "@types/node-fetch": "2.6.13",
-    "@types/node": "^22"
+    "@types/node": "^22",
+    "@types/ws": "^8.18.1"
   },
   "publishConfig": {
     "access": "public"

package/dist/chunk-9n9z2pty.js

@@ -1,89 +0,0 @@
-import {
-  KubernetesError,
-  ToolboxError,
-  kubernetesHttpError
-} from "./chunk-20kv4wc3.js";
-import {
-  ConcurrencyPool
-} from "./chunk-v3hxvnrc.js";
-
-// src/kubernetes/resources.ts
-import { KubeConfig } from "@kubernetes/client-node";
-import fetch from "node-fetch/lib/index.js";
-function resourceAccess(options, signal, limits) {
-  if (![limits.timeoutMs, limits.concurrency, limits.maxBytes].every((value) => Number.isSafeInteger(value) && value > 0)) {
-    throw new KubernetesError("Resource limits must be positive integers", { kind: "invalid_argument" });
-  }
-  const config = new KubeConfig;
-  try {
-    if (options.kubeconfig)
-      config.loadFromFile(options.kubeconfig);
-    else
-      config.loadFromDefault();
-    if (options.context)
-      config.setCurrentContext(options.context);
-  } catch (cause) {
-    throw new KubernetesError("Cannot load Kubernetes access configuration", { kind: "connection_failed", cause });
-  }
-  const cluster = config.getCurrentCluster();
-  if (!cluster)
-    throw new KubernetesError("Kubernetes context has no cluster", { kind: "invalid_argument" });
-  if (new URL(cluster.server).protocol === "http:") {
-    config.clusters = config.clusters.map((item) => item === cluster ? { ...item, skipTLSVerify: true } : item);
-  }
-  const pool = new ConcurrencyPool(limits.concurrency);
-  return {
-    get: (namespace, resource, name, selector) => pool.run(async () => {
-      const group = ["pods", "services"].includes(resource) ? "/api/v1" : "/apis/apps/v1";
-      const path = group + "/namespaces/" + encodeURIComponent(namespace) + "/" + resource + (name ? "/" + encodeURIComponent(name) : "");
-      const url = new URL(cluster.server.replace(/\/$/, "") + path);
-      if (selector)
-        url.searchParams.set("labelSelector", selector);
-      const controller = new AbortController;
-      const abort = () => controller.abort(signal.reason);
-      signal.addEventListener("abort", abort, { once: true });
-      let timedOut = false;
-      const timer = setTimeout(() => {
-        timedOut = true;
-        controller.abort();
-      }, limits.timeoutMs);
-      try {
-        signal.throwIfAborted();
-        const init = await config.applyToFetchOptions({});
-        controller.signal.throwIfAborted();
-        const response = await fetch(url.href, { ...init, signal: controller.signal, size: limits.maxBytes });
-        if (!response.ok) {
-          controller.abort();
-          const error = kubernetesHttpError(response.status);
-          throw new KubernetesError("Read " + resource + " in namespace " + namespace + " failed", { kind: error.kind, code: error.code });
-        }
-        return await response.json();
-      } catch (cause) {
-        if (signal.aborted)
-          throw signal.reason;
-        if (cause instanceof ToolboxError)
-          throw cause;
-        const type = cause && typeof cause === "object" && "type" in cause ? cause.type : undefined;
-        const code = cause && typeof cause === "object" && "code" in cause && typeof cause.code === "string" ? cause.code : undefined;
-        const tls = code !== undefined && [
-          "CERT_HAS_EXPIRED",
-          "DEPTH_ZERO_SELF_SIGNED_CERT",
-          "SELF_SIGNED_CERT_IN_CHAIN",
-          "UNABLE_TO_VERIFY_LEAF_SIGNATURE",
-          "UNABLE_TO_GET_ISSUER_CERT_LOCALLY",
-          "ERR_TLS_CERT_ALTNAME_INVALID"
-        ].includes(code);
-        throw new KubernetesError("Read " + resource + " in namespace " + namespace + " failed", {
-          kind: timedOut ? "timeout" : type === "max-size" ? "limit_exceeded" : type === "invalid-json" ? "invalid_response" : tls ? "tls_verification_failed" : code === "ECONNRESET" ? "connection_lost" : "connection_failed",
-          cause,
-          code
-        });
-      } finally {
-        clearTimeout(timer);
-        signal.removeEventListener("abort", abort);
-      }
-    }, signal)
-  };
-}
-
-export { resourceAccess };