@coswic/aipay 0.8.0 → 0.8.1

package/CHANGELOG.md

@@ -1,5 +1,12 @@
 # @coswic/aipay
 
+## 0.8.1 — 2026-10-11
+
+- The sign-in helpers that `aipay init` generates, and the CLI's own sign-in, pass the SDK's new `authOrigin` option (the authorization server origin) instead of the option name the SDK now deprecates.
+- `aipay init` upgrades an `@coswic/aipay-sdk` older than 0.5.1 that the project already has — the installed version, or the package.json range when nothing is installed yet — by running `<package manager> add @coswic/aipay-sdk@latest`; with `--no-install` it prints that command instead, and `--dry-run` shows it. The JSON result reports this as `sdk_upgrade`. `aipay doctor` warns when the installed SDK is older than 0.5.1.
+- The rules section of the generated `aipay-agent.md` is now headed "Rules for the coding agent". README and code comments reworded; no other behavior change.
+- Requires `@coswic/aipay-sdk` ^0.5.1.
+
 ## 0.8.0 — 2026-10-09
 
 - `aipay test`: a 401 from the API now says that, during the invitation-only beta, the signed-in user may hold no current invitation (or not have accepted the latest Terms) and that refreshing does not help; a sign-in that never reaches the loopback callback prints the same hint next to the timeout.
@@ -31,7 +38,7 @@
 - Add `apps callbacks list/add/remove` with the developer’s own management authorization and linked-project defaults.
 - Preserve other registered callbacks, make no-op changes idempotent, and refuse to remove the final callback.
 - Require server ETag support for mutations; concurrent edits and uncertain outcomes require readback instead of blind retries.
-- Guide agents through developer CLI login and callback management; local `init` remains distinct from server registration.
+- Guide the coding agent through developer CLI login and callback management; local `init` remains distinct from server registration.
 - Allow HTTPS application callbacks in `init` and `doctor`; `test --callback` can use a separately registered loopback callback without changing project settings.
 - Bound developer API requests to 30 seconds and allow conditional mutations to disable automatic retries after a 401.
 

package/README.md

