agentwheel 0.21.2 → 0.21.3

package/README.md

@@ -98,6 +98,7 @@ Fragments are Agentwheel composition inputs, not runtime file-drop targets.
 |---|---|
 | `agentwheel search <query>` | Search configured registries and the public enriched/Vercel catalogue; supports stable JSON output for agent reranking. |
 | `agentwheel add <source>` | Validate and save a package entry in `.agentwheel/config.json`; does not touch runtimes. |
+| `agentwheel pin <alias> <commit>` | Change an existing pinned alias's exact commit, preserving its configuration; does not resolve sources or touch runtimes. |
 | `agentwheel plan [name-or-source]` | Preview what `install` would reconcile without writing; supports `--profile <name>` and `--json`. |
 | `agentwheel install` | Reconcile configured packages into the current target or selected fleet. Uses the graph lock as input by default. |
 | `agentwheel install <name-or-source>` | Ensure semantics: configured name/source scopes the install; a new source is added and installed. |
@@ -583,6 +584,44 @@ agentwheel plan
 agentwheel install
 ```
 
+Use `add --runtimes codex` to restrict a saved package to matching runtime adapters. The option
+accepts comma-separated names and can be repeated. When replacing an existing package alias,
+pass its runtime restrictions and selection again; `add` replaces the saved entry.
+
+To change only an existing pinned alias's revision, use its exact configured name and a full
+40-hex commit SHA:
+
+```bash
+agentwheel pin shared-pack 0123456789abcdef0123456789abcdef01234567 --fleet delivery --reason "Pin the reviewed source revision"
+```
+
+`pin` preserves the source URL, driver, adapter, runtime restrictions, installation type (including
+its absence), package order and other fields. It accepts the normal workspace selectors
+`--fleet`, `--local`, `--user`, or `--target-root`, and uses the same mutation policy, durable
+receipts and revision provider as other source mutations. Missing or duplicate aliases, tracking
+packages and abbreviated or symbolic revisions are refused. No sources are fetched or rendered;
+use the normal plan/dry-run before installing the new revision.
+
+Omitting `--select` preserves the complete existing selection. Supplying repeatable or
+comma-separated `--select type/name` replaces the complete selection, including any legacy
+`skills` or imported `selection` field. An explicit empty selection is refused.
+
+For one source mutation with several aliases, use `pin --pins-file reviewed-pins.json --fleet
+delivery --reason "Pin the reviewed source set"`. The JSON file is a nonempty array of objects
+containing only `alias`, `commit` and optional `select`:
+
+```json
+[
+  { "alias": "shared-pack", "commit": "0123456789abcdef0123456789abcdef01234567" },
+  { "alias": "companion-pack", "commit": "abcdef0123456789abcdef0123456789abcdef01", "select": ["skills/companion"] }
+]
+```
+
+The batch cannot be combined with positional pins or `--select`. Every entry is validated before
+the config write; duplicate aliases and extra fields are refused. An omitted `select` preserves
+that package's selection; an explicit list replaces only that package's complete selection. The
+batch shares one durable receipt and revision-provider transaction.
+
 Package authors can mark artifacts as required. Required artifacts are always installed and cannot
 be deselected:
 

package/dist/index.js

@@ -2805,6 +2805,62 @@ var init_semver = __esm({
   }
 });
 
+// src/model/selection.ts
+function artifactSelectorKey(artifact) {
+  return `${artifact.type}/${artifact.name}`;
+}
+function artifactSelectorAliases(artifact) {
+  const primary = artifactSelectorKey(artifact);
+  if (artifact.type !== "subagents") return [primary];
+  const baseName = subagentBaseName(artifact.name);
+  if (baseName === artifact.name) return [primary];
+  return [primary, `subagents/${baseName}`];
+}
+function normalizeArtifactSelectors(select, legacySkills) {
+  const selected = [
+    ...select ?? [],
+    ...(legacySkills ?? []).map((name) => `skills/${name}`)
+  ].flatMap(splitSelectorList);
+  if (selected.length === 0) return void 0;
+  return [...new Set(selected.map(parseArtifactSelector))];
+}
+function filterArtifactsBySelection(artifacts, selectors, legacySkills, options = {}) {
+  const selected = normalizeArtifactSelectors(selectors, legacySkills);
+  if (!selected?.length) return artifacts;
+  const selectedSet = new Set(selected);
+  const available = new Set((options.validationArtifacts ?? artifacts).flatMap(artifactSelectorAliases));
+  const missing = selected.filter((selector) => !available.has(selector));
+  if (missing.length > 0) {
+    throw new Error(`Selected artifact not found in package: ${missing.join(", ")}`);
+  }
+  return artifacts.filter((artifact) => artifact.required || artifactSelectorAliases(artifact).some((selector) => selectedSet.has(selector)));
+}
+function splitSelectorList(value) {
+  return value.split(",").map((item) => item.trim()).filter(Boolean);
+}
+function parseArtifactSelector(value) {
+  const slash = value.indexOf("/");
+  if (slash <= 0 || slash === value.length - 1) {
+    throw new Error(`Invalid artifact selector: ${value}. Expected <type>/<name>.`);
+  }
+  const type = value.slice(0, slash);
+  const name = value.slice(slash + 1);
+  const parsedType = artifactTypeSchema.safeParse(type);
+  if (!parsedType.success) {
+    throw new Error(`Invalid artifact selector type: ${type}`);
+  }
+  return `${parsedType.data}/${name}`;
+}
+function subagentBaseName(name) {
+  return name.replace(/\.agent\.md$/i, "").replace(/\.toml$/i, "").replace(/\.md$/i, "");
+}
+var init_selection = __esm({
+  "src/model/selection.ts"() {
+    "use strict";
+    init_artifact();
+  }
+});
+
 // src/model/workspace.ts
 import { readFile as readFile10 } from "fs/promises";
 import { homedir as homedir4 } from "os";
@@ -2829,6 +2885,43 @@ async function writeWorkspaceConfig(workspaceRoot, config) {
   declareMutationPath(path);
   await writeJsonAtomic(path, workspaceConfigSchema.parse(config));
 }
+async function pinConfiguredPackages(workspaceRoot, input) {
+  const pins = z10.array(z10.object({
+    alias: z10.string().min(1),
+    commit: z10.string().regex(/^[a-f0-9]{40}$/i, "Pin requires an exact 40-hex commit SHA."),
+    select: z10.array(z10.string().min(1)).min(1).optional()
+  }).strict()).min(1).parse(input).map((pin) => {
+    const select = pin.select === void 0 ? void 0 : normalizeArtifactSelectors(pin.select);
+    if (pin.select !== void 0 && !select?.length) throw new Error("Explicit pin selection must not be empty.");
+    return { ...pin, select };
+  });
+  if (new Set(pins.map((pin) => pin.alias)).size !== pins.length) {
+    throw new Error("Pin requires unique configured aliases.");
+  }
+  const path = workspaceConfigPath(workspaceRoot);
+  const config = JSON.parse(await readFile10(path, "utf8"));
+  workspaceConfigSchema.parse(config);
+  const updates = pins.map(({ alias, commit, select }) => {
+    const matches = (config.packages ?? []).filter((pkg2) => pkg2.name === alias);
+    if (matches.length !== 1) {
+      throw new Error(matches.length === 0 ? `Configured package alias not found: ${alias}` : `Ambiguous configured package alias: ${alias}`);
+    }
+    const pkg = matches[0];
+    if (pkg.mode === "tracking") throw new Error(`Configured package ${alias} is tracking; pin requires pinned mode.`);
+    return { pkg, requestedRef: commit, select };
+  });
+  for (const { pkg, requestedRef, select } of updates) {
+    pkg.requestedRef = requestedRef;
+    if (select !== void 0) {
+      pkg.select = select;
+      delete pkg.skills;
+      delete pkg.selection;
+    }
+  }
+  workspaceConfigSchema.parse(config);
+  declareMutationPath(path);
+  await writeJsonAtomic(path, config);
+}
 function upsertPackage(config, entry) {
   const parsed = workspaceConfigSchema.parse(config);
   const packages = parsed.packages.filter((candidate) => candidate.name !== entry.name);
@@ -2920,6 +3013,7 @@ var init_workspace = __esm({
     init_mutation();
     init_declarations();
     init_adapters();
+    init_selection();
     artifactSelectorListSchema = z10.array(z10.string().min(1));
     CURRENT_WORKSPACE_SCHEMA_VERSION = 4;
     workspaceSelectionImportSchema = z10.object({
@@ -6874,7 +6968,7 @@ var init_identify = __esm({
 // src/cli/index.ts
 import { createHash as createHash28 } from "crypto";
 import { existsSync } from "fs";
-import { mkdir as mkdir27, mkdtemp as mkdtemp6, realpath as realpath4, rm as rm17, writeFile as writeFile24 } from "fs/promises";
+import { mkdir as mkdir27, mkdtemp as mkdtemp6, readFile as readFile45, realpath as realpath4, rm as rm17, writeFile as writeFile24 } from "fs/promises";
 import { homedir as homedir18, tmpdir as tmpdir7 } from "os";
 import { basename as basename24, dirname as dirname37, isAbsolute as isAbsolute14, join as join61, relative as relative19, resolve as resolve44 } from "path";
 import { fileURLToPath as fileURLToPath4 } from "url";
@@ -7505,59 +7599,7 @@ init_transport();
 
 // src/validation/adapter-targets.ts
 init_adapter();
-
-// src/model/selection.ts
-init_artifact();
-function artifactSelectorKey(artifact) {
-  return `${artifact.type}/${artifact.name}`;
-}
-function artifactSelectorAliases(artifact) {
-  const primary = artifactSelectorKey(artifact);
-  if (artifact.type !== "subagents") return [primary];
-  const baseName = subagentBaseName(artifact.name);
-  if (baseName === artifact.name) return [primary];
-  return [primary, `subagents/${baseName}`];
-}
-function normalizeArtifactSelectors(select, legacySkills) {
-  const selected = [
-    ...select ?? [],
-    ...(legacySkills ?? []).map((name) => `skills/${name}`)
-  ].flatMap(splitSelectorList);
-  if (selected.length === 0) return void 0;
-  return [...new Set(selected.map(parseArtifactSelector))];
-}
-function filterArtifactsBySelection(artifacts, selectors, legacySkills, options = {}) {
-  const selected = normalizeArtifactSelectors(selectors, legacySkills);
-  if (!selected?.length) return artifacts;
-  const selectedSet = new Set(selected);
-  const available = new Set((options.validationArtifacts ?? artifacts).flatMap(artifactSelectorAliases));
-  const missing = selected.filter((selector) => !available.has(selector));
-  if (missing.length > 0) {
-    throw new Error(`Selected artifact not found in package: ${missing.join(", ")}`);
-  }
-  return artifacts.filter((artifact) => artifact.required || artifactSelectorAliases(artifact).some((selector) => selectedSet.has(selector)));
-}
-function splitSelectorList(value) {
-  return value.split(",").map((item) => item.trim()).filter(Boolean);
-}
-function parseArtifactSelector(value) {
-  const slash = value.indexOf("/");
-  if (slash <= 0 || slash === value.length - 1) {
-    throw new Error(`Invalid artifact selector: ${value}. Expected <type>/<name>.`);
-  }
-  const type = value.slice(0, slash);
-  const name = value.slice(slash + 1);
-  const parsedType = artifactTypeSchema.safeParse(type);
-  if (!parsedType.success) {
-    throw new Error(`Invalid artifact selector type: ${type}`);
-  }
-  return `${parsedType.data}/${name}`;
-}
-function subagentBaseName(name) {
-  return name.replace(/\.agent\.md$/i, "").replace(/\.toml$/i, "").replace(/\.md$/i, "");
-}
-
-// src/validation/adapter-targets.ts
+init_selection();
 function filterArtifactsByAdapterTargets(artifacts, adapter, installationType, options = {}) {
   const skipped = [];
   const installable = artifacts.filter((artifact) => {
@@ -7600,10 +7642,11 @@ function skipWarning(selector, adapter, installationType, artifactType, support)
 
 // src/validation/artifacts.ts
 init_adapter();
+init_selection();
+init_fs();
 import { readFile as readFile24 } from "fs/promises";
 import { basename as basename7, join as join23 } from "path";
 import { parseDocument as parseDocument2 } from "yaml";
-init_fs();
 var behavioralRuleFormats = ["markdown-rule", "claude-markdown-rule", "copilot-instruction-rule"];
 var pluginFormats = ["claude-plugin", "codex-plugin", "hermes-plugin", "copilot-plugin", "openclaw-plugin", "openclaw-clawhub-plugin"];
 async function filterArtifactsByInstallFormat(artifacts, adapter, installationType, options = {}) {
@@ -12027,6 +12070,7 @@ function claudeAgentName(artifact) {
 }
 
 // src/staging/staging.ts
+init_selection();
 async function stageSource(driver, source, options = {}) {
   const raw = await stageSourceRaw(driver, source, options);
   return removeOnFailure(raw.root, () => renderStagedBundle(raw, options));
@@ -12232,13 +12276,15 @@ import { readdir as readdir12, readFile as readFile34, stat as stat14 } from "fs
 import { basename as basename20, extname as extname4, join as join41 } from "path";
 init_artifact();
 init_fs();
+init_selection();
 
 // src/model/workspace-composition.ts
 init_workspace();
+init_selection();
+init_fs();
 import { createHash as createHash16 } from "crypto";
 import { readFile as readFile32 } from "fs/promises";
 import { z as z12 } from "zod";
-init_fs();
 var selectionSourceConfigSchema = z12.object({
   schemaVersion: z12.literal(2),
   exports: workspaceExportsSchema
@@ -12397,6 +12443,7 @@ var registryCacheSchema = z13.object({
 });
 
 // src/registry/client.ts
+init_selection();
 init_workspace();
 init_fs();
 var DEFAULT_REGISTRY_SOURCE = "github:NestDevLab/agentwheel-registry";
@@ -13924,6 +13971,7 @@ function formatSelectionImport(root) {
 }
 
 // src/resolve/render.ts
+init_selection();
 import { createHash as createHash18 } from "crypto";
 import { readFile as readFile35, mkdtemp as mkdtemp5 } from "fs/promises";
 import { tmpdir as tmpdir6 } from "os";
@@ -14528,6 +14576,7 @@ function defaultTrustStorePath() {
 
 // src/lifecycle/source-plan.ts
 init_workspace();
+init_selection();
 
 // src/model/workspace-owner.ts
 import { Buffer as Buffer2 } from "buffer";
@@ -15998,6 +16047,7 @@ function runtimeScanRoot(request) {
 // src/lifecycle/profile.ts
 init_identify();
 init_transport();
+init_selection();
 init_declarations();
 async function syncProfile(options) {
   const config = await readMergedWorkspaceConfig(options.workspaceRoot);
@@ -16155,6 +16205,7 @@ function combinedSuggestionAliases(packageAliases, optionAliases) {
 }
 
 // src/registry/publish.ts
+init_selection();
 var DEFAULT_REGISTRY_SUBMISSION_URL = "https://github.com/NestDevLab/agentwheel-registry/issues/new";
 var registryEntryTypes = ["package", "skill", "plugin", "mcp", "adapter"];
 var explicitSourcePrefixes = ["github:", "git:", "skillkit:", "vercel:", "mcp-registry:", "clawhub:"];
@@ -16318,6 +16369,9 @@ function shellQuoteArg(value) {
   return `'${value.replaceAll("'", `'"'"'`)}'`;
 }
 
