@inneranimalmedia/agentsam-sdk 2.6.2 → 2.6.4

package/packages/agentsam-errors/test/transport.test.mjs

@@ -0,0 +1,46 @@
+import assert from 'node:assert/strict';
+import test from 'node:test';
+import {
+  createErrorEnvelope,
+  fromHttpError,
+  retryDelayMs,
+  shouldRetry,
+  toHttpError,
+} from '../src/index.js';
+
+test('HTTP transport preserves the complete canonical envelope', () => {
+  const error = createErrorEnvelope({
+    reason: 'provider_rate_limited',
+    message: 'Slow down',
+    source: { kind: 'provider', name: 'openai' },
+    provider: 'openai',
+    provider_code: 'slow_down',
+    request_id: 'req_1',
+    retry_after_ms: 2000,
+    domain: 'provider',
+  });
+  const http = toHttpError(error);
+  const decoded = fromHttpError({ status: http.status, body: http.body, headers: http.headers });
+  assert.deepEqual(decoded, error);
+});
+
+test('fallback HTTP failures still normalize without provider-specific code', () => {
+  const error = fromHttpError({ status: 503, body: { message: 'upstream down' }, provider: 'example' });
+  assert.equal(error.code, 'UNAVAILABLE');
+  assert.equal(error.reason, 'transport_unreachable');
+  assert.equal(error.retryable, true);
+});
+
+test('retry policy honors provider Retry-After before exponential fallback', () => {
+  const explicit = createErrorEnvelope({ reason: 'provider_rate_limited', message: 'wait', retry_after_ms: 2500 });
+  const fallback = createErrorEnvelope({ reason: 'provider_unavailable', message: 'down' });
+  assert.equal(shouldRetry(explicit), true);
+  assert.equal(retryDelayMs(explicit, 4), 2500);
+  assert.equal(retryDelayMs(fallback, 3, { baseMs: 500 }), 2000);
+});
+
+test('fingerprints exclude volatile request ids and messages', () => {
+  const a = createErrorEnvelope({ reason: 'provider_unavailable', message: 'first', source: { kind: 'provider', name: 'openai' }, provider: 'openai', request_id: 'req_a' });
+  const b = createErrorEnvelope({ reason: 'provider_unavailable', message: 'different wording', source: { kind: 'provider', name: 'openai' }, provider: 'openai', request_id: 'req_b' });
+  assert.equal(a.fingerprint, b.fingerprint);
+});

package/packages/agentsam-knowledge/package.json

@@ -0,0 +1,15 @@
+{
+  "name": "@inneranimalmedia/agentsam-knowledge",
+  "version": "0.1.0",
+  "private": true,
+  "description": "Portable AutoRAG discovery, adapter registries, probes, and company routing contracts for AgentSam.",
+  "type": "module",
+  "exports": {
+    ".": "./src/index.js",
+    "./autorag": "./src/autorag/index.js",
+    "./providers": "./src/providers/index.js",
+    "./backends": "./src/backends/index.js"
+  },
+  "scripts": { "test": "node --test test/*.test.mjs" },
+  "engines": { "node": ">=22 <25" }
+}

package/packages/agentsam-knowledge/src/autorag/index.js

