@inneranimalmedia/agentsam-sdk 2.5.0 → 2.6.1

package/src/knowledge/service/server.js

@@ -1,168 +1,120 @@
 import http from 'node:http';
 import fs from 'node:fs';
 import path from 'node:path';
-import { randomUUID, timingSafeEqual } from 'node:crypto';
-import { fork } from 'node:child_process';
-import { DatabaseSync } from 'node:sqlite';
 import { fileURLToPath } from 'node:url';
-import { fingerprint, validateConfig } from '../config.js';
-
-const workerPath = fileURLToPath(new URL('./job-worker.js', import.meta.url));
-const fail = (status, message) => Object.assign(new Error(message), { status });
-const decode = row => row && ({ id: row.id, status: row.status, attempts: row.attempts, created_at: row.created_at,
-  updated_at: row.updated_at, result: row.result ? JSON.parse(row.result) : null, error: row.error });
-
-function normalizeRequest(body, repositories, allowEmbeddings) {
-  if (!body || typeof body !== 'object' || Array.isArray(body)) throw fail(400, 'Expected a JSON object.');
-  const keys = ['repository', 'operation', 'scope', 'include', 'exclude', 'embed', 'semantic', 'query', 'top_k', 'token_budget', 'generation_id', 'max_inputs', 'max_characters'];
-  if (Object.keys(body).some(k => !keys.includes(k))) throw fail(400, 'Unknown job field.');
-  const repo = Object.hasOwn(repositories, body.repository) && repositories[body.repository];
-  if (!repo) throw fail(404, 'Repository is not registered.');
-  if (!['index', 'plan', 'search'].includes(body.operation)) throw fail(400, 'operation must be index, plan, or search.');
-  for (const key of ['embed', 'semantic']) if (body[key] !== undefined && typeof body[key] !== 'boolean') throw fail(400, `${key} must be a boolean.`);
-  if (((body.embed && body.operation !== 'plan') || body.semantic) && !allowEmbeddings) throw fail(403, 'Embedding calls are disabled on this service.');
-  if (body.exclude !== undefined && !Array.isArray(body.exclude)) throw fail(400, 'exclude must be an array.');
-  if (body.operation === 'search' && (typeof body.query !== 'string' || !body.query.trim() || body.query.length > 8000)) throw fail(400, 'A query of 1..8000 characters is required.');
-  const bounded = (key, fallback, min, max) => {
-    const value = body[key] ?? fallback;
-    if (!Number.isInteger(value) || value < min || value > max) throw fail(400, `${key} must be ${min}..${max}.`);
-    return value;
-  };
-  const request = { ...body, embed: body.embed ?? false, semantic: body.semantic ?? false,
-    max_inputs: bounded('max_inputs', 100, 0, 1000), max_characters: bounded('max_characters', 200000, 0, 2000000),
-    top_k: bounded('top_k', 8, 1, 8), token_budget: bounded('token_budget', 6000, 256, 6000) };
-  const config = structuredClone(repo.config);
-  if (body.scope !== undefined) config.scope.name = body.scope;
-  if (body.include !== undefined) config.scope.include = body.include;
-  if (body.exclude !== undefined) config.scope.exclude = [...config.scope.exclude, ...body.exclude];
-  let checked;
-  try { checked = validateConfig(config); } catch (error) { throw fail(400, error.message); }
-  // Request scopes can narrow a registered repository's scope, never widen it.
-  if (checked.scope.include.some(p => !repo.config.scope.include.some(allowed => allowed === '.' || p === allowed || p.startsWith(allowed + '/')))) throw fail(403, 'Requested include is outside the registered scope.');
-  return { request, config: checked, root: repo.root };
-}
+import { createBearerTokenVerifier } from './auth.js';
+import { createKnowledgeJobEngine, serviceError } from './job-engine.js';
 
 async function readBody(req) {
-  const chunks = []; let bytes = 0;
+  const chunks = [];
+  let bytes = 0;
   for await (const chunk of req) {
     bytes += chunk.length;
-    if (bytes > 16384) throw fail(413, 'Job body exceeds 16 KiB.');
+    if (bytes > 16384) throw serviceError(413, 'Job body exceeds 16 KiB.', 'RESOURCE_EXHAUSTED');
     chunks.push(chunk);
   }
-  try { return JSON.parse(Buffer.concat(chunks).toString()); } catch { throw fail(400, 'Invalid JSON.'); }
+  try {
+    return JSON.parse(Buffer.concat(chunks).toString());
+  } catch {
+    throw serviceError(400, 'Invalid JSON.', 'INVALID_ARGUMENT');
+  }
 }
 
