@wardby/cli 0.5.3 → 0.7.0

package/docs/coding-services.md

@@ -105,18 +105,18 @@ caller's principal id).
 
 An entry has:
 
-| Field             | Meaning                                                                                                                                                  |
-| ----------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `name`, `version` | What a repository declares. Unique together.                                                                                                             |
-| `kind`            | `sidecar`: a fresh instance next to each run.                                                                                                            |
-| `image`           | The image, pinned by digest.                                                                                                                             |
-| `port`            | The port it listens on.                                                                                                                                  |
-| `serviceEnv`      | Environment for the service container. Per-run throwaway values only; never put a secret here.                                                           |
-| `testEnv`         | Variables the agent's shells receive. Upper-case names; names wardby uses itself (`PATH`, `HOME`, `PIP_*`, `WARDBY_*`, proxy settings, ...) are refused. |
-| `readiness`       | A command in the image that succeeds once the service accepts connections on `127.0.0.1`, with its period, timeout and failure threshold.                |
-| `resources`       | CPU (millicores), memory (MiB) and disk (MiB). Requests equal limits.                                                                                    |
-| `dataPath`        | The directory the service writes its data to; an empty volume in every run (memory-backed on Docker).                                                    |
-| `writablePaths`   | Other directories the image writes to (a socket directory, `/tmp`). The service's root filesystem is read-only.                                          |
+| Field             | Meaning                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
+| ----------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `name`, `version` | What a repository declares. Unique together.                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
+| `kind`            | `sidecar`: a fresh instance next to each run.                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
+| `image`           | The image, pinned by digest.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
+| `port`            | The port it listens on.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
+| `serviceEnv`      | Environment for the service container. Per-run throwaway values only; never put a secret here.                                                                                                                                                                                                                                                                                                                                                                                                              |
+| `testEnv`         | Variables the agent's shells receive. Upper-case names. Names wardby uses itself are refused: `HOME`, `LANG`, `LC_ALL`, `PATH`, `SHELL`, `TMPDIR`, `USER`, `LD_PRELOAD`, `LD_LIBRARY_PATH`, `NODE_OPTIONS`, `NODE_PATH`, `PYTHONPATH`, `PYTHONHOME`, the proxy settings (`HTTP_PROXY`, `HTTPS_PROXY`, `NO_PROXY`, `ALL_PROXY`), `SSL_CERT_FILE`, `SSL_CERT_DIR`, and anything starting `WARDBY_`, `CODEX_`, `OPENAI_`, `ANTHROPIC_`, `PIP_`, `NPM_CONFIG_`, `UV_`, `GIT_`, `YARN_`, `PNPM_` or `COREPACK_`. |
+| `readiness`       | A command in the image that succeeds once the service accepts connections on `127.0.0.1`, with its period, timeout and failure threshold.                                                                                                                                                                                                                                                                                                                                                                   |
+| `resources`       | CPU (millicores), memory (MiB) and disk (MiB). Requests equal limits.                                                                                                                                                                                                                                                                                                                                                                                                                                       |
+| `dataPath`        | The directory the service writes its data to; an empty volume in every run (memory-backed on Docker).                                                                                                                                                                                                                                                                                                                                                                                                       |
+| `writablePaths`   | Other directories the image writes to (a socket directory, `/tmp`). The service's root filesystem is read-only.                                                                                                                                                                                                                                                                                                                                                                                             |
 
 ### Built-in services
 
@@ -194,7 +194,9 @@ to an agent that allows at least one service.
 
 A [bring-your-own worker image](coding-worker-byo-images.md) must be built on
 driver v11 or later to run with services; an agent whose `workerImageRef`
-predates driver v11 rejects the run input once services are on it.
+predates driver v11 rejects the run input once services are on it. For a
+Claude Code agent, build the custom image `FROM` the tool runner image of the
+same wardby release.
 
 ## Letting a coding agent change the declaration
 
@@ -231,6 +233,8 @@ Protected-path entries also accept a leading `!` for your own exceptions:
 | A service never became ready                   | Launch   | failed, category `service_unready`         | "The `<name>` service didn't become ready, so the run couldn't start."                                                                                                                |
 | The run's changes touched a protected path     | Collect  | failed, category `protected_path`          | "its changes include `<path>`, which this agent may not edit, so none of its changes were kept. Ask again without changing that file, or have the repository owner make that change." |
 
+For a coding sub-agent of a sandboxed run, these refusals appear when the run starts instead of at dispatch, and the parent's delegation call receives the result.
+
 A refused run's `error` (from `get_run`) is the code followed by that sentence.
 The sentence reaches the requester on the run's status comment and, for a
 coding run started by another agent, in that agent's tool result. A
