@inneranimalmedia/agentsam-sdk 2.5.0 → 2.6.0

package/src/eval/context.js

@@ -0,0 +1,191 @@
+import { assessContextUsage, compactContextItem, createContextBudget, estimateContextTokens, rehydrateContextRef, resolveContext } from '../context/index.js';
+import { calculateModelCost, getModelRecord } from '../models/index.js';
+import { hydrateToolSchemas, searchToolCards } from '../tools/index.js';
+
+const STRATEGIES = Object.freeze(['bounded', 'discovery', 'compact']);
+
+const BASE_TOOLS = Object.freeze([
+  { name: 'repository.snapshot', description: 'Inspect repository identity, tree, packages, and structural evidence.', category: 'repository', input_schema: { type: 'object', properties: { cwd: { type: 'string' } } } },
+  { name: 'code.symbols', description: 'Find exact symbols, declarations, imports, and callers in indexed source.', category: 'code', input_schema: { type: 'object', required: ['query'], properties: { query: { type: 'string' } } } },
+  { name: 'files.read', description: 'Read a selected file or bounded source range by stable reference.', category: 'files', input_schema: { type: 'object', required: ['ref'], properties: { ref: { type: 'string' } } } },
+  { name: 'tests.trace', description: 'Trace a failing test to referenced source symbols and files.', category: 'tests', input_schema: { type: 'object', required: ['test'], properties: { test: { type: 'string' } } } },
+  { name: 'context.rehydrate', description: 'Recover previously compacted evidence by stable reference and hash.', category: 'context', input_schema: { type: 'object', required: ['ref'], properties: { ref: { type: 'string' } } } },
+  ...Array.from({ length: 20 }, (_, index) => ({ name: `misc.tool.${index}`, description: `Unrelated generic capability ${index}.`, category: 'misc', input_schema: { type: 'object', properties: {} } })),
+]);
+
+const FIXTURES = Object.freeze({
+  'exact-symbol-callers': {
+    task: 'Find the exact resolveContext implementation and its budget dependency before changing context selection.',
+    required: ['file:src/context/resolve.js', 'file:src/context/budget.js'],
+    syntheticBaseTokens: 8_000,
+    items: [
+      { ref: 'file:src/context/resolve.js', kind: 'file', priority: 100, content: 'resolveContext selects evidence, computes receipt composition, and defers overflow refs.'.repeat(40) },
+      { ref: 'file:src/context/budget.js', kind: 'file', priority: 95, content: 'createContextBudget separates model capacity from AgentSam working-set policy.'.repeat(36) },
+      { ref: 'file:README.md', kind: 'file', priority: 8, content: 'General product documentation.'.repeat(100) },
+      { ref: 'file:apps/local-studio/theme.css', kind: 'file', priority: 1, content: 'Unrelated visual styles.'.repeat(160) },
+    ],
+  },
+  'two-file-repair': {
+    task: 'Repair a shell model-control regression spanning CLI preferences and slash dispatch without loading unrelated apps.',
+    required: ['file:src/lib/cli-preferences.js', 'file:src/commands/shell.js'],
+    syntheticBaseTokens: 14_000,
+    items: [
+      { ref: 'file:src/lib/cli-preferences.js', kind: 'file', priority: 100, content: 'CLI preference schema and persistence.'.repeat(90) },
+      { ref: 'file:src/commands/shell.js', kind: 'file', priority: 98, content: 'Slash command parsing, runtime cwd, model and context controls.'.repeat(120) },
+      { ref: 'file:apps/cad-creator/frontend/app.tsx', kind: 'file', priority: 5, content: 'CAD UI.'.repeat(300) },
+      { ref: 'file:docs/identity.md', kind: 'file', priority: 4, content: 'Identity docs.'.repeat(240) },
+    ],
+  },
+  'config-without-runtime-pollution': {
+    task: 'Update portable project defaults while keeping account, run, connection, and execution state out of committed config.',
+    required: ['file:.agentsam/config.json', 'file:src/lib/cli-preferences.js'],
+    syntheticBaseTokens: 10_000,
+    items: [
+      { ref: 'file:.agentsam/config.json', kind: 'file', priority: 100, content: 'Portable repository identity and defaults only.'.repeat(90) },
+      { ref: 'file:src/lib/cli-preferences.js', kind: 'file', priority: 90, content: 'Gitignored per-machine model, runtime, terminal, and trust preferences.'.repeat(85) },
+      { ref: 'memory:run-history', kind: 'memory', priority: 3, content: 'Large hosted run history must not be copied into project config.'.repeat(500), consumed: true },
+    ],
+  },
+  'trace-failing-test': {
+    task: 'Trace a failing shell regression test to the exact implementation and fix only the implicated source.',
+    required: ['file:test/shell.test.mjs', 'file:src/commands/shell.js'],
+    syntheticBaseTokens: 22_000,
+    items: [
+      { ref: 'file:test/shell.test.mjs', kind: 'file', priority: 100, content: 'Regression assertions for slash dispatch and runtime cwd.'.repeat(110) },
+      { ref: 'file:src/commands/shell.js', kind: 'file', priority: 96, content: 'Command implementation under test.'.repeat(140) },
+      { ref: 'file:test/cad.test.mjs', kind: 'file', priority: 2, content: 'Unrelated CAD tests.'.repeat(240) },
+    ],
+  },
+  'contradictory-paths': {
+    task: 'Detect two contradictory model-selection paths and choose one canonical runtime preference path.',
+    required: ['file:src/commands/models.js', 'file:src/commands/preferences.js', 'file:src/lib/cli-preferences.js'],
+    syntheticBaseTokens: 36_000,
+    items: [
+      { ref: 'file:src/commands/models.js', kind: 'file', priority: 100, content: 'Provider model discovery and availability proof.'.repeat(105) },
+      { ref: 'file:src/commands/preferences.js', kind: 'file', priority: 98, content: 'Interactive model, reasoning, and processing selection.'.repeat(100) },
+      { ref: 'file:src/lib/cli-preferences.js', kind: 'file', priority: 96, content: 'Canonical local preference persistence.'.repeat(90) },
+      { ref: 'file:legacy/model-picker.js', kind: 'file', priority: 15, content: 'Legacy duplicate picker path that should not become a second authority.'.repeat(200), consumed: true },
+    ],
+  },
+  'continuation-after-compaction': {
+    task: 'Continue a long tool-heavy run by compacting consumed evidence and rehydrating the exact result needed for the next step.',
+    required: ['tool:call_previous', 'file:src/context/compact.js'],
+    syntheticBaseTokens: 174_000,
+    items: [
+      { ref: 'tool:call_previous', kind: 'tool_result', priority: 100, content: 'Critical prior tool evidence with stable identity and the exact invariant required later. '.repeat(900), consumed: true },
+      { ref: 'file:src/context/compact.js', kind: 'file', priority: 95, content: 'Compaction preserves ref hash and source size while shrinking active context.'.repeat(100) },
+      { ref: 'file:unrelated/generated.log', kind: 'file', priority: 1, content: 'Noisy old generated log.'.repeat(500), consumed: true },
+    ],
+  },
+});
+
+function budgetFor(record) {
+  const p = record.context_policy;
+  return createContextBudget({ windowTokens: record.context_window, targetInputTokens: p.target_input_tokens, compactAtTokens: p.compact_at_tokens, interveneAtTokens: p.intervene_at_tokens, maxNormalInputTokens: p.max_normal_input_tokens, pricingThresholdTokens: p.pricing_threshold_tokens, safetyMarginTokens: p.safety_margin_tokens });
+}
+
+function fixture(name) {
+  const value = FIXTURES[name];
+  if (!value) throw new Error(`unknown context eval fixture: ${name}`);
+  return value;
+}
+
+async function runStrategy(fx, strategy, record) {
+  const budget = budgetFor(record);
+  let items = fx.items.map(item => ({ ...item }));
+  let compactedChars = 0;
+  const sources = new Map(items.map(item => [item.ref, item]));
+  const rehydratedRefs = [];
+
+  if (strategy === 'compact') {
+    items = items.map(item => {
+      if (!item.consumed) return item;
+      const compacted = compactContextItem(item, { maxChars: 4_000 });
+      compactedChars += Math.max(0, item.content.length - compacted.content.length);
+      return compacted;
+    });
+  }
+
+  const tools = strategy === 'bounded' ? { cards: [], receipt: { returned_items: 0, chars: 0 } } : searchToolCards(BASE_TOOLS, fx.task, { maxItems: 8 });
+  const hydrated = strategy === 'bounded' ? { tools: [], receipt: { hydrated_tools: 0, schema_chars: 0 } } : hydrateToolSchemas(BASE_TOOLS, tools.cards.map(card => card.tool), { maxTools: 8, maxChars: 40_000 });
+  let pack = resolveContext({ objective: fx.task, budget, toolSchemaChars: hydrated.receipt.schema_chars, items });
+  const selectedRefs = new Set(pack.items.map(item => item.ref));
+
+  if (strategy === 'compact') {
+    for (const ref of fx.required) {
+      const selected = pack.items.find(item => item.ref === ref);
+      if (!selected?.compacted) continue;
+      const source = sources.get(ref);
+      const rehydrated = await rehydrateContextRef(ref, async () => source, { kind: source.kind, maxChars: budget.maxFileCharsPerRead });
+      const remaining = pack.items.filter(item => item.ref !== ref);
+      remaining.push({ ...rehydrated, priority: source.priority });
+      pack = resolveContext({ objective: fx.task, budget, toolSchemaChars: hydrated.receipt.schema_chars, items: remaining });
+      selectedRefs.add(ref);
+      rehydratedRefs.push(ref);
+    }
+  }
+
+  const missingRequired = fx.required.filter(ref => !selectedRefs.has(ref));
+  const evidenceTokens = pack.receipt.estimated_input_tokens;
+  const activeTokens = fx.syntheticBaseTokens + evidenceTokens;
+  const pressure = assessContextUsage(activeTokens, budget);
+  const inputCost = calculateModelCost(record, { input_tokens: activeTokens, output_tokens: 0 }, { serviceTier: 'default' });
+  return Object.freeze({
+    strategy,
+    result: missingRequired.length ? 'FAIL' : 'PASS',
+    required_evidence: fx.required.length,
+    required_found: fx.required.length - missingRequired.length,
+    missing_required: Object.freeze(missingRequired),
+    sources_considered: pack.receipt.sources_considered,
+    sources_selected: pack.receipt.sources_included,
+    sources_deferred: pack.receipt.sources_deferred,
+    tool_cards: tools.receipt.returned_items,
+    tool_card_chars: tools.receipt.chars,
+    hydrated_tools: hydrated.receipt.hydrated_tools,
+    tool_schema_chars: hydrated.receipt.schema_chars,
+    compacted_chars: compactedChars,
+    rehydrated_refs: Object.freeze(rehydratedRefs),
+    active_context_tokens: activeTokens,
+    evidence_tokens: evidenceTokens,
+    window_tokens: budget.windowTokens,
+    pricing_threshold_tokens: budget.pricingThresholdTokens,
+    tokens_until_pricing_threshold: pressure.tokensUntilPricingThreshold,
+    pressure: pressure.stage,
+    should_compact: pressure.shouldCompact,
+    estimated_input_cost_usd: inputCost.total_usd,
+    estimate_kind: 'local',
+  });
+}
+
+function rank(results) {
+  return [...results].sort((a, b) => {
+    if (a.result !== b.result) return a.result === 'PASS' ? -1 : 1;
+    if (a.required_found !== b.required_found) return b.required_found - a.required_found;
+    if (a.active_context_tokens !== b.active_context_tokens) return a.active_context_tokens - b.active_context_tokens;
+    return a.tool_schema_chars - b.tool_schema_chars;
+  });
+}
+
+export function listContextEvalFixtures() { return Object.keys(FIXTURES); }
+
+export async function evaluateContextFixture(options = {}) {
+  const name = options.fixture || 'exact-symbol-callers';
+  const fx = fixture(name);
+  const record = getModelRecord(options.model || 'gpt-6-astra');
+  if (!record) throw new Error(`unknown model: ${options.model}`);
+  const strategies = options.strategy && options.strategy !== 'all' ? [options.strategy] : STRATEGIES;
+  for (const strategy of strategies) if (!STRATEGIES.includes(strategy)) throw new Error(`unknown context strategy: ${strategy}`);
+  const results = [];
+  for (const strategy of strategies) results.push(await runStrategy(fx, strategy, record));
+  const ranked = rank(results);
+  return Object.freeze({
+    schema_version: 1,
+    fixture: name,
+    task: fx.task,
+    model: record.provider_model_id,
+    live_provider_used: false,
+    strategies: Object.freeze(results),
+    winner: ranked[0]?.strategy || null,
+    scoring: Object.freeze(['correctness', 'required_evidence', 'context_efficiency', 'tool_efficiency']),
+  });
+}

