Version an agent in git

// npm install asteroid-odyssey
import { createHash } from 'node:crypto';
import { mkdir, readdir, readFile, rm, writeFile } from 'node:fs/promises';
import { dirname, join, relative } from 'node:path';
import { client, agentWorkflowHeadGetFiles } from 'asteroid-odyssey';

client.setConfig({
  baseUrl: 'https://odyssey.asteroid.ai/agents/v2',
  headers: { 'X-Api-Key': process.env.ASTEROID_API_KEY! },
});

// Every file under root, including .node-id and .sticky-note-id. Do not swap
// this for a glob unless it is configured to return dotfiles: an id file left
// out of the listing is deleted on push, and the node it identifies is
// recreated as new.
async function listFiles(dir: string, root = dir): Promise<string[]> {
  const entries = await readdir(dir, { withFileTypes: true });
  const nested = await Promise.all(
    entries.map((e) =>
      e.isDirectory()
        ? listFiles(join(dir, e.name), root)
        : Promise.resolve([relative(root, join(dir, e.name))]),
    ),
  );
  return nested.flat();
}

// The checksum of what is already on disk, or null when nothing is.
async function localChecksum(path: string): Promise<string | null> {
  try {
    return createHash('sha256').update(await readFile(path)).digest('hex');
  } catch {
    return null;
  }
}

export async function pull(agentId: string, root: string) {
  // The default mode: structural files arrive inline, agent files stay
  // references carrying a checksum. Asking for `all` would ship every blob as
  // base64 whether or not you already hold it.
  const { data, error } = await agentWorkflowHeadGetFiles({ path: { agentId } });
  if (error) throw new Error(`pull failed: ${JSON.stringify(error)}`);

  // Reconcile, do not wipe. Deleting only what the manifest no longer lists
  // drops a node deleted in the builder — which a write-only pull would leave
  // on disk for the next push to re-create — while keeping the blobs you hold.
  const remote = new Set(data!.files.map((f) => f.path));
  for (const path of await listFiles(root).catch(() => [])) {
    if (!remote.has(path)) await rm(join(root, path));
  }

  for (const file of data!.files) {
    const target = join(root, file.path);
    await mkdir(dirname(target), { recursive: true });

    // Structural content is inline already, so writing it costs nothing.
    if (file.content !== undefined) {
      await writeFile(target, file.content, 'utf-8');
      continue;
    }
    // An agent file you already hold needs no request at all.
    if (file.checksum && (await localChecksum(target)) === file.checksum) continue;
    if (file.contentBase64 !== undefined) {
      await writeFile(target, Buffer.from(file.contentBase64, 'base64'));
      continue;
    }
    // Never silently skip: a missing file becomes a deletion on the next push.
    if (!file.downloadUrl) throw new Error(`no content for ${file.path}`);
    const blob = await fetch(file.downloadUrl, {
      headers: { 'X-Api-Key': process.env.ASTEROID_API_KEY! },
    });
    if (!blob.ok) throw new Error(`download failed for ${file.path}: ${blob.status}`);
    await writeFile(target, Buffer.from(await blob.arrayBuffer()));
  }
  return { rev: data!.rev, contentHash: data!.contentHash };
}

# pip install asteroid-odyssey
import base64, hashlib, os
from pathlib import Path

import requests
from asteroid_odyssey import ApiClient, Configuration
from asteroid_odyssey.api.files_api import FilesApi

KEY = os.environ["ASTEROID_API_KEY"]
config = Configuration(api_key={"ApiKeyAuth": KEY})


def local_checksum(path: Path) -> str | None:
    """The checksum of what is already on disk, or None when nothing is."""
    if not path.is_file():
        return None
    return hashlib.sha256(path.read_bytes()).hexdigest()


def pull(agent_id: str, root: Path):
    # The default mode: structural files arrive inline, agent files stay
    # references carrying a checksum.
    with ApiClient(config) as api_client:
        tree = FilesApi(api_client).agent_workflow_head_get_files(agent_id=agent_id)

    # Reconcile, do not wipe: drop what the manifest no longer lists, and keep
    # the blobs you already hold.
    remote = {file.path for file in tree.files}
    for path in root.rglob("*"):
        if path.is_file() and str(path.relative_to(root)) not in remote:
            path.unlink()

    for file in tree.files:
        target = root / file.path
        target.parent.mkdir(parents=True, exist_ok=True)

        if file.content is not None:
            target.write_text(file.content, encoding="utf-8")
        elif file.checksum and local_checksum(target) == file.checksum:
            continue  # already held, no request needed
        elif file.content_base64 is not None:
            target.write_bytes(base64.b64decode(file.content_base64))
        elif file.download_url:
            # Over the inline budget. Fetch the blob itself.
            blob = requests.get(file.download_url, headers={"X-Api-Key": KEY})
            blob.raise_for_status()
            target.write_bytes(blob.content)
        else:
            raise RuntimeError(f"no content for {file.path}")

    return tree.rev, tree.content_hash

import { readFile } from 'node:fs/promises';
import { join } from 'node:path';
import {
  agentWorkflowHeadGetFiles,
  agentWorkflowHeadPatchFiles,
  agentWorkflowHeadPublishHead,
  agentWorkflowsGetFilesByVersion,
} from 'asteroid-odyssey';

// listFiles is the dotfile-safe walk from the pull example above.
export async function push(agentId: string, root: string) {
  const localPaths = await listFiles(root);

  const { data: head, error: readError } = await agentWorkflowHeadGetFiles({
    path: { agentId },
    query: { contents: 'none' }, // only the manifest is needed to get `rev`
  });
  if (readError) throw new Error(`read failed: ${JSON.stringify(readError)}`);

  const remotePaths = new Set(head!.files.map((f) => f.path));
  const writes = await Promise.all(
    localPaths.map(async (path) => ({
      path,
      contentBase64: (await readFile(join(root, path))).toString('base64'),
    })),
  );
  const deletes = [...remotePaths].filter((path) => !localPaths.includes(path));

  const { error: patchError } = await agentWorkflowHeadPatchFiles({
    path: { agentId },
    body: { baseRev: head!.rev, writes, deletes },
  });
  if (patchError) throw new Error(`patch failed: ${JSON.stringify(patchError)}`);

  const { data: published, error: publishError } = await agentWorkflowHeadPublishHead({
    path: { agentId },
  });
  if (publishError) throw new Error(`publish failed: ${JSON.stringify(publishError)}`);

  // Read the published version back for its hash. This is the value to record
  // against the commit — the drift check below compares against it.
  const { data: tree, error: hashError } = await agentWorkflowsGetFilesByVersion({
    path: { agentId, workflowId: published!.workflowId },
    query: { contents: 'none' },
  });
  if (hashError) throw new Error(`hash read failed: ${JSON.stringify(hashError)}`);

  return { version: published!.version, contentHash: tree!.contentHash };
}