For AI agents: the complete documentation index is available at https://scriptedalchemy.github.io/agent-bundle/llms.txt, the full documentation bundle is available at https://scriptedalchemy.github.io/agent-bundle/llms-full.txt, and this page is available as Markdown at https://scriptedalchemy.github.io/agent-bundle/guide/distribution/validation.md.
agent-bundle
  • English

      • Artifact validation

      Validation answers two different questions with one command. Against source it asks whether the project describes a legal bundle; against an artifact it asks whether the emitted bytes are the bytes the manifest promised.

      npx agent-bundle validate --root .                        # project source
npx agent-bundle validate --artifact artifact --strict    # built bytes, no sources needed

      validate --artifact, mcp, and hooks all work against a built artifact with the project sources deleted. That is deliberate: an artifact that only validates while its source tree is present is not really self-contained, and the packed-deleted-source proof level in Testing exists for the same reason.

      Content-addressed, not path-existence

      agent-bundle.manifest.json records a SHA-256 digest for every emitted file, including copied scripts and assets. Artifact validation compares real bytes against those digests, so a hand-edited generated file fails rather than passing because the path still exists. Referenced files are checked too — a manifest-declared logo that is missing from the artifact or escapes the deploy tree reports AB6025.

      Every diagnostic is one structured record: a stable AB code, a severity, a message, and usually a sourcePath and a recovery hint. The diagnostic-gated commands — build, prepack, validate, doctor, install, and dev — exit nonzero only when an error diagnostic is present; warnings and infos never gate a build, a validation, or a dev rebuild. eval and inspect also exit 1 for a failing or inconclusive trial or an invalid model, with no error diagnostic involved — see the CLI exit codes.

      Claude Code strict validation

      When Claude Code is on PATH, artifact validation runs claude plugin validate <bundle-dir> --strict for emitted claude and unified plugin targets:

      • Host errors become Agent Bundle errors.
      • Host warnings stay warnings unless agent-bundle validate --strict is set.
      • A missing binary is reported as an explicit informational skip, never as fabricated success.

      CI should use strict validation:

      npx agent-bundle validate --artifact artifact --strict

      Use --no-host-validation when a deterministic schema-only check is required — a machine without the hosts installed must still be able to run the same gate and get the same schema verdict.

      During development you can load a built target without installing it and verify registration:

      claude --plugin-dir artifact/claude plugin list --json

      Codex and Cursor: pinned schemas

      Neither Codex nor Cursor publishes a plugin-validation developer verb today, so Agent Bundle validates their emitted JSON documents against its own vendored pinned schemas and treats host schema generators as a drift signal, never as a substitute plugin contract.

      CodeSeverityMeaning
      AB6026infoEvery Cursor report states that Cursor publishes no plugin-validate verb, and names the vendored schema pin used locally.
      AB6027errorA required generated Cursor document is missing, or a present plugin, marketplace, MCP, or hooks document is unreadable, invalid JSON, or rejected by its pinned schema.
      AB6028errorGenerated bytes violate pinned Cursor loader evidence: manifest-candidate precedence selects a fallback manifest, a symlink resolves outside the bundle, or CURSOR_PLUGIN_ROOT appears outside loader-substituted fields.
      AB6029info / warningThe Cursor Agent version probe is unavailable (ENOENT, info) or could not complete (warning). Local pinned-schema validation still runs.
      AB6030infoThe Codex CLI is unavailable, or the installed release publishes no plugin validation command.
      AB6031info / warning (error under --strict)The Codex app-server schema-generation verb is unavailable, or its live output is missing or differs from the pinned generated hook schemas.
      AB6032errorA required Codex bundle document is missing, unreadable, invalid JSON, or fails its vendored pinned schema.
      AB6033errorA bounded Codex version or schema-generation command could not start, failed, timed out, exceeded 1 MiB of output, or produced unreadable output.

      AB6031 is the interesting one: when Codex's generated schema disagrees with the pinned revision, the pin is only updated once Codex publishes the matching contract. Following live host output automatically would turn an upstream change into a silent contract change here.

      Agent Skills spec lint

      AB6034 is an error on emitted bytes: a SKILL.md with valid YAML frontmatter but no Markdown instruction body after it. The pinned Agent Skills specification requires frontmatter followed by Markdown content, and the check runs against what the artifact actually contains rather than against the authored source.

      Hash pins versus repository-owned tables

      Hash pins cover vendored external content whose ground truth lives outside the repository and can drift: host document schemas under src/adapters/schemas/* (with upstream URL, commit, and SHA-256 recorded in PROVENANCE.json), the Agent Skills specification-derived schema pin in the manifest agentSkills block, and emitted artifact files and source inputs for integrity.

      Repository-owned capability tables and evidence are not hashed. Capability evidence records the observed host version (observedVersion) and target, while adapters carry a monotonic adapterRevision. Git already versions repository-owned content; hashing it again inside the repository is self-referential and causes churn on every table edit.

      The npm prepack gate

      npx agent-bundle prepack --root . --output artifact --json

      prepack runs the release build and npm pack --dry-run --json --ignore-scripts, then gates the exact package and artifact inventory, manifest hashes, package bin targets, and release-version agreement. --output is an artifact path relative to --root that overrides the configured output.distPath, defaulting to artifact. Use it as an npm prepack script; --ignore-scripts prevents recursion, and no npm lifecycle ever performs a host install.

      CodeMeaning
      AB7010The dry-run npm inventory omits a package output, artifact manifest or file, install surface, or README. Include dist and the artifact directory in the package files allowlist.
      AB7011An on-disk artifact file no longer matches its manifest SHA-256. Rebuild, and do not modify generated host packs.
      AB7012A package.json bin points outside the packed dist output (including src/) or names a file npm omitted. Point it at the generated dist/bin file.
      AB7013package.json, normalized plugin metadata, a host manifest, or artifact provenance reports a different release version. Make every release identity agree.

      A release build also refuses a project with no release version at all (AB4013), so a published artifact never carries the 0.0.0-dev.<short-revision> development fallback. A declared plugin.version that disagrees with package.json reports the AB4008 warning.

      Next