@@ -0,0 +1,64 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { execFileSync } from 'node:child_process';
+import { createProviderRegistry } from '../providers/index.js';
+import { createBackendRegistry } from '../backends/index.js';
+
+const clean = value => String(value || '').trim();
+const unique = values => [...new Set(values.filter(Boolean))];
+function git(root, args) { try { return execFileSync('git', args, { cwd: root, encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] }).trim() || null; } catch { return null; } }
+function findScopes(root) {
+  const candidates = ['packages', 'src', 'services', 'apps', 'docs', 'README.md', 'schema', 'migrations'];
+  return candidates.filter(candidate => fs.existsSync(path.join(root, candidate)));
+}
+export async function discoverAutoRag({ root = process.cwd(), env = process.env, companyAdapter = null, fetchImpl } = {}) {
+  const isGit = Boolean(git(root, ['rev-parse', '--is-inside-work-tree']));
+  const providerRegistry = createProviderRegistry({ gemini: { apiKey: env.GEMINI_API_KEY, fetchImpl }, openai: { apiKey: env.OPENAI_API_KEY, fetchImpl }, ollama: { endpoint: env.OLLAMA_HOST || 'http://127.0.0.1:11434', fetchImpl } });
+  const providers = await providerRegistry.capabilities();
+  const docker = git(root, ['--version']) && (() => { try { return Boolean(execFileSync('docker', ['--version'], { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] })); } catch { return false; } })();
+  const repositoryId = git(root, ['config', '--get', 'remote.origin.url']) || `local:${path.basename(root)}`;
+  return Object.freeze({
+    repository: { root, name: path.basename(root), identity: repositoryId, branch: git(root, ['branch', '--show-current']), revision: git(root, ['rev-parse', 'HEAD']), git: isGit, merkle: fs.existsSync(path.join(root, '.agentsam', 'merkle.json')), semantic_merkle: fs.existsSync(path.join(root, '.agentsam', 'merkle.json')) },
+    scopes: findScopes(root),
+    capabilities: { sqlite: true, git: isGit, merkle: isGit, structural_indexing: true, local_knowledge_engine: true, repository_intelligence: fs.existsSync(path.join(root, 'packages', 'agentsam-repository')), docker, providers, backends: createBackendRegistry().capabilities(), company_graph: Boolean(companyAdapter?.discover) ? await companyAdapter.discover() : { available: false } },
+  });
+}
+export function recommendAutoRag({ discovery, purpose = 'code', include, provider = 'none', backend = 'local_exact', semantic = false } = {}) {
+  const scopes = include?.length ? unique(include) : purpose === 'code' ? discovery.scopes.filter(scope => ['packages', 'src'].includes(scope)).slice(0, 2) : discovery.scopes.filter(scope => /^(docs|README\.md|schema|migrations)$/.test(scope)).slice(0, 3);
+  return Object.freeze({ purpose, repositories: [discovery.repository.identity], scope: scopes.length ? scopes : ['.'], evidence: purpose === 'code' ? ['git', 'merkle', 'semantic-metadata', 'ast', 'lexical'] : ['git', 'merkle', 'lexical'], embedding: semantic ? provider : 'none', control_plane: 'local_sqlite', backend, probe: { max_files: 25, max_chunks: 100, max_semantic_queries: 1, paid_embeddings: false }, company_registration: 'disabled' });
+}
+export function safeAutoRagConfig({ existing = {}, recommendation, repositoryId, projectKey } = {}) {
+  const config = structuredClone(existing);
+  config.version = Math.max(Number(config.version || 1), 2);
+  config.repository_id = config.repository_id || repositoryId;
+  config.project_key = config.project_key || projectKey || config.repository_id;
+  config.scope = { name: config.scope?.name || recommendation.purpose, include: recommendation.scope, exclude: config.scope?.exclude || [] };
+  config.chunking = config.chunking || { max_chars: 4000 };
+  config.embedding = recommendation.embedding === 'none' ? { provider: 'none', model: 'none', revision: '1', dimensions: 0, parameters: {} } : (config.embedding || { provider: recommendation.embedding, model: recommendation.embedding === 'ollama' ? 'nomic-embed-text' : recommendation.embedding === 'openai' ? 'text-embedding-3-small' : 'gemini-embedding-2', revision: '1', dimensions: 768, parameters: { task: 'code retrieval' } });
+  config.storage = config.storage || { driver: 'sqlite' };
+  config.lane = { id: config.lane?.id || `${recommendation.purpose}-local`, backend: recommendation.backend, resource: config.lane?.resource || null, binding: config.lane?.binding || null, index: config.lane?.index || null, metric: config.lane?.metric || 'cosine' };
+  return config;
+}
+export async function runAutoRagProbe({ root, config, engine, store, embedder = null, semantic = false, maxFiles = 25, maxChunks = 100, query = 'repository overview' } = {}) {
+  if (!engine?.planIndex || !engine?.runIndex || !engine?.retrieve) throw new TypeError('autorag_probe_engine_required');
+  if (semantic && !embedder) throw new Error('autorag_probe_semantic_adapter_required');
+  // Probes are isolated to a dedicated generation scope. A failed or successful
+  // probe therefore cannot replace a healthy normal indexing generation.
+  const probeConfig = structuredClone(config);
+  probeConfig.scope.name = `${config.scope.name}--probe`;
+  const plan = await engine.planIndex({ root, config: probeConfig, store, embed: semantic, limits: { maxFiles, maxChunks } });
+  if (plan.receipt.files > maxFiles || plan.receipt.chunks > maxChunks) throw new Error('autorag_probe_limits_not_enforced');
+  const result = await engine.runIndex({ root, config: probeConfig, store, embed: semantic, embedder, maxInputs: semantic ? maxChunks : 0, maxCharacters: 200000, limits: { maxFiles, maxChunks }, probe: true });
+  const contextPack = await engine.retrieve({ store, config: probeConfig, text: query, semantic, embedder, topK: 3, tokenBudget: 1200, generationId: result.generation_id });
+  return Object.freeze({ type: 'agentsam_autorag_probe_receipt', stages: ['discovery', 'source_read', 'chunk', 'structural_index', ...(semantic ? ['embed', 'vector_upsert'] : []), 'verify', 'query'], repository: config.repository_id, scope: config.scope, provider: config.embedding.provider, model: config.embedding.model, dimensions: config.embedding.dimensions, backend: config.lane?.backend || 'local_exact', files: result.files, chunks: result.chunks, generation: result.generation_id, git: result.git, merkle_root: result.merkle_root || null, published: result.published, query_result: contextPack.hits.slice(0, 1), paid_embeddings: false });
+}
+export function selectIntentRoute(routes, { repositoryId, accountId, intent } = {}) {
+  const matches = (routes || []).filter(route => route?.is_active !== false && route.intent_key === intent);
+  return matches.find(route => clean(route.repository_id) === clean(repositoryId) && clean(repositoryId)) || matches.find(route => clean(route.account_id) === clean(accountId) && !clean(route.repository_id)) || matches.find(route => !clean(route.account_id) && !clean(route.repository_id)) || null;
+}
+export async function routeCompanyQuestion({ question, companyAdapter, accountId, repositoryId, intent = 'code_question', limits = { repositories: 5, lanes: 3 } } = {}) {
+  if (!companyAdapter?.candidateRepositories) return { mode: 'local', repositories: repositoryId ? [repositoryId] : [], reason: 'company_graph_unavailable' };
+  const route = await companyAdapter.route?.({ accountId, repositoryId, intent }) || null;
+  const repositories = (await companyAdapter.candidateRepositories({ question, accountId, repositoryId, intent, route })).slice(0, limits.repositories);
+  return { mode: 'company_graph', intent, route, repositories, lane_limit: limits.lanes };
+}

