@a2f0/agent-tool 0.1.41 → 0.1.43

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@a2f0/agent-tool",
-  "version": "0.1.41",
+  "version": "0.1.43",
   "packageManager": "bun@1.4.4",
   "type": "module",
   "description": "Portable cross-agent review, PR workflows, and shared skills",

package/skills/open-issue/SKILL.md

@@ -0,0 +1,38 @@
+---
+name: open-issue
+description: Open a GitHub issue the user explicitly requested, assigned to the authenticated GitHub user, with a reviewable title and body.
+---
+
+# Open Issue
+
+Open an issue only when the user explicitly asks for one; finding a bug,
+recording evidence, or following another skill does not authorize it. Follow
+repository guidance for where issues belong, labels, and templates.
+
+Resolve the target repository with `agent-tool repo context` (its `repo`
+field) from the checkout, or the `owner/repo` the user named; never infer it
+from a folder name. Before creating, search open issues for a duplicate:
+
+```sh
+gh issue list --repo <owner/repo> --state open --search '<key words>' --json number,title,url
+```
+
+If one matches, report it instead of opening another, and assign it with
+`gh issue edit <number> --repo <owner/repo> --add-assignee @me` when the user
+wants it tracked.
+
+Write a specific title and a body that states the observed behavior, the
+expected behavior, and reproduction steps or evidence (commands, versions,
+links). Never include secret values. Use only labels that already exist
+(`gh label list --repo <owner/repo>`). Put the body in a temporary file, then
+create the issue assigned to the authenticated GitHub user:
+
+```sh
+gh issue create --repo <owner/repo> --title '<title>' --body-file /path/to/issue-body.md --assignee @me
+```
+
+Always pass `--assignee @me`; assign other people only when the user names
+them, in addition to `@me` unless the user says otherwise. Confirm the result
+with `gh issue view <url> --json url,assignees` and, if the assignee is missing,
+add it with `gh issue edit <url> --add-assignee @me`. Report the issue URL and
+its assignees, or the exact error if assignment failed.

package/src/release/commands.ts