+// src/cli/index.ts
+init_selection();
+
 // src/cli/update-check.ts
 import { mkdir as mkdir26, readFile as readFile38, writeFile as writeFile22 } from "fs/promises";
 import { homedir as homedir14 } from "os";
@@ -16818,6 +16872,7 @@ init_manifest2();
 init_apply();
 init_paths();
 init_transaction();
+init_selection();
 import { createHash as createHash20 } from "crypto";
 import { resolve as resolve37 } from "path";
 init_declarations();
@@ -19479,6 +19534,7 @@ function ensureTrailingSlash(value) {
 }
 
 // src/trial/skill.ts
+init_selection();
 import { createHash as createHash26 } from "crypto";
 import { readFile as readFile43, stat as stat16 } from "fs/promises";
 import { join as join59 } from "path";
@@ -21129,6 +21185,7 @@ var commandGovernance = {
   "fleet normalize": "governed-apply-or-recover",
   "cache prune": "governed-apply",
   add: "governed-always",
+  pin: "governed-always",
   list: "incidental-cache",
   search: "incidental-cache",
   try: "incidental-cache",
@@ -21185,6 +21242,7 @@ function requiresCleanMutationPreflight(path) {
     "init",
     "fleet register",
     "add",
+    "pin",
     "package migrate",
     "remember",
     "journal abort"
@@ -21264,13 +21322,22 @@ cacheCommand.command("prune").description("remove old Git source snapshots while
   for (const path of result.removedPaths) console.log(`${verb} ${path}`);
   console.log(`${options.apply ? "Pruned" : "Preview"}: ${result.removedPaths.length} snapshots; retained ${result.retainedPaths.length}.`);
 });
-program.command("add").description("add a package to .agentwheel/config.json without touching runtimes").argument("<source>", "package source").option("--driver <driver>", "source driver (local, git, skillkit, vercel-skills, mcp-registry, or clawhub)").option("--adapter <adapter>", "built-in adapter", "openclaw").option("-i, --installation-type <type>", "installation type (for example local or user)").option("--user", "use the user workspace", false).option("--local", "use the nearest local workspace", false).option("--fleet <id>", "use one registered named fleet").option("--adapter-config <path>", "adapter JSON/JSONC file").option("--adapter-module <path>", "local programmatic adapter module").option("--allow-adapter-code", "allow loading local adapter code", false).option("-t, --target-root <path>", "workspace root").option("--mode <mode>", "pinned or tracking", "pinned").option("--version <range>", "root package version policy (exact, ~, ^, or *)").option("--name <name>", "package alias").option("--select <type/name>", "select an artifact by type/name (repeatable or comma-separated)", collectSelectOption, []).option("--skill <name>", "select a skill by name (repeatable or comma-separated)", collectSkillOption, []).option("--with-suggestions", "include suggested companion artifacts for selected roots on future installs", false).option("--suggestion <alias>", "include one suggested companion alias on future installs (repeatable or comma-separated)", collectSuggestionOption, []).option("--override <source-or-package::type/name>", "allow this package to replace a colliding artifact (repeatable)", collectOverrideOption, []).action(async (source, options) => {
+program.command("add").description("add a package to .agentwheel/config.json without touching runtimes").argument("<source>", "package source").option("--driver <driver>", "source driver (local, git, skillkit, vercel-skills, mcp-registry, or clawhub)").option("--adapter <adapter>", "built-in adapter", "openclaw").option("--runtimes <adapters>", "restrict package runtimes (repeatable or comma-separated)", collectSelectOption, []).option("-i, --installation-type <type>", "installation type (for example local or user)").option("--user", "use the user workspace", false).option("--local", "use the nearest local workspace", false).option("--fleet <id>", "use one registered named fleet").option("--adapter-config <path>", "adapter JSON/JSONC file").option("--adapter-module <path>", "local programmatic adapter module").option("--allow-adapter-code", "allow loading local adapter code", false).option("-t, --target-root <path>", "workspace root").option("--mode <mode>", "pinned or tracking", "pinned").option("--version <range>", "root package version policy (exact, ~, ^, or *)").option("--name <name>", "package alias").option("--select <type/name>", "select an artifact by type/name (repeatable or comma-separated)", collectSelectOption, []).option("--skill <name>", "select a skill by name (repeatable or comma-separated)", collectSkillOption, []).option("--with-suggestions", "include suggested companion artifacts for selected roots on future installs", false).option("--suggestion <alias>", "include one suggested companion alias on future installs (repeatable or comma-separated)", collectSuggestionOption, []).option("--override <source-or-package::type/name>", "allow this package to replace a colliding artifact (repeatable)", collectOverrideOption, []).action(async (source, options) => {
   const normalizedOptions = normalizeRuntimeScopeOptions(options);
   const targetRoot = await workspaceRootFromOptions(normalizedOptions);
   const entry = await packageEntryFromSource(source, targetRoot, normalizedOptions);
   await writeWorkspaceConfig(targetRoot, upsertPackage(await readWorkspaceConfig(targetRoot), entry));
   console.log(`Added ${entry.name}. Preview: agentwheel plan - Apply: agentwheel install`);
 });
+program.command("pin").description("pin configured package aliases without resolving sources or touching runtimes").argument("[alias]", "exact configured package alias").argument("[commit]", "exact 40-hex commit SHA").option("--user", "use the user workspace", false).option("--local", "use the nearest local workspace", false).option("--fleet <id>", "use one registered named fleet").option("-t, --target-root <path>", "explicit workspace root").option("--pins-file <path>", "JSON array of {alias, commit, select?} pins in one mutation").option("--select <type/name>", "replace the complete selection (repeatable or comma-separated)", collectSelectOption).action(async (alias, commit, options) => {
+  const workspaceRoot = await workspaceRootFromOptions(normalizeRuntimeScopeOptions(options));
+  if (options.pinsFile ? alias !== void 0 || commit !== void 0 || options.select !== void 0 : !alias || !commit) {
+    throw new Error("Choose pin <alias> <commit> [--select ...] or pin --pins-file <path>, exclusively.");
+  }
+  const pins = options.pinsFile ? JSON.parse(await readFile45(resolve44(options.pinsFile), "utf8")) : [{ alias, commit, ...options.select === void 0 ? {} : { select: options.select } }];
+  await pinConfiguredPackages(workspaceRoot, pins);
+  console.log("Pinned configured package revisions. Preview: agentwheel plan - Apply: agentwheel install");
+});
 program.command("list").description("list artifacts exposed by a package source").argument("<source>", "package source").option("--driver <driver>", "source driver").option("--user", "use the user workspace", false).option("--local", "use the nearest local workspace", false).option("--fleet <id>", "use one registered named fleet").option("-t, --target-root <path>", "explicit workspace root").option("--select <type/name>", "select an artifact by type/name (repeatable or comma-separated)", collectSelectOption, []).option("--skill <name>", "select a skill by name (repeatable or comma-separated)", collectSkillOption, []).action(async (source, options) => {
   const targetRoot = await workspaceContextRootFromOptions(normalizeRuntimeScopeOptions(options));
   const resolvedInput = await resolvePackageSource(source, targetRoot);
@@ -22365,6 +22432,7 @@ async function packageEntryFromSource(source, targetRoot, options) {
       source: resolvedSource,
       driver: driverName,
       adapter: adapter.name,
+      runtimes: options.runtimes?.length ? options.runtimes : void 0,
       installationType,
       adapterConfig: options.adapterConfig,
       adapterModule: options.adapterModule,
@@ -24401,7 +24469,7 @@ function shellQuoteArg2(value) {
   if (/^[A-Za-z0-9_./:@=-]+$/.test(value)) return value;
   return `'${value.replaceAll("'", `'"'"'`)}'`;
 }
-function collectSelectOption(value, previous) {
+function collectSelectOption(value, previous = []) {
   return [...previous, ...splitSelectorList(value)];
 }
 function parsePositiveInteger(value) {
@@ -24808,7 +24876,7 @@ async function governedCommandContext(command, options) {
   const contextOnly = path === "cache prune";
   const workspaceRoot = contextOnly ? await workspaceContextRootFromOptions(normalized) : await workspaceRootFromOptions(normalized);
   const anticipatedPaths = [];
-  if (path === "add") anticipatedPaths.push(workspaceConfigPath(workspaceRoot));
+  if (path === "add" || path === "pin") anticipatedPaths.push(workspaceConfigPath(workspaceRoot));
   if (path === "remember" && options.runtime) {
     anticipatedPaths.push(join61(workspaceRoot, ".agentwheel", "overlays", options.runtime, "instructions.local.md"));
   }

package/openpack.json

@@ -1,7 +1,7 @@
 {
   "schemaVersion": 2,
   "name": "NestDevLab/agentwheel",
-  "version": "0.21.2",
+  "version": "0.21.3",
   "provides": [
     { "type": "skills", "path": "skills" }
   ]

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agentwheel",
-  "version": "0.21.2",
+  "version": "0.21.3",
   "description": "Weave skills, rules, and instructions across every AI agent.",
   "type": "module",
   "license": "MIT",

package/skills/agentwheel/SKILL.md

@@ -5,7 +5,7 @@ allowed-tools: [Bash]
 license: MIT
 metadata:
   author: NestDevLab
-  version: "0.21.2"
+  version: "0.21.3"
 ---
 
 # agentwheel

package/skills/agentwheel-discovery/SKILL.md

@@ -5,7 +5,7 @@ allowed-tools: [Bash]
 license: MIT
 metadata:
   author: NestDevLab
-  version: "0.21.2"
+  version: "0.21.3"
 ---
 
 # Agentwheel Discovery