feat(agents): support Kubernetes-driver gateways in the agent launcher

[purp]

User Story

As a maintainer running a persistent Kubernetes-backed gateway, I want scripts/agents/run.sh to launch agents against that gateway, so that unattended agents such as gator run on the same deployment topology used for shared and cloud deployments instead of requiring a separate Docker gateway kept alive just for them.

Problem Statement

The agent launcher supports only Docker and Podman compute drivers. Two gates combine to block Kubernetes:

• scripts/agents/run.sh:695 rejects any other driver outright: agent launcher local image builds require Docker or Podman.
• scripts/agents/run.sh:630 requires a local Dockerfile source, because the immutable agent payload (skills, prompts) is baked in as appended COPY layers. --from therefore cannot point at a pre-built registry image to bypass the build.

Together these mean no agent defined under scripts/agents/ can be launched against a gateway using the Kubernetes compute driver. The launcher builds into the local engine's image store, and nothing makes that image resolvable by a cluster.

Impact / Why This Matters

Kubernetes is the documented topology for running the gateway on a shared cluster, in a cloud environment, or as team infrastructure. A maintainer who runs the gateway that way must stand up and maintain a second, Docker-driver gateway whose only purpose is hosting agents.

For an unattended agent like gator, that second gateway becomes availability-critical infrastructure — typically on a developer workstation, since that is where the Docker driver is convenient. The workaround is insufficient on two counts: it does not survive the move to a real cluster, and it means agents are only ever exercised on a topology different from the one the project documents for production.

Proposed Design

run.sh should accept a gateway whose compute driver is Kubernetes. After building the payload image locally, the launcher makes that image resolvable by the target cluster and passes the resulting reference to the sandbox.

Observable behavior:

• ./scripts/agents/run.sh --agent <id> --gateway <kubernetes-gateway> ... provisions the sandbox and starts the agent, with the same supervised/watch semantics as the Docker path.
• How the image reaches the cluster is configurable, because a local single-node cluster and a remote managed cluster need different answers (importing into the node image store versus pushing to a registry the cluster can pull from).
• When no image destination is configured, the launcher fails with a message naming the missing configuration and how to supply it, rather than rejecting the driver outright.
• Payload immutability is preserved: skills and prompts remain baked into the image and read-only.

Acceptance Criteria

• The launcher provisions an agent sandbox against a Kubernetes-driver gateway.
• The agent payload remains baked into the image and read-only, matching the Docker path.
• The image destination is configurable to cover both a local cluster and a remote registry.
• A missing or unreachable image destination produces an actionable error naming the required configuration.
• Docker and Podman launches are unchanged.
• skills/ and the launch-openshell-gator contributor skill document the Kubernetes path.

Alternatives Considered

• Publish a pre-built agent image and point --from at it. Rejected by the immutable-payload requirement at run.sh:630, and it would decouple the payload from the image build that currently guarantees it is present and read-only.
• Keep a dedicated Docker-driver gateway for agents. The current workaround. It duplicates infrastructure, does not transfer to a cluster deployment, and leaves agents untested on the documented production topology.
• Have the gateway build images on behalf of the launcher. Expands gateway responsibility and trust surface well beyond its current role for a build-time convenience.

Agent Investigation

• scripts/agents/run.sh:683-698 resolves the gateway's compute driver via gateway info --output json, requires exactly one driver, and accepts only docker or podman.
• scripts/agents/run.sh:623-630 enforces that --from names a local Dockerfile or directory, because the payload is appended to the staged Dockerfile as COPY layers before the build.
• scripts/agents/gator/agent.yaml uses from: agent://., so gator specifically takes the local-build path.

[purp]

Ran a feasibility spike on a local k3d gateway (openshell-ci, Kubernetes driver, server 0.0.116). The image-distribution half of this works end to end today, and the required change looks narrower than the Proposed Design assumes.

What was verified

Built the gator image with Docker, imported it into the cluster, and launched a sandbox from it:

docker build -t openshell/agent-gator-spike:1 scripts/agents/gator/
k3d image import openshell/agent-gator-spike:1 -c openshell-ci
openshell --gateway openshell-ci sandbox create --name gator-spike --from openshell/agent-gator-spike:1 -- sleep infinity

The sandbox reached Ready. Pod events confirm no registry access was attempted for either container:

Normal  Pulled  spec.initContainers{workspace-init}: Container image "openshell/agent-gator-spike:1" already present on machine
Normal  Pulled  spec.containers{agent}:              Container image "openshell/agent-gator-spike:1" already present on machine

Why it resolves without a registry, and why that is fragile

KubernetesComputeConfig::default() sets image_pull_policy: None (crates/openshell-driver-kubernetes/src/config.rs:307), so the gateway omits imagePullPolicy and Kubernetes applies its own default: Always for :latest, IfNotPresent otherwise. The launcher tags builds openshell/agent-${AGENT_ID}:$(date +%s) (scripts/agents/run.sh:706), which is never latest, so an imported image is used as-is.

That is load-bearing but implicit. An operator who sets image_pull_policy = "Always" in gateway config, or an agent that ever tags :latest, turns this into ImagePullBackOff with no obvious cause. Suggest an explicit acceptance criterion: when the image destination is a node image store rather than a registry, the launcher either asserts an effective pull policy that permits local resolution or fails with a message naming the conflict.

The rest of the launcher is already driver-agnostic

• The sandbox create invocation (scripts/agents/run.sh:811-830) passes only --from, --provider, --no-auto-providers, --no-tty, --detach, --no-keep. Nothing Docker-specific.
• openshell --gateway <k8s> gateway info --output json reports exactly one driver (kubernetes), so the existing parsing at run.sh:686-692 already succeeds and reaches the case gate cleanly.
• provider profile import succeeded against the Kubernetes gateway.
• settings get --global exposes agent_policy_proposals_enabled and proposal_approval_mode, the two keys the launcher sets.

So the work is the driver gate plus an image-publish step. The payload/COPY mechanism needs no change, and --from can keep requiring a Dockerfile.

Not covered by this spike

Provider creation with live credentials and the gateway-managed Codex refresh rotation were not exercised, so the end-to-end gator launch on Kubernetes is still unproven. The spike ran a sleep infinity sandbox from the gator image, not the harness. Note also that 0.0.116 predates #3113 and #3317, so a current CLI against that server misreports created_at and sandbox deletion outcomes; that is version skew, unrelated to this issue, but it makes 0.0.116 a poor baseline for further launcher testing.