@@ -1,7 +1,7 @@
 # @coswic/aipay — AI Pay CLI
 
 The command-line companion to [`@coswic/aipay-sdk`](https://www.npmjs.com/package/@coswic/aipay-sdk).
-Made for developers and for the coding agents they hand the Console prompt to.
+Made for developers and for the coding agent they hand the Console prompt to.
 
 ```bash
 npx @coswic/aipay@latest login --api <api base>
@@ -30,7 +30,7 @@ AI Pay's production environment is in a free beta limited to invited users: only
 | `aipay apps callbacks list --app <client_id>` | Read the registered callback URLs. In a linked project, `--app` can be omitted; `--dir` selects the project. |
 | `aipay apps callbacks add --app <client_id> --callback <url>` | Add a registered callback while preserving the others. Adding an existing URL makes no write. |
 | `aipay apps callbacks remove --app <client_id> --callback <url>` | Remove one callback; removing an absent URL makes no write. The final callback cannot be removed. |
-| `aipay init` | Links the project to your app: writes `.aipay/project.json` (commit it), `.env.local` (public values only, git-ignored), a start/callback route for your framework (Next.js, Express, Fastify, Hono, plain Node) or a browser helper for a Vite SPA (`--framework` overrides detection), `aipay-agent.md` (the developer docs, fetched once, for your agent to read offline) and installs the SDK. Never overwrites a file it did not write this run. `--dry-run` shows the plan. |
+| `aipay init` | Links the project to your app: writes `.aipay/project.json` (commit it), `.env.local` (public values only, git-ignored), a start/callback route for your framework (Next.js, Express, Fastify, Hono, plain Node) or a browser helper for a Vite SPA (`--framework` overrides detection), `aipay-agent.md` (the developer docs, fetched once, for your agent to read offline) and installs the SDK — or upgrades it when the project already has one older than 0.5.1, which the generated code needs (`--no-install` prints the command instead). Never overwrites a file it did not write this run. `--dry-run` shows the plan. |
 | `aipay test` | The proof: a real sign-in through the AI Pay authorization server, received by the CLI on a loopback callback, then one chat completion on that user's behalf. Prints the receipt (`request_id`, amount charged). The Console's verify step turns green from the server side. The authorization server ignores the port for `127.0.0.1` redirect URIs (RFC 8252), so the CLI binds any free port and your dev server can keep running; `--port <n>` forces one. `--no-open` prints the URL instead of opening a browser; `--model <id>` picks the model. |
 | `aipay doctor` | Checks Node, the link, `.env.local`, the SDK install, and that the authorization server and API are reachable. `--offline` skips the network. |
 | `aipay status` | What this directory is linked to. |
@@ -102,7 +102,7 @@ to check the configured endpoints before retrying.
 ```
 .aipay/project.json   # app client_id, endpoints, callback, what was scaffolded — no secrets
 .env.local            # AIPAY_CLIENT_ID / AIPAY_AUTH_ORIGIN / AIPAY_API_BASE / AIPAY_CALLBACK_URL
-aipay-agent.md        # project facts + the developer docs, for coding agents
+aipay-agent.md        # project facts + the developer docs, for your coding agent
 src/aipay.ts          # sign-in helpers (start → callback → first completion)
 src/aipay-routes.ts   # framework wiring (or app/auth/aipay/*/route.ts for Next.js)
 ```

package/dist/agent-guide.js

@@ -33,7 +33,7 @@ ${files}
 3. ${verification}
 4. Typecheck/build pass. Do not commit automatically and do not deploy.
 
-## Rules for agents
+## Rules for the coding agent
 
 - Read the docs below before changing the integration; they are the source of truth.
 - Use standard OAuth sign-in and app authorization.

package/dist/args.d.ts

@@ -1,5 +1,5 @@
 /**
- * Tiny argv parser — zero deps on purpose (the CLI is installed by coding agents in
+ * Tiny argv parser — zero deps on purpose (the CLI gets installed by a coding agent into
  * arbitrary projects; every dependency is attack surface and install time).
  *
  * Supports `--flag`, `--flag value`, `--flag=value`, `--no-flag`, and positionals.

package/dist/commands/doctor.js

@@ -7,7 +7,7 @@ import { existsSync, readFileSync } from 'node:fs';
 import { join, resolve } from 'node:path';
 import { flagBool, flagString } from '../args.js';
 import { parseAppCallback } from '../callback-url.js';
-import { detectProject } from '../detect.js';
+import { detectProject, outdatedSdk, SDK_MIN_VERSION } from '../detect.js';
 import { EXIT } from '../output.js';
 import { ENV_FILE, ENV_KEYS, readProject } from '../project.js';
 import { createRemote, docsUrl, EMPTY_404_HINT } from '../remote.js';
@@ -95,19 +95,29 @@ export async function collectChecks(dir, opts, deps) {
     const det = detectProject(dir);
     if (det.hasPackageJson) {
         const installed = det.sdkInstalled && existsSync(join(dir, 'node_modules', '@coswic', 'aipay-sdk'));
-        checks.push(installed
-            ? { id: 'sdk', level: 'ok', text: '@coswic/aipay-sdk installed' }
-            : det.sdkInstalled
-                ? {
-                    id: 'sdk',
-                    level: 'bad',
-                    text: '@coswic/aipay-sdk is in package.json but not installed — run your package manager install',
-                }
-                : {
-                    id: 'sdk',
-                    level: 'bad',
-                    text: '@coswic/aipay-sdk not a dependency — rerun `aipay init` (or add it yourself)',
-                });
+        // Only the installed version counts here (the spec alone says nothing about what runs).
+        const old = installed && det.sdkVersion
+            ? outdatedSdk({ sdkVersion: det.sdkVersion, sdkSpec: null })
+            : null;
+        checks.push(old
+            ? {
+                id: 'sdk',
+                level: 'warn',
+                text: `@coswic/aipay-sdk ${old} installed — code generated by \`aipay init\` needs ${SDK_MIN_VERSION} or later; rerun \`aipay init\` or upgrade it`,
+            }
+            : installed
+                ? { id: 'sdk', level: 'ok', text: '@coswic/aipay-sdk installed' }
+                : det.sdkInstalled
+                    ? {
+                        id: 'sdk',
+                        level: 'bad',
+                        text: '@coswic/aipay-sdk is in package.json but not installed — run your package manager install',
+                    }
+                    : {
+                        id: 'sdk',
+                        level: 'bad',
+                        text: '@coswic/aipay-sdk not a dependency — rerun `aipay init` (or add it yourself)',
+                    });
         for (const f of project.scaffold.files)
             if (!existsSync(join(dir, f)))
                 checks.push({ id: 'scaffold', level: 'warn', text: `scaffolded file removed: ${f}` });

package/dist/commands/init.js

@@ -13,7 +13,7 @@ import { AGENT_GUIDE_FILE, agentGuide } from '../agent-guide.js';
 import { flagBool, flagString } from '../args.js';
 import { createAuthStore } from '../auth-store.js';
 import { parseAppCallback } from '../callback-url.js';
