@acquiredintelligence/attend 0.0.0-stage → 0.1.0

package/dist/llm.d.ts

@@ -0,0 +1,164 @@
+/**
+ * `attend/llm`: a judge over any model that can reply in JSON matching a schema. There is no SDK
+ * dependency: you pass the one structured-output call as `complete`. When the judge input carries
+ * images, `complete` receives them as `images` to place after the prompt in the model's own block
+ * format.
+ *
+ * With `contextTokens`, the judge declares a budget, and a rendered window over it loses its
+ * oldest consequence and context events first; acts and flushes always stay. A rejection that
+ * names the context length is retried once with the window halved, so let a vendor SDK's error
+ * propagate from `complete` with its `status`.
+ *
+ * Anthropic:
+ *
+ * ```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');
+ *   },
+ * });
+ * ```
+ *
+ * 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);
+ *   },
+ * });
+ * ```
+ *
+ * Gemini, through `@google/genai`. Unverified: 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');
+ *   },
+ * });
+ * ```
+ *
+ * Vercel AI SDK. Unverified: 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;
+ *   },
+ * });
+ * ```
+ */
+import type { JudgeBudget } from './core/types.js';
+import { type JsonObject, type Judge, type JudgeImage, type JudgeInput, type Route } from './types.js';
+export { DEFAULT_CRITERIA, DEFAULT_SYSTEM } from './internal/prompt.js';
+export interface CompleteRequest {
+    system: string;
+    prompt: string;
+    /** From the judge input; empty when it carries none. Place them after the prompt. */
+    images: JudgeImage[];
+    /**
+     * JSON Schema for `{ route, probabilities, predicates }`. Strict-mode safe: every object sets
+     * `additionalProperties: false` and requires all of its properties. `predicates` is left out
+     * when no predicate is asked.
+     */
+    schema: JsonObject;
+    signal: AbortSignal;
+}
+/** One structured-output call. Resolve with the parsed JSON reply; throw a `PermanentError` on a refusal, and let other errors propagate as thrown. */
+export type Complete = (request: CompleteRequest) => Promise<unknown>;
+export interface LlmJudgeOptions {
+    complete: Complete;
+    /** Replaces `DEFAULT_SYSTEM`. The routes on offer and their criteria are appended either way, since they change per call. */
+    system?: string;
+    /** Per-route criteria. A criterion on the judge input wins over these, and `DEFAULT_CRITERIA` fills the rest. */
+    criteria?: Partial<Record<Route, string>>;
+    /** The model's context window in tokens. Set it to declare a budget. */
+    contextTokens?: number;
+    /**
+     * Builds the user prompt from the judge input, once its window is trimmed to the budget or halved.
+     * The default renders the window, facts, recent routes and predicate questions as compact JSON, 64 events per macrotask.
+     */
+    render?: (input: JudgeInput) => string;
+}
+/** With `contextTokens`, `budget.reservedTokens` is measured from the system prompt with every route on offer, plus the schema. */
+export declare function llmJudge(options: LlmJudgeOptions): Judge & {
+    budget?: JudgeBudget;
+};
+//# sourceMappingURL=llm.d.ts.map

