@acquiredintelligence/attend 0.0.0-stage → 0.2.0

package/skills/attend/references/judges.md

@@ -0,0 +1,283 @@
+# Judges
+
+A judge is `(input: JudgeInput, signal: AbortSignal) => Promise<Judgment>`.
+
+## The input
+
+| Field | Holds |
+|---|---|
+| `scope` | The scope key |
+| `window` | The settled window: `events` with kinds, `reason`, `waits`, `dropped`, `gap` |
+| `routes` | The routes on offer, each with `criterion` when `AttendConfig.criteria` sets one. `wait` is absent when the window may not wait. |
+| `guidance` | `AttendConfig.guidance`, when set |
+| `predicates` | Yes-or-no questions, as `{ name, question }`, from `AttendConfig.predicates` and `context()` |
+| `facts` | `context(scope, signal).facts`, fetched on every call |
+| `images` | What `AttendConfig.capture` returned for this call, when it returned any |
+| `recent` | The scope's last verdicts, oldest first, at most `recentCount` |
+| `now` | attend's clock |
+
+## The answer
+
+Return `{ route, probabilities?, predicates?, confidence? }`.
+
+- `route` must be one of `input.routes`. Any other route fails the attempt, and the attempt is retried.
+- `probabilities` maps offered routes to numbers from 0 to 1. attend sets routes that were not offered to 0 and renormalises the rest. When they sum to 0, the chosen route gets 1.
+- `predicates` maps predicate names to numbers from 0 to 1. attend drops values outside that range.
+- `confidence` is a number from 0 to 1 when the judge has one, such as a classifier's confidence in the route. It reaches the sink as `decision.confidence`, null when absent.
+- Throw to retry with backoff from `retryBackoffMs`. Throw `PermanentError` from `@acquiredintelligence/attend` to dead-letter the window at once.
+- Stop when `signal` aborts. attend aborts the call after `judgeTimeoutMs`.
+
+## llmJudge
+
+`llmJudge({ complete })` from `@acquiredintelligence/attend/llm` writes the system prompt, renders the input as compact JSON, builds a strict JSON Schema for the answer, and validates the reply. `complete({ system, prompt, schema, signal })` makes one structured-output call and resolves with the parsed JSON.
+
+Claude:
+
+```ts
+import Anthropic from '@anthropic-ai/sdk';
+import { PermanentError } from '@acquiredintelligence/attend';
+import { llmJudge } from '@acquiredintelligence/attend/llm';
+
+const anthropic = new Anthropic();
+
+export const judge = llmJudge({
+  complete: async ({ system, prompt, images, schema, signal }) => {
+    const res = await anthropic.messages.create(
+      {
+        model: 'claude-opus-5-5',
+        max_tokens: 1024,
+        system,
+        messages: [
+          {
+            role: 'user',
+            content: [
+              { type: 'text', text: prompt },
+              ...images.map((image) => ({ type: 'image' as const, source: { type: 'base64' as const, media_type: image.mimeType, data: image.data } })),
+            ],
+          },
+        ],
+        output_config: { effort: 'low', format: { type: 'json_schema', schema } },
+      },
+      { signal },
+    );
+    if (res.stop_reason === 'refusal') throw new PermanentError('judge refused');
+    const text = res.content.find((b) => b.type === 'text');
+    return JSON.parse(text?.type === 'text' ? text.text : 'null');
+  },
+});
+```
+
+- Use `claude-opus-5-5`, or `claude-haiku-5-5` for a cheaper judge. Write the model id without a date suffix.
+- Request structured output with `output_config.format`. Keep `effort: 'low'` for a classifier, and leave `thinking` and `tool_choice` out.
+- Check `stop_reason === 'refusal'` before you read `content`. A refusal arrives with HTTP 200.
+- Images go as `image` blocks with a base64 `source`. PNG, JPEG, GIF and WEBP are accepted, at most 10 MB each and 8000 px per side (2000 px when a request has more than 20 images).
+
+OpenAI Responses API:
+
+```ts
+import OpenAI from 'openai';
+import { PermanentError } from '@acquiredintelligence/attend';
+import { llmJudge } from '@acquiredintelligence/attend/llm';
+
+const openai = new OpenAI();
+
+export const judge = llmJudge({
+  complete: async ({ system, prompt, images, schema, signal }) => {
+    const res = await openai.responses.create(
+      {
+        model: '<model id>',
+        instructions: system,
+        input: [
+          {
+            role: 'user',
+            content: [
+              { type: 'input_text', text: prompt },
+              ...images.map((image) => ({ type: 'input_image' as const, image_url: `data:${image.mimeType};base64,${image.data}`, detail: 'auto' as const })),
+            ],
+          },
+        ],
+        text: { format: { type: 'json_schema', name: 'judgment', schema, strict: true } },
+      },
+      { signal },
+    );
+    if (res.output.some((item) => item.type === 'message' && item.content.some((part) => part.type === 'refusal'))) throw new PermanentError('judge refused');
+    return JSON.parse(res.output_text);
+  },
+});
+```
+
+- A refusal is a `refusal` content part inside the `message` output item, not a status code. `response.status === 'incomplete'` means the answer was cut off; treat it as a retryable failure.
+- Images go as `input_image` parts with a `data:` URL. PNG, JPEG, WEBP and non-animated GIF are accepted.
+
+Gemini, through `@google/genai`. This snippet was written without the package installed, so check `generateContent` and the config fields against the version you use:
+
+```ts
+import { GoogleGenAI } from '@google/genai';
+import { PermanentError } from '@acquiredintelligence/attend';
+import { llmJudge } from '@acquiredintelligence/attend/llm';
+
+const ai = new GoogleGenAI({});
+
+export const judge = llmJudge({
+  complete: async ({ system, prompt, images, schema, signal }) => {
+    const res = await ai.models.generateContent({
+      model: '<model id>',
+      contents: [{ role: 'user', parts: [{ text: prompt }, ...images.map((image) => ({ inlineData: { mimeType: image.mimeType, data: image.data } }))] }],
+      config: { systemInstruction: system, responseMimeType: 'application/json', responseJsonSchema: schema, abortSignal: signal },
+    });
+    const finish = res.candidates?.[0]?.finishReason;
+    if (res.promptFeedback?.blockReason !== undefined || (finish !== undefined && finish !== 'STOP' && finish !== 'MAX_TOKENS')) throw new PermanentError('judge refused');
+    return JSON.parse(res.text ?? 'null');
+  },
+});
+```
+
+- A blocked prompt has `promptFeedback.blockReason` and no candidates; a blocked answer has a `finishReason` such as `SAFETY`. Both are refusals. `MAX_TOKENS` is truncation, and the JSON parse then fails as a retryable error.
+- Images go as `inlineData` parts. PNG, JPEG, WEBP, HEIC and HEIF are accepted; GIF is not. Keep the request under 20 MB.
+- The JS SDK does not retry on its own. attend retries the judge call, so leave `httpOptions.retryOptions` unset.
+
+Vercel AI SDK. This snippet was written without the `ai` package installed, so check `generateObject` and `jsonSchema` against the version you use:
+
+```ts
+import { openai } from '@ai-sdk/openai';
+import { generateObject, jsonSchema } from 'ai';
+import { llmJudge } from '@acquiredintelligence/attend/llm';
+
+export const judge = llmJudge({
+  complete: async ({ system, prompt, images, schema, signal }) => {
+    const { object } = await generateObject({
+      model: openai('<model id>'),
+      system,
+      messages: [{ role: 'user', content: [{ type: 'text', text: prompt }, ...images.map((image) => ({ type: 'image' as const, image: image.data, mediaType: image.mimeType }))] }],
+      schema: jsonSchema(schema),
+      abortSignal: signal,
+    });
+    return object;
+  },
+});
+```
+
+Options:
+
+- `system` replaces `DEFAULT_SYSTEM`. attend appends the offered routes and their criteria either way.
+- `criteria` sets per-route criteria. A criterion from `AttendConfig.criteria` wins, and `DEFAULT_CRITERIA` fills the rest.
+- `render(input)` replaces the default user prompt, which is compact JSON of the guidance, the window, the facts, the recent routes and the predicate questions.
+
+## jevJudge
+
+```ts
+import { jevJudge } from '@acquiredintelligence/attend/jev';
+
+export const judge = jevJudge({ apiKey: process.env.TYPESAFE_API_KEY ?? '' });
+```
+
+It calls TypeSafe's Jev at `POST /v1/systemone` with the user's own key. It sends one `choice` question keyed `route`, with each offered route's criterion as its option description, one `noul` question per predicate keyed by position, and the rendered state as JSON `state`. The answer's `probabilities` and `confidence` reach the judgment.
+
+Options:
+
+- `model`: `jev-latest` by default, which is the latest stable release (`jev-1.13.0` today). `jev-preview` is the newest release (`jev-1.14.0` today). `jev-1.14.0` and `jev-1.13.0` pin a version; pin one when thresholds on `confidence` are tuned.
+- `endpoint`: `https://api.typesafe.ai/v1/systemone` by default. OpenRouter serves the same API at `https://openrouter.ai/api/v1/systemone`, and LiteLLM at its own host under the same path.
+- `longContext: true` sends `TypeSafe-Danger-Zone-Long-Context: true`, which raises the per-request and per-question context from 64k and 32k tokens to 262k. It is slower and less accurate, so use it only when the state is long.
+- `criteria`, `instructions` and `fetch`, as on `decisionsJudge`.
+- `images: false` never sends images. `onImageError(error)` hears about every image dropped before a call and about a call retried without images. See [Images](#images).
+
+## decisionsJudge
+
+```ts
+import { decisionsJudge } from '@acquiredintelligence/attend/decisions';
+
+export const judge = decisionsJudge({ apiKey: process.env.OPENAI_API_KEY ?? '', model: '<model id>' });
+```
+
+It sends one `choice` question named `route`, with each offered route's criterion as its description, and one `predicate` question per predicate. Pass `fetch` to run it on a custom transport, and `endpoint` to point it elsewhere. `images: false` and `onImageError` work as on `jevJudge`.
+
+## Errors from the hosted judges
+
+Both `jevJudge` and `decisionsJudge` classify a response the same way:
+
+| Response | Thrown | attend does |
+|---|---|---|
+| Network failure, timeout, 408, 429, 5xx, 529 | `Error` | Retries with backoff |
+| 429 with a billing or quota code (`credit_balance_exhausted`, `organization_spend_limit_exceeded`, `project_spend_limit_exceeded`, `organization_usage_limit_exceeded`, `insufficient_quota`) | `PermanentError` | Dead-letters at once |
+| Any other 4xx, including 400 for a request over the context length and 413 for one over the body limit | `PermanentError` | Dead-letters at once |
+| A refusal of the route question (Decisions only; Jev has no refusals) | `PermanentError` | Dead-letters at once |
+| A reply whose route was not offered | `Error` | Retries |
+
+Every error from a response carries `status`, `requestId` (from `x-typesafe-request-id` or `x-request-id`) and `retryAfterMs` (from `retry-after-ms` or `Retry-After`, else null). attend's backoff does not read `retryAfterMs` yet; it is there for a wrapper that wants to.
+
+Before a call, a duplicate predicate name throws `PermanentError`, and so does a Decisions call with more than 199 predicates, since the API takes 200 questions and the route is one.
+
+## Images
+
+`createAttend({ capture })` adds images to every judge call:
+
+```ts
+import { createAttend, memoryStore, routes } from '@acquiredintelligence/attend';
+import type { JudgeImage } from '@acquiredintelligence/attend';
+
+declare function screenshot(scope: string, signal: AbortSignal): Promise<JudgeImage>;
+
+export const attend = createAttend({
+  store: memoryStore(),
+  kind: () => 'closing',
+  judge: async () => ({ route: 'queue' }),
+  sink: routes({ interrupt: async () => {}, queue: async () => {}, note: async () => {}, ask: async () => {} }),
+  deadLetter: async () => {},
+  capture: (scope, signal) => screenshot(scope, signal),
+  captureTimeoutMs: 500,
+});
+```
+
+- `capture(scope, signal)` returns one `JudgeImage`, a list, or null. A `JudgeImage` is `{ data, mimeType }` with `data` as base64 and no `data:` prefix, and `mimeType` one of `image/png`, `image/jpeg`, `image/webp` or `image/gif`.
+- A capture that throws or outlives `captureTimeoutMs` (default 500) never fails the judge call. The judge runs without images, and `observe` sees one `captureFailed` trace with the message.
+- `jevJudge` sends only PNG and JPEG, each side 280 to 1568 px, at most 16 MiB per file and 32 MiB in all, and drops anything else before the call. The provider never resizes, so capture at a size inside those limits. Images on this provider are experimental, and a request it still rejects over its images (400, 413, 415 or 422) is retried once without them.
+- `decisionsJudge` sends up to 128 images of any format as `input_image` data URLs, and retries once without them on the same statuses, since the API documents no format or size limits.
+- `llmJudge` hands the images to `complete` as `images`. The snippets above place them after the prompt in each model's own block format.
+
+## A function judge
+
+Write a plain function when a rule decides. Read `input.routes` before you answer `wait`:
+
+```ts
+import type { Judge } from '@acquiredintelligence/attend';
+
+export const judge: Judge = async ({ window, routes }) => {
+  const has = (name: string) => window.events.some((e) => e.name === name);
+  if (window.reason === 'flush') return { route: 'interrupt' };
+  if (has('build.failed')) return { route: routes.some((o) => o.route === 'wait') ? 'wait' : 'queue' };
+  return { route: 'skip' };
+};
+```
+
+Judges compose as functions. Wrap a model judge so rules answer first:
+
+```ts
+import type { Judge } from '@acquiredintelligence/attend';
+
+export const withShortcut =
+  (judge: Judge): Judge =>
+  async (input, signal) =>
+    input.window.reason === 'flush' ? { route: 'interrupt' } : judge(input, signal);
+```
+
+A hosted classifier is a judge too: send `input` as JSON, map its answer to `{ route }`, throw on retryable errors, and throw `PermanentError` on the rest.
+
+## Configuring what the judge sees
+
+```ts
+import { createAttend, memoryStore, routes } from '@acquiredintelligence/attend';
+
+export const attend = createAttend({
+  store: memoryStore(),
+  kind: () => 'closing',
+  judge: async () => ({ route: 'queue' }),
+  sink: routes({ interrupt: async () => {}, queue: async () => {}, note: async () => {}, ask: async () => {} }),
+  deadLetter: async () => {},
+  guidance: 'An on-call agent for the payments service. Its user wants pages for customer impact only.',
+  criteria: { interrupt: 'Customers are failing to pay right now.' },
+  predicates: { asked: 'Did the user ask the agent to handle this?' },
+  context: async (scope) => ({ facts: { midTurn: false, scope } }),
+});
+```
+
+Each predicate's answer arrives on `decision.predicates[name]` as a probability. A sink never sees `skip`, so to wake the agent on a skipped window whose predicate is high, wrap the judge: call it, then replace `skip` with another route when the predicate passes your threshold.

package/skills/attend/references/kinds.md

@@ -0,0 +1,62 @@
+# Settle rules
+
+How a scope's open window settles, exactly. All times are on attend's clock at ingest (`entry.seenAt`), never the source's `event.at`. Defaults are in `DEFAULT_POLICY`, exported from `@acquiredintelligence/attend`.
+
+`closing`, `flush`, `continuous` and `passive` are acts: things that happen in the scope and can call for the agent, whether the user did them or an outside party did. `consequence` is output that followed from an act, and `context` is the agent's own earlier output.
+
+## Deadlines
+
+Every event in the open window can set a deadline. The window settles at the earliest one, with that deadline's reason.
+
+| Deadline | At | Reason |
+|---|---|---|
+| A `flush` event | Its arrival | `flush` |
+| The last `closing` event | Its arrival plus `closingGraceMs` | `closing` |
+| The last `continuous` event | Its arrival plus `streamGapMs` | `stream_quiet` |
+| The last `passive` event | Its arrival plus `passiveQuietMs` | `passive_quiet` |
+| The first act (`closing`, `continuous` or `passive`) | Its arrival plus `maxWindowMs` | `age` |
+| `attend.flush(scope)` | The call | `forced` |
+| More than `maxEvents` events left after shedding | The last arrival | `overflow` |
+
+- A later closing, continuous or passive event moves its own deadline later. A steady run of continuous events holds the window open until they stop, or until the `age` deadline.
+- A window with no flush and no act has no deadline. It never settles.
+- After a `flush` or `forced` settle, the judge is not offered `wait`.
+
+## Shedding
+
+- When the window holds more than `maxEvents` events, attend drops its oldest `consequence` and `context` events, adds them to `window.dropped`, and traces `dropped` with `why: 'overflow'`. If only acts and flushes are left and the window is still too big, it settles with reason `overflow`.
+- `consequence` and `context` events that arrived before the first act and are older than `maxWindowMs` are dropped the same way, with `why: 'age'`.
+- attend never drops an act or a flush.
+
+## One judge call at a time
+
+Each scope has one judge slot. While a judge call runs, new events collect in the open window, and that window cannot settle. When the judge answers, a window whose deadline has already passed settles at once.
+
+## Wait and merge
+
+- `wait` moves the settled window into a held state until `waitHorizonMs` from the answer.
+- If the open window settles before the horizon, the held window and the new one merge, held events first. The merged window has a new id, because the id is a hash of all its event ids, and it keeps the held window's `waits` count. The judge is offered `wait` again only while `waits` is below `maxWaits` and the reason is neither `flush` nor `forced`.
+- At the horizon, attend judges the held window together with everything in the open window, consequences included, with `wait` withheld. The merged window has a new id.
+- `attend.flush(scope)` on a scope that holds only a waiting window judges it at the runner's next tick, with `wait` withheld.
+
+## What the judge sees
+
+`input.window` carries:
+
+- `id`, a hash of the scope and the event ids, which becomes the decision id;
+- `events`, oldest first, each with its `kind` and `seenAt`;
+- `reason`, the settle reason from the table above;
+- `waits`, how many times this window was held;
+- `dropped`, how many consequence and context events were shed;
+- `gap`, true when a source reported lost events, such as MCP `truncated: true`;
+- `settledAt`.
+
+## Kinds by agent
+
+These are starting points. Run the question sequence in `SKILL.md` on your own event names.
+
+- **Coding agent on a repo.** A comment that names the agent is `flush`. A merged pull request, a failed build and a finished deploy are `closing`. CI log lines and status changes are `consequence`. The agent's own commits and messages are `context`.
+- **Voice agent.** A final transcript is `flush`. Partial transcripts are `continuous`. Tool results are `consequence`. The agent's own speech is `context`.
+- **Inbox agent.** A message to the agent's address is `flush`. A new email that the agent should triage with no user act is `closing`. The user opening an email is `passive`, and the user sending a reply is `closing`. Delivery receipts are `consequence`.
+- **On-call agent.** A page or a fired alert is `closing`. Metric samples and log lines are `consequence`. An incident-channel message that mentions the agent is `flush`.
+- **Gesture app.** Hand and pointer motion are `continuous`. A gaze dwell is `passive`. Grabbing or releasing an object is `closing`. Physics and render results are `consequence`.

package/skills/attend/references/mcp.md

@@ -0,0 +1,132 @@
+# MCP Events sources
+
+`mcpEventsSource(client, options)` from `@acquiredintelligence/attend/mcp` turns one MCP Events subscription into a `Source`. It needs the peer dependencies `@modelcontextprotocol/sdk` and `zod` (3.25 or later, or 4).
+
+## Wire it
+
+```ts
+import { Client } from '@modelcontextprotocol/sdk/client/index.js';
+import { StdioClientTransport } from '@modelcontextprotocol/sdk/client/stdio.js';
+import { createAttend, memoryStore, routes } from '@acquiredintelligence/attend';
+import { mcpEventsSource } from '@acquiredintelligence/attend/mcp';
+
+const client = new Client({ name: 'my-agent', version: '1.0.0' });
+await client.connect(new StdioClientTransport({ command: 'node', args: ['./ci-events-server.js'] }));
+
+const attend = createAttend({
+  store: memoryStore(),
+  kind: (event) => (event.name === 'comment.created' ? 'flush' : 'consequence'),
+  judge: async () => ({ route: 'queue' }),
+  sink: routes({ interrupt: async () => {}, queue: async () => {}, note: async () => {}, ask: async () => {} }),
+  deadLetter: async () => {},
+});
+
+const controller = new AbortController();
+const source = mcpEventsSource(client, { name: 'repo.activity', arguments: { repo: 'acme/shop' } });
+await Promise.all([attend.run({ signal: controller.signal }), attend.attach('repo:acme/shop', source, { signal: controller.signal })]);
+```
+
+- One subscription feeds one scope. Pick the scope from the subscription's `arguments`, such as one scope per repo. A scope can take several sources; each keeps its own cursor under its `Source.key`, which for this source is `mcp:<name>:<arguments as sorted JSON>`.
+- Several subscriptions can share one `Client`. attend installs one notification handler for each of the five `notifications/events/*` methods the first time it uses a Client, records the JSON-RPC id of each `events/stream` request, and routes by `_meta["io.modelcontextprotocol/subscriptionId"]`. Do not replace those handlers.
+- Attach a given subscription to a scope from one process. Every batch commits the server's cursor with its events, and `attach` resumes from the committed cursor after a restart.
+
+## Options
+
+| Option | Default | Does |
+|---|---|---|
+| `name` | required | The event name from `events/list` |
+| `arguments` | none | The subscription's arguments |
+| `mode` | `'auto'` | `'auto'` streams when `events/list` lists `push` delivery for the event and polls otherwise. `'stream'` and `'poll'` force one. |
+| `maxAgeMs` | none | Passed through. Bounds replay when resuming from a cursor. |
+| `maxEvents` | none | Passed through as the poll page size |
+| `pollMs` | 10000 | Poll interval when the server sends no `nextPollMs` |
+| `maxBuffered` | 1000 | Stream notifications that may wait while an earlier one persists. Past it, the source drops what it holds, reports `overflow`, and reopens from the committed cursor so the server resends them. |
+| `idleTimeoutMs` | 300000 | How long a stream may go without any notification, heartbeats included. Past it, the source reports `idle` and reopens from the committed cursor. |
+| `clock` | the system clock | Pass the test's fake clock here too |
+| `onError` | ignore | Receives `{ kind: 'stream' }` for `notifications/events/error`, `{ kind: 'malformed' }` for a payload that failed validation, `{ kind: 'overflow' }`, `{ kind: 'idle' }`, and `{ kind: 'unrouted' }` for a notification under a subscription id no stream here opened |
+
+## What the source does with the protocol
+
+- `eventId` becomes `Event.id`, the occurrence's `name` becomes `Event.name`, `timestamp` becomes `Event.at`, and `data` becomes `Event.data`. `Event.text` stays unset, so `defaultNotice` prints the name and the JSON data.
+- `truncated: true` on a poll result or on `notifications/events/active` sets `window.gap`.
+- A poll result with `hasMore` polls again at once. Otherwise the source waits `nextPollMs`, or `pollMs`.
+- A malformed occurrence goes to `onError` and is skipped. Its cursor still advances.
+- A `notifications/events/terminated`, a stream request that returns, an overflow or an idle stream reopens the stream from the committed cursor after one second.
+
+## Errors
+
+`events/list`, `events/poll` and `events/stream` errors all follow this table.
+
+| Error | The source |
+|---|---|
+| `-32025` ResourceExhausted, or a request timeout | Throws it as a plain error. `attach` backs off through `retryBackoffMs` (the last rung repeated), traces `retrying` with stage `source`, and resubscribes from the committed cursor. |
+| `-32026` Unsupported on `events/stream` | Switches to `events/poll` in `auto` mode. In `stream` mode it ends the subscription with a `PermanentError`. |
+| `-32000` ConnectionClosed | The Client's transport closed. `attach` rejects with a `PermanentError` that says to reconnect the Client and attach again. |
+| `-32023` NotFound, `-32024` Forbidden, `-32027`, any other code | Ends the subscription. `attach` rejects with a `PermanentError` whose `cause` is the SDK error. |
+
+A rejected `attach` means the server refused the subscription or the Client closed. Reconnecting the Client and attaching again fixes the second; retrying the first gets the same answer, so log it and alert.
+
+## Filter events before they reach the scope
+
+`kind` cannot drop an event. To drop noise such as heartbeats, wrap the source and keep its key:
+
+```ts
+import type { Event, Source } from '@acquiredintelligence/attend';
+
+export const only = (source: Source, keep: (event: Event) => boolean): Source => ({
+  key: source.key,
+  subscribe: (cursor, emit, signal) => source.subscribe(cursor, (batch) => emit({ ...batch, events: batch.events.filter(keep) }), signal),
+});
+```
+
+The batch keeps its cursor, so dropped events never come back.
+
+## Test against an in-memory server
+
+A poll-only server over `InMemoryTransport` keeps a source test deterministic on a fake clock:
+
+```ts
+import { Client } from '@modelcontextprotocol/sdk/client/index.js';
+import { InMemoryTransport } from '@modelcontextprotocol/sdk/inMemory.js';
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import type { ServerCapabilities } from '@modelcontextprotocol/sdk/types.js';
+import { z } from 'zod/v4';
+
+export type Occurrence = { eventId: string; name: string; timestamp: string; data: Record<string, string | number | boolean> };
+
+const ListEvents = z.object({ method: z.literal('events/list') });
+const PollEvents = z.object({ method: z.literal('events/poll'), params: z.object({ name: z.string(), cursor: z.string().nullable() }) });
+
+/** A client connected to a server that serves `occurrences` from one poll event. Push to the array to publish more. */
+export async function pollServerClient(event: string, occurrences: Occurrence[]): Promise<Client> {
+  const capabilities: ServerCapabilities & { events: { listChanged: boolean } } = { events: { listChanged: true } };
+  const server = new Server({ name: 'test-events', version: '0.0.0' }, { capabilities });
+  server.setRequestHandler(ListEvents, () => ({ events: [{ name: event, delivery: ['poll'], inputSchema: { type: 'object' }, payloadSchema: { type: 'object' } }] }));
+  server.setRequestHandler(PollEvents, (request) => {
+    const from = Number(request.params.cursor ?? 0);
+    return { events: occurrences.slice(from), cursor: String(occurrences.length), truncated: false, hasMore: false, nextPollMs: 1000 };
+  });
+  const [clientTransport, serverTransport] = InMemoryTransport.createLinkedPair();
+  await server.connect(serverTransport);
+  const client = new Client({ name: 'test-agent', version: '0.0.0' });
+  await client.connect(clientTransport);
+  return client;
+}
+```
+
+Attach `mcpEventsSource(client, { name, clock })` with the same fake clock as `createAttend`. The client and the server talk through promise callbacks, so call `drain()` from `@acquiredintelligence/attend/testing` about four times after you attach, and again after each poll interval you advance, before you assert. Then advance past the settle deadline.
+
+## Typing note
+
+With `exactOptionalPropertyTypes` on, SDK 1.32's `StreamableHTTPClientTransport` does not typecheck as a `Transport`, because its `sessionId` getter can return `undefined`. `StdioClientTransport` and `InMemoryTransport` typecheck.
+
+## Serving decisions: attend serve
+
+`npx attend serve` runs attend as a sidecar. Events go in as NDJSON on `POST /v1/ingest`, and judged decisions come out on `/mcp` as MCP Events. Raw events never cross MCP.
+
+```sh
+npm install @acquiredintelligence/attend @modelcontextprotocol/server zod
+npx attend serve --store sqlite:attend.db --judge jev --kinds kinds.json --act-threshold 0.4
+```
+
+`kinds.json` maps event names to kinds, such as `{"message.created":"flush","build.failed":"closing"}`. Flags and their environment variables are in the README. Subscribe to `attention.decision` with `events/stream`, poll it with `events/poll`, or call the `attend_wait` tool in a loop from a host that cannot subscribe. In TypeScript, `decisionFeed` from `@acquiredintelligence/attend/mcp` keeps the cursor. Use `serve(attend, store, { listen })` from `@acquiredintelligence/attend/server` to run the same thing inside your own process.

package/skills/attend/references/sinks.md

@@ -0,0 +1,73 @@
+# Sinks
+
+A sink is `{ deliver(decision, signal) }`. attend calls it at least once per decision, one decision at a time per scope, oldest first. Build it with `routes()`, which takes one handler per delivered route and fails to compile when one is missing.
+
+## The decision
+
+| Field | Holds |
+|---|---|
+| `id` | The window id: a hash of the scope and the window's event ids, so it is unique across scopes. The same window redelivered has the same id. A merged window has a new one. |
+| `scope` | The scope key |
+| `route` | `interrupt`, `queue`, `note` or `ask`. A sink never sees `skip` or `wait`. |
+| `probabilities` | One number per route, summing to 1. Routes that were not offered are 0. |
+| `predicates` | The judge's answer to each predicate, by name |
+| `window` | The settled window, with `events` oldest first |
+| `at` | attend's clock when the judge answered |
+
+## Wiring template
+
+Map each route to an operation in the host. The decision id makes each operation idempotent.
+
+```ts
+import { createAttend, defaultNotice, routes, type DeadLetter, type Decision, type Event, type Judge, type Kind, type ScopeStore } from '@acquiredintelligence/attend';
+
+export interface Host {
+  /** Deliver now, even mid-turn: steer or cancel the current turn. */
+  interrupt(key: string, text: string): Promise<void>;
+  /** Deliver as the next user turn once the current turn ends. */
+  enqueue(key: string, text: string): Promise<void>;
+  /** Add to the next turn's context without starting a turn. */
+  addContext(key: string, text: string): Promise<void>;
+  /** Show the user a prompt that calls the agent in if they accept. */
+  offer(key: string, text: string): Promise<void>;
+  saveDeadLetter(key: string, letter: DeadLetter): Promise<void>;
+}
+
+export function wire(host: Host, store: ScopeStore, judge: Judge, kind: (event: Event) => Kind) {
+  return createAttend({
+    store,
+    judge,
+    kind,
+    sink: routes({
+      interrupt: (d: Decision) => host.interrupt(d.id, defaultNotice(d)),
+      queue: (d: Decision) => host.enqueue(d.id, defaultNotice(d)),
+      note: (d: Decision) => host.addContext(d.id, defaultNotice(d)),
+      ask: (d: Decision) => host.offer(d.id, defaultNotice(d)),
+    }),
+    deadLetter: (letter) => host.saveDeadLetter(letter.id, letter),
+  });
+}
+```
+
+Each `Host` method records `key` and returns early when it has seen the key before: a unique index on an inbox table, a set of delivered keys in the agent's runtime, or an id on the message the host sends.
+
+## Routes in common hosts
+
+| Host | `interrupt` | `queue` | `note` | `ask` |
+|---|---|---|---|---|
+| Chat host | Steer the running turn, or start one now | Append a user turn after the current one | Add a system note to the next turn | Show a "Ask the agent?" chip |
+| Coding agent | Stop the current step and read the notice | Add to the task queue | Add to the session context | Post a suggestion the user can accept |
+| Voice agent | Barge in at the next pause | Speak when the user finishes | Hold as context and stay silent | Play a short sound or show a hint |
+| Server-side agent | Push to the agent's high-priority queue | Push to its normal queue | Write to its memory store | Notify the user's client |
+
+## Failures
+
+- Throw to retry. attend retries through `retryBackoffMs`, then turns the decision into a dead letter.
+- Throw `PermanentError` from `@acquiredintelligence/attend` to dead-letter at once, for a decision the host can never take.
+- Each delivery holds a lease of `deliveryTimeoutMs`. attend aborts `signal` when it expires and counts it as a failed attempt. Stop when `signal` aborts.
+- One stuck delivery holds back later decisions in the same scope, because delivery is in order. Dead letters go through their own lane, so a failing `deadLetter` never holds back decisions.
+- Nothing is dropped. A scope whose sink stays down fills its decision lane to `maxOutbox`, and one whose dead-letter handler stays down fills its dead-letter lane to `maxDeadLetters`. Either cap makes `push` and a source's `emit` reject with `OutboxFullError` until the lane drains, and `attach` backs off and resubscribes on its own.
+
+## Dead letters
+
+`deadLetter(letter, signal)` is optional. Without it, each dead letter becomes a final row in the decision log, readable with `attend.decisions({ kinds: ['deadLetter'] }, …)` and as `attention.deadLetter` over MCP. Pass a handler when the app has a place to put them. A `DeadLetter` has `stage` (`judge` or `sink`), `window`, `decision` (null when the judge gave up), `message`, `permanent` and `attempts`. attend retries the handler with capped backoff until it succeeds and never drops a letter. Write the letter to durable storage, keyed on its `id`, and alert on it from there.

package/skills/attend/references/stores.md

@@ -0,0 +1,90 @@
+# Stores
+
+A store holds each scope's latest snapshot and the short tail of inputs committed since, a due index, and the decision log. A write names the version it read and lands only if that is still the stored version, so concurrent writers never overwrite each other. Every store passes the same conformance suite and crash suite.
+
+## Memory
+
+```ts
+import { memoryStore } from '@acquiredintelligence/attend';
+
+export const store = memoryStore();
+```
+
+State lives in the process and is lost when it exits. Use it for tests, demos, browser apps and short-lived processes.
+
+## SQLite
+
+```ts
+import { DatabaseSync } from 'node:sqlite';
+import { sqliteStore } from '@acquiredintelligence/attend/sqlite';
+
+export const store = sqliteStore(new DatabaseSync('attend.db'));
+```
+
+- Takes a `node:sqlite` `DatabaseSync`, a `bun:sqlite` `Database`, or any object with the same `exec` and `prepare`, so importing `@acquiredintelligence/attend/sqlite` loads no driver. The conformance and crash suites pass under Bun 1.4 on `bun:sqlite`.
+- Creates its table and index on construction. A second store over the same file uses what the first created.
+- `prefix` (default `attend_`) sets the table names. Letters, digits and underscores only.
+- Calls are synchronous and block the event loop for their duration.
+- `sqliteStore({ file: 'attend.db', worker: true })` runs the database on a worker thread so commits never block the event loop.
+- Several processes on one host can share the file. Keep the file off network filesystems.
+
+## Postgres
+
+```ts
+import pg from 'pg';
+import { migrate, postgresStore } from '@acquiredintelligence/attend/postgres';
+
+const pool = new pg.Pool({ connectionString: process.env.DATABASE_URL });
+await migrate(pool);
+export const store = postgresStore(pool);
+```
+
+- Takes any client with `query(text, values)`, such as a `pg` `Pool` or `Client`.
+- Run `migrate()` once at deploy or startup, with a role that can create tables. It is idempotent and safe to run from several processes at once. The store itself runs no DDL and needs only `SELECT`, `INSERT`, `UPDATE` and `DELETE`.
+- `prefix` (default `attend_`) must be lowercase letters, digits and underscores. To use another schema, set the connection's `search_path`.
+- Safe for many replicas. Each runner sweeps for due scopes, and the version check lets one replica win each write. One statement commits a group of scopes together.
+
+## Redis
+
+```ts
+import { createClient } from 'redis';
+import { redisStore } from '@acquiredintelligence/attend/redis';
+
+const client = createClient({ url: process.env.REDIS_URL ?? 'redis://localhost:6379' });
+await client.connect();
+export const store = redisStore((args) => client.sendCommand(args));
+```
+
+- Takes a function that sends one command. With ioredis, pass `([command, ...args]) => client.call(command, ...args)`.
+- Needs Redis 6.2 or later. One script validates every version in a group, then changes the scopes, the due index and the decision stream together.
+- Durable only as far as the server's persistence settings (AOF or RDB).
+- On Redis Cluster, every key a group touches and the shared due key must hash to one slot. Use a prefix with a hash tag: `redisStore(send, { prefix: 'attend:{app}:' })`. That puts every scope on one shard.
+
+## Shared logs
+
+Each store module also exports an `EventLog`: `memoryLog` from `@acquiredintelligence/attend`, `sqliteLog`, `postgresLog` and `redisLog`. Use one when producers live in other processes and you want a durable log in front of attend. Producers call `log.append(scope, events)`, and one process attaches the log:
+
+```ts
+import { createAttend, logSource, memoryLog, memoryStore, routes } from '@acquiredintelligence/attend';
+
+const log = memoryLog();
+const attend = createAttend({
+  store: memoryStore(),
+  kind: () => 'closing',
+  judge: async () => ({ route: 'queue' }),
+  sink: routes({ interrupt: async () => {}, queue: async () => {}, note: async () => {}, ask: async () => {} }),
+  deadLetter: async () => {},
+});
+
+const controller = new AbortController();
+await log.append('inbox:42', [{ id: 'm1', at: Date.now(), name: 'message.created', data: {}, text: 'Is the export done?' }]);
+await Promise.all([attend.run({ signal: controller.signal }), attend.attach('inbox:42', logSource(log, 'inbox:42'), { signal: controller.signal })]);
+```
+
+- `redisLog` waits for new entries with `XREAD BLOCK` only when you pass `blockingSend`, a send function on its own connection. Without it, `read` returns at once and `logSource` polls every `pollMs` (default 250).
+- `postgresLog` polls every `pollMs` (default 100) while a read blocks. `sqliteLog` never blocks.
+- The log may deliver an event more than once. The scope dedups by `event.id`.
+
+## Choosing between push and a log
+
+`push` writes the scope's state directly from any process, with a version check. It needs no log, and it contends when many producers write one scope at a high rate: a writer that loses backs off a few milliseconds and tries again, and after eight losses `push` rejects with `ConflictError`. A log takes those writes off the scope, and one attached source moves them in.