Skip to content
Merged
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
88 changes: 88 additions & 0 deletions .github/workflows/ci.yml
Original file line number Diff line number Diff line change
Expand Up @@ -219,6 +219,94 @@ jobs:
shell: bash
run: eng/prove-adoption-path.sh artifacts/packages

# Story 29.3: the self-contained aexp binaries, the path that needs no .NET. eng/publish-binaries.sh builds the five
# of them (linux-x64, linux-arm64, osx-arm64, osx-x64, win-x64) from a locked restore of the binaries' own lock file,
# with the same script release.yml runs on a tag, and uploads them with their SHA256SUMS for the job below. The tool
# package is untouched: the pack job above proves that. NOT published.
binaries:
needs: build-and-test
runs-on: ubuntu-24.04
timeout-minutes: 20
steps:
- name: Checkout
uses: actions/checkout@v5

# Local development may roll forward (global.json: latestFeature). CI may not: the runner image ships
# newer SDK bands, which would otherwise win. Disabling roll-forward here makes setup-dotnet install,
# and the host select, exactly the pinned SDK. The working copy is the runner's; nothing is committed.
- name: Pin the SDK exactly (CI only)
run: |
sed -i -E 's/"rollForward": *"[^"]*"/"rollForward": "disable"/' global.json
grep -q '"rollForward": "disable"' global.json

# Exactly global.json's SDK (asserted below). It carries the net10.0 runtime every project targets, so nothing
# else is installed.
- name: Setup .NET
uses: actions/setup-dotnet@v5
with:
global-json-file: global.json
cache: true
cache-dependency-path: '**/packages.lock.json'

