@inneranimalmedia/agentsam-sdk 2.6.1 → 2.6.2

package/src/commands/providers.js

@@ -0,0 +1,308 @@
+import {
+  cancel,
+  confirm,
+  intro,
+  isCancel,
+  multiselect,
+  outro,
+  password,
+  spinner,
+  text,
+} from '@clack/prompts';
+import { getJson } from '../lib/core-client.js';
+import {
+  PROVIDER_CREDENTIALS,
+  describeProviderCredential,
+  listProviderCredentialStatus,
+  normalizeProviderId,
+  providerCredentialSpec,
+  removeProviderCredential,
+  resolveProviderCredential,
+  setProviderCredential,
+} from '../lib/provider-credentials.js';
+import { discoverProviderModels } from '../models/discovery.js';
+
+const PROVIDER_ORDER = Object.freeze([
+  'openai',
+  'anthropic',
+  'gemini',
+  'cursor',
+  'xai',
+  'cloudflare',
+  'inneranimalmedia',
+]);
+
+function clean(value) { return value == null ? '' : String(value).trim(); }
+function writeLine(write, value = '') { write(`${value}\n`); }
+
+export function providerChoices(options = {}) {
+  const statuses = new Map(listProviderCredentialStatus(options).map((row) => [row.provider, row]));
+  return PROVIDER_ORDER.map((provider) => {
+    const spec = providerCredentialSpec(provider);
+    const status = statuses.get(provider);
+    return {
+      value: provider,
+      label: spec?.label || provider,
+      hint: status?.configured
+        ? `configured · ${status.source || 'runtime'}`
+        : status?.error ? `blocked · ${status.error}` : spec?.env || '',
+    };
+  });
+}
+
+async function verifyInnerAnimalMedia(credential, options = {}) {
+  if (!credential?.configured || !credential?.value) {
+    return { attempted: false, ok: false, error: credential?.error || 'credential unavailable', models: [] };
+  }
+  try {
+    const loader = options.iamContextLoader || ((token) => getJson('/api/sdk/context', token));
+    const context = await loader(credential.value);
+    return {
+      attempted: true,
+      ok: true,
+      error: null,
+      models: [],
+      identity: {
+        user_id: context?.user_id || null,
+        account_id: context?.account_id || null,
+        email: context?.email || context?.user?.email || null,
+      },
+    };
+  } catch (error) {
+    return { attempted: true, ok: false, error: error?.message || String(error), models: [] };
+  }
+}
+
+export async function verifyProviderCredential(provider, options = {}) {
+  const id = normalizeProviderId(provider);
+  const credential = resolveProviderCredential(id, options);
+  if (id === 'inneranimalmedia') return verifyInnerAnimalMedia(credential, options);
+  if (!credential.configured) {
+    return { attempted: false, ok: false, error: credential.error || 'credential unavailable', models: [] };
+  }
+  return discoverProviderModels(id, credential, { fetchImpl: options.fetchImpl || fetch });
+}
+
+export async function collectProviderStatus(options = {}) {
+  const rows = listProviderCredentialStatus(options);
+  if (options.verify !== true) {
+    return rows.map((row) => ({ ...row, verification: null }));
+  }
+  const verified = await Promise.all(rows.map(async (row) => {
+    if (!row.configured) return { ...row, verification: null };
+    const verification = await verifyProviderCredential(row.provider, options);
+    return {
+      ...row,
+      verification: {
+        attempted: verification.attempted === true,
+        ok: verification.ok === true,
+        error: verification.error || null,
+        model_count: Array.isArray(verification.models) ? verification.models.length : 0,
+      },
+    };
+  }));
+  return verified;
+}
+
+export function renderProviderStatus(rows = []) {
+  const lines = ['', '  Agent Sam · providers', ''];
+  for (const row of rows) {
+    const state = row.configured ? 'configured' : row.error ? `blocked (${row.error})` : 'not configured';
+    let verification = '';
+    if (row.verification) {
+      verification = row.verification.ok
+        ? ` · verified${row.verification.model_count ? ` · ${row.verification.model_count} models` : ''}`
+        : ` · verify failed: ${row.verification.error || 'unknown'}`;
+    }
+    lines.push(`  ${String(row.label || row.provider).padEnd(18)} ${state}${verification}`);
+  }
+  lines.push('');
+  lines.push('  Profiles: ~/.agentsam/env.d/<provider>.env · mode 0600');
+  lines.push('  Load one or many: source ~/.agentsam/load-agent-env.sh openai gemini cursor');
+  lines.push('');
+  return lines.join('\n');
+}
+
+async function promptProviderCredential(provider, options = {}) {
+  const spec = providerCredentialSpec(provider);
+  if (!spec) throw new Error(`unsupported_provider:${provider}`);
+  const promptPassword = options.passwordImpl || password;
+  const promptText = options.textImpl || text;
+  const secret = await promptPassword({
+    message: `${spec.label} · ${spec.env}`,
+    mask: '•',
+    validate(value) {
+      const trimmed = clean(value);
+      if (!trimmed) return 'Credential is required';
+      if (spec.tokenPrefix && !trimmed.startsWith(spec.tokenPrefix)) return `Expected ${spec.tokenPrefix}…`;
+    },
+  });
+  if (isCancel(secret)) return null;
+
+  let accountId = '';
+  if (provider === 'cloudflare') {
+    const answer = await promptText({
+      message: 'Cloudflare account ID',
+      placeholder: '32-character account ID',
+      validate(value) {
+        const id = clean(value);
+        if (!id) return 'Cloudflare account ID is required';
+        if (!/^[a-f0-9]{32}$/i.test(id)) return 'Expected a 32-character hexadecimal account ID';
+      },
+    });
+    if (isCancel(answer)) return null;
+    accountId = clean(answer);
+  }
+
+  setProviderCredential(provider, String(secret), { ...options, accountId });
+  return verifyProviderCredential(provider, options);
+}
+
+async function runInteractiveProviders(options = {}) {
+  const promptMultiselect = options.multiselectImpl || multiselect;
+  const selected = await promptMultiselect({
+    message: 'Providers to configure',
+    required: false,
+    options: providerChoices(options),
+  });
+  if (isCancel(selected)) {
+    cancel('Provider setup cancelled.');
+    return collectProviderStatus(options);
+  }
+  if (!selected.length) return collectProviderStatus(options);
+
+  intro('Agent Sam provider setup');
+  const spin = options.spinnerImpl ? options.spinnerImpl() : spinner();
+  for (const provider of selected) {
+    const result = await promptProviderCredential(provider, options);
+    if (!result) continue;
+    spin.start(`Verifying ${providerCredentialSpec(provider)?.label || provider}`);
+    if (result.ok) {
+      const suffix = result.models?.length ? ` · ${result.models.length} models` : '';
+      spin.stop(`Verified${suffix}`);
+    } else {
+      spin.stop(`Saved · verification failed: ${result.error || 'unknown'}`, 1);
+    }
+  }
+  outro('Provider setup complete');
+  return collectProviderStatus(options);
+}
+
+function parseArgs(argv = []) {
+  const out = { command: 'interactive', provider: '', json: false, verify: false, yes: false, fromEnv: '' };
+  const args = [...argv];
+  if (args[0] && !args[0].startsWith('-')) out.command = args.shift();
+  if (['add', 'set', 'remove', 'verify', 'status'].includes(out.command) && args[0] && !args[0].startsWith('-')) {
+    out.provider = normalizeProviderId(args.shift());
+  }
+  while (args.length) {
+    const arg = args.shift();
+    if (arg === '--json') out.json = true;
+    else if (arg === '--verify') out.verify = true;
+    else if (arg === '--yes' || arg === '-y') out.yes = true;
+    else if (arg === '--from-env') out.fromEnv = clean(args.shift());
+    else if (arg === '--help' || arg === '-h') out.command = 'help';
+    else throw new Error(`unknown providers option: ${arg}`);
+  }
+  return out;
+}
+
+export async function runProviders(argv = [], options = {}) {
+  const write = options.write || ((value) => process.stdout.write(value));
+  const parsed = parseArgs(argv);
+
+  if (parsed.command === 'help') {
+    write([
+      'agentsam providers',
+      'agentsam providers status [provider] [--verify] [--json]',
+      'agentsam providers add <provider> [--from-env NAME]',
+      'agentsam providers verify [provider] [--json]',
+      'agentsam providers remove <provider> [--yes]',
+      '',
+      `Providers: ${PROVIDER_ORDER.join(', ')}`,
+      '',
+    ].join('\n'));
+    return;
+  }
+
+  if (parsed.command === 'interactive') {
+    if (options.interactive === false || !(options.interactive ?? Boolean(process.stdin.isTTY && process.stdout.isTTY))) {
+      const rows = await collectProviderStatus({ ...options, verify: false });
+      write(renderProviderStatus(rows));
+      return rows;
+    }
+    const rows = await runInteractiveProviders(options);
+    write(renderProviderStatus(rows));
+    return rows;
+  }
+
+  if (parsed.provider && !providerCredentialSpec(parsed.provider)) throw new Error(`unsupported_provider:${parsed.provider}`);
+
+  if (parsed.command === 'status') {
+    let rows = await collectProviderStatus({ ...options, verify: parsed.verify });
+    if (parsed.provider) rows = rows.filter((row) => row.provider === parsed.provider);
+    if (parsed.json) writeLine(write, JSON.stringify(rows, null, 2));
+    else write(renderProviderStatus(rows));
+    return rows;
+  }
+
+  if (parsed.command === 'verify') {
+    const providers = parsed.provider
+      ? [parsed.provider]
+      : Object.keys(PROVIDER_CREDENTIALS).filter((provider) => describeProviderCredential(provider, options).configured);
+    const results = [];
+    for (const provider of providers) {
+      const result = await verifyProviderCredential(provider, options);
+      results.push({
+        provider,
+        ok: result.ok === true,
+        error: result.error || null,
+        model_count: Array.isArray(result.models) ? result.models.length : 0,
+      });
+    }
+    if (parsed.json) writeLine(write, JSON.stringify(results, null, 2));
+    else {
+      writeLine(write, '');
+      for (const row of results) {
+        writeLine(write, `  ${row.provider.padEnd(18)} ${row.ok ? `verified${row.model_count ? ` · ${row.model_count} models` : ''}` : `failed · ${row.error}`}`);
+      }
+      writeLine(write, '');
+    }
+    return results;
+  }
+
+  if (parsed.command === 'add' || parsed.command === 'set') {
+    if (!parsed.provider) throw new Error('providers add requires a provider');
+    if (parsed.fromEnv) {
+      const value = clean((options.env || process.env)[parsed.fromEnv]);
+      if (!value) throw new Error(`environment credential missing: ${parsed.fromEnv}`);
+      setProviderCredential(parsed.provider, value, options);
+      return verifyProviderCredential(parsed.provider, options);
+    }
+    if (options.interactive === false || !(options.interactive ?? Boolean(process.stdin.isTTY && process.stdout.isTTY))) {
+      throw new Error('providers add requires an interactive terminal or --from-env NAME');
+    }
+    const result = await promptProviderCredential(parsed.provider, options);
+    if (!result) return null;
+    writeLine(write, result.ok ? `  ${parsed.provider} verified` : `  ${parsed.provider} saved · verification failed: ${result.error}`);
+    return result;
+  }
+
+  if (parsed.command === 'remove') {
+    if (!parsed.provider) throw new Error('providers remove requires a provider');
+    let approved = parsed.yes;
+    if (!approved) {
+      if (options.interactive === false || !(options.interactive ?? Boolean(process.stdin.isTTY && process.stdout.isTTY))) {
+        throw new Error('providers remove requires --yes in non-interactive mode');
+      }
+      const answer = await (options.confirmImpl || confirm)({ message: `Remove ${providerCredentialSpec(parsed.provider)?.label} credential profile from this machine?` });
+      approved = !isCancel(answer) && answer === true;
+    }
+    if (!approved) return { provider: parsed.provider, removed: false };
+    const result = removeProviderCredential(parsed.provider, options);
+    writeLine(write, result.removed ? `  removed ${parsed.provider}` : `  ${parsed.provider} was not configured`);
+    return result;
+  }
+
+  throw new Error(`unknown providers command: ${parsed.command}`);
+}