package/packages/agentsam-knowledge/src/backends/index.js

@@ -0,0 +1,26 @@
+const clean = value => String(value || '').trim();
+function profileGuard(profile, supported) {
+  if (!supported.includes(profile?.backend)) throw new Error(`backend_profile_mismatch:${profile?.backend}`);
+  if (!Number.isInteger(profile?.dimensions) || profile.dimensions < 1) throw new Error('backend_dimensions_required');
+}
+function bindingBackend(id, required) {
+  return Object.freeze({
+    id, capabilities: () => ({ id, explicit_resource_required: true, supported: true }),
+    prepare(profile, context = {}) { profileGuard(profile, [id]); for (const key of required) if (!clean(context[key] || profile[key])) throw new Error(`backend_${id}_${key}_required`); return { id, dimensions: profile.dimensions }; },
+    async upsert(records, context = {}) { const backend = context.backend; if (!backend?.upsert) throw new Error(`backend_runtime_unavailable:${id}`); return backend.upsert(records); },
+    async delete(ids, context = {}) { const backend = context.backend; if (!backend?.delete) throw new Error(`backend_runtime_unavailable:${id}`); return backend.delete(ids); },
+    async query(vector, options, context = {}) { const backend = context.backend; if (!backend?.query) throw new Error(`backend_runtime_unavailable:${id}`); return backend.query(vector, options); },
+    async verify(ids, context = {}) { const backend = context.backend; if (!backend?.verify) throw new Error(`backend_runtime_unavailable:${id}`); return backend.verify(ids); },
+    health: async context => ({ id, operational: Boolean(context?.backend) }),
+  });
+}
+export function createBackendRegistry() {
+  const local = Object.freeze({
+    id: 'local_exact', capabilities: () => ({ id: 'local_exact', exact: true, external_resource_required: false }),
+    prepare(profile) { profileGuard(profile, ['local_exact']); return { id: 'local_exact', dimensions: profile.dimensions }; },
+    async upsert(records, context = {}) { if (!context.store?.cachePut) throw new Error('backend_runtime_unavailable:local_exact'); for (const record of records) await context.store.cachePut(record.id, record.vector); return { upserted: records.length }; },
+    async delete() { return { deleted: 0 }; }, async query() { throw new Error('backend_query_owned_by_knowledge_store'); }, async verify() { return { verified: true }; }, health: async () => ({ id: 'local_exact', operational: true }),
+  });
+  const adapters = new Map([['local_exact', local], ['postgres_pgvector', bindingBackend('postgres_pgvector', ['resource'])], ['supabase_pgvector', bindingBackend('supabase_pgvector', ['resource'])], ['cloudflare_vectorize', bindingBackend('cloudflare_vectorize', ['binding', 'index'])]]);
+  return Object.freeze({ ids: () => [...adapters.keys()], get(id) { const item = adapters.get(clean(id)); if (!item) throw new Error(`backend_unsupported:${id}`); return item; }, capabilities: () => [...adapters.values()].map(adapter => adapter.capabilities()) });
+}

package/packages/agentsam-knowledge/src/index.js

@@ -0,0 +1,3 @@
+export * from './providers/index.js';
+export * from './backends/index.js';
+export * from './autorag/index.js';

package/packages/agentsam-knowledge/src/providers/index.js

