@inneranimalmedia/agentsam-sdk 2.4.1 → 2.6.0

package/src/lib/project-rules.js

@@ -0,0 +1,68 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { createHash } from 'node:crypto';
+
+export const PROJECT_RULES_FILENAME = '.agentsamrules';
+export const DEFAULT_PROJECT_RULES_MAX_CHARS = 24_000;
+
+function sha256(value) {
+  return `sha256:${createHash('sha256').update(value).digest('hex')}`;
+}
+
+export function defaultProjectRules(projectName = 'this project') {
+  return `# Agent Sam project rules
+
+These instructions are committed with ${projectName} and apply when Agent Sam works in this repository.
+
+- Prefer repository evidence over assumptions.
+- Prefer structural lookup before semantic retrieval when an exact symbol or relationship can answer the question.
+- Keep retrieval bounded: metadata -> cards -> excerpt -> range -> full object only when required.
+- Keep secrets, account/runtime state, active runs, and machine-local preferences out of committed project configuration.
+- Treat Git as source-control authority and Merkle snapshots as filesystem evidence.
+- Run the smallest relevant validation before reporting a code change as complete.
+
+## Project-specific rules
+
+Add repository-specific conventions, commands, constraints, or architecture notes below this line.
+`;
+}
+
+export function ensureProjectRules(root, projectName = path.basename(path.resolve(root))) {
+  const filename = path.join(path.resolve(root), PROJECT_RULES_FILENAME);
+  if (fs.existsSync(filename)) return filename;
+  fs.writeFileSync(filename, defaultProjectRules(projectName), { encoding: 'utf8', flag: 'wx' });
+  return filename;
+}
+
+export function findProjectRules(startDir = process.cwd()) {
+  let dir = path.resolve(startDir);
+  for (let i = 0; i < 16; i += 1) {
+    const filename = path.join(dir, PROJECT_RULES_FILENAME);
+    if (fs.existsSync(filename)) return filename;
+    const projectBoundary = fs.existsSync(path.join(dir, '.git')) || fs.existsSync(path.join(dir, '.agentsam', 'config.json'));
+    if (projectBoundary) break;
+    const parent = path.dirname(dir);
+    if (parent === dir) break;
+    dir = parent;
+  }
+  return null;
+}
+
+export function loadProjectRules(startDir = process.cwd(), options = {}) {
+  const maxChars = Number(options.maxChars ?? DEFAULT_PROJECT_RULES_MAX_CHARS);
+  if (!Number.isInteger(maxChars) || maxChars < 1) throw new RangeError('project rules maxChars must be a positive integer');
+  const filename = options.filename ? path.resolve(options.filename) : findProjectRules(startDir);
+  if (!filename) return Object.freeze({ found: false, path: null, content: '', chars: 0, truncated: false, hash: null });
+  const source = fs.readFileSync(filename, 'utf8');
+  const truncated = source.length > maxChars;
+  const content = truncated ? `${source.slice(0, Math.max(0, maxChars - 1))}…` : source;
+  return Object.freeze({
+    found: true,
+    path: filename,
+    content,
+    chars: content.length,
+    source_chars: source.length,
+    truncated,
+    hash: sha256(source),
+  });
+}

package/src/lib/provider-credentials.js

