@inneranimalmedia/agentsam-sdk 2.6.0 → 2.6.1

package/src/agent/responses-runner.js

@@ -23,9 +23,11 @@ function userMessage(text) {
 }
 
 function modelBudget(record) {
+  const windowTokens = Number(record?.context_window);
+  if (!Number.isFinite(windowTokens) || windowTokens <= 0) return null;
   const policy = record.context_policy || {};
   return createContextBudget({
-    windowTokens: record.context_window,
+    windowTokens,
     targetInputTokens: policy.target_input_tokens,
     compactAtTokens: policy.compact_at_tokens,
     interveneAtTokens: policy.intervene_at_tokens,
@@ -102,6 +104,7 @@ function boundedToolOutput(value, callId, maxChars) {
 }
 
 function toolResultCharBudget(activeTokens, budget) {
+  if (!budget) return 48_000;
   if (!Number.isFinite(activeTokens) || activeTokens < 0) return budget.maxToolResultChars;
   const reserveTokens = 4_000;
   const headroomTokens = Math.max(256, budget.maxNormalInputTokens - Math.ceil(activeTokens) - reserveTokens);
@@ -110,12 +113,13 @@ function toolResultCharBudget(activeTokens, budget) {
 
 function projectedInputTokens({ instructions, input, toolSurface, priorActiveTokens, budget }) {
   const inputChars = typeof input === 'string' ? input.length : JSON.stringify(input ?? '').length;
-  const newTokens = estimateContextTokens(String(instructions || '').length + inputChars + toolSurface.receipt.hydrated_schema_chars, budget.charsPerToken);
+  const charsPerToken = budget?.charsPerToken || 4;
+  const newTokens = estimateContextTokens(String(instructions || '').length + inputChars + toolSurface.receipt.hydrated_schema_chars, charsPerToken);
   return Math.max(newTokens, Number.isFinite(priorActiveTokens) ? Math.ceil(priorActiveTokens) + newTokens : newTokens);
 }
 
 function assertEconomicPreflight(projectedTokens, budget, allowOverride) {
-  if (allowOverride) return;
+  if (!budget || allowOverride) return;
   if (budget.pricingThresholdTokens != null && projectedTokens > budget.pricingThresholdTokens) {
     throw new Error(`context_preflight_pricing_threshold:${projectedTokens}>${budget.pricingThresholdTokens}`);
   }
@@ -130,46 +134,56 @@ export async function runResponsesAgent(options = {}) {
   const cwd = path.resolve(options.cwd || process.cwd());
   const objective = clean(options.prompt);
   if (!objective) throw new TypeError('prompt is required');
-  const record = getModelRecord(options.model);
+  const record = options.modelRecord || getModelRecord(options.model);
   if (!record) throw new RangeError(`unknown model: ${options.model}`);
-  const reasoningEffort = clean(options.reasoningEffort || 'low');
+  const reasoningEffort = clean(options.reasoningEffort || 'auto');
   const serviceTier = clean(options.serviceTier || 'default');
   const budget = modelBudget(record);
-  const instructionSet = options.instructions == null ? compileAgentInstructions(cwd, { maxChars: budget.maxSystemChars }) : null;
+  const instructionSet = options.instructions == null ? compileAgentInstructions(cwd, { maxChars: budget?.maxSystemChars || 48_000 }) : null;
   const instructions = options.instructions == null ? instructionSet.content : String(options.instructions);
   const toolSurface = buildAgentToolSurface(options.capabilityAdapter, objective, options);
   const emit = options.emit;
   const runId = options.runId;
   event(emit, 'tool.search', toolSurface.receipt, runId);
 
-  let previousResponseId = clean(options.previousResponseId) || null;
+  let previousResponseId = clean(options.previousResponseId || options.previousProviderState?.previous_response_id) || null;
+  let providerState = options.previousProviderState && typeof options.previousProviderState === 'object'
+    ? structuredClone(options.previousProviderState)
+    : previousResponseId ? { previous_response_id: previousResponseId } : null;
   let priorActiveTokens = options.previousUsageSnapshot?.current_context?.input_tokens;
   let input = objective;
   let compacted = null;
   let projected = projectedInputTokens({ instructions, input, toolSurface, priorActiveTokens, budget });
 
-  if (projected >= budget.compactAtTokens && previousResponseId && options.autoCompact !== false && typeof provider.compact === 'function') {
+  if (budget && projected >= budget.compactAtTokens && providerState && options.autoCompact !== false && typeof provider.compact === 'function') {
     compacted = await provider.compact({
       model: record.provider_model_id,
+      modelRecord: record,
       previousResponseId,
+      providerState,
       instructions,
       promptCacheKey: options.promptCacheKey,
+      tokensBefore: Number.isFinite(priorActiveTokens) ? priorActiveTokens : projected,
       emit,
       runId,
     });
-    input = [...(compacted.output || []), userMessage(objective)];
-    previousResponseId = null;
+    if (Array.isArray(compacted.output) && compacted.output.length) input = [...compacted.output, userMessage(objective)];
+    providerState = compacted.provider_state || null;
+    previousResponseId = clean(providerState?.previous_response_id) || null;
     priorActiveTokens = null;
     projected = projectedInputTokens({ instructions, input, toolSurface, priorActiveTokens, budget });
   }
 
   assertEconomicPreflight(projected, budget, options.allowEconomicOverride === true);
-  const pressure = assessContextUsage(projected, budget);
+  const pressure = budget ? assessContextUsage(projected, budget) : null;
+  const declaredMaxOutput = Number(record.max_output_tokens);
   const maxOutputTokens = Number.isInteger(options.maxOutputTokens) && options.maxOutputTokens > 0
-    ? Math.min(options.maxOutputTokens, record.max_output_tokens)
-    : Math.min(32_768, record.max_output_tokens);
-  const projectedCost = calculateModelCost(record, { input_tokens: projected, output_tokens: maxOutputTokens }, { serviceTier });
-  if (Number.isFinite(options.maxCallCostUsd) && projectedCost.total_usd > options.maxCallCostUsd) {
+    ? (Number.isFinite(declaredMaxOutput) && declaredMaxOutput > 0 ? Math.min(options.maxOutputTokens, declaredMaxOutput) : options.maxOutputTokens)
+    : (Number.isFinite(declaredMaxOutput) && declaredMaxOutput > 0 ? Math.min(32_768, declaredMaxOutput) : 16_384);
+  const projectedCost = record.pricing
+    ? calculateModelCost(record, { input_tokens: projected, output_tokens: maxOutputTokens }, { serviceTier })
+    : null;
+  if (Number.isFinite(options.maxCallCostUsd) && projectedCost && projectedCost.total_usd > options.maxCallCostUsd) {
     throw new Error(`projected_call_cost_exceeds_budget:${projectedCost.total_usd.toFixed(6)}>${Number(options.maxCallCostUsd).toFixed(6)}`);
   }
   const preflight = Object.freeze({
@@ -178,9 +192,9 @@ export async function runResponsesAgent(options = {}) {
     service_tier: serviceTier,
     estimated_input_tokens: projected,
     max_output_tokens: maxOutputTokens,
-    projected_max_call_cost_usd: projectedCost.total_usd,
-    pricing_threshold_tokens: budget.pricingThresholdTokens,
-    tokens_until_pricing_threshold: pressure.tokensUntilPricingThreshold,
+    projected_max_call_cost_usd: projectedCost?.total_usd ?? null,
+    pricing_threshold_tokens: budget?.pricingThresholdTokens ?? null,
+    tokens_until_pricing_threshold: pressure?.tokensUntilPricingThreshold ?? null,
     compacted_before_turn: Boolean(compacted),
     estimate_kind: 'local',
   });
@@ -191,32 +205,40 @@ export async function runResponsesAgent(options = {}) {
   event(emit, 'context.snapshot', {
     estimate_kind: 'local',
     estimated_input_tokens: projected,
-    window_tokens: budget.windowTokens,
-    utilization_ratio: pressure.utilizationRatio,
-    pricing_threshold_tokens: budget.pricingThresholdTokens,
-    tokens_until_pricing_threshold: pressure.tokensUntilPricingThreshold,
-    pressure: pressure.stage,
-    projected_max_call_cost_usd: projectedCost.total_usd,
+    window_tokens: budget?.windowTokens ?? null,
+    utilization_ratio: pressure?.utilizationRatio ?? null,
+    pricing_threshold_tokens: budget?.pricingThresholdTokens ?? null,
+    tokens_until_pricing_threshold: pressure?.tokensUntilPricingThreshold ?? null,
+    pressure: pressure?.stage ?? 'unknown',
+    projected_max_call_cost_usd: projectedCost?.total_usd ?? null,
     tool_surface: toolSurface.receipt,
   }, runId);
 
   let cumulativeUsage = options.cumulativeUsage || null;
   let totalCostUsd = 0;
+  const costBreakdownUsd = { input: 0, cached_input: 0, cache_write: 0, output: 0 };
+  const accumulateCost = (cost) => {
+    totalCostUsd += Number(cost?.total_usd || 0);
+    for (const key of Object.keys(costBreakdownUsd)) costBreakdownUsd[key] += Number(cost?.components_usd?.[key] || 0);
+  };
   let response = await provider.create({
     model: record.provider_model_id,
+    modelRecord: record,
     input,
     instructions,
     reasoningEffort,
     serviceTier,
     tools: toolSurface.tools,
     previousResponseId: previousResponseId || undefined,
+    providerState,
     maxOutputTokens,
     promptCacheKey: options.promptCacheKey,
     cumulativeUsage,
     emit,
     runId,
   });
-  totalCostUsd += response.cost?.total_usd || 0;
+  accumulateCost(response.cost);
+  providerState = response.provider_state || (response.response_id ? { previous_response_id: response.response_id } : providerState);
   cumulativeUsage = response.usage_snapshot?.cumulative || cumulativeUsage;
 
   const toolReceipts = [];
@@ -275,6 +297,8 @@ export async function runResponsesAgent(options = {}) {
     response = await provider.continueWithToolOutputs({
       model: record.provider_model_id,
       previousResponseId: response.response_id,
+      providerState: response.provider_state || providerState,
+      modelRecord: record,
       toolOutputs: outputs,
       instructions,
       reasoningEffort,
@@ -286,21 +310,22 @@ export async function runResponsesAgent(options = {}) {
       emit,
       runId,
     });
-    totalCostUsd += response.cost?.total_usd || 0;
+    accumulateCost(response.cost);
+    providerState = response.provider_state || (response.response_id ? { previous_response_id: response.response_id } : providerState);
     cumulativeUsage = response.usage_snapshot?.cumulative || cumulativeUsage;
   }
 
   const active = response.usage_snapshot?.current_context?.input_tokens ?? 0;
-  const finalPressure = assessContextUsage(active, budget);
+  const finalPressure = budget ? assessContextUsage(active, budget) : null;
   event(emit, 'context.snapshot', {
     estimate_kind: 'provider',
     active_input_tokens: active,
-    window_tokens: budget.windowTokens,
-    utilization_ratio: finalPressure.utilizationRatio,
-    pricing_threshold_tokens: budget.pricingThresholdTokens,
-    tokens_until_pricing_threshold: finalPressure.tokensUntilPricingThreshold,
-    pressure: finalPressure.stage,
-    compact_before_next_turn: finalPressure.shouldCompact,
+    window_tokens: budget?.windowTokens ?? null,
+    utilization_ratio: finalPressure?.utilizationRatio ?? null,
+    pricing_threshold_tokens: budget?.pricingThresholdTokens ?? null,
+    tokens_until_pricing_threshold: finalPressure?.tokensUntilPricingThreshold ?? null,
+    pressure: finalPressure?.stage ?? 'unknown',
+    compact_before_next_turn: finalPressure?.shouldCompact ?? false,
   }, runId);
 
   return Object.freeze({
@@ -313,13 +338,16 @@ export async function runResponsesAgent(options = {}) {
     usage_snapshot: response.usage_snapshot,
     cumulative_usage: cumulativeUsage,
     total_cost_usd: totalCostUsd,
+    cost_breakdown_usd: Object.freeze({ ...costBreakdownUsd }),
     tool_surface: toolSurface.receipt,
     tool_receipts: Object.freeze(toolReceipts),
     compacted_before_turn: Boolean(compacted),
+    provider_state: providerState,
     continuation: Object.freeze({
-      previous_response_id: response.response_id,
+      previous_response_id: response.response_id || providerState?.previous_response_id || null,
+      provider_state: providerState,
       usage_snapshot: response.usage_snapshot,
-      compact_before_next_turn: finalPressure.shouldCompact,
+      compact_before_next_turn: finalPressure?.shouldCompact ?? false,
     }),
   });
 }

package/src/capabilities/repository-snapshot.js

@@ -4,10 +4,10 @@ import { execFile } from 'node:child_process';
 import { promisify } from 'node:util';
 import { fileURLToPath } from 'node:url';
 import { createHash } from 'node:crypto';
-import { resolveGitContext } from '../lib/git-context.js';
+import { resolveGitContext } from '../../packages/agentsam-repository/src/git-context.js';
 import { getRepositoryId, tryReadProjectConfig } from '../lib/project-config.js';
-import { buildMerkleTree } from '../lib/merkle/index.js';
-import { gitIgnoredPaths } from '../lib/merkle/git-ignore.js';
+import { buildMerkleTree } from '../../packages/agentsam-repository/src/merkle/index.js';
+import { gitIgnoredPaths } from '../../packages/agentsam-repository/src/merkle/git-ignore.js';
 import { analyzeExecutionBoundaries } from '../indexing/execution-boundary.js';
 import { showLatestDeployReceipt } from '../lib/deploy-receipt/index.js';
 import { CONFIG_PATH, canonical, readConfig, scopeKey } from '../knowledge/config.js';

package/src/cli.js

@@ -13,6 +13,7 @@ import { promptOptionalByokKeys } from './lib/prompt-byok.js';
 import { runStartLocal } from './commands/start-local.js';
 import { runOllama } from './commands/ollama.js';
 import { runModels } from './commands/models.js';
+import { runEnv } from './commands/env.js';
 import { runTunnel } from './commands/tunnel.js';
 import { runDeploy } from './commands/deploy.js';
 import { runConnections } from './commands/connections.js';
@@ -42,6 +43,7 @@ import fs from 'node:fs';
 import { repositoryRoot } from './knowledge/config.js';
 import { resolveAccountSdkKey } from './lib/account-session.js';
 import { renderDiagnosticError } from './errors/index.js';
+import { renderHelpOverview, runHelp } from './ui/cli/help.js';
 
 const VERSION = pkg.version;
 
@@ -60,6 +62,10 @@ function createPrompt() {
 }
 
 function printHelp() {
+  console.log(renderHelpOverview(VERSION));
+}
+
+function printLegacyHelp() {
   console.log(`
   Agent Sam SDK — CLI v${VERSION}
 
@@ -90,9 +96,10 @@ function printHelp() {
     agentsam status [--json]   Live local Git + DB + API + PTY status
     agentsam db init|status    Manage the project-local SQLite database
     agentsam models            Verify configured providers and selectable hosted/local models
-    agentsam login             Authenticate IAM and persist a secure machine-local session
-    agentsam logout            Remove the local IAM session; provider keys stay untouched
-    agentsam whoami [--json]   Authenticated IAM identity + safe credential status
+    agentsam env init <name>   Create a secure provider profile + reusable shell loader
+    agentsam login             Sign in to Inner Animal Media and persist a secure machine-local session
+    agentsam logout            Sign out locally; provider credentials stay untouched
+    agentsam whoami [--json]   Authenticated account identity + safe credential status
     agentsam resume [session]  Resume a saved Agent Sam session; omit id for picker
     agentsam eval context      Offline context-strategy/economics fixtures (--help)
     agentsam cloudflare        Native Wrangler reads + Worker CPU profile analysis (--help)
@@ -102,8 +109,9 @@ function printHelp() {
     agentsam tunnel            Explicitly expose local PTY when remote access is wanted
     agentsam deploy            Graduate to Cloudflare / GCP when ready
     agentsam dockerize         Build/run app, knowledge, or CAD containers (--help)
-    agentsam identity preview  Local auth portal preview
+    agentsam identity preview  Preview the reusable local auth portal (not production login)
     agentsam identity init     Add reusable identity package surfaces
+    agentsam help
     agentsam --version
     agentsam --help
 
@@ -127,8 +135,8 @@ function printHelp() {
     --pretty                   Pretty-print JSON; machine JSON is compact by default
     --remote <name>            Preferred Git remote (default origin; falls back to first remote)
 
-  Init is completable with Node only — no IAM login, no OAuth, no Cloudflare.
-  Prove locally first; deploy prompts for accounts only when you choose to ship.
+  Run agentsam from any project to enter the account-aware interactive experience.
+  Account, model-provider, terminal, and deploy permissions are requested only when the related capability needs them.
 
   Tunnel options:
     --quick                    Quick tunnel (default) — trycloudflare.com URL
@@ -311,6 +319,8 @@ const rest = process.argv.slice(3);
 
 if (command === '--version' || command === '-v') {
   console.log(VERSION);
+} else if (command === 'help') {
+  await runHelp(rest, { version: VERSION });
 } else if (command === '--help' || command === '-h') {
   printHelp();
 } else if (!command) {
@@ -377,6 +387,13 @@ if (command === '--version' || command === '-v') {
     reportCliError(e);
     process.exit(1);
   }
+} else if (command === 'env') {
+  try {
+    await runEnv(rest);
+  } catch (e) {
+    reportCliError(e);
+    process.exit(1);
+  }
 } else if (command === 'eval') {
   try {
     await runEval(rest);

package/src/commands/context-economics.js

@@ -12,7 +12,9 @@ function percent(value) {
 
 export function buildContextEconomicsReport(cwd, options = {}) {
   const preferences = options.preferences || readCliPreferences(cwd) || {};
-  const model = getModelRecord(preferences.modelPreference);
+  const model = preferences.modelSnapshot?.model_key === preferences.modelPreference
+    ? preferences.modelSnapshot
+    : getModelRecord(preferences.modelPreference);
   if (!model) {
     return Object.freeze({
       model: preferences.modelPreference || 'auto',
@@ -24,9 +26,22 @@ export function buildContextEconomicsReport(cwd, options = {}) {
     });
   }
 
+  const windowTokens = Number(model.context_window);
+  if (!(Number.isFinite(windowTokens) && windowTokens > 0)) {
+    return Object.freeze({
+      model: model.provider_model_id,
+      model_key: model.model_key,
+      resolved: false,
+      reason: 'This provider verified the model but did not expose a trustworthy context-window limit. Agent Sam will show ctx unknown rather than guess.',
+      reasoning_effort: preferences.reasoningEffort || 'auto',
+      service_tier: preferences.serviceTier || 'default',
+      active_input_tokens: Number.isFinite(options.activeInputTokens) ? Math.floor(options.activeInputTokens) : null,
+    });
+  }
+
   const policy = model.context_policy || {};
   const budget = createContextBudget({
-    windowTokens: model.context_window,
+    windowTokens,
     targetInputTokens: policy.target_input_tokens,
     compactAtTokens: policy.compact_at_tokens,
     interveneAtTokens: policy.intervene_at_tokens,

package/src/commands/context.js

@@ -1,4 +1,4 @@
-import { tryResolveGitContext } from '../lib/git-context.js';
+import { tryResolveGitContext } from '../../packages/agentsam-repository/src/git-context.js';
 import { resolveAgentSamBaseUrl, resolveBridgeKey } from '../lib/bridge-client.js';
 import { loadProjectRules } from '../lib/project-rules.js';
 

package/src/commands/db.js

@@ -1,6 +1,7 @@
 import fs from 'node:fs';
 import path from 'node:path';
-import { initializeLocalSqlite, inspectLocalSqlite } from '../local/sqlite.js';
+import { createLocalSqliteDatabase, initializeLocalSqlite, inspectLocalSqlite } from '../local/sqlite.js';
+import { applyRuntimeMigrations } from '../local/migrations.js';
 import { getLocalDatabasePath, getLocalSchemaPath, readProjectConfig } from '../lib/project-config.js';
 
 function findProjectRoot(startDir) {
@@ -23,7 +24,7 @@ function resolveDb(root, config) {
 
 export async function runDb(argv = [], opts = {}) {
   const sub = argv[0] || 'status';
-  if (!['init', 'status'].includes(sub)) {
+  if (!['init', 'migrate', 'status'].includes(sub)) {
     throw new Error(`unknown db command: ${sub}`);
   }
 
@@ -36,10 +37,26 @@ export async function runDb(argv = [], opts = {}) {
     console.log(`\n  Agent Sam local DB\n`);
     console.log(`  ✓ SQLite      ${result.dbPath}`);
     console.log(`  ✓ Tables      ${result.tables.length}`);
-    console.log(`  ✓ Schema      ${paths.schemaPath}\n`);
+    console.log(`  ✓ Schema      ${paths.schemaPath}`);
+    console.log('  ✓ Migrations  current\n');
     return result;
   }
 
+  if (sub === 'migrate') {
+    if (!fs.existsSync(paths.dbPath)) throw new Error('Local DB is not initialized — run `agentsam db init` first.');
+    const db = await createLocalSqliteDatabase(paths.dbPath);
+    try {
+      const result = await applyRuntimeMigrations(db);
+      console.log(`\n  Agent Sam local DB migrations\n`);
+      console.log(`  applied       ${result.applied}`);
+      console.log(`  known         ${result.total}`);
+      console.log(`  path          ${paths.dbPath}\n`);
+      return result;
+    } finally {
+      db.close();
+    }
+  }
+
   const result = await inspectLocalSqlite(paths.dbPath);
   console.log(`\n  Agent Sam local DB\n`);
   if (!result.exists) {

package/src/commands/env.js

@@ -0,0 +1,90 @@
+import { spawnSync } from 'node:child_process';
+import { describeProviderCredential, ensureProviderEnvProfile, providerCredentialSpec } from '../lib/provider-credentials.js';
+
+const PROVIDERS = Object.freeze(['openai', 'anthropic', 'gemini', 'grok', 'cloudflare']);
+
+function writeLine(write, value = '') { write(`${value}\n`); }
+
+function detectCloudflareAccounts(options = {}) {
+  const env = options.env || process.env;
+  const explicit = String(options.accountId || env.ACCOUNT_ID || env.CLOUDFLARE_ACCOUNT_ID || '').trim();
+  if (explicit) return { accounts: [{ id: explicit, name: null }], source: 'environment' };
+  const spawn = options.spawnSyncImpl || spawnSync;
+  const result = spawn('npx', ['--no-install', 'wrangler', 'whoami', '--json'], { cwd: options.cwd || process.cwd(), env, encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'] });
+  if (result?.status !== 0) return { accounts: [], source: 'wrangler', error: String(result?.stderr || '').trim() || `wrangler exited ${result?.status ?? 'unknown'}` };
+  try {
+    const parsed = JSON.parse(String(result.stdout || '{}'));
+    const accounts = (Array.isArray(parsed?.accounts) ? parsed.accounts : []).map((row) => ({
+      id: String(row?.id || row?.account_id || '').trim(),
+      name: String(row?.name || row?.account_name || '').trim() || null,
+    })).filter((row) => row.id);
+    return { accounts, source: 'wrangler', error: null };
+  } catch (error) {
+    return { accounts: [], source: 'wrangler', error: `invalid wrangler JSON: ${error?.message || error}` };
+  }
+}
+
+function cloudflareGuidance(write) {
+  writeLine(write, '');
+  writeLine(write, '  Cloudflare token guidance');
+  writeLine(write, '  models only       Workers AI Read');
+  writeLine(write, '  run Workers AI    Workers AI Read + Edit');
+  writeLine(write, '  deploy Workers    Workers Editor for existing Workers; Admin only when create/delete is required');
+  writeLine(write, '  routes/domains    add Workers Routes Write only when AgentSam must change them');
+  writeLine(write, '  D1 / R2 / KV      add direct product permissions only when AgentSam must read/write those resources directly');
+}
+
+export async function runEnv(argv = [], options = {}) {
+  const write = options.write || ((text) => process.stdout.write(text));
+  const [command = 'status', providerArg] = argv;
+  let accountId = '';
+  for (let i = 2; i < argv.length; i += 1) {
+    if (argv[i] === '--account-id') accountId = String(argv[++i] || '').trim();
+    else throw new Error(`unexpected env argument: ${argv[i]}`);
+  }
+  if (command === '--help' || command === '-h' || command === 'help') {
+    writeLine(write, 'agentsam env init <openai|anthropic|gemini|grok|cloudflare> [--account-id <id>]');
+    writeLine(write, 'agentsam env status [provider]');
+    return;
+  }
+  if (command === 'init') {
+    const provider = String(providerArg || '').trim().toLowerCase();
+    if (!PROVIDERS.includes(provider)) throw new Error(`env init requires one of: ${PROVIDERS.join(', ')}`);
+    let cloudflareAccounts = null;
+    if (provider === 'cloudflare') {
+      if (accountId && !/^[a-f0-9]{32}$/i.test(accountId)) throw new Error('Cloudflare --account-id must be a 32-character hexadecimal account ID');
+      cloudflareAccounts = detectCloudflareAccounts({ ...options, accountId });
+      if (!accountId && cloudflareAccounts.accounts.length === 1) accountId = cloudflareAccounts.accounts[0].id;
+    }
+    const result = ensureProviderEnvProfile(provider, { ...options, accountId });
+    writeLine(write, '');
+    writeLine(write, `  AgentSam · ${provider} environment`);
+    writeLine(write, `  profile  ${result.file}${result.created ? ' · created' : ' · existing'}`);
+    writeLine(write, `  loader   ${result.loader}`);
+    writeLine(write, '');
+    writeLine(write, '  Add the credential to the profile, then load it into this shell:');
+    writeLine(write, `    ${result.source_command}`);
+    if (provider === 'cloudflare') {
+      if (accountId) writeLine(write, `  account  detected/configured (${cloudflareAccounts?.source || 'explicit'})`);
+      else if ((cloudflareAccounts?.accounts || []).length > 1) writeLine(write, `  account  ${cloudflareAccounts.accounts.length} Wrangler accounts found · rerun with --account-id <id>`);
+      else writeLine(write, '  account  not detected · set ACCOUNT_ID in the profile or rerun with --account-id <id>');
+      cloudflareGuidance(write);
+    }
+    writeLine(write, '');
+    return result;
+  }
+  if (command === 'status') {
+    const providers = providerArg ? [String(providerArg).trim().toLowerCase()] : PROVIDERS;
+    for (const provider of providers) if (!providerCredentialSpec(provider)) throw new Error(`unsupported_provider:${provider}`);
+    writeLine(write, '');
+    writeLine(write, '  AgentSam · provider environments');
+    for (const provider of providers) {
+      const row = describeProviderCredential(provider, options);
+      const extra = row.account_id ? ` · account ${row.account_id}` : '';
+      writeLine(write, `  ${provider.padEnd(12)} ${row.configured ? 'configured' : row.error ? `blocked (${row.error})` : 'not configured'}${extra}`);
+    }
+    writeLine(write, '');
+    return;
+  }
+  throw new Error(`unknown env command: ${command}`);
+}

package/src/commands/knowledge.js

@@ -7,13 +7,13 @@ import { promisify } from 'node:util';
 import { fileURLToPath } from 'node:url';
 import { randomUUID } from 'node:crypto';
 import pkg from '../../package.json' with { type: 'json' };
-import { CONFIG_PATH, repositoryRoot, initRepository, readConfig, scopeKey, cacheNamespace } from '../knowledge/config.js';
+import { CONFIG_PATH, repositoryRoot, initRepository, readConfig, defaultConfig, scopeKey, cacheNamespace } from '../knowledge/config.js';
 import { openSqliteStore } from '../knowledge/stores/sqlite.js';
 import { openPostgresStore } from '../knowledge/stores/postgres.js';
 import { planIndex, runIndex, retrieve } from '../knowledge/engine.js';
 import { createGeminiEmbedder } from '../knowledge/providers/gemini.js';
 import { compareObservations } from '../knowledge/evolution.js';
-import { ensureProjectManifest, getProjectName, getRepositoryId } from '../lib/project-config.js';
+import { ensureProjectManifest, getProjectName, getRepositoryId, portableRepositoryIdFromGit, tryReadProjectConfig } from '../lib/project-config.js';
 import { ensureProjectRules } from '../lib/project-rules.js';
 
 const execute = promisify(execFile);
@@ -25,6 +25,14 @@ async function openStore(root, config, readOnly = false) {
   return config.storage.driver === 'sqlite' ? openSqliteStore(localPath(root), { readOnly }) : openPostgresStore(process.env[config.storage.connection_env]);
 }
 function provider() { return createGeminiEmbedder({ apiKey: process.env.GEMINI_API_KEY }); }
+function resolveKnowledgeConfig(root) {
+  const filename = path.join(root, CONFIG_PATH);
+  if (fs.existsSync(filename)) return readConfig(root);
+  const project = tryReadProjectConfig(root);
+  const repositoryId = getRepositoryId(project) || portableRepositoryIdFromGit(root);
+  if (!repositoryId) throw new Error(`${CONFIG_PATH} is absent and repository identity could not be derived; run agentsam init . --yes to configure this repository.`);
+  return defaultConfig({ repositoryId });
+}
 
 export async function runRepositoryInit(argv) {
   const { values: opts, positionals } = flags(argv, { existing: { type: 'boolean' }, yes: { type: 'boolean', short: 'y' }, include: { type: 'string' }, exclude: { type: 'string' }, scope: { type: 'string' }, target: { type: 'string' }, dimensions: { type: 'string' } });
@@ -73,7 +81,7 @@ export async function runKnowledge(argv) {
   const command = positionals[0] || 'plan';
   if (opts.help) { console.log('agentsam index plan|run|status|history|show|setup-store [--cwd PATH] [--embed] [--max-inputs 100] [--max-characters 200000] [--generation ID] [--json]\nplan is read-only; run defaults to AST/text only; --embed sends selected chunks to the configured provider.'); return; }
   if (positionals.length > 1 || !['plan', 'run', 'status', 'history', 'show', 'setup-store'].includes(command)) throw new Error('Unknown index command; use agentsam index --help.');
-  const root = repositoryRoot(opts.cwd), config = readConfig(root);
+  const root = repositoryRoot(opts.cwd), config = resolveKnowledgeConfig(root);
   const store = await openStore(root, config, !['run', 'setup-store'].includes(command));
   try {
     if (command === 'setup-store') {
@@ -97,7 +105,7 @@ export async function runKnowledge(argv) {
 export async function runSearch(argv) {
   const { values: opts, positionals } = flags(argv, { semantic: { type: 'boolean' }, 'top-k': { type: 'string' }, 'token-budget': { type: 'string' }, generation: { type: 'string' } });
   if (opts.help) { console.log('agentsam search "query" [--cwd PATH] [--semantic] [--top-k 8] [--token-budget 6000] [--generation ID]'); return; }
-  const root = repositoryRoot(opts.cwd), config = readConfig(root), store = await openStore(root, config, true);
+  const root = repositoryRoot(opts.cwd), config = resolveKnowledgeConfig(root), store = await openStore(root, config, true);
   try { show(await retrieve({ store, config, text: positionals.join(' '), semantic: opts.semantic, embedder: opts.semantic ? provider() : null, topK: Number(opts['top-k'] || 8), tokenBudget: Number(opts['token-budget'] || 6000), generationId: opts.generation })); }
   finally { await store?.close(); }
 }

package/src/commands/merkle-persist.js

@@ -1,10 +1,12 @@
 import path from 'node:path';
-import { readSnapshot } from '../lib/merkle/snapshot.js';
+import { readSnapshot } from '../../packages/agentsam-repository/src/merkle/snapshot.js';
+import { readAccountSession } from '../lib/account-session.js';
+import { getRepositoryId, portableRepositoryIdFromGit, tryReadProjectConfig } from '../lib/project-config.js';
 import {
   buildMerklePersistencePlan,
   persistMerkleSnapshotCloudflare,
   resolveWranglerMerklePersistence,
-} from '../lib/merkle/cloudflare-persistence.js';
+} from '../../packages/agentsam-repository/src/merkle/cloudflare-persistence.js';
 
 function value(args, index, flag) {
   const next = args[index + 1];
@@ -17,8 +19,6 @@ export function printMerklePersistHelp() {
   agentsam merkle persist <snapshot.json> — publish a saved Merkle snapshot through host bindings
 
   --wrangler-config <file>    Worker config containing WEBSITE_ASSETS and optionally DB
-  --owner-user-id <id>        Snapshot owner authority (or AGENTSAM_OWNER_USER_ID)
-  --repo-id <id>              Canonical repo id; inferred for GitHub/GitLab/Bitbucket when possible
   --capture-kind <kind>       deploy|manual|agent|index (default manual)
   --connection-id <id>        Execution provenance for non-deploy captures
   --runtime-lease-id <id>     Alternative execution provenance for non-deploy captures
@@ -35,9 +35,11 @@ export function printMerklePersistHelp() {
   --dry-run                   Resolve bindings and emit the exact storage/index plan without writes
   --json                      Machine-readable output
 
-  The SDK never infers owner identity. Hosts should pass authenticated owner_user_id.
-  Physical bucket/database names come from Wrangler bindings, so customer installs keep
-  WEBSITE_ASSETS/DB while selecting their own storage resources.
+  CLI ownership comes from the authenticated AgentSam session, while repository identity is
+  derived from Git/provider identity (with the committed project manifest as local fallback).
+  Programmatic hosts pass account_id + repository_id directly to the persistence plan. Physical
+  bucket/database names come from Wrangler bindings, so customer installs keep WEBSITE_ASSETS/DB
+  while selecting their own storage resources.
 `);
 }
 
@@ -55,7 +57,7 @@ function parse(args) {
     if (arg === '--dry-run') { opts.dryRun = true; continue; }
     if (arg === '--r2-only') { opts.r2Only = true; continue; }
     const map = {
-      '--wrangler-config': 'wranglerConfig', '--owner-user-id': 'ownerUserId', '--repo-id': 'repoId',
+      '--wrangler-config': 'wranglerConfig',
       '--capture-kind': 'captureKind', '--connection-id': 'connectionId', '--runtime-lease-id': 'runtimeLeaseId',
       '--deployment-id': 'deploymentId', '--worker-version': 'workerVersionId', '--reference-label': 'referenceLabel',
       '--source': 'source', '--prefix': 'storagePrefix', '--r2-binding': 'r2Binding', '--d1-binding': 'd1Binding',
@@ -65,19 +67,36 @@ function parse(args) {
     throw new Error(`Unknown merkle persist option: ${arg}`);
   }
   if (!opts.snapshotPath) throw new Error('snapshot_file_required');
-  opts.ownerUserId ||= process.env.AGENTSAM_OWNER_USER_ID || '';
   opts.wranglerConfig ||= process.env.AGENTSAM_WRANGLER_CONFIG || '';
   opts.connectionId ||= process.env.AGENTSAM_CONNECTION_ID || '';
   opts.runtimeLeaseId ||= process.env.AGENTSAM_RUNTIME_LEASE_ID || '';
   return opts;
 }
 
+export function resolveMerklePersistenceIdentity(root, options = {}) {
+  const session = options.session ?? readAccountSession(options.sessionOptions || {});
+  const accountId = String(session?.account_id || '').trim();
+  if (!accountId) throw new Error('agentsam_login_required_for_merkle_persistence');
+
+  const projectConfig = options.projectConfig ?? tryReadProjectConfig(root);
+  const gitRepositoryId = portableRepositoryIdFromGit(root);
+  const repositoryId = gitRepositoryId || getRepositoryId(projectConfig);
+  if (!repositoryId) throw new Error('repository_identity_unresolved');
+
+  return {
+    accountId,
+    repositoryId,
+    repositoryIdentitySource: gitRepositoryId ? 'git' : 'project_manifest',
+  };
+}
+
 export async function runMerklePersist(args = []) {
   const opts = parse(args);
   if (opts.help) { printMerklePersistHelp(); return null; }
   const snapshotPath = path.resolve(opts.snapshotPath);
   const snapshot = await readSnapshot(snapshotPath);
   const root = path.resolve(opts.root || snapshot.rootPath || process.cwd());
+  const identity = resolveMerklePersistenceIdentity(root);
   const wrangler = resolveWranglerMerklePersistence({
     configPath: opts.wranglerConfig,
     environment: opts.environment || null,
@@ -88,8 +107,8 @@ export async function runMerklePersist(args = []) {
   const plan = buildMerklePersistencePlan({
     snapshot,
     root,
-    ownerUserId: opts.ownerUserId,
-    repoId: opts.repoId,
+    accountId: identity.accountId,
+    repositoryId: identity.repositoryId,
     source: opts.source,
     captureKind: opts.captureKind,
     connectionId: opts.connectionId,