@nxgt/ai-alxia 0.0.0-stage → 0.1.0

package/dist/wire.d.ts

@@ -0,0 +1,275 @@
+import { type AgentEvent } from '@nxgt/ai-core';
+import { z } from 'zod';
+/** The code a client sees for a failure that has none of its own. */
+export declare const INTERNAL_ERROR = "INTERNAL_ERROR";
+/** The code of a thrown value: an `AiError`'s, else `INTERNAL_ERROR`. */
+export declare function codeOf(error: unknown): string;
+/** A tool result as sent: a failure is its code, with no message and no issues. */
+export declare const wireToolResultSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    isError: z.ZodLiteral<false>;
+    output: z.ZodUnknown;
+    type: z.ZodLiteral<"tool-result">;
+    callId: z.ZodString;
+    name: z.ZodString;
+}, z.core.$strip>, z.ZodObject<{
+    isError: z.ZodLiteral<true>;
+    error: z.ZodObject<{
+        code: z.ZodString;
+    }, z.core.$strip>;
+    type: z.ZodLiteral<"tool-result">;
+    callId: z.ZodString;
+    name: z.ZodString;
+}, z.core.$strip>], "isError">;
+/** Each wire event by its `type`, which is also its SSE `event:` name. */
+export declare const wireEventSchemas: {
+    readonly 'step-start': z.ZodObject<{
+        type: z.ZodLiteral<"step-start">;
+        step: z.ZodNumber;
+        runId: z.ZodString;
+    }, z.core.$strip>;
+    readonly 'text-delta': z.ZodObject<{
+        type: z.ZodLiteral<"text-delta">;
+        text: z.ZodString;
+        start: z.ZodOptional<z.ZodLiteral<true>>;
+    }, z.core.$strip>;
+    readonly 'thinking-delta': z.ZodObject<{
+        type: z.ZodLiteral<"thinking-delta">;
+        text: z.ZodString;
+        start: z.ZodOptional<z.ZodLiteral<true>>;
+        signature: z.ZodOptional<z.ZodString>;
+        redacted: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>;
+    readonly 'tool-call': z.ZodObject<{
+        type: z.ZodLiteral<"tool-call">;
+        id: z.ZodString;
+        name: z.ZodString;
+        input: z.ZodUnknown;
+    }, z.core.$strip>;
+    readonly 'tool-result': z.ZodObject<{
+        type: z.ZodLiteral<"tool-result">;
+        result: z.ZodDiscriminatedUnion<[z.ZodObject<{
+            isError: z.ZodLiteral<false>;
+            output: z.ZodUnknown;
+            type: z.ZodLiteral<"tool-result">;
+            callId: z.ZodString;
+            name: z.ZodString;
+        }, z.core.$strip>, z.ZodObject<{
+            isError: z.ZodLiteral<true>;
+            error: z.ZodObject<{
+                code: z.ZodString;
+            }, z.core.$strip>;
+            type: z.ZodLiteral<"tool-result">;
+            callId: z.ZodString;
+            name: z.ZodString;
+        }, z.core.$strip>], "isError">;
+    }, z.core.$strip>;
+    readonly 'proposed-action': z.ZodObject<{
+        type: z.ZodLiteral<"proposed-action">;
+        action: z.ZodObject<{
+            type: z.ZodLiteral<"proposed-action">;
+            id: z.ZodString;
+            tool: z.ZodString;
+            input: z.ZodUnknown;
+            summary: z.ZodOptional<z.ZodString>;
+            expiresAt: z.ZodNumber;
+        }, z.core.$strip>;
+    }, z.core.$strip>;
+    readonly message: z.ZodObject<{
+        type: z.ZodLiteral<"message">;
+        message: z.ZodObject<{
+            role: z.ZodEnum<{
+                tool: "tool";
+                user: "user";
+                assistant: "assistant";
+            }>;
+            parts: z.ZodArray<z.ZodUnion<readonly [z.ZodObject<{
+                type: z.ZodLiteral<"text">;
+                text: z.ZodString;
+            }, z.core.$strip>, z.ZodObject<{
+                type: z.ZodLiteral<"thinking">;
+                text: z.ZodString;
+                signature: z.ZodOptional<z.ZodString>;
+                redacted: z.ZodOptional<z.ZodString>;
+            }, z.core.$strip>, z.ZodObject<{
+                type: z.ZodLiteral<"tool-call">;
+                id: z.ZodString;
+                name: z.ZodString;
+                input: z.ZodUnknown;
+            }, z.core.$strip>, z.ZodDiscriminatedUnion<[z.ZodObject<{
+                isError: z.ZodLiteral<false>;
+                output: z.ZodUnknown;
+                type: z.ZodLiteral<"tool-result">;
+                callId: z.ZodString;
+                name: z.ZodString;
+            }, z.core.$strip>, z.ZodObject<{
+                isError: z.ZodLiteral<true>;
+                error: z.ZodObject<{
+                    code: z.ZodString;
+                }, z.core.$strip>;
+                type: z.ZodLiteral<"tool-result">;
+                callId: z.ZodString;
+                name: z.ZodString;
+            }, z.core.$strip>], "isError">, z.ZodObject<{
+                type: z.ZodLiteral<"proposed-action">;
+                id: z.ZodString;
+                tool: z.ZodString;
+                input: z.ZodUnknown;
+                summary: z.ZodOptional<z.ZodString>;
+                expiresAt: z.ZodNumber;
+            }, z.core.$strip>]>>;
+        }, z.core.$strip>;
+    }, z.core.$strip>;
+    readonly usage: z.ZodObject<{
+        type: z.ZodLiteral<"usage">;
+        usage: z.ZodObject<{
+            inputTokens: z.ZodNumber;
+            outputTokens: z.ZodNumber;
+            cacheReadTokens: z.ZodNumber;
+            cacheWriteTokens: z.ZodNumber;
+        }, z.core.$strip>;
+    }, z.core.$strip>;
+    readonly error: z.ZodObject<{
+        type: z.ZodLiteral<"error">;
+        error: z.ZodObject<{
+            code: z.ZodString;
+        }, z.core.$strip>;
+    }, z.core.$strip>;
+    readonly done: z.ZodObject<{
+        type: z.ZodLiteral<"done">;
+        reason: z.ZodString;
+        usage: z.ZodObject<{
+            inputTokens: z.ZodNumber;
+            outputTokens: z.ZodNumber;
+            cacheReadTokens: z.ZodNumber;
+            cacheWriteTokens: z.ZodNumber;
+        }, z.core.$strip>;
+    }, z.core.$strip>;
+};
+/**
+ * Validates an event as read from the stream (unlike `agentEventSchema` of
+ * `@nxgt/ai-core`, which wants the `message` the wire leaves out).
+ */
+export declare const wireEventSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    type: z.ZodLiteral<"step-start">;
+    step: z.ZodNumber;
+    runId: z.ZodString;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"text-delta">;
+    text: z.ZodString;
+    start: z.ZodOptional<z.ZodLiteral<true>>;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"thinking-delta">;
+    text: z.ZodString;
+    start: z.ZodOptional<z.ZodLiteral<true>>;
+    signature: z.ZodOptional<z.ZodString>;
+    redacted: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"tool-call">;
+    id: z.ZodString;
+    name: z.ZodString;
+    input: z.ZodUnknown;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"tool-result">;
+    result: z.ZodDiscriminatedUnion<[z.ZodObject<{
+        isError: z.ZodLiteral<false>;
+        output: z.ZodUnknown;
+        type: z.ZodLiteral<"tool-result">;
+        callId: z.ZodString;
+        name: z.ZodString;
+    }, z.core.$strip>, z.ZodObject<{
+        isError: z.ZodLiteral<true>;
+        error: z.ZodObject<{
+            code: z.ZodString;
+        }, z.core.$strip>;
+        type: z.ZodLiteral<"tool-result">;
+        callId: z.ZodString;
+        name: z.ZodString;
+    }, z.core.$strip>], "isError">;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"proposed-action">;
+    action: z.ZodObject<{
+        type: z.ZodLiteral<"proposed-action">;
+        id: z.ZodString;
+        tool: z.ZodString;
+        input: z.ZodUnknown;
+        summary: z.ZodOptional<z.ZodString>;
+        expiresAt: z.ZodNumber;
+    }, z.core.$strip>;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"message">;
+    message: z.ZodObject<{
+        role: z.ZodEnum<{
+            tool: "tool";
+            user: "user";
+            assistant: "assistant";
+        }>;
+        parts: z.ZodArray<z.ZodUnion<readonly [z.ZodObject<{
+            type: z.ZodLiteral<"text">;
+            text: z.ZodString;
+        }, z.core.$strip>, z.ZodObject<{
+            type: z.ZodLiteral<"thinking">;
+            text: z.ZodString;
+            signature: z.ZodOptional<z.ZodString>;
+            redacted: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>, z.ZodObject<{
+            type: z.ZodLiteral<"tool-call">;
+            id: z.ZodString;
+            name: z.ZodString;
+            input: z.ZodUnknown;
+        }, z.core.$strip>, z.ZodDiscriminatedUnion<[z.ZodObject<{
+            isError: z.ZodLiteral<false>;
+            output: z.ZodUnknown;
+            type: z.ZodLiteral<"tool-result">;
+            callId: z.ZodString;
+            name: z.ZodString;
+        }, z.core.$strip>, z.ZodObject<{
+            isError: z.ZodLiteral<true>;
+            error: z.ZodObject<{
+                code: z.ZodString;
+            }, z.core.$strip>;
+            type: z.ZodLiteral<"tool-result">;
+            callId: z.ZodString;
+            name: z.ZodString;
+        }, z.core.$strip>], "isError">, z.ZodObject<{
+            type: z.ZodLiteral<"proposed-action">;
+            id: z.ZodString;
+            tool: z.ZodString;
+            input: z.ZodUnknown;
+            summary: z.ZodOptional<z.ZodString>;
+            expiresAt: z.ZodNumber;
+        }, z.core.$strip>]>>;
+    }, z.core.$strip>;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"usage">;
+    usage: z.ZodObject<{
+        inputTokens: z.ZodNumber;
+        outputTokens: z.ZodNumber;
+        cacheReadTokens: z.ZodNumber;
+        cacheWriteTokens: z.ZodNumber;
+    }, z.core.$strip>;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"error">;
+    error: z.ZodObject<{
+        code: z.ZodString;
+    }, z.core.$strip>;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"done">;
+    reason: z.ZodString;
+    usage: z.ZodObject<{
+        inputTokens: z.ZodNumber;
+        outputTokens: z.ZodNumber;
+        cacheReadTokens: z.ZodNumber;
+        cacheWriteTokens: z.ZodNumber;
+    }, z.core.$strip>;
+}, z.core.$strip>], "type">;
+/** An event as the client reads it: errors are codes, never messages. */
+export type WireEvent = z.infer<typeof wireEventSchema>;
+export type WireToolResult = z.infer<typeof wireToolResultSchema>;
+/**
+ * The event a client may read. Everywhere an event holds an error (an
+ * `error` event, a failed `tool-result`, a failed result inside a `message`)
+ * only its `code` is kept: messages and issues can hold what a provider, a
+ * tool or an exception said, so they stay on the server.
+ */
+export declare function toWireEvent(event: AgentEvent): WireEvent;
+//# sourceMappingURL=wire.d.ts.map

