agent-package-manager

Package manager for agent-contracts DSL. Manages shared agent team definitions stored in GitHub private repositories with an npm-like UX.

Overview

agent-pkg CLI lets you share and version agent-contracts DSL packages across projects using GitHub repositories as a registry backend. Package versions are tracked in a registry manifest (agent-pkg.registry.json) with commit SHAs and content hashes for integrity verification.

GitHub registry repo              Local project
┌───────────────────────────┐     ┌──────────────────────────┐
│ agent-pkg.registry.json   │     │ agent_modules/            │
│ packages/                 │ add/│   backend-api/            │
│   backend-api/            │────►│   frontend/               │
│   frontend/               │sync │ agent_overrides/          │
│   police/                 │     │ agent-pkg.json            │
└───────────────────────────┘     │ agent-pkg.lock.json       │
        ▲                         │ .agent-pkg/build/         │
        │ publish                 │ agent/generated/          │
        │                         └──────────────────────────┘
┌───────┴───────────┐
│ Any local project │
│ or standalone dir │
└───────────────────┘

Install

npm install -D agent-package-manager

Commands

| Command | Description | |---------|-------------| | agent-pkg init | Initialize project configuration | | agent-pkg add <pkg>@<ver> | Add a package from a registry | | agent-pkg sync | Restore agent_modules/ from lock file | | agent-pkg update [pkg] | Update packages to newer versions | | agent-pkg diff <pkg> | Show semantic diff between versions | | agent-pkg check | Run full CI verification pipeline | | agent-pkg publish <path> | Publish a package to a registry |

Quick Start

Consuming packages

# Initialize project
agent-pkg init --registry github:myorg/agent-pkg-registry

# Add a package
agent-pkg add [email protected]

# Customize with project overrides
mkdir -p agent_overrides
# Edit agent_overrides/backend-api.yaml

# CI check
agent-pkg check

Publishing packages

# Publish a local package directory to a registry
agent-pkg publish ./agent-kit-lite \
  --registry github:myorg/agent-pkg-registry \
  --version 1.0.0

# Publish from a project that already has a default registry configured
agent-pkg publish ../aidev-skeleton/agent-kit

# Dry run to preview
agent-pkg publish ./my-pkg --registry github:myorg/registry --dry-run

Package Manifest

Each package must contain an agent-pkg.package.json with a strict schema (no additional properties allowed):

{
  "schemaVersion": 1,
  "id": "my-package",
  "version": "1.0.0",
  "description": "Optional description",
  "entrypoint": "agent-contracts.yaml",
  "dependencies": {
    "guardrails-base": ">=0.1.0"
  }
}

| Field | Required | Description | |-------|----------|-------------| | schemaVersion | yes | Must be 1 | | id | yes | Package identifier | | version | yes | Semver version | | description | no | Human-readable description | | entrypoint | yes | Root DSL file relative to the package | | dependencies | no | Map of package ID → semver range |

When agent-pkg add installs a package with dependencies, all required packages are automatically resolved and installed. Dependencies are added to the root agent-contracts.yaml extends list before the dependent package to ensure correct merge order. Circular dependencies are detected and rejected.

How It Works

1. Registry: A GitHub repository containing versioned DSL packages under packages/ and a manifest file (agent-pkg.registry.json) that indexes all packages and their versions with commit SHAs
2. Add/Sync: Packages are resolved via the registry manifest, then extracted from the exact commit using git archive into agent_modules/
3. Lock file: agent-pkg.lock.json pins exact commit SHAs and content hashes for reproducible installs
4. Overrides: Project-specific customizations go in agent_overrides/, never in agent_modules/
5. Materialize: Resolves DSL inheritance, applies overrides, validates, lints, and generates runtime artifacts
6. Publish: Copies a local package directory into the registry repo, commits, updates the manifest, and pushes — can be run from any project or standalone directory

Registry Manifest

The registry repository must contain an agent-pkg.registry.json at its root:

{
  "schemaVersion": 1,
  "packages": {
    "backend-api": {
      "path": "packages/backend-api",
      "description": "Backend API agent team",
      "versions": {
        "1.0.0": {
          "commit": "abc123...",
          "contentHash": "sha256:...",
          "publishedAt": "2026-05-01T00:00:00Z"
        }
      }
    }
  }
}

This manifest is the authoritative source for version resolution. The publish command updates it automatically.

Requirements

• Node.js >= 20
• Git (for registry access)
• gh CLI or SSH keys for GitHub authentication

Related

• agent-contracts — DSL toolkit
• agent-contracts-runtime — Runtime bridge

License

MIT