@oxy-hq/cli 0.8.0 → 0.9.0

package/README.md

@@ -159,8 +159,23 @@ oxyc tokens revoke <id>
 oxyc tokens revoke --current   # end the token in OXY_TOKEN
 oxyc tokens create          # opens Account → Personal access tokens
 oxyc tokens create --sandbox-agent --app <org>/<app> [--app …] [--hours 8] [--name …]
+oxyc tokens create --agent [--standing] [--hours 8] [--name …]
 ```
 
+**An agent runs on its own token, never on the person's `oxyc login`.** Which
+one depends on the task:
+
+| The agent is… | It mints | Which reaches |
+| --- | --- | --- |
+| building a custom app in a sandbox | `tokens create --sandbox-agent --app …` (`oxy_sbx_…`) | the sandboxes of the apps it names, and nothing else |
+| doing anything else: reading data with `oxyc api`, reproducing a bug against live data | `tokens create --agent` (`oxy_pat_…`) | everything its approver can, for hours |
+
+Both are approved once in the browser by the person the agent works for, both
+are printed once as `export OXY_TOKEN=…` and never stored, and both end with
+`tokens revoke --current`. After a mint, pass `--token-env OXY_TOKEN` to every
+command: a named variable is the only source, so a command that lost the
+variable exits `4` instead of quietly running on the person's cached login.
+
 **Every command resolves its credential the same way, first match wins:**
 
 1. **`OXY_TOKEN`** (or the variable `--token-env` names). It holds any
@@ -168,7 +183,8 @@ oxyc tokens create --sandbox-agent --app <org>/<app> [--app …] [--hours 8] [--
    token (`oxy_pat_…`), a service account token (`oxy_sat_…`), a CI token
    (`oxy_ci_…`) or a sandbox agent token (`oxy_sbx_…`) — a legacy API key
    (`oxy_…`), a publish token, or a session token. A blank value counts as
-   unset.
+   unset. An agent token is a personal access token by its prefix: only its
+   own description tells it from a login (`oxyc whoami`).
 2. **The login cache** — what `oxyc login` stored for this deployment.
 3. **GitHub OIDC**, in a GitHub Actions job granted `id-token: write`: the job's
    OIDC token is exchanged, once per process, for a fifteen-minute token acting
@@ -196,7 +212,7 @@ Settings → Workspace → Legacy API keys. Use an API token for anything new.
 
 **`login`** runs a browser loopback flow. Against a current deployment it
 receives a one-time code and exchanges it (PKCE) for a **personal access
-token** named `oxyc on <hostname>`: revocable, ninety days, and replacing that
+token** named `oxyc on <hostname>`: revocable, a year, and replacing that
 machine's previous one. No credential travels in a URL. Against a deployment
 that predates the exchange it stores the session token the page hands back,
 exactly as before, and says so — nothing needs upgrading first, in either
@@ -212,7 +228,10 @@ rather than reading as fine from the cache. For a token it also prints what the
 token is and what it can reach — `all access`, or one line per grant with the
 role it is capped at, and any organization whose policy blocks it. For a legacy
 API key it prints `Legacy API key`, and that it reaches everything its owner
-can.
+can. For an agent token it says `agent token`, who approved it, whether it
+carries their staff or partner access, and when it expires. When a token in
+`OXY_TOKEN` is refused (exit `4`), the advice is never to log in — a login
+cannot replace what is in the variable. An agent stops and reports.
 
 **`token`** prints the bearer on stdout and nothing else. Inside a GitHub
 Actions job with nothing stored it prints the token the job's OIDC identity
@@ -276,6 +295,35 @@ A refusal from the server carries a hint an agent can act on — never "try
 `oxyc login` again". Exit `4` under this token means it expired, was revoked,
 or its minter lost access: stop and report.
 
+**`tokens create --agent`** mints an **agent token** for everything that is not
+a sandbox: a personal access token (`oxy_pat_…`) that reaches what its approver
+reaches through their organization memberships, for 8 hours by default
+(`--hours`, 1 to 168). It cannot be extended, edited or regenerated, and it
+cannot create, extend or revoke tokens; it can open a browser session as itself
+(`login-link`).
+
+```bash
+eval "$(oxyc tokens create --agent --env dev)"
+```
+
+The same browser loopback again, with the same guarantees: stdout is the single
+line `export OXY_TOKEN=oxy_pat_…`, printed once, everything else is on stderr,
+it holds no credential while it runs, never writes the credentials file and
+revokes no other token. Arguments are checked before the browser opens (exit
+`2`); `--agent` and `--sandbox-agent` together are a usage error.
+
+`--standing` asks for the approver's staff or partner access as well. The
+approver decides on the page, where it starts **off**: a token that comes back
+without it is accepted, and stderr says so in one line. Without `--standing`, a
+token that carries either is refused.
+
+What comes back is checked before anything is printed: it must be a whole
+`oxy_pat_`; it must describe itself (`GET /api/auth/token`) as `personal` with
+`source` `oxyc_agent`; it must expire no later than the hours asked for; and it
+must carry no standing that was not asked for. A deployment that predates agent
+tokens would otherwise hand back an ordinary ninety-day login. On any mismatch
+the command prints nothing, revokes what was minted, and exits `8`.
+
 Credentials live in the OS config directory under **`oxy`** — the same file the
 Rust `oxy login` wrote before it was removed, so an existing login still works:
 
@@ -548,7 +596,15 @@ lets it publish.
 *The workflow* is `.github/workflows/oxy-publish.yml` at the repo root: a
 `build` job (no id-token) that runs `publish --build-only`, and a `publish` job
 bound to a GitHub `environment:` (`--environment`, default `oxy-publish`) whose
-only work is `publish --prebuilt`. That job uses no third-party action: each
+only work is `publish --prebuilt`. `build` installs pnpm with
+`pnpm/action-setup@v6` — the pnpm the repo root's package.json pins
+(`packageManager` or `devEngines.packageManager`), with no `version:` of its
+own, since the action refuses a second, different one; pnpm 11 when nothing
+pins it — and both jobs run the Node in `.nvmrc`, else 26 (pnpm 11 needs
+Node 22.13 or later). It warns when nothing pins pnpm, and when
+`pnpm-workspace.yaml` approves build scripts only with `onlyBuiltDependencies`,
+which pnpm 11 ignores (the build's install would fail with
+`ERR_PNPM_IGNORED_BUILDS`; move the entries to `allowBuilds`). The publish job uses no third-party action: each
 step runs `npx @oxy-hq/cli@<this version>` and `oxyc` exchanges the job's OIDC
 token for itself, acting as the service account `--service-account <org>/<name>`
 names — by default `<app's org>/deployer`. **Here, and only here, the account is
