From 9d6cca5e5f9854926be14b71b536a62136e7235b Mon Sep 17 00:00:00 2001 From: asher-aqi Date: Fri, 13 Nov 2026 23:02:17 -0600 Subject: [PATCH 1/3] build(python): package aqi-attend for its first PyPI release The Python package has never been published, so this is what its PyPI page and its files need: - The sdist holds the package source, the README, the license and pyproject.toml. The tests and the bench stay out: they read fixtures and TypeScript sources from the repo around python/, so they cannot run from an unpacked sdist. - The README's links are absolute. PyPI renders the README on its own page, where a link such as ../docs/reference.md leads nowhere. - Documentation and Changelog links in the project URLs, and classifiers for the operating system, Python 3 only and the topic. Co-Authored-By: Claude --- python/README.md | 20 ++++++++++---------- python/pyproject.toml | 9 +++++++++ 2 files changed, 19 insertions(+), 10 deletions(-) diff --git a/python/README.md b/python/README.md index bdb17de..c11eb06 100644 --- a/python/README.md +++ b/python/README.md @@ -2,7 +2,7 @@ Decide when an event should wake your agent, in an asyncio process. -This is the Python port of [attend](https://github.com/acquiredintelligence/attend). It has the same design and the same semantics as the TypeScript package, and its decision ids match it byte for byte. Both implementations pass the shared fixtures in [`conformance/`](../conformance), and either one can read and continue a scope the other wrote in a shared Redis or Postgres. [How attend works](../docs/how-it-works.md) and [the reference](../docs/reference.md) apply to both; this page covers what is particular to Python. +This is the Python port of [attend](https://github.com/acquiredintelligence/attend). It has the same design and the same semantics as the TypeScript package, and its decision ids match it byte for byte. Both implementations pass the shared fixtures in [`conformance/`](https://github.com/acquiredintelligence/attend/tree/main/conformance), and either one can read and continue a scope the other wrote in a shared Redis or Postgres. [How attend works](https://github.com/acquiredintelligence/attend/blob/main/docs/how-it-works.md) and [the reference](https://github.com/acquiredintelligence/attend/blob/main/docs/reference.md) apply to both; this page covers what is particular to Python. ```python import asyncio @@ -80,19 +80,19 @@ redis-py runs each concurrent command on a pooled connection of its own, and its - Keyword arguments and `settle` keys are snake_case, such as `create_attend(settle={"wait_horizon_ms": 5000})`. Every value that crosses a store or a judge (events, windows, decisions, dead letters, records, traces) is a dict with the TypeScript field names, such as `decision["window"]["settledAt"]`, so both runtimes share one persisted layout. - A judge, sink, dead-letter handler, `context` or `capture` is called with `(value, signal)`, where `signal` is an `aqi_attend.AbortSignal`. Honour it with `await signal.race(work)` or by checking `signal.aborted`. - `push`, `flush` and `end` return futures that resolve once the input is persisted. They take the input when called, as the TypeScript promises do. -- `settle={"continuation": "accumulate"}` retains one unresolved window through waits and retries. [Accumulating continuation](../docs/reference.md#accumulating-continuation) defines its bounds, failure allowance and stored-mode boundary. -- Add `"event_limits": {"counted": 3, "background": 2}` to that setting for an independent counted trigger and background capacity. Both numbers are required; do not also supply `max_events`. [Independent event limits](../docs/reference.md#independent-event-limits) defines retention, atomic input and saved-policy rules. -- A continuous event can carry `quietForMs` in its wire dictionary. [Continuous quiet duration](../docs/reference.md#continuous-quiet-duration) defines its validation, defaults and recovery. -- An event's optional `observedAt` keeps its camelCase wire name. It supplies source observation time for deadlines; `seenAt` remains engine ingestion time. The shared [observation-time reference](../docs/reference.md#observation-time) defines validation, ordering and replay. +- `settle={"continuation": "accumulate"}` retains one unresolved window through waits and retries. [Accumulating continuation](https://github.com/acquiredintelligence/attend/blob/main/docs/reference.md#accumulating-continuation) defines its bounds, failure allowance and stored-mode boundary. +- Add `"event_limits": {"counted": 3, "background": 2}` to that setting for an independent counted trigger and background capacity. Both numbers are required; do not also supply `max_events`. [Independent event limits](https://github.com/acquiredintelligence/attend/blob/main/docs/reference.md#independent-event-limits) defines retention, atomic input and saved-policy rules. +- A continuous event can carry `quietForMs` in its wire dictionary. [Continuous quiet duration](https://github.com/acquiredintelligence/attend/blob/main/docs/reference.md#continuous-quiet-duration) defines its validation, defaults and recovery. +- An event's optional `observedAt` keeps its camelCase wire name. It supplies source observation time for deadlines; `seenAt` remains engine ingestion time. The shared [observation-time reference](https://github.com/acquiredintelligence/attend/blob/main/docs/reference.md#observation-time) defines validation, ordering and replay. - Cancelling the task that runs `run()` stops it the way `stop()` does. -- `default_notice(decision, max_lines=20, fold=True)` takes its options as keyword arguments. [The notice](../docs/sinks.md#the-notice) says what it folds. -- `fold_events(values, repeats=..., continues=...)` returns a tuple of frozen `EventFold` groups with `first`, `last`, `count` and `mode`. The endpoint values refer to your inputs. [Write your own folded notice](../docs/sinks.md#write-your-own-folded-notice) explains the comparisons and filtering. +- `default_notice(decision, max_lines=20, fold=True)` takes its options as keyword arguments. [The notice](https://github.com/acquiredintelligence/attend/blob/main/docs/sinks.md#the-notice) says what it folds. +- `fold_events(values, repeats=..., continues=...)` returns a tuple of frozen `EventFold` groups with `first`, `last`, `count` and `mode`. The endpoint values refer to your inputs. [Write your own folded notice](https://github.com/acquiredintelligence/attend/blob/main/docs/sinks.md#write-your-own-folded-notice) explains the comparisons and filtering. -[DEVIATIONS.md](../DEVIATIONS.md#python-port) lists every difference. +[DEVIATIONS.md](https://github.com/acquiredintelligence/attend/blob/main/DEVIATIONS.md#python-port) lists every difference. ## Serial intake -`attend.open_intake(scope, capacity=20000)` owns preparation and immediate effects for an untouched scope. The shared [serial-intake contract](../docs/reference.md#serial-intake) defines ordering, admission, cancellation and recovery. +`attend.open_intake(scope, capacity=20000)` owns preparation and immediate effects for an untouched scope. The shared [serial-intake contract](https://github.com/acquiredintelligence/attend/blob/main/docs/reference.md#serial-intake) defines ordering, admission, cancellation and recovery. ```python from aqi_attend import AbortSignal, SourceBatch, create_attend @@ -123,7 +123,7 @@ Repeated cancellation of the runner does not skip its cleanup join. `stop()` rej ## Judges -`aqi_attend.judges` has `jev_judge` (TypeSafe's Jev, with your own key), `decisions_judge` (the OpenAI Decisions API) and `llm_judge`, which wraps any structured-output call you pass as `complete`. They send the same requests as the TypeScript judges, byte for byte. [Choose a judge](../docs/judges.md) explains each one, the window budget and the act threshold. +`aqi_attend.judges` has `jev_judge` (TypeSafe's Jev, with your own key), `decisions_judge` (the OpenAI Decisions API) and `llm_judge`, which wraps any structured-output call you pass as `complete`. They send the same requests as the TypeScript judges, byte for byte. [Choose a judge](https://github.com/acquiredintelligence/attend/blob/main/docs/judges.md) explains each one, the window budget and the act threshold. ## Test with a fake clock diff --git a/python/pyproject.toml b/python/pyproject.toml index 3b5cad3..9313078 100644 --- a/python/pyproject.toml +++ b/python/pyproject.toml @@ -13,10 +13,13 @@ classifiers = [ "Development Status :: 4 - Beta", "Framework :: AsyncIO", "Intended Audience :: Developers", + "Operating System :: OS Independent", "Programming Language :: Python :: 3", + "Programming Language :: Python :: 3 :: Only", "Programming Language :: Python :: 3.12", "Programming Language :: Python :: 3.13", "Programming Language :: Python :: 3.14", + "Topic :: Software Development :: Libraries :: Python Modules", "Typing :: Typed", ] @@ -27,8 +30,10 @@ http = ["httpx>=0.27"] [project.urls] Homepage = "https://github.com/acquiredintelligence/attend" +Documentation = "https://github.com/acquiredintelligence/attend/blob/main/python/README.md" Repository = "https://github.com/acquiredintelligence/attend" Issues = "https://github.com/acquiredintelligence/attend/issues" +Changelog = "https://github.com/acquiredintelligence/attend/blob/main/CHANGELOG.md" [dependency-groups] dev = [ @@ -49,6 +54,10 @@ build-backend = "hatchling.build" [tool.hatch.build.targets.wheel] packages = ["src/aqi_attend"] +# The tests read fixtures and TypeScript sources from the repo around this directory, so they stay out of the sdist. +[tool.hatch.build.targets.sdist] +only-include = ["src/aqi_attend"] + [tool.pytest.ini_options] testpaths = ["tests"] asyncio_mode = "auto" From c762dcde1fb3609a942def61c57ae8c3cff9e727 Mon Sep 17 00:00:00 2001 From: asher-aqi Date: Fri, 13 Nov 2026 23:02:28 -0600 Subject: [PATCH 2/3] release: v0.3.0 Sets the version to 0.3.0 in the five places it is written: package.json, python/pyproject.toml, python/uv.lock, the plugin manifest, and the version the MCP server reports, which was a literal '0.2.0' in two places in src/server/http.ts and is now one constant in src/internal/version.ts. scripts/check-version.mjs fails when those five disagree, and when a tag is given, when the tag does not name the version. `pnpm check` runs it. CHANGELOG.md is new. Its 0.3.0 entry covers everything merged since 0.2.0 reached npm: the Python package, folded notices, observation time, per-event quiet durations, serial intake, accumulating continuation, separate event limits, and the two `attend serve` wake-up fixes for Redis and Postgres. It opens with what to check before upgrading. Co-Authored-By: Claude --- .claude-plugin/plugin.json | 2 +- CHANGELOG.md | 39 ++++++++++++++++++++++++++++++++++++++ README.md | 4 ++-- package.json | 5 +++-- python/pyproject.toml | 2 +- python/uv.lock | 2 +- scripts/check-version.mjs | 35 ++++++++++++++++++++++++++++++++++ src/internal/version.ts | 2 ++ src/server/http.ts | 5 +++-- 9 files changed, 87 insertions(+), 9 deletions(-) create mode 100644 CHANGELOG.md create mode 100644 scripts/check-version.mjs create mode 100644 src/internal/version.ts diff --git a/.claude-plugin/plugin.json b/.claude-plugin/plugin.json index afc63ee..2bb6fe6 100644 --- a/.claude-plugin/plugin.json +++ b/.claude-plugin/plugin.json @@ -1,6 +1,6 @@ { "name": "attend", - "version": "0.2.0", + "version": "0.3.0", "description": "An Agent Skill for wiring attend, the attention layer that decides when an event should wake an agent.", "author": { "name": "Acquired Intelligence" }, "license": "MIT", diff --git a/CHANGELOG.md b/CHANGELOG.md new file mode 100644 index 0000000..6ea32ca --- /dev/null +++ b/CHANGELOG.md @@ -0,0 +1,39 @@ +# Changelog + +What changed in each release, for people who use attend. The npm package `@acquiredintelligence/attend` and the Python package `aqi-attend` are released together under one version number. + +## 0.3.0 (2026-11-14) + +This is the first release of the Python package. The npm package gains folded notices and five opt-in features, and `attend serve` delivers decisions sooner on Redis and Postgres. + +### Read this before you upgrade from 0.2.0 + +- **The default notice reads differently.** `defaultNotice` now folds repeated events into one line. If your agent or your tests depend on one line per event, pass `{ fold: false }`. +- **Upgrade every process that shares a store before you turn on a new option.** The stored format moves from reducer revision 1 to 5. 0.3.0 reads what 0.2.0 wrote and writes a fresh snapshot the first time it touches a scope. Nothing stops a 0.2.0 process from reading or writing a scope that 0.3.0 has written, and it will apply its old rules to it. Once events carry `observedAt` or `quietForMs`, or a scope uses `continuation: 'accumulate'`, going back to 0.2.0 changes how that stored state behaves. +- **`observedAt` and `quietForMs` are now event fields.** If your events already carried top-level fields with those names, attend now reads them. It rejects the batch when `observedAt` is in the future or not a finite number, and when `quietForMs` is invalid or sits on an event that is not `continuous`. +- **`attend serve` holds one more connection** to Redis or Postgres. See "Fixed" below. + +### Added + +- **A Python package.** `pip install aqi-attend`, then `import aqi_attend`. It is an asyncio port with the same semantics and the same decision ids as the TypeScript package, and either one can read and continue a scope the other wrote in a shared Redis or Postgres. It needs Python 3.12 or later and has no required dependencies; the `redis`, `postgres` and `http` extras add the store and judge clients. Start with the [Python guide](python/README.md). +- **Folded notices.** `defaultNotice` (`default_notice` in Python) turns a run of events that read the same into one line with its count, and a run of `continuous` events under one name into its first and last step with the count. Twenty-six identical failures are now one line instead of twenty lines and a count. `maxLines` counts folded lines. Only the text changes: the window, the decision id and what the judge sees are the same. `attend serve` sends the folded text in each decision's `notice` field. See [the notice](docs/sinks.md#the-notice). (#41) +- **`foldEvents`** (`fold_events` in Python) gives you the same groups for a notice you write yourself: `first`, `last`, `count` and `mode` for each run, using comparisons you supply. See [write your own folded notice](docs/sinks.md#write-your-own-folded-notice). (#42) +- **Observation time.** An event can carry `observedAt`, the time its source saw it. attend then measures quiet periods and window age from that time instead of from when the event arrived, which matters for a source that buffers or delivers late. Leave it out and timing is as before. See [observation time](docs/reference.md#observation-time). (#43) +- **A quiet duration for each continuous event.** A `continuous` event can carry `quietForMs`, so events that share a window can wait different lengths of quiet before the window settles. Events without it use `streamGapMs` as before. See [continuous quiet duration](docs/reference.md#continuous-quiet-duration). (#44) +- **Serial intake.** When events need asynchronous preparation before they can be pushed, `openIntake(attend, scope)` from the new `@acquiredintelligence/attend/intake` entry (`attend.open_intake(scope)` in Python) runs one preparation and its immediate judgments and deliveries at a time, in the order the work was registered. A quiet timer or an earlier delivery can no longer overtake work that is still being prepared. Closing the intake waits for every preparation it started to finish cleaning up. The entry needs Node; the default entry is unchanged and still imports nothing from Node. See [serial intake](docs/reference.md#serial-intake). (#45, #47) +- **Accumulating continuation.** With `settle: { continuation: 'accumulate' }`, a window the judge answered with `wait`, or one whose judge call failed, stays one window: events that arrive meanwhile join it, the judge can be offered `wait` again within `maxWaits`, and a retry never starts before its backoff ends. The default, `separate`, is the 0.2.0 behavior. A scope keeps the mode it was written with, and attend refuses to change the mode while the scope still holds unresolved events. See [accumulating continuation](docs/reference.md#accumulating-continuation). (#46) +- **Separate limits for counted and background events.** With accumulating continuation, `settle.eventLimits: { counted, background }` (`event_limits` in Python) settles the window once it holds `counted` acts, and separately keeps at most `background` context and consequence events, dropping the oldest first. It takes the place of `maxEvents`, and setting both is rejected. See [independent event limits](docs/reference.md#independent-event-limits). (#48) + +### Fixed + +- **`attend serve` on Redis delivered every decision up to 250 ms late.** Subscribers on `events/stream`, `events/poll` and `attend_wait` polled the decision log instead of blocking on it. `attend serve --store redis:` now opens a second connection for a blocking read, so a waiting subscriber wakes as soon as the decision is written. If you build the Redis store yourself for `serve()` or for `attend.decisions`, pass `blockingSend` to get the same; [choose a store](docs/storage.md) shows how. (#36) +- **`attend serve` on Postgres delivered decisions on the next poll, up to 100 ms late.** `attend serve --store postgres:` now holds one more connection that listens for new decisions. If you build the Postgres store yourself, pass a `listener`; [choose a store](docs/storage.md) shows how. (#38) +- **Restarting with changed `settle` options could apply finished input a second time.** On startup the TypeScript engine replayed a scope's stored inputs under the new options instead of the policy saved with the scope. It now replays under the saved policy. (#48) + +## 0.2.0 (2026-10-16) + +A leaner `createAttend`, and a guide for putting attend in front of a Mastra agent. + +## 0.1.0 (2026-10-16) + +The first release on npm. diff --git a/README.md b/README.md index f1ed09f..19a299d 100644 --- a/README.md +++ b/README.md @@ -55,7 +55,7 @@ npm install @acquiredintelligence/attend attend needs Node 22.13 or later and ships ESM only. The engine has no runtime dependencies. Before production, replace the function judge with [a real judge](docs/judges.md) and pass `store` [a database store](docs/storage.md); without one, state lives in memory. -A Python port for asyncio, with the same semantics and the same decision ids, lives in [`python/`](python/README.md). +A Python port for asyncio, with the same semantics and the same decision ids, installs with `pip install aqi-attend`. Its guide is in [`python/`](python/README.md). ## See it decide @@ -158,7 +158,7 @@ For Codex or Cursor, copy `skills/attend` into your project's `.agents/skills/`. ## Status -attend is v0, and its API can change before 1.0. MCP Events is a working-group draft, so its wire shapes can change too. `@acquiredintelligence/attend/mcp` follows the current draft. +attend is v0, and its API can change before 1.0. [The changelog](CHANGELOG.md) says what each release changed. MCP Events is a working-group draft, so its wire shapes can change too. `@acquiredintelligence/attend/mcp` follows the current draft. ## License diff --git a/package.json b/package.json index 1aab167..7a5eef3 100644 --- a/package.json +++ b/package.json @@ -1,6 +1,6 @@ { "name": "@acquiredintelligence/attend", - "version": "0.2.0", + "version": "0.3.0", "description": "The attention layer for agents: decide when an event should wake your agent.", "license": "MIT", "type": "module", @@ -83,8 +83,9 @@ "build": "tsc -p tsconfig.build.json", "typecheck": "tsc -p tsconfig.json --noEmit", "test": "vitest run", - "check": "pnpm typecheck && pnpm test && pnpm build && pnpm check:docs && pnpm check:browser", + "check": "pnpm typecheck && pnpm test && pnpm build && pnpm check:docs && pnpm check:browser && pnpm check:version", "check:browser": "node --experimental-vm-modules scripts/check-browser-root.mjs", + "check:version": "node scripts/check-version.mjs", "demo": "pnpm build && node --experimental-strip-types examples/demo.ts", "check:docs": "node scripts/check-snippets.mjs", "test:oracle": "vitest run -c vitest.oracle.config.ts", diff --git a/python/pyproject.toml b/python/pyproject.toml index 9313078..805edca 100644 --- a/python/pyproject.toml +++ b/python/pyproject.toml @@ -1,6 +1,6 @@ [project] name = "aqi-attend" -version = "0.2.0" +version = "0.3.0" description = "The attention layer for agents: decide when an event should wake your agent." readme = "README.md" license = "MIT" diff --git a/python/uv.lock b/python/uv.lock index 718dcac..ee491b7 100644 --- a/python/uv.lock +++ b/python/uv.lock @@ -17,7 +17,7 @@ wheels = [ [[package]] name = "aqi-attend" -version = "0.2.0" +version = "0.3.0" source = { editable = "." } [package.optional-dependencies] diff --git a/scripts/check-version.mjs b/scripts/check-version.mjs new file mode 100644 index 0000000..f61ec88 --- /dev/null +++ b/scripts/check-version.mjs @@ -0,0 +1,35 @@ +#!/usr/bin/env node +// The release version is written in five files, and they must agree. Given a tag, the tag must name it too. +// Usage: node scripts/check-version.mjs [vX.Y.Z], from anywhere; the repo is the directory above this script. +import { readFileSync } from 'node:fs'; +import { dirname, join, resolve } from 'node:path'; +import { fileURLToPath } from 'node:url'; + +const repo = resolve(dirname(fileURLToPath(import.meta.url)), '..'); +const read = (file) => readFileSync(join(repo, file), 'utf8'); +const match = (file, pattern) => read(file).match(pattern)?.[1]; + +const found = { + 'package.json': JSON.parse(read('package.json')).version, + 'src/internal/version.ts': match('src/internal/version.ts', /^export const VERSION = '([^']+)';$/m), + '.claude-plugin/plugin.json': JSON.parse(read('.claude-plugin/plugin.json')).version, + 'python/pyproject.toml': match('python/pyproject.toml', /^\[project\]\n(?:(?!\[).*\n)*?version = "([^"]+)"$/m), + 'python/uv.lock': match('python/uv.lock', /^name = "aqi-attend"\nversion = "([^"]+)"$/m), +}; + +const version = found['package.json']; +const problems = []; +// npm and PyPI spell a plain X.Y.Z the same way; a pre-release would need two spellings. +if (!/^\d+\.\d+\.\d+$/.test(version ?? '')) problems.push(`package.json: "${version}" is not X.Y.Z`); +for (const [file, value] of Object.entries(found)) { + if (value !== version) problems.push(`${file}: ${value === undefined ? 'no version found' : `"${value}"`}, but package.json says "${version}"`); +} +const tag = process.argv[2]; +if (tag && tag !== `v${version}`) problems.push(`tag "${tag}" does not name v${version}`); + +if (problems.length > 0) { + console.error(`check-version: ${problems.length} problem${problems.length === 1 ? '' : 's'}`); + for (const problem of problems) console.error(` ${problem}`); + process.exit(1); +} +console.log(`check-version: ${version} in ${Object.keys(found).length} files${tag ? `, and tag ${tag} names it` : ''}`); diff --git a/src/internal/version.ts b/src/internal/version.ts new file mode 100644 index 0000000..a22df72 --- /dev/null +++ b/src/internal/version.ts @@ -0,0 +1,2 @@ +/** The package version. `scripts/check-version.mjs` keeps it equal to package.json. */ +export const VERSION = '0.3.0'; diff --git a/src/server/http.ts b/src/server/http.ts index 8c3a64e..6c635b4 100644 --- a/src/server/http.ts +++ b/src/server/http.ts @@ -1,4 +1,5 @@ import type { IncomingMessage, ServerResponse } from 'node:http'; +import { VERSION } from '../internal/version.js'; import { EventsError, eventsError, parseSubscription } from './events.js'; import { notificationJSON } from './fanout.js'; import { guardStream } from './guard.js'; @@ -172,7 +173,7 @@ export function httpHandler(context: ServerContext, install: EventsServer['insta if (!legacy) { const owner = principal; const handler = sdk.createMcpHandler(() => { - const server = options.newServer?.() ?? new sdk.Server({ name: context.options.name ?? 'attend', version: context.options.version ?? '0.2.0' }, { capabilities: {} }); + const server = options.newServer?.() ?? new sdk.Server({ name: context.options.name ?? 'attend', version: context.options.version ?? VERSION }, { capabilities: {} }); install(server, { principal: owner }); // The public seam omits SDK methods that its factory also requires. return server as InstanceType | InstanceType; @@ -186,7 +187,7 @@ export function httpHandler(context: ServerContext, install: EventsServer['insta const newId = sessions.open(); if (!newId) { json(res, 503, { jsonrpc: '2.0', id, error: eventsError('ResourceExhausted', 'Session quota exceeded', { limit: 'sessions', max: options.sessions?.max ?? 10_000 }).toJSON() }); return; } try { - const server = options.newServer?.() ?? new sdk.Server({ name: context.options.name ?? 'attend', version: context.options.version ?? '0.2.0' }, { capabilities: {} }); + const server = options.newServer?.() ?? new sdk.Server({ name: context.options.name ?? 'attend', version: context.options.version ?? VERSION }, { capabilities: {} }); const transport = new sdk.WebStandardStreamableHTTPServerTransport({ sessionIdGenerator: () => newId, onsessionclosed: () => sessions.close(newId) }); install(server, { principal }); session = { principal, transport, abort: new AbortController(), async close() { await transport.close(); if ('close' in server && typeof server.close === 'function') await server.close(); } }; From c14094e37581c26249c2c88d7efa15ca9b8d1bc2 Mon Sep 17 00:00:00 2001 From: asher-aqi Date: Fri, 13 Nov 2026 23:02:28 -0600 Subject: [PATCH 3/3] ci(release): publish to npm and PyPI when a version tag is pushed Pushing a tag vX.Y.Z now publishes both packages. Earlier npm versions were published by hand, and the Python package has never been published. build tag names the version in all five files, tagged commit is on main, pnpm build, npm pack, uv build verify no checkout: the tarball, sdist and wheel hold only the package, twine check passes, each installs alone and imports publish-npm npm publish of the verified tarball, environment `npm` publish-pypi pypa/gh-action-pypi-publish on the verified files, environment `pypi` Both registries use trusted publishing, so no token is stored. Only the two publish jobs can ask for an OIDC token, and neither runs anything from the repo: they download what verify checked and upload it. npm attaches provenance and the PyPI action uploads attestations without extra flags. A pull request runs build and verify, so a packaging break shows up before a tag exists. The publish jobs run only for a tag push. Actions are pinned by major version, as in the other workflows. Co-Authored-By: Claude --- .github/workflows/release.yml | 164 ++++++++++++++++++++++++++++++++++ 1 file changed, 164 insertions(+) create mode 100644 .github/workflows/release.yml diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml new file mode 100644 index 0000000..c0a9c3e --- /dev/null +++ b/.github/workflows/release.yml @@ -0,0 +1,164 @@ +name: release + +# Pushing a tag vX.Y.Z publishes that version to npm and to PyPI. Both registries trust this file by +# name through OIDC, with the environments `npm` and `pypi`, so the repo stores no token. Renaming the +# file or an environment breaks that trust until the publisher is set up again on each registry. +# +# To release: set the version in the five files scripts/check-version.mjs reads, add a CHANGELOG.md +# entry, merge to main, then tag that commit vX.Y.Z and push the tag. +# +# A pull request runs build and verify on what would be published and never publishes. + +on: + push: + tags: ['v[0-9]+.[0-9]+.[0-9]+'] + pull_request: + +permissions: + contents: read + +concurrency: + group: release-${{ github.ref }} + cancel-in-progress: ${{ github.event_name == 'pull_request' }} + +defaults: + run: + shell: bash + +jobs: + build: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + with: + fetch-depth: 0 + - uses: pnpm/action-setup@v4 + # No dependency cache in this workflow: a release builds from the lockfiles alone. + - uses: actions/setup-node@v4 + with: + node-version: 24 + - uses: astral-sh/setup-uv@v6 + with: + enable-cache: false + - name: Every version agrees, and the tag names it + env: + TAG: ${{ github.ref_type == 'tag' && github.ref_name || '' }} + run: node scripts/check-version.mjs "$TAG" + - name: The tagged commit is on main + if: github.ref_type == 'tag' + run: | + if ! git merge-base --is-ancestor HEAD origin/main; then + echo "::error::$GITHUB_REF_NAME points at a commit that is not on main. Merge first, then tag the commit on main." + exit 1 + fi + - run: pnpm install --frozen-lockfile + - run: pnpm build + - run: | + mkdir "$RUNNER_TEMP/npm-package" + npm pack --pack-destination "$RUNNER_TEMP/npm-package" + - run: uv build --out-dir "$RUNNER_TEMP/python-dist" + working-directory: python + - uses: actions/upload-artifact@v4 + with: + name: npm-package + path: ${{ runner.temp }}/npm-package/*.tgz + if-no-files-found: error + - uses: actions/upload-artifact@v4 + with: + name: python-dist + path: | + ${{ runner.temp }}/python-dist/*.tar.gz + ${{ runner.temp }}/python-dist/*.whl + if-no-files-found: error + + # Checks the files the publish jobs will upload, in a job that has no checkout of the repo. + verify: + needs: build + runs-on: ubuntu-latest + steps: + - uses: actions/download-artifact@v4 + - uses: actions/setup-node@v4 + with: + node-version: 24 + - uses: astral-sh/setup-uv@v6 + with: + enable-cache: false + - name: The npm tarball holds only the package, installs alone and runs + run: | + tarball=$(ls "$PWD"/npm-package/*.tgz) + extra=$(tar -tzf "$tarball" | grep -v -E '^package/(dist/|skills/|README\.md$|LICENSE$|package\.json$)' || true) + if [ -n "$extra" ]; then printf 'Unexpected files in the npm tarball:\n%s\n' "$extra"; exit 1; fi + mkdir "$RUNNER_TEMP/app" + cd "$RUNNER_TEMP/app" + npm init --yes > /dev/null + npm install "$tarball" + node --input-type=module --eval " + import { createAttend, foldEvents } from '@acquiredintelligence/attend'; + import { openIntake } from '@acquiredintelligence/attend/intake'; + import { fakeClock } from '@acquiredintelligence/attend/testing'; + if (![createAttend, foldEvents, openIntake, fakeClock].every((f) => typeof f === 'function')) process.exit(1); + " + npx --no-install attend --help > /dev/null + - name: The Python files pass twine, hold only the package, install alone and import + working-directory: python-dist + run: | + uvx twine check --strict *.tar.gz *.whl + extra=$(tar -tzf *.tar.gz | grep -v -E '^aqi_attend-[0-9.]+/(src/aqi_attend/|README\.md$|LICENSE$|PKG-INFO$|pyproject\.toml$|\.gitignore$)' || true) + if [ -n "$extra" ]; then printf 'Unexpected files in the sdist:\n%s\n' "$extra"; exit 1; fi + extra=$(unzip -Z1 *.whl | grep -v -E '^aqi_attend(-[0-9.]+\.dist-info)?/' || true) + if [ -n "$extra" ]; then printf 'Unexpected files in the wheel:\n%s\n' "$extra"; exit 1; fi + uv venv --python 3.12 "$RUNNER_TEMP/venv" + uv pip install --python "$RUNNER_TEMP/venv/bin/python" *.whl + cd "$RUNNER_TEMP" + "$RUNNER_TEMP/venv/bin/python" -c " + import aqi_attend, aqi_attend.judges, aqi_attend.testing, aqi_attend.store.memory, aqi_attend.store.postgres, aqi_attend.store.redis + assert callable(aqi_attend.create_attend) and callable(aqi_attend.fold_events) + " + + publish-npm: + if: github.event_name == 'push' && github.ref_type == 'tag' && github.repository == 'acquiredintelligence/attend' + needs: verify + runs-on: ubuntu-latest + environment: + name: npm + url: https://www.npmjs.com/package/@acquiredintelligence/attend + permissions: + contents: read + id-token: write + steps: + - uses: actions/download-artifact@v4 + with: + name: npm-package + - uses: actions/setup-node@v4 + with: + node-version: 24 + registry-url: https://registry.npmjs.org + - name: npm is new enough for trusted publishing + run: | + node -e " + const [major, minor, patch] = process.argv[1].split('.').map(Number); + if (major < 11 || (major === 11 && (minor < 5 || (minor === 5 && patch < 1)))) { + console.error('npm ' + process.argv[1] + ' is older than 11.5.1, which trusted publishing needs'); + process.exit(1); + } + " "$(npm --version)" + # No token and no --provenance: npm trades this job's OIDC identity for a short-lived token, + # and attaches provenance on its own for a public package built from a public repo. + - run: npm publish ./*.tgz --access public + + publish-pypi: + if: github.event_name == 'push' && github.ref_type == 'tag' && github.repository == 'acquiredintelligence/attend' + needs: verify + runs-on: ubuntu-latest + environment: + name: pypi + url: https://pypi.org/p/aqi-attend + permissions: + id-token: write + steps: + - uses: actions/download-artifact@v4 + with: + name: python-dist + path: dist + # No token: the action trades this job's OIDC identity for one, and uploads attestations too. + - uses: pypa/gh-action-pypi-publish@release/v1