-/** Trusted backend API. The calling host must authorize its user before submitting jobs. */
-export async function startKnowledgeService({ stateDir, repositories, token, port = 8792, host = '127.0.0.1',
-  allowEmbeddings = false, maxQueued = 32, maxFiles = 2000, jobTimeoutMs = 600000 } = {}) {
-  if (typeof token !== 'string' || token.length < 32 || token.length > 256) throw new Error('Service token must be 32..256 characters.');
-  if (!repositories || !Object.keys(repositories).length) throw new Error('Register at least one repository.');
-  repositories = Object.fromEntries(Object.entries(repositories).map(([name, repo]) => {
-    if (!/^[a-z][a-z0-9_-]{0,47}$/.test(name)) throw new Error('Invalid repository alias.');
-    const root = fs.realpathSync(repo.root);
-    if (!fs.statSync(root).isDirectory()) throw new Error('Repository root must be a directory.');
-    const config = validateConfig(repo.config);
-    if (config.storage.driver !== 'sqlite') throw new Error('This service release uses its durable SQLite volume; Postgres is not configured by this preset.');
-    return [name, { root, config }];
-  }));
-  fs.mkdirSync(stateDir, { recursive: true, mode: 0o700 });
-  const db = new DatabaseSync(path.join(stateDir, 'jobs.sqlite'));
-  db.exec(`PRAGMA journal_mode=WAL; PRAGMA busy_timeout=5000;
-    CREATE TABLE IF NOT EXISTS jobs (id TEXT PRIMARY KEY, idem TEXT UNIQUE, digest TEXT NOT NULL,
-      payload TEXT NOT NULL, status TEXT NOT NULL, attempts INTEGER NOT NULL DEFAULT 0,
-      created_at TEXT NOT NULL, updated_at TEXT NOT NULL, result TEXT, error TEXT);
-    CREATE INDEX IF NOT EXISTS jobs_pending ON jobs(status, created_at);`);
-  fs.chmodSync(path.join(stateDir, 'jobs.sqlite'), 0o600);
-  // Interrupted work reuses SDK caches. Bound restarts so a poison job cannot loop forever.
-  db.prepare("UPDATE jobs SET status=CASE WHEN attempts>=3 THEN 'failed' ELSE 'queued' END, error=CASE WHEN attempts>=3 THEN 'Interrupted three times; submit a new job after investigation.' ELSE NULL END WHERE status='running'").run();
-  let child = null, closing = false, pumping = false;
-  const get = id => decode(db.prepare('SELECT * FROM jobs WHERE id=?').get(id));
-  const pump = () => {
-    if (closing || pumping) return;
-    const row = db.prepare("SELECT * FROM jobs WHERE status='queued' ORDER BY created_at,rowid LIMIT 1").get();
-    if (!row) return;
-    pumping = true;
-    db.prepare("UPDATE jobs SET status='running',attempts=attempts+1,updated_at=? WHERE id=?").run(new Date().toISOString(), row.id);
-    let response = null, timedOut = false;
-    child = fork(workerPath, [], { execArgv: [], stdio: ['ignore', 'ignore', 'ignore', 'ipc'], env: { ...process.env, GIT_OPTIONAL_LOCKS: '0' } });
-    const timer = setTimeout(() => { timedOut = true; child?.kill('SIGKILL'); }, jobTimeoutMs);
-    child.once('message', value => { response = value; });
-    child.once('error', () => { response = { ok: false, error: 'Could not start indexing process.' }; });
-    child.once('close', () => {
-      clearTimeout(timer); child = null;
-      if (!closing) {
-        const ok = response?.ok && !timedOut;
-        db.prepare('UPDATE jobs SET status=?,result=?,error=?,updated_at=? WHERE id=?').run(ok ? 'completed' : 'failed', ok ? JSON.stringify(response.result) : null,
-          ok ? null : timedOut ? 'Job exceeded its time limit; narrow the scope.' : response?.error || 'Indexing process exited unexpectedly.', new Date().toISOString(), row.id);
-      }
-      pumping = false;
-      if (!closing) setImmediate(pump);
-    });
-    // Re-resolve registry on replay. Removed repositories do not get resumed.
-    const payload = JSON.parse(row.payload), registered = repositories[payload.request.repository];
-    if (!registered || registered.config.repository_id !== payload.config.repository_id || fingerprint(registered.config.scope) !== payload.registered_scope || (!allowEmbeddings && ((payload.request.embed && payload.request.operation !== 'plan') || payload.request.semantic))) {
-      response = { ok: false, error: 'Repository registration changed; resubmit this job.' }; child.kill(); return;
-    }
-    child.send({ ...payload, root: registered.root, filename: path.join(stateDir, 'knowledge.sqlite'), maxFiles });
-  };
-  const secret = Buffer.from(token);
+export async function startKnowledgeHttpServer({ engine, token, verifyToken, port = 8792, host = '127.0.0.1' } = {}) {
+  if (!engine) throw new Error('Knowledge job engine is required.');
+  const verify = verifyToken || createBearerTokenVerifier(token);
   const server = http.createServer(async (req, res) => {
-    const send = (status, value) => { res.writeHead(status, { 'content-type': 'application/json', 'cache-control': 'no-store' }); res.end(JSON.stringify(value)); };
+    const send = (status, value) => {
+      res.writeHead(status, { 'content-type': 'application/json', 'cache-control': 'no-store' });
+      res.end(JSON.stringify(value));
+    };
     try {
       const route = new URL(req.url, 'http://local').pathname;
       if (req.method === 'GET' && route === '/healthz') return send(200, { ok: true, service: 'agentsam-knowledge', version: 1 });
-      const provided = Buffer.from((req.headers.authorization || '').replace(/^Bearer /, ''));
-      if (provided.length !== secret.length || !timingSafeEqual(provided, secret)) throw fail(401, 'Unauthorized.');
-      if (req.method === 'GET' && route === '/v1/repositories') return send(200, { repositories: Object.keys(repositories), embeddings_enabled: allowEmbeddings });
-      if (req.method === 'GET' && /^\/v1\/jobs\/[a-f0-9-]{36}$/.test(route)) {
-        const job = get(route.split('/').pop()); if (!job) throw fail(404, 'Job not found.'); return send(200, job);
+      if (!verify(req.headers.authorization)) throw serviceError(401, 'Unauthorized.', 'UNAUTHENTICATED');
+      if (req.method === 'GET' && route === '/v1/repositories') {
+        const value = engine.listRepositories();
+        return send(200, { repositories: value.repositories.map(repo => repo.alias), embeddings_enabled: value.embeddings_enabled });
       }
-      if (req.method !== 'POST' || route !== '/v1/jobs') throw fail(404, 'Route not found.');
-      if (closing) throw fail(503, 'Service is stopping.');
-      if (!(req.headers['content-type'] || '').startsWith('application/json')) throw fail(415, 'Use application/json.');
-      const payload = normalizeRequest(await readBody(req), repositories, allowEmbeddings);
-      payload.registered_scope = fingerprint(repositories[payload.request.repository].config.scope);
-      const key = req.headers['idempotency-key'];
-      if (key !== undefined && (typeof key !== 'string' || !/^[\w:.-]{1,128}$/.test(key))) throw fail(400, 'Invalid Idempotency-Key.');
-      const digest = fingerprint(payload), idem = key ? fingerprint([payload.config.repository_id, payload.registered_scope, key]) : null;
-      const previous = idem && db.prepare('SELECT * FROM jobs WHERE idem=?').get(idem);
-      if (previous) {
-        if (previous.digest !== digest) throw fail(409, 'Idempotency-Key already used for a different job.');
-        return send(200, decode(previous));
+      if (req.method === 'GET' && /^\/v1\/jobs\/[a-f0-9-]{36}$/.test(route)) {
+        return send(200, engine.getJob(route.split('/').pop()));
       }
-      if (db.prepare("SELECT COUNT(*) AS n FROM jobs WHERE status IN ('queued','running')").get().n >= maxQueued) throw fail(429, 'Job queue is full; retry later with the same Idempotency-Key.');
-      const id = randomUUID(), now = new Date().toISOString();
-      db.prepare("INSERT INTO jobs(id,idem,digest,payload,status,created_at,updated_at) VALUES(?,?,?,?,'queued',?,?)").run(id, idem, digest, JSON.stringify(payload), now, now);
-      send(202, get(id)); setImmediate(pump);
-    } catch (error) { if (!res.writableEnded) send(error.status || 500, { error: error.status ? error.message : 'Service request failed.' }); }
+      if (req.method !== 'POST' || route !== '/v1/jobs') throw serviceError(404, 'Route not found.', 'NOT_FOUND');
+      if (!(req.headers['content-type'] || '').startsWith('application/json')) throw serviceError(415, 'Use application/json.', 'INVALID_ARGUMENT');
+      const { job, created } = engine.submitJob(await readBody(req), { idempotencyKey: req.headers['idempotency-key'] });
+      return send(created ? 202 : 200, job);
+    } catch (error) {
+      if (!res.writableEnded) send(error.status || 500, { error: error.status ? error.message : 'Service request failed.' });
+    }
   });
-  server.requestTimeout = 15000; server.headersTimeout = 10000;
+  server.requestTimeout = 15000;
+  server.headersTimeout = 10000;
   await new Promise((resolve, reject) => { server.once('error', reject); server.listen(port, host, resolve); });
-  setImmediate(pump);
-  return { server, address: server.address(), async close() {
-    closing = true;
-    if (child) { const active = child; await new Promise(resolve => { active.once('close', resolve); active.kill('SIGKILL'); }); }
-    await new Promise(resolve => server.close(resolve)); db.close();
-  } };
+  return {
+    server,
+    address: server.address(),
+    async close() {
+      await new Promise(resolve => server.close(resolve));
+    },
+  };
+}
+
+/** Trusted backend API. The calling host must authorize its user before submitting jobs. */
+export async function startKnowledgeService({ token, port = 8792, host = '127.0.0.1', ...engineOptions } = {}) {
+  const verifyToken = createBearerTokenVerifier(token);
+  const engine = createKnowledgeJobEngine(engineOptions);
+  try {
+    const httpService = await startKnowledgeHttpServer({ engine, verifyToken, port, host });
+    return {
+      ...httpService,
+      engine,
+      async close() {
+        await httpService.close();
+        await engine.close();
+      },
+    };
+  } catch (error) {
+    await engine.close();
+    throw error;
+  }
 }
 
 if (process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
   try {
-    // Initialize the named volume, then match the host file owner before reading mounts.
-    // The long-running server and all indexing children run without root privileges.
     if (process.getuid?.() === 0 && process.env.AGENTSAM_RUNTIME_UID) {
-      const uid = Number(process.env.AGENTSAM_RUNTIME_UID), gid = Number(process.env.AGENTSAM_RUNTIME_GID);
+      const uid = Number(process.env.AGENTSAM_RUNTIME_UID);
+      const gid = Number(process.env.AGENTSAM_RUNTIME_GID);
       if (!Number.isInteger(uid) || uid < 0 || !Number.isInteger(gid) || gid < 0) throw new Error('Invalid runtime uid/gid.');
       const state = process.env.AGENTSAM_STATE_DIR || '/data';
-      fs.mkdirSync(state, { recursive: true, mode: 0o700 }); fs.chownSync(state, uid, gid);
-      process.setgroups([]); process.setgid(gid); process.setuid(uid);
+      fs.mkdirSync(state, { recursive: true, mode: 0o700 });
+      fs.chownSync(state, uid, gid);
+      process.setgroups([]);
+      process.setgid(gid);
+      process.setuid(uid);
     }
     const registry = JSON.parse(fs.readFileSync(process.env.AGENTSAM_REPOSITORIES_FILE || '/config/repositories.json', 'utf8'));
     const token = fs.readFileSync(process.env.AGENTSAM_SERVICE_TOKEN_FILE || '/config/service.token', 'utf8').trim();
-    const service = await startKnowledgeService({ stateDir: process.env.AGENTSAM_STATE_DIR || '/data', repositories: registry,
-      token, host: process.env.HOST || '0.0.0.0', port: Number(process.env.PORT || 8792), allowEmbeddings: process.env.AGENTSAM_ALLOW_EMBEDDINGS === 'true' });
+    const service = await startKnowledgeService({
+      stateDir: process.env.AGENTSAM_STATE_DIR || '/data',
+      repositories: registry,
+      token,
+      host: process.env.HOST || '0.0.0.0',
+      port: Number(process.env.PORT || 8792),
+      allowEmbeddings: process.env.AGENTSAM_ALLOW_EMBEDDINGS === 'true',
+    });
     console.log(JSON.stringify({ event: 'listening', port: service.address.port, repositories: Object.keys(registry), embeddings_enabled: process.env.AGENTSAM_ALLOW_EMBEDDINGS === 'true' }));
     let stopped = false;
-    for (const signal of ['SIGTERM', 'SIGINT']) process.on(signal, async () => { if (!stopped) { stopped = true; await service.close(); process.exit(0); } });
-  } catch { console.error('Knowledge service could not start; check repository registrations, token file, and state permissions.'); process.exit(1); }
+    for (const signal of ['SIGTERM', 'SIGINT']) {
+      process.on(signal, async () => {
+        if (!stopped) {
+          stopped = true;
+          await service.close();
+          process.exit(0);
+        }
+      });
+    }
+  } catch {
+    console.error('Knowledge service could not start; check repository registrations, token file, and state permissions.');
+    process.exit(1);
+  }
 }

package/src/knowledge/source.js

@@ -2,7 +2,7 @@ import fs from 'node:fs';
 import path from 'node:path';
 import { execFileSync } from 'node:child_process';
 import ts from 'typescript';
-import { fileHasher } from '../lib/merkle/hash.js';
+import { fileHasher } from '../../packages/agentsam-repository/src/merkle/hash.js';
 import { fingerprint } from './config.js';
 
 export const PARSER = `typescript:${ts.version}:agentsam-1`;

package/src/lib/account-session.js

@@ -0,0 +1,98 @@
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { resolveSdkKey } from '../../packages/identity/src/contracts/auth-config.js';
+
+export const ACCOUNT_SESSION_SCHEMA = 'agentsam-account-session-v1';
+
+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());
+}
+
+export function accountSessionPath(options = {}) {
+  return path.join(homeDirectory(options), '.agentsam', 'auth', 'session.json');
+}
+
+export function readAccountSession(options = {}) {
+  const filename = accountSessionPath(options);
+  if (!fs.existsSync(filename)) return null;
+  try {
+    const stat = fs.statSync(filename);
+    if (!stat.isFile()) return null;
+    if (process.platform !== 'win32' && (stat.mode & 0o077) !== 0) return null;
+    const parsed = JSON.parse(fs.readFileSync(filename, 'utf8'));
+    if (parsed?.schema_version !== ACCOUNT_SESSION_SCHEMA) return null;
+    const token = clean(parsed.sdk_key);
+    if (!token.startsWith('sdk_')) return null;
+    return {
+      schema_version: ACCOUNT_SESSION_SCHEMA,
+      sdk_key: token,
+      user_id: clean(parsed.user_id) || null,
+      account_id: clean(parsed.account_id) || null,
+      email: clean(parsed.email) || null,
+      created_at: clean(parsed.created_at) || null,
+      updated_at: clean(parsed.updated_at) || null,
+    };
+  } catch {
+    return null;
+  }
+}
+
+export function saveAccountSession(session = {}, options = {}) {
+  const token = clean(session.sdk_key || session.access_token);
+  if (!token.startsWith('sdk_')) throw new Error('account_session_sdk_key_required');
+  const filename = accountSessionPath(options);
+  const dir = path.dirname(filename);
+  fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
+  if (process.platform !== 'win32') {
+    try { fs.chmodSync(dir, 0o700); } catch { /* best effort */ }
+  }
+  const previous = readAccountSession(options);
+  const now = new Date().toISOString();
+  const value = {
+    schema_version: ACCOUNT_SESSION_SCHEMA,
+    sdk_key: token,
+    user_id: clean(session.user_id) || previous?.user_id || null,
+    account_id: clean(session.account_id) || previous?.account_id || null,
+    email: clean(session.email) || previous?.email || null,
+    created_at: previous?.created_at || now,
+    updated_at: now,
+  };
+  const temp = `${filename}.${process.pid}.tmp`;
+  fs.writeFileSync(temp, `${JSON.stringify(value, null, 2)}\n`, { mode: 0o600 });
+  if (process.platform !== 'win32') {
+    try { fs.chmodSync(temp, 0o600); } catch { /* best effort */ }
+  }
+  fs.renameSync(temp, filename);
+  return { ...value };
+}
+
+export function clearAccountSession(options = {}) {
+  const filename = accountSessionPath(options);
+  if (!fs.existsSync(filename)) return false;
+  fs.rmSync(filename, { force: true });
+  return true;
+}
+
+export function resolveAccountSdkKey(options = {}) {
+  const env = options.env || process.env;
+  const explicit = clean(options.explicit);
+  const fromEnv = resolveSdkKey(env, explicit);
+  if (fromEnv) return { value: fromEnv, source: explicit ? 'explicit' : 'environment' };
+  const session = readAccountSession({ ...options, env });
+  return session?.sdk_key
+    ? { value: session.sdk_key, source: 'agentsam_account_session', session }
+    : { value: '', source: null, session: null };
+}
+
+export function describeAccountSession(options = {}) {
+  const resolved = resolveAccountSdkKey(options);
+  return {
+    configured: Boolean(resolved.value),
+    source: resolved.source,
+    user_id: resolved.session?.user_id || null,
+    account_id: resolved.session?.account_id || null,
+    email: resolved.session?.email || null,
+  };
+}

