@inneranimalmedia/agentsam-sdk 2.4.1 → 2.5.0

package/src/context/resolve.js

@@ -0,0 +1,84 @@
+import { createContextBudget, estimateContextTokens } from './budget.js';
+import { loadProjectRules } from '../lib/project-rules.js';
+
+export const CONTEXT_ITEM_KINDS = Object.freeze(['file', 'symbol', 'memory', 'tool_result', 'repo', 'artifact']);
+
+function clean(value) { return value == null ? '' : String(value).trim(); }
+
+export function normalizeContextItem(value = {}) {
+  const ref = clean(value.ref);
+  if (!ref) throw new TypeError('ContextItem.ref is required');
+  const kind = clean(value.kind);
+  if (!CONTEXT_ITEM_KINDS.includes(kind)) throw new RangeError(`ContextItem.kind must be one of: ${CONTEXT_ITEM_KINDS.join(', ')}`);
+  const content = value.content == null ? '' : String(value.content);
+  const chars = Number.isInteger(value.chars) && value.chars >= 0 ? value.chars : content.length;
+  const priority = Number.isFinite(value.priority) ? Number(value.priority) : 0;
+  return Object.freeze({ ref, kind, chars, hash: clean(value.hash) || undefined, priority, content });
+}
+
+function capForKind(item, budget) {
+  if (item.kind === 'file') return budget.maxFileCharsPerRead;
+  if (item.kind === 'tool_result') return budget.maxToolResultChars;
+  return budget.maxEvidenceChars;
+}
+
+function truncate(content, maxChars) {
+  if (content.length <= maxChars) return { content, truncated: false };
+  return { content: `${content.slice(0, Math.max(0, maxChars - 1))}…`, truncated: true };
+}
+
+export function resolveContext(options = {}) {
+  const objective = clean(options.objective);
+  if (!objective) throw new TypeError('context.resolve objective is required');
+  const budget = options.budget?.windowTokens ? options.budget : createContextBudget(options.budget || {});
+  const refs = [...new Set((options.refs || []).map(clean).filter(Boolean))];
+  const candidates = (options.items || []).map((item, index) => ({ item: normalizeContextItem(item), index }));
+  candidates.sort((a, b) => (b.item.priority - a.item.priority) || (a.index - b.index));
+
+  let evidenceChars = 0;
+  let fileChars = 0;
+  const included = [];
+  const deferred = [];
+
+  for (const row of candidates) {
+    const item = row.item;
+    const remainingEvidence = budget.maxEvidenceChars - evidenceChars;
+    if (remainingEvidence <= 0) { deferred.push(item.ref); continue; }
+    const kindCap = capForKind(item, budget);
+    const remainingFile = item.kind === 'file' ? budget.maxFileCharsPerTurn - fileChars : Number.POSITIVE_INFINITY;
+    const allowed = Math.floor(Math.min(kindCap, remainingEvidence, remainingFile));
+    if (allowed <= 0) { deferred.push(item.ref); continue; }
+    const clipped = truncate(item.content, allowed);
+    const next = Object.freeze({ ...item, content: clipped.content, chars: clipped.content.length, truncated: clipped.truncated || item.chars > clipped.content.length });
+    included.push(next);
+    evidenceChars += next.chars;
+    if (item.kind === 'file') fileChars += next.chars;
+    if (clipped.truncated) deferred.push(`${item.ref}#remainder`);
+  }
+
+  const systemChars = options.rules?.content ? String(options.rules.content).length : 0;
+  const totalChars = systemChars + evidenceChars;
+  return Object.freeze({
+    objective,
+    refs: Object.freeze(refs),
+    rules: options.rules || null,
+    items: Object.freeze(included),
+    budget,
+    receipt: Object.freeze({
+      chars: totalChars,
+      evidence_chars: evidenceChars,
+      system_chars: systemChars,
+      estimated_tokens: estimateContextTokens(totalChars, budget.charsPerToken),
+      sources_considered: candidates.length,
+      sources_included: included.length,
+      sources_deferred: deferred.length,
+      deferred_refs: Object.freeze(deferred),
+    }),
+  });
+}
+
+export function resolveProjectContext(options = {}) {
+  const budget = options.budget?.windowTokens ? options.budget : createContextBudget(options.budget || {});
+  const rules = loadProjectRules(options.cwd || process.cwd(), { maxChars: Math.min(24_000, budget.maxSystemChars) });
+  return resolveContext({ ...options, budget, rules });
+}

