@inneranimalmedia/agentsam-sdk 2.1.0 → 2.2.0

package/src/knowledge/config.js

@@ -37,7 +37,8 @@ export function validateConfig(input) {
   allowed(c.embedding, ['provider', 'model', 'revision', 'dimensions', 'parameters'], 'embedding');
   allowed(c.storage, ['driver', 'connection_env'], 'storage');
   if (c.version !== 1) throw new Error('Unsupported knowledge configuration version.');
-  for (const key of ['repository_id', 'workspace_id']) if (typeof c[key] !== 'string' || !c[key].trim()) throw new Error(`${key} is required.`);
+  if (typeof c.repository_id !== 'string' || !c.repository_id.trim()) throw new Error('repository_id is required.');
+  if (c.workspace_id != null && (typeof c.workspace_id !== 'string' || !c.workspace_id.trim())) throw new Error('workspace_id must be a non-empty string when present.');
   if (typeof c.scope?.name !== 'string' || !c.scope.name.trim() || !Array.isArray(c.scope.include) || !c.scope.include.length) throw new Error('A named scope with at least one include path is required.');
   c.scope.include = [...new Set(c.scope.include.map(relativeSelection))].sort();
   c.scope.exclude = [...new Set((c.scope.exclude || []).map(relativeSelection))].sort();
@@ -49,10 +50,9 @@ export function validateConfig(input) {
   if (c.storage.driver === 'postgres' && !/^[A-Z_][A-Z0-9_]*$/.test(c.storage.connection_env || '')) throw new Error('Postgres requires a connection_env name, never a connection string in config.');
   return c;
 }
-export function defaultConfig({ include = ['.'], exclude = [], scope = 'default', workspace = 'local', target = 'local', dimensions = 768 } = {}) {
+export function defaultConfig({ include = ['.'], exclude = [], scope = 'default', target = 'local', dimensions = 768 } = {}) {
   if (!['local', 'production'].includes(target)) throw new Error('target must be local or production.');
-  if (target === 'production' && workspace === 'local') throw new Error('Production requires an explicit workspace identifier.');
-  return validateConfig({ version: 1, repository_id: randomUUID(), workspace_id: workspace,
+  return validateConfig({ version: 1, repository_id: randomUUID(),
     scope: { name: scope, include, exclude }, chunking: { max_chars: 4000 },
     embedding: { provider: 'gemini', model: 'gemini-embedding-2', revision: '1', dimensions, parameters: { task: 'code retrieval' } },
     storage: target === 'local' ? { driver: 'sqlite' } : { driver: 'postgres', connection_env: 'AGENTSAM_DATABASE_URL' } });
@@ -65,5 +65,11 @@ export function initRepository(root, options = {}) {
   fs.writeFileSync(target, JSON.stringify(config, null, 2) + '\n', { flag: 'wx', mode: 0o600 });
   return config;
 }
-export const scopeKey = config => fingerprint([config.workspace_id, config.repository_id, config.scope.name]);
-export const cacheNamespace = config => fingerprint([config.workspace_id, config.repository_id]);
+// New portable configs are repository-scoped. Legacy configs that still carry
+// workspace_id retain their original namespace so existing local generations stay readable.
+export const scopeKey = config => config.workspace_id
+  ? fingerprint([config.workspace_id, config.repository_id, config.scope.name])
+  : fingerprint([config.repository_id, config.scope.name]);
+export const cacheNamespace = config => config.workspace_id
+  ? fingerprint([config.workspace_id, config.repository_id])
+  : fingerprint([config.repository_id]);

package/src/knowledge/contracts.js

@@ -8,7 +8,7 @@ export const KNOWLEDGE_OPERATIONS = Object.freeze({
 export function assertRetrievalQuery(value) {
   if (!value || typeof value !== "object") throw new TypeError("RetrievalQuery must be an object");
   if (!String(value.text || "").trim()) throw new TypeError("RetrievalQuery.text is required");
-  if (!String(value.workspace_id || "").trim()) throw new TypeError("RetrievalQuery.workspace_id is required");
+  if (value.workspace_id != null && !String(value.workspace_id).trim()) throw new TypeError("RetrievalQuery.workspace_id must be non-empty when present");
   const topK = value.top_k ?? 12;
   if (!Number.isInteger(topK) || topK < 1 || topK > 100) throw new RangeError("top_k must be 1..100");
   if (!Number.isInteger(value.token_budget ?? 8000) || (value.token_budget ?? 8000) < 256) throw new RangeError("token_budget must be at least 256");

package/src/knowledge/engine.js

@@ -113,6 +113,6 @@ export async function retrieve({ store, config: input, text, semantic = false, e
       metadata: { generation_id: generation.id, symbol: hit.symbol, content_hash: hit.content_hash, freshness: 'working tree not checked' } }); estimatedTokens += tokens;
     if (hits.length === topK) break;
   }
-  return createContextPack({ queryId: randomUUID(), query: { text, workspace_id: config.workspace_id, top_k: topK, token_budget: tokenBudget }, hits,
+  return createContextPack({ queryId: randomUUID(), query: { text, top_k: topK, token_budget: tokenBudget }, hits,
     diagnostics: { generation_id: generation.id, source_hash: generation.source_hash, scope: generation.config.scope, mode: semantic ? 'semantic-exact' : 'lexical', freshness: 'snapshot; working tree not checked' } });
 }

package/src/knowledge/service/server.js

@@ -100,7 +100,7 @@ export async function startKnowledgeService({ stateDir, repositories, token, por
     });
     // 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 || registered.config.workspace_id !== payload.config.workspace_id || fingerprint(registered.config.scope) !== payload.registered_scope || (!allowEmbeddings && ((payload.request.embed && payload.request.operation !== 'plan') || payload.request.semantic))) {
+    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 });
@@ -124,7 +124,7 @@ export async function startKnowledgeService({ stateDir, repositories, token, por
       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.workspace_id, payload.config.repository_id, key]) : null;
+      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.');

package/src/lib/git-context.js

@@ -66,7 +66,9 @@ export function resolveGitContext(options = {}) {
     ? preferredRemote
     : availableRemotes[0] || preferredRemote;
   const remoteUrl = runGit(root, ['remote', 'get-url', remote], { required: false });
-  const revisionSha = runGit(root, ['rev-parse', 'HEAD']);
+  // A newly initialized repository can have an unborn HEAD. Repository identity
+  // and local inspection must still work before the first commit.
+  const revisionSha = runGit(root, ['rev-parse', 'HEAD'], { required: false }) || null;
   const branch = runGit(root, ['branch', '--show-current'], { required: false }) || null;
   const status = runGit(root, ['status', '--porcelain=v1'], { required: false });
 

package/src/presets/index.js

@@ -0,0 +1,20 @@
+import catalog from '../../protocol/presets/catalog.json' with { type: 'json' };
+
+export const PRESET_CATALOG_VERSION = catalog.schema_version;
+
+export function getPresetCatalog() { return structuredClone(catalog); }
+export function listPresets() { return Object.values(catalog.presets).map((row) => structuredClone(row)); }
+export function getPreset(id) {
+  const row = catalog.presets[String(id || '').trim().toLowerCase()];
+  return row ? structuredClone(row) : null;
+}
+export function resolvePreset(id = 'fullstack') {
+  const preset = getPreset(id);
+  if (!preset) throw new Error(`unknown_preset:${id}; expected ${Object.keys(catalog.presets).join(',')}`);
+  return preset;
+}
+export function listAddons() { return Object.values(catalog.addons).map((row) => structuredClone(row)); }
+export function getAddon(id) {
+  const row = catalog.addons[String(id || '').trim().toLowerCase()];
+  return row ? structuredClone(row) : null;
+}

package/src/repository/index.js

@@ -0,0 +1,4 @@
+export { repositorySnapshot } from '../capabilities/repository-snapshot.js';
+export { buildMerkleTree, diffTrees, readSnapshot, saveSnapshot, validateSnapshot } from '../lib/merkle/index.js';
+export { resolveGitContext, tryResolveGitContext, normalizeGitRemote } from '../lib/git-context.js';
+export { buildRetrievalPlan, createContextPack } from '../knowledge/index.js';

package/test/agent-capabilities.test.mjs

@@ -0,0 +1,67 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import { createCapabilityAdapter } from '../src/agent/index.js';
+import { buildRepositoryAuditPacket, runRepositoryAudit } from '../src/agent/repository-audit.js';
+
+const snapshot = {
+  schema_version: 1,
+  capability: 'repository.snapshot',
+  snapshot_id: 'rsnap_0123456789abcdef01234567',
+  content_hash: `sha256:${'a'.repeat(64)}`,
+  repository: { repository_id: 'github:owner/repo', provider: 'github', full_name: 'owner/repo', branch: 'main', revision_sha: 'b'.repeat(40), dirty: false },
+  tree: { merkle_root: `sha256:${'c'.repeat(64)}`, stats: { files: 10 } },
+  intelligence: {
+    summary: { file_count: 10, total_lines: 500 },
+    languages: [{ language: 'JavaScript', files: 7 }],
+    manifests: [{ path: 'package.json', kind: 'node' }],
+    top_level: [{ path: 'src', files: 7 }],
+    pressure_points: [{ path: 'src', pressure_score: 70 }],
+  },
+  packages: [{ path: 'package.json', name: 'demo', version: '1.0.0' }],
+  knowledge: { configured: false },
+  deploy: null,
+};
+
+test('repository audit packet is bounded read-only evidence', () => {
+  const packet = buildRepositoryAuditPacket({ snapshot, focus: ['packages'], evidenceBudget: 1000 });
+  assert.equal(packet.primitive, 'repository.audit');
+  assert.equal(packet.rules.read_only, true);
+  assert.equal(packet.rules.may_edit, false);
+  assert.equal(packet.snapshot_id, snapshot.snapshot_id);
+  assert.ok(JSON.stringify(packet.evidence).length <= 4000);
+});
+
+test('repository audit uses injected reasoning and validates read-only output', async () => {
+  const audit = await runRepositoryAudit({
+    snapshot,
+    reasoner: async packet => ({
+      summary: `Audited ${packet.evidence.repository.full_name}`,
+      packages: packet.evidence.packages,
+      notable_combinations: ['snapshot + audit'],
+      findings: [{ severity: 'low', finding: 'example' }],
+      recommended_routes: ['inspect capability registry'],
+      evidence_refs: [packet.evidence_index.packages],
+    }),
+  });
+  assert.equal(audit.primitive, 'repository.audit');
+  assert.equal(audit.summary, 'Audited owner/repo');
+  assert.equal(audit.packages.length, 1);
+  assert.deepEqual(audit.commands, []);
+
+  await assert.rejects(() => runRepositoryAudit({ snapshot, reasoner: async () => ({ summary: 'bad', jobs: [] }) }), /mutation field: jobs/);
+});
+
+test('agent capability adapter exposes only executable tools by default', async () => {
+  const adapter = createCapabilityAdapter({
+    reasoner: async packet => ({ summary: 'ok', evidence_refs: [packet.evidence_index.summary] }),
+    handlers: { 'knowledge.search': async input => ({ query: input.text, hits: [] }) },
+  });
+  const names = adapter.toolDescriptors().map(row => row.name);
+  assert.ok(names.includes('repository.snapshot'));
+  assert.ok(names.includes('repository.audit'));
+  assert.ok(names.includes('knowledge.search'));
+  assert.equal(names.includes('knowledge.index'), false);
+  const result = await adapter.invoke('knowledge.search', { text: 'hello' });
+  assert.equal(result.capability_id, 'knowledge.search');
+  assert.deepEqual(result.result.hits, []);
+});

package/test/capabilities.test.mjs

@@ -0,0 +1,84 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { execFileSync } from 'node:child_process';
+import { getCapability, getCapabilityManifest, repositorySnapshot } from '../src/capabilities/index.js';
+import { getPreset, resolvePreset } from '../src/presets/index.js';
+
+const CLI = path.resolve('src/cli.js');
+
+function git(cwd, args) { return execFileSync('git', args, { cwd, encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'] }).trim(); }
+
+function fixture() {
+  const root = fs.mkdtempSync(path.join(os.tmpdir(), 'agentsam-capability-'));
+  fs.writeFileSync(path.join(root, 'package.json'), JSON.stringify({ name: 'snapshot-fixture', version: '1.0.0', type: 'module' }, null, 2));
+  fs.mkdirSync(path.join(root, 'src'));
+  fs.writeFileSync(path.join(root, 'src', 'index.js'), 'export const value = 1;\n');
+  git(root, ['init', '-q']);
+  git(root, ['config', 'user.email', 'test@example.com']);
+  git(root, ['config', 'user.name', 'AgentSam Test']);
+  git(root, ['add', '.']);
+  git(root, ['commit', '-qm', 'fixture']);
+  return root;
+}
+
+test('capability manifest exposes deterministic primitives without requiring a model', () => {
+  const manifest = getCapabilityManifest();
+  assert.equal(manifest.schema_version, 1);
+  assert.equal(getCapability('repository.snapshot').model_required, false);
+  assert.equal(getCapability('repository.snapshot').side_effects, 'none');
+  assert.equal(getCapability('knowledge.index').deterministic, true);
+});
+
+test('presets resolve to explicit feature/capability selections', () => {
+  assert.equal(getPreset('cms').lane, 'cms');
+  const preset = resolvePreset('prototype');
+  assert.deepEqual(preset.features, ['agent']);
+  assert.throws(() => resolvePreset('nope'), /unknown_preset/);
+});
+
+test('repository.snapshot composes deterministic evidence and content addressing', async t => {
+  const root = fixture();
+  t.after(() => fs.rmSync(root, { recursive: true, force: true }));
+  const one = await repositorySnapshot({ cwd: root, churnDays: 30 });
+  const two = await repositorySnapshot({ cwd: root, churnDays: 30 });
+  assert.equal(one.capability, 'repository.snapshot');
+  assert.match(one.snapshot_id, /^rsnap_[a-f0-9]{24}$/);
+  assert.match(one.content_hash, /^sha256:[a-f0-9]{64}$/);
+  assert.equal(one.content_hash, two.content_hash);
+  assert.equal(one.snapshot_id, two.snapshot_id);
+  assert.equal(one.repository.revision_sha, git(root, ['rev-parse', 'HEAD']));
+  assert.ok(one.tree.merkle_root);
+  assert.ok(one.intelligence.summary.file_count >= 2);
+  assert.equal(one.packages[0].name, 'snapshot-fixture');
+  assert.equal(one.knowledge.configured, false);
+});
+
+test('product UX creates a preset project, adds a feature, and inspects before first commit', t => {
+  const parent = fs.mkdtempSync(path.join(os.tmpdir(), 'agentsam-product-'));
+  t.after(() => fs.rmSync(parent, { recursive: true, force: true }));
+  execFileSync(process.execPath, [CLI, 'create', 'demo', '--preset', 'cms', '--target', 'local'], {
+    cwd: parent,
+    stdio: 'pipe',
+  });
+  const project = path.join(parent, 'demo');
+  const config = JSON.parse(fs.readFileSync(path.join(project, '.agentsam', 'config.json'), 'utf8'));
+  assert.equal(config.preset, 'cms');
+  assert.equal(config.lane, 'cms');
+  assert.deepEqual(config.features, ['cms', 'knowledge']);
+  assert.ok(config.capabilities.includes('repository.snapshot'));
+
+  execFileSync(process.execPath, [CLI, 'add', 'knowledge', '--cwd', project, '--json'], { stdio: 'pipe' });
+  const features = JSON.parse(fs.readFileSync(path.join(project, '.agentsam', 'features.json'), 'utf8'));
+  assert.equal(features.features.knowledge.selected, true);
+
+  const snapshot = JSON.parse(execFileSync(process.execPath, [CLI, 'inspect', '--cwd', project, '--json'], {
+    encoding: 'utf8',
+    stdio: ['ignore', 'pipe', 'pipe'],
+  }));
+  assert.equal(snapshot.capability, 'repository.snapshot');
+  assert.equal(snapshot.repository.revision_sha, null);
+  assert.ok(snapshot.tree.stats.files > 0);
+});

package/test/portable-context.test.mjs

@@ -1,7 +1,7 @@
 import test from 'node:test';
 import assert from 'node:assert/strict';
 import { execFileSync } from 'node:child_process';
-import { mkdtempSync, writeFileSync } from 'node:fs';
+import { mkdtempSync, realpathSync, writeFileSync } from 'node:fs';
 import { tmpdir } from 'node:os';
 import { join } from 'node:path';
 
@@ -39,6 +39,16 @@ test('resolveGitContext derives repository identity from Git without user/worksp
   assert.equal('userId' in ctx, false);
 });
 
+test('resolveGitContext supports an initialized repository before its first commit', () => {
+  const root = mkdtempSync(join(tmpdir(), 'agentsam-sdk-unborn-'));
+  execFileSync('git', ['init'], { cwd: root, stdio: 'ignore' });
+  writeFileSync(join(root, 'README.md'), '# unborn\n');
+  const ctx = resolveGitContext({ cwd: root });
+  assert.equal(ctx.root, realpathSync(root));
+  assert.equal(ctx.revisionSha, null);
+  assert.equal(ctx.dirty, true);
+});
+
 test('bridge headers authenticate only the machine principal', () => {
   const headers = buildBridgeHeaders({
     env: {