@jacobbd/relay-ai 0.6.3 → 0.7.0

package/README.md

@@ -53,6 +53,7 @@ Pick your backend:
 | `relay-ai antigravity-ide` | Launch Antigravity IDE with Relay models, macOS ([warning + guide](docs/ANTIGRAVITY.md)) |
 | `relay-ai providers auth <id>` | Authenticate an OAuth provider (GitHub Copilot, xAI, OpenAI) |
 | `relay-ai --ai` | Full agent reference for scripts and alef-agent ([guide](docs/AI-AGENTS.md)) |
+| `@jacobbd/relay-ai/core` | Embed Relay AI in a Node app in-process — no CLI/UI/server ([guide](docs/CORE.md)) |
 
 ## Features
 
@@ -406,6 +407,31 @@ export ANTHROPIC_API_KEY="anything"
 unset CLAUDE_CODE_USE_VERTEX ANTHROPIC_VERTEX_PROJECT_ID CLOUD_ML_REGION
 ```
 
+## Embedded usage (`@jacobbd/relay-ai/core`)
+
+Node.js applications can embed Relay AI in-process — no CLI, UI, or server — to list the configured model catalog and obtain ready [Vercel AI SDK](https://sdk.vercel.ai) `LanguageModel` instances:
+
+```ts
+import { listRelayModels, createRelayModel, isRelayCoreError } from '@jacobbd/relay-ai/core';
+import { streamText } from 'ai';
+
+const models = listRelayModels();          // credential-free catalog
+const model = await createRelayModel(models[0].routeId);
+const result = await streamText({ model, prompt: 'Hello!' });
+```
+
+**Route ids** are unconditionally scoped: `` `${providerId}::${modelId}` `` (split on the first `::`; model ids may contain `/` and `:`, e.g. `openrouter::vendor/model:free`). Because they are never bare, a route id persisted by your app stays valid even when a second provider later exposes the same model id.
+
+**Ownership boundary:** Relay AI keeps sole ownership of provider registration, credentials, the OS keyring, and OAuth login/refresh. `createRelayModel()` resolves credentials (refreshing expiring OAuth tokens) at call time and returns only the SDK model — your app never receives or stores credential material. Re-authentication always happens through Relay (`relay-ai ui`), never through the consumer.
+
+**No server required:** the Core API reads the same registry and config as the CLI (`~/.relay-ai`, overridable with `RELAY_AI_HOME`) and never starts a server, opens a browser, or writes to disk. `createRelayModel()` re-reads state on every call, so provider changes take effect without restarting your app. Errors are thrown as `RelayCoreError` with a machine-readable `code` (see `isRelayCoreError`) and never contain credential material.
+
+**Schema compatibility:** Core supports registry schema v1. A registry written by a newer Relay version fails fast with `UNSUPPORTED_REGISTRY_VERSION` — upgrade relay-ai rather than downgrading the file.
+
+**Capability detection:** `capabilities.tools` and `capabilities.vision` are always `'unknown'` today — the cached model catalog carries no tools/vision metadata, and Core deliberately never guesses from a model's name. Don't filter on `=== true` for these two fields; use `capabilities.reasoning` (`'none' | 'fixed' | 'adjustable' | 'unknown'`), which is derived from real provider metadata.
+
+**Full guide:** prerequisites, the complete API and error-code reference, and troubleshooting — see **[docs/CORE.md](docs/CORE.md)**.
+
 ## Antigravity CLI, app, and IDE support
 
 Relay AI can launch the Antigravity CLI, standalone Antigravity app, and Antigravity IDE through a local Cloud Code gateway. This lets Antigravity's native model picker show Relay models from your configured providers.

package/dist/{chunk-WHEMJ7C3.js → chunk-IYYLLN5T.js}

@@ -11,7 +11,7 @@ import { join } from "path";
 // package.json
 var package_default = {
   name: "@jacobbd/relay-ai",
-  version: "0.6.3",
+  version: "0.7.0",
   publishConfig: {
     access: "public"
   },
@@ -46,7 +46,7 @@ var package_default = {
     node: ">=18"
   },
   scripts: {
-    build: "tsup && node scripts/copy-ui-assets.mjs",
+    build: "tsup && tsup --config tsup.core.config.ts && node scripts/copy-ui-assets.mjs",
     dev: "tsup --watch",
     test: "vitest run",
     "test:watch": "vitest",
@@ -100,6 +100,14 @@ var package_default = {
   },
   overrides: {
     ws: "^8.21.0"
+  },
+  exports: {
+    "./core": {
+      types: "./dist/core/index.d.ts",
+      import: "./dist/core/index.js",
+      default: "./dist/core/index.js"
+    },
+    "./package.json": "./package.json"
   }
 };
 
@@ -3627,7 +3635,7 @@ function parseRegistry(raw) {
   if (typeof data.pricingCacheAt === "string") registry.pricingCacheAt = data.pricingCacheAt;
   return registry;
 }
-function loadRegistry(path = getProvidersPath()) {
+function loadRegistry(path = getProvidersPath(), { persist = true } = {}) {
   if (!existsSync6(path)) {
     return { schemaVersion: REGISTRY_SCHEMA_VERSION, providers: [] };
   }
@@ -3638,7 +3646,7 @@ function loadRegistry(path = getProvidersPath()) {
     if (migrateOAuthOpenAiProvider(registry)) migrated = true;
     if (migrateOAuthXaiProvider(registry)) migrated = true;
     if (migrateAlibabaDashScopeChinaLabel(registry)) migrated = true;
-    if (migrated) {
+    if (migrated && persist) {
       try {
         saveRegistry(registry, path);
       } catch {
@@ -11103,4 +11111,4 @@ export {
   supportsClaudeTransparentMode,
   buildHttpProxyRoutes
 };
-//# sourceMappingURL=chunk-WHEMJ7C3.js.map
+//# sourceMappingURL=chunk-IYYLLN5T.js.map