@inneranimalmedia/agentsam-sdk 2.4.1 → 2.6.0

package/src/commands/skills.js

@@ -0,0 +1,66 @@
+import { getSkill, listSkills, loadSkill } from '../skills/index.js';
+
+function parse(argv = []) {
+  const out = { id: '', json: false, references: false };
+  for (const arg of argv) {
+    if (arg === '--json') out.json = true;
+    else if (arg === '--references' || arg === '--full') out.references = true;
+    else if (arg === '--help' || arg === '-h') out.help = true;
+    else if (arg.startsWith('-')) throw new Error(`Unknown skills option: ${arg}`);
+    else if (!out.id) out.id = arg;
+    else throw new Error('Only one skill id or alias may be supplied.');
+  }
+  return out;
+}
+
+function help() {
+  return [
+    'Agent Sam · skills',
+    '  agentsam skills                         list portable skills',
+    '  agentsam skills <id-or-alias>           print compact skill instructions',
+    '  agentsam skills <id-or-alias> --references  include on-demand references',
+    '  agentsam skills <id-or-alias> --json    machine-readable skill payload',
+    '',
+    'Examples:',
+    '  agentsam skills quick-bytes',
+    '  agentsam skills no-regress --references',
+    '',
+  ].join('\n');
+}
+
+export function runSkills(argv = []) {
+  const opts = parse(argv);
+  if (opts.help) {
+    process.stdout.write(help());
+    return null;
+  }
+
+  if (!opts.id) {
+    const skills = listSkills();
+    if (opts.json) process.stdout.write(`${JSON.stringify(skills, null, 2)}\n`);
+    else {
+      process.stdout.write('Agent Sam · portable skills\n\n');
+      for (const skill of skills) {
+        const aliases = (skill.aliases || []).length ? ` (${skill.aliases.join(', ')})` : '';
+        process.stdout.write(`  ${skill.id}${aliases}\n    ${skill.description}\n`);
+      }
+      process.stdout.write('\n');
+    }
+    return skills;
+  }
+
+  if (!getSkill(opts.id)) throw new Error(`Unknown skill: ${opts.id}`);
+  const loaded = loadSkill(opts.id, { references: opts.references });
+  if (opts.json) {
+    process.stdout.write(`${JSON.stringify(loaded, null, 2)}\n`);
+    return loaded;
+  }
+
+  process.stdout.write(`${loaded.instructions.trimEnd()}\n`);
+  if (loaded.references?.length) {
+    for (const reference of loaded.references) {
+      process.stdout.write(`\n---\nReference: ${reference.path}\n---\n\n${reference.content.trimEnd()}\n`);
+    }
+  }
+  return loaded;
+}

package/src/commands/start-local.js