@@ -0,0 +1,107 @@
+const clean = value => String(value || '').trim();
+const finiteVector = (vector, dimensions) => {
+  if (!Array.isArray(vector) || vector.length !== dimensions || vector.some(value => typeof value !== 'number' || !Number.isFinite(value))) {
+    throw new Error(`provider_vector_dimension_mismatch:${Array.isArray(vector) ? vector.length : 'invalid'}!=${dimensions}`);
+  }
+  return vector;
+};
+
+function httpAdapter({ id, env, models, request, credentials = env, allowAnyModel = false }) {
+  return Object.freeze({
+    id,
+    capabilities: () => ({ id, operational: Boolean(credentials()), models, credentials: credentials() ? 'available' : 'missing' }),
+    validate(profile) {
+      if (clean(profile?.provider) !== id) throw new Error(`provider_profile_mismatch:${id}`);
+      if (!allowAnyModel && !models.includes(clean(profile?.model))) throw new Error(`provider_model_unsupported:${id}:${profile?.model}`);
+      if (!Number.isInteger(profile?.dimensions) || profile.dimensions < 1) throw new Error('provider_dimensions_required');
+      if (!credentials()) throw new Error(`provider_credentials_unavailable:${id}`);
+    },
+    dimensions: profile => profile?.dimensions,
+    async embedDocuments(inputs, profile, context = {}) { this.validate(profile); return Promise.all(inputs.map(input => request(String(input), profile, { ...context, kind: 'document' }))); },
+    async embedQuery(input, profile, context = {}) { this.validate(profile); return request(String(input), profile, { ...context, kind: 'query' }); },
+    health: async () => ({ id, operational: Boolean(credentials()), models, credentials: credentials() ? 'available' : 'missing' }),
+  });
+}
+
+export function createFixtureProvider({ dimensions = 3 } = {}) {
+  const vector = text => {
+    const bytes = Buffer.from(String(text)); const values = Array.from({ length: dimensions }, () => 0);
+    for (let i = 0; i < bytes.length; i++) values[i % dimensions] += (bytes[i] % 23) + 1;
+    const norm = Math.hypot(...values) || 1;
+    return values.map(value => value / norm);
+  };
+  return Object.freeze({
+    id: 'fixture', capabilities: () => ({ id: 'fixture', operational: true, deterministic: true, models: ['deterministic'] }),
+    validate(profile) { if (profile?.provider !== 'fixture') throw new Error('provider_profile_mismatch:fixture'); if (profile.dimensions !== dimensions) throw new Error(`provider_vector_dimension_mismatch:${profile.dimensions}!=${dimensions}`); },
+    dimensions: profile => profile?.dimensions,
+    async embedDocuments(inputs, profile) { this.validate(profile); return inputs.map(vector); },
+    async embedQuery(input, profile) { this.validate(profile); return vector(input); },
+    health: async () => ({ id: 'fixture', operational: true }),
+  });
+}
+
+export function createGeminiProvider({ apiKey = process.env.GEMINI_API_KEY, fetchImpl = globalThis.fetch } = {}) {
+  return httpAdapter({ id: 'gemini', env: 'GEMINI_API_KEY', models: ['gemini-embedding-2'], credentials: () => apiKey,
+    request: async (text, profile, context) => {
+      const prefix = context.kind === 'query' ? `task: ${profile.parameters?.task || 'code retrieval'} | query: ` : 'title: none | text: ';
+      const response = await fetchImpl(`https://generativelanguage.googleapis.com/v1beta/models/${profile.model}:embedContent`, { method: 'POST', headers: { 'content-type': 'application/json', 'x-goog-api-key': apiKey }, body: JSON.stringify({ model: `models/${profile.model}`, content: { parts: [{ text: prefix + text }] }, outputDimensionality: profile.dimensions }) });
+      if (!response.ok) throw new Error(`provider_request_failed:gemini:${response.status}`);
+      return finiteVector((await response.json()).embedding?.values, profile.dimensions);
+    } });
+}
+
+export function createOpenAIProvider({ apiKey = process.env.OPENAI_API_KEY, fetchImpl = globalThis.fetch } = {}) {
+  return httpAdapter({ id: 'openai', env: 'OPENAI_API_KEY', models: ['text-embedding-3-small', 'text-embedding-3-large'], credentials: () => apiKey,
+    request: async (text, profile) => {
+      const response = await fetchImpl('https://api.openai.com/v1/embeddings', { method: 'POST', headers: { 'content-type': 'application/json', authorization: `Bearer ${apiKey}` }, body: JSON.stringify({ model: profile.model, input: text, dimensions: profile.dimensions }) });
+      if (!response.ok) throw new Error(`provider_request_failed:openai:${response.status}`);
+      return finiteVector((await response.json()).data?.[0]?.embedding, profile.dimensions);
+    } });
+}
+
+export function createWorkersAiProvider({ binding } = {}) {
+  return Object.freeze({
+    id: 'workers-ai', capabilities: () => ({ id: 'workers-ai', operational: Boolean(binding?.run), execution: 'authenticated-runtime' }),
+    validate(profile) { if (profile?.provider !== 'workers-ai') throw new Error('provider_profile_mismatch:workers-ai'); if (!binding?.run) throw new Error('provider_credentials_unavailable:workers-ai'); },
+    dimensions: profile => profile?.dimensions,
+    async embedDocuments(inputs, profile) { this.validate(profile); return Promise.all(inputs.map(input => binding.run(profile.model, { text: [input] }).then(result => finiteVector(result?.data?.[0] || result?.[0], profile.dimensions)))); },
+    async embedQuery(input, profile) { return (await this.embedDocuments([input], profile))[0]; },
+    health: async () => ({ id: 'workers-ai', operational: Boolean(binding?.run), execution: 'authenticated-runtime' }),
+  });
+}
+
+export function createOllamaProvider({ endpoint = process.env.OLLAMA_HOST || 'http://127.0.0.1:11434', fetchImpl = globalThis.fetch, models } = {}) {
+  // Model allowlist is advisory only — live `ollama list` / tags are authoritative at selection time.
+  const known = Array.isArray(models) && models.length ? models : ['mxbai-embed-large', 'nomic-embed-text'];
+  return httpAdapter({
+    id: 'ollama',
+    env: 'OLLAMA_HOST',
+    models: known,
+    allowAnyModel: true,
+    credentials: () => endpoint,
+    request: async (text, profile) => {
+      const response = await fetchImpl(new URL('/api/embed', endpoint), {
+        method: 'POST',
+        headers: { 'content-type': 'application/json' },
+        body: JSON.stringify({ model: profile.model, input: text }),
+      });
+      if (!response.ok) throw new Error(`provider_request_failed:ollama:${response.status}`);
+      return finiteVector((await response.json()).embeddings?.[0], profile.dimensions);
+    },
+  });
+}
+
+export function createProviderRegistry(options = {}) {
+  const adapters = new Map([
+    ['fixture', createFixtureProvider(options.fixture)],
+    ['gemini', createGeminiProvider(options.gemini)],
+    ['openai', createOpenAIProvider(options.openai)],
+    ['workers-ai', createWorkersAiProvider(options.workersAi)],
+    ['ollama', createOllamaProvider(options.ollama)],
+  ]);
+  return Object.freeze({
+    ids: () => [...adapters.keys()],
+    get(id) { const adapter = adapters.get(clean(id)); if (!adapter) throw new Error(`provider_unsupported:${id}`); return adapter; },
+    capabilities: async () => Promise.all([...adapters.values()].map(async adapter => adapter.health())),
+  });
+}