-import { detectProject, installCommand } from '../detect.js';
+import { detectProject, installCommand, outdatedSdk, SDK_MIN_VERSION } from '../detect.js';
 import { openDeveloperApi } from '../developer-api.js';
 import { CliError, EXIT } from '../output.js';
 import { ENV_FILE, ENV_KEYS, FRAMEWORKS, isFramework, mergeEnvFile, mergeGitignore, readProject, VITE_ENV_KEYS, writeProject, } from '../project.js';
@@ -176,16 +176,23 @@ export async function runInit(args, out, deps = {}) {
     });
     plan.push({ path: AGENT_GUIDE_FILE, action: existsSync(guidePath) ? 'update' : 'write' });
     plan.push({ path: '.aipay/project.json', action: existing ? 'update' : 'write' });
-    // 6. install
+    // 6. install — or upgrade: the generated code passes `authOrigin`, which the SDK accepts
+    //    from SDK_MIN_VERSION on, so an older SDK already in the project would break it.
+    const outdated = det.hasPackageJson && det.sdkInstalled ? outdatedSdk(det) : null;
+    const upgradeCmd = outdated
+        ? installCommand(det.packageManager ?? 'npm', `${SDK_PACKAGE}@latest`)
+        : null;
     let installCmd = null;
-    if (det.hasPackageJson && !det.sdkInstalled && install && det.packageManager)
-        installCmd = installCommand(det.packageManager, SDK_PACKAGE);
+    if (det.hasPackageJson && install && det.packageManager)
+        installCmd = det.sdkInstalled ? upgradeCmd : installCommand(det.packageManager, SDK_PACKAGE);
     out.blank();
     for (const p of plan)
         out.line(p.action === 'skip' ? 'info' : 'ok', `${p.action.padEnd(6)} ${p.path}${p.why ? `  (${p.why})` : ''}`);
+    if (outdated)
+        out.line(installCmd ? 'info' : 'warn', `${SDK_PACKAGE} ${outdated} is too old for the generated code (needs ${SDK_MIN_VERSION} or later)${installCmd ? '' : ` — upgrade it: ${upgradeCmd?.join(' ')}`}`);
     if (installCmd)
         out.line('info', `${dryRun ? 'would run' : 'run   '} ${installCmd.join(' ')}`);
-    else if (det.hasPackageJson && det.sdkInstalled)
+    else if (det.hasPackageJson && det.sdkInstalled && !outdated)
         out.line('info', `skip   ${SDK_PACKAGE} (already a dependency)`);
     let installExit = null;
     if (!dryRun) {
@@ -201,10 +208,10 @@ export async function runInit(args, out, deps = {}) {
             if (installExit !== 0)
                 out.line('bad', `install failed (exit ${installExit}); run it yourself: ${installCmd.join(' ')}`);
             else
-                out.line('ok', `installed ${SDK_PACKAGE}`);
+                out.line('ok', `${outdated ? 'upgraded' : 'installed'} ${SDK_PACKAGE}`);
         }
     }
