@inneranimalmedia/agentsam-sdk 2.0.0 → 2.2.0

package/src/lib/deploy-receipt/index.js

@@ -0,0 +1,246 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { execFileSync } from 'node:child_process';
+import { randomBytes } from 'node:crypto';
+import { buildMerkleTree, diffTrees, readSnapshot, validateSnapshot } from '../merkle/index.js';
+import { normalizePolicy } from '../merkle/policy.js';
+
+export const DEFAULT_DEPLOY_EXCLUDES = Object.freeze([
+  '.agentsam/deploy-merkle',
+  '.wrangler',
+  'coverage',
+  '.cache',
+  '.turbo',
+  '.env',
+  '.env.local',
+  '.env.cloudflare',
+  '.env.cloudflare.local',
+  '.env.production',
+  '.env.production.local',
+  '.env.development',
+  '.env.development.local',
+  '.env.test',
+  '.env.test.local',
+  '.env.staging',
+  '.env.preview',
+  '.env.docker',
+  '.dev.vars',
+  '.npmrc',
+  '.deploy-dashboard-source-fingerprint.json',
+  '.deploy-pipeline-stats.json',
+  '.deploy-r2-delta-stats.json',
+  '.deploy-r2-static-hashes.json',
+  '.deploy-route-stats.json',
+  '.deploy-sw-tiered-manifest.json',
+  '.deploy-worker-fingerprint.json',
+  '.deploy-worker-stats.json',
+]);
+
+function git(root, args) {
+  try {
+    return execFileSync('git', ['-C', root, ...args], { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] }).trim();
+  } catch {
+    return '';
+  }
+}
+
+function portableRelative(root, target) {
+  const relative = path.relative(root, target).split(path.sep).join('/');
+  return relative && !relative.startsWith('../') && relative !== '..' ? relative : '';
+}
+
+function paths(root, stateDir) {
+  const state = path.resolve(stateDir || path.join(root, '.agentsam/deploy-merkle'));
+  return {
+    stateDir: state,
+    pendingSnapshot: path.join(state, 'pending.snapshot.json'),
+    pendingReceipt: path.join(state, 'pending.receipt.json'),
+    latestSnapshot: path.join(state, 'latest.snapshot.json'),
+    latestReceipt: path.join(state, 'latest.receipt.json'),
+    historyDir: path.join(state, 'history'),
+  };
+}
+
+async function atomicJson(filename, value) {
+  await fs.mkdir(path.dirname(filename), { recursive: true });
+  const temp = `${filename}.tmp-${randomBytes(8).toString('hex')}`;
+  try {
+    await fs.writeFile(temp, JSON.stringify(value, null, 2) + '\n', { flag: 'wx', mode: 0o600 });
+    await fs.rename(temp, filename);
+  } finally {
+    await fs.rm(temp, { force: true }).catch(() => {});
+  }
+}
+
+async function loadSnapshot(input) {
+  if (!input) return null;
+  if (typeof input === 'string') return readSnapshot(input);
+  return validateSnapshot(input);
+}
+
+function sourceDirty(root, stateDir) {
+  const raw = git(root, ['status', '--porcelain=v1', '--untracked-files=all']);
+  if (!raw) return false;
+  const stateRelative = portableRelative(root, stateDir);
+  return raw.split('\n').some((line) => {
+    const candidate = line.slice(3).replace(/^"|"$/g, '').replace(/\\/g, '/');
+    return !(stateRelative && (candidate === stateRelative || candidate.startsWith(`${stateRelative}/`)));
+  });
+}
+
+function gitMetadata(root) {
+  return {
+    git_sha: git(root, ['rev-parse', 'HEAD']),
+    git_branch: git(root, ['rev-parse', '--abbrev-ref', 'HEAD']),
+    repository: git(root, ['remote', 'get-url', 'origin']),
+  };
+}
+
+function truncateChanges(changes, maxChangedFiles) {
+  const files = changes.map((change) => change.path);
+  if (files.length <= maxChangedFiles) return files;
+  return [...files.slice(0, maxChangedFiles), `__truncated__:+${files.length - maxChangedFiles}_more`];
+}
+
+export async function captureDeployReceipt({
+  root = '.',
+  project,
+  stateDir,
+  baselineSnapshot,
+  baselineSource,
+  include = [],
+  exclude = [],
+  maxChangedFiles = 100,
+  metadata = {},
+} = {}) {
+  const rootPath = await fs.realpath(root);
+  const state = paths(rootPath, stateDir);
+  const dirty = sourceDirty(rootPath, state.stateDir);
+  const stateRelative = portableRelative(rootPath, state.stateDir);
+  const policy = normalizePolicy({
+    include,
+    exclude: [...new Set([
+      ...DEFAULT_DEPLOY_EXCLUDES,
+      ...(stateRelative ? [stateRelative] : []),
+      ...exclude,
+    ])],
+  });
+
+  await fs.mkdir(state.historyDir, { recursive: true });
+
+  let baseline = null;
+  let resolvedBaselineSource = baselineSource || 'none';
+  if (baselineSnapshot) {
+    try {
+      baseline = await loadSnapshot(baselineSnapshot);
+      resolvedBaselineSource = baselineSource || 'provided';
+    } catch {
+      resolvedBaselineSource = 'invalid';
+    }
+  } else {
+    try {
+      baseline = await readSnapshot(state.latestSnapshot);
+      resolvedBaselineSource = 'local';
+    } catch (error) {
+      if (error?.code !== 'ENOENT') resolvedBaselineSource = 'invalid';
+    }
+  }
+
+  const tree = await buildMerkleTree(rootPath, { policy });
+  await atomicJson(state.pendingSnapshot, tree);
+
+  let diff = null;
+  if (baseline) {
+    try {
+      diff = diffTrees(baseline, tree);
+    } catch {
+      baseline = null;
+      resolvedBaselineSource = 'invalid';
+    }
+  }
+
+  const gitInfo = gitMetadata(rootPath);
+  const receipt = {
+    format: 'agentsam-deploy-merkle',
+    version: 1,
+    engine: 'agentsam-merkle-v1',
+    status: 'captured',
+    project: project || path.basename(rootPath),
+    repository: gitInfo.repository || null,
+    git_sha: gitInfo.git_sha || null,
+    git_branch: gitInfo.git_branch || null,
+    captured_at: new Date().toISOString(),
+    root_hash: tree.rootHash,
+    previous_root_hash: baseline?.rootHash || null,
+    has_baseline: Boolean(baseline),
+    baseline_source: resolvedBaselineSource,
+    working_tree_dirty: dirty,
+    stats: tree.stats,
+    diff_stats: diff?.stats || null,
+    changed_files: diff ? truncateChanges(diff.changes, maxChangedFiles) : [],
+    ...metadata,
+  };
+  await atomicJson(state.pendingReceipt, receipt);
+  return { receipt, snapshot: tree, paths: state };
+}
+
+export async function finalizeDeployReceipt({
+  root = '.',
+  stateDir,
+  status,
+  deploymentId,
+  workerVersionId,
+  metadata = {},
+} = {}) {
+  if (!['success', 'failed'].includes(status)) throw new Error('Deploy receipt status must be success or failed.');
+  const rootPath = await fs.realpath(root);
+  const state = paths(rootPath, stateDir);
+  const [pendingReceipt, pendingSnapshot] = await Promise.all([
+    JSON.parse(await fs.readFile(state.pendingReceipt, 'utf8')),
+    readSnapshot(state.pendingSnapshot),
+  ]).catch((error) => {
+    if (error?.code === 'ENOENT') throw new Error('No pending deploy receipt capture exists.');
+    throw error;
+  });
+  if (pendingReceipt?.format !== 'agentsam-deploy-merkle' || pendingReceipt?.status !== 'captured') {
+    throw new Error('Pending deploy receipt is invalid or already finalized.');
+  }
+  if (pendingReceipt.root_hash !== pendingSnapshot.rootHash) throw new Error('Pending receipt/snapshot root mismatch.');
+
+  const completed = new Date().toISOString();
+  const receipt = {
+    ...pendingReceipt,
+    ...metadata,
+    status,
+    completed_at: completed,
+    deployment_id: deploymentId || null,
+    worker_version_id: workerVersionId || null,
+  };
+  const stamp = completed.replace(/[-:.]/g, '').replace('Z', 'Z');
+  const sha = (receipt.git_sha || 'unknown').replace(/[^A-Za-z0-9._-]/g, '-');
+  const rootSlug = receipt.root_hash.replace(/^sha256:/, '');
+  const historyReceipt = path.join(state.historyDir, `${stamp}-${sha}-${rootSlug.slice(0, 12)}-${status}.receipt.json`);
+  await atomicJson(historyReceipt, receipt);
+
+  if (status === 'success') {
+    await fs.copyFile(state.pendingSnapshot, state.latestSnapshot);
+    await atomicJson(state.latestReceipt, receipt);
+  }
+  return { receipt, snapshot: pendingSnapshot, paths: { ...state, historyReceipt } };
+}
+
+export async function showLatestDeployReceipt({ root = '.', stateDir } = {}) {
+  const rootPath = await fs.realpath(root);
+  const state = paths(rootPath, stateDir);
+  try {
+    return JSON.parse(await fs.readFile(state.latestReceipt, 'utf8'));
+  } catch (error) {
+    if (error?.code === 'ENOENT') return null;
+    throw error;
+  }
+}
+
+export const captureCheckpoint = captureDeployReceipt;
+export async function promoteCheckpoint(options = {}) {
+  return finalizeDeployReceipt({ ...options, status: 'success' });
+}

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/deploy-receipt.test.mjs