@@ -301,3 +305,16 @@ who maintain the catalog; see
 Existing agents are allowed no services until their owners add
 `codingProfile.services`, and every existing agent gets the `.wardby/`
 protected-path baseline without any change to its settings.
+
+### From 0.7.0: `YARN_*`, `PNPM_*` and `COREPACK_*` are reserved
+
+From Wardby 0.7.0 a service's `testEnv` can't set a variable starting
+`YARN_`, `PNPM_` or `COREPACK_`: the worker uses them to point yarn, pnpm and
+corepack at the package registry (see
+[pnpm and yarn](coding-packages.md#pnpm-and-yarn)). A custom catalog entry
+that sets one fails to load after the upgrade, and so does a run that
+declares it. Before you upgrade, list the catalog (`list_services`) and
+remove those variables from any entry's `testEnv` with `update_service`.
+After the upgrade such an entry can no longer be read or updated: delete it
+with `delete_service` and create it again without those variables. The
+built-in services set none.

package/docs/coding-worker-byo-images.md

@@ -7,6 +7,9 @@ wardby's published **driver base image** and point your agent's
 `workerImageRef` at it, instead of waiting for wardby to hand-author a new
 `Dockerfile.<toolchain>`.
 
+The driver image is for Codex agents. A Claude Code agent's image starts from a
+different base; see [Codex and Claude Code](#codex-and-claude-code).
+
 ## The driver image
 
 `ghcr.io/wardby/wardby/wardby-coding-worker-driver` contains wardby's
@@ -112,13 +115,193 @@ point one at an arbitrary image without the step-up scope. The scope alone
 isn't enough: the caller must also hold the admin role (see
 [roles and privileged operations](security-deployment.md#roles-and-privileged-operations)).
 
-## Codex only
+## Codex and Claude Code
+
+A Codex agent runs in one container, and its commands run there too. A Claude
+Code agent uses two containers: one runs Claude Code and holds its API key; the
+other runs the agent's commands and has your repository. `workerImageRef` always
+replaces the container that runs commands.
+
+|                                | Codex agent                                                       | Claude Code agent                                                                                               |
+| ------------------------------ | ----------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------- |
+| What `workerImageRef` replaces | the agent's only container                                        | the container that runs commands                                                                                |
+| Build your image `FROM`        | [the coding-worker driver image](#the-driver-image) (`driver-vN`) | the `wardby-claude-tool-runner` image from the same wardby release (or `wardby-claude-tool-runner-node-python`) |
+| Rebuild when                   | the driver image changes                                          | you upgrade wardby                                                                                              |
+| Claude Code itself runs on     | —                                                                 | wardby's standard image, never yours                                                                            |
+
+The driver image sections above are for Codex. The subsections below are for
+Claude Code. In them, "tool runner" means the container that runs a Claude Code
+agent's commands.
+
+### Build a custom image for a Claude Code agent
+
+1. **Find your release's tool runner image.** It is the value of
+   `CODING_CLAUDE_TOOL_RUNNER_IMAGE` on your server. To start from Node and
+   Python, use `CODING_CLAUDE_TOOL_RUNNER_IMAGE_NODE_PYTHON_3_12` instead. A
+   release value looks like
+   `ghcr.io/wardby/wardby/wardby-claude-tool-runner@sha256:<digest>`. If the
+   value is a local image ID (`sha256:...` only), give it a name first, because
+   Docker cannot build `FROM` a bare ID:
+   `docker tag sha256:<id> wardby-tool-runner-base:local`.
+2. **Make a build folder.** Use a small folder of your own, outside your
+   repository. Put in it the Dockerfile and only the files the Dockerfile
+   copies.
+3. **Write the Dockerfile.** Start from the image in step 1, install your tools
+   as `root`, then switch back to the tool runner's user:
+
+   ```dockerfile
+   FROM <image from step 1>
+   USER root
+   RUN apt-get update \
+       && apt-get install -y --no-install-recommends <your packages> \
+       && rm -rf /var/lib/apt/lists/*
+   USER 10001:10001
+   ```
+
+   Keep these rules:
+   - The last `USER` line is `USER 10001:10001`.
+   - Do not set `ENTRYPOINT` or `CMD`. The tool runner starts with the base
+     image's own entrypoint.
+   - Install everything at build time. A run cannot install system packages.
+   - Put tools in `/usr/local/bin` or `/usr/bin`. Do not put anything under
+     `/tmp` or `/home/wardby`: a run hides both.
+   - Put environment settings your commands need in a file under
+     `/etc/profile.d/` (see "How the tool runner runs commands" below). `ENV`
+     lines in the Dockerfile do not reach the agent's commands.
+
+4. **Build it:** `docker build --tag <name> <build folder>`. Release images are
+   `linux/amd64`. On an ARM machine, add `--platform linux/amd64` here and to
+   `docker run` in step 5.
+5. **Run the tests the way a run would.** Clone the repository to a throwaway
+   folder (on Linux, make it writable: `chmod -R a+rwX <clone>`). Then run the
+   project's test command with a run's restrictions and its fixed environment,
+   so `ENV` lines in the image do not apply:
+
+   ```sh
+   docker run --rm --read-only --tmpfs /tmp:rw,noexec,nosuid,size=64m --tmpfs /home/wardby:rw,noexec,nosuid,size=64m,uid=10001,gid=10001,mode=0700 --network none --user 10001:10001 --cap-drop ALL --security-opt no-new-privileges -v <clone>:/workspace -w /workspace --entrypoint env <name> -i HOME=/home/wardby LANG=C.UTF-8 PATH=/opt/wardby/bin:/usr/local/bin:/usr/bin:/bin sh -lc '<test command>'
+   ```
 
-`workerImageRef` applies to Codex agents. A Claude Code agent's commands run in
-the Claude tool runner, which `workerImageRef` does not change, so Claude Code
-agents cannot use a custom toolchain yet. They can use wardby's curated
-`node-python` toolchain (set the matching
-`CODING_CLAUDE_TOOL_RUNNER_IMAGE_NODE_PYTHON_3_12` image).
+   On an ARM machine, add `--platform linux/amd64` after `docker run`. Fix the
+   Dockerfile until the tests pass, then delete the clone.
+
+6. **Get an immutable reference.** A tag is refused.
+   - **Docker launcher** (wardby runs coding jobs with Docker on a single
+     machine): use the local image ID,
+     `docker image inspect --format '{{.Id}}' <name>`. Build on that machine.
+     Wardby never pulls these images.
+   - **Kubernetes:** push the image to a registry your cluster can pull from,
+     and use `<registry>/<name>@sha256:<digest>`.
+7. **Point the agent at it.** Call `update_agent` with the agent's id. This
+   needs the `agents:admin` scope and the admin role:
+
+   ```json
+   {
+     "id": "<agent id>",
+     "codingProfile": { "workerImageRef": "<reference from step 6>" }
+   }
+   ```
+
+8. **Try it.** Trigger a small task that uses your tools, such as "Run the
+   project's tests and report the results. Change nothing."
+
+To undo it, set `codingProfile.workerImageRef` to `null`. The agent then uses
+the standard tool runner for its `toolchain`.
+
+### Languages other than Node and Python
+
+A run can download packages only from wardby's package registry, which serves
+npm and PyPI. Packages for any other language must be in the image. If a
+package compiles native code, compile it in an earlier build stage and copy
+only the results into the final image. The final image then needs no compiler.
+
+The tool runner is based on Debian 12 (bookworm). Build stages that compile
+code must use a bookworm-based image too, so the results work with the tool
+runner's system libraries.
+
+This example adds Ruby and a project's gems. It is a starting point to adapt,
+not a tested recipe. Copy the project's `Gemfile` and `Gemfile.lock` into the
+build folder first.
+
+```dockerfile
+# Stage 1: install Ruby and the project's gems, compiling any native code.
+FROM ruby:3.3-slim-bookworm AS builder
+RUN apt-get update \
+    && apt-get install -y --no-install-recommends build-essential \
+    && rm -rf /var/lib/apt/lists/*
+ENV BUNDLE_PATH=/usr/local/bundle \
+    BUNDLE_DEPLOYMENT=true
+WORKDIR /build
+COPY Gemfile Gemfile.lock ./
+RUN bundle install
+
+# Stage 2: the tool runner from your wardby release, plus Ruby and the gems.
+FROM <tool runner image from step 1>
+USER root
+# Shared libraries Ruby needs at run time, plus any library your native gems
+# link to (for example libpq5 for pg).
+RUN apt-get update \
+    && apt-get install -y --no-install-recommends libffi8 libgmp10 libssl3 libyaml-0-2 zlib1g \
+    && rm -rf /var/lib/apt/lists/*
+# Ruby lives in /usr/local, and the gems in /usr/local/bundle.
+COPY --from=builder /usr/local /usr/local
+# Settings for the agent's commands (Dockerfile ENV lines do not reach them).
+RUN ldconfig \
+    && printf '%s\n' \
+      'export GEM_HOME=/usr/local/bundle' \
+      'export BUNDLE_PATH=/usr/local/bundle' \
+      'export BUNDLE_APP_CONFIG=/usr/local/bundle' \
+      'export BUNDLE_DEPLOYMENT=true' \
+      > /etc/profile.d/ruby.sh \
+    && sh -lc 'ruby --version && bundle --version'
+USER 10001:10001
+```
+
+Pin the `ruby` image by digest for repeatable builds. Rebuild the image when
+the project's `Gemfile.lock` changes.
+
+### If a run fails
+
+| What you see                            | What it usually means                                                                                                                                  |
+| --------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `worker_tool_runner_unreachable`        | The image was not built `FROM` the tool runner of the same wardby release, or the Dockerfile changed its `USER` or `ENTRYPOINT`.                       |
+| A command is "not found"                | The tool is not in the image, or a setting it needs is in an `ENV` line instead of `/etc/profile.d/`.                                                  |
+| "Permission denied" when running a file | On Docker, something writes a program to `/tmp` or `/home/wardby` and runs it. Point that tool's temporary or cache folder under `/workspace/.cache/`. |
+
+### How the tool runner runs commands
+
+These details explain the rules above.
+
+- **User and privileges.** Commands always run as user `10001`, with no Linux
+  capabilities and `no-new-privileges`. `root` and setuid programs do not work
+  at run time.
+- **Filesystem.** The root filesystem is read-only. `/tmp` and `/home/wardby`
+  are small, empty scratch space; anything the image put there is hidden. On
+  Docker, files there cannot be run. `/workspace` holds the repository; put
+  caches, build output and temporary files under `/workspace/.cache/`.
+- **Shell and environment.** Each command runs as `sh -lc "<command>"` with a
+  fixed environment: `HOME=/home/wardby`, `LANG=C.UTF-8`, `TMPDIR` under
+  `/workspace/.cache/`, wardby's package registry settings, and
+  `PATH=/opt/wardby/bin:/usr/local/bin:/usr/bin:/bin`. The login shell reads
+  `/etc/profile` and the files in `/etc/profile.d/`, so that is where your own
+  settings go. `/etc/profile` resets `PATH` to Debian's default, so add any
+  other folder to `PATH` in your `/etc/profile.d/` file.
+  `/opt/wardby/bin` holds wardby's package-manager shim, linked as `npm`,
+  `pnpm` and `yarn`: it verifies the project's lockfile with the registry
+  before an install, then runs the image's own tool (or the release the
+  project pins, through corepack). Keep it first on `PATH`; see
+  [pnpm and yarn](coding-packages.md#pnpm-and-yarn).
+- **Network.** The tool runner reaches only wardby's package registry (npm and
+  PyPI).
+- **Images on the Docker launcher are never pulled.** When wardby runs coding
+  jobs with Docker on a single machine, the image must already be on that
+  machine. Kubernetes needs a registry digest
+  (`repo@sha256:<64 hex>`).
+- **Server settings.** Claude Code itself always runs on
+  `CODING_CLAUDE_WORKER_IMAGE`. The server still needs both
+  `CODING_CLAUDE_WORKER_IMAGE` and `CODING_CLAUDE_TOOL_RUNNER_IMAGE` set, even
+  for agents with their own `workerImageRef`.
+- **Toolchain.** While `workerImageRef` is set, `toolchain` and
+  `toolchainVersion` do not choose the image, for either builder.
 
 ## Running services with a BYO image
 
@@ -130,6 +313,35 @@ a worker built on an older driver base doesn't recognize the input's
 without them. Rebuild your image on a current `driver-vN` digest (see "The
 driver image" above) before allowing any service on an agent that uses it.
 
+## Repository skills need a current driver
+
+On a Codex agent, a `workerImageRef` image never receives Claude Code's
+repository context (`claudeContext`) or `claudeBareMode`. The one new input key
+it can see is `repoSkills`, which wardby writes only when an agent sets
+`repoSkills: false`. A worker built on
+an older driver base validates its input with a strict schema, so it rejects
+runs of agents with `repoSkills: false` (the run fails with
+`worker_input_failed`), and it keeps offering Codex's built-in skills
+(`imagegen`, `openai-docs`, `skill-creator`, `skill-installer`), which a
+current driver always disables. Rebuild any `workerImageRef` image on a
+current `driver-vN` digest (see "The driver image" above) before relying on
+either behavior.
+
+## The dependency cache needs a current driver
+
+The [dependency cache](coding-packages.md#dependency-cache) adds keys to the run
+input (`dependencyCache` and the workspace size). A worker built on an older
+driver base validates its input with a strict schema, so with the cache on
+for its agent every run fails at input (`worker_input_failed`) before the
+agent starts. For a Claude Code agent, a tool runner built on an older tool
+runner image doesn't fail the run, but it has no cache: its projects report
+`tool_unavailable`. Rebuild a `workerImageRef` image `FROM` the driver image
+(Codex) or tool runner image (Claude Code) of the release that includes the
+cache before you set `dependencyCache: true` on an agent that uses it.
+`create_agent` and `update_agent` return a warning when an agent has both.
+Images built `FROM` that release carry the cache module at
+`/opt/wardby/coding-worker/dependency-cache.mjs`; keep that path.
+
 ## What this doesn't cover
 
 wardby does not re-validate the contents of your built image beyond the