Skip to content
Closed
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 3 additions & 3 deletions docs/automations.md
Original file line number Diff line number Diff line change
Expand Up @@ -10,7 +10,7 @@ rocm-cli automations are local watcher events routed through explicit watcher
policy. A webhook payload is an event input, not an execution API: it cannot
grant a new action, choose a tool, override watcher mode, or run shell.

## Local Webhook Source
## Local webhook source

Start the persistent watcher loop with a loopback-only webhook source:

Expand Down Expand Up @@ -58,7 +58,7 @@ The listener only binds to `127.0.0.1`. There is no LAN or cloud webhook
listener, and local webhook events still dispatch through the configured
`observe`, `propose`, or `contained` policy for the target watcher.

## Restricted Tool API
## Restricted tool API

Automation actions never receive arbitrary shell access. Reviewed requests and
contained watcher work can only call this restricted tool surface:
Expand Down Expand Up @@ -163,7 +163,7 @@ Invoke-RestMethod `
http://127.0.0.1:18080/automation-events
```

## Artifact Prefetch Action
## Artifact prefetch action

The reviewed artifact-prefetch action keeps downloads disabled unless the caller
explicitly approves a source policy:
Expand Down
44 changes: 22 additions & 22 deletions docs/ci-hardware-testing.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,7 @@ Copyright © Advanced Micro Devices, Inc., or its affiliates.
SPDX-License-Identifier: MIT
-->

# CI hardware (GPU / WSL) testing
# CI hardware (GPU and WSL) testing

