@inneranimalmedia/agentsam-sdk 2.5.0 → 2.6.1

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,23 @@
+export {
+  ERROR_SCHEMA_VERSION,
+  ERROR_CODE,
+  ERROR_REASON,
+  GRPC_STATUS,
+  canonicalCodeFromHttpStatus,
+  canonicalCodeFromGrpcStatus,
+  defaultHttpStatusForCode,
+  grpcStatusForCode,
+  classifyCloudflareFailure,
+  classifyOAuthFailure,
+  createErrorEnvelope,
+} from './contract.js';
+
+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,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 {
@@ -19,7 +19,7 @@ export {
   normalizeGitRemote,
   resolveGitContext,
   tryResolveGitContext,
-} from './lib/git-context.js';
+} from '../packages/agentsam-repository/src/git-context.js';
 export {
   resolveAgentSamBaseUrl,
   resolveBridgeKey,
@@ -40,21 +40,87 @@ export {
   repositorySnapshot,
 } from './capabilities/index.js';
 export { getPreset, listPresets, resolvePreset, getAddon, listAddons } from './presets/index.js';
+export {
+  COMPANY_REPOSITORY_GRAPH_SCHEMA_VERSION,
+  REPOSITORY_STATUSES,
+  REPOSITORY_CONTRACT_TYPES,
+  REPOSITORY_CONTRACT_STATUSES,
+  REPOSITORY_DEPENDENCY_TYPES,
+  REPOSITORY_DEPENDENCY_CRITICALITIES,
+  REPOSITORY_FAILURE_POLICIES,
+  createRepositoryIdentity,
+  createRepositoryContract,
+  createRepositoryDependency,
+} from '../packages/agentsam-repository/src/contracts.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/knowledge/service/auth.js

@@ -0,0 +1,13 @@
+import { timingSafeEqual } from 'node:crypto';
+
+export function createBearerTokenVerifier(token) {
+  if (typeof token !== 'string' || token.length < 32 || token.length > 256) {
+    throw new Error('Service token must be 32..256 characters.');
+  }
+  const secret = Buffer.from(token);
+  return authorization => {
+    const raw = typeof authorization === 'string' ? authorization : '';
+    const provided = Buffer.from(raw.replace(/^Bearer /, ''));
+    return provided.length === secret.length && timingSafeEqual(provided, secret);
+  };
+}

package/src/knowledge/service/grpc-client.js

@@ -0,0 +1,115 @@
+import {
+  grpc,
+  KnowledgeServiceClient,
+  decodeJob,
+  decodeJobEvent,
+  decodeRepositoryList,
+  encodeGetJobRequest,
+  encodeSubmitRequest,
+  fromGrpcError,
+  knowledgePb,
+  metadataForToken,
+} from './grpc-codec.js';
+
+function normalizeTimeout(value, fallback) {
+  const timeout = value === undefined ? fallback : value;
+  if (timeout == null) return null;
+  if (!Number.isFinite(timeout) || timeout <= 0) throw new Error('timeoutMs must be a positive number or null.');
+  return timeout;
+}
+
+function validateJobId(id) {
+  if (typeof id !== 'string' || !/^[a-f0-9-]{36}$/.test(id)) throw new Error('Invalid job id.');
+  return id;
+}
+
+/** Node/native gRPC client. Keep this separate from the fetch-only Worker-safe client. */
+export function createKnowledgeGrpcClient({
+  target,
+  token,
+  timeoutMs = 15000,
+  credentials = grpc.credentials.createInsecure(),
+  clientOptions,
+} = {}) {
+  if (typeof target !== 'string' || !target.trim()) throw new Error('A gRPC target is required.');
+  if (!token) throw new Error('A service token is required.');
+  const client = new KnowledgeServiceClient(target.trim(), credentials, clientOptions);
+
+  const unary = (method, request, options = {}) => new Promise((resolve, reject) => {
+    const timeout = normalizeTimeout(options.timeoutMs, timeoutMs);
+    const callOptions = timeout == null ? {} : { deadline: new Date(Date.now() + timeout) };
+    client[method](request, metadataForToken(token), callOptions, (error, response) => {
+      if (error) reject(fromGrpcError(error));
+      else resolve(response);
+    });
+  });
+
+  async function repositories(options = {}) {
+    const response = await unary('listRepositories', new knowledgePb.ListRepositoriesRequest(), options);
+    return decodeRepositoryList(response);
+  }
+
+  async function submit(body, idempotencyKey, options = {}) {
+    const response = await unary('submitJob', encodeSubmitRequest(body, idempotencyKey), options);
+    return decodeJob(response);
+  }
+
+  async function job(id, options = {}) {
+    const response = await unary('getJob', encodeGetJobRequest(validateJobId(id)), options);
+    return decodeJob(response);
+  }
+
+  async function* watch(id, options = {}) {
+    validateJobId(id);
+    const timeout = normalizeTimeout(options.timeoutMs, null);
+    const callOptions = timeout == null ? {} : { deadline: new Date(Date.now() + timeout) };
+    const stream = client.watchJob(
+      encodeGetJobRequest(id, knowledgePb.WatchJobRequest),
+      metadataForToken(token),
+      callOptions,
+    );
+    const queue = [];
+    let done = false;
+    let failure = null;
+    let wake = null;
+    const notify = () => { const resolve = wake; wake = null; resolve?.(); };
+    const onData = event => { queue.push(decodeJobEvent(event)); notify(); };
+    const onEnd = () => { done = true; notify(); };
+    const onError = error => {
+      if (options.signal?.aborted && error?.code === grpc.status.CANCELLED) {
+        done = true;
+      } else {
+        failure = fromGrpcError(error);
+        done = true;
+      }
+      notify();
+    };
+    const onAbort = () => stream.cancel();
+    stream.on('data', onData);
+    stream.once('end', onEnd);
+    stream.once('error', onError);
+    options.signal?.addEventListener('abort', onAbort, { once: true });
+    if (options.signal?.aborted) onAbort();
+
+    try {
+      while (!done || queue.length) {
+        if (!queue.length) await new Promise(resolve => { wake = resolve; });
+        while (queue.length) yield queue.shift();
+        if (failure) throw failure;
+      }
+      if (failure) throw failure;
+    } finally {
+      options.signal?.removeEventListener('abort', onAbort);
+      stream.off('data', onData);
+      if (!done) stream.cancel();
+    }
+  }
+
+  return Object.freeze({
+    repositories,
+    submit,
+    job,
+    watch,
+    close() { client.close(); },
+  });
+}