package/src/lib/agent-instructions.js

@@ -0,0 +1,73 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { createHash } from 'node:crypto';
+import { findProjectRules } from './project-rules.js';
+
+export const AGENT_RUNTIME_FILENAME = 'AGENTSAM.md';
+export const AGENT_INSTRUCTION_PRECEDENCE = Object.freeze(['AGENTSAM.md', '.agentsamrules']);
+
+function sha256(value) {
+  return `sha256:${createHash('sha256').update(value).digest('hex')}`;
+}
+
+function findUp(startDir, filename) {
+  let dir = path.resolve(startDir);
+  for (let i = 0; i < 16; i += 1) {
+    const candidate = path.join(dir, filename);
+    if (fs.existsSync(candidate)) return candidate;
+    const boundary = fs.existsSync(path.join(dir, '.git')) || fs.existsSync(path.join(dir, '.agentsam', 'config.json'));
+    if (boundary) break;
+    const parent = path.dirname(dir);
+    if (parent === dir) break;
+    dir = parent;
+  }
+  return null;
+}
+
+export function findAgentRuntimeContract(startDir = process.cwd()) {
+  return findUp(startDir, AGENT_RUNTIME_FILENAME);
+}
+
+export function compileAgentInstructions(startDir = process.cwd(), options = {}) {
+  const maxChars = Number(options.maxChars ?? 24_000);
+  if (!Number.isInteger(maxChars) || maxChars < 1) throw new RangeError('agent instructions maxChars must be a positive integer');
+
+  const runtimePath = options.runtimeFilename ? path.resolve(options.runtimeFilename) : findAgentRuntimeContract(startDir);
+  const projectPath = options.projectFilename ? path.resolve(options.projectFilename) : findProjectRules(startDir);
+  const descriptors = [
+    { id: 'runtime', filename: AGENT_RUNTIME_FILENAME, path: runtimePath },
+    { id: 'project', filename: '.agentsamrules', path: projectPath },
+  ];
+  const sections = [];
+  const sources = [];
+  let sourceChars = 0;
+
+  for (const descriptor of descriptors) {
+    if (!descriptor.path || !fs.existsSync(descriptor.path)) continue;
+    const source = fs.readFileSync(descriptor.path, 'utf8');
+    sourceChars += source.length;
+    sources.push(Object.freeze({
+      id: descriptor.id,
+      filename: descriptor.filename,
+      path: descriptor.path,
+      chars: source.length,
+      hash: sha256(source),
+    }));
+    sections.push(`<!-- agentsam:${descriptor.id}:${descriptor.filename} -->\n${source.trim()}\n`);
+  }
+
+  const combined = sections.join('\n');
+  const truncated = combined.length > maxChars;
+  const content = truncated ? `${combined.slice(0, Math.max(0, maxChars - 1))}…` : combined;
+  return Object.freeze({
+    found: sources.length > 0,
+    path: projectPath || runtimePath || null,
+    content,
+    chars: content.length,
+    source_chars: sourceChars,
+    truncated,
+    hash: combined ? sha256(combined) : null,
+    precedence: AGENT_INSTRUCTION_PRECEDENCE,
+    sources: Object.freeze(sources),
+  });
+}

