Merge pull request #6 from Clawdi-AI/feat/agent-plugin-source-recipes

feat(v2): package pinned upstream Agent Plugins

Author: kingsleydon

.github/workflows/publish-agent-plugins.yml

@@ -0,0 +1,59 @@
+name: Publish Agent Plugin Artifacts
+
+on:
+  push:
+    branches: [main]
+    paths:
+      - "v2/source-packages/**"
+      - "v2/scripts/source_package.py"
+      - "v2/scripts/plugin_package.py"
+      - "v2/scripts/plugin_validation.py"
+      - "v2/scripts/skill_validation.py"
+      - "v2/schemas/**"
+  workflow_dispatch:
+
+permissions:
+  contents: write
+
+concurrency:
+  group: agent-plugin-artifacts
+  cancel-in-progress: false
+
+jobs:
+  publish:
+    if: github.ref == 'refs/heads/main'
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - name: Install validation dependencies
+        run: python -m pip install --disable-pip-version-check -r v2/requirements.txt
+      - name: Build and verify artifacts
+        run: python v2/scripts/source_package.py --check --artifacts "$RUNNER_TEMP/artifacts"
+      - name: Publish immutable release assets
+        env:
+          GH_TOKEN: ${{ github.token }}
+        run: |
+          set -euo pipefail
+          for release in v2/source-packages/*/release.json; do
+            url=$(jq -r '.source.url' "$release")
+            expected=$(jq -r '.source.archiveDigest | sub("^sha256:"; "")' "$release")
+            tag=$(python -c 'import sys, urllib.parse; print(urllib.parse.unquote(sys.argv[1].split("/releases/download/", 1)[1].split("/", 1)[0]))' "$url")
+            asset=$(python -c 'import sys, urllib.parse; print(urllib.parse.unquote(sys.argv[1].rsplit("/", 1)[1]))' "$url")
+            artifact="$RUNNER_TEMP/artifacts/$asset"
+            actual=$(sha256sum "$artifact" | cut -d ' ' -f 1)
+            test "$actual" = "$expected"
+
+            existing="$RUNNER_TEMP/existing-$asset"
+            if gh release download "$tag" --pattern "$asset" --output "$existing" 2>/dev/null; then
+              test "$(sha256sum "$existing" | cut -d ' ' -f 1)" = "$expected"
+              continue
+            fi
+            if gh release view "$tag" >/dev/null 2>&1; then
+              gh release upload "$tag" "$artifact"
+            else
+              gh release create "$tag" "$artifact" --title "$tag" --notes "Generated from pinned upstream sources at $GITHUB_SHA."
+            fi
+          done

.github/workflows/validate.yml

@@ -20,6 +20,8 @@ jobs:
         run: python -m pip install --disable-pip-version-check -r v2/requirements.txt
       - name: Test Agent v2 Store validation
         run: python -m unittest discover -s v2/tests -v
+      - name: Rebuild pinned Agent Plugin sources
+        run: python v2/scripts/source_package.py --check
       - name: Validate Agent v2 Store
         run: python v2/scripts/validate.py
       - name: Enforce published Agent v2 package immutability

v2/CONTRIBUTING.md

@@ -1,6 +1,9 @@
 # Contributing to the Agent v2 Store
 
-Keep authored package data inside one `v2/plugins/<plugin-key>/` package. Use
+Keep authored package data inside one `v2/plugins/<plugin-key>/` package. For
+approved upstream Skills, use a closed recipe under `v2/source-packages/` and
+pin full 40-hex GitHub commits; do not use branches, tags, submodules, symlinks,
+or runtime downloads. Use
 top-level `plugin.json.keywords` for search and discovery; do not duplicate it
 with extension tags. Never edit `v2/catalog.json` by hand: regenerate its
 normalized projection after package changes. Include licenses and attribution
@@ -10,13 +13,14 @@ Before opening a pull request, run:
 
 ```bash
 python3 -m pip install -r v2/requirements.txt
+python3 v2/scripts/source_package.py --check
 python3 v2/scripts/catalog.py --write
 python3 v2/scripts/validate.py
 python3 -m unittest discover -s v2/tests -v
 ```
 
-Review the reported `sha256-tree-v1` digest when package contents or executable
-modes change. Once a `name` and `version` appear in the baseline catalog, their
-digest is immutable; bump `plugin.json.version` before publishing changed
-bytes. Validation does not replace dependency, license, or runtime security
-review.
+Review both reported digests when source mappings, package contents, or
+executable modes change. Once a `name` and `version` appear in the baseline
+catalog, their source and digest are immutable; bump `plugin.json.version` and
+the release tag/asset before publishing changed bytes. Validation does not
+replace license, provenance, dependency, or runtime security review.

v2/README.md

@@ -94,6 +94,23 @@ non-secret. For protected remote MCP servers, standard MCP Authorization is
 performed by the MCP client and managed by its host/runtime, not declared as
 Store package authentication metadata.
 
+## Source-built packages
+
+Third-party Skills may be packaged from immutable upstream GitHub commits
+without checking their files into this branch. A closed recipe under
+`v2/source-packages/<name>/` maps selected upstream directories into a standard,
+self-contained Agent Plugin. CI downloads the pinned commit, rejects unsafe
+archive entries, validates the complete package, and reproduces a deterministic
+`.tar.gz` artifact. `release.json` binds its GitHub Release URL, archive SHA-256,
+package `sha256-tree-v1` digest, and catalog projection.
+
+Published release assets are immutable. The publish workflow creates a missing
+asset, treats an existing byte-identical asset as a no-op, and fails rather than
+overwriting different bytes. Runtime clients verify both digests before native
+installation. Upstream source files exist in the release artifact because Agent
+Plugins 1.0.0 packages must be self-contained; they are not retained in Store
+main or a developer checkout.
+
 ## Generated Store index
 
 `v2/catalog.json` is a Clawdi Store index, not an Agent Plugins standard field.
@@ -103,28 +120,26 @@ It is generated only from packages that pass the validation above:
 python3 v2/scripts/catalog.py --write
 ```
 
-The closed `schemaVersion: 1` entry is a normalized listing and resolution
+The closed `schemaVersion: 2` entry is a normalized listing and resolution
 projection. It contains package `name` and `version`; `displayName`, optional
 `description` and `publisher`, `category`, standard `keywords`, and `languages`;
-declared `runtimes`; `path` and optional `icon`; the `sha256-tree-v1` `digest`;
-`hasConfiguration`; and a closed `components` summary. `components.skills`
+declared `runtimes`; a closed `source` and optional in-Store `icon`; the
+`sha256-tree-v1` `digest`; and a closed `components` summary. `components.skills`
 contains exact Skill names, while `components.mcpServers` maps exact server
 names to declared `stdio`, `streamable-http`, or `sse` transports. It contains
 no Skill bodies or descriptions and no MCP URLs, headers, commands, or
 configuration data. Catalog-facing human strings and array items cannot
 contain ASCII control characters or DEL.
 
-`hasConfiguration` is retained for catalog schema compatibility and is always
-`false`. Packages cannot declare `extensions["ai.clawdi"].configuration`.
+Packages cannot declare `extensions["ai.clawdi"].configuration`.
 
-The index contains no Git commit. `path` is resolved relative to the directory
-containing `v2/catalog.json`, so `./plugins/example-plugin` selects
-`v2/plugins/example-plugin` in the same snapshot. A consumer resolves an
-external Store commit, verifies `digest`, and binds the install to that commit
-plus digest. The index exposes one current published version per plugin; it is
-not a multi-version registry. Existing installs remain pinned to their original
-commit and digest after a newer version replaces or removes the listing; the
-package bytes remain fetchable from that historical commit.
+For authored packages, `source.type: "store"` contains a path relative to the
+directory containing `v2/catalog.json`; consumers bind it to the resolved Store
+commit. For source-built packages, `source.type: "github-release"` contains a
+canonical asset URL and archive SHA-256. Consumers persist the complete source
+object and the tree digest. The index exposes one current published version per
+plugin; it is not a multi-version registry. Existing installs remain pinned to
+their original source and digests after a listing changes or is removed.
 
 CI rejects generated-file drift. Its separate baseline check also rejects a
 version regression or a changed digest for a `name` and `version` already
@@ -138,13 +153,15 @@ Run from the repository root:
 
 ```bash
 python3 -m pip install -r v2/requirements.txt
+python3 v2/scripts/source_package.py --check
 python3 v2/scripts/catalog.py --write
 python3 v2/scripts/validate.py
 python3 -m unittest discover -s v2/tests -v
 ```
 
-Validation is offline and scans only `v2/plugins`, then compares the checked-in
-catalog with the deterministic generated bytes. The canonical upstream
+Local-package validation is offline. Source-package reproduction downloads only
+the immutable GitHub commits declared by recipes, then compares generated locks
+and catalog bytes. The canonical upstream
 schemas are vendored under `v2/schemas/` for source review and audit. The
 validator performs explicit validation of the supported 1.0.0 contract; it is
 not a general JSON Schema evaluator.

v2/SECURITY.md

@@ -11,3 +11,10 @@ Review bundled executables and dependencies before publishing. Plugin packages
 cannot declare installers, install hooks, OAuth registration, trust state, or
 other privileged author-controlled behavior. Follow the repository root
 `SECURITY.md` for private vulnerability reporting and incident response.
+
+Source-package recipes must pin full GitHub commit IDs. Generated archives
+reject links, special files, path escapes, collisions, and unbounded input, and
+release assets are never overwritten. Review upstream licenses and source
+changes before updating a pin. A package's remote MCP URL is public package
+configuration; OAuth tokens remain client-managed and are not baked into the
+artifact or Store catalog.

v2/catalog.json

@@ -1,4 +1,97 @@
 {
-  "plugins": [],
-  "schemaVersion": 1
+  "plugins": [
+    {
+      "category": "developer-tools",
+      "components": {
+        "mcpServers": {},
+        "skills": [
+          "cetus-aggregator",
+          "cetus-clmm",
+          "cetus-dlmm"
+        ]
+      },
+      "description": "Cetus Protocol development guidance for swaps, CLMM, and DLMM on Sui.",
+      "digest": "sha256-tree-v1:015fd5cb641dae43479e500e65f0582831f81051ccc7c26579137e38ee8ec721",
+      "displayName": "Cetus Protocol",
+      "keywords": [
+        "cetus",
+        "sui",
+        "defi",
+        "liquidity",
+        "swaps"
+      ],
+      "languages": [
+        "en"
+      ],
+      "name": "cetus",
+      "publisher": "Cetus Protocol",
+      "runtimes": [
+        "openclaw",
+        "hermes"
+      ],
+      "source": {
+        "archiveDigest": "sha256:10974bca87f9045c9fc68a6af4b2fff16304d806b6cb4754fe75c54d1b105b72",
+        "type": "github-release",
+        "url": "https://github.com/Clawdi-AI/store/releases/download/agent-plugin-cetus-v0.1.0/cetus-0.1.0.tar.gz"
+      },
+      "version": "0.1.0"
+    },
+    {
+      "category": "developer-tools",
+      "components": {
+        "mcpServers": {
+          "sui-docs": "streamable-http"
+        },
+        "skills": [
+          "accessing-data",
+          "composable-move-functions",
+          "frontend-apps",
+          "generate-sui-agent-config",
+          "modern-move-syntax",
+          "move-unit-testing",
+          "naming-conventions",
+          "ptbs",
+          "sui-build",
+          "sui-cli",
+          "sui-client",
+          "sui-install",
+          "sui-move",
+          "sui-move-project",
+          "sui-object-model",
+          "sui-overview",
+          "sui-publish",
+          "sui-sdks",
+          "walrus-sites",
+          "walrus-sites-portal",
+          "walrus-sites-publishing"
+        ]
+      },
+      "description": "Official Sui development guidance and documentation access for coding agents.",
+      "digest": "sha256-tree-v1:c4dda94ccbb861177ce8029221824b1e67dc71a5af33d9d9e14f84561257f269",
+      "displayName": "Sui Development",
+      "keywords": [
+        "sui",
+        "move",
+        "blockchain",
+        "smart-contracts",
+        "sdk"
+      ],
+      "languages": [
+        "en"
+      ],
+      "name": "sui",
+      "publisher": "Mysten Labs",
+      "runtimes": [
+        "openclaw",
+        "hermes"
+      ],
+      "source": {
+        "archiveDigest": "sha256:a9364b27efea274693e0ef7f7a5b56974f020c261876aade22f64df6e8975f24",
+        "type": "github-release",
+        "url": "https://github.com/Clawdi-AI/store/releases/download/agent-plugin-sui-v0.1.0/sui-0.1.0.tar.gz"
+      },
+      "version": "0.1.0"
+    }
+  ],
+  "schemaVersion": 2
 }