@inneranimalmedia/agentsam-sdk 2.6.1 → 2.6.3

package/src/knowledge/service/job-engine.js

@@ -5,23 +5,83 @@ import { fork } from 'node:child_process';
 import { DatabaseSync } from 'node:sqlite';
 import { fileURLToPath } from 'node:url';
 import { fingerprint, validateConfig } from '../config.js';
+import {
+  AgentSamError,
+  ERROR_CODE,
+  ERROR_REASON,
+  createErrorEnvelope,
+  normalizeError,
+  parseError,
+} from '../../errors/index.js';
 
 const defaultWorkerPath = fileURLToPath(new URL('./job-worker.js', import.meta.url));
 const TERMINAL_STATUSES = new Set(['completed', 'failed']);
 
+function serviceReason(code) {
+  switch (code) {
+    case ERROR_CODE.UNAUTHENTICATED: return ERROR_REASON.AUTH_INVALID;
+    case ERROR_CODE.PERMISSION_DENIED: return ERROR_REASON.PERMISSION_DENIED;
+    case ERROR_CODE.NOT_FOUND: return ERROR_REASON.TARGET_NOT_FOUND;
+    case ERROR_CODE.ABORTED: return ERROR_REASON.CONFLICT;
+    case ERROR_CODE.RESOURCE_EXHAUSTED: return ERROR_REASON.CAPACITY_EXHAUSTED;
+    case ERROR_CODE.UNAVAILABLE: return ERROR_REASON.TRANSPORT_UNREACHABLE;
+    case ERROR_CODE.DEADLINE_EXCEEDED: return ERROR_REASON.DEADLINE_EXCEEDED;
+    case ERROR_CODE.INVALID_ARGUMENT: return ERROR_REASON.INPUT_INVALID;
+    default: return ERROR_REASON.INTERNAL;
+  }
+}
+
 export function serviceError(status, message, code) {
-  return Object.assign(new Error(message), { status, code });
+  const canonical = code === 'CONFLICT' ? ERROR_CODE.ABORTED : (Object.values(ERROR_CODE).includes(code) ? code : ERROR_CODE.INTERNAL);
+  const envelope = createErrorEnvelope({
+    code: canonical,
+    reason: serviceReason(canonical),
+    message,
+    http_status: status,
+    retryable: [429, 503, 504].includes(Number(status)),
+    source: { kind: 'agentsam', name: 'agentsam-knowledge', service: 'job_engine' },
+    resolution_owner: canonical === ERROR_CODE.UNAVAILABLE ? 'agentsam' : undefined,
+    domain: 'knowledge',
+    stage: 'request',
+  });
+  return new AgentSamError(envelope);
+}
+
+function decodeFailure(row) {
+  if (row?.failure_json) {
+    try { return parseError(row.failure_json); }
+    catch {
+      return createErrorEnvelope({
+        reason: ERROR_REASON.INTERNAL_CONTRACT_VIOLATION,
+        message: 'Stored knowledge failure could not be decoded.',
+        source: { kind: 'agentsam', name: 'agentsam-knowledge', service: 'job_engine' },
+        domain: 'knowledge',
+        stage: 'persistence',
+      });
+    }
+  }
+  if (!row?.error) return null;
+  return createErrorEnvelope({
+    reason: ERROR_REASON.EXECUTION_FAILED,
+    message: row.error,
+    source: { kind: 'agentsam', name: 'agentsam-knowledge', service: 'legacy_job_row' },
+    domain: 'knowledge',
+    stage: 'execute',
+  });
 }
 
 function decode(row) {
-  return row && {
+  if (!row) return null;
+  const failure = decodeFailure(row);
+  return {
     id: row.id,
     status: row.status,
     attempts: row.attempts,
     created_at: row.created_at,
     updated_at: row.updated_at,
     result: row.result ? JSON.parse(row.result) : null,
-    error: row.error,
+    failure,
+    error: failure?.message || row.error || null,
   };
 }
 
@@ -100,10 +160,22 @@ export function createKnowledgeJobEngine({
   db.exec(`PRAGMA journal_mode=WAL; PRAGMA busy_timeout=5000;
     CREATE TABLE IF NOT EXISTS jobs (id TEXT PRIMARY KEY, idem TEXT UNIQUE, digest TEXT NOT NULL,
       payload TEXT NOT NULL, status TEXT NOT NULL, attempts INTEGER NOT NULL DEFAULT 0,
-      created_at TEXT NOT NULL, updated_at TEXT NOT NULL, result TEXT, error TEXT);
+      created_at TEXT NOT NULL, updated_at TEXT NOT NULL, result TEXT, error TEXT, failure_json TEXT);
     CREATE INDEX IF NOT EXISTS jobs_pending ON jobs(status, created_at);`);
+  const columns = new Set(db.prepare('PRAGMA table_info(jobs)').all().map(row => row.name));
+  if (!columns.has('failure_json')) db.exec('ALTER TABLE jobs ADD COLUMN failure_json TEXT');
   fs.chmodSync(jobsFile, 0o600);
-  db.prepare("UPDATE jobs SET status=CASE WHEN attempts>=3 THEN 'failed' ELSE 'queued' END, error=CASE WHEN attempts>=3 THEN 'Interrupted three times; submit a new job after investigation.' ELSE NULL END WHERE status='running'").run();
+  const interruptedFailure = createErrorEnvelope({
+    reason: ERROR_REASON.EXECUTION_FAILED,
+    message: 'Interrupted three times; submit a new job after investigation.',
+    source: { kind: 'agentsam', name: 'agentsam-knowledge', service: 'job_engine' },
+    domain: 'knowledge',
+    stage: 'recovery',
+  });
+  db.prepare("UPDATE jobs SET status=CASE WHEN attempts>=3 THEN 'failed' ELSE 'queued' END, error=CASE WHEN attempts>=3 THEN ? ELSE NULL END, failure_json=CASE WHEN attempts>=3 THEN ? ELSE NULL END WHERE status='running'").run(
+    interruptedFailure.message,
+    JSON.stringify(interruptedFailure),
+  );
 
   let child = null;
   let closing = false;
@@ -120,11 +192,17 @@ export function createKnowledgeJobEngine({
     }
     if (TERMINAL_STATUSES.has(job.status)) watchers.delete(job.id);
   };
-  const updateStatus = (id, status, { result = null, error = null } = {}) => {
-    db.prepare('UPDATE jobs SET status=?,result=?,error=?,updated_at=? WHERE id=?').run(
+  const updateStatus = (id, status, { result = null, failure = null, error = null } = {}) => {
+    const normalizedFailure = failure
+      ? normalizeError(failure, { source: { kind: 'agentsam', name: 'agentsam-knowledge', service: 'job_engine' }, domain: 'knowledge', stage: 'execute' })
+      : error
+        ? createErrorEnvelope({ reason: ERROR_REASON.EXECUTION_FAILED, message: error, source: { kind: 'agentsam', name: 'agentsam-knowledge', service: 'job_engine' }, domain: 'knowledge', stage: 'execute' })
+        : null;
+    db.prepare('UPDATE jobs SET status=?,result=?,error=?,failure_json=?,updated_at=? WHERE id=?').run(
       status,
       result === null ? null : JSON.stringify(result),
-      error,
+      normalizedFailure?.message || null,
+      normalizedFailure ? JSON.stringify(normalizedFailure) : null,
       new Date().toISOString(),
       id,
     );
@@ -145,15 +223,49 @@ export function createKnowledgeJobEngine({
     child = fork(workerPath, [], { execArgv: [], stdio: ['ignore', 'ignore', 'ignore', 'ipc'], env: { ...process.env, GIT_OPTIONAL_LOCKS: '0' } });
     const timer = setTimeout(() => { timedOut = true; child?.kill('SIGKILL'); }, jobTimeoutMs);
     child.once('message', value => { response = value; });
-    child.once('error', () => { response = { ok: false, error: 'Could not start indexing process.' }; });
+    child.once('error', (cause) => {
+      response = {
+        ok: false,
+        failure: createErrorEnvelope({
+          reason: ERROR_REASON.INTERNAL_DEPENDENCY_FAILED,
+          message: 'Could not start indexing process.',
+          source: { kind: 'agentsam', name: 'agentsam-knowledge', service: 'job_worker' },
+          domain: 'knowledge',
+          stage: 'spawn',
+          native: { code: cause?.code || null, exception_type: cause?.name || null, stack: cause?.stack || null },
+        }),
+      };
+    });
     child.once('close', () => {
       clearTimeout(timer);
       child = null;
       if (!closing) {
         const ok = response?.ok && !timedOut;
+        let failure = null;
+        if (!ok) {
+          if (timedOut) {
+            failure = createErrorEnvelope({
+              reason: ERROR_REASON.EXECUTION_TIMEOUT,
+              message: 'Knowledge job exceeded its time limit; narrow the scope and retry.',
+              source: { kind: 'runtime', name: 'agentsam-knowledge-worker' },
+              domain: 'knowledge',
+              stage: 'execute',
+            });
+          } else if (response?.failure) {
+            failure = normalizeError(response.failure, { source: { kind: 'agentsam', name: 'agentsam-knowledge', service: 'job_worker' }, domain: 'knowledge', stage: 'execute' });
+          } else {
+            failure = createErrorEnvelope({
+              reason: ERROR_REASON.EXECUTION_FAILED,
+              message: response?.error || 'Indexing process exited unexpectedly.',
+              source: { kind: 'agentsam', name: 'agentsam-knowledge', service: 'job_worker' },
+              domain: 'knowledge',
+              stage: 'execute',
+            });
+          }
+        }
         updateStatus(row.id, ok ? 'completed' : 'failed', {
           result: ok ? response.result : null,
-          error: ok ? null : timedOut ? 'Job exceeded its time limit; narrow the scope.' : response?.error || 'Indexing process exited unexpectedly.',
+          failure,
         });
       }
       pumping = false;
@@ -162,7 +274,17 @@ export function createKnowledgeJobEngine({
     const payload = JSON.parse(row.payload);
     const registered = registry[payload.request.repository];
     if (!registered || registered.config.repository_id !== payload.config.repository_id || fingerprint(registered.config.scope) !== payload.registered_scope || (!allowEmbeddings && ((payload.request.embed && payload.request.operation !== 'plan') || payload.request.semantic))) {
-      response = { ok: false, error: 'Repository registration changed; resubmit this job.' };
+      response = {
+        ok: false,
+        failure: createErrorEnvelope({
+          reason: ERROR_REASON.REPOSITORY_CHANGED,
+          message: 'Repository registration changed; resubmit this job.',
+          source: { kind: 'agentsam', name: 'agentsam-knowledge', service: 'repository_registry' },
+          domain: 'repository',
+          stage: 'execute',
+          resource: { type: 'repository', id: payload.config.repository_id || null },
+        }),
+      };
       child.kill();
       return;
     }

package/src/knowledge/service/job-worker.js

@@ -3,12 +3,27 @@ import { openSqliteStore } from '../stores/sqlite.js';
 import { createGeminiEmbedder } from '../providers/gemini.js';
 import { inventory } from '../source.js';
 import { scopeKey } from '../config.js';
+import {
+  AgentSamError,
+  ERROR_REASON,
+  createErrorEnvelope,
+  normalizeError,
+} from '../../errors/index.js';
 
 // Parsing and vector ranking run in a child process, keeping HTTP acceptance responsive.
 process.once('message', async ({ root, config, filename, request, maxFiles }) => {
   let store;
   try {
-    if (request.operation !== 'search' && inventory(root, config.scope).length > maxFiles) throw new Error(`Scope exceeds ${maxFiles} files; choose a smaller include set.`);
+    if (request.operation !== 'search' && inventory(root, config.scope).length > maxFiles) throw new AgentSamError(createErrorEnvelope({
+      reason: ERROR_REASON.INPUT_OUT_OF_RANGE,
+      message: `Scope exceeds ${maxFiles} files; choose a smaller include set.`,
+      source: { kind: 'user', name: 'knowledge_request' },
+      resolution_owner: 'user',
+      domain: 'knowledge',
+      stage: 'inventory',
+      remediation: { action: 'reduce_scope', message: 'Narrow the repository include scope and retry.' },
+      resource: { type: 'repository', id: config.repository_id || null },
+    }));
     store = await openSqliteStore(filename);
     const embedder = request.operation !== 'plan' && (request.embed || request.semantic) ? createGeminiEmbedder({ apiKey: process.env.GEMINI_API_KEY }) : undefined;
     let result;
@@ -18,7 +33,15 @@ process.once('message', async ({ root, config, filename, request, maxFiles }) =>
       const generation = request.generation_id ? await store.getGeneration(scopeKey(config), request.generation_id) : await store.active(scopeKey(config));
       const under = (file, selection) => selection === '.' || file === selection || file.startsWith(selection + '/');
       if (generation?.files.some(file => !config.scope.include.some(p => under(file.path, p)) || config.scope.exclude.some(p => under(file.path, p)))) {
-        throw new Error('Generation exceeds the requested scope; select a matching scope or reindex.');
+        throw new AgentSamError(createErrorEnvelope({
+          reason: ERROR_REASON.PRECONDITION_FAILED,
+          message: 'Generation exceeds the requested scope; select a matching scope or reindex.',
+          source: { kind: 'user', name: 'knowledge_request' },
+          domain: 'knowledge',
+          stage: 'search',
+          remediation: { action: 'change_configuration', message: 'Select a matching indexed scope or reindex the requested scope.' },
+          resource: { type: 'repository', id: config.repository_id || null },
+        }));
       }
       result = await retrieve({ store, config, text: request.query, semantic: request.semantic, embedder,
         topK: request.top_k, tokenBudget: request.token_budget, generationId: request.generation_id });
@@ -27,8 +50,14 @@ process.once('message', async ({ root, config, filename, request, maxFiles }) =>
     process.send({ ok: true, result }, () => process.exit(0));
   } catch (error) {
     await store?.close();
-    // Provider error strings may include sensitive request details. Never persist them.
-    const message = request.embed || request.semantic ? 'Embedding job failed; check provider configuration, budgets, and availability.' : String(error.message).slice(0, 500);
-    process.send({ ok: false, error: message }, () => process.exit(1));
+    const failure = normalizeError(error, {
+      source: { kind: 'agentsam', name: 'agentsam-knowledge', service: 'job_worker' },
+      domain: 'knowledge',
+      stage: request.embed || request.semantic ? 'embedding' : request.operation || 'execute',
+      message: request.embed || request.semantic
+        ? 'Embedding job failed; inspect the canonical failure for provider/configuration details.'
+        : undefined,
+    });
+    process.send({ ok: false, failure }, () => process.exit(1));
   }
 });

package/src/knowledge/service/server.js

@@ -4,6 +4,7 @@ import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { createBearerTokenVerifier } from './auth.js';
 import { createKnowledgeJobEngine, serviceError } from './job-engine.js';
+import { normalizeError, toHttpError } from '../../errors/index.js';
 
 async function readBody(req) {
   const chunks = [];
@@ -44,7 +45,15 @@ export async function startKnowledgeHttpServer({ engine, token, verifyToken, por
       const { job, created } = engine.submitJob(await readBody(req), { idempotencyKey: req.headers['idempotency-key'] });
       return send(created ? 202 : 200, job);
     } catch (error) {
-      if (!res.writableEnded) send(error.status || 500, { error: error.status ? error.message : 'Service request failed.' });
+      if (!res.writableEnded) {
+        const envelope = normalizeError(error, {
+          source: { kind: 'agentsam', name: 'agentsam-knowledge', service: 'http_server' },
+          domain: 'knowledge',
+          stage: 'request',
+        });
+        const httpError = toHttpError(envelope);
+        send(httpError.status, httpError.body);
+      }
     }
   });
   server.requestTimeout = 15000;

package/src/knowledge/store-discovery.js

@@ -0,0 +1,77 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { CONFIG_PATH, readConfig, validateConfig, defaultConfig } from './config.js';
+import { findCliProjectRoot } from '../lib/cli-preferences.js';
+import { runtimeDatabasePath } from '../local/runtime-store.js';
+import { getRepositoryId, portableRepositoryIdFromGit, tryReadProjectConfig } from '../lib/project-config.js';
+
+// Configuration evidence only. No connection probes, credential reads, or schema writes.
+export async function discoverProjectStores(cwd, env = process.env) {
+  const root = findCliProjectRoot(cwd);
+  const config = fs.existsSync(path.join(root, CONFIG_PATH)) ? readConfig(root) : null;
+  const candidates = [
+    { id: 'runtime:sqlite', driver: 'sqlite', role: 'runtime', path: runtimeDatabasePath(root), selected: true },
+    { id: 'knowledge:sqlite', driver: 'sqlite', role: 'knowledge', path: path.join(root, '.agentsam/knowledge/index.sqlite'), selected: !config || config.storage.driver === 'sqlite', selectable: true },
+  ];
+  const envNames = new Set(['AGENTSAM_DATABASE_URL', 'DATABASE_URL', 'POSTGRES_URL', config?.storage?.connection_env].filter(Boolean));
+  for (const name of envNames) {
+    if (!Object.hasOwn(env, name) && name !== config?.storage?.connection_env) continue;
+    candidates.push({ id: `knowledge:postgres:${name}`, driver: 'postgres', role: 'knowledge', connection_env: name, configured: Boolean(env[name]), selected: config?.storage?.driver === 'postgres' && config.storage.connection_env === name, selectable: true });
+  }
+  const warnings = [];
+  let visited = 0;
+  const skip = new Set(['node_modules', '.git', '.agentsam', '.output', 'dist', 'build', 'vendor', '.wrangler']);
+  const configs = [];
+  function scan(dir, depth) {
+    if (depth > 5 || visited >= 4000) return;
+    for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+      if (++visited >= 4000) break;
+      if (entry.isSymbolicLink() || skip.has(entry.name)) continue;
+      const file = path.join(dir, entry.name);
+      if (entry.isDirectory()) scan(file, depth + 1);
+      else if (['wrangler.json', 'wrangler.jsonc'].includes(entry.name)) configs.push(file);
+      else if (entry.name === 'wrangler.toml') warnings.push(`${path.relative(root, file)}: TOML discovery is not implemented; inspect this configuration explicitly.`);
+    }
+  }
+  scan(root, 0);
+  if (visited >= 4000) warnings.push('Discovery reached its 4000-entry bound; inspect additional config paths explicitly.');
+  if (configs.length) {
+    const { parseConfigFileTextToJson } = await import('typescript');
+    for (const file of configs) {
+      const source = path.relative(root, file);
+      if (fs.statSync(file).size > 1024 * 1024) { warnings.push(`${source}: configuration too large`); continue; }
+      const parsed = parseConfigFileTextToJson(file, fs.readFileSync(file, 'utf8'));
+      if (parsed.error) { warnings.push(`${source}: invalid JSONC`); continue; }
+      const add = (cfg, environment = null) => {
+        for (const [key, driver, label] of [['d1_databases', 'd1', 'database_name'], ['hyperdrive', 'postgres-hyperdrive', 'id'], ['r2_buckets', 'r2', 'bucket_name']]) {
+          for (const binding of Array.isArray(cfg?.[key]) ? cfg[key] : []) {
+            candidates.push({ id: `${source}:${environment || 'default'}:${binding.binding}`, driver, role: 'application', binding: binding.binding, name: binding[label], source, environment, selectable: false, status: 'declared; connectivity not verified' });
+          }
+        }
+      };
+      add(parsed.config);
+      for (const [environment, cfg] of Object.entries(parsed.config?.env || {})) add(cfg, environment);
+    }
+  }
+  return { root, candidates, warnings, knowledge_config: CONFIG_PATH };
+}
+
+export function selectKnowledgeStore(cwd, driver, connectionEnv) {
+  const root = findCliProjectRoot(cwd);
+  if (!['sqlite', 'postgres'].includes(driver)) throw new Error('knowledge_store_adapter_unavailable: choose sqlite or postgres; D1 application bindings retain their existing authority');
+  const filename = path.join(root, CONFIG_PATH);
+  let config;
+  if (fs.existsSync(filename)) config = readConfig(root);
+  else {
+    const repositoryId = getRepositoryId(tryReadProjectConfig(root)) || portableRepositoryIdFromGit(root);
+    if (!repositoryId) throw new Error('repository_identity_required: run agentsam init . --yes first');
+    config = defaultConfig({ repositoryId });
+  }
+  config.storage = driver === 'sqlite' ? { driver } : { driver, connection_env: connectionEnv || 'AGENTSAM_DATABASE_URL' };
+  config = validateConfig(config);
+  fs.mkdirSync(path.dirname(filename), { recursive: true, mode: 0o700 });
+  const temp = `${filename}.${process.pid}.tmp`;
+  fs.writeFileSync(temp, JSON.stringify(config, null, 2) + '\n', { mode: 0o600 });
+  fs.renameSync(temp, filename);
+  return { storage: config.storage, config: CONFIG_PATH, next: driver === 'sqlite' ? 'agentsam index run' : 'agentsam index setup-store', note: 'Selection saved. Existing data remains in its original store; no migration or connection probe ran.' };
+}

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,65 @@ 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) return apiKey;
+  if (clean(options.explicit) && apiKey.error) return apiKey;
+  const browser = resolveBrowserSessionCredential(options);
+  if (browser.value) {
+    return apiKey.error ? { ...browser, fallback_error: apiKey.error } : browser;
+  }
+  if (browser.error) return browser;
+  return apiKey.error ? apiKey : browser;
 }
 
 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/agent-instructions.js

@@ -6,6 +6,9 @@ import { findProjectRules } from './project-rules.js';
 export const AGENT_RUNTIME_FILENAME = 'AGENTSAM.md';
 export const AGENT_INSTRUCTION_PRECEDENCE = Object.freeze(['AGENTSAM.md', '.agentsamrules']);
 
+/** Provider/editor adapters that must redirect to AGENTSAM.md — never compiled as policy. */
+export const AGENT_INSTRUCTION_COMPAT_SHIMS = Object.freeze(['AGENTS.md', 'CLAUDE.md']);
+
 function sha256(value) {
   return `sha256:${createHash('sha256').update(value).digest('hex')}`;
 }