package/src/lib/auth.js

@@ -5,6 +5,7 @@ import http from 'node:http';
 import { randomBytes } from 'node:crypto';
 import { postJson } from './core-client.js';
 import { promptToOpenUrl } from './open-url.js';
+import { saveAccountSession } from './account-session.js';
 
 function randomState() {
   return randomBytes(16).toString('hex');
@@ -63,5 +64,8 @@ export async function authenticateViaBrowser() {
 
   const code = await codePromise;
   const session = await postJson('/api/sdk/auth/exchange', { code, state });
+  if (String(session?.access_token || '').trim().startsWith('sdk_')) {
+    saveAccountSession(session);
+  }
   return session;
 }

package/src/lib/cli-preferences.js

@@ -3,14 +3,12 @@ import path from 'node:path';
 import { spawnSync } from 'node:child_process';
 import { getProjectName, tryReadProjectConfig } from './project-config.js';
 
-export const CLI_PREFERENCES_SCHEMA = 'agentsam-cli-preferences-v1';
+export const CLI_PREFERENCES_SCHEMA = 'agentsam-cli-preferences-v3';
+export const LEGACY_CLI_PREFERENCES_SCHEMAS = new Set(['agentsam-cli-preferences-v1', 'agentsam-cli-preferences-v2']);
 
 function readJson(filename) {
-  try {
-    return JSON.parse(fs.readFileSync(filename, 'utf8'));
-  } catch {
-    return null;
-  }
+  try { return JSON.parse(fs.readFileSync(filename, 'utf8')); }
+  catch { return null; }
 }
 
 function gitValue(cwd, args) {
@@ -22,14 +20,9 @@ export function findCliProjectRoot(startDir = process.cwd()) {
   const cwd = path.resolve(startDir);
   const gitRoot = gitValue(cwd, ['rev-parse', '--show-toplevel']);
   if (gitRoot) return path.resolve(gitRoot);
-
   let dir = cwd;
   for (let i = 0; i < 16; i += 1) {
-    if (
-      fs.existsSync(path.join(dir, '.agentsam', 'cli.json')) ||
-      fs.existsSync(path.join(dir, '.agentsam', 'config.json')) ||
-      fs.existsSync(path.join(dir, 'package.json'))
-    ) return dir;
+    if (fs.existsSync(path.join(dir, '.agentsam', 'cli.json')) || fs.existsSync(path.join(dir, '.agentsam', 'config.json')) || fs.existsSync(path.join(dir, 'package.json'))) return dir;
     const parent = path.dirname(dir);
     if (parent === dir) break;
     dir = parent;
@@ -48,27 +41,65 @@ export function detectCliProject(startDir = process.cwd()) {
   return { root, project, branch, remote, website, configured: Boolean(getProjectName(config)) };
 }
 
-export function cliPreferencesPath(root) {
-  return path.join(path.resolve(root), '.agentsam', 'cli.json');
+export function cliPreferencesPath(root) { return path.join(path.resolve(root), '.agentsam', 'cli.json'); }
+
+function safeModelSnapshot(value) {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) return null;
+  const provider = String(value.provider || '').trim();
+  const providerModelId = String(value.provider_model_id || '').trim();
+  if (!provider || !providerModelId) return null;
+  return {
+    model_key: String(value.model_key || `${provider}:${providerModelId}`),
+    provider,
+    provider_model_id: providerModelId,
+    label: String(value.label || providerModelId),
+    availability: value.availability === 'available' ? 'available' : 'unverified',
+    availability_source: String(value.availability_source || ''),
+    context_window: Number.isFinite(Number(value.context_window)) && Number(value.context_window) > 0 ? Number(value.context_window) : null,
+    context_window_source: String(value.context_window_source || 'unknown'),
+    max_output_tokens: Number.isFinite(Number(value.max_output_tokens)) && Number(value.max_output_tokens) > 0 ? Number(value.max_output_tokens) : null,
+    max_output_tokens_source: String(value.max_output_tokens_source || 'unknown'),
+    reasoning_efforts: Array.isArray(value.reasoning_efforts) && value.reasoning_efforts.length ? value.reasoning_efforts.map(String) : ['auto'],
+    service_tiers: Array.isArray(value.service_tiers) && value.service_tiers.length ? value.service_tiers.map(String) : ['default'],
+    capabilities: value.capabilities && typeof value.capabilities === 'object' ? { ...value.capabilities } : {},
+    pricing: value.pricing && typeof value.pricing === 'object' ? { ...value.pricing } : null,
+    context_policy: value.context_policy && typeof value.context_policy === 'object' ? { ...value.context_policy } : null,
+    source: value.source && typeof value.source === 'object' ? { ...value.source } : null,
+  };
+}
+
+function normalizePreferences(value = {}) {
+  const modelSnapshot = safeModelSnapshot(value.modelSnapshot);
+  return {
+    schemaVersion: CLI_PREFERENCES_SCHEMA,
+    trustedDirectory: value.trustedDirectory === true,
+    runtime: value.runtime || 'local',
+    terminal: value.terminal || '',
+    modelPreference: value.modelPreference || 'auto',
+    modelSnapshot,
+    reasoningEffort: value.reasoningEffort || 'auto',
+    serviceTier: value.serviceTier || 'default',
+    modelAuthority: modelSnapshot?.availability === 'available' ? 'provider-verified' : 'preference-only',
+    updatedAt: value.updatedAt || null,
+  };
 }
 
 export function readCliPreferences(root) {
   const value = readJson(cliPreferencesPath(root));
-  if (!value || value.schemaVersion !== CLI_PREFERENCES_SCHEMA) return null;
-  return value;
+  if (!value) return null;
+  if (value.schemaVersion !== CLI_PREFERENCES_SCHEMA && !LEGACY_CLI_PREFERENCES_SCHEMAS.has(value.schemaVersion)) return null;
+  return normalizePreferences(value);
 }
 
 export function writeCliPreferences(root, value = {}) {
   const filename = cliPreferencesPath(root);
   fs.mkdirSync(path.dirname(filename), { recursive: true });
-  const next = {
-    schemaVersion: CLI_PREFERENCES_SCHEMA,
-    runtime: value.runtime || 'local',
-    terminal: value.terminal || '',
-    modelPreference: value.modelPreference || 'auto',
-    modelAuthority: 'preference-only',
-    updatedAt: new Date().toISOString(),
-  };
+  const previous = readCliPreferences(root) || {};
+  const next = normalizePreferences({ ...previous, ...value, updatedAt: new Date().toISOString() });
   fs.writeFileSync(filename, `${JSON.stringify(next, null, 2)}\n`);
   return next;
 }
+
+export function updateCliPreferences(root, patch = {}) {
+  return writeCliPreferences(root, { ...(readCliPreferences(root) || {}), ...patch });
+}

package/src/lib/deploy/git-guard.js

@@ -0,0 +1,69 @@
+/**
+ * Production Wrangler deploys are allowed only from a clean main that matches origin/main.
+ * Dry-run / plan may run from a feature branch. Never from /private/tmp.
+ */
+import path from 'node:path';
+import { spawnSync } from 'node:child_process';
+
+const BLOCKED_BRANCH_PREFIXES = ['feat/', 'fix/', 'chore/', 'release/'];
+
+function git(cwd, args) {
+  const r = spawnSync('git', args, { cwd, encoding: 'utf8' });
+  return {
+    status: r.status,
+    stdout: String(r.stdout || '').trim(),
+    stderr: String(r.stderr || '').trim(),
+  };
+}
+
+export function inspectDeployGit(cwd = process.cwd()) {
+  const root = git(cwd, ['rev-parse', '--show-toplevel']);
+  const branch = git(cwd, ['rev-parse', '--abbrev-ref', 'HEAD']);
+  const head = git(cwd, ['rev-parse', 'HEAD']);
+  const origin = git(cwd, ['rev-parse', 'origin/main']);
+  const porcelain = git(cwd, ['status', '--porcelain']);
+  const detached = branch.stdout === 'HEAD';
+  const repoRoot = root.stdout || path.resolve(cwd);
+  return {
+    ok: root.status === 0,
+    repoRoot,
+    branch: branch.stdout,
+    detached,
+    head: head.stdout,
+    originMain: origin.stdout,
+    dirty: Boolean(porcelain.stdout),
+    tmpCheckout: repoRoot.includes('/private/tmp/') || repoRoot.includes('/tmp/'),
+  };
+}
+
+export function productionDeployBlockedReason(info) {
+  if (!info?.ok) return 'not a git checkout';
+  if (info.tmpCheckout) return 'refusing production deploy from a temporary checkout';
+  if (info.detached) return 'refusing production deploy from detached HEAD';
+  if (info.branch !== 'main') {
+    return `refusing production deploy from ${info.branch}; origin/main only`;
+  }
+  for (const prefix of BLOCKED_BRANCH_PREFIXES) {
+    if (info.branch.startsWith(prefix)) {
+      return `refusing production deploy from ${info.branch}`;
+    }
+  }
+  if (!info.originMain) return 'origin/main is missing; fetch before deploying';
+  if (info.head !== info.originMain) {
+    return `HEAD (${info.head.slice(0, 12)}) != origin/main (${info.originMain.slice(0, 12)})`;
+  }
+  if (info.dirty) return 'working tree is not clean';
+  return null;
+}
+
+export function assertProductionDeployAllowed(cwd = process.cwd()) {
+  const info = inspectDeployGit(cwd);
+  const reason = productionDeployBlockedReason(info);
+  if (reason) {
+    const err = new Error(reason);
+    err.code = 'production_deploy_refused';
+    err.git = info;
+    throw err;
+  }
+  return info;
+}