package/packages/agentsam-knowledge/test/autorag.test.mjs

@@ -0,0 +1,42 @@
+import assert from 'node:assert/strict';
+import test from 'node:test';
+import { createFixtureProvider, createProviderRegistry, createBackendRegistry, recommendAutoRag, safeAutoRagConfig, selectIntentRoute, routeCompanyQuestion } from '../src/index.js';
+
+test('provider registry is explicit, deterministic, and fails closed', async () => {
+  const registry = createProviderRegistry({ fixture: { dimensions: 3 }, gemini: { apiKey: null }, openai: { apiKey: null } });
+  assert.deepEqual(registry.ids(), ['fixture', 'gemini', 'openai', 'workers-ai', 'ollama']);
+  const fixture = createFixtureProvider({ dimensions: 3 });
+  const profile = { provider: 'fixture', model: 'deterministic', dimensions: 3 };
+  assert.equal((await fixture.embedQuery('hello', profile)).length, 3);
+  assert.throws(() => registry.get('not-a-provider'), /provider_unsupported/);
+  assert.equal((await registry.capabilities()).find(item => item.id === 'gemini').operational, false);
+});
+
+test('backend registry requires explicit resources and dimensions', () => {
+  const registry = createBackendRegistry();
+  assert.deepEqual(registry.get('local_exact').prepare({ backend: 'local_exact', dimensions: 3 }), { id: 'local_exact', dimensions: 3 });
+  assert.throws(() => registry.get('cloudflare_vectorize').prepare({ backend: 'cloudflare_vectorize', dimensions: 3 }), /binding_required/);
+  assert.throws(() => registry.get('unknown'), /backend_unsupported/);
+});
+
+test('recommendation preserves local defaults and never serializes credentials', () => {
+  const discovery = { repository: { identity: 'local:demo' }, scopes: ['src', 'docs'] };
+  const recommendation = recommendAutoRag({ discovery, purpose: 'code' });
+  const config = safeAutoRagConfig({ recommendation, repositoryId: 'local:demo' });
+  assert.deepEqual(config.scope.include, ['src']);
+  assert.equal(config.embedding.provider, 'none');
+  assert.equal(config.lane.backend, 'local_exact');
+  assert.equal(JSON.stringify(config).includes('API_KEY'), false);
+});
+
+test('routing is repository first, then account, then portable default', async () => {
+  const routes = [
+    { intent_key: 'code_question', account_id: '', repository_id: '', id: 'default' },
+    { intent_key: 'code_question', account_id: 'account', repository_id: '', id: 'account' },
+    { intent_key: 'code_question', account_id: 'account', repository_id: 'repo', id: 'repository' },
+  ];
+  assert.equal(selectIntentRoute(routes, { intent: 'code_question', accountId: 'account', repositoryId: 'repo' }).id, 'repository');
+  assert.equal(selectIntentRoute(routes, { intent: 'code_question', accountId: 'account', repositoryId: 'other' }).id, 'account');
+  const routed = await routeCompanyQuestion({ question: 'where is auth?', repositoryId: 'repo', companyAdapter: { candidateRepositories: async () => ['repo', 'related', 'unrelated'] } });
+  assert.deepEqual(routed.repositories, ['repo', 'related', 'unrelated']);
+});