The hosted CI (`ubuntu-latest`, `windows-latest`) builds and unit-tests every
shipping target natively, but GitHub-hosted runners have no AMD GPU. A
Expand All @@ -16,8 +16,8 @@ separate from the main `ci.yml`. The split is deliberate: a job queued on an
**offline** self-hosted runner cannot be cancelled by GitHub, so if it shared
`ci.yml`'s concurrency group a superseded run would hold that group and the
newer run's merge-required (GitHub-hosted) checks would sit pending forever
(observed on PR #138). Giving the self-hosted lanes their own workflow — and
thus their own concurrency group — means an offline runner can only ever stall
(observed on PR #138). Giving the self-hosted lanes their own workflow, and
thus their own concurrency group, means an offline runner can only ever stall
that workflow's own supersession, never `ci.yml`'s required checks. See
`EAI-7548`.

Expand All @@ -26,7 +26,7 @@ that workflow's own supersession, never `ci.yml`'s required checks. See
The E2E suite (BDD scenarios in Gherkin `.feature` files backed by Rust step
functions) runs as one job per platform. Each job's harness resolves every
scenario to pass / xfail / skip for that host from its `@id` and
`@requires-*` tags, a capability probe, and `expectations.toml` — there is no
`@requires-*` tags, a capability probe, and `expectations.toml`; there is no
separate tier flag or tag filter to maintain.

| Job | Workflow | Platform | Runner labels |
Expand Down Expand Up @@ -72,8 +72,8 @@ workspace; the lane installs them itself where it has passwordless sudo, and
otherwise fails with the list of what is missing rather than hanging on a
password prompt.

GPU coverage additionally needs ROCm's WSL passthrough to be complete —
`/dev/dxg` and dxcore alone are not enough, `librocdxg.so` and its ldconfig
GPU coverage additionally needs ROCm's WSL passthrough to be complete:
`/dev/dxg` and dxcore alone are not enough; `librocdxg.so` and its ldconfig
entry must be present too. `rocm examine` reports the verdict as
`driver_status: wsl_rocdxg_ready`; anything else (`wsl_rocdxg_missing`,
`wsl_gpu_plumbing_missing`) means the runtime cannot reach the device even
Expand All @@ -88,13 +88,13 @@ covers the mock platform;
`e2e-selfhosted.yml`'s `e2e-report` covers the GPU platforms;
`nightly.yml`'s `e2e-report-nightly` covers the same platforms with the
`@nightly` scenarios included. Each joins its platforms'
reports — including partial or failed runs — by scenario id into one HTML report
reports, including partial or failed runs, by scenario id into one HTML report
and GitHub step summary.

The lane artifacts are named canonically (`e2e-report`, `e2e-gpu-report`,
`e2e-gpu-rad3-report`, `e2e-gpu-strix-ubuntu-report`, `e2e-gpu-strix-windows-report`,
`e2e-gpu-strix-wsl-report`) in every workflow, because the report derives each
platform's name and OS from the artifact name. An unrecognised name renders as a
platform's name and OS from the artifact name. An unrecognized name renders as a
guessed platform on Linux, which would report a Windows lane as Linux; `xtask`'s
`every_uploaded_e2e_artifact_has_a_name_the_report_can_label` guards against it.

Expand All @@ -103,15 +103,15 @@ guessed platform on Linux, which would report a Windows lane as Linux; `xtask`'s
The GPU jobs (in `e2e-selfhosted.yml`) run automatically on `push`,
`pull_request`, and `merge_group` when the workflow's own `changes` job's
`serve` path filter is `true`. `serve` is narrower than `heavy`: it matches only
paths that can change serve *behaviour* or the GPU E2E harness (the engines, the
paths that can change serve *behavior* or the GPU E2E harness (the engines, the
serve code path in `apps/rocm`/`apps/rocmd`, `rocm-core`, the e2e-cucumber crate,
plus broad-dependency safety nets), **not** a blanket `**/*.rs`. So a Rust change
that cannot affect serving — e.g. a dashboard-only or unrelated-crate PR — skips
that cannot affect serving (for example, a dashboard-only or unrelated-crate PR) skips
the heavy GPU matrix, while compile coverage for every crate still runs on
`ci.yml`'s always-on build/test lanes. Off `pull_request` (push/merge_group) the
filter is forced `true`, so the full matrix always runs there. Unlike the
pre-split layout the GPU jobs do **not** gate on the hosted `build-and-test` job
— cross-workflow `needs` is not possible, so each GPU job builds the `rocm`
(cross-workflow `needs` is not possible), so each GPU job builds the `rocm`
binary itself as its first real step (a broken build fails that job fast and
non-fatally). `ci.yml`'s required `build-and-test` and mock `e2e` remain the
authoritative pre-merge build gate.
Expand All @@ -120,16 +120,16 @@ They can also be triggered manually via `e2e-selfhosted.yml`'s
`workflow_dispatch`, independent of the `serve` gate, with these inputs:

- `platform` (choice: `all`, `app-dev-gpu`, `strix-ubuntu`, `strix-windows`,
`strix-wsl`, `rad3`) — which self-hosted job(s) to run. `app-dev-gpu` maps to
`strix-wsl`, `rad3`): which self-hosted job(s) to run. `app-dev-gpu` maps to
`e2e-gpu`, `strix-ubuntu` to `e2e-gpu-strix-ubuntu`, `strix-windows` to
`e2e-gpu-strix-windows`, `strix-wsl` to `e2e-wsl`, and `rad3` to
`e2e-gpu-rad3`. (The mock lane has its own `platform` input on `ci.yml`; it is
not part of this workflow.)
- `name_filter` (string) — a scenario-name regex forwarded to the cucumber
- `name_filter` (string): a scenario-name regex forwarded to the cucumber
harness (`cargo xtask e2e -- --name <regex>`) so a dispatch can run a
single scenario instead of the full suite. Empty runs everything applicable
to the selected platform(s).
- `include_nightly` (boolean, default `false`) — opts a dispatch into
- `include_nightly` (boolean, default `false`): opts a dispatch into
`@nightly`-tagged scenarios (e.g. large-model serves, cold installs) that
are otherwise skipped on a normal push/PR run to keep it fast.

Expand Down Expand Up @@ -178,14 +178,14 @@ the pre-warm block is duplicated across multiple jobs in two shells;

## Blocking vs. non-blocking

The self-hosted jobs — `e2e-gpu`, `e2e-gpu-strix-ubuntu`,
`e2e-gpu-strix-windows`, `e2e-wsl`, and `e2e-gpu-rad3` — all run with `continue-on-error: true`, so a
The self-hosted jobs (`e2e-gpu`, `e2e-gpu-strix-ubuntu`,
`e2e-gpu-strix-windows`, `e2e-wsl`, and `e2e-gpu-rad3`) all run with `continue-on-error: true`, so a
hardware failure that RUNS never gates a PR merge. Their results still surface
in the self-hosted consolidated report for visibility.

### Timeouts on the shared Strix box

Three of those lanes — the two native Strix ones and `e2e-wsl` — run on the same
Three of those lanes (the two native Strix ones and `e2e-wsl`) run on the same
physical machine and can be in flight together, so a wait that is comfortable on
an idle runner can expire while a sibling lane loads a model. Two budgets are
raised there rather than letting contention read as a product failure:
Expand All @@ -196,12 +196,12 @@ genuine hang still fails, just later.
**Required-check caveat.** These three job names (plus, historically, a
consolidated-report name) are still in `main`'s required-status-check list.
`continue-on-error` neutralizes a job that ran and failed, but a required check
that *never reports* — because its self-hosted runner is offline — is treated as
that *never reports* (because its self-hosted runner is offline) is treated as
missing and still blocks the merge. The workflow split removes the catastrophic
concurrency stall (an offline runner can no longer freeze `ci.yml`'s hosted
required checks), but fully unblocking merges while a runner is offline
additionally requires removing these self-hosted checks from the required list —
a branch-protection change tracked separately from the workflow split.
additionally requires removing these self-hosted checks from the required list
(a branch-protection change tracked separately from the workflow split).

## Fork safety

Expand All @@ -218,8 +218,8 @@ which requires write access to trigger).
not performance, so this is not a performance benchmark. Release-fidelity,
`manylinux2014` (glibc 2.17) packaging validation is handled separately by
the nightly/release pipeline.
- Each workflow's `e2e-report` job collects whatever ran in that workflow —
including partial results from a cancelled or failed job — and renders one
- Each workflow's `e2e-report` job collects whatever ran in that workflow,
including partial results from a cancelled or failed job, and renders one
HTML report plus a step summary. `download-artifact@v8` flattens a
single-match download straight into the artifacts directory (it uses the root
path when exactly one artifact matches, regardless of the pattern), so after
Expand Down
23 changes: 12 additions & 11 deletions docs/commit-signatures.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,20 +4,20 @@ Copyright © Advanced Micro Devices, Inc., or its affiliates.
SPDX-License-Identifier: MIT
-->

# Commit Signatures and Sign-off
# Commit signatures and sign-off

Every commit that lands in this repository must be:

1. **Cryptographically signed** — so authorship is verifiable and history
1. **Cryptographically signed**, so authorship is verifiable and history
cannot be silently forged or impersonated.
2. **Signed-off** — a DCO `Signed-off-by:` trailer, certifying you have the
2. **Signed-off**: a DCO `Signed-off-by:` trailer, certifying you have the
right to submit the change under the project license.

Both requirements are **enforced**, not advisory: local git hooks reject
non-conforming commits before they leave your machine, and a blocking CI gate
rejects them on every pull request.

## Setting Up Signing
## Setting up signing

You can sign with SSH (simplest if you already have an SSH key) or GPG.

Expand Down Expand Up @@ -50,7 +50,7 @@ To add sign-off to a range of existing commits:
git rebase --signoff <base>
```

## Registering Your Key on GitHub (required for CI)
## Registering your key on GitHub (required for CI)

CI uses **strict** verification: it asks GitHub whether each commit's signature
is `verified`. For GitHub to report a commit as **Verified** you must:
Expand All @@ -63,7 +63,7 @@ is `verified`. For GitHub to report a commit as **Verified** you must:
If either is missing, the signature exists but GitHub will not mark it
"Verified", and the CI gate will fail.

## How Enforcement Works
## How enforcement works

### Local hooks (prek)

Expand All @@ -74,10 +74,10 @@ prek install # pre-commit
prek install -t pre-push # pre-push
```

- **pre-commit**: `cargo xtask verify-commits --check-config` — a fast check
- **pre-commit**: `cargo xtask verify-commits --check-config`, a fast check
that commit signing is enabled (`commit.gpgsign`, in any of git's truthy
spellings) and `user.signingkey` is set, with remediation if not.
- **pre-push**: `cargo xtask verify-commits` — verifies every outgoing commit
- **pre-push**: `cargo xtask verify-commits`, which verifies every outgoing commit
in `origin/main..HEAD` is signed (signature present and not bad) and
signed-off. The base is fixed at `origin/main`, so keep it fetched
(`git fetch origin main`); on a branch targeting a different base, run the
Expand All @@ -96,13 +96,14 @@ cargo xtask verify-commits --base origin/<base-branch> --require-verified
CLI). The job checks out with `fetch-depth: 0` so the base ref and all PR
commits are available. On a `merge_group` event it verifies the queued commits
against the queue's base (`merge_group.base_sha..head_sha`) instead of a PR
base — so the check still runs in the queue and can safely be made *required*
base, so the check still runs in the queue and can safely be made *required*
without stalling it. Mark it as a required check in branch protection / your
repository ruleset so it blocks merges.