@@ -0,0 +1,83 @@
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+
+const PROVIDER_CREDENTIALS = Object.freeze({
+  openai: Object.freeze({ env: 'OPENAI_API_KEY', files: ['openai.env'] }),
+  gemini: Object.freeze({ env: 'GEMINI_API_KEY', files: ['gemini.env'] }),
+  anthropic: Object.freeze({ env: 'ANTHROPIC_API_KEY', files: ['anthropic.env'] }),
+  grok: Object.freeze({ env: 'XAI_API_KEY', files: ['grok.env', 'xai.env'] }),
+  cloudflare: Object.freeze({ env: 'CLOUDFLARE_API_TOKEN', files: ['cloudflare.env'] }),
+});
+
+function clean(value) { return value == null ? '' : String(value).trim(); }
+
+function homeDirectory(options = {}) {
+  return path.resolve(clean(options.home) || clean(options.env?.HOME) || clean(options.env?.USERPROFILE) || os.homedir());
+}
+
+function parseEnvValue(source, variable) {
+  for (const rawLine of String(source || '').split(/\r?\n/)) {
+    const line = rawLine.trim();
+    if (!line || line.startsWith('#')) continue;
+    const match = line.match(/^(?:export\s+)?([A-Za-z_][A-Za-z0-9_]*)=(.*)$/);
+    if (!match || match[1] !== variable) continue;
+    let value = match[2].trim();
+    if ((value.startsWith('"') && value.endsWith('"')) || (value.startsWith("'") && value.endsWith("'"))) value = value.slice(1, -1);
+    return value;
+  }
+  return '';
+}
+
+function secureFile(filename) {
+  const stat = fs.statSync(filename);
+  if (!stat.isFile()) return { ok: false, error: 'not_a_file' };
+  if (process.platform !== 'win32' && (stat.mode & 0o077) !== 0) return { ok: false, error: 'permissions_too_open' };
+  return { ok: true, mode: stat.mode & 0o777 };
+}
+
+export function providerCredentialSpec(provider) {
+  const id = clean(provider).toLowerCase();
+  const spec = PROVIDER_CREDENTIALS[id];
+  return spec ? Object.freeze({ provider: id, ...spec }) : null;
+}
+
+export function resolveProviderCredential(provider, options = {}) {
+  const spec = providerCredentialSpec(provider);
+  if (!spec) return Object.freeze({ provider: clean(provider).toLowerCase(), configured: false, source: null, error: 'unsupported_provider', value: '' });
+  const env = options.env || process.env;
+  const fromEnv = clean(env?.[spec.env]);
+  if (fromEnv) return Object.freeze({ provider: spec.provider, configured: true, source: 'environment', env: spec.env, file: null, error: null, value: fromEnv });
+
+  const dir = path.join(homeDirectory({ ...options, env }), '.agentsam', 'env.d');
+  for (const basename of spec.files) {
+    const filename = path.join(dir, basename);
+    if (!fs.existsSync(filename)) continue;
+    try {
+      const safety = secureFile(filename);
+      if (!safety.ok) return Object.freeze({ provider: spec.provider, configured: false, source: 'agentsam_env_file', env: spec.env, file: filename, error: safety.error, value: '' });
+      const value = clean(parseEnvValue(fs.readFileSync(filename, 'utf8'), spec.env));
+      if (value) return Object.freeze({ provider: spec.provider, configured: true, source: 'agentsam_env_file', env: spec.env, file: filename, error: null, value });
+      return Object.freeze({ provider: spec.provider, configured: false, source: 'agentsam_env_file', env: spec.env, file: filename, error: 'credential_variable_missing', value: '' });
+    } catch (error) {
+      return Object.freeze({ provider: spec.provider, configured: false, source: 'agentsam_env_file', env: spec.env, file: filename, error: error?.message || String(error), value: '' });
+    }
+  }
+  return Object.freeze({ provider: spec.provider, configured: false, source: null, env: spec.env, file: null, error: null, value: '' });
+}
+
+export function describeProviderCredential(provider, options = {}) {
+  const resolved = resolveProviderCredential(provider, options);
+  return Object.freeze({
+    provider: resolved.provider,
+    configured: resolved.configured,
+    source: resolved.source,
+    env: resolved.env || null,
+    file: resolved.file || null,
+    error: resolved.error || null,
+  });
+}
+
+export function listProviderCredentialStatus(options = {}) {
+  return Object.freeze(Object.keys(PROVIDER_CREDENTIALS).map((provider) => describeProviderCredential(provider, options)));
+}

package/src/lib/save-sdk-token.js