package/packages/agentsam-nav/README.md

@@ -0,0 +1,40 @@
+# @inneranimalmedia/agentsam-nav
+
+One navigation context, two independently mountable surfaces. The package owns navigation presentation and transient interaction state. The host owns routing, accounts, projects, conversations, persistence, and all network access.
+
+```tsx
+import { Nav } from '@inneranimalmedia/agentsam-nav';
+import '@inneranimalmedia/agentsam-nav/theme.css';
+
+<Nav.Provider value={navigation} theme="dark" accentColor="#8B5CF6" peekable defaultOpen={false}>
+  <Nav.Sidenav />
+  <main>
+    <Nav.Topbar rightSlot={<YourWorkspaceControls />} />
+    {children}
+  </main>
+</Nav.Provider>
+```
+
+Either surface can be omitted. `Nav.Topbar` accepts `children` to replace its composition, or `contextSlot`, `modeSlot`, and `rightSlot`. Named parts include `TopbarLogo`, `ProjectContext`, `TopbarSpacer`, `FilesResources`, `ConversationActions`, `ShareButton`, `AccountSwitcher`, `OverflowMenu`, and `ModeSwitcher`. `Nav.Scope` applies the same appearance to a consumer's layout.
+
+## Configuration
+
+`value` supplies `brand`, `mode`, `project`, `conversation`, `projects`, `conversations`, `account`, `accounts`, `destinations`, menu action arrays, and callbacks. Every identity has a stable `id`. Routing uses consumer callbacks and has no router dependency. `brand` contains `name`, `logo`, and `home`. Destinations accept an icon node, label, and either `href` or `onSelect`.
+
+Menus use accessible keyboard navigation, collision handling, Escape dismissal, and restored trigger focus. Mobile navigation is a modal drawer. Hover expansion also supports focus. Persistence is deliberately external. `useNav()` exposes shell state and actions for custom controls.
+
+## Appearance contract
+
+`theme` is `dark`, `light`, or `system`. `accentColor` controls focus and selected control outlines. `tokens` customizes semantic roles rather than arbitrary selectors: `canvas`, `sidebar`, `surface`, `popover`, `text`, `muted`, `border`, `hover`, `selected`, `danger`, `font`, `label-size`, `meta-size`, `row-height`, `radius`, `menu-radius`, `shadow`, `width`, and `rail-width`.
+
+Defaults: 56px topbar/rail, 264px expanded sidenav, 14px labels, 12px metadata, 36px rows, 8px controls, 14px menus. Touch controls expand to 44px. Each surface and portal carries its own theme, so a light commerce host can embed a dark AgentSam shell without changing the host document. Supply complete, contrast-checked token sets when changing colorways. Brand identity, theme, accent, and route configuration remain separate.
+
+## Plain JavaScript hosts
+
+`mountNav` from the `/browser` export mounts React portals into host elements while retaining one provider. Pass `sidenav` and/or `topbar` DOM elements plus provider options. The return value supplies `update(options)` and `unmount()`. The optional `browser.global.js` bundle exposes `AgentSamNav.mountNav` and includes its own React runtime for non-React hosts. Load `theme.css` once. Do not use the bundled runtime inside an existing React tree; use the normal peer-dependent React exports there.
+
+## Boundaries
+
+No composer, model picker, plugin registry, message renderer, upload transport, browser, terminal, editor, or execution runtime is included. Their controls can be supplied as slots. Menu actions are callbacks; the package does not pretend unavailable operations work. The legacy low-level exports remain available; their stylesheet is `/legacy.css`.
+
+Build with `npm run build`; validate with `npm test` and `npm pack`. Distribution contains JavaScript, declarations, scoped CSS, and the browser adapter. Registry publication is a separate release action.

package/packages/agentsam-nav/dist/Nav.d.ts