package/src/context/result-policy.js

@@ -0,0 +1,66 @@
+export const RESULT_DETAIL_ORDER = Object.freeze(['metadata', 'card', 'excerpt', 'range', 'full']);
+
+export const DEFAULT_RESULT_POLICY = Object.freeze({
+  max_items: 8,
+  max_chars: 24_000,
+  detail: 'excerpt',
+});
+
+function positiveInteger(value, label) {
+  if (!Number.isInteger(value) || value < 1) throw new RangeError(`${label} must be a positive integer`);
+  return value;
+}
+
+function detailRank(value) {
+  const index = RESULT_DETAIL_ORDER.indexOf(value);
+  if (index === -1) throw new RangeError(`detail must be one of: ${RESULT_DETAIL_ORDER.join(', ')}`);
+  return index;
+}
+
+export function normalizeResultPolicy(value = {}, options = {}) {
+  const ceiling = { ...DEFAULT_RESULT_POLICY, ...(options.ceiling || {}) };
+  const requested = {
+    max_items: positiveInteger(value.max_items ?? ceiling.max_items, 'max_items'),
+    max_chars: positiveInteger(value.max_chars ?? ceiling.max_chars, 'max_chars'),
+    detail: value.detail ?? ceiling.detail,
+  };
+  detailRank(requested.detail);
+  detailRank(ceiling.detail);
+
+  const higherDetailOperation = options.operation === 'higher-detail';
+  if (!higherDetailOperation) {
+    if (requested.max_items > ceiling.max_items) throw new RangeError('result_policy_higher_detail_required:max_items');
+    if (requested.max_chars > ceiling.max_chars) throw new RangeError('result_policy_higher_detail_required:max_chars');
+    if (detailRank(requested.detail) > detailRank(ceiling.detail)) throw new RangeError('result_policy_higher_detail_required:detail');
+  }
+  return Object.freeze(requested);
+}
+
+export function truncateResultText(value, maxChars = DEFAULT_RESULT_POLICY.max_chars) {
+  const text = String(value ?? '');
+  positiveInteger(maxChars, 'maxChars');
+  if (text.length <= maxChars) return Object.freeze({ text, chars: text.length, source_chars: text.length, truncated: false });
+  const bounded = `${text.slice(0, Math.max(0, maxChars - 1))}…`;
+  return Object.freeze({ text: bounded, chars: bounded.length, source_chars: text.length, truncated: true });
+}
+
+export function boundResultItems(items = [], requested = {}, options = {}) {
+  if (!Array.isArray(items)) throw new TypeError('items must be an array');
+  const policy = normalizeResultPolicy(requested, options);
+  const selected = items.slice(0, policy.max_items);
+  const serialized = JSON.stringify(selected);
+  const bounded = truncateResultText(serialized, policy.max_chars);
+  return Object.freeze({
+    items: Object.freeze(selected),
+    policy,
+    receipt: Object.freeze({
+      source_items: items.length,
+      returned_items: selected.length,
+      omitted_items: Math.max(0, items.length - selected.length),
+      serialized_chars: serialized.length,
+      max_chars: policy.max_chars,
+      detail: policy.detail,
+      serialized_overflow: bounded.truncated,
+    }),
+  });
+}

package/src/index.js