### The xtask check

`cargo xtask verify-commits` is the single source of truth for the logic:
`cargo xtask verify-commits` is the single source of truth for the logic. Its
flags are:

| Flag | Meaning |
| ------------------- | ---------------------------------------------------------------- |
Expand All @@ -112,7 +113,7 @@ repository ruleset so it blocks merges.

An empty commit range is treated as success.

## Native GitHub Ruleset (Complementary)
## Native GitHub ruleset (complementary)

GitHub can natively **require signed commits** via a repository ruleset. Enable
it as defense-in-depth alongside the in-repo check:
Expand Down
2 changes: 2 additions & 0 deletions docs/demos.md
Original file line number Diff line number Diff line change
Expand Up @@ -19,6 +19,8 @@ to source branches; the README references them by absolute raw URL.

## Layout

The demo pipeline uses these paths and jobs:

| Path | Purpose |
| --- | --- |
| `docs/tapes/cli.tape` | CLI first-use journey. |
Expand Down
8 changes: 4 additions & 4 deletions docs/engine-plugins.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,7 @@ Copyright © Advanced Micro Devices, Inc., or its affiliates.
SPDX-License-Identifier: MIT
-->

# Engine Plugins
# Engine plugins

rocm-cli discovers serving engine adapters as executable files.

Expand All @@ -15,10 +15,10 @@ Search order:
3. Packaged sibling binaries installed beside `rocm`