package/dist/wire.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"wire.d.ts","sourceRoot":"","sources":["../src/wire.ts"],"names":[],"mappings":"AAAA,OAAO,EACN,KAAK,UAAU,EAKf,MAAM,eAAe,CAAC;AACvB,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,qEAAqE;AACrE,eAAO,MAAM,cAAc,mBAAmB,CAAC;AAE/C,yEAAyE;AACzE,wBAAgB,MAAM,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAE7C;AAiBD,mFAAmF;AACnF,eAAO,MAAM,oBAAoB;;;;;;;;;;;;;;8BAW/B,CAAC;AAkCH,0EAA0E;AAC1E,eAAO,MAAM,gBAAgB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAwCnB,CAAC;AAEX;;;GAGG;AACH,eAAO,MAAM,eAAe;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;2BAW1B,CAAC;AAEH,yEAAyE;AACzE,MAAM,MAAM,SAAS,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,eAAe,CAAC,CAAC;AACxD,MAAM,MAAM,cAAc,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,oBAAoB,CAAC,CAAC;AAgBlE;;;;;GAKG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,UAAU,GAAG,SAAS,CAWxD"}

package/docs/README.md

@@ -0,0 +1,9 @@
+# `@nxgt/ai-alxia` documentation
+
+| Page                                        | Read it when                                                                                   |
+| ------------------------------------------- | ---------------------------------------------------------------------------------------------- |
+| [Request and SSE](guide/request-and-sse.md) | you serve an agent from an alxia route: abort, language, observers, the event stream, a client |
+| [Troubleshooting](troubleshooting.md)       | you meet an error and want its cause and fix                                                   |
+| [Roadmap](roadmap.md)                       | you want to know what is coming                                                                |
+
+The [README](../README.md) is the short version.

