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
2 changes: 1 addition & 1 deletion .claude-plugin/plugin.json
Original file line number Diff line number Diff line change
@@ -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",
Expand Down
164 changes: 164 additions & 0 deletions .github/workflows/release.yml
Original file line number Diff line number Diff line change
@@ -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
39 changes: 39 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
@@ -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.
4 changes: 2 additions & 2 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down Expand Up @@ -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

Expand Down
5 changes: 3 additions & 2 deletions package.json
Original file line number Diff line number Diff line change
@@ -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",
Expand Down Expand Up @@ -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",
Expand Down
Loading
Loading