@@ -0,0 +1,43 @@
+import { type HTMLAttributes } from 'react';
+import { NavCollapsible, NavCollapsibleContent, NavCollapsibleTrigger } from './NavCollapsible.js';
+import { NavContent } from './NavContent.js';
+import { NavFooter } from './NavFooter.js';
+import { NavGroup, NavGroupLabel } from './NavGroup.js';
+import { NavHeader } from './NavHeader.js';
+import { NavMenu, NavMenuButton, NavMenuChevron, NavMenuItem, NavMenuSub, NavMenuSubButton } from './NavMenu.js';
+import { NavProvider } from './NavProvider.js';
+import { NavTrigger } from './NavTrigger.js';
+import { NavScope, NavSidenav, NavTopbar, NavTopbarLogo, NavTopbarSpacer, NavProjectContext, NavAccountSwitcher, NavFilesResources, NavPinnedSummary, NavConversationActions, NavShareButton, NavOverflowMenu, NavModeSwitcher } from './Surfaces.js';
+declare function NavRoot({ className, children, ...props }: HTMLAttributes<HTMLElement>): import("react").JSX.Element;
+export declare const Nav: typeof NavRoot & {
+    Scope: typeof NavScope;
+    Sidenav: typeof NavSidenav;
+    Topbar: typeof NavTopbar;
+    TopbarLogo: typeof NavTopbarLogo;
+    TopbarSpacer: typeof NavTopbarSpacer;
+    ProjectContext: typeof NavProjectContext;
+    AccountSwitcher: typeof NavAccountSwitcher;
+    FilesResources: typeof NavFilesResources;
+    PinnedSummary: typeof NavPinnedSummary;
+    ConversationActions: typeof NavConversationActions;
+    ShareButton: typeof NavShareButton;
+    OverflowMenu: typeof NavOverflowMenu;
+    ModeSwitcher: typeof NavModeSwitcher;
+    Provider: typeof NavProvider;
+    Header: typeof NavHeader;
+    Content: typeof NavContent;
+    Footer: typeof NavFooter;
+    Group: typeof NavGroup;
+    GroupLabel: typeof NavGroupLabel;
+    Menu: typeof NavMenu;
+    MenuItem: typeof NavMenuItem;
+    MenuButton: typeof NavMenuButton;
+    MenuSub: typeof NavMenuSub;
+    MenuSubButton: typeof NavMenuSubButton;
+    MenuChevron: typeof NavMenuChevron;
+    Collapsible: typeof NavCollapsible;
+    CollapsibleTrigger: typeof NavCollapsibleTrigger;
+    CollapsibleContent: typeof NavCollapsibleContent;
+    Trigger: typeof NavTrigger;
+};
+export {};

package/packages/agentsam-nav/dist/NavCollapsible.d.ts

@@ -0,0 +1,10 @@
+import { type ButtonHTMLAttributes, type HTMLAttributes, type ReactElement, type ReactNode } from 'react';
+export declare function NavCollapsible({ children, defaultOpen }: {
+    children: ReactNode;
+    defaultOpen?: boolean;
+}): import("react").JSX.Element;
+export declare function NavCollapsibleTrigger({ render, children, className, ...props }: ButtonHTMLAttributes<HTMLButtonElement> & {
+    render?: ReactElement;
+    children?: ReactNode;
+}): import("react").JSX.Element;
+export declare function NavCollapsibleContent({ className, ...props }: HTMLAttributes<HTMLDivElement>): import("react").JSX.Element;

package/packages/agentsam-nav/dist/NavContent.d.ts

@@ -0,0 +1,2 @@
+import type { HTMLAttributes } from 'react';
+export declare function NavContent({ className, ...props }: HTMLAttributes<HTMLDivElement>): import("react").JSX.Element;

package/packages/agentsam-nav/dist/NavFooter.d.ts

@@ -0,0 +1,2 @@
+import type { HTMLAttributes } from 'react';
+export declare function NavFooter({ className, ...props }: HTMLAttributes<HTMLDivElement>): import("react").JSX.Element;

package/packages/agentsam-nav/dist/NavGroup.d.ts

@@ -0,0 +1,3 @@
+import type { HTMLAttributes } from 'react';
+export declare function NavGroup({ className, ...props }: HTMLAttributes<HTMLElement>): import("react").JSX.Element;
+export declare function NavGroupLabel({ className, ...props }: HTMLAttributes<HTMLParagraphElement>): import("react").JSX.Element;

package/packages/agentsam-nav/dist/NavHeader.d.ts

@@ -0,0 +1,2 @@
+import type { HTMLAttributes } from 'react';
+export declare function NavHeader({ className, ...props }: HTMLAttributes<HTMLDivElement>): import("react").JSX.Element;

package/packages/agentsam-nav/dist/NavMenu.d.ts

@@ -0,0 +1,22 @@
+import type { ButtonHTMLAttributes, HTMLAttributes, ReactNode } from 'react';
+export declare function NavMenu({ className, ...props }: HTMLAttributes<HTMLUListElement>): import("react").JSX.Element;
+export declare function NavMenuItem({ className, ...props }: HTMLAttributes<HTMLLIElement>): import("react").JSX.Element;
+export type NavMenuButtonProps = ButtonHTMLAttributes<HTMLButtonElement> & {
+    icon?: unknown;
+    active?: boolean;
+    itemId?: string;
+    children: ReactNode;
+};
+export declare function NavMenuButton({ icon: Icon, active, itemId, className, children, ...props }: NavMenuButtonProps): import("react").JSX.Element;
+export declare function NavMenuSub({ className, ...props }: HTMLAttributes<HTMLUListElement>): import("react").JSX.Element;
+export type NavMenuSubButtonProps = {
+    href?: string;
+    active?: boolean;
+    className?: string;
+    children?: unknown;
+    onClick?: (event: React.MouseEvent<HTMLAnchorElement>) => void;
+};
+export declare function NavMenuSubButton({ active, className, children, ...props }: NavMenuSubButtonProps): import("react").JSX.Element;
+export declare function NavMenuChevron({ className }: {
+    className?: string;
+}): import("react").JSX.Element;