package/src/eval/index.js

@@ -0,0 +1 @@
+export { listContextEvalFixtures, evaluateContextFixture } from './context.js';

package/src/index.js

@@ -4,7 +4,7 @@ import pkg from '../package.json' with { type: 'json' };
 
 export { AgentSam } from './AgentSam.js';
 export { routeIntent } from './lib/router.js';
-export { searchToolCards, toToolCard } from './tools/index.js';
+export { searchToolCards, toToolCard, hydrateToolSchemas } from './tools/index.js';
 export { getToolCatalog } from './lib/tools.js';
 export { scaffoldProject } from './lib/scaffold.js';
 export {
@@ -44,17 +44,71 @@ export {
   DEFAULT_CONTEXT_RATIOS,
   DEFAULT_RESULT_POLICY,
   createContextBudget,
+  assessContextUsage,
   normalizeResultPolicy,
   resolveContext,
   resolveProjectContext,
   compactConsumedToolResult,
+  rehydrateContextRef,
   loadProjectRules,
+  compileAgentInstructions,
+  AGENT_INSTRUCTION_PRECEDENCE,
 } from './context/index.js';
 export {
   assertRepositoryKnowledgeProvider,
   createRepositoryKnowledgeClient,
   describeRepositoryKnowledgeProvider,
 } from './indexing/index.js';
+export {
+  MODEL_CATALOG_SCHEMA,
+  MODEL_CATALOG,
+  listModelCatalog,
+  getModelRecord,
+  calculateModelCost,
+} from './models/index.js';
+export {
+  AGENT_EVENT_TYPES,
+  RUNTIME_RECEIPT_SCHEMA_VERSION,
+  createAgentEvent,
+  createUsageSnapshot,
+  createRunReceipt,
+  createUsageReceipt,
+  createApprovalReceipt,
+  createTerminalJobReceipt,
+} from './telemetry/index.js';
+export {
+  createOpenAIResponsesAdapter,
+  extractOpenAIOutputText,
+  extractOpenAIFunctionCalls,
+} from './providers/index.js';
+export {
+  AgentSamDiagnosticError,
+  classifyOpenAIError,
+  createOpenAIHttpError,
+  createProcessDiagnosticError,
+  diagnosticFromError,
+  redactDiagnosticValue,
+  renderDiagnosticError,
+} from './errors/index.js';
+export {
+  WRANGLER_NATIVE_COMMANDS,
+  WRANGLER_OPERATION_FAMILIES,
+  buildWranglerInvocation,
+  listWranglerNativeCommands,
+  parseWranglerErrorEvidence,
+  runWranglerNative,
+  summarizeCloudflareCpuProfile,
+  summarizeCloudflareCpuProfileFile,
+  buildCloudflareCpuAuditPacket,
+  runCloudflareCpuAudit,
+} from './cloudflare/index.js';
+export {
+  createCapabilityAdapter,
+  buildAgentToolSurface,
+  capabilityFunctionName,
+  runResponsesAgent,
+} from './agent/index.js';
+export { listContextEvalFixtures, evaluateContextFixture } from './eval/index.js';
 
 export {
   createIdentityClient,

package/src/lib/account-session.js

@@ -0,0 +1,98 @@
+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';
+
+export const ACCOUNT_SESSION_SCHEMA = 'agentsam-account-session-v1';
+
+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());
+}
+
+export function accountSessionPath(options = {}) {
+  return path.join(homeDirectory(options), '.agentsam', 'auth', 'session.json');
+}
+
+export function readAccountSession(options = {}) {
+  const filename = accountSessionPath(options);
+  if (!fs.existsSync(filename)) return null;
+  try {
+    const stat = fs.statSync(filename);
+    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;
+    return {
+      schema_version: ACCOUNT_SESSION_SCHEMA,
+      sdk_key: token,
+      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,
+    };
+  } catch {
+    return null;
+  }
+}
+
+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 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 value = {
+    schema_version: ACCOUNT_SESSION_SCHEMA,
+    sdk_key: token,
+    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') {
+    try { fs.chmodSync(temp, 0o600); } catch { /* best effort */ }
+  }
+  fs.renameSync(temp, filename);
+  return { ...value };
+}
+
+export function clearAccountSession(options = {}) {
+  const filename = accountSessionPath(options);
+  if (!fs.existsSync(filename)) return false;
+  fs.rmSync(filename, { force: true });
+  return true;
+}
+
+export function resolveAccountSdkKey(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 };
+}
+
+export function describeAccountSession(options = {}) {
+  const resolved = resolveAccountSdkKey(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,
+  };
+}