@@ -4,6 +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 { getToolCatalog } from './lib/tools.js';
 export { scaffoldProject } from './lib/scaffold.js';
 export {
@@ -39,6 +40,21 @@ export {
   repositorySnapshot,
 } from './capabilities/index.js';
 export { getPreset, listPresets, resolvePreset, getAddon, listAddons } from './presets/index.js';
+export {
+  DEFAULT_CONTEXT_RATIOS,
+  DEFAULT_RESULT_POLICY,
+  createContextBudget,
+  normalizeResultPolicy,
+  resolveContext,
+  resolveProjectContext,
+  compactConsumedToolResult,
+  loadProjectRules,
+} from './context/index.js';
+export {
+  assertRepositoryKnowledgeProvider,
+  createRepositoryKnowledgeClient,
+  describeRepositoryKnowledgeProvider,
+} from './indexing/index.js';
 
 export {
   createIdentityClient,

package/src/indexing/execution-boundary.js

@@ -0,0 +1,144 @@
+import { builtinModules } from 'node:module';
+
+const NODE_BUILTINS = new Set(builtinModules.flatMap((name) => [name, name.replace(/^node:/, '')]));
+const SERVER_PACKAGES = new Set([
+  'pg', 'postgres', 'mysql', 'mysql2', 'better-sqlite3', 'sqlite3', 'tedious', 'oracledb',
+]);
+const PUBLIC_ENV_PREFIX = /^(?:VITE_|NEXT_PUBLIC_|PUBLIC_|REACT_APP_)/;
+const SECRETISH_ENV = /(?:SECRET|TOKEN|PASSWORD|PASSWD|PRIVATE|CREDENTIAL|DATABASE_URL|API_KEY|ACCESS_KEY|CLIENT_SECRET|SIGNING_KEY|ENCRYPTION_KEY)/i;
+
+function packageRoot(specifier) {
+  if (!specifier || specifier.startsWith('.') || specifier.startsWith('/')) return null;
+  const clean = specifier.replace(/^node:/, '');
+  if (clean.startsWith('@')) return clean.split('/').slice(0, 2).join('/');
+  return clean.split('/')[0];
+}
+
+function finding(kind, entry, extra = {}) {
+  return {
+    kind,
+    severity: 'high',
+    source: entry.path,
+    source_hash: entry.hash,
+    execution_domain: entry.execution_domain,
+    ...extra,
+  };
+}
+
+export function repairSuggestionForBoundaryFinding(item) {
+  const base = { finding: item.kind, automatic: false, evidence: { source: item.source, target: item.target || null } };
+  if (item.kind === 'browser-server-import') return {
+    ...base,
+    action: 'move-server-call-behind-api-boundary',
+    summary: 'Keep the browser-facing contract client-safe; move the privileged implementation behind a server/API boundary and call it over HTTP/RPC.',
+  };
+  if (item.kind === 'browser-server-runtime-import') return {
+    ...base,
+    action: 'move-server-dependency-out-of-browser-graph',
+    summary: `Move ${item.specifier} to server-owned code; expose only a bounded request/response contract to the browser.`,
+  };
+  if (item.kind === 'browser-private-env-access' || item.kind === 'browser-public-secret-name') return {
+    ...base,
+    action: 'move-secret-to-server-runtime',
+    summary: `Treat ${item.env} as server-owned. Browser code should receive only non-secret derived data from an authenticated server endpoint.`,
+  };
+  if (item.kind === 'shared-server-env') return {
+    ...base,
+    action: 'split-shared-contract-from-server-implementation',
+    summary: 'Keep shared code deterministic and secret-free; move server environment access into a server adapter and retain only types/schemas/contracts in shared.',
+  };
+  return { ...base, action: 'review-trust-boundary', summary: 'Review the client/server execution boundary using the attached AST/Merkle evidence.' };
+}
+
+export function analyzeExecutionBoundaries(semantic) {
+  if (!semantic || !Array.isArray(semantic.entries)) throw new TypeError('agentsam-filemeta semantic metadata is required');
+  const byPath = new Map(semantic.entries.map((entry) => [entry.path, entry]));
+  const browserRoots = semantic.entries.filter((entry) => entry.type === 'file' && entry.execution_domain === 'browser');
+  const reachable = new Map();
+  const queue = browserRoots.map((entry) => ({ path: entry.path, root: entry.path }));
+  for (const item of queue) reachable.set(item.path, item.root);
+  const findings = [];
+  const dedupe = new Set();
+  const add = (item) => {
+    const key = JSON.stringify([item.kind, item.source, item.target || '', item.specifier || '', item.env || '']);
+    if (dedupe.has(key)) return;
+    dedupe.add(key);
+    findings.push({ ...item, repair: repairSuggestionForBoundaryFinding(item) });
+  };
+
+  for (let i = 0; i < queue.length; i++) {
+    const current = queue[i];
+    const entry = byPath.get(current.path);
+    if (!entry) continue;
+
+    for (const edge of entry.resolved_imports || []) {
+      if (!edge.target) continue;
+      const target = byPath.get(edge.target);
+      if (!target) continue;
+      if (target.execution_domain === 'server') {
+        add(finding('browser-server-import', entry, {
+          target: target.path,
+          target_hash: target.hash,
+          specifier: edge.specifier,
+          browser_root: current.root,
+        }));
+        continue;
+      }
+      if (target.execution_domain === 'framework') {
+        if (!reachable.has(target.path)) reachable.set(target.path, current.root);
+        continue;
+      }
+      if (!reachable.has(target.path)) {
+        reachable.set(target.path, current.root);
+        queue.push({ path: target.path, root: current.root });
+      }
+    }
+
+    for (const specifier of entry.imports || []) {
+      if (specifier.startsWith('.')) continue;
+      const root = packageRoot(specifier);
+      const normalized = specifier.replace(/^node:/, '');
+      if (NODE_BUILTINS.has(normalized) || SERVER_PACKAGES.has(root)) {
+        add(finding('browser-server-runtime-import', entry, { specifier, browser_root: current.root }));
+      }
+    }
+
+    for (const access of entry.env_accesses || []) {
+      const env = access.name;
+      const publicName = PUBLIC_ENV_PREFIX.test(env);
+      if (publicName && SECRETISH_ENV.test(env)) {
+        add(finding('browser-public-secret-name', entry, { env, env_source: access.source, browser_root: current.root }));
+      } else if (access.source === 'process.env' && !publicName) {
+        add(finding('browser-private-env-access', entry, { env, env_source: access.source, browser_root: current.root }));
+      }
+    }
+  }
+
+  for (const entry of semantic.entries) {
+    if (entry.execution_domain !== 'shared') continue;
+    for (const access of entry.env_accesses || []) {
+      if (access.source === 'process.env' || SECRETISH_ENV.test(access.name)) {
+        add(finding('shared-server-env', entry, { env: access.name, env_source: access.source }));
+      }
+    }
+  }
+
+  findings.sort((a, b) => [a.source, a.kind, a.target || '', a.specifier || '', a.env || ''].join('\0').localeCompare([b.source, b.kind, b.target || '', b.specifier || '', b.env || ''].join('\0')));
+  const astEntries = semantic.entries.filter((entry) => entry.ast?.indexed);
+  const parseErrors = astEntries.filter((entry) => Number(entry.ast?.parse_error_count || 0) > 0).map((entry) => entry.path);
+  return {
+    schema_version: 1,
+    analyzer: 'agentsam-execution-boundary',
+    metadata_root: semantic.rootHash || null,
+    classifier: semantic.classifier || null,
+    complete: parseErrors.length === 0,
+    status: parseErrors.length ? 'incomplete' : findings.length ? 'action-required' : 'clean',
+    ok: parseErrors.length === 0 && findings.length === 0,
+    browser_roots: browserRoots.length,
+    browser_reachable_files: reachable.size,
+    ast_files: astEntries.length,
+    parse_errors: parseErrors,
+    findings,
+    repair_suggestions: findings.map((item) => item.repair),
+  };
+}

package/src/indexing/index.js

@@ -0,0 +1,8 @@
+export {
+  REPOSITORY_KNOWLEDGE_PROVIDER_METHODS,
+  assertRepositoryKnowledgeProvider,
+  createRepositoryKnowledgeClient,
+  describeRepositoryKnowledgeProvider,
+} from './provider.js';
+
+export { analyzeExecutionBoundaries, repairSuggestionForBoundaryFinding } from './execution-boundary.js';

package/src/indexing/provider.js

@@ -0,0 +1,41 @@
+export const REPOSITORY_KNOWLEDGE_PROVIDER_METHODS = Object.freeze([
+  'status',
+  'refresh',
+  'findSymbol',
+  'graph',
+  'retrieve',
+  'snapshot',
+]);
+
+export function assertRepositoryKnowledgeProvider(provider) {
+  if (!provider || typeof provider !== 'object') throw new TypeError('RepositoryKnowledgeProvider must be an object');
+  for (const method of REPOSITORY_KNOWLEDGE_PROVIDER_METHODS) {
+    if (typeof provider[method] !== 'function') throw new TypeError(`RepositoryKnowledgeProvider.${method}() is required`);
+  }
+  return provider;
+}
+
+export function createRepositoryKnowledgeClient(provider) {
+  const impl = assertRepositoryKnowledgeProvider(provider);
+  const call = (method, input = {}) => Promise.resolve(impl[method](input));
+  return Object.freeze({
+    status: (input) => call('status', input),
+    refresh: (input) => call('refresh', input),
+    findSymbol: (input) => call('findSymbol', input),
+    graph: (input) => call('graph', input),
+    retrieve: (input) => call('retrieve', input),
+    snapshot: (input) => call('snapshot', input),
+  });
+}
+
+export function describeRepositoryKnowledgeProvider(capabilities = {}) {
+  return Object.freeze({
+    structure: capabilities.structure || 'unknown',
+    lexical: capabilities.lexical !== false,
+    semantic: Boolean(capabilities.semantic),
+    graph: Boolean(capabilities.graph),
+    history: Boolean(capabilities.history),
+    evidence: capabilities.evidence || 'unknown',
+    provider: capabilities.provider || 'custom',
+  });
+}

package/src/knowledge/config.js

@@ -50,9 +50,9 @@ export function validateConfig(input) {
   if (c.storage.driver === 'postgres' && !/^[A-Z_][A-Z0-9_]*$/.test(c.storage.connection_env || '')) throw new Error('Postgres requires a connection_env name, never a connection string in config.');
   return c;
 }
-export function defaultConfig({ include = ['.'], exclude = [], scope = 'default', target = 'local', dimensions = 768 } = {}) {
+export function defaultConfig({ include = ['.'], exclude = [], scope = 'default', target = 'local', dimensions = 768, repositoryId = '' } = {}) {
   if (!['local', 'production'].includes(target)) throw new Error('target must be local or production.');
-  return validateConfig({ version: 1, repository_id: randomUUID(),
+  return validateConfig({ version: 1, repository_id: String(repositoryId || '').trim() || randomUUID(),
     scope: { name: scope, include, exclude }, chunking: { max_chars: 4000 },
     embedding: { provider: 'gemini', model: 'gemini-embedding-2', revision: '1', dimensions, parameters: { task: 'code retrieval' } },
     storage: target === 'local' ? { driver: 'sqlite' } : { driver: 'postgres', connection_env: 'AGENTSAM_DATABASE_URL' } });

package/src/knowledge/context-pack.js

@@ -1,12 +1,23 @@
 export function createContextPack({ queryId, query, hits = [], diagnostics = {}, confidence = "unknown" }) {
   const normalizedHits = hits.map((hit) => Object.freeze({ stale: false, reasons: [], metadata: {}, ...hit }));
+  const estimatedTokens = estimateTokens(normalizedHits);
+  const chars = normalizedHits.reduce((sum, hit) => sum + String(hit.content || "").length, 0);
+  const considered = Number.isInteger(diagnostics.sources_considered) ? diagnostics.sources_considered : normalizedHits.length;
+  const deferred = Number.isInteger(diagnostics.sources_deferred) ? diagnostics.sources_deferred : Math.max(0, considered - normalizedHits.length);
   return Object.freeze({
     query_id: queryId,
     query,
     hits: normalizedHits,
-    estimated_tokens: estimateTokens(normalizedHits),
+    estimated_tokens: estimatedTokens,
     confidence,
     diagnostics: Object.freeze({ ...diagnostics }),
+    receipt: Object.freeze({
+      chars,
+      estimated_tokens: estimatedTokens,
+      sources_considered: considered,
+      sources_included: normalizedHits.length,
+      sources_deferred: deferred,
+    }),
   });
 }
 

package/src/knowledge/contracts.js

@@ -1,5 +1,7 @@
 /** Provider-neutral AgentSam Knowledge SDK contracts and validators. */
 
+import { normalizeResultPolicy } from '../context/result-policy.js';
+
 export const KNOWLEDGE_OPERATIONS = Object.freeze({
   RETRIEVE: "knowledge.retrieve",
   INDEX: "knowledge.index",
@@ -9,10 +11,13 @@ export function assertRetrievalQuery(value) {
   if (!value || typeof value !== "object") throw new TypeError("RetrievalQuery must be an object");
   if (!String(value.text || "").trim()) throw new TypeError("RetrievalQuery.text is required");
   if (value.workspace_id != null && !String(value.workspace_id).trim()) throw new TypeError("RetrievalQuery.workspace_id must be non-empty when present");
-  const topK = value.top_k ?? 12;
-  if (!Number.isInteger(topK) || topK < 1 || topK > 100) throw new RangeError("top_k must be 1..100");
-  if (!Number.isInteger(value.token_budget ?? 8000) || (value.token_budget ?? 8000) < 256) throw new RangeError("token_budget must be at least 256");
-  return { ...value, top_k: topK, token_budget: value.token_budget ?? 8000 };
+  const resultPolicy = normalizeResultPolicy(value.result_policy || {});
+  const topK = value.top_k ?? resultPolicy.max_items;
+  if (!Number.isInteger(topK) || topK < 1 || topK > resultPolicy.max_items) throw new RangeError(`top_k must be 1..${resultPolicy.max_items} under the active result policy`);
+  const defaultTokenBudget = Math.max(256, Math.floor(resultPolicy.max_chars / 4));
+  const tokenBudget = value.token_budget ?? defaultTokenBudget;
+  if (!Number.isInteger(tokenBudget) || tokenBudget < 256 || tokenBudget > defaultTokenBudget) throw new RangeError(`token_budget must be 256..${defaultTokenBudget} under the active result policy`);
+  return { ...value, result_policy: resultPolicy, top_k: topK, token_budget: tokenBudget };
 }
 
 export function assertContextPack(value) {

package/src/knowledge/engine.js

@@ -2,6 +2,7 @@ import { randomUUID } from 'node:crypto';
 import { validateConfig, fingerprint, scopeKey, cacheNamespace, gitEvidence } from './config.js';
 import { PARSER, inventory, readSource, parseSource } from './source.js';
 import { createContextPack } from './context-pack.js';
+import { normalizeResultPolicy } from '../context/result-policy.js';
 
 export const embeddingProfileId = profile => fingerprint({ ...profile, input_format: 'agentsam-code-content:1' });
 export function validateVector(vector, dimensions) {
@@ -72,10 +73,13 @@ export async function runIndex({ root, config, store, embedder, embed = false, m
   return { ...receipt, generation_id: generation.id, published: true };
 }
 
-export async function retrieve({ store, config: input, text, semantic = false, embedder, topK = 8, tokenBudget = 8000, generationId }) {
+export async function retrieve({ store, config: input, text, semantic = false, embedder, topK = 8, tokenBudget = 6000, generationId, resultPolicy: requestedResultPolicy }) {
   const config = validateConfig(input);
   if (typeof text !== 'string' || !text.trim()) throw new Error('A nonempty query is required.');
-  if (!Number.isInteger(topK) || topK < 1 || topK > 100 || !Number.isInteger(tokenBudget) || tokenBudget < 256) throw new Error('topK must be 1..100 and tokenBudget at least 256.');
+  const resultPolicy = normalizeResultPolicy(requestedResultPolicy || {});
+  if (!Number.isInteger(topK) || topK < 1 || topK > resultPolicy.max_items) throw new Error(`topK must be 1..${resultPolicy.max_items} under the active result policy.`);
+  const maxTokenBudget = Math.max(256, Math.floor(resultPolicy.max_chars / 4));
+  if (!Number.isInteger(tokenBudget) || tokenBudget < 256 || tokenBudget > maxTokenBudget) throw new Error(`tokenBudget must be 256..${maxTokenBudget} under the active result policy.`);
   const generation = generationId ? await store?.getGeneration(scopeKey(config), generationId) : await store?.active(scopeKey(config));
   if (!generation) throw new Error('No generation found for this repository/scope. Run agentsam index run.');
   let queryVector;
@@ -113,6 +117,6 @@ export async function retrieve({ store, config: input, text, semantic = false, e
       metadata: { generation_id: generation.id, symbol: hit.symbol, content_hash: hit.content_hash, freshness: 'working tree not checked' } }); estimatedTokens += tokens;
     if (hits.length === topK) break;
   }
-  return createContextPack({ queryId: randomUUID(), query: { text, top_k: topK, token_budget: tokenBudget }, hits,
+  return createContextPack({ queryId: randomUUID(), query: { text, top_k: topK, token_budget: tokenBudget, result_policy: resultPolicy }, hits,
     diagnostics: { generation_id: generation.id, source_hash: generation.source_hash, scope: generation.config.scope, mode: semantic ? 'semantic-exact' : 'lexical', freshness: 'snapshot; working tree not checked' } });
 }

package/src/knowledge/service/server.js

@@ -30,7 +30,7 @@ function normalizeRequest(body, repositories, allowEmbeddings) {
   };
   const request = { ...body, embed: body.embed ?? false, semantic: body.semantic ?? false,
     max_inputs: bounded('max_inputs', 100, 0, 1000), max_characters: bounded('max_characters', 200000, 0, 2000000),
-    top_k: bounded('top_k', 8, 1, 100), token_budget: bounded('token_budget', 8000, 256, 32000) };
+    top_k: bounded('top_k', 8, 1, 8), token_budget: bounded('token_budget', 6000, 256, 6000) };
   const config = structuredClone(repo.config);
   if (body.scope !== undefined) config.scope.name = body.scope;
   if (body.include !== undefined) config.scope.include = body.include;

package/src/lib/bridge-client.js

@@ -1,17 +1,19 @@
-const DEFAULT_BASE_URL = 'https://inneranimalmedia.com';
+import {
+  resolveBridgeKey as resolveContractBridgeKey,
+  resolveIamOrigin,
+} from '../../packages/identity/src/contracts/auth-config.js';
 
 function clean(value) {
   return value == null ? '' : String(value).trim();
 }
 
 export function resolveAgentSamBaseUrl(env = process.env, explicit = '') {
-  return clean(
-    explicit || env.AGENTSAM_BASE_URL || env.AGENTSAM_CORE_URL || env.IAM_CORE_URL || DEFAULT_BASE_URL,
-  ).replace(/\/$/, '');
+  const compatibilityBase = env?.AGENTSAM_BASE_URL || env?.AGENTSAM_CORE_URL || env?.IAM_CORE_URL || '';
+  return resolveIamOrigin(env, explicit || env?.IAM_ORIGIN || compatibilityBase);
 }
 
 export function resolveBridgeKey(env = process.env, explicit = '') {
-  return clean(explicit || env.AGENTSAM_BRIDGE_KEY);
+  return resolveContractBridgeKey(env, explicit);
 }
 
 /**

package/src/lib/cli-preferences.js

@@ -0,0 +1,74 @@
+import fs from 'node:fs';
+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';
+
+function readJson(filename) {
+  try {
+    return JSON.parse(fs.readFileSync(filename, 'utf8'));
+  } catch {
+    return null;
+  }
+}
+
+function gitValue(cwd, args) {
+  const result = spawnSync('git', args, { cwd, encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] });
+  return result.status === 0 ? String(result.stdout || '').trim() : '';
+}
+
+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;
+    const parent = path.dirname(dir);
+    if (parent === dir) break;
+    dir = parent;
+  }
+  return cwd;
+}
+
+export function detectCliProject(startDir = process.cwd()) {
+  const root = findCliProjectRoot(startDir);
+  const config = tryReadProjectConfig(root) || {};
+  const pkg = readJson(path.join(root, 'package.json')) || {};
+  const branch = gitValue(root, ['branch', '--show-current']);
+  const remote = gitValue(root, ['config', '--get', 'remote.origin.url']);
+  const project = String(getProjectName(config, pkg.name || path.basename(root)));
+  const website = String(pkg.homepage || '').trim();
+  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 readCliPreferences(root) {
+  const value = readJson(cliPreferencesPath(root));
+  if (!value || value.schemaVersion !== CLI_PREFERENCES_SCHEMA) return null;
+  return 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(),
+  };
+  fs.writeFileSync(filename, `${JSON.stringify(next, null, 2)}\n`);
+  return next;
+}

package/src/lib/core-client.js

@@ -1,16 +1,16 @@
+import { resolveIamOrigin } from '../../packages/identity/src/contracts/auth-config.js';
+
 /**
  * IAM CORE client — SDK is a delivery mechanism; intelligence lives server-side.
  *
- * Default base URL https://inneranimalmedia.com is CORRECT-AS-DESIGNED for
- * multi-tenant client serving (thin client → IAM CORE). Override with
- * IAM_CORE_URL / AGENTSAM_CORE_URL. Without a CORE backend, consumers get
- * scaffold/local CLI only.
+ * IAM_ORIGIN is the canonical platform authority/API origin. During the
+ * migration window IAM_CORE_URL / AGENTSAM_CORE_URL remain compatibility-only
+ * fallbacks. Without a CORE backend, consumers get scaffold/local CLI only.
  */
 
-const DEFAULT_CORE = 'https://inneranimalmedia.com';
-
-export function coreBaseUrl() {
-  return (process.env.IAM_CORE_URL || process.env.AGENTSAM_CORE_URL || DEFAULT_CORE).replace(/\/$/, '');
+export function coreBaseUrl(env = process.env) {
+  const explicit = env?.IAM_ORIGIN || env?.IAM_CORE_URL || env?.AGENTSAM_CORE_URL || '';
+  return resolveIamOrigin(env, explicit);
 }
 
 export async function postJson(path, body, token) {

package/src/lib/deploy-receipt/index.js

@@ -146,7 +146,7 @@ export async function captureDeployReceipt({
     }
   }
 
-  const tree = await buildMerkleTree(rootPath, { policy });
+  const tree = await buildMerkleTree(rootPath, { policy, semantic: true });
   await atomicJson(state.pendingSnapshot, tree);
 
   let diff = null;
@@ -163,7 +163,7 @@ export async function captureDeployReceipt({
   const receipt = {
     format: 'agentsam-deploy-merkle',
     version: 1,
-    engine: 'agentsam-merkle-v1',
+    engine: tree.semantic ? 'agentsam-merkle-v1+agentsam-filemeta-v1' : 'agentsam-merkle-v1',
     status: 'captured',
     project: project || path.basename(rootPath),
     repository: gitInfo.repository || null,
@@ -171,6 +171,9 @@ export async function captureDeployReceipt({
     git_branch: gitInfo.git_branch || null,
     captured_at: new Date().toISOString(),
     root_hash: tree.rootHash,
+    policy_hash: tree.policyHash || null,
+    metadata_root: tree.semantic?.rootHash || null,
+    classifier: tree.semantic?.classifier || null,
     previous_root_hash: baseline?.rootHash || null,
     has_baseline: Boolean(baseline),
     baseline_source: resolvedBaselineSource,