@zenera/cli 1.1.0 → 1.1.3

package/templates/editor/.github/skills/zen-cli/references/sandbox.md

@@ -0,0 +1,91 @@
+# The sandbox — `zen sandbox`
+
+```
+zen sandbox [status|up|pull|clean|disk] [options]
+```
+
+Shell commands run in a container over the session workspace, never on the
+host. None of this is required: a run does all of it on its own, the first time
+an agent that can reach a shell is about to start one. These subcommands are for
+doing it deliberately — before a demo, in CI, or when diagnosing.
+
+| Subcommand | What it does                                                   |
+| ---------- | -------------------------------------------------------------- |
+| `status`   | What is installed, running and pulled. Changes nothing         |
+| `up`       | Install if asked, start the machine, pull or build the image   |
+| `pull`     | Just the image: pulled, or built from the project's Dockerfile |
+| `clean`    | Remove every container this CLI created                        |
+| `disk`     | What the engine and every known project occupy                 |
+
+| Flag                    | Meaning                                 |
+| ----------------------- | --------------------------------------- |
+| `--project <name\|dir>` | Which project the image comes from      |
+| `--image <ref>`         | Use this image instead of the project's |
+
+The engine is Podman. On macOS a machine has to exist and be running; `up`
+offers to install and start one, and its size follows the project's `cpus` and
+`memory`.
+
+## Configuring it — `sandbox:` in `agents.yaml`
+
+Top level, and again per agent, where an agent's block is merged over the base.
+
+| Key       | Meaning                                                          |
+| --------- | ---------------------------------------------------------------- |
+| `image`   | The image to run. Mutually exclusive with `build`                |
+| `build`   | `{ dockerfile, context? }` — build one instead. Excludes `image` |
+| `cpus`    | CPU limit                                                        |
+| `memory`  | Memory limit, in MiB                                             |
+| `network` | Whether the container has one                                    |
+| `workdir` | Where the workspace is mounted. `/workspace` by default          |
+| `timeout` | Seconds one command may take                                     |
+| `user`    | Who commands run as                                              |
+| `persist` | Keep the container between runs                                  |
+| `env`     | A name-only allow-list of variables to pass in                   |
+
+`env` refuses names matching `KEY`, `TOKEN`, `SECRET`, `PASSWORD`, `PASSWD` or
+`CREDENTIAL`: the keyring has already materialised real credentials into the
+process environment, and a sandbox is the last place they should be forwarded to.
+
+## `persist: true` is usually what you want
+
+Only `/workspace` and `/home/agent` survive an ephemeral container. A
+`pip install` as root, or an `apt-get install`, lands in the image's system
+paths and is gone by the next run — so the agent silently reinstalls its
+toolchain every single time. `zen init` scaffolds `persist: true` for that
+reason.
+
+The caveat: the container's name is a function of its configuration, so any
+change to the sandbox block names a _new_ container and abandons the installed
+rootfs. If runs keep beginning with an install, either persist, or bake the
+toolchain into the image.
+
+## Building an image instead of naming one
+
+```yaml
+sandbox:
+    build:
+        dockerfile: sandbox/Dockerfile
+    persist: true
+```
+
+The tag is content-addressed — a hash of the Dockerfile and every file in its
+context — so a changed Dockerfile is a different image and a `persist: true`
+container can never be left sitting on a stale rootfs. It is built only when
+that tag is absent, which is safe precisely because the tag follows the content.
+`zen sandbox pull` forces a rebuild.
+
+## Hardening
+
+`no-new-privileges`, an init process, a pid limit, no restart policy. Not
+`--cap-drop=ALL` (it breaks `apt` and `pip`) and never `--privileged`.
+
+## When it goes wrong
+
+Exit code `5` means the container engine is missing or the image could not be
+prepared, and the message names the command to run for this platform. `zen check`
+distinguishes the two cases: a broken Dockerfile is an error, a laptop with no
+Podman is a warning.
+
+`zen sandbox clean` removes every container this CLI created — the way out of a
+container left on a bad rootfs.

package/templates/editor/.vscode/settings.json

@@ -0,0 +1,6 @@
+{
+    "chat.useNestedAgentsMdFiles": false,
+    "chat.tools.terminal.autoApprove": {
+        "zen": true
+    }
+}

package/templates/parts/exa.yaml.tmpl

@@ -0,0 +1,5 @@
+# exa:* is web search and page reading, here because this
+# machine has an Exa key. The key is read from the environment
+# when a tool is called, so a clone of this project without one
+# still loads and only the call fails.
+- exa:*

package/templates/parts/model.yaml.tmpl

@@ -0,0 +1,4 @@
+# The model an agent uses when it does not pin its own. Change it here and the
+# whole project moves. The prefix is the *provider* name, not the vendor — drop
+# it and the id goes to the default provider, whatever the id looks like.
+model: {{ref}}

package/templates/parts/models.yaml.tmpl