package/src/lib/agent-instructions.js

@@ -0,0 +1,73 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { createHash } from 'node:crypto';
+import { findProjectRules } from './project-rules.js';
+
+export const AGENT_RUNTIME_FILENAME = 'AGENTSAM.md';
+export const AGENT_INSTRUCTION_PRECEDENCE = Object.freeze(['AGENTSAM.md', '.agentsamrules']);
+
+function sha256(value) {
+  return `sha256:${createHash('sha256').update(value).digest('hex')}`;
+}
+
+function findUp(startDir, filename) {
+  let dir = path.resolve(startDir);
+  for (let i = 0; i < 16; i += 1) {
+    const candidate = path.join(dir, filename);
+    if (fs.existsSync(candidate)) return candidate;
+    const boundary = fs.existsSync(path.join(dir, '.git')) || fs.existsSync(path.join(dir, '.agentsam', 'config.json'));
+    if (boundary) break;
+    const parent = path.dirname(dir);
+    if (parent === dir) break;
+    dir = parent;
+  }
+  return null;
+}
+
+export function findAgentRuntimeContract(startDir = process.cwd()) {
+  return findUp(startDir, AGENT_RUNTIME_FILENAME);
+}
+
+export function compileAgentInstructions(startDir = process.cwd(), options = {}) {
+  const maxChars = Number(options.maxChars ?? 24_000);
+  if (!Number.isInteger(maxChars) || maxChars < 1) throw new RangeError('agent instructions maxChars must be a positive integer');
+
+  const runtimePath = options.runtimeFilename ? path.resolve(options.runtimeFilename) : findAgentRuntimeContract(startDir);
+  const projectPath = options.projectFilename ? path.resolve(options.projectFilename) : findProjectRules(startDir);
+  const descriptors = [
+    { id: 'runtime', filename: AGENT_RUNTIME_FILENAME, path: runtimePath },
+    { id: 'project', filename: '.agentsamrules', path: projectPath },
+  ];
+  const sections = [];
+  const sources = [];
+  let sourceChars = 0;
+
+  for (const descriptor of descriptors) {
+    if (!descriptor.path || !fs.existsSync(descriptor.path)) continue;
+    const source = fs.readFileSync(descriptor.path, 'utf8');
+    sourceChars += source.length;
+    sources.push(Object.freeze({
+      id: descriptor.id,
+      filename: descriptor.filename,
+      path: descriptor.path,
+      chars: source.length,
+      hash: sha256(source),
+    }));
+    sections.push(`<!-- agentsam:${descriptor.id}:${descriptor.filename} -->\n${source.trim()}\n`);
+  }
+
+  const combined = sections.join('\n');
+  const truncated = combined.length > maxChars;
+  const content = truncated ? `${combined.slice(0, Math.max(0, maxChars - 1))}…` : combined;
+  return Object.freeze({
+    found: sources.length > 0,
+    path: projectPath || runtimePath || null,
+    content,
+    chars: content.length,
+    source_chars: sourceChars,
+    truncated,
+    hash: combined ? sha256(combined) : null,
+    precedence: AGENT_INSTRUCTION_PRECEDENCE,
+    sources: Object.freeze(sources),
+  });
+}