package/src/commands/shell.js

@@ -10,6 +10,7 @@ import { runDb } from './db.js';
 import { runDeploy } from './deploy.js';
 import { runStatus } from './status.js';
 import { runModels } from './models.js';
+import { runProviders } from './providers.js';
 import { configureCliPreferences } from './preferences.js';
 import { runCloudflare } from './cloudflare.js';
 import { probeOllamaModel, resolveOllamaConfig } from './ollama.js';
@@ -593,6 +594,9 @@ export async function dispatchShellLine(line, state = {}) {
       case '/models':
         await runModels(args, { cwd: state.cwd, write, home: state.home });
         break;
+      case '/providers':
+        await runProviders(args, { write, home: state.home, interactive: state.interactive });
+        break;
       case '/login':
         await runLogin(args, { write, home: state.home });
         break;

package/src/commands/tunnel.js

@@ -7,7 +7,7 @@
 import { spawn, spawnSync } from 'node:child_process';
 import { authenticateViaBrowser } from '../lib/auth.js';
 import { postJson } from '../lib/core-client.js';
-import { resolveAccountSdkKey } from '../lib/account-session.js';
+import { resolveAccountAuth } from '../lib/account-session.js';
 
 const DEFAULT_PORT = 3099;
 
@@ -33,7 +33,7 @@ function parseArgs(argv) {
     else if (a === '--platform') opts.platform = argv[++i] || opts.platform;
     else if (a === '--shell') opts.shell = argv[++i] || opts.shell;
     else if (a === '--token' && argv[i + 1]) {
-      process.env.AGENTSAM_SDK_KEY = argv[++i];
+      process.env.AGENTSAM_API_KEY = argv[++i];
     }
   }
   return opts;
@@ -51,13 +51,13 @@ function ensureCloudflared() {
 }
 
 async function resolveToken() {
-  const existing = resolveAccountSdkKey({ env: process.env }).value;
-  if (existing.startsWith('sdk_')) return existing;
+  const existing = resolveAccountAuth({ env: process.env });
+  if (existing.value) return existing.value;
+  if (existing.error) throw new Error(existing.error);
   const session = await authenticateViaBrowser();
-  const tok = String(session?.access_token || '').trim();
-  if (!tok.startsWith('sdk_')) throw new Error('IAM auth did not return an sdk_ bearer key');
-  process.env.AGENTSAM_SDK_KEY = tok;
-  return tok;
+  const token = String(session?.access_token || '').trim();
+  if (!token) throw new Error('IAM auth did not return a browser session credential');
+  return token;
 }
 
 async function assertLocalPty(port) {

package/src/commands/whoami.js

@@ -1,49 +1,68 @@
 import { getJson } from '../lib/core-client.js';
-import { resolveAccountSdkKey } from '../lib/account-session.js';
+import {
+  describeAccountSession,
+  resolveAccountApiKey,
+  resolveAccountAuth,
+} from '../lib/account-session.js';
 import { listProviderCredentialStatus } from '../lib/provider-credentials.js';
 
 function writeLine(write, value = '') { write(`${value}\n`); }
 
 export async function collectWhoami(options = {}) {
   const env = options.env || process.env;
-  const sdk = resolveAccountSdkKey({ env, explicit: options.token || '', home: options.home });
-  const token = sdk.value;
+  const apiKey = resolveAccountApiKey({ env, explicit: options.token || '', home: options.home });
+  const browserSession = describeAccountSession({ env, home: options.home });
+  const active = resolveAccountAuth({ env, explicit: options.token || '', home: options.home });
   const credentials = listProviderCredentialStatus({ env, home: options.home });
-  if (!token) return {
-    schema_version: 1,
+
+  const base = {
+    schema_version: 2,
     authenticated: false,
     authority: 'iam',
     identity: null,
-    sdk_credential: { configured: false, source: null },
+    active_auth: {
+      configured: Boolean(active.value || active.error),
+      kind: active.kind || null,
+      source: active.source || null,
+      valid: null,
+      error: active.error || null,
+    },
+    api_key: {
+      configured: Boolean(apiKey.value || apiKey.error),
+      source: apiKey.source || null,
+      valid: apiKey.error ? false : null,
+      error: apiKey.error || null,
+    },
+    browser_session: browserSession,
     provider_credentials: credentials,
   };
+
+  if (!active.value) return base;
+
   try {
-    const loader = options.contextLoader || ((sdkKey) => getJson('/api/sdk/context', sdkKey));
-    const context = await loader(token);
+    const loader = options.contextLoader || ((token) => getJson('/api/sdk/context', token));
+    const context = await loader(active.value);
     return {
-      schema_version: 1,
+      ...base,
       authenticated: true,
-      authority: 'iam',
       identity: {
         user_id: context?.user_id || null,
         account_id: context?.account_id || null,
         email: context?.email || context?.user?.email || null,
       },
-      sdk_credential: { configured: true, source: sdk.source, valid: true },
-      provider_credentials: credentials,
+      active_auth: { ...base.active_auth, valid: true, error: null },
+      api_key: active.kind === 'api_key' ? { ...base.api_key, valid: true, error: null } : base.api_key,
       cloudflare_connected: context?.cloudflare?.ok === true,
       byok: context?.byok && typeof context.byok === 'object'
         ? Object.fromEntries(Object.entries(context.byok).map(([key, value]) => [key, { configured: value?.configured === true }]))
         : {},
     };
   } catch (error) {
+    const message = error?.message || String(error);
     return {
-      schema_version: 1,
-      authenticated: false,
-      authority: 'iam',
-      identity: null,
-      sdk_credential: { configured: true, source: sdk.source, valid: false, error: error?.message || String(error) },
-      provider_credentials: credentials,
+      ...base,
+      active_auth: { ...base.active_auth, valid: false, error: message },
+      api_key: active.kind === 'api_key' ? { ...base.api_key, valid: false, error: message } : base.api_key,
     };
   }
 }
@@ -56,17 +75,19 @@ export function renderWhoami(status) {
     if (status.identity?.email) lines.push(`  email          ${status.identity.email}`);
     if (status.identity?.account_id) lines.push(`  account        ${status.identity.account_id}`);
     if (status.identity?.user_id) lines.push(`  user           ${status.identity.user_id}`);
+    lines.push(`  active auth    ${status.active_auth?.kind || 'unknown'} · ${status.active_auth?.source || 'runtime'}`);
   } else {
     lines.push('  authenticated  no');
-    lines.push(`  SDK key        ${status.sdk_credential?.configured ? 'present but not validated' : 'not configured'}`);
-    if (status.sdk_credential?.error) lines.push(`  error          ${status.sdk_credential.error}`);
+    lines.push(`  API key        ${status.api_key?.configured ? status.api_key?.valid === false ? 'invalid' : 'configured' : 'not configured'}`);
+    lines.push(`  browser login  ${status.browser_session?.configured ? 'stored' : 'not configured'}`);
+    if (status.active_auth?.error) lines.push(`  error          ${status.active_auth.error}`);
   }
   lines.push('');
   lines.push('  Provider credentials');
   for (const row of status.provider_credentials || []) {
     const state = row.configured ? 'available' : row.error ? `blocked (${row.error})` : 'not configured';
     const source = row.source ? ` · ${row.source}` : '';
-    lines.push(`  ${String(row.provider).padEnd(12)} ${state}${source}`);
+    lines.push(`  ${String(row.provider).padEnd(16)} ${state}${source}`);
   }
   lines.push('');
   lines.push('  Secret values are never printed by whoami.');

package/src/errors/diagnostic.js

@@ -3,6 +3,7 @@ const SECRET_KEY = /(?:authorization|api[-_]?key|access[-_]?token|refresh[-_]?to
 const SECRET_VALUE_PATTERNS = [
   /\bBearer\s+[A-Za-z0-9._~+\/-]+=*/gi,
   /\bsk-[A-Za-z0-9_-]{12,}\b/g,
+  /\baak_[A-Za-z0-9_-]{8,}\b/g,
   /\bsdk_[A-Za-z0-9_-]{8,}\b/g,
   /\bgh[pousr]_[A-Za-z0-9]{20,}\b/g,
 ];

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,
   };
 }