package/docs/guide/request-and-sse.md

@@ -0,0 +1,224 @@
+# Request and SSE
+
+An agent behind an alxia route needs three things from the request (a signal
+that fires when the client leaves, its language, the app's observers) and a way
+to stream events. `aiRequest` gives the first three, `agentEvents` the stream.
+
+- [aiRequest](#airequest)
+- [The abort signal](#the-abort-signal)
+- [The language](#the-language)
+- [Observers](#observers)
+- [agentEvents](#agentevents)
+- [What a client reads](#what-a-client-reads)
+- [A request body and memory](#a-request-body-and-memory)
+- [Errors carry codes only](#errors-carry-codes-only)
+- [Heartbeat](#heartbeat)
+- [Test your route](#test-your-route)
+
+## aiRequest
+
+```ts
+import { alxia } from '@alxia/core';
+import { language } from '@alxia/language';
+import { aiRequest } from '@nxgt/ai-alxia';
+
+const app = alxia()
+	.use(language({ supported: ['en', 'fr'] as const, fallback: 'en' }))
+	.use(aiRequest({ observers: [] }))
+	.get('/who', ({ ai, reply }) => reply(200, ai.language));
+```
+
+After it, every handler reads `ai`: `{ signal, language, observers }`. The
+three keys are those of `runAgent`'s options, so `...ai` spreads them.
+
+## The abort signal
+
+`ai.signal` is the request's own signal, which alxia aborts when the client
+hangs up. `...ai` gives it to `runAgent` (the model stream and running tools
+stop); `agentEvents(run, ai)` stops the stream at once and aborts the run:
+
+```ts
+return reply(200, agentEvents(runAgent({ ...ai, model, messages }), ai));
+```
+
+## The language
+
+`ai.language` is what `@alxia/language` or `@alxia/i18n` decided (query,
+cookie, path, `Accept-Language`, then the fallback). Use it in the system
+prompt or to pick a tool's wording:
+
+```ts
+runAgent({ ...ai, model, system: `Answer in ${ai.language}.`, messages });
+```
+
+## Observers
+
+`aiRequest({ observers })` holds the observers once for the app. Each request
+gets the same array, so an observer serving concurrent runs must key by `runId`
+(the `AgentObserver` hooks all receive it).
+
+```ts
+import { aiTelemetry } from '@nxgt/ai-telemetry';
+
+alxia().use(aiRequest({ observers: [aiTelemetry()] }));
+```
+
+## agentEvents
+
+`agentEvents(run, { signal?, heartbeatMs? })` is an async generator for
+`reply(200, …)`. alxia turns it into `text/event-stream` (`no-cache`,
+`x-accel-buffering: no`) and closes it when the client leaves. Declare the
+route with `agentEventStream` so each event is written under its name:
+
+```ts
+app.post('/chat', responds({ 200: agentEventStream }), ({ ai, reply }) =>
+	reply(200, agentEvents(runAgent({ ...ai, model, messages }), ai)),
+);
+```
+
+It ends after `done`, and aborts the run when it is closed or the signal aborts.
+
+## What a client reads
+
+One block per event: `event:` is the `AgentEvent` type, `data:` its JSON, on one
+line (JSON escapes line breaks, so text cannot forge another field).
+
+```text
+event: text-delta
+data: {"type":"text-delta","text":"Hello"}
+
+event: done
+data: {"type":"done","reason":"end","usage":{"inputTokens":3,"outputTokens":2,"cacheReadTokens":0,"cacheWriteTokens":0}}
+```
+
+`wireEventSchema` validates one event; `agentEventSchema` of `@nxgt/ai-core`
+does not parse the wire (it wants the error `message`). `EventSource` only does
+GET, so for a POST read the body of `fetch`:
+
+```ts
+import { type WireEvent, wireEventSchema } from '@nxgt/ai-alxia';
+
+async function chat(
+	url: string,
+	body: unknown,
+	onEvent: (event: WireEvent) => void,
+) {
+	const response = await fetch(url, {
+		method: 'POST',
+		headers: { 'content-type': 'application/json' },
+		body: JSON.stringify(body),
+	});
+	if (!response.ok || !response.body)
+		throw new Error(`HTTP ${response.status}`);
+	const reader = response.body.pipeThrough(new TextDecoderStream()).getReader();
+	let buffer = '';
+	for (;;) {
+		const { done, value } = await reader.read();
+		if (done) return;
+		buffer += value;
+		let end: number;
+		while ((end = buffer.indexOf('\n\n')) !== -1) {
+			const block = buffer.slice(0, end);
+			buffer = buffer.slice(end + 2);
+			// a block is `event:` and `data:` lines; a `:` line is a comment
+			const data = block.split('\n').find((line) => line.startsWith('data: '));
+			if (!data) continue;
+			const event = wireEventSchema.parse(JSON.parse(data.slice(6)));
+			onEvent(event);
+			if (event.type === 'done') return reader.cancel();
+		}
+	}
+}
+
+await chat('/chat', { question: 'Hi' }, (event) => {
+	switch (event.type) {
+		case 'text-delta':
+			console.log(event.text);
+			break;
+		case 'error':
+			console.error('failed:', event.error.code); // a code, never a message
+			break;
+		default:
+			break; // keep a default: newer servers add event types
+	}
+});
+```
+
+A GET route with the conversation id in the path works with `EventSource` too.
+
+## A request body and memory
+
+Never append parts from the client's request body to a memory store. A client
+could send a forged `proposed-action` part; the store would record it as a
+pending action that anyone can confirm. Append only the user's text, plus the
+messages the run produced (`run.result.messages`). Parse the body with
+`userMessageSchema`, which accepts a `user` message of text parts only and
+refuses every other part.
+
+```ts
+import { responds } from '@alxia/core';
+import { runAgent } from '@nxgt/ai-core';
+import { z } from 'zod';
+import {
+	agentEvents,
+	agentEventStream,
+	userMessageSchema,
+} from '@nxgt/ai-alxia';
+
+// `app`, `model` and `store` are those of the first example and your memory store.
+const body = z.object({ threadId: z.string(), message: userMessageSchema });
+
+app.post(
+	'/chat',
+	{ body },
+	responds({ 200: agentEventStream }),
+	({ ai, body, user, reply }) => {
+		const { threadId, message } = body;
+		async function* stream() {
+			const history = (await store.load(threadId, user.id))?.messages ?? [];
+			const run = runAgent({ ...ai, model, messages: [...history, message] });
+			yield* agentEvents(run, ai);
+			// after the stream: the user's text, then what the run produced
+			await store.append(threadId, user.id, [
+				message,
+				...(await run.result).messages,
+			]);
+		}
+		return reply(200, stream());
+	},
+);
+```
+
+`user` is whatever your auth middleware puts on the context; the store is
+scoped by its id on every call.
+
+## Errors carry codes only
+
+An `error` event is `{ "type": "error", "error": { "code": "RATE_LIMITED" } }`.
+The message of a run error can hold what a provider or a tool said, so it
+stays in the server's logs and observers. Every failed tool result, alone or inside a `message` event, is reduced the
+same way. A failure of the stream
+itself ends it with `INTERNAL_ERROR`, or the code of the `AiError`.
+`toWireEvent` is the function that does it, if you write your own transport.
+
+## Heartbeat
+
+alxia writes `: keep-alive` after eight silent seconds. A proxy that cuts idle
+connections sooner needs your own period:
+
+```ts
+agentEvents(run, { ...ai, heartbeatMs: 10_000 });
+```
+
+A comment is a line `EventSource` skips; it is not an event and moves no id.
+
+## Test your route
+
+```ts
+const response = await app.request('/chat?lang=fr', { method: 'POST' });
+const body = await response.text();
+expect(body).toContain('event: done');
+```
+
+Abort test: pass `{ signal }` to `app.request`, read one chunk, call
+`controller.abort()`, and check that an observer's `onRunEnd` saw `aborted`.

package/docs/roadmap.md

@@ -0,0 +1,27 @@
+# Roadmap
+
+A direction, not a commitment. See the [repository roadmap](https://github.com/softistx/nxgt-ai/blob/develop/docs/roadmap.md) for the whole SDK.
+
+## Now
+
+- **Request middleware and SSE reply** — `aiRequest` and `agentEvents`: you get:
+  - `ctx.ai = { signal, language, observers }` to spread into `runAgent`, the signal aborting when the client leaves;
+  - a run's events as named Server-Sent Events written by alxia, typed by `agentEventStream`, with an optional heartbeat comment;
+  - errors on the wire as codes only, and the run stopped on disconnect.
+
+## Next
+
+Nothing yet.
+
+## Later
+
+- **A client reader** — an async iterable of `AgentEvent` from a `fetch` response, for a browser or another service.
+
+## Not planned
+
+- **Its own SSE writer** — alxia's `eventStream` already frames, validates and keeps alive.
+- **WebSocket transport** — SSE is enough for a one-way stream of events.
+
+## Shipped
+
+Nothing yet. Releases are listed in `CHANGELOG.md`.

package/docs/troubleshooting.md

@@ -0,0 +1,68 @@
+# Troubleshooting
+
+- [A compile error on `.use(aiRequest())`](#a-compile-error-on-useairequest)
+- [`ai.language` is always the fallback](#ailanguage-is-always-the-fallback)
+- [The run goes on after the client left](#the-run-goes-on-after-the-client-left)
+- [The client sees no error message](#the-client-sees-no-error-message)
+- [`agentEventSchema` fails on an event](#agenteventschema-fails-on-an-event)
+- [The events arrive all at once](#the-events-arrive-all-at-once)
+- [The connection closes while the model thinks](#the-connection-closes-while-the-model-thinks)
+- [`EventSource` cannot call my POST route](#eventsource-cannot-call-my-post-route)
+
+## A compile error on `.use(aiRequest())`
+
+**When:** TypeScript says the middleware requires `language`.
+**Why:** `aiRequest` reads `language` from the context, and nothing before it adds it.
+**Fix:** use `@alxia/language` (or `@alxia/i18n`) first.
+
+```ts
+alxia()
+	.use(language({ supported: ['en'] as const, fallback: 'en' }))
+	.use(aiRequest());
+```
+
+## `ai.language` is always the fallback
+
+**When:** `?lang=fr` or `Accept-Language: fr` still gives the fallback.
+**Why:** the language middleware decides, not `aiRequest`: the language is not in `supported`, or its `order` leaves the source out.
+**Fix:** check `supported` and `order` of the language middleware; `languageSource` says which source decided.
+
+## The run goes on after the client left
+
+**When:** the model keeps streaming, or tools keep running, after a disconnect.
+**Why:** the run was not given the request's signal, or `agentEvents` was not (a run waiting on a model is only seen by the signal).
+**Fix:** write the pair: spread `ai` into `runAgent` and pass `ai` to `agentEvents`.
+
+```ts
+reply(200, agentEvents(runAgent({ ...ai, model, messages }), ai));
+```
+
+## The client sees no error message
+
+**When:** an `error` event is `{ "code": "MODEL_ERROR" }` with nothing else, or `INTERNAL_ERROR`.
+**Why:** by design: messages can hold provider or tool details. `INTERNAL_ERROR` means the stream itself failed with something that is not an `AiError` (a bug or an unexpected exception on the server).
+**Fix:** map the code to your own text on the client; for the cause, check the server logs or an observer (`onRunEnd`'s `error`).
+
+## `agentEventSchema` fails on an event
+
+**When:** `agentEventSchema.parse` from `@nxgt/ai-core` rejects an `error` event or a failed tool result.
+**Why:** that schema requires `message`; the wire has none.
+**Fix:** parse with `wireEventSchema` from `@nxgt/ai-alxia`.
+
+## The events arrive all at once
+
+**When:** the client gets the whole answer at the end.
+**Why:** a proxy buffers the response, or the client buffers the body. alxia sends `x-accel-buffering: no` for nginx; other proxies have their own switch. Compression middleware can buffer too.
+**Fix:** disable buffering for the route in the proxy, and keep a compression middleware off `text/event-stream`.
+
+## The connection closes while the model thinks
+
+**When:** the stream drops after some seconds of silence, before any event.
+**Why:** a proxy or load balancer cuts idle connections, more often than alxia's 8 s keep-alive.
+**Fix:** `agentEvents(run, { ...ai, heartbeatMs: 5000 })`, below the proxy's idle timeout.
+
+## `EventSource` cannot call my POST route
+
+**When:** `new EventSource('/chat')` gets a 404 or 405.
+**Why:** `EventSource` sends GET and no body.
+**Fix:** read `fetch(...).body` as a stream, or serve a GET route that takes the conversation id.

package/package.json

@@ -1,6 +1,67 @@
 {
-  "name": "@nxgt/ai-alxia",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+	"name": "@nxgt/ai-alxia",
+	"version": "0.1.0",
+	"description": "alxia glue for @nxgt/ai-core: a request middleware (abort signal, language, observers) and a Server-Sent Events reply that streams an agent run",
+	"license": "MIT",
+	"type": "module",
+	"main": "./dist/index.js",
+	"types": "./dist/index.d.ts",
+	"files": [
+		"dist",
+		"docs",
+		"README.md",
+		"package.json",
+		"LICENSE"
+	],
+	"exports": {
+		".": {
+			"types": "./dist/index.d.ts",
+			"import": "./dist/index.js",
+			"default": "./dist/index.js"
+		},
+		"./package.json": "./package.json"
+	},
+	"keywords": [
+		"ai",
+		"agent",
+		"llm",
+		"alxia",
+		"sse",
+		"server-sent-events",
+		"bun",
+		"typescript"
+	],
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/softistx/nxgt-ai.git",
+		"directory": "packages/ai-alxia"
+	},
+	"publishConfig": {
+		"registry": "https://registry.npmjs.org",
+		"access": "public"
+	},
+	"scripts": {
+		"build": "bun run ../../build.ts",
+		"test": "bun test src",
+		"typecheck": "tsc --noEmit"
+	},
+	"nxgt": {
+		"entrypoints": [
+			"src/index.ts"
+		]
+	},
+	"devDependencies": {
+		"@alxia/core": "^0.16.0",
+		"@alxia/language": "^0.3.12",
+		"@nxgt/ai-core": "^0.2.0",
+		"@nxgt/ai-testing": "^0.1.1",
+		"@types/bun": "^1.4.4",
+		"zod": "4.6.5"
+	},
+	"peerDependencies": {
+		"@alxia/core": ">=0.16.0 <0.17.0",
+		"@nxgt/ai-core": "^0.2.0",
+		"typescript": "^6.0.3 || ^7.0.0",
+		"zod": ">=4.6.5 <5"
+	}
+}