@nathapp/nax-ai 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025-2026 William Khoo
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,69 @@
+# @nathapp/nax-ai
+
+Provider-agnostic LLM client: completions, streaming, tool calls, usage accounting and auth across API-key and OAuth providers.
+
+> **Pre-1.0 — the API is unstable and will change without deprecation cycles.**
+> Published under the `next` dist-tag. Pin an exact version; do not use a caret range.
+>
+> ```
+> npm install @nathapp/nax-ai@next
+> ```
+
+## Where to start
+
+New to this repository, or picking the work up cold? **[`ROADMAP.md`](ROADMAP.md)** records the current milestone, what is next, and links to the design spec and the feasibility analysis behind it.
+
+## Usage
+
+```ts
+import { createClient, piProtocols, piProviders } from "@nathapp/nax-ai";
+
+const client = createClient({
+  providers: await piProviders(["deepseek", "anthropic"]),
+  protocols: piProtocols(),
+});
+
+const model = await client.model("deepseek", "deepseek-v4-flash");
+const result = await client.complete(model, { messages: [{ role: "user", content: "hi" }] });
+```
+
+Install from the `next` dist-tag while the API is unstable: `npm install @nathapp/nax-ai@next`.
+
+## Scope
+
+This package speaks a generic LLM vocabulary — models, messages, tool calls, usage, credentials. It knows nothing about any consumer's domain concepts, and that direction is one-way by design: consumers map onto their own types at their own boundary.
+
+That constraint is what lets the implementation underneath this surface be replaced, provider by provider, without consumers noticing. It is also why domain-specific abstractions do not belong here, however convenient they would be for the first consumer.
+
+## Requirements
+
+- **Node >= 22.19** — the compatibility target. Runs unmodified on Bun and Deno.
+- ESM only. There is no CommonJS build.
+
+The package must not use runtime-specific APIs. `Bun.*` and `bun:` imports are rejected by a build gate (`scripts/check-no-bun-apis.ts`) because the primary consumer runs on Bun, so nothing would fail there — the breakage would surface only for someone else, on install.
+
+## OAuth policy
+
+OAuth flows are governed by an explicit allowlist in `src/auth/oauth-policy.ts`, enforced by tests rather than convention.
+
+**Anthropic subscription OAuth is prohibited and must never be added.** Using Pro/Max tokens outside the official Claude CLI is server-blocked and a Consumer ToS violation. This is not a broken path awaiting repair — route Claude subscription traffic through the official CLI instead.
+
+The underlying client bundles Anthropic's flow beside permitted ones behind a shared lazy loader, which is precisely why the prohibition is a gate: "we simply won't call it" is not enforceable, and the environment that would notice the mistake is not the one running the tests.
+
+## Development
+
+```bash
+bun install
+bun run test         # vitest
+bun run typecheck    # tsc --noEmit
+bun run lint         # biome + no-bun-apis gate
+bun run build        # tsc -p tsconfig.build.json → dist/
+```
+
+**Vitest does not type-check.** It transpiles via esbuild, which strips types without verifying them, so a green suite proves nothing about compilation. `test` and `typecheck` cover disjoint ground and CI runs both.
+
+Tests run on Node (the compatibility target) and the built package is smoke-tested on Bun (the primary consumer's runtime). Testing only on Bun would hide exactly the class of breakage the Node target exists to prevent.
+
+## Licence
+
+MIT

package/dist/auth/oauth-policy.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Which OAuth flows this package is permitted to register.
+ *
+ * The underlying client (pi-ai) bundles OAuth flows for several providers
+ * behind a single lazy loader, including Anthropic's. Reaching the Anthropic
+ * flow is therefore only ever one call away from reaching a permitted one,
+ * which is why this policy is an explicit allowlist enforced by a gate rather
+ * than a convention maintained by review.
+ *
+ * Anthropic subscription OAuth (Pro/Max tokens outside the official CLI) is
+ * both server-blocked and a Consumer ToS violation. It is not "broken and may
+ * come back" — it is prohibited, and must never be registered here regardless
+ * of whether it happens to work on a given day. Subscription traffic to Claude
+ * belongs on a path that uses the official CLI, not on this client.
+ */
+import type { ProviderId } from "../types.ts";
+/**
+ * OAuth flows this package may register.
+ *
+ * Additions are a policy decision, not a routine change: each entry is a
+ * provider whose terms permit third-party OAuth use, or whose flow is a
+ * first-party developer credential rather than a consumer subscription.
+ */
+export declare const PERMITTED_OAUTH_FLOWS: readonly ProviderId[];
+/**
+ * OAuth flows that must never be registered, with the reason recorded so a
+ * future reader does not "fix" the omission.
+ */
+export declare const PROHIBITED_OAUTH_FLOWS: Readonly<Record<ProviderId, string>>;
+export declare class OAuthFlowProhibitedError extends Error {
+    readonly providerId: ProviderId;
+    constructor(providerId: ProviderId, reason: string);
+}
+export declare function isOAuthFlowPermitted(providerId: ProviderId): boolean;
+/**
+ * Throws if `providerId` names a flow this package must not register.
+ *
+ * Prohibited flows raise a specific error; merely-unknown flows raise a
+ * generic one, so a typo is distinguishable from a policy breach.
+ */
+export declare function assertOAuthFlowPermitted(providerId: ProviderId): void;
+//# sourceMappingURL=oauth-policy.d.ts.map

package/dist/auth/oauth-policy.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"oauth-policy.d.ts","sourceRoot":"","sources":["../../src/auth/oauth-policy.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAE9C;;;;;;GAMG;AACH,eAAO,MAAM,qBAAqB,EAAE,SAAS,UAAU,EAIrD,CAAC;AAEH;;;GAGG;AACH,eAAO,MAAM,sBAAsB,EAAE,QAAQ,CAAC,MAAM,CAAC,UAAU,EAAE,MAAM,CAAC,CAGtE,CAAC;AAEH,qBAAa,wBAAyB,SAAQ,KAAK;IACjD,QAAQ,CAAC,UAAU,EAAE,UAAU,CAAC;IAEhC,YAAY,UAAU,EAAE,UAAU,EAAE,MAAM,EAAE,MAAM,EAIjD;CACF;AAED,wBAAgB,oBAAoB,CAAC,UAAU,EAAE,UAAU,GAAG,OAAO,CAEpE;AAED;;;;;GAKG;AACH,wBAAgB,wBAAwB,CAAC,UAAU,EAAE,UAAU,GAAG,IAAI,CAQrE"}

package/dist/auth/oauth-policy.js

@@ -0,0 +1,61 @@
+/**
+ * Which OAuth flows this package is permitted to register.
+ *
+ * The underlying client (pi-ai) bundles OAuth flows for several providers
+ * behind a single lazy loader, including Anthropic's. Reaching the Anthropic
+ * flow is therefore only ever one call away from reaching a permitted one,
+ * which is why this policy is an explicit allowlist enforced by a gate rather
+ * than a convention maintained by review.
+ *
+ * Anthropic subscription OAuth (Pro/Max tokens outside the official CLI) is
+ * both server-blocked and a Consumer ToS violation. It is not "broken and may
+ * come back" — it is prohibited, and must never be registered here regardless
+ * of whether it happens to work on a given day. Subscription traffic to Claude
+ * belongs on a path that uses the official CLI, not on this client.
+ */
+/**
+ * OAuth flows this package may register.
+ *
+ * Additions are a policy decision, not a routine change: each entry is a
+ * provider whose terms permit third-party OAuth use, or whose flow is a
+ * first-party developer credential rather than a consumer subscription.
+ */
+export const PERMITTED_OAUTH_FLOWS = Object.freeze([
+    "openai-codex",
+    "github-copilot",
+    "openrouter",
+]);
+/**
+ * OAuth flows that must never be registered, with the reason recorded so a
+ * future reader does not "fix" the omission.
+ */
+export const PROHIBITED_OAUTH_FLOWS = Object.freeze({
+    anthropic: "Anthropic subscription OAuth outside the official Claude CLI is server-blocked and a Consumer ToS violation. Route Claude subscription traffic through the official CLI instead.",
+});
+export class OAuthFlowProhibitedError extends Error {
+    providerId;
+    constructor(providerId, reason) {
+        super(`OAuth flow for "${providerId}" is prohibited: ${reason}`);
+        this.name = "OAuthFlowProhibitedError";
+        this.providerId = providerId;
+    }
+}
+export function isOAuthFlowPermitted(providerId) {
+    return PERMITTED_OAUTH_FLOWS.includes(providerId);
+}
+/**
+ * Throws if `providerId` names a flow this package must not register.
+ *
+ * Prohibited flows raise a specific error; merely-unknown flows raise a
+ * generic one, so a typo is distinguishable from a policy breach.
+ */
+export function assertOAuthFlowPermitted(providerId) {
+    const prohibitedReason = PROHIBITED_OAUTH_FLOWS[providerId];
+    if (prohibitedReason !== undefined) {
+        throw new OAuthFlowProhibitedError(providerId, prohibitedReason);
+    }
+    if (!isOAuthFlowPermitted(providerId)) {
+        throw new Error(`Unknown OAuth flow "${providerId}". Permitted flows: ${PERMITTED_OAUTH_FLOWS.join(", ")}.`);
+    }
+}
+//# sourceMappingURL=oauth-policy.js.map

package/dist/auth/oauth-policy.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"oauth-policy.js","sourceRoot":"","sources":["../../src/auth/oauth-policy.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAIH;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,qBAAqB,GAA0B,MAAM,CAAC,MAAM,CAAC;IACxE,cAAc;IACd,gBAAgB;IAChB,YAAY;CACb,CAAC,CAAC;AAEH;;;GAGG;AACH,MAAM,CAAC,MAAM,sBAAsB,GAAyC,MAAM,CAAC,MAAM,CAAC;IACxF,SAAS,EACP,kLAAkL;CACrL,CAAC,CAAC;AAEH,MAAM,OAAO,wBAAyB,SAAQ,KAAK;IACxC,UAAU,CAAa;IAEhC,YAAY,UAAsB,EAAE,MAAc;QAChD,KAAK,CAAC,mBAAmB,UAAU,oBAAoB,MAAM,EAAE,CAAC,CAAC;QACjE,IAAI,CAAC,IAAI,GAAG,0BAA0B,CAAC;QACvC,IAAI,CAAC,UAAU,GAAG,UAAU,CAAC;IAC/B,CAAC;CACF;AAED,MAAM,UAAU,oBAAoB,CAAC,UAAsB;IACzD,OAAO,qBAAqB,CAAC,QAAQ,CAAC,UAAU,CAAC,CAAC;AACpD,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,wBAAwB,CAAC,UAAsB;IAC7D,MAAM,gBAAgB,GAAG,sBAAsB,CAAC,UAAU,CAAC,CAAC;IAC5D,IAAI,gBAAgB,KAAK,SAAS,EAAE,CAAC;QACnC,MAAM,IAAI,wBAAwB,CAAC,UAAU,EAAE,gBAAgB,CAAC,CAAC;IACnE,CAAC;IACD,IAAI,CAAC,oBAAoB,CAAC,UAAU,CAAC,EAAE,CAAC;QACtC,MAAM,IAAI,KAAK,CAAC,uBAAuB,UAAU,uBAAuB,qBAAqB,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;IAC/G,CAAC;AACH,CAAC"}

package/dist/auth/pi-auth.d.ts

@@ -0,0 +1,12 @@
+/**
+ * pi-ai's side of auth: a credential-store adapter and an AuthResolver.
+ *
+ * On the ALLOWED list in scripts/check-pi-ai-imports.ts. Nothing here leaks a
+ * pi-ai type through an export a consumer sees.
+ */
+import type { MutableModels, CredentialStore as PiCredentialStore } from "@earendil-works/pi-ai";
+import type { CredentialStore } from "../types.ts";
+import type { AuthResolver } from "./resolver.ts";
+export declare function toPiCredentialStore(store: CredentialStore): PiCredentialStore;
+export declare function createPiAuthResolver(models: MutableModels): AuthResolver;
+//# sourceMappingURL=pi-auth.d.ts.map

package/dist/auth/pi-auth.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pi-auth.d.ts","sourceRoot":"","sources":["../../src/auth/pi-auth.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAc,aAAa,EAAE,eAAe,IAAI,iBAAiB,EAAE,MAAM,uBAAuB,CAAC;AAC7G,OAAO,KAAK,EAAE,eAAe,EAA8B,MAAM,aAAa,CAAC;AAC/E,OAAO,KAAK,EAAE,YAAY,EAAgB,MAAM,eAAe,CAAC;AAoChE,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,eAAe,GAAG,iBAAiB,CA8B7E;AAED,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,aAAa,GAAG,YAAY,CAkBxE"}

package/dist/auth/pi-auth.js

@@ -0,0 +1,84 @@
+/**
+ * pi-ai's side of auth: a credential-store adapter and an AuthResolver.
+ *
+ * On the ALLOWED list in scripts/check-pi-ai-imports.ts. Nothing here leaks a
+ * pi-ai type through an export a consumer sees.
+ */
+function toPi(credential) {
+    if (credential === undefined)
+        return undefined;
+    if (credential.kind === "api-key") {
+        return {
+            type: "api_key",
+            key: credential.key,
+            ...(credential.env !== undefined ? { env: { ...credential.env } } : {}),
+        };
+    }
+    return {
+        type: "oauth",
+        access: credential.access,
+        refresh: credential.refresh,
+        expires: credential.expires,
+    };
+}
+function fromPi(credential) {
+    if (credential === undefined)
+        return undefined;
+    if (credential.type === "api_key") {
+        return {
+            kind: "api-key",
+            key: credential.key ?? "",
+            ...(credential.env !== undefined ? { env: { ...credential.env } } : {}),
+        };
+    }
+    return {
+        kind: "oauth",
+        access: credential.access,
+        refresh: credential.refresh,
+        expires: credential.expires,
+    };
+}
+export function toPiCredentialStore(store) {
+    return {
+        read: async (providerId) => toPi(await store.read(providerId)),
+        // modify stays a single read-modify-write so the underlying store can hold
+        // a lock across the whole operation. pi-ai runs OAuth refresh inside it.
+        modify: async (providerId, fn) => toPi(await store.modify(providerId, async (current) => {
+            const next = await fn(toPi(current));
+            // pi's modify contract treats an undefined return as "leave the
+            // entry unchanged" — its OAuth refresh returns that when a
+            // concurrent caller already rotated the token. nax-ai's undefined
+            // means "remove", so the no-op is translated to the current
+            // credential, never propagated; removal goes through delete().
+            return next === undefined ? current : fromPi(next);
+        })),
+        delete: async (providerId) => {
+            await store.delete(providerId);
+        },
+        // pi-ai requires `list` for account and status enumeration. nax-ai's
+        // CredentialStore has no equivalent and nax-ai never enumerates accounts:
+        // that belongs to login and logout, which are out of scope for M2. An
+        // empty list is what "this store does not enumerate" looks like, and it is
+        // only ever read by UI that nax-ai does not have.
+        list: async () => [],
+    };
+}
+export function createPiAuthResolver(models) {
+    return {
+        async resolve(ref) {
+            const result = await models.getAuth(ref.provider);
+            const auth = result?.auth;
+            if (auth === undefined)
+                return {};
+            return {
+                ...(auth.apiKey !== undefined ? { apiKey: auth.apiKey } : {}),
+                ...(auth.headers !== undefined
+                    ? {
+                        headers: Object.fromEntries(Object.entries(auth.headers).filter((entry) => entry[1] !== null)),
+                    }
+                    : {}),
+            };
+        },
+    };
+}
+//# sourceMappingURL=pi-auth.js.map

package/dist/auth/pi-auth.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"pi-auth.js","sourceRoot":"","sources":["../../src/auth/pi-auth.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAMH,SAAS,IAAI,CAAC,UAAwC;IACpD,IAAI,UAAU,KAAK,SAAS;QAAE,OAAO,SAAS,CAAC;IAC/C,IAAI,UAAU,CAAC,IAAI,KAAK,SAAS,EAAE,CAAC;QAClC,OAAO;YACL,IAAI,EAAE,SAAS;YACf,GAAG,EAAE,UAAU,CAAC,GAAG;YACnB,GAAG,CAAC,UAAU,CAAC,GAAG,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,GAAG,EAAE,EAAE,GAAG,UAAU,CAAC,GAAG,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;SACxE,CAAC;IACJ,CAAC;IACD,OAAO;QACL,IAAI,EAAE,OAAO;QACb,MAAM,EAAE,UAAU,CAAC,MAAM;QACzB,OAAO,EAAE,UAAU,CAAC,OAAO;QAC3B,OAAO,EAAE,UAAU,CAAC,OAAO;KAC5B,CAAC;AACJ,CAAC;AAED,SAAS,MAAM,CAAC,UAAkC;IAChD,IAAI,UAAU,KAAK,SAAS;QAAE,OAAO,SAAS,CAAC;IAC/C,IAAI,UAAU,CAAC,IAAI,KAAK,SAAS,EAAE,CAAC;QAClC,OAAO;YACL,IAAI,EAAE,SAAS;YACf,GAAG,EAAE,UAAU,CAAC,GAAG,IAAI,EAAE;YACzB,GAAG,CAAC,UAAU,CAAC,GAAG,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,GAAG,EAAE,EAAE,GAAG,UAAU,CAAC,GAAG,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;SACxE,CAAC;IACJ,CAAC;IACD,OAAO;QACL,IAAI,EAAE,OAAO;QACb,MAAM,EAAE,UAAU,CAAC,MAAM;QACzB,OAAO,EAAE,UAAU,CAAC,OAAO;QAC3B,OAAO,EAAE,UAAU,CAAC,OAAO;KAC5B,CAAC;AACJ,CAAC;AAED,MAAM,UAAU,mBAAmB,CAAC,KAAsB;IACxD,OAAO;QACL,IAAI,EAAE,KAAK,EAAE,UAAU,EAAE,EAAE,CAAC,IAAI,CAAC,MAAM,KAAK,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC;QAE9D,2EAA2E;QAC3E,yEAAyE;QACzE,MAAM,EAAE,KAAK,EAAE,UAAU,EAAE,EAAE,EAAE,EAAE,CAC/B,IAAI,CACF,MAAM,KAAK,CAAC,MAAM,CAAC,UAAU,EAAE,KAAK,EAAE,OAAO,EAAE,EAAE;YAC/C,MAAM,IAAI,GAAG,MAAM,EAAE,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC,CAAC;YACrC,gEAAgE;YAChE,2DAA2D;YAC3D,kEAAkE;YAClE,4DAA4D;YAC5D,+DAA+D;YAC/D,OAAO,IAAI,KAAK,SAAS,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;QACrD,CAAC,CAAC,CACH;QAEH,MAAM,EAAE,KAAK,EAAE,UAAU,EAAE,EAAE;YAC3B,MAAM,KAAK,CAAC,MAAM,CAAC,UAAU,CAAC,CAAC;QACjC,CAAC;QAED,qEAAqE;QACrE,0EAA0E;QAC1E,sEAAsE;QACtE,2EAA2E;QAC3E,kDAAkD;QAClD,IAAI,EAAE,KAAK,IAAI,EAAE,CAAC,EAAE;KACrB,CAAC;AACJ,CAAC;AAED,MAAM,UAAU,oBAAoB,CAAC,MAAqB;IACxD,OAAO;QACL,KAAK,CAAC,OAAO,CAAC,GAAa;YACzB,MAAM,MAAM,GAAG,MAAM,MAAM,CAAC,OAAO,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC;YAClD,MAAM,IAAI,GAAG,MAAM,EAAE,IAAI,CAAC;YAC1B,IAAI,IAAI,KAAK,SAAS;gBAAE,OAAO,EAAE,CAAC;YAClC,OAAO;gBACL,GAAG,CAAC,IAAI,CAAC,MAAM,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,IAAI,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;gBAC7D,GAAG,CAAC,IAAI,CAAC,OAAO,KAAK,SAAS;oBAC5B,CAAC,CAAC;wBACE,OAAO,EAAE,MAAM,CAAC,WAAW,CACzB,MAAM,CAAC,OAAO,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC,MAAM,CAAC,CAAC,KAAK,EAA6B,EAAE,CAAC,KAAK,CAAC,CAAC,CAAC,KAAK,IAAI,CAAC,CAC7F;qBACF;oBACH,CAAC,CAAC,EAAE,CAAC;aACR,CAAC;QACJ,CAAC;KACF,CAAC;AACJ,CAAC"}

package/dist/auth/resolver.d.ts

@@ -0,0 +1,30 @@
+/**
+ * The auth port.
+ *
+ * pi-ai resolves credentials today, but a hand-written backend will need the
+ * same thing and must not import pi-ai to get it. Keeping the port here, in
+ * nax-ai's own vocabulary, is what stops "delete the pi backend" from also
+ * deleting credential handling.
+ */
+import type { ModelRef } from "../types.ts";
+/**
+ * Request auth for one call.
+ *
+ * There is deliberately no `baseUrl`: it belongs to the model, and the
+ * upstream request options have no per-request slot for it.
+ */
+export interface ResolvedAuth {
+    readonly apiKey?: string;
+    readonly headers?: Readonly<Record<string, string>>;
+}
+export interface AuthResolver {
+    /**
+     * Refreshes an expired OAuth token as a side effect, under the store lock.
+     *
+     * Takes a `ModelRef` rather than a `ResolvedModel` so the pi protocol, which
+     * holds a pi-ai model, can call this without first round-tripping through
+     * the catalog.
+     */
+    resolve(ref: ModelRef): Promise<ResolvedAuth>;
+}
+//# sourceMappingURL=resolver.d.ts.map

package/dist/auth/resolver.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"resolver.d.ts","sourceRoot":"","sources":["../../src/auth/resolver.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AAE5C;;;;;GAKG;AACH,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,OAAO,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;CACrD;AAED,MAAM,WAAW,YAAY;IAC3B;;;;;;OAMG;IACH,OAAO,CAAC,GAAG,EAAE,QAAQ,GAAG,OAAO,CAAC,YAAY,CAAC,CAAC;CAC/C"}

package/dist/auth/resolver.js

@@ -0,0 +1,10 @@
+/**
+ * The auth port.
+ *
+ * pi-ai resolves credentials today, but a hand-written backend will need the
+ * same thing and must not import pi-ai to get it. Keeping the port here, in
+ * nax-ai's own vocabulary, is what stops "delete the pi backend" from also
+ * deleting credential handling.
+ */
+export {};
+//# sourceMappingURL=resolver.js.map

package/dist/auth/resolver.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"resolver.js","sourceRoot":"","sources":["../../src/auth/resolver.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG"}

package/dist/client.d.ts

@@ -0,0 +1,33 @@
+/**
+ * The client: the only thing a consumer constructs.
+ *
+ * It selects a protocol from `ResolvedModel.protocol`, so a consumer never
+ * names one. That indirection is what makes replacing a protocol's backend
+ * invisible to callers.
+ */
+import { type BackendSelection, type ProtocolEntries } from "./protocols/registry.ts";
+import type { ProtocolEvent, ProtocolRequest } from "./protocols/types.ts";
+import { type RawProvider } from "./providers/catalog.ts";
+import type { Pricing, ProviderOverride, ResolvedModel } from "./providers/types.ts";
+import type { CompleteResult, CredentialStore } from "./types.ts";
+export interface ClientOptions {
+    readonly providers: readonly RawProvider[];
+    readonly protocols: ProtocolEntries;
+    readonly backends?: BackendSelection;
+    readonly credentials?: CredentialStore;
+    readonly providerOverrides?: readonly ProviderOverride[];
+    /** Transport-fault retries before the first event. Default 2; 0 disables. */
+    readonly transportRetries?: number;
+}
+/** Everything on ProtocolRequest except `model`, which the client supplies. */
+export type ClientRequest = Omit<ProtocolRequest, "model">;
+export interface Client {
+    model(provider: string, model: string): Promise<ResolvedModel>;
+    listModels(provider?: string): Promise<readonly ResolvedModel[]>;
+    pricing(model: ResolvedModel): Pricing;
+    stream(model: ResolvedModel, req: ClientRequest): AsyncIterable<ProtocolEvent>;
+    complete(model: ResolvedModel, req: ClientRequest): Promise<CompleteResult>;
+    validate(): void;
+}
+export declare function createClient(options: ClientOptions): Client;
+//# sourceMappingURL=client.d.ts.map

package/dist/client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAGH,OAAO,EAAE,KAAK,gBAAgB,EAAkB,KAAK,eAAe,EAAE,MAAM,yBAAyB,CAAC;AAGtG,OAAO,KAAK,EAAE,aAAa,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAC;AAC3E,OAAO,EAAoB,KAAK,WAAW,EAAE,MAAM,wBAAwB,CAAC;AAC5E,OAAO,KAAK,EAAE,OAAO,EAAE,gBAAgB,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AACrF,OAAO,KAAK,EAAE,cAAc,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAElE,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,SAAS,EAAE,SAAS,WAAW,EAAE,CAAC;IAC3C,QAAQ,CAAC,SAAS,EAAE,eAAe,CAAC;IACpC,QAAQ,CAAC,QAAQ,CAAC,EAAE,gBAAgB,CAAC;IACrC,QAAQ,CAAC,WAAW,CAAC,EAAE,eAAe,CAAC;IACvC,QAAQ,CAAC,iBAAiB,CAAC,EAAE,SAAS,gBAAgB,EAAE,CAAC;IACzD,6EAA6E;IAC7E,QAAQ,CAAC,gBAAgB,CAAC,EAAE,MAAM,CAAC;CACpC;AAED,+EAA+E;AAC/E,MAAM,MAAM,aAAa,GAAG,IAAI,CAAC,eAAe,EAAE,OAAO,CAAC,CAAC;AAE3D,MAAM,WAAW,MAAM;IACrB,KAAK,CAAC,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,aAAa,CAAC,CAAC;IAC/D,UAAU,CAAC,QAAQ,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,SAAS,aAAa,EAAE,CAAC,CAAC;IACjE,OAAO,CAAC,KAAK,EAAE,aAAa,GAAG,OAAO,CAAC;IACvC,MAAM,CAAC,KAAK,EAAE,aAAa,EAAE,GAAG,EAAE,aAAa,GAAG,aAAa,CAAC,aAAa,CAAC,CAAC;IAC/E,QAAQ,CAAC,KAAK,EAAE,aAAa,EAAE,GAAG,EAAE,aAAa,GAAG,OAAO,CAAC,cAAc,CAAC,CAAC;IAC5E,QAAQ,IAAI,IAAI,CAAC;CAClB;AASD,wBAAgB,YAAY,CAAC,OAAO,EAAE,aAAa,GAAG,MAAM,CA2D3D"}

package/dist/client.js

@@ -0,0 +1,68 @@
+/**
+ * The client: the only thing a consumer constructs.
+ *
+ * It selects a protocol from `ResolvedModel.protocol`, so a consumer never
+ * names one. That indirection is what makes replacing a protocol's backend
+ * invisible to callers.
+ */
+import { collectStream } from "./protocols/collect.js";
+import { createRegistry } from "./protocols/registry.js";
+import { retryTransportFaults } from "./protocols/retry.js";
+import { clampThinkingLevel } from "./protocols/thinking.js";
+import { normaliseCatalog } from "./providers/catalog.js";
+/** Matches the doc comment on `ClientOptions.transportRetries`. */
+const DEFAULT_TRANSPORT_RETRIES = 2;
+function realSleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+export function createClient(options) {
+    const catalog = normaliseCatalog(options.providers, options.providerOverrides ?? []);
+    const registry = createRegistry(options.protocols, options.backends ?? {});
+    // A negative value is a config bug, not a policy choice — clamping it to 0
+    // would silently disable retry instead of telling the caller their option
+    // is nonsense. Checked here, once, rather than per stream() call.
+    const transportRetries = options.transportRetries ?? DEFAULT_TRANSPORT_RETRIES;
+    if (transportRetries < 0) {
+        throw new Error(`transportRetries must be >= 0, got ${transportRetries}.`);
+    }
+    async function* streamFrom(model, req) {
+        const protocol = await registry.resolve(model.protocol);
+        const thinking = req.thinking !== undefined ? clampThinkingLevel(req.thinking, model.thinkingLevels) : undefined;
+        const protocolRequest = {
+            ...req,
+            model: model.id,
+            provider: model.provider,
+            ...(thinking !== undefined ? { thinking } : {}),
+        };
+        yield* retryTransportFaults(() => protocol.stream(protocolRequest), {
+            retries: transportRetries,
+            sleep: realSleep,
+            ...(req.signal !== undefined ? { signal: req.signal } : {}),
+        });
+    }
+    return {
+        async model(provider, model) {
+            const resolved = catalog.model(provider, model);
+            if (resolved === undefined) {
+                throw new Error(`Unknown model "${model}" for provider "${provider}".`);
+            }
+            return resolved;
+        },
+        async listModels(provider) {
+            return catalog.listModels(provider);
+        },
+        pricing(model) {
+            return model.pricing;
+        },
+        stream(model, req) {
+            return streamFrom(model, req);
+        },
+        complete(model, req) {
+            return collectStream(streamFrom(model, req));
+        },
+        validate() {
+            registry.validate();
+        },
+    };
+}
+//# sourceMappingURL=client.js.map

package/dist/client.js.map

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

package/dist/index.d.ts

@@ -0,0 +1,27 @@
+/**
+ * @nathapp/nax-ai — provider-agnostic LLM client.
+ *
+ * Status: pre-1.0, API unstable. Published under the `next` dist-tag.
+ *
+ * Scope boundary: this package speaks a generic LLM vocabulary — models,
+ * messages, tool calls, usage, credentials. It deliberately knows nothing
+ * about any consumer's domain concepts (stories, operations, sessions,
+ * permission policy). Consumers map onto their own types at their boundary.
+ * Keeping that direction one-way is what allows the implementation beneath
+ * this surface to be replaced — provider by provider — without consumers
+ * noticing.
+ */
+export { assertOAuthFlowPermitted, isOAuthFlowPermitted, OAuthFlowProhibitedError, PERMITTED_OAUTH_FLOWS, PROHIBITED_OAUTH_FLOWS, } from "./auth/oauth-policy.ts";
+export type { AuthResolver, ResolvedAuth } from "./auth/resolver.ts";
+export { type Client, type ClientOptions, type ClientRequest, createClient } from "./client.ts";
+export { collectStream, ProtocolStreamError } from "./protocols/collect.ts";
+export { PI_PROTOCOL_NAMES, type PiProtocolName, type PiProtocolOptions, piProtocols, } from "./protocols/pi-protocols.ts";
+export { type BackendId, type BackendSelection, createRegistry, type ProtocolBackends, type ProtocolEntries, UnknownProtocolError, UnregisteredBackendError, } from "./protocols/registry.ts";
+export { clampThinkingLevel } from "./protocols/thinking.ts";
+export type { CacheRetention, ConversationMessage, JsonSchema, Protocol, ProtocolError, ProtocolEvent, ProtocolRequest, ThinkingBlock, ThinkingLevel, ToolCall, ToolDefinition, } from "./protocols/types.ts";
+export { type Catalog, normaliseCatalog, type RawModel, type RawProvider } from "./providers/catalog.ts";
+export { piProviders } from "./providers/pi-catalog.ts";
+export type { Pricing, PricingRates, PricingTier, ProviderAuth, ProviderOverride, ResolvedModel, ResolvedProvider, } from "./providers/types.ts";
+export type { CompleteOptions, CompleteResult, CredentialStore, Message, MessageRole, ModelRef, ProviderId, StopReason, StoredCredential, TokenUsage, } from "./types.ts";
+export { toTokenUsage, totalTokens, type UpstreamUsage } from "./usage.ts";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,EACL,wBAAwB,EACxB,oBAAoB,EACpB,wBAAwB,EACxB,qBAAqB,EACrB,sBAAsB,GACvB,MAAM,wBAAwB,CAAC;AAChC,YAAY,EAAE,YAAY,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AACrE,OAAO,EAAE,KAAK,MAAM,EAAE,KAAK,aAAa,EAAE,KAAK,aAAa,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAChG,OAAO,EAAE,aAAa,EAAE,mBAAmB,EAAE,MAAM,wBAAwB,CAAC;AAC5E,OAAO,EACL,iBAAiB,EACjB,KAAK,cAAc,EACnB,KAAK,iBAAiB,EACtB,WAAW,GACZ,MAAM,6BAA6B,CAAC;AACrC,OAAO,EACL,KAAK,SAAS,EACd,KAAK,gBAAgB,EACrB,cAAc,EACd,KAAK,gBAAgB,EACrB,KAAK,eAAe,EACpB,oBAAoB,EACpB,wBAAwB,GACzB,MAAM,yBAAyB,CAAC;AACjC,OAAO,EAAE,kBAAkB,EAAE,MAAM,yBAAyB,CAAC;AAC7D,YAAY,EACV,cAAc,EACd,mBAAmB,EACnB,UAAU,EACV,QAAQ,EACR,aAAa,EACb,aAAa,EACb,eAAe,EACf,aAAa,EACb,aAAa,EACb,QAAQ,EACR,cAAc,GACf,MAAM,sBAAsB,CAAC;AAC9B,OAAO,EAAE,KAAK,OAAO,EAAE,gBAAgB,EAAE,KAAK,QAAQ,EAAE,KAAK,WAAW,EAAE,MAAM,wBAAwB,CAAC;AACzG,OAAO,EAAE,WAAW,EAAE,MAAM,2BAA2B,CAAC;AACxD,YAAY,EACV,OAAO,EACP,YAAY,EACZ,WAAW,EACX,YAAY,EACZ,gBAAgB,EAChB,aAAa,EACb,gBAAgB,GACjB,MAAM,sBAAsB,CAAC;AAC9B,YAAY,EACV,eAAe,EACf,cAAc,EACd,eAAe,EACf,OAAO,EACP,WAAW,EACX,QAAQ,EACR,UAAU,EACV,UAAU,EACV,gBAAgB,EAChB,UAAU,GACX,MAAM,YAAY,CAAC;AACpB,OAAO,EAAE,YAAY,EAAE,WAAW,EAAE,KAAK,aAAa,EAAE,MAAM,YAAY,CAAC"}

package/dist/index.js

@@ -0,0 +1,23 @@
+/**
+ * @nathapp/nax-ai — provider-agnostic LLM client.
+ *
+ * Status: pre-1.0, API unstable. Published under the `next` dist-tag.
+ *
+ * Scope boundary: this package speaks a generic LLM vocabulary — models,
+ * messages, tool calls, usage, credentials. It deliberately knows nothing
+ * about any consumer's domain concepts (stories, operations, sessions,
+ * permission policy). Consumers map onto their own types at their boundary.
+ * Keeping that direction one-way is what allows the implementation beneath
+ * this surface to be replaced — provider by provider — without consumers
+ * noticing.
+ */
+export { assertOAuthFlowPermitted, isOAuthFlowPermitted, OAuthFlowProhibitedError, PERMITTED_OAUTH_FLOWS, PROHIBITED_OAUTH_FLOWS, } from "./auth/oauth-policy.js";
+export { createClient } from "./client.js";
+export { collectStream, ProtocolStreamError } from "./protocols/collect.js";
+export { PI_PROTOCOL_NAMES, piProtocols, } from "./protocols/pi-protocols.js";
+export { createRegistry, UnknownProtocolError, UnregisteredBackendError, } from "./protocols/registry.js";
+export { clampThinkingLevel } from "./protocols/thinking.js";
+export { normaliseCatalog } from "./providers/catalog.js";
+export { piProviders } from "./providers/pi-catalog.js";
+export { toTokenUsage, totalTokens } from "./usage.js";
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,EACL,wBAAwB,EACxB,oBAAoB,EACpB,wBAAwB,EACxB,qBAAqB,EACrB,sBAAsB,GACvB,MAAM,wBAAwB,CAAC;AAEhC,OAAO,EAAuD,YAAY,EAAE,MAAM,aAAa,CAAC;AAChG,OAAO,EAAE,aAAa,EAAE,mBAAmB,EAAE,MAAM,wBAAwB,CAAC;AAC5E,OAAO,EACL,iBAAiB,EAGjB,WAAW,GACZ,MAAM,6BAA6B,CAAC;AACrC,OAAO,EAGL,cAAc,EAGd,oBAAoB,EACpB,wBAAwB,GACzB,MAAM,yBAAyB,CAAC;AACjC,OAAO,EAAE,kBAAkB,EAAE,MAAM,yBAAyB,CAAC;AAc7D,OAAO,EAAgB,gBAAgB,EAAmC,MAAM,wBAAwB,CAAC;AACzG,OAAO,EAAE,WAAW,EAAE,MAAM,2BAA2B,CAAC;AAsBxD,OAAO,EAAE,YAAY,EAAE,WAAW,EAAsB,MAAM,YAAY,CAAC"}

package/dist/protocols/collect.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Derives a single result from a protocol stream.
+ *
+ * Implemented once, here, rather than per protocol — that is why `Protocol`
+ * exposes only `stream`. A backend cannot let a request/response path drift
+ * from its streaming path if it never writes one.
+ */
+import type { CompleteResult } from "../types.ts";
+import type { ProtocolError, ProtocolEvent } from "./types.ts";
+export declare class ProtocolStreamError extends Error {
+    readonly protocolError: ProtocolError;
+    constructor(protocolError: ProtocolError);
+}
+export declare function collectStream(events: AsyncIterable<ProtocolEvent>): Promise<CompleteResult>;
+//# sourceMappingURL=collect.d.ts.map

package/dist/protocols/collect.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"collect.d.ts","sourceRoot":"","sources":["../../src/protocols/collect.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAc,MAAM,aAAa,CAAC;AAC9D,OAAO,KAAK,EAAE,aAAa,EAAE,aAAa,EAA2B,MAAM,YAAY,CAAC;AAIxF,qBAAa,mBAAoB,SAAQ,KAAK;IAChC,QAAQ,CAAC,aAAa,EAAE,aAAa;IAAjD,YAAqB,aAAa,EAAE,aAAa,EAIhD;CACF;AAED,wBAAsB,aAAa,CAAC,MAAM,EAAE,aAAa,CAAC,aAAa,CAAC,GAAG,OAAO,CAAC,cAAc,CAAC,CAgDjG"}

package/dist/protocols/collect.js

@@ -0,0 +1,65 @@
+/**
+ * Derives a single result from a protocol stream.
+ *
+ * Implemented once, here, rather than per protocol — that is why `Protocol`
+ * exposes only `stream`. A backend cannot let a request/response path drift
+ * from its streaming path if it never writes one.
+ */
+const EMPTY_USAGE = { inputTokens: 0, outputTokens: 0 };
+export class ProtocolStreamError extends Error {
+    protocolError;
+    constructor(protocolError) {
+        super(protocolError.message);
+        this.protocolError = protocolError;
+        this.name = "ProtocolStreamError";
+        if (protocolError.cause !== undefined)
+            this.cause = protocolError.cause;
+    }
+}
+export async function collectStream(events) {
+    const text = [];
+    const toolCalls = [];
+    const thinking = [];
+    let usage;
+    let stopReason;
+    for await (const event of events) {
+        switch (event.type) {
+            case "text-delta":
+                text.push(event.text);
+                break;
+            case "tool-call":
+                toolCalls.push(event.call);
+                break;
+            case "thinking":
+                // Without this, complete() has no way to hand a caller the block
+                // needed to replay the next turn — the whole point of the fix.
+                thinking.push(event.block);
+                break;
+            case "usage":
+                usage = event.usage;
+                break;
+            case "error":
+                throw new ProtocolStreamError(event.error);
+            case "done":
+                stopReason = event.stopReason;
+                break;
+            // Thinking text is not part of the answer, and a partial tool call is
+            // superseded by the "tool-call" event that follows it.
+            case "thinking-delta":
+            case "tool-call-partial":
+                break;
+        }
+    }
+    if (stopReason === undefined) {
+        throw new Error("Protocol stream ended without a done event — the response was truncated.");
+    }
+    const result = {
+        text: text.join(""),
+        usage: usage ?? EMPTY_USAGE,
+        stopReason,
+        ...(toolCalls.length > 0 ? { toolCalls } : {}),
+        ...(thinking.length > 0 ? { thinking } : {}),
+    };
+    return result;
+}
+//# sourceMappingURL=collect.js.map

package/dist/protocols/collect.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"collect.js","sourceRoot":"","sources":["../../src/protocols/collect.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAKH,MAAM,WAAW,GAAe,EAAE,WAAW,EAAE,CAAC,EAAE,YAAY,EAAE,CAAC,EAAE,CAAC;AAEpE,MAAM,OAAO,mBAAoB,SAAQ,KAAK;IACvB,aAAa;IAAlC,YAAqB,aAA4B;QAC/C,KAAK,CAAC,aAAa,CAAC,OAAO,CAAC,CAAC;6BADV,aAAa;QAEhC,IAAI,CAAC,IAAI,GAAG,qBAAqB,CAAC;QAClC,IAAI,aAAa,CAAC,KAAK,KAAK,SAAS;YAAE,IAAI,CAAC,KAAK,GAAG,aAAa,CAAC,KAAK,CAAC;IAC1E,CAAC;CACF;AAED,MAAM,CAAC,KAAK,UAAU,aAAa,CAAC,MAAoC;IACtE,MAAM,IAAI,GAAa,EAAE,CAAC;IAC1B,MAAM,SAAS,GAAe,EAAE,CAAC;IACjC,MAAM,QAAQ,GAAoB,EAAE,CAAC;IACrC,IAAI,KAA6B,CAAC;IAClC,IAAI,UAAoD,CAAC;IAEzD,IAAI,KAAK,EAAE,MAAM,KAAK,IAAI,MAAM,EAAE,CAAC;QACjC,QAAQ,KAAK,CAAC,IAAI,EAAE,CAAC;YACnB,KAAK,YAAY;gBACf,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;gBACtB,MAAM;YACR,KAAK,WAAW;gBACd,SAAS,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;gBAC3B,MAAM;YACR,KAAK,UAAU;gBACb,iEAAiE;gBACjE,+DAA+D;gBAC/D,QAAQ,CAAC,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC;gBAC3B,MAAM;YACR,KAAK,OAAO;gBACV,KAAK,GAAG,KAAK,CAAC,KAAK,CAAC;gBACpB,MAAM;YACR,KAAK,OAAO;gBACV,MAAM,IAAI,mBAAmB,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC;YAC7C,KAAK,MAAM;gBACT,UAAU,GAAG,KAAK,CAAC,UAAU,CAAC;gBAC9B,MAAM;YACR,sEAAsE;YACtE,uDAAuD;YACvD,KAAK,gBAAgB,CAAC;YACtB,KAAK,mBAAmB;gBACtB,MAAM;QACV,CAAC;IACH,CAAC;IAED,IAAI,UAAU,KAAK,SAAS,EAAE,CAAC;QAC7B,MAAM,IAAI,KAAK,CAAC,0EAA0E,CAAC,CAAC;IAC9F,CAAC;IAED,MAAM,MAAM,GAAmB;QAC7B,IAAI,EAAE,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC;QACnB,KAAK,EAAE,KAAK,IAAI,WAAW;QAC3B,UAAU;QACV,GAAG,CAAC,SAAS,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,EAAE,SAAS,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QAC9C,GAAG,CAAC,QAAQ,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,EAAE,QAAQ,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;KAC7C,CAAC;IACF,OAAO,MAAM,CAAC;AAChB,CAAC"}