package/dist/llm.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"llm.d.ts","sourceRoot":"","sources":["../src/llm.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8HG;AACH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAC;AAGnD,OAAO,EAAU,KAAK,UAAU,EAAE,KAAK,KAAK,EAAE,KAAK,UAAU,EAAE,KAAK,UAAU,EAAoC,KAAK,KAAK,EAAE,MAAM,YAAY,CAAC;AAEjJ,OAAO,EAAE,gBAAgB,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAExE,MAAM,WAAW,eAAe;IAC9B,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf,qFAAqF;IACrF,MAAM,EAAE,UAAU,EAAE,CAAC;IACrB;;;;OAIG;IACH,MAAM,EAAE,UAAU,CAAC;IACnB,MAAM,EAAE,WAAW,CAAC;CACrB;AAED,uJAAuJ;AACvJ,MAAM,MAAM,QAAQ,GAAG,CAAC,OAAO,EAAE,eAAe,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;AAEtE,MAAM,WAAW,eAAe;IAC9B,QAAQ,EAAE,QAAQ,CAAC;IACnB,6HAA6H;IAC7H,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,iHAAiH;IACjH,QAAQ,CAAC,EAAE,OAAO,CAAC,MAAM,CAAC,KAAK,EAAE,MAAM,CAAC,CAAC,CAAC;IAC1C,wEAAwE;IACxE,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB;;;OAGG;IACH,MAAM,CAAC,EAAE,CAAC,KAAK,EAAE,UAAU,KAAK,MAAM,CAAC;CACxC;AAED,mIAAmI;AACnI,wBAAgB,QAAQ,CAAC,OAAO,EAAE,eAAe,GAAG,KAAK,GAAG;IAAE,MAAM,CAAC,EAAE,WAAW,CAAA;CAAE,CAkCnF"}

package/dist/llm.js

@@ -0,0 +1,79 @@
+import { DEFAULT_SYSTEM, renderBytes, renderWithin, resolveCriteria, sendHalving, stateText, tokensOf } from './internal/prompt.js';
+import { isRecord } from './internal/shared.js';
+import { ROUTES } from './types.js';
+export { DEFAULT_CRITERIA, DEFAULT_SYSTEM } from './internal/prompt.js';
+/** With `contextTokens`, `budget.reservedTokens` is measured from the system prompt with every route on offer, plus the schema. */
+export function llmJudge(options) {
+    const { complete, system = DEFAULT_SYSTEM, criteria, render, contextTokens } = options;
+    const reservedTokens = tokensOf(systemPrompt(system, resolveCriteria(ROUTES.map((route) => ({ route })), criteria), true) + JSON.stringify(judgmentSchema([...ROUTES], [])));
+    if (contextTokens !== undefined && !(contextTokens > reservedTokens))
+        throw new RangeError(`llmJudge: contextTokens must be more than the ${reservedTokens} tokens its own prompt takes, got ${contextTokens}`);
+    const budget = contextTokens === undefined ? undefined : { contextTokens, reservedTokens };
+    const judge = async (input, signal) => {
+        const routes = resolveCriteria(input.routes, criteria);
+        const offered = routes.map((r) => r.route);
+        const asked = input.predicates.map((p) => p.name);
+        const rendered = await renderWithin(input, renderBytes(budget), signal);
+        signal.throwIfAborted();
+        const reply = await sendHalving(rendered, (r) => complete({
+            system: systemPrompt(system, routes, asked.length > 0),
+            prompt: render === undefined ? stateText(r) : render(r.input),
+            images: input.images ?? [],
+            schema: judgmentSchema(offered, asked),
+            signal,
+        }));
+        return parseReply(reply, offered, asked);
+    };
+    if (budget !== undefined)
+        judge.budget = budget;
+    return judge;
+}
+function systemPrompt(base, routes, asksPredicates) {
+    const answer = asksPredicates
+        ? 'Answer with the route you choose, a probability from 0 to 1 for each route on offer, and for each entry under predicates the probability from 0 to 1 that the answer to its question is yes.'
+        : 'Answer with the route you choose and a probability from 0 to 1 for each route on offer.';
+    return [base, '', 'Routes on offer:', ...routes.map((r) => `- ${r.route}: ${r.criterion}`), '', answer].join('\n');
+}
+/** No `minimum`/`maximum`: Anthropic's structured outputs reject numeric bounds, so the range lives in the system prompt. */
+function judgmentSchema(routes, predicates) {
+    const numbers = (keys) => ({
+        type: 'object',
+        properties: Object.fromEntries(keys.map((key) => [key, { type: 'number' }])),
+        required: keys,
+        additionalProperties: false,
+    });
+    const properties = { route: { type: 'string', enum: routes }, probabilities: numbers(routes) };
+    if (predicates.length > 0)
+        properties.predicates = numbers(predicates);
+    return { type: 'object', properties, required: Object.keys(properties), additionalProperties: false };
+}
+/**
+ * Only the route is load-bearing. Probabilities and predicates keep the finite numbers found
+ * under known keys and drop the rest, because the reducer renormalises and a garbled ride-along
+ * should not cost a retry.
+ */
+function parseReply(reply, routes, predicates) {
+    if (!isRecord(reply))
+        throw new Error(`llmJudge: expected a JSON object, got ${describe(reply)}`);
+    const route = routes.find((r) => r === reply.route);
+    if (route === undefined)
+        throw new Error(`llmJudge: route ${JSON.stringify(reply.route)} is not one of ${routes.join(', ')}`);
+    return { route, probabilities: numbersAt(reply.probabilities, routes), predicates: numbersAt(reply.predicates, predicates) };
+}
+function numbersAt(value, keys) {
+    const out = {};
+    if (!isRecord(value))
+        return out;
+    for (const key of keys) {
+        const n = value[key];
+        if (typeof n === 'number' && Number.isFinite(n))
+            out[key] = n;
+    }
+    return out;
+}
+function describe(value) {
+    if (value === null)
+        return 'null';
+    return Array.isArray(value) ? 'an array' : typeof value;
+}
+//# sourceMappingURL=llm.js.map