@@ -705,6 +761,26 @@ object to stdout instead:
 { "app": "acme/dashboards", "appId": "…", "checks": [{ "name": "canary", "runId": "…", "status": "done", "passed": true, "durationMs": 4123 }] }
 ```
 
+**`--browser`** also loads the app's page in headless Chromium and proves it
+mounted: the platform runtime's `oxy-app-ready` beacon fires, nothing on the
+page throws, and `--expect-selector <css>` (optional) becomes visible. With
+`--app-env` the page must also report that environment and the build it serves
+(`oxyc env show`'s `build_uuid`) in `window.__OXY_APP__`. The credential and
+`X-Oxy-App-Env` ride only on requests under the app's own base path
+(`/customer-apps/<org>/<app>/`: the document, assets, beacon and `/fn` calls).
+The rest of the deployment's API is on the same origin, and the code under test
+is often a build someone else published, so its `/api/…` calls go without the
+credential, as an anonymous visitor's would. The result is one more entry in `checks[]`, with `"kind": "browser"` and
+the `/fn` calls the page made. Playwright is not a dependency: it is resolved
+from the working directory (`playwright`, `playwright-core` or
+`@playwright/test`), so run it where one is installed. The page loads as a
+user, so a publish, service-account, CI or sandbox agent token is refused
+before any request.
+
+```bash
+oxyc checks run acme/store --app-env dev-a1 --browser --expect-selector 'main'
+```
+
 **Auth** follows the same rule as `oxyc api`'s bearer surface, with one
 difference: `checks run` talks to `/api/admin/**`, which is not the
 `/external/api/*` surface, so a configured API key is sent explicitly as
@@ -1021,9 +1097,12 @@ them, and a tool that can only fail still costs its schema every turn. A dead
 token ends the server at startup with exit `4`.
 
 **`guide`** prints a page to paste into `AGENTS.md` / `CLAUDE.md`.
-**`skills install`** symlinks the six bundled Claude skills into
+**`skills install`** symlinks the bundled Oxy platform skills into
 `~/.claude/skills`; it refuses to run from an `npx` cache, whose symlinks dangle
-once npm reclaims it.
+once npm reclaims it. The same skills are published to
+[`oxy-hq/skills`](https://github.com/oxy-hq/skills) for every other agent —
+`npx skills add oxy-hq/skills`, or the Claude Code plugin `oxy@oxy-hq`. They are
+written in `skills/` here; see `internal-docs/platform-skills.md`.
 
 ## Exit codes
 
@@ -1039,7 +1118,10 @@ once npm reclaims it.
 9  a check ran and failed or timed out (`oxyc checks run`)
 ```
 
-`4` almost always means the wrong `--env`. `7` is worth retrying; `6` never is.
+`4` almost always means the wrong `--env`. A person logs in again. An agent on
+its own token (`tokens create --agent` or `--sandbox-agent`) does not: there,
+`4` means the token expired or was revoked, and the agent stops and reports.
+`7` is worth retrying; `6` never is.
 
 ## Environment variables