@@ -50,7 +50,7 @@ export async function runStartLocal(opts = {}) {
   Project services:
     npm run dev          → local Agent Sam API http://127.0.0.1:${config?.dev_port ?? 8787}
     npm run db:status    → inspect local SQLite
-    npm run tui          → ANSI Agent Sam dashboard
+    npx agentsam          → enter Agent Sam
 
   Press Ctrl+C to stop.
   `);

package/src/commands/tunnel.js

@@ -7,6 +7,7 @@
 import { spawn, spawnSync } from 'node:child_process';
 import { authenticateViaBrowser } from '../lib/auth.js';
 import { postJson } from '../lib/core-client.js';
+import { resolveAccountSdkKey } from '../lib/account-session.js';
 
 const DEFAULT_PORT = 3099;
 
@@ -32,7 +33,7 @@ function parseArgs(argv) {
     else if (a === '--platform') opts.platform = argv[++i] || opts.platform;
     else if (a === '--shell') opts.shell = argv[++i] || opts.shell;
     else if (a === '--token' && argv[i + 1]) {
-      process.env.AGENTSAM_SDK_TOKEN = argv[++i];
+      process.env.AGENTSAM_SDK_KEY = argv[++i];
     }
   }
   return opts;
@@ -50,12 +51,12 @@ function ensureCloudflared() {
 }
 
 async function resolveToken() {
-  const existing = String(process.env.AGENTSAM_SDK_TOKEN || '').trim();
+  const existing = resolveAccountSdkKey({ env: process.env }).value;
   if (existing.startsWith('sdk_')) return existing;
   const session = await authenticateViaBrowser();
   const tok = String(session?.access_token || '').trim();
-  if (!tok.startsWith('sdk_')) throw new Error('IAM auth did not return an sdk_ bearer token');
-  process.env.AGENTSAM_SDK_TOKEN = tok;
+  if (!tok.startsWith('sdk_')) throw new Error('IAM auth did not return an sdk_ bearer key');
+  process.env.AGENTSAM_SDK_KEY = tok;
   return tok;
 }
 

package/src/commands/whoami.js

@@ -0,0 +1,86 @@
+import { getJson } from '../lib/core-client.js';
+import { resolveAccountSdkKey } from '../lib/account-session.js';
+import { listProviderCredentialStatus } from '../lib/provider-credentials.js';
+
+function writeLine(write, value = '') { write(`${value}\n`); }
+
+export async function collectWhoami(options = {}) {
+  const env = options.env || process.env;
+  const sdk = resolveAccountSdkKey({ env, explicit: options.token || '', home: options.home });
+  const token = sdk.value;
+  const credentials = listProviderCredentialStatus({ env, home: options.home });
+  if (!token) return {
+    schema_version: 1,
+    authenticated: false,
+    authority: 'iam',
+    identity: null,
+    sdk_credential: { configured: false, source: null },
+    provider_credentials: credentials,
+  };
+  try {
+    const loader = options.contextLoader || ((sdkKey) => getJson('/api/sdk/context', sdkKey));
+    const context = await loader(token);
+    return {
+      schema_version: 1,
+      authenticated: true,
+      authority: 'iam',
+      identity: {
+        user_id: context?.user_id || null,
+        account_id: context?.account_id || null,
+        email: context?.email || context?.user?.email || null,
+      },
+      sdk_credential: { configured: true, source: sdk.source, valid: true },
+      provider_credentials: credentials,
+      cloudflare_connected: context?.cloudflare?.ok === true,
+      byok: context?.byok && typeof context.byok === 'object'
+        ? Object.fromEntries(Object.entries(context.byok).map(([key, value]) => [key, { configured: value?.configured === true }]))
+        : {},
+    };
+  } catch (error) {
+    return {
+      schema_version: 1,
+      authenticated: false,
+      authority: 'iam',
+      identity: null,
+      sdk_credential: { configured: true, source: sdk.source, valid: false, error: error?.message || String(error) },
+      provider_credentials: credentials,
+    };
+  }
+}
+
+export function renderWhoami(status) {
+  const lines = ['', '  Agent Sam · whoami', ''];
+  if (status.authenticated) {
+    lines.push('  authenticated  yes');
+    lines.push(`  authority      ${status.authority}`);
+    if (status.identity?.email) lines.push(`  email          ${status.identity.email}`);
+    if (status.identity?.account_id) lines.push(`  account        ${status.identity.account_id}`);
+    if (status.identity?.user_id) lines.push(`  user           ${status.identity.user_id}`);
+  } else {
+    lines.push('  authenticated  no');
+    lines.push(`  SDK key        ${status.sdk_credential?.configured ? 'present but not validated' : 'not configured'}`);
+    if (status.sdk_credential?.error) lines.push(`  error          ${status.sdk_credential.error}`);
+  }
+  lines.push('');
+  lines.push('  Provider credentials');
+  for (const row of status.provider_credentials || []) {
+    const state = row.configured ? 'available' : row.error ? `blocked (${row.error})` : 'not configured';
+    const source = row.source ? ` · ${row.source}` : '';
+    lines.push(`  ${String(row.provider).padEnd(12)} ${state}${source}`);
+  }
+  lines.push('');
+  lines.push('  Secret values are never printed by whoami.');
+  lines.push('');
+  return lines.join('\n');
+}
+
+export async function runWhoami(argv = [], options = {}) {
+  const allowed = new Set(['--json']);
+  const unknown = argv.filter((arg) => !allowed.has(arg));
+  if (unknown.length) throw new Error(`unknown whoami option: ${unknown[0]}`);
+  const status = await collectWhoami(options);
+  const write = options.write || ((text) => process.stdout.write(text));
+  if (argv.includes('--json')) writeLine(write, JSON.stringify(status, null, 2));
+  else write(renderWhoami(status));
+  return status;
+}

package/src/context/budget.js

@@ -0,0 +1,120 @@
+export const DEFAULT_CONTEXT_RATIOS = Object.freeze({
+  targetInputRatio: 0.60,
+  hardInputRatio: 0.85,
+  charsPerToken: 4,
+});
+
+function ratio(value, label) {
+  if (typeof value !== 'number' || !Number.isFinite(value) || value <= 0 || value > 1) throw new RangeError(`${label} must be > 0 and <= 1`);
+  return value;
+}
+
+function positiveNumber(value, label) {
+  if (typeof value !== 'number' || !Number.isFinite(value) || value <= 0) throw new RangeError(`${label} must be positive`);
+  return value;
+}
+
+function positiveInteger(value, label) {
+  if (!Number.isInteger(value) || value < 1) throw new RangeError(`${label} must be a positive integer`);
+  return value;
+}
+
+function nullablePositiveInteger(value, label) {
+  if (value == null) return null;
+  return positiveInteger(value, label);
+}
+
+export function createContextBudget(options = {}) {
+  const windowTokens = positiveInteger(options.windowTokens, 'windowTokens');
+  const charsPerToken = positiveNumber(options.charsPerToken ?? DEFAULT_CONTEXT_RATIOS.charsPerToken, 'charsPerToken');
+  const targetInputRatio = ratio(
+    options.targetInputRatio ?? (options.targetInputTokens ? options.targetInputTokens / windowTokens : DEFAULT_CONTEXT_RATIOS.targetInputRatio),
+    'targetInputRatio',
+  );
+  const hardInputRatio = ratio(
+    options.hardInputRatio ?? options.hardWindowRatio ?? (options.hardInputTokens ? options.hardInputTokens / windowTokens : DEFAULT_CONTEXT_RATIOS.hardInputRatio),
+    'hardInputRatio',
+  );
+  if (targetInputRatio >= hardInputRatio) throw new RangeError('targetInputRatio must be lower than hardInputRatio');
+
+  const windowChars = Math.floor(windowTokens * charsPerToken);
+  const targetInputTokens = positiveInteger(options.targetInputTokens ?? Math.floor(windowTokens * targetInputRatio), 'targetInputTokens');
+  const hardInputTokens = positiveInteger(options.hardInputTokens ?? Math.floor(windowTokens * hardInputRatio), 'hardInputTokens');
+  if (targetInputTokens >= hardInputTokens) throw new RangeError('targetInputTokens must be lower than hardInputTokens');
+
+  const maxNormalInputTokens = positiveInteger(options.maxNormalInputTokens ?? hardInputTokens, 'maxNormalInputTokens');
+  if (maxNormalInputTokens > hardInputTokens) throw new RangeError('maxNormalInputTokens must not exceed hardInputTokens');
+  const compactAtTokens = positiveInteger(
+    options.compactAtTokens ?? Math.floor(targetInputTokens + ((maxNormalInputTokens - targetInputTokens) * 0.4)),
+    'compactAtTokens',
+  );
+  const interveneAtTokens = positiveInteger(
+    options.interveneAtTokens ?? Math.floor(targetInputTokens + ((maxNormalInputTokens - targetInputTokens) * 0.72)),
+    'interveneAtTokens',
+  );
+  if (!(targetInputTokens <= compactAtTokens && compactAtTokens <= interveneAtTokens && interveneAtTokens <= maxNormalInputTokens)) {
+    throw new RangeError('context policy must satisfy target <= compactAt <= interveneAt <= maxNormal');
+  }
+
+  const pricingThresholdTokens = nullablePositiveInteger(options.pricingThresholdTokens, 'pricingThresholdTokens');
+  const safetyMarginTokens = Number.isInteger(options.safetyMarginTokens) && options.safetyMarginTokens >= 0
+    ? options.safetyMarginTokens
+    : pricingThresholdTokens && pricingThresholdTokens > maxNormalInputTokens
+      ? pricingThresholdTokens - maxNormalInputTokens
+      : 0;
+  const targetInputChars = Math.floor(targetInputTokens * charsPerToken);
+  const hardInputChars = Math.floor(hardInputTokens * charsPerToken);
+
+  return Object.freeze({
+    windowTokens,
+    windowChars,
+    charsPerToken,
+    targetInputRatio,
+    hardInputRatio,
+    hardWindowRatio: hardInputRatio,
+    targetInputTokens,
+    compactAtTokens,
+    interveneAtTokens,
+    maxNormalInputTokens,
+    hardInputTokens,
+    pricingThresholdTokens,
+    safetyMarginTokens,
+    targetInputChars,
+    hardInputChars,
+    maxSystemChars: positiveInteger(options.maxSystemChars ?? Math.max(4_000, Math.min(60_000, Math.floor(windowChars * 0.05))), 'maxSystemChars'),
+    maxToolSchemaChars: positiveInteger(options.maxToolSchemaChars ?? Math.max(4_000, Math.min(40_000, Math.floor(windowChars * 0.04))), 'maxToolSchemaChars'),
+    maxEvidenceChars: positiveInteger(options.maxEvidenceChars ?? Math.max(8_000, Math.min(100_000, Math.floor(targetInputChars * 0.25))), 'maxEvidenceChars'),
+    maxFileCharsPerRead: positiveInteger(options.maxFileCharsPerRead ?? 32_768, 'maxFileCharsPerRead'),
+    maxFileCharsPerTurn: positiveInteger(options.maxFileCharsPerTurn ?? Math.max(32_768, Math.min(131_072, Math.floor(targetInputChars * 0.25))), 'maxFileCharsPerTurn'),
+    maxToolResultChars: positiveInteger(options.maxToolResultChars ?? 24_000, 'maxToolResultChars'),
+  });
+}
+
+export function estimateContextTokens(chars, charsPerToken = DEFAULT_CONTEXT_RATIOS.charsPerToken) {
+  if (!Number.isFinite(chars) || chars < 0) throw new RangeError('chars must be a non-negative number');
+  if (!Number.isFinite(charsPerToken) || charsPerToken <= 0) throw new RangeError('charsPerToken must be positive');
+  return Math.ceil(chars / charsPerToken);
+}
+
+export function assessContextUsage(tokens, budget) {
+  const inputTokens = Number(tokens);
+  if (!Number.isFinite(inputTokens) || inputTokens < 0) throw new RangeError('tokens must be a non-negative number');
+  if (!budget?.windowTokens) throw new TypeError('context budget is required');
+  let stage = 'normal';
+  if (inputTokens >= budget.hardInputTokens) stage = 'hard';
+  else if (inputTokens >= budget.maxNormalInputTokens) stage = 'max-normal';
+  else if (inputTokens >= budget.interveneAtTokens) stage = 'intervene';
+  else if (inputTokens >= budget.compactAtTokens) stage = 'compact';
+  else if (inputTokens >= budget.targetInputTokens) stage = 'target';
+  const pricingThresholdTokens = budget.pricingThresholdTokens ?? null;
+  return Object.freeze({
+    inputTokens: Math.ceil(inputTokens),
+    stage,
+    utilizationRatio: inputTokens / budget.windowTokens,
+    pricingThresholdTokens,
+    tokensUntilPricingThreshold: pricingThresholdTokens == null ? null : pricingThresholdTokens - Math.ceil(inputTokens),
+    pricingThresholdCrossed: pricingThresholdTokens == null ? false : inputTokens > pricingThresholdTokens,
+    shouldCompact: inputTokens >= budget.compactAtTokens,
+    shouldIntervene: inputTokens >= budget.interveneAtTokens,
+  });
+}

package/src/context/compact.js

@@ -0,0 +1,28 @@
+import { normalizeContextItem } from './resolve.js';
+
+export const DEFAULT_CONSUMED_CONTEXT_CHARS = 4_000;
+
+export function compactContextItem(value, options = {}) {
+  const item = normalizeContextItem(value);
+  const maxChars = Number(options.maxChars ?? DEFAULT_CONSUMED_CONTEXT_CHARS);
+  if (!Number.isInteger(maxChars) || maxChars < 1) throw new RangeError('compact maxChars must be a positive integer');
+  if (item.content.length <= maxChars) return Object.freeze({ ...item, compacted: false });
+  const content = `${item.content.slice(0, Math.max(0, maxChars - 1))}…`;
+  return Object.freeze({
+    ...item,
+    content,
+    chars: content.length,
+    compacted: true,
+    source_chars: item.content.length,
+  });
+}
+
+export function compactConsumedToolResult(value, options = {}) {
+  const ref = String(options.ref || value?.ref || 'tool_result:consumed').trim();
+  const hash = options.hash || value?.hash;
+  const priority = Number.isFinite(options.priority) ? options.priority : Number(value?.priority || 0);
+  const content = typeof value === 'string'
+    ? value
+    : String(value?.content ?? JSON.stringify(value?.content ?? value ?? null));
+  return compactContextItem({ ref, kind: 'tool_result', hash, priority, content }, options);
+}

package/src/context/index.js

@@ -0,0 +1,7 @@
+export { DEFAULT_CONTEXT_RATIOS, createContextBudget, estimateContextTokens, assessContextUsage } from './budget.js';
+export { DEFAULT_RESULT_POLICY, RESULT_DETAIL_ORDER, normalizeResultPolicy, truncateResultText, boundResultItems } from './result-policy.js';
+export { CONTEXT_ITEM_KINDS, normalizeContextItem, resolveContext, resolveProjectContext } from './resolve.js';
+export { PROJECT_RULES_FILENAME, DEFAULT_PROJECT_RULES_MAX_CHARS, defaultProjectRules, ensureProjectRules, findProjectRules, loadProjectRules } from '../lib/project-rules.js';
+export { AGENT_RUNTIME_FILENAME, AGENT_INSTRUCTION_PRECEDENCE, findAgentRuntimeContract, compileAgentInstructions } from '../lib/agent-instructions.js';
+export { DEFAULT_CONSUMED_CONTEXT_CHARS, compactContextItem, compactConsumedToolResult } from './compact.js';
+export { rehydrateContextRef } from './rehydrate.js';

package/src/context/rehydrate.js

@@ -0,0 +1,35 @@
+import { createHash } from 'node:crypto';
+import { normalizeContextItem } from './resolve.js';
+
+function sha256(value) { return `sha256:${createHash('sha256').update(String(value)).digest('hex')}`; }
+
+export async function rehydrateContextRef(ref, adapter, options = {}) {
+  const sourceRef = String(ref || '').trim();
+  if (!sourceRef) throw new TypeError('rehydrate ref is required');
+  const read = typeof adapter === 'function' ? adapter : adapter?.read?.bind(adapter);
+  if (typeof read !== 'function') throw new TypeError('rehydration adapter must provide read(ref, options)');
+  const maxChars = Number(options.maxChars ?? 64_000);
+  if (!Number.isInteger(maxChars) || maxChars < 1) throw new RangeError('rehydration maxChars must be a positive integer');
+
+  const raw = await read(sourceRef, { maxChars, signal: options.signal });
+  if (raw == null) throw new Error(`rehydration_source_not_found:${sourceRef}`);
+  const value = typeof raw === 'string' ? { content: raw } : raw;
+  const content = String(value.content ?? '');
+  const computedHash = sha256(content);
+  const expectedHash = String(options.expectedHash || value.hash || '').trim();
+  if (expectedHash && expectedHash.startsWith('sha256:') && expectedHash !== computedHash) {
+    throw new Error(`rehydration_hash_mismatch:${sourceRef}`);
+  }
+  const bounded = content.length > maxChars ? `${content.slice(0, Math.max(0, maxChars - 1))}…` : content;
+  const item = normalizeContextItem({
+    ref: sourceRef,
+    kind: options.kind || value.kind || 'artifact',
+    hash: expectedHash || computedHash,
+    priority: Number.isFinite(options.priority) ? options.priority : Number(value.priority || 0),
+    content: bounded,
+    chars: bounded.length,
+    truncated: bounded.length < content.length,
+    source_chars: content.length > bounded.length ? content.length : undefined,
+  });
+  return Object.freeze({ ...item, truncated: bounded.length < content.length });
+}

package/src/context/resolve.js

@@ -0,0 +1,116 @@
+import { assessContextUsage, createContextBudget, estimateContextTokens } from './budget.js';
+import { compileAgentInstructions } from '../lib/agent-instructions.js';
+
+export const CONTEXT_ITEM_KINDS = Object.freeze(['file', 'symbol', 'memory', 'tool_result', 'repo', 'artifact']);
+
+function clean(value) { return value == null ? '' : String(value).trim(); }
+function nonNegativeInteger(value) { return Number.isInteger(value) && value >= 0 ? value : 0; }
+
+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,
+    ...(value.truncated === true ? { truncated: true } : {}),
+    ...(value.compacted === true ? { compacted: true } : {}),
+    ...(Number.isInteger(value.source_chars) && value.source_chars >= chars ? { source_chars: value.source_chars } : {}),
+  });
+}
+
+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 selectedChars = 0;
+  let fileChars = 0;
+  const included = [];
+  const deferred = [];
+
+  for (const row of candidates) {
+    const item = row.item;
+    const remainingEvidence = budget.maxEvidenceChars - selectedChars;
+    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.truncated === true || item.chars > clipped.content.length });
+    included.push(next);
+    selectedChars += next.chars;
+    if (item.kind === 'file') fileChars += next.chars;
+    if (clipped.truncated) deferred.push(`${item.ref}#remainder`);
+  }
+
+  const ruleChars = options.rules?.content ? String(options.rules.content).length : 0;
+  const instructionChars = ruleChars + nonNegativeInteger(options.instructionChars);
+  const toolSchemaChars = nonNegativeInteger(options.toolSchemaChars);
+  const historyChars = nonNegativeInteger(options.historyChars);
+  const toolResultChars = included.filter((item) => item.kind === 'tool_result').reduce((sum, item) => sum + item.chars, 0);
+  const evidenceChars = selectedChars - toolResultChars;
+  const totalChars = instructionChars + toolSchemaChars + historyChars + evidenceChars + toolResultChars;
+  const estimatedInputTokens = estimateContextTokens(totalChars, budget.charsPerToken);
+  const pressure = assessContextUsage(estimatedInputTokens, budget);
+  const rehydratable = [...new Set(included.filter((item) => item.ref).map((item) => item.ref))];
+
+  return Object.freeze({
+    objective,
+    refs: Object.freeze(refs),
+    rules: options.rules || null,
+    items: Object.freeze(included),
+    budget,
+    receipt: Object.freeze({
+      chars: totalChars,
+      system_chars: instructionChars,
+      instruction_chars: instructionChars,
+      tool_schema_chars: toolSchemaChars,
+      history_chars: historyChars,
+      evidence_chars: evidenceChars,
+      tool_result_chars: toolResultChars,
+      estimated_tokens: estimatedInputTokens,
+      estimated_input_tokens: estimatedInputTokens,
+      window_tokens: budget.windowTokens,
+      utilization_ratio: pressure.utilizationRatio,
+      pricing_threshold_tokens: pressure.pricingThresholdTokens,
+      tokens_until_pricing_threshold: pressure.tokensUntilPricingThreshold,
+      pressure: pressure.stage,
+      estimate_kind: 'local',
+      sources_considered: candidates.length,
+      sources_included: included.length,
+      sources_deferred: deferred.length,
+      deferred_refs: Object.freeze(deferred),
+      rehydratable_refs: Object.freeze(rehydratable),
+    }),
+  });
+}
+
+export function resolveProjectContext(options = {}) {
+  const budget = options.budget?.windowTokens ? options.budget : createContextBudget(options.budget || {});
+  const rules = compileAgentInstructions(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,
+    }),
+  });
+}