@amodalai/amodal 0.3.89 → 0.3.90

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@amodalai/amodal",
-  "version": "0.3.89",
+  "version": "0.3.90",
   "description": "Amodal CLI",
   "license": "MIT",
   "repository": {
@@ -27,12 +27,12 @@
     "react": "^19.2.4",
     "yargs": "^17.7.2",
     "zod": "^4.3.6",
-    "@amodalai/types": "0.3.89",
-    "@amodalai/core": "0.3.89",
-    "@amodalai/db": "0.3.89",
-    "@amodalai/runtime": "0.3.89",
-    "@amodalai/studio": "0.3.89",
-    "@amodalai/runtime-app": "0.3.89"
+    "@amodalai/types": "0.3.90",
+    "@amodalai/core": "0.3.90",
+    "@amodalai/db": "0.3.90",
+    "@amodalai/runtime": "0.3.90",
+    "@amodalai/studio": "0.3.90",
+    "@amodalai/runtime-app": "0.3.90"
   },
   "devDependencies": {
     "@types/node": "^20.11.24",

package/src/commands/build.test.ts

@@ -39,7 +39,7 @@ describe('runBuild', () => {
     expect(stderrWrites.some((s) => s.includes('amodal.json'))).toBe(true);
   });
 
-  it('builds a snapshot and writes resolved-config.json', async () => {
+  it('packs a tarball and writes a manifest', async () => {
     mkdirSync(testDir, {recursive: true});
     writeFileSync(join(testDir, 'amodal.json'), JSON.stringify({
       name: 'test-agent',
@@ -48,16 +48,21 @@ describe('runBuild', () => {
     }));
 
     const {runBuild} = await import('./build.js');
-    const outputPath = join(testDir, 'output.json');
-    const code = await runBuild({cwd: testDir, output: outputPath});
+    const outputDir = join(testDir, 'build-out');
+    const code = await runBuild({cwd: testDir, output: outputDir});
 
     expect(code).toBe(0);
-    expect(existsSync(outputPath)).toBe(true);
 
-    const snapshot = JSON.parse(readFileSync(outputPath, 'utf-8'));
-    expect(snapshot.deployId).toMatch(/^deploy-[0-9a-f]{7}$/);
-    expect(snapshot.config.name).toBe('test-agent');
-    expect(snapshot.source).toBe('cli');
-    expect(stderrWrites.some((s) => s.includes('Snapshot'))).toBe(true);
+    const tarballPath = join(outputDir, 'agent.tar.gz');
+    const manifestPath = join(outputDir, 'manifest.json');
+    expect(existsSync(tarballPath)).toBe(true);
+    expect(existsSync(manifestPath)).toBe(true);
+
+    const manifest = JSON.parse(readFileSync(manifestPath, 'utf-8'));
+    expect(typeof manifest.deployId).toBe('string');
+    expect(manifest.deployId.length).toBeGreaterThan(0);
+    expect(manifest.agentName).toBe('test-agent');
+    expect(manifest.source).toBe('cli');
+    expect(stderrWrites.some((s) => s.includes('Wrote tarball'))).toBe(true);
   });
 });

package/src/commands/build.ts

@@ -1,14 +1,16 @@
 /**
  * @license
- * Copyright 2025 Amodal Labs, Inc.
+ * Copyright 2026 Amodal Labs, Inc.
  * SPDX-License-Identifier: MIT
  */
 
-import {writeFileSync} from 'node:fs';
+import {writeFileSync, mkdirSync} from 'node:fs';
 import {join, resolve} from 'node:path';
 import {execSync} from 'node:child_process';
+import {randomUUID} from 'node:crypto';
 import type {CommandModule} from 'yargs';
-import {loadRepo, buildSnapshot, serializeSnapshot, snapshotSizeBytes} from '@amodalai/core';
+import {loadRepo} from '@amodalai/core';
+import type {ToolBuildManifest} from '@amodalai/types';
 import {buildToolTemplates} from './build-tools.js';
 import {findRepoRoot} from '../shared/repo-discovery.js';
 import {runValidate} from './validate.js';
@@ -20,8 +22,22 @@ export interface BuildOptions {
 }
 
 /**
- * Get the current user from git config or fallback.
+ * Audit + handoff metadata `amodal build` emits alongside the bundle
+ * tarball. Captures who built it, from where, against which commit —
+ * the minimum a runtime / platform needs without re-parsing the bundle.
  */
+export interface DeployManifest {
+  deployId: string;
+  createdAt: string;
+  createdBy: string;
+  source: 'cli' | 'github' | 'admin-ui';
+  commitSha?: string;
+  branch?: string;
+  message?: string;
+  agentName: string;
+  toolBuildManifest?: ToolBuildManifest;
+}
+
 function getCurrentUser(): string {
   try {
     return execSync('git config user.email', {encoding: 'utf-8'}).trim();
@@ -30,9 +46,6 @@ function getCurrentUser(): string {
   }
 }
 
-/**
- * Get the current git commit SHA, or undefined if not in a git repo.
- */
 function getGitSha(): string | undefined {
   try {
     return execSync('git rev-parse HEAD', {encoding: 'utf-8'}).trim();
@@ -41,14 +54,23 @@ function getGitSha(): string | undefined {
   }
 }
 
+function getGitBranch(): string | undefined {
+  try {
+    return execSync('git rev-parse --abbrev-ref HEAD', {encoding: 'utf-8'}).trim();
+  } catch {
+    return undefined;
+  }
+}
+
 /**
- * Build a deploy snapshot from the local repo.
+ * Build a deploy artifact (tarball + manifest) from the local repo.
  *
  * 1. Find repo root
  * 2. Validate configuration
- * 3. Load and resolve repo
- * 4. Build snapshot
- * 5. Write to output file
+ * 3. Load and resolve repo (verifies it parses)
+ * 4. Optionally build tool sandbox snapshots
+ * 5. Pack the repo (including `node_modules`) into a tarball
+ * 6. Write a manifest describing the build
  */
 export async function runBuild(options: BuildOptions = {}): Promise<number> {
   let repoPath: string;
@@ -68,7 +90,7 @@ export async function runBuild(options: BuildOptions = {}): Promise<number> {
     return 1;
   }
 
-  // Load repo
+  // Load repo to verify it parses cleanly
   process.stderr.write('[build] Loading repo...\n');
   let repo;
   try {
@@ -80,47 +102,65 @@ export async function runBuild(options: BuildOptions = {}): Promise<number> {
   }
 
   // Build tool sandbox snapshots if requested
-  let buildManifest;
+  let toolBuildManifest: ToolBuildManifest | undefined;
   if (options.tools && repo.tools.length > 0) {
     process.stderr.write(`[build] Building ${repo.tools.length} tool sandbox(es)...\n`);
-    buildManifest = await buildToolTemplates(repoPath, repo.tools);
+    toolBuildManifest = await buildToolTemplates(repoPath, repo.tools);
   } else if (options.tools && repo.tools.length === 0) {
     process.stderr.write('[build] No tools found in tools/ directory\n');
   }
 
-  // Build snapshot (includes tool metadata + build manifest if available)
-  const snapshot = buildSnapshot(repo, {
+  const outDir = options.output ? resolve(options.output) : join(repoPath, 'build');
+  mkdirSync(outDir, {recursive: true});
+
+  // Pack the repo into a tarball. Excludes things that don't belong in
+  // a deploy artifact: VCS dir, prior build output, environment files.
+  const tarballPath = join(outDir, 'agent.tar.gz');
+  process.stderr.write(`[build] Packing ${repoPath} → ${tarballPath}\n`);
+  try {
+    execSync(
+      `tar -czf "${tarballPath}" ` +
+      `--exclude='.git' --exclude='build' --exclude='.env' --exclude='.env.local' ` +
+      `-C "${repoPath}" .`,
+      {stdio: 'pipe'},
+    );
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    process.stderr.write(`[build] tar failed: ${msg}\n`);
+    return 1;
+  }
+
+  const manifest: DeployManifest = {
+    deployId: randomUUID(),
+    createdAt: new Date().toISOString(),
     createdBy: getCurrentUser(),
     source: 'cli',
-    commitSha: getGitSha(),
-    buildManifest,
-  });
-
-  // Serialize and write
-  const serialized = serializeSnapshot(snapshot);
-  const size = snapshotSizeBytes(serialized);
-  const outputPath = options.output
-    ? resolve(options.output)
-    : join(repoPath, 'resolved-config.json');
+    agentName: repo.config.name,
+    ...(getGitSha() ? {commitSha: getGitSha()} : {}),
+    ...(getGitBranch() ? {branch: getGitBranch()} : {}),
+    ...(toolBuildManifest ? {toolBuildManifest} : {}),
+  };
 
-  writeFileSync(outputPath, serialized);
+  const manifestPath = join(outDir, 'manifest.json');
+  writeFileSync(manifestPath, JSON.stringify(manifest, null, 2));
 
-  process.stderr.write(`[build] Snapshot ${snapshot.deployId} written to ${outputPath}\n`);
-  process.stderr.write(`[build] Size: ${(size / 1024).toFixed(1)} KB\n`);
-  process.stderr.write(`[build] Connections: ${Object.keys(snapshot.connections).length}, Skills: ${snapshot.skills.length}, Automations: ${snapshot.automations.length}, Knowledge: ${snapshot.knowledge.length}, Tools: ${repo.tools.length}\n`);
+  process.stderr.write(`[build] Wrote tarball ${tarballPath}\n`);
+  process.stderr.write(`[build] Wrote manifest ${manifestPath}\n`);
+  process.stderr.write(`[build] deployId=${manifest.deployId} commit=${manifest.commitSha ?? '(no git)'} branch=${manifest.branch ?? '-'}\n`);
+  process.stderr.write(`[build] Bundle: connections=${repo.connections.size + repo.externalConnections.size}, skills=${repo.skills.length}, automations=${repo.automations.length}, knowledge=${repo.knowledge.length}, tools=${repo.tools.length}\n`);
 
   return 0;
 }
 
 export const buildCommand: CommandModule = {
   command: 'build',
-  describe: 'Build a deploy snapshot from the local repo',
+  describe: 'Pack a deploy artifact (tarball + manifest) from the local repo',
   builder: (yargs) =>
     yargs
       .option('output', {
         type: 'string',
         alias: 'o',
-        describe: 'Output file path (default: resolved-config.json)',
+        describe: 'Output directory (default: ./build)',
       })
       .option('tools', {
         type: 'boolean',

package/src/commands/chat.ts

@@ -8,7 +8,7 @@ import type http from 'node:http';
 import {createElement} from 'react';
 import {render} from 'ink';
 import type {CommandModule} from 'yargs';
-import {createLocalServer, createSnapshotServer} from '@amodalai/runtime';
+import {createLocalServer, createBundleServer} from '@amodalai/runtime';
 import {findRepoRoot} from '../shared/repo-discovery.js';
 import {runConnectionPreflight, printPreflightTable} from '../shared/connection-preflight.js';
 import {ChatApp} from '../ui/ChatApp.js';
@@ -28,7 +28,7 @@ export interface ChatOptions {
  *
  * Three modes:
  *   --url <remote>    → connect to an already-running server (no local boot)
- *   --config <file>   → boot from a snapshot file
+ *   --config <dir>    → boot from an extracted bundle directory (offline replay)
  *   (default)         → boot from the local repo
  */
 export async function runChat(options: ChatOptions): Promise<void> {
@@ -57,9 +57,9 @@ export async function runChat(options: ChatOptions): Promise<void> {
   let repoPath: string | undefined;
 
   if (options.config) {
-    process.stderr.write(`[chat] Loading snapshot from ${options.config}\n`);
-    serverInstance = await createSnapshotServer({
-      snapshotPath: options.config,
+    process.stderr.write(`[chat] Loading bundle from ${options.config}\n`);
+    serverInstance = await createBundleServer({
+      bundlePath: options.config,
       port,
       host: '127.0.0.1',
     });

package/src/commands/serve.ts

@@ -1,20 +1,18 @@
 /**
  * @license
- * Copyright 2025 Amodal Labs, Inc.
+ * Copyright 2026 Amodal Labs, Inc.
  * SPDX-License-Identifier: MIT
  */
 
+import {execSync} from 'node:child_process';
+import {mkdtempSync, statSync} from 'node:fs';
+import {tmpdir} from 'node:os';
+import {join, resolve} from 'node:path';
 import type {CommandModule} from 'yargs';
-import {loadSnapshotFromFile, snapshotToBundle} from '@amodalai/core';
-import type {AgentBundle} from '@amodalai/core';
-import {createLocalServer, initLogLevel, interceptConsole} from '@amodalai/runtime';
-import {PlatformClient} from '../shared/platform-client.js';
+import {createBundleServer, initLogLevel, interceptConsole} from '@amodalai/runtime';
 
 export interface ServeOptions {
   config?: string;
-  platform?: boolean;
-  project?: string;
-  env?: string;
   port?: number;
   host?: string;
   verbose?: number;
@@ -24,83 +22,59 @@ export interface ServeOptions {
 const DEFAULT_PORT = 3847;
 
 /**
- * Load a repo from a snapshot file or from the platform.
+ * Resolve the `--config` argument to a directory `createBundleServer`
+ * can load via `loadRepoFromDisk`. Accepts either a directory or a
+ * `.tar.gz` tarball produced by `amodal build` (extracted to a tempdir).
  */
-async function loadFromSource(options: ServeOptions): Promise<AgentBundle | null> {
-  if (options.config) {
-    process.stderr.write(`[serve] Loading snapshot from ${options.config}...\n`);
-    try {
-      const snapshot = await loadSnapshotFromFile(options.config);
-      const repo = snapshotToBundle(snapshot, options.config);
-      process.stderr.write(`[serve] Loaded ${snapshot.deployId} (${snapshot.skills.length} skills, ${Object.keys(snapshot.connections).length} connections)\n`);
-      return repo;
-    } catch (err) {
-      const msg = err instanceof Error ? err.message : String(err);
-      process.stderr.write(`[serve] Failed to load snapshot: ${msg}\n`);
-      return null;
-    }
+function resolveBundlePath(configArg: string): string {
+  const absolute = resolve(configArg);
+  const stat = statSync(absolute);
+  if (stat.isDirectory()) return absolute;
+
+  if (absolute.endsWith('.tar.gz') || absolute.endsWith('.tgz')) {
+    const dir = mkdtempSync(join(tmpdir(), 'amodal-serve-'));
+    process.stderr.write(`[serve] Extracting ${absolute} → ${dir}\n`);
+    execSync(`tar -xzf "${absolute}" -C "${dir}"`, {stdio: 'pipe'});
+    return dir;
   }
 
-  if (options.platform) {
-    process.stderr.write('[serve] Fetching active snapshot from platform...\n');
-    let client: PlatformClient;
-    try {
-      client = await PlatformClient.create();
-    } catch (err) {
-      const msg = err instanceof Error ? err.message : String(err);
-      process.stderr.write(`[serve] ${msg}\n`);
-      return null;
-    }
-
-    const environment = options.env ?? 'production';
-    try {
-      const snapshot = await client.getActiveSnapshot(environment);
-      const repo = snapshotToBundle(snapshot, `platform:${environment}`);
-      process.stderr.write(`[serve] Loaded ${snapshot.deployId} from ${environment}\n`);
-      return repo;
-    } catch (err) {
-      const msg = err instanceof Error ? err.message : String(err);
-      process.stderr.write(`[serve] Failed to fetch snapshot: ${msg}\n`);
-      return null;
-    }
-  }
-
-  process.stderr.write('[serve] Specify --config <file> or --platform to load a snapshot.\n');
-  return null;
+  throw new Error(`Unsupported --config target: ${absolute} (expected a directory or .tar.gz tarball)`);
 }
 
-/**
- * Load an agent runtime from a snapshot (file or platform) and start the server.
- *
- * Returns the loaded repo, or exits with error.
- */
-export async function runServe(options: ServeOptions): Promise<AgentBundle | null> {
+export async function runServe(options: ServeOptions): Promise<boolean> {
   initLogLevel({verbosity: options.verbose ?? 0, quiet: options.quiet ?? false});
   interceptConsole();
 
-  const repo = await loadFromSource(options);
-  if (!repo) return null;
+  if (!options.config) {
+    process.stderr.write('[serve] --config <dir-or-tarball> is required.\n');
+    return false;
+  }
+
+  let bundlePath: string;
+  try {
+    bundlePath = resolveBundlePath(options.config);
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    process.stderr.write(`[serve] ${msg}\n`);
+    return false;
+  }
 
-  // Start the runtime server
   const port = options.port ?? DEFAULT_PORT;
   const host = options.host ?? '0.0.0.0';
 
-  process.stderr.write(`[serve] Starting server on ${host}:${port}...\n`);
+  process.stderr.write(`[serve] Starting bundle server from ${bundlePath} on ${host}:${port}...\n`);
 
   try {
-    const server = await createLocalServer({
-      repoPath: repo.origin,
+    const server = await createBundleServer({
+      bundlePath,
       port,
       host,
-      hotReload: false,
       corsOrigin: '*',
     });
 
     await server.start();
+    process.stderr.write(`[serve] Serving at http://${host}:${port}\n`);
 
-    process.stderr.write(`[serve] Agent "${repo.config.name}" serving at http://${host}:${port}\n`);
-
-    // Graceful shutdown
     const shutdown = async (signal: string): Promise<void> => {
       process.stderr.write(`\n[serve] Received ${signal}, shutting down...\n`);
       await server.stop();
@@ -112,33 +86,21 @@ export async function runServe(options: ServeOptions): Promise<AgentBundle | nul
   } catch (err) {
     const msg = err instanceof Error ? err.message : String(err);
     process.stderr.write(`[serve] Failed to start server: ${msg}\n`);
-    return null;
+    return false;
   }
 
-  return repo;
+  return true;
 }
 
 export const serveCommand: CommandModule = {
   command: 'serve',
-  describe: 'Load and serve an agent from a snapshot',
+  describe: 'Serve an agent from a built bundle (directory or .tar.gz from `amodal build`)',
   builder: (yargs) =>
     yargs
       .option('config', {
         type: 'string',
-        describe: 'Path to resolved-config.json snapshot file',
-      })
-      .option('platform', {
-        type: 'boolean',
-        describe: 'Fetch active snapshot from platform',
-        default: false,
-      })
-      .option('project', {
-        type: 'string',
-        describe: 'Platform project name',
-      })
-      .option('env', {
-        type: 'string',
-        describe: 'Platform environment (default: production)',
+        describe: 'Path to a bundle directory or .tar.gz tarball',
+        demandOption: true,
       })
       .option('port', {
         type: 'number',
@@ -161,15 +123,9 @@ export const serveCommand: CommandModule = {
         default: false,
       }),
   handler: async (argv) => {
-    const repo = await runServe({
-      // eslint-disable-next-line @typescript-eslint/no-unsafe-type-assertion
-      config: argv['config'] as string | undefined,
-      // eslint-disable-next-line @typescript-eslint/no-unsafe-type-assertion
-      platform: argv['platform'] as boolean | undefined,
-      // eslint-disable-next-line @typescript-eslint/no-unsafe-type-assertion
-      project: argv['project'] as string | undefined,
+    const ok = await runServe({
       // eslint-disable-next-line @typescript-eslint/no-unsafe-type-assertion
-      env: argv['env'] as string | undefined,
+      config: argv['config'] as string,
       // eslint-disable-next-line @typescript-eslint/no-unsafe-type-assertion
       port: argv['port'] as number | undefined,
       // eslint-disable-next-line @typescript-eslint/no-unsafe-type-assertion
@@ -179,9 +135,6 @@ export const serveCommand: CommandModule = {
       // eslint-disable-next-line @typescript-eslint/no-unsafe-type-assertion
       quiet: argv['quiet'] as boolean,
     });
-    if (!repo) {
-      process.exit(1);
-    }
-    // Server is running — process stays alive until SIGTERM/SIGINT
+    if (!ok) process.exit(1);
   },
 };

package/src/e2e-commands.test.ts

@@ -147,15 +147,20 @@ describe('E2E Commands: Local repo', () => {
 
   // --- build ---
 
-  it('should build a snapshot from the repo', async () => {
-    const outputPath = join(repoDir, 'test-snapshot.json');
-    const code = await runBuild({cwd: repoDir, output: outputPath});
+  it('should pack a tarball + manifest from the repo', async () => {
+    const outputDir = join(repoDir, 'test-build');
+    const code = await runBuild({cwd: repoDir, output: outputDir});
     expect(code).toBe(0);
-    expect(existsSync(outputPath)).toBe(true);
 
-    const snapshot = JSON.parse(readFileSync(outputPath, 'utf-8')) as Record<string, unknown>;
-    expect(snapshot['deployId']).toBeDefined();
-    expect((snapshot['config'] as Record<string, unknown>)['name']).toBe('e2e-commands-test');
+    const tarballPath = join(outputDir, 'agent.tar.gz');
+    const manifestPath = join(outputDir, 'manifest.json');
+    expect(existsSync(tarballPath)).toBe(true);
+    expect(existsSync(manifestPath)).toBe(true);
+
+    const manifest = JSON.parse(readFileSync(manifestPath, 'utf-8')) as Record<string, unknown>;
+    expect(manifest['deployId']).toBeDefined();
+    expect(manifest['agentName']).toBe('e2e-commands-test');
+    expect(manifest['source']).toBe('cli');
   });
 
   // --- docker init ---
@@ -272,16 +277,12 @@ describe.skipIf(!hasDb)('E2E Commands: Runtime', () => {
     await runEval({cwd: repoDir});
   });
 
-  // --- snapshot server ---
-
-  it('should boot a snapshot server and serve health', async () => {
-    const snapshotPath = join(repoDir, 'cmd-test-snapshot.json');
-    const buildCode = await runBuild({cwd: repoDir, output: snapshotPath});
-    expect(buildCode).toBe(0);
+  // --- bundle server ---
 
-    const {createSnapshotServer} = await import('@amodalai/runtime');
-    const snapServer = await createSnapshotServer({
-      snapshotPath,
+  it('should boot a bundle server and serve health', async () => {
+    const {createBundleServer} = await import('@amodalai/runtime');
+    const snapServer = await createBundleServer({
+      bundlePath: repoDir,
       port: 0,
       host: '127.0.0.1',
     });
@@ -295,7 +296,7 @@ describe.skipIf(!hasDb)('E2E Commands: Runtime', () => {
       expect(resp.ok).toBe(true);
       const data = (await resp.json()) as Record<string, unknown>;
       expect(data['status']).toBe('ok');
-      expect(data['mode']).toBe('snapshot');
+      expect(data['mode']).toBe('bundle');
       expect(data['agent_name']).toBe('e2e-commands-test');
     } finally {
       await snapServer.stop();

package/src/shared/platform-client.test.ts

@@ -41,42 +41,6 @@ describe('PlatformClient', () => {
     expect(client).toBeDefined();
   });
 
-  it('uploads snapshot via POST', async () => {
-    const mockResponse = {
-      id: 'deploy-abc1234',
-      environment: 'production',
-      isActive: true,
-      createdAt: new Date().toISOString(),
-      createdBy: 'test',
-      source: 'cli',
-      snapshotSize: 1024,
-    };
-
-    globalThis.fetch = vi.fn().mockResolvedValue({
-      ok: true,
-      json: () => Promise.resolve(mockResponse),
-    });
-
-    const client = new PlatformClient({url: 'http://localhost:4000', apiKey: 'key'});
-    const result = await client.uploadSnapshot({
-      deployId: 'deploy-abc1234',
-      createdAt: new Date().toISOString(),
-      createdBy: 'test',
-      source: 'cli',
-      config: {name: 'test', version: '1.0', models: {main: {provider: 'a', model: 'b'}}},
-      connections: {},
-      skills: [],
-      automations: [],
-      knowledge: [],
-    });
-
-    expect(result.id).toBe('deploy-abc1234');
-     
-    const fetchCall = (globalThis.fetch as ReturnType<typeof vi.fn>).mock.calls[0] as [string, RequestInit];
-    expect(fetchCall[0]).toBe('http://localhost:4000/api/snapshot-deployments');
-    expect(fetchCall[1].method).toBe('POST');
-  });
-
   it('lists deployments via GET', async () => {
     globalThis.fetch = vi.fn().mockResolvedValue({
       ok: true,