package/dist/llm.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"llm.js","sourceRoot":"","sources":["../src/llm.ts"],"names":[],"mappings":"AAgIA,OAAO,EAAE,cAAc,EAAE,WAAW,EAAE,YAAY,EAAE,eAAe,EAAE,WAAW,EAAE,SAAS,EAAE,QAAQ,EAAE,MAAM,sBAAsB,CAAC;AACpI,OAAO,EAAE,QAAQ,EAAE,MAAM,sBAAsB,CAAC;AAChD,OAAO,EAAE,MAAM,EAA+G,MAAM,YAAY,CAAC;AAEjJ,OAAO,EAAE,gBAAgB,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAkCxE,mIAAmI;AACnI,MAAM,UAAU,QAAQ,CAAC,OAAwB;IAC/C,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,cAAc,EAAE,QAAQ,EAAE,MAAM,EAAE,aAAa,EAAE,GAAG,OAAO,CAAC;IACvF,MAAM,cAAc,GAAG,QAAQ,CAC7B,YAAY,CACV,MAAM,EACN,eAAe,CACb,MAAM,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,CAAC,EAClC,QAAQ,CACT,EACD,IAAI,CACL,GAAG,IAAI,CAAC,SAAS,CAAC,cAAc,CAAC,CAAC,GAAG,MAAM,CAAC,EAAE,EAAE,CAAC,CAAC,CACpD,CAAC;IACF,IAAI,aAAa,KAAK,SAAS,IAAI,CAAC,CAAC,aAAa,GAAG,cAAc,CAAC;QAClE,MAAM,IAAI,UAAU,CAAC,iDAAiD,cAAc,qCAAqC,aAAa,EAAE,CAAC,CAAC;IAC5I,MAAM,MAAM,GAAG,aAAa,KAAK,SAAS,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,EAAE,aAAa,EAAE,cAAc,EAAE,CAAC;IAC3F,MAAM,KAAK,GAAqC,KAAK,EAAE,KAAK,EAAE,MAAM,EAAE,EAAE;QACtE,MAAM,MAAM,GAAG,eAAe,CAAC,KAAK,CAAC,MAAM,EAAE,QAAQ,CAAC,CAAC;QACvD,MAAM,OAAO,GAAG,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC;QAC3C,MAAM,KAAK,GAAG,KAAK,CAAC,UAAU,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC;QAClD,MAAM,QAAQ,GAAG,MAAM,YAAY,CAAC,KAAK,EAAE,WAAW,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC,CAAC;QACxE,MAAM,CAAC,cAAc,EAAE,CAAC;QACxB,MAAM,KAAK,GAAG,MAAM,WAAW,CAAC,QAAQ,EAAE,CAAC,CAAC,EAAE,EAAE,CAC9C,QAAQ,CAAC;YACP,MAAM,EAAE,YAAY,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,CAAC,MAAM,GAAG,CAAC,CAAC;YACtD,MAAM,EAAE,MAAM,KAAK,SAAS,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,KAAK,CAAC;YAC7D,MAAM,EAAE,KAAK,CAAC,MAAM,IAAI,EAAE;YAC1B,MAAM,EAAE,cAAc,CAAC,OAAO,EAAE,KAAK,CAAC;YACtC,MAAM;SACP,CAAC,CACH,CAAC;QACF,OAAO,UAAU,CAAC,KAAK,EAAE,OAAO,EAAE,KAAK,CAAC,CAAC;IAC3C,CAAC,CAAC;IACF,IAAI,MAAM,KAAK,SAAS;QAAE,KAAK,CAAC,MAAM,GAAG,MAAM,CAAC;IAChD,OAAO,KAAK,CAAC;AACf,CAAC;AAED,SAAS,YAAY,CAAC,IAAY,EAAE,MAAgC,EAAE,cAAuB;IAC3F,MAAM,MAAM,GAAG,cAAc;QAC3B,CAAC,CAAC,8LAA8L;QAChM,CAAC,CAAC,yFAAyF,CAAC;IAC9F,OAAO,CAAC,IAAI,EAAE,EAAE,EAAE,kBAAkB,EAAE,GAAG,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,KAAK,CAAC,CAAC,KAAK,KAAK,CAAC,CAAC,SAAS,EAAE,CAAC,EAAE,EAAE,EAAE,MAAM,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AACrH,CAAC;AAED,6HAA6H;AAC7H,SAAS,cAAc,CAAC,MAAe,EAAE,UAAoB;IAC3D,MAAM,OAAO,GAAG,CAAC,IAAc,EAAc,EAAE,CAAC,CAAC;QAC/C,IAAI,EAAE,QAAQ;QACd,UAAU,EAAE,MAAM,CAAC,WAAW,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,GAAG,EAAwB,EAAE,CAAC,CAAC,GAAG,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,CAAC,CAAC,CAAC;QAClG,QAAQ,EAAE,IAAI;QACd,oBAAoB,EAAE,KAAK;KAC5B,CAAC,CAAC;IACH,MAAM,UAAU,GAAe,EAAE,KAAK,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,IAAI,EAAE,MAAM,EAAE,EAAE,aAAa,EAAE,OAAO,CAAC,MAAM,CAAC,EAAE,CAAC;IAC3G,IAAI,UAAU,CAAC,MAAM,GAAG,CAAC;QAAE,UAAU,CAAC,UAAU,GAAG,OAAO,CAAC,UAAU,CAAC,CAAC;IACvE,OAAO,EAAE,IAAI,EAAE,QAAQ,EAAE,UAAU,EAAE,QAAQ,EAAE,MAAM,CAAC,IAAI,CAAC,UAAU,CAAC,EAAE,oBAAoB,EAAE,KAAK,EAAE,CAAC;AACxG,CAAC;AAED;;;;GAIG;AACH,SAAS,UAAU,CAAC,KAAc,EAAE,MAAe,EAAE,UAAoB;IACvE,IAAI,CAAC,QAAQ,CAAC,KAAK,CAAC;QAAE,MAAM,IAAI,KAAK,CAAC,yCAAyC,QAAQ,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC;IAClG,MAAM,KAAK,GAAG,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,KAAK,KAAK,CAAC,KAAK,CAAC,CAAC;IACpD,IAAI,KAAK,KAAK,SAAS;QAAE,MAAM,IAAI,KAAK,CAAC,mBAAmB,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,KAAK,CAAC,kBAAkB,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;IAC9H,OAAO,EAAE,KAAK,EAAE,aAAa,EAAE,SAAS,CAAC,KAAK,CAAC,aAAa,EAAE,MAAM,CAAC,EAAE,UAAU,EAAE,SAAS,CAAC,KAAK,CAAC,UAAU,EAAE,UAAU,CAAC,EAAE,CAAC;AAC/H,CAAC;AAED,SAAS,SAAS,CAAC,KAAc,EAAE,IAAc;IAC/C,MAAM,GAAG,GAA2B,EAAE,CAAC;IACvC,IAAI,CAAC,QAAQ,CAAC,KAAK,CAAC;QAAE,OAAO,GAAG,CAAC;IACjC,KAAK,MAAM,GAAG,IAAI,IAAI,EAAE,CAAC;QACvB,MAAM,CAAC,GAAG,KAAK,CAAC,GAAG,CAAC,CAAC;QACrB,IAAI,OAAO,CAAC,KAAK,QAAQ,IAAI,MAAM,CAAC,QAAQ,CAAC,CAAC,CAAC;YAAE,GAAG,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;IAChE,CAAC;IACD,OAAO,GAAG,CAAC;AACb,CAAC;AAED,SAAS,QAAQ,CAAC,KAAc;IAC9B,IAAI,KAAK,KAAK,IAAI;QAAE,OAAO,MAAM,CAAC;IAClC,OAAO,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,UAAU,CAAC,CAAC,CAAC,OAAO,KAAK,CAAC;AAC1D,CAAC"}