package/src/lib/auth.js

@@ -5,6 +5,7 @@ import http from 'node:http';
 import { randomBytes } from 'node:crypto';
 import { postJson } from './core-client.js';
 import { promptToOpenUrl } from './open-url.js';
+import { saveAccountSession } from './account-session.js';
 
 function randomState() {
   return randomBytes(16).toString('hex');
@@ -63,5 +64,8 @@ export async function authenticateViaBrowser() {
 
   const code = await codePromise;
   const session = await postJson('/api/sdk/auth/exchange', { code, state });
+  if (String(session?.access_token || '').trim().startsWith('sdk_')) {
+    saveAccountSession(session);
+  }
   return session;
 }

package/src/lib/cli-preferences.js

@@ -3,14 +3,12 @@ import path from 'node:path';
 import { spawnSync } from 'node:child_process';
 import { getProjectName, tryReadProjectConfig } from './project-config.js';
 
-export const CLI_PREFERENCES_SCHEMA = 'agentsam-cli-preferences-v1';
+export const CLI_PREFERENCES_SCHEMA = 'agentsam-cli-preferences-v2';
+export const LEGACY_CLI_PREFERENCES_SCHEMA = 'agentsam-cli-preferences-v1';
 
 function readJson(filename) {
-  try {
-    return JSON.parse(fs.readFileSync(filename, 'utf8'));
-  } catch {
-    return null;
-  }
+  try { return JSON.parse(fs.readFileSync(filename, 'utf8')); }
+  catch { return null; }
 }
 
 function gitValue(cwd, args) {
@@ -22,14 +20,9 @@ export function findCliProjectRoot(startDir = process.cwd()) {
   const cwd = path.resolve(startDir);
   const gitRoot = gitValue(cwd, ['rev-parse', '--show-toplevel']);
   if (gitRoot) return path.resolve(gitRoot);
-
   let dir = cwd;
   for (let i = 0; i < 16; i += 1) {
-    if (
-      fs.existsSync(path.join(dir, '.agentsam', 'cli.json')) ||
-      fs.existsSync(path.join(dir, '.agentsam', 'config.json')) ||
-      fs.existsSync(path.join(dir, 'package.json'))
-    ) return dir;
+    if (fs.existsSync(path.join(dir, '.agentsam', 'cli.json')) || fs.existsSync(path.join(dir, '.agentsam', 'config.json')) || fs.existsSync(path.join(dir, 'package.json'))) return dir;
     const parent = path.dirname(dir);
     if (parent === dir) break;
     dir = parent;
@@ -48,27 +41,38 @@ export function detectCliProject(startDir = process.cwd()) {
   return { root, project, branch, remote, website, configured: Boolean(getProjectName(config)) };
 }
 
-export function cliPreferencesPath(root) {
-  return path.join(path.resolve(root), '.agentsam', 'cli.json');
+export function cliPreferencesPath(root) { return path.join(path.resolve(root), '.agentsam', 'cli.json'); }
+
+function normalizePreferences(value = {}) {
+  return {
+    schemaVersion: CLI_PREFERENCES_SCHEMA,
+    trustedDirectory: value.trustedDirectory === true,
+    runtime: value.runtime || 'local',
+    terminal: value.terminal || '',
+    modelPreference: value.modelPreference || 'auto',
+    reasoningEffort: value.reasoningEffort || 'auto',
+    serviceTier: value.serviceTier || 'default',
+    modelAuthority: 'preference-only',
+    updatedAt: value.updatedAt || null,
+  };
 }
 
 export function readCliPreferences(root) {
   const value = readJson(cliPreferencesPath(root));
-  if (!value || value.schemaVersion !== CLI_PREFERENCES_SCHEMA) return null;
-  return value;
+  if (!value) return null;
+  if (value.schemaVersion !== CLI_PREFERENCES_SCHEMA && value.schemaVersion !== LEGACY_CLI_PREFERENCES_SCHEMA) return null;
+  return normalizePreferences(value);
 }
 
 export function writeCliPreferences(root, value = {}) {
   const filename = cliPreferencesPath(root);
   fs.mkdirSync(path.dirname(filename), { recursive: true });
-  const next = {
-    schemaVersion: CLI_PREFERENCES_SCHEMA,
-    runtime: value.runtime || 'local',
-    terminal: value.terminal || '',
-    modelPreference: value.modelPreference || 'auto',
-    modelAuthority: 'preference-only',
-    updatedAt: new Date().toISOString(),
-  };
+  const previous = readCliPreferences(root) || {};
+  const next = normalizePreferences({ ...previous, ...value, updatedAt: new Date().toISOString() });
   fs.writeFileSync(filename, `${JSON.stringify(next, null, 2)}\n`);
   return next;
 }
+
+export function updateCliPreferences(root, patch = {}) {
+  return writeCliPreferences(root, { ...(readCliPreferences(root) || {}), ...patch });
+}

package/src/lib/deploy/git-guard.js

@@ -0,0 +1,69 @@
+/**
+ * Production Wrangler deploys are allowed only from a clean main that matches origin/main.
+ * Dry-run / plan may run from a feature branch. Never from /private/tmp.
+ */
+import path from 'node:path';
+import { spawnSync } from 'node:child_process';
+
+const BLOCKED_BRANCH_PREFIXES = ['feat/', 'fix/', 'chore/', 'release/'];
+
+function git(cwd, args) {
+  const r = spawnSync('git', args, { cwd, encoding: 'utf8' });
+  return {
+    status: r.status,
+    stdout: String(r.stdout || '').trim(),
+    stderr: String(r.stderr || '').trim(),
+  };
+}
+
+export function inspectDeployGit(cwd = process.cwd()) {
+  const root = git(cwd, ['rev-parse', '--show-toplevel']);
+  const branch = git(cwd, ['rev-parse', '--abbrev-ref', 'HEAD']);
+  const head = git(cwd, ['rev-parse', 'HEAD']);
+  const origin = git(cwd, ['rev-parse', 'origin/main']);
+  const porcelain = git(cwd, ['status', '--porcelain']);
+  const detached = branch.stdout === 'HEAD';
+  const repoRoot = root.stdout || path.resolve(cwd);
+  return {
+    ok: root.status === 0,
+    repoRoot,
+    branch: branch.stdout,
+    detached,
+    head: head.stdout,
+    originMain: origin.stdout,
+    dirty: Boolean(porcelain.stdout),
+    tmpCheckout: repoRoot.includes('/private/tmp/') || repoRoot.includes('/tmp/'),
+  };
+}
+
+export function productionDeployBlockedReason(info) {
+  if (!info?.ok) return 'not a git checkout';
+  if (info.tmpCheckout) return 'refusing production deploy from a temporary checkout';
+  if (info.detached) return 'refusing production deploy from detached HEAD';
+  if (info.branch !== 'main') {
+    return `refusing production deploy from ${info.branch}; origin/main only`;
+  }
+  for (const prefix of BLOCKED_BRANCH_PREFIXES) {
+    if (info.branch.startsWith(prefix)) {
+      return `refusing production deploy from ${info.branch}`;
+    }
+  }
+  if (!info.originMain) return 'origin/main is missing; fetch before deploying';
+  if (info.head !== info.originMain) {
+    return `HEAD (${info.head.slice(0, 12)}) != origin/main (${info.originMain.slice(0, 12)})`;
+  }
+  if (info.dirty) return 'working tree is not clean';
+  return null;
+}
+
+export function assertProductionDeployAllowed(cwd = process.cwd()) {
+  const info = inspectDeployGit(cwd);
+  const reason = productionDeployBlockedReason(info);
+  if (reason) {
+    const err = new Error(reason);
+    err.code = 'production_deploy_refused';
+    err.git = info;
+    throw err;
+  }
+  return info;
+}