-    // C2 setup session：登入狀態下回報 init（Console 的「等待工具連線」變綠）；失敗不影響結果
+    // setup session：登入狀態下回報 init（Console 的「等待工具連線」變綠）；失敗不影響結果
     let reported = false;
     if (!dryRun)
         reported = await reportSetupEvent(clientId, 'cli.init', {
@@ -227,6 +234,9 @@ export async function runInit(args, out, deps = {}) {
         detection: det,
         plan,
         install: installCmd ? { command: installCmd, exit: installExit } : null,
+        sdk_upgrade: outdated
+            ? { from: outdated, minimum: SDK_MIN_VERSION, command: upgradeCmd }
+            : null,
         docs: { fetched: !!docs.markdown, empty404: docs.empty404, status: docs.status },
         reported,
     });

package/dist/commands/login.d.ts

@@ -6,14 +6,14 @@ export interface CliConfig {
     scopes: string[];
     redirect_path: string;
     audience: string;
-    /** A2: the server allows the device grant for the CLI (older APIs omit it = false). */
+    /** The server allows the device grant for the CLI (older APIs omit it = false). */
     device_authorization: boolean;
 }
 export interface LoginDeps {
     env?: NodeJS.ProcessEnv;
     open?: (url: string) => boolean;
     onAuthorizeUrl?: (url: string) => void;
-    /** A2: called with the verification URL and the user code (tests / drivers). */
+    /** `--device`: called with the verification URL and the user code (tests / drivers). */
     onDeviceCode?: (info: {
         url: string;
         userCode: string;

package/dist/commands/login.js

@@ -1,11 +1,11 @@
 /**
  * `aipay login [--api <base>] [--device] [--no-open] [--timeout <s>] [--json]`
  *
- * Developer sign-in for the CLI itself (consultant §10.2, auth model A): the CLI is a
- * first-party public client. It asks the API for its client config, then either
- *   A1 — runs loopback PKCE against the authorization server (a browser on this machine), or
- *   A2 — `--device`: RFC 8628 device authorization (no browser here: SSH boxes, containers,
- *        CI) — prints a URL + short code, the developer approves on any device, the CLI polls.
+ * Developer sign-in for the CLI itself: the CLI is a first-party public client. It asks
+ * the API for its client config, then either
+ *   - runs loopback PKCE against the authorization server (a browser on this machine), or
+ *   - `--device`: RFC 8628 device authorization (no browser here: SSH boxes, containers,
+ *     CI) — prints a URL + short code, the developer approves on any device, the CLI polls.
  * Both use audience aipay-developer-api and the management scope, and keep the tokens in
  * the OS keychain (or a 0600 file). No app secrets exist.
  */
@@ -118,7 +118,7 @@ export async function runLogin(args, out, deps = {}) {
         const code = u.searchParams.get('code');
         if (!code)
             throw new CliError('remote', 'callback without a code', EXIT.remote);
-        const tokens = await exchangeCode({ hydraPublicUrl: cfg.auth_origin, clientId: cfg.client_id, redirectUri }, { code, codeVerifier, fetchImpl });
+        const tokens = await exchangeCode({ authOrigin: cfg.auth_origin, clientId: cfg.client_id, redirectUri }, { code, codeVerifier, fetchImpl });
         return finishLogin({
             accessToken: tokens.accessToken,
             refreshToken: tokens.refreshToken,
@@ -130,7 +130,7 @@ export async function runLogin(args, out, deps = {}) {
         await loop.close();
     }
 }
-/** A2 (RFC 8628): print URL + code, poll until approved on another device. */
+/** `--device` (RFC 8628): print URL + code, poll until approved on another device. */
 async function deviceLogin(cfg, apiBase, timeoutS, fetchImpl, env, out, deps) {
     if (!cfg.device_authorization)
         throw new CliError('device_unsupported', `${apiBase} does not offer device sign-in yet — run \`aipay login\` on a machine with a browser`, EXIT.remote);
@@ -154,7 +154,7 @@ async function deviceLogin(cfg, apiBase, timeoutS, fetchImpl, env, out, deps) {
 }
 /** Shared tail of both flows: identity → keychain/file → summary. */
 async function finishLogin(tokens, cfg, apiBase, fetchImpl, env, out) {
-    const user = await getUserInfo({ hydraPublicUrl: cfg.auth_origin }, tokens.accessToken, {
+    const user = await getUserInfo({ authOrigin: cfg.auth_origin }, tokens.accessToken, {
         fetchImpl,
     });
     const store = createAuthStore(env);

package/dist/commands/region.d.ts

@@ -1,14 +1,14 @@
 /**
  * `aipay region` (show) and
  * `aipay region set --country <CC> [--state US-XX --line1 <street> [--line2 <apt>] --city <city> --zip <ZIP>] [--accept-terms]`.
- * US accounts (0121) must carry a full postal address: the backend locates the sales-tax jurisdiction
+ * US accounts must carry a full postal address: the backend locates the sales-tax jurisdiction
  * (state / county / city / special district) from it; `aipay region` shows the lookup result.
  *
  * The developer API is closed (403 region_required) until the account has a declared region and an
  * accepted current Terms of Service version. Both endpoints used here are exempt from that gate:
  *   GET  /v1/developer/me/region  → current state + the version to accept
  *   POST /v1/developer/me/region  → declare (same body as the dashboard)
- * Non-interactive on purpose (agents drive this): everything is a flag; missing input is a usage error.
+ * Non-interactive on purpose (a coding agent may drive this): everything is a flag; missing input is a usage error.
  */
 import { type ParsedArgs } from '../args.js';
 import { type Reporter } from '../output.js';
@@ -38,7 +38,7 @@ export interface RegionState {
     declared: boolean;
     terms_current: boolean;
     complete: boolean;
-    /** US only (0121): the full postal address on file */
+    /** US only: the full postal address on file */
     address?: RegionAddress | null;
     /** US only: background jurisdiction lookup (state / county / city / special district) */
     tax_location?: TaxLocationState | null;

package/dist/commands/region.js

@@ -1,14 +1,14 @@
 /**
  * `aipay region` (show) and
  * `aipay region set --country <CC> [--state US-XX --line1 <street> [--line2 <apt>] --city <city> --zip <ZIP>] [--accept-terms]`.
- * US accounts (0121) must carry a full postal address: the backend locates the sales-tax jurisdiction
+ * US accounts must carry a full postal address: the backend locates the sales-tax jurisdiction
  * (state / county / city / special district) from it; `aipay region` shows the lookup result.
  *
  * The developer API is closed (403 region_required) until the account has a declared region and an
  * accepted current Terms of Service version. Both endpoints used here are exempt from that gate:
  *   GET  /v1/developer/me/region  → current state + the version to accept
  *   POST /v1/developer/me/region  → declare (same body as the dashboard)
- * Non-interactive on purpose (agents drive this): everything is a flag; missing input is a usage error.
+ * Non-interactive on purpose (a coding agent may drive this): everything is a flag; missing input is a usage error.
  */
 import { flagBool, flagString } from '../args.js';
 import { createAuthStore } from '../auth-store.js';
@@ -116,7 +116,7 @@ export async function runRegion(args, out, env = process.env) {
         }
         if (country === 'US' && !state)
             throw new CliError('usage', 'the United States needs --state (e.g. --state US-CA)', EXIT.usage);
-        // 0121: the US needs a full address (street, city, ZIP) — the backend locates the sales-tax jurisdiction from it
+        // The US needs a full address (street, city, ZIP) — the backend locates the sales-tax jurisdiction from it
         if (country === 'US')
             address = parseAddressFlags(args.flags);
         else if (flagString(args.flags, 'line1') ||

package/dist/commands/test.js

@@ -42,7 +42,7 @@ export async function runTest(args, out, deps = {}) {
         throw e;
     });
     const redirectUri = redirectUriFor(target, loop.port);
-    const cfg = { hydraPublicUrl: project.auth_origin, clientId: project.app.client_id, redirectUri };
+    const cfg = { authOrigin: project.auth_origin, clientId: project.app.client_id, redirectUri };
     const { url, state, codeVerifier } = await createConnectUrl(cfg);
     const note = redirectUri === callback
         ? ''
@@ -113,7 +113,7 @@ export async function runTest(args, out, deps = {}) {
             };
             result.ok = true;
             out.line('ok', `receipt: request_id ${r.request_id}, charged ${formatUusd(charged)} ${r.currency}`);
-            // C2 setup session：登入狀態下回報 test 通過（伺服器本來就看得到回執；這條是給 Console 的時間戳）
+            // setup session：登入狀態下回報 test 通過（伺服器本來就看得到回執；這條是給 Console 的時間戳）
             await reportSetupEvent(project.app.client_id, 'cli.test', { request_id: r.request_id, model: res.model, ok: true }, out, env);
             out.line('ok', "done — the Console's verify step reads this from the server side");
         }
@@ -140,7 +140,7 @@ export async function runTest(args, out, deps = {}) {
         if (e instanceof CliError) {
             result.error = { code: e.code, message: e.message };
             out.line('bad', e.message);
-            // 顧問 §13.2：失敗也回報（error_code 進 Console 的驗證步與 setup 事件；best effort、無 token）
+            // 失敗也回報（error_code 進 Console 的驗證步與 setup 事件；best effort、無 token）
             await reportSetupEvent(project.app.client_id, 'cli.test', { ok: false, error_code: e.code }, out, env);
             out.result(result);
             return e.exitCode;

package/dist/detect.d.ts

@@ -1,5 +1,8 @@
 import type { Framework } from './project.js';
 export type PackageManager = 'pnpm' | 'npm' | 'yarn' | 'bun';
+/** Oldest @coswic/aipay-sdk the scaffolded code works with: it passes `authOrigin`, which
+ * the SDK accepts from 0.5.1 on. */
+export declare const SDK_MIN_VERSION = "0.5.1";
 export interface Detection {
     packageManager: PackageManager | null;
     framework: Framework | null;
@@ -7,6 +10,10 @@ export interface Detection {
     typescript: boolean;
     /** Whether @coswic/aipay-sdk is already a dependency. */
     sdkInstalled: boolean;
+    /** Its version spec in package.json (null when it is not a dependency). */
+    sdkSpec: string | null;
+    /** Version in node_modules/@coswic/aipay-sdk/package.json (null when absent or unreadable). */
+    sdkVersion: string | null;
     /** `src/` exists → scaffold under it, else project root. */
     srcDir: string;
 }
@@ -23,5 +30,12 @@ export declare function detectPackageManager(pkg: PackageJsonLike | null, lockfi
 }): PackageManager | null;
 export declare function detectFramework(pkg: PackageJsonLike | null): Framework | null;
 export declare function detectProject(dir: string): Detection;
+/**
+ * The SDK version this project would run when it is older than SDK_MIN_VERSION: the
+ * installed one when known, else the lowest version the package.json spec allows
+ * (`^0.5.0` → 0.5.0). Null when it is new enough or cannot be told (not a dependency, or a
+ * spec such as `latest`, `*`, a range or a `file:` / `workspace:` link).
+ */
+export declare function outdatedSdk(det: Pick<Detection, 'sdkSpec' | 'sdkVersion'>): string | null;
 /** The install command for the detected manager (printed in --dry-run, run otherwise). */
 export declare function installCommand(pm: PackageManager, pkgName: string): string[];

package/dist/detect.js

@@ -5,6 +5,9 @@
  */
 import { existsSync, readFileSync } from 'node:fs';
 import { join } from 'node:path';
+/** Oldest @coswic/aipay-sdk the scaffolded code works with: it passes `authOrigin`, which
+ * the SDK accepts from 0.5.1 on. */
+export const SDK_MIN_VERSION = '0.5.1';
 export function detectPackageManager(pkg, lockfiles) {
     const pm = pkg?.packageManager;
     if (typeof pm === 'string') {
@@ -59,15 +62,64 @@ export function detectProject(dir) {
         npm: existsSync(join(dir, 'package-lock.json')),
     };
     const deps = { ...(pkg?.dependencies ?? {}), ...(pkg?.devDependencies ?? {}) };
+    const sdkSpec = deps['@coswic/aipay-sdk'];
     return {
         packageManager: detectPackageManager(pkg, lockfiles),
         framework: detectFramework(pkg),
         hasPackageJson,
         typescript: 'typescript' in deps || existsSync(join(dir, 'tsconfig.json')),
         sdkInstalled: '@coswic/aipay-sdk' in deps,
+        sdkSpec: typeof sdkSpec === 'string' ? sdkSpec : null,
+        sdkVersion: installedSdkVersion(dir),
         srcDir: existsSync(join(dir, 'src')) ? 'src' : '.',
     };
 }
+function installedSdkVersion(dir) {
+    try {
+        const p = join(dir, 'node_modules', '@coswic', 'aipay-sdk', 'package.json');
+        const v = JSON.parse(readFileSync(p, 'utf8')).version;
+        return typeof v === 'string' ? v : null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * The SDK version this project would run when it is older than SDK_MIN_VERSION: the
+ * installed one when known, else the lowest version the package.json spec allows
+ * (`^0.5.0` → 0.5.0). Null when it is new enough or cannot be told (not a dependency, or a
+ * spec such as `latest`, `*`, a range or a `file:` / `workspace:` link).
+ */
+export function outdatedSdk(det) {
+    const version = det.sdkVersion ?? lowestAllowed(det.sdkSpec);
+    return version !== null && isOlder(version, SDK_MIN_VERSION) ? version : null;
+}
+/** Exact, `^`, `~`, `=` or `>=` spec → the version it starts at; anything else → null. */
+function lowestAllowed(spec) {
+    const m = /^\s*(?:[\^~=]|>=)?\s*v?(\d+)\.(\d+)(?:\.(\d+|x|\*))?(-[0-9A-Za-z.-]+)?\s*$/.exec(spec ?? '');
+    if (!m)
+        return null;
+    const patch = m[3] === undefined || m[3] === 'x' || m[3] === '*' ? '0' : m[3];
+    return `${m[1]}.${m[2]}.${patch}${m[4] ?? ''}`;
+}
+/** Semver precedence for `major.minor.patch[-prerelease]` (a prerelease sorts before its
+ * release); false when either side cannot be parsed. */
+function isOlder(version, than) {
+    const parse = (v) => {
+        const m = /^v?(\d+)\.(\d+)\.(\d+)(-[0-9A-Za-z.-]+)?(?:\+[0-9A-Za-z.-]+)?$/.exec(v.trim());
+        return m ? { core: [Number(m[1]), Number(m[2]), Number(m[3])], pre: m[4] !== undefined } : null;
+    };
+    const a = parse(version);
+    const b = parse(than);
+    if (!a || !b)
+        return false;
+    for (let i = 0; i < 3; i++) {
+        const d = a.core[i] - b.core[i];
+        if (d !== 0)
+            return d < 0;
+    }
+    return a.pre && !b.pre;
+}
 /** The install command for the detected manager (printed in --dry-run, run otherwise). */
 export function installCommand(pm, pkgName) {
     switch (pm) {

package/dist/developer-api.js

@@ -43,7 +43,7 @@ export async function openDeveloperApi(store) {
             catch {
                 body = { raw: text.slice(0, 500) };
             }
-            // 0074 hard gate: the developer API is closed until region + current Terms are on file.
+            // Hard gate: the developer API is closed until region + current Terms are on file.
             // `aipay region …` talks to the exempt endpoints, so this never traps the fix itself.
             if (res.status === 403 && errorCodeOf(body) === 'region_required')
                 throw new CliError('region_required', 'AI Pay needs your country/region and your acceptance of the current Terms of Service before the developer API can be used — run `aipay region set --country <ISO 3166-1> [--state US-XX] --accept-terms` (`aipay region` shows the version and terms URL)', EXIT.problem);
@@ -56,7 +56,7 @@ async function refresh(store, auth, fetchImpl) {
     if (!auth.refresh_token)
         throw new CliError('expired', 'the developer token expired — run `aipay login` again', EXIT.problem);
     const t = await refreshAccessToken({
-        hydraPublicUrl: auth.auth_origin,
+        authOrigin: auth.auth_origin,
         clientId: auth.client_id,
     }, auth.refresh_token, { fetchImpl }).catch(() => {
         throw new CliError('expired', 'could not renew the developer token — run `aipay login` again', EXIT.problem);

package/dist/device.js

@@ -1,5 +1,5 @@
 /**
- * RFC 8628 device authorization for `aipay login --device` (consultant §10.2, auth model A2):
+ * RFC 8628 device authorization for `aipay login --device`:
  * for machines without a browser (SSH boxes, containers, CI). The CLI asks the
  * authorization server for a device code + a short user code, prints the verification
  * URL and the code, then polls the token endpoint until the developer approves it in

package/dist/loopback.d.ts

@@ -11,9 +11,10 @@ export interface LoopbackTarget {
     path: string;
 }
 /**
- * Hydra compares loopback redirect URIs per RFC 8252 §7.3: for 127.0.0.1 / [::1] the port
- * is ignored, so the CLI may receive the callback on any free port while the app keeps
- * its registered URI. `localhost` is NOT treated as loopback by the server — exact port.
+ * The authorization server compares loopback redirect URIs per RFC 8252 §7.3: for
+ * 127.0.0.1 / [::1] the port is ignored, so the CLI may receive the callback on any free
+ * port while the app keeps its registered URI. `localhost` is NOT treated as loopback by
+ * the server — exact port.
  */
 export declare function portIsVariable(target: LoopbackTarget): boolean;
 /** The redirect_uri to send for a receiver bound to `port` (same host + path). */

package/dist/loopback.js

@@ -7,9 +7,10 @@
 import { createServer } from 'node:http';
 import { hasUnsafeCallbackText } from './callback-url.js';
 /**
- * Hydra compares loopback redirect URIs per RFC 8252 §7.3: for 127.0.0.1 / [::1] the port
- * is ignored, so the CLI may receive the callback on any free port while the app keeps
- * its registered URI. `localhost` is NOT treated as loopback by the server — exact port.
+ * The authorization server compares loopback redirect URIs per RFC 8252 §7.3: for
+ * 127.0.0.1 / [::1] the port is ignored, so the CLI may receive the callback on any free
+ * port while the app keeps its registered URI. `localhost` is NOT treated as loopback by
+ * the server — exact port.
  */
 export function portIsVariable(target) {
     return target.host === '127.0.0.1' || target.host === '::1';

package/dist/output.d.ts

@@ -1,7 +1,8 @@
 /**
  * Output channel: human-readable lines on stderr-ish stdout, or one JSON document when
- * `--json` is set (agents parse it; humans read the other one). Both go to stdout so
- * `aipay status --json | jq` works; diagnostics that must never pollute JSON go to stderr.
+ * `--json` is set (for scripts and coding tools; humans read the other one). Both go to
+ * stdout so `aipay status --json | jq` works; diagnostics that must never pollute JSON go
+ * to stderr.
  */
 export type Level = 'ok' | 'warn' | 'bad' | 'info';
 export interface Reporter {
@@ -19,7 +20,7 @@ export declare function createReporter(opts: {
     stdout?: (s: string) => void;
     stderr?: (s: string) => void;
 }): Reporter;
-/** Exit codes are part of the contract (agents branch on them). */
+/** Exit codes are part of the contract (scripts and coding tools branch on them). */
 export declare const EXIT: {
     readonly ok: 0;
     /** Something in the project/config is wrong and the user can fix it. */

package/dist/output.js

@@ -30,7 +30,7 @@ export function createReporter(opts) {
         },
     };
 }
-/** Exit codes are part of the contract (agents branch on them). */
+/** Exit codes are part of the contract (scripts and coding tools branch on them). */
 export const EXIT = {
     ok: 0,
     /** Something in the project/config is wrong and the user can fix it. */

package/dist/project.d.ts

@@ -5,7 +5,7 @@ export interface ProjectConfig {
         client_id: string;
         name: string | null;
     };
-    /** Authorization server origin (Hydra public), e.g. https://auth.ai-pay.example */
+    /** Authorization server origin, e.g. https://auth.ai-pay.example */
     auth_origin: string;
     /** API base for the SDK client, e.g. https://api.ai-pay.example */
     api_base: string;

package/dist/project.js

@@ -1,5 +1,5 @@
 /**
- * Local artifacts (consultant report §6.5):
+ * Local artifacts:
  *   .aipay/project.json  — committable: which app this project is linked to (no secrets)
  *   .env.local           — NOT committed: only public values (client_id, URLs)
  *   .gitignore           — gets `.env.local` and `.aipay/local/` appended once

package/dist/setup-events.js

@@ -1,5 +1,5 @@
 /**
- * Setup-session events (consultant §6.3): after `init` / `test` the CLI tells the Console
+ * Setup-session events: after `init` / `test` the CLI tells the Console
  * what happened so the "waiting for the tool" line turns into "the CLI finished init".
  * Best effort and strictly opt-in by state: only when the developer is signed in with the
  * CLI (`aipay login`); never blocks the command, never sends tokens or file contents.

package/dist/templates.d.ts

@@ -1,13 +1,3 @@
-/**
- * Scaffold templates: one `aipay` helper module (sign-in flow + first completion) and a
- * thin wiring file per framework. Authored twice (TypeScript / JavaScript) so nothing is
- * generated by stripping types. The callback path is the one registered in the Console
- * for the app (default /auth/aipay/callback); the start path sits next to it.
- *
- * Sessions are the developer's business — the template keeps pending flows and signed-in
- * users in memory with a loud comment, which is correct for a dev server and obviously
- * wrong for production.
- */
 import type { Framework } from './project.js';
 export interface TemplateFile {
     /** Path relative to the project root. */

package/dist/templates.js

@@ -1,3 +1,14 @@
+/**
+ * Scaffold templates: one `aipay` helper module (sign-in flow + first completion) and a
+ * thin wiring file per framework. Authored twice (TypeScript / JavaScript) so nothing is
+ * generated by stripping types. The callback path is the one registered in the Console
+ * for the app (default /auth/aipay/callback); the start path sits next to it.
+ *
+ * Sessions are the developer's business — the template keeps pending flows and signed-in
+ * users in memory with a loud comment, which is correct for a dev server and obviously
+ * wrong for production.
+ */
+import { SDK_MIN_VERSION } from './detect.js';
 export function startPathFor(callbackPath) {
     return callbackPath.replace(/\/[^/]*$/, '/start');
 }
@@ -72,7 +83,7 @@ import {
 } from '@coswic/aipay-sdk'
 
 const cfg = {
-  hydraPublicUrl: process.env.AIPAY_AUTH_ORIGIN${t(' as string', '')},
+  authOrigin: process.env.AIPAY_AUTH_ORIGIN${t(' as string', '')}, // needs @coswic/aipay-sdk ${SDK_MIN_VERSION}+
   clientId: process.env.AIPAY_CLIENT_ID${t(' as string', '')},
   redirectUri: process.env.AIPAY_CALLBACK_URL${t(' as string', '')},
 }
@@ -250,7 +261,7 @@ import {
 } from '@coswic/aipay-sdk'
 
 const cfg = {
-  hydraPublicUrl: import.meta.env.VITE_AIPAY_AUTH_ORIGIN${t(' as string', '')},
+  authOrigin: import.meta.env.VITE_AIPAY_AUTH_ORIGIN${t(' as string', '')}, // needs @coswic/aipay-sdk ${SDK_MIN_VERSION}+
   clientId: import.meta.env.VITE_AIPAY_CLIENT_ID${t(' as string', '')},
   redirectUri: import.meta.env.VITE_AIPAY_CALLBACK_URL${t(' as string', '')},
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@coswic/aipay",
-  "version": "0.8.0",
+  "version": "0.8.1",
   "description": "AI Pay CLI — developer sign-in, App and callback management, project integration, diagnostics, and real sign-in + AI receipt verification.",
   "author": "Coswic Labs (https://coswic.ai)",
   "license": "MIT",
@@ -27,7 +27,7 @@
     "node": ">=20"
   },
   "dependencies": {
-    "@coswic/aipay-sdk": "^0.5.0"
+    "@coswic/aipay-sdk": "^0.5.1"
   },
   "devDependencies": {
     "@types/node": "^26.1.1",