@@ -0,0 +1,10 @@
+# The model an agent uses when it does not pin its own. Change it here and the
+# whole project moves. A named configuration is what gives the knobs below
+# somewhere to live; a bare `model: <provider>:<id>` works when there are none.
+models:
+    main:
+        provider: {{provider}}
+        model: {{id}}
+        {{options}}
+
+model: main

package/templates/project/INSTRUCTIONS.md

@@ -0,0 +1,7 @@
+# House rules
+
+Everything in this file is prepended to every agent's prompt, so it is the
+place for the things that are true regardless of who is answering: tone,
+constraints, what to do when the answer is not knowable.
+
+Replace this with yours.

package/templates/project/SPECIFICATION.md

@@ -0,0 +1,6 @@
+# Specification
+
+What the project is meant to produce, the constraints it has to hold to, and
+how to tell a finished job from an unfinished one.
+
+Anything written here is the specification; while it is empty there is none.

package/templates/project/agents/prompts/default.md

@@ -0,0 +1,15 @@
+You are a helpful assistant working inside a project workspace.
+
+You have tools to read, search and edit files. The workspace is the only
+place you can see; paths are relative to its root.
+
+You can also run shell commands. They run in a container over the same
+workspace, not on the user's machine, so a command that fails there has cost
+them nothing — but it is still their work in the directory, so read before you
+overwrite and say what you ran.
+
+Read a file before you change it: `apply_patch` matches the surrounding text
+exactly, so a patch written from memory will not apply. Use `apply_patch` to
+change part of a file and `write_file` only for a new one.
+
+Say what you changed.

package/templates/project/agents.yaml.tmpl

@@ -0,0 +1,44 @@
+# Who exists, and what they may reach for.
+#
+version: 1
+
+{{model}}
+
+# Anything in assets/ is mounted read-only at /assets for every agent: they can
+# read, list and search it, and no tool can change it. It is a convention, so
+# the folder is enough — set `assets: <path>` only to keep the material
+# somewhere else in this project.
+
+# The container `sandbox:*` commands run in. `build:` names a Dockerfile to
+# build instead of an image to pull, so anything this project always needs is
+# in the image rather than installed by an agent on every run — put it in
+# sandbox/Dockerfile. Swap the whole block for `image: <ref>` to pull a
+# published one instead; the two cannot both be set.
+#
+# `persist: true` keeps the container between runs rather than throwing it
+# away, so what an agent installs for itself is still there next time —
+# otherwise only /workspace and its home directory survive. `zen sandbox
+# clean` removes the ones left behind. Everything else has a default; see the
+# sandbox: block in docs/agents-yaml.md to size it.
+sandbox:
+    persist: true
+    build:
+        dockerfile: sandbox/Dockerfile
+
+agents:
+    - name: default
+      description: The entry point.
+      # Instructions live in agents/prompts/<name>.md and are picked up by
+      # convention — no need to name the file here.
+      #
+      # workspace:* is every file tool at once, sandbox:* is the shell. Name
+      # them one by one to be narrower, or subtract: [workspace:*, -delete_file]
+      #
+      # sandbox:* runs commands in a container, not on this machine, so it
+      # needs podman — `zen run` installs and starts what it can on its own,
+      # and `zen sandbox status` says where that got to. Drop the line if you
+      # would rather this agent never reached a shell.
+      tools:
+          - workspace:*
+          - sandbox:*
+          {{exa}}

package/templates/project/assets/README.md

@@ -0,0 +1,12 @@
+# assets
+
+Everything in this folder is mounted at /assets when an agent runs. Every agent
+in this project can read, list and search it, and no tool of theirs can change
+it — so this is where reference material goes: handbooks, specifications,
+schemas, worked examples, the style guide the output is supposed to follow.
+
+It is the project's own files that agents get without being asked. The
+workspace they are pointed at is the work; this is what they consult while
+doing it.
+
+Delete this file once there is something here to read.

package/templates/project/gitignore

@@ -0,0 +1,9 @@
+# Sessions hold run state, memory, blobs and whatever the agent wrote.
+# None of it is source.
+sessions/
+
+# Scratch, inside the workspace so the sandbox can reach it.
+.tmp/
+
+# Credentials.
+.env

package/templates/project/sandbox/Dockerfile

@@ -0,0 +1,21 @@
+# The container `run_command` runs in. Built by `zen run` and `zen check`, and
+# named by the `sandbox: build:` block in agents.yaml.
+#
+# Python and Node both, because an agent asked to look at a repository does not
+# get to choose which one it finds. Add what this project always needs here
+# rather than letting an agent install it at run time: a root `pip install` or
+# `apt-get` lands in the container's own filesystem, which is thrown away.
+
+FROM node:24-bookworm-slim AS node
+FROM python:3.14-slim-bookworm
+
+# Copy Node.js runtime and global modules from official Node image
+COPY --from=node /usr/local/bin/node /usr/local/bin/node
+COPY --from=node /usr/local/include/node /usr/local/include/node
+COPY --from=node /usr/local/lib/node_modules /usr/local/lib/node_modules
+
+# Symlink npm and npx executables
+RUN ln -s /usr/local/lib/node_modules/npm/bin/npm-cli.js /usr/local/bin/npm \
+    && ln -s /usr/local/lib/node_modules/npm/bin/npx-cli.js /usr/local/bin/npx
+
+RUN npm install -g @zenera/cli @zenera/rag @google/genai

