@inneranimalmedia/agentsam-sdk 2.4.1 → 2.6.0

package/src/errors/diagnostic.js

@@ -0,0 +1,160 @@
+const DEFAULT_MAX_DETAIL_CHARS = 12_000;
+const SECRET_KEY = /(?:authorization|api[-_]?key|access[-_]?token|refresh[-_]?token|password|secret|cookie|credential)/i;
+const SECRET_VALUE_PATTERNS = [
+  /\bBearer\s+[A-Za-z0-9._~+\/-]+=*/gi,
+  /\bsk-[A-Za-z0-9_-]{12,}\b/g,
+  /\bsdk_[A-Za-z0-9_-]{8,}\b/g,
+  /\bgh[pousr]_[A-Za-z0-9]{20,}\b/g,
+];
+
+function clean(value) { return value == null ? '' : String(value).trim(); }
+function bounded(value, maxChars = DEFAULT_MAX_DETAIL_CHARS) {
+  const text = String(value ?? '');
+  if (text.length <= maxChars) return text;
+  return `${text.slice(0, Math.max(0, maxChars - 1))}…`;
+}
+
+function redactString(value, maxChars) {
+  let text = bounded(value, maxChars);
+  for (const pattern of SECRET_VALUE_PATTERNS) text = text.replace(pattern, '[REDACTED]');
+  return text;
+}
+
+export function redactDiagnosticValue(value, options = {}, depth = 0, key = '') {
+  const maxChars = Number.isInteger(options.maxChars) && options.maxChars > 0 ? options.maxChars : DEFAULT_MAX_DETAIL_CHARS;
+  if (SECRET_KEY.test(key)) return '[REDACTED]';
+  if (depth > 6) return '[TRUNCATED_DEPTH]';
+  if (value == null || typeof value === 'number' || typeof value === 'boolean') return value;
+  if (typeof value === 'string') return redactString(value, maxChars);
+  if (Array.isArray(value)) return value.slice(0, 50).map((item) => redactDiagnosticValue(item, options, depth + 1));
+  if (typeof value === 'object') {
+    const result = {};
+    for (const [childKey, childValue] of Object.entries(value).slice(0, 80)) {
+      result[childKey] = redactDiagnosticValue(childValue, options, depth + 1, childKey);
+    }
+    return result;
+  }
+  return redactString(String(value), maxChars);
+}
+
+function header(headers, name) {
+  if (!headers) return '';
+  if (typeof headers.get === 'function') return clean(headers.get(name));
+  const wanted = name.toLowerCase();
+  for (const [key, value] of Object.entries(headers)) if (String(key).toLowerCase() === wanted) return clean(value);
+  return '';
+}
+
+function retryAfterMs(headers) {
+  const value = header(headers, 'retry-after');
+  if (!value) return null;
+  if (/^\d+(?:\.\d+)?$/.test(value)) return Math.max(0, Math.round(Number(value) * 1000));
+  const when = Date.parse(value);
+  return Number.isFinite(when) ? Math.max(0, when - Date.now()) : null;
+}
+
+const OPENAI_NON_RETRY_CODES = new Set([
+  'credit_balance_exhausted',
+  'organization_spend_limit_exceeded',
+  'project_spend_limit_exceeded',
+  'organization_usage_limit_exceeded',
+]);
+
+export function classifyOpenAIError({ status, type, code, message, param } = {}) {
+  const httpStatus = Number(status || 0);
+  const normalizedType = clean(type).toLowerCase();
+  const normalizedCode = clean(code).toLowerCase();
+  const diagnosticText = `${normalizedCode} ${normalizedType} ${clean(param).toLowerCase()} ${clean(message).toLowerCase()}`;
+  if (normalizedCode === 'previous_response_not_found') return { category: 'continuation', retriable: true, retry_strategy: 'retry_full_context' };
+  if (normalizedCode === 'websocket_connection_limit_reached') return { category: 'connection_lifetime', retriable: true, retry_strategy: 'reconnect' };
+  if (OPENAI_NON_RETRY_CODES.has(normalizedCode)) return { category: 'billing_or_quota', retriable: false, retry_strategy: 'operator_action' };
+  if (httpStatus === 400 && /service[_ -]?tier/.test(diagnosticText)) return { category: 'service_tier', retriable: false, retry_strategy: 'change_configuration' };
+  if (httpStatus === 400) return { category: 'invalid_request', retriable: false, retry_strategy: 'change_request' };
+  if (httpStatus === 401) return { category: 'authentication', retriable: false, retry_strategy: 'fix_credentials' };
+  if (httpStatus === 403) return { category: 'authorization_or_region', retriable: false, retry_strategy: 'operator_action' };
+  if (httpStatus === 429 && normalizedCode === 'slow_down') return { category: 'ramp_rate', retriable: true, retry_strategy: 'retry_after_backoff' };
+  if (httpStatus === 429) return { category: 'rate_limit', retriable: true, retry_strategy: 'retry_after_backoff' };
+  if (httpStatus === 500) return { category: 'provider_server', retriable: true, retry_strategy: 'retry_backoff' };
+  if (httpStatus === 503 || normalizedCode === 'server_is_overloaded') return { category: 'provider_overload', retriable: true, retry_strategy: 'retry_after_backoff' };
+  return { category: 'provider_error', retriable: false, retry_strategy: 'inspect_error' };
+}
+
+export class AgentSamDiagnosticError extends Error {
+  constructor(diagnostic, options = {}) {
+    super(clean(diagnostic?.message) || clean(options.message) || 'AgentSam operation failed', options.cause ? { cause: options.cause } : undefined);
+    this.name = 'AgentSamDiagnosticError';
+    this.diagnostic = Object.freeze({ schema_version: 1, ...diagnostic });
+    this.code = diagnostic?.code || diagnostic?.kind || 'agentsam_error';
+    this.status = diagnostic?.http_status ?? diagnostic?.status ?? null;
+  }
+}
+
+export function createOpenAIHttpError({ status, body, headers, requestedServiceTier, rawText } = {}) {
+  const payload = body && typeof body === 'object' ? body : {};
+  const providerError = payload.error && typeof payload.error === 'object' ? payload.error : payload;
+  const type = clean(providerError.type) || null;
+  const code = clean(providerError.code) || null;
+  const message = clean(providerError.message || payload.message || rawText) || `OpenAI API returned HTTP ${status}`;
+  const classification = classifyOpenAIError({ status, type, code, message, param: providerError.param });
+  const diagnostic = {
+    source: 'openai',
+    kind: 'provider_http_error',
+    http_status: Number(status || 0) || null,
+    type,
+    code,
+    param: clean(providerError.param) || null,
+    message: redactString(message, 4_000),
+    category: classification.category,
+    retriable: classification.retriable,
+    retry_strategy: classification.retry_strategy,
+    retry_after_ms: retryAfterMs(headers),
+    request_id: header(headers, 'x-request-id') || header(headers, 'openai-request-id') || header(headers, 'request-id') || null,
+    ray_id: header(headers, 'cf-ray') || null,
+    requested_service_tier: clean(requestedServiceTier) || null,
+    details: redactDiagnosticValue(payload, { maxChars: DEFAULT_MAX_DETAIL_CHARS }),
+  };
+  return new AgentSamDiagnosticError(diagnostic);
+}
+
+export function createProcessDiagnosticError({ code, message, command, args, cwd, exitCode, signal, stderr, stdout, cause, retriable = false } = {}) {
+  return new AgentSamDiagnosticError({
+    source: 'process',
+    kind: 'process_error',
+    code: clean(code) || 'process_failed',
+    message: clean(message) || 'Process failed',
+    retriable: Boolean(retriable),
+    retry_strategy: retriable ? 'retry_after_inspection' : 'inspect_error',
+    command: clean(command) || null,
+    args: Array.isArray(args) ? args.slice(0, 64).map((value) => redactString(value, 1_000)) : [],
+    cwd: clean(cwd) || null,
+    exit_code: Number.isInteger(exitCode) ? exitCode : null,
+    signal: clean(signal) || null,
+    stderr: redactString(stderr || '', 12_000) || null,
+    stdout: redactString(stdout || '', 4_000) || null,
+  }, { cause });
+}
+
+export function diagnosticFromError(error, fallback = {}) {
+  if (error?.diagnostic) return error.diagnostic;
+  return Object.freeze({
+    schema_version: 1,
+    source: fallback.source || 'agentsam',
+    kind: fallback.kind || 'runtime_error',
+    code: clean(error?.code || fallback.code) || 'runtime_error',
+    message: redactString(error?.message || error || fallback.message || 'Unknown error', 4_000),
+    http_status: Number(error?.status || fallback.status || 0) || null,
+    retriable: Boolean(fallback.retriable),
+    retry_strategy: fallback.retry_strategy || 'inspect_error',
+  });
+}
+
+export function renderDiagnosticError(error) {
+  const d = diagnosticFromError(error);
+  const identity = [d.source, d.http_status ? `HTTP ${d.http_status}` : '', d.type, d.code].filter(Boolean).join(' · ');
+  const lines = [`✗ ${d.message}`, identity ? `  ${identity}` : ''];
+  if (d.request_id) lines.push(`  request_id: ${d.request_id}`);
+  if (d.ray_id) lines.push(`  ray_id: ${d.ray_id}`);
+  if (d.retry_after_ms != null) lines.push(`  retry_after_ms: ${d.retry_after_ms}`);
+  if (d.retry_strategy) lines.push(`  retry: ${d.retriable ? 'yes' : 'no'} · ${d.retry_strategy}`);
+  return lines.filter(Boolean).join('\n');
+}

package/src/errors/index.js

@@ -0,0 +1,9 @@
+export {
+  AgentSamDiagnosticError,
+  classifyOpenAIError,
+  createOpenAIHttpError,
+  createProcessDiagnosticError,
+  diagnosticFromError,
+  redactDiagnosticValue,
+  renderDiagnosticError,
+} from './diagnostic.js';

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,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, hydrateToolSchemas } from './tools/index.js';
 export { getToolCatalog } from './lib/tools.js';
 export { scaffoldProject } from './lib/scaffold.js';
 export {
@@ -39,6 +40,75 @@ export {
   repositorySnapshot,
 } from './capabilities/index.js';
 export { getPreset, listPresets, resolvePreset, getAddon, listAddons } from './presets/index.js';
+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/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' } });