package/packages/agentsam-nav/dist/NavProvider.d.ts

@@ -0,0 +1,35 @@
+import { type PropsWithChildren } from 'react';
+import type { NavTheme, NavValue, NavTokens } from './contracts.js';
+export type NavContextValue = {
+    data: NavValue;
+    tokens: NavTokens;
+    theme: NavTheme;
+    accentColor: string;
+    menu: string | null;
+    setMenu: (menu: string | null) => void;
+    open: boolean;
+    isMobile: boolean;
+    isPeeking: boolean;
+    peekable: boolean;
+    resizable: boolean;
+    width: number;
+    mobileBreakpoint: number;
+    setOpen: (open: boolean) => void;
+    toggle: () => void;
+    close: () => void;
+    setPeeking: (peeking: boolean) => void;
+    setWidth: (width: number) => void;
+    scrollToItem: (itemId: string) => void;
+};
+export type NavProviderProps = PropsWithChildren<{
+    value?: NavValue;
+    tokens?: NavTokens;
+    theme?: NavTheme;
+    accentColor?: string;
+    defaultOpen?: boolean;
+    mobileBreakpoint?: number;
+    peekable?: boolean;
+    resizable?: boolean;
+}>;
+export declare function NavProvider({ children, value: data, tokens, theme, accentColor, defaultOpen, mobileBreakpoint, peekable, resizable, }: NavProviderProps): import("react").JSX.Element;
+export declare function useNav(): NavContextValue;

package/packages/agentsam-nav/dist/NavTrigger.d.ts

@@ -0,0 +1,2 @@
+import type { ButtonHTMLAttributes } from 'react';
+export declare function NavTrigger({ className, 'aria-label': ariaLabel, ...props }: ButtonHTMLAttributes<HTMLButtonElement>): import("react").JSX.Element;

package/packages/agentsam-nav/dist/Surfaces.d.ts

@@ -0,0 +1,41 @@
+import { type CSSProperties, type HTMLAttributes, type ReactNode } from 'react';
+import type { NavAccount, NavAction } from './contracts.js';
+export declare function useNavStyle(): CSSProperties;
+export declare function NavScope({ className, style, ...props }: HTMLAttributes<HTMLDivElement>): import("react").JSX.Element;
+/** The portal carries its own theme, so standalone surfaces never depend on body CSS. */
+export declare function NavOverflowMenu({ label, actions, children, id: suppliedId, align }: {
+    label?: string;
+    actions?: NavAction[];
+    children?: ReactNode;
+    id?: string;
+    align?: 'start' | 'center' | 'end';
+}): import("react").JSX.Element;
+export declare function NavTopbarLogo({ variant, onClick, toggle }: {
+    variant?: 'mark' | 'expanded';
+    onClick?: () => void;
+    toggle?: boolean;
+}): import("react").JSX.Element;
+export declare function NavProjectContext(): import("react").JSX.Element;
+export declare function NavTopbarSpacer(): import("react").JSX.Element;
+export declare function NavFilesResources(): import("react").JSX.Element;
+export declare function NavPinnedSummary(): import("react").JSX.Element | null;
+export declare function NavConversationActions(): import("react").JSX.Element;
+export declare function NavShareButton(): import("react").JSX.Element | null;
+export declare function NavAccountSwitcher({ accounts, activeAccountId, onAccountChange, expanded }: {
+    accounts?: NavAccount[];
+    activeAccountId?: string;
+    onAccountChange?: (id: string) => void;
+    expanded?: boolean;
+}): import("react").JSX.Element;
+export declare function NavModeSwitcher(): import("react").JSX.Element;
+export declare function NavTopbar({ children, rightSlot, modeSlot, contextSlot, startup, className, showNavigationTrigger, showAccount, }: {
+    children?: ReactNode;
+    rightSlot?: ReactNode;
+    modeSlot?: ReactNode;
+    contextSlot?: ReactNode;
+    startup?: boolean;
+    className?: string;
+    showNavigationTrigger?: boolean;
+    showAccount?: boolean;
+}): import("react").JSX.Element;
+export declare function NavSidenav(): import("react").JSX.Element;

package/packages/agentsam-nav/dist/browser.d.ts

@@ -0,0 +1,11 @@
+import type { NavProviderProps } from './NavProvider.js';
+export interface MountNavOptions extends Omit<NavProviderProps, 'children'> {
+    sidenav?: HTMLElement;
+    topbar?: HTMLElement;
+    startup?: boolean;
+}
+/** Plain HTML integration. Both portals are descendants of the same provider. */
+export declare function mountNav(options: MountNavOptions): {
+    update(next: Partial<MountNavOptions>): void;
+    unmount(): void;
+};