package/templates/.github/skills/zen-cli/SKILL.md

@@ -1,110 +0,0 @@
----
-name: zen-cli
-description: How to drive this project from the terminal with `zen` — running it, validating it, credentials, the sandbox and run reports.
----
-
-# The `zen` command line
-
-Everything here operates on a project directory. The project is resolved from
-the working directory, or by name from the registry `zen init` wrote to, or
-explicitly with `--project <name|dir>`. Every command takes `--json` and prints
-a machine-readable answer instead of a rendered one.
-
-## Running
-
-```
-zen run [project] [prompt] [options]
-```
-
-On a terminal with no prompt it opens the TUI; with a prompt, or without a tty,
-it answers once on stdout. The first word is the project when it names one, and
-the first word of the prompt when it does not — `--project` settles it.
-
-| Flag                    | What it does                                 |
-| ----------------------- | -------------------------------------------- |
-| `--project <name\|dir>` | Which project. Inferred from the directory   |
-| `--session <id>`        | Continue a particular session                |
-| `--new`                 | Start a fresh one                            |
-| `--workspace <dir>`     | What the agent may read and write            |
-| `--model <ref>`         | Override the default model for this run      |
-| `--image <ref>`         | Override the container commands run in       |
-| `--read-only`           | Withhold every tool that can write           |
-| `--quiet`               | The answer only; no narration                |
-| `--plain`               | One shot, even on a terminal                 |
-| `--out <file>`          | Write the answer to a file as well as stdout |
-| `--yes`                 | Accept the questions it would otherwise ask  |
-
-Flags always win over the file: the repository states intent, the invocation
-overrides it. There is no `resume` — a session continues itself, because its
-state is what it is.
-
-With a prompt on the command line nothing is asked: a fresh session, the current
-directory as the workspace, writable.
-
-## Validating
-
-```
-zen check [dir] [--strict] [--quiet]     everything agents.yaml names
-zen models [--project <name|dir>]         providers, models and embeddings resolved
-```
-
-`zen check` reads the project the way `zen run` does and reports in full without
-calling a model — a missing prompt file, an unknown tool, a handoff to nobody, a
-model alias on an undeclared provider. `zen models` answers the narrower
-question of what each agent would actually talk to, and which credential it
-needs. Run `zen check` after any edit to `agents.yaml`, a prompt or a skill; it
-is the cheapest possible test.
-
-## Credentials
-
-```
-zen key ls [--check]              what is on the keyring, and whether it works
-zen key add <provider>[/name]     add one — never on the command line
-zen key use <provider>/<name>     choose the active key for a provider
-zen key check [provider[/name]]   a round trip per key
-zen key show <provider>[/name]    masked, or --reveal for the secret itself
-zen key rm <provider>/<name>      forget it
-zen key env [provider …]          `eval "$(zen key env)"` for other tools
-```
-
-The secret never comes from argv — a command line lands in `ps`, in shell
-history and in CI logs. `zen key add` takes it from piped stdin or an echo-off
-prompt, and nowhere else. Real environment variables win over the keyring, so
-`.env` still decides inside a run.
-
-## The sandbox
-
-```
-zen sandbox status    is a container runtime there, is the image pulled
-zen sandbox up        start it
-zen sandbox pull      fetch the image ahead of the first run
-zen sandbox clean     throw away persisted containers
-```
-
-Shell commands run in a container over the session workspace, not on the host.
-If runs begin by installing a toolchain, set `sandbox.image` to one that already
-has it, or `sandbox.persist: true`, rather than paying for it every run.
-
-## Reports and sessions
-
-```
-zen list [--sessions] [--prune]                       every known project
-zen inspect [run] [--session <id>] [--open] [--serve]  a run's report.html
-zen open [project] [--editor <cmd>] [--wait]           open it in an editor
-zen version                                            CLI, library and Node
-```
-
-`zen inspect` renders the trajectory of a run — every message, tool call, skill
-activation and handoff, in order, with what each one cost. It is the first place
-to look when behaviour is wrong and the prompt looks right: it shows what the
-model was actually given, which is rarely what you assumed.
-
-Sessions live under `sessions/` and hold run state, memory, blobs and whatever
-the agent wrote. None of it is source and none of it is committed.
-
-## Exit codes
-
-Non-zero on failure, with the offending key or file named in the message. A load
-error names the exact path — `agents.yaml: agents[1].skills.discovery — …` — so
-read it rather than guessing; the loader is strict on purpose and an unknown key
-is an error, not a value quietly ignored.