The first directory is the preferred location for external adapters. Use a
binary name in the form `rocm-engine-<engine>` on Linux/WSL and
binary name in the form `rocm-engine-<engine>` on Linux or WSL and
`rocm-engine-<engine>.exe` on Windows.

Packaged first-party adapters are `lemonade` and `vllm`. Linux/WSL-only ROCm GPU
Packaged first-party adapters are `lemonade` and `vllm`. Linux or WSL-only ROCm GPU
adapters (such as `vllm`) fail explicitly on native Windows instead of selecting
a CPU fallback.

Expand All @@ -35,7 +35,7 @@ unsupported. rocm-cli does not use a CPU fallback for this path.
## Pinned runtime versions

The versions of the third-party runtimes rocm-cli downloads are pinned in
`runtime-deps.toml` at the repository root — one `[runtime.<name>]` table per
`runtime-deps.toml` at the repository root: one `[runtime.<name>]` table per
runtime. That file is the only place a runtime version is written down:
archive names, download URLs, and the dashboard's offline fallback are all
derived from it, so a bump is a one-line edit and the tree cannot end up
Expand Down
18 changes: 10 additions & 8 deletions docs/llm-tool-use.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,11 +4,11 @@ Copyright © Advanced Micro Devices, Inc., or its affiliates.
SPDX-License-Identifier: MIT
-->

# LLM Tool Use
# LLM tool use

rocm-cli local assistants use structured tools, not shell commands.

## Design Rules
## Design rules

- The model chooses a tool call from a schema. rocm-cli validates the arguments
before anything runs.
Expand All @@ -28,15 +28,15 @@ rocm-cli local assistants use structured tools, not shell commands.
serving, but it should not switch its own built-in chat engine away from
Lemonade.
- On native Windows, vLLM live serving/install checks are skipped. The assistant
should direct those requests to WSL/Linux and should not suggest CPU fallback.
should direct those requests to WSL or Linux and should not suggest CPU fallback.

This follows the same shape described by current tool-use docs: the application
defines tool schemas, the model requests a tool, the application executes the
tool, and the result is returned to the model for the next response. MCP tool
annotations such as `readOnlyHint` and `destructiveHint` are useful UI hints,
but rocm-cli still enforces approval in code.

## Local Assistant Examples
## Local assistant examples

The assistant can inspect ComfyUI state:

Expand Down Expand Up @@ -104,8 +104,10 @@ tries to open the browser:
{"name":"rocm_command","arguments":{"args":["comfyui","start"]}}
```

## Sources
## Related documentation

- OpenAI Function Calling guide: https://platform.openai.com/docs/guides/function-calling
- Anthropic Tool Use guide: https://docs.anthropic.com/en/docs/agents-and-tools/tool-use/implement-tool-use
- Model Context Protocol tool annotations: https://modelcontextprotocol.io/specification/draft/schema#toolannotations
These upstream guides describe the tool-use patterns rocm-cli follows:

- [OpenAI function calling guide](https://platform.openai.com/docs/guides/function-calling)
- [Anthropic tool use guide](https://docs.anthropic.com/en/docs/agents-and-tools/tool-use/implement-tool-use)
- [Model Context Protocol tool annotations](https://modelcontextprotocol.io/specification/draft/schema#toolannotations)
Loading