@@ -11,7 +11,7 @@ export function saveSdkTokenHint(cwd, token) {
   fs.mkdirSync(dir, { recursive: true });
   const hintPath = path.join(dir, 'credentials.env.example');
   const content = `# Agent Sam SDK — add to your shell profile (optional)
-export AGENTSAM_SDK_TOKEN=${t}
+export AGENTSAM_SDK_KEY=${t}
 export USER_GCP_PROJECT=YOUR_GCP_PROJECT_ID
 `;
   fs.writeFileSync(hintPath, content, 'utf8');

package/src/lib/scaffold/templates/worker-api/index.js

@@ -2,31 +2,36 @@
  * Worker API template generator.
  */
 
-export function workerApiTemplates({ projectName, routes, cfAccountId }) {
+export function workerApiTemplates({ projectName, routes, cfAccountId, dbKind = 'd1' }) {
   const files = {};
 
+  const pkgScripts = {
+    deploy: 'wrangler deploy',
+    dev: 'wrangler dev',
+    ...(dbKind === 'hyperdrive'
+      ? { 'db:migrate': 'psql "$DATABASE_URL" -f migrations/001_init.sql' }
+      : { 'db:migrate': `wrangler d1 execute ${projectName} --file=migrations/001_init.sql --remote` }),
+  };
+
   files['package.json'] = JSON.stringify({
     name: projectName,
     version: '0.1.0',
     private: true,
-    scripts: {
-      deploy: 'wrangler deploy',
-      dev: 'wrangler dev',
-      'db:migrate': `wrangler d1 execute ${projectName} --file=migrations/001_init.sql --remote`,
-    },
+    scripts: pkgScripts,
     devDependencies: { wrangler: '^3.0.0' },
+    ...(dbKind === 'hyperdrive' ? { dependencies: { postgres: '^3.4.0' } } : {}),
   }, null, 2);
 
+  const dbBindingBlock = dbKind === 'hyperdrive'
+    ? `[[hyperdrive]]\nbinding = "HYPERDRIVE"\nid = "REPLACE_WITH_YOUR_HYPERDRIVE_ID"\n`
+    : `[[d1_databases]]\nbinding = "DB"\ndatabase_name = "${projectName}"\ndatabase_id = "REPLACE_WITH_YOUR_D1_ID"\n`;
+
   files['wrangler.toml'] = `name = "${projectName}"
 main = "src/index.js"
 compatibility_date = "2024-01-01"
 account_id = "${cfAccountId}"
-
-[[d1_databases]]
-binding = "DB"
-database_name = "${projectName}"
-database_id = "REPLACE_WITH_YOUR_D1_ID"
-`;
+${dbKind === 'hyperdrive' ? 'compatibility_flags = ["nodejs_compat"]\n' : ''}
+${dbBindingBlock}`;
 
   // Entry
   const routeImports = routes.map(r => `import { handle${cap(r)} } from './routes/${r}.js';`).join('\n');
@@ -83,6 +88,37 @@ ${routeMatches}
   }
 
   if (routes.includes('users')) {
+    if (dbKind === 'hyperdrive') {
+    files['src/routes/users.js'] = `import postgres from 'postgres';
+
+export async function handleUsers(request, env) {
+  const sql = postgres(env.HYPERDRIVE.connectionString);
+  const url = new URL(request.url);
+  const id = url.pathname.replace('/users/', '').replace('/users', '') || null;
+
+  if (request.method === 'GET' && !id) {
+    const rows = await sql\`SELECT * FROM users LIMIT 50\`;
+    return Response.json(rows);
+  }
+  if (request.method === 'GET' && id) {
+    const rows = await sql\`SELECT * FROM users WHERE id = \${id}\`;
+    if (!rows[0]) return Response.json({ error: 'Not found' }, { status: 404 });
+    return Response.json(rows[0]);
+  }
+  if (request.method === 'POST') {
+    const body = await request.json();
+    const newId = crypto.randomUUID();
+    await sql\`INSERT INTO users (id, email) VALUES (\${newId}, \${body.email})\`;
+    return Response.json({ id: newId }, { status: 201 });
+  }
+  if (request.method === 'DELETE' && id) {
+    await sql\`DELETE FROM users WHERE id = \${id}\`;
+    return Response.json({ ok: true });
+  }
+  return Response.json({ error: 'Method not allowed' }, { status: 405 });
+}
+`;
+    } else {
     files['src/routes/users.js'] = `export async function handleUsers(request, env) {
   const url = new URL(request.url);
   const id = url.pathname.replace('/users/', '').replace('/users', '') || null;
@@ -109,9 +145,38 @@ ${routeMatches}
   return Response.json({ error: 'Method not allowed' }, { status: 405 });
 }
 `;
+    }
   }
 
   if (routes.includes('content')) {
+    if (dbKind === 'hyperdrive') {
+    files['src/routes/content.js'] = `import postgres from 'postgres';
+
+export async function handleContent(request, env) {
+  const sql = postgres(env.HYPERDRIVE.connectionString);
+  const url = new URL(request.url);
+  const slug = url.pathname.replace('/content/', '').replace('/content', '') || null;
+
+  if (request.method === 'GET' && !slug) {
+    const rows = await sql\`SELECT id, slug, title, status FROM cms_pages LIMIT 50\`;
+    return Response.json(rows);
+  }
+  if (request.method === 'GET' && slug) {
+    const rows = await sql\`SELECT * FROM cms_pages WHERE slug = \${slug}\`;
+    if (!rows[0]) return Response.json({ error: 'Not found' }, { status: 404 });
+    return Response.json(rows[0]);
+  }
+  if (request.method === 'POST') {
+    const body = await request.json();
+    const id = crypto.randomUUID();
+    await sql\`INSERT INTO cms_pages (id, slug, title, template, content_json)
+      VALUES (\${id}, \${body.slug}, \${body.title}, \${body.template ?? 'default'}, \${JSON.stringify(body.content ?? {})})\`;
+    return Response.json({ id }, { status: 201 });
+  }
+  return Response.json({ error: 'Method not allowed' }, { status: 405 });
+}
+`;
+    } else {
     files['src/routes/content.js'] = `export async function handleContent(request, env) {
   const url = new URL(request.url);
   const slug = url.pathname.replace('/content/', '').replace('/content', '') || null;
@@ -136,6 +201,7 @@ ${routeMatches}
   return Response.json({ error: 'Method not allowed' }, { status: 405 });
 }
 `;
+    }
   }
 
   if (routes.includes('webhook')) {
@@ -154,13 +220,17 @@ ${routeMatches}
 `;
   }
 
-  // Migration
+  // Migration — column syntax differs: SQLite (D1) uses INTEGER/unixepoch(), Postgres uses TIMESTAMPTZ/NOW()
+  const createdAtCol = dbKind === 'hyperdrive'
+    ? 'created_at TIMESTAMPTZ NOT NULL DEFAULT NOW()'
+    : 'created_at INTEGER NOT NULL DEFAULT (unixepoch())';
+
   let sql = `-- ${projectName} initial schema\n\n`;
   if (routes.includes('users')) {
     sql += `CREATE TABLE IF NOT EXISTS users (
   id TEXT PRIMARY KEY,
   email TEXT NOT NULL UNIQUE,
-  created_at INTEGER NOT NULL DEFAULT (unixepoch())
+  ${createdAtCol}
 );\n\n`;
   }
   if (routes.includes('content')) {
@@ -171,12 +241,23 @@ ${routeMatches}
   template TEXT NOT NULL DEFAULT 'default',
   content_json TEXT,
   status TEXT NOT NULL DEFAULT 'draft',
-  created_at INTEGER NOT NULL DEFAULT (unixepoch())
+  ${createdAtCol}
 );\n\n`;
   }
 
   files['migrations/001_init.sql'] = sql;
 
+  const deploySteps = dbKind === 'hyperdrive'
+    ? `npm install
+npx wrangler hyperdrive create ${projectName} --connection-string="postgres://user:pass@host:5432/db"
+# paste the returned Hyperdrive id into wrangler.toml as HYPERDRIVE binding
+npx wrangler deploy`
+    : `npm install
+npx wrangler d1 create ${projectName}
+# paste database_id into wrangler.toml
+npx wrangler d1 execute ${projectName} --file=migrations/001_init.sql --remote
+npx wrangler deploy`;
+
   files['README.md'] = `# ${projectName}
 
 Scaffolded by [@inneranimalmedia/agentsam-sdk](https://github.com/SamPrimeaux/agentsam-sdk).
@@ -185,14 +266,14 @@ Scaffolded by [@inneranimalmedia/agentsam-sdk](https://github.com/SamPrimeaux/ag
 
 ${routes.map(r => `- \`/${r}\``).join('\n')}
 
+## Database
+
+${dbKind === 'hyperdrive' ? 'Your own Postgres, via Cloudflare Hyperdrive.' : 'Cloudflare D1 (SQLite).'}
+
 ## Deploy
 
 \`\`\`bash
-npm install
-npx wrangler d1 create ${projectName}
-# paste database_id into wrangler.toml
-npx wrangler d1 execute ${projectName} --file=migrations/001_init.sql --remote
-npx wrangler deploy
+${deploySteps}
 \`\`\`
 `;
 

package/src/lib/scaffold/wizards/worker-api.js

@@ -5,6 +5,7 @@
 
 import {
   text,
+  select,
   multiselect,
   confirm,
   spinner,
@@ -42,6 +43,15 @@ export async function runWorkerApiWizard() {
   });
   if (isCancel(routes)) { cancel('Cancelled.'); process.exit(0); }
 
+  const dbKind = await select({
+    message: 'Database?',
+    options: [
+      { value: 'd1', label: 'Cloudflare D1', hint: 'Native, free tier, SQLite' },
+      { value: 'hyperdrive', label: 'Your own Postgres (Hyperdrive)', hint: 'Supabase, Neon, RDS, etc.' },
+    ],
+  });
+  if (isCancel(dbKind)) { cancel('Cancelled.'); process.exit(0); }
+
   const cfAccountId = await text({
     message: 'Cloudflare account ID?',
     placeholder: 'abc123...',
@@ -57,20 +67,26 @@ export async function runWorkerApiWizard() {
   const s = spinner();
   s.start('Generating files...');
 
-  const config = { projectName: projectName.trim(), routes, cfAccountId: cfAccountId.trim() };
+  const config = { projectName: projectName.trim(), routes, cfAccountId: cfAccountId.trim(), dbKind };
   const fileTree = workerApiTemplates(config);
   await writeFileTree(`./${config.projectName}`, fileTree);
 
   s.stop(pc.green(`Files written to ./${config.projectName}/`));
 
-  note(
-    [
-      `cd ${config.projectName}`,
-      `npm install`,
-      `npx wrangler d1 create ${config.projectName}`,
-      `npx wrangler d1 execute ${config.projectName} --file=migrations/001_init.sql --remote`,
-      `npx wrangler deploy`,
-    ].join('\n'),
-    'Next steps'
-  );
+  const nextSteps = dbKind === 'hyperdrive'
+    ? [
+        `cd ${config.projectName}`,
+        `npm install`,
+        `npx wrangler hyperdrive create ${config.projectName} --connection-string="postgres://user:pass@host:5432/db"`,
+        `# paste the returned Hyperdrive id into wrangler.toml`,
+        `npx wrangler deploy`,
+      ]
+    : [
+        `cd ${config.projectName}`,
+        `npm install`,
+        `npx wrangler d1 create ${config.projectName}`,
+        `npx wrangler d1 execute ${config.projectName} --file=migrations/001_init.sql --remote`,
+        `npx wrangler deploy`,
+      ];
+  note(nextSteps.join('\n'), 'Next steps');
 }

package/src/lib/slash-commands.js

@@ -1,34 +1,41 @@
-/**
- * Canonical slash-command surface for Agent Sam SDK CLI / shell UX.
- * Consumed by the interactive `agentsam shell` REPL and presentation layers.
- */
+/** Canonical, implemented slash-command surface for Agent Sam SDK CLI. */
 
 export const SHELL_THEMES = ['NIGHT', 'DAY', 'LAVA', 'VOID'];
 
-/** @type {Array<{ cmd: string, description: string, lane?: string }>} */
 export const SLASH_COMMANDS = [
-  { cmd: '/help', description: 'Show Agent Sam commands' },
+  { cmd: '/model', description: 'Choose exact model, reasoning level, and processing tier', lane: 'model' },
+  { cmd: '/reasoning', description: 'Set reasoning effort for the selected model', lane: 'model' },
+  { cmd: '/fast', description: 'Use provider Fast processing when the selected model supports it', lane: 'model' },
+  { cmd: '/flex', description: 'Use provider Flex processing when the selected model supports it', lane: 'model' },
+  { cmd: '/standard', description: 'Return to Standard provider processing', lane: 'model' },
+  { cmd: '/context', description: 'Show model context economics; add repo for Git bridge context', lane: 'context' },
   { cmd: '/status', description: 'Local project, DB, Git, and PTY health', lane: 'local' },
-  { cmd: '/context', description: 'Current Git repository and revision', lane: 'git' },
+  { cmd: '/models', description: 'Probe providers and provider-verified known models', lane: 'model' },
+  { cmd: '/login', description: 'Authenticate IAM and save the machine-local Agent Sam session', lane: 'identity' },
+  { cmd: '/logout', description: 'Remove the local IAM session without deleting provider keys', lane: 'identity' },
+  { cmd: '/whoami', description: 'Show authenticated IAM identity and safe credential status', lane: 'identity' },
+  { cmd: '/session', description: 'Show current session usage, cost, and resume receipt', lane: 'observability' },
+  { cmd: '/cf', description: 'Cloudflare native reads, Wrangler status, and CPU profile analysis', lane: 'cloudflare' },
+  { cmd: '/settings', description: 'Choose project, runtime, terminal, and model policy' },
   { cmd: '/pwd', description: 'Print working directory', lane: 'terminal' },
   { cmd: '/cd', description: 'Change working directory', lane: 'terminal' },
-  { cmd: '/git', description: 'Git status, diff, branch, commit, and remote', lane: 'git' },
+  { cmd: '/git', description: 'Run an explicit Git subcommand', lane: 'git' },
+  { cmd: '/diff', description: 'Show the current Git diff', lane: 'git' },
   { cmd: '/db', description: 'Local SQLite status and query helpers', lane: 'data' },
-  { cmd: '/agent', description: 'Send a goal to the configured Agent Sam', lane: 'agent' },
+  { cmd: '/agent', description: 'Send a goal to the configured local Agent Sam runtime', lane: 'agent' },
   { cmd: '/logs', description: 'Show local Agent Sam execution events', lane: 'observability' },
-  { cmd: '/tui', description: 'Switch or preview terminal presentation', lane: 'terminal' },
   { cmd: '/deploy', description: 'Add a cloud adapter and deploy intentionally', lane: 'deploy' },
+  { cmd: '/clear', description: 'Clear the terminal display', lane: 'terminal' },
+  { cmd: '/help', description: 'Show the factual implemented command catalog' },
   { cmd: '/exit', description: 'Exit Agent Sam shell and return to the host terminal' },
 ];
 
-/** Shell UX rollout phases (gorilla-shell → SDK default CLI experience). */
 export const SHELL_PHASES = [
   { id: '0-prototype', label: 'Visual prototype + demo scenarios', status: 'complete' },
-  { id: 'pty-connection', label: 'Local PTY via agentsam start-local', status: 'current' },
-  { id: 'hud-layer', label: 'Quest log, tool gate, XP HUD', status: 'planned' },
-  { id: 'buddy-system', label: 'In-shell Agent Sam via MCP', status: 'planned' },
+  { id: 'pty-connection', label: 'Local PTY via agentsam start-local', status: 'complete' },
+  { id: 'model-context-controls', label: 'Model, reasoning, processing, and context economics', status: 'complete' },
+  { id: 'run-telemetry', label: 'Provider usage, cost, resumable sessions, and permission receipts', status: 'current' },
   { id: 'dashboard-embed', label: 'Embeddable shell for IAM dashboard', status: 'planned' },
-  { id: 'standalone-pwa', label: 'Installable PWA / SDK default shell', status: 'planned' },
 ];
 
 export function listSlashCommands(opts = {}) {

package/src/lib/tools.js

@@ -1,3 +1,5 @@
+import { DEFAULT_RESULT_POLICY } from '../context/result-policy.js';
+
 const CATALOG = {
   fullstack: [
     { name: 'plan', description: 'Break a goal into implementation steps.' },
@@ -30,9 +32,13 @@ export function normalizeLane(lane = 'fullstack') {
 
 export function getToolCatalog(lane = 'fullstack') {
   const key = normalizeLane(lane);
-  if (key.includes('cms')) return CATALOG.cms;
-  if (key.includes('data')) return CATALOG.data;
-  if (key.includes('customer') || key.includes('crm')) return CATALOG.crm;
-  if (key.includes('creative') || key.includes('design')) return CATALOG.creative;
-  return CATALOG.fullstack;
+  const rows = key.includes('cms') ? CATALOG.cms
+    : key.includes('data') ? CATALOG.data
+      : (key.includes('customer') || key.includes('crm')) ? CATALOG.crm
+        : (key.includes('creative') || key.includes('design')) ? CATALOG.creative
+          : CATALOG.fullstack;
+  return rows.map((tool) => ({
+    ...tool,
+    result_policy: { ...DEFAULT_RESULT_POLICY },
+  }));
 }

package/src/models/catalog.js

@@ -0,0 +1,135 @@
+export const MODEL_CATALOG_SCHEMA = 'agentsam-model-catalog-v1';
+
+const ASTRA_SOURCE = 'https://developers.openai.com/api/docs/models/gpt-6-astra';
+
+const GPT_6_ASTRA = Object.freeze({
+  schema_version: 1,
+  model_key: 'openai:gpt-6-astra',
+  provider: 'openai',
+  provider_model_id: 'gpt-6-astra',
+  label: 'GPT-6 Astra',
+  context_window: 1_050_000,
+  max_output_tokens: 128_000,
+  reasoning_efforts: Object.freeze(['low', 'medium', 'high', 'xhigh', 'max']),
+  service_tiers: Object.freeze(['default', 'fast', 'flex']),
+  capabilities: Object.freeze({
+    responses: true,
+    streaming: true,
+    function_calling: true,
+    structured_outputs: true,
+    prompt_caching: true,
+    compaction: true,
+    tool_search: true,
+    async_tool_calls: true,
+    mid_turn_steering: true,
+    configuration_update: true,
+    batch: true,
+    fast: true,
+    flex: true,
+  }),
+  pricing: Object.freeze({
+    currency: 'USD',
+    unit: 'per_million_tokens',
+    input: 10,
+    cached_input: 1,
+    cache_write: 12.5,
+    output: 50,
+    thresholds: Object.freeze([
+      Object.freeze({
+        input_tokens_gt: 272_000,
+        applies_to_full_request: true,
+        multipliers: Object.freeze({ input: 2, cached_input: 2, cache_write: 2, output: 1.5 }),
+      }),
+    ]),
+    service_tier_multipliers: Object.freeze({ default: 1, fast: 2, flex: 0.5, batch: 0.5 }),
+    source: ASTRA_SOURCE,
+    as_of: '2026-09-12',
+  }),
+  context_policy: Object.freeze({
+    target_input_tokens: 120_000,
+    compact_at_tokens: 180_000,
+    intervene_at_tokens: 220_000,
+    max_normal_input_tokens: 250_000,
+    pricing_threshold_tokens: 272_000,
+    safety_margin_tokens: 22_000,
+  }),
+  batch: Object.freeze({
+    supported: true,
+    completion_window: '24h',
+    relative_price: 0.5,
+    interactive: false,
+  }),
+  source: Object.freeze({ url: ASTRA_SOURCE, as_of: '2026-09-12' }),
+});
+
+export const MODEL_CATALOG = Object.freeze([GPT_6_ASTRA]);
+
+function clean(value) {
+  return value == null ? '' : String(value).trim();
+}
+
+function nonNegativeInteger(value, label) {
+  const number = Number(value ?? 0);
+  if (!Number.isFinite(number) || number < 0) throw new RangeError(`${label} must be a non-negative number`);
+  return Math.floor(number);
+}
+
+export function listModelCatalog(options = {}) {
+  const provider = clean(options.provider).toLowerCase();
+  return MODEL_CATALOG.filter((row) => !provider || row.provider === provider);
+}
+
+export function getModelRecord(value) {
+  const key = clean(value);
+  if (!key) return null;
+  return MODEL_CATALOG.find((row) => row.model_key === key || row.provider_model_id === key) || null;
+}
+
+export function calculateModelCost(model, usage = {}, options = {}) {
+  const record = typeof model === 'string' ? getModelRecord(model) : model;
+  if (!record?.pricing) throw new TypeError('model pricing record is required');
+
+  const totalInput = nonNegativeInteger(usage.input_tokens ?? usage.inputTokens, 'input_tokens');
+  const cachedInput = Math.min(totalInput, nonNegativeInteger(usage.cached_input_tokens ?? usage.cachedInputTokens, 'cached_input_tokens'));
+  const cacheWrite = Math.min(totalInput - cachedInput, nonNegativeInteger(usage.cache_write_tokens ?? usage.cacheWriteTokens, 'cache_write_tokens'));
+  const uncachedInput = Math.max(0, totalInput - cachedInput - cacheWrite);
+  const output = nonNegativeInteger(usage.output_tokens ?? usage.outputTokens, 'output_tokens');
+  const serviceTier = clean(options.serviceTier || usage.service_tier || usage.serviceTier || 'default') || 'default';
+  const tierMultiplier = record.pricing.service_tier_multipliers?.[serviceTier];
+  if (!Number.isFinite(tierMultiplier)) throw new RangeError(`unsupported service tier for ${record.provider_model_id}: ${serviceTier}`);
+
+  const threshold = (record.pricing.thresholds || []).find((row) => totalInput > row.input_tokens_gt) || null;
+  const thresholdMultipliers = threshold?.multipliers || {};
+  const rates = {
+    input: record.pricing.input * (thresholdMultipliers.input || 1) * tierMultiplier,
+    cached_input: record.pricing.cached_input * (thresholdMultipliers.cached_input || 1) * tierMultiplier,
+    cache_write: record.pricing.cache_write * (thresholdMultipliers.cache_write || 1) * tierMultiplier,
+    output: record.pricing.output * (thresholdMultipliers.output || 1) * tierMultiplier,
+  };
+  const components = {
+    input: (uncachedInput * rates.input) / 1_000_000,
+    cached_input: (cachedInput * rates.cached_input) / 1_000_000,
+    cache_write: (cacheWrite * rates.cache_write) / 1_000_000,
+    output: (output * rates.output) / 1_000_000,
+  };
+  const total = Object.values(components).reduce((sum, value) => sum + value, 0);
+
+  return Object.freeze({
+    model_key: record.model_key,
+    service_tier: serviceTier,
+    usage: Object.freeze({
+      input_tokens: totalInput,
+      uncached_input_tokens: uncachedInput,
+      cached_input_tokens: cachedInput,
+      cache_write_tokens: cacheWrite,
+      output_tokens: output,
+    }),
+    threshold_applied: threshold ? Object.freeze({ ...threshold }) : null,
+    rates_per_million: Object.freeze(rates),
+    components_usd: Object.freeze(components),
+    total_usd: total,
+    estimate_kind: usage.estimate_kind === 'provider' ? 'provider' : 'local',
+    pricing_source: record.pricing.source,
+    pricing_as_of: record.pricing.as_of,
+  });
+}

package/src/models/index.js

@@ -0,0 +1,7 @@
+export {
+  MODEL_CATALOG_SCHEMA,
+  MODEL_CATALOG,
+  listModelCatalog,
+  getModelRecord,
+  calculateModelCost,
+} from './catalog.js';

package/src/providers/index.js

@@ -0,0 +1,5 @@
+export {
+  createOpenAIResponsesAdapter,
+  extractOpenAIOutputText,
+  extractOpenAIFunctionCalls,
+} from './openai-responses.js';