agentvcs

Documentation

Overview

Package agentvcs implements a minimal jj-inspired version control system for tracking file changes across agent sessions. Each session produces a linear chain of immutable commits, enabling per-session changelogs and the ability to review or revert incremental work.

Index

• type Adapter
  • func NewAdapter(svc Service) *Adapter
  • func (a *Adapter) CreateSessionSnapshot(ctx context.Context, sessionID, snapshotType, description string) error
  • func (a *Adapter) Service() Service
• type Commit
• type CommitSummary
• type DiffEntry
• type DiffType
• type Service
  • func NewService() (Service, error)
• type SessionLog
• type Tree
• type TreeEntry

Types

type Adapter

type Adapter struct {
	// contains filtered or unexported fields
}

Adapter bridges the session package's SnapshotCreator interface with the agent-vcs Service. It maps snapshot types to agent-vcs operations:

• "start" → NewChange (initial commit for the session)
• "end" → Record (final delta commit)
• other → Record (intermediate delta commit)

func NewAdapter

func NewAdapter(svc Service) *Adapter

NewAdapter creates an Adapter wrapping the given Service.

func (*Adapter) CreateSessionSnapshot

func (a *Adapter) CreateSessionSnapshot(ctx context.Context, sessionID, snapshotType, description string) error

CreateSessionSnapshot satisfies session.SnapshotCreator.

func (*Adapter) Service

func (a *Adapter) Service() Service

Service returns the underlying agent-vcs Service for direct access.

type Commit

type Commit struct {
	ID               string `json:"id"`                           // Content-derived hash
	ParentID         string `json:"parent_id"`                    // Previous commit (empty for root)
	SessionID        string `json:"session_id"`                   // Owning agent session
	TreeID           string `json:"tree_id"`                      // Hash of the Tree object
	Description      string `json:"description"`                  // Human-readable label
	Author           string `json:"author"`                       // "agent" or user identifier
	CreatedAt        int64  `json:"created_at"`                   // Unix timestamp
	FileCount        int    `json:"file_count"`                   // Number of tracked files in the resulting tree
	TotalSize        int64  `json:"total_size"`                   // Sum of file sizes in the resulting tree
	ChangedFileCount int    `json:"changed_file_count,omitempty"` // Files changed vs parent for this commit
	ChangedTotalSize int64  `json:"changed_total_size,omitempty"` // Aggregate size of changed files for this commit
}

Commit is an immutable point-in-time snapshot of the working directory. Commits form a singly-linked list via ParentID within a session.

type CommitSummary

type CommitSummary struct {
	ID               string `json:"id"`
	ShortID          string `json:"short_id"` // First 12 hex chars
	ParentID         string `json:"parent_id,omitempty"`
	SessionID        string `json:"session_id"`
	Description      string `json:"description"`
	FileCount        int    `json:"file_count"`
	TotalSize        int64  `json:"total_size"`
	CreatedAt        int64  `json:"created_at"`
	ChangedFiles     int    `json:"changed_files"`      // Files changed vs parent
	ChangedTotalSize int64  `json:"changed_total_size"` // Aggregate size of changed files
}

CommitSummary is a lightweight view of a commit used in log listings.

type DiffEntry

type DiffEntry struct {
	Path    string   `json:"path"`
	Type    DiffType `json:"type"`
	OldHash string   `json:"old_hash,omitempty"`
	NewHash string   `json:"new_hash,omitempty"`
	OldSize int64    `json:"old_size,omitempty"`
	NewSize int64    `json:"new_size,omitempty"`
}

DiffEntry represents a single file change between two commits.

type DiffType

type DiffType string

DiffType describes a change between two commits.

const (
	DiffAdded    DiffType = "added"
	DiffModified DiffType = "modified"
	DiffDeleted  DiffType = "deleted"
)

type Service

type Service interface {
	pubsub.Suscriber[Commit]

	// NewChange creates the initial commit for a session, capturing the current
	// working directory state. Analogous to `jj new`.
	NewChange(ctx context.Context, sessionID, description string) (Commit, error)

	// Record snapshots the working directory and creates a new commit in the
	// session's chain if any files changed since the last commit. Returns the
	// new commit or the previous HEAD if nothing changed.
	Record(ctx context.Context, sessionID, description string) (Commit, error)

	// Log returns the ordered list of commits for a session (oldest first).
	Log(ctx context.Context, sessionID string) ([]CommitSummary, error)

	// GetCommit retrieves a single commit by ID.
	GetCommit(ctx context.Context, id string) (Commit, error)

	// GetTree retrieves a tree object by ID.
	GetTree(ctx context.Context, id string) (Tree, error)

	// Diff computes the file-level changes between two commits.
	Diff(ctx context.Context, commitID1, commitID2 string) ([]DiffEntry, error)

	// DiffFromParent computes the file-level changes between a commit and its parent.
	DiffFromParent(ctx context.Context, commitID string) ([]DiffEntry, error)

	// GetFileContent retrieves blob content by hash.
	GetFileContent(ctx context.Context, hash string) ([]byte, error)

	// ListSessions returns all session IDs that have at least one commit.
	ListSessions(ctx context.Context) ([]string, error)

	// SessionCommitCount returns the number of commits in a session.
	SessionCommitCount(ctx context.Context, sessionID string) (int, error)

	// Revert restores the working directory to the state captured in a commit.
	Revert(ctx context.Context, commitID string) error

	// Cleanup removes old sessions and orphan blobs.
	Cleanup(ctx context.Context, maxAgeDays, maxSessions int) error
}

Service defines the public API for agent-vcs.

func NewService

func NewService() (Service, error)

NewService creates a new agent-vcs service. It stores data alongside the old snapshots directory under the configured data directory.

type SessionLog

type SessionLog struct {
	SessionID string   `json:"session_id"`
	Commits   []string `json:"commits"` // Oldest first
	CreatedAt int64    `json:"created_at"`
	UpdatedAt int64    `json:"updated_at"`
}

SessionLog tracks the ordered list of commit IDs for one session.

type Tree

type Tree struct {
	ID      string      `json:"id"`      // SHA-256 of the serialised entries
	Entries []TreeEntry `json:"entries"` // Sorted list of tracked files
}

Tree represents the full file listing for a commit. It is stored separately so that identical trees across commits are deduplicated.

type TreeEntry

type TreeEntry struct {
	Path    string `json:"path"`             // Slash-separated relative path
	Hash    string `json:"hash,omitempty"`   // SHA-256 of file content
	Size    int64  `json:"size,omitempty"`   // File size in bytes
	ModTime int64  `json:"mod_time"`         // Last modification (Unix)
	IsDir   bool   `json:"is_dir,omitempty"` // Directory marker
}

TreeEntry is a single file (or directory marker) inside a Tree.