@inneranimalmedia/agentsam-sdk 2.6.2 → 2.6.4

package/src/lib/dockerize.js

@@ -98,6 +98,7 @@ function generateViteReact(opts) {
 FROM node:20-alpine AS build
 WORKDIR /app
 COPY package*.json ./
+RUN apk add --no-cache python3 make g++
 RUN if [ -f package-lock.json ]; then npm ci; else npm install; fi
 COPY . .
 RUN ${buildCmd}
@@ -125,6 +126,7 @@ function generateNodeService(opts) {
 FROM node:20-alpine
 WORKDIR /app
 COPY package*.json ./
+RUN apk add --no-cache python3 make g++
 RUN if [ -f package-lock.json ]; then npm ci --omit=dev; else npm install --omit=dev; fi
 COPY . .
 ENV PORT=${port}
@@ -152,6 +154,7 @@ function generateWranglerDev(opts) {
 FROM node:20-alpine
 WORKDIR /app
 COPY package*.json ./
+RUN apk add --no-cache python3 make g++
 RUN if [ -f package-lock.json ]; then npm ci; else npm install; fi
 COPY . .
 EXPOSE ${port}

package/src/lib/execution-approvals.js

@@ -33,6 +33,7 @@ export function toolApprovalKey(capabilityId, input = {}) {
   const id = clean(capabilityId);
   const command = clean(input?.command);
   if (id === 'cloudflare.wrangler.native' && /^[A-Za-z0-9._-]+$/.test(command)) return `${id}:${command}`;
+  if (id === 'terminal.exec' && /^[A-Za-z0-9._+-]+$/.test(command)) return `${id}:${command}`;
   return id;
 }
 

package/src/lib/identity-scaffold.js

@@ -9,7 +9,7 @@ const MIGRATION_FILE = path.join(IDENTITY_PKG, 'src', 'migrations', '0001_identi
 const BRANDING_SCRIPT = path.join(IDENTITY_PKG, 'src', 'frontend', 'auth-portal', 'shared', 'company-branding.js');
 
 /**
- * @param {{ projectName: string, brandName?: string, logoUrl?: string, sdkVersion?: string }} config
+ * @param {{ projectName: string, brandName?: string, logoUrl?: string, sdkVersion?: string, provider?: string }} config
  * @returns {Record<string, string>}
  */
 export function buildIdentityAppScaffold(config) {
@@ -17,6 +17,7 @@ export function buildIdentityAppScaffold(config) {
   const brandName = config.brandName || projectName;
   const logoUrl = config.logoUrl || '/brand/logo.svg';
   const sdkVersion = config.sdkVersion || 'alpha';
+  const provider = config.provider || 'inneranimalmedia';
 
   const migrationSql = `${fs.readFileSync(MIGRATION_FILE, 'utf8')}\n${buildCompanySeedSql({ brandName, logoUrl })}\n`;
   const loginHtml = injectBrandingScript(applyBrandTokens(fs.readFileSync(path.join(AUTH_PAGES_DIR, 'login.html'), 'utf8'), {
@@ -95,6 +96,8 @@ migrations_dir = "migrations"
 
 Boring scaffold: **app/frontend** (auth UI) + **backend** (Worker API) + **migrations** (D1).
 
+Provider template: \`${provider}\` (see \`agentsam identity plan --provider ${provider}\`).
+
 ## Quick start
 
 \`\`\`bash

package/src/lib/knowledge-docker.js

@@ -7,7 +7,13 @@ import { CONFIG_PATH, defaultConfig, readConfig } from '../knowledge/config.js';
 
 const sdkRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '../..');
 const runtimeFiles = () => {
-  const files = ['services/knowledge/package.json', 'services/knowledge/package-lock.json', 'packages/agentsam-repository/src/merkle/hash.js', 'src/errors/contract.js'];
+  const files = [
+    'services/knowledge/package.json',
+    'services/knowledge/package-lock.json',
+    'packages/agentsam-repository/src/merkle/hash.js',
+    'packages/agentsam-errors/package.json',
+    'src/errors/contract.js',
+  ];
   const walk = dir => { for (const entry of fs.readdirSync(path.join(sdkRoot, dir), { withFileTypes: true })) {
     const file = `${dir}/${entry.name}`;
     if (entry.isDirectory()) walk(file);
@@ -15,6 +21,7 @@ const runtimeFiles = () => {
   } };
   walk('src/knowledge');
   walk('src/rpc/generated');
+  walk('packages/agentsam-errors/src');
   return files.sort();
 };
 
@@ -31,6 +38,7 @@ WORKDIR /app
 COPY package.json package-lock.json ./
 RUN npm ci --omit=dev --ignore-scripts --no-audit --no-fund
 COPY src ./src
+COPY packages ./packages
 ENV NODE_ENV=production PORT=${port} GIT_OPTIONAL_LOCKS=0
 EXPOSE ${port}
 HEALTHCHECK --interval=15s --timeout=3s --start-period=10s --retries=3 CMD node -e "fetch('http://127.0.0.1:'+process.env.PORT+'/healthz').then(r=>process.exit(r.ok?0:1)).catch(()=>process.exit(1))"

package/src/lib/local-sessions.js

@@ -2,6 +2,10 @@ import fs from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
 import { randomUUID } from 'node:crypto';
+import { findCliProjectRoot } from './cli-preferences.js';
+import { runtimeDatabasePath, SQLITE_RUNTIME_CAPABILITIES } from '../local/runtime-store.js';
+import { createLocalSqliteDatabaseSync } from '../local/sqlite.js';
+import { applyRuntimeMigrationsSync } from '../local/migrations.js';
 
 export const LOCAL_SESSION_SCHEMA = 'agentsam-local-session-v1';
 
@@ -33,13 +37,51 @@ function filenameFor(sessionId, options = {}) {
   return path.join(localSessionDirectory(options), `${validateSessionId(sessionId)}.json`);
 }
 
-function ensureDirectory(options = {}) {
-  const dir = localSessionDirectory(options);
-  fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
-  if (process.platform !== 'win32') {
-    try { fs.chmodSync(dir, 0o700); } catch { /* best effort */ }
+function projectRoot(value = {}, options = {}) {
+  return findCliProjectRoot(options.projectRoot || value.project_root || value.cwd || options.cwd || process.cwd());
+}
+
+function withSessionDb(root, fn) {
+  const db = createLocalSqliteDatabaseSync(runtimeDatabasePath(root));
+  try {
+    applyRuntimeMigrationsSync(db);
+    return fn(db);
+  } finally {
+    db.close();
   }
-  return dir;
+}
+
+function safeProviderState(value) {
+  if (!value || typeof value !== 'object') return {};
+  // Opaque response IDs allow provider-side continuation. Message arrays and
+  // compaction input can carry prompts, tool output, or credential values.
+  return {
+    ...(clean(value.provider) ? { provider: clean(value.provider) } : {}),
+    ...(clean(value.previous_response_id) ? { previous_response_id: clean(value.previous_response_id) } : {}),
+    ...(value.has_compacted_input === true ? { has_compacted_input: true } : {}),
+  };
+}
+
+function safeLastError(value) {
+  if (!value || typeof value !== 'object') return null;
+  return {
+    code: clean(value.code) || null,
+    kind: clean(value.kind) || null,
+    source: clean(value.source) || null,
+  };
+}
+
+function safeUsageSnapshot(value) {
+  if (!value || typeof value !== 'object') return null;
+  const inputTokens = Number(value.current_context?.input_tokens);
+  const windowTokens = Number(value.current_context?.window_tokens);
+  return {
+    estimate_kind: value.estimate_kind === 'provider' ? 'provider' : 'local',
+    current_context: {
+      input_tokens: Number.isFinite(inputTokens) ? Math.max(0, inputTokens) : 0,
+      window_tokens: Number.isFinite(windowTokens) ? Math.max(0, windowTokens) : null,
+    },
+  };
 }
 
 function normalizeUsage(value = {}) {
@@ -72,13 +114,18 @@ export function normalizeLocalSession(value = {}) {
   const createdAt = clean(value.created_at) || now();
   const status = clean(value.status) || 'active';
   const updatedAt = clean(value.updated_at) || createdAt;
+  const root = projectRoot(value);
+  const dbPath = runtimeDatabasePath(root);
+  const relativeDbPath = path.relative(root, dbPath);
   return {
     schema_version: LOCAL_SESSION_SCHEMA,
     id: validateSessionId(value.id || createLocalSessionId()),
     status,
+    project_root: root,
+    storage: { runtime: 'sqlite', path: relativeDbPath.startsWith('..') ? dbPath : relativeDbPath, remote: null, capabilities: SQLITE_RUNTIME_CAPABILITIES },
     cwd: path.resolve(clean(value.cwd) || process.cwd()),
-    title: clean(value.title) || sessionTitleFromInput(value.last_input),
-    last_input: clean(value.last_input) || null,
+    title: clean(value.title) || 'Agent Sam session',
+    last_input: null,
     created_at: createdAt,
     updated_at: updatedAt,
     active_elapsed_ms: Math.max(0, Number(value.active_elapsed_ms || 0)),
@@ -88,26 +135,49 @@ export function normalizeLocalSession(value = {}) {
     reasoning_effort: clean(value.reasoning_effort) || null,
     requested_service_tier: clean(value.requested_service_tier) || null,
     actual_service_tier: clean(value.actual_service_tier) || null,
-    provider_state: value.provider_state && typeof value.provider_state === 'object' ? { ...value.provider_state } : {},
-    usage_snapshot: value.usage_snapshot && typeof value.usage_snapshot === 'object' ? structuredClone(value.usage_snapshot) : null,
+    provider_state: safeProviderState(value.provider_state),
+    latest_compaction: value.latest_compaction ? {
+      compaction_id: clean(value.latest_compaction.compaction_id) || null,
+      provider: clean(value.latest_compaction.provider) || null,
+      model: clean(value.latest_compaction.model) || null,
+      created_at: clean(value.latest_compaction.created_at) || null,
+      usage: normalizeUsage(value.latest_compaction.usage),
+      cost_usd: Number(value.latest_compaction.cost_usd || 0),
+    } : null,
+    auto_compact: value.auto_compact !== false,
+    usage_snapshot: safeUsageSnapshot(value.usage_snapshot),
     cumulative_usage: normalizeUsage(value.cumulative_usage || {}),
     total_cost_usd: Number(value.total_cost_usd || 0),
     cost_breakdown_usd: normalizeCostBreakdown(value.cost_breakdown_usd || {}),
     approved_projected_call_cost_usd: Number(value.approved_projected_call_cost_usd || 0),
-    last_error: value.last_error && typeof value.last_error === 'object' ? structuredClone(value.last_error) : null,
+    last_error: safeLastError(value.last_error),
   };
 }
 
 export function saveLocalSession(session, options = {}) {
-  const normalized = normalizeLocalSession({ ...session, updated_at: now() });
-  ensureDirectory(options);
-  const filename = filenameFor(normalized.id, options);
-  const temp = `${filename}.${process.pid}.tmp`;
-  fs.writeFileSync(temp, `${JSON.stringify(normalized, null, 2)}\n`, { mode: 0o600 });
-  if (process.platform !== 'win32') {
-    try { fs.chmodSync(temp, 0o600); } catch { /* best effort */ }
-  }
-  fs.renameSync(temp, filename);
+  const normalized = normalizeLocalSession({ ...session, project_root: projectRoot(session, options), updated_at: now() });
+  const compactedInput = session.provider_state?.compacted_input;
+  const serialized = Array.isArray(compactedInput) ? JSON.stringify(compactedInput) : null;
+  if (serialized && Buffer.byteLength(serialized) > 10 * 1024 * 1024) throw new Error('provider_continuation_too_large');
+  if (serialized) normalized.provider_state.has_compacted_input = true;
+  withSessionDb(normalized.project_root, (db) => {
+    db.exec('BEGIN IMMEDIATE');
+    try {
+      db.prepare(`
+        INSERT INTO agentsam_project_sessions (id, project_root, cwd, status, title, state_json, created_at, updated_at)
+        VALUES (?, ?, ?, ?, ?, ?, ?, ?)
+        ON CONFLICT(id) DO UPDATE SET
+          cwd = excluded.cwd, status = excluded.status, title = excluded.title,
+          state_json = excluded.state_json, updated_at = excluded.updated_at
+      `).run(normalized.id, normalized.project_root, normalized.cwd, normalized.status,
+        normalized.title, JSON.stringify(normalized), normalized.created_at, normalized.updated_at);
+      if (serialized) db.prepare(`INSERT INTO agentsam_provider_continuations (session_id, provider, output_json, updated_at)
+        VALUES (?, ?, ?, ?) ON CONFLICT(session_id) DO UPDATE SET provider=excluded.provider, output_json=excluded.output_json, updated_at=excluded.updated_at`
+      ).run(normalized.id, normalized.provider_state.provider || '', serialized, normalized.updated_at);
+      else if (!normalized.provider_state.has_compacted_input) db.prepare('DELETE FROM agentsam_provider_continuations WHERE session_id = ?').run(normalized.id);
+      db.exec('COMMIT');
+    } catch (error) { db.exec('ROLLBACK'); throw error; }
+  });
   return normalized;
 }
 
@@ -116,11 +186,23 @@ export function createLocalSession(value = {}, options = {}) {
 }
 
 export function loadLocalSession(sessionId, options = {}) {
+  const root = projectRoot({}, options);
+  const dbPath = runtimeDatabasePath(root);
+  if (fs.existsSync(dbPath)) {
+    const row = withSessionDb(root, (db) => db.prepare(
+      'SELECT state_json FROM agentsam_project_sessions WHERE id = ? AND project_root = ?'
+    ).get(validateSessionId(sessionId), root));
+    if (row) return normalizeLocalSession(JSON.parse(row.state_json));
+  }
+  // Read-only compatibility with older ~/.agentsam/sessions/*.json state.
+  // Import only when the saved cwd belongs to the selected project; never
+  // create new home-level session files or resume a different project's row.
   const filename = filenameFor(sessionId, options);
   if (!fs.existsSync(filename)) return null;
   const parsed = JSON.parse(fs.readFileSync(filename, 'utf8'));
   if (parsed?.schema_version !== LOCAL_SESSION_SCHEMA) throw new Error(`unsupported_local_session_schema:${parsed?.schema_version || 'missing'}`);
-  return normalizeLocalSession(parsed);
+  if (projectRoot(parsed) !== root) return null;
+  return saveLocalSession(parsed, { projectRoot: root });
 }
 
 export function updateLocalSession(sessionId, patch = {}, options = {}) {
@@ -130,19 +212,27 @@ export function updateLocalSession(sessionId, patch = {}, options = {}) {
 }
 
 export function listLocalSessions(options = {}) {
+  const root = projectRoot({}, options);
   const dir = localSessionDirectory(options);
-  if (!fs.existsSync(dir)) return [];
-  const cwd = clean(options.cwd) ? path.resolve(options.cwd) : '';
-  const limit = Number.isInteger(options.limit) && options.limit > 0 ? Math.min(options.limit, 100) : 20;
-  const rows = [];
-  for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
-    if (!entry.isFile() || !entry.name.startsWith('asess_') || !entry.name.endsWith('.json')) continue;
-    try {
-      const parsed = JSON.parse(fs.readFileSync(path.join(dir, entry.name), 'utf8'));
-      if (parsed?.schema_version !== LOCAL_SESSION_SCHEMA) continue;
-      const session = normalizeLocalSession(parsed);
-      if (!cwd || session.cwd === cwd) rows.push(session);
-    } catch { /* skip corrupt session file */ }
+  if (fs.existsSync(dir)) {
+    for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+      if (!entry.isFile() || !entry.name.startsWith('asess_') || !entry.name.endsWith('.json')) continue;
+      try { loadLocalSession(entry.name.slice(0, -5), { ...options, projectRoot: root }); }
+      catch { /* legacy corrupt files remain untouched */ }
+    }
   }
-  return rows.sort((a, b) => String(b.updated_at).localeCompare(String(a.updated_at))).slice(0, limit);
+  if (!fs.existsSync(runtimeDatabasePath(root))) return [];
+  const limit = Number.isInteger(options.limit) && options.limit > 0 ? Math.min(options.limit, 100) : 20;
+  return withSessionDb(root, (db) => db.prepare(
+    'SELECT state_json FROM agentsam_project_sessions WHERE project_root = ? ORDER BY updated_at DESC LIMIT ?'
+  ).all(root, limit).map((row) => normalizeLocalSession(JSON.parse(row.state_json))));
+}
+
+export function loadSessionContinuation(session) {
+  if (!session?.provider_state?.has_compacted_input) return session?.provider_state || null;
+  return withSessionDb(projectRoot(session), db => {
+    const row = db.prepare('SELECT provider, output_json FROM agentsam_provider_continuations WHERE session_id = ?').get(validateSessionId(session.id));
+    if (!row || row.provider !== session.provider_state.provider) throw new Error('provider_continuation_missing');
+    return { ...session.provider_state, compacted_input: JSON.parse(row.output_json) };
+  });
 }

package/src/lib/local-status.js

@@ -1,29 +1,37 @@
-import fs from 'node:fs';
 import path from 'node:path';
 import { tryResolveGitContext } from '../../packages/agentsam-repository/src/git-context.js';
 import { inspectLocalSqlite } from '../local/sqlite.js';
-import { getCreatedWithVersion, getDefaultProfile, getDeployTarget, getLocalDatabasePath, getProjectName, getProjectPreset, getRepositoryId, tryReadProjectConfig } from './project-config.js';
+import {
+  getCreatedWithVersion,
+  getDefaultProfile,
+  getDeployTarget,
+  getLocalDatabasePath,
+  getProjectName,
+  getProjectPreset,
+  getRepositoryId,
+  tryReadProjectConfig,
+} from './project-config.js';
+import { findCliProjectRoot } from './cli-preferences.js';
 
 export function findAgentSamProjectRoot(startDir = process.cwd()) {
-  let dir = path.resolve(startDir);
-  for (let i = 0; i < 16; i += 1) {
-    if (fs.existsSync(path.join(dir, '.agentsam', 'config.json'))) return dir;
-    const parent = path.dirname(dir);
-    if (parent === dir) break;
-    dir = parent;
-  }
-  return path.resolve(startDir);
+  return findCliProjectRoot(startDir);
 }
 
 async function probe(url) {
   try {
-    const response = await fetch(url, { signal: AbortSignal.timeout(500) });
+    const response = await fetch(url, { signal: AbortSignal.timeout(1500) });
     return { online: response.ok, status: response.status, url };
   } catch {
     return { online: false, status: null, url };
   }
 }
 
+function resolveLiveHealthUrl(config) {
+  const fromDeploy = config?.deployment?.cloudflare?.health_url;
+  if (fromDeploy != null && String(fromDeploy).trim()) return String(fromDeploy).trim();
+  return null;
+}
+
 export async function collectLocalStatus(cwd = process.cwd()) {
   const root = findAgentSamProjectRoot(cwd);
   const config = tryReadProjectConfig(root);
@@ -36,10 +44,16 @@ export async function collectLocalStatus(cwd = process.cwd()) {
 
   const devPort = config?.dev_port ?? 8787;
   const ptyPort = config?.pty_port ?? 3099;
-  const [api, pty] = await Promise.all([
+  const liveUrl = resolveLiveHealthUrl(config);
+  const probes = [
     probe(`http://127.0.0.1:${devPort}/api/health`),
     probe(`http://127.0.0.1:${ptyPort}/health`),
-  ]);
+  ];
+  if (liveUrl) probes.push(probe(liveUrl));
+  const results = await Promise.all(probes);
+  const api = results[0];
+  const pty = results[1];
+  const live = liveUrl ? results[2] : null;
 
   return {
     schemaVersion: 'agentsam-local-status-v1',
@@ -60,12 +74,19 @@ export async function collectLocalStatus(cwd = process.cwd()) {
         }
       : null,
     db: {
-      ready: Boolean(db.exists),
+      ready: Boolean(
+        db.exists &&
+          db.tables?.includes('agentsam_schema_migrations') &&
+          db.tables?.includes('agentsam_project_sessions'),
+      ),
       path: db.dbPath || path.join(root, '.agentsam/data/agentsam.sqlite'),
       tables: db.tables || [],
       sizeBytes: db.sizeBytes || 0,
     },
     api,
     pty,
+    live: liveUrl
+      ? live || { online: false, status: null, url: liveUrl }
+      : { online: false, status: null, url: null },
   };
 }

package/src/lib/project-config.js

@@ -76,6 +76,9 @@ export function createProjectManifest({
     knowledge: {
       config: '.agentsam/knowledge.json',
     },
+    // Project-owned plugin/resource declarations. Bindings, indexes, models,
+    // and dimensions belong here rather than in a global SDK default.
+    plugins: {},
     local: {
       database: '.agentsam/data/agentsam.sqlite',
       schema: 'db/schema.sql',
@@ -151,6 +154,12 @@ export function getKnowledgeConfigPath(config) {
   return clean(config?.knowledge?.config) || '.agentsam/knowledge.json';
 }
 
+export function getProjectPluginConfig(config, pluginKey) {
+  const key = clean(pluginKey).replace(/^@/, '');
+  const plugins = config?.plugins || config?.integrations || {};
+  return plugins[key] || plugins[`@${key}`] || null;
+}
+
 export function getLocalDatabasePath(config) {
   return clean(config?.local?.database || config?.db_path) || '.agentsam/data/agentsam.sqlite';
 }

package/src/lib/provider-credentials.js

@@ -1,6 +1,14 @@
 import fs from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
+import {
+  getSecureProviderKey,
+  setSecureProviderKey,
+  deleteSecureProviderKey,
+  hydrateSecureCredentials,
+} from '../security/local-vault.js';
+
+export { hydrateSecureCredentials };
 
 export const PROVIDER_CREDENTIALS = Object.freeze({
   openai: Object.freeze({ label: 'OpenAI', env: 'OPENAI_API_KEY', files: ['openai.env'], modelProvider: 'openai' }),
@@ -13,7 +21,7 @@ export const PROVIDER_CREDENTIALS = Object.freeze({
     env: 'CLOUDFLARE_API_TOKEN',
     files: ['cloudflare.env'],
     modelProvider: 'cloudflare',
-    accountEnv: ['ACCOUNT_ID', 'CLOUDFLARE_ACCOUNT_ID'],
+    accountEnv: ['CLOUDFLARE_ACCOUNT_ID'],
   }),
   inneranimalmedia: Object.freeze({
     label: 'InnerAnimalMedia',
@@ -121,32 +129,17 @@ export function agentEnvLoaderPath(options = {}) {
 
 export function ensureAgentEnvLoader(options = {}) {
   const filename = agentEnvLoaderPath(options);
-  const supported = Object.keys(PROVIDER_CREDENTIALS).join('|');
-  const source = `# AgentSam provider environment loader. Source this file; do not execute it.
-if [ "$#" -eq 0 ]; then
-  echo "usage: source ~/.agentsam/load-agent-env.sh <profile> [profile ...]" >&2
-  return 2 2>/dev/null || exit 2
+  const source = `# AgentSam environment loader. Source this file; do not execute it.
+# Credentials resolve from the OS keychain / local vault via \`agentsam env shell\`.
+# Do not put plaintext secrets in this file.
+if command -v agentsam >/dev/null 2>&1; then
+  eval "$(agentsam env shell --profile default)"
+elif command -v agentsam-env >/dev/null 2>&1; then
+  eval "$(agentsam-env shell --profile default)"
+else
+  echo "agentsam CLI not found on PATH; cannot load AgentSam credentials" >&2
+  return 1 2>/dev/null || exit 1
 fi
-for _agentsam_profile in "$@"; do
-  case "$_agentsam_profile" in
-    grok) _agentsam_profile="xai" ;;
-    ${supported}) ;;
-    *) echo "unknown AgentSam provider profile: $_agentsam_profile" >&2; return 2 2>/dev/null || exit 2 ;;
-  esac
-  _agentsam_file="\${HOME}/.agentsam/env.d/\${_agentsam_profile}.env"
-  if [ ! -f "$_agentsam_file" ]; then
-    echo "AgentSam provider profile not found: $_agentsam_file" >&2
-    return 1 2>/dev/null || exit 1
-  fi
-  set -a
-  . "$_agentsam_file"
-  set +a
-  if [ "$_agentsam_profile" = cloudflare ]; then
-    if [ -z "\${ACCOUNT_ID:-}" ] && [ -n "\${CLOUDFLARE_ACCOUNT_ID:-}" ]; then export ACCOUNT_ID="$CLOUDFLARE_ACCOUNT_ID"; fi
-    if [ -z "\${CLOUDFLARE_ACCOUNT_ID:-}" ] && [ -n "\${ACCOUNT_ID:-}" ]; then export CLOUDFLARE_ACCOUNT_ID="$ACCOUNT_ID"; fi
-  fi
-done
-unset _agentsam_file _agentsam_profile
 `;
   atomicWrite(filename, source, 0o700);
   return filename;
@@ -157,8 +150,8 @@ function profileSource(provider, credential = '', options = {}) {
   if (!spec) throw new Error(`unsupported_provider:${normalizeProviderId(provider)}`);
   const lines = [`# AgentSam ${spec.label} provider profile`];
   if (spec.provider === 'cloudflare') {
-    lines.push('# ACCOUNT_ID is your Cloudflare account identifier; it is not a secret.');
-    lines.push(`export ACCOUNT_ID=${envLiteral(normalizeCloudflareAccountId(options.accountId))}`);
+    lines.push('# CLOUDFLARE_ACCOUNT_ID is your Cloudflare account identifier; it is not a secret.');
+    lines.push(`export CLOUDFLARE_ACCOUNT_ID=${envLiteral(normalizeCloudflareAccountId(options.accountId))}`);
   }
   lines.push(`export ${spec.env}=${envLiteral(credential)}`);
   return `${lines.join('\n')}\n`;
@@ -190,9 +183,9 @@ export function ensureProviderEnvProfile(provider, options = {}) {
       const current = firstEnvValue(source, spec.accountEnv || []);
       if (!current) {
         const accountId = normalizeCloudflareAccountId(options.accountId);
-        const line = `export ACCOUNT_ID=${envLiteral(accountId)}`;
-        const next = /^(?:export\s+)?ACCOUNT_ID=.*$/m.test(source)
-          ? source.replace(/^(?:export\s+)?ACCOUNT_ID=.*$/m, line)
+        const line = `export CLOUDFLARE_ACCOUNT_ID=${envLiteral(accountId)}`;
+        const next = /^(?:export\s+)?CLOUDFLARE_ACCOUNT_ID=.*$/m.test(source)
+          ? source.replace(/^(?:export\s+)?CLOUDFLARE_ACCOUNT_ID=.*$/m, line)
           : `${line}\n${source}`;
         atomicWrite(filename, next, 0o600);
       }
@@ -212,8 +205,46 @@ export function setProviderCredential(provider, credential, options = {}) {
   const spec = providerCredentialSpec(provider);
   if (!spec) throw new Error(`unsupported_provider:${normalizeProviderId(provider)}`);
   const value = validateCredentialValue(spec, credential);
+  setSecureProviderKey(spec.provider, { value, accountId: options.accountId }, options);
+  if (typeof process !== 'undefined' && process.env) {
+    process.env[spec.env] = value;
+    if (spec.provider === 'cloudflare' && options.accountId) {
+      process.env.CLOUDFLARE_ACCOUNT_ID = options.accountId;
+    }
+  }
+  let file = null;
+  let loader = null;
+  let sourceCommand = null;
+  if (options.exportProfile === true || options.writeEnvProfile === true) {
+    const filename = path.join(agentEnvDirectory(options), spec.files[0]);
+    atomicWrite(filename, profileSource(spec.provider, value, options), 0o600);
+    loader = ensureAgentEnvLoader(options);
+    file = filename;
+    sourceCommand = `source ~/.agentsam/load-agent-env.sh ${spec.provider}`;
+  }
+  return Object.freeze({
+    provider: spec.provider,
+    file,
+    loader,
+    source_command: sourceCommand,
+  });
+}
+
+/**
+ * Exports a configured provider credential from the secure vault to a plaintext .env file.
+ * This is an explicit opt-in action for operators who need to source credentials into external shells.
+ * The standard AgentSam setup flows (interactive picker, models --setup, providers add)
+ * intentionally do NOT invoke this, keeping the credential strictly inside the encrypted vault.
+ */
+export function exportProviderEnvProfile(provider, options = {}) {
+  const spec = providerCredentialSpec(provider);
+  if (!spec) throw new Error(`unsupported_provider:${normalizeProviderId(provider)}`);
+  const resolved = resolveProviderCredential(spec.provider, options);
+  if (!resolved.configured || !resolved.value) {
+    throw new Error(`provider_not_configured:${spec.provider}`);
+  }
   const filename = path.join(agentEnvDirectory(options), spec.files[0]);
-  atomicWrite(filename, profileSource(spec.provider, value, options), 0o600);
+  atomicWrite(filename, profileSource(spec.provider, resolved.value, { ...options, accountId: resolved.account_id }), 0o600);
   const loader = ensureAgentEnvLoader(options);
   return Object.freeze({
     provider: spec.provider,
@@ -226,6 +257,7 @@ export function setProviderCredential(provider, credential, options = {}) {
 export function removeProviderCredential(provider, options = {}) {
   const spec = providerCredentialSpec(provider);
   if (!spec) throw new Error(`unsupported_provider:${normalizeProviderId(provider)}`);
+  deleteSecureProviderKey(spec.provider, options);
   const dir = agentEnvDirectory(options);
   let removed = false;
   for (const basename of spec.files) {
@@ -236,6 +268,9 @@ export function removeProviderCredential(provider, options = {}) {
     fs.rmSync(filename, { force: true });
     removed = true;
   }
+  if (typeof process !== 'undefined' && process.env) {
+    delete process.env[spec.env];
+  }
   return Object.freeze({ provider: spec.provider, removed });
 }
 
@@ -259,6 +294,22 @@ export function resolveProviderCredential(provider, options = {}) {
     });
   }
 
+  const secure = getSecureProviderKey(spec.provider, options);
+  if (secure && clean(secure.value)) {
+    const val = clean(secure.value);
+    const prefixError = spec.tokenPrefix && !val.startsWith(spec.tokenPrefix) ? `credential_prefix_required:${spec.tokenPrefix}` : null;
+    return Object.freeze({
+      provider: spec.provider,
+      configured: !prefixError,
+      source: secure.source || 'local_vault',
+      env: spec.env,
+      file: null,
+      error: prefixError,
+      value: prefixError ? '' : val,
+      account_id: accountIdFromEnv || secure.accountId || null,
+    });
+  }
+
   const dir = agentEnvDirectory({ ...options, env });
   for (const basename of spec.files) {
     const filename = path.join(dir, basename);
@@ -297,3 +348,56 @@ export function describeProviderCredential(provider, options = {}) {
 export function listProviderCredentialStatus(options = {}) {
   return Object.freeze(Object.keys(PROVIDER_CREDENTIALS).map((provider) => describeProviderCredential(provider, options)));
 }
+
+/**
+ * Emit shell `export` lines for configured credentials from vault/keychain/env.
+ * Bootstrap-safe: does not require AGENTSAM_API_KEY already present to resolve it.
+ * Prefer vault/OS store over ambient env when `preferVault` is true (default for shell).
+ */
+export function renderEnvShellExports(options = {}) {
+  const profile = clean(options.profile || 'default').toLowerCase();
+  const wanted = Array.isArray(options.providers) && options.providers.length
+    ? options.providers.map(normalizeProviderId).filter(Boolean)
+    : profile === 'default'
+      ? Object.keys(PROVIDER_CREDENTIALS)
+      : profile.split(/[,\s]+/).map(normalizeProviderId).filter(Boolean);
+
+  const lines = ['# AgentSam env shell — evaluated by: eval "$(agentsam env shell)"'];
+  const emitted = [];
+
+  for (const provider of wanted) {
+    const spec = providerCredentialSpec(provider);
+    if (!spec) continue;
+
+    let resolved;
+    if (options.preferVault !== false) {
+      // Skip ambient process.env so a stale empty shell does not block keychain.
+      const vaultOnly = { ...options, env: { ...(options.env || {}), [spec.env]: undefined } };
+      if (spec.accountEnv) {
+        for (const name of spec.accountEnv) vaultOnly.env[name] = undefined;
+      }
+      resolved = resolveProviderCredential(spec.provider, vaultOnly);
+      if (!resolved.configured) {
+        resolved = resolveProviderCredential(spec.provider, options);
+      }
+    } else {
+      resolved = resolveProviderCredential(spec.provider, options);
+    }
+
+    if (!resolved.configured || !resolved.value) continue;
+    lines.push(`export ${spec.env}=${envLiteral(resolved.value)}`);
+    if (spec.provider === 'cloudflare' && resolved.account_id) {
+      lines.push(`export CLOUDFLARE_ACCOUNT_ID=${envLiteral(resolved.account_id)}`);
+    }
+    emitted.push(spec.provider);
+  }
+
+  if (!emitted.length) {
+    lines.push('# No AgentSam credentials configured. Run: agentsam api-key create --store keychain --activate');
+  }
+  return Object.freeze({
+    profile,
+    providers: emitted,
+    script: `${lines.join('\n')}\n`,
+  });
+}