# Belt and braces after the pin above: a different SDK fails here instead of silently winning.
- name: Assert the exact pinned SDK
run: |
pinned="$(sed -nE 's/.*"version": *"([^"]+)".*/\1/p' global.json)"
actual="$(dotnet --version)"
test "$actual" = "$pinned" || { echo "::error::SDK $actual is in use, but global.json pins $pinned"; exit 1; }
echo "SDK $actual, as pinned"

- name: Build the self-contained binaries
run: eng/publish-binaries.sh artifacts/binaries

- name: Upload the binaries (for the adoption-path-binary job, never published from here)
uses: actions/upload-artifact@v4
with:
name: binaries
path: artifacts/binaries/
retention-days: 14

# Story 29.3: each binary proven on its own hardware, with no .NET installed (no setup-dotnet: the runner has only
# what a stranger's machine has). The leg runs the install script a stranger runs, scripts/install-aexp.sh, against
# the binaries job's artifact as a local download base (never the network), first on a copy with a corrupted sum
# (which must install nothing), then for real; then eng/prove-adoption-path.sh's checks: init, trust, a failed and a
# verified run, recall, lessons, benefit. AEXP_EXPECT_RUNTIME makes the leg assert it got the binary for its runtime.
# The five legs are required status checks on main.
adoption-path-binary:
needs: binaries
runs-on: ${{ matrix.os }}
strategy:
fail-fast: false
matrix:
include:
- os: ubuntu-24.04
runtime: linux-x64
- os: ubuntu-24.04-arm
runtime: linux-arm64
- os: macos-15
runtime: osx-arm64
- os: macos-15-intel
runtime: osx-x64
- os: windows-2025
runtime: win-x64
name: adoption-path-binary (${{ matrix.runtime }})
timeout-minutes: 15
steps:
- name: Checkout
uses: actions/checkout@v5

- name: Download the binaries the binaries job built
uses: actions/download-artifact@v4
with:
name: binaries
path: artifacts/binaries

- name: Install aexp through the install script and prove the adoption path
shell: bash
env:
AEXP_EXPECT_RUNTIME: ${{ matrix.runtime }}
run: eng/prove-adoption-path.sh --binaries artifacts/binaries

# The PostgreSQL matrix (story 6.3, KL-13): the storage suites, the pgvector proof, the sample's PostgreSQL
# mode and the upgrades from the published previews' databases (story 12.1), on every supported major. One
# variable picks both the pgvector image and the stock one, and each suite asserts the server it reached reports
Expand Down
86 changes: 80 additions & 6 deletions .github/workflows/release.yml
Original file line number Diff line number Diff line change
Expand Up @@ -3,9 +3,10 @@ name: Release
# The one workflow in this repository that may publish (RELEASING.md step 10). A maintainer starts it by pushing a
# version tag, and nothing else can: no branch push, pull request, schedule or manual dispatch. One tag releases all
# three languages at one version, from one verified commit. The verify job re-runs the release checks on the tagged
# commit and uploads what it verified: the eight NuGet packages, and the Python sdist and wheel. After a reviewer
# approves the `nuget-release` environment, the publish job pushes exactly those NuGet files to nuget.org, then tags
# the six Go modules at the tagged commit and creates the GitHub release. After a reviewer approves the
# commit and uploads what it verified: the eight NuGet packages, the five self-contained aexp binaries with their
# SHA256SUMS (story 29.3), and the Python sdist and wheel. After a reviewer approves the `nuget-release` environment,
# the publish job pushes exactly those NuGet files to nuget.org, then tags the six Go modules at the tagged commit and
# creates the GitHub release with the binaries attached. After a reviewer approves the
# `pypi-release` environment, the publish-pypi job uploads exactly the verified Python files to PyPI.
#
# No API key or token is stored anywhere. The publish job exchanges its GitHub OIDC token for a short-lived nuget.org
Expand Down Expand Up @@ -255,6 +256,50 @@ jobs:
- name: Verify the packages
run: dotnet run eng/verify-packages.cs -- artifacts/packages

# Story 29.3: the self-contained aexp binaries, built by the script ci.yml runs on every pull request, from a
# locked restore of the binaries' own lock file. The tool package packed above is unaffected.
- name: Build the self-contained binaries
run: eng/publish-binaries.sh artifacts/binaries

# Exactly the five binaries and their sums, the sums right, and the Linux x64 one (this runner's) carrying the
# tagged version. The other four are proven on their own hardware by ci.yml's adoption-path-binary legs on main.
- name: Check the binaries
env:
VERSION: ${{ steps.version.outputs.version }}
run: |
set -euo pipefail
ls -l artifacts/binaries
for file in aexp-linux-x64 aexp-linux-arm64 aexp-osx-arm64 aexp-osx-x64 aexp-win-x64.exe SHA256SUMS; do
test -f "artifacts/binaries/$file" || { echo "::error::artifacts/binaries has no $file"; exit 1; }
done
test "$(find artifacts/binaries -type f | wc -l)" -eq 6 || { echo "::error::artifacts/binaries must hold exactly six files"; exit 1; }
(cd artifacts/binaries && sha256sum --check --strict SHA256SUMS)
printed="$(artifacts/binaries/aexp-linux-x64 --version)"
test "$printed" = "$VERSION" || { echo "::error::aexp-linux-x64 --version prints '$printed', not $VERSION"; exit 1; }
echo "aexp $printed: five binaries and SHA256SUMS OK"

# The release page quotes the sums, so a person can check a download against the notes as well as against the
# SHA256SUMS asset, and leads with the install script.
- name: Add the binaries to the release notes
run: |
set -euo pipefail
{
echo
echo "## Binaries"
echo
echo "Self-contained \`aexp\` for Linux (x64, arm64), macOS (Apple silicon, Intel) and Windows (x64): no .NET needed. Install the one for this machine, its SHA-256 sum checked:"
echo
echo '```bash'
echo "curl -fsSL https://raw.githubusercontent.com/fabbrik/AgentExperience.NET/main/scripts/install-aexp.sh | sh"
echo '```'
echo
echo "SHA-256 sums of the attached binaries (\`SHA256SUMS\`):"
echo
echo '```'
cat artifacts/binaries/SHA256SUMS
echo '```'
} >> artifacts/release-notes/notes.md

# The Python distribution (python/). uv is pinned to one release, with its checksum, and nothing is cached: a
# release restores from the lock file alone.
- name: Setup uv and Python
Expand Down Expand Up @@ -357,6 +402,14 @@ jobs:
if-no-files-found: error
retention-days: 30

- name: Upload the binaries
uses: actions/upload-artifact@v4
with:
name: binaries
path: artifacts/binaries/
if-no-files-found: error
retention-days: 30

# Kept for 90 days, the most GitHub allows: re-running publish-pypi needs it (RELEASING.md).
- name: Upload the verified Python distribution
uses: actions/upload-artifact@v4
Expand Down Expand Up @@ -392,6 +445,24 @@ jobs:
name: release-notes
path: artifacts/release-notes

- name: Download the binaries
uses: actions/download-artifact@d3f86a106a0bac45b974a628896c90dbdf5c8093 # v4.3.0
with:
name: binaries
path: artifacts/binaries

# The five binaries and SHA256SUMS verify built, and nothing else, with their sums checked again here, just
# before they are attached to the release (as the Python distribution's are before its upload).
- name: Check the binaries are the tagged version
run: |
set -euo pipefail
ls -l artifacts/binaries
for file in aexp-linux-x64 aexp-linux-arm64 aexp-osx-arm64 aexp-osx-x64 aexp-win-x64.exe SHA256SUMS; do
test -f "artifacts/binaries/$file" || { echo "::error::artifacts/binaries has no $file"; exit 1; }
done
test "$(find artifacts/binaries -type f | wc -l)" -eq 6 || { echo "::error::artifacts/binaries must hold exactly six files"; exit 1; }
(cd artifacts/binaries && sha256sum --check --strict SHA256SUMS)

# Eight packages and eight symbol packages, all at the version the tag names, and nothing else.
- name: Check the packages are the tagged version
env:
Expand Down Expand Up @@ -487,7 +558,9 @@ jobs:
exit 1
done

# Only after the push and the Go tags. An existing release (a re-run) is left untouched.
# Only after the push and the Go tags, with the five binaries and SHA256SUMS attached. An existing release (a
# re-run) keeps its notes and gets its assets completed: the checked binaries are uploaded again, replacing any
# of the same name (story 29.3).
- name: Create the GitHub release
env:
GH_TOKEN: ${{ github.token }}
Expand All @@ -498,13 +571,14 @@ jobs:
run: |
set -euo pipefail
if gh release view "$TAG" > /dev/null 2>&1; then
echo "The GitHub release $TAG already exists; leaving it as it is."
echo "The GitHub release $TAG already exists; completing its assets and leaving the rest as it is."
gh release upload "$TAG" artifacts/binaries/* --clobber
exit 0
fi
flags=()
if [ "$PRERELEASE" = "true" ]; then flags+=(--prerelease); fi
gh release create "$TAG" --verify-tag --title "AgentExperience.NET $VERSION" \
--notes-file artifacts/release-notes/notes.md "${flags[@]}"
--notes-file artifacts/release-notes/notes.md "${flags[@]}" artifacts/binaries/*

# Uploads exactly the Python files verify built and checked, through PyPI Trusted Publishing: the action exchanges
# the job's GitHub OIDC token for a short-lived PyPI token, under a publisher on pypi.org that names this repository,
Expand Down
9 changes: 9 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -28,6 +28,15 @@ AgentExperience.NET is a **preview**. It is not production ready, and public API
the `.nupkg` packed for the same commit, runs `init` and `trust` on a scratch project, finalizes a failed and a
verified run, and asserts that `recall`, `lessons` and `benefit` report the lesson; the three `adoption-path` legs
gate every pull request.
- **`aexp` without the .NET SDK.** Every release now attaches self-contained, single-file `aexp` binaries for
linux-x64, linux-arm64, osx-arm64, osx-x64 and win-x64 with a `SHA256SUMS` file (sums quoted in the release notes),
built by `eng/publish-binaries.sh` from a locked restore; the tool package is unchanged. The install script
`scripts/install-aexp.sh` (`curl -fsSL https://raw.githubusercontent.com/fabbrik/AgentExperience.NET/main/scripts/install-aexp.sh | sh`)
picks the binary for the machine, checks its SHA-256 sum against `SHA256SUMS` (installing nothing on a mismatch) and
puts it on PATH; `AEXP_VERSION` pins a release and `AEXP_INSTALL_DIR` the directory. CI builds the same binaries on
every pull request and proves each on its own hardware with no .NET installed (`adoption-path-binary`, five legs:
the install script against the artifact, a corrupted sum refused, then the adoption-path checks). The README leads
with this path. See [CLI and MCP](docs/guide/cli-and-mcp.md#install).

### Changed

Expand Down
5 changes: 4 additions & 1 deletion CONTRIBUTING.md
Original file line number Diff line number Diff line change
Expand Up @@ -126,7 +126,10 @@ _sdlc/ product brief, PRD, architecture, ep
- Make sure `dotnet build` and `dotnet test` pass locally. CI (`.github/workflows/ci.yml`) runs on every pull request:
`build-and-test`, `pack` (with package verification), `adoption-path (ubuntu-24.04, macos-15, windows-2025)` (installs
`aexp` from the packed artifact on each OS and runs `eng/prove-adoption-path.sh`: init, trust, a failed and a
verified run, recall, lessons, benefit), the `postgres` matrix (15 to 18, plaintext and
verified run, recall, lessons, benefit), `binaries` (builds the five self-contained `aexp` binaries with
`eng/publish-binaries.sh`) and `adoption-path-binary (linux-x64, linux-arm64, osx-arm64, osx-x64, win-x64)` (each
binary on its own hardware with no .NET installed: `scripts/install-aexp.sh` against the artifact, a corrupted sum
refused, then the same proof), the `postgres` matrix (15 to 18, plaintext and
crypto-shredding), the MAF floor (`maf-compatibility (pinned)`), the Python port's `python` matrix (CPython 3.10 to
3.14, plus its PostgreSQL 16 and 18 legs; [python/README.md](python/README.md#running-the-tests) says how to run it
locally) and the Go port's `go` matrix (the core on Go 1.24, the stores from 1.25, and the Agent Framework
Expand Down
11 changes: 7 additions & 4 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -61,17 +61,20 @@ await agent.RunAsync("Ticket #4977: a refund is stuck on a lock again. Triage it

## Any agent: CLI and MCP

Agents outside the Agent Framework (Claude Code, Codex, Cursor, a script) get the same loop through `aexp`, a .NET tool
that is both a command line and an MCP stdio server, over a local SQLite file by default (published from the next
preview, `0.1.0-preview.19`; until then, [build it from this repository](dogfood/README.md)):
Agents outside the Agent Framework (Claude Code, Codex, Cursor, a script) get the same loop through `aexp`, one
command that is both a command line and an MCP stdio server, over a local SQLite file by default. No .NET needed: the
install script puts a self-contained binary for Linux, macOS or Windows on your PATH, its SHA-256 checked against the
release (the binaries ship with every release from the first one after this change):

```bash
dotnet tool install --global AgentExperience.Cli --prerelease
curl -fsSL https://raw.githubusercontent.com/fabbrik/AgentExperience.NET/main/scripts/install-aexp.sh | sh
aexp init # in the project root: detects the test command, writes .aexp/config.json
aexp trust # after you reviewed the config: a person's step
claude mcp add aexp -- aexp mcp # or any MCP client: the server is `aexp mcp`, run in the project
```

With the .NET 10 SDK, the same command is also a .NET tool: `dotnet tool install --global AgentExperience.Cli --prerelease`.

`.aexp/config.json` names the scope and the one command `aexp` may run, the verifier
(`"verify": { "command": ["dotnet", "test"] }`, exit code 0 = pass), which runs only once a person has reviewed the
config and approved it with `aexp trust` (an edit revokes the approval). The MCP tools `experience_recall`,
Expand Down
Loading
Loading