@@ -6,12 +6,19 @@ import { assert, flag, json, oid, option, output, poll, repository, timeoutOptio
 
 function packageName(name: unknown): asserts name is string { assert(typeof name === "string" && /^(?:@[a-z0-9._-]+\/)?[a-z0-9][a-z0-9._-]*$/.test(name), "Invalid npm package name."); }
 export interface ReleaseRun { databaseId: number; status: string; conclusion: string; headSha: string; url: string }
-export async function verifyTarball(metadata: { name: string; version: string; dist: { tarball: string; integrity: string } }): Promise<{ tarball: string; integrity: string }> {
+/**
+ * Downloads and checks the published tarball. Resolves null only when the
+ * registry answers 404 or 410: npm can list a version minutes before its
+ * tarball is served, so absence is a propagation delay. Any other failure,
+ * including a tarball that downloads but does not match, throws.
+ */
+export async function verifyTarball(metadata: { name: string; version: string; dist: { tarball: string; integrity: string } }): Promise<{ tarball: string; integrity: string } | null> {
   const url = new URL(metadata.dist.tarball);
   assert(url.protocol === "https:" && url.hostname === "registry.npmjs.org", "Expected an HTTPS npm registry tarball.");
   const integrity = /^sha512-([A-Za-z0-9+/]+={0,2})$/.exec(metadata.dist.integrity);
   assert(integrity, "Package must have SHA-512 tarball integrity.");
   const response = await fetch(url, { signal: AbortSignal.timeout(60_000), redirect: "error" });
+  if (response.status === 404 || response.status === 410) { await response.body?.cancel(); return null; }
   assert(response.ok && response.body, "Could not download the published tarball.");
   const chunks: Uint8Array[] = []; let size = 0;
   for await (const chunk of response.body) { size += chunk.length; assert(size <= 100 * 1024 * 1024, "Tarball exceeds the 100 MiB verification limit."); chunks.push(chunk); }
@@ -39,6 +46,7 @@ export async function inspectRelease(
   assert(metadata.name === expected.name && metadata.version === expected.version, "Registry returned a different package version.");
   assert(!metadata.gitHead || metadata.gitHead === expected.commit, "Registry gitHead differs from the publishing merge commit.");
   const artifact = await checkArtifact(metadata);
+  if (!artifact) return { done: false, value: { ok: false, reason: "Tarball has not propagated to npm.", run } };
   return { done: true, value: { ok: true, reason: "Workflow and published tarball verified.", run, ...artifact, gitHead: metadata.gitHead ?? null } };
 }
 

package/src/skills/bundled.ts

@@ -1,6 +1,7 @@
 // Generated by scripts/build/bundle-skills.ts; edit skills/*/SKILL.md.
 export const BUNDLED_SKILLS: Readonly<Record<string, string>> = {
   "cross-agent-review": "---\nname: cross-agent-review\ndescription: Review committed branch changes with an independent Claude Code, Codex, or OpenCode reviewer, and repair actionable findings when requested.\n---\n\n# Cross-Agent Review\n\nUse the installed `agent-tool` executable. Read the repository's development and\nreview policy and `agent-tool.json` when present. Keep project validation commands\nand release rules in the repository; do not assume Bun, a workspace layout, or\nparticular CI job names.\n\nSelect an independent reviewer using a different model/provider from the author\nwhen possible, not merely a different CLI: Hermes and OpenCode can use the same\nmodel as another harness. Hermes can coordinate this skill but is not a `review`\nadapter. Honor a requested reviewer or effort; otherwise use an available\nindependent reviewer.\nRun `agent-tool doctor` if CLI compatibility is uncertain.\n\nRun noisy validation or repair checks through\n`agent-tool run --label <check> -- <command> [args...]`. Read its bounded failure\ntail and use `agent-tool logs <log>` or a targeted search for more evidence.\nKeep `agent-tool review` direct: it retains reviewer stderr in a private local\nlog and displays the complete final review. Never hide, truncate, or substitute\na command success receipt for findings and the final verdict.\n\nReview committed changes with `agent-tool review claude`, `agent-tool review codex`,\nor `agent-tool review opencode`. Optional effort is `low`, `medium`, `high`,\n`xhigh`, or `max`. For a local or non-GitHub repository, add `--base <commit-or-ref>`.\nFor a coordinated GitHub review, pin the fetched base using\n`AGENT_TOOL_REVIEW_BASE_REF`, the base branch name such as `main` (not a\nremote-tracking ref like `origin/main`), and `AGENT_TOOL_REVIEW_BASE_OID`, its\nfetched commit. Fetch from the repository that owns the PR, which can differ\nfrom the checkout's origin.\n\nUse `agent-tool repo context --fetch` to resolve and fetch the PR's own base,\nthen record the exact base and HEAD before reviewing. The tool reviews raw committed\nfiles and excludes worktree edits. A zero exit means a complete review was\nreturned; it does not mean the findings are non-blocking. Read the final\n`VERDICT: BLOCKER|MAJOR|MINOR|SUGGESTION|CLEAN` and the findings. A reviewer\nthat labels findings `[P0]` through `[P3]` uses the same scale: `[P0]` and\n`[P1]` are BLOCKER and MAJOR, `[P2]` and `[P3]` are MINOR and SUGGESTION.\n\nIf a CLI is unavailable, out of credits, or returns an unusable review, try another\navailable reviewer and disclose the fallback. Do not silently convert a failed\nreview into CLEAN or call an in-session review independent.\n\nFor report-only requests, report findings without changing files or history.\nWhen repairs are authorized, address actionable BLOCKER and MAJOR findings,\nvalidate with the repository's relevant checks, commit the repairs, and review\nthe new HEAD. Continue while meaningful progress is possible; report an impasse\nwhen progress requires a material user decision. A repaired commit is unreviewed\nuntil the next review completes. Preserve unrelated work.\n\nBefore reporting success, confirm HEAD still matches the reviewed commit and\nthat an existing PR points to that same commit. If the base moved, refresh it and\nreview again before shipping. Report reviewer, exact base and head IDs, verdict,\nremaining findings, validation, and any repairs performed. This skill does not\nauthorize pushing, opening a PR, or merging unless the user requested that work.\n",
+  "open-issue": "---\nname: open-issue\ndescription: Open a GitHub issue the user explicitly requested, assigned to the authenticated GitHub user, with a reviewable title and body.\n---\n\n# Open Issue\n\nOpen an issue only when the user explicitly asks for one; finding a bug,\nrecording evidence, or following another skill does not authorize it. Follow\nrepository guidance for where issues belong, labels, and templates.\n\nResolve the target repository with `agent-tool repo context` (its `repo`\nfield) from the checkout, or the `owner/repo` the user named; never infer it\nfrom a folder name. Before creating, search open issues for a duplicate:\n\n```sh\ngh issue list --repo <owner/repo> --state open --search '<key words>' --json number,title,url\n```\n\nIf one matches, report it instead of opening another, and assign it with\n`gh issue edit <number> --repo <owner/repo> --add-assignee @me` when the user\nwants it tracked.\n\nWrite a specific title and a body that states the observed behavior, the\nexpected behavior, and reproduction steps or evidence (commands, versions,\nlinks). Never include secret values. Use only labels that already exist\n(`gh label list --repo <owner/repo>`). Put the body in a temporary file, then\ncreate the issue assigned to the authenticated GitHub user:\n\n```sh\ngh issue create --repo <owner/repo> --title '<title>' --body-file /path/to/issue-body.md --assignee @me\n```\n\nAlways pass `--assignee @me`; assign other people only when the user names\nthem, in addition to `@me` unless the user says otherwise. Confirm the result\nwith `gh issue view <url> --json url,assignees` and, if the assignee is missing,\nadd it with `gh issue edit <url> --add-assignee @me`. Report the issue URL and\nits assignees, or the exact error if assignment failed.\n",
   "open-pr": "---\nname: open-pr\ndescription: Open a GitHub pull request for the current feature branch with a validated title and a reviewable description.\n---\n\n# Open PR\n\nUse the installed `agent-tool`. Follow repository policy for validation, commits,\nand branch naming. Resolve the repository and default branch with `agent-tool repo context`;\ndo not assume the branch is named main. Preserve unrelated work and finish\nrequested changes and appropriate checks before publishing them.\n\nEnsure the intended commit is on a feature branch and use\n`agent-tool branch push <reviewed-head> --remote <remote>` through normal hooks.\nIt names the destination explicitly and verifies local/remote HEAD afterward;\na changed result needs another review. Respect existing push authorization.\nIf the user only requested a draft description, prepare it without publishing.\n\nWrite a title that satisfies the data-only `agent-tool.json` subject policy.\nDescribe the concrete resulting behavior and relevant validation. When the\nbranch changes package manifests, run\n`agent-tool dependencies diff --base <base-oid>` and name every `newPackages`\nentry in the body with its manifest and version, so a reviewer sees new\nthird-party code however it was added. Put multiline body text in a temporary\nfile, then run:\n\n```sh\nagent-tool pr open 'feat: describe the change' --body-file /path/to/pr-body.txt\n```\n\nOmitting the title uses the latest commit subject. The tool refuses duplicate\nopen PRs and requires the branch to be pushed at its local HEAD. It does not\npush for you. Resolve a fork's head/base identities explicitly if the repository\nuses fork PRs; the initial open helper supports same-repository branches.\n\nReport the created PR link and any remaining validation or review work. Run\n`agent-tool teardown` first, stop what the work started, and report what remains.\n",
   "reset": "---\nname: reset\ndescription: Return a clean checkout to its updated default branch after confirmed shipping or an explicit checkout cleanup request.\n---\n\n# Reset\n\nThis is checkout cleanup, not a destructive Git reset. Read repository guidance\nfor setup and hooks. Determine the default branch through the repository's\nremote metadata rather than assuming main.\n\nFor post-merge cleanup, preview with\n`agent-tool repo cleanup <PR-number> <shipped-head>`, then run it with `--apply`\nwithin the authorized cleanup scope. It requires a confirmed MERGED PR, refuses\nthe default and `branch.exempt` branches, preserves local edits, checks exact\nlocal/remote feature commits, verifies the merge is on the default branch, and\nfast-forwards that branch. By default it prunes the\nshipped local feature branch and deletes the matching remote branch if present.\nLocal pruning also applies after a squash merge or when GitHub already deleted\nthe remote branch; a missing remote is not evidence that local cleanup is done.\nPass `--keep-branch` when the user asked to preserve both feature refs.\nRead the receipt's completed steps if a later operation fails; do not claim full\ncleanup from a partial result. Verify the final branch and clean worktree, and\ncheck that `git branch --list <feature-branch>` is empty unless keeping the branch.\nIf the feature branch is checked out in another worktree, shared cleanup reports\na partial failure after updating the default branch and leaves both feature refs\nin place; preserve that worktree and report the remaining cleanup.\n\nRemote branch deletion uses GitHub REST after checking the live ref to avoid\npre-push hooks. The API has no atomic expected-OID delete guard; the check and\ndeletion retain a small concurrent-update window. Fork PRs require manual remote\nhandling and are refused by the shared cleanup command.\nUse a repository's stronger cleanup procedure when required, including atomic\nremote deletion or additional local verification; do not weaken it to use the\nshared command. The same local pruning and keep-branch outcomes still apply.\n\nFor an explicit checkout cleanup without a merged PR, preserve all feature refs:\ncheck worktree/index, resolve the default branch with `repo context`, fetch it,\nswitch, and update by fast-forward only. Never discard or automatically stash\nedits, force a diverged default branch, or infer shipping from Git ancestry after\na squash merge.\n\nRun `agent-tool teardown` and stop what the finished work left running\n(`teardown --apply` for recorded processes); report anything that remains.\nRun the repository's documented dependency/hook setup if required. When copied\nhooks are configured, use `agent-tool hooks check` and `hooks install --apply`;\ninspect unmanaged hooks before an explicit `--adopt`, which backs them up.\nDo not assume a package manager. Report final branch, commit, whether the shipped\nlocal branch was pruned or preserved, and unfinished cleanup or setup.\n",
   "ship-pr": "---\nname: ship-pr\ndescription: Complete an authorized commit, independent review, repair, PR, CI, and squash-merge workflow for a GitHub repository.\n---\n\n# Ship PR\n\nUse the installed `agent-tool`. Read repository guidance and policy first;\nvalidation, versioning, package management, and hook bodies remain project\nconcerns. Use shared branch, hook, check, cleanup, and release commands where\nconfigured; keep application-specific commands in repository guidance. Shipping authorizes this workflow within the user's stated scope.\nPreserve unrelated edits and honor requested stopping points such as open-PR\nonly, report-only review, or keeping the feature branch.\n\nUse `agent-tool run --label <check> -- <command> [args...]` for noisy setup,\nvalidation, builds, and hook-running Git commands. It preserves exit status and\ncomplete private logs, prints one success receipt, and shows a bounded failure\ntail. Inspect more with `agent-tool logs <log> --max-bytes 8192 --tail-lines 80`\nor a targeted search; never dump an entire suite log or pipe checks into `tail`.\nThe receipt proves process completion, not absence of warnings: inspect required\nwarning, coverage, timing, or artifact evidence before accepting a check. Keep\nmachine-readable receipts and review findings visible by running `versions\nprepare`, `review`, and other commands whose output drives a decision directly.\nPrefer documented compact test reporters when they preserve required evidence;\ndo not reduce test scope, skip checks, silence warnings, or mask failures.\nStart servers, watchers, and other long-running processes with\n`agent-tool proc start --label <name> -- <command>`, never a backgrounded shell\ncommand, so they can be found and stopped.\n\n1. Finish the requested change on a feature branch. Use\n   `agent-tool branch create <branch> --base <base-branch> --remote <remote>`\n   from a clean checkout; it fetches and pins the base, checks naming policy and\n   collisions, and creates without a local upstream. Use `branch check` with\n   explicit destination names in CI or hooks.\n   Validate it with appropriate project checks and commit only the intended\n   files.\n2. Use `agent-tool repo context --fetch` to resolve the PR's base repository\n   and branch, or the default branch when no PR exists, and fetch its exact base.\n   Record the returned base/head identities. Integrate the fetched base\n   using the repository's normal workflow, resolving conflicts without losing\n   user work. If project policy versions packages, prepare versions against the\n   pinned base after every integration or repair and before each review, using\n   the project's commands or `agent-tool versions prepare <base-oid>`, which\n   commits bumped manifests and the refreshed lockfile.\n   `agent-tool versions resolve-conflicts` resolves conflicts confined to\n   version fields. Review the resulting committed HEAD with an independent\n   reviewer using the bundled cross-agent-review skill. Repair blocking findings\n   and review every changed HEAD again. Review failure blocks shipping.\n3. Run `agent-tool branch push <reviewed-head> --remote <remote>` through\n   normal hooks; it verifies local and remote identity afterward. If a hook\n   changed content or HEAD, review that result.\n   Open the PR using the open-pr skill, or update the existing PR as needed.\n4. Allow configured review bots time to respond, then use\n   `agent-tool pr threads list` to fetch review threads and all comments. Follow repository policy for feedback: fix valid findings,\n   reply with `pr threads reply <comment-id>` (body file or stdin), and use\n   `pr threads resolve <thread-id>` only for fully addressed findings.\n   Validate, commit, push, and independently review every feedback or CI repair.\n   Wait with `agent-tool pr checks --wait --head <reviewed-head>`, whose limit\n   defaults to `agent-tool.json` `merge.checksTimeoutSeconds`; when a job\n   fails, read its log with `agent-tool pr logs --head <reviewed-head>`. When it\n   stops with `behind: true`, the base moved: cancel the stale head's CI with\n   `agent-tool pr cancel-runs --head <reviewed-head>`, integrate the reported\n   base, validate, review, push the new head, and wait on it. Then run\n   `agent-tool pr preflight <reviewed-head> <base-branch> <reviewed-base>` to\n   recheck CI, live base, PR identity, local state, and explicit version policy.\n   A changed base requires integration, validation, and another review. When\n   versions are managed, `agent-tool versions check <base-oid>` must pass for the\n   live base. Use the squash-merge skill to merge the exact reviewed HEAD.\n5. After confirmed MERGED, follow the reset skill: run\n   `agent-tool repo cleanup <PR-number> <reviewed-head> --apply` to return to the\n   updated default branch and prune the shipped feature branch, honoring\n   stronger repository cleanup rules. Never prune with raw `git branch -D` or\n   `git push --delete`: the cleanup command checks the merge and both refs\n   first, and harness command guards prompt for raw force deletes. If the user requested keep-branch, preserve\n   both feature refs. Check the cleanup receipt and verify the local feature ref\n   is absent unless preserved; report incomplete cleanup explicitly. Apply\n   documented dependency/hook setup.\n6. When the project publishes npm packages, use `agent-tool release verify\n   <package> <version> <merge-oid> --workflow <publish-workflow>` to verify the\n   exact workflow and tarball, allowing registry propagation time. When the\n   project deploys the merged branch, verify that deployment and documented\n   live checks. Report deployment failures\n   separately from a successful merge; follow project policy for repairs.\n\nBefore the final report, run `agent-tool teardown` in each repository this work\ntouched. Stop what the work started (`teardown --apply`, `proc stop`), stop any\nuntracked process it started, and remove worktrees it added. Report what\nremains and why; the work is not done while teardown fails for anything it\nstarted.\n\nNever infer a clean review from process success alone or carry a review across\ncontent changes. Do not weaken configured CI policy to get a merge through.\nIf a step fails, preserve useful intermediate work and report the concrete\nremaining issue. Report PR link, merged commit, review verdict, validation, final\ncheckout state, the teardown result, and whether the shipped local branch was\npruned or preserved.\n",