@inneranimalmedia/agentsam-sdk 2.6.0 → 2.6.2

package/src/lib/account-session.js

@@ -1,14 +1,28 @@
 import fs from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
-import { resolveSdkKey } from '../../packages/identity/src/contracts/auth-config.js';
+import { isApiKey, resolveApiKey } from '../../packages/identity/src/contracts/auth-config.js';
 
-export const ACCOUNT_SESSION_SCHEMA = 'agentsam-account-session-v1';
+export const ACCOUNT_SESSION_SCHEMA = 'agentsam-account-session-v3';
+const LEGACY_ACCOUNT_SESSION_SCHEMA = 'agentsam-account-session-v2';
 
 function clean(value) { return value == null ? '' : String(value).trim(); }
 function homeDirectory(options = {}) {
   return path.resolve(clean(options.home) || clean(options.env?.HOME) || clean(options.env?.USERPROFILE) || os.homedir());
 }
+function isoOrNull(value) {
+  const raw = clean(value);
+  if (!raw) return null;
+  const ms = Date.parse(raw);
+  return Number.isFinite(ms) ? new Date(ms).toISOString() : null;
+}
+function expiresAtFrom(session = {}, nowMs = Date.now()) {
+  const explicit = isoOrNull(session.expires_at);
+  if (explicit) return explicit;
+  const expiresIn = Number(session.expires_in);
+  if (!Number.isFinite(expiresIn) || expiresIn <= 0) return null;
+  return new Date(nowMs + (expiresIn * 1000)).toISOString();
+}
 
 export function accountSessionPath(options = {}) {
   return path.join(homeDirectory(options), '.agentsam', 'auth', 'session.json');
@@ -22,17 +36,24 @@ export function readAccountSession(options = {}) {
     if (!stat.isFile()) return null;
     if (process.platform !== 'win32' && (stat.mode & 0o077) !== 0) return null;
     const parsed = JSON.parse(fs.readFileSync(filename, 'utf8'));
-    if (parsed?.schema_version !== ACCOUNT_SESSION_SCHEMA) return null;
-    const token = clean(parsed.sdk_key);
-    if (!token.startsWith('sdk_')) return null;
+    if (![ACCOUNT_SESSION_SCHEMA, LEGACY_ACCOUNT_SESSION_SCHEMA].includes(parsed?.schema_version)) return null;
+    const accessToken = clean(parsed.access_token);
+    const refreshToken = clean(parsed.refresh_token);
+    if (!accessToken || isApiKey(accessToken) || (refreshToken && isApiKey(refreshToken))) return null;
     return {
       schema_version: ACCOUNT_SESSION_SCHEMA,
-      sdk_key: token,
+      access_token: accessToken,
+      refresh_token: refreshToken || null,
+      token_type: clean(parsed.token_type) || 'Bearer',
+      scope: clean(parsed.scope) || null,
+      expires_at: isoOrNull(parsed.expires_at),
+      client_id: clean(parsed.client_id) || null,
       user_id: clean(parsed.user_id) || null,
       account_id: clean(parsed.account_id) || null,
       email: clean(parsed.email) || null,
-      created_at: clean(parsed.created_at) || null,
-      updated_at: clean(parsed.updated_at) || null,
+      created_at: isoOrNull(parsed.created_at),
+      updated_at: isoOrNull(parsed.updated_at),
+      migrated_from: parsed.schema_version === LEGACY_ACCOUNT_SESSION_SCHEMA ? LEGACY_ACCOUNT_SESSION_SCHEMA : null,
     };
   } catch {
     return null;
@@ -40,25 +61,38 @@ export function readAccountSession(options = {}) {
 }
 
 export function saveAccountSession(session = {}, options = {}) {
-  const token = clean(session.sdk_key || session.access_token);
-  if (!token.startsWith('sdk_')) throw new Error('account_session_sdk_key_required');
+  const accessToken = clean(session.access_token);
+  const suppliedRefresh = clean(session.refresh_token);
+  if (!accessToken || isApiKey(accessToken) || (suppliedRefresh && isApiKey(suppliedRefresh))) {
+    throw new Error('account_browser_oauth_session_required');
+  }
+
   const filename = accountSessionPath(options);
   const dir = path.dirname(filename);
   fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
   if (process.platform !== 'win32') {
     try { fs.chmodSync(dir, 0o700); } catch { /* best effort */ }
   }
+
   const previous = readAccountSession(options);
-  const now = new Date().toISOString();
+  const nowMs = Number.isFinite(Number(options.nowMs)) ? Number(options.nowMs) : Date.now();
+  const now = new Date(nowMs).toISOString();
+  const preserveRefreshToken = options.preserveRefreshToken !== false;
   const value = {
     schema_version: ACCOUNT_SESSION_SCHEMA,
-    sdk_key: token,
+    access_token: accessToken,
+    refresh_token: suppliedRefresh || (preserveRefreshToken ? previous?.refresh_token : null) || null,
+    token_type: clean(session.token_type) || previous?.token_type || 'Bearer',
+    scope: clean(session.scope) || previous?.scope || null,
+    expires_at: expiresAtFrom(session, nowMs),
+    client_id: clean(session.client_id) || previous?.client_id || null,
     user_id: clean(session.user_id) || previous?.user_id || null,
     account_id: clean(session.account_id) || previous?.account_id || null,
     email: clean(session.email) || previous?.email || null,
     created_at: previous?.created_at || now,
     updated_at: now,
   };
+
   const temp = `${filename}.${process.pid}.tmp`;
   fs.writeFileSync(temp, `${JSON.stringify(value, null, 2)}\n`, { mode: 0o600 });
   if (process.platform !== 'win32') {
@@ -75,24 +109,59 @@ export function clearAccountSession(options = {}) {
   return true;
 }
 
-export function resolveAccountSdkKey(options = {}) {
+export function isBrowserSessionExpired(session, options = {}) {
+  const expiresAt = Date.parse(clean(session?.expires_at));
+  if (!Number.isFinite(expiresAt)) return false;
+  const nowMs = Number.isFinite(Number(options.nowMs)) ? Number(options.nowMs) : Date.now();
+  const skewMs = Number.isFinite(Number(options.skewMs)) ? Number(options.skewMs) : 60_000;
+  return expiresAt <= (nowMs + Math.max(0, skewMs));
+}
+
+export function resolveAccountApiKey(options = {}) {
   const env = options.env || process.env;
   const explicit = clean(options.explicit);
-  const fromEnv = resolveSdkKey(env, explicit);
-  if (fromEnv) return { value: fromEnv, source: explicit ? 'explicit' : 'environment' };
-  const session = readAccountSession({ ...options, env });
-  return session?.sdk_key
-    ? { value: session.sdk_key, source: 'agentsam_account_session', session }
-    : { value: '', source: null, session: null };
+  const value = resolveApiKey(env, explicit);
+  if (!value) return { value: '', source: null, kind: null };
+  if (!isApiKey(value)) return { value: '', source: explicit ? 'explicit' : 'environment', kind: 'api_key', error: 'invalid_api_key_prefix' };
+  return { value, source: explicit ? 'explicit' : 'environment', kind: 'api_key' };
+}
+
+export function resolveBrowserSessionCredential(options = {}) {
+  const session = readAccountSession(options);
+  if (!session?.access_token) return { value: '', source: null, kind: null, session: null, expired: false };
+  const expired = isBrowserSessionExpired(session, options);
+  return {
+    value: expired ? '' : session.access_token,
+    source: 'agentsam_browser_oauth',
+    kind: 'browser_oauth',
+    session,
+    expired,
+    error: expired ? 'browser_oauth_session_expired' : null,
+  };
+}
+
+/**
+ * Synchronous authority snapshot kept for low-level compatibility.
+ * Runtime SDK calls should use resolveAccountAuthority() from auth.js so expired
+ * OAuth sessions can refresh before a request is sent.
+ */
+export function resolveAccountAuth(options = {}) {
+  const apiKey = resolveAccountApiKey(options);
+  if (apiKey.value || apiKey.error) return apiKey;
+  return resolveBrowserSessionCredential(options);
 }
 
 export function describeAccountSession(options = {}) {
-  const resolved = resolveAccountSdkKey(options);
+  const session = readAccountSession(options);
   return {
-    configured: Boolean(resolved.value),
-    source: resolved.source,
-    user_id: resolved.session?.user_id || null,
-    account_id: resolved.session?.account_id || null,
-    email: resolved.session?.email || null,
+    configured: Boolean(session?.access_token),
+    source: session?.access_token ? 'agentsam_browser_oauth' : null,
+    kind: session?.access_token ? 'browser_oauth' : null,
+    refreshable: Boolean(session?.refresh_token),
+    expires_at: session?.expires_at || null,
+    expired: session ? isBrowserSessionExpired(session, options) : false,
+    user_id: session?.user_id || null,
+    account_id: session?.account_id || null,
+    email: session?.email || null,
   };
 }

package/src/lib/auth.js

@@ -1,71 +1,334 @@
 /**
- * Browser OAuth for SDK init — one click IAM login + Cloudflare connect.
+ * RFC 8252 native-app OAuth for AgentSam CLI.
+ *
+ * The CLI is a public client: authorization code + PKCE over a loopback
+ * redirect. Browser OAuth sessions are machine-local and remain separate from
+ * reusable AGENTSAM_API_KEY (aak_*) credentials.
  */
 import http from 'node:http';
-import { randomBytes } from 'node:crypto';
-import { postJson } from './core-client.js';
+import { createHash, randomBytes } from 'node:crypto';
+import { resolveIamIssuer } from '../../packages/identity/src/contracts/auth-config.js';
 import { promptToOpenUrl } from './open-url.js';
-import { saveAccountSession } from './account-session.js';
+import {
+  isBrowserSessionExpired,
+  readAccountSession,
+  resolveAccountApiKey,
+  saveAccountSession,
+} from './account-session.js';
 
-function randomState() {
-  return randomBytes(16).toString('hex');
+export const AGENTSAM_NATIVE_OAUTH_CLIENT_ID = 'iam_cli_agentsam';
+export const AGENTSAM_NATIVE_OAUTH_SCOPE = 'openid profile email offline_access';
+export const AGENTSAM_OAUTH_CALLBACK_PATH = '/callback';
+
+function clean(value) { return value == null ? '' : String(value).trim(); }
+function base64url(value) {
+  return Buffer.from(value).toString('base64')
+    .replace(/=/g, '')
+    .replace(/\+/g, '-')
+    .replace(/\//g, '_');
+}
+function randomUrlSafe(bytes = 32, randomBytesImpl = randomBytes) {
+  return base64url(randomBytesImpl(bytes));
+}
+function oauthErrorMessage(body, status) {
+  const code = clean(body?.error);
+  const description = clean(body?.error_description || body?.message);
+  if (code && description) return `${code}: ${description}`;
+  return code || description || `OAuth token HTTP ${status}`;
+}
+
+export function createPkcePair(options = {}) {
+  const verifier = randomUrlSafe(32, options.randomBytesImpl || randomBytes);
+  const challenge = base64url(createHash('sha256').update(verifier, 'ascii').digest());
+  return Object.freeze({ verifier, challenge, method: 'S256' });
+}
+
+export function buildNativeAuthorizationUrl(options = {}) {
+  const env = options.env || process.env;
+  const issuer = resolveIamIssuer(env, options.issuer || '');
+  const clientId = clean(options.clientId) || AGENTSAM_NATIVE_OAUTH_CLIENT_ID;
+  const redirectUri = clean(options.redirectUri);
+  const state = clean(options.state);
+  const codeChallenge = clean(options.codeChallenge);
+  const scope = clean(options.scope ?? AGENTSAM_NATIVE_OAUTH_SCOPE);
+  if (!redirectUri || !state || !codeChallenge) throw new Error('oauth_authorization_parameters_required');
+
+  const url = new URL('/api/oauth/authorize', `${issuer}/`);
+  url.searchParams.set('response_type', 'code');
+  url.searchParams.set('client_id', clientId);
+  url.searchParams.set('redirect_uri', redirectUri);
+  url.searchParams.set('code_challenge', codeChallenge);
+  url.searchParams.set('code_challenge_method', 'S256');
+  url.searchParams.set('state', state);
+  if (scope) url.searchParams.set('scope', scope);
+  return url.toString();
+}
+
+async function oauthTokenRequest(params, options = {}) {
+  const env = options.env || process.env;
+  const issuer = resolveIamIssuer(env, options.issuer || '');
+  const fetchImpl = options.fetchImpl || fetch;
+  const body = new URLSearchParams();
+  for (const [key, value] of Object.entries(params || {})) {
+    const normalized = clean(value);
+    if (normalized) body.set(key, normalized);
+  }
+
+  const response = await fetchImpl(new URL('/api/oauth/token', `${issuer}/`).toString(), {
+    method: 'POST',
+    headers: {
+      Accept: 'application/json',
+      'Content-Type': 'application/x-www-form-urlencoded',
+    },
+    body: body.toString(),
+    signal: options.signal || (typeof AbortSignal?.timeout === 'function' ? AbortSignal.timeout(15_000) : undefined),
+  });
+  const data = await response.json().catch(() => ({}));
+  if (!response.ok) {
+    const error = new Error(oauthErrorMessage(data, response.status));
+    error.status = response.status;
+    error.oauth_error = clean(data?.error) || null;
+    throw error;
+  }
+  if (!clean(data?.access_token)) throw new Error('oauth_token_response_missing_access_token');
+  return data;
+}
+
+export async function exchangeAuthorizationCode(options = {}) {
+  const code = clean(options.code);
+  const codeVerifier = clean(options.codeVerifier);
+  const redirectUri = clean(options.redirectUri);
+  if (!code || !codeVerifier || !redirectUri) throw new Error('oauth_authorization_code_exchange_parameters_required');
+  return oauthTokenRequest({
+    grant_type: 'authorization_code',
+    client_id: clean(options.clientId) || AGENTSAM_NATIVE_OAUTH_CLIENT_ID,
+    redirect_uri: redirectUri,
+    code,
+    code_verifier: codeVerifier,
+  }, options);
+}
+
+export async function refreshAccountSession(options = {}) {
+  const session = options.session || readAccountSession(options);
+  if (!session?.refresh_token) throw new Error('browser_oauth_refresh_unavailable');
+  const clientId = clean(session.client_id) || clean(options.clientId) || AGENTSAM_NATIVE_OAUTH_CLIENT_ID;
+  const refreshed = await oauthTokenRequest({
+    grant_type: 'refresh_token',
+    client_id: clientId,
+    refresh_token: session.refresh_token,
+  }, options);
+
+  return saveAccountSession({
+    ...refreshed,
+    refresh_token: clean(refreshed.refresh_token) || session.refresh_token,
+    client_id: clientId,
+    user_id: session.user_id,
+    account_id: session.account_id,
+    email: session.email,
+  }, {
+    ...options,
+    preserveRefreshToken: true,
+  });
 }
 
 /**
- * @returns {Promise<{ access_token: string, user_id: string, workspace_id: string, tenant_id: string }>}
+ * Canonical SDK account authority resolution.
+ * explicit aak_* -> AGENTSAM_API_KEY -> stored browser OAuth -> OAuth refresh.
  */
-export async function authenticateViaBrowser() {
-  const state = randomState();
-  const port = 8791 + (randomBytes(1)[0] % 20);
-  const redirectUri = `http://127.0.0.1:${port}/callback`;
+export async function resolveAccountAuthority(options = {}) {
+  const apiKey = resolveAccountApiKey(options);
+  if (apiKey.value || apiKey.error) return apiKey;
 
-  const { auth_url: authUrl } = await postJson('/api/sdk/auth/start', {
-    redirect_uri: redirectUri,
-    state,
+  let session = readAccountSession(options);
+  if (!session?.access_token) return { value: '', source: null, kind: null, session: null };
+
+  if (isBrowserSessionExpired(session, options)) {
+    if (!session.refresh_token) {
+      return {
+        value: '',
+        source: 'agentsam_browser_oauth',
+        kind: 'browser_oauth',
+        session,
+        error: 'browser_oauth_session_expired',
+      };
+    }
+    try {
+      const refreshImpl = options.refreshImpl || refreshAccountSession;
+      session = await refreshImpl({ ...options, session });
+    } catch (error) {
+      return {
+        value: '',
+        source: 'agentsam_browser_oauth',
+        kind: 'browser_oauth',
+        session,
+        error: `browser_oauth_refresh_failed: ${error?.message || String(error)}`,
+      };
+    }
+  }
+
+  return {
+    value: session.access_token,
+    source: 'agentsam_browser_oauth',
+    kind: 'browser_oauth',
+    session,
+  };
+}
+
+export async function createLoopbackCallbackListener(options = {}) {
+  const host = clean(options.host) || '127.0.0.1';
+  const callbackPath = clean(options.callbackPath) || AGENTSAM_OAUTH_CALLBACK_PATH;
+  const expectedState = clean(options.state);
+  if (!expectedState) throw new Error('oauth_state_required');
+  const timeoutMs = Number.isFinite(Number(options.timeoutMs)) ? Number(options.timeoutMs) : 180_000;
+  const createServerImpl = options.createServerImpl || http.createServer;
+
+  let settle;
+  let settled = false;
+  let timer = null;
+  const callbackPromise = new Promise((resolve, reject) => {
+    settle = (error, result) => {
+      if (settled) return;
+      settled = true;
+      if (timer) clearTimeout(timer);
+      if (error) reject(error);
+      else resolve(result);
+    };
   });
 
-  if (!authUrl) throw new Error('IAM auth did not return an authorization URL');
+  const server = createServerImpl((req, res) => {
+    try {
+      const requestUrl = new URL(req.url || '/', `http://${host}`);
+      if (requestUrl.pathname !== callbackPath) {
+        res.writeHead(404, { 'Content-Type': 'text/plain; charset=utf-8' });
+        res.end('Not found');
+        return;
+      }
 
-  const codePromise = new Promise((resolve, reject) => {
-    const server = http.createServer((req, res) => {
-      try {
-        const u = new URL(req.url || '/', `http://127.0.0.1:${port}`);
-        if (u.pathname !== '/callback') {
-          res.writeHead(404);
-          res.end('Not found');
-          return;
-        }
-        const code = u.searchParams.get('code');
-        const gotState = u.searchParams.get('state');
-        if (!code || gotState !== state) {
-          res.writeHead(400);
-          res.end('Invalid callback');
-          reject(new Error('auth callback invalid'));
-          server.close();
-          return;
-        }
-        res.writeHead(200, { 'Content-Type': 'text/html' });
-        res.end('<html><body style="font-family:system-ui"><h1>Agent Sam</h1><p>Authentication complete. You can close this tab and return to your terminal.</p></body></html>');
-        resolve(code);
-        server.close();
-      } catch (e) {
-        reject(e);
-        server.close();
+      const returnedState = clean(requestUrl.searchParams.get('state'));
+      const oauthError = clean(requestUrl.searchParams.get('error'));
+      const oauthDescription = clean(requestUrl.searchParams.get('error_description'));
+      const code = clean(requestUrl.searchParams.get('code'));
+
+      if (!returnedState || returnedState !== expectedState) {
+        res.writeHead(400, { 'Content-Type': 'text/plain; charset=utf-8' });
+        res.end('Invalid OAuth state. Return to the terminal and retry.');
+        settle(new Error('oauth_state_mismatch'));
+        return;
       }
-    });
-    server.on('error', reject);
-    server.listen(port, '127.0.0.1');
+      if (oauthError) {
+        res.writeHead(400, { 'Content-Type': 'text/plain; charset=utf-8' });
+        res.end('Authorization was not completed. Return to the terminal.');
+        settle(new Error(oauthDescription ? `${oauthError}: ${oauthDescription}` : oauthError));
+        return;
+      }
+      if (!code) {
+        res.writeHead(400, { 'Content-Type': 'text/plain; charset=utf-8' });
+        res.end('Authorization code missing. Return to the terminal and retry.');
+        settle(new Error('oauth_authorization_code_missing'));
+        return;
+      }
+
+      res.writeHead(200, { 'Content-Type': 'text/html; charset=utf-8' });
+      res.end('<!doctype html><html><body style="font-family:system-ui"><h1>Agent Sam</h1><p>Authentication complete. You can close this tab and return to your terminal.</p></body></html>');
+      settle(null, { code, state: returnedState });
+    } catch (error) {
+      try {
+        res.writeHead(500, { 'Content-Type': 'text/plain; charset=utf-8' });
+        res.end('OAuth callback failed. Return to the terminal.');
+      } catch { /* response may already be closed */ }
+      settle(error);
+    }
   });
 
-  await promptToOpenUrl(authUrl, {
-    heading: 'Authenticate your InnerAnimalMedia account at:',
-    prompt: 'Press ENTER to open InnerAnimalMedia sign-in in your browser.',
+  await new Promise((resolve, reject) => {
+    const onError = (error) => {
+      server.off('listening', onListening);
+      reject(error);
+    };
+    const onListening = () => {
+      server.off('error', onError);
+      resolve();
+    };
+    server.once('error', onError);
+    server.once('listening', onListening);
+    server.listen({ host, port: Number(options.port) || 0, exclusive: true });
   });
 
-  const code = await codePromise;
-  const session = await postJson('/api/sdk/auth/exchange', { code, state });
-  if (String(session?.access_token || '').trim().startsWith('sdk_')) {
-    saveAccountSession(session);
+  const address = server.address();
+  if (!address || typeof address === 'string') {
+    server.close();
+    throw new Error('oauth_loopback_listener_address_unavailable');
+  }
+  const redirectUri = `http://${host}:${address.port}${callbackPath}`;
+  timer = setTimeout(() => settle(new Error('oauth_callback_timeout')), Math.max(1, timeoutMs));
+  timer.unref?.();
+
+  return {
+    redirectUri,
+    waitForCallback: () => callbackPromise,
+    close: () => new Promise((resolve) => {
+      if (!server.listening) return resolve();
+      server.close(() => resolve());
+    }),
+  };
+}
+
+export async function authenticateViaBrowser(options = {}) {
+  const env = options.env || process.env;
+  const clientId = clean(options.clientId) || AGENTSAM_NATIVE_OAUTH_CLIENT_ID;
+  const state = randomUrlSafe(24, options.randomBytesImpl || randomBytes);
+  const pkce = createPkcePair({ randomBytesImpl: options.randomBytesImpl });
+  const listener = await createLoopbackCallbackListener({
+    state,
+    host: options.host,
+    port: options.port,
+    callbackPath: options.callbackPath,
+    timeoutMs: options.timeoutMs,
+    createServerImpl: options.createServerImpl,
+  });
+
+  try {
+    const authorizationUrl = buildNativeAuthorizationUrl({
+      env,
+      issuer: options.issuer,
+      clientId,
+      redirectUri: listener.redirectUri,
+      state,
+      codeChallenge: pkce.challenge,
+      scope: options.scope,
+    });
+
+    const promptImpl = options.promptToOpenUrlImpl || promptToOpenUrl;
+    await promptImpl(authorizationUrl, {
+      heading: 'Authenticate your InnerAnimalMedia account at:',
+      prompt: 'Press ENTER to open InnerAnimalMedia sign-in in your browser.',
+      input: options.input,
+      output: options.output,
+      openImpl: options.openImpl,
+    });
+
+    const callback = await listener.waitForCallback();
+    const tokenSet = await exchangeAuthorizationCode({
+      env,
+      issuer: options.issuer,
+      clientId,
+      redirectUri: listener.redirectUri,
+      code: callback.code,
+      codeVerifier: pkce.verifier,
+      fetchImpl: options.fetchImpl,
+      signal: options.signal,
+    });
+
+    return saveAccountSession({
+      ...tokenSet,
+      client_id: clientId,
+    }, {
+      home: options.home,
+      env,
+      nowMs: options.nowMs,
+      preserveRefreshToken: false,
+    });
+  } finally {
+    await listener.close();
   }
-  return session;
 }

package/src/lib/cli-preferences.js

@@ -3,8 +3,8 @@ import path from 'node:path';
 import { spawnSync } from 'node:child_process';
 import { getProjectName, tryReadProjectConfig } from './project-config.js';
 
-export const CLI_PREFERENCES_SCHEMA = 'agentsam-cli-preferences-v2';
-export const LEGACY_CLI_PREFERENCES_SCHEMA = 'agentsam-cli-preferences-v1';
+export const CLI_PREFERENCES_SCHEMA = 'agentsam-cli-preferences-v3';
+export const LEGACY_CLI_PREFERENCES_SCHEMAS = new Set(['agentsam-cli-preferences-v1', 'agentsam-cli-preferences-v2']);
 
 function readJson(filename) {
   try { return JSON.parse(fs.readFileSync(filename, 'utf8')); }
@@ -43,16 +43,43 @@ export function detectCliProject(startDir = process.cwd()) {
 
 export function cliPreferencesPath(root) { return path.join(path.resolve(root), '.agentsam', 'cli.json'); }
 
+function safeModelSnapshot(value) {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) return null;
+  const provider = String(value.provider || '').trim();
+  const providerModelId = String(value.provider_model_id || '').trim();
+  if (!provider || !providerModelId) return null;
+  return {
+    model_key: String(value.model_key || `${provider}:${providerModelId}`),
+    provider,
+    provider_model_id: providerModelId,
+    label: String(value.label || providerModelId),
+    availability: value.availability === 'available' ? 'available' : 'unverified',
+    availability_source: String(value.availability_source || ''),
+    context_window: Number.isFinite(Number(value.context_window)) && Number(value.context_window) > 0 ? Number(value.context_window) : null,
+    context_window_source: String(value.context_window_source || 'unknown'),
+    max_output_tokens: Number.isFinite(Number(value.max_output_tokens)) && Number(value.max_output_tokens) > 0 ? Number(value.max_output_tokens) : null,
+    max_output_tokens_source: String(value.max_output_tokens_source || 'unknown'),
+    reasoning_efforts: Array.isArray(value.reasoning_efforts) && value.reasoning_efforts.length ? value.reasoning_efforts.map(String) : ['auto'],
+    service_tiers: Array.isArray(value.service_tiers) && value.service_tiers.length ? value.service_tiers.map(String) : ['default'],
+    capabilities: value.capabilities && typeof value.capabilities === 'object' ? { ...value.capabilities } : {},
+    pricing: value.pricing && typeof value.pricing === 'object' ? { ...value.pricing } : null,
+    context_policy: value.context_policy && typeof value.context_policy === 'object' ? { ...value.context_policy } : null,
+    source: value.source && typeof value.source === 'object' ? { ...value.source } : null,
+  };
+}
+
 function normalizePreferences(value = {}) {
+  const modelSnapshot = safeModelSnapshot(value.modelSnapshot);
   return {
     schemaVersion: CLI_PREFERENCES_SCHEMA,
     trustedDirectory: value.trustedDirectory === true,
     runtime: value.runtime || 'local',
     terminal: value.terminal || '',
     modelPreference: value.modelPreference || 'auto',
+    modelSnapshot,
     reasoningEffort: value.reasoningEffort || 'auto',
     serviceTier: value.serviceTier || 'default',
-    modelAuthority: 'preference-only',
+    modelAuthority: modelSnapshot?.availability === 'available' ? 'provider-verified' : 'preference-only',
     updatedAt: value.updatedAt || null,
   };
 }
@@ -60,7 +87,7 @@ function normalizePreferences(value = {}) {
 export function readCliPreferences(root) {
   const value = readJson(cliPreferencesPath(root));
   if (!value) return null;
-  if (value.schemaVersion !== CLI_PREFERENCES_SCHEMA && value.schemaVersion !== LEGACY_CLI_PREFERENCES_SCHEMA) return null;
+  if (value.schemaVersion !== CLI_PREFERENCES_SCHEMA && !LEGACY_CLI_PREFERENCES_SCHEMAS.has(value.schemaVersion)) return null;
   return normalizePreferences(value);
 }