@@ -0,0 +1,91 @@
+import assert from 'node:assert/strict';
+import { test } from 'node:test';
+import fs from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+import { execFileSync, spawnSync } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+import {
+  captureDeployReceipt,
+  finalizeDeployReceipt,
+  showLatestDeployReceipt,
+} from '../src/lib/deploy-receipt/index.js';
+
+const cli = fileURLToPath(new URL('../src/cli.js', import.meta.url));
+
+async function fixture(t) {
+  const root = await fs.mkdtemp(path.join(os.tmpdir(), 'agentsam-deploy-receipt-'));
+  t.after(() => fs.rm(root, { recursive: true, force: true }));
+  execFileSync('git', ['init', '-q', root]);
+  execFileSync('git', ['-C', root, 'config', 'user.email', 'receipt-test@example.invalid']);
+  execFileSync('git', ['-C', root, 'config', 'user.name', 'Receipt Test']);
+  await fs.mkdir(path.join(root, 'src'), { recursive: true });
+  await fs.writeFile(path.join(root, 'src/app.js'), 'export const value = 1;\n');
+  execFileSync('git', ['-C', root, 'add', '.']);
+  execFileSync('git', ['-C', root, 'commit', '-qm', 'fixture']);
+  return root;
+}
+
+function run(args, cwd) {
+  return spawnSync(process.execPath, [cli, 'deploy-receipt', ...args], { cwd, encoding: 'utf8', timeout: 15000 });
+}
+
+test('successful finalize advances baseline while failure preserves the last trusted tree', async (t) => {
+  const root = await fixture(t);
+  const first = await captureDeployReceipt({ root, project: 'fixture' });
+  assert.equal(first.receipt.has_baseline, false);
+  assert.equal(first.receipt.baseline_source, 'none');
+  assert.equal(first.receipt.working_tree_dirty, false);
+  assert.ok(!first.snapshot.entries.some((entry) => entry.path.startsWith('.agentsam/deploy-merkle')));
+
+  const promoted = await finalizeDeployReceipt({ root, status: 'success', deploymentId: 'dep_1' });
+  assert.equal(promoted.receipt.status, 'success');
+  assert.equal(promoted.receipt.deployment_id, 'dep_1');
+  assert.equal((await showLatestDeployReceipt({ root })).root_hash, first.receipt.root_hash);
+
+  const clean = await captureDeployReceipt({ root, project: 'fixture' });
+  assert.equal(clean.receipt.has_baseline, true);
+  assert.equal(clean.receipt.baseline_source, 'local');
+  assert.deepEqual(clean.receipt.diff_stats, { unchanged: 1, modified: 0, added: 0, removed: 0 });
+  assert.deepEqual(clean.receipt.changed_files, []);
+  assert.equal(clean.receipt.root_hash, first.receipt.root_hash);
+  assert.equal(clean.receipt.working_tree_dirty, false, 'runtime receipt state must not make the source tree dirty');
+
+  await fs.writeFile(path.join(root, 'src/app.js'), 'export const value = 2;\n');
+  const changed = await captureDeployReceipt({ root, project: 'fixture' });
+  assert.equal(changed.receipt.working_tree_dirty, true);
+  assert.deepEqual(changed.receipt.diff_stats, { unchanged: 0, modified: 1, added: 0, removed: 0 });
+  assert.deepEqual(changed.receipt.changed_files, ['src/app.js']);
+  assert.notEqual(changed.receipt.root_hash, first.receipt.root_hash);
+
+  await finalizeDeployReceipt({ root, status: 'failed', deploymentId: 'dep_2' });
+  assert.equal((await showLatestDeployReceipt({ root })).root_hash, first.receipt.root_hash, 'failed run must not advance baseline');
+
+  const retry = await captureDeployReceipt({ root, project: 'fixture' });
+  assert.deepEqual(retry.receipt.changed_files, ['src/app.js']);
+  await finalizeDeployReceipt({ root, status: 'success', deploymentId: 'dep_3' });
+  const settled = await captureDeployReceipt({ root, project: 'fixture' });
+  assert.deepEqual(settled.receipt.diff_stats, { unchanged: 1, modified: 0, added: 0, removed: 0 });
+  assert.deepEqual(settled.receipt.changed_files, []);
+});
+
+test('deploy-receipt CLI emits machine-readable capture/finalize/show receipts', async (t) => {
+  const root = await fixture(t);
+  const capture = run(['capture', '.', '--project', 'cli-fixture', '--json'], root);
+  assert.equal(capture.status, 0, capture.stderr);
+  const captured = JSON.parse(capture.stdout);
+  assert.equal(captured.format, 'agentsam-deploy-merkle');
+  assert.equal(captured.project, 'cli-fixture');
+  assert.equal(captured.status, 'captured');
+
+  const success = run(['success', '.', '--deployment-id', 'dep_cli', '--worker-version', 'worker_v1', '--json'], root);
+  assert.equal(success.status, 0, success.stderr);
+  const finalized = JSON.parse(success.stdout);
+  assert.equal(finalized.status, 'success');
+  assert.equal(finalized.deployment_id, 'dep_cli');
+  assert.equal(finalized.worker_version_id, 'worker_v1');
+
+  const show = run(['show', '.', '--json'], root);
+  assert.equal(show.status, 0, show.stderr);
+  assert.equal(JSON.parse(show.stdout).root_hash, finalized.root_hash);
+});

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: {