package/dist/mcp.d.ts

@@ -0,0 +1,130 @@
+/**
+ * `attend/mcp`: an MCP Events subscription (`events/stream` or `events/poll`) as a
+ * `Source`. Peer dependency: `@modelcontextprotocol/sdk`. The draft's wire shapes stay
+ * inside this module; the public surface takes an SDK `Client` and emits domain events.
+ *
+ * The source installs one notification handler on the Client for each of the five
+ * `notifications/events/*` methods (`active`, `event`, `heartbeat`, `error`, `terminated`)
+ * the first time it is used on that Client, and routes by subscription id from there. The
+ * app must not replace those handlers.
+ *
+ * When the Client's transport closes, the SDK fails every open request with
+ * `ConnectionClosed` (-32000). The source turns that into a `PermanentError`, so `attach`
+ * rejects: the app must reconnect the Client (or make a new one) and attach again. A source
+ * waiting between polls or before a reopen is woken by the close and rejects the same way.
+ */
+import type { Client } from '@modelcontextprotocol/sdk/client/index.js';
+import type { AttendEventName, AttentionDeadLetterData, AttentionDecisionData, DeadLetterArguments, DecisionArguments } from './server/types.js';
+import type { Clock, JsonObject, Source } from './types.js';
+export interface McpEventsOptions {
+    /** An event name from `events/list`. */
+    name: string;
+    arguments?: JsonObject;
+    /** `auto` streams when `events/list` says the event supports `push`, else polls. Default `auto`. */
+    mode?: 'stream' | 'poll' | 'auto';
+    /** Bound on replay when resuming from a cursor; passed through as `maxAgeMs`. */
+    maxAgeMs?: number;
+    /** Poll page size; passed through as `maxEvents`. */
+    maxEvents?: number;
+    /** Poll interval when the server sends no `nextPollMs`. Default 10000. */
+    pollMs?: number;
+    /**
+     * How many stream notifications may wait while `emit` persists earlier ones. Past that, the
+     * source stops the stream, persists everything it holds, reports `overflow`, and reopens from
+     * the committed cursor, so the server sends the rest again. Notifications that arrive after
+     * the stop are lost only for an event type the server cannot replay from a cursor. Default 1000.
+     */
+    maxBuffered?: number;
+    /**
+     * How long a stream may go without any notification, heartbeats included, before the source
+     * treats it as dead: it reports `idle`, aborts the stream and reopens from the committed
+     * cursor. Default 300000.
+     */
+    idleTimeoutMs?: number;
+    clock?: Clock;
+    /** Everything the source survives: a server error notification, a skipped payload, an overflow, an idle stream, a stray notification. */
+    onError?: (error: McpEventsError) => void;
+}
+export type McpEventsError = 
+/** The server's `notifications/events/error`; the stream stays open. */
+{
+    kind: 'stream';
+    code: number;
+    message: string;
+    data: unknown;
+}
+/** A payload that failed validation and was skipped, with its cursor kept. */
+ | {
+    kind: 'malformed';
+    method: string;
+    message: string;
+    payload: unknown;
+}
+/**
+ * `buffered` notifications were waiting on `emit`; they are persisted, then the stream reopens
+ * from the committed cursor after `reopenMs`: at once when the overflowed stream moved that
+ * cursor, else after the reopen pause, since a server that cannot resume from a cursor would
+ * send the same backlog again.
+ */
+ | {
+    kind: 'overflow';
+    buffered: number;
+    reopenMs: number;
+}
+/** Nothing arrived for `idleTimeoutMs`; the stream reopens from the committed cursor. */
+ | {
+    kind: 'idle';
+}
+/** A notification on this Client named a subscription that no live stream here opened. */
+ | {
+    kind: 'unrouted';
+    method: string;
+    subscriptionId: string | null;
+};
+/**
+ * One subscription (name + arguments) as a `Source`, keyed `mcp:<name>:<arguments as sorted
+ * JSON>`. It holds no cursor of its own: every emit carries the server's cursor, the record
+ * persists it, and every open resumes from the committed one. `eventId` becomes `Event.id`, so
+ * the record's seen ring dedups redelivery. `truncated` becomes the batch's `truncated`, which
+ * marks the window as a gap.
+ *
+ * The subscription runs until `signal` aborts. A terminated or idle stream reopens from the last
+ * committed cursor after a short pause; an overflowed one at once, when it moved that cursor. A request error that the server says to
+ * retry (-32025, a request timeout) is thrown as a plain Error, so `attach` backs off through the
+ * app's `retryBackoffMs` and resubscribes; any other error, and a closed Client, is thrown as a
+ * `PermanentError` with the SDK error as its `cause`, and `attach` rejects.
+ */
+export declare function mcpEventsSource(client: Client, options: McpEventsOptions): Source;
+/** Options for consuming decisions with a durable cursor. */
+export interface DecisionFeedOptions {
+    /** Default 'attention.decision'. */
+    name?: AttendEventName;
+    arguments?: DecisionArguments | DeadLetterArguments;
+    /** The last cursor persisted. Null starts from now. */
+    cursor: string | null;
+    maxAgeMs?: number;
+    /** `auto` streams when `events/list` offers push, else polls. Default `auto`. */
+    mode?: 'stream' | 'poll' | 'auto';
+    /** A stream with no frame for this long counts as dead (twice the heartbeat). Default 30,000. */
+    idleTimeoutMs?: number;
+    signal: AbortSignal;
+}
+/** Persist `cursor` from every item, `cursor` items included, before acting on the next one. Dedup on `eventId`. */
+export type DecisionFeedItem = {
+    kind: 'decision';
+    eventId: string;
+    data: AttentionDecisionData;
+    cursor: string | null;
+} | {
+    kind: 'deadLetter';
+    eventId: string;
+    data: AttentionDeadLetterData;
+    cursor: string | null;
+} | {
+    kind: 'cursor';
+    cursor: string | null;
+    truncated: boolean;
+};
+/** Subscribes through `mcpEventsSource` and yields one item at a time; the subscription waits while the caller handles an item. */
+export declare function decisionFeed(client: Client, options: DecisionFeedOptions): AsyncIterable<DecisionFeedItem>;
+//# sourceMappingURL=mcp.d.ts.map

package/dist/mcp.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mcp.d.ts","sourceRoot":"","sources":["../src/mcp.ts"],"names":[],"mappings":"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"}